| DDB(4) | Device Drivers Manual | DDB(4) | 
ddb —
options DDB
To enable history editing:
  
  options DDB_HISTORY_SIZE=integer
To disable entering ddb upon kernel panic:
  
  options DDB_ONPANIC=0
To enable teeing all ddb output to the
    kernel msgbuf:
  
  options DDB_TEE_MSGBUF=1
To specify commands which will be executed on each entry to
    ddb:
  
  options DDB_COMMANDONENTER="trace;show
    registers" In this case, "trace" and then "show
    registers" will be executed automatically.
To enable extended online help:
  
  options DDB_VERBOSE_HELP.
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.
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:
The key sequence to activate ddb can be
    changed by modifying “hw.cnmagic” with
    sysctl(8). If the console is
    not dedicated to ddb the sequence should not be
    easily typed by accident. In addition, ddb may be
    explicitly activated by the debugging code in the kernel if
    DDB is configured.
Commands can be automatically run when ddb
    is entered by using options DDB_COMMANDONENTER or by
    setting ddb.commandonenter with
    sysctl(8). Multiple commands
    can be separated by a semi-colon.
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 address. 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:
,countrepeats 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
    displays “--db more--” and waits for a response, which may be
    one of:
qYou can set lines variable to zero to disable this feature.
If ddb history editing is enabled (by
    defining the
options
  DDB_HISTORY_SIZE=numnum commands
  is kept. The history can be manipulated with the following key sequences:
ddb supports the following commands:
!address([expression[,...])]call.break[/u]
    address[,count]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.
bt[/ul]
    [frame-address][,count]trace.bt/t[/ul]
    [pid][,count]trace/t.bt/a[/ul]
    [lwpaddr][,count]trace/a.call
    address([expression[,...])]continue[/c]/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 |
    #numberbreak, or by
      the breakpoint number returned by break if it's
      prefixed with ‘#’.dmesg
    [count]dwatch
    addresswatch command.examine[/modifier]
    address[,count]examine is used.
    The valid format characters for modifier are:
bhlqLaAxzodurcsmpiIkill
    pid[,signal_number]trace/t command for details). If
      signal_number isn't specified, the SIGTERM signal is
      sent.match[/p]next.next[/p]/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 ...]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][/l]show all procs.reboot
    [flags]| Value | Name | Description | 
| 0x1 | RB_ASKNAME | Ask for file name to reboot from | 
| 0x2 | RB_SINGLE | Reboot to single user mode | 
| 0x4 | RB_NOSYNC | Don't sync before reboot | 
| 0x8 | RB_HALT | Halt instead of reboot | 
| 0x40 | RB_KDB | Boot into kernel debugger | 
| 0x100 | RB_DUMP | Dump unconditionally before reboot | 
| 0x808 | RB_POWERDOWN | Power off (or at least halt) | 
Note: Limitations of the command line interface preclude specification of a boot string.
search[/bhl]
    address value
    [mask] [,count]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
    [=] expressionshow
    all calloutshow
    all locks[/t]/t is specified, stack traces of LWPs holding
      locks are also printed. This command is only useful if a kernel is
      compiled with options LOCKDEBUG.show
    all mount[/f]/f is specified, the
      complete vnode list is printed.show
    all pagesshow page.show
    all pools[/clpsS]show pool.show all procs[/a][/n][/w][/l]/n/ashow map command./w/lshow
    all tstiles[/t]/tshow
    routesAF_INET routing table. This
      command is available only on systems which support inet.show
    breaksshow
    buf[/f]
    address/f does nothing at this time.show
    event[/f][/i][/m][/t]/f/i/m/tIf none of /i,
        /m, or /t are specified,
        all are shown. You can combine any of these. For example, the modifier
        /itf will select both interrupt and trap events,
        including those that are non-zero.
show
    files addressshow all procs /a command. If the kernel is
      compiled with options LOCKDEBUG then details about
      the locking of the underlying uvm object will also be displayed.show
    lock addressoptions LOCKDEBUG.show
    lockstatsoptions LOCKDEBUG.show
    map[/f]
    address/f is specified, the complete map is printed.show
    mount[/f]
    address/f is specified, the complete vnode list is
      printed.show
    mbuf[/cdv]
    addressshow
    ncache addressshow
    object[/f]
    address/f is specified, the complete object is
    printed.show
    page[/f]
    address/f is specified, the complete page is
    printed.show
    panicshow
    pool[/clpsS]
    address/c/l/p/s/Sshow
    proc[/ap] address |
    pidshow
    registers[/u]/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
    sched_qsshow
    socket[/ampv]show
    uvmexpshow
    kernhist[/i]
    [addr[,count]]/i is specified, display
      information about the named history or all histories, instead of history
      entries. If count is specified, only the last
      count entries will be displayed. Currently the
      count handling is only performed if a single history
      is requested. This command is available only if a kernel is compiled with
      one or more of the kernel history options
      KERNHIST, SYSCALL_DEBUG,
      USB_DEBUG, BIOHIST, or
      UVMHIST.show
    vmem addressshow
    vmemsshow
    vnode[/f]
    address/f is specified, the complete vnode is
    printed.show
    vnode_lock[/f]
    address/f is specified, the complete vnode is
    printed.show
    watchessifting[/F]
    string/F is specified, a character is displayed
      immediately after each symbol name indicating the type of symbol.
    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]/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.
synctrace[/u[l]]
    [frame-address][,count]/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.
      If /l is specified, the trace is printed and also
      stored in the kernel message buffer.
    Warning: user-space stack trace is valid only if the machine dependent code supports it.
trace/t[l]
    [pid][,count]ps displays pids in decimal; prefix
      pid with ‘0t’ to force it to be
      interpreted as decimal (see VARIABLES
      section for radix). If /l is specified, the trace
      is printed and also stored in the kernel message buffer.
    Warning: trace by pid is valid only if the machine dependent code supports it.
trace/a[l]
    [lwpaddr][,count]/l is specified, the trace is
      printed and also stored in the kernel message buffer.
    Warning: trace by LWP address is valid only if the machine dependent code supports it.
until[/p]/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]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.
whatis
    addresswrite[/bhlqBHLQ]
    address expression
    [expression ...]examine. Valid modifiers are:
      /b, /h,
      /l, and /q. If no modifier
      is specified, /l is used.
    Specifying the modifiers in upper case,
        /B, /H,
        /L, /Q, will prevent
        ddb from reading the memory location first,
        which is useful for avoiding side effects when writing to I/O memory
        regions.
Warning: since there is no delimiter between expressions, strange things may occur. It's best to enclose each expression in parentheses.
x[/modifier]
    address[,count]examine.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:
breakcpucpuinfoframelwppteresetsysregwatchcpucpuframecpuvectorcp0cpukvtopnmiresettlb/v modifier to show only valid TLB entries.watch/m i for trap on an instruction
      fetch, /r for trap on a read,
      /w for trap on a write, /m
      for a mask on the address to match, /a for trap on
      a TLB ASID match. The /m and
      /a modifiers require an extra argument for the
      mask and ASID respectively.unwatchctxpvresettftlbdcruserctxcpudtlbdtsbkmapextractfpstateitlbitsblwppcbpctxpagephyspmapprocprompvsirstacktftstraptracewatchwindowcpuddb 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:
ddb is entered on panic.ddb from the console (by break signal or special
      key sequence). If the kernel configuration option
    options
      DDB_FROMCONSOLE=0more
      feature. When this variable is set to zero the
      more feature is disabled.'symbol'+offset unless
      offset is greater than
      maxoff.ddb wraps the
      current line by printing new line when maxwidth
      column is reached. When this variable is set to zero
      ddb doesn't perform any wrapping.ddb will
      be invoked when the kernel panics. If the kernel configuration option
    options
      DDB_ONPANIC=0ddb being entered. Setting
      onpanic to -1 suppresses the stack trace before
      reboot.ddb output will not only be displayed on screen
      but also be fed to the msgbuf. The default of the variable can be set
      using the kernel configuration option
    options
      DDB_TEE_MSGBUF=1ddb output from a crash
      investigation. This option is more generic than the /l command modifier
      possible for selected commands as discussed above to log the output.
      Mixing both /l and this setting can give double loggings.65535 (all frames), useful value around
      10.All built-in variables are accessible via sysctl(3).
ddb are:
emulator::mach_msg_trap) to specify other than
      kernel symbols..+..examine or
      write commands."$name#*exprddb kernel debugger was written as part of the MACH
  project at Carnegie-Mellon University.
| April 28, 2022 | NetBSD 10.0 |