GEM Engine Topology

GEM Engine Topology — Helpers for dealing engine topology

Functions

bool gem_has_engine_topology ()
struct intel_engine_data intel_engine_list_of_physical ()
struct intel_engine_data intel_engine_list_for_ctx_cfg ()
struct intel_execution_engine2 * intel_get_current_engine ()
struct intel_execution_engine2 * intel_get_current_physical_engine ()
void intel_next_engine ()
struct i915_engine_class_instance * gem_list_engines ()
bool gem_engine_is_equal ()
struct intel_execution_engine2 gem_eb_flags_to_engine ()
#define for_each_ctx_cfg_engine()
#define for_each_ctx_engine()
#define for_each_physical_engine()
void gem_engine_properties_configure ()
void gem_engine_properties_restore ()
int gem_engine_property_scanf ()
int gem_engine_property_printf ()
uint32_t gem_engine_mmio_base ()
bool gem_engine_has_capability ()
bool gem_engine_has_known_capability ()
bool gem_engine_can_block_copy ()
void dyn_sysfs_engines ()

Types and Values

struct intel_engine_data
struct gem_engine_properties

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_list_engines ()

struct i915_engine_class_instance *
gem_list_engines (int i915,
                  uint32_t gt_mask,
                  uint32_t class_mask,
                  unsigned int *count);

Parameters

i915

i915 drm file descriptor

  

gt_mask

gt mask

  

class_mask

engine class mask

  

out

returned engine count

  

Returns

the list of all physical engines belonging to the gt. Caller must free memory after use

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_properties_configure ()

void
gem_engine_properties_configure (int fd,
                                 struct gem_engine_properties *params);

gem_engine_properties_restore ()

void
gem_engine_properties_restore (int fd,
                               const struct gem_engine_properties *saved);

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);

gem_engine_has_capability ()

bool
gem_engine_has_capability (int i915,
                           const char *engine,
                           const char *cap);

gem_engine_has_known_capability ()

bool
gem_engine_has_known_capability (int i915,
                                 const char *engine,
                                 const char *cap);

gem_engine_can_block_copy ()

bool
gem_engine_can_block_copy (int i915,
                           const struct intel_execution_engine2 *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

  

struct gem_engine_properties

struct gem_engine_properties {
	struct intel_execution_engine2 engine;
	int preempt_timeout;
	int heartbeat_interval;
};
Generated by GTK-Doc V1.29