This chapter describes characteristics of hardware devices, software and user selections. Properties are associated with the device node in which they are created and are accessible both by OpenBoot routines and by client programs. Properties can be inspected and, in some cases, modified.
Each property has a property name and a property value.
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. 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:
Since property value arrays may be of zero length, properties may convey "true" or "false" information by their presence or absence.
An array of 1 or more bytes is stored in a property value array as a series of sequential bytes in the property value array.
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 (i.e. in big-endian format).
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 (i.e. a null terminated string).
A composite value is made up of the concatenation of encoded bytes, encoded 32-bit integers and/or encoded strings. Each such primitive is stored immediately after the preceding primitive with no intervening space (i.e. the items are packed). Here are examples of composite values:
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 (e.g. disk, tape, network, display, etc.) to determine how to use the device (if at all) during the boot process.
Solaris 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.
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.
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 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. --------------------------------------------------------------------------------
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 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. -------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------
#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. -------------------------------------------------------------------------------------------------------
-----------------------------------------------------------------
-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 ; -----------------------------------------------------------------
-------------------------------------------
d# 48 encode-int " address-bits" property -------------------------------------------
------------------------------------------------------
" ISO8859-1" encode-string " character-set" property ------------------------------------------------------
--------------------------------------------------
" display" encode-string " device_type" property --------------------------------------------------
Table 5-1 Standard Device Types
--------------------------------------------------------------------------------------------------------------
Device Type Device Characteristics --------------------------------------------------------------------------------------------------------------
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.
display Frame buffer or other similar display device, usable for message display during booting. See
Chapter 7, "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 9, "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 8, "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 10, "Serial Devices" for the requirements of this type of device.
--------------------------------------------------------------------------------------------------------------
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 5 0 intr -------------------------------------
To declare two interrupts (levels 3 and 5), used as:
-----------------------------------------------------------
5 encode-int 3 encode-int encode+ " interrupts" property 3 sbus-intrcpu encode-int \ Interrupt#1 0 encode-int encode+ \ Null vector#1 5 sbus-intrcpu encode-int encode+ \ Interrupt#2 0 encode-int encode+ \ Null vector#2 " intr" property -----------------------------------------------------------
See also: intr, interrupts, 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) ------------------------------------------------------------------------
---------------------------------------------
4000 encode-int " max-frame-size" property ---------------------------------------------
-----------------------------------------------------
" SUNW,501-1415-1" encode-string " model" property -----------------------------------------------------
--------------------------------------------------------
" SUNW,bison-printer" encode-string " name" property --------------------------------------------------------
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 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 "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, 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 "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, "Memory-Mapped Buses".
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 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 some cases, the reg command may also be used to create this property.
See also: reg, property.
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.
-----------------------------------------------------------------------------------------------------------------
-----------------------------------------------
" disabled" encode-string " status" property -----------------------------------------------
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:
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.
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). encode-phys is derived from encode-int and encode+. ----------------------------------------------------------------------------------------------------
There are three property value retrieving words, get-my-property, get-inherited-property, and get-package-property.
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 ihandlephandle 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.
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 ; -----------------------------------------------------------------
Following is a summary of property-specific FCodes. 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
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 ( name-addr name-len -- ) Delete the desired property.
Property Encoding
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 Concatenate two prop-encoded-
-- prop-addr prop-len1+2 ) array structures. They must have
been created sequentially.
encode-bytes ( 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.
Property Decoding
decode-int ( prop-addr prop-len -- prop-addr2 prop-len2 n ) Converts a prop-encoded-array string
to an integer.
decode-string ( prop-addr prop-len -- prop-addr2 prop-len2 addr len ) Converts a prop-encoded-array string
to a normal string.
Property Retrieval
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- ( addr len phandle -- true | prop-addr prop-len false ) Returns the prop-encoded-array
property contents for the property addr len in
the package phandle, or true if not
found.
get-inherited- ( addr len -- true | prop-addr prop-len false ) Returns the prop-encoded-array
property 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.
------------------------------------------------------------------------------------------------------------------------------
