ref: c04f70e2bb4a02655bb8a6247a8f07f75ff431bd
dir: /doc/acidtut.ms/
.de d0 .nr dP +1 .nr dV +1p .. .de d1 .nr dP -1 .nr dV -1p .. .nr dT 4 .de Af \" acid function .CW "\\$1(" "\fI\\$2\fP\f(CW)\fP" .. .TL Native Kernel Debugging with Acid .AU Tad Hunt tad@plan9.bell-labs.com .br Lucent Technologies Inc .br (Revised 22 May 2000 by Vita Nuova) .SH Introduction .PP This tutorial provides an introduction to the Acid debugger. It assumes that you are familiar with the features of a typical source-level debugger. The Acid debugger is built round a command language with a syntax similar to C. This tutorial is not an introduction to Acid as a whole, but offers a brief tour of the basic built in and standard library functions, especially those needed for debugging native Inferno kernels on a target board. .PP Acid was originally developed by Phil Winterbottom to help debug multi-threaded programs in the concurrent language Alef, and provide more sophisticated debugging for C programs. In the paper .I "Acid: A Debugger Built From a Language" , Winterbottom discusses Acid's design, including some worked examples of unusual applications of Acid to find memory leaks and assist code coverage analysis. Following that is the .I "Acid Reference Manual" , also by Phil Winterbottom, which gives a more precise specification of the Acid debugging language and its libraries. .SH Preliminaries -- the environment .PP Acid runs under the host operating system used for cross-development, in the same way as the Inferno compilers. Before running either compilers or Acid, the following environment variables must be set appropriately: .TS center; lf(CW) lf(R)w(4i) . ROOT T{ the directory in which Inferno lives (eg, .CW /usr/inferno ). T} SYSHOST T{ .I host operating system type: .CW Nt , .CW Solaris , .CW Plan9 , .CW Linux or .CW FreeBSD T} OBJTYPE T{ .I host machine's architecture type: .CW 386 , .CW sparc , .CW mips , or .CW powerpc T} .TE They might be set by a login shell profile (eg, Unix .CW ".profile" , or Plan 9 .CW lib/profile ). Also ensure that the directory .P1 $ROOT/$SYSHOST/$OBJTYPE/bin .P2 is on your search path. For example, on a Solaris sparc, one might use: .P1 ROOT=\fIinferno_root\fP SYSHOST=Solaris OBJTYPE=sparc ACIDLIB=$ROOT/lib/acid PATH=$ROOT/$SYSHOST/$OBJTYPE/bin:$PATH export ROOT ACIDLIB PATH OBJTYPE SYSHOST .P2 where .I "inferno_root" is the directory in which Inferno lives (eg, .CW "/usr/inferno" ). .SH An Example Program .PP The first example is not kernel code, but a small program that will be compiled but not run, to demonstrate basic Acid commands for source and object file inspection. The code is shown below: .P1 int factorial(int n) { if (n == 1) return 1; return n * factorial(n-1); } int f; void main(void) { f = factorial(5); } void _main(void) { main(); } .P2 .SH Compiling and Linking .PP The first step is to create an executable. The example shows the process for creating ARM executables. Substitute the appropriate compiler and linker for other cpu types. .P1 % 5c factorial.c % 5l -o factorial factorial.5 % ls factorial factorial.5 factorial.c .P2 .SH Starting Acid .PP Even without the target machine on which to run the program, many Acid features are available. The following command starts debugging the .CW "factorial" executable. Note that, upon startup, Acid will attempt to load some libaries from the directory specified in the .CW "ACIDLIB" environment variable (defaults to .CW "/usr/inferno/lib/acid" ). It will also attempt to load the file .CW "$HOME/lib/acid" , in which you can place commands to be executed during startup. .P1 % acid factorial factorial:Arm plan 9 executable $ROOT/lib/acid/port $ROOT/lib/acid/arm acid: .P2 .SH Exploring the Executable .PP To find out what symbols are in the program: .P1 acid: symbols("") etext T 0x00001068 f D 0x00002000 setR12 D 0x00002ffc end B 0x00002008 bdata D 0x00002000 edata D 0x00002008 factorial T 0x00001020 main T 0x00001048 _main T 0x0000105c acid: .P2 The output from the .CW symbols() function is similar to the output from the .I nm (10.1) command. The first column is the symbol name, the second column gives the section the symbol is in, and the third column is the address of the symbol. .PP There is also a .CW "symbols" global variable. Variables and functions can have the same names. It holds the list of symbol information that the .CW symbols function uses to generate the table: .d0 .P1 acid: symbols {{"etext", T, 0x00001068}, {"f", D, 0x00002000}, {"setR12", D, 0x00002ffc}, {"end", B, 0x00002008}, {"bdata", D, 0x00002000}, {"edata", D, 0x00002008}, {"factorial", T, 0x00001020}, {"main", T, 0x00001048}, {"_main", T, 0x00001 05c}} acid: .P2 .d1 In large programs, finding the symbol you are interested in from a list that may be thousands of lines long would be difficult. The string argument of .CW symbols() is a regular expression against which to match symbols. All symbols that contain the pattern will be displayed. For example: .P1 acid: symbols("main") main T 0x00001048 _main T 0x0000105c acid: symbols("^main") main T 0x00001048 acid: .P2 The .CW symbols function is written in the .I acid command language and lives in the .CW "port" library .CW $ACIDLIB/port ). ( .P1 defn symbols(pattern) { local l, s; l = symbols; while l do { s = head l; if regexp(pattern, s[0]) then print(s[0], "\t", s[1], "\t", s[2], "\n"); l = tail l; } } .P2 Acid retrieves the list of symbols from the executable and turns each one into a global variable whose value is the address of the symbol. If the symbol clashes with a builtin name or keyword or a previously defined function, enough .CW "$" characters are prepended to the name to make it unique. The list of such renamings is printed at startup. .PP Most acid functions operate on addresses. For example, to view the source code for a given address, use the .CW src function: .P1 acid: src(main) /usr/jrf/factorial.c:10 5 return n * factorial(n-1); 6 } 7 8 int f; 9 void >10 main(void) 11 { 12 f = factorial(5); 13 } 14 15 void .P2 The .Af "src" addr function displays a section of source code, with the line containing the address passed as an argument in the middle of the display. To print the assembly code beginning at a given address, use the .CW asm() function. .P1 acid: asm(factorial) factorial 0x00001020 MOVW.W R14,#-0x8(R13) factorial+0x4 0x00001024 CMP.S $#0x1,R0 factorial+0x8 0x00001028 MOVW.EQ $#0x1,R0 factorial+0xc 0x0000102c RET.EQ.P #0x8(R13) factorial+0x10 0x00001030 MOVW R0,n+0(FP) factorial+0x14 0x00001034 SUB $#0x1,R0,R0 factorial+0x18 0x00001038 BL factorial factorial+0x1c 0x0000103c MOVW n+0(FP),R2 factorial+0x20 0x00001040 MUL R2,R0,R0 factorial+0x24 0x00001044 RET.P #0x8(R13) main 0x00001048 MOVW.W R14,#-0x8(R13) acid: .P2 The output contains the symbolic address (symbol name+offset, where symbol name is the name of the enclosing function) followed by the absolute address, followed by the disassembled code. The .Af "asm" addr function prints the assembly beginning at .I "addr" and ending after either 30 lines have been printed, or the end of the function has been reached. The .CW "casm()" function continues the assembly listing from where it left off, even past the end of the function and into the next one. .P1 acid: casm() main+0x4 0x0000104c MOVW $#0x5,R0 main+0x8 0x00001050 BL factorial main+0xc 0x00001054 MOVW R0,$f-SB(SB) main+0x10 0x00001058 RET.P #0x8(R13) _main 0x0000105c MOVW.W R14,#-0x4(R13) acid: .P2 All the functions presented so far are written in the acid command language. To see the source of a comand written in the acid command language, use the builtin command .CW "whatis [" "\fIname\fP\f(CW ]\fP." It prints the definition of the optional argument .I "name" . If .I "name" is an Acid builtin, .CW whatis prints .CW "builtin function" . .P1 acid: whatis casm defn casm() { asm(lasmaddr); } acid: acid: whatis atof builtin function acid: .P2 If .I name is a variable, it prints the type of variable, and for the integer type, gives the format code used to print the value: .P1 acid: whatis pid integer variable format D acid: .P2 With no arguments, .CW whatis lists all available functions: .P1 acid: whatis Bsrc bpmask follow new sh _bpconddel bpneq func newproc source _bpcondset bpor gpr next spr _stk bpprint include notestk spsrch access bppush interpret params src acidinit bpset itoa pcfile start addsrcdir bptab kill pcline startstop asm casm kstk pfl status atof cont labstk print stk atoi debug line printto stmnt bpaddr dump linkreg procs stop bpand error lkstk rc stopped bpconddel file locals readfile strace bpcondset filepc lstk reason symbols bpdel findsrc map regexp waitstop bpderef fmt match regs bpeq fnbound mem setproc acid: .P2 The .Af "Bsrc" addr function brings up an editor on the line containing .I "addr" . It simply invokes a shell script named .CW "B" that takes two arguments, .I "-line" and .I "file" The shell script invokes .CW "$EDITOR +" .I "line file" . If unset, .CW "EDITOR" defaults to .I vi . The shell script, or the .CW Bsrc function can be easily rewritten to work with your favorite editor. .PP Entering a symbol name by itself will print the address of the symbol. Prefixing the symbol name with a .CW "*" will print the value at the address in the variable. Continuing to use our .CW "factorial" example: .P1 acid: f 0x00002000 acid: *f 0x00000000 acid: .P2 .SH Remote Debugging .PP Now that you have a basic understanding of how to explore the executable, it is time to examine a real remote debugging session. .PP We'll use the SA1100 keyboard driver as an example. Examining the kernel configuration file, you'll see the following: .P1 dev keyboard link driver/keyboard port scanfujn860 kbd.h keycodes.h link ./../driver plat kbdfujitsu ./../common/ssp.h \e /driver/keyboard/kbd.h \e /driver/keyboard/keycodes.h port const char *defaultkeyboard = "fujitsu"; const char *defaultkeytable = "scanfujn860"; int debugkeys = 1; /* 1 = enabled, 0 = disabled */ .P2 This describes the pieces of the keyboard driver which are linked into the kernel. The source code lives in two places, .CW "$ROOT/os/driver/keyboard" , and .CW "$ROOT/os/plat/sa1100/driver" . .PP The next step is to build a kernel. Use the .I mk target .CW acid to ensure that the Acid symbolic debugging data is produced. For example: .P1 % mk 'CONF=sword' acid isword.p9.gz .P2 This creates the Acid file .CW isword.acid , containing Acid declarations describing kernel structures, the kernel executable .CW isword.p9 ; and finally .I gzip s a copy of the kernel in .CW isword.p9.gz to load onto the device. Next, copy the gzipped image onto the device and then boot it. Follow the directions found elsewhere for details of this process. .PP From a shell prompt on the target device, start the remote debugger by writing the letter .CW r (for run) to .CW "#b/dbgctl" . Next, start Acid in remote debug mode, specifying the serial port it is connected to with the .CW "-R" option. .CW "$CONF" is the name of the configuration file used, for example .CW "sword" . .P1 % acid -R /dev/cua/b -l i$CONF.acid i$CONF isword:Arm plan 9 executable $ROOT/lib/acid/port i$CONF.acid $ROOT/lib/acid/arm /usr/jrf/lib/acid acid: .P2 You are now debugging the kernel that is running on the target device. All of the previously listed commands will work as described before, in addition, there are many more commands available. .SH Kernel Process Listing .PP To get a list of kernel processes, use the .CW "ps()" function: .P1 acid: ps() PID PC PRI STATE NAME 1 0x00054684 5 Queueing interp 2 0x00000000 1 Wakeme consdbg 3 0x00000000 5 Wakeme tcpack 4 0x00000000 5 Wakeme Fs.sync 5 0x00000000 4 Wakeme touchscreen 6 0x00054684 5 Queueing dis 7 0x00059788 5 Wakeme dis 8 0x00054684 5 Queueing dis 9 0x00054684 5 Queueing dis 10 0x00054684 5 Wakeme dis 11 0x0004c26c 1 Running dbg acid: .P2 The .CW "PC" column shows the address the process was executing at when the .CW ps command retrieved statistics on it. The .CW "PRI" column lists process priorities. The smaller the number the higher the process priority. Notice that the kernel process (kproc) running the debugger is the highest priority process in the system. The only process you will ever see in the .CW "Running" state while executing the .CW ps command will be the debugger, since it is gathering information about the other processes. .SH Breakpoints .PP Breakpoints in Inferno, unlike most traditional kernel debuggers, are conditional breakpoints. There are minimally two conditions which must be met. These conditions are address and process id. A breakpoint will only be taken when execution for a specific kernel process reaches the specified address. The user can create additional conditions that are evaluated if the address and process id match. If evaluation of these conditions result in a nonzero value, the breakpoint is taken, otherwise it is ignored, and execution continues. .PP Again, the best way to proceed is with an example: .P1 acid: setproc(7) .P2 The .Af setproc pid function selects a kproc to which later commands will be applied; the one with process ID (\fIpid\fP) in this case. .P1 acid: bpset(keyboardread) Waiting... 7: stopped flush8to4+0x18c MOVW (R3<<#4),R3 .P2 After selecting a kproc, we set a breakpoint at the address referred to by the .CW "keyboardread" symbol. As described before, the value of a global variable created from a symbol in the executable is the address of the symbol. In this case the address is the first instruction in the .CW "keyboardread()" function. Notice that setting a breakpoint stops the kproc from executing. A bit later, we'll see how to get it to continue execution. .PP Next, display the list of breakpoints using .CW "bptab()" : .P1 acid: bptab() ID PID ADDR CONDITIONS 0 7 keyboardread 0x0003c804 { } .P2 The first column is a unique number that identifies the breakpoint. The second column is the process ID in which the breakpoint will be taken. The third and fourth columns are the address of the breakpoint, first in symbolic form, then in numeric form. Finally, the last column is a list of conditions to evaluate whenever the kproc specified in the .CW "PID" column hits the the address specified in the .CW "ADDR" column. When they match, the list of conditions is evaluated. If the result is nonzero, the breakpoint is taken. Since we used the simplified breakpoint creation function, .CW "bpset()" , there are no additional conditions. Later on, we'll see how to set conditional breakpoints. .PP Start the selected kproc executing again, and wait for it to hit the breakpoint. .P1 acid: cont() .P2 The .CW "cont()" function will not return until a breakpoint has been hit, and there is no way to interrupt it. This means you should only set breakpoints that will be hit, otherwise you'll have to reboot the target device and restart your debugging session. .PP To continue our example, repeatedly hit new line (return, enter) on the keyboard on the target device, until the breakpoint occurs: .P1 break 0: pid 7: stopped keyboardread SUB $#0xa4,R13,R13 acid: .P2 This message, followed by the interactive prompt returning tells you that a breakpoint was hit. It gives the breakpoint id, the kernel process id, then the symbolic address at which execution halted, followed by the disassembly of the instruction at that address. .PP The .CW "kstk()" function prints a kernel stack trace, beginning with the current frame, all the way back to the call that started the kproc. For each function, it gives the name name, arguments, source file, and line number, followed by the symbolic address, source file, and line number of the caller. .d0 .P1 acid: kstk() At pc:247812:keyboardread /usr/inferno/os/driver/keyboard/devkey board.c:350 keyboardread(offset=0x0000009d,buf=0x001267f8,n=0x00000001) /usr /inferno/os/driver/keyboard/devkeyboard.c:350 called from kchanio+0x9c /usr/inferno/os/port/sysfile.c: 75 kchanio(buf=0x001267f8,n=0x00000001,mode=0x00000000) /usr/infern o/os/port/sysfile.c:64 called from consread+0x144 /usr/inferno/os/driver/port/d evcons consread(offset=0x0000009d,buf=0x0043d4fc,n=0x00000400,c=0x0044e c38) / usr/inferno/os/driver/port/devcons.c:357 called from kread+0x164 /usr/inferno/os/port/sysfile.c:2 97 kread(fd=0x00000006,n=0x00000400,va=0x0043d4fc) /usr/inferno/os/ port/sysfile.c:272 called from Sys_read+0x84 /usr/inferno/os/port/inferno.c :244 Sys_read() /usr/inferno/os/port/inferno.c:229 called from mcall+0x98 /usr/inferno/interp/xec.c:590 mcall() /usr/inferno/interp/xec.c:569 called from xec+0x128 /usr/inferno/interp/xec.c:1098 xec(p=0x0044edd8) /usr/inferno/interp/xec.c:1077 called from vmachine+0xbc /usr/inferno/os/port/dis.c:706 vmachine() /usr/inferno/os/port/dis.c:677 called from _main+0x50 /usr/inferno/os/plat/sa1100/infern o/main.c:237 acid: .P2 .d1 There is another kernel stack dump function, .CW "lkstk()" which shows the same information as .CW "kstk()" plus the names and values of local variables. Notice that in addition to the `called from' information, each local variable and its value is listed on a line by itself. .d0 .P1 acid: lkstk() At pc:247812:keyboardread /usr/inferno/os/driver/keyboard/devkeyboard. c:350 keyboardread(offset=0x00000018,buf=0x001267f9,n=0x00000001) /usr/inferno /os/driver/keyboard/devkeyboard.c:350 called from kchanio+0x9c /usr/inferno/os/port/sysfile.c:75 tmp=0x00000000 kchanio(buf=0x001267f9,n=0x00000001,mode=0x00000000) /usr/inferno/os/por t/sysfile.c:64 called from consread+0x144 /usr/inferno/os/driver/port/devcons c=0x0045a858 r=0x00000001 consread(offset=0x00000015,buf=0x0043d4fc,n=0x00000400,c=0x0044ec38) /us r/inferno/os/driver/port/devcons.c:357 called from kread+0x164 /usr/inferno/os/port/sysfile.c:297 r=0x00000001 ch=0x0000006c eol=0x00000000 i=0x00000000 mt=0x60000053 tmp=0x0007317c l=0x0044ec38 p=0x00049754 kread(fd=0x00000006,n=0x00000400,va=0x0043d4fc) /usr/inferno/os/port/sys file.c:272 called from Sys_read+0x84 /usr/inferno/os/port/inferno.c:244 c=0x0044ec38 dir=0x00000000 Sys_read() /usr/inferno/os/port/inferno.c:229 called from mcall+0x98 /usr/inferno/interp/xec.c:590 f=0x0044eff0 n=0x00000400 mcall() /usr/inferno/interp/xec.c:569 called from xec+0x128 /usr/inferno/interp/xec.c:1098 ml=0x0043d92c f=0x0044eff0 xec(p=0x0044edd8) /usr/inferno/interp/xec.c:1077 called from vmachine+0xbc /usr/inferno/os/port/dis.c:706 vmachine() /usr/inferno/os/port/dis.c:677 called from _main+0x50 /usr/inferno/os/plat/sa1100/inferno/main. c:237 r=0x0044edd8 o=0x0044ee50 .P2 .d1 The .CW "step()" function allows the currently selected process to execute a single instruction, and then stop. .P1 acid: step() break 1: pid 7: stopped keyboardread+0x4 MOVW R14,#0x0(R13) acid: .P2 The .CW "bpdel" ( .I id ) command deletes the breakpoint identified by .I id : .P1 acid: bpdel(0) .P2 The .CW "start()" command places the kproc back into the state it was in when it was stopped. .P1 acid: start(7) acid: .P2 Now lets look at how to set conditional breakpoints. .d0 .P1 acid: bpcondset(7, keyboardread, {bppush(_startup), bpderef()}) Waiting... 7: stopped sched+0x20 MOVW #0xffffff70(R12),R6 acid: bptab() ID PID ADDR CONDITIONS 0 7 keyboardread 0x0003c804 { {"p", 0x00008020} {"*", 0x00000000} } acid: *_startup = 0 acid: cont() .P2 .d1 Conditional breakpoints are set with .CW "bpcondset()" . It takes three arguments, the kernel process id, the address, and a list of stack based operations which are executed if the pid and addr match. The operations push values onto the stack, and if at the end of execution, a nonzero value is on the top of the stack, the breakpoint is taken. Examining the list of breakpoints with the .CW "bptab()" function shows the list of conditions to apply. The list is a bit confusing to read, but the .CW ""p"" means push and the .CW ""*"" means .I dereference . .PP No matter how much you type on the keyboard, this particular breakpoint will never be taken. That's because before continuing, we set the value at the address .CW "_startup" to zero, so whenever execution reaches .CW "keyboardread" in kproc number 7, it pushes the address .CW "_startup" , then pops it and pushes the word at that address. Since the top of the stack is zero, the breakpoint is ignored. .PP This contrived example may not be all that useful, but you can use a similar method in your driver to examine some state before making the decision to take the breakpoint. .SH Examining Registers .PP There are three commands to dump registers: .CW gpr() , .CW spr() and .CW "regs()" . The .CW "gpr()" function dumps the general purpose registers, .CW "spr()" dumps special purpose registers (such as the .CW "PC" and .CW "LINK " registers), and .CW "regs()" dumps both: .d0 .P1 acid: regs() PC 0x0004a3b0 sched+0x20 /home/tad/inf2.1/os/port/proc.c:82 LINK 0x0004b8e8 kchanio+0xa4 /home/tad/inf2.1/os/port/sysfile.c:75 SP 0x00453c4c R0 0x00458798 R1 0x000fdf9c R2 0x0003c804 R3 0x00000000 R4 0xffffffff R5 0x00000001 R6 0x00458798 R7 0x00000001 R8 0x001267f8 R9 0x00000000 R10 0x0044ee50 R11 0x00029f9c R12 0x000fc854 acid: .P2 .d1 .SH Complex Types .PP When reading in the symbol table, Acid treats all of the symbols in the executable as pointers to integers. This is fine for global integer variables, but it makes examining more complex types difficult. Luckily there is a solution. Acid allows you to create a description for more complex types, and a function which will automatically be called for these complex types. In fact, the compiler can automatically generate the acid code to describe these complex types. For example, if we wanted to print out the devtab structure for the keyboard driver, we can just give its name: .P1 acid: whatis keyboarddevtab integer variable format a complex Dev acid: keyboarddevtab dc 107 name 0x0010e0ea reset 0x0003c3fc init 0x0003c438 attach 0x0003c5dc clone 0x000480d0 walk 0x0003c600 stat 0x0003c640 open 0x0003c680 create 0x0004881c close 0x0003c768 read 0x0003c804 bread 0x0004883c write 0x0003c968 bwrite 0x00048900 remove 0x00048978 wstat 0x00048998 acid: .P2 Acid knows the keyboarddevtab variable is of type Dev, and it prints it by invoking the function Dev(keyboarddevtab). .P1 acid: whatis Dev complex Dev { 'D' 0 dc; 'X' 4 name; 'X' 8 reset; 'X' 12 init; 'X' 16 attach; 'X' 20 clone; 'X' 24 walk; 'X' 28 stat; 'X' 32 open; 'X' 36 create; 'X' 40 close; 'X' 44 read; 'X' 48 bread; 'X' 52 write; 'X' 56 bwrite; 'X' 60 remove; 'X' 64 wstat; }; .P3 defn Dev(addr) { complex Dev addr; print("\etdct",addr.dc,"\en"); print("\etnamet",addr.nameX,"\en"); print("\etresett",addr.resetX,"\en"); print("\etinitt",addr.initX,"\en"); print("\etattacht",addr.attachX,"\en"); print("\etclonet",addr.cloneX,"\en"); print("\etwalkt",addr.walkX,"\en"); print("\etstatt",addr.statX,"\en"); print("\etopent",addr.openX,"\en"); print("\etcreatet",addr.createX,"\en"); print("\etcloset",addr.closeX,"\en"); print("\etreadt",addr.readX,"\en"); print("\etbreadt",addr.breadX,"\en"); print("\etwritet",addr.writeX,"\en"); print("\etbwritet",addr.bwriteX,"\en"); print("\etremovet",addr.removeX,"\en"); print("\etwstatt",addr.wstatX,"\en"); } .P2 Notice the complex type definition and the function to print the type both have the same name. If we know that an address is the address of a complex type, even though acid may not (say we're storing multiple types of data in a void pointer), we can print the complex type by calling the type printing function ourselves. .P1 acid: print(fmt(keyboarddevtab, 'X')) 0x00106d50 acid: Dev(0x00106d50) dc 107 name 0x0010e0ea reset 0x0003c3fc init 0x0003c438 attach 0x0003c5dc clone 0x000480d0 walk 0x0003c600 stat 0x0003c640 open 0x0003c680 create 0x0004881c close 0x0003c768 read 0x0003c804 bread 0x0004883c write 0x0003c968 bwrite 0x00048900 remove 0x00048978 wstat 0x00048998 acid: .P2 .SH Conclusion .PP This introduction to using Acid for remote debugging Inferno kernels should be enough to get you started. As a tutorial, it only describes how to use some of the features of the debugger, and does not attempt to describe how to do advanced debugging such as writing your own functions, or modifying existing ones. Exploring the source, setting breakpoints, single stepping through code, and examining the contents of variables are the usual uses of a debugger. This tutorial gives examples of all of these. .PP For a more in depth discussion of the acid command language, and how to write your own acid functions, see the manual page .I acid (10.1) and Phil Winterbottom's papers on the Acid Debugger, reprinted in this volume. .TL Appendix .LP There are two important differences between Acid described in the accompanying paper, and Acid as distributed with Inferno for use in kernel debugging. .SH Connecting Acid to the remote Inferno kernel .PP A remote Plan 9 kernel can be debugged in the same way as a Plan 9 user process, using the file server .I rdbfs (4). It is a user-level file server on Plan 9 that uses a special debugging protocol on a serial connection to the remote kernel, but on the Plan 9 side serves a file system interface like that of .I proc (3), for use by Acid. Acid therefore does not need any special code to access the remote kernel's memory, or exert control over it. .PP Inferno's version of Acid currently runs under the host operating systems, which do not support such a mechanism (except for Plan 9). Instead, Acid itself provides a special debugging protocol, with (host) platform-specific interface code to access a serial port. This might well be addressed in future by implementing the native kernel debugger in Limbo. .SH Handling of breakpoints .PP .de Ip .KS .LP .tl '\f2\\$1\fP\ \ \f(CW\\$2(\f2\\$3\f(CW)\f1''\\$4' .IP .. .de Ex .KE .KS .IP .ft CW .ta 4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +4n .nf .in +4n .br .. .de Ee .fi .ft 1 .br .in -4n .KE .. The following functions are provided by the Acid library .CW $ROOT/lib/acid/$OBJTYPE for use in native kernel debugging. In several cases they change the behavior described in the Acid manual. The functions are: .P1 id = bpset(addr) id = bpcondset(pid, addr, list) bppush(val) bpderef() bpmask() bpeq() bpneq() bpand() bpor() bptab() addr = bpaddr(id) bpdel(id) bpconddel(id) .P2 .PP With traditional breakpoints, when a program reaches an address at which a breakpoint is set, execution is halted, and the debugger is notified. In applications programming, this type of breakpoint is sufficient because communicating the break in execution to the debugger is handled by the operating system. The traditional method of handling breakpoints breaks down when program being debugged is the kernel. A breakpoint cannot entirely suspend the execution of the kernel because there is no other program that can handle the communication to the debugger. .PP Some operating systems solve this problem by including a `mini' operating system, a self-contained program within the kernel that has its own code to handle the hardware used to communicate with the remote debugger or user. There are many problems with this mechanism. First, the debugger code that lives inside the kernel must duplicate a lot of code contained elsewhere in the kernel. This makes the kernel much bigger, and can increase maintenance costs. Typically this type of debug support treats the kernel as having a single thread of control, so a breakpoint stops everything while the user decides what to do about it. The only places in the kernel breakpoints cannot be set are in the debugger itself, and in the code that handles notifying the debugger of the breakpoint. .PP The Inferno kernel takes a different approach. The remote debug support is provided by a device driver that makes use of kernel services. Communication with the remote debugger is handled by a kernel process dedicated entirely to that task. All breakpoints can be considered to be minimally conditional on two values. First, the address to take the break at, and second, the kernel process to take the break in. This method allows the kernel debugger to be implemented as a regular Inferno device driver. The device driver can make use of all the APIs available to device drivers, it does not need to be self contained. Additionally, conditional breakpoints can be set anywhere in the kernel, with two exceptions. As with traditional debugger implementations, breakpoints can not be set in the code that handles notifying the debugger of the breakpoint. Unlike traditional implementations, the code that handles the execution and evaluation of the conditions applied to the breakpoint is the only other place breakpoint cannot be set. Since both of these parts of the kernel code are self contained, the user can set breakpoints in any other kernel routines. For example, the user could set a breakpoint in .CW kread() , for a given kernel process, but the debugger can still call .CW kread() itself. .PP Use of conditional breakpoints can help make the debugging process more efficient. If there is a bug that occurs in the Nth iteration of a loop, with unconditional breakpoints, user intervention is required N-1 times before reaching the state the bug occurs in. Conditional breakpoints give the user the ability to automatically check the value of N, and only take the breakpoint when it reaches the critical value. .PP The following changed and additional functions in the Acid library provide access to this extended breakpoint support: .SH Setting Breakpoints .LP .\" .\" .\" .Ip integer bpset integer "Set a breakpoint .CW bpset places an unconditional breakpoint for the currently selected kernel process at the address specified by its .I integer argument. It returns the ID of the newly created breakpoint, or the nil list on error. It is simply shorthand for a call .Ex bpcondset(pid, addr, {}) .Ee where .I pid is the global variable identifying the currently selected process, .I addr is the user-supplied address for the breakpoint, and .CW {} is the empty list, signifying no conditions. .Ip integer bpcondset "pid,addr,list" "Set conditional breakpoint Sets a conditional breakpoint at addr for the kernel process identified by .I pid . The .I list argument is a list of operations that are executed when execution reaches .I addr . If execution results in a a non-zero value on the top of the stack, the breakpoint is taken, otherwise it is skipped. The .I list is in reverse polish notation format, and has these operations: .Ex PUSH DEREF (pop val, push *(ulong*)val) MASK (pop mask, pop value, push value & mask) EQ (pop v1, pop v2, push v1 == v2) NEQ (pop v1, pop v2, push v1 != v2) AND (pop v1, pop v2, push v1 && v1) OR (pop v1, pop v2, push v1 || v2) .Ee Condition lists are executed in a single pass, starting with the first command in the list, ending with the last. If a nonzero value is on the top of the stack at the end of execution, the breakpoint is taken, otherwise it is skipped. .RS .LP In effect, there are two mandatory conditions, the address of the breakpoint, and the kernel process id. These two conditions must be met for the condition list to be processed. If these conditions are met, the entire condition list is processed, there is no short circuit evaluation path. .LP For example, given the following code fragment: .P1 +.4i int i; for(i=0; i<1000; i++) { ... } .P2 the following call to .CW bpcondset() sets a conditional breakpoint to be taken when execution reaches .I addr in kernel process .I pid on the 500th iteration of the loop: .P1 +.4i bpcondset(pid, addr, {bppush(i), bpderef(), bppush(500), bpeq()}); .P2 .RE .SH Condition List Construction .LP .Ip list bppush val "Construct breakpoint stack Push val onto the stack. .KE .Ip list bpderef "" "Construct breakpoint stack Replace the value at the top of the stack with the value found at the address obtained by treating value at the top of the stack as an address. Pop the value on the top of the stack, treat it as a ulong*, and push the value at the address. .Ex addr = pop(); push(*(ulong*)addr); .Ee .Ip list bpmask "" "Construct breakpoint stack Replace the top two values on the stack with the value obtained by masking the second value on the stack with the top of the stack. .Ex mask = pop(); value = pop(); push(value & mask); .Ee .Ip list bpeq "" "Construct breakpoint stack Comparison of the top two values on the stack. Replace the top two values on the stack with a 1 if the values are equal, or a zero if they are not. .Ex v1 = pop(); v2 = pop(); push(v1 == v2); .Ee .Ip list bpneq "" "Construct breakpoint stack Negative comparison of the top two values on the stack. Replace the top two values on the stack with a 0 if the values are equal, or 1 if they are not. .Ex v1 = pop(); v2 = pop(); push(v1 != v2); .Ee .Ip list bpand "" "Construct breakpoint stack Logical and of the top two values on the stack. Replace the top two values on the stack with a 0 if both are zero, or 1 if both are nonzero. .Ex v1 = pop(); v2 = pop(); push(v1 && v2); .Ee .Ip list bpor "" "Construct breakpoint stack Logical or of the top two values on the stack. Replace the top two values on the stack with a 1 if either is nonzero, 0 otherwise. .Ex v1 = pop(); v2 = pop(); push(v1 || v2); .Ee .SH Breakpoint Status .LP .Ip {} bptab "" "List active breakpoints Prints the list of breakpoints containing the following information in order: breakpoint number, kernel process id, breakpoint address, and the list of conditions to execute to determine if the breakpoint will be taken. .Ex acid: bptab() ID PID ADDR CONDITIONS 0 1 consread+0x20 0x216cc {} acid: .Ee .Ip integer bpaddr id "Address of breakpoint Returns the address the breakpoint identified by .I id is set to trigger on. .KE .SH Deleting breakpoints .Ip {} bpdel id "Delete breakpoint Delete the breakpoint identified by .I id . Shorthand for bpconddel(). .KE .Ip {} bpconddel id "Delete conditional breakpoint Delete the conditional breakpoint identified by the integer .I id . .KE