[V2] docs: fusa: Add requirements for Device Passthrough

Message ID	20241105154110.2175555-1-olekstysh@gmail.com (mailing list archive)
State	New
Headers	show Return-Path: <xen-devel-bounces@lists.xenproject.org> Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list Sender: "Xen-devel" <xen-devel-bounces@lists.xenproject.org> From: Oleksandr Tyshchenko <olekstysh@gmail.com> To: xen-devel@lists.xenproject.org Cc: Oleksandr Tyshchenko <oleksandr_tyshchenko@epam.com>, Stefano Stabellini <sstabellini@kernel.org>, Bertrand Marquis <bertrand.marquis@arm.com>, Michal Orzel <michal.orzel@amd.com>, Ayan Kumar Halder <ayan.kumar.halder@amd.com>, Artem Mygaiev <artem_mygaiev@epam.com>, Hisao Munakata <hisao.munakata.vt@renesas.com>, Julien Grall <julien@xen.org> Subject: [PATCH V2] docs: fusa: Add requirements for Device Passthrough Date: Tue, 5 Nov 2024 17:41:10 +0200 Message-Id: <20241105154110.2175555-1-olekstysh@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit
Series	[V2] docs: fusa: Add requirements for Device Passthrough \| expand [V2] docs: fusa: Add requirements for Device Passthrough

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

[V2] docs: fusa: Add requirements for Device Passthrough

Commit Message

Patch