ekdb(1M)
ekdb --
enhanced kernel debugger
Description
The enhanced kernel debugger is a simple debugger that resides
in the UNIX kernel and enables you to:
-
examine and modify memory
-
disassemble instructions
-
download and execute programs
-
set breakpoints and single-step instructions.
It can perform any of these tasks on any on-line processors.
You can configure the enhanced kernel
debugger as part of the kernel load file
(/unix), or you can use the
modadmin(1M)
command to load it while the system is running. After loading the debugger,
use <Ctrl>-<Alt>-D on the console or <Ctrl>-B on serial terminals to start it.
NOTE:
There is a second kernel debugger called
kdb(1M)
which you can also use. However, if your system contains 4GB or more of memory,
you may find it more useful to use ekdb as it uses the same interface as
kcrash(1M)
which you must use for large memory machines.
Multiprocessor support
The enhanced kernel debugger allows each processor independently
to be either ``in the debugger'' or ``running''
at any time. Processors in the debugger are in one of two modes:
NOTE:
If your system is a uni-processor system, you will only have one processor, which
is always in master mode, and always has a cpuid of ``0''. Ignore all references and
commands related to multiprocessor systems described in this manual page.
At most one processor is in master mode at any time, although master mode
may be transferred among the processors with a debugger command described
below. When any processor enters the debugger from a state in which all
processors are running, that processor becomes the master and forces all the
other processors to become slaves, thereby suspending execution over the
entire multiprocessor system. All the commands described below execute on
the current master processor unless otherwise noted. Slave processors do
nothing until instructed by the master as a result of a debugger command.
The console device is physically attached to only one processor in the
multiprocessor system; that processor is termed the
``console processor''.
All debugger I/O is routed through the console processor, no matter which
processor is master. Because the debugger allows independent control over
processors, it is possible to detach the console processor from the
master processor, which results in the loss of interaction between the
debugger and the user (for example, by resuming execution on the console
processor via the gos
command when it is in slave mode). The debugger prints a warning about this
condition when it detects it. The two ways for the console processor to
resume performing console I/O to the debugger are either for it to
voluntarily enter the debugger (by hitting a breakpoint or otherwise
trapping into the debugger), or, failing that, for the user to type the
debugger keystroke, <Ctrl>-<Alt>-D, on the console. Either of these will
force the console processor back into slave mode, and back into performing
console I/O on behalf of the current master processor.
Commands
All debugger commands are brief mnemonics (usually two characters)
followed by zero or more arguments.
In the following descriptions,
optional arguments are enclosed in square brackets.
Arguments are separated by spaces or commas, and
each argument must be one of the following:
-
A number in the current input radix (default hexadecimal), or in a different
radix as specified by a prefix: 0x for hex, 0t for decimal,
0o for octal, or 0b for binary.
-
A percent sign followed by a register name,
meaning the contents of that register,
such as %eax, %esp, %eflags.
Only 32-bit registers are allowed;
8- or 16-bit registers are invalid.
-
A percent sign followed by
b
and an instruction breakpoint number,
meaning the address referred to by that breakpoint,
such as %bx .
-
A dollar sign,
meaning the address of the last memory location that was displayed.
-
The name of a kernel symbol. A hash ``#'' prefix to a name
forces the interpretation as a
symbol, and not a hex number. (Without this, the name ``add'' for example
would always be interpreted as 0xADD.)
-
The name of a user-defined debugger variable.
-
Any of the above combined by using the usual arithmetic operators
(+ - * /
& | ^), the relational operators used as used in
the C programming language (== != <>
<= >=), or the C language
pointer-dereference operator (*).
Two special operators perform instruction arithmetic:
A @- B backs up B
instructions from address A;
A @+ B advances B
instructions from address A;
where A and B are expressions.
All operators have equal precedence.
Use parentheses
to force a particular order of evaluation.
Division by zero yields zero.
-
A string surrounded by single quotes `' or double quotes ``''.
The C escape for the newline character ``\n'' may be used in the string.
-
A percent sign followed by
s
and an expression, meaning the null-terminated
character string starting at that memory address.
-
A percent sign followed by
p
and an expression, meaning the physical memory address corresponding to that
virtual address.
-
A percent sign followed by
v
and an expression, to test that virtual address' validity. If the virtual
address is valid, this operation evaluates to ``1'', otherwise to ``0''.
-
Any numeric expression preceded by ``~'', meaning the ones-complement of
the number.
Input Commands
The enhanced kernel debugger prompts with
K
n,
where n is the processor identification number
(cpuid )
of the current master processor, in hex. This prompt indicates that the
debugger is ready to accept any of the commands described below. Input
characters can be erased with
<Bksp>
or <Del>. An entire input line can be erased with <Ctrl>-U or
<Ctrl>-X. In addition, the debugger supports flow control (<Ctrl>-S,
<Ctrl>-Q) and keyboard interrupt (<Ctrl>-C).
NOTE:
If your system is a uni-processor system, you will only have one processor, which
is always in master mode, and always has a cpuid of ``0''.
Before each time the debugger issues a prompt, it checks the state of each
processor and notifies the user of those processors that have entered slave
mode since the last check. In this way, the user is kept informed of the
activities on all the processors.
After a breakpoint or debug trap,
the debugger prints a status line describing the trap,
immediately followed by the ``K'' prompt,
and is again ready to accept commands.
In the case of a trace trap,
the debugger automatically supplies the expected command,
tr.
If you want to enter a different command,
erase the
tr
and enter a new command.
During any of the display,
modify,
examine or write commands,
you can enter one of the following:
- <Return>
-
Moves to the next item.
- +n
-
Moves to the
n th next item.
- -
-
Moves to the previous item.
- -n
-
Moves to the
n th previous item.
- =addr
-
Moves to the item at address
addr. Only valid when operating on memory,
not on registers.
- n
-
Changes the value of the item to n.
Only valid for modify or write commands,
not display or examine.
The mi
command allows you to enter multiple numbers separated by spaces,
to change more than one byte.
- .
-
(Or any character other than + - = or a hex number.)
Exits the command and returns to the debugger prompt.
If ever an attempt is made to access an invalid virtual address, the command
and all levels of invoked macros will be aborted and the debugger will
prompt for the next command.
Display Commands
These commands allow you to examine memory only.
This prevents accidental modification of system memory
when in the debugger.
- dl addr [ count]
-
Displays memory starting from address addr as longs (4 byte hex integers),
32 bytes at a time.
If a
count is given, memory is displayed
32 * count bytes at a time.
- dw addr [ count ]
-
Displays memory starting from address addr as words (2 byte hex integers),
32 bytes at a time.
- db addr [ count ]
-
Displays memory starting from address addr as bytes (1 byte hex integers),
32 bytes at a time.
- di [ addr ]
-
Displays memory as disassembled instructions.
The default addr is the contents of %eip.
- dr [ addr ]
-
Displays the CPU
general registers stored at addr.
The default addr
is the automatically-determined register save area (see the
rg command).
- dR
-
Displays the CPU ``special'' registers (debug,
control, and table base registers).
- dy addr [ count ]
-
Similar to dl, but displays the longs in symbolic form,
if possible.
- se start end pattern [ mask ]
-
Searches for the given pattern in the range of addresses starting at
start, up to (but not including) end.
The search is performed on longs. If a mask
is specified,
only those bits corresponding to 1 bits in the mask
are significant in the search.
Examine Commands
- el addr
-
Examines memory as longs,
one at a time.
- ew addr
-
Examines memory as words,
one at a time.
- eb addr
-
Examines memory as bytes,
one at a time.
- ei [ addr ]
-
Examines memory as disassembled instructions.
(Same as di.)
- er
-
Examines CPU general registers,
one at a time.
- eR
-
Examines the CPU special registers,
one at a time.
Modify Commands
- ml addr
-
Examines and optionally modifies memory,
as longs.
- mw addr
-
Examines and optionally modifies memory,
as words.
- mb addr
-
Examines and optionally modifies memory,
as bytes.
- mi [ addr ]
-
Examines memory as instructions and optionally modifies (as bytes).
- mr
-
Examines and optionally modifies the CPU
registers.
- mR
-
Examines and optionally modifies the CPU
special registers.
Write Commands
- wl addr
-
Writes memory as longs,
without examining.
- ww addr
-
Writes memory as words,
without examining.
- wb addr
-
Writes memory as bytes,
without examining.
I/O Commands
- in addr
-
- ib addr
-
Reads a byte from the specified
I/O port.
- iw addr
-
Reads a word (2 bytes) from the specified
I/O port.
- il addr
-
Reads a longword (4 bytes) from the specified
I/O port.
- ou addr value
-
- ob addr value
-
Outputs a byte value to the specified
I/O port.
- ow addr value
-
Outputs a word value to the specified
I/O port.
- ol addr value
-
Outputs a longword value to the specified
I/O port.
Execute Commands
- go [ addr ]
-
Resumes execution on all processors. If an
addr is given, the master processor
resumes execution at addr.
- gor [ addr ]
-
Resumes real-mode execution on the master processor, and normal execution on
all other processors. If an addr
is given, the master processor resumes execution at
addr.
- gos [ cpuid ... ]
-
Resumes execution on only the processors whose
cpuid's are listed. If no cpuid's
are given, it resumes execution on only the current master processor.
- tr [ addr ]
-
Trace:
single step one instruction on the master processor. If an
addr is given, the master processor resumes execution at
addr.
- trs [ cpuid ]
-
Trace (single step) on the slave processor identified by
cpuid,
or on the master processor if
cpuid is omitted.
- to [ addr ]
-
Trace over:
single step over ``call'' instructions on the master processor. If an
addr is given, the master processor resumes execution at
addr.
- tos [ cpuid ]
-
Trace (single step) over ``call'' instructions on the slave processor
identified by cpuid, or on the master processor if
cpuid is omitted.
- stop [ cpuid ... ]
-
Suspend execution on the running processors whose
cpuid's are listed, and force them into slave mode. If no
cpuid's are given, it suspends every currently running processor.
- call addr [ args ... ]
-
Call a function with the specified arguments and show the return value.
Multiprocessor commands
These commands, together with the execution commands above that start and
stop processors, comprise the complete multiprocessor command set.
NOTE:
If your system is a uni-processor system ignore all references and
commands related to multiprocessor systems described below.
- cpu cpuid
-
Switch master mode from the current master processor to the slave processor
identified by cpuid. The current master processor becomes a slave,
and the designated slave
becomes the new master.
- ss [ cpuid ]
-
Show the multiprocessor debugger status of the processor identified by
cpuid, or of all processors if cpuid
is omitted.
Instruction breakpoint commands
An instruction breakpoint invokes the debugger just prior to the execution
of a specified instruction.
There are a total of sixteen instruction breakpoints available.
Instruction breakpoints affect all processors; that is, every processor that
hits an instruction breakpoint will enter the debugger. Chip breakpoints
(see below) affect only the processor on which the breakpoint was set.
- br [ addr ]
-
Sets an instruction breakpoint.
The default address is the contents of
%eip.
- bc [ addr ]
-
Clears (removes) an instruction breakpoint.
- bC
-
Clears (removes) all instruction breakpoints.
- bx [ addr ]
-
Sets a temporary (one-shot) instruction breakpoint.
- bo [ addr ]
-
Turns an instruction breakpoint on or off.
If a breakpoint is turned off,
it acts as though it were cleared,
but the breakpoint remains in the breakpoint table.
- bp
-
Displays instruction breakpoints.
Chip breakpoint commands
A chip breakpoint invokes the debugger when a specified
memory location is referenced.
There are a total of four chip breakpoints available.
Chip breakpoints affect only the processor on which the breakpoint was
set. Instruction breakpoints (see above) affect all processors.
- ur num type [ addr ]
-
Sets a chip breakpoint.
Num must be 0 to 3,
addr is the breakpoint address,
and type
gives the type of memory access that will trigger the breakpoint.
Valid memory access types are:
- 0
-
Execute
- 10
-
Byte write
- 11
-
Byte read/write
- 20
-
Word write
- 21
-
Word read/write
- 40
-
Long write
- 41
-
Long read/write
NOTE:
The first digit specifies the breakpoint length
and the second specifies the access type (write-only or read/write).
The breakpoint is global unless the type is ORed with 100,
which makes it local;
or with 200,
which makes it global and local.
For example,
140 specifies a local long write-only breakpoint.
- uc num
-
Clears a chip breakpoint.
- uC
-
Clears all chip breakpoints.
- ux num type [ addr ]
-
Like ur, but sets a temporary (one-shot) breakpoint.
- up
-
Prints all chip breakpoints.
Miscellaneous commands
- bt [ addr ]
-
Displays a stack backtrace,
using addr as a frame pointer.
The default address is the contents of
%ebp.
This works only with C language routines in protected mode.
- fill start end value
-
Fills memory from address
start up to (but not including) address
end with the byte value.
- pf "string" [ args ... ]
-
- printf "string" [ args ... ]
-
Prints the string.
Percent signs in the string are treated as in
fprintf(3S):
%d, %u, %x, %o, %b,
%s, %c are supported.
In addition, %y prints its argument in symbolic form, if possible,
and %I prints its argument in disassembled instruction form.
- rg [ addr ]
-
Changes the pointer to the ``register save area'', from which
all references to CPU registers retrieve registers.
Normally, the register save area is set up automatically, but you can
use a different set of registers when you use rg to change the
pointer. To restore the pointer to its original value, use an
addr of zero. If addr
is missing, it displays the current register save area pointer.
- pg [ n ]
-
If n is 0, turns paging off.
If n is 1, turns paging on.
If n is missing,
it simply reports whether paging is on or off.
If paging is off,
the debugger interprets all addresses as physical addresses.
If paging is on,
addresses are interpreted as linear (virtual) addresses.
(Breakpoints are always linear addresses.)
- real [ n ]
-
If n is 0, turns real-mode off.
If n is 1, turns real-mode on.
If n is missing, it simply reports whether real-mode is on or off.
If real-mode is off, the debugger traces in protected mode.
If real-mode is on, the debugger traces in real mode.
- ma addr
-
- map addr
-
Displays the page directory and page table entries used to map
the given linear address to a physical address.
This behaves the same whether paging is on or off.
- c3 [ addr ]
-
Uses the specified physical address as the base of the page directory
for translating linear-to-physical addresses.
This address is obtained from the special register
CR3 if no c3 command is given. To restore the
base to that original value, use an addr
of zero. If addr is missing, it displays the current
page directory base.
- sp [ addr ]
-
addr
must be the address of a kernel
proc structure.
The debugger uses the context
of that process to translate linear-to-physical
addresses.
Use of the sp command overrides the
CR3 register: after an sp command,
c3 commands have no effect.
- radix [ n ]
-
Set the input radix to n.
If n is omitted, it displays the current input radix.
The default radix is hexadecimal.
- pr addr [ radix ]
-
Prints the value of the address given as an argument in the specified radix,
or in the current input radix if
radix is missing. This is most useful if addr
is an expression (see the earlier discussion of arguments).
- printbits "bit-desc" word
-
Display the bits that are set (the 1 bits) in
word symbolically according to
bit-desc, which is a colon-separated list of names associated with the
corresponding bit positions, starting with bit 0 (the least significant bit).
For example the following command,
printbits "X:Y:Z:FOO:BAR" 0x9D
prints
X Z FOO BAR
- ds addr
-
Prints the value of the address as an offset from the nearest symbol.
- sy [ n ] [ max ]
-
If n is 0, turns symbolic display off.
If n is 1, turns symbolic display on.
If n is missing, it simply reports whether symbolic
display is on or off. If max is given,
it specifies the maximum offset for printing symbols.
For example, if max is 1000,
a symbol may be displayed in the form
name+NNN, where
NNN is 1 through 1000,
but if NNN
would be greater than 1000,
the non-symbolic display format is used.
- more [ lines ]
-
Sets the number of display lines to lines.
If lines is greater than zero, it enables output paging. When
lines
or more contiguous lines of information are printed without asking the user
for input, the message
--press space for more--
is displayed and
output is temporarily suspended until the user presses the space bar. This
prevents the debugger from printing too many lines of output at once on
video terminals. If lines is zero, it disables output paging.
Output paging is disabled by default.
If lines
is missing, it reports whether output paging is enabled or disabled.
- pause
-
Pause until the user types something.
- he or help or ? or ??
-
Lists the debugger commands.
- ve
-
Prints the version number of the debugger.
- # or ## or no
-
No-op. Input lines beginning with # are treated as comments and ignored.
Debugger variable commands
These commands manipulate variables that the user defines. User-defined
debugger variables may be used in expressions just like kernel symbols.
- set var value
-
Set the variable named by var
to have the given value.
If the variable var
has not previously been defined, it becomes defined; if it was previously
defined, its old value is lost.
- read var
-
Read an expression from the user and set the named debugger variable to the
expression's value.
Macro Commands
- define "name" [arg-desc][maxsize]
-
Defines a MACRO, with the given name and the specified argument
description string. The optional maxsize argument specifies the
maximum size (in bytes) of the macro; the default size is 4096 bytes. The
macro can be invoked after its definition by simply typing its name like any
other command. The arg-desc
string describes to the debugger what arguments the macro expects: Each
lower-case letter specifies the type of the corresponding argument, as
follows:
- a or i
-
address or integer, the result of an arbitrary expression
- s
-
string
- ?
-
means the following arguments are optional
- *
-
means any number of arguments or any type
- .
-
means do not parse more arguments
- ,
-
is ignored.
For example, the argument description for the
se command is ``aai?i'', and for
pf it is ``s*''. If arg-desc
is missing, the macro will be defined as requiring no arguments.
After you enter the dm command, the debugger prompts with
``mac>'' for the body of the macro.
Any debugger commands can be entered as the body of the macro, although
interactive commands, such as di are not recommended (see
the interact command).
The expression $n,
where n is a digit from 1 to 9, is replaced
on invocation with the nth argument to the macro.
The expression $# evaluates to the number of arguments to the macro.
Entry of the macro body is terminated by a period ``.'' anywhere in the
macro body.
Include a period in the macro body by
preceding the character with a
backslash ``\''.
- em "name"
-
- delm "name"
-
Erases (deletes) the named macro.
- lm [ "name" ]
-
Lists the named macro.
If the macro name is omitted, lists all macros.
- nx
-
Repeats the call to the previously invoked macro.
The arguments used are those used on the previous call, possibly
modified by any intervening sa commands.
- sa n value
-
- setarg n value
-
Sets the nth macro argument to the given value.
The value of n should be between 1 and 9.
Useful within a macro to set up the arguments for the next call through
an nx command.
- args n
-
Sets the number of macro arguments to n.
- ec [ n ]
-
- echo [ n ]
-
If n is 1, macros are echoed when they are invoked.
If n is 0 (the default), macros are not echoed.
If n is missing, the status of the echo flag is printed.
If the ec command is given within a macro body,
it is in effect for that macro only.
- interact n
-
If n is 1, interactive commands (such as
di, bt, and mr)
when invoked during macro execution will read input from the user.
If n is 0 (the default), interactive commands inside macros will read
input from the macro body.
The interact command affects only the currently-executing macro and
has no effect outside a macro body.
- onbreak [ "name" ]
-
Set the on-break macro to the macro named by
name. If name
is omitted, it disables the on-break macro feature. The on-break macro, if
one is specified, is executed on every entrance to the debugger resulting
from any trap or breakpoint. This feature is very handy for implementing
conditional breakpoints.
- do "name" [ args ... ]
-
Repeatedly call the named macro with any
args
specified, until an
exit
command is executed. This is the only explicit form of iteration the
debugger provides. The
args
are passed to the first -- and, if
setarg
is not used, to every -- iteration.
- exit
-
Stop iterating a repeated macro call (see
do ).
Note that
exit
does not terminate the execution of the current macro; it merely prevents
further iterations.
Conditional commands
- IF expr
-
- EL
-
- FI
-
If the expression evaluates to zero, all commands up to the
matching EL or FI are skipped.
If the expression is non-zero, execution proceeds normally to the
matching FI, unless a matching EL is found,
in which case, commands between the EL and the FI
are skipped.
During any of this ``skipping'', the prompt changes from
Kn>
to -Kn> to indicate that the commands
are being read but not executed.
- if expr
-
- elseif expr
-
- else
-
- fi
-
Same as IF-EL-FI but with the elseif
construct which allows chaining
of conditional statements.
- ifdef "name"
-
Like if, but the condition is true if a
macro named name
exists.
- ifsdef "name"
-
Like if, but the condition is true if a
symbol named name exists.
Files
/etc/crash/macros Directory containing macro files.
References
crash(1M),
kcrash(1M),
kdb(1M)
Notices
If you try to go at the exact address where a breakpoint is set,
the breakpoint does not trigger.
The disassembler works only with protected mode (32 bit) instructions.
It does not know how to disassemble 16 bit instructions.
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.