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

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Tue, 22 Jul 2025, Oleksii Moisieiev wrote:
> 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>

This doc looks good, a couple of minor suggestions:
- briefly document the bindings expected as input (e.g. compatible
  "arm,scmi-smc" and "arm,scmi-shmem") or simply provide links to official docs
- it says "SCMI over SMC/HVC" but I am not sure if HVC would actually
  work


> ---
> 
> 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
>