             Functions reference manual for the ONEFOSsil developer
             Copyright c 1995 by Carl Morris and Morris Softronics
       ONEFOSsil, A low level serial I/O communications driver for MS-DOS
                     based FOSSIL 5 compliant applications.

     This document was originally wrote in Word/WordPad.  Translation is
     not perfect.  If you would like the Word/WordPad version, please write
     the publisher.

                                  Introduction

     This document is for developers wanting to use ONEFOSsil specific
     features and for developers just learning about the FOSSIL
     specification.  ONEFOSsil supports most FOSSIL 5 and X00 functions,
     and this document will help define any differences. Portions of this
     document are copyright by VEP Software, Rick Moore, and Raymond Gwinn.
     The rest of this document is copyright by Morris Softronics and Carl
     Morris.

     This documentation is distributed as is and is provided with no
     guarantees.  You use the information contain within at your own risk.

                     What is ONEFOSsil and a FOSSIL driver?

     ONEFOSsil is a simplified serial communications driver for 8250 series
     UART's and MS-DOS based machines running applications requiring a
     simple FOSSIL 5 communications driver.  ONEFOSsil only provides FOSSIL
     based services.

     FOSSIL is an acronym derived from Fido Opus Seadog Serial Interface
     Layer.  The FOSSIL specification was intended to permit machine
     independent software (Fido, Opus, and Seadog at the time) to be
     created and ran on any MS-DOS based 8086 based computer that had a
     FOSSIL compatible driver.  Those days are much over, and FOSSIL
     compatible drivers are only used as a low level communications
     interface for application software.  A better specification is needed
     to keep up with today's quickly changing world, though.

     ONEFOSsil does not maintain total compatibility with the FOSSIL 5
     specification.  These differences will be noted in this document, but
     will seldom cause problems with most modern software.

                                   Interface

     ONEFOSsil's Application Program Interface is partly based on the PC
     BIOS communications interface.  As such, the driver will be entered
     with an 8086 instruction INT 14h.  A function number is passed in 8086
     register AH and other registers are used as needed.  Return codes from
     functions will very from function to function, and is one of the most
     confusing aspect of FOSSIL programming; they're not logical!

     Registers are not modified by ONEFOSsil unless otherwise specified.
     Note that this is not true about all FOSSIL drivers. While this
     document covers basic FOSSIL functions, some differences will be
     encountered from FOSSIL to FOSSIL.

     In most cases, functions will require a port number to operate. In all
     cases, port numbers are passed in register DX.  Most FOSSIL's only
     support ports 0 - 7.  FOSSIL to DigiBoard converters support 0 - 15.
     ONEFOSsil supports ports 0 - 63. Notice that in most cases, the port
     number is one less than the COM port number; but, in most FOSSIL's,
     the port can be specified on any address/irq combination, or may not
     even map to a COM port at all.

     As a note to developers, FOSSIL functions should not be called in a
     way that could cause active code to be reentered.  ONEFOSsil and many
     other FOSSIL's are re-entrant, but not to that great of a degree.

                                   Detection

     Detecting FOSSIL drivers vary.  ONEFOSsil is not detectable in the
     normal fashion that most FOSSIL's are.  The FOSSIL specification
     states that to detect a FOSSIL, one should look at the 6th byte (3rd
     word) after the start of the INT 14h service routine for the word
     1954h, followed by a byte, the maximum function supported by the
     FOSSIL driver. However, because ONEFOSsil is a single port driver, it
     may need to be loaded among other drivers, even itself, or other
     drivers may be loaded after ONEFOSsil, and as such, does not support
     this.  Most other FOSSIL drivers will detect a previously loaded
     driver, and refuse to load.  If other communications drivers are
     loaded after a FOSSIL driver the above detection doesn't work at all.
     Instead, it is better to just make the call to the "Activate" function
     04h and check its return codes.  Almost all current applications
     detect the FOSSIL in this way.  Another method, which only works for a
     few drivers, is to call the "Information" function check its return
     codes.  X00 only works correctly if the FOSSIL port called is active.
     ONEFOSsil and BNU work all the time.  Refer to function 1Bh for more
     information on the "Information" function.

                                   Functions

     The following functions are supported by most FOSSIL drivers.

     Function 00h - Set communications baud, parity, etc.

          Input:  AH = 00h
                  AL = Communications parameters (defined below)
                  DX = Port number

          Output: AX = Port status (see function 03h)

          This function is identical to the IBM PC INT 14h BIOS call except
          that 110 baud and 150 baud have been replaced by 19200 baud and
          38400 baud respectively. See function 1Eh for an enhanced version
          of this function.  In addition, once function 1Eh has been used,
          this function will not set/reset the baud rate until re-enabled
          by a FOSSIL deactivate/activate sequence.

          Bits 7 - 5 define the baud rate:

                  010 =   300 baud
                  011 =   600 baud
                  100 =  1200 baud
                  101 =  2400 baud
                  110 =  4800 baud
                  111 =  9600 baud
                  000 = 19200 baud (Replaces IBM 110 baud setting)
                  001 = 38400 baud (Replaces IBM 150 baud setting)

          Bit 3 must be set to enable parity
          Bit 4 defines parity:

                  0 = odd parity
                  1 = even parity

          Bit 2 defines the number of stop bits:

                  0 = 1 stop bit;
                  1 = 1.5 bits for 5-bit byte length, 2 for all others

          Bits 1 - 0 define character byte length:

                  00 = 5 bits
                  01 = 6 bits
                  10 = 7 bits
                  11 = 8 bits

          The status returned can be found documented under function 03h.

     Function 01h - Transmit character and wait.

          Input:  AH = 01h
                  AL = Character
                  DX = Port number

          Output: AX = Port status (see function 03h)

          Upon entry to this function, AL must contain a character that is
          to be transmitted.  If there is room in the transmit buffer, the
          character is buffered.  Otherwise, this function will loop until
          there is room in the buffer or until a timeout occurs.  If set,
          the high order bit of the returned status indicates a time out
          occurred.  See function 03h for a definition of the return code.

          Note:  X00 executes functions with the interrupt mask set as it
          was when entered.  That is, if X00 is called with interrupts
          masked, interrupts will remain masked during the processing of
          the function.  If this function is called with interrupts masked,
          it may never return.

          Note:  ONEFOSsil always enables interrupts upon the beginning of
          every FOSSIL call, so unless you have severe hardware problems,
          ONEFOSsil should always return.

          Note:  It is advised not to use this function!  It is slow, and
          as X00 and BNU are prone to lock-ups, I suggest that function 0Bh
          be used instead.  Function 0Bh always returns immediately.

     Function 02h - Get received character with wait.

          Input:  AH = 02h
                  DX = Port number

          Output: AH = Line status (same as AH returned by function 3)
                  AL = Input character

          If a character is available in the receive buffer, this function
          returns the next character from the receive buffer.  If no
          characters are available, this function will wait until a
          character is received or until a timeout occurs.  If a timeout
          occurs, the high order bit of AH will be set upon return.  See
          function 03h for a definition of the return code.

          Note:  X00 executes functions with the interrupt mask set as it
          was when entered.  That is, if X00 is called with interrupts
          masked, interrupts will remain masked during the processing of
          the function.  If this function is called with interrupts masked,
          it may never return.

          Note:  ONEFOSsil always enables interrupts upon the beginning of
          every FOSSIL call, so unless you have severe hardware problems,
          ONEFOSsil should always return.

          Note:  It is advised not to use this function!  It is slow, and
          as X00 and BNU are prone to lock-ups, I suggest that function 18h
          be used instead.  Function 18h always returns immediately.
          Sample code for calling this block function in single character
          mode can be found under that function.  Also, X00 and ONEFOSsil
          support a "get character without wait" at function 20h, but is
          not supported by the FOSSIL 5 specification or most other
          FOSSIL's.

     Function 03h - Return Serial Port Status.

          Input:  AH = 03h
                  DX = Port number

          Output: AX = Status bits as follows:

          The Line Status returned in AH resembles the 8250 Line Status
          Register:

               Bit 7 = timeout set by 01h and 02h, all other bits void*
               Bit 6 = TSRE - output buffer is empty*
               Bit 5 = THRE - room is available in output buffer*
               Bit 4 = BRK - break detected (since last return)
               Bit 3 = FE - framing error detected (since last return)
               Bit 2 = PE - parity error detected (since last return)
               Bit 1 = OE - the input buffer has overrun (since last return)*
               Bit 0 = RDA - input data is available in buffer*

          The Modem Status returned in AL resembles the 8250 Modem Status
          Register:

               Bit 7 = Data carrier detect (DCD)*
               Bit 6 = Ring indicator (RI)
               Bit 5 = Data set ready (DSR)
               Bit 4 = Clear to send (CTS)
               Bit 3 = Always set to 1 upon return (DUMMY DCD)*
               Bit 3 = Delta data carrier detect (since last return)
               Bit 2 = Trailing edge ring indicator (since last return)
               Bit 1 = Delta data set ready (since last return)
               Bit 0 = Delta clear to send (since last return)

          * Denotes formal FOSSIL 5 specified bits.

          The FOSSIL Specification calls for the delta data carrier detect
          bit to always be set as to act as a DUMMY DCD.  If software need
          a dummy DCD, software should implement it internally.  As such
          ONEFOSsil does not support it and instead uses the bit as a Delta
          Data Carrier Detect.  All bits without asterisks (*) will vary in
          meaning from FOSSIL to FOSSIL.

          Note:  X00 does not attempt to accurately return the Delta bits.
          ONEFOSsil should correctly return the status of the Delta bits.

     Function 04h - Activate Port.

          Input:  AH = 04h
                  BX = 0h (in case FOSSIL supports Control-C flagging)
                  DX = port number

          Output: AX = 1954h if successful
                  BL = maximum function number supported
                  BH = rev of FOSSIL specification supported

          This function instructs the FOSSIL driver to initialize itself
          for communications on the specified port.  Buffers will be
          cleared, Interrupts activated, and DTR raised.  If the port can
          not be supported, the call goes to the next driver or to the
          system BIOS.

          The FOSSIL specification states that the port parameters are not
          to be initialized at this time.  However, with ONEFOSsil, if port
          parameters have been locked on the command line, they will be
          loaded during this time.

          The FOSSIL specification calls for an optional Control-C flag,
          and is not supported by X00 or ONEFOSsil.  As such, BX should be
          cleared to prevent any possibility of this occurring.

          X00 incorrectly returns the maximum function number (or it isn't
          documented.)  BNU has a compatibility option on whether to return
          the maximum function, or the count of functions.  ONEFOSsil will
          only return the maximum function (currently 21h.)

          Multiple calls to this function will repeat the above process as
          if the port had not been open.  If you want to insure the port is
          closed before opening, call function 05h first (many BBS's and
          doors do this.)

          NOTICE:  At some future date, Ray Gwinn intends to make this
          function identical to the PS/2's function 04h.  Function 1Ch is a
          duplicate of this function.  It is my intention to create a new
          standard that will support this, and permit much better
          communications over all devices available.  I do not; however,
          have any opinion on which call should be made.  The latest X00
          and VX00 still support both functions.

     Function 05h - Deactivate Port.

          Input:  AH = 05h
                  DX = Port number

          Output: Nothing

          This function instructs the FOSSIL that it should no longer
          process calls for specified port using the FOSSIL specification.
          This function is passed on to the next driver if the port is not
          active.  Any additional calls to this driver with the specified
          port will also be sent on the next driver or the PC BIOS.  Any
          function not needing a port number, or an active port, will be
          processed by most FOSSIL drivers.  X00 will not process
          "Information" requests if the port requested is not active.

          ONEFOSsil will attempt to flush the buffers before this function
          will return.  ONEFOSsil will return if a timeout occurs, after
          deactivating the port.  This is to help buggy software that
          deactivate the port before all of their "closing" screen has been
          sent.

          NOTICE: At some future date, Ray Gwinn intends to make this
          function identical to the PS/2's function 05h.  Function 1Dh is a
          duplicate of this function.  It is my intention to create a new
          standard that will support this, and permit much better
          communications over all devices available.  I do not; however,
          have any opinion on which call should be made.  The latest X00
          and VX00 still support both functions.

     Function 06h - Raise/lower DTR.

          Input:  AH = 06h
                  AL = DTR state to set
                  DX = Port number

          Output: Nothing

          This function is used to control the DTR signal.  AL is defined
          as follows:

                  00h = lower DTR
                  01h = raise DTR

          No other function (except functions 04h, 1Ch, and 1Fh) will alter
          DTR.

     Function 07h - Return timer tick information.

          Input:  AH = 07h

          Output: AL = Timer tick interrupt number (1Ch or 08h)
                  AH = Approximate interrupts per second (18 on IBM)
                  DX = Approximate number of milliseconds per tick (55)

          This function is used to determine the characteristic of the
          timer tick for the computer.

          The FOSSIL specification says this function is to return the
          interrupt number, not the vector.  However, most FOSSIL's seem to
          return the vector.  ONEFOSsil also returns the vector, 1Ch.

          This function useless today.  I would instead like to see some
          functions that do the timing internally, including calculating
          the time in seconds for the application.  There would need to be
          5 or 6 timers in each port, to allow both BBS's and DOOR software
          to do separate timing.  BBS and DOOR software could use a single
          downward counter/timer for time left on-line, but to actually see
          software implement this would be a miracle.

     Function 08h - Flush output buffer.

          Input:  AH = 08h
                  DX = Port number

          Output: Nothing

          This function is used to wait until all pending output has been
          transmitted.  It does not return until all buffered output has
          been sent.

          This function should be used with care.  Flow control can cause
          the system to hang in a tight un-interruptable loop given the
          right circumstances.

          Note:  X00 executes functions with the interrupt mask set as it
          was when entered.  That is, if X00 is called with interrupts
          masked, interrupts will remain masked during the processing of
          the function.  If this function is called with interrupts masked,
          it may never return.

          ONEFOSsil will not wait indefinitely and always enables
          interrupts.  ONEFOSsil will return if no output has been
          transmitted in the timeout period.  There is no status returned
          to notify the application of this condition.

          ONEFOSsil's deactivate function literally calls this function to
          flush the output buffer.

          It is advised that this function NOT be used due to the problems
          that could arise.  Instead developers are asked to use function
          03h and wait in their own loop while the TSRE bit is clear.  This
          would permit the application to keep an eye on local keyboard
          activity among other things.

     Function 09h - Purge output buffer.

          Input:  AH = 09h
                  DX = Port number

          Output: Nothing

          This function is used to remove any buffered output (transmit)
          data.  Any output data remaining in the output buffer (not
          transmitted yet) is discarded.

     Function 0Ah - Purge input buffer.

          Input:  AH = 0Ah
                  DX = Port number

          Output: Nothing

          This function is used to remove any buffered input (received)
          data.  Any input data which is in the receive buffer is
          discarded.

     Function 0Bh - Transmit no wait.

          Input:  AH = 0Bh
                  AL = Character
                  DX = Port number

          Output: AX = 0001h - Character was buffered for transmission
                     = 0000h - Character was not buffered

          This function performs the same operation as function 01h except
          control is returned even if there is no room in the buffer.

          It is requested that developers use this function for single
          character transmissions.  It is asked that you also look into
          using function 19h which can transmit more than one character at
          a time.

     Function 0Ch - Non-destructive read-ahead (Peek).

          Input:  AH = 0Ch
                  DX = Port number

          Output: AH = 00h if a character is available
                     > 00h if no character is available
                  AL = Next character if available

          This function returns the next character from the receive buffer.
          If the receive buffer is empty, a non zero value is returned in
          AH.  The character returned remains in the receive buffer.  Some
          programmers call this function "peek".

          The extended function 20h is a destructive read without wait.

     Function 0Dh - Keyboard read without wait.

          Input:  AH = 0Dh

          Output: AX = IBM-style scan code if available
                     = 0FFFFh if no character not available

          This function returns the keyboard scan code of the next
          character from the keyboard.  This is a non-destructive (peek)
          read of the keyboard.

          This function should not be used by IBM PC software.

     Function 0Eh - Keyboard read with wait.

          Input:  AH = 0Eh

          Output: AX = Keyboard scan code

          This function returns the next character available from the
          keyboard.  If no keyboard input is available, this function waits
          until a keyboard character is available.  Returned character
          codes are the same as function 0Dh (IBM style scan codes).

          This function should not be used by IBM PC software.

     Function 0Fh - Flow Control for serial I/O.

          Input:  AH = 0Fh
                  AL = Bit defining the flow control to use
                  DX = Port number

          Output: Nothing

          Two kinds of basic flow control are supported.  One is software,
          called Xon/Xoff flow control.  The other is hardware, called
          RTS/CTS flow control.  Both software and hardware flow control
          may be enabled and used at the same time.

          The bits passed in AL are defined as follows:

                  Bit 0 = 1       Enable receiving of Xon/Xoff
                  Bit 1 = 1       Enable RTS/CTS flow control
                  Bit 2           Reserved (should be zero)
                  Bit 3 = 1       Enable transmitting of Xon/Xoff

          The FOSSIL specification states that all other bits should be set
          to 1 for future expansion.  This is insane, as it might enable
          options the application doesn't want.  It is simpler to assume
          that if the bit is not used now, you wont need to use it later
          and leave it cleared.

          ONEFOSsil permits controlling and locking these options on the
          command line.  As such, a request to enable or disable a flow
          control may not be honored.

          Some other FOSSIL drivers automatically lock RTS/CTS if the baud
          rate or data parameters are locked on the command line.

     Function 10h - Control-C/K checking and transmitter control.

          Input:  AH = 10h
                  AL = Control bits (defined below)
                  DX = Port number

          Output: AX = 0001h - A Control-C/K has been received
                     = 0000h - A Control-C/K has not been received

          This is primarily used for BBS operation.  A bit mask is passed
          in AL with the following flags:

                  Bit 0 = 1       Enable Control-C/K checking
                  Bit 1 = 1       Disable the transmitter

          The Control-C/K status is only returned as long as Control-C/K
          checking is enabled.  The status is cleared after each call.

          The transmitter disable bit lets the application program to
          inhibit the transmitter.  FIFO's of 16550's can not be stopped,
          and will continue to transmit until empty.

          The disable of the transmitter is not absolute.  Several internal
          functions can cause the transmitter to be re-enabled, such as
          attempting to store another character in the buffer.  Some
          FOSSIL's will also re-enable the transmitter when they receive an
          Xon, but ONEFOSsil does not.

     Function 11h - Set current cursor location.

          Input:  AH = 11h
                  DH = Row (line)
                  DL = Column

          Output: Nothing

          This function is exactly like INT 10h, subfunction 2, on the IBM
          PC.  The desired cursor location is passed in DX, row in DH and
          column in DL.  The row and column are relative to zero.  That is,
          the home position on the screen is row 0, column 0.

          This function should not be used by IBM PC software.

     Function 12h - Read current cursor location.

          Input:  AH = 12h

          Output: DH = Row (line)
                  DL = Column

          This function is exactly like INT 10h, subfunction 3, on the IBM
          PC.  The current cursor location (using the same coordinate
          system as function 16h) is returned in DX.

          This function should not be used by IBM PC software.

     Function 13h - Single character ANSI write to screen.

          Input:  AH = 13h
                  AL = Character to display

          Output: Nothing

          The character passed in AL is sent displayed on the screen at the
          current cursor location.   ANSI.SYS type processing is performed.
          This routine should not be used in such a way that DOS output
          (which is not re-entrant) can not be employed by the FOSSIL to
          execute the function.

          ANSI.SYS is used by most FOSSIL drivers on the IBM PC.

          This function should not be used on IBM PC software.

     Function 14h - Enable or disable the DCD watchdog.

          Input:  AH = 14h
                  AL = 01h - Enable watchdog
                     = 00h - Disable watchdog
                  DX = Port number

          Output: Nothing

          This function enables and disables the monitoring of carrier
          detect.  When enabled, the state of the carrier detect (DCD) is
          constantly monitored during timer tick processing.  Should
          carrier detect be lost (turned off), the system will be
          re-booted.  Activate/deactivate have no effect on the state of
          the DCD watchdog.

          This function is not supported by ONEFOSsil, and is dangerous in
          many multitasking environments.

     Function 15h - Write character to screen using BIOS.

          Input:  AH = 15h
                  AL = Character to display

          Output: Nothing

          The specified character is sent to the screen using BIOS-level
          input/output routines.  This differs from function 13h in that
          DOS I/O will not be used.

          This function should not be used by IBM PC software.

     Function 16h - Add or delete a routine from the timer tick chain.

          Input:  AH = 16h
                  AL = 01h - Add a function
                     = 00h - Delete a function
                  ES = Segment of function
                  DX = Offset of function

          Output: AX < 0FFFFh if operation is successful
                     = 0FFFFh if operation unsuccessful

          This function is used to allow a central authority to manage the
          timer interrupts, so that the integrity of the "timer tick chain"
          is not compromised.  Rather than using the traditional method of
          saving the old contents of the timer vector, storing the address
          of your routine there, and calling the "old" routine, instead you
          call this function.  The FOSSIL manages a list of such entry
          points and calls them on a timer tick (interrupt) using a FAR
          call.

          X00 will allow up to 4 programs to hook into the timer tick.
          Interrupts are enabled when the hooked routines are called.

          CAUTION:  When this FOSSIL function was implemented, it provided
          the best means to hook into the timer tick on multi-tasking
          systems at that time.  However, with the 80386 and virtual 8086
          mode of operation used by DESQview, Windows V3.0+ etc, this
          function can crash the system.  The reason is the virtual 8086
          application (task/window) that hooked in, may not be the active
          virtual 8086 (task/window) when the timer tick interrupt occurs.

          Due to popularity of the virtual 8086 type multi-tasking systems,
          Ray Gwinn (who originally insisted that this function be created)
          RECOMMENDS THAT THIS FUNCTION NOT BE USED.

          ONEFOSsil returns 0FFFFh in AX at all times.  Happy Ray?

     Function 17h - Reboot system.

          Input:  AH = 17h
                  AL = 00h - "Cold boot"
                     = 01h - "Warm boot"

          Output: Nothing

          This function is intended primarily as a security feature.  It
          provides the application with a last resort escape from a
          situation that could allow a security breach.

          ONEFOSsil attempts to close the task that made the call, rather
          than rebooting what could be a multi-user system.

          This function should not be called by ANY software.

     Function 18h - Block Read.

          Input:  AH = 18h
                  CX = Requested number of characters to transfer
                  DX = Port number
                  ES = Segment of the caller's buffer
                  DI = Offset of the caller's buffer

          Output: AX = Number of characters actually transferred

          This function will transfer from 0 to 65535 characters from the
          inbound circular buffer to the caller's buffer.  ES and DI are
          not modified by this function.  The number of bytes placed in the
          caller's buffer is returned in AX.  The number returned in AX
          will be the lesser of the caller's requested amount or the entire
          contents (if any) of the receive buffer.

          I request that this function be used even for reading a single
          character at a time.  An example is in the application notes.

          This function should especially be used by file transfer protocol
          software.

     Function 19h - Block Write.

          Input:  AH = 19h
                  CX = Requested number of characters to transfer
                  DX = Port number
                  ES = Segment of the caller's buffer
                  DI = Offset of the caller's buffer

          Output: AX = Number of characters actually transferred

          This function will transfer from 0 to 65535 characters to the
          outbound circular buffer.  ES and DI are not modified by this
          function.  The number of bytes placed in the buffer is returned
          in AX.  The number returned in AX will be the lesser of the
          caller's requested amount or the amount (if any) required to fill
          the transmit buffer.

          This function should be used whenever possible!

     Function 1Ah - Break begin or end.

          Input:  AH = 1Ah
                  AL = 01h - Start sending 'break'
                     = 00h - Stop sending 'break'
                  DX = port number

          Output: Nothing

          This function will start or terminate a break signal.  This
          function is useful for activating command mode on some modems.
          The application program is responsible for the timing of the
          BREAK.  If ONEFOSsil has been restrained by an Xoff received from
          the modem, the flag will be cleared.  Any port setting functions
          (including 04h and 1Ch) will stop an in progress break.

          A break must be maintained long enough for the UART to have sent
          a full data byte at the current settings.  A break is a condition
          where the serial line maintains the state of a start bit for a
          full byte (or through the current stop bit.)

     Function 1Bh - Return information about X00.

          Input:  AH = 1Bh
                  CX = Size of caller's info buffer in bytes
                  DX = Port number
                  ES = Segment of caller's info buffer
                  DI = Offset of caller's info buffer

          Output: AX = Number of bytes actually transferred

          X00 returns the following:

                  CX = '0X'       First 2 bytes of 'X00 ' string
                  DX = ' 0'       Second 2 bytes of 'X00 ' string

          ONEFOSsil returns the following:

                  BX = 'ON'       No specific byte ordering, just the word
                  CX = 'E '       "ONE " if you were to look at it in
                                  a register dump.

          This function will transfer information about the selected port
          and its status to the caller.  This function is intended to
          assist "generic" applications to adjust to the current
          environment.

          Very little information should be used from the returned
          information.  An application should NOT use the buffer size or
          buffer free information for anything.  Use function 03h for
          information about the buffers.

          X00 returns the port status (function 03h) if this function is
          called for an inactive port.  BNU and ONEFOSsil return useful
          information if they support the port.

          X00 does not always return the following BAUD byte correctly.
          ONEFOSSIL contains extra fields in the following structure.

          The data structure (assembly language style) currently returned
          by ONEFOSsil is as follows:

             INFO    EQU $              ;DEFINE BEGIN OF STRUCTURE
             STRSIZ  DW  INFO_SIZE      ;SIZE OF THIS STRUC IN BYTES
             MAJVER  DB  CURR_FOSSIL    ;FOSSIL SPECIFICATION REV
             MINVER  DB  CURR_REV       ;REVISION OF THIS DRIVER.
             IDENT   DD  ID_STRING      ;"FAR" POINTER TO ASCIIZ
                                        ; DRIVER DESCRIPTION STRING.
             IBUFR   DW  IBSIZE         ;BYTE SIZE OF THE INPUT BUFFER
             IFREE   DW  ?              ;BYTES OF RECV BUFFER FREE
             OBUFR   DW  OBSIZE         ;BYTE SIZE OF THE XMIT BUFFER
             OFREE   DW  ?              ;BYTES OF XMIT BUFFER FREE
             SWIDTH  DB  SCREEN_WIDTH   ;WIDTH OF DISPLAY SCREEN
             SHEIGHT DB  SCREEN_HEIGHT  ;HEIGHT OF DISPLAY SCREEN
             BAUD    DB  ?              ;BAUD RATE, COMPUTER TO MODEM

                                        ;the follow are extensions

             NEWBAUD DB  ?              ;new baud rate location
             PORTSET DB  ?              ;complete port data settings
             OVERRUN DW  ?              ;number overruns this session

          The IDENT string is null-terminated, and does not contain a
          new-line.  The BAUD field contains the bits that Function 00h
          would use to set the port speed and data format.

          The fields related to a particular port (buffer size, space left
          in the buffer, baud rate) will be undefined if the port is not
          active.

          In some cases X00 can not accurately return information.  For
          example, the user can lock the baud rate at 115200 when loading
          X00.  There is no correct FOSSIL value that X00 can return in the
          BAUD field.  X00 will set the BAUD field equal to the last baud
          rate that the application attempted to set, at least that is what
          X00REF.DOC says.  It has been discovered that this is not true,
          and that most the time, the BAUD field contains no usable data.

          ONEFOSsil always sets the BAUD parameter to the closest possible
          value.  FHSLink really likes this practice, and as such displays
          a baud rate without using the -B parameter.  ONEFOSsil also uses
          the NEWBAUD and PORTSET bytes.  PORTSET is the bits function 1Eh
          would write to the Line Control Register (minus the break bit).
          The NEWBAUD byte contains a value similar to what function 1Eh
          would use to set the baud rate.  These are shown below.

          Values of NEWBAUD:

                  00h = 110       27% error factor on 8250 series
                  01h = 150
                  02h = 300
                  03h = 600
                  04h = 1200
                  05h = 2400
                  06h = 4800
                  07h = 9600
                  08h = 19200
                  09h = 28800
                  0Ah = 38400
                  0Bh = 57600
                  0Ch = 76800     does not exist on 8250 series
                  0Dh = 115200

          Values of PORTSET:

               Bit 7 and 6 are always clear

               Bit 3 is set if parity is enabled
               Bits 5 - 4 define parity:

                  00 = Odd parity
                  01 = Even parity
                  10 = Mark parity (sticky odd)
                  11 = Space parity (sticky even)

               Bit 2 defines the number of stop bits transmitted

                  0 = 1 stop bit sent
                  1 = 1.5 stop bits for 5 bit bytes, 2 for all others

               Bits 1 - 0 define the number of data bits

                  00 = 5 data bits
                  01 = 6 data bits
                  10 = 7 data bits
                  11 = 8 data bits

          The OVERRUN word is solely for information, and are just for this
          session.  It is cleared every time the port is activated.

                               Extended Functions

     Function numbers above 1Bh and below 7Eh are X00 extended functions.
     These functions will only work with X00 and ONEFOSsil.  It is fairly
     easy to see if other FOSSIL's support X00 functions by checking the
     maximum function supported on the "Activate" call.

     It is the hope of Ray Gwinn that these functions will be added by
     other FOSSIL authors in their implementations and become a part of the
     FOSSIL specification.  I would personally like to see a whole new, non
     UART specific specification emerge.  This new specification would get
     rid of the inefficiency FOSSIL 5 permits and clear up some of the
     compatibility issues with the new BIOS's.

     Functions 1Ch and 1Dh are exact duplicates of FOSSIL functions 04h and
     05h.  Functions 1Eh and 1Fh are intended to be exact duplicates of
     functions 04h and 05h of the PS/2's BIOS INT 14h.  Function 20h is a
     destructive read with no wait.  Function 21h is a Stuff/Poke character
     into the receive buffer.

     Developers are encouraged start using functions 1Ch and 1Dh instead of
     functions 04h and 05h.  See the application notes section for
     instructions on a compatible method of determining if functions 1Ch
     and 1Dh should be used instead of functions 04h and 05h.

     Function 1Ch - Activate Port.

          This function is identical to function 04h.  Please refer to
          function 04h for information.

     Function 1Dh - Deactivate Port.

          This function is identical to function 05h.  Please refer to
          function 05h for information.

     Function 1Eh - Extended line control initialization.

          This function is intended to exactly emulate the PS/2's BIOS INT
          14 services, function 04h.  Some or all of the functions provided
          here are duplicated by other FOSSIL functions.  In addition, once
          this function is called, function 00h will not be allowed to
          change the baud rate.  Function 00h will again be allowed to set
          the baud rate after the FOSSIL functions have been deactivated.

          Input:  AH = 1Eh
                  AL = Break, Where:
                     = 00h, No break and/or turn off break
                     = 01h, Start send of break.
                  BH = Parity, where:
                     = 00h, No parity
                     = 01h, Odd parity
                     = 02h, Even parity
                     = 03h, Mark parity (always 1)
                     = 04h, Space parity (always 0)
                  BL = Stop bits, where:
                     = 00h, One bit
                     = 01h, 1.5 bits on 5 bit bytes, 2 stop bits for all others
                  CH = Word length, where:
                     = 00h, 5 bits
                     = 01h, 6 bits
                     = 02h, 7 bits
                     = 03h, 8 bits
                  CL = Baud rate, where:
                     = 00h, 110 baud
                     = 01h, 150 baud
                     = 02h, 300 baud
                     = 03h, 600 baud
                     = 04h, 1200 baud
                     = 05h, 2400 baud
                     = 06h, 4800 baud
                     = 07h, 9600 baud
                     = 08h, 19200 baud
                     = 80h, 28800 baud (these are FOSSIL only baud rates)
                     = 81h, 38400 baud
                     = 82h, 57600 baud
                     = 83h, reserved (future 76800 baud)
                     = 84h, 115200 baud
                  DX = Port number

          Output: AX = Port status (see function 03h)

          If settings were locked at load time, the appropriate parameters
          are ignored.

     Function 1Fh - Extended serial port status/control.

          This function is intended to exactly emulate the PS/2's BIOS INT
          14 services, function 05h.  Some or all of the functions provided
          here are duplicated by other FOSSIL functions.  This function has
          2 subfunctions specified by AL.

          Subfunction 00h - Read MCR

          Input:  AH = 1Fh
                  AL = 00h, Read modem control register (MCR)
                  DX = Port number

          Output: AX = Port status (see function 03h)
                  BL = Modem control register, where:
                       Bits 7-5 = 0 (Reserved) (always 0)
                       Bit 4    = 1 Loopback mode
                       Bit 3    = 1 OUT2 (interrupts) enabled
                       Bit 2    = 1 OUT1 active
                       Bit 1    = 1 Request to send (RTS) active
                       Bit 0    = 1 Data terminal ready (DTR) active

          Subfunction 01h - Write MCR

          Input:  AH = 1Fh
                  AL = 01h, Write modem control register (MCR)
                  BL = Modem control register, where:
                       Bits 7-5 = 0 (Reserved) (forced 0)
                       Bit 4    = 1 Set loopback mode
                       Bit 3    = 1 Set OUT2 enable interrupts (forced 1)
                       Bit 2    = 1 Set OUT1 active (on)
                       Bit 1    = 1 Set Request to send active (on)
                       Bit 0    = 1 Set DTR active (on)
                  DX = Port number

          Output: AX = Port status (see function 03h)

          In subfunction 01h (write MCR) ONEFOSsil will force bit 3 to 1.
          That is, ONEFOSsil will not allow the communications interrupts
          to be disabled.

          RTS may be used as a flow control signal by the FOSSIL.  When the
          application program writes the MCR, the RTS bit is treated as an
          RTS enable bit.  This means that ONEFOSsil will allow the
          application program to signal when it wants to allow RTS on.  It
          does not force RTS on.

     Function 20h - Read with no wait (destructive).

          Input:  AH = 20h
                  DX = Port number

          Output: AH = 00h if a character is available
                     > 00h if no character is available
                  AL = Next character if available

          This function returns the next character from the receive buffer.
          If the receive buffer is empty, a non zero value is returned in
          AH.  This function is the same as function 0Ch except that any
          character returned is removed from the receive buffer.

     Function 21h - Stuff/Poke the receive buffer.

          Input:  AH = 20h
                  AL = Character to place in the receive buffer
                  DX = Port number

          Output: Nothing

          The OVERRUN flag and count will be set if there was no room in
          the receive buffer.

          This function will insert the passed character into the receive
          buffer (at the end).  Subsequent reading of the serial input will
          read the character.  The character is inserted at the end of the
          buffer (as though it were just received.)

          The character is inserted into the receive buffer by calling the
          receive interrupt routine.  All normal receive checking is
          preformed on the character.  Some things to note are:

          If receiving of Xon/Xoff is enabled and an Xoff is stuffed/poked
          into the buffer, the transmitter will stop until a an Xon is
          received or stuffed/poked.

          If Control-C/K checking is enabled and a Control-C/K is
          stuffed/poked, then the character is not put in the buffer and
          the internal flag is set.

                         "Layered Application" services

     ONEFOSsil supports NO "Layered Application" services.  The functions
     simply aren't monitored.  I don't feel most people have any use for
     them.

                               Application Notes

                 Which Activate/Deactivate functions to use

     It is the hope of Ray Gwinn (after a period of time) to make X00's
     functions 04h and 05h compatible with the PS/2's INT 14h functions 04h
     and 05h.  Currently, X00's functions 04h and 05h are duplicated at
     functions 1Ch and 1Dh respectively.  Ray requests that application
     programmers start using functions 1Ch and 1Dh if those functions are
     available.  That is, use functions 1Ch and 1Dh instead of functions
     04h and 05h respectively.

     It is relatively simple to determine if the functions at 1Ch and 1Dh
     are available.  When your program is ready to activate the FOSSIL for
     a given port, issue function 1Ch.  If 1954h is returned, then the port
     is activated.  If 1954h is not returned, reissue the request to
     function 04h.  Save the function number actually used to activate the
     port, then increment it by one to deactivate the port.  You may also
     keep track of the maximum function supported by the driver, to see
     what other calls are available.  You should; however, leave a user
     configured option to override all extended function calls.

     It is possible to get a single character without waiting, even on a non
     extended FOSSIL driver.  The following code shows an example in
     assembly that will perform such a feat, without monitoring the buffer
     status (which is unreliable).

     In ASM

             push    bp            ;save frame pointer
             mov     bp,sp         ;set it
             xor     ax,ax         ;clear temp value
             push    ax            ;temporary storage
             mov     ah,18h        ;function call 18h
             mov     cx,1          ;get 1 byte
             mov     dx,port       ;port number
             lea     di,[bp-2]     ;address of temp storage
             push    ss
             pop     es            ;move registers (size conscious)
             int     14h           ;make call
             or      ax,ax         ;any data moved?
             jnz     @F            ;data was moved
             mov     [bp-1],0FFh   ;write AH to 0xFF
     @@:     pop     ax            ;if AH = 0, AL = character
             pop     bp

     In C/C++

          No real example available as I would use in-line ASM to
          accomplish the function very similar to the above code.  Other
          people would use "regs" and "int86" calls.

     Notice that you could detect if function 20h is available, and use it
     when possible.  FOSSILC, my C/C++ FOSSIL routines (freeware) do
     exactly that.

<EoF>
