Contents:
Install
EasyConnection Software
Using
the Drivers
Important:
The drivers included in this package are intended as a replacement for
those shipped with the stable Linux kernel versions in the 2.0. x and
2.2.x series. The driver source in this package is generally the
latest, and provides support for more recent Stallion hardware and bug
fixes. There is no driver support in this package for kernel versions
older than 2.0.0.
The other utilities supplied in this package
can be used with Stallion drivers on any version of the kernel.
Please note the disclaimers set out in the GNU
general public license included with this driver package. All
host driver source is included in this package, and is copyrighted
under the GNU GPL. The board "firmware" code in this package is
copyright Stallion Technologies (i.e. The files cdk.sys and 2681.sys).
Installing
EasyConnection Software
If you are using a kernel provided by your installation
distribution, then you may have the Stallion drivers installed as modules
on your system already. Typically these will be in the /lib/modules/2.x.y/misc
directory, where 2.x.y is the kernel version number. To use these
drivers, jump to the "Loadable Modules"
section.
To install Stallion Driver files from the
CD ROM:
Step 1.
Mount /dev/cdrom /mnt
Step 2.
cd /usr/src
Step
3.
Extract the files using the tar command, eg. tar xvf /mnt/drivers/easyconnect/linux/v550.tar
Step 4.
This creates a directory containing the driver source files, e.g..
stallion-5.5.0
Step 5.
Change to the appropriate directory, e.g.. cd stallion-5.5.0
Step 6.
Copy the new driver source into the kernel source tree. Firstly,
copy all the header files:
cp
stallion.h cd1400.h sc26198.h /usr/include/linux/include/linux
cp istallion.h cdk.h
comstats.h /usr/include/linux/include/linux
Then
copy the appropriate driver source version for your kernel.
If you
are using a kernel version 2.0.x then do:
cp
stallion.c-2.0.X /usr/src/linux/drivers/char/stallion.c
cp istallion.c-2.0.X
/usr/src/linux/drivers/char/istallion.c
Or
if you are using a 2.2.X kernel version then do:
cp.stallion.c-2.2.X
/usr/src/linux/drivers/char/stallion.c
cp istallion.c-2.2.X
/usr/src/linux/drivers/char/istallion.c
The drivers can be used as loadable modules
or compiled into the kernel. Depending on which form of driver loading
you decide to use, the installation procedure will be slightly different.
All ISA, EISA and MCA boards need to be entered
into the driver(s) configuration structures. 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: Kernel PCI BIOS 32 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.
The following table lists all EasyConnection Board Types and the
appropriate driver to be used for each.
Board
Identification Table
Loadable
Module Drivers
If you are not using a pre-built Stallion driver
module, then build the module. You will need the gcc compiler
and make installed on your system to make the driver modules.
You will also need to have installed the kernel source (located in /usr/src/linux)
on the system, and have at least performed a 'make config'
and 'make dep'.
You may want to read the kernel source README file, usually found
in /usr/src/linux.
At the top of the Linux kernel source tree do:
make
modules
You must have configured your kernel source
with the Stallion drivers as modules.
Typically, to load up the smart board driver
use:
insmod
stallion.o
It
will output a message to say that it loaded, and print the driver version
number. It will also print out whether it found the configured
boards or not. These messages may not appear on the console, but
typically are always logged to /var/adm/messages or /var/log/syslog
files - depending on how the klogd and syslog daemons are set up on
your system.
To
load the intelligent board use:
insmod
istallion.o
It
will output similar messages to the smart board driver.
If
not using an auto detectable board type (that is a PCI board) then you
will also need to supply command line arguments to the "insmod" command
when loading the driver. To review board types, go to the Board
Identification Table.
The general
form of the configuration argument is:
board?=<name>[,<ioaddr>[,<addr>]
[,<irq>]]
where:
board? - specifies the arbitrary board
number of this board, can be in the range of 0 to 3.
name - textual name of this board.
The board name is the common board name, or any "shortened" version
of that. The board type number may also be used here.
ioaddr - specifies the I/O address
of this board. This argument is optional, but should generally
be specified.
addr - optional second address argument.
Some board types require a second I/O address, some require a memory
address. The exact meaning of this argument depends upon the
board type.
irq - optional IRQ line used by this
board.
Up to 4 board configuration arguments can be
specified on the load line.
Here are some examples:
insmod
istallion.o board3=ec8/64,0x2c0,0xcc000
This configures an EasyConnection 8/64 ISA board
at I/o address 0x2c0 at memory address 0xcc000.
insmod
stallion.o board1=ec8/32-at,0x2a0,0x280,10
This configures an EasyConnection 8/32 ISA board
at primary I/O address 0x2a0, secondary address 0x280 and IRQ 10.
You will probably want to enter this module
load and configuration information into your system startup scripts
so that the drivers are loaded and configured on each system boot.
Typically the startup script would be something like:
/etc/rd.c.d/rc.modules.
Static
Drivers (kernel linked)
You will need to build a new kernel to link
in the Stallion drivers. The first thing you need is to have the
full kernel source. Most people will have this. The following
assumes that the kernel source is in /usr/src/linux.
To review
board types, go to the Board Identification
Table.
Jump to Step
3 if installing any PCI model EasyConnection board.
To install the drivers, perform the following:
Step 1.
Enter the following command: cd
/usr/src/linux/drivers/char
Step 2.
Setup the driver configuration for the boards. If installing
a smart board (EasyConnection 8/32), use an editor (for example vi)
to perform the following:
vi stallion.c
- find the definition of the stl_brdconf array (of structures) near
top of the file
- modify this to match the boards you are going to install
- save and exit
If installing an intelligent board (EasyConnection
8/64 board), use an editor (for example vi) to perform the following:
vi istallion.c
- find the definition of the stli_brdconf array (of structures)
near top of the file
- modify this to match the boards to be installed
For example:
static stlconf_t stl_brdconf[] = {
{ BRD_ECH, 0x2a8, 0x280, 0, 12, 0 }
};
- save and exit
Step
3.
Enter the following command: cd /usr/src/linux
Step 4.
Build a new kernel. If you haven't done this before read the README
file in /usr/src/linux.
Once you have a new kernel built, reboot the system to load the new
kernel. On startup the driver will output a message to say it is operational
(with the driver version number). It will also print out if it could
find the boards listed in its configuration structure or not.
Check this output carefully to verify
that the boards you have configured have actually been found.
Intelligent
Driver Operation
All of the intelligent board types need to have
their `firmware' code downloaded into the card. This is done via a user
level application supplied in the driver package called `stlload'. Compile
this program where ever the Stallion driver files were created, e.g..
/usr/src/stallion-5.4.2, by using the `make' command, e.g..
make
stlload
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).
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. It is recommended
to 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 file in it.
As an example your /etc/rc.d/rc.S file might have the following line
added to it:
/usr/sbin/stlload
-b 0 -i /usr/lib/stallion/cdk.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. The 2681.sys will only function correctly on the Brumby
and ONboard cards. 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 loadable module version of the driver, consider
putting the insmod calls in the startup script as well (before
the download lines obviously).
Sharing
Interrupts
As mentioned in the introduction, it is possible
for multiple EasyConnection 8/32 cards to share the same interrupt in
an EISA system.
Step 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.
Step 2.
When physically installing the boards into the system you must enter
the system EISA configuration utility on rebooting. You will need
to install the EISA configuration files for all of the EasyConnection
8/32 boards that are sharing interrupts. The Stallion EasyConnection
8/32 EISA configuration files required are supplied on this CD.
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 EasyConnection
8/32 board(s) will be sharing interrupts.
Using
High Shared Memory
The EasyConnection 8/64-EI board is capable
of using shared memory addresses above the usual 640K - 1Mb range. The
EasyConnection 8/64-EI can be programmed for memory addresses up to
4Gb (the EISA bus addressing limit).
The istallion driver offers direct support
for these higher memory regions. To use them just enter the high memory
address as if it were a low memory address (in the driver board configuration
structure).
LINUX
Kernel Versions Other than 2.0.X and 2.2.X
There may be some minor differences between
the driver source code in this package and that in the Linux kernel
source. This will be due to changes needed in the drivers so that they
work correctly on newer kernels.
The driver source included in this package is
intended for use with 2.0.X and 2.2.X series kernels. If you have a
kernel version 2.3.0 or later, then use the source provided with the
kernel - it will be more up to date. Stallion Technologies regularly
submits the latest driver source to be included in the new kernel source
releases.
Troubleshooting
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 the module load arguments or change the resources
in the driver stallion.c or istallion.c configuration structure and
rebuild the kernel.
Alternatively, you can change the DIP switches
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 module load argument or in the
stallion.c configuration structure. There are no interrupts to
worry about for EasyConnection 8/64 boards.
Using
the Drivers
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 one board. This will create the normal serial port devices as /dev/ttyE#
where # is the port number starting from 0. A set of callout type devices
is also created. They are created as the devices /dev/cue# where
# is the same as the ttyE devices.
All possible 64 device modes are created for
each board, regardless of the actual number of ports on the board. To
create device nodes for ports on multiple boards supply a number of
boards argument to the `mkdevnods' script. For example to create nodes
for four boards use mkdevnods 4. This means that the first port on the
second board is port 64, the first port on the third board is 128, etc.
The Stallion driver emulates the standard PC
system COM ports and the standard Linux serial driver. You can use Stallion
board ports and COM ports interchangeably without modifying anything
but the device name.
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 way through setserial or using the CBAUDEX extensions.
Note that all of the EasyConnection cards support speeds of 57600 and
115200 bps. The XP panels also support speeds of 230400 and 460300 bps.
This driver should work with anything that works
on standard Linux serial ports. It has been used on the following devices
under Linux:
· Standard dumb terminals (using agetty,
getty)
· Serial mice (under X)
· Modems (using cu, uucp, minicom,
seyon, uugetty)
· slip and ppp connections
Notes
The major device numbers used by this driver
conform to the Linux Device Registry, so they should not clash with
any other devices. Also the device naming scheme is the `standard' used
by most Linux serial port devices.
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, 25 and 28 for their 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 istallion.c driver to use major numbers 60, 61
and 62. You will also need to create device nodes with different names
for the ports, for example ttyF# and cuf#.
Finding a free physical memory address range
can be a problem. If you have 16 Mb of RAM then you have no choice but
to put them somewhere in the 640K -> 1Mb range. If you don't have a
VGA card then 0xc0000 might be usable - there is no other place you
can put them below 1Mb.
EasyConnection 8/64 boards only require 4Kb
of address space, again usually 0xc8000, 0xcc000 or 0xd0000 are good.
If you are using an EasyConnection 8/64-EI 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 included called
`stlstty'. Most people will not need to use this. Use the `mapcts maprts'
flag options to this utility on the port(s) that you wish to do this
mapping on, e.g. ./stlstty maprts mapcts < /dev/cue0 This enables
RTS to act like DTR and CTS to act like DCD on the specified port.
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 letters `a' through `f' to select the different ports (on
this board and panel).
