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 if the device is working correctly.
The PROM has several purposes; it serves to:
Bring the machine up from power on, or from a hard reset PROM reset command.
Provide an interactive tool for examining and setting memory, device registers, and memory mappings.
Boot the SunOS system or the kernel debugger kadb(1M).
Simply powering up the computer and attempting to use its PROM to examine device registers will likely fail. While the device may be correctly installed, those mappings are SunOS specific and do not become active until SunOS is booted. Upon power up, the PROM maps only essential system devices, such as the keyboard.
For complete documentation on the Open Boot PROM, see the Open Boot PROM Toolkit User's Guide and monitor(1M). The examples in this section refer to a Sun-4u architecture; other architectures may require different commands to perform actions.
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, it may be necessary 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 may 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. This is a stack-based language; arguments must be pushed on the stack before running the desired command (called a word), and the result is left on the stack.
To place a number on the stack, type its value.
ok 57ok 68
To add the two top values on the stack, use the + operator.
The result remains on the stack. The stack is shown with the .s word.
The default base is hexadecimal. The hex and decimal words can be used to switch bases.
ok decimalok .s191
See the Forth User's Guide for more information.
The SunOS-like 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, use ls.
ok lsf006a064 SUNW,UltraSPARC@0,0 f00598b0 sbus@1f,0 f00592dc counter-timer@1f,3c00 f004eec8 virtual-memory f004e8e8 memory@0,0 f002ca28 aliases f002c9b8 options f002c880 openprom f002c814 chosen f002c7a4 packages
The full node name can be used:
ok cd sbus@1f,0ok lsf006a4e4 cgsix@2,0 f0068194 SUNW,bpp@e,c800000 f0065370 ledma@e,8400010 f006120c espdma@e,8400000 f005a448 SUNW,pll@f,1304000 f005a394 sc@f,1300000 f005a24c zs@f,1000000 f005a174 zs@f,1100000 f005a0c0 eeprom@f,1200000 f0059f8c SUNW,fdtwo@f,1400000 f0059ec4 flashprom@f,0 f0059e34 auxio@f,1900000 f0059d28 SUNW,CS4231@d,c000000
Rather than using the full node name in the previous example, you could have used an abbreviation. The abbreviated command line entry looks like this:
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 can be examined to determine which properties the device exports (this is useful later to ensure that the driver is looking for the correct hardware properties). These are the same properties that can be retrieved with ddi_getprop(9F). See sbus(4) and "Properties" for related information.
ok cd cgsixok .propertiescharacter-set ISO8859-1 intr 00000005 00000000 interrupts 00000005 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 fields:
u_int bustype; /* cookie for related bus type*/ u_int addr; /* address of reg relative to bus */ u_int size; /* size of this register set */
For the cgsix example, the address is 0.
To test the device, it must be mapped into memory. 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 that there should be a 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. It can be assigned a name with the constant operation.
ok "/sbus@1f,0" select-dev ok 800000 2 100000 map-inok .sffe98000 ok constant fb
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) operation.
A suffix of ! is used to indicate 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 @ is used to indicate a read operation. The read operation takes one argument (the address) off the stack.
ok ffe98000 c@ok .s55
A suffix of ? is used to display the value, without affecting the stack.
ok ffe98000 c?55
Be careful when trying to query the device. If the mappings are not set up correctly, trying to read or write could cause errors. There are special words 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 cprobeok .s0 ok ffe98000 cprobeok .s0 ffffffffffffffff
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 bytes.
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 (there is also a wfill and an Lfill for words and longwords). This causes the cgsix to display simple patterns based on the byte passed.
ok " /sbus" select-dev ok 800000 2 100000 map-in ok constant fbok fb 10000 ff fillok fb 20000 0 fillok fb 18000 55 fillok fb 15000 3 fillok fb 10000 5 fillok fb 5000 f9 fill
Certain machine-specific interrupt levels are ignored when the Open Boot PROM controls the machine.