From: Grygorii Strashko <grygorii_strashko@epam.com>

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

Signed-off-by: Grygorii Strashko <grygorii_strashko@epam.com>
Signed-off-by: Oleksii Moisieiev <oleksii_moisieiev@epam.com>
---

(no changes since v7)

Changes in v7:
- fixed typos

Changes in v6:
- add link to the scmi bindings used in the doc
- remove mentions about HVC calls from doc
- rename cmdline parameter to scmi-smc-passthrough

Changes in v5:
- rename dom0_scmi_smc_passthrough in documentation

 .../arm/firmware/arm-scmi.rst                 | 180 ++++++++++++++++++
 docs/hypervisor-guide/arm/index.rst           |   9 +
 docs/hypervisor-guide/index.rst               |   1 +
 3 files changed, 190 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..d65ce35acb
--- /dev/null
+++ b/docs/hypervisor-guide/arm/firmware/arm-scmi.rst
@@ -0,0 +1,180 @@
+.. 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 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 be 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/>`_
+| [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>`_
+
+Simple SCMI over SMC 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 calls as doorbell.
+
+The SCMI over SMC calls forwarding driver solves major problem for this case by allowing
+SMC calls to be forwarded from guest to the EL3 SCMI firmware.
+
+By default, the SCMI over SMC 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 calls.
+
+Compiling
+^^^^^^^^^
+
+To build with the SCMI over SMC calls forwarding enabled support, enable Kconfig option
+
+::
+
+    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 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>;
+                    ...
+                }
+        }
+    }
+
+Please refer to [2] for details of SCMI DT bindings.
+
+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