Introduction and Overview
FileSwitch has been extended with support for enumerating file handles, a catalogue filename width, IOCtl operations, and a reminder about the redeclaration of filing systems.
Technical Details
Enumerate Handles
A reason code is available within FileSwitch version 2.44 onward to enumerate file handles. This allows clients to obtain information on open files using a defined interface rather than relying on knowledge of the earlier restriction within FileSwitch of 255 file handles, allocated sequentially downward from 255. This reason code is used by clients wishing to enumerate open file handles. Clients should be aware that filing system operations may occur during the enumeration process and should take appropriate action. See SWI OS_FSControl 3A.
Catalogue filename width
A variable, FileSwitch$NameWidth, can be set to give the width of filenames in the *Cat display. It has a minimum value of 12, and a maximum value of 255. This can be set at any time and will be read per-use of *Cat. It is present in all versions of FileSwitch since RISC OS 4.
IOCtl operations
From FileSwitch 2.36 onward support has been added for IOCtl calls. These allow 'control' commands from the client opening the file. An OS_Args reason code has been added to support this, and a new bit added to the extra filing system information word. See SWI OS_Args 9. This operation will be passed to the FileSystem Args entry as reason code 11.
The IOCtl parameter block takes the following form :
| Offset | Contents | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Flags:
| ||||||||||||||||||||||||||
| 4... | Data for operation | ||||||||||||||||||||||||||
Parallel IOCtl operations
The following parallel IOCtl operation reason codes are supported by the parallel device driver :
- Read Device ID size
- Read Device ID data
- Read Reverse Nibble status size
- Read Reverse Nibble status data
In each case the first word of the data indicates the size of the buffer.
FIXME: The IOCtl reason code numbers for the parallel operations are not documented.
Serial IOCtl operations
The following serial IOCtl operation reason codes are defined for serial devices :
| Reason | Operation | Data | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | Baud rate | One word containing the baud rate (bits per second) | ||||||||||||||||||||||||||||||
| 2 | Data format | One word containing flags indicating data format:
| ||||||||||||||||||||||||||||||
| 3 | Handshake | One word containing the handshaking type:
| ||||||||||||||||||||||||||||||
| 4 | Buffer size | Size of buffer used for transfers | ||||||||||||||||||||||||||||||
| 5 | Buffer Threshold | Trigger for handshaking or upcall notification | ||||||||||||||||||||||||||||||
| 6 | Control lines | One word containing flags:
| ||||||||||||||||||||||||||||||
| 7 | FIFO trigger | Number of bytes in FIFO before an interrupt is generated. | ||||||||||||||||||||||||||||||
| 8 | Read number of baud rates | Returns a word containing the number of baud rates available | ||||||||||||||||||||||||||||||
| 9 | Read baud rate index | Supplies one word of index numbers and reads the baud rate associated with that index. | ||||||||||||||||||||||||||||||
| 10 | Flush buffer | Flushes buffer on write; undefined on read | ||||||||||||||||||||||||||||||
| 11 | Read IR capabilities | One word containing flags:
| ||||||||||||||||||||||||||||||
| 12 | IR status | One word containing the type of IR:
| ||||||||||||||||||||||||||||||
Generic IOCtl operations
The following IOCtl operations have been defined for generic operations :
- Non-blocking operation. A word containing 0 for blocking operation, any other value indicating non-blocking operation
- Buffer threshold. A word indicating a point in the buffer at which a notification will be raised.
- Flush stream. No data; writing causes all pending data to be discarded
- Timeout. Time in centiseconds before a blocking operation should be considered failed.
FIXME: The IOCtl reason code numbers for the generic operations are not documented.
Filing system redeclaration
As a reminder, PRM 2-524 indicates that filing systems should redeclare themselves to FileSwitch when Service_FSRedeclare is issued. Some external filing systems do not do this and thus cannot cope when the FileSwitch module is restarted.
SWI Calls
| R0 | = | 58 (reason code) |
| R1 | = | Last handle, or -1 to start at first handle |
| R0 | = | Stream status word, or preserved if no more handles exist |
| R1 | = | File handle, or -1 if no more handles exist |
| R2 | = | Filing system info word, or preserved if no more handles exist |
This reason code is used by clients wishing to enumerate open file handles. Clients should be aware that filing system operations may occur during the enumeration process and should take appropriate action.
| R0 | = | 9 (reason code) |
| R1 | = | File handle |
| R2 | = | Pointer to parameter block |
| R0 - R2 | = | Preserved |
This call is used by clients wishing to control devices at the other end of a file handle. This may be used for filing specific operations. This operation will be passed to the FileSystem Args entry as reason code 11.