NHS31xx SW API
timer: 16/32-bit Timer driver

Detailed Description

This driver provides APIs for the configuration and operation of both the 16-bit "CT16B" and 32-bit "CT32B" counters/timers. The CT16B and CT32B HW blocks (16 and 32 bits timer/counter units) provide 16-bit and 32-bit counters/timers function respectively.

Introduction:
This note describes the conceptual model of the timer hardware block. The timer hardware block has three extensions around its counter core: matching, external match control and pulse width modulation. Each of these are discussed next.
Counter core:
The core of the timer block is its counter. The counter register is called Timer Counter or TCR and is 32 bits (or 16 bits) wide. It is incremented when the prescaler of the timer expires, that is, when the Prescale Counter PC reaches the value in the Prescale Register PR. The core has a fourth register, the Timer Control Register TCR, with two control bits: enabling counting respectively resetting (both TC and PC).
dot_inline_dotgraph_6.png
The Prescale Counter PC counts cycles of the peripheral clock, which is the same as the system clock (towards the ARM).
Matching:
The first extension adds interrupt capabilities. There are 4 match registers MR0, MR1, MR2 and MR3 that are continuously compared against the Timer Counter TC. When the Timer Counter TC matches MRx, several actions can be performed by the hardware: The actions are programmed in the Match Control Register MCR. For each Match Register MRx, the Match Control Register MCR has three bits MRxI, MRxR and MRxS that enable the actions Interrupt, Reset and Stop respectively. The Interrupt Register IR records which of the match registers caused the interrupt.
dot_inline_dotgraph_7.png
External Match Control:
The timer hardware block has output lines: MATx. As usual, those outputs are routed through the iocon: IO Configuration driver to optionally connect them to external pins (typically with a function name CT32B_MATx or CT16B_MATx).

The External Match Control extension allows controlling the MATx outputs based on the match registers. When the Timer Counter TC matches MRx, the following actions can be performed by the hardware:

These actions are programmed in the External Match Register EMR. For each Match Register MRx, the EMR has a two bit External Match Control field EMCx with values:

Also note that the EMR has a one bit status field External Match EMx reflecting the state for each of the MATx outputs.

dot_inline_dotgraph_8.png

The External Match Control extension has a limited implementation: MAT2 and MAT3 are not supported, and thus EMR does not have the EM2/EM3 status fields, nor the EMC2/EMC3 control fields.

Also note that there is only one MRx that can operate on MATx. As a result it is hard to implement PWM functionality: by programming EMCx to toggle we can make a 50% duty cycling signal on MATx. For better control use the Pulse Width Modulation feature of the timer.

Pulse Width Modulation:
Pulse Width Modulation PWM extension can drive the MATx registers instead of having the External Match Control extension drive the MATx pins. This is achieved by setting the PWM Enable bit PWMENx in the PWM Control register PWMC.

The PWM extension drives MATx in a different way then the External Match Control extension. Basically, it starts by driving MATx low, until TC reached MRx, then it drives MATx high. When the Matching extension issues a reset (via MCR.MRyR) of TC, MATx is cleared again and the whole process repeats. So, with the PWM extension the duty cycle is controlled independently (MRx) from the frequency (MRy).

Note that the PWM extension has a limited implementation similar to the External Match Control extension: MAT2 and MAT3 are not supported, and thus PWMC does not have the PWMEN2/PWMEN3 control fields. Each block features:

  1. One 16/32-bit Timer Counter with a programmable 16/32-bit Prescaler
  2. Four 16/32-bit Match Registers that allow:
    • Continuous operation with optional interrupt generation on match
    • Stop timer on match with optional interrupt generation
    • Reset timer on match with optional interrupt generation
  3. Up to two external outputs corresponding to the match registers with the following capabilities:
    • Set LOW on match
    • Set HIGH on match
    • Toggle on match
    • Do nothing on match
    • Single-edge controlled PWM outputs
Operation description of Timer Block:
A Prescale Counter PC counts cycles of the peripheral clock and increments until it matches the Prescale Register PR value. On the next clock (i.e. NSS_TIMER_T.PR "PR" +1), the Timer Counter TC is incremented and the PC resets to zero.

The TC is then compared against each of the four Match Registers (MR0, MR1, MR2, MR3). When the value matches, the corresponding bits in Match Control Register MCR and External Match Registers EMR registers determine the actions to be executed. Configurable actions on match can be a combination of the following:

Refer to timing chart in the user manual for detail. Match registers can be independently set to generate interrupt on match, operate as configured by EMR or in PWM output mode.

The External Match Registers EMR determines if a match of TC and associated MRn shall either:

However, when the match output pins are configured as PWM output with Chip_TIMER_SetMatchOutputMode, the function of the external match output pins are determined by single-edge controlled PWM mode. Up to two single-edge controlled PWM outputs can be selected on the xxxxx_MAT[0,1] outputs.

In PWM mode, PWM outputs go LOW at the beginning of each PWM cycle (timer is set to zero). PWM outputs goes HIGH when its match value is reached. The match register for PWM channel0 is NSS_TIMER_T.MR "MR0", while that for PWM channel1 is NSS_TIMER_T.MR "MR1". One additional match register is necessary. This match register resets the timer, thus determines the PWM cycle length. When the timer is reset to zero, all currently HIGH PWM match outputs are cleared (LOW).

Example 1 - Increment a 10ms timed SW counter:
  • NSS_TIMER_T.PR "PR" : SystemClock / 500 (500Hz, 2ms per tick)
  • NSS_TIMER_T.MR "MR0" : 1 (5x 2ms)
  • Interrupt and reset on match are enabled; Stop-on-match disabled
Interrupt Handler:
/* To be called under interrupt from CT16B0_IRQHandler */
extern uint32_t counterTick_10ms;
counterTick_10ms++;
/* Further handling of the timer interrupt */
/* ... */
}
Example 2 - Setup 50Hz, 50% duty-cycle External Match Output on 32-bit xxxxx_MAT0 output pin:
Refer to user manual for actual pin names.
  • Prescale increment TC one tick every 2ms (500Hz)
  • NSS_TIMER_T.TC "TC" counts from 0 to 4 (10ms), matches NSS_TIMER_T.MR "MR0" and toggle xxxxx_MAT0 pin (Cycle Length is 20ms, or 50Hz output)
  • when NSS_TIMER_T.TC "TC" reaches 4, it resets to zero and repeats
Example 3 - Setup 2Hz PWM on both xxxxx_MAT0 and xxxxx_MAT1 output pins.
Refer to user manual for actual pin names. PWMEN0 and PWMEN1 are enabled with NSS_TIMER_T.MR "MR0" at 15/125 (88% duty cycle), NSS_TIMER_T.MR "MR1" at 75/125 (40% duty-cycle) and NSS_TIMER_T.MR "MR2" (with reset on match set) at 124.
  • xxxxx_MAT0 & xxxxx_MAT1 are both set LOW at start.
  • NSS_TIMER_T.TC "TC" counts until 15 and raise-HIGH xxxxx_MAT0
  • NSS_TIMER_T.TC "TC" continue counting until 75 and raise-HIGH xxxxx_MAT1, and
  • when NSS_TIMER_T.TC "TC" reaches 124, both xxxxx_MAT0 and xxxxx_MAT1 are set low, TC reset to zero and repeats

Data Structures

struct  NSS_TIMER_T
 

Macros

#define TIMER_IR_CLR(n)   (1u << (n))
 
#define TIMER_MATCH_INT(n)   ((1u << (n)) & 0x0F)
 
#define TIMER_ENABLE   ((1u << 0))
 
#define TIMER_RESET   ((1u << 1))
 
#define TIMER_INT_ON_MATCH(n)   (1u << ((n) * 3))
 
#define TIMER_RESET_ON_MATCH(n)   (1u << (((n) * 3) + 1))
 
#define TIMER_STOP_ON_MATCH(n)   (1u << (((n) * 3) + 2))
 

Enumerations

enum  TIMER_PIN_MATCH_STATE_T {
  TIMER_EXTMATCH_DO_NOTHING = 0,
  TIMER_EXTMATCH_CLEAR = 1,
  TIMER_EXTMATCH_SET = 2,
  TIMER_EXTMATCH_TOGGLE = 3
}
 
enum  NSS_TIMER_MATCH_OUTPUT_MODE_T {
  TIMER_MATCH_OUTPUT_EMC,
  TIMER_MATCH_OUTPUT_PWM
}
 

Functions

void Chip_TIMER_Init (NSS_TIMER_T *pTMR, CLOCK_PERIPHERAL_T clk)
 
void Chip_TIMER_DeInit (NSS_TIMER_T *pTMR, CLOCK_PERIPHERAL_T clk)
 
static bool Chip_TIMER_MatchPending (NSS_TIMER_T *pTMR, int8_t matchnum)
 
static void Chip_TIMER_ClearMatch (NSS_TIMER_T *pTMR, int8_t matchnum)
 
static void Chip_TIMER_Enable (NSS_TIMER_T *pTMR)
 
static void Chip_TIMER_Disable (NSS_TIMER_T *pTMR)
 
static uint32_t Chip_TIMER_ReadCount (NSS_TIMER_T *pTMR)
 
static uint32_t Chip_TIMER_ReadPrescale (NSS_TIMER_T *pTMR)
 
static void Chip_TIMER_PrescaleSet (NSS_TIMER_T *pTMR, uint32_t prescale)
 
static void Chip_TIMER_SetMatch (NSS_TIMER_T *pTMR, int8_t matchnum, uint32_t matchval)
 
void Chip_TIMER_Reset (NSS_TIMER_T *pTMR)
 
static void Chip_TIMER_MatchEnableInt (NSS_TIMER_T *pTMR, int8_t matchnum)
 
static void Chip_TIMER_MatchDisableInt (NSS_TIMER_T *pTMR, int8_t matchnum)
 
static void Chip_TIMER_ResetOnMatchEnable (NSS_TIMER_T *pTMR, int8_t matchnum)
 
static void Chip_TIMER_ResetOnMatchDisable (NSS_TIMER_T *pTMR, int8_t matchnum)
 
static void Chip_TIMER_StopOnMatchEnable (NSS_TIMER_T *pTMR, int8_t matchnum)
 
static void Chip_TIMER_StopOnMatchDisable (NSS_TIMER_T *pTMR, int8_t matchnum)
 
void Chip_TIMER_ExtMatchControlSet (NSS_TIMER_T *pTMR, int8_t initial_state, TIMER_PIN_MATCH_STATE_T matchState, int8_t matchnum)
 
void Chip_TIMER_SetMatchOutputMode (NSS_TIMER_T *pTMR, int matchnum, NSS_TIMER_MATCH_OUTPUT_MODE_T mode)
 
NSS_TIMER_MATCH_OUTPUT_MODE_T Chip_TIMER_GetMatchOutputMode (NSS_TIMER_T *pTMR, int matchnum)
 

Data Structure Documentation

◆ NSS_TIMER_T

struct NSS_TIMER_T

16/32-bit Timer register block structure

Data Fields
__IO uint32_t IR

Interrupt Register. The IR can be written to clear interrupts. The IR can be read to identify which of eight possible interrupt sources are pending.

__IO uint32_t TCR

Timer Control Register. The TCR is used to control the Timer Counter functions. The Timer Counter can be disabled or reset through the TCR.

__IO uint32_t TC

Timer Counter. This register is incremented every PR+1 cycles of PCLK. The TC is controlled through the TCR.

__IO uint32_t PR

Prescale Register. When the Prescale Counter (below) is equal to this value, the next clock increments the TC and clears the PC.

__IO uint32_t PC

Prescale Counter. The PC is a counter which is incremented to the value stored in PR. When the value in PR is reached, the TC is incremented and the PC is cleared. The PC is observable and controllable through the bus interface.

__IO uint32_t MCR

Match Control Register. The MCR is used to control if an interrupt is generated and if the TC is reset when a Match occurs.

__IO uint32_t MR[4]

Match Register. MR can be enabled through the MCR to reset the TC, stop both the TC and PC, and/or generate an interrupt every time MR matches the TC.

__I uint32_t RESERVED0[5]
__IO uint32_t EMR

External Match Register. The EMR controls the external match pins MATn.0-3 (MAT0.0-3 and MAT1.0-3 respectively).

__I uint32_t RESERVED1[13]
__IO uint32_t PWMC

The PWMC enables PWM mode of the external match pins

Macro Definition Documentation

◆ TIMER_IR_CLR

#define TIMER_IR_CLR (   n)    (1u << (n))

Macro to clear interrupt pending

◆ TIMER_MATCH_INT

#define TIMER_MATCH_INT (   n)    ((1u << (n)) & 0x0F)

Macro for getting a timer match interrupt bit

◆ TIMER_ENABLE

#define TIMER_ENABLE   ((1u << 0))

Timer/counter enable bit

◆ TIMER_RESET

#define TIMER_RESET   ((1u << 1))

Timer/counter reset bit

◆ TIMER_INT_ON_MATCH

#define TIMER_INT_ON_MATCH (   n)    (1u << ((n) * 3))

Bit location for interrupt on MRx match, n = 0 to 3

◆ TIMER_RESET_ON_MATCH

#define TIMER_RESET_ON_MATCH (   n)    (1u << (((n) * 3) + 1))

Bit location for reset on MRx match, n = 0 to 3

◆ TIMER_STOP_ON_MATCH

#define TIMER_STOP_ON_MATCH (   n)    (1u << (((n) * 3) + 2))

Bit location for stop on MRx match, n = 0 to 3

Enumeration Type Documentation

◆ TIMER_PIN_MATCH_STATE_T

Standard timer initial match pin state and change state

Enumerator
TIMER_EXTMATCH_DO_NOTHING 

Timer match state does nothing on match pin

TIMER_EXTMATCH_CLEAR 

Timer match state sets match pin low

TIMER_EXTMATCH_SET 

Timer match state sets match pin high

TIMER_EXTMATCH_TOGGLE 

Timer match state toggles match pin

◆ NSS_TIMER_MATCH_OUTPUT_MODE_T

Operating mode of external output pins

Enumerator
TIMER_MATCH_OUTPUT_EMC 

External Match Control mode

TIMER_MATCH_OUTPUT_PWM 

PWM mode

Function Documentation

◆ Chip_TIMER_Init()

void Chip_TIMER_Init ( NSS_TIMER_T pTMR,
CLOCK_PERIPHERAL_T  clk 
)

Initialize a timer

Parameters
pTMR: The base address of the TIMER peripheral on the chip
clk: Associated peripheral clock

◆ Chip_TIMER_DeInit()

void Chip_TIMER_DeInit ( NSS_TIMER_T pTMR,
CLOCK_PERIPHERAL_T  clk 
)

Shutdown a timer

Parameters
pTMR: The base address of the TIMER peripheral on the chip
clk: Associated peripheral clock

◆ Chip_TIMER_MatchPending()

static bool Chip_TIMER_MatchPending ( NSS_TIMER_T pTMR,
int8_t  matchnum 
)
inlinestatic

Determines if the match interrupt for the passed timer and match counter is pending.

Parameters
pTMR: The base address of the TIMER peripheral on the chip
matchnum: Match interrupt number to check
Returns
true if the interrupt is pending, false otherwise

◆ Chip_TIMER_ClearMatch()

static void Chip_TIMER_ClearMatch ( NSS_TIMER_T pTMR,
int8_t  matchnum 
)
inlinestatic

Clears a (pending) match interrupt

Parameters
pTMR: The base address of the TIMER peripheral on the chip
matchnum: Match interrupt number to clear
Note
Clears a pending timer match interrupt.

◆ Chip_TIMER_Enable()

static void Chip_TIMER_Enable ( NSS_TIMER_T pTMR)
inlinestatic

Enables the timer (starts count)

Parameters
pTMR: The base address of the TIMER peripheral on the chip
Note
Enables the timer to start counting.

◆ Chip_TIMER_Disable()

static void Chip_TIMER_Disable ( NSS_TIMER_T pTMR)
inlinestatic

Disables the timer (stops count)

Parameters
pTMR: The base address of the TIMER peripheral on the chip
Note
Disables the timer to stop counting.

◆ Chip_TIMER_ReadCount()

static uint32_t Chip_TIMER_ReadCount ( NSS_TIMER_T pTMR)
inlinestatic

Returns the current timer count

Parameters
pTMR: The base address of the TIMER peripheral on the chip
Returns
Current timer terminal count value
Note
Returns the current timer terminal count.

◆ Chip_TIMER_ReadPrescale()

static uint32_t Chip_TIMER_ReadPrescale ( NSS_TIMER_T pTMR)
inlinestatic

Returns the current prescale count

Parameters
pTMR: The base address of the TIMER peripheral on the chip
Returns
Current timer prescale count value
Note
Returns the current prescale count.

◆ Chip_TIMER_PrescaleSet()

static void Chip_TIMER_PrescaleSet ( NSS_TIMER_T pTMR,
uint32_t  prescale 
)
inlinestatic

Sets the prescaler value

Parameters
pTMR: The base address of the TIMER peripheral on the chip
prescale: Prescale value to set the prescale register to
Note
Sets the prescale count value.

◆ Chip_TIMER_SetMatch()

static void Chip_TIMER_SetMatch ( NSS_TIMER_T pTMR,
int8_t  matchnum,
uint32_t  matchval 
)
inlinestatic

Sets a timer match value

Parameters
pTMR: The base address of the TIMER peripheral on the chip
matchnum: Match timer to set match count for
matchval: Match value for the selected match count
Note
Sets one of the timer match values.

◆ Chip_TIMER_Reset()

void Chip_TIMER_Reset ( NSS_TIMER_T pTMR)

Resets the timer terminal and prescale counts to 0

Parameters
pTMR: The base address of the TIMER peripheral on the chip

◆ Chip_TIMER_MatchEnableInt()

static void Chip_TIMER_MatchEnableInt ( NSS_TIMER_T pTMR,
int8_t  matchnum 
)
inlinestatic

Enables a match interrupt that fires when the terminal count matches the match counter value.

Parameters
pTMR: The base address of the TIMER peripheral on the chip
matchnum: Match timer, 0 to 3

◆ Chip_TIMER_MatchDisableInt()

static void Chip_TIMER_MatchDisableInt ( NSS_TIMER_T pTMR,
int8_t  matchnum 
)
inlinestatic

Disables a match interrupt for a match counter.

Parameters
pTMR: The base address of the TIMER peripheral on the chip
matchnum: Match timer, 0 to 3

◆ Chip_TIMER_ResetOnMatchEnable()

static void Chip_TIMER_ResetOnMatchEnable ( NSS_TIMER_T pTMR,
int8_t  matchnum 
)
inlinestatic

For the specific match counter, enables reset of the terminal count register when a match occurs

Parameters
pTMR: The base address of the TIMER peripheral on the chip
matchnum: Match timer, 0 to 3

◆ Chip_TIMER_ResetOnMatchDisable()

static void Chip_TIMER_ResetOnMatchDisable ( NSS_TIMER_T pTMR,
int8_t  matchnum 
)
inlinestatic

For the specific match counter, disables reset of the terminal count register when a match occurs

Parameters
pTMR: The base address of the TIMER peripheral on the chip
matchnum: Match timer, 0 to 3

◆ Chip_TIMER_StopOnMatchEnable()

static void Chip_TIMER_StopOnMatchEnable ( NSS_TIMER_T pTMR,
int8_t  matchnum 
)
inlinestatic

Enable a match timer to stop the terminal count when a match count equals the terminal count.

Parameters
pTMR: The base address of the TIMER peripheral on the chip
matchnum: Match timer, 0 to 3

◆ Chip_TIMER_StopOnMatchDisable()

static void Chip_TIMER_StopOnMatchDisable ( NSS_TIMER_T pTMR,
int8_t  matchnum 
)
inlinestatic

Disable stop on match for a match timer. Disables a match timer to stop the terminal count when a match count equals the terminal count.

Parameters
pTMR: The base address of the TIMER peripheral on the chip
matchnum: Match timer, 0 to 3

◆ Chip_TIMER_ExtMatchControlSet()

void Chip_TIMER_ExtMatchControlSet ( NSS_TIMER_T pTMR,
int8_t  initial_state,
TIMER_PIN_MATCH_STATE_T  matchState,
int8_t  matchnum 
)

Sets external match control (MATn.matchnum) pin control. For the pin selected with matchnum, sets the function of the pin that occurs on a terminal count match for the match count.

Parameters
pTMR: The base address of the TIMER peripheral on the chip
initial_state: Initial state of the pin, high(1) or low(0)
matchState: Selects the match state for the pin
matchnum: MATn.matchnum signal to use. 0: Ext match 0, 1: Ext match 1
Note
For the pin selected with matchnum, sets the function of the pin that occurs a terminal count match for the match count. PWM functionality must be disabled for the corresponding external pin, see Chip_TIMER_SetMatchOutputMode.

◆ Chip_TIMER_SetMatchOutputMode()

void Chip_TIMER_SetMatchOutputMode ( NSS_TIMER_T pTMR,
int  matchnum,
NSS_TIMER_MATCH_OUTPUT_MODE_T  mode 
)

Sets PWM mode of external match pin. Each of the two external match outputs (xxxx_MAT[0,1] or xxxx_MAT[0,1]) can be independently set to perform either as PWM output or as match output whose function is controlled by the External Match Register EMR. If PWM function is disabled, the function of the pin will be controlled by the timer external match control. See detailed description and example above for details. In the user manual, this function sets the PWM control register PWMC. To drive the output pins, iocon: IO Configuration driver has to be configured to CT16/CT32 function.

Parameters
pTMR: The base address of the TIMER peripheral on the chip.
matchnum: 0: xxxx_MAT0, 1: xxxx_MAT1
mode: The output mode to be set, see NSS_TIMER_MATCH_OUTPUT_MODE_T

◆ Chip_TIMER_GetMatchOutputMode()

NSS_TIMER_MATCH_OUTPUT_MODE_T Chip_TIMER_GetMatchOutputMode ( NSS_TIMER_T pTMR,
int  matchnum 
)

Get external match output mode. This returns status of PWM control registers.

Parameters
pTMR: The base address of the TIMER peripheral on the chip
matchnum: 0: xxxxx_MAT0, 1: xxxxx_MAT1
Returns
Current external match output mode