]>
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> | |
84c08fd6 | 7 | <title>Using kgdb, kdb and the kernel debugger internals</title> |
e3e2aaf7 JW |
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> | |
e3e2aaf7 | 20 | <copyright> |
84c08fd6 | 21 | <year>2008,2010</year> |
e3e2aaf7 JW |
22 | <holder>Wind River Systems, Inc.</holder> |
23 | </copyright> | |
24 | <copyright> | |
25 | <year>2004-2005</year> | |
26 | <holder>MontaVista Software, Inc.</holder> | |
27 | </copyright> | |
28 | <copyright> | |
29 | <year>2004</year> | |
30 | <holder>Amit S. Kale</holder> | |
31 | </copyright> | |
32 | ||
33 | <legalnotice> | |
34 | <para> | |
35 | This file is licensed under the terms of the GNU General Public License | |
36 | version 2. This program is licensed "as is" without any warranty of any | |
37 | kind, whether express or implied. | |
38 | </para> | |
39 | ||
40 | </legalnotice> | |
41 | </bookinfo> | |
42 | ||
43 | <toc></toc> | |
44 | <chapter id="Introduction"> | |
45 | <title>Introduction</title> | |
46 | <para> | |
84c08fd6 JW |
47 | The kernel has two different debugger front ends (kdb and kgdb) |
48 | which interface to the debug core. It is possible to use either | |
49 | of the debugger front ends and dynamically transition between them | |
50 | if you configure the kernel properly at compile and runtime. | |
51 | </para> | |
52 | <para> | |
53 | Kdb is simplistic shell-style interface which you can use on a | |
54 | system console with a keyboard or serial console. You can use it | |
55 | to inspect memory, registers, process lists, dmesg, and even set | |
56 | breakpoints to stop in a certain location. Kdb is not a source | |
57 | level debugger, although you can set breakpoints and execute some | |
58 | basic kernel run control. Kdb is mainly aimed at doing some | |
59 | analysis to aid in development or diagnosing kernel problems. You | |
60 | can access some symbols by name in kernel built-ins or in kernel | |
61 | modules if the code was built | |
62 | with <symbol>CONFIG_KALLSYMS</symbol>. | |
63 | </para> | |
64 | <para> | |
65 | Kgdb is intended to be used as a source level debugger for the | |
66 | Linux kernel. It is used along with gdb to debug a Linux kernel. | |
67 | The expectation is that gdb can be used to "break in" to the | |
68 | kernel to inspect memory, variables and look through call stack | |
69 | information similar to the way an application developer would use | |
70 | gdb to debug an application. It is possible to place breakpoints | |
71 | in kernel code and perform some limited execution stepping. | |
e3e2aaf7 JW |
72 | </para> |
73 | <para> | |
84c08fd6 JW |
74 | Two machines are required for using kgdb. One of these machines is |
75 | a development machine and the other is the target machine. The | |
76 | kernel to be debugged runs on the target machine. The development | |
77 | machine runs an instance of gdb against the vmlinux file which | |
78 | contains the symbols (not boot image such as bzImage, zImage, | |
79 | uImage...). In gdb the developer specifies the connection | |
80 | parameters and connects to kgdb. The type of connection a | |
81 | developer makes with gdb depends on the availability of kgdb I/O | |
82 | modules compiled as built-ins or loadable kernel modules in the test | |
83 | machine's kernel. | |
e3e2aaf7 JW |
84 | </para> |
85 | </chapter> | |
86 | <chapter id="CompilingAKernel"> | |
84c08fd6 JW |
87 | <title>Compiling a kernel</title> |
88 | <para> | |
89 | <itemizedlist> | |
90 | <listitem><para>In order to enable compilation of kdb, you must first enable kgdb.</para></listitem> | |
91 | <listitem><para>The kgdb test compile options are described in the kgdb test suite chapter.</para></listitem> | |
92 | </itemizedlist> | |
93 | </para> | |
94 | <sect1 id="CompileKGDB"> | |
95 | <title>Kernel config options for kgdb</title> | |
e3e2aaf7 | 96 | <para> |
f9250937 | 97 | To enable <symbol>CONFIG_KGDB</symbol> you should first turn on |
98 | "Prompt for development and/or incomplete code/drivers" | |
99 | (CONFIG_EXPERIMENTAL) in "General setup", then under the | |
84c08fd6 JW |
100 | "Kernel debugging" select "KGDB: kernel debugger". |
101 | </para> | |
102 | <para> | |
103 | While it is not a hard requirement that you have symbols in your | |
104 | vmlinux file, gdb tends not to be very useful without the symbolic | |
105 | data, so you will want to turn | |
106 | on <symbol>CONFIG_DEBUG_INFO</symbol> which is called "Compile the | |
107 | kernel with debug info" in the config menu. | |
e3e2aaf7 JW |
108 | </para> |
109 | <para> | |
5f5ddfb3 | 110 | It is advised, but not required that you turn on the |
84c08fd6 JW |
111 | <symbol>CONFIG_FRAME_POINTER</symbol> kernel option which is called "Compile the |
112 | kernel with frame pointers" in the config menu. This option | |
113 | inserts code to into the compiled executable which saves the frame | |
114 | information in registers or on the stack at different points which | |
115 | allows a debugger such as gdb to more accurately construct | |
116 | stack back traces while debugging the kernel. | |
5f5ddfb3 JW |
117 | </para> |
118 | <para> | |
a9b60bf4 JW |
119 | If the architecture that you are using supports the kernel option |
120 | CONFIG_DEBUG_RODATA, you should consider turning it off. This | |
121 | option will prevent the use of software breakpoints because it | |
122 | marks certain regions of the kernel's memory space as read-only. | |
123 | If kgdb supports it for the architecture you are using, you can | |
124 | use hardware breakpoints if you desire to run with the | |
125 | CONFIG_DEBUG_RODATA option turned on, else you need to turn off | |
126 | this option. | |
127 | </para> | |
128 | <para> | |
84c08fd6 JW |
129 | Next you should choose one of more I/O drivers to interconnect |
130 | debugging host and debugged target. Early boot debugging requires | |
131 | a KGDB I/O driver that supports early debugging and the driver | |
132 | must be built into the kernel directly. Kgdb I/O driver | |
133 | configuration takes place via kernel or module parameters which | |
134 | you can learn more about in the in the section that describes the | |
135 | parameter "kgdboc". | |
e3e2aaf7 | 136 | </para> |
84c08fd6 JW |
137 | <para>Here is an example set of .config symbols to enable or |
138 | disable for kgdb: | |
139 | <itemizedlist> | |
140 | <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem> | |
141 | <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem> | |
142 | <listitem><para>CONFIG_KGDB=y</para></listitem> | |
143 | <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem> | |
144 | </itemizedlist> | |
e3e2aaf7 | 145 | </para> |
84c08fd6 JW |
146 | </sect1> |
147 | <sect1 id="CompileKDB"> | |
148 | <title>Kernel config options for kdb</title> | |
149 | <para>Kdb is quite a bit more complex than the simple gdbstub | |
150 | sitting on top of the kernel's debug core. Kdb must implement a | |
151 | shell, and also adds some helper functions in other parts of the | |
152 | kernel, responsible for printing out interesting data such as what | |
153 | you would see if you ran "lsmod", or "ps". In order to build kdb | |
154 | into the kernel you follow the same steps as you would for kgdb. | |
155 | </para> | |
156 | <para>The main config option for kdb | |
157 | is <symbol>CONFIG_KGDB_KDB</symbol> which is called "KGDB_KDB: | |
158 | include kdb frontend for kgdb" in the config menu. In theory you | |
159 | would have already also selected an I/O driver such as the | |
160 | CONFIG_KGDB_SERIAL_CONSOLE interface if you plan on using kdb on a | |
161 | serial port, when you were configuring kgdb. | |
162 | </para> | |
163 | <para>If you want to use a PS/2-style keyboard with kdb, you would | |
164 | select CONFIG_KDB_KEYBOARD which is called "KGDB_KDB: keyboard as | |
165 | input device" in the config menu. The CONFIG_KDB_KEYBOARD option | |
166 | is not used for anything in the gdb interface to kgdb. The | |
167 | CONFIG_KDB_KEYBOARD option only works with kdb. | |
168 | </para> | |
169 | <para>Here is an example set of .config symbols to enable/disable kdb: | |
170 | <itemizedlist> | |
171 | <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem> | |
172 | <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem> | |
173 | <listitem><para>CONFIG_KGDB=y</para></listitem> | |
174 | <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem> | |
175 | <listitem><para>CONFIG_KGDB_KDB=y</para></listitem> | |
176 | <listitem><para>CONFIG_KDB_KEYBOARD=y</para></listitem> | |
177 | </itemizedlist> | |
178 | </para> | |
179 | </sect1> | |
e3e2aaf7 | 180 | </chapter> |
84c08fd6 JW |
181 | <chapter id="kgdbKernelArgs"> |
182 | <title>Kernel Debugger Boot Arguments</title> | |
183 | <para>This section describes the various runtime kernel | |
184 | parameters that affect the configuration of the kernel debugger. | |
185 | The following chapter covers using kdb and kgdb as well as | |
186 | provides some examples of the configuration parameters.</para> | |
187 | <sect1 id="kgdboc"> | |
188 | <title>Kernel parameter: kgdboc</title> | |
189 | <para>The kgdboc driver was originally an abbreviation meant to | |
190 | stand for "kgdb over console". Today it is the primary mechanism | |
191 | to configure how to communicate from gdb to kgdb as well as the | |
192 | devices you want to use to interact with the kdb shell. | |
193 | </para> | |
194 | <para>For kgdb/gdb, kgdboc is designed to work with a single serial | |
195 | port. It is intended to cover the circumstance where you want to | |
196 | use a serial console as your primary console as well as using it to | |
197 | perform kernel debugging. It is also possible to use kgdb on a | |
198 | serial port which is not designated as a system console. Kgdboc | |
199 | may be configured as a kernel built-in or a kernel loadable module. | |
200 | You can only make use of <constant>kgdbwait</constant> and early | |
201 | debugging if you build kgdboc into the kernel as a built-in. | |
e3e2aaf7 | 202 | </para> |
84c08fd6 JW |
203 | <sect2 id="kgdbocArgs"> |
204 | <title>kgdboc arguments</title> | |
205 | <para>Usage: <constant>kgdboc=[kbd][[,]serial_device][,baud]</constant></para> | |
206 | <sect3 id="kgdbocArgs1"> | |
207 | <title>Using loadable module or built-in</title> | |
e3e2aaf7 | 208 | <para> |
84c08fd6 JW |
209 | <orderedlist> |
210 | <listitem><para>As a kernel built-in:</para> | |
211 | <para>Use the kernel boot argument: <constant>kgdboc=<tty-device>,[baud]</constant></para></listitem> | |
212 | <listitem> | |
213 | <para>As a kernel loadable module:</para> | |
214 | <para>Use the command: <constant>modprobe kgdboc kgdboc=<tty-device>,[baud]</constant></para> | |
215 | <para>Here are two examples of how you might formate the kgdboc | |
216 | string. The first is for an x86 target using the first serial port. | |
217 | The second example is for the ARM Versatile AB using the second | |
218 | serial port. | |
219 | <orderedlist> | |
220 | <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem> | |
221 | <listitem><para><constant>kgdboc=ttyAMA1,115200</constant></para></listitem> | |
222 | </orderedlist> | |
e3e2aaf7 | 223 | </para> |
84c08fd6 JW |
224 | </listitem> |
225 | </orderedlist></para> | |
226 | </sect3> | |
227 | <sect3 id="kgdbocArgs2"> | |
228 | <title>Configure kgdboc at runtime with sysfs</title> | |
229 | <para>At run time you can enable or disable kgdboc by echoing a | |
230 | parameters into the sysfs. Here are two examples:</para> | |
231 | <orderedlist> | |
232 | <listitem><para>Enable kgdboc on ttyS0</para> | |
233 | <para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> | |
234 | <listitem><para>Disable kgdboc</para> | |
235 | <para><constant>echo "" > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> | |
236 | </orderedlist> | |
237 | <para>NOTE: You do not need to specify the baud if you are | |
238 | configuring the console on tty which is already configured or | |
239 | open.</para> | |
240 | </sect3> | |
241 | <sect3 id="kgdbocArgs3"> | |
242 | <title>More examples</title> | |
243 | <para>You can configure kgdboc to use the keyboard, and or a serial device | |
244 | depending on if you are using kdb and or kgdb, in one of the | |
245 | following scenarios. | |
246 | <orderedlist> | |
247 | <listitem><para>kdb and kgdb over only a serial port</para> | |
248 | <para><constant>kgdboc=<serial_device>[,baud]</constant></para> | |
249 | <para>Example: <constant>kgdboc=ttyS0,115200</constant></para> | |
250 | </listitem> | |
251 | <listitem><para>kdb and kgdb with keyboard and a serial port</para> | |
252 | <para><constant>kgdboc=kbd,<serial_device>[,baud]</constant></para> | |
253 | <para>Example: <constant>kgdboc=kbd,ttyS0,115200</constant></para> | |
254 | </listitem> | |
255 | <listitem><para>kdb with a keyboard</para> | |
256 | <para><constant>kgdboc=kbd</constant></para> | |
257 | </listitem> | |
258 | </orderedlist> | |
259 | </para> | |
260 | </sect3> | |
261 | <para>NOTE: Kgdboc does not support interrupting the target via the | |
262 | gdb remote protocol. You must manually send a sysrq-g unless you | |
263 | have a proxy that splits console output to a terminal program. | |
264 | A console proxy has a separate TCP port for the debugger and a separate | |
265 | TCP port for the "human" console. The proxy can take care of sending | |
266 | the sysrq-g for you. | |
267 | </para> | |
268 | <para>When using kgdboc with no debugger proxy, you can end up | |
269 | connecting the debugger at one of two entry points. If an | |
270 | exception occurs after you have loaded kgdboc, a message should | |
271 | print on the console stating it is waiting for the debugger. In | |
272 | this case you disconnect your terminal program and then connect the | |
273 | debugger in its place. If you want to interrupt the target system | |
274 | and forcibly enter a debug session you have to issue a Sysrq | |
275 | sequence and then type the letter <constant>g</constant>. Then | |
276 | you disconnect the terminal session and connect gdb. Your options | |
277 | if you don't like this are to hack gdb to send the sysrq-g for you | |
278 | as well as on the initial connect, or to use a debugger proxy that | |
279 | allows an unmodified gdb to do the debugging. | |
280 | </para> | |
281 | </sect2> | |
282 | </sect1> | |
e3e2aaf7 JW |
283 | <sect1 id="kgdbwait"> |
284 | <title>Kernel parameter: kgdbwait</title> | |
285 | <para> | |
286 | The Kernel command line option <constant>kgdbwait</constant> makes | |
287 | kgdb wait for a debugger connection during booting of a kernel. You | |
288 | can only use this option you compiled a kgdb I/O driver into the | |
289 | kernel and you specified the I/O driver configuration as a kernel | |
290 | command line option. The kgdbwait parameter should always follow the | |
291 | configuration parameter for the kgdb I/O driver in the kernel | |
292 | command line else the I/O driver will not be configured prior to | |
293 | asking the kernel to use it to wait. | |
294 | </para> | |
295 | <para> | |
296 | The kernel will stop and wait as early as the I/O driver and | |
84c08fd6 JW |
297 | architecture allows when you use this option. If you build the |
298 | kgdb I/O driver as a loadable kernel module kgdbwait will not do | |
299 | anything. | |
e3e2aaf7 JW |
300 | </para> |
301 | </sect1> | |
84c08fd6 JW |
302 | <sect1 id="kgdbcon"> |
303 | <title>Kernel parameter: kgdbcon</title> | |
304 | <para> The kgdbcon feature allows you to see printk() messages | |
305 | inside gdb while gdb is connected to the kernel. Kdb does not make | |
306 | use of the kgdbcon feature. | |
307 | </para> | |
308 | <para>Kgdb supports using the gdb serial protocol to send console | |
309 | messages to the debugger when the debugger is connected and running. | |
310 | There are two ways to activate this feature. | |
311 | <orderedlist> | |
312 | <listitem><para>Activate with the kernel command line option:</para> | |
313 | <para><constant>kgdbcon</constant></para> | |
314 | </listitem> | |
315 | <listitem><para>Use sysfs before configuring an I/O driver</para> | |
316 | <para> | |
317 | <constant>echo 1 > /sys/module/kgdb/parameters/kgdb_use_con</constant> | |
318 | </para> | |
319 | <para> | |
320 | NOTE: If you do this after you configure the kgdb I/O driver, the | |
321 | setting will not take effect until the next point the I/O is | |
322 | reconfigured. | |
323 | </para> | |
324 | </listitem> | |
325 | </orderedlist> | |
326 | <para>IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an | |
327 | active system console. An example incorrect usage is <constant>console=ttyS0,115200 kgdboc=ttyS0 kgdbcon</constant> | |
328 | </para> | |
329 | <para>It is possible to use this option with kgdboc on a tty that is not a system console. | |
330 | </para> | |
e3e2aaf7 | 331 | </para> |
84c08fd6 JW |
332 | </sect1> |
333 | </chapter> | |
334 | <chapter id="usingKDB"> | |
335 | <title>Using kdb</title> | |
e3e2aaf7 | 336 | <para> |
84c08fd6 JW |
337 | </para> |
338 | <sect1 id="quickKDBserial"> | |
339 | <title>Quick start for kdb on a serial port</title> | |
340 | <para>This is a quick example of how to use kdb.</para> | |
341 | <para><orderedlist> | |
342 | <listitem><para>Boot kernel with arguments: | |
343 | <itemizedlist> | |
344 | <listitem><para><constant>console=ttyS0,115200 kgdboc=ttyS0,115200</constant></para></listitem> | |
345 | </itemizedlist></para> | |
346 | <para>OR</para> | |
347 | <para>Configure kgdboc after the kernel booted; assuming you are using a serial port console: | |
348 | <itemizedlist> | |
349 | <listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> | |
350 | </itemizedlist> | |
e3e2aaf7 JW |
351 | </para> |
352 | </listitem> | |
84c08fd6 JW |
353 | <listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para> |
354 | <itemizedlist> | |
355 | <listitem><para>When logged in as root or with a super user session you can run:</para> | |
356 | <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> | |
357 | <listitem><para>Example using minicom 2.2</para> | |
358 | <para>Press: <constant>Control-a</constant></para> | |
359 | <para>Press: <constant>f</constant></para> | |
360 | <para>Press: <constant>g</constant></para> | |
e3e2aaf7 | 361 | </listitem> |
84c08fd6 JW |
362 | <listitem><para>When you have telneted to a terminal server that supports sending a remote break</para> |
363 | <para>Press: <constant>Control-]</constant></para> | |
364 | <para>Type in:<constant>send break</constant></para> | |
365 | <para>Press: <constant>Enter</constant></para> | |
366 | <para>Press: <constant>g</constant></para> | |
367 | </listitem> | |
368 | </itemizedlist> | |
369 | </listitem> | |
370 | <listitem><para>From the kdb prompt you can run the "help" command to see a complete list of the commands that are available.</para> | |
371 | <para>Some useful commands in kdb include: | |
372 | <itemizedlist> | |
373 | <listitem><para>lsmod -- Shows where kernel modules are loaded</para></listitem> | |
374 | <listitem><para>ps -- Displays only the active processes</para></listitem> | |
375 | <listitem><para>ps A -- Shows all the processes</para></listitem> | |
376 | <listitem><para>summary -- Shows kernel version info and memory usage</para></listitem> | |
377 | <listitem><para>bt -- Get a backtrace of the current process using dump_stack()</para></listitem> | |
378 | <listitem><para>dmesg -- View the kernel syslog buffer</para></listitem> | |
379 | <listitem><para>go -- Continue the system</para></listitem> | |
380 | </itemizedlist> | |
e3e2aaf7 | 381 | </para> |
84c08fd6 JW |
382 | </listitem> |
383 | <listitem> | |
384 | <para>When you are done using kdb you need to consider rebooting the | |
385 | system or using the "go" command to resuming normal kernel | |
386 | execution. If you have paused the kernel for a lengthy period of | |
387 | time, applications that rely on timely networking or anything to do | |
388 | with real wall clock time could be adversely affected, so you | |
389 | should take this into consideration when using the kernel | |
390 | debugger.</para> | |
391 | </listitem> | |
392 | </orderedlist></para> | |
393 | </sect1> | |
394 | <sect1 id="quickKDBkeyboard"> | |
395 | <title>Quick start for kdb using a keyboard connected console</title> | |
396 | <para>This is a quick example of how to use kdb with a keyboard.</para> | |
397 | <para><orderedlist> | |
398 | <listitem><para>Boot kernel with arguments: | |
399 | <itemizedlist> | |
400 | <listitem><para><constant>kgdboc=kbd</constant></para></listitem> | |
401 | </itemizedlist></para> | |
402 | <para>OR</para> | |
403 | <para>Configure kgdboc after the kernel booted: | |
404 | <itemizedlist> | |
405 | <listitem><para><constant>echo kbd > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> | |
406 | </itemizedlist> | |
e3e2aaf7 | 407 | </para> |
84c08fd6 JW |
408 | </listitem> |
409 | <listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para> | |
410 | <itemizedlist> | |
411 | <listitem><para>When logged in as root or with a super user session you can run:</para> | |
412 | <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> | |
413 | <listitem><para>Example using a laptop keyboard</para> | |
414 | <para>Press and hold down: <constant>Alt</constant></para> | |
415 | <para>Press and hold down: <constant>Fn</constant></para> | |
416 | <para>Press and release the key with the label: <constant>SysRq</constant></para> | |
417 | <para>Release: <constant>Fn</constant></para> | |
418 | <para>Press and release: <constant>g</constant></para> | |
419 | <para>Release: <constant>Alt</constant></para> | |
420 | </listitem> | |
421 | <listitem><para>Example using a PS/2 101-key keyboard</para> | |
422 | <para>Press and hold down: <constant>Alt</constant></para> | |
423 | <para>Press and release the key with the label: <constant>SysRq</constant></para> | |
424 | <para>Press and release: <constant>g</constant></para> | |
425 | <para>Release: <constant>Alt</constant></para> | |
426 | </listitem> | |
427 | </itemizedlist> | |
428 | </listitem> | |
429 | <listitem> | |
430 | <para>Now type in a kdb command such as "help", "dmesg", "bt" or "go" to continue kernel execution.</para> | |
431 | </listitem> | |
432 | </orderedlist></para> | |
e3e2aaf7 | 433 | </sect1> |
84c08fd6 JW |
434 | </chapter> |
435 | <chapter id="EnableKGDB"> | |
436 | <title>Using kgdb / gdb</title> | |
437 | <para>In order to use kgdb you must activate it by passing | |
438 | configuration information to one of the kgdb I/O drivers. If you | |
439 | do not pass any configuration information kgdb will not do anything | |
440 | at all. Kgdb will only actively hook up to the kernel trap hooks | |
441 | if a kgdb I/O driver is loaded and configured. If you unconfigure | |
442 | a kgdb I/O driver, kgdb will unregister all the kernel hook points. | |
443 | </para> | |
444 | <para> All kgdb I/O drivers can be reconfigured at run time, if | |
445 | <symbol>CONFIG_SYSFS</symbol> and <symbol>CONFIG_MODULES</symbol> | |
446 | are enabled, by echo'ing a new config string to | |
447 | <constant>/sys/module/<driver>/parameter/<option></constant>. | |
448 | The driver can be unconfigured by passing an empty string. You cannot | |
449 | change the configuration while the debugger is attached. Make sure | |
450 | to detach the debugger with the <constant>detach</constant> command | |
451 | prior to trying to unconfigure a kgdb I/O driver. | |
452 | </para> | |
453 | <sect1 id="ConnectingGDB"> | |
454 | <title>Connecting with gdb to a serial port</title> | |
e3e2aaf7 | 455 | <orderedlist> |
84c08fd6 JW |
456 | <listitem><para>Configure kgdboc</para> |
457 | <para>Boot kernel with arguments: | |
458 | <itemizedlist> | |
459 | <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem> | |
460 | </itemizedlist></para> | |
461 | <para>OR</para> | |
462 | <para>Configure kgdboc after the kernel booted: | |
463 | <itemizedlist> | |
464 | <listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> | |
465 | </itemizedlist></para> | |
e3e2aaf7 | 466 | </listitem> |
84c08fd6 JW |
467 | <listitem> |
468 | <para>Stop kernel execution (break into the debugger)</para> | |
469 | <para>In order to connect to gdb via kgdboc, the kernel must | |
470 | first be stopped. There are several ways to stop the kernel which | |
471 | include using kgdbwait as a boot argument, via a sysrq-g, or running | |
472 | the kernel until it takes an exception where it waits for the | |
473 | debugger to attach. | |
474 | <itemizedlist> | |
475 | <listitem><para>When logged in as root or with a super user session you can run:</para> | |
476 | <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> | |
477 | <listitem><para>Example using minicom 2.2</para> | |
478 | <para>Press: <constant>Control-a</constant></para> | |
479 | <para>Press: <constant>f</constant></para> | |
480 | <para>Press: <constant>g</constant></para> | |
e3e2aaf7 | 481 | </listitem> |
84c08fd6 JW |
482 | <listitem><para>When you have telneted to a terminal server that supports sending a remote break</para> |
483 | <para>Press: <constant>Control-]</constant></para> | |
484 | <para>Type in:<constant>send break</constant></para> | |
485 | <para>Press: <constant>Enter</constant></para> | |
486 | <para>Press: <constant>g</constant></para> | |
487 | </listitem> | |
488 | </itemizedlist> | |
e3e2aaf7 | 489 | </para> |
84c08fd6 JW |
490 | </listitem> |
491 | <listitem> | |
492 | <para>Connect from from gdb</para> | |
e3e2aaf7 | 493 | <para> |
84c08fd6 | 494 | Example (using a directly connected port): |
e3e2aaf7 JW |
495 | </para> |
496 | <programlisting> | |
497 | % gdb ./vmlinux | |
498 | (gdb) set remotebaud 115200 | |
499 | (gdb) target remote /dev/ttyS0 | |
500 | </programlisting> | |
501 | <para> | |
84c08fd6 | 502 | Example (kgdb to a terminal server on TCP port 2012): |
e3e2aaf7 JW |
503 | </para> |
504 | <programlisting> | |
505 | % gdb ./vmlinux | |
a606b5e2 | 506 | (gdb) target remote 192.168.2.2:2012 |
e3e2aaf7 JW |
507 | </programlisting> |
508 | <para> | |
509 | Once connected, you can debug a kernel the way you would debug an | |
510 | application program. | |
511 | </para> | |
512 | <para> | |
513 | If you are having problems connecting or something is going | |
514 | seriously wrong while debugging, it will most often be the case | |
515 | that you want to enable gdb to be verbose about its target | |
516 | communications. You do this prior to issuing the <constant>target | |
d34a792d | 517 | remote</constant> command by typing in: <constant>set debug remote 1</constant> |
e3e2aaf7 | 518 | </para> |
84c08fd6 JW |
519 | </listitem> |
520 | </orderedlist> | |
521 | <para>Remember if you continue in gdb, and need to "break in" again, | |
522 | you need to issue an other sysrq-g. It is easy to create a simple | |
523 | entry point by putting a breakpoint at <constant>sys_sync</constant> | |
524 | and then you can run "sync" from a shell or script to break into the | |
525 | debugger.</para> | |
526 | </sect1> | |
527 | </chapter> | |
528 | <chapter id="switchKdbKgdb"> | |
529 | <title>kgdb and kdb interoperability</title> | |
530 | <para>It is possible to transition between kdb and kgdb dynamically. | |
531 | The debug core will remember which you used the last time and | |
532 | automatically start in the same mode.</para> | |
533 | <sect1> | |
534 | <title>Switching between kdb and kgdb</title> | |
535 | <sect2> | |
536 | <title>Switching from kgdb to kdb</title> | |
537 | <para> | |
538 | There are two ways to switch from kgdb to kdb: you can use gdb to | |
539 | issue a maintenance packet, or you can blindly type the command $3#33. | |
540 | Whenever kernel debugger stops in kgdb mode it will print the | |
541 | message <constant>KGDB or $3#33 for KDB</constant>. It is important | |
542 | to note that you have to type the sequence correctly in one pass. | |
543 | You cannot type a backspace or delete because kgdb will interpret | |
544 | that as part of the debug stream. | |
545 | <orderedlist> | |
546 | <listitem><para>Change from kgdb to kdb by blindly typing:</para> | |
547 | <para><constant>$3#33</constant></para></listitem> | |
548 | <listitem><para>Change from kgdb to kdb with gdb</para> | |
549 | <para><constant>maintenance packet 3</constant></para> | |
550 | <para>NOTE: Now you must kill gdb. Typically you press control-z and | |
551 | issue the command: kill -9 %</para></listitem> | |
552 | </orderedlist> | |
553 | </para> | |
554 | </sect2> | |
555 | <sect2> | |
556 | <title>Change from kdb to kgdb</title> | |
557 | <para>There are two ways you can change from kdb to kgdb. You can | |
558 | manually enter kgdb mode by issuing the kgdb command from the kdb | |
559 | shell prompt, or you can connect gdb while the kdb shell prompt is | |
560 | active. The kdb shell looks for the typical first commands that gdb | |
561 | would issue with the gdb remote protocol and if it sees one of those | |
562 | commands it automatically changes into kgdb mode.</para> | |
563 | <orderedlist> | |
564 | <listitem><para>From kdb issue the command:</para> | |
565 | <para><constant>kgdb</constant></para> | |
566 | <para>Now disconnect your terminal program and connect gdb in its place</para></listitem> | |
567 | <listitem><para>At the kdb prompt, disconnect the terminal program and connect gdb in its place.</para></listitem> | |
568 | </orderedlist> | |
569 | </sect2> | |
570 | </sect1> | |
571 | <sect1> | |
572 | <title>Running kdb commands from gdb</title> | |
573 | <para>It is possible to run a limited set of kdb commands from gdb, | |
574 | using the gdb monitor command. You don't want to execute any of the | |
575 | run control or breakpoint operations, because it can disrupt the | |
576 | state of the kernel debugger. You should be using gdb for | |
577 | breakpoints and run control operations if you have gdb connected. | |
578 | The more useful commands to run are things like lsmod, dmesg, ps or | |
579 | possibly some of the memory information commands. To see all the kdb | |
580 | commands you can run <constant>monitor help</constant>.</para> | |
581 | <para>Example: | |
582 | <informalexample><programlisting> | |
583 | (gdb) monitor ps | |
584 | 1 idle process (state I) and | |
585 | 27 sleeping system daemon (state M) processes suppressed, | |
586 | use 'ps A' to see all. | |
587 | Task Addr Pid Parent [*] cpu State Thread Command | |
588 | ||
589 | 0xc78291d0 1 0 0 0 S 0xc7829404 init | |
590 | 0xc7954150 942 1 0 0 S 0xc7954384 dropbear | |
591 | 0xc78789c0 944 1 0 0 S 0xc7878bf4 sh | |
592 | (gdb) | |
593 | </programlisting></informalexample> | |
594 | </para> | |
595 | </sect1> | |
e3e2aaf7 JW |
596 | </chapter> |
597 | <chapter id="KGDBTestSuite"> | |
598 | <title>kgdb Test Suite</title> | |
599 | <para> | |
600 | When kgdb is enabled in the kernel config you can also elect to | |
601 | enable the config parameter KGDB_TESTS. Turning this on will | |
602 | enable a special kgdb I/O module which is designed to test the | |
603 | kgdb internal functions. | |
604 | </para> | |
605 | <para> | |
606 | The kgdb tests are mainly intended for developers to test the kgdb | |
607 | internals as well as a tool for developing a new kgdb architecture | |
608 | specific implementation. These tests are not really for end users | |
609 | of the Linux kernel. The primary source of documentation would be | |
610 | to look in the drivers/misc/kgdbts.c file. | |
611 | </para> | |
612 | <para> | |
613 | The kgdb test suite can also be configured at compile time to run | |
614 | the core set of tests by setting the kernel config parameter | |
615 | KGDB_TESTS_ON_BOOT. This particular option is aimed at automated | |
616 | regression testing and does not require modifying the kernel boot | |
617 | config arguments. If this is turned on, the kgdb test suite can | |
618 | be disabled by specifying "kgdbts=" as a kernel boot argument. | |
619 | </para> | |
620 | </chapter> | |
621 | <chapter id="CommonBackEndReq"> | |
84c08fd6 | 622 | <title>Kernel Debugger Internals</title> |
225a4424 | 623 | <sect1 id="kgdbArchitecture"> |
e3e2aaf7 JW |
624 | <title>Architecture Specifics</title> |
625 | <para> | |
84c08fd6 | 626 | The kernel debugger is organized into a number of components: |
e3e2aaf7 | 627 | <orderedlist> |
84c08fd6 | 628 | <listitem><para>The debug core</para> |
e3e2aaf7 | 629 | <para> |
84c08fd6 | 630 | The debug core is found in kernel/debugger/debug_core.c. It contains: |
e3e2aaf7 | 631 | <itemizedlist> |
84c08fd6 JW |
632 | <listitem><para>A generic OS exception handler which includes |
633 | sync'ing the processors into a stopped state on an multi-CPU | |
634 | system.</para></listitem> | |
e3e2aaf7 | 635 | <listitem><para>The API to talk to the kgdb I/O drivers</para></listitem> |
84c08fd6 | 636 | <listitem><para>The API to make calls to the arch-specific kgdb implementation</para></listitem> |
e3e2aaf7 JW |
637 | <listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem> |
638 | <listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem> | |
84c08fd6 | 639 | <listitem><para>The API to invoke either the kdb or kgdb frontend to the debug core.</para></listitem> |
e3e2aaf7 JW |
640 | </itemizedlist> |
641 | </para> | |
642 | </listitem> | |
84c08fd6 | 643 | <listitem><para>kgdb arch-specific implementation</para> |
e3e2aaf7 JW |
644 | <para> |
645 | This implementation is generally found in arch/*/kernel/kgdb.c. | |
646 | As an example, arch/x86/kernel/kgdb.c contains the specifics to | |
647 | implement HW breakpoint as well as the initialization to | |
648 | dynamically register and unregister for the trap handlers on | |
84c08fd6 | 649 | this architecture. The arch-specific portion implements: |
e3e2aaf7 | 650 | <itemizedlist> |
84c08fd6 | 651 | <listitem><para>contains an arch-specific trap catcher which |
e3e2aaf7 JW |
652 | invokes kgdb_handle_exception() to start kgdb about doing its |
653 | work</para></listitem> | |
654 | <listitem><para>translation to and from gdb specific packet format to pt_regs</para></listitem> | |
655 | <listitem><para>Registration and unregistration of architecture specific trap hooks</para></listitem> | |
656 | <listitem><para>Any special exception handling and cleanup</para></listitem> | |
657 | <listitem><para>NMI exception handling and cleanup</para></listitem> | |
658 | <listitem><para>(optional)HW breakpoints</para></listitem> | |
659 | </itemizedlist> | |
660 | </para> | |
661 | </listitem> | |
84c08fd6 JW |
662 | <listitem><para>gdbstub frontend (aka kgdb)</para> |
663 | <para>The gdbstub is located in kernel/debug/gdbstub.c. It contains:</para> | |
664 | <itemizedlist> | |
665 | <listitem><para>All the logic to implement the gdb serial protocol</para></listitem> | |
666 | </itemizedlist> | |
667 | </listitem> | |
668 | <listitem><para>kdb frontend</para> | |
669 | <para>The kdb debugger shell is broken down into a number of | |
670 | components. The kdb core is located in kernel/debug/kdb. There | |
671 | are a number of helper functions in some of the other kernel | |
672 | components to make it possible for kdb to examine and report | |
673 | information about the kernel without taking locks that could | |
674 | cause a kernel deadlock. The kdb core contains implements the following functionality.</para> | |
675 | <itemizedlist> | |
676 | <listitem><para>A simple shell</para></listitem> | |
677 | <listitem><para>The kdb core command set</para></listitem> | |
678 | <listitem><para>A registration API to register additional kdb shell commands.</para> | |
679 | <para>A good example of a self-contained kdb module is the "ftdump" command for dumping the ftrace buffer. See: kernel/trace/trace_kdb.c</para></listitem> | |
680 | <listitem><para>The implementation for kdb_printf() which | |
681 | emits messages directly to I/O drivers, bypassing the kernel | |
682 | log.</para></listitem> | |
683 | <listitem><para>SW / HW breakpoint management for the kdb shell</para></listitem> | |
684 | </itemizedlist> | |
685 | </listitem> | |
e3e2aaf7 JW |
686 | <listitem><para>kgdb I/O driver</para> |
687 | <para> | |
84c08fd6 | 688 | Each kgdb I/O driver has to provide an implementation for the following: |
225a4424 | 689 | <itemizedlist> |
84c08fd6 | 690 | <listitem><para>configuration via built-in or module</para></listitem> |
225a4424 JW |
691 | <listitem><para>dynamic configuration and kgdb hook registration calls</para></listitem> |
692 | <listitem><para>read and write character interface</para></listitem> | |
693 | <listitem><para>A cleanup handler for unconfiguring from the kgdb core</para></listitem> | |
694 | <listitem><para>(optional) Early debug methodology</para></listitem> | |
695 | </itemizedlist> | |
696 | Any given kgdb I/O driver has to operate very closely with the | |
697 | hardware and must do it in such a way that does not enable | |
698 | interrupts or change other parts of the system context without | |
699 | completely restoring them. The kgdb core will repeatedly "poll" | |
700 | a kgdb I/O driver for characters when it needs input. The I/O | |
701 | driver is expected to return immediately if there is no data | |
702 | available. Doing so allows for the future possibility to touch | |
703 | watch dog hardware in such a way as to have a target system not | |
704 | reset when these are enabled. | |
e3e2aaf7 JW |
705 | </para> |
706 | </listitem> | |
707 | </orderedlist> | |
708 | </para> | |
709 | <para> | |
710 | If you are intent on adding kgdb architecture specific support | |
711 | for a new architecture, the architecture should define | |
712 | <constant>HAVE_ARCH_KGDB</constant> in the architecture specific | |
713 | Kconfig file. This will enable kgdb for the architecture, and | |
714 | at that point you must create an architecture specific kgdb | |
715 | implementation. | |
716 | </para> | |
717 | <para> | |
718 | There are a few flags which must be set on every architecture in | |
719 | their <asm/kgdb.h> file. These are: | |
720 | <itemizedlist> | |
721 | <listitem> | |
722 | <para> | |
723 | NUMREGBYTES: The size in bytes of all of the registers, so | |
724 | that we can ensure they will all fit into a packet. | |
725 | </para> | |
726 | <para> | |
727 | BUFMAX: The size in bytes of the buffer GDB will read into. | |
728 | This must be larger than NUMREGBYTES. | |
729 | </para> | |
730 | <para> | |
731 | CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call | |
732 | flush_cache_range or flush_icache_range. On some architectures, | |
733 | these functions may not be safe to call on SMP since we keep other | |
734 | CPUs in a holding pattern. | |
735 | </para> | |
736 | </listitem> | |
737 | </itemizedlist> | |
738 | </para> | |
739 | <para> | |
740 | There are also the following functions for the common backend, | |
741 | found in kernel/kgdb.c, that must be supplied by the | |
742 | architecture-specific backend unless marked as (optional), in | |
743 | which case a default function maybe used if the architecture | |
744 | does not need to provide a specific implementation. | |
745 | </para> | |
746 | !Iinclude/linux/kgdb.h | |
225a4424 JW |
747 | </sect1> |
748 | <sect1 id="kgdbocDesign"> | |
749 | <title>kgdboc internals</title> | |
750 | <para> | |
751 | The kgdboc driver is actually a very thin driver that relies on the | |
752 | underlying low level to the hardware driver having "polling hooks" | |
753 | which the to which the tty driver is attached. In the initial | |
754 | implementation of kgdboc it the serial_core was changed to expose a | |
84c08fd6 | 755 | low level UART hook for doing polled mode reading and writing of a |
225a4424 JW |
756 | single character while in an atomic context. When kgdb makes an I/O |
757 | request to the debugger, kgdboc invokes a call back in the serial | |
84c08fd6 JW |
758 | core which in turn uses the call back in the UART driver. It is |
759 | certainly possible to extend kgdboc to work with non-UART based | |
225a4424 JW |
760 | consoles in the future. |
761 | </para> | |
762 | <para> | |
84c08fd6 | 763 | 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> |
225a4424 JW |
764 | #ifdef CONFIG_CONSOLE_POLL |
765 | .poll_get_char = serial8250_get_poll_char, | |
766 | .poll_put_char = serial8250_put_poll_char, | |
767 | #endif | |
768 | </programlisting> | |
769 | Any implementation specifics around creating a polling driver use the | |
770 | <constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above. | |
771 | Keep in mind that polling hooks have to be implemented in such a way | |
772 | that they can be called from an atomic context and have to restore | |
84c08fd6 | 773 | the state of the UART chip on return such that the system can return |
225a4424 JW |
774 | to normal when the debugger detaches. You need to be very careful |
775 | with any kind of lock you consider, because failing here is most | |
776 | going to mean pressing the reset button. | |
777 | </para> | |
778 | </sect1> | |
e3e2aaf7 JW |
779 | </chapter> |
780 | <chapter id="credits"> | |
781 | <title>Credits</title> | |
782 | <para> | |
783 | The following people have contributed to this document: | |
784 | <orderedlist> | |
785 | <listitem><para>Amit Kale<email>amitkale@linsyssoft.com</email></para></listitem> | |
786 | <listitem><para>Tom Rini<email>trini@kernel.crashing.org</email></para></listitem> | |
e3e2aaf7 | 787 | </orderedlist> |
225a4424 JW |
788 | In March 2008 this document was completely rewritten by: |
789 | <itemizedlist> | |
790 | <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem> | |
791 | </itemizedlist> | |
84c08fd6 JW |
792 | In Jan 2010 this document was updated to include kdb. |
793 | <itemizedlist> | |
794 | <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem> | |
795 | </itemizedlist> | |
e3e2aaf7 JW |
796 | </para> |
797 | </chapter> | |
798 | </book> | |
799 |