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