Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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@gmail.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 |
Lucas De Marchi | 970e248 | 2012-03-30 13:37:16 -0700 | [diff] [blame] | 142 | on each system boot. Typically configuration files are put in the |
| 143 | /etc/modprobe.d/ directory. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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. |
| 392 | |