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