11 ˆ¾Ä ƒh¹ÂÆMODALIAS=acpi:LNXCPU: ˆÅÄ „ €q¯ÃÂÆ>À/* SPDX-License-Identifier: GPL-2.0 */ /* * KUnit resource API for test managed resources (allocations, etc.). * * Copyright (C) 2022, Google LLC. * Author: Daniel Latypov */ #ifndef _KUNIT_RESOURCE_H #define _KUNIT_RESOURCE_H #include #include #include #include #include struct kunit_resource; typedef int (*kunit_resource_init_t)(struct kunit_resource *, void *); typedef void (*kunit_resource_free_t)(struct kunit_resource *); /** * struct kunit_resource - represents a *test managed resource* * @data: for the user to store arbitrary data. * @name: optional name * @free: a user supplied function to free the resource. * * 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. * * Example: * * .. code-block:: c * * 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, gfp, ¶ms); * } * * 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. */ struct kunit_resource { void *data; const char *name; kunit_resource_free_t free; /* private: internal use only. */ struct kref refcount; struct list_head node; bool should_kfree; }; /** * kunit_get_resource() - Hold resource for use. Should not need to be used * by most users as we automatically get resources * retrieved by kunit_find_resource*(). * @res: resource */ static inline void kunit_get_resource(struct kunit_resource *res) { kref_get(&res->refcount); } /* * Called when refcount reaches zero via kunit_put_resource(); * should not be called directly. */ static inline void kunit_release_resource(struct kref *kref) { struct kunit_resource *res = container_of(kref, struct kunit_resource, refcount); if (res->free) res->free(res); /* 'res' is valid here, as if should_kfree is set, res->free may not free * 'res' itself, just res->data */ if (res->should_kfree) kfree(res); } /** * kunit_put_resource() - 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. * @res: resource */ static inline void kunit_put_resource(struct kunit_resource *res) { kref_put(&res->refcount, kunit_release_resource); } /** * __kunit_add_resource