linux-headers (unknown)
1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
2 /* Copyright (c) 2021-2022, NVIDIA CORPORATION & AFFILIATES.
3 */
4 #ifndef _IOMMUFD_H
5 #define _IOMMUFD_H
6
7 #include <linux/types.h>
8 #include <linux/ioctl.h>
9
10 #define IOMMUFD_TYPE (';')
11
12 /**
13 * DOC: General ioctl format
14 *
15 * The ioctl interface follows a general format to allow for extensibility. Each
16 * ioctl is passed in a structure pointer as the argument providing the size of
17 * the structure in the first u32. The kernel checks that any structure space
18 * beyond what it understands is 0. This allows userspace to use the backward
19 * compatible portion while consistently using the newer, larger, structures.
20 *
21 * ioctls use a standard meaning for common errnos:
22 *
23 * - ENOTTY: The IOCTL number itself is not supported at all
24 * - E2BIG: The IOCTL number is supported, but the provided structure has
25 * non-zero in a part the kernel does not understand.
26 * - EOPNOTSUPP: The IOCTL number is supported, and the structure is
27 * understood, however a known field has a value the kernel does not
28 * understand or support.
29 * - EINVAL: Everything about the IOCTL was understood, but a field is not
30 * correct.
31 * - ENOENT: An ID or IOVA provided does not exist.
32 * - ENOMEM: Out of memory.
33 * - EOVERFLOW: Mathematics overflowed.
34 *
35 * As well as additional errnos, within specific ioctls.
36 */
37 enum {
38 IOMMUFD_CMD_BASE = 0x80,
39 IOMMUFD_CMD_DESTROY = IOMMUFD_CMD_BASE,
40 IOMMUFD_CMD_IOAS_ALLOC,
41 IOMMUFD_CMD_IOAS_ALLOW_IOVAS,
42 IOMMUFD_CMD_IOAS_COPY,
43 IOMMUFD_CMD_IOAS_IOVA_RANGES,
44 IOMMUFD_CMD_IOAS_MAP,
45 IOMMUFD_CMD_IOAS_UNMAP,
46 IOMMUFD_CMD_OPTION,
47 IOMMUFD_CMD_VFIO_IOAS,
48 };
49
50 /**
51 * struct iommu_destroy - ioctl(IOMMU_DESTROY)
52 * @size: sizeof(struct iommu_destroy)
53 * @id: iommufd object ID to destroy. Can be any destroyable object type.
54 *
55 * Destroy any object held within iommufd.
56 */
57 struct iommu_destroy {
58 __u32 size;
59 __u32 id;
60 };
61 #define IOMMU_DESTROY _IO(IOMMUFD_TYPE, IOMMUFD_CMD_DESTROY)
62
63 /**
64 * struct iommu_ioas_alloc - ioctl(IOMMU_IOAS_ALLOC)
65 * @size: sizeof(struct iommu_ioas_alloc)
66 * @flags: Must be 0
67 * @out_ioas_id: Output IOAS ID for the allocated object
68 *
69 * Allocate an IO Address Space (IOAS) which holds an IO Virtual Address (IOVA)
70 * to memory mapping.
71 */
72 struct iommu_ioas_alloc {
73 __u32 size;
74 __u32 flags;
75 __u32 out_ioas_id;
76 };
77 #define IOMMU_IOAS_ALLOC _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_ALLOC)
78
79 /**
80 * struct iommu_iova_range - ioctl(IOMMU_IOVA_RANGE)
81 * @start: First IOVA
82 * @last: Inclusive last IOVA
83 *
84 * An interval in IOVA space.
85 */
86 struct iommu_iova_range {
87 __aligned_u64 start;
88 __aligned_u64 last;
89 };
90
91 /**
92 * struct iommu_ioas_iova_ranges - ioctl(IOMMU_IOAS_IOVA_RANGES)
93 * @size: sizeof(struct iommu_ioas_iova_ranges)
94 * @ioas_id: IOAS ID to read ranges from
95 * @num_iovas: Input/Output total number of ranges in the IOAS
96 * @__reserved: Must be 0
97 * @allowed_iovas: Pointer to the output array of struct iommu_iova_range
98 * @out_iova_alignment: Minimum alignment required for mapping IOVA
99 *
100 * Query an IOAS for ranges of allowed IOVAs. Mapping IOVA outside these ranges
101 * is not allowed. num_iovas will be set to the total number of iovas and
102 * the allowed_iovas[] will be filled in as space permits.
103 *
104 * The allowed ranges are dependent on the HW path the DMA operation takes, and
105 * can change during the lifetime of the IOAS. A fresh empty IOAS will have a
106 * full range, and each attached device will narrow the ranges based on that
107 * device's HW restrictions. Detaching a device can widen the ranges. Userspace
108 * should query ranges after every attach/detach to know what IOVAs are valid
109 * for mapping.
110 *
111 * On input num_iovas is the length of the allowed_iovas array. On output it is
112 * the total number of iovas filled in. The ioctl will return -EMSGSIZE and set
113 * num_iovas to the required value if num_iovas is too small. In this case the
114 * caller should allocate a larger output array and re-issue the ioctl.
115 *
116 * out_iova_alignment returns the minimum IOVA alignment that can be given
117 * to IOMMU_IOAS_MAP/COPY. IOVA's must satisfy::
118 *
119 * starting_iova % out_iova_alignment == 0
120 * (starting_iova + length) % out_iova_alignment == 0
121 *
122 * out_iova_alignment can be 1 indicating any IOVA is allowed. It cannot
123 * be higher than the system PAGE_SIZE.
124 */
125 struct iommu_ioas_iova_ranges {
126 __u32 size;
127 __u32 ioas_id;
128 __u32 num_iovas;
129 __u32 __reserved;
130 __aligned_u64 allowed_iovas;
131 __aligned_u64 out_iova_alignment;
132 };
133 #define IOMMU_IOAS_IOVA_RANGES _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_IOVA_RANGES)
134
135 /**
136 * struct iommu_ioas_allow_iovas - ioctl(IOMMU_IOAS_ALLOW_IOVAS)
137 * @size: sizeof(struct iommu_ioas_allow_iovas)
138 * @ioas_id: IOAS ID to allow IOVAs from
139 * @num_iovas: Input/Output total number of ranges in the IOAS
140 * @__reserved: Must be 0
141 * @allowed_iovas: Pointer to array of struct iommu_iova_range
142 *
143 * Ensure a range of IOVAs are always available for allocation. If this call
144 * succeeds then IOMMU_IOAS_IOVA_RANGES will never return a list of IOVA ranges
145 * that are narrower than the ranges provided here. This call will fail if
146 * IOMMU_IOAS_IOVA_RANGES is currently narrower than the given ranges.
147 *
148 * When an IOAS is first created the IOVA_RANGES will be maximally sized, and as
149 * devices are attached the IOVA will narrow based on the device restrictions.
150 * When an allowed range is specified any narrowing will be refused, ie device
151 * attachment can fail if the device requires limiting within the allowed range.
152 *
153 * Automatic IOVA allocation is also impacted by this call. MAP will only
154 * allocate within the allowed IOVAs if they are present.
155 *
156 * This call replaces the entire allowed list with the given list.
157 */
158 struct iommu_ioas_allow_iovas {
159 __u32 size;
160 __u32 ioas_id;
161 __u32 num_iovas;
162 __u32 __reserved;
163 __aligned_u64 allowed_iovas;
164 };
165 #define IOMMU_IOAS_ALLOW_IOVAS _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_ALLOW_IOVAS)
166
167 /**
168 * enum iommufd_ioas_map_flags - Flags for map and copy
169 * @IOMMU_IOAS_MAP_FIXED_IOVA: If clear the kernel will compute an appropriate
170 * IOVA to place the mapping at
171 * @IOMMU_IOAS_MAP_WRITEABLE: DMA is allowed to write to this mapping
172 * @IOMMU_IOAS_MAP_READABLE: DMA is allowed to read from this mapping
173 */
174 enum iommufd_ioas_map_flags {
175 IOMMU_IOAS_MAP_FIXED_IOVA = 1 << 0,
176 IOMMU_IOAS_MAP_WRITEABLE = 1 << 1,
177 IOMMU_IOAS_MAP_READABLE = 1 << 2,
178 };
179
180 /**
181 * struct iommu_ioas_map - ioctl(IOMMU_IOAS_MAP)
182 * @size: sizeof(struct iommu_ioas_map)
183 * @flags: Combination of enum iommufd_ioas_map_flags
184 * @ioas_id: IOAS ID to change the mapping of
185 * @__reserved: Must be 0
186 * @user_va: Userspace pointer to start mapping from
187 * @length: Number of bytes to map
188 * @iova: IOVA the mapping was placed at. If IOMMU_IOAS_MAP_FIXED_IOVA is set
189 * then this must be provided as input.
190 *
191 * Set an IOVA mapping from a user pointer. If FIXED_IOVA is specified then the
192 * mapping will be established at iova, otherwise a suitable location based on
193 * the reserved and allowed lists will be automatically selected and returned in
194 * iova.
195 *
196 * If IOMMU_IOAS_MAP_FIXED_IOVA is specified then the iova range must currently
197 * be unused, existing IOVA cannot be replaced.
198 */
199 struct iommu_ioas_map {
200 __u32 size;
201 __u32 flags;
202 __u32 ioas_id;
203 __u32 __reserved;
204 __aligned_u64 user_va;
205 __aligned_u64 length;
206 __aligned_u64 iova;
207 };
208 #define IOMMU_IOAS_MAP _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_MAP)
209
210 /**
211 * struct iommu_ioas_copy - ioctl(IOMMU_IOAS_COPY)
212 * @size: sizeof(struct iommu_ioas_copy)
213 * @flags: Combination of enum iommufd_ioas_map_flags
214 * @dst_ioas_id: IOAS ID to change the mapping of
215 * @src_ioas_id: IOAS ID to copy from
216 * @length: Number of bytes to copy and map
217 * @dst_iova: IOVA the mapping was placed at. If IOMMU_IOAS_MAP_FIXED_IOVA is
218 * set then this must be provided as input.
219 * @src_iova: IOVA to start the copy
220 *
221 * Copy an already existing mapping from src_ioas_id and establish it in
222 * dst_ioas_id. The src iova/length must exactly match a range used with
223 * IOMMU_IOAS_MAP.
224 *
225 * This may be used to efficiently clone a subset of an IOAS to another, or as a
226 * kind of 'cache' to speed up mapping. Copy has an efficiency advantage over
227 * establishing equivalent new mappings, as internal resources are shared, and
228 * the kernel will pin the user memory only once.
229 */
230 struct iommu_ioas_copy {
231 __u32 size;
232 __u32 flags;
233 __u32 dst_ioas_id;
234 __u32 src_ioas_id;
235 __aligned_u64 length;
236 __aligned_u64 dst_iova;
237 __aligned_u64 src_iova;
238 };
239 #define IOMMU_IOAS_COPY _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_COPY)
240
241 /**
242 * struct iommu_ioas_unmap - ioctl(IOMMU_IOAS_UNMAP)
243 * @size: sizeof(struct iommu_ioas_unmap)
244 * @ioas_id: IOAS ID to change the mapping of
245 * @iova: IOVA to start the unmapping at
246 * @length: Number of bytes to unmap, and return back the bytes unmapped
247 *
248 * Unmap an IOVA range. The iova/length must be a superset of a previously
249 * mapped range used with IOMMU_IOAS_MAP or IOMMU_IOAS_COPY. Splitting or
250 * truncating ranges is not allowed. The values 0 to U64_MAX will unmap
251 * everything.
252 */
253 struct iommu_ioas_unmap {
254 __u32 size;
255 __u32 ioas_id;
256 __aligned_u64 iova;
257 __aligned_u64 length;
258 };
259 #define IOMMU_IOAS_UNMAP _IO(IOMMUFD_TYPE, IOMMUFD_CMD_IOAS_UNMAP)
260
261 /**
262 * enum iommufd_option - ioctl(IOMMU_OPTION_RLIMIT_MODE) and
263 * ioctl(IOMMU_OPTION_HUGE_PAGES)
264 * @IOMMU_OPTION_RLIMIT_MODE:
265 * Change how RLIMIT_MEMLOCK accounting works. The caller must have privilege
266 * to invoke this. Value 0 (default) is user based accouting, 1 uses process
267 * based accounting. Global option, object_id must be 0
268 * @IOMMU_OPTION_HUGE_PAGES:
269 * Value 1 (default) allows contiguous pages to be combined when generating
270 * iommu mappings. Value 0 disables combining, everything is mapped to
271 * PAGE_SIZE. This can be useful for benchmarking. This is a per-IOAS
272 * option, the object_id must be the IOAS ID.
273 */
274 enum iommufd_option {
275 IOMMU_OPTION_RLIMIT_MODE = 0,
276 IOMMU_OPTION_HUGE_PAGES = 1,
277 };
278
279 /**
280 * enum iommufd_option_ops - ioctl(IOMMU_OPTION_OP_SET) and
281 * ioctl(IOMMU_OPTION_OP_GET)
282 * @IOMMU_OPTION_OP_SET: Set the option's value
283 * @IOMMU_OPTION_OP_GET: Get the option's value
284 */
285 enum iommufd_option_ops {
286 IOMMU_OPTION_OP_SET = 0,
287 IOMMU_OPTION_OP_GET = 1,
288 };
289
290 /**
291 * struct iommu_option - iommu option multiplexer
292 * @size: sizeof(struct iommu_option)
293 * @option_id: One of enum iommufd_option
294 * @op: One of enum iommufd_option_ops
295 * @__reserved: Must be 0
296 * @object_id: ID of the object if required
297 * @val64: Option value to set or value returned on get
298 *
299 * Change a simple option value. This multiplexor allows controlling options
300 * on objects. IOMMU_OPTION_OP_SET will load an option and IOMMU_OPTION_OP_GET
301 * will return the current value.
302 */
303 struct iommu_option {
304 __u32 size;
305 __u32 option_id;
306 __u16 op;
307 __u16 __reserved;
308 __u32 object_id;
309 __aligned_u64 val64;
310 };
311 #define IOMMU_OPTION _IO(IOMMUFD_TYPE, IOMMUFD_CMD_OPTION)
312
313 /**
314 * enum iommufd_vfio_ioas_op - IOMMU_VFIO_IOAS_* ioctls
315 * @IOMMU_VFIO_IOAS_GET: Get the current compatibility IOAS
316 * @IOMMU_VFIO_IOAS_SET: Change the current compatibility IOAS
317 * @IOMMU_VFIO_IOAS_CLEAR: Disable VFIO compatibility
318 */
319 enum iommufd_vfio_ioas_op {
320 IOMMU_VFIO_IOAS_GET = 0,
321 IOMMU_VFIO_IOAS_SET = 1,
322 IOMMU_VFIO_IOAS_CLEAR = 2,
323 };
324
325 /**
326 * struct iommu_vfio_ioas - ioctl(IOMMU_VFIO_IOAS)
327 * @size: sizeof(struct iommu_vfio_ioas)
328 * @ioas_id: For IOMMU_VFIO_IOAS_SET the input IOAS ID to set
329 * For IOMMU_VFIO_IOAS_GET will output the IOAS ID
330 * @op: One of enum iommufd_vfio_ioas_op
331 * @__reserved: Must be 0
332 *
333 * The VFIO compatibility support uses a single ioas because VFIO APIs do not
334 * support the ID field. Set or Get the IOAS that VFIO compatibility will use.
335 * When VFIO_GROUP_SET_CONTAINER is used on an iommufd it will get the
336 * compatibility ioas, either by taking what is already set, or auto creating
337 * one. From then on VFIO will continue to use that ioas and is not effected by
338 * this ioctl. SET or CLEAR does not destroy any auto-created IOAS.
339 */
340 struct iommu_vfio_ioas {
341 __u32 size;
342 __u32 ioas_id;
343 __u16 op;
344 __u16 __reserved;
345 };
346 #define IOMMU_VFIO_IOAS _IO(IOMMUFD_TYPE, IOMMUFD_CMD_VFIO_IOAS)
347 #endif
Browse
Usage
Versions