GEM Engine Topology: igt-gpu-tools Reference Manual

## 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 ()
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_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 {
    	const struct intel_execution_engine2 *engine;
    	int preempt_timeout;
    	int heartbeat_interval;
    };