Based on kernel version 2.6.27. Page generated on 2008-10-13 09:54 EST.
1 * NOTE - This is an unmaintained driver. Lantronix, which bought Stallion 2 technologies, is not active in driver maintenance, and they have no information 3 on when or if they will have a 2.6 driver. 4 5 James Nelson <james4765[AT]gmail[DOT]com> - 12-12-2004 6 7 Stallion Multiport Serial Driver Readme 8 --------------------------------------- 9 10 Copyright (C) 1994-1999, Stallion Technologies. 11 12 Version: 5.5.1 13 Date: 28MAR99 14 15 16 17 1. INTRODUCTION 18 19 There are two drivers that work with the different families of Stallion 20 multiport serial boards. One is for the Stallion smart boards - that is 21 EasyIO, EasyConnection 8/32 and EasyConnection 8/64-PCI, the other for 22 the true Stallion intelligent multiport boards - EasyConnection 8/64 23 (ISA, EISA, MCA), EasyConnection/RA-PCI, ONboard and Brumby. 24 25 If you are using any of the Stallion intelligent multiport boards (Brumby, 26 ONboard, EasyConnection 8/64 (ISA, EISA, MCA), EasyConnection/RA-PCI) with 27 Linux you will need to get the driver utility package. This contains a 28 firmware loader and the firmware images necessary to make the devices operate. 29 30 The Stallion Technologies ftp site, ftp.stallion.com, will always have 31 the latest version of the driver utility package. 32 33 ftp://ftp.stallion.com/drivers/ata5/Linux/ata-linux-550.tar.gz 34 35 As of the printing of this document the latest version of the driver 36 utility package is 5.5.0. If a later version is now available then you 37 should use the latest version. 38 39 If you are using the EasyIO, EasyConnection 8/32 or EasyConnection 8/64-PCI 40 boards then you don't need this package, although it does have a serial stats 41 display program. 42 43 If you require DIP switch settings, EISA or MCA configuration files, or any 44 other information related to Stallion boards then have a look at Stallion's 45 web pages at http://www.stallion.com. 46 47 48 49 2. INSTALLATION 50 51 The drivers can be used as loadable modules or compiled into the kernel. 52 You can choose which when doing a "config" on the kernel. 53 54 All ISA, EISA and MCA boards that you want to use need to be configured into 55 the driver(s). All PCI boards will be automatically detected when you load 56 the driver - so they do not need to be entered into the driver(s) 57 configuration structure. Note that kernel PCI support is required to use PCI 58 boards. 59 60 There are two methods of configuring ISA, EISA and MCA boards into the drivers. 61 If using the driver as a loadable module then the simplest method is to pass 62 the driver configuration as module arguments. The other method is to modify 63 the driver source to add configuration lines for each board in use. 64 65 If you have pre-built Stallion driver modules then the module argument 66 configuration method should be used. A lot of Linux distributions come with 67 pre-built driver modules in /lib/modules/X.Y.Z/misc for the kernel in use. 68 That makes things pretty simple to get going. 69 70 71 2.1 MODULE DRIVER CONFIGURATION: 72 73 The simplest configuration for modules is to use the module load arguments 74 to configure any ISA, EISA or MCA boards. PCI boards are automatically 75 detected, so do not need any additional configuration at all. 76 77 If using EasyIO, EasyConnection 8/32 ISA or MCA, or EasyConnection 8/63-PCI 78 boards then use the "stallion" driver module, Otherwise if you are using 79 an EasyConnection 8/64 ISA, EISA or MCA, EasyConnection/RA-PCI, ONboard, 80 Brumby or original Stallion board then use the "istallion" driver module. 81 82 Typically to load up the smart board driver use: 83 84 modprobe stallion 85 86 This will load the EasyIO and EasyConnection 8/32 driver. It will output a 87 message to say that it loaded and print the driver version number. It will 88 also print out whether it found the configured boards or not. These messages 89 may not appear on the console, but typically are always logged to 90 /var/adm/messages or /var/log/syslog files - depending on how the klogd and 91 syslogd daemons are setup on your system. 92 93 To load the intelligent board driver use: 94 95 modprobe istallion 96 97 It will output similar messages to the smart board driver. 98 99 If not using an auto-detectable board type (that is a PCI board) then you 100 will also need to supply command line arguments to the modprobe command 101 when loading the driver. The general form of the configuration argument is 102 103 board?=<name>[,<ioaddr>[,<addr>][,<irq>]] 104 105 where: 106 107 board? -- specifies the arbitrary board number of this board, 108 can be in the range 0 to 3. 109 110 name -- textual name of this board. The board name is the common 111 board name, or any "shortened" version of that. The board 112 type number may also be used here. 113 114 ioaddr -- specifies the I/O address of this board. This argument is 115 optional, but should generally be specified. 116 117 addr -- optional second address argument. Some board types require 118 a second I/O address, some require a memory address. The 119 exact meaning of this argument depends on the board type. 120 121 irq -- optional IRQ line used by this board. 122 123 Up to 4 board configuration arguments can be specified on the load line. 124 Here is some examples: 125 126 modprobe stallion board0=easyio,0x2a0,5 127 128 This configures an EasyIO board as board 0 at I/O address 0x2a0 and IRQ 5. 129 130 modprobe istallion board3=ec8/64,0x2c0,0xcc000 131 132 This configures an EasyConnection 8/64 ISA as board 3 at I/O address 0x2c0 at 133 memory address 0xcc000. 134 135 modprobe stallion board1=ec8/32-at,0x2a0,0x280,10 136 137 This configures an EasyConnection 8/32 ISA board at primary I/O address 0x2a0, 138 secondary address 0x280 and IRQ 10. 139 140 You will probably want to enter this module load and configuration information 141 into your system startup scripts so that the drivers are loaded and configured 142 on each system boot. Typically the start up script would be something like 143 /etc/modprobe.conf. 144 145 146 2.2 STATIC DRIVER CONFIGURATION: 147 148 For static driver configuration you need to modify the driver source code. 149 Entering ISA, EISA and MCA boards into the driver(s) configuration structure 150 involves editing the driver(s) source file. It's pretty easy if you follow 151 the instructions below. Both drivers can support up to 4 boards. The smart 152 card driver (the stallion.c driver) supports any combination of EasyIO and 153 EasyConnection 8/32 boards (up to a total of 4). The intelligent driver 154 supports any combination of ONboards, Brumbys, Stallions and EasyConnection 155 8/64 (ISA and EISA) boards (up to a total of 4). 156 157 To set up the driver(s) for the boards that you want to use you need to 158 edit the appropriate driver file and add configuration entries. 159 160 If using EasyIO or EasyConnection 8/32 ISA or MCA boards, 161 In drivers/char/stallion.c: 162 - find the definition of the stl_brdconf array (of structures) 163 near the top of the file 164 - modify this to match the boards you are going to install 165 (the comments before this structure should help) 166 - save and exit 167 168 If using ONboard, Brumby, Stallion or EasyConnection 8/64 (ISA or EISA) 169 boards, 170 In drivers/char/istallion.c: 171 - find the definition of the stli_brdconf array (of structures) 172 near the top of the file 173 - modify this to match the boards you are going to install 174 (the comments before this structure should help) 175 - save and exit 176 177 Once you have set up the board configurations then you are ready to build 178 the kernel or modules. 179 180 When the new kernel is booted, or the loadable module loaded then the 181 driver will emit some kernel trace messages about whether the configured 182 boards were detected or not. Depending on how your system logger is set 183 up these may come out on the console, or just be logged to 184 /var/adm/messages or /var/log/syslog. You should check the messages to 185 confirm that all is well. 186 187 188 2.3 SHARING INTERRUPTS 189 190 It is possible to share interrupts between multiple EasyIO and 191 EasyConnection 8/32 boards in an EISA system. To do this you must be using 192 static driver configuration, modifying the driver source code to add driver 193 configuration. Then a couple of extra things are required: 194 195 1. When entering the board resources into the stallion.c file you need to 196 mark the boards as using level triggered interrupts. Do this by replacing 197 the "0" entry at field position 6 (the last field) in the board 198 configuration structure with a "1". (This is the structure that defines 199 the board type, I/O locations, etc. for each board). All boards that are 200 sharing an interrupt must be set this way, and each board should have the 201 same interrupt number specified here as well. Now build the module or 202 kernel as you would normally. 203 204 2. When physically installing the boards into the system you must enter 205 the system EISA configuration utility. You will need to install the EISA 206 configuration files for *all* the EasyIO and EasyConnection 8/32 boards 207 that are sharing interrupts. The Stallion EasyIO and EasyConnection 8/32 208 EISA configuration files required are supplied by Stallion Technologies 209 on the EASY Utilities floppy diskette (usually supplied in the box with 210 the board when purchased. If not, you can pick it up from Stallion's FTP 211 site, ftp.stallion.com). You will need to edit the board resources to 212 choose level triggered interrupts, and make sure to set each board's 213 interrupt to the same IRQ number. 214 215 You must complete both the above steps for this to work. When you reboot 216 or load the driver your EasyIO and EasyConnection 8/32 boards will be 217 sharing interrupts. 218 219 220 2.4 USING HIGH SHARED MEMORY 221 222 The EasyConnection 8/64-EI, ONboard and Stallion boards are capable of 223 using shared memory addresses above the usual 640K - 1Mb range. The ONboard 224 ISA and the Stallion boards can be programmed to use memory addresses up to 225 16Mb (the ISA bus addressing limit), and the EasyConnection 8/64-EI and 226 ONboard/E can be programmed for memory addresses up to 4Gb (the EISA bus 227 addressing limit). 228 229 The higher than 1Mb memory addresses are fully supported by this driver. 230 Just enter the address as you normally would for a lower than 1Mb address 231 (in the driver's board configuration structure). 232 233 234 235 2.5 TROUBLE SHOOTING 236 237 If a board is not found by the driver but is actually in the system then the 238 most likely problem is that the I/O address is wrong. Change the module load 239 argument for the loadable module form. Or change it in the driver stallion.c 240 or istallion.c configuration structure and rebuild the kernel or modules, or 241 change it on the board. 242 243 On EasyIO and EasyConnection 8/32 boards the IRQ is software programmable, so 244 if there is a conflict you may need to change the IRQ used for a board. There 245 are no interrupts to worry about for ONboard, Brumby or EasyConnection 8/64 246 (ISA, EISA and MCA) boards. The memory region on EasyConnection 8/64 and 247 ONboard boards is software programmable, but not on the Brumby boards. 248 249 250 251 3. USING THE DRIVERS 252 253 3.1 INTELLIGENT DRIVER OPERATION 254 255 The intelligent boards also need to have their "firmware" code downloaded 256 to them. This is done via a user level application supplied in the driver 257 utility package called "stlload". Compile this program wherever you dropped 258 the package files, by typing "make". In its simplest form you can then type 259 260 ./stlload -i cdk.sys 261 262 in this directory and that will download board 0 (assuming board 0 is an 263 EasyConnection 8/64 or EasyConnection/RA board). To download to an 264 ONboard, Brumby or Stallion do: 265 266 ./stlload -i 2681.sys 267 268 Normally you would want all boards to be downloaded as part of the standard 269 system startup. To achieve this, add one of the lines above into the 270 /etc/rc.d/rc.S or /etc/rc.d/rc.serial file. To download each board just add 271 the "-b <brd-number>" option to the line. You will need to download code for 272 every board. You should probably move the stlload program into a system 273 directory, such as /usr/sbin. Also, the default location of the cdk.sys image 274 file in the stlload down-loader is /usr/lib/stallion. Create that directory 275 and put the cdk.sys and 2681.sys files in it. (It's a convenient place to put 276 them anyway). As an example your /etc/rc.d/rc.S file might have the 277 following lines added to it (if you had 3 boards): 278 279 /usr/sbin/stlload -b 0 -i /usr/lib/stallion/cdk.sys 280 /usr/sbin/stlload -b 1 -i /usr/lib/stallion/2681.sys 281 /usr/sbin/stlload -b 2 -i /usr/lib/stallion/2681.sys 282 283 The image files cdk.sys and 2681.sys are specific to the board types. The 284 cdk.sys will only function correctly on an EasyConnection 8/64 board. Similarly 285 the 2681.sys image fill only operate on ONboard, Brumby and Stallion boards. 286 If you load the wrong image file into a board it will fail to start up, and 287 of course the ports will not be operational! 288 289 If you are using the modularized version of the driver you might want to put 290 the modprobe calls in the startup script as well (before the download lines 291 obviously). 292 293 294 3.2 USING THE SERIAL PORTS 295 296 Once the driver is installed you will need to setup some device nodes to 297 access the serial ports. The simplest method is to use the /dev/MAKEDEV program. 298 It will automatically create device entries for Stallion boards. This will 299 create the normal serial port devices as /dev/ttyE# where# is the port number 300 starting from 0. A bank of 64 minor device numbers is allocated to each board, 301 so the first port on the second board is port 64,etc. A set of callout type 302 devices may also be created. They are created as the devices /dev/cue# where # 303 is the same as for the ttyE devices. 304 305 For the most part the Stallion driver tries to emulate the standard PC system 306 COM ports and the standard Linux serial driver. The idea is that you should 307 be able to use Stallion board ports and COM ports interchangeably without 308 modifying anything but the device name. Anything that doesn't work like that 309 should be considered a bug in this driver! 310 311 If you look at the driver code you will notice that it is fairly closely 312 based on the Linux serial driver (linux/drivers/char/serial.c). This is 313 intentional, obviously this is the easiest way to emulate its behavior! 314 315 Since this driver tries to emulate the standard serial ports as much as 316 possible, most system utilities should work as they do for the standard 317 COM ports. Most importantly "stty" works as expected and "setserial" can 318 also be used (excepting the ability to auto-configure the I/O and IRQ 319 addresses of boards). Higher baud rates are supported in the usual fashion 320 through setserial or using the CBAUDEX extensions. Note that the EasyIO and 321 EasyConnection (all types) support at least 57600 and 115200 baud. The newer 322 EasyConnection XP modules and new EasyIO boards support 230400 and 460800 323 baud as well. The older boards including ONboard and Brumby support a 324 maximum baud rate of 38400. 325 326 If you are unfamiliar with how to use serial ports, then get the Serial-HOWTO 327 by Greg Hankins. It will explain everything you need to know! 328 329 330 331 4. NOTES 332 333 You can use both drivers at once if you have a mix of board types installed 334 in a system. However to do this you will need to change the major numbers 335 used by one of the drivers. Currently both drivers use major numbers 24, 25 336 and 28 for their devices. Change one driver to use some other major numbers, 337 and then modify the mkdevnods script to make device nodes based on those new 338 major numbers. For example, you could change the istallion.c driver to use 339 major numbers 60, 61 and 62. You will also need to create device nodes with 340 different names for the ports, for example ttyF# and cuf#. 341 342 The original Stallion board is no longer supported by Stallion Technologies. 343 Although it is known to work with the istallion driver. 344 345 Finding a free physical memory address range can be a problem. The older 346 boards like the Stallion and ONboard need large areas (64K or even 128K), so 347 they can be very difficult to get into a system. If you have 16 Mb of RAM 348 then you have no choice but to put them somewhere in the 640K -> 1Mb range. 349 ONboards require 64K, so typically 0xd0000 is good, or 0xe0000 on some 350 systems. If you have an original Stallion board, "V4.0" or Rev.O, then you 351 need a 64K memory address space, so again 0xd0000 and 0xe0000 are good. 352 Older Stallion boards are a much bigger problem. They need 128K of address 353 space and must be on a 128K boundary. If you don't have a VGA card then 354 0xc0000 might be usable - there is really no other place you can put them 355 below 1Mb. 356 357 Both the ONboard and old Stallion boards can use higher memory addresses as 358 well, but you must have less than 16Mb of RAM to be able to use them. Usual 359 high memory addresses used include 0xec0000 and 0xf00000. 360 361 The Brumby boards only require 16Kb of address space, so you can usually 362 squeeze them in somewhere. Common addresses are 0xc8000, 0xcc000, or in 363 the 0xd0000 range. EasyConnection 8/64 boards are even better, they only 364 require 4Kb of address space, again usually 0xc8000, 0xcc000 or 0xd0000 365 are good. 366 367 If you are using an EasyConnection 8/64-EI or ONboard/E then usually the 368 0xd0000 or 0xe0000 ranges are the best options below 1Mb. If neither of 369 them can be used then the high memory support to use the really high address 370 ranges is the best option. Typically the 2Gb range is convenient for them, 371 and gets them well out of the way. 372 373 The ports of the EasyIO-8M board do not have DCD or DTR signals. So these 374 ports cannot be used as real modem devices. Generally, when using these 375 ports you should only use the cueX devices. 376 377 The driver utility package contains a couple of very useful programs. One 378 is a serial port statistics collection and display program - very handy 379 for solving serial port problems. The other is an extended option setting 380 program that works with the intelligent boards. 381 382 383 384 5. DISCLAIMER 385 386 The information contained in this document is believed to be accurate and 387 reliable. However, no responsibility is assumed by Stallion Technologies 388 Pty. Ltd. for its use, nor any infringements of patents or other rights 389 of third parties resulting from its use. Stallion Technologies reserves 390 the right to modify the design of its products and will endeavour to change 391 the information in manuals and accompanying documentation accordingly.