Properties are created by FCode PROMs. The CPU's boot PROM understands certain property names that tell it things such as the type of the device (disk, tape, network, display, and so on). The CPU boot PROM may use this information to determine how to use the device (if at all) during the boot process.
SunOS understands other property names that give information used 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 SunOS device drivers. The names of such properties and the interpretation of their values is subject to agreement between the writers of the FCode PROM and the SunOS driver, but may otherwise be arbitrarily chosen. For example, a display device might declare width, height, and depth properties to allow a single SunOS 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 attribute FCode, or with the name, reg, intr, model, and device-type FCodes, described below.
For example, a framebuffer package might export its register addresses, interrupt levels, and framebuffer size. Every package has an associated property list, which is arbitrarily extensible. Use the Forth Monitor command .attributes to display the names and values of the current node's properties.
Each property has a property name and a property value.
Many derived data types can be encoded into the primitive "array of bytes" data type, for example:
If an FCode program tries to create the same property (with the same name) more than once for a given package, the new property supercedes the old one.
You can add new properties during the lifetime of a product. For backward compatibility, an FCode or device driver program that needs the value of a particular property should consider the possibility that the property does not exist, in which case the program should supply its own default value.
A number of FCode properties have been defined and used by some or all current implementations of OpenBoot. These are listed below.
A package should never create any property using any of the following names, unless the defined meanings and structures are used. Doing otherwise can result in system errors occurring.
This is an optional property that declares currently-mapped device virtual addresses. It is generally used to declare large regions of existing mappings, in order to enable the SunOS device driver to reuse those mappings to conserve system resources.
The contents of the property are 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-adr : map-me ( -- ) my-address 10.0000 + my-space 1.0000 " map-in" $call-parent ( virt1 ) is my-buffers 2000 " dma-alloc" $call-parent ( virt2 ) is my-dma-adr my-buffers xdrint my-dma-adr xdrint xdr+ " address" attribute ; : unmap-me ( -- ) my-dma-adr 2000 " dma-free" $call-parent my-buffers 1.0000 " map-out" $call-parent " address" delete-attribute ; -----------------------------------------------------------------------------
See also: free-virtual, attribute
This optional property, when declared in "network" devices, indicates the number of address bits needed to address this device on its network. Used as:
-------------------------------------------
d# 48 xdrint " address-bits" attribute -------------------------------------------
See also: attribute and Chapter 9, "Network Devices".
This required property is located in every SBus controller node in the system.
Its value is a bit mask of burst transfer sizes supported by this SBus
implementation. If bit n is 1, then transfer size 2
Support for the extended (64-bit) SBus protocol is also indicated by this property, using the next-higher 16 bits of the value.
Thus, an SBus controller which supports transfer sizes of 1,2,4,8,16,32,64 bytes would have a "burst-sizes" value of 0x007f. An SBus controller which also supports extended (64-bit) transfers of 8,16,32,64,128 bytes would have a "burst-sizes" value of 0x00f8007f.
Notice that particular destination devices may be more restrictive in the allowed transfer sizes. This property only describes the transfer sizes allowed by the SBus controller itself.
It is acceptable for an SBus controller to omit this property, as long as some parent node is assured of having the correct value. A plug-in device should use get-inherited-attribute to query this property.
Some early systems only support 16-byte bursts (as well as 1,2,4 byte transfers), but do not declare the "burst-sizes" property at all. Thus, a missing "burst-sizes" should be assumed to be equivalent to a "burst-sizes" value of 0x0017. Used as:
---------------------------------------
h# 7f xdrint " burst-sizes" attribute ---------------------------------------
See also: slave-burst-sizes, attribute, Chapter 8, "Hierarchical Devices".
This optional property, when present on an SBus controller node, indicates that this SBus is generating parity on SBus transactions. A null value is used.
See also Chapter 8, "Hierarchical Devices".
This optional property, when declared in "display" or "serial" devices, indicates the recognized character set for this device. The contents are 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. There is an address for it in the X11R5 documentation.
Used as:
------------------------------------------------------
" ISO8859-1" xdrstring " character-set" attribute ------------------------------------------------------
See also: attribute, Chapter 7, "Display Devices" and Chapter 10, "Serial Devices".
This property may be queried (using get-inherited-attribute) by a plug- in device, to determine the clock frequency for this bus (if appropriate). The value is returned in Hertz (cycles per second).
Any bus nexus node implementing a bus with a basic clock frequency (such as SBus) must either publish this property, or ensure that the correct value will be returned if a child queries for this value using get-inherited-attribute. For example:
------------------------------
d# 2.000.000 xdrint " clock-frequency" attribute ------------------------------
See also: Chapter 8, "Hierarchical Devices".
This optional property declares the type of this plug-in device. The type need not be declared, unless this device is intended to be usable for booting. If this property is declared, using one of the following key values listed next, then 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" xdrstring " device_type" attribute -------------------------------------------------
Defined key values for this property are:
Table 5-1 Standard Device Types
----------------------------------------------------------------------------------------------------------------
Device Type Device Characteristics ----------------------------------------------------------------------------------------------------------------
display Framebuffer or other similar display device, usable for message display during booting. See
Chapter 7, "Display Devices" for the requirements of this type of device.
network Packet-oriented network device, such as Ethernet, usable as a boot file source. See Chapter 9,
"Network Devices" for the requirements of this type of device.
block Random-access, block-oriented device, such as a disk drive, usable as a boot file source. See
Chapter 6, "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 6, "Block and Byte Devices" 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 10, "Serial Devices" for the requirements of this type of device.
sbus SBus controller node, which lets you attach plug-in SBus devices. Some SBus controller nodes set
their "device_type" to "hierarchical" and set their "name" to "sbus". See Chapter 8,
"Hierarchical Devices" for the requirements of this type of device.
----------------------------------------------------------------------------------------------------------------
See also: device-type, attribute
This optional property, when declared in an SBus slave acting as a bus bridge (such as an "sbus" device), denotes transfer sizes allowed to the subordinate bus. The value is encoded similarly to "burst-sizes".
See also Chapter 8, "Hierarchical Devices".
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 xdrint " interrupts" attribute 5 0 intr ------------------------------------
To declare two interrupts (levels 3 and 5), used as:
----------------------------------------------------
5 xdrint 3 xdrint xdr+ " interrupts" attribute 3 sbus-intrcpu xdrint \ Interrupt#1 0 xdrint xdr+ \ Null vector#1 5 sbus-intrcpu xdrint xdr+ \ Interrupt#2 0 xdrint xdr+ \ Null vector#2 " intr" attribute ----------------------------------------------------
See also: "intr", intr, attribute
This property was used in early systems, but has now been superceded by the "interrupts" property.
Creation of this property automatically creates an "interrupts" property in most systems, except in the case where an "interrupts" property has already been created by the FCode for this device.
See also: "interrupts", intr, attribute
This optional property, when declared in "network" devices, indicates the built-in Media Access Control address for this device (if any). The system may or may not use this address in order to access this device.
Used as:
--------------------------------------------------------------------
" "(08,04,fe,23,46,9e)" xdrbytes " local-mac-address" attribute --------------------------------------------------------------------
See also: mac-address, "mac-address", attribute, and Chapter 9, "Network Devices".
This property must be declared in "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 the "local-mac-address" property, if any.
Here's how it all fits together.
Following are code examples for three typical situations.
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:
----------------------------------------------------------------------
" "(08,04,fe,23,46,9e)" xdrbytes " local-mac-address" attribute mac-address xdrbytes " mac-address" attribute (plus code to "assign" the correct mac-address value into registers) ----------------------------------------------------------------------
For a plug-in "network" device that has a factory-unique MAC address and is unable to alter its behavior to a different address, the FCode would appear as:
--------------------------------------------------------------------
" "(08,04,fe,23,46,9e)" xdrbytes " local-mac-address" attribute " "(08,04,fe,23,46,9e)" xdrbytes " mac-address" attribute --------------------------------------------------------------------
For a plug-in "network" device which does not have any built-in MAC address, the FCode would appear as:
----------------------------------------------------------------------
mac-address xdrbytes " mac-address" attribute (plus code to "assign" the correct mac-address value into registers) ----------------------------------------------------------------------
See also: mac-address, "local-mac-address", attribute and Chapter 9, "Network Devices".
This optional property, when declared in "network" devices, indicates the maximum allowable size of a packet (in bytes). Used as:
-------------------------------------------
4000 xdrint " max-frame-size" attribute -------------------------------------------
See also: attribute and Chapter 9, "Network Devices".
This optional property identifies the model name/number for a plug-in card, 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.
Used as:
-----------------------------------------------
" SUNW,501-1415" xdrstring " model" attribute -----------------------------------------------
See also: model, attribute
This property is used to match a particular SunOS device driver with the appropriate plug-in device. All device nodes must publish this property.
The contents are an arbitrary string. Any combination of printable characters is allowed, except for "@", ":" or "/". Embedded spaces are not allowed. The convention is to use a string of the form SUNW,xxxxxx.
(In place of SUNW, use your company's over-the-counter stock symbol. If you're not a publicly-traded company, pick a name that isn't being used.) This technique greatly reduces the chance that the value for your name property will accidentally collide with a name chosen by someone else.
Used as:
------------------------------------------------------
" SUNW,bison-printer" xdrstring " name" attribute ------------------------------------------------------
The name command may also be used to create this property.
See also: name, attribute, device-name.
This optional property, if present in the SBus controller node, indicates a system restriction on the use of SBus retry cycles. A null value is used.
If this property is present, the SBus controller restricts retries from a particular slot to use the same address until the retry cycle is completed, as opposed to being able to interleave retries with different addresses.
Any SBus master capable of interleaving pending retries with accesses to other addresses, must check for the absence of this property in the parent before enabling that feature. Used as:
-------------------------------------
0 0 " one-pending-retry" attribute -------------------------------------
See also: Chapter 8, "Hierarchical Devices".
This optional property contains the information to be passed when the my- params FCode is executed. This feature is obsolescent and should not be used.
See also: my-params, attribute.
This optional property, if present, indicates that this SBus device is currently generating correct parity on the SBus. This means that whenever this device presents data (or a virtual address) on the SBus data lines, the Parity signal is also driven to correct (odd) parity. The value of the property is null.
This does not deal with the methods for enabling or disabling parity checking. Presence of this property merely provides the necessary information to determine that parity is being generated, so that any decision as to whether or not to check parity can be made with adequate information.
If the device has the capability to turn parity-generation on and off, this property should be created and deleted accordingly. Used as:
-----------------------------------
0 0 " parity-generated" attribute -----------------------------------
See also: attribute.
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
-----------------------------
child-phys parent-phys size -----------------------------
specifications.
The specification means that there is a one-to-one correspondence between the child addresses and the parent addresses within 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 "io" space (space=1). The SBus slots appear in "io" 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 5-2 Child-Parent Address Relationships
--------------------------------------------------------
Child Address Parent Address Size --------------------------------------------------------
Space, Offset Space, Offset
0, 0 1, f800.0000 200.0000
1, 0 1, fa0.00000 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 "io 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:
The distinction between reg and ranges is as follows:
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 8, "Hierarchical Devices".
This property declares the location and size of onboard registers for its device. The FCode program for every plug-in SBus device must declare this property.
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 example, to declare two register fields at 10.0000-10.00ff and 20.0000- 20.037f, use the following:
----------------------------------------------------------------
my-address 10.0000 + my-space xdrphys \ Offset#1 100 xdrint xdr+ \ Merge size#1 my-address 20.0000 + my-space xdrphys xdr+ \ Merge offset#2 380 xdrint xdr+ \ Merge size#2 " reg" attribute ----------------------------------------------------------------
In some cases, the reg command may also be used to create this property.
See also: reg, attribute.
This optional property is located in one of the parent nodes of the system. It may be queried (using get-inherited-attribute) by a plug-in device. Its value is an integer, 0-15, indicating the address of the main SCSI host adapter of this system (if any). The value also indicates the suggested address for the host adapter for any plug-in SCSI controller.
The SCSI controller node for a plug-in SCSI controller may also publish this property, to indicate the current address of this host adapter. Used as:
-------------------------------------------
7 xdrint " scsi-initiator-id" attribute -------------------------------------------
See also: attribute.
This optional property uses a bitmask to indicate the set of SBus transfer sizes which this device will accept. It contains a set of integer values. The number of entries is the same as the number of (phys,size) entries in the "reg" property, and each entry in "slave-burst-sizes" describes the transfer sizes accepted by the corresponding "reg" entry. The encoding of each "slave-burst-sizes" entry is the same as the encoding for the "burst- sizes" property.
This property may be defined for any device which is capable of acting as an SBus slave. The value is a "hint" to the operating system, or to other devices which may desire to access this SBus device. Used as:
------------------------------------------------------------------
h# 3f xdrint h# 17 xdrint xdr+ " slave-burst-sizes" attribute ------------------------------------------------------------------
See also: burst-sizes, reg, attribute
This optional property, if present in the SBus controller node or other parent nodes, uses a bitmask to indicate that certain SBus slots support slave-only access. If bit n is 1, then slot#2^^n is slave-only. For example, a value of 8 indicates that slot#3 is slave-only.
A plug-in device should use get-inherited-attribute to query this property.
If this property is not found (for example, if the system contains a version 1 boot PROM that was released before this property was defined), then slot#3 is slave-only.
This affects SPARCstation1 and SPARCstation 1+ only (SPARCstation IPC only has two slots). Used as:
----------------------------------
8 xdrint " slave-only" attribute ----------------------------------
See also: attribute and Chapter 8, "Hierarchical Devices".
This required property in the SBus controller node specifies the number of address lines available to each SBus card. Typical values are either 25 or 28. It is acceptable for an SBus controller to omit this property, as long as some parent node is assured of having the correct value. A plug-in device should use get-inherited-attribute to query this property.
If this property is not found (for example, if the system contains a version 1 boot PROM that was released before this property was defined), then a value of 25 should be assumed. Used as:
---------------------------------------------
d# 25 xdrint " slot-address-bits" attribute ---------------------------------------------
See also: attribute.
This optional property indicates that this device has failed an internal selftest and is thus unavailable for use.
Absence of this property means that this device is believed to be operational.
If this property is present, the value is a string indicating the status of the device, as follows:
Table 5-3 status property values
--------------------------------------------------------------------------------------------------------------------
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" xdrstring " status" attribute --------------------------------------------
See also: attribute.
This optional property, when present on an SBus controller node, indicates the set of allowed transfer sizes up though the node to its parent bus. The value is encoded similarly to that of "burst-sizes".
See also: Chapter 8, "Hierarchical Devices".
By far the most common activity done with a property is to create or modify one. The FCode attribute is the general property publishing word. It will create a new property or change the value of an existing property for the current package.
There are some special property publishing FCodes, designed for use in common situations:
Various kinds of information may be stored in a property value byte array by using an external data representation (xdr) encoding/decoding method. The encoding format is machine-independent; the representation of the property values is independent of the byte organization and word alignment characteristics of particular processor.
Note - This encoding is not related to xdr-type encodings described in architecture documents for various other computer systems.
The data type of any particular property must be implicitly known by any software that wishes to use 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.
The second most common activity in connection with properties is to encode the value for a property in the external data representation, usually in preparation for publishing the property using attribute. There are four FCodes used to encode a basic piece of data, and one FCode for amalgamating the basic pieces for a property that has multiple values.
xdrint encodes a number. xdrstring encodes a string. xdrphys encodes a physical address (hiding all the relative addressing information). And finally, xdrbytes encodes a sequence of bytes.
xdr+ is used to amalgamate two basic pieces of data.
Somewhat less common is for a package to retrieve the value of a property. There are three property value retrieving words, get-my-attribute, get- inherited-attribute, and get-package-attribute.
For an example, suppose a particular SBus FCode package wants to use DVMA to transfer some data between a device and memory.
It could use get-inherited-attribute to find the value of a property named slave-only. slave-only will be a property of one of the parent nodes of the package being defined, if it exists.
The value of the property is a bitmask 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.
Once a package has searched for and found the value of a property of interest, it must decode the value to forms it can understand. Usually the value is the representation of an integer; use xdrtoint to generate the actual number as a binary number on the stack. Occasionally the value of interest is the representation of a string, in which case use xdrtostring. 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 know how to decode the value of a property it wishes to use.
Following is a summary of attribute-specific FCodes. Those introduced with OpenBoot 2.0 are noted by V2. See the individual dictionary entries in Chapter 11, "FCode Dictionary" for more information.
Table 5-4 Property-specific FCodes
-----------------------------------------------------------------------------------------------------------------------------
Name Stack Comment Description -----------------------------------------------------------------------------------------------------------------------------
Property Creation
attribute ( xdr-adr xdr-len name-adr name-len -- ) Create an property named name-adr name-len, with
the value xdr-adr xdr-len.
device-type ( adr len -- ) Shorthand word to create the "device_type"
property, with the value adr len.
intr ( intr-level vector -- ) Shorthand word to create the "intr" and
"interrupts" properties.
model ( adr len -- ) Shorthand word to create the "model" property,
with the value adr len.
name ( adr len -- ) Shorthand macro to create the "name" property,
with the value adr len.
reg ( phys space size -- ) Shorthand word to create the "reg" property.
device-name ( adr len -- ) Shorthand word to create the "name" property,
with the value adr len. Similar to name, but uses
only one FCode instead of creating a macro. V2.
delete-attribute ( name-adr name-len -- ) Delete the desired property. V2.
xdr Encoding
xdrint ( n -- xdr-adr xdr-len ) Converts an integer to xdr-format.
xdrphys ( phys space -- xdr-adr xdr-len ) Converts a physical unit pair to xdr-format.
xdrstring ( adr len -- xdr-adr xdr-len ) Converts a text string to xdr-format.
xdr+ ( xdr-adr1 xdr-len1 xdr-adr2 xdr-len2 -- Merge two xdr-format structures. They must have
xdr-adr xdr-len1+2 ) been created sequentially.
xdrbytes ( adr len -- xdr-adr xdr-len ) Converts a byte array to xdr-format. Similar to
xdrstring, except no trailing null is appended.
V2.
xdr Decoding
xdrtoint ( xdr-adr xdr-len -- xdr-adr2 xdr-len2 n ) Converts an xdr-format string to an integer. V2.
xdrtostring ( xdr-adr xdr-len -- xdr-adr2 xdr-len2 Converts an xdr-format string to a normal string.
adr len ) V2.
Attribute Retrieval
get-my-attribute ( adr len -- true | xdr-adr xdr-len false ) Returns the xdr-format contents for the property
adr len within the current instance, or true if not
found. V2.
get-package- ( adr len phandle -- true | xdr-adr xdr- Returns the xdr-format contents for the property
attribute len false ) adr len within the package phandle, or true if not
found. V2.
get-inherited- ( adr len -- true | xdr-adr xdr-len false ) Returns the xdr-format contents for the property
attribute adr 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.
V2.
-----------------------------------------------------------------------------------------------------------------------------
