About Open Firmware for the Network Server
Contents
* Introduction
* Starting Up Open Firmware
* Using Open Firmware
* Open Firmware Command Summary
Introduction
Open Firmware provides features that enable you to access low-level information about your Network Server. Using Open Firmware, for example, you may examine settings stored in the server's non volatile memory (NVRAM).
Open Firmware is a standard software architecture for controlling a computer before the operating system begins execution. The complete specification for the Open Firmware standard is defined in the IEEE standard document IEEE P1275-1994 Standard for Boot Firmware. The Open Firmware software orchestrates how the hardware loads the operating system and defines which properties (or features) of the hardware are available for use by the operating system. The Open Firmware command language is based on Forth.
For the latest version of Open Firmware software and documentation, click the Network Server button at the World Wide Web site http:/www.solutions.apple.com. [
Note: this service and web site are no longer available].
Starting Up Open Firmware
To start up Open Firmware, hold down these keys while the server is restarting:
Command-Option-O-F
Enter Open Firmware commands at the
>ok prompt. Separate each command by one or more spaces. A summary of general commands available in this implementation of the IEEE standard is provided at the end of this section.
Using Open Firmware
These commands provide low-level information about your Network Server:
printenv
Displays configuration settings stored in NVRAM. For example, one configuration setting specifies the boot path for the operating system. This setting is named boot-device. There is also a setting named diag-device which identifies the boot path for loading diagnostics when the server key switch is in the left (service) position.
The configuration setting name appears in the left column, the current setting appears in the middle column, and the default setting is in the right column. Use the set-default command to restore default settings when appropriate. If you encounter difficulties starting up the Network Server operating system, try setting defaults. Also, you should copy down the current settings after you install the operating system. If you later experience problems starting up the operating system, you can use printenv to check the settings using this command to determine verify the configuration settings.
devalias
Displays name aliases to devices stored as properties in the device tree. A name alias is an abbreviated way of referring to a device path name. For example, to boot the Network Server Diagnostic Utility, you specify the name alias for the floppy drive,
fd:
boot fd:diags
probe-scsi1
Searches the Fast and Wide SCSI bus 0 and for each device attached displays the SCSI ID, the type of device, and other pertinent information such as the device's firmware version number. Use this command to verify that the devices in the top four drive trays are correctly recognized by the Network Server.
probe-scsi2
Searches the Fast and Wide SCSI bus 1 and for each device attached displays the SCSI ID, the type of device, and other pertinent information such as the device's firmware version number. Use this command to verify that the devices in the bottom four drive trays and the two rear bracket-mounted internal drives (Network Server 700 only) are correctly recognized by the Network Server.
dump-device-tree
Displays the device tree, which lists all features and devices in the Network Server encoded into a specific data format. Use the spacebar to control scrolling of the list.
The following command are used to change configuration settings stored in NVRAM. The
name-alias variable is the setting name. The
value variable can be a number, logical name (true, false), or a sequence of text.
setenv name-alias value
Use this command to change the specified configuration setting to the indicated value. For example, to change the OS boot device:
setenv boot-device disk3:aix
This adds disk 6 to the boot search path:
setenv diag-device cd disk6 fd:diags
set-default name-alias
This command restores the default of the named configuration setting. This example restores the boot device setting to
disk2:aix:
set-default boot-device
This command restores the default diagnostic device to
disk2:aix:
set-default diag-device
set-defaults
Restores the factory defaults for all the configuration settings.
Configuration Settings to Check in Case of Problems
If you encounter problems when the operating system starts up, check these configuration settings:
auto-boot?
Must be true in order to enable automatic booting of the operating system or the diagnostics when the key switch is the in the service position.
load-base
The Network Server Diagnostic Utility expects this number to be 4000 or greater.
diag-device
In order to be able to boot the Network Server Diagnostic Utility from the floppy drive, the value of
diag-device must include
fd:diags. Any device preceding
fd:diags must be unmounted or removed. For example, the default setting for
diag-device is
cd fd:diags. This means that the search order for a bootable device begins with the CD-ROM drive and proceeds to the floppy drive only if the CD-ROM drive does not contain a bootable CD. You must remove the CD-ROM disk in this case in order to boot the floppy drive.
boot-device
The factory default for booting the operating system is disk2 or the hard drive contained in drive tray three (Fast and Wide bus 0 SCSI ID 2). If this value becomes corrupt or changes, the AIX operating system won't boot. If you are unable to restore this setting to the default or you cannot change the setting with the
setenv boot-device command, then you may still be able to boot AIX by manually entering the boot command:
boot disk2:aix
Open Firmware Command Summary
Changing the Number Base & Number Input/Output Commands
| Command | Stack | Comment |
| decimal | ( -- ) | Set the number base to 10. |
| d# number | ( -- n) | Interpret the next number in decimal. |
| hex | ( -- ) | Set the number base to 16. |
| h# number | ( -- n) | Interpret the next number in hex. |
| u. | (n -- ) | Display the unsigned number. |
| .d | (n -- ) | Display n in decimal without changing number base system. |
| .h | (n -- ) | Display n in hex without changing base. |
| . | (n -- ) | Display a number in the Current base. |
| .s | ( -- ) | Display contents of data stack. |
Memory Access Commands
| Command | Stack | Comment |
| ! | (n adr16 -- ) | Store a 32-bit Number at adr16, 16-bit aligned. |
| @ | (adr16 -- n ) | Fetch a 32-bit Number from adr16. |
| c! | (n adr -- ) | Store low byte of n at adr. |
| c@ | (adr -- n ) | Fetch a byte from adr. |
| cpeek | (adr -- [byte] ok?) | Fetch the byte at adr. Return the data and true if the read access was successful. Return false if an error occurred. |
| cpoke | (byte adr -- ok?) | Store the byte to adr. Return true if the write access was successful. Return false if an error occurred. |
| comp | (adr1 adr2 len -- n) | Compare two byte arrays, n=0 if arrays are identical, n=1 if first byte that is different is greater in array#1, n= -1 otherwise. |
| dump | (adr len -- ) | Display len bytes of memory from adr. |
| fill | (adr size byte -- ) | set size bytes of memory to byte. |
| l! | (n adr32 -- ) | Store a 32-bit number at adr32, 32-bit aligned. |
| l@ | (adr32 -- n) | Fetch a 32-bit number from adr32. |
| lpeek | (adr -- [long] ok?) | Like cpeek, but 32-bit access. |
| lpoke | (long adr -- ok?) | Like cpoke, but 32-bit access. |
| move | (adr1 adr2 n -- ) | Copy n bytes from adr1 to adr2. |
| w! | (n adr16 -- ) | Store a 16-bit number at adr16. |
| w@ | (adr16 -- n) | Fetch a 16-bit number from adr16. |
| wpeek | (adr -- [word] ok?) | Like cpeek, but 16-bit access. |
| wpoke | (word adr -- ok?) | Like cpoke, but 16-bit access. |
Memory Mapping Commands
| Command | Stack | Comment |
| do-map | (phys virt size mode -- ) | Map a region of 32-bit physical address at phys to a region of 32-bit virtual address at virt, the mode is 0 for Memory and 0x28 for input/output normally. Open Firmware turns on MMU translation and uses virtual address for Memory |
| do-unmap | ( virt size -- ) | Unmap the previous mapped region. |
PCI Registers Access Commands
| Command | Stack | Comment |
| rb! | (n adr -- ) | Store low byte of n at adr. |
| rb@ | (adr -- n) | Fetch a byte from adr. |
| rl! | (n adr32 -- ) | Store a 32-bit number at adr32, 32-bit aligned. |
| rl@ | (adr32 -- n ) | Fetch a 32-bit number from adr32. |
| rw! | (n adr16 -- ) | Store a 16-bit number at adr16. |
| rw@ | (adr16 -- n ) | Fetch a 16-bit number from adr16. |
| Note: For big endian registers use xb!, xb@, xl!, xl@, rw!, rw@ instead. If the (big endian) register access doesn't require special instruction such as eieio, it may use c!, c@, l!, l!, w!, w@. |
Stack Manipulation Commands
| Command | Stack | Comment |
| bounds | (start-adr size -- end-adr start-adr) | This is equal to:over + swap |
| 2drop | (n1 n2 -- ) | Remove two items from the stack. |
| 2dup | (n1 n2 -- n1 n2 n1 n2) | Duplicate two items. |
| clear | (??? -- ) | Empty the stack. |
| drop | (n -- ) | Remove one item from the stack. |
| dup | (n -- n n) | Duplicate the top stack item. |
| over | (n1 n2 -- n1 n2 n1) | Copy the second item to the top. |
| rot | (n1 n2 n3 -- n2 n3 n1) | Rotate three stack items. |
| swap | (n1 n2 -- n2 n1) | Exchange the top two items. |
Arithmetic Commands
| Command | Stack | Comment |
| * | (n1 n2 -- n3) | Multiply n1 * n2 |
| + | (n1 n2 -- n3) | Add n1 + n2 |
| - | (n1 n2 -- n3) | Subtract n1 - n2 |
| / | (n1 n2 -- n3) | Divide n1 / n2 (truncated) |
| << | (n1 n2 -- n3) | Left shift n1 by n2 bits |
| >> | (n1 n2 -- n3 ) | Right shift n1 by n2 bits |
| and | ( n1 n2 -- n3) | Bitwise logical and |
| mod | (n1 n2 -- n3) | Remainder of n1 / n2 |
| not | (n1 -- n2) | Bitwise logical inversion |
| or | (n1 n2 -- n3) | Bitwise logical or |
| xor | (n1 n2 -- n3) | Bitwise logical exclusive or. |
Examining and Creating Device Aliases
| devalias | Display all current device aliases. |
| devalias <alias> | Display the device path name corresponding to <alias>. |
| devalias <alias> <device-pathname> | Define an <alias> representing the <device-pathname>. |
Device Tree Browsing Commands
| dump-device-tree | Dump the whole system device tree. |
| .properties | Display the names and values of the current device node's properties. |
| dev <device-pathname> | Select the indicated device node, making it the current node. |
| dev <node-name> | Search for a node with 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. |
| show-devs <device-pathname> | Display all the devices directly beneath the given device. For example, show-devs /bandit |
| device-end | Leave no node selected. |
| ls | Display children of the current node. |
| pwd | Display the current device path name. |
| words | Display the names of the current node's methods. |
| select-dev (str,len -- ) | Select the desired device node in order to execute the device methods under it. This requires all nodes of the desired device path have open method. |
| unselect-dev | Unselect the previous selected device node. |
If-then-else Commands
| else ( -- ) | Execute the following code if 'if' failed. |
| if (flag -- ) | Execute the following code if flag is true. |
| then ( -- ) | Terminate if ... then ... else. |
Begin (conditional) Loop Commands
| again ( -- ) | End a begin ... again infinite loop. |
| begin ( -- ) | Begin a begin ... while ... repeat, begin ... until, or begin ... again loop. |
| repeat ( -- ) | End a begin ... while ... repeat loop. |
| until (flag -- ) | Continue executing a begin ... until loop until flag is true. |
| while (flag -- ) | Executing a begin ... while ... repeat loop while flag is true. |
Do (Counted) Loop Commands
| +loop (n -- ) | End a do ... +loop construct; add n to loop index and return to do (if n < 0, index goes from start to end inclusive). |
| do (end start -- ) | Begin a do ... loop. Index goes from start to end-1 inclusive. Example: 10 0 do i . loop |
| i ( -- n) | Loop index. |
| j ( -- n) | Loop index for next enclosing loop. |
| leave ( -- ) | Exit from do ... loop. |
| loop ( -- ) | End of do ... loop. |
Comparison Commands
| < | (n1 n2 -- flag) | True if n1 < n2. |
| <= | (n1 n2 -- flag) | True if n1 <= n2. |
| <> | (n1 n2 -- flag) | True if n1 <> n2. |
| = | (n1 n2 -- flag) | True if n1 = n2. |
| > | (n1 n2 -- flag) | True if n1 > n2. |
Controlling Text Input Commands & Display Text Output Commands
ascii <c>( -- n)
Get numerical value of first ASCIIcharacter of next word.
key ( -- char)
Read a character from the assigned input device's keyboard.
key? ( -- flag)
True if a key has been typed on the input device's keyboard.
cr ( -- )
Go to the next line on the display.
File Loading Commands
boot [specifiers]
Boot file from specified source.
dl
Load a Forth file over a serial line.
init-program
Initialize to execute a binary file.
load [specifiers]
Load data from specified device.
NOTE: Use boot (or load) one of these four ways:
(1) boot
(2) boot <device-specifier>
(3) boot <arguments>
(4) boot <device-specifier> <arguments>
NOTE: When using the floppy drive (name-alias is fd), the disk must be high density 1.4 MB formatted for the MacOS or DOS environments.
(1) For a MacOS floppy, <device-specifier> is fd:<filename>
(2) For a DOS floppy, <device-specifier> is fd:,<filename>
Defining Words
: <name>( -- ) Start creating a new command word.
; ( -- ) Finish creating the new word.
Manipulating Text Strings
" <string>"( -- adr len ) Collect an input string.
Redirecting I/O
input (device-str -- )
Select the indicated device for console input, device may be a device name-alias.
io (device-str -- )
Select device for subsequent input and output. Eg. ttyb:9600
output (device-str -- )
Select the indicated device for console output. Eg. screen output
Emergency Keyboard Commands
NOTE: Hold down keys during Open Firmware power on sequence.
Command-Option-O-F Abort auto booting if auto-boot? is true.
Command-Option-P-R Reset NVRAM contents to default values.
Miscellaneous Operation Commands
eject [fd]
Eject the floppy disk from the drive.
get-msecs ( -- ms )
Return the approximate current time in milliseconds.
ms ( n -- )
Delay for n milliseconds. Resolution is 1 millisecond.
reset-all
Reset the entire system (similar to a power cycle).
PowerPC Register Commands
| %r0 through %r31 | ( -- value) | Return saved copy of the given register. |
| %srr0 & %srr | ( -- value) | Return saved copy of Save/Restore reg. |
| %sprg0 through %sprg3 | ( -- value) | Access saved copies of SPRG registers. |
| %cr | ( -- value) | Return saved copy of Condition Register. |
| %ctr | ( -- value) | Return saved copy of Counter Register. |
| %lr | ( -- value) | Return saved copy of Link Register. |
| %xer | ( -- value) | Return saved copy of XER register. |
| msr@ | ( -- value) | Return current value of Machine State Register. |
| msr! | (value --) | Set new value of Machine State Register. |
| sprg3@ | ( -- value) | Get current interrupt vector pointer. |
| sprg3! | ( value --) | Set our interrupt vector pointer. |
| .registers | | Display the PowerPC CPU's saved program state. |
NVRAMRC Editor Commands
nvalias <alias> <Device-pathname>
Store the command "devalias <alias> <Device-pathname>" in NVRAMRC. (The alias persists until the nvunalias or set-defaults commands are executed or NVRAM is reset.)
nvedit
Enter the NVRAMRC editor. If data remains in the temporary buffer from a previous nvedit session, resume editing the previous contents. If not, read the contents of NVRAMRC into the temporary buffer and begin editing it.
nvquit
Discard the contents of the temporary buffer without writing it to NVRAMRC.
nvrecover
Recover the contents of NVRAMRC if they have been lost
nvrun
Evaluate the temporary buffer.
nvstore
Copy the contents of the temporary buffer to NVRAMRC; discard the contents of the temporary buffer.
nvunalias <alias>
Delete the corresponding alias from NVRAMRC.
^c (Control-C) Quit nvedit and get back to the ok prompt.