intel-gpu-tools Reference Manual: i-g-t aux

## i-g-t aux i-g-t aux — Auxiliary libraries and support functions |

## Functions

void | igt_fork_signal_helper ()
void | igt_stop_signal_helper ()
void | igt_exchange_int ()
void | igt_permute_array ()
void | igt_progress ()
void | igt_print_activity ()
bool | igt_check_boolean_env_var ()
bool | igt_aub_dump_enabled ()
void | igt_init_aperture_trashers ()
void | igt_trash_aperture ()
void | igt_cleanup_aperture_trashers ()
void | igt_system_suspend_autoresume ()
void | igt_drop_root ()
void | igt_debug_wait_for_keypress ()
bool | igt_setup_runtime_pm ()
enum igt_runtime_pm_status | igt_get_runtime_pm_status ()
bool | igt_wait_for_pm_status ()
void | intel_purge_vm_caches ()
uint64_t | intel_get_avail_ram_mb ()
uint64_t | intel_get_total_ram_mb ()
uint64_t | intel_get_total_swap_mb ()
void | intel_require_memory ()
#define | min()
#define | max()
#define | swap()
void | igt_lock_mem ()
void | igt_unlock_mem ()

## Types and Values

extern drm_intel_bo ** | trash_bos
extern int | num_trash_bos
enum | igt_runtime_pm_status
#define | CHECK_RAM
#define | CHECK_SWAP

## Includes

    #include <igt_aux.h>

## Description

This library provides various auxiliary helper functions that don't really fit into any other topic.

## Functions

### igt_fork_signal_helper ()

    void
    igt_fork_signal_helper (void);

Fork a child process using igt_fork_helper to interrupt the parent process with a SIGUSR1 signal at regular quick intervals. The corresponding dummy signal handler is installed in the parent process.

This is useful to exercise ioctl error paths, at least where those can be exercises by interrupting blocking waits, like stalling for the gpu. This helper can also be used from children spawned with igt_fork.

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

### igt_stop_signal_helper ()

    void
    igt_stop_signal_helper (void);

Stops the child process spawned with `igt_fork_signal_helper()` again.

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

### igt_exchange_int ()

    void
    igt_exchange_int (void *array,
                      unsigned  i,
                      unsigned  j);

Exchanges the two values at array indices `i` and `j` . Useful as an exchange function for `igt_permute_array()`.

#### Parameters

array | pointer to the array of integers |
i | first position |
j | second position |

### igt_permute_array ()

    void
    igt_permute_array (void *array,
                       unsigned  size,
                       void (*exchange_func) (void *array, unsigned i, unsigned j));

This function randomly permutes the array using `random()` as the PRNG source. The `exchange_func` function is called to exchange two elements in the array when needed.

#### Parameters

array | pointer to array |
size | size of the array |
exchange_func | function to exchange array elements |

### igt_progress ()

    void
    igt_progress (const char *header,
                  uint64_t i,
                  uint64_t total);

This function draws a progress indicator, which is useful for running long-winded tests manually on the console. To avoid spamming logfiles in automated runs the progress indicator is suppressed when not running on a terminal.

#### Parameters

header | header string to prepend to the progress indicator |
i | work processed thus far |
total | total amount of work |

### igt_print_activity ()

    void
    igt_print_activity (void);

Print a '.' to indicate activity. This is printed without a newline and only if output is to a terminal.

### igt_check_boolean_env_var ()

    bool
    igt_check_boolean_env_var (const char *env_var,
                               bool default_value);

This function should be used to parse boolean environment variable options.

#### Parameters

env_var | environment variable name |
default_value | default value for the environment variable |

#### Returns

The boolean value of the environment variable `env_var` as decoded by `atoi()` if it is set and `default_value` if the variable is not set.

### igt_aub_dump_enabled ()

    bool
    igt_aub_dump_enabled (void);

#### Returns

True if AUB dumping is enabled with IGT_DUMP_AUB=1 in the environment, false otherwise.

### igt_init_aperture_trashers ()

    void
    igt_init_aperture_trashers (drm_intel_bufmgr *bufmgr);

Initialize the aperture trasher using `bufmgr` , which can then be run with `igt_trash_aperture()`.

#### Parameters

bufmgr | libdrm buffer manager |

### igt_trash_aperture ()

    void
    igt_trash_aperture (void);

Trash the aperture by walking a set of GTT memory mapped objects.

### igt_cleanup_aperture_trashers ()

    void
    igt_cleanup_aperture_trashers (void);

Clean up all aperture trasher state set up with `igt_init_aperture_trashers()`.

### igt_system_suspend_autoresume ()

    void
    igt_system_suspend_autoresume (void);

Execute a system suspend-to-mem cycle and automatically wake up again using the firmwares resume timer.

This is very handy for implementing any kind of suspend/resume test.

### igt_drop_root ()

    void
    igt_drop_root (void);

Drop root privileges and make sure it actually worked. Useful for tests which need to check security constraints. Note that this should only be called from manually forked processes, since the lack of root privileges will wreak havoc with the automatic cleanup handlers.

### igt_debug_wait_for_keypress ()

    void
    igt_debug_wait_for_keypress (const char *key);

Waits for a key press when run interactively and when the corresponding debug key is set in the IGT_DEBUG_INTERACTIVE environment variable. Multiple keys can be specified as a comma-separated list or alternatively "all" if a wait should happen for all keys. When not connected to a terminal the environment setting is ignored and execution immediately continues.

This is useful for display tests where under certain situation manual inspection of the display is useful. Or when running a testcase in the background.

#### Parameters

key | env var lookup to to enable this wait |

### igt_setup_runtime_pm ()

    bool
    igt_setup_runtime_pm (void);

Sets up the runtime PM helper functions and enables runtime PM. To speed up tests the autosuspend delay is set to 0.

#### Returns

True if runtime pm is available, false otherwise.

### igt_get_runtime_pm_status ()

    enum igt_runtime_pm_status
    igt_get_runtime_pm_status (void);

#### Returns

The current runtime PM status.

### igt_wait_for_pm_status ()

    bool
    igt_wait_for_pm_status (enum igt_runtime_pm_status status);

Waits until for the driver to switch to into the desired runtime PM status, with a 10 second timeout.

Some subtests call this function while the signal helper is active, so we can't assume each `usleep()` call will sleep for 100ms.

#### Parameters

status | desired runtime PM status |

#### Returns

True if the desired runtime PM status was attained, false if the operation timed out.

### intel_purge_vm_caches ()

    void
    intel_purge_vm_caches (void);

### intel_get_avail_ram_mb ()

    uint64_t
    intel_get_avail_ram_mb (void);

#### Returns

The amount of unused system RAM available in MB.

### intel_get_total_ram_mb ()

    uint64_t
    intel_get_total_ram_mb (void);

#### Returns

The total amount of system RAM available in MB.

### intel_get_total_swap_mb ()

    uint64_t
    intel_get_total_swap_mb (void);

#### Returns

The total amount of swap space available in MB.

### intel_require_memory ()

    void
    intel_require_memory (uint32_t count,
                          uint32_t size,
                          unsigned  mode);

Computes the total amount of memory required to allocate `count` surfaces, each of `size` bytes, and includes an estimate for kernel overhead. It then queries the kernel for the available amount of memory on the system (either RAM and/or SWAP depending upon `mode` ) and determines whether there is sufficient to run the test.

Most tests should check that there is enough RAM to hold their working set. The rare swap thrashing tests should check that there is enough RAM + SWAP for their tests. oom-killer tests should only run if this reports that there is not enough RAM + SWAP!

If there is not enough RAM this function calls igt_skip with an appropriate message. It only ever returns if the requirement is fullfilled. This function also causes the test to be skipped automatically on simulation under the assumption that any test that needs to check for memory requirements is a thrashing test unsuitable for slow simulated systems.

#### Parameters

count | number of surfaces that will be created |
size | the size in bytes of each surface |
mode | a bitfield declaring whether the test will be run in RAM or in SWAP |

### min()

    #define min(a, b) ((a) < (b) ? (a) : (b))

### max()

    #define max(a, b) ((a) > (b) ? (a) : (b))

### swap()

    #define             swap(a, b)

### igt_lock_mem ()

    void
    igt_lock_mem (size_t size);

Allocate `size` MB of memory and lock it into RAM. This releases any previously locked memory.

Use igt_unlock_mem to release the currently locked memory.

#### Parameters

size | the amount of memory to lock into RAM, in MB |

### igt_unlock_mem ()

    void
    igt_unlock_mem (void);

Release and free the RAM used by igt_lock_mem.

## Types and Values

### trash_bos

    extern drm_intel_bo **trash_bos;

### num_trash_bos

    extern int num_trash_bos;

### enum igt_runtime_pm_status

#### Members

IGT_RUNTIME_PM_STATUS_ACTIVE |  |
IGT_RUNTIME_PM_STATUS_SUSPENDED |  |
IGT_RUNTIME_PM_STATUS_SUSPENDING |  |
IGT_RUNTIME_PM_STATUS_RESUMING |  |
IGT_RUNTIME_PM_STATUS_UNKNOWN |  |

### CHECK_RAM

    #define CHECK_RAM 0x1

### CHECK_SWAP

    #define CHECK_SWAP 0x2