development/design.rst

============
KUnit Design
============

High Level Structure
====================

KUnit in practice is divided into two components: the KUnit kernel (more often
referred to as the KUnit kernel, or just the kernel), and the kunit_tool. Most
of KUnit, including all the test cases, all of the test libraries, and even the
test runner itself are all part of the Linux kernel.

.. todo: Discuss the non-UML design of KUnit.

.. _uml:

User Mode Linux
---------------

User Mode Linux, or UML, is a way to compile and run the Linux kernel as a
normal program that can run in userspace without the help of a VM or any
virtualization support.

UML is an architecture `arch/um/
<https://elixir.bootlin.com/linux/latest/source/arch/um>`_ that maps all the
architecture specific elements, which would normally map to low level hardware
features, to the POSIX interface allowing the Linux kernel to be compiled and
run as a normal userspace program.

For more information on UML, see: http://user-mode-linux.sourceforge.net/

KUnit Kernel
------------

Most of the complexity of KUnit lies in the Linux kernel itself. Within the
KUnit kernel there are several parts:

- The :ref:`test-runner` which schedules and runs all the tests, which is
  composed of:

  - The Linux initcall subsystem which invokes:
  - The :ref:`test-case-runner` which handles sandboxing and running individual
    test cases.

- The :ref:`test-library` which provide wrappers around the API provided by the
  Test Case Runner to test cases to communicate with it.

The Linux kernel itself is **much** more complicated than this, but a full
overview is outside of the scope of this document.

.. _test-runner:

Test Runner
~~~~~~~~~~~

The test runner in KUnit is more or less the KUnit kernel itself. Each `kunit
suite <../third_party/kernel/docs/api/test.html#c.kunit_suite>`_, KUnit's name
for a test suite, registers its test case runner as an init call with the Linux
initcall system with |kunit_test_suite|_. When the kernel boots up, it runs
through all the initcalls to initialize all its subsystems; the last initcalls
it executes are the test case runners.

.. |kunit_test_suite| replace:: ``kunit_test_suite(suite)``
.. _kunit_test_suite: third_party/kernel/docs/api/test.html#c.kunit_test_suite

.. _test-case-runner:

Test Case Runner
~~~~~~~~~~~~~~~~

Each test case runner is associated with a `kunit suite
<../third_party/kernel/docs/api/test.html#c.kunit_suite>`_. When the test case
runner is invoked, it runs through each test case and for each test case, does
the following:

- Register a failure handler with the UML trap subsytem.
- Run the init function provided by the ``kunit_suite``.
- Run the test case.
- Run the exit function provided by the ``kunit_suite``.
- Deallocate all the test allocated resources.
- Report test results.

All this happens in `lib/kunit/test.c
<https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/tree/lib/kunit/test.c?h=test&id=741a98d022362c90609ac9dcd8ad56314d8e68b3>`_.

.. _test-library:

Test Library
~~~~~~~~~~~~

Currently, the test runner provides the function ``kunit_do_assertion`` for the
test case to communicate a failed assertion:

.. code-block:: c

   void kunit_do_assertion(struct kunit *test,
                           struct kunit_assert *assert,
                           bool pass,
                           const char *fmt, ...);

It takes a

- `kunit (test context object) <../third_party/kernel/docs/api/test.html#c.kunit>`_
- `assertion object <https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/tree/include/kunit/assert.h?h=test&id=741a98d022362c90609ac9dcd8ad56314d8e68b3#n42>`_
- whether the expectation/assertion failed or not
- log message to show on failure represented as a C format string.

The function definition can be found here:
https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/tree/lib/kunit/test.c?h=test&id=741a98d022362c90609ac9dcd8ad56314d8e68b3#n152

kunit_tool
----------

Currently the main purpose kunit_tool serves is just to make to process of
building the kernel and running tests easier, but it also serves as a place
where workarounds can be added in. For example, there are some bugs (for
example, if the UML kernel crashes, it will corrupt the user's terminal
settings) with the UML user interface that are much easier to work around
outside of the kernel than fix in the kernel itself. One of the function it
serves is to parse the kernel output and print out the summarized results in a
nice, human readable format.