Clock device tree configuration - Bootloader specif

Article purpose

本文介绍了由 first stage bootloader 执行的特定RCC internal peripheral 配置：

• TF-A用于可信启动链
• U-Boot SPL对于基本启动链

本文介绍了如何在启动时在 RCC 中配置时钟树。 然后，您可以参考clock device tree configuration 文章来了解如何在Linux中导出每个内部外围设备时钟树® OS from the RCC 时钟树。

配置使用 device tree 机制执行,该机制提供了 RCC 外围设备的硬件描述。

此时钟树仅在引导链FSBL的设备树中使用; 所以在TF-A设备树中为OpenSTLinux正式交付（或在SPL中仅用于DDR调优工具）。

即使 U-Boot 设备树中也存在时钟树信息，该SSBL在引导过程中都不会使用它。

DT bindings documentation

引导加载程序时钟设备树绑定对应于FSBL的clk-stm32mp1驱动程序使用的供应商时钟DT绑定 (TF-A 或 U-Boot SPL), 它基于：

• Clock_device_tree_configuration中描述的绑定
• #DT configuration中描述的引导加载程序特定属性

这个绑定文档解释了如何为 bootloader 端的时钟编写设备树文件:

• TF-A: tf-a/docs/devicetree/bindings/clock/st,stm32mp1-rcc.txt"
• U-Boot SPL: doc/device-tree-bindings/clock/st,stm32mp1.txt

DT configuration

该硬件描述是 STM32 microprocessor 设备树文件 (扩展名为.dtsi ) 和 board 设备树文件 (.dts extension)的组合。 有关设备树文件拆分的说明，请参阅 Device tree。

STM32CubeMX 可用于生成板设备树。有关详细信息，请参阅How to configure the DT using STM32CubeMX。

DT configuration (STM32 level)

STM32MP1时钟节点位于 stm32mp157c.dtsi (有关详细信息，请参阅Device tree ):

• 固定时钟定义在 clock node
• RCC 节点，用于#STM32MP1 clock node: 时钟生成和分配。

 / {
 ...
 	clocks {
 		clk_hse: clk-hse {
 			#clock-cells = <0>;
 			compatible = "fixed-clock";
 			clock-frequency = <24000000>;
 		};
 
 ...
   	};
 ...
 	soc {
 ...
 		rcc: rcc@50000000 {
 			compatible = "st,stm32mp1-rcc", "syscon";
 			reg = <0x50000000 0x1000>;
 			#clock-cells = <1>;
 			#reset-cells = <1>;
 			interrupts = <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>;
 		};
...
 
 	};
 
 };

有关Linux^®内核常见的绑定，请参考 clock device tree configuration 。

DT configuration (board level)

Clock node

时钟树也基于时钟节点中的五个固定时钟。它们用于定义相关ST32MP1振荡器的状态：

• clk-lsi
• clk-lse
• clk-hsi
• clk-hse
• clk-csi

详细信息请参考clock device tree configuration。

在引导时，时钟树初始化执行以下任务：

• 启用设备树中存在的且未禁用的振荡器(状态为“ disabled”的节点),
• 如果节点不存在或被禁用，则禁用HSI振荡器(HSI始终由ROM代码激活)。

此信息位于以下文件中：

• STM32MP157C-EV:
  • TF-A: fdts/stm32mp157c-ed1.dts
  • U-Boot SPL: arch/arm/dts/stm32mp157c-ed1-u-boot.dtsi
• STM32MP157X-DK:
  • TF-A: fdts/stm32mp157a-dk1.dts.
  • U-Boot SPL: arch/arm/dts/stm32mp157a-dk1-u-boot.dtsi.

Optional properties for "clk-lse" and "clk-hse" external oscillators

对于外部振荡器HSE和LSE，默认时钟配置是外部晶体/陶瓷谐振器。

支持四个可选字段：

• "st,bypass" 配置外部模拟时钟源 (set HSEBYP, LSEBYP),
• "st,digbypass" 配置外部数字时钟源 (set DIGBYP and HSEBYP, LSEBYP),
• "st,css" 启动时钟安全系统 (HSECSSON, LSECSSON),
• "st,drive" (LSE only) 包含振荡器的驱动器值 (请参阅文件“stm32mp1-clksrc.h”中定义的LSEDRV_).

DT configuration for HSE

HSE可以在OSC_IN上接受数字或模拟的外部晶体/陶瓷或外部时钟源：用户需要根据硬件设置在设备树中选择正确的频率和正确的配置。

所有ST板均使用数字外部时钟配置 (因此，设备树中包含 = st,digbypass).

例如，在相同的24MHz频率下，我们有3种配置：

• 数字外部时钟 = st,digbypass

 	/ {
 		clocks {
 			clk_hse: clk-hse {
 				#clock-cells = <0>;
 				compatible = "fixed-clock";
 				clock-frequency = <24000000>;
 				st,digbypass;
 			};
 	};

• 模拟外部时钟 = st,bypass

 	/ {
 		clocks {
 			clk_hse: clk-hse {
 				#clock-cells = <0>;
 				compatible = "fixed-clock";
 				clock-frequency = <24000000>;
 				st,bypass;
			};
 	};

• 晶体/陶瓷谐振器配置

 	/ {
 		clocks {
 			clk_hse: clk-hse {
 				#clock-cells = <0>;
 				compatible = "fixed-clock";
 				clock-frequency = <24000000>;
 			};
 	};

DT configuration for LSE

下面是一个带有 32768 kHz 晶体谐振器的LSE板上文件示例，该驱动器设置为中高电平，并具有激活的时钟安全系统。

 	/ {
 		clocks {
 			clk_lse: clk-lse {
 				#clock-cells = <0>;
 				compatible = "fixed-clock";
 				clock-frequency = <32768>;
 				st,css;
 				st,drive = <LSEDRV_MEDIUM_HIGH>;
 			};
 	};

Optional property for "clk-hsi" internal oscillator

对于STM32MP15设备，HSI时钟频率在内部固定为64 MHz。

在设备树中，clk-hsi是HSIDIV分频器之后的时钟 (有关clk_hsi的更多信息，请参见 reference manual中的RCC章节)。
因此，该固定时钟的频率用于计算时钟树初始化的预期HSIDIV。

以下是HSIDIV的示例 = 1/1:

 	/ {
 		clocks {
 			clk_hsi: clk-hsi {
 				#clock-cells = <0>;
 				compatible = "fixed-clock";
 				clock-frequency = <64000000>;
 			};
 	};

以下是HSIDIV的示例 = 1/2:

 	/ {
 		clocks {
 			clk_hsi: clk-hsi {
 				#clock-cells = <0>;
 				compatible = "fixed-clock";
 				clock-frequency = <32000000>;
 			};
 	};

Clock node example

时钟节点的示例包括：

• 所有振荡器打开(HSE, HSI, LSE, LSI, CSI)
• 64MHZ时的HSI (HSIDIV = 1/1)
• 使用24MHz数字外部时钟的HSE
• LSE使用外部晶体a 32.768kHz（典型频率）

我们重点介绍定制部件：

 / {
 	clocks {
 		clk_hse: clk-hse {
 			#clock-cells = <0>;
 			compatible = "fixed-clock";
 			clock-frequency = <24000000>;
 			st,digbypass;
 		};
 
 		clk_hsi: clk-hsi {
 			#clock-cells = <0>;
 			compatible = "fixed-clock";
 			clock-frequency = <64000000>;
 		};
 
 		clk_lse: clk-lse {
 			#clock-cells = <0>;
 			compatible = "fixed-clock";
 			clock-frequency = <32768>;
 		};
 
 		clk_lsi: clk-lsi {
 			#clock-cells = <0>;
 			compatible = "fixed-clock";
 			clock-frequency = <32000>;
 		};
 
 		clk_csi: clk-csi {
 			#clock-cells = <0>;
 			compatible = "fixed-clock";
 			clock-frequency = <4000000>;
 		};
 	};
 };

因此，基于SoC设备树“ stm32mp157c.dtsi”的最终电路板设备树为：

 #include "stm32mp157c.dtsi"
 &clk_hse {
 	clock-frequency = <24000000>;
 	st,digbypass;
 };
 
 &clk_hsi {
 	clock-frequency = <64000000>;
 };
 
 &clk_lse {
 	clock-frequency = <32768>;
 };

它是TF-A用于STM32MP157C-EV 的配置

STM32MP1 clock node

Please refer to clock device tree configuration for information on how to specify the number of cells in a clock specifier.

The bootloader performs a global clock initialization, as described below. The information related to a given board can be found in the board specific device tree files listed in clock node.

The bootloader uses other properties for RCC node ("st,stm32mp1-rcc" compatible):

• secure-status: related to TZEN bit configuration in RCC_TZCR register that allows to restrict RCC and PWR registers write access
• st,clksrc: clock source configuration array
• st,clkdiv: clock divider configuration array
• st,pll: specific PLL configuration
• st,pkcs: peripheral kernel clock distribution configuration array.

All the available clocks are defined as preprocessor macros in stm32mp1-clks.h and can be used in device tree sources.

Defining clock source distribution with st,clksrc property

This property can be used to configure the clock distribution tree. When used, it must describe the whole distribution tree.

There are nine clock source selectors for the STM32MP15 devices. They must be configured in the following order: MPU, AXI, MCU, PLL12, PLL3, PLL4, RTC, MCO1, and MCO2.

The clock source configuration values are defined by the CLK_<NAME>_<SOURCE> macros located in stm32mp1-clksrc.h.

Example:

        st,clksrc = <
                CLK_MPU_PLL1P
                CLK_AXI_PLL2P
                CLK_MCU_PLL3P
                CLK_PLL12_HSE
                CLK_PLL3_HSE
                CLK_PLL4_HSE
                CLK_RTC_LSE
                CLK_MCO1_DISABLED
                CLK_MCO2_DISABLED
        >;

Defining clock dividers with st,clkdiv property

This property can be used to configure the value of the clock main dividers. When used, it must describe the whole clock divider tree.

There are 11 dividers values for the STM32MP15 devices. They must be configured in the following order: MPU, AXI, MCU, APB1, APB2, APB3, APB4, APB5, RTC, MCO1 and MCO2.

Each divider value uses the DIV coding defined in the RCC associated register, RCC_xxxDIVR. In most cases, this value is the following:

• 0x0: not divided
• 0x1: division by 2
• 0x2: division by 4
• 0x3: division by 8
• ...

Note that the coding differs for RTC MCO1 and MCO2:

• 0x0: not divided
• 0x1: division by 2
• 0x2: division by 3
• 0x3: division by 4
• ...

Example:

        st,clkdiv = <
                1 /*MPU*/
                0 /*AXI*/
                0 /*MCU*/
                1 /*APB1*/
                1 /*APB2*/
                1 /*APB3*/
                1 /*APB4*/
                2 /*APB5*/
                23 /*RTC*/
                0 /*MCO1*/
                0 /*MCO2*/
        >;

Defining peripheral PLL frequencies with st,pll property

This property can be used to configure PLL frequencies.

The PLL children nodes for PLL1 to PLL4 (see reference manual for details) are associated with an index from 0 to 3 (st,pll@0 to st,pll@3). PLLx is off when the associated node is absent.

For ecosystem release ≥ v1.2.0{{#set:Ecosystem release=revision of a previous flow 1.2.0}} , TF-A automatically selects the most suitable operating point for the platform (please refer to 如何更改CPU频率), so the PLL1 node is no longer necessary.

Below the available properties for each PLL node:

• cfg contains the PLL configuration parameters in the following order: DIVM, DIVN, DIVP, DIVQ, DIVR, output.

DIVx values are defined as in RCC:

• 0x0: bypass (division by 1)
• 0x1: division by 2
• 0x2: division by 3
• 0x3: division by 4
• ...

Output contains a bitfield for each output value (1:ON / 0:OFF)

• BIT(0) → output P : DIVPEN
• BIT(1) → output Q : DIVQEN
• BIT(2) → output R : DIVREN

Note: PQR(p,q,r) macro can be used to build this value with p, q, r = 0 or 1.

• frac: fractional part of the multiplication factor (optional, when absent PLL is in integer mode).

• csg contains the clock spreading generator parameters (optional) in the following order: MOD_PER, INC_STEP and SSCG_MODE.

MOD_PER: modulation period adjustment

INC_STEP: modulation depth adjustment

SSCG_MODE: Spread spectrum clock generator mode, defined in stm32mp1-clksrc.h:

• SSCG_MODE_CENTER_SPREAD = 0
• SSCG_MODE_DOWN_SPREAD = 1

Example:

	st,pll@0 {
		cfg = < 1 53 0 0 0 1 >;
		frac = < 0x810 >;
	};
	st,pll@1 {
		cfg = < 1 43 1 0 0 PQR(0,1,1) >;
		csg = < 10 20 1 >;
	};
	st,pll@2 {
		cfg = < 2 85 3 13 3 0 >;
		csg = < 10 20 SSCG_MODE_CENTER_SPREAD >;
	};
	st,pll@3 {
		cfg = < 2 78 4 7 9 3 >;
	};

Defining peripheral kernel clock tree distribution with st,pkcs property

This property can be used to configure the peripheral kernel clock selection.

It is a list of peripheral kernel clock source identifiers defined by the CLK_<KERNEL-CLOCK>_<PARENT-CLOCK> macros in the stm32mp1-clksrc.h header file.

st,pkcs may not list all the kernel clocks. No specific order is required.

Example:

	st,pkcs = <
		CLK_STGEN_HSE
		CLK_CKPER_HSI
		CLK_USBPHY_PLL2P
		CLK_DSI_PLL2Q
                CLK_I2C46_HSI
                CLK_UART1_HSI
                CLK_UART24_HSI
	>;

HSI and CSI clocks calibration

The calibration is an optional feature that can be enabled from the device tree. It allows requesting the HSI or CSI clock calibration by several means:

• SiP SMC service
• Periodic calibration every X seconds
• Interrupt raised by the MCU

This feature requires that a hardware timer is assigned to the calibration sequence.

A dedicated interrupt must be defined using "mcu_sev" name to start a calibration on detection of an interrupt raised by the MCU.

• st,hsi-cal: used to enable HSI clock calibration feature.
• st,csi-cal; used to enable CSI clock calibration feature.
• st,cal-sec: used to enable periodic calibration at specified time intervals from the secure monitor. The time interval must be given in seconds. If not specified, a calibration is only processed for each incoming request.

Example:

	&rcc {
		st,hsi-cal;
		st,csi-cal;
		st,cal-sec = <15>;
		secure-interrupts = <GIC_SPI 144 IRQ_TYPE_LEVEL_HIGH>,
				<GIC_SPI 145 IRQ_TYPE_LEVEL_HIGH>;
		interrupt-names = "mcu_sev", "wakeup";
	};

How to configure the DT using STM32CubeMX

The STM32CubeMX tool can be used to configure the STM32MPU device and get the corresponding platform configuration device tree files.

The STM32CubeMX may not support all the properties described in the above DT bindings documentation paragraph.
If so, the tool inserts user sections in the generated device tree.
These sections can then be edited to add some properties and they are preserved from one generation to another.

Refer to STM32CubeMX user manual for further information.

References

Please refer to the following links for additional information: