[RFC PATCH v5 04/10] docs: arm: add docs for SCMI over SMC calls forwarding driver

[Oleksii Moisieiev <Oleksii_Moisieiev@xxxxxxxx>]

From: Grygorii Strashko <grygorii_strashko@xxxxxxxx>

Add documentation section for Simple Arm SCMI over SMC/HVC calls forwarding
driver (EL3).

Signed-off-by: Grygorii Strashko <grygorii_strashko@xxxxxxxx>
Signed-off-by: Oleksii Moisieiev <oleksii_moisieiev@xxxxxxxx>
---

Changes in v5:
- rename dom0_scmi_smc_passthrough in documentation

 .../arm/firmware/arm-scmi.rst                 | 177 ++++++++++++++++++
 docs/hypervisor-guide/arm/index.rst           |   9 +
 docs/hypervisor-guide/index.rst               |   1 +
 3 files changed, 187 insertions(+)
 create mode 100644 docs/hypervisor-guide/arm/firmware/arm-scmi.rst
 create mode 100644 docs/hypervisor-guide/arm/index.rst

diff --git a/docs/hypervisor-guide/arm/firmware/arm-scmi.rst 
b/docs/hypervisor-guide/arm/firmware/arm-scmi.rst
new file mode 100644
index 0000000000..a084c0caa3
--- /dev/null
+++ b/docs/hypervisor-guide/arm/firmware/arm-scmi.rst
@@ -0,0 +1,177 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+ARM System Control and Management Interface (SCMI)
+==================================================
+
+The System Control and Management Interface (SCMI) [1], which is a set of 
operating
+system-independent software interfaces that are used in system management. 
SCMI currently
+provides interfaces for:
+
+- Discovery and self-description of the interfaces it supports
+- Power domain management
+- Clock management
+- Reset domain management
+- Voltage domain management
+- Sensor management
+- Performance management
+- Power capping and monitoring
+- Pin control protocol.
+
+The SCMI compliant firmware could run:
+
+- as part of EL3 secure world software (like Trusted Firmware-A) with
+  ARM SMC/HVC shared-memory transport;
+- on dedicated System Control Processor (SCP) with HW mailbox shared-memory 
transport
+
+The major purpose of enabling SCMI support in Xen is to enable guest domains 
access to the SCMI
+interfaces for performing management actions on passed-through devices (such 
as clocks/resets etc)
+without accessing directly to the System control HW (like clock controllers) 
which in most cases
+can't shared/split between domains. Or, at minimum, allow SCMI access for 
dom0/hwdom (or guest
+domain serving as Driver domain).
+
+The below sections describe SCMI support options available for Xen.
+
+[1] `Arm SCMI <https://developer.arm.com/documentation/den0056/latest/>`_
+
+Simple SCMI over SMC/HVC calls forwarding driver (EL3)
+------------------------------------------------------
+
+The EL3 SCMI firmware (TF-A) with a single SCMI OSPM agent support is pretty 
generic case for
+the default vendors SDK and new platforms with SCMI support. Such EL3 SCMI 
firmware supports only
+single SCMI OSPM transport (agent) with Shared memory based transport and 
SMC/HVC calls as doorbell.
+
+The SCMI over SMC/HVC calls forwarding driver solves major problem for this 
case by allowing
+SMC/HVC calls to be forwarded form guest to the EL3 SCMI firmware.
+
+By default, the SCMI over SMC/HVC calls forwarding is enabled for Dom0/hwdom.
+
+::
+
+    +--------------------------+
+    |                          |
+    | EL3 SCMI FW (TF-A)       |
+    ++-------+--^--------------+
+     |shmem  |  | smc-id
+     +----^--+  |
+          |     |
+     +----|-+---+---+----------+
+     |    | |  FWD  |      Xen |
+     |    | +---^---+          |
+     +----|-----|--------------+
+          |     | smc-id
+     +----v-----+--+ +---------+
+     |             | |         |
+     | Dom0/hwdom  | | DomU    |
+     |             | |         |
+     |             | |         |
+     +-------------+ +---------+
+
+
+The SCMI messages are passed directly through SCMI shared-memory (zero-copy) 
and driver only
+forwards SMC/HVC calls.
+
+Compiling
+^^^^^^^^^
+
+To build with the SCMI over SMC/HVC calls forwarding enabled support, enable 
Kconfig option
+
+::
+
+    CONFIG_SCMI_SMC
+
+The ``CONFIG_SCMI_SMC`` is enabled by default.
+
+Pass-through SCMI SMC to domain which serves as Driver domain
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section describes how to configure the SCMI over SMC/HVC calls forwarding 
driver to handle use
+case "thin Dom0 with guest domain, which serves as Driver domain". In this 
case HW need to be
+enabled in Driver domain and dom0 is performing only control functions 
(without accessing FW) and so,
+the SCMI need to be enabled in Driver domain.
+
+::
+
+     +--------------------------+
+     |EL3 SCMI FW (TF-A)        |
+     |                          |
+     +-------------^--+-------+-+
+             smc-id|  |shmem0 |
+                   |  +----^--+
+    +-------------++------+|----+
+    |Xen          |  FWD  ||    |
+    |             +--^----+|    |
+    +----------------|-----|----+
+              smc-id |     |
+    +-----------+ +--+-----v-----+
+    |           | |              |
+    | Dom0      | |    Driver    |
+    | Control   | |    domain    |
+    |           | |              |
+    +-----------+ +--------------+
+
+The SCMI can be enabled for one and only one guest domain.
+
+First. configure Dom0 to enable SCMI pass-through using Xen Command Line
+**"scmi_smc_passthrough"** option. This will disable SCMI for Dom0/hwdom and 
SCMI nodes will
+be removed from Dom0/hwdom device tree.
+
+**Configure SCMI pass-through for guest domain with toolstack**
+
+* In domain's xl.cfg file add **"arm_sci"** option as below
+
+::
+
+    arm_sci = "type=scmi_smc"
+
+* In domain's xl.cfg file enable access to the "arm,scmi-shmem"
+
+::
+
+    iomem = [
+        "47ff0,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:
+
+.. 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";
+                    shmem = <&scmi_shm_0>;
+                    ...
+                }
+        }
+    }
+
+In general, the configuration is similar to any other HW pass-through, except 
explicitly
+enabling SCMI with "arm_sci" xl.cfg option.
+
+**Configure SCMI pass-through for predefined domain (dom0less)**
+
+* add "xen,sci_type" property for required DomU ("xen,domain") node
+
+::
+
+       xen,sci_type="scmi_smc"
+
+* add scmi nodes to the Driver domain partial device tree the same way as 
above and enable access
+  to the "arm,scmi-shmem" according to  dom0less documentation. For example:
+
+.. code::
+
+      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;
+      };
diff --git a/docs/hypervisor-guide/arm/index.rst 
b/docs/hypervisor-guide/arm/index.rst
new file mode 100644
index 0000000000..7aae4a0a03
--- /dev/null
+++ b/docs/hypervisor-guide/arm/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+ARM
+===
+
+.. toctree::
+   :maxdepth: 2
+
+   firmware/arm-scmi
diff --git a/docs/hypervisor-guide/index.rst b/docs/hypervisor-guide/index.rst
index e4393b0697..520fe01554 100644
--- a/docs/hypervisor-guide/index.rst
+++ b/docs/hypervisor-guide/index.rst
@@ -9,3 +9,4 @@ Hypervisor documentation
    code-coverage
 
    x86/index
+   arm/index
\ No newline at end of file
-- 
2.34.1