GEM Engine Topology

GEM Engine Topology — Helpers for dealing engine topology

Functions

Types and Values

Description

This helper library contains functions used for querying and dealing with engines in GEM contexts.

Combined with intel_ctx_t, these helpers give a pretty standard pattern for testing every engine in a device:

1
2
3
4
5
6
7
8
9
const struct intel_execution_engine2 *e;
const intel_ctx_t *ctx = intel_ctx_create_all_physical(fd);

igt_subtest_with_dynamic("basic") {
    for_each_ctx_engine(fd, ctx, e) {
        igt_dynamic_f("%s", e->name)
        run_ctx_test(fd, ctx, e);
    }
}

This pattern works regardless of whether or not the engines topology API is available and regardless of whether or not your platform supports contexts. If engines are unavailable, it falls back to a legacy context and if contexts are unavailable, intel_ctx_create_all_physical() will return a wrapper around ctx0.

If, for some reason, you want to create a second identical context to use with your engine iterator, duplicating the context is easy:

1
const intel_ctx_t *ctx2 = intel_ctx_create(fd, &ctx->cfg);

If you want each subtest to always create its own contexts, there are also iterators which work only on a context config. As long as all contexts are created from that config, or from one with an identical set of engines, the iterator will be valid for those contexts.

1
2
3
4
5
6
7
8
9
const struct intel_execution_engine2 *e;
intel_ctx_cfg_t cfg = intel_ctx_cfg_all_physical(fd);

igt_subtest_with_dynamic("basic") {
    for_each_ctx_cfg_engine(fd, &cfg, e) {
        igt_dynamic_f("%s", e->name)
        run_ctx_cfg_test(fd, &cfg, e);
    }
}

Functions

gem_has_engine_topology ()

bool
gem_has_engine_topology (int fd);

Queries whether the engine topology API is supported or not. Every kernel that has the global engines query should have the CONTEXT_PARAM_ENGINES and vice versa so this one check can be used for either.

Parameters

fd

open i915 drm file descriptor

 

Returns

Engine topology API availability.


intel_engine_list_of_physical ()

struct intel_engine_data
intel_engine_list_of_physical (int fd);

Returns the list of all physical engines in the device

Parameters

fd

open i915 drm file descriptor

 

intel_engine_list_for_ctx_cfg ()

struct intel_engine_data
intel_engine_list_for_ctx_cfg (int fd,
                               const intel_ctx_cfg_t *cfg);

Returns the list of all engines in the context config

Parameters

fd

open i915 drm file descriptor

 

cfg

Context config

 

intel_get_current_engine ()

struct intel_execution_engine2 *
intel_get_current_engine (struct intel_engine_data *ed);

intel_get_current_physical_engine ()

struct intel_execution_engine2 *
intel_get_current_physical_engine (struct intel_engine_data *ed);

intel_next_engine ()

void
intel_next_engine (struct intel_engine_data *ed);

gem_engine_is_equal ()

bool
gem_engine_is_equal (const struct intel_execution_engine2 *e1,
                     const struct intel_execution_engine2 *e2);

gem_eb_flags_to_engine ()

struct intel_execution_engine2
gem_eb_flags_to_engine (unsigned int flags);

for_each_ctx_cfg_engine()

#define             for_each_ctx_cfg_engine(fd__, ctx_cfg__, e__)

Iterates over each physical engine in the context config

Parameters

fd__

open i915 drm file descriptor

 

ctx_cfg__

Intel context config

 

e__

struct intel_execution_engine2 iterator

 

for_each_ctx_engine()

#define             for_each_ctx_engine(fd__, ctx__, e__)

Iterates over each physical engine in the context

Parameters

fd__

open i915 drm file descriptor

 

ctx__

Intel context wrapper

 

e__

struct intel_execution_engine2 iterator

 

for_each_physical_engine()

#define             for_each_physical_engine(fd__, e__)

Iterates over each physical engine in device. Be careful when using this iterator as your context may not have all of these engines and the intel_execution_engine2::flags field in the iterator may not match your context configuration.

Parameters

fd__

open i915 drm file descriptor

 

e__

struct intel_execution_engine2 iterator

 

gem_engine_property_scanf ()

int
gem_engine_property_scanf (int i915,
                           const char *engine,
                           const char *attr,
                           const char *fmt,
                           ...);

gem_engine_property_printf ()

int
gem_engine_property_printf (int i915,
                            const char *engine,
                            const char *attr,
                            const char *fmt,
                            ...);

gem_engine_mmio_base ()

uint32_t
gem_engine_mmio_base (int i915,
                      const char *engine);

dyn_sysfs_engines ()

void
dyn_sysfs_engines (int i915,
                   int engines,
                   const char *file,
                   void (*test) (int i915, int engine));

Types and Values

struct intel_engine_data

struct intel_engine_data {
	uint32_t nengines;
	uint32_t n;
	struct intel_execution_engine2 *current_engine;
	struct intel_execution_engine2 engines[GEM_MAX_ENGINES];
};

This struct acts as an interator for walking over a set of engines.

Members

uint32_t nengines;

Number of engines

 

uint32_t n;

Current engine index

 

struct intel_execution_engine2 *current_engine;

Current engine

 

struct intel_execution_engine2 engines[GEM_MAX_ENGINES];

List of all engines