ikdb(8) (RM400 only) ikdb(8)
NAME
ikdb - internal kernel debugging facility
SYNOPSIS
cmd [parameters]
DESCRIPTION
ikdb is an optional facility than can be built (i.e. linked) into the
kernel and that runs in the kernel environment. During the initial
stages of bringing up a system, the debugger should be configured into
the kernel, so that it will be available to help diagnose system prob-
lems. Once the system is stable, you can deconfigure the debugger to
save space in the kernel.
To configure or remove the debugger, edit the file
/etc/conf/sdevice.d/ikdb:
ikdb Y 1 0 0 0 0 0 0 0
The second field (Y or N) is the configure parameter. If it is set to
Y, the debugger will be linked into the kernel. If the field is set to
N, the debugger is excluded from the kernel.
This configuration takes effect the next time you rebuild the kernel.
ikdb can be entered in several ways:
1. ikdb is called from several key points in kernel code:
a) as early as possible in the startup process. This can be enabled
by setting bootflags to 0x20.
b) during execution of an exec call immediately prior to entering
user code. This can be enabled/disabled by the on/off ikdb com-
mands.
c) from panic to allow for postmortem analysis. This can be dis-
abled by setting bootflags to 0x10.
2. ikdb can be entered asynchronously by pushing the debug button or
by typing CTRL-@ IKDB.
3. ikdb is entered as the result of encountering a breakpoint esta-
blished by ikdb.
ikdb maintains the notion of a "current process" and a "current
stack". On entry, the current process is that process on behalf of
which the system is now executing (i.e. the "owner" of the current
user structure). The current process can be changed to another process
by the ne or cp commands so that processes that are currently dormant
can be manipulated. The ne and cp commands (for multi-systems) also
change the current stack to that of the new current process.
Page 1 Reliant UNIX 5.44 Printed 11/98
ikdb(8) (RM400 only) ikdb(8)
ikdb commands have the following form:
command parameters
where command is a command (described below) and parameters are param-
eters or options to be applied to the command. If several parameters
are enclosed in square brackets ([ ]), they are optional, and zero or
more can be specified. If several parameters are enclosed in braces
({ }), exactly one must be specified. The output of most commands is
stopped every 20 lines to allow the operator the option of terminating
the command. The backspace key deletes the last character typed and
CTRL-U will delete the entire command line.
Numeric expressions
Numeric expressions use a syntax compatible with the C programming
language and consist of arbitrary combinations of numeric strings,
kernel variables and arithmetic operators (+ - * / < > & | ^ ~). The
arithmetic operators have the same meaning as they do in C. An addi-
tional operator (@) is available to specify the value found at a par-
ticular virtual address. Placing a numeric expression inside square
brackets ([expression]) has the same effect as the indirect operator *
in C.
Expressions are evaluated left to right with operator precedence as in
C. In addition, parentheses can be used to control the order of
evaluation. The indirect operator can be used with additional indirect
operators to achieve multiple levels of indirect accesses.
Numeric constants are evaluated as base 16 numbers unless preceded by
the prefix 0b for binary (base 2), 0 or 0o for octal (base 8), 0t for
decimal (base 10), or 0x for hex (base 16). The default base can also
be changed with the cb command.
Symbolic addressing
Global kernel symbols can be used in any numeric expression to specify
the address associated with the variable or procedure name. Kernel
symbols are denoted by prepending the underscore character () to the
symbol name.
COMMAND SYNTAX AND DESCRIPTION
Display/modify memory commands
da [{address | n | l} [count]]
dc [{address | n | l} [count]]
dh [{address | n | l} [count]]
dl [{address | n | l} [count]]
If count is negative, then memory is displayed backwards from
address.
Page 2 Reliant UNIX 5.44 Printed 11/98
ikdb(8) (RM400 only) ikdb(8)
ds [{address | n | l} [count]]
Display memory contents in ascii (da), as disassembled code (dc),
in hex (dh), as kernel symbols (dl), or as a string (ds). These
are simply aliases for the sm command.
ma [{-b | -h | -w}] [address [[value]]
put [{-b | -h | -w}] [address [[value]]
The modifying address command is used to change the contents of
the specified address. address is a numeric expression with the
result being used as the address (either memory or its location)
to be modified. The -b or -h or -l option specifies the typ of
the value as byte or half-word or word. If numeric expression
value is given, the result is written to address.
If no value is specified, an interactive address editor is
started. It is similar to that in mm command but the location
specified by address is not read.
ma and put are specially designed to execute the function of the
mm command on "memory-mapped-io" addresses.
mm [{address | n | l} [value]]
The modify memory command is used to change the contents of the
specified memory location. address is a numeric expression with
the result being used as the address of the memory location to be
modified. Specifying n or l for the address has the same meaning
as for the display commands. If numeric expression value is
given, the result is put into memory.
If no value is specified, an interactive memory editor is
started. The editor will display the specified address and the
contents of the memory location at that address. The value can be
changed simply by entering a new value. The editor will then
display the next address and contents of memory at that address.
To end the process, enter a dot (".") for the value. Entering a
dash ("-") for the value will decrement the address and continue
the editing process. The memory editor accepts only constants;
numeric expressions are not permitted.
sa [{-b | -h | -w}] [address]
get [{-b | -h | -w}] [address]
The show address command displays the contents of the specified
address as byte (-b), word (-w) or long (-l) value in hexade-
cimal.
sa and get are specially designed to execute the function of the
sm command on "memory-mapped-io" addresses.
Page 3 Reliant UNIX 5.44 Printed 11/98
ikdb(8) (RM400 only) ikdb(8)
sm [{-a | -i | -l | -s | -x}] [{address | n | l} [count]]
The show memory command displays the contents of memory in ascii
(-a), as disassembled instructions (-i), as kernel symbols (-l),
as a string (-s), or in hex (-x). Display starts at the address
specified by address and continues for count words. If address is
not specified, the address beyond the end of the last display
command is used. The start address can also be specified with
respect to the last display command (n or l). Using n indicates
that the next address should be used allowing the display to con-
tinue on from where the previous one left off. To reuse the pre-
vious start address, specify the address as l.
The default count of 4 is used if the parameter count is missing.
When formatting as a string, the display will terminate whenever
the count has been reached or a NULL character is encountered. A
non existent or zero count for strings will display memory until
a NULL is encountered.
un Undo the last modify memory command. A modification has a global
lifetime. Hence the previous mm command can have occurred in a
previous entry to ikdb. Also note that this will only undo the
last change of a sequence of modifications made in the memory
editor.
Display/modify context commands
cp cpu
The processor executing ikdb is changed to the new cpu. This also
has the side effect of changing the current (and original) pro-
cess to the one currently active on the new cpu. This function is
only available in the multikernel.
mtf {s | r}
By default, this command displays a stack trace. With the s
option, a stack trace is displayed for all sleeping processes.
With the r option, a stack trace is displayed for all running
processes.
ne [[p] process]
The debugger environment is changed to reflect the state of the
specified process. If no processes are given, ikdb reverts back
to its original context. process can be either the address of the
process table entry, or if the p option is specified, the process
ID of the new process.
np cpu
Run the debugger on cpu. This function is only available in the
multikernel.
Page 4 Reliant UNIX 5.44 Printed 11/98
ikdb(8) (RM400 only) ikdb(8)
regs [-a] [address] [reg[=val]]
The regs command displays the contents of the processor's regis-
ters. The -a option displays the contents before the last panic
or assertion failure. Supplying an optional address displays the
registers in the exception frame at that location. The entire
register set is displayed unless a specific register is desig-
nated by reg. If the numeric expression =val is specified, the
contents of the specified register are changed to val.
fregs
Display the floating point registers.
sf level
The sf command sets the registers and the state of ikdb to the
specified stack frame, making it look as though execution had
been interrupted at that point.
tf [levels] [sp pc]
This command displays a trace stack frames. For each frame on the
stack, the function name, instruction address, first four parame-
ters, and the stack frame address are printed. If levels is
specified, the trace only proceeds for the number of stack frames
specified rather than tracing back to the beginning of the stack.
The trace starts from the current top of stack unless the sp and
pc parameters are given.
Breakpoint and single step commands
bp [-a] address [count]
Set a breakpoint at the specified address. If address is at the
beginning of a function, the breakpoint is placed at the end of
the basic block instruction preamble generated by the compiler.
This can be overridden using the -a option. Execution of the ker-
nel stops and ikdb is restarted after the breakpoint is encoun-
tered count times. The count value defaults to 1.
B List all breakpoints currently set.
d index
Delete the breakpoint specified by index, where index is the
index associated with the breakpoint as shown in the list of
breakpoints (see the B command).
D Delete all breakpoints currently set.
so [count]
Similar to the st command except that function calls are executed
as a single step.
st [count]
Execute count (defaults to 1) machine instructions.
Page 5 Reliant UNIX 5.44 Printed 11/98
ikdb(8) (RM400 only) ikdb(8)
w [-rw] [-p pattern] [-m mask] [address]
Without parameters this command shows the watchpoint currently
set. With the -rw option a watchpoint can be specified at address
for reading (-r), writing (-w) or both. Address must be from
K0SEG to K1SEG.
The watchpoint is pattern sensitive for each bit which is set to
1 by the -m option. It is then compared to the appropriate bit in
the pattern specified by the -p option.
W Delete watchpoint currently set.
Process display/control commands
fp {p | c | w | s} regexp
Find and list all processes that match a specific selection cri-
terion. Exactly one flag must be given to indicate the field for
the search: process ID (p), command (c), wait channel (w), or
process state (s). regexp is a regular expression used to compare
against the given field. For example:
fp c ^get
Would find and list all processes executing commands with names
beginning with "get".
ki [-s] [-sig] [pid]
Send a signal to a process. If specified, sig specifies the signal
to send; 9 is the default. pid indicates the process to signal. If
pid is missing, then all processes except system processes are sig-
naled. System processes cannot be killed unless the -s option is
specified and the process ID is stated explicitly.
lp The lp command lists all the processes active in the system and
gives a short status description. The processes that are
currently running on a CPU are highlighted.
wa wchan
Perform the Reliant UNIX wakeup call on the specified wait chan-
nel. wchan must be specified; there are no defaults.
Data structure display commands
This group of commands prints the contents of data structures. For
most of these commands, the structure can be specified by the follow-
ing arguments:
{address | offset}
If address is given, the command prints the name of each member of the
structure (truncated to 8 characters), and the member's value, as in
the following example for percpu:
Page 6 Reliant UNIX 5.44 Printed 11/98
ikdb(8) (RM400 only) ikdb(8)
ikdb > percpu c0030000
c0030000:
xclbind 0 idleproc c03aa400 lcpunum 1 lcpumask 2
percpufl 7 runrun 1 kprunrun 0 curpri 4f
npwakecn 0 dosoftin 1 dotimein 0 dqgen 1
migrate 0 intrcxt 100 locktestoff 0 lastlock ff
locklist [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
idleflag 0 backoff 5 idleadj 0 baseprio 0
fpproc 0 curproc c0739c00 oldcurp c03aa400 tlbpida 29
tlbpidg ca curipl 0 maxqueip 0 iplquema e0118000
iplfree c00479ec iplbase c0004000 unix-tic 1 fasttod 0
fastoff 0 Izero 0 itmrckp 0 rtodckp 0
todhid 0 clkspee 0 delaymu 708 icaches 0
dcaches 0
If offset is specified, the printout specifies the full name of each
structure member, its offset from the beginning of the structure in
bytes, and its size in bytes. The following is an example of the
percpu command:
ikdb > percpu offset
member(offset,size)
xclbind(0,4) idleproc(4,4) lcpunum(8,1) lcpumask(c,4)
percpuflags(10,4) runrun(20,4) kprunrun(24,4) curpri(28,4)
npwakecnt(2c,4) dosoftint(30,4) dotimein(34,4) dqgen(38,4)
migratefrom(3c,4) intrcxt(60,2) locktestoff(62,1) lastlock(63,1)
locklist(64,7c) idleflag(e0,4) backoff(e4,4) idleadj(f0,4)
tlbpidassigned(12c,4) tlbpidgen(130,4) curipl(134,4) maxqueipl(138,4)
iplquemask(13c,4) iplfree(140,4) iplbase(144,4) unixtick(180,4)
fasttodlo(184,4) ticktodhi(188,4) ticktodlo(184,4) showtodhi(190,4)
showtodlo(194,4) fastoffset(198,4) Izero(190,4) itmrckptcnt(1a0,4)
rtodckptcnt(1a4,4) todhidiff(1a8,4) clkspeed(1a4,1) delaymult(1b0,4)
icachesize(1b4,4) dcachesize(1b8,4)
as {address | offset}
Displays the contents of a particular as structure.
buf {address | offset}
Displays the contents of a particular buf structure.
cg {address | offset}
Displays the contents of a particular cg structure.
datab {address | offset}
Displays the contents of a particular datab structure.
fifonode {address | offset}
Displays the contents of a particular fifonode structure.
hat {address | offset}
Displays the contents of a particular hat structure.
Page 7 Reliant UNIX 5.44 Printed 11/98
ikdb(8) (RM400 only) ikdb(8)
hatdata {address | offset}
Displays the contents of a particular hatdata structure.
inode {address | offset}
Displays the contents of a particular inode structure.
inpcb {address | offset}
Displays the contents of a particular inpcb structure.
msgb {address | offset}
Displays the contents of a particular msgb structure.
page {address | offset}
Displays the contents of a particular page structure.
percpu {{lcpu | address} | offset}
Displays the contents of the percpu structure for a particular
processor. The processor is specified by either its logical CPU
number (lcpu) or the address of its percpu structure (address).
If offset is given, then the offset of each member into the
structure is printed as described above.
If no arguments are given, this command prints the values for the
current active CPU's percpu structure (note the active lcpu
number in the prompt) with the structure member names truncated
to 8 characters.
pp {{pid | address} | offset}
Displays the contents (in logical order) of the proc structure
for a particular process. The process is specified by either its
process ID (pid) or the address of its process table entry
(address).
ppa {{pid | address} | offset}
Displays the contents (in alphabetical order) of the proc struc-
ture for a particular process. The process is specified by either
its process ID (pid) or the address of its process table entry
(address). If offset is specified, then the offset into the
structure of each field is printed.
queue {address | offset}
Displays the contents of a particular queue structure.
seg {address | offset}
Displays the contents of a particular seg structure.
snode {address | offset}
Displays the contents of a particular snode structure.
stream {address | offset}
Displays the contents of a particular stream structure.
Page 8 Reliant UNIX 5.44 Printed 11/98
ikdb(8) (RM400 only) ikdb(8)
tcpcb {address | offset}
Displays the contents of a particular tcpcb structure.
var [offset]
Displays the contents of the var structure (v).
vnode {address | offset}
Displays the contents of a particular vnode structure.
Virtual memory translation commands
pt address
Display the translation information associated with the given
virtual address. This includes the physical address, and protec-
tion flags from both the kernel's data structures and the
hardware TLB (Translation Lookaside Buffer).
td [-c] [index ...]
Display the contents of the TLB. When ikdb is started, the con-
tents of the TLB are saved and used for this command. To use the
current contents of the TLB, specify the -c option. To dump
specific TLB locations, specify the indices of the locations to
be dumped.
vtop proc vaddr
Display the steps of the virtual to physical address translation
for address pair proc vaddr.
Miscellaneous commands
call func ([parameter [,parameter] ...])
Call a particular kernel function with the specified parameters.
Up to six parameters can be passed and all must be numeric
expressions. String constants are not allowed. The return value
from the function is printed.
cb newbase
Change the default base used by the expression evaluator for
interpreting numeric constants to newbase. (Be sure to express
newbase in the current base.)
echo [parameter ...]
Print the parameters specified on the command line.
ex or q
Exit the debugger and continue execution of the kernel from the
point where the debugger was invoked.
lck Display all the locks currently being held by each cpu.
Page 9 Reliant UNIX 5.44 Printed 11/98
ikdb(8) (RM400 only) ikdb(8)
ll1 [start] link value offset, offset ...
Display a linked list starting from the address given in start;
link indicates the offset to the pointer to the next node; value
indicates the terminating value for the linked list. Up to five
fields can be displayed for each node and offset lists the offset
value from the start address.
ll2 [start] link value lowbound highbound
List a linked list starting from address given in start. link
indicates the offset to the pointer to the next node. value indi-
cates the terminating value for the linked list. If lowbound and
highbound are specified, then bounds checking is carried out for
each node.
more [value]
Set the debug "more" facility to value. If value is zero, then
"more" is turned off. Otherwise, value indicates the number of
lines in a page.
na {symbol | address}
Print the numeric and symbolic values associated with the numeric
expression on the command line.
pa Force the system to panic after exiting ikdb.
S {symbol | address}
Print the numeric and symbolic values associated with the numeric
expression on the command line.
set [flag {on | off}]
Turn on or off a specific internal ikdb flag. If no parameters
are given, then the list of available flags is printed.
val number
Display the value of the numeric expression number in hex,
decimal, unsigned decimal, and octal.
? Print the list of commands understood by the debugger along with
a few character descriptions.
DIAGNOSTICS
The self-explanatory diagnostics indicate errors in the command line
or problems encountered when executing the commands.
Page 10 Reliant UNIX 5.44 Printed 11/98