*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> ikdebug (8)              



NAME    [Toc]    [Back]

       ikdebug - Integrated kernel debugger

DESCRIPTION    [Toc]    [Back]

       The ikdebug debugger is the integrated interactive mode of
       the kdebug kernel debugger. It provides  interactive  symbolic
  kernel  debugging without the need of a second host
       system to run dbx or kdbx. Its command syntax  is  derived
       from the Mach microkernel debugger ddb.

   Configuration    [Toc]    [Back]
       This  debugger  is  included  as part of the kdebug kernel
       debugger module. It is configured by enabling  the  kdebug
       module  in your system configuration file. When the kernel
       is booted with this debugger, the following  message  will
       be  displayed during boot: Loading vmunix symbol table ...
       [XXX bytes]

       If the kernel is booted with the k flag, the standard kdebug
 behavior is activated.

       If the kernel is booted with the e flag, the kernel enters
       the interactive debugger. This allows  breakpoints  to  be
       set  early  in the bootstrap process. The normal bootstrap
       sequence is resumed using the debugger continue command.

       If neither flag is specified, the  kernel  boots  normally
       and  the  interactive debugger is available through a console
 escape sequence described in the next section.

       The following kernel tunable parameters are available: The
       console  escape  string is defined by this parameter. This
       string defaults to "" (null) which disables  the  feature.
       It  may  be  overridden  by  adding  the  following to the
       /etc/sysconfigtab file:

                     kdebug_escape = fred

              As this is the value  with  which  you  invoke  the
              debugger,  the  string  should be easy to remember.
              Avoid strings that might cause you to  accidentally
              invoke the debugger.

              Alternatively,  the escape string can be changed at
              runtime by running the following command as root: #
              sysconfig -r kdebug kdebug_escape=ethyl

              Also, the console escape can be disabled by setting
              the escape sequence to the null  string  using  the
              following  command:  #  sysconfig  -r  kdebug  kdebug_escape=
 Using this parameter, the debugger  can
              be  configured  to stop automatically when a kernel
              panic occurs. By default this feature is  disabled.
              This  parameter  controls whether the debugger uses
              the kernel console driver or console firmware callbacks
  to perform I/O to the console.  A value of 1
              selects the kernel console driver while value of  0
              selects  console  firmware  callbacks. The debugger
              automatically selects the appropriate value depending
  on  the  system type.  This parameter controls
              the debugger use of the console SAVETERM  function.
              A  value  of  1  causes the SAVETERM function to be
              called on debugger entry while a value  of  0  disables
  the SAVETERM function call. This tuneable is
              only meaningful when a graphics console is  in  use
              and  the parameter kdebug_unix_console is set to 0,
              enabling console firmware callbacks.

   Entering and Exiting    [Toc]    [Back]
       The debugger is  entered  automatically  during  a  kernel
       panic,  after  any  system dump is generated, and before a
       reboot. To continue with the  reboot  operation,  use  the
       continue  or quit commands. The current thread will be the
       one that generated the panic.  You  may  also  invoke  the
       debugger manually. If you are logged in to the system console
 on a serial line, typing  the  kernel  tuneable  kdebug_escape
  string  will  drop  you into the debugger. The
       debugger escape sequence is recognized at all times.

       You can exit the debugger by entering  the  continue  command,
 or the command abbreviation c.

   Interacting With ikdebug    [Toc]    [Back]
       When you enter the debugger (or if it is invoked automatically),
 ikdebug places you in the context of the task  and
       thread  that  were active just before the debugger assumed
       control.  Note that all system activity on the current CPU
       is  suspended  until you enter a command to the debugger's

       Once invoked, the debugger's general  command  set  allows
       you  to  examine or modify register and address space contents.
 You can also call functions, set breakpoints,  execute
  instructions  a  step  at  a time, and perform stack
       trace operations.

       The debugger provides the abstraction of a  current  location,
 which, in keeping with UNIX style, is referred to as
       dot (.).  This dot represents the address  that  the  next
       command  will  use  if  you  do  not  provide an alternate

       The examine and write commands 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. See the  Synopsis  section
       for an explanation of the command syntax.

   Address Space Issues    [Toc]    [Back]
       No  matter  how  the  debugger is invoked, you always have
       access to the kernel's address space. You also have access
       to a single user address space.  If the system was executing
 in the context of a  user  task  just  before  ikdebug
       assumed  control,  that  task is the current task.  Otherwise,
 ikdebug sets the current task to the user task  that
       was  last  executed.  In either case, the address space of
       the current task is the one available by default.

       You may access a non-current user task's address space  by
       naming  a  thread  belonging to that task. You can use the
       "show" facility to determine such a task's identity.

       In general, the accessibility of a given  virtual  address
       depends upon whether or not the corresponding page resides
       in main memory. If the page is not resident, it is  likely
       that you will not be able to access the contents.

   Multipage Output Facility    [Toc]    [Back]
       The  ikdebug  debugger  has a feature similar to the shell
       command more for managing the display of  multipaged  output.
   If  an  output  line  exceeds the number set in the
       $lines variable, it displays the message  --db_more--  and
       waits  for  a  response.  Valid  responses are as follows:
       Press the Spacebar to display  one  more  page  Press  the
       Return  key  to  display  one more line Press the Q key to
       abort the current command, and return to the command input

       Any  other  character  displays  a single line, as for the
       Return key.

   Commands and Parameters    [Toc]    [Back]
       The general command syntax is: command [/modifier] address

       Specifying  address sets dot to the address.  Omitting the
       address uses the default address, dot. A missing count  is
       taken  to be 1 for printing commands or infinity for stack
       traces. The string !!  repeats the previous  command,  and
       the string "." repeats from the address next with the same
       count and modifiers.

       Multi-threaded debugging is supported by ikdebug.  Threadspecific
 breakpoints can be set, and the address space and
       registers of a non-current thread can be examined or modified
 if supported by machine dependent routines. For example,
 the command: break/t mach_msg_trap $task11.0

       sets a breakpoint at mach_msg_trap for the first thread of
       task 11 listed by a show all threads command.

       In the example, $task11.0 is translated to the corresponding
 thread structure's address by the variable translation
       mechanism  described  later  in  this reference page. If a
       default target thread is set in the variable $thread,  the
       $task11.0  argument  can  be omitted.  In general, if t is
       specified as a modifier of a command line,  the  specified
       thread  (or the current default target thread) is used for
       the command instead of the current thread  --  the  thread
       that  was running when ikdebug was entered. The t modifier
       in a command line is not valid in  evaluating  expressions
       in  a command line.  If you want to get a value indirectly
       from a specific thread's address space or  access  to  its
       registers  within  an  expression,  you  have to specify a
       default target thread in advance, and to use the :t  modifier
 immediately after the indirect access or the register
       reference as follows: set $thread $task11.0 print $a0:t

       The following are the commands accepted by ikdebug.   Each
       command  may  be  specified using the shortest unambiguous
       prefix of its name. In addition, a  few  commands  may  be
       given  as  a  single letter, even though this is not unambiguous.
 Commands specifiable with one  letter  are  indicated
  by  putting  the letter in parens after the command
       name, as in examine(x).  Enables you to set  a  breakpoint
       at  addr.   If  count  is supplied, the debugger continues
       count-1 times before stopping at the breakpoint.   If  the
       breakpoint  is set, a breakpoint number is printed with #.
       This number can be used in deleting the breakpoint.  Set a
       breakpoint  only  for  a  specific  thread.  The thread is
       specified by the thread parameter, or the  default  thread
       is  used if the parameter is omitted.  Set a breakpoint at
       a user-space address. It may be combined with a  t  or  T.
       option  (plus  a  thread  argument)  to specify an address
       space other than the current one.  This  option  is  never
       required.  Without it, supplying a user-space address will
       produce a warning, but will not cause an  error.  However,
       with  the  option,  a  kernel-space  address will cause an
       error. This option can be used only if it is supported  by
       machine  dependent  routines.   Set  a breakpoint only for
       threads in a specific task.   It  is  like  the  t  option
       except  that the breakpoint is valid for all threads which
       belong to the same task as the  specified  target  thread.
       Set  a breakpoint in shared user space address. It is like
       the u option, except that the breakpoint is valid for  all
       threads  which  share the same address space even if the t
       option is specified.  The t option is used only to specify
       the  target  shared  space.  Without the t option, u and U
       have the same meanings.  The U option is useful  for  setting
  a user space breakpoint in non-current address space
       with the t option such as in an emulation  library  space.
       This option can be used only if it is supported by machine
       dependent routines.


              Note that if user text  is  shadowed  by  a  normal
              user-space debugger, user-space breakpoints may not
              work correctly.  Call the function named func passing
  it the parameters in arg-list. After the function
 runs, the debugger  will  display  its  return

              A  single exclamation point may be used as a shorthand
 for call, for example !rpcc()".  Continue execution
  until  a  breakpoint.  If c is given, count
              instructions while  executing.  Some  systems  will
              also count loads and stores.

              Note  that,  when  counting, the debugger is really
              silently single-stepping.  This means  that  the  c
              option  can  easily  cause  unexpected behavior, by
              single-stepping through low-level code.  On an  SMP
              system,  switch  the current CPU.  This affects the
              identity of the current context (task plus thread).
              A CPU must already be in the debugger to become the
              current CPU. If the command targets a CPU on  which
              ikdebug  is inactive, the debugger ignores the command
 and  prints  an  error  message.   Delete  the
              breakpoint.  The target breakpoint can be specified
              by a breakpoint number with #, or by addr as specified
  in  the break command.  Display the addressed
              locations according to the formats in the modifier.
              Multiple  modifier  formats  display multiple locations.
 If no format is specified, the last  formats
              specified  for this command is used.  Address space
              other than that of the current thread can be specified
  with  the t option in the modifier and thread
              parameter. The format characters  are:  examine  by
              bytes  (8  bits)  examine  by  half words (16 bits)
              examine by long words (32  bits)  examine  by  quad
              words (64 bits) print the location being displayed,
              symbolically if possible; any symbol  close  enough
              to  the  location  will  be used print the location
              being displayed,  symbolically  if  possible;  only
              procedure  names  will be used, and if possible the
              source-level file name and line number of the definition
  will  be  output  display  in  unsigned hex
              display in unsigned octal display in signed decimal
              display in unsigned decimal display in current output
 radix ($oradix), signed display low 8 bits as a
              character. Non-printing characters are displayed as
              an octal escape code (\000).  display the null-terminated
  string at the location. Non-printing characters
 are displayed as octal escapes.  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.  display as an instruction
              display as an instruction including  register  contents
  Displays  detailed  help, a summary or usage
              for the specified command. If no command is  specified,
 all commands are displayed.  Display detailed
              help for the specified command  Display  a  command
              summary for the specified command Display a command
              usage for the specified command Print addrs according
  to the modifier character.  Valid formats are:
              a A x o d u r c. (These are the same formats as for
              the  examine command, except that the u format here
              corresponds to the u format there.)  If no modifier
              is specified, the last one specified to it is used.
              Each addr  argument  can  be  a  string,  which  is
              printed  literally,  with  printf(3)  style  escape
              sequences.  For example, print/x "pc = " $pc  "\nra
              = " $ra "\n"

              will  print the line pc = xxxxxx ra = yyyyyy Search
              memory for a value.  This  command  might  fail  in
              interesting  ways if it does not find the searchedfor
 value.  This is because ikdebug does not always
              recover  from  touching  bad  memory.  The optional
              count argument limits the search.   Set  the  named
              variable  or register with the value of expr. Valid
              variable names are described  below.   Single  step
              count  times. If -p option is specified, print each
              instruction at each step. Otherwise, only print the
              last instruction.


              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 (i860), stepping through code  executed
  by  interrupt  handlers  is not recommended.
              Stack  trace.   The  /u  option  causes  traces  to
              include  stack  frames  in  user space; if omitted,
              traces include only frames in kernel space.  If the
              /t option is specified, it shows the stack trace of
              the specified thread or a  default  target  thread.
              Otherwise,  it shows the stack trace of the current
              thread from the frame address specified by a parameter
  or  from the current frame.  The count is the
              number of frames to be traced.   If  the  count  is
              omitted, all frames are printed. The /T option outputs
 a trace for all threads within a task. In this
              case  only,  <thread_addr>  may  refer  either to a
              thread or to a task. To begin (or  resume)  tracing
              the threads of a task at a thread other than thread
              0, just name the desired thread (as in  $task4.27).


              If  the  target  thread's  stack is not in the main
              memory at that time, the  stack  trace  will  fail.
              User space stack trace is valid only if the machine
              dependent code supports it.  Write the  expressions
              at succeeding locations. The write unit size can be
              specified in the modifier with a letter b (byte), h
              (half  word),  l  (long  word),  or  q  (quad word)
              respectively. If omitted,  long  word  is  assumed.
              Target  address space can also be specified with /t
              option in the modifier and thread parameter. If the
              target  is  a  user  task,  you must include the /u
              option in the command.


              Since there is no  delimiter  between  expressions,
              strange  things  may  happen. It is best to enclose
              each expression in parentheses.   Examine  forward.
              It executes an examine command with the last specified
 parameters, updated so that the location  following
   the  last  location  previously  displayed
              becomes the start address for the current  command.
              Examine  backward.  It  executes an examine command
              with the last specified parameters, updated so that
              the  start  address  of the previous command, minus
              the number of  items  displayed  by  that  command,
              becomes  the start address for the current command.
              (This displays a "window" consisting of  the  items
              immediately  preceding the last group of items output.)

   Show Commands    [Toc]    [Back]
       The debugger will display a number of interesting  kernellevel
 data structures.  The commands to do so all have the
       form show <name>, where <name> is a  tag  related  to  the
       data structure in question. For some common cases where it
       is useful to inspect all instances of  a  given  structure
       with  a  single command, the debugger provides commands of
       the form: show all <name>

       Unless  otherwise  indicated,  each  show  command  simply
       prints the interesting members of the structure indicated.
       Each member is labeled by a name that is at least  related
       to  its  C-language  name.   Display  information  for the
       thread specified by addr. If addr is omitted,  information
       on  the  current  thread  is  displayed. If no modifier is
       given, the information displayed for the thread is its ID,
       the address of the corresponding thread structure, and the
       state of the thread. The state is output as some  combination
  of  these  letters:  Thread  is runnable.  Thread is
       waiting (has blocked itself); following the  state  output
       will  appear the address of the event on which it is waiting,
 or zero, if no event was asserted.   Thread  is  suspended.
   Thread  is swapped out.  Thread is waiting uninterruptibly;
 if W appears without N, the  wait  is  interruptible.
  Thread has used the floating-point unit.

              If  /l  is given, more information is displayed for
              the thread: the thread's  ID  the  address  of  the
              thread   structure  the  state  of  the  thread  as
              explained above the swap state of the thread, indicated
  by one of the letters: Activation is unswappable.
  Activation is swapped  in.   Activation  is
              being swapped out.  Activation is being swapped in.
              Activation is swapped out.

              The letter will be followed by a T if the  thread's
              task is being swapped, otherwise a hyphen will follow.
  the base of the  thread's  kernel  stack  the
              thread's  suspend count the priority of the thread,
              together with its scheduling policy,  one  of:  for
              first-in/first-out (no pre-emption) for round-robin
              (pre-empt only within priority level) for timesharing
  (degrade  priority  as  thread  executes)  the
              event, if any, on which the thread is waiting  Display
  information  on all tasks and threads. In all
              cases, this command shows task and thread identification
 numbers, which can be used to specify a task
              or an thread symbolically in  other  commands  (via
              task  variables). The numbers are valid only in the
              current debugger session; if  system  execution  is
              resumed,  they  may change. The currently-executing
              thread is distinguished from others by  a  #  after
              its id instead of :.

              With  no  options  given, this command displays the
              same information for each task and thread  as  show
              task  and  show thread would do, when they're given
              with no arguments. The /u option expands the output
              shown  for each task just as it does for show task.
              The /l option expands the  output  shown  for  each
              thread  just  as  it  does  for show thread or show
              task.  For each task, perform show task.  Show  all
              breakpoints  currently  set.  The  information displayed
 for each breakpoint is: the ID  (number)  of
              the  breakpoint  the  address  space (kernel, userspace
 or taskn) in which the breakpoint is set  the
              scope  of  the  breakpoint,  one  of  all (if it is
              global), taskn (if it is specific to task id n), or
              taskn.m  (if  it is specific to thread m of task id
              n) the count  specified  when  the  breakpoint  was
              established  the address at which the breakpoint is
              set Display the register set. Target thread can  be
              specified  with t option and thread parameter. If u
              option is specified,  it  displays  user  registers
              instead of kernel or currently saved one.


              The  support  of  t  and  u  option  depends on the
              machine.  If not supported,  incorrect  information
              will  be displayed.  For each processor set defined
              in the system, displays  each  occupied  run  queue
              (i.e.,  each  run  queue  where at least one thread
              resides).  For each run queue, the  queue  priority
              is  output,  followed by the task plus thread ID of
              each thread on that queue.  Display information for
              the  task  specified  by <addr>, or for the current
              task if <addr> not given. Information is also  displayed
  for  all threads in the task. If no options
              are given, the information displayed for  the  task
              is  its  ID,  the address of the corresponding task
              structure, and the number of threads the task  contains;
 information displayed for each thread is the
              same as for show threads with no options given.

              If the /l option is given, this command shows  more
              information for each thread -- the same information
              as show threads will with /l given.

              If the /u option is given, this command shows  more
              information  for  the  task itself: the task ID the
              address of the task structure the  address  of  the
              task's  map  (vm_map_t) the total number of threads
              in the task the  number  of  resident  (swapped-in)
              threads  in  the  task the task's suspend count the
              task's priority the task's swap state, indicated by
              one  of  the  letters: Task is swapped in.  Task is
              swapped out.  Task is being swapped out.   Task  is
              being  swapped  in.  Task is unswappable.  any UNIX
              process information available for the task  Display
              the current values of all debugger variables.

   Variables    [Toc]    [Back]
       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 u and t
       modifier to indicate user register and that of  a  default
       target  thread instead of that of the current thread, such
       as $eax:tu.

       Built-in variables currently supported  are:  Set  if  the
       console device will "autowrap" (i.e., insert a CR/LF pair)
       when its output width  is  exceeded.   Controls  automatic
       completion  of symbol names (see below).  If zero, completion
 is disabled. Otherwise, controls at  what  point  all
       the current alternatives for completion are displayed. (If
       more than this number of alternatives exist, they won't be
       displayed.)   The  number  of lines.  It is used by "more"
       feature.  Addresses are printed as 'symbol'+offset  unless
       offset is greater than maxoff.  The width of the displayed
       line.  Input radix Output radix Tab stop width.   Task  or
       thread  structure  address.   The  xx  and yy are task and
       thread  identification  numbers  printed  by  a  show  all
       threads command respectively.  This variable is read only.
       The value of xx can  be  1  to  10.   The  default  target
       thread.   The  value  is  used  when t option is specified
       without explicit thread  structure  address  parameter  in
       command  lines  or  expression evaluation.  Work variable.
       The value of xx can be 0 to 31.

   Expressions    [Toc]    [Back]
       Almost all expression operators in C are supported  except
       ~,  ^, and unary &. However, operator precedence is decidedly
 different. From lowest to highest, precedence  levels
       are:  logical or (||) logical and (&&) relational ops (==,
       !=, <, <=, >=, >) bitwise shift (<<, >>) "additive" (+, -,
       |) "multiplicative" (*, /, %, #, &) unary (+, -, !)

       Special  rules  in  ikdebug  are: name of a symbol.  It is
       translated to the address (or value) of it.   The  characters
  fullpoint (.) and colon (:) can be used in the identifier.

              If supported by an object format dependent routine:

              [<file_name>:]<variable>    <file_name>[:<line_number>]

              can all be accepted as a symbol.

              By default, symbols may be specified using a unique
              (or near-unique) prefix.  When  a  symbol  name  is
              being  entered,  the  debugger will attempt to complete
 it on receipt of a <tabcharacter. Any  unique
              substring  of  the name that follows the portion so
              far specified will be completed immediately. If the
              name  is  not  totally specified after that completion,
 then the debugger will display all  the  symbols
  that match the name so far completed, so long
              as the count of matching symbols  does  not  exceed
              the  value  of  the $completion variable.  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.   register name or variable.
              It is translated to the value of it. It may be followed
  by  a : and modifiers as described above.  a
              binary operator which rounds up the left hand  side
              to  the next multiple of right hand side.  indirection.
  It may be followed by a ':' and modifiers as
              described above.

SEE ALSO    [Toc]    [Back]

       Commands: dbx(1), kdbx(8)

       Kernel Debugging

[ Back ]
 Similar pages
Name OS Title
ddb OpenBSD kernel debugger
symmon IRIX kernel symbolic debugger
ddb FreeBSD interactive kernel debugger
idbg IRIX kernel debugger print utility
SSL_COMP_add_compression_method OpenBSD handle SSL/TLS integrated compression methods
speedshop IRIX an integrated package of performance tools
SSL_COMP_add_compression_method NetBSD handle SSL/TLS integrated compression methods
isdn IRIX Integrated Services Digital Network
SSL_COMP_add_compression_method Tru64 Handle SSL/TLS integrated compression methods
auth.adm HP-UX activate, deactivate, or query about HP-UX Integrated Login
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service