diff mbox series

docs: iommu: Remove outdated Documentation/userspace-api/iommu.rst

Message ID 20240702120617.26882-1-mark-pk.tsai@mediatek.com (mailing list archive)
State New
Headers show
Series docs: iommu: Remove outdated Documentation/userspace-api/iommu.rst | expand

Commit Message

Mark-PK Tsai July 2, 2024, 12:05 p.m. UTC 
The Documentation/userspace-api/iommu.rst file has become outdated due
to the removal of associated structures and APIs.

Specifically, struct such as iommu_cache_invalidate_info and guest
pasid related uapi were removed in commit 0c9f17877891 ("iommu:
Remove guest pasid related interfaces and definitions").
And the corresponding uapi/linux/iommu.h file was removed in
commit 00a9bc607043 ("iommu: Move iommu fault data to
linux/iommu.h").

Signed-off-by: Mark-PK Tsai <mark-pk.tsai@mediatek.com>
---
 Documentation/userspace-api/iommu.rst | 209 --------------------------
 MAINTAINERS                           |   1 -
 2 files changed, 210 deletions(-)
 delete mode 100644 Documentation/userspace-api/iommu.rst

Comments

Zenghui Yu July 2, 2024, 3:11 p.m. UTC | #1 
[ +Cc IOMMU maintainers and list ]

On 2024/7/2 20:05, Mark-PK Tsai wrote:
> The Documentation/userspace-api/iommu.rst file has become outdated due
> to the removal of associated structures and APIs.
> 
> Specifically, struct such as iommu_cache_invalidate_info and guest
> pasid related uapi were removed in commit 0c9f17877891 ("iommu:
> Remove guest pasid related interfaces and definitions").
> And the corresponding uapi/linux/iommu.h file was removed in
> commit 00a9bc607043 ("iommu: Move iommu fault data to
> linux/iommu.h").
> 
> Signed-off-by: Mark-PK Tsai <mark-pk.tsai@mediatek.com>
> ---
>  Documentation/userspace-api/iommu.rst | 209 --------------------------
>  MAINTAINERS                           |   1 -
>  2 files changed, 210 deletions(-)
>  delete mode 100644 Documentation/userspace-api/iommu.rst
> 
> diff --git a/Documentation/userspace-api/iommu.rst b/Documentation/userspace-api/iommu.rst
> deleted file mode 100644
> index d3108c1519d5..000000000000
> --- a/Documentation/userspace-api/iommu.rst
> +++ /dev/null
> @@ -1,209 +0,0 @@
> -.. SPDX-License-Identifier: GPL-2.0
> -.. iommu:
> -
> -=====================================
> -IOMMU Userspace API
> -=====================================
> -
> -IOMMU UAPI is used for virtualization cases where communications are
> -needed between physical and virtual IOMMU drivers. For baremetal
> -usage, the IOMMU is a system device which does not need to communicate
> -with userspace directly.
> -
> -The primary use cases are guest Shared Virtual Address (SVA) and
> -guest IO virtual address (IOVA), wherein the vIOMMU implementation
> -relies on the physical IOMMU and for this reason requires interactions
> -with the host driver.
> -
> -.. contents:: :local:
> -
> -Functionalities
> -===============
> -Communications of user and kernel involve both directions. The
> -supported user-kernel APIs are as follows:
> -
> -1. Bind/Unbind guest PASID (e.g. Intel VT-d)
> -2. Bind/Unbind guest PASID table (e.g. ARM SMMU)
> -3. Invalidate IOMMU caches upon guest requests
> -4. Report errors to the guest and serve page requests
> -
> -Requirements
> -============
> -The IOMMU UAPIs are generic and extensible to meet the following
> -requirements:
> -
> -1. Emulated and para-virtualised vIOMMUs
> -2. Multiple vendors (Intel VT-d, ARM SMMU, etc.)
> -3. Extensions to the UAPI shall not break existing userspace
> -
> -Interfaces
> -==========
> -Although the data structures defined in IOMMU UAPI are self-contained,
> -there are no user API functions introduced. Instead, IOMMU UAPI is
> -designed to work with existing user driver frameworks such as VFIO.
> -
> -Extension Rules & Precautions
> ------------------------------
> -When IOMMU UAPI gets extended, the data structures can *only* be
> -modified in two ways:
> -
> -1. Adding new fields by re-purposing the padding[] field. No size change.
> -2. Adding new union members at the end. May increase the structure sizes.
> -
> -No new fields can be added *after* the variable sized union in that it
> -will break backward compatibility when offset moves. A new flag must
> -be introduced whenever a change affects the structure using either
> -method. The IOMMU driver processes the data based on flags which
> -ensures backward compatibility.
> -
> -Version field is only reserved for the unlikely event of UAPI upgrade
> -at its entirety.
> -
> -It's *always* the caller's responsibility to indicate the size of the
> -structure passed by setting argsz appropriately.
> -Though at the same time, argsz is user provided data which is not
> -trusted. The argsz field allows the user app to indicate how much data
> -it is providing; it's still the kernel's responsibility to validate
> -whether it's correct and sufficient for the requested operation.
> -
> -Compatibility Checking
> -----------------------
> -When IOMMU UAPI extension results in some structure size increase,
> -IOMMU UAPI code shall handle the following cases:
> -
> -1. User and kernel has exact size match
> -2. An older user with older kernel header (smaller UAPI size) running on a
> -   newer kernel (larger UAPI size)
> -3. A newer user with newer kernel header (larger UAPI size) running
> -   on an older kernel.
> -4. A malicious/misbehaving user passing illegal/invalid size but within
> -   range. The data may contain garbage.
> -
> -Feature Checking
> -----------------
> -While launching a guest with vIOMMU, it is strongly advised to check
> -the compatibility upfront, as some subsequent errors happening during
> -vIOMMU operation, such as cache invalidation failures cannot be nicely
> -escalated to the guest due to IOMMU specifications. This can lead to
> -catastrophic failures for the users.
> -
> -User applications such as QEMU are expected to import kernel UAPI
> -headers. Backward compatibility is supported per feature flags.
> -For example, an older QEMU (with older kernel header) can run on newer
> -kernel. Newer QEMU (with new kernel header) may refuse to initialize
> -on an older kernel if new feature flags are not supported by older
> -kernel. Simply recompiling existing code with newer kernel header should
> -not be an issue in that only existing flags are used.
> -
> -IOMMU vendor driver should report the below features to IOMMU UAPI
> -consumers (e.g. via VFIO).
> -
> -1. IOMMU_NESTING_FEAT_SYSWIDE_PASID
> -2. IOMMU_NESTING_FEAT_BIND_PGTBL
> -3. IOMMU_NESTING_FEAT_BIND_PASID_TABLE
> -4. IOMMU_NESTING_FEAT_CACHE_INVLD
> -5. IOMMU_NESTING_FEAT_PAGE_REQUEST
> -
> -Take VFIO as example, upon request from VFIO userspace (e.g. QEMU),
> -VFIO kernel code shall query IOMMU vendor driver for the support of
> -the above features. Query result can then be reported back to the
> -userspace caller. Details can be found in
> -Documentation/driver-api/vfio.rst.
> -
> -
> -Data Passing Example with VFIO
> -------------------------------
> -As the ubiquitous userspace driver framework, VFIO is already IOMMU
> -aware and shares many key concepts such as device model, group, and
> -protection domain. Other user driver frameworks can also be extended
> -to support IOMMU UAPI but it is outside the scope of this document.
> -
> -In this tight-knit VFIO-IOMMU interface, the ultimate consumer of the
> -IOMMU UAPI data is the host IOMMU driver. VFIO facilitates user-kernel
> -transport, capability checking, security, and life cycle management of
> -process address space ID (PASID).
> -
> -VFIO layer conveys the data structures down to the IOMMU driver. It
> -follows the pattern below::
> -
> -   struct {
> -	__u32 argsz;
> -	__u32 flags;
> -	__u8  data[];
> -   };
> -
> -Here data[] contains the IOMMU UAPI data structures. VFIO has the
> -freedom to bundle the data as well as parse data size based on its own flags.
> -
> -In order to determine the size and feature set of the user data, argsz
> -and flags (or the equivalent) are also embedded in the IOMMU UAPI data
> -structures.
> -
> -A "__u32 argsz" field is *always* at the beginning of each structure.
> -
> -For example:
> -::
> -
> -   struct iommu_cache_invalidate_info {
> -	__u32	argsz;
> -	#define IOMMU_CACHE_INVALIDATE_INFO_VERSION_1 1
> -	__u32	version;
> -	/* IOMMU paging structure cache */
> -	#define IOMMU_CACHE_INV_TYPE_IOTLB	(1 << 0) /* IOMMU IOTLB */
> -	#define IOMMU_CACHE_INV_TYPE_DEV_IOTLB	(1 << 1) /* Device IOTLB */
> -	#define IOMMU_CACHE_INV_TYPE_PASID	(1 << 2) /* PASID cache */
> -	#define IOMMU_CACHE_INV_TYPE_NR		(3)
> -	__u8	cache;
> -	__u8	granularity;
> -	__u8	padding[6];
> -	union {
> -		struct iommu_inv_pasid_info pasid_info;
> -		struct iommu_inv_addr_info addr_info;
> -	} granu;
> -   };
> -
> -VFIO is responsible for checking its own argsz and flags. It then
> -invokes appropriate IOMMU UAPI functions. The user pointers are passed
> -to the IOMMU layer for further processing. The responsibilities are
> -divided as follows:
> -
> -- Generic IOMMU layer checks argsz range based on UAPI data in the
> -  current kernel version.
> -
> -- Generic IOMMU layer checks content of the UAPI data for non-zero
> -  reserved bits in flags, padding fields, and unsupported version.
> -  This is to ensure not breaking userspace in the future when these
> -  fields or flags are used.
> -
> -- Vendor IOMMU driver checks argsz based on vendor flags. UAPI data
> -  is consumed based on flags. Vendor driver has access to
> -  unadulterated argsz value in case of vendor specific future
> -  extensions. Currently, it does not perform the copy_from_user()
> -  itself. A __user pointer can be provided in some future scenarios
> -  where there's vendor data outside of the structure definition.
> -
> -IOMMU code treats UAPI data in two categories:
> -
> -- structure contains vendor data
> -  (Example: iommu_uapi_cache_invalidate())
> -
> -- structure contains only generic data
> -  (Example: iommu_uapi_sva_bind_gpasid())
> -
> -
> -
> -Sharing UAPI with in-kernel users
> ----------------------------------
> -For UAPIs that are shared with in-kernel users, a wrapper function is
> -provided to distinguish the callers. For example,
> -
> -Userspace caller ::
> -
> -  int iommu_uapi_sva_unbind_gpasid(struct iommu_domain *domain,
> -                                   struct device *dev,
> -                                   void __user *udata)
> -
> -In-kernel caller ::
> -
> -  int iommu_sva_unbind_gpasid(struct iommu_domain *domain,
> -                              struct device *dev, ioasid_t ioasid);
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 0748d6bd0c4f..1359ed17337e 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -11544,7 +11544,6 @@ L:	iommu@lists.linux.dev
>  S:	Maintained
>  T:	git git://git.kernel.org/pub/scm/linux/kernel/git/joro/iommu.git
>  F:	Documentation/devicetree/bindings/iommu/
> -F:	Documentation/userspace-api/iommu.rst
>  F:	drivers/iommu/
>  F:	include/linux/iommu.h
>  F:	include/linux/iova.h
Baolu Lu July 3, 2024, 2:14 a.m. UTC | #2 
On 7/2/24 8:05 PM, Mark-PK Tsai wrote:
> The Documentation/userspace-api/iommu.rst file has become outdated due
> to the removal of associated structures and APIs.
> 
> Specifically, struct such as iommu_cache_invalidate_info and guest
> pasid related uapi were removed in commit 0c9f17877891 ("iommu:
> Remove guest pasid related interfaces and definitions").
> And the corresponding uapi/linux/iommu.h file was removed in
> commit 00a9bc607043 ("iommu: Move iommu fault data to
> linux/iommu.h").
> 
> Signed-off-by: Mark-PK Tsai<mark-pk.tsai@mediatek.com>
> ---
>   Documentation/userspace-api/iommu.rst | 209 --------------------------
>   MAINTAINERS                           |   1 -
>   2 files changed, 210 deletions(-)
>   delete mode 100644 Documentation/userspace-api/iommu.rst

Reviewed-by: Lu Baolu <baolu.lu@linux.intel.com>

Thanks,
baolu
Will Deacon July 4, 2024, 2:18 p.m. UTC | #3 
On Tue, 02 Jul 2024 20:05:39 +0800, Mark-PK Tsai wrote:
> The Documentation/userspace-api/iommu.rst file has become outdated due
> to the removal of associated structures and APIs.
> 
> Specifically, struct such as iommu_cache_invalidate_info and guest
> pasid related uapi were removed in commit 0c9f17877891 ("iommu:
> Remove guest pasid related interfaces and definitions").
> And the corresponding uapi/linux/iommu.h file was removed in
> commit 00a9bc607043 ("iommu: Move iommu fault data to
> linux/iommu.h").
> 
> [...]

Applied to iommu (core), thanks!

[1/1] docs: iommu: Remove outdated Documentation/userspace-api/iommu.rst
      https://git.kernel.org/iommu/c/d926e7c04843

Cheers,
diff mbox series

Patch

diff --git a/Documentation/userspace-api/iommu.rst b/Documentation/userspace-api/iommu.rst
deleted file mode 100644
index d3108c1519d5..000000000000
--- a/Documentation/userspace-api/iommu.rst
+++ /dev/null
@@ -1,209 +0,0 @@ 
-.. SPDX-License-Identifier: GPL-2.0
-.. iommu:
-
-=====================================
-IOMMU Userspace API
-=====================================
-
-IOMMU UAPI is used for virtualization cases where communications are
-needed between physical and virtual IOMMU drivers. For baremetal
-usage, the IOMMU is a system device which does not need to communicate
-with userspace directly.
-
-The primary use cases are guest Shared Virtual Address (SVA) and
-guest IO virtual address (IOVA), wherein the vIOMMU implementation
-relies on the physical IOMMU and for this reason requires interactions
-with the host driver.
-
-.. contents:: :local:
-
-Functionalities
-===============
-Communications of user and kernel involve both directions. The
-supported user-kernel APIs are as follows:
-
-1. Bind/Unbind guest PASID (e.g. Intel VT-d)
-2. Bind/Unbind guest PASID table (e.g. ARM SMMU)
-3. Invalidate IOMMU caches upon guest requests
-4. Report errors to the guest and serve page requests
-
-Requirements
-============
-The IOMMU UAPIs are generic and extensible to meet the following
-requirements:
-
-1. Emulated and para-virtualised vIOMMUs
-2. Multiple vendors (Intel VT-d, ARM SMMU, etc.)
-3. Extensions to the UAPI shall not break existing userspace
-
-Interfaces
-==========
-Although the data structures defined in IOMMU UAPI are self-contained,
-there are no user API functions introduced. Instead, IOMMU UAPI is
-designed to work with existing user driver frameworks such as VFIO.
-
-Extension Rules & Precautions
------------------------------
-When IOMMU UAPI gets extended, the data structures can *only* be
-modified in two ways:
-
-1. Adding new fields by re-purposing the padding[] field. No size change.
-2. Adding new union members at the end. May increase the structure sizes.
-
-No new fields can be added *after* the variable sized union in that it
-will break backward compatibility when offset moves. A new flag must
-be introduced whenever a change affects the structure using either
-method. The IOMMU driver processes the data based on flags which
-ensures backward compatibility.
-
-Version field is only reserved for the unlikely event of UAPI upgrade
-at its entirety.
-
-It's *always* the caller's responsibility to indicate the size of the
-structure passed by setting argsz appropriately.
-Though at the same time, argsz is user provided data which is not
-trusted. The argsz field allows the user app to indicate how much data
-it is providing; it's still the kernel's responsibility to validate
-whether it's correct and sufficient for the requested operation.
-
-Compatibility Checking
-----------------------
-When IOMMU UAPI extension results in some structure size increase,
-IOMMU UAPI code shall handle the following cases:
-
-1. User and kernel has exact size match
-2. An older user with older kernel header (smaller UAPI size) running on a
-   newer kernel (larger UAPI size)
-3. A newer user with newer kernel header (larger UAPI size) running
-   on an older kernel.
-4. A malicious/misbehaving user passing illegal/invalid size but within
-   range. The data may contain garbage.
-
-Feature Checking
-----------------
-While launching a guest with vIOMMU, it is strongly advised to check
-the compatibility upfront, as some subsequent errors happening during
-vIOMMU operation, such as cache invalidation failures cannot be nicely
-escalated to the guest due to IOMMU specifications. This can lead to
-catastrophic failures for the users.
-
-User applications such as QEMU are expected to import kernel UAPI
-headers. Backward compatibility is supported per feature flags.
-For example, an older QEMU (with older kernel header) can run on newer
-kernel. Newer QEMU (with new kernel header) may refuse to initialize
-on an older kernel if new feature flags are not supported by older
-kernel. Simply recompiling existing code with newer kernel header should
-not be an issue in that only existing flags are used.
-
-IOMMU vendor driver should report the below features to IOMMU UAPI
-consumers (e.g. via VFIO).
-
-1. IOMMU_NESTING_FEAT_SYSWIDE_PASID
-2. IOMMU_NESTING_FEAT_BIND_PGTBL
-3. IOMMU_NESTING_FEAT_BIND_PASID_TABLE
-4. IOMMU_NESTING_FEAT_CACHE_INVLD
-5. IOMMU_NESTING_FEAT_PAGE_REQUEST
-
-Take VFIO as example, upon request from VFIO userspace (e.g. QEMU),
-VFIO kernel code shall query IOMMU vendor driver for the support of
-the above features. Query result can then be reported back to the
-userspace caller. Details can be found in
-Documentation/driver-api/vfio.rst.
-
-
-Data Passing Example with VFIO
-------------------------------
-As the ubiquitous userspace driver framework, VFIO is already IOMMU
-aware and shares many key concepts such as device model, group, and
-protection domain. Other user driver frameworks can also be extended
-to support IOMMU UAPI but it is outside the scope of this document.
-
-In this tight-knit VFIO-IOMMU interface, the ultimate consumer of the
-IOMMU UAPI data is the host IOMMU driver. VFIO facilitates user-kernel
-transport, capability checking, security, and life cycle management of
-process address space ID (PASID).
-
-VFIO layer conveys the data structures down to the IOMMU driver. It
-follows the pattern below::
-
-   struct {
-	__u32 argsz;
-	__u32 flags;
-	__u8  data[];
-   };
-
-Here data[] contains the IOMMU UAPI data structures. VFIO has the
-freedom to bundle the data as well as parse data size based on its own flags.
-
-In order to determine the size and feature set of the user data, argsz
-and flags (or the equivalent) are also embedded in the IOMMU UAPI data
-structures.
-
-A "__u32 argsz" field is *always* at the beginning of each structure.
-
-For example:
-::
-
-   struct iommu_cache_invalidate_info {
-	__u32	argsz;
-	#define IOMMU_CACHE_INVALIDATE_INFO_VERSION_1 1
-	__u32	version;
-	/* IOMMU paging structure cache */
-	#define IOMMU_CACHE_INV_TYPE_IOTLB	(1 << 0) /* IOMMU IOTLB */
-	#define IOMMU_CACHE_INV_TYPE_DEV_IOTLB	(1 << 1) /* Device IOTLB */
-	#define IOMMU_CACHE_INV_TYPE_PASID	(1 << 2) /* PASID cache */
-	#define IOMMU_CACHE_INV_TYPE_NR		(3)
-	__u8	cache;
-	__u8	granularity;
-	__u8	padding[6];
-	union {
-		struct iommu_inv_pasid_info pasid_info;
-		struct iommu_inv_addr_info addr_info;
-	} granu;
-   };
-
-VFIO is responsible for checking its own argsz and flags. It then
-invokes appropriate IOMMU UAPI functions. The user pointers are passed
-to the IOMMU layer for further processing. The responsibilities are
-divided as follows:
-
-- Generic IOMMU layer checks argsz range based on UAPI data in the
-  current kernel version.
-
-- Generic IOMMU layer checks content of the UAPI data for non-zero
-  reserved bits in flags, padding fields, and unsupported version.
-  This is to ensure not breaking userspace in the future when these
-  fields or flags are used.
-
-- Vendor IOMMU driver checks argsz based on vendor flags. UAPI data
-  is consumed based on flags. Vendor driver has access to
-  unadulterated argsz value in case of vendor specific future
-  extensions. Currently, it does not perform the copy_from_user()
-  itself. A __user pointer can be provided in some future scenarios
-  where there's vendor data outside of the structure definition.
-
-IOMMU code treats UAPI data in two categories:
-
-- structure contains vendor data
-  (Example: iommu_uapi_cache_invalidate())
-
-- structure contains only generic data
-  (Example: iommu_uapi_sva_bind_gpasid())
-
-
-
-Sharing UAPI with in-kernel users
----------------------------------
-For UAPIs that are shared with in-kernel users, a wrapper function is
-provided to distinguish the callers. For example,
-
-Userspace caller ::
-
-  int iommu_uapi_sva_unbind_gpasid(struct iommu_domain *domain,
-                                   struct device *dev,
-                                   void __user *udata)
-
-In-kernel caller ::
-
-  int iommu_sva_unbind_gpasid(struct iommu_domain *domain,
-                              struct device *dev, ioasid_t ioasid);
diff --git a/MAINTAINERS b/MAINTAINERS
index 0748d6bd0c4f..1359ed17337e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11544,7 +11544,6 @@  L:	iommu@lists.linux.dev
 S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/joro/iommu.git
 F:	Documentation/devicetree/bindings/iommu/
-F:	Documentation/userspace-api/iommu.rst
 F:	drivers/iommu/
 F:	include/linux/iommu.h
 F:	include/linux/iova.h