On Thu, 29 Jan 2026, Oleksii Moisieiev wrote:
> From: Grygorii Strashko <[email protected]>
>
> 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 <[email protected]>
> Signed-off-by: Oleksii Moisieiev <[email protected]>
> ---
>
> (no changes since v8)
>
> 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.
It might be good to clarify that actually /firmware/scmi is simply
copied to the Dom0 DT unmodified. However, for Dom0 SCMI configuration,
Xen actually relies on scmi-secondary-agents and xen,dom0-sci-agent-id.
> +.. 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>;
this should be 0x47ff2000 ?
> + -> 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
>
