| Message ID | 20200415201653.106-1-l.rubusch@gmail.com (mailing list archive) |
|---|---|
| State | Mainlined |
| Commit | c4714b0045ac74f3b578851e312f9fbccfb382db |
| Headers | show |
| Series | [v5] Documentation: test.h - fix warnings | expand |
On Wed, Apr 15, 2020 at 1:18 PM Lothar Rubusch <l.rubusch@gmail.com> wrote: > > Fix warnings at 'make htmldocs', and formatting issues in the resulting > documentation. > > - test.h: Fix annotation in kernel-doc parameter description. > > - Documentation/*.rst: Fixing formatting issues, and a duplicate label > issue due to usage of sphinx.ext.autosectionlabel and identical labels > within one document (sphinx warning) > > Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com> Reviewed-by: Brendan Higgins <brendanhiggins@google.com> FYI: I already gave you a Reviewed-by. In the future, please add Reviewed-bys you get to any follow-up patches. (You don't have to do anything if you get a Reviewed-by and don't have to send follow-up revisions.) Let me know if you have any questions about how this works. > --- > v2: Several documentation fixes > > v3: Do not touch API documentation index > > v4: Replace macro argument in test.h by named variadic argument > > v5: Patch format fixed > > NB: checkpatch.pl will complain about flow control statements (i.e. usage > of "return") within the macro kunit_test_suites(suites_list...). Yeah, it's a "bad code smell", but not necessarily always wrong, so right now we don't have anything better than to just always warn and sometimes ignore. > Better? Looks good to me! > I feel I'm making you a lot of extra work. I'm really sorry for > all this fuzz! No worries. Our documentation/on-boarding processes are at best not very good and at worst non-existent, so this is pretty much just par for the course. Thanks for sticking with this! I know getting up to speed on upstream Linux kernel development can be painful and tedious. I have been there myself, and I still make lots of silly mistakes. :-) Sorry, if I ever seemed impatient: I am not annoyed. I respond to dozens of emails everyday, so I can sometimes get rather terse as a result of trying to be expedient. I hope you understand! Trust me, once you go to a Linux conference and you meet some devs, you will find that in person, most of us are super nice people, even the ones who can *seem* mean and frustrated on the list. Thanks for the patch! Hope to see you around in the community!
On Wed, 15 Apr 2020 20:16:53 +0000 Lothar Rubusch <l.rubusch@gmail.com> wrote: > Fix warnings at 'make htmldocs', and formatting issues in the resulting > documentation. > > - test.h: Fix annotation in kernel-doc parameter description. > > - Documentation/*.rst: Fixing formatting issues, and a duplicate label > issue due to usage of sphinx.ext.autosectionlabel and identical labels > within one document (sphinx warning) > > Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com> > --- > v2: Several documentation fixes > > v3: Do not touch API documentation index > > v4: Replace macro argument in test.h by named variadic argument > > v5: Patch format fixed > > NB: checkpatch.pl will complain about flow control statements (i.e. usage > of "return") within the macro kunit_test_suites(suites_list...). > > Better? I feel I'm making you a lot of extra work. I'm really sorry for > all this fuzz! So I'm assuming this will go via Shuah's tree; let me know if that's incorrect. Thanks, jon
On 4/21/20 1:33 PM, Jonathan Corbet wrote: > On Wed, 15 Apr 2020 20:16:53 +0000 > Lothar Rubusch <l.rubusch@gmail.com> wrote: > >> Fix warnings at 'make htmldocs', and formatting issues in the resulting >> documentation. >> >> - test.h: Fix annotation in kernel-doc parameter description. >> >> - Documentation/*.rst: Fixing formatting issues, and a duplicate label >> issue due to usage of sphinx.ext.autosectionlabel and identical labels >> within one document (sphinx warning) >> >> Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com> >> --- >> v2: Several documentation fixes >> >> v3: Do not touch API documentation index >> >> v4: Replace macro argument in test.h by named variadic argument >> >> v5: Patch format fixed >> >> NB: checkpatch.pl will complain about flow control statements (i.e. usage >> of "return") within the macro kunit_test_suites(suites_list...). >> >> Better? I feel I'm making you a lot of extra work. I'm really sorry for >> all this fuzz! > > So I'm assuming this will go via Shuah's tree; let me know if that's > incorrect. > Applied to linux-kselftest kunit for Linux 5.8-rc1. thanks, -- Shuah
diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index e1c5ce80ce12..bb112cf70624 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -32,15 +32,17 @@ test targets as well. The ``.kunitconfig`` should also contain any other config options required by the tests. A good starting point for a ``.kunitconfig`` is the KUnit defconfig: + .. code-block:: bash cd $PATH_TO_LINUX_REPO cp arch/um/configs/kunit_defconfig .kunitconfig You can then add any other Kconfig options you wish, e.g.: + .. code-block:: none - CONFIG_LIST_KUNIT_TEST=y + CONFIG_LIST_KUNIT_TEST=y :doc:`kunit_tool <kunit-tool>` will ensure that all config options set in ``.kunitconfig`` are set in the kernel ``.config`` before running the tests. @@ -54,8 +56,8 @@ using. other tools (such as make menuconfig) to adjust other config options. -Running the tests ------------------ +Running the tests (KUnit Wrapper) +--------------------------------- To make sure that everything is set up correctly, simply invoke the Python wrapper from your kernel repo: @@ -105,8 +107,9 @@ have config options ending in ``_KUNIT_TEST``. KUnit and KUnit tests can be compiled as modules: in this case the tests in a module will be run when the module is loaded. -Running the tests ------------------ + +Running the tests (w/o KUnit Wrapper) +------------------------------------- Build and run your kernel as usual. Test output will be written to the kernel log in `TAP <https://testanything.org/>`_ format. diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 473a2361ec37..3c3fe8b5fecc 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -595,7 +595,7 @@ able to run one test case per invocation. KUnit debugfs representation ============================ When kunit test suites are initialized, they create an associated directory -in /sys/kernel/debug/kunit/<test-suite>. The directory contains one file +in ``/sys/kernel/debug/kunit/<test-suite>``. The directory contains one file - results: "cat results" displays results of each test case and the results of the entire suite for the last test run. @@ -604,4 +604,4 @@ The debugfs representation is primarily of use when kunit test suites are run in a native environment, either as modules or builtin. Having a way to display results like this is valuable as otherwise results can be intermixed with other events in dmesg output. The maximum size of each -results file is KUNIT_LOG_SIZE bytes (defined in include/kunit/test.h). +results file is KUNIT_LOG_SIZE bytes (defined in ``include/kunit/test.h``). diff --git a/include/kunit/test.h b/include/kunit/test.h index 9b0c46a6ca1f..47e61e1d5337 100644 --- a/include/kunit/test.h +++ b/include/kunit/test.h @@ -175,7 +175,7 @@ struct kunit_suite { void (*exit)(struct kunit *test); struct kunit_case *test_cases; - /* private - internal use only */ + /* private: internal use only */ struct dentry *debugfs; char *log; }; @@ -232,12 +232,12 @@ void __kunit_test_suites_exit(struct kunit_suite **suites); * kunit_test_suites() - used to register one or more &struct kunit_suite * with KUnit. * - * @suites: a statically allocated list of &struct kunit_suite. + * @suites_list...: a statically allocated list of &struct kunit_suite. * - * Registers @suites with the test framework. See &struct kunit_suite for + * Registers @suites_list with the test framework. See &struct kunit_suite for * more information. * - * When builtin, KUnit tests are all run as late_initcalls; this means + * When builtin, KUnit tests are all run as late_initcalls; this means * that they cannot test anything where tests must run at a different init * phase. One significant restriction resulting from this is that KUnit * cannot reliably test anything that is initialize in the late_init phase; @@ -253,8 +253,8 @@ void __kunit_test_suites_exit(struct kunit_suite **suites); * tests from the same place, and at the very least to do so after * everything else is definitely initialized. */ -#define kunit_test_suites(...) \ - static struct kunit_suite *suites[] = { __VA_ARGS__, NULL}; \ +#define kunit_test_suites(suites_list...) \ + static struct kunit_suite *suites[] = {suites_list, NULL}; \ static int kunit_test_suites_init(void) \ { \ return __kunit_test_suites_init(suites); \
Fix warnings at 'make htmldocs', and formatting issues in the resulting documentation. - test.h: Fix annotation in kernel-doc parameter description. - Documentation/*.rst: Fixing formatting issues, and a duplicate label issue due to usage of sphinx.ext.autosectionlabel and identical labels within one document (sphinx warning) Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com> --- v2: Several documentation fixes v3: Do not touch API documentation index v4: Replace macro argument in test.h by named variadic argument v5: Patch format fixed NB: checkpatch.pl will complain about flow control statements (i.e. usage of "return") within the macro kunit_test_suites(suites_list...). Better? I feel I'm making you a lot of extra work. I'm really sorry for all this fuzz! Documentation/dev-tools/kunit/start.rst | 13 ++++++++----- Documentation/dev-tools/kunit/usage.rst | 4 ++-- include/kunit/test.h | 12 ++++++------ 3 files changed, 16 insertions(+), 13 deletions(-)