On Wed, 30 Jul 2025 at 03:37, Marie Zhussupova marievic@google.com wrote:

Add `param_init` and `param_exit` function pointers to `struct kunit_case`. Users will be able to set them via the new `KUNIT_CASE_PARAM_WITH_INIT` macro.

These functions are invoked by kunit_run_tests() once before and once after the entire parameterized test series, respectively. They will receive the parent kunit test instance, allowing users to register and manage shared resources. Resources added to this parent kunit test will be accessible to all individual parameterized tests, facilitating init and exit for shared state.

Signed-off-by: Marie Zhussupova marievic@google.com

Thanks: this looks good to me, modulo the issues below (particularly the Rust breakage).

I was initially unsure of the names 'param_init' and 'param_exit', preferring just 'init'/'exit', but have since come to like it, as otherwise it'd be easy to confuse it with the kunit_suite init/exit functions, which behave differently. So happy to keep that.

With the Rust issue fixes, this is: Reviewed-by: David Gow davidgow@google.com

Cheers, -- David

include/kunit/test.h | 33 ++++++++++++++++++++++++++++++++- lib/kunit/test.c | 23 ++++++++++++++++++++++- 2 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/include/kunit/test.h b/include/kunit/test.h index a42d0c8cb985..d8dac7efd745 100644 --- a/include/kunit/test.h +++ b/include/kunit/test.h @@ -92,6 +92,8 @@ struct kunit_attributes {

• @name: the name of the test case.
• @generate_params: the generator function for parameterized tests.
• @attr: the attributes associated with the test

• • @param_init: The init function to run before parameterized tests.
• • @param_exit: The exit function to run after parameterized tests.
  • A test case is a function with the signature,
  • ``void (*)(struct kunit *)``

@@ -129,6 +131,13 @@ struct kunit_case { const void* (*generate_params)(const void *prev, char *desc); struct kunit_attributes attr;

•   /*
  

•    * Optional user-defined functions: one to register shared resources once
  

•    * before the parameterized test series, and another to release them after.
  

•    */
  

•   int (*param_init)(struct kunit *test);
  

•   void (*param_exit)(struct kunit *test);
  

As noted by the test robot, these need to be initialised in rust/kernel/kunit.rs when a kunit_case is being set up. Since parameterised tests aren't used in Rust, they can just be set to None.

    /* private: internal use only. */
    enum kunit_status status;
    char *module_name;

@@ -218,6 +227,27 @@ static inline char *kunit_status_to_ok_not_ok(enum kunit_status status) .generate_params = gen_params, \ .attr = attributes, .module_name = KBUILD_MODNAME}

+/**

• • KUNIT_CASE_PARAM_WITH_INIT() - Define a parameterized KUnit test case with custom
• • init and exit functions.
• • @test_name: The function implementing the test case.
• • @gen_params: The function to generate parameters for the test case.
• • @init: The init function to run before parameterized tests.
• • @exit: The exit function to run after parameterized tests.
• • Provides the option to register init and exit functions that take in the
• • parent of the parameterized tests and run once before and once after the
• • parameterized test series. The init function can be used to add any resources
• • to share between the parameterized tests or to pass parameter arrays. The
• • exit function can be used to clean up any resources that are not managed by
• • the test.
• */

+#define KUNIT_CASE_PARAM_WITH_INIT(test_name, gen_params, init, exit) \

•           { .run_case = test_name, .name = #test_name,                    \
  

•             .generate_params = gen_params,                                \
  

•             .param_init = init, .param_exit = exit,                       \
  

•             .module_name = KBUILD_MODNAME}
  

/**

• struct kunit_suite - describes a related collection of &struct kunit_case

@@ -269,7 +299,8 @@ struct kunit_suite_set {

• @priv: for user to store arbitrary data. Commonly used to pass data

•   created in the init function (see &struct kunit_suite).
  

• @parent: for user to store data that they want to shared across

• •     parameterized tests.
    

• •     parameterized tests. Typically, the data is provided in
    

• •     the param_init function (see &struct kunit_case).
    

  • Used to store information about the current context under which the test
  • is running. Most of this data is private and should only be accessed

diff --git a/lib/kunit/test.c b/lib/kunit/test.c index 4d6a39eb2c80..d80b5990d85d 100644 --- a/lib/kunit/test.c +++ b/lib/kunit/test.c @@ -641,6 +641,19 @@ static void kunit_accumulate_stats(struct kunit_result_stats *total, total->total += add.total; }

+static void __kunit_init_parent_test(struct kunit_case *test_case, struct kunit *test)

There's no fundamental reason this needs to start '__': other internal functions here don't.

(But please keep it static and internal.)

+{

•   if (test_case->param_init) {
  

•           int err = test_case->param_init(test);
  

•           if (err) {
  

•                   kunit_err(test_case, KUNIT_SUBTEST_INDENT KUNIT_SUBTEST_INDENT
  

•                           "# failed to initialize parent parameter test.");
  

•                   test_case->status = KUNIT_FAILURE;
  

•           }
  

•   }
  

+}

int kunit_run_tests(struct kunit_suite *suite) { char param_desc[KUNIT_PARAM_DESC_SIZE]; @@ -668,6 +681,8 @@ int kunit_run_tests(struct kunit_suite *suite) struct kunit_result_stats param_stats = { 0 };

            kunit_init_test(&test, test_case->name, test_case->log);

•           __kunit_init_parent_test(test_case, &test);
  

•           if (test_case->status == KUNIT_SKIPPED) {
                    /* Test marked as skip */
                    test.status = KUNIT_SKIPPED;
  

@@ -677,7 +692,7 @@ int kunit_run_tests(struct kunit_suite *suite) test_case->status = KUNIT_SKIPPED; kunit_run_case_catch_errors(suite, test_case, &test); kunit_update_stats(&param_stats, test.status);

•           } else {
  

•           } else if (test_case->status != KUNIT_FAILURE) {
                    /* Get initial param. */
                    param_desc[0] = '\0';
                    /* TODO: Make generate_params try-catch */
  

@@ -727,6 +742,12 @@ int kunit_run_tests(struct kunit_suite *suite)

            kunit_update_stats(&suite_stats, test_case->status);
            kunit_accumulate_stats(&total_stats, param_stats);

•           /*
  

•            * TODO: Put into a try catch. Since we don't need suite->exit
  

•            * for it we can't reuse kunit_try_run_cleanup for this yet.
  

•            */
  

•           if (test_case->param_exit)
  

•                   test_case->param_exit(&test);
  

Not thrilled that this is introducing another TODO here, but since we already have a number of places around parameterised tests where we're not running things from the separate try-catch thread, I don't think we should hold up useful features on it. The actual test code is still properly handled.

But I'm looking forward to going through and cleaning all of these up at some point.

            /* TODO: Put this kunit_cleanup into a try-catch. */
            kunit_cleanup(&test);
    }

-- 2.50.1.552.g942d659e1b-goog

On Tue, Jul 29, 2025 at 4:14 PM Rae Moar rmoar@google.com wrote:

On Tue, Jul 29, 2025 at 3:37 PM Marie Zhussupova marievic@google.com wrote:

...

KUnit parameterized tests currently support two primary methods for getting parameters:

1. Defining custom logic within a `generate_params` function.
2. Using the KUNIT_ARRAY_PARAM and KUNIT_ARRAY_PARAM_DESC macros with pre-defined static arrays.

These methods present limitations when dealing with dynamically generated parameter arrays, or in scenarios where populating parameters sequentially via `generate_params` is inefficient or overly complex.

This patch addresses these limitations by adding a new `params_data` field to `struct kunit`, of the type `kunit_params`. The struct `kunit_params` is designed to store the parameter array itself, along with essential metadata including the parameter count, parameter size, and a `get_description` function for providing custom descriptions for individual parameters.

The `params_data` field can be populated by calling the new `kunit_register_params_array` macro from within a `param_init` function. By attaching the parameter array directly to the parent kunit test instance, these parameters can be iterated over in kunit_run_tests() behind the scenes.

This modification provides greater flexibility to the KUnit framework, allowing testers to easily register and utilize both dynamic and static parameter arrays.

Signed-off-by: Marie Zhussupova marievic@google.com

include/kunit/test.h | 54 ++++++++++++++++++++++++++++++++++++++++---- lib/kunit/test.c | 26 ++++++++++++++++++++- 2 files changed, 75 insertions(+), 5 deletions(-)

diff --git a/include/kunit/test.h b/include/kunit/test.h index 4ba65dc35710..9143f0e22323 100644 --- a/include/kunit/test.h +++ b/include/kunit/test.h @@ -245,7 +245,8 @@ static inline char *kunit_status_to_ok_not_ok(enum kunit_status status) */ #define KUNIT_CASE_PARAM_WITH_INIT(test_name, gen_params, init, exit) \ { .run_case = test_name, .name = #test_name, \

•             .generate_params = gen_params,                                \
  

•             .generate_params = (gen_params)                               \
  

•              ?: kunit_get_next_param_and_desc,                            \
              .param_init = init, .param_exit = exit,                       \
              .module_name = KBUILD_MODNAME}
  
  

@@ -294,6 +295,21 @@ struct kunit_suite_set { struct kunit_suite * const *end; };

+/* Stores the pointer to the parameter array and its metadata. */ +struct kunit_params {

•   /*
  

•    * Reference to the parameter array for the parameterized tests. This
  

•    * is NULL if a parameter array wasn't directly passed to the
  

•    * parent kunit struct via the kunit_register_params_array macro.
  

•    */
  

•   const void *params;
  

•   /* Reference to a function that gets the description of a parameter. */
  

•   void (*get_description)(const void *param, char *desc);
  

•   int num_params;
  

•   size_t elem_size;
  

+};

/**

• struct kunit - represents a running instance of a test.

@@ -302,12 +318,14 @@ struct kunit_suite_set {

• @parent: for user to store data that they want to shared across

•     parameterized tests. Typically, the data is provided in
  

•     the param_init function (see &struct kunit_case).
  

• • @params_data: for users to directly store the parameter array.
  • Used to store information about the current context under which the test
  • is running. Most of this data is private and should only be accessed

• • indirectly via public functions; the two exceptions are @priv and @parent
• • which can be used by the test writer to store arbitrary data or data that is
• • available to all parameter test executions, respectively.

• • indirectly via public functions. There are three exceptions to this: @priv,
• • @parent, and @params_data. These members can be used by the test writer to
• • store arbitrary data, data available to all parameter test executions, and
• • the parameter array, respectively.
  */

struct kunit { void *priv; @@ -316,6 +334,8 @@ struct kunit { * during parameterized testing. */ struct kunit *parent;

•   /* Stores the params array and all data related to it. */
  

•   struct kunit_params params_data;
  
    /* private: internal use only. */
    const char *name; /* Read only after initialization! */
  

@@ -386,6 +406,8 @@ void kunit_exec_list_tests(struct kunit_suite_set *suite_set, bool include_attr) struct kunit_suite_set kunit_merge_suite_sets(struct kunit_suite_set init_suite_set, struct kunit_suite_set suite_set);

+const void *kunit_get_next_param_and_desc(struct kunit *test, const void *prev, char *desc);

Hello!

Thanks for sending out this series! I will do a full review of it. For now, I noticed that I get an error when I try to run KUnit tests as modules. I get the following error: "ERROR: modpost: "kunit_get_next_param_and_desc" [lib/kunit/kunit-example-test.ko] undefined!". As a possible fix, I suggest moving the function definition into the header file and making it a static inline function.

Thanks! -Rae

Hello! Feel free to also use EXPORT_SYMBOL_GPL(). Either solution should work here. Thanks!

On Wed, 30 Jul 2025 at 03:37, Marie Zhussupova marievic@google.com wrote:

Add `example_params_test_with_init` to illustrate how to manage shared resources across parameterized KUnit tests. This example showcases the use of the new `param_init` function and its registration to a test using the `KUNIT_CASE_PARAM_WITH_INIT` macro.

Additionally, the test demonstrates:

• How to directly assign a static parameter array to a test via `kunit_register_params_array`.
• Leveraging the Resource API for test resource management.

Signed-off-by: Marie Zhussupova marievic@google.com

Thanks for writing some examples! This is great, and makes the rest of the series much easier to understand.

(It also reminds me how much I hate the verbose parts of the resource API, but it's definitely out of scope to refactor that here. :-))

It does seem like this is a lot of effort to go through for one shared integer, though. In the real world, I'd suggest using kunit->parent->priv here. As an example, though, it's fine (though maybe using a named resource or even kunit_kzalloc() or similar would give a better example of how convenient this could be.

It's also not entirely clear why we're using kunit_register_params_array() for a static array, when KUNIT_ARRAY_PARAM() exists. (This is clearly because the latter doesn't support init functions; and I see why we don't necessarily want to make the number of macros explode through adding KUNIT_ARRAY_PARAM_WITH_INIT() et al, but maybe we should note that in the commit description, either here or before.)

Actual test looks fine, though:

Reviewed-by: David Gow davidgow@google.com

Cheers, -- David

lib/kunit/kunit-example-test.c | 112 +++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+)

diff --git a/lib/kunit/kunit-example-test.c b/lib/kunit/kunit-example-test.c index 3056d6bc705d..5bf559e243f6 100644 --- a/lib/kunit/kunit-example-test.c +++ b/lib/kunit/kunit-example-test.c @@ -277,6 +277,116 @@ static void example_slow_test(struct kunit *test) KUNIT_EXPECT_EQ(test, 1 + 1, 2); }

+/*

• • This custom function allocates memory for the kunit_resource data field.
• • The function is passed to kunit_alloc_resource() and executed once
• • by the internal helper __kunit_add_resource().
• */

+static int example_resource_init(struct kunit_resource *res, void *context) +{

•   int *info = kmalloc(sizeof(*info), GFP_KERNEL);
  

•   if (!info)
  

•           return -ENOMEM;
  

•   *info = *(int *)context;
  

•   res->data = info;
  

•   return 0;
  

+}

+/*

• • This function deallocates memory for the 'kunit_resource' data field.
• • The function is passed to kunit_alloc_resource() and automatically
• • executes within kunit_release_resource() when the resource's reference
• • count, via kunit_put_resource(), drops to zero. KUnit uses reference
• • counting to ensure that resources are not freed prematurely.
• */

+static void example_resource_free(struct kunit_resource *res) +{

•   kfree(res->data);
  

+}

+/*

• • This match function is invoked by kunit_find_resource() to locate
• • a test resource based on defined criteria. The current example
• • uniquely identifies the resource by its free function; however,
• • alternative custom criteria can be implemented. Refer to
• • lib/kunit/platform.c and lib/kunit/static_stub.c for further examples.
• */

+static bool example_resource_alloc_match(struct kunit *test,

•                                    struct kunit_resource *res,
  

•                                    void *match_data)
  

+{

•   return res->data && res->free == example_resource_free;
  

+}

+/*

• • This is an example of a function that provides a description for each of the
• • parameters.
• */

+static void example_param_array_get_desc(const void *p, char *desc) +{

•   const struct example_param *param = p;
  

•   snprintf(desc, KUNIT_PARAM_DESC_SIZE,
  

•            "example check if %d is less than or equal to 3", param->value);
  

+}

+/*

• • Initializes the parent kunit struct for parameterized KUnit tests.
• • This function enables sharing resources across all parameterized
• • tests by adding them to the `parent` kunit test struct. It also supports
• • registering either static or dynamic arrays of test parameters.
• */

+static int example_param_init(struct kunit *test) +{

•   int ctx = 3; /* Data to be stored. */
  

•   int arr_size = ARRAY_SIZE(example_params_array);
  

•   /*
  

•    * This allocates a struct kunit_resource, sets its data field to
  

•    * ctx, and adds it to the kunit struct's resources list. Note that
  

•    * this is test managed so we don't need to have a custom exit function
  

•    * to free it.
  

•    */
  

•   void *data = kunit_alloc_resource(test, example_resource_init, example_resource_free,
  

•                                     GFP_KERNEL, &ctx);
  

•   if (!data)
  

•           return -ENOMEM;
  

•   /* Pass the static param array information to the parent struct kunit. */
  

•   kunit_register_params_array(test, example_params_array, arr_size,
  

•                               example_param_array_get_desc);
  

•   return 0;
  

+}

+/*

• • This is an example of a parameterized test that uses shared resources
• • available from the struct kunit parent field of the kunit struct.
• */

+static void example_params_test_with_init(struct kunit *test) +{

•   int threshold;
  

•   struct kunit_resource *res;
  

•   const struct example_param *param = test->param_value;
  

•   /* By design, param pointer will not be NULL. */
  

•   KUNIT_ASSERT_NOT_NULL(test, param);
  

•   /* Here we access the parent pointer of the test to find the shared resource. */
  

•   res = kunit_find_resource(test->parent, example_resource_alloc_match, NULL);
  

•   KUNIT_ASSERT_NOT_NULL(test, res);
  

•   /* Since the data field in kunit_resource is a void pointer we need to typecast it. */
  

•   threshold = *((int *)res->data);
  

•   /* Assert that the parameter is less than or equal to a certain threshold. */
  

•   KUNIT_ASSERT_LE(test, param->value, threshold);
  

•   /* This decreases the reference count after calling kunit_find_resource(). */
  

•   kunit_put_resource(res);
  

+}

/*

• Here we make a list of all the test cases we want to add to the test suite
• below.

@@ -296,6 +406,8 @@ static struct kunit_case example_test_cases[] = { KUNIT_CASE(example_static_stub_using_fn_ptr_test), KUNIT_CASE(example_priv_test), KUNIT_CASE_PARAM(example_params_test, example_gen_params),

•   KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init, NULL,
  

•                              example_param_init, NULL),
    KUNIT_CASE_SLOW(example_slow_test),
    {}
  

};

2.50.1.552.g942d659e1b-goog

On Wed, 30 Jul 2025 at 03:37, Marie Zhussupova marievic@google.com wrote:

Introduce `example_params_test_with_init_dynamic_arr`. This new KUnit test demonstrates directly assigning a dynamic parameter array using the `kunit_register_params_array` macro. It highlights the use of `param_init` and `param_exit` for proper initialization and cleanup, and their registration to the test with `KUNIT_CASE_PARAM_WITH_INIT`.

Signed-off-by: Marie Zhussupova marievic@google.com

This is an excellent example, thanks. (I much prefer it to the previous one. In fact, if we could use some shared resource in this, we could probably get rid of the previous one entirely.)

Reviewed-by: David Gow davidgow@google.com

Cheers, -- David

lib/kunit/kunit-example-test.c | 95 ++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+)

diff --git a/lib/kunit/kunit-example-test.c b/lib/kunit/kunit-example-test.c index 5bf559e243f6..3ab121d81bf6 100644 --- a/lib/kunit/kunit-example-test.c +++ b/lib/kunit/kunit-example-test.c @@ -387,6 +387,98 @@ static void example_params_test_with_init(struct kunit *test) kunit_put_resource(res); }

+/*

• • Helper function to create a parameter array of Fibonacci numbers. This example
• • highlights a parameter generation scenario that is:
• • 1. Not feasible to fully pre-generate at compile time.
• • 2. Challenging to implement with a standard 'generate_params' function,
• • as it typically only provides the immediately 'prev' parameter, while
• • Fibonacci requires access to two preceding values for calculation.
• */

+static void *make_fibonacci_params(int seq_size) +{

•   int *seq;
  

•   if (seq_size <= 0)
  

•           return NULL;
  

•   seq = kmalloc_array(seq_size, sizeof(int), GFP_KERNEL);
  

If we used kunit_kmalloc_array here (we'd need to pass test through somehow, though), we could have a good example of a shared resource here.

•   if (!seq)
  

•           return NULL;
  

•   if (seq_size >= 1)
  

•           seq[0] = 0;
  

•   if (seq_size >= 2)
  

•           seq[1] = 1;
  

•   for (int i = 2; i < seq_size; i++)
  

•           seq[i] = seq[i - 1] + seq[i - 2];
  

•   return seq;
  

+}

+/*

• • This is an example of a function that provides a description for each of the
• • parameters.
• */

+static void example_param_dynamic_arr_get_desc(const void *p, char *desc)

Seeing this makes me wonder whether we should pass struct *kunit to the get_desc function, too.

Thoughts?

+{

•   const int *fib_num = p;
  

•   snprintf(desc, KUNIT_PARAM_DESC_SIZE, "fibonacci param: %d", *fib_num);
  

+}

+/*

• • Example of a parameterized test init function that registers a dynamic array.
• */

+static int example_param_init_dynamic_arr(struct kunit *test) +{

•   int seq_size = 6;
  

•   int *fibonacci_params = make_fibonacci_params(seq_size);
  

•   if (!fibonacci_params)
  

•           return -ENOMEM;
  

•   /*
  

•    * Passes the dynamic parameter array information to the parent struct kunit.
  

•    * The array and its metadata will be stored in test->parent->params_data.
  

•    * The array itself will be located in params_data.params.
  

•    */
  

•   kunit_register_params_array(test, fibonacci_params, seq_size,
  

•                               example_param_dynamic_arr_get_desc);
  

•   return 0;
  

+}

+/**

• • Function to clean up the parameterized test's parent kunit struct if
• • there were custom allocations.
• */

+static void example_param_exit_dynamic_arr(struct kunit *test) +{

•   /*
  

•    * We allocated this array, so we need to free it.
  

•    * Since the parent parameter instance is passed here,
  

•    * we can directly access the array via `test->params_data.params`
  

•    * instead of `test->parent->params_data.params`.
  

•    */
  

•   kfree(test->params_data.params);
  

If we used kunit_kmalloc_array above, though, we'd miss this good example. So I'm torn...

(I suppose we could use kunit_kfree() anyway, though, and just rely on the shared resource management for early aborts.)

+}

+/*

• • Example of test that uses the registered dynamic array to perform assertions
• • and expectations.
• */

+static void example_params_test_with_init_dynamic_arr(struct kunit *test) +{

•   const int *param = test->param_value;
  

•   int param_val;
  

•   /* By design, param pointer will not be NULL. */
  

•   KUNIT_ASSERT_NOT_NULL(test, param);
  

•   param_val = *param;
  

•   KUNIT_EXPECT_EQ(test, param_val - param_val, 0);
  

+}

/*

• Here we make a list of all the test cases we want to add to the test suite
• below.

@@ -408,6 +500,9 @@ static struct kunit_case example_test_cases[] = { KUNIT_CASE_PARAM(example_params_test, example_gen_params), KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init, NULL, example_param_init, NULL),

•   KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init_dynamic_arr, NULL,
  

•                              example_param_init_dynamic_arr,
  

•                              example_param_exit_dynamic_arr),
    KUNIT_CASE_SLOW(example_slow_test),
    {}
  

};

2.50.1.552.g942d659e1b-goog

On Wed, 30 Jul 2025 at 03:37, Marie Zhussupova marievic@google.com wrote:

-Update the KUnit documentation to explain the concept of a parent parameterized test. -Add examples demonstrating different ways of passing parameters to parameterized tests and how to manage shared resources between them.

Nit: We don't need the dot points ('-') here. Just make them paragraphs.

Signed-off-by: Marie Zhussupova marievic@google.com

Thanks very, very much for including such detailed documentation.

I do think some of the examples could be trimmed / left in the kunit-example-test.c file and referenced, as they're long enough that it's difficult to focus on the essentials. But otherwise, this looks great.

A few small notes below, but otherwise:

Reviewed-by: David Gow davidgow@google.com

Cheers, -- David

Documentation/dev-tools/kunit/usage.rst | 455 +++++++++++++++++++++++- 1 file changed, 449 insertions(+), 6 deletions(-)

diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 066ecda1dd98..be1d656053cf 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -542,11 +542,21 @@ There is more boilerplate code involved, but it can: Parameterized Testing

-The table-driven testing pattern is common enough that KUnit has special
-support for it.
-
-By reusing the same ``cases`` array from above, we can write the test as a
-"parameterized test" with the following.
+To efficiently and elegantly validate a test case against a variety of inputs,
+KUnit also provides a parameterized testing framework. This feature formalizes
+and extends the concept of table-driven tests discussed previously, offering
+a more integrated and flexible way to handle multiple test scenarios with
+minimal code duplication.

Nit: maybe we can tone down the adjectives slightly here. I do like parameterised testing a lot, but it probably doesn't need to be "efficient", "elegant", "integrated", and "flexible".

+Passing Parameters to the Test Cases +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +There are three main ways to provide the parameters to a test case:

+Array Parameter Macros (``KUNIT_ARRAY_PARAM`` or ``KUNIT_ARRAY_PARAM_DESC``):

• KUnit provides special support for the common table-driven testing pattern.
• By applying either ``KUNIT_ARRAY_PARAM`` or ``KUNIT_ARRAY_PARAM_DESC`` to the
• ``cases`` array from the previous section, we can create a parameterized test
• as shown below:

.. code-block:: c

@@ -555,7 +565,7 @@ By reusing the same ``cases`` array from above, we can write the test as a const char *str; const char *sha1; };

•   const struct sha1_test_case cases[] = {
  

•   static const struct sha1_test_case cases[] = {
            {
                    .str = "hello world",
                    .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
  

@@ -590,6 +600,439 @@ By reusing the same ``cases`` array from above, we can write the test as a {} };

+Custom Parameter Generator (``generate_params``):

• You can pass your own ``generate_params`` function to the ``KUNIT_CASE_PARAM``
• or ``KUNIT_CASE_PARAM_WITH_INIT`` macros. This function is responsible for
• generating parameters one by one. It receives the previously generated parameter
• as the ``prev`` argument (which is ``NULL`` on the first call) and can also
• access any context available from the parent ``struct kunit`` passed as the
• ``test`` argument. KUnit calls this function repeatedly until it returns
• ``NULL``. Below is an example of how it works:

+.. code-block:: c

•   #define MAX_TEST_BUFFER_SIZE 8
  

•   // Example generator function. It produces a sequence of buffer sizes that
  

•   // are powers of two, starting at 1 (e.g., 1, 2, 4, 8).
  

•   static const void *buffer_size_gen_params(struct kunit *test, const void *prev, char *desc)
  

•   {
  

•           long prev_buffer_size = (long)prev;
  

•           long next_buffer_size = 1; // Start with an initial size of 1.
  

•           // Stop generating parameters if the limit is reached or exceeded.
  

•           if (prev_buffer_size >= MAX_TEST_BUFFER_SIZE)
  

•                   return NULL;
  

•           // For subsequent calls, calculate the next size by doubling the previous one.
  

•           if (prev)
  

•                   next_buffer_size = prev_buffer_size << 1;
  

•           return (void *)next_buffer_size;
  

•   }
  

•   // Simple test to validate that kunit_kzalloc provides zeroed memory.
  

•   static void buffer_zero_test(struct kunit *test)
  

•   {
  

•           long buffer_size = (long)test->param_value;
  

•           // Use kunit_kzalloc to allocate a zero-initialized buffer. This makes the
  

•           // memory "parameter managed," meaning it's automatically cleaned up at
  

•           // the end of each parameter execution.
  

•           int *buf = kunit_kzalloc(test, buffer_size * sizeof(int), GFP_KERNEL);
  

•           // Ensure the allocation was successful.
  

•           KUNIT_ASSERT_NOT_NULL(test, buf);
  

•           // Loop through the buffer and confirm every element is zero.
  

•           for (int i = 0; i < buffer_size; i++)
  

•                   KUNIT_EXPECT_EQ(test, buf[i], 0);
  

•   }
  

•   static struct kunit_case buffer_test_cases[] = {
  

•           KUNIT_CASE_PARAM(buffer_zero_test, buffer_size_gen_params),
  

•           {}
  

•   };
  

+Direct Registration in Parameter Init Function (using ``kunit_register_params_array``):

Maybe we should highlight this as being array-based more explicitly. "Runtime Array Registration in the Init function" or similar?

• For more complex scenarios, you can directly register a parameter array with
• a test case instead of using a ``generate_params`` function. This is done by
• passing the array to the ``kunit_register_params_array`` macro within an
• initialization function for the parameterized test series
• (i.e., a function named ``param_init``). To better understand this mechanism
• please refer to the "Adding Shared Resources" section below.
• This method supports both dynamically built and static arrays.
• As the following code shows, the ``example_param_init_dynamic_arr`` function
• utilizes ``make_fibonacci_params`` to create a dynamic array, which is then
• registered using ``kunit_register_params_array``. The corresponding exit
• function, ``example_param_exit``, is responsible for freeing this dynamically
• allocated params array after the parameterized test series ends.

+.. code-block:: c

•   /*
  

•    * Helper function to create a parameter array of Fibonacci numbers. This example
  

•    * highlights a parameter generation scenario that is:
  

•    * 1. Not feasible to fully pre-generate at compile time.
  

•    * 2. Challenging to implement with a standard 'generate_params' function,
  

•    * as it typically only provides the immediately 'prev' parameter, while
  

•    * Fibonacci requires access to two preceding values for calculation.
  

•    */
  

•   static void *make_fibonacci_params(int seq_size)
  

•   {
  

•           int *seq;
  

•           if (seq_size <= 0)
  

•                   return NULL;
  

•           seq = kmalloc_array(seq_size, sizeof(int), GFP_KERNEL);
  

•           if (!seq)
  

•                   return NULL;
  

•           if (seq_size >= 1)
  

•                   seq[0] = 0;
  

•           if (seq_size >= 2)
  

•                   seq[1] = 1;
  

•           for (int i = 2; i < seq_size; i++)
  

•                   seq[i] = seq[i - 1] + seq[i - 2];
  

•           return seq;
  

•   }
  

•   // This is an example of a function that provides a description for each of the
  

•   // parameters.
  

•   static void example_param_dynamic_arr_get_desc(const void *p, char *desc)
  

•   {
  

•           const int *fib_num = p;
  

•           snprintf(desc, KUNIT_PARAM_DESC_SIZE, "fibonacci param: %d", *fib_num);
  

•   }
  

•   // Example of a parameterized test init function that registers a dynamic array.
  

•   static int example_param_init_dynamic_arr(struct kunit *test)
  

•   {
  

•           int seq_size = 6;
  

•           int *fibonacci_params = make_fibonacci_params(seq_size);
  

•           if (!fibonacci_params)
  

•                   return -ENOMEM;
  

•           /*
  

•            * Passes the dynamic parameter array information to the parent struct kunit.
  

•            * The array and its metadata will be stored in test->parent->params_data.
  

•            * The array itself will be located in params_data.params.
  

•            */
  

•           kunit_register_params_array(test, fibonacci_params, seq_size,
  

•                                       example_param_dynamic_arr_get_desc);
  

•           return 0;
  

•   }
  

•   // Function to clean up the parameterized test's parent kunit struct if
  

•   // there were custom allocations.
  

•   static void example_param_exit_dynamic_arr(struct kunit *test)
  

•   {
  

•           /*
  

•            * We allocated this array, so we need to free it.
  

•            * Since the parent parameter instance is passed here,
  

•            * we can directly access the array via `test->params_data.params`
  

•            * instead of `test->parent->params_data.params`.
  

•            */
  

•           kfree(test->params_data.params);
  

•   }
  

•   /*
  

•    * Example of test that uses the registered dynamic array to perform assertions
  

•    * and expectations.
  

•    */
  

•   static void example_params_test_with_init_dynamic_arr(struct kunit *test)
  

•   {
  

•           const int *param = test->param_value;
  

•           int param_val;
  

•           /* By design, param pointer will not be NULL. */
  

•           KUNIT_ASSERT_NOT_NULL(test, param);
  

•           param_val = *param;
  

•           KUNIT_EXPECT_EQ(test, param_val - param_val, 0);
  

•   }
  

•   static struct kunit_case example_tests[] = {
  

•           // The NULL here stands in for the generate_params function
  

•           KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init_dynamic_arr, NULL,
  

•                                      example_param_init_dynamic_arr,
  

•                                      example_param_exit_dynamic_arr),
  

•           {}
  

•   };
  

This is a long example, which already exists in the source code (kunit-example-test.c). Could we just include some highlights (e.g., the init function and the KUNIT_CASE_PARAM_WITH_INIT call), and link to the source code for the rest?

+Adding Shared Resources +^^^^^^^^^^^^^^^^^^^^^^^ +All parameterized test executions in this framework have a parent test of type +``struct kunit``. This parent is not used to execute any test logic itself; +instead, it serves as a container for shared context that can be accessed by +all its individual test executions (or parameters). Therefore, each individual +test execution holds a pointer to this parent, accessible via a field named +``parent``.

+It's possible to add resources to share between the individual test executions +within a parameterized test series by using the ``KUNIT_CASE_PARAM_WITH_INIT`` +macro, to which you pass custom ``param_init`` and ``param_exit`` functions. +These functions run once before and once after the entire parameterized test +series, respectively. The ``param_init`` function can be used for adding any +resources to the resources field of a parent test and also provide an additional +way of setting the parameter array. The ``param_exit`` function can be used +release any resources that were not test managed i.e. not automatically cleaned +up after the test ends.

+.. note::

• If both a ``generate_params`` function is passed to ``KUNIT_CASE_PARAM_WITH_INIT``
• and an array is registered via ``kunit_register_params_array`` in
• ``param_init``, the ``generate_params`` function will be used to get
• the parameters.

Maybe note that the ``generate_params`` function can use the array passed, though?

+Both ``param_init`` and ``param_exit`` are passed the parent instance of a test +(parent ``struct kunit``) behind the scenes. However, the test case function +receives the individual instance of a test for each parameter. Therefore, to +manage and access shared resources from within a test case function, you must use +``test->parent``.

+.. note::

• The ``suite->init()`` function, which runs before each parameter execution,
• receives the individual instance of a test for each parameter. Therefore,
• resources set up in ``suite->init()`` are reset for each individual
• parameterized test execution and are only visible within that specific test.

+For instance, finding a shared resource allocated by the Resource API requires +passing ``test->parent`` to ``kunit_find_resource()``. This principle extends to +all other APIs that might be used in the test case function, including +``kunit_kzalloc()``, ``kunit_kmalloc_array()``, and others (see +Documentation/dev-tools/kunit/api/test.rst and the +Documentation/dev-tools/kunit/api/resource.rst).

+The code below shows how you can add the shared resources. Note that this code +utilizes the Resource API, which you can read more about here: +Documentation/dev-tools/kunit/api/resource.rst.

+.. code-block:: c

•   /* An example parameter array. */
  

•   static const struct example_param {
  

•           int value;
  

•   } example_params_array[] = {
  

•           { .value = 3, },
  

•           { .value = 2, },
  

•           { .value = 1, },
  

•           { .value = 0, },
  

•   };
  

•   /*
  

•    * This custom function allocates memory for the kunit_resource data field.
  

•    * The function is passed to kunit_alloc_resource() and executed once
  

•    * by the internal helper __kunit_add_resource().
  

•    */
  

•   static int example_resource_init(struct kunit_resource *res, void *context)
  

•   {
  

•           int *info = kmalloc(sizeof(*info), GFP_KERNEL);
  

•           if (!info)
  

•                   return -ENOMEM;
  

•           *info = *(int *)context;
  

•           res->data = info;
  

•           return 0;
  

•   }
  

•   /*
  

•    * This function deallocates memory for the 'kunit_resource' data field.
  

•    * The function is passed to kunit_alloc_resource() and automatically
  

•    * executes within kunit_release_resource() when the resource's reference
  

•    * count, via kunit_put_resource(), drops to zero. KUnit uses reference
  

•    * counting to ensure that resources are not freed prematurely.
  

•    */
  

•   static void example_resource_free(struct kunit_resource *res)
  

•   {
  

•           kfree(res->data);
  

•   }
  

•   /*
  

•    * This match function is invoked by kunit_find_resource() to locate
  

•    * a test resource based on defined criteria. The current example
  

•    * uniquely identifies the resource by its free function; however,
  

•    * alternative custom criteria can be implemented. Refer to
  

•    * lib/kunit/platform.c and lib/kunit/static_stub.c for further examples.
  

•    */
  

•   static bool example_resource_alloc_match(struct kunit *test,
  

•                                            struct kunit_resource *res,
  

•                                            void *match_data)
  

•   {
  

•           return res->data && res->free == example_resource_free;
  

•   }
  

•   /*
  

•    * This is an example of a function that provides a description for each of the
  

•    * parameters.
  

•   */
  

•   static void example_param_array_get_desc(const void *p, char *desc)
  

•   {
  

•           const struct example_param *param = p;
  

•           snprintf(desc, KUNIT_PARAM_DESC_SIZE,
  

•                   "example check if %d is less than or equal to 3", param->value);
  

•   }
  

•   /*
  

•    * Initializes the parent kunit struct for parameterized KUnit tests.
  

•    * This function enables sharing resources across all parameterized
  

•    * tests by adding them to the `parent` kunit test struct. It also supports
  

•    * registering either static or dynamic arrays of test parameters.
  

•    */
  

•   static int example_param_init(struct kunit *test)
  

•   {
  

•           int ctx = 3; /* Data to be stored. */
  

•           int arr_size = ARRAY_SIZE(example_params_array);
  

•           /*
  

•            * This allocates a struct kunit_resource, sets its data field to
  

•            * ctx, and adds it to the kunit struct's resources list. Note that
  

•            * this is test managed so we don't need to have a custom exit function
  

•            * to free it.
  

•            */
  

•           void *data = kunit_alloc_resource(test, example_resource_init, example_resource_free,
  

•                                             GFP_KERNEL, &ctx);
  

•           if (!data)
  

•                   return -ENOMEM;
  

•           /* Pass the static param array information to the parent struct kunit. */
  

•           kunit_register_params_array(test, example_params_array, arr_size,
  

•                                       example_param_array_get_desc);
  

•           return 0;
  

•   }
  

•   /*
  

•   * This is an example of a parameterized test that uses shared resources
  

•   * available from the struct kunit parent field of the kunit struct.
  

•   */
  

•   static void example_params_test_with_init(struct kunit *test)
  

•   {
  

•           int threshold;
  

•           struct kunit_resource *res;
  

•           const struct example_param *param = test->param_value;
  

•           /* By design, param pointer will not be NULL. */
  

•           KUNIT_ASSERT_NOT_NULL(test, param);
  

•           /* Here we need to access the parent pointer of the test to find the shared resource. */
  

•           res = kunit_find_resource(test->parent, example_resource_alloc_match, NULL);
  

•           KUNIT_ASSERT_NOT_NULL(test, res);
  

•           /* Since the data field in kunit_resource is a void pointer we need to typecast it. */
  

•           threshold = *((int *)res->data);
  

•           /* Assert that the parameter is less than or equal to a certain threshold. */
  

•           KUNIT_ASSERT_LE(test, param->value, threshold);
  

•           /* This decreases the reference count after calling kunit_find_resource(). */
  

•           kunit_put_resource(res);
  

•   }
  

•   static struct kunit_case example_tests[] = {
  

•           KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init, NULL,
  

•                                      example_param_init, NULL),
  

•           {}
  

•   };
  

This is a really long example, which already exists in kunit-example-test.c. Can we either link to it there (and just include the most critical lines here), or have a smaller, less-complete example inline here?

+As an alternative to using the KUnit Resource API for shared resources, you can +place them in ``test->parent->priv``. It can store data that needs to persist +and be accessible across all executions within a parameterized test series.

+As stated previously ``param_init`` and ``param_exit`` receive the parent +``struct kunit`` instance. So, you can directly use ``test->priv`` within them +to manage shared resources. However, from within the test case function, you must +navigate up to the parent i.e. use ``test->parent->priv`` to access those same +resources.

+The resources placed in ``test->parent-priv`` will also need to be allocated in +memory to persist across the parameterized tests executions. If memory is

Nit: 'parameterized test executions' singular?

+allocated using the memory allocation APIs provided by KUnit (described more in +the section below), you will not need to worry about deallocating them as they +will be managed by the parent parameterized test that gets automatically cleaned +up upon the end of the parameterized test series.

+The code below demonstrates example usage of the ``priv`` field for shared +resources:

+.. code-block:: c

•   /* An example parameter array. */
  

•   static const struct example_param {
  

•           int value;
  

•   } example_params_array[] = {
  

•           { .value = 3, },
  

•           { .value = 2, },
  

•           { .value = 1, },
  

•           { .value = 0, },
  

•   };
  

•   /*
  

•    * Initializes the parent kunit struct for parameterized KUnit tests.
  

•    * This function enables sharing resources across all parameterized
  

•    * tests.
  

•    */
  

•   static int example_param_init_priv(struct kunit *test)
  

•   {
  

•           int ctx = 3; /* Data to be stored. */
  

•           int arr_size = ARRAY_SIZE(example_params_array);
  

•           /*
  

•            * Allocate memory using kunit_kzalloc(). Since the `param_init`
  

•            * function receives the parent instance of test, this memory
  

•            * allocation will be scoped to the lifetime of the whole
  

•            * parameterized test series.
  

•            */
  

•           test->priv = kunit_kzalloc(test, sizeof(int), GFP_KERNEL);
  

•           /* Assign the context value to test->priv.*/
  

•           *((int *)test->priv) = ctx;
  

•           /* Pass the static param array information to the parent struct kunit. */
  

•           kunit_register_params_array(test, example_params_array, arr_size, NULL);
  

•           return 0;
  

•   }
  

•   /*
  

•   * This is an example of a parameterized test that uses shared resources
  

•   * available from the struct kunit parent field of the kunit struct.
  

•   */
  

•   static void example_params_test_with_init_priv(struct kunit *test)
  

•   {
  

•           int threshold;
  

•           const struct example_param *param = test->param_value;
  

•           /* By design, param pointer will not be NULL. */
  

•           KUNIT_ASSERT_NOT_NULL(test, param);
  

•           /* By design, test->parent will also not be NULL. */
  

•           KUNIT_ASSERT_NOT_NULL(test, test->parent);
  

•           /* Assert that test->parent->priv has data. */
  

•           KUNIT_ASSERT_NOT_NULL(test, test->parent->priv);
  

•           /* Here we need to use test->parent->priv to access the shared resource. */
  

•           threshold = *(int *)test->parent->priv;
  

•           /* Assert that the parameter is less than or equal to a certain threshold. */
  

•           KUNIT_ASSERT_LE(test, param->value, threshold);
  

•   }
  

•   static struct kunit_case example_tests[] = {
  

•           KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init_priv, NULL,
  

•                                      example_param_init_priv, NULL),
  

•           {}
  

•   };
  

Again, this is a little long, but it's not as bad as the others, and isn't in the example tests, so I'm okay with leaving it. Though maybe we could get rid of some of the asserts for the purpose of keeping the documentation focused and readable.

Allocating Memory

-- 2.50.1.552.g942d659e1b-goog