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