1	/* SPDX-License-Identifier: MIT */
2	/*
3	* Copyright © 2023 Intel Corporation
4	*/
5
6	#ifndef _UAPI_XE_DRM_H_
7	#define _UAPI_XE_DRM_H_
8
9	#include "drm.h"
10
11	#if defined(__cplusplus)
12	extern "C" {
13	#endif
14
15	/*
16	* Please note that modifications to all structs defined here are
17	* subject to backwards-compatibility constraints.
18	* Sections in this file are organized as follows:
19	* 1. IOCTL definition
20	* 2. Extension definition and helper structs
21	* 3. IOCTL's Query structs in the order of the Query's entries.
22	* 4. The rest of IOCTL structs in the order of IOCTL declaration.
23	*/
24
25	/**
26	* DOC: Xe Device Block Diagram
27	*
28	* The diagram below represents a high-level simplification of a discrete
29	* GPU supported by the Xe driver. It shows some device components which
30	* are necessary to understand this API, as well as how their relations
31	* to each other. This diagram does not represent real hardware::
32	*
33	* ┌──────────────────────────────────────────────────────────────────┐
34	* │ ┌──────────────────────────────────────────────────┐ ┌─────────┐ │
35	* │ │ ┌───────────────────────┐ ┌─────┐ │ │ ┌─────┐ │ │
36	* │ │ │ VRAM0 ├───┤ ... │ │ │ │VRAM1│ │ │
37	* │ │ └───────────┬───────────┘ └─GT1─┘ │ │ └──┬──┘ │ │
38	* │ │ ┌──────────────────┴───────────────────────────┐ │ │ ┌──┴──┐ │ │
39	* │ │ │ ┌─────────────────────┐ ┌─────────────────┐ │ │ │ │ │ │ │
40	* │ │ │ │ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │ │ ┌─────┐ ┌─────┐ │ │ │ │ │ │ │ │
41	* │ │ │ │ │EU│ │EU│ │EU│ │EU│ │ │ │RCS0 │ │BCS0 │ │ │ │ │ │ │ │ │
42	* │ │ │ │ └──┘ └──┘ └──┘ └──┘ │ │ └─────┘ └─────┘ │ │ │ │ │ │ │ │
43	* │ │ │ │ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │ │ ┌─────┐ ┌─────┐ │ │ │ │ │ │ │ │
44	* │ │ │ │ │EU│ │EU│ │EU│ │EU│ │ │ │VCS0 │ │VCS1 │ │ │ │ │ │ │ │ │
45	* │ │ │ │ └──┘ └──┘ └──┘ └──┘ │ │ └─────┘ └─────┘ │ │ │ │ │ │ │ │
46	* │ │ │ │ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │ │ ┌─────┐ ┌─────┐ │ │ │ │ │ │ │ │
47	* │ │ │ │ │EU│ │EU│ │EU│ │EU│ │ │ │VECS0│ │VECS1│ │ │ │ │ │ ... │ │ │
48	* │ │ │ │ └──┘ └──┘ └──┘ └──┘ │ │ └─────┘ └─────┘ │ │ │ │ │ │ │ │
49	* │ │ │ │ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │ │ ┌─────┐ ┌─────┐ │ │ │ │ │ │ │ │
50	* │ │ │ │ │EU│ │EU│ │EU│ │EU│ │ │ │CCS0 │ │CCS1 │ │ │ │ │ │ │ │ │
51	* │ │ │ │ └──┘ └──┘ └──┘ └──┘ │ │ └─────┘ └─────┘ │ │ │ │ │ │ │ │
52	* │ │ │ └─────────DSS─────────┘ │ ┌─────┐ ┌─────┐ │ │ │ │ │ │ │ │
53	* │ │ │ │ │CCS2 │ │CCS3 │ │ │ │ │ │ │ │ │
54	* │ │ │ ┌─────┐ ┌─────┐ ┌─────┐ │ └─────┘ └─────┘ │ │ │ │ │ │ │ │
55	* │ │ │ │ ... │ │ ... │ │ ... │ │ │ │ │ │ │ │ │ │
56	* │ │ │ └─DSS─┘ └─DSS─┘ └─DSS─┘ └─────Engines─────┘ │ │ │ │ │ │ │
57	* │ │ └───────────────────────────GT0────────────────┘ │ │ └─GT2─┘ │ │
58	* │ └────────────────────────────Tile0─────────────────┘ └─ Tile1──┘ │
59	* └─────────────────────────────Device0───────┬──────────────────────┘
60	* │
61	* ───────────────────────┴────────── PCI bus
62	*/
63
64	/**
65	* DOC: Xe uAPI Overview
66	*
67	* This section aims to describe the Xe's IOCTL entries, its structs, and other
68	* Xe related uAPI such as uevents and PMU (Platform Monitoring Unit) related
69	* entries and usage.
70	*
71	* List of supported IOCTLs:
72	* - &DRM_IOCTL_XE_DEVICE_QUERY
73	* - &DRM_IOCTL_XE_GEM_CREATE
74	* - &DRM_IOCTL_XE_GEM_MMAP_OFFSET
75	* - &DRM_IOCTL_XE_VM_CREATE
76	* - &DRM_IOCTL_XE_VM_DESTROY
77	* - &DRM_IOCTL_XE_VM_BIND
78	* - &DRM_IOCTL_XE_EXEC_QUEUE_CREATE
79	* - &DRM_IOCTL_XE_EXEC_QUEUE_DESTROY
80	* - &DRM_IOCTL_XE_EXEC_QUEUE_GET_PROPERTY
81	* - &DRM_IOCTL_XE_EXEC
82	* - &DRM_IOCTL_XE_WAIT_USER_FENCE
83	* - &DRM_IOCTL_XE_OBSERVATION
84	* - &DRM_IOCTL_XE_MADVISE
85	* - &DRM_IOCTL_XE_VM_QUERY_MEM_RANGE_ATTRS
86	*/
87
88	/*
89	* xe specific ioctls.
90	*
91	* The device specific ioctl range is [DRM_COMMAND_BASE, DRM_COMMAND_END) ie
92	* [0x40, 0xa0) (a0 is excluded). The numbers below are defined as offset
93	* against DRM_COMMAND_BASE and should be between [0x0, 0x60).
94	*/
95	#define DRM_XE_DEVICE_QUERY 0x00
96	#define DRM_XE_GEM_CREATE 0x01
97	#define DRM_XE_GEM_MMAP_OFFSET 0x02
98	#define DRM_XE_VM_CREATE 0x03
99	#define DRM_XE_VM_DESTROY 0x04
100	#define DRM_XE_VM_BIND 0x05
101	#define DRM_XE_EXEC_QUEUE_CREATE 0x06
102	#define DRM_XE_EXEC_QUEUE_DESTROY 0x07
103	#define DRM_XE_EXEC_QUEUE_GET_PROPERTY 0x08
104	#define DRM_XE_EXEC 0x09
105	#define DRM_XE_WAIT_USER_FENCE 0x0a
106	#define DRM_XE_OBSERVATION 0x0b
107	#define DRM_XE_MADVISE 0x0c
108	#define DRM_XE_VM_QUERY_MEM_RANGE_ATTRS 0x0d
109
110	/* Must be kept compact -- no holes */
111
112	#define DRM_IOCTL_XE_DEVICE_QUERY DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_DEVICE_QUERY, struct drm_xe_device_query)
113	#define DRM_IOCTL_XE_GEM_CREATE DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_GEM_CREATE, struct drm_xe_gem_create)
114	#define DRM_IOCTL_XE_GEM_MMAP_OFFSET DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_GEM_MMAP_OFFSET, struct drm_xe_gem_mmap_offset)
115	#define DRM_IOCTL_XE_VM_CREATE DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_VM_CREATE, struct drm_xe_vm_create)
116	#define DRM_IOCTL_XE_VM_DESTROY DRM_IOW(DRM_COMMAND_BASE + DRM_XE_VM_DESTROY, struct drm_xe_vm_destroy)
117	#define DRM_IOCTL_XE_VM_BIND DRM_IOW(DRM_COMMAND_BASE + DRM_XE_VM_BIND, struct drm_xe_vm_bind)
118	#define DRM_IOCTL_XE_EXEC_QUEUE_CREATE DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_EXEC_QUEUE_CREATE, struct drm_xe_exec_queue_create)
119	#define DRM_IOCTL_XE_EXEC_QUEUE_DESTROY DRM_IOW(DRM_COMMAND_BASE + DRM_XE_EXEC_QUEUE_DESTROY, struct drm_xe_exec_queue_destroy)
120	#define DRM_IOCTL_XE_EXEC_QUEUE_GET_PROPERTY DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_EXEC_QUEUE_GET_PROPERTY, struct drm_xe_exec_queue_get_property)
121	#define DRM_IOCTL_XE_EXEC DRM_IOW(DRM_COMMAND_BASE + DRM_XE_EXEC, struct drm_xe_exec)
122	#define DRM_IOCTL_XE_WAIT_USER_FENCE DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_WAIT_USER_FENCE, struct drm_xe_wait_user_fence)
123	#define DRM_IOCTL_XE_OBSERVATION DRM_IOW(DRM_COMMAND_BASE + DRM_XE_OBSERVATION, struct drm_xe_observation_param)
124	#define DRM_IOCTL_XE_MADVISE DRM_IOW(DRM_COMMAND_BASE + DRM_XE_MADVISE, struct drm_xe_madvise)
125	#define DRM_IOCTL_XE_VM_QUERY_MEM_RANGE_ATTRS DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_VM_QUERY_MEM_RANGE_ATTRS, struct drm_xe_vm_query_mem_range_attr)
126
127	/**
128	* DOC: Xe IOCTL Extensions
129	*
130	* Before detailing the IOCTLs and its structs, it is important to highlight
131	* that every IOCTL in Xe is extensible.
132	*
133	* Many interfaces need to grow over time. In most cases we can simply
134	* extend the struct and have userspace pass in more data. Another option,
135	* as demonstrated by Vulkan's approach to providing extensions for forward
136	* and backward compatibility, is to use a list of optional structs to
137	* provide those extra details.
138	*
139	* The key advantage to using an extension chain is that it allows us to
140	* redefine the interface more easily than an ever growing struct of
141	* increasing complexity, and for large parts of that interface to be
142	* entirely optional. The downside is more pointer chasing; chasing across
143	* the __user boundary with pointers encapsulated inside u64.
144	*
145	* Example chaining:
146	*
147	* .. code-block:: C
148	*
149	* struct drm_xe_user_extension ext3 {
150	* .next_extension = 0, // end
151	* .name = ...,
152	* };
153	* struct drm_xe_user_extension ext2 {
154	* .next_extension = (uintptr_t)&ext3,
155	* .name = ...,
156	* };
157	* struct drm_xe_user_extension ext1 {
158	* .next_extension = (uintptr_t)&ext2,
159	* .name = ...,
160	* };
161	*
162	* Typically the struct drm_xe_user_extension would be embedded in some uAPI
163	* struct, and in this case we would feed it the head of the chain(i.e ext1),
164	* which would then apply all of the above extensions.
165	*/
166
167	/**
168	* struct drm_xe_user_extension - Base class for defining a chain of extensions
169	*/
170	struct drm_xe_user_extension {
171	/**
172	* @next_extension:
173	*
174	* Pointer to the next struct drm_xe_user_extension, or zero if the end.
175	*/
176	__u64 next_extension;
177
178	/**
179	* @name: Name of the extension.
180	*
181	* Note that the name here is just some integer.
182	*
183	* Also note that the name space for this is not global for the whole
184	* driver, but rather its scope/meaning is limited to the specific piece
185	* of uAPI which has embedded the struct drm_xe_user_extension.
186	*/
187	__u32 name;
188
189	/**
190	* @pad: MBZ
191	*
192	* All undefined bits must be zero.
193	*/
194	__u32 pad;
195	};
196
197	/**
198	* struct drm_xe_ext_set_property - Generic set property extension
199	*
200	* A generic struct that allows any of the Xe's IOCTL to be extended
201	* with a set_property operation.
202	*/
203	struct drm_xe_ext_set_property {
204	/** @base: base user extension */
205	struct drm_xe_user_extension base;
206
207	/** @property: property to set */
208	__u32 property;
209
210	/** @pad: MBZ */
211	__u32 pad;
212
213	/** @value: property value */
214	__u64 value;
215
216	/** @reserved: Reserved */
217	__u64 reserved[2];
218	};
219
220	/**
221	* struct drm_xe_engine_class_instance - instance of an engine class
222	*
223	* It is returned as part of the @drm_xe_engine, but it also is used as
224	* the input of engine selection for both @drm_xe_exec_queue_create and
225	* @drm_xe_query_engine_cycles
226	*
227	* The @engine_class can be:
228	* - %DRM_XE_ENGINE_CLASS_RENDER
229	* - %DRM_XE_ENGINE_CLASS_COPY
230	* - %DRM_XE_ENGINE_CLASS_VIDEO_DECODE
231	* - %DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE
232	* - %DRM_XE_ENGINE_CLASS_COMPUTE
233	* - %DRM_XE_ENGINE_CLASS_VM_BIND - Kernel only classes (not actual
234	* hardware engine class). Used for creating ordered queues of VM
235	* bind operations.
236	*/
237	struct drm_xe_engine_class_instance {
238	#define DRM_XE_ENGINE_CLASS_RENDER 0
239	#define DRM_XE_ENGINE_CLASS_COPY 1
240	#define DRM_XE_ENGINE_CLASS_VIDEO_DECODE 2
241	#define DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE 3
242	#define DRM_XE_ENGINE_CLASS_COMPUTE 4
243	#define DRM_XE_ENGINE_CLASS_VM_BIND 5
244	/** @engine_class: engine class id */
245	__u16 engine_class;
246	/** @engine_instance: engine instance id */
247	__u16 engine_instance;
248	/** @gt_id: Unique ID of this GT within the PCI Device */
249	__u16 gt_id;
250	/** @pad: MBZ */
251	__u16 pad;
252	};
253
254	/**
255	* struct drm_xe_engine - describe hardware engine
256	*/
257	struct drm_xe_engine {
258	/** @instance: The @drm_xe_engine_class_instance */
259	struct drm_xe_engine_class_instance instance;
260
261	/** @reserved: Reserved */
262	__u64 reserved[3];
263	};
264
265	/**
266	* struct drm_xe_query_engines - describe engines
267	*
268	* If a query is made with a struct @drm_xe_device_query where .query
269	* is equal to %DRM_XE_DEVICE_QUERY_ENGINES, then the reply uses an array of
270	* struct @drm_xe_query_engines in .data.
271	*/
272	struct drm_xe_query_engines {
273	/** @num_engines: number of engines returned in @engines */
274	__u32 num_engines;
275	/** @pad: MBZ */
276	__u32 pad;
277	/** @engines: The returned engines for this device */
278	struct drm_xe_engine engines[];
279	};
280
281	/**
282	* enum drm_xe_memory_class - Supported memory classes.
283	*/
284	enum drm_xe_memory_class {
285	/** @DRM_XE_MEM_REGION_CLASS_SYSMEM: Represents system memory. */
286	DRM_XE_MEM_REGION_CLASS_SYSMEM = 0,
287	/**
288	* @DRM_XE_MEM_REGION_CLASS_VRAM: On discrete platforms, this
289	* represents the memory that is local to the device, which we
290	* call VRAM. Not valid on integrated platforms.
291	*/
292	DRM_XE_MEM_REGION_CLASS_VRAM
293	};
294
295	/**
296	* struct drm_xe_mem_region - Describes some region as known to
297	* the driver.
298	*/
299	struct drm_xe_mem_region {
300	/**
301	* @mem_class: The memory class describing this region.
302	*
303	* See enum drm_xe_memory_class for supported values.
304	*/
305	__u16 mem_class;
306	/**
307	* @instance: The unique ID for this region, which serves as the
308	* index in the placement bitmask used as argument for
309	* &DRM_IOCTL_XE_GEM_CREATE
310	*/
311	__u16 instance;
312	/**
313	* @min_page_size: Min page-size in bytes for this region.
314	*
315	* When the kernel allocates memory for this region, the
316	* underlying pages will be at least @min_page_size in size.
317	* Buffer objects with an allowable placement in this region must be
318	* created with a size aligned to this value.
319	* GPU virtual address mappings of (parts of) buffer objects that
320	* may be placed in this region must also have their GPU virtual
321	* address and range aligned to this value.
322	* Affected IOCTLS will return %-EINVAL if alignment restrictions are
323	* not met.
324	*/
325	__u32 min_page_size;
326	/**
327	* @total_size: The usable size in bytes for this region.
328	*/
329	__u64 total_size;
330	/**
331	* @used: Estimate of the memory used in bytes for this region.
332	*
333	* Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliable
334	* accounting. Without this the value here will always equal
335	* zero.
336	*/
337	__u64 used;
338	/**
339	* @cpu_visible_size: How much of this region can be CPU
340	* accessed, in bytes.
341	*
342	* This will always be <= @total_size, and the remainder (if
343	* any) will not be CPU accessible. If the CPU accessible part
344	* is smaller than @total_size then this is referred to as a
345	* small BAR system.
346	*
347	* On systems without small BAR (full BAR), the probed_size will
348	* always equal the @total_size, since all of it will be CPU
349	* accessible.
350	*
351	* Note this is only tracked for DRM_XE_MEM_REGION_CLASS_VRAM
352	* regions (for other types the value here will always equal
353	* zero).
354	*/
355	__u64 cpu_visible_size;
356	/**
357	* @cpu_visible_used: Estimate of CPU visible memory used, in
358	* bytes.
359	*
360	* Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliable
361	* accounting. Without this the value here will always equal
362	* zero. Note this is only currently tracked for
363	* DRM_XE_MEM_REGION_CLASS_VRAM regions (for other types the value
364	* here will always be zero).
365	*/
366	__u64 cpu_visible_used;
367	/** @reserved: Reserved */
368	__u64 reserved[6];
369	};
370
371	/**
372	* struct drm_xe_query_mem_regions - describe memory regions
373	*
374	* If a query is made with a struct drm_xe_device_query where .query
375	* is equal to DRM_XE_DEVICE_QUERY_MEM_REGIONS, then the reply uses
376	* struct drm_xe_query_mem_regions in .data.
377	*/
378	struct drm_xe_query_mem_regions {
379	/** @num_mem_regions: number of memory regions returned in @mem_regions */
380	__u32 num_mem_regions;
381	/** @pad: MBZ */
382	__u32 pad;
383	/** @mem_regions: The returned memory regions for this device */
384	struct drm_xe_mem_region mem_regions[];
385	};
386
387	/**
388	* struct drm_xe_query_config - describe the device configuration
389	*
390	* If a query is made with a struct drm_xe_device_query where .query
391	* is equal to DRM_XE_DEVICE_QUERY_CONFIG, then the reply uses
392	* struct drm_xe_query_config in .data.
393	*
394	* The index in @info can be:
395	* - %DRM_XE_QUERY_CONFIG_REV_AND_DEVICE_ID - Device ID (lower 16 bits)
396	* and the device revision (next 8 bits)
397	* - %DRM_XE_QUERY_CONFIG_FLAGS - Flags describing the device
398	* configuration, see list below
399	*
400	* - %DRM_XE_QUERY_CONFIG_FLAG_HAS_VRAM - Flag is set if the device
401	* has usable VRAM
402	* - %DRM_XE_QUERY_CONFIG_FLAG_HAS_LOW_LATENCY - Flag is set if the device
403	* has low latency hint support
404	* - %DRM_XE_QUERY_CONFIG_FLAG_HAS_CPU_ADDR_MIRROR - Flag is set if the
405	* device has CPU address mirroring support
406	* - %DRM_XE_QUERY_CONFIG_MIN_ALIGNMENT - Minimal memory alignment
407	* required by this device, typically SZ_4K or SZ_64K
408	* - %DRM_XE_QUERY_CONFIG_VA_BITS - Maximum bits of a virtual address
409	* - %DRM_XE_QUERY_CONFIG_MAX_EXEC_QUEUE_PRIORITY - Value of the highest
410	* available exec queue priority
411	*/
412	struct drm_xe_query_config {
413	/** @num_params: number of parameters returned in info */
414	__u32 num_params;
415
416	/** @pad: MBZ */
417	__u32 pad;
418
419	#define DRM_XE_QUERY_CONFIG_REV_AND_DEVICE_ID 0
420	#define DRM_XE_QUERY_CONFIG_FLAGS 1
421	#define DRM_XE_QUERY_CONFIG_FLAG_HAS_VRAM (1 << 0)
422	#define DRM_XE_QUERY_CONFIG_FLAG_HAS_LOW_LATENCY (1 << 1)
423	#define DRM_XE_QUERY_CONFIG_FLAG_HAS_CPU_ADDR_MIRROR (1 << 2)
424	#define DRM_XE_QUERY_CONFIG_MIN_ALIGNMENT 2
425	#define DRM_XE_QUERY_CONFIG_VA_BITS 3
426	#define DRM_XE_QUERY_CONFIG_MAX_EXEC_QUEUE_PRIORITY 4
427	/** @info: array of elements containing the config info */
428	__u64 info[];
429	};
430
431	/**
432	* struct drm_xe_gt - describe an individual GT.
433	*
434	* To be used with drm_xe_query_gt_list, which will return a list with all the
435	* existing GT individual descriptions.
436	* Graphics Technology (GT) is a subset of a GPU/tile that is responsible for
437	* implementing graphics and/or media operations.
438	*
439	* The index in @type can be:
440	* - %DRM_XE_QUERY_GT_TYPE_MAIN
441	* - %DRM_XE_QUERY_GT_TYPE_MEDIA
442	*/
443	struct drm_xe_gt {
444	#define DRM_XE_QUERY_GT_TYPE_MAIN 0
445	#define DRM_XE_QUERY_GT_TYPE_MEDIA 1
446	/** @type: GT type: Main or Media */
447	__u16 type;
448	/** @tile_id: Tile ID where this GT lives (Information only) */
449	__u16 tile_id;
450	/** @gt_id: Unique ID of this GT within the PCI Device */
451	__u16 gt_id;
452	/** @pad: MBZ */
453	__u16 pad[3];
454	/** @reference_clock: A clock frequency for timestamp */
455	__u32 reference_clock;
456	/**
457	* @near_mem_regions: Bit mask of instances from
458	* drm_xe_query_mem_regions that are nearest to the current engines
459	* of this GT.
460	* Each index in this mask refers directly to the struct
461	* drm_xe_query_mem_regions' instance, no assumptions should
462	* be made about order. The type of each region is described
463	* by struct drm_xe_query_mem_regions' mem_class.
464	*/
465	__u64 near_mem_regions;
466	/**
467	* @far_mem_regions: Bit mask of instances from
468	* drm_xe_query_mem_regions that are far from the engines of this GT.
469	* In general, they have extra indirections when compared to the
470	* @near_mem_regions. For a discrete device this could mean system
471	* memory and memory living in a different tile.
472	* Each index in this mask refers directly to the struct
473	* drm_xe_query_mem_regions' instance, no assumptions should
474	* be made about order. The type of each region is described
475	* by struct drm_xe_query_mem_regions' mem_class.
476	*/
477	__u64 far_mem_regions;
478	/** @ip_ver_major: Graphics/media IP major version on GMD_ID platforms */
479	__u16 ip_ver_major;
480	/** @ip_ver_minor: Graphics/media IP minor version on GMD_ID platforms */
481	__u16 ip_ver_minor;
482	/** @ip_ver_rev: Graphics/media IP revision version on GMD_ID platforms */
483	__u16 ip_ver_rev;
484	/** @pad2: MBZ */
485	__u16 pad2;
486	/** @reserved: Reserved */
487	__u64 reserved[7];
488	};
489
490	/**
491	* struct drm_xe_query_gt_list - A list with GT description items.
492	*
493	* If a query is made with a struct drm_xe_device_query where .query
494	* is equal to DRM_XE_DEVICE_QUERY_GT_LIST, then the reply uses struct
495	* drm_xe_query_gt_list in .data.
496	*/
497	struct drm_xe_query_gt_list {
498	/** @num_gt: number of GT items returned in gt_list */
499	__u32 num_gt;
500	/** @pad: MBZ */
501	__u32 pad;
502	/** @gt_list: The GT list returned for this device */
503	struct drm_xe_gt gt_list[];
504	};
505
506	/**
507	* struct drm_xe_query_topology_mask - describe the topology mask of a GT
508	*
509	* This is the hardware topology which reflects the internal physical
510	* structure of the GPU.
511	*
512	* If a query is made with a struct drm_xe_device_query where .query
513	* is equal to DRM_XE_DEVICE_QUERY_GT_TOPOLOGY, then the reply uses
514	* struct drm_xe_query_topology_mask in .data.
515	*
516	* The @type can be:
517	* - %DRM_XE_TOPO_DSS_GEOMETRY - To query the mask of Dual Sub Slices
518	* (DSS) available for geometry operations. For example a query response
519	* containing the following in mask:
520	* ``DSS_GEOMETRY ff ff ff ff 00 00 00 00``
521	* means 32 DSS are available for geometry.
522	* - %DRM_XE_TOPO_DSS_COMPUTE - To query the mask of Dual Sub Slices
523	* (DSS) available for compute operations. For example a query response
524	* containing the following in mask:
525	* ``DSS_COMPUTE ff ff ff ff 00 00 00 00``
526	* means 32 DSS are available for compute.
527	* - %DRM_XE_TOPO_L3_BANK - To query the mask of enabled L3 banks. This type
528	* may be omitted if the driver is unable to query the mask from the
529	* hardware.
530	* - %DRM_XE_TOPO_EU_PER_DSS - To query the mask of Execution Units (EU)
531	* available per Dual Sub Slices (DSS). For example a query response
532	* containing the following in mask:
533	* ``EU_PER_DSS ff ff 00 00 00 00 00 00``
534	* means each DSS has 16 SIMD8 EUs. This type may be omitted if device
535	* doesn't have SIMD8 EUs.
536	* - %DRM_XE_TOPO_SIMD16_EU_PER_DSS - To query the mask of SIMD16 Execution
537	* Units (EU) available per Dual Sub Slices (DSS). For example a query
538	* response containing the following in mask:
539	* ``SIMD16_EU_PER_DSS ff ff 00 00 00 00 00 00``
540	* means each DSS has 16 SIMD16 EUs. This type may be omitted if device
541	* doesn't have SIMD16 EUs.
542	*/
543	struct drm_xe_query_topology_mask {
544	/** @gt_id: GT ID the mask is associated with */
545	__u16 gt_id;
546
547	#define DRM_XE_TOPO_DSS_GEOMETRY 1
548	#define DRM_XE_TOPO_DSS_COMPUTE 2
549	#define DRM_XE_TOPO_L3_BANK 3
550	#define DRM_XE_TOPO_EU_PER_DSS 4
551	#define DRM_XE_TOPO_SIMD16_EU_PER_DSS 5
552	/** @type: type of mask */
553	__u16 type;
554
555	/** @num_bytes: number of bytes in requested mask */
556	__u32 num_bytes;
557
558	/** @mask: little-endian mask of @num_bytes */
559	__u8 mask[];
560	};
561
562	/**
563	* struct drm_xe_query_engine_cycles - correlate CPU and GPU timestamps
564	*
565	* If a query is made with a struct drm_xe_device_query where .query is equal to
566	* DRM_XE_DEVICE_QUERY_ENGINE_CYCLES, then the reply uses struct drm_xe_query_engine_cycles
567	* in .data. struct drm_xe_query_engine_cycles is allocated by the user and
568	* .data points to this allocated structure.
569	*
570	* The query returns the engine cycles, which along with GT's @reference_clock,
571	* can be used to calculate the engine timestamp. In addition the
572	* query returns a set of cpu timestamps that indicate when the command
573	* streamer cycle count was captured.
574	*/
575	struct drm_xe_query_engine_cycles {
576	/**
577	* @eci: This is input by the user and is the engine for which command
578	* streamer cycles is queried.
579	*/
580	struct drm_xe_engine_class_instance eci;
581
582	/**
583	* @clockid: This is input by the user and is the reference clock id for
584	* CPU timestamp. For definition, see clock_gettime(2) and
585	* perf_event_open(2). Supported clock ids are CLOCK_MONOTONIC,
586	* CLOCK_MONOTONIC_RAW, CLOCK_REALTIME, CLOCK_BOOTTIME, CLOCK_TAI.
587	*/
588	__s32 clockid;
589
590	/** @width: Width of the engine cycle counter in bits. */
591	__u32 width;
592
593	/**
594	* @engine_cycles: Engine cycles as read from its register
595	* at 0x358 offset.
596	*/
597	__u64 engine_cycles;
598
599	/**
600	* @cpu_timestamp: CPU timestamp in ns. The timestamp is captured before
601	* reading the engine_cycles register using the reference clockid set by the
602	* user.
603	*/
604	__u64 cpu_timestamp;
605
606	/**
607	* @cpu_delta: Time delta in ns captured around reading the lower dword
608	* of the engine_cycles register.
609	*/
610	__u64 cpu_delta;
611	};
612
613	/**
614	* struct drm_xe_query_uc_fw_version - query a micro-controller firmware version
615	*
616	* Given a uc_type this will return the branch, major, minor and patch version
617	* of the micro-controller firmware.
618	*/
619	struct drm_xe_query_uc_fw_version {
620	/** @uc_type: The micro-controller type to query firmware version */
621	#define XE_QUERY_UC_TYPE_GUC_SUBMISSION 0
622	#define XE_QUERY_UC_TYPE_HUC 1
623	__u16 uc_type;
624
625	/** @pad: MBZ */
626	__u16 pad;
627
628	/** @branch_ver: branch uc fw version */
629	__u32 branch_ver;
630	/** @major_ver: major uc fw version */
631	__u32 major_ver;
632	/** @minor_ver: minor uc fw version */
633	__u32 minor_ver;
634	/** @patch_ver: patch uc fw version */
635	__u32 patch_ver;
636
637	/** @pad2: MBZ */
638	__u32 pad2;
639
640	/** @reserved: Reserved */
641	__u64 reserved;
642	};
643
644	/**
645	* struct drm_xe_query_pxp_status - query if PXP is ready
646	*
647	* If PXP is enabled and no fatal error has occurred, the status will be set to
648	* one of the following values:
649	* 0: PXP init still in progress
650	* 1: PXP init complete
651	*
652	* If PXP is not enabled or something has gone wrong, the query will be failed
653	* with one of the following error codes:
654	* -ENODEV: PXP not supported or disabled;
655	* -EIO: fatal error occurred during init, so PXP will never be enabled;
656	* -EINVAL: incorrect value provided as part of the query;
657	* -EFAULT: error copying the memory between kernel and userspace.
658	*
659	* The status can only be 0 in the first few seconds after driver load. If
660	* everything works as expected, the status will transition to init complete in
661	* less than 1 second, while in case of errors the driver might take longer to
662	* start returning an error code, but it should still take less than 10 seconds.
663	*
664	* The supported session type bitmask is based on the values in
665	* enum drm_xe_pxp_session_type. TYPE_NONE is always supported and therefore
666	* is not reported in the bitmask.
667	*
668	*/
669	struct drm_xe_query_pxp_status {
670	/** @status: current PXP status */
671	__u32 status;
672
673	/** @supported_session_types: bitmask of supported PXP session types */
674	__u32 supported_session_types;
675	};
676
677	/**
678	* struct drm_xe_device_query - Input of &DRM_IOCTL_XE_DEVICE_QUERY - main
679	* structure to query device information
680	*
681	* The user selects the type of data to query among DRM_XE_DEVICE_QUERY_*
682	* and sets the value in the query member. This determines the type of
683	* the structure provided by the driver in data, among struct drm_xe_query_*.
684	*
685	* The @query can be:
686	* - %DRM_XE_DEVICE_QUERY_ENGINES
687	* - %DRM_XE_DEVICE_QUERY_MEM_REGIONS
688	* - %DRM_XE_DEVICE_QUERY_CONFIG
689	* - %DRM_XE_DEVICE_QUERY_GT_LIST
690	* - %DRM_XE_DEVICE_QUERY_HWCONFIG - Query type to retrieve the hardware
691	* configuration of the device such as information on slices, memory,
692	* caches, and so on. It is provided as a table of key / value
693	* attributes.
694	* - %DRM_XE_DEVICE_QUERY_GT_TOPOLOGY
695	* - %DRM_XE_DEVICE_QUERY_ENGINE_CYCLES
696	* - %DRM_XE_DEVICE_QUERY_PXP_STATUS
697	*
698	* If size is set to 0, the driver fills it with the required size for
699	* the requested type of data to query. If size is equal to the required
700	* size, the queried information is copied into data. If size is set to
701	* a value different from 0 and different from the required size, the
702	* IOCTL call returns -EINVAL.
703	*
704	* For example the following code snippet allows retrieving and printing
705	* information about the device engines with DRM_XE_DEVICE_QUERY_ENGINES:
706	*
707	* .. code-block:: C
708	*
709	* struct drm_xe_query_engines *engines;
710	* struct drm_xe_device_query query = {
711	* .extensions = 0,
712	* .query = DRM_XE_DEVICE_QUERY_ENGINES,
713	* .size = 0,
714	* .data = 0,
715	* };
716	* ioctl(fd, DRM_IOCTL_XE_DEVICE_QUERY, &query);
717	* engines = malloc(query.size);
718	* query.data = (uintptr_t)engines;
719	* ioctl(fd, DRM_IOCTL_XE_DEVICE_QUERY, &query);
720	* for (int i = 0; i < engines->num_engines; i++) {
721	* printf("Engine %d: %s\n", i,
722	* engines->engines[i].instance.engine_class ==
723	* DRM_XE_ENGINE_CLASS_RENDER ? "RENDER":
724	* engines->engines[i].instance.engine_class ==
725	* DRM_XE_ENGINE_CLASS_COPY ? "COPY":
726	* engines->engines[i].instance.engine_class ==
727	* DRM_XE_ENGINE_CLASS_VIDEO_DECODE ? "VIDEO_DECODE":
728	* engines->engines[i].instance.engine_class ==
729	* DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE ? "VIDEO_ENHANCE":
730	* engines->engines[i].instance.engine_class ==
731	* DRM_XE_ENGINE_CLASS_COMPUTE ? "COMPUTE":
732	* "UNKNOWN");
733	* }
734	* free(engines);
735	*/
736	struct drm_xe_device_query {
737	/** @extensions: Pointer to the first extension struct, if any */
738	__u64 extensions;
739
740	#define DRM_XE_DEVICE_QUERY_ENGINES 0
741	#define DRM_XE_DEVICE_QUERY_MEM_REGIONS 1
742	#define DRM_XE_DEVICE_QUERY_CONFIG 2
743	#define DRM_XE_DEVICE_QUERY_GT_LIST 3
744	#define DRM_XE_DEVICE_QUERY_HWCONFIG 4
745	#define DRM_XE_DEVICE_QUERY_GT_TOPOLOGY 5
746	#define DRM_XE_DEVICE_QUERY_ENGINE_CYCLES 6
747	#define DRM_XE_DEVICE_QUERY_UC_FW_VERSION 7
748	#define DRM_XE_DEVICE_QUERY_OA_UNITS 8
749	#define DRM_XE_DEVICE_QUERY_PXP_STATUS 9
750	#define DRM_XE_DEVICE_QUERY_EU_STALL 10
751	/** @query: The type of data to query */
752	__u32 query;
753
754	/** @size: Size of the queried data */
755	__u32 size;
756
757	/** @data: Queried data is placed here */
758	__u64 data;
759
760	/** @reserved: Reserved */
761	__u64 reserved[2];
762	};
763
764	/**
765	* struct drm_xe_gem_create - Input of &DRM_IOCTL_XE_GEM_CREATE - A structure for
766	* gem creation
767	*
768	* The @flags can be:
769	* - %DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING - Modify the GEM object
770	* allocation strategy by deferring physical memory allocation
771	* until the object is either bound to a virtual memory region via
772	* VM_BIND or accessed by the CPU. As a result, no backing memory is
773	* reserved at the time of GEM object creation.
774	* - %DRM_XE_GEM_CREATE_FLAG_SCANOUT - Indicates that the GEM object is
775	* intended for scanout via the display engine. When set, kernel ensures
776	* that the allocation is placed in a memory region compatible with the
777	* display engine requirements. This may impose restrictions on tiling,
778	* alignment, and memory placement to guarantee proper display functionality.
779	* - %DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM - When using VRAM as a
780	* possible placement, ensure that the corresponding VRAM allocation
781	* will always use the CPU accessible part of VRAM. This is important
782	* for small-bar systems (on full-bar systems this gets turned into a
783	* noop).
784	* Note1: System memory can be used as an extra placement if the kernel
785	* should spill the allocation to system memory, if space can't be made
786	* available in the CPU accessible part of VRAM (giving the same
787	* behaviour as the i915 interface, see
788	* I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS).
789	* Note2: For clear-color CCS surfaces the kernel needs to read the
790	* clear-color value stored in the buffer, and on discrete platforms we
791	* need to use VRAM for display surfaces, therefore the kernel requires
792	* setting this flag for such objects, otherwise an error is thrown on
793	* small-bar systems.
794	*
795	* @cpu_caching supports the following values:
796	* - %DRM_XE_GEM_CPU_CACHING_WB - Allocate the pages with write-back
797	* caching. On iGPU this can't be used for scanout surfaces. Currently
798	* not allowed for objects placed in VRAM.
799	* - %DRM_XE_GEM_CPU_CACHING_WC - Allocate the pages as write-combined. This
800	* is uncached. Scanout surfaces should likely use this. All objects
801	* that can be placed in VRAM must use this.
802	*
803	* This ioctl supports setting the following properties via the
804	* %DRM_XE_GEM_CREATE_EXTENSION_SET_PROPERTY extension, which uses the
805	* generic @drm_xe_ext_set_property struct:
806	*
807	* - %DRM_XE_GEM_CREATE_SET_PROPERTY_PXP_TYPE - set the type of PXP session
808	* this object will be used with. Valid values are listed in enum
809	* drm_xe_pxp_session_type. %DRM_XE_PXP_TYPE_NONE is the default behavior, so
810	* there is no need to explicitly set that. Objects used with session of type
811	* %DRM_XE_PXP_TYPE_HWDRM will be marked as invalid if a PXP invalidation
812	* event occurs after their creation. Attempting to flip an invalid object
813	* will cause a black frame to be displayed instead. Submissions with invalid
814	* objects mapped in the VM will be rejected.
815	*/
816	struct drm_xe_gem_create {
817	#define DRM_XE_GEM_CREATE_EXTENSION_SET_PROPERTY 0
818	#define DRM_XE_GEM_CREATE_SET_PROPERTY_PXP_TYPE 0
819	/** @extensions: Pointer to the first extension struct, if any */
820	__u64 extensions;
821
822	/**
823	* @size: Size of the object to be created, must match region
824	* (system or vram) minimum alignment (&min_page_size).
825	*/
826	__u64 size;
827
828	/**
829	* @placement: A mask of memory instances of where BO can be placed.
830	* Each index in this mask refers directly to the struct
831	* drm_xe_query_mem_regions' instance, no assumptions should
832	* be made about order. The type of each region is described
833	* by struct drm_xe_query_mem_regions' mem_class.
834	*/
835	__u32 placement;
836
837	#define DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING (1 << 0)
838	#define DRM_XE_GEM_CREATE_FLAG_SCANOUT (1 << 1)
839	#define DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM (1 << 2)
840	/**
841	* @flags: Flags, currently a mask of memory instances of where BO can
842	* be placed
843	*/
844	__u32 flags;
845
846	/**
847	* @vm_id: Attached VM, if any
848	*
849	* If a VM is specified, this BO must:
850	*
851	* 1. Only ever be bound to that VM.
852	* 2. Cannot be exported as a PRIME fd.
853	*/
854	__u32 vm_id;
855
856	/**
857	* @handle: Returned handle for the object.
858	*
859	* Object handles are nonzero.
860	*/
861	__u32 handle;
862
863	#define DRM_XE_GEM_CPU_CACHING_WB 1
864	#define DRM_XE_GEM_CPU_CACHING_WC 2
865	/**
866	* @cpu_caching: The CPU caching mode to select for this object. If
867	* mmaping the object the mode selected here will also be used. The
868	* exception is when mapping system memory (including data evicted
869	* to system) on discrete GPUs. The caching mode selected will
870	* then be overridden to DRM_XE_GEM_CPU_CACHING_WB, and coherency
871	* between GPU- and CPU is guaranteed. The caching mode of
872	* existing CPU-mappings will be updated transparently to
873	* user-space clients.
874	*/
875	__u16 cpu_caching;
876	/** @pad: MBZ */
877	__u16 pad[3];
878
879	/** @reserved: Reserved */
880	__u64 reserved[2];
881	};
882
883	/**
884	* struct drm_xe_gem_mmap_offset - Input of &DRM_IOCTL_XE_GEM_MMAP_OFFSET
885	*
886	* The @flags can be:
887	* - %DRM_XE_MMAP_OFFSET_FLAG_PCI_BARRIER - For user to query special offset
888	* for use in mmap ioctl. Writing to the returned mmap address will generate a
889	* PCI memory barrier with low overhead (avoiding IOCTL call as well as writing
890	* to VRAM which would also add overhead), acting like an MI_MEM_FENCE
891	* instruction.
892	*
893	* Note: The mmap size can be at most 4K, due to HW limitations. As a result
894	* this interface is only supported on CPU architectures that support 4K page
895	* size. The mmap_offset ioctl will detect this and gracefully return an
896	* error, where userspace is expected to have a different fallback method for
897	* triggering a barrier.
898	*
899	* Roughly the usage would be as follows:
900	*
901	* .. code-block:: C
902	*
903	* struct drm_xe_gem_mmap_offset mmo = {
904	* .handle = 0, // must be set to 0
905	* .flags = DRM_XE_MMAP_OFFSET_FLAG_PCI_BARRIER,
906	* };
907	*
908	* err = ioctl(fd, DRM_IOCTL_XE_GEM_MMAP_OFFSET, &mmo);
909	* map = mmap(NULL, size, PROT_WRITE, MAP_SHARED, fd, mmo.offset);
910	* map[i] = 0xdeadbeaf; // issue barrier
911	*/
912	struct drm_xe_gem_mmap_offset {
913	/** @extensions: Pointer to the first extension struct, if any */
914	__u64 extensions;
915
916	/** @handle: Handle for the object being mapped. */
917	__u32 handle;
918
919	#define DRM_XE_MMAP_OFFSET_FLAG_PCI_BARRIER (1 << 0)
920	/** @flags: Flags */
921	__u32 flags;
922
923	/** @offset: The fake offset to use for subsequent mmap call */
924	__u64 offset;
925
926	/** @reserved: Reserved */
927	__u64 reserved[2];
928	};
929
930	/**
931	* struct drm_xe_vm_create - Input of &DRM_IOCTL_XE_VM_CREATE
932	*
933	* The @flags can be:
934	* - %DRM_XE_VM_CREATE_FLAG_SCRATCH_PAGE - Map the whole virtual address
935	* space of the VM to scratch page. A vm_bind would overwrite the scratch
936	* page mapping. This flag is mutually exclusive with the
937	* %DRM_XE_VM_CREATE_FLAG_FAULT_MODE flag, with an exception of on x2 and
938	* xe3 platform.
939	* - %DRM_XE_VM_CREATE_FLAG_LR_MODE - An LR, or Long Running VM accepts
940	* exec submissions to its exec_queues that don't have an upper time
941	* limit on the job execution time. But exec submissions to these
942	* don't allow any of the sync types DRM_XE_SYNC_TYPE_SYNCOBJ,
943	* DRM_XE_SYNC_TYPE_TIMELINE_SYNCOBJ, used as out-syncobjs, that is,
944	* together with sync flag DRM_XE_SYNC_FLAG_SIGNAL.
945	* LR VMs can be created in recoverable page-fault mode using
946	* DRM_XE_VM_CREATE_FLAG_FAULT_MODE, if the device supports it.
947	* If that flag is omitted, the UMD can not rely on the slightly
948	* different per-VM overcommit semantics that are enabled by
949	* DRM_XE_VM_CREATE_FLAG_FAULT_MODE (see below), but KMD may
950	* still enable recoverable pagefaults if supported by the device.
951	* - %DRM_XE_VM_CREATE_FLAG_FAULT_MODE - Requires also
952	* DRM_XE_VM_CREATE_FLAG_LR_MODE. It allows memory to be allocated on
953	* demand when accessed, and also allows per-VM overcommit of memory.
954	* The xe driver internally uses recoverable pagefaults to implement
955	* this.
956	*/
957	struct drm_xe_vm_create {
958	/** @extensions: Pointer to the first extension struct, if any */
959	__u64 extensions;
960
961	#define DRM_XE_VM_CREATE_FLAG_SCRATCH_PAGE (1 << 0)
962	#define DRM_XE_VM_CREATE_FLAG_LR_MODE (1 << 1)
963	#define DRM_XE_VM_CREATE_FLAG_FAULT_MODE (1 << 2)
964	/** @flags: Flags */
965	__u32 flags;
966
967	/** @vm_id: Returned VM ID */
968	__u32 vm_id;
969
970	/** @reserved: Reserved */
971	__u64 reserved[2];
972	};
973
974	/**
975	* struct drm_xe_vm_destroy - Input of &DRM_IOCTL_XE_VM_DESTROY
976	*/
977	struct drm_xe_vm_destroy {
978	/** @vm_id: VM ID */
979	__u32 vm_id;
980
981	/** @pad: MBZ */
982	__u32 pad;
983
984	/** @reserved: Reserved */
985	__u64 reserved[2];
986	};
987
988	/**
989	* struct drm_xe_vm_bind_op - run bind operations
990	*
991	* The @op can be:
992	* - %DRM_XE_VM_BIND_OP_MAP
993	* - %DRM_XE_VM_BIND_OP_UNMAP
994	* - %DRM_XE_VM_BIND_OP_MAP_USERPTR
995	* - %DRM_XE_VM_BIND_OP_UNMAP_ALL
996	* - %DRM_XE_VM_BIND_OP_PREFETCH
997	*
998	* and the @flags can be:
999	* - %DRM_XE_VM_BIND_FLAG_READONLY - Setup the page tables as read-only
1000	* to ensure write protection
1001	* - %DRM_XE_VM_BIND_FLAG_IMMEDIATE - On a faulting VM, do the
1002	* MAP operation immediately rather than deferring the MAP to the page
1003	* fault handler. This is implied on a non-faulting VM as there is no
1004	* fault handler to defer to.
1005	* - %DRM_XE_VM_BIND_FLAG_NULL - When the NULL flag is set, the page
1006	* tables are setup with a special bit which indicates writes are
1007	* dropped and all reads return zero. In the future, the NULL flags
1008	* will only be valid for DRM_XE_VM_BIND_OP_MAP operations, the BO
1009	* handle MBZ, and the BO offset MBZ. This flag is intended to
1010	* implement VK sparse bindings.
1011	* - %DRM_XE_VM_BIND_FLAG_CHECK_PXP - If the object is encrypted via PXP,
1012	* reject the binding if the encryption key is no longer valid. This
1013	* flag has no effect on BOs that are not marked as using PXP.
1014	* - %DRM_XE_VM_BIND_FLAG_CPU_ADDR_MIRROR - When the CPU address mirror flag is
1015	* set, no mappings are created rather the range is reserved for CPU address
1016	* mirroring which will be populated on GPU page faults or prefetches. Only
1017	* valid on VMs with DRM_XE_VM_CREATE_FLAG_FAULT_MODE set. The CPU address
1018	* mirror flag are only valid for DRM_XE_VM_BIND_OP_MAP operations, the BO
1019	* handle MBZ, and the BO offset MBZ.
1020	* - %DRM_XE_VM_BIND_FLAG_MADVISE_AUTORESET - Can be used in combination with
1021	* %DRM_XE_VM_BIND_FLAG_CPU_ADDR_MIRROR to reset madvises when the underlying
1022	* CPU address space range is unmapped (typically with munmap(2) or brk(2)).
1023	* The madvise values set with &DRM_IOCTL_XE_MADVISE are reset to the values
1024	* that were present immediately after the &DRM_IOCTL_XE_VM_BIND.
1025	* The reset GPU virtual address range is the intersection of the range bound
1026	* using &DRM_IOCTL_XE_VM_BIND and the virtual CPU address space range
1027	* unmapped.
1028	* This functionality is present to mimic the behaviour of CPU address space
1029	* madvises set using madvise(2), which are typically reset on unmap.
1030	* Note: free(3) may or may not call munmap(2) and/or brk(2), and may thus
1031	* not invoke autoreset. Neither will stack variables going out of scope.
1032	* Therefore it's recommended to always explicitly reset the madvises when
1033	* freeing the memory backing a region used in a &DRM_IOCTL_XE_MADVISE call.
1034	*
1035	* The @prefetch_mem_region_instance for %DRM_XE_VM_BIND_OP_PREFETCH can also be:
1036	* - %DRM_XE_CONSULT_MEM_ADVISE_PREF_LOC, which ensures prefetching occurs in
1037	* the memory region advised by madvise.
1038	*/
1039	struct drm_xe_vm_bind_op {
1040	/** @extensions: Pointer to the first extension struct, if any */
1041	__u64 extensions;
1042
1043	/**
1044	* @obj: GEM object to operate on, MBZ for MAP_USERPTR, MBZ for UNMAP
1045	*/
1046	__u32 obj;
1047
1048	/**
1049	* @pat_index: The platform defined @pat_index to use for this mapping.
1050	* The index basically maps to some predefined memory attributes,
1051	* including things like caching, coherency, compression etc. The exact
1052	* meaning of the pat_index is platform specific and defined in the
1053	* Bspec and PRMs. When the KMD sets up the binding the index here is
1054	* encoded into the ppGTT PTE.
1055	*
1056	* For coherency the @pat_index needs to be at least 1way coherent when
1057	* drm_xe_gem_create.cpu_caching is DRM_XE_GEM_CPU_CACHING_WB. The KMD
1058	* will extract the coherency mode from the @pat_index and reject if
1059	* there is a mismatch (see note below for pre-MTL platforms).
1060	*
1061	* Note: On pre-MTL platforms there is only a caching mode and no
1062	* explicit coherency mode, but on such hardware there is always a
1063	* shared-LLC (or is dgpu) so all GT memory accesses are coherent with
1064	* CPU caches even with the caching mode set as uncached. It's only the
1065	* display engine that is incoherent (on dgpu it must be in VRAM which
1066	* is always mapped as WC on the CPU). However to keep the uapi somewhat
1067	* consistent with newer platforms the KMD groups the different cache
1068	* levels into the following coherency buckets on all pre-MTL platforms:
1069	*
1070	* ppGTT UC -> COH_NONE
1071	* ppGTT WC -> COH_NONE
1072	* ppGTT WT -> COH_NONE
1073	* ppGTT WB -> COH_AT_LEAST_1WAY
1074	*
1075	* In practice UC/WC/WT should only ever used for scanout surfaces on
1076	* such platforms (or perhaps in general for dma-buf if shared with
1077	* another device) since it is only the display engine that is actually
1078	* incoherent. Everything else should typically use WB given that we
1079	* have a shared-LLC. On MTL+ this completely changes and the HW
1080	* defines the coherency mode as part of the @pat_index, where
1081	* incoherent GT access is possible.
1082	*
1083	* Note: For userptr and externally imported dma-buf the kernel expects
1084	* either 1WAY or 2WAY for the @pat_index.
1085	*
1086	* For DRM_XE_VM_BIND_FLAG_NULL bindings there are no KMD restrictions
1087	* on the @pat_index. For such mappings there is no actual memory being
1088	* mapped (the address in the PTE is invalid), so the various PAT memory
1089	* attributes likely do not apply. Simply leaving as zero is one
1090	* option (still a valid pat_index). Same applies to
1091	* DRM_XE_VM_BIND_FLAG_CPU_ADDR_MIRROR bindings as for such mapping
1092	* there is no actual memory being mapped.
1093	*/
1094	__u16 pat_index;
1095
1096	/** @pad: MBZ */
1097	__u16 pad;
1098
1099	union {
1100	/**
1101	* @obj_offset: Offset into the object, MBZ for CLEAR_RANGE,
1102	* ignored for unbind
1103	*/
1104	__u64 obj_offset;
1105
1106	/** @userptr: user pointer to bind on */
1107	__u64 userptr;
1108
1109	/**
1110	* @cpu_addr_mirror_offset: Offset from GPU @addr to create
1111	* CPU address mirror mappings. MBZ with current level of
1112	* support (e.g. 1 to 1 mapping between GPU and CPU mappings
1113	* only supported).
1114	*/
1115	__s64 cpu_addr_mirror_offset;
1116	};
1117
1118	/**
1119	* @range: Number of bytes from the object to bind to addr, MBZ for UNMAP_ALL
1120	*/
1121	__u64 range;
1122
1123	/** @addr: Address to operate on, MBZ for UNMAP_ALL */
1124	__u64 addr;
1125
1126	#define DRM_XE_VM_BIND_OP_MAP 0x0
1127	#define DRM_XE_VM_BIND_OP_UNMAP 0x1
1128	#define DRM_XE_VM_BIND_OP_MAP_USERPTR 0x2
1129	#define DRM_XE_VM_BIND_OP_UNMAP_ALL 0x3
1130	#define DRM_XE_VM_BIND_OP_PREFETCH 0x4
1131	/** @op: Bind operation to perform */
1132	__u32 op;
1133
1134	#define DRM_XE_VM_BIND_FLAG_READONLY (1 << 0)
1135	#define DRM_XE_VM_BIND_FLAG_IMMEDIATE (1 << 1)
1136	#define DRM_XE_VM_BIND_FLAG_NULL (1 << 2)
1137	#define DRM_XE_VM_BIND_FLAG_DUMPABLE (1 << 3)
1138	#define DRM_XE_VM_BIND_FLAG_CHECK_PXP (1 << 4)
1139	#define DRM_XE_VM_BIND_FLAG_CPU_ADDR_MIRROR (1 << 5)
1140	#define DRM_XE_VM_BIND_FLAG_MADVISE_AUTORESET (1 << 6)
1141	/** @flags: Bind flags */
1142	__u32 flags;
1143
1144	#define DRM_XE_CONSULT_MEM_ADVISE_PREF_LOC -1
1145	/**
1146	* @prefetch_mem_region_instance: Memory region to prefetch VMA to.
1147	* It is a region instance, not a mask.
1148	* To be used only with %DRM_XE_VM_BIND_OP_PREFETCH operation.
1149	*/
1150	__u32 prefetch_mem_region_instance;
1151
1152	/** @pad2: MBZ */
1153	__u32 pad2;
1154
1155	/** @reserved: Reserved */
1156	__u64 reserved[3];
1157	};
1158
1159	/**
1160	* struct drm_xe_vm_bind - Input of &DRM_IOCTL_XE_VM_BIND
1161	*
1162	* Below is an example of a minimal use of @drm_xe_vm_bind to
1163	* asynchronously bind the buffer `data` at address `BIND_ADDRESS` to
1164	* illustrate `userptr`. It can be synchronized by using the example
1165	* provided for @drm_xe_sync.
1166	*
1167	* .. code-block:: C
1168	*
1169	* data = aligned_alloc(ALIGNMENT, BO_SIZE);
1170	* struct drm_xe_vm_bind bind = {
1171	* .vm_id = vm,
1172	* .num_binds = 1,
1173	* .bind.obj = 0,
1174	* .bind.obj_offset = to_user_pointer(data),
1175	* .bind.range = BO_SIZE,
1176	* .bind.addr = BIND_ADDRESS,
1177	* .bind.op = DRM_XE_VM_BIND_OP_MAP_USERPTR,
1178	* .bind.flags = 0,
1179	* .num_syncs = 1,
1180	* .syncs = &sync,
1181	* .exec_queue_id = 0,
1182	* };
1183	* ioctl(fd, DRM_IOCTL_XE_VM_BIND, &bind);
1184	*
1185	*/
1186	struct drm_xe_vm_bind {
1187	/** @extensions: Pointer to the first extension struct, if any */
1188	__u64 extensions;
1189
1190	/** @vm_id: The ID of the VM to bind to */
1191	__u32 vm_id;
1192
1193	/**
1194	* @exec_queue_id: exec_queue_id, must be of class DRM_XE_ENGINE_CLASS_VM_BIND
1195	* and exec queue must have same vm_id. If zero, the default VM bind engine
1196	* is used.
1197	*/
1198	__u32 exec_queue_id;
1199
1200	/** @pad: MBZ */
1201	__u32 pad;
1202
1203	/** @num_binds: number of binds in this IOCTL */
1204	__u32 num_binds;
1205
1206	union {
1207	/** @bind: used if num_binds == 1 */
1208	struct drm_xe_vm_bind_op bind;
1209
1210	/**
1211	* @vector_of_binds: userptr to array of struct
1212	* drm_xe_vm_bind_op if num_binds > 1
1213	*/
1214	__u64 vector_of_binds;
1215	};
1216
1217	/** @pad2: MBZ */
1218	__u32 pad2;
1219
1220	/** @num_syncs: amount of syncs to wait on */
1221	__u32 num_syncs;
1222
1223	/** @syncs: pointer to struct drm_xe_sync array */
1224	__u64 syncs;
1225
1226	/** @reserved: Reserved */
1227	__u64 reserved[2];
1228	};
1229
1230	/**
1231	* struct drm_xe_exec_queue_create - Input of &DRM_IOCTL_XE_EXEC_QUEUE_CREATE
1232	*
1233	* This ioctl supports setting the following properties via the
1234	* %DRM_XE_EXEC_QUEUE_EXTENSION_SET_PROPERTY extension, which uses the
1235	* generic @drm_xe_ext_set_property struct:
1236	*
1237	* - %DRM_XE_EXEC_QUEUE_SET_PROPERTY_PRIORITY - set the queue priority.
1238	* CAP_SYS_NICE is required to set a value above normal.
1239	* - %DRM_XE_EXEC_QUEUE_SET_PROPERTY_TIMESLICE - set the queue timeslice
1240	* duration in microseconds.
1241	* - %DRM_XE_EXEC_QUEUE_SET_PROPERTY_PXP_TYPE - set the type of PXP session
1242	* this queue will be used with. Valid values are listed in enum
1243	* drm_xe_pxp_session_type. %DRM_XE_PXP_TYPE_NONE is the default behavior, so
1244	* there is no need to explicitly set that. When a queue of type
1245	* %DRM_XE_PXP_TYPE_HWDRM is created, the PXP default HWDRM session
1246	* (%XE_PXP_HWDRM_DEFAULT_SESSION) will be started, if isn't already running.
1247	* The user is expected to query the PXP status via the query ioctl (see
1248	* %DRM_XE_DEVICE_QUERY_PXP_STATUS) and to wait for PXP to be ready before
1249	* attempting to create a queue with this property. When a queue is created
1250	* before PXP is ready, the ioctl will return -EBUSY if init is still in
1251	* progress or -EIO if init failed.
1252	* Given that going into a power-saving state kills PXP HWDRM sessions,
1253	* runtime PM will be blocked while queues of this type are alive.
1254	* All PXP queues will be killed if a PXP invalidation event occurs.
1255	*
1256	* The example below shows how to use @drm_xe_exec_queue_create to create
1257	* a simple exec_queue (no parallel submission) of class
1258	* &DRM_XE_ENGINE_CLASS_RENDER.
1259	*
1260	* .. code-block:: C
1261	*
1262	* struct drm_xe_engine_class_instance instance = {
1263	* .engine_class = DRM_XE_ENGINE_CLASS_RENDER,
1264	* };
1265	* struct drm_xe_exec_queue_create exec_queue_create = {
1266	* .extensions = 0,
1267	* .vm_id = vm,
1268	* .num_bb_per_exec = 1,
1269	* .num_eng_per_bb = 1,
1270	* .instances = to_user_pointer(&instance),
1271	* };
1272	* ioctl(fd, DRM_IOCTL_XE_EXEC_QUEUE_CREATE, &exec_queue_create);
1273	*
1274	* Allow users to provide a hint to kernel for cases demanding low latency
1275	* profile. Please note it will have impact on power consumption. User can
1276	* indicate low latency hint with flag while creating exec queue as
1277	* mentioned below,
1278	*
1279	* struct drm_xe_exec_queue_create exec_queue_create = {
1280	* .flags = DRM_XE_EXEC_QUEUE_LOW_LATENCY_HINT,
1281	* .extensions = 0,
1282	* .vm_id = vm,
1283	* .num_bb_per_exec = 1,
1284	* .num_eng_per_bb = 1,
1285	* .instances = to_user_pointer(&instance),
1286	* };
1287	* ioctl(fd, DRM_IOCTL_XE_EXEC_QUEUE_CREATE, &exec_queue_create);
1288	*
1289	*/
1290	struct drm_xe_exec_queue_create {
1291	#define DRM_XE_EXEC_QUEUE_EXTENSION_SET_PROPERTY 0
1292	#define DRM_XE_EXEC_QUEUE_SET_PROPERTY_PRIORITY 0
1293	#define DRM_XE_EXEC_QUEUE_SET_PROPERTY_TIMESLICE 1
1294	#define DRM_XE_EXEC_QUEUE_SET_PROPERTY_PXP_TYPE 2
1295	/** @extensions: Pointer to the first extension struct, if any */
1296	__u64 extensions;
1297
1298	/** @width: submission width (number BB per exec) for this exec queue */
1299	__u16 width;
1300
1301	/** @num_placements: number of valid placements for this exec queue */
1302	__u16 num_placements;
1303
1304	/** @vm_id: VM to use for this exec queue */
1305	__u32 vm_id;
1306
1307	#define DRM_XE_EXEC_QUEUE_LOW_LATENCY_HINT (1 << 0)
1308	/** @flags: flags to use for this exec queue */
1309	__u32 flags;
1310
1311	/** @exec_queue_id: Returned exec queue ID */
1312	__u32 exec_queue_id;
1313
1314	/**
1315	* @instances: user pointer to a 2-d array of struct
1316	* drm_xe_engine_class_instance
1317	*
1318	* length = width (i) * num_placements (j)
1319	* index = j + i * width
1320	*/
1321	__u64 instances;
1322
1323	/** @reserved: Reserved */
1324	__u64 reserved[2];
1325	};
1326
1327	/**
1328	* struct drm_xe_exec_queue_destroy - Input of &DRM_IOCTL_XE_EXEC_QUEUE_DESTROY
1329	*/
1330	struct drm_xe_exec_queue_destroy {
1331	/** @exec_queue_id: Exec queue ID */
1332	__u32 exec_queue_id;
1333
1334	/** @pad: MBZ */
1335	__u32 pad;
1336
1337	/** @reserved: Reserved */
1338	__u64 reserved[2];
1339	};
1340
1341	/**
1342	* struct drm_xe_exec_queue_get_property - Input of &DRM_IOCTL_XE_EXEC_QUEUE_GET_PROPERTY
1343	*
1344	* The @property can be:
1345	* - %DRM_XE_EXEC_QUEUE_GET_PROPERTY_BAN
1346	*/
1347	struct drm_xe_exec_queue_get_property {
1348	/** @extensions: Pointer to the first extension struct, if any */
1349	__u64 extensions;
1350
1351	/** @exec_queue_id: Exec queue ID */
1352	__u32 exec_queue_id;
1353
1354	#define DRM_XE_EXEC_QUEUE_GET_PROPERTY_BAN 0
1355	/** @property: property to get */
1356	__u32 property;
1357
1358	/** @value: property value */
1359	__u64 value;
1360
1361	/** @reserved: Reserved */
1362	__u64 reserved[2];
1363	};
1364
1365	/**
1366	* struct drm_xe_sync - sync object
1367	*
1368	* The @type can be:
1369	* - %DRM_XE_SYNC_TYPE_SYNCOBJ
1370	* - %DRM_XE_SYNC_TYPE_TIMELINE_SYNCOBJ
1371	* - %DRM_XE_SYNC_TYPE_USER_FENCE
1372	*
1373	* and the @flags can be:
1374	* - %DRM_XE_SYNC_FLAG_SIGNAL
1375	*
1376	* A minimal use of @drm_xe_sync looks like this:
1377	*
1378	* .. code-block:: C
1379	*
1380	* struct drm_xe_sync sync = {
1381	* .flags = DRM_XE_SYNC_FLAG_SIGNAL,
1382	* .type = DRM_XE_SYNC_TYPE_SYNCOBJ,
1383	* };
1384	* struct drm_syncobj_create syncobj_create = { 0 };
1385	* ioctl(fd, DRM_IOCTL_SYNCOBJ_CREATE, &syncobj_create);
1386	* sync.handle = syncobj_create.handle;
1387	* ...
1388	* use of &sync in drm_xe_exec or drm_xe_vm_bind
1389	* ...
1390	* struct drm_syncobj_wait wait = {
1391	* .handles = &sync.handle,
1392	* .timeout_nsec = INT64_MAX,
1393	* .count_handles = 1,
1394	* .flags = 0,
1395	* .first_signaled = 0,
1396	* .pad = 0,
1397	* };
1398	* ioctl(fd, DRM_IOCTL_SYNCOBJ_WAIT, &wait);
1399	*/
1400	struct drm_xe_sync {
1401	/** @extensions: Pointer to the first extension struct, if any */
1402	__u64 extensions;
1403
1404	#define DRM_XE_SYNC_TYPE_SYNCOBJ 0x0
1405	#define DRM_XE_SYNC_TYPE_TIMELINE_SYNCOBJ 0x1
1406	#define DRM_XE_SYNC_TYPE_USER_FENCE 0x2
1407	/** @type: Type of the this sync object */
1408	__u32 type;
1409
1410	#define DRM_XE_SYNC_FLAG_SIGNAL (1 << 0)
1411	/** @flags: Sync Flags */
1412	__u32 flags;
1413
1414	union {
1415	/** @handle: Handle for the object */
1416	__u32 handle;
1417
1418	/**
1419	* @addr: Address of user fence. When sync is passed in via exec
1420	* IOCTL this is a GPU address in the VM. When sync passed in via
1421	* VM bind IOCTL this is a user pointer. In either case, it is
1422	* the users responsibility that this address is present and
1423	* mapped when the user fence is signalled. Must be qword
1424	* aligned.
1425	*/
1426	__u64 addr;
1427	};
1428
1429	/**
1430	* @timeline_value: Input for the timeline sync object. Needs to be
1431	* different than 0 when used with %DRM_XE_SYNC_TYPE_TIMELINE_SYNCOBJ.
1432	*/
1433	__u64 timeline_value;
1434
1435	/** @reserved: Reserved */
1436	__u64 reserved[2];
1437	};
1438
1439	/**
1440	* struct drm_xe_exec - Input of &DRM_IOCTL_XE_EXEC
1441	*
1442	* This is an example to use @drm_xe_exec for execution of the object
1443	* at BIND_ADDRESS (see example in @drm_xe_vm_bind) by an exec_queue
1444	* (see example in @drm_xe_exec_queue_create). It can be synchronized
1445	* by using the example provided for @drm_xe_sync.
1446	*
1447	* .. code-block:: C
1448	*
1449	* struct drm_xe_exec exec = {
1450	* .exec_queue_id = exec_queue,
1451	* .syncs = &sync,
1452	* .num_syncs = 1,
1453	* .address = BIND_ADDRESS,
1454	* .num_batch_buffer = 1,
1455	* };
1456	* ioctl(fd, DRM_IOCTL_XE_EXEC, &exec);
1457	*
1458	*/
1459	struct drm_xe_exec {
1460	/** @extensions: Pointer to the first extension struct, if any */
1461	__u64 extensions;
1462
1463	/** @exec_queue_id: Exec queue ID for the batch buffer */
1464	__u32 exec_queue_id;
1465
1466	#define DRM_XE_MAX_SYNCS 1024
1467	/** @num_syncs: Amount of struct drm_xe_sync in array. */
1468	__u32 num_syncs;
1469
1470	/** @syncs: Pointer to struct drm_xe_sync array. */
1471	__u64 syncs;
1472
1473	/**
1474	* @address: address of batch buffer if num_batch_buffer == 1 or an
1475	* array of batch buffer addresses
1476	*/
1477	__u64 address;
1478
1479	/**
1480	* @num_batch_buffer: number of batch buffer in this exec, must match
1481	* the width of the engine
1482	*/
1483	__u16 num_batch_buffer;
1484
1485	/** @pad: MBZ */
1486	__u16 pad[3];
1487
1488	/** @reserved: Reserved */
1489	__u64 reserved[2];
1490	};
1491
1492	/**
1493	* struct drm_xe_wait_user_fence - Input of &DRM_IOCTL_XE_WAIT_USER_FENCE
1494	*
1495	* Wait on user fence, XE will wake-up on every HW engine interrupt in the
1496	* instances list and check if user fence is complete::
1497	*
1498	* (*addr & MASK) OP (VALUE & MASK)
1499	*
1500	* Returns to user on user fence completion or timeout.
1501	*
1502	* The @op can be:
1503	* - %DRM_XE_UFENCE_WAIT_OP_EQ
1504	* - %DRM_XE_UFENCE_WAIT_OP_NEQ
1505	* - %DRM_XE_UFENCE_WAIT_OP_GT
1506	* - %DRM_XE_UFENCE_WAIT_OP_GTE
1507	* - %DRM_XE_UFENCE_WAIT_OP_LT
1508	* - %DRM_XE_UFENCE_WAIT_OP_LTE
1509	*
1510	* and the @flags can be:
1511	* - %DRM_XE_UFENCE_WAIT_FLAG_ABSTIME
1512	* - %DRM_XE_UFENCE_WAIT_FLAG_SOFT_OP
1513	*
1514	* The @mask values can be for example:
1515	* - 0xffu for u8
1516	* - 0xffffu for u16
1517	* - 0xffffffffu for u32
1518	* - 0xffffffffffffffffu for u64
1519	*/
1520	struct drm_xe_wait_user_fence {
1521	/** @extensions: Pointer to the first extension struct, if any */
1522	__u64 extensions;
1523
1524	/**
1525	* @addr: user pointer address to wait on, must qword aligned
1526	*/
1527	__u64 addr;
1528
1529	#define DRM_XE_UFENCE_WAIT_OP_EQ 0x0
1530	#define DRM_XE_UFENCE_WAIT_OP_NEQ 0x1
1531	#define DRM_XE_UFENCE_WAIT_OP_GT 0x2
1532	#define DRM_XE_UFENCE_WAIT_OP_GTE 0x3
1533	#define DRM_XE_UFENCE_WAIT_OP_LT 0x4
1534	#define DRM_XE_UFENCE_WAIT_OP_LTE 0x5
1535	/** @op: wait operation (type of comparison) */
1536	__u16 op;
1537
1538	#define DRM_XE_UFENCE_WAIT_FLAG_ABSTIME (1 << 0)
1539	/** @flags: wait flags */
1540	__u16 flags;
1541
1542	/** @pad: MBZ */
1543	__u32 pad;
1544
1545	/** @value: compare value */
1546	__u64 value;
1547
1548	/** @mask: comparison mask */
1549	__u64 mask;
1550
1551	/**
1552	* @timeout: how long to wait before bailing, value in nanoseconds.
1553	* Without DRM_XE_UFENCE_WAIT_FLAG_ABSTIME flag set (relative timeout)
1554	* it contains timeout expressed in nanoseconds to wait (fence will
1555	* expire at now() + timeout).
1556	* When DRM_XE_UFENCE_WAIT_FLAG_ABSTIME flat is set (absolute timeout) wait
1557	* will end at timeout (uses system MONOTONIC_CLOCK).
1558	* Passing negative timeout leads to neverending wait.
1559	*
1560	* On relative timeout this value is updated with timeout left
1561	* (for restarting the call in case of signal delivery).
1562	* On absolute timeout this value stays intact (restarted call still
1563	* expire at the same point of time).
1564	*/
1565	__s64 timeout;
1566
1567	/** @exec_queue_id: exec_queue_id returned from xe_exec_queue_create_ioctl */
1568	__u32 exec_queue_id;
1569
1570	/** @pad2: MBZ */
1571	__u32 pad2;
1572
1573	/** @reserved: Reserved */
1574	__u64 reserved[2];
1575	};
1576
1577	/**
1578	* enum drm_xe_observation_type - Observation stream types
1579	*/
1580	enum drm_xe_observation_type {
1581	/** @DRM_XE_OBSERVATION_TYPE_OA: OA observation stream type */
1582	DRM_XE_OBSERVATION_TYPE_OA,
1583	/** @DRM_XE_OBSERVATION_TYPE_EU_STALL: EU stall sampling observation stream type */
1584	DRM_XE_OBSERVATION_TYPE_EU_STALL,
1585	};
1586
1587	/**
1588	* enum drm_xe_observation_op - Observation stream ops
1589	*/
1590	enum drm_xe_observation_op {
1591	/** @DRM_XE_OBSERVATION_OP_STREAM_OPEN: Open an observation stream */
1592	DRM_XE_OBSERVATION_OP_STREAM_OPEN,
1593
1594	/** @DRM_XE_OBSERVATION_OP_ADD_CONFIG: Add observation stream config */
1595	DRM_XE_OBSERVATION_OP_ADD_CONFIG,
1596
1597	/** @DRM_XE_OBSERVATION_OP_REMOVE_CONFIG: Remove observation stream config */
1598	DRM_XE_OBSERVATION_OP_REMOVE_CONFIG,
1599	};
1600
1601	/**
1602	* struct drm_xe_observation_param - Input of &DRM_XE_OBSERVATION
1603	*
1604	* The observation layer enables multiplexing observation streams of
1605	* multiple types. The actual params for a particular stream operation are
1606	* supplied via the @param pointer (use __copy_from_user to get these
1607	* params).
1608	*/
1609	struct drm_xe_observation_param {
1610	/** @extensions: Pointer to the first extension struct, if any */
1611	__u64 extensions;
1612	/** @observation_type: observation stream type, of enum @drm_xe_observation_type */
1613	__u64 observation_type;
1614	/** @observation_op: observation stream op, of enum @drm_xe_observation_op */
1615	__u64 observation_op;
1616	/** @param: Pointer to actual stream params */
1617	__u64 param;
1618	};
1619
1620	/**
1621	* enum drm_xe_observation_ioctls - Observation stream fd ioctl's
1622	*
1623	* Information exchanged between userspace and kernel for observation fd
1624	* ioctl's is stream type specific
1625	*/
1626	enum drm_xe_observation_ioctls {
1627	/** @DRM_XE_OBSERVATION_IOCTL_ENABLE: Enable data capture for an observation stream */
1628	DRM_XE_OBSERVATION_IOCTL_ENABLE = _IO('i', 0x0),
1629
1630	/** @DRM_XE_OBSERVATION_IOCTL_DISABLE: Disable data capture for a observation stream */
1631	DRM_XE_OBSERVATION_IOCTL_DISABLE = _IO('i', 0x1),
1632
1633	/** @DRM_XE_OBSERVATION_IOCTL_CONFIG: Change observation stream configuration */
1634	DRM_XE_OBSERVATION_IOCTL_CONFIG = _IO('i', 0x2),
1635
1636	/** @DRM_XE_OBSERVATION_IOCTL_STATUS: Return observation stream status */
1637	DRM_XE_OBSERVATION_IOCTL_STATUS = _IO('i', 0x3),
1638
1639	/** @DRM_XE_OBSERVATION_IOCTL_INFO: Return observation stream info */
1640	DRM_XE_OBSERVATION_IOCTL_INFO = _IO('i', 0x4),
1641	};
1642
1643	/**
1644	* enum drm_xe_oa_unit_type - OA unit types
1645	*/
1646	enum drm_xe_oa_unit_type {
1647	/**
1648	* @DRM_XE_OA_UNIT_TYPE_OAG: OAG OA unit. OAR/OAC are considered
1649	* sub-types of OAG. For OAR/OAC, use OAG.
1650	*/
1651	DRM_XE_OA_UNIT_TYPE_OAG,
1652
1653	/** @DRM_XE_OA_UNIT_TYPE_OAM: OAM OA unit */
1654	DRM_XE_OA_UNIT_TYPE_OAM,
1655
1656	/** @DRM_XE_OA_UNIT_TYPE_OAM_SAG: OAM_SAG OA unit */
1657	DRM_XE_OA_UNIT_TYPE_OAM_SAG,
1658	};
1659
1660	/**
1661	* struct drm_xe_oa_unit - describe OA unit
1662	*/
1663	struct drm_xe_oa_unit {
1664	/** @extensions: Pointer to the first extension struct, if any */
1665	__u64 extensions;
1666
1667	/** @oa_unit_id: OA unit ID */
1668	__u32 oa_unit_id;
1669
1670	/** @oa_unit_type: OA unit type of @drm_xe_oa_unit_type */
1671	__u32 oa_unit_type;
1672
1673	/** @capabilities: OA capabilities bit-mask */
1674	__u64 capabilities;
1675	#define DRM_XE_OA_CAPS_BASE (1 << 0)
1676	#define DRM_XE_OA_CAPS_SYNCS (1 << 1)
1677	#define DRM_XE_OA_CAPS_OA_BUFFER_SIZE (1 << 2)
1678	#define DRM_XE_OA_CAPS_WAIT_NUM_REPORTS (1 << 3)
1679	#define DRM_XE_OA_CAPS_OAM (1 << 4)
1680
1681	/** @oa_timestamp_freq: OA timestamp freq */
1682	__u64 oa_timestamp_freq;
1683
1684	/** @reserved: MBZ */
1685	__u64 reserved[4];
1686
1687	/** @num_engines: number of engines in @eci array */
1688	__u64 num_engines;
1689
1690	/** @eci: engines attached to this OA unit */
1691	struct drm_xe_engine_class_instance eci[];
1692	};
1693
1694	/**
1695	* struct drm_xe_query_oa_units - describe OA units
1696	*
1697	* If a query is made with a struct drm_xe_device_query where .query
1698	* is equal to DRM_XE_DEVICE_QUERY_OA_UNITS, then the reply uses struct
1699	* drm_xe_query_oa_units in .data.
1700	*
1701	* OA unit properties for all OA units can be accessed using a code block
1702	* such as the one below:
1703	*
1704	* .. code-block:: C
1705	*
1706	* struct drm_xe_query_oa_units *qoa;
1707	* struct drm_xe_oa_unit *oau;
1708	* u8 *poau;
1709	*
1710	* // malloc qoa and issue DRM_XE_DEVICE_QUERY_OA_UNITS. Then:
1711	* poau = (u8 *)&qoa->oa_units[0];
1712	* for (int i = 0; i < qoa->num_oa_units; i++) {
1713	* oau = (struct drm_xe_oa_unit *)poau;
1714	* // Access 'struct drm_xe_oa_unit' fields here
1715	* poau += sizeof(*oau) + oau->num_engines * sizeof(oau->eci[0]);
1716	* }
1717	*/
1718	struct drm_xe_query_oa_units {
1719	/** @extensions: Pointer to the first extension struct, if any */
1720	__u64 extensions;
1721	/** @num_oa_units: number of OA units returned in oau[] */
1722	__u32 num_oa_units;
1723	/** @pad: MBZ */
1724	__u32 pad;
1725	/**
1726	* @oa_units: struct @drm_xe_oa_unit array returned for this device.
1727	* Written below as a u64 array to avoid problems with nested flexible
1728	* arrays with some compilers
1729	*/
1730	__u64 oa_units[];
1731	};
1732
1733	/**
1734	* enum drm_xe_oa_format_type - OA format types as specified in PRM/Bspec
1735	* 52198/60942
1736	*/
1737	enum drm_xe_oa_format_type {
1738	/** @DRM_XE_OA_FMT_TYPE_OAG: OAG report format */
1739	DRM_XE_OA_FMT_TYPE_OAG,
1740	/** @DRM_XE_OA_FMT_TYPE_OAR: OAR report format */
1741	DRM_XE_OA_FMT_TYPE_OAR,
1742	/** @DRM_XE_OA_FMT_TYPE_OAM: OAM report format */
1743	DRM_XE_OA_FMT_TYPE_OAM,
1744	/** @DRM_XE_OA_FMT_TYPE_OAC: OAC report format */
1745	DRM_XE_OA_FMT_TYPE_OAC,
1746	/** @DRM_XE_OA_FMT_TYPE_OAM_MPEC: OAM SAMEDIA or OAM MPEC report format */
1747	DRM_XE_OA_FMT_TYPE_OAM_MPEC,
1748	/** @DRM_XE_OA_FMT_TYPE_PEC: PEC report format */
1749	DRM_XE_OA_FMT_TYPE_PEC,
1750	};
1751
1752	/**
1753	* enum drm_xe_oa_property_id - OA stream property id's
1754	*
1755	* Stream params are specified as a chain of @drm_xe_ext_set_property
1756	* struct's, with @property values from enum @drm_xe_oa_property_id and
1757	* @drm_xe_user_extension base.name set to @DRM_XE_OA_EXTENSION_SET_PROPERTY.
1758	* @param field in struct @drm_xe_observation_param points to the first
1759	* @drm_xe_ext_set_property struct.
1760	*
1761	* Exactly the same mechanism is also used for stream reconfiguration using the
1762	* @DRM_XE_OBSERVATION_IOCTL_CONFIG observation stream fd ioctl, though only a
1763	* subset of properties below can be specified for stream reconfiguration.
1764	*/
1765	enum drm_xe_oa_property_id {
1766	#define DRM_XE_OA_EXTENSION_SET_PROPERTY 0
1767	/**
1768	* @DRM_XE_OA_PROPERTY_OA_UNIT_ID: ID of the OA unit on which to open
1769	* the OA stream, see @oa_unit_id in 'struct
1770	* drm_xe_query_oa_units'. Defaults to 0 if not provided.
1771	*/
1772	DRM_XE_OA_PROPERTY_OA_UNIT_ID = 1,
1773
1774	/**
1775	* @DRM_XE_OA_PROPERTY_SAMPLE_OA: A value of 1 requests inclusion of raw
1776	* OA unit reports or stream samples in a global buffer attached to an
1777	* OA unit.
1778	*/
1779	DRM_XE_OA_PROPERTY_SAMPLE_OA,
1780
1781	/**
1782	* @DRM_XE_OA_PROPERTY_OA_METRIC_SET: OA metrics defining contents of OA
1783	* reports, previously added via @DRM_XE_OBSERVATION_OP_ADD_CONFIG.
1784	*/
1785	DRM_XE_OA_PROPERTY_OA_METRIC_SET,
1786
1787	/** @DRM_XE_OA_PROPERTY_OA_FORMAT: OA counter report format */
1788	DRM_XE_OA_PROPERTY_OA_FORMAT,
1789	/*
1790	* OA_FORMAT's are specified the same way as in PRM/Bspec 52198/60942,
1791	* in terms of the following quantities: a. enum @drm_xe_oa_format_type
1792	* b. Counter select c. Counter size and d. BC report. Also refer to the
1793	* oa_formats array in drivers/gpu/drm/xe/xe_oa.c.
1794	*/
1795	#define DRM_XE_OA_FORMAT_MASK_FMT_TYPE (0xffu << 0)
1796	#define DRM_XE_OA_FORMAT_MASK_COUNTER_SEL (0xffu << 8)
1797	#define DRM_XE_OA_FORMAT_MASK_COUNTER_SIZE (0xffu << 16)
1798	#define DRM_XE_OA_FORMAT_MASK_BC_REPORT (0xffu << 24)
1799
1800	/**
1801	* @DRM_XE_OA_PROPERTY_OA_PERIOD_EXPONENT: Requests periodic OA unit
1802	* sampling with sampling frequency proportional to 2^(period_exponent + 1)
1803	*/
1804	DRM_XE_OA_PROPERTY_OA_PERIOD_EXPONENT,
1805
1806	/**
1807	* @DRM_XE_OA_PROPERTY_OA_DISABLED: A value of 1 will open the OA
1808	* stream in a DISABLED state (see @DRM_XE_OBSERVATION_IOCTL_ENABLE).
1809	*/
1810	DRM_XE_OA_PROPERTY_OA_DISABLED,
1811
1812	/**
1813	* @DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID: Open the stream for a specific
1814	* @exec_queue_id. OA queries can be executed on this exec queue.
1815	*/
1816	DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID,
1817
1818	/**
1819	* @DRM_XE_OA_PROPERTY_OA_ENGINE_INSTANCE: Optional engine instance to
1820	* pass along with @DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID or will default to 0.
1821	*/
1822	DRM_XE_OA_PROPERTY_OA_ENGINE_INSTANCE,
1823
1824	/**
1825	* @DRM_XE_OA_PROPERTY_NO_PREEMPT: Allow preemption and timeslicing
1826	* to be disabled for the stream exec queue.
1827	*/
1828	DRM_XE_OA_PROPERTY_NO_PREEMPT,
1829
1830	/**
1831	* @DRM_XE_OA_PROPERTY_NUM_SYNCS: Number of syncs in the sync array
1832	* specified in @DRM_XE_OA_PROPERTY_SYNCS
1833	*/
1834	DRM_XE_OA_PROPERTY_NUM_SYNCS,
1835
1836	/**
1837	* @DRM_XE_OA_PROPERTY_SYNCS: Pointer to struct @drm_xe_sync array
1838	* with array size specified via @DRM_XE_OA_PROPERTY_NUM_SYNCS. OA
1839	* configuration will wait till input fences signal. Output fences
1840	* will signal after the new OA configuration takes effect. For
1841	* @DRM_XE_SYNC_TYPE_USER_FENCE, @addr is a user pointer, similar
1842	* to the VM bind case.
1843	*/
1844	DRM_XE_OA_PROPERTY_SYNCS,
1845
1846	/**
1847	* @DRM_XE_OA_PROPERTY_OA_BUFFER_SIZE: Size of OA buffer to be
1848	* allocated by the driver in bytes. Supported sizes are powers of
1849	* 2 from 128 KiB to 128 MiB. When not specified, a 16 MiB OA
1850	* buffer is allocated by default.
1851	*/
1852	DRM_XE_OA_PROPERTY_OA_BUFFER_SIZE,
1853
1854	/**
1855	* @DRM_XE_OA_PROPERTY_WAIT_NUM_REPORTS: Number of reports to wait
1856	* for before unblocking poll or read
1857	*/
1858	DRM_XE_OA_PROPERTY_WAIT_NUM_REPORTS,
1859	};
1860
1861	/**
1862	* struct drm_xe_oa_config - OA metric configuration
1863	*
1864	* Multiple OA configs can be added using @DRM_XE_OBSERVATION_OP_ADD_CONFIG. A
1865	* particular config can be specified when opening an OA stream using
1866	* @DRM_XE_OA_PROPERTY_OA_METRIC_SET property.
1867	*/
1868	struct drm_xe_oa_config {
1869	/** @extensions: Pointer to the first extension struct, if any */
1870	__u64 extensions;
1871
1872	/** @uuid: String formatted like "%\08x-%\04x-%\04x-%\04x-%\012x" */
1873	char uuid[36];
1874
1875	/** @n_regs: Number of regs in @regs_ptr */
1876	__u32 n_regs;
1877
1878	/**
1879	* @regs_ptr: Pointer to (register address, value) pairs for OA config
1880	* registers. Expected length of buffer is: (2 * sizeof(u32) * @n_regs).
1881	*/
1882	__u64 regs_ptr;
1883	};
1884
1885	/**
1886	* struct drm_xe_oa_stream_status - OA stream status returned from
1887	* @DRM_XE_OBSERVATION_IOCTL_STATUS observation stream fd ioctl. Userspace can
1888	* call the ioctl to query stream status in response to EIO errno from
1889	* observation fd read().
1890	*/
1891	struct drm_xe_oa_stream_status {
1892	/** @extensions: Pointer to the first extension struct, if any */
1893	__u64 extensions;
1894
1895	/** @oa_status: OA stream status (see Bspec 46717/61226) */
1896	__u64 oa_status;
1897	#define DRM_XE_OASTATUS_MMIO_TRG_Q_FULL (1 << 3)
1898	#define DRM_XE_OASTATUS_COUNTER_OVERFLOW (1 << 2)
1899	#define DRM_XE_OASTATUS_BUFFER_OVERFLOW (1 << 1)
1900	#define DRM_XE_OASTATUS_REPORT_LOST (1 << 0)
1901
1902	/** @reserved: reserved for future use */
1903	__u64 reserved[3];
1904	};
1905
1906	/**
1907	* struct drm_xe_oa_stream_info - OA stream info returned from
1908	* @DRM_XE_OBSERVATION_IOCTL_INFO observation stream fd ioctl
1909	*/
1910	struct drm_xe_oa_stream_info {
1911	/** @extensions: Pointer to the first extension struct, if any */
1912	__u64 extensions;
1913
1914	/** @oa_buf_size: OA buffer size */
1915	__u64 oa_buf_size;
1916
1917	/** @reserved: reserved for future use */
1918	__u64 reserved[3];
1919	};
1920
1921	/**
1922	* enum drm_xe_pxp_session_type - Supported PXP session types.
1923	*
1924	* We currently only support HWDRM sessions, which are used for protected
1925	* content that ends up being displayed, but the HW supports multiple types, so
1926	* we might extend support in the future.
1927	*/
1928	enum drm_xe_pxp_session_type {
1929	/** @DRM_XE_PXP_TYPE_NONE: PXP not used */
1930	DRM_XE_PXP_TYPE_NONE = 0,
1931	/**
1932	* @DRM_XE_PXP_TYPE_HWDRM: HWDRM sessions are used for content that ends
1933	* up on the display.
1934	*/
1935	DRM_XE_PXP_TYPE_HWDRM = 1,
1936	};
1937
1938	/* ID of the protected content session managed by Xe when PXP is active */
1939	#define DRM_XE_PXP_HWDRM_DEFAULT_SESSION 0xf
1940
1941	/**
1942	* enum drm_xe_eu_stall_property_id - EU stall sampling input property ids.
1943	*
1944	* These properties are passed to the driver at open as a chain of
1945	* @drm_xe_ext_set_property structures with @property set to these
1946	* properties' enums and @value set to the corresponding values of these
1947	* properties. @drm_xe_user_extension base.name should be set to
1948	* @DRM_XE_EU_STALL_EXTENSION_SET_PROPERTY.
1949	*
1950	* With the file descriptor obtained from open, user space must enable
1951	* the EU stall stream fd with @DRM_XE_OBSERVATION_IOCTL_ENABLE before
1952	* calling read(). EIO errno from read() indicates HW dropped data
1953	* due to full buffer.
1954	*/
1955	enum drm_xe_eu_stall_property_id {
1956	#define DRM_XE_EU_STALL_EXTENSION_SET_PROPERTY 0
1957	/**
1958	* @DRM_XE_EU_STALL_PROP_GT_ID: @gt_id of the GT on which
1959	* EU stall data will be captured.
1960	*/
1961	DRM_XE_EU_STALL_PROP_GT_ID = 1,
1962
1963	/**
1964	* @DRM_XE_EU_STALL_PROP_SAMPLE_RATE: Sampling rate in
1965	* GPU cycles from @sampling_rates in struct @drm_xe_query_eu_stall
1966	*/
1967	DRM_XE_EU_STALL_PROP_SAMPLE_RATE,
1968
1969	/**
1970	* @DRM_XE_EU_STALL_PROP_WAIT_NUM_REPORTS: Minimum number of
1971	* EU stall data reports to be present in the kernel buffer
1972	* before unblocking a blocked poll or read.
1973	*/
1974	DRM_XE_EU_STALL_PROP_WAIT_NUM_REPORTS,
1975	};
1976
1977	/**
1978	* struct drm_xe_query_eu_stall - Information about EU stall sampling.
1979	*
1980	* If a query is made with a struct @drm_xe_device_query where .query
1981	* is equal to @DRM_XE_DEVICE_QUERY_EU_STALL, then the reply uses
1982	* struct @drm_xe_query_eu_stall in .data.
1983	*/
1984	struct drm_xe_query_eu_stall {
1985	/** @extensions: Pointer to the first extension struct, if any */
1986	__u64 extensions;
1987
1988	/** @capabilities: EU stall capabilities bit-mask */
1989	__u64 capabilities;
1990	#define DRM_XE_EU_STALL_CAPS_BASE (1 << 0)
1991
1992	/** @record_size: size of each EU stall data record */
1993	__u64 record_size;
1994
1995	/** @per_xecore_buf_size: internal per XeCore buffer size */
1996	__u64 per_xecore_buf_size;
1997
1998	/** @reserved: Reserved */
1999	__u64 reserved[5];
2000
2001	/** @num_sampling_rates: Number of sampling rates in @sampling_rates array */
2002	__u64 num_sampling_rates;
2003
2004	/**
2005	* @sampling_rates: Flexible array of sampling rates
2006	* sorted in the fastest to slowest order.
2007	* Sampling rates are specified in GPU clock cycles.
2008	*/
2009	__u64 sampling_rates[];
2010	};
2011
2012	/**
2013	* struct drm_xe_madvise - Input of &DRM_IOCTL_XE_MADVISE
2014	*
2015	* This structure is used to set memory attributes for a virtual address range
2016	* in a VM. The type of attribute is specified by @type, and the corresponding
2017	* union member is used to provide additional parameters for @type.
2018	*
2019	* Supported attribute types:
2020	* - DRM_XE_MEM_RANGE_ATTR_PREFERRED_LOC: Set preferred memory location.
2021	* - DRM_XE_MEM_RANGE_ATTR_ATOMIC: Set atomic access policy.
2022	* - DRM_XE_MEM_RANGE_ATTR_PAT: Set page attribute table index.
2023	*
2024	* Example:
2025	*
2026	* .. code-block:: C
2027	*
2028	* struct drm_xe_madvise madvise = {
2029	* .vm_id = vm_id,
2030	* .start = 0x100000,
2031	* .range = 0x2000,
2032	* .type = DRM_XE_MEM_RANGE_ATTR_ATOMIC,
2033	* .atomic_val = DRM_XE_ATOMIC_DEVICE,
2034	* };
2035	*
2036	* ioctl(fd, DRM_IOCTL_XE_MADVISE, &madvise);
2037	*
2038	*/
2039	struct drm_xe_madvise {
2040	/** @extensions: Pointer to the first extension struct, if any */
2041	__u64 extensions;
2042
2043	/** @start: start of the virtual address range */
2044	__u64 start;
2045
2046	/** @range: size of the virtual address range */
2047	__u64 range;
2048
2049	/** @vm_id: vm_id of the virtual range */
2050	__u32 vm_id;
2051
2052	#define DRM_XE_MEM_RANGE_ATTR_PREFERRED_LOC 0
2053	#define DRM_XE_MEM_RANGE_ATTR_ATOMIC 1
2054	#define DRM_XE_MEM_RANGE_ATTR_PAT 2
2055	/** @type: type of attribute */
2056	__u32 type;
2057
2058	union {
2059	/**
2060	* @preferred_mem_loc: preferred memory location
2061	*
2062	* Used when @type == DRM_XE_MEM_RANGE_ATTR_PREFERRED_LOC
2063	*
2064	* Supported values for @preferred_mem_loc.devmem_fd:
2065	* - DRM_XE_PREFERRED_LOC_DEFAULT_DEVICE: set vram of fault tile as preferred loc
2066	* - DRM_XE_PREFERRED_LOC_DEFAULT_SYSTEM: set smem as preferred loc
2067	*
2068	* Supported values for @preferred_mem_loc.migration_policy:
2069	* - DRM_XE_MIGRATE_ALL_PAGES
2070	* - DRM_XE_MIGRATE_ONLY_SYSTEM_PAGES
2071	*/
2072	struct {
2073	#define DRM_XE_PREFERRED_LOC_DEFAULT_DEVICE 0
2074	#define DRM_XE_PREFERRED_LOC_DEFAULT_SYSTEM -1
2075	/** @preferred_mem_loc.devmem_fd: fd for preferred loc */
2076	__u32 devmem_fd;
2077
2078	#define DRM_XE_MIGRATE_ALL_PAGES 0
2079	#define DRM_XE_MIGRATE_ONLY_SYSTEM_PAGES 1
2080	/** @preferred_mem_loc.migration_policy: Page migration policy */
2081	__u16 migration_policy;
2082
2083	/** @preferred_mem_loc.pad : MBZ */
2084	__u16 pad;
2085
2086	/** @preferred_mem_loc.reserved : Reserved */
2087	__u64 reserved;
2088	} preferred_mem_loc;
2089
2090	/**
2091	* @atomic: Atomic access policy
2092	*
2093	* Used when @type == DRM_XE_MEM_RANGE_ATTR_ATOMIC.
2094	*
2095	* Supported values for @atomic.val:
2096	* - DRM_XE_ATOMIC_UNDEFINED: Undefined or default behaviour.
2097	* Support both GPU and CPU atomic operations for system allocator.
2098	* Support GPU atomic operations for normal(bo) allocator.
2099	* - DRM_XE_ATOMIC_DEVICE: Support GPU atomic operations.
2100	* - DRM_XE_ATOMIC_GLOBAL: Support both GPU and CPU atomic operations.
2101	* - DRM_XE_ATOMIC_CPU: Support CPU atomic only, no GPU atomics supported.
2102	*/
2103	struct {
2104	#define DRM_XE_ATOMIC_UNDEFINED 0
2105	#define DRM_XE_ATOMIC_DEVICE 1
2106	#define DRM_XE_ATOMIC_GLOBAL 2
2107	#define DRM_XE_ATOMIC_CPU 3
2108	/** @atomic.val: value of atomic operation */
2109	__u32 val;
2110
2111	/** @atomic.pad: MBZ */
2112	__u32 pad;
2113
2114	/** @atomic.reserved: Reserved */
2115	__u64 reserved;
2116	} atomic;
2117
2118	/**
2119	* @pat_index: Page attribute table index
2120	*
2121	* Used when @type == DRM_XE_MEM_RANGE_ATTR_PAT.
2122	*/
2123	struct {
2124	/** @pat_index.val: PAT index value */
2125	__u32 val;
2126
2127	/** @pat_index.pad: MBZ */
2128	__u32 pad;
2129
2130	/** @pat_index.reserved: Reserved */
2131	__u64 reserved;
2132	} pat_index;
2133	};
2134
2135	/** @reserved: Reserved */
2136	__u64 reserved[2];
2137	};
2138
2139	/**
2140	* struct drm_xe_mem_range_attr - Output of &DRM_IOCTL_XE_VM_QUERY_MEM_RANGES_ATTRS
2141	*
2142	* This structure is provided by userspace and filled by KMD in response to the
2143	* DRM_IOCTL_XE_VM_QUERY_MEM_RANGES_ATTRS ioctl. It describes memory attributes of
2144	* a memory ranges within a user specified address range in a VM.
2145	*
2146	* The structure includes information such as atomic access policy,
2147	* page attribute table (PAT) index, and preferred memory location.
2148	* Userspace allocates an array of these structures and passes a pointer to the
2149	* ioctl to retrieve attributes for each memory ranges
2150	*
2151	* @extensions: Pointer to the first extension struct, if any
2152	* @start: Start address of the memory range
2153	* @end: End address of the virtual memory range
2154	*
2155	*/
2156	struct drm_xe_mem_range_attr {
2157	/** @extensions: Pointer to the first extension struct, if any */
2158	__u64 extensions;
2159
2160	/** @start: start of the memory range */
2161	__u64 start;
2162
2163	/** @end: end of the memory range */
2164	__u64 end;
2165
2166	/** @preferred_mem_loc: preferred memory location */
2167	struct {
2168	/** @preferred_mem_loc.devmem_fd: fd for preferred loc */
2169	__u32 devmem_fd;
2170
2171	/** @preferred_mem_loc.migration_policy: Page migration policy */
2172	__u32 migration_policy;
2173	} preferred_mem_loc;
2174
2175	/** @atomic: Atomic access policy */
2176	struct {
2177	/** @atomic.val: atomic attribute */
2178	__u32 val;
2179
2180	/** @atomic.reserved: Reserved */
2181	__u32 reserved;
2182	} atomic;
2183
2184	/** @pat_index: Page attribute table index */
2185	struct {
2186	/** @pat_index.val: PAT index */
2187	__u32 val;
2188
2189	/** @pat_index.reserved: Reserved */
2190	__u32 reserved;
2191	} pat_index;
2192
2193	/** @reserved: Reserved */
2194	__u64 reserved[2];
2195	};
2196
2197	/**
2198	* struct drm_xe_vm_query_mem_range_attr - Input of &DRM_IOCTL_XE_VM_QUERY_MEM_ATTRIBUTES
2199	*
2200	* This structure is used to query memory attributes of memory regions
2201	* within a user specified address range in a VM. It provides detailed
2202	* information about each memory range, including atomic access policy,
2203	* page attribute table (PAT) index, and preferred memory location.
2204	*
2205	* Userspace first calls the ioctl with @num_mem_ranges = 0,
2206	* @sizeof_mem_ranges_attr = 0 and @vector_of_vma_mem_attr = NULL to retrieve
2207	* the number of memory regions and size of each memory range attribute.
2208	* Then, it allocates a buffer of that size and calls the ioctl again to fill
2209	* the buffer with memory range attributes.
2210	*
2211	* If second call fails with -ENOSPC, it means memory ranges changed between
2212	* first call and now, retry IOCTL again with @num_mem_ranges = 0,
2213	* @sizeof_mem_ranges_attr = 0 and @vector_of_vma_mem_attr = NULL followed by
2214	* Second ioctl call.
2215	*
2216	* Example:
2217	*
2218	* .. code-block:: C
2219	*
2220	* struct drm_xe_vm_query_mem_range_attr query = {
2221	* .vm_id = vm_id,
2222	* .start = 0x100000,
2223	* .range = 0x2000,
2224	* };
2225	*
2226	* // First ioctl call to get num of mem regions and sizeof each attribute
2227	* ioctl(fd, DRM_IOCTL_XE_VM_QUERY_MEM_RANGE_ATTRS, &query);
2228	*
2229	* // Allocate buffer for the memory region attributes
2230	* void *ptr = malloc(query.num_mem_ranges * query.sizeof_mem_range_attr);
2231	* void *ptr_start = ptr;
2232	*
2233	* query.vector_of_mem_attr = (uintptr_t)ptr;
2234	*
2235	* // Second ioctl call to actually fill the memory attributes
2236	* ioctl(fd, DRM_IOCTL_XE_VM_QUERY_MEM_RANGE_ATTRS, &query);
2237	*
2238	* // Iterate over the returned memory region attributes
2239	* for (unsigned int i = 0; i < query.num_mem_ranges; ++i) {
2240	* struct drm_xe_mem_range_attr *attr = (struct drm_xe_mem_range_attr *)ptr;
2241	*
2242	* // Do something with attr
2243	*
2244	* // Move pointer by one entry
2245	* ptr += query.sizeof_mem_range_attr;
2246	* }
2247	*
2248	* free(ptr_start);
2249	*/
2250	struct drm_xe_vm_query_mem_range_attr {
2251	/** @extensions: Pointer to the first extension struct, if any */
2252	__u64 extensions;
2253
2254	/** @vm_id: vm_id of the virtual range */
2255	__u32 vm_id;
2256
2257	/** @num_mem_ranges: number of mem_ranges in range */
2258	__u32 num_mem_ranges;
2259
2260	/** @start: start of the virtual address range */
2261	__u64 start;
2262
2263	/** @range: size of the virtual address range */
2264	__u64 range;
2265
2266	/** @sizeof_mem_range_attr: size of struct drm_xe_mem_range_attr */
2267	__u64 sizeof_mem_range_attr;
2268
2269	/** @vector_of_mem_attr: userptr to array of struct drm_xe_mem_range_attr */
2270	__u64 vector_of_mem_attr;
2271
2272	/** @reserved: Reserved */
2273	__u64 reserved[2];
2274
2275	};
2276
2277	#if defined(__cplusplus)
2278	}
2279	#endif
2280
2281	#endif /* _UAPI_XE_DRM_H_ */
2282