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