home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / FSC.ZIP / FSC-0008.TXT < prev    next >
Text File  |  1987-10-11  |  29KB  |  697 lines
  1. FSC-0008
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                  Fundamentals of FOSSIL implementation and use
  14.                        Draft Version 4  August 10, 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. Introduction
  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.     At the same time something was rotten in the state of Texas. Wynn Wagner
  98.     started  encountering some serious  difficulties in his Opus development
  99.     effort. Specifically, he couldn't force the Greenleaf(tm) Communications
  100.     Libraries to behave in exactly the way he felt Opus required.  Enter Bob
  101.     Hartman.Having already enjoyed success in the effort with Thom Henderson,
  102.     he suggested to Wynn that with very few extensions,  any driver that was
  103.     already  SEAdog(tm) 4.0 compatible could drive Opus as well.  About that
  104.     time, Vince called Wynn to discuss porting Opus to the DEC Rainbow. Wynn
  105.     called Bob, Bob called Vince, and the FOSSIL driver came into existence.
  106.  
  107.     FOSSIL is an acronym for "Fido/Opus/SEAdog Standard Interface Layer". To
  108.     say that the concept has gained wide acceptance in the FidoNet community
  109.     would be an understatement. Henk Wevers' DUTCHIE package uses the FOSSIL
  110.     communications services.   Ron Bemis' OUTER package uses FOSSIL services
  111.     for everything it does and as a result it is completely generic.   There
  112.     are already FOSSIL implementations for the Tandy 2000, Heath/Zenith 100,
  113.     Sanyo 555 and other "non-IBM" architectures. With each new 'port' of the
  114.     spec, the potential of a properly coded FOSSIL application grows!
  115.  
  116. Fundamentals of FOSSIL implementation and use                         Page 2
  117. Basic conventions and calling method
  118.  
  119.  
  120.  
  121.  C. Basic principles of a FOSSIL driver
  122.  
  123.     1)  Interrupt 14H.
  124.  
  125.     The one basic rule that the driver depends upon,  is the ability for ANY
  126.     target machine to allow the vector for INT 14H (usually pointing to BIOS
  127.     comm functions) to be "stolen" by the driver.  In a system where the INT
  128.     14H vector is used already, it must be possible to replace the "builtin"
  129.     functionality with that of a FOSSIL,  when an application that wants the
  130.     use of a FOSSIL is to be run on the target machine.
  131.  
  132.  
  133.     2)  How to install a FOSSIL driver in a system
  134.  
  135.     There's no hard and fast way to do this. The FOSSIL might be implemented
  136.     as part of a device driver (like Ray Gwinn's X00.SYS) and therefore gets
  137.     loaded using a line in CONFIG.SYS at bootup time.  It might be done as a
  138.     TSR (terminate and stay resident) program, in which event you install it
  139.     by running the program  (DECcomm by Vince Perriello and Opus!Comm by Bob
  140.     Hartman work this way, for example).
  141.  
  142.  
  143.     3)  How an application can detect the presence of a FOSSIL
  144.  
  145.     The driver has a "signature" that can be used to determine whether it is 
  146.     present in memory. At offset 6 in the INT 14H service routine is a word, 
  147.     1954 hex,  followed by a byte that specifies the maximum function number 
  148.     supported by the driver. This is to make it possible to determine when a
  149.     driver is present and what level of functionality it provides. Also, the
  150.     Init call (see below) returns a 1954 Hex in AX.  SEAdog(tm) looks at the
  151.     signature and Opus just goes for the Init. Fido doesn't do either.
  152.  
  153.  
  154.     4)  How to call a FOSSIL function
  155.  
  156.     The FOSSIL driver is entered by issuing a software Interrupt 14 Hex from
  157.     the application  program. The code corresponding to the desired function 
  158.     should be in 8-bit register AH. For calls that relate to communications,
  159.     the port number will be passed from the application in register DX. When
  160.     DX contains a zero (0) it signifies use of COM1, or whatever the "first"
  161.     serial port on your machine is called. A one (1) in DX points the driver
  162.     at COM2, and so on. A value of Hex FF in DX is considered a special case
  163.     where the driver should do no actual processing but return SUCCESS.   In
  164.     the specific case of Init or Uninit with DX=FF,the FOSSIL should perform
  165.     all non-communications  processing  necessary  with such calls.  In some
  166.     machines  (H/Z-100 for example),  the FOSSIL must  assume control of the
  167.     keyboard in order to service the keyboard functions. 
  168.  
  169.     For all functions, any registers not specifically  containing a function
  170.     return can be assumed to be preserved across the call.
  171.  
  172. Fundamentals of FOSSIL implementation and use                         Page 3
  173. Communications functions
  174.  
  175.  
  176.  
  177. D. Functions currently defined for FOSSILs
  178.  
  179.  
  180.     AH = 00H    Set baud rate 
  181.         Input:    AL = baud rate code
  182.             DX = port number
  183.  
  184.     This works the same as the  equivalent IBM PC BIOS call,  except that it
  185.     ONLY selects a baud rate.  This is passed in the high order 3 bits of AL
  186.     as follows:
  187.  
  188.         010 =   300 baud
  189.         011 =   600  ''
  190.         100 =  1200  ''
  191.         101 =  2400  ''
  192.         110 =  4800  ''
  193.         111 =  9600  ''
  194.         000 = 19200  '' (Replaces old 110 baud mask)
  195.         001 = 38400  '' (Replaces old 150 baud mask)
  196.  
  197.     The low order 5 bits can be implemented or not by the FOSSIL, but in all
  198.     cases, if the low order bits of AL are 00011,  the result should be that
  199.     the communications device should be set to eight data bits, one stop bit
  200.     and no parity. This setting is a  MINIMUM REQUIREMENT  of Fido, Opus and
  201.     SEAdog.  For purposes of completeness,  here are the IBM PC "compatible"
  202.     bit settings:
  203.  
  204.     Bits 4-3 define parity:     0 0       no parity 
  205.                                 1 0       no parity 
  206.                                 0 1      odd parity 
  207.                                 1 1     even parity 
  208.   
  209.     Bit 2 defines stop bits:      0        1 stop bit;  
  210.                                   1      1.5 bits for 5-bit char;
  211.                                            2 for others 
  212.   
  213.     Bits 1-0 character length:  0 0        5 bits 
  214.                                 0 1        6 bits 
  215.                                 1 0        7 bits 
  216.                                 1 1        8 bits 
  217.  
  218.  
  219.     AH = 01H    Transmit character 
  220.         Input:    AL = character
  221.             DX = port number
  222.         Output: AX contains status bits (see function 3)
  223.  
  224.     AL contains the character to be sent.   If there is room in the transmit
  225.     buffer the return will be immediate,  otherwise it will wait until there
  226.     is room to store the character in the transmit buffer.  On return, AX is
  227.     set as in a status request (see function 3).
  228.  
  229. Fundamentals of FOSSIL implementation and use                         Page 4
  230. Communications functions
  231.  
  232.  
  233.     AH = 02H    Receive character 
  234.         Input:    DX = port number
  235.         Output:    AL = input character
  236.  
  237.     If there is a character  available in the  receive buffer,  returns with 
  238.     the next character in AL.  It will wait until a character is received if
  239.     none is available.
  240.  
  241.  
  242.     AH = 03H    Request status
  243.         Input:    DX = port number
  244.         Output:    AX = status bit mask (see below)
  245.  
  246.     Returns with the line and modem status in AX.  Status bits returned are:
  247.  
  248.         In AH:
  249.         Bit 0 =    RDA  - input data is available in buffer
  250.         Bit 5 = THRE - room is available in output buffer
  251.         Bit 6 = TSRE - output buffer is empty
  252.  
  253.         In AL:
  254.         Bit 7 =    DCD  - carrier detect 
  255.  
  256.     This can be used by the application to determine  whether carrier detect
  257.     (CD) is set,  signifying the presence/absence of a remote connection, as
  258.     well as monitoring both the input and output buffer status.
  259.  
  260.  
  261.     AH = 04H    Initialize driver 
  262.         Input:    DX = port number
  263.               ( BX = 4F50H
  264.             CX = ^C flag address --- optional )
  265.         Output:    AX = 1954H if successful
  266.             BL = maximum function number supported
  267.                  (not counting functions 7E and above)
  268.             BH = rev of FOSSIL doc supported
  269.  
  270.     This is used to tell the driver to begin  operations,  and to check that
  271.     the driver is installed. This function should be called before any other
  272.     communications calls are made.  At this point all interrupts involved in
  273.     supporting the comm port (specified in DX) should be set up for handling 
  274.     by the FOSSIL, then enabled.  If BX contains 4F50 hex,  then the address 
  275.     specified in BX:CX is that of a ^C flag byte in the application program,
  276.     to be incremented when  ^C is detected in the keyboard service routines.
  277.     This is an optional service and only need be supported on machines where
  278.     the keyboard service can't (or won't) perform an INT 1B or INT 23 when a
  279.     Control-C is entered.  DTR is raised by this call.
  280.  
  281.     NOTE: Should an additional call to this service occur  (2 Inits or Init,
  282.     Read,Init, etc.) the driver should reset all buffers, flow control, etc.
  283.     to the INIT state and return SUCCESS.
  284.  
  285. Fundamentals of FOSSIL implementation and use                         Page 5
  286. Communications functions
  287.  
  288.  
  289.     AH = 05H    Deinitialize driver
  290.         Input:    DX = port number
  291.  
  292.     This is used to tell the driver that comm port operations are ended. The
  293.     function should be called  when no more comm port functions will be used
  294.     on the port specified in DX. DTR is NOT affected by this call.
  295.  
  296.  
  297.     AH = 06H    Raise/lower DTR
  298.         Input:    DX = port number
  299.             AL = DTR state to be set (1 = Raise, 0 = Lower)
  300.  
  301.     This function is used to control the DTR line to the modem.    AL = 0 means 
  302.     lower DTR (disable the modem), and AL = 1 means to raise DTR (enable the 
  303.     modem).  No other function (except Init) should alter DTR.
  304.  
  305.  
  306.     AH = 07H    Return timer tick parameters
  307.         Output:    AL = timer tick interrupt number
  308.             AH = ticks per second on interrupt number in AL
  309.             DX = approximate number of milliseconds per tick
  310.  
  311.     This is used to  determine the parameters of the timer tick on any given
  312.     machine.  Three numbers are returned:
  313.  
  314.     AL =   Timer tick interrupt number
  315.     AH =   Ticks per second on interrupt number shown in AL
  316.     DX =   Milliseconds per tick (approximate)
  317.  
  318.     Applications can use this for critical timing  (granularity of less than
  319.     one second) or to set up code  (such as a watchdog)  that is executed on
  320.     every timer tick. See function 16H (add/delete function from timer tick)
  321.     for the preferred way of actually installing such code.
  322.  
  323.  
  324.     AH = 08H    Flush output buffer
  325.         Input:    DX = port number
  326.  
  327.     This is used to force any pending output.   It does not return until all 
  328.     pending output has been sent.  You should use this call with care.  Flow
  329.     control  (documented below)  can make your system hang on this call in a
  330.     tight uninterruptible loop under the right circumstances.
  331.  
  332.  
  333.     AH = 09H    Purge output buffer
  334.         Input:    DX = port number
  335.  
  336.     This is used to purge any pending output.   Any output data remaining in
  337.     the output buffer (not transmitted yet) is discarded.  
  338.  
  339. Fundamentals of FOSSIL implementation and use                         Page 6
  340. Communications functions
  341.  
  342.  
  343.     AH = 0AH    Purge input buffer
  344.         Input:    DX = port number
  345.  
  346.     This is used to purge any pending input.   Any input data which is still
  347.     in the buffer is discarded.
  348.  
  349.  
  350.     AH = 0BH    Transmit no wait
  351.         Input:    DX = port number
  352.         Output:    AX = 1 if character was accepted and 0 if not.
  353.  
  354.     This is exactly the same as the "regular"  transmit call, except that if
  355.     the driver is  unable to  buffer the character  (the buffer is full),  a
  356.     value of zero (0) is returned in AX. If the driver accepts the character
  357.     (room is available),  a one (1) is returned in AX.
  358.  
  359.  
  360.     AH = 0CH    Non-Destructive Read-ahead
  361.         Input:    DX = port number
  362.         Output:    AX = next character or FFFF if none available
  363.  
  364.     Return in  AX  the next character in the receive buffer.  If the receive 
  365.     buffer is empty, return  FFFF.  The  character  returned  remains in the
  366.     receive buffer. Some applications call this "peek".
  367.  
  368.     AH = 0DH    Keyboard read no wait
  369.         Output:    AX = IBM-style keyboard scan code or FFFF if
  370.                  no keyboard character available
  371.  
  372.     Return in  AX the next character  (non-destructive read ahead)  from the
  373.     keyboard; if nothing is currently in the keyboard buffer, return FFFF in
  374.     AX.   Use IBM-style  function key mapping  in the high order byte.  Scan
  375.     codes for non-"function" keys are not specifically required,  but may be
  376.     included. Function keys return 0 in AL and the "scan code" in AH.
  377.  
  378.  
  379.     AH = 0EH    Keyboard input with wait
  380.         Output:    AX = IBM-style keyboard scan code
  381.  
  382.     Return in AX the next character from the keyboard;  wait if no character
  383.     is available. Keyboard mapping should be the same as function 13.
  384.  
  385.  
  386.     AH = 0FH    Enable or Disable flow control on transmit
  387.         Input:    AL = bit mask describing requested flow control
  388.             DX = port number
  389.  
  390.     This is used to stop output when the "other end" is overwhelmed, or when
  391.     a BBS user wants to stop a screen.
  392.  
  393.     Two kinds of flow control are supported:
  394.  
  395.         Bit 0 = 1    Enable Receiving of XON/XOFF
  396.         Bit 1 = 1    CTS/RTS
  397.             Bit 2 is Reserved
  398.             Bit 3 = 1   Enable Sending of XON/XOFF
  399.  
  400. Fundamentals of FOSSIL implementation and use                         Page 7
  401. Communications functions
  402.  
  403.  
  404.     Flow control is enabled, or disabled, by setting the appropriate bits in
  405.     AL  for the types of flow control we want to ENABLE (value = 1),  and/or
  406.     DISABLE  (value = 0),  and calling this function.  Bit 2 is reserved for
  407.     DSR/DTR but is not currently supported in any implementation.
  408.  
  409.     Applications  using this  function  should set all bits  ON  in the high 
  410.     nibble of AL as well.  There is a compatible  (but not identical) FOSSIL
  411.     driver implementation that uses the  high nibble as a control mask.   If
  412.     your application sets the high nibble to all ones,  it will always work,
  413.     regardless of the method used by any given driver.
  414.  
  415.  
  416.     AH = 10H    Extended Control-C / Control-K checking and transmit on/off
  417.         Input:    AL = flags byte
  418.             DX = port number
  419.         Output:    AX = status (see below)
  420.  
  421.     This is used for BBS  operation,  primarily.  A bit mask is passed in AL
  422.     with the following flags:
  423.  
  424.         Bit 0    enable/disable Control-C / Control-K checking
  425.         Bit 1    disable/enable the transmitter
  426.  
  427.     The Enable (bit 0 = 1) and Disable (Bit 0 = 0) Control-C/Control-K check
  428.     function is meant primarily for BBS use. When the checking is enabled, a
  429.     Control-C or Control-K received  from the communications port will set a
  430.     flag internal to the FOSSIL driver,  but will not be stored in the input
  431.     buffer. The next use of this function will return the value of this flag
  432.     in register AX then clear the flag for the next occurrence. The returned
  433.     value is used by the BBS  software to determine whether output should be
  434.     halted or not.
  435.  
  436.     The Disable (Bit 1 = 1) and Enable (Bit 1 = 0) Transmitter function lets
  437.     the application restrain the asynchronous driver from output in much the
  438.     same way as XON/XOFF would.
  439.  
  440.  
  441.     AH = 11H    Set current cursor location.
  442.         Input:    DH = row (line)
  443.             DL = column
  444.  
  445.     This function looks exactly like like INT 10H, subfunction 2, on the IBM
  446.     PC. The cursor location is passed in DX: row in DH and column in DL. The
  447.     function treats the screen as a coordinate  system whose origin (0,0) is 
  448.     the upper left hand corner of the screen.
  449.  
  450.  
  451.     AH = 12H    Read current cursor location.
  452.         Output:    DH = row (line)
  453.             DL = column
  454.  
  455.     Looks exactly like INT 10H,  subfunction 3,  on the IBM PC.  The current 
  456.     cursor location  (using the same coordinate  system as  function 17)  is 
  457.     passed back in DX.
  458.  
  459. Fundamentals of FOSSIL implementation and use                         Page 8
  460. Communications functions
  461.  
  462.  
  463.     AH = 13H    Single character ANSI write to screen.
  464.         Input: AL = character to display
  465.  
  466.     The character in AL is sent to the screen by the fastest method possible
  467.     that allows ANSI processing to occur (if available). This routine should
  468.     not be used in such a way that DOS output  (which is not re-entrant) can 
  469.     not be employed by some FOSSIL driver to perform the function  (in fact,
  470.     on the IBM PC that is likely to be how it's done).  On some systems such
  471.     as the DEC Rainbow this will be a very fast method of screen writing.
  472.  
  473.  
  474.     AH = 14H    Enable or disable watchdog processing
  475.         Input:    AL = 1 to enable or 0 to disable watchdog
  476.             DX = port number
  477.  
  478.     When watchdog is enabled,   the state of the carrier detect (CD) line on
  479.     the comm port specified in DX should be constantly monitored. Should the
  480.     state of that line become FALSE (carrier lost), the system should be re-
  481.     booted, to enable the BBS (or other application) to start up again. This
  482.     monitor is not affected by Init/Uninit etc.
  483.  
  484.  
  485.     AH = 15H    Write character to screen using BIOS support routines
  486.         Input:    AL = character to display
  487.  
  488.     The character in AL is sent to the screen using  BIOS-level Input/Output 
  489.     routines. This differs from function 19 in that DOS I/O CAN    NOT be used,
  490.     as this function might be called from driver level.
  491.  
  492.  
  493.     AH = 16H    Insert or Delete a function from the timer tick chain
  494.         Input:    AL    = 1 to add a function or 0 to delete one
  495.             ES:DX = address of function
  496.         Output:    AX    = FFFF if unsuccessful
  497.  
  498.     This function is used to allow a  central authority  to manage the timer
  499.     interrupts, so that as code is loaded and unloaded, the integrity of the
  500.     "chain" is not compromised.  Rather than using the traditional method of
  501.     saving the old contents of the timer vector, storing the address of your
  502.     routine there,  and executing a far call to the "old" routine when yours
  503.     is done, instead you call this function. It manages a list of such entry
  504.     points and calls them on a timer tick (interrupt) using a FAR call.  All
  505.     the usual cautions about making DOS calls apply (that is, DON'T!).
  506.  
  507.     This makes it possible for a program to get in and out of the tick chain
  508.     without having to know whether another program has also done so since it
  509.     first insinuated itself.   At least 4 entries should be available in the
  510.     driver's table (including one to be used by Watchdog if implemented that
  511.     way).
  512.  
  513. Fundamentals of FOSSIL implementation and use                         Page 9
  514. Communications functions
  515.  
  516.  
  517.     AH = 17H    Reboot system
  518.         Input:    AL = 0 for "cold boot" or 1 for "warm boot"
  519.  
  520.     Perform the old 3-finger salute.  Used in extreme emergency by code that
  521.     can't seem to find a "clean" way out of the trouble it has gotten itself
  522.     into.  Hopefully it won't happen while you're computing something in the
  523.     other half of a DoubleDOS system. If your machine can make a distinction
  524.     between a "cold" (power-up, self-test and boot) and a "warm" (just boot)
  525.     bootstrap,  your FOSSIL should support the flag in AL. Otherwise just do
  526.     whatever bootstrap is possible.
  527.  
  528.  
  529.     AH = 18H    Read block (transfer from FOSSIL to user buffer)
  530.         Input:    CX = maximum number of characters to transfer
  531.             DX = port number
  532.              ES = segment of user buffer
  533.             DI = offset into DS of user buffer
  534.         Output:    AX = number of characters actually transferred
  535.  
  536.     A "no-wait" block read of 0 to 0xffff characters from the FOSSIL inbound
  537.     ring buffer to the calling routine's buffer. DS:SI are left untouched by
  538.     the call; the count of bytes actually transferred will be in AX.
  539.  
  540.  
  541.     AH = 19H    Write block (transfer from user buffer to FOSSIL)
  542.         Input:    CX = maximum number of characters to transfer
  543.             DX = port number
  544.              ES = segment of user buffer
  545.             DI = offset into DS of user buffer
  546.         Output:    AX = number of characters actually transferred
  547.  
  548.     A  "no-wait"  block  move of 0 to 0xffff  characters  from  the  calling 
  549.     program's buffer into the FOSSIL outbound ring buffer. The actual number
  550.     of characters moved into the ring buffer will be returned in AX.
  551.  
  552.  
  553.     AH = 1AH    Break Begin or End
  554.         Input:    AL = 1 to start a 'break' or 0 to end one.
  555.             DX = port number
  556.  
  557.     Send a break signal to the modem.  If AL=1, the driver will commence the
  558.     transmission of a 'break'. If AL=0 the driver will end the 'break'. This
  559.     is useful for communications with devices that can only go into 'command
  560.     mode' when a BREAK is received. Note: the application is responsible for
  561.     the timing of the BREAK.  Also,  if the FOSSIL has been restrained by an
  562.     XOFF received from the modem, the flag will be cleared.   An Init or Un-
  563.     Init will stop an in-progress BREAK.
  564.  
  565. Fundamentals of FOSSIL implementation and use                        Page 10
  566. Communications functions
  567.  
  568.  
  569.     AH = 1BH    Return information about the driver
  570.         Input:    CX = size of user info buffer in bytes
  571.             DX = port number (if data about port desired)
  572.              ES = segment of user info buffer
  573.             DI = offset into DS of user info buffer
  574.         Output:    AX = number of bytes actually transferred
  575.  
  576.     Transfer information about the driver and its current status to the user
  577.     for use in determining,  at the application level, limits of the driver.
  578.     Designed to assist  "generic" applications  to adjust to "foreign" gear.
  579.  
  580.     The data structure currently returned by the driver is as follows (sorry
  581.     but you'll have to live with assembly syntax):
  582.  
  583.     info    equ    $        ; define begin of structure 
  584.     strsiz    dw    info_size    ; size of the structure in bytes 
  585.     majver    db    curr_fossil    ; FOSSIL spec driver conforms to
  586.     minver    db    curr_rev    ; rev level of this specific driver
  587.     ident    dd    id_string    ; "FAR" pointer to ASCII ID string
  588.     ibufr    dw    ibsize        ; size of the input buffer (bytes)
  589.     ifree    dw    ?        ; number of bytes left in buffer
  590.     obufr    dw    obsize        ; size of the output buffer (bytes)
  591.     ofree    dw    ?        ; number of bytes left in the buffer
  592.     swidth    db    screen_width    ; width of screen on this adapter
  593.     sheight    db    screen_height    ; height of screen    "     "
  594.     baud    db    ?        ; ACTUAL baud rate, computer to modem
  595.     info_size equ $-info
  596.  
  597.     The ident string should be  null-terminated,  and NOT contain a newline.
  598.     The baud rate byte contains the bits that  Function 00H would use to set
  599.     the port to that speed.
  600.  
  601.     Additional information will always be passed after these,  so that,  for
  602.     example, offset "sheight" will never change with FOSSIL revs.
  603.  
  604.  
  605.  
  606. Fundamentals of FOSSIL implementation and use                        Page 11
  607. "Layered Application" services
  608.  
  609.  
  610.  
  611.     The functions below are not necessarily FOSSIL related. However, because
  612.     dispatchers  that support them are hooked on Interrupt 14H,  it behooves
  613.     the FOSSIL developer to support them as well to avoid fragmenting memory
  614.     with several dispatchers.
  615.  
  616.  
  617.  
  618.     AH = 7EH    Install an "external application" function
  619.         Input:    AL = code assigned to external application
  620.             DX = offset of application entry point
  621.              DS = segment of application entry point
  622.         Output:    AX = 1954H
  623.             BL = code assigned to application (same as input AL)
  624.             BH = 1 if successfully installed, 0 if not.
  625.  
  626.     This call is used by external application code  (special screen drivers,
  627.     modem code, database code, etc) to link into the INT 14H service for use
  628.     by multiple applications. The "error return" (BH=0 with AX=1954H) should
  629.     mean that  another application layer has  already been installed at that
  630.     particular code. Codes 80H through BFH should be supported.
  631.  
  632.     External application  codes 80-83 are  reserved by FOSSIL developers for
  633.     re-organizing FOSSIL services by type (comm, screen, keyboard, system).
  634.  
  635.     Installed application code will be entered, via a FAR call, from the INT
  636.     14H dispatcher whenever it is entered with AH=(application code).
  637.   
  638.     If the value returned in AX from this function is not 1954H, the service
  639.     code that is trying to be installed should bring up its own INT 14H code
  640.     that can service INT 14H functions 7E-BFH (80-BF are "applications").
  641.  
  642.  
  643.     AH = 7FH    Remove an "external application" function
  644.         Input:    AL = code assigned to external application
  645.             DX = offset of application entry point
  646.              DS = segment of application entry point
  647.         Output:    AX = 1954H
  648.             BL = code assigned to application (same as input AL)
  649.             BH = 1 if successfully removed, 0 if not.
  650.  
  651.     Removes an application's entry into the table.  Usually so it can remove
  652.     itself from memory. Error return means DS:DX did not match or that there
  653.     is no entry at the slot described by AL.
  654.  
  655.     An application that wants to remove itself from memory can issue the  7F
  656.     function to remove itself from the table, then, if it is successful, get
  657.     out of memory. If it had to install itself with an INT 14H dispatcher it
  658.     may back itself out, provided no other applications  have been installed
  659.     on top of it (using its dispatcher).
  660.   
  661.  
  662. Fundamentals of FOSSIL implementation and use                        Page 12
  663.  
  664.  
  665.  
  666.  
  667. E.  Validation Suite.
  668.  
  669.     Well, there is one, but it's involved.  Run FIDO_GEN V11w on your FOSSIL
  670.     for about a week with  reasonable caller activity  in the message areas,
  671.     file uploads and downloads,  and FidoNet(tm) mail.  Run SEAdog for a few
  672.     days,  sending and receiving a reasonable  number of messages.  Then run
  673.     Opus for about the same amount of time.   Using Ron Bemis' OUTER package
  674.     is also a useful test of the timer tick and reboot code. Some reasonable
  675.     combination of the  above steps should ensure that your FOSSIL will work
  676.     with most everything coded for one.
  677.  
  678.  
  679.  
  680. F.  Distribution.
  681.  
  682.     The good folks who  distribute Opus will be more than happy to take note
  683.     of your new FOSSIL driver and to add it to their distribution.  And,  of
  684.     course, you can upload it to any system you want, but your work will get
  685.     more publicity in the Opus community than anywhere else.
  686.  
  687.  
  688.  
  689. G.  Technical Discussion.
  690.  
  691.     A FOSSIL echomail conference exists,  for the purpose of exchanging info
  692.     and implementation details for FOSSIL drivers.It is coordinated by Vince
  693.     Perriello at IFNA node 141/491.  Contact him for details on how to join.
  694.     Keep in mind though,  that this conference is intended  SPECIFICALLY for
  695.     implementors of FOSSIL  software and not as a general Q&A conference for
  696.     people who think FOSSILs have something to do with paleontology.
  697.