RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2025-01-18 12:52:44 +01:00
Code Releases Activity

cpu/stm32: rework clock configuration documentation

Browse Source
This commit is contained in:
Alexandre Abadie 2020-10-21 16:12:58 +02:00
parent e4164e3924
commit 0bd70a46bc
No known key found for this signature in database
GPG Key ID: 1C919A403CAE1405
1 changed files with 94 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

145
cpu/stm32/doc.txt
View File

@ -1,53 +1,96 @@
/** /**
* @defgroup cpu_stm32 STM32 @defgroup cpu_stm32 STM32
* @ingroup cpu @ingroup cpu
* @brief All STM32 families code and definitions @brief All STM32 families code and definitions
*
* This module contains all code and definition to all STM32 cpu This module contains the code and definitions for STM32 cpu
* families supported by RIOT: F0, F1, F2, F3, F4, F7, L0, L4 and WB. families supported by RIOT: F0, F1, F2, F3, F4, F7, G0, G4, L0, L1, L4, L5 and WB.
*
* STM32Fx Clock configuration All constants described below can be configured using `CFLAGS` from the command
* =========================== line or in the application Makefile.
*
* stm32fx cpus share clock configuration code and macro. Clock configuration
* It can be configured as described here. ===================
*
* The following macro must be defined in the board's periph_conf.h: All STM32 cpus have clock configuration code and macros. It is recommend to read
* - CLOCK_HSE: 0 if HSI must be used as PLL source, frequency in Hz otherwise, the reference manual of the CPU of interest to learn about the corresponding
* - CLOCK_LSE: 0 if LSI must be used as low speed clock, 1 otherwise clock tree and the possible configurations.
* (the LSE is a 32.768kHz crytal)
* - CLOCK_CORECLOCK: desired main clock frequency For all families, different input clock sources are available for the SYSCLK
* - CLOCK_AHB_DIV, CLOCK_AHB: AHB prescaler in register value and AHB frequecny in Hz system clock (but only one can be used at a time):
* - CLOCK_APB1_DIV, CLOCK_APB1: APB1 prescaler in register value and APB1 frequecny in Hz
* - CLOCK_APB2_DIV, CLOCK_APB2: APB2 prescaler in register value and APB2 frequecny in Hz - HSE (High Speed External): HSE depends on the board configuration and its
* (CLOCK_APB2_DIV is not needed for stm32f0) presence is specified by the `CONFIG_BOARD_HAS_HSE` constant at board level.
* The `CLOCK_HSE` constant specifies the frequency of the external oscillator
* The following macro must be defined for stm32f[2|4|7]: in Hz.
* - CLOCK_PLL_M, CLOCK_PLL_N, CLOCK_PLL_P, CLOCK_PLL_Q, (CLOCK_PLL_R, optional): To use HSE as system clock (SYSCLK), set `CONFIG_USE_CLOCK_HSE` constant to 1;
* Main PLL factors
* - HSI (High Speed Internal): HSI is either 8MHz or 16MHz, depending
* The following macro must be defined for stm32f[0|1|3]: on the families.
* - PLL_MUL, PLL_PREDIV: PLL factors. These values are used as is. A PREDIV of 2 To use HSI as system clock (SYSCLK), set `CONFIG_USE_CLOCK_HSI` constant to 1;
* can be assumed when HSI is selected as PLL input. Some model support any value
* as PREDIV even with HSI though. The `clk_conf` tool will assume PREDIV must be - MSI (Multi-Speed Internal): This internal oscillator is only available on L0,
* to with HSI and will set it accordingly. L1, L4, L5 and WB families.
* To use MSI as system clock (SYSCLK), set `CONFIG_USE_CLOCK_MSI` constant to 1
* The following macro are optional and can be defined depending on board config The MSI clock frequency can be configured using the `CONFIG_CLOCK_MSI`
* and application needs: constant (in Hz);
* - CLOCK_ENABLE_PLL_I2S: if a second PLL (PLL I2S) is available on the cpu, it
* can be activated with this macro, then CLOCK_PLL_I2S_M, CLOCK_PLL_I2S_N, - PLL (Phase-Locked Loop) provides a finely configurable clock source for
* CLOCK_PLL_I2S_P and CLOCK_PLL_I2S_Q need to be defined, CLOCK_PLL_I2S_R is optional. SYSCLK and allows to reach precise and high clock speeds, depending on the
* - CLOCK_ENABLE_PLL_SAI: if a second PLL (PLL SAI) is available on the cpu, it input source. In RIOT, this is the default clock source for SYSCLK.
* can be activated with this macro, then CLOCK_PLL_SAI_M, CLOCK_PLL_SAI_N, To use the PLL as system clock (SYSCLK), set `CONFIG_USE_CLOCK_PLL` constant
* CLOCK_PLL_SAI_P and CLOCK_PLL_SAI_Q need to be defined, CLOCK_PLL_SAI_R is optional. to 1 (default).
* - CLOCK_USE_ALT_48MHZ: if the 48MHz clock should be generated by the alternate
* source (PLL I2S or PLL SAI, depending on cpu) If an HSE is provided by the board, it is automatically selected as input
* source for the PLL, otherwise HSI is selected.
* All the previous constants can be generated using the tool in
* `cpu/stm32_common/dist/clk_conf`. On L4 and WB, the PLL input source can be selected between HSE, HSI and MSI
* (default): to configure the PLL input source, just set
* Clock outputs can also be setup with macro: `CONFIG_CLOCK_PLL_SRC_HSI`, `CONFIG_CLOCK_PLL_SRC_HSE` or
* - CLOCK_MCOx_SRC, CLOCK_MCOx_PRE, with x=1,2: MCO1 and MCO2 output configuration `CONFIG_CLOCK_PLL_SRC_MSI` to 1.
* macros. CLOCK_MCOx_SRC defines the MCOx source, as a register value (see vendor header),
* CLOCK_MCOx_PRE defines the MCOx prescaler, as a register value. 2 types of PLL are available on STM32:
- for stm32f[2|4|7], stm32g[0|4] and stm32[l4|l5|wb], the PLL can be
configured with several parameters M, N, P, Q and R (optional). M is the
input divider, N is the multiplier and P, Q and R are output dividers.
On stm32f[2|4|7], the clock source from the P output divider is used as
SYSCLK input, the clock source from the Q output divider can be used as
48MHz.
On stm32g[0|4] and stm32[l4|l5|wb], the clock source from the R output
divider is used as SYSCLK input.
Constants used to configure the PLL on these families are
`CONFIG_CLOCK_PLL_M`, `CONFIG_CLOCK_PLL_N`, `CONFIG_CLOCK_PLL_P`,
`CONFIG_CLOCK_PLL_Q` and `CONFIG_CLOCK_PLL_R`.
- for stm32f[0|1|3] and stm32l[0|1], the PLL can be configured with a
predivider parameter and a multiplier parameter.
Constants used to configure the PLL on these families are
`CONFIG_CLOCK_PLL_DIV` (l0, l1) or `CONFIG_CLOCK_PLL_PREDIV` (f0, f1, f3)
and `CONFIG_CLOCK_PLL_MUL`.
Advanced Peripheral Bus (APB) clock prescalers:
-----------------------------------------------
These prescalers are used to compute the PCLK1 and PCLK2 clock values.
Use `CONFIG_CLOCK_APB1_DIV` and `CONFIG_CLOCK_APB2_DIV` constants to configure
the prescalers (just set the frequency factor).
APB2 is not available on f0 and g0 families so setting `CONFIG_CLOCK_APB2_DIV`
will have no effect on them.
MCO (Microcontroller Clock Output) parameters:
----------------------------------------------
For stm32f[2|4|7], clock outputs can be configured as follows:
- set `CONFIG_CLOCK_ENABLE_MCO1` to enable MCO1 (on PA8) and use
`CONFIG_CLOCK_MCO1_PRE` constant to specify the MCO1 prescaler (default to 1).
Possible sources are HSE, HSI and PLL (the default): set 1 to
`CONFIG_CLOCK_MCO1_USE_HSE`, `CONFIG_CLOCK_MCO1_USE_HSI` or
`CONFIG_CLOCK_MCO1_USE_PLL` to select the source;
- set `CONFIG_CLOCK_ENABLE_MCO2` to enable MCO1 (on PC9) and use
`CONFIG_CLOCK_MCO2_PRE` constant to specify the MCO2 prescaler (default to 1).
Possible sources are HSE, SYSCLK, PLLI2S and PLL (the default): set 1 to
`CONFIG_CLOCK_MCO1_USE_HSE`, `CONFIG_CLOCK_MCO1_USE_SYSCLK`,
`CONFIG_CLOCK_MCO1_USE_PLLI2S` or `CONFIG_CLOCK_MCO1_USE_PLL` to select the
source;
*/ */