GEM Context: igt-gpu-tools Reference Manual

## GEM Context GEM Context — Helpers for dealing with contexts |

## Functions

uint32_t | gem_context_create ()
uint32_t | gem_context_create_ext ()
void | gem_context_destroy ()
uint32_t | gem_context_create_for_engine ()
uint32_t | gem_context_create_for_class ()
bool | gem_contexts_has_shared_gtt ()
bool | gem_has_queues ()
bool | gem_has_contexts ()
void | gem_require_contexts ()
bool | gem_context_has_single_timeline ()
void | gem_context_require_bannable ()
void | gem_context_require_param ()
void | gem_context_get_param ()
void | gem_context_set_param ()
void | gem_context_set_priority ()
bool | gem_context_has_persistence ()
void | gem_context_set_persistence ()
bool | gem_context_has_engine ()

## Types and Values

struct | drm_i915_gem_context_param

## 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_create_ext ()

    uint32_t
    gem_context_create_ext (int fd,
                            uint32_t flags,
                            uint64_t extensions);

Creates a new GEM context with flags and extensions. If no flags or extensions are required, it's the same as gem_context_create and works on older kernels.

#### Parameters

fd | open i915 drm file descriptor |
flags | context create flags |
extensions | first extension struct, or 0 for no extensions |

#### 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_create_for_engine ()

    uint32_t
    gem_context_create_for_engine (int fd,
                                   unsigned int class,
                                   unsigned int inst);

### gem_context_create_for_class ()

    uint32_t
    gem_context_create_for_class (int i915,
                                  unsigned int class,
                                  unsigned int *count);

### 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_has_single_timeline ()

    bool
    gem_context_has_single_timeline (int i915);

### 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_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_has_persistence ()

    bool
    gem_context_has_persistence (int i915);

### 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

### struct drm_i915_gem_context_param

    struct drm_i915_gem_context_param;