Documentation/process/debugging/index.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ============================================
   4 Debugging advice for Linux Kernel developers
   5 ============================================
   6
   7 general guides
   8 --------------
   9
  10 .. toctree::
  11    :maxdepth: 1
  12
  13    driver_development_debugging_guide
  14    userspace_debugging_guide
  15
  16 .. only::  subproject and html
  17
  18 subsystem specific guides
  19 -------------------------
  20
  21 .. toctree::
  22    :maxdepth: 1
  23
  24    media_specific_debugging_guide
  25
  26 .. only::  subproject and html
  27
  28    Indices
  29    =======
  30
  31    * :ref:`genindex`
  32
  33 General debugging advice
  34 ========================
  35
  36 Depending on the issue, a different set of tools is available to track down the
  37 problem or even to realize whether there is one in the first place.
  38
  39 As a first step you have to figure out what kind of issue you want to debug.
  40 Depending on the answer, your methodology and choice of tools may vary.
  41
  42 Do I need to debug with limited access?
  43 ---------------------------------------
  44
  45 Do you have limited access to the machine or are you unable to stop the running
  46 execution?
  47
  48 In this case your debugging capability depends on built-in debugging support of
  49 provided distribution kernel.
  50 The :doc:`/process/debugging/userspace_debugging_guide` provides a brief
  51 overview over a range of possible debugging tools in that situation. You can
  52 check the capability of your kernel, in most cases, by looking into config file
  53 within the /boot directory.
  54
  55 Do I have root access to the system?
  56 ------------------------------------
  57
  58 Are you easily able to replace the module in question or to install a new
  59 kernel?
  60
  61 In that case your range of available tools is a lot bigger, you can find the
  62 tools in the :doc:`/process/debugging/driver_development_debugging_guide`.
  63
  64 Is timing a factor?
  65 -------------------
  66
  67 It is important to understand if the problem you want to debug manifests itself
  68 consistently (i.e. given a set of inputs you always get the same, incorrect
  69 output), or inconsistently. If it manifests itself inconsistently, some timing
  70 factor might be at play. If inserting delays into the code does change the
  71 behavior, then quite likely timing is a factor.
  72
  73 When timing does alter the outcome of the code execution using a simple
  74 printk() for debugging purposes may not work, a similar alternative is to use
  75 trace_printk() , which logs the debug messages to the trace file instead of the
  76 kernel log.
  77
  78 **Copyright** ©2024 : Collabora