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 pro-
     cessors, should they be present in a system.

     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 default  filename  can  be
     specified  on  the  boot(1M)  command line. See boot(1M) for

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

     Unlike adb(1), kadb runs  in  the  same  supervisor  virtual
     address  space  as  the  program being debugged, although it
     maintains a separate context.  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 signal  control
     (no :i, :t, or $i commands as in adb), although the keyboard
     facilities (CTRL-C, CTRL-S, and CTRL-Q) are simulated.

     In the case of the UNIX system kernel,  the  keyboard  abort
     sequence  suspends  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 default on all systems.
     See kb(7M) for more information.

     As the kernel is composed of the core image file and the set
     of loadable modules already in memory, kadb has the capabil-
     ity 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 executing.


     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  speci-
           fied  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


  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
           x86 based systems).

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

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

              o  The breakpoint triggers if any  bytes  from  the
                 breakpoint  for length bytes are being accessed.
                 See  $l  below  for  setting  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  registers,  and, when set, this uses

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

     @fmt  Used in the same manner as the adb / and  ?  commands.
           Specify  @  as a physical memory address as opposed to
           the normal virtual address. Specify fmt as any of  the
           formats  used  with the adb / command. 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  contin-

     :p    Sets a hardware  access  (read  or  write)  breakpoint
           using   the  processor  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 x86 I/O
           space. See :a.

     :w    Sets a write hardware access breakpoint using the pro-
           cessor hardware 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 breakpoints, 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,  access  for  an  access  hardware
           breakpoint, write for a write hardware breakpoint, and
           inst  for  an  instruction  hardware  breakpoint.  The
           second  is  the  len column which for access and write
           breakpoints indicate the length of  the  operation  to
           break on.

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

     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-specified I/O port.

           Inputs four bytes for display from port.  port  is  an
           address-specified 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 port.

     $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 machine. 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

     ::?   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 conditional 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
           command 14::more displays 14  (current  radix)  lines,
           followed  by  the  --More--  prompt.  At  this prompt,
           press: ENTER or RETURN to display one more line. Press
           c,  C,  or  CTRL-c to interrupt the display. Press any
           other key to display the next num number of  specified
           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
           enabled, the 0::more command disables the scroll  con-
           trol 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  deferred  break-
     point, as follows:


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

     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 breakpoint. 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  modules,  it does not resolve the location. Instead,
     it sends a message to the user and sets  a  deferred  break-

     When the specified module is loaded, kadb tries  to  resolve
     the  location. If the location can be resolved, the deferred
     breakpoint is converted 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  con-
     vert  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  speci-
     fied 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  attri-

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


     adb(1),  more(1),  uname(1),  boot(1M),  kernel(1M),  attri-
     butes(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  instructions  which change the processor status regis-

  SPARC and IA
     If a breakpoint or watchpoint is triggered while the console
     frame  buffer  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 output.


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

Man(1) output converted with man2html