DDB(4)

NAME
ddb - in-kernel debugger

SYNOPSIS
options DDB

To enable history editing:
options DDB_HISTORY_SIZE=integer

To disable entering
ddb upon kernel panic:
options DDB_ONPANIC=0

DESCRIPTION
ddb is the in-kernel debugger. It may be entered at any time via a special key sequence, and optionally may be invoked when the kernel panics.

ENTERING THE DEBUGGER
Unless DDB_ONPANIC is set to 0, ddb will be activated whenever the kernel would otherwise panic.

ddb may also be activated from the console. In general, sending a break on a serial console will activate. There are also key sequences for each port that will activate ddb from the keyboard:

alpha
    <Ctrl>-<Alt>-<Esc> on PC style keyboards.

amiga
    <LAlt>-<LAmiga>-<F10>

atari
    <Alt>-<LeftShift>-<F9>

hp300
    <Shift>-<Reset>

i386
    <Ctrl>-<Alt>-<Esc>

mac68k
    <Command>-<Power>, or the Interrupt switch.

mvme68k
    Abort switch on CPU card.

pmax
    <Do> on LK-201 rcons console.
    <Break> on serial console.

sparc
    <L1>-A, or <Stop>-A on a Sun keyboard.
    <Break> on serial console.

sun3
    <L1>-A, or <Stop>-A on a Sun keyboard.
    <Break> on serial console.

sun3x
    <L1>-A, or <Stop>-A on a Sun keyboard.
    <Break> on serial console.

x68k
    Interrupt switch on the body.

In addition, ddb may be explicitly activated by the debugging code in the kernel if DDB is configured.

COMMAND SYNTAX

The general command syntax is:

command[/modifier] address [,count]

The current memory location being edited is referred to as dot, and the next location is next. They are displayed as hexadecimal numbers.

Commands that examine and/or modify memory update dot to the address of the last line examined or the last location modified, and set next to the next location to be examined or modified. Other commands don't change dot, and set next to be the same as dot.

A blank line repeats the previous command from the address next with a count of 1 and no modifiers. Specifying address sets dot to the address. If address is omitted, dot is used. A missing count is taken to be 1 for printing commands, and infinity for stack traces.

ddb has a more(1) -like functionality; if a number of lines in a command's output exceeds the number defined in the lines variable, then ddb displays “--db more--” and waits for a response, which may be one of:

<return>
    one more line.

<space>
    one more page.

q   abort the current command, and return to the command input mode.

If ddb history editing is enabled (by defining the
    options DDB_HISTORY_SIZE=num
kernel option), then a history of the last num commands is kept. The history can be manipulated with the following key sequences:

<Ctrl>-P
    retrieve previous command in history (if any).

<Ctrl>-N
    retrieve next command in history (if any).

COMMANDS
ddb supports the following commands:

    examine[/modifier] address[,count] Display the address locations according to the format in modifier. Multiple modifier formats display multiple locations. If modifier isn't specified, the modifier from the last use of examine is used.

    The valid format characters for modifier are:

    b   examine bytes (8 bits).

    h   examine half-words (16 bits).

    l   examine long-words (32 bits).

    a   print the location being examined.

    A   print the location with a line number if possible.

    x   display in unsigned hex.

    z   display in signed hex.

    o   display in unsigned octal.

    d   display in signed decimal.

    u   display in unsigned decimal.

    r   display in current radix, signed.

    c   display low 8 bits as a character. Non-printing characters as displayed as an octal escape code (e.g., ‘\000’).

    s   display the NUL terminated string at the location. Non-printing characters are displayed as octal escapes.

    m   display in unsigned hex with a character dump at the end of each line. The location is displayed as hex at the beginning of each line.

    i   display as a machine instruction.

    I   display as a machine instruction, with possible alternative formats depending upon the machine:

        alpha
            print register operands

        m68k
            use Motorola syntax

        pc532
            print instruction bytes in hex

        vax don't assume that each external label is a procedure entry mask

    x[/modifier] address[,count] A synonym for examine.

xf  Examine forward. xf re-executes the most recent execute command with the same parameters except that address is set to next.

xb  Examine backward. xb re-executes the most recent execute command with the same parameters, except that address is set to the last start address minus its size.

    print[/axzodurc] address [address ...] Print addresses address according to the modifier character, as per examine. Valid modifiers are: /a, /x, /z, /o, /d, /u, /r, and /c (as per examine). If no modifier is specified, the most recent one specified is used. address may be a string, and is printed “as-is”. For example:

        print/x "eax = " $eax "\necx = " $ecx "\n"

    will produce:

        eax = xxxxxx
        ecx = yyyyyy

    write[/bhl] address expression [expression ...] Write the expressions at succeeding locations. The unit size is specified with a modifier character, as per examine. Valid modifiers are: /b, /h, and /l. If no modifier is specified, /l is used.

    Warning: since there is no delimiter between expressions, strange things may occur. It's best to enclose each expression in parentheses.

    set $variable [=] expression Set the named variable or register to the value of expression. Valid variable names are described in VARIABLES.

    break[/u] address[,count] Set a breakpoint at address. If count is supplied, continues (count-1) times before stopping at the breakpoint. If the breakpoint is set, a breakpoint number is printed with ‘#’. This number can be used to delete the breakpoint, or to add conditions to it.

    If /u is specified, set a breakpoint at a user-space address. Without /u, address is considered to be in the kernel-space, and an address in the wrong space will be rejected, and an error message will be emitted. This modifier may only be used if it is supported by machine dependent routines.

    Warning: if a user text is shadowed by a normal user-space debugger, user-space breakpoints may not work correctly. Setting a breakpoint at the low-level code paths may also cause strange behavior.

    delete address | #number Delete a breakpoint. The target breakpoint may be specified by address, as per break, or by the breakpoint number returned by break if it's prefixed with ‘#’.

    step[/p] [,count] Single-step count times. If /p is specified, print each instruction at each step. Otherwise, only print the last instruction.

    Warning: depending on the machine type, it may not be possible to single-step through some low-level code paths or user-space code. On machines with software-emulated single-stepping (e.g., pmax), stepping through code executed by interrupt handlers will probably do the wrong thing.

continue[/c]
    Continue execution until a breakpoint or watchpoint. If /c is specified, count instructions while executing. Some machines (e.g., pmax) also count loads and stores.

    Warning: when counting, the debugger is really silently single-stepping. This means that single-stepping on low-level may cause strange behavior.

until[/p]
    Stop at the next call or return instruction. If /p is specified, print the call nesting depth and the cumulative instruction count at each call or return. Otherwise, only print when the matching return is hit.

next[/p]
    Stop at the matching return instruction. If /p is specified, print the call nesting depth and the cumulative instruction count at each call or return. Otherwise, only print when the matching return is hit.

match[/p]
    A synonym for next.

    trace[/u] [frame-address] [,count] Stack trace from frame-address. If /u is specified, trace user-space, otherwise trace kernel-space. count is the number of frames to be traced. If count is omitted, all frames are printed.

    Warning: user-space stack trace is valid only if the machine dependent code supports it.

    trace/t [pid] [,count] Stack trace by “thread” (process, on NetBSD) rather than by stack frame address. Note that pid is interpreted using the current radix, whilst ps displays pids in decimal; prefix pid with ‘0t’ to force it to be interpreted as decimal (see VARIABLES section for radix)

    Warning: trace by pid is valid only if the machine dependent code supports it.

    search[/bhl] address value [mask] [,count] Search memory from address for value. The unit size is specified with a modifier character, as per examine. Valid modifiers are: /b, /h, and /l. If no modifier is specified, /l is used.

    This command might fail in interesting ways if it doesn't find value. This is because ddb doesn't always recover from touching bad memory. The optional count limits the search.

reboot [flags]
    Reboot, using the optionally supplied boot flags.

    Note: Limitations of the command line interface preclude specification of a boot string.

    show all procs [/a] [/n] [/w] Display all process information. Valid modifiers:

    /n  show process information in a ps(1) style format (this is the default). Information printed includes: process ID, parent process ID, process group, UID, process status, process flags, process command name, and process wait channel message.

    /a  show the kernel virtual addresses of each process' proc structure, u-are, and vmspace structure. The vmspace address is also the address of the process' vm_map structure, and can be used in the show map command.

    /w  show each process' PID, command, system call emulation, wait channel address, and wait channel message.

    ps [/a] [/n] [/w] A synonym for show all procs.

show registers[/u]
    Display the register set. If /u is specified, display user registers instead of kernel registers or the currently save one.

    Warning: support for /u is machine dependent. If not supported, incorrect information will be displayed.

    show map[/f] address Print the vm_map at address. If /f is specified the complete map is printed.

    show object[/f] address Print the vm_object at address. If /f is specified the complete object is printed.

show watches
    Display all watchpoints.

    watch address [,size] Set a watchpoint for a region. Execution stops when an attempt to modify the region occurs. size defaults to 4.

    If you specify a wrong space address, the request is rejected with an error message.

    Warning: attempts to watch wired kernel memory may cause an unrecoverable error in some systems such as i386. Watchpoints on user addresses work the best.

    dwatch address Delete the watchpoint at address that was previously set with watch command.

    kill pid[,signal_number] Send a signal to the process specified by the pid. Note that pid is interpreted using the current radix (see trace/t command for details). If signal_number isn't specified, the SIGTERM signal is sent.

    call address [ (expression [,...])] Call the function specified by address with the argument(s) listed in parentheses. Parentheses may be omitted if the function takes no arguments. The number of arguments is currently limited to 10.

MACHINE-SPECIFIC COMMANDS
The "glue" code that hooks ddb into the NetBSD kernel for any given port can also add machine specific commands to the ddb command parser. All of these commands are preceded by the command word machine to indicate that they are part of the machine-specific command set (e.g. machine reboot ). Some of these commands are:

  ALPHA

halt
    Call the PROM monitor to halt the CPU.

reboot
    Call the PROM monitor to reboot the CPU.

  ARM32

vmstat
    Equivalent to vmstat(8) output with "-s" option (statistics).

vnode
    Print out a description of a vnode.

intrchain
    Print the list of IRQ handlers.

panic
    Print the current "panic" string.

frame
    Given a trap frame address, print out the trap frame.

  MIPS

halt
    Call the PROM monitor to halt the CPU.

tlb Print out the Translation Lookaside Buffer (TLB).

trapdump
    Print out the Trap Log. Only works in NetBSD kernels compiled with DEBUG option.

  SPARC

prom
    Exit to the Sun PROM monitor.

  SUN3 and SUN3X

abort
    Drop into monitor via abort (allows continue).

halt
    Exit to Sun PROM monitor as in halt(8).

reboot
    Reboot the machine as in reboot(8).

pgmap
    Given an address, print the address, segment map, page map, and Page Table Entry (PTE).

VARIABLES
ddb accesses registers and variables as $name. Register names are as per the show registers command. Some variables are suffixed with numbers, and may have a modifier following a colon immediately after the variable name. For example, register variables may have a ‘u’ modifier to indicate user register (e.g., $eax:u).

Built-in variables currently supported are:

lines
    The number of lines. This is used by the more feature.

maxoff
    Addresses are printed as 'symbol'+offset unless offset is greater than maxoff.

maxwidth
    The width of the displayed line.

onpanic
    If non-zero (the default), ddb will be invoked when the kernel panics. If the kernel configuration option
        options DDB_ONPANIC=0
    is used, onpanic will be initialised to off.

radix
    Input and output radix.

tabstops
    Tab stop width.

workxx
    Temporary work variable. ‘xx’ is between 0 and 31.

All built-in variables are accessible via sysctl(3).

EXPRESSIONS
Almost all expression operators in C are supported, except ‘~’, ‘^’, and unary ‘&’. Special rules in ddb are:

identifier
    name of a symbol. It is translated to the address (or value) of it. ‘’. and ‘’: can be used in the identifier. If supported by an object format dependent routine, [filename:] function [:line number], [filename:] variable, and filename [:line number], can be accepted as a symbol. The symbol may be prefixed with symbol_table_name:: (e.g., emulator::mach_msg_trap) to specify other than kernel symbols.

number
    number. Radix is determined by the first two characters: ‘0x’ - hex, ‘0o’ - octal, ‘0t’ - decimal, otherwise follow current radix.

.   dot

+   next

..  address of the start of the last line examined. Unlike dot or next, this is only changed by the examine or write commands.

,   last address explicitly specified.

$name
    register name or variable. It is translated to the value of it. It may be followed by a ‘’: and modifiers as described above.

a   multiple of right-hand side.

*expr
    expression indirection. It may be followed by a ‘’: and modifiers as described above.

HISTORY
The ddb kernel debugger was written as part of the MACH project at Carnegie-Mellon University.

SEE ALSO
options(4), sysctl(8)