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/test.h> 10 #include <linux/kernel.h> 11 #include <linux/kref.h> 12 #include <linux/sched/debug.h> 13 14 #include "debugfs.h" 15 #include "string-stream.h" 16 #include "try-catch-impl.h" 17 18 static void kunit_set_failure(struct kunit *test) 19 { 20 WRITE_ONCE(test->success, false); 21 } 22 23 static void kunit_print_tap_version(void) 24 { 25 static bool kunit_has_printed_tap_version; 26 27 if (!kunit_has_printed_tap_version) { 28 pr_info("TAP version 14\n"); 29 kunit_has_printed_tap_version = true; 30 } 31 } 32 33 /* 34 * Append formatted message to log, size of which is limited to 35 * KUNIT_LOG_SIZE bytes (including null terminating byte). 36 */ 37 void kunit_log_append(char *log, const char *fmt, ...) 38 { 39 char line[KUNIT_LOG_SIZE]; 40 va_list args; 41 int len_left; 42 43 if (!log) 44 return; 45 46 len_left = KUNIT_LOG_SIZE - strlen(log) - 1; 47 if (len_left <= 0) 48 return; 49 50 va_start(args, fmt); 51 vsnprintf(line, sizeof(line), fmt, args); 52 va_end(args); 53 54 strncat(log, line, len_left); 55 } 56 EXPORT_SYMBOL_GPL(kunit_log_append); 57 58 size_t kunit_suite_num_test_cases(struct kunit_suite *suite) 59 { 60 struct kunit_case *test_case; 61 size_t len = 0; 62 63 kunit_suite_for_each_test_case(suite, test_case) 64 len++; 65 66 return len; 67 } 68 EXPORT_SYMBOL_GPL(kunit_suite_num_test_cases); 69 70 static void kunit_print_subtest_start(struct kunit_suite *suite) 71 { 72 kunit_print_tap_version(); 73 kunit_log(KERN_INFO, suite, KUNIT_SUBTEST_INDENT "# Subtest: %s", 74 suite->name); 75 kunit_log(KERN_INFO, suite, KUNIT_SUBTEST_INDENT "1..%zd", 76 kunit_suite_num_test_cases(suite)); 77 } 78 79 static void kunit_print_ok_not_ok(void *test_or_suite, 80 bool is_test, 81 bool is_ok, 82 size_t test_number, 83 const char *description) 84 { 85 struct kunit_suite *suite = is_test ? NULL : test_or_suite; 86 struct kunit *test = is_test ? test_or_suite : NULL; 87 88 /* 89 * We do not log the test suite results as doing so would 90 * mean debugfs display would consist of the test suite 91 * description and status prior to individual test results. 92 * Hence directly printk the suite status, and we will 93 * separately seq_printf() the suite status for the debugfs 94 * representation. 95 */ 96 if (suite) 97 pr_info("%s %zd - %s\n", 98 kunit_status_to_string(is_ok), 99 test_number, description); 100 else 101 kunit_log(KERN_INFO, test, KUNIT_SUBTEST_INDENT "%s %zd - %s", 102 kunit_status_to_string(is_ok), 103 test_number, description); 104 } 105 106 bool kunit_suite_has_succeeded(struct kunit_suite *suite) 107 { 108 const struct kunit_case *test_case; 109 110 kunit_suite_for_each_test_case(suite, test_case) { 111 if (!test_case->success) 112 return false; 113 } 114 115 return true; 116 } 117 EXPORT_SYMBOL_GPL(kunit_suite_has_succeeded); 118 119 static void kunit_print_subtest_end(struct kunit_suite *suite) 120 { 121 static size_t kunit_suite_counter = 1; 122 123 kunit_print_ok_not_ok((void *)suite, false, 124 kunit_suite_has_succeeded(suite), 125 kunit_suite_counter++, 126 suite->name); 127 } 128 129 unsigned int kunit_test_case_num(struct kunit_suite *suite, 130 struct kunit_case *test_case) 131 { 132 struct kunit_case *tc; 133 unsigned int i = 1; 134 135 kunit_suite_for_each_test_case(suite, tc) { 136 if (tc == test_case) 137 return i; 138 i++; 139 } 140 141 return 0; 142 } 143 EXPORT_SYMBOL_GPL(kunit_test_case_num); 144 145 static void kunit_print_string_stream(struct kunit *test, 146 struct string_stream *stream) 147 { 148 struct string_stream_fragment *fragment; 149 char *buf; 150 151 if (string_stream_is_empty(stream)) 152 return; 153 154 buf = string_stream_get_string(stream); 155 if (!buf) { 156 kunit_err(test, 157 "Could not allocate buffer, dumping stream:\n"); 158 list_for_each_entry(fragment, &stream->fragments, node) { 159 kunit_err(test, "%s", fragment->fragment); 160 } 161 kunit_err(test, "\n"); 162 } else { 163 kunit_err(test, "%s", buf); 164 kunit_kfree(test, buf); 165 } 166 } 167 168 static void kunit_fail(struct kunit *test, struct kunit_assert *assert) 169 { 170 struct string_stream *stream; 171 172 kunit_set_failure(test); 173 174 stream = alloc_string_stream(test, GFP_KERNEL); 175 if (!stream) { 176 WARN(true, 177 "Could not allocate stream to print failed assertion in %s:%d\n", 178 assert->file, 179 assert->line); 180 return; 181 } 182 183 assert->format(assert, stream); 184 185 kunit_print_string_stream(test, stream); 186 187 WARN_ON(string_stream_destroy(stream)); 188 } 189 190 static void __noreturn kunit_abort(struct kunit *test) 191 { 192 kunit_try_catch_throw(&test->try_catch); /* Does not return. */ 193 194 /* 195 * Throw could not abort from test. 196 * 197 * XXX: we should never reach this line! As kunit_try_catch_throw is 198 * marked __noreturn. 199 */ 200 WARN_ONCE(true, "Throw could not abort from test!\n"); 201 } 202 203 void kunit_do_assertion(struct kunit *test, 204 struct kunit_assert *assert, 205 bool pass, 206 const char *fmt, ...) 207 { 208 va_list args; 209 210 if (pass) 211 return; 212 213 va_start(args, fmt); 214 215 assert->message.fmt = fmt; 216 assert->message.va = &args; 217 218 kunit_fail(test, assert); 219 220 va_end(args); 221 222 if (assert->type == KUNIT_ASSERTION) 223 kunit_abort(test); 224 } 225 EXPORT_SYMBOL_GPL(kunit_do_assertion); 226 227 void kunit_init_test(struct kunit *test, const char *name, char *log) 228 { 229 spin_lock_init(&test->lock); 230 INIT_LIST_HEAD(&test->resources); 231 test->name = name; 232 test->log = log; 233 if (test->log) 234 test->log[0] = '\0'; 235 test->success = true; 236 } 237 EXPORT_SYMBOL_GPL(kunit_init_test); 238 239 /* 240 * Initializes and runs test case. Does not clean up or do post validations. 241 */ 242 static void kunit_run_case_internal(struct kunit *test, 243 struct kunit_suite *suite, 244 struct kunit_case *test_case) 245 { 246 if (suite->init) { 247 int ret; 248 249 ret = suite->init(test); 250 if (ret) { 251 kunit_err(test, "failed to initialize: %d\n", ret); 252 kunit_set_failure(test); 253 return; 254 } 255 } 256 257 test_case->run_case(test); 258 } 259 260 static void kunit_case_internal_cleanup(struct kunit *test) 261 { 262 kunit_cleanup(test); 263 } 264 265 /* 266 * Performs post validations and cleanup after a test case was run. 267 * XXX: Should ONLY BE CALLED AFTER kunit_run_case_internal! 268 */ 269 static void kunit_run_case_cleanup(struct kunit *test, 270 struct kunit_suite *suite) 271 { 272 if (suite->exit) 273 suite->exit(test); 274 275 kunit_case_internal_cleanup(test); 276 } 277 278 struct kunit_try_catch_context { 279 struct kunit *test; 280 struct kunit_suite *suite; 281 struct kunit_case *test_case; 282 }; 283 284 static void kunit_try_run_case(void *data) 285 { 286 struct kunit_try_catch_context *ctx = data; 287 struct kunit *test = ctx->test; 288 struct kunit_suite *suite = ctx->suite; 289 struct kunit_case *test_case = ctx->test_case; 290 291 /* 292 * kunit_run_case_internal may encounter a fatal error; if it does, 293 * abort will be called, this thread will exit, and finally the parent 294 * thread will resume control and handle any necessary clean up. 295 */ 296 kunit_run_case_internal(test, suite, test_case); 297 /* This line may never be reached. */ 298 kunit_run_case_cleanup(test, suite); 299 } 300 301 static void kunit_catch_run_case(void *data) 302 { 303 struct kunit_try_catch_context *ctx = data; 304 struct kunit *test = ctx->test; 305 struct kunit_suite *suite = ctx->suite; 306 int try_exit_code = kunit_try_catch_get_result(&test->try_catch); 307 308 if (try_exit_code) { 309 kunit_set_failure(test); 310 /* 311 * Test case could not finish, we have no idea what state it is 312 * in, so don't do clean up. 313 */ 314 if (try_exit_code == -ETIMEDOUT) { 315 kunit_err(test, "test case timed out\n"); 316 /* 317 * Unknown internal error occurred preventing test case from 318 * running, so there is nothing to clean up. 319 */ 320 } else { 321 kunit_err(test, "internal error occurred preventing test case from running: %d\n", 322 try_exit_code); 323 } 324 return; 325 } 326 327 /* 328 * Test case was run, but aborted. It is the test case's business as to 329 * whether it failed or not, we just need to clean up. 330 */ 331 kunit_run_case_cleanup(test, suite); 332 } 333 334 /* 335 * Performs all logic to run a test case. It also catches most errors that 336 * occur in a test case and reports them as failures. 337 */ 338 static void kunit_run_case_catch_errors(struct kunit_suite *suite, 339 struct kunit_case *test_case) 340 { 341 struct kunit_try_catch_context context; 342 struct kunit_try_catch *try_catch; 343 struct kunit test; 344 345 kunit_init_test(&test, test_case->name, test_case->log); 346 try_catch = &test.try_catch; 347 348 kunit_try_catch_init(try_catch, 349 &test, 350 kunit_try_run_case, 351 kunit_catch_run_case); 352 context.test = &test; 353 context.suite = suite; 354 context.test_case = test_case; 355 kunit_try_catch_run(try_catch, &context); 356 357 test_case->success = test.success; 358 359 kunit_print_ok_not_ok(&test, true, test_case->success, 360 kunit_test_case_num(suite, test_case), 361 test_case->name); 362 } 363 364 int kunit_run_tests(struct kunit_suite *suite) 365 { 366 struct kunit_case *test_case; 367 368 kunit_print_subtest_start(suite); 369 370 kunit_suite_for_each_test_case(suite, test_case) 371 kunit_run_case_catch_errors(suite, test_case); 372 373 kunit_print_subtest_end(suite); 374 375 return 0; 376 } 377 EXPORT_SYMBOL_GPL(kunit_run_tests); 378 379 static void kunit_init_suite(struct kunit_suite *suite) 380 { 381 kunit_debugfs_create_suite(suite); 382 } 383 384 int __kunit_test_suites_init(struct kunit_suite **suites) 385 { 386 unsigned int i; 387 388 for (i = 0; suites[i] != NULL; i++) { 389 kunit_init_suite(suites[i]); 390 kunit_run_tests(suites[i]); 391 } 392 return 0; 393 } 394 EXPORT_SYMBOL_GPL(__kunit_test_suites_init); 395 396 static void kunit_exit_suite(struct kunit_suite *suite) 397 { 398 kunit_debugfs_destroy_suite(suite); 399 } 400 401 void __kunit_test_suites_exit(struct kunit_suite **suites) 402 { 403 unsigned int i; 404 405 for (i = 0; suites[i] != NULL; i++) 406 kunit_exit_suite(suites[i]); 407 } 408 EXPORT_SYMBOL_GPL(__kunit_test_suites_exit); 409 410 /* 411 * Used for static resources and when a kunit_resource * has been created by 412 * kunit_alloc_resource(). When an init function is supplied, @data is passed 413 * into the init function; otherwise, we simply set the resource data field to 414 * the data value passed in. 415 */ 416 int kunit_add_resource(struct kunit *test, 417 kunit_resource_init_t init, 418 kunit_resource_free_t free, 419 struct kunit_resource *res, 420 void *data) 421 { 422 int ret = 0; 423 424 res->free = free; 425 kref_init(&res->refcount); 426 427 if (init) { 428 ret = init(res, data); 429 if (ret) 430 return ret; 431 } else { 432 res->data = data; 433 } 434 435 spin_lock(&test->lock); 436 list_add_tail(&res->node, &test->resources); 437 /* refcount for list is established by kref_init() */ 438 spin_unlock(&test->lock); 439 440 return ret; 441 } 442 EXPORT_SYMBOL_GPL(kunit_add_resource); 443 444 int kunit_add_named_resource(struct kunit *test, 445 kunit_resource_init_t init, 446 kunit_resource_free_t free, 447 struct kunit_resource *res, 448 const char *name, 449 void *data) 450 { 451 struct kunit_resource *existing; 452 453 if (!name) 454 return -EINVAL; 455 456 existing = kunit_find_named_resource(test, name); 457 if (existing) { 458 kunit_put_resource(existing); 459 return -EEXIST; 460 } 461 462 res->name = name; 463 464 return kunit_add_resource(test, init, free, res, data); 465 } 466 EXPORT_SYMBOL_GPL(kunit_add_named_resource); 467 468 struct kunit_resource *kunit_alloc_and_get_resource(struct kunit *test, 469 kunit_resource_init_t init, 470 kunit_resource_free_t free, 471 gfp_t internal_gfp, 472 void *data) 473 { 474 struct kunit_resource *res; 475 int ret; 476 477 res = kzalloc(sizeof(*res), internal_gfp); 478 if (!res) 479 return NULL; 480 481 ret = kunit_add_resource(test, init, free, res, data); 482 if (!ret) { 483 /* 484 * bump refcount for get; kunit_resource_put() should be called 485 * when done. 486 */ 487 kunit_get_resource(res); 488 return res; 489 } 490 return NULL; 491 } 492 EXPORT_SYMBOL_GPL(kunit_alloc_and_get_resource); 493 494 void kunit_remove_resource(struct kunit *test, struct kunit_resource *res) 495 { 496 spin_lock(&test->lock); 497 list_del(&res->node); 498 spin_unlock(&test->lock); 499 kunit_put_resource(res); 500 } 501 EXPORT_SYMBOL_GPL(kunit_remove_resource); 502 503 int kunit_destroy_resource(struct kunit *test, kunit_resource_match_t match, 504 void *match_data) 505 { 506 struct kunit_resource *res = kunit_find_resource(test, match, 507 match_data); 508 509 if (!res) 510 return -ENOENT; 511 512 kunit_remove_resource(test, res); 513 514 /* We have a reference also via _find(); drop it. */ 515 kunit_put_resource(res); 516 517 return 0; 518 } 519 EXPORT_SYMBOL_GPL(kunit_destroy_resource); 520 521 struct kunit_kmalloc_params { 522 size_t size; 523 gfp_t gfp; 524 }; 525 526 static int kunit_kmalloc_init(struct kunit_resource *res, void *context) 527 { 528 struct kunit_kmalloc_params *params = context; 529 530 res->data = kmalloc(params->size, params->gfp); 531 if (!res->data) 532 return -ENOMEM; 533 534 return 0; 535 } 536 537 static void kunit_kmalloc_free(struct kunit_resource *res) 538 { 539 kfree(res->data); 540 } 541 542 void *kunit_kmalloc(struct kunit *test, size_t size, gfp_t gfp) 543 { 544 struct kunit_kmalloc_params params = { 545 .size = size, 546 .gfp = gfp 547 }; 548 549 return kunit_alloc_resource(test, 550 kunit_kmalloc_init, 551 kunit_kmalloc_free, 552 gfp, 553 ¶ms); 554 } 555 EXPORT_SYMBOL_GPL(kunit_kmalloc); 556 557 void kunit_kfree(struct kunit *test, const void *ptr) 558 { 559 struct kunit_resource *res; 560 561 res = kunit_find_resource(test, kunit_resource_instance_match, 562 (void *)ptr); 563 564 /* 565 * Removing the resource from the list of resources drops the 566 * reference count to 1; the final put will trigger the free. 567 */ 568 kunit_remove_resource(test, res); 569 570 kunit_put_resource(res); 571 572 } 573 EXPORT_SYMBOL_GPL(kunit_kfree); 574 575 void kunit_cleanup(struct kunit *test) 576 { 577 struct kunit_resource *res; 578 579 /* 580 * test->resources is a stack - each allocation must be freed in the 581 * reverse order from which it was added since one resource may depend 582 * on another for its entire lifetime. 583 * Also, we cannot use the normal list_for_each constructs, even the 584 * safe ones because *arbitrary* nodes may be deleted when 585 * kunit_resource_free is called; the list_for_each_safe variants only 586 * protect against the current node being deleted, not the next. 587 */ 588 while (true) { 589 spin_lock(&test->lock); 590 if (list_empty(&test->resources)) { 591 spin_unlock(&test->lock); 592 break; 593 } 594 res = list_last_entry(&test->resources, 595 struct kunit_resource, 596 node); 597 /* 598 * Need to unlock here as a resource may remove another 599 * resource, and this can't happen if the test->lock 600 * is held. 601 */ 602 spin_unlock(&test->lock); 603 kunit_remove_resource(test, res); 604 } 605 } 606 EXPORT_SYMBOL_GPL(kunit_cleanup); 607 608 static int __init kunit_init(void) 609 { 610 kunit_debugfs_init(); 611 612 return 0; 613 } 614 late_initcall(kunit_init); 615 616 static void __exit kunit_exit(void) 617 { 618 kunit_debugfs_cleanup(); 619 } 620 module_exit(kunit_exit); 621 622 MODULE_LICENSE("GPL v2"); 623