diff options
author | Daniel Vetter <daniel.vetter@ffwll.ch> | 2014-03-12 02:34:40 +0100 |
---|---|---|
committer | Daniel Vetter <daniel.vetter@ffwll.ch> | 2014-03-12 16:39:39 +0100 |
commit | 55e64989e5f0359796d6e71d6753e432861b04a4 (patch) | |
tree | 8207435c6230be07a9e61cbf460956f4308ee1ca /lib/igt_core.h | |
parent | d63fe1519d34f0d0311ef8e3472c8b83c3dcfde3 (diff) |
lib/igt_core: api documentation
At most a bit of comment of function declaration movement for more
polish. One tricky bit is to #ifdef out (only for gtkdoc of course)
the struct option; forward declaration - gtkdoc needlessly lists it.
FIXME: The struct documentation for igt_helper_process somehow doesn't
get picked up ... Same issue seems to be with the igt_log_level enum,
I've shoveled the relevant documentation into igt_log in free-form for
now.
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Diffstat (limited to 'lib/igt_core.h')
-rw-r--r-- | lib/igt_core.h | 298 |
1 files changed, 226 insertions, 72 deletions
diff --git a/lib/igt_core.h b/lib/igt_core.h index 1ec0bfcb..0e3d7be0 100644 --- a/lib/igt_core.h +++ b/lib/igt_core.h @@ -30,8 +30,6 @@ #ifndef IGT_CORE_H #define IGT_CORE_H -bool igt_only_list_subtests(void); - bool __igt_fixture(void); void __igt_fixture_complete(void); void __igt_fixture_end(void) __attribute__((noreturn)); @@ -56,25 +54,42 @@ void __igt_fixture_end(void) __attribute__((noreturn)); jmp_buf igt_subtest_jmpbuf; void igt_subtest_init(int argc, char **argv); typedef int (*igt_opt_handler_t)(int opt, int opt_index); +#ifndef __GTK_DOC_IGNORE__ /* gtkdoc wants to document this forward decl */ struct option; +#endif int igt_subtest_init_parse_opts(int argc, char **argv, const char *extra_short_opts, struct option *extra_long_opts, const char *help_str, - igt_opt_handler_t opt_handler); + igt_opt_handler_t extra_opt_handler); bool __igt_run_subtest(const char *subtest_name); +#define __igt_tokencat2(x, y) x ## y + +/** + * igt_tokencat: + * @x: first variable + * @y: second variable + * + * C preprocessor helper to concatenate two variables while properly expanding + * them. + */ +#define igt_tokencat(x, y) __igt_tokencat2(x, y) + /** * igt_subtest: + * @name: name of the subtest * - * Denote a subtest code block + * This is a magic control flow block which denotes a subtest code block. Within + * that codeblock 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. * - * Magic control flow which denotes a subtest code block. Within that codeblock - * 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() */ -#define igt_tokencat2(x, y) x ## y -#define igt_tokencat(x, y) igt_tokencat2(x, y) +#define igt_subtest(name) for (; __igt_run_subtest((name)) && \ + (setjmp(igt_subtest_jmpbuf) == 0); \ + igt_success()) #define __igt_subtest_f(tmp, format...) \ for (char tmp [256]; \ snprintf( tmp , sizeof( tmp ), \ @@ -85,18 +100,29 @@ bool __igt_run_subtest(const char *subtest_name); /** * igt_subtest_f: - * @...: format string + * @...: format string and optional arguments * - * Denote a subtest code block + * This is a magic control flow block which denotes a subtest code block. Within + * that codeblock 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 + * Like igt_subtest(), but also accepts a printf format string instead of a + * static string. */ #define igt_subtest_f(f...) \ __igt_subtest_f(igt_tokencat(__tmpchar, __LINE__), f) -#define igt_subtest(name) for (; __igt_run_subtest((name)) && \ - (setjmp(igt_subtest_jmpbuf) == 0); \ - igt_success()) + const char *igt_subtest_name(void); +bool igt_only_list_subtests(void); + +/** + * igt_main: + * + * This is a magic control flow block used instead of a main() function for + * tests with subtests. Open-coding the main() function is only recommended if + * the test needs to parse additional cmdline arguments of its own. + */ #define igt_main \ static void igt_tokencat(__real_main, __LINE__)(void); \ int main(int argc, char **argv) { \ @@ -112,6 +138,14 @@ const char *igt_subtest_name(void); * Init for simple tests without subtests */ void igt_simple_init(void); + +/** + * igt_simple_main: + * + * This is a magic control flow block used instead of a main() function for + * simple tests. Open-coding the main() function is only recommended if + * the test needs to parse additional cmdline arguments of its own. + */ #define igt_simple_main \ static void igt_tokencat(__real_main, __LINE__)(void); \ int main(int argc, char **argv) { \ @@ -121,62 +155,27 @@ void igt_simple_init(void); } \ static void igt_tokencat(__real_main, __LINE__)(void) \ -/** - * igt_skip: - * - * Subtest aware test skipping - * - * For tests with subtests this will either bail out of the current subtest or - * mark all subsequent subtests as SKIP (in case some global setup code failed). - * - * For normal tests without subtest it will directly exit. - */ __attribute__((format(printf, 1, 2))) void igt_skip(const char *f, ...) __attribute__((noreturn)); __attribute__((format(printf, 5, 6))) void __igt_skip_check(const char *file, const int line, const char *func, const char *check, const char *format, ...) __attribute__((noreturn)); -/** - * igt_success: - * - * Complete a (subtest) as successfull - * - * This bails out of a subtests and marks it as successful. For global tests it - * it won't bail out of anything. - */ void igt_success(void); -/** - * igt_fail: - * - * Fail a testcase - * - * For subtest it just bails out of the subtest, when run in global context it - * will exit. Note that it won't attempt to keep on running further tests, - * presuming that some mandatory setup failed. - */ void igt_fail(int exitcode) __attribute__((noreturn)); __attribute__((format(printf, 6, 7))) void __igt_fail_assert(int exitcode, const char *file, const int line, const char *func, const char *assertion, const char *format, ...) __attribute__((noreturn)); -/** - * igt_exit: - * - * exit() for igts - * - * This will exit the test with the right exit code when subtests have been - * skipped. For normal tests it exits with a successful exit code, presuming - * everything has worked out. For subtests it also checks that at least one - * subtest has been run (save when only listing subtests. - */ void igt_exit(void) __attribute__((noreturn)); + /** * igt_assert: + * @expr: condition to test * - * Fails (sub-)test if a condition is not met + * Fails (sub-)test if the condition is not met * * Should be used everywhere where a test checks results. */ @@ -184,14 +183,36 @@ void igt_exit(void) __attribute__((noreturn)); do { if (!(expr)) \ __igt_fail_assert(99, __FILE__, __LINE__, __func__, #expr , NULL); \ } while (0) + +/** + * igt_assert_f: + * @expr: condition to test + * @...: format string and optional arguments + * + * 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. + */ #define igt_assert_f(expr, f...) \ do { if (!(expr)) \ __igt_fail_assert(99, __FILE__, __LINE__, __func__, #expr , f); \ } while (0) + /** - * igt_assert_cmptint: + * igt_assert_cmpint: + * @n1: first value + * @cmp: compare operator + * @n2: second value + * + * 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. + * Like igt_assert(), but displays the values being compared on failure instead + * of simply printing the stringified expression. */ #define igt_assert_cmpint(n1, cmp, n2) \ do { \ @@ -204,18 +225,61 @@ void igt_exit(void) __attribute__((noreturn)); /** * igt_require: + * @expr: condition to test * - * Skip a (sub-)test if a condition is not met + * Skip a (sub-)test if a condition is not met. * - * This is useful to streamline the skip logic since it allows for a more flat - * code control flow. + * 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() */ #define igt_require(expr) igt_skip_on(!(expr)) + +/** + * igt_skip_on: + * @expr: condition to test + * + * 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() + */ #define igt_skip_on(expr) \ do { if ((expr)) \ __igt_skip_check(__FILE__, __LINE__, __func__, #expr , NULL); \ } while (0) + +/** + * igt_require_f: + * @expr: condition to test + * @...: format string and optional arguments + * + * 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. + */ #define igt_require_f(expr, f...) igt_skip_on_f(!(expr), f) + +/** + * igt_skip_on_f: + * @expr: condition to test + * @...: format string and optional arguments + * + * 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. + */ #define igt_skip_on_f(expr, f...) \ do { if ((expr)) \ __igt_skip_check(__FILE__, __LINE__, __func__, #expr , f); \ @@ -223,21 +287,37 @@ void igt_exit(void) __attribute__((noreturn)); /* fork support code */ bool __igt_fork(void); + /** * igt_fork: * @child: name of the int variable with the child number * @num_children: number of children to fork * - * Fork parallel test threads with fork() + * 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. * - * 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(). */ #define igt_fork(child, num_children) \ for (int child = 0; child < (num_children); child++) \ for (; __igt_fork(); exit(0)) void igt_waitchildren(void); +/** + * igt_helper_process_t: + * @running: indicates whether the process is currently running + * @use_SIGKILL: whether the helper should be terminated with SIGKILL or SIGQUIT + * @pid: pid of the helper if @running is true + * @id: internal id + * + * Tracking structure for helper processes. Users of the i-g-t library should + * only set @use_SIGKILL directly. + */ struct igt_helper_process { bool running; bool use_SIGKILL; @@ -245,12 +325,40 @@ struct igt_helper_process { int id; }; bool __igt_fork_helper(struct igt_helper_process *proc); -void igt_stop_helper(struct igt_helper_process *proc); -void igt_wait_helper(struct igt_helper_process *proc); + +/** + * igt_fork_helper: + * @proc: #igt_helper_process structure + * + * 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. + */ #define igt_fork_helper(proc) \ for (; __igt_fork_helper(proc); exit(0)) +void igt_wait_helper(struct igt_helper_process *proc); +void igt_stop_helper(struct igt_helper_process *proc); /* exit handler code */ + +/** + * igt_exit_handler_t: + * @sig: Signal number which caused the exit or 0. + * + * 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. + */ typedef void (*igt_exit_handler_t)(int sig); /* reliable atexit helpers, also work when killed by a signal (if possible) */ @@ -260,18 +368,16 @@ void igt_disable_exit_handler(void); /* helpers to automatically reduce test runtime in simulation */ bool igt_run_in_simulation(void); -#define SLOW_QUICK(slow,quick) (igt_run_in_simulation() ? (quick) : (slow)) /** - * igt_skip_on_simulation: - * - * Skip tests when INTEL_SIMULATION env war is set + * SLOW_QUICK: + * @slow: value in simulation mode + * @quick: value in normal mode * - * Skip the test when running on simulation (and that's relevant only when - * we're not in the mode where we list the subtests). - * - * This function is subtest aware (since it uses igt_skip) and so can be used to - * skip specific subtests or all subsequent subtests. + * 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. */ +#define SLOW_QUICK(slow,quick) (igt_run_in_simulation() ? (quick) : (slow)) + void igt_skip_on_simulation(void); /* structured logging */ @@ -283,16 +389,64 @@ enum igt_log_level { }; __attribute__((format(printf, 2, 3))) void igt_log(enum igt_log_level level, const char *format, ...); + +/** + * igt_debug: + * @...: format string and optional arguments + * + * Wrapper for igt_log for message at the IGT_LOG_DEBUG level. + */ #define igt_debug(f...) igt_log(IGT_LOG_DEBUG, f) + +/** + * igt_info: + * @...: format string and optional arguments + * + * Wrapper for igt_log for message at the IGT_LOG_INFO level. + */ #define igt_info(f...) igt_log(IGT_LOG_INFO, f) + +/** + * igt_warn: + * @...: format string and optional arguments + * + * Wrapper for igt_log for message at the IGT_LOG_WARN level. + */ #define igt_warn(f...) igt_log(IGT_LOG_WARN, f) extern enum igt_log_level igt_log_level; +/** + * igt_warn_on: + * @condition: condition to test + * + * 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() + */ #define igt_warn_on(condition) do {\ if (condition) \ igt_warn("Warning on condition %s in fucntion %s, file %s:%i\n", \ #condition, __func__, __FILE__, __LINE__); \ } while (0) + +/** + * igt_warn_on_f: + * @condition: condition to test + * @...: format string and optional arguments + * + * 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. + */ #define igt_warn_on_f(condition, f...) do {\ if (condition) {\ igt_warn("Warning on condition %s in fucntion %s, file %s:%i\n", \ |