symmon(1M) symmon(1M) NAME symmon - kernel symbolic debugger DESCRIPTION symmon is a standalone program used to debug the kernel. It is intended to be used only by those involved in writing and debugging device drivers or other parts of the kernel. The implementation of symmon is machine dependent and the commands and functionality described here may not apply to all systems. To use symmon, several steps must be taken to prepare the system: 1. symmon must be manually installed by the user, because it is not installed on the system as shipped from the factory. This can be done by installing the ``Debugging Kernels'' subsystem in the IDO software development option. 2. Alterations must be done to the file /var/sysgen/system/irix.sm to build a kernel capable of being debugged; see the comments in that file for details. 3. The program setsym(1M) needs to be run on the newly generated kernel to allow symmon to recognize symbols in it. 4. symmon needs to be installed in the volume header of the root drive with dvhtool(1M). This normally happens as part of the software installation process. symmon is typically used with a terminal as the system console (see prom(1M) for information on how to enable a terminal as the console). When a debug kernel is booted, it automatically tries to load symmon from the same source. symmon can be booted from an alternate device by setting the dbgname environment variable in the prom. For example: setenv dbgname scsi(1)disk(1)rdisk(0)partition(8)symmon loads symmon from a disk 1, connected to SCSI controller 1. Once symmon is loaded, the system operates normally until symmon is triggered by the keyboard or an exceptional condition happens in the kernel that causes it to enter the debugger automatically. To enter symmon from the keyboard, type a <Ctrl-a>. symmon prompts with DBG: and accepts commands described below. Built-in Commands symmon has a set of basic commands for setting and clearing breakpoints and examining system state. Not all of the commands listed below are supported on all systems. Some commands take memory addresses as arguments. Addresses can be given directly in decimal, in hex if preceded by 0x, in binary if preceded with 0b, as names of functions or data, as names of registers if preceded by $, or as a combination of those with + and -. Some commands take a range of addresses specified as either ADDR:ADDR for an inclusive range or ADDR#COUNT for a count of COUNT starting at ADDR. Commands are listed below: brk [ADDR] Set a breakpoint at the given address. If no arguments are given, the set of current breakpoints is listed. bt [MAX_FRM] Print a stack back trace of up to MAX_FRM frames. See the discussion about ubt below for an alternate form of stack back trace. c Continue execution from a breakpoint. cacheflush [RANGE] Flush both the instruction and data caches over the range of address given. calc call ADDR [ARGLIST] Set up a stack frame and call the procedure at the specified address. clear Clear the screen. dis [RANGE] Disassemble instructions in memory over the range specified. dump [-b|-h|-w|-d] [-o|-t|-x|-c] RANGE Dump the contents of memory. The -b, -h, -w and -d flags can be used to specify byte, halfword, word or double word data. The -o, -t, -x, and -c flags can be used to specify octal, decimal, hexadecimal, or ASCII data formats. The specified range of memory to dump can take these forms: + base for a single location + base#count for count locations starting at base + base:limit for locations whose addresses are greater than or equal to base but less than limit g [-b|-h|-w] [ADDR|$regname] Get and display the contents of memory at the address given. If a register name is given, its contents are displayed at the time the kernel was stopped. goto ADDR Continue execution until the given address or a breakpoint is reached. This is a short hand way to set a breakpoint at an address, continue, and then remove that breakpoint. help List a short summary of the built-in commands. hx NAME The symbol table is searched for entries matching NAME, and if one is found, its value is printed. kp [KPNAME] Kernel print command. If no arguments are given, a list of the available kernel print commands is given. If a name is given, that print function is executed. See the discussion on kernel print commands below for more information. lkaddr ADDR The given address is matched against the symbol table and the symbols near it are listed. lkup STRING The given string is matched against the symbol table and any symbol with an equal or longer name is printed. This is convenient when you cannot remember the precise symbol name. msyms ID Print dynamically loaded kernel module's symbols. The module id is found using either the lboot -V command or the ml list command. See the mload(4) manual page for more information. nm ADDR The address given is matched against the symbol table and if an exact match is found, the symbolic name is printed. This is a more restrictive version of the lkaddr command described above. p [-b|-h|-w] ADDR VALUE Put the value given into the address given. This causes a write to memory. printregs List the contents of the general purpose registers when the kernel was stopped. quit Restart the PROM. s [COUNT] Single step the kernel for either one instruction or the given count. If the current instruction is a branch, then both it and the following instruction are executed. The next unexecuted instruction is disassembled when the command completes. After a step command is issued, symmon enters a command repeat mode where a null command causes another step to be taken. This repeat mode is indicated by a change to the prompt. S [COUNT] Same as the step command above, except that jump-and-link instructions are stepped over. tlbdump [RANGE] List the contents of the translation lookaside buffer. If specified, the range of TLB entries given is listed. The range should specify a subset of the 64 TLB slots. tlbflush [RANGE] Flush the TLB over the range of entries given or the entire TLB if no range is specified. tlbmap [-i INDEX] [-n|-d|-g|-v] VADDR PADDR Inserts an entry in the TLB that maps the virtual address given by VADDR to the physical address given by PADDR. If specified, the TLB slot given by INDEX is used. The -n, -d, -g, and -v flags can be used to turn on the non-cached, dirty, global, and valid bits. The current TLB context number is used. tlbpid [PID] Get or set the current TLB context number. If no argument is given, the current TLB context number is returned; otherwise, the context number is set to the argument. tlbptov PADDR Display TLB entries that map a virtual address to the physical address given. tlbvtop VADDR [PID] Find the physical address mapped to the virtual address given by VADDR. If PID is given, then it is used as the TLB context number in the match; otherwise, the current TLB context number is used. unbrk [BPNUM] Remove the breakpoint with the breakpoint number given. The breakpoint number can by determined by listing the set breakpoints with the brk command. wpt [r|w|rw] [0|PADDR] Set a read, write or read/write watch point at on physical address using the R4000 watch point registers. The address must be double word aligned, and the watch point trips on any access within the next eight bytes. An argument of 0 clears the watch point. Note that the R4000 only supports one watch point at a time. [ADDR]/[COUNT][d|D|o|O|x|X|XX|b|s|c|i] Dump the contents of memory at the given address. This command functions in a similar manner as the dbx(1) command of the same syntax. The XX is a symmon specific extension to printing hexadecimal double words. Kernel Print Commands The kernel extends the set of built-in symmon commands with kernel print commands. These commands dump various kernel data structures. proc PROCINDEX Dump the process structure associated with the given process table index. Note that the process table index is not the same as the IRIX process ID. user PROCINDEX Dump the contents of the user structure for the process with the process table index given. buf BUFNUM Dump the contents of a buffer structure. The address of the buffer to be dumped is controlled by the BUFNUM argument. If BUFNUM is a valid K0, K1, or K2 address, then the buffer at that address is displayed. If BUFNUM is a small integer, it is used as an index into the buffer table. If BUFNUM is equal to -1, summary information about the buffer pool is displayed. qbuf DEVICE Dump the contents of buffers queued for the device given. The device argument is given as the major/minor device number of the desired device. pda [CPUID] Dump the contents of the processor private data area for the processor ID given. runq Dump the run queue. A short summary of each process waiting for CPU time is listed. eframe [ADDR] The exception frame at the given address is displayed. If the address is a small integer, the exception frame of the process with that process table index is used. The exception frame holds the contents of the general purpose registers at the time the process last executed. ubt [PROCINDEX] User process stack back trace. A stack back trace is listed for the process whose process table index is given. plist Process table list. This gives an output similar to ps(1) and can be used to find the process table index number for a process. pb Dump console print buffer. The contents of the console print buffer are printed. This can be useful when an important message has scrolled off the screen. SEE ALSO prom(1M). Page 6