patch-1.3.64 linux/drivers/char/README.stallion

• Lines: 321
• Date: Thu Feb 15 12:07:35 1996
• Orig file: v1.3.63/linux/drivers/char/README.stallion
• Orig date: Thu Jan 1 02:00:00 1970

diff -u --recursive --new-file v1.3.63/linux/drivers/char/README.stallion linux/drivers/char/README.stallion
@@ -0,0 +1,320 @@
+
+Stallion Multiport Serial Drivers
+---------------------------------
+
+Version: 1.0.2
+Date:    01FEB96
+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 embedded 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
+/usr/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.
+
+
+
+5. DISCLAIMER
+
+I do not speak for Stallion Technologies in any capacity, officially or
+unofficially.
+