On Mon, Nov 07, 2022 at 08:49:03PM -0400, Jason Gunthorpe wrote:
diff --git a/include/uapi/linux/iommufd.h b/include/uapi/linux/iommufd.h index 2ad06b27a35fe5..a872a50d800a41 100644 --- a/include/uapi/linux/iommufd.h +++ b/include/uapi/linux/iommufd.h @@ -37,6 +37,13 @@ enum { IOMMUFD_CMD_BASE = 0x80, IOMMUFD_CMD_DESTROY = IOMMUFD_CMD_BASE,
- IOMMUFD_CMD_IOAS_ALLOC,
- IOMMUFD_CMD_IOAS_ALLOW_IOVAS,
- IOMMUFD_CMD_IOAS_COPY,
- IOMMUFD_CMD_IOAS_IOVA_RANGES,
- IOMMUFD_CMD_IOAS_MAP,
- IOMMUFD_CMD_IOAS_UNMAP,
- IOMMUFD_CMD_OPTION,
}; /** @@ -52,4 +59,238 @@ struct iommu_destroy { }; #define IOMMU_DESTROY _IO(IOMMUFD_TYPE, IOMMUFD_CMD_DESTROY) +/**
- struct iommu_ioas_alloc - ioctl(IOMMU_IOAS_ALLOC)
- @size: sizeof(struct iommu_ioas_alloc)
- @flags: Must be 0
- @out_ioas_id: Output IOAS ID for the allocated object
- Allocate an IO Address Space (IOAS) which holds an IO Virtual Address (IOVA)
- to memory mapping.
- */
+struct iommu_ioas_alloc {
- __u32 size;
- __u32 flags;
- __u32 out_ioas_id;
+}; +#define IOMMU_IOAS_ALLOC _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_ALLOC)
+/**
- struct iommu_iova_range
- @start: First IOVA
- @last: Inclusive last IOVA
- An interval in IOVA space.
- */
+struct iommu_iova_range {
- __aligned_u64 start;
- __aligned_u64 last;
+};
+/**
- struct iommu_ioas_iova_ranges - ioctl(IOMMU_IOAS_IOVA_RANGES)
- @size: sizeof(struct iommu_ioas_iova_ranges)
- @ioas_id: IOAS ID to read ranges from
- @num_iovas: Input/Output total number of ranges in the IOAS
- @__reserved: Must be 0
- @allowed_iovas: Pointer to the output array of struct iommu_iova_range
- @out_iova_alignment: Minimum alignment required for mapping IOVA
- Query an IOAS for ranges of allowed IOVAs. Mapping IOVA outside these ranges
- is not allowed. num_iovas will be set to the total number of iovas and
- the allowed_iovas[] will be filled in as space permits.
- The allowed ranges are dependent on the HW path the DMA operation takes, and
- can change during the lifetime of the IOAS. A fresh empty IOAS will have a
- full range, and each attached device will narrow the ranges based on that
- device's HW restrictions. Detatching a device can widen the ranges. Userspace
- should query ranges after every attach/detatch to know what IOVAs are valid
- for mapping.
- On input num_iovas is the length of the allowed_iovas array. On output it is
- the total number of iovas filled in. The ioctl will return -EMSGSIZE and set
- num_iovas to the required value if num_iovas is too small. In this case the
- caller should allocate a larger output array and re-issue the ioctl.
- */
+struct iommu_ioas_iova_ranges {
- __u32 size;
- __u32 ioas_id;
- __u32 num_iovas;
- __u32 __reserved;
- __aligned_u64 allowed_iovas;
- __aligned_u64 out_iova_alignment;
+}; +#define IOMMU_IOAS_IOVA_RANGES _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_IOVA_RANGES)
+/**
- struct iommu_ioas_allow_iovas - ioctl(IOMMU_IOAS_ALLOW_IOVAS)
- @size: sizeof(struct iommu_ioas_allow_iovas)
- @ioas_id: IOAS ID to allow IOVAs from
- @num_iovas: Input/Output total number of ranges in the IOAS
- @__reserved: Must be 0
- @allowed_iovas: Pointer to array of struct iommu_iova_range
- Ensure a range of IOVAs are always available for allocation. If this call
- succeeds then IOMMU_IOAS_IOVA_RANGES will never return a list of IOVA ranges
- that are narrower than the ranges provided here. This call will fail if
- IOMMU_IOAS_IOVA_RANGES is currently narrower than the given ranges.
- When an IOAS is first created the IOVA_RANGES will be maximally sized, and as
- devices are attached the IOVA will narrow based on the device restrictions.
- When an allowed range is specified any narrowing will be refused, ie device
- attachment can fail if the device requires limiting within the allowed range.
- Automatic IOVA allocation is also impacted by this call. MAP will only
- allocate within the allowed IOVAs if they are present.
- This call replaces the entire allowed list with the given list.
- */
+struct iommu_ioas_allow_iovas {
- __u32 size;
- __u32 ioas_id;
- __u32 num_iovas;
- __u32 __reserved;
- __aligned_u64 allowed_iovas;
+}; +#define IOMMU_IOAS_ALLOW_IOVAS _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_ALLOW_IOVAS)
+/**
- enum iommufd_ioas_map_flags - Flags for map and copy
- @IOMMU_IOAS_MAP_FIXED_IOVA: If clear the kernel will compute an appropriate
IOVA to place the mapping at
- @IOMMU_IOAS_MAP_WRITEABLE: DMA is allowed to write to this mapping
- @IOMMU_IOAS_MAP_READABLE: DMA is allowed to read from this mapping
- */
+enum iommufd_ioas_map_flags {
- IOMMU_IOAS_MAP_FIXED_IOVA = 1 << 0,
- IOMMU_IOAS_MAP_WRITEABLE = 1 << 1,
- IOMMU_IOAS_MAP_READABLE = 1 << 2,
+};
+/**
- struct iommu_ioas_map - ioctl(IOMMU_IOAS_MAP)
- @size: sizeof(struct iommu_ioas_map)
- @flags: Combination of enum iommufd_ioas_map_flags
- @ioas_id: IOAS ID to change the mapping of
- @__reserved: Must be 0
- @user_va: Userspace pointer to start mapping from
- @length: Number of bytes to map
- @iova: IOVA the mapping was placed at. If IOMMU_IOAS_MAP_FIXED_IOVA is set
then this must be provided as input.
- Set an IOVA mapping from a user pointer. If FIXED_IOVA is specified then the
- mapping will be established at iova, otherwise a suitable location based on
- the reserved and allowed lists will be automatically selected and returned in
- iova.
- */
+struct iommu_ioas_map {
- __u32 size;
- __u32 flags;
- __u32 ioas_id;
- __u32 __reserved;
- __aligned_u64 user_va;
- __aligned_u64 length;
- __aligned_u64 iova;
+}; +#define IOMMU_IOAS_MAP _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_MAP)
+/**
- struct iommu_ioas_copy - ioctl(IOMMU_IOAS_COPY)
- @size: sizeof(struct iommu_ioas_copy)
- @flags: Combination of enum iommufd_ioas_map_flags
- @dst_ioas_id: IOAS ID to change the mapping of
- @src_ioas_id: IOAS ID to copy from
- @length: Number of bytes to copy and map
- @dst_iova: IOVA the mapping was placed at. If IOMMU_IOAS_MAP_FIXED_IOVA is
set then this must be provided as input.
- @src_iova: IOVA to start the copy
- Copy an already existing mapping from src_ioas_id and establish it in
- dst_ioas_id. The src iova/length must exactly match a range used with
- IOMMU_IOAS_MAP.
- This may be used to efficiently clone a subset of an IOAS to another, or as a
- kind of 'cache' to speed up mapping. Copy has an effciency advantage over
- establishing equivalent new mappings, as internal resources are shared, and
- the kernel will pin the user memory only once.
- */
+struct iommu_ioas_copy {
- __u32 size;
- __u32 flags;
- __u32 dst_ioas_id;
- __u32 src_ioas_id;
- __aligned_u64 length;
- __aligned_u64 dst_iova;
- __aligned_u64 src_iova;
+}; +#define IOMMU_IOAS_COPY _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_COPY)
+/**
- struct iommu_ioas_unmap - ioctl(IOMMU_IOAS_UNMAP)
- @size: sizeof(struct iommu_ioas_unmap)
- @ioas_id: IOAS ID to change the mapping of
- @iova: IOVA to start the unmapping at
- @length: Number of bytes to unmap, and return back the bytes unmapped
- Unmap an IOVA range. The iova/length must be a superset of a previously
- mapped range used with IOMMU_IOAS_MAP or IOMMU_IOAS_COPY. Splitting or
- truncating ranges is not allowed. The values 0 to U64_MAX will unmap
- everything.
- */
+struct iommu_ioas_unmap {
- __u32 size;
- __u32 ioas_id;
- __aligned_u64 iova;
- __aligned_u64 length;
+}; +#define IOMMU_IOAS_UNMAP _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_UNMAP)
+/**
- enum iommufd_option
- @IOMMU_OPTION_RLIMIT_MODE:
- Change how RLIMIT_MEMLOCK accounting works. The caller must have privilege
- to invoke this. Value 0 (default) is user based accouting, 1 uses process
- based accounting. Global option, object_id must be 0
- @IOMMU_OPTION_HUGE_PAGES:
- Value 1 (default) allows contiguous pages to be combined when generating
- iommu mappings. Value 0 disables combining, everything is mapped to
- PAGE_SIZE. This can be useful for benchmarking. This is a per-IOAS
- option, the object_id must be the IOAS ID.
- */
+enum iommufd_option {
- IOMMU_OPTION_RLIMIT_MODE = 0,
- IOMMU_OPTION_HUGE_PAGES = 1,
+};
+/**
- enum iommufd_option_ops
- @IOMMU_OPTION_OP_SET: Set the option's value
- @IOMMU_OPTION_OP_GET: Get the option's value
- */
+enum iommufd_option_ops {
- IOMMU_OPTION_OP_SET = 0,
- IOMMU_OPTION_OP_GET = 1,
+};
+/**
- @size: sizeof(struct iommu_option)
- @option_id: One of enum iommufd_option
- @op: One of enum iommufd_option_ops
- @__reserved: Must be 0
- @object_id: ID of the object if required
- @val64: Option value to set or value returned on get
- Change a simple option value. This multiplexor allows controlling a options
- on objects. IOMMU_OPTION_OP_SET will load an option and IOMMU_OPTION_OP_GET
- will return the current value.
- */
+struct iommu_option {
- __u32 size;
- __u32 option_id;
- __u16 op;
- __u16 __reserved;
- __u32 object_id;
- __aligned_u64 val64;
+}; +#define IOMMU_OPTION _IO(IOMMUFD_TYPE, IOMMUFD_CMD_OPTION) #endif
I see kernel-doc warnings (missing short descriptions) when making htmldocs, so I have applied the fixup:
---- >8 ----
From 5643b202ae9853c11434466c76aeaaa044e88b07 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya bagasdotme@gmail.com Date: Tue, 8 Nov 2022 20:14:25 +0700 Subject: [PATCH] iommufd: Add missing ioctl short descriptions
Checking kernel-doc comments in iommufd.h header with scripts/kernel-doc produces missing short description warnings:
include/uapi/linux/iommufd.h:80: warning: missing initial short description on line: * struct iommu_iova_range include/uapi/linux/iommufd.h:250: warning: missing initial short description on line: * enum iommufd_option include/uapi/linux/iommufd.h:267: warning: missing initial short description on line: * enum iommufd_option_ops include/uapi/linux/iommufd.h:277: warning: Cannot understand * @size: sizeof(struct iommu_option) on line 277 - I thought it was a doc line include/uapi/linux/iommufd.h:299: warning: missing initial short description on line: * enum iommufd_vfio_ioas_op
One of them is reported by Stephen Rothwell when merging iommufd tree for linux-next.
Describe these ioctl structs and enums to fix above warnings.
Link: https://lore.kernel.org/linux-next/20221108165125.3bf96028@canb.auug.org.au/ Fixes: 5a013b3b3b2f02 ("iommufd: IOCTLs for the io_pagetable") Reported-by: Stephen Rothwell sfr@canb.auug.org.au Signed-off-by: Bagas Sanjaya bagasdotme@gmail.com --- include/uapi/linux/iommufd.h | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/include/uapi/linux/iommufd.h b/include/uapi/linux/iommufd.h index c7109d7e5e09a9..66e9fb104bde5a 100644 --- a/include/uapi/linux/iommufd.h +++ b/include/uapi/linux/iommufd.h @@ -77,7 +77,7 @@ struct iommu_ioas_alloc { #define IOMMU_IOAS_ALLOC _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_ALLOC)
/** - * struct iommu_iova_range + * struct iommu_iova_range - ioctl(IOMMU_IOVA_RANGE) * @start: First IOVA * @last: Inclusive last IOVA * @@ -247,7 +247,8 @@ struct iommu_ioas_unmap { #define IOMMU_IOAS_UNMAP _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_UNMAP)
/** - * enum iommufd_option + * enum iommufd_option - ioctl(IOMMU_OPTION_RLIMIT_MODE) and + * ioctl(IOMMU_OPTION_HUGE_PAGES) * @IOMMU_OPTION_RLIMIT_MODE: * Change how RLIMIT_MEMLOCK accounting works. The caller must have privilege * to invoke this. Value 0 (default) is user based accouting, 1 uses process @@ -264,7 +265,8 @@ enum iommufd_option { };
/** - * enum iommufd_option_ops + * enum iommufd_option_ops - ioctl(IOMMU_OPTION_OP_SET) and + * ioctl(IOMMU_OPTION_OP_GET) * @IOMMU_OPTION_OP_SET: Set the option's value * @IOMMU_OPTION_OP_GET: Get the option's value */ @@ -274,6 +276,7 @@ enum iommufd_option_ops { };
/** + * struct iommu_option - iommu option multiplexer * @size: sizeof(struct iommu_option) * @option_id: One of enum iommufd_option * @op: One of enum iommufd_option_ops @@ -296,7 +299,7 @@ struct iommu_option { #define IOMMU_OPTION _IO(IOMMUFD_TYPE, IOMMUFD_CMD_OPTION)
/** - * enum iommufd_vfio_ioas_op + * enum iommufd_vfio_ioas_op - IOMMU_VFIO_IOAS_* ioctls * @IOMMU_VFIO_IOAS_GET: Get the current compatibility IOAS * @IOMMU_VFIO_IOAS_SET: Change the current compatibility IOAS * @IOMMU_VFIO_IOAS_CLEAR: Disable VFIO compatibility
Thanks.