usr/src/man/man1m/obpsym.1m

   1 '\" te
   2 .\"  Copyright 2001 Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH OBPSYM 1M "Dec 13, 2001"
   7 .SH NAME
   8 obpsym \- Kernel Symbolic Debugging for OpenBoot Firmware
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBmodload\fR \fB-p\fR misc/obpsym
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 \fBobpsym\fR is a kernel module that installs OpenBoot callback handlers that
  19 provide kernel symbol information to OpenBoot. OpenBoot firmware user interface
  20 commands use the callbacks to convert numeric \fIaddresses\fR to kernel symbol
  21 names for display purposes, and to convert kernel symbol names to numeric
  22 \fIliterals\fR allowing symbolic names to be used as input arguments to user
  23 interface commands.
  24 .sp
  25 .LP
  26 Once \fBobpsym\fR is installed, kernel symbolic names may be used anywhere at
  27 the OpenBoot firmware's user interface command prompt in place of a literal
  28 (numeric) string. For example, if \fBobpsym\fR is installed, the OpenBoot
  29 firmware commands \fBctrace\fR and \fBdis\fR typically display symbolic names
  30 and offsets in the form \fImodname:symbolname + offset.\fR User interface
  31 Commands such as \fBdis\fR can be given a kernel symbolic name such as
  32 \fBufs:ufs_mount\fR instead of a numeric address.
  33 .sp
  34 .LP
  35 Placing the command
  36 .sp
  37 .LP
  38 \fBforceload: misc/obpsym\fR
  39 .sp
  40 .LP
  41 into the \fBsystem\fR(4) file forces the kernel module \fBmisc/obpsym\fR to be
  42 loaded and activates the kernel callbacks during the kernel startup sequence.
  43 .sp
  44 .LP
  45 \fBobpsym\fR may be useful as a kernel debugger in situations where other
  46 kernel debuggers are not useful. For example, on SPARC machines, if
  47 \fBobpsym\fR is loaded, you may be able to use the OpenBoot firmware's
  48 \fBctrace\fR command to display symbolic names in the stack backtrace after a
  49 watchdog reset.
  50 .SS "Kernel Symbolic Name Syntax"
  51 .sp
  52 .LP
  53 The syntax for a kernel symbolic name is:
  54 .sp
  55 .LP
  56 \fB\fR [ \fImodule-name\fR \fB:\fR ] \fIsymbol-name\fR
  57 .sp
  58 .LP
  59 Where \fImodule-name\fR is the name of the kernel module that the symbol
  60 \fIsymbol-name\fR appears in. A \fINULL\fR module name is taken as "all
  61 modules, in no particular order" by \fBobpsym\fR. The module name \fBunix\fR is
  62 equivalent to a \fINULL\fR module name, so that conflicts with words defined in
  63 the firmware's vocabulary can be avoided.
  64 .sp
  65 .LP
  66 Typically, OpenBoot firmware reads a word from the input stream and looks the
  67 word up in its internal \fIvocabulary\fR before checking if the word is a
  68 \fIliteral\fR. Thus, kernel symbols, such as \fBreset\fR may be given as
  69 \fBunix:reset\fR to avoid the unexpected side effect of the firmware finding
  70 and executing a matching word in its vocabulary.
  71 .SH FILES
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fB/etc/system\fR\fR
  76 .ad
  77 .sp .6
  78 .RS 4n
  79 system configuration information file
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fB/platform/\fR\fIplatform-name\fR\fB/kernel/misc/obpsym\fR\fR
  86 .ad
  87 .sp .6
  88 .RS 4n
  89
  90 .RE
  91
  92 .SH SEE ALSO
  93 .sp
  94 .LP
  95 \fBkadb\fR(1M), \fBkernel\fR(1M), \fBmodload\fR(1M), \fBmodunload\fR(1M),
  96 \fBuname\fR(1), \fBsystem\fR(4), \fBattributes\fR(5)
  97 .sp
  98 .LP
  99 \fI\fR
 100 .SH WARNINGS
 101 .sp
 102 .LP
 103 Some OpenBoot firmware user interface commands may use system resources
 104 incompatibly with the way they are used by the Unix kernel. These commands and
 105 the use of this feature as a kernel debugger may cause interactions that the
 106 Unix kernel is not prepared to deal with. If this occurs, the Unix kernel
 107 and/or the OpenBoot firmware user interface commands may react unpredictably
 108 and may panic the system, or may hang or may cause other unpredictable results.
 109 For these reasons, the use of this feature is only minimally supported and
 110 recommended to be used only as a kernel debugger of "last resort".
 111 .sp
 112 .LP
 113 If a breakpoint or watchpoint is triggered while the console frame buffer is
 114 powered off, the system can crash and be left in a state from which it is
 115 difficult to recover. If one of these is triggered while the monitor is powered
 116 off, you will not be able to see the debugger output.
 117 .SH NOTES
 118 .sp
 119 .LP
 120 \fIplatform-name\fR can be found using the \fB-i\fR option of \fBuname\fR(1)
 121 .sp
 122 .LP
 123 \fBobpsym\fR is supported only on architectures that support OpenBoot firmware.
 124 .sp
 125 .LP
 126 On some systems, OpenBoot must be completely RAM resident so the \fBobpsym\fR
 127 symbol callback support can be added to the firmware, if the firmware doesn't
 128 include support for the symbol callbacks. On these systems, \fBobpsym\fR may
 129 complain that it requires that "you must use ramforth to use this module".
 130 .sp
 131 .LP
 132 See the  for details on how to use the \fIramforth\fR command, how to place the
 133 command into \fInvramrc\fR, and how to set \fIuse-nvramrc?\fR to \fBtrue\fR. On
 134 systems with version 1.x OpenBoot firmware, \fInvramrc\fR doesn't exist, and
 135 the \fIramforth\fR command must be typed manually after each reset, in order to
 136 use this module.
 137 .sp
 138 .LP
 139 Once installed, the symbol table callbacks can be disabled by using the
 140 following OpenBoot firmware command:
 141 .sp
 142 .LP
 143 \fB0 0 set-symbol-lookup\fR