root/drivers/char/README.stallion

/* */

Stallion Multiport Serial Drivers
---------------------------------

Version: 1.0.6
Date:    11MAR96
Author:  Greg Ungerer (gerg@stallion.oz.au)


1. INTRODUCTION

There are two drivers that work with the different families of Stallion
multiport serial boards. One is for the Stallion smart boards - that is
EasyIO and EasyConnection 8/32, the other for the true Stallion intelligent
multiport boards - Stallion, Brumby, ONboard and EasyConnection 8/64.

If you are using any of the Stallion intelligent multiport boards (Brumby,
ONboard, Stallion, EasyConnection 8/64) with Linux you will need to get the
driver utility package. This package is available at most of the Linux
archive sites (and on CD's that contain these archives). The file will be
called stallion-X.X.X.tar.gz where X.X.X will be the version number. In
particular this package contains the board embeded executable images that
are required for these boards. It also contains the downloader program.
These boards cannot be used without this.

The following ftp sites (and their mirrors) definately have the stallion
driver utility package: ftp.stallion.com, tsx-11.mit.edu, sunsite.unc.edu.

ftp.stallion.com:/drivers/ata5/Linux/stallion-1.0.1.tar.gz
tsx-11.mit.edu:/pub/linux/BETA/serial/stallion/stallion-1.0.1.tar.gz
sunsite.unc.edu:/pub/Linux/kernel/patches/serial/stallion-1.0.1.tar.gz

If you are using the EasyIO or EasyConnection 8/32 boards then you don't
need this package. Although it does have a handy script to create the
/dev device nodes for these boards.

If you require DIP switch settings, EISA/MCA configuration files, or any
other information related to Stallion boards then have a look at
http://www.stallion.com.



2. INSTALLATION

The drivers can be used as loadable modules or compiled into the kernel.
You can choose which when doing a "make config" on the kernel.

All ISA, EISA and MCA boards that you want to use need to be entered into
the driver(s) configuration structures. All PCI boards will be automatically
detected when you load the driver - so they do not need to be entered into
the driver(s) configuration structure. (Note that kernel PCI BIOS32 support
is required to use PCI boards.)

Entering ISA, EISA and MCA boards into the driver(s) configuration structure
involves editing the driver(s) source file. It's pretty easy if you follow
the instructions below. Both drivers can support up to 4 boards. The smart
card driver (the stallion.c driver) supports any combination of EasyIO and
EasyConnection 8/32 boards (up to a total of 4). The intelligent driver
supports any combination of ONboards, Brumbys, Stallions and EasyConnection
8/64 boards (up to a total of 4).

To set up the driver(s) for the boards that you want to use you need to
edit the appropriate driver file and add configuration entries.

If using EasyIO or EasyConnection 8/32 ISA or MCA boards, do:
   vi stallion.c
      - find the definition of the stl_brdconf array (of structures)
        near the top of the file
      - modify this to match the boards you are going to install
        (the comments before this structure should help)
      - save and exit

If using ONboard, Brumby, Stallion or EasyConnection 8/64 boards then do:
   vi istallion.c
      - find the definition of the stli_brdconf array (of structures)
        near the top of the file
      - modify this to match the boards you are going to install
        (the comments before this structure should help)
      - save and exit

Once you have set up the board configurations then you are ready to build
the kernel or modules.

When the new kernel is booted, or the loadable module loaded then the
driver will emit some kernel trace messages about whether the configured
boards where detected or not. Depending on how your system logger is set
up these may come out on the console, or just be logged to
/var/adm/messages. You should check the messages to confirm that all is well.


2.1 SHARING INTERRUPTS

It is possible to share interrupts between multiple EasyIO and
EasyConnection 8/32 boards in an EISA system. To do this you will need to
do a couple of things:

1. When entering the board resources into the stallion.c file you need to
   mark the boards as using level triggered interrupts. Do this by replacing
   the "0" entry at field position 6 (the last field) in the board
   configuration structure with a "1". (This is the structure that defines
   the board type, I/O locations, etc. for each board). All boards that are
   sharing an interrupt must be set this way, and each board should have the
   same interrupt number specified here as well. Now build the module or
   kernel as you would normally.

2. When physically installing the boards into the system you must enter
   the system EISA configuration utility. You will need to install the EISA
   configuration files for *all* the EasyIO and EasyConnection 8/32 boards
   that are sharing interrupts. The Stallion EasyIO and EasyConnection 8/32
   EISA configuration files required are supplied by Stallion Technologies
   on the DOS Utilities floppy (usually supplied in the box with the board
   when purchased. If not, you can pick it up from Stallion's FTP site,
   ftp.stallion.com). You will need to edit the board resources to choose
   level triggered interrupts, and make sure to set each board's interrupt
   to the same IRQ number.

You must complete both the above steps for this to work. When you reboot
or load the driver your EasyIO and EasyConnection 8/32 boards will be
sharing interrupts.


2.2 USING HIGH SHARED MEMORY

The EasyConnection 8/64-EI, ONboard and Stallion boards are capable of
using shared memory addresses above the usual 640K - 1Mb range. The ONboard
ISA and the Stallion boards can be programmed to use memory addresses up to
16Mb (the ISA bus addressing limit), and the EasyConnection 8/64-EI and
ONboard/E can be programmed for memory addresses up to 4Gb (the EISA bus
addressing limit).

The istallion intelligent driver does offer support for these higher memory
addresses with a couple of limitations. The higher memory support can only
be used in the loadable module form of the driver, since the kernel memory
management routines it relies on can not be run from the drivers static
kernel init routine.

By default, support for these higher memory addresses is not compiled into
the driver. This is because it relies on kernel functions that are not
normally exported as part of the Linux loadable module system.

To add the appropriate symbols into the kernel export code you need to:

1. cd /usr/src/linux/kernel
   (assuming your Linux kernel code is in /usr/src/linux)
2. vi ksyms.c
   - find the line that reads
        X(vfree),
   - after this line insert the following line
        X(remap_page_range),
   - save and exit
3. cd ..
4. build a new kernel (usually just make)

This will export the "remap_page_range" function for loadable modules
which is required for the higher memory support code.

Finally you need to enable the code in the istallion driver. To do this
edit the istallion.c file and search for the symbol STLI_HIMEMORY. It is
near the top of the file in a line that looks like:

#define STLI_HIMEMORY   0

Change the "0" to a "1". This enables the high memory support code in
the driver. You will then need to rebuild the module or rebuild the
kernel to incorporate the change. You will also need to modify
the board resource configuration information to use a higher memory
address.

Once these changes are in place the driver will work as it did before.
Note that the physical memory address range is software programmed on the
EasyConnection 8/64-EI and ONboards, but must be set via DIP switches on
the original Stallion boards.


2.3 TROUBLE SHOOTING

If a board is not found by the driver but is actually in the system then the
most likely problem is that the I/O address is wrong. Change it in the driver
stallion.c or istallion.c configuration structure and rebuild the kernel or
modules, or change it on the board. 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 stallion.c configuration structure.
There are no interrupts to worry about for ONboard, Brumby, Stallion or
EasyConnection 8/64 boards. The memory region on EasyConnection 8/64 and
ONboard boards is software programmable, but not on the Brumbys or Stallions.



3. USING THE DRIVERS

3.1 INTELLIGENT DRIVER OPERATION

The intelligent boards also need to have their "firmware" code downloaded
to them. This is done via a user level application supplied in the driver
package called "stlload". Compile this program where ever you dropped the
package files, by typing "make". In its simplest form you can then type
    ./stlload -i cdk.sys
in this directory and that will download board 0 (assuming board 0 is an
EasyConnection 8/64 board). To download to an ONboard, Brumby or Stallion do:
    ./stlload -i 2681.sys

Normally you would want all boards to be downloaded as part of the standard
system startup. To achieve this, add one of the lines above into the
/etc/rc.d/rc.S or /etc/rc.d/rc.serial file. To download each board just add
the "-b <brd-number>" option to the line. You will need to download code for
every board. You should probably move the stlload program into a system
directory, such as /usr/sbin. Also, the default location of the cdk.sys image
file in the stlload down-loader is /usr/lib/stallion. Create that directory
and put the cdk.sys and 2681.sys files in it. (It's a convenient place to put
them anyway). As an example your /etc/rc.d/rc.S file might have the
following lines added to it (if you had 3 boards):
    /usr/sbin/stlload -b 0 -i /usr/lib/stallion/cdk.sys
    /usr/sbin/stlload -b 1 -i /usr/lib/stallion/2681.sys
    /usr/sbin/stlload -b 2 -i /usr/lib/stallion/2681.sys

The image files cdk.sys and 2681.sys are specific to the board types. The
cdk.sys will only function correctly on an EasyConnection 8/64 board. Similarly
the 2681.sys image fill only operate on ONboard, Brumby and Stallion boards.
If you load the wrong image file into a board it will fail to start up, and
of course the ports will not be operational!

If you are using the modularized version of the driver you might want to put
the insmod calls in the startup script as well (before the download lines
obviously).


3.2 USING THE SERIAL PORTS

Once the driver is installed you will need to setup some device nodes to
access the serial ports. The simplest method is to use the stallion utility
"mkdevnods" script. It will automatically create all possible device entries
required for all 4 boards. This will create the normal serial port devices as
/dev/ttyE# where # is the port number starting from 0. A bank of 64 minor
device numbers is allocated to each board, so the first port on the second
board is port 64, etc. A set of callout type devices is also created. They
are created as the devices /dev/cue# where # is the same as for the ttyE
devices.

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

If you look at the driver code you will notice that it is fairly closely
based on the Linux serial driver (linux/drivers/char/serial.c). This is
intentional, obviously this is the easiest way to emulate its behavior!

Since this driver tries to emulate the standard serial ports as much as
possible, most system utilities should work as they do for the standard
COM ports. Most importantly "stty" works as expected and "setserial" can be
also be used (excepting the ability to auto-configure the I/O and IRQ
addresses of boards). Higher baud rates are supported in the
usual fashion through setserial or using the CBAUDEX extensions. Note that
the EasyIO and EasyConnection (all types) support 57600 and 115200 baud. The
older boards including ONboard, Brumby and the original Stallion support a
maximum baud rate of 38400.

If you are unfamiliar with how to use serial ports, then get the Serial-HOWTO
by Greg Hankins. It will explain everything you need to know!



4. NOTES

You can use both drivers at once if you have a mix of board types installed
in a system. However to do this you will need to change the major numbers
used by one of the drivers. Currently both drivers use major numbers 24 and
25 for their port devices. Change one driver to use some other major numbers,
and then modify the mkdevnods script to make device nodes based on those new
major numbers. For example, you could change the stallion.c driver to use
major numbers 30 and 31 (don't use 28, it's used by istallion.c driver for its
sio memory device!). You will also need to create device nodes with different
names for the ports...

Finding a free physical memory address range can be a problem. The older
boards like the Stallion and ONboard need large areas (64K or even 128K), so
they can be very difficult to get into a system. If you have 16 Mb of RAM
then you have no choice but to put them somewhere in the 640K -> 1Mb range.
ONboards require 64K, so typically 0xd0000 is good, or 0xe0000 on some
systems. If you have an original Stallion board, "V4.0" or Rev.O,
then you need a 64K memory address space, so again 0xd0000 and 0xe0000 are
good. Older Stallion boards are a much bigger problem. They need 128K of
address space and must be on a 128K boundary. If you don't have a VGA card
then 0xc0000 might be usable - there is really no other place you can put
them below 1Mb.

Both the ONboard and old Stallion boards can use higher memory addresses as
well, but you must have less than 16Mb of RAM to be able to use them. Usual
high memory addresses used include 0xec0000 and 0xf00000.

The Brumby boards only require 16Kb of address space, so you can usually
squeeze them in somewhere. Common addresses are 0xc8000, 0xcc000, or in
the 0xd0000 range. EasyConnection 8/64 boards are even better, they only
require 4Kb of address space, again usually 0xc8000, 0xcc000 or 0xd0000
are good.

If you are using an EasyConnection 8/64-EI or ONboard/E then usually the
0xd0000 or 0xe0000 ranges are the best options below 1Mb. If neither of
them can be used then the high memory support to use the really high address
ranges is the best option. Typically the 2Gb range is convenient for them,
and gets them well out of the way.

There is a new utility program in the stallion utility package called
"stlstty". Most people will not need to use this. If you have an ONboard/16
which has partial signals on the upper 12 ports then this program can be used
to set the upper ports to have modem control instead of hardware flow control.
Use the "mapcts maprts" flag options to this utility on the port(s) that you
wish to do this mapping on, eg
    ./stlstty maprts mapcts < /dev/cue0
This enables RTS to act like DTR and CTS to act like DCD on the specified
port.

The ports of the EasyIO-8M board do not have DCD or DTR signals. So these
ports cannot be used as real modem devices. Generally when using these
ports you should only use the cueX devices.

There is another new utility in this package that reports statistics on
the serial ports. You will need to have the curses libray installed on
your system to build it.

To build the statistics display program type:
    make stlstats
Once compiled simply run it (you will need to be root) and it will display
a port summary for the first board and panel installed. Use the digits to
select different board numbers, or 'n' to cycle through the panels on a
board. To look at detailed port information then hit 'p', that will display
detailed port 0 information. Use the digits and letteres 'a' through 'f' to
select the different ports (on this board and panel).



5. DISCLAIMER

I do not speak for Stallion Technologies in any capacity, officially or
unofficially.

/* */