Skip to ContentSun and Oracle Channel Sun How to Buy Log In

Writing FCode 3.x Programs

Innerhalb

Solaris 2.5.1 Driver Developer AnswerBook

Nach weiteren Dokumenten suchen

Support-Ressourcen

Dieses Buch im PDF-Format herunterladen

Properties

5

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.

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

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

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

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

flag
Since property value arrays may be of zero length, properties may convey "true" or "false" information by their presence or absence.
byte
An array of 1 or more bytes is stored in a property value array as a series of sequential bytes in the property value array.
32-bit integer
A 32-bit integer is stored in a property value array in four successive bytes. The most significant byte of the integer in the next available address in the property value array is followed by the high middle, low middle and least significant bytes of the integer (i.e. in big-endian format).
text string
A text string of n printable characters is stored in a property value array in n+1 successive locations by storing the string in the first n locations followed by a byte of zero value (i.e. a null terminated string).
composite
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:
a. physical address range. Encoded as 4 integers: phys.lo phys.mid phys.hi size
b. array. The concatenation of n items of some type.

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

Properties may be created by FCode programs. The CPU's OpenBoot is able to use property names that tell it such things as the device type (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.

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.

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.

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.

#size-cells

Applies only to bus nodes. It specifies the number of cells used to represent the length of a physical address range (i.e. the size field of a child's reg property).

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: "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.

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


  child-phys parent-phys size  

 specifications.  
 · 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 "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 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:

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.

reg

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.

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). `encode-phys` is derived from `encode-int` and `encode+`.

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

Table 5-4

Name Property Creation	Stack Comment	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.

Table 5-4 (Continued)

Name	Stack Comment	Description
`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.
`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.