RTCDRVEMDRV
Detailed Description
Real-time Clock Driver.
The
rtcdriver.c
and
rtcdriver.h
source files for the RTCDRV device driver library are in the emdrv/rtcdrv folder.
Introduction
The RTCDRV driver uses the RTC peripheral of a device in Silicon Laboratories Gecko microcontroller family to provide a user-configurable number of software millisecond timers. Oneshot timers and periodic timers are supported. Timers will, when their timeout period has expired, call a user-supplied callback function.
- Note
- The callback function is called from within an interrupt handler with interrupts disabled.
In addition to the timers, RTCDRV also offers an optional wallclock functionality. The wallclock keeps track of the number of seconds elapsed since RTCDRV initialization.
RTCDRV resolution is 1 ms with 244 us accuracy. On the EFM32G family (classic Gecko), the accuracy is 61 us. Since RTCDRV is interrupt-driven using the default RTC interrupt priority level, timeout accuracy will be affected by the interrupt latency of the system.
Configuration Options
Some properties of the RTCDRV driver are compile-time configurable. These properties are stored in the rtcdrv_config.h file. A template for this file, containing default values, is in the emdrv/config folder. Currently the configuration options are as follows:
- The number of timers that RTCDRV provides.
- Inclusion of the wallclock functionality.
- Integration with the SLEEP driver.
When the integration with the SLEEP driver is enabled, RTCDRV will notify the SLEEP driver which energy mode can be safely used.
To configure RTCDRV, provide a custom configuration file. This is an example rtcdrv_config.h file:
#ifndef SILICON_LABS_RTCDRV_CONFIG_H #define SILICON_LABS_RTCDRV_CONFIG_H // Define how many timers RTCDRV provides. #define EMDRV_RTCDRV_NUM_TIMERS (4) // Uncomment the following line to include the wallclock functionality. //#define EMDRV_RTCDRV_WALLCLOCK_CONFIG // Uncomment the following line to enable integration with the SLEEP driver. //#define EMDRV_RTCDRV_SLEEPDRV_INTEGRATION // Uncomment the following line to let the RTCDRV clock on LFRCO. // The default is LFXO. //#define EMDRV_RTCDRV_USE_LFRCO #endif
The API
This section contains brief descriptions of the API functions. For more information about input and output parameters and return values, click 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.
The application code must include the
rtcdriver.h
header file.
All API functions can be called from within interrupt handlers.
RTCDRV_Init()
,
RTCDRV_DeInit()
These functions initialize or deinitialize the RTCDRV driver. Typically, RTCDRV_Init() is called once in the startup code.
RTCDRV_StartTimer()
,
RTCDRV_StopTimer()
Start/Stop a timer. When a timer expires, a user-supplied callback function is called. A pointer to this function is passed to RTCDRV_StartTimer(). See
TimerCallback
for details of the callback prototype. Note that it is legal to start an already started timer, which is restarted with the new timeout value.
RTCDRV_AllocateTimer()
,
RTCDRV_FreeTimer()
Reserve/release a timer. Many functions in the API require a timer ID as an input parameter. Use RTCDRV_AllocateTimer() to aquire this reference.
RTCDRV_TimeRemaining()
Get time left to the timer expiration.
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 expiration. RTCDRV_Callback_t( RTCDRV_TimerID_t id ) is called with the timer ID as an input parameter.
The timer type:
Timers are either oneshot or periodic.
- Oneshot timers run only once toward their expiration.
- Periodic timers will be automatically restarted when they expire.
The timer type is an enumeration, see RTCDRV_TimerType_t for details.
Example
#include "rtcdriver.h" #include <stddef.h> int i = 0; RTCDRV_TimerID_t id; void myCallback( RTCDRV_TimerID_t id, void * user ) { (void) user; // unused argument in this example i++; if ( i < 10 ) { // Restart timer RTCDRV_StartTimer( id, rtcdrvTimerTypeOneshot, 100, myCallback, NULL ); } } int main( void ) { // Initialization of the RTCDRV driver. RTCDRV_Init(); // Reserve a timer. RTCDRV_AllocateTimer( &id ); // Start a oneshot timer with 100 millisecond timeout. RTCDRV_StartTimer( id, rtcdrvTimerTypeOneshot, 100, myCallback, NULL ); return 0; }
Macros |
|
#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) |
An illegal timer ID.
|
|
#define | ECODE_EMDRV_RTCDRV_NOT_INITIALIZED ( ECODE_EMDRV_RTCDRV_BASE | 0x00000006) |
The driver is not initialized.
|
|
#define | ECODE_EMDRV_RTCDRV_OK ( ECODE_OK ) |
A successful return value.
|
|
#define | ECODE_EMDRV_RTCDRV_PARAM_ERROR ( ECODE_EMDRV_RTCDRV_BASE | 0x00000004) |
An illegal input parameter.
|
|
#define | ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED ( ECODE_EMDRV_RTCDRV_BASE | 0x00000003) |
A timer is not allocated.
|
|
#define | ECODE_EMDRV_RTCDRV_TIMER_NOT_RUNNING ( ECODE_EMDRV_RTCDRV_BASE | 0x00000005) |
A timer is not running.
|
|
Typedefs |
|
typedef void(* | RTCDRV_Callback_t ) ( RTCDRV_TimerID_t id, void *user) |
Typedef for the user supplied callback function which is called when a timer elapses.
|
|
typedef uint32_t | RTCDRV_TimerID_t |
Timer ID.
|
|
Enumerations |
|
enum |
RTCDRV_TimerType_t
{
rtcdrvTimerTypeOneshot = 0, rtcdrvTimerTypePeriodic = 1 } |
Timer type enumerator.
|
|
Functions |
|
Ecode_t | RTCDRV_AllocateTimer ( RTCDRV_TimerID_t *id) |
Allocate timer.
|
|
Ecode_t | RTCDRV_DeInit (void) |
Deinitialize the RTCDRV driver.
|
|
Ecode_t | RTCDRV_Delay (uint32_t ms) |
Millisecond delay function.
|
|
Ecode_t | RTCDRV_FreeTimer ( RTCDRV_TimerID_t id) |
Free timer.
|
|
uint32_t | RTCDRV_GetWallClock (void) |
Get wallclock time.
|
|
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.
|
|
uint64_t | RTCDRV_GetWallClockTicks64 (void) |
Get a wallclock tick count as a 64 bit value.
|
|
Ecode_t | RTCDRV_Init (void) |
Initialize the RTCDRV driver.
|
|
Ecode_t | RTCDRV_IsRunning ( RTCDRV_TimerID_t id, bool *isRunning) |
Check if a given timer is running.
|
|
uint64_t | RTCDRV_MsecsToTicks (uint32_t ms) |
Convert from milliseconds to RTC/RTCC ticks.
|
|
uint64_t | RTCDRV_SecsToTicks (uint32_t secs) |
Convert from seconds to RTC/RTCC ticks.
|
|
Ecode_t | RTCDRV_SetWallClock (uint32_t secs) |
Set wallclock time.
|
|
Ecode_t | RTCDRV_StartTimer ( RTCDRV_TimerID_t id, RTCDRV_TimerType_t type, uint32_t timeout, RTCDRV_Callback_t callback, void *user) |
Start a timer.
|
|
Ecode_t | RTCDRV_StopTimer ( RTCDRV_TimerID_t id) |
Stop a given timer.
|
|
uint32_t | RTCDRV_TicksToMsec (uint64_t ticks) |
Convert from RTC/RTCC ticks to milliseconds.
|
|
uint64_t | RTCDRV_TicksToMsec64 (uint64_t ticks) |
Convert from RTC/RTCC ticks to milliseconds with 64-bit resolution.
|
|
uint32_t | RTCDRV_TicksToSec (uint64_t ticks) |
Convert from RTC/RTCC ticks to seconds.
|
|
Ecode_t | RTCDRV_TimeRemaining ( RTCDRV_TimerID_t id, uint32_t *timeRemaining) |
Get time left before a given timer expires.
|
|
Typedef Documentation
typedef void(* RTCDRV_Callback_t) ( RTCDRV_TimerID_t id, void *user) |
Typedef for the user supplied callback function which is called when a timer elapses.
- Note
- This callback is called from within an interrupt handler with interrupts disabled.
- Parameters
-
[in] id
The timer ID. [in] user
An extra parameter for the user application.
Definition at line
66
of file
rtcdriver.h
.
Enumeration Type Documentation
enum RTCDRV_TimerType_t |
Function Documentation
Ecode_t RTCDRV_AllocateTimer | ( | RTCDRV_TimerID_t * |
id
|
) |
Allocate timer.
Reserve a timer instance.
- Parameters
-
[out] id
The ID of the reserved timer.
- Returns
-
ECODE_EMDRV_RTCDRV_OK
on success.
ECODE_EMDRV_RTCDRV_ALL_TIMERS_USED when no timers are available.
ECODE_EMDRV_RTCDRV_PARAM_ERROR if an invalid ID pointer was supplied.
ECODE_EMDRV_RTCDRV_NOT_INITIALIZED if the driver is not initialized.
Definition at line
238
of file
rtcdriver.c
.
References CORE_DECLARE_IRQ_STATE , CORE_ENTER_ATOMIC , CORE_EXIT_ATOMIC , ECODE_EMDRV_RTCDRV_ALL_TIMERS_USED , ECODE_EMDRV_RTCDRV_NOT_INITIALIZED , ECODE_EMDRV_RTCDRV_OK , and ECODE_EMDRV_RTCDRV_PARAM_ERROR .
Referenced by SPIDRV_Init() , and UTIL_sleepInit() .
Ecode_t RTCDRV_DeInit | ( | void |
|
) |
Deinitialize the RTCDRV driver.
Will disable interrupts and turn off the clock to the underlying hardware timer. If the integration with the SLEEP module is enabled, it will remove any restrictions that are set on energy mode usage.
- Returns
- ECODE_EMDRV_RTCDRV_OK .
Definition at line
448
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
|
) |
Millisecond delay function.
- Parameters
-
[in] ms
Milliseconds to stay in the delay function.
- Returns
-
ECODE_EMDRV_RTCDRV_OK
on success.
ECODE_EMDRV_RTCDRV_NOT_INITIALIZED if the driver is not initialized.
Definition at line
283
of file
rtcdriver.c
.
References ECODE_EMDRV_RTCDRV_NOT_INITIALIZED , and ECODE_EMDRV_RTCDRV_OK .
Referenced by delay_10ms() , and delay_1ms() .
Ecode_t RTCDRV_FreeTimer | ( | RTCDRV_TimerID_t |
id
|
) |
Free timer.
Release a reserved timer.
- Parameters
-
[out] id
The ID of the timer to release.
- Returns
-
ECODE_EMDRV_RTCDRV_OK
on success.
ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID if the ID has an illegal value.
Definition at line
316
of file
rtcdriver.c
.
References CORE_ATOMIC_SECTION , ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID , and ECODE_EMDRV_RTCDRV_OK .
Referenced by SPIDRV_DeInit() .
uint32_t RTCDRV_GetWallClock | ( | void |
|
) |
Get wallclock time.
- Returns
- Seconds elapsed since RTCDRV was initialized.
Definition at line
813
of file
rtcdriver.c
.
References RTCDRV_GetWallClockTicks32() .
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.
The return value of this function is in counter ticks. Use RTCDRV_TicksToMsec() or RTCDRV_TicksToSec() to convert ticks to the desired time unit.
- Returns
- A wallclock tick counter.
Definition at line
834
of file
rtcdriver.c
.
References CORE_DECLARE_IRQ_STATE , CORE_ENTER_ATOMIC , and CORE_EXIT_ATOMIC .
Referenced by RTCDRV_GetWallClock() , and RTCDRV_SetWallClock() .
uint64_t RTCDRV_GetWallClockTicks64 | ( | void |
|
) |
Get a wallclock tick count as a 64 bit value.
The return value of this function is in counter ticks. Use RTCDRV_TicksToMsec64() or RTCDRV_TicksToSec() to convert ticks to the desired time unit.
- Returns
- A wallclock tick counter.
Definition at line
869
of file
rtcdriver.c
.
References CORE_DECLARE_IRQ_STATE , CORE_ENTER_ATOMIC , and CORE_EXIT_ATOMIC .
Ecode_t RTCDRV_Init | ( | void |
|
) |
Initialize the RTCDRV driver.
Will enable all necessary clocks. Initializes internal data structures and configures the underlying hardware timer.
- Returns
- ECODE_EMDRV_RTCDRV_OK .
Definition at line
342
of file
rtcdriver.c
.
References CMU_ClockDivSet() , CMU_ClockEnable() , CMU_ClockSelectSet() , CMU_DivToLog2() , cmuClock_LFA , cmuClock_RTC , ECODE_EMDRV_RTCDRV_OK , RTC_Init() , SLEEP_SleepBlockBegin() , and sleepEM3 .
Referenced by SPIDRV_Init() , and UTIL_sleepInit() .
Ecode_t RTCDRV_IsRunning | ( | RTCDRV_TimerID_t |
id,
|
bool * |
isRunning
|
||
) |
Check if a given timer is running.
- Parameters
-
[in] id
The ID of the timer to query. [out] isRunning
True if the timer is running. False if not running. Only valid if return status is ECODE_EMDRV_RTCDRV_OK.
- Returns
-
ECODE_EMDRV_RTCDRV_OK
on success.
ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID if the ID has an illegal value.
ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED if the timer is not reserved.
ECODE_EMDRV_RTCDRV_PARAM_ERROR if an invalid isRunning pointer was supplied.
ECODE_EMDRV_RTCDRV_NOT_INITIALIZED if the driver is not initialized.
Definition at line
500
of file
rtcdriver.c
.
References CORE_DECLARE_IRQ_STATE , CORE_ENTER_ATOMIC , CORE_EXIT_ATOMIC , ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID , ECODE_EMDRV_RTCDRV_NOT_INITIALIZED , ECODE_EMDRV_RTCDRV_OK , ECODE_EMDRV_RTCDRV_PARAM_ERROR , and ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED .
uint64_t RTCDRV_MsecsToTicks | ( | uint32_t |
ms
|
) |
Convert from milliseconds to RTC/RTCC ticks.
- Parameters
-
[in] ms
Millisecond value to convert.
- Returns
- A number of ticks.
Definition at line
914
of file
rtcdriver.c
.
uint64_t RTCDRV_SecsToTicks | ( | uint32_t |
secs
|
) |
Convert from seconds to RTC/RTCC ticks.
- Parameters
-
[in] secs
Second value to convert.
- Returns
- A number of ticks.
Definition at line
930
of file
rtcdriver.c
.
Ecode_t RTCDRV_SetWallClock | ( | uint32_t |
secs
|
) |
Set wallclock time.
- Parameters
-
[in] secs
A value to set (seconds).
- Returns
- ECODE_EMDRV_RTCDRV_OK
Definition at line
897
of file
rtcdriver.c
.
References ECODE_EMDRV_RTCDRV_OK , and RTCDRV_GetWallClockTicks32() .
Ecode_t RTCDRV_StartTimer | ( | RTCDRV_TimerID_t |
id,
|
RTCDRV_TimerType_t |
type,
|
||
uint32_t |
timeout,
|
||
RTCDRV_Callback_t |
callback,
|
||
void * |
user
|
||
) |
Start a timer.
- Note
- It is legal to start an already running timer.
- Parameters
-
[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 is called immediately and the timer will not be started. [in] callback
Function to call when the timer expires. See RTCDRV_Callback_t . NULL is a legal value. [in] user
Extra callback function parameter for the user application.
- Returns
-
ECODE_EMDRV_RTCDRV_OK
on success.
ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID if the ID has an illegal value.
ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED if the timer is not reserved.
ECODE_EMDRV_RTCDRV_NOT_INITIALIZED if the driver is not initialized.
Definition at line
553
of file
rtcdriver.c
.
References CORE_DECLARE_IRQ_STATE , CORE_ENTER_ATOMIC , CORE_EXIT_ATOMIC , ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID , ECODE_EMDRV_RTCDRV_NOT_INITIALIZED , ECODE_EMDRV_RTCDRV_OK , ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED , rtcdrvTimerTypePeriodic , SL_MIN , SLEEP_SleepBlockBegin() , and sleepEM3 .
Referenced by SPIDRV_SReceive() , SPIDRV_SReceiveB() , SPIDRV_STransfer() , SPIDRV_STransferB() , SPIDRV_STransmit() , SPIDRV_STransmitB() , UTIL_sleep() , and UTIL_waitForEvent() .
Ecode_t RTCDRV_StopTimer | ( | RTCDRV_TimerID_t |
id
|
) |
Stop a given timer.
- Parameters
-
[in] id
The ID of the timer to stop.
- Returns
-
ECODE_EMDRV_RTCDRV_OK
on success.
ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID if the ID has an illegal value.
ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED if the timer is not reserved.
ECODE_EMDRV_RTCDRV_NOT_INITIALIZED if the driver is not initialized.
Definition at line
709
of file
rtcdriver.c
.
References CORE_DECLARE_IRQ_STATE , CORE_ENTER_ATOMIC , CORE_EXIT_ATOMIC , ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID , ECODE_EMDRV_RTCDRV_NOT_INITIALIZED , ECODE_EMDRV_RTCDRV_OK , and ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED .
Referenced by SPIDRV_AbortTransfer() , and SPIDRV_DeInit() .
uint32_t RTCDRV_TicksToMsec | ( | uint64_t |
ticks
|
) |
Convert from RTC/RTCC ticks to milliseconds.
- Parameters
-
[in] ticks
Number of ticks to convert.
- Returns
- A number of milliseconds.
Definition at line
946
of file
rtcdriver.c
.
uint64_t RTCDRV_TicksToMsec64 | ( | uint64_t |
ticks
|
) |
Convert from RTC/RTCC ticks to milliseconds with 64-bit resolution.
- Parameters
-
[in] ticks
Number of ticks to convert.
- Returns
- A number of milliseconds as a 64-bit value.
Definition at line
960
of file
rtcdriver.c
.
uint32_t RTCDRV_TicksToSec | ( | uint64_t |
ticks
|
) |
Convert from RTC/RTCC ticks to seconds.
- Parameters
-
[in] ticks
Number of ticks to convert.
- Returns
- A number of seconds.
Definition at line
976
of file
rtcdriver.c
.
Ecode_t RTCDRV_TimeRemaining | ( | RTCDRV_TimerID_t |
id,
|
uint32_t * |
timeRemaining
|
||
) |
Get time left before a given timer expires.
- Parameters
-
[in] id
The ID of the timer to query. [out] timeRemaining
Time left expressed in milliseconds. Only valid if the return status is ECODE_EMDRV_RTCDRV_OK.
- Returns
-
ECODE_EMDRV_RTCDRV_OK
on success.
ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID if the ID has an illegal value.
ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED if the timer is not reserved.
ECODE_EMDRV_RTCDRV_TIMER_NOT_RUNNING if the timer is not running.
ECODE_EMDRV_RTCDRV_PARAM_ERROR if an invalid timeRemaining pointer was supplied.
ECODE_EMDRV_RTCDRV_NOT_INITIALIZED if the driver is not initialized.
Definition at line
752
of file
rtcdriver.c
.
References CORE_DECLARE_IRQ_STATE , CORE_ENTER_ATOMIC , CORE_EXIT_ATOMIC , ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID , ECODE_EMDRV_RTCDRV_NOT_INITIALIZED , ECODE_EMDRV_RTCDRV_OK , ECODE_EMDRV_RTCDRV_PARAM_ERROR , ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED , and ECODE_EMDRV_RTCDRV_TIMER_NOT_RUNNING .
Referenced by UTIL_waitForEvent() .