Bila Vrana/BILA_VRANA.iso/019A/ONEFOS09.ZIP/ONEREF.TXT

Text File | 1996-06-15 | 50KB | 1,116 lines

             Functions Reference Manual for the ONEFOSsil Developer
            (C) Copyright 1995-96 by Carl Morris and Morris Softronics
         ONEFOSsil, A low level serial communications driver for MS-DOS
                     based FOSSIL 5 compliant applications.

                                  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 extended
    functions, and this document will help describe 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 contained 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 Standard 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 usually only
    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.  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,
    this is unreliable if other utilities and/or drivers have hooked the INT
    14h interrupt vector since the FOSSIL was loaded.  It is not suggested
    to use this method.  Instead, it is better to just make the call to the
    "Activate" function 04h for the port you want to open 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, and 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; however, this method is not suggested either.

                                   Functions

    The following functions are supported by most FOSSIL drivers.

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

         Input:
              AH = 00h
              AL = Communications parameters:
                  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)
                  ----0--- = No parity
                  ---01--- = Odd parity
                  ---11--- = Even parity
                  -----0-- = 1 stop bit;
                  -----1-- = 1½ bits for 5-bit byte length, 2 for all
                             others
                  ------00 = 5 bits
                  ------01 = 6 bits
                  ------10 = 7 bits
                  ------11 = 8 bits
              DX = Port number
              BX = 0 (incase BNU tries to extend this function)

         Output:
              AH = Line status (see function 03h)
              AL = Modem 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 change the baud rate until function 04h is
         used to reactivate the FOSSIL driver.

         Note that BNU contains an extension to this function, and that if
         that extension is not desired you should make sure that BX and CX
         are not equal, or that one of them are zero.  If you would like
         information on this extension please write the author of this
         document or David Nugent, author of BNU.

    Function 01h - Transmit character with wait.         Input:
              AH = 01h
              AL = Output character
              DX = Port number

         Output:
              AH = Line status (see function 03h)
                  1------- = Time-out occurred, all other bits void
                  0------- = Character buffered, all bits valid
              AL = Modem status (see function 03h, void if time-out
              occurred)

         If there is no room in the transmit buffer, this function will wait
         until there is room in the buffer or until a time-out occurs.

         Notes:

           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 always enables interrupts upon the beginning of every
           FOSSIL call, so unless there are severe hardware problems,
           ONEFOSsil should always return.
           It is suggested that applications use function 0Bh instead of
           this function in all cases.  This function is slow, and X00 and
           BNU are prone to lock-ups.  Even if the THRE bit is set in a
           status return, there is a chance that the buffer could be filled
           by another application between calls, and as such the correct
           applicatio