Core

Core — Core i-g-t testing support

Functions

#define BUILD_BUG_ON_INVALID()
#define igt_assume()
struct _GKeyFile * igt_load_igtrc ()
#define IGT_TEST_DESCRIPTION()
#define igt_fixture
int (*igt_opt_handler_t) ()
int igt_subtest_init_parse_opts ()
#define igt_subtest_init()
#define igt_tokencat()
#define igt_unique()
#define igt_subtest()
#define igt_subtest_f()
#define igt_subtest_with_dynamic()
#define igt_subtest_with_dynamic_f()
#define igt_dynamic()
#define igt_dynamic_f()
const char * igt_subtest_name ()
bool igt_only_list_subtests ()
#define igt_main_args()
const char * igt_test_name ()
void igt_simple_init_parse_opts ()
#define igt_simple_init()
#define igt_simple_main_args()
void igt_skip ()
#define igt_skip_check()
void igt_success ()
bool igt_can_fail ()
void igt_describe_f ()
#define igt_describe()
#define igt_assert()
#define igt_assert_f()
#define igt_fail_on()
#define igt_fail_on_f()
#define igt_assert_cmpint()
#define igt_assert_cmpuint()
#define igt_assert_cmps64()
#define igt_assert_cmpu64()
#define igt_assert_cmpdouble()
#define igt_assert_eq()
#define igt_assert_eq_u32()
#define igt_assert_eq_s64()
#define igt_assert_eq_u64()
#define igt_assert_eq_double()
#define igt_assert_neq()
#define igt_assert_neq_u32()
#define igt_assert_neq_u64()
#define igt_assert_neq_double()
#define igt_assert_lte()
#define igt_assert_lte_u32()
#define igt_assert_lte_u64()
#define igt_assert_lte_s64()
#define igt_assert_lt()
#define igt_assert_lt_u32()
#define igt_assert_lt_u64()
#define igt_assert_lt_s64()
#define igt_assert_lt_double()
#define igt_assert_fd()
#define igt_require()
#define igt_skip_on()
#define igt_require_f()
#define igt_require_fd()
#define igt_skip_on_f()
#define igt_abort_on_f()
#define igt_fork()
void igt_waitchildren ()
void igt_waitchildren_timeout ()
void igt_kill_children ()
#define igt_multi_fork()
#define igt_fork_helper()
int igt_wait_helper ()
void igt_stop_helper ()
void (*igt_exit_handler_t) ()
void igt_install_exit_handler ()
bool igt_run_in_simulation ()
#define SLOW_QUICK()
void igt_skip_on_simulation ()
void igt_log ()
void igt_vlog ()
#define igt_debug()
#define igt_info()
#define igt_warn()
#define igt_critical()
bool (*igt_buffer_log_handler_t) ()
void igt_log_buffer_inspect ()
#define igt_warn_on()
#define igt_warn_on_f()
#define igt_debug_on()
#define igt_debug_on_f()
void igt_set_timeout ()
int igt_gettime ()
double igt_time_elapsed ()
uint64_t igt_nsec_elapsed ()
#define igt_fopen_data()
int igt_system ()
int igt_system_quiet ()
#define igt_system_cmd()
void igt_srandom ()
void igt_trace ()
void igt_kmsg ()
return READ_ONCE ()
#define WRITE_ONCE()
#define cpu_to_le32()
#define le32_to_cpu()
#define for_if()
int igt_pci_system_init ()
int igt_pci_system_reinit ()
void igt_pci_system_cleanup ()
void igt_emit_ignore_dmesg_regex ()

Types and Values

#define IGT_LOG_DOMAIN
#define STATIC_ANALYSIS_BUILD
extern char * igt_frame_dump_path
#define IGT_EXIT_SKIP
#define IGT_EXIT_SUCCESS
#define IGT_EXIT_INVALID
#define IGT_EXIT_FAILURE
#define IGT_EXIT_ABORT
extern jmp_buf igt_subtest_jmpbuf
extern jmp_buf igt_dynamic_jmpbuf
#define IGT_OPT_HANDLER_SUCCESS
#define IGT_OPT_HANDLER_ERROR
#define igt_subtest_group
#define igt_main
#define igt_simple_main
#define igt_constructor
struct igt_helper_process
extern const char * igt_interactive_debug
extern bool igt_skip_crc_compare
enum igt_log_level
#define KMSG_EMER
#define KMSG_ALERT
#define KMSG_CRIT
#define KMSG_ERR
#define KMSG_WARNING
#define KMSG_NOTICE
#define KMSG_INFO
#define KMSG_DEBUG
#define MSEC_PER_SEC
#define USEC_PER_SEC
#define USEC_PER_DECISEC
#define NSEC_PER_SEC
#define USEC_PER_MSEC
#define NSEC_PER_MSEC

Includes

#include <igt.h>

Description

This library implements the core of the i-g-t test support infrastructure. Main features are the subtest enumeration, cmdline option parsing helpers for subtest handling and various helpers to structure testcases with subtests and handle subtest test results.

Auxiliary code provides exit handlers, support for forked processes with test result propagation. Other generally useful functionality includes optional structure logging infrastructure and some support code for running reduced test set on in simulated hardware environments.

When writing tests with subtests it is extremely important that nothing interferes with the subtest enumeration. In i-g-t subtests are enumerated at runtime, which allows powerful testcase enumeration. But it makes subtest enumeration a bit more tricky since the test code needs to be careful to never run any code which might fail (like trying to do privileged operations or opening device driver nodes).

To allow this i-g-t provides igt_fixture code blocks for setup code outside of subtests and automatically skips the subtest code blocks themselves. For special cases igt_only_list_subtests() is also provided. For setup code only shared by a group of subtest encapsulate the igt_fixture block and all the subtestest in a igt_subtest_group block.

Magic Control Blocks

i-g-t makes heavy use of C macros which serve as magic control blocks. They work fairly well and transparently but since C doesn't have full-blown closures there are caveats:

  • Asynchronous blocks which are used to spawn children internally use fork(). Which means that nonsensical control flow like jumping out of the control block is possible, but it will badly confuse the i-g-t library code. And of course all caveats of a real fork() call apply, namely that file descriptors are copied, but still point at the original file. This will terminally upset the libdrm buffer manager if both parent and child keep on using the same open instance of the drm device. Usually everything related to interacting with the kernel driver must be reinitialized to avoid such issues.

  • Code blocks with magic control flow are implemented with setjmp() and longjmp(). This applies to igt_fixture, igt_subtest, igt_subtest_with_dynamic and igt_dynamic blocks and all the three variants to finish test: igt_success(), igt_skip() and igt_fail(). Mostly this is of no concern, except when such a control block changes stack variables defined in the same function as the control block resides. Any store/load behaviour after a longjmp() is ill-defined for these variables. Avoid such code.

    Quoting the man page for longjmp():

    "The values of automatic variables are unspecified after a call to longjmp() if they meet all the following criteria:"

    • "they are local to the function that made the corresponding setjmp() call;

    • "their values are changed between the calls to setjmp() and longjmp(); and

    • "they are not declared as volatile."


Best Practices for Test Helper Libraries Design

Kernel tests itself tend to have fairly complex logic already. It is therefore paramount that helper code, both in libraries and test-private functions, add as little boilerplate code to the main test logic as possible. But then dense code is hard to understand without constantly consulting the documentation and implementation of all the helper functions if it doesn't follow some clear patterns. Hence follow these established best practices:

  • Make extensive use of the implicit control flow afforded by igt_skip(), igt_fail and igt_success(). When dealing with optional kernel features combine igt_skip() with igt_fail() to skip when the kernel support isn't available but fail when anything else goes awry. void should be the most common return type in all your functions, except object constructors of course.

  • The main test logic should have no explicit control flow for failure conditions, but instead such assumptions should be written in a declarative style. Use one of the many macros which encapsulate i-g-t's implicit control flow. Pick the most suitable one to have as much debug output as possible without polluting the code unnecessarily. For example igt_assert_cmpint() for comparing integers or do_ioctl() for running ioctls and checking their results. Feel free to add new ones to the library or wrap up a set of checks into a private function to further condense your test logic.

  • When adding a new feature test function which uses igt_skip() internally, use the {prefix}_require_{feature_name} naming scheme. When you instead add a feature test function which returns a boolean, because your main test logic must take different actions depending upon the feature's availability, then instead use the {prefix}_has_{feature_name}.

  • As already mentioned eschew explicit error handling logic as much as possible. If your test absolutely has to handle the error of some function the customary naming pattern is to prefix those variants with __. Try to restrict explicit error handling to leaf functions. For the main test flow simply pass the expected error condition down into your helper code, which results in tidy and declarative test logic.

  • Make your library functions as simple to use as possible. Automatically register cleanup handlers through igt_install_exit_handler(). Reduce the amount of setup boilerplate needed by using implicit singletons and lazy structure initialization and similar design patterns.

  • Don't shy away from refactoring common code, even when there are just 2-3 users and even if it's not a net reduction in code. As long as it helps to remove boilerplate and makes the code more declarative the resulting clearer test flow is worth it. All i-g-t library code has been organically extracted from testcases in this fashion.

  • For general coding style issues please follow the kernel's rules laid out in CodingStyle.


Interface with Testrunners

i-g-t testcase are all executables which should be run as root on an otherwise completely idle system. The test status is reflected in the exitcode. IGT_EXIT_SUCCESS means "success", IGT_EXIT_SKIP "skip", IGT_EXIT_TIMEOUT that some operation "timed out". All other exit codes encode a failed test result, including any abnormal termination of the test (e.g. by SIGKILL).

On top of that tests may report unexpected results and minor issues to stderr. If stderr is non-empty the test result should be treated as "warn".

The list of test executables is generated at build time and stored in tests/test-list.txt. When running tests with subtest from a test runner it is recommend to run each subtest individually, since otherwise the return code will only reflect the overall result.

To do that obtain the lists of subtests with "--list-subtests", which can be run as non-root and doesn't require a DRM driver to be loaded (or any GPU to be present). Then individual subtests can be run with "--run-subtest". Usage help for tests with subtests can be obtained with the "--help" command line option.

A wildcard expression can be given to --run-subtest to specify a subset of subtests to run. See https://tools.ietf.org/html/rfc3977section-4 for a description of allowed wildcard expressions. Some examples of allowed wildcard expressions are:

  • '*basic*' match any subtest containing basic

  • 'basic-???' match any subtest named basic- with 3 characters after -

  • 'basic-[0-9]' match any subtest named basic- with a single number after -

  • 'basic-[^0-9]' match any subtest named basic- with a single non numerical character after -

  • 'basic*,advanced*' match any subtest starting basic or advanced

  • '*,!basic*' match any subtest not starting basic

  • 'basic*,!basic-render*' match any subtest starting basic but not starting basic-render

It is possible to run a shell script at certain points of test execution with "--hook". See the usage description with "--help-hook" for details.


Configuration

Some of IGT's behavior can be configured through a configuration file. By default, this file is expected to exist in ~/.igtrc . The directory for this can be overridden by setting the environment variable IGT_CONFIG_PATH. An example configuration follows:

# The common configuration section follows.
[Common]
FrameDumpPath=/tmp # The path to dump frames that fail comparison checks

# Device selection filter
Device=pci:vendor=8086,card=0;sys:/sys/devices/platform/vgem

# The following section is used for configuring the Device Under Test.
# It is not mandatory and allows overriding default values.
[DUT]
SuspendResumeDelay=10

Some specific configuration options may be used by specific parts of IGT, such as those related to Chamelium support.

Functions

BUILD_BUG_ON_INVALID()

#define BUILD_BUG_ON_INVALID(e) ((void)(sizeof((long)(e))))

A macro that takes an expression and generates no code. Used for checking at build-time that an expression is valid code.

Parameters

expr

Expression

 

igt_assume()

#define igt_assume(e) assert(e)

An assert-like macro to be used for tautologies to give hints to static analysis of code. No-op if STATIC_ANALYSIS_BUILD is not defined, expands to an assert() if it is.

Parameters

expr

Condition to test

 

igt_load_igtrc ()

struct _GKeyFile *
igt_load_igtrc (void);

IGT_TEST_DESCRIPTION()

#define IGT_TEST_DESCRIPTION(str) const char* __igt_test_description = str

Defines a description for a test. This is used as the output for the "--help-description" option and is also included in the generated documentation.

Parameters

str

description string

 

igt_fixture

#define             igt_fixture

Annotate global test fixture code

Testcase with subtests often need to set up a bunch of global state as the common test fixture. To avoid such code interfering with the subtest enumeration (e.g. when enumerating on systems without an intel gpu) such blocks should be annotated with igt_fixture.


igt_opt_handler_t ()

int
(*igt_opt_handler_t) (int opt,
                      int opt_index,
                      void *data);

igt_subtest_init_parse_opts ()

int
igt_subtest_init_parse_opts (int *argc,
                             char **argv,
                             const char *extra_short_opts,
                             const struct option *extra_long_opts,
                             const char *help_str,
                             igt_opt_handler_t extra_opt_handler,
                             void *handler_data);

This function handles the subtest related command line options and allows an arbitrary set of additional options. This is useful for tests which have additional knobs to tune when run manually like the number of rounds execute or the size of the allocated buffer objects.

Tests should use igt_main_args instead of their own main() function and calling this function.

The help_str parameter is printed directly after the help text of standard arguments. The formatting of the string should be:

  • One line per option

  • Two spaces, option flag, tab character, help text, newline character

Example: " -s\tBuffer size\n"

The opt handler function must return IGT_OPT_HANDLER_SUCCESS on successful handling, IGT_OPT_HANDLER_ERROR on errors.

Parameters

argc

argc from the test's main()

 

argv

argv from the test's main()

 

extra_short_opts

getopt_long() compliant list with additional short options

 

extra_long_opts

getopt_long() compliant list with additional long options

 

help_str

help string for the additional options

 

extra_opt_handler

handler for the additional options

 

handler_data

user data given to extra_opt_handler when invoked

 

Returns

Forwards any option parsing errors from getopt_long.


igt_subtest_init()

#define             igt_subtest_init(argc, argv)

This initializes the for tests with subtests without the need for additional command line options. It is just a simplified version of igt_subtest_init_parse_opts().

If there's not a reason to the contrary it's less error prone to just use an igt_main block instead of stitching the test's main() function together manually.

Parameters

argc

argc from the test's main()

 

argv

argv from the test's main()

 

igt_tokencat()

#define igt_tokencat(x, y) __igt_tokencat2(x, y)

C preprocessor helper to concatenate two variables while properly expanding them.

Parameters

x

first variable

 

y

second variable

 

igt_unique()

#define             igt_unique(prefix)

C preprocessor helper to generate a custom 'unique' token by appending the line number onto the token.

Parameters

prefix

local identifier

 

igt_subtest()

#define             igt_subtest(name)

This is a magic control flow block which denotes a subtest code block. Within that code block igt_skip|success will only bail out of the subtest. The _f variant accepts a printf format string, which is useful for constructing combinatorial tests.

This is a simpler version of igt_subtest_f()

Parameters

name

name of the subtest

 

igt_subtest_f()

#define             igt_subtest_f(f...)

This is a magic control flow block which denotes a subtest code block. Within that code block igt_skip|success will only bail out of the subtest. The _f variant accepts a printf format string, which is useful for constructing combinatorial tests.

Like igt_subtest(), but also accepts a printf format string instead of a static string.

Parameters

...

format string and optional arguments

 

igt_subtest_with_dynamic()

#define             igt_subtest_with_dynamic(name)

This is a magic control flow block which denotes a subtest code block that contains dynamic subsubtests. The _f variant accepts a printf format string, which is useful for constructing combinatorial tests.

See igt_subtest_with_dynamic_f() for documentation.

Parameters

name

name of the subtest

 

igt_subtest_with_dynamic_f()

#define             igt_subtest_with_dynamic_f(f...)

This is a magic control flow block which denotes a subtest code block that contains dynamic subsubtests. The _f variant accepts a printf format string, which is useful for constructing combinatorial tests.

Dynamic subsubtests are to be used when reporting several aspects of something separately is desired, but knowing the full possible set beforehand is either too big of a set or just plain impossible. Otherwise, use normal subtests. An easy example is performing an operation separately for each KMS pipe: A subtest per pipe requires iterating through all possible pipe identifiers, checking if the pipe exists for the tested device and skipping if does not, and then performing the operation. With dynamic subsubtests instead, there would be a single subtest for the operation that loops over the pipes available, enters a dynamic subsubtest for each pipe and performs the operation for that pipe in there.

The result of a subtest igt_subtest_with_dynamic will be

  • SKIP, if no dynamic subsubtests are entered

  • PASS, if _all_ dynamic subsubtests PASS

  • FAIL, if _any_ dynamic subsubtests FAIL

Within a igt_subtest_with_dynamic block, explicit failure (e.g. igt_assert) is not allowed, only dynamic subsubtests themselves will produce test results. igt_skip()/igt_require() is allowed. Example:

1
2
3
4
5
6
7
8
9
10
11
12
igt_main
{
    igt_subtest_with_dynamic("engine-tests") {
              igt_require(is_awesome(fd)); // requires ok here

              for_each_engine(fd, e) {
                      igt_dynamic_subtest_f("%s", e->name) {
                              igt_assert(works(e)); // asserts ok here
                      }
              }
      }
}

Like igt_subtest_with_dynamic(), but also accepts a printf format string instead of a static string.

Parameters

...

format string and optional arguments

 

igt_dynamic()

#define             igt_dynamic(name)

This is a magic control flow block which denotes a dynamic subtest-of-a-subtest code block. Within that code block igt_skip|success will only bail out of the dynamic subtest. The _f variant accepts a printf format string, which is useful for constructing combinatorial tests.

See igt_subtest_with_dynamic_f() for documentation on dynamic subsubtests.

Parameters

name

name of the dynamic subtest

 

igt_dynamic_f()

#define             igt_dynamic_f(f...)

This is a magic control flow block which denotes a dynamic subtest-of-a-subtest code block. Within that code block igt_skip|success will only bail out of the dynamic subtest. The _f variant accepts a printf format string, which is useful for constructing combinatorial tests.

See igt_subtest_with_dynamic_f() for documentation on dynamic subsubtests.

Like igt_dynamic(), but also accepts a printf format string instead of a static string.

Parameters

...

format string and optional arguments

 

igt_subtest_name ()

const char *
igt_subtest_name (void);

Returns

The name of the currently executed subtest or NULL if called from outside a subtest block.


igt_only_list_subtests ()

bool
igt_only_list_subtests (void);

Returns

Returns true if only subtest should be listed and any setup code must be skipped, false otherwise.


igt_main_args()

#define             igt_main_args(short_opts, long_opts, help_str, opt_handler, handler_data)

This is a magic control flow block used instead of a main() function for tests with subtests, along with custom command line arguments. The macro parameters are passed directly to igt_subtest_init_parse_opts.

Parameters

extra_short_opts

getopt_long() compliant list with additional short options

 

extra_long_opts

getopt_long() compliant list with additional long options

 

help_str

help string for the additional options

 

extra_opt_handler

handler for the additional options

 

handler_data

user data given to extra_opt_handler when invoked

 

igt_test_name ()

const char *
igt_test_name (void);

igt_simple_init_parse_opts ()

void
igt_simple_init_parse_opts (int *argc,
                            char **argv,
                            const char *extra_short_opts,
                            const struct option *extra_long_opts,
                            const char *help_str,
                            igt_opt_handler_t extra_opt_handler,
                            void *handler_data);

This initializes a simple test without any support for subtests and allows an arbitrary set of additional options. This is useful for tests which have additional knobs to tune when run manually like the number of rounds execute or the size of the allocated buffer objects.

Tests should use igt_simple_main_args instead of their own main() function and calling this function.

The help_str parameter is printed directly after the help text of standard arguments. The formatting of the string should be:

  • One line per option

  • Two spaces, option flag, tab character, help text, newline character

Example: " -s\tBuffer size\n"

The opt handler function must return IGT_OPT_HANDLER_SUCCESS on successful handling, IGT_OPT_HANDLER_ERROR on errors.

Parameters

argc

argc from the test's main()

 

argv

argv from the test's main()

 

extra_short_opts

getopt_long() compliant list with additional short options

 

extra_long_opts

getopt_long() compliant list with additional long options

 

help_str

help string for the additional options

 

extra_opt_handler

handler for the additional options

 

handler_data

user data given to extra_opt_handler when invoked

 

igt_simple_init()

#define             igt_simple_init(argc, argv)

This initializes a simple test without any support for subtests.

If there's not a reason to the contrary it's less error prone to just use an igt_simple_main block instead of stitching the test's main() function together manually.

Parameters

argc

argc from the test's main()

 

argv

argv from the test's main()

 

igt_simple_main_args()

#define             igt_simple_main_args(short_opts, long_opts, help_str, opt_handler, handler_data)

This is a magic control flow block used instead of a main() function for simple tests with custom command line arguments. The macro parameters are passed directly to igt_simple_init_parse_opts.

Parameters

extra_short_opts

getopt_long() compliant list with additional short options

 

extra_long_opts

getopt_long() compliant list with additional long options

 

help_str

help string for the additional options

 

extra_opt_handler

handler for the additional options

 

handler_data

user data given to extra_opt_handler when invoked

 

igt_skip ()

void
igt_skip (const char *f,
          ...);

Subtest aware test skipping. The format string is printed to stderr as the reason why the test skipped.

For tests with subtests this will either bail out of the current subtest or mark all subsequent subtests as SKIP (presuming some global setup code failed).

For normal tests without subtest it will directly exit.

Parameters

f

format string

 

...

optional arguments used in the format string

 

igt_skip_check()

#define             igt_skip_check(E, F...)

igt_success ()

void
igt_success (void);

Complete a (subtest) as successful

This bails out of a subtests and marks it as successful. For global tests it it won't bail out of anything.


igt_can_fail ()

bool
igt_can_fail (void);

Returns true if called from either an igt_fixture, igt_subtest or a testcase without subtests, i.e. igt_simple_main. Returns false otherwise. In other words, it checks whether it's legal to call igt_fail(), igt_skip_on() and all the convenience macros build around those.

This is useful to make sure that library code is called from the right places.


igt_describe_f ()

void
igt_describe_f (const char *fmt,
                ...);

Attach a description to the following igt_subtest or igt_subtest_group block.

Check igt_describe for more details.

Parameters

fmt

format string containing description

 

...

argument used by the format string

 

igt_describe()

#define             igt_describe(dsc)

Attach a description to the following igt_subtest or igt_subtest_group block.

The description should complement the test/subtest name and provide more context on what is being tested. It should explain the idea of the test and do not mention implementation details, so that it never goes out of date.

DO:

  • focus on the userspace's perspective

  • try to capture the reason for the test's existence

  • be brief

DON'T:

  • try to translate the code into English

  • explain all the checks the test does

  • delve on the implementation

Good examples:

  • "make sure that legacy cursor updates do not stall atomic commits"

  • "check that atomic updates of many planes are indeed atomic and take effect immediately after the commit"

  • "make sure that the meta-data exposed by the kernel to the userspace is correct and matches the used EDID"

Bad examples:

  • "spawn 10 threads, each pinning cpu core with a busy loop..."

  • "randomly generate holes in a primary plane then try to cover each hole with a plane and make sure that CRC matches, do 25 gazillion rounds of that..."

Resulting igt_subtest documentation is a concatenation of its own description and all the parenting igt_subtest_group descriptions, starting from the outermost one. Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#include "igt.h"

IGT_TEST_DESCRIPTION("Global description of the whole binary");
igt_main
{
    igt_describe("Desc of the subgroup with A and B");
    igt_subtest_group {
        igt_describe("Desc of the subtest A");
        igt_subtest("subtest-a") {
            ...
        }

        igt_describe("Desc of the subtest B");
        igt_subtest("subtest-b") {
            ...
        }
    }

    igt_describe("Desc of the subtest C");
    igt_subtest("subtest-c") {
        ...
    }
}

It's will accessible via --describe command line switch:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$ test --describe
Global description of the whole binary

SUB subtest-a test.c:5:
  Desc of the subgroup with A and B

  Desc of the subtest A

SUB subtest-b test.c:10:
  Desc of the subgroup with A and B

  Desc of the subtest B

SUB subtest-c test.c:15:
  Desc of the subtest C

Every single igt_subtest does not have to be preceded with a igt_describe as long as it has good-enough explanation provided on the igt_subtest_group level.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#include "igt.h"

igt_main
{
    igt_describe("check xyz with different tilings");
    igt_subtest_group {
        // no need for extra description, group is enough and tiling is
        // obvious from the test name
        igt_subtest("foo-tiling-x") {
            ...
        }

        igt_subtest("foo-tiling-y") {
            ...
        }
    }
}

Parameters

dsc

string containing description

 

igt_assert()

#define             igt_assert(expr)

Fails (sub-)test if the condition is not met.

Should be used everywhere where a test checks results.

Parameters

expr

condition to test

 

igt_assert_f()

#define             igt_assert_f(expr, f...)

Fails (sub-)test if the condition is not met.

Should be used everywhere where a test checks results.

In addition to the plain igt_assert() helper this allows to print additional information to help debugging test failures.

Parameters

expr

condition to test

 

...

format string and optional arguments

 

igt_fail_on()

#define igt_fail_on(expr) igt_assert(!(expr))

Fails (sub-)test if the condition is met.

Should be used everywhere where a test checks results.

Parameters

expr

condition to test

 

igt_fail_on_f()

#define igt_fail_on_f(expr, f...) igt_assert_f(!(expr), f)

Fails (sub-)test if the condition is met.

Should be used everywhere where a test checks results.

In addition to the plain igt_assert() helper this allows to print additional information to help debugging test failures.

Parameters

expr

condition to test

 

...

format string and optional arguments

 

igt_assert_cmpint()

#define             igt_assert_cmpint(n1, cmp, ncmp, n2)

Fails (sub-)test if the condition is not met

Should be used everywhere where a test compares two integer values.

Like igt_assert(), but displays the values being compared on failure instead of simply printing the stringified expression.

Parameters

n1

first value

 

cmp

compare operator

 

ncmp

negated version of cmp

 

n2

second value

 

igt_assert_cmpuint()

#define             igt_assert_cmpuint(n1, cmp, ncmp, n2)

Like igt_assert_cmpint(), but for unsigned ints.

Parameters

n1

first value

 

cmp

compare operator

 

ncmp

negated version of cmp

 

n2

second value

 

igt_assert_cmps64()

#define             igt_assert_cmps64(n1, cmp, ncmp, n2)

Like igt_assert_cmpuint(), but for larger signed ints.

Parameters

n1

first value

 

cmp

compare operator

 

ncmp

negated version of cmp

 

n2

second value

 

igt_assert_cmpu64()

#define             igt_assert_cmpu64(n1, cmp, ncmp, n2)

Like igt_assert_cmpuint(), but for larger ints.

Parameters

n1

first value

 

cmp

compare operator

 

ncmp

negated version of cmp

 

n2

second value

 

igt_assert_cmpdouble()

#define             igt_assert_cmpdouble(n1, cmp, ncmp, n2)

Like igt_assert_cmpint(), but for doubles.

Parameters

n1

first value

 

cmp

compare operator

 

ncmp

negated version of cmp

 

n2

second value

 

igt_assert_eq()

#define igt_assert_eq(n1, n2) igt_assert_cmpint(n1, ==, !=, n2)

Fails (sub-)test if the two integers are not equal. Beware that for now this only works on integers.

Like igt_assert(), but displays the values being compared on failure instead of simply printing the stringified expression.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_eq_u32()

#define igt_assert_eq_u32(n1, n2) igt_assert_cmpuint(n1, ==, !=, n2)

Like igt_assert_eq(), but for uint32_t.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_eq_s64()

#define igt_assert_eq_s64(n1, n2) igt_assert_cmps64(n1, ==, !=, n2)

Like igt_assert_eq_u32(), but for int64_t.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_eq_u64()

#define igt_assert_eq_u64(n1, n2) igt_assert_cmpu64(n1, ==, !=, n2)

Like igt_assert_eq_u32(), but for uint64_t.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_eq_double()

#define igt_assert_eq_double(n1, n2) igt_assert_cmpdouble(n1, ==, !=, n2)

Like igt_assert_eq(), but for doubles.

Parameters

n1

first double

 

n2

second double

 

igt_assert_neq()

#define igt_assert_neq(n1, n2) igt_assert_cmpint(n1, !=, ==, n2)

Fails (sub-)test if the two integers are equal. Beware that for now this only works on integers.

Like igt_assert(), but displays the values being compared on failure instead of simply printing the stringified expression.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_neq_u32()

#define igt_assert_neq_u32(n1, n2) igt_assert_cmpuint(n1, !=, ==, n2)

Like igt_assert_neq(), but for uint32_t.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_neq_u64()

#define igt_assert_neq_u64(n1, n2) igt_assert_cmpu64(n1, !=, ==, n2)

Like igt_assert_neq_u32(), but for uint64_t.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_neq_double()

#define igt_assert_neq_double(n1, n2) igt_assert_cmpdouble(n1, !=, ==, n2)

Like igt_assert_neq(), but for doubles.

Parameters

n1

first double

 

n2

second double

 

igt_assert_lte()

#define igt_assert_lte(n1, n2) igt_assert_cmpint(n1, <=, >, n2)

Fails (sub-)test if the second integer is strictly smaller than the first. Beware that for now this only works on integers.

Like igt_assert(), but displays the values being compared on failure instead of simply printing the stringified expression.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_lte_u32()

#define igt_assert_lte_u32(n1, n2) igt_assert_cmpuint(n1, <=, >, n2)

Like igt_assert_lte(), but for uint32_t.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_lte_u64()

#define igt_assert_lte_u64(n1, n2) igt_assert_cmpu64(n1, <=, >, n2)

Fails (sub-)test if the second integer is strictly smaller than the first. Beware that for now this only works on integers.

Like igt_assert(), but displays the values being compared on failure instead of simply printing the stringified expression.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_lte_s64()

#define igt_assert_lte_s64(n1, n2) igt_assert_cmps64(n1, <=, >, n2)

Fails (sub-)test if the second integer is strictly smaller than the first. Beware that for now this only works on integers.

Like igt_assert(), but displays the values being compared on failure instead of simply printing the stringified expression.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_lt()

#define igt_assert_lt(n1, n2) igt_assert_cmpint(n1, <, >=, n2)

Fails (sub-)test if the second integer is smaller than or equal to the first. Beware that for now this only works on integers.

Like igt_assert(), but displays the values being compared on failure instead of simply printing the stringified expression.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_lt_u32()

#define igt_assert_lt_u32(n1, n2) igt_assert_cmpuint(n1, <, >=, n2)

Like igt_assert_lt(), but for uint32_t.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_lt_u64()

#define igt_assert_lt_u64(n1, n2) igt_assert_cmpu64(n1, <, >=, n2)

Fails (sub-)test if the second integer is smaller than or equal to the first. Beware that for now this only works on integers.

Like igt_assert(), but displays the values being compared on failure instead of simply printing the stringified expression.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_lt_s64()

#define igt_assert_lt_s64(n1, n2) igt_assert_cmps64(n1, <, >=, n2)

Fails (sub-)test if the second integer is smaller than or equal to the first. Beware that for now this only works on integers.

Like igt_assert(), but displays the values being compared on failure instead of simply printing the stringified expression.

Parameters

n1

first integer

 

n2

second integer

 

igt_assert_lt_double()

#define igt_assert_lt_double(n1, n2) igt_assert_cmpdouble(n1, <, >=, n2)

Fails (sub-)test if the second double is smaller than or equal to the first.

Like igt_assert(), but displays the values being compared on failure instead of simply printing the stringified expression.

Parameters

n1

first double

 

n2

second double

 

igt_assert_fd()

#define             igt_assert_fd(fd)

Fails (sub-) test if the given file descriptor is invalid.

Like igt_assert(), but displays the stringified identifier that was supposed to contain a valid fd on failure.

Parameters

fd

file descriptor

 

igt_require()

#define             igt_require(expr)

Skip a (sub-)test if a condition is not met.

Should be used everywhere where a test checks results to decide about skipping. This is useful to streamline the skip logic since it allows for a more flat code control flow, similar to igt_assert()

Parameters

expr

condition to test

 

igt_skip_on()

#define             igt_skip_on(expr)

Skip a (sub-)test if a condition is met.

Should be used everywhere where a test checks results to decide about skipping. This is useful to streamline the skip logic since it allows for a more flat code control flow, similar to igt_assert()

Parameters

expr

condition to test

 

igt_require_f()

#define             igt_require_f(expr, f...)

Skip a (sub-)test if a condition is not met.

Should be used everywhere where a test checks results to decide about skipping. This is useful to streamline the skip logic since it allows for a more flat code control flow, similar to igt_assert()

In addition to the plain igt_require() helper this allows to print additional information to help debugging test failures.

Parameters

expr

condition to test

 

...

format string and optional arguments

 

igt_require_fd()

#define             igt_require_fd(fd)

Skips (sub-) test if the given file descriptor is invalid.

Like igt_require(), but displays the stringified identifier that was supposed to contain a valid fd on failure.

Parameters

fd

file descriptor

 

igt_skip_on_f()

#define             igt_skip_on_f(expr, f...)

Skip a (sub-)test if a condition is met.

Should be used everywhere where a test checks results to decide about skipping. This is useful to streamline the skip logic since it allows for a more flat code control flow, similar to igt_assert()

In addition to the plain igt_skip_on() helper this allows to print additional information to help debugging test failures.

Parameters

expr

condition to test

 

...

format string and optional arguments

 

igt_abort_on_f()

#define             igt_abort_on_f(expr, f...)

Aborts current execution if a condition is met.

Should be used only when there is a serious issue with the environment and any further testing may be affected by it.

Parameters

expr

condition to test

 

...

format string and optional arguments

 

igt_fork()

#define             igt_fork(child, num_children)

This is a magic control flow block which spawns parallel test threads with fork().

The test children execute in parallel to the main test thread. Joining all test threads should be done with igt_waitchildren to ensure that the exit codes of all children are properly reflected in the test status.

Note that igt_skip() will not be forwarded, feature tests need to be done before spawning threads with igt_fork().

Parameters

child

name of the int variable with the child number

 

num_children

number of children to fork

 

igt_waitchildren ()

void
igt_waitchildren (void);

Wait for all children forked with igt_fork.

The magic here is that exit codes from children will be correctly propagated to the main thread, including the relevant exit code if a child thread failed. Of course if multiple children failed with different exit codes the resulting exit code will be non-deterministic.

Note that igt_skip() will not be forwarded, feature tests need to be done before spawning threads with igt_fork().


igt_waitchildren_timeout ()

void
igt_waitchildren_timeout (int seconds,
                          const char *reason);

Wait for all children forked with igt_fork, for a maximum of seconds . If the timeout expires, kills all children, cleans them up, and then fails by calling igt_fail().

Parameters

seconds

timeout in seconds to wait

 

reason

debug string explaining what timedout

 

igt_kill_children ()

void
igt_kill_children (int signal);

igt_multi_fork()

#define             igt_multi_fork(child, num_children)

This is a magic control flow block which spawns parallel processes with fork() expecting there will runs without skips.

The test children execute in parallel to the main test process. Joining all test threads should be done with igt_waitchildren. After multi_fork one can use igt_fork once to run more children.

Like in igt_fork() any igt_skip() will cause test fail.

Parameters

child

name of the int variable with the child number

 

num_children

number of children to fork

 

igt_fork_helper()

#define             igt_fork_helper(proc)

This is a magic control flow block which denotes an asynchronous helper process block. The difference compared to igt_fork() is that failures from the child process will not be forwarded, making this construct more suitable for background processes. Common use cases are regular interference of the main test thread through e.g. sending signals or evicting objects through debugfs. Through the explicit igt_helper_process they can also be controlled in a more fine-grained way than test children spawned through igt_fork().

For tests with subtest helper process can be started outside of a igt_subtest block.

Calling igt_wait_helper() joins a helper process and igt_stop_helper() forcefully terminates it.

Parameters

proc

igt_helper_process structure

 

igt_wait_helper ()

int
igt_wait_helper (struct igt_helper_process *proc);

Joins a helper process. It is an error to call this on a helper process which hasn't been spawned yet.

Parameters

proc

igt_helper_process structure

 

igt_stop_helper ()

void
igt_stop_helper (struct igt_helper_process *proc);

Terminates a helper process. It is legal to call this on a helper process which hasn't been spawned yet, e.g. if the helper was skipped due to HW restrictions.

Parameters

proc

igt_helper_process structure

 

igt_exit_handler_t ()

void
(*igt_exit_handler_t) (int sig);

Exit handler type used by igt_install_exit_handler(). Note that exit handlers can potentially be run from signal handling contexts, the sig parameter can be used to figure this out and act accordingly.

Parameters

sig

Signal number which caused the exit or 0.

 

igt_install_exit_handler ()

void
igt_install_exit_handler (igt_exit_handler_t fn);

Set a handler that will be called either when the process calls exit() or returns from the main function, or one of the signals in 'handled_signals' is raised. MAX_EXIT_HANDLERS handlers can be installed, each of which will be called only once, even if a subsequent signal is raised. If the exit handlers are called due to a signal, the signal will be re-raised with the original signal disposition after all handlers returned.

The handler will be passed the signal number if called due to a signal, or 0 otherwise. Exit handlers can also be used from test children spawned with igt_fork(), but not from within helper processes spawned with igt_fork_helper(). The list of exit handlers is reset when forking to avoid issues with children cleanup up the parent's state too early.

Parameters

fn

exit handler function

 

igt_run_in_simulation ()

bool
igt_run_in_simulation (void);

This function can be used to select a reduced test set when running in simulation environments. This i-g-t mode is selected by setting the INTEL_SIMULATION environment variable to 1.

Returns

True when run in simulation mode, false otherwise.


SLOW_QUICK()

#define SLOW_QUICK(hw, sim) (igt_run_in_simulation() ? (sim) : (hw))

Simple macro to select between two values (e.g. number of test rounds or test buffer size) depending upon whether i-g-t is run in simulation mode or not.

Parameters

sim

value in simulation mode

 

hw

value in normal mode

 

igt_skip_on_simulation ()

void
igt_skip_on_simulation (void);

Skip tests when INTEL_SIMULATION environment variable is set. It uses igt_skip() internally and hence is fully subtest aware.

Note that in contrast to all other functions which use igt_skip() internally it is allowed to use this outside of an igt_fixture block in a test with subtests. This is because in contrast to most other test requirements, checking for simulation mode doesn't depend upon the present hardware and it so makes a lot of sense to have this check in the outermost igt_main block.


igt_log ()

void
igt_log (const char *domain,
         enum igt_log_level level,
         const char *format,
         ...);

This is the generic structured logging helper function. i-g-t testcase should output all normal message to stdout. Warning level message should be printed to stderr and the test runner should treat this as an intermediate result between SUCCESS and FAILURE.

The log level can be set through the IGT_LOG_LEVEL environment variable with values "debug", "info", "warn", "critical" and "none". By default verbose debug message are disabled. "none" completely disables all output and is not recommended since crucial issues only reported at the IGT_LOG_WARN level are ignored.

Parameters

domain

the log domain, or NULL for no domain

 

level

igt_log_level

 

format

format string

 

...

optional arguments used in the format string

 

igt_vlog ()

void
igt_vlog (const char *domain,
          enum igt_log_level level,
          const char *format,
          va_list args);

This is the generic logging helper function using an explicit varargs structure and hence useful to implement domain-specific logging functions.

If there is no need to wrap up a vararg list in the caller it is simpler to just use igt_log().

Parameters

domain

the log domain, or NULL for no domain

 

level

igt_log_level

 

format

format string

 

args

variable arguments lists

 

igt_debug()

#define igt_debug(f...) igt_log(IGT_LOG_DOMAIN, IGT_LOG_DEBUG, f)

Wrapper for igt_log() for message at the IGT_LOG_DEBUG level.

Parameters

...

format string and optional arguments

 

igt_info()

#define igt_info(f...) igt_log(IGT_LOG_DOMAIN, IGT_LOG_INFO, f)

Wrapper for igt_log() for message at the IGT_LOG_INFO level.

Parameters

...

format string and optional arguments

 

igt_warn()

#define igt_warn(f...) igt_log(IGT_LOG_DOMAIN, IGT_LOG_WARN, f)

Wrapper for igt_log() for message at the IGT_LOG_WARN level.

Parameters

...

format string and optional arguments

 

igt_critical()

#define igt_critical(f...) igt_log(IGT_LOG_DOMAIN, IGT_LOG_CRITICAL, f)

Wrapper for igt_log() for message at the IGT_LOG_CRITICAL level.

Parameters

...

format string and optional arguments

 

igt_buffer_log_handler_t ()

bool
(*igt_buffer_log_handler_t) (const char *line,
                             void *data);

igt_log_buffer_inspect ()

void
igt_log_buffer_inspect (igt_buffer_log_handler_t check,
                        void *data);

Provides a way to replay the internal igt log buffer for inspection. check : A user-specified handler that gets invoked for each line of the log buffer. The handler should return true to stop inspecting the rest of the buffer. data : passed as a user argument to the inspection function.


igt_warn_on()

#define             igt_warn_on(condition)

Print a IGT_LOG_WARN level message if a condition is not met.

Should be used everywhere where a test checks results to decide about printing warnings. This is useful to streamline the test logic since it allows for a more flat code control flow, similar to igt_assert()

This macro also returns the value of condition .

Parameters

condition

condition to test

 

igt_warn_on_f()

#define             igt_warn_on_f(condition, f...)

Skip a (sub-)test if a condition is not met.

Print a IGT_LOG_WARN level message if a condition is not met.

Should be used everywhere where a test checks results to decide about printing warnings. This is useful to streamline the test logic since it allows for a more flat code control flow, similar to igt_assert()

In addition to the plain igt_warn_on_f() helper this allows to print additional information (again as warnings) to help debugging test failures.

It also returns the value of condition .

Parameters

condition

condition to test

 

...

format string and optional arguments

 

igt_debug_on()

#define             igt_debug_on(condition)

Print a IGT_LOG_DEBUG level message if a condition is met.

Should be used when something fails in a function that doesn't perform a long jump in that case, and either performs several operations that can fail that way or doesn't return unambiguous error codes on failures. This is useful to streamline the test logic since it allows for replacing open conding with function calls without loosing ability to provide debug output with failure details.

This macro also returns the value of condition .

Parameters

condition

condition to test

 

igt_debug_on_f()

#define             igt_debug_on_f(condition, f...)

Print a IGT_LOG_DEBUG level message if a condition is met.

Should be used when something fails in a function that doesn't perform a long jump in that case, and performs one or more operations in a loop, each time with different values of parameters. This is useful to streamline the test logic since it allows for replacing open conding with function calls without loosing ability to provide debug output with failure details.

In addition to the plain igt_debug_on() helper this allows to print additional debug information to help debugging operation failures.

It also returns the value of condition .

Parameters

condition

condition to test

 

...

format string and optional arguments

 

igt_set_timeout ()

void
igt_set_timeout (unsigned int seconds,
                 const char *op);

Fail a test and exit with IGT_EXIT_FAILURE status after the specified number of seconds have elapsed. If the current test has subtests and the timeout occurs outside a subtest, subsequent subtests will be skipped and marked as failed.

Any previous timer is cancelled and no timeout is scheduled if seconds is zero. But for clarity the timeout set with this function should be cleared with igt_reset_timeout().

Parameters

seconds

number of seconds before timeout

 

op

Optional string to explain what operation has timed out in the debug log

 

igt_gettime ()

int
igt_gettime (struct timespec *ts);

Reports the current time in the monotonic clock.

Parameters

ts

current monotonic clock reading

 

Returns

0 on success, -errno on failure.


igt_time_elapsed ()

double
igt_time_elapsed (struct timespec *then,
                  struct timespec *now);

Parameters

then

Earlier timestamp

 

now

Later timestamp

 

Returns

Time between two timestamps in seconds, as a floating point number.


igt_nsec_elapsed ()

uint64_t
igt_nsec_elapsed (struct timespec *start);

Reports the difference in the monotonic clock from the start time in nanoseconds. On the first invocation, start should be zeroed and will be set by the call.

Typical use would be:

igt_subtest("test") { struct timespec start = {}; while (igt_nsec_elapsed(&start) < test_timeout_ns) do_test(); }

A handy approximation is to use nsec >> 30 to convert to seconds, nsec >> 20 to convert to milliseconds - the error is about 8%, acceptable for test run times.

Parameters

start

measure from this point in time

 

igt_fopen_data()

#define             igt_fopen_data(filename)

Open a datafile for test, first try from installation directory, then from build directory, and finally from current directory.

Parameters

filename

filename to open.

 

igt_system ()

int
igt_system (const char *command);

An improved replacement of the system() call.

Executes the shell command specified in command with the added feature of concurrently capturing its stdout and stderr to igt_log and igt_warn respectively.

Returns

The exit status of the executed process. -1 for failure.


igt_system_quiet ()

int
igt_system_quiet (const char *command);

Returns

The exit status of the executed process. -1 for failure.


igt_system_cmd()

#define             igt_system_cmd(status, format...)

igt_srandom ()

void
igt_srandom (void);

It initializes seed for random number generator. If specific value is needed it can be set with IGT_SRANDOM environment variable.


igt_trace ()

void
igt_trace (const char *format,
           ...);

Writes a message into the kernel trace log.

Parameters

format

printf-style format string with optional args

 

igt_kmsg ()

void
igt_kmsg (const char *format,
          ...);

Writes a message into the kernel log file (/dev/kmsg).

Parameters

format

printf-style format string with optional args

 

READ_ONCE ()

return
READ_ONCE ();

WRITE_ONCE()

#define WRITE_ONCE(x, v) do *(volatile typeof(x) *)(&(x)) = (v); while (0)

cpu_to_le32()

#define cpu_to_le32(x)  bswap_32(x)

le32_to_cpu()

#define le32_to_cpu(x)  bswap_32(x)

for_if()

#define for_if(expr__) if (!(expr__)) {} else

igt_pci_system_init ()

int
igt_pci_system_init (void);

Runs pci_system_init() and installs igt_pci_system_cleanup() as IGT exit handler when called first per thread, subsequent calls are noop. Tests should use this wrapper instead of pci_system_init() to avoid memory leaking which happens each time a call to pci_system_init() is repeated not preceded by pci_system_cleanup() (may easily happen in consequence of long jumps performed by IGT flow control functions).

Return: Return value of pci_system_init() or 0 if pci system is already initialized.


igt_pci_system_reinit ()

int
igt_pci_system_reinit (void);

Executes igt_pci_system_cleanup() and igt_pci_system_init() to refresh the PCI system state, typically needed after PCI devices are added or removed.

Note: All previously obtained handles (pci_dev, mmio) become invalid after this call. Do not use old handles post-reinitialization.

Return: Outcome of igt_pci_system_init().


igt_pci_system_cleanup ()

void
igt_pci_system_cleanup (void);

igt_emit_ignore_dmesg_regex ()

void
igt_emit_ignore_dmesg_regex (const char *ignore_dmesg_regex);

Emits a string for igt_runner to ignore next dmesg warns or errors which matches it.

Parameters

ignore_dmesg

string regex

 

Types and Values

IGT_LOG_DOMAIN

#define IGT_LOG_DOMAIN (NULL)

STATIC_ANALYSIS_BUILD

#define STATIC_ANALYSIS_BUILD 1

igt_frame_dump_path

extern char *igt_frame_dump_path;

IGT_EXIT_SKIP

#define IGT_EXIT_SKIP    77

Exit status indicating the test was skipped.


IGT_EXIT_SUCCESS

#define IGT_EXIT_SUCCESS 0

Exit status indicating the test executed successfully.


IGT_EXIT_INVALID

#define IGT_EXIT_INVALID 79

Exit status indicating an invalid option or subtest was specified


IGT_EXIT_FAILURE

#define IGT_EXIT_FAILURE 98

Exit status indicating a test failure


IGT_EXIT_ABORT

#define IGT_EXIT_ABORT 112

Exit status indicating a severe test/environment failure, any continued testing past this point can yield unexpected results and is not recommended


igt_subtest_jmpbuf

extern jmp_buf igt_subtest_jmpbuf;

igt_dynamic_jmpbuf

extern jmp_buf igt_dynamic_jmpbuf;

IGT_OPT_HANDLER_SUCCESS

#define IGT_OPT_HANDLER_SUCCESS 0

IGT_OPT_HANDLER_ERROR

#define IGT_OPT_HANDLER_ERROR -2

igt_subtest_group

#define             igt_subtest_group

Group a set of subtests together with their common setup code

Testcase with subtests often need to set up a bunch of shared state as the common test fixture. But if there are multiple with different requirements the commont setup code can't be extracted, since a test condition failure in e.g. igt_require() would result in all subsequent tests skipping. Even those from a different group.

This macro allows to group together a set of igt_fixture and igt_subtest clauses. If any common setup in a fixture fails, only the subtests in this group will fail or skip. Subtest groups can be arbitrarily nested.


igt_main

#define igt_main igt_main_args(NULL, NULL, NULL, NULL, NULL)

This is a magic control flow block used instead of a main() function for tests with subtests. Open-coding the main() function is not recommended.


igt_simple_main

#define igt_simple_main igt_simple_main_args(NULL, NULL, NULL, NULL, NULL)

This is a magic control flow block used instead of a main() function for simple tests. Open-coding the main() function is not recommended.


igt_constructor

#define             igt_constructor

Convenience macro to run the provided code block when igt first starts, before any tests have been run. This should be used for parts of the igt library that require initialization of objects with global context.

This code block will be executed exactly once.


struct igt_helper_process

struct igt_helper_process {
	bool running;
	bool use_SIGKILL;
	pid_t pid;
	int id;
};

Tracking structure for helper processes. Users of the i-g-t library should only set use_SIGKILL directly.

Members

bool running;

indicates whether the process is currently running

 

bool use_SIGKILL;

whether the helper should be terminated with SIGKILL or SIGTERM

 

pid_t pid;

pid of the helper if running is true

 

int id;

internal id

 

igt_interactive_debug

extern const char *igt_interactive_debug;

igt_skip_crc_compare

extern bool igt_skip_crc_compare;

enum igt_log_level

Log levels used by functions like igt_log().

Members

IGT_LOG_DEBUG

debug information, not printed by default

 

IGT_LOG_INFO

informational message, printed by default

 

IGT_LOG_WARN

non-fatal warnings which should be treated as test failures

 

IGT_LOG_CRITICAL

critical errors which lead to immediate termination of tests

 

IGT_LOG_NONE

unused

 

KMSG_EMER

#define KMSG_EMER "<0>[IGT] "

KMSG_ALERT

#define KMSG_ALERT "<1>[IGT] "

KMSG_CRIT

#define KMSG_CRIT "<2>[IGT] "

KMSG_ERR

#define KMSG_ERR "<3>[IGT] "

KMSG_WARNING

#define KMSG_WARNING "<4>[IGT] "

KMSG_NOTICE

#define KMSG_NOTICE "<5>[IGT] "

KMSG_INFO

#define KMSG_INFO "<6>[IGT] "

KMSG_DEBUG

#define KMSG_DEBUG "<7>[IGT] "

MSEC_PER_SEC

#define MSEC_PER_SEC (1000u)

USEC_PER_SEC

#define USEC_PER_SEC (1000u * MSEC_PER_SEC)

USEC_PER_DECISEC

#define USEC_PER_DECISEC (100u * MSEC_PER_SEC)

NSEC_PER_SEC

#define NSEC_PER_SEC (1000u * USEC_PER_SEC)

USEC_PER_MSEC

#define USEC_PER_MSEC (1000u)

NSEC_PER_MSEC

#define NSEC_PER_MSEC (1000u * USEC_PER_MSEC)