libopencm3
A free/libre/open-source firmware library for various ARM Cortex-M3 microcontrollers.
RCC peripheral API

This library supports the Reset and Clock Control System in the STM32 series of ARM Cortex Microcontrollers by ST Microelectronics. More...

Collaboration diagram for RCC peripheral API:

Macros

#define _RCC_REG(i)   MMIO32(RCC_BASE + ((i) >> 5))
 
#define _RCC_BIT(i)   (1 << ((i) & 0x1f))
 

Functions

void rcc_clock_setup_pll (const struct rcc_pll_config *config)
 Setup the base PLLs and clock domains for the STM32H7. More...
 
uint32_t rcc_get_bus_clk_freq (enum rcc_clock_source source)
 Get the clock rate (in Hz) of the specified clock source. More...
 
uint32_t rcc_get_usart_clk_freq (uint32_t usart)
 Get the peripheral clock speed for the USART at base specified. More...
 
uint32_t rcc_get_timer_clk_freq (uint32_t timer)
 Get the peripheral clock speed for the Timer at base specified. More...
 
uint32_t rcc_get_i2c_clk_freq (uint32_t i2c)
 Get the peripheral clock speed for the I2C device at base specified. More...
 
uint32_t rcc_get_spi_clk_freq (uint32_t spi)
 Get the peripheral clock speed for the SPI device at base specified. More...
 
uint32_t rcc_get_fdcan_clk_freq (uint32_t fdcan)
 Get the peripheral clock speed for the FDCAN device at base specified. More...
 
void rcc_set_peripheral_clk_sel (uint32_t periph, uint32_t clksel)
 Set the clksel value for the specified peripheral. More...
 
void rcc_set_fdcan_clksel (uint8_t clksel)
 Set the clock select for the FDCAN devices. More...
 
void rcc_set_spi123_clksel (uint8_t clksel)
 Set the clock select for the SPI 1/2/3 devices. More...
 
void rcc_set_spi45_clksel (uint8_t clksel)
 Set the clock select for the SPI 4/5 devices. More...
 
void rcc_set_rng_clksel (uint8_t clksel)
 Set the clock select for the RNG device. More...
 
void rcc_peripheral_enable_clock (volatile uint32_t *reg, uint32_t en)
 RCC Enable Peripheral Clocks. More...
 
void rcc_peripheral_disable_clock (volatile uint32_t *reg, uint32_t en)
 RCC Disable Peripheral Clocks. More...
 
void rcc_peripheral_reset (volatile uint32_t *reg, uint32_t reset)
 RCC Reset Peripherals. More...
 
void rcc_peripheral_clear_reset (volatile uint32_t *reg, uint32_t clear_reset)
 RCC Remove Reset on Peripherals. More...
 
void rcc_periph_clock_enable (enum rcc_periph_clken clken)
 Enable Peripheral Clock in running mode. More...
 
void rcc_periph_clock_disable (enum rcc_periph_clken clken)
 Disable Peripheral Clock in running mode. More...
 
void rcc_periph_reset_pulse (enum rcc_periph_rst rst)
 Reset Peripheral, pulsed. More...
 
void rcc_periph_reset_hold (enum rcc_periph_rst rst)
 Reset Peripheral, hold. More...
 
void rcc_periph_reset_release (enum rcc_periph_rst rst)
 Reset Peripheral, release. More...
 
void rcc_set_mco (uint32_t mcosrc)
 Select the source of Microcontroller Clock Output. More...
 
void rcc_osc_bypass_enable (enum rcc_osc osc)
 RCC Enable Bypass. More...
 
void rcc_osc_bypass_disable (enum rcc_osc osc)
 RCC Disable Bypass. More...
 
uint16_t rcc_get_div_from_hpre (uint8_t div_val)
 This will return the divisor 1/2/4/8/16/64/128/256/512 which is set as a 4-bit value, typically used for hpre and other prescalers. More...
 

Detailed Description

This library supports the Reset and Clock Control System in the STM32 series of ARM Cortex Microcontrollers by ST Microelectronics.

LGPL License Terms libopencm3 License

Macro Definition Documentation

◆ _RCC_BIT

#define _RCC_BIT (   i)    (1 << ((i) & 0x1f))

Definition at line 117 of file rcc_common_all.c.

◆ _RCC_REG

#define _RCC_REG (   i)    MMIO32(RCC_BASE + ((i) >> 5))

Definition at line 116 of file rcc_common_all.c.

Function Documentation

◆ rcc_clock_setup_pll()

void rcc_clock_setup_pll ( const struct rcc_pll_config config)

Setup the base PLLs and clock domains for the STM32H7.

This function will utilize the users input parameters to configure all 3 PLLs, as well as the core clock domains (namely SYSCLK, CPU, HCLK, AHB, PCLK1-4) with the specified dividers. Given the dividers, the RCC module will track the the configured frequency for each of these clock domains.

Note: If clock sources, configs, divider, etc. are modified outside of this module, the frequency tracking may be undefined. Note: Clock tree is fairly complex, see RM0433 Section 7 for details.

Parameters
[in]configInput config structure defining desired setup.

Definition at line 181 of file rcc.c.

References FLASH_ACR_LATENCY_0WS, flash_prefetch_disable(), flash_prefetch_enable(), flash_set_ws(), rcc_pll_config::flash_waitstates, rcc_pll_config::hse_frequency, HZ_PER_KHZ, HZ_PER_MHZ, rcc_pll_config::power_mode, pwr_set_mode(), pwr_set_vos_scale(), RCC_CFGR, RCC_CFGR_SW_MASK, RCC_CFGR_SW_PLL1, RCC_CFGR_SW_SHIFT, RCC_CFGR_SWS_HSI, RCC_CFGR_SWS_MASK, RCC_CFGR_SWS_PLL1, RCC_CFGR_SWS_SHIFT, rcc_clock_setup_domain1(), rcc_clock_setup_domain2(), rcc_clock_setup_domain3(), rcc_clock_tree, RCC_CR, RCC_CR_HSEON, RCC_CR_HSERDY, RCC_CR_HSION, RCC_HSE, RCC_HSI_BASE_FREQUENCY, RCC_PLL, rcc_set_and_enable_plls(), rcc_pll_config::smps_level, rcc_pll_config::sysclock_source, and rcc_pll_config::voltage_scale.

Here is the call graph for this function:

◆ rcc_get_bus_clk_freq()

uint32_t rcc_get_bus_clk_freq ( enum rcc_clock_source  source)

Get the clock rate (in Hz) of the specified clock source.

There are numerous clock sources and configurations on the H7, so rates for each configured peripheral clock are aimed to be discoverd/calculated by this module such that the user does not need to know how the MCU is configured in order to utilize a peripheral clock.

Parameters
[in]sourceClock source desired to be fetched.
Returns
Clock rate in Hz for the specified clock. 0 if undefined or error.

Definition at line 234 of file rcc.c.

References cm3_assert_not_reached, HZ_PER_KHZ, HZ_PER_MHZ, RCC_AHBCLK, RCC_APB1CLK, RCC_APB2CLK, RCC_APB3CLK, RCC_APB4CLK, rcc_clock_tree, RCC_CPUCLK, RCC_D1CCIPR, RCC_D1CCIPR_CKPERSEL_HSE, RCC_D1CCIPR_CKPERSEL_HSI, RCC_D1CCIPR_CKPERSEL_MASK, RCC_D1CCIPR_CKPERSEL_SHIFT, RCC_HCLK3, RCC_HSI_BASE_FREQUENCY, RCC_PERCLK, RCC_SYSCLK, and RCC_SYSTICKCLK.

Referenced by rcc_get_spi_clk_freq().

Here is the caller graph for this function:

◆ rcc_get_div_from_hpre()

uint16_t rcc_get_div_from_hpre ( uint8_t  div_val)

This will return the divisor 1/2/4/8/16/64/128/256/512 which is set as a 4-bit value, typically used for hpre and other prescalers.

Parameters
div_valMasked and shifted divider value from register (e.g. RCC_CFGR)

Definition at line 260 of file rcc_common_all.c.

◆ rcc_get_fdcan_clk_freq()

uint32_t rcc_get_fdcan_clk_freq ( uint32_t  fdcan)

Get the peripheral clock speed for the FDCAN device at base specified.

Parameters
fdcanBase address of FDCAN to get clock frequency for (e.g. FDCAN1_BASE).

Definition at line 355 of file rcc.c.

References HZ_PER_KHZ, HZ_PER_MHZ, rcc_clock_tree, RCC_D2CCIP1R, RCC_D2CCIP1R_FDCANSEL_HSE, RCC_D2CCIP1R_FDCANSEL_MASK, RCC_D2CCIP1R_FDCANSEL_PLL1Q, RCC_D2CCIP1R_FDCANSEL_PLL2Q, and RCC_D2CCIP1R_FDCANSEL_SHIFT.

◆ rcc_get_i2c_clk_freq()

uint32_t rcc_get_i2c_clk_freq ( uint32_t  i2c)

Get the peripheral clock speed for the I2C device at base specified.

Parameters
i2cBase address of I2C to get clock frequency for (e.g. I2C1_BASE).

Definition at line 309 of file rcc.c.

References HZ_PER_MHZ, I2C4_BASE, and rcc_clock_tree.

◆ rcc_get_spi_clk_freq()

uint32_t rcc_get_spi_clk_freq ( uint32_t  spi)

◆ rcc_get_timer_clk_freq()

uint32_t rcc_get_timer_clk_freq ( uint32_t  timer)

Get the peripheral clock speed for the Timer at base specified.

Parameters
timerBase address of TIMER to get clock frequency for (e.g. TIM1_BASE).

Definition at line 297 of file rcc.c.

References HRTIM_BASE, HZ_PER_MHZ, LPTIM2_BASE, LPTIM5_BASE, rcc_clock_tree, and TIM1_BASE.

◆ rcc_get_usart_clk_freq()

uint32_t rcc_get_usart_clk_freq ( uint32_t  usart)

Get the peripheral clock speed for the USART at base specified.

Parameters
usartBase address of USART to get clock frequency for (e.g. USART1_BASE).

Definition at line 268 of file rcc.c.

References cm3_assert_not_reached, HZ_PER_MHZ, rcc_clock_tree, RCC_D2CCIP2R, RCC_D2CCIP2R_USART16SEL_SHIFT, RCC_D2CCIP2R_USART234578SEL_SHIFT, RCC_D2CCIP2R_USARTSEL_CSI, RCC_D2CCIP2R_USARTSEL_HSI, RCC_D2CCIP2R_USARTSEL_LSE, RCC_D2CCIP2R_USARTSEL_MASK, RCC_D2CCIP2R_USARTSEL_PCLK, RCC_D2CCIP2R_USARTSEL_PLL2Q, RCC_D2CCIP2R_USARTSEL_PLL3Q, RCC_HSI_BASE_FREQUENCY, USART1_BASE, and USART6_BASE.

Referenced by usart_set_baudrate().

Here is the caller graph for this function:

◆ rcc_osc_bypass_disable()

void rcc_osc_bypass_disable ( enum rcc_osc  osc)

RCC Disable Bypass.

Re-enable the internal clock (high speed and low speed clocks only). The internal clock must be disabled (see rcc_osc_off) for this to have effect.

Note
The LSE clock is in the backup domain and cannot have bypass removed until the backup domain write protection has been removed (see pwr_disable_backup_domain_write_protect) or the backup domain has been reset (see rcc_backupdomain_reset).
Parameters
[in]oscOscillator ID. Only HSE and LSE have effect.

Definition at line 238 of file rcc_common_all.c.

References RCC_BDCR, RCC_CR, RCC_CSR, RCC_HSE, and RCC_LSE.

◆ rcc_osc_bypass_enable()

void rcc_osc_bypass_enable ( enum rcc_osc  osc)

RCC Enable Bypass.

Enable an external clock to bypass the internal clock (high speed and low speed clocks only). The external clock must be enabled (see rcc_osc_on) and the internal clock must be disabled (see rcc_osc_off) for this to have effect.

Note
The LSE clock is in the backup domain and cannot be bypassed until the backup domain write protection has been removed (see pwr_disable_backup_domain_write_protect).
Parameters
[in]oscOscillator ID. Only HSE and LSE have effect.

Definition at line 208 of file rcc_common_all.c.

References RCC_BDCR, RCC_BDCR_LSEBYP, RCC_CR, RCC_CR_HSEBYP, RCC_CSR, RCC_HSE, and RCC_LSE.

◆ rcc_periph_clock_disable()

void rcc_periph_clock_disable ( enum rcc_periph_clken  clken)

Disable Peripheral Clock in running mode.

Disable the clock on particular peripheral.

Parameters
[in]clkenrcc_periph_clken Peripheral RCC

For available constants, see rcc_periph_clken (RCC_UART1 for example)

Definition at line 139 of file rcc_common_all.c.

References _RCC_REG.

◆ rcc_periph_clock_enable()

void rcc_periph_clock_enable ( enum rcc_periph_clken  clken)

Enable Peripheral Clock in running mode.

Enable the clock on particular peripheral.

Parameters
[in]clkenrcc_periph_clken Peripheral RCC

For available constants, see rcc_periph_clken (RCC_UART1 for example)

Definition at line 127 of file rcc_common_all.c.

References _RCC_BIT, and _RCC_REG.

Referenced by pwr_set_vos_scale().

Here is the caller graph for this function:

◆ rcc_periph_reset_hold()

void rcc_periph_reset_hold ( enum rcc_periph_rst  rst)

Reset Peripheral, hold.

Reset particular peripheral, and hold in reset state.

Parameters
[in]rstrcc_periph_rst Peripheral reset

For available constants, see rcc_periph_rst (RST_UART1 for example)

Definition at line 166 of file rcc_common_all.c.

References _RCC_BIT, and _RCC_REG.

◆ rcc_periph_reset_pulse()

void rcc_periph_reset_pulse ( enum rcc_periph_rst  rst)

Reset Peripheral, pulsed.

Reset particular peripheral, and restore to working state.

Parameters
[in]rstrcc_periph_rst Peripheral reset

For available constants, see rcc_periph_rst (RST_UART1 for example)

Definition at line 152 of file rcc_common_all.c.

References _RCC_BIT, and _RCC_REG.

◆ rcc_periph_reset_release()

void rcc_periph_reset_release ( enum rcc_periph_rst  rst)

Reset Peripheral, release.

Restore peripheral from reset state to working state.

Parameters
[in]rstrcc_periph_rst Peripheral reset

For available constants, see rcc_periph_rst (RST_UART1 for example)

Definition at line 179 of file rcc_common_all.c.

References _RCC_REG.

◆ rcc_peripheral_clear_reset()

void rcc_peripheral_clear_reset ( volatile uint32_t *  reg,
uint32_t  clear_reset 
)

RCC Remove Reset on Peripherals.

Remove the reset on particular peripherals. There are three registers involved, each one controlling reset of peripherals associated with the AHB, APB1 and APB2 respectively. Several peripherals could have the reset removed simultaneously only if they are controlled by the same register.

See also
rcc_periph_reset_release for a less error prone version, if you only need to unreset a single peripheral.
rcc_periph_reset_pulse if you are only going to toggle reset anyway.
Parameters
[in]*regUnsigned int32. Pointer to a Reset Register (either RCC_AHBENR, RCC_APB1ENR or RCC_APB2ENR)
[in]clear_resetUnsigned int32. Logical OR of all resets to be removed:
  • If register is RCC_AHBRSTR, from rcc_ahbrstr_rst
  • If register is RCC_APB1RSTR, from rcc_apb1rstr_rst
  • If register is RCC_APB2RSTR, from rcc_apb2rstr_rst

Definition at line 111 of file rcc_common_all.c.

◆ rcc_peripheral_disable_clock()

void rcc_peripheral_disable_clock ( volatile uint32_t *  reg,
uint32_t  en 
)

RCC Disable Peripheral Clocks.

Disable the clock on particular peripherals. There are three registers involved, each one controlling the enabling of clocks associated with the AHB, APB1 and APB2 respectively. Several peripherals could be disabled simultaneously only if they are controlled by the same register.

See also
rcc_periph_clock_disable for a less error prone version, if you only need to disable a single peripheral.
Parameters
[in]*regUnsigned int32. Pointer to a Clock Enable Register (either RCC_AHBENR, RCC_APB1ENR or RCC_APB2ENR)
[in]enUnsigned int32. Logical OR of all enables to be used for disabling.
  • If register is RCC_AHBENR, from rcc_ahbenr_en
  • If register is RCC_APB1ENR, from rcc_apb1enr_en
  • If register is RCC_APB2ENR, from rcc_apb2enr_en

Definition at line 66 of file rcc_common_all.c.

◆ rcc_peripheral_enable_clock()

void rcc_peripheral_enable_clock ( volatile uint32_t *  reg,
uint32_t  en 
)

RCC Enable Peripheral Clocks.

Enable the clock on particular peripherals. There are three registers involved, each one controlling the enabling of clocks associated with the AHB, APB1 and APB2 respectively. Several peripherals could be enabled simultaneously only if they are controlled by the same register.

See also
rcc_periph_clock_enable for a less error prone version, if you only need to enable a single peripheral.
Parameters
[in]*regUnsigned int32. Pointer to a Clock Enable Register (either RCC_AHBENR, RCC_APB1ENR or RCC_APB2ENR)
[in]enUnsigned int32. Logical OR of all enables to be set
  • If register is RCC_AHBENR, from rcc_ahbenr_en
  • If register is RCC_APB1ENR, from rcc_apb1enr_en
  • If register is RCC_APB2ENR, from rcc_apb2enr_en

Definition at line 44 of file rcc_common_all.c.

◆ rcc_peripheral_reset()

void rcc_peripheral_reset ( volatile uint32_t *  reg,
uint32_t  reset 
)

RCC Reset Peripherals.

Reset particular peripherals. There are three registers involved, each one controlling reset of peripherals associated with the AHB, APB1 and APB2 respectively. Several peripherals could be reset simultaneously only if they are controlled by the same register.

See also
rcc_periph_reset_hold for a less error prone version, if you only need to reset a single peripheral.
rcc_periph_reset_pulse if you are only going to toggle reset anyway.
Parameters
[in]*regUnsigned int32. Pointer to a Reset Register (either RCC_AHBENR, RCC_APB1ENR or RCC_APB2ENR)
[in]resetUnsigned int32. Logical OR of all resets.
  • If register is RCC_AHBRSTR, from rcc_ahbrstr_rst
  • If register is RCC_APB1RSTR, from rcc_apb1rstr_rst
  • If register is RCC_APB2RSTR, from rcc_apb2rstr_rst

Definition at line 88 of file rcc_common_all.c.

◆ rcc_set_fdcan_clksel()

void rcc_set_fdcan_clksel ( uint8_t  clksel)

Set the clock select for the FDCAN devices.

Parameters
[in]clkselClock source to configure for, RCC_D2CCIP1R Values appropriate for the FDCAN peripherals, eg RCC_D2CCIP1R_FDCANSEL_XXX
See also
rcc_set_peripheral_clk_sel for equivalent generic functionality

Definition at line 427 of file rcc.c.

References RCC_D2CCIP1R, RCC_D2CCIP1R_FDCANSEL_MASK, and RCC_D2CCIP1R_FDCANSEL_SHIFT.

◆ rcc_set_mco()

void rcc_set_mco ( uint32_t  mcosrc)

Select the source of Microcontroller Clock Output.

Exact sources available depend on your target. On devices with multiple MCO pins, this function controls MCO1

Parameters
[in]mcosrcthe unshifted source bits

Definition at line 191 of file rcc_common_all.c.

References RCC_CFGR, RCC_CFGR_MCO_MASK, and RCC_CFGR_MCO_SHIFT.

◆ rcc_set_peripheral_clk_sel()

void rcc_set_peripheral_clk_sel ( uint32_t  periph,
uint32_t  clksel 
)

Set the clksel value for the specified peripheral.

This code will determine the appropriate register, shift and mask values to apply to the selection to and set the values appropriately.

Peripheral specific clksels functions are also available, eg rcc_set_<periph>_clksel. These provide the same functionality, you only need one of them. for instance rcc_set_fdcan_clksel or rcc_set_spi123_clksel

Parameters
[in]periphBase address of the peripheral to set the clock sel for
[in]clkselRaw, unshifted selection value for the clock, depending on peripheral, see RCC_D1CCIP1R Values or RCC_D2CCIP1R Values or RCC_D2CCIP2R Values

Definition at line 370 of file rcc.c.

References cm3_assert_not_reached, FDCAN1_BASE, FDCAN2_BASE, RCC_D2CCIP1R, RCC_D2CCIP1R_FDCANSEL_MASK, RCC_D2CCIP1R_FDCANSEL_SHIFT, RCC_D2CCIP1R_SPI123SEL_MASK, RCC_D2CCIP1R_SPI123SEL_SHIFT, RCC_D2CCIP1R_SPI45SEL_MASK, RCC_D2CCIP1R_SPI45SEL_SHIFT, RCC_D2CCIP2R, RCC_D2CCIP2R_RNGSEL_MASK, RCC_D2CCIP2R_RNGSEL_SHIFT, RCC_D2CCIP2R_USART16SEL_SHIFT, RCC_D2CCIP2R_USART234578SEL_SHIFT, RCC_D2CCIP2R_USARTSEL_MASK, RNG_BASE, SPI1_BASE, SPI2_BASE, SPI3_BASE, SPI4_BASE, SPI5_BASE, UART4_BASE, UART5_BASE, UART7_BASE, UART8_BASE, USART1_BASE, USART2_BASE, USART3_BASE, and USART6_BASE.

◆ rcc_set_rng_clksel()

void rcc_set_rng_clksel ( uint8_t  clksel)

Set the clock select for the RNG device.

Parameters
[in]clkselClock source to configure for. RCC_D2CCIP2R Values
See also
rcc_set_peripheral_clk_sel for equivalent generic functionality

Definition at line 432 of file rcc.c.

References RCC_D2CCIP2R, RCC_D2CCIP2R_RNGSEL_MASK, and RCC_D2CCIP2R_RNGSEL_SHIFT.

◆ rcc_set_spi123_clksel()

void rcc_set_spi123_clksel ( uint8_t  clksel)

Set the clock select for the SPI 1/2/3 devices.

Parameters
[in]clkselClock source to configure for, RCC_D2CCIP1R Values appropriate for the SPI1/2/3 peripherals, eg RCC_D2CCIP1R_SPI123_XXX
See also
rcc_set_peripheral_clk_sel for equivalent generic functionality

Definition at line 437 of file rcc.c.

References RCC_D2CCIP1R, RCC_D2CCIP1R_SPI123SEL_MASK, and RCC_D2CCIP1R_SPI123SEL_SHIFT.

◆ rcc_set_spi45_clksel()

void rcc_set_spi45_clksel ( uint8_t  clksel)

Set the clock select for the SPI 4/5 devices.

Parameters
[in]clkselClock source to configure for. RCC_D2CCIP1R Values
See also
rcc_set_peripheral_clk_sel for equivalent generic functionality

Definition at line 442 of file rcc.c.

References RCC_D2CCIP1R, RCC_D2CCIP1R_SPI45SEL_MASK, and RCC_D2CCIP1R_SPI45SEL_SHIFT.