igt_core.h 17.4 KB
Newer Older
Daniel Vetter's avatar
Daniel Vetter committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
/*
 * Copyright © 2007,2014 Intel Corporation
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the next
 * paragraph) shall be included in all copies or substantial portions of the
 * Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 *
 * Authors:
 *    Eric Anholt <eric@anholt.net>
 *    Daniel Vetter <daniel.vetter@ffwll.ch>
 *
 */


#ifndef IGT_CORE_H
#define IGT_CORE_H

33
#include <setjmp.h>
34
#include <stdbool.h>
35
#include <stdlib.h>
36 37
#include <string.h>
#include <sys/types.h>
38
#include <stdarg.h>
39
#include <getopt.h>
40

41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
/**
 * IGT_EXIT_TIMEOUT:
 *
 * Exit status indicating a timeout occurred.
 */
#define IGT_EXIT_TIMEOUT 78

/**
 * IGT_EXIT_SKIP:
 *
 * Exit status indicating the test was skipped.
 */
#define IGT_EXIT_SKIP    77

/**
 * IGT_EXIT_SUCCESS
 *
 * Exit status indicating the test executed successfully.
 */
#define IGT_EXIT_SUCCESS 0

62 63 64 65 66 67 68
/**
 * IGT_EXIT_INVALID
 *
 * Exit status indicating an invalid option or subtest was specified
 */
#define IGT_EXIT_INVALID 79

69

Daniel Vetter's avatar
Daniel Vetter committed
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
bool __igt_fixture(void);
void __igt_fixture_complete(void);
void __igt_fixture_end(void) __attribute__((noreturn));
/**
 * 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 interferring with the subtest
 * enumeration (e.g. when enumerating on systemes without an intel gpu) such
 * blocks should be annotated with igt_fixture.
 */
#define igt_fixture for (int igt_tokencat(__tmpint,__LINE__) = 0; \
			 igt_tokencat(__tmpint,__LINE__) < 1 && \
			 __igt_fixture() && \
			 (setjmp(igt_subtest_jmpbuf) == 0); \
			 igt_tokencat(__tmpint,__LINE__) ++, \
			 __igt_fixture_complete())

/* subtest infrastructure */
jmp_buf igt_subtest_jmpbuf;
void igt_subtest_init(int argc, char **argv);
typedef int (*igt_opt_handler_t)(int opt, int opt_index);
94
#ifndef __GTK_DOC_IGNORE__ /* gtkdoc wants to document this forward decl */
Daniel Vetter's avatar
Daniel Vetter committed
95
struct option;
96
#endif
Daniel Vetter's avatar
Daniel Vetter committed
97 98 99 100
int igt_subtest_init_parse_opts(int argc, char **argv,
				const char *extra_short_opts,
				struct option *extra_long_opts,
				const char *help_str,
101
				igt_opt_handler_t extra_opt_handler);
Daniel Vetter's avatar
Daniel Vetter committed
102 103

bool __igt_run_subtest(const char *subtest_name);
104 105 106 107 108 109 110 111 112 113 114 115
#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)

Daniel Vetter's avatar
Daniel Vetter committed
116 117
/**
 * igt_subtest:
118
 * @name: name of the subtest
Daniel Vetter's avatar
Daniel Vetter committed
119
 *
120
 * This is a magic control flow block which denotes a subtest code block. Within
121
 * that code block igt_skip|success will only bail out of the subtest. The _f
122 123
 * variant accepts a printf format string, which is useful for constructing
 * combinatorial tests.
Daniel Vetter's avatar
Daniel Vetter committed
124
 *
125
 * This is a simpler version of igt_subtest_f()
Daniel Vetter's avatar
Daniel Vetter committed
126
 */
127 128 129
#define igt_subtest(name) for (; __igt_run_subtest((name)) && \
				   (setjmp(igt_subtest_jmpbuf) == 0); \
				   igt_success())
Daniel Vetter's avatar
Daniel Vetter committed
130 131 132 133 134 135 136 137 138 139
#define __igt_subtest_f(tmp, format...) \
	for (char tmp [256]; \
	     snprintf( tmp , sizeof( tmp ), \
		      format), \
	     __igt_run_subtest( tmp ) && \
	     (setjmp(igt_subtest_jmpbuf) == 0); \
	     igt_success())

/**
 * igt_subtest_f:
140
 * @...: format string and optional arguments
Daniel Vetter's avatar
Daniel Vetter committed
141
 *
142
 * This is a magic control flow block which denotes a subtest code block. Within
143
 * that code block igt_skip|success will only bail out of the subtest. The _f
144 145
 * variant accepts a printf format string, which is useful for constructing
 * combinatorial tests.
Daniel Vetter's avatar
Daniel Vetter committed
146
 *
147 148
 * Like igt_subtest(), but also accepts a printf format string instead of a
 * static string.
Daniel Vetter's avatar
Daniel Vetter committed
149 150 151
 */
#define igt_subtest_f(f...) \
	__igt_subtest_f(igt_tokencat(__tmpchar, __LINE__), f)
152

Daniel Vetter's avatar
Daniel Vetter committed
153
const char *igt_subtest_name(void);
154 155 156 157 158 159 160 161 162
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.
 */
Daniel Vetter's avatar
Daniel Vetter committed
163 164 165 166 167 168 169 170 171
#define igt_main \
	static void igt_tokencat(__real_main, __LINE__)(void); \
	int main(int argc, char **argv) { \
		igt_subtest_init(argc, argv); \
		igt_tokencat(__real_main, __LINE__)(); \
		igt_exit(); \
	} \
	static void igt_tokencat(__real_main, __LINE__)(void) \

172
void igt_simple_init(int argc, char **argv);
173 174 175 176 177
void igt_simple_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 extra_opt_handler);
178 179 180 181 182 183 184 185

/**
 * 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.
 */
Daniel Vetter's avatar
Daniel Vetter committed
186 187 188
#define igt_simple_main \
	static void igt_tokencat(__real_main, __LINE__)(void); \
	int main(int argc, char **argv) { \
189
		igt_simple_init(argc, argv); \
Daniel Vetter's avatar
Daniel Vetter committed
190
		igt_tokencat(__real_main, __LINE__)(); \
191
		igt_exit(); \
Daniel Vetter's avatar
Daniel Vetter committed
192 193 194 195 196 197 198 199 200
	} \
	static void igt_tokencat(__real_main, __LINE__)(void) \

__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));
201 202
#define igt_skip_check(E, F...) \
	__igt_skip_check(__FILE__, __LINE__, __func__, E, F);
Daniel Vetter's avatar
Daniel Vetter committed
203 204 205 206 207 208 209 210 211
void igt_success(void);

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));
void igt_exit(void) __attribute__((noreturn));
212

Daniel Vetter's avatar
Daniel Vetter committed
213 214
/**
 * igt_assert:
215
 * @expr: condition to test
Daniel Vetter's avatar
Daniel Vetter committed
216
 *
217
 * Fails (sub-)test if the condition is not met.
Daniel Vetter's avatar
Daniel Vetter committed
218 219 220 221 222 223 224
 *
 * Should be used everywhere where a test checks results.
 */
#define igt_assert(expr) \
	do { if (!(expr)) \
		__igt_fail_assert(99, __FILE__, __LINE__, __func__, #expr , NULL); \
	} while (0)
225 226 227 228 229 230

/**
 * igt_assert_f:
 * @expr: condition to test
 * @...: format string and optional arguments
 *
231
 * Fails (sub-)test if the condition is not met.
232 233 234 235 236 237
 *
 * 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.
 */
Daniel Vetter's avatar
Daniel Vetter committed
238 239 240 241
#define igt_assert_f(expr, f...) \
	do { if (!(expr)) \
		__igt_fail_assert(99, __FILE__, __LINE__, __func__, #expr , f); \
	} while (0)
242

243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266
/**
 * igt_fail_on:
 * @expr: condition to test
 *
 * Fails (sub-)test if the condition is met.
 *
 * Should be used everywhere where a test checks results.
 */
#define igt_fail_on(expr) igt_assert(!(expr))

/**
 * igt_assert_f:
 * @expr: condition to test
 * @...: format string and optional arguments
 *
 * 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.
 */
#define igt_fail_on_f(expr, f...) igt_assert_f(!(expr), f)

Daniel Vetter's avatar
Daniel Vetter committed
267
/**
268 269 270 271 272 273 274 275
 * 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.
Daniel Vetter's avatar
Daniel Vetter committed
276
 *
277 278
 * Like igt_assert(), but displays the values being compared on failure instead
 * of simply printing the stringified expression.
Daniel Vetter's avatar
Daniel Vetter committed
279
 */
280
#define igt_assert_cmpint(n1, cmp, ncmp, n2) \
Daniel Vetter's avatar
Daniel Vetter committed
281 282 283 284 285
	do { \
		int __n1 = (n1), __n2 = (n2); \
		if (__n1 cmp __n2) ; else \
		__igt_fail_assert(99, __FILE__, __LINE__, __func__, \
				  #n1 " " #cmp " " #n2, \
286
				  "error: %d " #ncmp " %d\n", __n1, __n2); \
287 288 289 290 291 292 293 294
	} while (0)

#define igt_assert_cmpuint(n1, cmp, ncmp, n2) \
	do { \
		uint32_t __n1 = (n1), __n2 = (n2); \
		if (__n1 cmp __n2) ; else \
		__igt_fail_assert(99, __FILE__, __LINE__, __func__, \
				  #n1 " " #cmp " " #n2, \
295
				  "error: %#x " #ncmp " %#x\n", __n1, __n2); \
Daniel Vetter's avatar
Daniel Vetter committed
296 297
	} while (0)

298 299 300 301 302 303 304 305 306 307 308
/**
 * igt_assert_eq:
 * @n1: first integer
 * @n2: second integer
 *
 * 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.
 */
309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
#define igt_assert_eq(n1, n2) igt_assert_cmpint(n1, ==, !=, n2)
#define igt_assert_eq_u32(n1, n2) igt_assert_cmpuint(n1, ==, !=, n2)

/**
 * igt_assert_neq:
 * @n1: first integer
 * @n2: second integer
 *
 * 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.
 */
#define igt_assert_neq(n1, n2) igt_assert_cmpint(n1, !=, ==, n2)

/**
 * igt_assert_lte:
 * @n1: first integer
 * @n2: second integer
 *
 * Fails (sub-)test if the second integers is greater 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.
 */
#define igt_assert_lte(n1, n2) igt_assert_cmpint(n1, <=, >, n2)
337

Daniel Vetter's avatar
Daniel Vetter committed
338 339
/**
 * igt_require:
340
 * @expr: condition to test
Daniel Vetter's avatar
Daniel Vetter committed
341
 *
342
 * Skip a (sub-)test if a condition is not met.
Daniel Vetter's avatar
Daniel Vetter committed
343
 *
344 345 346
 * 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()
Daniel Vetter's avatar
Daniel Vetter committed
347
 */
348 349 350
#define igt_require(expr) do { \
	if (!(expr)) igt_skip_check(#expr , NULL); \
} while (0)
351 352 353 354 355 356 357 358 359 360 361

/**
 * 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()
 */
362 363 364
#define igt_skip_on(expr) do { \
	if ((expr)) igt_skip_check("!(" #expr ")" , NULL); \
} while (0)
365 366 367 368 369 370 371 372 373 374 375 376 377 378 379

/**
 * 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.
 */
380 381 382
#define igt_require_f(expr, f...) do { \
	if (!(expr)) igt_skip_check(#expr , f); \
} while (0)
383 384 385 386 387 388 389 390 391 392 393 394 395 396 397

/**
 * 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.
 */
398 399 400
#define igt_skip_on_f(expr, f...) do { \
	if ((expr)) igt_skip_check(#expr , f); \
} while (0)
Daniel Vetter's avatar
Daniel Vetter committed
401 402 403

/* fork support code */
bool __igt_fork(void);
404

Daniel Vetter's avatar
Daniel Vetter committed
405 406 407 408 409
/**
 * igt_fork:
 * @child: name of the int variable with the child number
 * @num_children: number of children to fork
 *
410 411 412 413 414 415
 * 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.
Daniel Vetter's avatar
Daniel Vetter committed
416
 *
417 418
 * Note that igt_skip() will not be forwarded, feature tests need to be done
 * before spawning threads with igt_fork().
Daniel Vetter's avatar
Daniel Vetter committed
419 420 421 422 423 424
 */
#define igt_fork(child, num_children) \
	for (int child = 0; child < (num_children); child++) \
		for (; __igt_fork(); exit(0))
void igt_waitchildren(void);

425 426 427
/**
 * igt_helper_process_t:
 * @running: indicates whether the process is currently running
428
 * @use_SIGKILL: whether the helper should be terminated with SIGKILL or SIGTERM
429 430 431 432 433 434
 * @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.
 */
Daniel Vetter's avatar
Daniel Vetter committed
435 436 437 438 439 440 441
struct igt_helper_process {
	bool running;
	bool use_SIGKILL;
	pid_t pid;
	int id;
};
bool __igt_fork_helper(struct igt_helper_process *proc);
442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460

/**
 * 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.
 */
Daniel Vetter's avatar
Daniel Vetter committed
461 462
#define igt_fork_helper(proc) \
	for (; __igt_fork_helper(proc); exit(0))
463
int igt_wait_helper(struct igt_helper_process *proc);
464
void igt_stop_helper(struct igt_helper_process *proc);
Daniel Vetter's avatar
Daniel Vetter committed
465 466

/* exit handler code */
467 468 469 470 471 472 473 474 475

/**
 * 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.
 */
Daniel Vetter's avatar
Daniel Vetter committed
476 477 478 479 480 481 482 483 484 485
typedef void (*igt_exit_handler_t)(int sig);

/* reliable atexit helpers, also work when killed by a signal (if possible) */
void igt_install_exit_handler(igt_exit_handler_t fn);
void igt_enable_exit_handler(void);
void igt_disable_exit_handler(void);

/* helpers to automatically reduce test runtime in simulation */
bool igt_run_in_simulation(void);
/**
486 487 488
 * SLOW_QUICK:
 * @slow: value in simulation mode
 * @quick: value in normal mode
Daniel Vetter's avatar
Daniel Vetter committed
489
 *
490 491
 * 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.
Daniel Vetter's avatar
Daniel Vetter committed
492
 */
493 494
#define SLOW_QUICK(slow,quick) (igt_run_in_simulation() ? (quick) : (slow))

Daniel Vetter's avatar
Daniel Vetter committed
495 496 497 498 499 500 501 502 503 504 505
void igt_skip_on_simulation(void);

/* structured logging */
enum igt_log_level {
	IGT_LOG_DEBUG,
	IGT_LOG_INFO,
	IGT_LOG_WARN,
	IGT_LOG_NONE,
};
__attribute__((format(printf, 2, 3)))
void igt_log(enum igt_log_level level, const char *format, ...);
506
__attribute__((format(printf, 2, 0)))
507
void igt_vlog(enum igt_log_level level, const char *format, va_list args);
508 509 510 511 512

/**
 * igt_debug:
 * @...: format string and optional arguments
 *
513
 * Wrapper for igt_log() for message at the IGT_LOG_DEBUG level.
514
 */
Daniel Vetter's avatar
Daniel Vetter committed
515
#define igt_debug(f...) igt_log(IGT_LOG_DEBUG, f)
516 517 518 519 520

/**
 * igt_info:
 * @...: format string and optional arguments
 *
521
 * Wrapper for igt_log() for message at the IGT_LOG_INFO level.
522
 */
Daniel Vetter's avatar
Daniel Vetter committed
523
#define igt_info(f...) igt_log(IGT_LOG_INFO, f)
524 525 526 527 528

/**
 * igt_warn:
 * @...: format string and optional arguments
 *
529
 * Wrapper for igt_log() for message at the IGT_LOG_WARN level.
530
 */
Daniel Vetter's avatar
Daniel Vetter committed
531 532 533
#define igt_warn(f...) igt_log(IGT_LOG_WARN, f)
extern enum igt_log_level igt_log_level;

534 535 536 537 538 539 540 541 542 543
/**
 * 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()
 */
Daniel Vetter's avatar
Daniel Vetter committed
544 545 546 547 548
#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)
549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565

/**
 * 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.
 */
Daniel Vetter's avatar
Daniel Vetter committed
566 567 568 569 570 571 572 573 574
#define igt_warn_on_f(condition, f...) do {\
		if (condition) {\
			igt_warn("Warning on condition %s in fucntion %s, file %s:%i\n", \
				 #condition, __func__, __FILE__, __LINE__); \
			igt_warn(f); \
		} \
	} while (0)


Thomas Wood's avatar
Thomas Wood committed
575 576
void igt_set_timeout(unsigned int seconds);

Daniel Vetter's avatar
Daniel Vetter committed
577
#endif /* IGT_CORE_H */