KGDB — Getting Started
KGDB (Linux Kernel Source Level Debugger) allowed developers to debug the running Linux kernel using GDB — the standard GNU debugger — connected over a serial connection or network link to the target machine. This getting-started guide covers the basic setup for using KGDB on a development machine, originally written for the 2004-2005 era (Linux kernel 2.5 and early 2.6).
Prerequisites
- A development host running Linux with GDB installed
- A target machine to debug (this could be a second physical machine, a VM, or in some configurations the same machine as the host)
- A way to connect host to target — typically a null-modem serial cable, or a network connection for KGDB-over-Ethernet
- A Linux kernel built with KGDB support compiled in
Basic workflow
- Patch and build the kernel with KGDB support enabled. This required applying the KGDB patches to the kernel source tree, then building normally with the KGDB-related CONFIG options turned on.
- Configure the target machine to boot with KGDB enabled. This typically meant adding KGDB-specific boot arguments and ensuring the serial port (or network interface) used for the debug connection was properly set up.
- Connect from the host using GDB’s remote debugging mode. Once the target was paused at a KGDB break point, the host’s GDB session could inspect kernel state — variables, stack frames, structure contents — as if debugging a normal userspace program.
- Set breakpoints, step through code, and inspect kernel state using standard GDB commands.
Common first-time issues
The most frequent setup problems involved serial port configuration (wrong baud rate or wrong device), GDB version mismatches between host and the kernel’s debug symbols, and forgetting to compile in KGDB support before building the kernel. The KGDB FAQ and troubleshooting guide cover the most common issues.
Next steps after initial setup
Once you have a working KGDB connection, the natural next steps are reading the Kernel Debugging guide for the techniques specific to kernel debugging (which differ from userspace debugging in important ways), and the Using KGDB guide for the day-to-day workflow patterns. For architecture-specific notes, see x86_64 and PowerPC.
Modern context
Mainline Linux merged KGDB-equivalent functionality starting around the 2.6.26 kernel release. Modern Linux kernels include this support natively — no separate patch needed. The modern equivalent setup is documented in the Linux kernel’s Documentation/dev-tools/kgdb.rst file. The basic workflow (connect GDB from host, debug remote kernel) is unchanged from the LinSys era.
From the archive
|
|
||||||||||||||||||||||