freebsd/sys/i386/isa

Stallion Multiport Serial Driver Readme
---------------------------------------

Version: 0.0.2 alpha
Date:    08JAN96
Author:  Greg Ungerer (gerg@stallion.oz.au)



1. INTRODUCTION

This is a FreeBSD driver for some of the Stallion Technologies range of
multiport serial boards. This driver is still very new, so it should be
considered to be of very alpha quality.

This driver has not been developed by Stallion Technologies. I developed it
in my spare time in the hope that it would be useful. As such there is no
warranty or support of any form.

What this means is that this driver is not officially supported by Stallion
Technologies, so don't ring their support if you can't get it working. They
will probably not be able to help you. Instead email me if you have problems
or bug reports and I will do what I can... (Sorry to sound so heavy handed,
but I need to stress that this driver is not officially supported in any way.)

This driver supports the EasyIO and EasyConnection 8/32 range of boards.
All of these boards are not classical intelligent multiport boards, but are
host based multiport boards that use high performance Cirrus Logic CL-CD1400
RISC UART's (they have built in FIFO's, automatic flow control, and some
other good stuff).

The EasyIO range of cards comes in 3 forms, the EasyIO-4, EasyIO-8 and the
EasyIO-8M. All of these are non-expandable, low cost, ISA, multiport boards
with 4, 8 and 8 RS-232C ports respectively. The EasyIO-8M is not currently
supported by this driver. Though it is pretty easy to support so I'll do
that when I get a chance. Each EasyIO board requires 8 bytes of IO address
space and 1 interrupt. On an EISA system it is possible to share 1 interrupt
between multiple boards. The EasyIO-4 has 10 pin RJ connectors, and the
EasyIO-8 comes with a dongle cable that can be either 10 pin RJ connectors or
DB-25 connectors. The EasyIO-8M has 6 pin RJ connectors.

The EasyConnection 8/32 family of boards is a relatively low cost modular
range of multiport serial boards. The EasyConnection 8/32 boards can be
configured to have from 8 to 32 serial ports by plugging in external serial
port modules that contain from 8 to 16 ports each. There is a wide range of
external modules available that offer: DB-25 connectors, RJ-45 connectors
(both with RS-232 D and E compatible drivers), and also RS-422 ports. The
EasyConnection 8/32 boards come in ISA and MCA bus versions. The board takes
the form of a host adapter card, with an external connector cable that plugs
into the external modules. The external modules just clip together to add
ports (BTW they are not hot pluggable). Each EasyConnection 8/32 board
requires 2 separate IO address ranges, one 2 bytes in size and a secondary
region of 32 bytes. Each board also requires 1 interrupt, on EISA systems
multiple boards can share 1 interrupt. The secondary IO range (the 32 byte
range) can be shared between multiple boards on any bus type.

So thats the hardware supported (sounds like a marketing spiel doesn't it!).
I am working on drivers for other boards in the Stallion range, so look
out for those some time soon...



2. INSTALLATION

This driver, as is, will work on a FreeBSD 2.1 system. It will run on
a 2.0.5 system, or -current version systems by changing a define in the
driver source.

You will need to build a new kernel to use this driver. So the first thing
you need is to have the full kernel source. Most people will have this
(I hope!). The following assumes that the kernel source is in /usr/src/sys.

The driver can support up to 8 boards (any combination of EasyIO and
EasyConnection 8/32 boards). So there is a theoretical maximum of 256 ports.
(Off-course I have not tested a system with this many!)

Instructions to install:

1. Copy the driver source files into the kernel source tree.

        cp stallion.c /usr/src/sys/i386/isa
        cp scd1400.h /usr/src/sys/i386/ic

   Note: if you are not using FreeBSD 2.1.0 then you may need to edit the
   stallion.c file and change the VFREEBSD define to match your version.

2. Add a character device switch table entry for the driver into the cdevsw
   table structure. This involves adding some code into the kernel conf.c
   file:

        cd /usr/src/sys/i386/i386
        vi conf.c
            - add the following lines (in 2.1 I put them at line 729):

/* Stallion Multiport Serial Driver */
#include "stl.h"
#if	NSTL > 0
d_open_t        stlopen;
d_close_t       stlclose;
d_read_t        stlread;
d_write_t       stlwrite;
d_ioctl_t	stlioctl;
d_stop_t        stlstop;
d_ttycv_t	stldevtotty;
#define stlreset	nxreset
#define	stlmmap		nxmmap
#define stlstrategy	nxstrategy
#else
#define	stlopen		nxopen
#define stlclose	nxclose
#define stlread		nxread
#define stlwrite	nxwrite
#define stlioctl	nxioctl
#define stlstop		nxstop
#define stlreset	nxreset
#define stlmmap		nxmmap
#define stlstrategy	nxstrategy
#define	stldevtotty	nxdevtotty
#endif


            - and then inside the actual cdevsw structure definition, at the
              last entry add (this is now line 1384 in the 2.1 conf.c):

	{ stlopen,	stlclose,	stlread,	stlwrite,	/*72*/
	  stlioctl,	stlstop,	stlreset,	stldevtotty,/*stallion*/
	  ttselect,	stlmmap,	stlstrategy },

            - the line above used major number 72, but this may be different
              on your system. Take note of what major number you are using.
              
            - save the file and exit vi.

3. Add the driver source files to the kernel files list:

        cd /usr/src/sys/i386/conf
        vi files.i386
            - add the following definition line into the list (it is stored
              alphabetically, so insert it appropriately):

i386/isa/stallion.c		optional	stl	device-driver

            - save the file and exit vi.

4. Add board probe entries into the kernel configuration file:

        cd /usr/src/sys/i386/conf
        cp GENERIC MYKERNEL
            - if you already have a kernel config that you use then you
              could just use that (instead of MYKERNEL)
        vi MYKERNEL
            - enter a line for each board that you want to use, eg:

device		stl0	at isa? port 0x2a0 tty irq 10 vector stlintr

            - change the io address and irq in this line as required
            - save the file and exit

5. Build a new kernel using this configuration.

        cd /usr/src/sys/i386/conf
        config MYKERNEL
        cd ../../compile/MYKERNEL
        make depend
        make all
        make install


And there you have it!  It is a little bit of effort to get it in there...

So once you have a new kernel built, reboot to start it up. On startup the
Stallion board probes will report on whether the boards were found or not.
For each board found the driver will print out the type of board found,
and how many panels and ports it has. 

If a board is not found by the driver but is actually in the system then the
most likely problem is that the IO address is wrong. The easiest thing to do
is change the DIP switches on the board to the desired address and reboot.
On EasyIO and EasyConnection 8/32 boards the IRQ is software programmable,
so if there is a conflict you may need to change the IRQ used for a board in
the MYKERNEL configuration file and rebuild the kernel.

Note that the secondary IO address of the EasyConnection 8/32 boards is hard
wired into the stallion.c driver code. It is currently set to IO address
0x280. If you need to use a different address then you will need to edit this
file and change the variable named stl_ioshared.



3. USING THE DRIVER

Once the driver is installed you will need to setup some device nodes to
access the serial ports. Use the supplied "mkdevnods" script to automatically
create all required device entries for your boards. To make device nodes for
more than 1 board then just supply the number of boards you are using as a
command line parameter to mkdevnods and it will create nodes for that number
of boards. By default it will create device nodes for 1 board only.

Note that if the driver is not installed at character major number 72 then
you will need to edit the mkdevnods script and modify the STL_SERIALMAJOR
variable to the major number you are using.

Device nodes created for the normal serial port devices are named /dev/ttyEX
where X is the port number. (The second boards ports will start from ttyE32,
the third boards from ttyE64, etc). It will also create a set of modem call
out devices named cueX where again X is the port number.

For the most part the Stallion driver tries to emulate the standard PC system
com ports and the standard sio serial driver. The idea is that you should
be able to use Stallion board ports and com ports inter-changeably without
modifying anything but the device name. Anything that doesn't work like that
should be considered a bug in this driver!

Since this driver tries to emulate the standard serial ports as much as
possible then most system utilities should work as they do for the standard
com ports. Most importantly "stty" works as expected and "comcontrol" can be
used just like for the serial ports.

This driver should work with anything that works on standard com serial ports.
Having said that, I have used it on at least the following types of "things"
under FreeBSD:
    a) standard dumb terminals (using getty)
    b) modems (using cu, etc)



4. NOTES

Be aware that this driver is still very new, so there is sure to be some bugs
in it. Please email me any feedback on bugs, problems, or even good
experiences with this driver!

There is no real smart line discipline bypass code yet (like in the sio
driver). I will add this for the next driver release.

I will probably also add LKM support some time soon.



5. ACKNOWLEDGEMENTS

This driver is loosely based on the code of the FreeBSD sio serial driver.
A big thanks to Stallion Technologies for the use of their equipment.