Definition:

struct i915_user_extension {    __u64 next_extension;    __u32 name;    __u32 flags;    __u32 rsvd[4];};

Members

next_extension

Pointer to the nextstructi915_user_extension, or zero if the end.

name

Name of the extension.

Note that the name here is just some integer.

Also note that the name space for this is not global for the wholedriver, but rather its scope/meaning is limited to the specific pieceof uAPI which has embedded thestructi915_user_extension.

flags

MBZ

All undefined bits must be zero.

rsvd

MBZ

Reserved for future use; must be zero.

Constants

I915_ENGINE_CLASS_RENDER

Render engines support instructions used for 3D, Compute (GPGPU),and programmable media workloads. These instructions fetch data anddispatch individual work items to threads that operate in parallel.The threads run small programs (called “kernels” or “shaders”) onthe GPU’s execution units (EUs).

I915_ENGINE_CLASS_COPY

Copy engines (also referred to as “blitters”) support instructionsthat move blocks of data from one location in memory to another,or that fill a specified location of memory with fixed data.Copy engines can perform pre-defined logical or bitwise operationson the source, destination, or pattern data.

I915_ENGINE_CLASS_VIDEO

Video engines (also referred to as “bit stream decode” (BSD) or“vdbox”) support instructions that perform fixed-function mediadecode and encode.

I915_ENGINE_CLASS_VIDEO_ENHANCE

Video enhancement engines (also referred to as “vebox”) supportinstructions related to image enhancement.

I915_ENGINE_CLASS_COMPUTE

Compute engines support a subset of the instructions availableon render engines: compute engines support Compute (GPGPU) andprogrammable media workloads, but do not support the 3D pipeline.

I915_ENGINE_CLASS_INVALID

Placeholder value to represent an invalid engine class assignment.

Definition:

struct i915_engine_class_instance {    __u16 engine_class;#define I915_ENGINE_CLASS_INVALID_NONE -1;#define I915_ENGINE_CLASS_INVALID_VIRTUAL -2;    __u16 engine_instance;};

Members

engine_class

Engine class fromenumdrm_i915_gem_engine_class

engine_instance

Engine instance.

Definition:

struct drm_i915_getparam {    __s32 param;    int __user *value;};

Members

param

Driver parameter to query.

value

Address of memory where queried value should be put.

WARNING: Using pointers instead of fixed-size u64 means we need to writecompat32 code. Don’t repeat this mistake.

Definition:

struct drm_i915_gem_mmap_offset {    __u32 handle;    __u32 pad;    __u64 offset;    __u64 flags;#define I915_MMAP_OFFSET_GTT    0;#define I915_MMAP_OFFSET_WC     1;#define I915_MMAP_OFFSET_WB     2;#define I915_MMAP_OFFSET_UC     3;#define I915_MMAP_OFFSET_FIXED  4;    __u64 extensions;};

Members

handle

Handle for the object being mapped.

pad

Must be zero

offset

The fake offset to use for subsequent mmap call

This is a fixed-size type for 32/64 compatibility.

flags

Flags for extended behaviour.

It is mandatory that one of theMMAP_OFFSET typesshould be included:

• I915_MMAP_OFFSET_GTT: Use mmap with the object bound to GTT. (Write-Combined)

• I915_MMAP_OFFSET_WC: Use Write-Combined caching.

• I915_MMAP_OFFSET_WB: Use Write-Back caching.

• I915_MMAP_OFFSET_FIXED: Use object placement to determine caching.

On devices with local memoryI915_MMAP_OFFSET_FIXED is the only validtype. On devices without local memory, this caching mode is invalid.

As caching mode when specifyingI915_MMAP_OFFSET_FIXED, WC or WB willbe used, depending on the object placement on creation. WB will be usedwhen the object can only exist in system memory, WC otherwise.

extensions

Zero-terminated chain of extensions.

No current extensions defined; mbz.

Definition:

struct drm_i915_gem_set_domain {    __u32 handle;    __u32 read_domains;    __u32 write_domain;};

Members

handle

Handle for the object.

read_domains

New read domains.

write_domain

New write domain.

Note that having something in the write domain implies it’s in theread domain, and only that read domain.

Definition:

struct drm_i915_gem_exec_fence {    __u32 handle;    __u32 flags;#define I915_EXEC_FENCE_WAIT            (1<<0);#define I915_EXEC_FENCE_SIGNAL          (1<<1);#define __I915_EXEC_FENCE_UNKNOWN_FLAGS (-(I915_EXEC_FENCE_SIGNAL << 1));};

Members

handle

User’s handle for a drm_syncobj to wait on or signal.

flags

Supported flags are:

I915_EXEC_FENCE_WAIT:Wait for the input fence before request submission.

I915_EXEC_FENCE_SIGNAL:Return request completion fence as output

Definition:

struct drm_i915_gem_execbuffer_ext_timeline_fences {#define DRM_I915_GEM_EXECBUFFER_EXT_TIMELINE_FENCES 0;    struct i915_user_extension base;    __u64 fence_count;    __u64 handles_ptr;    __u64 values_ptr;};

Members

base

Extension link. Seestructi915_user_extension.

fence_count

Number of elements in thehandles_ptr &value_ptrarrays.

handles_ptr

Pointer to an array ofstructdrm_i915_gem_exec_fenceof lengthfence_count.

values_ptr

Pointer to an array of u64 values of lengthfence_count.Values must be 0 for a binary drm_syncobj. A Value of 0 for atimeline drm_syncobj is invalid as it turns a drm_syncobj into abinary one.

Definition:

struct drm_i915_gem_execbuffer2 {    __u64 buffers_ptr;    __u32 buffer_count;    __u32 batch_start_offset;    __u32 batch_len;    __u32 DR1;    __u32 DR4;    __u32 num_cliprects;    __u64 cliprects_ptr;    __u64 flags;#define I915_EXEC_RING_MASK              (0x3f);#define I915_EXEC_DEFAULT                (0<<0);#define I915_EXEC_RENDER                 (1<<0);#define I915_EXEC_BSD                    (2<<0);#define I915_EXEC_BLT                    (3<<0);#define I915_EXEC_VEBOX                  (4<<0);#define I915_EXEC_CONSTANTS_MASK        (3<<6);#define I915_EXEC_CONSTANTS_REL_GENERAL (0<<6);#define I915_EXEC_CONSTANTS_ABSOLUTE    (1<<6);#define I915_EXEC_CONSTANTS_REL_SURFACE (2<<6);#define I915_EXEC_GEN7_SOL_RESET        (1<<8);#define I915_EXEC_SECURE                (1<<9);#define I915_EXEC_IS_PINNED             (1<<10);#define I915_EXEC_NO_RELOC              (1<<11);#define I915_EXEC_HANDLE_LUT            (1<<12);#define I915_EXEC_BSD_SHIFT      (13);#define I915_EXEC_BSD_MASK       (3 << I915_EXEC_BSD_SHIFT);#define I915_EXEC_BSD_DEFAULT    (0 << I915_EXEC_BSD_SHIFT);#define I915_EXEC_BSD_RING1      (1 << I915_EXEC_BSD_SHIFT);#define I915_EXEC_BSD_RING2      (2 << I915_EXEC_BSD_SHIFT);#define I915_EXEC_RESOURCE_STREAMER     (1<<15);#define I915_EXEC_FENCE_IN              (1<<16);#define I915_EXEC_FENCE_OUT             (1<<17);#define I915_EXEC_BATCH_FIRST           (1<<18);#define I915_EXEC_FENCE_ARRAY   (1<<19);#define I915_EXEC_FENCE_SUBMIT          (1 << 20);#define I915_EXEC_USE_EXTENSIONS        (1 << 21);#define __I915_EXEC_UNKNOWN_FLAGS (-(I915_EXEC_USE_EXTENSIONS << 1));    __u64 rsvd1;    __u64 rsvd2;};

Members

buffers_ptr

Pointer to a list of gem_exec_object2 structs

buffer_count

Number of elements inbuffers_ptr array

batch_start_offset

Offset in the batchbuffer to start executionfrom.

batch_len

Length in bytes of the batch buffer, starting from thebatch_start_offset. If 0, length is assumed to be the batch bufferobject size.

DR1

deprecated

DR4

deprecated

num_cliprects

Seecliprects_ptr

cliprects_ptr

Kernel clipping was a DRI1 misfeature.

It is invalid to use this field if I915_EXEC_FENCE_ARRAY orI915_EXEC_USE_EXTENSIONS flags are not set.

If I915_EXEC_FENCE_ARRAY is set, then this is a pointer to an arrayofdrm_i915_gem_exec_fence andnum_cliprects is the length of thearray.

If I915_EXEC_USE_EXTENSIONS is set, then this is a pointer to asinglei915_user_extension and num_cliprects is 0.

flags

Execbuf flags

rsvd1

Context id

rsvd2

in and out sync_file file descriptors.

When I915_EXEC_FENCE_IN or I915_EXEC_FENCE_SUBMIT flag is set, thelower 32 bits of this field will have the in sync_file fd (input).

When I915_EXEC_FENCE_OUT flag is set, the upper 32 bits of thisfield will have the out sync_file fd (output).

Definition:

struct drm_i915_gem_caching {    __u32 handle;#define I915_CACHING_NONE               0;#define I915_CACHING_CACHED             1;#define I915_CACHING_DISPLAY            2;    __u32 caching;};

Members

handle

Handle of the buffer to set/get the caching level.

caching

The GTT caching level to apply or possible return value.

The supportedcaching values:

I915_CACHING_NONE:

GPU access is not coherent with CPU caches. Default for machineswithout an LLC. This means manual flushing might be needed, if wewant GPU access to be coherent.

I915_CACHING_CACHED:

GPU access is coherent with CPU caches and furthermore the data iscached in last-level caches shared between CPU cores and the GPU GT.

I915_CACHING_DISPLAY:

Special GPU caching mode which is coherent with the scanout engines.Transparently falls back to I915_CACHING_NONE on platforms where nospecial cache mode (like write-through or gfdt flushing) isavailable. The kernel automatically sets this mode when using abuffer as a scanout target. Userspace can manually set this mode toavoid a costly stall and clflush in the hotpath of drawing the firstframe.

Definition:

struct drm_i915_gem_context_create_ext {    __u32 ctx_id;    __u32 flags;#define I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS        (1u << 0);#define I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE       (1u << 1);#define I915_CONTEXT_CREATE_FLAGS_UNKNOWN         (-(I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE << 1));    __u64 extensions;#define I915_CONTEXT_CREATE_EXT_SETPARAM 0;#define I915_CONTEXT_CREATE_EXT_CLONE 1;};

Members

ctx_id

Id of the created context (output)

flags

Supported flags are:

I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS:

Extensions may be appended to this structure and driver must checkfor those. Seeextensions.

I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE

Created context will have single timeline.

extensions

Zero-terminated chain of extensions.

I915_CONTEXT_CREATE_EXT_SETPARAM:Context parameter to set or query during context creation.Seestructdrm_i915_gem_context_create_ext_setparam.

I915_CONTEXT_CREATE_EXT_CLONE:This extension has been removed. On the off chance someone somewherehas attempted to use it, never re-use this extension number.

Definition:

struct drm_i915_gem_context_param {    __u32 ctx_id;    __u32 size;    __u64 param;#define I915_CONTEXT_PARAM_BAN_PERIOD   0x1;#define I915_CONTEXT_PARAM_NO_ZEROMAP   0x2;#define I915_CONTEXT_PARAM_GTT_SIZE     0x3;#define I915_CONTEXT_PARAM_NO_ERROR_CAPTURE     0x4;#define I915_CONTEXT_PARAM_BANNABLE     0x5;#define I915_CONTEXT_PARAM_PRIORITY     0x6;#define I915_CONTEXT_MAX_USER_PRIORITY        1023;#define I915_CONTEXT_DEFAULT_PRIORITY         0;#define I915_CONTEXT_MIN_USER_PRIORITY        -1023;#define I915_CONTEXT_PARAM_SSEU         0x7;#define I915_CONTEXT_PARAM_RECOVERABLE  0x8;#define I915_CONTEXT_PARAM_VM           0x9;#define I915_CONTEXT_PARAM_ENGINES      0xa;#define I915_CONTEXT_PARAM_PERSISTENCE  0xb;#define I915_CONTEXT_PARAM_RINGSIZE     0xc;#define I915_CONTEXT_PARAM_PROTECTED_CONTENT    0xd;#define I915_CONTEXT_PARAM_LOW_LATENCY          0xe;#define I915_CONTEXT_PARAM_CONTEXT_IMAGE        0xf;    __u64 value;};

Members

ctx_id

Context id

size

Size of the parametervalue

param

Parameter to set or query

value

Context parameter value to be set or queried

Definition:

struct i915_context_engines_parallel_submit {    struct i915_user_extension base;    __u16 engine_index;    __u16 width;    __u16 num_siblings;    __u16 mbz16;    __u64 flags;    __u64 mbz64[3];    struct i915_engine_class_instance engines[];};

Members

base

base user extension.

engine_index

slot for parallel engine

width

number of contexts per parallel engine or in other words thenumber of batches in each submission

num_siblings

number of siblings per context or in other words thenumber of possible placements for each submission

mbz16

reserved for future use; must be zero

flags

all undefined flags must be zero, currently not defined flags

mbz64

reserved for future use; must be zero

engines

2-d array of engine instances to configure parallel engine

length = width (i) * num_siblings (j)index = j + i * num_siblings

Definition:

struct drm_i915_gem_context_create_ext_setparam {    struct i915_user_extension base;    struct drm_i915_gem_context_param param;};

Members

base

Extension link. Seestructi915_user_extension.

param

Context parameter to set or query.Seestructdrm_i915_gem_context_param.

Definition:

struct drm_i915_gem_vm_control {    __u64 extensions;    __u32 flags;    __u32 vm_id;};

Members

extensions

Zero-terminated chain of extensions.

flags

reserved for future usage, currently MBZ

vm_id

Id of the VM created or to be destroyed

Definition:

struct drm_i915_gem_userptr {    __u64 user_ptr;    __u64 user_size;    __u32 flags;#define I915_USERPTR_READ_ONLY 0x1;#define I915_USERPTR_PROBE 0x2;#define I915_USERPTR_UNSYNCHRONIZED 0x80000000;    __u32 handle;};

Members

user_ptr

The pointer to the allocated memory.

Needs to be aligned to PAGE_SIZE.

user_size

The size in bytes for the allocated memory. This will also become theobject size.

Needs to be aligned to PAGE_SIZE, and should be at least PAGE_SIZE,or larger.

flags

Supported flags:

I915_USERPTR_READ_ONLY:

Mark the object as readonly, this also means GPU access can only bereadonly. This is only supported on HW which supports readonly accessthrough the GTT. If the HW can’t support readonly access, an error isreturned.

I915_USERPTR_PROBE:

Probe the provideduser_ptr range and validate that theuser_ptr isindeed pointing to normal memory and that the range is also valid.For example if some garbage address is given to the kernel, then thisshould complain.

Returns -EFAULT if the probe failed.

Note that this doesn’t populate the backing pages, and also doesn’tguarantee that the object will remain valid when the object iseventually used.

The kernel supports this feature if I915_PARAM_HAS_USERPTR_PROBEreturns a non-zero value.

I915_USERPTR_UNSYNCHRONIZED:

NOT USED. Setting this flag will result in an error.

handle

Returned handle for the object.

Object handles are nonzero.

Definition:

struct drm_i915_perf_oa_config {    char uuid[36];    __u32 n_mux_regs;    __u32 n_boolean_regs;    __u32 n_flex_regs;    __u64 mux_regs_ptr;    __u64 boolean_regs_ptr;    __u64 flex_regs_ptr;};

Members

uuid

String formatted like “%08x-%04x-%04x-%04x-%012x”

n_mux_regs

Number of mux regs inmux_regs_ptr.

n_boolean_regs

Number of boolean regs inboolean_regs_ptr.

n_flex_regs

Number of flex regs inflex_regs_ptr.

mux_regs_ptr

Pointer to tuples of u32 values (register address, value) for muxregisters. Expected length of buffer is (2 * sizeof(u32) *n_mux_regs).

boolean_regs_ptr

Pointer to tuples of u32 values (register address, value) for muxregisters. Expected length of buffer is (2 * sizeof(u32) *n_boolean_regs).

flex_regs_ptr

Pointer to tuples of u32 values (register address, value) for muxregisters. Expected length of buffer is (2 * sizeof(u32) *n_flex_regs).

Definition:

struct drm_i915_query_item {    __u64 query_id;#define DRM_I915_QUERY_TOPOLOGY_INFO            1;#define DRM_I915_QUERY_ENGINE_INFO              2;#define DRM_I915_QUERY_PERF_CONFIG              3;#define DRM_I915_QUERY_MEMORY_REGIONS           4;#define DRM_I915_QUERY_HWCONFIG_BLOB            5;#define DRM_I915_QUERY_GEOMETRY_SUBSLICES       6;#define DRM_I915_QUERY_GUC_SUBMISSION_VERSION   7;    __s32 length;    __u32 flags;#define DRM_I915_QUERY_PERF_CONFIG_LIST          1;#define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2;#define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID   3;    __u64 data_ptr;};

Members

query_id

The id for this query. Currently accepted query IDs are:

• DRM_I915_QUERY_TOPOLOGY_INFO (seestructdrm_i915_query_topology_info)

• DRM_I915_QUERY_ENGINE_INFO (seestructdrm_i915_engine_info)

• DRM_I915_QUERY_PERF_CONFIG (seestructdrm_i915_query_perf_config)

• DRM_I915_QUERY_MEMORY_REGIONS (seestructdrm_i915_query_memory_regions)

• DRM_I915_QUERY_HWCONFIG_BLOB (seeGuC HWCONFIG blob uAPI)

• DRM_I915_QUERY_GEOMETRY_SUBSLICES (seestructdrm_i915_query_topology_info)

• DRM_I915_QUERY_GUC_SUBMISSION_VERSION (seestructdrm_i915_query_guc_submission_version)

length

When set to zero by userspace, this is filled with the size of thedata to be written at thedata_ptr pointer. The kernel sets thisvalue to a negative value to signal an error on a particular queryitem.

flags

Whenquery_id ==DRM_I915_QUERY_TOPOLOGY_INFO, must be 0.

Whenquery_id ==DRM_I915_QUERY_PERF_CONFIG, must be one of thefollowing:

• DRM_I915_QUERY_PERF_CONFIG_LIST

• DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID

• DRM_I915_QUERY_PERF_CONFIG_FOR_UUID

Whenquery_id ==DRM_I915_QUERY_GEOMETRY_SUBSLICES must containastructi915_engine_class_instance that references a render engine.

data_ptr

Data will be written at the location pointed bydata_ptr when thevalue oflength matches the length of the data to be written by thekernel.

Definition:

struct drm_i915_query {    __u32 num_items;    __u32 flags;    __u64 items_ptr;};

Members

num_items

The number of elements in theitems_ptr array

flags

Unused for now. Must be cleared to zero.

items_ptr

Pointer to an array ofstructdrm_i915_query_item. The number ofarray elements isnum_items.

Definition:

struct drm_i915_query_topology_info {    __u16 flags;    __u16 max_slices;    __u16 max_subslices;    __u16 max_eus_per_subslice;    __u16 subslice_offset;    __u16 subslice_stride;    __u16 eu_offset;    __u16 eu_stride;    __u8 data[];};

Members

flags

Unused for now. Must be cleared to zero.

max_slices

The number of bits used to express the slice mask.

max_subslices

The number of bits used to express the subslice mask.

max_eus_per_subslice

The number of bits in the EU mask that correspond to a singlesubslice’s EUs.

subslice_offset

Offset in data[] at which the subslice masks are stored.

subslice_stride

Stride at which each of the subslice masks for each slice arestored.

eu_offset

Offset in data[] at which the EU masks are stored.

eu_stride

Stride at which each of the EU masks for each subslice are stored.

data

Contains 3 pieces of information :

• The slice mask with one bit per slice telling whether a slice isavailable. The availability of slice X can be queried with thefollowing formula :

  (data[X/8]>>(X%8))&1

  Starting with Xe_HP platforms, Intel hardware no longer hastraditional slices so i915 will always report a single slice(hardcoded slicemask = 0x1) which contains all of the platform’ssubslices. I.e., the mask here does not reflect any of the newerhardware concepts such as “gslices” or “cslices” since userspaceis capable of inferring those from the subslice mask.

• The subslice mask for each slice with one bit per subslice tellingwhether a subslice is available. Starting with Gen12 we use theterm “subslice” to refer to what the hardware documentationdescribes as a “dual-subslices.” The availability of subslice Yin slice X can be queried with the following formula :

  (data[subslice_offset+X*subslice_stride+Y/8]>>(Y%8))&1

• The EU mask for each subslice in each slice, with one bit per EUtelling whether an EU is available. The availability of EU Z insubslice Y in slice X can be queried with the following formula :

  (data[eu_offset+(X*max_subslices+Y)*eu_stride+Z/8]>>(Z%8))&1

Definition:

struct drm_i915_engine_info {    struct i915_engine_class_instance engine;    __u32 rsvd0;    __u64 flags;#define I915_ENGINE_INFO_HAS_LOGICAL_INSTANCE           (1 << 0);    __u64 capabilities;#define I915_VIDEO_CLASS_CAPABILITY_HEVC                (1 << 0);#define I915_VIDEO_AND_ENHANCE_CLASS_CAPABILITY_SFC     (1 << 1);    __u16 logical_instance;    __u16 rsvd1[3];    __u64 rsvd2[3];};

Members

engine

Engine class and instance.

rsvd0

Reserved field.

flags

Engine flags.

capabilities

Capabilities of this engine.

logical_instance

Logical instance of engine

rsvd1

Reserved fields.

rsvd2

Reserved fields.

Definition:

struct drm_i915_query_engine_info {    __u32 num_engines;    __u32 rsvd[3];    struct drm_i915_engine_info engines[];};

Members

num_engines

Number ofstructdrm_i915_engine_info structs following.

rsvd

MBZ

engines

Marker for drm_i915_engine_info structures.

Definition:

struct drm_i915_query_perf_config {    union {        __u64 n_configs;        __u64 config;        char uuid[36];    };    __u32 flags;    __u8 data[];};

Members

{unnamed_union}

anonymous

n_configs

Whendrm_i915_query_item.flags ==DRM_I915_QUERY_PERF_CONFIG_LIST, i915 sets this fields tothe number of configurations available.

config

Whendrm_i915_query_item.flags ==DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID, i915 will use thevalue in this field as configuration identifier to decidewhat data to write into config_ptr.

uuid

Whendrm_i915_query_item.flags ==DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID, i915 will use thevalue in this field as configuration identifier to decidewhat data to write into config_ptr.

String formatted like “08x-````04x-````04x-````04x-````012x”

flags

Unused for now. Must be cleared to zero.

data

Whendrm_i915_query_item.flags ==DRM_I915_QUERY_PERF_CONFIG_LIST,i915 will write an array of __u64 of configuration identifiers.

Whendrm_i915_query_item.flags ==DRM_I915_QUERY_PERF_CONFIG_DATA,i915 will write astructdrm_i915_perf_oa_config. If the followingfields ofstructdrm_i915_perf_oa_config are not set to 0, i915 willwrite into the associated pointers the values of submitted when theconfiguration was created :

• drm_i915_perf_oa_config.n_mux_regs

• drm_i915_perf_oa_config.n_boolean_regs

• drm_i915_perf_oa_config.n_flex_regs

Constants

I915_MEMORY_CLASS_SYSTEM

System memory

I915_MEMORY_CLASS_DEVICE

Device local-memory

Definition:

struct drm_i915_gem_memory_class_instance {    __u16 memory_class;    __u16 memory_instance;};

Members

memory_class

Seeenumdrm_i915_gem_memory_class

memory_instance

Which instance

Definition:

struct drm_i915_memory_region_info {    struct drm_i915_gem_memory_class_instance region;    __u32 rsvd0;    __u64 probed_size;    __u64 unallocated_size;    union {        __u64 rsvd1[8];        struct {            __u64 probed_cpu_visible_size;            __u64 unallocated_cpu_visible_size;        };    };};

Members

region

The class:instance pair encoding

rsvd0

MBZ

probed_size

Memory probed by the driver

Note that it should not be possible to ever encounter a zero valuehere, also note that no current region type will ever return -1 here.Although for future region types, this might be a possibility. Thesame applies to the other size fields.

unallocated_size

Estimate of memory remaining

Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliable accounting.Without this (or if this is an older kernel) the value here willalways equal theprobed_size. Note this is only currently trackedfor I915_MEMORY_CLASS_DEVICE regions (for other types the value herewill always equal theprobed_size).

{unnamed_union}

anonymous

rsvd1

MBZ

{unnamed_struct}

anonymous

probed_cpu_visible_size

Memory probed by the driverthat is CPU accessible.

This will be always be <=probed_size, and theremainder (if there is any) will not be CPUaccessible.

On systems without small BAR, theprobed_size willalways equal theprobed_cpu_visible_size, since allof it will be CPU accessible.

Note this is only tracked forI915_MEMORY_CLASS_DEVICE regions (for other types thevalue here will always equal theprobed_size).

Note that if the value returned here is zero, thenthis must be an old kernel which lacks the relevantsmall-bar uAPI support (includingI915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS), but onsuch systems we should never actually end up with asmall BAR configuration, assuming we are able to loadthe kernel module. Hence it should be safe to treatthis the same as whenprobed_cpu_visible_size ==probed_size.

unallocated_cpu_visible_size

Estimate of CPUvisible memory remaining.

Note this is only tracked forI915_MEMORY_CLASS_DEVICE regions (for other types thevalue here will always equal theprobed_cpu_visible_size).

Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliableaccounting. Without this the value here will alwaysequal theprobed_cpu_visible_size. Note this is onlycurrently tracked for I915_MEMORY_CLASS_DEVICEregions (for other types the value here will alsoalways equal theprobed_cpu_visible_size).

If this is an older kernel the value here will bezero, see alsoprobed_cpu_visible_size.

Definition:

struct drm_i915_query_memory_regions {    __u32 num_regions;    __u32 rsvd[3];    struct drm_i915_memory_region_info regions[];};

Members

num_regions

Number of supported regions

rsvd

MBZ

regions

Info about each supported region

Definition:

struct drm_i915_query_guc_submission_version {    __u32 branch;    __u32 major;    __u32 minor;    __u32 patch;};

Members

branch

Firmware branch version.

major

Firmware major version.

minor

Firmware minor version.

patch

Firmware patch version.

Definition:

struct drm_i915_gem_create_ext {    __u64 size;    __u32 handle;#define I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS (1 << 0);    __u32 flags;#define I915_GEM_CREATE_EXT_MEMORY_REGIONS 0;#define I915_GEM_CREATE_EXT_PROTECTED_CONTENT 1;#define I915_GEM_CREATE_EXT_SET_PAT 2;    __u64 extensions;};

Members

size

Requested size for the object.

The (page-aligned) allocated size for the object will be returned.

On platforms like DG2/ATS the kernel will always use 64K or largerpages for I915_MEMORY_CLASS_DEVICE. The kernel also requires aminimum of 64K GTT alignment for such objects.

NOTE: Previously the ABI here required a minimum GTT alignment of 2Mon DG2/ATS, due to how the hardware implemented 64K GTT page support,where we had the following complications:

1) The entire PDE (which covers a 2MB virtual address range), mustcontain only 64K PTEs, i.e mixing 4K and 64K PTEs in the samePDE is forbidden by the hardware.

2) We still need to support 4K PTEs for I915_MEMORY_CLASS_SYSTEMobjects.

However on actual production HW this was completely changed to nowallow setting a TLB hint at the PTE level (see PS64), which is a lotmore flexible than the above. With this the 2M restriction wasdropped where we now only require 64K.

handle

Returned handle for the object.

Object handles are nonzero.

flags

Optional flags.

Supported values:

I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS - Signal to the kernel thatthe object will need to be accessed via the CPU.

Only valid when placing objects in I915_MEMORY_CLASS_DEVICE, and onlystrictly required on configurations where some subset of the devicememory is directly visible/mappable through the CPU (which we alsocall small BAR), like on some DG2+ systems. Note that this is quiteundesirable, but due to various factors like the client CPU, BIOS etcit’s something we can expect to see in the wild. Seedrm_i915_memory_region_info.probed_cpu_visible_size for how todetermine if this system applies.

Note that one of the placements MUST be I915_MEMORY_CLASS_SYSTEM, toensure the kernel can always spill the allocation to system memory,if the object can’t be allocated in the mappable part ofI915_MEMORY_CLASS_DEVICE.

Also note that since the kernel only supports flat-CCS on objectsthat canonly be placed in I915_MEMORY_CLASS_DEVICE, we thereforedon’t support I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS together withflat-CCS.

Without this hint, the kernel will assume that non-mappableI915_MEMORY_CLASS_DEVICE is preferred for this object. Note that thekernel can still migrate the object to the mappable part, as a lastresort, if userspace ever CPU faults this object, but this might beexpensive, and so ideally should be avoided.

On older kernels which lack the relevant small-bar uAPI support (seealsodrm_i915_memory_region_info.probed_cpu_visible_size),usage of the flag will result in an error, but it should NEVER bepossible to end up with a small BAR configuration, assuming we canalso successfully load the i915 kernel module. In such cases theentire I915_MEMORY_CLASS_DEVICE region will be CPU accessible, and assuch there are zero restrictions on where the object can be placed.

extensions

The chain of extensions to apply to this object.

This will be useful in the future when we need to support severaldifferent extensions, and we need to apply more than one whencreating the object. Seestructi915_user_extension.

If we don’t supply any extensions then we get the same old gem_createbehaviour.

For I915_GEM_CREATE_EXT_MEMORY_REGIONS usage seestructdrm_i915_gem_create_ext_memory_regions.

For I915_GEM_CREATE_EXT_PROTECTED_CONTENT usage seestructdrm_i915_gem_create_ext_protected_content.

For I915_GEM_CREATE_EXT_SET_PAT usage seestructdrm_i915_gem_create_ext_set_pat.

Definition:

struct drm_i915_gem_create_ext_memory_regions {    struct i915_user_extension base;    __u32 pad;    __u32 num_regions;    __u64 regions;};

Members

base

Extension link. Seestructi915_user_extension.

pad

MBZ

num_regions

Number of elements in theregions array.

regions

The regions/placements array.

An array ofstructdrm_i915_gem_memory_class_instance.

Definition:

struct drm_i915_gem_create_ext_protected_content {    struct i915_user_extension base;    __u32 flags;};

Members

base

Extension link. Seestructi915_user_extension.

flags

reserved for future usage, currently MBZ

Definition:

struct drm_i915_gem_create_ext_set_pat {    struct i915_user_extension base;    __u32 pat_index;    __u32 rsvd;};

Members

base

Extension link. Seestructi915_user_extension.

pat_index

PAT index to be setPAT index is a bit field in Page Table Entry to control cachingbehaviors for GPU accesses. The definition of PAT index isplatform dependent and can be found in hardware specifications,

rsvd

reserved for future use

Definition:

struct drm_panthor_obj_array {    __u32 stride;    __u32 count;    __u64 array;};

Members

stride

Stride of object struct. Used for versioning.

count

Number of objects in the array.

array

User pointer to an array of objects.

Parameters

cnt

Number of elements in the array.

ptr

Pointer to the array to pass to the kernel.

Description

Macro initializing a drm_panthor_obj_array based on the object size as knownby userspace.

Constants

DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_MASK

Synchronization handle type mask.

DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_SYNCOBJ

Synchronization object type.

DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_TIMELINE_SYNCOBJ

Timeline synchronizationobject type.

DRM_PANTHOR_SYNC_OP_WAIT

Wait operation.

DRM_PANTHOR_SYNC_OP_SIGNAL

Signal operation.

Definition:

struct drm_panthor_sync_op {    __u32 flags;    __u32 handle;    __u64 timeline_value;};

Members

flags

Synchronization operation flags. Combination of DRM_PANTHOR_SYNC_OP values.

handle

Sync handle.

timeline_value

MBZ if(flags & DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_MASK) !=DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_TIMELINE_SYNCOBJ.

Constants

DRM_PANTHOR_DEV_QUERY_GPU_INFO

Query GPU information.

DRM_PANTHOR_DEV_QUERY_CSIF_INFO

Query command-stream interface information.

DRM_PANTHOR_DEV_QUERY_TIMESTAMP_INFO

Query timestamp information.

DRM_PANTHOR_DEV_QUERY_GROUP_PRIORITIES_INFO

Query allowed group priorities information.

Constants

DRM_PANTHOR_GPU_COHERENCY_ACE_LITE

ACE Lite coherency.

DRM_PANTHOR_GPU_COHERENCY_ACE

ACE coherency.

DRM_PANTHOR_GPU_COHERENCY_NONE

No coherency.

Definition:

struct drm_panthor_gpu_info {    __u32 gpu_id;#define DRM_PANTHOR_ARCH_MAJOR(x)               ((x) >> 28);#define DRM_PANTHOR_ARCH_MINOR(x)               (((x) >> 24) & 0xf);#define DRM_PANTHOR_ARCH_REV(x)                 (((x) >> 20) & 0xf);#define DRM_PANTHOR_PRODUCT_MAJOR(x)            (((x) >> 16) & 0xf);#define DRM_PANTHOR_VERSION_MAJOR(x)            (((x) >> 12) & 0xf);#define DRM_PANTHOR_VERSION_MINOR(x)            (((x) >> 4) & 0xff);#define DRM_PANTHOR_VERSION_STATUS(x)           ((x) & 0xf);    __u32 gpu_rev;    __u32 csf_id;#define DRM_PANTHOR_CSHW_MAJOR(x)               (((x) >> 26) & 0x3f);#define DRM_PANTHOR_CSHW_MINOR(x)               (((x) >> 20) & 0x3f);#define DRM_PANTHOR_CSHW_REV(x)                 (((x) >> 16) & 0xf);#define DRM_PANTHOR_MCU_MAJOR(x)                (((x) >> 10) & 0x3f);#define DRM_PANTHOR_MCU_MINOR(x)                (((x) >> 4) & 0x3f);#define DRM_PANTHOR_MCU_REV(x)                  ((x) & 0xf);    __u32 l2_features;    __u32 tiler_features;    __u32 mem_features;    __u32 mmu_features;#define DRM_PANTHOR_MMU_VA_BITS(x)              ((x) & 0xff);    __u32 thread_features;    __u32 max_threads;    __u32 thread_max_workgroup_size;    __u32 thread_max_barrier_size;    __u32 coherency_features;    __u32 texture_features[4];    __u32 as_present;    __u32 selected_coherency;    __u64 shader_present;    __u64 l2_present;    __u64 tiler_present;    __u32 core_features;    __u32 pad;    __u64 gpu_features;};

Members

gpu_id

GPU ID.

gpu_rev

GPU revision.

csf_id

Command stream frontend ID.

l2_features

L2-cache features.

tiler_features

Tiler features.

mem_features

Memory features.

mmu_features

MMU features.

thread_features

Thread features.

max_threads

Maximum number of threads.

thread_max_workgroup_size

Maximum workgroup size.

thread_max_barrier_size

Maximum number of threads that can waitsimultaneously on a barrier.

coherency_features

Coherency features.

Combination of drm_panthor_gpu_coherency flags.

Note that this is just what the coherency protocols supported by theGPU, but the actual coherency in place depends on the SoCintegration and is reflected bydrm_panthor_gpu_info::selected_coherency.

texture_features

Texture features.

as_present

Bitmask encoding the number of address-space exposed by the MMU.

selected_coherency

Coherency selected for this device.

One of drm_panthor_gpu_coherency.

shader_present

Bitmask encoding the shader cores exposed by the GPU.

l2_present

Bitmask encoding the L2 caches exposed by the GPU.

tiler_present

Bitmask encoding the tiler units exposed by the GPU.

core_features

Used to discriminate core variants when they exist.

pad

MBZ.

gpu_features

Bitmask describing supported GPU-wide features

Definition:

struct drm_panthor_csif_info {    __u32 csg_slot_count;    __u32 cs_slot_count;    __u32 cs_reg_count;    __u32 scoreboard_slot_count;    __u32 unpreserved_cs_reg_count;    __u32 pad;};

Members

csg_slot_count

Number of command stream group slots exposed by the firmware.

cs_slot_count

Number of command stream slots per group.

cs_reg_count

Number of command stream registers.

scoreboard_slot_count

Number of scoreboard slots.

unpreserved_cs_reg_count

Number of command stream registers reserved bythe kernel driver to call a userspace command stream.

All registers can be used by a userspace command stream, but the[cs_slot_count - unpreserved_cs_reg_count .. cs_slot_count] registers areused by the kernel when DRM_PANTHOR_IOCTL_GROUP_SUBMIT is called.

pad

Padding field, set to zero.

Definition:

struct drm_panthor_timestamp_info {    __u64 timestamp_frequency;    __u64 current_timestamp;    __u64 timestamp_offset;};

Members

timestamp_frequency

The frequency of the timestamp timer or 0 ifunknown.

current_timestamp

The current timestamp.

timestamp_offset

The offset of the timestamp timer.

Definition:

struct drm_panthor_group_priorities_info {    __u8 allowed_mask;    __u8 pad[3];};

Members

allowed_mask

Bitmask of the allowed group priorities.

Each bit represents a variant of theenumdrm_panthor_group_priority.

pad

Padding fields, MBZ.

Definition:

struct drm_panthor_dev_query {    __u32 type;    __u32 size;    __u64 pointer;};

Members

type

the query type (see drm_panthor_dev_query_type).

size

size of the type being queried.

If pointer is NULL, size is updated by the driver to provide theoutput structure size. If pointer is not NULL, the driver willonly copy min(size, actual_structure_size) bytes to the pointer,and update the size accordingly. This allows us to extend querytypes without breaking userspace.

pointer

user pointer to a query type struct.

Pointer can be NULL, in which case, nothing is copied, but theactual structure size is returned. If not NULL, it must point toa location that’s large enough to hold size bytes.

Definition:

struct drm_panthor_vm_create {    __u32 flags;    __u32 id;    __u64 user_va_range;};

Members

flags

VM flags, MBZ.

id

Returned VM ID.

user_va_range

Size of the VA space reserved for user objects.

The kernel will pick the remaining space to map kernel-only objects to theVM (heap chunks, heap context, ring buffers, kernel synchronization objects,...). If the space left for kernel objects is too small, kernel objectallocation will fail further down the road. One can usedrm_panthor_gpu_info::mmu_features to extract the total virtual addressrange, and chose a user_va_range that leaves some space to the kernel.

If user_va_range is zero, the kernel will pick a sensible value based onTASK_SIZE and the virtual range supported by the GPU MMU (the kernel/usersplit should leave enough VA space for userspace processes to support SVM,while still allowing the kernel to map some amount of kernel objects inthe kernel VA range). The value chosen by the driver will be returned inuser_va_range.

User VA space always starts at 0x0, kernel VA space is always placed afterthe user VA range.

Definition:

struct drm_panthor_vm_destroy {    __u32 id;    __u32 pad;};

Members

id

ID of the VM to destroy.

pad

MBZ.

Constants

DRM_PANTHOR_VM_BIND_OP_MAP_READONLY

Map the memory read-only.

Only valid with DRM_PANTHOR_VM_BIND_OP_TYPE_MAP.

DRM_PANTHOR_VM_BIND_OP_MAP_NOEXEC

Map the memory not-executable.

Only valid with DRM_PANTHOR_VM_BIND_OP_TYPE_MAP.

DRM_PANTHOR_VM_BIND_OP_MAP_UNCACHED

Map the memory uncached.

Only valid with DRM_PANTHOR_VM_BIND_OP_TYPE_MAP.

DRM_PANTHOR_VM_BIND_OP_TYPE_MASK

Mask used to determine the type of operation.

DRM_PANTHOR_VM_BIND_OP_TYPE_MAP

Map operation.

DRM_PANTHOR_VM_BIND_OP_TYPE_UNMAP

Unmap operation.

DRM_PANTHOR_VM_BIND_OP_TYPE_SYNC_ONLY

No VM operation.

Just serves as a synchronization point on a VM queue.

Only valid ifDRM_PANTHOR_VM_BIND_ASYNC is set in drm_panthor_vm_bind::flags,and drm_panthor_vm_bind_op::syncs contains at least one element.

Definition:

struct drm_panthor_vm_bind_op {    __u32 flags;    __u32 bo_handle;    __u64 bo_offset;    __u64 va;    __u64 size;    struct drm_panthor_obj_array syncs;};

Members

flags

Combination of drm_panthor_vm_bind_op_flags flags.

bo_handle

Handle of the buffer object to map.MBZ for unmap or sync-only operations.

bo_offset

Buffer object offset.MBZ for unmap or sync-only operations.

va

Virtual address to map/unmap.MBZ for sync-only operations.

size

Size to map/unmap.MBZ for sync-only operations.

syncs

Array ofstructdrm_panthor_sync_op synchronizationoperations.

This array must be empty ifDRM_PANTHOR_VM_BIND_ASYNC is not set onthe drm_panthor_vm_bind object containing this VM bind operation.

This array shall not be empty for sync-only operations.

Constants

DRM_PANTHOR_VM_BIND_ASYNC

VM bind operations are queued to the VMqueue instead of being executed synchronously.

Definition:

struct drm_panthor_vm_bind {    __u32 vm_id;    __u32 flags;    struct drm_panthor_obj_array ops;};

Members

vm_id

VM targeted by the bind request.

flags

Combination of drm_panthor_vm_bind_flags flags.

ops

Array ofstructdrm_panthor_vm_bind_op bind operations.

Constants

DRM_PANTHOR_VM_STATE_USABLE

VM is usable.

New VM operations will be accepted on this VM.

DRM_PANTHOR_VM_STATE_UNUSABLE

VM is unusable.

Something put the VM in an unusable state (like an asynchronousVM_BIND request failing for any reason).

Once the VM is in this state, all new MAP operations will berejected, and any GPU job targeting this VM will fail.UNMAP operations are still accepted.

The only way to recover from an unusable VM is to create a newVM, and destroy the old one.

Definition:

struct drm_panthor_vm_get_state {    __u32 vm_id;    __u32 state;};

Members

vm_id

VM targeted by the get_state request.

state

state returned by the driver.

Must be one of theenumdrm_panthor_vm_state values.

Constants

DRM_PANTHOR_BO_NO_MMAP

The buffer object will never be CPU-mapped in userspace.

DRM_PANTHOR_BO_WB_MMAP

Force “Write-Back Cacheable” CPU mapping.

CPU map the buffer object in userspace by forcing the “Write-BackCacheable” cacheability attribute. The mapping otherwise uses the“Non-Cacheable” attribute if the GPU is not IO coherent.

Definition:

struct drm_panthor_bo_create {    __u64 size;    __u32 flags;    __u32 exclusive_vm_id;    __u32 handle;    __u32 pad;};

Members

size

Requested size for the object

The (page-aligned) allocated size for the object will be returned.

flags

Flags. Must be a combination of drm_panthor_bo_flags flags.

exclusive_vm_id

Exclusive VM this buffer object will be mapped to.

If not zero, the field must refer to a valid VM ID, and implies that:

• the buffer object will only ever be bound to that VM

• cannot be exported as a PRIME fd

handle

Returned handle for the object.

Object handles are nonzero.

pad

MBZ.

Definition:

struct drm_panthor_bo_mmap_offset {    __u32 handle;    __u32 pad;    __u64 offset;};

Members

handle

Handle of the object we want an mmap offset for.

pad

MBZ.

offset

The fake offset to use for subsequent mmap calls.

Definition:

struct drm_panthor_queue_create {    __u8 priority;    __u8 pad[3];    __u32 ringbuf_size;};

Members

priority

Defines the priority of queues inside a group. Goes from 0 to 15,15 being the highest priority.

pad

Padding fields, MBZ.

ringbuf_size

Size of the ring buffer to allocate to this queue.

Constants

PANTHOR_GROUP_PRIORITY_LOW

Low priority group.

PANTHOR_GROUP_PRIORITY_MEDIUM

Medium priority group.

PANTHOR_GROUP_PRIORITY_HIGH

High priority group.

Requires CAP_SYS_NICE or DRM_MASTER.

PANTHOR_GROUP_PRIORITY_REALTIME

Realtime priority group.

Requires CAP_SYS_NICE or DRM_MASTER.

Definition:

struct drm_panthor_group_create {    struct drm_panthor_obj_array queues;    __u8 max_compute_cores;    __u8 max_fragment_cores;    __u8 max_tiler_cores;    __u8 priority;    __u32 pad;    __u64 compute_core_mask;    __u64 fragment_core_mask;    __u64 tiler_core_mask;    __u32 vm_id;    __u32 group_handle;};

Members

queues

Array of drm_panthor_queue_create elements.

max_compute_cores

Maximum number of cores that can be used by computejobs across CS queues bound to this group.

Must be less or equal to the number of bits set incompute_core_mask.

max_fragment_cores

Maximum number of cores that can be used by fragmentjobs across CS queues bound to this group.

Must be less or equal to the number of bits set infragment_core_mask.

max_tiler_cores

Maximum number of tilers that can be used by tiler jobsacross CS queues bound to this group.

Must be less or equal to the number of bits set intiler_core_mask.

priority

Group priority (seeenumdrm_panthor_group_priority).

pad

Padding field, MBZ.

compute_core_mask

Mask encoding cores that can be used for compute jobs.

This field must have at leastmax_compute_cores bits set.

The bits set here should also be set in drm_panthor_gpu_info::shader_present.

fragment_core_mask

Mask encoding cores that can be used for fragment jobs.

This field must have at leastmax_fragment_cores bits set.

The bits set here should also be set in drm_panthor_gpu_info::shader_present.

tiler_core_mask

Mask encoding cores that can be used for tiler jobs.

This field must have at leastmax_tiler_cores bits set.

The bits set here should also be set in drm_panthor_gpu_info::tiler_present.

vm_id

VM ID to bind this group to.

All submission to queues bound to this group will use this VM.

group_handle

Returned group handle. Passed back when submitting jobs ordestroying a group.

Definition:

struct drm_panthor_group_destroy {    __u32 group_handle;    __u32 pad;};

Members

group_handle

Group to destroy

pad

Padding field, MBZ.

Definition:

struct drm_panthor_queue_submit {    __u32 queue_index;    __u32 stream_size;    __u64 stream_addr;    __u32 latest_flush;    __u32 pad;    struct drm_panthor_obj_array syncs;};

Members

queue_index

Index of the queue inside a group.

stream_size

Size of the command stream to execute.

Must be 64-bit/8-byte aligned (the size of a CS instruction)

Can be zero if stream_addr is zero too.

When the stream size is zero, the queue submit serves as asynchronization point.

stream_addr

GPU address of the command stream to execute.

Must be aligned on 64-byte.

Can be zero is stream_size is zero too.

latest_flush

FLUSH_ID read at the time the stream was built.

This allows cache flush elimination for the automaticflush+invalidate(all) done at submission time, which is needed toensure the GPU doesn’t get garbage when reading the indirect commandstream buffers. If you want the cache flush to happenunconditionally, pass a zero here.

Ignored when stream_size is zero.

pad

MBZ.

syncs

Array ofstructdrm_panthor_sync_op sync operations.

Definition:

struct drm_panthor_group_submit {    __u32 group_handle;    __u32 pad;    struct drm_panthor_obj_array queue_submits;};

Members

group_handle

Handle of the group to queue jobs to.

pad

MBZ.

queue_submits

Array of drm_panthor_queue_submit objects.

Constants

DRM_PANTHOR_GROUP_STATE_TIMEDOUT

Group had unfinished jobs.

When a group ends up with this flag set, no jobs can be submitted to its queues.

DRM_PANTHOR_GROUP_STATE_FATAL_FAULT

Group had fatal faults.

When a group ends up with this flag set, no jobs can be submitted to its queues.

DRM_PANTHOR_GROUP_STATE_INNOCENT

Group was killed during a reset caused by othergroups.

This flag can only be set if DRM_PANTHOR_GROUP_STATE_TIMEDOUT is set andDRM_PANTHOR_GROUP_STATE_FATAL_FAULT is not.

Definition:

struct drm_panthor_group_get_state {    __u32 group_handle;    __u32 state;    __u32 fatal_queues;    __u32 pad;};

Members

group_handle

Handle of the group to query state on

state

Combination of DRM_PANTHOR_GROUP_STATE_* flags encoding thegroup state.

fatal_queues

Bitmask of queues that faced fatal faults.

pad

MBZ

Definition:

struct drm_panthor_tiler_heap_create {    __u32 vm_id;    __u32 initial_chunk_count;    __u32 chunk_size;    __u32 max_chunks;    __u32 target_in_flight;    __u32 handle;    __u64 tiler_heap_ctx_gpu_va;    __u64 first_heap_chunk_gpu_va;};

Members

vm_id

VM ID the tiler heap should be mapped to

initial_chunk_count

Initial number of chunks to allocate. Must be at least one.

chunk_size

Chunk size.

Must be page-aligned and lie in the [128k:8M] range.

max_chunks

Maximum number of chunks that can be allocated.

Must be at leastinitial_chunk_count.

target_in_flight

Maximum number of in-flight render passes.

If the heap has more than tiler jobs in-flight, the FW will wait for renderpasses to finish before queuing new tiler jobs.

handle

Returned heap handle. Passed back to DESTROY_TILER_HEAP.

tiler_heap_ctx_gpu_va

Returned heap GPU virtual address returned

first_heap_chunk_gpu_va

First heap chunk.

The tiler heap is formed of heap chunks forming a single-link list. Thisis the first element in the list.

Definition:

struct drm_panthor_tiler_heap_destroy {    __u32 handle;    __u32 pad;};

Members

handle

Handle of the tiler heap to destroy.

Must be a valid heap handle returned by DRM_IOCTL_PANTHOR_TILER_HEAP_CREATE.

pad

Padding field, MBZ.

Definition:

struct drm_panthor_bo_set_label {    __u32 handle;    __u32 pad;    __u64 label;};

Members

handle

Handle of the buffer object to label.

pad

MBZ.

label

User pointer to a NUL-terminated string

Length cannot be greater than 4096

Definition:

struct drm_panthor_set_user_mmio_offset {    __u64 offset;};

Members

offset

User MMIO offset to use.

Must be either DRM_PANTHOR_USER_MMIO_OFFSET_32BIT orDRM_PANTHOR_USER_MMIO_OFFSET_64BIT.

Use DRM_PANTHOR_USER_MMIO_OFFSET (which selects OFFSET_32BIT orOFFSET_64BIT based on the size of an unsigned long) unless youhave a very good reason to overrule this decision.

Constants

DRM_PANTHOR_BO_SYNC_CPU_CACHE_FLUSH

Flush CPU caches.

DRM_PANTHOR_BO_SYNC_CPU_CACHE_FLUSH_AND_INVALIDATE

Flush and invalidate CPU caches.

Definition:

struct drm_panthor_bo_sync_op {    __u32 handle;    __u32 type;    __u64 offset;    __u64 size;};

Members

handle

Handle of the buffer object to sync.

type

Type of operation.

offset

Offset into the BO at which the sync range starts.

This will be rounded down to the nearest cache line as needed.

size

Size of the range to sync

size +offset will be rounded up to the nearest cache line asneeded.

Definition:

struct drm_panthor_bo_sync {    struct drm_panthor_obj_array ops;};

Members

ops

Array ofstructdrm_panthor_bo_sync_op sync operations.

Constants

DRM_PANTHOR_BO_IS_IMPORTED

BO has been imported from an external driver.

Note that imported dma-buf handles are not flagged as imported if theywhere exported by panthor. Only buffers that are coming from other drivers(dma heaps, other GPUs, display controllers, V4L, ...).

It’s also important to note that all imported BOs are mapped cached and can’tbe considered IO-coherent even if the GPU is. This means they require explicitsyncs that must go through the DRM_PANTHOR_BO_SYNC ioctl (userland cachemaintenance is not allowed in that case, because extra operations might beneeded to make changes visible to the CPU/device, like buffer migration when theexporter is a GPU with its own VRAM).

Definition:

struct drm_panthor_bo_query_info {    __u32 handle;    __u32 extra_flags;    __u32 create_flags;    __u32 pad;};

Members

handle

Handle of the buffer object to query flags on.

extra_flags

Combination ofenumdrm_panthor_bo_extra_flags flags.

create_flags

Flags passed at creation time.

Combination ofenumdrm_panthor_bo_flags flags.Will be zero if the buffer comes from a different driver.

pad

Will be zero on return.

Parameters

__access

Access type. Must be R, W or RW.

__id

One of the DRM_PANTHOR_xxx id.

__type

Suffix of the type being passed to the IOCTL.

Description

Don’t use this macro directly, use the DRM_IOCTL_PANTHOR_xxxvalues instead.

Return

An IOCTL number to be passed to ioctl() from userspace.

Definition:

struct drm_xe_user_extension {    __u64 next_extension;    __u32 name;    __u32 pad;};

Members

next_extension

Pointer to the nextstructdrm_xe_user_extension, or zero if the end.

name

Name of the extension.

Note that the name here is just some integer.

Also note that the name space for this is not global for the wholedriver, but rather its scope/meaning is limited to the specific pieceof uAPI which has embedded thestructdrm_xe_user_extension.

pad

MBZ

All undefined bits must be zero.

Definition:

struct drm_xe_ext_set_property {    struct drm_xe_user_extension base;    __u32 property;    __u32 pad;    union {        __u64 value;        __u64 ptr;    };    __u64 reserved[2];};

Members

base

base user extension

property

property to set

pad

MBZ

{unnamed_union}

anonymous

value

property value

ptr

pointer to user value

reserved

Reserved

Definition:

struct drm_xe_engine_class_instance {#define DRM_XE_ENGINE_CLASS_RENDER              0;#define DRM_XE_ENGINE_CLASS_COPY                1;#define DRM_XE_ENGINE_CLASS_VIDEO_DECODE        2;#define DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE       3;#define DRM_XE_ENGINE_CLASS_COMPUTE             4;#define DRM_XE_ENGINE_CLASS_VM_BIND             5;    __u16 engine_class;    __u16 engine_instance;    __u16 gt_id;    __u16 pad;};

Members

engine_class

engine class id

engine_instance

engine instance id

gt_id

Unique ID of this GT within the PCI Device

pad

MBZ

Definition:

struct drm_xe_engine {    struct drm_xe_engine_class_instance instance;    __u64 reserved[3];};

Members

instance

Thedrm_xe_engine_class_instance

reserved

Reserved

Definition:

struct drm_xe_query_engines {    __u32 num_engines;    __u32 pad;    struct drm_xe_engine engines[];};

Members

num_engines

number of engines returned inengines

pad

MBZ

engines

The returned engines for this device

Constants

DRM_XE_MEM_REGION_CLASS_SYSMEM

Represents system memory.

DRM_XE_MEM_REGION_CLASS_VRAM

On discrete platforms, thisrepresents the memory that is local to the device, which wecall VRAM. Not valid on integrated platforms.

Definition:

struct drm_xe_mem_region {    __u16 mem_class;    __u16 instance;    __u32 min_page_size;    __u64 total_size;    __u64 used;    __u64 cpu_visible_size;    __u64 cpu_visible_used;    __u64 reserved[6];};

Members

mem_class

The memory class describing this region.

Seeenumdrm_xe_memory_class for supported values.

instance

The unique ID for this region, which serves as theindex in the placement bitmask used as argument forDRM_IOCTL_XE_GEM_CREATE

min_page_size

Min page-size in bytes for this region.

When the kernel allocates memory for this region, theunderlying pages will be at leastmin_page_size in size.Buffer objects with an allowable placement in this region must becreated with a size aligned to this value.GPU virtual address mappings of (parts of) buffer objects thatmay be placed in this region must also have their GPU virtualaddress and range aligned to this value.Affected IOCTLS will return-EINVAL if alignment restrictions arenot met.

total_size

The usable size in bytes for this region.

used

Estimate of the memory used in bytes for this region.

cpu_visible_size

How much of this region can be CPUaccessed, in bytes.

This will always be <=total_size, and the remainder (ifany) will not be CPU accessible. If the CPU accessible partis smaller thantotal_size then this is referred to as asmall BAR system.

On systems without small BAR (full BAR), the probed_size willalways equal thetotal_size, since all of it will be CPUaccessible.

Note this is only tracked for DRM_XE_MEM_REGION_CLASS_VRAMregions (for other types the value here will always equalzero).

cpu_visible_used

Estimate of CPU visible memory used, inbytes.

Note this is only currently tracked forDRM_XE_MEM_REGION_CLASS_VRAM regions (for other types the valuehere will always be zero).

reserved

Reserved

Definition:

struct drm_xe_query_mem_regions {    __u32 num_mem_regions;    __u32 pad;    struct drm_xe_mem_region mem_regions[];};

Members

num_mem_regions

number of memory regions returned inmem_regions

pad

MBZ

mem_regions

The returned memory regions for this device

Definition:

struct drm_xe_query_config {    __u32 num_params;    __u32 pad;#define DRM_XE_QUERY_CONFIG_REV_AND_DEVICE_ID   0;#define DRM_XE_QUERY_CONFIG_FLAGS                       1;#define DRM_XE_QUERY_CONFIG_FLAG_HAS_VRAM       (1 << 0);#define DRM_XE_QUERY_CONFIG_FLAG_HAS_LOW_LATENCY        (1 << 1);#define DRM_XE_QUERY_CONFIG_FLAG_HAS_CPU_ADDR_MIRROR    (1 << 2);#define DRM_XE_QUERY_CONFIG_FLAG_HAS_NO_COMPRESSION_HINT (1 << 3);#define DRM_XE_QUERY_CONFIG_MIN_ALIGNMENT               2;#define DRM_XE_QUERY_CONFIG_VA_BITS                     3;#define DRM_XE_QUERY_CONFIG_MAX_EXEC_QUEUE_PRIORITY     4;    __u64 info[];};

Members

num_params

number of parameters returned in info

pad

MBZ

info

array of elements containing the config info

Definition:

struct drm_xe_gt {#define DRM_XE_QUERY_GT_TYPE_MAIN               0;#define DRM_XE_QUERY_GT_TYPE_MEDIA              1;    __u16 type;    __u16 tile_id;    __u16 gt_id;    __u16 pad[3];    __u32 reference_clock;    __u64 near_mem_regions;    __u64 far_mem_regions;    __u16 ip_ver_major;    __u16 ip_ver_minor;    __u16 ip_ver_rev;    __u16 pad2;    __u64 reserved[7];};

Members

type

GT type: Main or Media

tile_id

Tile ID where this GT lives (Information only)

gt_id

Unique ID of this GT within the PCI Device

pad

MBZ

reference_clock

A clock frequency for timestamp

near_mem_regions

Bit mask of instances fromdrm_xe_query_mem_regions that are nearest to the current enginesof this GT.Each index in this mask refers directly to thestructdrm_xe_query_mem_regions’ instance, no assumptions shouldbe made about order. The type of each region is describedbystructdrm_xe_query_mem_regions’ mem_class.

far_mem_regions

Bit mask of instances fromdrm_xe_query_mem_regions that are far from the engines of this GT.In general, they have extra indirections when compared to thenear_mem_regions. For a discrete device this could mean systemmemory and memory living in a different tile.Each index in this mask refers directly to thestructdrm_xe_query_mem_regions’ instance, no assumptions shouldbe made about order. The type of each region is describedbystructdrm_xe_query_mem_regions’ mem_class.

ip_ver_major

Graphics/media IP major version on GMD_ID platforms

ip_ver_minor

Graphics/media IP minor version on GMD_ID platforms

ip_ver_rev

Graphics/media IP revision version on GMD_ID platforms

pad2

MBZ

reserved

Reserved

Definition:

struct drm_xe_query_gt_list {    __u32 num_gt;    __u32 pad;    struct drm_xe_gt gt_list[];};

Members

num_gt

number of GT items returned in gt_list

pad

MBZ

gt_list

The GT list returned for this device

Definition:

struct drm_xe_query_topology_mask {    __u16 gt_id;#define DRM_XE_TOPO_DSS_GEOMETRY        1;#define DRM_XE_TOPO_DSS_COMPUTE         2;#define DRM_XE_TOPO_L3_BANK             3;#define DRM_XE_TOPO_EU_PER_DSS          4;#define DRM_XE_TOPO_SIMD16_EU_PER_DSS   5;    __u16 type;    __u32 num_bytes;    __u8 mask[];};

Members

gt_id

GT ID the mask is associated with

type

type of mask

num_bytes

number of bytes in requested mask

mask

little-endian mask ofnum_bytes

Definition:

struct drm_xe_query_engine_cycles {    struct drm_xe_engine_class_instance eci;    __s32 clockid;    __u32 width;    __u64 engine_cycles;    __u64 cpu_timestamp;    __u64 cpu_delta;};

Members

eci

This is input by the user and is the engine for which commandstreamer cycles is queried.

clockid

This is input by the user and is the reference clock id forCPU timestamp. For definition, see clock_gettime(2) andperf_event_open(2). Supported clock ids are CLOCK_MONOTONIC,CLOCK_MONOTONIC_RAW, CLOCK_REALTIME, CLOCK_BOOTTIME, CLOCK_TAI.

width

Width of the engine cycle counter in bits.

engine_cycles

Engine cycles as read from its registerat 0x358 offset.

cpu_timestamp

CPU timestamp in ns. The timestamp is captured beforereading the engine_cycles register using the reference clockid set by theuser.

cpu_delta

Time delta in ns captured around reading the lower dwordof the engine_cycles register.

Definition:

struct drm_xe_query_uc_fw_version {#define XE_QUERY_UC_TYPE_GUC_SUBMISSION 0;#define XE_QUERY_UC_TYPE_HUC 1;    __u16 uc_type;    __u16 pad;    __u32 branch_ver;    __u32 major_ver;    __u32 minor_ver;    __u32 patch_ver;    __u32 pad2;    __u64 reserved;};

Members

uc_type

The micro-controller type to query firmware version

pad

MBZ

branch_ver

branch uc fw version

major_ver

major uc fw version

minor_ver

minor uc fw version

patch_ver

patch uc fw version

pad2

MBZ

reserved

Reserved

Definition:

struct drm_xe_query_pxp_status {    __u32 status;    __u32 supported_session_types;};

Members

status

current PXP status

supported_session_types

bitmask of supported PXP session types

Definition:

struct drm_xe_device_query {    __u64 extensions;#define DRM_XE_DEVICE_QUERY_ENGINES             0;#define DRM_XE_DEVICE_QUERY_MEM_REGIONS         1;#define DRM_XE_DEVICE_QUERY_CONFIG              2;#define DRM_XE_DEVICE_QUERY_GT_LIST             3;#define DRM_XE_DEVICE_QUERY_HWCONFIG            4;#define DRM_XE_DEVICE_QUERY_GT_TOPOLOGY         5;#define DRM_XE_DEVICE_QUERY_ENGINE_CYCLES       6;#define DRM_XE_DEVICE_QUERY_UC_FW_VERSION       7;#define DRM_XE_DEVICE_QUERY_OA_UNITS            8;#define DRM_XE_DEVICE_QUERY_PXP_STATUS          9;#define DRM_XE_DEVICE_QUERY_EU_STALL            10;    __u32 query;    __u32 size;    __u64 data;    __u64 reserved[2];};

Members

extensions

Pointer to the first extension struct, if any

query

The type of data to query

size

Size of the queried data

data

Queried data is placed here

reserved

Reserved

Definition:

struct drm_xe_gem_create {#define DRM_XE_GEM_CREATE_EXTENSION_SET_PROPERTY        0;#define DRM_XE_GEM_CREATE_SET_PROPERTY_PXP_TYPE       0;    __u64 extensions;    __u64 size;    __u32 placement;#define DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING            (1 << 0);#define DRM_XE_GEM_CREATE_FLAG_SCANOUT                  (1 << 1);#define DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM       (1 << 2);#define DRM_XE_GEM_CREATE_FLAG_NO_COMPRESSION           (1 << 3);    __u32 flags;    __u32 vm_id;    __u32 handle;#define DRM_XE_GEM_CPU_CACHING_WB                      1;#define DRM_XE_GEM_CPU_CACHING_WC                      2;    __u16 cpu_caching;    __u16 pad[3];    __u64 reserved[2];};

Members

extensions

Pointer to the first extension struct, if any

size

Size of the object to be created, must match region(system or vram) minimum alignment (min_page_size).

placement

A mask of memory instances of where BO can be placed.Each index in this mask refers directly to thestructdrm_xe_query_mem_regions’ instance, no assumptions shouldbe made about order. The type of each region is describedbystructdrm_xe_query_mem_regions’ mem_class.

flags

Flags, currently a mask of memory instances of where BO canbe placed

vm_id

Attached VM, if any

If a VM is specified, this BO must:

1. Only ever be bound to that VM.

2. Cannot be exported as a PRIME fd.

handle

Returned handle for the object.

Object handles are nonzero.

cpu_caching

The CPU caching mode to select for this object. Ifmmaping the object the mode selected here will also be used. Theexception is when mapping system memory (including data evictedto system) on discrete GPUs. The caching mode selected willthen be overridden to DRM_XE_GEM_CPU_CACHING_WB, and coherencybetween GPU- and CPU is guaranteed. The caching mode ofexisting CPU-mappings will be updated transparently touser-space clients.

pad

MBZ

reserved

Reserved

Definition:

struct drm_xe_gem_mmap_offset {    __u64 extensions;    __u32 handle;#define DRM_XE_MMAP_OFFSET_FLAG_PCI_BARRIER     (1 << 0);    __u32 flags;    __u64 offset;    __u64 reserved[2];};

Members

extensions

Pointer to the first extension struct, if any

handle

Handle for the object being mapped.

flags

Flags

offset

The fake offset to use for subsequent mmap call

reserved

Reserved

Definition:

struct drm_xe_vm_create {    __u64 extensions;#define DRM_XE_VM_CREATE_FLAG_SCRATCH_PAGE      (1 << 0);#define DRM_XE_VM_CREATE_FLAG_LR_MODE           (1 << 1);#define DRM_XE_VM_CREATE_FLAG_FAULT_MODE        (1 << 2);    __u32 flags;    __u32 vm_id;    __u64 reserved[2];};

Members

extensions

Pointer to the first extension struct, if any

flags

Flags

vm_id

Returned VM ID

reserved

Reserved

Definition:

struct drm_xe_vm_destroy {    __u32 vm_id;    __u32 pad;    __u64 reserved[2];};

Members

vm_id

VM ID

pad

MBZ

reserved

Reserved

Definition:

struct drm_xe_vm_bind_op {    __u64 extensions;    __u32 obj;    __u16 pat_index;    __u16 pad;    union {        __u64 obj_offset;        __u64 userptr;        __s64 cpu_addr_mirror_offset;    };    __u64 range;    __u64 addr;#define DRM_XE_VM_BIND_OP_MAP           0x0;#define DRM_XE_VM_BIND_OP_UNMAP         0x1;#define DRM_XE_VM_BIND_OP_MAP_USERPTR   0x2;#define DRM_XE_VM_BIND_OP_UNMAP_ALL     0x3;#define DRM_XE_VM_BIND_OP_PREFETCH      0x4;    __u32 op;#define DRM_XE_VM_BIND_FLAG_READONLY    (1 << 0);#define DRM_XE_VM_BIND_FLAG_IMMEDIATE   (1 << 1);#define DRM_XE_VM_BIND_FLAG_NULL        (1 << 2);#define DRM_XE_VM_BIND_FLAG_DUMPABLE    (1 << 3);#define DRM_XE_VM_BIND_FLAG_CHECK_PXP   (1 << 4);#define DRM_XE_VM_BIND_FLAG_CPU_ADDR_MIRROR     (1 << 5);#define DRM_XE_VM_BIND_FLAG_MADVISE_AUTORESET   (1 << 6);    __u32 flags;#define DRM_XE_CONSULT_MEM_ADVISE_PREF_LOC      -1;    __u32 prefetch_mem_region_instance;    __u32 pad2;    __u64 reserved[3];};

Members

extensions

Pointer to the first extension struct, if any

obj

GEM object to operate on, MBZ for MAP_USERPTR, MBZ for UNMAP

pat_index

The platform definedpat_index to use for this mapping.The index basically maps to some predefined memory attributes,including things like caching, coherency, compression etc. The exactmeaning of the pat_index is platform specific and defined in theBspec and PRMs. When the KMD sets up the binding the index here isencoded into the ppGTT PTE.

For coherency thepat_index needs to be at least 1way coherent whendrm_xe_gem_create.cpu_caching is DRM_XE_GEM_CPU_CACHING_WB. The KMDwill extract the coherency mode from thepat_index and reject ifthere is a mismatch (see note below for pre-MTL platforms).

Note: On pre-MTL platforms there is only a caching mode and noexplicit coherency mode, but on such hardware there is always ashared-LLC (or is dgpu) so all GT memory accesses are coherent withCPU caches even with the caching mode set as uncached. It’s only thedisplay engine that is incoherent (on dgpu it must be in VRAM whichis always mapped as WC on the CPU). However to keep the uapi somewhatconsistent with newer platforms the KMD groups the different cachelevels into the following coherency buckets on all pre-MTL platforms:

ppGTT UC -> COH_NONEppGTT WC -> COH_NONEppGTT WT -> COH_NONEppGTT WB -> COH_AT_LEAST_1WAY

In practice UC/WC/WT should only ever used for scanout surfaces onsuch platforms (or perhaps in general for dma-buf if shared withanother device) since it is only the display engine that is actuallyincoherent. Everything else should typically use WB given that wehave a shared-LLC. On MTL+ this completely changes and the HWdefines the coherency mode as part of thepat_index, whereincoherent GT access is possible.

Note: For userptr and externally imported dma-buf the kernel expectseither 1WAY or 2WAY for thepat_index.

For DRM_XE_VM_BIND_FLAG_NULL bindings there are no KMD restrictionson thepat_index. For such mappings there is no actual memory beingmapped (the address in the PTE is invalid), so the various PAT memoryattributes likely do not apply. Simply leaving as zero is oneoption (still a valid pat_index). Same applies toDRM_XE_VM_BIND_FLAG_CPU_ADDR_MIRROR bindings as for such mappingthere is no actual memory being mapped.

pad

MBZ

{unnamed_union}

anonymous

obj_offset

Offset into the object, MBZ for CLEAR_RANGE,ignored for unbind

userptr

user pointer to bind on

cpu_addr_mirror_offset

Offset from GPUaddr to createCPU address mirror mappings. MBZ with current level ofsupport (e.g. 1 to 1 mapping between GPU and CPU mappingsonly supported).

range

Number of bytes from the object to bind to addr, MBZ for UNMAP_ALL

addr

Address to operate on, MBZ for UNMAP_ALL

op

Bind operation to perform

flags

Bind flags

prefetch_mem_region_instance

Memory region to prefetch VMA to.It is a region instance, not a mask.To be used only withDRM_XE_VM_BIND_OP_PREFETCH operation.

pad2

MBZ

reserved

Reserved

Definition:

struct drm_xe_vm_bind {    __u64 extensions;    __u32 vm_id;    __u32 exec_queue_id;    __u32 pad;    __u32 num_binds;    union {        struct drm_xe_vm_bind_op bind;        __u64 vector_of_binds;    };    __u32 pad2;    __u32 num_syncs;    __u64 syncs;    __u64 reserved[2];};

Members

extensions

Pointer to the first extension struct, if any

vm_id

The ID of the VM to bind to

exec_queue_id

exec_queue_id, must be of class DRM_XE_ENGINE_CLASS_VM_BINDand exec queue must have same vm_id. If zero, the default VM bind engineis used.

pad

MBZ

num_binds

number of binds in this IOCTL

{unnamed_union}

anonymous

bind

used if num_binds == 1

vector_of_binds

userptr to array ofstructdrm_xe_vm_bind_op if num_binds > 1

pad2

MBZ

num_syncs

amount of syncs to wait on

syncs

pointer tostructdrm_xe_sync array

reserved

Reserved