Introduction to Debugging the FreeBSD Kernel John H. Baldwin Yahoo!, Inc. Atlanta, GA 30327 [email protected], http://people.FreeBSD.org/˜jhb Abstract used either directly by the user or indirectly via other tools such as kgdb [3]. Just like every other piece of software, the The Kernel Debugging chapter of the FreeBSD kernel has bugs. Debugging a ker- FreeBSD Developer’s Handbook [4] covers nel is a bit different from debugging a user- several details already such as entering DDB, land program as there is nothing underneath configuring a system to save kernel crash the kernel to provide debugging facilities such dumps, and invoking kgdb on a crash dump. as ptrace() or procfs. This paper will give a This paper will not cover these topics. In- brief overview of some of the tools available stead, it will demonstrate some ways to use for investigating bugs in the FreeBSD kernel. FreeBSD’s kernel debugging tools to investi- It will cover the in-kernel debugger DDB and gate bugs. the external debugger kgdb which is used to perform post-mortem analysis on kernel crash dumps. 2 Kernel Crash Messages 1 Introduction The first debugging service the FreeBSD kernel provides is the messages the kernel prints on the console when the kernel crashes. When a userland application encounters a When the kernel encounters an invalid condi- bug the operating system provides services for tion (such as an assertion failure or a memory investigating the bug. For example, a kernel protection violation) it halts execution of the may save a copy of the a process’ memory current thread and enters a “panic” state also image on disk as a core dump. An operating known as a “crash”. The kernel will always system may also provide APIs for one process print a message on the console summarizing to analyze the state of another process. Using the reason for the crash. For many crashes these services, debugging tools such as gdb [1] this summary message is all the kernel out- can be written. puts. Figure 1 contains the crash message for a simple assertion violation. In this case the Operating system kernels have bugs just message indicates that a thread attempted to like userland applications. A key difference, sleep while sleeping is prohibited. however, is that operating system kernels are not always able to rely on a separate piece of Some crashes output more detailed mes- software to provide debugging services. As a sages to the console. Crashes caused by a result, kernels generally must provide their CPU exception generally output several de- own specialized support for debugging ser- tails. For example, if a thread in the ker- vices. The FreeBSD kernel provides several nel dereferences a pointer into unmapped services such as crash messages, crash dumps, memory (such as a NULL pointer) then the the /dev/kmem device, a remote GDB inter- crash messages will include the invalid ad- face, and a self-contained in-kernel debugger dress. Figure 2 contains the crash messages called DDB [2]. These services can then be for an amd64 page fault. This particular page panic: Trying sleep, but thread marked as sleeping prohibited Figure 1: Example Assertion Failure Crash fault was the result of a NULL pointer deref- system. The listing includes a summary of erence in the net.inet.tcp.pcblist sysctl the state of each thread including any lock handler. It was caused by a race condi- the thread is blocked on or a wait channel on tion where a struct tcpcb was freed in one which the thread is sleeping. More specific thread while another thread was in the sysctl details about individual processes may be ob- handler. tained via the show proc command. This command accepts a single argument that is The first key piece of data is the fault vir- either a direct pointer to a struct proc or a tual address. It is the invalid memory ad- process ID (PID). Similarly, the show thread dress that caused the fault. In this case command provides details about an individ- the fault address is indicative of a NULL ual thread and accepts either a direct pointer pointer derefence since its value is very small. to a struct thread or a thread ID (TID). The instruction pointer indicates the pro- Figure 3 shows a truncated list of processes gram counter value where the fault occurred. and threads in various states. Figure 4 shows This can be used either with gdb(1) or more detailed information about the first pro- addr2line(1) to determine the corresponding cess in the list and one of its threads. source line. The current process lists the com- mand name and PID of the process that was A very important part of a thread’s state is executing when the fault occurred. the stack trace. A stack trace provides a bit of history of where the thread has been in the past. It can also help explain how a thread arrived at its current state. DDB provides a 3 Live Debugging with DDB trace command to obtain the stack trace of single thread. With no aguments it will pro- vide a trace of the current thread. If an argu- Another debugging tool provided by the ment is specified then it may be either a TID FreeBSD kernel is the in-kernel debugger or a PID. If the argument is a PID, then the DDB. DDB is an interactive debugger that first thread from the indicated process will be allows the user to execute specific commands used. Figure 5 shows the stack trace for the to inspect various details of the running ker- thread blocked on the def lock. The trace in- nel. It is able to resolve global symbols to ad- dicates that the thread attempted to acquire dresses and control execution via breakpoints the lock in the aptly named mtx deadlock and single stepping. It is also extensible since function. new commands may be added at compile time. Details about several of the commonly used DDB commands may be found in the 3.2 Investigating Deadlocks ddb(4) manpage [2]. Debugging deadlocks requires determining 3.1 Inspecting Processes and which resources threads are waiting on and Threads then analyzing those dependencies to find a cycle. One source of deadlocks is mis- use of locking primitives such as mutexes. One of the best ways to get an overview DDB provides several commands for analyz- of a system’s state from DDB is to examine ing locking primitives and the dependency re- the current state of individual processes and lationships between threads and locks. threads. DDB provides several commands to do this. First, the ps command will display First, DDB provides commands to directly a list of all the processes and threads in the inspect the state of locks and the queues of Fatal trap 12: page fault while in kernel mode cpuid = 0; apic id = 00 fault virtual address = 0x4 fault code = supervisor read, page not present instruction pointer = 0x8:0xffffffff80359af8 stack pointer = 0x10:0xffffffffa3cbb550 frame pointer = 0x10:0xffffffffa3cbb570 code segment = base 0x0, limit 0xfffff, type 0x1b = DPL 0, pres 1, long 1, def32 0, gran 1 processor eflags = interrupt enabled, resume, IOPL = 0 current process = 31466 (netstat) trap number = 12 panic: page fault Figure 2: Example amd64 Page Fault db> ps pid ppid pgrp uid state wmesg wchan cmd 954 0 0 0 LL (threaded) crash2 100144 L *abc 0xffffff0001288dc0 [crash2: 3] 100143 L *jkl 0xffffff0001288c80 [crash2: 2] 100142 L *ghi 0xffffff0001288be0 [crash2: 1] 100055 L *def 0xffffff0001288d20 [crash2: 0] 812 0 0 0 SL - 0xffffffff80673a20 [nfsiod 0] 771 769 771 26840 Ss+ ttyin 0xffffff00011b9810 tcsh 769 767 767 26840 S select 0xffffff00018ca0d0 sshd 767 705 767 0 Ss sbwait 0xffffff00016ed94c sshd ... 10 0 0 0 RL (threaded) idle 100005 Run CPU 0 [idle: cpu0] 100004 Run CPU 1 [idle: cpu1] 100003 Run CPU 2 [idle: cpu2] 100002 Run CPU 3 [idle: cpu3] Figure 3: Example DDB ps Output db> show proc 954 Process 954 (crash2) at 0xffffff0001354000: state: NORMAL uid: 0 gids: 0 parent: pid 0 at 0xffffffff806538e0 ABI: null threads: 4 100144 L *abc 0xffffff0001288dc0 [crash2: 3] 100143 L *jkl 0xffffff0001288c80 [crash2: 2] 100142 L *ghi 0xffffff0001288be0 [crash2: 1] 100055 L *def 0xffffff0001288d20 [crash2: 0] db> show thread 100055 Thread 100055 at 0xffffff00013869c0: proc (pid 954): 0xffffff0001354000 name: crash2: 0 stack: 0xffffffffae213000-0xffffffffae216fff flags: 0x4 pflags: 0x200000 state: INHIBITED: {LOCK} lock: def turnstile: 0xffffff0001288d20 priority: 224 Figure 4: Inspecting a Process and Thread in DDB db> tr 100055 Tracing pid 954 tid 100055 td 0xffffff00013869c0 sched_switch() at sched_switch+0x15d mi_switch() at mi_switch+0x215 turnstile_wait() at turnstile_wait+0x24c _mtx_lock_sleep() at _mtx_lock_sleep+0xe0 _mtx_lock_flags() at _mtx_lock_flags+0x7a mtx_deadlock() at mtx_deadlock+0xb4 crash_thread() at crash_thread+0x138 fork_exit() at fork_exit+0x12a fork_trampoline() at fork_trampoline+0xe --- trap 0, rip = 0, rsp = 0xffffffffae23ed30, rbp = 0 --- Figure 5: Example DDB Stack Trace threads waiting for locks. The show lock for four threads locked in a cycle of lockmgr command takes the address of a lock (either a and sx locks. mutex [5], read-mostly lock [6], reader/writer lock [7], shared/exclusive (sx) lock [8], or lockmgr lock [9]) as its argument and displays 3.3 Adding New DDB Commands details about the lock including the current owner, if any. The show turnstile com- mand takes the address of a mutex, read- DDB commands are implemented by func- mostly lock or reader/writer wlock as its ar- tions in the kernel. Thus, new commands can gument. If there is a turnstile associated be added simply by writing new functions. with the lock, then it will display the lists Currently new commands cannot be added of threads waiting on the specified lock.