Documentation/stallion.txt

   1
   2 Stallion Multiport Serial Driver Readme
   3 ---------------------------------------
   4
   5 Copyright (C) 1994-1998,  Stallion Technologies (support@stallion.com).
   6
   7 Version:   5.4.6
   8 Date:      23JUN98
   9
  10
  11
  12 1. INTRODUCTION
  13
  14 There are two drivers that work with the different families of Stallion
  15 multiport serial boards. One is for the Stallion smart boards - that is
  16 EasyIO, EasyConnection 8/32 and EasyConnection 8/64-PCI, the other for
  17 the true Stallion intelligent multiport boards - EasyConnection 8/64
  18 (ISA and EISA), ONboard and Brumby.
  19
  20 If you are using any of the Stallion intelligent multiport boards (Brumby,
  21 ONboard, EasyConnection 8/64 (ISA or EISA)) with Linux you will need to
  22 get the driver utility package. This package is available at most of the
  23 Linux archive sites (and on CD-ROMs that contain these archives). The file
  24 will be called stallion-X.X.X.tar.gz where X.X.X will be the version
  25 number. In particular this package contains the board embedded executable
  26 images that are required for these boards. It also contains the downloader
  27 program. These boards cannot be used without this.
  28
  29 The Stallion Technologies ftp site, ftp.stallion.com, will always have
  30 the latest version of the driver utility package. Other sites that usually
  31 have the latest version are tsx-11.mit.edu, sunsite.unc.edu and their
  32 mirrors.
  33
  34 ftp.stallion.com:/drivers/ata5/Linux/v544.tar.gz
  35 tsx-11.mit.edu:/pub/linux/packages/stallion/stallion-5.4.4.tar.gz
  36 sunsite.unc.edu:/pub/Linux/kernel/patches/serial/stallion-5.4.4.tar.gz
  37
  38 As of the printing of this document the latest version of the driver
  39 utility package is 5.4.4. If a later version is now available then you
  40 should use the latest version.
  41
  42 If you are using the EasyIO, EasyConnection 8/32 or EasyConnection 8/64-PCI
  43 boards then you don't need this package. Although it does have a handy
  44 script to create the /dev device nodes for these boards, and a serial stats
  45 display program.
  46
  47 If you require DIP switch settings, EISA/MCA configuration files, or any
  48 other information related to Stallion boards then have a look at Stallion's
  49 web pages at http://www.stallion.com.
  50
  51
  52
  53 2. INSTALLATION
  54
  55 The drivers can be used as loadable modules or compiled into the kernel.
  56 You can choose which when doing a "config" on the kernel.
  57
  58 All ISA, EISA and MCA boards that you want to use need to be entered into
  59 the driver(s) configuration structures. All PCI boards will be automatically
  60 detected when you load the driver - so they do not need to be entered into
  61 the driver(s) configuration structure. (Note that kernel PCI BIOS32 support
  62 is required to use PCI boards.)
  63
  64 Entering ISA, EISA and MCA boards into the driver(s) configuration structure
  65 involves editing the driver(s) source file. It's pretty easy if you follow
  66 the instructions below. Both drivers can support up to 4 boards. The smart
  67 card driver (the stallion.c driver) supports any combination of EasyIO and
  68 EasyConnection 8/32 boards (up to a total of 4). The intelligent driver
  69 supports any combination of ONboards, Brumbys, Stallions and EasyConnection
  70 8/64 (ISA and EISA) boards (up to a total of 4).
  71
  72 To set up the driver(s) for the boards that you want to use you need to
  73 edit the appropriate driver file and add configuration entries.
  74
  75 If using EasyIO or EasyConnection 8/32 ISA or MCA boards, do:
  76    vi /usr/src/linux/drivers/char/stallion.c
  77       - find the definition of the stl_brdconf array (of structures)
  78         near the top of the file
  79       - modify this to match the boards you are going to install
  80         (the comments before this structure should help)
  81       - save and exit
  82
  83 If using ONboard, Brumby, Stallion or EasyConnection 8/64 (ISA or EISA)
  84 boards then do:
  85    vi /usr/src/linux/drivers/char/istallion.c
  86       - find the definition of the stli_brdconf array (of structures)
  87         near the top of the file
  88       - modify this to match the boards you are going to install
  89         (the comments before this structure should help)
  90       - save and exit
  91
  92 Once you have set up the board configurations then you are ready to build
  93 the kernel or modules.
  94
  95 When the new kernel is booted, or the loadable module loaded then the
  96 driver will emit some kernel trace messages about whether the configured
  97 boards were detected or not. Depending on how your system logger is set
  98 up these may come out on the console, or just be logged to
  99 /var/adm/messages. You should check the messages to confirm that all is well.
 100
 101
 102 2.1 SHARING INTERRUPTS
 103
 104 It is possible to share interrupts between multiple EasyIO and
 105 EasyConnection 8/32 boards in an EISA system. To do this you will need to
 106 do a couple of things:
 107
 108 1. When entering the board resources into the stallion.c file you need to
 109    mark the boards as using level triggered interrupts. Do this by replacing
 110    the "0" entry at field position 6 (the last field) in the board
 111    configuration structure with a "1". (This is the structure that defines
 112    the board type, I/O locations, etc. for each board). All boards that are
 113    sharing an interrupt must be set this way, and each board should have the
 114    same interrupt number specified here as well. Now build the module or
 115    kernel as you would normally.
 116
 117 2. When physically installing the boards into the system you must enter
 118    the system EISA configuration utility. You will need to install the EISA
 119    configuration files for *all* the EasyIO and EasyConnection 8/32 boards
 120    that are sharing interrupts. The Stallion EasyIO and EasyConnection 8/32
 121    EISA configuration files required are supplied by Stallion Technologies
 122    on the EASY Utilities floppy diskette (usually supplied in the box with
 123    the board when purchased. If not, you can pick it up from Stallion's FTP
 124    site, ftp.stallion.com). You will need to edit the board resources to
 125    choose level triggered interrupts, and make sure to set each board's
 126    interrupt to the same IRQ number.
 127
 128 You must complete both the above steps for this to work. When you reboot
 129 or load the driver your EasyIO and EasyConnection 8/32 boards will be
 130 sharing interrupts.
 131
 132
 133 2.2 USING HIGH SHARED MEMORY
 134
 135 The EasyConnection 8/64-EI, ONboard and Stallion boards are capable of
 136 using shared memory addresses above the usual 640K - 1Mb range. The ONboard
 137 ISA and the Stallion boards can be programmed to use memory addresses up to
 138 16Mb (the ISA bus addressing limit), and the EasyConnection 8/64-EI and
 139 ONboard/E can be programmed for memory addresses up to 4Gb (the EISA bus
 140 addressing limit).
 141
 142 The higher than 1Mb memory addresses are fully supported by this driver.
 143 Just enter the address as you normally would for a lower than 1Mb address
 144 (in the driver's board configuration structure).
 145
 146
 147
 148 2.3 TROUBLE SHOOTING
 149
 150 If a board is not found by the driver but is actually in the system then the
 151 most likely problem is that the I/O address is wrong. Change it in the driver
 152 stallion.c or istallion.c configuration structure and rebuild the kernel or
 153 modules, or change it on the board. On EasyIO and EasyConnection 8/32 boards
 154 the IRQ is software programmable, so if there is a conflict you may need to
 155 change the IRQ used for a board in the stallion.c configuration structure.
 156 There are no interrupts to worry about for ONboard, Brumby or EasyConnection
 157 8/64 (ISA, EISA and MCA) boards. The memory region on EasyConnection 8/64 and
 158 ONboard boards is software programmable, but not on the Brumby boards.
 159
 160
 161
 162 3. USING THE DRIVERS
 163
 164 3.1 INTELLIGENT DRIVER OPERATION
 165
 166 The intelligent boards also need to have their "firmware" code downloaded
 167 to them. This is done via a user level application supplied in the driver
 168 utility package called "stlload". Compile this program wherever you dropped
 169 the package files, by typing "make". In its simplest form you can then type
 170     ./stlload -i cdk.sys
 171 in this directory and that will download board 0 (assuming board 0 is an
 172 EasyConnection 8/64 board). To download to an ONboard, Brumby or Stallion do:
 173     ./stlload -i 2681.sys
 174
 175 Normally you would want all boards to be downloaded as part of the standard
 176 system startup. To achieve this, add one of the lines above into the
 177 /etc/rc.d/rc.S or /etc/rc.d/rc.serial file. To download each board just add
 178 the "-b <brd-number>" option to the line. You will need to download code for
 179 every board. You should probably move the stlload program into a system
 180 directory, such as /usr/sbin. Also, the default location of the cdk.sys image
 181 file in the stlload down-loader is /usr/lib/stallion. Create that directory
 182 and put the cdk.sys and 2681.sys files in it. (It's a convenient place to put
 183 them anyway). As an example your /etc/rc.d/rc.S file might have the
 184 following lines added to it (if you had 3 boards):
 185     /usr/sbin/stlload -b 0 -i /usr/lib/stallion/cdk.sys
 186     /usr/sbin/stlload -b 1 -i /usr/lib/stallion/2681.sys
 187     /usr/sbin/stlload -b 2 -i /usr/lib/stallion/2681.sys
 188
 189 The image files cdk.sys and 2681.sys are specific to the board types. The
 190 cdk.sys will only function correctly on an EasyConnection 8/64 board. Similarly
 191 the 2681.sys image fill only operate on ONboard, Brumby and Stallion boards.
 192 If you load the wrong image file into a board it will fail to start up, and
 193 of course the ports will not be operational!
 194
 195 If you are using the modularized version of the driver you might want to put
 196 the insmod calls in the startup script as well (before the download lines
 197 obviously).
 198
 199
 200 3.2 USING THE SERIAL PORTS
 201
 202 Once the driver is installed you will need to setup some device nodes to
 203 access the serial ports. The simplest method is to use the stallion utility
 204 "mkdevnods" script. It will automatically create device entries for Stallion
 205 boards. This will create the normal serial port devices as /dev/ttyE# where
 206 # is the port number starting from 0. A bank of 64 minor device numbers is
 207 allocated to each board, so the first port on the second board is port 64,
 208 etc. A set of callout type devices is also created. They are created as the
 209 devices /dev/cue# where # is the same as for the ttyE devices.
 210
 211 For the most part the Stallion driver tries to emulate the standard PC system
 212 COM ports and the standard Linux serial driver. The idea is that you should
 213 be able to use Stallion board ports and COM ports interchangeably without
 214 modifying anything but the device name. Anything that doesn't work like that
 215 should be considered a bug in this driver!
 216
 217 If you look at the driver code you will notice that it is fairly closely
 218 based on the Linux serial driver (linux/drivers/char/serial.c). This is
 219 intentional, obviously this is the easiest way to emulate its behavior!
 220
 221 Since this driver tries to emulate the standard serial ports as much as
 222 possible, most system utilities should work as they do for the standard
 223 COM ports. Most importantly "stty" works as expected and "setserial" can
 224 also be used (excepting the ability to auto-configure the I/O and IRQ
 225 addresses of boards). Higher baud rates are supported in the usual fashion
 226 through setserial or using the CBAUDEX extensions. Note that the EasyIO and
 227 EasyConnection (all types) support at least 57600 and 115200 baud. The newer
 228 EasyConnection XP modules and new EasyIO boards support 230400 and 460800
 229 baud as well. The older boards including ONboard and Brumby support a
 230 maximum baud rate of 38400.
 231
 232 If you are unfamiliar with how to use serial ports, then get the Serial-HOWTO
 233 by Greg Hankins. It will explain everything you need to know!
 234
 235
 236
 237 4. NOTES
 238
 239 You can use both drivers at once if you have a mix of board types installed
 240 in a system. However to do this you will need to change the major numbers
 241 used by one of the drivers. Currently both drivers use major numbers 24, 25
 242 and 28 for their devices. Change one driver to use some other major numbers,
 243 and then modify the mkdevnods script to make device nodes based on those new
 244 major numbers. For example, you could change the istallion.c driver to use
 245 major numbers 60, 61 and 62. You will also need to create device nodes with
 246 different names for the ports, for example ttyF# and cuf#.
 247
 248 The original Stallion board is no longer supported by Stallion Technologies.
 249 Although it is known to work with the istallion driver.
 250
 251 Finding a free physical memory address range can be a problem. The older
 252 boards like the Stallion and ONboard need large areas (64K or even 128K), so
 253 they can be very difficult to get into a system. If you have 16 Mb of RAM
 254 then you have no choice but to put them somewhere in the 640K -> 1Mb range.
 255 ONboards require 64K, so typically 0xd0000 is good, or 0xe0000 on some
 256 systems. If you have an original Stallion board, "V4.0" or Rev.O, then you
 257 need a 64K memory address space, so again 0xd0000 and 0xe0000 are good.
 258 Older Stallion boards are a much bigger problem. They need 128K of address
 259 space and must be on a 128K boundary. If you don't have a VGA card then
 260 0xc0000 might be usable - there is really no other place you can put them
 261 below 1Mb.
 262
 263 Both the ONboard and old Stallion boards can use higher memory addresses as
 264 well, but you must have less than 16Mb of RAM to be able to use them. Usual
 265 high memory addresses used include 0xec0000 and 0xf00000.
 266
 267 The Brumby boards only require 16Kb of address space, so you can usually
 268 squeeze them in somewhere. Common addresses are 0xc8000, 0xcc000, or in
 269 the 0xd0000 range. EasyConnection 8/64 boards are even better, they only
 270 require 4Kb of address space, again usually 0xc8000, 0xcc000 or 0xd0000
 271 are good.
 272
 273 If you are using an EasyConnection 8/64-EI or ONboard/E then usually the
 274 0xd0000 or 0xe0000 ranges are the best options below 1Mb. If neither of
 275 them can be used then the high memory support to use the really high address
 276 ranges is the best option. Typically the 2Gb range is convenient for them,
 277 and gets them well out of the way.
 278
 279 The ports of the EasyIO-8M board do not have DCD or DTR signals. So these
 280 ports cannot be used as real modem devices. Generally, when using these
 281 ports you should only use the cueX devices.
 282
 283 The driver utility package contains a couple of very useful programs. One
 284 is a serial port statistics collection and display program - very handy
 285 for solving serial port problems. The other is an extended option setting
 286 program that works with the intelligent boards.
 287
 288
 289
 290 5. DISCLAIMER
 291
 292 The information contained in this document is believed to be accurate and
 293 reliable. However, no responsibility is assumed by Stallion Technologies
 294 Pty. Ltd. for its use, nor any infringements of patents or other rights
 295 of third parties resulting from its use. Stallion Technologies reserves
 296 the right to modify the design of its products and will endeavour to change
 297 the information in manuals and accompanying documentation accordingly.
 298