Using KGDB

Using KGDB — Day-to-Day Workflow

Once KGDB is set up (see Getting Started), the day-to-day debugging workflow involves standard GDB commands applied to the running kernel. This guide covers the patterns that are most useful for kernel-level work, which differ in important ways from typical userspace debugging.

Triggering a debug session

There are three common ways to drop the kernel into KGDB:

Compile-time breakpoint — insert a KGDB_BREAKPOINT() macro call into kernel code at the point of interest, then connect when execution reaches it
Magic SysRq key — pressing the SysRq sequence on the target’s console drops the kernel into KGDB immediately
Programmatic break — calling kgdb_breakpoint() from kernel code (e.g., from an interrupt handler) when a specific condition occurs

Useful GDB commands for kernel work

bt / backtrace — show the kernel stack frame chain. Particularly useful for understanding how execution got to the current point through interrupt handlers and system call paths.
info threads — list all kernel tasks (KGDB models each task as a GDB thread). Switching between threads lets you inspect any task’s state.
print *current — dump the current task structure, showing PID, state, scheduling info, and memory layout pointers
info registers — show CPU register state (architecture-specific — see x86_64 or PowerPC notes for arch-specific registers)
x/Nx address — dump memory at a specific address in hex; useful for inspecting kernel data structures by pointer

Common debugging scenarios

Investigating a kernel panic — the most common use case. Reproduce the panic, drop into KGDB, examine the stack and surrounding state to understand what triggered the panic.
Verifying driver behavior — set breakpoints in your custom driver’s entry points and inspect the parameters, then step through the code path to confirm it behaves as expected.
Catching race conditions — set conditional breakpoints that fire only when a specific concurrent state is detected, then inspect the kernel state at that moment.
Inspecting kernel data structures — at any KGDB break point, dump kernel lists, hash tables, and other data structures using GDB’s print command with debug symbols.

Caveats specific to kernel debugging

Kernel debugging has constraints that userspace debugging doesn’t: the entire system is frozen while KGDB has control — including watchdogs, network protocols, and any time-sensitive operations. Sessions need to be quick. Also, modifying kernel state via the debugger (changing variable values, calling functions) is significantly riskier than in userspace because there’s no operating system to isolate the consequences of a mistake.