Merge tag 'linux-kselftest-5.5-rc2' of...

Kselftest tests the kernel from userspace.  Sometimes things need

testing from within the kernel, one method of doing this is to create a

test module.  We can tie the module into the kselftest framework by

using a shell script test runner.  ``kselftest_module.sh`` is designed

using a shell script test runner.  ``kselftest/module.sh`` is designed

to facilitate this process.  There is also a header file provided to

assist writing kernel modules that are for use with kselftest:

- ``tools/testing/kselftest/kselftest_module.h``

- ``tools/testing/kselftest/kselftest_module.sh``

- ``tools/testing/kselftest/kselftest/module.sh``

How to use

----------

   #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt

   #include "../tools/testing/selftests/kselftest_module.h"

   #include "../tools/testing/selftests/kselftest/module.h"

   KSTM_MODULE_GLOBALS();

    #!/bin/bash

    # SPDX-License-Identifier: GPL-2.0+

    $(dirname $0)/../kselftest_module.sh "foo" test_foo

    $(dirname $0)/../kselftest/module.sh "foo" test_foo

Test Harness

	start

	usage

	kunit-tool

	api/index

	faq

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

What is a kunitconfig?

======================

It's just a defconfig that kunit_tool looks for in the base directory.

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.

How do I use 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.

If you just want to use the defconfig that ships with the kernel, you can

append the ``--defconfig`` flag as well:

.. code-block:: bash

	./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all` --defconfig

.. note::

	This command is particularly helpful for getting started because it

	just works. No kunitconfig needs to be present.

For a list of all the flags supported by kunit_tool, you can run:

.. code-block:: bash

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

.. code-block:: bash

   ./tools/testing/kunit/kunit.py run

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

For more information on this wrapper (also called kunit_tool) checkout the

:doc:`kunit-tool` page.

Creating a kunitconfig

======================

The Python script is a thin wrapper around Kbuild as such, it needs to be

The Python script is a thin wrapper around Kbuild. As such, it needs to be

configured with a ``kunitconfig`` file. This file essentially contains the

regular Kernel config, with the specific test targets as well.

followed by a list of tests that are run. All of them should be passing.

.. note::

   Because it is building a lot of sources for the first time, the ``Building

   kunit kernel`` step may take a while.

	Because it is building a lot of sources for the first time, the

	``Building KUnit kernel`` step may take a while.

Writing your first test

=======================

.. code-block:: bash

	./tools/testing/kunit/kunit.py

	./tools/testing/kunit/kunit.py run

You should see the following failure:

=============================

This document is organized into two main sections: Testing and Isolating

Behavior. The first covers what a unit test is and how to use KUnit to write

Behavior. The first covers what unit tests are and how to use KUnit to write

them. The second covers how to use KUnit to isolate code and make it possible

to unit test code that was otherwise un-unit-testable.

~~~~~~~~~~~

Now obviously one unit test isn't very helpful; the power comes from having

many test cases covering all of your behaviors. Consequently it is common to

have many *similar* tests; in order to reduce duplication in these closely

related tests most unit testing frameworks provide the concept of a *test

suite*, in KUnit we call it a *test suite*; all it is is just a collection of

test cases for a unit of code with a set up function that gets invoked before

every test cases and then a tear down function that gets invoked after every

test case completes.

many test cases covering all of a unit's behaviors. Consequently it is common

to have many *similar* tests; in order to reduce duplication in these closely

related tests most unit testing frameworks - including KUnit - provide the

concept of a *test suite*. A *test suite* is just a collection of test cases

for a unit of code with a set up function that gets invoked before every test

case and then a tear down function that gets invoked after every test case

completes.

Example:

.. note::

   A test case will only be run if it is associated with a test suite.

For a more information on these types of things see the :doc:`api/test`.

For more information on these types of things see the :doc:`api/test`.

Isolating Behavior

==================

		return count;

	}

	ssize_t fake_eeprom_write(struct eeprom *this, size_t offset, const char *buffer, size_t count)

	ssize_t fake_eeprom_write(struct eeprom *parent, size_t offset, const char *buffer, size_t count)

	{

		struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);

By default KUnit uses UML as a way to provide dependencies for code under test.

Under most circumstances KUnit's usage of UML should be treated as an

implementation detail of how KUnit works under the hood. Nevertheless, there

are instances where being able to run architecture specific code, or test

are instances where being able to run architecture specific code or test

against real hardware is desirable. For these reasons KUnit supports running on

other architectures.

.. important::

   Always prefer tests that run on UML to tests that only run under a particular

   architecture, and always prefer tests that run under QEMU or another easy

   (and monitarily free) to obtain software environment to a specific piece of

   (and monetarily free) to obtain software environment to a specific piece of

   hardware.

Nevertheless, there are still valid reasons to write an architecture or hardware