| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Typedefs | Enumerations | Functions
Clock driver
Clock HAL and driver

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
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.
  MODULE_ALREADY_INITIALIZED | If the driver was already initialized.
  NRF_ERROR_SOFTDEVICE_NOT_ENABLED | If the SoftDevice was not enabled.

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.