stallion.txt 18 KB

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