|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [PATCH v7 5/5] 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 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 | 341 ++++++++++++++++++ docs/misc/arm/device-tree/booting.txt | 123 ++++--- 2 files changed, 412 insertions(+), 52 deletions(-) diff --git a/docs/hypervisor-guide/arm/firmware/arm-scmi.rst b/docs/hypervisor-guide/arm/firmware/arm-scmi.rst index d9698f4e4b..630965fef3 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,342 @@ 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 based on the ``xen,config`` node under ``chosen`` + (only one SCMI interface is supported), which describes the Xen management + agent SCMI interface. + +.. 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 = <0x82000002>; <--- Xen management agent smc-id + #address-cells = < 1>; + #size-cells = < 0>; + #access-controller-cells = < 1>; + shmem = <&scmi_shm_1>; <--- Xen management agent shmem + }; + +- 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,config { + ranges; <--- set default ranges so address can be translated when parsing scmi_shm node + scmi-secondary-agents = < + 0x82000003 &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 + + 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 = <0x82000002>; <--- 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@47ff1000 { + compatible = "arm,scmi-shmem"; + reg = <0x0 0x47ff1000 0x0 0x1000>; + }; + + firmware { + scmi: scmi { + compatible = "arm,scmi-smc"; + arm,smc-id = <0x82000003>; <--- 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 ``/chosen`` 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,config { + scmi-secondary-agents = < + 0x82000003 &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 +^^^^^^^^^^^^^^^^^^^^^^^ +The **"dom0=sci-agent-id=<dom0_agent_id>"** parameter in the Xen command line is used to enable +SCMI functionality for Dom0. If not provided, SCMI will be disabled for Dom0 and all SCMI nodes +removed from Dom0 DT. + +Example: **dom0=sci-agent-id=0** to enable SCMI with agent ID 0 for Dom0. + +Xen utilizes Host DT SCMI node to configure Dom0 SCMI Agent so the device-tree remains unchanged +except for the Xen specific properties under ``/chosen`` node. If Xen device-tree doesn't include +``/firmware/scmi`` node or it's disabled, the Dom0 SCMI Agent will not be configured. + +.. note:: + + The **sci-agent-id** value should match the ``func_id`` and ``shmem`` in the ``/firmware/scmi`` node + to set the correct Dom0 SCMI Agent. + +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>; + 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: + +.. 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; + }; diff --git a/docs/misc/arm/device-tree/booting.txt b/docs/misc/arm/device-tree/booting.txt index 6fd7e4a16b..76eda1b756 100644 --- a/docs/misc/arm/device-tree/booting.txt +++ b/docs/misc/arm/device-tree/booting.txt @@ -844,9 +844,12 @@ SCMI SMC multi-agent support For enabling the ARM SCMI SMC multi-agent support (enabled by CONFIG_SCMI_SMC_MA) the Xen specific SCMI Agent's configuration shall be provided in the Host DT -according to the SCMI compliant EL3 Firmware specification with -ARM SMC/HVC transport using property "scmi-secondary-agents" placed in "xen,config" -node under "chosen" node: +according to the SCMI compliant EL3 Firmware specification with ARM SMC/HVC +transport. The SCMI configuration must live under the Xen SCMI container +"xen,sci" beneath "/chosen" (for example "/chosen/xen/xen_scmi_config/scmi"). 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. - scmi-secondary-agents @@ -859,47 +862,53 @@ node under "chosen" node: As an example: -/{ -chosen { - xen,config { - scmi_shm_0 : sram@47ff0000 { - compatible = "arm,scmi-shmem"; - reg = <0x0 0x47ff0000 0x0 0x1000>; - }; - // Xen SCMI 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_shm_3: sram@47ff4000 { - compatible = "arm,scmi-shmem"; - reg = <0x0 0x47ff4000 0x0 0x1000>; - }; - 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>; - }; - - scmi_xen: scmi { - compatible = "arm,scmi-smc"; - arm,smc-id = <0x82000002>; <--- Xen management agent smc-id - #address-cells = < 1>; - #size-cells = < 0>; - #access-controller-cells = < 1>; - shmem = <&scmi_shm_1>; <--- Xen management agent shmem +/ { + chosen { + xen { + ranges; + xen_scmi_config { + compatible = "xen,sci"; + #address-cells = <2>; + #size-cells = <2>; + ranges; + + scmi_shm_0: sram@47ff0000 { + compatible = "arm,scmi-shmem"; + reg = <0x0 0x47ff0000 0x0 0x1000>; + }; + + /* Xen SCMI 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-secondary-agents = < + 0x82000002 &scmi_shm_0 0 + 0x82000004 &scmi_shm_2 2 + 0x82000005 &scmi_shm_3 3>; <--- func_id, shmem, agent_id + #scmi-secondary-agents-cells = <3>; + + scmi_xen: scmi { + compatible = "arm,scmi-smc"; + arm,smc-id = <0x82000002>; <--- Xen management agent func_id + #address-cells = <1>; + #size-cells = <0>; + #access-controller-cells = <1>; + shmem = <&scmi_shm_1>; <--- Xen management agent shmem + }; + }; }; - }; }; @@ -915,15 +924,25 @@ chosen { Example: -/{ -chosen { - xen,config { - scmi-secondary-agents = < - 0x82000003 &scmi_shm_1 - 0x82000004 &scmi_shm_2 - 0x82000005 &scmi_shm_3 - 0x82000006 &scmi_shm_4>; - #scmi-secondary-agents-cells = <2>; +/ { + chosen { + xen { + ranges; + xen_scmi_config { + compatible = "xen,sci"; + #address-cells = <2>; + #size-cells = <2>; + ranges; + + /* Shared memory nodes as in the previous example */ + + scmi-secondary-agents = < + 0x82000003 &scmi_shm_1 + 0x82000004 &scmi_shm_2 + 0x82000005 &scmi_shm_3 + 0x82000006 &scmi_shm_4>; + #scmi-secondary-agents-cells = <2>; + }; }; }; }; -- 2.34.1
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |