lib/kunit/test.c

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