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