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