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