Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
DDB(4)		       FreeBSD 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
     kernel, it	can be invoked locally with the	`debug'	keymap(5) action.  The
     debugger 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 hexadec-
     imal 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
     offers 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
	     command 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 charac-
		     ters 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.

     xf	     Examine forward: execute an examine command with the last speci-
	     fied 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 sub-
	     tracted 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
	     parentheses.

     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 con-
	     sidered in	the kernel space, and wrong space address is rejected
	     with an error message.  This modifier can be used only if it is
	     supported 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
	     behavior.

     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 spec-
	     ified 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 error message.

	     Warning: Attempts to watch	wired kernel memory may	cause unrecov-
	     erable error in some systems such as i386.	 Watchpoints on	user
	     addresses 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
	     occurs.  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
	     syntax).  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
	     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 proba-
	     bly do the	wrong thing.

     continue[/c]
     c[/c]   Continue execution	until a	breakpoint or watchpoint.  If the c
	     modifier 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 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
	     instruction 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
	     instruction 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
	     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.

     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
	     addresses for the process and not show other info.

     show registers[/u]
	     Display the register set.	If the u modifier is specified,	it
	     displays 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
	     topology.	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
	     complete 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,
	     another 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 archi-
	     tecture.

     halt    Halt the system.

     kill sig pid
	     Send signal sig to	process	pid.  The signal is acted on upon
	     returning 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
	     abbreviations.

VARIABLES
     The debugger accesses registers and variables as $name.  Register names
     are as in the ``show registers'' command.	Some variables are suffixed
     with numbers, 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 sym-
		  bol, which is	the address of the corresponding object.  `.'
		  and `:' can be used in the identifier.  If supported by an
		  object format	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
		  described above.

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)

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.

FreeBSD	10.1			August 6, 2007			  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | VARIABLES | EXPRESSIONS | HINTS | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=ddb&sektion=4&manpath=FreeBSD+7.0-RELEASE>

home | help