Documentation/process/debugging/gdb-kernel-debugging.rst

Source file repositories/reference/linux-study-clean/Documentation/process/debugging/gdb-kernel-debugging.rst

File Facts

System
Linux kernel
Corpus path
Documentation/process/debugging/gdb-kernel-debugging.rst
Extension
.rst
Size
6560 bytes
Lines
185
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. highlight:: none

Debugging kernel and modules via gdb
====================================

The kernel debugger kgdb, hypervisors like QEMU or JTAG-based hardware
interfaces allow to debug the Linux kernel and its modules during runtime
using gdb. Gdb comes with a powerful scripting interface for python. The
kernel provides a collection of helper scripts that can simplify typical
kernel debugging steps. This is a short tutorial about how to enable and use
them. It focuses on QEMU/KVM virtual machines as target, but the examples can
be transferred to the other gdb stubs as well.


Requirements
------------

- gdb 7.2+ (recommended: 7.4+) with python support enabled (typically true
  for distributions)


Setup
-----

- Create a virtual Linux machine for QEMU/KVM (see www.linux-kvm.org and
  www.qemu.org for more details). For cross-development,
  https://landley.net/aboriginal/bin keeps a pool of machine images and
  toolchains that can be helpful to start from.

- Build the kernel with CONFIG_GDB_SCRIPTS enabled, but leave
  CONFIG_DEBUG_INFO_REDUCED off. If your architecture supports
  CONFIG_FRAME_POINTER, keep it enabled.

- Install that kernel on the guest, turn off KASLR if necessary by adding
  "nokaslr" to the kernel command line.
  Alternatively, QEMU allows to boot the kernel directly using -kernel,
  -append, -initrd command line switches. This is generally only useful if
  you do not depend on modules. See QEMU documentation for more details on
  this mode. In this case, you should build the kernel with
  CONFIG_RANDOMIZE_BASE disabled if the architecture supports KASLR.

- Build the gdb scripts (required on kernels v5.1 and above)::

    make scripts_gdb

- Enable the gdb stub of QEMU/KVM, either

    - at VM startup time by appending "-s" to the QEMU command line

  or

    - during runtime by issuing "gdbserver" from the QEMU monitor
      console

- cd /path/to/linux-build

- Start gdb: gdb vmlinux

  Note: Some distros may restrict auto-loading of gdb scripts to known safe
  directories. In case gdb reports to refuse loading vmlinux-gdb.py, add::

    add-auto-load-safe-path /path/to/linux-build

  to ~/.gdbinit. See gdb help for more details.

- Attach to the booted guest::

    (gdb) target remote :1234

Annotation

Implementation Notes