Clock Manager#

Overview#

Clock Manager is a platform-level software module that manages the device's oscillators and clock tree. The Clock Manager module is split into two main parts: The Initialization part and the Runtime part. The runtime part has its component clock_manager_runtime and can be used independently from the initialization part. The clock_manager component includes both the initialization part and the runtime part and it should be the component added to your project slcp file.

Initialization#

The initialization part includes the configuration files sl_clock_manager_oscillator_config.h and sl_clock_manager_tree_config.h. As their name indicates, those C header files are used to configure the different device oscillators and the device clock tree. Those header files use the CMSIS Configuration Wizard Annotations and are specific to each device. The API function sl_clock_manager_init() is used to initialize the Clock Manager module based on the configuration values specified in the two configuration files. This function must be called early during your initialization sequence. If the SL System component (System Initialization and Action Processing) is used by your application, the sl_clock_manager_init() call will be added automatically to your initialization sequence.

Oscillators Configuration#

Oscillators' configurations are all grouped in the sl_clock_manager_oscillator_config.h file. Crystal-based oscillators, HFXO and LFXO, have an enable/disable configuration to indicate if the required crystal is present or not. In the absence of the required crystal, the configuration must be disabled and the associated oscillator will not be initialized.

The HFXO configuration also provides the configuration for the Crystal Sharing feature when supported by the device. This feature allows to use the dedicated HFCLKOUT pin to output a sinusoidal clock that can be used as the HFXO input for another EFR device. In the configuration, you need to specify if your device is the leader or the follower. The leader will be the one outputting the clock and the follower, the one receiving the clock signal. In the leader configuration, the GPIO pin is used to receive the request from the follower. You can refer to your device datasheet to know the available location for the HFXO BUFOUT_REQ pin. In the follower mode, the pin configuration can be used to send an HFXO request signal to the leader. The "High Frequency Clock Ouput" section of your device reference manual also provides more details about this feature.

The first HFRCO module, whose output clock is called HFRCODPLL, can be connected to the DPLL module to have a better precision clock. When the DPLL is enabled through the configuration define SL_CLOCK_MANAGER_HFRCO_DPLL_EN, the DPLL settings take precedence over the HFRCO band configuration.

Clock Tree Configuration#

The device clock tree configurations are all grouped in the sl_clock_manager_tree_config.h file. Refer to your device's reference manual for the clock tree diagram and see which peripherals are connected to which clock branches. In the configuration file, each clock branch can be independently configured. However, to facilitate the clock setup for users, two additional configurations were added: SL_CLOCK_MANAGER_DEFAULT_HF_CLOCK_SOURCE and SL_CLOCK_MANAGER_DEFAULT_LF_CLOCK_SOURCE. Those configurations allow the selection of the default high-frequency and low-frequency oscillators to be used inside the clock tree. Every clock branch that can benefit from those default selections will use them by default. On certain devices, the Power Manager module offers an Execution Modes feature with the SL_POWER_MANAGER_EXECUTION_MODES_FEATURE_EN configuration. When this feature is enabled, the SL_CLOCK_MANAGER_SYSCLK_SOURCE configuration could be overriden by the Execution Modes feature. Refer to the description of SL_CLOCK_MANAGER_SYSCLK_SOURCE in sl_clock_manager_tree_config.h file to know if this is the case.

Some peripherals have an internal clock divider. Those are not handled by the Clock Manager configuration. The peripheral driver will usually expose the divider configuration when such a divider is present inside the peripheral module.

The Clock tree configuration is available at compile-time only. The Clock Manager module does not offer API functions to manipulate the clock tree at runtime.

The more oscillators are used by different clock branches the more power consumption you will have. To limit your power consumption, you can try to limit the number of oscillators used. So for example, only use one High-frequency oscillator and one Low-frequency oscillator across the clock tree. However, if the application is radio-based, the HFXO oscillator is mandatory for the Radio clock branch and if the Radio clock branch is connected to the SYSCLK branch, this will limit you to use HFXO for SYSCLK as well. In this specific case, SYSCLK could also be configured to use HFRCO with DPLL, but the chosen frequency must be two times the HFXO frequency so that the Radio module can retrieve the HF crystal frequency with its divider. This will also come with an increase in power consumption since both HFXO and HFRCO oscillators will be used. Refer to your device reference manual to know if your Radio clock is connected to the SYSCLK clock branch or not.

Note

• The Clock Manager Initialization is incompatible with the device_init_clocks (Clock Initialization), device_init_hfxo (HFXO Initialization), device_init_hfrco (HFRCO Initialization) device_init_dpll (DPLL Initialization), device_init_rffpll (RFFPLL Initialization), device_init_usbpll (USB PLL Initialization), device_init_lfxo (LFXO Initialization) and device_init_lfrco (LFRCO Initialization) components. This does not mean that the device_init component (Device Initialization) is incompatible with the clock_manager component. The device_init component can pull other initialization modules like EMU and DCDC that are not related to clocks. Therefore, both device_init and clock_manager should be present in your project file. SLC will take care of pulling only the sub device_init_xxx components that are needed.

The runtime part, which is associated with the clock_manager_runtime component, has also an initialization function of its own, sl_clock_manager_runtime_init(). This function must also be part of the initialization sequence. If the SL System component (System Initialization and Action Processing) is used by your application, the sl_clock_manager_runtime_init() call will be added automatically to your initialization sequence.

Functionalities#

The Runtime part includes functionalities related to oscillators, clock tree and the CMU hardware module features. The main functionalities are:

• Retrieving the frequency or precision of an oscillator or clock branch

• Enabling/Disabling modules' bus clock

• Retrieving or setting calibration values for oscillators

• Exporting clocks to GPIO

• Starting an RCO Calibration process based on a reference clock source

Retrieve the frequency or precision of an oscillator or clock branch#

API functions sl_clock_manager_get_oscillator_frequency() and sl_clock_manager_get_oscillator_precision() allow retrieving respectively the frequency and precision of a given oscillator. Similar functions exist for clock branches: sl_clock_manager_get_clock_branch_frequency() and sl_clock_manager_get_clock_branch_precision().

To retrieve the frequency or precision of a specific peripheral, you will first need to retrieve to which clock branch this peripheral is connected. To do so, the Device Manager and its Device Abstraction Peripheral can be used. The below code example shows how to retrieve the clock branch of the TIMER0 peripheral.

#include "sl_clock_manager.h"
#include "sl_device_peripheral.h"

sl_status_t status;
uint32_t freq;
sl_clock_branch_t clock_branch;

clock_branch = sl_device_peripheral_get_clock_branch(SL_PERIPHERAL_TIMER0);
status = sl_clock_manager_get_clock_branch_frequency(clock_branch, &freq);

Enable/Disable modules' bus clock#

Before accessing a peripheral's register interface, its bus clock must be enabled, or else a bus fault exception will be triggered. API functions sl_clock_manager_enable_bus_clock() and sl_clock_manager_disable_bus_clock() allow to perform such operations.

Note that the peripheral clock will automatically be enabled when a peripheral is enabled with the clock on-demand feature.

Oscillator Calibration#

The Clock Manager initialization, if present, will calibrate the different oscillators during the initialization sequence, but sometimes calibration values must be updated during runtime in certain conditions, for example, if the device temperature changes too much. This is considered an advanced functionality and users must be careful as to when to use this functionality.

API functions sl_clock_manager_set_rc_oscillator_calibration() and sl_clock_manager_get_rc_oscillator_calibration() allow to set or get the CAL register of HFRCO and LFRCO oscillators. Not all devices have an LFRCO module with a CAL register. Some LFRCO modules will have a high-precision configuration allowing to use the HFXO to auto-calibrate the LFRCO. Refer to your device reference manual to retrieve oscillator specifications.

API functions sl_clock_manager_set_hfxo_calibration() and sl_clock_manager_get_hfxo_calibration() allow to set or get the COREBIASANA inside the HFXO XTALCTRL register. The HFXO module has a Core Bias Optimization stage at the end of the oscillator startup sequence that allows to further optimize current consumption. This optimization will automatically set the COREBIASANA bitfield when finished. Upon reset, this optimization will run the first time HFXO is started and afterwards, the XTALCTRL->SKIPCOREBIASOPT bit will automatically be set so that next time HFXO is started during the application lifetime, the optimization stage will be skipped. This optimization stage takes a while to run, in the order of hundreds of milliseconds, therefore we don't want it to run each time HFXO is started. With the function sl_clock_manager_set_hfxo_calibration() it is possible to manually set the COREBIASANA bitfield and set the SKIPCOREBIASOPT bit. This function will usually be used in the context of an EM4 wake-up where to save on the initialization sequence time, we want to skip the Core Bias Optimization stage and manually set the value that would have previously been retrieved with sl_clock_manager_get_hfxo_calibration() and saved in an EM4 retained memory. In this context, sl_clock_manager_set_hfxo_calibration() will need to be called early in the initialization sequence, before the usual clock initialization function.

slx_clock_manager_hfxo_set_ctune(), slx_clock_manager_hfxo_get_ctune() and slx_clock_manager_hfxo_calibrate_ctune() functions allow to manipulate the HFXO tuning capacitances. Changing the CTUNE value while HFXO is running can result in significant clock glitches for one clock period. Therefore, those functions should be used with caution. The difference between the slx_clock_manager_hfxo_set_ctune() and slx_clock_manager_hfxo_calibrate_ctune() functions is that the calibration one will also start and wait for the HFXO Core Bias Optimization stage to complete.

API functions sl_clock_manager_set_lfxo_calibration() and sl_clock_manager_get_lfxo_calibration() allow to set and get the LFXO CTUNE value.

Export clocks to GPIO#

The CMU module offers the functionality to export a given clock source to a GPIO pin. Refer to function sl_clock_manager_set_gpio_clock_output() for more details and the sl_clock_manager_export_clock_source_t enum for a list of acceptable clock sources. Note that there is a specific clock branch named EXPCLK that is usually connected to the SYSCLK and offers an additional divider.

RCO Calibration#

The CMU module also offers RCO Calibration hardware support. This can be used to calibrate at runtime HFRCO and LFRCO oscillators using a high-precision reference clock. Refer to your device reference manual for more details about this functionality. API function sl_clock_manager_configure_rco_calibration() can be used to configure the calibration process. Then sl_clock_manager_start_rco_calibration() and sl_clock_manager_stop_rco_calibration() can be called to start/stop the process. sl_clock_manager_wait_rco_calibration() function can be called to actively wait for the process to finish. And finally, sl_clock_manager_get_rco_calibration_count() can be called to retrieve the calibration process result.