Serial Interface Specification

Contents

Overview

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

FileSwitch (2.36)

	On entry
		r0 = 9 (reason code)
		r1 = file handle
		r2 -> ioctl parameter block
	On exit
		r0 preserved
		r1 preserved
		r2 preserved

	Bit	Meaning if set
	3	Filing system supports OS_Arg IOCtl.

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)

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

Calling convention

	On entry
		r2 -> ioctl parameter block
	On exit
		r2 preserved

	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;

User interface

Programmer interface

Introduction

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

Ports

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

Configuration

devices#<configuration options>:$.serial1

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

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

IOCtl configuration

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

Data transfer

• 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

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

	On entry
		r0 = 15 (upcall code Upcall_DeviceRxDataPresent)
		r1 = stream handle

Threshold above

	On entry
		r0 = 16 (upcall code UpCall_DeviceThresAbove)
		r1 = stream handle

Threshold below

	On entry
		r0 = 17 (upcall code UpCall_DeviceThresBelow)
		r1 = stream handle

Serial errors and line status changes

	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