Standard FCode Properties

IEEE Standard 1275-1994 defines the following standard properties. A package should never create any 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.

name	Name of the package.
reg	Package's registers.
device_type	Characteristics that the device is expected to have.
model	Manufacturer's model number.
interrupts	Interrupts used by the device.
address	Virtual addresses of one or more memory-mapped regions of the device.
compatible	List of devices with which this device is compatible.
status	Operational status of the device.

Display Device Properties

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

character-set	Character set (e.g. ISO8859-1).
depth	Number of bits in each pixel of the display.
height	Number of pixels in the "y" direction of the display.
linebytes	Number of pixels between consecutive scan lines of the display.
width	Number of pixels in the "x" direction of the display.
big-endian-aperture	The big-endian aperture of the frame buffer.
little-endian-aperture	The little-endian aperture of the frame buffer.

Network Device Properties

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

mac-address	Last used network address.
address-bits	Number of address bits needed to address this device on the physical layer.
max-frame-size	Maximum packet size that the device can transmit at one time.

Memory Device Properties

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

reg	Physical addresses installed in the system.
available	Regions of physical addresses that are currently unallocated by OpenBoot.

General Properties For Parent Nodes

#address-cells	Device node's address format.
#size-cells	Number of cells that are used to encode the size field of a child's reg property.
ranges	Relationship between the physical address spaces of the parent and child nodes.

Properties For PCI Parent Nodes

#address-cells	The value of this property for a PCI bus node is 3.
#size-cells	The value of this property for a PCI bus node is 2, reflecting the 64-bit address space of PCI.
device_type	The value of this property for a PCI bus node is "pci".
reg	For nodes representing PCI-to-PCI bridges, the value denotes the configuration space address of the bridges's configuration registers. The format is the same as that for PCI child nodes. For nodes representing bridges from some other bus to PCI, the format is as defined for the other bus.
bus-range	Specifies the range of bus numbers controlled by this PCI bus.
slot-names	Describes the external labeling of add-in slots.

Properties for PCI Child Nodes

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

reg	This standard property is mandatory for PCI Child nodes.
interrupts	The presence of this property indicates that the function represented by this node is connected to a PCI expansion connector's interrupt line.
alternate-reg	Defines alternate access paths for addressable regions.
has-fcode	The presence of this property indicates that this node was created by the evaluation of an FCode program.
assigned-addresses	Defines the configuration space's base address and size.
power-consumption	Describes the device's maximum power consumption categorized by the various power rails and the device's power-management state.

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 non-zero.

• "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

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

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

#size-cells

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

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 re-use those mappings, thus conserving system resources. This property should be created after virtual addresses have been assigned by mapping operations. 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.

-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, indicates the number of address bits needed to address this device on its network. Used as:

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

See also: property and Chapter 11, "Network Devices".

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 (in other words, 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 place-holder 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 and the second integer denotes the least-significant 32 bits thereof.

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 and the second integer denotes the least-significant 32 bits thereof.

Each entry (in other words, (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.

---

Note - There is no implied correspondence between the order of entries in the "reg" property value and order of entries in the assigned-addresses property value. The correspondence between the "reg" entries and assigned-addresses entries is determined by matching the fields denoting the base address register.

---

available

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 a phys.lo phys.mid phys.hi list of integers 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.

big-endian-aperture

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 (i.e. the address range through which the frame buffer can be addressed in big-endian mode).

character-set

When declared in display or serial devices, 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.

Used as:

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

See also: property, Chapter 9, "Display Devices" and Chapter 12, "Serial Devices".

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.

---

Note - Reccommended practice document on the topic "Generic Names" is available on the Open Firmware Workink Group's homepage. Recommended practice documents can be obtained as described in "Related Books" in the Preface.

---

See also: name.

class-code

Contains the value of the "Class Code" register from the Configuration Space header. That 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

depth

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-id

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

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). Used as:

" display" encode-string " device_type" property

Defined values for this property are:

Table 7-1

Device Type	Device Characteristics
block	Random-access, block-oriented device, such as a disk drive, usable as a boot file source. See Chapter 8, "Block and Byte Devices" for the requirements of this type of device.
byte	Random-access, byte-oriented device, such as a tape drive, usable as a boot file source. See Chapter 8, "Block and Byte Devices" for the requirements of this type of device.
display	Frame buffer or other similar display device, usable for message display during booting. See Chapter 9, "Display Devices" for the requirements of this type of device
memory	Random-access memory device. See IEEE Standard 1275-1994 for the requirements of this type of device.
network	Packet-oriented network device, such as Ethernet, can be used as a boot file source. See Chapter 11, "Network Devices" for the requirements of this type of device.
pci	A PCI bus node to which PCI plug-in devices can be attached. See Chapter 10, "Memory-Mapped Buses" for the requirements of this type of device.
serial	Byte-oriented device, such as a serial port, usable for console input and/or console output. See Chapter 12, "Serial Devices" for the requirements of this type of device.

See also: device-type, property.

devsel-speed

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

Specifies all of the regions 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 this device node creation involved FCode program evaluation, as opposed to being completely automatically created from information in configuration registers.

fast-back-to-back

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 they are not to the same agent.

See also: PCI Local Bus Specification.

has-fcode

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

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: video - SBus level 5, Ethernet - SBus level 4, SCSI and 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 instead of the interrupts property in earlier systems, we recommend 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 for you as required.

To declare a single interrupt (level 5), used as:

5 encode-int " interrupts" property

To declare two interrupts (levels 3 and 5), used as:

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:

Table 7-2

Value	Description
1	The device uses the INTA# interrupt line
2	The device uses the INTB# interrupt line
3	The device uses the INTC# interrupt line
4	The device uses the INTD# interrupt line

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 system-specific information about the way that the system handles interrupts. The system-specific information is known by the code that handles the system component 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

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 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, "mac-address", property, and Chapter 11, "Network Devices".

mac-address

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 made up:

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/or 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 well-behaved 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, "Network Devices".

max-frame-size

When declared in "network" devices, 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, "Network Devices".

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

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), as opposed to the name property (since several different but functionally-equivalent cards would have the same "name" property, thus calling the same device driver). Although the "model" property is good to have in general, it generally 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", model, property.

name

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 one 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 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, the most practical form of name is to use the company's stock symbol (e.g. 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 world-wide. 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 an example usage:

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

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

See also: name, 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 non-zero. 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, they correspond to the two unspecified and the two "+5" quantities, and the others are zero.

The following code would create 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 address 0xf800.0000, 0xfa00.0000, 0xfc00.0000, and 0xfe00.0000. In terms of the SBus's 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:

Table 7-3

Child Address		Parent Address
Space	Offset	Space	Offset	Size
0	0	1	f800.0000	200.0000
1	0	1	fa00.0000	200.0000
2	0	1	fc00.0000	200.0000
3	0	1	fe00.0000	200.0000

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 is supposed to represent the actual 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 stand-alone programs. One exception could be a bus extender or adaptor.

See also: Chapter 10, "Memory-Mapped Buses".

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 length 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:

Table 7-4

Child Address Function	phys.hi	phys.mid	phys.lo	Parent Address	Size
SCSI	0000.0800	0000.0000	0000.0000	8080.1000	0000.0800
Slot A	0000.1000	0000.0000	0000.0000	8080.2000	0000.0800
Slot B	0000.1800	0000.0000	0000.0000	8080.4000	0000.0800
Slot C	0000.2000	0000.0000	0000.0000	8080.8000	0000.0800
ISA I/O space	0100.0000	0000.0000	0000.0000	8000.0000	0001.0000
PCI I/O space	0100.0000	0000.0000	0001.0000	8100.0000	3e80.0000
PCI Memory space	0200.0000	0000.0000	0000.0000	c000.0000	3e00.0000

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.

reg and ranges are differentiated thus:

• 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, "Memory-Mapped Buses".

reg

This property declares the location and size of onboard 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, to declare two register fields at 10.0000-10.00ff and 20.0000- 20.037f, use the following:

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 non-relocatable 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 thereof.

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 128Kbyte PCI Expansion ROM.
• A non-relocatable 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 one 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 component--in other words

• One component for the card's configuration space registers
• At least one for the device's functional registers and

• One for the PCI Expansion ROM).

---

Note - The contents of the "reg" property are used by OpenBoot firmware to determine how large a portion of the system's virtual address space to reserve for use by the card. It is important that the size arguments be as large as the actual available addressable resource. If the size argument for a region were to be declared smaller than that actually available, and if the driver or a user were to later add a legitimate offset that was larger than size to the base address of the region, the resulting virtual address might be within the virtual address space of another card.

---

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

See also: reg, 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:

Table 7-5

Status Value	Meaning
okay	The device is believed to be operational.
disabled	The device represented by this node is not operational, but it might become operational in the future (e.g. an external switch is turned off, or something isn't plugged in).
fail	The device represented by this node is not operational because a fault has been detected, and it is unlikely that the device will become operational without repair. No additional failure details are available.
fail-xxx	The device represented by this node is not operational because a fault has been detected, and it is unlikely that the device will become operational without repair. "xxx" is additional human-readable information about the particular fault condition that was detected.

Used as:

" 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

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 basic piece of data into a property value and one for concatenating the basic pieces of data for a property with multiple values.

encode-int	encodes a number
encode-string	encodes a string
encode-bytes	encodes a sequence of bytes
encode+	is used to concatenate two previously encoded, basic pieces of data
encode-phys	is an FCode that encodes a physical address (hiding all the relative addressing information)

Property Retrieval

There are three property value retrieving words, get-my-property, get-inherited-property, and get-package-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.

---

Note - Using get-inherited-property can be a bad idea because you don't know who supplied the data.

---

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 you need it.

: 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, "FCode Dictionary", for more information.

Table 7-6

Name Property Creation	Stack Diagram	Description
property	( prop-addr prop-len name-addr name-len -- )	Create a property named name-addr name-len with the value prop-addr prop-len.
device-type	( addr len -- )	Shorthand word to create the device_type property with the value addr len.
model	( addr len -- )	Shorthand word to create the model property with the value addr len.
name	( addr len -- )	Shorthand macro to create the name property with the value addr len.
reg	( phys.lo ... phys.hi size -- )	Shorthand word to create the reg property.
device-name	( addr len -- )	Shorthand word to create the name property with the value addr len. Similar to name, but uses only one FCode instead of creating a macro.
delete-property Property Encoding	( name-addr name-len -- )	Delete the desired property.
encode-int	( n -- prop-addr prop-len )	Converts an integer to a prop-encoded-array.
encode-phys	( phys.lo ... phys.hi -- prop-addr prop-len )	Converts a physical unit pair to a prop-encoded-array.
encode-string	( addr len -- prop-addr prop-len )	Converts a text string to a prop-encoded-array.
encode+	( prop-addr1 prop-len1 prop-addr2 prop-len2 -- prop-addr prop-len1+2 )	Concatenate two prop-encoded-array structures. They must have been created sequentially.
encode-bytes Property Decoding	( addr len -- prop-addr prop-len )	Converts a byte array to a prop-encoded- array. Similar to encode-string, except no trailing null is appended.
decode-int	( prop-addr prop-len -- prop-addr2 prop-len2 n )	Converts a prop-encoded-array string to an integer.

Table 7-6 (Continued)

Name	Stack Diagram	Description
decode-string Property Retrieval	( prop-addr prop-len -- prop-addr2 prop-len2 addr len )	Converts a prop-encoded-array string to a normal string.
get-my-property	( name-addr name-len -- true | prop-addr prop-len false )	Returns the prop-encoded-array contents for the property addr len in the current instance, or true if not found.
get-package-property	( addr len phandle -- true | prop-addr prop-len false )	Returns the prop-encoded-array contents for the property addr len in the package phandle, or true if not found.
get-inherited-property	( addr len -- true | prop-addr prop-len false )	Returns the prop-encoded-array contents for the property addr len, or true if not found. The current package instance is searched first. If not found, the parent is searched next, then the parent's parent, and so on.