[PATCH 08/36] docs-rst: convert kgdb DocBook to ReST
From: Mauro Carvalho Chehab
Date: Fri May 12 2017 - 10:01:13 EST
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
---
Documentation/DocBook/Makefile | 2 +-
Documentation/DocBook/kgdb.tmpl | 918 -------------------------------------
Documentation/dev-tools/index.rst | 1 +
Documentation/dev-tools/kgdb.rst | 930 ++++++++++++++++++++++++++++++++++++++
4 files changed, 932 insertions(+), 919 deletions(-)
delete mode 100644 Documentation/DocBook/kgdb.tmpl
create mode 100644 Documentation/dev-tools/kgdb.rst
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 9df94f7c2003..b9d2b88b9905 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -8,7 +8,7 @@
DOCBOOKS := z8530book.xml \
networking.xml \
- filesystems.xml lsm.xml kgdb.xml \
+ filesystems.xml lsm.xml \
libata.xml mtdnand.xml librs.xml rapidio.xml \
s390-drivers.xml scsi.xml \
sh.xml w1.xml
diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl
deleted file mode 100644
index 856ac20bf367..000000000000
--- a/Documentation/DocBook/kgdb.tmpl
+++ /dev/null
@@ -1,918 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []>
-
-<book id="kgdbOnLinux">
- <bookinfo>
- <title>Using kgdb, kdb and the kernel debugger internals</title>
-
- <authorgroup>
- <author>
- <firstname>Jason</firstname>
- <surname>Wessel</surname>
- <affiliation>
- <address>
- <email>jason.wessel@xxxxxxxxxxxxx</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
- <copyright>
- <year>2008,2010</year>
- <holder>Wind River Systems, Inc.</holder>
- </copyright>
- <copyright>
- <year>2004-2005</year>
- <holder>MontaVista Software, Inc.</holder>
- </copyright>
- <copyright>
- <year>2004</year>
- <holder>Amit S. Kale</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This file is licensed under the terms of the GNU General Public License
- version 2. This program is licensed "as is" without any warranty of any
- kind, whether express or implied.
- </para>
-
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
- <chapter id="Introduction">
- <title>Introduction</title>
- <para>
- 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 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 a 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>
- <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 look under
- "Kernel hacking" / "Kernel debugging" and 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
- <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
- CONFIG_STRICT_KERNEL_RWX, 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_STRICT_KERNEL_RWX 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 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>Here is an example set of .config symbols to enable or
- disable for kgdb:
- <itemizedlist>
- <listitem><para># CONFIG_STRICT_KERNEL_RWX 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_STRICT_KERNEL_RWX 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="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
- providing 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>
- <para>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.
- </para>
- <sect2 id="kgdbocArgs">
- <title>kgdboc arguments</title>
- <para>Usage: <constant>kgdboc=[kms][[,]kbd][[,]serial_device][,baud]</constant></para>
- <para>The order listed above must be observed if you use any of the
- optional configurations together.
- </para>
- <para>Abbreviations:
- <itemizedlist>
- <listitem><para>kms = Kernel Mode Setting</para></listitem>
- <listitem><para>kbd = Keyboard</para></listitem>
- </itemizedlist>
- </para>
- <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. The order listed above must be observed if
- you use any of the optional configurations together. Using kms +
- only gdb is generally not a useful combination.</para>
- <sect3 id="kgdbocArgs1">
- <title>Using loadable module or built-in</title>
- <para>
- <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 format 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>
- <listitem><para>kdb with kernel mode setting</para>
- <para><constant>kgdboc=kms,kbd</constant></para>
- </listitem>
- <listitem><para>kdb with kernel mode setting and kgdb over a serial port</para>
- <para><constant>kgdboc=kms,kbd,ttyS0,115200</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 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>
- </sect3>
- </sect2>
- </sect1>
- <sect1 id="kgdbwait">
- <title>Kernel parameter: kgdbwait</title>
- <para>
- The Kernel command line option <constant>kgdbwait</constant> makes
- kgdb wait for a debugger connection during booting of a kernel. You
- can only use this option if 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.
- </para>
- <para>
- 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.
- </para>
- </sect1>
- <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>
- <para>IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an
- active system console. An example of 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>
- </sect1>
- <sect1 id="kgdbreboot">
- <title>Run time parameter: kgdbreboot</title>
- <para> 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.</para>
- <orderedlist>
- <listitem><para>echo -1 > /sys/module/debug_core/parameters/kgdbreboot</para>
- <para>Ignore the reboot notification entirely.</para>
- </listitem>
- <listitem><para>echo 0 > /sys/module/debug_core/parameters/kgdbreboot</para>
- <para>Send the detach message to any attached debugger client.</para>
- </listitem>
- <listitem><para>echo 1 > /sys/module/debug_core/parameters/kgdbreboot</para>
- <para>Enter the debugger on reboot notify.</para>
- </listitem>
- </orderedlist>
- </sect1>
- </chapter>
- <chapter id="usingKDB">
- <title>Using kdb</title>
- <para>
- </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>Configure kgdboc at boot using kernel parameters:
- <itemizedlist>
- <listitem><para><constant>console=ttyS0,115200 kgdboc=ttyS0,115200</constant></para></listitem>
- </itemizedlist></para>
- <para>OR</para>
- <para>Configure kgdboc after the kernel has 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>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>
- <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>
- </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 that rely on timely networking or anything to do
- with real wall clock time could be adversely affected, so you
- should take this into consideration when using the kernel
- debugger.</para>
- </listitem>
- </orderedlist></para>
- </sect1>
- <sect1 id="quickKDBkeyboard">
- <title>Quick start for kdb using a keyboard connected console</title>
- <para>This is a quick example of how to use kdb with a keyboard.</para>
- <para><orderedlist>
- <listitem><para>Configure kgdboc at boot using kernel parameters:
- <itemizedlist>
- <listitem><para><constant>kgdboc=kbd</constant></para></listitem>
- </itemizedlist></para>
- <para>OR</para>
- <para>Configure kgdboc after the kernel has booted:
- <itemizedlist>
- <listitem><para><constant>echo kbd > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
- </itemizedlist>
- </para>
- </listitem>
- <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 a laptop keyboard</para>
- <para>Press and hold down: <constant>Alt</constant></para>
- <para>Press and hold down: <constant>Fn</constant></para>
- <para>Press and release the key with the label: <constant>SysRq</constant></para>
- <para>Release: <constant>Fn</constant></para>
- <para>Press and release: <constant>g</constant></para>
- <para>Release: <constant>Alt</constant></para>
- </listitem>
- <listitem><para>Example using a PS/2 101-key keyboard</para>
- <para>Press and hold down: <constant>Alt</constant></para>
- <para>Press and release the key with the label: <constant>SysRq</constant></para>
- <para>Press and release: <constant>g</constant></para>
- <para>Release: <constant>Alt</constant></para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>Now type in a kdb command such as "help", "dmesg", "bt" or "go" to continue kernel execution.</para>
- </listitem>
- </orderedlist></para>
- </sect1>
- </chapter>
- <chapter id="EnableKGDB">
- <title>Using kgdb / gdb</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.
- </para>
- <para> All kgdb I/O 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 to unconfigure a kgdb I/O driver.
- </para>
- <sect1 id="ConnectingGDB">
- <title>Connecting with gdb to a serial port</title>
- <orderedlist>
- <listitem><para>Configure kgdboc</para>
- <para>Configure kgdboc at boot using kernel parameters:
- <itemizedlist>
- <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem>
- </itemizedlist></para>
- <para>OR</para>
- <para>Configure kgdboc after the kernel has booted:
- <itemizedlist>
- <listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
- </itemizedlist></para>
- </listitem>
- <listitem>
- <para>Stop kernel execution (break into the debugger)</para>
- <para>In order to connect to gdb via kgdboc, the kernel must
- first be stopped. There are several ways to stop the kernel which
- include using kgdbwait as a boot argument, via a sysrq-g, or running
- the kernel until it takes an exception where it waits for the
- debugger to attach.
- <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>
- <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>
- </para>
- </listitem>
- <listitem>
- <para>Connect from gdb</para>
- <para>
- Example (using a directly connected port):
- </para>
- <programlisting>
- % gdb ./vmlinux
- (gdb) set remotebaud 115200
- (gdb) target remote /dev/ttyS0
- </programlisting>
- <para>
- Example (kgdb to a terminal server on TCP port 2012):
- </para>
- <programlisting>
- % gdb ./vmlinux
- (gdb) target remote 192.168.2.2:2012
- </programlisting>
- <para>
- Once connected, you can debug a kernel the way you would debug an
- application program.
- </para>
- <para>
- If you are having problems connecting or something is going
- 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 debug remote 1</constant>
- </para>
- </listitem>
- </orderedlist>
- <para>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 <constant>sys_sync</constant>
- and then you can run "sync" from a shell or script to break into the
- debugger.</para>
- </sect1>
- </chapter>
- <chapter id="switchKdbKgdb">
- <title>kgdb and kdb interoperability</title>
- <para>It is possible to transition between kdb and kgdb dynamically.
- The debug core will remember which you used the last time and
- automatically start in the same mode.</para>
- <sect1>
- <title>Switching between kdb and kgdb</title>
- <sect2>
- <title>Switching from kgdb to kdb</title>
- <para>
- There are two ways to switch from kgdb to kdb: you can use gdb to
- issue a maintenance packet, or you can blindly type the command $3#33.
- Whenever the kernel debugger stops in kgdb mode it will print the
- message <constant>KGDB or $3#33 for KDB</constant>. It is important
- to note that you have to type the sequence correctly in one pass.
- You cannot type a backspace or delete because kgdb will interpret
- that as part of the debug stream.
- <orderedlist>
- <listitem><para>Change from kgdb to kdb by blindly typing:</para>
- <para><constant>$3#33</constant></para></listitem>
- <listitem><para>Change from kgdb to kdb with gdb</para>
- <para><constant>maintenance packet 3</constant></para>
- <para>NOTE: Now you must kill gdb. Typically you press control-z and
- issue the command: kill -9 %</para></listitem>
- </orderedlist>
- </para>
- </sect2>
- <sect2>
- <title>Change from kdb to kgdb</title>
- <para>There are two ways you can change from kdb to kgdb. You can
- manually enter kgdb mode by issuing the kgdb command from the kdb
- shell prompt, or you can connect gdb while the kdb shell prompt is
- active. The kdb shell looks for the typical first commands that gdb
- would issue with the gdb remote protocol and if it sees one of those
- commands it automatically changes into kgdb mode.</para>
- <orderedlist>
- <listitem><para>From kdb issue the command:</para>
- <para><constant>kgdb</constant></para>
- <para>Now disconnect your terminal program and connect gdb in its place</para></listitem>
- <listitem><para>At the kdb prompt, disconnect the terminal program and connect gdb in its place.</para></listitem>
- </orderedlist>
- </sect2>
- </sect1>
- <sect1>
- <title>Running kdb commands from gdb</title>
- <para>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 <constant>monitor help</constant>.</para>
- <para>Example:
- <informalexample><programlisting>
-(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)
- </programlisting></informalexample>
- </para>
- </sect1>
- </chapter>
- <chapter id="KGDBTestSuite">
- <title>kgdb Test Suite</title>
- <para>
- When kgdb is enabled in the kernel config you can also elect to
- enable the config parameter KGDB_TESTS. Turning this on will
- enable a special kgdb I/O module which is designed to test the
- kgdb internal functions.
- </para>
- <para>
- The kgdb tests are mainly intended for developers to test the kgdb
- internals as well as a tool for developing a new kgdb architecture
- specific implementation. These tests are not really for end users
- of the Linux kernel. The primary source of documentation would be
- to look in the drivers/misc/kgdbts.c file.
- </para>
- <para>
- The kgdb test suite can also be configured at compile time to run
- the core set of tests by setting the kernel config parameter
- KGDB_TESTS_ON_BOOT. This particular option is aimed at automated
- regression testing and does not require modifying the kernel boot
- config arguments. If this is turned on, the kgdb test suite can
- be disabled by specifying "kgdbts=" as a kernel boot argument.
- </para>
- </chapter>
- <chapter id="CommonBackEndReq">
- <title>Kernel Debugger Internals</title>
- <sect1 id="kgdbArchitecture">
- <title>Architecture Specifics</title>
- <para>
- The kernel debugger is organized into a number of components:
- <orderedlist>
- <listitem><para>The debug core</para>
- <para>
- The debug core is found in kernel/debugger/debug_core.c. It contains:
- <itemizedlist>
- <listitem><para>A generic OS exception handler which includes
- sync'ing the processors into a stopped state on an multi-CPU
- system.</para></listitem>
- <listitem><para>The API to talk to the kgdb I/O drivers</para></listitem>
- <listitem><para>The API to make calls to the arch-specific kgdb implementation</para></listitem>
- <listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem>
- <listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem>
- <listitem><para>The API to invoke either the kdb or kgdb frontend to the debug core.</para></listitem>
- <listitem><para>The structures and callback API for atomic kernel mode setting.</para>
- <para>NOTE: kgdboc is where the kms callbacks are invoked.</para></listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem><para>kgdb arch-specific implementation</para>
- <para>
- This implementation is generally found in arch/*/kernel/kgdb.c.
- As an example, arch/x86/kernel/kgdb.c contains the specifics to
- implement HW breakpoint as well as the initialization to
- dynamically register and unregister for the trap handlers on
- this architecture. The arch-specific portion implements:
- <itemizedlist>
- <listitem><para>contains an arch-specific trap catcher which
- invokes kgdb_handle_exception() to start kgdb about doing its
- work</para></listitem>
- <listitem><para>translation to and from gdb specific packet format to pt_regs</para></listitem>
- <listitem><para>Registration and unregistration of architecture specific trap hooks</para></listitem>
- <listitem><para>Any special exception handling and cleanup</para></listitem>
- <listitem><para>NMI exception handling and cleanup</para></listitem>
- <listitem><para>(optional) HW breakpoints</para></listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem><para>gdbstub frontend (aka kgdb)</para>
- <para>The gdbstub is located in kernel/debug/gdbstub.c. It contains:</para>
- <itemizedlist>
- <listitem><para>All the logic to implement the gdb serial protocol</para></listitem>
- </itemizedlist>
- </listitem>
- <listitem><para>kdb frontend</para>
- <para>The kdb debugger shell is broken down into a number of
- components. The kdb core is located in kernel/debug/kdb. There
- are a number of helper functions in some of the other kernel
- components to make it possible for kdb to examine and report
- information about the kernel without taking locks that could
- cause a kernel deadlock. The kdb core contains implements the following functionality.</para>
- <itemizedlist>
- <listitem><para>A simple shell</para></listitem>
- <listitem><para>The kdb core command set</para></listitem>
- <listitem><para>A registration API to register additional kdb shell commands.</para>
- <itemizedlist>
- <listitem><para>A good example of a self-contained kdb module
- is the "ftdump" command for dumping the ftrace buffer. See:
- kernel/trace/trace_kdb.c</para></listitem>
- <listitem><para>For an example of how to dynamically register
- a new kdb command you can build the kdb_hello.ko kernel module
- from samples/kdb/kdb_hello.c. To build this example you can
- set CONFIG_SAMPLES=y and CONFIG_SAMPLE_KDB=m in your kernel
- config. Later run "modprobe kdb_hello" and the next time you
- enter the kdb shell, you can run the "hello"
- command.</para></listitem>
- </itemizedlist></listitem>
- <listitem><para>The implementation for kdb_printf() which
- emits messages directly to I/O drivers, bypassing the kernel
- log.</para></listitem>
- <listitem><para>SW / HW breakpoint management for the kdb shell</para></listitem>
- </itemizedlist>
- </listitem>
- <listitem><para>kgdb I/O driver</para>
- <para>
- Each kgdb I/O driver has to provide an implementation for the following:
- <itemizedlist>
- <listitem><para>configuration via built-in 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
- watchdog hardware in such a way as to have a target system not
- reset when these are enabled.
- </para>
- </listitem>
- </orderedlist>
- </para>
- <para>
- If you are intent on adding kgdb architecture specific support
- for a new architecture, the architecture should define
- <constant>HAVE_ARCH_KGDB</constant> 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.
- </para>
- <para>
- There are a few flags which must be set on every architecture in
- their <asm/kgdb.h> file. These are:
- <itemizedlist>
- <listitem>
- <para>
- NUMREGBYTES: The size in bytes of all of the registers, so
- that we can ensure they will all fit into a packet.
- </para>
- </listitem>
- <listitem>
- <para>
- BUFMAX: The size in bytes of the buffer GDB will read into.
- This must be larger than NUMREGBYTES.
- </para>
- </listitem>
- <listitem>
- <para>
- CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call
- flush_cache_range or flush_icache_range. On some architectures,
- these functions may not be safe to call on SMP since we keep other
- CPUs in a holding pattern.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- 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.
- </para>
-!Iinclude/linux/kgdb.h
- </sect1>
- <sect1 id="kgdbocDesign">
- <title>kgdboc internals</title>
- <sect2>
- <title>kgdboc and uarts</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"
- to which the tty driver is attached. In the initial
- implementation of kgdboc 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 callback in the serial
- core which in turn uses the callback in the UART driver.</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 likely
- going to mean pressing the reset button.
- </para>
- </sect2>
- <sect2 id="kgdbocKbd">
- <title>kgdboc and keyboards</title>
- <para>The kgdboc driver contains logic to configure communications
- with an attached keyboard. The keyboard infrastructure is only
- compiled into the kernel when CONFIG_KDB_KEYBOARD=y is set in the
- kernel configuration.</para>
- <para>The core polled keyboard driver driver for PS/2 type keyboards
- is in drivers/char/kdb_keyboard.c. This driver is hooked into the
- debug core when kgdboc populates the callback in the array
- called <constant>kdb_poll_funcs[]</constant>. The
- kdb_get_kbd_char() is the top-level function which polls hardware
- for single character input.
- </para>
- </sect2>
- <sect2 id="kgdbocKms">
- <title>kgdboc and kms</title>
- <para>The kgdboc driver contains logic to request the graphics
- display to switch to a text context when you are using
- "kgdboc=kms,kbd", provided that you have a video driver which has a
- frame buffer console and atomic kernel mode setting support.</para>
- <para>
- Every time the kernel
- debugger is entered it calls kgdboc_pre_exp_handler() which in turn
- calls con_debug_enter() in the virtual console layer. On resuming kernel
- execution, the kernel debugger calls kgdboc_post_exp_handler() which
- in turn calls con_debug_leave().</para>
- <para>Any video driver that wants to be compatible with the kernel
- debugger and the atomic kms callbacks must implement the
- mode_set_base_atomic, fb_debug_enter and fb_debug_leave operations.
- For the fb_debug_enter and fb_debug_leave the option exists to use
- the generic drm fb helper functions or implement something custom for
- the hardware. The following example shows the initialization of the
- .mode_set_base_atomic operation in
- drivers/gpu/drm/i915/intel_display.c:
- <informalexample>
- <programlisting>
-static const struct drm_crtc_helper_funcs intel_helper_funcs = {
-[...]
- .mode_set_base_atomic = intel_pipe_set_base_atomic,
-[...]
-};
- </programlisting>
- </informalexample>
- </para>
- <para>Here is an example of how the i915 driver initializes the fb_debug_enter and fb_debug_leave functions to use the generic drm helpers in
- drivers/gpu/drm/i915/intel_fb.c:
- <informalexample>
- <programlisting>
-static struct fb_ops intelfb_ops = {
-[...]
- .fb_debug_enter = drm_fb_helper_debug_enter,
- .fb_debug_leave = drm_fb_helper_debug_leave,
-[...]
-};
- </programlisting>
- </informalexample>
- </para>
- </sect2>
- </sect1>
- </chapter>
- <chapter id="credits">
- <title>Credits</title>
- <para>
- The following people have contributed to this document:
- <orderedlist>
- <listitem><para>Amit Kale<email>amitkale@xxxxxxxxxxxxxx</email></para></listitem>
- <listitem><para>Tom Rini<email>trini@xxxxxxxxxxxxxxxxxxx</email></para></listitem>
- </orderedlist>
- In March 2008 this document was completely rewritten by:
- <itemizedlist>
- <listitem><para>Jason Wessel<email>jason.wessel@xxxxxxxxxxxxx</email></para></listitem>
- </itemizedlist>
- In Jan 2010 this document was updated to include kdb.
- <itemizedlist>
- <listitem><para>Jason Wessel<email>jason.wessel@xxxxxxxxxxxxx</email></para></listitem>
- </itemizedlist>
- </para>
- </chapter>
-</book>
-
diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
index 07d881147ef3..4ac991dbddb7 100644
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -23,6 +23,7 @@ whole; patches welcome!
kmemleak
kmemcheck
gdb-kernel-debugging
+ kgdb
.. only:: subproject and html
diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst
new file mode 100644
index 000000000000..ea01541806c8
--- /dev/null
+++ b/Documentation/dev-tools/kgdb.rst
@@ -0,0 +1,930 @@
+=================================================
+Using kgdb, kdb and the kernel debugger internals
+=================================================
+
+:Author: Jason Wessel
+
+Introduction
+============
+
+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.
+
+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
+``CONFIG_KALLSYMS``.
+
+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.
+
+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
+a 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.
+
+Compiling a kernel
+==================
+
+- In order to enable compilation of kdb, you must first enable kgdb.
+
+- The kgdb test compile options are described in the kgdb test suite
+ chapter.
+
+Kernel config options for kgdb
+------------------------------
+
+To enable ``CONFIG_KGDB`` you should look under "Kernel hacking" /
+"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_STRICT_KERNEL_RWX, 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_STRICT_KERNEL_RWX
+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:
+
+- # CONFIG_STRICT_KERNEL_RWX is not set
+
+- CONFIG_FRAME_POINTER=y
+
+- CONFIG_KGDB=y
+
+- CONFIG_KGDB_SERIAL_CONSOLE=y
+
+Kernel config options for kdb
+-----------------------------
+
+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:
+
+- # CONFIG_STRICT_KERNEL_RWX is not set
+
+- CONFIG_FRAME_POINTER=y
+
+- CONFIG_KGDB=y
+
+- CONFIG_KGDB_SERIAL_CONSOLE=y
+
+- CONFIG_KGDB_KDB=y
+
+- CONFIG_KDB_KEYBOARD=y
+
+Kernel Debugger Boot Arguments
+==============================
+
+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 providing some examples of the
+configuration parameters.
+
+Kernel parameter: kgdboc
+------------------------
+
+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.
+
+kgdboc arguments
+~~~~~~~~~~~~~~~~
+
+Usage: ``kgdboc=[kms][[,]kbd][[,]serial_device][,baud]``
+
+The order listed above must be observed if you use any of the optional
+configurations together.
+
+Abbreviations:
+
+- kms = Kernel Mode Setting
+
+- kbd = Keyboard
+
+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. The order listed above must be observed if you use any of the
+optional configurations together. Using kms + only gdb is generally not
+a useful combination.
+
+Using loadable module or built-in
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. As a kernel built-in:
+
+ Use the kernel boot argument: ``kgdboc=<tty-device>,[baud]``
+
+2. As a kernel loadable module:
+
+ Use the command: ``modprobe kgdboc kgdboc=<tty-device>,[baud]``
+
+ Here are two examples of how you might format 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.
+
+ 1. ``kgdboc=ttyS0,115200``
+
+ 2. ``kgdboc=ttyAMA1,115200``
+
+Configure kgdboc at runtime with sysfs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+At run time you can enable or disable kgdboc by echoing a parameters
+into the sysfs. Here are two examples:
+
+1. Enable kgdboc on ttyS0
+
+ ``echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc``
+
+2. Disable kgdboc
+
+ ``echo "" > /sys/module/kgdboc/parameters/kgdboc``
+
+NOTE: You do not need to specify the baud if you are configuring the
+console on tty which is already configured or open.
+
+More examples
+^^^^^^^^^^^^^
+
+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.
+
+1. kdb and kgdb over only a serial port
+
+ ``kgdboc=<serial_device>[,baud]``
+
+ Example: ``kgdboc=ttyS0,115200``
+
+2. kdb and kgdb with keyboard and a serial port
+
+ ``kgdboc=kbd,<serial_device>[,baud]``
+
+ Example: ``kgdboc=kbd,ttyS0,115200``
+
+3. kdb with a keyboard
+
+ ``kgdboc=kbd``
+
+4. kdb with kernel mode setting
+
+ ``kgdboc=kms,kbd``
+
+5. kdb with kernel mode setting and kgdb over a serial port
+
+ ``kgdboc=kms,kbd,ttyS0,115200``
+
+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.
+
+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 ``g``. 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.
+
+Kernel parameter: kgdbwait
+--------------------------
+
+The Kernel command line option ``kgdbwait`` makes kgdb wait for a
+debugger connection during booting of a kernel. You can only use this
+option if 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.
+
+Kernel parameter: kgdbcon
+-------------------------
+
+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.
+
+1. Activate with the kernel command line option:
+
+ ``kgdbcon``
+
+2. Use sysfs before configuring an I/O driver
+
+ ``echo 1 > /sys/module/kgdb/parameters/kgdb_use_con``
+
+ 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.
+
+IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an
+active system console. An example of 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.
+
+Run time parameter: kgdbreboot
+------------------------------
+
+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.
+
+1. echo -1 > /sys/module/debug_core/parameters/kgdbreboot
+
+ Ignore the reboot notification entirely.
+
+2. echo 0 > /sys/module/debug_core/parameters/kgdbreboot
+
+ Send the detach message to any attached debugger client.
+
+3. echo 1 > /sys/module/debug_core/parameters/kgdbreboot
+
+ Enter the debugger on reboot notify.
+
+Using kdb
+=========
+
+Quick start for kdb on a serial port
+------------------------------------
+
+This is a quick example of how to use kdb.
+
+1. Configure kgdboc at boot using kernel parameters:
+
+ - ``console=ttyS0,115200 kgdboc=ttyS0,115200``
+
+ OR
+
+ Configure kgdboc after the kernel has booted; assuming you are using
+ a serial port console:
+
+ - ``echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc``
+
+2. 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.
+
+ - When logged in as root or with a super user session you can run:
+
+ ``echo g > /proc/sysrq-trigger``
+
+ - Example using minicom 2.2
+
+ Press: ``Control-a``
+
+ Press: ``f``
+
+ Press: ``g``
+
+ - When you have telneted to a terminal server that supports sending
+ a remote break
+
+ Press: ``Control-]``
+
+ Type in:\ ``send break``
+
+ Press: ``Enter``
+
+ Press: ``g``
+
+3. From the kdb prompt you can run the "help" command to see a complete
+ list of the commands that are available.
+
+ Some useful commands in kdb include:
+
+ - lsmod -- Shows where kernel modules are loaded
+
+ - ps -- Displays only the active processes
+
+ - ps A -- Shows all the processes
+
+ - summary -- Shows kernel version info and memory usage
+
+ - bt -- Get a backtrace of the current process using dump_stack()
+
+ - dmesg -- View the kernel syslog buffer
+
+ - go -- Continue the system
+
+4. 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
+ that rely on timely networking or anything to do with real wall clock
+ time could be adversely affected, so you should take this into
+ consideration when using the kernel debugger.
+
+Quick start for kdb using a keyboard connected console
+------------------------------------------------------
+
+This is a quick example of how to use kdb with a keyboard.
+
+1. Configure kgdboc at boot using kernel parameters:
+
+ - ``kgdboc=kbd``
+
+ OR
+
+ Configure kgdboc after the kernel has booted:
+
+ - ``echo kbd > /sys/module/kgdboc/parameters/kgdboc``
+
+2. 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.
+
+ - When logged in as root or with a super user session you can run:
+
+ ``echo g > /proc/sysrq-trigger``
+
+ - Example using a laptop keyboard
+
+ Press and hold down: ``Alt``
+
+ Press and hold down: ``Fn``
+
+ Press and release the key with the label: ``SysRq``
+
+ Release: ``Fn``
+
+ Press and release: ``g``
+
+ Release: ``Alt``
+
+ - Example using a PS/2 101-key keyboard
+
+ Press and hold down: ``Alt``
+
+ Press and release the key with the label: ``SysRq``
+
+ Press and release: ``g``
+
+ Release: ``Alt``
+
+3. Now type in a kdb command such as "help", "dmesg", "bt" or "go" to
+ continue kernel execution.
+
+Using kgdb / gdb
+================
+
+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.
+
+All kgdb I/O drivers can be reconfigured at run time, if
+``CONFIG_SYSFS`` and ``CONFIG_MODULES`` are enabled, by echo'ing a new
+config string to ``/sys/module/<driver>/parameter/<option>``. 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 ``detach`` command prior to trying to unconfigure a
+kgdb I/O driver.
+
+Connecting with gdb to a serial port
+------------------------------------
+
+1. Configure kgdboc
+
+ Configure kgdboc at boot using kernel parameters:
+
+ - ``kgdboc=ttyS0,115200``
+
+ OR
+
+ Configure kgdboc after the kernel has booted:
+
+ - ``echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc``
+
+2. Stop kernel execution (break into the debugger)
+
+ In order to connect to gdb via kgdboc, the kernel must first be
+ stopped. There are several ways to stop the kernel which include
+ using kgdbwait as a boot argument, via a sysrq-g, or running the
+ kernel until it takes an exception where it waits for the debugger to
+ attach.
+
+ - When logged in as root or with a super user session you can run:
+
+ ``echo g > /proc/sysrq-trigger``
+
+ - Example using minicom 2.2
+
+ Press: ``Control-a``
+
+ Press: ``f``
+
+ Press: ``g``
+
+ - When you have telneted to a terminal server that supports sending
+ a remote break
+
+ Press: ``Control-]``
+
+ Type in:\ ``send break``
+
+ Press: ``Enter``
+
+ Press: ``g``
+
+3. Connect from gdb
+
+ Example (using a directly connected port):
+
+ ::
+
+ % gdb ./vmlinux
+ (gdb) set remotebaud 115200
+ (gdb) target remote /dev/ttyS0
+
+
+ Example (kgdb to a terminal server on TCP port 2012):
+
+ ::
+
+ % gdb ./vmlinux
+ (gdb) target remote 192.168.2.2:2012
+
+
+ Once connected, you can debug a kernel the way you would debug an
+ application program.
+
+ If you are having problems connecting or something is going 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 ``target
+ remote`` command by typing in: ``set debug remote 1``
+
+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.
+
+kgdb and kdb interoperability
+=============================
+
+It is possible to transition between kdb and kgdb dynamically. The debug
+core will remember which you used the last time and automatically start
+in the same mode.
+
+Switching between kdb and kgdb
+------------------------------
+
+Switching from kgdb to kdb
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two ways to switch from kgdb to kdb: you can use gdb to issue
+a maintenance packet, or you can blindly type the command $3#33.
+Whenever the kernel debugger stops in kgdb mode it will print the
+message ``KGDB or $3#33 for KDB``. It is important to note that you have
+to type the sequence correctly in one pass. You cannot type a backspace
+or delete because kgdb will interpret that as part of the debug stream.
+
+1. Change from kgdb to kdb by blindly typing:
+
+ ``$3#33``
+
+2. Change from kgdb to kdb with gdb
+
+ ``maintenance packet 3``
+
+ NOTE: Now you must kill gdb. Typically you press control-z and issue
+ the command: kill -9 %
+
+Change from kdb to kgdb
+~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two ways you can change from kdb to kgdb. You can manually
+enter kgdb mode by issuing the kgdb command from the kdb shell prompt,
+or you can connect gdb while the kdb shell prompt is active. The kdb
+shell looks for the typical first commands that gdb would issue with the
+gdb remote protocol and if it sees one of those commands it
+automatically changes into kgdb mode.
+
+1. From kdb issue the command:
+
+ ``kgdb``
+
+ Now disconnect your terminal program and connect gdb in its place
+
+2. At the kdb prompt, disconnect the terminal program and connect gdb in
+ its place.
+
+Running kdb commands from gdb
+-----------------------------
+
+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:
+
+.. raw:: html
+
+ <div class="informalexample">
+
+::
+
+ (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)
+
+
+.. raw:: html
+
+ </div>
+
+kgdb Test Suite
+===============
+
+When kgdb is enabled in the kernel config you can also elect to enable
+the config parameter KGDB_TESTS. Turning this on will enable a special
+kgdb I/O module which is designed to test the kgdb internal functions.
+
+The kgdb tests are mainly intended for developers to test the kgdb
+internals as well as a tool for developing a new kgdb architecture
+specific implementation. These tests are not really for end users of the
+Linux kernel. The primary source of documentation would be to look in
+the drivers/misc/kgdbts.c file.
+
+The kgdb test suite can also be configured at compile time to run the
+core set of tests by setting the kernel config parameter
+KGDB_TESTS_ON_BOOT. This particular option is aimed at automated
+regression testing and does not require modifying the kernel boot config
+arguments. If this is turned on, the kgdb test suite can be disabled by
+specifying "kgdbts=" as a kernel boot argument.
+
+Kernel Debugger Internals
+=========================
+
+Architecture Specifics
+----------------------
+
+The kernel debugger is organized into a number of components:
+
+1. The debug core
+
+ The debug core is found in kernel/debugger/debug_core.c. It
+ contains:
+
+ - A generic OS exception handler which includes sync'ing the
+ processors into a stopped state on an multi-CPU system.
+
+ - The API to talk to the kgdb I/O drivers
+
+ - The API to make calls to the arch-specific kgdb implementation
+
+ - The logic to perform safe memory reads and writes to memory while
+ using the debugger
+
+ - A full implementation for software breakpoints unless overridden
+ by the arch
+
+ - The API to invoke either the kdb or kgdb frontend to the debug
+ core.
+
+ - The structures and callback API for atomic kernel mode setting.
+
+ NOTE: kgdboc is where the kms callbacks are invoked.
+
+2. kgdb arch-specific implementation
+
+ This implementation is generally found in arch/\*/kernel/kgdb.c. As
+ an example, arch/x86/kernel/kgdb.c contains the specifics to
+ implement HW breakpoint as well as the initialization to dynamically
+ register and unregister for the trap handlers on this architecture.
+ The arch-specific portion implements:
+
+ - contains an arch-specific trap catcher which invokes
+ kgdb_handle_exception() to start kgdb about doing its work
+
+ - translation to and from gdb specific packet format to pt_regs
+
+ - Registration and unregistration of architecture specific trap
+ hooks
+
+ - Any special exception handling and cleanup
+
+ - NMI exception handling and cleanup
+
+ - (optional) HW breakpoints
+
+3. gdbstub frontend (aka kgdb)
+
+ The gdbstub is located in kernel/debug/gdbstub.c. It contains:
+
+ - All the logic to implement the gdb serial protocol
+
+4. kdb frontend
+
+ The kdb debugger shell is broken down into a number of components.
+ The kdb core is located in kernel/debug/kdb. There are a number of
+ helper functions in some of the other kernel components to make it
+ possible for kdb to examine and report information about the kernel
+ without taking locks that could cause a kernel deadlock. The kdb core
+ contains implements the following functionality.
+
+ - A simple shell
+
+ - The kdb core command set
+
+ - A registration API to register additional kdb shell commands.
+
+ - A good example of a self-contained kdb module is the "ftdump"
+ command for dumping the ftrace buffer. See:
+ kernel/trace/trace_kdb.c
+
+ - For an example of how to dynamically register a new kdb command
+ you can build the kdb_hello.ko kernel module from
+ samples/kdb/kdb_hello.c. To build this example you can set
+ CONFIG_SAMPLES=y and CONFIG_SAMPLE_KDB=m in your kernel
+ config. Later run "modprobe kdb_hello" and the next time you
+ enter the kdb shell, you can run the "hello" command.
+
+ - The implementation for kdb_printf() which emits messages directly
+ to I/O drivers, bypassing the kernel log.
+
+ - SW / HW breakpoint management for the kdb shell
+
+5. kgdb I/O driver
+
+ Each kgdb I/O driver has to provide an implementation for the
+ following:
+
+ - configuration via built-in or module
+
+ - dynamic configuration and kgdb hook registration calls
+
+ - read and write character interface
+
+ - A cleanup handler for unconfiguring from the kgdb core
+
+ - (optional) Early debug methodology
+
+ 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 watchdog hardware in such a way
+ as to have a target system not reset when these are enabled.
+
+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:
+
+- NUMREGBYTES: The size in bytes of all of the registers, so that we
+ can ensure they will all fit into a packet.
+
+- BUFMAX: The size in bytes of the buffer GDB will read into. This must
+ be larger than NUMREGBYTES.
+
+- CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call
+ flush_cache_range or flush_icache_range. On some architectures,
+ these functions may not be safe to call on SMP since we keep other
+ CPUs in a holding pattern.
+
+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.
+
+.. kernel-doc:: include/linux/kgdb.h
+ :internal:
+
+kgdboc internals
+----------------
+
+kgdboc and uarts
+~~~~~~~~~~~~~~~~
+
+The kgdboc driver is actually a very thin driver that relies on the
+underlying low level to the hardware driver having "polling hooks" to
+which the tty driver is attached. In the initial implementation of
+kgdboc 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 callback in the serial core which in turn uses the callback in
+the UART driver.
+
+When using kgdboc with a UART, the UART driver must implement two
+callbacks in the ``struct uart_ops``. Example from drivers/8250.c:
+
+::
+
+ #ifdef CONFIG_CONSOLE_POLL
+ .poll_get_char = serial8250_get_poll_char,
+ .poll_put_char = serial8250_put_poll_char,
+ #endif
+
+
+Any implementation specifics around creating a polling driver use the
+``#ifdef CONFIG_CONSOLE_POLL``, 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 likely going to mean pressing the
+reset button.
+
+kgdboc and keyboards
+~~~~~~~~~~~~~~~~~~~~
+
+The kgdboc driver contains logic to configure communications with an
+attached keyboard. The keyboard infrastructure is only compiled into the
+kernel when CONFIG_KDB_KEYBOARD=y is set in the kernel configuration.
+
+The core polled keyboard driver driver for PS/2 type keyboards is in
+drivers/char/kdb_keyboard.c. This driver is hooked into the debug core
+when kgdboc populates the callback in the array called
+``kdb_poll_funcs[]``. The kdb_get_kbd_char() is the top-level
+function which polls hardware for single character input.
+
+kgdboc and kms
+~~~~~~~~~~~~~~
+
+The kgdboc driver contains logic to request the graphics display to
+switch to a text context when you are using "kgdboc=kms,kbd", provided
+that you have a video driver which has a frame buffer console and atomic
+kernel mode setting support.
+
+Every time the kernel debugger is entered it calls
+kgdboc_pre_exp_handler() which in turn calls con_debug_enter() in
+the virtual console layer. On resuming kernel execution, the kernel
+debugger calls kgdboc_post_exp_handler() which in turn calls
+con_debug_leave().
+
+Any video driver that wants to be compatible with the kernel debugger
+and the atomic kms callbacks must implement the mode_set_base_atomic,
+fb_debug_enter and fb_debug_leave operations. For the
+fb_debug_enter and fb_debug_leave the option exists to use the
+generic drm fb helper functions or implement something custom for the
+hardware. The following example shows the initialization of the
+.mode_set_base_atomic operation in
+drivers/gpu/drm/i915/intel_display.c:
+
+.. raw:: html
+
+ <div class="informalexample">
+
+::
+
+ static const struct drm_crtc_helper_funcs intel_helper_funcs = {
+ [...]
+ .mode_set_base_atomic = intel_pipe_set_base_atomic,
+ [...]
+ };
+
+
+.. raw:: html
+
+ </div>
+
+Here is an example of how the i915 driver initializes the
+fb_debug_enter and fb_debug_leave functions to use the generic drm
+helpers in drivers/gpu/drm/i915/intel_fb.c:
+
+.. raw:: html
+
+ <div class="informalexample">
+
+::
+
+ static struct fb_ops intelfb_ops = {
+ [...]
+ .fb_debug_enter = drm_fb_helper_debug_enter,
+ .fb_debug_leave = drm_fb_helper_debug_leave,
+ [...]
+ };
+
+
+.. raw:: html
+
+ </div>
+
+Credits
+=======
+
+The following people have contributed to this document:
+
+1. Amit Kale\ amitkale@xxxxxxxxxxxxxx
+
+2. Tom Rini\ trini@xxxxxxxxxxxxxxxxxxx
+
+In March 2008 this document was completely rewritten by:
+
+- Jason Wessel\ jason.wessel@xxxxxxxxxxxxx
+
+In Jan 2010 this document was updated to include kdb.
+
+- Jason Wessel\ jason.wessel@xxxxxxxxxxxxx
--
2.9.3