i-g-t gt

i-g-t gt — GT support library

Functions

Types and Values

Includes

#include <igt_gt.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.

Parameters

fd

open i915 drm file descriptor

 

ring

execbuf ring flag

 

igt_hang_ring ()

struct igt_hang_ring
igt_hang_ring (int fd,
               int ring);

This helper function injects a hanging batch into ring . It returns a igt_hang_ring_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,
                    struct igt_hang_ring 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_fork_hang_helper ()

int
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.

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


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 (void);

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_to_stop_ring_flag ()

enum stop_ring_flags
igt_to_stop_ring_flag (int ring);

This converts the specified ring to a ring flag to be used with igt_get_stop_rings() and igt_set_stop_rings().

Parameters

ring

the specified ring flag from execbuf ioctl (I915_EXEC_*)

 

Returns

Ring flag for the given ring.


igt_set_stop_rings ()

void
igt_set_stop_rings (enum stop_ring_flags flags);

This writes flags to 'i915_ring_stop' debugfs entry. Driver will prevent the CPU from writing tail pointer for the ring that flags specify. Note that the ring is not stopped right away. Instead any further command emissions won't be executed after the flag is set.

This is the least invasive way to make the GPU stuck. Hence you must set this after a batch submission with it's own invalid or endless looping instructions. In this case it is merely for giving notification for the driver that this was simulated hang, as the batch would have caused hang in any case. On the other hand if you use a valid or noop batch and want to hang the ring (GPU), you must set corresponding flag before submitting the batch.

Driver checks periodically if a ring is making any progress, and if it is not, it will declare the ring to be hung and will reset the GPU. After reset, the driver will clear flags in 'i915_ring_stop'

Note: Always when hanging the GPU, use igt_set_stop_rings() to notify the driver. Driver controls hang log messaging based on these flags and thus prevents false positives on logs.

Parameters

flags

Ring flags to write

 

igt_get_stop_rings ()

enum stop_ring_flags
igt_get_stop_rings (void);

Read current ring flags from 'i915_ring_stop' debugfs entry.

Returns

Current ring flags.

Types and Values

igt_hang_ring_t

typedef struct {
	unsigned handle;
	unsigned ban;
} igt_hang_ring_t;

enum stop_ring_flags

Enumeration of all supported flags for igt_set_stop_rings().

Members

STOP_RING_NONE

Can be used to clear the pending stop (warning: hang might be declared already). Returned by igt_get_stop_rings() if there is no currently stopped rings.

 

STOP_RING_RENDER

Render ring

 

STOP_RING_BSD

Video encoding/decoding ring

 

STOP_RING_BLT

Blitter ring

 

STOP_RING_VEBOX

Video enhancement ring

 

STOP_RING_ALL

All rings

 

STOP_RING_ALLOW_ERRORS

Driver will not omit expected DRM_ERRORS

 

STOP_RING_ALLOW_BAN

Driver will use context ban policy

 

STOP_RING_DEFAULTS

STOP_RING_ALL | STOP_RING_ALLOW_ERRORS