NHS31xx SW API
rtc: Real-Time Clock driver

Detailed Description

The Real-Time Clock (RTC) module has two main features:

Time up-counter
This records the time (e.g. seconds since epoch, which can be converted in year/month/day, hour/minute/second).
Wake-up down-counter
This counter counts down to zero and can 'wake-up' the chip from standby modes: Sleep, Deep Sleep and Deep Power Down.

Both the counters step on a "tick". A tick consists of a number of TFRO pulses. The TFRO is calibrated during production to run at about 32768 Hz on reset, one tick is typically about 32768 TFRO pulses and thus 1 second. The exact number of TFRO clocks to make 1 second is loaded during boot time and stored in the RTCCAL register. Both the TFRO oscillator and the RTC HW block are part of the always-on power domain.

Time up-counter
As soon as the TFRO is connected, the up-counter starts incrementing. This happens independently from the power mode and the ARM state. See pmu: Power Management Unit driver for details on TFRO configuration.
Wake-up down-counter
The down-counter is by default disabled. It needs to be explicitly enabled and started in order to count. When active, the counter counts down, independently from the power mode and the ARM state. When the down-counter reaches zero, a wake-up event is generated. This allows the chip to 'wake-up' from Sleep, Deep Sleep, and Deep Power Down.
In Deep Power Down mode, the IC will wake up unconditionally when the down-counter reaches zero. It is not required to configure the NVIC and or any other start logic for waking up from the Deep Power Down mode. A reset signal is generated and a full boot process is run. SW execution is not resumed, and no interrupt function is called. The application can instead check at startup whether the PMU_DPD_WAKEUPREASON_RTC flag is set.
In other modes (Active, Sleep, Deep Sleep), when the down-counter reaches zero, an RTC interrupt is generated that forks to two slots in the NVIC: the standard RTC peripheral interrupt RTC_IRQn and the secondary interrupt RTCPWREQ_IRQn via Start Logic.
See NVIC API and System wake-up start logic for more details.
Note
There can be other 'wake-up' reasons from various standby modes. See pmu: Power Management Unit driver for details.
In order to operate the RTC module
Warning
Each RTC block register read and write action requires at least one wait period. A single wait period can take up to 100us to complete due to hardware synchronization within the module. All functions in this driver make at least one such register access unless stated otherwise. This impacts performance and should be taken into account, especially when calling RTC driver functions in an interrupt context. If an RTC block register read/write preempts another RTC block register read/write, the procedure is repeated leading to another wait period, until no preemption is detected.
Example 1 - RTC down-counter: wake-up from Sleep Mode

Initialization (once):
Activation:
/* RTC_IRQHandler is called after 10 seconds. System resumes here after ISR has been serviced. */
/* ... */

RTC interrupt handling:
/* To be called under interrupt from RTC_IRQHandler */
/* Further handling of the event "down-counter expired". */
/* ... */
}

Example 2 - RTC down-counter: wake-up from Deep Sleep Mode, and manual start.
This example is using System wake-up start logic

Initialization (once):
Activation:
/* When RTC_WAKEUPCTRL_AUTO is not set, RTC_WAKEUPCTRL_START is required to start the down-counter. */
/* RTC_IRQHandler is called after 10 seconds. System resumes here after ISR has been serviced. */
/* ... */

RTC interrupt handling:
/* To be called under interrupt from RTCPWREQ_IRQHandler */
/* Further handling of the event "down-counter expired". */
/* ... */
}

Example 3 - RTC "wake-up down-counter" with Deep Power Down Mode

Initialization (once):
Activation:
ASSERT(false); /* System does not resume here. Unreachable. */

RTC interrupt service routine will not be called as NVIC is not active during Deep Power Down mode.

Data Structures

struct  NSS_RTC_T
 

Enumerations

enum  RTC_WAKEUPCTRL_T {
  RTC_WAKEUPCTRL_ENABLE = (1 << 0),
  RTC_WAKEUPCTRL_AUTO = (1 << 1),
  RTC_WAKEUPCTRL_START = (1 << 2),
  RTC_WAKEUPCTRL_DISABLE = 0
}
 
enum  RTC_INT_T {
  RTC_INT_WAKEUP = (1 << 0),
  RTC_INT_ALL = 0x01,
  RTC_INT_NONE = 0
}
 

Functions

void Chip_RTC_Init (NSS_RTC_T *pRTC)
 
void Chip_RTC_DeInit (NSS_RTC_T *pRTC)
 
void Chip_RTC_SetCalibration (NSS_RTC_T *pRTC, int calibValue)
 
int Chip_RTC_GetCalibration (NSS_RTC_T *pRTC)
 
void Chip_RTC_Wakeup_SetControl (NSS_RTC_T *pRTC, RTC_WAKEUPCTRL_T control)
 
RTC_WAKEUPCTRL_T Chip_RTC_Wakeup_GetControl (NSS_RTC_T *pRTC)
 
void Chip_RTC_Wakeup_SetReload (NSS_RTC_T *pRTC, int ticks)
 
int Chip_RTC_Wakeup_GetReload (NSS_RTC_T *pRTC)
 
int Chip_RTC_Wakeup_GetRemaining (NSS_RTC_T *pRTC)
 
bool Chip_RTC_Wakeup_IsRunning (NSS_RTC_T *pRTC)
 
int Chip_RTC_Time_GetValue (NSS_RTC_T *pRTC)
 
void Chip_RTC_Time_SetValue (NSS_RTC_T *pRTC, int tickValue)
 
void Chip_RTC_Int_SetEnabledMask (NSS_RTC_T *pRTC, RTC_INT_T mask)
 
RTC_INT_T Chip_RTC_Int_GetEnabledMask (NSS_RTC_T *pRTC)
 
RTC_INT_T Chip_RTC_Int_GetRawStatus (NSS_RTC_T *pRTC)
 
void Chip_RTC_Int_ClearRawStatus (NSS_RTC_T *pRTC, RTC_INT_T flags)
 

Data Structure Documentation

◆ NSS_RTC_T

struct NSS_RTC_T

RTC block register block structure

Data Fields
volatile uint32_t CR

< Defines 'read / write' permissions Control register

volatile uint32_t SR

< Defines 'read / write' permissions Status register

volatile uint32_t CAL

< Defines 'read / write' permissions TFRO counts per 'tick' calibration value

volatile uint32_t SLEEPT

< Defines 'read / write' permissions "Wake-up down-counter" tick value - Amount of ticks until a 'wake-up' event

volatile const uint32_t VAL

< Defines 'read only' permissions Current (remaining) "wake-up down-counter" tick value

volatile uint32_t IMSC

< Defines 'read / write' permissions Interrupt mask set/clear register - Enable/disable interrupt

volatile const uint32_t RIS

< Defines 'read only' permissions Raw Interrupt status register

volatile const uint32_t MIS

< Defines 'read only' permissions Masked interrupt status register

volatile uint32_t ICR

< Defines 'write only' permissions Interrupt clear register

volatile const uint32_t ACCSTAT

< Defines 'read only' permissions Access status register

volatile const uint32_t RESERVED[2]

< Defines 'read only' permissions

volatile uint32_t TIME

< Defines 'read / write' permissions Real-time clock "time up-counter" value

Enumeration Type Documentation

◆ RTC_WAKEUPCTRL_T

RTC "wake-up down-counter" control. For use with Chip_RTC_Wakeup_SetControl and Chip_RTC_Wakeup_GetControl

Note
Enumerator
RTC_WAKEUPCTRL_ENABLE 

Enables "wake-up down-counter"

RTC_WAKEUPCTRL_AUTO 

Enables the automatic start/restart of the "wake-up down-counter", each time a tick value is written in NSS_RTC_T.SLEEPT with Chip_RTC_Wakeup_SetReload().

RTC_WAKEUPCTRL_START 

Starts counting of "wake-up down-counter" with tick value loaded with Chip_RTC_Wakeup_SetReload.

RTC_WAKEUPCTRL_DISABLE 

Disables "wake-up down-counter" and stops counting

◆ RTC_INT_T

enum RTC_INT_T

RTC block interrupt bitfields

Enumerator
RTC_INT_WAKEUP 

"wake-up down-counter" has reached 0

RTC_INT_ALL 

All RTC interrupt bits

RTC_INT_NONE 

No RTC interrupt

Function Documentation

◆ Chip_RTC_Init()

void Chip_RTC_Init ( NSS_RTC_T pRTC)

Enables ARM access to RTC block via APB bus

Parameters
pRTC: The base address of the RTC peripheral on the chip
Note
This RTC driver requires that TFRO clock connection to RTC is enabled. TFRO is connected to RTC by default after a full-system reset.

◆ Chip_RTC_DeInit()

void Chip_RTC_DeInit ( NSS_RTC_T pRTC)

Halts the counting of "wake-up down-counter" and disables ARM access to RTC block via APB bus.
This function:

  1. Disables "wake-up down-counter" operation
  2. Disables "wake-up down-counter" interrupt
  3. Disables ARM access to RTC block via APB clock
Parameters
pRTC: The base address of the RTC peripheral on the chip
Warning
This function performs two synchronized register accesses. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_SetCalibration()

void Chip_RTC_SetCalibration ( NSS_RTC_T pRTC,
int  calibValue 
)

Sets the number of TFRO clock pulses in one RTC 'tick'

Parameters
pRTC: The base address of the RTC peripheral on the chip
calibValue16-bit value indicating the number of TFRO clock pulses in one tick.
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_GetCalibration()

int Chip_RTC_GetCalibration ( NSS_RTC_T pRTC)

Returns the number of TFRO clock pulses in one RTC 'tick'

Parameters
pRTC: The base address of the RTC peripheral on the chip
Returns
16-bit value indicating the number of TFRO clock pulses in one tick.
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_Wakeup_SetControl()

void Chip_RTC_Wakeup_SetControl ( NSS_RTC_T pRTC,
RTC_WAKEUPCTRL_T  control 
)

Controls the operation of "wake-up down-counter"

Parameters
pRTC: The base address of the RTC peripheral on the chip
control: Bitfield of Control Mode of type RTC_WAKEUPCTRL_T
See also
RTC_WAKEUPCTRL_T for operation details
Note
RTC interrupt MUST be enabled to wake up from various standby modes (Sleep/Deep Sleep/Deep Power Down).
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_Wakeup_GetControl()

RTC_WAKEUPCTRL_T Chip_RTC_Wakeup_GetControl ( NSS_RTC_T pRTC)

Returns the control register of the "wake-up down-counter" operation

Parameters
pRTC: The base address of the RTC peripheral on the chip
Returns
Bitfield of Control state.
Note
RTC_WAKEUPCTRL_START bit is cleared when "wake-up down-counter" reaches zero, or when a new tick is loaded with Chip_RTC_Wakeup_SetReload without RTC_WAKEUPCTRL_AUTO
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_Wakeup_SetReload()

void Chip_RTC_Wakeup_SetReload ( NSS_RTC_T pRTC,
int  ticks 
)

Sets the "wake-up down-counter" ticks. This tick value is decremented until it reaches zero, and the RTC interrupt is generated, thus a 'wake-up' event

Parameters
pRTC: The base address of the RTC peripheral on the chip
ticks: 24bit unsigned number of ticks (seconds) to wake-up. Acceptable value from 0 to 16,777,215
Note
RTC interrupt MUST be enabled to wake up from various standby modes (Sleep/Deep Sleep/Deep Power Down).
When RTC_WAKEUPCTRL_AUTO bit is set, calling Chip_RTC_Wakeup_SetControl starts the "wake-up down-counter".
Without RTC_WAKEUPCTRL_AUTO bit, setting a "wake-up down-counter" value clears RTC_WAKEUPCTRL_START.
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_Wakeup_GetReload()

int Chip_RTC_Wakeup_GetReload ( NSS_RTC_T pRTC)

Returns the number of "wake-up down-counter" ticks (seconds) previously set by Chip_RTC_Wakeup_SetReload

Parameters
pRTC: The base address of the RTC peripheral on the chip
Returns
24bit unsigned value of the number of ticks
Note
This function does not return remaining ticks to a 'wake-up' event.
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_Wakeup_GetRemaining()

int Chip_RTC_Wakeup_GetRemaining ( NSS_RTC_T pRTC)

Returns the remaining ("wake-up down-counter") ticks until 'wake-up' event occurs

Parameters
pRTC: The base address of the RTC peripheral on the chip
Returns
24bit unsigned value of the remaining number of ticks to a 'wake-up' event
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_Wakeup_IsRunning()

bool Chip_RTC_Wakeup_IsRunning ( NSS_RTC_T pRTC)

Indicates whether or not the "wake-up-down-counter" is in fact running

Parameters
pRTC: The base address of the RTC peripheral on the chip
Returns
true if it is running or false otherwise.
Warning
This function performs synchronized register accesses. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_Time_GetValue()

int Chip_RTC_Time_GetValue ( NSS_RTC_T pRTC)

Returns the current 'tick' value of the "time up-counter"

Parameters
pRTC: The base address of the RTC peripheral on the chip
Returns
Current ticks since the TFRO clock was enabled (unless updated via Chip_RTC_Time_SetValue).
Note
Note that HW returns 'tick' in 32bit of unsigned magnitude, type-casted and returned as signed 'int' in Chip_RTC_Time_GetValue
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_Time_SetValue()

void Chip_RTC_Time_SetValue ( NSS_RTC_T pRTC,
int  tickValue 
)

Sets a new 'tick' value to the "time up-counter". When using as an epoch, the number of seconds since that epoch can be written to the "time up-counter", so that it maintains the current date/time.

Parameters
pRTC: The base address of the RTC peripheral on the chip
tickValuetick value to assign to "time up-counter". This value will be type-casted as unsigned 32-bit then applied to HW registers
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_Int_SetEnabledMask()

void Chip_RTC_Int_SetEnabledMask ( NSS_RTC_T pRTC,
RTC_INT_T  mask 
)

Enables/Disables the RTC interrupts.

Parameters
pRTC: The base address of the RTC block on the chip
mask: Interrupt enabled mask to set
Note
Interrupt MUST be enabled to wake up from Sleep/Deep Sleep states
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_Int_GetEnabledMask()

RTC_INT_T Chip_RTC_Int_GetEnabledMask ( NSS_RTC_T pRTC)

Retrieves the RTC interrupt enabled mask.

Parameters
pRTC: base address of the RTC block on chip.
Returns
Interrupt enabled mask
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_Int_GetRawStatus()

RTC_INT_T Chip_RTC_Int_GetRawStatus ( NSS_RTC_T pRTC)

Retrieves a bitVector with the RAW RTC interrupt flags

Parameters
pRTC: The base address of the RTC peripheral on the chip
Returns
BitVector with the RTC RAW interrupt flags
Note
A bit set to 1 means that the correspondent interrupt flag is set.
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.

◆ Chip_RTC_Int_ClearRawStatus()

void Chip_RTC_Int_ClearRawStatus ( NSS_RTC_T pRTC,
RTC_INT_T  flags 
)

Clears the required RTC interrupt flags.

Parameters
pRTC: The base address of the RTC peripheral on the chip
flags: Bitvector indicating which interrupt flags to clear
Warning
This function performs a synchronized register access. Impact on runtime performance and other same and lower-priority contexts should be carefully considered. See warning section.