Re: [PATCH v2 1/9] docs: Document IO Address Space ID (IOASID) APIs
On Mon, 7 Sep 2020 10:03:39 +0200 Auger Eric wrote: > Hi Jacob, > > On 9/1/20 6:56 PM, Jacob Pan wrote: > > Hi Eric, > > > > On Thu, 27 Aug 2020 18:21:07 +0200 > > Auger Eric wrote: > > > >> Hi Jacob, > >> On 8/24/20 12:32 PM, Jean-Philippe Brucker wrote: > >>> On Fri, Aug 21, 2020 at 09:35:10PM -0700, Jacob Pan wrote: > IOASID is used to identify address spaces that can be targeted by > device DMA. It is a system-wide resource that is essential to its > many users. This document is an attempt to help developers from > all vendors navigate the APIs. At this time, ARM SMMU and Intel’s > Scalable IO Virtualization (SIOV) enabled platforms are the > primary users of IOASID. Examples of how SIOV components interact > with IOASID APIs are provided in that many APIs are driven by the > requirements from SIOV. > > Signed-off-by: Liu Yi L > Signed-off-by: Wu Hao > Signed-off-by: Jacob Pan > --- > Documentation/ioasid.rst | 618 > +++ 1 file changed, > 618 insertions(+) create mode 100644 Documentation/ioasid.rst > > diff --git a/Documentation/ioasid.rst b/Documentation/ioasid.rst > >>> > >>> Thanks for writing this up. Should it go to > >>> Documentation/driver-api/, or Documentation/driver-api/iommu/? I > >>> think this also needs to Cc linux-...@vger.kernel.org and > >>> cor...@lwn.net > new file mode 100644 > index ..b6a8cdc885ff > --- /dev/null > +++ b/Documentation/ioasid.rst > @@ -0,0 +1,618 @@ > +.. ioasid: > + > += > +IO Address Space ID > += > + > +IOASID is a generic name for PCIe Process Address ID (PASID) or > ARM +SMMU sub-stream ID. An IOASID identifies an address space > that DMA > >>> > >>> "SubstreamID" > >> On ARM if we don't use PASIDs we have streamids (SID) which can also > >> identify address spaces that DMA requests can target. So maybe this > >> definition is not sufficient. > >> > > According to SMMU spec, the SubstreamID is equivalent to PASID. My > > understanding is that SID is equivalent to PCI requester ID that > > identifies stage 2. Do you plan to use IOASID for stage 2? > No. So actually if PASID is not used we still have a default single > IOASID matching the single context. So that may be fine as a definition. OK, thanks for explaining. > > IOASID is mostly for SVA and DMA request w/ PASID. > > > >>> > +requests can target. > + > +The primary use cases for IOASID are Shared Virtual Address (SVA) > and +IO Virtual Address (IOVA). However, the requirements for > IOASID > >>> > >>> IOVA alone isn't a use case, maybe "multiple IOVA spaces per > >>> device"? > +management can vary among hardware architectures. > + > +This document covers the generic features supported by IOASID > +APIs. Vendor-specific use cases are also illustrated with Intel's > VT-d +based platforms as the first example. > + > +.. contents:: :local: > + > +Glossary > + > +PASID - Process Address Space ID > + > +IOASID - IO Address Space ID (generic term for PCIe PASID and > +sub-stream ID in SMMU) > >>> > >>> "SubstreamID" > >>> > + > +SVA/SVM - Shared Virtual Addressing/Memory > + > +ENQCMD - New Intel X86 ISA for efficient workqueue submission > [1] > >>> > >>> Maybe drop the "New", to keep the documentation perennial. It might > >>> be good to add internal links here to the specifications URLs at > >>> the bottom. > + > +DSA - Intel Data Streaming Accelerator [2] > + > +VDCM - Virtual device composition module [3] > + > +SIOV - Intel Scalable IO Virtualization > + > + > +Key Concepts > + > + > +IOASID Set > +--- > +An IOASID set is a group of IOASIDs allocated from the system-wide > +IOASID pool. An IOASID set is created and can be identified by a > +token of u64. Refer to IOASID set APIs for more details. > >>> > >>> Identified either by an u64 or an mm_struct, right? Maybe just > >>> drop the second sentence if it's detailed in the IOASID set section > >>> below. > + > +IOASID set is particularly useful for guest SVA where each guest > could +have its own IOASID set for security and efficiency reasons. > + > +IOASID Set Private ID (SPID) > + > +SPIDs are introduced as IOASIDs within its set. Each SPID maps to > a +system-wide IOASID but the namespace of SPID is within its > IOASID +set. > >>> > >>> The intro isn't super clear. Perhaps this is simpler: > >>> "Each IOASID set has a private namespace of SPIDs. An SPID maps to a > >>> single system-wide
Re: [PATCH v2 1/9] docs: Document IO Address Space ID (IOASID) APIs
Hi Jacob, On 9/1/20 6:56 PM, Jacob Pan wrote: > Hi Eric, > > On Thu, 27 Aug 2020 18:21:07 +0200 > Auger Eric wrote: > >> Hi Jacob, >> On 8/24/20 12:32 PM, Jean-Philippe Brucker wrote: >>> On Fri, Aug 21, 2020 at 09:35:10PM -0700, Jacob Pan wrote: IOASID is used to identify address spaces that can be targeted by device DMA. It is a system-wide resource that is essential to its many users. This document is an attempt to help developers from all vendors navigate the APIs. At this time, ARM SMMU and Intel’s Scalable IO Virtualization (SIOV) enabled platforms are the primary users of IOASID. Examples of how SIOV components interact with IOASID APIs are provided in that many APIs are driven by the requirements from SIOV. Signed-off-by: Liu Yi L Signed-off-by: Wu Hao Signed-off-by: Jacob Pan --- Documentation/ioasid.rst | 618 +++ 1 file changed, 618 insertions(+) create mode 100644 Documentation/ioasid.rst diff --git a/Documentation/ioasid.rst b/Documentation/ioasid.rst >>> >>> Thanks for writing this up. Should it go to >>> Documentation/driver-api/, or Documentation/driver-api/iommu/? I >>> think this also needs to Cc linux-...@vger.kernel.org and >>> cor...@lwn.net new file mode 100644 index ..b6a8cdc885ff --- /dev/null +++ b/Documentation/ioasid.rst @@ -0,0 +1,618 @@ +.. ioasid: + += +IO Address Space ID += + +IOASID is a generic name for PCIe Process Address ID (PASID) or ARM +SMMU sub-stream ID. An IOASID identifies an address space that DMA >>> >>> "SubstreamID" >> On ARM if we don't use PASIDs we have streamids (SID) which can also >> identify address spaces that DMA requests can target. So maybe this >> definition is not sufficient. >> > According to SMMU spec, the SubstreamID is equivalent to PASID. My > understanding is that SID is equivalent to PCI requester ID that > identifies stage 2. Do you plan to use IOASID for stage 2? No. So actually if PASID is not used we still have a default single IOASID matching the single context. So that may be fine as a definition. > IOASID is mostly for SVA and DMA request w/ PASID. > >>> +requests can target. + +The primary use cases for IOASID are Shared Virtual Address (SVA) and +IO Virtual Address (IOVA). However, the requirements for IOASID >>> >>> IOVA alone isn't a use case, maybe "multiple IOVA spaces per >>> device"? +management can vary among hardware architectures. + +This document covers the generic features supported by IOASID +APIs. Vendor-specific use cases are also illustrated with Intel's VT-d +based platforms as the first example. + +.. contents:: :local: + +Glossary + +PASID - Process Address Space ID + +IOASID - IO Address Space ID (generic term for PCIe PASID and +sub-stream ID in SMMU) >>> >>> "SubstreamID" >>> + +SVA/SVM - Shared Virtual Addressing/Memory + +ENQCMD - New Intel X86 ISA for efficient workqueue submission [1] >>> >>> Maybe drop the "New", to keep the documentation perennial. It might >>> be good to add internal links here to the specifications URLs at >>> the bottom. + +DSA - Intel Data Streaming Accelerator [2] + +VDCM - Virtual device composition module [3] + +SIOV - Intel Scalable IO Virtualization + + +Key Concepts + + +IOASID Set +--- +An IOASID set is a group of IOASIDs allocated from the system-wide +IOASID pool. An IOASID set is created and can be identified by a +token of u64. Refer to IOASID set APIs for more details. >>> >>> Identified either by an u64 or an mm_struct, right? Maybe just >>> drop the second sentence if it's detailed in the IOASID set section >>> below. + +IOASID set is particularly useful for guest SVA where each guest could +have its own IOASID set for security and efficiency reasons. + +IOASID Set Private ID (SPID) + +SPIDs are introduced as IOASIDs within its set. Each SPID maps to a +system-wide IOASID but the namespace of SPID is within its IOASID +set. >>> >>> The intro isn't super clear. Perhaps this is simpler: >>> "Each IOASID set has a private namespace of SPIDs. An SPID maps to a >>> single system-wide IOASID." >> or, "within an ioasid set, each ioasid can be associated with an alias >> ID, named SPID." > I don't have strong opinion, I feel it is good to explain the > relationship between SPID and IOASID in both directions, how about add? > " Conversely, each IOASID is associated with an alias ID, named SPID." yep. I amy suggest: each IOASID may be associated with an alias ID,
Re: [PATCH v2 1/9] docs: Document IO Address Space ID (IOASID) APIs
Hi Eric, On Thu, 27 Aug 2020 18:21:07 +0200 Auger Eric wrote: > Hi Jacob, > On 8/24/20 12:32 PM, Jean-Philippe Brucker wrote: > > On Fri, Aug 21, 2020 at 09:35:10PM -0700, Jacob Pan wrote: > >> IOASID is used to identify address spaces that can be targeted by > >> device DMA. It is a system-wide resource that is essential to its > >> many users. This document is an attempt to help developers from > >> all vendors navigate the APIs. At this time, ARM SMMU and Intel’s > >> Scalable IO Virtualization (SIOV) enabled platforms are the > >> primary users of IOASID. Examples of how SIOV components interact > >> with IOASID APIs are provided in that many APIs are driven by the > >> requirements from SIOV. > >> > >> Signed-off-by: Liu Yi L > >> Signed-off-by: Wu Hao > >> Signed-off-by: Jacob Pan > >> --- > >> Documentation/ioasid.rst | 618 > >> +++ 1 file changed, > >> 618 insertions(+) create mode 100644 Documentation/ioasid.rst > >> > >> diff --git a/Documentation/ioasid.rst b/Documentation/ioasid.rst > > > > Thanks for writing this up. Should it go to > > Documentation/driver-api/, or Documentation/driver-api/iommu/? I > > think this also needs to Cc linux-...@vger.kernel.org and > > cor...@lwn.net > >> new file mode 100644 > >> index ..b6a8cdc885ff > >> --- /dev/null > >> +++ b/Documentation/ioasid.rst > >> @@ -0,0 +1,618 @@ > >> +.. ioasid: > >> + > >> += > >> +IO Address Space ID > >> += > >> + > >> +IOASID is a generic name for PCIe Process Address ID (PASID) or > >> ARM +SMMU sub-stream ID. An IOASID identifies an address space > >> that DMA > > > > "SubstreamID" > On ARM if we don't use PASIDs we have streamids (SID) which can also > identify address spaces that DMA requests can target. So maybe this > definition is not sufficient. > According to SMMU spec, the SubstreamID is equivalent to PASID. My understanding is that SID is equivalent to PCI requester ID that identifies stage 2. Do you plan to use IOASID for stage 2? IOASID is mostly for SVA and DMA request w/ PASID. > > > >> +requests can target. > >> + > >> +The primary use cases for IOASID are Shared Virtual Address (SVA) > >> and +IO Virtual Address (IOVA). However, the requirements for > >> IOASID > > > > IOVA alone isn't a use case, maybe "multiple IOVA spaces per > > device"? > >> +management can vary among hardware architectures. > >> + > >> +This document covers the generic features supported by IOASID > >> +APIs. Vendor-specific use cases are also illustrated with Intel's > >> VT-d +based platforms as the first example. > >> + > >> +.. contents:: :local: > >> + > >> +Glossary > >> + > >> +PASID - Process Address Space ID > >> + > >> +IOASID - IO Address Space ID (generic term for PCIe PASID and > >> +sub-stream ID in SMMU) > > > > "SubstreamID" > > > >> + > >> +SVA/SVM - Shared Virtual Addressing/Memory > >> + > >> +ENQCMD - New Intel X86 ISA for efficient workqueue submission > >> [1] > > > > Maybe drop the "New", to keep the documentation perennial. It might > > be good to add internal links here to the specifications URLs at > > the bottom. > >> + > >> +DSA - Intel Data Streaming Accelerator [2] > >> + > >> +VDCM - Virtual device composition module [3] > >> + > >> +SIOV - Intel Scalable IO Virtualization > >> + > >> + > >> +Key Concepts > >> + > >> + > >> +IOASID Set > >> +--- > >> +An IOASID set is a group of IOASIDs allocated from the system-wide > >> +IOASID pool. An IOASID set is created and can be identified by a > >> +token of u64. Refer to IOASID set APIs for more details. > > > > Identified either by an u64 or an mm_struct, right? Maybe just > > drop the second sentence if it's detailed in the IOASID set section > > below. > >> + > >> +IOASID set is particularly useful for guest SVA where each guest > >> could +have its own IOASID set for security and efficiency reasons. > >> + > >> +IOASID Set Private ID (SPID) > >> + > >> +SPIDs are introduced as IOASIDs within its set. Each SPID maps to > >> a +system-wide IOASID but the namespace of SPID is within its > >> IOASID +set. > > > > The intro isn't super clear. Perhaps this is simpler: > > "Each IOASID set has a private namespace of SPIDs. An SPID maps to a > > single system-wide IOASID." > or, "within an ioasid set, each ioasid can be associated with an alias > ID, named SPID." I don't have strong opinion, I feel it is good to explain the relationship between SPID and IOASID in both directions, how about add? " Conversely, each IOASID is associated with an alias ID, named SPID." > > > >> SPIDs can be used as guest IOASIDs where each guest could do > >> +IOASID allocation from its own pool and map them to host physical > >> +IOASIDs. SPIDs are particularly useful for supporting live > >> migration +where decoupling guest and host physical resources are
Re: [PATCH v2 1/9] docs: Document IO Address Space ID (IOASID) APIs
Hi Jean, Thanks for the review! On Mon, 24 Aug 2020 12:32:39 +0200 Jean-Philippe Brucker wrote: > On Fri, Aug 21, 2020 at 09:35:10PM -0700, Jacob Pan wrote: > > IOASID is used to identify address spaces that can be targeted by > > device DMA. It is a system-wide resource that is essential to its > > many users. This document is an attempt to help developers from all > > vendors navigate the APIs. At this time, ARM SMMU and Intel’s > > Scalable IO Virtualization (SIOV) enabled platforms are the primary > > users of IOASID. Examples of how SIOV components interact with > > IOASID APIs are provided in that many APIs are driven by the > > requirements from SIOV. > > > > Signed-off-by: Liu Yi L > > Signed-off-by: Wu Hao > > Signed-off-by: Jacob Pan > > --- > > Documentation/ioasid.rst | 618 > > +++ 1 file changed, 618 > > insertions(+) create mode 100644 Documentation/ioasid.rst > > > > diff --git a/Documentation/ioasid.rst b/Documentation/ioasid.rst > > Thanks for writing this up. Should it go to > Documentation/driver-api/, or Documentation/driver-api/iommu/? I > think this also needs to Cc linux-...@vger.kernel.org and > cor...@lwn.net > Good point, I think Documentation/driver-api/ is good for now as there are no other IOMMU docs. Will CC Jon also. > > new file mode 100644 > > index ..b6a8cdc885ff > > --- /dev/null > > +++ b/Documentation/ioasid.rst > > @@ -0,0 +1,618 @@ > > +.. ioasid: > > + > > += > > +IO Address Space ID > > += > > + > > +IOASID is a generic name for PCIe Process Address ID (PASID) or ARM > > +SMMU sub-stream ID. An IOASID identifies an address space that > > DMA > > "SubstreamID" > > > +requests can target. > > + > > +The primary use cases for IOASID are Shared Virtual Address (SVA) > > and +IO Virtual Address (IOVA). However, the requirements for > > IOASID > > IOVA alone isn't a use case, maybe "multiple IOVA spaces per device"? > Yes, I meant guest IOVA for mdev which has "multiple IOVA spaces per device" based on aux domain. I will add this to the IOVA case description. "The primary use cases for IOASID are Shared Virtual Address (SVA) and multiple IOVA spaces per device. However, the requirements for IOASID management can vary among hardware architectures. For baremetal IOVA, IOASID #0 is used for DMA request without PASID. Even though some architectures such as VT-d also offers the flexibility of using any PASIDs for DMA request without PASID. PASID #0 is reserved and not allocated from any ioasid_set. Multiple IOVA spaces per device are mapped to auxiliary domains which can be used for mediated device assignment with and without a virtual IOMMU (vIOMMU). An IOASID is allocated for each auxiliary domain as default PASID. Without vIOMMU, default IOASID is used for DMA map/unmap APIs. With vIOMMU, default IOASID is used for guest IOVA where DMA request with PASID is required for the device. The reason is that there is only one PASID #0 per device, e.g. VT-d, RID_PASID is per PCI device. " > > +management can vary among hardware architectures. > > + > > +This document covers the generic features supported by IOASID > > +APIs. Vendor-specific use cases are also illustrated with Intel's > > VT-d +based platforms as the first example. > > + > > +.. contents:: :local: > > + > > +Glossary > > + > > +PASID - Process Address Space ID > > + > > +IOASID - IO Address Space ID (generic term for PCIe PASID and > > +sub-stream ID in SMMU) > > "SubstreamID" > will fix. > > + > > +SVA/SVM - Shared Virtual Addressing/Memory > > + > > +ENQCMD - New Intel X86 ISA for efficient workqueue submission [1] > > Maybe drop the "New", to keep the documentation perennial. It might be > good to add internal links here to the specifications URLs at the > bottom. > Good idea > > + > > +DSA - Intel Data Streaming Accelerator [2] > > + > > +VDCM - Virtual device composition module [3] > > + > > +SIOV - Intel Scalable IO Virtualization > > + > > + > > +Key Concepts > > + > > + > > +IOASID Set > > +--- > > +An IOASID set is a group of IOASIDs allocated from the system-wide > > +IOASID pool. An IOASID set is created and can be identified by a > > +token of u64. Refer to IOASID set APIs for more details. > > Identified either by an u64 or an mm_struct, right? Maybe just drop > the second sentence if it's detailed in the IOASID set section below. > Sounds good. > > + > > +IOASID set is particularly useful for guest SVA where each guest > > could +have its own IOASID set for security and efficiency reasons. > > + > > +IOASID Set Private ID (SPID) > > + > > +SPIDs are introduced as IOASIDs within its set. Each SPID maps to a > > +system-wide IOASID but the namespace of SPID is within its IOASID > > +set. > > The intro isn't super clear. Perhaps this is simpler: > "Each IOASID set has a private
Re: [PATCH v2 1/9] docs: Document IO Address Space ID (IOASID) APIs
Hi Baolu, Thanks for the review! On Sun, 23 Aug 2020 15:05:08 +0800 Lu Baolu wrote: > Hi Jacob, > > On 2020/8/22 12:35, Jacob Pan wrote: > > IOASID is used to identify address spaces that can be targeted by > > device DMA. It is a system-wide resource that is essential to its > > many users. This document is an attempt to help developers from all > > vendors navigate the APIs. At this time, ARM SMMU and Intel’s > > Scalable IO Virtualization (SIOV) enabled platforms are the primary > > users of IOASID. Examples of how SIOV components interact with > > IOASID APIs are provided in that many APIs are driven by the > > requirements from SIOV. > > > > Signed-off-by: Liu Yi L > > Signed-off-by: Wu Hao > > Signed-off-by: Jacob Pan > > --- > > Documentation/ioasid.rst | 618 > > +++ 1 file changed, 618 > > insertions(+) create mode 100644 Documentation/ioasid.rst > > > > diff --git a/Documentation/ioasid.rst b/Documentation/ioasid.rst > > new file mode 100644 > > index ..b6a8cdc885ff > > --- /dev/null > > +++ b/Documentation/ioasid.rst > > @@ -0,0 +1,618 @@ > > +.. ioasid: > > + > > += > > +IO Address Space ID > > += > > + > > +IOASID is a generic name for PCIe Process Address ID (PASID) or ARM > > +SMMU sub-stream ID. An IOASID identifies an address space that DMA > > +requests can target. > > + > > +The primary use cases for IOASID are Shared Virtual Address (SVA) > > and +IO Virtual Address (IOVA). However, the requirements for > > IOASID > > Can you please elaborate a bit more about how ioasid is used by IOVA? > Good point, I will add a paragraph for IOVA usage. Something like this: "For IOVA, IOASID #0 is typically used for DMA request without PASID. However, some architectures such as VT-d also offers the flexibility of using any PASID for DMA request without PASID. For example, on VT-d PASID #0 is used for PCI device RID2PASID and for SIOV each auxilary domain also allocates a non-zero default PASID for DMA request w/o PASID. PASID #0, is reserved and not allocated from any ioasid_set." > > +management can vary among hardware architectures. > > + > > +This document covers the generic features supported by IOASID > > +APIs. Vendor-specific use cases are also illustrated with Intel's > > VT-d +based platforms as the first example. > > + > > +.. contents:: :local: > > + > > +Glossary > > + > > +PASID - Process Address Space ID > > + > > +IOASID - IO Address Space ID (generic term for PCIe PASID and > > +sub-stream ID in SMMU) > > + > > +SVA/SVM - Shared Virtual Addressing/Memory > > + > > +ENQCMD - New Intel X86 ISA for efficient workqueue submission [1] > > + > > +DSA - Intel Data Streaming Accelerator [2] > > + > > +VDCM - Virtual device composition module [3] > > Capitalize the first letter of each word. > will do. > > + > > +SIOV - Intel Scalable IO Virtualization > > + > > + > > +Key Concepts > > + > > + > > +IOASID Set > > +--- > > +An IOASID set is a group of IOASIDs allocated from the system-wide > > +IOASID pool. An IOASID set is created and can be identified by a > > +token of u64. Refer to IOASID set APIs for more details. > > + > > +IOASID set is particularly useful for guest SVA where each guest > > could +have its own IOASID set for security and efficiency reasons. > > + > > +IOASID Set Private ID (SPID) > > + > > +SPIDs are introduced as IOASIDs within its set. Each SPID maps to a > > +system-wide IOASID but the namespace of SPID is within its IOASID > > +set. SPIDs can be used as guest IOASIDs where each guest could do > > +IOASID allocation from its own pool and map them to host physical > > +IOASIDs. SPIDs are particularly useful for supporting live > > migration +where decoupling guest and host physical resources are > > necessary. + > > +For example, two VMs can both allocate guest PASID/SPID #101 but > > map to +different host PASIDs #201 and #202 respectively as shown > > in the +diagram below. > > +:: > > + > > + .--..--. > > + | VM 1 || VM 2 | > > + | || | > > + |--||--| > > + | GPASID/SPID 101 || GPASID/SPID 101 | > > + '--'---' Guest > > + __|__|__ > > + | | Host > > + v v > > + .--..--. > > + | Host IOASID 201 || Host IOASID 202 | > > + '--''--' > > + | IOASID set 1 || IOASID set 2 | > > + '--''--' > > + > > +Guest PASID is treated as IOASID set private ID (SPID) within an > > +IOASID set, mappings between guest and host IOASIDs are stored in > > the +set
Re: [PATCH v2 1/9] docs: Document IO Address Space ID (IOASID) APIs
Hi Jacob, On 8/24/20 12:32 PM, Jean-Philippe Brucker wrote: > On Fri, Aug 21, 2020 at 09:35:10PM -0700, Jacob Pan wrote: >> IOASID is used to identify address spaces that can be targeted by device >> DMA. It is a system-wide resource that is essential to its many users. >> This document is an attempt to help developers from all vendors navigate >> the APIs. At this time, ARM SMMU and Intel’s Scalable IO Virtualization >> (SIOV) enabled platforms are the primary users of IOASID. Examples of >> how SIOV components interact with IOASID APIs are provided in that many >> APIs are driven by the requirements from SIOV. >> >> Signed-off-by: Liu Yi L >> Signed-off-by: Wu Hao >> Signed-off-by: Jacob Pan >> --- >> Documentation/ioasid.rst | 618 >> +++ >> 1 file changed, 618 insertions(+) >> create mode 100644 Documentation/ioasid.rst >> >> diff --git a/Documentation/ioasid.rst b/Documentation/ioasid.rst > > Thanks for writing this up. Should it go to Documentation/driver-api/, or > Documentation/driver-api/iommu/? I think this also needs to Cc > linux-...@vger.kernel.org and cor...@lwn.net > >> new file mode 100644 >> index ..b6a8cdc885ff >> --- /dev/null >> +++ b/Documentation/ioasid.rst >> @@ -0,0 +1,618 @@ >> +.. ioasid: >> + >> += >> +IO Address Space ID >> += >> + >> +IOASID is a generic name for PCIe Process Address ID (PASID) or ARM >> +SMMU sub-stream ID. An IOASID identifies an address space that DMA > > "SubstreamID" On ARM if we don't use PASIDs we have streamids (SID) which can also identify address spaces that DMA requests can target. So maybe this definition is not sufficient. > >> +requests can target. >> + >> +The primary use cases for IOASID are Shared Virtual Address (SVA) and >> +IO Virtual Address (IOVA). However, the requirements for IOASID > > IOVA alone isn't a use case, maybe "multiple IOVA spaces per device"? > >> +management can vary among hardware architectures. >> + >> +This document covers the generic features supported by IOASID >> +APIs. Vendor-specific use cases are also illustrated with Intel's VT-d >> +based platforms as the first example. >> + >> +.. contents:: :local: >> + >> +Glossary >> + >> +PASID - Process Address Space ID >> + >> +IOASID - IO Address Space ID (generic term for PCIe PASID and >> +sub-stream ID in SMMU) > > "SubstreamID" > >> + >> +SVA/SVM - Shared Virtual Addressing/Memory >> + >> +ENQCMD - New Intel X86 ISA for efficient workqueue submission [1] > > Maybe drop the "New", to keep the documentation perennial. It might be > good to add internal links here to the specifications URLs at the bottom. > >> + >> +DSA - Intel Data Streaming Accelerator [2] >> + >> +VDCM - Virtual device composition module [3] >> + >> +SIOV - Intel Scalable IO Virtualization >> + >> + >> +Key Concepts >> + >> + >> +IOASID Set >> +--- >> +An IOASID set is a group of IOASIDs allocated from the system-wide >> +IOASID pool. An IOASID set is created and can be identified by a >> +token of u64. Refer to IOASID set APIs for more details. > > Identified either by an u64 or an mm_struct, right? Maybe just drop the > second sentence if it's detailed in the IOASID set section below. > >> + >> +IOASID set is particularly useful for guest SVA where each guest could >> +have its own IOASID set for security and efficiency reasons. >> + >> +IOASID Set Private ID (SPID) >> + >> +SPIDs are introduced as IOASIDs within its set. Each SPID maps to a >> +system-wide IOASID but the namespace of SPID is within its IOASID >> +set. > > The intro isn't super clear. Perhaps this is simpler: > "Each IOASID set has a private namespace of SPIDs. An SPID maps to a > single system-wide IOASID." or, "within an ioasid set, each ioasid can be associated with an alias ID, named SPID." > >> SPIDs can be used as guest IOASIDs where each guest could do >> +IOASID allocation from its own pool and map them to host physical >> +IOASIDs. SPIDs are particularly useful for supporting live migration >> +where decoupling guest and host physical resources are necessary. >> + >> +For example, two VMs can both allocate guest PASID/SPID #101 but map to >> +different host PASIDs #201 and #202 respectively as shown in the >> +diagram below. >> +:: >> + >> + .--..--. >> + | VM 1 || VM 2 | >> + | || | >> + |--||--| >> + | GPASID/SPID 101 || GPASID/SPID 101 | >> + '--'---' Guest >> + __|__|__ >> + | | Host >> + v v >> + .--..--. >> + | Host IOASID 201 || Host IOASID 202 | >> +
Re: [PATCH v2 1/9] docs: Document IO Address Space ID (IOASID) APIs
On Fri, Aug 21, 2020 at 09:35:10PM -0700, Jacob Pan wrote: > IOASID is used to identify address spaces that can be targeted by device > DMA. It is a system-wide resource that is essential to its many users. > This document is an attempt to help developers from all vendors navigate > the APIs. At this time, ARM SMMU and Intel’s Scalable IO Virtualization > (SIOV) enabled platforms are the primary users of IOASID. Examples of > how SIOV components interact with IOASID APIs are provided in that many > APIs are driven by the requirements from SIOV. > > Signed-off-by: Liu Yi L > Signed-off-by: Wu Hao > Signed-off-by: Jacob Pan > --- > Documentation/ioasid.rst | 618 > +++ > 1 file changed, 618 insertions(+) > create mode 100644 Documentation/ioasid.rst > > diff --git a/Documentation/ioasid.rst b/Documentation/ioasid.rst Thanks for writing this up. Should it go to Documentation/driver-api/, or Documentation/driver-api/iommu/? I think this also needs to Cc linux-...@vger.kernel.org and cor...@lwn.net > new file mode 100644 > index ..b6a8cdc885ff > --- /dev/null > +++ b/Documentation/ioasid.rst > @@ -0,0 +1,618 @@ > +.. ioasid: > + > += > +IO Address Space ID > += > + > +IOASID is a generic name for PCIe Process Address ID (PASID) or ARM > +SMMU sub-stream ID. An IOASID identifies an address space that DMA "SubstreamID" > +requests can target. > + > +The primary use cases for IOASID are Shared Virtual Address (SVA) and > +IO Virtual Address (IOVA). However, the requirements for IOASID IOVA alone isn't a use case, maybe "multiple IOVA spaces per device"? > +management can vary among hardware architectures. > + > +This document covers the generic features supported by IOASID > +APIs. Vendor-specific use cases are also illustrated with Intel's VT-d > +based platforms as the first example. > + > +.. contents:: :local: > + > +Glossary > + > +PASID - Process Address Space ID > + > +IOASID - IO Address Space ID (generic term for PCIe PASID and > +sub-stream ID in SMMU) "SubstreamID" > + > +SVA/SVM - Shared Virtual Addressing/Memory > + > +ENQCMD - New Intel X86 ISA for efficient workqueue submission [1] Maybe drop the "New", to keep the documentation perennial. It might be good to add internal links here to the specifications URLs at the bottom. > + > +DSA - Intel Data Streaming Accelerator [2] > + > +VDCM - Virtual device composition module [3] > + > +SIOV - Intel Scalable IO Virtualization > + > + > +Key Concepts > + > + > +IOASID Set > +--- > +An IOASID set is a group of IOASIDs allocated from the system-wide > +IOASID pool. An IOASID set is created and can be identified by a > +token of u64. Refer to IOASID set APIs for more details. Identified either by an u64 or an mm_struct, right? Maybe just drop the second sentence if it's detailed in the IOASID set section below. > + > +IOASID set is particularly useful for guest SVA where each guest could > +have its own IOASID set for security and efficiency reasons. > + > +IOASID Set Private ID (SPID) > + > +SPIDs are introduced as IOASIDs within its set. Each SPID maps to a > +system-wide IOASID but the namespace of SPID is within its IOASID > +set. The intro isn't super clear. Perhaps this is simpler: "Each IOASID set has a private namespace of SPIDs. An SPID maps to a single system-wide IOASID." > SPIDs can be used as guest IOASIDs where each guest could do > +IOASID allocation from its own pool and map them to host physical > +IOASIDs. SPIDs are particularly useful for supporting live migration > +where decoupling guest and host physical resources are necessary. > + > +For example, two VMs can both allocate guest PASID/SPID #101 but map to > +different host PASIDs #201 and #202 respectively as shown in the > +diagram below. > +:: > + > + .--..--. > + | VM 1 || VM 2 | > + | || | > + |--||--| > + | GPASID/SPID 101 || GPASID/SPID 101 | > + '--'---' Guest > + __|__|__ > + | | Host > + v v > + .--..--. > + | Host IOASID 201 || Host IOASID 202 | > + '--''--' > + | IOASID set 1 || IOASID set 2 | > + '--''--' > + > +Guest PASID is treated as IOASID set private ID (SPID) within an > +IOASID set, mappings between guest and host IOASIDs are stored in the > +set for inquiry. > + > +IOASID APIs > +=== > +To get the IOASID APIs, users must #include . These APIs > +serve the following functionalities: > + > + - IOASID allocation/Free > + - Group
Re: [PATCH v2 1/9] docs: Document IO Address Space ID (IOASID) APIs
Hi Jacob, On 2020/8/22 12:35, Jacob Pan wrote: IOASID is used to identify address spaces that can be targeted by device DMA. It is a system-wide resource that is essential to its many users. This document is an attempt to help developers from all vendors navigate the APIs. At this time, ARM SMMU and Intel’s Scalable IO Virtualization (SIOV) enabled platforms are the primary users of IOASID. Examples of how SIOV components interact with IOASID APIs are provided in that many APIs are driven by the requirements from SIOV. Signed-off-by: Liu Yi L Signed-off-by: Wu Hao Signed-off-by: Jacob Pan --- Documentation/ioasid.rst | 618 +++ 1 file changed, 618 insertions(+) create mode 100644 Documentation/ioasid.rst diff --git a/Documentation/ioasid.rst b/Documentation/ioasid.rst new file mode 100644 index ..b6a8cdc885ff --- /dev/null +++ b/Documentation/ioasid.rst @@ -0,0 +1,618 @@ +.. ioasid: + += +IO Address Space ID += + +IOASID is a generic name for PCIe Process Address ID (PASID) or ARM +SMMU sub-stream ID. An IOASID identifies an address space that DMA +requests can target. + +The primary use cases for IOASID are Shared Virtual Address (SVA) and +IO Virtual Address (IOVA). However, the requirements for IOASID Can you please elaborate a bit more about how ioasid is used by IOVA? +management can vary among hardware architectures. + +This document covers the generic features supported by IOASID +APIs. Vendor-specific use cases are also illustrated with Intel's VT-d +based platforms as the first example. + +.. contents:: :local: + +Glossary + +PASID - Process Address Space ID + +IOASID - IO Address Space ID (generic term for PCIe PASID and +sub-stream ID in SMMU) + +SVA/SVM - Shared Virtual Addressing/Memory + +ENQCMD - New Intel X86 ISA for efficient workqueue submission [1] + +DSA - Intel Data Streaming Accelerator [2] + +VDCM - Virtual device composition module [3] Capitalize the first letter of each word. + +SIOV - Intel Scalable IO Virtualization + + +Key Concepts + + +IOASID Set +--- +An IOASID set is a group of IOASIDs allocated from the system-wide +IOASID pool. An IOASID set is created and can be identified by a +token of u64. Refer to IOASID set APIs for more details. + +IOASID set is particularly useful for guest SVA where each guest could +have its own IOASID set for security and efficiency reasons. + +IOASID Set Private ID (SPID) + +SPIDs are introduced as IOASIDs within its set. Each SPID maps to a +system-wide IOASID but the namespace of SPID is within its IOASID +set. SPIDs can be used as guest IOASIDs where each guest could do +IOASID allocation from its own pool and map them to host physical +IOASIDs. SPIDs are particularly useful for supporting live migration +where decoupling guest and host physical resources are necessary. + +For example, two VMs can both allocate guest PASID/SPID #101 but map to +different host PASIDs #201 and #202 respectively as shown in the +diagram below. +:: + + .--..--. + | VM 1 || VM 2 | + | || | + |--||--| + | GPASID/SPID 101 || GPASID/SPID 101 | + '--'---' Guest + __|__|__ + | | Host + v v + .--..--. + | Host IOASID 201 || Host IOASID 202 | + '--''--' + | IOASID set 1 || IOASID set 2 | + '--''--' + +Guest PASID is treated as IOASID set private ID (SPID) within an +IOASID set, mappings between guest and host IOASIDs are stored in the +set for inquiry. Is there a real IOASID set allocated in the host which represent the SPID? + +IOASID APIs +=== +To get the IOASID APIs, users must #include . These APIs +serve the following functionalities: + + - IOASID allocation/Free + - Group management in the form of ioasid_set + - Private data storage and lookup + - Reference counting + - Event notification in case of state change + +IOASID Set Level APIs +-- +For use cases such as guest SVA it is necessary to manage IOASIDs at +a group level. For example, VMs may allocate multiple IOASIDs for +guest process address sharing (vSVA). It is imperative to enforce +VM-IOASID ownership such that malicious guest cannot target DMA +traffic outside its own IOASIDs, or free an active IOASID belong to +another VM. +:: + + struct ioasid_set *ioasid_alloc_set(void *token, ioasid_t quota, u32 type) + + int ioasid_adjust_set(struct ioasid_set *set, int quota); + + void ioasid_set_get(struct ioasid_set *set) + + void
