| Message ID | 20231213010201.1802507-6-rmoar@google.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | e9f0e21ceb65ea5e450ede7c9b9a5bfc90a403ae |
| Delegated to: | Brendan Higgins |
| Headers | show |
| Series | [v4,1/6] kunit: move KUNIT_TABLE out of INIT_DATA | expand |
On Wed, 13 Dec 2023 at 09:02, Rae Moar <rmoar@google.com> wrote: > > Expand the documentation on the KUnit debugfs filesystem on the > run_manual.rst page. > > Add section describing how to access results using debugfs. > > Add section describing how to run tests after boot using debugfs. > > Signed-off-by: Rae Moar <rmoar@google.com> > --- Looks good! Reviewed-by: David Gow <davidgow@google.com> Thanks, -- David > Changes since v3: > - Change the introduction of the debugfs section > - Add detail to not being able to run concurrently or run with init data > > Documentation/dev-tools/kunit/run_manual.rst | 51 ++++++++++++++++++-- > 1 file changed, 47 insertions(+), 4 deletions(-) > > diff --git a/Documentation/dev-tools/kunit/run_manual.rst b/Documentation/dev-tools/kunit/run_manual.rst > index e7b46421f247..699d92885075 100644 > --- a/Documentation/dev-tools/kunit/run_manual.rst > +++ b/Documentation/dev-tools/kunit/run_manual.rst > @@ -49,9 +49,52 @@ loaded. > > The results will appear in TAP format in ``dmesg``. > > +debugfs > +======= > + > +KUnit can be accessed from userspace via the debugfs filesystem (See more > +information about debugfs at Documentation/filesystems/debugfs.rst). > + > +If ``CONFIG_KUNIT_DEBUGFS`` is enabled, the KUnit debugfs filesystem is > +mounted at /sys/kernel/debug/kunit. You can use this filesystem to perform > +the following actions. > + > +Retrieve Test Results > +===================== > + > +You can use debugfs to retrieve KUnit test results. The test results are > +accessible from the debugfs filesystem in the following read-only file: > + > +.. code-block :: bash > + > + /sys/kernel/debug/kunit/<test_suite>/results > + > +The test results are printed in a KTAP document. Note this document is separate > +to the kernel log and thus, may have different test suite numbering. > + > +Run Tests After Kernel Has Booted > +================================= > + > +You can use the debugfs filesystem to trigger built-in tests to run after > +boot. To run the test suite, you can use the following command to write to > +the ``/sys/kernel/debug/kunit/<test_suite>/run`` file: > + > +.. code-block :: bash > + > + echo "any string" > /sys/kernel/debugfs/kunit/<test_suite>/run > + > +As a result, the test suite runs and the results are printed to the kernel > +log. > + > +However, this feature is not available with KUnit suites that use init data, > +because init data may have been discarded after the kernel boots. KUnit > +suites that use init data should be defined using the > +kunit_test_init_section_suites() macro. > + > +Also, you cannot use this feature to run tests concurrently. Instead a test > +will wait to run until other tests have completed or failed. > + > .. note :: > > - If ``CONFIG_KUNIT_DEBUGFS`` is enabled, KUnit test results will > - be accessible from the ``debugfs`` filesystem (if mounted). > - They will be in ``/sys/kernel/debug/kunit/<test_suite>/results``, in > - TAP format. > + For test authors, to use this feature, tests will need to correctly initialise > + and/or clean up any data, so the test runs correctly a second time. > -- > 2.43.0.472.g3155946c3a-goog >
diff --git a/Documentation/dev-tools/kunit/run_manual.rst b/Documentation/dev-tools/kunit/run_manual.rst index e7b46421f247..699d92885075 100644 --- a/Documentation/dev-tools/kunit/run_manual.rst +++ b/Documentation/dev-tools/kunit/run_manual.rst @@ -49,9 +49,52 @@ loaded. The results will appear in TAP format in ``dmesg``. +debugfs +======= + +KUnit can be accessed from userspace via the debugfs filesystem (See more +information about debugfs at Documentation/filesystems/debugfs.rst). + +If ``CONFIG_KUNIT_DEBUGFS`` is enabled, the KUnit debugfs filesystem is +mounted at /sys/kernel/debug/kunit. You can use this filesystem to perform +the following actions. + +Retrieve Test Results +===================== + +You can use debugfs to retrieve KUnit test results. The test results are +accessible from the debugfs filesystem in the following read-only file: + +.. code-block :: bash + + /sys/kernel/debug/kunit/<test_suite>/results + +The test results are printed in a KTAP document. Note this document is separate +to the kernel log and thus, may have different test suite numbering. + +Run Tests After Kernel Has Booted +================================= + +You can use the debugfs filesystem to trigger built-in tests to run after +boot. To run the test suite, you can use the following command to write to +the ``/sys/kernel/debug/kunit/<test_suite>/run`` file: + +.. code-block :: bash + + echo "any string" > /sys/kernel/debugfs/kunit/<test_suite>/run + +As a result, the test suite runs and the results are printed to the kernel +log. + +However, this feature is not available with KUnit suites that use init data, +because init data may have been discarded after the kernel boots. KUnit +suites that use init data should be defined using the +kunit_test_init_section_suites() macro. + +Also, you cannot use this feature to run tests concurrently. Instead a test +will wait to run until other tests have completed or failed. + .. note :: - If ``CONFIG_KUNIT_DEBUGFS`` is enabled, KUnit test results will - be accessible from the ``debugfs`` filesystem (if mounted). - They will be in ``/sys/kernel/debug/kunit/<test_suite>/results``, in - TAP format. + For test authors, to use this feature, tests will need to correctly initialise + and/or clean up any data, so the test runs correctly a second time.
Expand the documentation on the KUnit debugfs filesystem on the run_manual.rst page. Add section describing how to access results using debugfs. Add section describing how to run tests after boot using debugfs. Signed-off-by: Rae Moar <rmoar@google.com> --- Changes since v3: - Change the introduction of the debugfs section - Add detail to not being able to run concurrently or run with init data Documentation/dev-tools/kunit/run_manual.rst | 51 ++++++++++++++++++-- 1 file changed, 47 insertions(+), 4 deletions(-)