xref: /openbmc/linux/include/kunit/resource.h (revision bbaf1ff0)
1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * KUnit resource API for test managed resources (allocations, etc.).
4  *
5  * Copyright (C) 2022, Google LLC.
6  * Author: Daniel Latypov <dlatypov@google.com>
7  */
8 
9 #ifndef _KUNIT_RESOURCE_H
10 #define _KUNIT_RESOURCE_H
11 
12 #include <kunit/test.h>
13 
14 #include <linux/kref.h>
15 #include <linux/list.h>
16 #include <linux/slab.h>
17 #include <linux/spinlock.h>
18 
19 struct kunit_resource;
20 
21 typedef int (*kunit_resource_init_t)(struct kunit_resource *, void *);
22 typedef void (*kunit_resource_free_t)(struct kunit_resource *);
23 
24 /**
25  * struct kunit_resource - represents a *test managed resource*
26  * @data: for the user to store arbitrary data.
27  * @name: optional name
28  * @free: a user supplied function to free the resource.
29  *
30  * Represents a *test managed resource*, a resource which will automatically be
31  * cleaned up at the end of a test case. This cleanup is performed by the 'free'
32  * function. The struct kunit_resource itself is freed automatically with
33  * kfree() if it was allocated by KUnit (e.g., by kunit_alloc_resource()), but
34  * must be freed by the user otherwise.
35  *
36  * Resources are reference counted so if a resource is retrieved via
37  * kunit_alloc_and_get_resource() or kunit_find_resource(), we need
38  * to call kunit_put_resource() to reduce the resource reference count
39  * when finished with it.  Note that kunit_alloc_resource() does not require a
40  * kunit_resource_put() because it does not retrieve the resource itself.
41  *
42  * Example:
43  *
44  * .. code-block:: c
45  *
46  *	struct kunit_kmalloc_params {
47  *		size_t size;
48  *		gfp_t gfp;
49  *	};
50  *
51  *	static int kunit_kmalloc_init(struct kunit_resource *res, void *context)
52  *	{
53  *		struct kunit_kmalloc_params *params = context;
54  *		res->data = kmalloc(params->size, params->gfp);
55  *
56  *		if (!res->data)
57  *			return -ENOMEM;
58  *
59  *		return 0;
60  *	}
61  *
62  *	static void kunit_kmalloc_free(struct kunit_resource *res)
63  *	{
64  *		kfree(res->data);
65  *	}
66  *
67  *	void *kunit_kmalloc(struct kunit *test, size_t size, gfp_t gfp)
68  *	{
69  *		struct kunit_kmalloc_params params;
70  *
71  *		params.size = size;
72  *		params.gfp = gfp;
73  *
74  *		return kunit_alloc_resource(test, kunit_kmalloc_init,
75  *			kunit_kmalloc_free, gfp, &params);
76  *	}
77  *
78  * Resources can also be named, with lookup/removal done on a name
79  * basis also.  kunit_add_named_resource(), kunit_find_named_resource()
80  * and kunit_destroy_named_resource().  Resource names must be
81  * unique within the test instance.
82  */
83 struct kunit_resource {
84 	void *data;
85 	const char *name;
86 	kunit_resource_free_t free;
87 
88 	/* private: internal use only. */
89 	struct kref refcount;
90 	struct list_head node;
91 	bool should_kfree;
92 };
93 
94 /**
95  * kunit_get_resource() - Hold resource for use.  Should not need to be used
96  *			  by most users as we automatically get resources
97  *			  retrieved by kunit_find_resource*().
98  * @res: resource
99  */
100 static inline void kunit_get_resource(struct kunit_resource *res)
101 {
102 	kref_get(&res->refcount);
103 }
104 
105 /*
106  * Called when refcount reaches zero via kunit_put_resource();
107  * should not be called directly.
108  */
109 static inline void kunit_release_resource(struct kref *kref)
110 {
111 	struct kunit_resource *res = container_of(kref, struct kunit_resource,
112 						  refcount);
113 
114 	if (res->free)
115 		res->free(res);
116 
117 	/* 'res' is valid here, as if should_kfree is set, res->free may not free
118 	 * 'res' itself, just res->data
119 	 */
120 	if (res->should_kfree)
121 		kfree(res);
122 }
123 
124 /**
125  * kunit_put_resource() - When caller is done with retrieved resource,
126  *			  kunit_put_resource() should be called to drop
127  *			  reference count.  The resource list maintains
128  *			  a reference count on resources, so if no users
129  *			  are utilizing a resource and it is removed from
130  *			  the resource list, it will be freed via the
131  *			  associated free function (if any).  Only
132  *			  needs to be used if we alloc_and_get() or
133  *			  find() resource.
134  * @res: resource
135  */
136 static inline void kunit_put_resource(struct kunit_resource *res)
137 {
138 	kref_put(&res->refcount, kunit_release_resource);
139 }
140 
141 /**
142  * __kunit_add_resource() - Internal helper to add a resource.
143  *
144  * res->should_kfree is not initialised.
145  * @test: The test context object.
146  * @init: a user-supplied function to initialize the result (if needed).  If
147  *        none is supplied, the resource data value is simply set to @data.
148  *	  If an init function is supplied, @data is passed to it instead.
149  * @free: a user-supplied function to free the resource (if needed).
150  * @res: The resource.
151  * @data: value to pass to init function or set in resource data field.
152  */
153 int __kunit_add_resource(struct kunit *test,
154 			 kunit_resource_init_t init,
155 			 kunit_resource_free_t free,
156 			 struct kunit_resource *res,
157 			 void *data);
158 
159 /**
160  * kunit_add_resource() - Add a *test managed resource*.
161  * @test: The test context object.
162  * @init: a user-supplied function to initialize the result (if needed).  If
163  *        none is supplied, the resource data value is simply set to @data.
164  *	  If an init function is supplied, @data is passed to it instead.
165  * @free: a user-supplied function to free the resource (if needed).
166  * @res: The resource.
167  * @data: value to pass to init function or set in resource data field.
168  */
169 static inline int kunit_add_resource(struct kunit *test,
170 				     kunit_resource_init_t init,
171 				     kunit_resource_free_t free,
172 				     struct kunit_resource *res,
173 				     void *data)
174 {
175 	res->should_kfree = false;
176 	return __kunit_add_resource(test, init, free, res, data);
177 }
178 
179 static inline struct kunit_resource *
180 kunit_find_named_resource(struct kunit *test, const char *name);
181 
182 /**
183  * kunit_add_named_resource() - Add a named *test managed resource*.
184  * @test: The test context object.
185  * @init: a user-supplied function to initialize the resource data, if needed.
186  * @free: a user-supplied function to free the resource data, if needed.
187  * @res: The resource.
188  * @name: name to be set for resource.
189  * @data: value to pass to init function or set in resource data field.
190  */
191 static inline int kunit_add_named_resource(struct kunit *test,
192 					   kunit_resource_init_t init,
193 					   kunit_resource_free_t free,
194 					   struct kunit_resource *res,
195 					   const char *name,
196 					   void *data)
197 {
198 	struct kunit_resource *existing;
199 
200 	if (!name)
201 		return -EINVAL;
202 
203 	existing = kunit_find_named_resource(test, name);
204 	if (existing) {
205 		kunit_put_resource(existing);
206 		return -EEXIST;
207 	}
208 
209 	res->name = name;
210 	res->should_kfree = false;
211 
212 	return __kunit_add_resource(test, init, free, res, data);
213 }
214 
215 /**
216  * kunit_alloc_and_get_resource() - Allocates and returns a *test managed resource*.
217  * @test: The test context object.
218  * @init: a user supplied function to initialize the resource.
219  * @free: a user supplied function to free the resource (if needed).
220  * @internal_gfp: gfp to use for internal allocations, if unsure, use GFP_KERNEL
221  * @context: for the user to pass in arbitrary data to the init function.
222  *
223  * Allocates a *test managed resource*, a resource which will automatically be
224  * cleaned up at the end of a test case. See &struct kunit_resource for an
225  * example.
226  *
227  * This is effectively identical to kunit_alloc_resource, but returns the
228  * struct kunit_resource pointer, not just the 'data' pointer. It therefore
229  * also increments the resource's refcount, so kunit_put_resource() should be
230  * called when you've finished with it.
231  *
232  * Note: KUnit needs to allocate memory for a kunit_resource object. You must
233  * specify an @internal_gfp that is compatible with the use context of your
234  * resource.
235  */
236 static inline struct kunit_resource *
237 kunit_alloc_and_get_resource(struct kunit *test,
238 			     kunit_resource_init_t init,
239 			     kunit_resource_free_t free,
240 			     gfp_t internal_gfp,
241 			     void *context)
242 {
243 	struct kunit_resource *res;
244 	int ret;
245 
246 	res = kzalloc(sizeof(*res), internal_gfp);
247 	if (!res)
248 		return NULL;
249 
250 	res->should_kfree = true;
251 
252 	ret = __kunit_add_resource(test, init, free, res, context);
253 	if (!ret) {
254 		/*
255 		 * bump refcount for get; kunit_resource_put() should be called
256 		 * when done.
257 		 */
258 		kunit_get_resource(res);
259 		return res;
260 	}
261 	return NULL;
262 }
263 
264 /**
265  * kunit_alloc_resource() - Allocates a *test managed resource*.
266  * @test: The test context object.
267  * @init: a user supplied function to initialize the resource.
268  * @free: a user supplied function to free the resource (if needed).
269  * @internal_gfp: gfp to use for internal allocations, if unsure, use GFP_KERNEL
270  * @context: for the user to pass in arbitrary data to the init function.
271  *
272  * Allocates a *test managed resource*, a resource which will automatically be
273  * cleaned up at the end of a test case. See &struct kunit_resource for an
274  * example.
275  *
276  * Note: KUnit needs to allocate memory for a kunit_resource object. You must
277  * specify an @internal_gfp that is compatible with the use context of your
278  * resource.
279  */
280 static inline void *kunit_alloc_resource(struct kunit *test,
281 					 kunit_resource_init_t init,
282 					 kunit_resource_free_t free,
283 					 gfp_t internal_gfp,
284 					 void *context)
285 {
286 	struct kunit_resource *res;
287 
288 	res = kzalloc(sizeof(*res), internal_gfp);
289 	if (!res)
290 		return NULL;
291 
292 	res->should_kfree = true;
293 	if (!__kunit_add_resource(test, init, free, res, context))
294 		return res->data;
295 
296 	return NULL;
297 }
298 
299 typedef bool (*kunit_resource_match_t)(struct kunit *test,
300 				       struct kunit_resource *res,
301 				       void *match_data);
302 
303 /**
304  * kunit_resource_name_match() - Match a resource with the same name.
305  * @test: Test case to which the resource belongs.
306  * @res: The resource.
307  * @match_name: The name to match against.
308  */
309 static inline bool kunit_resource_name_match(struct kunit *test,
310 					     struct kunit_resource *res,
311 					     void *match_name)
312 {
313 	return res->name && strcmp(res->name, match_name) == 0;
314 }
315 
316 /**
317  * kunit_find_resource() - Find a resource using match function/data.
318  * @test: Test case to which the resource belongs.
319  * @match: match function to be applied to resources/match data.
320  * @match_data: data to be used in matching.
321  */
322 static inline struct kunit_resource *
323 kunit_find_resource(struct kunit *test,
324 		    kunit_resource_match_t match,
325 		    void *match_data)
326 {
327 	struct kunit_resource *res, *found = NULL;
328 	unsigned long flags;
329 
330 	spin_lock_irqsave(&test->lock, flags);
331 
332 	list_for_each_entry_reverse(res, &test->resources, node) {
333 		if (match(test, res, (void *)match_data)) {
334 			found = res;
335 			kunit_get_resource(found);
336 			break;
337 		}
338 	}
339 
340 	spin_unlock_irqrestore(&test->lock, flags);
341 
342 	return found;
343 }
344 
345 /**
346  * kunit_find_named_resource() - Find a resource using match name.
347  * @test: Test case to which the resource belongs.
348  * @name: match name.
349  */
350 static inline struct kunit_resource *
351 kunit_find_named_resource(struct kunit *test,
352 			  const char *name)
353 {
354 	return kunit_find_resource(test, kunit_resource_name_match,
355 				   (void *)name);
356 }
357 
358 /**
359  * kunit_destroy_resource() - Find a kunit_resource and destroy it.
360  * @test: Test case to which the resource belongs.
361  * @match: Match function. Returns whether a given resource matches @match_data.
362  * @match_data: Data passed into @match.
363  *
364  * RETURNS:
365  * 0 if kunit_resource is found and freed, -ENOENT if not found.
366  */
367 int kunit_destroy_resource(struct kunit *test,
368 			   kunit_resource_match_t match,
369 			   void *match_data);
370 
371 static inline int kunit_destroy_named_resource(struct kunit *test,
372 					       const char *name)
373 {
374 	return kunit_destroy_resource(test, kunit_resource_name_match,
375 				      (void *)name);
376 }
377 
378 /**
379  * kunit_remove_resource() - remove resource from resource list associated with
380  *			     test.
381  * @test: The test context object.
382  * @res: The resource to be removed.
383  *
384  * Note that the resource will not be immediately freed since it is likely
385  * the caller has a reference to it via alloc_and_get() or find();
386  * in this case a final call to kunit_put_resource() is required.
387  */
388 void kunit_remove_resource(struct kunit *test, struct kunit_resource *res);
389 
390 /* A 'deferred action' function to be used with kunit_add_action. */
391 typedef void (kunit_action_t)(void *);
392 
393 /**
394  * kunit_add_action() - Call a function when the test ends.
395  * @test: Test case to associate the action with.
396  * @action: The function to run on test exit
397  * @ctx: Data passed into @func
398  *
399  * Defer the execution of a function until the test exits, either normally or
400  * due to a failure.  @ctx is passed as additional context. All functions
401  * registered with kunit_add_action() will execute in the opposite order to that
402  * they were registered in.
403  *
404  * This is useful for cleaning up allocated memory and resources, as these
405  * functions are called even if the test aborts early due to, e.g., a failed
406  * assertion.
407  *
408  * See also: devm_add_action() for the devres equivalent.
409  *
410  * Returns:
411  *   0 on success, an error if the action could not be deferred.
412  */
413 int kunit_add_action(struct kunit *test, kunit_action_t *action, void *ctx);
414 
415 /**
416  * kunit_add_action_or_reset() - Call a function when the test ends.
417  * @test: Test case to associate the action with.
418  * @action: The function to run on test exit
419  * @ctx: Data passed into @func
420  *
421  * Defer the execution of a function until the test exits, either normally or
422  * due to a failure.  @ctx is passed as additional context. All functions
423  * registered with kunit_add_action() will execute in the opposite order to that
424  * they were registered in.
425  *
426  * This is useful for cleaning up allocated memory and resources, as these
427  * functions are called even if the test aborts early due to, e.g., a failed
428  * assertion.
429  *
430  * If the action cannot be created (e.g., due to the system being out of memory),
431  * then action(ctx) will be called immediately, and an error will be returned.
432  *
433  * See also: devm_add_action_or_reset() for the devres equivalent.
434  *
435  * Returns:
436  *   0 on success, an error if the action could not be deferred.
437  */
438 int kunit_add_action_or_reset(struct kunit *test, kunit_action_t *action,
439 			      void *ctx);
440 
441 /**
442  * kunit_remove_action() - Cancel a matching deferred action.
443  * @test: Test case the action is associated with.
444  * @action: The deferred function to cancel.
445  * @ctx: The context passed to the deferred function to trigger.
446  *
447  * Prevent an action deferred via kunit_add_action() from executing when the
448  * test terminates.
449  *
450  * If the function/context pair was deferred multiple times, only the most
451  * recent one will be cancelled.
452  *
453  * See also: devm_remove_action() for the devres equivalent.
454  */
455 void kunit_remove_action(struct kunit *test,
456 			 kunit_action_t *action,
457 			 void *ctx);
458 
459 /**
460  * kunit_release_action() - Run a matching action call immediately.
461  * @test: Test case the action is associated with.
462  * @action: The deferred function to trigger.
463  * @ctx: The context passed to the deferred function to trigger.
464  *
465  * Execute a function deferred via kunit_add_action()) immediately, rather than
466  * when the test ends.
467  *
468  * If the function/context pair was deferred multiple times, it will only be
469  * executed once here. The most recent deferral will no longer execute when
470  * the test ends.
471  *
472  * kunit_release_action(test, func, ctx);
473  * is equivalent to
474  * func(ctx);
475  * kunit_remove_action(test, func, ctx);
476  *
477  * See also: devm_release_action() for the devres equivalent.
478  */
479 void kunit_release_action(struct kunit *test,
480 			  kunit_action_t *action,
481 			  void *ctx);
482 #endif /* _KUNIT_RESOURCE_H */
483