Resource API

This file documents the KUnit resource API.

Most users won’t need to use this API directly, power users can use it to store state on a per-test basis, register custom cleanup actions, and more.

struct kunit_resource

represents a test managed resource

Definition

struct kunit_resource {
  void *data;
  const char *name;
  kunit_resource_free_t free;
};

Members

data

for the user to store arbitrary data.

name

optional name

free

a user supplied function to free the resource.

Description

Represents a test managed resource, a resource which will automatically be cleaned up at the end of a test case. This cleanup is performed by the ‘free’ function. The struct kunit_resource itself is freed automatically with kfree() if it was allocated by KUnit (e.g., by kunit_alloc_resource()), but must be freed by the user otherwise.

Resources are reference counted so if a resource is retrieved via kunit_alloc_and_get_resource() or kunit_find_resource(), we need to call kunit_put_resource() to reduce the resource reference count when finished with it. Note that kunit_alloc_resource() does not require a kunit_resource_put() because it does not retrieve the resource itself.

struct kunit_kmalloc_params {
        size_t size;
        gfp_t gfp;
};

static int kunit_kmalloc_init(struct kunit_resource *res, void *context)
{
        struct kunit_kmalloc_params *params = context;
        res->data = kmalloc(params->size, params->gfp);

        if (!res->data)
                return -ENOMEM;

        return 0;
}

static void kunit_kmalloc_free(struct kunit_resource *res)
{
        kfree(res->data);
}

void *kunit_kmalloc(struct kunit *test, size_t size, gfp_t gfp)
{
        struct kunit_kmalloc_params params;

        params.size = size;
        params.gfp = gfp;

        return kunit_alloc_resource(test, kunit_kmalloc_init,
                kunit_kmalloc_free, &params);
}

Resources can also be named, with lookup/removal done on a name basis also. kunit_add_named_resource(), kunit_find_named_resource() and kunit_destroy_named_resource(). Resource names must be unique within the test instance.

Example

void kunit_get_resource(struct kunit_resource *res)

Hold resource for use. Should not need to be used by most users as we automatically get resources retrieved by kunit_find_resource*().

Parameters

struct kunit_resource *res

resource

void kunit_put_resource(struct kunit_resource *res)

When caller is done with retrieved resource, kunit_put_resource() should be called to drop reference count. The resource list maintains a reference count on resources, so if no users are utilizing a resource and it is removed from the resource list, it will be freed via the associated free function (if any). Only needs to be used if we alloc_and_get() or find() resource.

Parameters

struct kunit_resource *res

resource

int __kunit_add_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, struct kunit_resource *res, void *data)

Internal helper to add a resource.

Parameters

struct kunit *test

The test context object.

kunit_resource_init_t init

a user-supplied function to initialize the result (if needed). If none is supplied, the resource data value is simply set to data. If an init function is supplied, data is passed to it instead.

kunit_resource_free_t free

a user-supplied function to free the resource (if needed).

struct kunit_resource *res

The resource.

void *data

value to pass to init function or set in resource data field.

Description

res->should_kfree is not initialised.

int kunit_add_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, struct kunit_resource *res, void *data)

Add a test managed resource.

Parameters

struct kunit *test

The test context object.

kunit_resource_init_t init

a user-supplied function to initialize the result (if needed). If none is supplied, the resource data value is simply set to data. If an init function is supplied, data is passed to it instead.

kunit_resource_free_t free

a user-supplied function to free the resource (if needed).

struct kunit_resource *res

The resource.

void *data

value to pass to init function or set in resource data field.

int kunit_add_named_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, struct kunit_resource *res, const char *name, void *data)

Add a named test managed resource.

Parameters

struct kunit *test

The test context object.

kunit_resource_init_t init

a user-supplied function to initialize the resource data, if needed.

kunit_resource_free_t free

a user-supplied function to free the resource data, if needed.

struct kunit_resource *res

The resource.

const char *name

name to be set for resource.

void *data

value to pass to init function or set in resource data field.

struct kunit_resource *kunit_alloc_and_get_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, gfp_t internal_gfp, void *context)

Allocates and returns a test managed resource.

Parameters

struct kunit *test

The test context object.

kunit_resource_init_t init

a user supplied function to initialize the resource.

kunit_resource_free_t free

a user supplied function to free the resource (if needed).

gfp_t internal_gfp

gfp to use for internal allocations, if unsure, use GFP_KERNEL

void *context

for the user to pass in arbitrary data to the init function.

Description

Allocates a test managed resource, a resource which will automatically be cleaned up at the end of a test case. See struct kunit_resource for an example.

This is effectively identical to kunit_alloc_resource, but returns the struct kunit_resource pointer, not just the ‘data’ pointer. It therefore also increments the resource’s refcount, so kunit_put_resource() should be called when you’ve finished with it.

Note

KUnit needs to allocate memory for a kunit_resource object. You must specify an internal_gfp that is compatible with the use context of your resource.

void *kunit_alloc_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, gfp_t internal_gfp, void *context)

Allocates a test managed resource.

Parameters

struct kunit *test

The test context object.

kunit_resource_init_t init

a user supplied function to initialize the resource.

kunit_resource_free_t free

a user supplied function to free the resource (if needed).

gfp_t internal_gfp

gfp to use for internal allocations, if unsure, use GFP_KERNEL

void *context

for the user to pass in arbitrary data to the init function.

Description

Allocates a test managed resource, a resource which will automatically be cleaned up at the end of a test case. See struct kunit_resource for an example.

Note

KUnit needs to allocate memory for a kunit_resource object. You must specify an internal_gfp that is compatible with the use context of your resource.

bool kunit_resource_instance_match(struct kunit *test, struct kunit_resource *res, void *match_data)

Match a resource with the same instance.

Parameters

struct kunit *test

Test case to which the resource belongs.

struct kunit_resource *res

The resource.

void *match_data

The resource pointer to match against.

Description

An instance of kunit_resource_match_t that matches a resource whose allocation matches match_data.

bool kunit_resource_name_match(struct kunit *test, struct kunit_resource *res, void *match_name)

Match a resource with the same name.

Parameters

struct kunit *test

Test case to which the resource belongs.

struct kunit_resource *res

The resource.

void *match_name

The name to match against.

struct kunit_resource *kunit_find_resource(struct kunit *test, kunit_resource_match_t match, void *match_data)

Find a resource using match function/data.

Parameters

struct kunit *test

Test case to which the resource belongs.

kunit_resource_match_t match

match function to be applied to resources/match data.

void *match_data

data to be used in matching.

struct kunit_resource *kunit_find_named_resource(struct kunit *test, const char *name)

Find a resource using match name.

Parameters

struct kunit *test

Test case to which the resource belongs.

const char *name

match name.

int kunit_destroy_resource(struct kunit *test, kunit_resource_match_t match, void *match_data)

Find a kunit_resource and destroy it.

Parameters

struct kunit *test

Test case to which the resource belongs.

kunit_resource_match_t match

Match function. Returns whether a given resource matches match_data.

void *match_data

Data passed into match.

Return

0 if kunit_resource is found and freed, -ENOENT if not found.

void kunit_remove_resource(struct kunit *test, struct kunit_resource *res)

remove resource from resource list associated with test.

Parameters

struct kunit *test

The test context object.

struct kunit_resource *res

The resource to be removed.

Description

Note that the resource will not be immediately freed since it is likely the caller has a reference to it via alloc_and_get() or find(); in this case a final call to kunit_put_resource() is required.