GEM Context

GEM Context — Helpers for dealing with contexts

Functions

Types and Values

Description

This helper library contains functions used for handling gem contexts. Conceptually, gem contexts are similar to their CPU counterparts, in that they are a mix of software and hardware features allowing to isolate some aspects of task execution. Initially it was just a matter of maintaining separate state for each context, but more features were added, some improving contexts isolation (per-context address space), some are just software features improving submission model (context priority).

Functions

gem_context_create ()

uint32_t
gem_context_create (int fd);

This wraps the CONTEXT_CREATE ioctl, which is used to allocate a new context. Note that similarly to gem_set_caching() this wrapper skips on kernels and platforms where context support is not available.

Parameters

fd

open i915 drm file descriptor

 

Returns

The id of the allocated context.


gem_context_destroy ()

void
gem_context_destroy (int fd,
                     uint32_t ctx_id);

This wraps the CONTEXT_DESTROY ioctl, which is used to free a context.

Parameters

fd

open i915 drm file descriptor

 

ctx_id

i915 context id

 

gem_context_clone ()

uint32_t
gem_context_clone (int i915,
                   uint32_t src,
                   unsigned int share,
                   unsigned int flags);

gem_context_clone_with_engines ()

uint32_t
gem_context_clone_with_engines (int i915,
                                uint32_t src);

Special purpose wrapper to create a new context by cloning engines from src .

In can be called regardless of whether the kernel supports context cloning.

Intended purpose is to use for creating contexts against which work will be submitted and the engine index came from external source, derived from a default context potentially configured with an engine map.

Parameters

i915

open i915 drm file descriptor

 

src

i915 context id

 

gem_context_copy_engines ()

void
gem_context_copy_engines (int src_fd,
                          uint32_t src,
                          int dst_fd,
                          uint32_t dst);

Special purpose helper for copying engine map from one context to another.

In can be called regardless of whether the kernel supports context engine maps and is a no-op if not supported.

Parameters

src_fd

open i915 drm file descriptor where src context belongs to

 

src

source engine map context id

 

dst_fd

open i915 drm file descriptor where dst context belongs to

 

dst

destination engine map context id

 

gem_queue_create ()

uint32_t
gem_queue_create (int i915);

gem_queue_clone_with_engines ()

uint32_t
gem_queue_clone_with_engines (int i915,
                              uint32_t src);

See gem_context_clone_with_engines.

Parameters

i915

open i915 drm file descriptor

 

src

i915 context id

 

gem_contexts_has_shared_gtt ()

bool
gem_contexts_has_shared_gtt (int i915);

gem_has_queues ()

bool
gem_has_queues (int i915);

gem_has_contexts ()

bool
gem_has_contexts (int fd);

Queries whether context creation is supported or not.

Parameters

fd

open i915 drm file descriptor

 

Returns

Context creation availability.


gem_require_contexts ()

void
gem_require_contexts (int fd);

This helper will automatically skip the test on platforms where context support is not available.

Parameters

fd

open i915 drm file descriptor

 

gem_context_require_bannable ()

void
gem_context_require_bannable (int fd);

gem_context_require_param ()

void
gem_context_require_param (int fd,
                           uint64_t param);

Feature test macro to query whether context parameter support for param is available. Automatically skips through igt_require() if not.

Parameters

fd

open i915 drm file descriptor

 

param

i915 context parameter

 

gem_has_context_clone ()

bool
gem_has_context_clone (int i915);

gem_context_get_param ()

void
gem_context_get_param (int fd,
                       struct drm_i915_gem_context_param *p);

This wraps the CONTEXT_GET_PARAM ioctl, which is used to get a context parameter.

Parameters

fd

open i915 drm file descriptor

 

p

i915 context parameter

 

gem_context_set_param ()

void
gem_context_set_param (int fd,
                       struct drm_i915_gem_context_param *p);

This wraps the CONTEXT_SET_PARAM ioctl, which is used to set a context parameter.

Parameters

fd

open i915 drm file descriptor

 

p

i915 context parameter

 

gem_context_set_priority ()

void
gem_context_set_priority (int fd,
                          uint32_t ctx,
                          int prio);

Like __gem_context_set_priority(), except we assert on failure.

Parameters

fd

open i915 drm file descriptor

 

ctx_id

i915 context id

 

prio

desired context priority

 

gem_context_set_persistence ()

void
gem_context_set_persistence (int i915,
                             uint32_t ctx,
                             bool state);

gem_context_has_engine ()

bool
gem_context_has_engine (int fd,
                        uint32_t ctx,
                        uint64_t engine);

Types and Values

LOCAL_I915_CONTEXT_MAX_USER_PRIORITY

#define LOCAL_I915_CONTEXT_MAX_USER_PRIORITY 1023

LOCAL_I915_CONTEXT_DEFAULT_PRIORITY

#define LOCAL_I915_CONTEXT_DEFAULT_PRIORITY 0

LOCAL_I915_CONTEXT_MIN_USER_PRIORITY

#define LOCAL_I915_CONTEXT_MIN_USER_PRIORITY -1023

struct drm_i915_gem_context_param

struct drm_i915_gem_context_param;