home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / GENUTIL / ONEFOS09.ZIP / ONEREF.TXT < prev    next >
Text File  |  1996-06-15  |  50KB  |  1,116 lines
  1.              Functions Reference Manual for the ONEFOSsil Developer
  2.             (C) Copyright 1995-96 by Carl Morris and Morris Softronics
  3.          ONEFOSsil, A low level serial communications driver for MS-DOS
  4.                      based FOSSIL 5 compliant applications.
  5.  
  6.                                   Introduction
  7.  
  8.     This document is for developers wanting to use ONEFOSsil specific
  9.     features and for developers just learning about the FOSSIL
  10.     specification.  ONEFOSsil supports most FOSSIL 5 and X00 extended
  11.     functions, and this document will help describe any differences.
  12.     Portions of this document are copyright by VEP Software, Rick Moore, and
  13.     Raymond Gwinn.  The rest of this document is copyright by Morris
  14.     Softronics and Carl Morris.
  15.  
  16.     This documentation is distributed as is and is provided with no
  17.     guarantees.  You use the information contained within at your own risk.
  18.  
  19.                      What is ONEFOSsil and a FOSSIL driver?
  20.  
  21.     ONEFOSsil is a simplified serial communications driver for 8250 series
  22.     UART's and MS-DOS based machines running applications requiring a simple
  23.     FOSSIL 5 communications driver.  ONEFOSsil only provides FOSSIL based
  24.     services.
  25.  
  26.     FOSSIL is an acronym derived from Fido Opus Seadog Standard Interface
  27.     Layer.  The FOSSIL specification was intended to permit machine
  28.     independent software (Fido, Opus, and Seadog at the time) to be created
  29.     and ran on any MS-DOS based 8086 based computer that had a FOSSIL
  30.     compatible driver.  Those days are much over, and FOSSIL compatible
  31.     drivers are only used as a low level communications interface for
  32.     application software.  A better specification is needed to keep up with
  33.     today's quickly changing world, though.
  34.  
  35.     ONEFOSsil does not maintain total compatibility with the FOSSIL 5
  36.     specification.  These differences will be noted in this document, but
  37.     will seldom cause problems with most modern software.
  38.  
  39.                                    Interface
  40.  
  41.     ONEFOSsil's Application Program Interface is partly based on the PC BIOS
  42.     communications interface.  As such, the driver will be entered with an
  43.     8086 instruction INT 14h.  A function number is passed in 8086 register
  44.     AH and other registers are used as needed.  Return codes from functions
  45.     will very from function to function, and is one of the most confusing
  46.     aspect of FOSSIL programming; they're not logical!
  47.  
  48.     Registers are not modified by ONEFOSsil unless otherwise specified.
  49.     Note that this is not true about all FOSSIL drivers.  While this
  50.     document covers basic FOSSIL functions, some differences will be
  51.     encountered from FOSSIL to FOSSIL.
  52.  
  53.     In most cases, functions will require a port number to operate.  In all
  54.     cases, port numbers are passed in register DX.  Most FOSSIL's only
  55.     support ports 0 - 7.  FOSSIL to DigiBoard converters usually only
  56.     support 0 - 15.  ONEFOSsil supports ports 0 - 63.  Notice that in most
  57.     cases, the port number is one less than the COM port number; but, in
  58.     most FOSSIL's, the port can be specified on any address/irq combination,
  59.     or may not even map to a COM port at all.
  60.  
  61.     As a note to developers, FOSSIL functions should not be called in a way
  62.     that could cause active code to be reentered.  ONEFOSsil and many other
  63.     FOSSIL's are re-entrant, but not to that great of a degree.
  64.  
  65.                                    Detection
  66.     Detecting FOSSIL drivers vary.  The FOSSIL specification states that to
  67.     detect a FOSSIL, one should look at the 6th byte (3rd word) after the
  68.     start of the INT 14h service routine for the word 1954h, followed by a
  69.     byte, the maximum function supported by the FOSSIL driver.  However,
  70.     this is unreliable if other utilities and/or drivers have hooked the INT
  71.     14h interrupt vector since the FOSSIL was loaded.  It is not suggested
  72.     to use this method.  Instead, it is better to just make the call to the
  73.     "Activate" function 04h for the port you want to open and check its
  74.     return codes.  Almost all current applications detect the FOSSIL in this
  75.     way.  Another method, which only works for a few drivers, is to call the
  76.     "Information" function, and check its return codes.  X00 only works
  77.     correctly if the FOSSIL port called is active.  ONEFOSsil and BNU work
  78.     all the time.  Refer to function 1Bh for more information on the
  79.     "Information" function; however, this method is not suggested either.
  80.  
  81.                                    Functions
  82.  
  83.     The following functions are supported by most FOSSIL drivers.
  84.  
  85.     Function 00h - Set communications baud, parity, etc.
  86.  
  87.          Input:
  88.               AH = 00h
  89.               AL = Communications parameters:
  90.                   010----- = 300 baud
  91.                   011----- = 600 baud
  92.                   100----- = 1200 baud
  93.                   101----- = 2400 baud
  94.                   110----- = 4800 baud
  95.                   111----- = 9600 baud
  96.                   000----- = 19200 baud (replaces IBM 110 baud setting)
  97.                   001----- = 38400 baud (replaces IBM 150 baud setting)
  98.                   ----0--- = No parity
  99.                   ---01--- = Odd parity
  100.                   ---11--- = Even parity
  101.                   -----0-- = 1 stop bit;
  102.                   -----1-- = 1½ bits for 5-bit byte length, 2 for all
  103.                              others
  104.                   ------00 = 5 bits
  105.                   ------01 = 6 bits
  106.                   ------10 = 7 bits
  107.                   ------11 = 8 bits
  108.               DX = Port number
  109.               BX = 0 (incase BNU tries to extend this function)
  110.  
  111.          Output:
  112.               AH = Line status (see function 03h)
  113.               AL = Modem status (see function 03h)
  114.  
  115.          This function is identical to the IBM PC INT 14h BIOS call except
  116.          that 110 baud and 150 baud have been replaced by 19200 baud and
  117.          38400 baud respectively.  See function 1Eh for an enhanced version
  118.          of this function.  In addition, once function 1Eh has been used,
  119.          this function will not change the baud rate until function 04h is
  120.          used to reactivate the FOSSIL driver.
  121.  
  122.          Note that BNU contains an extension to this function, and that if
  123.          that extension is not desired you should make sure that BX and CX
  124.          are not equal, or that one of them are zero.  If you would like
  125.          information on this extension please write the author of this
  126.          document or David Nugent, author of BNU.
  127.  
  128.     Function 01h - Transmit character with wait.         Input:
  129.               AH = 01h
  130.               AL = Output character
  131.               DX = Port number
  132.  
  133.          Output:
  134.               AH = Line status (see function 03h)
  135.                   1------- = Time-out occurred, all other bits void
  136.                   0------- = Character buffered, all bits valid
  137.               AL = Modem status (see function 03h, void if time-out
  138.               occurred)
  139.  
  140.          If there is no room in the transmit buffer, this function will wait
  141.          until there is room in the buffer or until a time-out occurs.
  142.  
  143.          Notes:
  144.  
  145.            X00 executes functions with the interrupt mask set as it was
  146.            when entered.  That is, if X00 is called with interrupts masked,
  147.            interrupts will remain masked during the processing of the
  148.            function.  If this function is called with interrupts masked, it
  149.            may never return.
  150.            ONEFOSsil always enables interrupts upon the beginning of every
  151.            FOSSIL call, so unless there are severe hardware problems,
  152.            ONEFOSsil should always return.
  153.            It is suggested that applications use function 0Bh instead of
  154.            this function in all cases.  This function is slow, and X00 and
  155.            BNU are prone to lock-ups.  Even if the THRE bit is set in a
  156.            status return, there is a chance that the buffer could be filled
  157.            by another application between calls, and as such the correct
  158.            application would get a long, unnecessary delay before control
  159.            is returned.
  160.            Many applications do not check the returned status for a time-
  161.            out condition, and as such drop characters when time-outs occur.
  162.  
  163.     Function 02h - Get received character with wait.
  164.  
  165.          Input:
  166.               AH = 02h
  167.               DX = Port number
  168.  
  169.          Output:
  170.               AH = Line status (see function 03h)
  171.                   1------- = Time-out occurred, all other bits void
  172.                   0------- = Character returned, all bits valid
  173.               AL = Input character (if no time-out occurred)
  174.  
  175.          If no character is available from the receive buffer, this function
  176.          will wait until a character is received or until a time-out occurs.
  177.  
  178.          Notes:
  179.  
  180.            X00 executes functions with the interrupt mask set as it was
  181.            when entered.  That is, if X00 is called with interrupts masked,
  182.            interrupts will remain masked during the processing of the
  183.            function.  If this function is called with interrupts masked, it
  184.            may never return.
  185.            ONEFOSsil always enables interrupts upon the beginning of every
  186.            FOSSIL call, so unless there are severe hardware problems,
  187.            ONEFOSsil should always return.
  188.            It is suggested that applications do not use this function.  It
  189.            is slow, and X00 and BNU are prone to lock-ups.  Even if the RDA
  190.            bit is set in a status return, it is possible that another
  191.            application could steal the character, leaving the correct
  192.            application to wait for the next character or a time-out.  It is
  193.            suggested that function 18h be used instead.  Function 18h
  194.            always returns immediately.  Sample code for calling this block
  195.            function in a single character mode can be found in the
  196.            applications notes.  Also, X00 and ONEFOSsil support a "get
  197.            character with no wait" at function 20h, but is not supported by
  198.            the FOSSIL 5 specification or most other FOSSIL's.
  199.  
  200.     Function 03h - Return serial port status.
  201.  
  202.          Input:
  203.               AH = 03h
  204.               DX = Port number
  205.  
  206.          Output:
  207.               AH = Line Status (resembles the 8250 Line Status Register)
  208.                   1------- = time-out, all other bits in AH and AL void*
  209.                   -1------ = TSRE, output buffer is empty*
  210.                   --1----- = THRE, room is available in output buffer*
  211.                   ---1---- = BRK, break detected (since last return)
  212.                   ----1--- = FE, framing error detected (since last return)
  213.                   -----1-- = PE, parity error detected (since last return)
  214.                   ------1- = OE, the input buffer has overrun (since last
  215.                              return)*
  216.                   -------1 = RDA, received data is available in buffer*
  217.               AL = Modem Status (resembles the 8250 Modem Status Register)
  218.                   1------- = Data carrier detect (DCD)*
  219.                   -1------ = Ring indicator (RI)
  220.                   --1----- = Data set ready (DSR)
  221.                   ---1---- = Clear to send (CTS)
  222.                   ----1--- = Always set to 1 upon return (dummy DCD)*
  223.                   ----1--- = Delta data carrier detect (since last return)
  224.                   -----1-- = Trailing edge ring indicator (since last
  225.                              return)
  226.                   ------1- = Delta data set ready (since last return)
  227.                   -------1 = Delta clear to send (since last return)
  228.  
  229.          * Denotes formal FOSSIL 5 specified bits.
  230.  
  231.          The FOSSIL specification calls for the delta data carrier detect
  232.          bit to always be set to act as a dummy DCD.  If an application
  233.          needs a dummy DCD, it should implement it internally as described
  234.          in the notes below.  As such ONEFOSsil does not support it and
  235.          instead uses the bit as a Delta Data Carrier Detect.  ONEFOSsil
  236.          instead includes a command line option to fake Data Carrier Detect.
  237.  
  238.          Notes:
  239.  
  240.            All bits without asterisks (*) will vary in meaning from FOSSIL
  241.            to FOSSIL driver.
  242.            X00 does not attempt to accurately return the Delta bits.
  243.            ONEFOSsil should correctly return the status of the Delta bits.
  244.            One way to implement a dummy DCD is to check the DCD at the
  245.            start of the connection.  If DCD is active, the real DCD should
  246.            be watched.  If DCD is inactive, it should be assumed that there
  247.            might never be a DCD, and assume an internal dummy DCD.  If DCD
  248.            was to go active at some later time, real DCD watching should be
  249.            re-enabled and used from there out.  However, with ONEFOSsil
  250.            supporting command line options for faking DCD, it is not
  251.            suggested to follow the above practice.
  252.  
  253.     Function 04h - Activate Port.
  254.  
  255.          Input:
  256.               AH = 04h
  257.               BX = 0h (in case the FOSSIL supports Control-C flagging)
  258.               DX = Port number
  259.  
  260.          Output:
  261.               AX = 1954h if successful
  262.               BL = Maximum function number supported
  263.               BH = Revision of FOSSIL specification supported
  264.  
  265.          This function instructs the FOSSIL driver to initialize itself for
  266.          communications on the specified port.  Buffers will be cleared,
  267.          interrupts activated, and DTR raised.  If the port can not be
  268.          supported, the call goes to the next driver or to the system BIOS.
  269.  
  270.          The FOSSIL specification states that the port parameters are not to
  271.          be initialized at this time.  However, with ONEFOSsil, if port
  272.          parameters have been locked on the command line, they will be
  273.          loaded during this time.
  274.  
  275.          The FOSSIL specification calls for an optional Control-C flag, and
  276.          is not supported by X00 or ONEFOSsil.  As such, BX should be
  277.          cleared to prevent any possibility of this occurring.
  278.  
  279.          X00 incorrectly returns the maximum function number (or it isn't
  280.          documented.)  BNU and ONEFOSsil will only return the maximum
  281.          function (currently 20h in ONEFOSsil.)  BNU has an option to be
  282.          compatible with the bug X00 has also.
  283.  
  284.          Multiple calls to this function will repeat the above process as
  285.          if the port had not been open.  If you want to insure the port is
  286.          closed before opening, call function 05h first (many BBS's and
  287.          doors do this.)
  288.  
  289.          Notes:
  290.  
  291.            At some future date, Ray Gwinn intends to make this function
  292.            identical to the PS/2's function 04h.  Function 1Ch is a
  293.            duplicate of this function.  It is my intention to create a new
  294.            standard that will support this, and permit much better
  295.            communications over all devices available.  I do not; however,
  296.            have any opinion on which call should be made.  The latest X00
  297.            and VX00 still support both functions.
  298.            Calling this function with an invalid port number will not
  299.            return a valid reponse.  Any application which calls this
  300.            function with port number 255 is in error!
  301.  
  302.     Function 05h - Deactivate Port.
  303.  
  304.          Input: AH = 05h
  305.                 DX = Port number
  306.  
  307.          Output:   Nothing
  308.  
  309.          This function instructs the FOSSIL that it should no longer process
  310.          calls for specified port using the FOSSIL specification.  This
  311.          function is passed on to the next driver if the port is not active.
  312.          Any additional calls to this driver with the specified port will
  313.          also be sent on the next driver or the PC BIOS.  Any function not
  314.          needing a port number, or an active port, will be processed by most
  315.          FOSSIL drivers.  X00 will not process "Information" requests if the
  316.          port requested is not
  317.          active.
  318.  
  319.          ONEFOSsil will attempt to flush the buffers before this function
  320.          will return.  ONEFOSsil will return if a time-out occurs, after
  321.          deactivating the port.  This is to help buggy software that
  322.          deactivate the port before all of their "closing" screen has been
  323.          sent.  It should be assumed however that what is in the transmit
  324.          buffer will be lost when this function is called.
  325.  
  326.          NOTICE:  With Revision 9, ONEFOSsil will nolonger flush the port.
  327.          This created an extra long delay under some circuimstances, and if
  328.          application authors can't get it right on their own, ONEFOSsil
  329.          isn't going to cover up for them.
  330.  
  331.          NOTICE: At some future date, Ray Gwinn intends to make this
  332.          function identical to the PS/2's function 05h.  Function 1Dh is a
  333.          duplicate of this function.  It is my intention to create a new
  334.          standard that will support this, and permit much better
  335.          communications over all devices available.  I do not; however, have
  336.          any opinion on which call should be made.  The latest X00 and VX00
  337.          still support both functions.
  338.  
  339.     Function 06h - Raise/lower DTR.
  340.  
  341.          Input: AH = 06h
  342.                 AL = DTR state to set
  343.                 DX = Port number
  344.  
  345.          Output:   Nothing
  346.  
  347.          This function is used to control the DTR signal.  AL is defined as
  348.          follows:
  349.  
  350.                 00h = lower DTR
  351.                 01h = raise DTR
  352.  
  353.          With ONEFOSsil and most other FOSSILs, any even value will lower
  354.          the DTR, any odd value will raise the DTR.
  355.  
  356.          No other function (except functions 04h, 1Ch, and 1Fh) will alter
  357.          DTR.
  358.  
  359.     Function 07h - Return timer tick information.
  360.  
  361.          Input: AH = 07h
  362.  
  363.          Output:   AL = Timer tick interrupt number (1Ch or 08h)
  364.                 AH = Approximate interrupts per second (18 on IBM)
  365.                 DX = Approximate number of milliseconds per tick (55)
  366.  
  367.          This function is used to determine the characteristic of the timer
  368.          tick for the computer.
  369.  
  370.          The FOSSIL specification says this function is to return the
  371.          interrupt number, not the vector.  However, most FOSSIL's seem to
  372.          return the vector.  ONEFOSsil also returns the vector, 1Ch.
  373.  
  374.          This function useless today.  I would instead like to see some
  375.          functions that do the timing internally, including calculating the
  376.          time in seconds for the application.  There would need to be 5 or 6
  377.          timers in each port, to allow both BBS's and DOOR software to do
  378.          separate timing.  BBS and DOOR software could use a single downward
  379.          counter/timer for time left on-line, but to actually see software
  380.          implement this would be a miracle.
  381.  
  382.     Function 08h - Flush output buffer.
  383.  
  384.          Input: AH = 08h
  385.                 DX = Port number
  386.  
  387.          Output:   Nothing
  388.  
  389.          This function is used to wait until all pending output has been
  390.          transmitted.  It does not return until all buffered output has been
  391.          sent.
  392.  
  393.          This function should be used with care.  Flow control can cause the
  394.          system to hang in a tight un-interruptible loop given the right
  395.          circumstances.
  396.  
  397.          Note:  X00 executes functions with the interrupt mask set as it was
  398.          when entered.  That is, if X00 is called with interrupts masked,
  399.          interrupts will remain masked during the processing of the
  400.          function.  If this function is called with interrupts masked, it
  401.          may never return.
  402.  
  403.          ONEFOSsil will not wait indefinitely and always enables interrupts.
  404.          ONEFOSsil will return if no output has been transmitted in the
  405.          time-out period.  There is no status returned to notify the
  406.          application of this condition.
  407.  
  408.          ONEFOSsil's deactivate function literally calls this function to
  409.          flush the output buffer.
  410.  
  411.          It is advised that this function NOT be used due to the problems
  412.          that could arise.  Instead developers are asked to use function 03h
  413.          and wait in their own loop while the TSRE bit is clear.  This would
  414.          permit the application to keep an eye on local keyboard activity
  415.          among other things.
  416.  
  417.     Function 09h - Purge output buffer.
  418.  
  419.          Input: AH = 09h
  420.                 DX = Port number
  421.  
  422.          Output:   Nothing
  423.  
  424.          This function is used to remove any buffered output (transmit)
  425.          data.  Any output data remaining in the output buffer (not
  426.          transmitted yet) is discarded.
  427.  
  428.     Function 0Ah - Purge input buffer.
  429.  
  430.          Input: AH = 0Ah
  431.                 DX = Port number
  432.  
  433.          Output:   Nothing
  434.  
  435.          This function is used to remove any buffered input (received) data.
  436.          Any input data which is in the receive buffer is discarded.
  437.  
  438.     Function 0Bh - Transmit no wait.
  439.  
  440.          Input: AH = 0Bh
  441.                 AL = Character
  442.                 DX = Port number
  443.  
  444.          Output:   AX > 0000h - Character was buffered for transmission
  445.                    = 0000h - Character was not buffered
  446.  
  447.          This function performs the same operation as function 01h except
  448.          control is returned even if there is no room in the buffer.
  449.  
  450.          It is requested that developers use this function for single
  451.          character transmissions.  It is asked that you also look into using
  452.          function 19h which can transmit more than one character at a time.
  453.     Function 0Ch - Non-destructive read-ahead (Peek).
  454.  
  455.          Input: AH = 0Ch
  456.                 DX = Port number
  457.  
  458.          Output:   AH = 00h if a character is available
  459.                    > 00h if no character is available
  460.                 AL = Next character if available
  461.  
  462.          This function returns the next character from the receive buffer.
  463.          The character returned remains in the receive buffer.  Some
  464.          programmers call this function "peek".
  465.  
  466.          The extended function 20h is a destructive read without wait.
  467.  
  468.     Function 0Dh - Keyboard peek without wait.
  469.  
  470.          Input: AH = 0Dh
  471.  
  472.          Output:   AX = IBM-style scan code if available
  473.                    = 0FFFFh if no character is available
  474.  
  475.          This function returns the keyboard scan code of the next character
  476.          from the keyboard.  This is a non-destructive (peek) read of the
  477.          keyboard.
  478.  
  479.          This function should not be used by IBM PC software.
  480.  
  481.     Function 0Eh - Keyboard read with wait.
  482.  
  483.          Input: AH = 0Eh
  484.  
  485.          Output:   AX = Keyboard scan code
  486.  
  487.          This function returns the next character available from the
  488.          keyboard.  If no keyboard input is available, this function waits
  489.          until a keyboard character is available.  Returned character codes
  490.          are the same as function 0Dh (IBM style scan codes).
  491.  
  492.          This function should not be used by IBM PC software.
  493.  
  494.     Function 0Fh - Flow Control for serial I/O.
  495.  
  496.          Input: AH = 0Fh
  497.                 AL = Bit defining the flow control to use
  498.                 DX = Port number
  499.  
  500.          Output:   Nothing
  501.  
  502.          Two kinds of basic flow control are supported.  One is software,
  503.          called Xon/Xoff flow control.  The other is hardware, called
  504.          RTS/CTS flow control.  Both software and hardware flow control may
  505.          be enabled and used at the same time.
  506.  
  507.          The bits passed in AL are defined as follows:
  508.  
  509.                 Bit 0 = 1    Enable receiving of Xon/Xoff
  510.                 Bit 1 = 1    Enable RTS/CTS flow control
  511.                 Bit 2        Reserved (should be zero)
  512.                 Bit 3 = 1    Enable transmitting of Xon/Xoff
  513.  
  514.          The FOSSIL specification states that all other bits should be set
  515.          to 1 for future expansion.  This is insane, as it might enable
  516.          options the application doesn't want.  It is simpler to assume that
  517.          if the bit is not used now, you wont need to use it later and leave
  518.          it cleared.
  519.  
  520.          ONEFOSsil permits controlling and locking these options on the
  521.          command line.  As such, a request to enable or disable a flow
  522.          control may not be honored.
  523.  
  524.          Some other FOSSIL drivers automatically lock RTS/CTS if the baud
  525.          rate or data parameters are locked on the command line.
  526.  
  527.     Function 10h - Control-C/K checking and transmitter control.
  528.  
  529.          Input: AH = 10h
  530.                 AL = Control bits (defined below)
  531.                 DX = Port number
  532.  
  533.          Output:   AX = 0001h - A Control-C/K has been received
  534.                    = 0000h - A Control-C/K has not been received
  535.  
  536.          This is primarily used for BBS operation.  A bit mask is passed in
  537.          AL with the following flags:
  538.  
  539.                 Bit 0 = 1    Enable Control-C/K checking
  540.                 Bit 1 = 1    Disable the transmitter
  541.  
  542.          The Control-C/K status is only returned as long as Control-C/K
  543.          checking is enabled.  The status is cleared after each call.
  544.  
  545.          The transmitter disable bit lets the application program inhibit
  546.          the transmitter.  FIFO's of 16550's can not be stopped, and will
  547.          continue to transmit until empty.
  548.  
  549.          The disable of the transmitter is not absolute.  Several internal
  550.          functions can cause the transmitter to be re-enabled, such as
  551.          attempting to store another character in the buffer.  Some FOSSIL's
  552.          will also re-enable the transmitter when they receive an Xon, but
  553.          ONEFOSsil does not.
  554.  
  555.     Function 11h - Set current cursor location.
  556.  
  557.          Input: AH = 11h
  558.                 DH = Row (line)
  559.                 DL = Column
  560.  
  561.          Output:   Nothing
  562.  
  563.          This function is exactly like INT 10h, sub-function 2, on the IBM
  564.          PC.  The row and column are relative to zero.  That is, the home
  565.          position on the screen is row 0, column 0.
  566.  
  567.          This function should not be used by IBM PC software.
  568.  
  569.     Function 12h - Read current cursor location.
  570.  
  571.          Input: AH = 12h
  572.  
  573.          Output:   DH = Row (line)
  574.                 DL = Column
  575.  
  576.          This function is exactly like INT 10h, sub-function 3, on the IBM
  577.          PC.  The current cursor location (using the same coordinate system
  578.          as function 16h) is returned in DX.
  579.  
  580.          This function should not be used by IBM PC software.
  581.  
  582.     Function 13h - Single character ANSI write to screen.
  583.  
  584.          Input: AH = 13h
  585.                 AL = Character to display
  586.  
  587.          Output:   Nothing
  588.  
  589.          The character passed in AL is sent displayed on the screen at the
  590.          current cursor location.   ANSI.SYS type processing is performed.
  591.          This routine should not be used in such a way that DOS output
  592.          (which is not re-entrant) can not be employed by the FOSSIL to
  593.          execute the function.
  594.  
  595.          ANSI.SYS is used by most FOSSIL drivers on the IBM PC.
  596.  
  597.          This function should not be used on IBM PC software.
  598.  
  599.     Function 14h - Enable or disable the DCD watchdog.
  600.  
  601.          Input: AH = 14h
  602.                 AL = 01h - Enable watchdog
  603.                    = 00h - Disable watchdog
  604.                 DX = Port number
  605.  
  606.          Output:   Nothing
  607.  
  608.          This function enables and disables the monitoring of carrier
  609.          detect.  When enabled, the state of the carrier detect (DCD) is
  610.          constantly monitored during timer tick processing.  Should carrier
  611.          detect be lost (turned off), the system will be re-booted.
  612.          Activate/deactivate have no effect on the state of the DCD
  613.          watchdog.
  614.  
  615.          This function is not supported by ONEFOSsil, and is dangerous in
  616.          many multitasking environments.
  617.  
  618.     Function 15h - Write character to screen using BIOS.
  619.  
  620.          Input: AH = 15h
  621.                 AL = Character to display
  622.  
  623.          Output:   Nothing
  624.  
  625.          The specified character is sent to the screen using BIOS-level
  626.          input/output routines.  This differs from function 13h in that DOS
  627.          I/O will not be used.
  628.  
  629.          This function should not be used by IBM PC software.
  630.  
  631.     Function 16h - Add or delete a routine from the timer tick chain.
  632.  
  633.          Input: AH = 16h
  634.                 AL = 01h - Add a function
  635.                    = 00h - Delete a function
  636.                 ES = Segment of function
  637.                 DX = Offset of function
  638.  
  639.          Output:   AX < 0FFFFh if operation is successful
  640.                    = 0FFFFh if operation unsuccessful
  641.  
  642.          This function is used to allow a central authority to manage the
  643.          timer interrupts, so that the integrity of the "timer tick chain"
  644.          is not compromised.  Rather than using the traditional method of
  645.          saving the old contents of the timer vector, storing the address of
  646.          your routine there, and calling the "old" routine, instead you call
  647.          this function.  The FOSSIL manages a list of such entry points and
  648.          calls them on a timer tick (interrupt) using a FAR call.
  649.  
  650.          X00 will allow up to 4 programs to hook into the timer tick.
  651.          Interrupts are enabled when the hooked routines are called.
  652.  
  653.          CAUTION:  When this FOSSIL function was implemented, it provided
  654.          the best means to hook into the timer tick on multitasking systems
  655.          at that time.  However, with the 80386 and virtual 8086 mode of
  656.          operation used by DESQview, Windows V3.0+ etc., this function can
  657.          crash the system.  The reason is the virtual 8086 application
  658.          (task/window) that hooked in, may not be the active virtual 8086
  659.          (task/window) when the timer tick interrupt occurs.
  660.  
  661.          Due to popularity of the virtual 8086 type multi-tasking systems,
  662.          Ray Gwinn (who originally insisted that this function be created)
  663.          RECOMMENDS THAT THIS FUNCTION NOT BE USED.
  664.  
  665.          ONEFOSsil returns 0FFFFh in AX at all times.  Happy Ray?
  666.  
  667.     Function 17h - Reboot system.
  668.  
  669.          Input: AH = 17h
  670.                 AL = 00h - "Cold boot"
  671.                    = 01h - "Warm boot"
  672.  
  673.          Output:   Nothing
  674.  
  675.          This function is intended primarily as a security feature.  It
  676.          provides the application with a last resort escape from a situation
  677.          that could allow a security breach.
  678.  
  679.          ONEFOSsil attempts to close the task that made the call, rather
  680.          than rebooting what could be a multi-user system.
  681.  
  682.          This function should not be called by ANY software.
  683.  
  684.     Function 18h - Block Read.
  685.  
  686.          Input: AH = 18h
  687.                 CX = Requested number of characters to transfer
  688.                 DX = Port number
  689.                 ES = Segment of the caller's buffer
  690.                 DI = Offset of the caller's buffer
  691.  
  692.          Output:   AX = Number of characters actually transferred
  693.  
  694.          This function will transfer from 0 to 65535 characters from the
  695.          inbound circular buffer to the caller's buffer.  ES and DI are not
  696.          modified by this function.  The number returned in AX will be the
  697.          lesser of the caller's requested amount or the entire contents (if
  698.          any) of the receive buffer.
  699.  
  700.          I request that this function be used even for reading a single
  701.          character at a time.  The following examples to help:
  702.  
  703.          In ASM
  704.  
  705.               push bp        ;save frame pointer
  706.               mov  bp,sp          ;set it
  707.               xor  ax,ax          ;clear temp. value
  708.               push ax        ;temporary storage
  709.               mov  ah,18h    ;function call 18h
  710.               mov  cx,1      ;get 1 byte
  711.               mov  dx,port   ;port number
  712.               lea  di,[bp-2] ;address of temp. storage
  713.               push ss
  714.               pop  es        ;move registers (size conscious)
  715.               int  14h       ;make call
  716.               or   ax,ax          ;any data moved?
  717.               jnz  @F        ;data was moved
  718.               mov  [bp-1],0FFh    ;write AH to 0xFF
  719.          @@:  pop  ax        ;if AH = 0, AL = character
  720.               pop  bp
  721.  
  722.          In C/C++
  723.  
  724.               No real example available as I would use in-line ASM to
  725.               accomplish the function very similar to the above code.  Other
  726.               people would use "regs" and "int86" calls.
  727.  
  728.          Notice that you could detect if function 20h is available, and use
  729.          it when possible.  FOSSILC, my C/C++ FOSSIL routines (freeware) do
  730.          exactly that.
  731.  
  732.          This function should especially be used by file transfer protocol
  733.          software.
  734.  
  735.     Function 19h - Block Write.
  736.  
  737.          Input: AH = 19h
  738.                 CX = Requested number of characters to transfer
  739.                 DX = Port number
  740.                 ES = Segment of the caller's buffer
  741.                 DI = Offset of the caller's buffer
  742.  
  743.          Output:   AX = Number of characters actually transferred
  744.  
  745.          This function will transfer from 0 to 65535 characters to the
  746.          outbound circular buffer.  ES and DI are not modified by this
  747.          function.  The number returned in AX will be the lesser of the
  748.          caller's requested amount or the amount (if any) required to fill
  749.          the transmit buffer.
  750.  
  751.          This function should be used whenever possible!
  752.  
  753.     Function 1Ah - Break begin or end.
  754.  
  755.          Input: AH = 1Ah
  756.                 AL = 01h - Start sending 'break'
  757.                    = 00h - Stop sending 'break'
  758.                 DX = port number
  759.  
  760.          Output:   Nothing
  761.  
  762.          This function will start or terminate a break signal.  This
  763.          function is useful for activating command mode on some modems.  The
  764.          application program is responsible for the timing of the BREAK.  If
  765.          ONEFOSsil has been restrained by an Xoff received from the modem,
  766.          the flag will be cleared.  Any port setting functions (including
  767.          04h and 1Ch) will stop an in progress break.
  768.  
  769.          A break must be maintained long enough for the UART to have sent a
  770.          full data byte at the current settings.  A break is a condition
  771.          where the serial line maintains the state of a start bit for a full
  772.          byte length.
  773.  
  774.     Function 1Bh - Return information about FOSSIL.
  775.  
  776.          Input: AH = 1Bh
  777.                 CX = Size of caller's info buffer in bytes
  778.                 DX = Port number
  779.                 ES = Segment of caller's info buffer
  780.                 DI = Offset of caller's info buffer
  781.  
  782.          Output:   AX = Number of bytes actually transferred
  783.  
  784.          X00 returns the following:
  785.  
  786.                 CX = '0X'    First 2 bytes of 'X00 ' string
  787.                 DX = ' 0'    Second 2 bytes of 'X00 ' string
  788.  
  789.          ONEFOSsil returns the following:
  790.  
  791.                 BX = 'ON'    No specific byte ordering, just the word
  792.                 CX = 'E '    "ONE " if you were to look at it in a register
  793.                              dump.
  794.  
  795.          This function will transfer information about the selected port and
  796.          its status to the caller.  This function is intended to assist
  797.          "generic" applications to adjust to the current environment.
  798.  
  799.          Very little information should be used from the returned
  800.          information.  An application should NOT use the buffer size or
  801.          buffer free information for anything.  Use function 03h for
  802.          information about the buffers.
  803.  
  804.          X00 returns the port status (function 03h) if this function is
  805.          called for an inactive port.  BNU and ONEFOSsil return useful
  806.          information if they support the port.
  807.  
  808.          X00 does not always return the following BAUD byte correctly.
  809.          ONEFOSsil contains extra fields in the following structure.
  810.  
  811.          The data structure (assembly language style) currently returned by
  812.          ONEFOSsil is as follows:
  813.  
  814.               INFO   EQU  $            ;DEFINE BEGIN OF STRUCTURE
  815.               STRSIZ DW   INFO_SIZE    ;SIZE OF THIS STRUC IN BYTES
  816.               MAJVER DB   CURR_FOSSIL  ;FOSSIL SPECIFICATION REV
  817.               MINVER DB   CURR_REV     ;REVISION OF THIS DRIVER.
  818.               IDENT  DD   ID_STRING    ;"FAR" POINTER TO ASCIIZ
  819.                                        ; DRIVER DESCRIPTION STRING.
  820.               IBUFR  DW   IBSIZE       ;BYTE SIZE OF THE INPUT BUFFER
  821.               IFREE  DW   ?            ;BYTES OF RECV BUFFER FREE
  822.               OBUFR  DW   OBSIZE       ;BYTE SIZE OF THE XMIT BUFFER
  823.               OFREE  DW   ?            ;BYTES OF XMIT BUFFER FREE
  824.               SWIDTH DB   SCREEN_WIDTH ;WIDTH OF DISPLAY SCREEN
  825.               SHEIGHT DB  CREEN_HEIGHT ;HEIGHT OF DISPLAY SCREEN
  826.               BAUD   DB   ?            ;BAUD RATE, COMPUTER TO MODEM
  827.  
  828.                                        ;the follow are extensions
  829.  
  830.               NEWBAUD     DB           ?    ;new baud rate location
  831.               PORTSET     DB           ?    ;complete port data settings
  832.               OVERRUN     DW           ?    ;number overruns this session
  833.  
  834.          The IDENT string is null-terminated, and does not contain a new-
  835.          line.  The BAUD field contains the bits that Function 00h would use
  836.          to set the port speed and data format.
  837.  
  838.          The fields related to a particular port (buffer size, space left in
  839.          the buffer, baud rate) will be undefined if the port is not active.
  840.          In some cases X00 can not accurately return information.  For
  841.          example, the user can lock the baud rate at 115200 when loading
  842.          X00.  There is no correct FOSSIL value that X00 can return in the
  843.          BAUD field.  X00 will set the BAUD field equal to the last baud
  844.          rate that the application attempted to set, at least that's what
  845.          X00REF.DOC says.  It has been discovered that this is not true, and
  846.          that most the time, the BAUD field contains no usable data.
  847.  
  848.          ONEFOSsil always sets the BAUD parameter to the closest possible
  849.          value.  FHSLink really likes this practice, and as such displays a
  850.          baud rate without using the -B parameter.  ONEFOSsil also uses the
  851.          NEWBAUD and PORTSET bytes.  PORTSET is the bits function 1Eh would
  852.          write to the Line Control Register (minus the break bit).  The
  853.          NEWBAUD byte contains a value similar to what function 1Eh would
  854.          use to set the baud rate.  These are shown below.
  855.  
  856.          Values of NEWBAUD:
  857.  
  858.                 00h = 110    27% error factor on 8250 series
  859.                 01h = 150
  860.                 02h = 300
  861.                 03h = 600
  862.                 04h = 1200
  863.                 05h = 2400
  864.                 06h = 4800
  865.                 07h = 9600
  866.                 08h = 19200
  867.                 09h = 28800
  868.                 0Ah = 38400
  869.                 0Bh = 57600
  870.                 0Ch = 76800  does not exist on 8250 series
  871.                 0Dh = 115200
  872.  
  873.          Values of PORTSET:
  874.  
  875.               Bit 7 and 6 are always clear
  876.  
  877.               Bit 3 is set if parity is enabled
  878.  
  879.               Bits 5 - 4 define parity:
  880.  
  881.                    00 = Odd parity
  882.                    01 = Even parity
  883.                    10 = Mark parity (sticky odd)
  884.                    11 = Space parity (sticky even)
  885.  
  886.               Bit 2 defines the number of stop bits transmitted
  887.  
  888.                    0 = 1 stop bit sent
  889.                    1 = 1.5 stop bits for 5 bit bytes, 2 for all others
  890.  
  891.               Bits 1 - 0 define the number of data bits
  892.  
  893.                    00 = 5 data bits
  894.                    01 = 6 data bits
  895.                    10 = 7 data bits
  896.                    11 = 8 data bits
  897.  
  898.          The OVERRUN word is solely for information.
  899.  
  900.     Extended Functions
  901.  
  902.     Function numbers above 1Bh and below 7Eh are X00 extended functions.
  903.     These functions will only work with X00 and ONEFOSsil.  It is fairly
  904.     easy to see if other FOSSIL's support X00 functions by checking the
  905.     maximum function supported on the "Activate" call.
  906.  
  907.     It is the hope of Ray Gwinn that these functions will be added by other
  908.     FOSSIL authors in their implementations and become a part of the FOSSIL
  909.     specification.  I would personally like to see a whole new, non UART
  910.     specific specification emerge.  This new specification would get rid of
  911.     the inefficiency FOSSIL 5 permits and clear up some of the compatibility
  912.     issues with the new BIOS's.
  913.  
  914.     Functions 1Ch and 1Dh are exact duplicates of FOSSIL functions 04h and
  915.     05h.  Functions 1Eh and 1Fh are intended to be exact duplicates of
  916.     functions 04h and 05h of the PS/2's BIOS INT 14h.  Function 20h is a
  917.     destructive read with no wait.  Function 21h is a Stuff/Poke character
  918.     into the receive buffer.  Note that function 1Eh or 1Fh are not exactly
  919.     compatible with functions 04h and 05h of the PS/2 BIOS.
  920.  
  921.     Developers are encouraged start using functions 1Ch and 1Dh instead of
  922.     functions 04h and 05h.  See the application notes section for
  923.     instructions on a compatible method of determining if functions 1Ch and
  924.     1Dh should be used instead of functions 04h and 05h.
  925.  
  926.     Function 1Ch - Activate Port.
  927.  
  928.          This function is identical to function 04h.  Please refer to
  929.          function 04h for information.
  930.  
  931.     Function 1Dh - Deactivate Port.
  932.  
  933.          This function is identical to function 05h.  Please refer to
  934.          function 05h for information.
  935.  
  936.     Function 1Eh - Extended line control initialization.
  937.  
  938.          This function is intended to exactly emulate the PS/2's BIOS INT 14
  939.          services, function 04h.  Some or all of the functions provided here
  940.          are duplicated by other FOSSIL functions.  In addition, once this
  941.          function is called, function 00h will not be allowed to change the
  942.          baud rate.  Function 00h will again be allowed to set the baud rate
  943.          after the FOSSIL functions have been deactivated.
  944.  
  945.          Input: AH = 1Eh
  946.                 AL = Break, Where:
  947.                    = 00h, No break and/or turn off break
  948.                    = 01h, Start send of break.
  949.                 BH = Parity, where:
  950.                    = 00h, No parity
  951.                    = 01h, Odd parity
  952.                    = 02h, Even parity
  953.                    = 03h, Mark parity (always 1)
  954.                    = 04h, Space parity (always 0)
  955.                 BL = Stop bits, where:
  956.                    = 00h, One bit
  957.                    = 01h, 1.5 bits on 5 bit bytes, 2 stop bits for all
  958.          others
  959.                 CH = Word length, where:
  960.                    = 00h, 5 bits
  961.                    = 01h, 6 bits
  962.                    = 02h, 7 bits
  963.                    = 03h, 8 bits
  964.                 CL = Baud rate, where:
  965.                    = 00h, 110 baud
  966.                    = 01h, 150 baud
  967.                    = 02h, 300 baud
  968.                    = 03h, 600 baud
  969.                    = 04h, 1200 baud
  970.                    = 05h, 2400 baud
  971.                    = 06h, 4800 baud
  972.                    = 07h, 9600 baud
  973.                    = 08h, 19200 baud
  974.                    = 80h, 28800 baud (these are FOSSIL only baud rates)
  975.                    = 81h, 38400 baud
  976.                    = 82h, 57600 baud
  977.                    = 83h, reserved (future 76800 baud)
  978.                    = 84h, 115200 baud
  979.                 DX = Port number
  980.  
  981.          Output:   AX = Port status (see function 03h)
  982.  
  983.          If settings were locked at load time, the appropriate parameters
  984.          are ignored.
  985.  
  986.          ONEFOSsil does not permit the break bit to be set by this function.
  987.          The value in AL is ignored.  The reason is that the PS/2
  988.          specification calls for a value of 0 to make a break and a 1 to
  989.          clear a break.  X00REF.DOC states the function as it appear above,
  990.          but the Interrupt shows it as being an exact duplicate of the PS/2
  991.          function.  I do not wish to trouble myself with programs that fail
  992.          to work because their authors used the Interrupt List to write
  993.          them.
  994.  
  995.     Function 1Fh - Extended serial port status/control.
  996.  
  997.          This function is intended to exactly emulate the PS/2's BIOS INT 14
  998.          services, function 05h.  Some or all of the functions provided here
  999.          are duplicated by other FOSSIL functions.  This function has 2 sub-
  1000.          functions specified by AL.
  1001.  
  1002.          Sub-function 00h - Read MCR
  1003.  
  1004.          Input: AH = 1Fh
  1005.                 AL = 00h, Read modem control register (MCR)
  1006.                 DX = Port number
  1007.  
  1008.          Output:   AX = Port status (see function 03h)
  1009.                 BL = Modem control register, where:
  1010.                      Bits 7-5 = 0 (Reserved) (always 0)
  1011.                      Bit 4    = 1 Loopback mode
  1012.                      Bit 3    = 1 OUT2 (interrupts) enabled
  1013.                      Bit 2    = 1 OUT1 active
  1014.                      Bit 1    = 1 Request to send (RTS) active
  1015.                      Bit 0    = 1 Data terminal ready (DTR) active
  1016.  
  1017.          Sub-function 01h - Write MCR
  1018.  
  1019.          Input: AH = 1Fh
  1020.                 AL = 01h, Write modem control register (MCR)
  1021.                 BL = Modem control register, where:
  1022.                      Bits 7-5 = 0 (Reserved) (forced 0)
  1023.                      Bit 4    = 1 Set loopback mode
  1024.                      Bit 3    = 1 Set OUT2 enable interrupts (forced 1)
  1025.                      Bit 2    = 1 Set OUT1 active (on)
  1026.                      Bit 1    = 1 Set Request to send active (on)
  1027.                      Bit 0    = 1 Set DTR active (on)
  1028.                 DX = Port number
  1029.  
  1030.          Output:   AX = Port status (see function 03h)
  1031.  
  1032.          In sub-function 01h (write MCR) X00 will force bit 3 to 1.  That
  1033.          is, X00 will not allow the communications interrupts to be
  1034.          disabled.
  1035.  
  1036.          RTS may be used as a flow control signal by the FOSSIL.  When
  1037.          the application program writes the MCR, the RTS bit is treated as
  1038.          an RTS enable bit.  This means that X00 will allow the application
  1039.          program to signal when it wants to allow RTS on.  It does not force
  1040.          RTS on.
  1041.  
  1042.          RTS only permits the DTR to be modified with this function.  This
  1043.          function should not be used for any reason.  It is hardware
  1044.          specific and such hardware may not exist in the future.
  1045.  
  1046.     Function 20h - Read with no wait (destructive).
  1047.  
  1048.          Input: AH = 20h
  1049.                 DX = Port number
  1050.  
  1051.          Output:   AH = 00h if a character is available
  1052.                    > 00h if no character is available
  1053.                 AL = Next character if available
  1054.  
  1055.          This function returns the next character from the receive buffer.
  1056.          This function is the same as function 0Ch except that any character
  1057.          returned is removed from the receive buffer.
  1058.  
  1059.     Function 21h - Stuff/Poke the receive buffer.
  1060.  
  1061.          Input: AH = 20h
  1062.                 AL = Character to place in the receive buffer
  1063.                 DX = Port number
  1064.  
  1065.          Output:   Nothing
  1066.  
  1067.          This function will insert the passed character into the receive
  1068.          buffer (at the end).  Subsequent reading of the serial input will
  1069.          read the character.  The character is inserted at the end of the
  1070.          buffer (as though it were just received.)
  1071.  
  1072.          The character is inserted into the receive buffer by calling the
  1073.          receive interrupt routine.  All normal receive checking is
  1074.          preformed on the character.  Some things to note are:
  1075.  
  1076.               If receiving of Xon/Xoff is enabled and an Xoff is
  1077.               stuffed/poked into the buffer, the transmitter will stop
  1078.               until a an Xon is received or stuffed/poked.
  1079.  
  1080.               If Control-C/K checking is enabled and a Control-C/K is
  1081.               stuffed/poked, then the character is not put in the
  1082.               buffer and the internal flag is set.
  1083.  
  1084.          ONEFOSsil does not support this function as there is no known need
  1085.          for it.
  1086.  
  1087.                          "Layered Application" services
  1088.  
  1089.     ONEFOSsil supports NO "Layered Application" services.  The functions
  1090.     simply aren't monitored.  I don't feel most people have any use for
  1091.     them.
  1092.  
  1093.                                Application Notes
  1094.  
  1095.                    Which Activate/Deactivate functions to use
  1096.  
  1097.     It is the hope of Ray Gwinn (after a period of time) to make X00's
  1098.     functions 04h and 05h compatible with the PS/2's INT 14h functions 04h
  1099.     and 05h.  Currently, X00's functions 04h and 05h are duplicated at
  1100.     functions 1Ch and 1Dh respectively.  Ray requests that application
  1101.     programmers start using functions 1Ch and 1Dh if those functions are
  1102.     available.  That is, use functions 1Ch and 1Dh instead of functions 04h
  1103.     and 05h respectively.
  1104.  
  1105.     It is relatively simple to determine if the functions at 1Ch and 1Dh are
  1106.     available.  When your program is ready to activate the FOSSIL for a
  1107.     given port, issue function 1Ch.  If 1954h is returned, then the port is
  1108.     activated.  If 1954h is not returned, reissue the request to function
  1109.     04h.  Save the function number actually used to activate the port, then
  1110.     increment it by one to deactivate the port.  You may also keep track of
  1111.     the maximum function supported by the driver, to see what other calls
  1112.     are available.  You should; however, leave a user configured option to
  1113.     override all extended function calls.
  1114.  
  1115.     <EoF>
  1116.