home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 2 / AUCD2.iso / internet / acornet.spk / !Acornet / Resources / !SerialDev / BlockSpec < prev    next >
Text File  |  1995-09-03  |  18KB  |  531 lines
  1. Block Driver Specification
  2. --------------------------
  3.  
  4. Hugo Fiennes, Rev 11, 7th July 1995
  5.  
  6. Contact me on 01749 670058 (altman@cryton.demon.co.uk, fidonet#2:255/102.0)
  7. for information about the latest version of the spec.
  8.  
  9. Aim
  10. ---
  11.  
  12. To provide a standard way for applications to access serial devices. Any
  13. application supporting block drivers can be used with many serial devices, with
  14. no modification required to the application code - and it's easier to use than
  15. the serial SWIs anyway!
  16.  
  17. Info
  18. ----
  19.  
  20. This standard is public domain. The drivers supplied are freely distributed
  21. by  1994/1995 Hugo Fiennes of The Serial Port.  If you intend to use the block
  22. drivers, please distribute the whole block driver package (inc sample source,
  23. this file, and the complete !SerialDev application) with your program, making
  24. sure that you are distributing the latest version (available from The World of
  25. Cryton BBS, Arcade BBS, and ftp.demon.co.uk in the /pub/archimedes directory).
  26.  
  27. An application called !SerialDev holds the drivers - in your application !Run
  28. sequence you should check to see if <SerialDev$Path> is set, and if not, set it
  29. to your application directory, inside which is Modules.Internal at least, for
  30. your application to default to the internal port.
  31.  
  32. Eventually the idea is to have !SerialDev hold an application that handles the
  33. installation in a 'pretty way' - eg dragging new drivers to a window to install
  34. them, this would check to see if the driver was a later version of an existing
  35. driver and if so replace the old one, otherwise it would install the driver.
  36. Maybe this application could look a bit like ArtWorks !FontInst. Hint, hint,
  37. somebody write one...
  38.  
  39. The drivers each have their own directory just in case, possibly extensions
  40. with !Run files, modules, etc relating to the driver could be stored there.
  41. Of course, drivers know their own name and could load files into RMA on
  42. initialisation now and cause no problems.
  43.  
  44. ARCterm 7 1.44 and later use drivers of this specification. In this archive I
  45. have included some other drivers, documented below. Other programs that support
  46. block drivers are: Binkleyterm (2.11+), Hearsay 2 (2.17+), ARCfax (1.06+),
  47. ARCbbs (1.63+), RISCbbs (1.02+), Netway.
  48.  
  49. C headers have been provided for C programmers. BASIC/Assembler people should
  50. have no problems working it out either - a small application, 'Example' is
  51. provided which will work with any block driver module to provide a very simple
  52. terminal program.
  53.  
  54. REVISION 4 : Added 'wont empty' and 'dont overlay io' flags for pipes and
  55.              (unfixed) RO3.10 serial ports.
  56.  
  57. REVISION 5 : Initialise can now return an error string.
  58.  
  59. REVISION 6 : More information on calling initialise.
  60.  
  61. REVISION 7 : Pipe drivers now support 'peek byte' - return next byte in buffer
  62.              without removing it.
  63.  
  64. REVISION 8 : Internal port with PC cable now works with DCD low (bit 1 on
  65.              SerialOp 0 now set). OSBYTE 152 used for peek byte (for some
  66.              reason the proper legal method doesn't work well).
  67.  
  68. REVISION 9 : All drivers must now store R14 on the stack so they can be called
  69.              from supervisor mode.
  70.  
  71. REVISION 10: Basically this release just tidied the internal driver for RiscPC
  72.              use - hitting the metal isn't required anymore to set high rates,
  73.              so it isn't done. Still needed on A5000, A3010, A3020, A4000 & A4
  74.              though.
  75.  
  76.              Inquiry initialise (see below) added for JP :-) This is
  77.              implemented in Internal, SP_Dual and Pipe drivers. It's only
  78.              really necessary in the Internal (sets baud tables) and the
  79.              SP_Dual (counts installed ports) drivers.
  80.  
  81. REVISION 10a:"I must not release software without testing it" :-)
  82.              A little buglet in the SP_Dual drivers was pointed out to me,
  83.              "they don't work!". This has now been fixed. Drivers should now
  84.              also preserve the PSR (Internal, Dummy, Pipe, and SP_Dual do)
  85.              just in case.
  86.  
  87. REVISION 11: Internal drivers:
  88.                Supervisor mode fixes by Tom Hughes (for Freenet to work!)
  89.                incorporated in this release.
  90.  
  91.                Mod to flow control threshold setting suggested by Andrew
  92.                Sellors implemented.
  93.  
  94.              SP_Dual drivers:
  95.                Inquiry initialise will now return error if no card installed.
  96.  
  97.                Workaround for bug in DS firmware when block ops want to
  98.                transfer 0 bytes implemented. [James Miller]
  99.  
  100.  
  101. Internal driver
  102. ---------------
  103.  
  104. There are two version of this: Internal and InternalPC - the PC version
  105. expects a standard PC serial cable, which will only work properly on A5000
  106. or later machines (some early A5000s might have problems too).
  107.  
  108. Needs RO3.1 for block operations.
  109.  
  110. On a 'new hardware' machine (ie A5000 or later) will support 38400, 57600,
  111. 115200 automatically. Remember that these rates may well not be reliable
  112. due to the lack of FIFO on the serial chip. These rates are achieved by
  113. writing directly to the serial chip, which is definitely not Acorn-approved.
  114. Beware!
  115.  
  116. On RiscPCs all rates to 115200 should be perfectly reliable as the hardware
  117. now includes a FIFO.
  118.  
  119. Cables - the Acorn wiring for a modem is this:
  120.  
  121.    Acorn 9w female               Modem 25w male
  122.    ---------------               --------------
  123.        1-4-8                           20
  124.          2                              3
  125.          3                              2
  126.          5                              7
  127.          6                              5
  128.          7                              4
  129.          9                              8
  130.  
  131. And the PC wiring is this:
  132.  
  133.    Acorn 9w female               Modem 25w male
  134.    ---------------               --------------
  135.          1                              8
  136.          2                              3
  137.          3                              2
  138.          4                             20
  139.          5                              7
  140.          6                              6 (not usually used much)
  141.          7                              4
  142.          8                              5
  143.          9                             22 (not usually used much)
  144.  
  145. Serial Port Dual Serial
  146. -----------------------
  147.  
  148. Again, there are 2 versions: SP_Dual and SP_DualPC, the PC version expects
  149. a standard PC serial cable.
  150.  
  151. Since release 9, the Xon/Xoff flags are cleared every time flow control
  152. is changed to stop things sticking if an Xoff has been received.
  153.  
  154. PipeA and PipeB
  155. ---------------
  156.  
  157. This will autoload the ARCbbs_Pipes module (contained in the PipeA directory)
  158. if necessary.
  159.  
  160. The idea is, you open a port (0-15) on pipeA and data sent appears in the
  161. input of the corresponding port on pipeB (and vice-versa). DTR at one end
  162. is translated to DCD at the other (ditto for RTS-CTS). In this way, any
  163. application which supports the block driver spec can talk to another, for
  164. example, with ARCbbs and the ARCterm modem server on the same machine,
  165. some ARCbbs ports could be given over to network access via the modem
  166. server.
  167.  
  168. The pipes use the flag 'wont empty' as you can't wait for the pipe to
  169. 'finish sending' as the other end of the pipe may be waiting for the same
  170. thing (unlike a serial port, where the data will go away eventually).
  171.  
  172. The pipes are 2k long in each direction.
  173.  
  174. Acorn Telnet (Needs Acorn's TCP/IP protocol suite)
  175. ------------
  176. *Note! Does not store R14_SVC
  177.  
  178. This is only in testing, but is supplied as it might be useful. The coding
  179. is possibly quite inefficient, but it works. You require !Internet and 
  180. !Telnet to have been run before trying to use the driver. It will prompt
  181. for a host name - type one, or an internet address. You can add ',xx'
  182. where xx is the port number to telnet into. DCD as reported by modem
  183. status will go high when a successful connection is made. Dropping DTR
  184. then raising it again will clear any current call.
  185.  
  186. Known bugs: You can't have multiple sessions - if you load another emulator
  187. and run telnet the port_claim message will stop the first one - possibly a
  188. 'dynamic' port number (returned by init?) should be put into the spec to
  189. cater for things like this.
  190.  
  191.  
  192. Dummy (/dev/null)
  193. -----
  194.  
  195. This is a dummy driver, for when you want somewhere to trash data. It
  196. always shows CTS, DSR and DCD, and will completely ignore any data you
  197. send to it. It never has any data to give you.
  198.  
  199. II_Dual driver
  200. --------------
  201. *Note! Does not store R14_SVC
  202.  
  203. This is a temporary stop-gap until v3.xx software is available for the II
  204. card. The port number you specify is the II port number -1, ie II port 3
  205. would be specified as port 2. If you want to use the internal port while
  206. using II ports, you need the Internal2 driver. Both of these drivers
  207. rely on the poll entry being called directly after each wimp poll, to set
  208. the current port.
  209.  
  210. II_DualPC driver
  211. --------------
  212.  
  213. This uses IIDual v3.xx software. The port number you specify is the II port
  214. number -1, ie II port 2 would be specified as port 1. This version expects
  215. a standard PC serial cable.
  216.  
  217. Econet driver (not supplied with this release)
  218. -------------
  219.  
  220. This works with ARCterm's new 16-line modem server to allow remote serial
  221. access. To support connection, etc, it has 3 special functions:
  222.  
  223. Connect (function code 128)
  224.   r1=handle/net/station (handle in bits 16-23,net in bits 8-15, station in 0-7)
  225.   r2-> password, null terminated
  226.  
  227.   Tries to set up a connection with the modem server. Returns 0 for success,
  228.   1 for no reply, 2 for already connected, or a pointer to an error block if
  229.   r0 is 'big' on return.
  230.  
  231. Disconnect (function code 129)
  232.   Disconnects from the modem server.
  233.  
  234. Scan for modem servers (function code 130)
  235.   r1=buffer to fill of format:
  236.      0    station
  237.      1    net
  238.      2    handle
  239.      3    modem driver number as defined in the modem server config file
  240.      4-63 modem ID string (null terminated)
  241.   r2=max number of entries table can handle
  242.  
  243. -------------------------------------------------------------------------------
  244. Driver layout
  245. -------------------------------------------------------------------------------
  246.  
  247. 0x000 Entry point to call routines
  248.  
  249.       In:  r0=function code
  250.            r1-r3=data
  251.  
  252.       Out: r0=result
  253.  
  254.       NOTE! CHANGE IN REVISION 9!
  255.       |
  256.       | This entry point can be called in EITHER user or supervisor mode, so
  257.       | R14 should always be pushed on the stack (STMFD R13!,{R14}) and be used
  258.       | to return from the driver so that r14_svc is preserved if the driver is
  259.       | called when in supervisor mode.
  260.       |
  261.  
  262.       r0-r3 can be corrupted, r4-r12 should be preserved. r14 contains the
  263.       return address
  264.  
  265.       Callers note that r13 should point to a full, descending stack
  266.       with a decent amount of space free on it.
  267.  
  268.       Example handler code follows:
  269.  
  270.       entry
  271.             STMFD R13!,{R14}
  272.             CMP   R0,#((endoftable-table)/4)
  273.             ADDCC PC,PC,R0,LSL#2
  274.             LDMFD R13!,{PC}
  275.  
  276.       table
  277.             B     func_0
  278.             B     func_1
  279.       endtable
  280.  
  281. 0x080 Driver information string (31 bytes max, 0 terminated)
  282. 0x0A0 Manufacturer information string (31 bytes max, 0 terminated)
  283. 0x0C0 Version number (top 16 bits major, low 16 bits minor)
  284. 0x0C4 Driver flags
  285.  
  286.       0x00000001 - More than one port available
  287.       0x00000002 - Supports split rates
  288.       0x00000004 - Has >1 byte hardware FIFO
  289.       0x00000008 - Can use Set control lines to generate a break
  290.       0x00000010 - Requires polling (by function 19)
  291.       0x00000020 - Won't empty (is a shared buffer)
  292.       0x00000040 - Supports block get/put operations
  293.       0x00000080 - Prefer not to overlap serial IO and disk IO
  294.       0x00000100 - Supports inquiry initialise
  295.  
  296.       0xdd...... - Top byte is highest port number supported (numbered from 0)
  297.       
  298. 0x0C8 Driver number. This is allocated by me, and always has the lowest byte
  299.       as 0. The purpose of the driver number is for the Device_Claim protocol:
  300.       when a serial port is specified, the port number is used to specify
  301.       which port is to be claimed/released. The internal port is port 0 and
  302.       driver number 0. To make the port number to use you add the sub-port
  303.       number and the driver number together. eg, say the II dual card was
  304.       driver number 1 (0x00000100) and you wanted to claim port 5, you
  305.       would use the port number 0x00000105. This is unique and hopefully
  306.       would cause no problems.
  307.  
  308.       PORT NUMBERS PASSED TO BLOCK DRIVERS ARE THE LOWER 8 BITS ONLY: THEY DO
  309.       NOT INCLUDE THE DRIVER NUMBER.
  310.  
  311.       Currently allocated driver numbers:
  312.  
  313.         0 - Internal serial
  314.         1 - II dual serial
  315.         2 - Serial port dual serial
  316.         3 - Internal serial with PC cable
  317.         4 - Brainsoft Multipod (Kelvin Hill, #179 on Cryton)
  318.         5 - Acorn telnet interface
  319.         6 - Serial port dual serial with PC cable
  320.         7 - II dual serial with PC cable
  321.  
  322.       100 - Remote econet driver
  323.       128 - Virtual pipe (end A)
  324.       129 - Virtual pipe (end B)
  325.  
  326. 0x0CC - 0x0FF reserved
  327.  
  328. 0x100 Supported speed table. One word per speed, terminated with a null word.
  329.  
  330. 0x180-> driver code.
  331.  
  332.  
  333. Function codes - Summary
  334. ------------------------
  335. r0=0    Put byte
  336. r0=1    Get byte
  337. r0=2    Put block
  338. r0=3    Get block
  339. r0=4    Check TX buffer
  340. r0=5    Check RX buffer
  341. r0=6    Flush TX buffer (and hardware FIFO if applicable)
  342. r0=7    Flush RX buffer (and hardware FIFO if applicable)
  343. r0=8    Control lines  R/W
  344. r0=9    Read modem control lines
  345. r0=10   Read RX errors
  346. r0=11   Send break
  347. r0=12   Examine byte (like Get byte but leaves it in the buffer)
  348. r0=13   TX Speed  R/W
  349. r0=14   RX Speed  R/W
  350. r0=15   Set word format   R/W
  351. r0=16   Set flow control  R/W
  352. r0=17   Initialise driver
  353. r0=18   Close down driver
  354. r0=19   Poll driver
  355.  
  356.  
  357.  
  358. Function codes - Description
  359. ----------------------------
  360.  
  361. r0=0  Put byte
  362.       --------
  363.       r1=port number
  364.       r2=byte to send
  365.  
  366.       Returns with r0=-1 if byte not inserted, r0=0 if byte inserted into
  367.       TX queue.
  368.  
  369. r0=1  Get byte
  370.       --------
  371.       r1=port number
  372.  
  373.       Returns with r0=-1 if no byte available, r0=byte if a byte was removed.
  374.  
  375. r0=2  Put block
  376.       ---------
  377.       r1=port number
  378.       r2=pointer to block
  379.       r3=number of bytes to try and insert
  380.  
  381.       Returns with r0=number of bytes successfully inserted.
  382.  
  383. r0=3  Get block
  384.       ---------
  385.       r1=port number
  386.       r2=pointer to block
  387.       r3=maximum number of bytes to put into buffer
  388.  
  389.       Returns with r0=number of bytes put in buffer.
  390.  
  391. r0=4  Check TX buffer
  392.       ---------------
  393.       r1=port number
  394.  
  395.       Returns with r0=number of bytes free in TX buffer
  396.  
  397. r0=5  Check RX buffer
  398.       ---------------
  399.       r1=port number
  400.  
  401.       Returns with r0=number of bytes used in RX buffer
  402.  
  403. r0=6  Flush TX buffer (and hardware FIFO if applicable)
  404.       ---------------
  405.       r1=port number
  406.  
  407. r0=7  Flush RX buffer (and hardware FIFO if applicable)
  408.       ---------------
  409.       r1=port number
  410.  
  411. r0=8  Control lines  R/W
  412.       ------------------
  413.       r1=port number
  414.       r2=-1 to read or new settings
  415.  
  416.       Returns r0=control line settings
  417.  
  418.       b0=DTR
  419.       b1=RTS
  420.       b2=If set, set TX data active (ie break state)
  421.  
  422. r0=9  Read modem control lines
  423.       ------------------------
  424.       r1=port number
  425.  
  426.       Returns r0=control line status
  427.  
  428.       b0=CTS
  429.       b1=DSR
  430.       b2=RI
  431.       b3=DCD
  432.  
  433. r0=10 Read RX errors
  434.       --------------
  435.       r1=port number
  436.  
  437.       Returns r0=bitset of errors seen since last read RX errors.
  438.  
  439.       b0=Overrun error
  440.       b1=Parity error
  441.       b2=Framing error
  442.       b3=Break received
  443.  
  444. r0=11 Send break
  445.       ----------
  446.       r1=port number
  447.       r2=break time (in centiseconds)
  448.  
  449.       This does not return until the break has been sent - although some
  450.       serial ports could multitask when sending a break, the internal port
  451.       can't. Check the driver flags to see if you can use a multitasking
  452.       break before using this call.
  453.  
  454. r0=12 Examine byte (like Get byte but leaves it in the buffer)
  455.       ------------
  456.       r1=port number
  457.  
  458.       Returns with r0=-1 if no byte available, r0=byte if a byte was
  459.       returned.
  460.  
  461. r0=13 TX Speed R/W
  462.       ------------
  463.       r1=port number
  464.       r2=speed to set or -1 to read
  465.  
  466.       Returns with r0=speed.
  467.  
  468. r0=14 RX Speed R/W
  469.       ------------
  470.       r1=port number
  471.       r2=speed to set or -1 to read
  472.  
  473.       Returns with r0=speed.
  474.  
  475. r0=15 Set word format R/W
  476.       -------------------
  477.       r1=port number
  478.       r2=word format to set or -1 to read
  479.  
  480.       Returns with r0=word format.
  481.  
  482. r0=16 Set flow control R/W
  483.       --------------------
  484.       r1=port number
  485.       r2=flow control method to set or -1 to read
  486.  
  487.       Returns with r0=method
  488.  
  489.       0=no flow control
  490.       1=hardware
  491.       2=xon/xoff
  492.       3=both
  493.  
  494. r0=17 Initialise driver
  495.       -----------------
  496.       r1=port number
  497.       r2=parameter string (optional)
  498.  
  499.       r2 optionally points to a null terminated string which can specify
  500.       device options.
  501.  
  502.       Returns with r0 pointing to error string if
  503.       initialisation unsuccessful, otherwise r0=0.
  504.  
  505.       NOTE! Do not read the baud rate tables or driver flags UNTIL AFTER
  506.       the initialise driver entry has been called. This allows for drivers
  507.       to configure themselves to the available hardware and adjust the
  508.       services offered accordingly.
  509.  
  510.       Release 10: There is now a flag, 'supports inquiry initialise' (see
  511.       above) which allows you to call the initialise entry with r1=-1,
  512.       which will not touch any hardware, just set all the baud tables,
  513.       driver flags, and count the number of ports installed (if necessary),
  514.       so you can read them and set up menus, etc.
  515.  
  516. r0=18 Close down driver
  517.       -----------------
  518.       r1=port number
  519.  
  520. r0=19 Poll driver
  521.       -----------
  522.       r1=port number
  523.  
  524.       This should be called regularly (eg in a polling loop) for the driver
  525.       to perform polling tasks - eg the econet driver needs to check internal
  526.       buffers and poll econet protocol tasks. Polls can be as infrequent as
  527.       three or four times a second : if a driver needs polling more often
  528.       than that, it should install a module and hook onto a vector somewhere.
  529.  
  530.  
  531.