home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / internet / netlite2 / DriverSpec / BlockSpec next >
Encoding:
Text File  |  1993-01-27  |  9.4 KB  |  314 lines
  1. Alternative Block Driver Specification
  2. --------------------------------------
  3.  
  4. Hugo Fiennes, Rev 4, 27th January 1993
  5.  
  6. Contact me on 0749 670058 (altman@cryton.demon.co.uk, fidonet 2:252/102.0)
  7. for information about the latest version of the spec.
  8.  
  9. An application called !SerialDev holds the drivers - in your application !Run
  10. sequence you should check to see if <SerialDev$Path> is set, and if not, set
  11. it to your application directory, inside which is Modules.Internal at least,
  12. for your application to default to the internal port.
  13.  
  14. Eventually the idea is to have !SerialDev hold an application that handles
  15. the intstallation in a 'pretty way' - eg dragging new drivers to a window to
  16. install them, this would check to see if the driver was a later version of an
  17. existing driver and if so replace the old one, otherwise it would install the
  18. driver. Maybe this application could look a bit like ArtWorks !FontInst.
  19. Hint, hint, somebody write one...
  20.  
  21. The drivers each have their own directory just in case, possibly extensions
  22. with !Run files, modules, etc relating to the driver could be stored there.
  23. Of course, drivers know their own name and could load files into RMA on
  24. initialisation now and cause no problems.
  25.  
  26. ARCterm 7 1.44 and later use drivers of this specification. In this
  27. archive I have included the (tested) internal serial port driver.
  28. I've also done a driver for the Serial Port dual serial card, but this
  29. will be released with the card itself.
  30.  
  31. Note that these drivers will probably need RO3.1, due to the use of the
  32. vectors which were more unpredictable under RO2.
  33.  
  34. C headers have been provided for C programmers. BASIC/Assembler people
  35. should have no problems working it out either.
  36.  
  37. REVISION 4 : Added 'wont empty' and 'dont overlay io' flags for pipes and
  38.              (unfixed) RO3.10 serial ports.
  39.  
  40. Internal driver (driver number=0)
  41. ---------------
  42.  
  43. Needs RO3.1 for block operations.
  44.  
  45. II_Dual driver (not supplied with this release)
  46. --------------
  47.  
  48. This has been coded, but only works with the (as yet unreleased) version 3.x
  49. module. A tested version will be released as soon as possible.
  50.  
  51. Serial Port Dual Serial (not supplied with this release)
  52. -----------------------
  53.  
  54. No known problems.
  55.  
  56. Econet driver (not supplied with this release)
  57. -------------
  58.  
  59. This works with ARCterm's modem server to allow remote serial access. To
  60. support connection, etc, it has 3 special functions:
  61.  
  62. Connect (function code 128)
  63.   r1=handle/net/station (handle in bits 16-23,net in bits 8-15, station in 0-7)
  64.   r2-> password, null terminated
  65.  
  66.   Tries to set up a connection with the modem server. Returns 0 for success,
  67.   1 for no reply, 2 for already connected, or a pointer to an error block if
  68.   r0 is 'big' on return.
  69.  
  70. Disconnect (function code 129)
  71.   Disconnects from the modem server.
  72.  
  73. Scan for modem servers (function code 130)
  74.   r1=buffer to fill of format:
  75.      0    station
  76.      1    net
  77.      2    handle
  78.      3    modem driver number as defined in the modem server config file
  79.      4-63 modem ID string (null terminated)
  80.   r2=max number of entries table can handle
  81.  
  82. PipeA and PipeB (not supplied with this release)
  83. ---------------
  84.  
  85. This works in conjunction with the ARCbbs pipe module currently - when I put
  86. RO3 in the BBS machine it will probably be modified to work with RO3's PipeFS.
  87. The idea is, you open a port (of 16) on pipeA and data sent appears in the
  88. input of the corresponding port on pipeB (and vice-versa). DTR at one end
  89. is translated to DCD at the other (ditto for RTS-CTS). In this way, any
  90. application which supports the block driver spec can talk to another, for
  91. example, with ARCbbs and the ARCterm modem server on the same machine,
  92. some ARCbbs ports could be given over to network access via the modem
  93. server.
  94.  
  95. The pipes use the flag 'wont empty' as you can't wait for the pipe to
  96. 'finish sending' as the other end of the pipe may be waiting for the same
  97. thing (unlike a serial port, where the data will go away eventually).
  98.  
  99. -------------------------------------------------------------------------------
  100. Driver layout
  101. -------------------------------------------------------------------------------
  102.  
  103. 0x000 Entry point to call routines
  104.  
  105.       In:  r0=function code
  106.            r1-r3=data
  107.  
  108.       Out: r0=result
  109.  
  110.       This entry point should only be called in user mode, so the driver
  111.       does not need to preserve r14_svc - this should be fine for the majority
  112.       of applications.
  113.  
  114.       r0-r3 can be corrupted, r4-r12 should be preserved. r14 contains the
  115.       return address
  116.  
  117.       Callers note that r13 should point to a full, descending stack
  118.       with a decent amount of space free on it.
  119.  
  120.       Example handler code follows:
  121.  
  122.       entry
  123.             CMP   R0,#((endoftable-table)/4)
  124.             ADDCC PC,PC,R0,LSL#2
  125.             MOV   PC,R14
  126.  
  127.       table
  128.             B     func_0
  129.             B     func_1
  130.       endtable
  131.  
  132. 0x080 Driver information string (31 bytes max, 0 terminated)
  133. 0x0A0 Manufacturer information string (31 bytes max, 0 terminated)
  134. 0x0C0 Version number (top 16 bits major, low 16 bits minor)
  135. 0x0C4 Driver flags
  136.  
  137.       0x00000001 - More than one port availiable
  138.       0x00000002 - Supports split rates
  139.       0x00000004 - Has >1 byte hardware FIFO
  140.       0x00000008 - Can use Set control lines to generate a break
  141.       0x00000010 - Requires polling (by function 19)
  142.       0x00000020 - Won't empty (is a shared buffer)
  143.       0x00000040 - Supports block get/put operations
  144.       0x00000080 - Prefer not to overlap serial IO and disk IO
  145.  
  146.       0xdd...... - Top byte is highest port number supported (numbered from 0)
  147. 0x0C8 Driver number. This is allocated by me, and always has the lowest byte
  148.       as 0. The purpose of the driver number is for the Device_Claim protocol:
  149.       when a serial port is specified, the port number is used to specify
  150.       which port is to be claimed/released. The internal port is port 0 and
  151.       driver number 0. To make the port number to use you add the sub-port
  152.       number and the driver number together. eg, say the II dual card was
  153.       driver number 1 (0x00000100) and you wanted to claim port 5, you
  154.       would use the port number 0x00000105. This is unique and hopefully
  155.       would cause no problems.
  156.  
  157. 0x0CC - 0x0FF reserved
  158.  
  159. 0x100 Supported speed table. One word per speed, terminated with a null word.
  160.  
  161. 0x180-> driver code.
  162.  
  163. Function codes
  164. --------------
  165.  
  166. r0=0  Put byte
  167.       --------
  168.       r1=port number
  169.       r2=byte to send
  170.  
  171.       Returns with r0=-1 if byte not inserted, r0=0 if byte inserted into
  172.       TX queue.
  173.  
  174. r0=1  Get byte
  175.       --------
  176.       r1=port number
  177.  
  178.       Returns with r0=-1 if no byte availiable, r0=byte if a byte was removed.
  179.  
  180. r0=2  Put block
  181.       ---------
  182.       r1=port number
  183.       r2=pointer to block
  184.       r3=number of bytes to try and insert
  185.  
  186.       Returns with r0=number of bytes sucessfully inserted.
  187.  
  188. r0=3  Get block
  189.       ---------
  190.       r1=port number
  191.       r2=pointer to block
  192.       r3=maximum number of bytes to put into buffer
  193.  
  194.       Returns with r0=number of bytes put in buffer.
  195.  
  196. r0=4  Check TX buffer
  197.       ---------------
  198.       r1=port number
  199.  
  200.       Returns with r0=number of bytes free in TX buffer
  201.  
  202. r0=5  Check RX buffer
  203.       ---------------
  204.       r1=port number
  205.  
  206.       Returns with r0=number of bytes used in RX buffer
  207.  
  208. r0=6  Flush TX buffer (and hardware FIFO if applicable)
  209.       ---------------
  210.       r1=port number
  211.  
  212. r0=7  Flush RX buffer (and hardware FIFO if applicable)
  213.       ---------------
  214.       r1=port number
  215.  
  216. r0=8  Control lines
  217.       -------------
  218.       r1=port number
  219.       r2=-1 to read or new settings
  220.  
  221.       Returns r0=control line settings
  222.  
  223.       b0=DTR
  224.       b1=RTS
  225.       b2=If set, set TX data active (ie break state)
  226.  
  227. r0=9  Read modem control lines
  228.       ------------------------
  229.       r1=port number
  230.  
  231.       Returns r0=control line status
  232.  
  233.       b0=CTS
  234.       b1=DSR
  235.       b2=RI
  236.       b3=DCD
  237.  
  238. r0=10 Read RX errors
  239.       --------------
  240.       r1=port number
  241.  
  242.       Returns r0=bitset of errors seen since last read RX errors.
  243.  
  244.       b0=Overrun error
  245.       b1=Parity error
  246.       b2=Framing error
  247.       b3=Break received
  248.  
  249. r0=11 Send break
  250.       ----------
  251.       r1=port number
  252.       r2=break time (in centiseconds)
  253.  
  254.       This does not return until the break has been sent - although some
  255.       serial ports could multitask when sending a break, the internal port
  256.       can't. Check the driver flags to see if you can use a multitasking
  257.       break before using this call.
  258.  
  259. r0=12 Examine byte (like Get byte but leaves it in the buffer)
  260.       ------------
  261.       r1=port number
  262.  
  263.       Returns with r0=-1 if no byte availiable, r0=byte if a byte was
  264.       returned.
  265.  
  266. r0=13 TX Speed
  267.       --------
  268.       r1=port number
  269.       r2=speed to set or -1 to read
  270.  
  271.       Returns with r0=speed.
  272.  
  273. r0=14 RX Speed
  274.       --------
  275.       r1=port number
  276.       r2=speed to set or -1 to read
  277.  
  278.       Returns with r0=speed.
  279.  
  280. r0=15 Set word format
  281.       ---------------
  282.       r1=port number
  283.       r2=word format to set or -1 to read
  284.  
  285.       Returns with r0=word format.
  286.  
  287. r0=16 Set flow control
  288.       ----------------
  289.       r1=port number
  290.       r2=flow control method to set or -1 to read
  291.  
  292.       Returns with r0=method
  293.  
  294.       0=no flow control
  295.       1=hardware
  296.       2=xon/xoff
  297.       3=both
  298.  
  299. r0=17 Initialise driver
  300.       -----------------
  301.       r1=port number
  302.  
  303. r0=18 Close down driver
  304.       -----------------
  305.       r1=port number
  306.  
  307. r0=19 Poll driver
  308.       -----------
  309.       r1=port number
  310.  
  311.       This should be called regularly (eg in a polling loop) for the driver
  312.       to perform polling tasks - eg the econet driver needs to check internal
  313.       buffers and poll econet protocol tasks.
  314.