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

## Functions

uint32_t | gem_context_create ()
void | gem_context_destroy ()
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 ()

## Types and Values

#define | LOCAL_I915_CONTEXT_MAX_USER_PRIORITY
#define | LOCAL_I915_CONTEXT_DEFAULT_PRIORITY
#define | LOCAL_I915_CONTEXT_MIN_USER_PRIORITY

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

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