C H A P T E R 1 - SBus Cards and FCode

C H A P T E R 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.

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, perform three functions:

Exercising the device during development, and verifying its functionality

Providing the necessary driver to be used by the system boot PROM during power-up

Providing 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 Solaris trademark drivers.

SBus device PROMs must be written in the FCode programming language, which is similar to ANS Forth. FCode is described in more detail in Chapter 3.

This chapter includes the following sections:

FCode PROM Format

Interpreting FCode

Device Identification

Creating and Executing FCode Definitions

FCode PROM Format

An FCode PROM begins at address 0 in the SBus card's physical address space. Its size can range from 30 bytes up to 32Kbytes. Typical sizes are 60 bytes (for a simple card that identifies itself but does not need a driver) and 5 to 15Kbytes (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 1s byte)

Interpreting FCode

For each SBus slot, the FCode program is interpreted during boot 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 number 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 device name used to link the device to its Solaris 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 7 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

By the OpenBoot system (for using this boot or display system during system startup)

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