Lines Matching +full:in +full:- +full:kernel
2 Using kgdb, kdb and the kernel debugger internals
10 The kernel has two different debugger front ends (kdb and kgdb) which
13 configure the kernel properly at compile and runtime.
15 Kdb is simplistic shell-style interface which you can use on a system
18 stop in a certain location. Kdb is not a source level debugger, although
19 you can set breakpoints and execute some basic kernel run control. Kdb
20 is mainly aimed at doing some analysis to aid in development or
21 diagnosing kernel problems. You can access some symbols by name in
22 kernel built-ins or in kernel modules if the code was built with
26 kernel. It is used along with gdb to debug a Linux kernel. The
27 expectation is that gdb can be used to "break in" to the kernel to
30 application. It is possible to place breakpoints in kernel code and
34 development machine and the other is the target machine. The kernel to
37 a boot image such as bzImage, zImage, uImage...). In gdb the developer
40 kgdb I/O modules compiled as built-ins or loadable kernel modules in the
41 test machine's kernel.
43 Compiling a kernel
46 - In order to enable compilation of kdb, you must first enable kgdb.
48 - The kgdb test compile options are described in the kgdb test suite
51 Kernel config options for kgdb
52 ------------------------------
55 :menuselection:`Kernel hacking --> Kernel debugging` and select
56 :menuselection:`KGDB: kernel debugger`.
58 While it is not a hard requirement that you have symbols in your vmlinux
61 :menuselection:`Compile the kernel with debug info` in the config menu.
64 ``CONFIG_FRAME_POINTER`` kernel option which is called :menuselection:`Compile
65 the kernel with frame pointers` in the config menu. This option inserts code
66 into the compiled executable which saves the frame information in registers
68 more accurately construct stack back traces while debugging the kernel.
70 If the architecture that you are using supports the kernel option
73 certain regions of the kernel's memory space as read-only. If kgdb
81 the kernel directly. Kgdb I/O driver configuration takes place via
82 kernel or module parameters which you can learn more about in the in the
92 Kernel config options for kdb
93 -----------------------------
96 of the kernel's debug core. Kdb must implement a shell, and also adds
97 some helper functions in other parts of the kernel, responsible for
99 ``lsmod``, or ``ps``. In order to build kdb into the kernel you follow the
103 :menuselection:`KGDB_KDB: include kdb frontend for kgdb` in the config menu.
104 In theory you would have already also selected an I/O driver such as the
108 If you want to use a PS/2-style keyboard with kdb, you would select
110 input device` in the config menu. The ``CONFIG_KDB_KEYBOARD`` option is not
111 used for anything in the gdb interface to kgdb. The ``CONFIG_KDB_KEYBOARD``
123 Kernel Debugger Boot Arguments
126 This section describes the various runtime kernel parameters that affect
127 the configuration of the kernel debugger. The following chapter covers
131 Kernel parameter: kgdboc
132 ------------------------
141 console as your primary console as well as using it to perform kernel
143 designated as a system console. Kgdboc may be configured as a kernel
144 built-in or a kernel loadable module. You can only make use of
145 ``kgdbwait`` and early debugging if you build kgdboc into the kernel as
146 a built-in.
148 Optionally you can elect to activate kms (Kernel Mode Setting)
151 on the graphics console. When the kernel execution is resumed, the
153 useful tool to aid in diagnosing crashes or doing analysis of memory
168 - kms = Kernel Mode Setting
170 - kbd = Keyboard
173 depending on if you are using kdb and/or kgdb, in one of the following
178 Using loadable module or built-in
181 1. As a kernel built-in:
183 Use the kernel boot argument::
185 kgdboc=<tty-device>,[baud]
187 2. As a kernel loadable module:
191 modprobe kgdboc kgdboc=<tty-device>,[baud]
224 depending on if you are using kdb and/or kgdb, in one of the following
247 4. kdb with kernel mode setting::
251 5. kdb with kernel mode setting and kgdb over a serial port::
258 protocol. You must manually send a :kbd:`SysRq-G` unless you have a proxy
261 "human" console. The proxy can take care of sending the :kbd:`SysRq-G`
267 waiting for the debugger. In this case you disconnect your terminal
268 program and then connect the debugger in its place. If you want to
272 don't like this are to hack gdb to send the :kbd:`SysRq-G` for you as well as
276 Kernel parameter: ``kgdboc_earlycon``
277 -------------------------------------
279 If you specify the kernel parameter ``kgdboc_earlycon`` and your serial
300 Kernel parameter: ``kgdbwait``
301 ------------------------------
303 The Kernel command line option ``kgdbwait`` makes kgdb wait for a
304 debugger connection during booting of a kernel. You can only use this
305 option if you compiled a kgdb I/O driver into the kernel and you
306 specified the I/O driver configuration as a kernel command line option.
308 for the kgdb I/O driver in the kernel command line else the I/O driver
309 will not be configured prior to asking the kernel to use it to wait.
311 The kernel will stop and wait as early as the I/O driver and
313 driver as a loadable kernel module kgdbwait will not do anything.
315 Kernel parameter: ``kgdbcon``
316 -----------------------------
319 while gdb is connected to the kernel. Kdb does not make use of the kgdbcon
326 1. Activate with the kernel command line option::
351 ----------------------------------
359 .. flat-table::
362 * - 1
363 - ``echo -1 > /sys/module/debug_core/parameters/kgdbreboot``
364 - Ignore the reboot notification entirely.
366 * - 2
367 - ``echo 0 > /sys/module/debug_core/parameters/kgdbreboot``
368 - Send the detach message to any attached debugger client.
370 * - 3
371 - ``echo 1 > /sys/module/debug_core/parameters/kgdbreboot``
372 - Enter the debugger on reboot notify.
374 Kernel parameter: ``nokaslr``
375 -----------------------------
379 virtual address where the kernel image is mapped and confuse
380 gdb which resolve kernel symbol address from symbol table
387 ------------------------------------
391 1. Configure kgdboc at boot using kernel parameters::
397 Configure kgdboc after the kernel has booted; assuming you are using
402 2. Enter the kernel debugger manually or by waiting for an oops or
403 fault. There are several ways you can enter the kernel debugger
404 manually; all involve using the :kbd:`SysRq-G`, which means you must have
405 enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config.
407 - When logged in as root or with a super user session you can run::
409 echo g > /proc/sysrq-trigger
411 - Example using minicom 2.2
413 Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
415 - When you have telneted to a terminal server that supports sending
418 Press: :kbd:`CTRL-]`
420 Type in: ``send break``
427 Some useful commands in kdb include:
430 ``lsmod`` Shows where kernel modules are loaded
433 ``summary`` Shows kernel version info and memory usage
435 ``dmesg`` View the kernel syslog buffer
440 or using the ``go`` command to resuming normal kernel execution. If you
441 have paused the kernel for a lengthy period of time, applications
444 consideration when using the kernel debugger.
447 ------------------------------------------------------
451 1. Configure kgdboc at boot using kernel parameters::
457 Configure kgdboc after the kernel has booted::
461 2. Enter the kernel debugger manually or by waiting for an oops or
462 fault. There are several ways you can enter the kernel debugger
463 manually; all involve using the :kbd:`SysRq-G`, which means you must have
464 enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config.
466 - When logged in as root or with a super user session you can run::
468 echo g > /proc/sysrq-trigger
470 - Example using a laptop keyboard:
484 - Example using a PS/2 101-key keyboard
494 3. Now type in a kdb command such as ``help``, ``dmesg``, ``bt`` or ``go`` to
495 continue kernel execution.
500 In order to use kgdb you must activate it by passing configuration
503 only actively hook up to the kernel trap hooks if a kgdb I/O driver is
505 unregister all the kernel hook points.
516 ------------------------------------
520 Configure kgdboc at boot using kernel parameters::
526 Configure kgdboc after the kernel has booted::
530 2. Stop kernel execution (break into the debugger)
532 In order to connect to gdb via kgdboc, the kernel must first be
533 stopped. There are several ways to stop the kernel which include
534 using kgdbwait as a boot argument, via a :kbd:`SysRq-G`, or running the
535 kernel until it takes an exception where it waits for the debugger to
538 - When logged in as root or with a super user session you can run::
540 echo g > /proc/sysrq-trigger
542 - Example using minicom 2.2
544 Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
546 - When you have telneted to a terminal server that supports sending
549 Press: :kbd:`CTRL-]`
551 Type in: ``send break``
570 Once connected, you can debug a kernel the way you would debug an
576 this prior to issuing the ``target remote`` command by typing in::
580 Remember if you continue in gdb, and need to "break in" again, you need
581 to issue an other :kbd:`SysRq-G`. It is easy to create a simple entry point by
590 in the same mode.
593 ------------------------------
600 Whenever the kernel debugger stops in kgdb mode it will print the
602 to type the sequence correctly in one pass. You cannot type a backspace
615 Now you must kill gdb. Typically you press :kbd:`CTRL-Z` and issue
618 kill -9 %
634 Now disconnect your terminal program and connect gdb in its place
636 2. At the kdb prompt, disconnect the terminal program and connect gdb in
640 -----------------------------
644 breakpoint operations, because it can disrupt the state of the kernel
667 When kgdb is enabled in the kernel config you can also elect to enable
674 Linux kernel. The primary source of documentation would be to look in
678 core set of tests by setting the kernel config parameter
680 regression testing and does not require modifying the kernel boot config
682 specifying ``kgdbts=`` as a kernel boot argument.
684 Kernel Debugger Internals
688 ----------------------
690 The kernel debugger is organized into a number of components:
694 The debug core is found in ``kernel/debugger/debug_core.c``. It
697 - A generic OS exception handler which includes sync'ing the
698 processors into a stopped state on an multi-CPU system.
700 - The API to talk to the kgdb I/O drivers
702 - The API to make calls to the arch-specific kgdb implementation
704 - The logic to perform safe memory reads and writes to memory while
707 - A full implementation for software breakpoints unless overridden
710 - The API to invoke either the kdb or kgdb frontend to the debug
713 - The structures and callback API for atomic kernel mode setting.
717 2. kgdb arch-specific implementation
719 This implementation is generally found in ``arch/*/kernel/kgdb.c``. As
720 an example, ``arch/x86/kernel/kgdb.c`` contains the specifics to
723 The arch-specific portion implements:
725 - contains an arch-specific trap catcher which invokes
728 - translation to and from gdb specific packet format to struct pt_regs
730 - Registration and unregistration of architecture specific trap
733 - Any special exception handling and cleanup
735 - NMI exception handling and cleanup
737 - (optional) HW breakpoints
741 The gdbstub is located in ``kernel/debug/gdbstub.c``. It contains:
743 - All the logic to implement the gdb serial protocol
748 The kdb core is located in kernel/debug/kdb. There are a number of
749 helper functions in some of the other kernel components to make it
750 possible for kdb to examine and report information about the kernel
751 without taking locks that could cause a kernel deadlock. The kdb core
754 - A simple shell
756 - The kdb core command set
758 - A registration API to register additional kdb shell commands.
760 - A good example of a self-contained kdb module is the ``ftdump``
762 ``kernel/trace/trace_kdb.c``
764 - For an example of how to dynamically register a new kdb command
765 you can build the kdb_hello.ko kernel module from
767 ``CONFIG_SAMPLES=y`` and ``CONFIG_SAMPLE_KDB=m`` in your kernel
771 - The implementation for kdb_printf() which emits messages directly
772 to I/O drivers, bypassing the kernel log.
774 - SW / HW breakpoint management for the kdb shell
781 - configuration via built-in or module
783 - dynamic configuration and kgdb hook registration calls
785 - read and write character interface
787 - A cleanup handler for unconfiguring from the kgdb core
789 - (optional) Early debug methodology
792 hardware and must do it in such a way that does not enable interrupts
797 for the future possibility to touch watchdog hardware in such a way
801 architecture, the architecture should define ``HAVE_ARCH_KGDB`` in the
806 There are a few flags which must be set on every architecture in their
809 - ``NUMREGBYTES``:
810 The size in bytes of all of the registers, so that we
813 - ``BUFMAX``:
814 The size in bytes of the buffer GDB will read into. This must
817 - ``CACHE_FLUSH_IS_SAFE``:
821 CPUs in a holding pattern.
823 There are also the following functions for the common backend, found in
824 ``kernel/kgdb.c``, that must be supplied by the architecture-specific
825 backend unless marked as (optional), in which case a default function
829 .. kernel-doc:: include/linux/kgdb.h
833 ----------------
840 which the tty driver is attached. In the initial implementation of
842 doing polled mode reading and writing of a single character while in an
844 invokes a callback in the serial core which in turn uses the callback in
848 callbacks in the struct uart_ops.
859 ``#ifdef CONFIG_CONSOLE_POLL``, as shown above. Keep in mind that
860 polling hooks have to be implemented in such a way that they can be
872 kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.
874 The core polled keyboard driver for PS/2 type keyboards is in
876 when kgdboc populates the callback in the array called
877 :c:expr:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level
886 kernel mode setting support.
888 Every time the kernel debugger is entered it calls
889 kgdboc_pre_exp_handler() which in turn calls con_debug_enter()
890 in the virtual console layer. On resuming kernel execution, the kernel
891 debugger calls kgdboc_post_exp_handler() which in turn calls
894 Any video driver that wants to be compatible with the kernel debugger
900 .mode_set_base_atomic operation in
913 helpers in ``drivers/gpu/drm/i915/intel_fb.c``::
931 2. Tom Rini <trini@kernel.crashing.org>
933 In March 2008 this document was completely rewritten by:
935 - Jason Wessel <jason.wessel@windriver.com>
937 In Jan 2010 this document was updated to include kdb.
939 - Jason Wessel <jason.wessel@windriver.com>