1 =================================================
2 Using kgdb, kdb and the kernel debugger internals
3 =================================================
10 The kernel has two different debugger front ends (kdb and kgdb) which
11 interface to the debug core. It is possible to use either of the
12 debugger front ends and dynamically transition between them if you
13 configure the kernel properly at compile and runtime.
15 Kdb is simplistic shell-style interface which you can use on a system
16 console with a keyboard or serial console. You can use it to inspect
17 memory, registers, process lists, dmesg, and even set breakpoints to
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
25 Kgdb is intended to be used as a source level debugger for the Linux
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
28 inspect memory, variables and look through call stack information
29 similar to the way an application developer would use gdb to debug an
30 application. It is possible to place breakpoints in kernel code and
31 perform some limited execution stepping.
33 Two machines are required for using kgdb. One of these machines is a
34 development machine and the other is the target machine. The kernel to
35 be debugged runs on the target machine. The development machine runs an
36 instance of gdb against the vmlinux file which contains the symbols (not
37 a boot image such as bzImage, zImage, uImage...). In gdb the developer
38 specifies the connection parameters and connects to kgdb. The type of
39 connection a developer makes with gdb depends on the availability of
40 kgdb I/O modules compiled as built-ins or loadable kernel modules in the
41 test machine's 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 ------------------------------
54 To enable ``CONFIG_KGDB`` you should look under
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
59 file, gdb tends not to be very useful without the symbolic data, so you
60 will want to turn on ``CONFIG_DEBUG_INFO`` which is called
61 :menuselection:`Compile the kernel with debug info` in the config menu.
63 It is advised, but not required, that you turn on the
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 to into the compiled executable which saves the frame information in
67 registers or on the stack at different points which allows a debugger
68 such as gdb to more accurately construct stack back traces while
71 If the architecture that you are using supports the kernel option
72 ``CONFIG_STRICT_KERNEL_RWX``, you should consider turning it off. This
73 option will prevent the use of software breakpoints because it marks
74 certain regions of the kernel's memory space as read-only. If kgdb
75 supports it for the architecture you are using, you can use hardware
76 breakpoints if you desire to run with the ``CONFIG_STRICT_KERNEL_RWX``
77 option turned on, else you need to turn off this option.
79 Next you should choose one of more I/O drivers to interconnect debugging
80 host and debugged target. Early boot debugging requires a KGDB I/O
81 driver that supports early debugging and the driver must be built into
82 the kernel directly. Kgdb I/O driver configuration takes place via
83 kernel or module parameters which you can learn more about in the in the
84 section that describes the parameter kgdboc.
86 Here is an example set of ``.config`` symbols to enable or disable for kgdb::
88 # CONFIG_STRICT_KERNEL_RWX is not set
89 CONFIG_FRAME_POINTER=y
91 CONFIG_KGDB_SERIAL_CONSOLE=y
93 Kernel config options for kdb
94 -----------------------------
96 Kdb is quite a bit more complex than the simple gdbstub sitting on top
97 of the kernel's debug core. Kdb must implement a shell, and also adds
98 some helper functions in other parts of the kernel, responsible for
99 printing out interesting data such as what you would see if you ran
100 ``lsmod``, or ``ps``. In order to build kdb into the kernel you follow the
101 same steps as you would for kgdb.
103 The main config option for kdb is ``CONFIG_KGDB_KDB`` which is called
104 :menuselection:`KGDB_KDB: include kdb frontend for kgdb` in the config menu.
105 In theory you would have already also selected an I/O driver such as the
106 ``CONFIG_KGDB_SERIAL_CONSOLE`` interface if you plan on using kdb on a
107 serial port, when you were configuring kgdb.
109 If you want to use a PS/2-style keyboard with kdb, you would select
110 ``CONFIG_KDB_KEYBOARD`` which is called :menuselection:`KGDB_KDB: keyboard as
111 input device` in the config menu. The ``CONFIG_KDB_KEYBOARD`` option is not
112 used for anything in the gdb interface to kgdb. The ``CONFIG_KDB_KEYBOARD``
113 option only works with kdb.
115 Here is an example set of ``.config`` symbols to enable/disable kdb::
117 # CONFIG_STRICT_KERNEL_RWX is not set
118 CONFIG_FRAME_POINTER=y
120 CONFIG_KGDB_SERIAL_CONSOLE=y
122 CONFIG_KDB_KEYBOARD=y
124 Kernel Debugger Boot Arguments
125 ==============================
127 This section describes the various runtime kernel parameters that affect
128 the configuration of the kernel debugger. The following chapter covers
129 using kdb and kgdb as well as providing some examples of the
130 configuration parameters.
132 Kernel parameter: kgdboc
133 ------------------------
135 The kgdboc driver was originally an abbreviation meant to stand for
136 "kgdb over console". Today it is the primary mechanism to configure how
137 to communicate from gdb to kgdb as well as the devices you want to use
138 to interact with the kdb shell.
140 For kgdb/gdb, kgdboc is designed to work with a single serial port. It
141 is intended to cover the circumstance where you want to use a serial
142 console as your primary console as well as using it to perform kernel
143 debugging. It is also possible to use kgdb on a serial port which is not
144 designated as a system console. Kgdboc may be configured as a kernel
145 built-in or a kernel loadable module. You can only make use of
146 ``kgdbwait`` and early debugging if you build kgdboc into the kernel as
149 Optionally you can elect to activate kms (Kernel Mode Setting)
150 integration. When you use kms with kgdboc and you have a video driver
151 that has atomic mode setting hooks, it is possible to enter the debugger
152 on the graphics console. When the kernel execution is resumed, the
153 previous graphics mode will be restored. This integration can serve as a
154 useful tool to aid in diagnosing crashes or doing analysis of memory
155 with kdb while allowing the full graphics console applications to run.
162 kgdboc=[kms][[,]kbd][[,]serial_device][,baud]
164 The order listed above must be observed if you use any of the optional
165 configurations together.
169 - kms = Kernel Mode Setting
173 You can configure kgdboc to use the keyboard, and/or a serial device
174 depending on if you are using kdb and/or kgdb, in one of the following
175 scenarios. The order listed above must be observed if you use any of the
176 optional configurations together. Using kms + only gdb is generally not
177 a useful combination.
179 Using loadable module or built-in
180 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
182 1. As a kernel built-in:
184 Use the kernel boot argument::
186 kgdboc=<tty-device>,[baud]
188 2. As a kernel loadable module:
192 modprobe kgdboc kgdboc=<tty-device>,[baud]
194 Here are two examples of how you might format the kgdboc string. The
195 first is for an x86 target using the first serial port. The second
196 example is for the ARM Versatile AB using the second serial port.
198 1. ``kgdboc=ttyS0,115200``
200 2. ``kgdboc=ttyAMA1,115200``
202 Configure kgdboc at runtime with sysfs
203 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
205 At run time you can enable or disable kgdboc by echoing a parameters
206 into the sysfs. Here are two examples:
208 1. Enable kgdboc on ttyS0::
210 echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
214 echo "" > /sys/module/kgdboc/parameters/kgdboc
218 You do not need to specify the baud if you are configuring the
219 console on tty which is already configured or open.
224 You can configure kgdboc to use the keyboard, and/or a serial device
225 depending on if you are using kdb and/or kgdb, in one of the following
228 1. kdb and kgdb over only a serial port::
230 kgdboc=<serial_device>[,baud]
236 2. kdb and kgdb with keyboard and a serial port::
238 kgdboc=kbd,<serial_device>[,baud]
242 kgdboc=kbd,ttyS0,115200
244 3. kdb with a keyboard::
248 4. kdb with kernel mode setting::
252 5. kdb with kernel mode setting and kgdb over a serial port::
254 kgdboc=kms,kbd,ttyS0,115200
258 Kgdboc does not support interrupting the target via the gdb remote
259 protocol. You must manually send a :kbd:`SysRq-G` unless you have a proxy
260 that splits console output to a terminal program. A console proxy has a
261 separate TCP port for the debugger and a separate TCP port for the
262 "human" console. The proxy can take care of sending the :kbd:`SysRq-G`
265 When using kgdboc with no debugger proxy, you can end up connecting the
266 debugger at one of two entry points. If an exception occurs after you
267 have loaded kgdboc, a message should print on the console stating it is
268 waiting for the debugger. In this case you disconnect your terminal
269 program and then connect the debugger in its place. If you want to
270 interrupt the target system and forcibly enter a debug session you have
271 to issue a :kbd:`Sysrq` sequence and then type the letter :kbd:`g`. Then you
272 disconnect the terminal session and connect gdb. Your options if you
273 don't like this are to hack gdb to send the :kbd:`SysRq-G` for you as well as
274 on the initial connect, or to use a debugger proxy that allows an
275 unmodified gdb to do the debugging.
277 Kernel parameter: ``kgdbwait``
278 ------------------------------
280 The Kernel command line option ``kgdbwait`` makes kgdb wait for a
281 debugger connection during booting of a kernel. You can only use this
282 option if you compiled a kgdb I/O driver into the kernel and you
283 specified the I/O driver configuration as a kernel command line option.
284 The kgdbwait parameter should always follow the configuration parameter
285 for the kgdb I/O driver in the kernel command line else the I/O driver
286 will not be configured prior to asking the kernel to use it to wait.
288 The kernel will stop and wait as early as the I/O driver and
289 architecture allows when you use this option. If you build the kgdb I/O
290 driver as a loadable kernel module kgdbwait will not do anything.
292 Kernel parameter: ``kgdbcon``
293 -----------------------------
295 The ``kgdbcon`` feature allows you to see :c:func:`printk` messages inside gdb
296 while gdb is connected to the kernel. Kdb does not make use of the kgdbcon
299 Kgdb supports using the gdb serial protocol to send console messages to
300 the debugger when the debugger is connected and running. There are two
301 ways to activate this feature.
303 1. Activate with the kernel command line option::
307 2. Use sysfs before configuring an I/O driver::
309 echo 1 > /sys/module/kgdb/parameters/kgdb_use_con
313 If you do this after you configure the kgdb I/O driver, the
314 setting will not take effect until the next point the I/O is
319 You cannot use kgdboc + kgdbcon on a tty that is an
320 active system console. An example of incorrect usage is::
322 console=ttyS0,115200 kgdboc=ttyS0 kgdbcon
324 It is possible to use this option with kgdboc on a tty that is not a
327 Run time parameter: ``kgdbreboot``
328 ----------------------------------
330 The kgdbreboot feature allows you to change how the debugger deals with
331 the reboot notification. You have 3 choices for the behavior. The
332 default behavior is always set to 0.
334 .. tabularcolumns:: |p{0.4cm}|p{11.5cm}|p{5.6cm}|
340 - ``echo -1 > /sys/module/debug_core/parameters/kgdbreboot``
341 - Ignore the reboot notification entirely.
344 - ``echo 0 > /sys/module/debug_core/parameters/kgdbreboot``
345 - Send the detach message to any attached debugger client.
348 - ``echo 1 > /sys/module/debug_core/parameters/kgdbreboot``
349 - Enter the debugger on reboot notify.
354 Quick start for kdb on a serial port
355 ------------------------------------
357 This is a quick example of how to use kdb.
359 1. Configure kgdboc at boot using kernel parameters::
361 console=ttyS0,115200 kgdboc=ttyS0,115200
365 Configure kgdboc after the kernel has booted; assuming you are using
366 a serial port console::
368 echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
370 2. Enter the kernel debugger manually or by waiting for an oops or
371 fault. There are several ways you can enter the kernel debugger
372 manually; all involve using the :kbd:`SysRq-G`, which means you must have
373 enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
375 - When logged in as root or with a super user session you can run::
377 echo g > /proc/sysrq-trigger
379 - Example using minicom 2.2
381 Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
383 - When you have telneted to a terminal server that supports sending
388 Type in: ``send break``
390 Press: :kbd:`Enter` :kbd:`g`
392 3. From the kdb prompt you can run the ``help`` command to see a complete
393 list of the commands that are available.
395 Some useful commands in kdb include:
397 =========== =================================================================
398 ``lsmod`` Shows where kernel modules are loaded
399 ``ps`` Displays only the active processes
400 ``ps A`` Shows all the processes
401 ``summary`` Shows kernel version info and memory usage
402 ``bt`` Get a backtrace of the current process using :c:func:`dump_stack`
403 ``dmesg`` View the kernel syslog buffer
404 ``go`` Continue the system
405 =========== =================================================================
407 4. When you are done using kdb you need to consider rebooting the system
408 or using the ``go`` command to resuming normal kernel execution. If you
409 have paused the kernel for a lengthy period of time, applications
410 that rely on timely networking or anything to do with real wall clock
411 time could be adversely affected, so you should take this into
412 consideration when using the kernel debugger.
414 Quick start for kdb using a keyboard connected console
415 ------------------------------------------------------
417 This is a quick example of how to use kdb with a keyboard.
419 1. Configure kgdboc at boot using kernel parameters::
425 Configure kgdboc after the kernel has booted::
427 echo kbd > /sys/module/kgdboc/parameters/kgdboc
429 2. Enter the kernel debugger manually or by waiting for an oops or
430 fault. There are several ways you can enter the kernel debugger
431 manually; all involve using the :kbd:`SysRq-G`, which means you must have
432 enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
434 - When logged in as root or with a super user session you can run::
436 echo g > /proc/sysrq-trigger
438 - Example using a laptop keyboard:
440 Press and hold down: :kbd:`Alt`
442 Press and hold down: :kbd:`Fn`
444 Press and release the key with the label: :kbd:`SysRq`
448 Press and release: :kbd:`g`
452 - Example using a PS/2 101-key keyboard
454 Press and hold down: :kbd:`Alt`
456 Press and release the key with the label: :kbd:`SysRq`
458 Press and release: :kbd:`g`
462 3. Now type in a kdb command such as ``help``, ``dmesg``, ``bt`` or ``go`` to
463 continue kernel execution.
468 In order to use kgdb you must activate it by passing configuration
469 information to one of the kgdb I/O drivers. If you do not pass any
470 configuration information kgdb will not do anything at all. Kgdb will
471 only actively hook up to the kernel trap hooks if a kgdb I/O driver is
472 loaded and configured. If you unconfigure a kgdb I/O driver, kgdb will
473 unregister all the kernel hook points.
475 All kgdb I/O drivers can be reconfigured at run time, if
476 ``CONFIG_SYSFS`` and ``CONFIG_MODULES`` are enabled, by echo'ing a new
477 config string to ``/sys/module/<driver>/parameter/<option>``. The driver
478 can be unconfigured by passing an empty string. You cannot change the
479 configuration while the debugger is attached. Make sure to detach the
480 debugger with the ``detach`` command prior to trying to unconfigure a
483 Connecting with gdb to a serial port
484 ------------------------------------
488 Configure kgdboc at boot using kernel parameters::
494 Configure kgdboc after the kernel has booted::
496 echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
498 2. Stop kernel execution (break into the debugger)
500 In order to connect to gdb via kgdboc, the kernel must first be
501 stopped. There are several ways to stop the kernel which include
502 using kgdbwait as a boot argument, via a :kbd:`SysRq-G`, or running the
503 kernel until it takes an exception where it waits for the debugger to
506 - When logged in as root or with a super user session you can run::
508 echo g > /proc/sysrq-trigger
510 - Example using minicom 2.2
512 Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
514 - When you have telneted to a terminal server that supports sending
519 Type in: ``send break``
521 Press: :kbd:`Enter` :kbd:`g`
525 Example (using a directly connected port)::
528 (gdb) set remotebaud 115200
529 (gdb) target remote /dev/ttyS0
532 Example (kgdb to a terminal server on TCP port 2012)::
535 (gdb) target remote 192.168.2.2:2012
538 Once connected, you can debug a kernel the way you would debug an
541 If you are having problems connecting or something is going seriously
542 wrong while debugging, it will most often be the case that you want
543 to enable gdb to be verbose about its target communications. You do
544 this prior to issuing the ``target remote`` command by typing in::
548 Remember if you continue in gdb, and need to "break in" again, you need
549 to issue an other :kbd:`SysRq-G`. It is easy to create a simple entry point by
550 putting a breakpoint at ``sys_sync`` and then you can run ``sync`` from a
551 shell or script to break into the debugger.
553 kgdb and kdb interoperability
554 =============================
556 It is possible to transition between kdb and kgdb dynamically. The debug
557 core will remember which you used the last time and automatically start
560 Switching between kdb and kgdb
561 ------------------------------
563 Switching from kgdb to kdb
564 ~~~~~~~~~~~~~~~~~~~~~~~~~~
566 There are two ways to switch from kgdb to kdb: you can use gdb to issue
567 a maintenance packet, or you can blindly type the command ``$3#33``.
568 Whenever the kernel debugger stops in kgdb mode it will print the
569 message ``KGDB or $3#33 for KDB``. It is important to note that you have
570 to type the sequence correctly in one pass. You cannot type a backspace
571 or delete because kgdb will interpret that as part of the debug stream.
573 1. Change from kgdb to kdb by blindly typing::
577 2. Change from kgdb to kdb with gdb::
583 Now you must kill gdb. Typically you press :kbd:`CTRL-Z` and issue
588 Change from kdb to kgdb
589 ~~~~~~~~~~~~~~~~~~~~~~~
591 There are two ways you can change from kdb to kgdb. You can manually
592 enter kgdb mode by issuing the kgdb command from the kdb shell prompt,
593 or you can connect gdb while the kdb shell prompt is active. The kdb
594 shell looks for the typical first commands that gdb would issue with the
595 gdb remote protocol and if it sees one of those commands it
596 automatically changes into kgdb mode.
598 1. From kdb issue the command::
602 Now disconnect your terminal program and connect gdb in its place
604 2. At the kdb prompt, disconnect the terminal program and connect gdb in
607 Running kdb commands from gdb
608 -----------------------------
610 It is possible to run a limited set of kdb commands from gdb, using the
611 gdb monitor command. You don't want to execute any of the run control or
612 breakpoint operations, because it can disrupt the state of the kernel
613 debugger. You should be using gdb for breakpoints and run control
614 operations if you have gdb connected. The more useful commands to run
615 are things like lsmod, dmesg, ps or possibly some of the memory
616 information commands. To see all the kdb commands you can run
622 1 idle process (state I) and
623 27 sleeping system daemon (state M) processes suppressed,
624 use 'ps A' to see all.
625 Task Addr Pid Parent [*] cpu State Thread Command
627 0xc78291d0 1 0 0 0 S 0xc7829404 init
628 0xc7954150 942 1 0 0 S 0xc7954384 dropbear
629 0xc78789c0 944 1 0 0 S 0xc7878bf4 sh
635 When kgdb is enabled in the kernel config you can also elect to enable
636 the config parameter ``KGDB_TESTS``. Turning this on will enable a special
637 kgdb I/O module which is designed to test the kgdb internal functions.
639 The kgdb tests are mainly intended for developers to test the kgdb
640 internals as well as a tool for developing a new kgdb architecture
641 specific implementation. These tests are not really for end users of the
642 Linux kernel. The primary source of documentation would be to look in
643 the ``drivers/misc/kgdbts.c`` file.
645 The kgdb test suite can also be configured at compile time to run the
646 core set of tests by setting the kernel config parameter
647 ``KGDB_TESTS_ON_BOOT``. This particular option is aimed at automated
648 regression testing and does not require modifying the kernel boot config
649 arguments. If this is turned on, the kgdb test suite can be disabled by
650 specifying ``kgdbts=`` as a kernel boot argument.
652 Kernel Debugger Internals
653 =========================
655 Architecture Specifics
656 ----------------------
658 The kernel debugger is organized into a number of components:
662 The debug core is found in ``kernel/debugger/debug_core.c``. It
665 - A generic OS exception handler which includes sync'ing the
666 processors into a stopped state on an multi-CPU system.
668 - The API to talk to the kgdb I/O drivers
670 - The API to make calls to the arch-specific kgdb implementation
672 - The logic to perform safe memory reads and writes to memory while
675 - A full implementation for software breakpoints unless overridden
678 - The API to invoke either the kdb or kgdb frontend to the debug
681 - The structures and callback API for atomic kernel mode setting.
683 .. note:: kgdboc is where the kms callbacks are invoked.
685 2. kgdb arch-specific implementation
687 This implementation is generally found in ``arch/*/kernel/kgdb.c``. As
688 an example, ``arch/x86/kernel/kgdb.c`` contains the specifics to
689 implement HW breakpoint as well as the initialization to dynamically
690 register and unregister for the trap handlers on this architecture.
691 The arch-specific portion implements:
693 - contains an arch-specific trap catcher which invokes
694 :c:func:`kgdb_handle_exception` to start kgdb about doing its work
696 - translation to and from gdb specific packet format to :c:type:`pt_regs`
698 - Registration and unregistration of architecture specific trap
701 - Any special exception handling and cleanup
703 - NMI exception handling and cleanup
705 - (optional) HW breakpoints
707 3. gdbstub frontend (aka kgdb)
709 The gdbstub is located in ``kernel/debug/gdbstub.c``. It contains:
711 - All the logic to implement the gdb serial protocol
715 The kdb debugger shell is broken down into a number of components.
716 The kdb core is located in kernel/debug/kdb. There are a number of
717 helper functions in some of the other kernel components to make it
718 possible for kdb to examine and report information about the kernel
719 without taking locks that could cause a kernel deadlock. The kdb core
720 contains implements the following functionality.
724 - The kdb core command set
726 - A registration API to register additional kdb shell commands.
728 - A good example of a self-contained kdb module is the ``ftdump``
729 command for dumping the ftrace buffer. See:
730 ``kernel/trace/trace_kdb.c``
732 - For an example of how to dynamically register a new kdb command
733 you can build the kdb_hello.ko kernel module from
734 ``samples/kdb/kdb_hello.c``. To build this example you can set
735 ``CONFIG_SAMPLES=y`` and ``CONFIG_SAMPLE_KDB=m`` in your kernel
736 config. Later run ``modprobe kdb_hello`` and the next time you
737 enter the kdb shell, you can run the ``hello`` command.
739 - The implementation for :c:func:`kdb_printf` which emits messages directly
740 to I/O drivers, bypassing the kernel log.
742 - SW / HW breakpoint management for the kdb shell
746 Each kgdb I/O driver has to provide an implementation for the
749 - configuration via built-in or module
751 - dynamic configuration and kgdb hook registration calls
753 - read and write character interface
755 - A cleanup handler for unconfiguring from the kgdb core
757 - (optional) Early debug methodology
759 Any given kgdb I/O driver has to operate very closely with the
760 hardware and must do it in such a way that does not enable interrupts
761 or change other parts of the system context without completely
762 restoring them. The kgdb core will repeatedly "poll" a kgdb I/O
763 driver for characters when it needs input. The I/O driver is expected
764 to return immediately if there is no data available. Doing so allows
765 for the future possibility to touch watchdog hardware in such a way
766 as to have a target system not reset when these are enabled.
768 If you are intent on adding kgdb architecture specific support for a new
769 architecture, the architecture should define ``HAVE_ARCH_KGDB`` in the
770 architecture specific Kconfig file. This will enable kgdb for the
771 architecture, and at that point you must create an architecture specific
774 There are a few flags which must be set on every architecture in their
775 ``asm/kgdb.h`` file. These are:
778 The size in bytes of all of the registers, so that we
779 can ensure they will all fit into a packet.
782 The size in bytes of the buffer GDB will read into. This must
783 be larger than NUMREGBYTES.
785 - ``CACHE_FLUSH_IS_SAFE``:
786 Set to 1 if it is always safe to call
787 flush_cache_range or flush_icache_range. On some architectures,
788 these functions may not be safe to call on SMP since we keep other
789 CPUs in a holding pattern.
791 There are also the following functions for the common backend, found in
792 ``kernel/kgdb.c``, that must be supplied by the architecture-specific
793 backend unless marked as (optional), in which case a default function
794 maybe used if the architecture does not need to provide a specific
797 .. kernel-doc:: include/linux/kgdb.h
806 The kgdboc driver is actually a very thin driver that relies on the
807 underlying low level to the hardware driver having "polling hooks" to
808 which the tty driver is attached. In the initial implementation of
809 kgdboc the serial_core was changed to expose a low level UART hook for
810 doing polled mode reading and writing of a single character while in an
811 atomic context. When kgdb makes an I/O request to the debugger, kgdboc
812 invokes a callback in the serial core which in turn uses the callback in
815 When using kgdboc with a UART, the UART driver must implement two
816 callbacks in the :c:type:`struct uart_ops <uart_ops>`.
817 Example from ``drivers/8250.c``::
820 #ifdef CONFIG_CONSOLE_POLL
821 .poll_get_char = serial8250_get_poll_char,
822 .poll_put_char = serial8250_put_poll_char,
826 Any implementation specifics around creating a polling driver use the
827 ``#ifdef CONFIG_CONSOLE_POLL``, as shown above. Keep in mind that
828 polling hooks have to be implemented in such a way that they can be
829 called from an atomic context and have to restore the state of the UART
830 chip on return such that the system can return to normal when the
831 debugger detaches. You need to be very careful with any kind of lock you
832 consider, because failing here is most likely going to mean pressing the
836 ~~~~~~~~~~~~~~~~~~~~~~~~
838 The kgdboc driver contains logic to configure communications with an
839 attached keyboard. The keyboard infrastructure is only compiled into the
840 kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.
842 The core polled keyboard driver driver for PS/2 type keyboards is in
843 ``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core
844 when kgdboc populates the callback in the array called
845 :c:type:`kdb_poll_funcs[]`. The :c:func:`kdb_get_kbd_char` is the top-level
846 function which polls hardware for single character input.
851 The kgdboc driver contains logic to request the graphics display to
852 switch to a text context when you are using ``kgdboc=kms,kbd``, provided
853 that you have a video driver which has a frame buffer console and atomic
854 kernel mode setting support.
856 Every time the kernel debugger is entered it calls
857 :c:func:`kgdboc_pre_exp_handler` which in turn calls :c:func:`con_debug_enter`
858 in the virtual console layer. On resuming kernel execution, the kernel
859 debugger calls :c:func:`kgdboc_post_exp_handler` which in turn calls
860 :c:func:`con_debug_leave`.
862 Any video driver that wants to be compatible with the kernel debugger
863 and the atomic kms callbacks must implement the ``mode_set_base_atomic``,
864 ``fb_debug_enter`` and ``fb_debug_leave operations``. For the
865 ``fb_debug_enter`` and ``fb_debug_leave`` the option exists to use the
866 generic drm fb helper functions or implement something custom for the
867 hardware. The following example shows the initialization of the
868 .mode_set_base_atomic operation in
869 drivers/gpu/drm/i915/intel_display.c::
872 static const struct drm_crtc_helper_funcs intel_helper_funcs = {
874 .mode_set_base_atomic = intel_pipe_set_base_atomic,
879 Here is an example of how the i915 driver initializes the
880 fb_debug_enter and fb_debug_leave functions to use the generic drm
881 helpers in ``drivers/gpu/drm/i915/intel_fb.c``::
884 static struct fb_ops intelfb_ops = {
886 .fb_debug_enter = drm_fb_helper_debug_enter,
887 .fb_debug_leave = drm_fb_helper_debug_leave,
895 The following people have contributed to this document:
897 1. Amit Kale <amitkale@linsyssoft.com>
899 2. Tom Rini <trini@kernel.crashing.org>
901 In March 2008 this document was completely rewritten by:
903 - Jason Wessel <jason.wessel@windriver.com>
905 In Jan 2010 this document was updated to include kdb.
907 - Jason Wessel <jason.wessel@windriver.com>