1 // SPDX-License-Identifier: GPL-2.0
3 * Base unit test (KUnit) API.
5 * Copyright (C) 2019, Google LLC.
6 * Author: Brendan Higgins <brendanhiggins@google.com>
9 #include <kunit/test.h>
10 #include <linux/kernel.h>
11 #include <linux/kref.h>
12 #include <linux/sched/debug.h>
13 #include <linux/sched.h>
16 #include "string-stream.h"
17 #include "try-catch-impl.h"
20 * Append formatted message to log, size of which is limited to
21 * KUNIT_LOG_SIZE bytes (including null terminating byte).
23 void kunit_log_append(char *log
, const char *fmt
, ...)
25 char line
[KUNIT_LOG_SIZE
];
32 len_left
= KUNIT_LOG_SIZE
- strlen(log
) - 1;
37 vsnprintf(line
, sizeof(line
), fmt
, args
);
40 strncat(log
, line
, len_left
);
42 EXPORT_SYMBOL_GPL(kunit_log_append
);
44 size_t kunit_suite_num_test_cases(struct kunit_suite
*suite
)
46 struct kunit_case
*test_case
;
49 kunit_suite_for_each_test_case(suite
, test_case
)
54 EXPORT_SYMBOL_GPL(kunit_suite_num_test_cases
);
56 static void kunit_print_subtest_start(struct kunit_suite
*suite
)
58 kunit_log(KERN_INFO
, suite
, KUNIT_SUBTEST_INDENT
"# Subtest: %s",
60 kunit_log(KERN_INFO
, suite
, KUNIT_SUBTEST_INDENT
"1..%zd",
61 kunit_suite_num_test_cases(suite
));
64 static void kunit_print_ok_not_ok(void *test_or_suite
,
68 const char *description
)
70 struct kunit_suite
*suite
= is_test
? NULL
: test_or_suite
;
71 struct kunit
*test
= is_test
? test_or_suite
: NULL
;
74 * We do not log the test suite results as doing so would
75 * mean debugfs display would consist of the test suite
76 * description and status prior to individual test results.
77 * Hence directly printk the suite status, and we will
78 * separately seq_printf() the suite status for the debugfs
82 pr_info("%s %zd - %s\n",
83 kunit_status_to_string(is_ok
),
84 test_number
, description
);
86 kunit_log(KERN_INFO
, test
, KUNIT_SUBTEST_INDENT
"%s %zd - %s",
87 kunit_status_to_string(is_ok
),
88 test_number
, description
);
91 bool kunit_suite_has_succeeded(struct kunit_suite
*suite
)
93 const struct kunit_case
*test_case
;
95 kunit_suite_for_each_test_case(suite
, test_case
) {
96 if (!test_case
->success
)
102 EXPORT_SYMBOL_GPL(kunit_suite_has_succeeded
);
104 static void kunit_print_subtest_end(struct kunit_suite
*suite
)
106 static size_t kunit_suite_counter
= 1;
108 kunit_print_ok_not_ok((void *)suite
, false,
109 kunit_suite_has_succeeded(suite
),
110 kunit_suite_counter
++,
114 unsigned int kunit_test_case_num(struct kunit_suite
*suite
,
115 struct kunit_case
*test_case
)
117 struct kunit_case
*tc
;
120 kunit_suite_for_each_test_case(suite
, tc
) {
128 EXPORT_SYMBOL_GPL(kunit_test_case_num
);
130 static void kunit_print_string_stream(struct kunit
*test
,
131 struct string_stream
*stream
)
133 struct string_stream_fragment
*fragment
;
136 if (string_stream_is_empty(stream
))
139 buf
= string_stream_get_string(stream
);
142 "Could not allocate buffer, dumping stream:\n");
143 list_for_each_entry(fragment
, &stream
->fragments
, node
) {
144 kunit_err(test
, "%s", fragment
->fragment
);
146 kunit_err(test
, "\n");
148 kunit_err(test
, "%s", buf
);
149 kunit_kfree(test
, buf
);
153 static void kunit_fail(struct kunit
*test
, struct kunit_assert
*assert)
155 struct string_stream
*stream
;
157 kunit_set_failure(test
);
159 stream
= alloc_string_stream(test
, GFP_KERNEL
);
162 "Could not allocate stream to print failed assertion in %s:%d\n",
168 assert->format(assert, stream
);
170 kunit_print_string_stream(test
, stream
);
172 WARN_ON(string_stream_destroy(stream
));
175 static void __noreturn
kunit_abort(struct kunit
*test
)
177 kunit_try_catch_throw(&test
->try_catch
); /* Does not return. */
180 * Throw could not abort from test.
182 * XXX: we should never reach this line! As kunit_try_catch_throw is
185 WARN_ONCE(true, "Throw could not abort from test!\n");
188 void kunit_do_assertion(struct kunit
*test
,
189 struct kunit_assert
*assert,
191 const char *fmt
, ...)
200 assert->message
.fmt
= fmt
;
201 assert->message
.va
= &args
;
203 kunit_fail(test
, assert);
207 if (assert->type
== KUNIT_ASSERTION
)
210 EXPORT_SYMBOL_GPL(kunit_do_assertion
);
212 void kunit_init_test(struct kunit
*test
, const char *name
, char *log
)
214 spin_lock_init(&test
->lock
);
215 INIT_LIST_HEAD(&test
->resources
);
220 test
->success
= true;
222 EXPORT_SYMBOL_GPL(kunit_init_test
);
225 * Initializes and runs test case. Does not clean up or do post validations.
227 static void kunit_run_case_internal(struct kunit
*test
,
228 struct kunit_suite
*suite
,
229 struct kunit_case
*test_case
)
234 ret
= suite
->init(test
);
236 kunit_err(test
, "failed to initialize: %d\n", ret
);
237 kunit_set_failure(test
);
242 test_case
->run_case(test
);
245 static void kunit_case_internal_cleanup(struct kunit
*test
)
251 * Performs post validations and cleanup after a test case was run.
252 * XXX: Should ONLY BE CALLED AFTER kunit_run_case_internal!
254 static void kunit_run_case_cleanup(struct kunit
*test
,
255 struct kunit_suite
*suite
)
260 kunit_case_internal_cleanup(test
);
263 struct kunit_try_catch_context
{
265 struct kunit_suite
*suite
;
266 struct kunit_case
*test_case
;
269 static void kunit_try_run_case(void *data
)
271 struct kunit_try_catch_context
*ctx
= data
;
272 struct kunit
*test
= ctx
->test
;
273 struct kunit_suite
*suite
= ctx
->suite
;
274 struct kunit_case
*test_case
= ctx
->test_case
;
276 #if (IS_ENABLED(CONFIG_KASAN) && IS_ENABLED(CONFIG_KUNIT))
277 current
->kunit_test
= test
;
278 #endif /* IS_ENABLED(CONFIG_KASAN) && IS_ENABLED(CONFIG_KUNIT) */
281 * kunit_run_case_internal may encounter a fatal error; if it does,
282 * abort will be called, this thread will exit, and finally the parent
283 * thread will resume control and handle any necessary clean up.
285 kunit_run_case_internal(test
, suite
, test_case
);
286 /* This line may never be reached. */
287 kunit_run_case_cleanup(test
, suite
);
290 static void kunit_catch_run_case(void *data
)
292 struct kunit_try_catch_context
*ctx
= data
;
293 struct kunit
*test
= ctx
->test
;
294 struct kunit_suite
*suite
= ctx
->suite
;
295 int try_exit_code
= kunit_try_catch_get_result(&test
->try_catch
);
298 kunit_set_failure(test
);
300 * Test case could not finish, we have no idea what state it is
301 * in, so don't do clean up.
303 if (try_exit_code
== -ETIMEDOUT
) {
304 kunit_err(test
, "test case timed out\n");
306 * Unknown internal error occurred preventing test case from
307 * running, so there is nothing to clean up.
310 kunit_err(test
, "internal error occurred preventing test case from running: %d\n",
317 * Test case was run, but aborted. It is the test case's business as to
318 * whether it failed or not, we just need to clean up.
320 kunit_run_case_cleanup(test
, suite
);
324 * Performs all logic to run a test case. It also catches most errors that
325 * occur in a test case and reports them as failures.
327 static void kunit_run_case_catch_errors(struct kunit_suite
*suite
,
328 struct kunit_case
*test_case
)
330 struct kunit_try_catch_context context
;
331 struct kunit_try_catch
*try_catch
;
334 kunit_init_test(&test
, test_case
->name
, test_case
->log
);
335 try_catch
= &test
.try_catch
;
337 kunit_try_catch_init(try_catch
,
340 kunit_catch_run_case
);
341 context
.test
= &test
;
342 context
.suite
= suite
;
343 context
.test_case
= test_case
;
344 kunit_try_catch_run(try_catch
, &context
);
346 test_case
->success
= test
.success
;
348 kunit_print_ok_not_ok(&test
, true, test_case
->success
,
349 kunit_test_case_num(suite
, test_case
),
353 int kunit_run_tests(struct kunit_suite
*suite
)
355 struct kunit_case
*test_case
;
357 kunit_print_subtest_start(suite
);
359 kunit_suite_for_each_test_case(suite
, test_case
)
360 kunit_run_case_catch_errors(suite
, test_case
);
362 kunit_print_subtest_end(suite
);
366 EXPORT_SYMBOL_GPL(kunit_run_tests
);
368 static void kunit_init_suite(struct kunit_suite
*suite
)
370 kunit_debugfs_create_suite(suite
);
373 int __kunit_test_suites_init(struct kunit_suite
* const * const suites
)
377 for (i
= 0; suites
[i
] != NULL
; i
++) {
378 kunit_init_suite(suites
[i
]);
379 kunit_run_tests(suites
[i
]);
383 EXPORT_SYMBOL_GPL(__kunit_test_suites_init
);
385 static void kunit_exit_suite(struct kunit_suite
*suite
)
387 kunit_debugfs_destroy_suite(suite
);
390 void __kunit_test_suites_exit(struct kunit_suite
**suites
)
394 for (i
= 0; suites
[i
] != NULL
; i
++)
395 kunit_exit_suite(suites
[i
]);
397 EXPORT_SYMBOL_GPL(__kunit_test_suites_exit
);
400 * Used for static resources and when a kunit_resource * has been created by
401 * kunit_alloc_resource(). When an init function is supplied, @data is passed
402 * into the init function; otherwise, we simply set the resource data field to
403 * the data value passed in.
405 int kunit_add_resource(struct kunit
*test
,
406 kunit_resource_init_t init
,
407 kunit_resource_free_t free
,
408 struct kunit_resource
*res
,
414 kref_init(&res
->refcount
);
417 ret
= init(res
, data
);
424 spin_lock(&test
->lock
);
425 list_add_tail(&res
->node
, &test
->resources
);
426 /* refcount for list is established by kref_init() */
427 spin_unlock(&test
->lock
);
431 EXPORT_SYMBOL_GPL(kunit_add_resource
);
433 int kunit_add_named_resource(struct kunit
*test
,
434 kunit_resource_init_t init
,
435 kunit_resource_free_t free
,
436 struct kunit_resource
*res
,
440 struct kunit_resource
*existing
;
445 existing
= kunit_find_named_resource(test
, name
);
447 kunit_put_resource(existing
);
453 return kunit_add_resource(test
, init
, free
, res
, data
);
455 EXPORT_SYMBOL_GPL(kunit_add_named_resource
);
457 struct kunit_resource
*kunit_alloc_and_get_resource(struct kunit
*test
,
458 kunit_resource_init_t init
,
459 kunit_resource_free_t free
,
463 struct kunit_resource
*res
;
466 res
= kzalloc(sizeof(*res
), internal_gfp
);
470 ret
= kunit_add_resource(test
, init
, free
, res
, data
);
473 * bump refcount for get; kunit_resource_put() should be called
476 kunit_get_resource(res
);
481 EXPORT_SYMBOL_GPL(kunit_alloc_and_get_resource
);
483 void kunit_remove_resource(struct kunit
*test
, struct kunit_resource
*res
)
485 spin_lock(&test
->lock
);
486 list_del(&res
->node
);
487 spin_unlock(&test
->lock
);
488 kunit_put_resource(res
);
490 EXPORT_SYMBOL_GPL(kunit_remove_resource
);
492 int kunit_destroy_resource(struct kunit
*test
, kunit_resource_match_t match
,
495 struct kunit_resource
*res
= kunit_find_resource(test
, match
,
501 kunit_remove_resource(test
, res
);
503 /* We have a reference also via _find(); drop it. */
504 kunit_put_resource(res
);
508 EXPORT_SYMBOL_GPL(kunit_destroy_resource
);
510 struct kunit_kmalloc_params
{
515 static int kunit_kmalloc_init(struct kunit_resource
*res
, void *context
)
517 struct kunit_kmalloc_params
*params
= context
;
519 res
->data
= kmalloc(params
->size
, params
->gfp
);
526 static void kunit_kmalloc_free(struct kunit_resource
*res
)
531 void *kunit_kmalloc(struct kunit
*test
, size_t size
, gfp_t gfp
)
533 struct kunit_kmalloc_params params
= {
538 return kunit_alloc_resource(test
,
544 EXPORT_SYMBOL_GPL(kunit_kmalloc
);
546 void kunit_kfree(struct kunit
*test
, const void *ptr
)
548 struct kunit_resource
*res
;
550 res
= kunit_find_resource(test
, kunit_resource_instance_match
,
554 * Removing the resource from the list of resources drops the
555 * reference count to 1; the final put will trigger the free.
557 kunit_remove_resource(test
, res
);
559 kunit_put_resource(res
);
562 EXPORT_SYMBOL_GPL(kunit_kfree
);
564 void kunit_cleanup(struct kunit
*test
)
566 struct kunit_resource
*res
;
569 * test->resources is a stack - each allocation must be freed in the
570 * reverse order from which it was added since one resource may depend
571 * on another for its entire lifetime.
572 * Also, we cannot use the normal list_for_each constructs, even the
573 * safe ones because *arbitrary* nodes may be deleted when
574 * kunit_resource_free is called; the list_for_each_safe variants only
575 * protect against the current node being deleted, not the next.
578 spin_lock(&test
->lock
);
579 if (list_empty(&test
->resources
)) {
580 spin_unlock(&test
->lock
);
583 res
= list_last_entry(&test
->resources
,
584 struct kunit_resource
,
587 * Need to unlock here as a resource may remove another
588 * resource, and this can't happen if the test->lock
591 spin_unlock(&test
->lock
);
592 kunit_remove_resource(test
, res
);
594 #if (IS_ENABLED(CONFIG_KASAN) && IS_ENABLED(CONFIG_KUNIT))
595 current
->kunit_test
= NULL
;
596 #endif /* IS_ENABLED(CONFIG_KASAN) && IS_ENABLED(CONFIG_KUNIT)*/
598 EXPORT_SYMBOL_GPL(kunit_cleanup
);
600 static int __init
kunit_init(void)
602 kunit_debugfs_init();
606 late_initcall(kunit_init
);
608 static void __exit
kunit_exit(void)
610 kunit_debugfs_cleanup();
612 module_exit(kunit_exit
);
614 MODULE_LICENSE("GPL v2");