[PATCH v2 0/8] Documentation: Kunit: clean kunit-tool.rst and start.rst

[PATCH v2 0/8] Documentation: Kunit: clean kunit-tool.rst and start.rst

[Tales Aparecida]

Hi,

Continuing the documentation refactoring started by Harinder Singh[1],
removes kunit-tool.rst, which had its information rearranged into run_wrapper,
and employs further work in the index and the getting-started guide.

This series was written on top of another[2] that haven't got applied yet,
but the only dependency it has is the "kunit-on-qemu" anchor used in start.rst.

Changelog:

v1 -> v2:

- Update expected output for `kunit.py run` from "Generating .config ..." to
"Configuring KUnit Kernel ..."
- Update run_wrapper titles as suggested by Sadiya Kazi
- Remove confusing recommendation from start.rst intro, highlighted by Tim Bird
- Fix grammars nits pointed by Maíra Canal and Sadiya Kazi
- Add some reviewed-by

Thanks again for your feedbacks,
Tales

[1] https://lore.kernel.org/r/20211217044911.798817-1-sharinder@google.com/
[2] https://lore.kernel.org/r/20220813042055.136832-1-tales.aparecida@gmail.com/

Tales Aparecida (8):
  Documentation: KUnit: remove duplicated docs for kunit_tool
  Documentation: KUnit: avoid repeating "kunit.py run" in start.rst
  Documentation: KUnit: add note about mrproper in start.rst
  Documentation: KUnit: Reword start guide for selecting tests
  Documentation: KUnit: add intro to the getting-started page
  Documentation: KUnit: update links in the index page
  lib: overflow: update reference to kunit-tool
  lib: stackinit: update reference to kunit-tool

 Documentation/dev-tools/kunit/index.rst       |  16 +-
 Documentation/dev-tools/kunit/kunit-tool.rst  | 232 ------------------
 Documentation/dev-tools/kunit/run_wrapper.rst |  34 +--
 Documentation/dev-tools/kunit/start.rst       | 136 ++++++----
 lib/overflow_kunit.c                          |   2 +-
 lib/stackinit_kunit.c                         |   2 +-
 6 files changed, 117 insertions(+), 305 deletions(-)
 delete mode 100644 Documentation/dev-tools/kunit/kunit-tool.rst


base-commit: 568035b01cfb107af8d2e4bd2fb9aea22cf5b868
prerequisite-patch-id: b794218cd939a6644aaf5fb2a73997c56a624c80
prerequisite-patch-id: ccd24491ae99152ebdc6dcb8ddb9499d3456a4a0
prerequisite-patch-id: cc17b80d42fd5f5049e144da5c04e922036a33eb
prerequisite-patch-id: ba7edd270c6f285352e0e17bfe65ff6119192113
-- 
2.37.2

[PATCH v2 1/8] Documentation: KUnit: remove duplicated docs for kunit_tool

[Tales Aparecida]

Delete "kunit-tool.rst" to remove repeated info from KUnit docs.
"What is kunit_tool?" was integrated into index.rst, the remaining
sections were moved into run_wrapper.rst and renamed as follows:

"What is a .kunitconfig?" -> "Creating a ``.kunitconfig`` file"
"Getting Started with kunit_tool" -> "Running tests with kunit_tool"
"Configuring, Building, and Running Tests" ->
	"Configuring, building, and running tests"
"Running Tests on QEMU" -> "Running tests on QEMU"
"Parsing Test Results" -> "Parsing test results"
"Filtering Tests" -> "Filtering tests"
"Other Useful Options" -> "Running command-line arguments"

Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
Reviewed-by: Sadiya Kazi <sadiyakazi@google.com>

---
Notes:
    Update titles on run_wrapper.rst (Sadiya Kazi)
---
 Documentation/dev-tools/kunit/index.rst       |   3 -
 Documentation/dev-tools/kunit/kunit-tool.rst  | 232 ------------------
 Documentation/dev-tools/kunit/run_wrapper.rst |  32 +--
 Documentation/dev-tools/kunit/start.rst       |   2 -
 4 files changed, 16 insertions(+), 253 deletions(-)
 delete mode 100644 Documentation/dev-tools/kunit/kunit-tool.rst

diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst
index bc91ad7b8961..d7187282ba28 100644
--- a/Documentation/dev-tools/kunit/index.rst
+++ b/Documentation/dev-tools/kunit/index.rst
@@ -13,7 +13,6 @@ KUnit - Linux Kernel Unit Testing
 	run_wrapper
 	run_manual
 	usage
-	kunit-tool
 	api/index
 	style
 	faq
@@ -109,7 +108,5 @@ How do I use it?
     examples.
 *   Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
     used for testing.
-*   Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper
-    script.
 *   Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
     answers.
diff --git a/Documentation/dev-tools/kunit/kunit-tool.rst b/Documentation/dev-tools/kunit/kunit-tool.rst
deleted file mode 100644
index ae52e0f489f9..000000000000
--- a/Documentation/dev-tools/kunit/kunit-tool.rst
+++ /dev/null
@@ -1,232 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-=================
-kunit_tool How-To
-=================
-
-What is kunit_tool?
-===================
-
-kunit_tool is a script (``tools/testing/kunit/kunit.py``) that aids in building
-the Linux kernel as UML (`User Mode Linux
-<http://user-mode-linux.sourceforge.net/>`_), running KUnit tests, parsing
-the test results and displaying them in a user friendly manner.
-
-kunit_tool addresses the problem of being able to run tests without needing a
-virtual machine or actual hardware with User Mode Linux. User Mode Linux is a
-Linux architecture, like ARM or x86; however, unlike other architectures it
-compiles the kernel as a standalone Linux executable that can be run like any
-other program directly inside of a host operating system. To be clear, it does
-not require any virtualization support: it is just a regular program.
-
-What is a .kunitconfig?
-=======================
-
-It's just a defconfig that kunit_tool looks for in the build directory
-(``.kunit`` by default).  kunit_tool uses it to generate a .config as you might
-expect. In addition, it verifies that the generated .config contains the CONFIG
-options in the .kunitconfig; the reason it does this is so that it is easy to
-be sure that a CONFIG that enables a test actually ends up in the .config.
-
-It's also possible to pass a separate .kunitconfig fragment to kunit_tool,
-which is useful if you have several different groups of tests you wish
-to run independently, or if you want to use pre-defined test configs for
-certain subsystems.
-
-Getting Started with kunit_tool
-===============================
-
-If a kunitconfig is present at the root directory, all you have to do is:
-
-.. code-block:: bash
-
-	./tools/testing/kunit/kunit.py run
-
-However, you most likely want to use it with the following options:
-
-.. code-block:: bash
-
-	./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all`
-
-- ``--timeout`` sets a maximum amount of time to allow tests to run.
-- ``--jobs`` sets the number of threads to use to build the kernel.
-
-.. note::
-	This command will work even without a .kunitconfig file: if no
-	.kunitconfig is present, a default one will be used instead.
-
-If you wish to use a different .kunitconfig file (such as one provided for
-testing a particular subsystem), you can pass it as an option.
-
-.. code-block:: bash
-
-	./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig
-
-For a list of all the flags supported by kunit_tool, you can run:
-
-.. code-block:: bash
-
-	./tools/testing/kunit/kunit.py run --help
-
-Configuring, Building, and Running Tests
-========================================
-
-It's also possible to run just parts of the KUnit build process independently,
-which is useful if you want to make manual changes to part of the process.
-
-A .config can be generated from a .kunitconfig by using the ``config`` argument
-when running kunit_tool:
-
-.. code-block:: bash
-
-	./tools/testing/kunit/kunit.py config
-
-Similarly, if you just want to build a KUnit kernel from the current .config,
-you can use the ``build`` argument:
-
-.. code-block:: bash
-
-	./tools/testing/kunit/kunit.py build
-
-And, if you already have a built UML kernel with built-in KUnit tests, you can
-run the kernel and display the test results with the ``exec`` argument:
-
-.. code-block:: bash
-
-	./tools/testing/kunit/kunit.py exec
-
-The ``run`` command which is discussed above is equivalent to running all three
-of these in sequence.
-
-All of these commands accept a number of optional command-line arguments. The
-``--help`` flag will give a complete list of these, or keep reading this page
-for a guide to some of the more useful ones.
-
-Parsing Test Results
-====================
-
-KUnit tests output their results in TAP (Test Anything Protocol) format.
-kunit_tool will, when running tests, parse this output and print a summary
-which is much more pleasant to read. If you wish to look at the raw test
-results in TAP format, you can pass the ``--raw_output`` argument.
-
-.. code-block:: bash
-
-	./tools/testing/kunit/kunit.py run --raw_output
-
-The raw output from test runs may contain other, non-KUnit kernel log
-lines. You can see just KUnit output with ``--raw_output=kunit``:
-
-.. code-block:: bash
-
-	./tools/testing/kunit/kunit.py run --raw_output=kunit
-
-If you have KUnit results in their raw TAP format, you can parse them and print
-the human-readable summary with the ``parse`` command for kunit_tool. This
-accepts a filename for an argument, or will read from standard input.
-
-.. code-block:: bash
-
-	# Reading from a file
-	./tools/testing/kunit/kunit.py parse /var/log/dmesg
-	# Reading from stdin
-	dmesg | ./tools/testing/kunit/kunit.py parse
-
-This is very useful if you wish to run tests in a configuration not supported
-by kunit_tool (such as on real hardware, or an unsupported architecture).
-
-Filtering Tests
-===============
-
-It's possible to run only a subset of the tests built into a kernel by passing
-a filter to the ``exec`` or ``run`` commands. For example, if you only wanted
-to run KUnit resource tests, you could use:
-
-.. code-block:: bash
-
-	./tools/testing/kunit/kunit.py run 'kunit-resource*'
-
-This uses the standard glob format for wildcards.
-
-Running Tests on QEMU
-=====================
-
-kunit_tool supports running tests on QEMU as well as via UML (as mentioned
-elsewhere). The default way of running tests on QEMU requires two flags:
-
-``--arch``
-	Selects a collection of configs (Kconfig as well as QEMU configs
-	options, etc) that allow KUnit tests to be run on the specified
-	architecture in a minimal way; this is usually not much slower than
-	using UML. The architecture argument is the same as the name of the
-	option passed to the ``ARCH`` variable used by Kbuild. Not all
-	architectures are currently supported by this flag, but can be handled
-	by the ``--qemu_config`` discussed later. If ``um`` is passed (or this
-	this flag is ignored) the tests will run via UML. Non-UML architectures,
-	e.g. i386, x86_64, arm, um, etc. Non-UML run on QEMU.
-
-``--cross_compile``
-	Specifies the use of a toolchain by Kbuild. The argument passed here is
-	the same passed to the ``CROSS_COMPILE`` variable used by Kbuild. As a
-	reminder this will be the prefix for the toolchain binaries such as gcc
-	for example ``sparc64-linux-gnu-`` if you have the sparc toolchain
-	installed on your system, or
-	``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux-``
-	if you have downloaded the microblaze toolchain from the 0-day website
-	to a directory in your home directory called ``toolchains``.
-
-In many cases it is likely that you may want to run an architecture which is
-not supported by the ``--arch`` flag, or you may want to just run KUnit tests
-on QEMU using a non-default configuration. For this use case, you can write
-your own QemuConfig. These QemuConfigs are written in Python. They must have an
-import line ``from ..qemu_config import QemuArchParams`` at the top of the file
-and the file must contain a variable called ``QEMU_ARCH`` that has an instance
-of ``QemuArchParams`` assigned to it. An example can be seen in
-``tools/testing/kunit/qemu_configs/x86_64.py``.
-
-Once you have a QemuConfig you can pass it into kunit_tool using the
-``--qemu_config`` flag; when used this flag replaces the ``--arch`` flag. If we
-were to do this with the ``x86_64.py`` example from above, the invocation would
-look something like this:
-
-.. code-block:: bash
-
-	./tools/testing/kunit/kunit.py run \
-		--timeout=60 \
-		--jobs=12 \
-		--qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py
-
-Other Useful Options
-====================
-
-kunit_tool has a number of other command-line arguments which can be useful
-when adapting it to fit your environment or needs.
-
-Some of the more useful ones are:
-
-``--help``
-	Lists all of the available options. Note that different commands
-	(``config``, ``build``, ``run``, etc) will have different supported
-	options. Place ``--help`` before the command to list common options,
-	and after the command for options specific to that command.
-
-``--build_dir``
-	Specifies the build directory that kunit_tool will use. This is where
-	the .kunitconfig file is located, as well as where the .config and
-	compiled kernel will be placed. Defaults to ``.kunit``.
-
-``--make_options``
-	Specifies additional options to pass to ``make`` when compiling a
-	kernel (with the ``build`` or ``run`` commands). For example, to enable
-	compiler warnings, you can pass ``--make_options W=1``.
-
-``--alltests``
-        Builds a UML kernel with all config options enabled using ``make
-        allyesconfig``. This allows you to run as many tests as is possible,
-        but is very slow and prone to breakage as new options are added or
-        modified. In most cases, enabling all tests which have satisfied
-        dependencies by adding ``CONFIG_KUNIT_ALL_TESTS=1`` to your
-        .kunitconfig is preferable.
-
-There are several other options (and new ones are often added), so do check
-``--help`` if you're looking for something not mentioned here.
diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst
index a1070def284f..518cf87ea732 100644
--- a/Documentation/dev-tools/kunit/run_wrapper.rst
+++ b/Documentation/dev-tools/kunit/run_wrapper.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-=========================
-Run Tests with kunit_tool
-=========================
+=============================
+Running tests with kunit_tool
+=============================
 
 We can either run KUnit tests using kunit_tool or can run tests
 manually, and then use kunit_tool to parse the results. To run tests
@@ -58,8 +58,8 @@ To view kunit_tool flags (optional command-line arguments), run:
 
 	./tools/testing/kunit/kunit.py run --help
 
-Create a  ``.kunitconfig`` File
-===============================
+Creating a ``.kunitconfig`` file
+================================
 
 If we want to run a specific set of tests (rather than those listed
 in the KUnit ``defconfig``), we can provide Kconfig options in the
@@ -98,8 +98,8 @@ have not included the options dependencies.
    The build dir needs to be set for ``make menuconfig`` to
    work, therefore  by default use ``make O=.kunit menuconfig``.
 
-Configure, Build, and Run Tests
-===============================
+Configuring, building, and running tests
+========================================
 
 If we want to make manual changes to the KUnit build process, we
 can run part of the KUnit build process independently.
@@ -125,11 +125,11 @@ argument:
 
 	./tools/testing/kunit/kunit.py exec
 
-The ``run`` command discussed in section: **Run Tests with kunit_tool**,
+The ``run`` command discussed in section: **Running tests with kunit_tool**,
 is equivalent to running the above three commands in sequence.
 
-Parse Test Results
-==================
+Parsing test results
+====================
 
 KUnit tests output displays results in TAP (Test Anything Protocol)
 format. When running tests, kunit_tool parses this output and prints
@@ -152,8 +152,8 @@ standard input.
 	# Reading from stdin
 	dmesg | ./tools/testing/kunit/kunit.py parse
 
-Run Selected Test Suites
-========================
+Filtering tests
+===============
 
 By passing a bash style glob filter to the ``exec`` or ``run``
 commands, we can run a subset of the tests built into a kernel . For
@@ -167,8 +167,8 @@ This uses the standard glob format with wildcard characters.
 
 .. _kunit-on-qemu:
 
-Run Tests on qemu
-=================
+Running tests on QEMU
+=====================
 
 kunit_tool supports running tests on  qemu as well as
 via UML. To run tests on qemu, by default it requires two flags:
@@ -231,8 +231,8 @@ as
 		--jobs=12 \
 		--qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py
 
-Command-Line Arguments
-======================
+Running command-line arguments
+==============================
 
 kunit_tool has a number of other command-line arguments which can
 be useful for our test environment. Below are the most commonly used
diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
index 867a4bba6bf6..e730df1f468e 100644
--- a/Documentation/dev-tools/kunit/start.rst
+++ b/Documentation/dev-tools/kunit/start.rst
@@ -254,7 +254,5 @@ Next Steps
     examples.
 *   Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
     used for testing.
-*   Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper
-    script.
 *   Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
     answers.
-- 
2.37.2

[PATCH v2 2/8] Documentation: KUnit: avoid repeating "kunit.py run" in start.rst

[Tales Aparecida]

Combine two sections mentioning "kunit.py run" to streamline the
getting-started guide. Update "kunit.py run" expected output in
the guide and run_wrapper.

Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>

---
Notes:
    Update the expected output and the note that follows it (Maíra Canal and
    Sadiya Kazi). The output was updated on the commit: 45ba7a893ad8
    ("kunit: kunit_tool: Separate out config/build/exec/parse")
    Add word "step" to note and fix the case of "kernel".
---
 Documentation/dev-tools/kunit/run_wrapper.rst |  2 +-
 Documentation/dev-tools/kunit/start.rst       | 38 ++++++++-----------
 2 files changed, 16 insertions(+), 24 deletions(-)

diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst
index 518cf87ea732..6b33caf6c8ab 100644
--- a/Documentation/dev-tools/kunit/run_wrapper.rst
+++ b/Documentation/dev-tools/kunit/run_wrapper.rst
@@ -22,7 +22,7 @@ We should see the following:
 
 .. code-block::
 
-	Generating .config...
+	Configuring KUnit Kernel ...
 	Building KUnit kernel...
 	Starting KUnit kernel...
 
diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
index e730df1f468e..2e31350a85e1 100644
--- a/Documentation/dev-tools/kunit/start.rst
+++ b/Documentation/dev-tools/kunit/start.rst
@@ -19,7 +19,21 @@ can run kunit_tool:
 
 	./tools/testing/kunit/kunit.py run
 
-For more information on this wrapper, see:
+If everything worked correctly, you should see the following:
+
+.. code-block::
+
+	Configuring KUnit Kernel ...
+	Building KUnit Kernel ...
+	Starting KUnit Kernel ...
+
+The tests will pass or fail.
+
+.. note ::
+   Because it is building a lot of sources for the first time,
+   the ``Building KUnit Kernel`` step may take a while.
+
+For detailed information on this wrapper, see:
 Documentation/dev-tools/kunit/run_wrapper.rst.
 
 Creating a ``.kunitconfig``
@@ -74,28 +88,6 @@ you if you have not included dependencies for the options used.
    tools like ``make menuconfig O=.kunit``. As long as its a superset of
    ``.kunitconfig``, kunit.py won't overwrite your changes.
 
-Running Tests (KUnit Wrapper)
------------------------------
-1. To make sure that everything is set up correctly, invoke the Python
-   wrapper from your kernel repository:
-
-.. code-block:: bash
-
-	./tools/testing/kunit/kunit.py run
-
-If everything worked correctly, you should see the following:
-
-.. code-block::
-
-	Generating .config ...
-	Building KUnit Kernel ...
-	Starting KUnit Kernel ...
-
-The tests will pass or fail.
-
-.. note ::
-   Because it is building a lot of sources for the first time, the
-   ``Building KUnit kernel`` may take a while.
 
 Running Tests without the KUnit Wrapper
 =======================================
-- 
2.37.2

[PATCH v2 3/8] Documentation: KUnit: add note about mrproper in start.rst

[Tales Aparecida]

The "Getting Started" guide should be beginner-friendly, therefore
add a note about the requirement of a clean source tree when running
kunit_tool for the first time, and its related error.

Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>

---
Notes:
    Edit note following suggestions (Sadiya Kazi)
---
 Documentation/dev-tools/kunit/start.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
index 2e31350a85e1..9beec7d6ac4b 100644
--- a/Documentation/dev-tools/kunit/start.rst
+++ b/Documentation/dev-tools/kunit/start.rst
@@ -19,6 +19,22 @@ can run kunit_tool:
 
 	./tools/testing/kunit/kunit.py run
 
+.. note ::
+	You may see the following error:
+	"The source tree is not clean, please run 'make ARCH=um mrproper'"
+
+	This happens because internally kunit.py specifies ``.kunit``
+	(default option) as the build directory in the command ``make O=output/dir``
+	through the argument ``--build_dir``.  Hence, before starting an
+	out-of-tree build, the source tree must be clean.
+
+	There is also the same caveat mentioned in the "Build directory for
+	the kernel" section of the :doc:`admin-guide </admin-guide/README>`,
+	that is, its use, it must be used for all invocations of ``make``.
+	The good news is that it can indeed be solved by running
+	``make ARCH=um mrproper``, just be aware that this will delete the
+	current configuration and all generated files.
+
 If everything worked correctly, you should see the following:
 
 .. code-block::
-- 
2.37.2

[PATCH v2 4/8] Documentation: KUnit: Reword start guide for selecting tests

[Tales Aparecida]

Reword "Creating a ``.kunitconfig``" into "Selecting which tests to run"
covering the current alternatives for editing configs and glob-filtering

Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
Reviewed-by: Maíra Canal <mairacanal@riseup.net>

---
Notes:
    Avoid hyphen in "test case" and "test suite"
    Fix nit: "any test case that match" -> "...matches"
---
 Documentation/dev-tools/kunit/start.rst | 90 +++++++++++++++++--------
 1 file changed, 63 insertions(+), 27 deletions(-)

diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
index 9beec7d6ac4b..adf782507999 100644
--- a/Documentation/dev-tools/kunit/start.rst
+++ b/Documentation/dev-tools/kunit/start.rst
@@ -52,27 +52,20 @@ The tests will pass or fail.
 For detailed information on this wrapper, see:
 Documentation/dev-tools/kunit/run_wrapper.rst.
 
-Creating a ``.kunitconfig``
----------------------------
-
-By default, kunit_tool runs a selection of tests. However, you can specify which
-unit tests to run by creating a ``.kunitconfig`` file with kernel config options
-that enable only a specific set of tests and their dependencies.
-The ``.kunitconfig`` file contains a list of kconfig options which are required
-to run the desired targets. The ``.kunitconfig`` also contains any other test
-specific config options, such as test dependencies. For example: the
-``FAT_FS`` tests - ``FAT_KUNIT_TEST``, depends on
-``FAT_FS``. ``FAT_FS`` can be enabled by selecting either ``MSDOS_FS``
-or ``VFAT_FS``. To run ``FAT_KUNIT_TEST``, the ``.kunitconfig`` has:
+Selecting which tests to run
+----------------------------
 
-.. code-block:: none
+By default, kunit_tool runs all tests reachable with minimal configuration,
+that is, using default values for most of the kconfig options.  However,
+you can select which tests to run by:
 
-	CONFIG_KUNIT=y
-	CONFIG_MSDOS_FS=y
-	CONFIG_FAT_KUNIT_TEST=y
+- `Customizing Kconfig`_ used to compile the kernel, or
+- `Filtering tests by name`_ to select specifically which compiled tests to run.
 
-1. A good starting point for the ``.kunitconfig`` is the KUnit default config.
-   You can generate it by running:
+Customizing Kconfig
+~~~~~~~~~~~~~~~~~~~
+A good starting point for the ``.kunitconfig`` is the KUnit default config.
+If you didn't run ``kunit.py run`` yet, you can generate it by running:
 
 .. code-block:: bash
 
@@ -84,27 +77,70 @@ or ``VFAT_FS``. To run ``FAT_KUNIT_TEST``, the ``.kunitconfig`` has:
    ``.kunitconfig`` lives in the ``--build_dir`` used by kunit.py, which is
    ``.kunit`` by default.
 
-.. note ::
+Before running the tests, kunit_tool ensures that all config options
+set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn
+you if you have not included dependencies for the options used.
+
+There are many ways to customize the configurations:
+
+a. Edit ``.kunit/.kunitconfig``. The file should contain the list of kconfig
+   options required to run the desired tests, including their dependencies.
    You may want to remove CONFIG_KUNIT_ALL_TESTS from the ``.kunitconfig`` as
    it will enable a number of additional tests that you may not want.
+   If you need to run on an architecture other than UML see :ref:`kunit-on-qemu`.
 
-2. You can then add any other Kconfig options, for example:
+b. Enable additional kconfig options on top of ``.kunit/.kunitconfig``.
+   For example, to include the kernel's linked-list test you can run::
 
-.. code-block:: none
+	./tools/testing/kunit/kunit.py run \
+		--kconfig_add CONFIG_LIST_KUNIT_TEST=y
 
-	CONFIG_LIST_KUNIT_TEST=y
+c. Provide the path of one or more .kunitconfig files from the tree.
+   For example, to run only ``FAT_FS`` and ``EXT4`` tests you can run::
 
-Before running the tests, kunit_tool ensures that all config options
-set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn
-you if you have not included dependencies for the options used.
+	./tools/testing/kunit/kunit.py run \
+		--kunitconfig ./fs/fat/.kunitconfig \
+		--kunitconfig ./fs/ext4/.kunitconfig
 
-.. note ::
-   If you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the
+d. If you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the
    ``.config`` file. But you can edit the ``.config`` file directly or with
    tools like ``make menuconfig O=.kunit``. As long as its a superset of
    ``.kunitconfig``, kunit.py won't overwrite your changes.
 
 
+.. note ::
+
+	To save a .kunitconfig after finding a satisfactory configuration::
+
+		make savedefconfig O=.kunit
+		cp .kunit/defconfig .kunit/.kunitconfig
+
+Filtering tests by name
+~~~~~~~~~~~~~~~~~~~~~~~
+If you want to be more specific than Kconfig can provide, it is also possible
+to select which tests to execute at boot-time by passing a glob filter
+(read instructions regarding the pattern in the manpage :manpage:`glob(7)`).
+If there is a ``"."`` (period) in the filter, it will be interpreted as a
+separator between the name of the test suite and the test case,
+otherwise, it will be interpreted as the name of the test suite.
+For example, let's assume we are using the default config:
+
+a. inform the name of a test suite, like ``"kunit_executor_test"``,
+   to run every test case it contains::
+
+	./tools/testing/kunit/kunit.py run "kunit_executor_test"
+
+b. inform the name of a test case prefixed by its test suite,
+   like ``"example.example_simple_test"``, to run specifically that test case::
+
+	./tools/testing/kunit/kunit.py run "example.example_simple_test"
+
+c. use wildcard characters (``*?[``) to run any test case that matches the pattern,
+   like ``"*.*64*"`` to run test cases containing ``"64"`` in the name inside
+   any test suite::
+
+	./tools/testing/kunit/kunit.py run "*.*64*"
+
 Running Tests without the KUnit Wrapper
 =======================================
 If you do not want to use the KUnit Wrapper (for example: you want code
-- 
2.37.2

[PATCH v2 5/8] Documentation: KUnit: add intro to the getting-started page

[Tales Aparecida]

Describe the objective of the Getting Started page, which should be a
brief and beginner-friendly walkthrough for running and writing tests,
showing the reader where to find detailed instructions in other pages.

Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
Reviewed-by: Maíra Canal <mairacanal@riseup.net>

---
Notes:
    Remove recommendation about having compiled the kernel before using
    kunit_tool. I changed my mind about it after Tim Bird's highlight.
---
 Documentation/dev-tools/kunit/start.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
index adf782507999..75fd05286396 100644
--- a/Documentation/dev-tools/kunit/start.rst
+++ b/Documentation/dev-tools/kunit/start.rst
@@ -4,6 +4,10 @@
 Getting Started
 ===============
 
+This page contains an overview of the kunit_tool and KUnit framework,
+teaching how to run existing tests and then how to write a simple test case,
+and covers common problems users face when using KUnit for the first time.
+
 Installing Dependencies
 =======================
 KUnit has the same dependencies as the Linux kernel. As long as you can
-- 
2.37.2

[PATCH v2 6/8] Documentation: KUnit: update links in the index page

[Tales Aparecida]

Replace out-of-date external links with references to the kernel
documentation, replacing TAP webpage for the more appropriate KTAP
documentation and the UML webpage by its documentation.

Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
---
 Documentation/dev-tools/kunit/index.rst | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst
index d7187282ba28..f5d13f1d37be 100644
--- a/Documentation/dev-tools/kunit/index.rst
+++ b/Documentation/dev-tools/kunit/index.rst
@@ -28,10 +28,10 @@ KUnit (Kernel unit testing framework) provides a common framework for
 unit tests within the Linux kernel. Using KUnit, you can define groups
 of test cases called test suites. The tests either run on kernel boot
 if built-in, or load as a module. KUnit automatically flags and reports
-failed test cases in the kernel log. The test results appear in `TAP
-(Test Anything Protocol) format <https://testanything.org/>`_. It is inspired by
-JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock (C++ unit testing
-framework).
+failed test cases in the kernel log. The test results appear in
+:doc:`KTAP (Kernel - Test Anything Protocol) format</dev-tools/ktap>`.
+It is inspired by JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock
+(C++ unit testing framework).
 
 KUnit tests are part of the kernel, written in the C (programming)
 language, and test parts of the Kernel implementation (example: a C
@@ -45,8 +45,9 @@ internal system functionality. KUnit runs in kernel space and is not
 restricted to things exposed to user-space.
 
 In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``)
-that configures the Linux kernel, runs KUnit tests under QEMU or UML (`User Mode
-Linux <http://user-mode-linux.sourceforge.net/>`_), parses the test results and
+that configures the Linux kernel, runs KUnit tests under QEMU or UML
+(:doc:`User Mode Linux </virt/uml/user_mode_linux_howto_v2>`),
+parses the test results and
 displays them in a user friendly manner.
 
 Features
-- 
2.37.2

[PATCH v2 7/8] lib: overflow: update reference to kunit-tool

[Tales Aparecida]

Replace URL with an updated path to the full Documentation page

Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
Reviewed-by: Kees Cook <keescook@chromium.org>
---
 lib/overflow_kunit.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/overflow_kunit.c b/lib/overflow_kunit.c
index 7e3e43679b73..78075106c0df 100644
--- a/lib/overflow_kunit.c
+++ b/lib/overflow_kunit.c
@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-2.0 OR MIT
 /*
  * Test cases for arithmetic overflow checks. See:
- * https://www.kernel.org/doc/html/latest/dev-tools/kunit/kunit-tool.html#configuring-building-and-running-tests
+ * "Running tests with kunit_tool" at Documentation/dev-tools/kunit/start.rst
  *	./tools/testing/kunit/kunit.py run overflow [--raw_output]
  */
 #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
-- 
2.37.2

[PATCH v2 8/8] lib: stackinit: update reference to kunit-tool

[Tales Aparecida]

Replace URL with an updated path to the full Documentation page

Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
---
 lib/stackinit_kunit.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/stackinit_kunit.c b/lib/stackinit_kunit.c
index 35c69aa425b2..4591d6cf5e01 100644
--- a/lib/stackinit_kunit.c
+++ b/lib/stackinit_kunit.c
@@ -3,7 +3,7 @@
  * Test cases for compiler-based stack variable zeroing via
  * -ftrivial-auto-var-init={zero,pattern} or CONFIG_GCC_PLUGIN_STRUCTLEAK*.
  * For example, see:
- * https://www.kernel.org/doc/html/latest/dev-tools/kunit/kunit-tool.html#configuring-building-and-running-tests
+ * "Running tests with kunit_tool" at Documentation/dev-tools/kunit/start.rst
  *	./tools/testing/kunit/kunit.py run stackinit [--raw_output] \
  *		--make_option LLVM=1 \
  *		--kconfig_add CONFIG_INIT_STACK_ALL_ZERO=y
-- 
2.37.2

Re: [PATCH v2 4/8] Documentation: KUnit: Reword start guide for selecting tests

[Sadiya Kazi]

Hello Tales,
I have a few suggestions listed below. Please see my comments inline.
Apart from that it looks fine to me.

Regards,
Sadiya

On Mon, Aug 22, 2022 at 8:00 AM Tales Aparecida
<tales.aparecida@gmail.com> wrote:
>
> Reword "Creating a ``.kunitconfig``" into "Selecting which tests to run"
> covering the current alternatives for editing configs and glob-filtering
>
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
> Reviewed-by: Maíra Canal <mairacanal@riseup.net>
>
> ---
> Notes:
>     Avoid hyphen in "test case" and "test suite"
>     Fix nit: "any test case that match" -> "...matches"
> ---




>  Documentation/dev-tools/kunit/start.rst | 90 +++++++++++++++++--------
>  1 file changed, 63 insertions(+), 27 deletions(-)
>
> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
> index 9beec7d6ac4b..adf782507999 100644
> --- a/Documentation/dev-tools/kunit/start.rst
> +++ b/Documentation/dev-tools/kunit/start.rst
> @@ -52,27 +52,20 @@ The tests will pass or fail.
>  For detailed information on this wrapper, see:
>  Documentation/dev-tools/kunit/run_wrapper.rst.
>


You can add the new heading and the intro content given below:

Running selected unit tests
----------------------------
The kunit_tool runs a set of default unit tests as listed in the KUnit
``defconfig``. To run a specific set of tests (rather than the default
tests), you can create a ``.kunitconfig``
file with kernel config options that enable only a specific set of
tests and their dependencies.
The .kunitconfig also contains any other test specific config options,
such as test dependencies.
You can select which tests to run by: <Add the new content you added>

Reviewed-by:Sadiya Kazi <Sadiyakazi@google.com>

> -Creating a ``.kunitconfig``
> ----------------------------
> -
> -By default, kunit_tool runs a selection of tests. However, you can specify which
> -unit tests to run by creating a ``.kunitconfig`` file with kernel config options
> -that enable only a specific set of tests and their dependencies.
> -The ``.kunitconfig`` file contains a list of kconfig options which are required
> -to run the desired targets. The ``.kunitconfig`` also contains any other test
> -specific config options, such as test dependencies. For example: the
> -``FAT_FS`` tests - ``FAT_KUNIT_TEST``, depends on
> -``FAT_FS``. ``FAT_FS`` can be enabled by selecting either ``MSDOS_FS``
> -or ``VFAT_FS``. To run ``FAT_KUNIT_TEST``, the ``.kunitconfig`` has:
> +Selecting which tests to run
> +----------------------------
>
> -.. code-block:: none
> +By default, kunit_tool runs all tests reachable with minimal configuration,
> +that is, using default values for most of the kconfig options.  However,
> +you can select which tests to run by:
>
> -       CONFIG_KUNIT=y
> -       CONFIG_MSDOS_FS=y
> -       CONFIG_FAT_KUNIT_TEST=y
> +- `Customizing Kconfig`_ used to compile the kernel, or
> +- `Filtering tests by name`_ to select specifically which compiled tests to run.
>
> -1. A good starting point for the ``.kunitconfig`` is the KUnit default config.
> -   You can generate it by running:
> +Customizing Kconfig
> +~~~~~~~~~~~~~~~~~~~
> +A good starting point for the ``.kunitconfig`` is the KUnit default config.
> +If you didn't run ``kunit.py run`` yet, you can generate it by running:
>
>  .. code-block:: bash
>
> @@ -84,27 +77,70 @@ or ``VFAT_FS``. To run ``FAT_KUNIT_TEST``, the ``.kunitconfig`` has:
>     ``.kunitconfig`` lives in the ``--build_dir`` used by kunit.py, which is
>     ``.kunit`` by default.
>
> -.. note ::
> +Before running the tests, kunit_tool ensures that all config options
> +set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn
> +you if you have not included dependencies for the options used.
> +
> +There are many ways to customize the configurations:
> +
> +a. Edit ``.kunit/.kunitconfig``. The file should contain the list of kconfig
> +   options required to run the desired tests, including their dependencies.
>     You may want to remove CONFIG_KUNIT_ALL_TESTS from the ``.kunitconfig`` as
>     it will enable a number of additional tests that you may not want.
> +   If you need to run on an architecture other than UML see :ref:`kunit-on-qemu`.
>
> -2. You can then add any other Kconfig options, for example:
> +b. Enable additional kconfig options on top of ``.kunit/.kunitconfig``.
> +   For example, to include the kernel's linked-list test you can run::
>
> -.. code-block:: none
> +       ./tools/testing/kunit/kunit.py run \
> +               --kconfig_add CONFIG_LIST_KUNIT_TEST=y
>
> -       CONFIG_LIST_KUNIT_TEST=y
> +c. Provide the path of one or more .kunitconfig files from the tree.
> +   For example, to run only ``FAT_FS`` and ``EXT4`` tests you can run::
>
> -Before running the tests, kunit_tool ensures that all config options
> -set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn
> -you if you have not included dependencies for the options used.
> +       ./tools/testing/kunit/kunit.py run \
> +               --kunitconfig ./fs/fat/.kunitconfig \
> +               --kunitconfig ./fs/ext4/.kunitconfig
>
> -.. note ::
> -   If you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the
> +d. If you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the
>     ``.config`` file. But you can edit the ``.config`` file directly or with
>     tools like ``make menuconfig O=.kunit``. As long as its a superset of
>     ``.kunitconfig``, kunit.py won't overwrite your changes.
>
>
> +.. note ::
> +
> +       To save a .kunitconfig after finding a satisfactory configuration::
> +
> +               make savedefconfig O=.kunit
> +               cp .kunit/defconfig .kunit/.kunitconfig
> +
> +Filtering tests by name
> +~~~~~~~~~~~~~~~~~~~~~~~
> +If you want to be more specific than Kconfig can provide, it is also possible
> +to select which tests to execute at boot-time by passing a glob filter
> +(read instructions regarding the pattern in the manpage :manpage:`glob(7)`).
> +If there is a ``"."`` (period) in the filter, it will be interpreted as a
> +separator between the name of the test suite and the test case,
> +otherwise, it will be interpreted as the name of the test suite.
> +For example, let's assume we are using the default config:
> +
> +a. inform the name of a test suite, like ``"kunit_executor_test"``,
> +   to run every test case it contains::
> +
> +       ./tools/testing/kunit/kunit.py run "kunit_executor_test"
> +
> +b. inform the name of a test case prefixed by its test suite,
> +   like ``"example.example_simple_test"``, to run specifically that test case::
> +
> +       ./tools/testing/kunit/kunit.py run "example.example_simple_test"
> +
> +c. use wildcard characters (``*?[``) to run any test case that matches the pattern,
> +   like ``"*.*64*"`` to run test cases containing ``"64"`` in the name inside
> +   any test suite::
> +
> +       ./tools/testing/kunit/kunit.py run "*.*64*"
> +
>  Running Tests without the KUnit Wrapper
>  =======================================
>  If you do not want to use the KUnit Wrapper (for example: you want code
> --
> 2.37.2
>

Re: [PATCH v2 5/8] Documentation: KUnit: add intro to the getting-started page

[Sadiya Kazi]

On Mon, Aug 22, 2022 at 8:00 AM Tales Aparecida
<tales.aparecida@gmail.com> wrote:
>
> Describe the objective of the Getting Started page, which should be a
> brief and beginner-friendly walkthrough for running and writing tests,
> showing the reader where to find detailed instructions in other pages.
>
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
> Reviewed-by: Maíra Canal <mairacanal@riseup.net>
>
> ---
> Notes:
>     Remove recommendation about having compiled the kernel before using
>     kunit_tool. I changed my mind about it after Tim Bird's highlight.
> ---


Hi Tales,
Thank you for helping with this documentation. You can provide the
below content as an intro to this page:

This page covers information you'll need to know when you're new to
working with KUnit. It includes topics like running tests,
writing a simple test case, and covers common problems users face when
using KUnit for the first time.

Reviewed-by:Sadiya Kazi<Sadiaykazi@google.com>

Regards,
Sadiya




>  Documentation/dev-tools/kunit/start.rst | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
> index adf782507999..75fd05286396 100644
> --- a/Documentation/dev-tools/kunit/start.rst
> +++ b/Documentation/dev-tools/kunit/start.rst
> @@ -4,6 +4,10 @@
>  Getting Started
>  ===============
>
> +This page contains an overview of the kunit_tool and KUnit framework,
> +teaching how to run existing tests and then how to write a simple test case,
> +and covers common problems users face when using KUnit for the first time.
> +
>  Installing Dependencies
>  =======================
>  KUnit has the same dependencies as the Linux kernel. As long as you can
> --
> 2.37.2
>

Re: [PATCH v2 2/8] Documentation: KUnit: avoid repeating "kunit.py run" in start.rst

[Maíra Canal]

On 8/21/22 23:26, Tales Aparecida wrote:
> Combine two sections mentioning "kunit.py run" to streamline the
> getting-started guide. Update "kunit.py run" expected output in
> the guide and run_wrapper.
> 
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>

Thanks for the quick re-spin!

Reviewed-by: Maíra Canal <mairacanal@riseup.net>

Best Regards,
- Maíra Canal

> 
> ---
> Notes:
>      Update the expected output and the note that follows it (Maíra Canal and
>      Sadiya Kazi). The output was updated on the commit: 45ba7a893ad8
>      ("kunit: kunit_tool: Separate out config/build/exec/parse")
>      Add word "step" to note and fix the case of "kernel".
> ---
>   Documentation/dev-tools/kunit/run_wrapper.rst |  2 +-
>   Documentation/dev-tools/kunit/start.rst       | 38 ++++++++-----------
>   2 files changed, 16 insertions(+), 24 deletions(-)
> 
> diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst
> index 518cf87ea732..6b33caf6c8ab 100644
> --- a/Documentation/dev-tools/kunit/run_wrapper.rst
> +++ b/Documentation/dev-tools/kunit/run_wrapper.rst
> @@ -22,7 +22,7 @@ We should see the following:
>   
>   .. code-block::
>   
> -	Generating .config...
> +	Configuring KUnit Kernel ...
>   	Building KUnit kernel...
>   	Starting KUnit kernel...
>   
> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
> index e730df1f468e..2e31350a85e1 100644
> --- a/Documentation/dev-tools/kunit/start.rst
> +++ b/Documentation/dev-tools/kunit/start.rst
> @@ -19,7 +19,21 @@ can run kunit_tool:
>   
>   	./tools/testing/kunit/kunit.py run
>   
> -For more information on this wrapper, see:
> +If everything worked correctly, you should see the following:
> +
> +.. code-block::
> +
> +	Configuring KUnit Kernel ...
> +	Building KUnit Kernel ...
> +	Starting KUnit Kernel ...
> +
> +The tests will pass or fail.
> +
> +.. note ::
> +   Because it is building a lot of sources for the first time,
> +   the ``Building KUnit Kernel`` step may take a while.
> +
> +For detailed information on this wrapper, see:
>   Documentation/dev-tools/kunit/run_wrapper.rst.
>   
>   Creating a ``.kunitconfig``
> @@ -74,28 +88,6 @@ you if you have not included dependencies for the options used.
>      tools like ``make menuconfig O=.kunit``. As long as its a superset of
>      ``.kunitconfig``, kunit.py won't overwrite your changes.
>   
> -Running Tests (KUnit Wrapper)
> ------------------------------
> -1. To make sure that everything is set up correctly, invoke the Python
> -   wrapper from your kernel repository:
> -
> -.. code-block:: bash
> -
> -	./tools/testing/kunit/kunit.py run
> -
> -If everything worked correctly, you should see the following:
> -
> -.. code-block::
> -
> -	Generating .config ...
> -	Building KUnit Kernel ...
> -	Starting KUnit Kernel ...
> -
> -The tests will pass or fail.
> -
> -.. note ::
> -   Because it is building a lot of sources for the first time, the
> -   ``Building KUnit kernel`` may take a while.
>   
>   Running Tests without the KUnit Wrapper
>   =======================================

Re: [PATCH v2 2/8] Documentation: KUnit: avoid repeating "kunit.py run" in start.rst

[Sadiya Kazi]

On Mon, Aug 22, 2022 at 8:00 AM Tales Aparecida
<tales.aparecida@gmail.com> wrote:
>
> Combine two sections mentioning "kunit.py run" to streamline the
> getting-started guide. Update "kunit.py run" expected output in
> the guide and run_wrapper.
>
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
>
> ---
> Notes:
>     Update the expected output and the note that follows it (Maíra Canal and
>     Sadiya Kazi). The output was updated on the commit: 45ba7a893ad8
>     ("kunit: kunit_tool: Separate out config/build/exec/parse")
>     Add word "step" to note and fix the case of "kernel".
> ---

Thanks, Tales. This looks good to me.

Reviewed-by: Sadiya Kazi<sadiyakazi@google.com>

Cheers,
Sadiya

>  Documentation/dev-tools/kunit/run_wrapper.rst |  2 +-
>  Documentation/dev-tools/kunit/start.rst       | 38 ++++++++-----------
>  2 files changed, 16 insertions(+), 24 deletions(-)
>
> diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst
> index 518cf87ea732..6b33caf6c8ab 100644
> --- a/Documentation/dev-tools/kunit/run_wrapper.rst
> +++ b/Documentation/dev-tools/kunit/run_wrapper.rst
> @@ -22,7 +22,7 @@ We should see the following:
>
>  .. code-block::
>
> -       Generating .config...
> +       Configuring KUnit Kernel ...
>         Building KUnit kernel...
>         Starting KUnit kernel...
>
> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
> index e730df1f468e..2e31350a85e1 100644
> --- a/Documentation/dev-tools/kunit/start.rst
> +++ b/Documentation/dev-tools/kunit/start.rst
> @@ -19,7 +19,21 @@ can run kunit_tool:
>
>         ./tools/testing/kunit/kunit.py run
>
> -For more information on this wrapper, see:
> +If everything worked correctly, you should see the following:
> +
> +.. code-block::
> +
> +       Configuring KUnit Kernel ...
> +       Building KUnit Kernel ...
> +       Starting KUnit Kernel ...
> +
> +The tests will pass or fail.
> +
> +.. note ::
> +   Because it is building a lot of sources for the first time,
> +   the ``Building KUnit Kernel`` step may take a while.
> +
> +For detailed information on this wrapper, see:
>  Documentation/dev-tools/kunit/run_wrapper.rst.
>
>  Creating a ``.kunitconfig``
> @@ -74,28 +88,6 @@ you if you have not included dependencies for the options used.
>     tools like ``make menuconfig O=.kunit``. As long as its a superset of
>     ``.kunitconfig``, kunit.py won't overwrite your changes.
>
> -Running Tests (KUnit Wrapper)
> ------------------------------
> -1. To make sure that everything is set up correctly, invoke the Python
> -   wrapper from your kernel repository:
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py run
> -
> -If everything worked correctly, you should see the following:
> -
> -.. code-block::
> -
> -       Generating .config ...
> -       Building KUnit Kernel ...
> -       Starting KUnit Kernel ...
> -
> -The tests will pass or fail.
> -
> -.. note ::
> -   Because it is building a lot of sources for the first time, the
> -   ``Building KUnit kernel`` may take a while.
>
>  Running Tests without the KUnit Wrapper
>  =======================================
> --
> 2.37.2
>

Re: [PATCH v2 1/8] Documentation: KUnit: remove duplicated docs for kunit_tool

[David Gow]

[-- Attachment #1: Type: text/plain, Size: 16741 bytes --]

On Mon, Aug 22, 2022 at 10:30 AM Tales Aparecida
<tales.aparecida@gmail.com> wrote:
>
> Delete "kunit-tool.rst" to remove repeated info from KUnit docs.
> "What is kunit_tool?" was integrated into index.rst, the remaining
> sections were moved into run_wrapper.rst and renamed as follows:
>
> "What is a .kunitconfig?" -> "Creating a ``.kunitconfig`` file"
> "Getting Started with kunit_tool" -> "Running tests with kunit_tool"
> "Configuring, Building, and Running Tests" ->
>         "Configuring, building, and running tests"
> "Running Tests on QEMU" -> "Running tests on QEMU"
> "Parsing Test Results" -> "Parsing test results"
> "Filtering Tests" -> "Filtering tests"
> "Other Useful Options" -> "Running command-line arguments"
>
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
> Reviewed-by: Sadiya Kazi <sadiyakazi@google.com>
>
> ---
> Notes:
>     Update titles on run_wrapper.rst (Sadiya Kazi)
> ---
While I think there are some reasons we might want to keep this page,
ultimately, I agree we should get rid of it.

My concerns were basically that:
1. Having a distinction between a more tutorialised ("here's how to
run tests via kunit_tool") and reference-y ("a list of every option
kunit_tool has") pages makes sense. Then again, these pages were close
to identical in practice, so it's a theoretical objection at best.
2. There may be some links or references to the kunit_tool page (from
outside the kernel documentation) which will break. But, I'm not aware
of any, so they're certainly not common.

Let's move forward with this.

Reviewed-by: David Gow <davidgow@google.com>

Cheers,
-- David



>  Documentation/dev-tools/kunit/index.rst       |   3 -
>  Documentation/dev-tools/kunit/kunit-tool.rst  | 232 ------------------
>  Documentation/dev-tools/kunit/run_wrapper.rst |  32 +--
>  Documentation/dev-tools/kunit/start.rst       |   2 -
>  4 files changed, 16 insertions(+), 253 deletions(-)
>  delete mode 100644 Documentation/dev-tools/kunit/kunit-tool.rst
>
> diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst
> index bc91ad7b8961..d7187282ba28 100644
> --- a/Documentation/dev-tools/kunit/index.rst
> +++ b/Documentation/dev-tools/kunit/index.rst
> @@ -13,7 +13,6 @@ KUnit - Linux Kernel Unit Testing
>         run_wrapper
>         run_manual
>         usage
> -       kunit-tool
>         api/index
>         style
>         faq
> @@ -109,7 +108,5 @@ How do I use it?
>      examples.
>  *   Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
>      used for testing.
> -*   Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper
> -    script.
>  *   Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
>      answers.
> diff --git a/Documentation/dev-tools/kunit/kunit-tool.rst b/Documentation/dev-tools/kunit/kunit-tool.rst
> deleted file mode 100644
> index ae52e0f489f9..000000000000
> --- a/Documentation/dev-tools/kunit/kunit-tool.rst
> +++ /dev/null
> @@ -1,232 +0,0 @@
> -.. SPDX-License-Identifier: GPL-2.0
> -
> -=================
> -kunit_tool How-To
> -=================
> -
> -What is kunit_tool?
> -===================
> -
> -kunit_tool is a script (``tools/testing/kunit/kunit.py``) that aids in building
> -the Linux kernel as UML (`User Mode Linux
> -<http://user-mode-linux.sourceforge.net/>`_), running KUnit tests, parsing
> -the test results and displaying them in a user friendly manner.
> -
> -kunit_tool addresses the problem of being able to run tests without needing a
> -virtual machine or actual hardware with User Mode Linux. User Mode Linux is a
> -Linux architecture, like ARM or x86; however, unlike other architectures it
> -compiles the kernel as a standalone Linux executable that can be run like any
> -other program directly inside of a host operating system. To be clear, it does
> -not require any virtualization support: it is just a regular program.
> -
> -What is a .kunitconfig?
> -=======================
> -
> -It's just a defconfig that kunit_tool looks for in the build directory
> -(``.kunit`` by default).  kunit_tool uses it to generate a .config as you might
> -expect. In addition, it verifies that the generated .config contains the CONFIG
> -options in the .kunitconfig; the reason it does this is so that it is easy to
> -be sure that a CONFIG that enables a test actually ends up in the .config.
> -
> -It's also possible to pass a separate .kunitconfig fragment to kunit_tool,
> -which is useful if you have several different groups of tests you wish
> -to run independently, or if you want to use pre-defined test configs for
> -certain subsystems.
> -
> -Getting Started with kunit_tool
> -===============================
> -
> -If a kunitconfig is present at the root directory, all you have to do is:
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py run
> -
> -However, you most likely want to use it with the following options:
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all`
> -
> -- ``--timeout`` sets a maximum amount of time to allow tests to run.
> -- ``--jobs`` sets the number of threads to use to build the kernel.
> -
> -.. note::
> -       This command will work even without a .kunitconfig file: if no
> -       .kunitconfig is present, a default one will be used instead.
> -
> -If you wish to use a different .kunitconfig file (such as one provided for
> -testing a particular subsystem), you can pass it as an option.
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig
> -
> -For a list of all the flags supported by kunit_tool, you can run:
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py run --help
> -
> -Configuring, Building, and Running Tests
> -========================================
> -
> -It's also possible to run just parts of the KUnit build process independently,
> -which is useful if you want to make manual changes to part of the process.
> -
> -A .config can be generated from a .kunitconfig by using the ``config`` argument
> -when running kunit_tool:
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py config
> -
> -Similarly, if you just want to build a KUnit kernel from the current .config,
> -you can use the ``build`` argument:
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py build
> -
> -And, if you already have a built UML kernel with built-in KUnit tests, you can
> -run the kernel and display the test results with the ``exec`` argument:
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py exec
> -
> -The ``run`` command which is discussed above is equivalent to running all three
> -of these in sequence.
> -
> -All of these commands accept a number of optional command-line arguments. The
> -``--help`` flag will give a complete list of these, or keep reading this page
> -for a guide to some of the more useful ones.
> -
> -Parsing Test Results
> -====================
> -
> -KUnit tests output their results in TAP (Test Anything Protocol) format.
> -kunit_tool will, when running tests, parse this output and print a summary
> -which is much more pleasant to read. If you wish to look at the raw test
> -results in TAP format, you can pass the ``--raw_output`` argument.
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py run --raw_output
> -
> -The raw output from test runs may contain other, non-KUnit kernel log
> -lines. You can see just KUnit output with ``--raw_output=kunit``:
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py run --raw_output=kunit
> -
> -If you have KUnit results in their raw TAP format, you can parse them and print
> -the human-readable summary with the ``parse`` command for kunit_tool. This
> -accepts a filename for an argument, or will read from standard input.
> -
> -.. code-block:: bash
> -
> -       # Reading from a file
> -       ./tools/testing/kunit/kunit.py parse /var/log/dmesg
> -       # Reading from stdin
> -       dmesg | ./tools/testing/kunit/kunit.py parse
> -
> -This is very useful if you wish to run tests in a configuration not supported
> -by kunit_tool (such as on real hardware, or an unsupported architecture).
> -
> -Filtering Tests
> -===============
> -
> -It's possible to run only a subset of the tests built into a kernel by passing
> -a filter to the ``exec`` or ``run`` commands. For example, if you only wanted
> -to run KUnit resource tests, you could use:
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py run 'kunit-resource*'
> -
> -This uses the standard glob format for wildcards.
> -
> -Running Tests on QEMU
> -=====================
> -
> -kunit_tool supports running tests on QEMU as well as via UML (as mentioned
> -elsewhere). The default way of running tests on QEMU requires two flags:
> -
> -``--arch``
> -       Selects a collection of configs (Kconfig as well as QEMU configs
> -       options, etc) that allow KUnit tests to be run on the specified
> -       architecture in a minimal way; this is usually not much slower than
> -       using UML. The architecture argument is the same as the name of the
> -       option passed to the ``ARCH`` variable used by Kbuild. Not all
> -       architectures are currently supported by this flag, but can be handled
> -       by the ``--qemu_config`` discussed later. If ``um`` is passed (or this
> -       this flag is ignored) the tests will run via UML. Non-UML architectures,
> -       e.g. i386, x86_64, arm, um, etc. Non-UML run on QEMU.
> -
> -``--cross_compile``
> -       Specifies the use of a toolchain by Kbuild. The argument passed here is
> -       the same passed to the ``CROSS_COMPILE`` variable used by Kbuild. As a
> -       reminder this will be the prefix for the toolchain binaries such as gcc
> -       for example ``sparc64-linux-gnu-`` if you have the sparc toolchain
> -       installed on your system, or
> -       ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux-``
> -       if you have downloaded the microblaze toolchain from the 0-day website
> -       to a directory in your home directory called ``toolchains``.
> -
> -In many cases it is likely that you may want to run an architecture which is
> -not supported by the ``--arch`` flag, or you may want to just run KUnit tests
> -on QEMU using a non-default configuration. For this use case, you can write
> -your own QemuConfig. These QemuConfigs are written in Python. They must have an
> -import line ``from ..qemu_config import QemuArchParams`` at the top of the file
> -and the file must contain a variable called ``QEMU_ARCH`` that has an instance
> -of ``QemuArchParams`` assigned to it. An example can be seen in
> -``tools/testing/kunit/qemu_configs/x86_64.py``.
> -
> -Once you have a QemuConfig you can pass it into kunit_tool using the
> -``--qemu_config`` flag; when used this flag replaces the ``--arch`` flag. If we
> -were to do this with the ``x86_64.py`` example from above, the invocation would
> -look something like this:
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py run \
> -               --timeout=60 \
> -               --jobs=12 \
> -               --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py
> -
> -Other Useful Options
> -====================
> -
> -kunit_tool has a number of other command-line arguments which can be useful
> -when adapting it to fit your environment or needs.
> -
> -Some of the more useful ones are:
> -
> -``--help``
> -       Lists all of the available options. Note that different commands
> -       (``config``, ``build``, ``run``, etc) will have different supported
> -       options. Place ``--help`` before the command to list common options,
> -       and after the command for options specific to that command.
> -
> -``--build_dir``
> -       Specifies the build directory that kunit_tool will use. This is where
> -       the .kunitconfig file is located, as well as where the .config and
> -       compiled kernel will be placed. Defaults to ``.kunit``.
> -
> -``--make_options``
> -       Specifies additional options to pass to ``make`` when compiling a
> -       kernel (with the ``build`` or ``run`` commands). For example, to enable
> -       compiler warnings, you can pass ``--make_options W=1``.
> -
> -``--alltests``
> -        Builds a UML kernel with all config options enabled using ``make
> -        allyesconfig``. This allows you to run as many tests as is possible,
> -        but is very slow and prone to breakage as new options are added or
> -        modified. In most cases, enabling all tests which have satisfied
> -        dependencies by adding ``CONFIG_KUNIT_ALL_TESTS=1`` to your
> -        .kunitconfig is preferable.
> -
> -There are several other options (and new ones are often added), so do check
> -``--help`` if you're looking for something not mentioned here.
> diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst
> index a1070def284f..518cf87ea732 100644
> --- a/Documentation/dev-tools/kunit/run_wrapper.rst
> +++ b/Documentation/dev-tools/kunit/run_wrapper.rst
> @@ -1,8 +1,8 @@
>  .. SPDX-License-Identifier: GPL-2.0
>
> -=========================
> -Run Tests with kunit_tool
> -=========================
> +=============================
> +Running tests with kunit_tool
> +=============================
>
>  We can either run KUnit tests using kunit_tool or can run tests
>  manually, and then use kunit_tool to parse the results. To run tests
> @@ -58,8 +58,8 @@ To view kunit_tool flags (optional command-line arguments), run:
>
>         ./tools/testing/kunit/kunit.py run --help
>
> -Create a  ``.kunitconfig`` File
> -===============================
> +Creating a ``.kunitconfig`` file
> +================================
>
>  If we want to run a specific set of tests (rather than those listed
>  in the KUnit ``defconfig``), we can provide Kconfig options in the
> @@ -98,8 +98,8 @@ have not included the options dependencies.
>     The build dir needs to be set for ``make menuconfig`` to
>     work, therefore  by default use ``make O=.kunit menuconfig``.
>
> -Configure, Build, and Run Tests
> -===============================
> +Configuring, building, and running tests
> +========================================
>
>  If we want to make manual changes to the KUnit build process, we
>  can run part of the KUnit build process independently.
> @@ -125,11 +125,11 @@ argument:
>
>         ./tools/testing/kunit/kunit.py exec
>
> -The ``run`` command discussed in section: **Run Tests with kunit_tool**,
> +The ``run`` command discussed in section: **Running tests with kunit_tool**,
>  is equivalent to running the above three commands in sequence.
>
> -Parse Test Results
> -==================
> +Parsing test results
> +====================
>
>  KUnit tests output displays results in TAP (Test Anything Protocol)
>  format. When running tests, kunit_tool parses this output and prints
> @@ -152,8 +152,8 @@ standard input.
>         # Reading from stdin
>         dmesg | ./tools/testing/kunit/kunit.py parse
>
> -Run Selected Test Suites
> -========================
> +Filtering tests
> +===============
>
>  By passing a bash style glob filter to the ``exec`` or ``run``
>  commands, we can run a subset of the tests built into a kernel . For
> @@ -167,8 +167,8 @@ This uses the standard glob format with wildcard characters.
>
>  .. _kunit-on-qemu:
>
> -Run Tests on qemu
> -=================
> +Running tests on QEMU
> +=====================
>
>  kunit_tool supports running tests on  qemu as well as
>  via UML. To run tests on qemu, by default it requires two flags:
> @@ -231,8 +231,8 @@ as
>                 --jobs=12 \
>                 --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py
>
> -Command-Line Arguments
> -======================
> +Running command-line arguments
> +==============================
>
>  kunit_tool has a number of other command-line arguments which can
>  be useful for our test environment. Below are the most commonly used
> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
> index 867a4bba6bf6..e730df1f468e 100644
> --- a/Documentation/dev-tools/kunit/start.rst
> +++ b/Documentation/dev-tools/kunit/start.rst
> @@ -254,7 +254,5 @@ Next Steps
>      examples.
>  *   Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
>      used for testing.
> -*   Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper
> -    script.
>  *   Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
>      answers.
> --
> 2.37.2
>

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4003 bytes --]

Re: [PATCH v2 2/8] Documentation: KUnit: avoid repeating "kunit.py run" in start.rst

[David Gow]

[-- Attachment #1: Type: text/plain, Size: 3484 bytes --]

On Mon, Aug 22, 2022 at 10:30 AM Tales Aparecida
<tales.aparecida@gmail.com> wrote:
>
> Combine two sections mentioning "kunit.py run" to streamline the
> getting-started guide. Update "kunit.py run" expected output in
> the guide and run_wrapper.
>
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
>
> ---
> Notes:
>     Update the expected output and the note that follows it (Maíra Canal and
>     Sadiya Kazi). The output was updated on the commit: 45ba7a893ad8
>     ("kunit: kunit_tool: Separate out config/build/exec/parse")
>     Add word "step" to note and fix the case of "kernel".
> ---

Seems okay to me.

FYI: The old "Generating .config" message is still technically correct
for the first time kunit_tool is run. I don't think it matters one way
or the other, though...

Reviewed-by: David Gow <davidgow@google.com>

Cheers,
-- David


>  Documentation/dev-tools/kunit/run_wrapper.rst |  2 +-
>  Documentation/dev-tools/kunit/start.rst       | 38 ++++++++-----------
>  2 files changed, 16 insertions(+), 24 deletions(-)
>
> diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst
> index 518cf87ea732..6b33caf6c8ab 100644
> --- a/Documentation/dev-tools/kunit/run_wrapper.rst
> +++ b/Documentation/dev-tools/kunit/run_wrapper.rst
> @@ -22,7 +22,7 @@ We should see the following:
>
>  .. code-block::
>
> -       Generating .config...
> +       Configuring KUnit Kernel ...
>         Building KUnit kernel...
>         Starting KUnit kernel...
>
> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
> index e730df1f468e..2e31350a85e1 100644
> --- a/Documentation/dev-tools/kunit/start.rst
> +++ b/Documentation/dev-tools/kunit/start.rst
> @@ -19,7 +19,21 @@ can run kunit_tool:
>
>         ./tools/testing/kunit/kunit.py run
>
> -For more information on this wrapper, see:
> +If everything worked correctly, you should see the following:
> +
> +.. code-block::
> +
> +       Configuring KUnit Kernel ...
> +       Building KUnit Kernel ...
> +       Starting KUnit Kernel ...
> +
> +The tests will pass or fail.
> +
> +.. note ::
> +   Because it is building a lot of sources for the first time,
> +   the ``Building KUnit Kernel`` step may take a while.
> +
> +For detailed information on this wrapper, see:
>  Documentation/dev-tools/kunit/run_wrapper.rst.
>
>  Creating a ``.kunitconfig``
> @@ -74,28 +88,6 @@ you if you have not included dependencies for the options used.
>     tools like ``make menuconfig O=.kunit``. As long as its a superset of
>     ``.kunitconfig``, kunit.py won't overwrite your changes.
>
> -Running Tests (KUnit Wrapper)
> ------------------------------
> -1. To make sure that everything is set up correctly, invoke the Python
> -   wrapper from your kernel repository:
> -
> -.. code-block:: bash
> -
> -       ./tools/testing/kunit/kunit.py run
> -
> -If everything worked correctly, you should see the following:
> -
> -.. code-block::
> -
> -       Generating .config ...
> -       Building KUnit Kernel ...
> -       Starting KUnit Kernel ...
> -
> -The tests will pass or fail.
> -
> -.. note ::
> -   Because it is building a lot of sources for the first time, the
> -   ``Building KUnit kernel`` may take a while.
>
>  Running Tests without the KUnit Wrapper
>  =======================================
> --
> 2.37.2
>

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4003 bytes --]

Re: [PATCH v2 3/8] Documentation: KUnit: add note about mrproper in start.rst

[David Gow]

[-- Attachment #1: Type: text/plain, Size: 2430 bytes --]

On Mon, Aug 22, 2022 at 10:30 AM Tales Aparecida
<tales.aparecida@gmail.com> wrote:
>
> The "Getting Started" guide should be beginner-friendly, therefore
> add a note about the requirement of a clean source tree when running
> kunit_tool for the first time, and its related error.
>
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
>
> ---
> Notes:
>     Edit note following suggestions (Sadiya Kazi)
> ---

Thanks very much: this is something we've um-ed and ah-ed about
including a bit. We were worried that it could be confusing to mention
it when it occurs rarely, but I think your description is detailed
enough that no-one will be confused.

One note below about how we could use --build_dir=. to set the build
directory to be equal to the source directory (and hence do an in-tree
build), but I won't lose any sleep if we don't mention it.

Reviewed-by: David Gow <davidgow@google.com>

Cheers,

-- David

>  Documentation/dev-tools/kunit/start.rst | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)
>
> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
> index 2e31350a85e1..9beec7d6ac4b 100644
> --- a/Documentation/dev-tools/kunit/start.rst
> +++ b/Documentation/dev-tools/kunit/start.rst
> @@ -19,6 +19,22 @@ can run kunit_tool:
>
>         ./tools/testing/kunit/kunit.py run
>
> +.. note ::
> +       You may see the following error:
> +       "The source tree is not clean, please run 'make ARCH=um mrproper'"
> +
> +       This happens because internally kunit.py specifies ``.kunit``
> +       (default option) as the build directory in the command ``make O=output/dir``
> +       through the argument ``--build_dir``.  Hence, before starting an
> +       out-of-tree build, the source tree must be clean.
> +
> +       There is also the same caveat mentioned in the "Build directory for
> +       the kernel" section of the :doc:`admin-guide </admin-guide/README>`,
> +       that is, its use, it must be used for all invocations of ``make``.
> +       The good news is that it can indeed be solved by running
> +       ``make ARCH=um mrproper``, just be aware that this will delete the
> +       current configuration and all generated files.
> +

You could also mention that passing --build_dir=. will cause
kunit_tool to do an in-tree build.


>  If everything worked correctly, you should see the following:
>
>  .. code-block::
> --
> 2.37.2
>

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4003 bytes --]

Re: [PATCH v2 4/8] Documentation: KUnit: Reword start guide for selecting tests

[David Gow]

[-- Attachment #1: Type: text/plain, Size: 7657 bytes --]

On Mon, Aug 22, 2022 at 10:30 AM Tales Aparecida
<tales.aparecida@gmail.com> wrote:
>
> Reword "Creating a ``.kunitconfig``" into "Selecting which tests to run"
> covering the current alternatives for editing configs and glob-filtering
>
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
> Reviewed-by: Maíra Canal <mairacanal@riseup.net>
>
> ---
> Notes:
>     Avoid hyphen in "test case" and "test suite"
>     Fix nit: "any test case that match" -> "...matches"
> ---

Thanks very much: I quite like this, more detailed, description.

I'd prefer we tell people explicitly to use ".kunitconfig" files
rather than "using Kconfig": personally I find the latter is a bit
ambiguous as to which files are being changed, and whether or not
you're changing things using .kunitconfig files, or be directly
modifying .config. "Cutomizing Kconfig" suggests the latter to me.
Though it is a little awkward to call it kunitconfig when doing the
--kconfig_add options, too, so if you'd really prefer it as-is, I'll
live with it.

Other than that, though, I'm really happy with this change. I do think
it's starting to push against the edges of the "Getting Started"
guide: I think if we wanted anything more complicated than this, it'd
be best to just link to the run_wrapper.rst page, but this seems good.

Reviewed-by: David Gow <davidgow@google.com>

Cheers,
 -- David

>  Documentation/dev-tools/kunit/start.rst | 90 +++++++++++++++++--------
>  1 file changed, 63 insertions(+), 27 deletions(-)
>
> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
> index 9beec7d6ac4b..adf782507999 100644
> --- a/Documentation/dev-tools/kunit/start.rst
> +++ b/Documentation/dev-tools/kunit/start.rst
> @@ -52,27 +52,20 @@ The tests will pass or fail.
>  For detailed information on this wrapper, see:
>  Documentation/dev-tools/kunit/run_wrapper.rst.
>
> -Creating a ``.kunitconfig``
> ----------------------------
> -
> -By default, kunit_tool runs a selection of tests. However, you can specify which
> -unit tests to run by creating a ``.kunitconfig`` file with kernel config options
> -that enable only a specific set of tests and their dependencies.
> -The ``.kunitconfig`` file contains a list of kconfig options which are required
> -to run the desired targets. The ``.kunitconfig`` also contains any other test
> -specific config options, such as test dependencies. For example: the
> -``FAT_FS`` tests - ``FAT_KUNIT_TEST``, depends on
> -``FAT_FS``. ``FAT_FS`` can be enabled by selecting either ``MSDOS_FS``
> -or ``VFAT_FS``. To run ``FAT_KUNIT_TEST``, the ``.kunitconfig`` has:
> +Selecting which tests to run
> +----------------------------
>
> -.. code-block:: none
> +By default, kunit_tool runs all tests reachable with minimal configuration,
> +that is, using default values for most of the kconfig options.  However,
> +you can select which tests to run by:
>
> -       CONFIG_KUNIT=y
> -       CONFIG_MSDOS_FS=y
> -       CONFIG_FAT_KUNIT_TEST=y
> +- `Customizing Kconfig`_ used to compile the kernel, or
> +- `Filtering tests by name`_ to select specifically which compiled tests to run.
>
> -1. A good starting point for the ``.kunitconfig`` is the KUnit default config.
> -   You can generate it by running:
> +Customizing Kconfig
> +~~~~~~~~~~~~~~~~~~~
> +A good starting point for the ``.kunitconfig`` is the KUnit default config.
> +If you didn't run ``kunit.py run`` yet, you can generate it by running:
>
>  .. code-block:: bash
>
> @@ -84,27 +77,70 @@ or ``VFAT_FS``. To run ``FAT_KUNIT_TEST``, the ``.kunitconfig`` has:
>     ``.kunitconfig`` lives in the ``--build_dir`` used by kunit.py, which is
>     ``.kunit`` by default.
>
> -.. note ::
> +Before running the tests, kunit_tool ensures that all config options
> +set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn
> +you if you have not included dependencies for the options used.
> +
> +There are many ways to customize the configurations:
> +
> +a. Edit ``.kunit/.kunitconfig``. The file should contain the list of kconfig
> +   options required to run the desired tests, including their dependencies.
>     You may want to remove CONFIG_KUNIT_ALL_TESTS from the ``.kunitconfig`` as
>     it will enable a number of additional tests that you may not want.
> +   If you need to run on an architecture other than UML see :ref:`kunit-on-qemu`.
>
> -2. You can then add any other Kconfig options, for example:
> +b. Enable additional kconfig options on top of ``.kunit/.kunitconfig``.
> +   For example, to include the kernel's linked-list test you can run::
>
> -.. code-block:: none
> +       ./tools/testing/kunit/kunit.py run \
> +               --kconfig_add CONFIG_LIST_KUNIT_TEST=y
>
> -       CONFIG_LIST_KUNIT_TEST=y
> +c. Provide the path of one or more .kunitconfig files from the tree.
> +   For example, to run only ``FAT_FS`` and ``EXT4`` tests you can run::
>
> -Before running the tests, kunit_tool ensures that all config options
> -set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn
> -you if you have not included dependencies for the options used.
> +       ./tools/testing/kunit/kunit.py run \
> +               --kunitconfig ./fs/fat/.kunitconfig \
> +               --kunitconfig ./fs/ext4/.kunitconfig
>
> -.. note ::
> -   If you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the
> +d. If you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the
>     ``.config`` file. But you can edit the ``.config`` file directly or with
>     tools like ``make menuconfig O=.kunit``. As long as its a superset of
>     ``.kunitconfig``, kunit.py won't overwrite your changes.
>
>
> +.. note ::
> +
> +       To save a .kunitconfig after finding a satisfactory configuration::
> +
> +               make savedefconfig O=.kunit
> +               cp .kunit/defconfig .kunit/.kunitconfig
> +
> +Filtering tests by name
> +~~~~~~~~~~~~~~~~~~~~~~~
> +If you want to be more specific than Kconfig can provide, it is also possible
> +to select which tests to execute at boot-time by passing a glob filter
> +(read instructions regarding the pattern in the manpage :manpage:`glob(7)`).
> +If there is a ``"."`` (period) in the filter, it will be interpreted as a
> +separator between the name of the test suite and the test case,
> +otherwise, it will be interpreted as the name of the test suite.
> +For example, let's assume we are using the default config:
> +
> +a. inform the name of a test suite, like ``"kunit_executor_test"``,
> +   to run every test case it contains::
> +
> +       ./tools/testing/kunit/kunit.py run "kunit_executor_test"
> +
> +b. inform the name of a test case prefixed by its test suite,
> +   like ``"example.example_simple_test"``, to run specifically that test case::
> +
> +       ./tools/testing/kunit/kunit.py run "example.example_simple_test"
> +
> +c. use wildcard characters (``*?[``) to run any test case that matches the pattern,
> +   like ``"*.*64*"`` to run test cases containing ``"64"`` in the name inside
> +   any test suite::
> +
> +       ./tools/testing/kunit/kunit.py run "*.*64*"
> +

Another interesting distinction is that filtering tests can be done
without using kunit_tool, though that's probably out-of-scope for the
Getting Started documentation.


>  Running Tests without the KUnit Wrapper
>  =======================================
>  If you do not want to use the KUnit Wrapper (for example: you want code
> --
> 2.37.2
>

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4003 bytes --]

Re: [PATCH v2 5/8] Documentation: KUnit: add intro to the getting-started page

[David Gow]

[-- Attachment #1: Type: text/plain, Size: 1478 bytes --]

On Mon, Aug 22, 2022 at 10:30 AM Tales Aparecida
<tales.aparecida@gmail.com> wrote:
>
> Describe the objective of the Getting Started page, which should be a
> brief and beginner-friendly walkthrough for running and writing tests,
> showing the reader where to find detailed instructions in other pages.
>
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
> Reviewed-by: Maíra Canal <mairacanal@riseup.net>
>
> ---
> Notes:
>     Remove recommendation about having compiled the kernel before using
>     kunit_tool. I changed my mind about it after Tim Bird's highlight.
> ---

This is fine.

Reviewed-by: David Gow <davidgow@google.com>

Cheers,
-- David


>  Documentation/dev-tools/kunit/start.rst | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
> index adf782507999..75fd05286396 100644
> --- a/Documentation/dev-tools/kunit/start.rst
> +++ b/Documentation/dev-tools/kunit/start.rst
> @@ -4,6 +4,10 @@
>  Getting Started
>  ===============
>
> +This page contains an overview of the kunit_tool and KUnit framework,
> +teaching how to run existing tests and then how to write a simple test case,
> +and covers common problems users face when using KUnit for the first time.
> +
>  Installing Dependencies
>  =======================
>  KUnit has the same dependencies as the Linux kernel. As long as you can
> --
> 2.37.2
>

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4003 bytes --]

Re: [PATCH v2 6/8] Documentation: KUnit: update links in the index page

[David Gow]

[-- Attachment #1: Type: text/plain, Size: 2571 bytes --]

On Mon, Aug 22, 2022 at 10:30 AM Tales Aparecida
<tales.aparecida@gmail.com> wrote:
>
> Replace out-of-date external links with references to the kernel
> documentation, replacing TAP webpage for the more appropriate KTAP
> documentation and the UML webpage by its documentation.
>
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
> ---

Thanks. These links are definitely better.

(I'm a little sad about losing the link to the TAP page, but it's
linked-to from the KTAP page, so it's fine.)

Reviewed-by: David Gow <davidgow@google.com>

Cheers,
-- David


>  Documentation/dev-tools/kunit/index.rst | 13 +++++++------
>  1 file changed, 7 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst
> index d7187282ba28..f5d13f1d37be 100644
> --- a/Documentation/dev-tools/kunit/index.rst
> +++ b/Documentation/dev-tools/kunit/index.rst
> @@ -28,10 +28,10 @@ KUnit (Kernel unit testing framework) provides a common framework for
>  unit tests within the Linux kernel. Using KUnit, you can define groups
>  of test cases called test suites. The tests either run on kernel boot
>  if built-in, or load as a module. KUnit automatically flags and reports
> -failed test cases in the kernel log. The test results appear in `TAP
> -(Test Anything Protocol) format <https://testanything.org/>`_. It is inspired by
> -JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock (C++ unit testing
> -framework).
> +failed test cases in the kernel log. The test results appear in
> +:doc:`KTAP (Kernel - Test Anything Protocol) format</dev-tools/ktap>`.
> +It is inspired by JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock
> +(C++ unit testing framework).
>
>  KUnit tests are part of the kernel, written in the C (programming)
>  language, and test parts of the Kernel implementation (example: a C
> @@ -45,8 +45,9 @@ internal system functionality. KUnit runs in kernel space and is not
>  restricted to things exposed to user-space.
>
>  In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``)
> -that configures the Linux kernel, runs KUnit tests under QEMU or UML (`User Mode
> -Linux <http://user-mode-linux.sourceforge.net/>`_), parses the test results and
> +that configures the Linux kernel, runs KUnit tests under QEMU or UML
> +(:doc:`User Mode Linux </virt/uml/user_mode_linux_howto_v2>`),
> +parses the test results and
>  displays them in a user friendly manner.
>
>  Features
> --
> 2.37.2
>

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4003 bytes --]

Re: [PATCH v2 7/8] lib: overflow: update reference to kunit-tool

[David Gow]

[-- Attachment #1: Type: text/plain, Size: 1147 bytes --]

On Mon, Aug 22, 2022 at 10:30 AM Tales Aparecida
<tales.aparecida@gmail.com> wrote:
>
> Replace URL with an updated path to the full Documentation page
>
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
> Reviewed-by: Kees Cook <keescook@chromium.org>
> ---

Reviewed-by: David Gow <davidgow@google.com>

If no-one objects, I think we'll take this (along with the rest of the
series) via the kselftest/kunit tree.

Cheers,
-- David


>  lib/overflow_kunit.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/lib/overflow_kunit.c b/lib/overflow_kunit.c
> index 7e3e43679b73..78075106c0df 100644
> --- a/lib/overflow_kunit.c
> +++ b/lib/overflow_kunit.c
> @@ -1,7 +1,7 @@
>  // SPDX-License-Identifier: GPL-2.0 OR MIT
>  /*
>   * Test cases for arithmetic overflow checks. See:
> - * https://www.kernel.org/doc/html/latest/dev-tools/kunit/kunit-tool.html#configuring-building-and-running-tests
> + * "Running tests with kunit_tool" at Documentation/dev-tools/kunit/start.rst
>   *     ./tools/testing/kunit/kunit.py run overflow [--raw_output]
>   */
>  #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
> --
> 2.37.2
>

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4003 bytes --]

Re: [PATCH v2 8/8] lib: stackinit: update reference to kunit-tool

[David Gow]

[-- Attachment #1: Type: text/plain, Size: 1208 bytes --]

On Mon, Aug 22, 2022 at 10:30 AM Tales Aparecida
<tales.aparecida@gmail.com> wrote:
>
> Replace URL with an updated path to the full Documentation page
>
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
> ---

Reviewed-by: David Gow <davidgow@google.com>

If there are no objections we'll take this (along with the whole
series) via the ksefltest/kunit tree.

Cheers,
-- David


>  lib/stackinit_kunit.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/lib/stackinit_kunit.c b/lib/stackinit_kunit.c
> index 35c69aa425b2..4591d6cf5e01 100644
> --- a/lib/stackinit_kunit.c
> +++ b/lib/stackinit_kunit.c
> @@ -3,7 +3,7 @@
>   * Test cases for compiler-based stack variable zeroing via
>   * -ftrivial-auto-var-init={zero,pattern} or CONFIG_GCC_PLUGIN_STRUCTLEAK*.
>   * For example, see:
> - * https://www.kernel.org/doc/html/latest/dev-tools/kunit/kunit-tool.html#configuring-building-and-running-tests
> + * "Running tests with kunit_tool" at Documentation/dev-tools/kunit/start.rst
>   *     ./tools/testing/kunit/kunit.py run stackinit [--raw_output] \
>   *             --make_option LLVM=1 \
>   *             --kconfig_add CONFIG_INIT_STACK_ALL_ZERO=y
> --
> 2.37.2
>

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4003 bytes --]

Re: [PATCH v2 8/8] lib: stackinit: update reference to kunit-tool

[David Gow]

[-- Attachment #1: Type: text/plain, Size: 1208 bytes --]

On Mon, Aug 22, 2022 at 10:30 AM Tales Aparecida
<tales.aparecida@gmail.com> wrote:
>
> Replace URL with an updated path to the full Documentation page
>
> Signed-off-by: Tales Aparecida <tales.aparecida@gmail.com>
> ---

Reviewed-by: David Gow <davidgow@google.com>

If there are no objections we'll take this (along with the whole
series) via the ksefltest/kunit tree.

Cheers,
-- David


>  lib/stackinit_kunit.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/lib/stackinit_kunit.c b/lib/stackinit_kunit.c
> index 35c69aa425b2..4591d6cf5e01 100644
> --- a/lib/stackinit_kunit.c
> +++ b/lib/stackinit_kunit.c
> @@ -3,7 +3,7 @@
>   * Test cases for compiler-based stack variable zeroing via
>   * -ftrivial-auto-var-init={zero,pattern} or CONFIG_GCC_PLUGIN_STRUCTLEAK*.
>   * For example, see:
> - * https://www.kernel.org/doc/html/latest/dev-tools/kunit/kunit-tool.html#configuring-building-and-running-tests
> + * "Running tests with kunit_tool" at Documentation/dev-tools/kunit/start.rst
>   *     ./tools/testing/kunit/kunit.py run stackinit [--raw_output] \
>   *             --make_option LLVM=1 \
>   *             --kconfig_add CONFIG_INIT_STACK_ALL_ZERO=y
> --
> 2.37.2
>

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4003 bytes --]