DDB(4)                    NetBSD Programmer's Manual                    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 spe-
     cial 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 ddb.  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>
           hpcmips  <Ctrl>-<Alt>-<Esc>
           hpcsh    <Ctrl>-<Alt>-<Esc>
           i386     <Ctrl>-<Alt>-<Esc>
                    <Break> on serial console.
           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 the
     previous count and no modifiers.  Specifying address sets dot to the ad-
     dress.  If address is omitted, dot is used.  A missing count is taken to
     be 1 for printing commands, and infinity for stack traces.

     The syntax:

           ,count

     repeats the previous command, just as a blank line does, but with the
     specified count.

     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 dis-
     plays ``--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 in-
                     put 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:

     !address[(expression[,...])]
             A synonym for call.

     break[/u] address[,count]
            Set a breakpoint at address.  If count is supplied, continues
            (count-1) times before stopping at the breakpoint.  If the break-
            point is set, a breakpoint number is printed with `#'.  This num-
            ber 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 mes-
            sage 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 debug-
            ger, user-space breakpoints may not work correctly.  Setting a
            breakpoint at the low-level code paths may also cause strange be-
            havior.

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

     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.

     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 `#'.

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

     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 words (legacy ``long'', 32 bits).
                  L   examine long words (implementation dependent)
                  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 charac-
                      ters 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 alterna-
                      tive 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

     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.

     match[/p]
            A synonym for next.

     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.

     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

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

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

            Note: Limitations of the command line interface preclude specifi-
            cation of a boot string.

     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.

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

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

            /a   show the kernel virtual addresses of each process' proc
                 structure, u-area, and vmspace structure.  The vmspace ad-
                 dress 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.

     show breaks
            Display all breakpoints.

     show buf[/f] address
            Print the struct buf at address.  The /f does nothing at this
            time.

     show event[/f]
            Print all the non-zero evcnt(9) event counters.  If /f is speci-
            fied, all event counters with a count of zero are printed as well.

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

     show ncache address
            Dump the namecache list associated with vnode at address.

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

     show page[/f] address
            Print the vm_page at address.  If /f is specified, the complete
            page is printed.

     show pool[/clp] address
            Print the pool at address.  Valid modifiers:
            /c    Print the cachelist and its statistics for this pool.
            /l    Print the log entries for this pool.
            /p    Print the pagelist for this pool.

     show registers[/u]
            Display the register set.  If /u is specified, display user regis-
            ters 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 uvmexp
            Print a selection of UVM counters and statistics.

     show vnode[/f] address
            Print the vnode at address.  If /f is specified, the complete vn-
            ode is printed.

     show watches
            Display all watchpoints.

     sifting[/F] string
            Search the symbol tables for all symbols of which string is a sub-
            string, and display them. If /F is specified, a character is dis-
            played immediately after each symbol name indicating the type of
            symbol.

            For a.out(5)-format symbol tables, absolute symbols display @,
            text segment symbols display *, data segment symbols display +,
            BSS segment symbols display -, and filename symbols display /.
            For ELF-format symbol tables, object symbols display +, function
            symbols display *, section symbols display &, and file symbols
            display /.

            To sift for a string beginning with a number, escape the first
            character with a backslash as:

                  sifting \386

     step[/p] [,count]
            Single-step count times.  If /p is specified, print each instruc-
            tion 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.

     sync   Force a crash dump, and then reboot.

     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 de-
            pendent 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 cur-
            rent radix, whilst ps displays pids in decimal; prefix pid with
            `0t' to force it to be interpreted as decimal (see VARIABLES sec-
            tion for radix)

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

     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.

     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 unre-
            coverable error in some systems such as i386.  Watchpoints on user
            addresses work the best.

     write[/bhl] address expression [expression ...]
            Write the expressions at succeeding locations.  The unit size is
            specified with a modifier character, as per examine.  Valid modi-
            fiers 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 paren-
            theses.

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

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(1) 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
     kvtop      Print the physical address for a given kernel virtual address.
     tlb        Print out the Translation Lookaside Buffer (TLB).  Only works
                in NetBSD kernels compiled with DEBUG option.

   SH3
     tlb        Print TLB entries
     cache      Print cache entries
     frame      Print switch frame and trap frames.
     stack      Print kernel stack usage. Only works in NetBSD kernels com-
                piled with KSTACK_DEBUG option.

   SPARC
     prom       Exit to the Sun PROM monitor.

   SPARC64
     buf        Print buffer information.
     ctx        Print process context information.
     dtlb       Print data translation look-aside buffer context information.
     dtsb       Display data translation storage buffer information.
     kmap       Display information about the listed mapping in the kernel
                pmap.  Use the ``f'' modifier to get a full listing.
     pcb        Display information about the ``struct pcb'' listed.
     pctx       Attempt to change process context.
     page       Display the pointer to the ``struct vm_page'' for this physi-
                cal address.
     phys       Display physical memory.
     pmap       Display the pmap.  Use the ``f'' modifier to get a fuller
                listing.
     proc       Display some information about the process pointed to, or cur-
                proc.
     prom       Enter the OFW prom.
     pv         Display the ``struct pv_entry'' pointed to.
     stack      Dump the window stack.  Use the ``u'' modifier to get userland
                information.
     tf         Display full trap frame state.  This is most useful for inclu-
                sion with bug reports.
     ts         Display trap state.
     traptrace  Display or set trap trace information.  Use the ``r'' and
                ``f'' modifiers to get reversed and full information, respec-
                tively.
     uvmdump    Dumps the UVM histories.
     watch      Set or clear a physical or virtual hardware watchpoint.  Pass
                the address to be watched, or ``0'' to clear the watchpoint.
                Append ``p'' to the watch point to use the physical watchpoint
                registers.
     window     Print register window information about given address.

   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 indi-
     cate 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 initialized to off.
           fromconsole
                     If non-zero (the default), the kernel allows to enter ddb
                     from the console (by break signal or special key se-
                     quence).  If the kernel configuration option
                           options DDB_FROMCONSOLE=0
                     is used, fromconsole will be initialized to off.
           radix     Input and output radix.
           tabstops  Tab stop width.

     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 identifi-
                       er.  If supported by an object format dependent rou-
                       tine, [filename:]function[:linenumber], [file-
                       name:]variable, and filename[:linenumber], can be ac-
                       cepted 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 charac-
                       ters: `0x' - hex, `0o' - octal, `0t' - decimal, other-
                       wise 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.

SEE ALSO
     options(4), sysctl(8)

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

NetBSD 1.6                     February 11, 2001                             8

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen