.. SPDX-License-Identifier: GPL-2.0

==========================
Userspace debugging advice
==========================

This document provides a brief overview of common tools to debug the Linux
Kernel from userspace.
For debugging advice aimed at driver developers go :doc:`here
</process/debugging/driver_development_debugging_guide>`.
For general debugging advice, see :doc:`general advice document
</process/debugging/index>`.

.. contents::
    :depth: 3

The following sections show you the available tools.

Dynamic debug
-------------

Mechanism to filter what ends up in the kernel log by dis-/en-abling log
messages.

Prerequisite: ``CONFIG_DYNAMIC_DEBUG``

Dynamic debug is only able to target:

- pr_debug()
- dev_dbg()
- print_hex_dump_debug()
- print_hex_dump_bytes()

Therefore the usability of this tool is, as of now, quite limited as there is
no uniform rule for adding debug prints to the codebase, resulting in a variety
of ways these prints are implemented.

Also, note that most debug statements are implemented as a variation of
dprintk(), which have to be activated via a parameter in respective module,
dynamic debug is unable to do that step for you.

Here is one example, that enables all available pr_debug()'s within the file::

  $ alias ddcmd='echo $* > /proc/dynamic_debug/control'
  $ ddcmd '-p; file v4l2-h264.c +p'
  $ grep =p /proc/dynamic_debug/control
   drivers/media/v4l2-core/v4l2-h264.c:372 [v4l2_h264]print_ref_list_b =p
   "ref_pic_list_b%u (cur_poc %u%c) %s"
   drivers/media/v4l2-core/v4l2-h264.c:333 [v4l2_h264]print_ref_list_p =p
   "ref_pic_list_p (cur_poc %u%c) %s\n"

**When should you use this over Ftrace ?**

- When the code contains one of the valid print statements (see above) or when
  you have added multiple pr_debug() statements during development
- When timing is not an issue, meaning if multiple pr_debug() statements in
  the code won't cause delays
- When you care more about receiving specific log messages than tracing the
  pattern of how a function is called

For the full documentation see :doc:`/admin-guide/dynamic-debug-howto`

Ftrace
------

Prerequisite: ``CONFIG_DYNAMIC_FTRACE``

This tool uses the tracefs file system for the control files and output files.
That file system will be mounted as a ``tracing`` directory, which can be found
in either ``/sys/kernel/`` or ``/sys/debug/kernel/``.

Some of the most important operations for debugging are:

- You can perform a function trace by adding a function name to the
  ``set_ftrace_filter`` file (which accepts any function name found within the
  ``available_filter_functions`` file) or you can specifically disable certain
  functions by adding their names to the ``set_ftrace_notrace`` file (more info
  at: :ref:`trace/ftrace:dynamic ftrace`).
- In order to find out where calls originate from you can activate the
  ``func_stack_trace`` option under ``options/func_stack_trace``.
- Tracing the children of a function call and showing the return values are
  possible by adding the desired function in the ``set_graph_function`` file
  (requires config ``FUNCTION_GRAPH_RETVAL``); more info at
  :ref:`trace/ftrace:dynamic ftrace with the function graph tracer`.

For the full Ftrace documentation see :doc:`/trace/ftrace`

Or you could also trace for specific events by :ref:`using event tracing
<trace/events:2. using event tracing>`, which can be defined as described here:
:ref:`Creating a custom Ftrace tracepoint
<process/debugging/driver_development_debugging_guide:ftrace>`.

For the full Ftrace event tracing documentation see :doc:`/trace/events`

.. _read_ftrace_log:

Reading the ftrace log
~~~~~~~~~~~~~~~~~~~~~~

The ``trace`` file can be read just like any other file (``cat``, ``tail``,
``head``, ``vim``, etc.), the size of the file is limited by the
``buffer_size_kb`` (``echo 1000 > buffer_size_kb``). The
:ref:`trace/ftrace:trace_pipe` will behave similarly to the ``trace`` file, but
whenever you read from the file the content is consumed.

Kernelshark
~~~~~~~~~~~

A GUI interface to visualize the traces as a graph and list view from the
output of the `trace-cmd
<https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/>`__ application.

For the full documentation see `<https://kernelshark.org/Documentation.html>`__

Perf & alternatives
-------------------

The tools mentioned above provide ways to inspect kernel code, results,
variable values, etc. Sometimes you have to find out first where to look and
for those cases, a box of performance tracking tools can help you to frame the
issue.

Why should you do a performance analysis?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A performance analysis is a good first step when among other reasons:

- you cannot define the issue
- you do not know where it occurs
- the running system should not be interrupted or it is a remote system, where
  you cannot install a new module/kernel

How to do a simple analysis with linux tools?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For the start of a performance analysis, you can start with the usual tools
like:

- ``top`` / ``htop`` / ``atop`` (*get an overview of the system load, see
  spikes on specific processes*)
- ``mpstat -P ALL`` (*look at the load distribution among CPUs*)
- ``iostat -x`` (*observe input and output devices utilization and performance*)
- ``vmstat`` (*overview of memory usage on the system*)
- ``pidstat`` (*similar to* ``vmstat`` *but per process, to dial it down to the
  target*)
- ``strace -tp $PID`` (*once you know the process, you can figure out how it
  communicates with the Kernel*)

These should help to narrow down the areas to look at sufficiently.

Diving deeper with perf
~~~~~~~~~~~~~~~~~~~~~~~

The **perf** tool provides a series of metrics and events to further dial down
on issues.

Prerequisite: build or install perf on your system

Gather statistics data for finding all files starting with ``gcc`` in ``/usr``::

  # perf stat -d find /usr -name 'gcc*' | wc -l

   Performance counter stats for 'find /usr -name gcc*':

     1277.81 msec    task-clock             #    0.997 CPUs utilized
     9               context-switches       #    7.043 /sec
     1               cpu-migrations         #    0.783 /sec
     704             page-faults            #  550.943 /sec
     766548897       cycles                 #    0.600 GHz                         (97.15%)
     798285467       instructions           #    1.04  insn per cycle              (97.15%)
     57582731        branches               #   45.064 M/sec                       (2.85%)
     3842573         branch-misses          #    6.67% of all branches             (97.15%)
     281616097       L1-dcache-loads        #  220.390 M/sec                       (97.15%)
     4220975         L1-dcache-load-misses  #    1.50% of all L1-dcache accesses   (97.15%)
     <not supported> LLC-loads
     <not supported> LLC-load-misses

   1.281746009 seconds time elapsed

   0.508796000 seconds user
   0.773209000 seconds sys


  52

The availability of events and metrics depends on the system you are running.

For the full documentation see
`<https://perf.wiki.kernel.org/index.php/Main_Page>`__

Perfetto
~~~~~~~~

A set of tools to measure and analyze how well applications and systems perform.
You can use it to:

* identify bottlenecks
* optimize code
* make software run faster and more efficiently.

**What is the difference between perfetto and perf?**

* perf is tool as part of and specialized for the Linux Kernel and has CLI user
  interface.
* perfetto cross-platform performance analysis stack, has extended
  functionality into userspace and provides a WEB user interface.

For the full documentation see `<https://perfetto.dev/docs/>`__

Kernel panic analysis tools
---------------------------

  To capture the crash dump please use ``Kdump`` & ``Kexec``. Below you can find
  some advice for analysing the data.

  For the full documentation see the :doc:`/admin-guide/kdump/kdump`

  In order to find the corresponding line in the code you can use `faddr2line
  <https://elixir.bootlin.com/linux/v6.11.6/source/scripts/faddr2line>`__; note
  that you need to enable ``CONFIG_DEBUG_INFO`` for that to work.

  An alternative to using ``faddr2line`` is the use of ``objdump`` (and its
  derivatives for the different platforms like ``aarch64-linux-gnu-objdump``).
  Take this line as an example:

  ``[  +0.000240]  rkvdec_device_run+0x50/0x138 [rockchip_vdec]``.

  We can find the corresponding line of code by executing::

    aarch64-linux-gnu-objdump -dS drivers/staging/media/rkvdec/rockchip-vdec.ko | grep rkvdec_device_run\>: -A 40
    0000000000000ac8 <rkvdec_device_run>:
     ac8:	d503201f 	nop
     acc:	d503201f 	nop
    {
     ad0:	d503233f 	paciasp
     ad4:	a9bd7bfd 	stp	x29, x30, [sp, #-48]!
     ad8:	910003fd 	mov	x29, sp
     adc:	a90153f3 	stp	x19, x20, [sp, #16]
     ae0:	a9025bf5 	stp	x21, x22, [sp, #32]
        const struct rkvdec_coded_fmt_desc *desc = ctx->coded_fmt_desc;
     ae4:	f9411814 	ldr	x20, [x0, #560]
        struct rkvdec_dev *rkvdec = ctx->dev;
     ae8:	f9418015 	ldr	x21, [x0, #768]
        if (WARN_ON(!desc))
     aec:	b4000654 	cbz	x20, bb4 <rkvdec_device_run+0xec>
        ret = pm_runtime_resume_and_get(rkvdec->dev);
     af0:	f943d2b6 	ldr	x22, [x21, #1952]
        ret = __pm_runtime_resume(dev, RPM_GET_PUT);
     af4:	aa0003f3 	mov	x19, x0
     af8:	52800081 	mov	w1, #0x4                   	// #4
     afc:	aa1603e0 	mov	x0, x22
     b00:	94000000 	bl	0 <__pm_runtime_resume>
        if (ret < 0) {
     b04:	37f80340 	tbnz	w0, #31, b6c <rkvdec_device_run+0xa4>
        dev_warn(rkvdec->dev, "Not good\n");
     b08:	f943d2a0 	ldr	x0, [x21, #1952]
     b0c:	90000001 	adrp	x1, 0 <rkvdec_try_ctrl-0x8>
     b10:	91000021 	add	x1, x1, #0x0
     b14:	94000000 	bl	0 <_dev_warn>
        *bad = 1;
     b18:	d2800001 	mov	x1, #0x0                   	// #0
     ...

  Meaning, in this line from the crash dump::

    [  +0.000240]  rkvdec_device_run+0x50/0x138 [rockchip_vdec]

  I can take the ``0x50`` as offset, which I have to add to the base address
  of the corresponding function, which I find in this line::

    0000000000000ac8 <rkvdec_device_run>:

  The result of ``0xac8 + 0x50 = 0xb18``
  And when I search for that address within the function I get the
  following line::

    *bad = 1;
    b18:      d2800001        mov     x1, #0x0

**Copyright** ©2024 : Collabora