From 7fb2e8a49037099c56ea209aaa8527e5f3e742ba Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 11 May 2017 16:23:50 -0300 Subject: docs-rst: convert kgdb DocBook to ReST Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab --- Documentation/dev-tools/index.rst | 1 + Documentation/dev-tools/kgdb.rst | 930 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 931 insertions(+) create mode 100644 Documentation/dev-tools/kgdb.rst (limited to 'Documentation/dev-tools') 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=,[baud]`` + +2. As a kernel loadable module: + + Use the command: ``modprobe kgdboc kgdboc=,[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=[,baud]`` + + Example: ``kgdboc=ttyS0,115200`` + +2. kdb and kgdb with keyboard and a serial port + + ``kgdboc=kbd,[,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//parameter/