KGDB
Documentation
For versions upto 2.2
Copyright © 2005, LinSysSoft Technologies Pvt. Ltd. All rights reserved.
LinSysSoft Technologies Pvt. Ltd.
Table of Contents
Introduction: ..............................................................................................................................................................4
Using KGDB..............................................................................................................................................................5
Requirements.................................................................................................................. ...................................................................5
Hardware Requirements ................................................................................................................5
Software Requirements ................................................................................................................5
Hardware Setup ...........................................................................................................................5
Preparing a kernel..........................................................................................................................................................................6
Preparing a kernel ..........................................................................................................................6
Connecting to Debug Kernel ..........................................................................................................7
Preparing modules for debugging..........................................................................................................................................9
Requirements and Preparations on development and test machines................................................9
Compiling and installing modules...............................................................................................9
Module debugging setup with KGDB versions <= 1.8................................................................9
Loading modules............................................................................................................................10
Loading a module file ...................................................................................................................11
Unloading and loading modules ..................................................................................................12
Unloading a module and loading it again in kgdb 1.8 and earlier.............................................13
Debugging a kernel.......................................................................................................................................................................14
Using gdb for kernel debugging.....................................................................................................14
Killing or terminating GDB.......................................................................................................14
Test machine reboot...................................................................................................................14
Controlling the execution of a kernel.............................................................................................15
Stopping kernel execution..........................................................................................................15
Continuing kernel execution......................................................................................................15
Breakpoints................................................................................................................................15
Stepping through code...............................................................................................................15
Stack Trace ..................................................................................................................................15
Inline functions .............................................................................................................................16
Thread Analysis ............................................................................................................................18
Caveats in using gdb thread model with kernel threads:...........................................................21
Copyright © 2005, LinSysSoft Technologies Pvt. Ltd. All rights reserved.
Watchpoints .................................................................................................................................21
Debugging modules.......................................................................................................................................................................23
Inline functions ............................................................................................................................23
Unloading a module and loading it again ......................................................................................23
Working of loadmodule.sh ...........................................................................................................23
Object file sections.....................................................................................................................23
Loading of the module...............................................................................................................25
Generation of gdb script.............................................................................................................26
Loading object files into gdb.....................................................................................................26
Debugging init_module ...............................................................................................................27
For kgdb versions 1.9 and later..................................................................................................27
For kgdb versions 1.8 and earlier...............................................................................................27
Architecture Dependencies......................................................................................................................................................27
Debugging on x86_64 ..................................................................................................................27
Debugging on PowerPC ..............................................................................................................29
Compiling a kernel with kgdb....................................................................................................29
Debugging on s390 ......................................................................................................................29
Kgdb stub for Linux/s390 running under VM (ver 0.2.0).........................................................29
Requirements..................................................................................................................................................................................29
x86 or s390 machine running Linux...............................................................................................29
Basic Usage................................................................................................................................29
Thread Debugging.....................................................................................................................31
Tips............................................................................................................................................34
gdb patch....................................................................................................................................34
Miscellaneous ........................................................................................................................................................35
GDB Macros ...................................................................... ..............................................................................................................35
Hardware debugging.......................................................................................................................35
Shell Scripts ..................................................................................................................................................................................36
loadmodule.sh.................................................................................................................................36
disasfun.sh......................................................................................................................................36
Asserts ............................................................................................... .............................................................................................37
Kgdb asserts....................................................................................................................................38
Kernel asserts..................................................................................................................................38
Assertions in modules.....................................................................................................................38
Troubleshooting ....................................................................................................................................................40
Connection problems...................................................................................................................................................................40
Problems with breakpoints......................................................................................................................................................40
Copyright © 2005, LinSysSoft Technologies Pvt. Ltd. All rights reserved.
Introduction:
KGDB is a source level debugger for linux kernel. It is used along with gdb to debug linux kernel. Kernel
developers can debug a kernel similar to application programs with use of KGDB. It makes it possible to
place breakpoints in kernel code, step through the code and observe variables.
Two machines are required for using KGDB. One of these machines is a development machine and the
other is a test machine. The machines are connected through a serial line, a null-modem cable which
connects their serial ports. The kernel to be debugged runs on the test machine. gdb runs on the
development machine. The serial line is used by gdb to communicate to the kernel being debugged.
KGDB is available for i386, x86_64, ppc and s390 architectures.
KGDB is a kernel patch. It has to be applied to a linux kernel to enable kernel debugging. KGDB patch
adds following components to a kernel
● gdb stub - The gdb stub is heart of the debugger. It is the part that handles requests coming from
gdb on the development machine. It has control of all processors in the target machine when kernel
running on it is inside the debugger.
● modifications to fault handlers - Kernel gives control to debugger when an unexpected fault occurs.
A kernel which does not contain gdb panics on unexpected faults. Modifications to fault handles
allow kernel developers to analyze unexpected faults.
● serial communication - This component uses a serial driver in the kernel and offers an interface to
gdb stub in the kernel. It is responsible for sending and receiving data from a serial line. This component
is also responsible for handling control break request sent by gdb.
KGDB is available for x86 architecture on several versions of linux kernel from 2.4.6 to 2.6.13. Please go to
downloads page for getting it.
Copyright © 2005, LinSysSoft Technologies Pvt. Ltd. All rights reserved.
Using KGDB
Requirements
Hardware Requirements
Two x86 machines are required for using KGDB. One of the machines runs a kernel to be debugged.
The other machine runs gdb. The machine that runs the kernel to be debugged is called the Test
machine while the machine that runs gdb is called the Development machine.
A single development machine can be used with several test machines. The architecture of development
and test machine can be different. But the architecture of test machine and the architecture of the kernel
being debugged should match. The development machine will run a copy of GDB per test machine. The
development machine should have at least 128MB RAM so that loading debugging info into gdb does
not result into too much of swap space usage.
A serial line is required between the development and the test machine. For the serial line to be established,
machines need one serial port each. A null modem cable is required to connect serial ports of the machines.
Recent versions of KGDB work over ethernet also. If KGDB is run over ethernet, a serial line is not required.
If debugging of modules is needed, the two machines should be connected through a network. The network
connection is required by rcp and rsh commands used by module debugging utilities. KGDB itself does not
need a network connection. It always needs a serial line only. It's also convenient to have the machines
connected through a network for looking into the test machine. The documentation on this site assumes
presence of a network.
Software Requirements
Both development and test machines require redhat 7.3 or later. The test machine runs a kernel to be debugged.
For example to debug a linux kernel version 2.4.3, the test machine will run 2.4.3 kernel. The development
machine need not run any special kernel (the kernel that comes with rh6.2 will do).
If debugging of modules is not required, having above software is sufficient. For debugging of modules,
the gdb and module utilities that come with redhat 7.3 are not sufficient. The gdb to be used for debugging
modules is available from this site, whereas module utilities are available elsewhere. A shell script used to
load modules on the test machine is required to be present on the development machine. The module debugging
page gives more information on these topics.Kgdb has been tested with redhat 9 also.
Hardware Setup
The setup required for running KGDB over a serial line is described below. KGDB over ethernet doesn't
require this setup.
Null-modem cable:
Connect the machines using a null-modem cable. A null-modem cable is a 3 wire cable connecting serial
ports of the machines. It has DB9 or DB25 connectors at the end to be plugged into serial ports. Connections
with for DB25 connectors at both the ends are shown below.
Connector 1 pins - Connector 2 pins
2 (TxD) - 3 (RxD)
3 (RxD) - 2 (TxD)
7 (GND) - 7 (GND)
Copyright © 2005, LinSysSoft Technologies Pvt. Ltd. All rights reserved.
