[REQUIREMENTS][PATCH v2 4/6] reqs: add host ITS/LPI requirements

Add software requirements for Xen's host-side ITS-backed LPI handling.
Guest-visible ITS behaviour is covered by separate requirement.

Signed-off-by: Mykola Kvach <[email protected]>
---
Changes in v2:
- avoid passive voice in titles.
---
 .../physical_resources/arm64/index.rst        |   1 +
 .../physical_resources/arm64/its.rst          | 519 ++++++++++++++++++
 2 files changed, 520 insertions(+)
 create mode 100644 software_safety_reqs/domain_creation_and_runtime/physical_resources/arm64/its.rst

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 71d8981..cd1aaca 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
@@ -7,6 +7,7 @@ Arm64
    :maxdepth: 1
 
    gicv3
+   its
    p2m
    pci_host_rcar
    scif
diff --git a/software_safety_reqs/domain_creation_and_runtime/physical_resources/arm64/its.rst b/software_safety_reqs/domain_creation_and_runtime/physical_resources/arm64/its.rst
new file mode 100644
index 0000000..6024259
--- /dev/null
+++ b/software_safety_reqs/domain_creation_and_runtime/physical_resources/arm64/its.rst
@@ -0,0 +1,519 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Host ITS/LPI requirements
+=========================
+
+The following requirements define Xen's host-side use of GICv3 ITS and LPI
+interfaces [1]. Guest-visible ITS/vGIC state and GICv4 direct virtual LPI
+delivery are covered by separate requirement groups.
+
+Host ITS Device Tree discovery
+------------------------------
+
+`XenSSR~arm64_gicv3_its_dt_discovery~1`
+
+Description:
+Xen shall discover host ITS frames from Device Tree nodes compatible with
+``arm,gic-v3-its``. This discovery shall include use of the following Device
+Tree state:
+
+ - ITS node compatibility
+ - ITS register frame base address
+ - ITS register frame size
+
+Rationale:
+Xen uses host ITS frames to translate assigned-device MSI events into host
+LPIs.
+
+Covers:
+ - `XenPRQ~boot~1`
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host ITS initialization before use
+----------------------------------
+
+`XenSSR~arm64_gicv3_its_init_before_use~1`
+
+Description:
+Xen shall initialize a discovered host ITS before using it for MSI/LPI
+translation.
+
+Rationale:
+A host ITS translates DeviceID and EventID values into LPIs routed to
+Redistributors. Xen relies on initialized ITS state before creating host event
+mappings.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host ITS quiescent state before configuration
+---------------------------------------------
+
+`XenSSR~arm64_gicv3_its_quiescent_before_config~1`
+
+Description:
+Xen shall put a host ITS into the quiescent state before programming its
+command queue or translation table base registers. This shall include use of:
+
+ - ``GITS_CTLR.Enabled``
+ - ``GITS_CTLR.Quiescent``
+
+Rationale:
+A host ITS can retain outstanding commands or translations. Xen ensures that
+previous ITS activity has completed before programming new host ITS state.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host ITS command queue readiness
+--------------------------------
+
+`XenSSR~arm64_gicv3_its_cmd_queue_ready~1`
+
+Description:
+Xen shall configure the host ITS command queue before issuing host ITS
+commands. This shall include use of:
+
+ - ``GITS_CBASER``
+ - ``GITS_CWRITER``
+ - ``GITS_CREADR``
+
+Rationale:
+Xen issues host ITS commands through the ITS command queue. The command queue
+state determines where command entries are stored and how producer and consumer
+positions are tracked.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host ITS translation table readiness
+------------------------------------
+
+`XenSSR~arm64_gicv3_its_translation_table_ready~1`
+
+Description:
+Xen shall configure the host ITS translation tables required by the selected
+ITS before enabling that ITS. This shall include use of:
+
+ - ``GITS_BASER<n>``
+ - ``GITS_TYPER``
+ - ``GITS_CTLR``
+
+Rationale:
+The ITS uses translation tables to store Device, Collection and other
+implementation-supported translation state.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host ITS command issue
+----------------------
+
+`XenSSR~arm64_gicv3_its_cmd_issue~1`
+
+Description:
+Xen shall issue a host ITS command only after the command queue has space for
+the command entry. This shall include use of:
+
+ - ``GITS_CREADR``
+ - ``GITS_CWRITER``
+
+Rationale:
+The ITS command queue is a circular queue. Xen advances the command queue
+producer position to expose command entries to the ITS.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host ITS command completion
+---------------------------
+
+`XenSSR~arm64_gicv3_its_cmd_completion~1`
+
+Description:
+Xen shall complete the host ITS command sequence required for a mapping before
+reporting that mapping as successful. Depending on the mapping operation, this
+shall include completion of the relevant command sequence using:
+
+ - ``MAPC``
+ - ``MAPD``
+ - ``MAPTI``
+ - ``INV``
+ - ``SYNC``
+
+Rationale:
+Host ITS commands complete asynchronously. Mapping success depends on the host
+ITS completing the commands that create, update or invalidate interrupt
+translation state.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host ITS command failure propagation
+------------------------------------
+
+`XenSSR~arm64_gicv3_its_cmd_failure_propagation~1`
+
+Description:
+Xen shall propagate host ITS command issue or completion failure to the
+operation that depends on that command.
+
+Rationale:
+A host ITS command queue full condition, command issue failure or command
+completion timeout means the dependent ITS translation state cannot be treated
+as committed.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host ITS Redistributor target encoding
+--------------------------------------
+
+`XenSSR~arm64_gicv3_its_rd_target_encoding~1`
+
+Description:
+Xen shall encode host ITS Redistributor targets using the RDbase format selected
+by the host ITS. This shall include use of:
+
+ - ``GITS_TYPER.PTA``
+
+Rationale:
+A host ITS can identify Redistributor targets by physical address or by
+Redistributor processor number. Xen uses the selected ITS target address format
+when encoding commands that refer to Redistributor targets.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host ITS collection target setup
+--------------------------------
+
+`XenSSR~arm64_gicv3_its_collection_target_setup~1`
+
+Description:
+Xen shall complete host ITS collection setup for a CPU before using that CPU as
+an LPI delivery target. This shall include completion of:
+
+ - ``MAPC``
+ - ``SYNC``
+
+Rationale:
+A host ITS collection identifies the Redistributor target used for LPI delivery
+to a CPU.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host ITS DeviceID and EventID range
+-----------------------------------
+
+`XenSSR~arm64_gicv3_its_device_event_range~1`
+
+Description:
+Xen shall map host ITS device events using DeviceID and EventID values within
+the ranges supported by the selected host ITS. This shall include use of:
+
+ - ``GITS_TYPER``
+
+Rationale:
+The host ITS uses DeviceID and EventID values to index interrupt translation
+state. Xen derives the supported ranges from the selected host ITS capability
+state.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host ITS assigned-device mapping setup
+--------------------------------------
+
+`XenSSR~arm64_gicv3_its_assigned_dev_mapping_setup~1`
+
+Description:
+Xen shall complete host ITS device and event mapping before reporting an
+assigned-device interrupt mapping as successful. Depending on the mapping
+operation, this shall include completion of the relevant command sequence using:
+
+ - ``MAPD``
+ - ``MAPTI``
+ - ``INV``
+ - ``SYNC``
+
+Rationale:
+Assigned-device interrupt delivery depends on a valid host device table entry
+and a valid EventID-to-host-LPI translation.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host ITS setup rollback
+-----------------------
+
+`XenSSR~arm64_gicv3_its_setup_rollback~1`
+
+Description:
+Xen shall remove host ITS and host LPI state created for an assigned-device
+event setup when that setup fails before completion.
+
+Rationale:
+Assigned-device interrupt setup can fail after some host ITS or host LPI state
+has been created. Xen removes the partial state so that later interrupts cannot
+use an incomplete mapping.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host LPI support selection
+--------------------------
+
+`XenSSR~arm64_gicv3_lpi_support_selection~1`
+
+Description:
+Xen shall enable host LPI delivery only when the host GIC reports LPI support
+and at least one host ITS has been discovered.
+
+Rationale:
+The reviewed Xen host LPI implementation uses an ITS to translate MSI events
+into LPIs. Without a discovered host ITS, Xen does not configure Redistributor
+LPI delivery for host LPIs.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host LPI Redistributor state readiness
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`XenSSR~arm64_gicv3_lpi_redist_state_readiness~1`
+
+Description:
+Xen shall enable host LPI delivery for a Redistributor only after the LPI
+Property table and a zeroed LPI Pending table for that Redistributor have been
+initialized successfully. This shall include use of:
+
+ - GICR_PROPBASER
+ - GICR_PENDBASER
+ - GICR_CTLR
+
+Rationale:
+The Redistributor uses the LPI Property table to determine LPI enable and
+priority state, and the LPI Pending table to record physical LPI pending state.
+Xen enables host LPI delivery only after both tables have been initialized so
+that host LPIs are delivered using initialized Redistributor LPI state.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host LPI INTID allocation
+-------------------------
+
+`XenSSR~arm64_gicv3_lpi_intid_allocation~1`
+
+Description:
+Xen shall allocate host LPI INTIDs from the physical LPI INTID range supported
+by the host GIC. This shall include use of the following state:
+
+ - ``GICD_TYPER.IDbits``
+ - configured Xen host LPI limit
+
+Rationale:
+Host LPIs are physical interrupt IDs used to represent assigned-device events.
+Xen limits host LPI allocation to the implemented physical INTID range and to
+the configured host LPI limit.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host LPI ownership lookup
+-------------------------
+
+`XenSSR~arm64_gicv3_lpi_delivery_ownership~1`
+
+Description:
+Xen shall resolve a received host LPI to the domain and virtual LPI associated
+with the active host ITS mapping for that device event.
+
+Rationale:
+A host LPI represents an assigned-device event after host ITS translation. Xen
+uses the host LPI ownership state to identify the target domain and virtual LPI
+before handing the interrupt to the virtual interrupt delivery path.
+
+Covers:
+ - `XenPRQ~intc~1`
+
+Needs:
+ - XenVerTestCase
+
+Host suspend/resume
+-------------------
+
+Suspend/resume ITS context
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The suspend/resume requirements below apply to Xen-owned host ITS state and
+Redistributor LPI state. The covered context includes the following state, when
+the corresponding feature is implemented and enabled on the platform.
+
+ITS state:
+
+ - ``GITS_CTLR``
+ - ``GITS_CBASER``
+ - ``GITS_BASER<n>``
+ - ``GITS_CWRITER`` is reset after restoring ``GITS_CBASER`` so that command
+   queue pointers are coherent after resume.
+ - ITS collection state is replayed only when the collection is held in the ITS
+   itself. Memory-backed collections are restored through the restored
+   ``GITS_BASER<n>`` tables and are not remapped unconditionally.
+
+Redistributor LPI state:
+
+ -  ``GICR_PROPBASER``
+ -  ``GICR_PENDBASER``
+
+Save host ITS/LPI state before suspend
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`XenSSR~arm64_suspend_resume_its_lpi_save_before_firmware~1`
+
+Description:
+Xen shall save the Xen-owned host ITS/LPI context required to restore host
+MSI-to-LPI translation and LPI delivery after firmware wakeup before invoking
+firmware ``SYSTEM_SUSPEND``. The saved context is described in the
+`Suspend/resume ITS context`_.
+
+Rationale:
+Firmware suspend can remove or reset host ITS and Redistributor LPI state. Xen
+saves the Xen-owned ITS/LPI state before entering firmware suspend so that host
+MSI-to-LPI translation and LPI delivery can be restored after wakeup.
+
+Covers:
+ - `XenPRQ~intc~1`
+ - `XenPRQ~suspend~1`
+
+Needs:
+ - XenVerTestCase
+
+Restore host ITS/LPI state before use
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`XenSSR~arm64_suspend_resume_its_lpi_restore_before_use~1`
+
+Description:
+Xen shall restore the Xen-owned host ITS/LPI context after firmware resume or
+host-suspend abort before issuing host ITS commands or relying on host LPI
+delivery. The restored context is described in the `Suspend/resume ITS context`_.
+
+Rationale:
+Host ITS commands and host LPI delivery rely on initialized ITS tables, command
+queue state, and Redistributor LPI state. Xen restores the Xen-owned ITS/LPI
+context before using the host ITS or relying on host LPI delivery after resume
+or suspend abort.
+
+Covers:
+ - `XenPRQ~intc~1`
+ - `XenPRQ~resume~1`
+
+Needs:
+ - XenVerTestCase
+
+Replay ITS-backed collection mappings when required
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`XenSSR~arm64_suspend_resume_its_collection_replay_conditional~1`
+
+Description:
+Xen shall replay host ITS collection mappings on resume only for collection IDs
+held in the ITS itself, as indicated by ``GITS_TYPER.HCC``. This shall include
+use of:
+
+ - ``GITS_TYPER.HCC``
+ - ``MAPC``
+ - ``SYNC``
+
+Xen shall use the restored ``GITS_BASER<n>`` translation table state as the
+source of collection state for memory-backed collections.
+
+Rationale:
+ITS collection state can be held either in the ITS itself or in memory-backed
+tables. Replaying collection mappings for memory-backed collections can
+duplicate or overwrite state that has already been restored through
+``GITS_BASER<n>``. Conditioning replay on ``GITS_TYPER.HCC`` keeps the resume
+path aligned with the ITS collection storage model.
+
+Covers:
+ - `XenPRQ~intc~1`
+ - `XenPRQ~resume~1`
+
+Needs:
+ - XenVerTestCase
+
+Tolerate retained Redistributor LPI state
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`XenSSR~arm64_suspend_resume_its_retained_redist_lpi_state~1`
+
+Description:
+Xen shall tolerate platforms where Redistributor LPI state is retained across
+CPU_OFF/CPU_ON or host suspend/resume, and shall avoid reinitializing retained
+Redistributor LPI state as lost state.
+
+Rationale:
+Some platforms retain Redistributor LPI state across CPU power transitions or
+host suspend/resume. Incorrect reinitialization can corrupt retained pending or
+configured LPI state.
+
+Covers:
+ - `XenPRQ~intc~1`
+ - `XenPRQ~pcpu_on~1`
+ - `XenPRQ~resume~1`
+
+Needs:
+ - XenVerTestCase
+
+| [1] Arm Generic Interrupt Controller Architecture Specification (GIC architecture version 3 and version 4)
-- 
2.43.0