1
2 Stallion Multiport Serial Driver Readme
3 ---------------------------------------
4
5 Version: 0.0.5 alpha
6 Date: 20MAR96
7 Author: Greg Ungerer (gerg@stallion.oz.au)
8
9
10
11 1. INTRODUCTION
12
13 This is a FreeBSD driver for some of the Stallion Technologies range of
14 multiport serial boards. This driver is still very new, so it should be
15 considered to be of very alpha quality.
16
17 This driver has not been developed by Stallion Technologies. I developed it
18 in my spare time in the hope that it would be useful. As such there is no
19 warranty or support of any form. What this means is that this driver is not
20 officially supported by Stallion Technologies, so don't ring their support
21 if you can't get it working. They will probably not be able to help you.
22 Instead email me if you have problems or bug reports and I will do what I
23 can... (Sorry to sound so heavy handed, but I need to stress that this driver
24 is not officially supported in any way.)
25
26 This package actually contains two drivers. One is for the true Stallion
27 intelligent multiport boards, and the other is for the smart range of boards.
28
29 All host driver source is included in this package, and is copyrighted under
30 a BSD style copyright. The board "firmware" code in this package is copyright
31 Stallion Technologies (the files cdk.sys and 2681.sys).
32
33
34 1.1 SMART MULTIPORT BOARD DRIVER
35
36 This driver supports the EasyIO and EasyConnection 8/32 range of boards.
37 These boards are not classic intelligent multiport boards, but are host
38 based multiport boards that use high performance Cirrus Logic CL-CD1400 RISC
39 UART's (they have built in FIFO's, automatic flow control and some other
40 good stuff).
41
42 The EasyIO range of cards comes in 3 forms, the EasyIO-4, EasyIO-8 and the
43 EasyIO-8M. All of these are non-expandable, low cost, ISA, multiport boards
44 with 4, 8 and 8 RS-232C ports respectively. Each EasyIO board requires 8
45 bytes of I/O address space and 1 interrupt. On an EISA system it is possible
46 to share 1 interrupt between multiple boards. The EasyIO-4 has 10 pin RJ
47 connectors, and the EasyIO-8 comes with a dongle cable with either 10 pin RJ
48 connectors or DB-25 connectors. The EasyIO-8M has 6 pin RJ connectors.
49
50 The EasyConnection 8/32 family of boards is a relatively low cost modular
51 range of multiport serial boards. The EasyConnection 8/32 boards can be
52 configured to have from 8 to 32 serial ports by plugging in external serial
53 port modules that contain either 8 or 16 ports each. There is a wide range
54 of external modules available that offer: DB-25 connectors, RJ-45 connectors
55 (both with RS-232 D and E compatible drivers), and also RS-422 and RS-485
56 ports. The EasyConnection 8/32 boards come in ISA, PCI and MCA bus versions.
57 The board takes the form of a host adapter card, with an external connector
58 cable that plugs into the external modules. The external modules just clip
59 together to add ports (BTW, they are NOT hot pluggable). Each ISA
60 EasyConnection 8/32 board requires two separate I/O address ranges, one two
61 bytes in size and a secondary region of 32 bytes. Each PCI EasyConnection
62 8/32 requires two regions of I/O address space, normally these will be
63 automatically allocated by the system BIOS at system power on time. Each MCA
64 EasyConnection board requires one I/O address region 64 bytes in size. All
65 board types also require one interrupt. On EISA systems multiple boards can
66 share one interrupt. The secondary I/O range of the ISA board (the 32 byte
67 range) can be shared between multiple boards on any bus type.
68
69
70 1.2 INTELLIGENT MULTIPORT BOARD DRIVER
71
72 This driver is for Stallion's range of true intelligent multiport boards.
73 It supports the EasyConnection 8/64, ONboard, Brumby and original Stallion
74 families of multiport boards. The EasyConnection 8/64 and ONboard boards come
75 in ISA, EISA and Microchannel bus versions. The Brumby and Stallion boards
76 are only available in ISA versions.
77
78 The EasyConnection 8/64 family of boards is a medium cost, high performance,
79 modular range of intelligent multiport serial boards. The EasyConnection 8/64
80 boards can be configured to have from 8 to 64 serial ports by plugging in
81 external serial port modules that contain either 8 or 16 ports each (these
82 modules are the same used by the EasyConnection 8/32 board). There is a wide
83 range of external modules available that offer: DB-25 connectors, RJ-45
84 connectors (both with RS-232 D and E compatible drivers), and also RS-422 and
85 RS-485 ports. The board takes the form of a host adapter card, with an external
86 connector cable that plugs into the external modules. The external modules
87 just clip together to add ports (BTW, they are NOT hot pluggable). Each
88 EasyConnection 8/64 board requires 4 bytes of I/O address space and a region
89 of memory space. The size of the memory region required depends on the exact
90 board type. The EISA version requires 64 Kbytes of address space (that can
91 reside anywhere in the 4 Gigabyte physical address space). The ISA and MCA
92 boards require 4 Kbytes of address space (which must reside in the lower
93 1 Mbyte of physical address space - typically in the c8000 to e0000 range).
94 No interrupts are required. The physical memory region of multiple
95 EasyConnection 8/64 boards can be shared, but each board must have a separate
96 I/O address space.
97
98 The ONboard family of boards are traditional intelligent multiport serial
99 boards. They are Stallion's older range of boards with a limited expansion
100 capability. They come in 4, 8, 12, 16 and 32 port versions. The board uses
101 the same base card (which has 4 ports on it) and is expanded to more ports
102 via a mezzanine board that attaches directly onto the board. External panels
103 plug into the ONboard providing RS-232C ports with DB-25 plugs. An RS-422
104 DB-25 dual interface panel is also available. The ISA and microchannel
105 ONboards require 16 bytes of I/O address space and 64K bytes of memory
106 space. The memory space can be anywhere in the 16 Mbyte ISA bus address
107 range. No interrupt is required. The EISA ONboard requires 64 Kbytes of
108 memory space that can be anywhere in the 4 Gigabyte physical address space.
109 All ONboard boards can share their memory region with other ONboards (or
110 EasyConnection 8/64 boards).
111
112 The Brumby family of boards are traditional, low cost intelligent multiport
113 serial boards. They are non-expandable and come in 4, 8 and 16 port versions.
114 They are only available for the ISA bus. The serial ports are all on DB-25
115 "dongle" cables that attach to the rear of the board. Each Brumby board
116 requires 16 bytes of I/O address space and 16 Kbytes of memory space. No
117 interrupts are required.
118
119 The original Stallion boards are old. They went out of production some years
120 back. They offer limited expandability and are available in 8 or 16 port
121 configurations. An external panel houses 16 RS-232C ports with DB-9
122 connectors. They require 16 bytes of I/O address space, and either 64K or
123 128K of memory space. No interrupt is required. I will not actively support
124 these boards, although they will work with the driver.
125
126 That's the boards supported by the second driver. The ONboard, Brumby and
127 Stallion boards are Stallion's older range of intelligent multiports - so
128 there are lots of them around. They only support a maximum baud rate of
129 38400. The EasyConnection 8/64 is a true high performance intelligent
130 multiport board, having much greater throughput than any of Stallion's
131 older boards. It also supports speeds up to 115200 baud.
132
133
134 1.3 HOW TO GET BOARDS
135
136 Stallion Technologies has offices all over the world, as well as many more
137 distributors and resellers. To find out about local availability please
138 contact the nearest Stallion office and they can give you all the information
139 you need.
140
141 Stallion Technologies Sales and Support Offices
142 ===============================================
143
144 Stallion Technologies Pty. Ltd.
145 P.O. Box 954
146 Toowong, QLD 4066, Australia
147 Tel. +61 7 3270 4242
148 Fax. +61 7 3270 4245
149 Email: support@stallion.oz.au
150
151 Stallion Technologies Inc.
152 2880 Research Park Drive,
153 Soquel, CA 95073, USA.
154 Tel. +1 408 477 0440
155 Fax. +1 408 477 0444
156 Email: support@staltec.com
157
158 Stallion Technologies Deutschland GmbH.
159 Martin-Behaim-Strasse 12
160 63263 Neu-Isenburg
161 Germany
162 Tel. +49 6102 73970
163 Fax. +49 6102 739710
164
165 Another good source of information about the Stallion range of boards and
166 local availability is on the Stallion Web page. Check it out at
167 http://www.stallion.com.
168
169
170
171 2. INSTALLATION
172
173 This driver, as is, will work on a FreeBSD 2.1 system. It will run on
174 a 2.0.5 system, or -current version systems by changing a define in the
175 driver source.
176
177 You will need to build a new kernel to use this driver. So the first thing
178 you need is to have the full kernel source. Most people will have this
179 (I hope!). The following assumes that the kernel source is in /usr/src/sys.
180
181 The drivers can support up to 8 boards. For the smart board driver any
182 combination of EasyIO and EasyConnection 8/32 boards can be installed. For
183 the intelligent any combination of EasyConnection 8/64, ONboard, Brumby or
184 original Stallion. So there is a theoretical maximum of 512 ports.
185 (Off-course I have not tested a system with this many!)
186
187
188 [[[ The install instructions are obsolete, it is now standard ]]]
189 [[[ Skip forward to item 4, editing your kernel config file ]]]
190
191 2.1 Instructions to install:
192
193 1. Copy the driver source files into the kernel source tree.
194
195 cp stallion.c istallion.c cdk.h comstats.h /usr/src/sys/i386/isa
196 cp scd1400.h /usr/src/sys/i386/isa/ic
197
198 Note: if you are NOT using FreeBSD 2.1.0 then you will need to edit the
199 stallion.c and istallion.c files and change the VFREEBSD define to match
200 your version.
201
202 2. Skip to next step if on a FreeBSD kernel later than 2.1.0.
203 Add a character device switch table entry for the driver that you which
204 to use into the cdevsw table structure. This involves adding some code
205 into the kernel conf.c file.
206
207 If you are using an EasyIO or EasyConnection 8/32 then you need to use
208 the stallion.c driver. All other board types (EasyConnection 8/64,
209 ONboard, Brumby, Stallion) use the istallion.c driver. You can also have
210 a mix of boards using both drivers. You will need to use a different
211 major device number for the second driver though (not the default 72 -
212 see below for more details on this).
213
214 2.1. If using the stallion.c driver then do:
215
216 cd /usr/src/sys/i386/i386
217 vi conf.c
218 - add the following lines (in 2.1 I put them at line 729):
219
220 /* Stallion Multiport Serial Driver */
221 #include "stl.h"
222 #if NSTL > 0
223 d_open_t stlopen;
224 d_close_t stlclose;
225 d_read_t stlread;
226 d_write_t stlwrite;
227 d_ioctl_t stlioctl;
228 d_stop_t stlstop;
229 d_ttycv_t stldevtotty;
230 #define stlreset nxreset
231 #define stlmmap nxmmap
232 #define stlstrategy nxstrategy
233 #else
234 #define stlopen nxopen
235 #define stlclose nxclose
236 #define stlread nxread
237 #define stlwrite nxwrite
238 #define stlioctl nxioctl
239 #define stlstop nxstop
240 #define stlreset nxreset
241 #define stlmmap nxmmap
242 #define stlstrategy nxstrategy
243 #define stldevtotty nxdevtotty
244 #endif
245
246
247 - and then inside the actual cdevsw structure definition, at the
248 last entry add (this is now line 1384 in the 2.1 conf.c):
249
250 { stlopen, stlclose, stlread, stlwrite, /*72*/
251 stlioctl, stlstop, stlreset, stldevtotty,/*stallion*/
252 ttselect, stlmmap, stlstrategy },
253
254 - the line above used major number 72, but this may be different
255 on your system. Take note of what major number you are using.
256
257 - save the file and exit vi.
258
259
260 2.2. If using the istallion.c driver then do:
261
262 cd /usr/src/sys/i386/i386
263 vi conf.c
264 - add the following lines (in 2.1 I put them at line 729):
265
266 /* Stallion Intelligent Multiport Serial Driver */
267 #include "stl.h"
268 #if NSTL > 0
269 d_open_t stliopen;
270 d_close_t stliclose;
271 d_read_t stliread;
272 d_write_t stliwrite;
273 d_ioctl_t stliioctl;
274 d_stop_t stlistop;
275 d_ttycv_t stlidevtotty;
276 #define stlireset nxreset
277 #define stlimmap nxmmap
278 #define stlistrategy nxstrategy
279 #else
280 #define stliopen nxopen
281 #define stliclose nxclose
282 #define stliread nxread
283 #define stliwrite nxwrite
284 #define stliioctl nxioctl
285 #define stlistop nxstop
286 #define stlireset nxreset
287 #define stlimmap nxmmap
288 #define stlistrategy nxstrategy
289 #define stlidevtotty nxdevtotty
290 #endif
291
292
293 - and then inside the actual cdevsw structure definition, at the
294 last entry add (this is now line 1384 in the 2.1 conf.c):
295
296 { stliopen, stliclose, stliread, stliwrite, /*72*/
297 stliioctl, stlistop, stlireset, stlidevtotty,/*istallion*/
298 ttselect, stlimmap, stlistrategy },
299
300 - the line above used major number 72, but this may be different
301 on your system. Take note of what major number you are using.
302
303 - save the file and exit vi.
304
305 3. Add the driver source files to the kernel files list:
306
307 cd /usr/src/sys/i386/conf
308 vi files.i386
309 - add the following definition lines into the list (it is stored
310 alphabetically, so insert them appropriately):
311
312 i386/isa/istallion.c optional stli device-driver
313
314 i386/isa/stallion.c optional stl device-driver
315
316 - save the file and exit vi.
317
318 4. Add board probe entries into the kernel configuration file:
319
320 cd /usr/src/sys/i386/conf
321 cp GENERIC MYKERNEL
322 - if you already have a kernel config that you use then you
323 could just use that (instead of MYKERNEL)
324 vi MYKERNEL
325 - if only using ECH-PCI boards then you don't need to enter a
326 configuration line, the kernel will automatically detect
327 the board at boot up, so skip to step 5.
328 - enter a line for each board that you want to use. For stallion.c
329 boards entries should look like:
330
331 device stl0 at isa? port 0x2a0 tty irq 10
332
333 For istallion.c boards, the entries should look like:
334
335 device stli0 at isa? port 0x2a0 tty iomem 0xcc000 iosiz 0x1000 flags 23
336
337 (I suggest you put them after the sio? entries)
338 (Don't enter lines for ECH-PCI boards)
339 - change the entry resources as required. For the Stallion.c
340 entries this may involve changing the port address or irq.
341 For the istallion.c entries this may involve changing the port
342 address, iomem address, iosiz value and the flags. Select from
343 the following table for appropriate flags and iosiz values for
344 your board type:
345
346 EasyConnection 8/64 ISA: flags 23 iosiz 0x1000
347 EasyConnection 8/64 EISA: flags 24 iosiz 0x10000
348 EasyConnection 8/64 MCA: flags 25 iosiz 0x1000
349 ONboard ISA: flags 4 iosiz 0x10000
350 ONboard EISA: flags 7 iosiz 0x10000
351 ONboard MCA: flags 3 iosiz 0x10000
352 Brumby: flags 2 iosiz 0x4000
353 Stallion: flags 1 iosiz 0x10000
354
355 - save the file and exit
356
357 5. Build a new kernel using this configuration.
358
359 cd /usr/src/sys/i386/conf
360 config MYKERNEL
361 cd ../../compile/MYKERNEL
362 make depend
363 make all
364 make install
365
366
367 And there you have it! It is a little bit of effort to get it in there...
368
369 Once you have a new kernel built reboot to start it up. On startup the
370 Stallion board probes will report on whether the boards were found or not.
371 For each board found the driver will print out the type of board found,
372 and how many panels and ports it has.
373
374 If a board is not found by the driver but is actually in the system then the
375 most likely problem is that the IO address is incorrect. The easiest thing to
376 do is change the DIP switches on the board to the desired address and reboot.
377
378 On EasyIO and EasyConnection 8/32 boards the IRQ is software programmable,
379 so if there is a conflict you may need to change the IRQ used for a board in
380 the MYKERNEL configuration file and rebuild the kernel.
381
382 Note that the secondary IO address of the EasyConnection 8/32 boards is hard
383 coded into the stallion.c driver code. It is currently set to IO address
384 0x280. If you need to use a different address then you will need to edit this
385 file and change the variable named stl_ioshared.
386
387 On intelligent boards it is possible that the board shared memory region is
388 clashing with that of some other device. Check for this and change the device
389 or kernel configuration as required.
390
391
392 2.2 INTELLIGENT DRIVER OPERATION
393
394 The intelligent boards also need to have their "firmware" code downloaded
395 to them. This is done via a user level application supplied in the driver
396 package called "stlload". Compile this program where ever you dropped the
397 package files, by typing "make". In its simplest form you can then type
398 ./stlload -i cdk.sys
399 in this directory and that will download board 0 (assuming board 0 is an
400 EasyConnection 8/64 board). To download to an ONboard, Brumby or Stallion do:
401 ./stlload -i 2681.sys
402
403 Normally you would want all boards to be downloaded as part of the standard
404 system startup. To achieve this, add one of the lines above into the
405 /etc/rc.serial file. To download each board just add the "-b <brd-number>"
406 option to the line. You will need to download code for every board. You should
407 probably move the stlload program into a system directory, such as /usr/sbin.
408 Also, the default location of the cdk.sys image file in the stlload
409 down-loader is /usr/lib/stallion. Create that directory and put the cdk.sys
410 and 2681.sys files in it. (It's a convenient place to put them anyway). As an
411 example your /etc/rc.serial file might have the following lines added to it
412 (if you had 3 boards):
413 /usr/sbin/stlload -b 0 -i /usr/lib/stallion/cdk.sys
414 /usr/sbin/stlload -b 1 -i /usr/lib/stallion/2681.sys
415 /usr/sbin/stlload -b 2 -i /usr/lib/stallion/2681.sys
416
417 The image files cdk.sys and 2681.sys are specific to the board types. The
418 cdk.sys will only function correctly on an EasyConnection 8/64 board. Similarly
419 the 2681.sys image will only operate on ONboard, Brumby and Stallion boards.
420 If you load the wrong image file into a board it will fail to start up, and
421 of course the ports will not be operational!
422
423
424
425 3. USING THE DRIVER
426
427 Once the driver is installed you will need to setup some device nodes to
428 access the serial ports. Use the supplied "mkdevnods" script to automatically
429 create all required device entries for your boards. To make device nodes for
430 more than 1 board then just supply the number of boards you are using as a
431 command line parameter to mkdevnods and it will create nodes for that number
432 of boards. By default it will create device nodes for 1 board only.
433
434 Note that if the driver is not installed at character major number 72 then
435 you will need to edit the mkdevnods script and modify the STL_SERIALMAJOR
436 variable to the major number you are using.
437
438 Device nodes created for the normal serial port devices are named /dev/ttyEX
439 where X is the port number. (The second boards ports will start from ttyE64,
440 the third boards from ttyE128, etc). It will also create a set of modem call
441 out devices named cueX where again X is the port number.
442
443 For the most part the Stallion driver tries to emulate the standard PC system
444 com ports and the standard sio serial driver. The idea is that you should
445 be able to use Stallion board ports and com ports inter-changeably without
446 modifying anything but the device name. Anything that doesn't work like that
447 should be considered a bug in this driver!
448
449 Since this driver tries to emulate the standard serial ports as much as
450 possible then most system utilities should work as they do for the standard
451 com ports. Most importantly "stty" works as expected and "comcontrol" can be
452 used just like for the serial ports.
453
454 This driver should work with anything that works on standard com serial ports.
455 Having said that, I have used it on at least the following types of "things"
456 under FreeBSD:
457 a) standard dumb terminals (using getty)
458 b) modems (using cu, etc)
459 c) ppp (through pppd, kernel ppp)
460
461
462
463 4. NOTES
464
465 Be aware that these drivers are still very new, so there is sure to be some
466 bugs in them. Please email me any feedback on bugs, problems, or even good
467 experiences with these drivers!
468
469 You can use both drivers at once if you have a mix of board types installed
470 in a system. However to do this you will need to change the major number used
471 by one of the drivers. Currently both drivers use default major number 72 for
472 their devices. Change one driver to use some other major number (how this is
473 achieved will depend on the kernel version you are using), and then modify the
474 mkdevnods script to make device nodes based on those new major numbers. For
475 example, you could change the stallion.c driver to use major number 73. You
476 will also need to create device nodes with different names for the ports, for
477 eg ttyFXXX.
478
479 Currently the intelligent board driver (istallion.c) does not have the
480 ability to share a boards memory region with other boards (you can only do
481 this on EasyConnection 8/64 and ONboards normally anyway). It also does
482 not currently support any memory address ranges above the low 1Mb region.
483 These will be fixed in a future release of the driver.
484
485 Finding a free physical memory address range can be a problem. The older
486 boards like the Stallion and ONboard need large areas (64K or even 128K), so
487 they can be very difficult to get into a system. If you have 16 Mb of RAM
488 then you have no choice but to put them somewhere in the 640K -> 1Mb range.
489 ONboards require 64K, so typically 0xd0000 is good, or 0xe0000 on some
490 systems. If you have an original Stallion board, "V4.0" or Rev.O, then you
491 need a 64K memory address space, so again 0xd0000 and 0xe0000 are good. Older
492 Stallion boards are a much bigger problem. They need 128K of address space and
493 must be on a 128K boundary. If you don't have a VGA card then 0xc0000 might be
494 usable - there is really no other place you can put them below 1Mb.
495
496 Both the ONboard and old Stallion boards can use higher memory addresses as
497 well, but you must have less than 16Mb of RAM to be able to use them. Usual
498 high memory addresses used include 0xec0000 and 0xf00000.
499
500 The Brumby boards only require 16Kb of address space, so you can usually
501 squeeze them in somewhere. Common addresses are 0xc8000, 0xcc000, or in
502 the 0xd0000 range. EasyConnection 8/64 boards are even better, they only
503 require 4Kb of address space, again usually 0xc8000, 0xcc000 or 0xd0000
504 are good.
505
506 If you are using an EasyConnection 8/64-EI or ONboard/E then usually the
507 0xd0000 or 0xe0000 ranges are the best options below 1Mb. If neither of
508 them can be used then the high memory support to use the really high address
509 ranges is the best option. Typically the 2Gb range is convenient for them,
510 and gets them well out of the way.
511
512 The ports of the EasyIO-8M board do not have DCD or DTR signals. So these
513 ports cannot be used as real modem devices. Generally when using these
514 ports you should only use the cueX devices.
515
516 There is a new utility in this package that reports statistics on the
517 serial ports. You will need to have the ncurses library installed on your
518 system to build it.
519
520 To build the statistics display program type:
521 make stlstats
522 Once compiled simply run it (you will need to be root) and it will display
523 a port summary for the first board and panel installed. Use the digits to
524 select different board numbers, or 'n' to cycle through the panels on a
525 board. To look at detailed port information then hit 'p', that will display
526 detailed port 0 information. Use the digits and letters 'a' through 'f' to
527 select the different ports (on this board and panel).
528
529
530
531 5. ACKNOWLEDGEMENTS
532
533 This driver is loosely based on the code of the FreeBSD sio serial driver.
534 A big thanks to Stallion Technologies for the use of their equipment.
535
Cache object: b8f5c5c15e603812e22ca45e2be3526b
|