# Configure kernel debugger

Configuring a kernel debugger allows you to inspect and control the Linux kernel during runtime or after a crash. Tools like Kernel GNU debugger KGDB and dynamic tracing frameworks enable step-by-step debugging, to identify and resolve low-level issues in kernel code.

## Debug kernel and modules with KGDB

KGDB provides live debugging support for the kernel on a device.

You can configure KGDB to debug core kernel and module issues. KGDB is a source-level debugger used with GDB to debug the Qualcomm Linux kernel.

For more information about KGDB kernel debugging, see
[Debugging kernel and modules via gdb](https://www.kernel.org/doc/html/v6.14-rc7/process/debugging/gdb-kernel-debugging.html).

## Use KGDB with serial COM port

Enable the following kernel drivers in the kernel configuration file to support KGDB with serial COM port:

CONFIG_FRAME_POINTER
    CONFIG_KGDB
    CONFIG_KGDB_SERIAL_CONSOLE
    CONFIG_HAVE_ARCH_KGDB
    CONFIG_CONSOLE_POLL
    CONFIG_MAGIC_SYSRQ
    Copy to clipboard

Update the command-line for debug:

# Append  KERNEL_CMDLINE_EXTRA in meta-qcom-hwe/conf/machine/include/qcom-<SoC>.conf with following string
    "kgdboc=ttyMSM0,115200n8 kgdbwait nokaslr"
    
    # If waiting during the boot of kernel for gdb connection is not desired,
    # the parameter 'kgdbwait' can be skipped.
    Copy to clipboard

**Disable watchdog**

- Disable the watchdog when debugging using KGDB. The SoC resets when the watchdog is enabled.
- To disable the watchdog, add the following kernel command-line parameter:

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

**Methods to enter debug mode**

**Method 1** - Use `kgdbwait`:

If `kgdbwait` is passed as the command-line parameter, the kernel does the following:
1. Pauses the execution during boot
2. Enters the Debug mode
3. Waits for the connection from remote GDB, with the following message:

[ 0.239669] printk: console [ttyMSM0] enabled
    [ 1.535669] random: fast init done
    [ 1.541411] KGDB: Registered I/O driver kgdboc
    [ 2.224804] KGDB: Waiting for connection from remote gdb...
    Copy to clipboard

Disable the watchdog from the configuration.

**Method 2** - Use `Magic SysRq`:

To enter the Debug mode, run `SysRq-G` in the shell, and run the following command:

`echo g > /proc/sysrq-trigger`

**Method 3** - Whenever you want to hit a KGDB breakpoint in the source code, add the following code snippet to the intended driver file:

#include <linux/kgdb.h>   (you may need to include this file )
    kgdb_breakpoint(); //call this for adding a break point at compile time
    Copy to clipboard

**Method 4** - Triggering panic: The kernel automatically enters Debug mode when an exception occurs. To trigger a crash, use the `Magic SysRq` feature.

`echo c > /proc/sysrq-trigger`

### Connect to the Qualcomm SoC through GDB over COM port

Install GDB `gdb-multiarch: mingw64\bin\gdb-multiarch.exe`.

- For GDB for Windows–Install Mingw-w64 through [MSYS2](https://www.msys2.org/).
- For GDB for Linux–Install GDB using [How to Install GDB](https://www.gdbtutorial.com/tutorial/how-install-gdb).
- Close all other connections to a serial port, while using the COM Port with GDB to connect to the SoC.
- On a Windows host, set the COM port number to a number greater than 16. You can get the port number from the device manager.
- On a Windows host, pass the COM Port as `\\.\com<#>`.
- In the following example, establish a connection from a serial port on a Windows host. The serial port number used is COM17. GDB is disconnected from COM port before connecting PuTTY again. To attach and detach GDB commands, run the following commands:

gdb-multiarch.exe -b 115200 <path_to_vmlinux>
        (gdb) target remote \\.\com17
           Remote debugging using \\.\com17
           warning: multi-threaded target stopped without sending a thread-id, using first non-exited thread
           [Switching to Thread -2]
           arch_kgdb_breakpoint () at arch/arm64/include/asm/kgdb.h:21
           21      arch/arm64/include/asm/kgdb.h: No such file or directory.
        Copy to clipboard

To set the breakpoints, view them, or check CPU registers, run the following commands:

# backtrace:
    > bt
    
    # set a break point:
    break <function_name>
    or
    break <filename>: line no
    
    # View all current break points:
    info break
    
    # View CPU registers:
    info reg
    
    # step over:
    s
    
    # continue execution:
    c
    Copy to clipboard

#### Use KGDB to debug kernel modules

KGDB is a kernel patch that allows source-level debugging of a running
Qualcomm Linux kernel using the GDB interface.

You must have the `.ko` files and location of the `.text` kernel
module files.

To get the address of the `.text` section of the loaded module, run the following command:

# from live device
    # cat /sys/module/<module>/sections/.text
    Copy to clipboard

To add a module symbol file, run the following command:

(gdb) add-symbol-file <path_to_.ko> <.text_addr>
    Copy to clipboard

For example, `add-symbol-file /sys/modules/linux/linux.ko 0xc0ae22d0`.

Last Published: Jun 25, 2026

[Previous Topic
Access content from the device](https://docs.qualcomm.com/bundle/publicresource/80-70030-3/topics/access-content-from-the-device.md) [Next Topic
Troubleshoot kernel issues](https://docs.qualcomm.com/bundle/publicresource/80-70030-3/topics/common_troubleshooting.md)