SCMI overview

Applicable for

STM32MP13x lines, STM32MP15x lines, STM32MP21x lines, STM32MP23x lines, STM32MP25x lines

1. Article Purpose[edit | edit source]

The purpose of this article is to explain the SCMI services used in OpenSTLinux distribution.

2. What is SCMI and what is it used for[edit | edit source]

SCMI stands for System Control and Management Interface. It refers to Arm^® SCMI specification^[1]. SCMI is a message driven interface between an SCMI agent (client) and an SCMI host (server). Specific SCMI protocols expose standard services to control system resources. SCMI can be used when there are resources hosted in an enclave, such as an isolated co-processor or the CPU secure world, and they need to be exposed to the normal world where U-Boot and Linux execute.

SCMI protocols allow the discovery of protocols, and exposed resources can provide asynchronous notifications from distant resource events. The SCMI integration includes a transport layer in charge of the communication between the client (SCMI agent) and the server (SCMI host).

U-Boot (v2021.01 and up) and Linux (v4.17 and up) implement an SCMI agent driver, some of the SCMI protocols and several communication transports: mailbox, smc, optee, ffa. OP-TEE (v3.9.0 and up) and TF-A (v2.5 and up) implement some SCMI protocols used by the few boards that embed SCMI host services. The Linux kernel Device Tree bindings documentation clearly defines how to describe an SCMI agent using DT technology.

OpenSTLinux is an illustrative example of SCMI usage, when a system hosts a normal world (U-Boot/Linux OS) and a secure world (such as OP-TEE) executing on the very same CPU, is the CPU dynamic clock scaling (Linux' DVFS) feature. As the secure world executes on the CPU, the normal world cannot freely manipulate the CPU clock configuration. In such systems, it is recommended to give full control of the CPU clock configuration to the secure world, which exposes restricted controls that the normal world can use to request CPU clock changes. SCMI provides this interface on the basis of a reviewed, evolutive and well-established specification with active maintainers in the open-source communities, especially Linux kernel, U-Boot, TF-A, and OP-TEE.

3. SCMI in OpenSTLinux BSP[edit | edit source]

The OpenSTLinux BSP implements a part of the SCMI specification ^[1] to create a server/client path between the secure and non-secure worlds. The exposed resources are related to resources that are possibly used by U-Boot or the Linux kernel, but are under exclusive control of the Cortex-A secure world in OP-TEE because of peripheral access firewall considerations.

3.1. Component description[edit | edit source]

The OpenSTLinux BSP implements an SCMI agent in both U-Boot bootloader and the Linux kernel, and implements an SCMI server in OP-TEE image. SCMI integration requires the SCMI agents implement the SCMI OP-TEE transport, defined in the Linux kernel and U-Boot bootloader associated Device tree scmi node.

STM32 Arm^® Cortex^® MPUs software deliveries embed OP-TEE in the secure world. OP-TEE exposes SCMI services for the clock, a reset controller, voltage regulator resources, and a performance management service for CPU DVFS support.

See STM32MP1 power overview or STM32MP2 power overview for integration details in OpenSTlinux.

Depending on the configuration of the secure world, not all exposed services can be used by the SCMI client. Requests for a disallowed service return an SCMI access denied return code, like when a reset control line is fully assigned to secure world services, meaning the normal world will not be able to act on that reset line through the exposed SCMI reset protocol.

Devices exposed by SCMI protocols are used by generic Linux device frameworks such as the regulator framework, the clock framework and reset framework to support power management.

3.2. API description[edit | edit source]

The SCMI specification ^[1] define

agent: caller of SCMI
platform: provider of SCMI
protocol: individual groups of system control and management message
the associated ID for each protocols are:
- 0x10 Base protocol
- 0x11 Power domain management protocol
- 0x12 System power management protocol
- 0x13 Performance domain management protocol
- 0x14 Clock management protocol
- 0x15 Sensor management protocol
- 0x16 Reset domain management protocol
- 0x17 Voltage domain management protocol
- 0x18 Power capping and monitoring protocol
- 0x19 Pin Control protocol
transport: method by which protocol messages are communicated between agents and the platform
- ACPI-based Transport
- Shared Memory or MMIO based Transport for FastChannels
- Virtio-SCMI
ressource: component controlled by SCMI messages

See SCMI specification for message and transport details.

Each resource is identified by a well-known ID, the domain_id, common between agent and platform.

The OP-TEE transport with device tree compatible linaro,scmi-optee, based on OP-TEE message is defined by OP-TEE and is used in OpenSTLinux.

4. Configuration[edit | edit source]

4.1. OP-TEE configuration[edit | edit source]

Refer to How to configure OP-TEE article for details on OP-TEE configuration.

The SCMI server is activated by default in OpenSTLinux, base on OP-TEE transport with compilation flag named CFG_SCMI_* in

core/arch/arm/plat-stm32mp1/conf.mk for STM32MP1 series
core/arch/arm/plat-stm32mp2/conf.mk for STM32MP2 series

SCMI is embedded in OP-TEE with one driver:

CFG_SCMI_MSG_DRIVERS, embeds SCMI message drivers in the core, selected default for STM32MP1 series, and activated protocol are:
- CFG_SCMI_MSG_CLOCK embeds SCMI clock protocol support.
- CFG_SCMI_MSG_RESET_DOMAIN embeds SCMI reset domain protocol support.
- CFG_SCMI_MSG_VOLTAGE_DOMAIN embeds SCMI voltage domain protocol support.
- CFG_SCMI_MSG_PERF_DOMAIN embeds SCMI performance domain management protocol (not used for STM32MP15x lines on STMicroelectronics boards, as I2C4, PMIC and DVFS is managed by Linux)
CFG_SCMI_SCPFW, embeds the reference SCMI server implementation provided by SCP firmware project^[2], selected by default for STM32MP2 series
- with CFG_SCMI_SCPFW_PRODUCT=optee-stm32mp2, the SCMI stack is configured with core/lib/scmi-server/conf-optee-stm32mp2.mk

For STM32MP15x lines , the secure world exposes clock and reset services for the related peripheral interface assigned to the secure world as per the RCC TZEN ("How to assign and configure the peripheral" chapter) configuration. For example, the I2C4 clock and reset controllers in the RCC subsystem can only be accessed from the secure world when RCC[TZEN]=1. If the overall system architecture assigns the I2C4 bus to the nonsecure world, both Linux OS and U-Boot bootloader shall access the I2C4 clock and reset controllers through the SCMI clock device driver and the SCMI reset device driver. Alternatively, if the overall system architecture assigns the I2C4 bus to the secure world, Linux and U-Boot will still see the I2C4 clock and reset through SCMI devices, but they will be unable to reset the bus or disable the bus clock.
On STM32MP15x lines STMicroelectronics boards the I2C4 is assigned to Linux.

4.2. U-Boot configuration[edit | edit source]

SCMI support is activated by default in ST deliveries with flags:

CONFIG_CLK_SCMI
CONFIG_DM_REGULATOR_SCMI
CONFIG_RESET_SCMI
CONFIG_SCMI_FIRMWARE
CONFIG_SCMI_AGENT_OPTEE

4.3. Kernel configuration[edit | edit source]

SCMI support is activated by default in ST deliveries.

The next flags are required and can not be deactivated:

CONFIG_ARM_SCMI_PROTOCOL
CONFIG_RESET_SCMI
CONFIG_COMMON_CLK_SCMI
CONFIG_REGULATOR_ARM_SCMI
CONFIG_ARM_SCMI_CPUFREQ
CONFIG_ARM_SCMI_TRANSPORT_OPTEE

The other protocol are not required. Nevertheless, if a specific configuration is needed, they can be activated in the kernel.

CONFIG_SENSORS_ARM_SCMI
CONFIG_ARM_SCMI_POWERCAP
CONFIG_IIO_SCMI

4.4. Device tree configuration[edit | edit source]

A detailed device tree configuration is described in SCMI device tree configuration.

5. Source code location[edit | edit source]

The SCMI framework is composed by OpenSTLinux components:

in OP-TEE:
- SCMI server for CFG_SCMI_MSG_DRIVERS:
  core/arch/arm/plat-stm32mp1/scmi_server.c
- SCMI server by SCPFW for CFG_SCMI_SCPFW:
  core/lib/scmi-server/SCP-firmware/
- SCMI PTA for OP-TEE transport activated with CFG_SCMI_PTA:
  core/pta/scmi.c
- STM32MP configuration files for SCMI server
  - for STM32MP1 series with CFG_SCMI_MSG_DRIVERS (default)
    core/arch/arm/plat-stm32mp1/scmi_server.c
    with SCMI defines the in binding files:
    - for STM32MP13x lines : core/include/dt-bindings/clock/stm32mp13-clks.h core/include/dt-bindings/reset/stm32mp13-resets.h core/include/dt-bindings/regulator/st,stm32mp13-regulator.h
    - for STM32MP15x lines : core/include/dt-bindings/clock/stm32mp1-clks.h core/include/dt-bindings/reset/stm32mp1-resets.h core/include/dt-bindings/regulator/st,stm32mp15-regulator.h
  - for STM32MP1 series with CFG_SCMI_SCPFW)
    core/arch/arm/plat-stm32mp1/scmi_server_scpfw.c
    core/lib/scmi-server/conf-optee-stm32mp1.mk
  - for STM32MP2 series with CFG_SCMI_SCPFW
    core/arch/arm/plat-stm32mp2/scmi_server_scpfw.c
    core/lib/scmi-server/conf-optee-stm32mp2.mk
    scmi {...} node in device tree SoC files: stm32mp251.dtsi | stm32mp231.dtsi | stm32mp211.dtsi
in Linux kernel:
- SCMI drivers: drivers/firmware/arm_scmi/
- SCMI protocol drivers for each framework:
  - regulator: drivers/regulator/scmi-regulator.c
  - clock: drivers/clk/clk-scmi.c
  - reset: drivers/reset/reset-scmi.c
  - cpufreq (DVFS) drivers/cpufreq/scmi-cpufreq.c
in U-Boot:
- SCMI drivers: drivers/firmware/scmi/
- SCMI protocol drivers for each uclass:
  - clock: drivers/clk/clk_scmi.c
  - regulator: drivers/power/regulator/scmi_regulator.c
  - reset: drivers/reset/reset-scmi.c

6. How to trace and debug the framework[edit | edit source]

6.1. How to monitor[edit | edit source]

Check device tree with:

ls /sys/firmware/devicetree/base/firmware/scmi

Check associated driver with:

ls /sys/bus/scmi_protocol/drivers/
ls /sys/devices/platform/firmware:scmi

Check associated TA in

ls /sys/bus/tee/drivers/scmi-optee

6.2. How to trace[edit | edit source]

Activate Ftrace to have access to TRACE_EVENT defined in include/trace/events/scmi.h and used in SCMI drivers.

6.3. How to debug[edit | edit source]

Activate trace in the associated SCMI driver at transport or protocol level for each components, e.g. OP-TEE or U-Boot.

Activate trace or use use sysfs for framework associated to each SCMI protocol such as the regulator framework, the clock framework and reset framework.

7. How to go further[edit | edit source]

See STM32MP1 power overview or STM32MP2 power overview for integration details in OpenSTlinux.

See power management for integration in Linux kernel with the associated frameworks:

See the next pages for SCMI usage examples:

8. References[edit | edit source]

↑ ^1.0 ^1.1 ^1.2 Arm System Control and Management Interface Platform Design Document (SCMI) specification:
https://developer.arm.com/documentation/den0056
↑ System Control Processor (SCP) firmware: https://gitlab.arm.com/firmware/SCP-firmware

[SCMI-1] 1.0 ^1.1 ^1.2 Arm System Control and Management Interface Platform Design Document (SCMI) specification:
https://developer.arm.com/documentation/den0056

[2] System Control Processor (SCP) firmware: https://gitlab.arm.com/firmware/SCP-firmware

[1]

[2]