Intel Context Wrapper: igt-gpu-tools Reference Manual

## Intel Context Wrapper Intel Context Wrapper — Wrapper structs for dealing with contexts |

## Functions

intel_ctx_cfg_t | intel_ctx_cfg_for_engine ()
intel_ctx_cfg_t | intel_ctx_cfg_all_physical ()
int | intel_ctx_cfg_engine_class ()
const intel_ctx_t * | intel_ctx_create ()
const intel_ctx_t * | intel_ctx_0 ()
const intel_ctx_t * | intel_ctx_create_for_engine ()
const intel_ctx_t * | intel_ctx_create_all_physical ()
void | intel_ctx_destroy ()
unsigned int | intel_ctx_engine_class ()

## Types and Values

#define | GEM_MAX_ENGINES
| intel_ctx_cfg_t
| intel_ctx_t

## Description

This helper library contains a couple of wrapper structs for easier dealing with GEM contexts. This includes a context configuration struct which represents important context construction parameters and a context struct which contains the context ID and its configuration. This makes it easier to pass around a context without losing the context create information.

## Functions

### intel_ctx_cfg_for_engine ()

    intel_ctx_cfg_t
    intel_ctx_cfg_for_engine (unsigned int class,
                              unsigned int inst);

Returns an intel_ctx_cfg_t containing exactly one engine.

#### Parameters

class | engine class |
inst | engine instance |

### intel_ctx_cfg_all_physical ()

    intel_ctx_cfg_t
    intel_ctx_cfg_all_physical (int fd);

Returns an intel_ctx_cfg_t containing all physical engines. On kernels without the engines API, a default context configuration will be returned.

#### Parameters

fd | open i915 drm file descriptor |

### intel_ctx_cfg_engine_class ()

    int
    intel_ctx_cfg_engine_class (const intel_ctx_cfg_t *cfg,
                                unsigned int engine);

Returns the class for the given engine.

#### Parameters

cfg | an intel_ctx_cfg_t |
engine | an engine specifier |

### intel_ctx_create ()

    const intel_ctx_t *
    intel_ctx_create (int i915,
                      const intel_ctx_cfg_t *cfg);

Creates a new intel_ctx_t with the given config. If `cfg` is NULL, a default context is created.

#### Parameters

fd | open i915 drm file descriptor |
cfg | configuration for the created context |

### intel_ctx_0 ()

    const intel_ctx_t *
    intel_ctx_0 (int fd);

Returns an intel_ctx_t representing the default context.

#### Parameters

fd | open i915 drm file descriptor |

### intel_ctx_create_for_engine ()

    const intel_ctx_t *
    intel_ctx_create_for_engine (int fd,
                                 unsigned int class,
                                 unsigned int inst);

Returns an intel_ctx_t containing the specified engine.

#### Parameters

fd | open i915 drm file descriptor |
class | engine class |
inst | engine instance |

### intel_ctx_create_all_physical ()

    const intel_ctx_t *
    intel_ctx_create_all_physical (int fd);

Creates an intel_ctx_t containing all physical engines. On kernels without the engines API, the created context will be the same as `intel_ctx_0()` except that it will be a new GEM context. On kernels or hardware which do not support contexts, it is the same as `intel_ctx_0()`.

#### Parameters

fd | open i915 drm file descriptor |

### intel_ctx_destroy ()

    void
    intel_ctx_destroy (int fd,
                       const intel_ctx_t *ctx);

Destroys an intel_ctx_t.

#### Parameters

fd | open i915 drm file descriptor |
ctx | context to destroy, or NULL |

### intel_ctx_engine_class ()

    unsigned int
    intel_ctx_engine_class (const intel_ctx_t *ctx,
                            unsigned int engine);

Returns the class for the given engine.

#### Parameters

ctx | an intel_ctx_t |
engine | an engine specifier |

## Types and Values

### GEM_MAX_ENGINES

    #define GEM_MAX_ENGINES		I915_EXEC_RING_MASK + 1

### intel_ctx_cfg_t

    typedef struct {
    	uint32_t flags;
    	uint32_t vm;
    	bool nopersist;
    	bool load_balance;
    	bool parallel;
    	unsigned int num_engines;
    	unsigned int width;
    	struct i915_engine_class_instance engines[GEM_MAX_ENGINES];
    } intel_ctx_cfg_t;

Represents the full configuration of an intel_ctx.

`num_engines` not only specifies the number of engines in the context but also how engine information should be communicated to execbuf. With the engines API, every context has two modes:

- In legacy mode (indicated by `num_engines` == 0), the context has a fixed set of engines. The engine to use is specified to execbuf via an I915_EXEC_* flag such as I915_EXEC_RENDER or I915_EXEC_BLT. This is the default behavior of a GEM context if CONTEXT_PARAM_ENGINES is never set.

- In modern mode (indicated by `num_engines` > 0), the set of engines is provided by userspace via CONTEXT_PARAM_ENGINES. Userspace provides an array of i915_engine_class_instance which are class + instance pairs. When calling execbuf in this mode, the engine to use is specified by passing an integer engine index into that array of engines as part of the flags parameter. (Because of the layout of the flags, the maximum possible index value is 63.)

#### Members

uint32_t `flags`; | Context create flags |
uint32_t `vm`; | VM to inherit or 0 for using a per-context VM |
bool `nopersist`; | set I915_CONTEXT_PARAM_PERSISTENCE to 0 |
bool `load_balance`; | True if the first engine should be a load balancing engine |
bool `parallel`; |  |
unsigned int `num_engines`; | Number of client-specified engines or 0 for legacy mode |
unsigned int `width`; |  |
struct i915_engine_class_instance `engines`[GEM_MAX_ENGINES]; | Client-specified engines |

### intel_ctx_t

    typedef struct {
    	uint32_t id;
    	intel_ctx_cfg_t cfg;
    } intel_ctx_t;

Represents the full configuration of an intel_ctx.

#### Members

uint32_t `id`; | the context id/handle |
intel_ctx_cfg_t `cfg`; | the config used to create this context |