linux-kernel - [PATCH RESEND 6/7] Documentation: kunit: rewrite "Run Tests without kunit

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20221023130846.63296-7-bagasdotme@gmail.com>
Date:   Sun, 23 Oct 2022 20:08:46 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        linux-kselftest@...r.kernel.org, kunit-dev@...glegroups.com
Cc:     Jonathan Corbet <corbet@....net>,
        Brendan Higgins <brendan.higgins@...ux.dev>,
        David Gow <davidgow@...gle.com>,
        Lukas Bulwahn <lukas.bulwahn@...il.com>,
        Khalid Masum <khalid.masum.92@...il.com>,
        Sadiya Kazi <sadiyakazi@...gle.com>,
        Bagas Sanjaya <bagasdotme@...il.com>
Subject: [PATCH RESEND 6/7] Documentation: kunit: rewrite "Run Tests without kunit_tool"

Rewrite the documentation for clarity. Major points:

  * Use second-person point of view
  * Align and format the first note like other note blocks
  * Remove unnecessary lists and trivial modprobe code block (every
    developer should have known how to load modules)

Signed-off-by: Bagas Sanjaya <bagasdotme@...il.com>
---
 Documentation/dev-tools/kunit/run_manual.rst | 68 ++++++++------------
 1 file changed, 27 insertions(+), 41 deletions(-)

diff --git a/Documentation/dev-tools/kunit/run_manual.rst b/Documentation/dev-tools/kunit/run_manual.rst
index e7b46421f247e1..28c6a1caa0fed0 100644
--- a/Documentation/dev-tools/kunit/run_manual.rst
+++ b/Documentation/dev-tools/kunit/run_manual.rst
@@ -4,54 +4,40 @@
 Run Tests without kunit_tool
 ============================
 
-If we do not want to use kunit_tool (For example: we want to integrate
-with other systems, or run tests on real hardware), we can
-include KUnit in any kernel, read out results, and parse manually.
+If you do not want to use kunit_tool (e.g. integrating
+with other testing framework or running tests on real hardware), you
+can run KUnit-enabled kernel manually. The test results can be parsed with
+your existing tools.
 
-.. note:: KUnit is not designed for use in a production system. It is
-          possible that tests may reduce the stability or security of
-          the system.
+.. note::
 
-Configure the Kernel
+	Using KUnit is not recommended in production system, since
+	stability and security issues may occur if it is enabled.
+
+Kernel configuration
 ====================
 
-KUnit tests can run without kunit_tool. This can be useful, if:
+To enable KUnit, configure the kernel with ``CONFIG_KUNIT`` enabled.
+Individual tests can then be selected. KUnit tests usually (but don't always)
+have configuration name suffixed with ``_KUNIT_TEST``. As with other kernel
+configurations, most tests can be enabled either builtin or as module.
 
-- We have an existing kernel configuration to test.
-- Need to run on real hardware (or using an emulator/VM kunit_tool
-  does not support).
-- Wish to integrate with some existing testing systems.
+.. note::
 
-KUnit is configured with the ``CONFIG_KUNIT`` option, and individual
-tests can also be built by enabling their config options in our
-``.config``. KUnit tests usually (but don't always) have config options
-ending in ``_KUNIT_TEST``. Most tests can either be built as a module,
-or be built into the kernel.
+	You can enable ``KUNIT_ALL_TESTS``, which automatically enable all
+	tests for which their dependencies can be satisfied. This is a good
+        way of quickly testing everything applicable to the current
+        configuration.
 
-.. note ::
+Once the kernel have been built and installed, it is simple to run
+the tests just by booting the kernel. If these are builtin, they will run
+automatically. If these are built as modules, they will need to be loaded
+first in order to run them.
 
-	We can enable the ``KUNIT_ALL_TESTS`` config option to
-	automatically enable all tests with satisfied dependencies. This is
-	a good way of quickly testing everything applicable to the current
-	config.
+The test results will be logged in TAP format in ``dmesg``.
 
-Once we have built our kernel (and/or modules), it is simple to run
-the tests. If the tests are built-in, they will run automatically on the
-kernel boot. The results will be written to the kernel log (``dmesg``)
-in TAP format.
+.. note::
 
-If the tests are built as modules, they will run when the module is
-loaded.
-
-.. code-block :: bash
-
-	# modprobe example-test
-
-The results will appear in TAP format in ``dmesg``.
-
-.. 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.
+	If ``CONFIG_KUNIT_DEBUGFS`` is enabled, the test results can
+	be accessed from debugfs (if mounted). Results for each test suite
+	will be in ``/sys/kernel/debug/kunit/<test_suite>/results``.
-- 
An old man doll... just what I always wanted! - Clara