How to activate HSI and CSI oscillators calibration

Revision as of 00:10, 18 May 2022 by Registered User
Applicable for STM32MP13x lines, STM32MP15x lines

1. Article purpose[edit source]

The purpose of this article is to explain how to calibrate the HSI and CSI oscillators in the RCC, by using the OP-TEE calibration Pseudo Trusted Application(PTA) (see References), relying on TIM internal peripheral TIM12 and/or TIM15 counters assigned to the secure monitor: TF-A (Only on STM32MP15x lines More info.png) or OP-TEE. And the Linux client application, periodically called by a systemd[1] service. This systemd service is linked to a systemd timer, which defines when to call the application.

These clocks are internal oscillators whose frequency can be affected by temperature and voltage variations. To achieve a good clock accuracy, it is important to provide a mechanism to compensate the effects of these variations.

The clock calibration algorithm is based on the comparison of a timer (fed by HSI or CSI) and a clock that is derived from the HSE clock that is considered as always accurate.

Refer to STM32MP13 reference manuals or STM32MP15 reference manuals for detailed information on the timer channels that can be used for HSI or CSI calibration input.


2. Linux Daemon[edit source]

The Linux calibration client relies on the fact that STM32MPU boards supports the systemd suite that starts the system. This suite handles daemons execution with a huge quantity of settings.

Regarding clock calibration: a service, responsible for executing the client calibration binary is linked to a timer.

You can change the timer settings by editing the Timer section in the stm32mp-calibration.timer file. By default, the timer trigger is set to 1 min with an accuracy of 5 seconds, using the systemd timer OnCalendar and AccuracySec settings:

   [Timer]
   Unit=stm32mp-calibration.service
   OnBootSec=1min
   OnCalendar=*-*-* *:*:00
   AccuracySec=5sec

The Unit setting is used to specify which service should be called when the timer is triggered. The OnBootSec setting specifies the time after boot at which the timer should start.

3. OP-TEE PTA[edit source]

The calibration algorithm is implemented in the calibration driver, probed at boot time. It compares both clocks and programs a correction factor in the RCC peripheral. This driver includes the calibration PTA. It is triggered by command invocation from the calibration client while the session is opened between the non-secure and the secure world, in this case Linux and OP-TEE.

In other words, the client application opens a session to the calibration PTA in OP-TEE and ask for a calibration by invoking a calibration command. Then, it shuts down the session once it is done. See the OP-TEE documentation on Pseudo Trusted Application and Global Platform API in the references.

4. Calibration Sequence[edit source]

File:Calibration sequence.png
Clock calibration sequence


5. How to activate the calibration[edit source]

This is done in the device tree by setting the status property to "okay". See the Device tree for an explanation of the device-tree file.

HSI and CSI calibration are both enabled by default and defined at secure OS Device tree SoC level.

For STM32MP13:

  osc_calibration: osc-calibration {
           compatible = "st,osc-calibration";
           csi_calibration: csi-calibration {
                   compatible = "st,csi-cal";
                   counter = <&timers12 0 2>;
                   status = "disabled";
           };
           hsi_calibration: hsi-calibration {
                   compatible = "st,hsi-cal";
                   counter = <&timers12 0 1>;
                   status = "disabled";
           };
  };

At board level, it is possible to change the status which disables total or part of the calibration.

Example at board level:

  • Disable the CSI calibration and enable the HSI calibration:
 &osc_calibration {
         csi-calibration {
                status = "disabled";
         };
         hsi-calibration {
                status = "okay";
         };
 };

6. TF-A SP_MIN[edit source]

This is only applicable on STM32MP15x lines More info.png

6.1. Configuring the timers[edit source]

The timers used for calibration must be assigned to the secure context.

Example: timer12-input1 is used for HSI and timer12-input2 for CSI

  &timers12 {
             secure-status = "okay";
             st,hsi-cal-input = <1>;
             st,csi_cal-input = <2>;
  };
  &timers15 {
             secure-status = "disabled";
             st,hsi-cal-input = <7>;
             st,csi_cal-input = <8>;
  };

6.2. Enabling and configuring the calibration service[edit source]

This can be done by enabling options inside the clock device tree section




7. References[edit source]

  1. https://optee.readthedocs.io/en/latest/architecture/trusted_applications.html
  2. https://systemd.io/
  3. https://optee.readthedocs.io/en/latest/architecture/globalplatform_api.html