diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2010-05-21 11:08:05 -0700 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2010-05-21 11:08:05 -0700 |
commit | 90b9a32d8f441369b2f97a765d2d957b531eb653 (patch) | |
tree | 3146d251a983ba12226e75c121613de6f051af8b | |
parent | 8b108c609adefd98577c35f0a41497a610041a6c (diff) | |
parent | 4402c153cb9c549cd21d6007ef0dfac50c8d148d (diff) |
Merge branch 'kdb-merge' of git://git.kernel.org/pub/scm/linux/kernel/git/jwessel/linux-2.6-kgdb
* 'kdb-merge' of git://git.kernel.org/pub/scm/linux/kernel/git/jwessel/linux-2.6-kgdb: (25 commits)
kdb,debug_core: Allow the debug core to receive a panic notification
MAINTAINERS: update kgdb, kdb, and debug_core info
debug_core,kdb: Allow the debug core to process a recursive debug entry
printk,kdb: capture printk() when in kdb shell
kgdboc,kdb: Allow kdb to work on a non open console port
kgdb: Add the ability to schedule a breakpoint via a tasklet
mips,kgdb: kdb low level trap catch and stack trace
powerpc,kgdb: Introduce low level trap catching
x86,kgdb: Add low level debug hook
kgdb: remove post_primary_code references
kgdb,docs: Update the kgdb docs to include kdb
kgdboc,keyboard: Keyboard driver for kdb with kgdb
kgdb: gdb "monitor" -> kdb passthrough
sparc,sunzilog: Add console polling support for sunzilog serial driver
sh,sh-sci: Use NO_POLL_CHAR in the SCIF polled console code
kgdb,8250,pl011: Return immediately from console poll
kgdb: core changes to support kdb
kdb: core for kgdb back end (2 of 2)
kdb: core for kgdb back end (1 of 2)
kgdb,blackfin: Add in kgdb_arch_set_pc for blackfin
...
51 files changed, 9240 insertions, 2016 deletions
diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl index 5cff41a5fa7c..55f12ac37acd 100644 --- a/Documentation/DocBook/kgdb.tmpl +++ b/Documentation/DocBook/kgdb.tmpl @@ -4,7 +4,7 @@ <book id="kgdbOnLinux"> <bookinfo> - <title>Using kgdb and the kgdb Internals</title> + <title>Using kgdb, kdb and the kernel debugger internals</title> <authorgroup> <author> @@ -17,33 +17,8 @@ </affiliation> </author> </authorgroup> - - <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rini</surname> - <affiliation> - <address> - <email>trini@kernel.crashing.org</email> - </address> - </affiliation> - </author> - </authorgroup> - - <authorgroup> - <author> - <firstname>Amit S.</firstname> - <surname>Kale</surname> - <affiliation> - <address> - <email>amitkale@linsyssoft.com</email> - </address> - </affiliation> - </author> - </authorgroup> - <copyright> - <year>2008</year> + <year>2008,2010</year> <holder>Wind River Systems, Inc.</holder> </copyright> <copyright> @@ -69,41 +44,76 @@ <chapter id="Introduction"> <title>Introduction</title> <para> - 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 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. + The kernel has two different debugger front ends (kdb and kgdb) + which interface to the debug core. It is possible to use either + of the debugger front ends and dynamically transition between them + if you configure the kernel properly at compile and runtime. + </para> + <para> + Kdb is simplistic shell-style interface which you can use on a + system console with a keyboard or serial console. You can use it + to inspect memory, registers, process lists, dmesg, and even set + breakpoints to stop in a certain location. Kdb is not a source + level debugger, although you can set breakpoints and execute some + basic kernel run control. Kdb is mainly aimed at doing some + analysis to aid in development or diagnosing kernel problems. You + can access some symbols by name in kernel built-ins or in kernel + modules if the code was built + with <symbol>CONFIG_KALLSYMS</symbol>. + </para> + <para> + Kgdb is intended to be used as a source level debugger for the + 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 call stack + information similar to the way an application developer would use + gdb to debug an application. It is possible to place breakpoints + in kernel code and perform some limited execution stepping. </para> <para> - Two machines are required for using kgdb. One of these machines is a - development machine and the other is a test machine. The kernel - to be debugged runs on the test machine. The development machine - 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. 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. + Two machines are required for using kgdb. One of these machines is + a development machine and the other is the target machine. The + kernel to be debugged runs on the target machine. The development + machine 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. The type of connection a + developer makes with gdb depends on the availability of kgdb I/O + modules compiled as built-ins or loadable kernel modules in the test + machine's kernel. </para> </chapter> <chapter id="CompilingAKernel"> - <title>Compiling a kernel</title> + <title>Compiling a kernel</title> + <para> + <itemizedlist> + <listitem><para>In order to enable compilation of kdb, you must first enable kgdb.</para></listitem> + <listitem><para>The kgdb test compile options are described in the kgdb test suite chapter.</para></listitem> + </itemizedlist> + </para> + <sect1 id="CompileKGDB"> + <title>Kernel config options for kgdb</title> <para> 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". + "Kernel debugging" select "KGDB: kernel debugger". + </para> + <para> + 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 <symbol>CONFIG_DEBUG_INFO</symbol> which is called "Compile the + kernel with debug info" in the config menu. </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. + <symbol>CONFIG_FRAME_POINTER</symbol> 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. </para> <para> If the architecture that you are using supports the kernel option @@ -116,38 +126,160 @@ this option. </para> <para> - 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, see following - chapter. + 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". </para> - <para> - The kgdb test compile options are described in the kgdb test suite chapter. + <para>Here is an example set of .config symbols to enable or + disable for kgdb: + <itemizedlist> + <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem> + <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem> + <listitem><para>CONFIG_KGDB=y</para></listitem> + <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem> + </itemizedlist> </para> - + </sect1> + <sect1 id="CompileKDB"> + <title>Kernel config options for kdb</title> + <para>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. + </para> + <para>The main config option for kdb + is <symbol>CONFIG_KGDB_KDB</symbol> 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. + </para> + <para>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. + </para> + <para>Here is an example set of .config symbols to enable/disable kdb: + <itemizedlist> + <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem> + <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem> + <listitem><para>CONFIG_KGDB=y</para></listitem> + <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem> + <listitem><para>CONFIG_KGDB_KDB=y</para></listitem> + <listitem><para>CONFIG_KDB_KEYBOARD=y</para></listitem> + </itemizedlist> + </para> + </sect1> </chapter> - <chapter id="EnableKGDB"> - <title>Enable kgdb for debugging</title> - <para> - In order to use kgdb you must activate it by passing configuration - information to one of the kgdb I/O drivers. If you do not pass any - configuration information kgdb will not do anything at all. Kgdb - will only actively hook up to the kernel trap hooks if a kgdb I/O - driver is loaded and configured. If you unconfigure a kgdb I/O - driver, kgdb will unregister all the kernel hook points. + <chapter id="kgdbKernelArgs"> + <title>Kernel Debugger Boot Arguments</title> + <para>This section describes the various runtime kernel + parameters that affect the configuration of the kernel debugger. + The following chapter covers using kdb and kgdb as well as + provides some examples of the configuration parameters.</para> + <sect1 id="kgdboc"> + <title>Kernel parameter: kgdboc</title> + <para>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. + </para> + <para>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 <constant>kgdbwait</constant> and early + debugging if you build kgdboc into the kernel as a built-in. </para> + <sect2 id="kgdbocArgs"> + <title>kgdboc arguments</title> + <para>Usage: <constant>kgdboc=[kbd][[,]serial_device][,baud]</constant></para> + <sect3 id="kgdbocArgs1"> + <title>Using loadable module or built-in</title> <para> - All drivers can be reconfigured at run time, if - <symbol>CONFIG_SYSFS</symbol> and <symbol>CONFIG_MODULES</symbol> - are enabled, by echo'ing a new config string to - <constant>/sys/module/<driver>/parameter/<option></constant>. - The driver can be unconfigured by passing an empty string. You cannot - change the configuration while the debugger is attached. Make sure - to detach the debugger with the <constant>detach</constant> command - prior to trying unconfigure a kgdb I/O driver. + <orderedlist> + <listitem><para>As a kernel built-in:</para> + <para>Use the kernel boot argument: <constant>kgdboc=<tty-device>,[baud]</constant></para></listitem> + <listitem> + <para>As a kernel loadable module:</para> + <para>Use the command: <constant>modprobe kgdboc kgdboc=<tty-device>,[baud]</constant></para> + <para>Here are two examples of how you might formate the kgdboc + string. The first is for an x86 target using the first serial port. + The second example is for the ARM Versatile AB using the second + serial port. + <orderedlist> + <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem> + <listitem><para><constant>kgdboc=ttyAMA1,115200</constant></para></listitem> + </orderedlist> </para> + </listitem> + </orderedlist></para> + </sect3> + <sect3 id="kgdbocArgs2"> + <title>Configure kgdboc at runtime with sysfs</title> + <para>At run time you can enable or disable kgdboc by echoing a + parameters into the sysfs. Here are two examples:</para> + <orderedlist> + <listitem><para>Enable kgdboc on ttyS0</para> + <para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + <listitem><para>Disable kgdboc</para> + <para><constant>echo "" > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + </orderedlist> + <para>NOTE: You do not need to specify the baud if you are + configuring the console on tty which is already configured or + open.</para> + </sect3> + <sect3 id="kgdbocArgs3"> + <title>More examples</title> + <para>You can configure kgdboc to use the keyboard, and or a serial device + depending on if you are using kdb and or kgdb, in one of the + following scenarios. + <orderedlist> + <listitem><para>kdb and kgdb over only a serial port</para> + <para><constant>kgdboc=<serial_device>[,baud]</constant></para> + <para>Example: <constant>kgdboc=ttyS0,115200</constant></para> + </listitem> + <listitem><para>kdb and kgdb with keyboard and a serial port</para> + <para><constant>kgdboc=kbd,<serial_device>[,baud]</constant></para> + <para>Example: <constant>kgdboc=kbd,ttyS0,115200</constant></para> + </listitem> + <listitem><para>kdb with a keyboard</para> + <para><constant>kgdboc=kbd</constant></para> + </listitem> + </orderedlist> + </para> + </sect3> + <para>NOTE: Kgdboc does not support interrupting the target via the + gdb remote protocol. You must manually send a sysrq-g unless you + have a proxy that splits console output to a terminal program. + A console proxy has a separate TCP port for the debugger and a separate + TCP port for the "human" console. The proxy can take care of sending + the sysrq-g for you. + </para> + <para>When using kgdboc with no debugger proxy, you can end up + connecting the debugger at one of two entry points. If an + exception occurs after you have loaded kgdboc, a message should + print on the console stating it is waiting for the debugger. In + this case you disconnect your terminal program and then connect the + debugger in its place. If you want to interrupt the target system + and forcibly enter a debug session you have to issue a Sysrq + sequence and then type the letter <constant>g</constant>. Then + you disconnect the terminal session and connect gdb. Your options + if you don't like this are to hack gdb to send the sysrq-g for you + as well as on the initial connect, or to use a debugger proxy that + allows an unmodified gdb to do the debugging. + </para> + </sect2> + </sect1> <sect1 id="kgdbwait"> <title>Kernel parameter: kgdbwait</title> <para> @@ -162,103 +294,204 @@ </para> <para> The kernel will stop and wait as early as the I/O driver and - architecture will allow when you use this option. If you build the - kgdb I/O driver as a kernel module kgdbwait will not do anything. + 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. </para> </sect1> - <sect1 id="kgdboc"> - <title>Kernel parameter: kgdboc</title> - <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. 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. Of course you can - also use kgdboc without assigning a console to the same port. + <sect1 id="kgdbcon"> + <title>Kernel parameter: kgdbcon</title> + <para> 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. + </para> + <para>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. + <orderedlist> + <listitem><para>Activate with the kernel command line option:</para> + <para><constant>kgdbcon</constant></para> + </listitem> + <listitem><para>Use sysfs before configuring an I/O driver</para> + <para> + <constant>echo 1 > /sys/module/kgdb/parameters/kgdb_use_con</constant> + </para> + <para> + NOTE: If you do this after you configure the kgdb I/O driver, the + setting will not take effect until the next point the I/O is + reconfigured. + </para> + </listitem> + </orderedlist> + <para>IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an + active system console. An example incorrect usage is <constant>console=ttyS0,115200 kgdboc=ttyS0 kgdbcon</constant> + </para> + <para>It is possible to use this option with kgdboc on a tty that is not a system console. + </para> </para> - <sect2 id="UsingKgdboc"> - <title>Using kgdboc</title> - <para> - You can configure kgdboc via sysfs or a module or kernel boot line - parameter depending on if you build with CONFIG_KGDBOC as a module - or built-in. - <orderedlist> - <listitem><para>From the module load or build-in</para> - <para><constant>kgdboc=<tty-device>,[baud]</constant></para> + </sect1> + </chapter> + <chapter id="usingKDB"> + <title>Using kdb</title> <para> - The example here would be if your console port was typically ttyS0, you would use something like <constant>kgdboc=ttyS0,115200</constant> or on the ARM Versatile AB you would likely use <constant>kgdboc=ttyAMA0,115200</constant> + </para> + <sect1 id="quickKDBserial"> + <title>Quick start for kdb on a serial port</title> + <para>This is a quick example of how to use kdb.</para> + <para><orderedlist> + <listitem><para>Boot kernel with arguments: + <itemizedlist> + <listitem><para><constant>console=ttyS0,115200 kgdboc=ttyS0,115200</constant></para></listitem> + </itemizedlist></para> + <para>OR</para> + <para>Configure kgdboc after the kernel booted; assuming you are using a serial port console: + <itemizedlist> + <listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + </itemizedlist> </para> </listitem> - <listitem><para>From sysfs</para> - <para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para> + <listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para> + <itemizedlist> + <listitem><para>When logged in as root or with a super user session you can run:</para> + <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> + <listitem><para>Example using minicom 2.2</para> + <para>Press: <constant>Control-a</constant></para> + <para>Press: <constant>f</constant></para> + <para>Press: <constant>g</constant></para> </listitem> - </orderedlist> - </para> - <para> - NOTE: Kgdboc does not support interrupting the target via the - gdb remote protocol. You must manually send a sysrq-g unless you - have a proxy that splits console output to a terminal problem and - has a separate port for the debugger to connect to that sends the - sysrq-g for you. + <listitem><para>When you have telneted to a terminal server that supports sending a remote break</para> + <para>Press: <constant>Control-]</constant></para> + <para>Type in:<constant>send break</constant></para> + <para>Press: <constant>Enter</constant></para> + <para>Press: <constant>g</constant></para> + </listitem> + </itemizedlist> + </listitem> + <listitem><para>From the kdb prompt you can run the "help" command to see a complete list of the commands that are available.</para> + <para>Some useful commands in kdb include: + <itemizedlist> + <listitem><para>lsmod -- Shows where kernel modules are loaded</para></listitem> + <listitem><para>ps -- Displays only the active processes</para></listitem> + <listitem><para>ps A -- Shows all the processes</para></listitem> + <listitem><para>summary -- Shows kernel version info and memory usage</para></listitem> + <listitem><para>bt -- Get a backtrace of the current process using dump_stack()</para></listitem> + <listitem><para>dmesg -- View the kernel syslog buffer</para></listitem> + <listitem><para>go -- Continue the system</para></listitem> + </itemizedlist> </para> - <para>When using kgdboc with no debugger proxy, you can end up - connecting the debugger for one of two entry points. If an - exception occurs after you have loaded kgdboc a message should print - on the console stating it is waiting for the debugger. In case you - disconnect your terminal program and then connect the debugger in - its place. If you want to interrupt the target system and forcibly - enter a debug session you have to issue a Sysrq sequence and then - type the letter <constant>g</constant>. Then you disconnect the - terminal session and connect gdb. Your options if you don't like - this are to hack gdb to send the sysrq-g for you as well as on the - initial connect, or to use a debugger proxy that allows an - unmodified gdb to do the debugging. + </listitem> + <listitem> + <para>When you are done using kdb you need to consider rebooting the + system or using the "go" command to resuming normal kernel + execution. If you have paused the kernel for a lengthy period of + time, applications |