^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) =================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Using kgdb, kdb and the kernel debugger internals
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) :Author: Jason Wessel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) The kernel has two different debugger front ends (kdb and kgdb) which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) interface to the debug core. It is possible to use either of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) debugger front ends and dynamically transition between them if you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) configure the kernel properly at compile and runtime.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Kdb is simplistic shell-style interface which you can use on a system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) console with a keyboard or serial console. You can use it to inspect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) memory, registers, process lists, dmesg, and even set breakpoints to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) stop in a certain location. Kdb is not a source level debugger, although
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) you can set breakpoints and execute some basic kernel run control. Kdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) is mainly aimed at doing some analysis to aid in development or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) diagnosing kernel problems. You can access some symbols by name in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) kernel built-ins or in kernel modules if the code was built with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) ``CONFIG_KALLSYMS``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) Kgdb is intended to be used as a source level debugger for the Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) kernel. It is used along with gdb to debug a Linux kernel. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) expectation is that gdb can be used to "break in" to the kernel to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) inspect memory, variables and look through call stack information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) similar to the way an application developer would use gdb to debug an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) application. It is possible to place breakpoints in kernel code and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) perform some limited execution stepping.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) Two machines are required for using kgdb. One of these machines is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) development machine and the other is the target machine. The kernel to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) be debugged runs on the target machine. The development machine runs an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) instance of gdb against the vmlinux file which contains the symbols (not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) a boot image such as bzImage, zImage, uImage...). In gdb the developer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) specifies the connection parameters and connects to kgdb. The type of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) connection a developer makes with gdb depends on the availability of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) kgdb I/O modules compiled as built-ins or loadable kernel modules in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) test machine's kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) Compiling a kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) - In order to enable compilation of kdb, you must first enable kgdb.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) - The kgdb test compile options are described in the kgdb test suite
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) chapter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) Kernel config options for kgdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) To enable ``CONFIG_KGDB`` you should look under
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) :menuselection:`Kernel hacking --> Kernel debugging` and select
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) :menuselection:`KGDB: kernel debugger`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) While it is not a hard requirement that you have symbols in your vmlinux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) file, gdb tends not to be very useful without the symbolic data, so you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) will want to turn on ``CONFIG_DEBUG_INFO`` which is called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) :menuselection:`Compile the kernel with debug info` in the config menu.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) It is advised, but not required, that you turn on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) ``CONFIG_FRAME_POINTER`` kernel option which is called :menuselection:`Compile
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) the kernel with frame pointers` in the config menu. This option inserts code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) to into the compiled executable which saves the frame information in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) registers or on the stack at different points which allows a debugger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) such as gdb to more accurately construct stack back traces while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) debugging the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) If the architecture that you are using supports the kernel option
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) ``CONFIG_STRICT_KERNEL_RWX``, you should consider turning it off. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) option will prevent the use of software breakpoints because it marks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) certain regions of the kernel's memory space as read-only. If kgdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) supports it for the architecture you are using, you can use hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) breakpoints if you desire to run with the ``CONFIG_STRICT_KERNEL_RWX``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) option turned on, else you need to turn off this option.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) Next you should choose one of more I/O drivers to interconnect debugging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) host and debugged target. Early boot debugging requires a KGDB I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) driver that supports early debugging and the driver must be built into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) the kernel directly. Kgdb I/O driver configuration takes place via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) kernel or module parameters which you can learn more about in the in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) section that describes the parameter kgdboc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) Here is an example set of ``.config`` symbols to enable or disable for kgdb::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) # CONFIG_STRICT_KERNEL_RWX is not set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) CONFIG_FRAME_POINTER=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) CONFIG_KGDB=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) CONFIG_KGDB_SERIAL_CONSOLE=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) Kernel config options for kdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) Kdb is quite a bit more complex than the simple gdbstub sitting on top
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) of the kernel's debug core. Kdb must implement a shell, and also adds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) some helper functions in other parts of the kernel, responsible for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) printing out interesting data such as what you would see if you ran
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) ``lsmod``, or ``ps``. In order to build kdb into the kernel you follow the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) same steps as you would for kgdb.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) The main config option for kdb is ``CONFIG_KGDB_KDB`` which is called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) :menuselection:`KGDB_KDB: include kdb frontend for kgdb` in the config menu.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) In theory you would have already also selected an I/O driver such as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) ``CONFIG_KGDB_SERIAL_CONSOLE`` interface if you plan on using kdb on a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) serial port, when you were configuring kgdb.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) If you want to use a PS/2-style keyboard with kdb, you would select
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) ``CONFIG_KDB_KEYBOARD`` which is called :menuselection:`KGDB_KDB: keyboard as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) input device` in the config menu. The ``CONFIG_KDB_KEYBOARD`` option is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) used for anything in the gdb interface to kgdb. The ``CONFIG_KDB_KEYBOARD``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) option only works with kdb.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) Here is an example set of ``.config`` symbols to enable/disable kdb::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) # CONFIG_STRICT_KERNEL_RWX is not set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) CONFIG_FRAME_POINTER=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) CONFIG_KGDB=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) CONFIG_KGDB_SERIAL_CONSOLE=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) CONFIG_KGDB_KDB=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) CONFIG_KDB_KEYBOARD=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) Kernel Debugger Boot Arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) This section describes the various runtime kernel parameters that affect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) the configuration of the kernel debugger. The following chapter covers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) using kdb and kgdb as well as providing some examples of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) configuration parameters.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) Kernel parameter: kgdboc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) The kgdboc driver was originally an abbreviation meant to stand for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) "kgdb over console". Today it is the primary mechanism to configure how
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) to communicate from gdb to kgdb as well as the devices you want to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) to interact with the kdb shell.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) For kgdb/gdb, kgdboc is designed to work with a single serial port. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) is intended to cover the circumstance where you want to use a serial
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) console as your primary console as well as using it to perform kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) debugging. It is also possible to use kgdb on a serial port which is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) designated as a system console. Kgdboc may be configured as a kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) built-in or a kernel loadable module. You can only make use of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) ``kgdbwait`` and early debugging if you build kgdboc into the kernel as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) a built-in.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) Optionally you can elect to activate kms (Kernel Mode Setting)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) integration. When you use kms with kgdboc and you have a video driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) that has atomic mode setting hooks, it is possible to enter the debugger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) on the graphics console. When the kernel execution is resumed, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) previous graphics mode will be restored. This integration can serve as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) useful tool to aid in diagnosing crashes or doing analysis of memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) with kdb while allowing the full graphics console applications to run.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) kgdboc arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) ~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) Usage::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) kgdboc=[kms][[,]kbd][[,]serial_device][,baud]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) The order listed above must be observed if you use any of the optional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) configurations together.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) Abbreviations:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) - kms = Kernel Mode Setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) - kbd = Keyboard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) You can configure kgdboc to use the keyboard, and/or a serial device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) depending on if you are using kdb and/or kgdb, in one of the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) scenarios. The order listed above must be observed if you use any of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) optional configurations together. Using kms + only gdb is generally not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) a useful combination.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) Using loadable module or built-in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) 1. As a kernel built-in:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) Use the kernel boot argument::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) kgdboc=<tty-device>,[baud]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) 2. As a kernel loadable module:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) Use the command::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) modprobe kgdboc kgdboc=<tty-device>,[baud]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) Here are two examples of how you might format the kgdboc string. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) first is for an x86 target using the first serial port. The second
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) example is for the ARM Versatile AB using the second serial port.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) 1. ``kgdboc=ttyS0,115200``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) 2. ``kgdboc=ttyAMA1,115200``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) Configure kgdboc at runtime with sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) At run time you can enable or disable kgdboc by echoing a parameters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) into the sysfs. Here are two examples:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) 1. Enable kgdboc on ttyS0::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) 2. Disable kgdboc::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) echo "" > /sys/module/kgdboc/parameters/kgdboc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) You do not need to specify the baud if you are configuring the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) console on tty which is already configured or open.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) More examples
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) ^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) You can configure kgdboc to use the keyboard, and/or a serial device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) depending on if you are using kdb and/or kgdb, in one of the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) scenarios.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) 1. kdb and kgdb over only a serial port::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) kgdboc=<serial_device>[,baud]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) Example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) kgdboc=ttyS0,115200
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) 2. kdb and kgdb with keyboard and a serial port::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) kgdboc=kbd,<serial_device>[,baud]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) Example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) kgdboc=kbd,ttyS0,115200
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) 3. kdb with a keyboard::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) kgdboc=kbd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) 4. kdb with kernel mode setting::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) kgdboc=kms,kbd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) 5. kdb with kernel mode setting and kgdb over a serial port::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) kgdboc=kms,kbd,ttyS0,115200
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) Kgdboc does not support interrupting the target via the gdb remote
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) protocol. You must manually send a :kbd:`SysRq-G` unless you have a proxy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) that splits console output to a terminal program. A console proxy has a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) separate TCP port for the debugger and a separate TCP port for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) "human" console. The proxy can take care of sending the :kbd:`SysRq-G`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) for you.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) When using kgdboc with no debugger proxy, you can end up connecting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) debugger at one of two entry points. If an exception occurs after you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) have loaded kgdboc, a message should print on the console stating it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) waiting for the debugger. In this case you disconnect your terminal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) program and then connect the debugger in its place. If you want to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) interrupt the target system and forcibly enter a debug session you have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) to issue a :kbd:`Sysrq` sequence and then type the letter :kbd:`g`. Then you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) disconnect the terminal session and connect gdb. Your options if you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) don't like this are to hack gdb to send the :kbd:`SysRq-G` for you as well as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) on the initial connect, or to use a debugger proxy that allows an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) unmodified gdb to do the debugging.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) Kernel parameter: ``kgdboc_earlycon``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) -------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) If you specify the kernel parameter ``kgdboc_earlycon`` and your serial
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) driver registers a boot console that supports polling (doesn't need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) interrupts and implements a nonblocking read() function) kgdb will attempt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) to work using the boot console until it can transition to the regular
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) tty driver specified by the ``kgdboc`` parameter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) Normally there is only one boot console (especially that implements the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) read() function) so just adding ``kgdboc_earlycon`` on its own is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) sufficient to make this work. If you have more than one boot console you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) can add the boot console's name to differentiate. Note that names that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) are registered through the boot console layer and the tty layer are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) the same for the same port.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) For instance, on one board to be explicit you might do::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) kgdboc_earlycon=qcom_geni kgdboc=ttyMSM0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) If the only boot console on the device was "qcom_geni", you could simplify::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) kgdboc_earlycon kgdboc=ttyMSM0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) Kernel parameter: ``kgdbwait``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) The Kernel command line option ``kgdbwait`` makes kgdb wait for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) debugger connection during booting of a kernel. You can only use this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) option if you compiled a kgdb I/O driver into the kernel and you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) specified the I/O driver configuration as a kernel command line option.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) The kgdbwait parameter should always follow the configuration parameter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) for the kgdb I/O driver in the kernel command line else the I/O driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) will not be configured prior to asking the kernel to use it to wait.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) The kernel will stop and wait as early as the I/O driver and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) architecture allows when you use this option. If you build the kgdb I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) driver as a loadable kernel module kgdbwait will not do anything.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) Kernel parameter: ``kgdbcon``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) The ``kgdbcon`` feature allows you to see printk() messages inside gdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) while gdb is connected to the kernel. Kdb does not make use of the kgdbcon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) feature.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) Kgdb supports using the gdb serial protocol to send console messages to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) the debugger when the debugger is connected and running. There are two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) ways to activate this feature.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) 1. Activate with the kernel command line option::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) kgdbcon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) 2. Use sysfs before configuring an I/O driver::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) echo 1 > /sys/module/kgdb/parameters/kgdb_use_con
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) If you do this after you configure the kgdb I/O driver, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) setting will not take effect until the next point the I/O is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) reconfigured.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) .. important::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) You cannot use kgdboc + kgdbcon on a tty that is an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) active system console. An example of incorrect usage is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) console=ttyS0,115200 kgdboc=ttyS0 kgdbcon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) It is possible to use this option with kgdboc on a tty that is not a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) system console.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) Run time parameter: ``kgdbreboot``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) The kgdbreboot feature allows you to change how the debugger deals with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) the reboot notification. You have 3 choices for the behavior. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) default behavior is always set to 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) .. tabularcolumns:: |p{0.4cm}|p{11.5cm}|p{5.6cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) .. flat-table::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) :widths: 1 10 8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) * - 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) - ``echo -1 > /sys/module/debug_core/parameters/kgdbreboot``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) - Ignore the reboot notification entirely.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) * - 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) - ``echo 0 > /sys/module/debug_core/parameters/kgdbreboot``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) - Send the detach message to any attached debugger client.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) * - 3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) - ``echo 1 > /sys/module/debug_core/parameters/kgdbreboot``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) - Enter the debugger on reboot notify.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) Kernel parameter: ``nokaslr``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) If the architecture that you are using enable KASLR by default,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) you should consider turning it off. KASLR randomizes the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) virtual address where the kernel image is mapped and confuse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) gdb which resolve kernel symbol address from symbol table
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) of vmlinux.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) Using kdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) Quick start for kdb on a serial port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) ------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) This is a quick example of how to use kdb.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) 1. Configure kgdboc at boot using kernel parameters::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) console=ttyS0,115200 kgdboc=ttyS0,115200 nokaslr
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) OR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) Configure kgdboc after the kernel has booted; assuming you are using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) a serial port console::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) 2. Enter the kernel debugger manually or by waiting for an oops or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) fault. There are several ways you can enter the kernel debugger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) manually; all involve using the :kbd:`SysRq-G`, which means you must have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) - When logged in as root or with a super user session you can run::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) echo g > /proc/sysrq-trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) - Example using minicom 2.2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) - When you have telneted to a terminal server that supports sending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) a remote break
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) Press: :kbd:`CTRL-]`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) Type in: ``send break``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) Press: :kbd:`Enter` :kbd:`g`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) 3. From the kdb prompt you can run the ``help`` command to see a complete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) list of the commands that are available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) Some useful commands in kdb include:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) =========== =================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) ``lsmod`` Shows where kernel modules are loaded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) ``ps`` Displays only the active processes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) ``ps A`` Shows all the processes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) ``summary`` Shows kernel version info and memory usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) ``bt`` Get a backtrace of the current process using dump_stack()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) ``dmesg`` View the kernel syslog buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) ``go`` Continue the system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) =========== =================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) 4. When you are done using kdb you need to consider rebooting the system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) or using the ``go`` command to resuming normal kernel execution. If you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) have paused the kernel for a lengthy period of time, applications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) that rely on timely networking or anything to do with real wall clock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) time could be adversely affected, so you should take this into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) consideration when using the kernel debugger.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) Quick start for kdb using a keyboard connected console
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) ------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) This is a quick example of how to use kdb with a keyboard.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) 1. Configure kgdboc at boot using kernel parameters::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) kgdboc=kbd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) OR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) Configure kgdboc after the kernel has booted::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) echo kbd > /sys/module/kgdboc/parameters/kgdboc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) 2. Enter the kernel debugger manually or by waiting for an oops or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) fault. There are several ways you can enter the kernel debugger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) manually; all involve using the :kbd:`SysRq-G`, which means you must have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) - When logged in as root or with a super user session you can run::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) echo g > /proc/sysrq-trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) - Example using a laptop keyboard:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) Press and hold down: :kbd:`Alt`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) Press and hold down: :kbd:`Fn`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) Press and release the key with the label: :kbd:`SysRq`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) Release: :kbd:`Fn`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) Press and release: :kbd:`g`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) Release: :kbd:`Alt`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) - Example using a PS/2 101-key keyboard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) Press and hold down: :kbd:`Alt`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) Press and release the key with the label: :kbd:`SysRq`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) Press and release: :kbd:`g`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) Release: :kbd:`Alt`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) 3. Now type in a kdb command such as ``help``, ``dmesg``, ``bt`` or ``go`` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) continue kernel execution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) Using kgdb / gdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) In order to use kgdb you must activate it by passing configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) information to one of the kgdb I/O drivers. If you do not pass any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) configuration information kgdb will not do anything at all. Kgdb will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) only actively hook up to the kernel trap hooks if a kgdb I/O driver is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) loaded and configured. If you unconfigure a kgdb I/O driver, kgdb will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) unregister all the kernel hook points.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) All kgdb I/O drivers can be reconfigured at run time, if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) ``CONFIG_SYSFS`` and ``CONFIG_MODULES`` are enabled, by echo'ing a new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) config string to ``/sys/module/<driver>/parameter/<option>``. The driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) can be unconfigured by passing an empty string. You cannot change the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) configuration while the debugger is attached. Make sure to detach the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) debugger with the ``detach`` command prior to trying to unconfigure a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) kgdb I/O driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) Connecting with gdb to a serial port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) ------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) 1. Configure kgdboc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) Configure kgdboc at boot using kernel parameters::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) kgdboc=ttyS0,115200
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) OR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) Configure kgdboc after the kernel has booted::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) 2. Stop kernel execution (break into the debugger)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) In order to connect to gdb via kgdboc, the kernel must first be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) stopped. There are several ways to stop the kernel which include
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) using kgdbwait as a boot argument, via a :kbd:`SysRq-G`, or running the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) kernel until it takes an exception where it waits for the debugger to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) attach.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) - When logged in as root or with a super user session you can run::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) echo g > /proc/sysrq-trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) - Example using minicom 2.2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) - When you have telneted to a terminal server that supports sending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) a remote break
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) Press: :kbd:`CTRL-]`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) Type in: ``send break``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) Press: :kbd:`Enter` :kbd:`g`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) 3. Connect from gdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) Example (using a directly connected port)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) % gdb ./vmlinux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) (gdb) set remotebaud 115200
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) (gdb) target remote /dev/ttyS0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) Example (kgdb to a terminal server on TCP port 2012)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) % gdb ./vmlinux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) (gdb) target remote 192.168.2.2:2012
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) Once connected, you can debug a kernel the way you would debug an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) application program.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) If you are having problems connecting or something is going seriously
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) wrong while debugging, it will most often be the case that you want
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) to enable gdb to be verbose about its target communications. You do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) this prior to issuing the ``target remote`` command by typing in::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) set debug remote 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) Remember if you continue in gdb, and need to "break in" again, you need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) to issue an other :kbd:`SysRq-G`. It is easy to create a simple entry point by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) putting a breakpoint at ``sys_sync`` and then you can run ``sync`` from a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) shell or script to break into the debugger.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) kgdb and kdb interoperability
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) It is possible to transition between kdb and kgdb dynamically. The debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) core will remember which you used the last time and automatically start
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) in the same mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) Switching between kdb and kgdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) Switching from kgdb to kdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) ~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) There are two ways to switch from kgdb to kdb: you can use gdb to issue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) a maintenance packet, or you can blindly type the command ``$3#33``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) Whenever the kernel debugger stops in kgdb mode it will print the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) message ``KGDB or $3#33 for KDB``. It is important to note that you have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) to type the sequence correctly in one pass. You cannot type a backspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) or delete because kgdb will interpret that as part of the debug stream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) 1. Change from kgdb to kdb by blindly typing::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) $3#33
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) 2. Change from kgdb to kdb with gdb::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) maintenance packet 3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) Now you must kill gdb. Typically you press :kbd:`CTRL-Z` and issue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) the command::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) kill -9 %
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) Change from kdb to kgdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) ~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624) There are two ways you can change from kdb to kgdb. You can manually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) enter kgdb mode by issuing the kgdb command from the kdb shell prompt,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) or you can connect gdb while the kdb shell prompt is active. The kdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) shell looks for the typical first commands that gdb would issue with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) gdb remote protocol and if it sees one of those commands it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) automatically changes into kgdb mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) 1. From kdb issue the command::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) kgdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) Now disconnect your terminal program and connect gdb in its place
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) 2. At the kdb prompt, disconnect the terminal program and connect gdb in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) its place.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) Running kdb commands from gdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) It is possible to run a limited set of kdb commands from gdb, using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) gdb monitor command. You don't want to execute any of the run control or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) breakpoint operations, because it can disrupt the state of the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646) debugger. You should be using gdb for breakpoints and run control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) operations if you have gdb connected. The more useful commands to run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648) are things like lsmod, dmesg, ps or possibly some of the memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) information commands. To see all the kdb commands you can run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) ``monitor help``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) Example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) (gdb) monitor ps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) 1 idle process (state I) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) 27 sleeping system daemon (state M) processes suppressed,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) use 'ps A' to see all.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) Task Addr Pid Parent [*] cpu State Thread Command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660) 0xc78291d0 1 0 0 0 S 0xc7829404 init
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) 0xc7954150 942 1 0 0 S 0xc7954384 dropbear
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) 0xc78789c0 944 1 0 0 S 0xc7878bf4 sh
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663) (gdb)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665) kgdb Test Suite
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668) When kgdb is enabled in the kernel config you can also elect to enable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) the config parameter ``KGDB_TESTS``. Turning this on will enable a special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) kgdb I/O module which is designed to test the kgdb internal functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) The kgdb tests are mainly intended for developers to test the kgdb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) internals as well as a tool for developing a new kgdb architecture
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674) specific implementation. These tests are not really for end users of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) Linux kernel. The primary source of documentation would be to look in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) the ``drivers/misc/kgdbts.c`` file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) The kgdb test suite can also be configured at compile time to run the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) core set of tests by setting the kernel config parameter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680) ``KGDB_TESTS_ON_BOOT``. This particular option is aimed at automated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) regression testing and does not require modifying the kernel boot config
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) arguments. If this is turned on, the kgdb test suite can be disabled by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) specifying ``kgdbts=`` as a kernel boot argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) Kernel Debugger Internals
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) Architecture Specifics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) The kernel debugger is organized into a number of components:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693) 1. The debug core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695) The debug core is found in ``kernel/debugger/debug_core.c``. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) contains:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) - A generic OS exception handler which includes sync'ing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) processors into a stopped state on an multi-CPU system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) - The API to talk to the kgdb I/O drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) - The API to make calls to the arch-specific kgdb implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) - The logic to perform safe memory reads and writes to memory while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) using the debugger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) - A full implementation for software breakpoints unless overridden
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) by the arch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) - The API to invoke either the kdb or kgdb frontend to the debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) - The structures and callback API for atomic kernel mode setting.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) .. note:: kgdboc is where the kms callbacks are invoked.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) 2. kgdb arch-specific implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) This implementation is generally found in ``arch/*/kernel/kgdb.c``. As
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) an example, ``arch/x86/kernel/kgdb.c`` contains the specifics to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) implement HW breakpoint as well as the initialization to dynamically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723) register and unregister for the trap handlers on this architecture.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) The arch-specific portion implements:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) - contains an arch-specific trap catcher which invokes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) kgdb_handle_exception() to start kgdb about doing its work
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) - translation to and from gdb specific packet format to struct pt_regs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) - Registration and unregistration of architecture specific trap
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) hooks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) - Any special exception handling and cleanup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) - NMI exception handling and cleanup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738) - (optional) HW breakpoints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) 3. gdbstub frontend (aka kgdb)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) The gdbstub is located in ``kernel/debug/gdbstub.c``. It contains:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) - All the logic to implement the gdb serial protocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) 4. kdb frontend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) The kdb debugger shell is broken down into a number of components.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749) The kdb core is located in kernel/debug/kdb. There are a number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) helper functions in some of the other kernel components to make it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751) possible for kdb to examine and report information about the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) without taking locks that could cause a kernel deadlock. The kdb core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753) contains implements the following functionality.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755) - A simple shell
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757) - The kdb core command set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) - A registration API to register additional kdb shell commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) - A good example of a self-contained kdb module is the ``ftdump``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762) command for dumping the ftrace buffer. See:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763) ``kernel/trace/trace_kdb.c``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) - For an example of how to dynamically register a new kdb command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766) you can build the kdb_hello.ko kernel module from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767) ``samples/kdb/kdb_hello.c``. To build this example you can set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768) ``CONFIG_SAMPLES=y`` and ``CONFIG_SAMPLE_KDB=m`` in your kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769) config. Later run ``modprobe kdb_hello`` and the next time you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) enter the kdb shell, you can run the ``hello`` command.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772) - The implementation for kdb_printf() which emits messages directly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) to I/O drivers, bypassing the kernel log.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) - SW / HW breakpoint management for the kdb shell
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777) 5. kgdb I/O driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) Each kgdb I/O driver has to provide an implementation for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780) following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782) - configuration via built-in or module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) - dynamic configuration and kgdb hook registration calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786) - read and write character interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) - A cleanup handler for unconfiguring from the kgdb core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) - (optional) Early debug methodology
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792) Any given kgdb I/O driver has to operate very closely with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793) hardware and must do it in such a way that does not enable interrupts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794) or change other parts of the system context without completely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) restoring them. The kgdb core will repeatedly "poll" a kgdb I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) driver for characters when it needs input. The I/O driver is expected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797) to return immediately if there is no data available. Doing so allows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798) for the future possibility to touch watchdog hardware in such a way
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799) as to have a target system not reset when these are enabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801) If you are intent on adding kgdb architecture specific support for a new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802) architecture, the architecture should define ``HAVE_ARCH_KGDB`` in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803) architecture specific Kconfig file. This will enable kgdb for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) architecture, and at that point you must create an architecture specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805) kgdb implementation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807) There are a few flags which must be set on every architecture in their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808) ``asm/kgdb.h`` file. These are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810) - ``NUMREGBYTES``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) The size in bytes of all of the registers, so that we
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812) can ensure they will all fit into a packet.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) - ``BUFMAX``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815) The size in bytes of the buffer GDB will read into. This must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) be larger than NUMREGBYTES.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818) - ``CACHE_FLUSH_IS_SAFE``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819) Set to 1 if it is always safe to call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820) flush_cache_range or flush_icache_range. On some architectures,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821) these functions may not be safe to call on SMP since we keep other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822) CPUs in a holding pattern.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) There are also the following functions for the common backend, found in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825) ``kernel/kgdb.c``, that must be supplied by the architecture-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826) backend unless marked as (optional), in which case a default function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827) maybe used if the architecture does not need to provide a specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828) implementation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830) .. kernel-doc:: include/linux/kgdb.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833) kgdboc internals
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836) kgdboc and uarts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837) ~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839) The kgdboc driver is actually a very thin driver that relies on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840) underlying low level to the hardware driver having "polling hooks" to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841) which the tty driver is attached. In the initial implementation of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842) kgdboc the serial_core was changed to expose a low level UART hook for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843) doing polled mode reading and writing of a single character while in an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844) atomic context. When kgdb makes an I/O request to the debugger, kgdboc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845) invokes a callback in the serial core which in turn uses the callback in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846) the UART driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848) When using kgdboc with a UART, the UART driver must implement two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849) callbacks in the struct uart_ops.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850) Example from ``drivers/8250.c``::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853) #ifdef CONFIG_CONSOLE_POLL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854) .poll_get_char = serial8250_get_poll_char,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855) .poll_put_char = serial8250_put_poll_char,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856) #endif
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859) Any implementation specifics around creating a polling driver use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860) ``#ifdef CONFIG_CONSOLE_POLL``, as shown above. Keep in mind that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861) polling hooks have to be implemented in such a way that they can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862) called from an atomic context and have to restore the state of the UART
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863) chip on return such that the system can return to normal when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864) debugger detaches. You need to be very careful with any kind of lock you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865) consider, because failing here is most likely going to mean pressing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866) reset button.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868) kgdboc and keyboards
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) ~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871) The kgdboc driver contains logic to configure communications with an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872) attached keyboard. The keyboard infrastructure is only compiled into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873) kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875) The core polled keyboard driver for PS/2 type keyboards is in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876) ``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877) when kgdboc populates the callback in the array called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878) :c:expr:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879) function which polls hardware for single character input.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 881) kgdboc and kms
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 882) ~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 883)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 884) The kgdboc driver contains logic to request the graphics display to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 885) switch to a text context when you are using ``kgdboc=kms,kbd``, provided
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 886) that you have a video driver which has a frame buffer console and atomic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 887) kernel mode setting support.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 888)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 889) Every time the kernel debugger is entered it calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 890) kgdboc_pre_exp_handler() which in turn calls con_debug_enter()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 891) in the virtual console layer. On resuming kernel execution, the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 892) debugger calls kgdboc_post_exp_handler() which in turn calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 893) con_debug_leave().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 894)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 895) Any video driver that wants to be compatible with the kernel debugger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 896) and the atomic kms callbacks must implement the ``mode_set_base_atomic``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 897) ``fb_debug_enter`` and ``fb_debug_leave operations``. For the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 898) ``fb_debug_enter`` and ``fb_debug_leave`` the option exists to use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 899) generic drm fb helper functions or implement something custom for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 900) hardware. The following example shows the initialization of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 901) .mode_set_base_atomic operation in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 902) drivers/gpu/drm/i915/intel_display.c::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 903)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 904)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 905) static const struct drm_crtc_helper_funcs intel_helper_funcs = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 906) [...]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 907) .mode_set_base_atomic = intel_pipe_set_base_atomic,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 908) [...]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 909) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 910)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 911)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 912) Here is an example of how the i915 driver initializes the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 913) fb_debug_enter and fb_debug_leave functions to use the generic drm
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 914) helpers in ``drivers/gpu/drm/i915/intel_fb.c``::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 915)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 916)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 917) static struct fb_ops intelfb_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 918) [...]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 919) .fb_debug_enter = drm_fb_helper_debug_enter,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 920) .fb_debug_leave = drm_fb_helper_debug_leave,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 921) [...]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 922) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 923)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 924)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 925) Credits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 926) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 927)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 928) The following people have contributed to this document:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 929)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 930) 1. Amit Kale <amitkale@linsyssoft.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 931)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 932) 2. Tom Rini <trini@kernel.crashing.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 933)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 934) In March 2008 this document was completely rewritten by:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 935)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 936) - Jason Wessel <jason.wessel@windriver.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 937)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 938) In Jan 2010 this document was updated to include kdb.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 939)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 940) - Jason Wessel <jason.wessel@windriver.com>
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags