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 #include <kunit/resource.h> 10 #include <kunit/test.h> 11 #include <kunit/test-bug.h> 12 #include <linux/kernel.h> 13 #include <linux/module.h> 14 #include <linux/moduleparam.h> 15 #include <linux/panic.h> 16 #include <linux/sched/debug.h> 17 #include <linux/sched.h> 18 19 #include "debugfs.h" 20 #include "string-stream.h" 21 #include "try-catch-impl.h" 22 23 #if IS_BUILTIN(CONFIG_KUNIT) 24 /* 25 * Fail the current test and print an error message to the log. 26 */ 27 void __kunit_fail_current_test(const char *file, int line, const char *fmt, ...) 28 { 29 va_list args; 30 int len; 31 char *buffer; 32 33 if (!current->kunit_test) 34 return; 35 36 kunit_set_failure(current->kunit_test); 37 38 /* kunit_err() only accepts literals, so evaluate the args first. */ 39 va_start(args, fmt); 40 len = vsnprintf(NULL, 0, fmt, args) + 1; 41 va_end(args); 42 43 buffer = kunit_kmalloc(current->kunit_test, len, GFP_KERNEL); 44 if (!buffer) 45 return; 46 47 va_start(args, fmt); 48 vsnprintf(buffer, len, fmt, args); 49 va_end(args); 50 51 kunit_err(current->kunit_test, "%s:%d: %s", file, line, buffer); 52 kunit_kfree(current->kunit_test, buffer); 53 } 54 EXPORT_SYMBOL_GPL(__kunit_fail_current_test); 55 #endif 56 57 /* 58 * Enable KUnit tests to run. 59 */ 60 #ifdef CONFIG_KUNIT_DEFAULT_ENABLED 61 static bool enable_param = true; 62 #else 63 static bool enable_param; 64 #endif 65 module_param_named(enable, enable_param, bool, 0); 66 MODULE_PARM_DESC(enable, "Enable KUnit tests"); 67 68 /* 69 * KUnit statistic mode: 70 * 0 - disabled 71 * 1 - only when there is more than one subtest 72 * 2 - enabled 73 */ 74 static int kunit_stats_enabled = 1; 75 module_param_named(stats_enabled, kunit_stats_enabled, int, 0644); 76 MODULE_PARM_DESC(stats_enabled, 77 "Print test stats: never (0), only for multiple subtests (1), or always (2)"); 78 79 struct kunit_result_stats { 80 unsigned long passed; 81 unsigned long skipped; 82 unsigned long failed; 83 unsigned long total; 84 }; 85 86 static bool kunit_should_print_stats(struct kunit_result_stats stats) 87 { 88 if (kunit_stats_enabled == 0) 89 return false; 90 91 if (kunit_stats_enabled == 2) 92 return true; 93 94 return (stats.total > 1); 95 } 96 97 static void kunit_print_test_stats(struct kunit *test, 98 struct kunit_result_stats stats) 99 { 100 if (!kunit_should_print_stats(stats)) 101 return; 102 103 kunit_log(KERN_INFO, test, 104 KUNIT_SUBTEST_INDENT 105 "# %s: pass:%lu fail:%lu skip:%lu total:%lu", 106 test->name, 107 stats.passed, 108 stats.failed, 109 stats.skipped, 110 stats.total); 111 } 112 113 /* 114 * Append formatted message to log, size of which is limited to 115 * KUNIT_LOG_SIZE bytes (including null terminating byte). 116 */ 117 void kunit_log_append(char *log, const char *fmt, ...) 118 { 119 char line[KUNIT_LOG_SIZE]; 120 va_list args; 121 int len_left; 122 123 if (!log) 124 return; 125 126 len_left = KUNIT_LOG_SIZE - strlen(log) - 1; 127 if (len_left <= 0) 128 return; 129 130 va_start(args, fmt); 131 vsnprintf(line, sizeof(line), fmt, args); 132 va_end(args); 133 134 strncat(log, line, len_left); 135 } 136 EXPORT_SYMBOL_GPL(kunit_log_append); 137 138 size_t kunit_suite_num_test_cases(struct kunit_suite *suite) 139 { 140 struct kunit_case *test_case; 141 size_t len = 0; 142 143 kunit_suite_for_each_test_case(suite, test_case) 144 len++; 145 146 return len; 147 } 148 EXPORT_SYMBOL_GPL(kunit_suite_num_test_cases); 149 150 static void kunit_print_suite_start(struct kunit_suite *suite) 151 { 152 kunit_log(KERN_INFO, suite, KUNIT_SUBTEST_INDENT "# Subtest: %s", 153 suite->name); 154 kunit_log(KERN_INFO, suite, KUNIT_SUBTEST_INDENT "1..%zd", 155 kunit_suite_num_test_cases(suite)); 156 } 157 158 static void kunit_print_ok_not_ok(void *test_or_suite, 159 bool is_test, 160 enum kunit_status status, 161 size_t test_number, 162 const char *description, 163 const char *directive) 164 { 165 struct kunit_suite *suite = is_test ? NULL : test_or_suite; 166 struct kunit *test = is_test ? test_or_suite : NULL; 167 const char *directive_header = (status == KUNIT_SKIPPED) ? " # SKIP " : ""; 168 169 /* 170 * We do not log the test suite results as doing so would 171 * mean debugfs display would consist of the test suite 172 * description and status prior to individual test results. 173 * Hence directly printk the suite status, and we will 174 * separately seq_printf() the suite status for the debugfs 175 * representation. 176 */ 177 if (suite) 178 pr_info("%s %zd - %s%s%s\n", 179 kunit_status_to_ok_not_ok(status), 180 test_number, description, directive_header, 181 (status == KUNIT_SKIPPED) ? directive : ""); 182 else 183 kunit_log(KERN_INFO, test, 184 KUNIT_SUBTEST_INDENT "%s %zd - %s%s%s", 185 kunit_status_to_ok_not_ok(status), 186 test_number, description, directive_header, 187 (status == KUNIT_SKIPPED) ? directive : ""); 188 } 189 190 enum kunit_status kunit_suite_has_succeeded(struct kunit_suite *suite) 191 { 192 const struct kunit_case *test_case; 193 enum kunit_status status = KUNIT_SKIPPED; 194 195 if (suite->suite_init_err) 196 return KUNIT_FAILURE; 197 198 kunit_suite_for_each_test_case(suite, test_case) { 199 if (test_case->status == KUNIT_FAILURE) 200 return KUNIT_FAILURE; 201 else if (test_case->status == KUNIT_SUCCESS) 202 status = KUNIT_SUCCESS; 203 } 204 205 return status; 206 } 207 EXPORT_SYMBOL_GPL(kunit_suite_has_succeeded); 208 209 static size_t kunit_suite_counter = 1; 210 211 static void kunit_print_suite_end(struct kunit_suite *suite) 212 { 213 kunit_print_ok_not_ok((void *)suite, false, 214 kunit_suite_has_succeeded(suite), 215 kunit_suite_counter++, 216 suite->name, 217 suite->status_comment); 218 } 219 220 unsigned int kunit_test_case_num(struct kunit_suite *suite, 221 struct kunit_case *test_case) 222 { 223 struct kunit_case *tc; 224 unsigned int i = 1; 225 226 kunit_suite_for_each_test_case(suite, tc) { 227 if (tc == test_case) 228 return i; 229 i++; 230 } 231 232 return 0; 233 } 234 EXPORT_SYMBOL_GPL(kunit_test_case_num); 235 236 static void kunit_print_string_stream(struct kunit *test, 237 struct string_stream *stream) 238 { 239 struct string_stream_fragment *fragment; 240 char *buf; 241 242 if (string_stream_is_empty(stream)) 243 return; 244 245 buf = string_stream_get_string(stream); 246 if (!buf) { 247 kunit_err(test, 248 "Could not allocate buffer, dumping stream:\n"); 249 list_for_each_entry(fragment, &stream->fragments, node) { 250 kunit_err(test, "%s", fragment->fragment); 251 } 252 kunit_err(test, "\n"); 253 } else { 254 kunit_err(test, "%s", buf); 255 kunit_kfree(test, buf); 256 } 257 } 258 259 static void kunit_fail(struct kunit *test, const struct kunit_loc *loc, 260 enum kunit_assert_type type, const struct kunit_assert *assert, 261 const struct va_format *message) 262 { 263 struct string_stream *stream; 264 265 kunit_set_failure(test); 266 267 stream = alloc_string_stream(test, GFP_KERNEL); 268 if (!stream) { 269 WARN(true, 270 "Could not allocate stream to print failed assertion in %s:%d\n", 271 loc->file, 272 loc->line); 273 return; 274 } 275 276 kunit_assert_prologue(loc, type, stream); 277 assert->format(assert, message, stream); 278 279 kunit_print_string_stream(test, stream); 280 281 WARN_ON(string_stream_destroy(stream)); 282 } 283 284 static void __noreturn kunit_abort(struct kunit *test) 285 { 286 kunit_try_catch_throw(&test->try_catch); /* Does not return. */ 287 288 /* 289 * Throw could not abort from test. 290 * 291 * XXX: we should never reach this line! As kunit_try_catch_throw is 292 * marked __noreturn. 293 */ 294 WARN_ONCE(true, "Throw could not abort from test!\n"); 295 } 296 297 void kunit_do_failed_assertion(struct kunit *test, 298 const struct kunit_loc *loc, 299 enum kunit_assert_type type, 300 const struct kunit_assert *assert, 301 const char *fmt, ...) 302 { 303 va_list args; 304 struct va_format message; 305 va_start(args, fmt); 306 307 message.fmt = fmt; 308 message.va = &args; 309 310 kunit_fail(test, loc, type, assert, &message); 311 312 va_end(args); 313 314 if (type == KUNIT_ASSERTION) 315 kunit_abort(test); 316 } 317 EXPORT_SYMBOL_GPL(kunit_do_failed_assertion); 318 319 void kunit_init_test(struct kunit *test, const char *name, char *log) 320 { 321 spin_lock_init(&test->lock); 322 INIT_LIST_HEAD(&test->resources); 323 test->name = name; 324 test->log = log; 325 if (test->log) 326 test->log[0] = '\0'; 327 test->status = KUNIT_SUCCESS; 328 test->status_comment[0] = '\0'; 329 } 330 EXPORT_SYMBOL_GPL(kunit_init_test); 331 332 /* 333 * Initializes and runs test case. Does not clean up or do post validations. 334 */ 335 static void kunit_run_case_internal(struct kunit *test, 336 struct kunit_suite *suite, 337 struct kunit_case *test_case) 338 { 339 if (suite->init) { 340 int ret; 341 342 ret = suite->init(test); 343 if (ret) { 344 kunit_err(test, "failed to initialize: %d\n", ret); 345 kunit_set_failure(test); 346 return; 347 } 348 } 349 350 test_case->run_case(test); 351 } 352 353 static void kunit_case_internal_cleanup(struct kunit *test) 354 { 355 kunit_cleanup(test); 356 } 357 358 /* 359 * Performs post validations and cleanup after a test case was run. 360 * XXX: Should ONLY BE CALLED AFTER kunit_run_case_internal! 361 */ 362 static void kunit_run_case_cleanup(struct kunit *test, 363 struct kunit_suite *suite) 364 { 365 if (suite->exit) 366 suite->exit(test); 367 368 kunit_case_internal_cleanup(test); 369 } 370 371 struct kunit_try_catch_context { 372 struct kunit *test; 373 struct kunit_suite *suite; 374 struct kunit_case *test_case; 375 }; 376 377 static void kunit_try_run_case(void *data) 378 { 379 struct kunit_try_catch_context *ctx = data; 380 struct kunit *test = ctx->test; 381 struct kunit_suite *suite = ctx->suite; 382 struct kunit_case *test_case = ctx->test_case; 383 384 current->kunit_test = test; 385 386 /* 387 * kunit_run_case_internal may encounter a fatal error; if it does, 388 * abort will be called, this thread will exit, and finally the parent 389 * thread will resume control and handle any necessary clean up. 390 */ 391 kunit_run_case_internal(test, suite, test_case); 392 /* This line may never be reached. */ 393 kunit_run_case_cleanup(test, suite); 394 } 395 396 static void kunit_catch_run_case(void *data) 397 { 398 struct kunit_try_catch_context *ctx = data; 399 struct kunit *test = ctx->test; 400 struct kunit_suite *suite = ctx->suite; 401 int try_exit_code = kunit_try_catch_get_result(&test->try_catch); 402 403 if (try_exit_code) { 404 kunit_set_failure(test); 405 /* 406 * Test case could not finish, we have no idea what state it is 407 * in, so don't do clean up. 408 */ 409 if (try_exit_code == -ETIMEDOUT) { 410 kunit_err(test, "test case timed out\n"); 411 /* 412 * Unknown internal error occurred preventing test case from 413 * running, so there is nothing to clean up. 414 */ 415 } else { 416 kunit_err(test, "internal error occurred preventing test case from running: %d\n", 417 try_exit_code); 418 } 419 return; 420 } 421 422 /* 423 * Test case was run, but aborted. It is the test case's business as to 424 * whether it failed or not, we just need to clean up. 425 */ 426 kunit_run_case_cleanup(test, suite); 427 } 428 429 /* 430 * Performs all logic to run a test case. It also catches most errors that 431 * occur in a test case and reports them as failures. 432 */ 433 static void kunit_run_case_catch_errors(struct kunit_suite *suite, 434 struct kunit_case *test_case, 435 struct kunit *test) 436 { 437 struct kunit_try_catch_context context; 438 struct kunit_try_catch *try_catch; 439 440 kunit_init_test(test, test_case->name, test_case->log); 441 try_catch = &test->try_catch; 442 443 kunit_try_catch_init(try_catch, 444 test, 445 kunit_try_run_case, 446 kunit_catch_run_case); 447 context.test = test; 448 context.suite = suite; 449 context.test_case = test_case; 450 kunit_try_catch_run(try_catch, &context); 451 452 /* Propagate the parameter result to the test case. */ 453 if (test->status == KUNIT_FAILURE) 454 test_case->status = KUNIT_FAILURE; 455 else if (test_case->status != KUNIT_FAILURE && test->status == KUNIT_SUCCESS) 456 test_case->status = KUNIT_SUCCESS; 457 } 458 459 static void kunit_print_suite_stats(struct kunit_suite *suite, 460 struct kunit_result_stats suite_stats, 461 struct kunit_result_stats param_stats) 462 { 463 if (kunit_should_print_stats(suite_stats)) { 464 kunit_log(KERN_INFO, suite, 465 "# %s: pass:%lu fail:%lu skip:%lu total:%lu", 466 suite->name, 467 suite_stats.passed, 468 suite_stats.failed, 469 suite_stats.skipped, 470 suite_stats.total); 471 } 472 473 if (kunit_should_print_stats(param_stats)) { 474 kunit_log(KERN_INFO, suite, 475 "# Totals: pass:%lu fail:%lu skip:%lu total:%lu", 476 param_stats.passed, 477 param_stats.failed, 478 param_stats.skipped, 479 param_stats.total); 480 } 481 } 482 483 static void kunit_update_stats(struct kunit_result_stats *stats, 484 enum kunit_status status) 485 { 486 switch (status) { 487 case KUNIT_SUCCESS: 488 stats->passed++; 489 break; 490 case KUNIT_SKIPPED: 491 stats->skipped++; 492 break; 493 case KUNIT_FAILURE: 494 stats->failed++; 495 break; 496 } 497 498 stats->total++; 499 } 500 501 static void kunit_accumulate_stats(struct kunit_result_stats *total, 502 struct kunit_result_stats add) 503 { 504 total->passed += add.passed; 505 total->skipped += add.skipped; 506 total->failed += add.failed; 507 total->total += add.total; 508 } 509 510 int kunit_run_tests(struct kunit_suite *suite) 511 { 512 char param_desc[KUNIT_PARAM_DESC_SIZE]; 513 struct kunit_case *test_case; 514 struct kunit_result_stats suite_stats = { 0 }; 515 struct kunit_result_stats total_stats = { 0 }; 516 517 /* Taint the kernel so we know we've run tests. */ 518 add_taint(TAINT_TEST, LOCKDEP_STILL_OK); 519 520 if (suite->suite_init) { 521 suite->suite_init_err = suite->suite_init(suite); 522 if (suite->suite_init_err) { 523 kunit_err(suite, KUNIT_SUBTEST_INDENT 524 "# failed to initialize (%d)", suite->suite_init_err); 525 goto suite_end; 526 } 527 } 528 529 kunit_print_suite_start(suite); 530 531 kunit_suite_for_each_test_case(suite, test_case) { 532 struct kunit test = { .param_value = NULL, .param_index = 0 }; 533 struct kunit_result_stats param_stats = { 0 }; 534 test_case->status = KUNIT_SKIPPED; 535 536 if (!test_case->generate_params) { 537 /* Non-parameterised test. */ 538 kunit_run_case_catch_errors(suite, test_case, &test); 539 kunit_update_stats(¶m_stats, test.status); 540 } else { 541 /* Get initial param. */ 542 param_desc[0] = '\0'; 543 test.param_value = test_case->generate_params(NULL, param_desc); 544 kunit_log(KERN_INFO, &test, KUNIT_SUBTEST_INDENT KUNIT_SUBTEST_INDENT 545 "# Subtest: %s", test_case->name); 546 547 while (test.param_value) { 548 kunit_run_case_catch_errors(suite, test_case, &test); 549 550 if (param_desc[0] == '\0') { 551 snprintf(param_desc, sizeof(param_desc), 552 "param-%d", test.param_index); 553 } 554 555 kunit_log(KERN_INFO, &test, 556 KUNIT_SUBTEST_INDENT KUNIT_SUBTEST_INDENT 557 "%s %d - %s", 558 kunit_status_to_ok_not_ok(test.status), 559 test.param_index + 1, param_desc); 560 561 /* Get next param. */ 562 param_desc[0] = '\0'; 563 test.param_value = test_case->generate_params(test.param_value, param_desc); 564 test.param_index++; 565 566 kunit_update_stats(¶m_stats, test.status); 567 } 568 } 569 570 571 kunit_print_test_stats(&test, param_stats); 572 573 kunit_print_ok_not_ok(&test, true, test_case->status, 574 kunit_test_case_num(suite, test_case), 575 test_case->name, 576 test.status_comment); 577 578 kunit_update_stats(&suite_stats, test_case->status); 579 kunit_accumulate_stats(&total_stats, param_stats); 580 } 581 582 if (suite->suite_exit) 583 suite->suite_exit(suite); 584 585 kunit_print_suite_stats(suite, suite_stats, total_stats); 586 suite_end: 587 kunit_print_suite_end(suite); 588 589 return 0; 590 } 591 EXPORT_SYMBOL_GPL(kunit_run_tests); 592 593 static void kunit_init_suite(struct kunit_suite *suite) 594 { 595 kunit_debugfs_create_suite(suite); 596 suite->status_comment[0] = '\0'; 597 suite->suite_init_err = 0; 598 } 599 600 bool kunit_enabled(void) 601 { 602 return enable_param; 603 } 604 605 int __kunit_test_suites_init(struct kunit_suite * const * const suites, int num_suites) 606 { 607 unsigned int i; 608 609 if (!kunit_enabled() && num_suites > 0) { 610 pr_info("kunit: disabled\n"); 611 return 0; 612 } 613 614 for (i = 0; i < num_suites; i++) { 615 kunit_init_suite(suites[i]); 616 kunit_run_tests(suites[i]); 617 } 618 return 0; 619 } 620 EXPORT_SYMBOL_GPL(__kunit_test_suites_init); 621 622 static void kunit_exit_suite(struct kunit_suite *suite) 623 { 624 kunit_debugfs_destroy_suite(suite); 625 } 626 627 void __kunit_test_suites_exit(struct kunit_suite **suites, int num_suites) 628 { 629 unsigned int i; 630 631 if (!kunit_enabled()) 632 return; 633 634 for (i = 0; i < num_suites; i++) 635 kunit_exit_suite(suites[i]); 636 637 kunit_suite_counter = 1; 638 } 639 EXPORT_SYMBOL_GPL(__kunit_test_suites_exit); 640 641 #ifdef CONFIG_MODULES 642 static void kunit_module_init(struct module *mod) 643 { 644 __kunit_test_suites_init(mod->kunit_suites, mod->num_kunit_suites); 645 } 646 647 static void kunit_module_exit(struct module *mod) 648 { 649 __kunit_test_suites_exit(mod->kunit_suites, mod->num_kunit_suites); 650 } 651 652 static int kunit_module_notify(struct notifier_block *nb, unsigned long val, 653 void *data) 654 { 655 struct module *mod = data; 656 657 switch (val) { 658 case MODULE_STATE_LIVE: 659 kunit_module_init(mod); 660 break; 661 case MODULE_STATE_GOING: 662 kunit_module_exit(mod); 663 break; 664 case MODULE_STATE_COMING: 665 case MODULE_STATE_UNFORMED: 666 break; 667 } 668 669 return 0; 670 } 671 672 static struct notifier_block kunit_mod_nb = { 673 .notifier_call = kunit_module_notify, 674 .priority = 0, 675 }; 676 #endif 677 678 struct kunit_kmalloc_array_params { 679 size_t n; 680 size_t size; 681 gfp_t gfp; 682 }; 683 684 static int kunit_kmalloc_array_init(struct kunit_resource *res, void *context) 685 { 686 struct kunit_kmalloc_array_params *params = context; 687 688 res->data = kmalloc_array(params->n, params->size, params->gfp); 689 if (!res->data) 690 return -ENOMEM; 691 692 return 0; 693 } 694 695 static void kunit_kmalloc_array_free(struct kunit_resource *res) 696 { 697 kfree(res->data); 698 } 699 700 void *kunit_kmalloc_array(struct kunit *test, size_t n, size_t size, gfp_t gfp) 701 { 702 struct kunit_kmalloc_array_params params = { 703 .size = size, 704 .n = n, 705 .gfp = gfp 706 }; 707 708 return kunit_alloc_resource(test, 709 kunit_kmalloc_array_init, 710 kunit_kmalloc_array_free, 711 gfp, 712 ¶ms); 713 } 714 EXPORT_SYMBOL_GPL(kunit_kmalloc_array); 715 716 void kunit_kfree(struct kunit *test, const void *ptr) 717 { 718 struct kunit_resource *res; 719 720 res = kunit_find_resource(test, kunit_resource_instance_match, 721 (void *)ptr); 722 723 /* 724 * Removing the resource from the list of resources drops the 725 * reference count to 1; the final put will trigger the free. 726 */ 727 kunit_remove_resource(test, res); 728 729 kunit_put_resource(res); 730 731 } 732 EXPORT_SYMBOL_GPL(kunit_kfree); 733 734 void kunit_cleanup(struct kunit *test) 735 { 736 struct kunit_resource *res; 737 unsigned long flags; 738 739 /* 740 * test->resources is a stack - each allocation must be freed in the 741 * reverse order from which it was added since one resource may depend 742 * on another for its entire lifetime. 743 * Also, we cannot use the normal list_for_each constructs, even the 744 * safe ones because *arbitrary* nodes may be deleted when 745 * kunit_resource_free is called; the list_for_each_safe variants only 746 * protect against the current node being deleted, not the next. 747 */ 748 while (true) { 749 spin_lock_irqsave(&test->lock, flags); 750 if (list_empty(&test->resources)) { 751 spin_unlock_irqrestore(&test->lock, flags); 752 break; 753 } 754 res = list_last_entry(&test->resources, 755 struct kunit_resource, 756 node); 757 /* 758 * Need to unlock here as a resource may remove another 759 * resource, and this can't happen if the test->lock 760 * is held. 761 */ 762 spin_unlock_irqrestore(&test->lock, flags); 763 kunit_remove_resource(test, res); 764 } 765 current->kunit_test = NULL; 766 } 767 EXPORT_SYMBOL_GPL(kunit_cleanup); 768 769 static int __init kunit_init(void) 770 { 771 kunit_debugfs_init(); 772 #ifdef CONFIG_MODULES 773 return register_module_notifier(&kunit_mod_nb); 774 #else 775 return 0; 776 #endif 777 } 778 late_initcall(kunit_init); 779 780 static void __exit kunit_exit(void) 781 { 782 #ifdef CONFIG_MODULES 783 unregister_module_notifier(&kunit_mod_nb); 784 #endif 785 kunit_debugfs_cleanup(); 786 } 787 module_exit(kunit_exit); 788 789 MODULE_LICENSE("GPL v2"); 790