Questions and answers on OpenBoot
Bookmark this so the next time you need to diagnose a pesky hardware problem this information will be at hand
OpenBoot -- the firmware in the Sun boot PROM -- is an obscure component of any workstation, but it turns out to be pretty important, with some interesting features. Solaris expert Steve Leung of Amdahl uses a Q&A format to reveal the dark magic of an oft-overlooked system every administrator can use. You may not need this information today, but add it to your bookmarks so that the next time you need to diagnose a pesky hardware problem this information's at hand. (4,500 words)
Q: What is OpenBoot?
When you turn on a Sun workstation, the firmware in the boot PROM (programmable read-only memory) is executed immediately. The main function of a boot PROM is to load a standalone program to the core memory and start its execution. Standalone programs can be operating systems, diagnostic software, and others. The firmware in Sun's boot PROM is called OpenBoot. Other than initial program loading and invocation, OpenBoot provides debugging features to assist kernel debugging and board bring-up.
Q: What is the main advantage of
Sun offers many different machine architectures (e.g., sun4d, sun4m, etc.) and boot devices (e.g., different types of disks). Instead of having different versions of the boot PROM firmware to support all combinations, OpenBoot supports plug-in device drivers. The drivers are written in a dialect of the interpreted language Forth (OpenBoot implements a Forth interpreter). The code for the driver may reside on the device PROM itself or in empty space on the system board PROM. This plug-in feature allows Sun or any third party vendors to develop new boot devices but without recompiling or relinking the boot PROM.
Another nice thing about OpenBoot is that it behaves the same across platforms. The newer revisions provide new commands, but generally OpenBoot is stable. Sun hasn't released a major revision in more than a year.
Q: Why do application developers need to care
When the network connected to your workstation is down, and you have nothing else to do, you can always go to OpenBoot to write a Forth program to entertain yourself for a few hours. Besides that, there are many practical things you can do with OpenBoot, such as security and device diagnostics.
Q: How do I access
Pressing the keys L1 and A at the same time will bring you to the OpenBoot system. You will see the display
Type b (boot), c (continued), or n (new command mode) >
You are now interacting with the restricted monitor that allows
you to do three things. Typing
b boots a standalone program (most
likely the operating system). Typing
c resumes the execution of a
halted program. Typing
n gets you to the Forth monitor, and the prompt
will change to
ok. Most of the Forth language syntax is
accepted at the Forth monitor, a.k.a., the
Now you are ready and able to do many interesting things. To continue executing (e.g., return to the OS), type
Q: What is Forth doing in
OpenBoot contains a command interpreter (something like the shell). Instead of providing a new command language syntax, it incorporates a dialect of the programming language Forth. Forth is a popular language used in many embedded systems. Because the language is simple and its interpreter small, Forth systems take up very little space. They fit perfectly into PROM.
Q: What does a Forth program look
Forth programming is interactive, much like BASIC programming. You see
the result immediately. Forth commands are also called words.
In addition to accepting arguments, Forth words rely heavily on values
in the Forth stack, which is a last-in, first-out (LIFO) buffer for
temporarily holding information. The word
showstack shows the
current content of the stack. Forth uses postfix notation
rather than infix. For example, in Forth, you write "3
4 +" instead of "3 + 4".
You can define your own Forth word. The syntax is weird. A colon starts the definition, and semicolon ends it. (There is a space between the colon and the name of the word.)
In the following example, we define a new Forth word
double, which doubles the value of the top stack item.
+ are built-in Forth words.
dup duplicates the top stack item.
the topmost two stack items and pushes the result on top of the stack.
The built-in command . (yes, it's a period) pops the top stack item
and displays it. You can see the source code of any Forth word by the
ok : double dup + . ; ok 4 double 8 ok see double : double dup + . ;
Q: How do I change the OpenBoot
There are OpenBoot configuration parameters that you can set. They are stored in the non-volatile RAM (NVRAM) that keeps the values of the parameters even after a power cycle. To display all current values, type
To display just the current value of a named parameter, type
ok printenv parameter
where parameter is the name of the object you want to see.
To set the named parameter to the given value, type
ok setenv parameter value
To reset all parameters or the named parameter to the factory default, type
ok set-default parameter
to reset just one specific parameter.
Some of the valid parameters are boot-device, boot-file, screen-#columns, screen-#rows, and security-mode.
Q: How do I stop people from rebooting my workstation?
OpenBoot can provide security on reboot. Security parameters control what actions users can perform in OpenBoot. Remember, users interact with OpenBoot through either the restricted monitor or the Forth Monitor. Security parameter
security-mode places restrictions
on how the boot process works. The default value of security-mode is
none; therefore, anybody can reboot the machine. With
security-mode set to
command, a password is required
to boot with parameters (the
b command), or execute the
n command in the restricted monitor. This prevents illegal
users executing illegal programs. For example,
>b stand_alone_program_virus PROM Password: >n PROM Password:
For the examples above, a password is required for both the command
n, and is not echoed as it is typed.
Note: A password is not required to reboot with default parameters. If
full, then a password is
required to perform any kind of reboot. For example,
>b PROM Password:
You can set the password with the command
password in the
Forth monitor. For example,
ok password New Password (only first 8 chars are used); Retype new password:
You can reset security back to
none by issuing the command
setenv security-mode none.
One thing you have to remember -- if you enable the password and forget it, you will have to call Sun's support to remove the password and make your machine bootable again.
Q: How do I change the Power-on
First, you can display the system banner by executing the command
banner. It displays Sun's power-on logo and message. To let
the OEM partners have a little bit of freedom, Sun (or OpenBoot) lets
you set your own power-on logo and message. For example, type
ok setenv oem-banner power-on-message ok setenv oem-banner? True
This will set your own power-on message. To set the power-on logo,
you do the same thing with the parameters
oem-logo?. However it is a little bit more complicated to
oem-logo, since a logo is a bit-mapped icon. It is
better to do this with OS utility
eeprom can be used to access OpenBoot settings. First, at
the OS level, run
iconedit to create the power-on
icon, then use
eeprom to convert the icon to the internal
Q: How do I boot a different
At the Forth monitor, the command to boot a standalone program (e.g., OS kernel) is :
ok boot [boot-device] [stand-alone-program] [flag(s)-for-the-stand-alone-program]
If you execute
boot without any arguments, defaults are
used. The defaults are stored in the configuration parameters
boot-file. To display their contents,
ok printenv boot-device boot-device disk0 disk ok printenv bootfile boot-file
In the above example, current and default values of
the values of
boot-file are empty strings.
disk are device aliases. To see the real device, type
ok devalias disk0 disk0 /sbus/esp@0,800000/sd@3,0As you can see from the output,
disk0is a SCSI disk
sd. An empty string in
boot-filemeans to let the secondary booter choose the default, usually
kernel/unix. The commands
printenvwith no argument list all the device aliases and NVRAMRC configuration parameters in the OpenBoot firmware, respectively.
Q: What exactly happens during the boot process?
A lot. First, at the Forth monitor, the command
boot locates the
boot loads the fixed-size block
bootblock from a fixed location in the boot device.
bootblock loads the secondary booter from the
device. The location of the secondary booter is recorded in the
bootblock is prepared by the
installboot. If the boot device is a UFS file
system, the secondary booter is
Third, the secondary booter locates and loads the standalone
program. If the name of the standalone program was not specified in
ufsboot loads its default
At last the standalone program is executed.
A different secondary booter is needed for each different type of
file system installed in the boot device. This is because the secondary
booter needs to understand the protocol of that particular file system
in order to locate and load the standalone program. For example, if you
specify the standalone program as
/home/mary/test/version10/kernel/unix, the secondary booter has to
be able to locate the file from the file system in the boot device.
Q: Can I boot from any
device? Officially, Sun only supports booting from a hard disk, CD-ROM, floppy disk, and Ethernet. A floppy disk typically does not have the capacity to boot a kernel, given their usual size. However you can use it to boot other standalone programs (assuming that they would fit in a single floppy disk). When booting from the network, OpenBoot broadcasts a reverse ARP request to the network, and a boot server will reply. Then OpenBoot establishes a TFTP connection to the boot server to retrieve the secondary booter
inetboot uses the
bootparams protocol to obtain the root file system, and then it
uses the NFS protocol to fetch the kernel over the Ethernet. The boot
server needs to set up its boot parameter database properly in order
for this boot process to work.
Q: What are the option parameters available in booting Solaris kernels?
A Solaris kernel takes a few standard flags at the Forth monitor. They are
ok boot kernel/unix [-a | -r | -s | -v ]
-a asks you interactively for configuration
information. You use this flag if you want to specify a different
system configuration file (not /etc/system), a different root
file system, a different search path for dynamic load modules (DLMs),
-r reconfigures your device tree at both /dev and
/devices. You would boot the kernel with this flag on after you add a
new device to the system. The system probes all attached hardware
devices and rebuilds the device tree from scratch.
-s boots the kernel to the single-user mode. Many times
when you fail to complete a full kernel boot, you would prefer to at
least boot to the single-user mode and then perform troubleshooting
-v turns on the verbose mode. This means system boot
messages are not just going to the system log file (usually
/var/adm/messages) but also simultaneously to the console
Q: What other standalone programs are
available for OpenBoot?
Ninety-nine percent of the time, the standalone program is the Solaris
kernel. The rest of the time you probably run the kernel debugger
kadb and some hardware diagnostic tools from the hardware
kadb is based on the debugger
includes many pre-defined macros which understand kernel data
structures. Sorry, you cannot define your own macros. They are
compiled together with
kadb. The syntax to run
ok boot [boot-device] kadb [-d] [kernel-flags]
kadb prompts you for the kernel you
want to debug; otherwise the default
kernel/unix is used.
Kernel flags are simply passed to the kernel by
Q: What is a device tree?
Sun hardware uses the concept of the device tree to organize devices attached to the system. To see the entire device tree, use
ok show-devs /io-unit@f,e1200000 /io-unit@f,e0200000 /mem-unit@f,e1100000 /mem-unit@f,e0100000 /cpu-unit@f,e1800000 /cpu-unit@f,e1000000 /cpu-unit@f,e0800000 /cpu-unit@f,e0000000 /boards /openprom /virtual-memory@0,0 /memory@0,0 /aliases /options /packages /io-unit@f,e1200000/sbi@0,0 /io-unit@f,e1200000/sbi@0,0/SBUSDKHS@3,2000 /io-unit@f,e1200000/sbi@0,0/lebuffer@0,40000 /io-unit@f,e1200000/sbi@0,0/dma@0,81000 /io-unit@f,e1200000/sbi@0,0/lebuffer@0,40000/le@0,60000 /io-unit@f,e1200000/sbi@0,0/dma@0,81000/esp@0,80000
Each entry of the output represents a device. At the Solaris OS
level, you can see the same tree under
/devices. In addition,
the Forth Monitor provides Unix-like commands to manipulate the
devices. For example,
ok cd /io-unit@f,firstname.lastname@example.org
cd makes the device
/io-unit@f,email@example.com the current node.
ok ls ffda2b3c qec@3,20000 ffda093c lebuffer@1,40000 ffd9baec dma@1,81000 ffd998ec lebuffer@0,40000 ffd946c4 dma@0,81000
ls lists the nodes under the current nodes.
The second column of the output lists the names of the nodes. The first
column lists the physical addresses associated with the nodes.
pwd displays the pathname of the current
ok pwd /io-unit@f,e0200000/sbi@0,0
Q: How do I interpret a device
Each node in the device tree represents a device. Nodes with children usually represent buses and their associated controllers. Their children are devices connected to the buses or controllers.
A full device path begins with a /. It is the root of the tree and represents the machine node. Each node name has the form name@address:arguments. Other than name, the rest are optional and the format is device-dependent. If the system can identify the device without ambiguity, you can ignore that portion of the device path name. I usually write the complete path.
address represents a physical address associated with the device. arguments is used to pass additional information to the device's software.
Let's look at a simple example. The root file system of my IPX system is /dev/dsk/c0t3d0s0, which is equivalent to the device node
Let's see how we interpret the path. From
know the device is a SCSI disk
sd attached to the SCSI bus
at target 3 and logical unit 0. The
a at the end represents
the first partition of the disk. From
esp@0,800000, we know
the SCSI bus is implemented as a SCSI host adapter
residing in the SBus slot 0 at offset 800,000. Finally from
sbus@1,f8000000, we know the SBus interface is attached to
the system bus at address
Q: How do I create device
As you can see, each device path is quite long. It would be nice to be
able to make aliases for devices. OpenBoot provides the command
devalias for this purpose.
ok devalias [alias]
devalias displays the current values of all
device aliases (if no parameter is given) or the named alias.
ok devalias alias device-path
devalias with two arguments defines a device alias
alias to the value device-path.
Q: What can I do with a device
Each device node has attributes and methods associated with it. Use the
Forth Monitor commands
display the values for the current node. For example,
ok cd /io-unit@f,e0200000/sbi@0,0/dma@0,81000/esp@0,80000/sd ok .attributes device_type block name sd ok words selftest reset load write read seek sd-selftest close open write-blocks read-blocks dma-free dma-alloc max-transfer block-size spin-up
The above example shows a SCSI disk
sd and it is a
block device. Methods are provided to open, close, read and
write the device. The
cd command is needed to make the
named device the current node.
words only work on the current node.
Q: How do I perform device
There are a few commands that come very handy for device diagnostics.
probe-scsi-all identifies all SCSI devices attached to the
probe-scsi-all is not supported until OpenBoot
revision 2.6. The output of the command banner will indicate
the current OpenBoot revision number for your machine.)
ok probe-scsi-all /io-unit@f,e1200000/sbi@0,0/dma@0,81000/esp@0,80000 Target 0 Unit 0 Disk CONNER CP30548 SUN0535AEBX9308288P Target 1 Unit 0 Disk CONNER CP30548 SUN0535AEBX93082PA7 Target 2 Unit 0 Disk CONNER CP30548 SUN0535AEBX9308280V Target 3 Unit 0 Disk CONNER CP30548 SUN0535AEBX93082PMC /io-unit@f,e0200000/sbi@0,0/dma@1,81000/esp@1,80000 Target 0 Unit 0 Disk SEAGATE ST42400N SUN2.1G0417705457 Copyright (c) 1992 Seagate All rights reserved ok
probe-scsi identifies SCSI devices attached to only the
built-in SCSI bus.
ok probe-scsi Target 0 Unit 0 Disk SEAGATE ST31200N SUN1.05872200147810Copyright (c) 1994 Seaga te All rights reserved 0000 Target 1 Unit 0 Disk SEAGATE ST31200N SUN1.05872200137389Copyright (c) 1994 Seaga te All rights reserved 0000 Target 2 Unit 0 Disk SEAGATE ST31200N SUN1.05872200150421Copyright (c) 1994 Seaga te All rights reserved 0000 Target 3 Unit 0 Disk SEAGATE ST31200N SUN1.058722001494te All rights reserved 000078Copyright (c) 1994 Seaga te All rights reserved 0000 Target 5 Unit 0 Removable Tape ARCHIVE Python 28454-XXX4ASB Target 6 Unit 0 Removable Read Only device SONY CDU 561 SUNMSCD1.9k ok
test executes the named device's method
In other words, if
words lists the method,
test will work.
ok test /io-unit@f,e0200000/sbi@0,0 No selftest method for /io-unit@f,e0200000/sbi@0,0 ok test disk
In the example, the device /io-unit@f,e0200000/sbi@0,0 does not
have the method
test would not
work. The device
disk has the method; therefore,
selftest succeeds, it outputs nothing.
test-all tests all the devices in the system.
ok test-all Testing /memory@0,0 Testing /io-unit@f,e1200000/sbi@0,0/lebuffer@0,40000 Testing /io-unit@f,e1200000/sbi@0,0/lebuffer@0,40000/le@0,60000 Internal loopback test -- succeeded. External loopback test -- succeeded. Testing /io-unit@f,e1200000/sbi@0,0/dma@0,81000/esp@0,80000 Testing /io-unit@f,e0200000/sbi@0,0/qec@3,20000 Testing /io-unit@f,e0200000/sbi@0,0/lebuffer@1,40000 Testing /io-unit@f,e0200000/sbi@0,0/lebuffer@0,40000 Testing /io-unit@f,e0200000/sbi@0,0/qec@3,20000/qe@3,0 Internal loopback test -- succeeded. Internal (including Mendec) loopback test -- succeeded. Link state check -- failed, transceiver cable problem? or check the hub. Selftest failed. Return code = -1
watch-clock tests the clock function. The system responds
by incrementing a number (starting at zero) by one each second.
ok watch-clock Watching the 'seconds' register of the real time clock chip. It should be 'ticking' once a second. Type any key to stop. 49 ok
watch-net monitors the network traffic. It displays a
dot (.) each time it receives a error-free packet. The external
loopback test will fail if the system is not connected to Ethernet.
ok watch-net Internal loopback test -- succeeded. External loopback test -- succeeded. Looking for Ethernet packets. '.' is a good packet. 'X' is a bad packet. Type any key to stop. ................................................................................ ................................... ok
show-bus displays all the installed and probed SBus
ok show-sbus Board# 0 SBus slot 0 lebuffer le dma esp Board# 0 SBus slot 1 lebuffer le dma esp Board# 0 SBus slot 2 Board# 0 SBus slot 3 qec qe qe qe qe Board# 1 SBus slot 0 lebuffer le dma esp Board# 1 SBus slot 1 Board# 1 SBus slot 2 Board# 1 SBus slot 3 SBUSDKHS ok
Q: How do I make permanent changes in OpenBoot settings?
A portion of the NVRAM called NVRAMRC is reserved for storing user-defined commands and device aliases. User-defined commands are written in Forth. You can look at it as those Unix rc files in which commands are executed during start-up. Those commands are stored in ASCII text format. Almost all Forth monitor commands can be used. Exceptions are
banner, boot, go, nvedit, password, reset,
Some useful commands to operate NVRAMRC are:
ok nvalias alias device-path
The effect of
nvalias is to store the command
devalias alias device-path" in the
NVRAMRC. Or you can use the NVRAMRC editor
nvedit to directly
edit the NVRAMRC buffer.
nvedit has its own editing commands,
a little bit like Emacs, e.g., CTRL-P to move forward one character and
CTRL-B to move backward.
nvedit only operates on a temporary
buffer. To make permanent changes to NVRAMRC, execute the command
nvstore after you quit
nvedit. To test the changes in
the buffer, try
nvrun, which executes the contents of the
temporary buffer. Also
ok nvunalias alias
deletes the named alias from NVRAMRC.
Q: How do I do program debugging with
OpenBoot provides register-display commands, breakpoint commands, a
disassembler, and symbolic debugging ability. However they are intended
for assisting device bring-up's. They are not general-purpose
facilities for the general public. For OS- and applications-level
kadb is the preferred choice.
OpenBoot debugging commands normally display addresses in
hexadecimal. However, if you load the standalone program through the
dload (which is another way to perform program
loading in OpenBoot), OpenBoot will keep the symbol table information,
and memory addresses are displayed symbolically whenever possible. The
OS is usually not loaded with
dload but through some
intermediate booter (like the
ufsboot used with
boot); therefore symbol information included in the kernel's
a.out file is not available to the OpenBoot debugging facility. It is
really not much use for the average users if the symbol information is
Here are some useful commands if you have to debug at the OpenBoot
level (for example, if
kadb was not started at the boot time,
and the system crashes):
.fregisters displays values in registers
ok .fregisters 0 1 2 3 4 5 6 7 +0: 0 0 ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff +8: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff +16: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff +24: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff fsr: 0 fq:address: 0 fq:instruction: 81a00000
.registers displays values in registers
ok .registers %g0 %g1 %g2 %g3 %g4 %g5 %g6 %g7 0 e00511f0 e3781ec0 e0069fb8 570 0 1 e3781ec0 PC nPC Y PSR WIM TBR ffd72210 ffd72214 0 40400ce6 10 e0040050
.locals displays the values in
In SPARC terminology,
%o are input, local and output registers respectively.
ok .locals 0 1 2 3 4 5 6 7 IN: 2 ffd418a0 e e01a54e2 0 1 e379fdb0 e006ca04 LOC: 40800cc6 f0 e006c518 40 0 e0069fb8 7 ffffffc0 OUT: e0040050 ffeff000 0 1f00506 0 f00 e379fd50 ffd418ac
%f0 and etc. return the value of the individual
register respectively. The value is pushed onto the Forth monitor
stack. The command . is used to pop the value off the stack
and display it.
ok %g1 . e00511f0 ok %pc . ffd72210
w sets the current active window for displaying
%o registers. By changing the current register window, you can
examine different set of local registers. SPARC has the concept of
register sliding windows. Each window has its own set of local
resisters for faster context switch.
1 w .locals advances
one window and executes
ok 1 w .locals IN: 2e0000 6e 2e0000 4 1 6e e379fe10 e004c878 LOC: 60 e00e48a0 f 10 1 e01b88c8 1 e01c4f10 OUT: 2 ffd418a0 e e01a54e2 0 1 e379fdb0 e006ca04
ctrace displays the return stack showing C functions.
ok ctrace PC: ffd72210 Last leaf: call ffd721ec from ffd418ac 0 w %o0-%o5: ( e0040050 ffeff000 0 1f00506 0 f00 ) jmpl ffd418a0 from e006ca04 1 w %o0-%o5: ( 2 ffd418a0 e01b8800 f c 1 ) call e006c9a4 from e004c878 2 w %o0-%o5: ( 2e0000 63 2e0000 e01b88dc c 63 ) call e004c764 from e004c748 3 w %o0-%o5: ( 0 740000 74 0 e01c497c e01c497c ) ok
dis starts disassembling at the given address.
+dis continues disassembling where the last disassembly
left off. In the following example, it starts the disassembling at the
current program counter. The command
%pc places the current
value of the program counter on the Forth monitor stack.
dis pops the value off the top of the stack and takes it as
ok %pc ok dis ffd72210 ta %g0, 7f ffd72214 wrtbr %o0, 0 ffd72218 sethi 0, %g0 ffd7221c sethi 0, %g0 ffd72220 sethi 0, %g0 ffd72224 jmp %o7, 8, %g0 ffd72228 sethi 0, %g0 ok +dis ffd7222c call ffd48ecc ffd72230 sub %g7, 4, %g7 ok
Q: At OpenBoot, can I mount file systems and
No, in practice you cannot. OpenBoot understands neither Solaris file systems nor files. It is a very primitive system that mainly deals with hardware devices and not high-level objects like file systems and files. But yes, theoretically, you can. You can write a Forth program to interface with the methods of a device like a hard disk. For example a hard disk device would have the methods to read and write disk blocks. You can then map the file system related data structures to the disk blocks and locate the individual files. The whole process is definitely not trivial.
Q: How do I reset reboot the
reset resets the complete system and is
to a power cycle. It initializes the memory to zeros. If
auto-boot? is set to
true, the system will also
re-boot. Alternately you can use the command
sync to reboot
sync synchronizes all the mounted file systems
and flushes out all the dirty pages to the disks before the reboot.
sync returns to the OS which then synchronizes
sync) all the mounted file systems, and saves a core image of
the kernel. You can hit L1-A to stop the core dump. Sync always reboots
the machine automatically at the end.
Q: Where can I find more literature on
OpenBoot and related topics?
At the Forth Monitor, you can type
help to get
more information. In addition each command is a Forth word, and you can
see command to view the Forth source
code for a particular command.
There are also manual pages. Try man pages:
monitor(1M), boot(1M), eeprom(1M), kernel(1M), kadb(1M), iconedit(1), system(4), installboot(1M).
There are reference manuals and users' guides too. Try Writing FCode Programs, by Sun Microsystems, published by SunSoft Press, 1994, ISBN 0-13-107236-6. Details and ordering info on this book are available at http://www.sun.com/smi/ssoftpress/books/WritingFCode/WritingFCode.html.
To learn more on Forth 83 programming, read: Starting Forth, second edition by Leo Brodie, Prentice-Hall.
About the author
Steve Leung (SSL20@amdahl.com) is a senior software engineer at Amdahl Corp., Sunnyvale, CA. He works on the Amdahl A+ edition of Solaris and on UTS (Amdahl's version of Unix SVR4 on S/390 mainframes).
If you have technical problems with this magazine, contact firstname.lastname@example.org