[REQUIREMENTS][PATCH v2 2/6] reqs: add host GICv3 requirements

[Mykola Kvach <mykola_kvach@xxxxxxxx>]

Add software requirements for the Device Tree-based host GICv3 path.

The requirements cover GICv3-specific host behavior: Device Tree operation
registration and description parsing, GICD/GICR architecture identification,
supported SPI and extended SPI INTID handling, Distributor and Redistributor
initialization, Redistributor enumeration and CPU association, CPU interface
initialization, SPI and extended SPI routing, Group 1 interrupt acknowledge
and completion, SGI delivery, and secondary pCPU interrupt readiness.

Guest/vGIC state, ITS/LPI handling, host GICv4 behavior, and common
interrupt-management behavior are covered by separate requirement groups.
ACPI discovery is out of scope for this document.

Signed-off-by: Mykola Kvach <mykola_kvach@xxxxxxxx>
---
Changes in v2:
- avoid passive voice in titles.
---
 .../physical_resources/arm64/gicv3.rst        | 564 ++++++++++++++++++
 .../physical_resources/arm64/index.rst        |   1 +
 2 files changed, 565 insertions(+)
 create mode 100644 
software_safety_reqs/domain_creation_and_runtime/physical_resources/arm64/gicv3.rst

diff --git 
a/software_safety_reqs/domain_creation_and_runtime/physical_resources/arm64/gicv3.rst
 
b/software_safety_reqs/domain_creation_and_runtime/physical_resources/arm64/gicv3.rst
new file mode 100644
index 0000000..6a43165
--- /dev/null
+++ 
b/software_safety_reqs/domain_creation_and_runtime/physical_resources/arm64/gicv3.rst
@@ -0,0 +1,564 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Host GICv3 requirements
+=======================
+
+The following requirements are related to Xen's host-side support for the
+Arm Generic Interrupt Controller version 3 (GICv3) architecture [1].
+
+These requirements cover Xen's management of the physical GICv3 interfaces,
+including Distributor, Redistributor, CPU interface.
+
+Software Safety Requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Host GICv3 Device Tree operation registration
+---------------------------------------------
+
+`XenSSR~arm64_register_gicv3_ops~1`
+
+Description:
+Xen shall register the host GICv3 interrupt-controller operations for Device
+Tree nodes that identify a GICv3 interrupt controller.
+
+Rationale:
+Xen uses the registered GICv3 operations to initialize and operate the host
+physical interrupt controller when the platform firmware describes a GICv3
+interrupt controller through Device Tree.
+
+Covers:
+ - `XenPRQ~boot~1`
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host GICv3 Device Tree description
+----------------------------------
+
+`XenSSR~arm64_gicv3_dt_description~1`
+
+Description:
+Xen shall collect the GICv3 Distributor base and Redistributor region
+description from the Device Tree before host GICv3 initialization.
+
+The relevant Device Tree state includes:
+
+ - Distributor base address
+ - Redistributor region base addresses
+ - Redistributor region sizes
+ - ``#redistributor-regions``
+ - ``redistributor-stride``
+
+Rationale:
+Xen uses the Device Tree GICv3 description to locate the Distributor and to 
walk
+the Redistributor regions used by the host physical interrupt controller.
+
+Covers:
+ - `XenPRQ~boot~1`
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host GICv3 System register support
+----------------------------------
+
+`XenSSR~arm64_gicv3_sysreg_support~1`
+
+Description:
+Xen shall select the host GICv3 driver after confirming GICv3 System register
+support is available on the CPU.
+
+Rationale:
+The host GICv3 driver uses the GICv3 CPU interface System registers for
+physical interrupt handling.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host GICv3 architecture identification
+--------------------------------------
+
+`XenSSR~arm64_gicv3_arch_identification~1`
+
+Description:
+Xen shall identify a host GIC Distributor or Redistributor frame as
+GICv3-compatible only when its ``PIDR2`` architecture field reports GICv3 or
+GICv4.
+
+The relevant registers include:
+
+ - ``GICD_PIDR2``
+ - ``GICR_PIDR2``
+
+Rationale:
+Xen uses ``PIDR2`` to validate that the mapped frame belongs to a GICv3 or
+GICv4-compatible interrupt controller before using that frame as a host GICv3
+interface.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host Distributor security-state preservation
+--------------------------------------------
+
+`XenSSR~arm64_gicv3_dist_are_ns_state_preservation~1`
+
+Description:
+Xen shall preserve the ``GICD_CTLR.ARE_NS`` value when disabling Distributor
+Group 1 physical interrupt delivery during initialization.
+
+Rationale:
+The GIC architecture makes changing ``GICD_CTLR.ARE_NS`` from 1 to 0
+unpredictable. Xen preserves the field when preparing the Distributor for host
+GICv3 initialization.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host supported SPI and extended SPI INTID ranges
+------------------------------------------------
+
+`XenSSR~arm64_gicv3_supported_spi_and_espi_ranges~1`
+
+Description:
+Xen shall initialize and operate only SPI and extended SPI INTIDs implemented
+by the host GICv3 Distributor, as reported by GICD_TYPER.
+
+Rationale:
+Xen derives the supported Distributor-controlled physical interrupt range from
+the Distributor type information and uses that range when initializing and
+operating global interrupt state.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host extended SPI support
+-------------------------
+
+`XenSSR~arm64_gicv3_espi_support~1`
+
+Description:
+Xen shall initialize and operate extended SPI INTIDs only when the host GICv3
+Distributor reports extended SPI support in GICD_TYPER. This shall include
+use of the following registers:
+
+ - ``GICD_TYPER``
+ - ``GICD_ICFGR<n>E``
+ - ``GICD_IPRIORITYR<n>E``
+ - ``GICD_ICENABLER<n>E``
+ - ``GICD_ICACTIVER<n>E``
+ - ``GICD_IGROUPR<n>E``
+ - ``GICD_IROUTER<n>E``
+
+Rationale:
+GICv3.1 defines an extended SPI range controlled through extended Distributor
+registers. Xen uses Distributor capability information to determine whether
+extended SPIs are present before initializing their configuration, priority,
+enable, active, group, and routing state.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host Distributor Group 1 delivery
+---------------------------------
+
+`XenSSR~arm64_gicv3_dist_group1_delivery~1`
+
+Description:
+Xen shall enable Distributor Group 1 physical interrupt delivery only after
+supported SPI and extended SPI interrupt state has been initialized. The
+initialized state shall include:
+
+ - interrupt group state
+ - interrupt enable state
+ - interrupt active state
+ - interrupt priority state
+ - interrupt configuration state
+ - interrupt routing state
+
+Rationale:
+Xen initializes supported Distributor-controlled interrupt state before
+enabling Distributor forwarding so that physical interrupts are delivered using
+the configured group, enable, active, priority, configuration, and routing
+state.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host Redistributor region enumeration
+-------------------------------------
+
+`XenSSR~arm64_gicv3_redist_region_enumeration~1`
+
+Description:
+Xen shall locate Redistributor frames only within discovered GICv3
+Redistributor regions and according to the region layout used for that
+platform. This shall include use of the following Redistributor discovery
+state:
+
+ - Redistributor region base
+ - Redistributor region count
+ - Redistributor stride
+ - ``GICR_TYPER.Last``
+ - ``GICR_TYPER.VLPIS``
+
+Rationale:
+GICv3 Redistributors can be described as one or more regions, and a region can
+contain Redistributor frames separated by the platform stride or by the
+architectural frame layout. A GICv4-compatible Redistributor can include
+additional VLPI and reserved frames after the RD and SGI frames. Xen uses the
+Redistributor region description to walk the available Redistributor frames and
+to stop at the end of the described Redistributor sequence.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host Redistributor CPU association
+----------------------------------
+
+`XenSSR~arm64_gicv3_redist_cpu_association~1`
+
+Description:
+Xen shall associate each CPU with the GICv3 Redistributor that corresponds to
+that CPU before using Redistributor-local interrupt state for that CPU. This
+shall include use of Redistributor affinity information reported by:
+
+ - ``GICR_TYPER``
+
+Rationale:
+Redistributor-local registers control SGI and PPI hardware state for one CPU.
+Xen uses Redistributor affinity information to select the Redistributor
+associated with the CPU before programming local interrupt state.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host Redistributor local interrupt initialization
+-------------------------------------------------
+
+`XenSSR~arm64_gicv3_redist_local_int_init~1`
+
+Description:
+Xen shall initialize Redistributor-local SGI and PPI hardware state before
+enabling local interrupt delivery on a CPU. The initialized state shall 
include:
+
+ - Redistributor wakeup state
+ - SGI and PPI priority state
+ - SGI and PPI active state
+ - SGI and PPI enable state
+ - SGI and PPI group state
+
+Rationale:
+The common interrupt-management requirements cover per-CPU local IRQ software
+state. The host GICv3 driver initializes the Redistributor-local hardware state
+used for SGI and PPI delivery before local interrupt delivery is enabled on the
+CPU.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host CPU interface initialization
+---------------------------------
+
+`XenSSR~arm64_gicv3_cpu_interface_init~1`
+
+Description:
+Xen shall initialize the GICv3 CPU interface System register interface before
+enabling Group 1 interrupt delivery on a CPU. This shall include use of the
+following CPU interface System registers:
+
+ - ``ICC_SRE_EL2``
+ - ``ICC_BPR1_EL1``
+ - ``ICC_PMR_EL1``
+ - ``ICC_CTLR_EL1``
+
+Rationale:
+Xen uses the GICv3 CPU interface System registers to control access to the
+System register interface, priority masking, priority drop, deactivation, and
+Group 1 interrupt delivery.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host CPU interface Group 1 delivery control
+-------------------------------------------
+
+`XenSSR~arm64_gicv3_cpu_iface_group1_delivery_control~1`
+
+Description:
+Xen shall use ``ICC_IGRPEN1_EL1`` to enable and disable host Group 1 physical
+interrupt delivery through the GICv3 CPU interface according to the per-CPU
+GICv3 lifecycle state.
+
+Rationale:
+The GICv3 CPU interface controls whether Group 1 physical interrupts can be
+signaled to a CPU. Xen enables Group 1 delivery only after per-CPU GICv3
+initialization has completed and disables Group 1 delivery when shutting down
+the per-CPU GICv3 physical CPU interface.
+
+Covers:
+ - `XenPRQ~intc~1`
+ - `XenPRQ-pcpu_off~1`
+ - `XenPRQ~pcpu_on~1`
+ - `XenPRQ~resume~1`
+ - `XenPRQ~suspend~1`
+
+Needs:
+ - XenVerTestCase
+
+Host SPI and extended SPI affinity routing
+------------------------------------------
+
+`XenSSR~arm64_gicv3_spi_and_espi_affinity_routing~1`
+
+Description:
+Xen shall route a physical SPI or extended SPI to a CPU selected from the
+requested CPU mask. This shall include use of the following Distributor routing
+register groups:
+
+ - ``GICD_IROUTER<n>``
+ - ``GICD_IROUTER<n>E``
+
+Rationale:
+The common interrupt-management requirements define the CPU-affinity contract
+for physical interrupts. The host GICv3 driver realizes that contract for SPIs
+and extended SPIs by programming the corresponding GICv3 Distributor routing
+register group.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host Group 1 interrupt acknowledge
+----------------------------------
+
+`XenSSR~arm64_gicv3_cpu_iface_group1_ack~1`
+
+Description:
+Xen shall acknowledge host Group 1 physical interrupts through the GICv3 CPU
+interface. This shall include reading: ``ICC_IAR1_EL1``.
+
+Rationale:
+``ICC_IAR1_EL1`` is the GICv3 CPU interface register used to acknowledge a
+Group 1 physical interrupt and obtain the INTID selected by the CPU interface.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host Xen-owned physical interrupt completion
+--------------------------------------------
+
+`XenSSR~arm64_gicv3_cpu_iface_host_int_completion~1`
+
+Description:
+Xen shall complete a Xen-owned physical interrupt through the GICv3 CPU
+interface when separate priority-drop and deactivate mode is used. This shall
+include use of:
+
+ - `ICC_EOIR1_EL1`
+ - `ICC_DIR_EL1`
+
+Rationale:
+In separate priority-drop and deactivate mode, `ICC_EOIR1_EL1` drops the
+priority of the interrupt and `ICC_DIR_EL1` deactivates the interrupt. Xen
+uses both operations so that a Xen-owned physical interrupt is no longer active
+after its handler has completed.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host SGI delivery
+-----------------
+
+`XenSSR~arm64_gicv3_cpu_iface_sgi_delivery~1`
+
+Description:
+Xen shall send a host SGI through ``ICC_SGI1R_EL1`` to the CPU targets selected
+by the requested SGI mode and CPU mask.
+
+Rationale:
+``ICC_SGI1R_EL1`` encodes the SGI INTID and the target CPUs selected by Xen.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host secondary CPU physical interrupt readiness
+-----------------------------------------------
+
+`XenSSR~arm64_gicv3_secondary_cpu_phys_int_readiness~1`
+
+Description:
+Xen shall complete per-CPU host GICv3 physical interrupt initialization before
+accepting physical interrupts on a secondary CPU.
+
+Rationale:
+The common interrupt-management requirements cover CPU hotplug notification and
+per-CPU IRQ software state. The host GICv3 driver initializes the
+Redistributor-local hardware state and physical CPU interface state required 
for
+SGI, PPI and routed SPI delivery on the secondary CPU.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host suspend/resume
+^^^^^^^^^^^^^^^^^^^
+
+Suspend/resume GIC context
+--------------------------
+
+The Xen-owned GIC suspend/resume context covers the following register state,
+when the corresponding GIC version and optional feature is implemented and
+enabled on the platform.
+
+CPU interface registers:
+ - ``ICC_CTLR_EL1``
+ - ``ICC_PMR_EL1``
+ - ``ICC_BPR1_EL1``
+ - ``ICC_SRE_EL2``
+ - ``ICC_IGRPEN1_EL1``
+ - ``ICC_AP1R<n>_EL1`` is checked for physical Group 1 active-priority
+   quiescence before suspend and is not restored as normal suspend context.
+
+Distributor registers:
+ - ``GICD_CTLR``
+ - ``GICD_ISENABLER<n>``
+ - ``GICD_ISACTIVER<n>``
+ - ``GICD_IPRIORITYR<n>``
+ - ``GICD_IROUTER<n>``
+ - ``GICD_ICFGR<n>``
+ - ``GICD_IGROUPR<n>`` is re-initialized as part of resume ordering where
+   required by the GICv3 restore sequence.
+
+Redistributor registers:
+ - ``GICR_CTLR``
+ - ``GICR_IPRIORITYR<n>`` for SGI/PPI priority state
+ - ``GICR_ISACTIVER0``
+ - ``GICR_ISENABLER0``
+ - ``GICR_IGROUPR0``
+ - ``GICR_ICFGR1``
+
+Distributor eSPI registers:
+ - ``GICD_ISENABLERnE<n>``
+ - ``GICD_ISACTIVERnE<n>``
+ - ``GICD_IPRIORITYRnE<n>``
+ - ``GICD_IROUTERnE<n>``
+ - ``GICD_ICFGRnE<n>``
+ - ``GICD_IGROUPRnE<n>`` is re-initialized as part of the eSPI resume ordering
+   where required by the GICv3 restore sequence.
+
+The GIC suspend/resume context is limited to state owned by Xen. Guest-owned
+virtual GIC state that is saved and restored on vCPU context switch is not part
+of the host-wide GIC suspend context.
+
+Save GIC state before on suspend
+--------------------------------
+
+`XenSSR~arm64_suspend_resume_gic_save_before_firmware~1`
+
+Description:
+Xen shall save the Xen-owned GIC context before invoking firmware
+``SYSTEM_SUSPEND``, it is required to restore host interrupt management
+after firmware wakeup.
+
+The saved context is described in `Suspend/resume GIC context`_.
+
+Rationale:
+
+Covers:
+ - `XenPRQ~intc~1`
+ - `XenPRQ~suspend~1`
+
+Needs:
+ - XenVerTestCase
+
+Restore GIC state before unmasking local IRQ delivery
+-----------------------------------------------------
+
+`XenSSR~arm64_suspend_resume_gic_restore_before_irq_unmask~1`
+
+Description:
+Xen shall restore the Xen-owned GIC context after firmware resume or
+host-suspend abort, it is required for host interrupt management before
+local IRQ delivery is unmasked on the CPU executing the host resume or
+abort path.
+
+The restored context is described in `Suspend/resume GIC context`_.
+
+Rationale:
+
+Covers:
+ - `XenPRQ~intc~1`
+ - `XenPRQ~resume~1`
+
+Needs:
+ - XenVerTestCase
+
+Quiescent GIC state before suspend point
+----------------------------------------
+
+`XenSSR~arm64_suspend_resume_gic_quiescent_state~1`
+
+Description:
+Xen shall enter a GIC suspend point only after visible active-priority and
+active interrupt state has reached a quiescent state suitable for saving the
+GIC context.
+
+Rationale:
+Saving interrupt-controller state while active state remains visible can make
+the saved GIC context inconsistent with the physical interrupt lifecycle and
+break interrupt restoration after resume.
+
+Covers:
+ - `XenPRQ~intc~1`
+ - `XenPRQ~suspend~1`
+
+Needs:
+ - XenVerTestCase
+
+| [1] Arm Generic Interrupt Controller Architecture Specification (GIC 
architecture version 3 and version 4)
diff --git 
a/software_safety_reqs/domain_creation_and_runtime/physical_resources/arm64/index.rst
 
b/software_safety_reqs/domain_creation_and_runtime/physical_resources/arm64/index.rst
index 8ba4601..71d8981 100644
--- 
a/software_safety_reqs/domain_creation_and_runtime/physical_resources/arm64/index.rst
+++ 
b/software_safety_reqs/domain_creation_and_runtime/physical_resources/arm64/index.rst
@@ -6,6 +6,7 @@ Arm64
 .. toctree::
    :maxdepth: 1
 
+   gicv3
    p2m
    pci_host_rcar
    scif
-- 
2.43.0