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