home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Datafile PD-CD 5
/
DATAFILE_PDCD5.iso
/
utilities
/
m
/
modemdial
/
!ModemDial
/
SerialDev
/
BlockSpec
next >
Wrap
Text File
|
1996-06-11
|
19KB
|
537 lines
Block Driver Specification Hugo Fiennes, Rev 12, 11th June 1996
-------------------------------------------------------------------------------
Contact me as 'altman@cryton.demon.co.uk', for information about the latest
version of the spec.
ARCterm 7 users - please see the notes on release 12 at the end of this
document before installing the drivers.
Aim
-------------------------------------------------------------------------------
To provide a standard way for applications to access serial devices. Any
application supporting block drivers can be used with many serial devices, with
no modification required to the application code - and it's easier to use than
the serial SWIs anyway!
Info
-------------------------------------------------------------------------------
This standard is public domain - the drivers supplied are freely distributable.
If you intend to use the block drivers, please distribute the whole block
driver package (inc sample source, this file, and the complete !SerialDev
application) with your program, making sure that you are distributing the
latest version (available from ftp.demon.co.uk in the /pub/archimedes
directory).
An application called !SerialDev holds the drivers - in your application !Run
sequence you should check to see if <SerialDev$Path> is set, and if not, set it
to your application directory, inside which is Modules.Internal at least, for
your application to default to the internal port.
Eventually the idea is to have !SerialDev hold an application that handles the
installation in a 'pretty way' - eg dragging new drivers to a window to install
them, this would check to see if the driver was a later version of an existing
driver and if so replace the old one, otherwise it would install the driver.
Maybe this application could look a bit like ArtWorks !FontInst. Hint, hint,
somebody write one...
The drivers each have their own directory just in case, possibly extensions
with !Run files, modules, etc relating to the driver could be stored there.
Of course, drivers know their own name and could load files into RMA on
initialisation now and cause no problems.
ARCterm 7 1.44 and later use drivers of this specification. In this archive I
have included some other drivers, documented below. Other programs that support
block drivers are: Binkleyterm (2.11+), Hearsay 2 (2.17+), ARCfax (1.06+),
ARCbbs (1.63+), RISCbbs (1.02+), Netway, KA9Q/!TCPIP, Freenet, Acorn's PPP.
Calling drivers
-------------------------------------------------------------------------------
The drivers can be called in USR or SVC mode, and will use/corrupt r0-r3.
All functions that return data do so in R0 for compatibility with C programs.
Parameters to all functions go in via r0-r3.
The functions are called simply by branching to the start of the driver that
has been loaded with the registers set up and a return address (in R14) set
up correctly (remember - if you're calling from SVC mode, R14 must also
include the correct CPU mode).
The first function that should be called after loading a driver (before even
reading baudrate tables) is the initialise entry, which may fix up tables
and other data depending on hardware capabilities.
An example program in BASIC and C is provided with the distribution for you to
look at.
Function codes - Summary
------------------------
r0=0 Put byte
r0=1 Get byte
r0=2 Put block
r0=3 Get block
r0=4 Check TX buffer
r0=5 Check RX buffer
r0=6 Flush TX buffer (and hardware FIFO if applicable)
r0=7 Flush RX buffer (and hardware FIFO if applicable)
r0=8 Control lines R/W
r0=9 Read modem control lines
r0=10 Read RX errors
r0=11 Send break
r0=12 Examine byte (like Get byte but leaves it in the buffer)
r0=13 TX Speed R/W
r0=14 RX Speed R/W
r0=15 Set word format R/W
r0=16 Set flow control R/W
r0=17 Initialise driver
r0=18 Close down driver
r0=19 Poll driver
Function codes - Description
----------------------------
r0=0 Put byte
--------
r1=port number
r2=byte to send
Returns with r0=-1 if byte not inserted, r0=0 if byte inserted into
TX queue.
r0=1 Get byte
--------
r1=port number
Returns with r0=-1 if no byte available, r0=byte if a byte was removed.
r0=2 Put block
---------
r1=port number
r2=pointer to block
r3=number of bytes to try and insert
Returns with r0=number of bytes successfully inserted.
r0=3 Get block
---------
r1=port number
r2=pointer to block
r3=maximum number of bytes to put into buffer
Returns with r0=number of bytes put in buffer.
r0=4 Check TX buffer
---------------
r1=port number
Returns with r0=number of bytes free in TX buffer
r0=5 Check RX buffer
---------------
r1=port number
Returns with r0=number of bytes used in RX buffer
r0=6 Flush TX buffer (and hardware FIFO if applicable)
---------------
r1=port number
r0=7 Flush RX buffer (and hardware FIFO if applicable)
---------------
r1=port number
r0=8 Control lines R/W
------------------
r1=port number
r2=-1 to read or new settings
Returns r0=control line settings
b0=DTR
b1=RTS
b2=If set, set TX data active (ie break state)
r0=9 Read modem control lines
------------------------
r1=port number
Returns r0=control line status
b0=CTS
b1=DSR
b2=RI
b3=DCD
r0=10 Read RX errors
--------------
r1=port number
Returns r0=bitset of errors seen since last read RX errors.
b0=Overrun error
b1=Parity error
b2=Framing error
b3=Break received
r0=11 Send break
----------
r1=port number
r2=break time (in centiseconds)
This does not return until the break has been sent - although some
serial ports could multitask when sending a break, the internal port
can't. Check the driver flags to see if you can use a multitasking
break before using this call.
r0=12 Examine byte (like Get byte but leaves it in the buffer)
------------
r1=port number
Returns with r0=-1 if no byte available, r0=byte if a byte was
returned.
r0=13 TX Speed R/W
------------
r1=port number
r2=speed to set or -1 to read
Returns with r0=speed.
r0=14 RX Speed R/W
------------
r1=port number
r2=speed to set or -1 to read
Returns with r0=speed.
r0=15 Set word format R/W
-------------------
r1=port number
r2=word format to set or -1 to read
Returns with r0=word format.
r0=16 Set flow control R/W
--------------------
r1=port number
r2=flow control method to set or -1 to read
Returns with r0=method
0=no flow control
1=hardware
2=xon/xoff
3=both
r0=17 Initialise driver
-----------------
r1=port number
r2=parameter string (optional)
r2 optionally points to a null terminated string which can specify
device options.
Returns with r0 pointing to error string if
initialisation unsuccessful, otherwise r0=0.
NOTE! Do not read the baud rate tables or driver flags UNTIL AFTER
the initialise driver entry has been called. This allows for drivers
to configure themselves to the available hardware and adjust the
services offered accordingly.
Release 10: There is now a flag, 'supports inquiry initialise' (see
above) which allows you to call the initialise entry with r1=-1,
which will not touch any hardware, just set all the baud tables,
driver flags, and count the number of ports installed (if necessary),
so you can read them and set up menus, etc.
r0=18 Close down driver
-----------------
r1=port number
r0=19 Poll driver
-----------
r1=port number
This should be called regularly (eg in a polling loop) for the driver
to perform polling tasks - eg the econet driver needs to check internal
buffers and poll econet protocol tasks. Polls can be as infrequent as
three or four t