Basic Timer

Features

  • 32-bit up-counter

  • Overflow interrupt generation

  • Preloadable auto-reload register

  • Sleep mode operation with interrupt wakeup capability

Application Examples

SDK provides two implementation types for Basic Timer:

  • mbed Examples

    • Path: {SDK}\example\peripheral\mbed\Timer\mbed_gtimer\{demo}

    • Demonstrates Basic Timer control in mbed environment

  • raw Examples

    • Path: {SDK}\example\peripheral\raw\Timer\raw_gtimer\{demo}

    • Demonstrates direct register-level Basic Timer control

Note

Check example’s README.md for supported chip information.

API

Raw API

BASICTIMER Exported Types

struct RTIM_TimeBaseInitTypeDef

TIM Basic Init Structure Definition.

Public Members

u32 TIM_Prescaler

Specifies the prescaler value used to divide the TIM clock. This parameter can be a number between 0x0 and 0xFFFF, basic timer dont care.

u32 TIM_Period

Specifies the period value to be loaded into the active Auto-Reload Register at the next update event. This parameter is 16bits for PWM/Capture timers, and 32bits for basic timers. You can get it from SourceClock & TIM_Prescaler.

u32 TIM_UpdateEvent

Specifies whether or not to enable update event(UEV). This parameter can be ENABLE or DISABLE. ENABLE means UEV Enable, DISABLE means UEV Disable.

u32 TIM_UpdateSource

Specifies the update request source. This parameter can be TIM_UpdateSource_Overflow or TIM_UpdateSource_Global. TIM_UpdateSource_Overflow means counter overflow generates an update event(UEV). TIM_UpdateSource_Global means both counter overflow and setting the UG bit can generate UEV.

u32 TIM_ARRProtection

DISABLE or ENABLE, when ENABLE: period will update when cnt = 0(counter overflow, an UEV happens), or period will update immediatly.

u8 TIM_Idx

Specifies the timer index.

u32 TIM_SecureTimer

Specifies the secure attribute of this timer. This parameter is used in secure world of trustzone.

BASICTIMER Exported Constants

SEC Control Enable Definition
/* R/W 0x0 Secure timer enable * 0: non-security timer * 1: security timer */
#define TIM_BIT_SEC ((u32)0x00000001 << 0)
TIM Event Source
/* Event source: counter update event. */
#define TIM_EventSource_Update ((u32)0x00000001)

/* Check if LP timer event source value is valid. */
#define IS_LP_TIM_EVENT_SOURCE ((((SOURCE) & 0xFFFFFFFE) == 0x0000) && \
    (((SOURCE) & 0x1) != 0x0000))
RTL8721Dx: 
/* Check if HP timer event source value is valid. */
#define IS_HP_TIM_EVENT_SOURCE ((((SOURCE) & 0xFFFFFE00) == 0x0000) && \
    (((SOURCE) & 0x1FF) != 0x0000))
TIM PSC Reload Mode
/* Prescaler reloaded at next update event. */
#define TIM_PSCReloadMode_Update ((u32)0x00000000)

/* Prescaler reloaded immediately. */
#define TIM_PSCReloadMode_Immediate ((u32)0x00000001)

/* Check if prescaler reload mode value is valid. */
#define IS_TIM_PRESCALER_RELOAD (((RELOAD) == TIM_PSCReloadMode_Update) || \
    ((RELOAD) == TIM_PSCReloadMode_Immediate))
TIM Prescaler
/* Check if prescaler value fits in 16 bits. */
#define IS_TIM_PSC (VAL <= 0xFFFF)
TIM Update Source
/* Source of update is the counter overflow or the setting of UG bit. */
#define TIM_UpdateSource_Global ((u32)0x00000000)

/* Source of update is counter overflow. */
#define TIM_UpdateSource_Overflow ((u32)0x00000004)

/* Check if update request source value is valid. */
#define IS_TIM_UPDATE_SOURCE (((SOURCE) == TIM_UpdateSource_Global) || \
    ((SOURCE) == TIM_UpdateSource_Overflow))
TIM Type
RTL8721Dx: 
/* Check if peripheral is a valid timer. */
#define IS_TIM_ALL_TIM (((PERIPH) == TIM0) || \
    ((PERIPH) == TIM1) || \
    ((PERIPH) == TIM2) || \
    ((PERIPH) == TIM3) || \
    ((PERIPH) == TIM4) || \
    ((PERIPH) == TIM5) || \
    ((PERIPH) == TIM6) || \
    ((PERIPH) == TIM7) || \
    ((PERIPH) == TIM8) || \
    ((PERIPH) == TIM9) || \
    ((PERIPH) == TIM10) || \
    ((PERIPH) == TIM11) || \
    ((PERIPH) == TIM0_S) || \
    ((PERIPH) == TIM1_S) || \
    ((PERIPH) == TIM2_S) || \
    ((PERIPH) == TIM3_S) || \
    ((PERIPH) == TIM4_S) || \
    ((PERIPH) == TIM5_S) || \
    ((PERIPH) == TIM6_S) || \
    ((PERIPH) == TIM7_S) || \
    ((PERIPH) == TIM8_S) || \
    ((PERIPH) == TIM9_S) || \
    ((PERIPH) == TIM10_S) || \
    ((PERIPH) == TIM11_S))

/* Check if peripheral is a secure-world timer. */
#define IS_TIM_SEC_TIM (((PERIPH) == TIM0_S) || \
    ((PERIPH) == TIM1_S) || \
    ((PERIPH) == TIM2_S) || \
    ((PERIPH) == TIM3_S) || \
    ((PERIPH) == TIM4_S) || \
    ((PERIPH) == TIM5_S) || \
    ((PERIPH) == TIM6_S) || \
    ((PERIPH) == TIM7_S) || \
    ((PERIPH) == TIM8_S) || \
    ((PERIPH) == TIM9_S) || \
    ((PERIPH) == TIM10_S) || \
    ((PERIPH) == TIM11_S))

/* Check if peripheral is a basic timer. */
#define IS_TIM_BASIC_TIM (((PERIPH) == TIM0) || \
    ((PERIPH) == TIM1) || \
    ((PERIPH) == TIM2) || \
    ((PERIPH) == TIM3) || \
    ((PERIPH) == TIM4) || \
    ((PERIPH) == TIM5) || \
    ((PERIPH) == TIM6) || \
    ((PERIPH) == TIM7) || \
    ((PERIPH) == TIM10) || \
    ((PERIPH) == TIM11) || \
    ((PERIPH) == TIM0_S) || \
    ((PERIPH) == TIM1_S) || \
    ((PERIPH) == TIM2_S) || \
    ((PERIPH) == TIM3_S) || \
    ((PERIPH) == TIM4_S) || \
    ((PERIPH) == TIM5_S) || \
    ((PERIPH) == TIM6_S) || \
    ((PERIPH) == TIM7_S) || \
    ((PERIPH) == TIM10_S) || \
    ((PERIPH) == TIM11_S))

/* Check if peripheral is a 40 MHz timer. */
#define IS_TIM_40M_TIM (((PERIPH) == TIM8) || \
    ((PERIPH) == TIM9) || \
    ((PERIPH) == TIM10) || \
    ((PERIPH) == TIM11) || \
    ((PERIPH) == TIM8_S) || \
    ((PERIPH) == TIM9_S) || \
    ((PERIPH) == TIM10_S) || \
    ((PERIPH) == TIM11_S))
TIM Peripheral Count
RTL8721Dx: 
/* Total number of TIM peripherals. */
#define TimerNum 12

BASICTIMER Exported Functions

TimeBase Management Functions
void RTIM_ARRPreloadConfig(RTIM_TypeDef *TIMx, u32 NewState)

Enable or disable TIMx peripheral Preload register on ARR.

Parameters:

  • TIMx – The TIM peripheral, where x can be 0 to (TimerNum - 1). See TIM Peripheral Count.

  • NewState – New state of the TIMx peripheral Preload register This parameter can be: ENABLE or DISABLE.

Note

  • DISABLE: TIMx_ARR register is not buffered, and shadow register will update immediately

  • ENABLE: TIMx_ARR register is buffered, and shadow register will update after overflow

void RTIM_ChangePeriod(RTIM_TypeDef *TIMx, u32 Autoreload)

Set the TIMx Autoreload Register(TIMx_ARR) value to change period with protection.

Parameters:

  • TIMx – The TIM peripheral, where x can be 0 to (TimerNum - 1). See TIM Peripheral Count.

  • Autoreload –

    Specifies the Autoreload register new value. The valid range depends on the TIM type:

    • Basic timers (non-CCM): 0 ~ 0xFFFFFFFF

    • CCM timers (PWM/Capture): 0 ~ 0xFFFF

void RTIM_ChangePeriodImmediate(RTIM_TypeDef *TIMx, u32 Autoreload)

Set the TIMx Autoreload Register(TIMx_ARR) value to change period.

Parameters:

  • TIMx – The TIM peripheral, where x can be 0 to (TimerNum - 1). See TIM Peripheral Count.

  • Autoreload –

    Specifies the Autoreload register new value. The valid range depends on the TIM type:

    • Basic timers (non-CCM): 0 ~ 0xFFFFFFFF

    • CCM timers (PWM/Capture): 0 ~ 0xFFFF

void RTIM_Cmd(RTIM_TypeDef *TIMx, u32 NewState)

Enable or disable the specified TIM peripheral.

Parameters:

  • TIMx – The TIM peripheral, where x can be 0 to (TimerNum - 1). See TIM Peripheral Count.

  • NewState – New state of the TIMx peripheral. This parameter can be: ENABLE or DISABLE.

void RTIM_DeInit(RTIM_TypeDef *TIMx)

DeInit the specified TIM peripheral, including disable TIM, close and clear interrupt.

Parameters:
void RTIM_GenerateEvent(RTIM_TypeDef *TIMx, u32 TIM_EventSource)

Configure the TIMx event to be generated by software.

Parameters:

  • TIMx – The TIM peripheral, where x can be 0 to (TimerNum - 1). See TIM Peripheral Count.

  • TIM_EventSource – Specifies the event source. This parameter can be one or more of the following values TIM Event Source

u32 RTIM_GetCount(RTIM_TypeDef *TIMx)

Get the TIMx Counter value.

Parameters:
Returns:

Counter Register value.

void RTIM_PrescalerConfig(RTIM_TypeDef *TIMx, u32 Prescaler, u32 TIM_PSCReloadMode)

Configure the TIMx Prescaler.

Parameters:

  • TIMx – The TIM peripheral with CCM capability. See IS_TIM_CCM_TIM macro.

  • Prescaler – Specifies the Prescaler Register value, which can be a number in 0~0xFFFF range.

  • TIM_PSCReloadMode –

    Specifies the TIM Prescaler Reload mode This parameter can be one of the following values:

    • TIM_PSCReloadMode_Update: The Prescaler is loaded at the update event.

    • TIM_PSCReloadMode_Immediate: The Prescaler is loaded immediately.

void RTIM_Reset(RTIM_TypeDef *TIMx)

Reset timer, counter will start from 0.

Parameters:
void RTIM_TimeBaseInit(RTIM_TypeDef *TIMx, RTIM_TimeBaseInitTypeDef *TIM_InitStruct, IRQn_Type IrqNum, IRQ_FUN UserCB, u32 UserCBData)

Initialize the TIMx Time Base Unit peripheral according to the specified parameters in the TIM_InitStruct.

Parameters:

  • TIMx – The TIM peripheral, where x can be 0 to (TimerNum - 1). See TIM Peripheral Count.

  • TIM_InitStruct – Pointer to a RTIM_TimeBaseInitTypeDef structure that contains the configuration information for the specified TIM peripheral.

  • IrqNum – The IRQ number for TIMx, which can be TIMERx_IRQ where x is 0 to (TimerNum - 1). See TIM Peripheral Count.

  • UserCB – ISR callback function. This parameter uses the IRQ_FUN type, which takes a void pointer and returns u32.

  • UserCBData – Parameters of ISR function.

void RTIM_TimeBaseStructInit(RTIM_TimeBaseInitTypeDef *TIM_InitStruct)

Initialize the parameters in the TIM_InitStruct with its default value.

Parameters:
void RTIM_UpdateDisableConfig(RTIM_TypeDef *TIMx, u32 NewState)

Enable or Disable the TIMx Update event(UEV).

Parameters:

  • TIMx – The TIM peripheral, where x can be 0 to (TimerNum - 1). See TIM Peripheral Count.

  • NewState – New state of the TIMx UDIS bit This parameter can be:ENABLE or DISABLE

Note

  • If NewState is ENABLE, Update Disable Bit is set, UEV disable and shadow registers keep their value.

  • If NewState is DISABLE, Update Disable Bit is clear, UEV enable and buffered registers are loaded with their preload values when UEV happen.

void RTIM_UpdateRequestConfig(RTIM_TypeDef *TIMx, u32 TIM_UpdateSource)

Configure the TIMx Update Request Interrupt source.

Parameters:

  • TIMx – The TIM peripheral, where x can be 0 to (TimerNum - 1). See TIM Peripheral Count.

  • TIM_UpdateSource –

    Specifies the Update source. This parameter can be one of the following values:

    • TIM_UpdateSource_Global: Source of update is the counter overflow or the setting of UG bit.

    • TIM_UpdateSource_Overflow: Source of update is counter overflow.

RTL8721Dx:

Not supported.

Interrupt Management Functions
u32 RTIM_GetINTStatus(RTIM_TypeDef *TIMx, u32 TIM_IT)

Check whether the TIM interrupt has occurred or not.

Parameters:

  • TIMx – The TIM peripheral, where x can be 0 to (TimerNum - 1). See TIM Peripheral Count.

  • TIM_IT – Specifies the TIM interrupt source to check. This parameter is one of the TIM interrupt sources. See TIM Interrupt Control for available values.

Returns:

The new state of the TIM_IT:

  • TRUE: The specified TIM interrupt has occurred.

  • FALSE: The specified TIM interrupt has not occurred.

void RTIM_INTClear(RTIM_TypeDef *TIMx)

Clear the TIMx’s all interrupt pending bits.

Parameters:
void RTIM_INTClearPendingBit(RTIM_TypeDef *TIMx, u32 TIM_IT)

Clear the TIMx’s interrupt pending bits.

Parameters:

  • TIMx – The TIM peripheral, where x can be 0 to (TimerNum - 1). See TIM Peripheral Count.

  • TIM_IT – Specifies the pending bit(s) to clear. This parameter is a combination of TIM interrupt bits. See TIM Interrupt Control for available values.

void RTIM_INTConfig(RTIM_TypeDef *TIMx, u32 TIM_IT, u32 NewState)

ENABLE/DISABLE the TIMx’s interrupt bits.

Parameters:

  • TIMx – The TIM peripheral, where x can be 0 to (TimerNum - 1). See TIM Peripheral Count.

  • TIM_IT – Specifies the interrupt bit(s) to configure. This parameter is a combination of TIM interrupt bits. See TIM Interrupt Control for available values.

  • NewState – ENABLE or DISABLE.

Mbed API

MBED_TIMER Exported Types

Structure Type
typedef void (*gtimer_irq_handler)(uint32_t id)

Typedef of interrupt handler function pointer.

typedef struct gtimer_s gtimer_t

Typedef of struct gtimer_s as gtimer_t.

Enumeration Type
RTL8721Dx:
enum TIMER_ID

Enumeration of general timer IDs.

Values:

/* General timer 0. */
TIMER0 = 0

/* General timer 1. */
TIMER1 = 1

/* General timer 2. */
TIMER2 = 2

/* General timer 3. */
TIMER3 = 3

/* General timer 4. */
TIMER4 = 4

/* General timer 5. */
TIMER5 = 5

/* General timer 6. */
TIMER6 = 6

/* General timer 7. */
TIMER7 = 7

/* General timer 8. */
TIMER8 = 8

/* General timer 9. */
TIMER9 = 9

/* General timer 10. */
TIMER10 = 10

/* General timer 11. */
TIMER11 = 11

/* Total number of general timers. */
GTIMER_MAX = 12

MBED_TIMER Exported Functions

void gtimer_deinit(gtimer_t *obj)

Deinitialize the timer device, including interrupt and timer registers.

Parameters:

  • obj – Timer object defined in application software.

void gtimer_init(gtimer_t *obj, uint32_t tid)

Initialize the timer device, including timer registers and interrupt.

Parameters:

  • obj – Timer object defined in application software.

  • tid – General timer ID, which can be a value of TIMER_ID enumeration.

uint32_t gtimer_read_tick(gtimer_t *obj)

Get counter value of the specified timer.

Parameters:

  • obj – Timer object defined in application software.

Returns:

Counter value.

uint64_t gtimer_read_us(gtimer_t *obj)

Read current timer tick in microsecond.

Parameters:

  • obj – Timer object defined in application software.

Returns:

64b tick time in microsecond(us).

void gtimer_reload(gtimer_t *obj, uint32_t duration_us)

Change period of the specified timer.

Parameters:

  • obj – Timer object defined in application software.

  • duration_us – Period to be set in microseconds.

void gtimer_start(gtimer_t *obj)

Start the specified timer and enable update interrupt.

Parameters:

  • obj – Timer object defined in application software.

void gtimer_start_one_shout(gtimer_t *obj, uint32_t duration_us, void *handler, uint32_t hid)

Start the specified timer in one-shot mode with specified period and interrupt handler.

Parameters:

  • obj – Timer object defined in application software.

  • duration_us – Period to be set in microseconds.

  • handler – User-defined IRQ callback function.

  • hid – User-defined IRQ callback parameter.

Note

In one-shot mode, timer will stop counting the first time counter overflows.

void gtimer_start_periodical(gtimer_t *obj, uint32_t duration_us, void *handler, uint32_t hid)

Start the specified timer in periodical mode with specified period and interrupt handler.

Parameters:

  • obj – Timer object defined in application software.

  • duration_us – Period to be set in microseconds.

  • handler – User-defined IRQ callback function.

  • hid – User-defined IRQ callback parameter.

Note

In periodical mode, timer will restart from 0 each time the counter overflows.

void gtimer_stop(gtimer_t *obj)

Disable the specified timer peripheral.

Parameters:

  • obj – Timer object defined in application software.