GNU Debugger

Introduction

The GNU Debugger Router App provides an interactive debugging environment for programs written in C and C++. Invoked from the router's command-line interface via the gdb command, it enables developers to:

Set breakpoints and watchpoints to pause program execution at specific points.
Step through code line by line to trace execution flow.
Inspect and modify variable values and memory at runtime.
Analyze backtraces to diagnose crashes and unexpected behavior.
Examine core dumps generated by program crashes.

Built-in help is accessible at any time by typing help at the GDB prompt, providing guidance on all available commands and their usage. GDB is a valuable tool for diagnosing issues, optimizing performance, and ensuring the quality of programs running on the router.

Installation

To install the GNU Debugger Router App, follow the instructions in the Configuration Manual, section Customization → Router Apps.

To verify the installation, check the GDB version from the router's CLI:

gdb --version

Prerequisites

To debug a program effectively with GDB, it must be compiled with debug symbols. When cross-compiling for the router using GCC, add the -g flag:

gcc -g -o my_program my_program.c

Without debug symbols, GDB can still run the program but cannot display source code, variable names, or meaningful function names in backtraces.

Basic Usage

Starting a Debugging Session

To start debugging a program, pass it as an argument to gdb:

gdb ./my_program

To debug a program that requires command-line arguments, use --args:

gdb --args ./my_program arg1 arg2

To analyze a core dump generated by a crashed program:

gdb ./my_program core

GDB Command Reference

The following commands are most commonly used during a GDB session:

Command	Short form	Description
`run`	`r`	Start the program.
`run arg1 arg2`	`r arg1 arg2`	Start the program with arguments.
`break <location>`	`b`	Set a breakpoint. Location can be a function name, `file:line`, or memory address.
`info breakpoints`	`info b`	List all breakpoints.
`delete <n>`	`d <n>`	Delete breakpoint number n.
`continue`	`c`	Resume execution until the next breakpoint.
`next`	`n`	Execute the next line, stepping over function calls.
`step`	`s`	Execute the next line, stepping into function calls.
`finish`		Run until the current function returns.
`print <expr>`	`p`	Print the value of a variable or expression.
`display <expr>`		Print a value automatically after every step.
`backtrace`	`bt`	Display the call stack.
`frame <n>`	`f <n>`	Select stack frame number n.
`list`	`l`	Show source code around the current line.
`info locals`		Show all local variables in the current frame.
`info args`		Show function arguments in the current frame.
`watch <expr>`		Set a watchpoint — break when the expression's value changes.
`quit`	`q`	Exit GDB.
`help`		Display help for GDB commands.

GDB command reference

Example Session

The following example starts GDB, sets a breakpoint at main, runs the program, and inspects a variable:

$ gdb ./my_program
GNU gdb (GDB) 10.x ...
(gdb) break main
Breakpoint 1 at 0x4005c0: file my_program.c, line 10.
(gdb) run
Starting program: ./my_program

Breakpoint 1, main () at my_program.c:10
10          int count = 0;
(gdb) next
11          count = 42;
(gdb) print count
$1 = 0
(gdb) next
12          printf("Count: %d\n", count);
(gdb) print count
$2 = 42
(gdb) continue
Count: 42
[Inferior 1 (process 1234) exited normally]
(gdb) quit

Remote Debugging with gdbserver

When developing router applications on a separate host machine, remote debugging with gdbserver allows the program to run on the router while the debugger is controlled from the development computer. This approach is particularly useful when the router's CLI access is limited or when full GDB tooling is preferred on the host.

On the Router

Start gdbserver on the router, specifying a TCP port and the program to debug:

gdbserver :2345 ./my_program

gdbserver waits for an incoming connection before starting the program.

On the Development Machine

Start GDB with a local copy of the binary and connect to the router:

gdb ./my_program

(gdb) target remote ROUTER_IP_ADDRESS:2345
Remote debugging using ROUTER_IP_ADDRESS:2345
...
(gdb) break main
Breakpoint 1 at 0x4005c0: file my_program.c, line 10.
(gdb) continue

Replace ROUTER_IP_ADDRESS with the router's IP address and 2345 with the port used when starting gdbserver.

Tips

The binary on the development machine must match the binary running on the router exactly — the same source code and compilation flags. The local copy should retain full debug symbols (-g). The binary deployed to the router may optionally be stripped to reduce file size (strip my_program), though keeping symbols on the router produces more informative backtraces.

Getting Help

GDB provides extensive built-in documentation accessible directly from the GDB prompt:

(gdb) help
(gdb) help breakpoints
(gdb) help running
(gdb) help data

To get help on a specific command:

(gdb) help <command>

Comprehensive GDB documentation is also available at the GNU GDB website.