Commit | Line | Data |
---|---|---|
e3e2aaf7 JW |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> | |
4 | ||
5 | <book id="kgdbOnLinux"> | |
6 | <bookinfo> | |
7 | <title>Using kgdb and the kgdb Internals</title> | |
8 | ||
9 | <authorgroup> | |
10 | <author> | |
11 | <firstname>Jason</firstname> | |
12 | <surname>Wessel</surname> | |
13 | <affiliation> | |
14 | <address> | |
15 | <email>jason.wessel@windriver.com</email> | |
16 | </address> | |
17 | </affiliation> | |
18 | </author> | |
19 | </authorgroup> | |
20 | ||
21 | <authorgroup> | |
22 | <author> | |
23 | <firstname>Tom</firstname> | |
24 | <surname>Rini</surname> | |
25 | <affiliation> | |
26 | <address> | |
27 | <email>trini@kernel.crashing.org</email> | |
28 | </address> | |
29 | </affiliation> | |
30 | </author> | |
31 | </authorgroup> | |
32 | ||
33 | <authorgroup> | |
34 | <author> | |
35 | <firstname>Amit S.</firstname> | |
36 | <surname>Kale</surname> | |
37 | <affiliation> | |
38 | <address> | |
39 | <email>amitkale@linsyssoft.com</email> | |
40 | </address> | |
41 | </affiliation> | |
42 | </author> | |
43 | </authorgroup> | |
44 | ||
45 | <copyright> | |
46 | <year>2008</year> | |
47 | <holder>Wind River Systems, Inc.</holder> | |
48 | </copyright> | |
49 | <copyright> | |
50 | <year>2004-2005</year> | |
51 | <holder>MontaVista Software, Inc.</holder> | |
52 | </copyright> | |
53 | <copyright> | |
54 | <year>2004</year> | |
55 | <holder>Amit S. Kale</holder> | |
56 | </copyright> | |
57 | ||
58 | <legalnotice> | |
59 | <para> | |
60 | This file is licensed under the terms of the GNU General Public License | |
61 | version 2. This program is licensed "as is" without any warranty of any | |
62 | kind, whether express or implied. | |
63 | </para> | |
64 | ||
65 | </legalnotice> | |
66 | </bookinfo> | |
67 | ||
68 | <toc></toc> | |
69 | <chapter id="Introduction"> | |
70 | <title>Introduction</title> | |
71 | <para> | |
72 | kgdb is a source level debugger for linux kernel. It is used along | |
73 | with gdb to debug a linux kernel. The expectation is that gdb can | |
74 | be used to "break in" to the kernel to inspect memory, variables | |
f9250937 | 75 | and look through call stack information similar to what an |
e3e2aaf7 JW |
76 | application developer would use gdb for. It is possible to place |
77 | breakpoints in kernel code and perform some limited execution | |
78 | stepping. | |
79 | </para> | |
80 | <para> | |
81 | Two machines are required for using kgdb. One of these machines is a | |
82 | development machine and the other is a test machine. The kernel | |
83 | to be debugged runs on the test machine. The development machine | |
84 | runs an instance of gdb against the vmlinux file which contains | |
85 | the symbols (not boot image such as bzImage, zImage, uImage...). | |
86 | In gdb the developer specifies the connection parameters and | |
a606b5e2 JW |
87 | connects to kgdb. The type of connection a developer makes with |
88 | gdb depends on the availability of kgdb I/O modules compiled as | |
89 | builtin's or kernel modules in the test machine's kernel. | |
e3e2aaf7 JW |
90 | </para> |
91 | </chapter> | |
92 | <chapter id="CompilingAKernel"> | |
93 | <title>Compiling a kernel</title> | |
94 | <para> | |
f9250937 | 95 | To enable <symbol>CONFIG_KGDB</symbol> you should first turn on |
96 | "Prompt for development and/or incomplete code/drivers" | |
97 | (CONFIG_EXPERIMENTAL) in "General setup", then under the | |
98 | "Kernel debugging" select "KGDB: kernel debugging with remote gdb". | |
e3e2aaf7 JW |
99 | </para> |
100 | <para> | |
5f5ddfb3 JW |
101 | It is advised, but not required that you turn on the |
102 | CONFIG_FRAME_POINTER kernel option. This option inserts code to | |
103 | into the compiled executable which saves the frame information in | |
104 | registers or on the stack at different points which will allow a | |
105 | debugger such as gdb to more accurately construct stack back traces | |
106 | while debugging the kernel. | |
107 | </para> | |
108 | <para> | |
a9b60bf4 JW |
109 | If the architecture that you are using supports the kernel option |
110 | CONFIG_DEBUG_RODATA, you should consider turning it off. This | |
111 | option will prevent the use of software breakpoints because it | |
112 | marks certain regions of the kernel's memory space as read-only. | |
113 | If kgdb supports it for the architecture you are using, you can | |
114 | use hardware breakpoints if you desire to run with the | |
115 | CONFIG_DEBUG_RODATA option turned on, else you need to turn off | |
116 | this option. | |
117 | </para> | |
118 | <para> | |
e3e2aaf7 JW |
119 | Next you should choose one of more I/O drivers to interconnect debugging |
120 | host and debugged target. Early boot debugging requires a KGDB | |
121 | I/O driver that supports early debugging and the driver must be | |
122 | built into the kernel directly. Kgdb I/O driver configuration | |
123 | takes place via kernel or module parameters, see following | |
124 | chapter. | |
125 | </para> | |
126 | <para> | |
127 | The kgdb test compile options are described in the kgdb test suite chapter. | |
128 | </para> | |
129 | ||
130 | </chapter> | |
131 | <chapter id="EnableKGDB"> | |
132 | <title>Enable kgdb for debugging</title> | |
133 | <para> | |
134 | In order to use kgdb you must activate it by passing configuration | |
135 | information to one of the kgdb I/O drivers. If you do not pass any | |
136 | configuration information kgdb will not do anything at all. Kgdb | |
137 | will only actively hook up to the kernel trap hooks if a kgdb I/O | |
138 | driver is loaded and configured. If you unconfigure a kgdb I/O | |
139 | driver, kgdb will unregister all the kernel hook points. | |
140 | </para> | |
141 | <para> | |
142 | All drivers can be reconfigured at run time, if | |
143 | <symbol>CONFIG_SYSFS</symbol> and <symbol>CONFIG_MODULES</symbol> | |
144 | are enabled, by echo'ing a new config string to | |
145 | <constant>/sys/module/<driver>/parameter/<option></constant>. | |
146 | The driver can be unconfigured by passing an empty string. You cannot | |
147 | change the configuration while the debugger is attached. Make sure | |
148 | to detach the debugger with the <constant>detach</constant> command | |
149 | prior to trying unconfigure a kgdb I/O driver. | |
150 | </para> | |
151 | <sect1 id="kgdbwait"> | |
152 | <title>Kernel parameter: kgdbwait</title> | |
153 | <para> | |
154 | The Kernel command line option <constant>kgdbwait</constant> makes | |
155 | kgdb wait for a debugger connection during booting of a kernel. You | |
156 | can only use this option you compiled a kgdb I/O driver into the | |
157 | kernel and you specified the I/O driver configuration as a kernel | |
158 | command line option. The kgdbwait parameter should always follow the | |
159 | configuration parameter for the kgdb I/O driver in the kernel | |
160 | command line else the I/O driver will not be configured prior to | |
161 | asking the kernel to use it to wait. | |
162 | </para> | |
163 | <para> | |
164 | The kernel will stop and wait as early as the I/O driver and | |
165 | architecture will allow when you use this option. If you build the | |
166 | kgdb I/O driver as a kernel module kgdbwait will not do anything. | |
167 | </para> | |
168 | </sect1> | |
169 | <sect1 id="kgdboc"> | |
170 | <title>Kernel parameter: kgdboc</title> | |
171 | <para> | |
172 | The kgdboc driver was originally an abbreviation meant to stand for | |
173 | "kgdb over console". Kgdboc is designed to work with a single | |
225a4424 | 174 | serial port. It was meant to cover the circumstance |
e3e2aaf7 | 175 | where you wanted to use a serial console as your primary console as |
225a4424 JW |
176 | well as using it to perform kernel debugging. Of course you can |
177 | also use kgdboc without assigning a console to the same port. | |
e3e2aaf7 JW |
178 | </para> |
179 | <sect2 id="UsingKgdboc"> | |
180 | <title>Using kgdboc</title> | |
181 | <para> | |
182 | You can configure kgdboc via sysfs or a module or kernel boot line | |
183 | parameter depending on if you build with CONFIG_KGDBOC as a module | |
184 | or built-in. | |
185 | <orderedlist> | |
186 | <listitem><para>From the module load or build-in</para> | |
187 | <para><constant>kgdboc=<tty-device>,[baud]</constant></para> | |
188 | <para> | |
189 | The example here would be if your console port was typically ttyS0, you would use something like <constant>kgdboc=ttyS0,115200</constant> or on the ARM Versatile AB you would likely use <constant>kgdboc=ttyAMA0,115200</constant> | |
190 | </para> | |
191 | </listitem> | |
192 | <listitem><para>From sysfs</para> | |
193 | <para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para> | |
194 | </listitem> | |
195 | </orderedlist> | |
196 | </para> | |
197 | <para> | |
198 | NOTE: Kgdboc does not support interrupting the target via the | |
199 | gdb remote protocol. You must manually send a sysrq-g unless you | |
200 | have a proxy that splits console output to a terminal problem and | |
201 | has a separate port for the debugger to connect to that sends the | |
202 | sysrq-g for you. | |
203 | </para> | |
204 | <para>When using kgdboc with no debugger proxy, you can end up | |
205 | connecting the debugger for one of two entry points. If an | |
206 | exception occurs after you have loaded kgdboc a message should print | |
207 | on the console stating it is waiting for the debugger. In case you | |
208 | disconnect your terminal program and then connect the debugger in | |
209 | its place. If you want to interrupt the target system and forcibly | |
210 | enter a debug session you have to issue a Sysrq sequence and then | |
211 | type the letter <constant>g</constant>. Then you disconnect the | |
212 | terminal session and connect gdb. Your options if you don't like | |
213 | this are to hack gdb to send the sysrq-g for you as well as on the | |
214 | initial connect, or to use a debugger proxy that allows an | |
215 | unmodified gdb to do the debugging. | |
216 | </para> | |
217 | </sect2> | |
e3e2aaf7 JW |
218 | </sect1> |
219 | <sect1 id="kgdbcon"> | |
220 | <title>Kernel parameter: kgdbcon</title> | |
221 | <para> | |
222 | Kgdb supports using the gdb serial protocol to send console messages | |
223 | to the debugger when the debugger is connected and running. There | |
224 | are two ways to activate this feature. | |
225 | <orderedlist> | |
226 | <listitem><para>Activate with the kernel command line option:</para> | |
227 | <para><constant>kgdbcon</constant></para> | |
228 | </listitem> | |
229 | <listitem><para>Use sysfs before configuring an io driver</para> | |
230 | <para> | |
231 | <constant>echo 1 > /sys/module/kgdb/parameters/kgdb_use_con</constant> | |
232 | </para> | |
233 | <para> | |
234 | NOTE: If you do this after you configure the kgdb I/O driver, the | |
235 | setting will not take effect until the next point the I/O is | |
236 | reconfigured. | |
237 | </para> | |
238 | </listitem> | |
239 | </orderedlist> | |
240 | </para> | |
241 | <para> | |
242 | IMPORTANT NOTE: Using this option with kgdb over the console | |
a606b5e2 | 243 | (kgdboc) is not supported. |
e3e2aaf7 JW |
244 | </para> |
245 | </sect1> | |
246 | </chapter> | |
247 | <chapter id="ConnectingGDB"> | |
248 | <title>Connecting gdb</title> | |
249 | <para> | |
250 | If you are using kgdboc, you need to have used kgdbwait as a boot | |
251 | argument, issued a sysrq-g, or the system you are going to debug | |
252 | has already taken an exception and is waiting for the debugger to | |
253 | attach before you can connect gdb. | |
254 | </para> | |
255 | <para> | |
256 | If you are not using different kgdb I/O driver other than kgdboc, | |
257 | you should be able to connect and the target will automatically | |
258 | respond. | |
259 | </para> | |
260 | <para> | |
261 | Example (using a serial port): | |
262 | </para> | |
263 | <programlisting> | |
264 | % gdb ./vmlinux | |
265 | (gdb) set remotebaud 115200 | |
266 | (gdb) target remote /dev/ttyS0 | |
267 | </programlisting> | |
268 | <para> | |
a606b5e2 | 269 | Example (kgdb to a terminal server on tcp port 2012): |
e3e2aaf7 JW |
270 | </para> |
271 | <programlisting> | |
272 | % gdb ./vmlinux | |
a606b5e2 | 273 | (gdb) target remote 192.168.2.2:2012 |
e3e2aaf7 JW |
274 | </programlisting> |
275 | <para> | |
276 | Once connected, you can debug a kernel the way you would debug an | |
277 | application program. | |
278 | </para> | |
279 | <para> | |
280 | If you are having problems connecting or something is going | |
281 | seriously wrong while debugging, it will most often be the case | |
282 | that you want to enable gdb to be verbose about its target | |
283 | communications. You do this prior to issuing the <constant>target | |
284 | remote</constant> command by typing in: <constant>set remote debug 1</constant> | |
285 | </para> | |
286 | </chapter> | |
287 | <chapter id="KGDBTestSuite"> | |
288 | <title>kgdb Test Suite</title> | |
289 | <para> | |
290 | When kgdb is enabled in the kernel config you can also elect to | |
291 | enable the config parameter KGDB_TESTS. Turning this on will | |
292 | enable a special kgdb I/O module which is designed to test the | |
293 | kgdb internal functions. | |
294 | </para> | |
295 | <para> | |
296 | The kgdb tests are mainly intended for developers to test the kgdb | |
297 | internals as well as a tool for developing a new kgdb architecture | |
298 | specific implementation. These tests are not really for end users | |
299 | of the Linux kernel. The primary source of documentation would be | |
300 | to look in the drivers/misc/kgdbts.c file. | |
301 | </para> | |
302 | <para> | |
303 | The kgdb test suite can also be configured at compile time to run | |
304 | the core set of tests by setting the kernel config parameter | |
305 | KGDB_TESTS_ON_BOOT. This particular option is aimed at automated | |
306 | regression testing and does not require modifying the kernel boot | |
307 | config arguments. If this is turned on, the kgdb test suite can | |
308 | be disabled by specifying "kgdbts=" as a kernel boot argument. | |
309 | </para> | |
310 | </chapter> | |
311 | <chapter id="CommonBackEndReq"> | |
225a4424 JW |
312 | <title>KGDB Internals</title> |
313 | <sect1 id="kgdbArchitecture"> | |
e3e2aaf7 JW |
314 | <title>Architecture Specifics</title> |
315 | <para> | |
316 | Kgdb is organized into three basic components: | |
317 | <orderedlist> | |
318 | <listitem><para>kgdb core</para> | |
319 | <para> | |
320 | The kgdb core is found in kernel/kgdb.c. It contains: | |
321 | <itemizedlist> | |
322 | <listitem><para>All the logic to implement the gdb serial protocol</para></listitem> | |
323 | <listitem><para>A generic OS exception handler which includes sync'ing the processors into a stopped state on an multi cpu system.</para></listitem> | |
324 | <listitem><para>The API to talk to the kgdb I/O drivers</para></listitem> | |
325 | <listitem><para>The API to make calls to the arch specific kgdb implementation</para></listitem> | |
326 | <listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem> | |
327 | <listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem> | |
328 | </itemizedlist> | |
329 | </para> | |
330 | </listitem> | |
331 | <listitem><para>kgdb arch specific implementation</para> | |
332 | <para> | |
333 | This implementation is generally found in arch/*/kernel/kgdb.c. | |
334 | As an example, arch/x86/kernel/kgdb.c contains the specifics to | |
335 | implement HW breakpoint as well as the initialization to | |
336 | dynamically register and unregister for the trap handlers on | |
337 | this architecture. The arch specific portion implements: | |
338 | <itemizedlist> | |
339 | <listitem><para>contains an arch specific trap catcher which | |
340 | invokes kgdb_handle_exception() to start kgdb about doing its | |
341 | work</para></listitem> | |
342 | <listitem><para>translation to and from gdb specific packet format to pt_regs</para></listitem> | |
343 | <listitem><para>Registration and unregistration of architecture specific trap hooks</para></listitem> | |
344 | <listitem><para>Any special exception handling and cleanup</para></listitem> | |
345 | <listitem><para>NMI exception handling and cleanup</para></listitem> | |
346 | <listitem><para>(optional)HW breakpoints</para></listitem> | |
347 | </itemizedlist> | |
348 | </para> | |
349 | </listitem> | |
350 | <listitem><para>kgdb I/O driver</para> | |
351 | <para> | |
225a4424 JW |
352 | Each kgdb I/O driver has to provide an implemenation for the following: |
353 | <itemizedlist> | |
354 | <listitem><para>configuration via builtin or module</para></listitem> | |
355 | <listitem><para>dynamic configuration and kgdb hook registration calls</para></listitem> | |
356 | <listitem><para>read and write character interface</para></listitem> | |
357 | <listitem><para>A cleanup handler for unconfiguring from the kgdb core</para></listitem> | |
358 | <listitem><para>(optional) Early debug methodology</para></listitem> | |
359 | </itemizedlist> | |
360 | Any given kgdb I/O driver has to operate very closely with the | |
361 | hardware and must do it in such a way that does not enable | |
362 | interrupts or change other parts of the system context without | |
363 | completely restoring them. The kgdb core will repeatedly "poll" | |
364 | a kgdb I/O driver for characters when it needs input. The I/O | |
365 | driver is expected to return immediately if there is no data | |
366 | available. Doing so allows for the future possibility to touch | |
367 | watch dog hardware in such a way as to have a target system not | |
368 | reset when these are enabled. | |
e3e2aaf7 JW |
369 | </para> |
370 | </listitem> | |
371 | </orderedlist> | |
372 | </para> | |
373 | <para> | |
374 | If you are intent on adding kgdb architecture specific support | |
375 | for a new architecture, the architecture should define | |
376 | <constant>HAVE_ARCH_KGDB</constant> in the architecture specific | |
377 | Kconfig file. This will enable kgdb for the architecture, and | |
378 | at that point you must create an architecture specific kgdb | |
379 | implementation. | |
380 | </para> | |
381 | <para> | |
382 | There are a few flags which must be set on every architecture in | |
383 | their <asm/kgdb.h> file. These are: | |
384 | <itemizedlist> | |
385 | <listitem> | |
386 | <para> | |
387 | NUMREGBYTES: The size in bytes of all of the registers, so | |
388 | that we can ensure they will all fit into a packet. | |
389 | </para> | |
390 | <para> | |
391 | BUFMAX: The size in bytes of the buffer GDB will read into. | |
392 | This must be larger than NUMREGBYTES. | |
393 | </para> | |
394 | <para> | |
395 | CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call | |
396 | flush_cache_range or flush_icache_range. On some architectures, | |
397 | these functions may not be safe to call on SMP since we keep other | |
398 | CPUs in a holding pattern. | |
399 | </para> | |
400 | </listitem> | |
401 | </itemizedlist> | |
402 | </para> | |
403 | <para> | |
404 | There are also the following functions for the common backend, | |
405 | found in kernel/kgdb.c, that must be supplied by the | |
406 | architecture-specific backend unless marked as (optional), in | |
407 | which case a default function maybe used if the architecture | |
408 | does not need to provide a specific implementation. | |
409 | </para> | |
410 | !Iinclude/linux/kgdb.h | |
225a4424 JW |
411 | </sect1> |
412 | <sect1 id="kgdbocDesign"> | |
413 | <title>kgdboc internals</title> | |
414 | <para> | |
415 | The kgdboc driver is actually a very thin driver that relies on the | |
416 | underlying low level to the hardware driver having "polling hooks" | |
417 | which the to which the tty driver is attached. In the initial | |
418 | implementation of kgdboc it the serial_core was changed to expose a | |
419 | low level uart hook for doing polled mode reading and writing of a | |
420 | single character while in an atomic context. When kgdb makes an I/O | |
421 | request to the debugger, kgdboc invokes a call back in the serial | |
422 | core which in turn uses the call back in the uart driver. It is | |
423 | certainly possible to extend kgdboc to work with non-uart based | |
424 | consoles in the future. | |
425 | </para> | |
426 | <para> | |
427 | When using kgdboc with a uart, the uart driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting> | |
428 | #ifdef CONFIG_CONSOLE_POLL | |
429 | .poll_get_char = serial8250_get_poll_char, | |
430 | .poll_put_char = serial8250_put_poll_char, | |
431 | #endif | |
432 | </programlisting> | |
433 | Any implementation specifics around creating a polling driver use the | |
434 | <constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above. | |
435 | Keep in mind that polling hooks have to be implemented in such a way | |
436 | that they can be called from an atomic context and have to restore | |
437 | the state of the uart chip on return such that the system can return | |
438 | to normal when the debugger detaches. You need to be very careful | |
439 | with any kind of lock you consider, because failing here is most | |
440 | going to mean pressing the reset button. | |
441 | </para> | |
442 | </sect1> | |
e3e2aaf7 JW |
443 | </chapter> |
444 | <chapter id="credits"> | |
445 | <title>Credits</title> | |
446 | <para> | |
447 | The following people have contributed to this document: | |
448 | <orderedlist> | |
449 | <listitem><para>Amit Kale<email>amitkale@linsyssoft.com</email></para></listitem> | |
450 | <listitem><para>Tom Rini<email>trini@kernel.crashing.org</email></para></listitem> | |
e3e2aaf7 | 451 | </orderedlist> |
225a4424 JW |
452 | In March 2008 this document was completely rewritten by: |
453 | <itemizedlist> | |
454 | <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem> | |
455 | </itemizedlist> | |
e3e2aaf7 JW |
456 | </para> |
457 | </chapter> | |
458 | </book> | |
459 |