|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [PATCH v16 6/6] docs: arm: add SCI SCMI SMC multi-agent driver docs
From: Grygorii Strashko <grygorii_strashko@xxxxxxxx> 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@xxxxxxxx> Signed-off-by: Oleksii Moisieiev <oleksii_moisieiev@xxxxxxxx> --- Changes in v16: - label Xen in the architecture diagram - document BASE_SET_DEVICE_PERMISSIONS as mandatory and explain the warning and persistent-state implications when agent reset is unavailable - use xen,dom0-sci-agent and xen,sci-agent phandles with DT labels in Dom0 and dom0less examples; retain optional reg in agent nodes and distinguish explicit-ID unit addresses from discovery node names - explain that phandle selection also works with firmware-discovered IDs by resolving the ID collected during probe, and that toolstack configuration continues to use numeric agent_id - correct the access-controller example to reference Xen's management node; fix DTS syntax, section headings and partial-DT examples Changes in v14: - describe secondary agents as xen,scmi-agent nodes under agents - update host, discovery and dom0less examples for the child-node format - clarify shared-memory placement and platform RAM reservations Changes in v10: - rephrase section about /firmware/scmi. Mentioned that this node is taken from Host DT and copied unmodified. - fix xen,reg address for secondary domains for Dom0less configuration 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 | 437 ++++++++++++++++++ 1 file changed, 437 insertions(+) diff --git a/docs/hypervisor-guide/arm/firmware/arm-scmi.rst b/docs/hypervisor-guide/arm/firmware/arm-scmi.rst index d9698f4e4b..06b1e3b3f3 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,438 @@ 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 supports Arm EL3 firmware, such as Trusted +Firmware-A (TF-A), that provides a separate SCMI transport channel for each +agent, as shown below. + +:: + + +-----------------------------------------+ + | | + | EL3 TF-A SCMI | + +-------+--+-------+--+-------+--+-------++ + |shmem1 | |shmem0 | |shmem2 | |shmemX | + +-----+-+ +---+---+ +--+----+ +---+---+ + smc-id1 | | | | + agent1 | | | | + +-----v--------+---------+-----------+----+ + | | | | | + | | Xen | | | + +--------------+---------+-----------+----+ + smc-id0 | smc-id2| smc-idX| + agent0 | agent2 | agentX | + | | | + +----v---+ +--v-----+ +--v-----+ + | | | | | | + | Dom0 | | Dom1 | | DomX | + | | | | | | + | | | | | | + +--------+ +--------+ +--------+ + +The EL3 firmware must provide an SCMI SMC shared-memory transport channel +for each agent. Each channel consists of: + +- ``arm,smc-id``: the SMC function ID used as a doorbell. +- ``shmem``: the shared-memory buffer used to transfer messages. Its address + and size must be **Xen page aligned**. Xen maps the buffer as Device memory + using ``MT_DEVICE_nGnRE`` and ``_PAGE_DEVICE``. + +The firmware must provide the following agents: + +- Xen management agent: a trusted agent that has access to Base protocol + commands to configure agent-specific permissions. +- OSPM VM agents: untrusted agents, one for each guest domain that needs + SCMI access. At least one is required, even if only the hardware domain + uses SCMI. + +The firmware must implement these Base protocol messages: + +- ``BASE_DISCOVER_AGENT``: required for Xen and for secondary agents whose + ``reg`` property is omitted. +- ``BASE_SET_DEVICE_PERMISSIONS``: required. Xen checks support through + ``PROTOCOL_MESSAGE_ATTRIBUTES`` during initialization and fails to + initialize the mediator if the command is unavailable. Firmware must + enforce the permissions configured by Xen and prevent untrusted agents + from changing other agents' permissions. For firmware without this + command, use the single-agent driver for the hardware domain. + +``BASE_RESET_AGENT_CONFIGURATION`` is optional. Xen requests a reset when +relinquishing a domain's resources. If the command is unsupported, Xen +prints a warning and continues teardown. Device state and agent permissions +may persist, so platform software must ensure that reusing the agent is +safe. Other reset failures are reported and propagated to the caller. + +The number of agents and the transport channels available depend on the +firmware implementation. + +Compiling with multi-agent support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To build the SCMI SMC multi-agent driver, enable the Kconfig option: + +:: + + CONFIG_SCMI_SMC_MA + + +Driver functionality +^^^^^^^^^^^^^^^^^^^^ + +The SCI SCMI SMC multi-agent driver implements the following functionality: + +- The driver is initialized from the Xen SCMI node ``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 + a node compatible with ``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" node; 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 */ + #address-cells = < 1>; + #size-cells = < 0>; + #access-controller-cells = < 1>; + shmem = <&scmi_shm_1>; /* Xen management shared memory */ + }; + +.. 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 reads secondary agents from an ``agents`` child node of the + ``xen,sci`` node. The ``agents`` node uses ``#address-cells = <1>`` and + ``#size-cells = <0>``. Each enabled ``xen,scmi-agent`` child node specifies its + doorbell in ``arm,smc-id`` and a single shared-memory phandle in ``shmem``. + The optional single-cell ``reg`` property supplies the SCMI + agent ID (0..254). IDs must be unique and distinct from Xen's management + agent. + At least one enabled secondary agent is required. + With an explicit ID, use a unit address matching ``reg``, such as + ``scmi_agent_domu: agent@2``. For discovery, omit ``reg`` and use a node + name without a unit address, retaining the label for phandle references. + + Place the SCMI-specific shared-memory nodes under ``xen_scmi_config``. + Keep the host OSPM shared-memory node and ``/firmware/scmi`` in the platform DT. + A shared-memory node describes a channel location and does not reserve RAM. + If buffers occupy system RAM, the platform must reserve the entire + firmware-owned range in ``/reserved-memory`` before Xen boots. A single + reservation may cover multiple channels, including unused ones. SRAM + outside system RAM does not require a RAM reservation. The channel nodes + do not have to be moved into ``/reserved-memory``. + +.. code-block:: dts + + / { + #address-cells = <2>; + #size-cells = <2>; + + scmi_shm_0: 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_0>; /* Host OSPM agent shmem */ + }; + }; + + chosen { + #address-cells = <2>; + #size-cells = <2>; + ranges; + + xen { + #address-cells = <2>; + #size-cells = <2>; + ranges; + + xen_scmi_config { + compatible = "xen,sci"; + #address-cells = <2>; + #size-cells = <2>; + ranges; + xen,dom0-sci-agent = <&scmi_agent_dom0>; + + /* Xen management channel */ + scmi_shm_1: sram@47ff1000 { + compatible = "arm,scmi-shmem"; + reg = <0x0 0x47ff1000 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_xen: scmi { + compatible = "arm,scmi-smc"; + arm,smc-id = <0x82000003>; /* Xen management smc-id */ + #address-cells = <1>; + #size-cells = <0>; + #access-controller-cells = <1>; + shmem = <&scmi_shm_1>; /* Xen management agent shmem */ + }; + + agents { + #address-cells = <1>; + #size-cells = <0>; + + scmi_agent_dom0: agent@0 { + compatible = "xen,scmi-agent"; + reg = <0>; + arm,smc-id = <0x82000002>; + shmem = <&scmi_shm_0>; + }; + + scmi_agent_domu: agent@2 { + compatible = "xen,scmi-agent"; + reg = <2>; + arm,smc-id = <0x82000004>; + shmem = <&scmi_shm_2>; + }; + + scmi_agent_domu3: agent@3 { + compatible = "xen,scmi-agent"; + reg = <3>; + arm,smc-id = <0x82000005>; + shmem = <&scmi_shm_3>; + }; + }; + }; + }; + }; + }; + +The ``xen,sci`` subtree is omitted from Dom0's DT. The host OSPM channel is +copied to Dom0 when SCMI is enabled for it. Xen uses its separate privileged +management channel to configure the other agents. + +To discover a secondary agent ID through ``BASE_DISCOVER_AGENT``, omit +``reg`` and the node's unit address. Keep the label so domain references +still resolve. For example, replace only ``scmi_agent_domu: agent@2`` above with: + +.. code-block:: dts + + scmi_agent_domu: agent-domu { + compatible = "xen,scmi-agent"; + arm,smc-id = <0x82000004>; + shmem = <&scmi_shm_2>; + }; + +Providing ``reg`` skips mapping and probing that secondary +channel during initialization. A malformed property is rejected. Xen always +discovers its own management agent ID. Thus ``BASE_DISCOVER_AGENT`` is +mandatory for the management channel and for secondary channels whose +``reg`` is omitted. Use node labels, such as +``scmi_agent_domu``, in phandle references; node names, such as +``agent-domu``, are not labels. + +Neither ``xen,dom0-sci-agent`` nor ``xen,sci-agent`` contains an agent ID. +If the referenced agent node has no ``reg``, Xen sends +``BASE_DISCOVER_AGENT`` through that node's ``arm,smc-id`` and ``shmem`` +channel during mediator initialization. Xen saves the returned ID with the +agent node, then resolves either domain's phandle to that ID when building +the domain. Discovery failure aborts mediator initialization; Xen does not +derive an ID from the node name, phandle value or SMC function ID. + +.. note:: + + Only Xen needs to know about the multi-agent configuration. Each guest + uses its assigned channel as an ordinary SCMI transport. + +- The driver implements the SCI subsystem interface to configure SCMI for + Dom0 and guest domains. Each domain must use a unique agent ID and the + corresponding SCMI SMC transport channel ``[arm,smc-id, shmem]``. + +- Once a domain is configured, it can communicate with the EL3 firmware: + + - zero-copy: the guest writes and reads SCMI messages to/from shared memory; + - the guest issues an SMC using its agent's ``arm,smc-id`` as a doorbell; + - Xen checks the SMC function ID and synchronously forwards the call to EL3. + +- During domain teardown, Xen sends ``BASE_RESET_AGENT_CONFIGURATION`` + through the management channel to reset the agent's configuration. If + reset is unsupported, Xen warns about the persistent state as described + above. + + +Configuring SCMI for Dom0 +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Add ``xen,dom0-sci-agent`` to the ``xen,sci`` node under ``/chosen``. +Its value is a single phandle to an enabled secondary agent node. Xen +resolves that node to its configured or discovered agent ID. If the +property is absent or invalid, SCMI stays disabled for Dom0 and the SCMI +nodes are removed from Dom0's DT. An invalid reference produces a warning. + +.. code-block:: dts + + chosen { + xen { + ranges; + xen_scmi_config { + compatible = "xen,sci"; + xen,dom0-sci-agent = <&scmi_agent_dom0>; + /* agents, shared memory and scmi_xen as shown above */ + }; + }; + }; + +When SCMI is enabled for Dom0, Xen copies the host's ``/firmware/scmi`` node +to Dom0's DT unmodified. This node must be present and enabled for Dom0's +SCMI driver to use the channel. Xen selects the agent using the ``agents`` +child node and ``xen,dom0-sci-agent`` property under ``xen,sci``. + +.. note:: + + The selected agent's ``arm,smc-id`` and ``shmem`` must match the channel + described by the host's ``/firmware/scmi`` node and provided by EL3 for Dom0. + +Configuring SCMI for a guest domain with the toolstack +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Add the ``arm_sci`` option to the domain's xl.cfg file: + +:: + + arm_sci = "type=scmi_smc_multiagent,agent_id=2" + +* Use ``iomem`` to map the shared-memory channel associated with the domain's + ``agent_id``: + +:: + + iomem = [ + "47ff2,1@22001", + ] + +.. note:: The user selects the guest IPA used to map SCMI shared memory. + +* Add SCMI nodes to the guest's partial device tree. ``arm,smc-id`` must + match the channel associated with the assigned ``agent_id``: + +.. code-block:: dts + + passthrough { + #address-cells = <2>; + #size-cells = <2>; + + scmi_shm_0: sram@22001000 { + compatible = "arm,scmi-shmem"; + reg = <0x0 0x22001000 0x0 0x1000>; + }; + + firmware { + scmi: scmi { + compatible = "arm,scmi-smc"; + arm,smc-id = <0x82000004>; /* channel for agent_id=2 */ + shmem = <&scmi_shm_0>; + }; + }; + }; + +**Device specific access control** + +The Xen SCMI SMC multi-agent driver acts as an access-controller provider. +It uses the required ``BASE_SET_DEVICE_PERMISSIONS`` command to configure +the devices each agent can access. The Xen management SCMI node must have +``#access-controller-cells = <1>``. Bind devices to that node using the +Access Controllers bindings [3]. + +For example: + +.. code-block:: dts + + &i2c1 { + access-controllers = <&scmi_xen 0>; + }; + +Use ``dtdev`` in the domain's xl.cfg file to assign SCMI-managed devices: + +:: + + dtdev = [ + "/soc/i2c@e6508000", + ] + +.. note:: + + ``dtdev`` needs to contain all SCMI-managed devices passed through to + the guest, including devices without IOMMU protection. + +Configuring SCMI for predefined domains (dom0less) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Add ``xen,sci_type`` and ``xen,sci-agent`` to the guest's ``xen,domain`` + node. The phandle selects an enabled secondary agent, including one whose + ID is discovered from firmware: + +:: + + xen,sci_type = "scmi_smc_multiagent"; + xen,sci-agent = <&scmi_agent_domu>; + +* Add SCMI nodes to the guest's partial device tree as in the toolstack + example, and map the shared memory according to the dom0less documentation: + +.. code-block:: dts + + scmi_shm_0: sram@22001000 { + compatible = "arm,scmi-shmem"; + reg = <0x00 0x22001000 0x00 0x1000>; + xen,reg = <0x0 0x47ff2000 0x0 0x1000 0x0 0x22001000>; + xen,force-assign-without-iommu; + }; + +* Configure SCMI-managed passthrough devices in the guest's partial DT + according to the dom0less documentation. Set ``xen,path`` to each device's + host DT path so Xen can find its ``access-controllers`` property. + +Use the complete Xen SCMI configuration above. Remove +``xen,dom0-sci-agent`` if Dom0 does not use SCMI. The guest selects the +secondary channel labelled ``scmi_agent_domu``: + +.. code-block:: dts + + chosen { + domU1 { + compatible = "xen,domain"; + xen,sci_type = "scmi_smc_multiagent"; + xen,sci-agent = <&scmi_agent_domu>; + /* 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.43.0
|
![]() |
Lists.xenproject.org is hosted with RackSpace, monitoring our |