symmon(1M)symmon(1M)NAMEsymmon - kernel symbolic debugger
DESCRIPTIONsymmon 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
Page 1
symmon(1M)symmon(1M)
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:
o base for a single location
o base#count for count locations starting at base
o 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
Page 2
symmon(1M)symmon(1M)
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.
Page 3
symmon(1M)symmon(1M)
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.
Page 4
symmon(1M)symmon(1M)
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.
Page 5
symmon(1M)symmon(1M)SEE ALSOprom(1M).
Page 6
