1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * Base unit test (KUnit) API. 4 * 5 * Copyright (C) 2019, Google LLC. 6 * Author: Brendan Higgins <brendanhiggins@google.com> 7 */ 8 9 #ifndef _KUNIT_TEST_H 10 #define _KUNIT_TEST_H 11 12 #include <kunit/assert.h> 13 #include <kunit/try-catch.h> 14 15 #include <linux/args.h> 16 #include <linux/compiler.h> 17 #include <linux/container_of.h> 18 #include <linux/err.h> 19 #include <linux/init.h> 20 #include <linux/jump_label.h> 21 #include <linux/kconfig.h> 22 #include <linux/kref.h> 23 #include <linux/list.h> 24 #include <linux/module.h> 25 #include <linux/slab.h> 26 #include <linux/spinlock.h> 27 #include <linux/string.h> 28 #include <linux/types.h> 29 30 #include <asm/rwonce.h> 31 #include <asm/sections.h> 32 33 /* Static key: true if any KUnit tests are currently running */ 34 DECLARE_STATIC_KEY_FALSE(kunit_running); 35 36 struct kunit; 37 struct string_stream; 38 39 /* Maximum size of parameter description string. */ 40 #define KUNIT_PARAM_DESC_SIZE 128 41 42 /* Maximum size of a status comment. */ 43 #define KUNIT_STATUS_COMMENT_SIZE 256 44 45 /* 46 * TAP specifies subtest stream indentation of 4 spaces, 8 spaces for a 47 * sub-subtest. See the "Subtests" section in 48 * https://node-tap.org/tap-protocol/ 49 */ 50 #define KUNIT_INDENT_LEN 4 51 #define KUNIT_SUBTEST_INDENT " " 52 #define KUNIT_SUBSUBTEST_INDENT " " 53 54 /** 55 * enum kunit_status - Type of result for a test or test suite 56 * @KUNIT_SUCCESS: Denotes the test suite has not failed nor been skipped 57 * @KUNIT_FAILURE: Denotes the test has failed. 58 * @KUNIT_SKIPPED: Denotes the test has been skipped. 59 */ 60 enum kunit_status { 61 KUNIT_SUCCESS, 62 KUNIT_FAILURE, 63 KUNIT_SKIPPED, 64 }; 65 66 /* Attribute struct/enum definitions */ 67 68 /* 69 * Speed Attribute is stored as an enum and separated into categories of 70 * speed: very_slowm, slow, and normal. These speeds are relative to 71 * other KUnit tests. 72 * 73 * Note: unset speed attribute acts as default of KUNIT_SPEED_NORMAL. 74 */ 75 enum kunit_speed { 76 KUNIT_SPEED_UNSET, 77 KUNIT_SPEED_VERY_SLOW, 78 KUNIT_SPEED_SLOW, 79 KUNIT_SPEED_NORMAL, 80 KUNIT_SPEED_MAX = KUNIT_SPEED_NORMAL, 81 }; 82 83 /* Holds attributes for each test case and suite */ 84 struct kunit_attributes { 85 enum kunit_speed speed; 86 }; 87 88 /** 89 * struct kunit_case - represents an individual test case. 90 * 91 * @run_case: the function representing the actual test case. 92 * @name: the name of the test case. 93 * @generate_params: the generator function for parameterized tests. 94 * @attr: the attributes associated with the test 95 * 96 * A test case is a function with the signature, 97 * ``void (*)(struct kunit *)`` 98 * that makes expectations and assertions (see KUNIT_EXPECT_TRUE() and 99 * KUNIT_ASSERT_TRUE()) about code under test. Each test case is associated 100 * with a &struct kunit_suite and will be run after the suite's init 101 * function and followed by the suite's exit function. 102 * 103 * A test case should be static and should only be created with the 104 * KUNIT_CASE() macro; additionally, every array of test cases should be 105 * terminated with an empty test case. 106 * 107 * Example: 108 * 109 * .. code-block:: c 110 * 111 * void add_test_basic(struct kunit *test) 112 * { 113 * KUNIT_EXPECT_EQ(test, 1, add(1, 0)); 114 * KUNIT_EXPECT_EQ(test, 2, add(1, 1)); 115 * KUNIT_EXPECT_EQ(test, 0, add(-1, 1)); 116 * KUNIT_EXPECT_EQ(test, INT_MAX, add(0, INT_MAX)); 117 * KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN)); 118 * } 119 * 120 * static struct kunit_case example_test_cases[] = { 121 * KUNIT_CASE(add_test_basic), 122 * {} 123 * }; 124 * 125 */ 126 struct kunit_case { 127 void (*run_case)(struct kunit *test); 128 const char *name; 129 const void* (*generate_params)(const void *prev, char *desc); 130 struct kunit_attributes attr; 131 132 /* private: internal use only. */ 133 enum kunit_status status; 134 char *module_name; 135 struct string_stream *log; 136 }; 137 138 static inline char *kunit_status_to_ok_not_ok(enum kunit_status status) 139 { 140 switch (status) { 141 case KUNIT_SKIPPED: 142 case KUNIT_SUCCESS: 143 return "ok"; 144 case KUNIT_FAILURE: 145 return "not ok"; 146 } 147 return "invalid"; 148 } 149 150 /** 151 * KUNIT_CASE - A helper for creating a &struct kunit_case 152 * 153 * @test_name: a reference to a test case function. 154 * 155 * Takes a symbol for a function representing a test case and creates a 156 * &struct kunit_case object from it. See the documentation for 157 * &struct kunit_case for an example on how to use it. 158 */ 159 #define KUNIT_CASE(test_name) \ 160 { .run_case = test_name, .name = #test_name, \ 161 .module_name = KBUILD_MODNAME} 162 163 /** 164 * KUNIT_CASE_ATTR - A helper for creating a &struct kunit_case 165 * with attributes 166 * 167 * @test_name: a reference to a test case function. 168 * @attributes: a reference to a struct kunit_attributes object containing 169 * test attributes 170 */ 171 #define KUNIT_CASE_ATTR(test_name, attributes) \ 172 { .run_case = test_name, .name = #test_name, \ 173 .attr = attributes, .module_name = KBUILD_MODNAME} 174 175 /** 176 * KUNIT_CASE_SLOW - A helper for creating a &struct kunit_case 177 * with the slow attribute 178 * 179 * @test_name: a reference to a test case function. 180 */ 181 182 #define KUNIT_CASE_SLOW(test_name) \ 183 { .run_case = test_name, .name = #test_name, \ 184 .attr.speed = KUNIT_SPEED_SLOW, .module_name = KBUILD_MODNAME} 185 186 /** 187 * KUNIT_CASE_PARAM - A helper for creation a parameterized &struct kunit_case 188 * 189 * @test_name: a reference to a test case function. 190 * @gen_params: a reference to a parameter generator function. 191 * 192 * The generator function:: 193 * 194 * const void* gen_params(const void *prev, char *desc) 195 * 196 * is used to lazily generate a series of arbitrarily typed values that fit into 197 * a void*. The argument @prev is the previously returned value, which should be 198 * used to derive the next value; @prev is set to NULL on the initial generator 199 * call. When no more values are available, the generator must return NULL. 200 * Optionally write a string into @desc (size of KUNIT_PARAM_DESC_SIZE) 201 * describing the parameter. 202 */ 203 #define KUNIT_CASE_PARAM(test_name, gen_params) \ 204 { .run_case = test_name, .name = #test_name, \ 205 .generate_params = gen_params, .module_name = KBUILD_MODNAME} 206 207 /** 208 * KUNIT_CASE_PARAM_ATTR - A helper for creating a parameterized &struct 209 * kunit_case with attributes 210 * 211 * @test_name: a reference to a test case function. 212 * @gen_params: a reference to a parameter generator function. 213 * @attributes: a reference to a struct kunit_attributes object containing 214 * test attributes 215 */ 216 #define KUNIT_CASE_PARAM_ATTR(test_name, gen_params, attributes) \ 217 { .run_case = test_name, .name = #test_name, \ 218 .generate_params = gen_params, \ 219 .attr = attributes, .module_name = KBUILD_MODNAME} 220 221 /** 222 * struct kunit_suite - describes a related collection of &struct kunit_case 223 * 224 * @name: the name of the test. Purely informational. 225 * @suite_init: called once per test suite before the test cases. 226 * @suite_exit: called once per test suite after all test cases. 227 * @init: called before every test case. 228 * @exit: called after every test case. 229 * @test_cases: a null terminated array of test cases. 230 * @attr: the attributes associated with the test suite 231 * 232 * A kunit_suite is a collection of related &struct kunit_case s, such that 233 * @init is called before every test case and @exit is called after every 234 * test case, similar to the notion of a *test fixture* or a *test class* 235 * in other unit testing frameworks like JUnit or Googletest. 236 * 237 * Note that @exit and @suite_exit will run even if @init or @suite_init 238 * fail: make sure they can handle any inconsistent state which may result. 239 * 240 * Every &struct kunit_case must be associated with a kunit_suite for KUnit 241 * to run it. 242 */ 243 struct kunit_suite { 244 const char name[256]; 245 int (*suite_init)(struct kunit_suite *suite); 246 void (*suite_exit)(struct kunit_suite *suite); 247 int (*init)(struct kunit *test); 248 void (*exit)(struct kunit *test); 249 struct kunit_case *test_cases; 250 struct kunit_attributes attr; 251 252 /* private: internal use only */ 253 char status_comment[KUNIT_STATUS_COMMENT_SIZE]; 254 struct dentry *debugfs; 255 struct string_stream *log; 256 int suite_init_err; 257 bool is_init; 258 }; 259 260 /* Stores an array of suites, end points one past the end */ 261 struct kunit_suite_set { 262 struct kunit_suite * const *start; 263 struct kunit_suite * const *end; 264 }; 265 266 /** 267 * struct kunit - represents a running instance of a test. 268 * 269 * @priv: for user to store arbitrary data. Commonly used to pass data 270 * created in the init function (see &struct kunit_suite). 271 * 272 * Used to store information about the current context under which the test 273 * is running. Most of this data is private and should only be accessed 274 * indirectly via public functions; the one exception is @priv which can be 275 * used by the test writer to store arbitrary data. 276 */ 277 struct kunit { 278 void *priv; 279 280 /* private: internal use only. */ 281 const char *name; /* Read only after initialization! */ 282 struct string_stream *log; /* Points at case log after initialization */ 283 struct kunit_try_catch try_catch; 284 /* param_value is the current parameter value for a test case. */ 285 const void *param_value; 286 /* param_index stores the index of the parameter in parameterized tests. */ 287 int param_index; 288 /* 289 * success starts as true, and may only be set to false during a 290 * test case; thus, it is safe to update this across multiple 291 * threads using WRITE_ONCE; however, as a consequence, it may only 292 * be read after the test case finishes once all threads associated 293 * with the test case have terminated. 294 */ 295 spinlock_t lock; /* Guards all mutable test state. */ 296 enum kunit_status status; /* Read only after test_case finishes! */ 297 /* 298 * Because resources is a list that may be updated multiple times (with 299 * new resources) from any thread associated with a test case, we must 300 * protect it with some type of lock. 301 */ 302 struct list_head resources; /* Protected by lock. */ 303 304 char status_comment[KUNIT_STATUS_COMMENT_SIZE]; 305 /* Saves the last seen test. Useful to help with faults. */ 306 struct kunit_loc last_seen; 307 }; 308 309 static inline void kunit_set_failure(struct kunit *test) 310 { 311 WRITE_ONCE(test->status, KUNIT_FAILURE); 312 } 313 314 bool kunit_enabled(void); 315 const char *kunit_action(void); 316 const char *kunit_filter_glob(void); 317 char *kunit_filter(void); 318 char *kunit_filter_action(void); 319 320 void kunit_init_test(struct kunit *test, const char *name, struct string_stream *log); 321 322 int kunit_run_tests(struct kunit_suite *suite); 323 324 size_t kunit_suite_num_test_cases(struct kunit_suite *suite); 325 326 unsigned int kunit_test_case_num(struct kunit_suite *suite, 327 struct kunit_case *test_case); 328 329 struct kunit_suite_set 330 kunit_filter_suites(const struct kunit_suite_set *suite_set, 331 const char *filter_glob, 332 char *filters, 333 char *filter_action, 334 int *err); 335 void kunit_free_suite_set(struct kunit_suite_set suite_set); 336 337 int __kunit_test_suites_init(struct kunit_suite * const * const suites, int num_suites); 338 339 void __kunit_test_suites_exit(struct kunit_suite **suites, int num_suites); 340 341 void kunit_exec_run_tests(struct kunit_suite_set *suite_set, bool builtin); 342 void kunit_exec_list_tests(struct kunit_suite_set *suite_set, bool include_attr); 343 344 struct kunit_suite_set kunit_merge_suite_sets(struct kunit_suite_set init_suite_set, 345 struct kunit_suite_set suite_set); 346 347 #if IS_BUILTIN(CONFIG_KUNIT) 348 int kunit_run_all_tests(void); 349 #else 350 static inline int kunit_run_all_tests(void) 351 { 352 return 0; 353 } 354 #endif /* IS_BUILTIN(CONFIG_KUNIT) */ 355 356 #define __kunit_test_suites(unique_array, ...) \ 357 static struct kunit_suite *unique_array[] \ 358 __aligned(sizeof(struct kunit_suite *)) \ 359 __used __section(".kunit_test_suites") = { __VA_ARGS__ } 360 361 /** 362 * kunit_test_suites() - used to register one or more &struct kunit_suite 363 * with KUnit. 364 * 365 * @__suites: a statically allocated list of &struct kunit_suite. 366 * 367 * Registers @suites with the test framework. 368 * This is done by placing the array of struct kunit_suite * in the 369 * .kunit_test_suites ELF section. 370 * 371 * When builtin, KUnit tests are all run via the executor at boot, and when 372 * built as a module, they run on module load. 373 * 374 */ 375 #define kunit_test_suites(__suites...) \ 376 __kunit_test_suites(__UNIQUE_ID(array), \ 377 ##__suites) 378 379 #define kunit_test_suite(suite) kunit_test_suites(&suite) 380 381 #define __kunit_init_test_suites(unique_array, ...) \ 382 static struct kunit_suite *unique_array[] \ 383 __aligned(sizeof(struct kunit_suite *)) \ 384 __used __section(".kunit_init_test_suites") = { __VA_ARGS__ } 385 386 /** 387 * kunit_test_init_section_suites() - used to register one or more &struct 388 * kunit_suite containing init functions or 389 * init data. 390 * 391 * @__suites: a statically allocated list of &struct kunit_suite. 392 * 393 * This functions similar to kunit_test_suites() except that it compiles the 394 * list of suites during init phase. 395 * 396 * This macro also suffixes the array and suite declarations it makes with 397 * _probe; so that modpost suppresses warnings about referencing init data 398 * for symbols named in this manner. 399 * 400 * Note: these init tests are not able to be run after boot so there is no 401 * "run" debugfs file generated for these tests. 402 * 403 * Also, do not mark the suite or test case structs with __initdata because 404 * they will be used after the init phase with debugfs. 405 */ 406 #define kunit_test_init_section_suites(__suites...) \ 407 __kunit_init_test_suites(CONCATENATE(__UNIQUE_ID(array), _probe), \ 408 ##__suites) 409 410 #define kunit_test_init_section_suite(suite) \ 411 kunit_test_init_section_suites(&suite) 412 413 #define kunit_suite_for_each_test_case(suite, test_case) \ 414 for (test_case = suite->test_cases; test_case->run_case; test_case++) 415 416 enum kunit_status kunit_suite_has_succeeded(struct kunit_suite *suite); 417 418 /** 419 * kunit_kmalloc_array() - Like kmalloc_array() except the allocation is *test managed*. 420 * @test: The test context object. 421 * @n: number of elements. 422 * @size: The size in bytes of the desired memory. 423 * @gfp: flags passed to underlying kmalloc(). 424 * 425 * Just like `kmalloc_array(...)`, except the allocation is managed by the test case 426 * and is automatically cleaned up after the test case concludes. See kunit_add_action() 427 * for more information. 428 * 429 * Note that some internal context data is also allocated with GFP_KERNEL, 430 * regardless of the gfp passed in. 431 */ 432 void *kunit_kmalloc_array(struct kunit *test, size_t n, size_t size, gfp_t gfp); 433 434 /** 435 * kunit_kmalloc() - Like kmalloc() except the allocation is *test managed*. 436 * @test: The test context object. 437 * @size: The size in bytes of the desired memory. 438 * @gfp: flags passed to underlying kmalloc(). 439 * 440 * See kmalloc() and kunit_kmalloc_array() for more information. 441 * 442 * Note that some internal context data is also allocated with GFP_KERNEL, 443 * regardless of the gfp passed in. 444 */ 445 static inline void *kunit_kmalloc(struct kunit *test, size_t size, gfp_t gfp) 446 { 447 return kunit_kmalloc_array(test, 1, size, gfp); 448 } 449 450 /** 451 * kunit_kfree() - Like kfree except for allocations managed by KUnit. 452 * @test: The test case to which the resource belongs. 453 * @ptr: The memory allocation to free. 454 */ 455 void kunit_kfree(struct kunit *test, const void *ptr); 456 457 /** 458 * kunit_kzalloc() - Just like kunit_kmalloc(), but zeroes the allocation. 459 * @test: The test context object. 460 * @size: The size in bytes of the desired memory. 461 * @gfp: flags passed to underlying kmalloc(). 462 * 463 * See kzalloc() and kunit_kmalloc_array() for more information. 464 */ 465 static inline void *kunit_kzalloc(struct kunit *test, size_t size, gfp_t gfp) 466 { 467 return kunit_kmalloc(test, size, gfp | __GFP_ZERO); 468 } 469 470 /** 471 * kunit_kcalloc() - Just like kunit_kmalloc_array(), but zeroes the allocation. 472 * @test: The test context object. 473 * @n: number of elements. 474 * @size: The size in bytes of the desired memory. 475 * @gfp: flags passed to underlying kmalloc(). 476 * 477 * See kcalloc() and kunit_kmalloc_array() for more information. 478 */ 479 static inline void *kunit_kcalloc(struct kunit *test, size_t n, size_t size, gfp_t gfp) 480 { 481 return kunit_kmalloc_array(test, n, size, gfp | __GFP_ZERO); 482 } 483 484 485 /** 486 * kunit_kfree_const() - conditionally free test managed memory 487 * @test: The test context object. 488 * @x: pointer to the memory 489 * 490 * Calls kunit_kfree() only if @x is not in .rodata section. 491 * See kunit_kstrdup_const() for more information. 492 */ 493 void kunit_kfree_const(struct kunit *test, const void *x); 494 495 /** 496 * kunit_kstrdup() - Duplicates a string into a test managed allocation. 497 * 498 * @test: The test context object. 499 * @str: The NULL-terminated string to duplicate. 500 * @gfp: flags passed to underlying kmalloc(). 501 * 502 * See kstrdup() and kunit_kmalloc_array() for more information. 503 */ 504 static inline char *kunit_kstrdup(struct kunit *test, const char *str, gfp_t gfp) 505 { 506 size_t len; 507 char *buf; 508 509 if (!str) 510 return NULL; 511 512 len = strlen(str) + 1; 513 buf = kunit_kmalloc(test, len, gfp); 514 if (buf) 515 memcpy(buf, str, len); 516 return buf; 517 } 518 519 /** 520 * kunit_kstrdup_const() - Conditionally duplicates a string into a test managed allocation. 521 * 522 * @test: The test context object. 523 * @str: The NULL-terminated string to duplicate. 524 * @gfp: flags passed to underlying kmalloc(). 525 * 526 * Calls kunit_kstrdup() only if @str is not in the rodata section. Must be freed with 527 * kunit_kfree_const() -- not kunit_kfree(). 528 * See kstrdup_const() and kunit_kmalloc_array() for more information. 529 */ 530 const char *kunit_kstrdup_const(struct kunit *test, const char *str, gfp_t gfp); 531 532 /** 533 * kunit_vm_mmap() - Allocate KUnit-tracked vm_mmap() area 534 * @test: The test context object. 535 * @file: struct file pointer to map from, if any 536 * @addr: desired address, if any 537 * @len: how many bytes to allocate 538 * @prot: mmap PROT_* bits 539 * @flag: mmap flags 540 * @offset: offset into @file to start mapping from. 541 * 542 * See vm_mmap() for more information. 543 */ 544 unsigned long kunit_vm_mmap(struct kunit *test, struct file *file, 545 unsigned long addr, unsigned long len, 546 unsigned long prot, unsigned long flag, 547 unsigned long offset); 548 549 void kunit_cleanup(struct kunit *test); 550 551 void __printf(2, 3) kunit_log_append(struct string_stream *log, const char *fmt, ...); 552 553 /** 554 * kunit_mark_skipped() - Marks @test_or_suite as skipped 555 * 556 * @test_or_suite: The test context object. 557 * @fmt: A printk() style format string. 558 * 559 * Marks the test as skipped. @fmt is given output as the test status 560 * comment, typically the reason the test was skipped. 561 * 562 * Test execution continues after kunit_mark_skipped() is called. 563 */ 564 #define kunit_mark_skipped(test_or_suite, fmt, ...) \ 565 do { \ 566 WRITE_ONCE((test_or_suite)->status, KUNIT_SKIPPED); \ 567 scnprintf((test_or_suite)->status_comment, \ 568 KUNIT_STATUS_COMMENT_SIZE, \ 569 fmt, ##__VA_ARGS__); \ 570 } while (0) 571 572 /** 573 * kunit_skip() - Marks @test_or_suite as skipped 574 * 575 * @test_or_suite: The test context object. 576 * @fmt: A printk() style format string. 577 * 578 * Skips the test. @fmt is given output as the test status 579 * comment, typically the reason the test was skipped. 580 * 581 * Test execution is halted after kunit_skip() is called. 582 */ 583 #define kunit_skip(test_or_suite, fmt, ...) \ 584 do { \ 585 kunit_mark_skipped((test_or_suite), fmt, ##__VA_ARGS__);\ 586 kunit_try_catch_throw(&((test_or_suite)->try_catch)); \ 587 } while (0) 588 589 /* 590 * printk and log to per-test or per-suite log buffer. Logging only done 591 * if CONFIG_KUNIT_DEBUGFS is 'y'; if it is 'n', no log is allocated/used. 592 */ 593 #define kunit_log(lvl, test_or_suite, fmt, ...) \ 594 do { \ 595 printk(lvl fmt, ##__VA_ARGS__); \ 596 kunit_log_append((test_or_suite)->log, fmt, \ 597 ##__VA_ARGS__); \ 598 } while (0) 599 600 #define kunit_printk(lvl, test, fmt, ...) \ 601 kunit_log(lvl, test, KUNIT_SUBTEST_INDENT "# %s: " fmt, \ 602 (test)->name, ##__VA_ARGS__) 603 604 /** 605 * kunit_info() - Prints an INFO level message associated with @test. 606 * 607 * @test: The test context object. 608 * @fmt: A printk() style format string. 609 * 610 * Prints an info level message associated with the test suite being run. 611 * Takes a variable number of format parameters just like printk(). 612 */ 613 #define kunit_info(test, fmt, ...) \ 614 kunit_printk(KERN_INFO, test, fmt, ##__VA_ARGS__) 615 616 /** 617 * kunit_warn() - Prints a WARN level message associated with @test. 618 * 619 * @test: The test context object. 620 * @fmt: A printk() style format string. 621 * 622 * Prints a warning level message. 623 */ 624 #define kunit_warn(test, fmt, ...) \ 625 kunit_printk(KERN_WARNING, test, fmt, ##__VA_ARGS__) 626 627 /** 628 * kunit_err() - Prints an ERROR level message associated with @test. 629 * 630 * @test: The test context object. 631 * @fmt: A printk() style format string. 632 * 633 * Prints an error level message. 634 */ 635 #define kunit_err(test, fmt, ...) \ 636 kunit_printk(KERN_ERR, test, fmt, ##__VA_ARGS__) 637 638 /* 639 * Must be called at the beginning of each KUNIT_*_ASSERTION(). 640 * Cf. KUNIT_CURRENT_LOC. 641 */ 642 #define _KUNIT_SAVE_LOC(test) do { \ 643 WRITE_ONCE(test->last_seen.file, __FILE__); \ 644 WRITE_ONCE(test->last_seen.line, __LINE__); \ 645 } while (0) 646 647 /** 648 * KUNIT_SUCCEED() - A no-op expectation. Only exists for code clarity. 649 * @test: The test context object. 650 * 651 * The opposite of KUNIT_FAIL(), it is an expectation that cannot fail. In other 652 * words, it does nothing and only exists for code clarity. See 653 * KUNIT_EXPECT_TRUE() for more information. 654 */ 655 #define KUNIT_SUCCEED(test) _KUNIT_SAVE_LOC(test) 656 657 void __noreturn __kunit_abort(struct kunit *test); 658 659 void __printf(6, 7) __kunit_do_failed_assertion(struct kunit *test, 660 const struct kunit_loc *loc, 661 enum kunit_assert_type type, 662 const struct kunit_assert *assert, 663 assert_format_t assert_format, 664 const char *fmt, ...); 665 666 #define _KUNIT_FAILED(test, assert_type, assert_class, assert_format, INITIALIZER, fmt, ...) do { \ 667 static const struct kunit_loc __loc = KUNIT_CURRENT_LOC; \ 668 const struct assert_class __assertion = INITIALIZER; \ 669 __kunit_do_failed_assertion(test, \ 670 &__loc, \ 671 assert_type, \ 672 &__assertion.assert, \ 673 assert_format, \ 674 fmt, \ 675 ##__VA_ARGS__); \ 676 if (assert_type == KUNIT_ASSERTION) \ 677 __kunit_abort(test); \ 678 } while (0) 679 680 681 #define KUNIT_FAIL_ASSERTION(test, assert_type, fmt, ...) do { \ 682 _KUNIT_SAVE_LOC(test); \ 683 _KUNIT_FAILED(test, \ 684 assert_type, \ 685 kunit_fail_assert, \ 686 kunit_fail_assert_format, \ 687 {}, \ 688 fmt, \ 689 ##__VA_ARGS__); \ 690 } while (0) 691 692 /** 693 * KUNIT_FAIL() - Always causes a test to fail when evaluated. 694 * @test: The test context object. 695 * @fmt: an informational message to be printed when the assertion is made. 696 * @...: string format arguments. 697 * 698 * The opposite of KUNIT_SUCCEED(), it is an expectation that always fails. In 699 * other words, it always results in a failed expectation, and consequently 700 * always causes the test case to fail when evaluated. See KUNIT_EXPECT_TRUE() 701 * for more information. 702 */ 703 #define KUNIT_FAIL(test, fmt, ...) \ 704 KUNIT_FAIL_ASSERTION(test, \ 705 KUNIT_EXPECTATION, \ 706 fmt, \ 707 ##__VA_ARGS__) 708 709 /* Helper to safely pass around an initializer list to other macros. */ 710 #define KUNIT_INIT_ASSERT(initializers...) { initializers } 711 712 #define KUNIT_UNARY_ASSERTION(test, \ 713 assert_type, \ 714 condition_, \ 715 expected_true_, \ 716 fmt, \ 717 ...) \ 718 do { \ 719 _KUNIT_SAVE_LOC(test); \ 720 if (likely(!!(condition_) == !!expected_true_)) \ 721 break; \ 722 \ 723 _KUNIT_FAILED(test, \ 724 assert_type, \ 725 kunit_unary_assert, \ 726 kunit_unary_assert_format, \ 727 KUNIT_INIT_ASSERT(.condition = #condition_, \ 728 .expected_true = expected_true_), \ 729 fmt, \ 730 ##__VA_ARGS__); \ 731 } while (0) 732 733 #define KUNIT_TRUE_MSG_ASSERTION(test, assert_type, condition, fmt, ...) \ 734 KUNIT_UNARY_ASSERTION(test, \ 735 assert_type, \ 736 condition, \ 737 true, \ 738 fmt, \ 739 ##__VA_ARGS__) 740 741 #define KUNIT_FALSE_MSG_ASSERTION(test, assert_type, condition, fmt, ...) \ 742 KUNIT_UNARY_ASSERTION(test, \ 743 assert_type, \ 744 condition, \ 745 false, \ 746 fmt, \ 747 ##__VA_ARGS__) 748 749 /* 750 * A factory macro for defining the assertions and expectations for the basic 751 * comparisons defined for the built in types. 752 * 753 * Unfortunately, there is no common type that all types can be promoted to for 754 * which all the binary operators behave the same way as for the actual types 755 * (for example, there is no type that long long and unsigned long long can 756 * both be cast to where the comparison result is preserved for all values). So 757 * the best we can do is do the comparison in the original types and then coerce 758 * everything to long long for printing; this way, the comparison behaves 759 * correctly and the printed out value usually makes sense without 760 * interpretation, but can always be interpreted to figure out the actual 761 * value. 762 */ 763 #define KUNIT_BASE_BINARY_ASSERTION(test, \ 764 assert_class, \ 765 format_func, \ 766 assert_type, \ 767 left, \ 768 op, \ 769 right, \ 770 fmt, \ 771 ...) \ 772 do { \ 773 const typeof(left) __left = (left); \ 774 const typeof(right) __right = (right); \ 775 static const struct kunit_binary_assert_text __text = { \ 776 .operation = #op, \ 777 .left_text = #left, \ 778 .right_text = #right, \ 779 }; \ 780 \ 781 _KUNIT_SAVE_LOC(test); \ 782 if (likely(__left op __right)) \ 783 break; \ 784 \ 785 _KUNIT_FAILED(test, \ 786 assert_type, \ 787 assert_class, \ 788 format_func, \ 789 KUNIT_INIT_ASSERT(.text = &__text, \ 790 .left_value = __left, \ 791 .right_value = __right), \ 792 fmt, \ 793 ##__VA_ARGS__); \ 794 } while (0) 795 796 #define KUNIT_BINARY_INT_ASSERTION(test, \ 797 assert_type, \ 798 left, \ 799 op, \ 800 right, \ 801 fmt, \ 802 ...) \ 803 KUNIT_BASE_BINARY_ASSERTION(test, \ 804 kunit_binary_assert, \ 805 kunit_binary_assert_format, \ 806 assert_type, \ 807 left, op, right, \ 808 fmt, \ 809 ##__VA_ARGS__) 810 811 #define KUNIT_BINARY_PTR_ASSERTION(test, \ 812 assert_type, \ 813 left, \ 814 op, \ 815 right, \ 816 fmt, \ 817 ...) \ 818 KUNIT_BASE_BINARY_ASSERTION(test, \ 819 kunit_binary_ptr_assert, \ 820 kunit_binary_ptr_assert_format, \ 821 assert_type, \ 822 left, op, right, \ 823 fmt, \ 824 ##__VA_ARGS__) 825 826 #define KUNIT_BINARY_STR_ASSERTION(test, \ 827 assert_type, \ 828 left, \ 829 op, \ 830 right, \ 831 fmt, \ 832 ...) \ 833 do { \ 834 const char *__left = (left); \ 835 const char *__right = (right); \ 836 static const struct kunit_binary_assert_text __text = { \ 837 .operation = #op, \ 838 .left_text = #left, \ 839 .right_text = #right, \ 840 }; \ 841 \ 842 _KUNIT_SAVE_LOC(test); \ 843 if (likely((__left) && (__right) && (strcmp(__left, __right) op 0))) \ 844 break; \ 845 \ 846 \ 847 _KUNIT_FAILED(test, \ 848 assert_type, \ 849 kunit_binary_str_assert, \ 850 kunit_binary_str_assert_format, \ 851 KUNIT_INIT_ASSERT(.text = &__text, \ 852 .left_value = __left, \ 853 .right_value = __right), \ 854 fmt, \ 855 ##__VA_ARGS__); \ 856 } while (0) 857 858 #define KUNIT_MEM_ASSERTION(test, \ 859 assert_type, \ 860 left, \ 861 op, \ 862 right, \ 863 size_, \ 864 fmt, \ 865 ...) \ 866 do { \ 867 const void *__left = (left); \ 868 const void *__right = (right); \ 869 const size_t __size = (size_); \ 870 static const struct kunit_binary_assert_text __text = { \ 871 .operation = #op, \ 872 .left_text = #left, \ 873 .right_text = #right, \ 874 }; \ 875 \ 876 _KUNIT_SAVE_LOC(test); \ 877 if (likely(__left && __right)) \ 878 if (likely(memcmp(__left, __right, __size) op 0)) \ 879 break; \ 880 \ 881 _KUNIT_FAILED(test, \ 882 assert_type, \ 883 kunit_mem_assert, \ 884 kunit_mem_assert_format, \ 885 KUNIT_INIT_ASSERT(.text = &__text, \ 886 .left_value = __left, \ 887 .right_value = __right, \ 888 .size = __size), \ 889 fmt, \ 890 ##__VA_ARGS__); \ 891 } while (0) 892 893 #define KUNIT_PTR_NOT_ERR_OR_NULL_MSG_ASSERTION(test, \ 894 assert_type, \ 895 ptr, \ 896 fmt, \ 897 ...) \ 898 do { \ 899 const typeof(ptr) __ptr = (ptr); \ 900 \ 901 _KUNIT_SAVE_LOC(test); \ 902 if (!IS_ERR_OR_NULL(__ptr)) \ 903 break; \ 904 \ 905 _KUNIT_FAILED(test, \ 906 assert_type, \ 907 kunit_ptr_not_err_assert, \ 908 kunit_ptr_not_err_assert_format, \ 909 KUNIT_INIT_ASSERT(.text = #ptr, .value = __ptr), \ 910 fmt, \ 911 ##__VA_ARGS__); \ 912 } while (0) 913 914 /** 915 * KUNIT_EXPECT_TRUE() - Causes a test failure when the expression is not true. 916 * @test: The test context object. 917 * @condition: an arbitrary boolean expression. The test fails when this does 918 * not evaluate to true. 919 * 920 * This and expectations of the form `KUNIT_EXPECT_*` will cause the test case 921 * to fail when the specified condition is not met; however, it will not prevent 922 * the test case from continuing to run; this is otherwise known as an 923 * *expectation failure*. 924 */ 925 #define KUNIT_EXPECT_TRUE(test, condition) \ 926 KUNIT_EXPECT_TRUE_MSG(test, condition, NULL) 927 928 #define KUNIT_EXPECT_TRUE_MSG(test, condition, fmt, ...) \ 929 KUNIT_TRUE_MSG_ASSERTION(test, \ 930 KUNIT_EXPECTATION, \ 931 condition, \ 932 fmt, \ 933 ##__VA_ARGS__) 934 935 /** 936 * KUNIT_EXPECT_FALSE() - Makes a test failure when the expression is not false. 937 * @test: The test context object. 938 * @condition: an arbitrary boolean expression. The test fails when this does 939 * not evaluate to false. 940 * 941 * Sets an expectation that @condition evaluates to false. See 942 * KUNIT_EXPECT_TRUE() for more information. 943 */ 944 #define KUNIT_EXPECT_FALSE(test, condition) \ 945 KUNIT_EXPECT_FALSE_MSG(test, condition, NULL) 946 947 #define KUNIT_EXPECT_FALSE_MSG(test, condition, fmt, ...) \ 948 KUNIT_FALSE_MSG_ASSERTION(test, \ 949 KUNIT_EXPECTATION, \ 950 condition, \ 951 fmt, \ 952 ##__VA_ARGS__) 953 954 /** 955 * KUNIT_EXPECT_EQ() - Sets an expectation that @left and @right are equal. 956 * @test: The test context object. 957 * @left: an arbitrary expression that evaluates to a primitive C type. 958 * @right: an arbitrary expression that evaluates to a primitive C type. 959 * 960 * Sets an expectation that the values that @left and @right evaluate to are 961 * equal. This is semantically equivalent to 962 * KUNIT_EXPECT_TRUE(@test, (@left) == (@right)). See KUNIT_EXPECT_TRUE() for 963 * more information. 964 */ 965 #define KUNIT_EXPECT_EQ(test, left, right) \ 966 KUNIT_EXPECT_EQ_MSG(test, left, right, NULL) 967 968 #define KUNIT_EXPECT_EQ_MSG(test, left, right, fmt, ...) \ 969 KUNIT_BINARY_INT_ASSERTION(test, \ 970 KUNIT_EXPECTATION, \ 971 left, ==, right, \ 972 fmt, \ 973 ##__VA_ARGS__) 974 975 /** 976 * KUNIT_EXPECT_PTR_EQ() - Expects that pointers @left and @right are equal. 977 * @test: The test context object. 978 * @left: an arbitrary expression that evaluates to a pointer. 979 * @right: an arbitrary expression that evaluates to a pointer. 980 * 981 * Sets an expectation that the values that @left and @right evaluate to are 982 * equal. This is semantically equivalent to 983 * KUNIT_EXPECT_TRUE(@test, (@left) == (@right)). See KUNIT_EXPECT_TRUE() for 984 * more information. 985 */ 986 #define KUNIT_EXPECT_PTR_EQ(test, left, right) \ 987 KUNIT_EXPECT_PTR_EQ_MSG(test, left, right, NULL) 988 989 #define KUNIT_EXPECT_PTR_EQ_MSG(test, left, right, fmt, ...) \ 990 KUNIT_BINARY_PTR_ASSERTION(test, \ 991 KUNIT_EXPECTATION, \ 992 left, ==, right, \ 993 fmt, \ 994 ##__VA_ARGS__) 995 996 /** 997 * KUNIT_EXPECT_NE() - An expectation that @left and @right are not equal. 998 * @test: The test context object. 999 * @left: an arbitrary expression that evaluates to a primitive C type. 1000 * @right: an arbitrary expression that evaluates to a primitive C type. 1001 * 1002 * Sets an expectation that the values that @left and @right evaluate to are not 1003 * equal. This is semantically equivalent to 1004 * KUNIT_EXPECT_TRUE(@test, (@left) != (@right)). See KUNIT_EXPECT_TRUE() for 1005 * more information. 1006 */ 1007 #define KUNIT_EXPECT_NE(test, left, right) \ 1008 KUNIT_EXPECT_NE_MSG(test, left, right, NULL) 1009 1010 #define KUNIT_EXPECT_NE_MSG(test, left, right, fmt, ...) \ 1011 KUNIT_BINARY_INT_ASSERTION(test, \ 1012 KUNIT_EXPECTATION, \ 1013 left, !=, right, \ 1014 fmt, \ 1015 ##__VA_ARGS__) 1016 1017 /** 1018 * KUNIT_EXPECT_PTR_NE() - Expects that pointers @left and @right are not equal. 1019 * @test: The test context object. 1020 * @left: an arbitrary expression that evaluates to a pointer. 1021 * @right: an arbitrary expression that evaluates to a pointer. 1022 * 1023 * Sets an expectation that the values that @left and @right evaluate to are not 1024 * equal. This is semantically equivalent to 1025 * KUNIT_EXPECT_TRUE(@test, (@left) != (@right)). See KUNIT_EXPECT_TRUE() for 1026 * more information. 1027 */ 1028 #define KUNIT_EXPECT_PTR_NE(test, left, right) \ 1029 KUNIT_EXPECT_PTR_NE_MSG(test, left, right, NULL) 1030 1031 #define KUNIT_EXPECT_PTR_NE_MSG(test, left, right, fmt, ...) \ 1032 KUNIT_BINARY_PTR_ASSERTION(test, \ 1033 KUNIT_EXPECTATION, \ 1034 left, !=, right, \ 1035 fmt, \ 1036 ##__VA_ARGS__) 1037 1038 /** 1039 * KUNIT_EXPECT_LT() - An expectation that @left is less than @right. 1040 * @test: The test context object. 1041 * @left: an arbitrary expression that evaluates to a primitive C type. 1042 * @right: an arbitrary expression that evaluates to a primitive C type. 1043 * 1044 * Sets an expectation that the value that @left evaluates to is less than the 1045 * value that @right evaluates to. This is semantically equivalent to 1046 * KUNIT_EXPECT_TRUE(@test, (@left) < (@right)). See KUNIT_EXPECT_TRUE() for 1047 * more information. 1048 */ 1049 #define KUNIT_EXPECT_LT(test, left, right) \ 1050 KUNIT_EXPECT_LT_MSG(test, left, right, NULL) 1051 1052 #define KUNIT_EXPECT_LT_MSG(test, left, right, fmt, ...) \ 1053 KUNIT_BINARY_INT_ASSERTION(test, \ 1054 KUNIT_EXPECTATION, \ 1055 left, <, right, \ 1056 fmt, \ 1057 ##__VA_ARGS__) 1058 1059 /** 1060 * KUNIT_EXPECT_LE() - Expects that @left is less than or equal to @right. 1061 * @test: The test context object. 1062 * @left: an arbitrary expression that evaluates to a primitive C type. 1063 * @right: an arbitrary expression that evaluates to a primitive C type. 1064 * 1065 * Sets an expectation that the value that @left evaluates to is less than or 1066 * equal to the value that @right evaluates to. Semantically this is equivalent 1067 * to KUNIT_EXPECT_TRUE(@test, (@left) <= (@right)). See KUNIT_EXPECT_TRUE() for 1068 * more information. 1069 */ 1070 #define KUNIT_EXPECT_LE(test, left, right) \ 1071 KUNIT_EXPECT_LE_MSG(test, left, right, NULL) 1072 1073 #define KUNIT_EXPECT_LE_MSG(test, left, right, fmt, ...) \ 1074 KUNIT_BINARY_INT_ASSERTION(test, \ 1075 KUNIT_EXPECTATION, \ 1076 left, <=, right, \ 1077 fmt, \ 1078 ##__VA_ARGS__) 1079 1080 /** 1081 * KUNIT_EXPECT_GT() - An expectation that @left is greater than @right. 1082 * @test: The test context object. 1083 * @left: an arbitrary expression that evaluates to a primitive C type. 1084 * @right: an arbitrary expression that evaluates to a primitive C type. 1085 * 1086 * Sets an expectation that the value that @left evaluates to is greater than 1087 * the value that @right evaluates to. This is semantically equivalent to 1088 * KUNIT_EXPECT_TRUE(@test, (@left) > (@right)). See KUNIT_EXPECT_TRUE() for 1089 * more information. 1090 */ 1091 #define KUNIT_EXPECT_GT(test, left, right) \ 1092 KUNIT_EXPECT_GT_MSG(test, left, right, NULL) 1093 1094 #define KUNIT_EXPECT_GT_MSG(test, left, right, fmt, ...) \ 1095 KUNIT_BINARY_INT_ASSERTION(test, \ 1096 KUNIT_EXPECTATION, \ 1097 left, >, right, \ 1098 fmt, \ 1099 ##__VA_ARGS__) 1100 1101 /** 1102 * KUNIT_EXPECT_GE() - Expects that @left is greater than or equal to @right. 1103 * @test: The test context object. 1104 * @left: an arbitrary expression that evaluates to a primitive C type. 1105 * @right: an arbitrary expression that evaluates to a primitive C type. 1106 * 1107 * Sets an expectation that the value that @left evaluates to is greater than 1108 * the value that @right evaluates to. This is semantically equivalent to 1109 * KUNIT_EXPECT_TRUE(@test, (@left) >= (@right)). See KUNIT_EXPECT_TRUE() for 1110 * more information. 1111 */ 1112 #define KUNIT_EXPECT_GE(test, left, right) \ 1113 KUNIT_EXPECT_GE_MSG(test, left, right, NULL) 1114 1115 #define KUNIT_EXPECT_GE_MSG(test, left, right, fmt, ...) \ 1116 KUNIT_BINARY_INT_ASSERTION(test, \ 1117 KUNIT_EXPECTATION, \ 1118 left, >=, right, \ 1119 fmt, \ 1120 ##__VA_ARGS__) 1121 1122 /** 1123 * KUNIT_EXPECT_STREQ() - Expects that strings @left and @right are equal. 1124 * @test: The test context object. 1125 * @left: an arbitrary expression that evaluates to a null terminated string. 1126 * @right: an arbitrary expression that evaluates to a null terminated string. 1127 * 1128 * Sets an expectation that the values that @left and @right evaluate to are 1129 * equal. This is semantically equivalent to 1130 * KUNIT_EXPECT_TRUE(@test, !strcmp((@left), (@right))). See KUNIT_EXPECT_TRUE() 1131 * for more information. 1132 */ 1133 #define KUNIT_EXPECT_STREQ(test, left, right) \ 1134 KUNIT_EXPECT_STREQ_MSG(test, left, right, NULL) 1135 1136 #define KUNIT_EXPECT_STREQ_MSG(test, left, right, fmt, ...) \ 1137 KUNIT_BINARY_STR_ASSERTION(test, \ 1138 KUNIT_EXPECTATION, \ 1139 left, ==, right, \ 1140 fmt, \ 1141 ##__VA_ARGS__) 1142 1143 /** 1144 * KUNIT_EXPECT_STRNEQ() - Expects that strings @left and @right are not equal. 1145 * @test: The test context object. 1146 * @left: an arbitrary expression that evaluates to a null terminated string. 1147 * @right: an arbitrary expression that evaluates to a null terminated string. 1148 * 1149 * Sets an expectation that the values that @left and @right evaluate to are 1150 * not equal. This is semantically equivalent to 1151 * KUNIT_EXPECT_TRUE(@test, strcmp((@left), (@right))). See KUNIT_EXPECT_TRUE() 1152 * for more information. 1153 */ 1154 #define KUNIT_EXPECT_STRNEQ(test, left, right) \ 1155 KUNIT_EXPECT_STRNEQ_MSG(test, left, right, NULL) 1156 1157 #define KUNIT_EXPECT_STRNEQ_MSG(test, left, right, fmt, ...) \ 1158 KUNIT_BINARY_STR_ASSERTION(test, \ 1159 KUNIT_EXPECTATION, \ 1160 left, !=, right, \ 1161 fmt, \ 1162 ##__VA_ARGS__) 1163 1164 /** 1165 * KUNIT_EXPECT_MEMEQ() - Expects that the first @size bytes of @left and @right are equal. 1166 * @test: The test context object. 1167 * @left: An arbitrary expression that evaluates to the specified size. 1168 * @right: An arbitrary expression that evaluates to the specified size. 1169 * @size: Number of bytes compared. 1170 * 1171 * Sets an expectation that the values that @left and @right evaluate to are 1172 * equal. This is semantically equivalent to 1173 * KUNIT_EXPECT_TRUE(@test, !memcmp((@left), (@right), (@size))). See 1174 * KUNIT_EXPECT_TRUE() for more information. 1175 * 1176 * Although this expectation works for any memory block, it is not recommended 1177 * for comparing more structured data, such as structs. This expectation is 1178 * recommended for comparing, for example, data arrays. 1179 */ 1180 #define KUNIT_EXPECT_MEMEQ(test, left, right, size) \ 1181 KUNIT_EXPECT_MEMEQ_MSG(test, left, right, size, NULL) 1182 1183 #define KUNIT_EXPECT_MEMEQ_MSG(test, left, right, size, fmt, ...) \ 1184 KUNIT_MEM_ASSERTION(test, \ 1185 KUNIT_EXPECTATION, \ 1186 left, ==, right, \ 1187 size, \ 1188 fmt, \ 1189 ##__VA_ARGS__) 1190 1191 /** 1192 * KUNIT_EXPECT_MEMNEQ() - Expects that the first @size bytes of @left and @right are not equal. 1193 * @test: The test context object. 1194 * @left: An arbitrary expression that evaluates to the specified size. 1195 * @right: An arbitrary expression that evaluates to the specified size. 1196 * @size: Number of bytes compared. 1197 * 1198 * Sets an expectation that the values that @left and @right evaluate to are 1199 * not equal. This is semantically equivalent to 1200 * KUNIT_EXPECT_TRUE(@test, memcmp((@left), (@right), (@size))). See 1201 * KUNIT_EXPECT_TRUE() for more information. 1202 * 1203 * Although this expectation works for any memory block, it is not recommended 1204 * for comparing more structured data, such as structs. This expectation is 1205 * recommended for comparing, for example, data arrays. 1206 */ 1207 #define KUNIT_EXPECT_MEMNEQ(test, left, right, size) \ 1208 KUNIT_EXPECT_MEMNEQ_MSG(test, left, right, size, NULL) 1209 1210 #define KUNIT_EXPECT_MEMNEQ_MSG(test, left, right, size, fmt, ...) \ 1211 KUNIT_MEM_ASSERTION(test, \ 1212 KUNIT_EXPECTATION, \ 1213 left, !=, right, \ 1214 size, \ 1215 fmt, \ 1216 ##__VA_ARGS__) 1217 1218 /** 1219 * KUNIT_EXPECT_NULL() - Expects that @ptr is null. 1220 * @test: The test context object. 1221 * @ptr: an arbitrary pointer. 1222 * 1223 * Sets an expectation that the value that @ptr evaluates to is null. This is 1224 * semantically equivalent to KUNIT_EXPECT_PTR_EQ(@test, ptr, NULL). 1225 * See KUNIT_EXPECT_TRUE() for more information. 1226 */ 1227 #define KUNIT_EXPECT_NULL(test, ptr) \ 1228 KUNIT_EXPECT_NULL_MSG(test, \ 1229 ptr, \ 1230 NULL) 1231 1232 #define KUNIT_EXPECT_NULL_MSG(test, ptr, fmt, ...) \ 1233 KUNIT_BINARY_PTR_ASSERTION(test, \ 1234 KUNIT_EXPECTATION, \ 1235 ptr, ==, NULL, \ 1236 fmt, \ 1237 ##__VA_ARGS__) 1238 1239 /** 1240 * KUNIT_EXPECT_NOT_NULL() - Expects that @ptr is not null. 1241 * @test: The test context object. 1242 * @ptr: an arbitrary pointer. 1243 * 1244 * Sets an expectation that the value that @ptr evaluates to is not null. This 1245 * is semantically equivalent to KUNIT_EXPECT_PTR_NE(@test, ptr, NULL). 1246 * See KUNIT_EXPECT_TRUE() for more information. 1247 */ 1248 #define KUNIT_EXPECT_NOT_NULL(test, ptr) \ 1249 KUNIT_EXPECT_NOT_NULL_MSG(test, \ 1250 ptr, \ 1251 NULL) 1252 1253 #define KUNIT_EXPECT_NOT_NULL_MSG(test, ptr, fmt, ...) \ 1254 KUNIT_BINARY_PTR_ASSERTION(test, \ 1255 KUNIT_EXPECTATION, \ 1256 ptr, !=, NULL, \ 1257 fmt, \ 1258 ##__VA_ARGS__) 1259 1260 /** 1261 * KUNIT_EXPECT_NOT_ERR_OR_NULL() - Expects that @ptr is not null and not err. 1262 * @test: The test context object. 1263 * @ptr: an arbitrary pointer. 1264 * 1265 * Sets an expectation that the value that @ptr evaluates to is not null and not 1266 * an errno stored in a pointer. This is semantically equivalent to 1267 * KUNIT_EXPECT_TRUE(@test, !IS_ERR_OR_NULL(@ptr)). See KUNIT_EXPECT_TRUE() for 1268 * more information. 1269 */ 1270 #define KUNIT_EXPECT_NOT_ERR_OR_NULL(test, ptr) \ 1271 KUNIT_EXPECT_NOT_ERR_OR_NULL_MSG(test, ptr, NULL) 1272 1273 #define KUNIT_EXPECT_NOT_ERR_OR_NULL_MSG(test, ptr, fmt, ...) \ 1274 KUNIT_PTR_NOT_ERR_OR_NULL_MSG_ASSERTION(test, \ 1275 KUNIT_EXPECTATION, \ 1276 ptr, \ 1277 fmt, \ 1278 ##__VA_ARGS__) 1279 1280 /** 1281 * KUNIT_FAIL_AND_ABORT() - Always causes a test to fail and abort when evaluated. 1282 * @test: The test context object. 1283 * @fmt: an informational message to be printed when the assertion is made. 1284 * @...: string format arguments. 1285 * 1286 * The opposite of KUNIT_SUCCEED(), it is an assertion that always fails. In 1287 * other words, it always results in a failed assertion, and consequently 1288 * always causes the test case to fail and abort when evaluated. 1289 * See KUNIT_ASSERT_TRUE() for more information. 1290 */ 1291 #define KUNIT_FAIL_AND_ABORT(test, fmt, ...) \ 1292 KUNIT_FAIL_ASSERTION(test, KUNIT_ASSERTION, fmt, ##__VA_ARGS__) 1293 1294 /** 1295 * KUNIT_ASSERT_TRUE() - Sets an assertion that @condition is true. 1296 * @test: The test context object. 1297 * @condition: an arbitrary boolean expression. The test fails and aborts when 1298 * this does not evaluate to true. 1299 * 1300 * This and assertions of the form `KUNIT_ASSERT_*` will cause the test case to 1301 * fail *and immediately abort* when the specified condition is not met. Unlike 1302 * an expectation failure, it will prevent the test case from continuing to run; 1303 * this is otherwise known as an *assertion failure*. 1304 */ 1305 #define KUNIT_ASSERT_TRUE(test, condition) \ 1306 KUNIT_ASSERT_TRUE_MSG(test, condition, NULL) 1307 1308 #define KUNIT_ASSERT_TRUE_MSG(test, condition, fmt, ...) \ 1309 KUNIT_TRUE_MSG_ASSERTION(test, \ 1310 KUNIT_ASSERTION, \ 1311 condition, \ 1312 fmt, \ 1313 ##__VA_ARGS__) 1314 1315 /** 1316 * KUNIT_ASSERT_FALSE() - Sets an assertion that @condition is false. 1317 * @test: The test context object. 1318 * @condition: an arbitrary boolean expression. 1319 * 1320 * Sets an assertion that the value that @condition evaluates to is false. This 1321 * is the same as KUNIT_EXPECT_FALSE(), except it causes an assertion failure 1322 * (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1323 */ 1324 #define KUNIT_ASSERT_FALSE(test, condition) \ 1325 KUNIT_ASSERT_FALSE_MSG(test, condition, NULL) 1326 1327 #define KUNIT_ASSERT_FALSE_MSG(test, condition, fmt, ...) \ 1328 KUNIT_FALSE_MSG_ASSERTION(test, \ 1329 KUNIT_ASSERTION, \ 1330 condition, \ 1331 fmt, \ 1332 ##__VA_ARGS__) 1333 1334 /** 1335 * KUNIT_ASSERT_EQ() - Sets an assertion that @left and @right are equal. 1336 * @test: The test context object. 1337 * @left: an arbitrary expression that evaluates to a primitive C type. 1338 * @right: an arbitrary expression that evaluates to a primitive C type. 1339 * 1340 * Sets an assertion that the values that @left and @right evaluate to are 1341 * equal. This is the same as KUNIT_EXPECT_EQ(), except it causes an assertion 1342 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1343 */ 1344 #define KUNIT_ASSERT_EQ(test, left, right) \ 1345 KUNIT_ASSERT_EQ_MSG(test, left, right, NULL) 1346 1347 #define KUNIT_ASSERT_EQ_MSG(test, left, right, fmt, ...) \ 1348 KUNIT_BINARY_INT_ASSERTION(test, \ 1349 KUNIT_ASSERTION, \ 1350 left, ==, right, \ 1351 fmt, \ 1352 ##__VA_ARGS__) 1353 1354 /** 1355 * KUNIT_ASSERT_PTR_EQ() - Asserts that pointers @left and @right are equal. 1356 * @test: The test context object. 1357 * @left: an arbitrary expression that evaluates to a pointer. 1358 * @right: an arbitrary expression that evaluates to a pointer. 1359 * 1360 * Sets an assertion that the values that @left and @right evaluate to are 1361 * equal. This is the same as KUNIT_EXPECT_EQ(), except it causes an assertion 1362 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1363 */ 1364 #define KUNIT_ASSERT_PTR_EQ(test, left, right) \ 1365 KUNIT_ASSERT_PTR_EQ_MSG(test, left, right, NULL) 1366 1367 #define KUNIT_ASSERT_PTR_EQ_MSG(test, left, right, fmt, ...) \ 1368 KUNIT_BINARY_PTR_ASSERTION(test, \ 1369 KUNIT_ASSERTION, \ 1370 left, ==, right, \ 1371 fmt, \ 1372 ##__VA_ARGS__) 1373 1374 /** 1375 * KUNIT_ASSERT_NE() - An assertion that @left and @right are not equal. 1376 * @test: The test context object. 1377 * @left: an arbitrary expression that evaluates to a primitive C type. 1378 * @right: an arbitrary expression that evaluates to a primitive C type. 1379 * 1380 * Sets an assertion that the values that @left and @right evaluate to are not 1381 * equal. This is the same as KUNIT_EXPECT_NE(), except it causes an assertion 1382 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1383 */ 1384 #define KUNIT_ASSERT_NE(test, left, right) \ 1385 KUNIT_ASSERT_NE_MSG(test, left, right, NULL) 1386 1387 #define KUNIT_ASSERT_NE_MSG(test, left, right, fmt, ...) \ 1388 KUNIT_BINARY_INT_ASSERTION(test, \ 1389 KUNIT_ASSERTION, \ 1390 left, !=, right, \ 1391 fmt, \ 1392 ##__VA_ARGS__) 1393 1394 /** 1395 * KUNIT_ASSERT_PTR_NE() - Asserts that pointers @left and @right are not equal. 1396 * KUNIT_ASSERT_PTR_EQ() - Asserts that pointers @left and @right are equal. 1397 * @test: The test context object. 1398 * @left: an arbitrary expression that evaluates to a pointer. 1399 * @right: an arbitrary expression that evaluates to a pointer. 1400 * 1401 * Sets an assertion that the values that @left and @right evaluate to are not 1402 * equal. This is the same as KUNIT_EXPECT_NE(), except it causes an assertion 1403 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1404 */ 1405 #define KUNIT_ASSERT_PTR_NE(test, left, right) \ 1406 KUNIT_ASSERT_PTR_NE_MSG(test, left, right, NULL) 1407 1408 #define KUNIT_ASSERT_PTR_NE_MSG(test, left, right, fmt, ...) \ 1409 KUNIT_BINARY_PTR_ASSERTION(test, \ 1410 KUNIT_ASSERTION, \ 1411 left, !=, right, \ 1412 fmt, \ 1413 ##__VA_ARGS__) 1414 /** 1415 * KUNIT_ASSERT_LT() - An assertion that @left is less than @right. 1416 * @test: The test context object. 1417 * @left: an arbitrary expression that evaluates to a primitive C type. 1418 * @right: an arbitrary expression that evaluates to a primitive C type. 1419 * 1420 * Sets an assertion that the value that @left evaluates to is less than the 1421 * value that @right evaluates to. This is the same as KUNIT_EXPECT_LT(), except 1422 * it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion 1423 * is not met. 1424 */ 1425 #define KUNIT_ASSERT_LT(test, left, right) \ 1426 KUNIT_ASSERT_LT_MSG(test, left, right, NULL) 1427 1428 #define KUNIT_ASSERT_LT_MSG(test, left, right, fmt, ...) \ 1429 KUNIT_BINARY_INT_ASSERTION(test, \ 1430 KUNIT_ASSERTION, \ 1431 left, <, right, \ 1432 fmt, \ 1433 ##__VA_ARGS__) 1434 /** 1435 * KUNIT_ASSERT_LE() - An assertion that @left is less than or equal to @right. 1436 * @test: The test context object. 1437 * @left: an arbitrary expression that evaluates to a primitive C type. 1438 * @right: an arbitrary expression that evaluates to a primitive C type. 1439 * 1440 * Sets an assertion that the value that @left evaluates to is less than or 1441 * equal to the value that @right evaluates to. This is the same as 1442 * KUNIT_EXPECT_LE(), except it causes an assertion failure (see 1443 * KUNIT_ASSERT_TRUE()) when the assertion is not met. 1444 */ 1445 #define KUNIT_ASSERT_LE(test, left, right) \ 1446 KUNIT_ASSERT_LE_MSG(test, left, right, NULL) 1447 1448 #define KUNIT_ASSERT_LE_MSG(test, left, right, fmt, ...) \ 1449 KUNIT_BINARY_INT_ASSERTION(test, \ 1450 KUNIT_ASSERTION, \ 1451 left, <=, right, \ 1452 fmt, \ 1453 ##__VA_ARGS__) 1454 1455 /** 1456 * KUNIT_ASSERT_GT() - An assertion that @left is greater than @right. 1457 * @test: The test context object. 1458 * @left: an arbitrary expression that evaluates to a primitive C type. 1459 * @right: an arbitrary expression that evaluates to a primitive C type. 1460 * 1461 * Sets an assertion that the value that @left evaluates to is greater than the 1462 * value that @right evaluates to. This is the same as KUNIT_EXPECT_GT(), except 1463 * it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion 1464 * is not met. 1465 */ 1466 #define KUNIT_ASSERT_GT(test, left, right) \ 1467 KUNIT_ASSERT_GT_MSG(test, left, right, NULL) 1468 1469 #define KUNIT_ASSERT_GT_MSG(test, left, right, fmt, ...) \ 1470 KUNIT_BINARY_INT_ASSERTION(test, \ 1471 KUNIT_ASSERTION, \ 1472 left, >, right, \ 1473 fmt, \ 1474 ##__VA_ARGS__) 1475 1476 /** 1477 * KUNIT_ASSERT_GE() - Assertion that @left is greater than or equal to @right. 1478 * @test: The test context object. 1479 * @left: an arbitrary expression that evaluates to a primitive C type. 1480 * @right: an arbitrary expression that evaluates to a primitive C type. 1481 * 1482 * Sets an assertion that the value that @left evaluates to is greater than the 1483 * value that @right evaluates to. This is the same as KUNIT_EXPECT_GE(), except 1484 * it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion 1485 * is not met. 1486 */ 1487 #define KUNIT_ASSERT_GE(test, left, right) \ 1488 KUNIT_ASSERT_GE_MSG(test, left, right, NULL) 1489 1490 #define KUNIT_ASSERT_GE_MSG(test, left, right, fmt, ...) \ 1491 KUNIT_BINARY_INT_ASSERTION(test, \ 1492 KUNIT_ASSERTION, \ 1493 left, >=, right, \ 1494 fmt, \ 1495 ##__VA_ARGS__) 1496 1497 /** 1498 * KUNIT_ASSERT_STREQ() - An assertion that strings @left and @right are equal. 1499 * @test: The test context object. 1500 * @left: an arbitrary expression that evaluates to a null terminated string. 1501 * @right: an arbitrary expression that evaluates to a null terminated string. 1502 * 1503 * Sets an assertion that the values that @left and @right evaluate to are 1504 * equal. This is the same as KUNIT_EXPECT_STREQ(), except it causes an 1505 * assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1506 */ 1507 #define KUNIT_ASSERT_STREQ(test, left, right) \ 1508 KUNIT_ASSERT_STREQ_MSG(test, left, right, NULL) 1509 1510 #define KUNIT_ASSERT_STREQ_MSG(test, left, right, fmt, ...) \ 1511 KUNIT_BINARY_STR_ASSERTION(test, \ 1512 KUNIT_ASSERTION, \ 1513 left, ==, right, \ 1514 fmt, \ 1515 ##__VA_ARGS__) 1516 1517 /** 1518 * KUNIT_ASSERT_STRNEQ() - An assertion that strings @left and @right are not equal. 1519 * @test: The test context object. 1520 * @left: an arbitrary expression that evaluates to a null terminated string. 1521 * @right: an arbitrary expression that evaluates to a null terminated string. 1522 * 1523 * Sets an assertion that the values that @left and @right evaluate to are 1524 * not equal. This is semantically equivalent to 1525 * KUNIT_ASSERT_TRUE(@test, strcmp((@left), (@right))). See KUNIT_ASSERT_TRUE() 1526 * for more information. 1527 */ 1528 #define KUNIT_ASSERT_STRNEQ(test, left, right) \ 1529 KUNIT_ASSERT_STRNEQ_MSG(test, left, right, NULL) 1530 1531 #define KUNIT_ASSERT_STRNEQ_MSG(test, left, right, fmt, ...) \ 1532 KUNIT_BINARY_STR_ASSERTION(test, \ 1533 KUNIT_ASSERTION, \ 1534 left, !=, right, \ 1535 fmt, \ 1536 ##__VA_ARGS__) 1537 1538 /** 1539 * KUNIT_ASSERT_MEMEQ() - Asserts that the first @size bytes of @left and @right are equal. 1540 * @test: The test context object. 1541 * @left: An arbitrary expression that evaluates to the specified size. 1542 * @right: An arbitrary expression that evaluates to the specified size. 1543 * @size: Number of bytes compared. 1544 * 1545 * Sets an assertion that the values that @left and @right evaluate to are 1546 * equal. This is semantically equivalent to 1547 * KUNIT_ASSERT_TRUE(@test, !memcmp((@left), (@right), (@size))). See 1548 * KUNIT_ASSERT_TRUE() for more information. 1549 * 1550 * Although this assertion works for any memory block, it is not recommended 1551 * for comparing more structured data, such as structs. This assertion is 1552 * recommended for comparing, for example, data arrays. 1553 */ 1554 #define KUNIT_ASSERT_MEMEQ(test, left, right, size) \ 1555 KUNIT_ASSERT_MEMEQ_MSG(test, left, right, size, NULL) 1556 1557 #define KUNIT_ASSERT_MEMEQ_MSG(test, left, right, size, fmt, ...) \ 1558 KUNIT_MEM_ASSERTION(test, \ 1559 KUNIT_ASSERTION, \ 1560 left, ==, right, \ 1561 size, \ 1562 fmt, \ 1563 ##__VA_ARGS__) 1564 1565 /** 1566 * KUNIT_ASSERT_MEMNEQ() - Asserts that the first @size bytes of @left and @right are not equal. 1567 * @test: The test context object. 1568 * @left: An arbitrary expression that evaluates to the specified size. 1569 * @right: An arbitrary expression that evaluates to the specified size. 1570 * @size: Number of bytes compared. 1571 * 1572 * Sets an assertion that the values that @left and @right evaluate to are 1573 * not equal. This is semantically equivalent to 1574 * KUNIT_ASSERT_TRUE(@test, memcmp((@left), (@right), (@size))). See 1575 * KUNIT_ASSERT_TRUE() for more information. 1576 * 1577 * Although this assertion works for any memory block, it is not recommended 1578 * for comparing more structured data, such as structs. This assertion is 1579 * recommended for comparing, for example, data arrays. 1580 */ 1581 #define KUNIT_ASSERT_MEMNEQ(test, left, right, size) \ 1582 KUNIT_ASSERT_MEMNEQ_MSG(test, left, right, size, NULL) 1583 1584 #define KUNIT_ASSERT_MEMNEQ_MSG(test, left, right, size, fmt, ...) \ 1585 KUNIT_MEM_ASSERTION(test, \ 1586 KUNIT_ASSERTION, \ 1587 left, !=, right, \ 1588 size, \ 1589 fmt, \ 1590 ##__VA_ARGS__) 1591 1592 /** 1593 * KUNIT_ASSERT_NULL() - Asserts that pointers @ptr is null. 1594 * @test: The test context object. 1595 * @ptr: an arbitrary pointer. 1596 * 1597 * Sets an assertion that the values that @ptr evaluates to is null. This is 1598 * the same as KUNIT_EXPECT_NULL(), except it causes an assertion 1599 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1600 */ 1601 #define KUNIT_ASSERT_NULL(test, ptr) \ 1602 KUNIT_ASSERT_NULL_MSG(test, \ 1603 ptr, \ 1604 NULL) 1605 1606 #define KUNIT_ASSERT_NULL_MSG(test, ptr, fmt, ...) \ 1607 KUNIT_BINARY_PTR_ASSERTION(test, \ 1608 KUNIT_ASSERTION, \ 1609 ptr, ==, NULL, \ 1610 fmt, \ 1611 ##__VA_ARGS__) 1612 1613 /** 1614 * KUNIT_ASSERT_NOT_NULL() - Asserts that pointers @ptr is not null. 1615 * @test: The test context object. 1616 * @ptr: an arbitrary pointer. 1617 * 1618 * Sets an assertion that the values that @ptr evaluates to is not null. This 1619 * is the same as KUNIT_EXPECT_NOT_NULL(), except it causes an assertion 1620 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1621 */ 1622 #define KUNIT_ASSERT_NOT_NULL(test, ptr) \ 1623 KUNIT_ASSERT_NOT_NULL_MSG(test, \ 1624 ptr, \ 1625 NULL) 1626 1627 #define KUNIT_ASSERT_NOT_NULL_MSG(test, ptr, fmt, ...) \ 1628 KUNIT_BINARY_PTR_ASSERTION(test, \ 1629 KUNIT_ASSERTION, \ 1630 ptr, !=, NULL, \ 1631 fmt, \ 1632 ##__VA_ARGS__) 1633 1634 /** 1635 * KUNIT_ASSERT_NOT_ERR_OR_NULL() - Assertion that @ptr is not null and not err. 1636 * @test: The test context object. 1637 * @ptr: an arbitrary pointer. 1638 * 1639 * Sets an assertion that the value that @ptr evaluates to is not null and not 1640 * an errno stored in a pointer. This is the same as 1641 * KUNIT_EXPECT_NOT_ERR_OR_NULL(), except it causes an assertion failure (see 1642 * KUNIT_ASSERT_TRUE()) when the assertion is not met. 1643 */ 1644 #define KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ptr) \ 1645 KUNIT_ASSERT_NOT_ERR_OR_NULL_MSG(test, ptr, NULL) 1646 1647 #define KUNIT_ASSERT_NOT_ERR_OR_NULL_MSG(test, ptr, fmt, ...) \ 1648 KUNIT_PTR_NOT_ERR_OR_NULL_MSG_ASSERTION(test, \ 1649 KUNIT_ASSERTION, \ 1650 ptr, \ 1651 fmt, \ 1652 ##__VA_ARGS__) 1653 1654 /** 1655 * KUNIT_ARRAY_PARAM() - Define test parameter generator from an array. 1656 * @name: prefix for the test parameter generator function. 1657 * @array: array of test parameters. 1658 * @get_desc: function to convert param to description; NULL to use default 1659 * 1660 * Define function @name_gen_params which uses @array to generate parameters. 1661 */ 1662 #define KUNIT_ARRAY_PARAM(name, array, get_desc) \ 1663 static const void *name##_gen_params(const void *prev, char *desc) \ 1664 { \ 1665 typeof((array)[0]) *__next = prev ? ((typeof(__next)) prev) + 1 : (array); \ 1666 if (__next - (array) < ARRAY_SIZE((array))) { \ 1667 void (*__get_desc)(typeof(__next), char *) = get_desc; \ 1668 if (__get_desc) \ 1669 __get_desc(__next, desc); \ 1670 return __next; \ 1671 } \ 1672 return NULL; \ 1673 } 1674 1675 /** 1676 * KUNIT_ARRAY_PARAM_DESC() - Define test parameter generator from an array. 1677 * @name: prefix for the test parameter generator function. 1678 * @array: array of test parameters. 1679 * @desc_member: structure member from array element to use as description 1680 * 1681 * Define function @name_gen_params which uses @array to generate parameters. 1682 */ 1683 #define KUNIT_ARRAY_PARAM_DESC(name, array, desc_member) \ 1684 static const void *name##_gen_params(const void *prev, char *desc) \ 1685 { \ 1686 typeof((array)[0]) *__next = prev ? ((typeof(__next)) prev) + 1 : (array); \ 1687 if (__next - (array) < ARRAY_SIZE((array))) { \ 1688 strscpy(desc, __next->desc_member, KUNIT_PARAM_DESC_SIZE); \ 1689 return __next; \ 1690 } \ 1691 return NULL; \ 1692 } 1693 1694 // TODO(dlatypov@google.com): consider eventually migrating users to explicitly 1695 // include resource.h themselves if they need it. 1696 #include <kunit/resource.h> 1697 1698 #endif /* _KUNIT_TEST_H */ 1699