|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [xen staging] docs: arm: add docs for SCMI over SMC calls forwarding driver
commit b63699ee98caed47f6b3fb99fcfc87462066795a
Author: Grygorii Strashko <grygorii_strashko@xxxxxxxx>
AuthorDate: Mon Sep 1 13:52:11 2025 +0000
Commit: Stefano Stabellini <stefano.stabellini@xxxxxxx>
CommitDate: Thu Sep 4 12:12:37 2025 -0700
docs: arm: add docs for SCMI over SMC calls forwarding driver
Add documentation section for Simple Arm SCMI over SMC calls forwarding
driver (EL3).
Signed-off-by: Grygorii Strashko <grygorii_strashko@xxxxxxxx>
Signed-off-by: Oleksii Moisieiev <oleksii_moisieiev@xxxxxxxx>
[stefano: code style, 80 chars limit per line]
Signed-off-by: Stefano Stabellini <stefano.stabellini@xxxxxxx>
Reviewed-by: Stefano Stabellini <sstabellini@xxxxxxxxxx>
---
docs/hypervisor-guide/arm/firmware/arm-scmi.rst | 191 ++++++++++++++++++++++++
docs/hypervisor-guide/arm/index.rst | 9 ++
docs/hypervisor-guide/index.rst | 1 +
3 files changed, 201 insertions(+)
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..d9698f4e4b
--- /dev/null
+++ b/docs/hypervisor-guide/arm/firmware/arm-scmi.rst
@@ -0,0 +1,191 @@
+.. 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
--
generated by git-patchbot for /home/xen/git/xen.git#staging
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |