PROM on SPARC Machines
Some platforms have a PROM monitor that provides support for debugging a device without
an operating system. This section describes how to use the PROM on SPARC
machines to map device registers so that they can be accessed. Usually, the
device can be exercised enough with PROM commands to determine whether the device
is working correctly.
See the boot(1M) man page for a description of the x86 boot subsystem.
The PROM has several purposes, including:
Bringing the machine up from power on, or from a hard reset PROM reset command
Providing an interactive tool for examining and setting memory, device registers, and memory mappings
Booting the Solaris system.
Simply powering up the computer and attempting to use its PROM to examine device registers can fail. While the device might be correctly installed, those mappings are specific to the Solaris OS and do not become active until the Solaris kernel is booted. Upon power up, the PROM maps only essential system devices, such as the keyboard.
Taking a system crash dump using the sync command
Open Boot PROM 3
For complete documentation on the Open Boot PROM, see the Open Boot PROM Toolkit User's Guide and the
monitor(1M) man page. The examples in this section refer to a Sun4UTM architecture.
Other architectures might require different commands to perform actions.
Note - The Open Boot PROM is currently used on Sun machines with an
SBus or UPA/PCI. The Open Boot PROM uses an “ok” prompt. On older machines,
you might have to type `n' to get the “ok” prompt.
If the PROM is in secure mode (the security-mode parameter is not set
to none), the PROM password might be required (set in the security-password parameter).
The printenv command displays all parameters and their values.
Help is available with the help command.
EMACS-style command-line history is available. Use Control-N (next) and Control-P (previous) to traverse
the history list.
The Open Boot PROM uses the Forth programming language. Forth is a
stack-based language. Arguments must be pushed on the stack before running the correct command
(called a word), and the result is left on the stack.
To place a number on the stack, type its value.
To add the two top values on the stack, use the +
The result remains on the stack. The stack is shown with the
The default base is hexadecimal. The hex and decimal words can be
used to switch bases.
See the Forth User's Guide for more information.
Walking the PROMs Device Tree
The commands pwd, cd, and ls walk the PROM device tree to
get to the device. The cd command must be used to establish a
position in the tree before pwd will work. This example is from an
Ultra 1 workstation with a cgsix frame buffer on an SBus.
ok cd /
To see the devices attached to the current node in the tree,
The full node name can be used:
ok cd sbus@1f,0
Rather than using the full node name in the previous example, you
could also use an abbreviation. The abbreviated command-line entry looks like the following example:
ok cd sbus
The name is actually device@slot,offset (for SBus devices). The cgsix device is in
slot 2 and starts at offset 0. If an SBus device is displayed
in this tree, the device has been recognized by the PROM.
The .properties command displays the PROM properties of a device. These properties can
be examined to determine which properties the device exports. This information is useful
later to ensure that the driver is looking for the correct hardware properties.
These properties are the same properties that can be retrieved with ddi_getprop(9F).
ok cd cgsix
intr 00000005 00000000
reg 00000002 00000000 01000000
dblbuf 00 00 00 00
vmsize 00 00 00 01
The reg property defines an array of register description structures containing the following
uint_t bustype; /* cookie for related bus type*/
uint_t addr; /* address of reg relative to bus */
uint_t size; /* size of this register set */
For the cgsix example, the address is 0.
Mapping the Device
A device must be mapped into memory to be tested. The PROM
can then be used to verify proper operation of the device by using
data-transfer commands to transfer bytes, words, and long words. If the device can
be operated from the PROM, even in a limited way, the driver should
also be able to operate the device.
To set up the device for initial testing, perform the following steps:
Determine the SBus slot number the device is in.
In this example, the cgsix device is located in slot 2.
Determine the offset within the physical address space used by the device.
The offset used is specific to the device. In the cgsix example, the video memory happens to start at an offset of 0x800000.
Use the select-dev word to select the Sbus device and the map-in word to map the device in.
The select-dev word takes a string of the device path as its argument. The map-in word takes an offset, a slot number, and a size as arguments to map. Like the offset, the size of the byte transfer is specific to the device. In the cgsix example, the size is set to 0x100000 bytes.
In the following code example, the Sbus path is displayed as an argument to the select-dev word, and the offset, slot number, and size values for the frame buffer are displayed as arguments to the map-in word. Notice the space between the opening quote and / in the select-dev argument. The virtual address to use remains on top of the stack. The stack is shown using the .s word. The stack can be assigned a name with the constant operation.
ok " sbus@1f,0" select-dev
ok 800000 2 100000 map-in
ok constant fb
Reading and Writing
The PROM provides a variety of 8-bit, 16-bit, and 32-bit operations. In general,
a c (character) prefix indicates an 8-bit (one-byte) operation; a w (word) prefix
indicates a 16-bit (two-byte) operation; and an L (longword) prefix indicates a 32-bit (four-byte)
A suffix of ! indicates a write operation. The write operation takes the
first two items off the stack. The first item is the address, and
the second item is the value.
ok 55 ffe98000 c!
A suffix of @ indicates a read operation. The read operation takes the
address off the stack.
ok ffe98000 c@
A suffix of ? is used to display the value without affecting the
ok ffe98000 c?
Be careful when trying to query the device. If the mappings are
not set up correctly, trying to read or write could cause errors. Special
words are provided to handle these cases. cprobe, wprobe, and lprobe, for example, read
from the given address but return zero if the location does not respond,
or nonzero if it does.
ok fffa4000 c@
Data Access Error
ok fffa4000 cprobe
ok ffe98000 cprobe
A region of memory can be shown with the dump word. This takes
an address and a length, and displays the contents of the memory region
In the following example, the fill word is used to fill video memory
with a pattern. fill takes the address, the number of bytes to fill,
and the byte to use. Use wfill and an Lfill for words and
longwords. This fill example causes the cgsix to display simple patterns based on
the byte passed.
ok " /sbus" select-dev
ok 800000 2 100000 map-in
ok constant fb
ok fb 10000 ff fill
ok fb 20000 0 fill
ok fb 18000 55 fill
ok fb 15000 3 fill
ok fb 10000 5 fillok fb 5000 f9 fill