The information is duplicated now in run_wrapper.rst, which was added in
commit 46201d47d6c4 ("Documentation: kunit: Reorganize documentation
related to running tests").
You cna compare these pages here:
https://www.kernel.org/doc/html/v5.18/dev-tools/kunit/run_wrapper.html
https://www.kernel.org/doc/html/v5.18/dev-tools/kunit/kunit-tool.html
We should have deleted it in then but it got overlooked.
Signed-off-by: Daniel Latypov <[email protected]>
---
Documentation/dev-tools/kunit/index.rst | 3 -
Documentation/dev-tools/kunit/kunit-tool.rst | 232 -------------------
Documentation/dev-tools/kunit/start.rst | 2 -
3 files changed, 237 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 595205348d2d..84a87c57c7e8 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
@@ -107,7 +106,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/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.
base-commit: 50fd82b3a9a9335df5d50c7ddcb81c81d358c4fc
--
2.36.1.255.ge46751e96f-goog
Commit ad659ccb5412 ("kunit: tool: Default --jobs to number of CPUs")
changed the --jobs flag from a hard-coded value of 8 to basically
`nproc`.
Therefore, most users should probably not need to bother to tweak this
flag. Having it near the top of the page is more noise than anything.
Signed-off-by: Daniel Latypov <[email protected]>
---
Documentation/dev-tools/kunit/run_wrapper.rst | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst
index 653985ce9cae..1fccf2e099f7 100644
--- a/Documentation/dev-tools/kunit/run_wrapper.rst
+++ b/Documentation/dev-tools/kunit/run_wrapper.rst
@@ -30,10 +30,9 @@ We may want to use the following options:
.. code-block::
- ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all
+ ./tools/testing/kunit/kunit.py run --timeout=30
- ``--timeout`` sets a maximum amount of time for tests to run.
-- ``--jobs`` sets the number of threads to build the kernel.
kunit_tool will generate a ``.kunitconfig`` with a default
configuration, if no other ``.kunitconfig`` file exists
@@ -237,6 +236,9 @@ command line arguments:
compiling a kernel (using ``build`` or ``run`` commands). For example:
to enable compiler warnings, we can pass ``--make_options W=1``.
+- ``--jobs``: The ``-j`` argument to ``make`` when building the kernel.
+ Defaults to the same value as ``nproc``.
+
- ``--alltests``: Builds a UML kernel with all config options enabled
using ``make allyesconfig``. This allows us to run as many tests as
possible.
--
2.36.1.255.ge46751e96f-goog
Daniel Latypov <[email protected]> writes:
> The information is duplicated now in run_wrapper.rst, which was added in
> commit 46201d47d6c4 ("Documentation: kunit: Reorganize documentation
> related to running tests").
>
> You cna compare these pages here:
> https://www.kernel.org/doc/html/v5.18/dev-tools/kunit/run_wrapper.html
> https://www.kernel.org/doc/html/v5.18/dev-tools/kunit/kunit-tool.html
>
> We should have deleted it in then but it got overlooked.
>
> Signed-off-by: Daniel Latypov <[email protected]>
So not that long ago these patches were going through Shuah...it seems
that's not happening anymore? I can pick up kunit docs patches,
certainly. I've taken the silence on these as assent and applied them.
Thanks,
jon
On Fri, Jun 24, 2022 at 12:47 PM Jonathan Corbet <[email protected]> wrote:
>
> Daniel Latypov <[email protected]> writes:
>
> > The information is duplicated now in run_wrapper.rst, which was added in
> > commit 46201d47d6c4 ("Documentation: kunit: Reorganize documentation
> > related to running tests").
> >
> > You cna compare these pages here:
> > https://www.kernel.org/doc/html/v5.18/dev-tools/kunit/run_wrapper.html
> > https://www.kernel.org/doc/html/v5.18/dev-tools/kunit/kunit-tool.html
> >
> > We should have deleted it in then but it got overlooked.
> >
> > Signed-off-by: Daniel Latypov <[email protected]>
>
> So not that long ago these patches were going through Shuah...it seems
> that's not happening anymore? I can pick up kunit docs patches,
> certainly. I've taken the silence on these as assent and applied them.
Thanks!
Tbh, I'm not really sure what the status is either.
I saw that 46201d47d6c4 (which added the duplication) went through the
docs tree, so I followed suit for this.
I've been guilty of sending purely doc patches through
Shuah/-kselftest tree before, but that was mostly when there were code
change dependencies.
If it makes it simpler, we could try and agree that all kunit doc
patches go through Shuah going forward?
Shuah, Bredan: thoughts/opinions?
Daniel
Shuah Khan <[email protected]> writes:
>> So not that long ago these patches were going through Shuah...it seems
>> that's not happening anymore? I can pick up kunit docs patches,
>> certainly. I've taken the silence on these as assent and applied them.
>>
>
> I am still taking ksefltest and kunit doc patches through my tree. I wait
> for Brendan to ack at times. This one didn't show up in linux-kselftest
> list it appears.
>
> If you cc linux-kselftest and I get an ack from Brendan, I will take this
> through kselftest tree.
As I said up above, I went ahead and applied them. I can drop them
again if you want to carry them, just let me know.
Thanks,
jon
On 6/24/22 1:47 PM, Jonathan Corbet wrote:
> Daniel Latypov <[email protected]> writes:
>
>> The information is duplicated now in run_wrapper.rst, which was added in
>> commit 46201d47d6c4 ("Documentation: kunit: Reorganize documentation
>> related to running tests").
>>
>> You cna compare these pages here:
>> https://www.kernel.org/doc/html/v5.18/dev-tools/kunit/run_wrapper.html
>> https://www.kernel.org/doc/html/v5.18/dev-tools/kunit/kunit-tool.html
>>
>> We should have deleted it in then but it got overlooked.
>>
>> Signed-off-by: Daniel Latypov <[email protected]>
>
> So not that long ago these patches were going through Shuah...it seems
> that's not happening anymore? I can pick up kunit docs patches,
> certainly. I've taken the silence on these as assent and applied them.
>
I am still taking ksefltest and kunit doc patches through my tree. I wait
for Brendan to ack at times. This one didn't show up in linux-kselftest
list it appears.
If you cc linux-kselftest and I get an ack from Brendan, I will take this
through kselftest tree.
thanks,
-- Shuah
On 6/24/22 4:43 PM, Jonathan Corbet wrote:
> Shuah Khan <[email protected]> writes:
>
>>> So not that long ago these patches were going through Shuah...it seems
>>> that's not happening anymore? I can pick up kunit docs patches,
>>> certainly. I've taken the silence on these as assent and applied them.
>>>
>>
>> I am still taking ksefltest and kunit doc patches through my tree. I wait
>> for Brendan to ack at times. This one didn't show up in linux-kselftest
>> list it appears.
>>
>> If you cc linux-kselftest and I get an ack from Brendan, I will take this
>> through kselftest tree.
>
> As I said up above, I went ahead and applied them. I can drop them
> again if you want to carry them, just let me know.
>
Jon, yes please go ahead and drop this one. I will wait for Brendan
to ack it. Reduces confusion in the future. Very often, there is code
dependencies as well.
Daniel, please don't skip kselftest list in the future.
thanks,
-- Shuah
On Fri, Jun 24, 2022 at 3:51 PM Shuah Khan <[email protected]> wrote:
>
> On 6/24/22 4:43 PM, Jonathan Corbet wrote:
> > Shuah Khan <[email protected]> writes:
> >
> >>> So not that long ago these patches were going through Shuah...it seems
> >>> that's not happening anymore? I can pick up kunit docs patches,
> >>> certainly. I've taken the silence on these as assent and applied them.
> >>>
> >>
> >> I am still taking ksefltest and kunit doc patches through my tree. I wait
> >> for Brendan to ack at times. This one didn't show up in linux-kselftest
> >> list it appears.
> >>
> >> If you cc linux-kselftest and I get an ack from Brendan, I will take this
> >> through kselftest tree.
> >
> > As I said up above, I went ahead and applied them. I can drop them
> > again if you want to carry them, just let me know.
> >
>
> Jon, yes please go ahead and drop this one. I will wait for Brendan
> to ack it. Reduces confusion in the future. Very often, there is code
> dependencies as well.
>
> Daniel, please don't skip kselftest list in the future.
Ack.
I was hoping to avoid confusion about who should apply them; looks
like it created more.
Just a note: this one has no code dependencies, so it can be applied
whenever or wherever.
Daniel
Shuah Khan <[email protected]> writes:
> On 6/24/22 4:43 PM, Jonathan Corbet wrote:
>> Shuah Khan <[email protected]> writes:
>>
>>>> So not that long ago these patches were going through Shuah...it seems
>>>> that's not happening anymore? I can pick up kunit docs patches,
>>>> certainly. I've taken the silence on these as assent and applied them.
>>>>
>>>
>>> I am still taking ksefltest and kunit doc patches through my tree. I wait
>>> for Brendan to ack at times. This one didn't show up in linux-kselftest
>>> list it appears.
>>>
>>> If you cc linux-kselftest and I get an ack from Brendan, I will take this
>>> through kselftest tree.
>>
>> As I said up above, I went ahead and applied them. I can drop them
>> again if you want to carry them, just let me know.
>>
>
> Jon, yes please go ahead and drop this one. I will wait for Brendan
> to ack it. Reduces confusion in the future. Very often, there is code
> dependencies as well.
OK, I have dropped those three commits. Note that I also had to drop
Randy's patch which had been waiting since April:
https://lore.kernel.org/linux-doc/20220401024707.10550-1-rdunlap%40infradead.org/
since it conflicts with the above. So you'll want to pick that one up
too.
Thanks,
jon
On 6/27/22 4:28 PM, Jonathan Corbet wrote:
> Shuah Khan <[email protected]> writes:
>
>> On 6/24/22 4:43 PM, Jonathan Corbet wrote:
>>> Shuah Khan <[email protected]> writes:
>>>
>>>>> So not that long ago these patches were going through Shuah...it seems
>>>>> that's not happening anymore? I can pick up kunit docs patches,
>>>>> certainly. I've taken the silence on these as assent and applied them.
>>>>>
>>>>
>>>> I am still taking ksefltest and kunit doc patches through my tree. I wait
>>>> for Brendan to ack at times. This one didn't show up in linux-kselftest
>>>> list it appears.
>>>>
>>>> If you cc linux-kselftest and I get an ack from Brendan, I will take this
>>>> through kselftest tree.
>>>
>>> As I said up above, I went ahead and applied them. I can drop them
>>> again if you want to carry them, just let me know.
>>>
>>
>> Jon, yes please go ahead and drop this one. I will wait for Brendan
>> to ack it. Reduces confusion in the future. Very often, there is code
>> dependencies as well.
>
> OK, I have dropped those three commits. Note that I also had to drop
> Randy's patch which had been waiting since April:
>
> https://lore.kernel.org/linux-doc/20220401024707.10550-1-rdunlap%40infradead.org/
>
> since it conflicts with the above. So you'll want to pick that one up
> too.
>
Thank you. I will pick these 3 up.
thanks,
-- Shuah