code:
=================================================
Using kgdb, kdb and the kernel debugger internals
=================================================

:Author: Jason Wessel

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

The kernel has two different debugger front ends (kdb and kgdb) which
interface to the debug core. It is possible to use either of the
debugger front ends and dynamically transition between them if you
configure the kernel properly at compile and runtime.

Kdb is simplistic shell-style interface which you can use on a system
console with a keyboard or serial console. You can use it to inspect
memory, registers, process lists, dmesg, and even set breakpoints to
stop in a certain location. Kdb is not a source level debugger, although
you can set breakpoints and execute some basic kernel run control. Kdb
is mainly aimed at doing some analysis to aid in development or
diagnosing kernel problems. You can access some symbols by name in
kernel built-ins or in kernel modules if the code was built with
``CONFIG_KALLSYMS``.

Kgdb is intended to be used as a source level debugger for the Linux
kernel. It is used along with gdb to debug a Linux kernel. The
expectation is that gdb can be used to "break in" to the kernel to
inspect memory, variables and look through call stack information
similar to the way an application developer would use gdb to debug an
application. It is possible to place breakpoints in kernel code and
perform some limited execution stepping.

Two machines are required for using kgdb. One of these machines is a
development machine and the other is the target machine. The kernel to
be debugged runs on the target machine. The development machine runs an
instance of gdb against the vmlinux file which contains the symbols (not
a boot image such as bzImage, zImage, uImage...). In gdb the developer
specifies the connection parameters and connects to kgdb. The type of
connection a developer makes with gdb depends on the availability of
kgdb I/O modules compiled as built-ins or loadable kernel modules in the
test machine's kernel.

Compiling a kernel
==================

-  In order to enable compilation of kdb, you must first enable kgdb.

-  The kgdb test compile options are described in the kgdb test suite
   chapter.

Kernel config options for kgdb
------------------------------

To enable ``CONFIG_KGDB`` you should look under
:menuselection:`Kernel hacking --> Kernel debugging` and select
:menuselection:`KGDB: kernel debugger`.

While it is not a hard requirement that you have symbols in your vmlinux
file, gdb tends not to be very useful without the symbolic data, so you
will want to turn on ``CONFIG_DEBUG_INFO`` which is called
:menuselection:`Compile the kernel with debug info` in the config menu.

It is advised, but not required, that you turn on the
``CONFIG_FRAME_POINTER`` kernel option which is called :menuselection:`Compile
the kernel with frame pointers` in the config menu. This option inserts code
into the compiled executable which saves the frame information in registers
or on the stack at different points which allows a debugger such as gdb to
more accurately construct stack back traces while debugging the kernel.

If the architecture that you are using supports the kernel option
``CONFIG_STRICT_KERNEL_RWX``, you should consider turning it off. This
option will prevent the use of software breakpoints because it marks
certain regions of the kernel's memory space as read-only. If kgdb
supports it for the architecture you are using, you can use hardware
breakpoints if you desire to run with the ``CONFIG_STRICT_KERNEL_RWX``
option turned on, else you need to turn off this option.

Next you should choose one of more I/O drivers to interconnect debugging
host and debugged target. Early boot debugging requires a KGDB I/O
driver that supports early debugging and the driver must be built into
the kernel directly. Kgdb I/O driver configuration takes place via
kernel or module parameters which you can learn more about in the in the
section that describes the parameter kgdboc.

Here is an example set of ``.config`` symbols to enable or disable for kgdb::

  # CONFIG_STRICT_KERNEL_RWX is not set
  CONFIG_FRAME_POINTER=y
  CONFIG_KGDB=y
  CONFIG_KGDB_SERIAL_CONSOLE=y

Kernel config options for kdb
-----------------------------

Kdb is quite a bit more complex than the simple gdbstub sitting on top
of the kernel's debug core. Kdb must implement a shell, and also adds
some helper functions in other parts of the kernel, responsible for
printing out interesting data such as what you would see if you ran
``lsmod``, or ``ps``. In order to build kdb into the kernel you follow the
same steps as you would for kgdb.

The main config option for kdb is ``CONFIG_KGDB_KDB`` which is called
:menuselection:`KGDB_KDB: include kdb frontend for kgdb` in the config menu.
In theory you would have already also selected an I/O driver such as the
``CONFIG_KGDB_SERIAL_CONSOLE`` interface if you plan on using kdb on a
serial port, when you were configuring kgdb.

If you want to use a PS/2-style keyboard with kdb, you would select
``CONFIG_KDB_KEYBOARD`` which is called :menuselection:`KGDB_KDB: keyboard as
input device` in the config menu. The ``CONFIG_KDB_KEYBOARD`` option is not
used for anything in the gdb interface to kgdb. The ``CONFIG_KDB_KEYBOARD``
option only works with kdb.

Here is an example set of ``.config`` symbols to enable/disable kdb::

  # CONFIG_STRICT_KERNEL_RWX is not set
  CONFIG_FRAME_POINTER=y
  CONFIG_KGDB=y
  CONFIG_KGDB_SERIAL_CONSOLE=y
  CONFIG_KGDB_KDB=y
  CONFIG_KDB_KEYBOARD=y

Kernel Debugger Boot Arguments
==============================

This section describes the various runtime kernel parameters that affect
the configuration of the kernel debugger. The following chapter covers
using kdb and kgdb as well as providing some examples of the
configuration parameters.

Kernel parameter: kgdboc
------------------------

The kgdboc driver was originally an abbreviation meant to stand for
"kgdb over console". Today it is the primary mechanism to configure how
to communicate from gdb to kgdb as well as the devices you want to use
to interact with the kdb shell.

For kgdb/gdb, kgdboc is designed to work with a single serial port. It
is intended to cover the circumstance where you want to use a serial
console as your primary console as well as using it to perform kernel
debugging. It is also possible to use kgdb on a serial port which is not
designated as a system console. Kgdboc may be configured as a kernel
built-in or a kernel loadable module. You can only make use of
``kgdbwait`` and early debugging if you build kgdboc into the kernel as
a built-in.

Optionally you can elect to activate kms (Kernel Mode Setting)
integration. When you use kms with kgdboc and you have a video driver
that has atomic mode setting hooks, it is possible to enter the debugger
on the graphics console. When the kernel execution is resumed, the
previous graphics mode will be restored. This integration can serve as a
useful tool to aid in diagnosing crashes or doing analysis of memory
with kdb while allowing the full graphics console applications to run.

kgdboc arguments
~~~~~~~~~~~~~~~~

Usage::

	kgdboc=[kms][[,]kbd][[,]serial_device][,baud]

The order listed above must be observed if you use any of the optional
configurations together.

Abbreviations:

-  kms = Kernel Mode Setting

-  kbd = Keyboard

You can configure kgdboc to use the keyboard, and/or a serial device
depending on if you are using kdb and/or kgdb, in one of the following
scenarios. The order listed above must be observed if you use any of the
optional configurations together. Using kms + only gdb is generally not
a useful combination.

Using loadable module or built-in
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. As a kernel built-in:

   Use the kernel boot argument::

	kgdboc=<tty-device>,[baud]

2. As a kernel loadable module:

   Use the command::

	modprobe kgdboc kgdboc=<tty-device>,[baud]

   Here are two examples of how you might format the kgdboc string. The
   first is for an x86 target using the first serial port. The second
   example is for the ARM Versatile AB using the second serial port.

   1. ``kgdboc=ttyS0,115200``

   2. ``kgdboc=ttyAMA1,115200``

Configure kgdboc at runtime with sysfs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

At run time you can enable or disable kgdboc by echoing a parameters
into the sysfs. Here are two examples:

1. Enable kgdboc on ttyS0::

	echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc

2. Disable kgdboc::

	echo "" > /sys/module/kgdboc/parameters/kgdboc

.. note::

   You do not need to specify the baud if you are configuring the
   console on tty which is already configured or open.

More examples
^^^^^^^^^^^^^

You can configure kgdboc to use the keyboard, and/or a serial device
depending on if you are using kdb and/or kgdb, in one of the following
scenarios.

1. kdb and kgdb over only a serial port::

	kgdboc=<serial_device>[,baud]

   Example::

	kgdboc=ttyS0,115200

2. kdb and kgdb with keyboard and a serial port::

	kgdboc=kbd,<serial_device>[,baud]

   Example::

	kgdboc=kbd,ttyS0,115200

3. kdb with a keyboard::

	kgdboc=kbd

4. kdb with kernel mode setting::

	kgdboc=kms,kbd

5. kdb with kernel mode setting and kgdb over a serial port::

	kgdboc=kms,kbd,ttyS0,115200

.. note::

   Kgdboc does not support interrupting the target via the gdb remote
   protocol. You must manually send a :kbd:`SysRq-G` unless you have a proxy
   that splits console output to a terminal program. A console proxy has a
   separate TCP port for the debugger and a separate TCP port for the
   "human" console. The proxy can take care of sending the :kbd:`SysRq-G`
   for you.

When using kgdboc with no debugger proxy, you can end up connecting the
debugger at one of two entry points. If an exception occurs after you
have loaded kgdboc, a message should print on the console stating it is
waiting for the debugger. In this case you disconnect your terminal
program and then connect the debugger in its place. If you want to
interrupt the target system and forcibly enter a debug session you have
to issue a :kbd:`Sysrq` sequence and then type the letter :kbd:`g`. Then you
disconnect the terminal session and connect gdb. Your options if you
don't like this are to hack gdb to send the :kbd:`SysRq-G` for you as well as
on the initial connect, or to use a debugger proxy that allows an
unmodified gdb to do the debugging.

Kernel parameter: ``kgdboc_earlycon``
-------------------------------------

If you specify the kernel parameter ``kgdboc_earlycon`` and your serial
driver registers a boot console that supports polling (doesn't need
interrupts and implements a nonblocking read() function) kgdb will attempt
to work using the boot console until it can transition to the regular
tty driver specified by the ``kgdboc`` parameter.

Normally there is only one boot console (especially that implements the
read() function) so just adding ``kgdboc_earlycon`` on its own is
sufficient to make this work. If you have more than one boot console you
can add the boot console's name to differentiate. Note that names that
are registered through the boot console layer and the tty layer are not
the same for the same port.

For instance, on one board to be explicit you might do::

   kgdboc_earlycon=qcom_geni kgdboc=ttyMSM0

If the only boot console on the device was "qcom_geni", you could simplify::

   kgdboc_earlycon kgdboc=ttyMSM0

Kernel parameter: ``kgdbwait``
------------------------------

The Kernel command line option ``kgdbwait`` makes kgdb wait for a
debugger connection during booting of a kernel. You can only use this
option if you compiled a kgdb I/O driver into the kernel and you
specified the I/O driver configuration as a kernel command line option.
The kgdbwait parameter should always follow the configuration parameter
for the kgdb I/O driver in the kernel command line else the I/O driver
will not be configured prior to asking the kernel to use it to wait.

The kernel will stop and wait as early as the I/O driver and
architecture allows when you use this option. If you build the kgdb I/O
driver as a loadable kernel module kgdbwait will not do anything.

Kernel parameter: ``kgdbcon``
-----------------------------

The ``kgdbcon`` feature allows you to see printk() messages inside gdb
while gdb is connected to the kernel. Kdb does not make use of the kgdbcon
feature.

Kgdb supports using the gdb serial protocol to send console messages to
the debugger when the debugger is connected and running. There are two
ways to activate this feature.

1. Activate with the kernel command line option::

	kgdbcon

2. Use sysfs before configuring an I/O driver::

	echo 1 > /sys/module/kgdb/parameters/kgdb_use_con

.. note::

   If you do this after you configure the kgdb I/O driver, the
   setting will not take effect until the next point the I/O is
   reconfigured.

.. important::

   You cannot use kgdboc + kgdbcon on a tty that is an
   active system console. An example of incorrect usage is::

	console=ttyS0,115200 kgdboc=ttyS0 kgdbcon

It is possible to use this option with kgdboc on a tty that is not a
system console.

Run time parameter: ``kgdbreboot``
----------------------------------

The kgdbreboot feature allows you to change how the debugger deals with
the reboot notification. You have 3 choices for the behavior. The
default behavior is always set to 0.

.. tabularcolumns:: |p{0.4cm}|p{11.5cm}|p{5.6cm}|

.. flat-table::
  :widths: 1 10 8

  * - 1
    - ``echo -1 > /sys/module/debug_core/parameters/kgdbreboot``
    - Ignore the reboot notification entirely.

  * - 2
    - ``echo 0 > /sys/module/debug_core/parameters/kgdbreboot``
    - Send the detach message to any attached debugger client.

  * - 3
    - ``echo 1 > /sys/module/debug_core/parameters/kgdbreboot``
    - Enter the debugger on reboot notify.

Kernel parameter: ``nokaslr``
-----------------------------

If the architecture that you are using enable KASLR by default,
you should consider turning it off.  KASLR randomizes the
virtual address where the kernel image is mapped and confuse
gdb which resolve kernel symbol address from symbol table
of vmlinux.

Using kdb
=========

Quick start for kdb on a serial port
------------------------------------

This is a quick example of how to use kdb.

1. Configure kgdboc at boot using kernel parameters::

	console=ttyS0,115200 kgdboc=ttyS0,115200 nokaslr

   OR

   Configure kgdboc after the kernel has booted; assuming you are using
   a serial port console::

	echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc

2. Enter the kernel debugger manually or by waiting for an oops or
   fault. There are several ways you can enter the kernel debugger
   manually; all involve using the :kbd:`SysRq-G`, which means you must have
   enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config.

   -  When logged in as root or with a super user session you can run::

	echo g > /proc/sysrq-trigger

   -  Example using minicom 2.2

      Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`

   -  When you have telneted to a terminal server that supports sending
      a remote break

      Press: :kbd:`CTRL-]`

      Type in: ``send break``

      Press: :kbd:`Enter` :kbd:`g`

3. From the kdb prompt you can run the ``help`` command to see a complete
   list of the commands that are available.

   Some useful commands in kdb include:

   =========== =================================================================
   ``lsmod``   Shows where kernel modules are loaded
   ``ps``      Displays only the active processes
   ``ps A``    Shows all the processes
   ``summary`` Shows kernel version info and memory usage
   ``bt``      Get a backtrace of the current process using dump_stack()
   ``dmesg``   View the kernel syslog buffer
   ``go``      Continue the system
   =========== =================================================================

4. When you are done using kdb you need to consider rebooting the system
   or using the ``go`` command to resuming normal kernel execution. If you
   have paused the kernel for a lengthy period of time, applications
   that rely on timely networking or anything to do with real wall clock
   time could be adversely affected, so you should take this into
   consideration when using the kernel debugger.

Quick start for kdb using a keyboard connected console
------------------------------------------------------

This is a quick example of how to use kdb with a keyboard.

1. Configure kgdboc at boot using kernel parameters::

	kgdboc=kbd

   OR

   Configure kgdboc after the kernel has booted::

	echo kbd > /sys/module/kgdboc/parameters/kgdboc

2. Enter the kernel debugger manually or by waiting for an oops or
   fault. There are several ways you can enter the kernel debugger
   manually; all involve using the :kbd:`SysRq-G`, which means you must have
   enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config.

   -  When logged in as root or with a super user session you can run::

	echo g > /proc/sysrq-trigger

   -  Example using a laptop keyboard:

      Press and hold down: :kbd:`Alt`

      Press and hold down: :kbd:`Fn`

      Press and release the key with the label: :kbd:`SysRq`

      Release: :kbd:`Fn`

      Press and release: :kbd:`g`

      Release: :kbd:`Alt`

   -  Example using a PS/2 101-key keyboard

      Press and hold down: :kbd:`Alt`

      Press and release the key with the label: :kbd:`SysRq`

      Press and release: :kbd:`g`

      Release: :kbd:`Alt`

3. Now type in a kdb command such as ``help``, ``dmesg``, ``bt`` or ``go`` to
   continue kernel execution.

Using kgdb / gdb
================

In order to use kgdb you must activate it by passing configuration
information to one of the kgdb I/O drivers. If you do not pass any
configuration information kgdb will not do anything at all. Kgdb will
only actively hook up to the kernel trap hooks if a kgdb I/O driver is
loaded and configured. If you unconfigure a kgdb I/O driver, kgdb will
unregister all the kernel hook points.

All kgdb I/O drivers can be reconfigured at run time, if
``CONFIG_SYSFS`` and ``CONFIG_MODULES`` are enabled, by echo'ing a new
config string to ``/sys/module/<driver>/parameter/<option>``. The driver
can be unconfigured by passing an empty string. You cannot change the
configuration while the debugger is attached. Make sure to detach the
debugger with the ``detach`` command prior to trying to unconfigure a
kgdb I/O driver.

Connecting with gdb to a serial port
------------------------------------

1. Configure kgdboc

   Configure kgdboc at boot using kernel parameters::

	kgdboc=ttyS0,115200

   OR

   Configure kgdboc after the kernel has booted::

	echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc

2. Stop kernel execution (break into the debugger)

   In order to connect to gdb via kgdboc, the kernel must first be
   stopped. There are several ways to stop the kernel which include
   using kgdbwait as a boot argument, via a :kbd:`SysRq-G`, or running the
   kernel until it takes an exception where it waits for the debugger to
   attach.

   -  When logged in as root or with a super user session you can run::

	echo g > /proc/sysrq-trigger

   -  Example using minicom 2.2

      Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`

   -  When you have telneted to a terminal server that supports sending
      a remote break

      Press: :kbd:`CTRL-]`

      Type in: ``send break``

      Press: :kbd:`Enter` :kbd:`g`

3. Connect from gdb

   Example (using a directly connected port)::

           % gdb ./vmlinux
           (gdb) set serial baud 115200
           (gdb) target remote /dev/ttyS0

   Example (kgdb to a terminal server on TCP port 2012)::

           % gdb ./vmlinux
           (gdb) target remote 192.168.2.2:2012

   Once connected, you can debug a kernel the way you would debug an
   application program.

   If you are having problems connecting or something is going seriously
   wrong while debugging, it will most often be the case that you want
   to enable gdb to be verbose about its target communications. You do
   this prior to issuing the ``target remote`` command by typing in::

	set debug remote 1

Remember if you continue in gdb, and need to "break in" again, you need
to issue an other :kbd:`SysRq-G`. It is easy to create a simple entry point by
putting a breakpoint at ``sys_sync`` and then you can run ``sync`` from a
shell or script to break into the debugger.

kgdb and kdb interoperability
=============================

It is possible to transition between kdb and kgdb dynamically. The debug
core will remember which you used the last time and automatically start
in the same mode.

Switching between kdb and kgdb
------------------------------

Switching from kgdb to kdb
~~~~~~~~~~~~~~~~~~~~~~~~~~

There are two ways to switch from kgdb to kdb: you can use gdb to issue
a maintenance packet, or you can blindly type the command ``$3#33``.
Whenever the kernel debugger stops in kgdb mode it will print the
message ``KGDB or $3#33 for KDB``. It is important to note that you have
to type the sequence correctly in one pass. You cannot type a backspace
or delete because kgdb will interpret that as part of the debug stream.

1. Change from kgdb to kdb by blindly typing::

	$3#33

2. Change from kgdb to kdb with gdb::

	maintenance packet 3

   .. note::

     Now you must kill gdb. Typically you press :kbd:`CTRL-Z` and issue
     the command::

	kill -9 %

Change from kdb to kgdb
~~~~~~~~~~~~~~~~~~~~~~~

There are two ways you can change from kdb to kgdb. You can manually
enter kgdb mode by issuing the kgdb command from the kdb shell prompt,
or you can connect gdb while the kdb shell prompt is active. The kdb
shell looks for the typical first commands that gdb would issue with the
gdb remote protocol and if it sees one of those commands it
automatically changes into kgdb mode.

1. From kdb issue the command::

	kgdb

   Now disconnect your terminal program and connect gdb in its place

2. At the kdb prompt, disconnect the terminal program and connect gdb in
   its place.

Running kdb commands from gdb
-----------------------------

It is possible to run a limited set of kdb commands from gdb, using the
gdb monitor command. You don't want to execute any of the run control or
breakpoint operations, because it can disrupt the state of the kernel
debugger. You should be using gdb for breakpoints and run control
operations if you have gdb connected. The more useful commands to run
are things like lsmod, dmesg, ps or possibly some of the memory
information commands. To see all the kdb commands you can run
``monitor help``.

Example::

    (gdb) monitor ps
    1 idle process (state I) and
    27 sleeping system daemon (state M) processes suppressed,
    use 'ps A' to see all.
    Task Addr       Pid   Parent [*] cpu State Thread     Command

    0xc78291d0        1        0  0    0   S  0xc7829404  init
    0xc7954150      942        1  0    0   S  0xc7954384  dropbear
    0xc78789c0      944        1  0    0   S  0xc7878bf4  sh
    (gdb)

kgdb Test Suite
===============

When kgdb is enabled in the kernel config you can also elect to enable
the config parameter ``KGDB_TESTS``. Turning this on will enable a special
kgdb I/O module which is designed to test the kgdb internal functions.

The kgdb tests are mainly intended for developers to test the kgdb
internals as well as a tool for developing a new kgdb architecture
specific implementation. These tests are not really for end users of the
Linux kernel. The primary source of documentation would be to look in
the ``drivers/misc/kgdbts.c`` file.

The kgdb test suite can also be configured at compile time to run the
core set of tests by setting the kernel config parameter
``KGDB_TESTS_ON_BOOT``. This particular option is aimed at automated
regression testing and does not require modifying the kernel boot config
arguments. If this is turned on, the kgdb test suite can be disabled by
specifying ``kgdbts=`` as a kernel boot argument.

Kernel Debugger Internals
=========================

Architecture Specifics
----------------------

The kernel debugger is organized into a number of components:

1. The debug core

   The debug core is found in ``kernel/debugger/debug_core.c``. It
   contains:

   -  A generic OS exception handler which includes sync'ing the
      processors into a stopped state on an multi-CPU system.

   -  The API to talk to the kgdb I/O drivers

   -  The API to make calls to the arch-specific kgdb implementation

   -  The logic to perform safe memory reads and writes to memory while
      using the debugger

   -  A full implementation for software breakpoints unless overridden
      by the arch

   -  The API to invoke either the kdb or kgdb frontend to the debug
      core.

   -  The structures and callback API for atomic kernel mode setting.

      .. note:: kgdboc is where the kms callbacks are invoked.

2. kgdb arch-specific implementation

   This implementation is generally found in ``arch/*/kernel/kgdb.c``. As
   an example, ``arch/x86/kernel/kgdb.c`` contains the specifics to
   implement HW breakpoint as well as the initialization to dynamically
   register and unregister for the trap handlers on this architecture.
   The arch-specific portion implements:

   -  contains an arch-specific trap catcher which invokes
      kgdb_handle_exception() to start kgdb about doing its work

   -  translation to and from gdb specific packet format to struct pt_regs

   -  Registration and unregistration of architecture specific trap
      hooks

   -  Any special exception handling and cleanup

   -  NMI exception handling and cleanup

   -  (optional) HW breakpoints

3. gdbstub frontend (aka kgdb)

   The gdbstub is located in ``kernel/debug/gdbstub.c``. It contains:

   -  All the logic to implement the gdb serial protocol

4. kdb frontend

   The kdb debugger shell is broken down into a number of components.
   The kdb core is located in kernel/debug/kdb. There are a number of
   helper functions in some of the other kernel components to make it
   possible for kdb to examine and report information about the kernel
   without taking locks that could cause a kernel deadlock. The kdb core
   contains implements the following functionality.

   -  A simple shell

   -  The kdb core command set

   -  A registration API to register additional kdb shell commands.

      -  A good example of a self-contained kdb module is the ``ftdump``
         command for dumping the ftrace buffer. See:
         ``kernel/trace/trace_kdb.c``

      -  For an example of how to dynamically register a new kdb command
         you can build the kdb_hello.ko kernel module from
         ``samples/kdb/kdb_hello.c``. To build this example you can set
         ``CONFIG_SAMPLES=y`` and ``CONFIG_SAMPLE_KDB=m`` in your kernel
         config. Later run ``modprobe kdb_hello`` and the next time you
         enter the kdb shell, you can run the ``hello`` command.

   -  The implementation for kdb_printf() which emits messages directly
      to I/O drivers, bypassing the kernel log.

   -  SW / HW breakpoint management for the kdb shell

5. kgdb I/O driver

   Each kgdb I/O driver has to provide an implementation for the
   following:

   -  configuration via built-in or module

   -  dynamic configuration and kgdb hook registration calls

   -  read and write character interface

   -  A cleanup handler for unconfiguring from the kgdb core

   -  (optional) Early debug methodology

   Any given kgdb I/O driver has to operate very closely with the
   hardware and must do it in such a way that does not enable interrupts
   or change other parts of the system context without completely
   restoring them. The kgdb core will repeatedly "poll" a kgdb I/O
   driver for characters when it needs input. The I/O driver is expected
   to return immediately if there is no data available. Doing so allows
   for the future possibility to touch watchdog hardware in such a way
   as to have a target system not reset when these are enabled.

If you are intent on adding kgdb architecture specific support for a new
architecture, the architecture should define ``HAVE_ARCH_KGDB`` in the
architecture specific Kconfig file. This will enable kgdb for the
architecture, and at that point you must create an architecture specific
kgdb implementation.

There are a few flags which must be set on every architecture in their
``asm/kgdb.h`` file. These are:

-  ``NUMREGBYTES``:
     The size in bytes of all of the registers, so that we
     can ensure they will all fit into a packet.

-  ``BUFMAX``:
     The size in bytes of the buffer GDB will read into. This must
     be larger than NUMREGBYTES.

-  ``CACHE_FLUSH_IS_SAFE``:
     Set to 1 if it is always safe to call
     flush_cache_range or flush_icache_range. On some architectures,
     these functions may not be safe to call on SMP since we keep other
     CPUs in a holding pattern.

There are also the following functions for the common backend, found in
``kernel/kgdb.c``, that must be supplied by the architecture-specific
backend unless marked as (optional), in which case a default function
maybe used if the architecture does not need to provide a specific
implementation.

.. kernel-doc:: include/linux/kgdb.h
   :internal:

kgdboc internals
----------------

kgdboc and uarts
~~~~~~~~~~~~~~~~

The kgdboc driver is actually a very thin driver that relies on the
underlying low level to the hardware driver having "polling hooks" to
which the tty driver is attached. In the initial implementation of
kgdboc the serial_core was changed to expose a low level UART hook for
doing polled mode reading and writing of a single character while in an
atomic context. When kgdb makes an I/O request to the debugger, kgdboc
invokes a callback in the serial core which in turn uses the callback in
the UART driver.

When using kgdboc with a UART, the UART driver must implement two
callbacks in the struct uart_ops.
Example from ``drivers/8250.c``::

    #ifdef CONFIG_CONSOLE_POLL
        .poll_get_char = serial8250_get_poll_char,
        .poll_put_char = serial8250_put_poll_char,
    #endif

Any implementation specifics around creating a polling driver use the
``#ifdef CONFIG_CONSOLE_POLL``, as shown above. Keep in mind that
polling hooks have to be implemented in such a way that they can be
called from an atomic context and have to restore the state of the UART
chip on return such that the system can return to normal when the
debugger detaches. You need to be very careful with any kind of lock you
consider, because failing here is most likely going to mean pressing the
reset button.

kgdboc and keyboards
~~~~~~~~~~~~~~~~~~~~~~~~

The kgdboc driver contains logic to configure communications with an
attached keyboard. The keyboard infrastructure is only compiled into the
kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.

The core polled keyboard driver for PS/2 type keyboards is in
``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core
when kgdboc populates the callback in the array called
:c:expr:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level
function which polls hardware for single character input.

kgdboc and kms
~~~~~~~~~~~~~~~~~~

The kgdboc driver contains logic to request the graphics display to
switch to a text context when you are using ``kgdboc=kms,kbd``, provided
that you have a video driver which has a frame buffer console and atomic
kernel mode setting support.

Every time the kernel debugger is entered it calls
kgdboc_pre_exp_handler() which in turn calls con_debug_enter()
in the virtual console layer. On resuming kernel execution, the kernel
debugger calls kgdboc_post_exp_handler() which in turn calls
con_debug_leave().

Any video driver that wants to be compatible with the kernel debugger
and the atomic kms callbacks must implement the ``mode_set_base_atomic``,
``fb_debug_enter`` and ``fb_debug_leave operations``. For the
``fb_debug_enter`` and ``fb_debug_leave`` the option exists to use the
generic drm fb helper functions or implement something custom for the
hardware. The following example shows the initialization of the
.mode_set_base_atomic operation in
drivers/gpu/drm/i915/intel_display.c::

    static const struct drm_crtc_helper_funcs intel_helper_funcs = {
    [...]
            .mode_set_base_atomic = intel_pipe_set_base_atomic,
    [...]
    };

Here is an example of how the i915 driver initializes the
fb_debug_enter and fb_debug_leave functions to use the generic drm
helpers in ``drivers/gpu/drm/i915/intel_fb.c``::

    static struct fb_ops intelfb_ops = {
    [...]
           .fb_debug_enter = drm_fb_helper_debug_enter,
           .fb_debug_leave = drm_fb_helper_debug_leave,
    [...]
    };

Credits
=======

The following people have contributed to this document:

1. Amit Kale <amitkale@linsyssoft.com>

2. Tom Rini <trini@kernel.crashing.org>

In March 2008 this document was completely rewritten by:

-  Jason Wessel <jason.wessel@windriver.com>

In Jan 2010 this document was updated to include kdb.

-  Jason Wessel <jason.wessel@windriver.com>


code:
Kernel Memory Leak Detector
===========================

Kmemleak provides a way of detecting possible kernel memory leaks in a
way similar to a `tracing garbage collector
<https://en.wikipedia.org/wiki/Tracing_garbage_collection>`_,
with the difference that the orphan objects are not freed but only
reported via /sys/kernel/debug/kmemleak. A similar method is used by the
Valgrind tool (``memcheck --leak-check``) to detect the memory leaks in
user-space applications.

Usage
-----

CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel
thread scans the memory every 10 minutes (by default) and prints the
number of new unreferenced objects found. If the ``debugfs`` isn't already
mounted, mount with::

  # mount -t debugfs nodev /sys/kernel/debug/

To display the details of all the possible scanned memory leaks::

  # cat /sys/kernel/debug/kmemleak

To trigger an intermediate memory scan::

  # echo scan > /sys/kernel/debug/kmemleak

To clear the list of all current possible memory leaks::

  # echo clear > /sys/kernel/debug/kmemleak

New leaks will then come up upon reading ``/sys/kernel/debug/kmemleak``
again.

Note that the orphan objects are listed in the order they were allocated
and one object at the beginning of the list may cause other subsequent
objects to be reported as orphan.

Memory scanning parameters can be modified at run-time by writing to the
``/sys/kernel/debug/kmemleak`` file. The following parameters are supported:

- off
    disable kmemleak (irreversible)
- stack=on
    enable the task stacks scanning (default)
- stack=off
    disable the tasks stacks scanning
- scan=on
    start the automatic memory scanning thread (default)
- scan=off
    stop the automatic memory scanning thread
- scan=<secs>
    set the automatic memory scanning period in seconds
    (default 600, 0 to stop the automatic scanning)
- scan
    trigger a memory scan
- clear
    clear list of current memory leak suspects, done by
    marking all current reported unreferenced objects grey,
    or free all kmemleak objects if kmemleak has been disabled.
- dump=<addr>
    dump information about the object found at <addr>

Kmemleak can also be disabled at boot-time by passing ``kmemleak=off`` on
the kernel command line.

Memory may be allocated or freed before kmemleak is initialised and
these actions are stored in an early log buffer. The size of this buffer
is configured via the CONFIG_DEBUG_KMEMLEAK_MEM_POOL_SIZE option.

If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is
disabled by default. Passing ``kmemleak=on`` on the kernel command
line enables the function.

If you are getting errors like "Error while writing to stdout" or "write_loop:
Invalid argument", make sure kmemleak is properly enabled.

Basic Algorithm
---------------

The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
:c:func:`kmem_cache_alloc` and
friends are traced and the pointers, together with additional
information like size and stack trace, are stored in a rbtree.
The corresponding freeing function calls are tracked and the pointers
removed from the kmemleak data structures.

An allocated block of memory is considered orphan if no pointer to its
start address or to any location inside the block can be found by
scanning the memory (including saved registers). This means that there
might be no way for the kernel to pass the address of the allocated
block to a freeing function and therefore the block is considered a
memory leak.

The scanning algorithm steps:

  1. mark all objects as white (remaining white objects will later be
     considered orphan)
  2. scan the memory starting with the data section and stacks, checking
     the values against the addresses stored in the rbtree. If
     a pointer to a white object is found, the object is added to the
     gray list
  3. scan the gray objects for matching addresses (some white objects
     can become gray and added at the end of the gray list) until the
     gray set is finished
  4. the remaining white objects are considered orphan and reported via
     /sys/kernel/debug/kmemleak

Some allocated memory blocks have pointers stored in the kernel's
internal data structures and they cannot be detected as orphans. To
avoid this, kmemleak can also store the number of values pointing to an
address inside the block address range that need to be found so that the
block is not considered a leak. One example is __vmalloc().

Testing specific sections with kmemleak
---------------------------------------

Upon initial bootup your /sys/kernel/debug/kmemleak output page may be
quite extensive. This can also be the case if you have very buggy code
when doing development. To work around these situations you can use the
'clear' command to clear all reported unreferenced objects from the
/sys/kernel/debug/kmemleak output. By issuing a 'scan' after a 'clear'
you can find new unreferenced objects; this should help with testing
specific sections of code.

To test a critical section on demand with a clean kmemleak do::

  # echo clear > /sys/kernel/debug/kmemleak
  ... test your kernel or modules ...
  # echo scan > /sys/kernel/debug/kmemleak

Then as usual to get your report with::

  # cat /sys/kernel/debug/kmemleak

Freeing kmemleak internal objects
---------------------------------

To allow access to previously found memory leaks after kmemleak has been
disabled by the user or due to an fatal error, internal kmemleak objects
won't be freed when kmemleak is disabled, and those objects may occupy
a large part of physical memory.

In this situation, you may reclaim memory with::

  # echo clear > /sys/kernel/debug/kmemleak

Kmemleak API
------------

See the include/linux/kmemleak.h header for the functions prototype.

- ``kmemleak_init``		 - initialize kmemleak
- ``kmemleak_alloc``		 - notify of a memory block allocation
- ``kmemleak_alloc_percpu``	 - notify of a percpu memory block allocation
- ``kmemleak_vmalloc``		 - notify of a vmalloc() memory allocation
- ``kmemleak_free``		 - notify of a memory block freeing
- ``kmemleak_free_part``	 - notify of a partial memory block freeing
- ``kmemleak_free_percpu``	 - notify of a percpu memory block freeing
- ``kmemleak_update_trace``	 - update object allocation stack trace
- ``kmemleak_not_leak``	 - mark an object as not a leak
- ``kmemleak_ignore``		 - do not scan or report an object as leak
- ``kmemleak_scan_area``	 - add scan areas inside a memory block
- ``kmemleak_no_scan``	 - do not scan a memory block
- ``kmemleak_erase``		 - erase an old value in a pointer variable
- ``kmemleak_alloc_recursive`` - as kmemleak_alloc but checks the recursiveness
- ``kmemleak_free_recursive``	 - as kmemleak_free but checks the recursiveness

The following functions take a physical address as the object pointer
and only perform the corresponding action if the address has a lowmem
mapping:

- ``kmemleak_alloc_phys``
- ``kmemleak_free_part_phys``
- ``kmemleak_ignore_phys``

Dealing with false positives/negatives
--------------------------------------

The false negatives are real memory leaks (orphan objects) but not
reported by kmemleak because values found during the memory scanning
point to such objects. To reduce the number of false negatives, kmemleak
provides the kmemleak_ignore, kmemleak_scan_area, kmemleak_no_scan and
kmemleak_erase functions (see above). The task stacks also increase the
amount of false negatives and their scanning is not enabled by default.

The false positives are objects wrongly reported as being memory leaks
(orphan). For objects known not to be leaks, kmemleak provides the
kmemleak_not_leak function. The kmemleak_ignore could also be used if
the memory block is known not to contain other pointers and it will no
longer be scanned.

Some of the reported leaks are only transient, especially on SMP
systems, because of pointers temporarily stored in CPU registers or
stacks. Kmemleak defines MSECS_MIN_AGE (defaulting to 1000) representing
the minimum age of an object to be reported as a memory leak.

Limitations and Drawbacks
-------------------------

The main drawback is the reduced performance of memory allocation and
freeing. To avoid other penalties, the memory scanning is only performed
when the /sys/kernel/debug/kmemleak file is read. Anyway, this tool is
intended for debugging purposes where the performance might not be the
most important requirement.

To keep the algorithm simple, kmemleak scans for values pointing to any
address inside a block's address range. This may lead to an increased
number of false negatives. However, it is likely that a real memory leak
will eventually become visible.

Another source of false negatives is the data stored in non-pointer
values. In a future version, kmemleak could only scan the pointer
members in the allocated structures. This feature would solve many of
the false negative cases described above.

The tool can report false positives. These are cases where an allocated
block doesn't need to be freed (some cases in the init_call functions),
the pointer is calculated by other methods than the usual container_of
macro or the pointer is stored in a location not scanned by kmemleak.

Page allocations and ioremap are not tracked.

Testing with kmemleak-test
--------------------------

To check if you have all set up to use kmemleak, you can use the kmemleak-test
module, a module that deliberately leaks memory. Set CONFIG_DEBUG_KMEMLEAK_TEST
as module (it can't be used as built-in) and boot the kernel with kmemleak
enabled. Load the module and perform a scan with::

        # modprobe kmemleak-test
        # echo scan > /sys/kernel/debug/kmemleak

Note that the you may not get results instantly or on the first scanning. When
kmemleak gets results, it'll log ``kmemleak: <count of leaks> new suspected
memory leaks``. Then read the file to see then::

        # cat /sys/kernel/debug/kmemleak
        unreferenced object 0xffff89862ca702e8 (size 32):
          comm "modprobe", pid 2088, jiffies 4294680594 (age 375.486s)
          hex dump (first 32 bytes):
            6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
            6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5  kkkkkkkkkkkkkkk.
          backtrace:
            [<00000000e0a73ec7>] 0xffffffffc01d2036
            [<000000000c5d2a46>] do_one_initcall+0x41/0x1df
            [<0000000046db7e0a>] do_init_module+0x55/0x200
            [<00000000542b9814>] load_module+0x203c/0x2480
            [<00000000c2850256>] __do_sys_finit_module+0xba/0xe0
            [<000000006564e7ef>] do_syscall_64+0x43/0x110
            [<000000007c873fa6>] entry_SYSCALL_64_after_hwframe+0x44/0xa9
        ...

Removing the module with ``rmmod kmemleak_test`` should also trigger some
kmemleak results.

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GPL-2.0
.. Copyright (C) 2022, Google LLC.

===================================
The Kernel Memory Sanitizer (KMSAN)
===================================

KMSAN is a dynamic error detector aimed at finding uses of uninitialized
values. It is based on compiler instrumentation, and is quite similar to the
userspace `MemorySanitizer tool`_.

An important note is that KMSAN is not intended for production use, because it
drastically increases kernel memory footprint and slows the whole system down.

Usage
=====

Building the kernel
-------------------

In order to build a kernel with KMSAN you will need a fresh Clang (14.0.6+).
Please refer to `LLVM documentation`_ for the instructions on how to build Clang.

Now configure and build the kernel with CONFIG_KMSAN enabled.

Example report
--------------

Here is an example of a KMSAN report::

  =====================================================
  BUG: KMSAN: uninit-value in test_uninit_kmsan_check_memory+0x1be/0x380 [kmsan_test]
   test_uninit_kmsan_check_memory+0x1be/0x380 mm/kmsan/kmsan_test.c:273
   kunit_run_case_internal lib/kunit/test.c:333
   kunit_try_run_case+0x206/0x420 lib/kunit/test.c:374
   kunit_generic_run_threadfn_adapter+0x6d/0xc0 lib/kunit/try-catch.c:28
   kthread+0x721/0x850 kernel/kthread.c:327
   ret_from_fork+0x1f/0x30 ??:?

  Uninit was stored to memory at:
   do_uninit_local_array+0xfa/0x110 mm/kmsan/kmsan_test.c:260
   test_uninit_kmsan_check_memory+0x1a2/0x380 mm/kmsan/kmsan_test.c:271
   kunit_run_case_internal lib/kunit/test.c:333
   kunit_try_run_case+0x206/0x420 lib/kunit/test.c:374
   kunit_generic_run_threadfn_adapter+0x6d/0xc0 lib/kunit/try-catch.c:28
   kthread+0x721/0x850 kernel/kthread.c:327
   ret_from_fork+0x1f/0x30 ??:?

  Local variable uninit created at:
   do_uninit_local_array+0x4a/0x110 mm/kmsan/kmsan_test.c:256
   test_uninit_kmsan_check_memory+0x1a2/0x380 mm/kmsan/kmsan_test.c:271

  Bytes 4-7 of 8 are uninitialized
  Memory access of size 8 starts at ffff888083fe3da0

  CPU: 0 PID: 6731 Comm: kunit_try_catch Tainted: G    B       E     5.16.0-rc3+ #104
  Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014
  =====================================================

The report says that the local variable ``uninit`` was created uninitialized in
``do_uninit_local_array()``. The third stack trace corresponds to the place
where this variable was created.

The first stack trace shows where the uninit value was used (in
``test_uninit_kmsan_check_memory()``). The tool shows the bytes which were left
uninitialized in the local variable, as well as the stack where the value was
copied to another memory location before use.

A use of uninitialized value ``v`` is reported by KMSAN in the following cases:

 - in a condition, e.g. ``if (v) { ... }``;
 - in an indexing or pointer dereferencing, e.g. ``array[v]`` or ``*v``;
 - when it is copied to userspace or hardware, e.g. ``copy_to_user(..., &v, ...)``;
 - when it is passed as an argument to a function, and
   ``CONFIG_KMSAN_CHECK_PARAM_RETVAL`` is enabled (see below).

The mentioned cases (apart from copying data to userspace or hardware, which is
a security issue) are considered undefined behavior from the C11 Standard point
of view.

Disabling the instrumentation
-----------------------------

A function can be marked with ``__no_kmsan_checks``. Doing so makes KMSAN
ignore uninitialized values in that function and mark its output as initialized.
As a result, the user will not get KMSAN reports related to that function.

Another function attribute supported by KMSAN is ``__no_sanitize_memory``.
Applying this attribute to a function will result in KMSAN not instrumenting
it, which can be helpful if we do not want the compiler to interfere with some
low-level code (e.g. that marked with ``noinstr`` which implicitly adds
``__no_sanitize_memory``).

This however comes at a cost: stack allocations from such functions will have
incorrect shadow/origin values, likely leading to false positives. Functions
called from non-instrumented code may also receive incorrect metadata for their
parameters.

As a rule of thumb, avoid using ``__no_sanitize_memory`` explicitly.

It is also possible to disable KMSAN for a single file (e.g. main.o)::

  KMSAN_SANITIZE_main.o := n

or for the whole directory::

  KMSAN_SANITIZE := n

in the Makefile. Think of this as applying ``__no_sanitize_memory`` to every
function in the file or directory. Most users won't need KMSAN_SANITIZE, unless
their code gets broken by KMSAN (e.g. runs at early boot time).

Support
=======

In order for KMSAN to work the kernel must be built with Clang, which so far is
the only compiler that has KMSAN support. The kernel instrumentation pass is
based on the userspace `MemorySanitizer tool`_.

The runtime library only supports x86_64 at the moment.

How KMSAN works
===============

KMSAN shadow memory
-------------------

KMSAN associates a metadata byte (also called shadow byte) with every byte of
kernel memory. A bit in the shadow byte is set iff the corresponding bit of the
kernel memory byte is uninitialized. Marking the memory uninitialized (i.e.
setting its shadow bytes to ``0xff``) is called poisoning, marking it
initialized (setting the shadow bytes to ``0x00``) is called unpoisoning.

When a new variable is allocated on the stack, it is poisoned by default by
instrumentation code inserted by the compiler (unless it is a stack variable
that is immediately initialized). Any new heap allocation done without
``__GFP_ZERO`` is also poisoned.

Compiler instrumentation also tracks the shadow values as they are used along
the code. When needed, instrumentation code invokes the runtime library in
``mm/kmsan/`` to persist shadow values.

The shadow value of a basic or compound type is an array of bytes of the same
length. When a constant value is written into memory, that memory is unpoisoned.
When a value is read from memory, its shadow memory is also obtained and
propagated into all the operations which use that value. For every instruction
that takes one or more values the compiler generates code that calculates the
shadow of the result depending on those values and their shadows.

Example::

  int a = 0xff;  // i.e. 0x000000ff
  int b;
  int c = a | b;

In this case the shadow of ``a`` is ``0``, shadow of ``b`` is ``0xffffffff``,
shadow of ``c`` is ``0xffffff00``. This means that the upper three bytes of
``c`` are uninitialized, while the lower byte is initialized.

Origin tracking
---------------

Every four bytes of kernel memory also have a so-called origin mapped to them.
This origin describes the point in program execution at which the uninitialized
value was created. Every origin is associated with either the full allocation
stack (for heap-allocated memory), or the function containing the uninitialized
variable (for locals).

When an uninitialized variable is allocated on stack or heap, a new origin
value is created, and that variable's origin is filled with that value. When a
value is read from memory, its origin is also read and kept together with the
shadow. For every instruction that takes one or more values, the origin of the
result is one of the origins corresponding to any of the uninitialized inputs.
If a poisoned value is written into memory, its origin is written to the
corresponding storage as well.

Example 1::

  int a = 42;
  int b;
  int c = a + b;

In this case the origin of ``b`` is generated upon function entry, and is
stored to the origin of ``c`` right before the addition result is written into
memory.

Several variables may share the same origin address, if they are stored in the
same four-byte chunk. In this case every write to either variable updates the
origin for all of them. We have to sacrifice precision in this case, because
storing origins for individual bits (and even bytes) would be too costly.

Example 2::

  int combine(short a, short b) {
    union ret_t {
      int i;
      short s[2];
    } ret;
    ret.s[0] = a;
    ret.s[1] = b;
    return ret.i;
  }

If ``a`` is initialized and ``b`` is not, the shadow of the result would be
0xffff0000, and the origin of the result would be the origin of ``b``.
``ret.s[0]`` would have the same origin, but it will never be used, because
that variable is initialized.

If both function arguments are uninitialized, only the origin of the second
argument is preserved.

Origin chaining
~~~~~~~~~~~~~~~

To ease debugging, KMSAN creates a new origin for every store of an
uninitialized value to memory. The new origin references both its creation stack
and the previous origin the value had. This may cause increased memory
consumption, so we limit the length of origin chains in the runtime.

Clang instrumentation API
-------------------------

Clang instrumentation pass inserts calls to functions defined in
``mm/kmsan/nstrumentation.c`` into the kernel code.

Shadow manipulation
~~~~~~~~~~~~~~~~~~~

For every memory access the compiler emits a call to a function that returns a
pair of pointers to the shadow and origin addresses of the given memory::

  typedef struct {
    void *shadow, *origin;
  } shadow_origin_ptr_t

  shadow_origin_ptr_t __msan_metadata_ptr_for_load_{1,2,4,8}(void *addr)
  shadow_origin_ptr_t __msan_metadata_ptr_for_store_{1,2,4,8}(void *addr)
  shadow_origin_ptr_t __msan_metadata_ptr_for_load_n(void *addr, uintptr_t size)
  shadow_origin_ptr_t __msan_metadata_ptr_for_store_n(void *addr, uintptr_t size)

The function name depends on the memory access size.

The compiler makes sure that for every loaded value its shadow and origin
values are read from memory. When a value is stored to memory, its shadow and
origin are also stored using the metadata pointers.

Handling locals
~~~~~~~~~~~~~~~

A special function is used to create a new origin value for a local variable and
set the origin of that variable to that value::

  void __msan_poison_alloca(void *addr, uintptr_t size, char *descr)

Access to per-task data
~~~~~~~~~~~~~~~~~~~~~~~

At the beginning of every instrumented function KMSAN inserts a call to
``__msan_get_context_state()``::

  kmsan_context_state *__msan_get_context_state(void)

``kmsan_context_state`` is declared in ``include/linux/kmsan.h``::

  struct kmsan_context_state {
    char param_tls[KMSAN_PARAM_SIZE];
    char retval_tls[KMSAN_RETVAL_SIZE];
    char va_arg_tls[KMSAN_PARAM_SIZE];
    char va_arg_origin_tls[KMSAN_PARAM_SIZE];
    u64 va_arg_overflow_size_tls;
    char param_origin_tls[KMSAN_PARAM_SIZE];
    depot_stack_handle_t retval_origin_tls;
  };

This structure is used by KMSAN to pass parameter shadows and origins between
instrumented functions (unless the parameters are checked immediately by
``CONFIG_KMSAN_CHECK_PARAM_RETVAL``).

Passing uninitialized values to functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Clang's MemorySanitizer instrumentation has an option,
``-fsanitize-memory-param-retval``, which makes the compiler check function
parameters passed by value, as well as function return values.

The option is controlled by ``CONFIG_KMSAN_CHECK_PARAM_RETVAL``, which is
enabled by default to let KMSAN report uninitialized values earlier.
Please refer to the `LKML discussion`_ for more details.

Because of the way the checks are implemented in LLVM (they are only applied to
parameters marked as ``noundef``), not all parameters are guaranteed to be
checked, so we cannot give up the metadata storage in ``kmsan_context_state``.

String functions
~~~~~~~~~~~~~~~~

The compiler replaces calls to ``memcpy()``/``memmove()``/``memset()`` with the
following functions. These functions are also called when data structures are
initialized or copied, making sure shadow and origin values are copied alongside
with the data::

  void *__msan_memcpy(void *dst, void *src, uintptr_t n)
  void *__msan_memmove(void *dst, void *src, uintptr_t n)
  void *__msan_memset(void *dst, int c, uintptr_t n)

Error reporting
~~~~~~~~~~~~~~~

For each use of a value the compiler emits a shadow check that calls
``__msan_warning()`` in the case that value is poisoned::

  void __msan_warning(u32 origin)

``__msan_warning()`` causes KMSAN runtime to print an error report.

Inline assembly instrumentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

KMSAN instruments every inline assembly output with a call to::

  void __msan_instrument_asm_store(void *addr, uintptr_t size)

, which unpoisons the memory region.

This approach may mask certain errors, but it also helps to avoid a lot of
false positives in bitwise operations, atomics etc.

Sometimes the pointers passed into inline assembly do not point to valid memory.
In such cases they are ignored at runtime.

Runtime library
---------------

The code is located in ``mm/kmsan/``.

Per-task KMSAN state
~~~~~~~~~~~~~~~~~~~~

Every task_struct has an associated KMSAN task state that holds the KMSAN
context (see above) and a per-task flag disallowing KMSAN reports::

  struct kmsan_context {
    ...
    bool allow_reporting;
    struct kmsan_context_state cstate;
    ...
  }

  struct task_struct {
    ...
    struct kmsan_context kmsan;
    ...
  }

KMSAN contexts
~~~~~~~~~~~~~~

When running in a kernel task context, KMSAN uses ``current->kmsan.cstate`` to
hold the metadata for function parameters and return values.

But in the case the kernel is running in the interrupt, softirq or NMI context,
where ``current`` is unavailable, KMSAN switches to per-cpu interrupt state::

  DEFINE_PER_CPU(struct kmsan_ctx, kmsan_percpu_ctx);

Metadata allocation
~~~~~~~~~~~~~~~~~~~

There are several places in the kernel for which the metadata is stored.

1. Each ``struct page`` instance contains two pointers to its shadow and
origin pages::

  struct page {
    ...
    struct page *shadow, *origin;
    ...
  };

At boot-time, the kernel allocates shadow and origin pages for every available
kernel page. This is done quite late, when the kernel address space is already
fragmented, so normal data pages may arbitrarily interleave with the metadata
pages.

This means that in general for two contiguous memory pages their shadow/origin
pages may not be contiguous. Consequently, if a memory access crosses the
boundary of a memory block, accesses to shadow/origin memory may potentially
corrupt other pages or read incorrect values from them.

In practice, contiguous memory pages returned by the same ``alloc_pages()``
call will have contiguous metadata, whereas if these pages belong to two
different allocations their metadata pages can be fragmented.

For the kernel data (``.data``, ``.bss`` etc.) and percpu memory regions
there also are no guarantees on metadata contiguity.

In the case ``__msan_metadata_ptr_for_XXX_YYY()`` hits the border between two
pages with non-contiguous metadata, it returns pointers to fake shadow/origin regions::

  char dummy_load_page[PAGE_SIZE] __attribute__((aligned(PAGE_SIZE)));
  char dummy_store_page[PAGE_SIZE] __attribute__((aligned(PAGE_SIZE)));

``dummy_load_page`` is zero-initialized, so reads from it always yield zeroes.
All stores to ``dummy_store_page`` are ignored.

2. For vmalloc memory and modules, there is a direct mapping between the memory
range, its shadow and origin. KMSAN reduces the vmalloc area by 3/4, making only
the first quarter available to ``vmalloc()``. The second quarter of the vmalloc
area contains shadow memory for the first quarter, the third one holds the
origins. A small part of the fourth quarter contains shadow and origins for the
kernel modules. Please refer to ``arch/x86/include/asm/pgtable_64_types.h`` for
more details.

When an array of pages is mapped into a contiguous virtual memory space, their
shadow and origin pages are similarly mapped into contiguous regions.

References
==========

E. Stepanov, K. Serebryany. `MemorySanitizer: fast detector of uninitialized
memory use in C++
<https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/43308.pdf>`_.
In Proceedings of CGO 2015.

.. _MemorySanitizer tool: https://clang.llvm.org/docs/MemorySanitizer.html
.. _LLVM documentation: https://llvm.org/docs/GettingStarted.html
.. _LKML discussion: https://lore.kernel.org/all/20220614144853.3693273-1-glider@google.com/


code:
======================
Linux Kernel Selftests
======================

The kernel contains a set of "self tests" under the tools/testing/selftests/
directory. These are intended to be small tests to exercise individual code
paths in the kernel. Tests are intended to be run after building, installing
and booting a kernel.

Kselftest from mainline can be run on older stable kernels. Running tests
from mainline offers the best coverage. Several test rings run mainline
kselftest suite on stable releases. The reason is that when a new test
gets added to test existing code to regression test a bug, we should be
able to run that test on an older kernel. Hence, it is important to keep
code that can still test an older kernel and make sure it skips the test
gracefully on newer releases.

You can find additional information on Kselftest framework, how to
write new tests using the framework on Kselftest wiki:

https://kselftest.wiki.kernel.org/

On some systems, hot-plug tests could hang forever waiting for cpu and
memory to be ready to be offlined. A special hot-plug target is created
to run the full range of hot-plug tests. In default mode, hot-plug tests run
in safe mode with a limited scope. In limited mode, cpu-hotplug test is
run on a single cpu as opposed to all hotplug capable cpus, and memory
hotplug test is run on 2% of hotplug capable memory instead of 10%.

kselftest runs as a userspace process.  Tests that can be written/run in
userspace may wish to use the `Test Harness`_.  Tests that need to be
run in kernel space may wish to use a `Test Module`_.

Running the selftests (hotplug tests are run in limited mode)
=============================================================

To build the tests::

  $ make -C tools/testing/selftests

To run the tests::

  $ make -C tools/testing/selftests run_tests

To build and run the tests with a single command, use::

  $ make kselftest

Note that some tests will require root privileges.

Kselftest supports saving output files in a separate directory and then
running tests. To locate output files in a separate directory two syntaxes
are supported. In both cases the working directory must be the root of the
kernel src. This is applicable to "Running a subset of selftests" section
below.

To build, save output files in a separate directory with O= ::

  $ make O=/tmp/kselftest kselftest

To build, save output files in a separate directory with KBUILD_OUTPUT ::

  $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest

The O= assignment takes precedence over the KBUILD_OUTPUT environment
variable.

The above commands by default run the tests and print full pass/fail report.
Kselftest supports "summary" option to make it easier to understand the test
results. Please find the detailed individual test results for each test in
/tmp/testname file(s) when summary option is specified. This is applicable
to "Running a subset of selftests" section below.

To run kselftest with summary option enabled ::

  $ make summary=1 kselftest

Running a subset of selftests
=============================

You can use the "TARGETS" variable on the make command line to specify
single test to run, or a list of tests to run.

To run only tests targeted for a single subsystem::

  $ make -C tools/testing/selftests TARGETS=ptrace run_tests

You can specify multiple tests to build and run::

  $  make TARGETS="size timers" kselftest

To build, save output files in a separate directory with O= ::

  $ make O=/tmp/kselftest TARGETS="size timers" kselftest

To build, save output files in a separate directory with KBUILD_OUTPUT ::

  $ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest

Additionally you can use the "SKIP_TARGETS" variable on the make command
line to specify one or more targets to exclude from the TARGETS list.

To run all tests but a single subsystem::

  $ make -C tools/testing/selftests SKIP_TARGETS=ptrace run_tests

You can specify multiple tests to skip::

  $  make SKIP_TARGETS="size timers" kselftest

You can also specify a restricted list of tests to run together with a
dedicated skiplist::

  $  make TARGETS="bpf breakpoints size timers" SKIP_TARGETS=bpf kselftest

See the top-level tools/testing/selftests/Makefile for the list of all
possible targets.

Running the full range hotplug selftests
========================================

To build the hotplug tests::

  $ make -C tools/testing/selftests hotplug

To run the hotplug tests::

  $ make -C tools/testing/selftests run_hotplug

Note that some tests will require root privileges.

Install selftests
=================

You can use the "install" target of "make" (which calls the `kselftest_install.sh`
tool) to install selftests in the default location (`tools/testing/selftests/kselftest_install`),
or in a user specified location via the `INSTALL_PATH` "make" variable.

To install selftests in default location::

   $ make -C tools/testing/selftests install

To install selftests in a user specified location::

   $ make -C tools/testing/selftests install INSTALL_PATH=/some/other/path

Running installed selftests
===========================

Found in the install directory, as well as in the Kselftest tarball,
is a script named `run_kselftest.sh` to run the tests.

You can simply do the following to run the installed Kselftests. Please
note some tests will require root privileges::

   $ cd kselftest_install
   $ ./run_kselftest.sh

To see the list of available tests, the `-l` option can be used::

   $ ./run_kselftest.sh -l

The `-c` option can be used to run all the tests from a test collection, or
the `-t` option for specific single tests. Either can be used multiple times::

   $ ./run_kselftest.sh -c bpf -c seccomp -t timers:posix_timers -t timer:nanosleep

For other features see the script usage output, seen with the `-h` option.

Packaging selftests
===================

In some cases packaging is desired, such as when tests need to run on a
different system. To package selftests, run::

   $ make -C tools/testing/selftests gen_tar

This generates a tarball in the `INSTALL_PATH/kselftest-packages` directory. By
default, `.gz` format is used. The tar compression format can be overridden by
specifying a `FORMAT` make variable. Any value recognized by `tar's auto-compress`_
option is supported, such as::

    $ make -C tools/testing/selftests gen_tar FORMAT=.xz

`make gen_tar` invokes `make install` so you can use it to package a subset of
tests by using variables specified in `Running a subset of selftests`_
section::

    $ make -C tools/testing/selftests gen_tar TARGETS="bpf" FORMAT=.xz

.. _tar's auto-compress: https://www.gnu.org/software/tar/manual/html_node/gzip.html#auto_002dcompress

Contributing new tests
======================

In general, the rules for selftests are

 * Do as much as you can if you're not root;

 * Don't take too long;

 * Don't break the build on any architecture, and

 * Don't cause the top-level "make run_tests" to fail if your feature is
   unconfigured.

Contributing new tests (details)
================================

 * In your Makefile, use facilities from lib.mk by including it instead of
   reinventing the wheel. Specify flags and binaries generation flags on
   need basis before including lib.mk. ::

    CFLAGS = $(KHDR_INCLUDES)
    TEST_GEN_PROGS := close_range_test
    include ../lib.mk

 * Use TEST_GEN_XXX if such binaries or files are generated during
   compiling.

   TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by
   default.

   TEST_CUSTOM_PROGS should be used by tests that require custom build
   rules and prevent common build rule use.

   TEST_PROGS are for test shell scripts. Please ensure shell script has
   its exec bit set. Otherwise, lib.mk run_tests will generate a warning.

   TEST_CUSTOM_PROGS and TEST_PROGS will be run by common run_tests.

   TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the
   executable which is not tested by default.
   TEST_FILES, TEST_GEN_FILES mean it is the file which is used by
   test.

 * First use the headers inside the kernel source and/or git repo, and then the
   system headers.  Headers for the kernel release as opposed to headers
   installed by the distro on the system should be the primary focus to be able
   to find regressions. Use KHDR_INCLUDES in Makefile to include headers from
   the kernel source.

 * If a test needs specific kernel config options enabled, add a config file in
   the test directory to enable them.

   e.g: tools/testing/selftests/android/config

 * Create a .gitignore file inside test directory and add all generated objects
   in it.

 * Add new test name in TARGETS in selftests/Makefile::

    TARGETS += android

 * All changes should pass::

    kselftest-{all,install,clean,gen_tar}
    kselftest-{all,install,clean,gen_tar} O=abo_path
    kselftest-{all,install,clean,gen_tar} O=rel_path
    make -C tools/testing/selftests {all,install,clean,gen_tar}
    make -C tools/testing/selftests {all,install,clean,gen_tar} O=abs_path
    make -C tools/testing/selftests {all,install,clean,gen_tar} O=rel_path

Test Module
===========

Kselftest tests the kernel from userspace.  Sometimes things need
testing from within the kernel, one method of doing this is to create a
test module.  We can tie the module into the kselftest framework by
using a shell script test runner.  ``kselftest/module.sh`` is designed
to facilitate this process.  There is also a header file provided to
assist writing kernel modules that are for use with kselftest:

- ``tools/testing/selftests/kselftest_module.h``
- ``tools/testing/selftests/kselftest/module.sh``

Note that test modules should taint the kernel with TAINT_TEST. This will
happen automatically for modules which are in the ``tools/testing/``
directory, or for modules which use the ``kselftest_module.h`` header above.
Otherwise, you'll need to add ``MODULE_INFO(test, "Y")`` to your module
source. selftests which do not load modules typically should not taint the
kernel, but in cases where a non-test module is loaded, TEST_TAINT can be
applied from userspace by writing to ``/proc/sys/kernel/tainted``.

How to use
----------

Here we show the typical steps to create a test module and tie it into
kselftest.  We use kselftests for lib/ as an example.

1. Create the test module

2. Create the test script that will run (load/unload) the module
   e.g. ``tools/testing/selftests/lib/printf.sh``

3. Add line to config file e.g. ``tools/testing/selftests/lib/config``

4. Add test script to makefile  e.g. ``tools/testing/selftests/lib/Makefile``

5. Verify it works:

.. code-block:: sh

   # Assumes you have booted a fresh build of this kernel tree
   cd /path/to/linux/tree
   make kselftest-merge
   make modules
   sudo make modules_install
   make TARGETS=lib kselftest

Example Module
--------------

A bare bones test module might look like this:

.. code-block:: c

   // SPDX-License-Identifier: GPL-2.0+

   #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt

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

   KSTM_MODULE_GLOBALS();

   /*
    * Kernel module for testing the foobinator
    */

   static int __init test_function()
   {
           ...
   }

   static void __init selftest(void)
   {
           KSTM_CHECK_ZERO(do_test_case("", 0));
   }

   KSTM_MODULE_LOADERS(test_foo);
   MODULE_AUTHOR("John Developer <jd@fooman.org>");
   MODULE_LICENSE("GPL");
   MODULE_INFO(test, "Y");

Example test script
-------------------

.. code-block:: sh

    #!/bin/bash
    # SPDX-License-Identifier: GPL-2.0+
    $(dirname $0)/../kselftest/module.sh "foo" test_foo

Test Harness
============

The kselftest_harness.h file contains useful helpers to build tests.  The
test harness is for userspace testing, for kernel space testing see `Test
Module`_ above.

The tests from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as
example.

Example
-------

.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
    :doc: example

Helpers
-------

.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
    :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP
                FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN FIXTURE_VARIANT
                FIXTURE_VARIANT_ADD

Operators
---------

.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
    :doc: operators

.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
    :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE
                ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE
                ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT
                EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE
                EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE


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

===================================================
The Kernel Test Anything Protocol (KTAP), version 1
===================================================

TAP, or the Test Anything Protocol is a format for specifying test results used
by a number of projects. It's website and specification are found at this `link
<https://testanything.org/>`_. The Linux Kernel largely uses TAP output for test
results. However, Kernel testing frameworks have special needs for test results
which don't align with the original TAP specification. Thus, a "Kernel TAP"
(KTAP) format is specified to extend and alter TAP to support these use-cases.
This specification describes the generally accepted format of KTAP as it is
currently used in the kernel.

KTAP test results describe a series of tests (which may be nested: i.e., test
can have subtests), each of which can contain both diagnostic data -- e.g., log
lines -- and a final result. The test structure and results are
machine-readable, whereas the diagnostic data is unstructured and is there to
aid human debugging.

KTAP output is built from four different types of lines:
- Version lines
- Plan lines
- Test case result lines
- Diagnostic lines

In general, valid KTAP output should also form valid TAP output, but some
information, in particular nested test results, may be lost. Also note that
there is a stagnant draft specification for TAP14, KTAP diverges from this in
a couple of places (notably the "Subtest" header), which are described where
relevant later in this document.

Version lines
-------------

All KTAP-formatted results begin with a "version line" which specifies which
version of the (K)TAP standard the result is compliant with.

For example:
- "KTAP version 1"
- "TAP version 13"
- "TAP version 14"

Note that, in KTAP, subtests also begin with a version line, which denotes the
start of the nested test results. This differs from TAP14, which uses a
separate "Subtest" line.

While, going forward, "KTAP version 1" should be used by compliant tests, it
is expected that most parsers and other tooling will accept the other versions
listed here for compatibility with existing tests and frameworks.

Plan lines
----------

A test plan provides the number of tests (or subtests) in the KTAP output.

Plan lines must follow the format of "1..N" where N is the number of tests or subtests.
Plan lines follow version lines to indicate the number of nested tests.

While there are cases where the number of tests is not known in advance -- in
which case the test plan may be omitted -- it is strongly recommended one is
present where possible.

Test case result lines
----------------------

Test case result lines indicate the final status of a test.
They are required and must have the format:

.. code-block:: none

	<result> <number> [<description>][ # [<directive>] [<diagnostic data>]]

The result can be either "ok", which indicates the test case passed,
or "not ok", which indicates that the test case failed.

<number> represents the number of the test being performed. The first test must
have the number 1 and the number then must increase by 1 for each additional
subtest within the same test at the same nesting level.

The description is a description of the test, generally the name of
the test, and can be any string of characters other than # or a
newline.  The description is optional, but recommended.

The directive and any diagnostic data is optional. If either are present, they
must follow a hash sign, "#".

A directive is a keyword that indicates a different outcome for a test other
than passed and failed. The directive is optional, and consists of a single
keyword preceding the diagnostic data. In the event that a parser encounters
a directive it doesn't support, it should fall back to the "ok" / "not ok"
result.

Currently accepted directives are:

- "SKIP", which indicates a test was skipped (note the result of the test case
  result line can be either "ok" or "not ok" if the SKIP directive is used)
- "TODO", which indicates that a test is not expected to pass at the moment,
  e.g. because the feature it is testing is known to be broken. While this
  directive is inherited from TAP, its use in the kernel is discouraged.
- "XFAIL", which indicates that a test is expected to fail. This is similar
  to "TODO", above, and is used by some kselftest tests.
- “TIMEOUT”, which indicates a test has timed out (note the result of the test
  case result line should be “not ok” if the TIMEOUT directive is used)
- “ERROR”, which indicates that the execution of a test has failed due to a
  specific error that is included in the diagnostic data. (note the result of
  the test case result line should be “not ok” if the ERROR directive is used)

The diagnostic data is a plain-text field which contains any additional details
about why this result was produced. This is typically an error message for ERROR
or failed tests, or a description of missing dependencies for a SKIP result.

The diagnostic data field is optional, and results which have neither a
directive nor any diagnostic data do not need to include the "#" field
separator.

Example result lines include::

	ok 1 test_case_name

The test "test_case_name" passed.

::

	not ok 1 test_case_name

The test "test_case_name" failed.

::

	ok 1 test # SKIP necessary dependency unavailable

The test "test" was SKIPPED with the diagnostic message "necessary dependency
unavailable".

::

	not ok 1 test # TIMEOUT 30 seconds

The test "test" timed out, with diagnostic data "30 seconds".

::

	ok 5 check return code # rcode=0

The test "check return code" passed, with additional diagnostic data “rcode=0”

Diagnostic lines
----------------

If tests wish to output any further information, they should do so using
"diagnostic lines". Diagnostic lines are optional, freeform text, and are
often used to describe what is being tested and any intermediate results in
more detail than the final result and diagnostic data line provides.

Diagnostic lines are formatted as "# <diagnostic_description>", where the
description can be any string.  Diagnostic lines can be anywhere in the test
output. As a rule, diagnostic lines regarding a test are directly before the
test result line for that test.

Note that most tools will treat unknown lines (see below) as diagnostic lines,
even if they do not start with a "#": this is to capture any other useful
kernel output which may help debug the test. It is nevertheless recommended
that tests always prefix any diagnostic output they have with a "#" character.

Unknown lines
-------------

There may be lines within KTAP output that do not follow the format of one of
the four formats for lines described above. This is allowed, however, they will
not influence the status of the tests.

This is an important difference from TAP.  Kernel tests may print messages
to the system console or a log file.  Both of these destinations may contain
messages either from unrelated kernel or userspace activity, or kernel
messages from non-test code that is invoked by the test.  The kernel code
invoked by the test likely is not aware that a test is in progress and
thus can not print the message as a diagnostic message.

Nested tests
------------

In KTAP, tests can be nested. This is done by having a test include within its
output an entire set of KTAP-formatted results. This can be used to categorize
and group related tests, or to split out different results from the same test.

The "parent" test's result should consist of all of its subtests' results,
starting with another KTAP version line and test plan, and end with the overall
result. If one of the subtests fail, for example, the parent test should also
fail.

Additionally, all lines in a subtest should be indented. One level of
indentation is two spaces: "  ". The indentation should begin at the version
line and should end before the parent test's result line.

"Unknown lines" are not considered to be lines in a subtest and thus are
allowed to be either indented or not indented.

An example of a test with two nested subtests:

::

	KTAP version 1
	1..1
	  KTAP version 1
	  1..2
	  ok 1 test_1
	  not ok 2 test_2
	# example failed
	not ok 1 example

An example format with multiple levels of nested testing:

::

	KTAP version 1
	1..2
	  KTAP version 1
	  1..2
	    KTAP version 1
	    1..2
	    not ok 1 test_1
	    ok 2 test_2
	  not ok 1 test_3
	  ok 2 test_4 # SKIP
	not ok 1 example_test_1
	ok 2 example_test_2

Major differences between TAP and KTAP
--------------------------------------

==================================================   =========  ===============
Feature                                              TAP        KTAP
==================================================   =========  ===============
yaml and json in diagnosic message                   ok         not recommended
TODO directive                                       ok         not recognized
allows an arbitrary number of tests to be nested     no         yes
"Unknown lines" are in category of "Anything else"   yes        no
"Unknown lines" are                                  incorrect  allowed
==================================================   =========  ===============

The TAP14 specification does permit nested tests, but instead of using another
nested version line, uses a line of the form
"Subtest: <name>" where <name> is the name of the parent test.

Example KTAP output
--------------------
::

	KTAP version 1
	1..1
	  KTAP version 1
	  1..3
	    KTAP version 1
	    1..1
	    # test_1: initializing test_1
	    ok 1 test_1
	  ok 1 example_test_1
	    KTAP version 1
	    1..2
	    ok 1 test_1 # SKIP test_1 skipped
	    ok 2 test_2
	  ok 2 example_test_2
	    KTAP version 1
	    1..3
	    ok 1 test_1
	    # test_2: FAIL
	    not ok 2 test_2
	    ok 3 test_3 # SKIP test_3 skipped
	  not ok 3 example_test_3
	not ok 1 main_test

This output defines the following hierarchy:

A single test called "main_test", which fails, and has three subtests:
- "example_test_1", which passes, and has one subtest:

   - "test_1", which passes, and outputs the diagnostic message "test_1: initializing test_1"

- "example_test_2", which passes, and has two subtests:

   - "test_1", which is skipped, with the explanation "test_1 skipped"
   - "test_2", which passes

- "example_test_3", which fails, and has three subtests

   - "test_1", which passes
   - "test_2", which outputs the diagnostic line "test_2: FAIL", and fails.
   - "test_3", which is skipped with the explanation "test_3 skipped"

Note that the individual subtests with the same names do not conflict, as they
are found in different parent tests. This output also exhibits some sensible
rules for "bubbling up" test results: a test fails if any of its subtests fail.
Skipped tests do not affect the result of the parent test (though it often
makes sense for a test to be marked skipped if _all_ of its subtests have been
skipped).

See also:
---------

- The TAP specification:
  https://testanything.org/tap-version-13-specification.html
- The (stagnant) TAP version 14 specification:
  https://github.com/TestAnything/Specification/blob/tap-14-specification/specification.md
- The kselftest documentation:
  Documentation/dev-tools/kselftest.rst
- The KUnit documentation:
  Documentation/dev-tools/kunit/index.rst


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

=============
API Reference
=============
.. toctree::

	test
	resource

This section documents the KUnit kernel testing API. It is divided into the
following sections:

Documentation/dev-tools/kunit/api/test.rst

 - documents all of the standard testing API

Documentation/dev-tools/kunit/api/resource.rst

 - documents the KUnit resource API


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

============
Resource API
============

This file documents the KUnit resource API.

Most users won't need to use this API directly, power users can use it to store
state on a per-test basis, register custom cleanup actions, and more.

.. kernel-doc:: include/kunit/resource.h
   :internal:


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

========
Test API
========

This file documents all of the standard testing API.

.. kernel-doc:: include/kunit/test.h
   :internal:


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

==================
KUnit Architecture
==================

The KUnit architecture is divided into two parts:

- `In-Kernel Testing Framework`_
- `kunit_tool (Command-line Test Harness)`_

In-Kernel Testing Framework
===========================

The kernel testing library supports KUnit tests written in C using
KUnit. These KUnit tests are kernel code. KUnit performs the following
tasks:

- Organizes tests
- Reports test results
- Provides test utilities

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

The test case is the fundamental unit in KUnit. KUnit test cases are organised
into suites. A KUnit test case is a function with type signature
``void (*)(struct kunit *test)``. These test case functions are wrapped in a
struct called struct kunit_case.

.. note:
	``generate_params`` is optional for non-parameterized tests.

Each KUnit test case receives a ``struct kunit`` context object that tracks a
running test. The KUnit assertion macros and other KUnit utilities use the
``struct kunit`` context object. As an exception, there are two fields:

- ``->priv``: The setup functions can use it to store arbitrary test
  user data.

- ``->param_value``: It contains the parameter value which can be
  retrieved in the parameterized tests.

Test Suites
-----------

A KUnit suite includes a collection of test cases. The KUnit suites
are represented by the ``struct kunit_suite``. 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,
		.test_cases = example_test_cases,
	};
	kunit_test_suite(example_test_suite);

In the above example, the test suite ``example_test_suite``, runs the
test cases ``example_test_foo``, ``example_test_bar``, and
``example_test_baz``. Before running the test, the ``example_test_init``
is called and after running the test, ``example_test_exit`` is called.
The ``kunit_test_suite(example_test_suite)`` registers the test suite
with the KUnit test framework.

Executor
--------

The KUnit executor can list and run built-in KUnit tests on boot.
The Test suites are stored in a linker section
called ``.kunit_test_suites``. For the code, see ``KUNIT_TABLE()`` macro
definition in
`include/asm-generic/vmlinux.lds.h <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v6.0#n950>`_.
The linker section consists of an array of pointers to
``struct kunit_suite``, and is populated by the ``kunit_test_suites()``
macro. The KUnit executor iterates over the linker section array in order to
run all the tests that are compiled into the kernel.

.. kernel-figure:: kunit_suitememorydiagram.svg
	:alt:	KUnit Suite Memory

	KUnit Suite Memory Diagram

On the kernel boot, the KUnit executor uses the start and end addresses
of this section to iterate over and run all tests. For the implementation of the
executor, see
`lib/kunit/executor.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c>`_.
When built as a module, the ``kunit_test_suites()`` macro defines a
``module_init()`` function, which runs all the tests in the compilation
unit instead of utilizing the executor.

In KUnit tests, some error classes do not affect other tests
or parts of the kernel, each KUnit case executes in a separate thread
context. See the ``kunit_try_catch_run()`` function in
`lib/kunit/try-catch.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58>`_.

Assertion Macros
----------------

KUnit tests verify state using expectations/assertions.
All expectations/assertions are formatted as:
``KUNIT_{EXPECT|ASSERT}_<op>[_MSG](kunit, property[, message])``

- ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an
  expectation.
  In the event of a failure, the testing flow differs as follows:

	- For expectations, the test is marked as failed and the failure is logged.

	- Failing assertions, on the other hand, result in the test case being
	  terminated immediately.

		- Assertions call the function:
		  ``void __noreturn kunit_abort(struct kunit *)``.

		- ``kunit_abort`` calls the function:
		  ``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``.

		- ``kunit_try_catch_throw`` calls the function:
		  ``void kthread_complete_and_exit(struct completion *, long) __noreturn;``
		  and terminates the special thread context.

- ``<op>`` denotes a check with options: ``TRUE`` (supplied property
  has the boolean value "true"), ``EQ`` (two supplied properties are
  equal), ``NOT_ERR_OR_NULL`` (supplied pointer is not null and does not
  contain an "err" value).

- ``[_MSG]`` prints a custom message on failure.

Test Result Reporting
---------------------
KUnit prints the test results in KTAP format. KTAP is based on TAP14, see
Documentation/dev-tools/ktap.rst.
KTAP works with KUnit and Kselftest. The KUnit executor prints KTAP results to
dmesg, and debugfs (if configured).

Parameterized Tests
-------------------

Each KUnit parameterized test is associated with a collection of
parameters. The test is invoked multiple times, once for each parameter
value and the parameter is stored in the ``param_value`` field.
The test case includes a KUNIT_CASE_PARAM() macro that accepts a
generator function. The generator function is passed the previous parameter
and returns the next parameter. It also includes a macro for generating
array-based common-case generators.

kunit_tool (Command-line Test Harness)
======================================

``kunit_tool`` is a Python script, found in ``tools/testing/kunit/kunit.py``. It
is used to configure, build, execute, parse test results and run all of the
previous commands in correct order (i.e., configure, build, execute and parse).
You have two options for running KUnit tests: either build the kernel with KUnit
enabled and manually parse the results (see
Documentation/dev-tools/kunit/run_manual.rst) or use ``kunit_tool``
(see Documentation/dev-tools/kunit/run_wrapper.rst).

- ``configure`` command generates the kernel ``.config`` from a
  ``.kunitconfig`` file (and any architecture-specific options).
  The Python scripts available in ``qemu_configs`` folder
  (for example, ``tools/testing/kunit/qemu configs/powerpc.py``) contains
  additional configuration options for specific architectures.
  It parses both the existing ``.config`` and the ``.kunitconfig`` files
  to ensure that ``.config`` is a superset of ``.kunitconfig``.
  If not, it will combine the two and run ``make olddefconfig`` to regenerate
  the ``.config`` file. It then checks to see if ``.config`` has become a superset.
  This verifies that all the Kconfig dependencies are correctly specified in the
  file ``.kunitconfig``. The ``kunit_config.py`` script contains the code for parsing
  Kconfigs. The code which runs ``make olddefconfig`` is part of the
  ``kunit_kernel.py`` script. You can invoke this command through:
  ``./tools/testing/kunit/kunit.py config`` and
  generate a ``.config`` file.
- ``build`` runs ``make`` on the kernel tree with required options
  (depends on the architecture and some options, for example: build_dir)
  and reports any errors.
  To build a KUnit kernel from the current ``.config``, you can use the
  ``build`` argument: ``./tools/testing/kunit/kunit.py build``.
- ``exec`` command executes kernel results either directly (using
  User-mode Linux configuration), or through an emulator such
  as QEMU. It reads results from the log using standard
  output (stdout), and passes them to ``parse`` to be parsed.
  If you already have built a kernel with built-in KUnit tests,
  you can run the kernel and display the test results with the ``exec``
  argument: ``./tools/testing/kunit/kunit.py exec``.
- ``parse`` extracts the KTAP output from a kernel log, parses
  the test results, and prints a summary. For failed tests, any
  diagnostic output will be included.


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

==========================
Frequently Asked Questions
==========================

How is this different from Autotest, kselftest, and so on?
==========================================================
KUnit is a unit testing framework. Autotest, kselftest (and some others) are
not.

A `unit test <https://martinfowler.com/bliki/UnitTest.html>`_ is supposed to
test a single unit of code in isolation and hence the name *unit test*. A unit
test should be the finest granularity of testing and should allow all possible
code paths to be tested in the code under test. This is only possible if the
code under test is small and does not have any external dependencies outside of
the test's control like hardware.

There are no testing frameworks currently available for the kernel that do not
require installing the kernel on a test machine or in a virtual machine. All
testing frameworks require tests to be written in userspace and run on the
kernel under test. This is true for Autotest, kselftest, and some others,
disqualifying any of them from being considered unit testing frameworks.

Does KUnit support running on architectures other than UML?
===========================================================

Yes, mostly.

For the most part, the KUnit core framework (what we use to write the tests)
can compile to any architecture. It compiles like just another part of the
kernel and runs when the kernel boots, or when built as a module, when the
module is loaded.  However, there is infrastructure, like the KUnit Wrapper
(``tools/testing/kunit/kunit.py``) that might not support some architectures
(see :ref:`kunit-on-qemu`).

In short, yes, you can run KUnit on other architectures, but it might require
more work than using KUnit on UML.

For more information, see :ref:`kunit-on-non-uml`.

.. _kinds-of-tests:

What is the difference between a unit test and other kinds of tests?
====================================================================
Most existing tests for the Linux kernel would be categorized as an integration
test, or an end-to-end test.

- A unit test is supposed to test a single unit of code in isolation. A unit
  test should be the finest granularity of testing and, as such, allows all
  possible code paths to be tested in the code under test. This is only possible
  if the code under test is small and does not have any external dependencies
  outside of the test's control like hardware.
- An integration test tests the interaction between a minimal set of components,
  usually just two or three. For example, someone might write an integration
  test to test the interaction between a driver and a piece of hardware, or to
  test the interaction between the userspace libraries the kernel provides and
  the kernel itself. However, one of these tests would probably not test the
  entire kernel along with hardware interactions and interactions with the
  userspace.
- An end-to-end test usually tests the entire system from the perspective of the
  code under test. For example, someone might write an end-to-end test for the
  kernel by installing a production configuration of the kernel on production
  hardware with a production userspace and then trying to exercise some behavior
  that depends on interactions between the hardware, the kernel, and userspace.

KUnit is not working, what should I do?
=======================================

Unfortunately, there are a number of things which can break, but here are some
things to try.

1. Run ``./tools/testing/kunit/kunit.py run`` with the ``--raw_output``
   parameter. This might show details or error messages hidden by the kunit_tool
   parser.
2. Instead of running ``kunit.py run``, try running ``kunit.py config``,
   ``kunit.py build``, and ``kunit.py exec`` independently. This can help track
   down where an issue is occurring. (If you think the parser is at fault, you
   can run it manually against ``stdin`` or a file with ``kunit.py parse``.)
3. Running the UML kernel directly can often reveal issues or error messages,
   ``kunit_tool`` ignores. This should be as simple as running ``./vmlinux``
   after building the UML kernel (for example, by using ``kunit.py build``).
   Note that UML has some unusual requirements (such as the host having a tmpfs
   filesystem mounted), and has had issues in the past when built statically and
   the host has KASLR enabled. (On older host kernels, you may need to run
   ``setarch `uname -m` -R ./vmlinux`` to disable KASLR.)
4. Make sure the kernel .config has ``CONFIG_KUNIT=y`` and at least one test
   (e.g. ``CONFIG_KUNIT_EXAMPLE_TEST=y``). kunit_tool will keep its .config
   around, so you can see what config was used after running ``kunit.py run``.
   It also preserves any config changes you might make, so you can
   enable/disable things with ``make ARCH=um menuconfig`` or similar, and then
   re-run kunit_tool.
5. Try to run ``make ARCH=um defconfig`` before running ``kunit.py run``. This
   may help clean up any residual config items which could be causing problems.
6. Finally, try running KUnit outside UML. KUnit and KUnit tests can be
   built into any kernel, or can be built as a module and loaded at runtime.
   Doing so should allow you to determine if UML is causing the issue you're
   seeing. When tests are built-in, they will execute when the kernel boots, and
   modules will automatically execute associated tests when loaded. Test results
   can be collected from ``/sys/kernel/debug/kunit/<test suite>/results``, and
   can be parsed with ``kunit.py parse``. For more details, see :ref:`kunit-on-qemu`.

If none of the above tricks help, you are always welcome to email any issues to
kunit-dev@googlegroups.com.