This article explains how to configure the clock tree in the RCC at boot time.You can then refer to the clock device tree configuration article to understand how to derive each internal peripheral clock tree in Linux® OS from the RCC clock tree.

The configuration is performed using the device tree mechanism that provides a hardware description of the RCC peripheral.

This clock tree is only used in the device tree of the boot chain FSBL; so in the TF-A device tree for OpenSTLinux official delivery (or in SPL only for the DDR tuning tool).

Even if the clock tree information is also present in the U-Boot device tree, it is not used during boot by this SSBL.

This hardware description is a combination of the STM32 microprocessor device tree files (.dtsi extension) and board device tree files (.dts extension). See the Device tree for an explanation of the device tree file split.

The HSE can accept an external crystal/ceramic or external clock source on OSC_IN, digital or analog : the user needs to select the correct frequency and the correct configuration in the device tree, corresponding to the hardware setup.

All the ST boards are using a digital external clock configuration (so device tree with = st,digbypass).

The HSI clock frequency is internally fixed to 64 MHz for the STM32MP15 devices.

In the device tree, clk-hsi is the clock after HSIDIV divider (more information on clk_hsi can be found in the RCC chapter in the reference manual). As a result the frequency of this fixed clock is used to compute the expected HSIDIV for the clock tree initialization.

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 , TF-A automatically selects the most suitable operating point for the platform (please refer to How to change the CPU frequency), so the PLL1 node is no longer necessary.

CalibrationThe calibrationis 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.

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.

{{Warning|This article explains how to configure the clock tree in the [[RCC_internal_peripheral|RCC]] at boot time.<br/>You can then refer to the [[Clock device tree configuration|clock device tree configuration]] article to understand how to derive each internal peripheral clock tree in Linux<sup>&reg;</sup> OS from the [[RCC_internal_peripheral|RCC]] clock tree.}}

{{Warning|This article explains how to configure the clock tree in the [[RCC_internal_peripheral|RCC]] at boot time.<br/>You can then refer to the [[Clock device tree configuration|clock device tree configuration]] article to understand how to derive each internal peripheral clock tree in Linux<sup>&reg;</sup> OS from the [[RCC_internal_peripheral|RCC]] clock tree.}}

The configuration is performed using the [[Device tree|device tree]] mechanism that provides a hardware description of the [[RCC_internal_peripheral|RCC]] peripheral.

The configuration is performed using the [[Device tree|device tree]] mechanism that provides a hardware description of the [[RCC_internal_peripheral|RCC]] peripheral.

+

+

This clock tree is only used in the device tree of the boot chain FSBL; so in the TF-A device tree for OpenSTLinux official delivery (or in SPL only for the DDR tuning tool).

+

+

Even if the clock tree information is also present in the [[U-Boot_overview|U-Boot]] device tree, it is not used during boot by this SSBL.

== DT bindings documentation ==

== DT bindings documentation ==

−

The bootloader clock device tree bindings are composed of the vendor clock DT bindings used by the clk-stm32mp1 [[TF-A overview|TF-A]] and by the [[U-Boot_overview#SPL:_FSBL_for_basic_boot|U-Boot SPL]] driver.

+

The bootloader clock device tree bindings correspond to the vendor clock DT bindings used by the clk-stm32mp1 driver of the FSBL ([[TF-A overview|TF-A]] or [[U-Boot_overview#SPL:_FSBL_for_basic_boot|U-Boot SPL]]), it is based on:

+

* binding described in [[Clock_device_tree_configuration]]

+

* bootloader specific properties described in [[#DT configuration]]

−

This binding document explains how to write device tree files for clocks on bootloader side:

+

This binding document explains how to write the device tree files for clocks on the bootloader side:

The HSE can accept an external crystal/ceramic or external clock source on OSC_IN, digital or analog : the user needs to select the correct frequency and the correct configuration in the device tree, corresponding to the hardware setup.

−

clocks {

+

−

clk_hse: clk-hse {

+

All the ST boards are using a digital external clock configuration (so device tree with = st,digbypass).

−

#clock-cells = <0>;

+

−

compatible = "fixed-clock";

+

For example with the same 24MHz frequency, we have 3 configurations:

−

clock-frequency = <24000000>;

+

−

st,bypass;

+

[[File:Hse config.jpg|800px|none|]]

−

};

+

+

* Digital external clock = st,digbypass

+

/ {

+

clocks {

+

clk_hse: clk-hse {

+

#clock-cells = <0>;

+

compatible = "fixed-clock";

+

clock-frequency = <{{Highlight|24000000}}>;

+

{{Highlight|st,digbypass;}}

+

};

+

};

+

+

* Analog external clock = st,bypass

+

/ {

+

clocks {

+

clk_hse: clk-hse {

+

#clock-cells = <0>;

+

compatible = "fixed-clock";

+

clock-frequency = <{{Highlight|24000000}}>;

+

{{Highlight|st,bypass;}}

+

};

+

};

+

+

* Crystal/ ceramic resonators configuration

+

/ {

+

clocks {

+

clk_hse: clk-hse {

+

#clock-cells = <0>;

+

compatible = "fixed-clock";

+

clock-frequency = <{{Highlight|24000000}}>;

+

};

+

};

+

+

===== DT configuration for LSE =====

+

+

Below an example of LSE on board file with 32,768kHz crystal resonators, the drive set to medium high and with activated clock security system.

−

clk_lse: clk-lse {

+

/ {

−

#clock-cells = <0>;

+

clocks {

−

compatible = "fixed-clock";

+

clk_lse: clk-lse {

−

clock-frequency = <32768>;

+

#clock-cells = <0>;

−

st,css;

+

compatible = "fixed-clock";

−

st,drive = <LSEDRV_LOWEST>;

+

clock-frequency = <{{Highlight|32768}}>;

−

};

+

{{Highlight|st,css;}}

−

};

+

st,drive = <{{Highlight|LSEDRV_MEDIUM_HIGH}}>;

−

</pre>

+

};

+

};

===== Optional property for "clk-hsi" internal oscillator =====

===== Optional property for "clk-hsi" internal oscillator =====

−

The HSI clock frequency is internally fixed to 64 MHz for STM32MP15 devices.

+

The HSI clock frequency is internally fixed to 64 MHz for the STM32MP15 devices.

In the device tree, clk-hsi is the clock after HSIDIV divider (more information on clk_hsi can be found in the RCC chapter in the [[STM32MP15 resources|reference manual]]).<br/>

In the device tree, clk-hsi is the clock after HSIDIV divider (more information on clk_hsi can be found in the RCC chapter in the [[STM32MP15 resources|reference manual]]).<br/>

Line 145:

Line 177:

};

};

};

};

+

+

===== Clock node example =====

+

+

An example of clocks node with:

+

* all oscillators switched on (HSE, HSI, LSE, LSI, CSI)

+

* HSI at 64MHZ (HSIDIV = 1/1)

+

* HSE using a digital external clock at 24MHz

+

* LSE using an external crystal a 32.768kHz (the typical frequency)

+

+

We highlight the customized parts:

+

/ {

+

clocks {

+

clk_hse: clk-hse {

+

#clock-cells = <0>;

+

compatible = "fixed-clock";

+

clock-frequency = <{{Highlight|24000000}}>;

+

{{Highlight|st,digbypass;}}

+

};

+

+

clk_hsi: clk-hsi {

+

#clock-cells = <0>;

+

compatible = "fixed-clock";

+

clock-frequency = <{{Highlight|64000000}}>;

+

};

+

+

clk_lse: clk-lse {

+

#clock-cells = <0>;

+

compatible = "fixed-clock";

+

clock-frequency = <{{Highlight|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>;

+

};

+

};

+

};

+

+

So the resulting board device tree, based on SoC device tree "stm32mp157c.dtsi", is :

+

+

#include "stm32mp157c.dtsi"

+

&clk_hse {

+

clock-frequency = <{{Highlight|24000000}}>;

+

{{Highlight|st,digbypass;}}

+

};

+

+

&clk_hsi {

+

clock-frequency = <{{Highlight|64000000}}>;

+

};

+

+

&clk_lse {

+

clock-frequency = <{{Highlight|32768}}>;

+

};

+

+

It is the configuration used by TF-A for STM32MP157C-EV <ref name="stm32mp157c-ed1"/>

==== STM32MP1 clock node ====

==== STM32MP1 clock node ====

Line 151:

Line 245:

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|clock node]].

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|clock node]].

−

The bootloader uses other properties:

+

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

PLL children nodes for PLL1 to PLL4 (see [[STM32MP15 resources|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.

+

The PLL children nodes for PLL1 to PLL4 (see [[STM32MP15 resources|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 {{EcosystemRelease | revision=1.2.0 | range=and after}}''', TF-A automatically selects the most suitable operating point for the platform (please refer to [[How to change the CPU frequency]]), so the PLL1 node is no longer necessary.

Below the available properties for each PLL node:

Below the available properties for each PLL node:

Line 286:

Line 382:

</pre>

</pre>

−

===== HSI and CSI clock calibration =====

+

===== HSI and CSI clocks calibration =====

−

[[How_to_activate_HSI_and_CSI_oscillators_calibration|Calibration]] is an optional feature that can be enabled from the device tree. It

+

The [[How_to_activate_HSI_and_CSI_oscillators_calibration|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:

allows requesting the HSI or CSI clock calibration by several means:

* SiP SMC service

* SiP SMC service

Line 299:

Line 395:

* st,hsi-cal: used to enable HSI clock calibration feature.

* st,hsi-cal: used to enable HSI clock calibration feature.

* st,csi-cal; used to enable CSI 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 processed for each incoming request.

+

* 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.