From: Grygorii Strashko <grygorii_strashko@epam.com>
Add SCI SCMI SMC multi-agent driver documentation.
It includes a detailed description of the SCMI multi-agent driver.
This document explains the driver's functionality, configuration,
and the compilation process. The Xen SCMI multi-agent driver is
designed to provide SCMI access to system resources from different
domains.
Signed-off-by: Grygorii Strashko <grygorii_strashko@epam.com>
Signed-off-by: Oleksii Moisieiev <oleksii_moisieiev@epam.com>
---
Changes in v8:
- update documentation to match the last DT format
- fixed RST: "... code-block:: dts" -> ".. code-block:: dts"
- update documentation with dom0less configuration example
- update documentation with new param xen,dom0-sci-agent-id
instead of the command line parameter
Changes in v7:
- update documentation in section of the xen_scmi configuration which
is matched by "xen,sci" compatible instead of the direct path.
Changes in v6:
- remove all HVC mentions from the multi-agent doc
- update sci-agent-id parameter description in the documentation
- add missing Sign-of
- minor fixes across the document
Changes in v5:
- rework multi-agent driver to leave Host Device-tree unmodified
.../arm/firmware/arm-scmi.rst | 420 ++++++++++++++++++
1 file changed, 420 insertions(+)
diff --git a/docs/hypervisor-guide/arm/firmware/arm-scmi.rst b/docs/hypervisor-guide/arm/firmware/arm-scmi.rst
index d9698f4e4b..2497a870f3 100644
--- a/docs/hypervisor-guide/arm/firmware/arm-scmi.rst
+++ b/docs/hypervisor-guide/arm/firmware/arm-scmi.rst
@@ -36,6 +36,8 @@ The below sections describe SCMI support options available for Xen.
| [1] `Arm SCMI <https://developer.arm.com/documentation/den0056/latest/>`_
| [2] `System Control and Management Interface (SCMI) bindings <https://web.git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/firmware/arm,scmi.yaml>`_
+| [3] `Generic Domain Access Controllers bindings <https://web.git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/access-controllers/access-controllers.yaml>`_
+
Simple SCMI over SMC calls forwarding driver (EL3)
------------------------------------------------------
@@ -189,3 +191,421 @@ except explicitly enabling SCMI with "arm_sci" xl.cfg option.
-> xen,reg = <0x0 0x47ff0000 0x0 0x1000 0x0 0x22001000>;
-> xen,force-assign-without-iommu;
};
+
+SCMI SMC multi-agent driver (EL3)
+-------------------------------------
+
+The SCMI SMC multi-agent driver enables support for ARM EL3 Trusted Firmware-A (TF-A) which
+provides SCMI interface with multi-agent support, as shown below.
+
+::
+
+ +-----------------------------------------+
+ | |
+ | EL3 TF-A SCMI |
+ +-------+--+-------+--+-------+--+-------++
+ |shmem1 | |shmem0 | |shmem2 | |shmemX |
+ +-----+-+ +---+---+ +--+----+ +---+---+
+ smc-id1 | | | |
+ agent1 | | | |
+ +-----v--------+---------+-----------+----+
+ | | | | |
+ | | | | |
+ +--------------+---------+-----------+----+
+ smc-id0 | smc-id2| smc-idX|
+ agent0 | agent2 | agentX |
+ | | |
+ +----v---+ +--v-----+ +--v-----+
+ | | | | | |
+ | Dom0 | | Dom1 | | DomX |
+ | | | | | |
+ | | | | | |
+ +--------+ +--------+ +--------+
+
+The EL3 SCMI multi-agent firmware is expected to provide SCMI SMC shared-memory transport
+for every Agent in the system. The SCMI Agent transport channel defined by pair:
+
+- smc-id: SMC function id used for Doorbell
+- shmem: shared memory for messages transfer, **Xen page aligned**.
+ Shared memory is mapped with the following flags: MT_DEVICE_nGnRE and _PAGE_DEVICE, indicating that this
+ memory is mapped as device memory.
+
+The following SCMI Agents are expected to be defined by SCMI FW to enable SCMI multi-agent functionality
+under Xen:
+
+- Xen management agent: trusted agents that accesses to the Base Protocol commands to configure
+ agent specific permissions
+- OSPM VM agents: non-trusted agent, one for each Guest domain which is allowed direct HW access.
+ At least one OSPM VM agent has to be provided by FW if HW is handled only by Dom0 or Driver Domain.
+
+The EL3 SCMI FW is expected to implement following Base protocol messages:
+
+- BASE_DISCOVER_AGENT (optional if agent_id was provided)
+- BASE_RESET_AGENT_CONFIGURATION (optional)
+- BASE_SET_DEVICE_PERMISSIONS (optional)
+
+The number of supported SCMI agents and their transport specifications are SCMI FW implementation
+specific.
+
+Compiling with multi-agent support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To build with the SCMI SMC multi-agent driver support, enable Kconfig option:
+
+::
+
+ CONFIG_SCMI_SMC_MA
+
+
+Driver functionality
+^^^^^^^^^^^^^^^^^^^^
+
+The SCI SCMI SMC multi-agent driver implements following functionality:
+
+- The driver is initialized from the Xen SCMI container ``xen_scmi_config``
+ under ``/chosen/xen`` (for example ``/chosen/xen/xen_scmi_config/scmi``).
+ Only one SCMI interface is supported. The SCMI configuration must live under
+ the Xen SCMI container ``xen,sci`` beneath ``/chosen``.
+ The Xen SCMI mediator will bind only to the "arm,scmi-smc" node that is a child of
+ this "xen,sci" container; any other "arm,scmi-smc" nodes (for example under
+ "/firmware") are ignored to avoid stealing the host's SCMI OSPM instance.
+
+.. code-block:: dts
+
+ scmi_shm_1: sram@47ff1000 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x0 0x47ff1000 0x0 0x1000>;
+ };
+ scmi_xen: scmi {
+ compatible = "arm,scmi-smc";
+ arm,smc-id = <0x82000003>; <--- Xen management agent smc-id
+ #address-cells = < 1>;
+ #size-cells = < 0>;
+ #access-controller-cells = < 1>;
+ shmem = <&scmi_shm_1>; <--- Xen management agent shmem
+ };
+
+.. note::
+ This layout keeps the Host DT unchanged for Dom0 and baremetal Linux by
+ using func_id 0x82000002 / shmem 0x47ff0000 for Dom0, while Xen uses a
+ separate privileged channel func_id 0x82000003 / shmem 0x47ff1000. EL3
+ firmware enforces permissions per agent_id, so there is no conflict between
+ Dom0 and Xen channels.
+
+- The driver obtains Xen specific SCMI Agent's configuration from the Host DT, probes Agents and
+ builds SCMI Agents list. The Agents configuration is taken from "scmi-secondary-agents"
+ property where first item is "arm,smc-id", second - "arm,scmi-shmem" phandle and third is
+ optional "agent_id":
+
+.. code-block:: dts
+
+ chosen {
+ ranges; <--- set default ranges so address can be translated when parsing scmi_shm node
+ xen {
+ ranges;
+ xen_scmi_config {
+ compatible = "xen,sci";
+ #address-cells = <2>;
+ #size-cells = <2>;
+ ranges; <--- set default ranges so address can be translated when parsing scmi_shm node
+ scmi-secondary-agents = <
+ 0x82000002 &scmi_shm_0 0
+ 0x82000004 &scmi_shm_2 2
+ 0x82000005 &scmi_shm_3 3
+ 0x82000006 &scmi_shm_4 4>;
+ #scmi-secondary-agents-cells = <3>; <--- optional, default 3
+ xen,dom0-sci-agent-id = <0>; /* Dom0 agent ID */
+
+ scmi_shm_0 : sram@47ff0000 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x0 0x47ff0000 0x0 0x1000>;
+ };
+
+ scmi_shm_2: sram@47ff2000 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x0 0x47ff2000 0x0 0x1000>;
+ };
+ scmi_shm_3: sram@47ff3000 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x0 0x47ff3000 0x0 0x1000>;
+ };
+ scmi_shm_4: sram@47ff4000 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x0 0x47ff4000 0x0 0x1000>;
+ };
+
+ // Xen SCMI management channel
+ scmi_shm_1: sram@47ff1000 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x0 0x47ff1000 0x0 0x1000>;
+ };
+
+ scmi_xen: scmi {
+ compatible = "arm,scmi-smc";
+ arm,smc-id = <0x82000003>; <--- Xen management agent smc-id
+ #address-cells = < 1>;
+ #size-cells = < 0>;
+ #access-controller-cells = < 1>;
+ shmem = <&scmi_shm_1>; <--- Xen management agent shmem
+ };
+ };
+ };
+ };
+
+ /{
+ // Host SCMI OSPM channel - provided to the Dom0 as is if SCMI enabled for it
+ scmi_shm: sram@47ff0000 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x0 0x47ff0000 0x0 0x1000>;
+ };
+
+ firmware {
+ scmi: scmi {
+ compatible = "arm,scmi-smc";
+ arm,smc-id = <0x82000002>; <--- Host OSPM agent smc-id
+ #address-cells = < 1>;
+ #size-cells = < 0>;
+ shmem = <&scmi_shm>; <--- Host OSPM agent shmem
+
+ protocol@X{
+ };
+ };
+ };
+ };
+
+ This approach allows defining multiple SCMI Agents by adding Xen-specific properties under
+ the ``/chosen`` node to the Host Device Tree, leaving the main part unchanged. The Host DT
+ SCMI channel will be passed to Dom0.
+
+ The Xen management agent is described as a ``scmi_xen`` node under the ``xen,sci`` compatible node,
+ which is used by Xen to control other SCMI Agents in the system.
+
+ All secondary agents' configurations are provided in the ``scmi-secondary-agents`` property with
+ an optional ``agent_id`` field.
+
+ The ``agent_id`` from the ``scmi-secondary-agents`` property is used to identify the agent in the
+ system and can be omitted by setting ``#scmi-secondary-agents-cells = <2>``, so the Secondary
+ Agents configuration will look like this:
+
+.. code-block:: dts
+
+ chosen {
+ xen {
+ xen_scmi_config {
+ compatible = "xen,sci";
+ scmi-secondary-agents = <
+ 0x82000002 &scmi_shm_0
+ 0x82000004 &scmi_shm_2
+ 0x82000005 &scmi_shm_3
+ 0x82000006 &scmi_shm_4>;
+ #scmi-secondary-agents-cells = <2>;
+ };
+ };
+ }
+
+ In this case, Xen will use the ``SCMI_BASE_DISCOVER_AGENT`` call to discover the ``agent_id``
+ for each secondary agent. Providing the ``agent_id`` in the ``scmi-secondary-agents`` property
+ allows skipping the discovery call, which is useful when the secondary agent's shared memory is
+ not accessible by Xen or when boot time is important because it allows skipping the agent
+ discovery procedure.
+
+.. note::
+
+ Note that Xen is the only one entry in the system which need to know about SCMI multi-agent support.
+
+- The driver implements the SCI subsystem interface required for configuring and enabling SCMI
+ functionality for Dom0/hwdom and Guest domains. To enable SCMI functionality for guest domain
+ it has to be configured with unique supported SCMI Agent_id and use corresponding SCMI SMC
+ shared-memory transport ``[smc-id, shmem]`` defined for this SCMI Agent_id.
+
+- Once Xen domain is configured it can communicate with EL3 SCMI FW:
+
+ - zero-copy, the guest domain puts/gets SCMI message in/from shmem;
+ - the guest triggers SMC exception with agent "smc-id" (doorbell);
+ - the Xen driver catches exception, do checks and synchronously forwards it to EL3 FW.
+
+- the Xen driver sends BASE_RESET_AGENT_CONFIGURATION message to Xen management agent channel on
+ domain destroy event. This allows to reset resources used by domain and so implement use-case
+ like domain reboot.
+
+
+Configure SCMI for Dom0
+^^^^^^^^^^^^^^^^^^^^^^^
+Set the Dom0 SCMI agent ID in the device tree using the Xen SCMI container under ``/chosen``.
+Add ``xen,dom0-sci-agent-id`` to the ``xen,sci`` node. If the property is absent, SCMI stays
+disabled for Dom0 and the SCMI nodes are removed from Dom0 DT.
+
+.. code-block:: dts
+
+ chosen {
+ xen {
+ ranges;
+ xen_scmi_config {
+ compatible = "xen,sci";
+ xen,dom0-sci-agent-id = <0>; /* Dom0 agent ID */
+ /* scmi-secondary-agents and scmi_xen as shown above */
+ };
+ };
+ };
+
+Xen utilizes the Host DT ``/firmware/scmi`` node to configure the Dom0 SCMI agent, leaving the
+rest of the Host DT unchanged except for the Xen-specific properties under ``/chosen``. If the
+``/firmware/scmi`` node is missing or disabled, the Dom0 SCMI agent will not be configured.
+
+.. note::
+
+ The ``xen,dom0-sci-agent-id`` value must match the ``func_id`` and ``shmem`` pairing provided by
+ the EL3 firmware for Dom0 (for example in the ``/firmware/scmi`` node).
+
+Configure SCMI for for guest domain with toolstack
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* In domain's xl.cfg file add **"arm_sci"** option as below
+
+::
+
+ arm_sci = "type=scmi_smc_multiagent,agent_id=2"
+
+* In domain's xl.cfg file enable access to the "arm,scmi-shmem" which should correspond
+ assigned "agent_id" for the domain, for example:
+
+::
+
+ iomem = [
+ "47ff2,1@22001",
+ ]
+
+.. note:: It's up to the user to select guest IPA for mapping SCMI shared-memory.
+
+* Add SCMI nodes to the Driver domain partial device tree as in the below example.
+ The "arm,smc-id" should correspond assigned agent_id for the domain:
+
+.. code::
+
+ passthrough {
+ scmi_shm_0: sram@22001000 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x0 0x22001000 0x0 0x1000>;
+ };
+
+ firmware {
+ compatible = "simple-bus";
+ scmi: scmi {
+ compatible = "arm,scmi-smc";
+ arm,smc-id = <0x82000004>; <--- smc-id for agent_id=2
+ shmem = <&scmi_shm_0>;
+ ...
+ }
+ }
+ }
+
+**Device specific access control**
+
+The XEN SCMI SMC multi-agent driver performs "access-controller" provider function in case
+EL3 SCMI FW implements SCMI "4.2.1.1 Device specific access control" and provides the
+BASE_SET_DEVICE_PERMISSIONS command to configure the devices that an agents have access to.
+The Host DT SCMI node should have "#access-controller-cells=<1>" property and DT devices should
+be bound to the SCMI node using Access Controllers bindings [3].
+
+For example:
+
+.. code-block:: dts
+
+ &i2c1 {
+ access-controllers = <&scmi 0>;
+ };
+
+Use domain's xl.cfg file **"dtdev"** property to assign SCMI devices from toolstack to the guest:
+
+::
+
+ dtdev = [
+ "/soc/i2c@e6508000",
+ ]
+
+.. note::
+
+ xl.cfg:"dtdev" need contain all nodes which are under SCMI management (not only those which are
+ behind IOMMU) and passed-through to the guest domain.
+
+Configure SCMI for predefined domains (dom0less)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* add "xen,sci_type" and "xen,sci-agent-id" properties for required DomU ("xen,domain") node
+
+::
+
+ xen,sci_type="scmi_smc_multiagent"
+ xen,sci-agent-id=2
+
+* add scmi nodes to the Driver domain partial device tree the same way as above (toolstack case) and
+ enable access to the "arm,scmi-shmem" according to the dom0less documentation. For example:
+
+.. code-block:: dts
+
+ scmi_shm_0: sram@22001000 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x00 0x22001000 0x00 0x1000>;
+ -> xen,reg = <0x0 0x47ff0000 0x0 0x1000 0x0 0x22001000>;
+ -> xen,force-assign-without-iommu;
+ };
+
+* For SCMI device access control configure pass-through devices in the guest partial DT according to
+ the dom0less documentation and ensure that devices SCMI management has "xen,path" property set:
+
+Example (dom0less, multi-agent):
+
+.. code-block:: dts
+
+ chosen {
+ xen {
+ ranges;
+ xen_scmi_config {
+ compatible = "xen,sci";
+ #address-cells = <2>;
+ #size-cells = <2>;
+ ranges;
+
+ /* Xen management channel shared memory */
+ scmi_shm_1: sram@47ff1000 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x0 0x47ff1000 0x0 0x1000>;
+ };
+
+ scmi_shm_domu: sram@47ff2000 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x0 0x47ff2000 0x0 0x1000>;
+ };
+
+ scmi-secondary-agents = <
+ 0x82000004 &scmi_shm_domu 2>;
+ #scmi-secondary-agents-cells = <3>;
+
+ scmi_xen: scmi {
+ compatible = "arm,scmi-smc";
+ arm,smc-id = <0x82000003>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ #access-controller-cells = <1>;
+ shmem = <&scmi_shm_1>;
+ };
+ };
+ };
+
+ xen,domain@1 {
+ compatible = "xen,domain";
+ xen,sci_type = "scmi_smc_multiagent";
+ xen,sci-agent-id = <2>;
+ /* other domain properties here */
+ };
+ };
+
+.. code-block:: dts
+
+ i2c@e6508000 {
+ ...
+ reg = <0x00 0xe6508000 0x00 0x1000>;
+ -> xen,path = "/soc/i2c@e6508000"
+ -> xen,reg = <0x0 0xe6508000 0x0 0x1000 0x0 0xe6508000>;
+ -> xen,force-assign-without-iommu;
+ };
--
2.34.1© 2016 - 2026 Red Hat, Inc.