This chapter introduces the OpenBoot firmware, the standard firmware for Sun systems.
The OpenBoot Version 1 firmware was introduced on the Sun SPARCstation 1. It also was the firmware for the SPARCstation 1+, SPARCstation IPC, and SPARCstation SLC(TM) systems. This manual describes Version 2 of the firmware, which first appeared on the SPARCstation 2 system.
The OpenBoot firmware is stored in the boot PROM (programmable read-only memory) of a system so that it is executed immediately after you turn on your system. The primary task of the OpenBoot firmware is to boot the operating system from either a mass storage device or from a network. The firmware also provides extensive features for testing hardware and software interactively.
The OpenBoot architecture provides a significant increase in functionality over the boot PROMs in earlier Sun systems. Although this architecture was first implemented on SPARC systems, its design is processor-independent. Some notable features of the OpenBoot firmware include:
Plug-in device drivers. A plug-in device driver is usually loaded from a plug-in device such as an SBus card. The plug-in device driver can be used to boot the operating system from that device or to display text on the device before the operating system has activated its own drivers. This feature allows the input and output devices supported by a particular system to evolve without changing the system PROM.
FCode interpreter. Plug-in drivers are written in a machine-independent interpreted language called FCode. Each OpenBoot system PROM contains an FCode interpreter. Thus, the same device and driver can be used on machines with different CPU instruction sets.
Device tree. The device tree is an OpenBoot data structure describing the devices (permanently installed and plug-in) attached to a system. Both the user and the operating system can determine the hardware configuration of the system by inspecting the device tree.
Programmable user interface. The OpenBoot user interface is based on the interactive programming language Forth. Sequences of user commands can be combined to form complete programs. This provides a powerful capability for debugging hardware and software.
You can enter the OpenBoot environment in the following ways:
By halting the operating system.
By using the Stop-A key sequence from the keyboard. (This abruptly breaks execution of the operating system and should be used with caution.)
By power-cycling the system. (If your system is configured to boot automatically, you can enter the OpenBoot environment by pressing Stop-A after the display console banner appears but before the system starts booting the operating system. If automatic booting is not enabled, the system will enter the OpenBoot environment on its own instead of booting the operating system.)
When the system hardware detects an error from which it cannot recover. (This is known as a Watchdog Reset.)
The OpenBoot firmware provides three external interfaces: an interface for the operating system or other standalone programs, an interface for expansion bus plug-in boards (for example, SBus), and a command line interface for the user at the system console. This manual describes the third of these interfaces: the system console command line interface.
The command line interface has two modes:
The Restricted Monitor
The Forth Monitor
The Restricted Monitor provides a simple set of commands to initiate booting of the system, resume system execution, or enter the Forth Monitor. The Restricted Monitor is also used to implement system security. (See Chapter 3, Setting Configuration Parameters, for information on system security.)
The Restricted Monitor prompt is >. When you enter the Restricted Monitor, the following screen is displayed:
Type b (boot), c (continue), or n (new command mode) >
The Restricted Monitor commands are summarized in the following table.
Table 1-1 Restricted Monitor CommandsCommand | Description |
---|---|
b [specifiers] | Boot the operating system. |
c | Resume the execution of a halted program. |
n | Enter the Forth Monitor. |
The Restricted Monitor functions b (for booting the system) and c (for resuming execution of a halted program) are available as the boot (see Chapter 2, Booting and Testing Your System) and go (see Chapter 5, Loading and Executing Programs) commands, respectively, in the Forth Monitor.
The Forth Monitor is an interactive command interpreter that gives you access to an extensive set of functions for hardware and software development, fault isolation, and debugging. A variety of system users, from end-users to system administrators to system developers, can use these functions.
The Forth Monitor prompt is ok. When you enter the Forth Monitor, the following screen is displayed:
Type help for more information ok
The default mode in early OpenBoot systems is the Restricted Monitor. This was done mainly to provide a default look and feel similar to pre-OpenBoot systems.
The SPARCserver(TM) 690 system was the first to have the Forth Monitor as the default mode. All systems introduced thereafter also default to this mode. For such systems, the Restricted Monitor's only real function is to support system security. (Chapter 3, Setting Configuration Parameters, discusses system security.)
If you want to leave the Forth Monitor and get into the Restricted Monitor, type:
ok old-mode
Devices are attached to a SPARC-based system on a set of interconnected buses. The OpenBoot firmware represents the interconnected buses and their attached devices as a tree of nodes. Such a tree is called the device tree. A node representing the whole machine forms the tree's root node.
Each device node can have:
Properties, which are the data structures describing the node and its associated device
Methods, which are the software procedures used to access the device
Children, which are other device nodes "attached" to that node, that lie directly below it in the device tree
A parent, which is the node that lies directly above it in the device tree.
Nodes with children usually represent buses and their associated controllers, if any. Each such node defines a physical address space that distinguishes the devices connected to the node from one another. Each child of that node is assigned a physical address within the parent's address space.
The physical address generally represents a physical characteristic unique to the device (such as the bus address or the slot number where the device is installed). This prevents device addresses from changing when another device is installed in the system.
The firmware deals directly with hardware devices in the system. Each device has a unique name representing the type of device and where that device is located within the system addressing structure. The following example shows a full device path name:
/sbus@1,f8000000/esp@0,40000/sd@3,0:a
A full device path name is a series of node names separated by slashes (/). The root of the tree is the machine node, which is not named explicitly but is indicated by a leading slash (/). Each node name has the form:
name@address:arguments
The following table describes each of these parameters.
Table 1-2 Device Path Name Parameters
Path Name Parameter |
Description |
---|---|
name |
A text string that, ideally, has some mnemonic value. (For example, sd represents "SCSI disk".) Many names, especially names of plug-in modules, include the name or stock symbol of the device's manufacturer (for example, SUNW,esp). |
@ |
Must precede the address parameter. |
address |
A text string representing an address, usually of the form hex_number,hex_number. (Numbers are given in hexadecimal format.) |
: |
Must precede the arguments parameter. |
arguments |
A text string, whose format depends on the particular device. It can be used to pass additional information to the device's software. |
The full device path name mimics the hardware addressing used by the system to distinguish between different devices. Thus, you can specify a particular device without ambiguity.
In general, the address part of a node name represents an address in the address space of its parent. The exact meaning of a particular address depends on the bus to which the device is attached. Consider the same example:
/sbus@1,f8000000/esp@0,40000/sd@3,0:a
1,f8000000 represents an address on the main system bus, because the SBus interface is directly attached to the main system bus.
0,40000 is an SBus slot number and an offset within that slot, because the esp device is in SBus slot 0 at offset 40000. (In this example, the device is a SCSI host adapter, although the name does not say so directly.)
3,0 is a SCSI target and logical unit number, because the sd device is attached to a SCSI bus at target 3, logical unit 0.
When specifying a path name, either the @address or name part of a node name is optional, in which case the firmware tries to pick the device that best matches the given name. If more than one equally-good selection exists, the firmware makes a selection (but it may not be the one you want).
For example, using /sbus/esp@0,40000/sd@3,0 assumes that the system in question has exactly one SBus interface on the main system bus, making sbus as unambiguous an address as sbus@1,f8000000. On the same system, however, /sbus/esp/sd@3,0 might or might not be ambiguous. Since SBus accepts plug-in cards, there could be more than one esp device on the same SBus. If there were more than one on the system, using esp alone would not specify which one, and the firmware might not select the one you intended.
As another example, /sbus/@0,40000/sd@3,0 would normally be acceptable while /sbus/esp@0,40000/@3,0 usually would not, since both a SCSI disk device driver (sd) and a SCSI tape device driver (st) can use the SCSI target,logical unit address 3,0.
The :arguments part of the node name is also optional. Once again, in the example:
/sbus@1,f8000000/esp@0,40000/sd@3,0:a
the argument for the sd device is the string a. The software driver for sd interprets its argument as a disk partition, so the device path name refers to partition a on that disk.
There are two kinds of device names:
Full device path names (discussed in the previous section), such as /sbus@1,f8000000/esp@0,40000/sd@3,0:a
Device aliases, such as disk
A device alias, or simply, alias, is a way of representing a device path name. An alias represents an entire device path name, not a component of it. For example, the alias disk may represent the device path name:
/sbus@1,f8000000/esp@0,40000/sd@3,0:a
Systems have predefined device aliases for most commonly-used devices, so you rarely need to type a full device path name.
The following table describes the devalias command, which is used to examine, create, and change aliases.
Table 1-3 Examining and Creating Device Aliases
Command |
Description |
---|---|
devalias |
Display all current device aliases. |
devalias alias |
Display the device path name corresponding to alias. |
devalias alias device-path |
Define an alias representing device path. If an alias with the same name already exists, the new value supersedes the old. |
User-defined aliases are lost after a system reset or power cycle. If you want to create permanent aliases, you can either manually store the output of the devalias command in a portion of non-volatile RAM (NVRAM) called NVRAMRC, or use the nvalias and nvunalias commands. (See Chapter 3, Setting Configuration Parameters, for more details.)
You can browse the device tree to examine and modify individual device tree nodes. The device tree browsing commands are similar to the UNIX\256 commands for changing the working directory within the UNIX directory tree. Selecting a device node makes it the current node.
Examine the device tree with the commands shown in the following table.
Table 1-4 Commands for Browsing the Device Tree
Command |
Description |
---|---|
.attributes |
Display the names and values of the current node's properties. |
cd device-path |
Select the indicated device node, making it the current node. |
cd node-name |
Search for a node with the given name in the subtree below the current node, and select the first such node found. |
cd .. |
Select the device node that is the parent of the current node. |
cd / |
Select the root machine node. |
device-end |
De-select the current device node, leaving no node selected. |
ls |
Display the names of the current node's children. |
pwd |
Display the device path name that names the current node. |
show-devs [device-path] |
Display all the devices known to the system directly beneath a given level in the device hierarchy. show-devs used by itself shows the entire device tree. |
words |
Display the names of the current node's methods. |
If you have been browsing the device tree, and want to reset the system, type:
ok device-end ok reset
The following example shows the use of .attributes:
ok cd /zs@1,f0000000 ok .attributes address ffee9000 port-b-ignore-cd port-a-ignore-cd keyboard device_type serial slave 00000001 intr 0000000c 00000000 interrupts 0000000c reg 00000001 f0000000 00000008 name zs ok
show-devs lists all the devices in the OpenBoot device tree, as shown in the following example:
ok show-devs /fd@1,f7200000 /virtual-memory@0,0 /memory@0,0 /sbus@1,f8000000 /auxiliary-io@1,f7400003 /interrupt-enable@1,f5000000 /memory-error@1,f4000000 /counter-timer@1,f3000000 /eeprom@1,f2000000 /audio@1,f7201000 /zs@1,f0000000 /zs@1,f1000000 /openprom /aliases /options /packages /sbus@1,f8000000/cgsix@3,0 /sbus@1,f8000000/le@0,c00000 /sbus@1,f8000000/esp@0,800000 ok
The following is an example of the use of words:
ok cd /zs ok words selftest ring-bell read remove-abort? install-abort close open abort? restore clear reset initkbdmouse keyboard-addr mouse 1200baud setbaud initport port-addr ok
Whenever you see the ok prompt on the display, you can ask the system for help by typing one of the help commands shown in the following table.
Table 1-5 Help Commands
Command |
Description |
---|---|
help |
List main help categories. |
help category |
Show help for all commands in the category. Use only the first word of the category description. |
help command |
Show help for individual command (where available). |
help, without any specifier, displays instructions about using the help system and lists the available help categories. Because of the large number of commands, help is available only for commands that are used frequently.
If you want to see the help messages for all the commands in a selected category, or, possibly, a list of sub-categories, type:
ok help category
If you want help for a specific command, type:
ok help command
For example, when you ask for information on the dump command, you see the following message:
ok help dump Category: Memory access dump ( addr length -- ) display memory at addr for length bytes ok
The above help message first shows that dump is a command from the Memory access category. The message also shows the format of the command.
In some newer systems, descriptions of additional machine-specific commands are available with the help command.
If you boot the operating system, exit it with either the Stop-A or halt commands, and then use some OpenBoot commands, the commands might not work as expected.
For example, suppose you boot the operating system, exit it with Stop-A, then execute the probe-scsi command. You may find that probe-scsi fails, and you may not be able to resume the operating system. When this happens, type the following commands:
ok sync ok boot
To re-execute an OpenBoot command which fails because the operating system has halted, reset the system, then invoke the command, as shown:
ok reset ok probe-scsi ok