Installation guide for the FAS Final Async Solution 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.

You have to be user root to compile and install the driver!


Compilation phase
=================

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, if you
don't link in the original serial driver you might have to uncomment
the `NEED_PUT_GETCHAR' define in `fas.h'. You also may want to
uncomment `HAVE_VPIX' in `fas.h' if you have VP/ix support in
the kernel.

After that you choose one of the space-xxxxx 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 trouble. 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 3.X/386 AT&T C compiler. Don't use any
other compiler because this may break things. In particular, don't use
the GNU C compiler as it wants to link in some "helpful" routines that
aren't in the kernel.

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 phase
==================

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-xxxxx 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.

       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 `README' file 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.


ISC:   Copy one of the s_fas-xxxxx 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 and
       end address of the first (lowest 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.

       Then you copy one of the n_fas-xxxxx 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 `README' file for a description of the possible
       minor device numbers.

       Now copy one of the i_fas-xxxxx files to `i_fas'. This file
       contains the getty lines for the inittab file which is rebuild
       every time a new kernel is installed. Make sure that you use the
       same device names here as in the file `n_fas'.

       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.
       Therefor, 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	4	1	16	-1

       The 6th field contains the major device number of the driver. You
       may change this if it collides with another driver.

       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.


ESIX:  Follow the description for ISC UNIX.


BELL:  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 remove 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.

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

       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'.

       You have to compile FAS with the AT&T standard C compiler (rcc,
       don't use the Microsoft compiler !) and with the `-DSCO'
       compiler command line flag. 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 remove `sio' completely
       because there seem to be SCO UNIX releases where the kernel config
       and build programs are broken (doesn't surprise me at all :-( ).


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

       In file `fas.h' you 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'.

       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). Therefor, IRQ9 (IRQ2 on the serial card) is
       vector 31 (octal) in this example.

       Make sure that they match the interrupt vectors defined in `space.c'.
       And 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.

       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 from the README file.
       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.


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 3.X you should get it to work eventually.

Good luck.
