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