@web-font-path: "roboto-debian.css";
Clock Management API. More...
Typedefs | |
typedef enum clock_num_rp2040 | clock_num_t |
Clock numbers on RP2040 (used as typedef clock_num_t) | |
typedef enum clock_dest_num_rp2040 | clock_dest_num_t |
Clock destination numbers on RP2040 (used as typedef clock_dest_num_t) | |
typedef void(* | resus_callback_t) (void) |
Resus callback function type. | |
Functions | |
bool | clock_configure (clock_handle_t clock, uint32_t src, uint32_t auxsrc, uint32_t src_freq, uint32_t freq) |
Configure the specified clock with automatic clock divisor setup. | |
void | clock_configure_undivided (clock_handle_t clock, uint32_t src, uint32_t auxsrc, uint32_t src_freq) |
Configure the specified clock to use the undivided input source. | |
void | clock_configure_int_divider (clock_handle_t clock, uint32_t src, uint32_t auxsrc, uint32_t src_freq, uint32_t int_divider) |
Configure the specified clock to use the undivided input source. | |
void | clock_stop (clock_handle_t clock) |
Stop the specified clock. | |
uint32_t | clock_get_hz (clock_handle_t clock) |
Get the current frequency of the specified clock. | |
uint32_t | frequency_count_khz (uint src) |
Measure a clocks frequency using the Frequency counter. | |
void | clock_set_reported_hz (clock_handle_t clock, uint hz) |
Set the "current frequency" of the clock as reported by clock_get_hz without actually changing the clock. | |
void | clocks_enable_resus (resus_callback_t resus_callback) |
Enable the resus function. Restarts clk_sys if it is accidentally stopped. | |
void | clock_gpio_init_int_frac16 (uint gpio, uint src, uint32_t div_int, uint16_t div_frac16) |
Output an optionally divided clock to the specified gpio pin. | |
static void | clock_gpio_init_int_frac8 (uint gpio, uint src, uint32_t div_int, uint8_t div_frac8) |
Output an optionally divided clock to the specified gpio pin. | |
static void | clock_gpio_init (uint gpio, uint src, float div) |
Output an optionally divided clock to the specified gpio pin. | |
bool | clock_configure_gpin (clock_handle_t clock, uint gpio, uint32_t src_freq, uint32_t freq) |
Configure a clock to come from a gpio input. | |
void | set_sys_clock_48mhz (void) |
Initialise the system clock to 48MHz. | |
void | set_sys_clock_pll (uint32_t vco_freq, uint post_div1, uint post_div2) |
Initialise the system clock. | |
bool | check_sys_clock_hz (uint32_t freq_hz, uint *vco_freq_out, uint *post_div1_out, uint *post_div2_out) |
Check if a given system clock frequency is valid/attainable. | |
bool | check_sys_clock_khz (uint32_t freq_khz, uint *vco_freq_out, uint *post_div1_out, uint *post_div2_out) |
Check if a given system clock frequency is valid/attainable. | |
static bool | set_sys_clock_hz (uint32_t freq_hz, bool required) |
Attempt to set a system clock frequency in hz. | |
static bool | set_sys_clock_khz (uint32_t freq_khz, bool required) |
Attempt to set a system clock frequency in khz. | |
Clock Management API.
This API provides a high level interface to the clock functions.
The clocks block provides independent clocks to on-chip and external components. It takes inputs from a variety of clock sources allowing the user to trade off performance against cost, board area and power consumption. From these sources it uses multiple clock generators to provide the required clocks. This architecture allows the user flexibility to start and stop clocks independently and to vary some clock frequencies whilst maintaining others at their optimum frequencies
Please refer to the appropriate datasheet for more details on the RP-series clocks.
The clock source depends on which clock you are attempting to configure. The first table below shows main clock sources. If you are not setting the Reference clock or the System clock, or you are specifying that one of those two will be using an auxiliary clock source, then you will need to use one of the entries from the subsequent tables.
Main Clock Sources
Source | Reference Clock | System Clock |
---|---|---|
ROSC | CLOCKS_CLK_REF_CTRL_SRC_VALUE_ROSC_CLKSRC_PH | |
Auxiliary | CLOCKS_CLK_REF_CTRL_SRC_VALUE_CLKSRC_CLK_REF_AUX | CLOCKS_CLK_SYS_CTRL_SRC_VALUE_CLKSRC_CLK_SYS_AUX |
XOSC | CLOCKS_CLK_REF_CTRL_SRC_VALUE_XOSC_CLKSRC | |
Reference | CLOCKS_CLK_SYS_CTRL_SRC_VALUE_CLK_REF |
Auxiliary Clock Sources
The auxiliary clock sources available for use in the configure function depend on which clock is being configured. The following table describes the available values that can be used. Note that for clk_gpout[x], x can be 0-3.
Aux Source | clk_gpout[x] | clk_ref | clk_sys |
---|---|---|---|
System PLL | CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS | CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS | |
GPIO in 0 | CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0 | CLOCKS_CLK_REF_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0 | CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0 |
GPIO in 1 | CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1 | CLOCKS_CLK_REF_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1 | CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1 |
USB PLL | CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB | CLOCKS_CLK_REF_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB | CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB |
ROSC | CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_ROSC_CLKSRC | CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_ROSC_CLKSRC | |
XOSC | CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_XOSC_CLKSRC | CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_XOSC_CLKSRC | |
System clock | CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLK_SYS | ||
USB Clock | CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLK_USB | ||
ADC clock | CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLK_ADC | ||
RTC Clock | CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLK_RTC | ||
Ref clock | CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLK_REF |
Aux Source | clk_peri | clk_usb | clk_adc |
---|---|---|---|
System PLL | CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS | CLOCKS_CLK_USB_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS | CLOCKS_CLK_ADC_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS |
GPIO in 0 | CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0 | CLOCKS_CLK_USB_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0 | CLOCKS_CLK_ADC_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0 |
GPIO in 1 | CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1 | CLOCKS_CLK_USB_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1 | CLOCKS_CLK_ADC_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1 |
USB PLL | CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB | CLOCKS_CLK_USB_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB | CLOCKS_CLK_ADC_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB |
ROSC | CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_ROSC_CLKSRC_PH | CLOCKS_CLK_USB_CTRL_AUXSRC_VALUE_ROSC_CLKSRC_PH | CLOCKS_CLK_ADC_CTRL_AUXSRC_VALUE_ROSC_CLKSRC_PH |
XOSC | CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_XOSC_CLKSRC | CLOCKS_CLK_USB_CTRL_AUXSRC_VALUE_XOSC_CLKSRC | CLOCKS_CLK_ADC_CTRL_AUXSRC_VALUE_XOSC_CLKSRC |
System clock | CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_CLK_SYS |
Aux Source | clk_rtc |
---|---|
System PLL | CLOCKS_CLK_RTC_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS |
GPIO in 0 | CLOCKS_CLK_RTC_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0 |
GPIO in 1 | CLOCKS_CLK_RTC_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1 |
USB PLL | CLOCKS_CLK_RTC_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB |
ROSC | CLOCKS_CLK_RTC_CTRL_AUXSRC_VALUE_ROSC_CLKSRC_PH |
XOSC | CLOCKS_CLK_RTC_CTRL_AUXSRC_VALUE_XOSC_CLKSRC |
typedef void(* resus_callback_t) (void) |
Resus callback function type.
User provided callback for a resus event (when clk_sys is stopped by the programmer and is restarted for them).
Clock destination numbers on RP2040 (used as typedef clock_dest_num_t)
enum clock_num_rp2040 |
Clock numbers on RP2040 (used as typedef clock_num_t)
bool check_sys_clock_hz | ( | uint32_t | freq_hz, |
uint * | vco_freq_out, | ||
uint * | post_div1_out, | ||
uint * | post_div2_out ) |
Check if a given system clock frequency is valid/attainable.
freq_hz | Requested frequency |
vco_freq_out | On success, the voltage controlled oscillator frequency to be used by the SYS PLL |
post_div1_out | On success, The first post divider for the SYS PLL |
post_div2_out | On success, The second post divider for the SYS PLL. |
bool check_sys_clock_khz | ( | uint32_t | freq_khz, |
uint * | vco_freq_out, | ||
uint * | post_div1_out, | ||
uint * | post_div2_out ) |
Check if a given system clock frequency is valid/attainable.
freq_khz | Requested frequency |
vco_freq_out | On success, the voltage controlled oscillator frequency to be used by the SYS PLL |
post_div1_out | On success, The first post divider for the SYS PLL |
post_div2_out | On success, The second post divider for the SYS PLL. |
bool clock_configure | ( | clock_handle_t | clock, |
uint32_t | src, | ||
uint32_t | auxsrc, | ||
uint32_t | src_freq, | ||
uint32_t | freq ) |
Configure the specified clock with automatic clock divisor setup.
This method allows both the src_frequency of the input clock source AND the desired frequency to be specified, and will set the clock divider to achieve the exact or higher frequency achievable, with the maximum being the src_freq.
Note: The RP2040 clock hardware only supports divisors of exactly 1.0 or 2.0->16777216.0 in steps of 1/256
See the tables in the description for details on the possible values for clock sources.
clock | The clock to configure |
src | The main clock source, can be 0. |
auxsrc | The auxiliary clock source, which depends on which clock is being set. Can be 0 |
src_freq | Frequency of the input clock source |
freq | Requested frequency |
bool clock_configure_gpin | ( | clock_handle_t | clock, |
uint | gpio, | ||
uint32_t | src_freq, | ||
uint32_t | freq ) |
Configure a clock to come from a gpio input.
clock | The clock to configure |
gpio | The GPIO pin to run the clock from. Valid GPIOs are: 20 and 22. |
src_freq | Frequency of the input clock source |
freq | Requested frequency |
void clock_configure_int_divider | ( | clock_handle_t | clock, |
uint32_t | src, | ||
uint32_t | auxsrc, | ||
uint32_t | src_freq, | ||
uint32_t | int_divider ) |
Configure the specified clock to use the undivided input source.
See the tables in the description for details on the possible values for clock sources.
clock | The clock to configure |
src | The main clock source, can be 0. |
auxsrc | The auxiliary clock source, which depends on which clock is being set. Can be 0 |
src_freq | Frequency of the input clock source |
int_divider | an integer divider |
void clock_configure_undivided | ( | clock_handle_t | clock, |
uint32_t | src, | ||
uint32_t | auxsrc, | ||
uint32_t | src_freq ) |
Configure the specified clock to use the undivided input source.
See the tables in the description for details on the possible values for clock sources.
clock | The clock to configure |
src | The main clock source, can be 0. |
auxsrc | The auxiliary clock source, which depends on which clock is being set. Can be 0 |
src_freq | Frequency of the input clock source |
uint32_t clock_get_hz | ( | clock_handle_t | clock | ) |
Get the current frequency of the specified clock.
clock | Clock |
|
inlinestatic |
Output an optionally divided clock to the specified gpio pin.
gpio | The GPIO pin to output the clock to. Valid GPIOs are: 21, 23, 24, 25. These GPIOs are connected to the GPOUT0-3 clock generators. |
src | The source clock. See the register field CLOCKS_CLK_GPOUT0_CTRL_AUXSRC for a full list. The list is the same for each GPOUT clock generator. |
div | The float amount to divide the source clock by. This is useful to not overwhelm the GPIO pin with a fast clock. |
void clock_gpio_init_int_frac16 | ( | uint | gpio, |
uint | src, | ||
uint32_t | div_int, | ||
uint16_t | div_frac16 ) |
Output an optionally divided clock to the specified gpio pin.
gpio | The GPIO pin to output the clock to. Valid GPIOs are: 21, 23, 24, 25. These GPIOs are connected to the GPOUT0-3 clock generators. |
src | The source clock. See the register field CLOCKS_CLK_GPOUT0_CTRL_AUXSRC for a full list. The list is the same for each GPOUT clock generator. |
div_int | The integer part of the value to divide the source clock by. This is useful to not overwhelm the GPIO pin with a fast clock. This is in range of 1..2^24-1 on RP2040 and 1..2^16-1 on RP2350 |
div_frac16 | The fractional part of the value to divide the source clock by. This is in range of 0..65535 (/65536). |
|
inlinestatic |
Output an optionally divided clock to the specified gpio pin.
gpio | The GPIO pin to output the clock to. Valid GPIOs are: 21, 23, 24, 25. These GPIOs are connected to the GPOUT0-3 clock generators. |
src | The source clock. See the register field CLOCKS_CLK_GPOUT0_CTRL_AUXSRC for a full list. The list is the same for each GPOUT clock generator. |
div_int | The integer part of the value to divide the source clock by. This is useful to not overwhelm the GPIO pin with a fast clock. This is in range of 1..2^24-1 on RP2040 and 1..2^16-1 on RP2350 |
div_frac8 | The fractional part of the value to divide the source clock by. This is in range of 0..255 (/256). |
void clock_set_reported_hz | ( | clock_handle_t | clock, |
uint | hz ) |
Set the "current frequency" of the clock as reported by clock_get_hz without actually changing the clock.
void clock_stop | ( | clock_handle_t | clock | ) |
Stop the specified clock.
clock | The clock to stop |
void clocks_enable_resus | ( | resus_callback_t | resus_callback | ) |
Enable the resus function. Restarts clk_sys if it is accidentally stopped.
The resuscitate function will restart the system clock if it falls below a certain speed (or stops). This could happen if the clock source the system clock is running from stops. For example if a PLL is stopped.
resus_callback | a function pointer provided by the user to call if a resus event happens. |
uint32_t frequency_count_khz | ( | uint | src | ) |
Measure a clocks frequency using the Frequency counter.
Uses the inbuilt frequency counter to measure the specified clocks frequency. Currently, this function is accurate to +-1KHz. See the datasheet for more details.
void set_sys_clock_48mhz | ( | void | ) |
Initialise the system clock to 48MHz.
Set the system clock to 48MHz, and set the peripheral clock to match.
|
inlinestatic |
Attempt to set a system clock frequency in hz.
Note that not all clock frequencies are possible; it is preferred that you use src/rp2_common/hardware_clocks/scripts/vcocalc.py to calculate the parameters for use with set_sys_clock_pll
freq_hz | Requested frequency |
required | if true then this function will assert if the frequency is not attainable. |
|
inlinestatic |
Attempt to set a system clock frequency in khz.
Note that not all clock frequencies are possible; it is preferred that you use src/rp2_common/hardware_clocks/scripts/vcocalc.py to calculate the parameters for use with set_sys_clock_pll
freq_khz | Requested frequency |
required | if true then this function will assert if the frequency is not attainable. |
void set_sys_clock_pll | ( | uint32_t | vco_freq, |
uint | post_div1, | ||
uint | post_div2 ) |
Initialise the system clock.
vco_freq | The voltage controller oscillator frequency to be used by the SYS PLL |
post_div1 | The first post divider for the SYS PLL |
post_div2 | The second post divider for the SYS PLL. |
See the PLL documentation in the datasheet for details of driving the PLLs.