i915_context_engines_load_balance Struct Reference

#include <i915_drm.h>

Collaboration diagram for i915_context_engines_load_balance:

Public Attributes
struct i915_user_extension	base
__u16	engine_index
__u16	num_siblings
__u32	flags
__u64	mbz64
struct i915_engine_class_instance	engines []

Detailed Description

DOC: Virtual Engine uAPI

Virtual engine is a concept where userspace is able to configure a set of physical engines, submit a batch buffer, and let the driver execute it on any engine from the set as it sees fit.

This is primarily useful on parts which have multiple instances of a same class engine, like for example GT3+ Skylake parts with their two VCS engines.

For instance userspace can enumerate all engines of a certain class using the previously described Engine Discovery uAPI_. After that userspace can create a GEM context with a placeholder slot for the virtual engine (using I915_ENGINE_CLASS_INVALID and I915_ENGINE_CLASS_INVALID_NONE for class and instance respectively) and finally using the I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE extension place a virtual engine in the same reserved slot.

Example of creating a virtual engine and submitting a batch buffer to it:

.. code-block:: C

I915_DEFINE_CONTEXT_ENGINES_LOAD_BALANCE(virtual, 2) = {
    .base.name = I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE,
    .engine_index = 0, // Place this virtual engine into engine map slot 0
    .num_siblings = 2,
    .engines = { { I915_ENGINE_CLASS_VIDEO, 0 },
             { I915_ENGINE_CLASS_VIDEO, 1 }, },
};
I915_DEFINE_CONTEXT_PARAM_ENGINES(engines, 1) = {
    .engines = { { I915_ENGINE_CLASS_INVALID,
               I915_ENGINE_CLASS_INVALID_NONE } },
    .extensions = to_user_pointer(&virtual), // Chains after load_balance extension
};
struct drm_i915_gem_context_create_ext_setparam p_engines = {
    .base = {
        .name = I915_CONTEXT_CREATE_EXT_SETPARAM,
    },
    .param = {
        .param = I915_CONTEXT_PARAM_ENGINES,
        .value = to_user_pointer(&engines),
        .size = sizeof(engines),
    },
};
struct drm_i915_gem_context_create_ext create = {
    .flags = I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS,
    .extensions = to_user_pointer(&p_engines);
};

ctx_id = gem_context_create_ext(drm_fd, &create);

// Now we have created a GEM context with its engine map containing a
// single virtual engine. Submissions to this slot can go either to
// vcs0 or vcs1, depending on the load balancing algorithm used inside
// the driver. The load balancing is dynamic from one batch buffer to
// another and transparent to userspace.

...
execbuf.rsvd1 = ctx_id;
execbuf.flags = 0; // Submits to index 0 which is the virtual engine
gem_execbuf(drm_fd, &execbuf);

Member Data Documentation

base

struct i915_user_extension i915_context_engines_load_balance::base

engine_index

__u16 i915_context_engines_load_balance::engine_index

engines

struct i915_engine_class_instance i915_context_engines_load_balance::engines[]

flags

__u32 i915_context_engines_load_balance::flags

mbz64

__u64 i915_context_engines_load_balance::mbz64

num_siblings

__u16 i915_context_engines_load_balance::num_siblings

---

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

• XenevaOS/BaseHdr/uapi/drm/i915_drm.h