[RFC PATCH v1 26/26] docs: arm: add an Arm CCA Realm guest guide

[Koichiro Den <den@xxxxxxxxxxxxx>]

Document the Realm guest model, the current build/runtime flow, and the
limits deliberately left outside this implementation.

Signed-off-by: Koichiro Den <den@xxxxxxxxxxxxx>
---
 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