Merge branch 'vendor/NCURSES'
[dragonfly.git] / sys / platform / pc32 / isa / README.stl
984263bc 1$FreeBSD: src/sys/i386/isa/README.stl,v 2001/08/30 12:29:57 murray Exp $
1f2de5d4 2$DragonFly: src/sys/platform/pc32/isa/README.stl,v 1.3 2003/08/07 21:17:23 dillon Exp $
4Stallion Multiport Serial Driver Readme
7Version: 2.0.0
8Date: 22JAN98
9Author: Greg Ungerer (
15This is a set of FreeBSD drivers for most of the Stallion Technologies
16range of multiport serial boards.
18This driver has not been developed by Stallion Technologies. I developed it
19in my spare time in the hope that it would be useful. As such there is no
20warranty or support of any form. What this means is that this driver is not
21officially supported by Stallion Technologies, so don't ring their support
22if you can't get it working. They will probably not be able to help you.
23Instead email me if you have problems or bug reports and I will do what I
24can... (Sorry to sound so heavy handed, but I need to stress that this driver
25is not officially supported in any way.)
27This package actually contains two drivers. One is for the true Stallion
28intelligent multiport boards, and the other is for the smart range of boards.
30All host driver source is included in this package, and is copyrighted under
31a BSD style copyright. The board "firmware" code in this package is copyright
32Stallion Technologies (the files cdk.sys and 2681.sys).
37This driver supports the EasyIO, EasyConnection 8/32 and EasyConnection
388/64-PCI range of boards. These boards are not classic intelligent multiport
39boards, but are host based multiport boards that use Cirrus Logic CL-CD1400
40UART's, or on newer versions of the hardware use the Signetics 26C198 UART.
41Both of these are high performance UART's with built in FIFO's, automatic
42flow control and a host of other features.
44The EasyIO range of cards comes in 4 forms, the EasyIO-4, EasyIO-8,
45EasyIO-8M and EasyIO-8-PCI. The first three are ISA based boards while
46the last is a PCI bus board. All of these are non-expandable, low cost,
47multiport boards with 4 or 8 RS-232C ports. Each ISA EasyIO board requires 8
48bytes of I/O address space and 1 interrupt. The PCI EasyIO board uses 64
49bytes of I/O address space and 1 interrupt. On EISA and PCI systems it is
50possible to share 1 interrupt between multiple boards. The EasyIO-4 has 10
51pin RJ connectors, and the EasyIO-8 comes with a dongle cable with either 10
52pin RJ connectors or DB-25 connectors. The EasyIO-8M has 6 pin RJ connectors.
54The EasyConnection 8/32 family of boards is a relatively low cost modular
55range of multiport serial boards. The EasyConnection 8/32 boards can be
56configured to have from 8 to 32 serial ports by plugging in external serial
57port modules that contain either 8 or 16 ports each. There is a wide range
58of 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
60ports. The EasyConnection 8/32 boards come in ISA, PCI and MCA bus versions.
61The board takes the form of a host adapter card, with an external connector
62cable that plugs into the external modules. The external modules just clip
63together to add ports (BTW, they are NOT hot pluggable). Each ISA
64EasyConnection 8/32 board requires two separate I/O address ranges, one two
65bytes in size and a secondary region of 32 bytes. Each PCI EasyConnection
668/32 requires two regions of I/O address space, normally these will be
67automatically allocated by the system BIOS at power on time. Each MCA
68EasyConnection board requires one I/O address region 64 bytes in size. All
69board types also require one interrupt. On EISA systems multiple boards can
70share one interrupt. The secondary I/O range of the ISA board (the 32 byte
71range) can be shared between multiple boards on any bus type.
73The EasyConnection 8/64-PCI family is similar to the EasyConnection 8/32-PCI
74board, and uses the same external modules. It is supported by the smart
75board driver - not the intelligent board driver. It uses 2 regions of I/O
76address space, both 64 bytes in size, and 1 interrupt.
81This driver is for Stallion's range of true intelligent multiport boards.
82It supports the EasyConnection 8/64, ONboard and Brumby families of multiport
83boards. The EasyConnection 8/64 and ONboard boards come in ISA, EISA and
84Microchannel bus versions. The Brumby boards are only available in ISA
85versions. This driver can also work with the original Stallion board, but
86these are no longer supported by Stallion Technologies.
88The EasyConnection 8/64 family of boards is a medium cost, high performance,
89modular range of intelligent multiport serial boards. The EasyConnection 8/64
90boards can be configured to have from 8 to 64 serial ports by plugging in
91external serial port modules that contain either 8 or 16 ports each (these
92modules are the same used by the EasyConnection 8/32 board). There is a wide
93range of external modules available that offer: DB-25 connectors, RJ-45
94connectors (both with RS-232 D and E compatible drivers), and also RS-422 and
95RS-485 ports. The board takes the form of a host adapter card, with an external
96connector cable that plugs into the external modules. The external modules
97just clip together to add ports (BTW, they are NOT hot pluggable). Each
98EasyConnection 8/64 board requires 4 bytes of I/O address space and a region
99of memory space. The size of the memory region required depends on the exact
100board type. The EISA version requires 64 Kbytes of address space (that can
101reside anywhere in the 4 Gigabyte physical address space). The ISA and MCA
102boards require 4 Kbytes of address space (which must reside in the lower
1031 Mbyte of physical address space - typically in the c8000 to e0000 range).
104No interrupts are required. The physical memory region of multiple
105EasyConnection 8/64 boards can be shared, but each board must have a separate
106I/O address.
108The ONboard family of boards are traditional intelligent multiport serial
109boards. They are Stallion's older range of boards with a limited expansion
110capability. They come in 4, 8, 12, 16 and 32 port versions. The board uses
111the same base card (which has 4 ports on it) and is expanded to more ports via
112a mezzanine board that attaches directly onto the base card. External panels
113plug into the ONboard providing RS-232C ports with DB-25 plugs. An RS-422
114DB-25 dual interface panel is also available. The ISA and microchannel
115ONboards require 16 bytes of I/O address space and 64K bytes of memory
116space. The memory space can be anywhere in the 16 Mbyte ISA bus address
117range. No interrupt is required. The EISA ONboard requires 64 Kbytes of
118memory space that can be anywhere in the 4 Gigabyte physical address space.
119All ONboard boards can share their memory region with other ONboards (or
120EasyConnection 8/64 boards).
122The Brumby family of boards are traditional, low cost intelligent multiport
123serial boards. They are non-expandable and come in 4, 8 and 16 port versions.
124They 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
126requires 16 bytes of I/O address space and 16 Kbytes of memory space. No
127interrupts are required.
129The original Stallion boards are old. They went out of production some years
130back and are no longer supported. They offer limited expandability and are
131available in 8 or 16 port configurations. An external panel houses 16 RS-232C
132ports with DB-9 connectors. They require 16 bytes of I/O address space, and
133either 64K or 128K of memory space. No interrupt is required.
135That's the boards supported by the second driver. The ONboard, Brumby and
136Stallion boards are Stallion's older range of intelligent multiports - so
137there are lots of them around. They only support a maximum baud rate of
13838400. The EasyConnection 8/64 is a true high performance intelligent
139multiport board, having much greater throughput than any of Stallion's
140older boards. It also supports speeds up to 460800 baud.
145Stallion Technologies has offices all over the world, as well as many more
146distributors and resellers. To find out about local availability please
147contact the nearest Stallion office and they can give you all the information
148you need. Look in the "Offices" file in the driver package for a current list
149of Stallion Technologies offices.
151Another good source of information about the Stallion range of boards and
152local availability is on the Stallion Web page. Check it out at
159This driver, as is, will work on a FreeBSD 2.2.5 system. It will run on any
160FreeBSD system version 2.0.5 and up, including -current version systems.
161For systems other than 2.2.0 and 2.2.5 you will need to change the version
162define in the driver source. Look for the symbol name VFREEBSD, then change
163it to match the version number of your FreeBSD system (for example 2.2.5 is
164225, 3.0.0 would be 300, etc).
166Recent versions of FreeBSD 2.1.5 and above include the Stallion drivers
167in the distribution. You may still need to use this source for these systems.
168If the code in this package is newer than the version enclosed on your
169FreeBSD installation then you should use this source instead.
171You will need to build a new kernel to use this driver. So the first thing
172you 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.
175The drivers can support up to 8 boards. For the smart board driver any
176combination of EasyIO, EasyConnection 8/32 and EasyConnection 8/64-PCI
177boards can be installed. For the intelligent any combination of
178EasyConnection 8/64 (ISA and EISA), ONboard, Brumby or original Stallion.
179So there is a theoretical maximum of 512 ports.
1812.1 Instructions to install:
1831. Copy the driver source files into the kernel source tree.
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
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.
1942. If you are using FreeBSD version 2.2.0 or above then jump to step 4 now.
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.
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).
2072.1. If using the stallion.c driver then do:
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):
213/* Stallion Multiport Serial Driver */
1f2de5d4 214#include "use_stl.h"
215#if NSTL > 0
216d_open_t stlopen;
217d_close_t stlclose;
218d_read_t stlread;
219d_write_t stlwrite;
220d_ioctl_t stlioctl;
221d_stop_t stlstop;
222d_ttycv_t stldevtotty;
223#define stlreset nxreset
224#define stlmmap nxmmap
225#define stlstrategy nxstrategy
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
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):
243 { stlopen, stlclose, stlread, stlwrite, /*72*/
244 stlioctl, stlstop, stlreset, stldevtotty,/*stallion*/
245 ttselect, stlmmap, stlstrategy },
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.
250 - save the file and exit vi.
2532.2. If using the istallion.c driver then do:
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):
259/* Stallion Intelligent Multiport Serial Driver */
1f2de5d4 260#include "use_stl.h"
261#if NSTL > 0
262d_open_t stliopen;
263d_close_t stliclose;
264d_read_t stliread;
265d_write_t stliwrite;
266d_ioctl_t stliioctl;
267d_stop_t stlistop;
268d_ttycv_t stlidevtotty;
269#define stlireset nxreset
270#define stlimmap nxmmap
271#define stlistrategy nxstrategy
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
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):
289 { stliopen, stliclose, stliread, stliwrite, /*72*/
290 stliioctl, stlistop, stlireset, stlidevtotty,/*istallion*/
291 ttselect, stlimmap, stlistrategy },
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.
296 - save the file and exit vi.
2983. Add the driver source files to the kernel files list:
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):
305i386/isa/istallion.c optional stli device-driver
307i386/isa/stallion.c optional stl device-driver
309 - save the file and exit vi.
3114. Add board probe entries into the kernel configuration file:
313 cd /usr/src/sys/i386/conf
315 - if you already have a kernel config that you use then you
316 could just use that (instead of 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:
324device stl0 at isa? port 0x2a0 tty irq 10 vector stlintr
326 For istallion.c boards, the entries should look like:
328device stli0 at isa? port 0x2a0 tty iomem 0xcc000 iosiz 0x1000 flags 23
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:
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
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.
3535. Build a new kernel using this configuration.
355 cd /usr/src/sys/i386/conf
356 config MYKERNEL
357 cd ../../compile/MYKERNEL
358 make depend
359 make all
360 make install
363And there you have it!
365Once you have a new kernel built reboot to start it up. On startup the
366Stallion board probes will report on whether the boards were found or not.
367For each board found the driver will print out the type of board found,
368and how many panels and ports it has.
370If a board is not found by the driver but is actually in the system then the
371most likely problem is that the IO address is incorrect. The easiest thing to
372do is change the DIP switches on the board to the desired address and reboot.
374On EasyIO and EasyConnection 8/32 boards the IRQ is software programmable,
375so if there is a conflict you may need to change the IRQ used for a board in
376the MYKERNEL configuration file and rebuild the kernel.
378Note that the secondary IO address of the EasyConnection 8/32 boards is hard
379coded into the stallion.c driver code. It is currently set to IO address
3800x280. If you need to use a different address then you will need to edit this
381file and change the variable named stl_ioshared.
383On intelligent boards it is possible that the board shared memory region is
384clashing with that of some other device. Check for this and change the device
385or kernel configuration as required.
390The intelligent boards also need to have their "firmware" code downloaded
391to them. This is done via a user level application supplied in the driver
392package called "stlload". Compile this program where ever you dropped the
393package files, by typing "make". In its simplest form you can then type
394 ./stlload -i cdk.sys
395in this directory and that will download board 0 (assuming board 0 is an
396EasyConnection 8/64 board). To download to an ONboard, Brumby or Stallion do:
397 ./stlload -i 2681.sys
399Normally you would want all boards to be downloaded as part of the standard
400system 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>"
402option to the line. You will need to download code for every board. You should
403probably move the stlload program into a system directory, such as /usr/sbin.
404Also, the default location of the cdk.sys image file in the stlload
405down-loader is /usr/libdata/stallion. Create that directory and put the
406cdk.sys and 2681.sys files in it. (It's a convenient place to put them
407anyway). As an example your /etc/rc.serial file might have the following
408lines 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
413The image files cdk.sys and 2681.sys are specific to the board types. The
414cdk.sys will only function correctly on an EasyConnection 8/64 (ISA and EISA)
415board. Similarly the 2681.sys image will only operate on ONboard, Brumby and
416Stallion boards. If you load the wrong image file into a board it will fail
417to start up, and of course the ports will not be operational!
423Once the driver is installed you will need to setup some device nodes to
424access the serial ports. Use the supplied "mkdevnods" script to automatically
425create all required device entries for your boards. To make device nodes for
426more than 1 board then just supply the number of boards you are using as a
427command line parameter to mkdevnods and it will create nodes for that number
428of boards. By default it will create device nodes for 1 board only.
430Note that if the driver is not installed at character major number 72 then
431you will need to edit the mkdevnods script and modify the STL_SERIALMAJOR
432variable to the major number you are using.
434Device nodes created for the normal serial port devices are named /dev/ttyEX
435where X is the port number. (The second boards ports will start from ttyE64,
436the third boards from ttyE128, etc). It will also create a set of modem call
437out devices named cueX where again X is the port number.
439For the most part the Stallion driver tries to emulate the standard PC system
440com ports and the standard sio serial driver. The idea is that you should
441be able to use Stallion board ports and com ports inter-changeably without
442modifying anything but the device name. Anything that doesn't work like that
443should be considered a bug in this driver!
445Since this driver tries to emulate the standard serial ports as much as
446possible then most system utilities should work as they do for the standard
447com ports. Most importantly "stty" works as expected and "comcontrol" can be
448used just like for the serial ports.
450This driver should work with anything that works on standard com serial ports.
451Having said that, I have used it on at least the following types of "things"
452under FreeBSD:
453 a) standard dumb terminals (using getty)
454 b) modems (using cu, etc)
455 c) ppp (through pppd, kernel ppp)
4594. NOTES
461Please email me any feedback on bugs, problems, or even good experiences
462with these drivers!
464You can use both drivers at once if you have a mix of board types installed
465in a system. On FreeBSD 2.1.5 and later systems each driver has been
466assigned a different major number. On earlier FreeBSD versions you may
467need to manually assign each driver a different major number. You will
468also need to adjust the names of the device nodes for each board. To do
469this modify the mkdevnods script to make device nodes based on those new
470major numbers. For example, you could change the istallion.c driver to use
471major number 75. You will also need to create device nodes with different
472names for the ports, for eg ttyFXXX.
474Currently the intelligent board driver (istallion.c) does not have the
475ability to share a boards memory region with other boards (you can only do
476this on EasyConnection 8/64 and ONboards normally anyway). It also does
477not currently support any memory address ranges above the low 1Mb region.
478These will be fixed in a future release of the driver.
480Finding a free physical memory address range can be a problem. The older
481boards like the Stallion and ONboard need large areas (64K or even 128K), so
482they can be very difficult to get into a system. If you have 16 Mb of RAM
483then you have no choice but to put them somewhere in the 640K -> 1Mb range.
484ONboards require 64K, so typically 0xd0000 is good, or 0xe0000 on some
485systems. If you have an original Stallion board, "V4.0" or Rev.O, then you
486need a 64K memory address space, so again 0xd0000 and 0xe0000 are good. Older
487Stallion boards are a much bigger problem. They need 128K of address space and
488must be on a 128K boundary. If you don't have a VGA card then 0xc0000 might be
489usable - there is really no other place you can put them below 1Mb.
491Both the ONboard and old Stallion boards can use higher memory addresses as
492well, but you must have less than 16Mb of RAM to be able to use them. Usual
493high memory addresses used include 0xec0000 and 0xf00000.
495The Brumby boards only require 16Kb of address space, so you can usually
496squeeze them in somewhere. Common addresses are 0xc8000, 0xcc000, or in
497the 0xd0000 range. EasyConnection 8/64 boards are even better, they only
498require 4Kb of address space, again usually 0xc8000, 0xcc000 or 0xd0000
499are good.
501If you are using an EasyConnection 8/64-EI or ONboard/E then usually the
5020xd0000 or 0xe0000 ranges are the best options below 1Mb. If neither of
503them can be used then the high memory support to use the really high address
504ranges is the best option. Typically the 2Gb range is convenient for them,
505and gets them well out of the way.
507The ports of the EasyIO-8M board do not have DCD or DTR signals. So these
508ports cannot be used as real modem devices. Generally when using these
509ports you should only use the cueX devices.
511There is a utility in this package that reports statistics on the serial
512ports. You will need to have the ncurses library installed on your system
513to build it.
515To build the statistics display program type:
516 make stlstats
517Once compiled simply run it (you will need to be root) and it will display
518a port summary for the first board and panel installed. Use the digits to
519select different board numbers, or 'n' to cycle through the panels on a
520board. To look at detailed port information then hit 'p', that will display
521detailed port 0 information. Use the digits and letters 'a' through 'f' to
522select the different ports (on this board and panel).
528This driver is loosely based on the code of the FreeBSD sio serial driver.
529A big thanks to Stallion Technologies for the use of their equipment.