From: Oleksandr Tyshchenko <oleksandr_tyshchenko@epam.com>

Add common requirements for a physical device assignment to Arm64
and AMD64 PVH domains.

Signed-off-by: Oleksandr Tyshchenko <oleksandr_tyshchenko@epam.com>
---
Previous discussion (V1) here:
https://lists.xenproject.org/archives/html/xen-devel/2024-10/msg00534.html

  V2:
    A lot of changes... Reworked the document significantly. Incorporated review
    comments done for V1: The main changes are:
     - split complex requirements
     - clarify existing requirements
     - generalize requirements
     - add more requirements
     - drop redundant requirements
---
---
 .../reqs/design-reqs/common/passthrough.rst   | 432 ++++++++++++++++++
 docs/fusa/reqs/index.rst                      |   1 +
 docs/fusa/reqs/market-reqs/reqs.rst           |  33 ++
 docs/fusa/reqs/product-reqs/common/reqs.rst   |  29 ++
 4 files changed, 495 insertions(+)
 create mode 100644 docs/fusa/reqs/design-reqs/common/passthrough.rst
 create mode 100644 docs/fusa/reqs/product-reqs/common/reqs.rst

diff --git a/docs/fusa/reqs/design-reqs/common/passthrough.rst b/docs/fusa/reqs/design-reqs/common/passthrough.rst
new file mode 100644
index 0000000000..58a140a0a1
--- /dev/null
+++ b/docs/fusa/reqs/design-reqs/common/passthrough.rst
@@ -0,0 +1,432 @@
+
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Device Passthrough
+==================
+
+The following are the requirements related to a physical device assignment
+[1], [2] to Arm64 and AMD64 PVH boot time domains.
+
+Requirements for both Arm64 and AMD64 PVH
+=========================================
+
+Configure IOMMU at boot
+-----------------------
+
+`XenSwdgn~passthrough_configure_iommu_at_boot~1`
+
+Description:
+Xen shall configure the IOMMU at domain creation time according to the stage-2
+(or 2nd stage) translation tables.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Provide interface for addition and removal of PCI devices
+---------------------------------------------------------
+
+`XenSwdgn~passthrough_provide_if_for_add_rm_pci_devs~1`
+
+Description:
+Xen shall provide hypercalls to allow the hardware domain to inform Xen about
+the appearance and disappearance of PCI devices.
+
+Rationale:
+The hardware domain enumerates and discovers PCI devices.
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Discover PCI devices from Xen
+-----------------------------
+
+`XenSwdgn~passthrough_discover_pci_devs_from_xen~1`
+
+Description:
+Xen shall discover PCI devices (enumerated by the firmware beforehand) at boot.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Support assignment of PCI devices
+---------------------------------
+
+`XenSwdgn~passthrough_support_assign_pci_devs~1`
+
+Description:
+Xen shall support the assignment of PCI devices to the domains. The PCI device
+is always implied as DMA-capable and interrupt-driven.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Support deassignment of PCI devices
+-----------------------------------
+
+`XenSwdgn~passthrough_support_deassign_pci_devs~1`
+
+Description:
+Xen shall support the deassignment of PCI devices from the domains.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Deassign PCI device from domain
+-------------------------------
+
+`XenSwdgn~passthrough_deassign_pci_dev_from_dom~1`
+
+Description:
+Xen shall deassign a specified PCI device from a domain during its destruction.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Assign single device to single domain
+-------------------------------------
+
+`XenSwdgn~passthrough_assign_single_dev_to_single_dom~1`
+
+Description:
+Xen shall assign a single device to a single domain. Xen shall fail to create
+a new domain if the device to be passed through is already assigned to
+the existing domain.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Assign devices sharing resources to same domain
+-----------------------------------------------
+
+`XenSwdgn~passthrough_assign_devs_sharing_res_to_same_dom~1`
+
+Description:
+Xen shall assign devices that share some resources (interrupts or IOMMU
+connections) to the same domain. Xen shall fail to create a new domain if
+the device to be passed through shares resources with the device already
+assigned to the existing domain.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Enable IOMMU to perform DMA Remapping for device
+------------------------------------------------
+
+`XenSwdgn~passthrough_enable_iommu_to_perform_dma_remapping_for_dev~1`
+
+Xen shall enable IOMMU to perform stage-2 (or 2nd stage) address translations
+for the DMA operations done by a DMA-capable device when assigning it
+to a domain.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Use IOMMU to enforce DMA operations from device
+------------------------------------------------
+
+`XenSwdgn~passthrough_use_iommu_to_enforce_dma_ops_from_dev~1`
+
+Description:
+Xen shall use the IOMMU to enforce DMA operations done by a DMA-capable device
+assigned to a domain to be restricted to the memory of the given domain.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Use IOMMU to deny DMA operations from device
+--------------------------------------------
+
+`XenSwdgn~passthrough_use_iommu_to_deny_dma_ops_from_dev~1`
+
+Description:
+Xen shall use the IOMMU to deny DMA operations done by a DMA-capable device
+not assigned to any domain (deassigned from a domain).
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Map device memory region
+------------------------
+
+`XenSwdgn~passthrough_map_dev_mem_region~1`
+
+Description:
+Xen shall map the device memory (i.e. MMIO) region into stage-2 (or 2nd stage)
+translation tables when assigning a specified device to a domain so the domain
+can configure and use the device.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Deliver MSIs to domain
+----------------------
+
+`XenSwdgn~passthrough_deliver_msis_to_dom~1`
+
+Xen shall inject associated with the MSI-capable (i.e. PCI) device interrupts
+(MSIs) into the domain to which the device is assigned whenever interrupts
+are generated.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Requirements for Arm64 only
+===========================
+
+Support assignment of platform devices
+--------------------------------------
+
+`XenSwdgn~passthrough_support_assign_dt_devs~1`
+
+Description:
+Xen shall support the assignment of platform devices to the domains.
+The platform device can be either non-DMA-capable or DMA-capable.
+The platform device can be either interrupt-less or interrupt-driven.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Support deassignment of platform devices
+----------------------------------------
+
+`XenSwdgn~passthrough_support_deassign_dt_devs~1`
+
+Description:
+Xen shall support the deassignment of platform devices from the domains.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Assign platform device to domain
+--------------------------------
+
+`XenSwdgn~arm64_passthrough_assign_dt_dev_to_dom~1`
+
+Description:
+Xen shall assign a specified platform device to a domain during its creation
+using passthrough (partial) device tree.
+
+Rationale:
+
+ - The passthrough device tree is specified using a device tree module node
+   with compatible ("multiboot,device-tree") in the host device tree.
+ - The passthrough device tree shall entirely describe the platform device to
+   be passed through to a domain so the domain can discover and use the device.
+ - The intention of the platform device usage for the passthrough is specified
+   using device tree property ("xen,passthrough") in the device node described
+   in the host device tree.
+ - The memory region of the platform device and the corresponding guest address
+   for remapping are specified using the device tree property ("xen,reg") in
+   the device node described in the passthrough device tree.
+ - The path of the platform device node in the host device tree is specified
+   using the device tree property ("xen,path") in the device node described
+   in the passthrough device tree. Both interrupt mappings and IOMMU settings
+   are based on it.
+ - The allowance of the platform device assignment which is not behind an IOMMU
+   (for both non-DMA-capable and DMA-capable devices) is specified using
+   the device tree property ("xen,force-assign-without-iommu") in the device
+   node described in the passthrough device tree. The said property also allows
+   the interrupt-less platform device assignment (a device that has only
+   an memory region) without specifying the corresponding node in the host
+   device via device tree property ("xen,path").
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Deassign platform device from domain
+------------------------------------
+
+`XenSwdgn~passthrough_deassign_dt_dev_from_dom~1`
+
+Description:
+Xen shall deassign a specified platform device from a domain during its
+destruction.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Assign PCI device to domain on Arm64
+------------------------------------
+
+`XenSwdgn~passthrough_assign_pci_dev_to_dom_arm64~1`
+
+Description:
+Xen shall assign a specified PCI device to a domain during its creation using
+passthrough (partial) device tree.
+
+Rationale:
+
+ - The passthrough device tree is specified using a device tree module node
+   with compatible ("multiboot,device-tree") in the host device tree.
+ - The PCI device to be passed through is specified using device tree property
+   ("xen,pci-assigned") in the "passthrough" node described in the passthrough
+   device tree.
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Support creation of direct mapped domains
+-----------------------------------------
+
+`XenSwdgn~passthrough_support_creation_direct_mapped_doms~1`
+
+Description:
+Xen shall support the creation of direct mapped (guest frame number == machine
+frame number) domains using passthrough (partial) device tree.
+
+Rationale:
+The assignment of DMA-capable device which is not behind an IOMMU is allowed
+for the trusted direct mapped domains only.
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Deliver SPIs to domain
+----------------------
+
+`XenSwdgn~passthrough_deliver_spis_to_dom~1`
+
+Xen shall inject associated with the platform device interrupts (SPIs) into
+the domain to which the device is assigned whenever interrupts are generated.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Requirements for AMD64 PVH only
+===============================
+
+Assign PCI device to domain on AMD-x86
+--------------------------------------
+
+`XenSwdgn~passthrough_assign_pci_dev_to_dom_x86~1`
+
+Description:
+Xen shall assign a specified PCI device to a domain during its creation using
+Hyperlaunch device tree.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Enable IOMMU to perform Interrupt Remapping for device
+------------------------------------------------------
+
+`XenSwdgn~passthrough_enable_iommu_to_perform_irq_remapping_for_dev~1`
+
+Xen shall enable the IOMMU to perform filtering (permission checking) and
+Interrupt Remapping for the device interrupts when assigning a specified device
+to a domain.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Use IOMMU to enforce interrupt generation from device
+-----------------------------------------------------
+
+`XenSwdgn~passthrough_use_iommu_to_enforce_irq_gen_from_dev~1`
+
+Description:
+Xen shall use the IOMMU to ensure that the device can only generate interrupts
+for the domain to which it is assigned.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~device_passthrough~1`
+
+Notes
+=====
+
+The AMD64 PVH-specific requirements are written under the assumption that once
+the Hyperlaunch feature is completed, Xen shall assign a PCI device to boot
+time domains. This is not the case today, where the PCI device can be passed
+through only to domains launched by a control (toolstack) domain.
+
+The Arm64-specific requirements are written under the assumption that once
+the dom0less PCI Passthrough feature is completed, Xen shall assign a PCI device
+to boot time domains. This is not the case today, where only the platform device
+Passthrough is supported.
+
+[1] https://xenbits.xenproject.org/gitweb/?p=xen.git;a=blob;f=docs/misc/arm/passthrough.txt;hb=HEAD
+[2] https://xenbits.xenproject.org/gitweb/?p=xen.git;a=blob;f=docs/misc/arm/passthrough-noiommu.txt;hb=HEAD
diff --git a/docs/fusa/reqs/index.rst b/docs/fusa/reqs/index.rst
index 183f183b1f..19c2f26b2b 100644
--- a/docs/fusa/reqs/index.rst
+++ b/docs/fusa/reqs/index.rst
@@ -10,3 +10,4 @@ Requirements documentation
    market-reqs
    product-reqs
    design-reqs/arm64
+   design-reqs/common
diff --git a/docs/fusa/reqs/market-reqs/reqs.rst b/docs/fusa/reqs/market-reqs/reqs.rst
index f456788d96..37a443395b 100644
--- a/docs/fusa/reqs/market-reqs/reqs.rst
+++ b/docs/fusa/reqs/market-reqs/reqs.rst
@@ -47,3 +47,36 @@ Comments:
 
 Needs:
  - XenProd
+
+Run AMD-x86 domains
+-------------------
+
+`XenMkt~run_x86_domains~1`
+
+Description:
+Xen shall run AMD-x86 domains.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
+
+Domain device assignment
+------------------------
+
+`XenMkt~domain_device_assignment~1`
+
+Description:
+Xen shall assign device to each domain.
+
+For example, it shall assign GPU to domain A, MMC to domain B. Only the domain
+assigned to a device, shall have exclusive access to the device.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
diff --git a/docs/fusa/reqs/product-reqs/common/reqs.rst b/docs/fusa/reqs/product-reqs/common/reqs.rst
new file mode 100644
index 0000000000..9304399e4d
--- /dev/null
+++ b/docs/fusa/reqs/product-reqs/common/reqs.rst
@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Domain Creation And Runtime
+===========================
+
+Device Passthrough
+------------------
+
+`XenProd~device_passthrough~1`
+
+Description:
+Xen shall provide mechanism for assigning a physical device to the domains.
+
+For example:
+
+- PCI passthrough
+- MMC passthrough
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~run_arm64_domains~1`
+ - `XenMkt~run_x86_domains~1`
+ - `XenMkt~domain_device_assignment~1`
+
+Needs:
+ - XenSwdgn
-- 
2.34.1