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/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                                     &params);
 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");