1. Article purpose[edit source]
The purpose of this article is to explain how the SCMI resources configuration are defined in U-Boot bootloader and Linux® kernel.
The configuration is performed using the device tree mechanism[1].
2. DT bindings documentation[edit source]
The SCMI services device tree bindings are defined in the Linux kernel source tree, in Arm SCMI DT bindings[2] documentation. This documentation only defines the SCMI agent configuration, to be used in U-Boot or Linux kernel device trees.
An SCMI agent, in U-Boot or Linux kernel is represented by a node named scmi in the firmware node of the device tree. Each SCMI protocol used is represented by a subnode of the scmi node. SCMI protocol nodes defines and registers resources enumerated by the server or listed in the agent's device tree.
Valid values for compatible property are listed in the SCMI DT bindings [2].
firmware {
scmi {
compatible = "...";
#address-cells = <1>;
#size-cells = <0>;
(...)
protocol@11 {
reg = <0x11>;
(...)
};
protocol@14 {
reg = <0x14>;
(...)
};
(...)
};
};
For example, the SCMI specification[3] defines the SCMI power domain management protocol with the protocol ID 0x11. Device tree represents this SCMI protocol as a power domain controller, also called a PM domain provider in [4] documentation, that exposes power domains to Linux kernel drivers. From SCMI communication, agent and server for that platform use well defined ID numbers for each power domain, called the domain ID in SCMI litterature.
As shown in the source code snipet below, the power domain provider is a subnode named protocol@11 of the scmi node. Each power domain exposed through this protocol is identified by well known ID number. A device consuming the SCMI agent's power domain ID 2 would refer to that power domain using the SCMI protocol node phandle, scmi_devpd1 here, and use the SCMI power domain ID 2 as phandle argument: e.g. power-domains = <&scmi_devpd1 2>;. The below DTSI source code snipet is extracted from the SCMI DT bindings documentation[2].
firmware {
scmi {
compatible = "arm,scmi-smc";
shmem = <&cpu_scp_lpri0 &cpu_scp_lpri1>;
arm,smc-id = <0xc3000001>;
#address-cells = <1>;
#size-cells = <0>;
scmi_devpd1: protocol@11 {
reg = <0x11>;
#power-domain-cells = <1>;
};
};
};
3. DT configuration[edit source]
When an STM32MPU platform is to operate with an SCMI server in secure OP-TEE world, the SCMI agent needs to be described in Linux kernel and U-Boot bootloader device tree data.
The SCMI devices are described by a node named scmi. Devices and providers registered by the SCMI agent driver are described by subnodes, one per SCMI protocol used by the agent using reg bindings rules to carry the protocol ID number. Property compatible defines the SCMI transport layer used, either "arm,scmi-smc" or "linaro,scmi-optee" whether embedding TF-A or OP-TEE respectively.
When the using a predefined area of sram compatible memory for exchanging SCMI messages between non-secure and secure worlds, the platform must have a shmem property in the scmi node that refers to the phandle of a related "arm,scmi-shmem" compatible nodes in the device tree to describe the shared memory.
3.1. SCMI agent when TF-A in secure world[edit source]
Compatible "arm,scmi-smc" requires node property shmem and a specific property: arm,smc-id = <FUNC_ID>; that defines the platform SMC function ID used for SCMI messages notification. When the platform defines a specific communication (couple SMC function ID and shared memory), the node of the SCMI protocol shall define both arm,smc-id and shmem properties in the SCMI protocol subnode.
Note that STM32MP15 platforms currently use a single channel with pre-allocated SYSRAM shared memory for SCMI, to expose clock and reset controllers, as show in the DTS extract below:
scmi_sram: sram@2ffff000 {
compatible = "mmio-sram";
reg = <0x2ffff000 0x1000>;
#address-cells = <1>;
#size-cells = <1>;
ranges = <0 0x2ffff000 0x1000>;
scmi_shm: scmi_shm@0 {
compatible = "arm,scmi-shmem";
reg = <0 0x80>;
};
};
firmware {
scmi: scmi {
compatible = "arm,scmi-smc";
arm,smc-id = <0x82002000>;
shmem = <&scmi_shm>;
#address-cells = <1>;
#size-cells = <0>;
scmi_clk: protocol@14 {
reg = <0x14>;
#clock-cells = <1>;
};
scmi_reset: protocol@16 {
reg = <0x16>;
#reset-cells = <1>;
};
};
};
3.2. SCMI agent when OP-TEE in secure world[edit source]
Compatible "linaro,scmi-optee" requires a specific property in the device node: linaro,optee-channel-id = <CHANNEL_ID>; where CHANNEL_ID is the channel identifer defined for the SCMI communication.
When the platform uses a predefined area of sram compatible memory for exchanging SCMI messages bet ween non-secure and secure worlds, the platform must set property shmem = <SOME_PHANDLE> in the protocol node, next to linaro,optee-channel-id property unless what the agent assumes that channel rely on an OP-TEE shared memory buffer dynamically allocated.
OP-TEE SCMI DT bindings permits SCMI protocol to be carried on specific channels, allows concurrent sending of messages. In such cases, the protocol subnode shall have property linaro,optee-channel-id defined with the expect channel ID. When the channel uses a predefined area of sram compatible memory, property shmem must be defined next to linaro,optee-channel-id property in the protocol node, unless what the channel is expected to use an OP-TEE shared memory buffer dynamically allocated.
The below example describes an OP-TEE SCMI firmware that exposes 2 channels. Channel 0 uses pre-defined shared memory and is used for SCMI base comminucation and for SCMI reset controls messaging. Channel 1 uses dynamically allocated shared memory and is used for a voltage regulator controller.
firmware {
scmi: scmi {
compatible = "linaro,scmi-optee";
linaro,optee-channel-id = <0>;
shmem = <&scmi_shm>;
#address-cells = <1>;
#size-cells = <0>;
scmi_clk: protocol@14 {
reg = <0x14>;
#clock-cells = <1>;
};
protocol@17 {
reg = <0x17>;
linaro,optee-channel-id = <1>;
regulators {
#address-cells = <1>;
#size-cells = <0>;
scmi_reg11: reg11@0 {
reg = <0>;
regulator-name = "reg11";
regulator-min-microvolt = <1100000>;
};
};
};
};
};
Note that STM32MP15 platforms currently use a single channel with pre-allocated SYSRAM shared memory for SCMI communication. The example below illustrates when SCMI server is embedded in OP-TEE firmware and is exposing clocks and reset controllers:
scmi_sram: sram@2ffff000 {
compatible = "mmio-sram";
reg = <0x2ffff000 0x1000>;
#address-cells = <1>;
#size-cells = <1>;
ranges = <0 0x2ffff000 0x1000>;
scmi_shm: scmi_shm@0 {
compatible = "arm,scmi-shmem";
reg = <0 0x80>;
};
};
firmware {
scmi: scmi {
compatible = "linaro,scmi-optee";
#address-cells = <1>;
#size-cells = <0>;
linaro,optee-channel-id = <0>;
shmem = <&scmi_shm>;
scmi_clk: protocol@14 {
reg = <0x14>;
#clock-cells = <1>;
};
scmi_reset: protocol@16 {
reg = <0x16>;
#reset-cells = <1>;
};
};
};
3.3. DT configuration for SCMI resource consumers[edit source]
All devices using SCMI clocks and reset controllers refer to the phandle of the related SCMI clock contoller node scmi_clk or SCMI reset controller node scmi_reset. For example, the CPU references an SCMI clock:
cpus {
#address-cells = <1>;
#size-cells = <0>;
cpu0: cpu@0 {
compatible = "arm,cortex-a7";
device_type = "cpu";
reg = <0>;
clocks = <&scmi_clk CK_SCMI_MPU>;
clock-names = "cpu";
operating-points-v2 = <&cpu0_opp_table>;
nvmem-cells = <&part_number_otp>;
nvmem-cell-names = "part_number";
#cooling-cells = <2>;
};
};
We can point also examples for I2C4 bus...
i2c4: i2c@5c002000 {
compatible = "st,stm32mp15-i2c";
reg = <0x5c002000 0x400>;
(...)
clocks = <&scmi_clk CK_SCMI_I2C4>;
resets = <&scmi_reset RST_SCMI_I2C4>;
(...)
};
... or the RTC device node.
rtc: rtc@5c004000 {
compatible = "st,stm32mp1-rtc";
reg = <0x5c004000 0x400>;
clocks = <&scmi_clk CK_SCMI_RTCAPB>,
<&scmi_clk CK_SCMI_RTC>;
clock-names = "pclk", "rtc_ck";
interrupts-extended = <&exti 19 IRQ_TYPE_LEVEL_HIGH>;
(...)
};
4. References[edit source]
Please refer to the following links for additional information:
- ↑ Device tree
- ↑ 2.0 2.1 2.2 Documentation/devicetree/bindings/firmware/arm,scmi.yaml Arm SCMI DT bindings
- ↑ https://developer.arm.com/documentation/den0056
- ↑ Documentation/devicetree/bindings/power/power-domain.yaml Power Domains DT bindings
Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere. 