The presence of this property indicates that the device supplies absolute X,Y coordinates (e.g., a graphics tablet). Absence of this property indicates that the device supplies relative X,Y position (e.g., a mouse).
In addition to the Open Firmware standard open and close methods, the following method shall be supported by an Open Firmware implementation of a "mouse" device.
Pointing devices typically supply data only when an event occurs (e.g., the mouse moves or a button is pressed). The following method attempts to obtain an event from the device, reporting whether an event occurred.
get-event ( msec -- pos.x pos.y buttons true|false ) M
This method is used to obtain the next event of the pointing device. msecs is the number of milliseconds to wait for an event before reporting failure; a value of zero (0) implies wait until event pos.x, pos.y return the positioning
information. The pos.x and pos.y values can be interpreted as unsigned or signed
depending upon the presence or absence of the "absolute-position" property. The value for pos.x increases moving to the right direction and the value for pos.y increases
moving in a downward direction. buttons returns a bit-mask (in the low-order bits) representing any buttons that are pressed; the number of significant bits to examine is defined by the "#buttons" property. The top stack result indicates whether
an event was detected within the timeout period.
Open Firmware for Real Time Clocks defines the following properties and methods. The representation of time is defined by the TIME&DATE method of the ANS Forth standard [3].
"device_type" S
Standard property name to define the device's implemented interface.
The meaning of this property is as defined in the Open Firmware core document. The value for nodes described by this specification shall be "rtc".
In addition to the Open Firmware standard open and close methods, the following methods shall be supported by an Open Firmware implementation of a "rtc" device.
get-time ( -- n1 n2 n3 n4 n5 n6 ) M
Return the current time as the integers n1\xc9 n6, where n1 is the second {0\xc9 59}, n2 is the minute {0\xc9 59}, n3 is the hour {0\xc9 23}, n4 is the day {1\xc9 31}, n5 is the month {1\xc9 12}, and n6 is the year (e.g., 1994).
set-time ( n1 n2 n3 n4 n5 n6 -- ) M
Set the current time from the integers n1\xc9 n6, where n1 is the second {0\xc9 59}, n2 is the minute {0\xc9 59}, n3 is the hour {0\xc9 23}, n4 is the day {1\xc9 31}, n5 is the month {1\xc9 12}, and n6 is the year (e.g., 1994).
In order to use a sound device within the context of Open Firmware (e.g., "boot beeps"), the following properties and methods shall be implemented. To provide a common data format for universal support, Open Firmware shall, by
default, accept audio to write or return audio from read that consists of a sample rate of 8KHz of 8-bit monophonic samples encoded as unsigned linear values, centered at 128.
Note 1: Some implementation of "sound" nodes may need to convert this data into a form acceptable to the audio hardware being supported. It is not anticipated that this is an unreasonable requirement.
Note 2: An implementation may choose to supply additional properties, methods and open arguments so as to support more advanced audio capabilities, so long as a default open results in read and write using the standard format.
channel: One "track" of audio data. In stereophonic data, there are two channels - left and right.
sample: The atomic unit of audio data. A single digital sample from one channel.
sample frame: A set of samples, one per channel. (In the trivial case of a single channel, synonymous with sample.)
precision: The size (in bits) of a sample.
signed linear: An audio encoding where the sample is represented by a signed number, with 0 as the centerpoint.
unsigned linear: An audio encoding where the sample is represented by an unsigned number with 1/2 range, e.g. 128 or 32768, as the centerpoint.
A standard audio-CD player has a digital output sound channel that uses unsigned linear unencoded (PCM) 16 bit sample precision per channel (2 channels for stereo) at a frame rate of 44.1KHz. The sound information would be defined in the above
terms by:
The following properties document the possible values to which the device can be set.
"device_type" S
Standard property name to define the device's implemented interface.
The meaning of this property is as defined in the Open Firmware core document. The value for nodes described by this specification shall be "sound".
"#input-channels" S
property name, defines the possible numbers of input channels supported.
prop-encoded-array: Arbitrary number of integers, each encoded with encode-int.
"#output-channels" S
property name, defines the possible numbers of output channels supported.
prop-encoded-array: Arbitrary number of integers, each encoded with encode-int.
"sample-precisions" S
property name, defines the possible sample precisions.
prop-encoded-array: Arbitrary number of integers, each encoded with encode-int.
Specifies the possible numbers of bits required to store one audio sample from one channel.
"sample-frame-size" S
property name defines the possible sample frame sizes.
prop-encoded-array: Arbitrary number of integers, each encoded with encode-int.
Specifies the possible numbers of bits required to store one sample frame - one sample from each channel.
"input-frame-rates" S
property name, defines the possible sample frame rates for audio input.
prop-encoded-array: Arbitrary number of integers, each encoded with encode-int.
Specifies the possible input sampling rates, in sample frames per second.
"output-frame-rates" S
property name, defines the possible sample frame rates for audio output.
prop-encoded-array: Arbitrary number of integers, each encoded with encode-int.
Specifies the possible output sampling rates, in sample frames per second.
"input-encoding-types" S
property name, defines the possible input encoding types.
prop-encoded-array: The concatenation, with encode+, of an arbitrary number of text strings, each encoded with encode-string.
Specifies possible input encodings. Valid values include:
"8bit-u-law"
"8bit-A-law"
"8bit-unsigned-linear"
"8bit-signed-linear"
"16bit-LE-unsigned-linear"
"16bit-BE-unsigned-linear"
"16bit-LE-signed-linear"
"16bit-BE-signed-linear"
"4bit-ADPCM"
"output-encoding-types" S
property name, defines the possible output encoding types.
prop-encoded-array: The concatenation, with encode+, of an arbitrary number of text strings, each encoded with encode-string.
Specifies possible output encodings. Valid values are as for "input-encoding-types".
The following methods shall be implemented by a "sound" device.
open ( -- true | false ) M
This standard method prepares the "sound" device for subsequent reads and/or writes.
close ( -- ) M
Standard Open Firmware behavior.
read ( addr size -- actual ) M
Acquire sound data, storing the samples at addr.
write ( addr size -- actual ) M
Output sound samples stored at addr.
Access to NVRAM is supported by this device-type. The NVRAM is treated as a device that can be read and written using the standard Open Firmware read and write methods; the starting position within the NVRAM can be specified by the
seek method.
"device_type" S
Standard property name to define the device's implemented interface.
The meaning of this property is as defined in the Open Firmware core document. The value for nodes described by this specification shall be "nvram".
"#bytes" S
property name, describes the number of bytes the device is capable of storing.
prop-encoded array: An integer, encoded as with encode-int.
The value is the number of bytes for the physical device. Typical values could be 4K, 8K, 16K or 32K bytes.
The following methods have the semantics of the Open Firmware methods:
read ( addr len -- actual ) M
write ( addr len -- actual ) M
seek ( pos.lo pos.hi -- status ) M
size ( -- size ) M
The returned value, size, is the number of NVRAM bytes available to the client interface.
The following methods have additional behavior depending upon the argument used to open the device.
open ( -- true | false ) M
Standard method used to initiate access to the device
close ( -- ) M
Standard Open Firmware behavior
Access to the serial port is supported by this device type. The serial port is treated as a byte-stream device.
As specified in [1] and [6] , with the following additions or modifications.
"device_type" S
Standard property name to define the device's implemented interface.
The meaning of this property is as defined in the Open Firmware core document [1]. The value for nodes described by this specification shall be "serial".
As specified in [1] and [6], with the following additions or modifications.
open is a standard method for the serial device. When the serial device is opened, several device-arguments can be passed as defined below:
driver-name@unit-address:device-arguments
device-arguments are defined to be of the form, e.g. 9600,8,n,1,- and sets the UART parameters (baud rate, data bits, parity, stop bits, and handshake) accordingly. The serial device default mode is 9600,8,n,1,- if the open
arguments are not specified.
The fields are (in order, left to right):
<baud rate>, <data bits>, <parity>, <stop bits>, <handshake>
Fields with empty values are not changed. Values for fields are whatever the hardware will support:
baud rate: various, including 110, 300, 1200, 2400, 4800, 9600, 19200, 38400
data bits: 5,6,7,8
parity:
-------------
char meaning
-------------
n none
e even
o odd
m mark
s space
-------------
stop bits:
----------------
char meaning
----------------
1 1 stop bit
. 1.5 stop
bits
2 2 stop
bits
----------------
handshake:
--------------------------
char meaning
--------------------------
- none
h hardware (RTS/CTS)
s software (XON/XOFF)
--------------------------
As specified in [1] and [6], with the following additions.
set-mode ( adr len -- ) M
Sets the device mode according to the string at adr, of length len, which is interpreted the same as the arguments to the open method (see section 8.2.1.1. on page 9).
set-modem-control ( bitmask -- ) M
Sets the device's modem control lines according to the following table:
----------------------------
bitmask Modem control state
----------------------------
0 RTS off, DTR off
1 RTS off, DTR on
2 RTS on, DTR off
3 RTS on, DTR on
----------------------------
The response for other values of bitmask are implementation dependent.
Changing the bits associated with these lines shall have no effect on other bits not associated with this function.
Access to the network is supported by this device type. The network device is treated as a byte-stream device.
These properties shall be reported by packages representing "network" devices.
"device_type" S
Standard property name to define the device's implemented interface.
The meaning of this property is as defined in the Open Firmware core document. The value for nodes described by this specification shall be "network".
"supported-network-types" S
property name, reports possible types of "network" the device can support.
prop-encoded-array: a string, as encoded with encode-sting.
The string is chosen from the following set representing <network type>, <speed (Mbps)>, <connector type> and <duplex mode>:
"ethernet,10,rj45,half"
"ethernet,10,rj45,full"
"ethernet,100,rj45,half"
"ethernet,100,rj45,full"
"ethernet,10,aui,half"
"ethernet,10,aui,full"
"ethernet,100,aui,half"
"ethernet,100,aui,full"
"ethernet,10,bnc,half"
"ethernet,10,bnc,full"
"ethernet,100,bnc,half"
"ethernet,100,bnc,full"
"token-ring,4,rj45,half"
"token-ring,4,rj45,full"
"token-ring,16,rj45,half"
"token-ring,16,rj45,full"
"token-ring,4,9pin,half"
"token-ring,4,9pin,full"
"token-ring,16,9pin,half"
"token-ring,16,9pin,full"
"fddi,100,rj45,half"
"fddi,100,sc,half"
"fddi,100,mic,half"
"atm,100,sc,full"
"atm,155,sc,full"
"atm,622,sc,full"
"fcs,1000,sc,full"
"chosen-network-type" S
property name, reports type of "network" this device is supporting.
prop-encoded-array: a string, as encoded with encode-string, that is chosen from one of the values in "supported-network-types" property.
If present, indicates that the firmware or the user has selected one of the "supported-network-types" and the value indicates which one was chosen. The "chosen-network-type" property need not exist if the firmware cannot determine
the "network" type or there is only a single "network" type choice.
As specified in [1], Section 3.7.4, the standard methods are supported with the addition of new arguments passed through the open method. The open method of the device shall parse the
obp-tftp package's open method. The device arguments shown below for the device open method must come first and the comma's in the arguments are required if another parameter follows. Values for device arguments are defined
below:
open network-device:[promiscuous,][speed=n,][duplex=mode,][obp-tftp parameters]
where:
promiscuous puts network device in a mode where all addresses are
recognized; e.g., a communication device that snoops the LAN.
speed=n where n indicates the "network" speed in Mbps. Typical
values can be 4, 10, 16, 100, 155, 622 & 1000 Mbps.
duplex=mode where mode values are "half" or "full".
obp-tftp parameters - Reference [6] for additional information.
The device arguments, promiscuous, speed and duplex are optional and may be in any order, but a recommended order is as shown. These three parameters must be the first parameters.
The obp-tftp parameters siaddr, filename, ciaddr, giaddr, bootp-retries, tftp-retries are optional. If any of these parameters are present, then the bootp parameter shall be present and precede the other parameters.
The open method for the network device could have the following parameters, including passing through ones for the obp-tftp package open method:
open network-device:[promiscuous,][speed=n,]
[duplex=mode,][bootp],[siaddr],[filename],[ciaddr],
[giaddr],[bootp-retries],[tftp-retries]
Network device open method parameter examples:
open network-device: promiscuous,speed=100,duplex=full,bootp,
siaddr,filename,ciaddr,giaddr,bootp-retries,tftp-retries
open network-device: duplex=half,,,,,bootp-retries
open network-device: promiscuous,bootp,siaddr,,,,,tftp-retries
Note: Comma's are required for missing open method's positional parameters unless they are at the end of a list.
The following is a defined order of operations for the network device FCode. The network device FCode will look at the following items to determine precedence of operations for initialization/configuration:
1) The network device open method parameters; if none present, then,
2) The value of "chosen-network-type" property; if not present, then,
3) The network device will be implementation specific, depending on the
devices capability.
If the open method does not recognize a value for n or mode (speed or duplex mode) parameters or the network device cannot execute the specified value for n or mode, a failure should result (device should
not open) with a warning message to the user.
Access to the parallel port is supported by this device-type. The parallel port is treated as a byte-stream device.
"device_type" S
Standard property name to define the device's implemented interface.
The meaning of this property is as defined in the Open Firmware core document. The value for nodes described by this specification shall be "parallel".
The following methods have the semantics of the corresponding Open Firmware standard methods:
open ( -- true | false ) M
close ( -- ) M
write ( addr len -- actual ) M
A node representing a SCSI-2 device shall implement all the methods and properties specified in Annex E, sections E.1 through E.5 of [1].
"wide" S
property name, indicates that the SCSI-2 Node is wide.
prop-encode-array: <none>
This property shall be present if the SCSI-2 controller represented by this node is wide, with SCSI-2 ID ranges 0 through 15, and shall be absent otherwise.
In order to support the wide SCSI-2, the example in Appendix E.6.3 of [1] would be amended as follows:
E.6.3 hacom.fth
...
: show-children ( -- )
open 0= if ." Can't open SCSI-2 host adapter" cr exit then
" wide" get-my-property if 8 else 2drop d# 16 then
0 do
i probe-target if
." Target " i . cr
8 0 do i j show-lun loop
then
loop
;
"differential"
property name, indicates that the SCSI-2 Node supports differential signaling.
prop-encode-array: <none>
This property may be present if the SCSI-2 controller represented by this node supports differential signaling.
"scsi-initiator-id"
property name, indicating the initiator-id to be used for SCSI-2 transfers by this controller.
prop-encode-array: An integer, encoded as with encode-int.
The integer specifies the value of the initiator-id for subsequent transfers by this controller. If the "wide" property is not present the value is in the range of 0..7. If the "wide" property is present the value is in the range
f 0..15. The initial value of the property is implementation dependent.
open ( -- true ) M
In addition to the standard Open Firmware behavior, the open method shall set the host adapter's own selection ID as follows:
Attempt to locate a "scsi-initiator-id" property by executing "get-inherited-property" with the string "scsi-initiator-id" as its argument. If such a property is found, decode its value as with "decode-int", and use the
decoded value as the host adapter's own selection ID. Otherwise, use the value 7.
Note: The use of "get-inherited-property" to get the "scsi-initiator-id" property makes it possible to choose the set of SCSI-2 host adapters to which the property applies. If the property is in the root node, for example, it applies to all the
SCSI host adapters in the system. If the property is elsewhere in the device tree, it applies only to host adapters in the subtree below and including the location of the property.
The disk-label standard support package and packages of device type block and byte shall implement the following method:
size ( -- d ) M
Return the size of the device in bytes.
Return, as a double number "d", the number of bytes of storage associated with the device or instance. If the size cannot be determined, return the double number -1.
Packages of device type block and byte shall implement the following method:
#blocks ( -- u ) M
Return the size of the device in blocks.
Return, as an unsigned number "u", the number of blocks of storage associated with the device or instance, where a block is a unit of storage consisting of the number of bytes returned by the package's block-size method. If the siz
cannot be determined, or if the number of blocks exceeds the range of an unsigned number, return the maximum unsigned integer (which, because of Open Firmware's assumption of two's complement arithmetic is equivalent to the signed number -1).
The disk-label standard support package and packages of device type "block" shall implement the following methods:
offset-low ( -- u ) M
Returns the least significant cell of the double number denoting the beginning offset of the disk partition that was specified when the disk-label support package was opened. In general that offset is obtained by executing the
offset method of the "disk-label" support package with an argument of zero. It is permissible for the disk package to execute the disk-label
support package's offset method once after opening that support package, storing the result for later us.
offset-high ( -- u ) M
Returns the most significant cell of the double number denoting the beginning offset of the disk partition that was specified when the disk-label support package was opened. In general that offset is obtained by executing the offsetdisk-label support package with an argument of zero. It is permissible for the disk package to execute the disk-label support package's offset method once after opening that support package, storing the result for late
use.
-- END OF DOCUMENT --