System Administration Commands                         obpsym(1M)



NAME
     obpsym - Kernel Symbolic Debugging for OpenBoot Firmware

SYNOPSIS
     modload -p misc/obpsym


DESCRIPTION
     obpsym is a kernel module that  installs  OpenBoot  callback
     handlers that provide kernel symbol information to OpenBoot.
     OpenBoot firmware user interface commands use the  callbacks
     to  convert  numeric  addresses  to  kernel symbol names for
     display purposes, and to  convert  kernel  symbol  names  to
     numeric literals allowing symbolic names to be used as input
     arguments to user interface commands.


     Once obpsym is installed, kernel symbolic names may be  used
     anywhere  at  the OpenBoot firmware's user interface command
     prompt in place of a literal (numeric) string. For  example,
     if  obpsym  is  installed,  the  OpenBoot  firmware commands
     ctrace and dis typically display symbolic names and  offsets
     in the form modname:symbolname ] offset. User interface Com-
     mands such as dis can be given a kernel symbolic  name  such
     as ufs:ufsmount instead of a numeric address.


     Placing the command


     forceload: misc/obpsym


     into the system(4) file forces the kernel module misc/obpsym
     to  be  loaded and activates the kernel callbacks during the
     kernel startup sequence.


     obpsym may be useful as  a  kernel  debugger  in  situations
     where other kernel debuggers are not useful. For example, on
     SPARC machines, if obpsym is loaded, you may be able to  use
     the  OpenBoot  firmware's ctrace command to display symbolic
     names in the stack backtrace after a watchdog reset.

  Kernel Symbolic Name Syntax
     The syntax for a kernel symbolic name is:


      [ module-name : ] symbol-name






SunOS 5.11          Last change: 13 Dec 2001                    1






System Administration Commands                         obpsym(1M)



     Where module-name is the name of the kernel module that  the
     symbol  symbol-name  appears in. A NUL module name is taken
     as "all modules, in no  particular  order"  by  obpsym.  The
     module  name  unix  is  equivalent to a NUL module name, so
     that conflicts with words defined in the firmware's  vocabu-
     lary can be avoided.


     Typically, OpenBoot firmware reads a  word  from  the  input
     stream  and  looks  the  word  up in its internal vocabulary
     before checking if the word is a literal. Thus, kernel  sym-
     bols,  such as reset may be given as unix:reset to avoid the
     unexpected side effect of the firmware finding and executing
     a matching word in its vocabulary.

FILES
     /etc/system

         system configuration information file


     /platform/platform-name/kernel/misc/obpsym




ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Availability                 SUNWcar                     
    


SEE ALSO
     kadb(1M), kernel(1M), modload(1M), modunload(1M),  uname(1),
     system(4), attributes(5)


WARNINGS
     Some OpenBoot firmware user interface commands may use  sys-
     tem resources incompatibly with the way they are used by the
     Unix kernel. These commands and the use of this feature as a
     kernel  debugger may cause interactions that the Unix kernel
     is not prepared to deal with. If this occurs, the Unix  ker-
     nel and/or the OpenBoot firmware user interface commands may
     react unpredictably and may panic the system, or may hang or



SunOS 5.11          Last change: 13 Dec 2001                    2






System Administration Commands                         obpsym(1M)



     may  cause  other  unpredictable results. For these reasons,
     the use of this feature  is  only  minimally  supported  and
     recommended  to  be  used only as a kernel debugger of "last
     resort".


     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.

NOTES
     platform-name can be found using the -i option of uname(1)


     obpsym is supported only on architectures that support Open-
     Boot firmware.


     On some systems, OpenBoot must be completely RAM resident so
     the  obpsym  symbol  callback  support  can  be added to the
     firmware, if the firmware doesn't include  support  for  the
     symbol callbacks. On these systems, obpsym may complain that
     it requires that "you must use ramforth to use this module".


     See the  for details on how to use the ramforth command, how
     to  place  the  command  into  nvramrc,  and how to set use-
     nvramrc? to true.  On  systems  with  version  1.x  OpenBoot
     firmware,  nvramrc  doesn't  exist, and the ramforth command
     must be typed manually after each reset,  in  order  to  use
     this module.


     Once installed, the symbol table callbacks can  be  disabled
     by using the following OpenBoot firmware command:


     0 0 set-symbol-lookup















SunOS 5.11          Last change: 13 Dec 2001                    3