Commit 6d9247f3 authored by ROOL's avatar ROOL :robot:
Browse files

This commit was manufactured by cvs2git to create branch 'Ursula_RiscPC'.

Sprout from Ursula 1998-07-21 14:35:30 UTC William Turner <wturner@gitlab.riscosopen.org> 'A couple of superficial changes to the file structure have resulted in CVS'
Delete:
    Docs/Ursula
    Docs/serial.htm,faf
parent 5431cfdd
Ursula changes for DualSerial
-----------------------------
On Phoebe, we have 2 serial ports as standard in the combo chip.
However, unlike the NC, these ports have individual interrupts, and
so this needs to be changed in the DualSerial source. Also, the second
serial port on Phoebe is capable of acting over an IR link OR a wire
link.
In order to add this, a pair of IOCtl reason codes will be added...
IOCtl reason code 11
read IR capability of port
bit
0 - IrDA capable
1 - ConsumerIR capable
2 - ASK-IR
IOCtl reason code 12
set/read IR status of port
0 - Wired
1 - IrDA
2 - ConsumerIR
3 - ASK-IR
note that the 'capability' of being driven in a set mode does not imply
anything about the data format required.
An additional problem is that we need to retain as much backwards compatibility
as possible, namely OS_SerialOps etc.
<HTML>
<HEAD>
<TITLE>
Serial Interface Specification
</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
<CENTER>
<H1>
NOTE: THIS VERSION OF THE CODE CONTAINS IOCtls 11 AND 12, WHICH WERE ADDED FOR DAYTONA BUT ARE NOT DOCUMENTED IN THIS F.S.
</H1>
</CENTER>
<CENTER>
<H1>
Serial Interface Specification
</H1>
</CENTER>
<HR>
<CENTER>
<TABLE BORDER=0 WIDTH=40%>
<TR><TD>Document ref: <TD>Not yet issued
<TR><TD>Project: <TD>
<TR><TD>Revision: <TD>0.03
<TR><TD>Date: <TD>16-Jun-1997
<TR><TD>Author(s): <TD>Rich Buckley
<TR><TD>AMR: <TD>
</TABLE>
</CENTER>
<HR>
<H2> Contents </H2>
<TABLE BORDER=0 WIDTH=100%>
<TR><TD WIDTH=8%>1.0 <TD><A HREF="#overview"> Overview </A>
<TR><TD>2.0 <TD><A HREF="#outstanding"> Outstanding issues </A>
<TR><TD>3.0 <TD><A HREF="#technical"> Technical background </A>
<TR><TD>4.0 <TD><A HREF="#user"> User interface </A>
<TR><TD>5.0 <TD><A HREF="#programmer"> Programmer interface </A>
<TR><TD>6.0 <TD><A HREF="#acceptance"> Acceptance test </A>
<TR><TD>7.0 <TD><A HREF="#test"> Development test strategy </A>
<TR><TD>8.0 <TD><A HREF="#organisation"> Product organisation </A>
<TR><TD>9.0 <TD><A HREF="#enhancements"> Future enhancements </A>
<TR><TD>10.0 <TD><A HREF="#glossary"> Glossary </A>
<TR><TD>11.0 <TD><A HREF="#references"> References </A>
<TR><TD>12.0 <TD><A HREF="#history"> History </A>
</TABLE>
<HR>
<H2> <A NAME="overview"> 1.0 Overview </A> </H2>
On a Network Computer the two serial ports supported by the SuperIO device have their interrupts wired-ORed together to form a shared interrupt. To support this change in interrupt architecture changes were required to the RiscOS serial device drivers. This resulted in a completely different machanism for handling serial type devices and passing data to and from them.
<p>
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.
<HR>
<H2> <A NAME="outstanding"> 2.0 Outstanding issues </A> </H2>
<ul>
<li> Acorn to establish device registration procedure.
<li> Acorn to establish <code>IOCtl</code> allocation procedure.
</ul>
<HR>
<H2> <A NAME="technical"> 3.0 Technical background </A> </H2>
<h3> <a name="ioctlsupport"> 3.1 IOCtl support </a> </h3>
The modules FileSwitch and DeviceFS now support IOCtl's. 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.
<h4> <a name="fileswitch" > 3.1.1 FileSwitch (2.36)</a> </h4>
A new <code>OS_Arg</code> reason code has been allocated <code>OSArgs_IOCtl</code> this has the following arguments.
<pre>
On entry
r0 = 9 (reason code)
r1 = file handle
r2 -&gt; ioctl parameter block
On exit
r0 preserved
r1 preserved
r2 preserved
</pre>
A new bit has been allocated in the extra filing system information word (PRM 2-523) as follows
<pre>
Bit Meaning if set
3 Filing system supports <code>OS_Arg IOCtl</code>.
</pre>
Filing systems should set this bit if they intend to support <code>OS_Arg IOCtl</code>. Existing filing systems will have this bit clear so will never be asked to handle this call.
<p>
If the registered filing system supports the <code>IOCtl OS_Arg</code> 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.
<h4> <a name="devicefs"> 3.1.2 DeviceFS (0.34)</a> </h4>
DeviceFS now sets the bit in the extra filing system information word to indicate that it wants to handle <code>OS_Arg IOCtl</code>.
<p>
A new <code>DeviceFS_CallDevice</code> reason code has been allocated <code>DeviceCall_IOCtl</code> this has the following arguments when received.
<pre>
DeviceDriver_Entry 14
IOCtl
On entry
r0 = 14 (reason code)
r1 = file handle
r2 = stream handle
r3 -&gt; ioctl parameter block as passed in r2 of OS_Args call
On exit
r0 preserved
r1 preserved
r2 preserved
r3 preserved
</pre>
This call is dispatched to the underlying device driver whenever the <code>OS_Arg IOCtl</code> swi is called or the swi <code>DeviceFS_CallDevice (14)</code> is called.
<h4> <a name="convention"> 3.1.3 Calling convention </a> </h4>
The following calling convention should be adopted when using this ioctl interface. Fields have been taken from the unix ioctl implementation as shown below.
<pre>
On entry
r2 -&gt; ioctl parameter block
On exit
r2 preserved
</pre>
where ioctl control block is a pointer to the following structure
<pre>
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;
</pre>
In the case of an <code>ioctl</code> called with both read and write flags set, the returned value will be the new or latest value of the parameter being accessed.
<HR>
<H2> <A NAME="user"> 4.0 User interface </A> </H2>
None provided.
<HR>
<H2> <A NAME="programmer"> 5.0 Programmer interface </A> </H2>
<h3> <a name="introduction"> 5.1 Introduction </a> </h3>
A consistant interface is provided to the two internal serial ports. The API for configuration of these ports is documented in sections below.
<p>
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 <code>ioctls</code> as documented below.
<p>
Input and/or output to DeviceFS streams should be made on the file path : <code>devices:$.&lt;stream name&gt;</code>
<p>
DeviceFS also establishes an environment variable to allow simpler access to this path. This would be constructed as : <code>&lt;stream name&gt;:</code>
<h3> <a name="ports"> 5.2 Ports </a> </h3>
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 <code>devices:$</code>. The following streams are present for NC hardware.
<ul>
<li> <code>serial1</code> - serial port 1 on the combo chip
<li> <code>serial2</code> - serial port 2 on the combo chip (IrDa capable depending upon device)
</ul>
<p>
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 <code>serial3:</code>, <code>modem1:</code>.
<h3> <a name="configuration"> 5.3 Configuration </a> </h3>
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 :
<blockquote> <pre>
devices#&lt;configuration options&gt;:$.serial1
</pre> </blockquote>
Where <code>&lt;configuration options&gt;</code> 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.
<ol>
<li> <code>baud&lt;n&gt;</code> - baud rate in bps
<li> <code>data&lt;n&gt;</code> - data length in bits
<li> <code>stop&lt;n&gt;</code> - number of start/stop bits
<li> <code>[noparity|even|odd]</code> - type of parity required
<li> <code>[nohandshake|rts|xon|dtr]</code> - type of handshaking required
<li> <code>size&lt;n&gt;</code> - size of buffer
<li> <code>thres&lt;n&gt;</code> - buffer threshold point
</ol>
For example '<code>#baud19200;data8;stop1;noparity;rts;size1024;thres32</code>'. 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.
<p>
If any of the parameters are invalid, for example baud rate not supported, the request to open the stream is refused.
<h3> <a name="ioctlconfig"> 5.4 IOCtl configuration </a> </h3>
Direct control of the serial port control lines can be achieved using the <a href="#ioctlsupport">IOCtl interface</a> described above. This will have the following reason codes.
<ol>
<li> set/read baud rate :
<ul>
<li> 50, 75, 110, 150, 300, 600, 1200, 1800, 2400, 3600, 4800, 7200, 9600, 19200, 38400, 56000 or 115200
</ul>
<p>
<li> set/read data format :
<ul>
<li> bits 0-7 : data length (5,6,7 or 8)
<li> bits 8-15 : number of start/stop bits (1 or 2)
<li> bits 16-23 : parity encoded as
<ul>
<li> 0 - no parity
<li> 1 - even parity
<li> 2 - odd parity
</ul>
<li> bits 24-31 : reserved (should be 0)
</ul>
<p>
<li> set/read handshaking :
<ul>
<li> 0 - no handshake
<li> 1 - rts/cts handshaking
<li> 2 - xon/xoff handshaking
<li> 3 - dtr/dsr handshaking
</ul>
<p>
<li> set/read buffer size :
<ul>
<li> 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.
</ul>
<p>
<li> set/read rx/tx buffer threshold point :
<ul>
<li> rx buffer, sets the point at which handshaking will be invoked.
<li> tx buffer, sets the point at which <a href="#async">upcall notification</a> is sent to higher level modules/applications to indicate tx space available.
</ul>
<p>
<li> set/read control lines :
<ul>
<li> bits 0-15 read/writable bits
<ul>
<li> bit 0 : DTR (1 = /DTR active, i.e. low)
<li> bit 1 : RTS (1 = /RTS active, i.e. low)
</ul>
<li> bits 16-31 read only flags
<ul>
<li> bit 16 : CTS (1 = /CTS active, i.e. low)
<li> bit 17 : DSR (1 = /DSR active, i.e. low)
<li> bit 18 : RI (1 = /RI active, i.e. low)
<li> bit 19 : DCD (1 = /DCD active, i.e. low)
<li> bit 20 : fifos enabled
</ul>
</ul>
<p>
<li> set/read fifo trigger level :
<ul>
<li> 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.
</ul>
<p>
<li> read number of supported baud rates :
<ul>
<li> 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.
</ul>
<p>
<li> read baud rate associated with index &lt;n&gt; :
<ul>
<li> This will return the baud rate associated with index &lt;n&gt;. &lt;n&gt; is an index between 0 and number of supported baud rates-1.
</ul>
<li> flush buffer :
<ul>
<li> write will flush contents of current buffer.
<li> read will return an undefined value.
</ul>
</ol>
<h3> <a name="datatransfer"> 5.5 Data transfer </a> </h3>
Once the DeviceFS stream has been chosen, data input/output is carried out using standard file access on the stream path name. For example :
<ul>
<li> <code>type devices:$.serial1</code> - echo's to the screen any characters received on serial port 1.
<li> <code>copy &lt;filename&gt; devices:$.serial1</code> - copies the data in file <code>&lt;filename&gt;</code> to serial port 1.
<li> swi interface
<ul>
<li> <code>OS_Find</code> to open a stream for tx/rx
<li> <code>OS_GBPB 2,4</code> to perform block read/writes from/to the stream
<li> <code>OS_BPut</code> to transmit a character
<li> <code>OS_BGet</code> to fetch a character
<li> <code>OS_Args 2</code> to obtain the amount of data in rx stream buffer and amount of free space in tx stream buffer
</ul>
</ul>
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.
<p>
To obtain the functionality of swi <code>OS_Args 2</code> 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.
<p>
It should also be noted that the behaviour of DeviceFS means that the functions to read data from an input stream are blocking. <code>OS_Args 2</code> should therefore be used to check the amount of data present in an input stream before a read is requested.
<h3> <a name="async"> 5.6 Asynchronous notification </a> </h3>
<h4> 5.6.1 Data present </h4>
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.
<pre>
On entry
r0 = 15 (upcall code Upcall_DeviceRxDataPresent)
r1 = stream handle
</pre>
<h4> 5.6.2 Threshold above </h4>
An upcall is dispatched whenever the amount of data in a stream exceeds the threshold value.
<pre>
On entry
r0 = 16 (upcall code UpCall_DeviceThresAbove)
r1 = stream handle
</pre>
<h4> 5.6.3 Threshold below </h4>
An upcall is dispatched whenever the amount of data in a stream falls below the threshold value.
<pre>
On entry
r0 = 17 (upcall code UpCall_DeviceThresBelow)
r1 = stream handle
</pre>
<h4> 5.6.4 Serial errors and line status changes </h4>
An event is generated whenever DSR or DCD change or when a line error (parity, framing, overrun) occurs.
<pre>
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
</pre>
<HR>
<H2> <A NAME="acceptance"> 6.0 Acceptance test </A> </H2>
<HR>
<H2> <a NAME="test"> 7.0 Development test strategy </A> </H2>
<HR>
<H2> <A NAME="organisation"> 8.0 Product organisation </A> </H2>
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.
<HR>
<H2> <A NAME="enhancements"> 9.0 Future enhancements </A> </H2>
<HR>
<H2> <A NAME="glossary"> 10.0 Glossary </A> </H2>
<HR>
<H2> <A NAME="references"> 11.0 References </A> </H2>
<HR>
<H2> <A NAME="history"> 12.0 History </A> </H2>
<TABLE BORDER=0 WIDTH=100%>
<TR><TD WIDTH=10%><B>Revision</B> <TD WIDTH=10%><B>Who</B> <TD WIDTH=15%><B>Date</B> <TD WIDTH=65%><B>Comment</B>
<TR><TD>0.01 <TD>RWB <TD>22 Jan 1997 <TD> Created based on Acorn internal documentation.
<tr><td>0.02 <td>RWB <td>30 Jan 1997 <td> Reformatted.
<tr><td>0.03 <td>RWB <td>17 Jun 1997 <td> Added IOCtl 10 for flushing buffers
</TABLE>
<HR>
<TABLE BORDER=1 WIDTH=100%>
<TR>
<TD WIDTH=50% VALIGN=TOP>
<SMALL>
This document must not be copied, reproduced or disclosed in part or whole.
</SMALL>
<TD WIDTH=50% VALIGN=TOP>
<SMALL>
by Acorn Network Computing, UK.<BR>
&copy; Acorn Computers Ltd 1997<BR>
</SMALL>
</TABLE>
</BODY>
</HTML>
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment