Using KGDB for Linux Kernel and Module Debugging: Environment Setup and Step‑by‑Step Guide

KGDB Background

KGDB was officially supported starting from Linux kernel 2.6.26 and is available on distributions such as SLES11+ and RHEL6+. Earlier kernels required third‑party patches.

1. Debugging Environment Setup

1.1 Target Machine Configuration

1.1.1 Serial Port

Configure the physical or virtual serial port so that the pipe name matches on both the target and development machines.

1.1.2 Update Kernel for KGDB Support

Ensure sufficient disk space (≥7 GB, preferably 10 GB) before compiling the kernel with debugging symbols.

Steps:

Run uname -r to identify the current kernel, copy the corresponding .config from /boot to the source tree.

Execute make menuconfig and enable:

[*] Compile the kernel with debug info

[*] Compile the kernel with frame pointers

[*] KGDB: kernel debugging with remote gdb

Disable Write protect kernel read‑only data structures to allow breakpoints.

Compile the kernel:

Run make all (optionally make -j$(nproc) all).

Install modules with make modules_install (note the underscore).

Backup original /boot/vmlinuz and /boot/initrd, then run make install to install the new kernel and generate an initrd.

Create a new boot entry adding the parameter kgdboc=ttyS0,115200 (add kgdbwait if you want the target to pause immediately).

1.2 Development Machine Configuration

The host only needs a compatible GDB version; a SLES10SP4 32‑bit VM is used in this guide.

1.2.1 Serial Port

Verify the serial link by:

On the target: cat /dev/ttyS0 On the host: echo test > /dev/ttyS0 Confirm the target prints “test”.

1.2.2 Prepare Source and Binary

Copy the full kernel source tree from the target to the host before compilation, and copy the built binaries (e.g., vmlinux or xxx.ko) to the host.

2. Debugging Steps

2.1 Debugging the Kernel Image (vmlinux)

Example: debugging the function get_request_wait in the block layer.

On the target, trigger a pause: echo g > /proc/sysrq-trigger.

On the host, start GDB and connect:

set remotebaud 115200

target remote /dev/ttyS0

Set a breakpoint and continue:

b get_request_wait

c

Inspect the call stack with bt and step through with n. Use p rq and p *rq to examine variables.

After debugging, clear breakpoints ( info b, d breakpoint 1) and resume execution ( c).

2.2 Debugging a Loadable Module (KO)

Example: debugging scsi_mod.ko.

Find the module’s load address on the target and pause the system.

On the host, start GDB and load the module symbols: add-symbol-file scsi_mod.ko 0xADDRESS Proceed with the same remote‑debugging steps as for the kernel image.

3. Summary

KGDB enables live inspection of kernel code and simplifies troubleshooting of both core and third‑party modules without extensive printk instrumentation, greatly improving debugging efficiency. The most time‑consuming part is rebuilding the kernel with the required options; teams should coordinate kernel preparation for different distributions to streamline future use.