ONEFOSsil FOSSIL 5 Communications Driver Revision 7
Copyright (c) 1995 by Carl Morris
Published by Morris Softronics

ONEFOSsil is a FOSSIL 5 serial communications driver for 8250 series
UARTs.  The 8250 series includes all compatible UARTS, including the
8250A, 8250B, 16450, 16550, 16550A, and the 82510 in compatibility mode.

ONEFOSsil is distributed under the SHAREWARE marketing technique. The
SHAREWARE technique provides the end user a chance to evaluate the
product before actually purchasing the product.  It is required of the
user to either purchase the full product or stop using the product after
the evaluation period.

Please refer to the LICENSE.TXT file you received with ONEFOSsil for
complete details.  Some other publishers may be granted to distribute
the full product with their products.  A list of these are maintained by
the primary publisher of ONEFOSsil and may be requested at any time.

Please refer to the SUPPORT.TXT file you received with ONEFOSsil for
instructions on how to obtain support for this product.  The
instructions may vary from copy to copy depending on the distributor.

You may have already noticed, but ONEFOSsil's archive is Windows
friendly. All documentation files have an extension of .TXT rather than
.DOC.  This makes viewing the files under the Windows environment more
friendly as users of MS Word for Windows will not be forced to use Word
for reading the documentation.

All trademarks and copyrights mentioned in this documentation are the
property of their owners.  Use of such names in no way is an
advertisement or a guarantee that this product will work with any
mentioned products.

In NO WAY is Morris Softronics or Carl Morris liable for any damages
this product might be claimed to have made.  There is no warranty of any
kind, either expressed or implied, that this product will perform as
described, even under similar environments.

ONEFOSsil Revision 5 Documentation                             Page 1
------------------------------------------------------------------------

Background

ONEFOSsil is simply a communications driver that complies with MOST of
the FOSSIL 5 specification.  Simply put, ONEFOSsil will probably not
work with any program that was designed to use the FOSSIL driver for
complete access of the computer.  A technical document will describe the
differences with this driver if someone needs to know more.

ONEFOSsil is special in that it only supports one FOSSIL port at a time.
As such some FOSSIL 5 specifications had to be violated to be compatible
with other FOSSIL drivers and multiple copies of ONEFOSsil.  Just
because ONEFOSsil] is a single port driver, that does not stop it from
being useful for multi-port or multi-line systems.  ONEFOSsil can even
handle multiple ports that share the same IRQ.

In the time of using other FOSSIL's I have found that very few people
seem to be actively working on any.  Most people even refuse to work on
the bugs current versions have.  As such this FOSSIL was wrote for this
purpose. It provides the plug for the gap that has been made recently in
the area of DOS based FOSSIL/Communications support.  It fixes the bugs
that X00 has with single port modes, and improves the reliability of
BNU.  Few other drivers exist, and even then, these drivers don't get
the support they need.

As I have been working with the FOSSIL specification, I have come to
conclude that it is quite outdated.  It was designed in a day when the
number of BBS software were low and the number of 8086 class machines
running a form of MS-DOS were high.  Today, serial communications is not
the only type of modem or BBS access, the number of BBS software nears
the population of the smallest state, only one 8086 class machine
running anything that resembles MS-DOS exists, and almost everyone owns
a Microsoft product (even if they don't own an 8086 based machine). What
the population still using DOS needs is a small versatile communications
standard with out the overhead of the FOSSIL specification.  Already its
been shown that if you have FOSSIL support, you can have incoming
telnet, even on a DOS machine.  The catch is that most software still
thinks it is running and the old UART the first PC came with.  This is
only making it a burden on the software performing this task.  I wish to
work on this with a new specification, called SUCI (pronounced "sucky").
SUCI stands for Simple Universal Communications Interface.  This gets
rid of the FOSSIL Fido, Opus, and SEADog trademarks.  You have to hand
it to those programmers. They started what was quite a short lived
compatibility achievement, and failed only because of Microsoft and IBM.

Put that behind us, lets get on with this FOSSIL.  Please read the
FidoNet ONEFOS echo for more information on SUCI.

Requirements

This FOSSIL 5 driver requires that you are running MS DOS 3.0 or
compatible operating system.  It requires about 3 kilobytes of memory
plus some for buffers.  ONEFOSsil will NOT work with any processor less
than an 80286.  It also requires that you have software that is FOSSIL 5
compliant, such as BBS software or on-line doors.  There may be other
software that requires or can make use of a FOSSIL driver.

Not all FOSSIL 5 compliant software may work with ONEFOSsil.  Read the
SUPPORT.TXT file if you find a program that refuses to use ONEFOSsil.

Using ONEFOSsil

NOTICE: As of revision 7, not all functions are complete.  Notes may
appear below on functions that are still pending.  Read SUPPORT.TXT if
you feel you are having troubles with ONEFOSsil's installations.

Port Numbers

ONEFOSsil, being a single port driver, at least needs to know which port
you wish to work with.  What comes next depends on what you want
ONEFOSsil to do on that port.  FOSSIL drivers work with ports on a
programmer level. As such, an odd rule must be observed because port
numbers are not the same as COM ports.  Generally COM1 is FOSSIL port 0,
but even that is not always the case.  However, many programs that use
FOSSIL's ask for a COM number.  If you want ONEFOSsil to run on your
COM1, then you should have ONEFOSsil using port 0, and set your software
to use COM1.

FOSSIL ports in this driver may range from 0 through 63, but most other
software will only support ports 0 through 7, or 0 through 15.

Installation

ONEFOSsil assumes very little about your system.  It uses command line
parameters to use your computers hardware.  You must specify the same
command line every time if you expect ONEFOSsil to behave the same every
time.

USE: ONEFOS port=addr,irq [options]

If an equals sign appears after the port number, ONEFOSsil presumes you
want to load the driver on that port.  The addr and irq parameters MUST
follow to tell ONEFOSsil where the UART is.  The addr parameter is a
hexadecimal address of the UART which may range from 0100 to FFFF.  The
irq parameter is a decimal IRQ that the UART uses to signal activity and
may be 3 through 5, 7, 9 through 12, or 15.  IRQ 9 will work wherever
IRQ 2 is needed. Below is a simple table of common address/irq
assignments made by IBM in the PC specification. More exist, but none
are really standard.  Consult your computer's manuals or hardware's
manuals for more information.

PORT | COMx | Address | IRQ
----------------------------
  0    COM1    03F8      4
  1    COM2    02F8      3
  2    COM3    03E8            No standard IRQ.  You must pick an unused
  3    COM4    02E8            one when installing your hardware.

After defining the address and IRQ of the UART, options follow that are
in no way required, but allow you to customize the driver to your
situation.  A description will follow below.

H       Just the single letter by itself.  ONEFOSsil will hook the IRQ
        immediately rather than waiting for the port to be used.  This
        option is probably needed when running before a multi-tasker or
        when sharing IRQ's among multiple copies of ONEFOSsil.

T=num   ONEFOSsil will only wait for a while when an operation is
        failing.  This is to prevent modem/serial problems from locking
        the computer completely.  The num parameter sets this timing to
        a number of seconds.  Valid range is 0 through 3599 seconds. X00
        is set to 30 seconds.  BNU will never timeout under some
        conditions.  The BIOS uses a timeout of 2 seconds; however, I
        have found that FOSSIL based programs are poorly wrote and need
        the 30 seconds!  The default is 30 seconds.  The timeout value
        is accurate to 1/18th of a second.

B=write,read,stop,continue

        FOSSIL's when applied to most communications devices need to
        buffer data.  In the case of serial communications, there is no
        perfect buffer sizes, or even ideal buffer sizes.  This option
        give you room to try to eliminate performance problems.  Not all
        parameters need to be specified, but do not leave any trailing
        comma's.

        The write parameter is for the output buffer size.  It may be
        any size between 32 bytes and 32767 bytes.  Default is 1024.

        The read parameter is for the input buffer size.  It may also be
        any size between 32 bytes and 32767 bytes.  Default is 1024.

        Memory restrictions do apply as the driver code and buffers must
        fit in a single 65536 byte segment.  You may get an "out of
        memory" error if you try to load too large of buffers.

        The next parameters are automatically calculated based on the
        above read parameter, and it is strongly suggested that you do
        not attempt to change the default settings.

        The stop parameter is used only when flow control is being used.
        The FOSSIL driver must shut the other end off before the buffer
        becomes completely filled, otherwise an overrun will likely
        occur. The stop parameter may range from 0 to 2 short of the
        size of input buffer and must be less than the value of the
        continue parameter.  When the number of bytes free in the input
        buffer is fewer than the stop parameter, flow control is
        exerted.

        The continue parameter complements the stop parameter.  After
        flow control has been exerted it must then be removed when there
        is enough room in the buffer.  It may range from 1 to 1 short of
        the size of the input buffer.  It must also be greater than the
        stop value.  When the number of bytes free in the input buffer
        becomes larger than this number, flow control will be removed.

        It is the author's experience that the faster the modem, or the
        slower the computer, the larger the buffers should be, and the
        larger that gap between read, continue, and stop parameters.  I
        would also recommend that smaller write buffers help BBS users
        on slow modems; however, there is also a software solutions for
        this, but few BBS softwares or on-line games take this into
        account.

        The default buffer sizes are 1024 bytes for both.  The stop
        parameter defaults to 1/4 the size of the input buffer, and
        continue defaults to 1/2 the size of the input buffer.

L=baud,data,flow

        The FOSSIL specification was wrote before the days of high speed
        modems.  As such the maximum speed was 9600, and later 38400.
        Newer drivers needed to use even higher speeds, and old software
        just would not work to set the speed any more.  The locking
        option of FOSSIL drivers thus serve two purposes, to prevent
        poorly programmed software from screwing with a locked baud rate
        high speed modem, and to make amends in the area of support of
        high speeds.  Drivers like ONEFOSsil and X00 have a means for
        software to control higher speeds, but little software take use
        of it.  As such it is wise to lock any parameters you can. The
        use of this option is really hard to understand and describe to
        someone else.  I strongly suggest getting help before using some
        of the parameters the locking option provides.  Again, not all
        parameters need be specified, but do not leave trailing comma's.

        The baud parameter is a value that must be one of the following:
        110,150,300,600,1200,2400,4800,9600,19200,28800,38400,57600, or
        115200.  Once locked, the port speed will not be allowed to be
        changed through the FOSSIL driver.

        The data parameter is several options thrown together in one
        parameter.  It is formatted as three characters: a number, a
        letter, and another number.  The first number sets the number of
        data bits per byte.  Valid values are 5, 6, 7, and 8, with 8
        being the most common.  The letter is a parity code that comes
        from the first letter of the following words: None, Odd, Even,
        Mark, or Space.  Most often None is used.  The last number is
        only 1 or 2, and is the number of stop bits to send.  Most often
        it is set to 1.

        The flow parameter is probably the hardest part to understand.
        Most FOSSIL's do not give any options for locking flow control.
        ONEFOSsil permits both locking flow controls on and off.  The
        flow parameter is made of a string of characters, each
        optionally preceded by a minus (-).  The available letters are:
        H for hardware flow control use, R for receiving software flow
        control, and S for sending software flow control.  If a dash
        appears in front of a character, that mode of flow control is
        locked off, otherwise it is locked on.

        The common rule, in most cases, you should always lock the data
        to 8N1 just as a safety.  If you lock a baud rate, you should
        also lock hardware flow control.  If you run a BBS, and you have
        problems when users use their left arrow key, lock software flow
        control receiving off.

S=os,sensitivity

        Another complicated option.  X00 has the ability to give up time
        slices when it detects the application to be idle.  This is only
        available for DESQview, which was the most widely used
        multi-tasker at that time.  Windows has recently emerged as a
        good multi-tasker, and still the only kind of sleeping modes
        available in most FOSSIL's is DESQview and OS/2.  While OS/2 is
        compatible with the same function Windows uses to sleep, it also
        has its own.  ONEFOSsil; however, only supports generic DESQview
        and Windows sleep calls.  FOSSIL drivers are obsolete for OS/2,
        but if ONEFOSsil is used under OS/2, the Windows mode of
        sleeping will work.  In some cases this option should not be
        used.  There is no settings that will work best for every
        system, all you can do is experiment.

        The os parameter is either a D for DESQview or a W for Windows.
        By default ONEFOSsil does not attempted any sleeping.

        The sensitivity parameter is like the slider in the Windows 95
        DOS properties; however, this sensitivity is for communications
        calls.  It must be in the range from 0 through 255.  0 is low
        sensitivity and will cause a lot of sleeping, 255 is high
        sensitivity and will cause little sleeping.  Please understand
        that some applications sleep on their own.  This setting will
        rarely affect those that do sleep on their own.

F=fifo  There is not much to control with FIFO'd chips.  Generally the
        reason behind FIFO'd chips is so the processor/FOSSIL driver is
        not required to catch every character as they come in.  FIFO's
        should not be used for reducing interrupt overhead as claimed.
        In ONEFOSsil receive interrupts are fixed at 1.  This does not
        mean that the UART will only put 1 character in the FIFO!  It
        just means that ONEFOSsil will be interrupted every time a
        character arrives. This should make it more reliable under
        multitasking environments. The transmit fifo however is
        complicated, and is what this function allows you to set.  There
        is no perfect setting, but there are some guide lines.

        The fifo parameter is a number that may range from 0 to 255.  It
        specifies the number of characters transmitted at one time.  It
        should not be set greater than the number of FIFO registers in
        your UART, which for a 16550 is 16.  If the fifo parameter is
        set to 0, FIFO's will be entirely disabled, including receive
        FIFO's.

        Some common rules for setting the fifo parameter are:  Never set
        it greater than the number of receive FIFO's of the receiving
        UART;  If the receiving end seems to be dropping characters, it
        may help to reduce the fifo parameter, even setting it to 1;
        insure that the gap between the read, stop, and continue
        parameters of the B option are greater than your UART's FIFO
        buffer plus the transmitting UART's FIFO setting (if its
        optional.)  Usually it is wise to use 3 times your FIFO buffer
        size as a gap value.  The default fifo setting is 15 if FIFO's
        are detected in your UART.

Options above may be listed in any order after the port specification.
They may not appear twice however.  All options are case insensitive.
Options that include multiple parameters do not require all parameters
be specified.  In this case, you may leave the parameter blank by
skipping to the next parameter.  Some examples follow:

Port 0, standard COM1, locked at 115200:

ONEFOS 0=03F8,4 L=115200,,H

Port 5, no standard, locked at 38400 8N1, hooking the interrupt now:

ONEFOS 5=3480,13 L=38400,8N1,H H

Port 3, COM4 IRQ 7, lock data at 7E2 with software XON/XOFF, transmit
buffer of 64 bytes:

ONEFOS 3=02E8,7 L=,7E2,SR B=64

Other Operations

Installing is not the only thing ONEFOSsil can do.  If a space appears
after the port number, ONEFOS will try to accomplish one of the
following options:

ONEFOS port O

        Opens the port.  The port doesn't have to be a ONEFOSsil port.

ONEFOS port C

        Closes the port.  The port doesn't have to be a ONEFOSsil port.

ONEFOS port U

        After ONEFOSsil has been installed, it may be unloaded with this
        command.  ONEFOSsil may not be able to unload if other drivers
        or programs have been installed after ONEFOSsil.

ONEFOS port S   not completed

ONEFOS port     not completed

Rest of documentation not written

Future

I have a bunch of interesting things planned for revision 8.  The code
of the driver will be rewritten, and the installer will be written in a
high level language.  This will give me the ability of many high level
features on the command line ... more to come ...

Credits

Thanks the most to Ralph Brown and others for the Interrupt List
(version 47).  Without the Interrupt List and its many other components,
this project would have flopped from all the misleading sources I used.
Yes, the Interrupt List is not perfect, but not nearly as bad as some of
the other sources I used in this project.

Thanks also to Allen L. Wyatt, Sr. for "Advanced Assembly Language"
(ISBN 1-56529-037-2) which provided me with just enough (misleading)
information to start on the project.  Many sample programs contradict
information shown in the charts, but they all seem to run, and I do plan
to use more of the book than the serial communications chapter.

Thanks also to Ray Gwinn for providing the specifications to his
slightly advanced FOSSIL specification.  Yes, small errors here and
there too, but nothing the Interrupt List didn't clear up.  It is also
his buggy DOS based FOSSIL driver, X00, and his denounce of Windows,
that prompted for the creation of this driver.  Bob Juge also had some
help in getting me to write this driver, with his persistent, "the X00
specs are publicly available."

Thanks a little to Barb Maly, for constantly reminding me why she didn't
use X00, and why I didn't use BNU.  She was also a primary beta tester.

Dan Liston gets a little thanks too, for allowing me to test my driver
on repeated calls to his system.  I know it had to be annoying.

COMPATIBILITY NOTES:

If you use DOORWAY 2.3 or earlier, possibly later versions too, you MUST
use the H option when installing, or the O option before running
DOORWAY. DOORWAY has a bug dealing with the order in which it saves and
restores the interrupt table and initializes/deinitializes the FOSSIL
driver.

If you use CEXYZ as a protocol driver, under a multi-tasker, performance
may drag, specially on receiving.  Everything is ok if I run in DOS, so
I am not sure on the reason as of yet, other than in the time I tested
ONEFOSsil with CEXYZ I noticed a lot of crazy things that CEXYZ doesn't
need to be doing to work.

LORE will not work if set to Extended FOSSIL.  For some reason, LORE
does an "Information" call, then never activates the port, so all
communications goes to the BIOS communications routines.

Software tested: Renegade BBS, FHSLink, L.O.R.D., Planets: TEOS,
Usurper, Galactic Overlords, Global War, DoorWay, CEXYZ, RIPVersi, LORE,
FOSSILC (unreleased version), B.R.E., Portal of Power, FrontDoor.

Thats about all for now.

<EoF>
