TITLE
    Apple Network Server 500,700: Open Firmware Read Me
Article ID:
Created:
Modified: 		60285
4/16/99
4/16/99
TOPIC

    This article contains a comprehensive overview of Apple's implementation of PCI Open Firmware on the Apple Network Servers 500 and 700. While it is a reference specific to that particular product line, Open Firmware is an industry cross-platform standard, and most of the information included applies broadly to all PCI Macintosh systems.

DISCUSSION

    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.

Document Information
Product Area: Computers
Category: Apple Network Server
Sub Category: Network Server 500 & 700
Keywords: kppc, kmosXserver

Copyright © 2000 Apple Computer, Inc. All rights reserved.