> For the complete documentation index, see [llms.txt](https://dev.solid-run.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.solid-run.com/nxp/lx2160a/sbc-platform/lx2160a-software/kgdb-kernel-debugger.md). # KGDB Kernel Debugger This page describes how to use in-kernel KGDB to debug the Linux Kernel running on LX2162A Clearfog Board. ## Requirements On the Target (LX2162A Clearfog) a native UART from the SoC must be used. UART1 (`ttyAMA0`) is normally used for console access (mini-USB connector). Additionally UART2 (`ttyAMA1`) is available on pin header J19. The host may connect to the target by any suitable usb-to-uart adapters, usually showing up as `/dev/ttyUSB0` or similar. Further the kernel must be recompiled adding support for KGDB and additional symbol information: ``` CONFIG_KGDB=y CONFIG_DEBUG_INFO=y # CONFIG_DEBUG_INFO_REDUCED is not set ``` Finally the target must disable its watchdog functionality to avoid unintended reset while debugging. ## Configure Host ### Dedicated UART Debugging Linux using the LX2162A Clearfog UART2 exposed on J19 pin header at 3.3V logic level. **Note: This method currently is not functional during the author’s testing …** ### Share Console Debugging Linux using the LX2162A Clearfog UART1 that is already in use for console. Kernel developers provide a proxy tool for multiplexing between KGDB commands and the regular console from a single UART: It reads from the Host (PC) Serial POrt that is connected to the Target, and exposes KGDB and Console on two local network ports for access from gdb and telnet. If on the Host side the console uart is `/dev/ttyUSB0`, then the agent-proxy is started as follows: ``` ./agent-proxy 5550^5551 0 /dev/ttyUSB0,115200 Agent Proxy 1.97 Started with: 5550^5551 0 /dev/ttyUSB0,115200 Agent Proxy running. pid: 855222 ``` **Note: Ensure no other process is opening the serial device, in particular no other terminal emulator.** Console is now available using telnet: ``` telnet localhost 5550 ``` Note: When configuring the target, choose `ttyAMA0` for KGDB. Note: When configuring the target, choose `ttyAMA0` for KGDB. **Note: When configuring the target, choose** `ttyAMA0`**for KGDB instead of dedicated** `ttyAMA1`**.** ## Configure Debugger on Target ### Disable Watchdog 1. In Linux edit systemd config file to disable watchdog configuration: ``` sed -i "s;^\(RuntimeWatchdogSec=.*\)$;#\1;g" /etc/systemd/system.conf ``` 2. In boot-loader during every boot, break to u-boot console during the timeout and stop the watchdog: ``` Hit any key to stop autoboot: 0 => wdt list watchdog@23a0000 (sbsa_gwdt) => wdt dev watchdog@23a0000 => wdt stop => boot ``` ### At Boot-Time Kernel debugger can be configured using kernel cmdline passed from bootloader. Edit extlinux.conf `APPEND` line and add `kgdboc=ttyAMA1,115200` - e.g.: ``` timeout 30 default linux menu title linux-lx2160a boot options label primary menu label primary kernel linux /boot/Image.gz fdtdir /boot/ APPEND console=ttyAMA0,115200 earlycon=pl011,mmio32,0x21c0000 default_hugepagesz=1024m hugepagesz=1024m hugepages=2 pci=pcie_bus_perf root=PARTUUID=30303030-01 rw rootwait kgdboc=ttyAMA1,115200 kgdbwait ``` ### At Run-Time Kernel debugger can be enabled at run-time by setting the `kgdboc` parameter through sysfs: ``` echo ttyAMA1,115200 > /sys/module/kgdboc/parameters/kgdboc [ 42.920363] KGDB: Registered I/O driver kgdboc ``` ## Start Debugging To start a debug session requires coordinated steps on both the Host (PC) and the Target (LX2162A Clearfog). Extra complication is added by system watchdog if it wasn’t disabled properly. ### Target A debug session on the Target is started by issuing magic sysrq - which will halt the kernel and start KGDB: ``` echo g > /proc/sysrq-trigger [ 907.508271] sysrq: DEBUG [ 907.510809] KGDB: Entering KGDB ``` ### Host The Host should connect to the Target immediately after sysrq was issued. It is recommended to first start gdb and wait while it loads `vmlinux` file - then issue sysrq and connect (`target` command). ``` gdb-multiarch vmlinux -tui GNU gdb (Debian 13.1-3) 13.1 Copyright (C) 2023 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "x86_64-linux-gnu". Type "show configuration" for configuration details. For bug reporting instructions, please see: . Find the GDB manual and other documentation resources online at: . For help, type "help". Type "apropos word" to search for commands related to "word"... Reading symbols from vmlinux... (gdb) # for dedicated UART (gdb) set serial baud 115200 (gdb) target remote /dev/ttyUSB1 (gdb) # for Console UART (gdb) target remote localhost:5551 Remote debugging using localhost:5551 ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://dev.solid-run.com/nxp/lx2160a/sbc-platform/lx2160a-software/kgdb-kernel-debugger.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.