home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / fido / gendrivr.zip / GENERIC.DOC < prev   
Text File  |  1986-01-29  |  9KB  |  253 lines
  1.  
  2.     GENERIC FIDO DRIVER INTERFACE
  3.     Updatewd 29 Jan 86
  4.     T. Jennings 12 July 1985
  5.  
  6.     FIDO_GEN.EXE is a "generic" Fido for otherwise unsupported
  7.     machines. It will not work until you write a device driver
  8.     or terminate-stay-resident program to provide the following
  9.     functions. The format of this driver will remain independent
  10.     of the Fido version; once written it will work with all
  11.     future Fido versions.
  12.  
  13.     All IO is done through an IBM PC like Interrupt 14 hex. Many
  14.     calls are directly compatible, but you will have to extend
  15.     it to support the added features. Note that FIDO_GEN will
  16.     NOT run on an IBM PC as is.
  17.  
  18.     The interface is very consistent; AX and DX are used for
  19.     all functions.
  20.  
  21.     It is possible to use an entirely polled IO system for
  22.     Fido; Fido does "typeahead" in the higher level software,
  23.     so everything but ASCII Upload will work fine polled, and
  24.     even that may work OK on most machines. Interrupt character
  25.     input is very desireable. Interrupt output is not needed
  26.     at all, unless you wish to run under a multi-tasker such
  27.     as Multilink.
  28.  
  29.     Please note that I cannot help you write drivers, nor will
  30.     I help you debug them. You are on your own! Extensive
  31.     assembly language experience is needed, and a good degree
  32.     of familiarity with your hardware, so please do not
  33.     underestimate the difficulty of this task.
  34.  
  35.     Assumptions here are that you can run MSDOS or PCDOS
  36.     version 2 or 3; Fido does not support ANY other operating
  37.     system.
  38.  
  39.     Either a device driver or a terminate-stay-resident type
  40.     structure for your driver set is reccomended. Device drivers
  41.     obviously go in your CONFIG.SYS on the boot disk; term stay
  42.     res programs should be put in AUTOEXEC.BAT, to be run only 
  43.     ONCE. Every time you run a term stay res, it consumes more
  44.     memory, unless special provision is made in your program
  45.     to detect whether it was previously loaded. Keep in mind that
  46.     in normal operation, Fido is run more than once, ie. you may
  47.     Control-C Fido to copy files, run in Test Mode, etc.
  48.  
  49.     On the subject of Test Mode, an important note: Fido does not
  50.     make ANY HARDWARE DEPENDENT CALLS in /T test mode. This means
  51.     that ANY version of Fido will work on ANY other machine in
  52.     test mode. You must run it without /T specified in order to
  53.     get it to use your drivers. Test mode is useless as a test of
  54.     your drivers. It means nothing.
  55.  
  56.     It is probably a good idea to test each and every single 
  57.     function before attempting to use Fido with your driver set;
  58.     I repeat, I cannot help you with your drivers in any way.
  59.  
  60.  
  61.     The following is the function call used internally to Fido
  62.     to access the drivers you write. This is provided for your
  63.     information only. 
  64.  
  65.     val= int14(ah,al,dx);
  66.  
  67.     int val;        /* integer return value */
  68.  
  69.     int ah;            /* command byte, 0 - N */
  70.     int al;            /* argument */
  71.     int dx;            /* I/O device, ie. channel */
  72.  
  73.  
  74.     For all calls, DX is the IO device from the /1, /2, etc
  75.     command line switch. This can be used or ignored as desired.
  76.     It will be valid for all calls at all times.
  77.  
  78.     AH is the command type; 0 - 3 are very similar to IBM PC
  79.     INT 14 calls. 4 and up are extentions to support further
  80.     functions. (Note that the IBM version of Fido does NOT
  81.     use INT 14.)
  82.  
  83.     For all calls, your driver MUST preserve all segment
  84.     registers, plus BP and SP. All other registers can be
  85.     modified. Interrupts should be left ENABLED after 
  86.     returning. There is adequate stack space to do almost
  87.     anything you need; there should be at least a kilobyte
  88.     of stack space.
  89.  
  90.  
  91. AH = 0:    Set baud rate
  92.  
  93.     This command is almost identical to the IBM PC equivalent
  94.     call. The upper three bits indicate the baud rate; the
  95.     lower ones indicate parity (always none) and stop bits 
  96.     (always 1). You can always assume that NO PARITY and ONE
  97.     STOP BIT are used throughout Fido.
  98.  
  99.         Baud    Value
  100.          300    043h
  101.         1200    083h
  102.         2400    0a3h
  103.         9600    0e3h
  104.  
  105.     The sample driver strips off all but the upper three
  106.     bits. You can do this in your driver also, but Fido
  107.     will always pass the byte patterns as defined above.
  108.  
  109.  
  110.  
  111. AH = 1:    Write a character to the serial port
  112.  
  113.     Output the character in AL to the serial port. Wait for 
  114.     output ready as necessary.
  115.  
  116.  
  117.  
  118. AH = 2:    Read a character from the serial port
  119.  
  120.     Return one character from the serial port in AL. Wait for 
  121.     one if necessary.
  122.  
  123.  
  124. AH = 3:    Return status
  125.  
  126.     This command returns various status bits back to Fido in AH
  127.     and AL. There are three status bits you must return in this
  128.     call; two have predetermined values, and the other you can
  129.     assign to any other bit, as it is tested with the command
  130.     line /V value. (See below) These are bit patterns, not
  131.     numeric values; you can (and will) have more than one bit
  132.     set at a time.
  133.  
  134.     AH:    20h        TBE    Transmit Buffer Empty
  135.         01h        RDA    Receive Data Available
  136.  
  137.     TBE means the transmitter is ready to accept a character.
  138.     RDA means there is a character from the modem waiting.
  139.  
  140.     The other bit the the Carrier Detect (CD) bit. This can be
  141.     returned in either AH or AL. The command line switch /V
  142.     defines the mask bit used to test this port. For example,
  143.  
  144.         128/V
  145.  
  146.     Defines the CD mask bit to be 128, or 0080h. This is ANDed
  147.     with the value returned by the STATUS call, and if the 
  148.     result is true (bit is set) then Fido assumes the modem is
  149.     connected.
  150.  
  151.     For making this test, Fido treats AH and AL as a 16 bit
  152.     integer, in the usual fashion: AH is the most signifigant
  153.     and AL the least.  Therefore, 32768/V tests the MSB in
  154.     AH, and 1/V test the LSB in AL. You can't use 8192/V 
  155.     or 256/V, since those are TBE and RDA, respectively.
  156.  
  157.     Unused bits may take on any value as you see fit.
  158.  
  159.  
  160.  
  161. AH = 4:    One time initialization
  162.  
  163.     Perform any necessary one time initialization here. Fido 
  164.     will make this call only ONCE before any IO is done to 
  165.     the serial port. 
  166.  
  167.     After this function is called, DTR should be high. This
  168.     is important, as Fido will not raise DTR explicitly for
  169.     the first call.
  170.  
  171.  
  172. AH = 5:    One time UN initialization
  173.  
  174.     Do one time un-initialization; this is called ONCE, just
  175.     before Fido exits to DOS. Remove any interrupt structures
  176.     or whatever were installed by AH = 0. NO OTHER call will be
  177.     mode to the IO drivers after this call.
  178.  
  179.     It is general practice when exiting Fido to leave the 
  180.     DTR line low so that the modem is disabled when Fido 
  181.     is not running. Fido lowers DTR before calling this
  182.     function and exiting, but you might want to make sure that
  183.     this function does not raise it again inadvertantly.
  184.  
  185.  
  186.  
  187. AH = 6:    Raise/Lower Data Terminal Ready
  188.  
  189.     This function controls the state of the DTR line output to
  190.     the modem, usually on Pin 20. AL = 0 means lower DTR; 
  191.     AL = 1 means raise it true. True enables the modem; false
  192.     disables it.
  193.  
  194.     No other functions in your drivers should change the state
  195.     of the DTR line, except AH = 4 and AH = 5. See the note
  196.     in AH = 5 about exiting Fido.
  197.  
  198. AH = 7:    Return Timer Tick parameters
  199.  
  200.     This function is used to tell Fido about the timer tick
  201.     to be used for marking time. This is an extremely critical
  202.     function, and luckily, fairly simple. The hard part will
  203.     be getting the information.
  204.  
  205.     AH = 4 is called before this call, so you can use that to
  206.     start any timer running if necessary; if you do, use AH = 5
  207.     to remove it.
  208.  
  209.     AH = 7 returns three numbers:
  210.  
  211.         AL =     Timer Tick Interrupt Number    0 - 255
  212.         AH =    Ticks Per Second
  213.         DX =     Timer Tick Rate, Milliseconds
  214.  
  215.     Note that this function merely returns fixed values to
  216.     Fido; Fido will do all the work of operating the timer
  217.     interrupt, and pass control to the original interrupt
  218.     service routine. The following information is given
  219.     as background only.
  220.  
  221.     Fido's timer tick is done very simply by inserting itself
  222.     in series with the interrupt numbe you specify in AL. When
  223.     Fido has done its timer counter incrementing, it chains
  224.     via a long jump to the original interrupt vector, thereby
  225.     preserving the original interrupt vector. Fido does not 
  226.     defer the interrupt by more than a few hundred microseconds,
  227.     so there are no problems with interrupt acknowledges
  228.     regardless of the interrupt system type. The DEC Rainbow,
  229.     for instance, has a low tolerance for interrupt deferrment;
  230.     it has hardware to check for interrupt loss, and the screen
  231.     refresh depends on a repeatable clock; Fido's timer tick
  232.     method presents no problem.
  233.  
  234.     The reason for both ticks per second and milliseconds per
  235.     tick is that frequently the timer is at an inconvenient rate;
  236.     the IBM PC for example is approx. 55 mS, which does not make
  237.     for easy counting. (Note that if you work it out, the
  238.     sample drive as supplied is very inaccurate. Oh well.)
  239.  
  240.     Fido counts both milliseconds and hours minutes seconds; these
  241.     two parameters let you choose values that will result in the 
  242.     highest accuracy. It is not necessary to have extreme accuracy.
  243.  
  244.     Fido does its millisecond counting by adding the number you
  245.     return in DX to a 32 bit counter in memory; it is used for
  246.     XMODEM, etc timeouts, and does not need to be highly accurate;
  247.     10% is fine, but try for the most accurate possible.
  248.  
  249.     Hour minute second counting is done with the number your return
  250.     in AH; every (AH) timer tick Fido increments the seconds counter.
  251.     This value should be as accurate as is possible, since this is
  252.     what controls each users time limit on the system.
  253.