On Fri, Aug 19, 2022 at 11:02 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?" -> "Create a ``.kunitconfig`` File" "Getting Started with kunit_tool" -> "Run Tests with kunit_tool" "Configuring, Building, and Running Tests" -> "Configure, Build, and Run Tests" "Running Tests on QEMU" -> "Run Tests on QEMU" "Parsing Test Results" -> "Parse Test Results" "Filtering Tests" -> "Run Selected Test Suites" "Other Useful Options" -> "Command-Line Arguments"

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

Hi Tales, Thank you for removing repeated content from the docs. It definitely helps. You could change the headings as follows:

"What is a .kunitconfig?" -> "Create a ``.kunitconfig`` File". Keep it as "Creating a ``.kunitconfig`` file". "Getting Started with kunit_tool" -> "Run Tests with kunit_tool". Keep it as "Running tests with kunit_tool". "Configuring, Building, and Running Tests" -> "Configure, Build, and Run Tests". Keep it as "Configuring, building, and running tests" "Running Tests on QEMU" -> "Run Tests on QEMU". Keep it as "Running tests on QEMU" "Parsing Test Results" -> "Parse Test Results". Keep it as "Parsing test results" "Filtering Tests" -> "Run Selected Test Suites". Keep it as "Filtering tests" "Other Useful Options" -> "Command-Line Arguments". Keep it as "Running command-line arguments". This would help to display the right results when any user is searching with the keyword command-line. Makes the document more discoverable.

Reviewed-by: Sadiya Kazi sadiyakazi@google.com

Regards, Sadiya Kazi

Documentation/dev-tools/kunit/index.rst | 3 - Documentation/dev-tools/kunit/kunit-tool.rst | 232 ------------------ Documentation/dev-tools/kunit/run_wrapper.rst | 4 +- Documentation/dev-tools/kunit/start.rst | 2 - 4 files changed, 2 insertions(+), 239 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..24373db26f9d 100644 --- a/Documentation/dev-tools/kunit/run_wrapper.rst +++ b/Documentation/dev-tools/kunit/run_wrapper.rst @@ -58,7 +58,7 @@ To view kunit_tool flags (optional command-line arguments), run:

    ./tools/testing/kunit/kunit.py run --help

-Create a ``.kunitconfig`` File

+Create a ``.kunitconfig`` File

If we want to run a specific set of tests (rather than those listed @@ -167,7 +167,7 @@ This uses the standard glob format with wildcard characters.

.. _kunit-on-qemu:

-Run Tests on qemu

+Run Tests on QEMU

kunit_tool supports running tests on qemu as well as 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.1

Hi Tales

On 8/19/22 02:32, Tales Aparecida wrote:

Combine two sections mentioning "kunit.py run" to streamline the getting-started guide.

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

Documentation/dev-tools/kunit/start.rst | 38 ++++++++++--------------- 1 file changed, 15 insertions(+), 23 deletions(-)

diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index e730df1f468e..165d7964aa13 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::

• Generating .config ...

When I run ./tools/testing/kunit/kunit.py run, I usually see "Configuring KUnit Kernel ..." instead of "Generating .config ...". Maybe there was a change in the code that didn't reflect on the docs.

• 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.

Minor nit: s/``Building KUnit kernel``/``Building KUnit Kernel``

Best Regards, - Maíra Canal

+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 =======================================

Thanks Tales, Please see my suggestions inline below.

Regards, Sadiya Kazi

On Fri, Aug 19, 2022 at 11:02 AM Tales Aparecida tales.aparecida@gmail.com wrote:

Combine two sections mentioning "kunit.py run" to streamline the getting-started guide.

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

Documentation/dev-tools/kunit/start.rst | 38 ++++++++++--------------- 1 file changed, 15 insertions(+), 23 deletions(-)

diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index e730df1f468e..165d7964aa13 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::

•   Generating .config ...
  

I also see this as "Configuring KUnit Kernel" when I run ./tools/testing/kunit/kunit.py.

•   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.

+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 ...
  

Same comment as above

•   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.

Minor nit: Because it is building a lot of sources for the first time, the ``Building KUnit kernel`` step may take a while.

Running Tests without the KUnit Wrapper

-- 2.37.1

On Fri, Aug 19, 2022 at 11:02 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

Hi Tales, One suggestion on the note below. You could write the note as:

.. 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 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, after 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.

Regards, Sadiya

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 165d7964aa13..e4b73adde6d0 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 might see the error:
  

•   "The source tree is not clean, please run 'make ARCH=um mrproper'"
  

•   That happens because internally kunit.py specifies the build directory in
  

•   the command ``make O=output/dir`` through the argument ``--build_dir``,
  

•   which is ``.kunit`` by default, and before starting out-of-tree build,
  

•   the source tree must be clean.
  

•   There's also the same caveats mentioned in the "Build directory for the kernel"
  

•   section of the :doc:`admin-guide </admin-guide/README>`, that is,
  

•   after it's used 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.1

Hi Tales

On 8/19/22 02:32, Tales Aparecida 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

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 e4b73adde6d0..f0ec64207bd3 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:

Another small nit: you could keep the consistency on naming test-suite and test-cases. Currently, you are using "test-suite" and "test suite" (same for test-cases). I guess any of the two options are fine, but it would be nice to keep it consistent.

+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 match the pattern,

I guess it would be "matches" instead of "match" here.

Other than this small nits, this is a great improvement on the docs!

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

Best Regards, - Maíra Canal

• 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

Hi Tales

On 8/19/22 02:32, Tales Aparecida 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

Documentation/dev-tools/kunit/start.rst | 5 +++++ 1 file changed, 5 insertions(+)

diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index f0ec64207bd3..3855402a5b3e 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -4,6 +4,11 @@ Getting Started =============== +This page contains an overview about the kunit_tool and Kunit framework, +teaching how to run existent tests and then how to write a simple test-case, +and covering common problems users face when using Kunit for the first time. +It is recommended that the reader had compiled the Kernel at least once before.

Some grammar nits: - s/an overview about/an overview of - s/Kunit/KUnit for consistency - s/existent/existing - s/covering/covers

Other than this small nits,

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

Best Regards, - Maíra Canal

Installing Dependencies

KUnit has the same dependencies as the Linux kernel. As long as you can

Hi Daniel,

Em seg., 22 de ago. de 2022 às 17:09, Daniel Latypov dlatypov@google.com escreveu:

On Thu, Aug 18, 2022 at 10:33 PM 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

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#confi...

• • "Running tests with kunit_tool" at Documentation/dev-tools/kunit/start.rst

Oh, I thought I had sent a patch out for this. The rewritten version of the patch is https://www.kernel.org/doc/html/latest/dev-tools/kunit/run_wrapper.html That's what I was intending to rewrite this line to point to.

But if people like a Documentation/ path to start.rst instead, that also works.

Daniel

You are absolutely right! You did send and I wasn't aware, sorry. https://lore.kernel.org/all/20220603195626.121922-1-dlatypov@google.com/ I guess it stalled after that discussion about *where* it should be applied, I got a green flag in IRC and didn't do my due diligence carefully, just tried to find pending patches at linux-kselftest which wasn't CC'd

Now, about the change, either way is fine by me.

Kind regards, Tales

Em seg., 22 de ago. de 2022 às 19:52, Daniel Latypov dlatypov@google.com escreveu:

On Mon, Aug 22, 2022 at 3:35 PM Tales tales.aparecida@gmail.com wrote:

...

Hi Daniel,

Em seg., 22 de ago. de 2022 às 17:09, Daniel Latypov dlatypov@google.com escreveu:

...

On Thu, Aug 18, 2022 at 10:33 PM 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

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#confi...

• • "Running tests with kunit_tool" at Documentation/dev-tools/kunit/start.rst

Oh, I thought I had sent a patch out for this. The rewritten version of the patch is https://www.kernel.org/doc/html/latest/dev-tools/kunit/run_wrapper.html That's what I was intending to rewrite this line to point to.

But if people like a Documentation/ path to start.rst instead, that also works.

Daniel

You are absolutely right! You did send and I wasn't aware, sorry. https://lore.kernel.org/all/20220603195626.121922-1-dlatypov@google.com/ I guess it stalled after that discussion about *where* it should be applied, I got a green flag in IRC and didn't do my due diligence carefully, just tried to find pending patches at linux-kselftest which wasn't CC'd

Oh right, it was that series where I didn't cc linux-kselftest. That was my bad, sorry.

But I had forgotten to include a patch in that series to update this file still, afaict. I could revive that series and add on a version of this patch, if we want?

Daniel

I can bring your patches in my V3, if you don't mind! :D