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