[xen staging] docs/arm: Document GICv3 vCPU limit for host-layout domains

[patchbot@xxxxxxx]

commit f8523357f016f8e726d220b4c34079021d3360fc
Author:     Mykola Kvach <mykola_kvach@xxxxxxxx>
AuthorDate: Wed May 27 03:18:51 2026 +0200
Commit:     Michal Orzel <michal.orzel@xxxxxxx>
CommitDate: Wed May 27 08:56:26 2026 +0200

    docs/arm: Document GICv3 vCPU limit for host-layout domains
    
    The number of vCPUs requested for a boot-time Arm domain is not bounded
    solely by Xen's generic domain limits. For GICv3 domains using the host
    memory layout, Xen can only create vCPUs whose virtual redistributor
    frame is covered by redistributor MMIO regions exposed for that layout.
    
    This can affect the hardware domain and direct-mapped domains. Document
    the GICv3-specific limit in the `cpus` property description in the Arm
    device-tree booting guide. Also add a generic domain-limit caveat to the
    `dom0_max_vcpus` command-line documentation.
    
    Signed-off-by: Mykola Kvach <mykola_kvach@xxxxxxxx>
    Reviewed-by: Michal Orzel <michal.orzel@xxxxxxx>
---
 docs/misc/arm/device-tree/booting.txt | 9 +++++++++
 docs/misc/xen-command-line.pandoc     | 3 +++
 2 files changed, 12 insertions(+)

diff --git a/docs/misc/arm/device-tree/booting.txt 
b/docs/misc/arm/device-tree/booting.txt
index f73839df09..bcb06bc796 100644
--- a/docs/misc/arm/device-tree/booting.txt
+++ b/docs/misc/arm/device-tree/booting.txt
@@ -162,6 +162,15 @@ with the following properties:
 
     An integer specifying the number of vcpus to allocate to the guest.
 
+    The resulting number of vcpus is still subject to Xen's generic and
+    architecture-specific domain limits. On Arm GICv3 systems, each vcpu
+    needs a virtual redistributor frame. Domains using the host GIC layout,
+    such as the hardware domain or direct-mapped domains, can only use vcpus
+    whose virtual redistributor frame is covered by the redistributor MMIO
+    regions exposed for that layout. If the requested number of vcpus exceeds
+    that limit, Xen will create fewer vcpus than requested, stopping at the
+    first vcpu whose virtual redistributor frame is not covered.
+
 - llc-colors
     A string specifying the LLC color configuration for the guest.
     Refer to docs/misc/cache_coloring.rst for syntax. This option is applicable
diff --git a/docs/misc/xen-command-line.pandoc 
b/docs/misc/xen-command-line.pandoc
index d46d5b2152..8c89b7852c 100644
--- a/docs/misc/xen-command-line.pandoc
+++ b/docs/misc/xen-command-line.pandoc
@@ -1000,6 +1000,9 @@ For example, with `dom0_max_vcpus=4-8`:
 >      8    |  8
 >     10    |  8
 
+The resulting number of Dom0 VCPUs is still subject to Xen's generic
+and architecture-specific domain limits.
+
 ### dom0_mem (ARM)
 > `= <size>`
 
--
generated by git-patchbot for /home/xen/git/xen.git#staging