OS_Args 9 Support

OS_Args 9 is still undocumented in the usual RISC OS PRMs (even 2010). It seems that it has been introduced around 1996 and allows you to perfom some IO-Control operations on certain fileswitch handles.

Fileswitch will pass the request to the according filing system. Eg. at DeviceFS some requests are handled internally. Others are passed as a special DeviceCall to the device drivers.

OS_Args 9 takes the file switch handle in R1 and a pointer to a so called IOCTL-block in R2. The request are decoded inside this block. For the FTDI driver this is done as follows:

Word Bit Meaning
0 31 Set means write required.
30 Set means read required.
16-29 Group code
0-15 Reason code
1 contains data at entry for write if requested and at exit the read value if requested.

If reading and writing is requested reading is performed before writing so that the old vlaue will be returned.

In IO-Mode (serial is the only mode supported by the driver in the moment) group code is always 0. The reason codes are as follows (puzzled from ROOLs source and documents):

Reason code Action Word 1 on entry Word 1 on exit
0 Do nothing. No read or write Bit set! - -
1 Read/Set baud rate. baud rate baud rate
2 Read/Set data format Format
Bit Meaning
0-7 Number of Data Bits
8-15 Number of Stop Bits
16-23 Parity (Format unknown)
see above
3 Set handshaking
Value Handshaking type
0 None (uncertain whether it is RISC OS compatible)
1 RTS/CTS
2 XON/OFF
3 DTR/DSR
4 Read/Set buffer size. Ignored.
5 Read/Set buffer threshold. Ignored.
6 Read/Set Control lines. Contains control line information to set.
Bit Meaning Can be set
0 DTR Yes
1 RTS Yes
16 CTS No
17 DSR No
18 RI No
19 DCD No
20 Fifo present (Not supported in the moment) No
Contains control line status. See above.
7 Read/Set fifo threshold. Ignored.
8 Return number of possible Baud rates (Read only!). number of baud rates
9 Return a certain Baud rate (Read only!). Required baud rate (position number. base = 0 (uncertain whether this matches RISC OS Standard)) baud rate
10 Flush buffer. Ignored.
11 Clear buffer (of FTDI). No read or write Bit set! - -

In parallel mode if it should be implemented the group code would be also 0 and there would be the following reason codes:

Reason code Action Word 1 on entry Word 1 on exit
0 Do nothing. No read or write Bit set! - -
6 Read/Set Control lines. Contains control line information to set. Contains control line status
11 Clear buffer (of FTDI). No read or write Bit set! - -

All other codes will generate an error.

All this has been setup in accordance to newer RISC OS hardware drivers for the according interfaces.

This concept overcomes some limitations of classic RISC OS direct port access SWIs which are limited to exactly one port. This allows eg. terminal programms which formerly dealt with a couple of SWIs to handle settings like the baudrates to implement one interface valid for all ports they wish to handle.

To provide implementation of full compatibility eg for control line access it is possible to bypass OS_Args 9 which would require an open stream by direct CallDevice actions. In this case the IOCTL-Block must be passed in R3 instead of R2.