[PATCH for-4.22 v2 2/2] docs/arm: Document GICv3 vCPU limit for host-layout domains

[Mykola Kvach <xakep.amatop@xxxxxxxxx>]

From: Mykola Kvach <mykola_kvach@xxxxxxxx>

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>
---
Changes in v2:
- move the detailed GICv3 host-layout redistributor note from
  dom0_max_vcpus to the Arm device-tree booting documentation.
- keep only a generic domain-limit note under dom0_max_vcpus.
---
 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>`
 
-- 
2.43.0