FreeBSD/Linux Kernel Cross Reference
sys/i386/isa/README.stl

     $FreeBSD$
     
     Stallion Multiport Serial Driver Readme
     ---------------------------------------
     
     Version: 2.0.0
     Date:    22JAN98
     Author:  Greg Ungerer (gerg@stallion.com)
     
    
    
    1. INTRODUCTION
    
    This is a set of FreeBSD drivers for most of the Stallion Technologies
    range of multiport serial boards.
    
    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 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, EasyConnection 8/32 and EasyConnection
    8/64-PCI range of boards. These boards are not classic intelligent multiport
    boards, but are host based multiport boards that use Cirrus Logic CL-CD1400
    UART's, or on newer versions of the hardware use the Signetics 26C198 UART.
    Both of these are high performance UART's with built in FIFO's, automatic
    flow control and a host of other features.
    
    The EasyIO range of cards comes in 4 forms, the EasyIO-4, EasyIO-8,
    EasyIO-8M and EasyIO-8-PCI. The first three are ISA based boards while
    the last is a PCI bus board. All of these are non-expandable, low cost,
    multiport boards with 4 or 8 RS-232C ports. Each ISA EasyIO board requires 8
    bytes of I/O address space and 1 interrupt. The PCI EasyIO board uses 64
    bytes of I/O address space and 1 interrupt. On EISA and PCI systems 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 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 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 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.
    
    The EasyConnection 8/64-PCI family is similar to the EasyConnection 8/32-PCI
    board, and uses the same external modules. It is supported by the smart
    board driver - not the intelligent board driver. It uses 2 regions of I/O
    address space, both 64 bytes in size, and 1 interrupt.
    
    
    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 and Brumby families of multiport
    boards. The EasyConnection 8/64 and ONboard boards come in ISA, EISA and
    Microchannel bus versions. The Brumby boards are only available in ISA
    versions. This driver can also work with the original Stallion board, but
    these are no longer supported by Stallion Technologies.
    
    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.
   
   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 base card. 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 and are no longer supported. 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.
   
   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 460800 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
   contact the nearest Stallion office and they can give you all the information
   you need. Look in the "Offices" file in the driver package for a current list
   of Stallion Technologies offices.
   
   Another good source of information about the Stallion range of boards and
   local availability is on the Stallion Web page. Check it out at
   http://www.stallion.com.
   
   
   
   2. INSTALLATION
   
   This driver, as is, will work on a FreeBSD 2.2.5 system. It will run on any
   FreeBSD system version 2.0.5 and up, including -current version systems.
   For systems other than 2.2.0 and 2.2.5  you will need to change the version
   define in the driver source. Look for the symbol name VFREEBSD, then change
   it to match the version number of your FreeBSD system (for example 2.2.5 is
   225, 3.0.0 would be 300, etc).
   
   Recent versions of FreeBSD 2.1.5 and above include the Stallion drivers
   in the distribution. You may still need to use this source for these systems.
   If the code in this package is newer than the version enclosed on your
   FreeBSD installation then you should use this source instead.
   
   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 drivers can support up to 8 boards. For the smart board driver any
   combination of EasyIO, EasyConnection 8/32 and EasyConnection 8/64-PCI
   boards can be installed. For the intelligent any combination of
   EasyConnection 8/64 (ISA and EISA), ONboard, Brumby or original Stallion.
   So there is a theoretical maximum of 512 ports.
   
   2.1 Instructions to install:
   
   1. Copy the driver source files into the kernel source tree.
   
           cp stallion.c istallion.c /usr/src/sys/i386/isa
           cp cdk.h comstats.h /usr/src/sys/i386/include
           cp scd1400.h sc26198.h /usr/src/sys/i386/isa/ic
   
      Note: if you are NOT using FreeBSD 2.2.5 then you will need to edit the
      stallion.c and istallion.c files and change the VFREEBSD define to match
      your version. This define is near the top of the file, and should be
      easy to find.
   
   2. If you are using FreeBSD version 2.2.0 or above then jump to step 4 now.
   
      Add a character device switch table entry for the driver that you wish
      to use into the cdevsw table structure. This involves adding some code
      into the kernel conf.c file. 
   
      If you are using an EasyIO, EasyConnection 8/32 or EasyConnection 8/64-PCI
      then you need to use the stallion.c driver. All other board types
      (EasyConnection 8/64 (ISA and EISA), 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
               - add the following lines (in 2.1.0 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.
   
   
   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.0 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 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
   
               - 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
               - if only using 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. 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 PCI boards)
               - 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
               - more detailed information about board configuration and
                 some helpful examples are contained in the driver manual
                 pages.
   
   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!
   
   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 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
   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/libdata/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/libdata/stallion/cdk.sys
       /usr/sbin/stlload -b 1 -i /usr/libdata/stallion/2681.sys
       /usr/sbin/stlload -b 2 -i /usr/libdata/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 (ISA and EISA)
   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
   
   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 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
   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)
       c) ppp (through pppd, kernel ppp)
   
   
   
   4. NOTES
   
   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. On FreeBSD 2.1.5 and later systems each driver has been
   assigned a different major number. On earlier FreeBSD versions you may
   need to manually assign each driver a different major number. You will
   also need to adjust the names of the device nodes for each board. To do
   this 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 number 75. 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 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).
   
   
   
   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.
   

Cache object: ad5d96c8a85d7f4281350580dcfef8a0