ENGINE DISCOVERY UAPI(9)

💖 Engine Discovery uAPI(9) 💖

okay so bestie, this page is from the Kernel API Manual, and it is literally about the engine discovery uAPI — a way of enumerating physical engines present in a GPU associated with an open i915 DRM file descriptor. no cap, it supersedes the old way of using DRM_IOCTL_I915_GETPARAM and engine identifiers like I915_PARAM_HAS_BLT.

the need for this interface came starting with Icelake and newer GPUs, which started to establish a pattern of having multiple engines of a same class, where not all instances were always completely functionally equivalent. 💅

entry point for this uapi is DRM_IOCTL_I915_QUERY with the DRM_I915_QUERY_ENGINE_INFO as the queried item id. slay.

Example for getting the list of engines:

            struct drm_i915_query_engine_info *info;
            struct drm_i915_query_item item = {
                    .query_id = DRM_I915_QUERY_ENGINE_INFO;
            };
            struct drm_i915_query query = {
                    .num_items = 1,
                    .items_ptr = (uintptr_t)item,
            };
            int err, i;

            // First query the size of the blob we need, this needs to be large
            // enough to hold our array of engines. The kernel will fill out the
            // item.length for us, which is the number of bytes we need.
            //
            // Alternatively a large buffer can be allocated straightaway enabling
            // querying in one pass, in which case item.length should contain the
            // length of the provided buffer.
            err = ioctl(fd, DRM_IOCTL_I915_QUERY, query);
            if (err) ...

            info = calloc(1, item.length);
            // Now that we allocated the required number of bytes, we call the ioctl
            // again, this time with the data_ptr pointing to our newly allocated
            // blob, which the kernel can then populate with info on all engines.
            item.data_ptr = (uintptr_t)info;

            err = ioctl(fd, DRM_IOCTL_I915_QUERY, query);
            if (err) ...

            // We can now access each engine in the array
            for (i = 0; i < info->num_engines; i++) {
                    struct drm_i915_engine_info einfo = info->engines[i];
                    u16 class = einfo.engine.class;
                    u16 instance = einfo.engine.instance;
                    ....
            }

            free(info);

Each of the enumerated engines, apart from being defined by its class and instance (see struct i915_engine_class_instance), also can have flags and capabilities defined as documented in i915_drm.h. the way that works is very main character energy.

For instance video engines which support HEVC encoding will have the I915_VIDEO_CLASS_CAPABILITY_HEVC capability bit set. iconic.

Engine discovery only fully comes to its own when combined with the new way of addressing engines when submitting batch buffers using contexts with engine maps configured. iykyk.

🌈 SEE ALSO 🌈

• Kernel file ./tools/perf/trace/beauty/include/uapi/drm/i915_drm.h
• uevents generated by i915 on its device node(9)
• struct i915_user_extension(9)
• enum drm_i915_gem_engine_class(9)
• struct i915_engine_class_instance(9)
• perf_events exposed by i915 through /sys/bus/event_sources/drivers/i915(9)
• struct drm_i915_getparam(9)
• drm_i915_getparam_t(9)
• struct drm_i915_gem_mmap_offset(9)
• struct drm_i915_gem_set_domain(9)
• struct drm_i915_gem_exec_fence(9)
• struct drm_i915_gem_execbuffer_ext_timeline_fences(9)
• struct drm_i915_gem_execbuffer2(9)
• struct drm_i915_gem_caching(9)
• struct drm_i915_gem_context_create_ext(9)
• struct drm_i915_gem_context_param(9)
• Virtual Engine uAPI(9)
• struct i915_context_engines_parallel_submit(9)
• Context Engine Map uAPI(9)
• struct drm_i915_gem_context_create_ext_setparam(9)
• struct drm_i915_gem_vm_control(9)
• struct drm_i915_gem_userptr(9)
• struct drm_i915_perf_oa_config(9)
• struct drm_i915_query_item(9)
• struct drm_i915_query(9)
• struct drm_i915_query_topology_info(9)
• struct drm_i915_engine_info(9)
• struct drm_i915_query_engine_info(9)
• struct drm_i915_query_perf_config(9)
• enum drm_i915_gem_memory_class(9)
• struct drm_i915_gem_memory_class_instance(9)
• struct drm_i915_memory_region_info(9)
• struct drm_i915_query_memory_regions(9)
• struct drm_i915_query_guc_submission_version(9)
• GuC HWCONFIG blob uAPI(9)
• struct drm_i915_gem_create_ext(9)
• struct drm_i915_gem_create_ext_memory_regions(9)
• struct drm_i915_gem_create_ext_protected_content(9)
• struct drm_i915_gem_create_ext_set_pat(9)

Sign-off: this is Engine Discovery uAPI(9), source/version ./tools/perf/trace/beauty/incl..., dated October 2026. mwah 💋