Kernel debugger (KGDB) - Qualcomm Dragonwing Documentation

KGDB (Kernel GNU Debugger) provides live source-level debugging of a running Qualcomm^® Linux kernel. A host machine running GDB connects to the target device over a serial port and can set breakpoints, inspect registers, and step through kernel code, including for dynamically loaded modules.

Required kernel configuration

Enable the following Kconfig options and rebuild the kernel:

CONFIG_FRAME_POINTER=y
CONFIG_KGDB=y
CONFIG_KGDB_SERIAL_CONSOLE=y
CONFIG_HAVE_ARCH_KGDB=y
CONFIG_CONSOLE_POLL=y
CONFIG_MAGIC_SYSRQ=y

Verify on a running system:

zcat /proc/config.gz | grep -E "CONFIG_KGDB|CONFIG_MAGIC_SYSRQ|CONFIG_FRAME_POINTER"

Serial setup

KGDB communicates over a serial port using the kgdboc (KGDB over console) driver.

Kernel command-line parameters

Add the following to KERNEL_CMDLINE_EXTRA in meta-qcom/conf/machine/include/qcom-<SoC>.conf:

kgdboc=ttyMSM0,115200n8 kgdbwait nokaslr

Parameter	Effect
`kgdboc=ttyMSM0,115200n8`	Register `ttyMSM0` at 115200 baud as the KGDB I/O channel
`kgdbwait`	Pause the kernel during boot and wait for a GDB connection before proceeding. Omit this if you prefer to connect GDB at a later point using SysRq.
`nokaslr`	Disable kernel address-space layout randomisation. Required for GDB symbol matching.

Disable the watchdog

The Qualcomm SoC watchdog resets the device if the kernel stops responding. Disable it before starting a KGDB session to prevent unexpected resets:

echo 1 > /sys/bus/platform/devices/hypervisor:qcom,gh-watchdog/disable

Enter debug mode

Choose one of the following methods to pause the kernel and activate the KGDB stub.

Method 1: kgdbwait (boot-time)

When kgdbwait is present on the kernel command line, the kernel stops during boot and prints the following message on the serial console:

[    0.239669] printk: console [ttyMSM0] enabled
[    1.541411] KGDB: Registered I/O driver kgdboc
[    2.224804] KGDB: Waiting for connection from remote gdb...

Connect GDB from the host before the kernel proceeds.

Method 2: Magic SysRq (runtime)

From a shell on the target:

echo g > /proc/sysrq-trigger

The kernel immediately suspends and waits for GDB.

Method 3: Compile-time breakpoint

Insert a hard breakpoint in driver source code:

#include <linux/kgdb.h>
kgdb_breakpoint();   /* kernel breaks here when this line is reached */

Rebuild and flash the kernel. The breakpoint fires when the code path executes.

Method 4: Kernel panic (exception-driven)

The kernel automatically enters KGDB mode when an unhandled exception or panic occurs. To deliberately trigger a crash for testing:

echo c > /proc/sysrq-trigger   # kernel panic → enters KGDB

Connect GDB from the host

Install gdb-multiarch on the host machine:

# Debian / Ubuntu
sudo apt install gdb-multiarch

# MSYS2 (Windows)
pacman -S mingw-w64-x86_64-gdb-multiarch

Linux host

gdb-multiarch -b 115200 <path_to_vmlinux>
(gdb) target remote /dev/ttyUSB0

Windows host

On Windows, set the COM port number above 16 in Device Manager and use the \\.\comN path syntax:

gdb-multiarch.exe -b 115200 <path_to_vmlinux>
(gdb) target remote \\.\com17

Expected output after connecting:

Remote debugging using \\.\com17
[Switching to Thread -2]
arch_kgdb_breakpoint () at arch/arm64/include/asm/kgdb.h:21

GDB debug session

Essential GDB commands

Table: GDB command reference

Command	Description
`bt`	Print a backtrace of the current call stack
`break <function>`	Set a breakpoint at the start of a function
`break <file>:<line>`	Set a breakpoint at a specific source line
`info break`	List all current breakpoints
`info reg`	Display all CPU registers
`x/<n>x <addr>`	Examine `n` words of memory at address `addr` in hex
`p <expression>`	Print the value of a C expression or variable
`s`	Step one source line (step into function calls)
`n`	Next source line (step over function calls)
`c`	Continue execution until the next breakpoint or interrupt
`finish`	Run until the current function returns
`detach`	Detach from the target (kernel continues running)

Load module symbols

To debug a dynamically loaded kernel module, retrieve the .text section address from the target:

# On the target device
cat /sys/module/<module_name>/sections/.text
# Example output: 0xffff800008800000

Then load the symbol file in GDB:

(gdb) add-symbol-file <path_to_module.ko> 0xffff800008800000

Example:

(gdb) add-symbol-file drivers/net/ethernet/my_driver.ko 0xffff800008800000
(gdb) break my_driver_probe
(gdb) c

For the full upstream KGDB documentation, see Debugging kernel and modules via gdb.

​Required kernel configuration

​Serial setup

​Kernel command-line parameters

​Disable the watchdog

​Enter debug mode

​Method 1: kgdbwait (boot-time)

​Method 2: Magic SysRq (runtime)

​Method 3: Compile-time breakpoint

​Method 4: Kernel panic (exception-driven)

​Connect GDB from the host

​Linux host

​Windows host

​GDB debug session

​Essential GDB commands

​Load module symbols