RTCDRVEMDRV

Detailed Description

Real-time Clock Driver.

The source files for the RTCDRV device driver library resides in the emdrv/rtcdrv folder, and are named rtcdriver.c and rtcdriver.h.


Introduction

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.

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 was initialized.

RTCDRV resolution is 1 ms with 244 us accuracy. On the EFM32G family (classic Gecko's) 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 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:

  • The number of timers that RTCDRV provides.
  • Inclusion of the wallclock functionality.
  • Integration with SLEEP driver.

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

// Uncomment one of the following lines to let RTCDRV clock on LFRCO or PLFRCO,
// the default is LFXO.
//#define EMDRV_RTCDRV_USE_LFRCO
//#define EMDRV_RTCDRV_USE_PLFRCO

#endif


The API

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.

  • Oneshot timer run only once toward their expiry.
  • Periodic timers will be automatically restartet 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 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)
 Illegal timer id.
 
#define ECODE_EMDRV_RTCDRV_OK   (ECODE_OK)
 Success return value.
 
#define ECODE_EMDRV_RTCDRV_PARAM_ERROR   (ECODE_EMDRV_RTCDRV_BASE | 0x00000004)
 Illegal input parameter.
 
#define ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED   (ECODE_EMDRV_RTCDRV_BASE | 0x00000003)
 Timer is not allocated.
 
#define ECODE_EMDRV_RTCDRV_TIMER_NOT_RUNNING   (ECODE_EMDRV_RTCDRV_BASE | 0x00000005)
 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 elapse.
 
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 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 wallclock tick count as a 64 bit value. This will never overflow.
 
Ecode_t RTCDRV_Init (void)
 Initialize 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.
 
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 elapse.

Note
This callback is called from within an interrupt handler with interrupts disabled.
Parameters
[in]idThe timer id.
[in]userExtra parameter for user application.

Definition at line 63 of file rtcdriver.h.

Enumeration Type Documentation

Timer type enumerator.

Enumerator
rtcdrvTimerTypeOneshot 

Oneshot timer.

rtcdrvTimerTypePeriodic 

Periodic timer.

Definition at line 66 of file rtcdriver.h.

Function Documentation

Ecode_t RTCDRV_AllocateTimer ( RTCDRV_TimerID_t id)

Allocate timer.

Reserve a timer instance.

Parameters
[out]idThe 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.

Definition at line 232 of file rtcdriver.c.

References CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, ECODE_EMDRV_RTCDRV_ALL_TIMERS_USED, ECODE_EMDRV_RTCDRV_OK, and ECODE_EMDRV_RTCDRV_PARAM_ERROR.

Referenced by SPIDRV_Init(), and UTIL_sleepInit().

Ecode_t RTCDRV_DeInit ( void  )

Deinitialize RTCDRV driver.

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.

Returns
ECODE_EMDRV_RTCDRV_OK.

Definition at line 418 of file rtcdriver.c.

References CMU_ClockEnable(), cmuClock_RTCC, ECODE_EMDRV_RTCDRV_OK, RTCC_Enable(), SLEEP_SleepBlockEnd(), and sleepEM3.

Ecode_t RTCDRV_Delay ( uint32_t  ms)

Millisecond delay function.

Parameters
[in]msMilliseconds to stay in the delay function.
Returns
ECODE_EMDRV_RTCDRV_OK.

Definition at line 271 of file rtcdriver.c.

References 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]idThe id of the timer to release.
Returns
ECODE_EMDRV_RTCDRV_OK on success.
ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID if id has an illegal value.

Definition at line 299 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 759 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.

Returns
Wallclock tick counter.

Definition at line 775 of file rtcdriver.c.

Referenced by RTCDRV_GetWallClock(), and RTCDRV_SetWallClock().

uint64_t RTCDRV_GetWallClockTicks64 ( void  )

Get wallclock tick count as a 64 bit value. This will never overflow.

Returns
Wallclock tick counter.

Definition at line 801 of file rtcdriver.c.

Ecode_t RTCDRV_Init ( void  )

Initialize RTCDRV driver.

Will enable all necessary clocks. Initializes internal datastructures and configures the underlying hardware timer.

Returns
ECODE_EMDRV_RTCDRV_OK.

Definition at line 325 of file rtcdriver.c.

References CMU_ClockDivSet(), CMU_ClockEnable(), CMU_ClockSelectSet(), CMU_DivToLog2(), cmuClock_LFA, cmuClock_LFE, cmuClock_RTCC, ECODE_EMDRV_RTCDRV_OK, RTCC_Init_TypeDef::presc, RTCC_ChannelInit(), RTCC_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]idThe id of the timer to query.
[out]isRunningTrue if 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 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.

Definition at line 469 of file rtcdriver.c.

References CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID, 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]msMillisecond value to convert.
Returns
Number of ticks.

Definition at line 842 of file rtcdriver.c.

uint64_t RTCDRV_SecsToTicks ( uint32_t  secs)

Convert from seconds to RTC/RTCC ticks.

Parameters
[in]secsSecond value to convert.
Returns
Number of ticks.

Definition at line 858 of file rtcdriver.c.

Ecode_t RTCDRV_SetWallClock ( uint32_t  secs)

Set wallclock time.

Parameters
[in]secsValue to set (seconds).
Returns
ECODE_EMDRV_RTCDRV_OK

Definition at line 825 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]idThe id of the timer to start.
[in]typeTimer type, oneshot or periodic. See RTCDRV_TimerType_t.
[in]timeoutTimeout expressed in milliseconds. If the timeout value is 0, the callback function will be called immediately and the timer will not be started.
[in]callbackFunction to call on timer expiry. See RTCDRV_Callback_t. NULL is a legal value.
[in]userExtra callback function parameter for user application.
Returns
ECODE_EMDRV_RTCDRV_OK on success.
ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID if id has an illegal value.
ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED if the timer is not reserved.

Definition at line 516 of file rtcdriver.c.

References CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID, 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]idThe id of the timer to stop.
Returns
ECODE_EMDRV_RTCDRV_OK on success.
ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID if id has an illegal value.
ECODE_EMDRV_RTCDRV_TIMER_NOT_ALLOCATED if the timer is not reserved.

Definition at line 666 of file rtcdriver.c.

References CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID, 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]ticksNumber of ticks to convert.
Returns
Number of milliseconds.

Definition at line 874 of file rtcdriver.c.

uint32_t RTCDRV_TicksToSec ( uint64_t  ticks)

Convert from RTC/RTCC ticks to seconds.

Parameters
[in]ticksNumber of ticks to convert.
Returns
Number of seconds.

Definition at line 890 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]idThe id of the timer to query.
[out]timeRemainingTime left expressed in milliseconds. Only valid if return status is ECODE_EMDRV_RTCDRV_OK.
Returns
ECODE_EMDRV_RTCDRV_OK on success.
ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID if 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.

Definition at line 703 of file rtcdriver.c.

References CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, ECODE_EMDRV_RTCDRV_ILLEGAL_TIMER_ID, 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().