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