gettid

#define             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().

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.

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.

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

igt_exchange_int64 ()

void
igt_exchange_int64 (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().

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.

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.

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.

igt_aub_dump_enabled ()

bool
igt_aub_dump_enabled (void);

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.

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.

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.

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. Calling this function with "all" will assert.

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.

igt_debug_interactive_mode_check ()

void
igt_debug_interactive_mode_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.

min()

#define min(x, y) __careful_cmp(x, y, <, min)

max()

#define max(x, y) __careful_cmp(x, y, >, max)

clamp()

#define clamp(val, lo, hi) min(max(val, lo), hi)

min_t()

#define min_t(t, x, y) __careful_cmp((typeof(t))x, (typeof(t))y, <, min_t)

max_t()

#define max_t(t, x, y) __careful_cmp((typeof(t))x, (typeof(t))y, >, max_t)

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.

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.

igt_start_siglatency ()

void
igt_start_siglatency (int sig);

igt_stop_siglatency ()

double
igt_stop_siglatency (struct igt_mean *result);

igt_allow_unlimited_files ()

bool
igt_allow_unlimited_files (void);

igt_is_process_running ()

int
igt_is_process_running (const char *comm);

igt_terminate_process ()

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

igt_lsof ()

void
igt_lsof (const char *dpath);

igt_lsof_kill_audio_processes ()

int
igt_lsof_kill_audio_processes (void);

pipewire_pulse_start_reserve ()

int
pipewire_pulse_start_reserve (void);

pipewire_pulse_stop_reserve ()

void
pipewire_pulse_stop_reserve (void);

igt_hweight()

#define             igt_hweight(x)

is_power_of_two()

#define is_power_of_two(x)  (((x) & ((x)-1)) == 0)

igt_fls()

#define             igt_fls(x)

roundup_power_of_two()

#define roundup_power_of_two(x) ((x) != 0 ? 1ULL << igt_fls((x) - 1) : 0)

DIV_ROUND_UP()

#define DIV_ROUND_UP(n, d) (((n) + (d) - 1) / (d))

DIV_ROUND_CLOSEST()

#define DIV_ROUND_CLOSEST(n, d) (((n) + (d) / 2) / (d))

igt_rol()

#define             igt_rol(value, shift, size)

igt_ror()

#define             igt_ror(value, shift, size)

vfs_file_max ()

uint64_t
vfs_file_max (void);

igt_memdup ()

void *
igt_memdup (const void *ptr,
            size_t len);

igt_wait_and_close ()

void
igt_wait_and_close (int fence_fd);

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.

enum igt_suspend_test

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

enum igt_mem_sleep

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