This chapter introduces OpenBoot as defined by IEEE Standard 1275-1994. OpenBoot firmware is executed immediately after you turn on your system. The primary tasks of OpenBoot firmware are:
The OpenBoot architecture provides a significant increase in functionality and portability when compared to proprietary systems of the past. Although this architecture was first implemented by Sun Microsystems as OpenBoot on SPARCŪ systems, its design is processor-independent. Some notable features of OpenBoot firmware include:
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.
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.
The device tree is a 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.
The OpenBoot User Interface is based on the interactive programming language Forth. Sequences of user commands can be combined to form complete programs, and this provides a powerful capability for debugging hardware and software.
The User Interface is based on 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, ranging from end-users to system administrators to system developers, can use these functions.
The User Interface prompt is implementation dependent.
You can enter the OpenBoot environment in the following ways:
If your system is not configured to boot automatically, the system will stop at the User Interface.
If automatic booting is configured, you can cause the system to stop at the User Interface by entering the Stop-A key sequence from the keyboard after the display console banner appears but before the system starts booting the operating system.
Devices are attached to a host computer through a hierarchy of interconnected buses. OpenBoot 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 host computer's main physical address bus forms the tree's root node.
Each device node can have:
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 in 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). The use of physical addresses to identify devices prevents device addresses from changing when other devices are installed or removed.
Nodes without children are called leaf nodes and generally represent devices. However, some such nodes represent system-supplied firmware services.
OpenBoot 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 in the system addressing structure. The following example shows a full device path name:
---------------------------------------
/sbus@1f,0/SUNW,fas@e,8800000 ---------------------------------------
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:
driver-name@unit-address:device-arguments
Table 1 describes each of these parameters.
Table 1 Device Path Name Parameters
------------------------------------------------------------------------------------------------------------------------
Path Name Parameter Description ------------------------------------------------------------------------------------------------------------------------
driver-name A human-readable string consisting of one to 31 letters, digits and punctuation
characters from the set ", . _ + - " that, ideally, has some mnemonic value. Upper-case
and lower-case characters are distinct. In some cases, this name includes the name of the
device's manufacturer and the device's model name, separated by a comma. Typically,
the manufacturer's upper-case, publicly-listed stock symbol is used as the
manufacturer's name (e.g. SUNW,sd). For built-in devices, the manufacturer's name is
usually omitted (e.g. sbus).
@ Must precede the address parameter.
unit-address A text string representing the physical address of the device in its parent's address
space. The format of the text is bus dependent.
: Must precede the arguments parameter.
device-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 unit-address part of a node name represents an address in the physical address space of its parent. The exact meaning of a particular address depends on the bus to which the device is attached. Consider this example:
-------------------------------------
/sbus@1f,0/esp@0,40000/sd@3,0:a -------------------------------------
When specifying a path name, either the @unit-address or driver-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 there are several matching nodes, the firmware chooses one (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 on the main system bus, making sbus as unambiguous an address as sbus@1f,0. 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 bus. If there were more than one on the system, using esp alone would not specify which one, and the firmware might not choose the one you intended.
As another example, /sbus/@2,1/sd@3,0 would normally be unambiguous, while /sbus/scsi@2,1/@3,0 usually would not, since both a SCSI disk device driver and a SCSI tape device driver can use the SCSI target, logical unit address 3,0.
The :device-arguments part of the node name is also optional. Once again, in the example:
-----------------------------------
/sbus@1f,0/scsi@2,1/sd@3,0:a -----------------------------------
the argument for the disk device is a. The software driver for this device interprets its argument as a disk partition, so the device path name refers to partition a on that disk.
Some implementations also allow you to omit pathname components. So long as the omission does not create any ambiguity, those implementations will select the device that you intended. For example, if our example system had only one sd device,
/sd:a
would identify the same device as the much longer preceding expression.
A device alias, or simply, alias, is a shorthand representation of a device path.
For example, the alias disk may represent the complete device path name:
------------------------------------
/sbus@1f,0/esp@0,40000/sd@3,0:a ------------------------------------
Systems usually have predefined device aliases for the most commonly-used devices, so you rarely need to type a full device path name.
Table 2 describes the devalias command, which is used to examine, create, and change 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 devalias command in a portion of non-volatile RAM (NVRAM) called nvramrc, or use the nvalias and nvunalias commands. (See Chapter 3, "Setting Configuration Variables" 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 Solaris commands for changing, displaying and listing the current directory in the Solaris directory tree. Selecting a device node makes it the current node.
The User Interface commands for browsing the device tree are shown in Table 3.
-------------------------------------------------------------------------------------------------------------------
Command Description -------------------------------------------------------------------------------------------------------------------
.properties Display the names and values of the current node's properties.
dev device-path Choose the indicated device node, making it the current node.
dev node-name Search for a node with the given name in the subtree below the current node,
and choose the first such node found.
dev .. Choose the device node that is the parent of the current node.
dev / Choose the root machine node.
device-end Leave the device tree.
" device-path" find-device Choose device node, similar to dev.
ls Display the names of the current node's children.
pwd Display the device path name that names the current node.
see wordname Decompile the specified word.
show-devs [device-path] Display all the devices directly beneath the specified device in the device tree.
show-devs used by itself shows the entire device tree.
words Display the names of the current node's methods.
" device-path" select-dev Select the specified device and make it the active node.
-------------------------------------------------------------------------------------------------------------------
.properties displays the names and values of all the properties in the current node:
-----------------------------------------------------
ok dev /zs@1,f0000000 ok .properties 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 -----------------------------------------------------
dev sets the current node to the named node so its contents can be viewed. For example, to make the ACME company's SBus device named "ACME,widget" the current node:
---------------------------
ok dev /sbus/ACME,widget ---------------------------
find-device is essentially identical to dev differing only in the way the input pathname is passed.
--------------------------------------
ok " /sbus/ACME,widget" find-device --------------------------------------
Note - After choosing a device node with dev or find-device, it is not in general possible to execute that node's methods because dev does not establish the current instance. For a detailed explanation of this issue, refer to Writing FCode 3.x Programs.
show-devs lists all the devices in the OpenBoot device tree, as shown in the following example:
----------------------------------------
ok show-devs /SUNW,UltraSPARC@0,0 /sbus@1f,0 /counter-timer@1f,3c00 /virtual-memory /memory@0,0 /aliases /options /openprom /chosen /packages /sbus@1f,0/cgsix@1,0 /sbus@1f,0/lebuffer@0,40000 /sbus@1f,0/dma@0,81000 /sbus@1f,0/SUNW,bpp@e,c800000 /sbus@1f,0/SUNW,hme@e,8c00000 /sbus@1f,0/SUNW,fas@e,8800000 /sbus@1f,0/sc@f,1300000 /sbus@1f,0/zs@f,1000000 /sbus@1f,0/zs@f,1100000 /sbus@1f,0/eeprom@f,1200000 /sbus@1f,0/SUNW,fdtwo@f,1400000 /sbus@1f,0/flashprom@f,0 /sbus@1f,0/auxio@f,1900000 /sbus@1f,0/SUNW,CS4231@d,c000000 /sbus@1f,0/lebuffer@0,40000/le@0,60000 /sbus@1f,0/dma@0,81000/esp@0,80000 /sbus@1f,0/dma@0,81000/esp@0,80000/st /sbus@1f,0/dma@0,81000/esp@0,80000/sd /sbus@1f,0/SUNW,fas@e,8800000/st /sbus@1f,0/SUNW,fas@e,8800000/sd /openprom/client-services /packages/disk-label /packages/obp-tftp /packages/deblocker /packages/terminal-emulator ok ----------------------------------------
Here is an example of the use of words:
----------------------------------------------------------------------
ok dev /zs ok words 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 Table 4.
Table 4 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 on how to use 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 subcategories, 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 might 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.
Note - In some newer systems, descriptions of additional machine-specific commands are available with the help command. Help as described may not be available on all systems.
If you boot the operating system, exit from the operating system into OpenBoot without resetting the system, then use some OpenBoot commands, the commands might not work as expected. In this case, you may have to power cycle the system to restore normal operation.
For example, suppose you boot the operating system, exit to OpenBoot, then execute the probe-scsi command (described in , "Booting and Testing Your System"). You may find that probe-scsi fails, and you may not be able to resume the operating system.
To re-execute an OpenBoot command which fails because the operating system has halted, reset the system first, then invoke the command, as shown:
------------------
ok reset-all ok probe-scsi ok ------------------
