GRTC driver

group nrfx_grtc

Global Real Timer Counter (GRTC) peripheral driver.

Defines

NRFX_GRTC_SLEEP_DEFAULT_CONFIG

GRTC sleep default configuration.

This configuration sets up GRTC with the following options:

  • sleep timeout: 5 LFCLK cycles

  • wake time: 4 LFCLK cycles

  • automatic mode: true

Typedefs

typedef void (*nrfx_grtc_cc_handler_t)(int32_t id, uint64_t cc_value, void *p_context)

GRTC driver instance compare handler type.

Param id:

[in] Channel ID.

Param cc_value:

[in] Compare value.

Param p_context:

[in] User context.

typedef void (*nrfx_grtc_syscountervalid_handler_t)(void *p_context)

GRTC driver instance SYSCOUNTER valid handler type.

Param p_context:

[in] User context.

typedef void (*nrfx_grtc_rtcomparesync_handler_t)(void *p_context)

GRTC driver instance RTCOMPARESYNC handler type.

Param p_context:

[in] User context.

Enums

enum nrfx_grtc_action_t

GRTC action types.

Values:

enumerator NRFX_GRTC_ACTION_START

Start the GRTC.

enumerator NRFX_GRTC_ACTION_STOP

Stop the GRTC.

enumerator NRFX_GRTC_ACTION_CLEAR

Clear the GRTC.

enum nrfx_grtc_cc_relative_reference_t

GRTC compare event relative references.

Values:

enumerator NRFX_GRTC_CC_RELATIVE_SYSCOUNTER

The SYSCOUNTER content will be used as the reference.

enumerator NRFX_GRTC_CC_RELATIVE_COMPARE

The corresponding compare register content will be used as the reference.

Functions

nrfx_err_t nrfx_grtc_sleep_configure(nrfx_grtc_sleep_config_t const *p_sleep_cfg)

Function for configuring the SYSCOUNTER sleep feature.

Parameters:

  • p_sleep_cfg – [in] Pointer to the configuration sleep structure.

Return values:

  • NRFX_SUCCESS – The procedure was successful.

  • NRFX_ERROR_NOT_SUPPORTED – The sleep feature is not supported.

nrfx_err_t nrfx_grtc_sleep_configuration_get(nrfx_grtc_sleep_config_t *p_sleep_cfg)

Function for getting the SYSCOUNTER sleep configuration.

Parameters:

  • p_sleep_cfg – [out] Pointer to the structure to be filled with sleep configuration.

Return values:

  • NRFX_SUCCESS – The procedure was successful.

  • NRFX_ERROR_NOT_SUPPORTED – The sleep feature is not supported.

nrfx_err_t nrfx_grtc_channel_alloc(uint8_t *p_channel)

Function for allocating the GRTC capture/compare channel.

Note

Function is thread safe as it uses nrfx_flag32_alloc.

Note

Routines that allocate and free the GRTC channels are independent from the rest of the driver. In particular, the driver does not need to be initialized when this function is called.

Parameters:

  • p_channel – [out] Pointer to the capture/compare channel.

Return values:

  • NRFX_SUCCESS – Allocation was successful.

  • NRFX_ERROR_NO_MEM – No resource available.

nrfx_err_t nrfx_grtc_channel_free(uint8_t channel)

Function for freeing the GRTC capture/compare channel.

Note

Function is thread safe as it uses nrfx_flag32_free.

Note

Routines that allocate and free the GRTC channels are independent from the rest of the driver. In particular, the driver does not need to be initialized when this function is called.

Note

This function also mark specified channel as unused by the driver.

Parameters:

  • channel – [in] Allocated channel to be freed.

Return values:

  • NRFX_SUCCESS – Allocation was successful.

  • NRFX_ERROR_FORBIDDEN – The domain is not allowed to use specified channel.

  • NRFX_ERROR_INVALID_PARAM – Channel is not allocated.

bool nrfx_grtc_is_channel_used(uint8_t channel)

Function for checking whether the specified channel is used by the driver.

Note

Channels marked as used cannot be utilized by external API.

Parameters:

  • channel – [in] Channel to be checked.

Return values:

  • true – Channel is used by the driver.

  • false – Channel is not used by the driver.

nrfx_err_t nrfx_grtc_init(uint8_t interrupt_priority)

Function for initializing the GRTC.

Parameters:

  • interrupt_priority – [in] Interrupt priority.

Return values:

  • NRFX_SUCCESS – Initialization was successful.

  • NRFX_ERROR_ALREADY – The driver is already initialized.

  • NRFX_ERROR_INVALID_STATE – The driver is already initialized. Deprecated - use NRFX_ERROR_ALREADY instead.

  • NRFX_ERROR_INTERNAL – No valid channel configuration provided.

nrfx_err_t nrfx_grtc_rtcounter_cc_disable(void)

Function for disabling the RTCOUNTER CC channel.

Return values:

  • NRFX_SUCCESS – The procedure was successful.

  • NRFX_ERROR_INTERNAL – The SYSCOUNTER (1 MHz) is running and the operation is not allowed.

  • NRFX_ERROR_TIMEOUT – RTCOUNTER compare interrupt is pending.

void nrfx_grtc_rtcomparesync_int_enable(nrfx_grtc_rtcomparesync_handler_t handler, void *p_context)

Function for enabling the RTCOMPARESYNC interrupt.

Parameters:

  • handler – [in] Handler provided by the user. May be NULL.

  • p_context – [in] User context.

void nrfx_grtc_rtcomparesync_int_disable(void)

Function for disabling the RTCOMPARESYNC interrupt.

nrfx_err_t nrfx_grtc_rtcounter_cc_absolute_set(nrfx_grtc_rtcounter_handler_data_t *handler_data, uint64_t val, bool enable_irq, bool sync)

Function for setting the absolute compare value for the RTCOUNTER.

Parameters:

  • handler_data – [in] Pointer to the handler data instance structure.

  • val – [in] Absolute value to be set in the compare register.

  • enable_irq – [in] True if interrupt is to be enabled, false otherwise.

  • sync – [in] True if the internal synchronization mechanism shall be used, false otherwise.

Return values:

  • NRFX_SUCCESS – The procedure was successful.

  • NRFX_ERROR_INTERNAL – The SYSCOUNTER (1 MHz) is running and the operation is not allowed.

void nrfx_grtc_rtcounter_cc_int_enable(bool sync)

Function for enabling the RTCOUNTER compare interrupt.

Parameters:

  • sync – [in] True if the internal synchronization mechanism shall be used, false otherwise.

void nrfx_grtc_rtcounter_cc_int_disable(void)

Function for disabling the RTCOUNTER compare interrupt.

void nrfx_grtc_syscountervalid_int_enable(nrfx_grtc_syscountervalid_handler_t handler, void *p_context)

Function for enabling the SYSCOUNTERVALID interrupt.

Parameters:

  • handler – [in] Handler provided by the user. May be NULL.

  • p_context – [in] User context.

void nrfx_grtc_syscountervalid_int_disable(void)

Function for disabling the SYSCOUNTERVALID interrupt.

nrfx_err_t nrfx_grtc_syscounter_start(bool busy_wait, uint8_t *p_main_cc_channel)

Function for starting the 1 MHz SYSCOUNTER.

Note

This function automatically allocates and marks as used the special-purpose main capture/compare channel. It is available only for GRTC manager.

Note

Use auxiliary structure of type nrfx_grtc_channel_t when working with SYSCOUNTER.

Parameters:

  • busy_wait – [in] True if wait for synchronization operation is to be performed, false otherwise.

  • p_main_cc_channel – [out] Pointer to the main capture/compare channel.

Return values:

  • NRFX_SUCCESS – Starting was successful.

  • NRFX_ERROR_NO_MEM – No resource available to allocate main channel.

  • NRFX_ERROR_ALREADY – The GRTC is already running.

nrfx_err_t nrfx_grtc_action_perform(nrfx_grtc_action_t action)

Function for performing an action for the GRTC.

Parameters:

  • action – [in] Action to be performed.

Return values:

  • NRFX_SUCCESS – Starting was successful.

  • NRFX_ERROR_INTERNAL – The SYSCOUNTER (1 MHz) is running and the operation is not allowed.

void nrfx_grtc_uninit(void)

Function for uninitializing the GRTC.

Note

This function automatically frees all channels used by the driver. It also marks these channels as unused

bool nrfx_grtc_init_check(void)

Function for checking if the GRTC driver is initialized.

Return values:

  • true – Driver is already initialized.

  • false – Driver is not initialized.

nrfx_err_t nrfx_grtc_syscounter_cc_disable(uint8_t channel)

Function for disabling the SYSCOUNTER CC channel.

Note

This function marks the specified channel as unused.

Parameters:

  • channel – [in] Channel to be disabled.

Return values:

  • NRFX_SUCCESS – The procedure was successful.

  • NRFX_ERROR_FORBIDDEN – The domain is not allowed to use specified channel.

  • NRFX_ERROR_INVALID_PARAM – The specified channel is either not allocated or marked as unused.

  • NRFX_ERROR_INTERNAL – The SYSCOUNTER (1 MHz) is not running.

  • NRFX_ERROR_TIMEOUT – SYSCOUNTER compare interrupt is pending on the requested channel.

nrfx_err_t nrfx_grtc_syscounter_cc_absolute_set(nrfx_grtc_channel_t *p_chan_data, uint64_t val, bool enable_irq)

Function for setting the absolute compare value for the SYSCOUNTER.

Note

This function marks the specified channel as used.

Parameters:

  • p_chan_data – [in] Pointer to the channel data instance structure.

  • val – [in] Absolute value to be set in the compare register.

  • enable_irq – [in] True if interrupt is to be enabled, false otherwise.

Return values:

  • NRFX_SUCCESS – The procedure was successful.

  • NRFX_ERROR_FORBIDDEN – The domain is not allowed to use specified channel.

  • NRFX_ERROR_INVALID_PARAM – Channel is not allocated.

  • NRFX_ERROR_INTERNAL – The SYSCOUNTER (1 MHz) is not running.

nrfx_err_t nrfx_grtc_syscounter_cc_relative_set(nrfx_grtc_channel_t *p_chan_data, uint32_t val, bool enable_irq, nrfx_grtc_cc_relative_reference_t reference)

Function for setting the relative compare value for the SYSCOUNTER.

Note

This function marks the specified channel as used.

Parameters:

  • p_chan_data – [in] Pointer to the channel data instance structure.

  • val – [in] Relative value to be set in the compare register.

  • enable_irq – [in] True if interrupt is to be enabled, false otherwise.

  • reference – [in] Reference type to be used.

Return values:

  • NRFX_SUCCESS – The procedure was successful.

  • NRFX_ERROR_FORBIDDEN – The domain is not allowed to use specified channel.

  • NRFX_ERROR_INVALID_PARAM – Channel is not allocated.

  • NRFX_ERROR_INTERNAL – The SYSCOUNTER (1 MHz) is not running.

nrfx_err_t nrfx_grtc_syscounter_cc_int_disable(uint8_t channel)

Function for disabling the SYSCOUNTER compare interrupt.

Parameters:

  • channel – [in] Compare channel number.

Return values:

  • NRFX_SUCCESS – The procedure was successful.

  • NRFX_ERROR_FORBIDDEN – The domain is not allowed to use specified channel.

  • NRFX_ERROR_INVALID_PARAM – The specified channel is either not allocated or marked as unused.

  • NRFX_ERROR_INTERNAL – The SYSCOUNTER (1 MHz) is not running.

nrfx_err_t nrfx_grtc_syscounter_cc_int_enable(uint8_t channel)

Function for enabling the SYSCOUNTER compare interrupt.

Note

This function marks the specified channel as used.

Parameters:

  • channel – [in] Compare channel number.

Return values:

  • NRFX_SUCCESS – The procedure was successful.

  • NRFX_ERROR_FORBIDDEN – The domain is not allowed to use specified channel.

  • NRFX_ERROR_INVALID_PARAM – Channel is not allocated.

  • NRFX_ERROR_INTERNAL – The SYSCOUNTER (1 MHz) is not running.

bool nrfx_grtc_syscounter_cc_int_enable_check(uint8_t channel)

Function for checking whether the SYSCOUNTER compare interrupt is enabled for the specified channel.

Parameters:

  • channel – [in] Compare channel number.

Return values:

  • true – The interrupt is enabled for the specified channel.

  • false – The interrupt is disabled for the specified channel.

nrfx_err_t nrfx_grtc_syscounter_capture(uint8_t channel)

Function for triggering the SYSCOUNTER capture task.

Note

This function marks the specified channel as used.

Parameters:

  • channel – [in] Capture channel number.

Return values:

  • NRFX_SUCCESS – The procedure was successful.

  • NRFX_ERROR_FORBIDDEN – The domain is not allowed to use specified channel.

  • NRFX_ERROR_INVALID_PARAM – Channel is not allocated.

  • NRFX_ERROR_INTERNAL – The SYSCOUNTER (1 MHz) is not running.

nrfx_err_t nrfx_grtc_syscounter_cc_value_read(uint8_t channel, uint64_t *p_val)

Function for reading the GRTC capture/compare register for the specified channel.

Parameters:

  • channel – [in] Capture channel number.

  • p_val – [out] Pointer to the variable where the result is to be stored.

Return values:

  • NRFX_SUCCESS – The procedure was successful.

  • NRFX_ERROR_FORBIDDEN – The domain is not allowed to use specified channel.

  • NRFX_ERROR_INVALID_PARAM – The specified channel is either not allocated or marked as unused.

  • NRFX_ERROR_INTERNAL – The SYSCOUNTER (1 MHz) is not running.

void nrfx_grtc_active_request_set(bool active)

Function for requesting the SYSCOUNTER state.

Note

By using this function any domain can prevent SYSCOUNTER from going to sleep state.

Parameters:

  • active – [in] True if SYSCOUNTER is to be always kept active, false otherwise.

nrfx_err_t nrfx_grtc_syscounter_get(uint64_t *p_counter)

Function for reading the GRTC SYSCOUNTER value.

Parameters:

  • p_counter – [out] p_counter Pointer to the variable to be filled with the SYSCOUNTER value.

Return values:

  • NRFX_SUCCESS – The procedure was successful.

  • NRFX_ERROR_INTERNAL – The SYSCOUNTER (1 MHz) is not running.

NRFX_STATIC_INLINE uint32_t nrfx_grtc_task_address_get(nrf_grtc_task_t task)

Function for retrieving the address of the specified GRTC task.

Parameters:

  • task – [in] GRTC task.

Returns:

Task address.

NRFX_STATIC_INLINE uint32_t nrfx_grtc_event_address_get(nrf_grtc_event_t event)

Function for retrieving the address of the specified GRTC event.

Parameters:

  • event – [in] GRTC event.

Returns:

Event address.

NRFX_STATIC_INLINE uint32_t nrfx_grtc_capture_task_address_get(uint8_t channel)

Function for retrieving the address of the capture task for the specified channel.

Parameters:

  • channel – [in] Capture channel number.

Returns:

Task address.

NRFX_STATIC_INLINE uint32_t nrfx_grtc_event_compare_address_get(uint8_t channel)

Function for retrieving the address of the capture task for the specified channel.

Parameters:

  • channel – [in] Compare channel number.

Returns:

Event address.

NRFX_STATIC_INLINE bool nrfx_grtc_sys_counter_cc_enable_check(uint8_t channel)

Function for checking whether the specified capture/compare channel is enabled.

Parameters:

  • channel – [in] Channel to be checked.

Return values:

  • true – Channel is enabled.

  • false – Channel is disabled.

NRFX_STATIC_INLINE bool nrfx_grtc_syscounter_compare_event_check(uint8_t channel)

Function for retrieving the state of the compare GRTC event.

Parameters:

  • channel – [in] Compare channel of the corresponding event to be checked.

Return values:

  • true – The event has been generated.

  • false – The event has not been generated.

NRFX_STATIC_INLINE uint64_t nrfx_grtc_rtcounter_get(void)

Function for reading the GRTC RTCOUNTER value.

Returns:

RTCOUNTER (32 kHz) value.

NRFX_STATIC_INLINE void nrfx_grtc_clock_source_set(nrf_grtc_clksel_t clk_src)

Function for setting the clock source for the GRTC low-frequency clock.

Parameters:

  • clk_src – [in] Selected clock source.

struct nrfx_grtc_channel_t
#include <nrfx_grtc.h>

GRTC capture/compare channel description structure.

Public Members

nrfx_grtc_cc_handler_t handler

User handler.

void *p_context

User context.

uint8_t channel

Capture/compare channel number.

struct nrfx_grtc_rtcounter_handler_data_t
#include <nrfx_grtc.h>

GRTC RTCOUNTER handler data structure.

Public Members

nrfx_grtc_cc_handler_t handler

User handler.

void *p_context

User context.

struct nrfx_grtc_sleep_config_t
#include <nrfx_grtc.h>

GRTC SYSCOUNTER sleep configuration structure.

Public Members

uint32_t timeout

Delay in LFCLK cycles after the condition allowing SYSCOUNTER to go to sleep is met.

uint32_t waketime

Number of LFCLK cycles to wakeup the SYSCOUNTER before the wake-up event occured.

bool auto_mode

Enable automatic mode, which keeps the SYSCOUNTER active when any of the local CPUs is active.