1obpsym(1M)              System Administration Commands              obpsym(1M)
2
3
4

NAME

6       obpsym - Kernel Symbolic Debugging for OpenBoot Firmware
7

SYNOPSIS

9       modload -p misc/obpsym
10
11

DESCRIPTION

13       obpsym is a kernel module that installs OpenBoot callback handlers that
14       provide kernel symbol information to OpenBoot. OpenBoot  firmware  user
15       interface  commands  use  the callbacks to convert numeric addresses to
16       kernel symbol names for display purposes, and to convert kernel  symbol
17       names  to  numeric literals allowing symbolic names to be used as input
18       arguments to user interface commands.
19
20
21       Once obpsym is installed, kernel symbolic names may be used anywhere at
22       the  OpenBoot  firmware's  user  interface command prompt in place of a
23       literal (numeric) string. For example,  if  obpsym  is  installed,  the
24       OpenBoot  firmware  commands  ctrace and dis typically display symbolic
25       names and offsets in the form modname:symbolname + offset. User  inter‐
26       face  Commands  such as dis can be given a kernel symbolic name such as
27       ufs:ufs_mount instead of a numeric address.
28
29
30       Placing the command
31
32
33       forceload: misc/obpsym
34
35
36       into the system(4) file forces the  kernel  module  misc/obpsym  to  be
37       loaded  and  activates  the  kernel callbacks during the kernel startup
38       sequence.
39
40
41       obpsym may be useful as a kernel debugger  in  situations  where  other
42       kernel  debuggers  are  not  useful. For example, on SPARC machines, if
43       obpsym is loaded, you may be able to use the OpenBoot firmware's ctrace
44       command to display symbolic names in the stack backtrace after a watch‐
45       dog reset.
46
47   Kernel Symbolic Name Syntax
48       The syntax for a kernel symbolic name is:
49
50
51        [ module-name : ] symbol-name
52
53
54       Where module-name is the name of the kernel module that the symbol sym‐
55       bol-name appears in. A NULL module name is taken as "all modules, in no
56       particular order" by obpsym. The module name unix is  equivalent  to  a
57       NULL  module  name,  so  that  conflicts  with  words  defined  in  the
58       firmware's vocabulary can be avoided.
59
60
61       Typically, OpenBoot firmware reads a word from  the  input  stream  and
62       looks  the  word  up  in its internal vocabulary before checking if the
63       word is a literal. Thus, kernel symbols, such as reset may be given  as
64       unix:reset  to avoid the unexpected side effect of the firmware finding
65       and executing a matching word in its vocabulary.
66

FILES

68       /etc/system
69
70           system configuration information file
71
72
73       /platform/platform-name/kernel/misc/obpsym
74
75
76
77

ATTRIBUTES

79       See attributes(5) for descriptions of the following attributes:
80
81
82
83
84       ┌─────────────────────────────┬─────────────────────────────┐
85       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
86       ├─────────────────────────────┼─────────────────────────────┤
87       │Availability                 │SUNWcar                      │
88       └─────────────────────────────┴─────────────────────────────┘
89

SEE ALSO

91       kadb(1M), kernel(1M), modload(1M), modunload(1M), uname(1),  system(4),
92       attributes(5)
93
94
95
96

WARNINGS

98       Some OpenBoot firmware user interface commands may use system resources
99       incompatibly with the way they are used by the Unix kernel. These  com‐
100       mands and the use of this feature as a kernel debugger may cause inter‐
101       actions that the Unix kernel is not prepared  to  deal  with.  If  this
102       occurs,  the  Unix  kernel  and/or the OpenBoot firmware user interface
103       commands may react unpredictably and may panic the system, or may  hang
104       or may cause other unpredictable results. For these reasons, the use of
105       this feature is only minimally supported and  recommended  to  be  used
106       only as a kernel debugger of "last resort".
107
108
109       If a breakpoint or watchpoint is triggered while the console frame buf‐
110       fer is powered off, the system can crash and be left in  a  state  from
111       which  it  is  difficult to recover. If one of these is triggered while
112       the monitor is powered off, you will not be able to  see  the  debugger
113       output.
114

NOTES

116       platform-name can be found using the -i option of uname(1)
117
118
119       obpsym  is  supported  only  on  architectures  that  support  OpenBoot
120       firmware.
121
122
123       On some systems, OpenBoot must be completely RAM resident so the obpsym
124       symbol  callback  support can be added to the firmware, if the firmware
125       doesn't include support for the symbol  callbacks.  On  these  systems,
126       obpsym may complain that it requires that "you must use ramforth to use
127       this module".
128
129
130       See the  for details on how to use the ramforth command, how  to  place
131       the  command into nvramrc, and how to set use-nvramrc? to true. On sys‐
132       tems with version 1.x OpenBoot firmware, nvramrc doesn't exist, and the
133       ramforth  command  must be typed manually after each reset, in order to
134       use this module.
135
136
137       Once installed, the symbol table callbacks can be disabled by using the
138       following OpenBoot firmware command:
139
140
141       0 0 set-symbol-lookup
142
143
144
145SunOS 5.11                        13 Dec 2001                       obpsym(1M)
Impressum