2 * Copyright 2003 Tungsten Graphics, Inc., Cedar Park, Texas.
5 * Permission is hereby granted, free of charge, to any person obtaining a
6 * copy of this software and associated documentation files (the
7 * "Software"), to deal in the Software without restriction, including
8 * without limitation the rights to use, copy, modify, merge, publish,
9 * distribute, sub license, and/or sell copies of the Software, and to
10 * permit persons to whom the Software is furnished to do so, subject to
11 * the following conditions:
13 * The above copyright notice and this permission notice (including the
14 * next paragraph) shall be included in all copies or substantial portions
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
20 * IN NO EVENT SHALL TUNGSTEN GRAPHICS AND/OR ITS SUPPLIERS BE LIABLE FOR
21 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
22 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
27 #ifndef _UAPI_I915_DRM_H_
28 #define _UAPI_I915_DRM_H_
32 #if defined(__cplusplus)
36 /* Please note that modifications to all structs defined here are
37 * subject to backwards-compatibility constraints.
41 * DOC: uevents generated by i915 on it's device node
43 * I915_L3_PARITY_UEVENT - Generated when the driver receives a parity mismatch
44 * event from the gpu l3 cache. Additional information supplied is ROW,
45 * BANK, SUBBANK, SLICE of the affected cacheline. Userspace should keep
46 * track of these events and if a specific cache-line seems to have a
47 * persistent error remap it with the l3 remapping tool supplied in
48 * intel-gpu-tools. The value supplied with the event is always 1.
50 * I915_ERROR_UEVENT - Generated upon error detection, currently only via
51 * hangcheck. The error detection event is a good indicator of when things
52 * began to go badly. The value supplied with the event is a 1 upon error
53 * detection, and a 0 upon reset completion, signifying no more error
54 * exists. NOTE: Disabling hangcheck or reset via module parameter will
55 * cause the related events to not be seen.
57 * I915_RESET_UEVENT - Event is generated just before an attempt to reset the
58 * GPU. The value supplied with the event is always 1. NOTE: Disable
59 * reset via module parameter will cause this event to not be seen.
61 #define I915_L3_PARITY_UEVENT "L3_PARITY_ERROR"
62 #define I915_ERROR_UEVENT "ERROR"
63 #define I915_RESET_UEVENT "RESET"
66 * struct i915_user_extension - Base class for defining a chain of extensions
68 * Many interfaces need to grow over time. In most cases we can simply
69 * extend the struct and have userspace pass in more data. Another option,
70 * as demonstrated by Vulkan's approach to providing extensions for forward
71 * and backward compatibility, is to use a list of optional structs to
72 * provide those extra details.
74 * The key advantage to using an extension chain is that it allows us to
75 * redefine the interface more easily than an ever growing struct of
76 * increasing complexity, and for large parts of that interface to be
77 * entirely optional. The downside is more pointer chasing; chasing across
78 * the __user boundary with pointers encapsulated inside u64.
84 * struct i915_user_extension ext3 {
85 * .next_extension = 0, // end
88 * struct i915_user_extension ext2 {
89 * .next_extension = (uintptr_t)&ext3,
92 * struct i915_user_extension ext1 {
93 * .next_extension = (uintptr_t)&ext2,
97 * Typically the struct i915_user_extension would be embedded in some uAPI
98 * struct, and in this case we would feed it the head of the chain(i.e ext1),
99 * which would then apply all of the above extensions.
102 struct i915_user_extension {
106 * Pointer to the next struct i915_user_extension, or zero if the end.
108 __u64 next_extension;
110 * @name: Name of the extension.
112 * Note that the name here is just some integer.
114 * Also note that the name space for this is not global for the whole
115 * driver, but rather its scope/meaning is limited to the specific piece
116 * of uAPI which has embedded the struct i915_user_extension.
122 * All undefined bits must be zero.
128 * Reserved for future use; must be zero.
134 * MOCS indexes used for GPU surfaces, defining the cacheability of the
135 * surface data and the coherency for this data wrt. CPU vs. GPU accesses.
137 enum i915_mocs_table_index {
139 * Not cached anywhere, coherency between CPU and GPU accesses is
144 * Cacheability and coherency controlled by the kernel automatically
145 * based on the DRM_I915_GEM_SET_CACHING IOCTL setting and the current
146 * usage of the surface (used for display scanout or not).
150 * Cached in all GPU caches available on the platform.
151 * Coherency between CPU and GPU accesses to the surface is not
152 * guaranteed without extra synchronization.
158 * enum drm_i915_gem_engine_class - uapi engine type enumeration
160 * Different engines serve different roles, and there may be more than one
161 * engine serving each role. This enum provides a classification of the role
162 * of the engine, which may be used when requesting operations to be performed
163 * on a certain subset of engines, or for providing information about that
166 enum drm_i915_gem_engine_class {
168 * @I915_ENGINE_CLASS_RENDER:
170 * Render engines support instructions used for 3D, Compute (GPGPU),
171 * and programmable media workloads. These instructions fetch data and
172 * dispatch individual work items to threads that operate in parallel.
173 * The threads run small programs (called "kernels" or "shaders") on
174 * the GPU's execution units (EUs).
176 I915_ENGINE_CLASS_RENDER = 0,
179 * @I915_ENGINE_CLASS_COPY:
181 * Copy engines (also referred to as "blitters") support instructions
182 * that move blocks of data from one location in memory to another,
183 * or that fill a specified location of memory with fixed data.
184 * Copy engines can perform pre-defined logical or bitwise operations
185 * on the source, destination, or pattern data.
187 I915_ENGINE_CLASS_COPY = 1,
190 * @I915_ENGINE_CLASS_VIDEO:
192 * Video engines (also referred to as "bit stream decode" (BSD) or
193 * "vdbox") support instructions that perform fixed-function media
196 I915_ENGINE_CLASS_VIDEO = 2,
199 * @I915_ENGINE_CLASS_VIDEO_ENHANCE:
201 * Video enhancement engines (also referred to as "vebox") support
202 * instructions related to image enhancement.
204 I915_ENGINE_CLASS_VIDEO_ENHANCE = 3,
207 * @I915_ENGINE_CLASS_COMPUTE:
209 * Compute engines support a subset of the instructions available
210 * on render engines: compute engines support Compute (GPGPU) and
211 * programmable media workloads, but do not support the 3D pipeline.
213 I915_ENGINE_CLASS_COMPUTE = 4,
215 /* Values in this enum should be kept compact. */
218 * @I915_ENGINE_CLASS_INVALID:
220 * Placeholder value to represent an invalid engine class assignment.
222 I915_ENGINE_CLASS_INVALID = -1
226 * struct i915_engine_class_instance - Engine class/instance identifier
228 * There may be more than one engine fulfilling any role within the system.
229 * Each engine of a class is given a unique instance number and therefore
230 * any engine can be specified by its class:instance tuplet. APIs that allow
231 * access to any engine in the system will use struct i915_engine_class_instance
232 * for this identification.
234 struct i915_engine_class_instance {
238 * Engine class from enum drm_i915_gem_engine_class
241 #define I915_ENGINE_CLASS_INVALID_NONE -1
242 #define I915_ENGINE_CLASS_INVALID_VIRTUAL -2
249 __u16 engine_instance;
253 * DOC: perf_events exposed by i915 through /sys/bus/event_sources/drivers/i915
257 enum drm_i915_pmu_engine_sample {
258 I915_SAMPLE_BUSY = 0,
259 I915_SAMPLE_WAIT = 1,
263 #define I915_PMU_SAMPLE_BITS (4)
264 #define I915_PMU_SAMPLE_MASK (0xf)
265 #define I915_PMU_SAMPLE_INSTANCE_BITS (8)
266 #define I915_PMU_CLASS_SHIFT \
267 (I915_PMU_SAMPLE_BITS + I915_PMU_SAMPLE_INSTANCE_BITS)
269 #define __I915_PMU_ENGINE(class, instance, sample) \
270 ((class) << I915_PMU_CLASS_SHIFT | \
271 (instance) << I915_PMU_SAMPLE_BITS | \
274 #define I915_PMU_ENGINE_BUSY(class, instance) \
275 __I915_PMU_ENGINE(class, instance, I915_SAMPLE_BUSY)
277 #define I915_PMU_ENGINE_WAIT(class, instance) \
278 __I915_PMU_ENGINE(class, instance, I915_SAMPLE_WAIT)
280 #define I915_PMU_ENGINE_SEMA(class, instance) \
281 __I915_PMU_ENGINE(class, instance, I915_SAMPLE_SEMA)
283 #define __I915_PMU_OTHER(x) (__I915_PMU_ENGINE(0xff, 0xff, 0xf) + 1 + (x))
285 #define I915_PMU_ACTUAL_FREQUENCY __I915_PMU_OTHER(0)
286 #define I915_PMU_REQUESTED_FREQUENCY __I915_PMU_OTHER(1)
287 #define I915_PMU_INTERRUPTS __I915_PMU_OTHER(2)
288 #define I915_PMU_RC6_RESIDENCY __I915_PMU_OTHER(3)
289 #define I915_PMU_SOFTWARE_GT_AWAKE_TIME __I915_PMU_OTHER(4)
291 #define I915_PMU_LAST /* Deprecated - do not use */ I915_PMU_RC6_RESIDENCY
293 /* Each region is a minimum of 16k, and there are at most 255 of them.
295 #define I915_NR_TEX_REGIONS 255 /* table size 2k - maximum due to use
296 * of chars for next/prev indices */
297 #define I915_LOG_MIN_TEX_REGION_SIZE 14
299 typedef struct _drm_i915_init {
301 I915_INIT_DMA = 0x01,
302 I915_CLEANUP_DMA = 0x02,
303 I915_RESUME_DMA = 0x03
305 unsigned int mmio_offset;
306 int sarea_priv_offset;
307 unsigned int ring_start;
308 unsigned int ring_end;
309 unsigned int ring_size;
310 unsigned int front_offset;
311 unsigned int back_offset;
312 unsigned int depth_offset;
316 unsigned int pitch_bits;
317 unsigned int back_pitch;
318 unsigned int depth_pitch;
320 unsigned int chipset;
323 typedef struct _drm_i915_sarea {
324 struct drm_tex_region texList[I915_NR_TEX_REGIONS + 1];
325 int last_upload; /* last time texture was uploaded */
326 int last_enqueue; /* last time a buffer was enqueued */
327 int last_dispatch; /* age of the most recently dispatched buffer */
328 int ctxOwner; /* last context to upload state */
330 int pf_enabled; /* is pageflipping allowed? */
332 int pf_current_page; /* which buffer is being displayed? */
333 int perf_boxes; /* performance boxes to be displayed */
334 int width, height; /* screen size in pixels */
336 drm_handle_t front_handle;
340 drm_handle_t back_handle;
344 drm_handle_t depth_handle;
348 drm_handle_t tex_handle;
351 int log_tex_granularity;
353 int rotation; /* 0, 90, 180 or 270 */
357 int virtualX, virtualY;
359 unsigned int front_tiled;
360 unsigned int back_tiled;
361 unsigned int depth_tiled;
362 unsigned int rotated_tiled;
363 unsigned int rotated2_tiled;
374 /* fill out some space for old userspace triple buffer */
375 drm_handle_t unused_handle;
376 __u32 unused1, unused2, unused3;
378 /* buffer object handles for static buffers. May change
379 * over the lifetime of the client.
381 __u32 front_bo_handle;
382 __u32 back_bo_handle;
383 __u32 unused_bo_handle;
384 __u32 depth_bo_handle;
388 /* due to userspace building against these headers we need some compat here */
389 #define planeA_x pipeA_x
390 #define planeA_y pipeA_y
391 #define planeA_w pipeA_w
392 #define planeA_h pipeA_h
393 #define planeB_x pipeB_x
394 #define planeB_y pipeB_y
395 #define planeB_w pipeB_w
396 #define planeB_h pipeB_h
398 /* Flags for perf_boxes
400 #define I915_BOX_RING_EMPTY 0x1
401 #define I915_BOX_FLIP 0x2
402 #define I915_BOX_WAIT 0x4
403 #define I915_BOX_TEXTURE_LOAD 0x8
404 #define I915_BOX_LOST_CONTEXT 0x10
407 * i915 specific ioctls.
409 * The device specific ioctl range is [DRM_COMMAND_BASE, DRM_COMMAND_END) ie
410 * [0x40, 0xa0) (a0 is excluded). The numbers below are defined as offset
411 * against DRM_COMMAND_BASE and should be between [0x0, 0x60).
413 #define DRM_I915_INIT 0x00
414 #define DRM_I915_FLUSH 0x01
415 #define DRM_I915_FLIP 0x02
416 #define DRM_I915_BATCHBUFFER 0x03
417 #define DRM_I915_IRQ_EMIT 0x04
418 #define DRM_I915_IRQ_WAIT 0x05
419 #define DRM_I915_GETPARAM 0x06
420 #define DRM_I915_SETPARAM 0x07
421 #define DRM_I915_ALLOC 0x08
422 #define DRM_I915_FREE 0x09
423 #define DRM_I915_INIT_HEAP 0x0a
424 #define DRM_I915_CMDBUFFER 0x0b
425 #define DRM_I915_DESTROY_HEAP 0x0c
426 #define DRM_I915_SET_VBLANK_PIPE 0x0d
427 #define DRM_I915_GET_VBLANK_PIPE 0x0e
428 #define DRM_I915_VBLANK_SWAP 0x0f
429 #define DRM_I915_HWS_ADDR 0x11
430 #define DRM_I915_GEM_INIT 0x13
431 #define DRM_I915_GEM_EXECBUFFER 0x14
432 #define DRM_I915_GEM_PIN 0x15
433 #define DRM_I915_GEM_UNPIN 0x16
434 #define DRM_I915_GEM_BUSY 0x17
435 #define DRM_I915_GEM_THROTTLE 0x18
436 #define DRM_I915_GEM_ENTERVT 0x19
437 #define DRM_I915_GEM_LEAVEVT 0x1a
438 #define DRM_I915_GEM_CREATE 0x1b
439 #define DRM_I915_GEM_PREAD 0x1c
440 #define DRM_I915_GEM_PWRITE 0x1d
441 #define DRM_I915_GEM_MMAP 0x1e
442 #define DRM_I915_GEM_SET_DOMAIN 0x1f
443 #define DRM_I915_GEM_SW_FINISH 0x20
444 #define DRM_I915_GEM_SET_TILING 0x21
445 #define DRM_I915_GEM_GET_TILING 0x22
446 #define DRM_I915_GEM_GET_APERTURE 0x23
447 #define DRM_I915_GEM_MMAP_GTT 0x24
448 #define DRM_I915_GET_PIPE_FROM_CRTC_ID 0x25
449 #define DRM_I915_GEM_MADVISE 0x26
450 #define DRM_I915_OVERLAY_PUT_IMAGE 0x27
451 #define DRM_I915_OVERLAY_ATTRS 0x28
452 #define DRM_I915_GEM_EXECBUFFER2 0x29
453 #define DRM_I915_GEM_EXECBUFFER2_WR DRM_I915_GEM_EXECBUFFER2
454 #define DRM_I915_GET_SPRITE_COLORKEY 0x2a
455 #define DRM_I915_SET_SPRITE_COLORKEY 0x2b
456 #define DRM_I915_GEM_WAIT 0x2c
457 #define DRM_I915_GEM_CONTEXT_CREATE 0x2d
458 #define DRM_I915_GEM_CONTEXT_DESTROY 0x2e
459 #define DRM_I915_GEM_SET_CACHING 0x2f
460 #define DRM_I915_GEM_GET_CACHING 0x30
461 #define DRM_I915_REG_READ 0x31
462 #define DRM_I915_GET_RESET_STATS 0x32
463 #define DRM_I915_GEM_USERPTR 0x33
464 #define DRM_I915_GEM_CONTEXT_GETPARAM 0x34
465 #define DRM_I915_GEM_CONTEXT_SETPARAM 0x35
466 #define DRM_I915_PERF_OPEN 0x36
467 #define DRM_I915_PERF_ADD_CONFIG 0x37
468 #define DRM_I915_PERF_REMOVE_CONFIG 0x38
469 #define DRM_I915_QUERY 0x39
470 #define DRM_I915_GEM_VM_CREATE 0x3a
471 #define DRM_I915_GEM_VM_DESTROY 0x3b
472 #define DRM_I915_GEM_CREATE_EXT 0x3c
473 /* Must be kept compact -- no holes */
475 #define DRM_IOCTL_I915_INIT DRM_IOW( DRM_COMMAND_BASE + DRM_I915_INIT, drm_i915_init_t)
476 #define DRM_IOCTL_I915_FLUSH DRM_IO ( DRM_COMMAND_BASE + DRM_I915_FLUSH)
477 #define DRM_IOCTL_I915_FLIP DRM_IO ( DRM_COMMAND_BASE + DRM_I915_FLIP)
478 #define DRM_IOCTL_I915_BATCHBUFFER DRM_IOW( DRM_COMMAND_BASE + DRM_I915_BATCHBUFFER, drm_i915_batchbuffer_t)
479 #define DRM_IOCTL_I915_IRQ_EMIT DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_IRQ_EMIT, drm_i915_irq_emit_t)
480 #define DRM_IOCTL_I915_IRQ_WAIT DRM_IOW( DRM_COMMAND_BASE + DRM_I915_IRQ_WAIT, drm_i915_irq_wait_t)
481 #define DRM_IOCTL_I915_GETPARAM DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GETPARAM, drm_i915_getparam_t)
482 #define DRM_IOCTL_I915_SETPARAM DRM_IOW( DRM_COMMAND_BASE + DRM_I915_SETPARAM, drm_i915_setparam_t)
483 #define DRM_IOCTL_I915_ALLOC DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_ALLOC, drm_i915_mem_alloc_t)
484 #define DRM_IOCTL_I915_FREE DRM_IOW( DRM_COMMAND_BASE + DRM_I915_FREE, drm_i915_mem_free_t)
485 #define DRM_IOCTL_I915_INIT_HEAP DRM_IOW( DRM_COMMAND_BASE + DRM_I915_INIT_HEAP, drm_i915_mem_init_heap_t)
486 #define DRM_IOCTL_I915_CMDBUFFER DRM_IOW( DRM_COMMAND_BASE + DRM_I915_CMDBUFFER, drm_i915_cmdbuffer_t)
487 #define DRM_IOCTL_I915_DESTROY_HEAP DRM_IOW( DRM_COMMAND_BASE + DRM_I915_DESTROY_HEAP, drm_i915_mem_destroy_heap_t)
488 #define DRM_IOCTL_I915_SET_VBLANK_PIPE DRM_IOW( DRM_COMMAND_BASE + DRM_I915_SET_VBLANK_PIPE, drm_i915_vblank_pipe_t)
489 #define DRM_IOCTL_I915_GET_VBLANK_PIPE DRM_IOR( DRM_COMMAND_BASE + DRM_I915_GET_VBLANK_PIPE, drm_i915_vblank_pipe_t)
490 #define DRM_IOCTL_I915_VBLANK_SWAP DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_VBLANK_SWAP, drm_i915_vblank_swap_t)
491 #define DRM_IOCTL_I915_HWS_ADDR DRM_IOW(DRM_COMMAND_BASE + DRM_I915_HWS_ADDR, struct drm_i915_gem_init)
492 #define DRM_IOCTL_I915_GEM_INIT DRM_IOW(DRM_COMMAND_BASE + DRM_I915_GEM_INIT, struct drm_i915_gem_init)
493 #define DRM_IOCTL_I915_GEM_EXECBUFFER DRM_IOW(DRM_COMMAND_BASE + DRM_I915_GEM_EXECBUFFER, struct drm_i915_gem_execbuffer)
494 #define DRM_IOCTL_I915_GEM_EXECBUFFER2 DRM_IOW(DRM_COMMAND_BASE + DRM_I915_GEM_EXECBUFFER2, struct drm_i915_gem_execbuffer2)
495 #define DRM_IOCTL_I915_GEM_EXECBUFFER2_WR DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_EXECBUFFER2_WR, struct drm_i915_gem_execbuffer2)
496 #define DRM_IOCTL_I915_GEM_PIN DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_PIN, struct drm_i915_gem_pin)
497 #define DRM_IOCTL_I915_GEM_UNPIN DRM_IOW(DRM_COMMAND_BASE + DRM_I915_GEM_UNPIN, struct drm_i915_gem_unpin)
498 #define DRM_IOCTL_I915_GEM_BUSY DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_BUSY, struct drm_i915_gem_busy)
499 #define DRM_IOCTL_I915_GEM_SET_CACHING DRM_IOW(DRM_COMMAND_BASE + DRM_I915_GEM_SET_CACHING, struct drm_i915_gem_caching)
500 #define DRM_IOCTL_I915_GEM_GET_CACHING DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_GET_CACHING, struct drm_i915_gem_caching)
501 #define DRM_IOCTL_I915_GEM_THROTTLE DRM_IO ( DRM_COMMAND_BASE + DRM_I915_GEM_THROTTLE)
502 #define DRM_IOCTL_I915_GEM_ENTERVT DRM_IO(DRM_COMMAND_BASE + DRM_I915_GEM_ENTERVT)
503 #define DRM_IOCTL_I915_GEM_LEAVEVT DRM_IO(DRM_COMMAND_BASE + DRM_I915_GEM_LEAVEVT)
504 #define DRM_IOCTL_I915_GEM_CREATE DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_CREATE, struct drm_i915_gem_create)
505 #define DRM_IOCTL_I915_GEM_CREATE_EXT DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_CREATE_EXT, struct drm_i915_gem_create_ext)
506 #define DRM_IOCTL_I915_GEM_PREAD DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_PREAD, struct drm_i915_gem_pread)
507 #define DRM_IOCTL_I915_GEM_PWRITE DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_PWRITE, struct drm_i915_gem_pwrite)
508 #define DRM_IOCTL_I915_GEM_MMAP DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_MMAP, struct drm_i915_gem_mmap)
509 #define DRM_IOCTL_I915_GEM_MMAP_GTT DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_MMAP_GTT, struct drm_i915_gem_mmap_gtt)
510 #define DRM_IOCTL_I915_GEM_MMAP_OFFSET DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_MMAP_GTT, struct drm_i915_gem_mmap_offset)
511 #define DRM_IOCTL_I915_GEM_SET_DOMAIN DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_SET_DOMAIN, struct drm_i915_gem_set_domain)
512 #define DRM_IOCTL_I915_GEM_SW_FINISH DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_SW_FINISH, struct drm_i915_gem_sw_finish)
513 #define DRM_IOCTL_I915_GEM_SET_TILING DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_SET_TILING, struct drm_i915_gem_set_tiling)
514 #define DRM_IOCTL_I915_GEM_GET_TILING DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_GET_TILING, struct drm_i915_gem_get_tiling)
515 #define DRM_IOCTL_I915_GEM_GET_APERTURE DRM_IOR (DRM_COMMAND_BASE + DRM_I915_GEM_GET_APERTURE, struct drm_i915_gem_get_aperture)
516 #define DRM_IOCTL_I915_GET_PIPE_FROM_CRTC_ID DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GET_PIPE_FROM_CRTC_ID, struct drm_i915_get_pipe_from_crtc_id)
517 #define DRM_IOCTL_I915_GEM_MADVISE DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_MADVISE, struct drm_i915_gem_madvise)
518 #define DRM_IOCTL_I915_OVERLAY_PUT_IMAGE DRM_IOW(DRM_COMMAND_BASE + DRM_I915_OVERLAY_PUT_IMAGE, struct drm_intel_overlay_put_image)
519 #define DRM_IOCTL_I915_OVERLAY_ATTRS DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_OVERLAY_ATTRS, struct drm_intel_overlay_attrs)
520 #define DRM_IOCTL_I915_SET_SPRITE_COLORKEY DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_SET_SPRITE_COLORKEY, struct drm_intel_sprite_colorkey)
521 #define DRM_IOCTL_I915_GET_SPRITE_COLORKEY DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GET_SPRITE_COLORKEY, struct drm_intel_sprite_colorkey)
522 #define DRM_IOCTL_I915_GEM_WAIT DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_WAIT, struct drm_i915_gem_wait)
523 #define DRM_IOCTL_I915_GEM_CONTEXT_CREATE DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_CONTEXT_CREATE, struct drm_i915_gem_context_create)
524 #define DRM_IOCTL_I915_GEM_CONTEXT_CREATE_EXT DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_CONTEXT_CREATE, struct drm_i915_gem_context_create_ext)
525 #define DRM_IOCTL_I915_GEM_CONTEXT_DESTROY DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_CONTEXT_DESTROY, struct drm_i915_gem_context_destroy)
526 #define DRM_IOCTL_I915_REG_READ DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_REG_READ, struct drm_i915_reg_read)
527 #define DRM_IOCTL_I915_GET_RESET_STATS DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GET_RESET_STATS, struct drm_i915_reset_stats)
528 #define DRM_IOCTL_I915_GEM_USERPTR DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_USERPTR, struct drm_i915_gem_userptr)
529 #define DRM_IOCTL_I915_GEM_CONTEXT_GETPARAM DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_CONTEXT_GETPARAM, struct drm_i915_gem_context_param)
530 #define DRM_IOCTL_I915_GEM_CONTEXT_SETPARAM DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_CONTEXT_SETPARAM, struct drm_i915_gem_context_param)
531 #define DRM_IOCTL_I915_PERF_OPEN DRM_IOW(DRM_COMMAND_BASE + DRM_I915_PERF_OPEN, struct drm_i915_perf_open_param)
532 #define DRM_IOCTL_I915_PERF_ADD_CONFIG DRM_IOW(DRM_COMMAND_BASE + DRM_I915_PERF_ADD_CONFIG, struct drm_i915_perf_oa_config)
533 #define DRM_IOCTL_I915_PERF_REMOVE_CONFIG DRM_IOW(DRM_COMMAND_BASE + DRM_I915_PERF_REMOVE_CONFIG, __u64)
534 #define DRM_IOCTL_I915_QUERY DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_QUERY, struct drm_i915_query)
535 #define DRM_IOCTL_I915_GEM_VM_CREATE DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_VM_CREATE, struct drm_i915_gem_vm_control)
536 #define DRM_IOCTL_I915_GEM_VM_DESTROY DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_VM_DESTROY, struct drm_i915_gem_vm_control)
538 /* Allow drivers to submit batchbuffers directly to hardware, relying
539 * on the security mechanisms provided by hardware.
541 typedef struct drm_i915_batchbuffer {
542 int start; /* agp offset */
543 int used; /* nr bytes in use */
544 int DR1; /* hw flags for GFX_OP_DRAWRECT_INFO */
545 int DR4; /* window origin for GFX_OP_DRAWRECT_INFO */
546 int num_cliprects; /* mulitpass with multiple cliprects? */
547 struct drm_clip_rect __user *cliprects; /* pointer to userspace cliprects */
548 } drm_i915_batchbuffer_t;
550 /* As above, but pass a pointer to userspace buffer which can be
551 * validated by the kernel prior to sending to hardware.
553 typedef struct _drm_i915_cmdbuffer {
554 char __user *buf; /* pointer to userspace command buffer */
555 int sz; /* nr bytes in buf */
556 int DR1; /* hw flags for GFX_OP_DRAWRECT_INFO */
557 int DR4; /* window origin for GFX_OP_DRAWRECT_INFO */
558 int num_cliprects; /* mulitpass with multiple cliprects? */
559 struct drm_clip_rect __user *cliprects; /* pointer to userspace cliprects */
560 } drm_i915_cmdbuffer_t;
562 /* Userspace can request & wait on irq's:
564 typedef struct drm_i915_irq_emit {
566 } drm_i915_irq_emit_t;
568 typedef struct drm_i915_irq_wait {
570 } drm_i915_irq_wait_t;
573 * Different modes of per-process Graphics Translation Table,
574 * see I915_PARAM_HAS_ALIASING_PPGTT
576 #define I915_GEM_PPGTT_NONE 0
577 #define I915_GEM_PPGTT_ALIASING 1
578 #define I915_GEM_PPGTT_FULL 2
580 /* Ioctl to query kernel params:
582 #define I915_PARAM_IRQ_ACTIVE 1
583 #define I915_PARAM_ALLOW_BATCHBUFFER 2
584 #define I915_PARAM_LAST_DISPATCH 3
585 #define I915_PARAM_CHIPSET_ID 4
586 #define I915_PARAM_HAS_GEM 5
587 #define I915_PARAM_NUM_FENCES_AVAIL 6
588 #define I915_PARAM_HAS_OVERLAY 7
589 #define I915_PARAM_HAS_PAGEFLIPPING 8
590 #define I915_PARAM_HAS_EXECBUF2 9
591 #define I915_PARAM_HAS_BSD 10
592 #define I915_PARAM_HAS_BLT 11
593 #define I915_PARAM_HAS_RELAXED_FENCING 12
594 #define I915_PARAM_HAS_COHERENT_RINGS 13
595 #define I915_PARAM_HAS_EXEC_CONSTANTS 14
596 #define I915_PARAM_HAS_RELAXED_DELTA 15
597 #define I915_PARAM_HAS_GEN7_SOL_RESET 16
598 #define I915_PARAM_HAS_LLC 17
599 #define I915_PARAM_HAS_ALIASING_PPGTT 18
600 #define I915_PARAM_HAS_WAIT_TIMEOUT 19
601 #define I915_PARAM_HAS_SEMAPHORES 20
602 #define I915_PARAM_HAS_PRIME_VMAP_FLUSH 21
603 #define I915_PARAM_HAS_VEBOX 22
604 #define I915_PARAM_HAS_SECURE_BATCHES 23
605 #define I915_PARAM_HAS_PINNED_BATCHES 24
606 #define I915_PARAM_HAS_EXEC_NO_RELOC 25
607 #define I915_PARAM_HAS_EXEC_HANDLE_LUT 26
608 #define I915_PARAM_HAS_WT 27
609 #define I915_PARAM_CMD_PARSER_VERSION 28
610 #define I915_PARAM_HAS_COHERENT_PHYS_GTT 29
611 #define I915_PARAM_MMAP_VERSION 30
612 #define I915_PARAM_HAS_BSD2 31
613 #define I915_PARAM_REVISION 32
614 #define I915_PARAM_SUBSLICE_TOTAL 33
615 #define I915_PARAM_EU_TOTAL 34
616 #define I915_PARAM_HAS_GPU_RESET 35
617 #define I915_PARAM_HAS_RESOURCE_STREAMER 36
618 #define I915_PARAM_HAS_EXEC_SOFTPIN 37
619 #define I915_PARAM_HAS_POOLED_EU 38
620 #define I915_PARAM_MIN_EU_IN_POOL 39
621 #define I915_PARAM_MMAP_GTT_VERSION 40
624 * Query whether DRM_I915_GEM_EXECBUFFER2 supports user defined execution
625 * priorities and the driver will attempt to execute batches in priority order.
626 * The param returns a capability bitmask, nonzero implies that the scheduler
627 * is enabled, with different features present according to the mask.
629 * The initial priority for each batch is supplied by the context and is
630 * controlled via I915_CONTEXT_PARAM_PRIORITY.
632 #define I915_PARAM_HAS_SCHEDULER 41
633 #define I915_SCHEDULER_CAP_ENABLED (1ul << 0)
634 #define I915_SCHEDULER_CAP_PRIORITY (1ul << 1)
635 #define I915_SCHEDULER_CAP_PREEMPTION (1ul << 2)
636 #define I915_SCHEDULER_CAP_SEMAPHORES (1ul << 3)
637 #define I915_SCHEDULER_CAP_ENGINE_BUSY_STATS (1ul << 4)
639 * Indicates the 2k user priority levels are statically mapped into 3 buckets as
642 * -1k to -1 Low priority
644 * 1 to 1k Highest priority
646 #define I915_SCHEDULER_CAP_STATIC_PRIORITY_MAP (1ul << 5)
648 #define I915_PARAM_HUC_STATUS 42
650 /* Query whether DRM_I915_GEM_EXECBUFFER2 supports the ability to opt-out of
651 * synchronisation with implicit fencing on individual objects.
652 * See EXEC_OBJECT_ASYNC.
654 #define I915_PARAM_HAS_EXEC_ASYNC 43
656 /* Query whether DRM_I915_GEM_EXECBUFFER2 supports explicit fence support -
657 * both being able to pass in a sync_file fd to wait upon before executing,
658 * and being able to return a new sync_file fd that is signaled when the
659 * current request is complete. See I915_EXEC_FENCE_IN and I915_EXEC_FENCE_OUT.
661 #define I915_PARAM_HAS_EXEC_FENCE 44
663 /* Query whether DRM_I915_GEM_EXECBUFFER2 supports the ability to capture
664 * user specified bufffers for post-mortem debugging of GPU hangs. See
665 * EXEC_OBJECT_CAPTURE.
667 #define I915_PARAM_HAS_EXEC_CAPTURE 45
669 #define I915_PARAM_SLICE_MASK 46
671 /* Assuming it's uniform for each slice, this queries the mask of subslices
672 * per-slice for this system.
674 #define I915_PARAM_SUBSLICE_MASK 47
677 * Query whether DRM_I915_GEM_EXECBUFFER2 supports supplying the batch buffer
678 * as the first execobject as opposed to the last. See I915_EXEC_BATCH_FIRST.
680 #define I915_PARAM_HAS_EXEC_BATCH_FIRST 48
682 /* Query whether DRM_I915_GEM_EXECBUFFER2 supports supplying an array of
683 * drm_i915_gem_exec_fence structures. See I915_EXEC_FENCE_ARRAY.
685 #define I915_PARAM_HAS_EXEC_FENCE_ARRAY 49
688 * Query whether every context (both per-file default and user created) is
689 * isolated (insofar as HW supports). If this parameter is not true, then
690 * freshly created contexts may inherit values from an existing context,
691 * rather than default HW values. If true, it also ensures (insofar as HW
692 * supports) that all state set by this context will not leak to any other
695 * As not every engine across every gen support contexts, the returned
696 * value reports the support of context isolation for individual engines by
697 * returning a bitmask of each engine class set to true if that class supports
700 #define I915_PARAM_HAS_CONTEXT_ISOLATION 50
702 /* Frequency of the command streamer timestamps given by the *_TIMESTAMP
703 * registers. This used to be fixed per platform but from CNL onwards, this
704 * might vary depending on the parts.
706 #define I915_PARAM_CS_TIMESTAMP_FREQUENCY 51
709 * Once upon a time we supposed that writes through the GGTT would be
710 * immediately in physical memory (once flushed out of the CPU path). However,
711 * on a few different processors and chipsets, this is not necessarily the case
712 * as the writes appear to be buffered internally. Thus a read of the backing
713 * storage (physical memory) via a different path (with different physical tags
714 * to the indirect write via the GGTT) will see stale values from before
715 * the GGTT write. Inside the kernel, we can for the most part keep track of
716 * the different read/write domains in use (e.g. set-domain), but the assumption
717 * of coherency is baked into the ABI, hence reporting its true state in this
720 * Reports true when writes via mmap_gtt are immediately visible following an
721 * lfence to flush the WCB.
723 * Reports false when writes via mmap_gtt are indeterminately delayed in an in
724 * internal buffer and are _not_ immediately visible to third parties accessing
725 * directly via mmap_cpu/mmap_wc. Use of mmap_gtt as part of an IPC
726 * communications channel when reporting false is strongly disadvised.
728 #define I915_PARAM_MMAP_GTT_COHERENT 52
731 * Query whether DRM_I915_GEM_EXECBUFFER2 supports coordination of parallel
732 * execution through use of explicit fence support.
733 * See I915_EXEC_FENCE_OUT and I915_EXEC_FENCE_SUBMIT.
735 #define I915_PARAM_HAS_EXEC_SUBMIT_FENCE 53
738 * Revision of the i915-perf uAPI. The value returned helps determine what
739 * i915-perf features are available. See drm_i915_perf_property_id.
741 #define I915_PARAM_PERF_REVISION 54
743 /* Query whether DRM_I915_GEM_EXECBUFFER2 supports supplying an array of
744 * timeline syncobj through drm_i915_gem_execbuffer_ext_timeline_fences. See
745 * I915_EXEC_USE_EXTENSIONS.
747 #define I915_PARAM_HAS_EXEC_TIMELINE_FENCES 55
749 /* Query if the kernel supports the I915_USERPTR_PROBE flag. */
750 #define I915_PARAM_HAS_USERPTR_PROBE 56
752 /* Must be kept compact -- no holes and well documented */
755 * struct drm_i915_getparam - Driver parameter query structure.
757 struct drm_i915_getparam {
758 /** @param: Driver parameter to query. */
762 * @value: Address of memory where queried value should be put.
764 * WARNING: Using pointers instead of fixed-size u64 means we need to write
765 * compat32 code. Don't repeat this mistake.
771 * typedef drm_i915_getparam_t - Driver parameter query structure.
772 * See struct drm_i915_getparam.
774 typedef struct drm_i915_getparam drm_i915_getparam_t;
776 /* Ioctl to set kernel params:
778 #define I915_SETPARAM_USE_MI_BATCHBUFFER_START 1
779 #define I915_SETPARAM_TEX_LRU_LOG_GRANULARITY 2
780 #define I915_SETPARAM_ALLOW_BATCHBUFFER 3
781 #define I915_SETPARAM_NUM_USED_FENCES 4
782 /* Must be kept compact -- no holes */
784 typedef struct drm_i915_setparam {
787 } drm_i915_setparam_t;
789 /* A memory manager for regions of shared memory:
791 #define I915_MEM_REGION_AGP 1
793 typedef struct drm_i915_mem_alloc {
797 int __user *region_offset; /* offset from start of fb or agp */
798 } drm_i915_mem_alloc_t;
800 typedef struct drm_i915_mem_free {
803 } drm_i915_mem_free_t;
805 typedef struct drm_i915_mem_init_heap {
809 } drm_i915_mem_init_heap_t;
811 /* Allow memory manager to be torn down and re-initialized (eg on
814 typedef struct drm_i915_mem_destroy_heap {
816 } drm_i915_mem_destroy_heap_t;
818 /* Allow X server to configure which pipes to monitor for vblank signals
820 #define DRM_I915_VBLANK_PIPE_A 1
821 #define DRM_I915_VBLANK_PIPE_B 2
823 typedef struct drm_i915_vblank_pipe {
825 } drm_i915_vblank_pipe_t;
827 /* Schedule buffer swap at given vertical blank:
829 typedef struct drm_i915_vblank_swap {
830 drm_drawable_t drawable;
831 enum drm_vblank_seq_type seqtype;
832 unsigned int sequence;
833 } drm_i915_vblank_swap_t;
835 typedef struct drm_i915_hws_addr {
837 } drm_i915_hws_addr_t;
839 struct drm_i915_gem_init {
841 * Beginning offset in the GTT to be managed by the DRM memory
846 * Ending offset in the GTT to be managed by the DRM memory
852 struct drm_i915_gem_create {
854 * Requested size for the object.
856 * The (page-aligned) allocated size for the object will be returned.
860 * Returned handle for the object.
862 * Object handles are nonzero.
868 struct drm_i915_gem_pread {
869 /** Handle for the object being read. */
872 /** Offset into the object to read from */
874 /** Length of data to read */
877 * Pointer to write the data into.
879 * This is a fixed-size type for 32/64 compatibility.
884 struct drm_i915_gem_pwrite {
885 /** Handle for the object being written to. */
888 /** Offset into the object to write to */
890 /** Length of data to write */
893 * Pointer to read the data from.
895 * This is a fixed-size type for 32/64 compatibility.
900 struct drm_i915_gem_mmap {
901 /** Handle for the object being mapped. */
904 /** Offset in the object to map. */
907 * Length of data to map.
909 * The value will be page-aligned.
913 * Returned pointer the data was mapped at.
915 * This is a fixed-size type for 32/64 compatibility.
920 * Flags for extended behaviour.
922 * Added in version 2.
925 #define I915_MMAP_WC 0x1
928 struct drm_i915_gem_mmap_gtt {
929 /** Handle for the object being mapped. */
933 * Fake offset to use for subsequent mmap call
935 * This is a fixed-size type for 32/64 compatibility.
941 * struct drm_i915_gem_mmap_offset - Retrieve an offset so we can mmap this buffer object.
943 * This struct is passed as argument to the `DRM_IOCTL_I915_GEM_MMAP_OFFSET` ioctl,
944 * and is used to retrieve the fake offset to mmap an object specified by &handle.
946 * The legacy way of using `DRM_IOCTL_I915_GEM_MMAP` is removed on gen12+.
947 * `DRM_IOCTL_I915_GEM_MMAP_GTT` is an older supported alias to this struct, but will behave
948 * as setting the &extensions to 0, and &flags to `I915_MMAP_OFFSET_GTT`.
950 struct drm_i915_gem_mmap_offset {
951 /** @handle: Handle for the object being mapped. */
953 /** @pad: Must be zero */
956 * @offset: The fake offset to use for subsequent mmap call
958 * This is a fixed-size type for 32/64 compatibility.
963 * @flags: Flags for extended behaviour.
965 * It is mandatory that one of the `MMAP_OFFSET` types
966 * should be included:
968 * - `I915_MMAP_OFFSET_GTT`: Use mmap with the object bound to GTT. (Write-Combined)
969 * - `I915_MMAP_OFFSET_WC`: Use Write-Combined caching.
970 * - `I915_MMAP_OFFSET_WB`: Use Write-Back caching.
971 * - `I915_MMAP_OFFSET_FIXED`: Use object placement to determine caching.
973 * On devices with local memory `I915_MMAP_OFFSET_FIXED` is the only valid
974 * type. On devices without local memory, this caching mode is invalid.
976 * As caching mode when specifying `I915_MMAP_OFFSET_FIXED`, WC or WB will
977 * be used, depending on the object placement on creation. WB will be used
978 * when the object can only exist in system memory, WC otherwise.
982 #define I915_MMAP_OFFSET_GTT 0
983 #define I915_MMAP_OFFSET_WC 1
984 #define I915_MMAP_OFFSET_WB 2
985 #define I915_MMAP_OFFSET_UC 3
986 #define I915_MMAP_OFFSET_FIXED 4
989 * @extensions: Zero-terminated chain of extensions.
991 * No current extensions defined; mbz.
997 * struct drm_i915_gem_set_domain - Adjust the objects write or read domain, in
998 * preparation for accessing the pages via some CPU domain.
1000 * Specifying a new write or read domain will flush the object out of the
1001 * previous domain(if required), before then updating the objects domain
1002 * tracking with the new domain.
1004 * Note this might involve waiting for the object first if it is still active on
1007 * Supported values for @read_domains and @write_domain:
1009 * - I915_GEM_DOMAIN_WC: Uncached write-combined domain
1010 * - I915_GEM_DOMAIN_CPU: CPU cache domain
1011 * - I915_GEM_DOMAIN_GTT: Mappable aperture domain
1013 * All other domains are rejected.
1015 * Note that for discrete, starting from DG1, this is no longer supported, and
1016 * is instead rejected. On such platforms the CPU domain is effectively static,
1017 * where we also only support a single &drm_i915_gem_mmap_offset cache mode,
1018 * which can't be set explicitly and instead depends on the object placements,
1021 * Implicit caching rules, starting from DG1:
1023 * - If any of the object placements (see &drm_i915_gem_create_ext_memory_regions)
1024 * contain I915_MEMORY_CLASS_DEVICE then the object will be allocated and
1025 * mapped as write-combined only.
1027 * - Everything else is always allocated and mapped as write-back, with the
1028 * guarantee that everything is also coherent with the GPU.
1030 * Note that this is likely to change in the future again, where we might need
1031 * more flexibility on future devices, so making this all explicit as part of a
1032 * new &drm_i915_gem_create_ext extension is probable.
1034 struct drm_i915_gem_set_domain {
1035 /** @handle: Handle for the object. */
1038 /** @read_domains: New read domains. */
1042 * @write_domain: New write domain.
1044 * Note that having something in the write domain implies it's in the
1045 * read domain, and only that read domain.
1050 struct drm_i915_gem_sw_finish {
1051 /** Handle for the object */
1055 struct drm_i915_gem_relocation_entry {
1057 * Handle of the buffer being pointed to by this relocation entry.
1059 * It's appealing to make this be an index into the mm_validate_entry
1060 * list to refer to the buffer, but this allows the driver to create
1061 * a relocation list for state buffers and not re-write it per
1062 * exec using the buffer.
1064 __u32 target_handle;
1067 * Value to be added to the offset of the target buffer to make up
1068 * the relocation entry.
1072 /** Offset in the buffer the relocation entry will be written into */
1076 * Offset value of the target buffer that the relocation entry was last
1079 * If the buffer has the same offset as last time, we can skip syncing
1080 * and writing the relocation. This value is written back out by
1081 * the execbuffer ioctl when the relocation is written.
1083 __u64 presumed_offset;
1086 * Target memory domains read by this operation.
1091 * Target memory domains written by this operation.
1093 * Note that only one domain may be written by the whole
1094 * execbuffer operation, so that where there are conflicts,
1095 * the application will get -EINVAL back.
1101 * Intel memory domains
1103 * Most of these just align with the various caches in
1104 * the system and are used to flush and invalidate as
1105 * objects end up cached in different domains.
1108 #define I915_GEM_DOMAIN_CPU 0x00000001
1109 /** Render cache, used by 2D and 3D drawing */
1110 #define I915_GEM_DOMAIN_RENDER 0x00000002
1111 /** Sampler cache, used by texture engine */
1112 #define I915_GEM_DOMAIN_SAMPLER 0x00000004
1113 /** Command queue, used to load batch buffers */
1114 #define I915_GEM_DOMAIN_COMMAND 0x00000008
1115 /** Instruction cache, used by shader programs */
1116 #define I915_GEM_DOMAIN_INSTRUCTION 0x00000010
1117 /** Vertex address cache */
1118 #define I915_GEM_DOMAIN_VERTEX 0x00000020
1119 /** GTT domain - aperture and scanout */
1120 #define I915_GEM_DOMAIN_GTT 0x00000040
1121 /** WC domain - uncached access */
1122 #define I915_GEM_DOMAIN_WC 0x00000080
1125 struct drm_i915_gem_exec_object {
1127 * User's handle for a buffer to be bound into the GTT for this
1132 /** Number of relocations to be performed on this buffer */
1133 __u32 relocation_count;
1135 * Pointer to array of struct drm_i915_gem_relocation_entry containing
1136 * the relocations to be performed in this buffer.
1140 /** Required alignment in graphics aperture */
1144 * Returned value of the updated offset of the object, for future
1145 * presumed_offset writes.
1150 /* DRM_IOCTL_I915_GEM_EXECBUFFER was removed in Linux 5.13 */
1151 struct drm_i915_gem_execbuffer {
1153 * List of buffers to be validated with their relocations to be
1154 * performend on them.
1156 * This is a pointer to an array of struct drm_i915_gem_validate_entry.
1158 * These buffers must be listed in an order such that all relocations
1159 * a buffer is performing refer to buffers that have already appeared
1160 * in the validate list.
1165 /** Offset in the batchbuffer to start execution from. */
1166 __u32 batch_start_offset;
1167 /** Bytes used in batchbuffer from batch_start_offset */
1171 __u32 num_cliprects;
1172 /** This is a struct drm_clip_rect *cliprects */
1173 __u64 cliprects_ptr;
1176 struct drm_i915_gem_exec_object2 {
1178 * User's handle for a buffer to be bound into the GTT for this
1183 /** Number of relocations to be performed on this buffer */
1184 __u32 relocation_count;
1186 * Pointer to array of struct drm_i915_gem_relocation_entry containing
1187 * the relocations to be performed in this buffer.
1191 /** Required alignment in graphics aperture */
1195 * When the EXEC_OBJECT_PINNED flag is specified this is populated by
1196 * the user with the GTT offset at which this object will be pinned.
1198 * When the I915_EXEC_NO_RELOC flag is specified this must contain the
1199 * presumed_offset of the object.
1201 * During execbuffer2 the kernel populates it with the value of the
1202 * current GTT offset of the object, for future presumed_offset writes.
1204 * See struct drm_i915_gem_create_ext for the rules when dealing with
1205 * alignment restrictions with I915_MEMORY_CLASS_DEVICE, on devices with
1206 * minimum page sizes, like DG2.
1210 #define EXEC_OBJECT_NEEDS_FENCE (1<<0)
1211 #define EXEC_OBJECT_NEEDS_GTT (1<<1)
1212 #define EXEC_OBJECT_WRITE (1<<2)
1213 #define EXEC_OBJECT_SUPPORTS_48B_ADDRESS (1<<3)
1214 #define EXEC_OBJECT_PINNED (1<<4)
1215 #define EXEC_OBJECT_PAD_TO_SIZE (1<<5)
1216 /* The kernel implicitly tracks GPU activity on all GEM objects, and
1217 * synchronises operations with outstanding rendering. This includes
1218 * rendering on other devices if exported via dma-buf. However, sometimes
1219 * this tracking is too coarse and the user knows better. For example,
1220 * if the object is split into non-overlapping ranges shared between different
1221 * clients or engines (i.e. suballocating objects), the implicit tracking
1222 * by kernel assumes that each operation affects the whole object rather
1223 * than an individual range, causing needless synchronisation between clients.
1224 * The kernel will also forgo any CPU cache flushes prior to rendering from
1225 * the object as the client is expected to be also handling such domain
1228 * The kernel maintains the implicit tracking in order to manage resources
1229 * used by the GPU - this flag only disables the synchronisation prior to
1230 * rendering with this object in this execbuf.
1232 * Opting out of implicit synhronisation requires the user to do its own
1233 * explicit tracking to avoid rendering corruption. See, for example,
1234 * I915_PARAM_HAS_EXEC_FENCE to order execbufs and execute them asynchronously.
1236 #define EXEC_OBJECT_ASYNC (1<<6)
1237 /* Request that the contents of this execobject be copied into the error
1238 * state upon a GPU hang involving this batch for post-mortem debugging.
1239 * These buffers are recorded in no particular order as "user" in
1240 * /sys/class/drm/cardN/error. Query I915_PARAM_HAS_EXEC_CAPTURE to see
1241 * if the kernel supports this flag.
1243 #define EXEC_OBJECT_CAPTURE (1<<7)
1244 /* All remaining bits are MBZ and RESERVED FOR FUTURE USE */
1245 #define __EXEC_OBJECT_UNKNOWN_FLAGS -(EXEC_OBJECT_CAPTURE<<1)
1256 * struct drm_i915_gem_exec_fence - An input or output fence for the execbuf
1259 * The request will wait for input fence to signal before submission.
1261 * The returned output fence will be signaled after the completion of the
1264 struct drm_i915_gem_exec_fence {
1265 /** @handle: User's handle for a drm_syncobj to wait on or signal. */
1269 * @flags: Supported flags are:
1271 * I915_EXEC_FENCE_WAIT:
1272 * Wait for the input fence before request submission.
1274 * I915_EXEC_FENCE_SIGNAL:
1275 * Return request completion fence as output
1278 #define I915_EXEC_FENCE_WAIT (1<<0)
1279 #define I915_EXEC_FENCE_SIGNAL (1<<1)
1280 #define __I915_EXEC_FENCE_UNKNOWN_FLAGS (-(I915_EXEC_FENCE_SIGNAL << 1))
1284 * struct drm_i915_gem_execbuffer_ext_timeline_fences - Timeline fences
1285 * for execbuf ioctl.
1287 * This structure describes an array of drm_syncobj and associated points for
1288 * timeline variants of drm_syncobj. It is invalid to append this structure to
1289 * the execbuf if I915_EXEC_FENCE_ARRAY is set.
1291 struct drm_i915_gem_execbuffer_ext_timeline_fences {
1292 #define DRM_I915_GEM_EXECBUFFER_EXT_TIMELINE_FENCES 0
1293 /** @base: Extension link. See struct i915_user_extension. */
1294 struct i915_user_extension base;
1297 * @fence_count: Number of elements in the @handles_ptr & @value_ptr
1303 * @handles_ptr: Pointer to an array of struct drm_i915_gem_exec_fence
1304 * of length @fence_count.
1309 * @values_ptr: Pointer to an array of u64 values of length
1311 * Values must be 0 for a binary drm_syncobj. A Value of 0 for a
1312 * timeline drm_syncobj is invalid as it turns a drm_syncobj into a
1319 * struct drm_i915_gem_execbuffer2 - Structure for DRM_I915_GEM_EXECBUFFER2
1322 struct drm_i915_gem_execbuffer2 {
1323 /** @buffers_ptr: Pointer to a list of gem_exec_object2 structs */
1326 /** @buffer_count: Number of elements in @buffers_ptr array */
1330 * @batch_start_offset: Offset in the batchbuffer to start execution
1333 __u32 batch_start_offset;
1336 * @batch_len: Length in bytes of the batch buffer, starting from the
1337 * @batch_start_offset. If 0, length is assumed to be the batch buffer
1342 /** @DR1: deprecated */
1345 /** @DR4: deprecated */
1348 /** @num_cliprects: See @cliprects_ptr */
1349 __u32 num_cliprects;
1352 * @cliprects_ptr: Kernel clipping was a DRI1 misfeature.
1354 * It is invalid to use this field if I915_EXEC_FENCE_ARRAY or
1355 * I915_EXEC_USE_EXTENSIONS flags are not set.
1357 * If I915_EXEC_FENCE_ARRAY is set, then this is a pointer to an array
1358 * of &drm_i915_gem_exec_fence and @num_cliprects is the length of the
1361 * If I915_EXEC_USE_EXTENSIONS is set, then this is a pointer to a
1362 * single &i915_user_extension and num_cliprects is 0.
1364 __u64 cliprects_ptr;
1366 /** @flags: Execbuf flags */
1368 #define I915_EXEC_RING_MASK (0x3f)
1369 #define I915_EXEC_DEFAULT (0<<0)
1370 #define I915_EXEC_RENDER (1<<0)
1371 #define I915_EXEC_BSD (2<<0)
1372 #define I915_EXEC_BLT (3<<0)
1373 #define I915_EXEC_VEBOX (4<<0)
1375 /* Used for switching the constants addressing mode on gen4+ RENDER ring.
1376 * Gen6+ only supports relative addressing to dynamic state (default) and
1377 * absolute addressing.
1379 * These flags are ignored for the BSD and BLT rings.
1381 #define I915_EXEC_CONSTANTS_MASK (3<<6)
1382 #define I915_EXEC_CONSTANTS_REL_GENERAL (0<<6) /* default */
1383 #define I915_EXEC_CONSTANTS_ABSOLUTE (1<<6)
1384 #define I915_EXEC_CONSTANTS_REL_SURFACE (2<<6) /* gen4/5 only */
1386 /** Resets the SO write offset registers for transform feedback on gen7. */
1387 #define I915_EXEC_GEN7_SOL_RESET (1<<8)
1389 /** Request a privileged ("secure") batch buffer. Note only available for
1390 * DRM_ROOT_ONLY | DRM_MASTER processes.
1392 #define I915_EXEC_SECURE (1<<9)
1394 /** Inform the kernel that the batch is and will always be pinned. This
1395 * negates the requirement for a workaround to be performed to avoid
1396 * an incoherent CS (such as can be found on 830/845). If this flag is
1397 * not passed, the kernel will endeavour to make sure the batch is
1398 * coherent with the CS before execution. If this flag is passed,
1399 * userspace assumes the responsibility for ensuring the same.
1401 #define I915_EXEC_IS_PINNED (1<<10)
1403 /** Provide a hint to the kernel that the command stream and auxiliary
1404 * state buffers already holds the correct presumed addresses and so the
1405 * relocation process may be skipped if no buffers need to be moved in
1406 * preparation for the execbuffer.
1408 #define I915_EXEC_NO_RELOC (1<<11)
1410 /** Use the reloc.handle as an index into the exec object array rather
1411 * than as the per-file handle.
1413 #define I915_EXEC_HANDLE_LUT (1<<12)
1415 /** Used for switching BSD rings on the platforms with two BSD rings */
1416 #define I915_EXEC_BSD_SHIFT (13)
1417 #define I915_EXEC_BSD_MASK (3 << I915_EXEC_BSD_SHIFT)
1418 /* default ping-pong mode */
1419 #define I915_EXEC_BSD_DEFAULT (0 << I915_EXEC_BSD_SHIFT)
1420 #define I915_EXEC_BSD_RING1 (1 << I915_EXEC_BSD_SHIFT)
1421 #define I915_EXEC_BSD_RING2 (2 << I915_EXEC_BSD_SHIFT)
1423 /** Tell the kernel that the batchbuffer is processed by
1424 * the resource streamer.
1426 #define I915_EXEC_RESOURCE_STREAMER (1<<15)
1428 /* Setting I915_EXEC_FENCE_IN implies that lower_32_bits(rsvd2) represent
1429 * a sync_file fd to wait upon (in a nonblocking manner) prior to executing
1432 * Returns -EINVAL if the sync_file fd cannot be found.
1434 #define I915_EXEC_FENCE_IN (1<<16)
1436 /* Setting I915_EXEC_FENCE_OUT causes the ioctl to return a sync_file fd
1437 * in the upper_32_bits(rsvd2) upon success. Ownership of the fd is given
1438 * to the caller, and it should be close() after use. (The fd is a regular
1439 * file descriptor and will be cleaned up on process termination. It holds
1440 * a reference to the request, but nothing else.)
1442 * The sync_file fd can be combined with other sync_file and passed either
1443 * to execbuf using I915_EXEC_FENCE_IN, to atomic KMS ioctls (so that a flip
1444 * will only occur after this request completes), or to other devices.
1446 * Using I915_EXEC_FENCE_OUT requires use of
1447 * DRM_IOCTL_I915_GEM_EXECBUFFER2_WR ioctl so that the result is written
1448 * back to userspace. Failure to do so will cause the out-fence to always
1449 * be reported as zero, and the real fence fd to be leaked.
1451 #define I915_EXEC_FENCE_OUT (1<<17)
1454 * Traditionally the execbuf ioctl has only considered the final element in
1455 * the execobject[] to be the executable batch. Often though, the client
1456 * will known the batch object prior to construction and being able to place
1457 * it into the execobject[] array first can simplify the relocation tracking.
1458 * Setting I915_EXEC_BATCH_FIRST tells execbuf to use element 0 of the
1459 * execobject[] as the * batch instead (the default is to use the last
1462 #define I915_EXEC_BATCH_FIRST (1<<18)
1464 /* Setting I915_FENCE_ARRAY implies that num_cliprects and cliprects_ptr
1465 * define an array of i915_gem_exec_fence structures which specify a set of
1466 * dma fences to wait upon or signal.
1468 #define I915_EXEC_FENCE_ARRAY (1<<19)
1471 * Setting I915_EXEC_FENCE_SUBMIT implies that lower_32_bits(rsvd2) represent
1472 * a sync_file fd to wait upon (in a nonblocking manner) prior to executing
1475 * Returns -EINVAL if the sync_file fd cannot be found.
1477 #define I915_EXEC_FENCE_SUBMIT (1 << 20)
1480 * Setting I915_EXEC_USE_EXTENSIONS implies that
1481 * drm_i915_gem_execbuffer2.cliprects_ptr is treated as a pointer to an linked
1482 * list of i915_user_extension. Each i915_user_extension node is the base of a
1483 * larger structure. The list of supported structures are listed in the
1484 * drm_i915_gem_execbuffer_ext enum.
1486 #define I915_EXEC_USE_EXTENSIONS (1 << 21)
1487 #define __I915_EXEC_UNKNOWN_FLAGS (-(I915_EXEC_USE_EXTENSIONS << 1))
1489 /** @rsvd1: Context id */
1493 * @rsvd2: in and out sync_file file descriptors.
1495 * When I915_EXEC_FENCE_IN or I915_EXEC_FENCE_SUBMIT flag is set, the
1496 * lower 32 bits of this field will have the in sync_file fd (input).
1498 * When I915_EXEC_FENCE_OUT flag is set, the upper 32 bits of this
1499 * field will have the out sync_file fd (output).
1504 #define I915_EXEC_CONTEXT_ID_MASK (0xffffffff)
1505 #define i915_execbuffer2_set_context_id(eb2, context) \
1506 (eb2).rsvd1 = context & I915_EXEC_CONTEXT_ID_MASK
1507 #define i915_execbuffer2_get_context_id(eb2) \
1508 ((eb2).rsvd1 & I915_EXEC_CONTEXT_ID_MASK)
1510 struct drm_i915_gem_pin {
1511 /** Handle of the buffer to be pinned. */
1515 /** alignment required within the aperture */
1518 /** Returned GTT offset of the buffer. */
1522 struct drm_i915_gem_unpin {
1523 /** Handle of the buffer to be unpinned. */
1528 struct drm_i915_gem_busy {
1529 /** Handle of the buffer to check for busy */
1532 /** Return busy status
1534 * A return of 0 implies that the object is idle (after
1535 * having flushed any pending activity), and a non-zero return that
1536 * the object is still in-flight on the GPU. (The GPU has not yet
1537 * signaled completion for all pending requests that reference the
1538 * object.) An object is guaranteed to become idle eventually (so
1539 * long as no new GPU commands are executed upon it). Due to the
1540 * asynchronous nature of the hardware, an object reported
1541 * as busy may become idle before the ioctl is completed.
1543 * Furthermore, if the object is busy, which engine is busy is only
1544 * provided as a guide and only indirectly by reporting its class
1545 * (there may be more than one engine in each class). There are race
1546 * conditions which prevent the report of which engines are busy from
1547 * being always accurate. However, the converse is not true. If the
1548 * object is idle, the result of the ioctl, that all engines are idle,
1551 * The returned dword is split into two fields to indicate both
1552 * the engine classess on which the object is being read, and the
1553 * engine class on which it is currently being written (if any).
1555 * The low word (bits 0:15) indicate if the object is being written
1556 * to by any engine (there can only be one, as the GEM implicit
1557 * synchronisation rules force writes to be serialised). Only the
1558 * engine class (offset by 1, I915_ENGINE_CLASS_RENDER is reported as
1559 * 1 not 0 etc) for the last write is reported.
1561 * The high word (bits 16:31) are a bitmask of which engines classes
1562 * are currently reading from the object. Multiple engines may be
1563 * reading from the object simultaneously.
1565 * The value of each engine class is the same as specified in the
1566 * I915_CONTEXT_PARAM_ENGINES context parameter and via perf, i.e.
1567 * I915_ENGINE_CLASS_RENDER, I915_ENGINE_CLASS_COPY, etc.
1568 * Some hardware may have parallel execution engines, e.g. multiple
1569 * media engines, which are mapped to the same class identifier and so
1570 * are not separately reported for busyness.
1573 * Only the boolean result of this query is reliable; that is whether
1574 * the object is idle or busy. The report of which engines are busy
1575 * should be only used as a heuristic.
1581 * struct drm_i915_gem_caching - Set or get the caching for given object
1584 * Allow userspace to control the GTT caching bits for a given object when the
1585 * object is later mapped through the ppGTT(or GGTT on older platforms lacking
1586 * ppGTT support, or if the object is used for scanout). Note that this might
1587 * require unbinding the object from the GTT first, if its current caching value
1590 * Note that this all changes on discrete platforms, starting from DG1, the
1591 * set/get caching is no longer supported, and is now rejected. Instead the CPU
1592 * caching attributes(WB vs WC) will become an immutable creation time property
1593 * for the object, along with the GTT caching level. For now we don't expose any
1594 * new uAPI for this, instead on DG1 this is all implicit, although this largely
1595 * shouldn't matter since DG1 is coherent by default(without any way of
1598 * Implicit caching rules, starting from DG1:
1600 * - If any of the object placements (see &drm_i915_gem_create_ext_memory_regions)
1601 * contain I915_MEMORY_CLASS_DEVICE then the object will be allocated and
1602 * mapped as write-combined only.
1604 * - Everything else is always allocated and mapped as write-back, with the
1605 * guarantee that everything is also coherent with the GPU.
1607 * Note that this is likely to change in the future again, where we might need
1608 * more flexibility on future devices, so making this all explicit as part of a
1609 * new &drm_i915_gem_create_ext extension is probable.
1611 * Side note: Part of the reason for this is that changing the at-allocation-time CPU
1612 * caching attributes for the pages might be required(and is expensive) if we
1613 * need to then CPU map the pages later with different caching attributes. This
1614 * inconsistent caching behaviour, while supported on x86, is not universally
1615 * supported on other architectures. So for simplicity we opt for setting
1616 * everything at creation time, whilst also making it immutable, on discrete
1619 struct drm_i915_gem_caching {
1621 * @handle: Handle of the buffer to set/get the caching level.
1626 * @caching: The GTT caching level to apply or possible return value.
1628 * The supported @caching values:
1630 * I915_CACHING_NONE:
1632 * GPU access is not coherent with CPU caches. Default for machines
1633 * without an LLC. This means manual flushing might be needed, if we
1634 * want GPU access to be coherent.
1636 * I915_CACHING_CACHED:
1638 * GPU access is coherent with CPU caches and furthermore the data is
1639 * cached in last-level caches shared between CPU cores and the GPU GT.
1641 * I915_CACHING_DISPLAY:
1643 * Special GPU caching mode which is coherent with the scanout engines.
1644 * Transparently falls back to I915_CACHING_NONE on platforms where no
1645 * special cache mode (like write-through or gfdt flushing) is
1646 * available. The kernel automatically sets this mode when using a
1647 * buffer as a scanout target. Userspace can manually set this mode to
1648 * avoid a costly stall and clflush in the hotpath of drawing the first
1651 #define I915_CACHING_NONE 0
1652 #define I915_CACHING_CACHED 1
1653 #define I915_CACHING_DISPLAY 2
1657 #define I915_TILING_NONE 0
1658 #define I915_TILING_X 1
1659 #define I915_TILING_Y 2
1661 * Do not add new tiling types here. The I915_TILING_* values are for
1662 * de-tiling fence registers that no longer exist on modern platforms. Although
1663 * the hardware may support new types of tiling in general (e.g., Tile4), we
1664 * do not need to add them to the uapi that is specific to now-defunct ioctls.
1666 #define I915_TILING_LAST I915_TILING_Y
1668 #define I915_BIT_6_SWIZZLE_NONE 0
1669 #define I915_BIT_6_SWIZZLE_9 1
1670 #define I915_BIT_6_SWIZZLE_9_10 2
1671 #define I915_BIT_6_SWIZZLE_9_11 3
1672 #define I915_BIT_6_SWIZZLE_9_10_11 4
1673 /* Not seen by userland */
1674 #define I915_BIT_6_SWIZZLE_UNKNOWN 5
1675 /* Seen by userland. */
1676 #define I915_BIT_6_SWIZZLE_9_17 6
1677 #define I915_BIT_6_SWIZZLE_9_10_17 7
1679 struct drm_i915_gem_set_tiling {
1680 /** Handle of the buffer to have its tiling state updated */
1684 * Tiling mode for the object (I915_TILING_NONE, I915_TILING_X,
1687 * This value is to be set on request, and will be updated by the
1688 * kernel on successful return with the actual chosen tiling layout.
1690 * The tiling mode may be demoted to I915_TILING_NONE when the system
1691 * has bit 6 swizzling that can't be managed correctly by GEM.
1693 * Buffer contents become undefined when changing tiling_mode.
1698 * Stride in bytes for the object when in I915_TILING_X or
1704 * Returned address bit 6 swizzling required for CPU access through
1710 struct drm_i915_gem_get_tiling {
1711 /** Handle of the buffer to get tiling state for. */
1715 * Current tiling mode for the object (I915_TILING_NONE, I915_TILING_X,
1721 * Returned address bit 6 swizzling required for CPU access through
1727 * Returned address bit 6 swizzling required for CPU access through
1728 * mmap mapping whilst bound.
1730 __u32 phys_swizzle_mode;
1733 struct drm_i915_gem_get_aperture {
1734 /** Total size of the aperture used by i915_gem_execbuffer, in bytes */
1738 * Available space in the aperture used by i915_gem_execbuffer, in
1741 __u64 aper_available_size;
1744 struct drm_i915_get_pipe_from_crtc_id {
1745 /** ID of CRTC being requested **/
1748 /** pipe of requested CRTC **/
1752 #define I915_MADV_WILLNEED 0
1753 #define I915_MADV_DONTNEED 1
1754 #define __I915_MADV_PURGED 2 /* internal state */
1756 struct drm_i915_gem_madvise {
1757 /** Handle of the buffer to change the backing store advice */
1760 /* Advice: either the buffer will be needed again in the near future,
1761 * or wont be and could be discarded under memory pressure.
1765 /** Whether the backing store still exists. */
1770 #define I915_OVERLAY_TYPE_MASK 0xff
1771 #define I915_OVERLAY_YUV_PLANAR 0x01
1772 #define I915_OVERLAY_YUV_PACKED 0x02
1773 #define I915_OVERLAY_RGB 0x03
1775 #define I915_OVERLAY_DEPTH_MASK 0xff00
1776 #define I915_OVERLAY_RGB24 0x1000
1777 #define I915_OVERLAY_RGB16 0x2000
1778 #define I915_OVERLAY_RGB15 0x3000
1779 #define I915_OVERLAY_YUV422 0x0100
1780 #define I915_OVERLAY_YUV411 0x0200
1781 #define I915_OVERLAY_YUV420 0x0300
1782 #define I915_OVERLAY_YUV410 0x0400
1784 #define I915_OVERLAY_SWAP_MASK 0xff0000
1785 #define I915_OVERLAY_NO_SWAP 0x000000
1786 #define I915_OVERLAY_UV_SWAP 0x010000
1787 #define I915_OVERLAY_Y_SWAP 0x020000
1788 #define I915_OVERLAY_Y_AND_UV_SWAP 0x030000
1790 #define I915_OVERLAY_FLAGS_MASK 0xff000000
1791 #define I915_OVERLAY_ENABLE 0x01000000
1793 struct drm_intel_overlay_put_image {
1794 /* various flags and src format description */
1796 /* source picture description */
1798 /* stride values and offsets are in bytes, buffer relative */
1799 __u16 stride_Y; /* stride for packed formats */
1801 __u32 offset_Y; /* offset for packet formats */
1807 /* to compensate the scaling factors for partially covered surfaces */
1808 __u16 src_scan_width;
1809 __u16 src_scan_height;
1810 /* output crtc description */
1819 #define I915_OVERLAY_UPDATE_ATTRS (1<<0)
1820 #define I915_OVERLAY_UPDATE_GAMMA (1<<1)
1821 #define I915_OVERLAY_DISABLE_DEST_COLORKEY (1<<2)
1822 struct drm_intel_overlay_attrs {
1837 * Intel sprite handling
1839 * Color keying works with a min/mask/max tuple. Both source and destination
1840 * color keying is allowed.
1843 * Sprite pixels within the min & max values, masked against the color channels
1844 * specified in the mask field, will be transparent. All other pixels will
1845 * be displayed on top of the primary plane. For RGB surfaces, only the min
1846 * and mask fields will be used; ranged compares are not allowed.
1848 * Destination keying:
1849 * Primary plane pixels that match the min value, masked against the color
1850 * channels specified in the mask field, will be replaced by corresponding
1851 * pixels from the sprite plane.
1853 * Note that source & destination keying are exclusive; only one can be
1854 * active on a given plane.
1857 #define I915_SET_COLORKEY_NONE (1<<0) /* Deprecated. Instead set
1858 * flags==0 to disable colorkeying.
1860 #define I915_SET_COLORKEY_DESTINATION (1<<1)
1861 #define I915_SET_COLORKEY_SOURCE (1<<2)
1862 struct drm_intel_sprite_colorkey {
1870 struct drm_i915_gem_wait {
1871 /** Handle of BO we shall wait on */
1874 /** Number of nanoseconds to wait, Returns time remaining. */
1878 struct drm_i915_gem_context_create {
1879 __u32 ctx_id; /* output: id of new context*/
1884 * struct drm_i915_gem_context_create_ext - Structure for creating contexts.
1886 struct drm_i915_gem_context_create_ext {
1887 /** @ctx_id: Id of the created context (output) */
1891 * @flags: Supported flags are:
1893 * I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS:
1895 * Extensions may be appended to this structure and driver must check
1896 * for those. See @extensions.
1898 * I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE
1900 * Created context will have single timeline.
1903 #define I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS (1u << 0)
1904 #define I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE (1u << 1)
1905 #define I915_CONTEXT_CREATE_FLAGS_UNKNOWN \
1906 (-(I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE << 1))
1909 * @extensions: Zero-terminated chain of extensions.
1911 * I915_CONTEXT_CREATE_EXT_SETPARAM:
1912 * Context parameter to set or query during context creation.
1913 * See struct drm_i915_gem_context_create_ext_setparam.
1915 * I915_CONTEXT_CREATE_EXT_CLONE:
1916 * This extension has been removed. On the off chance someone somewhere
1917 * has attempted to use it, never re-use this extension number.
1920 #define I915_CONTEXT_CREATE_EXT_SETPARAM 0
1921 #define I915_CONTEXT_CREATE_EXT_CLONE 1
1925 * struct drm_i915_gem_context_param - Context parameter to set or query.
1927 struct drm_i915_gem_context_param {
1928 /** @ctx_id: Context id */
1931 /** @size: Size of the parameter @value */
1934 /** @param: Parameter to set or query */
1936 #define I915_CONTEXT_PARAM_BAN_PERIOD 0x1
1937 /* I915_CONTEXT_PARAM_NO_ZEROMAP has been removed. On the off chance
1938 * someone somewhere has attempted to use it, never re-use this context
1941 #define I915_CONTEXT_PARAM_NO_ZEROMAP 0x2
1942 #define I915_CONTEXT_PARAM_GTT_SIZE 0x3
1943 #define I915_CONTEXT_PARAM_NO_ERROR_CAPTURE 0x4
1944 #define I915_CONTEXT_PARAM_BANNABLE 0x5
1945 #define I915_CONTEXT_PARAM_PRIORITY 0x6
1946 #define I915_CONTEXT_MAX_USER_PRIORITY 1023 /* inclusive */
1947 #define I915_CONTEXT_DEFAULT_PRIORITY 0
1948 #define I915_CONTEXT_MIN_USER_PRIORITY -1023 /* inclusive */
1950 * When using the following param, value should be a pointer to
1951 * drm_i915_gem_context_param_sseu.
1953 #define I915_CONTEXT_PARAM_SSEU 0x7
1956 * Not all clients may want to attempt automatic recover of a context after
1957 * a hang (for example, some clients may only submit very small incremental
1958 * batches relying on known logical state of previous batches which will never
1959 * recover correctly and each attempt will hang), and so would prefer that
1960 * the context is forever banned instead.
1962 * If set to false (0), after a reset, subsequent (and in flight) rendering
1963 * from this context is discarded, and the client will need to create a new
1964 * context to use instead.
1966 * If set to true (1), the kernel will automatically attempt to recover the
1967 * context by skipping the hanging batch and executing the next batch starting
1968 * from the default context state (discarding the incomplete logical context
1969 * state lost due to the reset).
1971 * On creation, all new contexts are marked as recoverable.
1973 #define I915_CONTEXT_PARAM_RECOVERABLE 0x8
1976 * The id of the associated virtual memory address space (ppGTT) of
1977 * this context. Can be retrieved and passed to another context
1978 * (on the same fd) for both to use the same ppGTT and so share
1979 * address layouts, and avoid reloading the page tables on context
1980 * switches between themselves.
1982 * See DRM_I915_GEM_VM_CREATE and DRM_I915_GEM_VM_DESTROY.
1984 #define I915_CONTEXT_PARAM_VM 0x9
1987 * I915_CONTEXT_PARAM_ENGINES:
1989 * Bind this context to operate on this subset of available engines. Henceforth,
1990 * the I915_EXEC_RING selector for DRM_IOCTL_I915_GEM_EXECBUFFER2 operates as
1991 * an index into this array of engines; I915_EXEC_DEFAULT selecting engine[0]
1992 * and upwards. Slots 0...N are filled in using the specified (class, instance).
1994 * engine_class: I915_ENGINE_CLASS_INVALID,
1995 * engine_instance: I915_ENGINE_CLASS_INVALID_NONE
1996 * to specify a gap in the array that can be filled in later, e.g. by a
1997 * virtual engine used for load balancing.
1999 * Setting the number of engines bound to the context to 0, by passing a zero
2000 * sized argument, will revert back to default settings.
2002 * See struct i915_context_param_engines.
2005 * i915_context_engines_load_balance (I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE)
2006 * i915_context_engines_bond (I915_CONTEXT_ENGINES_EXT_BOND)
2007 * i915_context_engines_parallel_submit (I915_CONTEXT_ENGINES_EXT_PARALLEL_SUBMIT)
2009 #define I915_CONTEXT_PARAM_ENGINES 0xa
2012 * I915_CONTEXT_PARAM_PERSISTENCE:
2014 * Allow the context and active rendering to survive the process until
2015 * completion. Persistence allows fire-and-forget clients to queue up a
2016 * bunch of work, hand the output over to a display server and then quit.
2017 * If the context is marked as not persistent, upon closing (either via
2018 * an explicit DRM_I915_GEM_CONTEXT_DESTROY or implicitly from file closure
2019 * or process termination), the context and any outstanding requests will be
2020 * cancelled (and exported fences for cancelled requests marked as -EIO).
2022 * By default, new contexts allow persistence.
2024 #define I915_CONTEXT_PARAM_PERSISTENCE 0xb
2026 /* This API has been removed. On the off chance someone somewhere has
2027 * attempted to use it, never re-use this context param number.
2029 #define I915_CONTEXT_PARAM_RINGSIZE 0xc
2032 * I915_CONTEXT_PARAM_PROTECTED_CONTENT:
2034 * Mark that the context makes use of protected content, which will result
2035 * in the context being invalidated when the protected content session is.
2036 * Given that the protected content session is killed on suspend, the device
2037 * is kept awake for the lifetime of a protected context, so the user should
2038 * make sure to dispose of them once done.
2039 * This flag can only be set at context creation time and, when set to true,
2040 * must be preceded by an explicit setting of I915_CONTEXT_PARAM_RECOVERABLE
2041 * to false. This flag can't be set to true in conjunction with setting the
2042 * I915_CONTEXT_PARAM_BANNABLE flag to false. Creation example:
2046 * struct drm_i915_gem_context_create_ext_setparam p_protected = {
2048 * .name = I915_CONTEXT_CREATE_EXT_SETPARAM,
2051 * .param = I915_CONTEXT_PARAM_PROTECTED_CONTENT,
2055 * struct drm_i915_gem_context_create_ext_setparam p_norecover = {
2057 * .name = I915_CONTEXT_CREATE_EXT_SETPARAM,
2058 * .next_extension = to_user_pointer(&p_protected),
2061 * .param = I915_CONTEXT_PARAM_RECOVERABLE,
2065 * struct drm_i915_gem_context_create_ext create = {
2066 * .flags = I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS,
2067 * .extensions = to_user_pointer(&p_norecover);
2070 * ctx_id = gem_context_create_ext(drm_fd, &create);
2072 * In addition to the normal failure cases, setting this flag during context
2073 * creation can result in the following errors:
2075 * -ENODEV: feature not available
2076 * -EPERM: trying to mark a recoverable or not bannable context as protected
2078 #define I915_CONTEXT_PARAM_PROTECTED_CONTENT 0xd
2079 /* Must be kept compact -- no holes and well documented */
2081 /** @value: Context parameter value to be set or queried */
2086 * Context SSEU programming
2088 * It may be necessary for either functional or performance reason to configure
2089 * a context to run with a reduced number of SSEU (where SSEU stands for Slice/
2092 * This is done by configuring SSEU configuration using the below
2093 * @struct drm_i915_gem_context_param_sseu for every supported engine which
2094 * userspace intends to use.
2096 * Not all GPUs or engines support this functionality in which case an error
2097 * code -ENODEV will be returned.
2099 * Also, flexibility of possible SSEU configuration permutations varies between
2100 * GPU generations and software imposed limitations. Requesting such a
2101 * combination will return an error code of -EINVAL.
2103 * NOTE: When perf/OA is active the context's SSEU configuration is ignored in
2104 * favour of a single global setting.
2106 struct drm_i915_gem_context_param_sseu {
2108 * Engine class & instance to be configured or queried.
2110 struct i915_engine_class_instance engine;
2113 * Unknown flags must be cleared to zero.
2116 #define I915_CONTEXT_SSEU_FLAG_ENGINE_INDEX (1u << 0)
2119 * Mask of slices to enable for the context. Valid values are a subset
2120 * of the bitmask value returned for I915_PARAM_SLICE_MASK.
2125 * Mask of subslices to enable for the context. Valid values are a
2126 * subset of the bitmask value return by I915_PARAM_SUBSLICE_MASK.
2128 __u64 subslice_mask;
2131 * Minimum/Maximum number of EUs to enable per subslice for the
2132 * context. min_eus_per_subslice must be inferior or equal to
2133 * max_eus_per_subslice.
2135 __u16 min_eus_per_subslice;
2136 __u16 max_eus_per_subslice;
2139 * Unused for now. Must be cleared to zero.
2145 * DOC: Virtual Engine uAPI
2147 * Virtual engine is a concept where userspace is able to configure a set of
2148 * physical engines, submit a batch buffer, and let the driver execute it on any
2149 * engine from the set as it sees fit.
2151 * This is primarily useful on parts which have multiple instances of a same
2152 * class engine, like for example GT3+ Skylake parts with their two VCS engines.
2154 * For instance userspace can enumerate all engines of a certain class using the
2155 * previously described `Engine Discovery uAPI`_. After that userspace can
2156 * create a GEM context with a placeholder slot for the virtual engine (using
2157 * `I915_ENGINE_CLASS_INVALID` and `I915_ENGINE_CLASS_INVALID_NONE` for class
2158 * and instance respectively) and finally using the
2159 * `I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE` extension place a virtual engine in
2160 * the same reserved slot.
2162 * Example of creating a virtual engine and submitting a batch buffer to it:
2166 * I915_DEFINE_CONTEXT_ENGINES_LOAD_BALANCE(virtual, 2) = {
2167 * .base.name = I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE,
2168 * .engine_index = 0, // Place this virtual engine into engine map slot 0
2169 * .num_siblings = 2,
2170 * .engines = { { I915_ENGINE_CLASS_VIDEO, 0 },
2171 * { I915_ENGINE_CLASS_VIDEO, 1 }, },
2173 * I915_DEFINE_CONTEXT_PARAM_ENGINES(engines, 1) = {
2174 * .engines = { { I915_ENGINE_CLASS_INVALID,
2175 * I915_ENGINE_CLASS_INVALID_NONE } },
2176 * .extensions = to_user_pointer(&virtual), // Chains after load_balance extension
2178 * struct drm_i915_gem_context_create_ext_setparam p_engines = {
2180 * .name = I915_CONTEXT_CREATE_EXT_SETPARAM,
2183 * .param = I915_CONTEXT_PARAM_ENGINES,
2184 * .value = to_user_pointer(&engines),
2185 * .size = sizeof(engines),
2188 * struct drm_i915_gem_context_create_ext create = {
2189 * .flags = I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS,
2190 * .extensions = to_user_pointer(&p_engines);
2193 * ctx_id = gem_context_create_ext(drm_fd, &create);
2195 * // Now we have created a GEM context with its engine map containing a
2196 * // single virtual engine. Submissions to this slot can go either to
2197 * // vcs0 or vcs1, depending on the load balancing algorithm used inside
2198 * // the driver. The load balancing is dynamic from one batch buffer to
2199 * // another and transparent to userspace.
2202 * execbuf.rsvd1 = ctx_id;
2203 * execbuf.flags = 0; // Submits to index 0 which is the virtual engine
2204 * gem_execbuf(drm_fd, &execbuf);
2208 * i915_context_engines_load_balance:
2210 * Enable load balancing across this set of engines.
2212 * Into the I915_EXEC_DEFAULT slot [0], a virtual engine is created that when
2213 * used will proxy the execbuffer request onto one of the set of engines
2214 * in such a way as to distribute the load evenly across the set.
2216 * The set of engines must be compatible (e.g. the same HW class) as they
2217 * will share the same logical GPU context and ring.
2219 * To intermix rendering with the virtual engine and direct rendering onto
2220 * the backing engines (bypassing the load balancing proxy), the context must
2221 * be defined to use a single timeline for all engines.
2223 struct i915_context_engines_load_balance {
2224 struct i915_user_extension base;
2228 __u32 flags; /* all undefined flags must be zero */
2230 __u64 mbz64; /* reserved for future use; must be zero */
2232 struct i915_engine_class_instance engines[];
2233 } __attribute__((packed));
2235 #define I915_DEFINE_CONTEXT_ENGINES_LOAD_BALANCE(name__, N__) struct { \
2236 struct i915_user_extension base; \
2237 __u16 engine_index; \
2238 __u16 num_siblings; \
2241 struct i915_engine_class_instance engines[N__]; \
2242 } __attribute__((packed)) name__
2245 * i915_context_engines_bond:
2247 * Constructed bonded pairs for execution within a virtual engine.
2249 * All engines are equal, but some are more equal than others. Given
2250 * the distribution of resources in the HW, it may be preferable to run
2251 * a request on a given subset of engines in parallel to a request on a
2252 * specific engine. We enable this selection of engines within a virtual
2253 * engine by specifying bonding pairs, for any given master engine we will
2254 * only execute on one of the corresponding siblings within the virtual engine.
2256 * To execute a request in parallel on the master engine and a sibling requires
2257 * coordination with a I915_EXEC_FENCE_SUBMIT.
2259 struct i915_context_engines_bond {
2260 struct i915_user_extension base;
2262 struct i915_engine_class_instance master;
2264 __u16 virtual_index; /* index of virtual engine in ctx->engines[] */
2267 __u64 flags; /* all undefined flags must be zero */
2268 __u64 mbz64[4]; /* reserved for future use; must be zero */
2270 struct i915_engine_class_instance engines[];
2271 } __attribute__((packed));
2273 #define I915_DEFINE_CONTEXT_ENGINES_BOND(name__, N__) struct { \
2274 struct i915_user_extension base; \
2275 struct i915_engine_class_instance master; \
2276 __u16 virtual_index; \
2280 struct i915_engine_class_instance engines[N__]; \
2281 } __attribute__((packed)) name__
2284 * struct i915_context_engines_parallel_submit - Configure engine for
2285 * parallel submission.
2287 * Setup a slot in the context engine map to allow multiple BBs to be submitted
2288 * in a single execbuf IOCTL. Those BBs will then be scheduled to run on the GPU
2289 * in parallel. Multiple hardware contexts are created internally in the i915 to
2290 * run these BBs. Once a slot is configured for N BBs only N BBs can be
2291 * submitted in each execbuf IOCTL and this is implicit behavior e.g. The user
2292 * doesn't tell the execbuf IOCTL there are N BBs, the execbuf IOCTL knows how
2293 * many BBs there are based on the slot's configuration. The N BBs are the last
2294 * N buffer objects or first N if I915_EXEC_BATCH_FIRST is set.
2296 * The default placement behavior is to create implicit bonds between each
2297 * context if each context maps to more than 1 physical engine (e.g. context is
2298 * a virtual engine). Also we only allow contexts of same engine class and these
2299 * contexts must be in logically contiguous order. Examples of the placement
2300 * behavior are described below. Lastly, the default is to not allow BBs to be
2301 * preempted mid-batch. Rather insert coordinated preemption points on all
2302 * hardware contexts between each set of BBs. Flags could be added in the future
2303 * to change both of these default behaviors.
2305 * Returns -EINVAL if hardware context placement configuration is invalid or if
2306 * the placement configuration isn't supported on the platform / submission
2308 * Returns -ENODEV if extension isn't supported on the platform / submission
2311 * .. code-block:: none
2314 * CS[X] = generic engine of same class, logical instance X
2315 * INVALID = I915_ENGINE_CLASS_INVALID, I915_ENGINE_CLASS_INVALID_NONE
2317 * Example 1 pseudo code:
2318 * set_engines(INVALID)
2319 * set_parallel(engine_index=0, width=2, num_siblings=1,
2320 * engines=CS[0],CS[1])
2322 * Results in the following valid placement:
2325 * Example 2 pseudo code:
2326 * set_engines(INVALID)
2327 * set_parallel(engine_index=0, width=2, num_siblings=2,
2328 * engines=CS[0],CS[2],CS[1],CS[3])
2330 * Results in the following valid placements:
2334 * This can be thought of as two virtual engines, each containing two
2335 * engines thereby making a 2D array. However, there are bonds tying the
2336 * entries together and placing restrictions on how they can be scheduled.
2337 * Specifically, the scheduler can choose only vertical columns from the 2D
2338 * array. That is, CS[0] is bonded to CS[1] and CS[2] to CS[3]. So if the
2339 * scheduler wants to submit to CS[0], it must also choose CS[1] and vice
2340 * versa. Same for CS[2] requires also using CS[3].
2341 * VE[0] = CS[0], CS[2]
2342 * VE[1] = CS[1], CS[3]
2344 * Example 3 pseudo code:
2345 * set_engines(INVALID)
2346 * set_parallel(engine_index=0, width=2, num_siblings=2,
2347 * engines=CS[0],CS[1],CS[1],CS[3])
2349 * Results in the following valid and invalid placements:
2351 * CS[1], CS[3] - Not logically contiguous, return -EINVAL
2353 struct i915_context_engines_parallel_submit {
2355 * @base: base user extension.
2357 struct i915_user_extension base;
2360 * @engine_index: slot for parallel engine
2365 * @width: number of contexts per parallel engine or in other words the
2366 * number of batches in each submission
2371 * @num_siblings: number of siblings per context or in other words the
2372 * number of possible placements for each submission
2377 * @mbz16: reserved for future use; must be zero
2382 * @flags: all undefined flags must be zero, currently not defined flags
2387 * @mbz64: reserved for future use; must be zero
2392 * @engines: 2-d array of engine instances to configure parallel engine
2394 * length = width (i) * num_siblings (j)
2395 * index = j + i * num_siblings
2397 struct i915_engine_class_instance engines[];
2401 #define I915_DEFINE_CONTEXT_ENGINES_PARALLEL_SUBMIT(name__, N__) struct { \
2402 struct i915_user_extension base; \
2403 __u16 engine_index; \
2405 __u16 num_siblings; \
2409 struct i915_engine_class_instance engines[N__]; \
2410 } __attribute__((packed)) name__
2413 * DOC: Context Engine Map uAPI
2415 * Context engine map is a new way of addressing engines when submitting batch-
2416 * buffers, replacing the existing way of using identifiers like `I915_EXEC_BLT`
2417 * inside the flags field of `struct drm_i915_gem_execbuffer2`.
2419 * To use it created GEM contexts need to be configured with a list of engines
2420 * the user is intending to submit to. This is accomplished using the
2421 * `I915_CONTEXT_PARAM_ENGINES` parameter and `struct
2422 * i915_context_param_engines`.
2424 * For such contexts the `I915_EXEC_RING_MASK` field becomes an index into the
2427 * Example of creating such context and submitting against it:
2431 * I915_DEFINE_CONTEXT_PARAM_ENGINES(engines, 2) = {
2432 * .engines = { { I915_ENGINE_CLASS_RENDER, 0 },
2433 * { I915_ENGINE_CLASS_COPY, 0 } }
2435 * struct drm_i915_gem_context_create_ext_setparam p_engines = {
2437 * .name = I915_CONTEXT_CREATE_EXT_SETPARAM,
2440 * .param = I915_CONTEXT_PARAM_ENGINES,
2441 * .value = to_user_pointer(&engines),
2442 * .size = sizeof(engines),
2445 * struct drm_i915_gem_context_create_ext create = {
2446 * .flags = I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS,
2447 * .extensions = to_user_pointer(&p_engines);
2450 * ctx_id = gem_context_create_ext(drm_fd, &create);
2452 * // We have now created a GEM context with two engines in the map:
2453 * // Index 0 points to rcs0 while index 1 points to bcs0. Other engines
2454 * // will not be accessible from this context.
2457 * execbuf.rsvd1 = ctx_id;
2458 * execbuf.flags = 0; // Submits to index 0, which is rcs0 for this context
2459 * gem_execbuf(drm_fd, &execbuf);
2462 * execbuf.rsvd1 = ctx_id;
2463 * execbuf.flags = 1; // Submits to index 0, which is bcs0 for this context
2464 * gem_execbuf(drm_fd, &execbuf);
2467 struct i915_context_param_engines {
2468 __u64 extensions; /* linked chain of extension blocks, 0 terminates */
2469 #define I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE 0 /* see i915_context_engines_load_balance */
2470 #define I915_CONTEXT_ENGINES_EXT_BOND 1 /* see i915_context_engines_bond */
2471 #define I915_CONTEXT_ENGINES_EXT_PARALLEL_SUBMIT 2 /* see i915_context_engines_parallel_submit */
2472 struct i915_engine_class_instance engines[0];
2473 } __attribute__((packed));
2475 #define I915_DEFINE_CONTEXT_PARAM_ENGINES(name__, N__) struct { \
2477 struct i915_engine_class_instance engines[N__]; \
2478 } __attribute__((packed)) name__
2481 * struct drm_i915_gem_context_create_ext_setparam - Context parameter
2482 * to set or query during context creation.
2484 struct drm_i915_gem_context_create_ext_setparam {
2485 /** @base: Extension link. See struct i915_user_extension. */
2486 struct i915_user_extension base;
2489 * @param: Context parameter to set or query.
2490 * See struct drm_i915_gem_context_param.
2492 struct drm_i915_gem_context_param param;
2495 struct drm_i915_gem_context_destroy {
2501 * struct drm_i915_gem_vm_control - Structure to create or destroy VM.
2503 * DRM_I915_GEM_VM_CREATE -
2505 * Create a new virtual memory address space (ppGTT) for use within a context
2506 * on the same file. Extensions can be provided to configure exactly how the
2507 * address space is setup upon creation.
2509 * The id of new VM (bound to the fd) for use with I915_CONTEXT_PARAM_VM is
2510 * returned in the outparam @id.
2512 * An extension chain maybe provided, starting with @extensions, and terminated
2513 * by the @next_extension being 0. Currently, no extensions are defined.
2515 * DRM_I915_GEM_VM_DESTROY -
2517 * Destroys a previously created VM id, specified in @vm_id.
2519 * No extensions or flags are allowed currently, and so must be zero.
2521 struct drm_i915_gem_vm_control {
2522 /** @extensions: Zero-terminated chain of extensions. */
2525 /** @flags: reserved for future usage, currently MBZ */
2528 /** @vm_id: Id of the VM created or to be destroyed */
2532 struct drm_i915_reg_read {
2535 * For 64bit wide registers where the upper 32bits don't immediately
2536 * follow the lower 32bits, the offset of the lower 32bits must
2540 #define I915_REG_READ_8B_WA (1ul << 0)
2542 __u64 val; /* Return value */
2547 * Render engine timestamp - 0x2358 + 64bit - gen7+
2548 * - Note this register returns an invalid value if using the default
2549 * single instruction 8byte read, in order to workaround that pass
2550 * flag I915_REG_READ_8B_WA in offset field.
2554 struct drm_i915_reset_stats {
2558 /* All resets since boot/module reload, for all contexts */
2561 /* Number of batches lost when active in GPU, for this context */
2564 /* Number of batches lost pending for execution, for this context */
2565 __u32 batch_pending;
2571 * struct drm_i915_gem_userptr - Create GEM object from user allocated memory.
2573 * Userptr objects have several restrictions on what ioctls can be used with the
2576 struct drm_i915_gem_userptr {
2578 * @user_ptr: The pointer to the allocated memory.
2580 * Needs to be aligned to PAGE_SIZE.
2587 * The size in bytes for the allocated memory. This will also become the
2590 * Needs to be aligned to PAGE_SIZE, and should be at least PAGE_SIZE,
2600 * I915_USERPTR_READ_ONLY:
2602 * Mark the object as readonly, this also means GPU access can only be
2603 * readonly. This is only supported on HW which supports readonly access
2604 * through the GTT. If the HW can't support readonly access, an error is
2607 * I915_USERPTR_PROBE:
2609 * Probe the provided @user_ptr range and validate that the @user_ptr is
2610 * indeed pointing to normal memory and that the range is also valid.
2611 * For example if some garbage address is given to the kernel, then this
2614 * Returns -EFAULT if the probe failed.
2616 * Note that this doesn't populate the backing pages, and also doesn't
2617 * guarantee that the object will remain valid when the object is
2620 * The kernel supports this feature if I915_PARAM_HAS_USERPTR_PROBE
2621 * returns a non-zero value.
2623 * I915_USERPTR_UNSYNCHRONIZED:
2625 * NOT USED. Setting this flag will result in an error.
2628 #define I915_USERPTR_READ_ONLY 0x1
2629 #define I915_USERPTR_PROBE 0x2
2630 #define I915_USERPTR_UNSYNCHRONIZED 0x80000000
2632 * @handle: Returned handle for the object.
2634 * Object handles are nonzero.
2639 enum drm_i915_oa_format {
2640 I915_OA_FORMAT_A13 = 1, /* HSW only */
2641 I915_OA_FORMAT_A29, /* HSW only */
2642 I915_OA_FORMAT_A13_B8_C8, /* HSW only */
2643 I915_OA_FORMAT_B4_C8, /* HSW only */
2644 I915_OA_FORMAT_A45_B8_C8, /* HSW only */
2645 I915_OA_FORMAT_B4_C8_A16, /* HSW only */
2646 I915_OA_FORMAT_C4_B8, /* HSW+ */
2650 I915_OA_FORMAT_A12_B8_C8,
2651 I915_OA_FORMAT_A32u40_A4u32_B8_C8,
2653 I915_OA_FORMAT_MAX /* non-ABI */
2656 enum drm_i915_perf_property_id {
2658 * Open the stream for a specific context handle (as used with
2659 * execbuffer2). A stream opened for a specific context this way
2660 * won't typically require root privileges.
2662 * This property is available in perf revision 1.
2664 DRM_I915_PERF_PROP_CTX_HANDLE = 1,
2667 * A value of 1 requests the inclusion of raw OA unit reports as
2668 * part of stream samples.
2670 * This property is available in perf revision 1.
2672 DRM_I915_PERF_PROP_SAMPLE_OA,
2675 * The value specifies which set of OA unit metrics should be
2676 * configured, defining the contents of any OA unit reports.
2678 * This property is available in perf revision 1.
2680 DRM_I915_PERF_PROP_OA_METRICS_SET,
2683 * The value specifies the size and layout of OA unit reports.
2685 * This property is available in perf revision 1.
2687 DRM_I915_PERF_PROP_OA_FORMAT,
2690 * Specifying this property implicitly requests periodic OA unit
2691 * sampling and (at least on Haswell) the sampling frequency is derived
2692 * from this exponent as follows:
2694 * 80ns * 2^(period_exponent + 1)
2696 * This property is available in perf revision 1.
2698 DRM_I915_PERF_PROP_OA_EXPONENT,
2701 * Specifying this property is only valid when specify a context to
2702 * filter with DRM_I915_PERF_PROP_CTX_HANDLE. Specifying this property
2703 * will hold preemption of the particular context we want to gather
2704 * performance data about. The execbuf2 submissions must include a
2705 * drm_i915_gem_execbuffer_ext_perf parameter for this to apply.
2707 * This property is available in perf revision 3.
2709 DRM_I915_PERF_PROP_HOLD_PREEMPTION,
2712 * Specifying this pins all contexts to the specified SSEU power
2713 * configuration for the duration of the recording.
2715 * This parameter's value is a pointer to a struct
2716 * drm_i915_gem_context_param_sseu.
2718 * This property is available in perf revision 4.
2720 DRM_I915_PERF_PROP_GLOBAL_SSEU,
2723 * This optional parameter specifies the timer interval in nanoseconds
2724 * at which the i915 driver will check the OA buffer for available data.
2725 * Minimum allowed value is 100 microseconds. A default value is used by
2726 * the driver if this parameter is not specified. Note that larger timer
2727 * values will reduce cpu consumption during OA perf captures. However,
2728 * excessively large values would potentially result in OA buffer
2729 * overwrites as captures reach end of the OA buffer.
2731 * This property is available in perf revision 5.
2733 DRM_I915_PERF_PROP_POLL_OA_PERIOD,
2735 DRM_I915_PERF_PROP_MAX /* non-ABI */
2738 struct drm_i915_perf_open_param {
2740 #define I915_PERF_FLAG_FD_CLOEXEC (1<<0)
2741 #define I915_PERF_FLAG_FD_NONBLOCK (1<<1)
2742 #define I915_PERF_FLAG_DISABLED (1<<2)
2744 /** The number of u64 (id, value) pairs */
2745 __u32 num_properties;
2748 * Pointer to array of u64 (id, value) pairs configuring the stream
2751 __u64 properties_ptr;
2755 * Enable data capture for a stream that was either opened in a disabled state
2756 * via I915_PERF_FLAG_DISABLED or was later disabled via
2757 * I915_PERF_IOCTL_DISABLE.
2759 * It is intended to be cheaper to disable and enable a stream than it may be
2760 * to close and re-open a stream with the same configuration.
2762 * It's undefined whether any pending data for the stream will be lost.
2764 * This ioctl is available in perf revision 1.
2766 #define I915_PERF_IOCTL_ENABLE _IO('i', 0x0)
2769 * Disable data capture for a stream.
2771 * It is an error to try and read a stream that is disabled.
2773 * This ioctl is available in perf revision 1.
2775 #define I915_PERF_IOCTL_DISABLE _IO('i', 0x1)
2778 * Change metrics_set captured by a stream.
2780 * If the stream is bound to a specific context, the configuration change
2781 * will performed inline with that context such that it takes effect before
2782 * the next execbuf submission.
2784 * Returns the previously bound metrics set id, or a negative error code.
2786 * This ioctl is available in perf revision 2.
2788 #define I915_PERF_IOCTL_CONFIG _IO('i', 0x2)
2791 * Common to all i915 perf records
2793 struct drm_i915_perf_record_header {
2799 enum drm_i915_perf_record_type {
2802 * Samples are the work horse record type whose contents are extensible
2803 * and defined when opening an i915 perf stream based on the given
2806 * Boolean properties following the naming convention
2807 * DRM_I915_PERF_SAMPLE_xyz_PROP request the inclusion of 'xyz' data in
2810 * The order of these sample properties given by userspace has no
2811 * affect on the ordering of data within a sample. The order is
2815 * struct drm_i915_perf_record_header header;
2817 * { u32 oa_report[]; } && DRM_I915_PERF_PROP_SAMPLE_OA
2820 DRM_I915_PERF_RECORD_SAMPLE = 1,
2823 * Indicates that one or more OA reports were not written by the
2824 * hardware. This can happen for example if an MI_REPORT_PERF_COUNT
2825 * command collides with periodic sampling - which would be more likely
2826 * at higher sampling frequencies.
2828 DRM_I915_PERF_RECORD_OA_REPORT_LOST = 2,
2831 * An error occurred that resulted in all pending OA reports being lost.
2833 DRM_I915_PERF_RECORD_OA_BUFFER_LOST = 3,
2835 DRM_I915_PERF_RECORD_MAX /* non-ABI */
2839 * struct drm_i915_perf_oa_config
2841 * Structure to upload perf dynamic configuration into the kernel.
2843 struct drm_i915_perf_oa_config {
2847 * String formatted like "%\08x-%\04x-%\04x-%\04x-%\012x"
2854 * Number of mux regs in &mux_regs_ptr.
2861 * Number of boolean regs in &boolean_regs_ptr.
2863 __u32 n_boolean_regs;
2868 * Number of flex regs in &flex_regs_ptr.
2875 * Pointer to tuples of u32 values (register address, value) for mux
2876 * registers. Expected length of buffer is (2 * sizeof(u32) *
2882 * @boolean_regs_ptr:
2884 * Pointer to tuples of u32 values (register address, value) for mux
2885 * registers. Expected length of buffer is (2 * sizeof(u32) *
2888 __u64 boolean_regs_ptr;
2893 * Pointer to tuples of u32 values (register address, value) for mux
2894 * registers. Expected length of buffer is (2 * sizeof(u32) *
2897 __u64 flex_regs_ptr;
2901 * struct drm_i915_query_item - An individual query for the kernel to process.
2903 * The behaviour is determined by the @query_id. Note that exactly what
2904 * @data_ptr is also depends on the specific @query_id.
2906 struct drm_i915_query_item {
2910 * The id for this query. Currently accepted query IDs are:
2911 * - %DRM_I915_QUERY_TOPOLOGY_INFO (see struct drm_i915_query_topology_info)
2912 * - %DRM_I915_QUERY_ENGINE_INFO (see struct drm_i915_engine_info)
2913 * - %DRM_I915_QUERY_PERF_CONFIG (see struct drm_i915_query_perf_config)
2914 * - %DRM_I915_QUERY_MEMORY_REGIONS (see struct drm_i915_query_memory_regions)
2915 * - %DRM_I915_QUERY_HWCONFIG_BLOB (see `GuC HWCONFIG blob uAPI`)
2916 * - %DRM_I915_QUERY_GEOMETRY_SUBSLICES (see struct drm_i915_query_topology_info)
2919 #define DRM_I915_QUERY_TOPOLOGY_INFO 1
2920 #define DRM_I915_QUERY_ENGINE_INFO 2
2921 #define DRM_I915_QUERY_PERF_CONFIG 3
2922 #define DRM_I915_QUERY_MEMORY_REGIONS 4
2923 #define DRM_I915_QUERY_HWCONFIG_BLOB 5
2924 #define DRM_I915_QUERY_GEOMETRY_SUBSLICES 6
2925 /* Must be kept compact -- no holes and well documented */
2930 * When set to zero by userspace, this is filled with the size of the
2931 * data to be written at the @data_ptr pointer. The kernel sets this
2932 * value to a negative value to signal an error on a particular query
2940 * When &query_id == %DRM_I915_QUERY_TOPOLOGY_INFO, must be 0.
2942 * When &query_id == %DRM_I915_QUERY_PERF_CONFIG, must be one of the
2945 * - %DRM_I915_QUERY_PERF_CONFIG_LIST
2946 * - %DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID
2947 * - %DRM_I915_QUERY_PERF_CONFIG_FOR_UUID
2949 * When &query_id == %DRM_I915_QUERY_GEOMETRY_SUBSLICES must contain
2950 * a struct i915_engine_class_instance that references a render engine.
2953 #define DRM_I915_QUERY_PERF_CONFIG_LIST 1
2954 #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2
2955 #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID 3
2960 * Data will be written at the location pointed by @data_ptr when the
2961 * value of @length matches the length of the data to be written by the
2968 * struct drm_i915_query - Supply an array of struct drm_i915_query_item for the
2969 * kernel to fill out.
2971 * Note that this is generally a two step process for each struct
2972 * drm_i915_query_item in the array:
2974 * 1. Call the DRM_IOCTL_I915_QUERY, giving it our array of struct
2975 * drm_i915_query_item, with &drm_i915_query_item.length set to zero. The
2976 * kernel will then fill in the size, in bytes, which tells userspace how
2977 * memory it needs to allocate for the blob(say for an array of properties).
2979 * 2. Next we call DRM_IOCTL_I915_QUERY again, this time with the
2980 * &drm_i915_query_item.data_ptr equal to our newly allocated blob. Note that
2981 * the &drm_i915_query_item.length should still be the same as what the
2982 * kernel previously set. At this point the kernel can fill in the blob.
2984 * Note that for some query items it can make sense for userspace to just pass
2985 * in a buffer/blob equal to or larger than the required size. In this case only
2986 * a single ioctl call is needed. For some smaller query items this can work
2990 struct drm_i915_query {
2991 /** @num_items: The number of elements in the @items_ptr array */
2995 * @flags: Unused for now. Must be cleared to zero.
3002 * Pointer to an array of struct drm_i915_query_item. The number of
3003 * array elements is @num_items.
3009 * struct drm_i915_query_topology_info
3011 * Describes slice/subslice/EU information queried by
3012 * %DRM_I915_QUERY_TOPOLOGY_INFO
3014 struct drm_i915_query_topology_info {
3018 * Unused for now. Must be cleared to zero.
3025 * The number of bits used to express the slice mask.
3032 * The number of bits used to express the subslice mask.
3034 __u16 max_subslices;
3037 * @max_eus_per_subslice:
3039 * The number of bits in the EU mask that correspond to a single
3042 __u16 max_eus_per_subslice;
3047 * Offset in data[] at which the subslice masks are stored.
3049 __u16 subslice_offset;
3054 * Stride at which each of the subslice masks for each slice are
3057 __u16 subslice_stride;
3062 * Offset in data[] at which the EU masks are stored.
3069 * Stride at which each of the EU masks for each subslice are stored.
3076 * Contains 3 pieces of information :
3078 * - The slice mask with one bit per slice telling whether a slice is
3079 * available. The availability of slice X can be queried with the
3080 * following formula :
3084 * (data[X / 8] >> (X % 8)) & 1
3086 * Starting with Xe_HP platforms, Intel hardware no longer has
3087 * traditional slices so i915 will always report a single slice
3088 * (hardcoded slicemask = 0x1) which contains all of the platform's
3089 * subslices. I.e., the mask here does not reflect any of the newer
3090 * hardware concepts such as "gslices" or "cslices" since userspace
3091 * is capable of inferring those from the subslice mask.
3093 * - The subslice mask for each slice with one bit per subslice telling
3094 * whether a subslice is available. Starting with Gen12 we use the
3095 * term "subslice" to refer to what the hardware documentation
3096 * describes as a "dual-subslices." The availability of subslice Y
3097 * in slice X can be queried with the following formula :
3101 * (data[subslice_offset + X * subslice_stride + Y / 8] >> (Y % 8)) & 1
3103 * - The EU mask for each subslice in each slice, with one bit per EU
3104 * telling whether an EU is available. The availability of EU Z in
3105 * subslice Y in slice X can be queried with the following formula :
3110 * (X * max_subslices + Y) * eu_stride +
3118 * DOC: Engine Discovery uAPI
3120 * Engine discovery uAPI is a way of enumerating physical engines present in a
3121 * GPU associated with an open i915 DRM file descriptor. This supersedes the old
3122 * way of using `DRM_IOCTL_I915_GETPARAM` and engine identifiers like
3123 * `I915_PARAM_HAS_BLT`.
3125 * The need for this interface came starting with Icelake and newer GPUs, which
3126 * started to establish a pattern of having multiple engines of a same class,
3127 * where not all instances were always completely functionally equivalent.
3129 * Entry point for this uapi is `DRM_IOCTL_I915_QUERY` with the
3130 * `DRM_I915_QUERY_ENGINE_INFO` as the queried item id.
3132 * Example for getting the list of engines:
3136 * struct drm_i915_query_engine_info *info;
3137 * struct drm_i915_query_item item = {
3138 * .query_id = DRM_I915_QUERY_ENGINE_INFO;
3140 * struct drm_i915_query query = {
3142 * .items_ptr = (uintptr_t)&item,
3146 * // First query the size of the blob we need, this needs to be large
3147 * // enough to hold our array of engines. The kernel will fill out the
3148 * // item.length for us, which is the number of bytes we need.
3150 * // Alternatively a large buffer can be allocated straight away enabling
3151 * // querying in one pass, in which case item.length should contain the
3152 * // length of the provided buffer.
3153 * err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query);
3156 * info = calloc(1, item.length);
3157 * // Now that we allocated the required number of bytes, we call the ioctl
3158 * // again, this time with the data_ptr pointing to our newly allocated
3159 * // blob, which the kernel can then populate with info on all engines.
3160 * item.data_ptr = (uintptr_t)&info,
3162 * err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query);
3165 * // We can now access each engine in the array
3166 * for (i = 0; i < info->num_engines; i++) {
3167 * struct drm_i915_engine_info einfo = info->engines[i];
3168 * u16 class = einfo.engine.class;
3169 * u16 instance = einfo.engine.instance;
3175 * Each of the enumerated engines, apart from being defined by its class and
3176 * instance (see `struct i915_engine_class_instance`), also can have flags and
3177 * capabilities defined as documented in i915_drm.h.
3179 * For instance video engines which support HEVC encoding will have the
3180 * `I915_VIDEO_CLASS_CAPABILITY_HEVC` capability bit set.
3182 * Engine discovery only fully comes to its own when combined with the new way
3183 * of addressing engines when submitting batch buffers using contexts with
3184 * engine maps configured.
3188 * struct drm_i915_engine_info
3190 * Describes one engine and it's capabilities as known to the driver.
3192 struct drm_i915_engine_info {
3193 /** @engine: Engine class and instance. */
3194 struct i915_engine_class_instance engine;
3196 /** @rsvd0: Reserved field. */
3199 /** @flags: Engine flags. */
3201 #define I915_ENGINE_INFO_HAS_LOGICAL_INSTANCE (1 << 0)
3203 /** @capabilities: Capabilities of this engine. */
3205 #define I915_VIDEO_CLASS_CAPABILITY_HEVC (1 << 0)
3206 #define I915_VIDEO_AND_ENHANCE_CLASS_CAPABILITY_SFC (1 << 1)
3208 /** @logical_instance: Logical instance of engine */
3209 __u16 logical_instance;
3211 /** @rsvd1: Reserved fields. */
3213 /** @rsvd2: Reserved fields. */
3218 * struct drm_i915_query_engine_info
3220 * Engine info query enumerates all engines known to the driver by filling in
3221 * an array of struct drm_i915_engine_info structures.
3223 struct drm_i915_query_engine_info {
3224 /** @num_engines: Number of struct drm_i915_engine_info structs following. */
3230 /** @engines: Marker for drm_i915_engine_info structures. */
3231 struct drm_i915_engine_info engines[];
3235 * struct drm_i915_query_perf_config
3237 * Data written by the kernel with query %DRM_I915_QUERY_PERF_CONFIG and
3238 * %DRM_I915_QUERY_GEOMETRY_SUBSLICES.
3240 struct drm_i915_query_perf_config {
3245 * When &drm_i915_query_item.flags ==
3246 * %DRM_I915_QUERY_PERF_CONFIG_LIST, i915 sets this fields to
3247 * the number of configurations available.
3254 * When &drm_i915_query_item.flags ==
3255 * %DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID, i915 will use the
3256 * value in this field as configuration identifier to decide
3257 * what data to write into config_ptr.
3264 * When &drm_i915_query_item.flags ==
3265 * %DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID, i915 will use the
3266 * value in this field as configuration identifier to decide
3267 * what data to write into config_ptr.
3269 * String formatted like "%08x-%04x-%04x-%04x-%012x"
3277 * Unused for now. Must be cleared to zero.
3284 * When &drm_i915_query_item.flags == %DRM_I915_QUERY_PERF_CONFIG_LIST,
3285 * i915 will write an array of __u64 of configuration identifiers.
3287 * When &drm_i915_query_item.flags == %DRM_I915_QUERY_PERF_CONFIG_DATA,
3288 * i915 will write a struct drm_i915_perf_oa_config. If the following
3289 * fields of struct drm_i915_perf_oa_config are not set to 0, i915 will
3290 * write into the associated pointers the values of submitted when the
3291 * configuration was created :
3293 * - &drm_i915_perf_oa_config.n_mux_regs
3294 * - &drm_i915_perf_oa_config.n_boolean_regs
3295 * - &drm_i915_perf_oa_config.n_flex_regs
3301 * enum drm_i915_gem_memory_class - Supported memory classes
3303 enum drm_i915_gem_memory_class {
3304 /** @I915_MEMORY_CLASS_SYSTEM: System memory */
3305 I915_MEMORY_CLASS_SYSTEM = 0,
3306 /** @I915_MEMORY_CLASS_DEVICE: Device local-memory */
3307 I915_MEMORY_CLASS_DEVICE,
3311 * struct drm_i915_gem_memory_class_instance - Identify particular memory region
3313 struct drm_i915_gem_memory_class_instance {
3314 /** @memory_class: See enum drm_i915_gem_memory_class */
3317 /** @memory_instance: Which instance */
3318 __u16 memory_instance;
3322 * struct drm_i915_memory_region_info - Describes one region as known to the
3325 * Note this is using both struct drm_i915_query_item and struct drm_i915_query.
3326 * For this new query we are adding the new query id DRM_I915_QUERY_MEMORY_REGIONS
3327 * at &drm_i915_query_item.query_id.
3329 struct drm_i915_memory_region_info {
3330 /** @region: The class:instance pair encoding */
3331 struct drm_i915_gem_memory_class_instance region;
3337 * @probed_size: Memory probed by the driver
3339 * Note that it should not be possible to ever encounter a zero value
3340 * here, also note that no current region type will ever return -1 here.
3341 * Although for future region types, this might be a possibility. The
3342 * same applies to the other size fields.
3347 * @unallocated_size: Estimate of memory remaining
3349 * Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliable accounting.
3350 * Without this (or if this is an older kernel) the value here will
3351 * always equal the @probed_size. Note this is only currently tracked
3352 * for I915_MEMORY_CLASS_DEVICE regions (for other types the value here
3353 * will always equal the @probed_size).
3355 __u64 unallocated_size;
3362 * @probed_cpu_visible_size: Memory probed by the driver
3363 * that is CPU accessible.
3365 * This will be always be <= @probed_size, and the
3366 * remainder (if there is any) will not be CPU
3369 * On systems without small BAR, the @probed_size will
3370 * always equal the @probed_cpu_visible_size, since all
3371 * of it will be CPU accessible.
3373 * Note this is only tracked for
3374 * I915_MEMORY_CLASS_DEVICE regions (for other types the
3375 * value here will always equal the @probed_size).
3377 * Note that if the value returned here is zero, then
3378 * this must be an old kernel which lacks the relevant
3379 * small-bar uAPI support (including
3380 * I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS), but on
3381 * such systems we should never actually end up with a
3382 * small BAR configuration, assuming we are able to load
3383 * the kernel module. Hence it should be safe to treat
3384 * this the same as when @probed_cpu_visible_size ==
3387 __u64 probed_cpu_visible_size;
3390 * @unallocated_cpu_visible_size: Estimate of CPU
3391 * visible memory remaining.
3393 * Note this is only tracked for
3394 * I915_MEMORY_CLASS_DEVICE regions (for other types the
3395 * value here will always equal the
3396 * @probed_cpu_visible_size).
3398 * Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliable
3399 * accounting. Without this the value here will always
3400 * equal the @probed_cpu_visible_size. Note this is only
3401 * currently tracked for I915_MEMORY_CLASS_DEVICE
3402 * regions (for other types the value here will also
3403 * always equal the @probed_cpu_visible_size).
3405 * If this is an older kernel the value here will be
3406 * zero, see also @probed_cpu_visible_size.
3408 __u64 unallocated_cpu_visible_size;
3414 * struct drm_i915_query_memory_regions
3416 * The region info query enumerates all regions known to the driver by filling
3417 * in an array of struct drm_i915_memory_region_info structures.
3419 * Example for getting the list of supported regions:
3423 * struct drm_i915_query_memory_regions *info;
3424 * struct drm_i915_query_item item = {
3425 * .query_id = DRM_I915_QUERY_MEMORY_REGIONS;
3427 * struct drm_i915_query query = {
3429 * .items_ptr = (uintptr_t)&item,
3433 * // First query the size of the blob we need, this needs to be large
3434 * // enough to hold our array of regions. The kernel will fill out the
3435 * // item.length for us, which is the number of bytes we need.
3436 * err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query);
3439 * info = calloc(1, item.length);
3440 * // Now that we allocated the required number of bytes, we call the ioctl
3441 * // again, this time with the data_ptr pointing to our newly allocated
3442 * // blob, which the kernel can then populate with the all the region info.
3443 * item.data_ptr = (uintptr_t)&info,
3445 * err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query);
3448 * // We can now access each region in the array
3449 * for (i = 0; i < info->num_regions; i++) {
3450 * struct drm_i915_memory_region_info mr = info->regions[i];
3451 * u16 class = mr.region.class;
3452 * u16 instance = mr.region.instance;
3459 struct drm_i915_query_memory_regions {
3460 /** @num_regions: Number of supported regions */
3466 /** @regions: Info about each supported region */
3467 struct drm_i915_memory_region_info regions[];
3471 * DOC: GuC HWCONFIG blob uAPI
3473 * The GuC produces a blob with information about the current device.
3474 * i915 reads this blob from GuC and makes it available via this uAPI.
3476 * The format and meaning of the blob content are documented in the
3477 * Programmer's Reference Manual.
3481 * struct drm_i915_gem_create_ext - Existing gem_create behaviour, with added
3482 * extension support using struct i915_user_extension.
3484 * Note that new buffer flags should be added here, at least for the stuff that
3485 * is immutable. Previously we would have two ioctls, one to create the object
3486 * with gem_create, and another to apply various parameters, however this
3487 * creates some ambiguity for the params which are considered immutable. Also in
3488 * general we're phasing out the various SET/GET ioctls.
3490 struct drm_i915_gem_create_ext {
3492 * @size: Requested size for the object.
3494 * The (page-aligned) allocated size for the object will be returned.
3496 * DG2 64K min page size implications:
3498 * On discrete platforms, starting from DG2, we have to contend with GTT
3499 * page size restrictions when dealing with I915_MEMORY_CLASS_DEVICE
3500 * objects. Specifically the hardware only supports 64K or larger GTT
3501 * page sizes for such memory. The kernel will already ensure that all
3502 * I915_MEMORY_CLASS_DEVICE memory is allocated using 64K or larger page
3505 * Note that the returned size here will always reflect any required
3506 * rounding up done by the kernel, i.e 4K will now become 64K on devices
3507 * such as DG2. The kernel will always select the largest minimum
3508 * page-size for the set of possible placements as the value to use when
3509 * rounding up the @size.
3511 * Special DG2 GTT address alignment requirement:
3513 * The GTT alignment will also need to be at least 2M for such objects.
3515 * Note that due to how the hardware implements 64K GTT page support, we
3516 * have some further complications:
3518 * 1) The entire PDE (which covers a 2MB virtual address range), must
3519 * contain only 64K PTEs, i.e mixing 4K and 64K PTEs in the same
3520 * PDE is forbidden by the hardware.
3522 * 2) We still need to support 4K PTEs for I915_MEMORY_CLASS_SYSTEM
3525 * To keep things simple for userland, we mandate that any GTT mappings
3526 * must be aligned to and rounded up to 2MB. The kernel will internally
3527 * pad them out to the next 2MB boundary. As this only wastes virtual
3528 * address space and avoids userland having to copy any needlessly
3529 * complicated PDE sharing scheme (coloring) and only affects DG2, this
3530 * is deemed to be a good compromise.
3535 * @handle: Returned handle for the object.
3537 * Object handles are nonzero.
3542 * @flags: Optional flags.
3546 * I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS - Signal to the kernel that
3547 * the object will need to be accessed via the CPU.
3549 * Only valid when placing objects in I915_MEMORY_CLASS_DEVICE, and only
3550 * strictly required on configurations where some subset of the device
3551 * memory is directly visible/mappable through the CPU (which we also
3552 * call small BAR), like on some DG2+ systems. Note that this is quite
3553 * undesirable, but due to various factors like the client CPU, BIOS etc
3554 * it's something we can expect to see in the wild. See
3555 * &drm_i915_memory_region_info.probed_cpu_visible_size for how to
3556 * determine if this system applies.
3558 * Note that one of the placements MUST be I915_MEMORY_CLASS_SYSTEM, to
3559 * ensure the kernel can always spill the allocation to system memory,
3560 * if the object can't be allocated in the mappable part of
3561 * I915_MEMORY_CLASS_DEVICE.
3563 * Also note that since the kernel only supports flat-CCS on objects
3564 * that can *only* be placed in I915_MEMORY_CLASS_DEVICE, we therefore
3565 * don't support I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS together with
3568 * Without this hint, the kernel will assume that non-mappable
3569 * I915_MEMORY_CLASS_DEVICE is preferred for this object. Note that the
3570 * kernel can still migrate the object to the mappable part, as a last
3571 * resort, if userspace ever CPU faults this object, but this might be
3572 * expensive, and so ideally should be avoided.
3574 * On older kernels which lack the relevant small-bar uAPI support (see
3575 * also &drm_i915_memory_region_info.probed_cpu_visible_size),
3576 * usage of the flag will result in an error, but it should NEVER be
3577 * possible to end up with a small BAR configuration, assuming we can
3578 * also successfully load the i915 kernel module. In such cases the
3579 * entire I915_MEMORY_CLASS_DEVICE region will be CPU accessible, and as
3580 * such there are zero restrictions on where the object can be placed.
3582 #define I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS (1 << 0)
3586 * @extensions: The chain of extensions to apply to this object.
3588 * This will be useful in the future when we need to support several
3589 * different extensions, and we need to apply more than one when
3590 * creating the object. See struct i915_user_extension.
3592 * If we don't supply any extensions then we get the same old gem_create
3595 * For I915_GEM_CREATE_EXT_MEMORY_REGIONS usage see
3596 * struct drm_i915_gem_create_ext_memory_regions.
3598 * For I915_GEM_CREATE_EXT_PROTECTED_CONTENT usage see
3599 * struct drm_i915_gem_create_ext_protected_content.
3601 #define I915_GEM_CREATE_EXT_MEMORY_REGIONS 0
3602 #define I915_GEM_CREATE_EXT_PROTECTED_CONTENT 1
3607 * struct drm_i915_gem_create_ext_memory_regions - The
3608 * I915_GEM_CREATE_EXT_MEMORY_REGIONS extension.
3610 * Set the object with the desired set of placements/regions in priority
3611 * order. Each entry must be unique and supported by the device.
3613 * This is provided as an array of struct drm_i915_gem_memory_class_instance, or
3614 * an equivalent layout of class:instance pair encodings. See struct
3615 * drm_i915_query_memory_regions and DRM_I915_QUERY_MEMORY_REGIONS for how to
3616 * query the supported regions for a device.
3618 * As an example, on discrete devices, if we wish to set the placement as
3619 * device local-memory we can do something like:
3623 * struct drm_i915_gem_memory_class_instance region_lmem = {
3624 * .memory_class = I915_MEMORY_CLASS_DEVICE,
3625 * .memory_instance = 0,
3627 * struct drm_i915_gem_create_ext_memory_regions regions = {
3628 * .base = { .name = I915_GEM_CREATE_EXT_MEMORY_REGIONS },
3629 * .regions = (uintptr_t)®ion_lmem,
3632 * struct drm_i915_gem_create_ext create_ext = {
3633 * .size = 16 * PAGE_SIZE,
3634 * .extensions = (uintptr_t)®ions,
3637 * int err = ioctl(fd, DRM_IOCTL_I915_GEM_CREATE_EXT, &create_ext);
3640 * At which point we get the object handle in &drm_i915_gem_create_ext.handle,
3641 * along with the final object size in &drm_i915_gem_create_ext.size, which
3642 * should account for any rounding up, if required.
3644 * Note that userspace has no means of knowing the current backing region
3645 * for objects where @num_regions is larger than one. The kernel will only
3646 * ensure that the priority order of the @regions array is honoured, either
3647 * when initially placing the object, or when moving memory around due to
3650 * On Flat-CCS capable HW, compression is supported for the objects residing
3651 * in I915_MEMORY_CLASS_DEVICE. When such objects (compressed) have other
3652 * memory class in @regions and migrated (by i915, due to memory
3653 * constraints) to the non I915_MEMORY_CLASS_DEVICE region, then i915 needs to
3654 * decompress the content. But i915 doesn't have the required information to
3655 * decompress the userspace compressed objects.
3657 * So i915 supports Flat-CCS, on the objects which can reside only on
3658 * I915_MEMORY_CLASS_DEVICE regions.
3660 struct drm_i915_gem_create_ext_memory_regions {
3661 /** @base: Extension link. See struct i915_user_extension. */
3662 struct i915_user_extension base;
3666 /** @num_regions: Number of elements in the @regions array. */
3669 * @regions: The regions/placements array.
3671 * An array of struct drm_i915_gem_memory_class_instance.
3677 * struct drm_i915_gem_create_ext_protected_content - The
3678 * I915_OBJECT_PARAM_PROTECTED_CONTENT extension.
3680 * If this extension is provided, buffer contents are expected to be protected
3681 * by PXP encryption and require decryption for scan out and processing. This
3682 * is only possible on platforms that have PXP enabled, on all other scenarios
3683 * using this extension will cause the ioctl to fail and return -ENODEV. The
3684 * flags parameter is reserved for future expansion and must currently be set
3687 * The buffer contents are considered invalid after a PXP session teardown.
3689 * The encryption is guaranteed to be processed correctly only if the object
3690 * is submitted with a context created using the
3691 * I915_CONTEXT_PARAM_PROTECTED_CONTENT flag. This will also enable extra checks
3692 * at submission time on the validity of the objects involved.
3694 * Below is an example on how to create a protected object:
3698 * struct drm_i915_gem_create_ext_protected_content protected_ext = {
3699 * .base = { .name = I915_GEM_CREATE_EXT_PROTECTED_CONTENT },
3702 * struct drm_i915_gem_create_ext create_ext = {
3703 * .size = PAGE_SIZE,
3704 * .extensions = (uintptr_t)&protected_ext,
3707 * int err = ioctl(fd, DRM_IOCTL_I915_GEM_CREATE_EXT, &create_ext);
3710 struct drm_i915_gem_create_ext_protected_content {
3711 /** @base: Extension link. See struct i915_user_extension. */
3712 struct i915_user_extension base;
3713 /** @flags: reserved for future usage, currently MBZ */
3717 /* ID of the protected content session managed by i915 when PXP is active */
3718 #define I915_PROTECTED_CONTENT_DEFAULT_SESSION 0xf
3720 #if defined(__cplusplus)
3724 #endif /* _UAPI_I915_DRM_H_ */