From nobody Sun Dec 22 12:00:49 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=pass(p=none dis=none) header.from=gmail.com ARC-Seal: i=1; a=rsa-sha256; t=1728327368; cv=none; d=zohomail.com; s=zohoarc; b=ns17i853tA06fdjTl8ykVetEFtsnfsAsN+E3BVl5hGcDUd7KTIUkpWFftDBeNxNqEadz7DFLsIXODHmXilhNuw0tNh22zhDtVWIDJRlEamNL68V6TEVLfYoeq+FAMjROmsE4ELrra2W4kbFsAtxklHZ6wmsSkQqvBW5i6uGbx0M= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1728327368; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=0O/bwYVoYbl6H5jEzHRfmeoSwPu6F3N4nQtAhVDwn+U=; b=IFrPps3tRw3yYwhh8CNgr3VJlYlZXaVxzBxiYVr2qUp1OsjZntdpNtN+sYoByEkDW4ZQ0ZfVN2zoWJFi13Qed0ViYmigEIIrbBtd7ntLoI5UPpDLDr4vj+kF9gxNFTLZGcs1ALMs7p7/S0eQNdQVRMfszW7cNERp5W5C5v2VUo8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1728327368361630.7033473160084; Mon, 7 Oct 2024 11:56:08 -0700 (PDT) Received: from list by lists.xenproject.org with outflank-mailman.812348.1225080 (Exim 4.92) (envelope-from ) id 1sxstV-000354-Ox; Mon, 07 Oct 2024 18:55:45 +0000 Received: by outflank-mailman (output) from mailman id 812348.1225080; Mon, 07 Oct 2024 18:55:45 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1sxstV-00034v-M7; Mon, 07 Oct 2024 18:55:45 +0000 Received: by outflank-mailman (input) for mailman id 812348; Mon, 07 Oct 2024 18:55:44 +0000 Received: from se1-gles-sth1-in.inumbo.com ([159.253.27.254] helo=se1-gles-sth1.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1sxstT-00031L-Qc for xen-devel@lists.xenproject.org; Mon, 07 Oct 2024 18:55:43 +0000 Received: from mail-lf1-x12d.google.com (mail-lf1-x12d.google.com [2a00:1450:4864:20::12d]) by se1-gles-sth1.inumbo.com (Halon) with ESMTPS id c099259e-84dd-11ef-a0bb-8be0dac302b0; Mon, 07 Oct 2024 20:55:42 +0200 (CEST) Received: by mail-lf1-x12d.google.com with SMTP id 2adb3069b0e04-5398d171fa2so5456393e87.0 for ; Mon, 07 Oct 2024 11:55:42 -0700 (PDT) Received: from EPUAKYIW03DD.. ([91.123.151.46]) by smtp.gmail.com with ESMTPSA id 2adb3069b0e04-539aff23530sm903643e87.239.2024.10.07.11.55.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 07 Oct 2024 11:55:39 -0700 (PDT) X-Outflank-Mailman: Message body and most headers restored to incoming version X-BeenThere: xen-devel@lists.xenproject.org List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list Sender: "Xen-devel" X-Inumbo-ID: c099259e-84dd-11ef-a0bb-8be0dac302b0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1728327342; x=1728932142; darn=lists.xenproject.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=0O/bwYVoYbl6H5jEzHRfmeoSwPu6F3N4nQtAhVDwn+U=; b=LNm9OnFzqyClPXyBbLjPnSQPmqPfA76E1z5czt8gmTofQCTNP0BpRQFuxRyuRdrBVP T0y+0F1Laui1u9FSL8RE9nGl5TsT8UoKVLvqO2G8ib4qrI64SfGjdtyQhK9lOB5tUueA 7ImXSJE21zBJuTxsYAeZc2IdeBzB7MXDWmC10rqhtpaTdkgYPgOwoMZlgBp4sS+dUDb8 aaFm9GHRdvrnkmFJwb82iusZYptc2L93QBU9nXlJHIXB2blNLgaPDVzp/3Pe0MP9xaj4 C9Tv4rcKG3LFeqZycXbecLFpm2/FfX1ZATlK/1WGc7V367+Vhc77lran/6m1CVwKeUij pbOg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1728327342; x=1728932142; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=0O/bwYVoYbl6H5jEzHRfmeoSwPu6F3N4nQtAhVDwn+U=; b=qwQQ3cJjCL9kGMAiSP9I/ijecblHvMVymLhKP8f3ZwWorQJkCZgF/eaRdVbAYa0pIZ dKdgs7zB357xe5BqbkVGS41fEVIwVfIBph2mSV3LLHW9ga41yG5ESbdKaxNPPw7rm0Ip 3Ut7NYzkhsgZnloUyEQ4/5ImMAZdOXFbAJV/wvZAffK5y46ZkjEqqo88HQ8jd2pDE8fj WHdJarel8k56rpeWN2I8Q6Q0iePhK/WvGJdJb35620JWCDqxierCjccx5zIrta84ezfP BlE8nCJGCHLcp0JTf7JcIPXOkR3LgOkSKRCu9nQMj18djNm+f7Z6Q9idn5v4ERlSL6pl V9ag== X-Gm-Message-State: AOJu0YxwArIG59/6PmpoiDbndSCFbfk4pZwsS/1VG1Bk0OUdcCO8i8Zd PkvGREW8tRfnmmj7VybbT/kPpz2akR4Hlg7cx8P2Ci95Fr9R2EXohN4oIA== X-Google-Smtp-Source: AGHT+IE1dijPr6it5cor4eT0Dl7l9AHJXIHyY/lyMwb9CGjNnafq4K6WEn5eNDOGsSytgTdPtHv3RA== X-Received: by 2002:a05:6512:1155:b0:539:9225:43a6 with SMTP id 2adb3069b0e04-539ab88ccb1mr7667357e87.35.1728327341455; Mon, 07 Oct 2024 11:55:41 -0700 (PDT) From: Oleksandr Tyshchenko To: xen-devel@lists.xenproject.org Cc: Oleksandr Tyshchenko , Stefano Stabellini , Bertrand Marquis , Michal Orzel , Ayan Kumar Halder , Artem Mygaiev , Hisao Munakata Subject: [PATCH] docs: fusa: Add requirements for Device Passthrough Date: Mon, 7 Oct 2024 21:55:08 +0300 Message-Id: <20241007185508.3044115-1-olekstysh@gmail.com> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @gmail.com) X-ZM-MESSAGEID: 1728327370253116600 Content-Type: text/plain; charset="utf-8" From: Oleksandr Tyshchenko Add common requirements for a physical device assignment to Arm64 and AMD64 PVH domains. Signed-off-by: Oleksandr Tyshchenko --- Based on: [PATCH] docs: fusa: Replace VM with domain https://patchew.org/Xen/20241007182603.826807-1-ayan.kumar.halder@amd.com/ --- --- .../reqs/design-reqs/common/passthrough.rst | 365 ++++++++++++++++++ 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, 428 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..a1d6676f65 --- /dev/null +++ b/docs/fusa/reqs/design-reqs/common/passthrough.rst @@ -0,0 +1,365 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Device Passthrough +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The following are the requirements related to a physical device assignment +[1], [2] to Arm64 and AMD64 PVH domains. + +Requirements for both Arm64 and AMD64 PVH +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Hide IOMMU from a domain +------------------------ + +`XenSwdgn~passthrough_hide_iommu_from_domain~1` + +Description: +Xen shall not expose the IOMMU device to the domain even if I/O virtualiza= tion +is disabled. The IOMMU shall be under hypervisor control only. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Discover PCI devices from hardware domain +----------------------------------------- + +`XenSwdgn~passthrough_discover_pci_devices_from_hwdom~1` + +Description: +The hardware domain shall enumerate and discover PCI devices and inform Xen +about their appearance and disappearance. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Discover PCI devices from Xen +----------------------------- + +`XenSwdgn~passthrough_discover_pci_devices_from_xen~1` + +Description: +Xen shall discover PCI devices (enumerated by the firmware beforehand) dur= ing +boot if the hardware domain is not present. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Assign PCI device to domain (with IOMMU) +---------------------------------------- + +`XenSwdgn~passthrough_assign_pci_device_with_iommu~1` + +Description: +Xen shall assign a specified PCI device (always implied as DMA-capable) to +a domain during its creation using passthrough (partial) device tree on Ar= m64 +and Hyperlaunch device tree on AMD-x86. The physical device to be assigned= is +protected by the IOMMU. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Deassign PCI device from domain (with IOMMU) +-------------------------------------------- + +`XenSwdgn~passthrough_deassign_pci_device_with_iommu~1` + +Description: +Xen shall deassign a specified PCI device from a domain during its destruc= tion. +The physical device to be deassigned is protected by the IOMMU. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Forbid the same PCI device assignment to multiple domains +--------------------------------------------------------- + +`XenSwdgn~passthrough_forbid_same_pci_device_assignment~1` + +Description: +Xen shall not assign the same PCI device to multiple domains by failing to +create a new domain if the device to be passed through is already assigned +to the existing domain. Also different PCI devices which share some resour= ces +(interrupts, IOMMU connections) can be assigned only to the same domain. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Requirements for Arm64 only +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + +Assign interrupt-less platform device to domain +----------------------------------------------- + +`XenSwdgn~passthrough_assign_interrupt_less_platform_device~1` + +Description: +Xen shall assign a specified platform device that has only a MMIO region +(does not have any interrupts) to a domain during its creation using passt= hrough +device tree. +The example of interrupt-less device is PWM or clock controller. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Deassign interrupt-less platform device from domain +--------------------------------------------------- + +`XenSwdgn~passthrough_deassign_interrupt_less_platform_device~1` + +Description: +Xen shall deassign a specified platform device that has only a MMIO region +(does not have any interrupts) from a domain during its destruction. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Assign non-DMA-capable platform device to domain +------------------------------------------------ + +`XenSwdgn~passthrough_assign_non_dma_platform_device~1` + +Description: +Xen shall assign a specified non-DMA-capable platform device to a domain d= uring +its creation using passthrough device tree. +The example of non-DMA-capable device is Timer. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Deassign non-DMA-capable platform device from domain +---------------------------------------------------- + +`XenSwdgn~passthrough_deassign_non_dma_platform_device~1` + +Description: +Xen shall deassign a specified non-DMA-capable platform device from a doma= in +during its destruction. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Assign DMA-capable platform device to domain (with IOMMU) +--------------------------------------------------------- + +`XenSwdgn~passthrough_assign_dma_platform_device_with_iommu~1` + +Description: +Xen shall assign a specified DMA-capable platform device to a domain during +its creation using passthrough device tree. The physical device to be assi= gned +is protected by the IOMMU. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Deassign DMA-capable platform device from domain (with IOMMU) +------------------------------------------------------------- + +`XenSwdgn~passthrough_deassign_dma_platform_device_with_iommu~1` + +Description: +Xen shall deassign a specified DMA-capable platform device from a domain d= uring +its destruction. The physical device to be deassigned is protected by the = IOMMU. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Assign DMA-capable platform device to domain (without IOMMU) +------------------------------------------------------------ + +`XenSwdgn~passthrough_assign_dma_platform_device_without_iommu~1` + +Description: +Xen shall assign a specified DMA-capable platform device to a domain during +its creation using passthrough device tree. The physical device to be assi= gned +is not protected by the IOMMU. +The DMA-capable device assignment which is not behind an IOMMU is allowed = for +the direct mapped domains only. The direct mapped domain must be either sa= fe or +additional security mechanisms for protecting against possible malicious or +buggy DMA devices must be in place, e.g. Xilinx memory protection unit (XM= PU) +and Xilinx peripheral protection unit (XPPU). + +Rationale: +The IOMMU is absent from the system or it is disabled (status =3D "disable= d" +in the host device tree). + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Deassign DMA-capable platform device from domain (without IOMMU) +---------------------------------------------------------------- + +`XenSwdgn~passthrough_deassign_dma_platform_device_without_iommu~1` + +Description: +Xen shall deassign a specified DMA-capable platform device from a domain d= uring +its destruction. The physical device to be deassigned is not protected +by the IOMMU. + +Rationale: +The IOMMU is absent from the system or it is disabled (status =3D "disable= d" +in the host device tree). + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Map platform device MMIO region identity +---------------------------------------- + +`XenSwdgn~passthrough_map_platform_device_mmio_region_ident~1` + +Description: +Xen shall map platform device memory region identity (guest address =3D=3D +physical address) when assigning a specified platform device to a domain. +The device can be either non-DMA-capable or DMA-capable. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Map platform device MMIO region non-identity +-------------------------------------------- + +`XenSwdgn~passthrough_map_platform_device_mmio_region_non_ident~1` + +Description: +Xen shall map platform device memory region non-identity (guest address != =3D +physical address) when assigning a specified platform device to a domain. +The device can be either non-DMA-capable or DMA-capable. + +Rationale: + +Covers: + - `XenProd~device_passthrough~1` + +Assign PCI device to domain (without IOMMU) +------------------------------------------- + +`XenSwdgn~passthrough_assign_pci_device_without_iommu~1` + +Description: +Xen shall assign a specified PCI device to a domain during its creation us= ing +passthrough device tree. The physical device to be assigned is not protect= ed +by the IOMMU. +The DMA-capable device assignment which is not behind an IOMMU is allowed = for +the direct mapped domains only. The direct mapped domain must be either sa= fe or +additional security mechanisms for protecting against possible malicious or +buggy DMA devices must be in place, e.g. Xilinx memory protection unit (XM= PU) +and Xilinx peripheral protection unit (XPPU). + +Rationale: +The IOMMU is absent from the system or it is disabled (status =3D "disable= d" +in the host device tree). + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Deassign PCI device from domain (without IOMMU) +----------------------------------------------- + +`XenSwdgn~passthrough_deassign_pci_device_without_iommu~1` + +Description: +Xen shall deassign a specified PCI device from a domain during its destruc= tion. +The physical device to be deassigned is not protected by the IOMMU. + +Rationale: +The IOMMU is absent from the system or it is disabled (status =3D "disable= d" +in the host device tree). + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Forbid the same platform device assignment to multiple domains +-------------------------------------------------------------- + +`XenSwdgn~passthrough_forbid_same_platform_device_assignment~1` + +Description: +Xen shall not assign the same platform device to multiple domains by faili= ng +to create a new domain if the device to be passed through is already assig= ned +to the existing domain. Also, different platform devices which share some +resources (interrupts, IOMMU connections) can be assigned only to the same +domain. + +Rationale: + +Comments: + +Covers: + - `XenProd~device_passthrough~1` + +Notes +=3D=3D=3D=3D=3D + +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 pass= ed +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=3Dxen.git;a=3Dblob;f=3Ddocs/m= isc/arm/passthrough.txt;hb=3DHEAD +[2] https://xenbits.xenproject.org/gitweb/?p=3Dxen.git;a=3Dblob;f=3Ddocs/m= isc/arm/passthrough-noiommu.txt;hb=3DHEAD 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-re= qs/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: =20 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 do= main +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/p= roduct-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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + +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 --=20 2.34.1