Import kernel parts of the v0.0.5alpha Stallion driver(s).

This is now two seperate drivers that support (I think) all of Stallions's
range, including the high performance intelligent cards, and their older
cards.

Submitted by: Greg Ungerer (gerg@stallion.oz.au)

(User-mode parts and patches to follow)

1 files changed, 304 insertions, 56 deletions

diff --git a/sys/i386/isa/README.stl b/sys/i386/isa/README.stl
index 0bcd728..4beba66 100644
--- a/sys/i386/isa/README.stl
+++ b/sys/i386/isa/README.stl
@@ -2,8 +2,8 @@
 Stallion Multiport Serial Driver Readme
 ---------------------------------------
 
-Version: 0.0.4 alpha
-Date:    06FEB96
+Version: 0.0.5 alpha
+Date:    20MAR96
 Author:  Greg Ungerer (gerg@stallion.oz.au)
 
 
@@ -16,50 +16,122 @@ 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.
+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.)
 
-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 package actually contains two drivers. One is for the true Stallion
+intelligent multiport boards, and the other is for the smart range of boards.
+
+All host driver source is included in this package, and is copyrighted under
+a BSD style copyright. The board "firmware" code in this package is copyright
+Stallion Technologies (the files cdk.sys and 2681.sys).
+
+
+1.1 SMART MULTIPORT BOARD DRIVER
 
 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).
+These boards are not classic 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. Each EasyIO board requires 8
-bytes of IO address space and 1 interrupt. On an EISA system it is possible
+bytes of I/O 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.
+connectors, and the EasyIO-8 comes with a dongle cable with 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
+port modules that contain either 8 or 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 and RS-485
+ports. The EasyConnection 8/32 boards come in ISA, PCI 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 ISA
+EasyConnection 8/32 board requires two separate I/O address ranges, one two
+bytes in size and a secondary region of 32 bytes. Each PCI EasyConnection
+8/32 requires two regions of I/O address space, normally these will be
+automatically allocated by the system BIOS at system power on time. Each MCA
+EasyConnection board requires one I/O address region 64 bytes in size. All
+board types also require one interrupt. On EISA systems multiple boards can
+share one interrupt. The secondary I/O range of the ISA board (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...
 
-
-1.1 HOW TO GET BOARDS
+1.2 INTELLIGENT MULTIPORT BOARD DRIVER
+
+This driver is for Stallion's range of true intelligent multiport boards.
+It supports the EasyConnection 8/64, ONboard, Brumby and original Stallion
+families of multiport boards. The EasyConnection 8/64 and ONboard boards come
+in ISA, EISA and Microchannel bus versions. The Brumby and Stallion boards
+are only available in ISA versions.
+
+The EasyConnection 8/64 family of boards is a medium cost, high performance,
+modular range of intelligent multiport serial boards. The EasyConnection 8/64
+boards can be configured to have from 8 to 64 serial ports by plugging in
+external serial port modules that contain either 8 or 16 ports each (these
+modules are the same used by the EasyConnection 8/32 board). 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 and
+RS-485 ports. 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/64 board requires 4 bytes of I/O address space and a region
+of memory space. The size of the memory region required depends on the exact
+board type. The EISA version requires 64 Kbytes of address space (that can
+reside anywhere in the 4 Gigabyte physical address space). The ISA and MCA
+boards require 4 Kbytes of address space (which must reside in the lower
+1 Mbyte of physical address space - typically in the c8000 to e0000 range).
+No interrupts are required. The physical memory region of multiple
+EasyConnection 8/64 boards can be shared, but each board must have a separate
+I/O address space.
+
+The ONboard family of boards are traditional intelligent multiport serial
+boards. They are Stallion's older range of boards with a limited expansion
+capability. They come in 4, 8, 12, 16 and 32 port versions. The board uses
+the same base card (which has 4 ports on it) and is expanded to more ports
+via a mezzanine board that attaches directly onto the board. External panels
+plug into the ONboard providing RS-232C ports with DB-25 plugs. An RS-422
+DB-25 dual interface panel is also available. The ISA and microchannel
+ONboards require 16 bytes of I/O address space and 64K bytes of memory
+space. The memory space can be anywhere in the 16 Mbyte ISA bus address
+range. No interrupt is required. The EISA ONboard requires 64 Kbytes of
+memory space that can be anywhere in the 4 Gigabyte physical address space.
+All ONboard boards can share their memory region with other ONboards (or
+EasyConnection 8/64 boards).
+
+The Brumby family of boards are traditional, low cost intelligent multiport
+serial boards. They are non-expandable and come in 4, 8 and 16 port versions.
+They are only available for the ISA bus. The serial ports are all on DB-25
+"dongle" cables that attach to the rear of the board. Each Brumby board
+requires 16 bytes of I/O address space and 16 Kbytes of memory space. No
+interrupts are required.
+
+The original Stallion boards are old. They went out of production some years
+back. They offer limited expandability and are available in 8 or 16 port
+configurations. An external panel houses 16 RS-232C ports with DB-9
+connectors. They require 16 bytes of I/O address space, and either 64K or
+128K of memory space. No interrupt is required. I will not actively support
+these boards, although they will work with the driver.
+
+That's the boards supported by the second driver. The ONboard, Brumby and
+Stallion boards are Stallion's older range of intelligent multiports - so
+there are lots of them around. They only support a maximum baud rate of
+38400. The EasyConnection 8/64 is a true high performance intelligent
+multiport board, having much greater throughput than any of Stallion's
+older boards. It also supports speeds up to 115200 baud.
+
+
+1.3 HOW TO GET BOARDS
 
 Stallion Technologies has offices all over the world, as well as many more
 distributors and resellers. To find out about local availability please
@@ -83,24 +155,37 @@ 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, with any combination of EasyIO and
-EasyConnection 8/32 boards. So there is a theoretical maximum of 256 ports.
+The drivers can support up to 8 boards. For the smart board driver any
+combination of EasyIO and EasyConnection 8/32 boards can be installed. For
+the intelligent any combination of EasyConnection 8/64, ONboard, Brumby or
+original Stallion. So there is a theoretical maximum of 512 ports.
 (Off-course I have not tested a system with this many!)
 
-Instructions to install:
+
+2.1 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
+        cp stallion.c istallion.c cdk.h comstats.h /usr/src/sys/i386/isa
+        cp scd1400.h /usr/src/sys/i386/isa/ic
 
    Note: if you are NOT using FreeBSD 2.1.0 then you will need to edit the
-   stallion.c file and change the VFREEBSD define to match your version.
+   stallion.c and istallion.c files and change the VFREEBSD define to match
+   your version.
 
-2. (Note: skip to next step if on a FreeBSD kernel later than 2.1.0)
-   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:
+2. Skip to next step if on a FreeBSD kernel later than 2.1.0.
+   Add a character device switch table entry for the driver that you which
+   to use into the cdevsw table structure. This involves adding some code
+   into the kernel conf.c file. 
+
+   If you are using an EasyIO or EasyConnection 8/32 then you need to use
+   the stallion.c driver. All other board types (EasyConnection 8/64,
+   ONboard, Brumby, Stallion) use the istallion.c driver. You can also have
+   a mix of boards using both drivers. You will need to use a different
+   major device number for the second driver though (not the default 72 -
+   see below for more details on this).
+
+2.1. If using the stallion.c driver then do:
 
         cd /usr/src/sys/i386/i386
         vi conf.c
@@ -145,12 +230,60 @@ d_ttycv_t	stldevtotty;
               
             - save the file and exit vi.
 
+
+2.2. If using the istallion.c driver then do:
+
+        cd /usr/src/sys/i386/i386
+        vi conf.c
+            - add the following lines (in 2.1 I put them at line 729):
+
+/* Stallion Intelligent Multiport Serial Driver */
+#include "stl.h"
+#if	NSTL > 0
+d_open_t        stliopen;
+d_close_t       stliclose;
+d_read_t        stliread;
+d_write_t       stliwrite;
+d_ioctl_t	stliioctl;
+d_stop_t        stlistop;
+d_ttycv_t	stlidevtotty;
+#define stlireset	nxreset
+#define	stlimmap	nxmmap
+#define stlistrategy	nxstrategy
+#else
+#define	stliopen	nxopen
+#define stliclose	nxclose
+#define stliread	nxread
+#define stliwrite	nxwrite
+#define stliioctl	nxioctl
+#define stlistop	nxstop
+#define stlireset	nxreset
+#define stlimmap	nxmmap
+#define stlistrategy	nxstrategy
+#define	stlidevtotty	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):
+
+	{ stliopen,	stliclose,	stliread,     stliwrite,	/*72*/
+	  stliioctl,	stlistop,	stlireset,    stlidevtotty,/*istallion*/
+	  ttselect,	stlimmap,	stlistrategy },
+
+            - 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):
+            - add the following definition lines into the list (it is stored
+              alphabetically, so insert them appropriately):
+
+i386/isa/istallion.c		optional	stli	device-driver
 
 i386/isa/stallion.c		optional	stl	device-driver
 
@@ -166,13 +299,33 @@ i386/isa/stallion.c		optional	stl	device-driver
             - if only using ECH-PCI boards then you don't need to enter a
               configuration line, the kernel will automatically detect
               the board at boot up, so skip to step 5.
-            - enter a line for each board that you want to use, eg:
+            - enter a line for each board that you want to use. For stallion.c
+              boards entries should look like:
 
 device		stl0	at isa? port 0x2a0 tty irq 10 vector stlintr
 
+              For istallion.c boards, the entries should look like:
+
+device		stli0	at isa? port 0x2a0 tty iomem 0xcc000 iosiz 0x1000 flags 23
+
               (I suggest you put them after the sio? entries)
               (Don't enter lines for ECH-PCI boards)
-            - change the io address and irq in this line as required
+            - change the entry resources as required. For the Stallion.c
+              entries this may involve changing the port address or irq.
+              For the istallion.c entries this may involve changing the port
+              address, iomem address, iosiz value and the flags. Select from
+              the following table for appropriate flags and iosiz values for
+              your board type:
+
+              EasyConnection 8/64 ISA:     flags 23         iosiz 0x1000
+              EasyConnection 8/64 EISA:    flags 24         iosiz 0x10000
+              EasyConnection 8/64 MCA:     flags 25         iosiz 0x1000
+              ONboard ISA:                 flags 4          iosiz 0x10000
+              ONboard EISA:                flags 7          iosiz 0x10000
+              ONboard MCA:                 flags 3          iosiz 0x10000
+              Brumby:                      flags 2          iosiz 0x4000
+              Stallion:                    flags 1          iosiz 0x10000
+
             - save the file and exit
 
 5. Build a new kernel using this configuration.
@@ -187,23 +340,60 @@ device		stl0	at isa? port 0x2a0 tty irq 10 vector stlintr
 
 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
+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.
+most likely problem is that the IO address is incorrect. 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
+coded 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.
 
+On intelligent boards it is possible that the board shared memory region is
+clashing with that of some other device. Check for this and change the device
+or kernel configuration as required.
+
+
+2.2 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.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.serial 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 will 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!
+
 
 
 3. USING THE DRIVER
@@ -220,8 +410,8 @@ 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
+where X is the port number. (The second boards ports will start from ttyE64,
+the third boards from ttyE128, 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
@@ -246,11 +436,69 @@ under FreeBSD:
 
 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!
-
-I will probably also add LKM support some time soon.
+Be aware that these drivers are still very new, so there is sure to be some
+bugs in them. Please email me any feedback on bugs, problems, or even good
+experiences with these drivers!
+
+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 number used
+by one of the drivers. Currently both drivers use default major number 72 for
+their devices. Change one driver to use some other major number (how this is
+achieved will depend on the kernel version you are using), 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 number 73. You
+will also need to create device nodes with different names for the ports, for
+eg ttyFXXX.
+
+Currently the intelligent board driver (istallion.c) does not have the
+ability to share a boards memory region with other boards (you can only do
+this on EasyConnection 8/64 and ONboards normally anyway). It also does
+not currently support any memory address ranges above the low 1Mb region.
+These will be fixed in a future release of the driver.
+
+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.
+
+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 a new utility in this package that reports statistics on the
+serial ports. You will need to have the ncurses library 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 letters 'a' through 'f' to
+select the different ports (on this board and panel).