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

FreeBSD Manual Pages


home | help
kadb(1M)		System Administration Commands		      kadb(1M)

       kadb - a	kernel debugger

       ok boot device_specifier	kadb [-d] [boot-flags]

       > b kadb	[-d] [boot-flags]

       select (b)oot or	(i)nterpreter: b kadb [-d] [boot-flags]

       select (b)oot or	(i)nterpreter: i kadb [-d] [boot-flags]

       kadb is an interactive kernel debugger with a user interface similar to
       adb(1), the assembly language debugger.

       kadb must be loaded prior to the	standalone program  it	is  to	debug.
       kadb  runs  with	 the same environment as the standalone	program, so it
       shares many resources with that program.	The debugger is	 cognizant  of
       and  able  to  control multiple processors, should they be present in a

       When kadb is started, it	requests the default filename  from  boot(1M),
       and  if	loaded non-interactively (without the -d option), it loads the
       default filename.

       On systems which	support	 both  32-bit  and  64-bit  operating  system,
       boot(1M)	 chooses  an  appropriate default filename for that system. If
       loaded interactively (by	specifying the -d option), kadb	 prompts  with
       the  default  filename, which can be changed before continuing. The de-
       fault filename can be specified	on  the	 boot(1M)  command  line.  See
       boot(1M)	for details.

       Before  loading the 64-bit kernel explicitly, review the	information in
       boot(1M)	for restrictions on running the	64-bit kernel on certain  con-

       Unlike  adb(1),	kadb runs in the same supervisor virtual address space
       as the program being debugged, although it maintains  a	separate  con-
       text.   The  debugger runs as a co-process that cannot be killed	(no :k
       command as in adb) or rerun (no :r command as in	adb). There is no sig-
       nal  control  (no  :i, :t, or $i	commands as in adb), although the key-
       board facilities	(CTRL-C, CTRL-S, and CTRL-Q) are simulated.

       In the case of the UNIX system kernel, the keyboard abort sequence sus-
       pends kernel operations and breaks into the debugger. This behavior may
       be disabled by way of the kbd(1)	command	and may	not be the current de-
       fault on	all systems. See kb(7M)	for more information.

       As  the	kernel is composed of the core image file and the set of load-
       able modules already in memory, kadb has	the  capability	 of  debugging
       all  of	these by traversing special data structures. kadb makes	use of
       this feature to allow it	to reference any kernel	data  structure,  even
       if it resides in	a loadable module. kadb	sets the -d flag by default so
       the program being debugged can tell it is being watched.	If  this  flag
       is not given, kadb loads	and immediately	runs the default kernel	.

       Most  adb(1)  commands  function	in kadb	as they	do in adb. As with adb
       -k, $p works when debugging kernels. The	verbs ?	and /  are  equivalent
       in kadb,	as there is only one address space in use.

       The  keyboard abort sequence is L1+A on keyboards with an <L1> key, and
       F1+A on keyboards with no <L1> key. On serial lines, the	default	 abort
       sequence	 is  a	BREAK  signal, but this	can be changed to the sequence
       ``carriage return, tilde, control-B'' using:

       kbd -a alternate

       See kbd(1).

       Once aborted, kadb responds with	the following:

	      where cpu	is the number of the CPU on which  kadb	 is  currently

       The following options are supported:

       -d    Interactive  startup.  If specified, kadb stops after loading and
	     displays the kadb:	prompt,	followed by the	name  of  the  default
	     program to	debug.

	     The user may either press RETURN to debug the default program, or
	     BACK SPACE	followed by the	name of	another	program	to debug.

       The following operands are supported:

	     Specifies boot flags as arguments to kadb.	 The  specified	 boot-
	     flags  are	passed to the program being debugged. See boot(1M) for
	     available boot-flags.

   SPARC Only
	     Specifies the device from which to	load. See monitor(1M).

   Kernel Macros
       As with adb(1), kernel macros can be used with kadb, but	they cannot be
       read from a file	at runtime. Use	the kadb $M command to list all	of the
       built-in	kadb macros.

       kadb reads commands from	the standard input and displays	 responses  on
       the standard output. kadb supports the majority of the adb(1) commands.
       kadb does not support the following adb commands: :k, :r,  :i,  :t,  or
       $i. See adb(1).

       Additionally, kadb supports the following commands:

       [     Performs the same function	as :e in adb(1), but requires only one
	     keystroke and no RETURN (ENTER on IA based	systems).

       ]     Performs the same function	as :s in adb(1), but requires only one
	     keystroke and no RETURN (ENTER on IA based	systems).

       :a    Sets  a hardware access (read or write) breakpoint	using the pro-
	     cessor hardware facilities. The syntax and	action for  this  com-
	     mand is the same as the :b	command	in adb,	with the following ex-

		o  The breakpoint triggers if any bytes	 from  the  breakpoint
		   for	length bytes are being accessed. See $l	below for set-
		   ting	the length of a	hardware breakpoint.

		o  Breakpoints should be aligned for the length	specified. Any
		   address  is	valid  for  length 1. Addresses	divisible by 2
		   should be used for length 2 (short).	Addresses divisible by
		   4 should be used for	length 4 (int).

		o  Detection  of  an access breakpoint occurs after completion
		   of the instruction that caused it.

		o  There are a limited number (4) of hardware breakpoint  reg-
		   isters, and,	when set, this uses one.

		o  As  this  breakpoint	does not modify	memory locations, this
		   command will	work on	locations that are not in core at  the
		   time	the breakpoint is set.

       @fmt  Used in the same manner as	the adb	/ and ?	commands. Specify @ as
	     a physical	memory address as opposed to the  normal  virtual  ad-
	     dress. Specify fmt	as any of the formats used with	the adb	/ com-
	     mand. This	command	is useful for displaying memory	that  may  not
	     be	 mapped,  for  example,	kernel page tables or buffers used for
	     DMA by device drivers.

       function:: call arg1, arg2, arg3, ...
	     Invokes kernel functions with 0 or	 more  arguments.  Using  this
	     command results in	a response such	as:

	     retval = function(arg1,arg2,arg3,...);

	     where  retval  is	the return value of the	function. This feature
	     can be error prone, as functions may have side effects that cause
	     failures if the kernel is continued.

       :p    Sets  a hardware access (read or write) breakpoint	using the pro-
	     cessor hardware facilities	when an	instruction at	the  specified
	     address  is  run.	The $l operation has no	effect on this type of
	     breakpoint. This breakpoint occurs	before the instruction is exe-

       :P    Works as :a, but this command will	only breakpoint	when an	access
	     is	made to	the address in IA I/O space. See :a.

       :w    Sets a write hardware access breakpoint using the processor hard-
	     ware facilities.

	     Sets  the	default	data length for	an access or write breakpoint.
	     length can	be set to 1 for	byte, 2	for short, and 4 for int  word
	     accesses.	If   length  is	not specified, 1 byte is assumed. Once
	     set, this value affects any newly	set  access  or	 write	break-
	     points, but does not affect ones set before this operation.

       $b    Displays  two  additional columns that adb	does not. The first is
	     the type column which indicates soft for a	normal breakpoint, ac-
	     cess  for	an access hardware breakpoint, write for a write hard-
	     ware breakpoint, and inst for an instruction hardware breakpoint.
	     The  second  is  the len column which for access and write	break-
	     points indicate the length	of the operation to break on.

       $q    Gives control to the boot prom, from which	 you  may  reboot  the

       cpu:x Switches  the  active CPU to cpu. Thereafter, commands such as $r
	     and $c displays the registers and stack of	the new	CPU, cpu.

	     Inputs a byte for display from port. port is an address-specified
	     I/O port.	For example, 330:i inputs from address port 330.

	     Same as the :i command. See :i.

	     Inputs two	bytes for display from port. port is an	address-speci-
	     fied I/O port.

	     Inputs four bytes for display from	port. port is an address-spec-
	     ified I/O port.

	     Outputs  a	 byte  to port.	port is	an address-specified I/O port.
	     [address],[data]:o	outputs	the value data to  address  I/O	 port.
	     For example, 330,80:o outputs 80 to address port 330.

	     Same as the :o command. See port,data:o.

	     Outputs two bytes to port.	port is	an address-specified I/O port.

	     Outputs  four  bytes  to  port.  port is an address-specified I/O

       $q    Prompts the user with:

	     Type 'y' if you really want to reboot.

	     Responding	with a y or Y causes the system	to reboot.  Responding
	     with  anything  other than	a y or Y returns control to  kadb. Use
	     this feature when you cannot press	the reset switch on  your  ma-
	     chine.  Because  using  $q	 may result in data loss, this command
	     should only be used when you would	 press	the  reset  switch  or
	     power off your system.

   Online Help Commands
	     Displays the formats of kadb commands and extended	commands.

       ::?   Same as the ::help	command. See ::help.

	     Displays  additional information about commonly used commands and
	     provides an explanation of	data formats.

   Scroll Control Feature
	     A common problem with using kadb is that scrolling	 is  sometimes
	     too  fast and that	CTRL-s and CTRL-q are inexact controls.	A con-
	     ditional scroll control feature similar to	more(1)	has been added
	     to	kadb. To enable	this feature, the user specifies the number of
	     lines to be displayed, followed by	::more.	For example, the  com-
	     mand  14::more displays 14	(current radix)	lines, followed	by the
	     --More-- prompt. At this prompt, press: ENTER or RETURN  to  dis-
	     play  one	more line. Press c, C, or CTRL-c to interrupt the dis-
	     play. Press any other key to display the next num number of spec-
	     ified lines (14 in	this example). The command ::more displays the
	     current setting for the number of lines that kadb displays	before
	     printing the --More-- prompt. The initial scroll control value of
	     this feature is 0,	meaning	that scrolling is disabled.  Once  en-
	     abled, the	0::more	command	disables the scroll control feature.

   Deferred Breakpoint Feature
       Since  the  kernel is dynamically loaded, not all modules may be	loaded
       when a breakpoint is set	kadb can set deferred breakpoints  which  will
       be  dynamically	inserted  when the corresponding module	is loaded. The
       module and the location must both be specified when referring to	a  de-
       ferred breakpoint, as follows:


       This  syntax  is	implemented for	kadb only and uses existing breakpoint
       commands	(for example, ufs#ufs_open:b or	ufs#ufs_open+4,5:b).

       If the module has been loaded, kadb attempts to find the	symbol in  the
       module  specified.  If  kadb finds the symbol, it sets a	regular	break-
       point. If it does not find the symbol, it generates  an	error  message
       and returns to the command line without setting a breakpoint.

       If  kadb	 fails to find the module on the list of currently loaded mod-
       ules, it	does not resolve the location. Instead,	it sends a message  to
       the user	and sets a deferred breakpoint.

       When  the  specified  module is loaded, kadb tries to resolve the loca-
       tion. If	the location can be resolved, the deferred breakpoint is  con-
       verted  to a regular breakpoint.	If kadb	cannot resolve the location, a
       message is sent to the user, and	kadb halts execution.  In  this	 case,
       kadb  does not convert the deferred breakpoint to a regular breakpoint;
       it removes it from the breakpoint table.	The user may then  re-enter  a
       correct	breakpoint.  Strict scoping is enforced, so kadb does not look
       at any other module than	the one	specified with the location.

       When specifying a deferred breakpoint in	which the module name contains
       a  hyphen,  you must escape the hyphen. For example, for	a module named
       pci-ide,	enter:


       The output from the the $b command indicates whether the	breakpoint  is
       of type "deferred" (defr) or is another type.

	     primary debugger path

	     alternative debugger path for some	platforms

	     primary default 32-bit kernel

	     alternative default 32-bit	kernel for some	platforms

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWcar			   |

       adb(1), more(1),	uname(1), boot(1M), kernel(1M),	attributes(5), kb(7M)

   SPARC Only
       kbd(1), monitor(1M), obpsym(1M)

       When  there is no current command or format, kadb comments about	syntax
       errors, abnormal	termination of commands, and the like.

   SPARC Only
       On a SPARC based	system,	kadb cannot reliably single-step over instruc-
       tions which change the processor	status register.

   SPARC and IA
       If a breakpoint or watchpoint is	triggered while	the console frame buf-
       fer is powered off, the system can crash	and be left in	a  state  from
       which  it  is  difficult	to recover. If one of these is triggered while
       the monitor is powered off, you will not	be able	to  see	 the  debugger

       platform-name  can  be found using the -i option	of uname(1). hardware-
       class-name can be found using the -m option of uname(1).

SunOS 5.9			  22 Mar 2001			      kadb(1M)


Want to link to this manual page? Use this URL:

home | help