1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 8. Kernel Debugger Internals</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Using kgdb, kdb and the kernel debugger internals"><link rel="up" href="index.html" title="Using kgdb, kdb and the kernel debugger internals"><link rel="prev" href="KGDBTestSuite.html" title="Chapter 7. kgdb Test Suite"><link rel="next" href="API-kgdb-skipexception.html" title="kgdb_skipexception"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. Kernel Debugger Internals</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="KGDBTestSuite.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="API-kgdb-skipexception.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="CommonBackEndReq"></a>Chapter 8. Kernel Debugger Internals</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="CommonBackEndReq.html#kgdbArchitecture">Architecture Specifics</a></span></dt><dt><span class="sect1"><a href="kgdbocDesign.html">kgdboc internals</a></span></dt><dd><dl><dt><span class="sect2"><a href="kgdbocDesign.html#idp1114388756">kgdboc and uarts</a></span></dt><dt><span class="sect2"><a href="kgdbocDesign.html#kgdbocKbd">kgdboc and keyboards</a></span></dt><dt><span class="sect2"><a href="kgdbocDesign.html#kgdbocKms">kgdboc and kms</a></span></dt></dl></dd></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="kgdbArchitecture"></a>Architecture Specifics</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="API-kgdb-skipexception.html"><span class="phrase">kgdb_skipexception</span></a></span><span class="refpurpose"> — 2 (optional) exit kgdb_handle_exception early 3 </span></dt><dt><span class="refentrytitle"><a href="API-kgdb-breakpoint.html"><span class="phrase">kgdb_breakpoint</span></a></span><span class="refpurpose"> — 4 compiled in breakpoint 5 </span></dt><dt><span class="refentrytitle"><a href="API-kgdb-arch-init.html"><span class="phrase">kgdb_arch_init</span></a></span><span class="refpurpose"> — 6 Perform any architecture specific initalization. 7 </span></dt><dt><span class="refentrytitle"><a href="API-kgdb-arch-exit.html"><span class="phrase">kgdb_arch_exit</span></a></span><span class="refpurpose"> — 8 Perform any architecture specific uninitalization. 9 </span></dt><dt><span class="refentrytitle"><a href="API-pt-regs-to-gdb-regs.html"><span class="phrase">pt_regs_to_gdb_regs</span></a></span><span class="refpurpose"> — 10 Convert ptrace regs to GDB regs 11 </span></dt><dt><span class="refentrytitle"><a href="API-sleeping-thread-to-gdb-regs.html"><span class="phrase">sleeping_thread_to_gdb_regs</span></a></span><span class="refpurpose"> — 12 Convert ptrace regs to GDB regs 13 </span></dt><dt><span class="refentrytitle"><a href="API-gdb-regs-to-pt-regs.html"><span class="phrase">gdb_regs_to_pt_regs</span></a></span><span class="refpurpose"> — 14 Convert GDB regs to ptrace regs. 15 </span></dt><dt><span class="refentrytitle"><a href="API-kgdb-arch-handle-exception.html"><span class="phrase">kgdb_arch_handle_exception</span></a></span><span class="refpurpose"> — 16 Handle architecture specific GDB packets. 17 </span></dt><dt><span class="refentrytitle"><a href="API-kgdb-roundup-cpus.html"><span class="phrase">kgdb_roundup_cpus</span></a></span><span class="refpurpose"> — 18 Get other CPUs into a holding pattern 19 </span></dt><dt><span class="refentrytitle"><a href="API-kgdb-arch-set-pc.html"><span class="phrase">kgdb_arch_set_pc</span></a></span><span class="refpurpose"> — 20 Generic call back to the program counter 21 </span></dt><dt><span class="refentrytitle"><a href="API-kgdb-arch-late.html"><span class="phrase">kgdb_arch_late</span></a></span><span class="refpurpose"> — 22 Perform any architecture specific initalization. 23 </span></dt><dt><span class="refentrytitle"><a href="API-struct-kgdb-arch.html"><span class="phrase">struct kgdb_arch</span></a></span><span class="refpurpose"> — 24 Describe architecture specific values. 25 </span></dt><dt><span class="refentrytitle"><a href="API-struct-kgdb-io.html"><span class="phrase">struct kgdb_io</span></a></span><span class="refpurpose"> — 26 Describe the interface for an I/O driver to talk with KGDB. 27 </span></dt></dl></div><p> 28 The kernel debugger is organized into a number of components: 29 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>The debug core</p><p> 30 The debug core is found in kernel/debugger/debug_core.c. It contains: 31 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A generic OS exception handler which includes 32 sync'ing the processors into a stopped state on an multi-CPU 33 system.</p></li><li class="listitem"><p>The API to talk to the kgdb I/O drivers</p></li><li class="listitem"><p>The API to make calls to the arch-specific kgdb implementation</p></li><li class="listitem"><p>The logic to perform safe memory reads and writes to memory while using the debugger</p></li><li class="listitem"><p>A full implementation for software breakpoints unless overridden by the arch</p></li><li class="listitem"><p>The API to invoke either the kdb or kgdb frontend to the debug core.</p></li><li class="listitem"><p>The structures and callback API for atomic kernel mode setting.</p><p>NOTE: kgdboc is where the kms callbacks are invoked.</p></li></ul></div><p> 34 </p></li><li class="listitem"><p>kgdb arch-specific implementation</p><p> 35 This implementation is generally found in arch/*/kernel/kgdb.c. 36 As an example, arch/x86/kernel/kgdb.c contains the specifics to 37 implement HW breakpoint as well as the initialization to 38 dynamically register and unregister for the trap handlers on 39 this architecture. The arch-specific portion implements: 40 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>contains an arch-specific trap catcher which 41 invokes kgdb_handle_exception() to start kgdb about doing its 42 work</p></li><li class="listitem"><p>translation to and from gdb specific packet format to pt_regs</p></li><li class="listitem"><p>Registration and unregistration of architecture specific trap hooks</p></li><li class="listitem"><p>Any special exception handling and cleanup</p></li><li class="listitem"><p>NMI exception handling and cleanup</p></li><li class="listitem"><p>(optional) HW breakpoints</p></li></ul></div><p> 43 </p></li><li class="listitem"><p>gdbstub frontend (aka kgdb)</p><p>The gdbstub is located in kernel/debug/gdbstub.c. It contains:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>All the logic to implement the gdb serial protocol</p></li></ul></div></li><li class="listitem"><p>kdb frontend</p><p>The kdb debugger shell is broken down into a number of 44 components. The kdb core is located in kernel/debug/kdb. There 45 are a number of helper functions in some of the other kernel 46 components to make it possible for kdb to examine and report 47 information about the kernel without taking locks that could 48 cause a kernel deadlock. The kdb core contains implements the following functionality.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A simple shell</p></li><li class="listitem"><p>The kdb core command set</p></li><li class="listitem"><p>A registration API to register additional kdb shell commands.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>A good example of a self-contained kdb module 49 is the "ftdump" command for dumping the ftrace buffer. See: 50 kernel/trace/trace_kdb.c</p></li><li class="listitem"><p>For an example of how to dynamically register 51 a new kdb command you can build the kdb_hello.ko kernel module 52 from samples/kdb/kdb_hello.c. To build this example you can 53 set CONFIG_SAMPLES=y and CONFIG_SAMPLE_KDB=m in your kernel 54 config. Later run "modprobe kdb_hello" and the next time you 55 enter the kdb shell, you can run the "hello" 56 command.</p></li></ul></div></li><li class="listitem"><p>The implementation for kdb_printf() which 57 emits messages directly to I/O drivers, bypassing the kernel 58 log.</p></li><li class="listitem"><p>SW / HW breakpoint management for the kdb shell</p></li></ul></div></li><li class="listitem"><p>kgdb I/O driver</p><p> 59 Each kgdb I/O driver has to provide an implementation for the following: 60 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>configuration via built-in or module</p></li><li class="listitem"><p>dynamic configuration and kgdb hook registration calls</p></li><li class="listitem"><p>read and write character interface</p></li><li class="listitem"><p>A cleanup handler for unconfiguring from the kgdb core</p></li><li class="listitem"><p>(optional) Early debug methodology</p></li></ul></div><p> 61 Any given kgdb I/O driver has to operate very closely with the 62 hardware and must do it in such a way that does not enable 63 interrupts or change other parts of the system context without 64 completely restoring them. The kgdb core will repeatedly "poll" 65 a kgdb I/O driver for characters when it needs input. The I/O 66 driver is expected to return immediately if there is no data 67 available. Doing so allows for the future possibility to touch 68 watchdog hardware in such a way as to have a target system not 69 reset when these are enabled. 70 </p></li></ol></div><p> 71 </p><p> 72 If you are intent on adding kgdb architecture specific support 73 for a new architecture, the architecture should define 74 <code class="constant">HAVE_ARCH_KGDB</code> in the architecture specific 75 Kconfig file. This will enable kgdb for the architecture, and 76 at that point you must create an architecture specific kgdb 77 implementation. 78 </p><p> 79 There are a few flags which must be set on every architecture in 80 their <asm/kgdb.h> file. These are: 81 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 82 NUMREGBYTES: The size in bytes of all of the registers, so 83 that we can ensure they will all fit into a packet. 84 </p></li><li class="listitem"><p> 85 BUFMAX: The size in bytes of the buffer GDB will read into. 86 This must be larger than NUMREGBYTES. 87 </p></li><li class="listitem"><p> 88 CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call 89 flush_cache_range or flush_icache_range. On some architectures, 90 these functions may not be safe to call on SMP since we keep other 91 CPUs in a holding pattern. 92 </p></li></ul></div><p> 93 </p><p> 94 There are also the following functions for the common backend, 95 found in kernel/kgdb.c, that must be supplied by the 96 architecture-specific backend unless marked as (optional), in 97 which case a default function maybe used if the architecture 98 does not need to provide a specific implementation. 99 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="KGDBTestSuite.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="API-kgdb-skipexception.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. kgdb Test Suite </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">kgdb_skipexception</span></td></tr></table></div></body></html> 100