code:
.. SPDX-License-Identifier: GPL-2.0

=================================
KUnit - Linux Kernel Unit Testing
=================================

.. toctree::
	:maxdepth: 2
	:caption: Contents:

	start
	architecture
	run_wrapper
	run_manual
	usage
	api/index
	style
	faq
	running_tips

This section details the kernel unit testing framework.

Introduction
============

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
: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
language function). Excluding build time, from invocation to
completion, KUnit can run around 100 tests in less than 10 seconds.
KUnit can test any kernel component, for example: file system, system
calls, memory management, device drivers and so on.

KUnit follows the white-box testing approach. The test has access to
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
(:doc:`User Mode Linux </virt/uml/user_mode_linux_howto_v2>`),
parses the test results and
displays them in a user friendly manner.

Features
--------

- Provides a framework for writing unit tests.
- Runs tests on any kernel architecture.
- Runs a test in milliseconds.

Prerequisites
-------------

- Any Linux kernel compatible hardware.
- For Kernel under test, Linux kernel version 5.5 or greater.

Unit Testing
============

A unit test tests a single unit of code in isolation. A unit test is the finest
granularity of testing and allows all possible code paths to be tested in the
code under test. This is possible if the code under test is small and does not
have any external dependencies outside of the test's control like hardware.

Write Unit Tests
----------------

To write good unit tests, there is a simple but powerful pattern:
Arrange-Act-Assert. This is a great way to structure test cases and
defines an order of operations.

- Arrange inputs and targets: At the start of the test, arrange the data
  that allows a function to work. Example: initialize a statement or
  object.
- Act on the target behavior: Call your function/code under test.
- Assert expected outcome: Verify that the result (or resulting state) is as
  expected.

Unit Testing Advantages
-----------------------

- Increases testing speed and development in the long run.
- Detects bugs at initial stage and therefore decreases bug fix cost
  compared to acceptance testing.
- Improves code quality.
- Encourages writing testable code.

Read also :ref:`kinds-of-tests`.

How do I use it?
================

You can find a step-by-step guide to writing and running KUnit tests in
Documentation/dev-tools/kunit/start.rst

Alternatively, feel free to look through the rest of the KUnit documentation,
or to experiment with tools/testing/kunit/kunit.py and the example test under
lib/kunit/kunit-example-test.c

Happy testing!


code:
.. SPDX-License-Identifier: GPL-2.0

============================
Run Tests without kunit_tool
============================

If we do not want to use kunit_tool (For example: we want to integrate
with other systems, or run tests on real hardware), we can
include KUnit in any kernel, read out results, and parse manually.

.. note:: KUnit is not designed for use in a production system. It is
          possible that tests may reduce the stability or security of
          the system.

Configure the Kernel
====================

KUnit tests can run without kunit_tool. This can be useful, if:

- We have an existing kernel configuration to test.
- Need to run on real hardware (or using an emulator/VM kunit_tool
  does not support).
- Wish to integrate with some existing testing systems.

KUnit is configured with the ``CONFIG_KUNIT`` option, and individual
tests can also be built by enabling their config options in our
``.config``. KUnit tests usually (but don't always) have config options
ending in ``_KUNIT_TEST``. Most tests can either be built as a module,
or be built into the kernel.

.. note ::

	We can enable the ``KUNIT_ALL_TESTS`` config option to
	automatically enable all tests with satisfied dependencies. This is
	a good way of quickly testing everything applicable to the current
	config.

Once we have built our kernel (and/or modules), it is simple to run
the tests. If the tests are built-in, they will run automatically on the
kernel boot. The results will be written to the kernel log (``dmesg``)
in TAP format.

If the tests are built as modules, they will run when the module is
loaded.

.. code-block :: bash

	# modprobe example-test

The results will appear in TAP format in ``dmesg``.

.. note ::

	If ``CONFIG_KUNIT_DEBUGFS`` is enabled, KUnit test results will
	be accessible from the ``debugfs`` filesystem (if mounted).
	They will be in ``/sys/kernel/debug/kunit/<test_suite>/results``, in
	TAP format.

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GPL-2.0

=============================
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
manually, see: Documentation/dev-tools/kunit/run_manual.rst.
As long as we can build the kernel, we can run KUnit.

kunit_tool is a Python script which configures and builds a kernel, runs
tests, and formats the test results.

Run command:

.. code-block::

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

We should see the following:

.. code-block::

	Configuring KUnit Kernel ...
	Building KUnit kernel...
	Starting KUnit kernel...

We may want to use the following options:

.. code-block::

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

- ``--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
(in the build directory). In addition, it verifies that the
generated ``.config`` file contains the ``CONFIG`` options in the
``.kunitconfig``.
It is also possible to pass a separate ``.kunitconfig`` fragment to
kunit_tool. This is useful if we have several different groups of
tests we want to run independently, or if we want to use pre-defined
test configs for certain subsystems.

To use a different ``.kunitconfig`` file (such as one
provided to test a particular subsystem), pass it as an option:

.. code-block::

	./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig

To view kunit_tool flags (optional command-line arguments), run:

.. code-block::

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

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
``.kunitconfig`` file. For default .kunitconfig, see:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/kunit/configs/default.config.
A ``.kunitconfig`` is a ``minconfig`` (a .config
generated by running ``make savedefconfig``), used for running a
specific set of tests. This file contains the regular Kernel configs
with specific test targets. The ``.kunitconfig`` also
contains any other config options required by the tests (For example:
dependencies for features under tests, configs that enable/disable
certain code blocks, arch configs and so on).

To create a ``.kunitconfig``, using the KUnit ``defconfig``:

.. code-block::

	cd $PATH_TO_LINUX_REPO
	cp tools/testing/kunit/configs/default.config .kunit/.kunitconfig

We can then add any other Kconfig options. For example:

.. code-block::

	CONFIG_LIST_KUNIT_TEST=y

kunit_tool ensures that all config options in ``.kunitconfig`` are
set in the kernel ``.config`` before running the tests. It warns if we
have not included the options dependencies.

.. note:: Removing something from the ``.kunitconfig`` will
   not rebuild the ``.config file``. The configuration is only
   updated if the ``.kunitconfig`` is not a subset of ``.config``.
   This means that we can use other tools
   (For example: ``make menuconfig``) to adjust other config options.
   The build dir needs to be set for ``make menuconfig`` to
   work, therefore  by default use ``make O=.kunit menuconfig``.

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.
When running kunit_tool, from a ``.kunitconfig``, we can generate a
``.config`` by using the ``config`` argument:

.. code-block::

	./tools/testing/kunit/kunit.py config

To build a KUnit kernel from the current ``.config``, we can use the
``build`` argument:

.. code-block::

	./tools/testing/kunit/kunit.py build

If we already have built UML kernel with built-in KUnit tests, we
can run the kernel, and display the test results with the ``exec``
argument:

.. code-block::

	./tools/testing/kunit/kunit.py exec

The ``run`` command discussed in section: **Running tests with kunit_tool**,
is equivalent to running the above three commands in sequence.

Parsing test results
====================

KUnit tests output displays results in TAP (Test Anything Protocol)
format. When running tests, kunit_tool parses this output and prints
a summary. To see the raw test results in TAP format, we can pass the
``--raw_output`` argument:

.. code-block::

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

If we have KUnit results in the raw TAP format, we 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

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
example: if we only want to run KUnit resource tests, use:

.. code-block::

	./tools/testing/kunit/kunit.py run 'kunit-resource*'

This uses the standard glob format with wildcard characters.

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

- ``--arch``: Selects a configs collection (Kconfig, qemu config options
  and so on), that allow KUnit tests to be run on the specified
  architecture in a minimal way. The architecture argument is same as
  the option name passed to the ``ARCH`` variable used by Kbuild.
  Not all architectures currently support this flag, but we can use
  ``--qemu_config`` to handle it. If ``um`` is passed (or this flag
  is ignored), the tests will run via UML. Non-UML architectures,
  for example: i386, x86_64, arm and so on; run on qemu.

- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the
  same argument as 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 we have the sparc toolchain installed on
    our system.

  - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux``
    if we have downloaded the microblaze toolchain from the 0-day
    website to a directory in our home directory called toolchains.

This means that for most architectures, running under qemu is as simple as:

.. code-block:: bash

	./tools/testing/kunit/kunit.py run --arch=x86_64

When cross-compiling, we'll likely need to specify a different toolchain, for
example:

.. code-block:: bash

	./tools/testing/kunit/kunit.py run \
		--arch=s390 \
		--cross_compile=s390x-linux-gnu-

If we want to run KUnit tests on an architecture not supported by
the ``--arch`` flag, or want to run KUnit tests on qemu using a
non-default configuration; then we can write our own``QemuConfig``.
These ``QemuConfigs`` are written in Python. They have an import line
``from..qemu_config import QemuArchParams`` at the top of the file.
The file must contain a variable called ``QEMU_ARCH`` that has an
instance of ``QemuArchParams`` assigned to it. See example in:
``tools/testing/kunit/qemu_configs/x86_64.py``.

Once we have a ``QemuConfig``, we can pass it into kunit_tool,
using the ``--qemu_config`` flag. When used, this flag replaces the
``--arch`` flag. For example: using
``tools/testing/kunit/qemu_configs/x86_64.py``, the invocation appear
as

.. code-block:: bash

	./tools/testing/kunit/kunit.py run \
		--timeout=60 \
		--jobs=12 \
		--qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py

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
command line arguments:

- ``--help``: Lists all available options. To list common options,
  place ``--help`` before the command. To list options specific to that
  command, place ``--help`` after the command.

  .. note:: Different commands (``config``, ``build``, ``run``, etc)
            have different supported options.
- ``--build_dir``: Specifies kunit_tool build directory. It includes
  the ``.kunitconfig``, ``.config`` files and compiled kernel.

- ``--make_options``: Specifies additional options to pass to make, when
  compiling a kernel (using ``build`` or ``run`` commands). For example:
  to enable compiler warnings, we can pass ``--make_options W=1``.

- ``--alltests``: Enable a predefined set of options in order to build
  as many tests as possible.

  .. note:: The list of enabled options can be found in
            ``tools/testing/kunit/configs/all_tests.config``.

            If you only want to enable all tests with otherwise satisfied
            dependencies, instead add ``CONFIG_KUNIT_ALL_TESTS=y`` to your
            ``.kunitconfig``.

- ``--kunitconfig``: Specifies the path or the directory of the ``.kunitconfig``
  file. For example:

  - ``lib/kunit/.kunitconfig`` can be the path of the file.

  - ``lib/kunit`` can be the directory in which the file is located.

  This file is used to build and run with a predefined set of tests
  and their dependencies. For example, to run tests for a given subsystem.

- ``--kconfig_add``: Specifies additional configuration options to be
  appended to the ``.kunitconfig`` file. For example:

  .. code-block::

	./tools/testing/kunit/kunit.py run --kconfig_add CONFIG_KASAN=y

- ``--arch``: Runs tests on the specified architecture. The architecture
  argument is same as the Kbuild ARCH environment variable.
  For example, i386, x86_64, arm, um, etc. Non-UML architectures run on qemu.
  Default is `um`.

- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the
  same argument as passed to the ``CROSS_COMPILE`` variable used by
  Kbuild. This will be the prefix for the toolchain
  binaries such as GCC. For example:

  - ``sparc64-linux-gnu-`` if we have the sparc toolchain installed on
    our system.

  - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux``
    if we have downloaded the microblaze toolchain from the 0-day
    website to a specified path in our home directory called toolchains.

- ``--qemu_config``: Specifies the path to a file containing a
  custom qemu architecture definition. This should be a python file
  containing a `QemuArchParams` object.

- ``--qemu_args``: Specifies additional qemu arguments, for example, ``-smp 8``.

- ``--jobs``: Specifies the number of jobs (commands) to run simultaneously.
  By default, this is set to the number of cores on your system.

- ``--timeout``: Specifies the maximum number of seconds allowed for all tests to run.
  This does not include the time taken to build the tests.

- ``--kernel_args``: Specifies additional kernel command-line arguments. May be repeated.

- ``--run_isolated``: If set, boots the kernel for each individual suite/test.
  This is useful for debugging a non-hermetic test, one that
  might pass/fail based on what ran before it.

- ``--raw_output``: If set, generates unformatted output from kernel. Possible options are:

   - ``all``: To view the full kernel output, use ``--raw_output=all``.

   - ``kunit``: This is the default option and filters to KUnit output. Use ``--raw_output`` or ``--raw_output=kunit``.

- ``--json``: If set, stores the test results in a JSON format and prints to `stdout` or
  saves to a file if a filename is specified.


code:
.. SPDX-License-Identifier: GPL-2.0

============================
Tips For Running KUnit Tests
============================

Using ``kunit.py run`` ("kunit tool")
=====================================

Running from any directory
--------------------------

It can be handy to create a bash function like:

.. code-block:: bash

	function run_kunit() {
	  ( cd "$(git rev-parse --show-toplevel)" && ./tools/testing/kunit/kunit.py run "$@" )
	}

.. note::
	Early versions of ``kunit.py`` (before 5.6) didn't work unless run from
	the kernel root, hence the use of a subshell and ``cd``.

Running a subset of tests
-------------------------

``kunit.py run`` accepts an optional glob argument to filter tests. The format
is ``"<suite_glob>[.test_glob]"``.

Say that we wanted to run the sysctl tests, we could do so via:

.. code-block:: bash

	$ echo -e 'CONFIG_KUNIT=y\nCONFIG_KUNIT_ALL_TESTS=y' > .kunit/.kunitconfig
	$ ./tools/testing/kunit/kunit.py run 'sysctl*'

We can filter down to just the "write" tests via:

.. code-block:: bash

	$ echo -e 'CONFIG_KUNIT=y\nCONFIG_KUNIT_ALL_TESTS=y' > .kunit/.kunitconfig
	$ ./tools/testing/kunit/kunit.py run 'sysctl*.*write*'

We're paying the cost of building more tests than we need this way, but it's
easier than fiddling with ``.kunitconfig`` files or commenting out
``kunit_suite``'s.

However, if we wanted to define a set of tests in a less ad hoc way, the next
tip is useful.

Defining a set of tests
-----------------------

``kunit.py run`` (along with ``build``, and ``config``) supports a
``--kunitconfig`` flag. So if you have a set of tests that you want to run on a
regular basis (especially if they have other dependencies), you can create a
specific ``.kunitconfig`` for them.

E.g. kunit has one for its tests:

.. code-block:: bash

	$ ./tools/testing/kunit/kunit.py run --kunitconfig=lib/kunit/.kunitconfig

Alternatively, if you're following the convention of naming your
file ``.kunitconfig``, you can just pass in the dir, e.g.

.. code-block:: bash

	$ ./tools/testing/kunit/kunit.py run --kunitconfig=lib/kunit

.. note::
	This is a relatively new feature (5.12+) so we don't have any
	conventions yet about on what files should be checked in versus just
	kept around locally. It's up to you and your maintainer to decide if a
	config is useful enough to submit (and therefore have to maintain).

.. note::
	Having ``.kunitconfig`` fragments in a parent and child directory is
	iffy. There's discussion about adding an "import" statement in these
	files to make it possible to have a top-level config run tests from all
	child directories. But that would mean ``.kunitconfig`` files are no
	longer just simple .config fragments.

	One alternative would be to have kunit tool recursively combine configs
	automagically, but tests could theoretically depend on incompatible
	options, so handling that would be tricky.

Setting kernel commandline parameters
-------------------------------------

You can use ``--kernel_args`` to pass arbitrary kernel arguments, e.g.

.. code-block:: bash

	$ ./tools/testing/kunit/kunit.py run --kernel_args=param=42 --kernel_args=param2=false

Generating code coverage reports under UML
------------------------------------------

.. note::
	TODO(brendanhiggins@google.com): There are various issues with UML and
	versions of gcc 7 and up. You're likely to run into missing ``.gcda``
	files or compile errors.

This is different from the "normal" way of getting coverage information that is
documented in Documentation/dev-tools/gcov.rst.

Instead of enabling ``CONFIG_GCOV_KERNEL=y``, we can set these options:

.. code-block:: none

	CONFIG_DEBUG_KERNEL=y
	CONFIG_DEBUG_INFO=y
	CONFIG_DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT=y
	CONFIG_GCOV=y

Putting it together into a copy-pastable sequence of commands:

.. code-block:: bash

	# Append coverage options to the current config
	$ ./tools/testing/kunit/kunit.py run --kunitconfig=.kunit/ --kunitconfig=tools/testing/kunit/configs/coverage_uml.config
	# Extract the coverage information from the build dir (.kunit/)
	$ lcov -t "my_kunit_tests" -o coverage.info -c -d .kunit/

	# From here on, it's the same process as with CONFIG_GCOV_KERNEL=y
	# E.g. can generate an HTML report in a tmp dir like so:
	$ genhtml -o /tmp/coverage_html coverage.info

If your installed version of gcc doesn't work, you can tweak the steps:

.. code-block:: bash

	$ ./tools/testing/kunit/kunit.py run --make_options=CC=/usr/bin/gcc-6
	$ lcov -t "my_kunit_tests" -o coverage.info -c -d .kunit/ --gcov-tool=/usr/bin/gcov-6

Running tests manually
======================

Running tests without using ``kunit.py run`` is also an important use case.
Currently it's your only option if you want to test on architectures other than
UML.

As running the tests under UML is fairly straightforward (configure and compile
the kernel, run the ``./linux`` binary), this section will focus on testing
non-UML architectures.

Running built-in tests
----------------------

When setting tests to ``=y``, the tests will run as part of boot and print
results to dmesg in TAP format. So you just need to add your tests to your
``.config``, build and boot your kernel as normal.

So if we compiled our kernel with:

.. code-block:: none

	CONFIG_KUNIT=y
	CONFIG_KUNIT_EXAMPLE_TEST=y

Then we'd see output like this in dmesg signaling the test ran and passed:

.. code-block:: none

	TAP version 14
	1..1
	    # Subtest: example
	    1..1
	    # example_simple_test: initializing
	    ok 1 - example_simple_test
	ok 1 - example

Running tests as modules
------------------------

Depending on the tests, you can build them as loadable modules.

For example, we'd change the config options from before to

.. code-block:: none

	CONFIG_KUNIT=y
	CONFIG_KUNIT_EXAMPLE_TEST=m

Then after booting into our kernel, we can run the test via

.. code-block:: none

	$ modprobe kunit-example-test

This will then cause it to print TAP output to stdout.

.. note::
	The ``modprobe`` will *not* have a non-zero exit code if any test
	failed (as of 5.13). But ``kunit.py parse`` would, see below.

.. note::
	You can set ``CONFIG_KUNIT=m`` as well, however, some features will not
	work and thus some tests might break. Ideally tests would specify they
	depend on ``KUNIT=y`` in their ``Kconfig``'s, but this is an edge case
	most test authors won't think about.
	As of 5.13, the only difference is that ``current->kunit_test`` will
	not exist.

Pretty-printing results
-----------------------

You can use ``kunit.py parse`` to parse dmesg for test output and print out
results in the same familiar format that ``kunit.py run`` does.

.. code-block:: bash

	$ ./tools/testing/kunit/kunit.py parse /var/log/dmesg

Retrieving per suite results
----------------------------

Regardless of how you're running your tests, you can enable
``CONFIG_KUNIT_DEBUGFS`` to expose per-suite TAP-formatted results:

.. code-block:: none

	CONFIG_KUNIT=y
	CONFIG_KUNIT_EXAMPLE_TEST=m
	CONFIG_KUNIT_DEBUGFS=y

The results for each suite will be exposed under
``/sys/kernel/debug/kunit/<suite>/results``.
So using our example config:

.. code-block:: bash

	$ modprobe kunit-example-test > /dev/null
	$ cat /sys/kernel/debug/kunit/example/results
	... <TAP output> ...

	# After removing the module, the corresponding files will go away
	$ modprobe -r kunit-example-test
	$ cat /sys/kernel/debug/kunit/example/results
	/sys/kernel/debug/kunit/example/results: No such file or directory

Generating code coverage reports
--------------------------------

See Documentation/dev-tools/gcov.rst for details on how to do this.

The only vaguely KUnit-specific advice here is that you probably want to build
your tests as modules. That way you can isolate the coverage from tests from
other code executed during boot, e.g.

.. code-block:: bash

	# Reset coverage counters before running the test.
	$ echo 0 > /sys/kernel/debug/gcov/reset
	$ modprobe kunit-example-test


code:
.. SPDX-License-Identifier: GPL-2.0

===============
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
build the kernel, you can run KUnit.

Running tests with kunit_tool
=============================
kunit_tool is a Python script, which configures and builds a kernel, runs
tests, and formats the test results. From the kernel repository, you
can run kunit_tool:

.. code-block:: bash

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

	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.

Selecting which tests to run
----------------------------

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:

- `Customizing Kconfig`_ used to compile the kernel, or
- `Filtering tests by name`_ to select specifically which compiled tests to run.

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

	cd $PATH_TO_LINUX_REPO
	tools/testing/kunit/kunit.py config
	cat .kunit/.kunitconfig

.. note ::
   ``.kunitconfig`` lives in the ``--build_dir`` used by kunit.py, which is
   ``.kunit`` by default.

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

b. Enable additional kconfig options on top of ``.kunit/.kunitconfig``.
   For example, to include the kernel's linked-list test you can run::

	./tools/testing/kunit/kunit.py run \
		--kconfig_add 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::

	./tools/testing/kunit/kunit.py run \
		--kunitconfig ./fs/fat/.kunitconfig \
		--kunitconfig ./fs/ext4/.kunitconfig

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
under test to integrate with other systems, or use a different/
unsupported architecture or configuration), KUnit can be included in
any kernel, and the results are read out and parsed manually.

.. note ::
   ``CONFIG_KUNIT`` should not be enabled in a production environment.
   Enabling KUnit disables Kernel Address-Space Layout Randomization
   (KASLR), and tests may affect the state of the kernel in ways not
   suitable for production.

Configuring the Kernel
----------------------
To enable KUnit itself, you need to enable the ``CONFIG_KUNIT`` Kconfig
option (under Kernel Hacking/Kernel Testing and Coverage in
``menuconfig``). From there, you can enable any KUnit tests. They
usually have config options ending in ``_KUNIT_TEST``.

KUnit and KUnit tests can be compiled as modules. The tests in a module
will run when the module is loaded.

Running Tests (without KUnit Wrapper)
-------------------------------------
Build and run your kernel. In the kernel log, the test output is printed
out in the TAP format. This will only happen by default if KUnit/tests
are built-in. Otherwise the module will need to be loaded.

.. note ::
   Some lines and/or data may get interspersed in the TAP output.

Writing Your First Test
=======================
In your kernel repository, let's add some code that we can test.

1. Create a file ``drivers/misc/example.h``, which includes:

.. code-block:: c

	int misc_example_add(int left, int right);

2. Create a file ``drivers/misc/example.c``, which includes:

.. code-block:: c

	#include <linux/errno.h>

	#include "example.h"

	int misc_example_add(int left, int right)
	{
		return left + right;
	}

3. Add the following lines to ``drivers/misc/Kconfig``:

.. code-block:: kconfig

	config MISC_EXAMPLE
		bool "My example"

4. Add the following lines to ``drivers/misc/Makefile``:

.. code-block:: make

	obj-$(CONFIG_MISC_EXAMPLE) += example.o

Now we are ready to write the test cases.

1. Add the below test case in ``drivers/misc/example_test.c``:

.. code-block:: c

	#include <kunit/test.h>
	#include "example.h"

	/* Define the test cases. */

	static void misc_example_add_test_basic(struct kunit *test)
	{
		KUNIT_EXPECT_EQ(test, 1, misc_example_add(1, 0));
		KUNIT_EXPECT_EQ(test, 2, misc_example_add(1, 1));
		KUNIT_EXPECT_EQ(test, 0, misc_example_add(-1, 1));
		KUNIT_EXPECT_EQ(test, INT_MAX, misc_example_add(0, INT_MAX));
		KUNIT_EXPECT_EQ(test, -1, misc_example_add(INT_MAX, INT_MIN));
	}

	static void misc_example_test_failure(struct kunit *test)
	{
		KUNIT_FAIL(test, "This test never passes.");
	}

	static struct kunit_case misc_example_test_cases[] = {
		KUNIT_CASE(misc_example_add_test_basic),
		KUNIT_CASE(misc_example_test_failure),
		{}
	};

	static struct kunit_suite misc_example_test_suite = {
		.name = "misc-example",
		.test_cases = misc_example_test_cases,
	};
	kunit_test_suite(misc_example_test_suite);

2. Add the following lines to ``drivers/misc/Kconfig``:

.. code-block:: kconfig

	config MISC_EXAMPLE_TEST
		tristate "Test for my example" if !KUNIT_ALL_TESTS
		depends on MISC_EXAMPLE && KUNIT=y
		default KUNIT_ALL_TESTS

3. Add the following lines to ``drivers/misc/Makefile``:

.. code-block:: make

	obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o

4. Add the following lines to ``.kunit/.kunitconfig``:

.. code-block:: none

	CONFIG_MISC_EXAMPLE=y
	CONFIG_MISC_EXAMPLE_TEST=y

5. Run the test:

.. code-block:: bash

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

You should see the following failure:

.. code-block:: none

	...
	[16:08:57] [PASSED] misc-example:misc_example_add_test_basic
	[16:08:57] [FAILED] misc-example:misc_example_test_failure
	[16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17
	[16:08:57]      This test never passes.
	...

Congrats! You just wrote your first KUnit test.

Next Steps
==========

If you're interested in using some of the more advanced features of kunit.py,
take a look at Documentation/dev-tools/kunit/run_wrapper.rst

If you'd like to run tests without using kunit.py, check out
Documentation/dev-tools/kunit/run_manual.rst

For more information on writing KUnit tests (including some common techniques
for testing different things), see Documentation/dev-tools/kunit/usage.rst


code:
.. SPDX-License-Identifier: GPL-2.0

===========================
Test Style and Nomenclature
===========================

To make finding, writing, and using KUnit tests as simple as possible, it is
strongly encouraged that they are named and written according to the guidelines
below. While it is possible to write KUnit tests which do not follow these rules,
they may break some tooling, may conflict with other tests, and may not be run
automatically by testing systems.

It is recommended that you only deviate from these guidelines when:

1. Porting tests to KUnit which are already known with an existing name.
2. Writing tests which would cause serious problems if automatically run. For
   example, non-deterministically producing false positives or negatives, or
   taking a long time to run.

Subsystems, Suites, and Tests
=============================

To make tests easy to find, they are grouped into suites and subsystems. A test
suite is a group of tests which test a related area of the kernel. A subsystem
is a set of test suites which test different parts of a kernel subsystem
or a driver.

Subsystems
----------

Every test suite must belong to a subsystem. A subsystem is a collection of one
or more KUnit test suites which test the same driver or part of the kernel. A
test subsystem should match a single kernel module. If the code being tested
cannot be compiled as a module, in many cases the subsystem should correspond to
a directory in the source tree or an entry in the ``MAINTAINERS`` file. If
unsure, follow the conventions set by tests in similar areas.

Test subsystems should be named after the code being tested, either after the
module (wherever possible), or after the directory or files being tested. Test
subsystems should be named to avoid ambiguity where necessary.

If a test subsystem name has multiple components, they should be separated by
underscores. *Do not* include "test" or "kunit" directly in the subsystem name
unless we are actually testing other tests or the kunit framework itself. For
example, subsystems could be called:

``ext4``
  Matches the module and filesystem name.
``apparmor``
  Matches the module name and LSM name.
``kasan``
  Common name for the tool, prominent part of the path ``mm/kasan``
``snd_hda_codec_hdmi``
  Has several components (``snd``, ``hda``, ``codec``, ``hdmi``) separated by
  underscores. Matches the module name.

Avoid names as shown in examples below:

``linear-ranges``
  Names should use underscores, not dashes, to separate words. Prefer
  ``linear_ranges``.
``qos-kunit-test``
  This name should use underscores, and not have "kunit-test" as a
  suffix. ``qos`` is also ambiguous as a subsystem name, because several parts
  of the kernel have a ``qos`` subsystem. ``power_qos`` would be a better name.
``pc_parallel_port``
  The corresponding module name is ``parport_pc``, so this subsystem should also
  be named ``parport_pc``.

.. note::
        The KUnit API and tools do not explicitly know about subsystems. They are
        a way of categorizing test suites and naming modules which provides a
        simple, consistent way for humans to find and run tests. This may change
        in the future.

Suites
------

KUnit tests are grouped into test suites, which cover a specific area of
functionality being tested. Test suites can have shared initialization and
shutdown code which is run for all tests in the suite. Not all subsystems need
to be split into multiple test suites (for example, simple drivers).

Test suites are named after the subsystem they are part of. If a subsystem
contains several suites, the specific area under test should be appended to the
subsystem name, separated by an underscore.

In the event that there are multiple types of test using KUnit within a
subsystem (for example, both unit tests and integration tests), they should be
put into separate suites, with the type of test as the last element in the suite
name. Unless these tests are actually present, avoid using ``_test``, ``_unittest``
or similar in the suite name.

The full test suite name (including the subsystem name) should be specified as
the ``.name`` member of the ``kunit_suite`` struct, and forms the base for the
module name. For example, test suites could include:

``ext4_inode``
  Part of the ``ext4`` subsystem, testing the ``inode`` area.
``kunit_try_catch``
  Part of the ``kunit`` implementation itself, testing the ``try_catch`` area.
``apparmor_property_entry``
  Part of the ``apparmor`` subsystem, testing the ``property_entry`` area.
``kasan``
  The ``kasan`` subsystem has only one suite, so the suite name is the same as
  the subsystem name.

Avoid names, for example:

``ext4_ext4_inode``
  There is no reason to state the subsystem twice.
``property_entry``
  The suite name is ambiguous without the subsystem name.
``kasan_integration_test``
  Because there is only one suite in the ``kasan`` subsystem, the suite should
  just be called as ``kasan``. Do not redundantly add
  ``integration_test``. It should be a separate test suite. For example, if the
  unit tests are added, then that suite could be named as ``kasan_unittest`` or
  similar.

Test Cases
----------

Individual tests consist of a single function which tests a constrained
codepath, property, or function. In the test output, an individual test's
results will show up as subtests of the suite's results.

Tests should be named after what they are testing. This is often the name of the
function being tested, with a description of the input or codepath being tested.
As tests are C functions, they should be named and written in accordance with
the kernel coding style.

.. note::
        As tests are themselves functions, their names cannot conflict with
        other C identifiers in the kernel. This may require some creative
        naming. It is a good idea to make your test functions `static` to avoid
        polluting the global namespace.

Example test names include:

``unpack_u32_with_null_name``
  Tests the ``unpack_u32`` function when a NULL name is passed in.
``test_list_splice``
  Tests the ``list_splice`` macro. It has the prefix ``test_`` to avoid a
  name conflict with the macro itself.

Should it be necessary to refer to a test outside the context of its test suite,
the *fully-qualified* name of a test should be the suite name followed by the
test name, separated by a colon (i.e. ``suite:test``).

Test Kconfig Entries
====================

Every test suite should be tied to a Kconfig entry.

This Kconfig entry must:

* be named ``CONFIG_<name>_KUNIT_TEST``: where <name> is the name of the test
  suite.
* be listed either alongside the config entries for the driver/subsystem being
  tested, or be under [Kernel Hacking]->[Kernel Testing and Coverage]
* depend on ``CONFIG_KUNIT``.
* be visible only if ``CONFIG_KUNIT_ALL_TESTS`` is not enabled.
* have a default value of ``CONFIG_KUNIT_ALL_TESTS``.
* have a brief description of KUnit in the help text.

If we are not able to meet above conditions (for example, the test is unable to
be built as a module), Kconfig entries for tests should be tristate.

For example, a Kconfig entry might look like:

.. code-block:: none

	config FOO_KUNIT_TEST
		tristate "KUnit test for foo" if !KUNIT_ALL_TESTS
		depends on KUNIT
		default KUNIT_ALL_TESTS
		help
		  This builds unit tests for foo.

		  For more information on KUnit and unit tests in general,
		  please refer to the KUnit documentation in Documentation/dev-tools/kunit/.

		  If unsure, say N.

Test File and Module Names
==========================

KUnit tests can often be compiled as a module. These modules should be named
after the test suite, followed by ``_test``. If this is likely to conflict with
non-KUnit tests, the suffix ``_kunit`` can also be used.

The easiest way of achieving this is to name the file containing the test suite
``<suite>_test.c`` (or, as above, ``<suite>_kunit.c``). This file should be
placed next to the code under test.

If the suite name contains some or all of the name of the test's parent
directory, it may make sense to modify the source filename to reduce redundancy.
For example, a ``foo_firmware`` suite could be in the ``foo/firmware_test.c``
file.


code:
.. SPDX-License-Identifier: GPL-2.0

Writing Tests
=============

Test Cases
----------

The fundamental unit in KUnit is the test case. A test case is a function with
the signature ``void (*)(struct kunit *test)``. It calls the function under test
and then sets *expectations* for what should happen. For example:

.. code-block:: c

	void example_test_success(struct kunit *test)
	{
	}

	void example_test_failure(struct kunit *test)
	{
		KUNIT_FAIL(test, "This test never passes.");
	}

In the above example, ``example_test_success`` always passes because it does
nothing; no expectations are set, and therefore all expectations pass. On the
other hand ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``,
which is a special expectation that logs a message and causes the test case to
fail.

Expectations
~~~~~~~~~~~~
An *expectation* specifies that we expect a piece of code to do something in a
test. An expectation is called like a function. A test is made by setting
expectations about the behavior of a piece of code under test. When one or more
expectations fail, the test case fails and information about the failure is
logged. For example:

.. code-block:: c

	void add_test_basic(struct kunit *test)
	{
		KUNIT_EXPECT_EQ(test, 1, add(1, 0));
		KUNIT_EXPECT_EQ(test, 2, add(1, 1));
	}

In the above example, ``add_test_basic`` makes a number of assertions about the
behavior of a function called ``add``. The first parameter is always of type
``struct kunit *``, which contains information about the current test context.
The second parameter, in this case, is what the value is expected to be. The
last value is what the value actually is. If ``add`` passes all of these
expectations, the test case, ``add_test_basic`` will pass; if any one of these
expectations fails, the test case will fail.

A test case *fails* when any expectation is violated; however, the test will
continue to run, and try other expectations until the test case ends or is
otherwise terminated. This is as opposed to *assertions* which are discussed
later.

To learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst.

.. note::
   A single test case should be short, easy to understand, and focused on a
   single behavior.

For example, if we want to rigorously test the ``add`` function above, create
additional tests cases which would test each property that an ``add`` function
should have as shown below:

.. code-block:: c

	void add_test_basic(struct kunit *test)
	{
		KUNIT_EXPECT_EQ(test, 1, add(1, 0));
		KUNIT_EXPECT_EQ(test, 2, add(1, 1));
	}

	void add_test_negative(struct kunit *test)
	{
		KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
	}

	void add_test_max(struct kunit *test)
	{
		KUNIT_EXPECT_EQ(test, INT_MAX, add(0, INT_MAX));
		KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
	}

	void add_test_overflow(struct kunit *test)
	{
		KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1));
	}

Assertions
~~~~~~~~~~

An assertion is like an expectation, except that the assertion immediately
terminates the test case if the condition is not satisfied. For example:

.. code-block:: c

	static void test_sort(struct kunit *test)
	{
		int *a, i, r = 1;
		a = kunit_kmalloc_array(test, TEST_LEN, sizeof(*a), GFP_KERNEL);
		KUNIT_ASSERT_NOT_ERR_OR_NULL(test, a);
		for (i = 0; i < TEST_LEN; i++) {
			r = (r * 725861) % 6599;
			a[i] = r;
		}
		sort(a, TEST_LEN, sizeof(*a), cmpint, NULL);
		for (i = 0; i < TEST_LEN-1; i++)
			KUNIT_EXPECT_LE(test, a[i], a[i + 1]);
	}

In this example, we need to be able to allocate an array to test the ``sort()``
function. So we use ``KUNIT_ASSERT_NOT_ERR_OR_NULL()`` to abort the test if
there's an allocation error.

.. note::
   In other test frameworks, ``ASSERT`` macros are often implemented by calling
   ``return`` so they only work from the test function. In KUnit, we stop the
   current kthread on failure, so you can call them from anywhere.

Customizing error messages
--------------------------

Each of the ``KUNIT_EXPECT`` and ``KUNIT_ASSERT`` macros have a ``_MSG``
variant.  These take a format string and arguments to provide additional
context to the automatically generated error messages.

.. code-block:: c

	char some_str[41];
	generate_sha1_hex_string(some_str);

	/* Before. Not easy to tell why the test failed. */
	KUNIT_EXPECT_EQ(test, strlen(some_str), 40);

	/* After. Now we see the offending string. */
	KUNIT_EXPECT_EQ_MSG(test, strlen(some_str), 40, "some_str='%s'", some_str);

Alternatively, one can take full control over the error message by using
``KUNIT_FAIL()``, e.g.

.. code-block:: c

	/* Before */
	KUNIT_EXPECT_EQ(test, some_setup_function(), 0);

	/* After: full control over the failure message. */
	if (some_setup_function())
		KUNIT_FAIL(test, "Failed to setup thing for testing");

Test Suites
~~~~~~~~~~~

We need many test cases covering all the unit's behaviors. 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 a collection of test cases for a unit of code
with optional setup and teardown functions that run before/after the whole
suite and/or every test case. For example:

.. code-block:: c

	static struct kunit_case example_test_cases[] = {
		KUNIT_CASE(example_test_foo),
		KUNIT_CASE(example_test_bar),
		KUNIT_CASE(example_test_baz),
		{}
	};

	static struct kunit_suite example_test_suite = {
		.name = "example",
		.init = example_test_init,
		.exit = example_test_exit,
		.suite_init = example_suite_init,
		.suite_exit = example_suite_exit,
		.test_cases = example_test_cases,
	};
	kunit_test_suite(example_test_suite);

In the above example, the test suite ``example_test_suite`` would first run
``example_suite_init``, then run the test cases ``example_test_foo``,
``example_test_bar``, and ``example_test_baz``. Each would have
``example_test_init`` called immediately before it and ``example_test_exit``
called immediately after it. Finally, ``example_suite_exit`` would be called
after everything else. ``kunit_test_suite(example_test_suite)`` registers the
test suite with the KUnit test framework.

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

``kunit_test_suite(...)`` is a macro which tells the linker to put the
specified test suite in a special linker section so that it can be run by KUnit
either after ``late_init``, or when the test module is loaded (if the test was
built as a module).

For more information, see Documentation/dev-tools/kunit/api/test.rst.

.. _kunit-on-non-uml:

Writing Tests For Other Architectures
-------------------------------------

It is better to write tests that run on UML to tests that only run under a
particular architecture. It is better to write tests that run under QEMU or
another easy to obtain (and monetarily free) software environment to a specific
piece of hardware.

Nevertheless, there are still valid reasons to write a test that is architecture
or hardware specific. For example, we might want to test code that really
belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does
not depend on physical hardware. Some of our test cases may not need hardware,
only few tests actually require the hardware to test it. When hardware is not
available, instead of disabling tests, we can skip them.

Now that we have narrowed down exactly what bits are hardware specific, the
actual procedure for writing and running the tests is same as writing normal
KUnit tests.

.. important::
   We may have to reset hardware state. If this is not possible, we may only
   be able to run one test case per invocation.

.. TODO(brendanhiggins@google.com): Add an actual example of an architecture-
   dependent KUnit test.

Common Patterns
===============

Isolating Behavior
------------------

Unit testing limits the amount of code under test to a single unit. It controls
what code gets run when the unit under test calls a function. Where a function
is exposed as part of an API such that the definition of that function can be
changed without affecting the rest of the code base. In the kernel, this comes
from two constructs: classes, which are structs that contain function pointers
provided by the implementer, and architecture-specific functions, which have
definitions selected at compile time.

Classes
~~~~~~~

Classes are not a construct that is built into the C programming language;
however, it is an easily derived concept. Accordingly, in most cases, every
project that does not use a standardized object oriented library (like GNOME's
GObject) has their own slightly different way of doing object oriented
programming; the Linux kernel is no exception.

The central concept in kernel object oriented programming is the class. In the
kernel, a *class* is a struct that contains function pointers. This creates a
contract between *implementers* and *users* since it forces them to use the
same function signature without having to call the function directly. To be a
class, the function pointers must specify that a pointer to the class, known as
a *class handle*, be one of the parameters. Thus the member functions (also
known as *methods*) have access to member variables (also known as *fields*)
allowing the same implementation to have multiple *instances*.

A class can be *overridden* by *child classes* by embedding the *parent class*
in the child class. Then when the child class *method* is called, the child
implementation knows that the pointer passed to it is of a parent contained
within the child. Thus, the child can compute the pointer to itself because the
pointer to the parent is always a fixed offset from the pointer to the child.
This offset is the offset of the parent contained in the child struct. For
example:

.. code-block:: c

	struct shape {
		int (*area)(struct shape *this);
	};

	struct rectangle {
		struct shape parent;
		int length;
		int width;
	};

	int rectangle_area(struct shape *this)
	{
		struct rectangle *self = container_of(this, struct rectangle, parent);

		return self->length * self->width;
	};

	void rectangle_new(struct rectangle *self, int length, int width)
	{
		self->parent.area = rectangle_area;
		self->length = length;
		self->width = width;
	}

In this example, computing the pointer to the child from the pointer to the
parent is done by ``container_of``.

Faking Classes
~~~~~~~~~~~~~~

In order to unit test a piece of code that calls a method in a class, the
behavior of the method must be controllable, otherwise the test ceases to be a
unit test and becomes an integration test.

A fake class implements a piece of code that is different than what runs in a
production instance, but behaves identical from the standpoint of the callers.
This is done to replace a dependency that is hard to deal with, or is slow. For
example, implementing a fake EEPROM that stores the "contents" in an
internal buffer. Assume we have a class that represents an EEPROM:

.. code-block:: c

	struct eeprom {
		ssize_t (*read)(struct eeprom *this, size_t offset, char *buffer, size_t count);
		ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count);
	};

And we want to test code that buffers writes to the EEPROM:

.. code-block:: c

	struct eeprom_buffer {
		ssize_t (*write)(struct eeprom_buffer *this, const char *buffer, size_t count);
		int flush(struct eeprom_buffer *this);
		size_t flush_count; /* Flushes when buffer exceeds flush_count. */
	};

	struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom);
	void destroy_eeprom_buffer(struct eeprom *eeprom);

We can test this code by *faking out* the underlying EEPROM:

.. code-block:: c

	struct fake_eeprom {
		struct eeprom parent;
		char contents[FAKE_EEPROM_CONTENTS_SIZE];
	};

	ssize_t fake_eeprom_read(struct eeprom *parent, size_t offset, char *buffer, size_t count)
	{
		struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);

		count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
		memcpy(buffer, this->contents + offset, count);

		return 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);

		count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
		memcpy(this->contents + offset, buffer, count);

		return count;
	}

	void fake_eeprom_init(struct fake_eeprom *this)
	{
		this->parent.read = fake_eeprom_read;
		this->parent.write = fake_eeprom_write;
		memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE);
	}

We can now use it to test ``struct eeprom_buffer``:

.. code-block:: c

	struct eeprom_buffer_test {
		struct fake_eeprom *fake_eeprom;
		struct eeprom_buffer *eeprom_buffer;
	};

	static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)
	{
		struct eeprom_buffer_test *ctx = test->priv;
		struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
		struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
		char buffer[] = {0xff};

		eeprom_buffer->flush_count = SIZE_MAX;

		eeprom_buffer->write(eeprom_buffer, buffer, 1);
		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);

		eeprom_buffer->write(eeprom_buffer, buffer, 1);
		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);

		eeprom_buffer->flush(eeprom_buffer);
		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
	}

	static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)
	{
		struct eeprom_buffer_test *ctx = test->priv;
		struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
		struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
		char buffer[] = {0xff};

		eeprom_buffer->flush_count = 2;

		eeprom_buffer->write(eeprom_buffer, buffer, 1);
		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);

		eeprom_buffer->write(eeprom_buffer, buffer, 1);
		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
	}

	static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)
	{
		struct eeprom_buffer_test *ctx = test->priv;
		struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
		struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
		char buffer[] = {0xff, 0xff};

		eeprom_buffer->flush_count = 2;

		eeprom_buffer->write(eeprom_buffer, buffer, 1);
		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);

		eeprom_buffer->write(eeprom_buffer, buffer, 2);
		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
		/* Should have only flushed the first two bytes. */
		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
	}

	static int eeprom_buffer_test_init(struct kunit *test)
	{
		struct eeprom_buffer_test *ctx;

		ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
		KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);

		ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);
		KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);
		fake_eeprom_init(ctx->fake_eeprom);

		ctx->eeprom_buffer = new_eeprom_buffer(&ctx->fake_eeprom->parent);
		KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);

		test->priv = ctx;

		return 0;
	}

	static void eeprom_buffer_test_exit(struct kunit *test)
	{
		struct eeprom_buffer_test *ctx = test->priv;

		destroy_eeprom_buffer(ctx->eeprom_buffer);
	}

Testing Against Multiple Inputs
-------------------------------

Testing just a few inputs is not enough to ensure that the code works correctly,
for example: testing a hash function.

We can write a helper macro or function. The function is called for each input.
For example, to test ``sha1sum(1)``, we can write:

.. code-block:: c

	#define TEST_SHA1(in, want) \
		sha1sum(in, out); \
		KUNIT_EXPECT_STREQ_MSG(test, out, want, "sha1sum(%s)", in);

	char out[40];
	TEST_SHA1("hello world",  "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed");
	TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169");

Note the use of the ``_MSG`` version of ``KUNIT_EXPECT_STREQ`` to print a more
detailed error and make the assertions clearer within the helper macros.

The ``_MSG`` variants are useful when the same expectation is called multiple
times (in a loop or helper function) and thus the line number is not enough to
identify what failed, as shown below.

In complicated cases, we recommend using a *table-driven test* compared to the
helper macro variation, for example:

.. code-block:: c

	int i;
	char out[40];

	struct sha1_test_case {
		const char *str;
		const char *sha1;
	};

	struct sha1_test_case cases[] = {
		{
			.str = "hello world",
			.sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
		},
		{
			.str = "hello world!",
			.sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
		},
	};
	for (i = 0; i < ARRAY_SIZE(cases); ++i) {
		sha1sum(cases[i].str, out);
		KUNIT_EXPECT_STREQ_MSG(test, out, cases[i].sha1,
		                      "sha1sum(%s)", cases[i].str);
	}

There is more boilerplate code involved, but it can:

* be more readable when there are multiple inputs/outputs (due to field names).

  * For example, see ``fs/ext4/inode-test.c``.

* reduce duplication if test cases are shared across multiple tests.

  * For example: if we want to test ``sha256sum``, we could add a ``sha256``
    field and reuse ``cases``.

* be converted to a "parameterized test".

Parameterized Testing
~~~~~~~~~~~~~~~~~~~~~

The table-driven testing pattern is common enough that KUnit has special
support for it.

By reusing the same ``cases`` array from above, we can write the test as a
"parameterized test" with the following.

.. code-block:: c

	// This is copy-pasted from above.
	struct sha1_test_case {
		const char *str;
		const char *sha1;
	};
	const struct sha1_test_case cases[] = {
		{
			.str = "hello world",
			.sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
		},
		{
			.str = "hello world!",
			.sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
		},
	};

	// Need a helper function to generate a name for each test case.
	static void case_to_desc(const struct sha1_test_case *t, char *desc)
	{
		strcpy(desc, t->str);
	}
	// Creates `sha1_gen_params()` to iterate over `cases`.
	KUNIT_ARRAY_PARAM(sha1, cases, case_to_desc);

	// Looks no different from a normal test.
	static void sha1_test(struct kunit *test)
	{
		// This function can just contain the body of the for-loop.
		// The former `cases[i]` is accessible under test->param_value.
		char out[40];
		struct sha1_test_case *test_param = (struct sha1_test_case *)(test->param_value);

		sha1sum(test_param->str, out);
		KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,
				      "sha1sum(%s)", test_param->str);
	}

	// Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the
	// function declared by KUNIT_ARRAY_PARAM.
	static struct kunit_case sha1_test_cases[] = {
		KUNIT_CASE_PARAM(sha1_test, sha1_gen_params),
		{}
	};

Allocating Memory
-----------------

Where you might use ``kzalloc``, you can instead use ``kunit_kzalloc`` as KUnit
will then ensure that the memory is freed once the test completes.

This is useful because it lets us use the ``KUNIT_ASSERT_EQ`` macros to exit
early from a test without having to worry about remembering to call ``kfree``.
For example:

.. code-block:: c

	void example_test_allocation(struct kunit *test)
	{
		char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL);
		/* Ensure allocation succeeded. */
		KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer);

		KUNIT_ASSERT_STREQ(test, buffer, "");
	}

Testing Static Functions
------------------------

If we do not want to expose functions or variables for testing, one option is to
conditionally ``#include`` the test file at the end of your .c file. For
example:

.. code-block:: c

	/* In my_file.c */

	static int do_interesting_thing();

	#ifdef CONFIG_MY_KUNIT_TEST
	#include "my_kunit_test.c"
	#endif

Injecting Test-Only Code
------------------------

Similar to as shown above, we can add test-specific logic. For example:

.. code-block:: c

	/* In my_file.h */

	#ifdef CONFIG_MY_KUNIT_TEST
	/* Defined in my_kunit_test.c */
	void test_only_hook(void);
	#else
	void test_only_hook(void) { }
	#endif

This test-only code can be made more useful by accessing the current ``kunit_test``
as shown in next section: *Accessing The Current Test*.

Accessing The Current Test
--------------------------

In some cases, we need to call test-only code from outside the test file.  This
is helpful, for example, when providing a fake implementation of a function, or
to fail any current test from within an error handler.
We can do this via the ``kunit_test`` field in ``task_struct``, which we can
access using the ``kunit_get_current_test()`` function in ``kunit/test-bug.h``.

``kunit_get_current_test()`` is safe to call even if KUnit is not enabled. If
KUnit is not enabled, was built as a module (``CONFIG_KUNIT=m``), or no test is
running in the current task, it will return ``NULL``. This compiles down to
either a no-op or a static key check, so will have a negligible performance
impact when no test is running.

The example below uses this to implement a "mock" implementation of a function, ``foo``:

.. code-block:: c

	#include <kunit/test-bug.h> /* for kunit_get_current_test */

	struct test_data {
		int foo_result;
		int want_foo_called_with;
	};

	static int fake_foo(int arg)
	{
		struct kunit *test = kunit_get_current_test();
		struct test_data *test_data = test->priv;

		KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg);
		return test_data->foo_result;
	}

	static void example_simple_test(struct kunit *test)
	{
		/* Assume priv (private, a member used to pass test data from
		 * the init function) is allocated in the suite's .init */
		struct test_data *test_data = test->priv;

		test_data->foo_result = 42;
		test_data->want_foo_called_with = 1;

		/* In a real test, we'd probably pass a pointer to fake_foo somewhere
		 * like an ops struct, etc. instead of calling it directly. */
		KUNIT_EXPECT_EQ(test, fake_foo(1), 42);
	}

In this example, we are using the ``priv`` member of ``struct kunit`` as a way
of passing data to the test from the init function. In general ``priv`` is
pointer that can be used for any user data. This is preferred over static
variables, as it avoids concurrency issues.

Had we wanted something more flexible, we could have used a named ``kunit_resource``.
Each test can have multiple resources which have string names providing the same
flexibility as a ``priv`` member, but also, for example, allowing helper
functions to create resources without conflicting with each other. It is also
possible to define a clean up function for each resource, making it easy to
avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/resource.rst.

Failing The Current Test
------------------------

If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)``
which is defined in ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``.
For example, we have an option to enable some extra debug checks on some data
structures as shown below:

.. code-block:: c

	#include <kunit/test-bug.h>

	#ifdef CONFIG_EXTRA_DEBUG_CHECKS
	static void validate_my_data(struct data *data)
	{
		if (is_valid(data))
			return;

		kunit_fail_current_test("data %p is invalid", data);

		/* Normal, non-KUnit, error reporting code here. */
	}
	#else
	static void my_debug_function(void) { }
	#endif

``kunit_fail_current_test()`` is safe to call even if KUnit is not enabled. If
KUnit is not enabled, was built as a module (``CONFIG_KUNIT=m``), or no test is
running in the current task, it will do nothing. This compiles down to either a
no-op or a static key check, so will have a negligible performance impact when
no test is running.


code:
.. Copyright 2004 Linus Torvalds
.. Copyright 2004 Pavel Machek <pavel@ucw.cz>
.. Copyright 2006 Bob Copeland <me@bobcopeland.com>

Sparse
======

Sparse is a semantic checker for C programs; it can be used to find a
number of potential problems with kernel code.  See
https://lwn.net/Articles/689907/ for an overview of sparse; this document
contains some kernel-specific sparse information.
More information on sparse, mainly about its internals, can be found in
its official pages at https://sparse.docs.kernel.org.

Using sparse for typechecking
-----------------------------

"__bitwise" is a type attribute, so you have to do something like this::

        typedef int __bitwise pm_request_t;

        enum pm_request {
                PM_SUSPEND = (__force pm_request_t) 1,
                PM_RESUME = (__force pm_request_t) 2
        };

which makes PM_SUSPEND and PM_RESUME "bitwise" integers (the "__force" is
there because sparse will complain about casting to/from a bitwise type,
but in this case we really _do_ want to force the conversion). And because
the enum values are all the same type, now "enum pm_request" will be that
type too.

And with gcc, all the "__bitwise"/"__force stuff" goes away, and it all
ends up looking just like integers to gcc.

Quite frankly, you don't need the enum there. The above all really just
boils down to one special "int __bitwise" type.

So the simpler way is to just do::

        typedef int __bitwise pm_request_t;

        #define PM_SUSPEND ((__force pm_request_t) 1)
        #define PM_RESUME ((__force pm_request_t) 2)

and you now have all the infrastructure needed for strict typechecking.

One small note: the constant integer "0" is special. You can use a
constant zero as a bitwise integer type without sparse ever complaining.
This is because "bitwise" (as the name implies) was designed for making
sure that bitwise types don't get mixed up (little-endian vs big-endian
vs cpu-endian vs whatever), and there the constant "0" really _is_
special.

Using sparse for lock checking
------------------------------

The following macros are undefined for gcc and defined during a sparse
run to use the "context" tracking feature of sparse, applied to
locking.  These annotations tell sparse when a lock is held, with
regard to the annotated function's entry and exit.

__must_hold - The specified lock is held on function entry and exit.

__acquires - The specified lock is held on function exit, but not entry.

__releases - The specified lock is held on function entry, but not exit.

If the function enters and exits without the lock held, acquiring and
releasing the lock inside the function in a balanced way, no
annotation is needed.  The three annotations above are for cases where
sparse would otherwise report a context imbalance.

Getting sparse
--------------

You can get tarballs of the latest released versions from:
https://www.kernel.org/pub/software/devel/sparse/dist/

Alternatively, you can get snapshots of the latest development version
of sparse using git to clone::

        git://git.kernel.org/pub/scm/devel/sparse/sparse.git

Once you have it, just do::

        make
        make install

as a regular user, and it will install sparse in your ~/bin directory.

Using sparse
------------

Do a kernel make with "make C=1" to run sparse on all the C files that get
recompiled, or use "make C=2" to run sparse on the files whether they need to
be recompiled or not.  The latter is a fast way to check the whole tree if you
have already built it.

The optional make variable CF can be used to pass arguments to sparse.  The
build system passes -Wbitwise to sparse automatically.

Note that sparse defines the __CHECKER__ preprocessor symbol.


code:
.. SPDX-License-Identifier: GPL-2.0

====================
Kernel Testing Guide
====================

There are a number of different tools for testing the Linux kernel, so knowing
when to use each of them can be a challenge. This document provides a rough
overview of their differences, and how they fit together.

Writing and Running Tests
=========================

The bulk of kernel tests are written using either the kselftest or KUnit
frameworks. These both provide infrastructure to help make running tests and
groups of tests easier, as well as providing helpers to aid in writing new
tests.

If you're looking to verify the behaviour of the Kernel — particularly specific
parts of the kernel — then you'll want to use KUnit or kselftest.

The Difference Between KUnit and kselftest
------------------------------------------

KUnit (Documentation/dev-tools/kunit/index.rst) is an entirely in-kernel system
for "white box" testing: because test code is part of the kernel, it can access
internal structures and functions which aren't exposed to userspace.

KUnit tests therefore are best written against small, self-contained parts
of the kernel, which can be tested in isolation. This aligns well with the
concept of 'unit' testing.

For example, a KUnit test might test an individual kernel function (or even a
single codepath through a function, such as an error handling case), rather
than a feature as a whole.

This also makes KUnit tests very fast to build and run, allowing them to be
run frequently as part of the development process.

There is a KUnit test style guide which may give further pointers in
Documentation/dev-tools/kunit/style.rst

kselftest (Documentation/dev-tools/kselftest.rst), on the other hand, is
largely implemented in userspace, and tests are normal userspace scripts or
programs.

This makes it easier to write more complicated tests, or tests which need to
manipulate the overall system state more (e.g., spawning processes, etc.).
However, it's not possible to call kernel functions directly from kselftest.
This means that only kernel functionality which is exposed to userspace somehow
(e.g. by a syscall, device, filesystem, etc.) can be tested with kselftest.  To
work around this, some tests include a companion kernel module which exposes
more information or functionality. If a test runs mostly or entirely within the
kernel, however,  KUnit may be the more appropriate tool.

kselftest is therefore suited well to tests of whole features, as these will
expose an interface to userspace, which can be tested, but not implementation
details. This aligns well with 'system' or 'end-to-end' testing.

For example, all new system calls should be accompanied by kselftest tests.

Code Coverage Tools
===================

The Linux Kernel supports two different code coverage measurement tools. These
can be used to verify that a test is executing particular functions or lines
of code. This is useful for determining how much of the kernel is being tested,
and for finding corner-cases which are not covered by the appropriate test.

Documentation/dev-tools/gcov.rst is GCC's coverage testing tool, which can be
used with the kernel to get global or per-module coverage. Unlike KCOV, it
does not record per-task coverage. Coverage data can be read from debugfs,
and interpreted using the usual gcov tooling.

Documentation/dev-tools/kcov.rst is a feature which can be built in to the
kernel to allow capturing coverage on a per-task level. It's therefore useful
for fuzzing and other situations where information about code executed during,
for example, a single syscall is useful.

Dynamic Analysis Tools
======================

The kernel also supports a number of dynamic analysis tools, which attempt to
detect classes of issues when they occur in a running kernel. These typically
each look for a different class of bugs, such as invalid memory accesses,
concurrency issues such as data races, or other undefined behaviour like
integer overflows.

Some of these tools are listed below:

* kmemleak detects possible memory leaks. See
  Documentation/dev-tools/kmemleak.rst
* KASAN detects invalid memory accesses such as out-of-bounds and
  use-after-free errors. See Documentation/dev-tools/kasan.rst
* UBSAN detects behaviour that is undefined by the C standard, like integer
  overflows. See Documentation/dev-tools/ubsan.rst
* KCSAN detects data races. See Documentation/dev-tools/kcsan.rst
* KFENCE is a low-overhead detector of memory issues, which is much faster than
  KASAN and can be used in production. See Documentation/dev-tools/kfence.rst
* lockdep is a locking correctness validator. See
  Documentation/locking/lockdep-design.rst
* There are several other pieces of debug instrumentation in the kernel, many
  of which can be found in lib/Kconfig.debug

These tools tend to test the kernel as a whole, and do not "pass" like
kselftest or KUnit tests. They can be combined with KUnit or kselftest by
running tests on a kernel with these tools enabled: you can then be sure
that none of these errors are occurring during the test.

Some of these tools integrate with KUnit or kselftest and will
automatically fail tests if an issue is detected.

Static Analysis Tools
=====================

In addition to testing a running kernel, one can also analyze kernel source code
directly (**at compile time**) using **static analysis** tools. The tools
commonly used in the kernel allow one to inspect the whole source tree or just
specific files within it. They make it easier to detect and fix problems during
the development process.

Sparse can help test the kernel by performing type-checking, lock checking,
value range checking, in addition to reporting various errors and warnings while
examining the code. See the Documentation/dev-tools/sparse.rst documentation
page for details on how to use it.

Smatch extends Sparse and provides additional checks for programming logic
mistakes such as missing breaks in switch statements, unused return values on
error checking, forgetting to set an error code in the return of an error path,
etc. Smatch also has tests against more serious issues such as integer
overflows, null pointer dereferences, and memory leaks. See the project page at
http://smatch.sourceforge.net/.

Coccinelle is another static analyzer at our disposal. Coccinelle is often used
to aid refactoring and collateral evolution of source code, but it can also help
to avoid certain bugs that occur in common code patterns. The types of tests
available include API tests, tests for correct usage of kernel iterators, checks
for the soundness of free operations, analysis of locking behavior, and further
tests known to help keep consistent kernel usage. See the
Documentation/dev-tools/coccinelle.rst documentation page for details.

Beware, though, that static analysis tools suffer from **false positives**.
Errors and warns need to be evaluated carefully before attempting to fix them.

When to use Sparse and Smatch
-----------------------------

Sparse does type checking, such as verifying that annotated variables do not
cause endianness bugs, detecting places that use ``__user`` pointers improperly,
and analyzing the compatibility of symbol initializers.

Smatch does flow analysis and, if allowed to build the function database, it
also does cross function analysis. Smatch tries to answer questions like where
is this buffer allocated? How big is it? Can this index be controlled by the
user? Is this variable larger than that variable?

It's generally easier to write checks in Smatch than it is to write checks in
Sparse. Nevertheless, there are some overlaps between Sparse and Smatch checks.

Strong points of Smatch and Coccinelle
--------------------------------------

Coccinelle is probably the easiest for writing checks. It works before the
pre-processor so it's easier to check for bugs in macros using Coccinelle.
Coccinelle also creates patches for you, which no other tool does.

For example, with Coccinelle you can do a mass conversion from
``kmalloc(x * size, GFP_KERNEL)`` to ``kmalloc_array(x, size, GFP_KERNEL)``, and
that's really useful. If you just created a Smatch warning and try to push the
work of converting on to the maintainers they would be annoyed. You'd have to
argue about each warning if can really overflow or not.

Coccinelle does no analysis of variable values, which is the strong point of
Smatch. On the other hand, Coccinelle allows you to do simple things in a simple
way.


code:
The Undefined Behavior Sanitizer - UBSAN
========================================

UBSAN is a runtime undefined behaviour checker.

UBSAN uses compile-time instrumentation to catch undefined behavior (UB).
Compiler inserts code that perform certain kinds of checks before operations
that may cause UB. If check fails (i.e. UB detected) __ubsan_handle_*
function called to print error message.

GCC has that feature since 4.9.x [1_] (see ``-fsanitize=undefined`` option and
its suboptions). GCC 5.x has more checkers implemented [2_].

Report example
--------------

::

	 ================================================================================
	 UBSAN: Undefined behaviour in ../include/linux/bitops.h:110:33
	 shift exponent 32 is to large for 32-bit type 'unsigned int'
	 CPU: 0 PID: 0 Comm: swapper Not tainted 4.4.0-rc1+ #26
	  0000000000000000 ffffffff82403cc8 ffffffff815e6cd6 0000000000000001
	  ffffffff82403cf8 ffffffff82403ce0 ffffffff8163a5ed 0000000000000020
	  ffffffff82403d78 ffffffff8163ac2b ffffffff815f0001 0000000000000002
	 Call Trace:
	  [<ffffffff815e6cd6>] dump_stack+0x45/0x5f
	  [<ffffffff8163a5ed>] ubsan_epilogue+0xd/0x40
	  [<ffffffff8163ac2b>] __ubsan_handle_shift_out_of_bounds+0xeb/0x130
	  [<ffffffff815f0001>] ? radix_tree_gang_lookup_slot+0x51/0x150
	  [<ffffffff8173c586>] _mix_pool_bytes+0x1e6/0x480
	  [<ffffffff83105653>] ? dmi_walk_early+0x48/0x5c
	  [<ffffffff8173c881>] add_device_randomness+0x61/0x130
	  [<ffffffff83105b35>] ? dmi_save_one_device+0xaa/0xaa
	  [<ffffffff83105653>] dmi_walk_early+0x48/0x5c
	  [<ffffffff831066ae>] dmi_scan_machine+0x278/0x4b4
	  [<ffffffff8111d58a>] ? vprintk_default+0x1a/0x20
	  [<ffffffff830ad120>] ? early_idt_handler_array+0x120/0x120
	  [<ffffffff830b2240>] setup_arch+0x405/0xc2c
	  [<ffffffff830ad120>] ? early_idt_handler_array+0x120/0x120
	  [<ffffffff830ae053>] start_kernel+0x83/0x49a
	  [<ffffffff830ad120>] ? early_idt_handler_array+0x120/0x120
	  [<ffffffff830ad386>] x86_64_start_reservations+0x2a/0x2c
	  [<ffffffff830ad4f3>] x86_64_start_kernel+0x16b/0x17a
	 ================================================================================

Usage
-----

To enable UBSAN configure kernel with::

	CONFIG_UBSAN=y

and to check the entire kernel::

        CONFIG_UBSAN_SANITIZE_ALL=y

To enable instrumentation for specific files or directories, add a line
similar to the following to the respective kernel Makefile:

- For a single file (e.g. main.o)::

    UBSAN_SANITIZE_main.o := y

- For all files in one directory::

    UBSAN_SANITIZE := y

To exclude files from being instrumented even if
``CONFIG_UBSAN_SANITIZE_ALL=y``, use::

  UBSAN_SANITIZE_main.o := n

and::

  UBSAN_SANITIZE := n

Detection of unaligned accesses controlled through the separate option -
CONFIG_UBSAN_ALIGNMENT. It's off by default on architectures that support
unaligned accesses (CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS=y). One could
still enable it in config, just note that it will produce a lot of UBSAN
reports.

References
----------

.. _1: https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/Debugging-Options.html
.. _2: https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html
.. _3: https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html


code:
# SPDX-License-Identifier: GPL-2.0-only
*.example.dts
/processed-schema*.yaml
/processed-schema*.json


code:
extends: relaxed

rules:
  line-length:
    # 80 chars should be enough, but don't fail if a line is longer
    max: 110
    allow-non-breakable-words: true
    level: warning
  braces:
    min-spaces-inside: 0
    max-spaces-inside: 1
    min-spaces-inside-empty: 0
    max-spaces-inside-empty: 0
  brackets:
    min-spaces-inside: 0
    max-spaces-inside: 1
    min-spaces-inside-empty: 0
    max-spaces-inside-empty: 0
  colons: {max-spaces-before: 0, max-spaces-after: 1}
  commas: {min-spaces-after: 1, max-spaces-after: 1}
  comments:
    require-starting-space: false
    min-spaces-from-content: 1
  comments-indentation: disable
  document-start:
    present: true
  empty-lines:
    max: 3
    max-end: 1
  empty-values:
    forbid-in-block-mappings: true
    forbid-in-flow-mappings: true
  hyphens:
    max-spaces-after: 1
  indentation:
    spaces: 2
    indent-sequences: true
    check-multi-line-strings: false
  trailing-spaces: false


code:
.. SPDX-License-Identifier: GPL-2.0

===================
Devicetree (DT) ABI
===================

I. Regarding stable bindings/ABI, we quote from the 2013 ARM mini-summit
   summary document:

     "That still leaves the question of, what does a stable binding look
     like?  Certainly a stable binding means that a newer kernel will not
     break on an older device tree, but that doesn't mean the binding is
     frozen for all time. Grant said there are ways to change bindings that
     don't result in breakage. For instance, if a new property is added,
     then default to the previous behaviour if it is missing. If a binding
     truly needs an incompatible change, then change the compatible string
     at the same time.  The driver can bind against both the old and the
     new. These guidelines aren't new, but they desperately need to be
     documented."

II.  General binding rules

  1) Maintainers, don't let perfect be the enemy of good.  Don't hold up a
     binding because it isn't perfect.

  2) Use specific compatible strings so that if we need to add a feature (DMA)
     in the future, we can create a new compatible string.  See I.

  3) Bindings can be augmented, but the driver shouldn't break when given
     the old binding. ie. add additional properties, but don't change the
     meaning of an existing property. For drivers, default to the original
     behaviour when a newly added property is missing.

  4) Don't submit bindings for staging or unstable.  That will be decided by
     the devicetree maintainers *after* discussion on the mailinglist.

III. Notes

  1) This document is intended as a general familiarization with the process as
     decided at the 2013 Kernel Summit.  When in doubt, the current word of the
     devicetree maintainers overrules this document.  In that situation, a patch
     updating this document would be appreciated.


code:
# SPDX-License-Identifier: GPL-2.0
DT_DOC_CHECKER ?= dt-doc-validate
DT_EXTRACT_EX ?= dt-extract-example
DT_MK_SCHEMA ?= dt-mk-schema

DT_SCHEMA_LINT = $(shell which yamllint || \
  echo "warning: python package 'yamllint' not installed, skipping" >&2)

DT_SCHEMA_MIN_VERSION = 2022.3

PHONY += check_dtschema_version
check_dtschema_version:
	@which $(DT_DOC_CHECKER) >/dev/null || \
		{ echo "Error: '$(DT_DOC_CHECKER)' not found!" >&2; \
		  echo "Ensure dtschema python package is installed and in your PATH." >&2; \
		  echo "Current PATH is:" >&2; \
		  echo "$$PATH" >&2; false; }
	@{ echo $(DT_SCHEMA_MIN_VERSION); \
	$(DT_DOC_CHECKER) --version 2>/dev/null || echo 0; } | sort -Vc >/dev/null || \
	{ echo "ERROR: dtschema minimum version is v$(DT_SCHEMA_MIN_VERSION)" >&2; false; }

quiet_cmd_extract_ex = DTEX    $@
      cmd_extract_ex = $(DT_EXTRACT_EX) $< > $@

$(obj)/%.example.dts: $(src)/%.yaml check_dtschema_version FORCE
	$(call if_changed,extract_ex)

find_all_cmd = find $(srctree)/$(src) \( -name '*.yaml' ! \
		-name 'processed-schema*' \)

find_cmd = $(find_all_cmd) | grep -F "$(DT_SCHEMA_FILES)"
CHK_DT_DOCS := $(shell $(find_cmd))

quiet_cmd_yamllint = LINT    $(src)
      cmd_yamllint = ($(find_cmd) | \
                     xargs -n200 -P$$(nproc) \
		     $(DT_SCHEMA_LINT) -f parsable -c $(srctree)/$(src)/.yamllint >&2) || true

quiet_cmd_chk_bindings = CHKDT   $@
      cmd_chk_bindings = ($(find_cmd) | \
                         xargs -n200 -P$$(nproc) $(DT_DOC_CHECKER) -u $(srctree)/$(src)) || true

quiet_cmd_mk_schema = SCHEMA  $@
      cmd_mk_schema = f=$$(mktemp) ; \
                      $(find_all_cmd) > $$f ; \
                      $(DT_MK_SCHEMA) -j $(DT_MK_SCHEMA_FLAGS) @$$f > $@ ; \
		      rm -f $$f

define rule_chkdt
	$(if $(DT_SCHEMA_LINT),$(call cmd,yamllint),)
	$(call cmd,chk_bindings)
	$(call cmd,mk_schema)
endef

DT_DOCS = $(patsubst $(srctree)/%,%,$(shell $(find_all_cmd)))

override DTC_FLAGS := \
	-Wno-avoid_unnecessary_addr_size \
	-Wno-graph_child_address \
	-Wno-interrupt_provider \
	-Wno-unique_unit_address \
	-Wunique_unit_address_if_enabled

# Disable undocumented compatible checks until warning free
override DT_CHECKER_FLAGS ?=

$(obj)/processed-schema.json: $(DT_DOCS) $(src)/.yamllint check_dtschema_version FORCE
	$(call if_changed_rule,chkdt)

always-y += processed-schema.json
always-$(CHECK_DT_BINDING) += $(patsubst $(srctree)/$(src)/%.yaml,%.example.dts, $(CHK_DT_DOCS))
always-$(CHECK_DT_BINDING) += $(patsubst $(srctree)/$(src)/%.yaml,%.example.dtb, $(CHK_DT_DOCS))

# Hack: avoid 'Argument list too long' error for 'make clean'. Remove most of
# build artifacts here before they are processed by scripts/Makefile.clean
clean-files = $(shell find $(obj) \( -name '*.example.dts' -o \
			-name '*.example.dtb' \) -delete 2>/dev/null)

dt_compatible_check: $(obj)/processed-schema.json
	$(Q)$(srctree)/scripts/dtc/dt-extract-compatibles $(srctree) | xargs dt-check-compatible -v -s $<


code:
* ARC HS Performance Counters

The ARC HS can be configured with a pipeline performance monitor for counting
CPU and cache events like cache misses and hits. Like conventional PCT there
are 100+ hardware conditions dynamically mapped to up to 32 counters.
It also supports overflow interrupts.

Required properties:

- compatible : should contain
	"snps,archs-pct"

Example:

pmu {
        compatible = "snps,archs-pct";
};


code:
Synopsys DesignWare ARC Software Development Platforms Device Tree Bindings
---------------------------------------------------------------------------

SDP Main Board with an AXC001 CPU Card hoisting ARC700 core in silicon

Required root node properties:
    - compatible = "snps,axs101", "snps,arc-sdp";


code:
Synopsys DesignWare ARC Software Development Platforms Device Tree Bindings
---------------------------------------------------------------------------

SDP Main Board with an AXC003 FPGA Card which can contain various flavours of
HS38x cores.

Required root node properties:
    - compatible = "snps,axs103", "snps,arc-sdp";


code:
EZchip NPS Network Processor Platforms Device Tree Bindings
---------------------------------------------------------------------------

Appliance main board with NPS400 ASIC.

Required root node properties:
    - compatible = "ezchip,arc-nps";


code:
Synopsys DesignWare ARC HS Development Kit Device Tree Bindings
---------------------------------------------------------------------------

ARC HSDK Board with quad-core ARC HS38x4 in silicon.

Required root node properties:
    - compatible = "snps,hsdk";


code:
* ARC Performance Counters

The ARC700 can be configured with a pipeline performance monitor for counting
CPU and cache events like cache misses and hits. Like conventional PCT there
are 100+ hardware conditions dynamically mapped to up to 32 counters

Note that:
 * The ARC 700 PCT does not support interrupts; although HW events may be
   counted, the HW events themselves cannot serve as a trigger for a sample.

Required properties:

- compatible : should contain
	"snps,arc700-pct"

Example:

pmu {
        compatible = "snps,arc700-pct";
};


code:
# SPDX-License-Identifier: GPL-2.0-or-later OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/arm/actions.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Actions Semi platforms

maintainers:
  - Andreas Färber <afaerber@suse.de>
  - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>

properties:
  $nodename:
    const: "/"
  compatible:
    oneOf:
      # The Actions Semi S500 is a quad-core ARM Cortex-A9 SoC.
      - items:
          - enum:
              - allo,sparky # Allo.com Sparky
              - cubietech,cubieboard6 # Cubietech CubieBoard6
              - roseapplepi,roseapplepi # RoseapplePi.org RoseapplePi
          - const: actions,s500
      - items:
          - enum:
              - caninos,labrador-base-m # Labrador Base Board M v1
          - const: caninos,labrador-v2  # Labrador Core v2
          - const: actions,s500
      - items:
          - enum:
              - lemaker,guitar-bb-rev-b # LeMaker Guitar Base Board rev. B
          - const: lemaker,guitar
          - const: actions,s500

      # The Actions Semi S700 is a quad-core ARM Cortex-A53 SoC.
      - items:
          - enum:
              - caninos,labrador-base-m2 # Labrador Base Board M v2
          - const: caninos,labrador-v3   # Labrador Core v3
          - const: actions,s700
      - items:
          - enum:
              - cubietech,cubieboard7 # Cubietech CubieBoard7
          - const: actions,s700

      # The Actions Semi S900 is a quad-core ARM Cortex-A53 SoC.
      - items:
          - enum:
              - ucrobotics,bubblegum-96 # uCRobotics Bubblegum-96
          - const: actions,s900

additionalProperties: true


code:
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/arm/airoha.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Airoha SoC based Platforms

maintainers:
  - Felix Fietkau <nbd@nbd.name>
  - John Crispin <john@phrozen.org>

description:
  Boards with an Airoha SoC shall have the following properties.

properties:
  $nodename:
    const: '/'
  compatible:
    oneOf:
      - items:
          - enum:
              - airoha,en7523-evb
          - const: airoha,en7523

additionalProperties: true

...


code:
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/arm/altera.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Altera's SoCFPGA platform

maintainers:
  - Dinh Nguyen <dinguyen@kernel.org>

properties:
  $nodename:
    const: "/"
  compatible:
    oneOf:
      - description: Arria 5 boards
        items:
          - enum:
              - altr,socfpga-arria5-socdk
          - const: altr,socfpga-arria5
          - const: altr,socfpga

      - description: Arria 10 boards
        items:
          - enum:
              - altr,socfpga-arria10-socdk
          - const: altr,socfpga-arria10
          - const: altr,socfpga

      - description: Mercury+ AA1 boards
        items:
          - enum:
              - google,chameleon-v3
          - const: enclustra,mercury-aa1
          - const: altr,socfpga-arria10
          - const: altr,socfpga

      - description: Cyclone 5 boards
        items:
          - enum:
              - altr,socfpga-cyclone5-socdk
              - denx,mcvevk
              - ebv,socrates
              - macnica,sodia
              - novtech,chameleon96
              - samtec,vining
              - terasic,de0-atlas
              - terasic,socfpga-cyclone5-sockit
          - const: altr,socfpga-cyclone5
          - const: altr,socfpga

      - description: Stratix 10 boards
        items:
          - enum:
              - altr,socfpga-stratix10-socdk
              - altr,socfpga-stratix10-swvp
          - const: altr,socfpga-stratix10

      - description: SoCFPGA VT
        items:
          - const: altr,socfpga-vt
          - const: altr,socfpga

additionalProperties: true

...


code:
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/arm/altera/socfpga-clk-manager.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Altera SOCFPGA Clock Manager

maintainers:
  - Dinh Nguyen <dinguyen@kernel.org>

description: test

properties:
  compatible:
    items:
      - const: altr,clk-mgr
  reg:
    maxItems: 1

required:
  - compatible

additionalProperties: false

examples:
  - |
    clkmgr@ffd04000 {
      compatible = "altr,clk-mgr";
      reg = <0xffd04000 0x1000>;
    };

...


code:
Altera SOCFPGA SDRAM Controller

Required properties:
- compatible : Should contain "altr,sdr-ctl" and "syscon".
  syscon is required by the Altera SOCFPGA SDRAM EDAC.
- reg : Should contain 1 register range (address and length)

Example:
	sdr: sdr@ffc25000 {
		compatible = "altr,sdr-ctl", "syscon";
		reg = <0xffc25000 0x1000>;
	};


code:
Altera SOCFPGA SDRAM Error Detection & Correction [EDAC]
The EDAC accesses a range of registers in the SDRAM controller.

Required properties:
- compatible : should contain "altr,sdram-edac" or "altr,sdram-edac-a10"
- altr,sdr-syscon : phandle of the sdr module
- interrupts : Should contain the SDRAM ECC IRQ in the
	appropriate format for the IRQ controller.

Example:
	sdramedac {
		compatible = "altr,sdram-edac";
		altr,sdr-syscon = <&sdr>;
		interrupts = <0 39 4>;
	};


code:
Altera SOCFPGA System Manager

Required properties:
- compatible : "altr,sys-mgr"
- reg : Should contain 1 register ranges(address and length)
- cpu1-start-addr : CPU1 start address in hex.

Example:
	 sysmgr@ffd08000 {
		compatible = "altr,sys-mgr";
		reg = <0xffd08000 0x1000>;
		cpu1-start-addr = <0xffd080c4>;
	};

ARM64 - Stratix10
Required properties:
- compatible : "altr,sys-mgr-s10"
- reg : Should contain 1 register range(address and length)
        for system manager register.

Example:
	 sysmgr@ffd12000 {
		compatible = "altr,sys-mgr-s10";
		reg = <0xffd12000 0x228>;
	};


code:
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/arm/amazon,al.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Amazon's Annapurna Labs Alpine Platform

maintainers:
  - Hanna Hawa <hhhawa@amazon.com>
  - Talel Shenhar <talel@amazon.com>, <talelshenhar@gmail.com>
  - Ronen Krupnik <ronenk@amazon.com>

properties:
  compatible:
    oneOf:
      - description: Boards with Alpine V1 SoC
        items:
          - const: al,alpine

      - description: Boards with Alpine V2 SoC
        items:
          - enum:
              - al,alpine-v2-evp
          - const: al,alpine-v2

      - description: Boards with Alpine V3 SoC
        items:
          - enum:
              - amazon,al-alpine-v3-evp
          - const: amazon,al-alpine-v3

additionalProperties: true

...