home | help
DDB(4)			     Kernel Interfaces Manual			  DDB(4)

NAME
     ddb -- interactive kernel debugger

SYNOPSIS
     options KDB
     options DDB

     To prevent activation of the debugger on kernel panic(9):
     options KDB_UNATTENDED

DESCRIPTION
     The ddb kernel debugger has most of the features of the old kdb, but with a
     more  rational  syntax inspired by gdb(1).  If linked into the running ker-
     nel, it can be invoked locally with the `debug' keymap(5) action.	The  de-
     bugger  is  also  invoked on kernel panic(9) if the debug.debugger_on_panic
     sysctl(8) MIB variable is set non-zero, which is  the  default  unless  the
     KDB_UNATTENDED option is specified.

     The  current location is called dot.  The dot is displayed with a hexadeci-
     mal format at a prompt.  The commands examine and write update dot  to  the
     address  of  the  last line examined or the last location modified, and set
     next to the address of the next location to be examined or changed.   Other
     commands do not change dot, and set next to be the same as dot.

     The general command syntax is: command[/modifier] address[,count]

     A	blank line repeats the previous command from the address next with count
     1 and no modifiers.  Specifying address sets dot to the address.	Omitting
     address  uses  dot.  A missing count is taken to be 1 for printing commands
     or infinity for stack traces.

     The ddb debugger has a pager feature (like the  more(1)  command)	for  the
     output.  If an output line exceeds the number set in the lines variable, it
     displays  "--More--"  and waits for a response.  The valid responses for it
     are:

     SPC  one more page
     RET  one more line
     q	  abort the current command, and return to the command input mode

     Finally, ddb provides a small (currently 10 items) command history, and of-
     fers simple emacs-style command line editing capabilities.  In addition  to
     the  emacs  control keys, the usual ANSI arrow keys might be used to browse
     through the history buffer, and move the cursor within the current line.

COMMANDS
     examine
     x	     Display the addressed locations according to  the	formats  in  the
	     modifier.	 Multiple  modifier  formats display multiple locations.
	     If no format is specified, the last format specified for this  com-
	     mand is used.

	     The format characters are:
	     b	     look at by bytes (8 bits)
	     h	     look at by half words (16 bits)
	     l	     look at by long words (32 bits)
	     a	     print the location being displayed
	     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
		     are displayed as an octal escape code (e.g., `\000').
	     s	     display  the  null-terminated string at the location.  Non-
		     printing characters are displayed as octal escapes.
	     m	     display in unsigned hex with character dump at the  end  of
		     each  line.   The	location is also displayed in hex at the
		     beginning of each line.
	     i	     display as an instruction
	     I	     display as an instruction with possible  alternate  formats
		     depending on the machine:
		     alpha    Show the registers of the instruction.
		     amd64    No alternate format.
		     i386     No alternate format.
		     ia64     No alternate format.
		     powerpc  No alternate format.
		     sparc64  No alternate format.
	     S	     display a symbol name for the pointer stored at the address

     xf      Examine forward: execute an examine command with the last specified
	     parameters  to  it  except that the next address displayed by it is
	     used as the start address.

     xb      Examine backward: execute an examine command with the  last  speci-
	     fied parameters to it except that the last start address subtracted
	     by the size displayed by it is used as the start address.

     print[/acdoruxz]
     p[/acdoruxz]
	     Print addrs according to the modifier character (as described above
	     for  examine).   Valid formats are: a, x, z, o, d, u, r, and c.  If
	     no modifier is specified, the last one specified  to  it  is  used.
	     The  argument  addr can be a string, in which case it is printed as
	     it is.  For example:

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

	     will print like:

		   eax = xxxxxx
		   ecx = yyyyyy

     write[/bhl] addr expr1 [expr2 ...]
     w[/bhl] addr expr1 [expr2 ...]
	     Write the expressions specified after addr on the command	line  at
	     succeeding  locations  starting with addr.  The write unit size can
	     be specified in the modifier with a letter b (byte), h (half  word)
	     or l (long word) respectively.  If omitted, long word is assumed.

	     Warning:  since  there is no delimiter between expressions, strange
	     things may happen.  It is best to enclose each expression in paren-
	     theses.

     set $variable [=] expr
	     Set the named variable or register with the value of  expr.   Valid
	     variable names are described below.

     break[/u]
     b[/u]   Set a break point at addr.  If count is supplied, continues count -
	     1	times before stopping at the break point.  If the break point is
	     set, a break point number is printed with `#'.  This number can  be
	     used in deleting the break point or adding conditions to it.

	     If  the u modifier is specified, this command sets a break point in
	     user space address.  Without the u option, the address  is  consid-
	     ered  in the kernel space, and wrong space address is rejected with
	     an error message.	This modifier can be used only	if  it	is  sup-
	     ported by machine dependent routines.

	     Warning:  If  a user text is shadowed by a normal user space debug-
	     ger, user space break points may not  work  correctly.   Setting  a
	     break  point at the low-level code paths may also cause strange be-
	     havior.

     delete addr
     d addr
     delete #number
     d #number
	     Delete the break point.  The target break point can be specified by
	     a break point number with `#', or by using the same addr  specified
	     in the original break command.

     watch addr,size
	     Set  a watchpoint for a region.  Execution stops when an attempt to
	     modify the region occurs.	The size argument defaults to 4.  If you
	     specify a wrong space address, the request is rejected with an  er-
	     ror message.

	     Warning: Attempts to watch wired kernel memory may cause unrecover-
	     able  error  in some systems such as i386.  Watchpoints on user ad-
	     dresses work best.

     hwatch addr,size
	     Set a hardware watchpoint for a region if supported by  the  archi-
	     tecture.	Execution stops when an attempt to modify the region oc-
	     curs.  The size argument defaults to 4.

	     Warning: The hardware debug facilities do not  have  a  concept  of
	     separate  address	spaces	like the watch command does.  Use hwatch
	     for setting watchpoints on kernel address locations only, and avoid
	     its use on user mode address spaces.

     dhwatch addr,size
	     Delete specified hardware watchpoint.

     step[/p]
     s[/p]   Single step count times (the comma is a mandatory part of the  syn-
	     tax).   If  the  p modifier is specified, print each instruction at
	     each step.  Otherwise, only print the last instruction.

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

     continue[/c]
     c[/c]   Continue execution until a breakpoint or watchpoint.  If the c mod-
	     ifier  is	specified, count instructions while executing.	Some ma-
	     chines (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 code may
	     cause strange behavior.

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

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

     trace[/u] [pid | tid] [,count]
     t[/u] [pid | tid] [,count]
     where[/u] [pid | tid] [,count]
     bt[/u] [pid | tid] [,count]
	     Stack trace.  The u option traces user  space;  if  omitted,  trace
	     only  traces kernel space.  The optional argument count is the num-
	     ber of frames to be traced.  If count is omitted,	all  frames  are
	     printed.

	     Warning: User space stack trace is valid only if the machine depen-
	     dent code supports it.

     search[/bhl] addr value [mask] [,count]
	     Search  memory  for  value.  This command might fail in interesting
	     ways if it does not find the searched-for value.  This  is  because
	     ddb does not always recover from touching bad memory.  The optional
	     count argument limits the search.

     show all procs[/m]
     ps[/m]  Display  all  process information.  The process information may not
	     be shown if it is not supported in the machine, or  the  bottom  of
	     the  stack  of the target process is not in the main memory at that
	     time.  The m modifier will alter the display to  show  VM	map  ad-
	     dresses for the process and not show other info.

     show registers[/u]
	     Display  the register set.  If the u modifier is specified, it dis-
	     plays user registers instead of kernel or currently saved one.

	     Warning: The support of the u modifier depends on the machine.   If
	     not supported, incorrect information will be displayed.

     show sysregs
	     Show  system  registers (e.g., cr0-4 on i386.)  Not present on some
	     platforms.

     show geom [addr]
	     If the addr argument is not given, displays the entire GEOM  topol-
	     ogy.   If	the addr is given, displays details about the given GEOM
	     object (class, geom, provider or consumer).

     show map[/f] addr
	     Prints the VM map at addr.  If the f modifier is specified the com-
	     plete map is printed.

     show object[/f] addr
	     Prints the VM object at addr.  If the f  option  is  specified  the
	     complete object is printed.

     show vnode addr
	     Displays details about the given vnode.

     show watches
	     Displays all watchpoints.

     gdb     Toggles  between  remote GDB and DDB mode.  In remote GDB mode, an-
	     other machine is required that runs gdb(1) using the  remote  debug
	     feature, with a connection to the serial console port on the target
	     machine.  Currently only available on the i386 architecture.

     halt    Halt the system.

     kill sig pid
	     Send  signal  sig	to process pid.  The signal is acted on upon re-
	     turning from the debugger.  This command can  be  used  to  kill  a
	     process  causing  resource contention in the case of a hung system.
	     See signal(3) for a list of signals.  Note that the  arguments  are
	     reversed relative to kill(2).

     reboot
     reset   Hard reset the system.

     help    Print  a short summary of the available commands and command abbre-
	     viations.

     capture on
     capture off
     capture reset
     capture status
	     ddb supports a basic output capture facility, which can be used  to
	     retrieve  the  results  of  debugging commands from userpsace using
	     sysctl(2).  capture on enables output capture; capture off disables
	     capture.  capture reset will clear the capture buffer  and  disable
	     capture.	capture  status  will  report current buffer use, buffer
	     size, and disposition of output capture.

	     Userspace processes may inspect and manage ddb capture state  using
	     sysctl(8):

	     debug.ddb.capture.bufsize	may  be used to query or set the current
	     capture buffer size.

	     debug.ddb.capture.maxbufsize may be used to query the  compile-time
	     limit on the capture buffer size.

	     debug.ddb.capture.bytes may be used to query the number of bytes of
	     output currently in the capture buffer.

	     debug.ddb.capture.data  returns  the  contents  of  the buffer as a
	     string to an appropriately privileged process.

	     This facility is particularly useful in concert with the  scripting
	     and  textdump(4)  facilities, allowing scripted debugging output to
	     be captured and committed to disk as part of a textdump  for  later
	     analysis.	The contents of the capture buffer may also be inspected
	     in a kernel core dump using kgdb(1).

     run
     script
     scripts
     unscript
	     Run, define, list, and delete scripts.  See the "SCRIPTING" section
	     for more information on the scripting facility.

     textdump set
     textdump status
     textdump unset
	     The  textdump set command may be used to force the next kernel core
	     dump to be a textdump rather than	a  traditional	memory	dump  or
	     minidump.	 textdump  status  reports  whether  a textdump has been
	     scheduled.  textdump unset cancels a request to perform a	textdump
	     as  the  next  kernel  core dump.	More information may be found in
	     textdump(4).

VARIABLES
     The debugger accesses registers and variables as $name.  Register names are
     as in the "show registers" command.  Some variables are suffixed with  num-
     bers,  and  may  have some modifier following a colon immediately after the
     variable name.  For example, register variables can have a  u  modifier  to
     indicate user register (e.g., "$eax:u").

     Built-in variables currently supported are:

     radix     Input and output radix.
     maxoff    Addresses are printed as "symbol+offset" unless offset is greater
	       than maxoff.
     maxwidth  The width of the displayed line.
     lines     The number of lines.  It is used by the built-in pager.
     tabstops  Tab stop width.
     workxx    Work variable; xx can take values from 0 to 31.

EXPRESSIONS
     Most  expression  operators  in  C are supported except `~', `^', and unary
     `&'.  Special rules in ddb are:

     Identifiers  The name of a symbol is translated to the value of the symbol,
		  which is the address of the corresponding object.  `.' and `:'
		  can be used in the identifier.  If supported by an object for-
		  mat	   dependent	  routine,	 [filename:]func:lineno,
		  [filename:]variable,	and [filename:]lineno can be accepted as
		  a symbol.

     Numbers	  Radix is determined by the first two letters: `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 examine or write command.

     '		  last address explicitly specified.

     $variable	  Translated to the value of the specified variable.  It may  be
		  followed by a `:' and modifiers as described above.

     a#b	  A  binary  operator  which rounds up the left hand side to the
		  next multiple of right hand side.

     *expr	  Indirection.	It may be followed by a `:' and modifiers as de-
		  scribed above.

SCRIPTING
     ddb supports a basic scripting facility to allow automating  tasks  or  re-
     sponses to specific events.  Each script consists of a list of DDB commands
     to be executed sequentially, and is assigned a unique name.  Certain script
     names  have  special  meaning, and will be automatically run on various ddb
     events if scripts by those names have been defined.

     The script command may be used to define a script by name.  Scripts consist
     of a series of ddb commands separated with the ; character.  For example:

	   script kdb.enter.panic=bt; show pcpu
	   script lockinfo=show alllocks; show lockedvnods

     The scripts command lists currently defined scripts.

     The run command execute a script by name.	For example:

	   run lockinfo

     The unscript command may be used to delete a script by name.  For example:

	   unscript kdb.enter.panic

     These functions may also be performed from userspace using the ddb(8)  com-
     mand.

     Certain scripts are run automatically, if defined, for specific ddb events.
     The follow scripts are run when various events occur:

     kdb.enter.acpi	  The  kernel  debugger  was  entered  as a result of an
			  acpi(4) event.

     kdb.enter.bootflags  The kernel debugger was entered at boot as a result of
			  the debugger boot flag being set.

     kdb.enter.break	  The kernel debugger was entered as a result of a  ser-
			  ial or console break.

     kdb.enter.cam	  The  kernel  debugger  was  entered  as  a result of a
			  CAM(4) event.

     kdb.enter.mac	  The kernel debugger was entered as a result of an  as-
			  sertion  failure  in	the  mac_test(4)  module  of the
			  TrustedBSD MAC Framework.

     kdb.enter.ndis	  The kernel debugger was entered  as  a  result  of  an
			  ndis(4) breakpoint event.

     kdb.enter.netgraph   The  kernel debugger was entered as a result of a net-
			  graph(4) event.

     kdb.enter.panic	  panic(9) was called.

     kdb.enter.powerfail  The kernel debugger was entered as a result of a  pow-
			  erfail NMI on the sparc64 platform.

     kdb.enter.powerpc	  The  kernel  debugger  was  entered  as a result of an
			  unimplemented interrupt type on the powerpc platform.

     kdb.enter.sysctl	  The kernel debugger was entered as  a  result  of  the
			  debug.kdb.enter sysctl being set.

     kdb.enter.trapsig	  The kernel debugger was entered as a result of a trap-
			  sig event on the sparc64 or sun4v platform.

     kdb.enter.unionfs	  The  kernel debugger was entered as a result of an as-
			  sertion failure in the union file system.

     kdb.enter.unknown	  The kernel debugger was entered,  but  no  reason  has
			  been set.

     kdb.enter.vfslock	  The  kernel  debugger was entered as a result of a VFS
			  lock violation.

     kdb.enter.watchdog   The kernel debugger was  entered  as	a  result  of  a
			  watchdog firing.

     kdb.enter.witness	  The  kernel debugger was entered as a result of a wit-
			  ness(4) violation.

     In the event that none of these scripts is found, ddb will attempt to  exe-
     cute a default script:

     kdb.enter.default	  The  kernel debugger was entered, but a script exactly
			  matching the reason  for  entering  was  not	defined.
			  This	can  be  used as a catch-all to handle cases not
			  specifically	   of	  interest;	for	example,
			  kdb.enter.witness  might  be	defined  to have special
			  handling, and kdb.enter.default might  be  defined  to
			  simply panic and reboot.

HINTS
     On  machines with an ISA expansion bus, a simple NMI generation card can be
     constructed by connecting a push button between the A01 and B01 (CHCHK# and
     GND) card fingers.  Momentarily shorting these  two  fingers  together  may
     cause  the  bridge  chipset  to generate an NMI, which causes the kernel to
     pass control to ddb.  Some bridge chipsets do not generate a NMI on CHCHK#,
     so your mileage may vary.	The NMI allows one to break into the debugger on
     a wedged machine to diagnose problems.  Other bus' bridge chipsets  may  be
     able to generate NMI using bus specific methods.

SEE ALSO
     gdb(1),   kgdb(1),  acpi(4),  CAM(4),  mac_text(4),  ndis(4),  netgraph(4),
     textdump(4), witness(4), ddb(8), sysctl(8), panic(9)

HISTORY
     The ddb debugger was developed for Mach, and ported to  386BSD  0.1.   This
     manual page translated from man(7) macros by Garrett Wollman.

     Robert  N.  M. Watson added support for ddb output capture, textdump(4) and
     scripting in FreeBSD 7.1.

FreeBSD 7.1			December 26, 2007			  DDB(4)

home | help