#include <i915_drm.h>

Collaboration diagram for drm_i915_engine_info:

Public Attributes
struct i915_engine_class_instance	engine

__u32	rsvd0

__u64	flags

__u64	capabilities

__u16	logical_instance

__u16	rsvd1 [3]

__u64	rsvd2 [3]

Detailed Description

DOC: Engine Discovery uAPI

Engine discovery uAPI is a way of enumerating physical engines present in a GPU associated with an open i915 DRM file descriptor. This 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.

Example for getting the list of engines:

.. code-block:: C

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.

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

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. struct drm_i915_engine_info

Describes one engine and its capabilities as known to the driver.

Member Data Documentation

◆ capabilities

__u64 drm_i915_engine_info::capabilities

@capabilities: Capabilities of this engine.

◆ engine

struct i915_engine_class_instance drm_i915_engine_info::engine

@engine: Engine class and instance.

◆ flags

__u64 drm_i915_engine_info::flags

@flags: Engine flags.

◆ logical_instance

__u16 drm_i915_engine_info::logical_instance

@logical_instance: Logical instance of engine

◆ rsvd0

__u32 drm_i915_engine_info::rsvd0

@rsvd0: Reserved field.

◆ rsvd1

__u16 drm_i915_engine_info::rsvd1[3]

@rsvd1: Reserved fields.

◆ rsvd2

__u64 drm_i915_engine_info::rsvd2[3]

@rsvd2: Reserved fields.

The documentation for this struct was generated from the following file:

XenevaOS/BaseHdr/uapi/drm/i915_drm.h

Public Attributes