Serial Interface Specification

Document ref: 1309,424/FS
Revision: 0.04
Date: 18-Aug-1998
Author(s): Rich Buckley, William Turner


Technical background
User interface
Programmer interface


On modern Acorn hardware, there are two serial ports supported by the combo chip. In order for both these to be supported, a different mechanism for handling serial type devices and passing data to and from them is required.

This documentation describes the programmers interface provided by the new serial device driver. It is intended that any other serial/uart type devices that are to be supported under RiscOS and NC-OS will conform to this interface but use a different device name. Device names will be allocated by Acorn.

Technical background

IOCtl support

The modules FileSwitch and DeviceFS now support IOCtls. This allows a device driver to receive a control command from an application based on either an open file handle or a directory path in DeviceFS as required by the serial module. The following modifications have taken place to achieve this support.

FileSwitch (2.36)

A new OS_Arg reason code has been allocated OSArgs_IOCtl this has the following arguments.
	On entry
		r0 = 9 (reason code)
		r1 = file handle
		r2 -> ioctl parameter block
	On exit
		r0 preserved
		r1 preserved
		r2 preserved
A new bit has been allocated in the extra filing system information word (PRM 2-523) as follows
	Bit	Meaning if set
	3	Filing system supports OS_Arg IOCtl.
Filing systems should set this bit if they intend to support OS_Arg IOCtl. Existing filing systems will have this bit clear so will never be asked to handle this call.

If the registered filing system supports the IOCtl OS_Arg swi, the call will be dispatched using the normal entry point and reason code. It is up to the underlying filing system to impose a meaning on the registers r2-r7.

DeviceFS (0.34)

DeviceFS now sets the bit in the extra filing system information word to indicate that it wants to handle OS_Arg IOCtl.

A new DeviceFS_CallDevice reason code has been allocated DeviceCall_IOCtl this has the following arguments when received.

DeviceDriver_Entry 14


	On entry
		r0 = 14 (reason code)
		r1 = file handle
		r2 = stream handle
		r3 -> ioctl parameter block as passed in r2 of OS_Args call
	On exit
		r0 preserved
		r1 preserved
		r2 preserved
		r3 preserved
This call is dispatched to the underlying device driver whenever the OS_Arg IOCtl swi is called or the swi DeviceFS_CallDevice (14) is called.

Calling convention

The following calling convention should be adopted when using this ioctl interface. Fields have been taken from the unix ioctl implementation as shown below.
	On entry
		r2 -> ioctl parameter block
	On exit
		r2 preserved
where ioctl control block is a pointer to the following structure
	typedef struct {
		unsigned int reason   : 16; /* ioctl reason code */
		unsigned int group    : 8;  /* ioctl group code */
		unsigned int reserved : 6;  /* should be zero */
		unsigned int read     : 1;  /* read flag */
		unsigned int write    : 1;  /* write flag */
		unsigned int data;          /* actual data */
	} ioctl_t;
In the case of an ioctl called with both read and write flags set, the returned value will be the new or latest value of the parameter being accessed.

User interface

None provided.

Programmer interface


A consistant interface is provided to the two internal serial ports. The API for configuration of these ports is documented in sections below.

The serial data input/output interface is provided through the DeviceFS interface with data transfers analogous to file read/writes. The control interface is provided by ioctls as documented below.

Input and/or output to DeviceFS streams should be made on the file path : devices:$.<stream name>

DeviceFS also establishes an environment variable to allow simpler access to this path. This would be constructed as : <stream name>:


The serial module registers a number of streams (files) within the DeviceFS filing system. Any application wishing to see what ports are available would enumerate the contents of the directory devices:$. The following streams are present for NC and Phoebe hardware (serial1 not present on the latter if port1 is in backwards-compatible mode).

Support for further serial devices would require device name allocations with the relavent driver registering the new device with DeviceFS alongside the existing ports. Examples would be serial3:, modem1:.


The configuration of the serial ports works by having a special string passed to DeviceFS when the stream is opened for input/output. The position of this configuration string within the file path is demonstrated below :
devices#<configuration options>:$.serial1
Where <configuration options> can be made up of any of the following entries in order. Some fields may be omitted and this will leave the option unchanged. Currently due to a problem with DeviceFS, the options should be given in order. A semicolon ';' is used to separate option fields.
  1. baud<n> - baud rate in bps
  2. data<n> - data length in bits
  3. stop<n> - number of start/stop bits
  4. [noparity|even|odd] - type of parity required
  5. [nohandshake|rts|xon|dtr] - type of handshaking required
  6. size<n> - size of buffer
  7. thres<n> - buffer threshold point
For example '#baud19200;data8;stop1;noparity;rts;size1024;thres32'. In fact this is the default state of the driver on initialisation. Except the tx buffer will default to 512 bytes. It should be noted that the current behaviour of DeviceFS requires the above special string fields to be presented in the exact order given above. This may be fixed in future versions of DeviceFS.

If any of the parameters are invalid, for example baud rate not supported, the request to open the stream is refused.

IOCtl configuration

Direct control of the serial port control lines can be achieved using the IOCtl interface described above. This will have the following reason codes.
  1. set/read baud rate :

  2. set/read data format :

  3. set/read handshaking :

  4. set/read buffer size :

  5. set/read rx/tx buffer threshold point :

  6. set/read control lines :

  7. set/read fifo trigger level :

  8. read number of supported baud rates :

  9. read baud rate associated with index <n> :
  10. flush buffer :
  11. read IR capability of port :
  12. set/read IR status of port :

Data transfer

Once the DeviceFS stream has been chosen, data input/output is carried out using standard file access on the stream path name. For example : It should be noted that a single DeviceFS stream cannot be opened for read/write access. Two streams should be opened and maintained. If the second stream is opened with different line characteristics for example a different baud rate, the initial settings will be overwritten in preference of the latest.

To obtain the functionality of swi OS_Args 2 required a change to DeviceFS to allow this information to be returned. You therefore require version 0.31 or greater of DeviceFS in order to implement this functionality.

It should also be noted that the behaviour of DeviceFS means that the functions to read data from an input stream are blocking. OS_Args 2 should therefore be used to check the amount of data present in an input stream before a read is requested.

Asynchronous notification

Data present

An upcall is dispatched whenever data enters a previously empty input buffer. This required a change to the BufferManager module therefore requiring version 0.25 or greater.
	On entry
		r0 = 15 (upcall code Upcall_DeviceRxDataPresent)
		r1 = stream handle

Threshold above

An upcall is dispatched whenever the amount of data in a stream exceeds the threshold value.
	On entry
		r0 = 16 (upcall code UpCall_DeviceThresAbove)
		r1 = stream handle

Threshold below

An upcall is dispatched whenever the amount of data in a stream falls below the threshold value.
	On entry
		r0 = 17 (upcall code UpCall_DeviceThresBelow)
		r1 = stream handle

Serial errors and line status changes

An event is generated whenever DSR or DCD change or when a line error (parity, framing, overrun) occurs.
	On entry
		r0 = 7 (event code Event_RS423Error)
		r1 = flags
			SerialEvent_Parity         bit 5
			SerialEvent_Overrun	   bit 4
			SerialEvent_Framing	   bit 3
			SerialEvent_DSR		   bit 2
			SerialEvent_DCD		   bit 1
		r2 = input stream handle

This document must not be copied, reproduced or disclosed in part or whole. by Acorn Network Computing, UK.
© Acorn Computers Ltd 1997