1 # Debug the DragonFly kernel
5 This chapter should give you an introduction how to obtain a crash dump after a kernel panic and how to extract useful information for the developers out of the dump.
9 ***Contributed by Matthias Schmidt***
13 ## Configure your system
15 Normally a crash dump is saved in your swap partition after a crash. If you reboot your machine the next time the dump is extracted by [savecore(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#savecore§ion8) from the partition and stored into `/var/crash`. Due to the fact that `/var` is a relatively small partition it could be possible that the dump isn't saved, because the dump size is larger than the remaining size.
19 To circumvent this problem you can change the default settings in `/etc/rc.conf`:
23 [[!table header=no data="""
24 > `dumpdev` | | Indicates the device (usually a swap partition) to which a crash dump should be written in the event of a system crash.
25 > `dumpdir` | | savecore(8) will save that crash dump and a copy of the kernel to the directory specified by the dumpdir variable. The default value is /var/crash. You can set this to another directory on another partition with more space available to safely obtain the dump.
28 If you are unsure about your swap partition device, use [swapinfo(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#swapinfo§ion8) or look into `/etc/fstab` :
33 Device 1K-blocks Used Avail Capacity Type
34 /dev/ad0s1b 1048448 0 1048448 0% Interleaved
36 # cat /etc/fstab | grep swap
37 /dev/ad0s1b none swap sw 0 0
40 ### Enable debugging options in your kernel config
42 If you don't know how to configure a custom kernel, look into [Configuring the DragonFly Kernel](kernelconfig.html). You have to add the following lines to compile your kernel with debugging symbols:
46 makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
49 If you want additional support for the interactive kernel debugger [ddb(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#ddb§ion4) and invariant debugging, also add these lines:
53 # Debugging for Development
60 ## How does a crash look like?
64 Easy answer: Your system stopped working. Complicated one: Your system occurred a [panic(9)](http://leaf.dragonflybsd.org/cgi/web-man?command#panic§ion9) and drops into [ddb(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=ddb§ion=4), the interactive kernel debugger.
66 The output while seeing a crash might look this:
70 Fatal trap 12: page fault while in kernel mode
71 fault virtual address = 0xd0686f55
72 fault code = supervisor read, page not present
73 instruction pointer = 0x8:0xc02ddb9a
74 stack pointer = 0x10:0xcec0fb18
75 frame pointer = 0x10:0xcec0fb18
76 code segment = base 0x0, limit 0xfffff, type 0x1b
77 = DPL 0, pres 1, def32 1, gran 1
78 processor eflags # interrupt enabled, resume, IOPL 0
79 current process = 50725 (sysctl)
80 current thread = pri 6
85 Before your machine reboots a crash dump is saved into your swap partition (if you have one and don't disabled crash dumps). Writing the dump to disk takes some time depending on your machine and the amount of RAM installed. This might look like this:
89 dumping to dev #ad/0x20001, blockno 1049088
90 dump 511 510 509 508 507 506 505
92 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 succeeded
94 Now your machine reboots, checks its file system and finally extracts the crash dump from the swap partition to your `dumpdir` (see `rc.conf` setting above). If your `/var` partition is to small, you'll see an error similar to the following:
98 savecore: reboot after panic: from debugger
99 savecore: no dump, not enough free space on device (231420 available, need 541840)
102 If this happens, you have to extract the crash dump yourselves. See next Section how to do this.
104 ### Extract a crash dump manually
106 You can use [savecore(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#savecore§ion8) to copy your currently running kernel and the associated crash dump to a particular directory you have to specify (we use `/usr/crash` here in the example):
110 # mkdir -p /usr/crash
111 # chmod 700 /usr/crash
112 # savecore /usr/crash/
117 This will take some time dependent on the speed of your machine. See the man page of savecore(8) for more available options.
119 ### Upload the crash dump
121 If you don't have the ability or skills to debug are crash yourselves, please upload the complete content of your crash directory to a public available location (HTTP, FTP web space or your leaf account) and send a detailed bug report to the bugs@dragonflybsd.org list. If its possible please tar and compress (gzip, bzip2) the directory to save disk space and bandwith.
125 ## Debug the crash dump with kgdb
127 The [kgdb(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#kgdb§ion1) utility is a debugger based on gdb(1) that allows debugging of kernel core files.
131 To get some handy helper command execute the following command before starting kgdb:
135 source /usr/src/test/debug/gdb.kernel
137 This gives you several new commands like kldstat (displays all loaded modules) or psx (displays all running processes).
139 Start kgdb as follows:
145 -rw-r--r-- 1 root wheel 2B Jan 7 17:07 bounds
146 -rw-r--r-- 1 root wheel 17M Jan 7 17:08 kernel.0
147 -rw------- 1 root wheel 512M Jan 7 17:08 vmcore.0
148 # kgdb kernel.0 vmcore.0
151 kgdb(1) will show you the panic message after start. The first thing to do is to obtain a ***backtrace*** with the ***bt*** command:
155 Unread portion of the kernel message buffer:
161 Fatal trap 12: page fault while in kernel mode
162 fault virtual address = 0xd0686f55
163 fault code = supervisor read, page not present
164 instruction pointer = 0x8:0xc02ddb9a
165 stack pointer = 0x10:0xcec0fb18
166 frame pointer = 0x10:0xcec0fb18
167 code segment = base 0x0, limit 0xfffff, type 0x1b
168 current process = 50725 (sysctl)
169 current thread = pri 6
177 Fatal trap 3: breakpoint instruction fault while in kernel mode
178 instruction pointer = 0x8:0xc03136a4
179 stack pointer = 0x10:0xcec0f92c
180 frame pointer = 0x10:0xcec0f934
181 code segment = base 0x0, limit 0xfffff, type 0x1b
182 = DPL 0, pres 1, def32 1, gran 1
183 processor eflags # interrupt enabled, IOPL 0
184 current process = 50725 (sysctl)
185 current thread = pri 6
193 dumping to dev #ad/0x20001, blockno 1049088
194 dump 511 510 509 508 507 506 505 504 503 502 501 500 499 498
196 40 39 38 37 36 35 34 33 32 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
201 Copyright 2004 Free Software Foundation, Inc.
202 GDB is free software, covered by the GNU General Public License, and you are
203 welcome to change it and/or distribute copies of it under certain conditions.
204 Type "show copying" to see the conditions.
205 There is absolutely no warranty for GDB. Type "show warranty" for details.
206 This GDB was configured as "i386-dragonfly".
208 #0 dumpsys () at thread.h:83
209 #1 0xc01c4e1b in boot (howto=260) at /usr/src/sys/kern/kern_shutdown.c:375
210 #2 0xc01c4f3c in panic (fmt=Variable "fmt" is not available.
211 ) at /usr/src/sys/kern/kern_shutdown.c:800
212 #3 0xc0149be5 in db_panic (addr=Could not find the frame base for "db_panic".
213 ) at /usr/src/sys/ddb/db_command.c:447
214 #4 0xc014a250 in db_command_loop () at /usr/src/sys/ddb/db_command.c:343
215 #5 0xc014c7bc in db_trap (type#12, code0) at /usr/src/sys/ddb/db_trap.c:71
216 #6 0xc03137f7 in kdb_trap (type#12, code0, regs=0xcec0fad0) at /usr/src/sys/platform/pc32/i386/db_interface.c:148
217 #7 0xc032384b in trap_fatal (frame#0xcec0fad0, evaVariable "eva" is not available.
218 ) at /usr/src/sys/platform/pc32/i386/trap.c:1091
219 #8 0xc03239b0 in trap_pfault (frame#0xcec0fad0, usermode0, eva=3496505173)
220 at /usr/src/sys/platform/pc32/i386/trap.c:997
221 #9 0xc03241a0 in trap (frame=0xcec0fad0) at /usr/src/sys/platform/pc32/i386/trap.c:680
222 #10 0xc0314506 in calltrap () at /usr/src/sys/platform/pc32/i386/exception.s:783
223 #11 0xc02ddb9a in strlen (str=0xd0686f55 <Address 0xd0686f55 out of bounds>) at /usr/src/sys/libkern/strlen.c:41
224 #12 0xc02c2153 in sysctl_vm_zone (oidp#0xc03b42a0, arg10x0, arg2=0, req=0xcec0fc08) at /usr/src/sys/vm/vm_zone.c:447
225 #13 0xc01cf935 in sysctl_root (oidp=Variable "oidp" is not available.
226 ) at /usr/src/sys/kern/kern_sysctl.c:1193
227 #14 0xc01cfa27 in userland_sysctl (name#0xcec0fc90, namelen2, old=0x0, oldlenp=0xbfbfe8f0, inkernel=0, new=0x0,
228 newlen#0, retval0xcec0fc8c) at /usr/src/sys/kern/kern_sysctl.c:1268
229 #15 0xc01cfc28 in sys___sysctl (uap=0xcec0fcf0) at /usr/src/sys/kern/kern_sysctl.c:1211
230 #16 0xc0323ccb in syscall2 (frame=0xcec0fd40) at /usr/src/sys/platform/pc32/i386/trap.c:1339
231 #17 0xc03145a5 in Xint0x80_syscall () at /usr/src/sys/platform/pc32/i386/exception.s:872
232 #18 0x08055d38 in ?? ()
233 #19 0xbfbfe86c in ?? ()
234 #20 0x0000002f in ?? ()
235 #21 0x00000000 in ?? ()
236 #22 0x00000000 in ?? ()
237 #23 0x00000000 in ?? ()
238 #24 0x00000000 in ?? ()
239 #25 0x13c4b000 in ?? ()
240 #26 0x00000001 in ?? ()
241 #27 0xc03c2bf8 in intr_info_ary ()
242 #28 0xcec0f8d4 in ?? ()
243 #29 0xcec0f8c4 in ?? ()
244 #30 0xc8076300 in ?? ()
245 #31 0xc01cac5a in lwkt_preempt (ntd#0x2, critpriCannot access memory at address 0xbfbfe8a4
246 ) at /usr/src/sys/kern/lwkt_thread.c:893
247 Previous frame inner to this frame (corrupt stack?)
251 kgdb(1) gives you the ability to look into specific frames, display variable content and obtain the source code (if your kernel was compiled with -g):
256 #13 0xc01cf935 in sysctl_root (oidp=Variable "oidp" is not available.
257 ) at /usr/src/sys/kern/kern_sysctl.c:1193
258 1193 error = oid->oid_handler(oid, oid->oid_arg1, oid->oid_arg2,
261 1189 if ((oid->oid_kind & CTLTYPE) # CTLTYPE_NODE)
262 1190 error = oid->oid_handler(oid, (int *)arg1 + indx, arg2 - indx,
265 1193 error = oid->oid_handler(oid, oid->oid_arg1, oid->oid_arg2,
271 $1 # {oid_parent 0xc03cbda8, oid_link = {sle_next = 0x0}, oid_number = 283, oid_kind = -2147483645, oid_arg1 = 0x0,
272 oid_arg2 # 0, oid_name 0xc03616ad "zone", oid_handler = 0xc02c20fa <sysctl_vm_zone>, oid_fmt = 0xc036a56f "A",
273 oid_refcnt # 0, oid_descr 0xc036906a "Zone Info"}
277 ## Further Information
279 To get more information about how to use a debugger, look here:
282 * [Man page of kgdb(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#kgdb§ion1)
285 * [Man page of gdb(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#gdb§ion1)
288 * [How to retrieve symbols from kernel modules](http://leaf.dragonflybsd.org/mailarchive/kernel/2005-11/msg00065.html)
291 * [FreeBSD Developers Handbook](http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/book.html#KERNELDEBUG)
294 * [GDB Manual](http://sourceware.org/gdb/documentation/)
297 * [Debug tutorial from Greg Lehey](http://www.lemis.com/grog/Papers/Debug-tutorial/tutorial.pdf)