Difference between revisions of "SCMI overview"

[quality revision] [pending revision]
m
m (What is SCMI and what is it used for)
 

1 Article Purpose[edit]

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

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

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

STM32MP15 uses SCMI to abstrat RCC resources, as clock and reset controllers, assigned to secure world excluvie 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[2] and SCMI reset driver reset-scmi.c[3] to handle the resource in the system.

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


SCMI is a protocol based on message exchanged. It allows a resource master to expose device services to a client entity SCMI is a set of protocols based on message exchanged to discover resources, control devices and get notification. It allows a resource owner to expose device services to a client entity. The resource owner, exposing service, is called a platform server in SCMI literature, the client is an SCMI agent. The communication, SCMI messages exchange, is handled by a SCMI transport.

SCMI allows to expose device service in a generic manner portable to various environments.

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 nattily 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 STM32MP15 SCMI overview3 STM32MP use of SCMI[edit]

SCMI on STM32MP15 is used STM32MP implements features from the SCMI specification (v2.0 or above) [2] to create server/client paths between secure and non-secure worldworlds to offer device driver services for the SoC resource chip resources when some firewalls configuration firewall configurations are hardened.

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


In STM32MP15 software release, secure world exposes some clock and reset controllers to non-secure world. Secure world can be TF-A or OP-TEE. They implement features from the SCMI specification v2.0 [4]. TF-A and OP-TEE supports necessary features from SCMI Base: clock, reset, domain protocols. These clock and reset controllers are related the SoC configuration that grants write access to specific RCC interface register. As stated in RCC security hardening, RCC TZEN restricts certain resource accesses, RCC MCKPROT restricts even more resource accesses.

Since there are 2 levels of secure hardening, STM32MP1 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 STM32MP15 SCMI clocks and reset[edit]

In STM32MP15, SCMI exposes resource for the peripheral interfaces listed below. Note that when a related device is assigned to secure world by system configuration (see , 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 for further information), the SCMI controls, even if exposed, will not allow non-secure world to effectively access the resource. The SCMI clock protocol phandle together with the clock ID, supported values are defined in STM32MP1 DT clock bindings[5], forms a unique identifer for the clock resources in 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 a generic SCMI implementation (i.e. Linux and U-Boot executable.

The SCMI reset domain protocol phandle together with the agent reset domain ID, supported values are defined in STM32MP1 DT reset bindings[6], forms a unique identifer for the reset controller resources.

  • SCMI exposes CRYP1 clock with ID CK_SCMI0_CRYP1 to non-secure agent 0.
    SCMI exposes CRYP1 reset with ID RST_SCMI0_CRYP1 to non-secure agent 0.
  • SCMI exposes HASH1 clock with ID CK_SCMI0_HASH1 to non-secure agent 0.
    SCMI exposes HASH1 reset with ID RST_SCMI0_CRYP1 to non-secure agent 0.
  • SCMI exposes RNG1 clock with ID CK_SCMI0_RNG1 to non-secure agent 0.
    SCMI exposes RNG1 reset with ID RST_SCMI0_RNG1 to non-secure agent 0.
  • SCMI exposes BSEC clock with ID CK_SCMI0_BSEC to non-secure agent 0.
  • SCMI exposes GPIOZ bank clock with ID CK_SCMI0_GPIOZ to non-secure agent 0.
    SCMI exposes GPIOZ bank reset with ID RST_SCMI0_GPIOZ to non-secure agent 0.
  • SCMI exposes I2C4 and I2C6 clock with ID CK_SCMI0_I2Cx to non-secure agent 0.
    SCMI exposes I2C4 and I2C6 reset with ID RST_SCMI0_I2Cx to non-secure agent 0.
  • SCMI exposes SPI6 clock with ID CK_SCMI0_SPI6 to non-secure agent 0.
    SCMI exposes SPI6 reset with ID RST_SCMI0_SPI6 to non-secure agent 0.
  • SCMI exposes USART1 clock with ID CK_SCMI0_USART1 to non-secure agent 0.
    SCMI exposes USART1 reset with ID RST_SCMI0_USART1 to non-secure agent 0.
  • SCMI exposes IWDG1 bus clock with ID CK_SCMI0_IWDG1 to non-secure agent 0.
  • SCMI exposes RTC clock controller with ID CK_SCMI0_RTC to non-secure agent 0.
  • SCMI exposes MDMA reset controller with ID CK_SCMI0_MDMA to non-secure agent 0.
SCMI exposes MCU clock to non-secure agent 1 with ID CK_SCMI1_MCU.
SCMI exposes MCU reset to non-secure agent 0 with ID RST_SCMI0_MCU.
They can be used for coprocessor startup whether via

SCMI drivers) to discover, identify and register system resources. For example the Linux SCMI clock driver clk-scmi.c[3] and SCMI reset controller driver reset-scmi.c[4].

The Device Tree technology is used to describe to Linux and U-Boot the SCMI resources, those used to realize SCMI communiaction and the system resources exposed through SCMI protocols.



3.1 STM32MP15[edit]

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 invoked 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[5] defines clock_id identifier values used by SCMI agents in SCMI clock protocol communication.

STM32MP15 DT reset bindings[6] 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:

  • SCMI exposes PLL2Q and PLL2R to non-secure agent 0
    with IDs CK_SCMI0_PLL2_Q and CK_SCMI0_PLL2_R.
  • SCMI exposes PLL3Q and PLL3R to non-secure agent 1
    with IDs CK_SCMI1_PLL3_Q and CK_SCMI1_PLL3_R.

5 STM32MP15 SCMI agents[edit]

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 shared memories used are all located at the top (high addresses) is SYSRAM internal memory.

6
  • and PLL2 output clocks PLL2Q.


SCMI devices exposed to agent SCMI1 on STM32MP15:

4 Device Tree description[edit]

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

6.1 SCMI agent nodes[edit]

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[edit]

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[edit]

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[8], 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

Device Tree bindings for SCMI on STM32MP are detailed in the SCMI device tree configuration article.

5 How to go further[edit]

One can follow SCMI developments through TF-A mailing list[98] and OP-TEE OS issues[109] and pull requests[1110] forums.

8 6 References[edit]

https://developer.arm.com/docs/den0056/latest Documentation/devicetree/bindings/arm/arm,scmi.txt Arm SCMI DT bindings


== Article Purpose ==
The purposespurpose of this article is to explain the SCMI services in STM32MPU.
SCMI == What is SCMI and what is it used for ==

SCMI stands for System Control and MagagementManagement Interface. It refers to Arm SCMI specification<ref>https://developer.arm.com/architectures/system-architectures/software-standards/scmi</ref>. SCMI is a message driven interface where specific SCMI protocols expose statndard service for system resources.

STM32MP15 uses SCMI to abstrat [[RCC_internal_peripheral|RCC]] resources, as clock and reset controllers, assigned to secure world excluvie access by [[RCC_internal_peripheral#Security_support|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''<ref name="Linux_clk_scmi_c">{{CodeSource | Linux kernel | drivers/clk/clk-scmi.c | Linux drivers/clk/clk-scmi.c}}</ref> and SCMI reset driver ''reset-scmi.c''<ref name="Linux_reset_scmi_c">{{CodeSource | Linux kernel | drivers/reset/reset-scmi.c | Linux drivers/reset/reset-scmi.c}}</ref> to handle the resource in the system.

==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 entitystantdard services to control system resources.
{{ReviewsComments | [[User:Erwan Le Ray|Erwan Le Ray]] ([[User talk:Erwan Le Ray|talk]]) 12:06, 25 March 2021 (CET) - typo in "stantdard", you should mean "standard" ?}}

SCMI is a set of protocols based on message exchanged to discover resources, control devices and get notification. It allows a resource owner
to expose device services to a client entity. The resource owner, exposing service, is called a platform server in SCMI literature, the client is an SCMI agent. The communication, SCMI messages exchange, is handled by a SCMI transport.

SCMI allows to expose device service in a generic manner portable to various environments.

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 nativelynattily 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_internal_peripheral|RCC interface]]. DDR controller access
permissions are configure through [[ETZPC_internal_peripheral|ETZPC]].
STM32MP15 software release ensures platform configuration consistency.

== STM32MP15 SCMI overview ==

SCMI on STM32MP15 is used {{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 11:31, 5 March 2021 (CET)<br />nattily : not sure this is the right word you wanted to use... or I do not understand correctly}}

== STM32MP use of SCMI ==
STM32MP implements features from the SCMI specification (v2.0 or above)<ref>https://developer.arm.com/docs/den0056/latest</ref> to create server/client paths between
[[Security_overview#Secure_and_non-secure_worlds|secure and non-secure worldworlds]] to offer
device driver services for the SoC resource chip resources when some [[Security_overview#Firewall|firewalls]]
configuration firewall]] 
configurations are hardened.

In STM32MP1STM32MP software release, the secure world, being is [[TF-A_overview|TF-A]] or [[OP-TEE_overview|OP-TEE]],
embeds . They both embed a SCMI server that exposes clock and reset controllers that non-secure
world cannot access straight due to the configuration loaded in STM32MP1
[[RCC_internal_peripheral#Security_support|RCC security hardening]].

In STM32MP15 software release, secure world exposes some devices as clock and reset controllers to non-secure world. Secure world can be [[TF-A_overview|TF-A]] or [[OP-TEE_overview|OP-TEE]].
They implement features from the SCMI specification v2.0<ref>https://developer.arm.com/docs/den0056/latest</ref>. [[TF-A_overview|TF-A]] and
[[OP-TEE_overview|OP-TEE]] supports necessary features from SCMI Base: clock, reset, domain protocols.
These clock and reset controllers are related the SoC configuration that grants
write access to specific RCC interface register.
As stated in [[RCC_internal_peripheral#Security_support|RCC security hardening]],
RCC TZEN restricts certain resource accesses, RCC MCKPROT restricts
even more resource accesses.

Since there are 2 levels of secure hardening, STM32MP1 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.

== STM32MP15 SCMI clocks and reset ==

In STM32MP15, SCMI exposes resource for the peripheral interfaces listed below. Note that when a related device is assigned to secure world by system configuration (see .

{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 11:35, 5 March 2021 (CET)<br />The sentence below is not clear ("In secure world, peripherals assigned to secure world acquire resource that can strict access to the resource exposed as described above")}}
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]] for further information), the SCMI controls, even if exposed, will not allow non-secure world to effectively access the resource.

The SCMI clock protocol phandle together with the clock ID, supported values
are defined in STM32MP1 DT clock bindings<ref>{{CodeSource | TF-A | include/dt-bindings/clock/stm32mp1-clks.h}}stm32mp1 DT clocks bindings</ref>, forms a unique identifer for the clock resources in Linux and U-Boot executable.

The SCMI reset domain protocol phandle together with the agent reset domain ID,
supported values are defined in STM32MP1 DT reset bindings<ref>{{CodeSource | TF-A | include/dt-bindings/reset/stm32mp1-resets.h}}stm32mp1 DT reset bindings</ref>,
forms a unique identifer for the reset controller resources.

* SCMI exposes [[CRYP_internal_peripheral | CRYP1]] clock with ID CK_SCMI0_CRYP1 to non-secure agent 0.<br/>SCMI exposes [[CRYP_internal_peripheral | CRYP1]] reset with ID RST_SCMI0_CRYP1 to non-secure agent 0.

* SCMI exposes [[HASH_internal_peripheral | HASH1]] clock with ID CK_SCMI0_HASH1 to non-secure agent 0.<br/>SCMI exposes [[HASH_internal_peripheral | HASH1]] reset with ID RST_SCMI0_CRYP1 to non-secure agent 0.

* SCMI exposes [[RNG_internal_peripheral | RNG1]] clock with ID CK_SCMI0_RNG1 to non-secure agent 0.<br/>SCMI exposes [[RNG_internal_peripheral | RNG1]] reset with ID RST_SCMI0_RNG1 to non-secure agent 0.

* SCMI exposes [[BSEC_internal_peripheral | BSEC]] clock with ID CK_SCMI0_BSEC to non-secure agent 0.

* SCMI exposes [[GPIO_internal_peripheral | GPIOZ bank]] clock with ID CK_SCMI0_GPIOZ to non-secure agent 0.<br/>SCMI exposes [[GPIO_internal_peripheral | GPIOZ bank]] reset with ID RST_SCMI0_GPIOZ to non-secure agent 0.

* SCMI exposes [[I2C_internal_peripheral | I2C4 and I2C6]] clock with ID CK_SCMI0_I2Cx to non-secure agent 0.<br/>SCMI exposes [[I2C_internal_peripheral | I2C4 and I2C6]] reset with ID RST_SCMI0_I2Cx to non-secure agent 0.

* SCMI exposes [[SPI_internal_peripheral | SPI6]] clock with ID CK_SCMI0_SPI6 to non-secure agent 0.<br/>SCMI exposes [[SPI_internal_peripheral | SPI6]] reset with ID RST_SCMI0_SPI6 to non-secure agent 0.

* SCMI exposes [[USART_internal_peripheral | USART1]] clock with ID CK_SCMI0_USART1 to non-secure agent 0.<br/>SCMI exposes [[USART_internal_peripheral | USART1]] reset with ID RST_SCMI0_USART1 to non-secure agent 0.

* SCMI exposes [[IWDG_internal_peripheral | IWDG1]] bus clock with ID CK_SCMI0_IWDG1 to non-secure agent 0.

* SCMI exposes [[RTC_internal_peripheral | RTC]] clock controller with ID CK_SCMI0_RTC to non-secure agent 0.

* SCMI exposes [[MDMA_internal_peripheral | MDMA]] reset controller with ID CK_SCMI0_MDMA to non-secure agent 0.

* SCMI exposes MCU clock to non-secure agent 1 with ID CK_SCMI1_MCU.<br/>SCMI exposes MCU reset to non-secure agent 0 with ID RST_SCMI0_MCU.<br/> They can be used for coprocessor startup whether via [[Linux remoteproc framework overview|Linux remoteproc framework]] or [[How to start the coprocessor from the bootloader|U-Boot bootloader]].

* SCMI exposes internal root clocks [[RCC_internal_peripheral | LSI, HSI and CSI]] to non-secure agent 0<br/> with IDs CLK_SCMI0_LSI, CLK_SCMI0_HSI and CLK_SCMI0_CSI.
* SCMI exposes external root clocks [[RCC_internal_peripheral | LSE and HSE]] to non-secure agent 0<br/> with IDs CK_SCMI0_HSE and CK_SCMI0_LSE.

* SCMI exposes PLL2Q and PLL2R to non-secure agent 0<br/> with IDs CK_SCMI0_PLL2_Q and CK_SCMI0_PLL2_R.
* SCMI exposes PLL3Q and PLL3R to non-secure agent 1<br/> with IDs CK_SCMI1_PLL3_Q and CK_SCMI1_PLL3_R.

== 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 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.
{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 11:36, 5 March 2021 (CET)<br />The sentence above is not clear ("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 a generic SCMI implementation (i.e. Linux and U-Boot SCMI drivers) to discover, identify and register system resources. For example the Linux SCMI clock driver ''clk-scmi.c''<ref name="Linux_clk_scmi_c">{{CodeSource | Linux kernel | drivers/clk/clk-scmi.c | Linux drivers/clk/clk-scmi.c}}</ref> and SCMI reset controller driver ''reset-scmi.c''<ref name="Linux_reset_scmi_c">{{CodeSource | Linux kernel | drivers/reset/reset-scmi.c | Linux drivers/reset/reset-scmi.c}}</ref>.

The Device Tree technology is used to describe to Linux and U-Boot the SCMI resources, those used to realize SCMI communiaction and the system resources exposed through SCMI protocols.
{{ReviewsComments|-- [[User:Loic Pallardy|Loic Pallardy]] ([[User talk:Loic Pallardy|talk]]) 08:58, 13 November 2020 (CET)<br />An overview figure will be nice somewhere. it will allow to list all services and also identify drivers used}}
{{ReviewsComments|-- [[User:Etienne Carriere|Etienne Carriere]] ([[User talk:Etienne Carriere|talk]]) 14:45, 7 January 2021 (CET)<br />Addressed with illustration below.}}
{{ReviewsComments|-- [[User:Loic Pallardy|Loic Pallardy]] ([[User talk:Loic Pallardy|talk]]) 08:38, 19 February 2021 (CET)<br />Should we clearly show reset-scmi and clk-scmi drivers?}}
[[File:SCMI agent-server illustration.png|center]]

=== STM32MP15 ===

STM32MP15 defines 2 SCMI agents: 
* Agent SCMI0 exposes RCC resource (clocks, reset controllers) related to [[RCC_internal_peripheral#Security_support|RCC TZEN]] hardening, the 3
later being  

* Agent SCMI1 exposes RCC clocks related to [[RCC_internal_peripheral#Security_support|RCC MCKPROT]] hardening.
When [[RCC_internal_peripheral#Security_support|RCC TZEN]] hardening is enabled, non-secure world shall rely on SCMI agent 0 to access the desired resources.

When [[RCC_internal_peripheral#Security_support|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
worldsEach agent (SCMI0 and SCMI1) interface the secure SCMI server using a shared memory at top (higher addresses) in [[SYSRAM_internal_memory|SYSRAM internal memory]]. Message notification and processing is invoked with CPU SMC/HVC instructions (see SMCCC). The [[Device_tree|device tree]] technology is used the define theto fully describe SCMI message transport configuration, in non-secure side. In secure world, the
transport means are built-in firmware image. The shared memories used are all
located at the top (high addresses) is [[SYSRAM_internal_memory|SYSRAM internal memory]].

== Device Tree description ==

The SCMI services device tree bindings are defined in the Linux kernel source tree in Arm SCMI DT bindings<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/arm/arm,scmi.txt}}Arm SCMI DT bindings</ref> documentation.

=== 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"''.
<pre>

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

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

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


=== 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.
<pre>

        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>;
                };
        };</pre>


Mailbox device: ad-hoc ''arm,smc-mbox''.<br/>

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

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


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

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


=== STM32MP15 SCMI device tree nodes ===

STM32MP15 exposes SCMI over 2 devices in the [[Device_tree|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 resources in the Linux kernel or U-Boot firmware. 
{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 11:52, 5 March 2021 (CET)<br />a reference or link is missing for SMCCC}}
{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 11:52, 5 March 2021 (CET)<br />HVC : why ? (if the answer is given in the SMCCC reference from the previous comment, ignore this one)}}

STM32MP15 DT clock bindings<ref>{{CodeSource | TF-A | include/dt-bindings/clock/stm32mp1-clks.h}}stm32mp1 DT clocks bindings</ref> defines clock_id identifier values used by SCMI agents in SCMI clock protocol communication.

STM32MP15 DT reset bindings<ref>{{CodeSource | TF-A | include/dt-bindings/reset/stm32mp1-resets.h}}stm32mp1 DT reset bindings</ref> defines the domain_id identifiers used by SCMI agent in SCMI Reset Domain protocol communication.

{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 11:55, 5 March 2021 (CET)<br />In the sentence below, "Directly or Indirectly" is confusing : can you clarify or remove if this detail is not required here ? Moreover, it is strange to put Linux/U-Boot and Device Tree technology at the same level because the first ones are consumers of the second one}}
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:<br/>

* Clock and reset controllers for [[CRYP_internal_peripheral | CRYP1]], [[HASH_internal_peripheral | HASH1]], [[RNG_internal_peripheral | RNG1]], [[GPIO_internal_peripheral | GPIOZ bank]], [[I2C_internal_peripheral | I2C4 and I2C6]], [[SPI_internal_peripheral | SPI6]] and  [[USART_internal_peripheral | USART1]].
* Clock controller for [[IWDG_internal_peripheral | IWDG1]], [[RTC_internal_peripheral | RTC]],  [[BSEC_internal_peripheral | BSEC]].
* Reset controller for [[MDMA_internal_peripheral | MDMA]]
* MCU reset controller and MCU hold-on-boot controller. See also [[Linux remoteproc framework overview|Linux remoteproc framework]] or [[How to start the coprocessor from the bootloader|U-Boot bootloader]].
* System internal root clocks [[RCC_internal_peripheral | LSI, HSI and CSI]], external root clocks [[RCC_internal_peripheral | LSE and HSE]] and PLL2 output clocks PLL2Q.
{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 12:03, 5 March 2021 (CET)<br />Only PLL2Q (for the GPU) ? Can you explain why and tell how the PLL1 can be controlled if not with SCMI0 ?}}

SCMI devices exposed to agent SCMI1 on STM32MP15:<br/>

* MCU clock.  See also [[Linux remoteproc framework overview|Linux remoteproc framework]] or [[How to start the coprocessor from the bootloader|U-Boot bootloader]]
* PLL3 output clocks PLL3Q and PLL3R.

== Device Tree description ==
The SCMI services device tree bindings are defined in the Linux kernel source tree in Arm SCMI DT bindings<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/arm/arm,scmi.txt}}Arm SCMI DT bindings</ref>, 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.
<pre>

        /* 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>;
                        };
                };</pre>


== documentation.

Device Tree bindings for SCMI on STM32MP are detailed in the [[SCMI_device_tree_configuration|SCMI device tree configuration article]].

==How to go further==

One can follow SCMI developments through TF-A mailing list<ref>https://lists.trustedfirmware.org/mailman/listinfo/tf-a</ref> and OP-TEE OS issues<ref>https://github.com/OP-TEE/optee_os/issues</ref> and  pull requests<ref>https://github.com/OP-TEE/optee_os/pulls</ref> forums.

==References==<references/>

<noinclude>

[[Category:Platform security]]
{{PublicationRequestId | <None> | 2018-10-22 | EtienneCTBC | TBC| }}
{{ArticleBasedOnModel | Internal peripheral article model}}

[[Category:Device tree configuration]]
[[Category:Clock]]
[[Category:Reset]]</noinclude>
(48 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
== Article Purpose ==
 
== Article Purpose ==
The purposes of this article is to explain the SCMI services in STM32MPU.
+
The purpose of this article is to explain the SCMI services in STM32MPU.
   
SCMI stands for System Control and Magagement Interface. It refers to Arm SCMI specification<ref>https://developer.arm.com/architectures/system-architectures/software-standards/scmi</ref>. SCMI is a message driven interface where specific SCMI protocols expose statndard service for system resources.
+
== What is SCMI and what is it used for ==
   
STM32MP15 uses SCMI to abstrat [[RCC_internal_peripheral|RCC]] resources, as clock and reset controllers, assigned to secure world excluvie access by [[RCC_internal_peripheral#Security_support|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''<ref name="Linux_clk_scmi_c">{{CodeSource | Linux kernel | drivers/clk/clk-scmi.c | Linux drivers/clk/clk-scmi.c}}</ref> and SCMI reset driver ''reset-scmi.c''<ref name="Linux_reset_scmi_c">{{CodeSource | Linux kernel | drivers/reset/reset-scmi.c | Linux drivers/reset/reset-scmi.c}}</ref> to handle the resource in the system.
+
SCMI stands for System Control and Management Interface. It refers to Arm SCMI specification<ref>https://developer.arm.com/architectures/system-architectures/software-standards/scmi</ref>. SCMI is a message driven interface where specific SCMI protocols expose stantdard services to control system resources.
  +
{{ReviewsComments | [[User:Erwan Le Ray|Erwan Le Ray]] ([[User talk:Erwan Le Ray|talk]]) 12:06, 25 March 2021 (CET) - typo in "stantdard", you should mean "standard" ?}}
   
==What is SCMI and what is it used for ==
+
SCMI is a set of protocols based on message exchanged to discover resources, control devices and get notification. It allows a resource owner
  +
to expose device services to a client entity. The resource owner, exposing service, is called a platform server in SCMI literature, the client is an SCMI agent. The communication, SCMI messages exchange, is handled by a SCMI transport.
   
SCMI is a protocol based on message exchanged. It allows a resource master
+
SCMI allows to expose device service in a generic manner portable to various environments.
to expose device services to a client entity.
 
   
 
For example, the CPU clock cannot be freely manipulated by the non-secure world.
 
For example, the CPU clock cannot be freely manipulated by the non-secure world.
Line 15: Line 16:
 
Implementing a SCMI agent in non-secure world (Linux kernel, U-Boot bootloader) and a SCMI server
 
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
 
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.
+
U-Boot to nattily discover the DDR clock as a standard clock device.
  +
{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 11:31, 5 March 2021 (CET)<br />nattily : not sure this is the right word you wanted to use... or I do not understand correctly}}
   
In the example, applied to STM32MP15, enabling security on the DDR
+
== STM32MP use of SCMI ==
clock is also related to enable the security on DDR controllers
+
STM32MP implements features from the SCMI specification (v2.0 or above)
interfaces. DDR clock secure hardening is enabled from
+
<ref>https://developer.arm.com/docs/den0056/latest</ref> to create server/client paths between
[[RCC_internal_peripheral|RCC interface]]. DDR controller access
+
[[Security_overview#Secure_and_non-secure_worlds|secure and non-secure worlds]] to offer
permissions are configure through [[ETZPC_internal_peripheral|ETZPC]].
+
device driver services for chip resources when some [[Security_overview#Firewall|firewall]]  
STM32MP15 software release ensures platform configuration consistency.
+
configurations are hardened.
   
== STM32MP15 SCMI overview ==
+
In STM32MP software release, the secure world is [[TF-A_overview|TF-A]] or [[OP-TEE_overview|OP-TEE]]. They both embed a SCMI server that exposes devices as clock and reset controllers.
   
SCMI on STM32MP15 is used to create server/client paths
+
{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 11:35, 5 March 2021 (CET)<br />The sentence below is not clear ("In secure world, peripherals assigned to secure world acquire resource that can strict access to the resource exposed as described above")}}
between [[Security_overview#Secure_and_non-secure_worlds|secure and non-secure world]]
+
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.
to offer device driver services for the SoC resource when some [[Security_overview#Firewall|firewalls]]
+
{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 11:36, 5 March 2021 (CET)<br />The sentence above is not clear ("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.")}}
configuration are hardened.
 
   
In STM32MP1 software release, the secure world, being [[TF-A_overview|TF-A]] or [[OP-TEE_overview|OP-TEE]],
+
In non-secure world, SCMI allows a generic SCMI implementation (i.e. Linux and U-Boot SCMI drivers) to discover, identify and register system resources. For example the Linux SCMI clock driver ''clk-scmi.c''<ref name="Linux_clk_scmi_c">{{CodeSource | Linux kernel | drivers/clk/clk-scmi.c | Linux drivers/clk/clk-scmi.c}}</ref> and SCMI reset controller driver ''reset-scmi.c''<ref name="Linux_reset_scmi_c">{{CodeSource | Linux kernel | drivers/reset/reset-scmi.c | Linux drivers/reset/reset-scmi.c}}</ref>.
embeds a SCMI server that exposes clock and reset controllers that non-secure
 
world cannot access straight due to the configuration loaded in STM32MP1
 
[[RCC_internal_peripheral#Security_support|RCC security hardening]].
 
   
In STM32MP15 software release, secure world exposes some clock and reset
+
The Device Tree technology is used to describe to Linux and U-Boot the SCMI resources, those used to realize SCMI communiaction and the system resources exposed through SCMI protocols.
controllers to non-secure world. Secure world can be [[TF-A_overview|TF-A]] or [[OP-TEE_overview|OP-TEE]].
+
{{ReviewsComments|-- [[User:Loic Pallardy|Loic Pallardy]] ([[User talk:Loic Pallardy|talk]]) 08:58, 13 November 2020 (CET)<br />An overview figure will be nice somewhere. it will allow to list all services and also identify drivers used}}
They implement features from the SCMI specification v2.0
+
{{ReviewsComments|-- [[User:Etienne Carriere|Etienne Carriere]] ([[User talk:Etienne Carriere|talk]]) 14:45, 7 January 2021 (CET)<br />Addressed with illustration below.}}
<ref>https://developer.arm.com/docs/den0056/latest</ref>. [[TF-A_overview|TF-A]] and
+
{{ReviewsComments|-- [[User:Loic Pallardy|Loic Pallardy]] ([[User talk:Loic Pallardy|talk]]) 08:38, 19 February 2021 (CET)<br />Should we clearly show reset-scmi and clk-scmi drivers?}}
[[OP-TEE_overview|OP-TEE]] supports necessary features from SCMI Base: clock, reset, domain protocols.
+
[[File:SCMI agent-server illustration.png|center]]
These clock and reset controllers are related the SoC configuration that grants
 
write access to specific RCC interface register.
 
As stated in [[RCC_internal_peripheral#Security_support|RCC security hardening]],
 
RCC TZEN restricts certain resource accesses, RCC MCKPROT restricts
 
even more resource accesses.
 
   
Since there are 2 levels of secure hardening, STM32MP1 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.
 
   
== STM32MP15 SCMI clocks and reset ==
+
=== STM32MP15 ===
   
In STM32MP15, SCMI exposes resource for the peripheral interfaces listed below. Note that when a related device is assigned to secure world by system configuration (see [[How to assign an internal peripheral to a runtime context]] for further information), the SCMI controls, even if exposed, will not allow non-secure world to effectively access the resource.
+
STM32MP15 defines 2 SCMI agents:
  +
* Agent SCMI0 exposes RCC resource (clocks, reset controllers) related to [[RCC_internal_peripheral#Security_support|RCC TZEN]] hardening
  +
* Agent SCMI1 exposes RCC clocks related to [[RCC_internal_peripheral#Security_support|RCC MCKPROT]] hardening.
   
The SCMI clock protocol phandle together with the clock ID, supported values
+
Each agent (SCMI0 and SCMI1) interface the secure SCMI server using a shared memory at top (higher addresses) in [[SYSRAM_internal_memory|SYSRAM internal memory]]. Message notification and processing is invoked with CPU SMC/HVC instructions (see SMCCC). The [[Device_tree|device tree]] technology is used to fully describe SCMI resources in the Linux kernel or U-Boot firmware.
are defined in STM32MP1 DT clock bindings<ref>{{CodeSource | TF-A | include/dt-bindings/clock/stm32mp1-clks.h}}stm32mp1 DT clocks bindings</ref>, forms a unique identifer for the clock resources in Linux and U-Boot executable.
+
{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 11:52, 5 March 2021 (CET)<br />a reference or link is missing for SMCCC}}
  +
{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 11:52, 5 March 2021 (CET)<br />HVC : why ? (if the answer is given in the SMCCC reference from the previous comment, ignore this one)}}
   
The SCMI reset domain protocol phandle together with the agent reset domain ID,
+
STM32MP15 DT clock bindings<ref>{{CodeSource | TF-A | include/dt-bindings/clock/stm32mp1-clks.h}}stm32mp1 DT clocks bindings</ref> defines clock_id identifier values used by SCMI agents in SCMI clock protocol communication.
supported values are defined in STM32MP1 DT reset bindings<ref>{{CodeSource | TF-A | include/dt-bindings/reset/stm32mp1-resets.h}}stm32mp1 DT reset bindings</ref>,
 
forms a unique identifer for the reset controller resources.
 
   
* SCMI exposes [[CRYP_internal_peripheral | CRYP1]] clock with ID CK_SCMI0_CRYP1 to non-secure agent 0.<br/>SCMI exposes [[CRYP_internal_peripheral | CRYP1]] reset with ID RST_SCMI0_CRYP1 to non-secure agent 0.
+
STM32MP15 DT reset bindings<ref>{{CodeSource | TF-A | include/dt-bindings/reset/stm32mp1-resets.h}}stm32mp1 DT reset bindings</ref> defines the domain_id identifiers used by SCMI agent in SCMI Reset Domain protocol communication.
   
* SCMI exposes [[HASH_internal_peripheral | HASH1]] clock with ID CK_SCMI0_HASH1 to non-secure agent 0.<br/>SCMI exposes [[HASH_internal_peripheral | HASH1]] reset with ID RST_SCMI0_CRYP1 to non-secure agent 0.
+
{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 11:55, 5 March 2021 (CET)<br />In the sentence below, "Directly or Indirectly" is confusing : can you clarify or remove if this detail is not required here ? Moreover, it is strange to put Linux/U-Boot and Device Tree technology at the same level because the first ones are consumers of the second one}}
  +
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 exposes [[RNG_internal_peripheral | RNG1]] clock with ID CK_SCMI0_RNG1 to non-secure agent 0.<br/>SCMI exposes [[RNG_internal_peripheral | RNG1]] reset with ID RST_SCMI0_RNG1 to non-secure agent 0.
+
SCMI devices exposed to agent SCMI0 on STM32MP15:<br/>
  +
* Clock and reset controllers for [[CRYP_internal_peripheral | CRYP1]], [[HASH_internal_peripheral | HASH1]], [[RNG_internal_peripheral | RNG1]], [[GPIO_internal_peripheral | GPIOZ bank]], [[I2C_internal_peripheral | I2C4 and I2C6]], [[SPI_internal_peripheral | SPI6]] and  [[USART_internal_peripheral | USART1]].
  +
* Clock controller for [[IWDG_internal_peripheral | IWDG1]], [[RTC_internal_peripheral | RTC]],  [[BSEC_internal_peripheral | BSEC]].
  +
* Reset controller for [[MDMA_internal_peripheral | MDMA]]
  +
* MCU reset controller and MCU hold-on-boot controller. See also [[Linux remoteproc framework overview|Linux remoteproc framework]] or [[How to start the coprocessor from the bootloader|U-Boot bootloader]].
  +
* System internal root clocks [[RCC_internal_peripheral | LSI, HSI and CSI]], external root clocks [[RCC_internal_peripheral | LSE and HSE]] and PLL2 output clocks PLL2Q.
  +
{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 12:03, 5 March 2021 (CET)<br />Only PLL2Q (for the GPU) ? Can you explain why and tell how the PLL1 can be controlled if not with SCMI0 ?}}
   
* SCMI exposes [[BSEC_internal_peripheral | BSEC]] clock with ID CK_SCMI0_BSEC to non-secure agent 0.
+
SCMI devices exposed to agent SCMI1 on STM32MP15:<br/>
 
+
* MCU clock. See also [[Linux remoteproc framework overview|Linux remoteproc framework]] or [[How to start the coprocessor from the bootloader|U-Boot bootloader]]
* SCMI exposes [[GPIO_internal_peripheral | GPIOZ bank]] clock with ID CK_SCMI0_GPIOZ to non-secure agent 0.<br/>SCMI exposes [[GPIO_internal_peripheral | GPIOZ bank]] reset with ID RST_SCMI0_GPIOZ to non-secure agent 0.
+
* PLL3 output clocks PLL3Q and PLL3R.
 
 
* SCMI exposes [[I2C_internal_peripheral | I2C4 and I2C6]] clock with ID CK_SCMI0_I2Cx to non-secure agent 0.<br/>SCMI exposes [[I2C_internal_peripheral | I2C4 and I2C6]] reset with ID RST_SCMI0_I2Cx to non-secure agent 0.
 
 
 
* SCMI exposes [[SPI_internal_peripheral | SPI6]] clock with ID CK_SCMI0_SPI6 to non-secure agent 0.<br/>SCMI exposes [[SPI_internal_peripheral | SPI6]] reset with ID RST_SCMI0_SPI6 to non-secure agent 0.
 
 
 
* SCMI exposes [[USART_internal_peripheral | USART1]] clock with ID CK_SCMI0_USART1 to non-secure agent 0.<br/>SCMI exposes [[USART_internal_peripheral | USART1]] reset with ID RST_SCMI0_USART1 to non-secure agent 0.
 
 
 
* SCMI exposes [[IWDG_internal_peripheral | IWDG1]] bus clock with ID CK_SCMI0_IWDG1 to non-secure agent 0.
 
 
 
* SCMI exposes [[RTC_internal_peripheral | RTC]] clock controller with ID CK_SCMI0_RTC to non-secure agent 0.
 
 
 
* SCMI exposes [[MDMA_internal_peripheral | MDMA]] reset controller with ID CK_SCMI0_MDMA to non-secure agent 0.
 
 
 
* SCMI exposes MCU clock to non-secure agent 1 with ID CK_SCMI1_MCU.<br/>SCMI exposes MCU reset to non-secure agent 0 with ID RST_SCMI0_MCU.<br/> They can be used for coprocessor startup whether via [[Linux remoteproc framework overview|Linux remoteproc framework]] or [[How to start the coprocessor from the bootloader|U-Boot bootloader]].
 
 
 
* SCMI exposes internal root clocks [[RCC_internal_peripheral | LSI, HSI and CSI]] to non-secure agent 0<br/> with IDs CLK_SCMI0_LSI, CLK_SCMI0_HSI and CLK_SCMI0_CSI.
 
* SCMI exposes external root clocks [[RCC_internal_peripheral | LSE and HSE]] to non-secure agent 0<br/> with IDs CK_SCMI0_HSE and CK_SCMI0_LSE.
 
 
 
* SCMI exposes PLL2Q and PLL2R to non-secure agent 0<br/> with IDs CK_SCMI0_PLL2_Q and CK_SCMI0_PLL2_R.
 
* SCMI exposes PLL3Q and PLL3R to non-secure agent 1<br/> with IDs CK_SCMI1_PLL3_Q and CK_SCMI1_PLL3_R.
 
 
 
== 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_internal_peripheral#Security_support|RCC TZEN]] hardening, the 3
 
later being related to [[RCC_internal_peripheral#Security_support|RCC MCKPROT]] hardening.
 
 
 
When [[RCC_internal_peripheral#Security_support|RCC TZEN]] hardening is enabled, non-secure world shall rely on SCMI agent 0 to access the desired resources.
 
 
 
When [[RCC_internal_peripheral#Security_support|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|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 shared memories used are all
 
located at the top (high addresses) is [[SYSRAM_internal_memory|SYSRAM internal memory]].
 
   
 
== Device Tree description ==
 
== Device Tree description ==
 
 
The SCMI services device tree bindings are defined in the Linux kernel source tree in Arm SCMI DT bindings<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/arm/arm,scmi.txt}}Arm SCMI DT bindings</ref> documentation.
 
The SCMI services device tree bindings are defined in the Linux kernel source tree in Arm SCMI DT bindings<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/arm/arm,scmi.txt}}Arm SCMI DT bindings</ref> documentation.
   
=== SCMI agent nodes ===
+
Device Tree bindings for SCMI on STM32MP are detailed in the [[SCMI_device_tree_configuration|SCMI device tree configuration article]].
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"''.
 
 
 
<pre>
 
                scmi-agent {
 
                        compatible = "arm,scmi";
 
 
 
                        (...) /* SCMI transport properties */
 
 
 
                        /* Below are the discovered SCMI protocols */
 
                        protocol@X {
 
                                reg = <0xX>;
 
                                (...)
 
                        };
 
                        protocol@Y {
 
                                reg = <0xY>;
 
                                (...)
 
                        };
 
                };
 
</pre>
 
 
 
=== 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.
 
 
 
<pre>
 
        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>;
 
                };
 
        };
 
</pre>
 
 
 
Mailbox device: ad-hoc ''arm,smc-mbox''.<br/>
 
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.
 
 
 
<pre>
 
        scmi0_mbox: mailbox-0 {
 
                #mbox-cells = <0>;
 
                compatible = "arm,smc-mbox";
 
                arm,func-id = <0x82002000>;
 
        };
 
</pre>
 
 
 
In example below, SCMI agent 0 uses ''scmi0_mbox'' mailbox and ''scmi0_shm'' as shared memory.
 
<pre>
 
        firmware {
 
                scmi0: scmi-0 {
 
                        compatible = "arm,scmi";
 
                        (...)
 
                        mboxes = <&scmi0_mbox 0>;
 
                        mbox-names = "txrx";
 
                        shmem = <&scmi0_shm>;
 
                        (...)
 
                };
 
        };
 
</pre>
 
 
 
=== STM32MP15 SCMI device tree nodes ===
 
 
 
STM32MP15 exposes SCMI over 2 devices in the [[Device_tree|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<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/arm/arm,scmi.txt}}Arm SCMI DT bindings</ref>, 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.
 
 
 
<pre>
 
        /* 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>;
 
                        };
 
                };
 
</pre>
 
   
 
==How to go further==
 
==How to go further==
   
One can follow SCMI developments through TF-A mailing list<ref>https://lists.trustedfirmware.org/mailman/listinfo/tf-a</ref> and OP-TEE OS issues<ref>https://github.com/OP-TEE/optee_os/issues</ref>and  pull requests<ref>https://github.com/OP-TEE/optee_os/pulls</ref>forums.
+
One can follow SCMI developments through TF-A mailing list<ref>https://lists.trustedfirmware.org/mailman/listinfo/tf-a</ref> and OP-TEE OS issues<ref>https://github.com/OP-TEE/optee_os/issues</ref> and  pull requests<ref>https://github.com/OP-TEE/optee_os/pulls</ref> forums.
   
 
==References==
 
==References==
Line 278: Line 84:
 
<noinclude>
 
<noinclude>
 
[[Category:Platform security]]
 
[[Category:Platform security]]
{{PublicationRequestId | <None> | 2018-10-22 | EtienneC}}
+
{{PublicationRequestId | TBC | TBC| }}
 
{{ArticleBasedOnModel | Internal peripheral article model}}
 
{{ArticleBasedOnModel | Internal peripheral article model}}
   
[[Category:Device tree configuration]]
 
 
[[Category:Clock]]
 
[[Category:Clock]]
 
[[Category:Reset]]
 
[[Category:Reset]]
 
</noinclude>
 
</noinclude>