## aux aux — Auxiliary libraries and support functions |

## Functions

#define | gettid
void | igt_fork_signal_helper ()
void | igt_stop_signal_helper ()
void | igt_suspend_signal_helper ()
void | igt_resume_signal_helper ()
void | igt_fork_shrink_helper ()
void | igt_stop_shrink_helper ()
void | igt_fork_hang_detector ()
void | igt_stop_hang_detector ()
#define | igt_while_interruptible()
#define | igt_until_timeout()
#define | igt_for_milliseconds()
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_set_autoresume_delay ()
int | igt_get_autoresume_delay ()
void | igt_drop_root ()
void | igt_debug_wait_for_keypress ()
void | igt_debug_manual_check ()
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 ()
void | intel_require_files ()
#define | min()
#define | max()
#define | igt_swap()
void | igt_lock_mem ()
void | igt_unlock_mem ()
#define | igt_wait()
void | igt_start_siglatency ()
double | igt_stop_siglatency ()
void | igt_set_module_param ()
void | igt_set_module_param_int ()
int | igt_terminate_process ()
void | igt_lsof ()
#define | IGT_LIST()
#define | container_of()
#define | igt_list_first_entry()
#define | igt_list_last_entry()
#define | igt_list_next_entry()
#define | igt_list_prev_entry()
#define | igt_list_for_each()
#define | igt_list_for_each_reverse()
#define | igt_list_for_each_safe()

## Types and Values

extern drm_intel_bo ** | trash_bos
extern int | num_trash_bos
#define | MSEC_PER_SEC
#define | USEC_PER_SEC
#define | NSEC_PER_SEC
#define | sigev_notify_thread_id
struct | _igt_sigiter
enum | igt_suspend_state
enum | igt_suspend_test
#define | CHECK_RAM
#define | CHECK_SWAP
struct | igt_list
struct | igt_mean

## Includes

    #include <igt.h>

## Description

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

## Functions

### gettid

    #define gettid() syscall(__NR_gettid)

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

Note that this just spews signals at the current process unconditionally and hence incurs quite a bit of overhead. For a more focused approach, with less overhead, look at the igt_while_interruptible code block macro.

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

    void
    igt_suspend_signal_helper (void);

Suspends the child process spawned with `igt_fork_signal_helper()`. This should be called before a critical section of code that has difficulty to make progress if interrupted frequently, like the `clone()` syscall called from a largish executable. `igt_resume_signal_helper()` must be called after the critical section to restart interruptions for the test.

### igt_resume_signal_helper ()

    void
    igt_resume_signal_helper (void);

Resumes the child process spawned with `igt_fork_signal_helper()`.

This should be paired with `igt_suspend_signal_helper()` and called after the problematic code sensitive to signals.

### igt_fork_shrink_helper ()

    void
    igt_fork_shrink_helper (int fd);

Fork a child process using igt_fork_helper to force all available objects to be paged out (via `i915_gem_shrink()`).

This is useful to exercise swapping paths, without requiring us to hit swap.

This should only be used from an igt_fixture.

### igt_stop_shrink_helper ()

    void
    igt_stop_shrink_helper (void);

Stops the child process spawned with `igt_fork_shrink_helper()`.

### igt_fork_hang_detector ()

    void
    igt_fork_hang_detector (int fd);

### igt_stop_hang_detector ()

    void
    igt_stop_hang_detector (void);

### igt_while_interruptible()

    #define             igt_while_interruptible(enable)

Provides control flow such that all `drmIoctl()` (strictly `igt_ioctl()`) within the loop are forcibly injected with signals (SIGRTMIN).

This is useful to exercise ioctl error paths, at least where those can be exercises by interrupting blocking waits, like stalling for the gpu.

The code block attached to this macro is run in a loop with doubling the interrupt timeout on each ioctl for every run, until no ioctl gets interrupted any more. The starting timeout is taken to be the signal delivery latency, measured at runtime. This way the any ioctls called from this code block should be exhaustively tested for all signal interruption paths.

Note that since this overloads the `igt_ioctl()`, this method is not useful for widespread signal injection, for example providing coverage of pagefaults. To interrupt everything, see `igt_fork_signal_helper()`.

#### Parameters

enable | enable igt_ioctl interrupting or not |

### igt_until_timeout()

    #define             igt_until_timeout(timeout)

Convenience macro loop to run the provided code block in a loop until the timeout has expired. Of course when an individual execution takes too long, the actual execution time could be a lot longer.

The code block will be executed at least once.

#### Parameters

timeout | timeout in seconds |

### igt_for_milliseconds()

    #define             igt_for_milliseconds(t)

Convenience macro loop to run the provided code block in a loop until the target interval has expired. Of course when an individual execution takes too long, the actual execution time could be a lot longer.

The code block will be executed at least once.

#### Parameters

time | how long to run the loop in milliseconds |

### 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 log files 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 (enum igt_suspend_state state,
                                   enum igt_suspend_test test);

Execute a system suspend cycle targeting the given `state` optionally completing the cycle at the given `test` point and automaically wake up again. Waking up is either achieved using the RTC wake-up alarm for a full suspend cycle or a kernel timer for a suspend test cycle. The kernel timer delay for a test cycle can be configured by the suspend.pm_test_delay kernel parameter (5 sec by default).

SUSPEND_TEST_NONE specifies a full suspend cycle. The SUSPEND_TEST_FREEZER..SUSPEND_TEST_CORE test points can make it possible to collect error logs in case a full suspend cycle would prevent this by hanging the machine, or they can provide an idea of the faulty component by comparing fail/no-fail results at different test points.

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

#### Parameters

state | an igt_suspend_state, the target suspend state |
test | an igt_suspend_test, test point at which to complete the suspend cycle |

### igt_set_autoresume_delay ()

    void
    igt_set_autoresume_delay (int delay_secs);

Sets how long we wait to resume the system after suspending it, using the suspend.pm_test_delay variable. On exit, the original delay value is restored.

#### Parameters

delay_secs | The delay in seconds before resuming the system |

### igt_get_autoresume_delay ()

    int
    igt_get_autoresume_delay (enum igt_suspend_state state);

Retrieves how long we wait to resume the system after suspending it. This can either be set through igt_set_autoresume_delay or be a default value that depends on the suspend state.

#### Parameters

state | an igt_suspend_state, the target suspend state |

#### Returns

The autoresume delay, in seconds.

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

Waits for a key press when run interactively and when the corresponding debug var is set in the --interactive-debug=$var variable. Multiple keys can be specified as a comma-separated list or alternatively "all" if a wait should happen for all cases.

When not connected to a terminal interactive_debug 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

var | var lookup to to enable this wait |

### igt_debug_manual_check ()

    void
    igt_debug_manual_check (const char *var,
                            const char *expected);

Waits for a key press when run interactively and when the corresponding debug var is set in the --interactive-debug=$var variable. Multiple vars can be specified as a comma-separated list or alternatively "all" if a wait should happen for all cases.

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.

When not connected to a terminal interactive_debug is ignored and execution immediately continues. For this reason by default this function returns true. It returns false only when N/n is pressed indicating the user isn't seeing what was expected.

Force test fail when N/n is pressed.

#### Parameters

var | var lookup to to enable this wait |
expected | message to be printed as expected behaviour before wait for keys Y/n |

### intel_purge_vm_caches ()

    void
    intel_purge_vm_caches (int fd);

### 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 (uint64_t count,
                          uint64_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 fulfilled. 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 bit field declaring whether the test will be run in RAM or in SWAP |

### intel_require_files ()

    void
    intel_require_files (uint64_t count);

Does the system support enough file descriptors for the test?

#### Parameters

count | number of files that will be created |

### min()

    #define             min(a, b)

### max()

    #define             max(a, b)

### igt_swap()

    #define             igt_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.

### igt_wait()

    #define             igt_wait(COND, timeout_ms, interval_ms)

Waits until COND evaluates to true or the timeout passes.

It is safe to call this macro if the signal helper is active. The only problem is that the `usleep()` calls will return early, making us evaluate COND too often, possibly eating valuable CPU cycles.

#### Parameters

COND | condition to wait |
timeout_ms | timeout in milliseconds |
interval_ms | amount of time we try to sleep between COND checks |

#### Returns

True of COND evaluated to true, false otherwise.

### igt_start_siglatency ()

    void
    igt_start_siglatency (int sig);

### igt_stop_siglatency ()

    double
    igt_stop_siglatency (struct igt_mean *result);

### igt_set_module_param ()

    void
    igt_set_module_param (const char *name,
                          const char *val);

This function sets the desired value for the given i915.ko parameter. It also takes care of saving and restoring the values that were already set before the test was run.

Please consider using `igt_set_module_param_int()` for the integer and bool parameters.

#### Parameters

name | i915.ko parameter name |
val | i915.ko parameter value |

### igt_set_module_param_int ()

    void
    igt_set_module_param_int (const char *name,
                              int val);

This is a wrapper for `igt_set_module_param()` that takes an integer instead of a string. Please see `igt_set_module_param()`.

#### Parameters

name | i915.ko parameter name |
val | i915.ko parameter value |

### igt_terminate_process ()

    int
    igt_terminate_process (int sig,
                           const char *comm);

#### Parameters

sig | Signal to send |
comm | Name of process in the form found in /proc/pid/comm (limited to 15 chars) |

#### Returns

0 in case the process is not found running or the signal has been sent successfully or -errno otherwise.

This function sends the signal `sig` for a process found in process table with name `comm` .

### igt_lsof ()

    void
    igt_lsof (const char *dpath);

### IGT_LIST()

    #define IGT_LIST(name) struct igt_list name = __IGT_INIT_LIST(name)

### container_of()

    #define             container_of(ptr, sample, member)

### igt_list_first_entry()

    #define             igt_list_first_entry(head, pos, member)

### igt_list_last_entry()

    #define             igt_list_last_entry(head, pos, member)

### igt_list_next_entry()

    #define             igt_list_next_entry(pos, member)

### igt_list_prev_entry()

    #define             igt_list_prev_entry(pos, member)

### igt_list_for_each()

    #define             igt_list_for_each(pos, head, member)

### igt_list_for_each_reverse()

    #define             igt_list_for_each_reverse(pos, head, member)

### igt_list_for_each_safe()

    #define             igt_list_for_each_safe(pos, tmp, head, member)

## Types and Values

### trash_bos

    extern drm_intel_bo **trash_bos;

### num_trash_bos

    extern int num_trash_bos;

### MSEC_PER_SEC

    #define MSEC_PER_SEC (1000)

### USEC_PER_SEC

    #define USEC_PER_SEC (1000*MSEC_PER_SEC)

### NSEC_PER_SEC

    #define NSEC_PER_SEC (1000*USEC_PER_SEC)

### sigev_notify_thread_id

    #define sigev_notify_thread_id _sigev_un._tid

### struct _igt_sigiter

    struct _igt_sigiter {
    	unsigned pass;
    };

### enum igt_suspend_state

Target suspend states used with `igt_system_suspend_autoresume()`. See /sys/power/state for the available states on a given machine.

#### Members

SUSPEND_STATE_FREEZE | suspend-to-idle target state, aka S0ix or freeze, first non-hibernation state |
SUSPEND_STATE_STANDBY | standby target state, aka S1, second non-hibernation state |
SUSPEND_STATE_MEM | suspend-to-mem target state aka S3, third non-hibernation state |
SUSPEND_STATE_DISK | suspend-to-disk target state, aka S4 or hibernation |

### enum igt_suspend_test

Test points used with `igt_system_suspend_autoresume()`. Specifies if and where the suspend sequence is to be terminated.

#### Members

SUSPEND_TEST_NONE | no testing, perform a full suspend/resume cycle |
SUSPEND_TEST_FREEZER | complete cycle after freezing all freezable threads |
SUSPEND_TEST_DEVICES | complete cycle after the above step and suspending devices (before calling the drivers' suspend late and no_irq hooks). Platform and system devices are not suspended here, see SUSPEND_TEST_CORE. |
SUSPEND_TEST_PLATFORM | complete cycle after all the above steps and calling the ACPI platform global control methods (applies only with /sys/power/disk set to platform) |
SUSPEND_TEST_PROCESSORS | complete cycle after all the above steps and disabling non-boot CPUs |
SUSPEND_TEST_CORE | complete cycle after all the above steps and suspending platform and system devices |

### CHECK_RAM

    #define CHECK_RAM 0x1

### CHECK_SWAP

    #define CHECK_SWAP 0x2

### struct igt_list

    struct igt_list {
    	struct igt_list *prev;
    	struct igt_list *next;
    };

### struct igt_mean

    struct igt_mean {
    };

Structure to compute running statistical numbers. Needs to be initialized with `igt_mean_init()`. Read out data using `igt_mean_get()` and `igt_mean_get_variance()`.