Skip to contentSkip to conversation

kunit: split resource API from test.h into new resource.h

PATCH Superseded Daniel Latypov 3 participants 5 messages Mar 26, 2022 – Mar 28, 2022

Subsystems (4)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/2 kunit: split resource API from test.h into new resource.h

Background:
Currently, a reader looking at kunit/test.h will find the file is quite long, and the first meaty comment is a doc comment about struct kunit_resource.

Most users will not ever use the KUnit resource API directly. They'll use kunit_kmalloc() and friends, or decide it's simpler to do cleanups via labels (it often can be) instead of figuring out how to use the API.

It's also logically separate from everything else in test.h. Removing it from the file doesn't cause any compilation errors (since struct kunit has struct list_head resources to store them).

This commit:
Let's move it into a kunit/resource.h file and give it a separate page in the docs, kunit/api/resource.rst.

We include resource.h at the bottom of test.h since
* don't want to force existing users to add a new include if they use the API
* it accesses lock inside struct kunit in a inline func
* so we can't just forward declare, and the alternatives require uninlining the func, adding hepers to lock/unlock, or other more invasive changes.

Now the first big comment in test.h is about kunit_case, which is a lot more relevant to what a new user wants to know.

A side effect of this is git blame won't properly track history by default, users need to run

$ git blame -L ,1 -C17 include/kunit/resource.h

---
v1 -> v2: add TODO to make users #include resource.h, drop redundant fwd decl of struct kunit in resource.h

---
 Documentation/dev-tools/kunit/api/index.rst   |   5 +
 .../dev-tools/kunit/api/resource.rst          |  13 +
 include/kunit/resource.h                      | 318 ++++++++++++++++++
 include/kunit/test.h                          | 303 +----------------
 4 files changed, 340 insertions(+), 299 deletions(-)
 create mode 100644 Documentation/dev-tools/kunit/api/resource.rst
 create mode 100644 include/kunit/resource.h
Documentation/dev-tools/kunit/api/index.rst +5 -0
index 3006cadcf44a..45ce04823f9f 100644
@@ -6,6 +6,7 @@ API Reference
 .. toctree::
 
 	test
+	resource
 
 This section documents the KUnit kernel testing API. It is divided into the
 following sections:
@@ -13,3 +14,7 @@ following sections:
 Documentation/dev-tools/kunit/api/test.rst
 
  - documents all of the standard testing API
+
+Documentation/dev-tools/kunit/api/resource.rst
+
+ - documents the KUnit resource API
Documentation/dev-tools/kunit/api/resource.rst new file +13 -0
new file mode 100644
index 000000000000..0a94f831259e
@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+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.
+
+.. kernel-doc:: include/kunit/resource.h
+   :internal:
include/kunit/resource.h new file +318 -0

318 lines not on this page · raw message

include/kunit/test.h +4 -299

319 lines not on this page · raw message

base-commit: b14ffae378aa1db993e62b01392e70d1e585fb23

Signature · 1 line
2.35.1.1021.g381101b075-goog
#1 lore raw

PATCH v2 2/2 kunit: split resource API impl from test.c into new resource.c

We've split out the declarations from include/kunit/test.h into resource.h.
This patch splits out the definitions as well for consistency.

A side effect of this is git blame won't properly track history by default, users need to run

$ git blame -L ,1 -C13 lib/kunit/resource.c
---
 lib/kunit/Makefile   |   1 +
 lib/kunit/resource.c | 126 +++++++++++++++++++++++++++++++++++++++++++
 lib/kunit/test.c     | 116 +--------------------------------------
 3 files changed, 128 insertions(+), 115 deletions(-)
 create mode 100644 lib/kunit/resource.c
lib/kunit/Makefile +1 -0
index c49f4ffb6273..29aff6562b42 100644
@@ -1,6 +1,7 @@
 obj-$(CONFIG_KUNIT) +=			kunit.o
 
 kunit-objs +=				test.o \
+					resource.o \
 					string-stream.o \
 					assert.o \
 					try-catch.o \
lib/kunit/resource.c new file +126 -0

126 lines not on this page · raw message

lib/kunit/test.c +1 -115

131 lines not on this page · raw message

Signature · 1 line
2.35.1.1021.g381101b075-goog
Reviewed-by on v2 2/2
#2 lore raw

Re: [PATCH v2 2/2] kunit: split resource API impl from test.c into new resource.c

Quoted 11 lines · Daniel Latypov

We've split out the declarations from include/kunit/test.h into resource.h.
This patch splits out the definitions as well for consistency.

A side effect of this is git blame won't properly track history by default, users need to run

$ git blame -L ,1 -C13 lib/kunit/resource.c

---

Looks good and works fine here. I'm going to try to rebase most of the other resource system stuff I'm working on on top of these (which will likely end up moving a bunch of code _again_, but is probably the least terrible of all the available options).

One nitpick (newline at end of file) below, otherwise this is good.

Cheers,
-- David

Quoted 140 lines
 lib/kunit/Makefile   |   1 +
 lib/kunit/resource.c | 126 +++++++++++++++++++++++++++++++++++++++++++
 lib/kunit/test.c     | 116 +--------------------------------------
 3 files changed, 128 insertions(+), 115 deletions(-)
 create mode 100644 lib/kunit/resource.c
lib/kunit/Makefile +1 -0
index c49f4ffb6273..29aff6562b42 100644
@@ -1,6 +1,7 @@
 obj-$(CONFIG_KUNIT) +=                 kunit.o
 
 kunit-objs +=                          test.o \
+                                       resource.o \
                                        string-stream.o \
                                        assert.o \
                                        try-catch.o \
lib/kunit/resource.c new file +116 -0
new file mode 100644
index 000000000000..b8bced246217
@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * KUnit resource API for test managed resources (allocations, etc.).
+ *
+ * Copyright (C) 2022, Google LLC.
+ * Author: Daniel Latypov <[email protected]>
+ */
+
+#include <kunit/resource.h>
+#include <kunit/test.h>
+#include <linux/kref.h>
+
+/*
+ * Used for static resources and when a kunit_resource * has been created by
+ * kunit_alloc_resource().  When an init function is supplied, @data is passed
+ * into the init function; otherwise, we simply set the resource data field to
+ * the data value passed in.
+ */
+int kunit_add_resource(struct kunit *test,
+                      kunit_resource_init_t init,
+                      kunit_resource_free_t free,
+                      struct kunit_resource *res,
+                      void *data)
+{
+       int ret = 0;
+       unsigned long flags;
+
+       res->free = free;
+       kref_init(&res->refcount);
+
+       if (init) {
+               ret = init(res, data);
+               if (ret)
+                       return ret;
+       } else {
+               res->data = data;
+       }
+
+       spin_lock_irqsave(&test->lock, flags);
+       list_add_tail(&res->node, &test->resources);
+       /* refcount for list is established by kref_init() */
+       spin_unlock_irqrestore(&test->lock, flags);
+
+       return ret;
+}
+EXPORT_SYMBOL_GPL(kunit_add_resource);
+
+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)
+{
+       struct kunit_resource *existing;
+
+       if (!name)
+               return -EINVAL;
+
+       existing = kunit_find_named_resource(test, name);
+       if (existing) {
+               kunit_put_resource(existing);
+               return -EEXIST;
+       }
+
+       res->name = name;
+
+       return kunit_add_resource(test, init, free, res, data);
+}
+EXPORT_SYMBOL_GPL(kunit_add_named_resource);
+
+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 *data)
+{
+       struct kunit_resource *res;
+       int ret;
+
+       res = kzalloc(sizeof(*res), internal_gfp);
+       if (!res)
+               return NULL;
+
+       ret = kunit_add_resource(test, init, free, res, data);
+       if (!ret) {
+               /*
+                * bump refcount for get; kunit_resource_put() should be called
+                * when done.
+                */
+               kunit_get_resource(res);
+               return res;
+       }
+       return NULL;
+}
+EXPORT_SYMBOL_GPL(kunit_alloc_and_get_resource);
+
+void kunit_remove_resource(struct kunit *test, struct kunit_resource *res)
+{
+       unsigned long flags;
+
+       spin_lock_irqsave(&test->lock, flags);
+       list_del(&res->node);
+       spin_unlock_irqrestore(&test->lock, flags);
+       kunit_put_resource(res);
+}
+EXPORT_SYMBOL_GPL(kunit_remove_resource);
+
+int kunit_destroy_resource(struct kunit *test, kunit_resource_match_t match,
+                          void *match_data)
+{
+       struct kunit_resource *res = kunit_find_resource(test, match,
+                                                        match_data);
+
+       if (!res)
+               return -ENOENT;

lib/kunit/resource.c line 126

Quoted 10 lines
lib/kunit/resource.c new file +10 -0
+
+       kunit_remove_resource(test, res);
+
+       /* We have a reference also via _find(); drop it. */
+       kunit_put_resource(res);
+
+       return 0;
+}
+EXPORT_SYMBOL_GPL(kunit_destroy_resource);
+

.git/rebase-apply/patch:151: new blank line at EOF.

+

Quoted 140 lines
lib/kunit/test.c +1 -116
index 3bca3bf5c15b..0f66c13d126e 100644
@@ -6,10 +6,10 @@
  * Author: Brendan Higgins <[email protected]>
  */
 
+#include <kunit/resource.h>
 #include <kunit/test.h>
 #include <kunit/test-bug.h>
 #include <linux/kernel.h>
-#include <linux/kref.h>
 #include <linux/moduleparam.h>
 #include <linux/sched/debug.h>
 #include <linux/sched.h>
@@ -592,120 +592,6 @@ void __kunit_test_suites_exit(struct kunit_suite **suites)
 }
 EXPORT_SYMBOL_GPL(__kunit_test_suites_exit);
 
-/*
- * Used for static resources and when a kunit_resource * has been created by
- * kunit_alloc_resource().  When an init function is supplied, @data is passed
- * into the init function; otherwise, we simply set the resource data field to
- * the data value passed in.
- */
-int kunit_add_resource(struct kunit *test,
-                      kunit_resource_init_t init,
-                      kunit_resource_free_t free,
-                      struct kunit_resource *res,
-                      void *data)
-{
-       int ret = 0;
-       unsigned long flags;
-
-       res->free = free;
-       kref_init(&res->refcount);
-
-       if (init) {
-               ret = init(res, data);
-               if (ret)
-                       return ret;
-       } else {
-               res->data = data;
-       }
-
-       spin_lock_irqsave(&test->lock, flags);
-       list_add_tail(&res->node, &test->resources);
-       /* refcount for list is established by kref_init() */
-       spin_unlock_irqrestore(&test->lock, flags);
-
-       return ret;
-}
-EXPORT_SYMBOL_GPL(kunit_add_resource);
-
-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)
-{
-       struct kunit_resource *existing;
-
-       if (!name)
-               return -EINVAL;
-
-       existing = kunit_find_named_resource(test, name);
-       if (existing) {
-               kunit_put_resource(existing);
-               return -EEXIST;
-       }
-
-       res->name = name;
-
-       return kunit_add_resource(test, init, free, res, data);
-}
-EXPORT_SYMBOL_GPL(kunit_add_named_resource);
-
-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 *data)
-{
-       struct kunit_resource *res;
-       int ret;
-
-       res = kzalloc(sizeof(*res), internal_gfp);
-       if (!res)
-               return NULL;
-
-       ret = kunit_add_resource(test, init, free, res, data);
-       if (!ret) {
-               /*
-                * bump refcount for get; kunit_resource_put() should be called
-                * when done.
-                */
-               kunit_get_resource(res);
-               return res;
-       }
-       return NULL;
-}
-EXPORT_SYMBOL_GPL(kunit_alloc_and_get_resource);
-
-void kunit_remove_resource(struct kunit *test, struct kunit_resource *res)
-{
-       unsigned long flags;
-
-       spin_lock_irqsave(&test->lock, flags);
-       list_del(&res->node);
-       spin_unlock_irqrestore(&test->lock, flags);
-       kunit_put_resource(res);
-}
-EXPORT_SYMBOL_GPL(kunit_remove_resource);
-
-int kunit_destroy_resource(struct kunit *test, kunit_resource_match_t match,
-                          void *match_data)
-{
-       struct kunit_resource *res = kunit_find_resource(test, match,
-                                                        match_data);
-
-       if (!res)
-               return -ENOENT;
-
-       kunit_remove_resource(test, res);
-
-       /* We have a reference also via _find(); drop it. */
-       kunit_put_resource(res);
-
-       return 0;
-}
-EXPORT_SYMBOL_GPL(kunit_destroy_resource);
-
 struct kunit_kmalloc_array_params {
        size_t n;
        size_t size;
--

2.35.1.1021.g381101b075-goog

#3 lore raw

Re: [PATCH v2 2/2] kunit: split resource API impl from test.c into new resource.c

Quoted 14 lines · David Gow
Quoted 11 lines · Daniel Latypov

We've split out the declarations from include/kunit/test.h into resource.h.
This patch splits out the definitions as well for consistency.

A side effect of this is git blame won't properly track history by default, users need to run

$ git blame -L ,1 -C13 lib/kunit/resource.c

---

Quoted 6 lines

Looks good and works fine here. I'm going to try to rebase most of the other resource system stuff I'm working on on top of these (which will likely end up moving a bunch of code _again_, but is probably the least terrible of all the available options).

One nitpick (newline at end of file) below, otherwise this is good.

Huh, I had thought checkpatch --strict would catch this. I guess not.

Fixing this and sending out a v3.

Quoted 2 lines
Reviewed-by on v2 2/2
#4 lore raw

Re: [PATCH v2 2/2] kunit: split resource API impl from test.c into new resource.c

In reply to Daniel Latypov
Quoted 10 lines · Daniel Latypov

We've split out the declarations from include/kunit/test.h into resource.h.
This patch splits out the definitions as well for consistency.

A side effect of this is git blame won't properly track history by default, users need to run

$ git blame -L ,1 -C13 lib/kunit/resource.c