SCMI overview

1. Article Purpose

The purpose of this article is to explain the SCMI services in STM32MPU.

SCMI stands for System Control and Management Interface. It refers to Arm SCMI specification. SCMI is a message driven interface where specific SCMI protocols expose stantdard services to control system resources.

For example, STM32MP15 uses SCMI to abstract RCC resources, as clock and reset controllers, assigned to secure world exclusive access by RCC TZEN configuration. Secure world embeds a SCMI server that exposes clock and reset controllers. Non-secure world uses SCMI drivers as SCMI clock driver clk-scmi.c and SCMI reset driver reset-scmi.c to handle the resource in the system.

2. What is SCMI and what is it used for

SCMI is a protocol based on message exchanged. It allows a resource master to expose device services to a client entity.

For example, the CPU clock cannot be freely manipulated by the non-secure world. Yet, Linux kernel executing in non-secure world may need to get or set the DDR frequency. Implementing a SCMI agent in non-secure world (Linux kernel, U-Boot bootloader) and a SCMI server in secure firmware (TF-A, OP-TEE) allows non-secure Linux kernel and U-Boot to natively discover the DDR clock as a standard clock device.

In the example, applied to STM32MP15, enabling security on the DDR clock is also related to enable the security on DDR controllers interfaces. DDR clock secure hardening is enabled from RCC interface. DDR controller access permissions are configure through ETZPC. STM32MP15 software release ensures platform configuration consistency.

3. STM32MP SCMI overview

SCMI on STM32MP is used to create server/client paths between secure and non-secure world to offer device driver services for chip resources when some firewall configurations are hardened.

In STM32MP software release, the secure world, TF-A or OP-TEE, embeds a SCMI server that exposes devices as clock and reset controllers that non-secure world cannot access straight due to the configuration loaded in STM32MP RCC security hardening.

STM32MP implements features from the SCMI specification (v2.0 or above) . TF-A and OP-TEE support necessary features of the SCMI base protocol and the several other used SCMI protocols (clock, reset, ...). These clock and reset controllers are related the chip resources bound to restricted access rights because of chip RCC secure hardening. For example, as stated in RCC security hardening, RCC TZEN configuration can restrict certain resource accesses.

STM32MP15 specific: since there are 2 levels of secure hardening, STM32MP15 exposes system resources over 2 channel, represented by 2 agents in non-secure world. SCMI agent 0 discovers clocks and reset hardened per RCC TZEN enabling. SCMI agent 1 discovers clocks hardended upon RCC MCKPROT enabling.

4. System resource exposed through SCMI

Chips of the STM32MP family uses SCMI to expose system resources under control of the secure world. Some of the secure hardened controllers, as clock, reset controller etc... can be assign to non-secure world exclusive (a reset controller) or shared access (a clock).

In secure world, peripherals assigned to secure world acquire resource that can strict access to the resource exposed as described above. Article How to assign an internal peripheral to a runtime context provide details on peripheral assignment. SCMI resources exposed to non-secure world that are refused resource access get an denied error status, but system description should not have non-secure world depending on a unreachable resource.

In non-secure world, SCMI allows the generic implementation (I.e. Linux and U-Boot SCMI drivers) to define system resources only with Device Tree technology. The Device Tree defines the SCMI agent nodes each listing the SCMI protocols probed and related exposed resources.

4.1. STM32MP15 SCMI bindings

STM32MP15 defines 2 SCMI agents:

• Agent SCMI0 exposes RCC resource (clocks, reset controllers) related to RCC TZEN hardening
• Agent SCMI1 exposes RCC clocks related to RCC MCKPROT hardening.

Each agent (SCMI0 and SCMI1) interface the secure SCMI server using a shared memory at top (higher addresses) in SYSRAM internal memory. Message notification and processing is invoke with CPU SMC/HVC instructions (see SMCCC). The device tree technology is used to fully describe SCMI resources in the Linux kernel or U-Boot firmware.

STM32MP15 DT clock bindings defines clock_id identifier values used by SCMI agents in SCMI clock protocol communication.

STM32MP15 DT reset bindings defines the domain_id identifiers used by SCMI agent in SCMI Reset Domain protocol communication.

Directly or Indirectly Linux kernel, U-Boot firmware as well as Device Tree technology reference a SCMI clock or a reset controller with the SCMI agent reference and the SCMI identifier (clock_id, domain_id)..

SCMI devices exposed to agent SCMI0 on STM32MP15:

• Clock and reset controllers for CRYP1, HASH1, RNG1, GPIOZ bank, I2C4 and I2C6, SPI6 and USART1.
• Clock controller for IWDG1, RTC, BSEC.
• Reset controller for MDMA
• MCU reset controller and MCU hold-on-boot controller. See also Linux remoteproc framework or U-Boot bootloader.
• System internal root clocks LSI, HSI and CSI, external root clocks LSE and HSE and PLL2 output clocks PLL2Q.

SCMI devices exposed to agent SCMI1 on STM32MP15:

• MCU clock. See also Linux remoteproc framework or U-Boot bootloader
• PLL3 output clocks PLL3Q and PLL3R.

5. STM32MP15 SCMI agents

Among all clocks and resets exposed by STM32MP15, see the list in the previous section, all but MCU clock and PLL3Q and PLL3R clocks are related to RCC TZEN hardening, the 3 later being related to RCC MCKPROT hardening.

When RCC TZEN hardening is enabled, non-secure world shall rely on SCMI agent 0 to access the desired resources.

When RCC MCKPROT hardening is enabled, non-secure world shall rely on SCMI agent 1 to access the desired resources.

Each agent interface uses a specific shared memory for SCMI message exchanges. A specific notification layer is also used between non-secure and secure worlds. The device tree technology is used the define the SCMI message transport configuration, in non-secure side. In secure world, the transport means are built-in firmware image. The used shared memories are all located at the top (highest addresses) in SYSRAM internal memory.

6. Device Tree description

The SCMI services device tree bindings are defined in the Linux kernel source tree in Arm SCMI DT bindings documentation.

6.1. SCMI agent nodes

Each SCMI agent is a subnode of the firmware node in the device tree description.

SCMI devices are described in the firmware node of the device tree, with compatible = "arm,scmi".

                scmi-agent {
                        compatible = "arm,scmi";

                        (...) /* SCMI transport properties */

                        /* Below are the discovered SCMI protocols */
                        protocol@X {
                                reg = <0xX>;
                                (...)
                        };
                        protocol@Y {
                                reg = <0xY>;
                                (...)
                        };
                };

6.2. STM32MP1 SCMI Transport

SCMI framework support several transport layers for message exchange. SCMI uses a transport built on mmio-sram shared memory instance with a smc-mbox mailbox device for message notification.

Shared memory device with mmio-sram. Device tree bindings offers compatible "mmio-sram" devices to described physical memory. It is supported by U-Boot and Linux kernel. In STM32MP1 memory layout, 2 shared memories in SYSRAM internal RAM are reserved for non-secure SCMI communication. In exmample below, phandle scmi0_shm refers to SYSRAM range [0x2FFFF000 0x2FFFF07F] used by SCMI agent 0 for client/server communication.

        sram@2ffff000 {
                compatible = "mmio-sram";
                reg = <0x2ffff000 0x1000>;
                #address-cells = <1>;
                #size-cells = <1>;
                ranges = <0 0x2ffff000 0x1000>;

                scmi0_shm: scmi_shm@0 {
                        reg = <0 0x80>;
                };
        };

Mailbox device: ad-hoc arm,smc-mbox.
STM32MP1 software release uses a SMC mailbox described with a "arm,smc-mbox" compatible node. Property arm,func-id defines the function ID used to invoke secure world for a specific SCMI agent/server interface.

        scmi0_mbox: mailbox-0 {
                #mbox-cells = <0>;
                compatible = "arm,smc-mbox";
                arm,func-id = <0x82002000>;
        };

In example below, SCMI agent 0 uses scmi0_mbox mailbox and scmi0_shm as shared memory.

        firmware {
                scmi0: scmi-0 {
                        compatible = "arm,scmi";
                        (...)
                        mboxes = <&scmi0_mbox 0>;
                        mbox-names = "txrx";
                        shmem = <&scmi0_shm>;
                        (...)
                };
        };

6.3. STM32MP15 SCMI device tree nodes

STM32MP15 exposes SCMI over 2 devices in the device tree description. One device per supported SCMI agents, hence two: one for the clocks and reset controllers related to RCC TZEN hardening configuration, and one for the clock controllers related to RCC MCKPROT hardening configuration.

As defined in Arm SCMI DT bindings, a SCMI agent node can contain one or more supported SCMI protocols. Each are described in a specific subnode of the agent node. STM32MP15 implements SCMI Clock protocol (ID 0x14) that is a clock provider device and SCMI Reset Domain protocol (ID 0x16) that is a reset controller provider device.

Example below shows a configuration supported in STM32MP15 software release.

        /* Shared memory used for SCMI agent/server communication */
        scmi_sram: sram@2ffff000 {
                compatible = "mmio-sram";
                reg = <0x2ffff000 0x1000>;
                #address-cells = <1>;
                #size-cells = <1>;
                ranges = <0 0x2ffff000 0x1000>;

                scmi0_shm: scmi_shm@0 {
                        reg = <0 0x80>;
                };
                scmi1_shm: scmi_shm@200 {
                        reg = <0x200 0x80>;
                };
        };

        /* Mailbox device used for SCMI agent/server communication */
        scmi0_mbox: mailbox-0 {
                #mbox-cells = <0>;
                compatible = "arm,smc-mbox";
                arm,func-id = <0x82002000>;
        };
        scmi1_mbox: mailbox-1 {
                #mbox-cells = <0>;
                compatible = "arm,smc-mbox";
                arm,func-id = <0x82002001>;
        };

        /* SCMI agent nodes, in the firmware node */
        firmware {
                scmi0: scmi-0 {
                        compatible = "arm,scmi";
                        #address-cells = <1>;
                        #size-cells = <0>;

                        status = "okay"; /* To enable upon RCC[TZEN] */
                        mboxes = <&scmi0_mbox 0>;
                        mbox-names = "txrx";
                        shmem = <&scmi0_shm>;

                        scmi0_clk: protocol@14 {
                                reg = <0x14>;
                                #clock-cells = <1>;
                        };
                        scmi0_reset: protocol@16 {
                                reg = <0x16>;
                                #reset-cells = <1>;
                        };
                };

                scmi1: scmi-1 {
                        compatible = "arm,scmi";
                        #address-cells = <1>;
                        #size-cells = <0>;

                        status = "disabled"; /* To enable upon RCC[MCKPROT] */
                        mboxes = <&scmi1_mbox 0>;
                        mbox-names = "txrx";
                        shmem = <&scmi1_shm>;

                        scmi1_clk: protocol@14 {
                                reg = <0x14>;
                                #clock-cells = <1>;
                        };
                };

7. How to go further

One can follow SCMI developments through TF-A mailing list and OP-TEE OS issuesand pull requestsforums.

System control and management interface

Arm^® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

Central processing unit

Linux^® is a registered trademark of Linus Torvalds.

Doubledata rate (memory domain)

Das U-Boot -- the universal boot loader (see U-Boot)

Trusted firmware for Arm^® Cortex^®-A

Open portable trusted execution environment

Reset and clock control

Secure monitor call

Secure monitor call (SMC) calling convention

Device tree

Microcontroller unit (MCUs have internal flash memory and are intended to operate with a minimum amount of external support ICs. They commonly are a self-contained, system-on-chip (SoC) designs.)

Random access memory (Early computer memories generally hadserial access. Memories where any given address can be accessed when desired were then called "random access" to distinguish them from the memories where contents can only be accessed in a fixed order. The term is used today for volatile random-acces ssemiconductor memories.)

Operating system