Serial Interface Specification

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

	Overview
	Technical background
	User interface

Overview

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

	IOCtl

	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.