Document the Realm guest model, the current build/runtime flow, and the limits deliberately left outside this implementation.
Signed-off-by: Koichiro Den <[email protected]> --- docs/hypervisor-guide/arm/cca-realm.rst | 83 +++++++++++++++++++++++++ docs/hypervisor-guide/arm/index.rst | 1 + 2 files changed, 84 insertions(+) create mode 100644 docs/hypervisor-guide/arm/cca-realm.rst diff --git a/docs/hypervisor-guide/arm/cca-realm.rst b/docs/hypervisor-guide/arm/cca-realm.rst new file mode 100644 index 000000000000..9a0a63220bfb --- /dev/null +++ b/docs/hypervisor-guide/arm/cca-realm.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +====================== +Arm CCA Realm support +====================== + +Overview +======== + +Xen can create Arm CCA Realm guests and run their vCPUs with +``RMI_REC_ENTER``. + +The initial support implements the DEN0137 2.0-bet1 Realm lifecycle: Xen +creates the RD and RTTs, initializes RIPAS, populates measured DATA granules, +creates RECs, and activates the Realm. + +Guest creation model +==================== + +Realm guest creation is exposed through ``libxl`` with ``realm=true``. + +Realm guests are currently restricted to: + +* 64-bit Arm PVH +* GICv3 +* a Xen-generated device tree +* guest RAM fully contained within the first guest RAM bank + +When ``realm=true`` is selected, Realm DTBs set the PSCI method to ``"smc"`` +and do not include the Xen hypervisor node, because Xen PV interfaces are not +exposed to Realm guests. The only supported virtual console is +``vuart="sbsa_uart"``. + +This VUART is a host-visible clear-text debug channel. It is accepted only when +``CONFIG_ARM_CCA_REALM_DEBUG_VUART=y`` and is not suitable for +confidentiality-oriented Realm deployments. + +Runtime model +============= + +Each Realm vCPU has a REC and a ``RecRun`` buffer shared between Xen and the +RMM in non-secure memory. Xen enters the Realm with ``RMI_REC_ENTER``. On +return, the RMM provides an ``RmiRecExit`` describing why the REC stopped. + +Before handling an exit, Xen synchronizes the Realm-side vGIC and timer state +needed by the host model. The current path handles the exits needed by this +series: host interrupt returns, emulatable MMIO, a small GICv3 sysreg subset, +``WFI/WFE``, PSCI, and RIPAS changes. Other exits are treated as unsupported. + +Current implementation notes +============================ + +* Initial Realm RAM population currently measures all populated DATA + granules. There is no separate interface for passing measured ranges + from the toolstack. + +* Xen tracks up to 64 accepted donation pages for one memory-transferring + SRO. This is a Xen implementation cap, not an RMI limit. + +* Xen checks that host RAM is fine-tracked conventional memory and ensures + GPT L1s exist before it creates Realms. + +Known limitations +================= + +The initial support is small in scope. + +* No Dom0less Realm launch at Xen boot +* No Xen PV, grant-table based, or virtio device exposure to Realm guests +* No passthrough or Realm device assignment, including VDEV/VSMMU handling +* No ACPI support +* No Multi-Plane Realms or S2AP change exits +* No Realm LPA2, SVE, or PMU support +* Fixed Live Firmware Activation policy, ``RMI_LFA_DISALLOW`` +* Shared MEC policy only +* Fixed zero Realm Personalization Value +* No non-4KB RMI granule or non-1GB tracking-region configuration support +* No Realm shared-memory mappings via + ``RMI_RTT_UNPROT_MAP`` / ``RMI_RTT_UNPROT_UNMAP`` +* No ``RMI_EXIT_HOST_CALL`` handling +* No hardware-backed vIRQ deactivation in the ``ICC_DIR_EL1`` emulation path + +This document should be updated as the Xen/Arm Realm feature set expands. diff --git a/docs/hypervisor-guide/arm/index.rst b/docs/hypervisor-guide/arm/index.rst index 7aae4a0a0301..feac2b4230c3 100644 --- a/docs/hypervisor-guide/arm/index.rst +++ b/docs/hypervisor-guide/arm/index.rst @@ -6,4 +6,5 @@ ARM .. toctree:: :maxdepth: 2 + cca-realm firmware/arm-scmi -- 2.51.0
