Clock driver

nRF5 SDK v12.2.0
Modules | Data Structures | Typedefs | Enumerations | Functions

Driver for managing the low-frequency clock (LFCLK) and the high-frequency clock (HFCLK). More...

Modules

CLOCK peripheral driver configuration

Data Structures

struct nrf_drv_clock_handler_item_s

Typedefs

typedef void(* nrf_drv_clock_event_handler_t )( nrf_drv_clock_evt_type_t event)
Clock event handler. More...
typedef struct
nrf_drv_clock_handler_item_s 		nrf_drv_clock_handler_item_t

Enumerations

enum nrf_drv_clock_evt_type_t {
NRF_DRV_CLOCK_EVT_HFCLK_STARTED ,
NRF_DRV_CLOCK_EVT_LFCLK_STARTED ,
NRF_DRV_CLOCK_EVT_CAL_DONE ,
NRF_DRV_CLOCK_EVT_CAL_ABORTED
}
Clock events. More...

Functions

bool nrf_drv_clock_init_check (void)
Function for checking if driver is already initialized. More...
ret_code_t nrf_drv_clock_init (void)
Function for initializing the nrf_drv_clock module. More...
void nrf_drv_clock_uninit (void)
Function for uninitializing the clock module.
void nrf_drv_clock_lfclk_request ( nrf_drv_clock_handler_item_t *p_handler_item)
Function for requesting the LFCLK. More...
void nrf_drv_clock_lfclk_release (void)
Function for releasing the LFCLK. More...
bool nrf_drv_clock_lfclk_is_running (void)
Function for checking the LFCLK state. More...
void nrf_drv_clock_hfclk_request ( nrf_drv_clock_handler_item_t *p_handler_item)
Function for requesting the high-accuracy source HFCLK. More...
void nrf_drv_clock_hfclk_release (void)
Function for releasing the high-accuracy source HFCLK. More...
bool nrf_drv_clock_hfclk_is_running (void)
Function for checking the HFCLK state. More...
ret_code_t nrf_drv_clock_calibration_start (uint8_t delay, nrf_drv_clock_event_handler_t handler)
Function for starting a single calibration process. More...
ret_code_t nrf_drv_clock_calibration_abort (void)
Function for aborting calibration. More...
ret_code_t nrf_drv_clock_is_calibrating (bool *p_is_calibrating)
Function for checking if calibration is in progress. More...
__STATIC_INLINE uint32_t nrf_drv_clock_ppi_task_addr ( nrf_clock_task_t task)
Function for returning a requested task address for the clock driver module. More...
__STATIC_INLINE uint32_t nrf_drv_clock_ppi_event_addr ( nrf_clock_event_t event)
Function for returning a requested event address for the clock driver module. More...

Detailed Description

Driver for managing the low-frequency clock (LFCLK) and the high-frequency clock (HFCLK).

Typedef Documentation

typedef void(* nrf_drv_clock_event_handler_t)( nrf_drv_clock_evt_type_t event)

Clock event handler.

Parameters
[in] event Event.

Enumeration Type Documentation

enum nrf_drv_clock_evt_type_t

Clock events.

Enumerator
NRF_DRV_CLOCK_EVT_HFCLK_STARTED

HFCLK has been started.

NRF_DRV_CLOCK_EVT_LFCLK_STARTED

LFCLK has been started.

NRF_DRV_CLOCK_EVT_CAL_DONE

Calibration is done.

NRF_DRV_CLOCK_EVT_CAL_ABORTED

Calibration has been aborted.

Function Documentation

ret_code_t nrf_drv_clock_calibration_abort ( void )

Function for aborting calibration.

This function aborts on-going calibration. If calibration was started, it cannot be stopped. If a handler was provided by nrf_drv_clock_calibration_start , this handler will be called once aborted calibration is completed. nrf_drv_clock_is_calibrating can also be used to check if the system is calibrating.

Return values
NRF_SUCCESS If the procedure was successful.
NRF_ERROR_FORBIDDEN If a SoftDevice is present or the selected LFCLK source is not an RC oscillator.
ret_code_t nrf_drv_clock_calibration_start ( uint8_t delay ,
nrf_drv_clock_event_handler_t handler
)

Function for starting a single calibration process.

This function can also delay the start of calibration by a user-specified value. The delay will use a low-power timer that is part of the CLOCK module. nrf_drv_clock_is_calibrating can be called to check if calibration is still in progress. If a handler is provided, the user can be notified when calibration is completed. The ext calibration can be started from the handler context.

The calibration process consists of three phases:

  • Delay (optional)
  • Requesting the high-accuracy HFCLK
  • Hardware-supported calibration
Parameters
[in] delay Time after which the calibration will be started (in 0.25 s units).
[in] handler NULL or user function to be called when calibration is completed or aborted.
Return values
NRF_SUCCESS If the procedure was successful.
NRF_ERROR_FORBIDDEN If a SoftDevice is present or the selected LFCLK source is not an RC oscillator.
NRF_ERROR_INVALID_STATE If the low-frequency clock is off.
NRF_ERROR_BUSY If calibration is in progress.
bool nrf_drv_clock_hfclk_is_running ( void )

Function for checking the HFCLK state.

Return values
true If the HFCLK is running (for nRF5 XTAL source).
false If the HFCLK is not running.
void nrf_drv_clock_hfclk_release ( void )

Function for releasing the high-accuracy source HFCLK.

If there are no more requests, the high-accuracy source will be released.

void nrf_drv_clock_hfclk_request ( nrf_drv_clock_handler_item_t * p_handler_item )

Function for requesting the high-accuracy source HFCLK.

The high-accuracy source can be requested by different modules or contexts. The driver ensures that the high-accuracy clock will be started only when it is requested the first time. If the clock is not ready but it was already started, the handler item that is provided as an input parameter is added to the list of handlers that will be notified when the clock is started.

If an event handler is provided, it will be called once the clock is started. If the clock was already started at this time, the event handler will be called from the context of this function. Additionally, the nrf_drv_clock_hfclk_is_running function can be polled to check if the clock has started.

Note
If a SoftDevice is running, the clock is managed by the SoftDevice and all requests are handled by the SoftDevice. This function cannot be called from all interrupt priority levels in that case.
The handler item provided by the user cannot be an automatic variable.
Parameters
[in] p_handler_item A pointer to the event handler structure.
ret_code_t nrf_drv_clock_init ( void )

Function for initializing the nrf_drv_clock module.

After initialization, the module is in power off state (clocks are not requested).

Return values
NRF_SUCCESS If the procedure was successful.
NRF_ERROR_MODULE_ALREADY_INITIALIZED If the driver was already initialized.
bool nrf_drv_clock_init_check ( void )

Function for checking if driver is already initialized.

This function is used to check whatever common POWER_CLOCK common interrupt should be disabled or not if POWER driver tries to disable the interrupt.

Return values
true Driver is initialized
false Driver is uninitialized
ret_code_t nrf_drv_clock_is_calibrating ( bool * p_is_calibrating )

Function for checking if calibration is in progress.

This function indicates that the system is in calibration if it is in any of the calibration process phases (see nrf_drv_clock_calibration_start ).

Parameters
[out] p_is_calibrating True if calibration is in progress, false if not.
Return values
NRF_SUCCESS If the procedure was successful.
NRF_ERROR_FORBIDDEN If a SoftDevice is present or the selected LFCLK source is not an RC oscillator.
bool nrf_drv_clock_lfclk_is_running ( void )

Function for checking the LFCLK state.

Return values
true If the LFCLK is running.
false If the LFCLK is not running.
void nrf_drv_clock_lfclk_release ( void )

Function for releasing the LFCLK.

If there are no more requests, the LFCLK source will be stopped.

Note
When a SoftDevice is enabled, the LFCLK is always running.
void nrf_drv_clock_lfclk_request ( nrf_drv_clock_handler_item_t * p_handler_item )

Function for requesting the LFCLK.

The low-frequency clock can be requested by different modules or contexts. The driver ensures that the clock will be started only when it is requested the first time. If the clock is not ready but it was already started, the handler item that is provided as an input parameter is added to the list of handlers that will be notified when the clock is started. If the clock is already enabled, user callback is called from the current context.

The first request will start the selected LFCLK source. If an event handler is provided, it will be called once the LFCLK is started. If the LFCLK was already started at this time, the event handler will be called from the context of this function. Additionally, the nrf_drv_clock_lfclk_is_running function can be polled to check if the clock has started.

Note
When a SoftDevice is enabled, the LFCLK is always running and the driver cannot control it.
The handler item provided by the user cannot be an automatic variable.
Parameters
[in] p_handler_item A pointer to the event handler structure.
__STATIC_INLINE uint32_t nrf_drv_clock_ppi_event_addr ( nrf_clock_event_t event )

Function for returning a requested event address for the clock driver module.

Parameters
[in] event One of the peripheral events.
Returns
Event address.
__STATIC_INLINE uint32_t nrf_drv_clock_ppi_task_addr ( nrf_clock_task_t task )

Function for returning a requested task address for the clock driver module.

Parameters
[in] task One of the peripheral tasks.
Returns
Task address.