GT

GT — GT support library

Functions

Types and Values

Includes

#include <igt.h>

Description

This library provides various auxiliary helper functions to handle general interactions with the GT like forcewake handling, injecting hangs or stopping engines.

Functions

igt_require_hang_ring ()

void
igt_require_hang_ring (int fd,
                       int ring);

Convenience helper to check whether advanced hang injection is supported by the kernel. Uses igt_skip to automatically skip the test/subtest if this isn't the case.

Note that we can't simply just call this from igt_hang_ring since some tests want to exercise gpu wedging behavior. For which we intentionally disable gpu reset support, but still want to inject a hang, see for example tests/gem_eio.c Instead, we expect that the first invocation of igt_require_hand_ring be from a vanilla context and use the has_gpu_reset() determined then for all later instances. This allows us the convenience of double checking when injecting hangs, whilst pushing the complexity to the tests that are deliberating trying to break the box.

This function is also controlled by the environment variables:

IGT_HANG (boolean) - if false, skip all tests that try to inject a hang. Default: true

IGT_HANG_WITHOUT_RESET (boolean) - if true, allow the hang even if the kernel does not support GPU recovery. The machine will be wedged afterwards (and so require a reboot between testing), but it does allow limited testing to be done under hang injection. Default: false

Parameters

fd

open i915 drm file descriptor

 

ring

execbuf ring flag

 

igt_allow_hang ()

igt_hang_t
igt_allow_hang (int fd,
                unsigned  ctx,
                unsigned  flags);

igt_disallow_hang ()

void
igt_disallow_hang (int fd,
                   igt_hang_t arg);

igt_hang_ctx ()

igt_hang_t
igt_hang_ctx (int fd,
              uint32_t ctx,
              int ring,
              unsigned  flags,
              uint64_t *offset);

igt_hang_ring ()

igt_hang_t
igt_hang_ring (int fd,
               int ring);

This helper function injects a hanging batch into ring . It returns a igt_hang_t structure which must be passed to igt_post_hang_ring() for hang post-processing (after the gpu hang interaction has been tested.

Parameters

fd

open i915 drm file descriptor

 

ring

execbuf ring flag

 

Returns

Structure with helper internal state for igt_post_hang_ring().


igt_post_hang_ring ()

void
igt_post_hang_ring (int fd,
                    igt_hang_t arg);

This function does the necessary post-processing after a gpu hang injected with igt_hang_ring().

Parameters

fd

open i915 drm file descriptor

 

arg

hang state from igt_hang_ring()

 

igt_force_gpu_reset ()

void
igt_force_gpu_reset (int fd);

forces a gpu reset using the i915_wedged debugfs interface. To be used to recover from situations where the hangcheck didn't trigger and/or the gpu is stuck, either because the test manually disabled gpu resets or because the test hit an hangcheck bug


igt_fork_hang_helper ()

void
igt_fork_hang_helper (void);

Fork a child process using igt_fork_helper to hang the default engine of the GPU at regular intervals.

This is useful to exercise slow running code (such as aperture placement) which needs to be robust against a GPU reset.

This function automatically skips when test requirements aren't met using igt_skip().


igt_stop_hang_helper ()

void
igt_stop_hang_helper (void);

Stops the child process spawned with igt_fork_hang_helper().

In tests with subtests this function can be called outside of failure catching code blocks like igt_fixture or igt_subtest.


igt_open_forcewake_handle ()

int
igt_open_forcewake_handle (int fd);

This functions opens the debugfs forcewake file and so prevents the GT from suspending. The reference is automatically dropped when the is closed.

Returns

The file descriptor of the forcewake handle or -1 if that didn't work out.


igt_setup_clflush ()

int
igt_setup_clflush (void);

igt_clflush_range ()

void
igt_clflush_range (void *addr,
                   int size);

intel_detect_and_clear_missed_interrupts ()

unsigned
intel_detect_and_clear_missed_interrupts
                               (int fd);

for_if()

#define for_if(expr__) if (!(expr__)) {} else

for_each_engine()

#define             for_each_engine(fd__, flags__)

for_each_physical_engine()

#define             for_each_physical_engine(fd__, flags__)

gem_ring_is_physical_engine ()

bool
gem_ring_is_physical_engine (int fd,
                             unsigned int ring);

gem_ring_has_physical_engine ()

bool
gem_ring_has_physical_engine (int fd,
                              unsigned int ring);

gem_can_store_dword ()

bool
gem_can_store_dword (int fd,
                     unsigned int engine);

gem_class_instance_to_eb_flags ()

unsigned int
gem_class_instance_to_eb_flags (int gem_fd,
                                enum drm_i915_gem_engine_class class,
                                unsigned int instance);

gem_has_engine ()

bool
gem_has_engine (int gem_fd,
                enum drm_i915_gem_engine_class class,
                unsigned int instance);

gem_require_engine ()

void
gem_require_engine (int gem_fd,
                    enum drm_i915_gem_engine_class class);

for_each_engine_class_instance()

#define             for_each_engine_class_instance(fd__, e__)

Types and Values

igt_hang_t

typedef struct {
	unsigned handle;
	unsigned ctx;
	unsigned ban;
	unsigned flags;
} igt_hang_t;

HANG_POISON

#define HANG_POISON 0xc5c5c5c5

HANG_ALLOW_BAN

#define HANG_ALLOW_BAN 1

HANG_ALLOW_CAPTURE

#define HANG_ALLOW_CAPTURE 2

ALL_ENGINES

#define ALL_ENGINES ~0u /* Use in interfaces to iterate all engines */