1 SBus Cards and FCode

Each SBus card must have a PROM whose contents identify the device and its characteristics.

The SBus card's PROM may also include an optional software driver that lets you use the card as a boot device or a display device during booting. The software driver may also include diagnostic selftest code.

In addition to designing hardware, the process of developing SBus devices may include writing, testing, and installing FCode drivers for the device. These drivers, if present, serve three functions:

• To exercise the device during development, and to verify its functionality.

• To provide the necessary driver to be used by the system boot PROM during power-up.

• To provide device configuration information.

In practice, these functions overlap substantially. The same code needed by the system boot PROM usually serves to significantly test the device as well, although additional code may be desired to fully verify proper behavior of the device. The PROM code is used before and during the boot sequence. After the boot sequence finishes, and while not using the OpenBoot Forth Monitor, most SBus device use is through SunOS drivers.

SBus device PROMs must be written in the FCode programming language, which is similar to Forth-83. FCode is described in more detail in Chapter 2, "Elements of FCode Programming".

FCode PROM Format

An FCode PROM begins at address 0 within the SBus card's physical address space. Its size can range from 30 bytes up to 32K bytes. Typical sizes are 60 bytes (for a simple card that identifies itself but does not need a driver) and 1- 4K bytes (for a card with a boot driver). It is good practice to make FCode boot drivers as short as is practical.

An FCode PROM must be organized as follows:

• Header (8 bytes: consisting of magic number, version number, length, checksum).

• Body (FCode program; 0 or more bytes).

• End Token (either End0, a zero byte, or End1, an alternative all 1's byte).

Interpreting FCode

For each SBus slot, the FCode program is interpreted during bootup as follows:

• Location 0 of the SBus PROM is read with an 8-bit or 32-bit access. If there is no response (as when there is no card in that slot), the slot is subsequently ignored.

• If the high-order byte of the value returned from the first access is not the FCode magic numbers 0xfd or 0xf1, the slot is subsequently ignored.

• If the high-order byte is 0xfd or 0xf1, the PROM is assumed to contain a valid FCode program. The FCode is then interpreted by starting at location 0 and reading one byte at a time, executing a procedure associated with each FCode value.

• Interpretation ceases when the FCode 0x00 or 0xff (End0 or End1) is encountered.

Device Identification

An FCode PROM must identify its device. This identification must include, at a minimum, the driver name, used to link the device to its SunOS driver. Identification information may include additional characteristics of the device for the benefit of the operating system and the CPU boot PROM.

In most systems, the CPU's FCode interpreter will store each device's identification information in a device tree that has a node for each device. Each device node has a property list that identifies and describes the device. The property list is created as a result of interpreting the program in the FCode PROM.

Each property must have a name and a value. The name is a string and the value is an array of bytes, which may encode strings, numbers, and various other data types.

See Chapter 5, "Properties" for more information.

Creating and Executing FCode Definitions

Many FCode programs create executable routines, called colon definitions (or methods) that typically read from and write to device locations to control device functions. These definitions are also stored in the device tree node for that device.

Once defined, these routines may typically be executed under any of the following circumstances:

• Interactively at the OpenBoot ok prompt (for selftest or other purposes).

• By the OpenBoot system (for using this boot or display system during system start-up).

• Automatically during FCode interpretation (for power-on initialization or other purposes).