Installation guide for the FAS driver
-------------------------------------

To install this driver you need the manual of your serial card,
your system manuals and a certain knowledge about what actually
a serial driver is.

Note that the sample config files for multiport cards all have COM1
and COM2 additionally enabled. If you don't have COM1 and/or COM2
and the IRQs associated with them are needed for another device driver
all you have to do is to disable the respective interrupt so that the
kernel build program stops complaining. How to do that is OS dependent
and is described below. Apart from that, you don't need to change any
other config file in case of an interrupt conflict. If COM1 and/or COM2
aren't present in your system FAS automatically disables them.

There is an fas(7) man page that contains most of the informations
about FAS. File `fas.7' is the man page in NROFF source format while
`fas.7.cat' is the formatted version. As there is no automatic
installation procedure in the makefiles you need to install the man
page by hand. This is not only because the layout of the man page
directory tree differs between the various platforms but also because
this layout is frequently modified when there is an improved man program
installed. So just copy one of the two files into the proper directory
and, if necessary, notify your man porgram about the new man page.

You have to be user root to install the driver!


COMPILATION
===========

First of all you should copy the makefile that matches your system
to the file `Makefile'. Make sure that the makefile contains the
proper compiler switches, paths and file names for your system.
You may also look at `fas.c' and `fas.h' to find out what defines
are possible for conditional compilation. In particular, you should
take a closer look at the following OS dependent symbolic constants
in `fas.h':

NEED_PUT_GETCHAR
     If you don't link in the original serial driver you need to
     uncomment `NEED_PUT_GETCHAR' if the kernel linker complains
     about the undefined symbols `(asy|sio)putchar' and
     `(asy|sio)getchar'.
HAVE_VPIX
     If your OS doesn't have VP/ix support or FAS doesn't compile
     properly with VP/ix support you need to comment `HAVE_VPIX'
     out to disable it.
TUNABLE_TTYHOG
     Some UNIX flavors have a tunable `ttyhog' kernel variable
     that is used by FAS. If the kernel linker complains about
     this symbol being undefined you have to comment `TUNABLE_TTYHOG'
     out so that FAS uses the `TTYHOG' symbolic constant (from
     `sys/tty.h') instead.

After that you choose one of the space-* configuration files
that matches your serial card and copy this to `space.c'. If you
don't find a matching space file you should copy the one that
comes closest to your card to `space.c'.

In any case you should check the entries in that file against your
card's manual and jumper settings. The space files contain explanations
about what data you have to enter.

If your `space.c' is filled in properly you simply type `make' to
compile the driver. If you don't get error messages you may begin
with the actual installation. Otherwise you have to find the cause of
the problem. Some error reasons may be missing include files, macros
that are defined in different include files or missing at all, or you
don't use the standard UNIX [34].X/386 AT&T C compiler. Don't use any
other compiler because this may break things. An exception from this
rule is the GNU C compiler which can also be used. But note that older
versions tend to break FAS, so you should use gcc 2.4.5 or newer.
However, don't overestimate the performance gain of a gcc compiled FAS
driver. At least with gcc 2.4.5, gcc produces rather poor code for FAS.

For SCO Xenix you have to use the Microsoft C compiler because Xenix
doesn't have the AT&T compiler. You will need the ANSI C version of
the Microsoft compiler because the preprocessor of the original
Xenix distribution doesn't understand `#if defined(...)' statements
in 386 mode.


INSTALLATION
============

If you want to have both the original asy (or sio) and the new FAS
driver in the kernel the only restriction is that ports and interrupt
vectors can't be shared between the two drivers. Each driver controls
its own separate set of ports and IRQs.

uPort:  Copy one of the config-* files to `config'. Check out
        whether the interrupt vectors in this file reflect the
        jumper settings on your serial card. Note that an IRQ2 on
        your card is an interrupt vector of 9. All other IRQ numbers
        correspond to the vector number, though. If you want to
        disable an interrupt vector just remove the respective number
        from the `intvec' entry.

        Next you have to tell the config program to include the new
        driver at kernel link time. This is done by a line in the file
        /etc/atconf/systems/system.std. Look for the line containing
        `asy' followed by an asterisk (`*') and a comment. Create a
        similar line where `asy' is substituted with `fas'. Add a
        proper comment. If you don't want to use any ports under the
        DOS emulator you should insert an asterisk at the beginning
        of the line that contains the word `asy'. This excludes the
        asy driver from the kernel. But if you want to have it in the
        kernel you have to configure it to only use the ports you
        need under DOS. The remaining ports should be controlled by
        the FAS driver.

        Now type `make install' and after that you are ready to link
        a new kernel. Refer to your system manuals on how to do that.

        Before you reboot the new kernel make sure that you create
        the proper tty device nodes in /dev. But first you should
        remove all device nodes belonging to the original asy driver
        that you don't need any more.

        Now create your own tty device nodes that fit your needs.
        The default device name prefix for the FAS driver is `ttyF'.
        That is, ttyF00, ttyF01 ... and ttyFM00, ttyFM01 ...
        You may choose another prefix, but note that some utilities
        like uustat depend on tty-devices beginning with `tty'!

        The default value for the major device number is 4, and
        sane values for the minor device numbers are 80 + device #
        for the dialout node and 208 + device # for the dialin (getty)
        node. Device # counts from 0 and reflects the actual port number.
        Refer to the fas(7) man page for a description of the possible
        minor device numbers.

        Remember to change the inittab file to the new device names.
        Other files that contain tty-names for some reason should be
        updated, too (ttytype, Devices etc.).

        After you have booted the new kernel, provided your configuration
        was correct, you should be able to use the serial devices. You
        may also want to look at the `CABLING' and `MODEM SETUP' sections
        in the fas(7) man page.


ISC:    Copy one of the s_fas-* files to `s_fas'. Make sure that
        you have a separate line in it for each block of contiguous
        port addresses assigned to the same interrupt vector (check
        the jumper settings on your serial card). Each line contains
        the number of ports bound to that interrupt, the start address
        of the first (lowest or only) and the end address of the last
        (highest or only) port on this interrupt line and other data.
        Refer to your ISC manuals if you need to change this file. Note
        that an IRQ2 on your card is an interrupt vector of 9. All other
        IRQ numbers correspond to the vector number, though.

        If you want to change the interrupt vector assignment of the
        various ports/cards you can do so by changing the 6th field
        of the respective line. But make sure that each line has a
        different value in the 6th field when you're finished with
        the changes. If you want to disable an interrupt vector just
        set the second field of the line to `N'. A `Y', on the other
        hand, enables the vector. Due to a bug in some kernel build
        programs you need to have all enabled lines (with `Y') in
        front of the disabled lines (with `N') because the build
        program stops scanning the file when it finds the first line
        with an `N' in the second field. So just move all enabled lines
        to the beginning of the file.

        Then you copy one of the n_fas-* files to `n_fas'. This
        file contains data needed to automatically create tty device
        nodes at installation time. Things you may want to change are
        the tty node names and the minor device numbers (last field) for
        these nodes. Make sure you have a node for every port on your
        serial card in this file.

        Sane values for the minor device numbers are 80 + device #
        for the dialout node and 208 + device # for the dialin (getty)
        node. Device # counts from 0 and reflects the actual port number.
        Refer to the fas(7) man page for a description of the possible
        minor device numbers.

        Now copy one of the i_fas-* files to `i_fas'. This file
        contains the getty lines for the inittab file which is rebuilt
        every time a new kernel is installed. Make sure that you use the
        same device names here as in the file `n_fas'. If there is a
        file /etc/conf/init.d/fas already installed, note that `i_fas'
        won't be copied over it so that customized lines in
        /etc/conf/init.d/fas are preserved.

        Next you have to modify the file /etc/conf/sdevice.d/asy in a way
        that only those devices are enabled that you want to be controlled
        by the original `asy' driver. This is done with an `N' in the second
        column of the corresponding line to disable the port and a `Y' to
        enable it. But usually you don't need the original driver any more.
        Therefore, all lines in /etc/conf/sdevice.d/asy should be set to `N'.

        To tell the kernel config program how to link in the FAS driver
        you have to add the following line to the file /etc/conf/cf.d/mdevice:

        fas	Iocrwi	iHct	fas	0	3	1	16	-1

        The 6th field contains the major device number of the driver. You
        may change this if it collides with another driver. This is normal
        as I can't know in advance what major device numbers all the UNIX
        vendors will use for their drivers. You can, however, use the
        major device number of the original asy driver if you completely
        suspend the asy driver (see above), that is, drivers can have the
        same major device number if not more than one of them is linked
        into the kernel at the same time.

        The sample line above is contained in the file `m_fas' so you
        don't need to type it in. All you have to do is to edit the file
        (the 6th field if you want to change the major device number) and
        to then append it once to /etc/conf/cf.d/mdevice.

        All this is in the ISC manuals. Read them carefully.

        Now type `make install' and after that you are ready to link
        a new kernel. Refer to your system manuals on how to do that.

        You may have to change files that contain tty names to the new
        device names (ttytype, Devices etc.). Take the names from `n_fas'.

        After you have booted the new kernel, provided your configuration
        was correct, you should be able to use the serial devices. You
        may also want to look at the `CABLING' and `MODEM SETUP' sections
        in the fas(7) man page.


ESIX:   Follow the description for ISC UNIX.


BELL:   Follow the description for ISC UNIX.


ATT:    Follow the description for ISC UNIX.


SCO:    Do the same steps as for ISC UNIX. Here are some additional
        hints:

        The original SCO serial driver is called `sio' instead of `asy'.
        You need to disable it because it won't coexist peacefully with
        FAS.

        According to reports from some beta test sites it isn't enough
        to disable the `sio' driver by setting all lines in
        `/etc/conf/sdevice.d/sio' to `N'. Additionally, you have to
        delete the `sio' entry in `/etc/conf/cf.d/mdevice'. You may also
        want to remove the file `/etc/conf/init.d/sio' in order to get
        rid of the lines in `/etc/inittab' that refer to `sio' devices.

        For the device nodes you should use SCO's naming conventions because
        there are some utilities that expect this tty name format. You need
        to change the names in `i_fas' and `n_fas'. To prevent a collision
        with the `sio' device node names you need to remove the file
        `/etc/conf/node.d/sio'.

        In file `fas.h' you may need to uncomment the `NEED_PUT_GETCHAR'
        define before you compile the sources.

        You have to compile FAS with the AT&T standard C compiler (rcc,
        don't use the Microsoft compiler !) and with the symbol `SCO'
        defined. The makefile for SCO takes care of this, though.

        After you made all the changes you need to run the `configure'
        utility to get all the dependencies right. To convince the
        configure program that it has work to do you should change some
        parameter and put in the original value afterwards. Be prepared
        that there may be more tinkering needed to disable `sio' completely
        because there seem to be SCO UNIX releases where the kernel config
        and build programs are broken.

        By default, FAS' boot message doesn't contain informations about
        the interrupt vector assignment. This is because FAS doesn't have,
        and doesn't need to have any knowledge about interrupt vectors.
        Only the generic kernel interrupt dispatcher knows about the
        assignment. However, if you can't live without the interrupt infos
        all you need to do to have them displayed is to enter the respective
        numbers into the fas_vec[] array in `space.c'. But make sure that
        these values correspond with the entries in `s_fas'.

        At least under some SCO UNIX versions there is a bug/feature in
        getty. It writes the `login:' message to stdout and then flushes
        the receiver buffers. This means that a fast automatic login
        attempt (`uucico') may fail because it sends the login name
        before getty has a chance to do the buffer flush. So the login
        name is lost and the login fails.

        There are two workarouds: Either use a different getty program
        or delay the sending of the login name for about two seconds
        (to be on the safe side). The latter solution implies that you
        have to tell every dialup user and poll site about the problem,
        as the fix has to be implemented on the remote side.


XENIX:  The installation procedure for Xenix is completely different
        from the other UNIX flavors.

        In file `fas.h' you may need to uncomment the `NEED_PUT_GETCHAR'
        define before you compile the sources. After compilation
        the files `fas.o' and `space.o' have to be copied to the
        directory `/usr/sys/io/fas'. Typing `make install' takes care
        of this.

        As the `sio' driver won't coexist peacefully with FAS you have
        to remove the `sio' line from the file `/usr/sys/conf/xenixconf'.
        Create a new line for `fas' in this file.

        After this you have to modify the file `/usr/sys/conf/master'.
        There is a line in it that looks like this:

        sio      4  0577 104    sio  0   0   5    1   7    3     4     33  34  

        You have to comment this out with an asterisk (`*') at the beginning
        of the line. Directly after this line you need to insert a new line
        with the following contents (for two ports, one on IRQ3 and one on
        IRQ4):

        fas      2  0537 104    fas  0   0   5    1   7    3     4     0   0  

        The second column indicates how many interrupt vectors are used by
        this driver (two vectors in this example). The last four columns
        contain the corresponding IRQ numbers (in octal !). Unused vectors
        are set to zero.

        Here is an example for three ports (on IRQ3, IRQ4 and IRQ5):

        fas      3  0537 104    fas  0   0   5    1   7    3     4     5   0  

        And this is for four ports (IRQ3, IRQ4, IRQ5 and IRQ2/9):

        fas      4  0537 104    fas  0   0   5    1   7    3     4     5   31 

        Note that the AT bus interrupts IRQ8 to IRQ15 are mapped to vector
        30 (octal) to 37 (octal). Therefore, IRQ9 (IRQ2 on the serial card) is
        vector 31 (octal) in this example.

        Take care that you don't use interrupt vectors that are already
        assigned to other drivers.

        For further details refer to the master(F) man page.

        By default, FAS' boot message doesn't contain informations about
        the interrupt vector assignment. This is because FAS doesn't have,
        and doesn't need to have any knowledge about interrupt vectors.
        Only the generic kernel interrupt dispatcher knows about the
        assignment. However, if you can't live without the interrupt infos
        all you need to do to have them displayed is to enter the respective
        numbers into the fas_vec[] array in `space.c'. But make sure that
        these values correspond with the entries in `/usr/sys/conf/master'.

        Now you have to insert the following line in `/usr/sys/conf/link_xenix'
        (before the lines with the system libs):

                ../io/fas/fas.o ../io/fas/space.o \

        After you made all the changes you might need to run the
        `/usr/sys/conf/configure' utility to get all the dependencies right.
        To convince the configure program that it has work to do you should
        change some parameter and put in the original value afterwards.

        Go to the directory `/usr/sys/conf' and link the new kernel with
        the `make' command. If all went well, copy the kernel to the
        root directory.

        You need to create the FAS device nodes manually in the directory
        `/dev' (with the command `mknod'). You should use SCO's naming
        conventions because there are some utilities that expect this
        tty name format. Here is an example how to make the device nodes:

        mknod tty1a c 5 80; mknod tty1A c 5 208
        mknod tty1b c 5 81; mknod tty1B c 5 209

        Major device number is always `5' (that of the suspended `sio'
        driver), the minor device numbers are calculated as described in
        the fas(7) man page. For full duplex hardware flow control
        tty1[a-z] gets the minor device number 80 + device# (device#
        counted from 0) and tty1[A-Z] gets 208 + device#.

        The last thing you have to do before you reboot your system is
        to check whether you need to make changes to the files that contain
        the device names for your original `sio' driver (for programs like
        `getty', `cu' and `uucico').

        After reboot you should remove all device nodes that belong
        to the now suspended `sio' driver. You may want to look at the
        `CABLING' and `MODEM SETUP' sections in the fas(7) man page.


SVR4.0: Do the same steps as for ISC UNIX. Here are some additional
        hints:

        Currently, FAS is _not_ a STREAMS driver. Therefore, you need
        the tty compatibility drivers in the kernel. They are named
        `ttcompat', `clist', and maybe there are even more drivers
        needed. These compatibility drivers don't provide some of the
        features a genuine STREAMS driver would have. So FAS under SVR4.0
        can't be used for SLIP, for instance. Please look into your SVR4.0
        manuals for more informations.

        Neither VP/ix nor DosMerge are supported by FAS under this
        operating system. You should comment `HAVE_VPIX' out in `fas.h'.
        This will change when FAS is converted into a STREAMS driver.


Other flavors of UNIX
=====================

Check out if one of the above installation schemes is similar to the
one you need for your system. Make the appropriate changes and try
out if it works. If your system is entirely different you have to
find out from your manuals how to install device drivers. But if
you use a UNIX SYSV/386 [34].X you should get it to work eventually.

Good luck.
