Writing FCode 3.x Programs

This chapter describes characteristics of hardware devices, software, and user selections. It includes the following sections:

• Standard FCode Properties
• Detailed Descriptions of Standard Properties
• Manipulating Properties
• Property-Specific FCodes

Properties are associated with the device node in which they are created and are accessible by bothOpenBoot routines and client programs. Properties can be inspected and, in some cases, modified.

Each property has a property name and a property value.

• Property names are human-readable strings consisting of 1 to 31 printable, lowercase letters and symbols not including blanks, or any of the following characters: /, \, :, [ , ] , or @. Property names beginning with "+" are reserved for future use by IEEE Standard 1275-1994 Standard for Boot Firmware.
• Property values specify the contents, or value, of a particular property. The value is an array of bytes that may be used to encode integer numbers, text strings, or other forms of information.

Properties are accessed by name. Given a property's name, it is possible to determine whether that property has been defined and, if so, what its value is.

Property values are encoded as arrays of zero or more bytes for portability across machine architectures. The encoding and decoding procedures are defined by IEEE Standard 1275-1994 Standard for Boot Firmware. The encoding format is independent of hardware byte order and alignment characteristics. The encoded byte order is big-endian and the bytes are stored in successive memory locations without any padding.

The format of the property value array associated with a given property name is specific to that property name. There are five basic types of property value array formats:

• Flag

Since property value arrays may be of zero length, properties may convey "true" or "false" information by their presence or absence.

• Byte

An array of one or more bytes is stored in a property value array as a series of sequential bytes in the property value array.

• 32-bit integer

A 32-bit integer is stored in a property value array in four successive bytes. The most significant byte of the integer in the next available address in the property value array is followed by the high middle, low middle, and least significant bytes of the integer (in other words, in big-endian format).

• Text string

A text string of n printable characters is stored in a property value array in n+1 successive locations by storing the string in the first n locations followed by a byte of zero value (in other words, a null terminated string).

• Composite

A composite value is made up of the concatenation of encoded bytes, encoded 32-bit integers, or encoded strings. Each such primitive is stored immediately after the preceding primitive with no intervening space (in other words, the items are packed). Here are examples of composite values:

1. physical address range. Encoded as 4 integers: phys.lo phys.mid phys.hi size

2. array. The concatenation of n items of some type.

The standard defines a number of standard properties with specified names and value formats. If a package uses one of these standard properties then the value format of the property must be as defined by the standard. Packages may define other properties whose names do not conflict with the list of standard properties. Such newly defined properties may have any value format.

Properties may be created by FCode programs. The CPU's OpenBoot is able to use property names that tell it such things as the device type (disk, tape, network, display, and so on) to determine how to use the device (if at all) during the boot process.

The Solaris operating environment recognizes other property names that give information for configuring the operating system automatically. These properties include the driver name, the addresses and sizes of the device's registers, and interrupt levels and interrupt vectors used by the device.

Other properties may be used by individual operating system device drivers. The names of such properties and the interpretation of their values is subject to agreement between the writers of the FCode programs and the operating system driver, but may otherwise be arbitrarily chosen. For example, a display device might declare width, height, and depth properties to allow a single operating system driver to automatically configure itself for one of several similar but different devices.

A package's properties identify the characteristics of the package and its associated physical device, if any. You can create a property either with the property FCode, or with the name, reg, model, and device-type FCodes, described below.

For example, a frame buffer package might export its register addresses, interrupt levels, and frame buffer size. Every package has an associated property list, which is arbitrarily extensible. The user interface command.properties displays the names and values of the current node's properties.

For example, if a property named foo is created in a device node which already has a property named foo, the new property supersedes the old one.

New properties can be added during the lifetime of a product. For backward compatibility, an FCode or device driver program that needs the value of a particular property should determine whether or not the property exists, and if not, the program should supply its own default value.

---

Standard FCode Properties

IEEE Standard 1275-1994 Standard for Boot Firmware defines the following standard properties. A package should never create a property using any of the following names, unless the defined meanings and structures are used.

Standard Property Names

This group of properties applies to all device nodes regardless of type. The name property is required in all packages. The remaining properties are optional.

Display Device Properties

Display devices include bitmapped frame buffers, graphics displays, and character-mapped displays. Display devices are typically used for console output. The following properties are specific to display devices:

Network Device Properties

Network devices are packet-oriented devices capable of sending and receiving Ethernet packets. Network devices are typically used for booting.

Memory Device Properties

Memory devices are traditional random-access memory, suitable for temporary storage of data.

General Properties for Parent Nodes

Properties for PCI Parent Nodes

Properties for PCI Child Nodes

The following definitions are specified by the PCI Bus Binding to IEEE Standard 1275-1994.

Each of the following PCI child node properties is created during the probing process, after the device node has been created, and before evaluating the device's FCode (if any). The property values are those found in the standard PCI configuration registers.

Unless otherwise specified, each of the following properties has a property value created by encoding the value contained in the associated hardware register with encode-int.

• vendor-id
• device-id
• revision-id
• class-code
• interrupts

This property is present only if the interrupt pin register is nonzero.

• min-grant
• max-latency
• devsel-speed
• fast-back-to-back

This property is present only if the fast back-to-back bit (bit 7) of the function's status register is set.

---

Detailed Descriptions of Standard Properties

#address-cells

This property applies only to bus nodes. It specifies the number of cells that are used to represent a physical address with a bus's address space.

The value for SBus nodes is 2, for PCI bus nodes is 3.

#size-cells

This property applies only to bus nodes. It specifies the number of cells used to represent the length of a physical address range (in other words, the size field of a child's reg property).

The value for SBus nodes is 1, for PCI bus nodes is 2.

address

This property declares currently mapped device virtual addresses. It is generally used to declare large regions of existing mappings in order to enable the operating system device driver to reuse those mappings, thus conserving system resources. This property should be created after virtual addresses have been assigned by mapping operations. It should be deleted when the corresponding virtual addresses are unmapped.

The property value is an arbitrary number of virtual addresses. The correspondence between declared addresses and the set of mappable regions of a particular device is device-dependent.

Usage:

-1 value my-buffers

-1 value my-dma-addr

: map-me ( -- )

   my-address my-space 1.0000 " map-in" $call-parent  ( virt1 )

   to my-buffers

   2000 " dma-alloc" $call-parent  ( virt2 )  to my-dma-addr

   my-buffers encode-int  my-dma-addr encode-int  encode+

   " address" property

;

: unmap-me  ( -- )

   my-dma-addr 2000 " dma-free" $call-parent

   my-buffers 1.0000 " map-out" $call-parent

   " address" delete-property

;

See also: free-virtual, property.

address-bits

When declared in network devices, this property indicates the number of address bits needed to address this device on its network.

Usage:

d# 48 encode-int " address-bits" property

See also: property and Chapter 11.

alternate-reg

This property describes alternative access paths for the addressable regions described by the reg property. Typically, an alternative access path exists when a particular part of a device can be accessed either in memory space or in I/O space, with a separate base address register for each of the two access paths. The primary access paths are described by the reg property and the secondary access paths, if any, are described by the alternate-reg property.

If no alternative paths exist, the alternate-reg property should not be defined.

If the device has alternative access paths, each entry (each phys-addr size pair) of its value represents the secondary access path for the addressable region whose primary access path is in the corresponding entry of the reg property value. If the number of alternate-reg entries exceeds the number of reg property entries, the additional entries denote addressable regions that are not represented by reg property entries, and are thus not intended to be used in normal operation; such regions might, for example, be used for diagnostic functions.

If the number of alternate-reg entries is less than the number of reg entries, the regions described by the extra reg entries do not have alternative access paths. An alternate-reg entry whose phys.hi component is zero indicates that the corresponding region does not have an alternative access path; such an entry can be used as a placeholder to preserve the positions of later entries relative to the corresponding reg entries. The first alternate-reg entry, corresponding to the reg entry describing the function's configuration space registers, has a phys.hi component of zero.

The property value is an arbitrary number of (phys-addr, size) pairs where:

• phys-addr is (phys.lo phys.mid phys.hi), encoded with encode-phys.
• size is a pair of integers, each encoded with encode-int. The first integer denotes the most significant 32 bits of the 64-bit region size. The second integer denotes the least significant 32 bits.

assigned-addresses

This property describes the location and size of regions of physical address space that are specified in the device's configuration space base address registers.

The property value is zero to six (phys-addr, size) pairs where:

• phys-addr is (phys.lo phys.mid phys.hi), encoded with encode-phys.
• size is a pair of integers, each encoded with encode-int. The first integer denotes the most significant 32 bits of the 64-bit region size. The second integer denotes the least significant 32 bits.

Each (phys-addr, size) pair in this property value corresponds to one (or two, in the case of 64-bit-address memory space) of the function's configuration space base address registers. The entry indicates the physical address that has been assigned to that base address register and the size in bytes of the assigned region. The size is a power of two, since the structure of PCI base address registers forces the decoding granularity to powers of two. Please see the glossary entry for this property for a complete description of the formatting details.

available

This property defines the resources that are managed by this package (in other words, /memory or /mmu) that are currently available for use by a client program.

The property value is an arbitrary number of (phys-addr, length) pairs where:

• phys-addr is (phys.lo phys.mid phys.hi), encoded with encode-int
• length (whose format depends on the package) is one or more integers, each encoded with encode-int

big-endian-aperture

This property is associated with display devices. Encoded identically to reg for the corresponding bus, the property value contains the address of the big-endian aperture of the frame buffer (in other words, the address range through which the frame buffer can be addressed in big-endian mode).

bus-range

This property specifies the range of bus numbers controlled by this PCI bus. The property value is two integers, each encoded with encode-int. The first integer represents the bus number of the PCI bus implemented by the bus controller represented by this node. The second integer represents the largest bus number of any PCI bus in the portion of the PCI domain that is subordinate to this node.

character-set

When declared in display or serial devices, this property indicates the recognized character set for this device. The property value is a text string.

A typical value is "ISO8859-1". 8859-1 is the number of the ISO specification for that particular character set, which essentially covers the full range of western European languages. To get a list of possible values, consult the X registry for which there is an address in the X11R5 documentation.

Usage:

" ISO8859-1" encode-string " character-set" property

See also: property, Chapter 9 and Chapter 12.

class-code

This property contains the value of the class code register from the configuration space header. This register identifies the generic function of the device and (in some cases) a specific register-level programming interface.

The property value is the register's value encoded with encode-int.

See also: PCI Local Bus Specification.

compatible

This property specifies a list of devices with which this device is compatible. The property is typically used by client programs to determine the correct driver to use with the device in those cases where the client program does not have a driver which matches the name property.

The property value is the concatenation (with encode+) of an arbitrary number of text strings (encoded with encode-string) wherein each text string follows the formatting conventions as described for the "name" property.

See also: name.

depth

This property is associated with display devices. Encoded with encode-int, the property value specifies the number of bits in each pixel of the display.

device-id

This property contains the value of the device ID register from the configuration space header. That register identifies the particular device. The encoding of the register is determined by the device vendor.

The property value is the register's value encoded with encode-int.

See also: PCI Local Bus Specification.

device_type

This property declares the type of this plug-in device. The type need not be declared unless this device is intended to be used for booting. If this property is declared using one of the following key values, the FCode program must follow the required conventions for that particular type of device by implementing a specified set of properties and procedures (methods).

Usage:

" display" encode-string " device_type" property

Defined values for this property are:

See also: device-type, property.

devsel-speed

This property contains the value of the DEVSEL timing field (bits 9-10) of the status register from the configuration space header. This field describes the timing of the DEVSEL# output of the device.

The property value is the register's value encoded with encode-int. A value of 0 indicates fast, 1 indicates medium and 2 indicates slow timing.

See also: PCI Local Bus Specification.

existing

This property specifies all of the region's physical addresses actually installed in the system.

fast-back-to-back

This property should be present only if the fast back-to-back capable field (bit 7) is set in the status register from the configuration space header. That field indicates whether the device is capable of accepting fast back-to-back transactions when the transactions are not to the same agent.

See also: PCI Local Bus Specification.

has-fcode

This property should be present only if the creation of this device node involved the evaluation of an FCode program, rather than automatic creation from information in configuration registers.

height

This property is associated with display devices. Encoded with encode-int, the property value specifies the number of displayable pixels in the "y" direction of the display.

interrupts

This optional property declares the interrupt level(s) for this plug-in device. The contents are one or more integers. Note that the bus-level interrupt (not the CPU-level interrupt) is specified.

For SBus devices, SBus interrupt levels 1-7 are allowed. The correct choice for your interrupt level will depend on your latency requirements. Typical usage is as follows:

• video - SBus level 5
• Ethernet - SBus level 4
• SCSI - SBus level 3
• DMA - SBus level 3

SBus levels 6 and 7 should only be used with great care. Otherwise significant system performance degradation may occur.

Because of previous usage of the intr property in earlier systems, it is recommended that both intr and interrupts be declared in FCode for SBus cards. However, cards which only declare intr should continue to work, as current systems automatically generate the interrupts property as required.

To declare a single interrupt (level 5):

5 encode-int " interrupts" property

To declare two interrupts (levels 3 and 5):

5 encode-int 3 encode-int encode+  " interrupts" property

See also: interrupts, property.

For PCI devices, this property should be present only if the function represented by this node is connected to a PCI expansion connector's interrupt line. The value of this property is determined from the contents of the interrupt pin register from the configuration space header.

The property value is the register's value encoded with encode-int. The defined values are:

The interrupts property is used to report the interrupt pin that the card uses, strictly within the domain of interrupts defined by the PCI specification. It is the responsibility of the operating system's PCI bus driver code to translate the interrupts reported by its children into the interrupt domain of its parent. This makes it possible to write portable, system-independent FCode drivers because the FCode driver does not need to know how the system handles interrupts. The system-specific information is known by the system component code that actually performs the hardware mapping from PCI interrupt pins to whatever interrupt facilities exist on the system. In some cases, the mapping may even be hierarchical. For example, a UPA-to-PCI bus bridge might translate PCI interrupt pins into UPA interrupt vectors.

See also: PCI Local Bus Specification.

linebytes

This property is associated with display devices. Encoded with encode-int, the property value specifies the number of pixels between consecutive scan lines of the display.

little-endian-aperture

This property is associated with display devices. Encoded identically to reg for the corresponding bus, the property value contains the address of the little-endian aperture of the frame buffer (in other words, the address range through which the frame buffer can be addressed in little-endian mode).

local-mac-address

Used with devices whose device_type is network, this property should be present only if the device has a built-in 48-bit IEEE 802.3-style media access control (MAC) address. The system may or may not use this address in order to access this device. Encoded with encode-bytes.

See also: mac-address, property, and Chapter 11.

mac-address

This property must be created by the open method of network devices to indicate the media access control (MAC) address that this device is currently using. This value may or may not be the same as any local-mac-address property.

This property is typically used by client programs that determine which network address was used by the network interface from which the client program was loaded.

The property value is the six-byte MAC address encoded with encode-byte. Here's how it is composed:

1. If a plug-in device has an assigned MAC address from the factory, this address is published as the value for local-mac-address.

2. The system (based on various factors such as presence or absence of local-mac-address and the value of the NVRAM parameter local-mac-address?) determines the address for the plug-in device to use. The value returned by the mac-address FCode is set to this address.

3. The plug-in device then reports the address it is using by publishing the mac-address property.

For example:
For a plug-in network device which has a factory-unique MAC address but can use another system-supplied MAC address if desired by the system, the FCode would appear as:

create mac-address 8 c, 0 c, 20 c, 0 c, 14 c, 5e c,

mac-address              encode-bytes  " mac-address"        property

\(plus code to "assign" the correct mac-address value into registers)

See also: mac-address, local-mac-address, property, and Chapter 11.

max-frame-size

When declared in network devices, this property indicates the maximum packet size (in bytes) that the physical layer of the device can transmit. This property can be used by client programs to allocate buffers of the appropriate length.

Usage:

4000 encode-int  " max-frame-size" property

See also: property and Chapter 11.

max-latency

This property contains the value of the Max_Lat register from the configuration space header. That register specifies how frequently the device needs to gain access to the PCI bus. The value is given in units of 250 nanoseconds. A value of zero indicates that the device has no major requirements for the setting of the latency timers.

The property value is the register's value encoded with encode-int.

See also: PCI Local Bus Specification.

min-grant

This property contains the value of the Min_Gnt register from the configuration space header. That register specifies how long a burst period the device needs, assuming a clock frequency of 33 MHz. The value is given in units of 250 nanoseconds. A value of zero indicates that the device has no major requirements for the setting of the latency timers.

The property value is the register's value encoded with encode-int.

See also: PCI Local Bus Specification.

model

This property identifies the model name and number (including revision) for a device for manufacturing and field service purposes.

The model property is useful to identify the specific piece of hardware (the plug-in card), since several different but functionally equivalent cards could have the same name property, thus calling the same device driver. Although the model property is good to have in general, it does not have any other specific purpose.

The property value format is arbitrary, but conventional usage is to begin the string with the manufacturer's name (as with the name property) and to end it with the revision level.

Usage:

" SUNW,501-1415-1" encode-string " model" property

See also: name, property.

name

This property specifies the manufacturer's name and device name. All device nodes must publish this property. The name property can be used to match a particular operating system device driver with the device.

The property value is an arbitrary string. Any combination of 1 to 31 printable characters is allowed, except for @, :, or /. The string may contain one comma at most. Embedded spaces are not allowed.

IEEE Standard 1275-1994 Standard for Boot Firmware specifies three different formats for the manufacturer's name portion of the property value where two of those formats are strongly preferred.

For United States companies that have publicly listed stock,for example, the most practical form of name is to use the company's stock symbol (such as SUNW for Sun Microsystems, Inc.). This option is also available to any company in the world provided that there is no duplication of the company's stock symbol on either the New York Stock Exchange or the NASDAQ Exchange. If a non-U.S. company's stock is traded as an American Depository Receipt (ADR), the ADR symbol satisfies this requirement. A prime advantage of this form of manufacturer's name is that such stock symbols are very human-readable.

Alternatively, a company may obtain an organizationally unique identifier (OUI) from the IEEE Registration Authority Committee. This is a 24-bit number that is guaranteed to be unique worldwide. Companies that have obtained an OUI would use a sequence of hexadecimal digits of the form "0NNNNNN" for the manufacturer's name portion of the property. This form of name has the disadvantage that the manufacturer is not easily recognizable.

Each manufacturer may devise its own format for the device name portion of the property value.

Here is a usage example:

" SUNW,bison-printer" encode-string  " name" property

You may also use the name command to create this property.

See also: property, device-name.

page-size

This property specifies the number of bytes in the smallest mappable region of virtual address space managed by the /mmu package.

power-consumption

This property describes the device's maximum power consumption (in microwatts) categorized by the various power rails and the device's power management state (standby or fully on).

The property value is a list of up to ten integers encoded with encode-int in the following order:

• Unspecified standby
• Unspecified full-on
• +5V standby
• +5V full-on
• +3.3V standby
• +3.3V full-on
• I/O power standby
• I/O power full-on
• Reserved standby
• Reserved full-on

The unspecified entries indicate that it is unknown how the power is divided among the various rails. The unspecified entries must be zero if any of the other entries are nonzero. The unspecified entries are provided so that the power-consumption property can be created for devices without FCode from the information on the PRSNT1# and PRSNT2# connector pins.

If the number of integers in the encoded property value is less than ten, the power consumption is zero for the cases corresponding to the missing entries. For example, if there are four integers, corresponding to the two unspecified and the two "+5" quantities, then the others are zero.

The following code creates a power-consumption property for a device with +5V standby consumption of 100 mA and +5V full-on consumption of 2.5A:

0 encode-int 0 encode-int encode+ \ Set unspecified values to zero

500000 encode-int encode+ \ 100 mA@5V = 500,000 uW standby

12500000 encode-int encode+ \ 2.5A@5V = 12,500,000 uW full-on

" power-consumption" property

ranges

The ranges property is a list of child-to-parent physical address correspondences required for most hierarchical devices.

ranges is a property for bus devices, particularly those buses whose children can be accessed with CPU load and store operations (as opposed to buses like SCSI, whose children are accessed with a command protocol).

The ranges property value describes the correspondence between the part of the physical address space of the bus node's parent available for use by the bus node (the parent address space), and the physical address space defined by the bus node for its children (the child address space).

The ranges property value is a sequence of specifications:

child-phys parent-phys size

• child-phys is a starting address in the child physical address space defined by the bus node
• parent-phys is a starting address in the physical address space of the parent of the bus node
• size is the length in bytes of the address range

The specification means that there is a one-to-one correspondence between the child addresses and the parent addresses in that range. The parent addresses given are always relative to the parent's address space.

Each starting address is represented using the physical address representation as two 32-bit numbers (one for space and one for offset). size is encoded as an unsigned integer.

The total size of each such specification is five 32-bit numbers (two for each of the two addresses, plus one for the size). Successive specifications are encoded sequentially. A space with length 2**(number of bits in a machine word) is represented with a size of 0.

The specifications should be sorted in ascending order of the child address. The address ranges thus described need not be contiguous in either the child space or the parent space. Also, the entire child space must be described in terms of parent addresses, but not all of the parent address space available to the bus device need be used for child addresses (the bus device might reserve some addresses for its own purposes, for instance).

For example, suppose that a 4-slot 25-bit SBus is attached to a machine whose physical address space consists of a 32-bit memory space (space=0) and a 32-bit I/O space (space=1). The SBus slots appear in I/O space at addresses 0xf800.0000, 0xfa00.0000, 0xfc00.0000, and 0xfe00.0000. In terms of the parent address space, the SBus device has available for its purposes the offsets from 0xf800.0000 through 0xffff.ffff in space 1 of its parent.

The SBus device defines for its children the spaces 0, 1, 2, and 3, all starting at offset 0 and running for 0x200.0000 bytes. In this case, the SBus device uses all the address space given to it by its parent for the SBus children and reserves none of the addresses for itself. The ranges property for the SBus device would contain the encoded form of the following sequence of numbers:

Here the high components of the child address represent the SBus slot numbers, and the high component of the parent address represents I/O space.

If ranges exists but its value is of 0 length, the bus's child address space is identical to its parent address space.

If the ranges property for a particular bus device node is nonexistent, code using that device should use an appropriate default interpretation. Some examples include the following:

• SBus node: Missing ranges means that the version of OpenBoot was created before the ranges property came into existence. Code should supply the correct ranges based on the machine type from the finite set of machines that existed before ranges came into existence.
• Machine node: The machine node has no parent. Therefore, the correspondence between its child and parent address spaces is meaningless, and there is no need for ranges.
• SCSI host adapter node: The child address space is not directly addressable, thus ranges would be meaningless.

The distinction between reg and ranges is as follows:

• reg represents the device registers in the parent address space. For a bus adapter, this would be such as configuration/mode/initialization registers.
• ranges represents the correspondence between a bus adapter's child and parent address spaces.

Most packages do not need to be concerned with ranges. These properties are mainly to communicate with standalone programs. One exception could be a bus extender or adapter.

See also: Chapter 10.

For a PCI node in a PowerPC Reference Platform (PPCRP) compliant machine, the total size of each such specification is five 32-bit numbers (one for the parent address space, three for the child address space, and one for the size). Successive specifications are encoded sequentially. A space with langth 2** (number of bits in a machine word) is represented with a size of 0.

Sort the specifications in ascending order of child-phys, in accordance with recommendations. The address ranges thus described need not be contiguous in either the child space or the parent space. Also, the entire child space must be described in terms of parent addresses, but not all of the parent address space available to the bus device need be used for child addresses (the bus device might reserve some addresses for its own purposes, for instance).

In the PPCRP machine example, consider a 4-slot 32-bit PCI bus attached to a machine whose physical address space consists of a 32-bit memory space (bit 31=0) and a 32-bit I/O space (bit 31=1).

• ISA I/O space appears in the parent's I/O space at 0x8000.0000; the size is 0x1.0000.
• A reserved block of addresses begins at 0x8001.0000; the size is 0x7f.0000.
• PCI configuration space begins at 0x8080.0000; the size is 0x80.0000. The configuration registers of the individual PCI slots appear at addresses 0x8080.1000, 0x8080.2000, 0x8080.4000, and 0x8080.8000.
• PCI I/O space begins at 0x8100.0000; the size is 3e80.0000.
• Parity/interrupt vectors begin at 0xbf80.0000; their size is 0x80.0000.
• PCI memory space begins at 0xc000.0000; the size is 3e00.0000.

The PCI device defines:

• Configuration spaces for devices 1 through 4 that each begin at 0x0000.0000; their size is 0x100 bytes.
• ISA I/O space that begins at 0x0000.0000; the size is 0x1.0000.
• PCI I/O space that begins at 0x0001.0000; the size is 0x3e80.0000.
• A 32-bit PCI memory space that begins at 0x0000.0000; the size is 0x3e00.0000.

The ranges property for the PCI device would contain the encoded form of the following sequence of numbers:

Here the phys.hi component of the child address represents the type of address space and the PCI device numbers. Bit 31 of the parent address represents I/O space. (Please see the PCI Bus Binding to IEEE Standard 1275-1994 for a detailed description of the encoding of the phys.hi field.)

The code to create this ranges property is:

\SCSI Configuration Space

0000.0800 encode-int encode+ 0 encode-int encode+ 0 encode-int encode+

8080.1000 encode-int encode+

800 encode-int encode+

\ Slot A Configuration Space

0000.1000 encode-int encode+ 0 encode-int encode+ 0 encode-int encode+

8080.2000 encode-int encode+

800 encode-int encode+

\ Slot B Configuration Space

0000.1800 encode-int encode+ 0 encode-int encode+ 0 encode-int encode+

8080.4000 encode-int encode+

800 encode-int encode+

\ Slot C Configuration Space

0000.2000 encode-int encode+ 0 encode-int encode+ 0 encode-int encode+

8080.8000 encode-int encode+

800 encode-int encode+

\ ISA I/O space

0100.0000 encode-int encode+ 0 encode-int encode+ 0 encode-int encode+

8000.0000 encode-int encode+

1.0000 encode-int encode+

\ PCI I/O space

0100.0000 encode-int encode+ 0 encode-int encode+ 1.0000 encode-int encode+

8100.0000 encode-int encode+

3e80.0000 encode-int encode+

\ PCI Memory space

0200.0000 encode-int encode+ 0 encode-int encode+ 0 encode-int encode+

c000.0000 encode-int encode+

3e00.0000 encode-int encode+

" ranges" property

If ranges exists but its value is of 0 length, the bus's child address space is identical to its parent address space.

If the ranges property for a particular bus device node is nonexistent, code using that device should use an appropriate default interpretation. Here are some examples:

• Root node: The root node has no parent. Therefore the correspondence between its child and parent address spaces is meaningless and there is no need for ranges.
• SCSI host adapter node: The child address space is not directly addressable, thus ranges would be meaningless.
• For memory-mapped bus devices where a ranges property would be meaningful, the absence of a ranges property is conventionally interpreted to mean that the parent and child address spaces are identical.

The distinction between reg and ranges is as follows:

• reg represents the device registers in the parent address space. For a bus adapter, this would be such as configuration/mode/initialization registers.
• ranges represents the correspondence between a bus adapter's child and parent address spaces.

Most packages do not need to consider ranges. This property is mainly used for bus bridges. The firmware system does not itself use this property. ranges is mainly used by operating systems that wish to auto-configure themselves.

See also: Chapter 10.

reg

This property declares the location and size of on-board registers for its device. The FCode program for every plug-in SBus and PCI device must declare this property.

For SBus, the contents are one or more (phys,size) pairs. Each pair specifies an addressable region of the device. An FCode PROM at location 0 of the device is generally not declared, except in the case where there are no other regions to declare.

For an SBus device,declare two register fields at 10.0000-10.00ff and 20.0000-20.037f:

my-address 10.0000 +  my-space  encode-phys          \ Offset#1

100 encode-int                               encode+    \ Merge size#1

my-address 20.0000 +  my-space  encode-phys  encode+    \ Merge offset#2

380 encode-int                               encode+    \ Merge size#2

" reg" property

In the first (phys,size) pair for a PCI device, the phys component is the configuration space address of the beginning of the function's set of configuration registers; the size component is zero. Each additional (phys,size) pair specifies the address and characteristics of an addressable region of memory space or I/O space associated with the function including the PCI expansion ROM.

For a PCI device, the order of the pairs should be:

• An entry describing the configuration space for the device.
• An entry for each active base address register (BAR), in configuration space order, describing the entire space mapped by that BAR.
• An entry describing the expansion ROM BAR, if the device has an expansion ROM.
• An entry for each nonrelocatable addressable resource.

In the event that a function has an addressable region that can be accessed relative to more than one base address register (for example, in memory space relative to one base register, and in I/O space relative to another), only the primary access path (typically, the one in memory space) is listed in the reg property, and the secondary access path is listed in the alternate-reg property.

For PCI, phys is (phys.lo phys.mid phys.hi), encoded with encode-phys, and size is a pair of integers, each encoded with encode-int. The first integer denotes the most significant 32 bits of the 64-bit region size, and the second integer denotes the least significant 32 bits.

For example, to declare a PCI device with:

• A register field of size 0x100 in 32-bit memory space that is controlled by the first 32-bit base address register
• A register field of size 0x440 in I/O space that is controlled by the second 32-bit base address register. The register field of interest is offset from the base address register by 0x20.0000
• A 128 Kbyte PCI expansion ROM
• A nonrelocatable field at 0-fff in I/O space

use the following:

hex

my-address my-space encode-phys \ Config space regs

0 encode-int encode+ 0 encode-int encode+ 

0 0 my-space 0200.0010 or encode-phys encode+ \ Memory space 

0 encode-int encode+ 100 encode-int encode+ \ BAR at 0x10

20.0000 0 my-space 0100.0014 or encode-phys \ I/O space

encode+	\ BAR at 0x14

0 encode-int encode+ 440 encode-int encode+

0 0 my-space 0200.0030 or encode-phys encode+ \ PCI Expansion ROM

0 encode-int encode+ 2.0000 encode-int encode+ \ memory space

0 0 my-space 8100.0000 or encode-phys encode+ \ Non-relocatable

0 encode-int encode+ 1000 encode-int encode+ \ memory space

" reg" property

In some non-PCI cases, the reg command may also be used to create this property. However, reg may only be used on buses for which #size-cells is 1 and only when a single reg property component is required. Consequently, reg is never used with PCI devices which require at least three reg property components In other words:

• One component for the card's configuration space registers
• At least one for the device's functional registers
• One for the PCI expansion ROM)

See the PCI Bus Binding to IEEE Standard 1275-1994 for the encoding details.

See also: property.

revision-id

This property contains the value of the revision ID register from the configuration space header. That register specifies a device-specific revision identifier that is chosen by the vendor. Zero is an acceptable value.

The property value is the register's value encoded with encode-int.

See also: PCI Local Bus Specification.

slot-names

This property describes the external labeling of plug-in slots.

The property value is an integer, encoded with encode-int, followed by a list of strings, each encoded with encode-string.

The integer portion of the property value is a bit mask of available slots; for each add-in slot on the bus, the bit corresponding to that slot's device number is set. The least significant bit corresponds to Device Number 0, the next bit corresponds to Device Number 1, and so on. The number of following strings is the same as the number of slots; the first string gives the label that is printed on the chassis for the slot with the smallest device number, and so on.

status

This optional property indicates the operational status of the device.

Absence of this property means that the operational status of the device is unknown or okay.

If this property is present, the value is a string indicating the status of the device, as follows:

Usage:

" disabled" encode-string  " status" property

See also: property.

translations

This property contains an array of (phys-addr, virt-addr, size) entries describing the address translations currently in use by OpenBoot. Those operating systems calling on OpenBoot services while taking over the memory management function must create all translations described by this property's value.

vendor-id

This property contains the value of the vendor ID register from the configuration space header. That register identifies the manufacturer of the device. Vendor identifiers are assigned by the PCI SIG to ensure uniqueness. 0xffff is an invalid value for vendor-id.

The property value is the register's value encoded with encode-int.

See also: PCI Local Bus Specification.

width

This property is associated with display devices. Encoded with encode-int, the property value specifies the number of displayable pixels in the "x" direction of the display.

---

Manipulating Properties

Property Creation and Modification

Use the FCode function property to create new properties or modify values of existing properties.

There are some special property-publishing FCodes, designed for use in common situations:

• reg is a quick way to create a "reg" property that describes the location of the package's physical resources.
• model is a quick way to create the "model" property.
• device-name is a quick way to create the "name" property.
• delete-property completely removes a property.

Property Values

Various kinds of information can be stored in a property value byte array by using property encoding and decoding methods. The encoding format is machine-independent. Property value representation is independent of the byte organization and word alignment characteristics of a processor.

A property's data type must be recognized by any software that uses it. In other words, property value data types are not self-identifying. Furthermore, the presence or absence of a property with a particular name can encode a true/false flag; such a property may have a zero-length property value.

Property Encoding

There are three FCodes for encoding a piece of data into a property value and one for concatenating pieces of data for a property with multiple values.

Property Retrieval

There are three property value retrieving words: get-my-property, get-package-property, and get-inherited-property.

• Use get-my-property if the property desired exists for the package being defined.
• Use get-package-property if the property exists in some other package. In this case, you must first find the phandle of the other package, perhaps by using find-package.
• Use get-inherited-property if the property exists somewhere in the chain of parent instances between the package being defined and the root node of the machine.

FCode programs often do not retrieve property values. Such programs usually know the values of their own properties implicitly, and often interact with their parents by calling well-known parent methods.

For example, suppose a particular SBus FCode package calls DVMA to transfer data between a device and memory.

It could use my-parent ihandle>phandle get-package-property to find the value of a property named slave-only. slave-only will be a property of the parent node of the package being defined, if it exists.

The value of the property is a bit mask of the SBus slots that do not support DVMA. Then the package would look at my-unit or my-space to get its slot number. The two pieces of information will tell the package whether or not it can use DVMA.

Property Decoding

Once a package has found a property's value, it must decode the value to forms it can recognize. If the value is the representation of an integer, use decode-int to generate the number as a binary number on the stack. If the value is the representation of a string, use decode-string. Both of these FCodes act as parsers. They will also return the unused portion of the value for further decoding.

Other kinds of values can be decoded by left-parse-string or package-specific decoders. Note that the package must be able to decode the value of a property.

There is no decode-bytes function, but it is easy to synthesize if needed:

: decode-bytes  ( addr1 len1 #bytes -- addr len2 addr1 #bytes )

   tuck -				( addr1 #bytes len2 )

   >r 2dup +				( addr1 #bytes addr2 ) ( R: len2 )

   r> 2swap

;

---

Property-Specific FCodes

Following is a summary of property-specific FCodes. See the individual dictionary entries in Chapter 14 for more information.

Writing FCode 3.x Programs

806-1379-10

Copyright © 2004, Sun Microsystems, Inc. All Rights Reserved.