QTMR Peripheral and Driver Overview

Peripheral feature and how this peripheral works

QTMR module is a timer system with 4 identical independent 16-bit counter channels. Each channel has two input nodes and its own output signal. One module has 4 input pins (input pin 0 ~ input pin 3), the input pin signals are shared by all channels' input nodes in this module.

Features

• Support two input nodes for each channel: primary input and secondary input.
  • Input source support select from multiple clock sources.
    • Primary input can select from "input pin 0~3", "channel output 0~3" and "IP bus clock prescaler".
    • Secondary input can select from "input pin 0~3".
    • External clock rate need lower than peripheral clock/2.
  • Secondary input source support capture feature.
    • The active edge of secondary input source can trigger capture the channel counter value into CAP register.
    • Support make channel reload counter value after capture event occurs.
  • Secondary input source support act as a fault signal.
    • When enabled, the channel output signal (OFLAG) is cleared when the secondary input is set.
  • Support invert the "input pin 0~3" clock sources of channel.
    • Invert feature only affects "input pin 0~3", and acts on the channel input node, not the input pin, so it only affect current channel and not share by other channel.
    • The primary and secondary input node can choose different "input pin 0~3" signals for one channel, the invert feature will act both primary input node and secondary input node at the same time.
  • Support add independent input filter for each "input pin 0~3" signal.
    • 4 input pins have 4 corresponding filter registers.
    • The input filter acts on the input pin directly, so the input filter config will affect all channels that select this input pin as source.
• Support different count behaviors for each channel.
  • Support different basic channel counting events base on primary input or/and secondary input.
    • Support count primary input active edge.
      • Active edge is raising edge when choose "channel output 0~3" or "IP bus clock prescaler" as primary input source.
      • Active edge is determined by whether the invert feature is enabled when choose "input pin 0~3" as primary input source. It is raising edge when disable invert, is falling edge when enable invert.
    • Support count primary input both edges.
    • Support count primary input source active edge when secondary input is at a active level
      • Active edge/level is raising edge and high level when choose "channel output 0~3" or "IP bus clock prescaler" as primary/secondary input source.
      • Active edge/level is determined by whether the invert feature is enabled when choose "input pin 0~3" as primary/secondary input source. It is raising edge and high level when disable invert, is falling edge and low level when enable invert.
    • Support quadrature count mode, uses primary and secondary input sources.
    • Support count primary input active edge while secondary input level decide count direction.
      • Active edge is raising edge when choose "channel output 0~3" or "IP bus clock prescaler" as primary input source.
      • Active edge is determined by whether the invert feature is enabled when choose "input pin 0~3" as primary input source. It is raising edge when disable invert, is fall when enable invert.
      • Secondary input level also affects by invert feature when choose "input pin 0~3" as secondary input source.
    • Support count primary input active edge while secondary input act as a trigger to start and stop/re-initialize the counter.
      • Active edge and trigger edge is raising edge when choose "channel output 0~3" or "IP bus clock prescaler" as primary/secondary input source.
      • Active edge and trigger edge is determined by whether the invert feature is enabled when choose "input pin 0~3" as primary/secondary input source. It is raising edge when disable invert, is falling edge when enable invert.
      • Counter will start on first secondary input trigger edge, and continue until a compare event occurs or another secondary input trigger edge is detected, then counter will stop/re-initialize.
        • Stop or re-initialize is determined by whether the re-initialize feature is enabled. When disable, the counter will stop and timer compare flag will be set, when enable, the counter will reload and continue counting.
        • Subsequent secondary input trigger edge will continue to restart and stop/re-initialize the counting until a compare event occurs.
    • Support count cascaded mode, primary input source must be set to another channel's output within the module. If a channel selecting its own output for input is illegal, the result is no counting.
  • Support count until roll over or until compare event.
    • Channel have two compare events, corresponding to the COMP1 and COMP2 registers.
  • Support count up or down.
    • Count direction can be selected independently by the CTRL[DIR] bit control.
    • When chose "secondary specifies direction" count mode, count direction decide by the secondary input level XOR with CTRL[DIR] bit. Secondary input level will affects by invert feature when choose "input pin 0~3" as secondary input source.
      • Disable invert feature (IPS = 0)
        • Count up when (CTRL[DIR] = 0 & secondary input = 0) or (CTRL[DIR] = 1 & secondary input = 1).
        • Count down when (CTRL[DIR] = 0 & secondary input = 1) or (CTRL[DIR] = 1 & secondary input = 0).
      • Enable invert feature (IPS = 1)
        • Count up when (CTRL[DIR] = 0 & secondary input = 1) or (CTRL[DIR] = 1 & secondary input = 0).
        • Count down when (CTRL[DIR] = 0 & secondary input = 0) or (CTRL[DIR] = 1 & secondary input = 1).
  • Support different count compare event mode.
    • Normal mode, count up trigger COMP1 compare event and count down trigger COMP2 compare event.
    • Alternative mode, count up will trigger COMP1 compare event and COMP2 compare event alternating, or count down, but COMP2 act first.
  • Support count once or repeatedly.
  • Support different counter re-initialized mode.
    • Normal mode, channel counter re-initialized only with the LOAD register.
    • Alternative mode, channel counter is re-initialized with LOAD register when counting up and a match COMP1 occurs, or channel counter is re-initialized with COMPLD2 register when counting down and a match COMP2 occurs.
  • Support different preload mode for COMPn register.
    • Never reload.
    • COMPn register can be loaded with the value in corresponding CMPLDn register when COMP1 compare event.
    • COMPn register can be loaded with the value in corresponding CMPLDn register when COMP2 compare event.
• Support different output behaviors for each channel.
  • Support operate output signal (OFLAG) base on different channel event.
    • Support Assert OFLAG while channel active.
    • Support Set/Clear/Toggle OFLAG on normal mode compare event.
    • Support Toggle OFLAG on compare event alternating mode.
    • Support Set OFLAG on compare event and clear on secondary input active edge.
    • Support Set OFLAG on compare event and clear on count roll over.
    • Support primary node source output while channel counter is active.
  • Support invert output signal.
  • Support forces a configurable value to output signal.
    • Force command can be software or compare event from a master channel.
  • Support drive the output signal to the external pin.
• Support cooperation with other channel.
  • Support enable master mode for each channel, and master channel can broadcast compare event to all channels within this module.
  • Support enable receiving compare event from master channel. The master compare event can re-initialize channel or/and force this channel OFLAG signal.
• Support hold feature to stores the counter's values of specific channels whenever any of the four channel within a module is read.
• Support performs certain actions in response to the chip entering debug mode.
  • Continue with normal operation during chip in debug mode.
  • Halt channel counter during chip in debug mode.
  • Force channel output to logic 0 during chip in debug mode.
  • Halt channel counter and force channel output to logic 0 during chip in debug mode.
• Supports Interrupts.
  • Compare event interrupt: Compare event interrupt, COMP1 compare event interrupt, COMP2 compare event interrupt.
  • Count overflow interrupt.
  • Input capture edge interrupt.
    • Secondary input source input capture rising or/and falling edge interrupt, the edge is determined by the capture mode, this interrupt can't work with input capture edge trigger DMA enable.
• Supports DMA.
  • Channel load CMPLD1 register into COMP1 will trigger DMA write request for CMPLD1
  • Channel load CMPLD2 register into COMP2 will trigger DMA write request for CMPLD2.
  • Secondary input source input edge flag setting will trigger DMA read request for CAPT register, can't work with input capture edge interrupt enable.

How this peripheral works

1. Select clock source for primary input and secondary input and config necessary input attributes.
2. Config count mode with length, direction, times, compare, load and perload attributes.
3. Config output signal work mode and cooperation mode.
4. Enable channel to start count, it can generate output signal (OFLAG) and interrupt/dma request.

How this driver are designed to make this peripheral works

The qtmr driver provides the structure qtmr_channel_config_t which contain several sub-structures and other member to cover all feature of one qtmr channel. The QTMR_Init() function takes the argument in type of qtmr_channel_config_t to complete the initialization of the channel. Since QTMR is very flexible and cannot give the commonly used configuration, these sub-structures are only used to facilitate the understanding of the module and will not provide function APIs to take them as parameters. Base on the sub-structures and other behaviors of QTMR module, the qtmr driver also be divided into several basic function groups.

• Initialization and deinitialization Interfaces. The APIs in this function group can be used to initialize or de-initialize the qtmr channel.
• Input signal control related Interfaces. The APIs in this function group can be used to configure channel input signal related option, such as primary/secondary input source, secondary input capture mode.
• Channel count related Interfaces. The APIs in this function group can be used to configure channel count control related option or read channel count status, such as count mode, count length, count preload mode, count mode.
• Channel output signal (OFLAG) related Interfaces. The APIs in this function group can be used to configure channel output signal related option, such as output mode, output polarity.
• Channel cooperation control related Interfaces. The APIs in this function group can be used to configure channel cooperation related option, such as master mode enable.
• DMA control Interfaces. The APIs in this function group can be used to enable/disable channel DMA features.
• Interrupt control Interfaces. The APIs in this function group can be used to enable/disable channel interrupts.
• QTMR channel Status Flag Interfaces. The APIs in this function group can be used to get or clear the status flag of the QTMR channel.
• QTMR channel debug control Interface. The API in this function group is used to configure the channel operation mode when the chip enters debug mode.
• QTMR channel enable control Interface. The API in this function group can be used to enable/disable one channel or multiple channels together.

How to use this driver

• Steps shall be done outside QTMR driver
  • Initialize the pin or/and XBAR with expected features configured. QTMR input pin signal can from chip pin or other peripheral output, and channel output signal can connect to chip pin or other peripheral input.
  • SoC level interrupt controller configuration shall be configured / enabled in application codes if QTMR channel is expected to generator interrupt on compare event, input capture edge event or count overflow event.
  • Interrupt entry function shall be added in the application codes and interrupt handler function shall be placed in the entry function to make sure the implemented interrupt handling codes will be invoked on a generation of interrupt.
  • Enable DMA and configure DMA channel trigger source in application codes if QTMR channel is expected to generator DMA request on input capture edge event or channel load CMPLDn register into COMPn event.
• Sets the QTMR work mode by invoking QTMR_Init()
  • [Optional] Invokes QTMR_GetChannelDefaultConfig() function to get the default channel configuration.
  • Set the member of channel configuration structure qtmr_channel_config_t to get expected feature. The following lists the members that need be set to enable the channel to count.
    • eCountMode : Used to set the count mode of the channel. E.g. If users set the count mode to count rising edges of primary source, this member can be configured as qtmr_channel_count_mode_t::kQTMR_CountPrimarySrcRiseEdge.
    • u16Comp1/2 : Decide the compare value in count up /down mode. Need set when "count until compare" is enabled.
  • Set the pointer member of qtmr_config_t with the address of "channel"/"input pin filter" configure structure.
  • Invokes QTMR_Init() to set QTMR configuration.
    • Channel will start directly when channel config variable member bEnableChannel is true.
• [Optional] Invokes QTMR_EnableChannels() to start channel counter.
• [Optional] Invokes function API to get status or do flexible control.

Typical Use Case

1. Count mode with trigger a periodic interrupt In this typical use case, the counter will count the rising edges of the IP bus clock divider by 2. And generate compare interrupts when channel count to u16Comp1 value.

   *        qtmr_config_t sQtmrConfig = {0};
   *        qtmr_channel_config_t sChannelConfig;
   *        sQtmrConfig.psChannelConfig[0] = &sChannelConfig;
   *        uint16_t interrupt_period;
   *        QTMR_GetChannelDefaultConfig(&sChannelConfig);
   *        sChannelConfig.sCountConfig.eCountLength = kQTMR_CountLengthUntilCompare;
   *        sChannelConfig.u16EnabledInterruptMask = kQTMR_CompareInterruptEnable;
   *        sChannelConfig.u16Comp1 = interrupt_period;
   *        QTMR_Init(DEMO_QTMR_BASEADDR, &sChannelConfig);
   *        QTMR_EnableChannels(QTMR, (uint16_t)kQTMR_Channel0);
   *    

2. Triggered count mode to capture PWM pulse width In this typical use case, the counter will start count the rising edges of the IP bus clock divider by 2 on first secondary input (secondary input connect to kQTMR_InputPin0) rising edge. And generate input edge flag on first secondary input falling edge. Then DMA will read the PWM pulse width from CAPT register. (Need enable DMA and configure DMA channel trigger source in application codes )

   *        qtmr_config_t sQtmrConfig = {0};
   *        qtmr_channel_config_t sChannelConfig;
   *        sQtmrConfig.psChannelConfig[0] = &sChannelConfig;
   *        QTMR_GetChannelDefaultConfig(&sChannelConfig);
   *        sChannelConfig.sInputConfig.eSecondarySourceCaptureMode = kQTMR_SecondarySrcCaptureFallingEdge;
   *        sChannelConfig.sCountConfig.eCountMode =
   *                 kQTMR_CountPrimarySrcRiseEdgeSecondarySrcRiseEdgeTrigWithReInit;
   *        sChannelConfig.u16EnabledDMAMask = kQTMR_InputEdgeFlagDmaEnable;
   *        QTMR_Init(QTMR, &sChannelConfig);
   *        QTMR_EnableChannels(QTMR, (uint16_t)kQTMR_Channel0);
   *    

3. Triggered count mode to short the PWM pulse width In this typical use case, the counter will start count the rising edges of the IP bus clock divider by 2 on the first secondary input (PWM output connect to kQTMR_InputPin0) rising edge. The channel output will clear on this init, and set until the counter compare event(compare value should short than PWM pulse width), then the output will clear on the next secondary input falling edge. This case makes QTMR channel output to be a PWM signal with a shorter pulse width.

   *        qtmr_config_t sQtmrConfig = {0};
   *        qtmr_channel_config_t sChannelConfig;
   *        sQtmrConfig.psChannelConfig[0] = &sChannelConfig;
   *        uint16_t delay_period;
   *        QTMR_GetChannelDefaultConfig(&sChannelConfig);
   *        sChannelConfig.sCountConfig.eCountMode =
   *                 kQTMR_CountPrimarySrcRiseEdgeSecondarySrcRiseEdgeTrig;
   *        sChannelConfig.sCountConfig.eCountLength = kQTMR_CountLengthUntilCompare;
   *        sChannelConfig.sOutputConfig.eOutputMode = kQTMR_OutputSetOnComareClearOnSecSrcActiveEdge;
   *        sChannelConfig.u16Comp1 = delay_period;
   *        QTMR_Init(QTMR, &sChannelConfig);
   *        QTMR_EnableChannels(QTMR, (uint16_t)kQTMR_Channel0);
   *    

4. PWM mode with variable frequency and pulse width In this typical use case, the channel output yields a pulse-width modulated (PWM) signal whose frequency and pulse width is determined by the values programmed into the COMP1 and COMP2 registers, and the input clock frequency. When interrupts generated by the channel compare2 event, use can write new values for both CMPLD1 and CMPLD2 according to the next pulse width and frequency.

   *        qtmr_config_t sQtmrConfig = {0};
   *        qtmr_channel_config_t sChannelConfig;
   *        sQtmrConfig.psChannelConfig[0] = &sChannelConfig;
   *        uint16_t pulse_width;
   *        uint16_t pwm_period;
   *        QTMR_GetChannelDefaultConfig(&sChannelConfig);
   *        sChannelConfig.u16EnabledInterruptMask = kQTMR_Compare2InterruptEnable;
   *        sChannelConfig.u16Comp1Preload = pulse_width;
   *        sChannelConfig.u16Comp2Preload = pwm_period - pulse_width;
   *        sChannelConfig.sCountConfig.eCountLength = kQTMR_CountLengthUntilCompare;
   *        sChannelConfig.sCountConfig.eCountPreload1 = kQTMR_CountPreloadOnComp2CompareEvent;
   *        sChannelConfig.sCountConfig.eCountPreload2 = kQTMR_CountPreloadOnComp1CompareEvent;
   *        sChannelConfig.sOutputConfig.eOutputMode = kQTMR_OutputToggleOnAltCompareReg;
   *        sChannelConfig.sOutputConfig.eOutputValueOnForce = kQTMR_OutputValueSetOnForce;
   *        sChannelConfig.sOutputConfig.bEnableSwForceOutput = true;
   *        sChannelConfig.sOutputConfig.bEnableOutputPin = true;
   *        QTMR_Init(QTMR, &sChannelConfig);
   *        QTMR_EnableChannels(QTMR, (uint16_t)kQTMR_Channel0);
   *