kgdb is a source level debugger for linux kernel. It is used along
with gdb to debug a linux kernel. The expectation is that gdb can
be used to "break in" to the kernel to inspect memory, variables
- and look through a cal stack information similar to what an
+ and look through call stack information similar to what an
application developer would use gdb for. It is possible to place
breakpoints in kernel code and perform some limited execution
stepping.
runs an instance of gdb against the vmlinux file which contains
the symbols (not boot image such as bzImage, zImage, uImage...).
In gdb the developer specifies the connection parameters and
- connects to kgdb. Depending on which kgdb I/O modules exist in
- the kernel for a given architecture, it may be possible to debug
- the test machine's kernel with the development machine using a
- rs232 or ethernet connection.
+ connects to kgdb. The type of connection a developer makes with
+ gdb depends on the availability of kgdb I/O modules compiled as
+ builtin's or kernel modules in the test machine's kernel.
</para>
</chapter>
<chapter id="CompilingAKernel">
<title>Compiling a kernel</title>
<para>
- To enable <symbol>CONFIG_KGDB</symbol>, look under the "Kernel debugging"
- and then select "KGDB: kernel debugging with remote gdb".
+ To enable <symbol>CONFIG_KGDB</symbol> you should first turn on
+ "Prompt for development and/or incomplete code/drivers"
+ (CONFIG_EXPERIMENTAL) in "General setup", then under the
+ "Kernel debugging" select "KGDB: kernel debugging with remote gdb".
+ </para>
+ <para>
+ It is advised, but not required that you turn on the
+ CONFIG_FRAME_POINTER kernel option. This option inserts code to
+ into the compiled executable which saves the frame information in
+ registers or on the stack at different points which will allow a
+ debugger such as gdb to more accurately construct stack back traces
+ while debugging the kernel.
+ </para>
+ <para>
+ 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.
</para>
<para>
Next you should choose one of more I/O drivers to interconnect debugging
<para>
The kgdboc driver was originally an abbreviation meant to stand for
"kgdb over console". Kgdboc is designed to work with a single
- serial port as example, and it was meant to cover the circumstance
+ serial port. It was meant to cover the circumstance
where you wanted to use a serial console as your primary console as
- well as using it to perform kernel debugging.
+ well as using it to perform kernel debugging. Of course you can
+ also use kgdboc without assigning a console to the same port.
</para>
<sect2 id="UsingKgdboc">
<title>Using kgdboc</title>
unmodified gdb to do the debugging.
</para>
</sect2>
- <sect2 id="kgdbocDesign">
- <title>kgdboc internals</title>
- <para>
- The kgdboc driver is actually a very thin driver that relies on the
- underlying low level to the hardware driver having "polling hooks"
- which the to which the tty driver is attached. In the initial
- implementation of kgdboc it the serial_core was changed to expose a
- low level uart hook for doing polled mode reading and writing of a
- single character while in an atomic context. When kgdb makes an I/O
- request to the debugger, kgdboc invokes a call back in the serial
- core which in turn uses the call back in the uart driver. It is
- certainly possible to extend kgdboc to work with non-uart based
- consoles in the future.
- </para>
- <para>
- When using kgdboc with a uart, the uart driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting>
-#ifdef CONFIG_CONSOLE_POLL
- .poll_get_char = serial8250_get_poll_char,
- .poll_put_char = serial8250_put_poll_char,
-#endif
- </programlisting>
- Any implementation specifics around creating a polling driver use the
- <constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above.
- Keep in mind that polling hooks have to be implemented in such a way
- that they can be called from an atomic context and have to restore
- the state of the uart chip on return such that the system can return
- to normal when the debugger detaches. You need to be very careful
- with any kind of lock you consider, because failing here is most
- going to mean pressing the reset button.
- </para>
- </sect2>
</sect1>
<sect1 id="kgdbcon">
<title>Kernel parameter: kgdbcon</title>
</para>
<para>
IMPORTANT NOTE: Using this option with kgdb over the console
- (kgdboc) or kgdb over ethernet (kgdboe) is not supported.
+ (kgdboc) is not supported.
</para>
</sect1>
</chapter>
(gdb) target remote /dev/ttyS0
</programlisting>
<para>
- Example (kgdb to a terminal server):
- </para>
- <programlisting>
- % gdb ./vmlinux
- (gdb) target remote udp:192.168.2.2:6443
- </programlisting>
- <para>
- Example (kgdb over ethernet):
+ Example (kgdb to a terminal server on tcp port 2012):
</para>
<programlisting>
% gdb ./vmlinux
- (gdb) target remote udp:192.168.2.2:6443
+ (gdb) target remote 192.168.2.2:2012
</programlisting>
<para>
Once connected, you can debug a kernel the way you would debug an
seriously wrong while debugging, it will most often be the case
that you want to enable gdb to be verbose about its target
communications. You do this prior to issuing the <constant>target
- remote</constant> command by typing in: <constant>set remote debug 1</constant>
+ remote</constant> command by typing in: <constant>set debug remote 1</constant>
</para>
</chapter>
<chapter id="KGDBTestSuite">
</para>
</chapter>
<chapter id="CommonBackEndReq">
+ <title>KGDB Internals</title>
+ <sect1 id="kgdbArchitecture">
<title>Architecture Specifics</title>
<para>
Kgdb is organized into three basic components:
</listitem>
<listitem><para>kgdb I/O driver</para>
<para>
- Each kgdb I/O driver has to provide an configuration
- initialization, and cleanup handler for when it
- unloads/unconfigures. Any given kgdb I/O driver has to operate
- very closely with the hardware and must do it in such a way that
- does not enable interrupts or change other parts of the system
- context without completely restoring them. Every kgdb I/O
- driver must provide a read and write character interface. The
- kgdb core will repeatedly "poll" a kgdb I/O driver for characters
- when it needs input. The I/O driver is expected to return
- immediately if there is no data available. Doing so allows for
- the future possibility to touch watch dog hardware in such a way
- as to have a target system not reset when these are enabled.
+ Each kgdb I/O driver has to provide an implemenation for the following:
+ <itemizedlist>
+ <listitem><para>configuration via builtin or module</para></listitem>
+ <listitem><para>dynamic configuration and kgdb hook registration calls</para></listitem>
+ <listitem><para>read and write character interface</para></listitem>
+ <listitem><para>A cleanup handler for unconfiguring from the kgdb core</para></listitem>
+ <listitem><para>(optional) Early debug methodology</para></listitem>
+ </itemizedlist>
+ Any given kgdb I/O driver has to operate very closely with the
+ hardware and must do it in such a way that does not enable
+ interrupts or change other parts of the system context without
+ completely restoring them. The kgdb core will repeatedly "poll"
+ a kgdb I/O driver for characters when it needs input. The I/O
+ driver is expected to return immediately if there is no data
+ available. Doing so allows for the future possibility to touch
+ watch dog hardware in such a way as to have a target system not
+ reset when these are enabled.
</para>
</listitem>
</orderedlist>
does not need to provide a specific implementation.
</para>
!Iinclude/linux/kgdb.h
+ </sect1>
+ <sect1 id="kgdbocDesign">
+ <title>kgdboc internals</title>
+ <para>
+ The kgdboc driver is actually a very thin driver that relies on the
+ underlying low level to the hardware driver having "polling hooks"
+ which the to which the tty driver is attached. In the initial
+ implementation of kgdboc it the serial_core was changed to expose a
+ low level uart hook for doing polled mode reading and writing of a
+ single character while in an atomic context. When kgdb makes an I/O
+ request to the debugger, kgdboc invokes a call back in the serial
+ core which in turn uses the call back in the uart driver. It is
+ certainly possible to extend kgdboc to work with non-uart based
+ consoles in the future.
+ </para>
+ <para>
+ When using kgdboc with a uart, the uart driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting>
+#ifdef CONFIG_CONSOLE_POLL
+ .poll_get_char = serial8250_get_poll_char,
+ .poll_put_char = serial8250_put_poll_char,
+#endif
+ </programlisting>
+ Any implementation specifics around creating a polling driver use the
+ <constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above.
+ Keep in mind that polling hooks have to be implemented in such a way
+ that they can be called from an atomic context and have to restore
+ the state of the uart chip on return such that the system can return
+ to normal when the debugger detaches. You need to be very careful
+ with any kind of lock you consider, because failing here is most
+ going to mean pressing the reset button.
+ </para>
+ </sect1>
</chapter>
<chapter id="credits">
<title>Credits</title>
<orderedlist>
<listitem><para>Amit Kale<email>amitkale@linsyssoft.com</email></para></listitem>
<listitem><para>Tom Rini<email>trini@kernel.crashing.org</email></para></listitem>
- <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem>
</orderedlist>
+ In March 2008 this document was completely rewritten by:
+ <itemizedlist>
+ <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem>
+ </itemizedlist>
</para>
</chapter>
</book>
git://ftp.safe.ca / safe / jmp / linux-2.6 / blobdiff