DeviceFS Technical Details (changes)
Showing changes from revision #3 to #4:
Added | Removed | Changed
DeviceFS
» DeviceFS Technical Details
DeviceFS Technical Details
Special Fields
Special Fields within the DeviceFS are commonly used to specify parameters to the device. ie what buffers to be used, if the device should be flushing when a stream is closed and so on.
A validation string can be specified to parse the special field when the stream is being opened. DeviceFS will parse the string and return a block of data that relates to the string contents. The data will remain intact for as long as the stream remains open. If no validation string is specified then it is the duty of the device to take and manage a copy of the data and filter out any unwanted information.
Validation Strings
The syntax for validation strings is as follows:
keyword [, keyword ]/ escape_seq [/ escape_seq ]
Keywords
Keywords associate each command with an escape sequence. More than once keyword can be associated with a particular escape field. The reason for this is twofold
- When a different word has the same meaning. e.g. Colour or color
- When defining the various states for a switch
The escape sequence describes how preceding data should be validated and what to do with the rest of the special field string (up to the next separator).
The Characters below are valid within in escape sequences:
/N number
/S switch
Parameters
Within the special field string each parameter is separated by a comma or a character which is out of place, ie a non-numeric in a numerical field. Each keyword within the special field string is separated by a semi-colon.
The buffer passed to the device contains 1 word per escape character, set to &DEADDEAD if the corresponding keyword is not present in the special field string.
Numbers are simply read stored with into the word; they are decoded usingOS_ReadUnsigned and stored away. in Switches store the state word. of the keywords placed, ie:
Switches store the number of the parameter in the switch’s validation string.
mike,dennis/S
Given a device called Serial and a validation string of
baud,rate/Nnohandshake,xon,rts,dtr/Snoparity,even,odd/Sdata/N
the file name serialbaud19200;noparity: would yield
| Offset | Value | Explanation |
|---|---|---|
| 0 | 19200 | number |
| 4 | &DEADDEAD | handshake keyword not supplied |
| 8 | 0 | noparity is first entry in switch |
| 12 | &DEADDEAD | data keyword not supplied |
and serialrate28800;dtr;even;data7: would yield
| Offset | Value | Explanation |
|---|---|---|
| 0 | 28800 | rate is an alias for baud |
| 4 | 3 | dtr is fourth entry in switch |
| 8 | 1 | even is second entry in switch |
| 12 | 7 | number |
This yields 0 if ‘mike’ is present within the string, 1 if ‘dennis’ is present within the string.
The order of commands within the validation string and the special field string need not match; the commands within the validation string control how the values are returned back to the caller.
Device Description
Devices are specified as a list of 24 byte blocks, terminated by a null word.
| Offset | Contents |
|---|---|
| 0 | Offset to zero terminated device name from start of this block |
| 4 | Bit 0 set for buffered |
Bit 1 set to create path variable (e.g. Serial$Path for a device Serial) |
|
| 8 | Default RX buffer flags |
| 12 | Default RX buffer size |
| 16 | Default TX buffer flags |
| 20 | Default TX buffer size |
| 24 | Reserved (must be zero) |
The device name is used:
- in the DeviceFS directory structure
- to create a
DeviceFS$Device$optionsvariable if this does not exist - a path variable (if the flag bit is set)
See also
Social
and
ROOL Store
Buy RISC OS Open merchandise here, including SD cards for Raspberry Pi and more.