home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / fossil / hzcomm31.arc / FOSSIL.DOC next >
Text File  |  1987-03-07  |  20KB  |  546 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                  Fundamentals of FOSSIL implementation and use
  14.                         Draft Version 3   March 7, 1987
  15.                       Vincent E. Perriello, VEP Software
  16.  
  17.  
  18.          IFNA Address: Network 141 Node 491 (141/491)
  19.      Usenet address: ...decvax!envore!vaxine!spark!141!491!Vince_Perriello
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  Copyright (C) 1987, VEP Software, Naugatuck, CT 06770. All rights reserved.
  50.  
  51.  This document may be freely used or copied by anyone interested in the data
  52.  contained herein. No fees may be charged for distribution of this document.
  53.  You will be held  accountable for all such charges,  and expected to either
  54.  reimburse those persons or organizations so charged,  or to make a donation
  55.  in the exact amount of those fees to the International FidoNet Association, 
  56.  to  assist  them in their  efforts to  advance the  technology of  personal 
  57.  computer telecommunications.
  58.  
  59. Fundamentals of FOSSIL implementation and use                         Page 1
  60.  
  61.  
  62.  
  63.  
  64.  A. Objectives of this document
  65.  
  66.     This document is directed at implementors or intellectuals.  It is meant
  67.     for use in implementing applications that can use FOSSIL drivers, or for
  68.     details needed to implement a new FOSSIL. As such it won't always go out
  69.     of its way to explain itself to the neophyte.
  70.  
  71.     This document will have served its purpose to you if you are able to use
  72.     the data contained within to perform either of the above tasks.   If you
  73.     feel that necessary data has been omitted please contact Vince Perriello
  74.     at the above listed address so that the appropriate changes can be made.
  75.  
  76.  
  77.  
  78.  B. Historical perspective
  79.  
  80.     For those people who were not lucky enough to have an IBM PC or a system
  81.     nearly completely compatible, the world has not been very friendly. With
  82.     his implementation of the Generic Fido(tm) driver,  Tom Jennings made it
  83.     possible for systems that had nothing in common with an IBM PC except an
  84.     808x-class processor, and the ability to run MS-DOS Version 2 and above,
  85.     to run his Fido(tm) software. That was a lot to ask, and a lot of people
  86.     thought it was enough.
  87.  
  88.     But not everyone.  While Thom Henderson was debugging Version 4.0 of his
  89.     SEAdog(tm) mail package,  an "extended" Generic driver was designed  (in
  90.     cooperation with Bob Hartman)   as a quick kludge to help him get past a
  91.     problem with certain UART chips.The new hook was quickly pounced upon by
  92.     Vince Perriello,  who, with almost DAILY prodding (ouch! it still hurts)
  93.     by Ken Kaplan,had been working with Henderson to get DEC Rainbow support
  94.     into SEAdog. Vince then coded a driver to use this hook and - Voila! - 
  95.     SEAdog 4.0 started working like a champ on the Rainbow.
  96.  
  97.     Then something WONDERFUL happened. Wynn Wagner started having a bad time
  98.     getting the Greenleaf(tm) Communication Libraries to work in exactly the
  99.     way he wanted them to. Enter Bob Hartman. Having already enjoyed success
  100.     in the effort with Thom Henderson, he suggested to Wynn that with a very
  101.     few extensions, the driver that SEAdog(tm) 4.0 liked could drive Opus as
  102.     well. Then Vince called Wynn, Wynn called Bob, Bob called Vince, and the
  103.     FOSSIL driver came into existence.
  104.  
  105.     FOSSIL, by the way, is an acronym that Vince dreamed up. It took a while
  106.     for everyone to stomach it,but it now seems to be loved by all. It is an
  107.     acronym for "Fido/Opus/SEAdog Standard Interface Layer". And the concept
  108.     is catching on.   Henk Wevers is reportedly coding a terminal program in
  109.     Turbo Pascal that uses FOSSIL services to do all the work.   This should
  110.     mean that the result will play elsewhere.   And there are already FOSSIL
  111.     implementations for the Tandy 2000, Sanyo 555, Z100 and others,   so the
  112.     potential of a properly coded FOSSIL application is very great.
  113.  
  114. Fundamentals of FOSSIL implementation and use                         Page 2
  115.  
  116.  
  117.  
  118.  
  119.  C. Basic principles of a FOSSIL driver
  120.  
  121.     1)  Interrupt 14H.
  122.  
  123.     The one basic rule that the driver depends upon,  is the ability for ANY
  124.     target machine to allow the vector for INT 14H (absolute locations 50 to
  125.     53 in segment 0) to be "stolen" by the driver. In a system where the INT
  126.     14H vector is used already, it must be possible to replace the "builtin"
  127.     functionality with that of a FOSSIL,  when an application that wants the
  128.     use of a FOSSIL is to be run on the target machine.
  129.  
  130.  
  131.     2)  How to install a FOSSIL driver in a system
  132.  
  133.     There's no hard and fast way to do this. The FOSSIL might be implemented
  134.     as part of a device driver (like Ray Gwinn's X00.SYS) and therefore gets
  135.     loaded using a line in CONFIG.SYS at bootup time.  It might be done as a
  136.     TSR (terminate and stay resident) program, in which event you install it
  137.     by running the program  (DECCOMM by Vince Perriello and Opus!Comm by Bob
  138.     Hartman work this way, for example).
  139.  
  140.  
  141.     3)  How an application can detect the presence of a FOSSIL
  142.  
  143.     The driver has a "signature" that can be used to determine whether it is 
  144.     present in memory. At offset 6 in the INT 14H service routine is a word, 
  145.     1954 hex,  followed by a byte that specifies the maximum function number 
  146.     supported by the driver. This is to make it possible to determine when a
  147.     driver is present and what level of functionality it provides. Also, the
  148.     Init call (see below) returns a 1954 Hex in AX.  SEAdog(tm) looks at the
  149.     signature and Opus just goes for the Init. Fido doesn't do either.
  150.  
  151.  
  152.     4)  How to call a FOSSIL function
  153.  
  154.     The FOSSIL driver is entered by issuing a software Interrupt 14 Hex from
  155.     the application  program. The code corresponding to the desired function 
  156.     should be in 8-bit register AH. For calls that relate to communications,
  157.     the port number will be passed from the application in register DX. When
  158.     DX contains a zero (0) it signifies use of COM1, or whatever the "first"
  159.     serial port on your machine is called. A one (1) in DX points the driver
  160.     at COM2, and so on.
  161.  
  162. Fundamentals of FOSSIL implementation and use                         Page 3
  163.  
  164.  
  165.  
  166.  
  167. D. Functions currently defined for FOSSILs
  168.  
  169.  
  170.  
  171.     AH = 0    Set baud rate 
  172.         Input:    AL = baud rate code
  173.             DX = port number
  174.  
  175.     This works the same as the  equivalent IBM PC BIOS call,  except that it
  176.     ONLY selects a baud rate.  This is passed in the high order 3 bits of AL
  177.     as follows:
  178.  
  179.         000 =  110 baud
  180.         001 =  150  ''
  181.         010 =  300  ''
  182.         011 =  600  ''
  183.         100 = 1200  ''
  184.         101 = 2400  ''
  185.         110 = 4800  ''
  186.         111 = 9600  ''
  187.  
  188.     The low order 3 bits can be implemented or not by the FOSSIL, but in all
  189.     cases, if the low order bits of AL are 00011,  the result should be that
  190.     the communications device should be set to eight data bits, one stop bit
  191.     and no parity. This setting is a  MINIMUM REQUIREMENT  of Fido, Opus and
  192.     SEAdog.
  193.  
  194.  
  195.  
  196.     AH = 1    Transmit character 
  197.         Input:    AL = character
  198.             DX = port number
  199.         Output: AX contains status bits (see function 3)
  200.  
  201.     AL contains the character to be sent.   If there is room in the transmit
  202.     buffer the return will be immediate,  otherwise it will wait until there
  203.     is room to store the character in the transmit buffer.  On return, AX is
  204.     set as in a status request (see function 3).
  205.  
  206.  
  207.  
  208.     AH = 2    Receive a character 
  209.         Input:    DX = port number
  210.         Output:    AL = input character
  211.  
  212.     If there is a character  available in the  receive buffer,  returns with 
  213.     the next character in AL.  It will wait until a character is received if
  214.     none is available.
  215.  
  216. Fundamentals of FOSSIL implementation and use                         Page 4
  217.  
  218.  
  219.  
  220.  
  221.     AH = 3    Request status
  222.         Input:    DX = port number
  223.         Output:    AX = status bit mask (see below)
  224.  
  225.     Returns with the line and modem status in AX.  Status bits returned are:
  226.  
  227.         In AH:
  228.         Bit 0 =    RDA  - input data is available in buffer
  229.         Bit 5 = THRE - room is available in output buffer
  230.         Bit 6 = TSRE - output buffer is empty
  231.  
  232.         In AL:
  233.         Bit 7 =    DCD  - carrier detect 
  234.  
  235.     This can be used by the application to determine  whether carrier detect
  236.     (CD) is set,  signifying the presence/absence of a remote connection, as
  237.     well as monitoring both the input and output buffer status.
  238.  
  239.  
  240.  
  241.     AH = 4    Initialize driver 
  242.         Input:    DX = port number
  243.               ( BX = 4F50
  244.             CX = ^C flag address --- optional )
  245.         Output:    AX = 1954H if successful
  246.  
  247.  
  248.     This is used to tell the driver to begin  operations,  and to check that
  249.     the driver is installed. This function should be called before any other
  250.     communications calls are made.  At this point all interrupts involved in
  251.     supporting the comm port (specified in DX) should be set up for handling 
  252.     by the FOSSIL, then enabled.  If BX contains 4F50 hex,  then the address 
  253.     specified in DS:CX is that of a ^C flag byte in the application program,
  254.     to be incremented when  ^C is detected in the keyboard service routines.
  255.     This is an optional service and only need be supported on machines where
  256.     the keyboard service can't (or won't) perform an INT 1B or INT 23 when a
  257.     Control-C is entered.
  258.  
  259.  
  260.  
  261.     AH = 5    Deinitialize driver
  262.         Input:    DX = port number
  263.  
  264.     This is used to tell the driver that comm port operations are ended. The
  265.     function should be called  when no more comm port functions will be used
  266.     on the port specified in DX.
  267.  
  268.  
  269.  
  270.     AH = 6    Raise/lower DTR
  271.         Input:    DX = port number
  272.             AL = DTR state to be set (1 = Raise, 0 = Lower)
  273.  
  274.     This function is used to control the DTR line to the modem.    AL = 0 means 
  275.     lower DTR (disable the modem), and AL = 1 means to raise DTR (enable the 
  276.     modem).  No other function (except Init) should alter DTR.
  277.  
  278. Fundamentals of FOSSIL implementation and use                         Page 5
  279.  
  280.  
  281.  
  282.  
  283.     AH = 7    Return timer tick parameters
  284.         Output:    AL = timer tick interrupt number
  285.             AH = ticks per second on interrupt number in AL
  286.             DX = approximate number of milliseconds per tick
  287.  
  288.     This is used to  determine the parameters of the timer tick on any given
  289.     machine.  Three numbers are returned:
  290.  
  291.     AL =   Timer tick interrupt number
  292.     AH =   Ticks per second on interrupt number shown in AL
  293.     DX =   Milliseconds per tick (approximate)
  294.  
  295.     Applications can use this for critical timing  (granularity of less than
  296.     one second) or to set up code  (such as a watchdog)  that is executed on
  297.     every timer tick. See function 22  (add/delete function from timer tick)
  298.     for the preferred way of actually installing such code.
  299.  
  300.  
  301.  
  302.     AH = 8    Flush output buffer
  303.         Input:    DX = port number
  304.  
  305.     This is used to force any pending output.   It does not return until all 
  306.     pending output has been sent.  You should use this call with care.  Flow
  307.     control  (documented below)  can make your system hang on this call in a
  308.     tight uninterruptible loop under the right circumstances.
  309.  
  310.  
  311.  
  312.     AH = 9    Purge output buffer
  313.         Input:    DX = port number
  314.  
  315.     This is used to purge any pending output.   Any output data remaining in
  316.     the output buffer (not transmitted yet) is discarded.  
  317.  
  318.  
  319.  
  320.     AH = 10    Purge input buffer
  321.         Input:    DX = port number
  322.  
  323.     This is used to purge any pending input.   Any input data which is still
  324.     in the buffer is discarded.
  325.  
  326.  
  327.  
  328.     AH = 11    Transmit no wait
  329.         Input:    DX = port number
  330.         Output:    AX = 1 if character was accepted and 0 if not.
  331.  
  332.     This is exactly the same as the "regular"  transmit call, except that if
  333.     the driver is  unable to  buffer the character  (the buffer is full),  a
  334.     value of zero (0) is returned in AX. If the driver accepts the character
  335.     (room is available),  a one (1) is returned in AX.
  336.  
  337. Fundamentals of FOSSIL implementation and use                         Page 6
  338.  
  339.  
  340.  
  341.  
  342.     AH = 12    Read no wait
  343.         Input:    DX = port number
  344.         Output:    AX = next character or FFFF if none available
  345.  
  346.     Return in  AX  the next character in the receive buffer.  If the receive 
  347.     buffer is empty return FFFF.
  348.  
  349.  
  350.  
  351.     AH = 13    Keyboard read no wait
  352.         Output:    AX = IBM-style keyboard scan code or FFFF if
  353.                  no keyboard character available
  354.  
  355.     Return in  AX the next character  (non-destructive read ahead)  from the
  356.     keyboard;  if nothing there  (in the type-ahead buffer),  return FFFF in
  357.     AX.   Use IBM-style  function key mapping  in the high order byte.  Scan
  358.     codes for non-"function" keys are not specifically required,  but may be
  359.     included.
  360.  
  361.  
  362.  
  363.     AH = 14    Keyboard input with wait
  364.         Output:    AX = IBM-style keyboard scan code
  365.  
  366.     Return in AX the next character from the keyboard;  wait if no character
  367.     is available. Keyboard mapping should be the same as function 13.
  368.  
  369.  
  370.  
  371.     AH = 15    Enable or Disable flow control on transmit
  372.         Input:    AL = bit mask describing requested flow control
  373.             DX = port number
  374.  
  375.     This is used to stop output when the "other end" is overwhelmed, or when
  376.     a BBS user wants to stop a screen.
  377.  
  378.     Two kinds of flow control are supported:
  379.  
  380.         Bit 0 = 1    XON/XOFF
  381.         Bit 1 = 1    CTS/RTS
  382.  
  383.     Flow control is enabled, or disabled, by setting the appropriate bits in
  384.     AL  for the types of flow control we want to ENABLE (value = 1),  and/or
  385.     DISABLE  (value = 0),  and calling this function.  Bit 2 is reserved for
  386.     DSR/DTR but is not currently supported in the DECCOMM implementation.
  387.  
  388.     Applications  using this  function  should set all bits  ON  in the high 
  389.     nibble of AL as well.  There is a compatible  (but not identical) FOSSIL
  390.     driver implementation that uses the  high nibble as a control mask.   If
  391.     your application sets the high nibble to all ones,  it will always work,
  392.     regardless of the method used by any given driver.
  393.  
  394. Fundamentals of FOSSIL implementation and use                         Page 7
  395.  
  396.  
  397.  
  398.  
  399.     AH = 16    Extended Control-C / Control-K checking and transmit on/off
  400.         Input:    AL = flags byte
  401.             DX = port number
  402.         Output:    AX = status (see below)
  403.  
  404.     This is used for BBS  operation,  primarily.  A bit mask is passed in AL
  405.     with the following flags:
  406.  
  407.         Bit 0    enable/disable Control-C / Control-K checking
  408.         Bit 1    disable/enable the transmitter
  409.  
  410.     The Enable (bit 0 = 1) and Disable (Bit 0 = 0) Control-C/Control-K check
  411.     function is meant primarily for BBS use. When the checking is enabled, a
  412.     Control-C or Control-K received  from the communications port will set a
  413.     flag internal to the FOSSIL driver,  but will not be stored in the input
  414.     buffer.  The next use of the function will return the value of this flag
  415.     in register AX then clear the flag for the next occurrence. The returned
  416.     value is used by the BBS  software to determine whether output should be
  417.     halted or not.
  418.  
  419.     The Enable (Bit 1 = 1) and Disable (Bit 1 = 0) Transmitter function lets
  420.     the application restrain the asynchronous driver from output in much the
  421.     same way as XON/XOFF would.
  422.  
  423.  
  424.  
  425.     AH = 17    Set current cursor location.
  426.         Input:    DH = row (line)
  427.             DL = column
  428.  
  429.     This function looks exactly like like INT 10H, subfunction 2, on the IBM
  430.     PC. The cursor location is passed in DX: row in DH and column in DL. The
  431.     function treats the screen as a coordinate  system whose origin (0,0) is 
  432.     the upper left hand corner of the screen.
  433.  
  434.  
  435.  
  436.     AH = 18    Read current cursor location.
  437.         Output:    DH = row (line)
  438.             DL = column
  439.  
  440.     Looks exactly like INT 10H,  subfunction 3,  on the IBM PC.  The current 
  441.     cursor location  (using the same coordinate  system as  function 17)  is 
  442.     passed back in DX.
  443.  
  444.  
  445.  
  446.     AH = 19    Single character ANSI write to screen.
  447.         Input: AL = character to display
  448.  
  449.     The character in AL is sent to the screen by the fastest method possible
  450.     that allows ANSI processing to occur (if available). This routine should
  451.     not be used in such a way that DOS output  (which is not re-entrant) can 
  452.     not be employed by some FOSSIL driver to perform the function  (in fact,
  453.     on the IBM PC that is likely to be how it's done).  On some systems such
  454.     as the DEC Rainbow this will be a very fast method of screen writing.
  455.  
  456. Fundamentals of FOSSIL implementation and use                         Page 8
  457.  
  458.  
  459.  
  460.  
  461.     AH = 20    Enable or disable watchdog processing
  462.         Input:    AL = 1 to enable or 0 to disable watchdog
  463.             DX = port number
  464.  
  465.     When watchdog is enabled,   the state of the carrier detect (CD) line on
  466.     the comm port specified in DX should be constantly monitored. Should the
  467.     state of that line become FALSE (carrier lost), the system should be re-
  468.     booted, to enable the BBS (or other application) to start up again.
  469.  
  470.  
  471.  
  472.     AH = 21    Write character to screen using BIOS support routines
  473.         Input:    AL = character to display
  474.  
  475.     The character in AL is sent to the screen using  BIOS-level Input/Output 
  476.     routines. This differs from function 19 in that DOS I/O CAN    NOT be used,
  477.     as this function might be called from driver level.
  478.  
  479.  
  480.  
  481.     AH = 22    Insert or Delete a function from the timer tick chain
  482.         Input:    AL    = 1 to add a function or 0 to delete one
  483.             DS:DX = address of function
  484.         Output:    AX    = FFFF if unsuccessful
  485.  
  486.     This function is used to allow a  central authority  to manage the timer
  487.     interrupts, so that as code is loaded and unloaded, the integrity of the
  488.     "chain" is not compromised.  Rather than using the traditional method of
  489.     saving the old contents of the timer vector, storing the address of your
  490.     routine there,  and executing a far call to the "old" routine when yours
  491.     is done, instead you call this function. It manages a list of such entry
  492.     points and calls them on a timer tick (interrupt) using a FAR call.  All
  493.     the usual cautions about making DOS calls apply (that is, DON'T!).
  494.  
  495.     This makes it possible for a program to get in and out of the tick chain
  496.     without having to know whether another program has also done so since it
  497.     first insinuated itself.
  498.  
  499.  
  500.  
  501.     AH = 23    Reboot system
  502.         Input:    AL = 0 for "cold boot" or 1 for "warm boot"
  503.  
  504.     Perform the old 3-finger salute.  Used in extreme emergency by code that
  505.     can't seem to find a "clean" way out of the trouble it has gotten itself
  506.     into.  Hopefully it won't happen while you're computing something in the
  507.     other half of a DoubleDOS system. If your machine can make a distinction
  508.     between a "cold" (power-up, self-test and boot) and a "warm" (just boot)
  509.     bootstrap,  your FOSSIL should support the flag in AL. Otherwise just do
  510.     whatever bootstrap is possible.
  511.  
  512. Fundamentals of FOSSIL implementation and use                         Page 9
  513.  
  514.  
  515.  
  516.  
  517. E.  Validation Suite.
  518.  
  519.     Well, there is one, but it's involved.  Run FIDO_GEN V11w on your FOSSIL
  520.     for about a week with  reasonable caller activity  in the message areas,
  521.     file uploads and downloads,  and FidoNet(tm) mail.  Run SEAdog for a few
  522.     days,  sending and receiving a reasonable  number of messages.  Then run
  523.     Opus for the  rest of your natural life.  Why not?  It's a good package.
  524.     Anyway,  some reasonable  compromise with the  above steps should ensure
  525.     that your FOSSIL will work with most everything coded for one.
  526.  
  527.  
  528.  
  529. F.  Distribution.
  530.  
  531.     The good folks who  distribute Opus will be more than happy to take note
  532.     of your new FOSSIL driver and to add it to their distribution.  And,  of
  533.     course, you can upload it to any system you want, but your work will get
  534.     more publicity in the Opus community than anywhere else.
  535.  
  536.  
  537.  
  538. G.  Technical Discussion.
  539.  
  540.     A FOSSIL echomail conference is in the process of starting up.   It will
  541.     be coordinated by Vince Perriello at IFNA node 141/491.  Contact him for
  542.     details on how to join. Keep in mind though, this conference is intended
  543.     SPECIFICALLY  for implementors of  FOSSIL  software and not as a general
  544.     Q&A conference,  for people who think  FOSSILs have something to do with
  545.     paleontology.
  546.