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