EFM32 Happy Gecko Software Documentation
efm32hg-doc-4.2.1
|
RTCDRV timer module, see RTCDRV Real Time Clock Timer driver page for detailed documentation.
. More...
Macros | |
#define | ECODE_EMDRV_RTCDRV_OK ( ECODE_OK ) |
Success return value. | |
#define | ECODE_EMDRV_RTCDRV_ALL_TIMERS_USED ( ECODE_EMDRV_RTCDRV_BASE | 0x00000001 ) |
No timers available. | |
#define | ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID ( ECODE_EMDRV_RTCDRV_BASE | 0x00000002 ) |
Illegal timer id. | |
#define | ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED ( ECODE_EMDRV_RTCDRV_BASE | 0x00000003 ) |
Timer is not allocated. | |
#define | ECODE_EMDRV_RTCDRV_PARAM_ERROR ( ECODE_EMDRV_RTCDRV_BASE | 0x00000004 ) |
Illegal input parameter. | |
#define | ECODE_EMDRV_RTCDRV_TIMER_NOT_RUNNING ( ECODE_EMDRV_RTCDRV_BASE | 0x00000005 ) |
Timer is not running. | |
Typedefs | |
typedef uint32_t | RTCDRV_TimerID_t |
Timer ID. | |
typedef void(* | RTCDRV_Callback_t) (RTCDRV_TimerID_t id, void *user) |
Typedef for the user supplied callback function which is called when a timer elapse. More... | |
Enumerations | |
enum | RTCDRV_TimerType_t { rtcdrvTimerTypeOneshot =0, rtcdrvTimerTypePeriodic =1 } |
Timer type enumerator. More... | |
Functions | |
Ecode_t | RTCDRV_AllocateTimer (RTCDRV_TimerID_t *id) |
Allocate timer. More... | |
Ecode_t | RTCDRV_DeInit (void) |
Deinitialize RTCDRV driver. More... | |
Ecode_t | RTCDRV_Delay (uint32_t ms) |
Millisecond delay function. More... | |
Ecode_t | RTCDRV_FreeTimer (RTCDRV_TimerID_t id) |
Free timer. More... | |
Ecode_t | RTCDRV_Init (void) |
Initialize RTCDRV driver. More... | |
Ecode_t | RTCDRV_IsRunning (RTCDRV_TimerID_t id, bool *isRunning) |
Check if a given timer is running. More... | |
Ecode_t | RTCDRV_StartTimer (RTCDRV_TimerID_t id, RTCDRV_TimerType_t type, uint32_t timeout, RTCDRV_Callback_t callback, void *user) |
Start a timer. More... | |
Ecode_t | RTCDRV_StopTimer (RTCDRV_TimerID_t id) |
Stop a given timer. More... | |
Ecode_t | RTCDRV_TimeRemaining (RTCDRV_TimerID_t id, uint32_t *timeRemaining) |
Get time left before a given timer expires. More... | |
uint32_t | RTCDRV_GetWallClock (void) |
Get wallclock time. More... | |
uint32_t | RTCDRV_GetWallClockTicks32 (void) |
Get wallclock tick count as a 32bit value. At 4 ticks per millisecond, overflow occurs after approximately 12.5 days. More... | |
uint64_t | RTCDRV_GetWallClockTicks64 (void) |
Get wallclock tick count as a 64 bit value. This will never overflow. More... | |
uint64_t | RTCDRV_MsecsToTicks (uint32_t ms) |
Convert from milliseconds to RTC/RTCC ticks. More... | |
uint64_t | RTCDRV_SecsToTicks (uint32_t secs) |
Convert from seconds to RTC/RTCC ticks. More... | |
Ecode_t | RTCDRV_SetWallClock (uint32_t secs) |
Set wallclock time. More... | |
uint32_t | RTCDRV_TicksToMsec (uint64_t ticks) |
Convert from RTC/RTCC ticks to milliseconds. More... | |
uint32_t | RTCDRV_TicksToSec (uint64_t ticks) |
Convert from RTC/RTCC ticks to seconds. More... | |
The RTCDRV driver use the RTC peripheral of a device in Silicon Laboratories Gecko microcontroller family to provide a user configurable number of software millisecond timers. Two kinds of timers are supported; oneshot timers and periodic timers. Timers will, when their timeout period has expired, call a user supplied callback function.
In addition to the timers, RTCDRV also offers an optional wallclock functionality. The wallclock keeps track of the number of seconds elapsed since RTCDRV was initialized.
Some properties of the RTCDRV driver are compile-time configurable. These properties are stored in a file named rtcdrv_config.h. A template for this file, containing default values, resides in the emdrv/config folder. Currently the configuration options are:
When integration with the SLEEP driver is enabled, RTCDRV will keep the SLEEP driver updated with regards to which energy mode that can be safely used.
To configure RTCDRV, provide your own configuration file. Here is a sample rtcdrv_config.h file:
#ifndef __SILICON_LABS_RTCDRV_CONFIG_H__ #define __SILICON_LABS_RTCDRV_CONFIG_H__ // Define how many timers RTCDRV provide. #define EMDRV_RTCDRV_NUM_TIMERS (4) // Uncomment the following line to include wallclock functionality. //#define EMDRV_RTCDRV_WALLCLOCK_CONFIG // Uncomment the following line to enable integration with SLEEP driver. //#define EMDRV_RTCDRV_SLEEPDRV_INTEGRATION #endif
This section contain brief descriptions of the functions in the API. You will find detailed information on input and output parameters and return values by clicking on the hyperlinked function names. Most functions return an error code, ECODE_EMDRV_RTCDRV_OK is returned on success, see ecode.h and rtcdriver.h for other error codes.
Your application code must include one header file: rtcdriver.h.
All functions defined in the API can be called from within interrupt handlers.
RTCDRV_Init(), RTCDRV_DeInit()
These functions initializes or deinitializes the RTCDRV driver. Typically RTCDRV_Init() is called once in your startup code.
RTCDRV_StartTimer(), RTCDRV_StopTimer()
Start/Stop a timer. When a timer expire, a user supplied callback function is called. A pointer to this function is passed to
RTCDRV_StartTimer(). Refer to TimerCallback for details of the callback prototype. Note that it is legal to start an already started timer, it will then just be restarted with the new timeout value.
RTCDRV_AllocateTimer(), RTCDRV_FreeTimer()
Reserve/release a timer. Many functions in the API require a timer ID as input parameter. Use RTCDRV_AllocateTimer() to aquire such a reference.
RTCDRV_TimeRemaining()
Get time left to timer expiry.
RTCDRV_Delay()
Millisecond delay function. This is an "active wait" delay function.
RTCDRV_IsRunning()
Check if a timer is running.
RTCDRV_GetWallClock(), RTCDRV_SetWallClock()
Get or set wallclock time.
RTCDRV_GetWallClockTicks32(), RTCDRV_GetWallClockTicks64()
Get wallclock time expressed as number of RTC/RTCC counter ticks, available both as 32bit and 64 bit values.
RTCDRV_MsecsToTicks(), RTCDRV_SecsToTicks(), RTCDRV_TicksToMsec(), RTCDRV_TicksToSec()
Conversion functions between seconds, milliseconds and RTC/RTCC counter ticks.
The timer expiry callback function:
The callback function, prototyped as RTCDRV_Callback_t(), is called from within the RTC peripheral interrupt handler on timer expiry. RTCDRV_Callback_t( RTCDRV_TimerID_t id ) is called with the timer id as input parameter.
The timer type:
Timers are either of oneshot type or of periodic type.
The timer type is an enumeration, see RTCDRV_TimerType_t for details.
#include "rtcdriver.h" int i = 0; RTCDRV_TimerID_t id; void myCallback( RTCDRV_TimerID_t id ) { // Timer has elapsed ! i++; if ( i < 10 ) { // Restart timer RTCDRV_StartTimer( id, rtcdrvTimerTypeOneshot, 100, myCallback ); } } int main( void ) { // Initialization of RTCDRV driver RTCDRV_Init(); // Reserve a timer RTCDRV_AllocateTimer( &id ); // Start a oneshot timer with 100 millisecond timeout RTCDRV_StartTimer( id, rtcdrvTimerTypeOneshot, 100, myCallback ); }
typedef void(* RTCDRV_Callback_t) (RTCDRV_TimerID_t id, void *user) |
[in] | id | The timer id. |
[in] | user | Extra parameter for user application. |
Definition at line 65 of file rtcdriver.h.
enum RTCDRV_TimerType_t |
Enumerator | |
---|---|
rtcdrvTimerTypeOneshot |
Oneshot timer. |
rtcdrvTimerTypePeriodic |
Periodic timer. |
Definition at line 68 of file rtcdriver.h.
Ecode_t RTCDRV_AllocateTimer | ( | RTCDRV_TimerID_t * | id | ) |
Reserve a timer instance.
[out] | id | The id of the reserved timer. |
Definition at line 228 of file rtcdriver.c.
References ECODE_EMDRV_RTCDRV_ALL_TIMERS_USED, ECODE_EMDRV_RTCDRV_OK, ECODE_EMDRV_RTCDRV_PARAM_ERROR, INT_Disable(), and INT_Enable().
Referenced by SPIDRV_Init().
Ecode_t RTCDRV_DeInit | ( | void | ) |
Will disable interrupts and turn off the clock to the underlying hardware timer. If integration with SLEEP module is enabled it will remove any restriction that are set on energy mode usage.
Definition at line 415 of file rtcdriver.c.
References CMU_ClockEnable(), cmuClock_RTC, ECODE_EMDRV_RTCDRV_OK, RTC_Enable(), SLEEP_SleepBlockEnd(), and sleepEM3.
Ecode_t RTCDRV_Delay | ( | uint32_t | ms | ) |
[in] | ms | Milliseconds to stay in the delay function. |
Definition at line 266 of file rtcdriver.c.
References ECODE_EMDRV_RTCDRV_OK.
Referenced by delay_10ms(), and delay_1ms().
Ecode_t RTCDRV_FreeTimer | ( | RTCDRV_TimerID_t | id | ) |
Release a reserved timer.
[out] | id | The id of the timer to release. |
Definition at line 294 of file rtcdriver.c.
References ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID, ECODE_EMDRV_RTCDRV_OK, INT_Disable(), and INT_Enable().
Referenced by SPIDRV_DeInit().
Ecode_t RTCDRV_Init | ( | void | ) |
Will enable all necessary clocks. Initializes internal datastructures and configures the underlying hardware timer.
Definition at line 322 of file rtcdriver.c.
References CMU_ClockDivSet(), CMU_ClockEnable(), CMU_ClockSelectSet(), CMU_DivToLog2(), cmuClock_CORELE, cmuClock_LFA, cmuClock_RTC, ECODE_EMDRV_RTCDRV_OK, RTC_Init(), SLEEP_SleepBlockBegin(), and sleepEM3.
Referenced by SPIDRV_Init().
Ecode_t RTCDRV_IsRunning | ( | RTCDRV_TimerID_t | id, |
bool * | isRunning | ||
) |
[in] | id | The id of the timer to query. |
[out] | isRunning | True if timer is running. False if not running. Only valid if return status is ECODE_EMDRV_RTCDRV_OK. |
Definition at line 466 of file rtcdriver.c.
References ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID, ECODE_EMDRV_RTCDRV_OK, ECODE_EMDRV_RTCDRV_PARAM_ERROR, ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED, INT_Disable(), and INT_Enable().
Ecode_t RTCDRV_StartTimer | ( | RTCDRV_TimerID_t | id, |
RTCDRV_TimerType_t | type, | ||
uint32_t | timeout, | ||
RTCDRV_Callback_t | callback, | ||
void * | user | ||
) |
[in] | id | The id of the timer to start. |
[in] | type | Timer type, oneshot or periodic. See RTCDRV_TimerType_t. |
[in] | timeout | Timeout expressed in milliseconds. If the timeout value is 0, the callback function will be called immediately and the timer will not be started. |
[in] | callback | Function to call on timer expiry. See RTCDRV_Callback_t. NULL is a legal value. |
[in] | user | Extra callback function parameter for user application. |
Definition at line 511 of file rtcdriver.c.
References ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID, ECODE_EMDRV_RTCDRV_OK, ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED, EFM32_MIN, INT_Disable(), INT_Enable(), rtcdrvTimerTypePeriodic, SLEEP_SleepBlockBegin(), and sleepEM3.
Referenced by SPIDRV_SReceive(), SPIDRV_SReceiveB(), SPIDRV_STransfer(), SPIDRV_STransferB(), SPIDRV_STransmit(), and SPIDRV_STransmitB().
Ecode_t RTCDRV_StopTimer | ( | RTCDRV_TimerID_t | id | ) |
[in] | id | The id of the timer to stop. |
Definition at line 661 of file rtcdriver.c.
References ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID, ECODE_EMDRV_RTCDRV_OK, ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED, INT_Disable(), and INT_Enable().
Referenced by SPIDRV_AbortTransfer(), and SPIDRV_DeInit().
Ecode_t RTCDRV_TimeRemaining | ( | RTCDRV_TimerID_t | id, |
uint32_t * | timeRemaining | ||
) |
[in] | id | The id of the timer to query. |
[out] | timeRemaining | Time left expressed in milliseconds. Only valid if return status is ECODE_EMDRV_RTCDRV_OK. |
Definition at line 696 of file rtcdriver.c.
References ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID, ECODE_EMDRV_RTCDRV_OK, ECODE_EMDRV_RTCDRV_PARAM_ERROR, ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED, ECODE_EMDRV_RTCDRV_TIMER_NOT_RUNNING, INT_Disable(), and INT_Enable().
uint32_t RTCDRV_GetWallClock | ( | void | ) |
Definition at line 752 of file rtcdriver.c.
References RTCDRV_GetWallClockTicks32().
uint32_t RTCDRV_GetWallClockTicks32 | ( | void | ) |
Definition at line 768 of file rtcdriver.c.
Referenced by RTCDRV_GetWallClock(), and RTCDRV_SetWallClock().
uint64_t RTCDRV_GetWallClockTicks64 | ( | void | ) |
Definition at line 795 of file rtcdriver.c.
uint64_t RTCDRV_MsecsToTicks | ( | uint32_t | ms | ) |
[in] | ms | Millisecond value to convert. |
Definition at line 837 of file rtcdriver.c.
uint64_t RTCDRV_SecsToTicks | ( | uint32_t | secs | ) |
[in] | secs | Second value to convert. |
Definition at line 853 of file rtcdriver.c.
Ecode_t RTCDRV_SetWallClock | ( | uint32_t | secs | ) |
[in] | secs | Value to set (seconds). |
Definition at line 820 of file rtcdriver.c.
References ECODE_EMDRV_RTCDRV_OK, and RTCDRV_GetWallClockTicks32().
uint32_t RTCDRV_TicksToMsec | ( | uint64_t | ticks | ) |
[in] | ticks | Number of ticks to convert. |
Definition at line 869 of file rtcdriver.c.
uint32_t RTCDRV_TicksToSec | ( | uint64_t | ticks | ) |
[in] | ticks | Number of ticks to convert. |
Definition at line 885 of file rtcdriver.c.