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 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 ++++++++++++++++++
 1 file changed, 341 insertions(+)

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;
+        };
-- 
2.34.1