# Serial Interface Specification

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

## Contents

1.0 | Overview
2.0 | Outstanding issues
3.0 | Technical background
4.0 | User interface
5.0 | Programmer interface
6.0 | Acceptance test
7.0 | Development test strategy
8.0 | Product organisation
9.0 | Future enhancements
10.0 | Glossary
11.0 | References
12.0 | History

## 1.0 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.

## 2.0 Outstanding issues

- Acorn to establish device registration procedure.
- Acorn to establish `IOCtl` allocation procedure.

## 3.0 Technical background

### 3.1 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.

#### 3.1.1 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.

#### 3.1.2 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.

#### 3.1.3 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.

## 4.0 User interface

None provided.

## 5.0 Programmer interface

### 5.1 Introduction

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>:`

### 5.2 Ports

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).

- `serial1` - serial port 1 on the combo chip
- `serial2` - serial port 2 on the combo chip

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:`.

### 5.3 Configuration

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.

### 5.4 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 :
   - 50, 75, 110, 150, 300, 600, 1200, 1800, 2400, 3600, 4800, 7200, 9600, 19200, 38400, 56000 or 115200

2. set/read data format :
   - bits 0-7 : data length (5,6,7 or 8)
   - bits 8-15 : number of start/stop bits (1 or 2)
   - bits 16-23 : parity encoded as
     - 0 - no parity
     - 1 - even parity
     - 2 - odd parity
   - bits 24-31 : reserved (should be 0)

3. set/read handshaking :
   - 0 - no handshake
   - 1 - rts/cts handshaking
   - 2 - xon/xoff handshaking
   - 3 - dtr/dsr handshaking

4. set/read buffer size :
   - Size of buffer in bytes used for rx/tx (depending upon stream). If the buffer has already been created, this call will fail by returning the actual buffer size.

5. set/read rx/tx buffer threshold point :
   - rx buffer, sets the point at which handshaking will be invoked.
   - tx buffer, sets the point at which upcall notification is sent to higher level modules/applications to indicate tx space available.

6. set/read control lines :
   - bits 0-15 read/writable bits
     - bit 0 : DTR (1 = /DTR active, i.e. low)
     - bit 1 : RTS (1 = /RTS active, i.e. low)
   - bits 16-31 read only flags
     - bit 16 : CTS (1 = /CTS active, i.e. low)
     - bit 17 : DSR (1 = /DSR active, i.e. low)
     - bit 18 : RI (1 = /RI active, i.e. low)
     - bit 19 : DCD (1 = /DCD active, i.e. low)
     - bit 20 : fifos enabled

7. set/read fifo trigger level :
   - This sets the number of bytes that need to be present in the 16 byte fifo in order for an interrupt to be generated. Valid options for this are 1, 4, 8 or 14.

8. read number of supported baud rates :
   - This returns the number of baud rates supported by the driver. It should be used in conjunction with the ioctl below to enumerate baud rates.

9. read baud rate associated with index <n> :
   - This will return the baud rate associated with index <n>. <n> is an index between 0 and number of supported baud rates-1.
10. flush buffer :
    - write will flush contents of current buffer.
    - read will return an undefined value.
11. read IR capability of port :
    - bit 0 : IrDA capable
    - bit 1 : ConsumerIR capable
    - bit 2 : ASK-IR capable
    - bits 3-31: Reserved
12. set/read IR status of port :
    - 0 : Wired
    - 1 : IrDA
    - 2 : ConsumerIR capable
    - 3 : ASK-IR capable
    - All other values reserved

### 5.5 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 :

- `type devices:$.serial1` - echo's to the screen any characters received on serial port 1.
- `copy <filename> devices:$.serial1` - copies the data in file `<filename>` to serial port 1.
- swi interface
  - `OS_Find` to open a stream for tx/rx
  - `OS_GBPB 2,4` to perform block read/writes from/to the stream
  - `OS_BPut` to transmit a character
  - `OS_BGet` to fetch a character
  - `OS_Args 2` to obtain the amount of data in rx stream buffer and amount of free space in tx stream buffer

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.

### 5.6 Asynchronous notification

#### 5.6.1 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

#### 5.6.2 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

#### 5.6.3 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

#### 5.6.4 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

## 6.0 Acceptance test

## 7.0 Development test strategy

## 8.0 Product organisation

Requires modules FileSwitch (2.36), BufferManager (0.25), DeviceFS (0.34) or greater. These modules are contained within NC-OS release 1.06 and greater, and also in RISCOS 4

## 9.0 Future enhancements

## 10.0 Glossary

## 11.0 References

## 12.0 History

Revision | Who | Date | Comment
0.01 | RWB | 22 Jan 1997 | Created based on Acorn internal documentation.
0.02 | RWB | 30 Jan 1997 | Reformatted.
0.03 | RWB | 17 Jun 1997 | Added IOCtl 10 for flushing buffers
0.04 | WT | 18 Aug 1998 | Added IOCtls 11 and 12 for Phoebe

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