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: 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:

  1. 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.

  2. 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.

  3. A percent sign followed by b and an instruction breakpoint number, meaning the address referred to by that breakpoint, such as %bx .

  4. A dollar sign, meaning the address of the last memory location that was displayed.

  5. 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.)

  6. The name of a user-defined debugger variable.

  7. 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.

  8. A string surrounded by single quotes `' or double quotes ``''. The C escape for the newline character ``\n'' may be used in the string.

  9. A percent sign followed by s and an expression, meaning the null-terminated character string starting at that memory address.

  10. A percent sign followed by p and an expression, meaning the physical memory address corresponding to that virtual address.

  11. 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''.

  12. Any numeric expression preceded by ``~'', meaning the ones-complement of the number.

Input Commands

The enhanced kernel debugger prompts with Kn, 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.