1 /*
2 * Copyright © 2007,2014 Intel Corporation
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Software"),
6 * to deal in the Software without restriction, including without limitation
7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice (including the next
12 * paragraph) shall be included in all copies or substantial portions of the
13 * Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
18 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
21 * IN THE SOFTWARE.
22 *
23 * Authors:
24 * Eric Anholt <[email protected]>
25 * Daniel Vetter <[email protected]>
26 *
27 */
28
29
30 #ifndef IGT_CORE_H
31 #define IGT_CORE_H
32
33 #include <assert.h>
34 #include <setjmp.h>
35 #include <stdbool.h>
36 #include <stdint.h>
37 #include <stdlib.h>
38 #include <stdio.h>
39 #include <string.h>
40 #include <sys/types.h>
41 #include <stdarg.h>
42 #include <getopt.h>
43 #include <unistd.h>
44
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48
49 #ifndef IGT_LOG_DOMAIN
50 #define IGT_LOG_DOMAIN (NULL)
51 #endif
52
53
54 #ifndef STATIC_ANALYSIS_BUILD
55 #if defined(__clang_analyzer__) || defined(__COVERITY__) || defined(__KLOCWORK__)
56 #define STATIC_ANALYSIS_BUILD 1
57 #else
58 #define STATIC_ANALYSIS_BUILD 0
59 #endif
60 #endif
61
62 /**
63 * BUILD_BUG_ON_INVALID:
64 * @expr: Expression
65 *
66 * A macro that takes an expression and generates no code. Used for
67 * checking at build-time that an expression is valid code.
68 */
69 #define BUILD_BUG_ON_INVALID(e) ((void)(sizeof((long)(e))))
70
71 /**
72 * igt_assume:
73 * @expr: Condition to test
74 *
75 * An assert-like macro to be used for tautologies to give hints to
76 * static analysis of code. No-op if STATIC_ANALYSIS_BUILD is not
77 * defined, expands to an assert() if it is.
78 */
79 #if STATIC_ANALYSIS_BUILD
80 #define igt_assume(e) assert(e)
81 #else
82 /* Make sure the expression is still parsed even though it generates no code */
83 #define igt_assume(e) BUILD_BUG_ON_INVALID(e)
84 #endif
85
86 extern const char* __igt_test_description __attribute__((weak));
87 extern bool __igt_plain_output;
88 extern char *igt_frame_dump_path;
89
90 /**
91 * IGT_TEST_DESCRIPTION:
92 * @str: description string
93 *
94 * Defines a description for a test. This is used as the output for the
95 * "--help-description" option and is also included in the generated
96 * documentation.
97 */
98 #define IGT_TEST_DESCRIPTION(str) const char* __igt_test_description = str
99
100 /**
101 * IGT_EXIT_SKIP:
102 *
103 * Exit status indicating the test was skipped.
104 */
105 #define IGT_EXIT_SKIP 77
106
107 /**
108 * IGT_EXIT_SUCCESS
109 *
110 * Exit status indicating the test executed successfully.
111 */
112 #define IGT_EXIT_SUCCESS 0
113
114 /**
115 * IGT_EXIT_INVALID
116 *
117 * Exit status indicating an invalid option or subtest was specified
118 */
119 #define IGT_EXIT_INVALID 79
120
121 /**
122 * IGT_EXIT_FAILURE
123 *
124 * Exit status indicating a test failure
125 */
126 #define IGT_EXIT_FAILURE 98
127
128 bool __igt_fixture(void);
129 void __igt_fixture_complete(void);
130 void __igt_fixture_end(void) __attribute__((noreturn));
131 /**
132 * igt_fixture:
133 *
134 * Annotate global test fixture code
135 *
136 * Testcase with subtests often need to set up a bunch of global state as the
137 * common test fixture. To avoid such code interfering with the subtest
138 * enumeration (e.g. when enumerating on systems without an intel gpu) such
139 * blocks should be annotated with igt_fixture.
140 */
141 #define igt_fixture for (volatile int igt_tokencat(__tmpint,__LINE__) = 0; \
142 igt_tokencat(__tmpint,__LINE__) < 1 && \
143 (STATIC_ANALYSIS_BUILD || \
144 (__igt_fixture() && \
145 (sigsetjmp(igt_subtest_jmpbuf, 1) == 0))); \
146 igt_tokencat(__tmpint,__LINE__) ++, \
147 __igt_fixture_complete())
148
149 /* subtest infrastructure */
150 jmp_buf igt_subtest_jmpbuf;
151 typedef int (*igt_opt_handler_t)(int opt, int opt_index, void *data);
152 #define IGT_OPT_HANDLER_SUCCESS 0
153 #define IGT_OPT_HANDLER_ERROR -2
154 #ifndef __GTK_DOC_IGNORE__ /* gtkdoc wants to document this forward decl */
155 struct option;
156 #endif
157 int igt_subtest_init_parse_opts(int *argc, char **argv,
158 const char *extra_short_opts,
159 const struct option *extra_long_opts,
160 const char *help_str,
161 igt_opt_handler_t extra_opt_handler,
162 void *handler_data);
163
164
165 /**
166 * igt_subtest_init:
167 * @argc: argc from the test's main()
168 * @argv: argv from the test's main()
169 *
170 * This initializes the for tests with subtests without the need for additional
171 * command line options. It is just a simplified version of
172 * igt_subtest_init_parse_opts().
173 *
174 * If there's not a reason to the contrary it's less error prone to just use an
175 * #igt_main block instead of stitching the test's main() function together
176 * manually.
177 */
178 #define igt_subtest_init(argc, argv) \
179 igt_subtest_init_parse_opts(&argc, argv, NULL, NULL, NULL, NULL, NULL);
180
181 bool __igt_run_subtest(const char *subtest_name, const char *file, const int line);
182 #define __igt_tokencat2(x, y) x ## y
183
184 /**
185 * igt_tokencat:
186 * @x: first variable
187 * @y: second variable
188 *
189 * C preprocessor helper to concatenate two variables while properly expanding
190 * them.
191 */
192 #define igt_tokencat(x, y) __igt_tokencat2(x, y)
193
194 /**
195 * igt_subtest:
196 * @name: name of the subtest
197 *
198 * This is a magic control flow block which denotes a subtest code block. Within
199 * that code block igt_skip|success will only bail out of the subtest. The _f
200 * variant accepts a printf format string, which is useful for constructing
201 * combinatorial tests.
202 *
203 * This is a simpler version of igt_subtest_f()
204 */
205 #define igt_subtest(name) for (; __igt_run_subtest((name), __FILE__, __LINE__) && \
206 (sigsetjmp(igt_subtest_jmpbuf, 1) == 0); \
207 igt_success())
208 #define __igt_subtest_f(tmp, format...) \
209 for (char tmp [256]; \
210 snprintf( tmp , sizeof( tmp ), \
211 format), \
212 __igt_run_subtest(tmp, __FILE__, __LINE__) && \
213 (sigsetjmp(igt_subtest_jmpbuf, 1) == 0); \
214 igt_success())
215
216 /**
217 * igt_subtest_f:
218 * @...: format string and optional arguments
219 *
220 * This is a magic control flow block which denotes a subtest code block. Within
221 * that code block igt_skip|success will only bail out of the subtest. The _f
222 * variant accepts a printf format string, which is useful for constructing
223 * combinatorial tests.
224 *
225 * Like igt_subtest(), but also accepts a printf format string instead of a
226 * static string.
227 */
228 #define igt_subtest_f(f...) \
229 __igt_subtest_f(igt_tokencat(__tmpchar, __LINE__), f)
230
231 const char *igt_subtest_name(void);
232 bool igt_only_list_subtests(void);
233
234 void __igt_subtest_group_save(int *, int *);
235 void __igt_subtest_group_restore(int, int);
236 /**
237 * igt_subtest_group:
238 *
239 * Group a set of subtests together with their common setup code
240 *
241 * Testcase with subtests often need to set up a bunch of shared state as the
242 * common test fixture. But if there are multiple with different requirements
243 * the commont setup code can't be extracted, since a test condition failure in
244 * e.g. igt_require() would result in all subsequent tests skipping. Even those
245 * from a different group.
246 *
247 * This macro allows to group together a set of #igt_fixture and #igt_subtest
248 * clauses. If any common setup in a fixture fails, only the subtests in this
249 * group will fail or skip. Subtest groups can be arbitrarily nested.
250 */
251 #define igt_subtest_group for (int igt_tokencat(__tmpint,__LINE__) = 0, \
252 igt_tokencat(__save,__LINE__) = 0, \
253 igt_tokencat(__desc,__LINE__) = 0; \
254 igt_tokencat(__tmpint,__LINE__) < 1 && \
255 (__igt_subtest_group_save(& igt_tokencat(__save,__LINE__), \
256 & igt_tokencat(__desc,__LINE__) ), true); \
257 igt_tokencat(__tmpint,__LINE__) ++, \
258 __igt_subtest_group_restore(igt_tokencat(__save,__LINE__), \
259 igt_tokencat(__desc,__LINE__)))
260
261 /**
262 * igt_main_args:
263 * @extra_short_opts: getopt_long() compliant list with additional short options
264 * @extra_long_opts: getopt_long() compliant list with additional long options
265 * @help_str: help string for the additional options
266 * @extra_opt_handler: handler for the additional options
267 * @handler_data: user data given to @extra_opt_handler when invoked
268 *
269 * This is a magic control flow block used instead of a main()
270 * function for tests with subtests, along with custom command line
271 * arguments. The macro parameters are passed directly to
272 * #igt_subtest_init_parse_opts.
273 */
274 #define igt_main_args(short_opts, long_opts, help_str, opt_handler, handler_data) \
275 static void igt_tokencat(__real_main, __LINE__)(void); \
276 int main(int argc, char **argv) { \
277 igt_subtest_init_parse_opts(&argc, argv, \
278 short_opts, long_opts, help_str, \
279 opt_handler, handler_data); \
280 igt_tokencat(__real_main, __LINE__)(); \
281 igt_exit(); \
282 } \
283 static void igt_tokencat(__real_main, __LINE__)(void) \
284
285
286 /**
287 * igt_main:
288 *
289 * This is a magic control flow block used instead of a main() function for
290 * tests with subtests. Open-coding the main() function is not recommended.
291 */
292 #define igt_main igt_main_args(NULL, NULL, NULL, NULL, NULL)
293
294 const char *igt_test_name(void);
295 void igt_simple_init_parse_opts(int *argc, char **argv,
296 const char *extra_short_opts,
297 const struct option *extra_long_opts,
298 const char *help_str,
299 igt_opt_handler_t extra_opt_handler,
300 void *handler_data);
301
302 /**
303 * igt_simple_init:
304 * @argc: argc from the test's main()
305 * @argv: argv from the test's main()
306 *
307 * This initializes a simple test without any support for subtests.
308 *
309 * If there's not a reason to the contrary it's less error prone to just use an
310 * #igt_simple_main block instead of stitching the test's main() function together
311 * manually.
312 */
313 #define igt_simple_init(argc, argv) \
314 igt_simple_init_parse_opts(&argc, argv, NULL, NULL, NULL, NULL, NULL);
315
316
317 /**
318 * igt_simple_main_args:
319 * @extra_short_opts: getopt_long() compliant list with additional short options
320 * @extra_long_opts: getopt_long() compliant list with additional long options
321 * @help_str: help string for the additional options
322 * @extra_opt_handler: handler for the additional options
323 * @handler_data: user data given to @extra_opt_handler when invoked
324 *
325 * This is a magic control flow block used instead of a main()
326 * function for simple tests with custom command line arguments. The
327 * macro parameters are passed directly to
328 * #igt_simple_init_parse_opts.
329 */
330 #define igt_simple_main_args(short_opts, long_opts, help_str, opt_handler, handler_data) \
331 static void igt_tokencat(__real_main, __LINE__)(void); \
332 int main(int argc, char **argv) { \
333 igt_simple_init_parse_opts(&argc, argv, \
334 short_opts, long_opts, help_str, \
335 opt_handler, handler_data); \
336 igt_tokencat(__real_main, __LINE__)(); \
337 igt_exit(); \
338 } \
339 static void igt_tokencat(__real_main, __LINE__)(void) \
340
341
342 /**
343 * igt_simple_main:
344 *
345 * This is a magic control flow block used instead of a main() function for
346 * simple tests. Open-coding the main() function is not recommended.
347 */
348 #define igt_simple_main igt_simple_main_args(NULL, NULL, NULL, NULL, NULL)
349
350 /**
351 * igt_constructor:
352 *
353 * Convenience macro to run the provided code block when igt first starts,
354 * before any tests have been run. This should be used for parts of the igt
355 * library that require initialization of objects with global context.
356 *
357 * This code block will be executed exactly once.
358 */
359 #define igt_constructor \
360 __attribute__((constructor)) \
361 static void igt_tokencat(__igt_constructor_l, __LINE__)(void)
362
363 __attribute__((format(printf, 1, 2)))
364 void igt_skip(const char *f, ...) __attribute__((noreturn));
365 __attribute__((format(printf, 5, 6)))
366 void __igt_skip_check(const char *file, const int line,
367 const char *func, const char *check,
368 const char *format, ...) __attribute__((noreturn));
369 #define igt_skip_check(E, F...) \
370 __igt_skip_check(__FILE__, __LINE__, __func__, E, F)
371 void igt_success(void);
372
373 bool igt_can_fail(void);
374
375 void igt_fail(int exitcode) __attribute__((noreturn));
376 __attribute__((format(printf, 6, 7)))
377 void __igt_fail_assert(const char *domain, const char *file,
378 const int line, const char *func, const char *assertion,
379 const char *format, ...)
380 __attribute__((noreturn));
381 void igt_exit(void) __attribute__((noreturn));
382 void igt_fatal_error(void) __attribute__((noreturn));
383
384 /**
385 * igt_ignore_warn:
386 * @expr: condition to ignore
387 *
388 *
389 * Stops the compiler warning about an unused return value.
390 */
igt_ignore_warn(bool value)391 static inline void igt_ignore_warn(bool value)
392 {
393 }
394
395 __attribute__((format(printf, 1, 2)))
396 void igt_describe_f(const char *fmt, ...);
397
398 /**
399 * igt_describe:
400 * @dsc: string containing description
401 *
402 * Attach a description to the following #igt_subtest or #igt_subtest_group
403 * block.
404 *
405 * The description should complement the test/subtest name and provide more
406 * context on what is being tested. It should explain the idea of the test and
407 * do not mention implementation details, so that it never goes out of date.
408 *
409 * DO:
410 * * focus on the userspace's perspective
411 * * try to capture the reason for the test's existence
412 * * be brief
413 *
414 * DON'T:
415 * * try to translate the code into English
416 * * explain all the checks the test does
417 * * delve on the implementation
418 *
419 * Good examples:
420 * * "make sure that legacy cursor updates do not stall atomic commits"
421 * * "check that atomic updates of many planes are indeed atomic and take
422 * effect immediately after the commit"
423 * * "make sure that the meta-data exposed by the kernel to the userspace
424 * is correct and matches the used EDID"
425 *
426 * Bad examples:
427 * * "spawn 10 threads, each pinning cpu core with a busy loop..."
428 * * "randomly generate holes in a primary plane then try to cover each hole
429 * with a plane and make sure that CRC matches, do 25 gazillion rounds of
430 * that..."
431 *
432 *
433 * Resulting #igt_subtest documentation is a concatenation of its own
434 * description and all the parenting #igt_subtest_group descriptions, starting
435 * from the outermost one. Example:
436 *
437 * |[<!-- language="C" -->
438 * #include "igt.h"
439 *
440 * IGT_TEST_DESCRIPTION("Global description of the whole binary");
441 * igt_main
442 * {
443 * igt_describe("Desc of the subgroup with A and B");
444 * igt_subtest_group {
445 * igt_describe("Desc of the subtest A");
446 * igt_subtest("subtest-a") {
447 * ...
448 * }
449 *
450 * igt_describe("Desc of the subtest B");
451 * igt_subtest("subtest-b") {
452 * ...
453 * }
454 * }
455 *
456 * igt_describe("Desc of the subtest C");
457 * igt_subtest("subtest-c") {
458 * ...
459 * }
460 * }
461 * ]|
462 *
463 * It's will accessible via --describe command line switch:
464 *
465 * |[
466 * $ test --describe
467 * Global description of the whole binary
468 *
469 * SUB subtest-a test.c:5:
470 * Desc of the subgroup with A and B
471 *
472 * Desc of the subtest A
473 *
474 * SUB subtest-b test.c:10:
475 * Desc of the subgroup with A and B
476 *
477 * Desc of the subtest B
478 *
479 * SUB subtest-c test.c:15:
480 * Desc of the subtest C
481 * ]|
482 *
483 * Every single #igt_subtest does not have to be preceded with a #igt_describe
484 * as long as it has good-enough explanation provided on the #igt_subtest_group
485 * level.
486 *
487 * Example:
488 *
489 * |[<!-- language="C" -->
490 * #include "igt.h"
491 *
492 * igt_main
493 * {
494 * igt_describe("check xyz with different tilings");
495 * igt_subtest_group {
496 * // no need for extra description, group is enough and tiling is
497 * // obvious from the test name
498 * igt_subtest("foo-tiling-x") {
499 * ...
500 * }
501 *
502 * igt_subtest("foo-tiling-y") {
503 * ...
504 * }
505 * }
506 * }
507 * ]|
508 *
509 */
510 #define igt_describe(dsc) \
511 igt_describe_f("%s", dsc)
512
513 /**
514 * igt_assert:
515 * @expr: condition to test
516 *
517 * Fails (sub-)test if the condition is not met.
518 *
519 * Should be used everywhere where a test checks results.
520 */
521 #define igt_assert(expr) \
522 do { if (!(expr)) \
523 __igt_fail_assert(IGT_LOG_DOMAIN, __FILE__, __LINE__, __func__, #expr , NULL); \
524 } while (0)
525
526 /**
527 * igt_assert_f:
528 * @expr: condition to test
529 * @...: format string and optional arguments
530 *
531 * Fails (sub-)test if the condition is not met.
532 *
533 * Should be used everywhere where a test checks results.
534 *
535 * In addition to the plain igt_assert() helper this allows to print additional
536 * information to help debugging test failures.
537 */
538 #define igt_assert_f(expr, f...) \
539 do { if (!(expr)) \
540 __igt_fail_assert(IGT_LOG_DOMAIN, __FILE__, __LINE__, __func__, #expr , f); \
541 } while (0)
542
543 /**
544 * igt_fail_on:
545 * @expr: condition to test
546 *
547 * Fails (sub-)test if the condition is met.
548 *
549 * Should be used everywhere where a test checks results.
550 */
551 #define igt_fail_on(expr) igt_assert(!(expr))
552
553 /**
554 * igt_fail_on_f:
555 * @expr: condition to test
556 * @...: format string and optional arguments
557 *
558 * Fails (sub-)test if the condition is met.
559 *
560 * Should be used everywhere where a test checks results.
561 *
562 * In addition to the plain igt_assert() helper this allows to print additional
563 * information to help debugging test failures.
564 */
565 #define igt_fail_on_f(expr, f...) igt_assert_f(!(expr), f)
566
567 /**
568 * igt_assert_cmpint:
569 * @n1: first value
570 * @cmp: compare operator
571 * @ncmp: negated version of @cmp
572 * @n2: second value
573 *
574 * Fails (sub-)test if the condition is not met
575 *
576 * Should be used everywhere where a test compares two integer values.
577 *
578 * Like igt_assert(), but displays the values being compared on failure instead
579 * of simply printing the stringified expression.
580 */
581 #define igt_assert_cmpint(n1, cmp, ncmp, n2) \
582 do { \
583 int __n1 = (n1), __n2 = (n2); \
584 if (__n1 cmp __n2) ; else \
585 __igt_fail_assert(IGT_LOG_DOMAIN, __FILE__, __LINE__, __func__, \
586 #n1 " " #cmp " " #n2, \
587 "error: %d " #ncmp " %d\n", __n1, __n2); \
588 } while (0)
589
590 /**
591 * igt_assert_cmpuint:
592 * @n1: first value
593 * @cmp: compare operator
594 * @ncmp: negated version of @cmp
595 * @n2: second value
596 *
597 * Like igt_assert_cmpint(), but for unsigned ints.
598 */
599 #define igt_assert_cmpuint(n1, cmp, ncmp, n2) \
600 do { \
601 uint32_t __n1 = (n1), __n2 = (n2); \
602 if (__n1 cmp __n2) ; else \
603 __igt_fail_assert(IGT_LOG_DOMAIN, __FILE__, __LINE__, __func__, \
604 #n1 " " #cmp " " #n2, \
605 "error: %#x " #ncmp " %#x\n", __n1, __n2); \
606 } while (0)
607
608 /**
609 * igt_assert_cmps64:
610 * @n1: first value
611 * @cmp: compare operator
612 * @ncmp: negated version of @cmp
613 * @n2: second value
614 *
615 * Like igt_assert_cmpuint(), but for larger signed ints.
616 */
617 #define igt_assert_cmps64(n1, cmp, ncmp, n2) \
618 do { \
619 int64_t __n1 = (n1), __n2 = (n2); \
620 if (__n1 cmp __n2) ; else \
621 __igt_fail_assert(IGT_LOG_DOMAIN, __FILE__, __LINE__, __func__, \
622 #n1 " " #cmp " " #n2, \
623 "error: %lld " #ncmp " %lld\n", (long long)__n1, (long long)__n2); \
624 } while (0)
625
626 /**
627 * igt_assert_cmpu64:
628 * @n1: first value
629 * @cmp: compare operator
630 * @ncmp: negated version of @cmp
631 * @n2: second value
632 *
633 * Like igt_assert_cmpuint(), but for larger ints.
634 */
635 #define igt_assert_cmpu64(n1, cmp, ncmp, n2) \
636 do { \
637 uint64_t __n1 = (n1), __n2 = (n2); \
638 if (__n1 cmp __n2) ; else \
639 __igt_fail_assert(IGT_LOG_DOMAIN, __FILE__, __LINE__, __func__, \
640 #n1 " " #cmp " " #n2, \
641 "error: %#llx " #ncmp " %#llx\n", (long long)__n1, (long long)__n2); \
642 } while (0)
643
644 /**
645 * igt_assert_cmpdouble:
646 * @n1: first value
647 * @cmp: compare operator
648 * @ncmp: negated version of @cmp
649 * @n2: second value
650 *
651 * Like igt_assert_cmpint(), but for doubles.
652 */
653 #define igt_assert_cmpdouble(n1, cmp, ncmp, n2) \
654 do { \
655 double __n1 = (n1), __n2 = (n2); \
656 if (__n1 cmp __n2) ; else \
657 __igt_fail_assert(IGT_LOG_DOMAIN, __FILE__, __LINE__, __func__, \
658 #n1 " " #cmp " " #n2, \
659 "error: %#lf " #ncmp " %#lf\n", __n1, __n2); \
660 } while (0)
661
662 /**
663 * igt_assert_eq:
664 * @n1: first integer
665 * @n2: second integer
666 *
667 * Fails (sub-)test if the two integers are not equal. Beware that for now this
668 * only works on integers.
669 *
670 * Like igt_assert(), but displays the values being compared on failure instead
671 * of simply printing the stringified expression.
672 */
673 #define igt_assert_eq(n1, n2) igt_assert_cmpint(n1, ==, !=, n2)
674
675 /**
676 * igt_assert_eq_u32:
677 * @n1: first integer
678 * @n2: second integer
679 *
680 * Like igt_assert_eq(), but for uint32_t.
681 */
682 #define igt_assert_eq_u32(n1, n2) igt_assert_cmpuint(n1, ==, !=, n2)
683
684 /**
685 * igt_assert_eq_s64:
686 * @n1: first integer
687 * @n2: second integer
688 *
689 * Like igt_assert_eq_u32(), but for int64_t.
690 */
691 #define igt_assert_eq_s64(n1, n2) igt_assert_cmps64(n1, ==, !=, n2)
692
693 /**
694 * igt_assert_eq_u64:
695 * @n1: first integer
696 * @n2: second integer
697 *
698 * Like igt_assert_eq_u32(), but for uint64_t.
699 */
700 #define igt_assert_eq_u64(n1, n2) igt_assert_cmpu64(n1, ==, !=, n2)
701
702 /**
703 * igt_assert_eq_double:
704 * @n1: first double
705 * @n2: second double
706 *
707 * Like igt_assert_eq(), but for doubles.
708 */
709 #define igt_assert_eq_double(n1, n2) igt_assert_cmpdouble(n1, ==, !=, n2)
710
711 /**
712 * igt_assert_neq:
713 * @n1: first integer
714 * @n2: second integer
715 *
716 * Fails (sub-)test if the two integers are equal. Beware that for now this
717 * only works on integers.
718 *
719 * Like igt_assert(), but displays the values being compared on failure instead
720 * of simply printing the stringified expression.
721 */
722 #define igt_assert_neq(n1, n2) igt_assert_cmpint(n1, !=, ==, n2)
723
724 /**
725 * igt_assert_neq_u32:
726 * @n1: first integer
727 * @n2: second integer
728 *
729 * Like igt_assert_neq(), but for uint32_t.
730 */
731 #define igt_assert_neq_u32(n1, n2) igt_assert_cmpuint(n1, !=, ==, n2)
732
733 /**
734 * igt_assert_neq_u64:
735 * @n1: first integer
736 * @n2: second integer
737 *
738 * Like igt_assert_neq_u32(), but for uint64_t.
739 */
740 #define igt_assert_neq_u64(n1, n2) igt_assert_cmpu64(n1, !=, ==, n2)
741
742 /**
743 * igt_assert_neq_double:
744 * @n1: first double
745 * @n2: second double
746 *
747 * Like igt_assert_neq(), but for doubles.
748 */
749 #define igt_assert_neq_double(n1, n2) igt_assert_cmpdouble(n1, !=, ==, n2)
750
751 /**
752 * igt_assert_lte:
753 * @n1: first integer
754 * @n2: second integer
755 *
756 * Fails (sub-)test if the second integer is strictly smaller than the first.
757 * Beware that for now this only works on integers.
758 *
759 * Like igt_assert(), but displays the values being compared on failure instead
760 * of simply printing the stringified expression.
761 */
762 #define igt_assert_lte(n1, n2) igt_assert_cmpint(n1, <=, >, n2)
763
764 /**
765 * igt_assert_lte_u64:
766 * @n1: first integer
767 * @n2: second integer
768 *
769 * Fails (sub-)test if the second integer is strictly smaller than the first.
770 * Beware that for now this only works on integers.
771 *
772 * Like igt_assert(), but displays the values being compared on failure instead
773 * of simply printing the stringified expression.
774 */
775 #define igt_assert_lte_u64(n1, n2) igt_assert_cmpu64(n1, <=, >, n2)
776
777 /**
778 * igt_assert_lte_s64:
779 * @n1: first integer
780 * @n2: second integer
781 *
782 * Fails (sub-)test if the second integer is strictly smaller than the first.
783 * Beware that for now this only works on integers.
784 *
785 * Like igt_assert(), but displays the values being compared on failure instead
786 * of simply printing the stringified expression.
787 */
788 #define igt_assert_lte_s64(n1, n2) igt_assert_cmps64(n1, <=, >, n2)
789
790 /**
791 * igt_assert_lt:
792 * @n1: first integer
793 * @n2: second integer
794 *
795 * Fails (sub-)test if the second integer is smaller than or equal to the first.
796 * Beware that for now this only works on integers.
797 *
798 * Like igt_assert(), but displays the values being compared on failure instead
799 * of simply printing the stringified expression.
800 */
801 #define igt_assert_lt(n1, n2) igt_assert_cmpint(n1, <, >=, n2)
802
803 /**
804 * igt_assert_lt_u64:
805 * @n1: first integer
806 * @n2: second integer
807 *
808 * Fails (sub-)test if the second integer is smaller than or equal to the first.
809 * Beware that for now this only works on integers.
810 *
811 * Like igt_assert(), but displays the values being compared on failure instead
812 * of simply printing the stringified expression.
813 */
814 #define igt_assert_lt_u64(n1, n2) igt_assert_cmpu64(n1, <, >=, n2)
815
816 /**
817 * igt_assert_lt_s64:
818 * @n1: first integer
819 * @n2: second integer
820 *
821 * Fails (sub-)test if the second integer is smaller than or equal to the first.
822 * Beware that for now this only works on integers.
823 *
824 * Like igt_assert(), but displays the values being compared on failure instead
825 * of simply printing the stringified expression.
826 */
827 #define igt_assert_lt_s64(n1, n2) igt_assert_cmps64(n1, <, >=, n2)
828
829 /**
830 * igt_assert_fd:
831 * @fd: file descriptor
832 *
833 * Fails (sub-) test if the given file descriptor is invalid.
834 *
835 * Like igt_assert(), but displays the values being compared on failure instead
836 * of simply printing the stringified expression.
837 */
838 #define igt_assert_fd(fd) \
839 igt_assert_f(fd >= 0, "file descriptor " #fd " failed\n");
840
841 /**
842 * igt_require:
843 * @expr: condition to test
844 *
845 * Skip a (sub-)test if a condition is not met.
846 *
847 * Should be used everywhere where a test checks results to decide about
848 * skipping. This is useful to streamline the skip logic since it allows for a more flat
849 * code control flow, similar to igt_assert()
850 */
851 #define igt_require(expr) do { \
852 if (!(expr)) igt_skip_check(#expr , NULL); \
853 else igt_debug("Test requirement passed: %s\n", #expr); \
854 } while (0)
855
856 /**
857 * igt_skip_on:
858 * @expr: condition to test
859 *
860 * Skip a (sub-)test if a condition is met.
861 *
862 * Should be used everywhere where a test checks results to decide about
863 * skipping. This is useful to streamline the skip logic since it allows for a more flat
864 * code control flow, similar to igt_assert()
865 */
866 #define igt_skip_on(expr) do { \
867 if ((expr)) igt_skip_check("!(" #expr ")" , NULL); \
868 else igt_debug("Test requirement passed: !(%s)\n", #expr); \
869 } while (0)
870
871 /**
872 * igt_require_f:
873 * @expr: condition to test
874 * @...: format string and optional arguments
875 *
876 * Skip a (sub-)test if a condition is not met.
877 *
878 * Should be used everywhere where a test checks results to decide about
879 * skipping. This is useful to streamline the skip logic since it allows for a more flat
880 * code control flow, similar to igt_assert()
881 *
882 * In addition to the plain igt_require() helper this allows to print additional
883 * information to help debugging test failures.
884 */
885 #define igt_require_f(expr, f...) do { \
886 if (!(expr)) igt_skip_check(#expr , f); \
887 else igt_debug("Test requirement passed: %s\n", #expr); \
888 } while (0)
889
890 /**
891 * igt_skip_on_f:
892 * @expr: condition to test
893 * @...: format string and optional arguments
894 *
895 * Skip a (sub-)test if a condition is met.
896 *
897 * Should be used everywhere where a test checks results to decide about
898 * skipping. This is useful to streamline the skip logic since it allows for a more flat
899 * code control flow, similar to igt_assert()
900 *
901 * In addition to the plain igt_skip_on() helper this allows to print additional
902 * information to help debugging test failures.
903 */
904 #define igt_skip_on_f(expr, f...) do { \
905 if ((expr)) igt_skip_check("!("#expr")", f); \
906 else igt_debug("Test requirement passed: !(%s)\n", #expr); \
907 } while (0)
908
909 /* fork support code */
910 bool __igt_fork(void);
911
912 /**
913 * igt_fork:
914 * @child: name of the int variable with the child number
915 * @num_children: number of children to fork
916 *
917 * This is a magic control flow block which spawns parallel test threads with
918 * fork().
919 *
920 * The test children execute in parallel to the main test thread. Joining all
921 * test threads should be done with igt_waitchildren to ensure that the exit
922 * codes of all children are properly reflected in the test status.
923 *
924 * Note that igt_skip() will not be forwarded, feature tests need to be done
925 * before spawning threads with igt_fork().
926 */
927 #define igt_fork(child, num_children) \
928 for (int child = 0; child < (num_children); child++) \
929 for (; __igt_fork(); exit(0))
930 int __igt_waitchildren(void);
931 void igt_waitchildren(void);
932 void igt_waitchildren_timeout(int seconds, const char *reason);
933
934 /**
935 * igt_helper_process:
936 * @running: indicates whether the process is currently running
937 * @use_SIGKILL: whether the helper should be terminated with SIGKILL or SIGTERM
938 * @pid: pid of the helper if @running is true
939 * @id: internal id
940 *
941 * Tracking structure for helper processes. Users of the i-g-t library should
942 * only set @use_SIGKILL directly.
943 */
944 struct igt_helper_process {
945 bool running;
946 bool use_SIGKILL;
947 pid_t pid;
948 int id;
949 };
950 bool __igt_fork_helper(struct igt_helper_process *proc);
951
952 /**
953 * igt_fork_helper:
954 * @proc: #igt_helper_process structure
955 *
956 * This is a magic control flow block which denotes an asynchronous helper
957 * process block. The difference compared to igt_fork() is that failures from
958 * the child process will not be forwarded, making this construct more suitable
959 * for background processes. Common use cases are regular interference of the
960 * main test thread through e.g. sending signals or evicting objects through
961 * debugfs. Through the explicit #igt_helper_process they can also be controlled
962 * in a more fine-grained way than test children spawned through igt_fork().
963 *
964 * For tests with subtest helper process can be started outside of a
965 * #igt_subtest block.
966 *
967 * Calling igt_wait_helper() joins a helper process and igt_stop_helper()
968 * forcefully terminates it.
969 */
970 #define igt_fork_helper(proc) \
971 for (; __igt_fork_helper(proc); exit(0))
972 int igt_wait_helper(struct igt_helper_process *proc);
973 void igt_stop_helper(struct igt_helper_process *proc);
974
975 /* exit handler code */
976
977 /**
978 * igt_exit_handler_t:
979 * @sig: Signal number which caused the exit or 0.
980 *
981 * Exit handler type used by igt_install_exit_handler(). Note that exit handlers
982 * can potentially be run from signal handling contexts, the @sig parameter can
983 * be used to figure this out and act accordingly.
984 */
985 typedef void (*igt_exit_handler_t)(int sig);
986
987 /* reliable atexit helpers, also work when killed by a signal (if possible) */
988 void igt_install_exit_handler(igt_exit_handler_t fn);
989
990 /* helpers to automatically reduce test runtime in simulation */
991 bool igt_run_in_simulation(void);
992 /**
993 * SLOW_QUICK:
994 * @slow: value in simulation mode
995 * @quick: value in normal mode
996 *
997 * Simple macro to select between two values (e.g. number of test rounds or test
998 * buffer size) depending upon whether i-g-t is run in simulation mode or not.
999 */
1000 #define SLOW_QUICK(slow,quick) (igt_run_in_simulation() ? (quick) : (slow))
1001
1002 void igt_skip_on_simulation(void);
1003
1004 extern const char *igt_interactive_debug;
1005 extern bool igt_skip_crc_compare;
1006
1007 /**
1008 * igt_log_level:
1009 * @IGT_LOG_DEBUG: debug information, not printed by default
1010 * @IGT_LOG_INFO: informational message, printed by default
1011 * @IGT_LOG_WARN: non-fatal warnings which should be treated as test failures
1012 * @IGT_LOG_CRITICAL: critical errors which lead to immediate termination of tests
1013 * @IGT_LOG_NONE: unused
1014 *
1015 * Log levels used by functions like igt_log().
1016 */
1017 enum igt_log_level {
1018 IGT_LOG_DEBUG,
1019 IGT_LOG_INFO,
1020 IGT_LOG_WARN,
1021 IGT_LOG_CRITICAL,
1022 IGT_LOG_NONE,
1023 };
1024 __attribute__((format(printf, 3, 4)))
1025 void igt_log(const char *domain, enum igt_log_level level, const char *format, ...);
1026 __attribute__((format(printf, 3, 0)))
1027 void igt_vlog(const char *domain, enum igt_log_level level, const char *format, va_list args);
1028
1029 /**
1030 * igt_debug:
1031 * @...: format string and optional arguments
1032 *
1033 * Wrapper for igt_log() for message at the IGT_LOG_DEBUG level.
1034 */
1035 #define igt_debug(f...) igt_log(IGT_LOG_DOMAIN, IGT_LOG_DEBUG, f)
1036
1037 /**
1038 * igt_info:
1039 * @...: format string and optional arguments
1040 *
1041 * Wrapper for igt_log() for message at the IGT_LOG_INFO level.
1042 */
1043 #define igt_info(f...) igt_log(IGT_LOG_DOMAIN, IGT_LOG_INFO, f)
1044
1045 /**
1046 * igt_warn:
1047 * @...: format string and optional arguments
1048 *
1049 * Wrapper for igt_log() for message at the IGT_LOG_WARN level.
1050 */
1051 #define igt_warn(f...) igt_log(IGT_LOG_DOMAIN, IGT_LOG_WARN, f)
1052
1053 /**
1054 * igt_critical:
1055 * @...: format string and optional arguments
1056 *
1057 * Wrapper for igt_log() for message at the IGT_LOG_CRITICAL level.
1058 */
1059 #define igt_critical(f...) igt_log(IGT_LOG_DOMAIN, IGT_LOG_CRITICAL, f)
1060
1061 typedef bool (*igt_buffer_log_handler_t)(const char *line, void *data);
1062 void igt_log_buffer_inspect(igt_buffer_log_handler_t check, void *data);
1063
1064 extern enum igt_log_level igt_log_level;
1065
1066 /**
1067 * igt_warn_on:
1068 * @condition: condition to test
1069 *
1070 * Print a IGT_LOG_WARN level message if a condition is not met.
1071 *
1072 * Should be used everywhere where a test checks results to decide about
1073 * printing warnings. This is useful to streamline the test logic since it
1074 * allows for a more flat code control flow, similar to igt_assert()
1075 *
1076 * This macro also returns the value of @condition.
1077 */
1078 #define igt_warn_on(condition) ({ \
1079 typeof(condition) ret__ = (condition); \
1080 if (ret__) \
1081 igt_warn("Warning on condition %s in function %s, file %s:%i\n", \
1082 #condition, __func__, __FILE__, __LINE__); \
1083 ret__; \
1084 })
1085
1086 /**
1087 * igt_warn_on_f:
1088 * @condition: condition to test
1089 * @...: format string and optional arguments
1090 *
1091 * Skip a (sub-)test if a condition is not met.
1092 *
1093 * Print a IGT_LOG_WARN level message if a condition is not met.
1094 *
1095 * Should be used everywhere where a test checks results to decide about
1096 * printing warnings. This is useful to streamline the test logic since it
1097 * allows for a more flat code control flow, similar to igt_assert()
1098 *
1099 * In addition to the plain igt_warn_on_f() helper this allows to print
1100 * additional information (again as warnings) to help debugging test failures.
1101 *
1102 * It also returns the value of @condition.
1103 */
1104 #define igt_warn_on_f(condition, f...) ({ \
1105 typeof(condition) ret__ = (condition); \
1106 if (ret__) {\
1107 igt_warn("Warning on condition %s in function %s, file %s:%i\n", \
1108 #condition, __func__, __FILE__, __LINE__); \
1109 igt_warn(f); \
1110 } \
1111 ret__; \
1112 })
1113
1114 void igt_set_timeout(unsigned int seconds,
1115 const char *op);
1116
1117 /**
1118 * igt_gettime:
1119 * @ts: current monotonic clock reading
1120 *
1121 * Reports the current time in the monotonic clock.
1122 * Returns: 0 on success, -errno on failure.
1123 */
1124 int igt_gettime(struct timespec *ts);
1125
1126 /**
1127 * igt_time_elapsed:
1128 * @then: Earlier timestamp
1129 * @now: Later timestamp
1130 *
1131 * Returns: Time between two timestamps in seconds, as a floating
1132 * point number.
1133 */
1134 double igt_time_elapsed(struct timespec *then,
1135 struct timespec *now);
1136
1137 /**
1138 * igt_nsec_elapsed:
1139 * @start: measure from this point in time
1140 *
1141 * Reports the difference in the monotonic clock from the start time
1142 * in nanoseconds. On the first invocation, start should be zeroed and will
1143 * be set by the call.
1144 *
1145 * Typical use would be:
1146 *
1147 * igt_subtest("test") {
1148 * struct timespec start = {};
1149 * while (igt_nsec_elapsed(&start) < test_timeout_ns)
1150 * do_test();
1151 * }
1152 *
1153 * A handy approximation is to use nsec >> 30 to convert to seconds,
1154 * nsec >> 20 to convert to milliseconds - the error is about 8%, acceptable
1155 * for test run times.
1156 */
1157 uint64_t igt_nsec_elapsed(struct timespec *start);
1158
1159 /**
1160 * igt_seconds_elapsed:
1161 * @start: measure from this point in time
1162 *
1163 * A wrapper around igt_nsec_elapsed that reports the approximate (8% error)
1164 * number of seconds since the start point.
1165 */
igt_seconds_elapsed(struct timespec * start)1166 static inline uint32_t igt_seconds_elapsed(struct timespec *start)
1167 {
1168 return igt_nsec_elapsed(start) >> 30;
1169 }
1170
1171 void igt_reset_timeout(void);
1172
1173 FILE *__igt_fopen_data(const char* igt_srcdir, const char* igt_datadir,
1174 const char* filename);
1175 /**
1176 * igt_fopen_data:
1177 * @filename: filename to open.
1178 *
1179 * Open a datafile for test, first try from installation directory,
1180 * then from build directory, and finally from current directory.
1181 */
1182 #define igt_fopen_data(filename) \
1183 __igt_fopen_data(IGT_SRCDIR, IGT_DATADIR, filename)
1184
1185 int igt_system(const char *command);
1186 int igt_system_quiet(const char *command);
1187 #define igt_system_cmd(status, format...) \
1188 do { \
1189 char *buf = 0; \
1190 igt_assert(asprintf(&buf, format) != -1); \
1191 status = igt_system(buf); \
1192 free(buf); \
1193 } while (0)
1194
1195 /**
1196 * igt_kmsg:
1197 * @format: printf-style format string with optional args
1198 *
1199 * Writes a message into the kernel log file (/dev/kmsg).
1200 */
1201 __attribute__((format(printf, 1, 2)))
1202 void igt_kmsg(const char *format, ...);
1203 #define KMSG_EMER "<0>[IGT] "
1204 #define KMSG_ALERT "<1>[IGT] "
1205 #define KMSG_CRIT "<2>[IGT] "
1206 #define KMSG_ERR "<3>[IGT] "
1207 #define KMSG_WARNING "<4>[IGT] "
1208 #define KMSG_NOTICE "<5>[IGT] "
1209 #define KMSG_INFO "<6>[IGT] "
1210 #define KMSG_DEBUG "<7>[IGT] "
1211
1212 #ifdef __cplusplus
1213 extern "C++" {
1214 #include <type_traits>
1215 #define READ_ONCE(x) (*(volatile std::remove_reference<decltype(x)>::type *)(&(x)))
1216 }
1217 #else
1218 #define READ_ONCE(x) (*(volatile typeof(x) *)(&(x)))
1219 #endif
1220
1221 #define MSEC_PER_SEC (1000)
1222 #define USEC_PER_SEC (1000*MSEC_PER_SEC)
1223 #define NSEC_PER_SEC (1000*USEC_PER_SEC)
1224
1225 #ifdef __cplusplus
1226 }
1227 #endif
1228
1229 #endif /* IGT_CORE_H */
1230