Using kgdb, kdb and the kernel debugger internals

To enable CONFIG_KGDB you should look under "Kernel debugging" and select "KGDB: kernel debugger".

While it is not a hard requirement that you have symbols in your vmlinux file, gdb tends not to be very useful without the symbolic data, so you will want to turn on CONFIG_DEBUG_INFO which is called "Compile the kernel with debug info" in the config menu.

It is advised, but not required that you turn on the CONFIG_FRAME_POINTER kernel option which is called "Compile the kernel with frame pointers" in the config menu. This option inserts code to into the compiled executable which saves the frame information in registers or on the stack at different points which allows a debugger such as gdb to more accurately construct stack back traces while debugging the kernel.

If the architecture that you are using supports the kernel option CONFIG_DEBUG_RODATA, you should consider turning it off. This option will prevent the use of software breakpoints because it marks certain regions of the kernel's memory space as read-only. If kgdb supports it for the architecture you are using, you can use hardware breakpoints if you desire to run with the CONFIG_DEBUG_RODATA option turned on, else you need to turn off this option.

Next you should choose one of more I/O drivers to interconnect debugging host and debugged target. Early boot debugging requires a KGDB I/O driver that supports early debugging and the driver must be built into the kernel directly. Kgdb I/O driver configuration takes place via kernel or module parameters which you can learn more about in the in the section that describes the parameter "kgdboc".

Here is an example set of .config symbols to enable or disable for kgdb:

Kdb is quite a bit more complex than the simple gdbstub sitting on top of the kernel's debug core. Kdb must implement a shell, and also adds some helper functions in other parts of the kernel, responsible for printing out interesting data such as what you would see if you ran "lsmod", or "ps". In order to build kdb into the kernel you follow the same steps as you would for kgdb.

The main config option for kdb is CONFIG_KGDB_KDB which is called "KGDB_KDB: include kdb frontend for kgdb" in the config menu. In theory you would have already also selected an I/O driver such as the CONFIG_KGDB_SERIAL_CONSOLE interface if you plan on using kdb on a serial port, when you were configuring kgdb.

If you want to use a PS/2-style keyboard with kdb, you would select CONFIG_KDB_KEYBOARD which is called "KGDB_KDB: keyboard as input device" in the config menu. The CONFIG_KDB_KEYBOARD option is not used for anything in the gdb interface to kgdb. The CONFIG_KDB_KEYBOARD option only works with kdb.

Here is an example set of .config symbols to enable/disable kdb:

The kgdboc driver was originally an abbreviation meant to stand for "kgdb over console". Today it is the primary mechanism to configure how to communicate from gdb to kgdb as well as the devices you want to use to interact with the kdb shell.

For kgdb/gdb, kgdboc is designed to work with a single serial port. It is intended to cover the circumstance where you want to use a serial console as your primary console as well as using it to perform kernel debugging. It is also possible to use kgdb on a serial port which is not designated as a system console. Kgdboc may be configured as a kernel built-in or a kernel loadable module. You can only make use of kgdbwait and early debugging if you build kgdboc into the kernel as a built-in.

Optionally you can elect to activate kms (Kernel Mode Setting) integration. When you use kms with kgdboc and you have a video driver that has atomic mode setting hooks, it is possible to enter the debugger on the graphics console. When the kernel execution is resumed, the previous graphics mode will be restored. This integration can serve as a useful tool to aid in diagnosing crashes or doing analysis of memory with kdb while allowing the full graphics console applications to run.

The Kernel command line option kgdbwait makes kgdb wait for a debugger connection during booting of a kernel. You can only use this option you compiled a kgdb I/O driver into the kernel and you specified the I/O driver configuration as a kernel command line option. The kgdbwait parameter should always follow the configuration parameter for the kgdb I/O driver in the kernel command line else the I/O driver will not be configured prior to asking the kernel to use it to wait.

The kernel will stop and wait as early as the I/O driver and architecture allows when you use this option. If you build the kgdb I/O driver as a loadable kernel module kgdbwait will not do anything.

The kgdbcon feature allows you to see printk() messages inside gdb while gdb is connected to the kernel. Kdb does not make use of the kgdbcon feature.

Kgdb supports using the gdb serial protocol to send console messages to the debugger when the debugger is connected and running. There are two ways to activate this feature.

IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an active system console. An example incorrect usage is console=ttyS0,115200 kgdboc=ttyS0 kgdbcon

It is possible to use this option with kgdboc on a tty that is not a system console.

The kgdbreboot feature allows you to change how the debugger deals with the reboot notification. You have 3 choices for the behavior. The default behavior is always set to 0.

This is a quick example of how to use kdb.

This is a quick example of how to use kdb with a keyboard.

Remember if you continue in gdb, and need to "break in" again, you need to issue an other sysrq-g. It is easy to create a simple entry point by putting a breakpoint at sys_sync and then you can run "sync" from a shell or script to break into the debugger.

It is possible to run a limited set of kdb commands from gdb, using the gdb monitor command. You don't want to execute any of the run control or breakpoint operations, because it can disrupt the state of the kernel debugger. You should be using gdb for breakpoints and run control operations if you have gdb connected. The more useful commands to run are things like lsmod, dmesg, ps or possibly some of the memory information commands. To see all the kdb commands you can run monitor help.

Example:

(gdb) monitor ps
1 idle process (state I) and
27 sleeping system daemon (state M) processes suppressed,
use 'ps A' to see all.
Task Addr       Pid   Parent [*] cpu State Thread     Command

0xc78291d0        1        0  0    0   S  0xc7829404  init
0xc7954150      942        1  0    0   S  0xc7954384  dropbear
0xc78789c0      944        1  0    0   S  0xc7878bf4  sh
(gdb)
  

The kernel debugger is organized into a number of components:

If you are intent on adding kgdb architecture specific support for a new architecture, the architecture should define HAVE_ARCH_KGDB in the architecture specific Kconfig file. This will enable kgdb for the architecture, and at that point you must create an architecture specific kgdb implementation.

There are a few flags which must be set on every architecture in their <asm/kgdb.h> file. These are:

There are also the following functions for the common backend, found in kernel/kgdb.c, that must be supplied by the architecture-specific backend unless marked as (optional), in which case a default function maybe used if the architecture does not need to provide a specific implementation.

struct kgdb_arch {
  unsigned char gdb_bpt_instr[BREAK_INSTR_SIZE];
  unsigned long flags;
  int (* set_breakpoint) (unsigned long, char *);
  int (* remove_breakpoint) (unsigned long, char *);
  int (* set_hw_breakpoint) (unsigned long, int, enum kgdb_bptype);
  int (* remove_hw_breakpoint) (unsigned long, int, enum kgdb_bptype);
  void (* disable_hw_break) (struct pt_regs *regs);
  void (* remove_all_hw_break) (void);
  void (* correct_hw_break) (void);
  void (* enable_nmi) (bool on);
};  

struct kgdb_io {
  const char * name;
  int (* read_char) (void);
  void (* write_char) (u8);
  void (* flush) (void);
  int (* init) (void);
  void (* pre_exception) (void);
  void (* post_exception) (void);
  int is_console;
};