GT: igt-gpu-tools Reference Manual

## GT GT — GT support library |

## Functions

void | igt_require_hang_ring ()
igt_hang_t | igt_allow_hang ()
void | igt_disallow_hang ()
igt_hang_t | igt_hang_ctx ()
igt_hang_t | igt_hang_ctx_with_ahnd ()
igt_hang_t | igt_hang_ring ()
igt_hang_t | igt_hang_ring_with_ahnd ()
void | igt_post_hang_ring ()
void | igt_force_gpu_reset ()
void | igt_fork_hang_helper ()
void | igt_stop_hang_helper ()
int | igt_open_forcewake_handle ()
int | igt_setup_clflush ()
void | igt_clflush_range ()
unsigned | intel_detect_and_clear_missed_interrupts ()
bool | gem_can_store_dword ()
bool | gem_class_can_store_dword ()
int | gem_execbuf_flags_to_engine_class ()

## Types and Values

| igt_hang_t
#define | HANG_POISON
#define | HANG_ALLOW_BAN
#define | HANG_ALLOW_CAPTURE
#define | HANG_WANT_ENGINE_RESET
#define | ALL_ENGINES

## 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,
                           uint32_t ctx,
                           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);

### igt_hang_ctx_with_ahnd ()

    igt_hang_t
    igt_hang_ctx_with_ahnd (int fd,
                            uint64_t ahnd,
                            uint32_t ctx,
                            int ring,
                            unsigned  flags);

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

    igt_hang_t
    igt_hang_ring_with_ahnd (int fd,
                             int ring,
                             uint64_t ahnd);

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

### gem_can_store_dword ()

    bool
    gem_can_store_dword (int fd,
                         unsigned int engine);

### gem_class_can_store_dword ()

    bool
    gem_class_can_store_dword (int fd,
                               int class);

### gem_execbuf_flags_to_engine_class ()

    int
    gem_execbuf_flags_to_engine_class (unsigned int flags);

## Types and Values

### igt_hang_t

    typedef struct {
    	igt_spin_t *spin;
    	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

### HANG_WANT_ENGINE_RESET

    #define HANG_WANT_ENGINE_RESET 4

### ALL_ENGINES

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