aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/serial
diff options
context:
space:
mode:
authorJean Delvare <jdelvare@suse.de>2014-03-31 08:54:25 -0400
committerGreg Kroah-Hartman <gregkh@linuxfoundation.org>2014-04-16 17:20:34 -0400
commit3053075cea4e1d385cf0b003ffeb860cc8b378fb (patch)
tree34715f61ac6d6077e7a36e2dfb1b26406f34265a /Documentation/serial
parentd758c9c1b36b4d9a141c2146c70398d756167ed1 (diff)
Documentation/serial: Delete obsolete driver documentation
These serial drivers were removed in kernel v3.1, so we can drop their documentation files and references to their magic numbers and parameters. There are still references to these old drivers in Documentation/devices.txt but I'm afraid they can't be removed. Signed-off-by: Jean Delvare <jdelvare@suse.de> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Cc: Jiri Slaby <jslaby@suse.cz> Cc: Rob Landley <rob@landley.net> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Diffstat (limited to 'Documentation/serial')
-rw-r--r--Documentation/serial/00-INDEX8
-rw-r--r--Documentation/serial/digiepca.txt98
-rw-r--r--Documentation/serial/riscom8.txt36
-rw-r--r--Documentation/serial/specialix.txt383
-rw-r--r--Documentation/serial/sx.txt294
5 files changed, 0 insertions, 819 deletions
diff --git a/Documentation/serial/00-INDEX b/Documentation/serial/00-INDEX
index f9c6b5ed03e7..8021a9f29fc5 100644
--- a/Documentation/serial/00-INDEX
+++ b/Documentation/serial/00-INDEX
@@ -2,23 +2,15 @@
2 - this file. 2 - this file.
3README.cycladesZ 3README.cycladesZ
4 - info on Cyclades-Z firmware loading. 4 - info on Cyclades-Z firmware loading.
5digiepca.txt
6 - info on Digi Intl. {PC,PCI,EISA}Xx and Xem series cards.
7driver 5driver
8 - intro to the low level serial driver. 6 - intro to the low level serial driver.
9moxa-smartio 7moxa-smartio
10 - file with info on installing/using Moxa multiport serial driver. 8 - file with info on installing/using Moxa multiport serial driver.
11n_gsm.txt 9n_gsm.txt
12 - GSM 0710 tty multiplexer howto. 10 - GSM 0710 tty multiplexer howto.
13riscom8.txt
14 - notes on using the RISCom/8 multi-port serial driver.
15rocket.txt 11rocket.txt
16 - info on the Comtrol RocketPort multiport serial driver. 12 - info on the Comtrol RocketPort multiport serial driver.
17serial-rs485.txt 13serial-rs485.txt
18 - info about RS485 structures and support in the kernel. 14 - info about RS485 structures and support in the kernel.
19specialix.txt
20 - info on hardware/driver for specialix IO8+ multiport serial card.
21sx.txt
22 - info on the Specialix SX/SI multiport serial driver.
23tty.txt 15tty.txt
24 - guide to the locking policies of the tty layer. 16 - guide to the locking policies of the tty layer.
diff --git a/Documentation/serial/digiepca.txt b/Documentation/serial/digiepca.txt
deleted file mode 100644
index f2560e22f2c9..000000000000
--- a/Documentation/serial/digiepca.txt
+++ /dev/null
@@ -1,98 +0,0 @@
1NOTE: This driver is obsolete. Digi provides a 2.6 driver (dgdm) at
2http://www.digi.com for PCI cards. They no longer maintain this driver,
3and have no 2.6 driver for ISA cards.
4
5This driver requires a number of user-space tools. They can be acquired from
6http://www.digi.com, but only works with 2.4 kernels.
7
8
9The Digi Intl. epca driver.
10----------------------------
11The Digi Intl. epca driver for Linux supports the following boards:
12
13Digi PC/Xem, PC/Xr, PC/Xe, PC/Xi, PC/Xeve
14Digi EISA/Xem, PCI/Xem, PCI/Xr
15
16Limitations:
17------------
18Currently the driver only autoprobes for supported PCI boards.
19
20The Linux MAKEDEV command does not support generating the Digiboard
21Devices. Users executing digiConfig to setup EISA and PC series cards
22will have their device nodes automatically constructed (cud?? for ~CLOCAL,
23and ttyD?? for CLOCAL). Users wishing to boot their board from the LILO
24prompt, or those users booting PCI cards may use buildDIGI to construct
25the necessary nodes.
26
27Notes:
28------
29This driver may be configured via LILO. For users who have already configured
30their driver using digiConfig, configuring from LILO will override previous
31settings. Multiple boards may be configured by issuing multiple LILO command
32lines. For examples see the bottom of this document.
33
34Device names start at 0 and continue up. Beware of this as previous Digi
35drivers started device names with 1.
36
37PCI boards are auto-detected and configured by the driver. PCI boards will
38be allocated device numbers (internally) beginning with the lowest PCI slot
39first. In other words a PCI card in slot 3 will always have higher device
40nodes than a PCI card in slot 1.
41
42LILO config examples:
43---------------------
44Using LILO's APPEND command, a string of comma separated identifiers or
45integers can be used to configure supported boards. The six values in order
46are:
47
48 Enable/Disable this card or Override,
49 Type of card: PC/Xe (AccelePort) (0), PC/Xeve (1), PC/Xem or PC/Xr (2),
50 EISA/Xem (3), PC/64Xe (4), PC/Xi (5),
51 Enable/Disable alternate pin arrangement,
52 Number of ports on this card,
53 I/O Port where card is configured (in HEX if using string identifiers),
54 Base of memory window (in HEX if using string identifiers),
55
56NOTE : PCI boards are auto-detected and configured. Do not attempt to
57configure PCI boards with the LILO append command. If you wish to override
58previous configuration data (As set by digiConfig), but you do not wish to
59configure any specific card (Example if there are PCI cards in the system)
60the following override command will accomplish this:
61-> append="digi=2"
62
63Samples:
64 append="digiepca=E,PC/Xe,D,16,200,D0000"
65 or
66 append="digi=1,0,0,16,512,851968"
67
68Supporting Tools:
69-----------------
70Supporting tools include digiDload, digiConfig, buildPCI, and ditty. See
71drivers/char/README.epca for more details. Note,
72this driver REQUIRES that digiDload be executed prior to it being used.
73Failure to do this will result in an ENODEV error.
74
75Documentation:
76--------------
77Complete documentation for this product may be found in the tool package.
78
79Sources of information and support:
80-----------------------------------
81Digi Intl. support site for this product:
82
83-> http://www.digi.com
84
85Acknowledgments:
86----------------
87Much of this work (And even text) was derived from a similar document
88supporting the original public domain DigiBoard driver Copyright (C)
891994,1995 Troy De Jongh. Many thanks to Christoph Lameter
90(christoph@lameter.com) and Mike McLagan (mike.mclagan@linux.org) who authored
91and contributed to the original document.
92
93Changelog:
94----------
9510-29-04: Update status of driver, remove dead links in document
96 James Nelson <james4765@gmail.com>
97
982000 (?) Original Document
diff --git a/Documentation/serial/riscom8.txt b/Documentation/serial/riscom8.txt
deleted file mode 100644
index 14f61fdad7ca..000000000000
--- a/Documentation/serial/riscom8.txt
+++ /dev/null
@@ -1,36 +0,0 @@
1* NOTE - this is an unmaintained driver. The original author cannot be located.
2
3SDL Communications is now SBS Technologies, and does not have any
4information on these ancient ISA cards on their website.
5
6James Nelson <james4765@gmail.com> - 12-12-2004
7
8 This is the README for RISCom/8 multi-port serial driver
9 (C) 1994-1996 D.Gorodchanin
10 See file LICENSE for terms and conditions.
11
12NOTE: English is not my native language.
13 I'm sorry for any mistakes in this text.
14
15Misc. notes for RISCom/8 serial driver, in no particular order :)
16
171) This driver can support up to 4 boards at time.
18 Use string "riscom8=0xXXX,0xXXX,0xXXX,0xXXX" at LILO prompt, for
19 setting I/O base addresses for boards. If you compile driver
20 as module use modprobe options "iobase=0xXXX iobase1=0xXXX iobase2=..."
21
222) The driver partially supports famous 'setserial' program, you can use almost
23 any of its options, excluding port & irq settings.
24
253) There are some misc. defines at the beginning of riscom8.c, please read the
26 comments and try to change some of them in case of problems.
27
284) I consider the current state of the driver as BETA.
29
305) SDL Communications WWW page is http://www.sdlcomm.com.
31
326) You can use the MAKEDEV program to create RISCom/8 /dev/ttyL* entries.
33
347) Minor numbers for first board are 0-7, for second 8-15, etc.
35
3622 Apr 1996.
diff --git a/Documentation/serial/specialix.txt b/Documentation/serial/specialix.txt
deleted file mode 100644
index 6eb6f3a3331c..000000000000
--- a/Documentation/serial/specialix.txt
+++ /dev/null
@@ -1,383 +0,0 @@
1
2 specialix.txt -- specialix IO8+ multiport serial driver readme.
3
4
5
6 Copyright (C) 1997 Roger Wolff (R.E.Wolff@BitWizard.nl)
7
8 Specialix pays for the development and support of this driver.
9 Please DO contact io8-linux@specialix.co.uk if you require
10 support.
11
12 This driver was developed in the BitWizard linux device
13 driver service. If you require a linux device driver for your
14 product, please contact devices@BitWizard.nl for a quote.
15
16 This code is firmly based on the riscom/8 serial driver,
17 written by Dmitry Gorodchanin. The specialix IO8+ card
18 programming information was obtained from the CL-CD1865 Data
19 Book, and Specialix document number 6200059: IO8+ Hardware
20 Functional Specification, augmented by document number 6200088:
21 Merak Hardware Functional Specification. (IO8+/PCI is also
22 called Merak)
23
24
25 This program is free software; you can redistribute it and/or
26 modify it under the terms of the GNU General Public License as
27 published by the Free Software Foundation; either version 2 of
28 the License, or (at your option) any later version.
29
30 This program is distributed in the hope that it will be
31 useful, but WITHOUT ANY WARRANTY; without even the implied
32 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
33 PURPOSE. See the GNU General Public License for more details.
34
35 You should have received a copy of the GNU General Public
36 License along with this program; if not, write to the Free
37 Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
38 USA.
39
40
41Intro
42=====
43
44
45This file contains some random information, that I like to have online
46instead of in a manual that can get lost. Ever misplace your Linux
47kernel sources? And the manual of one of the boards in your computer?
48
49
50Addresses and interrupts
51========================
52
53Address dip switch settings:
54The dip switch sets bits 2-9 of the IO address.
55
56 9 8 7 6 5 4 3 2
57 +-----------------+
58 0 | X X X X X X X |
59 | | = IoBase = 0x100
60 1 | X |
61 +-----------------+ ------ RS232 connectors ---->
62
63 | | |
64 edge connector
65 | | |
66 V V V
67
68Base address 0x100 caused a conflict in one of my computers once. I
69haven't the foggiest why. My Specialix card is now at 0x180. My
70other computer runs just fine with the Specialix card at 0x100....
71The card occupies 4 addresses, but actually only two are really used.
72
73The PCI version doesn't have any dip switches. The BIOS assigns
74an IO address.
75
76The driver now still autoprobes at 0x100, 0x180, 0x250 and 0x260. If
77that causes trouble for you, please report that. I'll remove
78autoprobing then.
79
80The driver will tell the card what IRQ to use, so you don't have to
81change any jumpers to change the IRQ. Just use a command line
82argument (irq=xx) to the insmod program to set the interrupt.
83
84The BIOS assigns the IRQ on the PCI version. You have no say in what
85IRQ to use in that case.
86
87If your specialix cards are not at the default locations, you can use
88the kernel command line argument "specialix=io0,irq0,io1,irq1...".
89Here "io0" is the io address for the first card, and "irq0" is the
90irq line that the first card should use. And so on.
91
92Examples.
93
94You use the driver as a module and have three cards at 0x100, 0x250
95and 0x180. And some way or another you want them detected in that
96order. Moreover irq 12 is taken (e.g. by your PS/2 mouse).
97
98 insmod specialix.o iobase=0x100,0x250,0x180 irq=9,11,15
99
100The same three cards, but now in the kernel would require you to
101add
102
103 specialix=0x100,9,0x250,11,0x180,15
104
105to the command line. This would become
106
107 append="specialix=0x100,9,0x250,11,0x180,15"
108
109in your /etc/lilo.conf file if you use lilo.
110
111The Specialix driver is slightly odd: It allows you to have the second
112or third card detected without having a first card. This has
113advantages and disadvantages. A slot that isn't filled by an ISA card,
114might be filled if a PCI card is detected. Thus if you have an ISA
115card at 0x250 and a PCI card, you would get:
116
117sx0: specialix IO8+ Board at 0x100 not found.
118sx1: specialix IO8+ Board at 0x180 not found.
119sx2: specialix IO8+ board detected at 0x250, IRQ 12, CD1865 Rev. B.
120sx3: specialix IO8+ Board at 0x260 not found.
121sx0: specialix IO8+ board detected at 0xd800, IRQ 9, CD1865 Rev. B.
122
123This would happen if you don't give any probe hints to the driver.
124If you would specify:
125
126 specialix=0x250,11
127
128you'd get the following messages:
129
130sx0: specialix IO8+ board detected at 0x250, IRQ 11, CD1865 Rev. B.
131sx1: specialix IO8+ board detected at 0xd800, IRQ 9, CD1865 Rev. B.
132
133ISA probing is aborted after the IO address you gave is exhausted, and
134the PCI card is now detected as the second card. The ISA card is now
135also forced to IRQ11....
136
137
138Baud rates
139==========
140
141The rev 1.2 and below boards use a CL-CD1864. These chips can only
142do 64kbit. The rev 1.3 and newer boards use a CL-CD1865. These chips
143are officially capable of 115k2.
144
145The Specialix card uses a 25MHz crystal (in times two mode, which in
146fact is a divided by two mode). This is not enough to reach the rated
147115k2 on all ports at the same time. With this clock rate you can only
148do 37% of this rate. This means that at 115k2 on all ports you are
149going to lose characters (The chip cannot handle that many incoming
150bits at this clock rate.) (Yes, you read that correctly: there is a
151limit to the number of -=bits=- per second that the chip can handle.)
152
153If you near the "limit" you will first start to see a graceful
154degradation in that the chip cannot keep the transmitter busy at all
155times. However with a central clock this slow, you can also get it to
156miss incoming characters. The driver will print a warning message when
157you are outside the official specs. The messages usually show up in
158the file /var/log/messages .
159
160The specialix card cannot reliably do 115k2. If you use it, you have
161to do "extensive testing" (*) to verify if it actually works.
162
163When "mgetty" communicates with my modem at 115k2 it reports:
164got: +++[0d]ATQ0V1H0[0d][0d][8a]O[cb][0d][8a]
165 ^^^^ ^^^^ ^^^^
166
167The three characters that have the "^^^" under them have suffered a
168bit error in the highest bit. In conclusion: I've tested it, and found
169that it simply DOESN'T work for me. I also suspect that this is also
170caused by the baud rate being just a little bit out of tune.
171
172I upgraded the crystal to 66Mhz on one of my Specialix cards. Works
173great! Contact me for details. (Voids warranty, requires a steady hand
174and more such restrictions....)
175
176
177(*) Cirrus logic CD1864 databook, page 40.
178
179
180Cables for the Specialix IO8+
181=============================
182
183The pinout of the connectors on the IO8+ is:
184
185 pin short direction long name
186 name
187 Pin 1 DCD input Data Carrier Detect
188 Pin 2 RXD input Receive
189 Pin 3 DTR/RTS output Data Terminal Ready/Ready To Send
190 Pin 4 GND - Ground
191 Pin 5 TXD output Transmit
192 Pin 6 CTS input Clear To Send
193
194
195 -- 6 5 4 3 2 1 --
196 | |
197 | |
198 | |
199 | |
200 +----- -----+
201 |__________|
202 clip
203
204 Front view of an RJ12 connector. Cable moves "into" the paper.
205 (the plug is ready to plug into your mouth this way...)
206
207
208 NULL cable. I don't know who is going to use these except for
209 testing purposes, but I tested the cards with this cable. (It
210 took quite a while to figure out, so I'm not going to delete
211 it. So there! :-)
212
213
214 This end goes This end needs
215 straight into the some twists in
216 RJ12 plug. the wiring.
217 IO8+ RJ12 IO8+ RJ12
218 1 DCD white -
219 - - 1 DCD
220 2 RXD black 5 TXD
221 3 DTR/RTS red 6 CTS
222 4 GND green 4 GND
223 5 TXD yellow 2 RXD
224 6 CTS blue 3 DTR/RTS
225
226
227 Same NULL cable, but now sorted on the second column.
228
229 1 DCD white -
230 - - 1 DCD
231 5 TXD yellow 2 RXD
232 6 CTS blue 3 DTR/RTS
233 4 GND green 4 GND
234 2 RXD black 5 TXD
235 3 DTR/RTS red 6 CTS
236
237
238
239 This is a modem cable usable for hardware handshaking:
240 RJ12 DB25 DB9
241 1 DCD white 8 DCD 1 DCD
242 2 RXD black 3 RXD 2 RXD
243 3 DTR/RTS red 4 RTS 7 RTS
244 4 GND green 7 GND 5 GND
245 5 TXD yellow 2 TXD 3 TXD
246 6 CTS blue 5 CTS 8 CTS
247 +---- 6 DSR 6 DSR
248 +---- 20 DTR 4 DTR
249
250 This is a modem cable usable for software handshaking:
251 It allows you to reset the modem using the DTR ioctls.
252 I (REW) have never tested this, "but xxxxxxxxxxxxx
253 says that it works." If you test this, please
254 tell me and I'll fill in your name on the xxx's.
255
256 RJ12 DB25 DB9
257 1 DCD white 8 DCD 1 DCD
258 2 RXD black 3 RXD 2 RXD
259 3 DTR/RTS red 20 DTR 4 DTR
260 4 GND green 7 GND 5 GND
261 5 TXD yellow 2 TXD 3 TXD
262 6 CTS blue 5 CTS 8 CTS
263 +---- 6 DSR 6 DSR
264 +---- 4 RTS 7 RTS
265
266 I bought a 6 wire flat cable. It was colored as indicated.
267 Check that yours is the same before you trust me on this.
268
269
270Hardware handshaking issues.
271============================
272
273The driver can be told to operate in two different ways. The default
274behaviour is specialix.sx_rtscts = 0 where the pin behaves as DTR when
275hardware handshaking is off. It behaves as the RTS hardware
276handshaking signal when hardware handshaking is selected.
277
278When you use this, you have to use the appropriate cable. The
279cable will either be compatible with hardware handshaking or with
280software handshaking. So switching on the fly is not really an
281option.
282
283I actually prefer to use the "specialix.sx_rtscts=1" option.
284This makes the DTR/RTS pin always an RTS pin, and ioctls to
285change DTR are always ignored. I have a cable that is configured
286for this.
287
288
289Ports and devices
290=================
291
292Port 0 is the one furthest from the card-edge connector.
293
294Devices:
295
296You should make the devices as follows:
297
298bash
299cd /dev
300for i in 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 \
301 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
302do
303 echo -n "$i "
304 mknod /dev/ttyW$i c 75 $i
305 mknod /dev/cuw$i c 76 $i
306done
307echo ""
308
309If your system doesn't come with these devices preinstalled, bug your
310linux-vendor about this. They have had ample time to get this
311implemented by now.
312
313You cannot have more than 4 boards in one computer. The card only
314supports 4 different interrupts. If you really want this, contact me
315about this and I'll give you a few tips (requires soldering iron)....
316
317If you have enough PCI slots, you can probably use more than 4 PCI
318versions of the card though....
319
320The PCI version of the card cannot adhere to the mechanical part of
321the PCI spec because the 8 serial connectors are simply too large. If
322it doesn't fit in your computer, bring back the card.
323
324
325------------------------------------------------------------------------
326
327
328 Fixed bugs and restrictions:
329 - During initialization, interrupts are blindly turned on.
330 Having a shadow variable would cause an extra memory
331 access on every IO instruction.
332 - The interrupt (on the card) should be disabled when we
333 don't allocate the Linux end of the interrupt. This allows
334 a different driver/card to use it while all ports are not in
335 use..... (a la standard serial port)
336 == An extra _off variant of the sx_in and sx_out macros are
337 now available. They don't set the interrupt enable bit.
338 These are used during initialization. Normal operation uses
339 the old variant which enables the interrupt line.
340 - RTS/DTR issue needs to be implemented according to
341 specialix' spec.
342 I kind of like the "determinism" of the current
343 implementation. Compile time flag?
344 == Ok. Compile time flag! Default is how Specialix likes it.
345 == Now a config time flag! Gets saved in your config file. Neat!
346 - Can you set the IO address from the lilo command line?
347 If you need this, bug me about it, I'll make it.
348 == Hah! No bugging needed. Fixed! :-)
349 - Cirrus logic hasn't gotten back to me yet why the CD1865 can
350 and the CD1864 can't do 115k2. I suspect that this is
351 because the CD1864 is not rated for 33MHz operation.
352 Therefore the CD1864 versions of the card can't do 115k2 on
353 all ports just like the CD1865 versions. The driver does
354 not block 115k2 on CD1864 cards.
355 == I called the Cirrus Logic representative here in Holland.
356 The CD1864 databook is identical to the CD1865 databook,
357 except for an extra warning at the end. Similar Bit errors
358 have been observed in testing at 115k2 on both an 1865 and
359 a 1864 chip. I see no reason why I would prohibit 115k2 on
360 1864 chips and not do it on 1865 chips. Actually there is
361 reason to prohibit it on BOTH chips. I print a warning.
362 If you use 115k2, you're on your own.
363 - A spiky CD may send spurious HUPs. Also in CLOCAL???
364 -- A fix for this turned out to be counter productive.
365 Different fix? Current behaviour is acceptable?
366 -- Maybe the current implementation is correct. If anybody
367 gets bitten by this, please report, and it will get fixed.
368
369 -- Testing revealed that when in CLOCAL, the problem doesn't
370 occur. As warned for in the CD1865 manual, the chip may
371 send modem intr's on a spike. We could filter those out,
372 but that would be a cludge anyway (You'd still risk getting
373 a spurious HUP when two spikes occur.).....
374
375
376
377 Bugs & restrictions:
378 - This is a difficult card to autoprobe.
379 You have to WRITE to the address register to even
380 read-probe a CD186x register. Disable autodetection?
381 -- Specialix: any suggestions?
382
383
diff --git a/Documentation/serial/sx.txt b/Documentation/serial/sx.txt
deleted file mode 100644
index cb4efa0fb5cc..000000000000
--- a/Documentation/serial/sx.txt
+++ /dev/null
@@ -1,294 +0,0 @@
1
2 sx.txt -- specialix SX/SI multiport serial driver readme.
3
4
5
6 Copyright (C) 1997 Roger Wolff (R.E.Wolff@BitWizard.nl)
7
8 Specialix pays for the development and support of this driver.
9 Please DO contact support@specialix.co.uk if you require
10 support.
11
12 This driver was developed in the BitWizard linux device
13 driver service. If you require a linux device driver for your
14 product, please contact devices@BitWizard.nl for a quote.
15
16 (History)
17 There used to be an SI driver by Simon Allan. This is a complete
18 rewrite from scratch. Just a few lines-of-code have been snatched.
19
20 (Sources)
21 Specialix document number 6210028: SX Host Card and Download Code
22 Software Functional Specification.
23
24 (Copying)
25 This program is free software; you can redistribute it and/or
26 modify it under the terms of the GNU General Public License as
27 published by the Free Software Foundation; either version 2 of
28 the License, or (at your option) any later version.
29
30 This program is distributed in the hope that it will be
31 useful, but WITHOUT ANY WARRANTY; without even the implied
32 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
33 PURPOSE. See the GNU General Public License for more details.
34
35 You should have received a copy of the GNU General Public
36 License along with this program; if not, write to the Free
37 Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
38 USA.
39
40 (Addendum)
41 I'd appreciate it that if you have fixes, that you send them
42 to me first.
43
44
45Introduction
46============
47
48This file contains some random information, that I like to have online
49instead of in a manual that can get lost. Ever misplace your Linux
50kernel sources? And the manual of one of the boards in your computer?
51
52
53Theory of operation
54===================
55
56An important thing to know is that the driver itself doesn't have the
57firmware for the card. This means that you need the separate package
58"sx_firmware". For now you can get the source at
59
60 ftp://ftp.bitwizard.nl/specialix/sx_firmware_<version>.tgz
61
62The firmware load needs a "misc" device, so you'll need to enable the
63"Support for user misc device modules" in your kernel configuration.
64The misc device needs to be called "/dev/specialix_sxctl". It needs
65misc major 10, and minor number 167 (assigned by HPA). The section
66on creating device files below also creates this device.
67
68After loading the sx.o module into your kernel, the driver will report
69the number of cards detected, but because it doesn't have any
70firmware, it will not be able to determine the number of ports. Only
71when you then run "sx_firmware" will the firmware be downloaded and
72the rest of the driver initialized. At that time the sx_firmware
73program will report the number of ports installed.
74
75In contrast with many other multi port serial cards, some of the data
76structures are only allocated when the card knows the number of ports
77that are connected. This means we won't waste memory for 120 port
78descriptor structures when you only have 8 ports. If you experience
79problems due to this, please report them: I haven't seen any.
80
81
82Interrupts
83==========
84
85A multi port serial card, would generate a horrendous amount of
86interrupts if it would interrupt the CPU for every received
87character. Even more than 10 years ago, the trick not to use
88interrupts but to poll the serial cards was invented.
89
90The SX card allow us to do this two ways. First the card limits its
91own interrupt rate to a rate that won't overwhelm the CPU. Secondly,
92we could forget about the cards interrupt completely and use the
93internal timer for this purpose.
94
95Polling the card can take up to a few percent of your CPU. Using the
96interrupts would be better if you have most of the ports idle. Using
97timer-based polling is better if your card almost always has work to
98do. You save the separate interrupt in that case.
99
100In any case, it doesn't really matter all that much.
101
102The most common problem with interrupts is that for ISA cards in a PCI
103system the BIOS has to be told to configure that interrupt as "legacy
104ISA". Otherwise the card can pull on the interrupt line all it wants
105but the CPU won't see this.
106
107If you can't get the interrupt to work, remember that polling mode is
108more efficient (provided you actually use the card intensively).
109
110
111Allowed Configurations
112======================
113
114Some configurations are disallowed. Even though at a glance they might
115seem to work, they are known to lockup the bus between the host card
116and the device concentrators. You should respect the drivers decision
117not to support certain configurations. It's there for a reason.
118
119Warning: Seriously technical stuff ahead. Executive summary: Don't use
120SX cards except configured at a 64k boundary. Skip the next paragraph.
121
122The SX cards can theoretically be placed at a 32k boundary. So for
123instance you can put an SX card at 0xc8000-0xd7fff. This is not a
124"recommended configuration". ISA cards have to tell the bus controller
125how they like their timing. Due to timing issues they have to do this
126based on which 64k window the address falls into. This means that the
12732k window below and above the SX card have to use exactly the same
128timing as the SX card. That reportedly works for other SX cards. But
129you're still left with two useless 32k windows that should not be used
130by anybody else.
131
132
133Configuring the driver
134======================
135
136PCI cards are always detected. The driver auto-probes for ISA cards at
137some sensible addresses. Please report if the auto-probe causes trouble
138in your system, or when a card isn't detected.
139
140I'm afraid I haven't implemented "kernel command line parameters" yet.
141This means that if the default doesn't work for you, you shouldn't use
142the compiled-into-the-kernel version of the driver. Use a module
143instead. If you convince me that you need this, I'll make it for
144you. Deal?
145
146I'm afraid that the module parameters are a bit clumsy. If you have a
147better idea, please tell me.
148
149You can specify several parameters:
150
151 sx_poll: number of jiffies between timer-based polls.
152
153 Set this to "0" to disable timer based polls.
154 Initialization of cards without a working interrupt
155 will fail.
156
157 Set this to "1" if you want a polling driver.
158 (on Intel: 100 polls per second). If you don't use
159 fast baud rates, you might consider a value like "5".
160 (If you don't know how to do the math, use 1).
161
162 sx_slowpoll: Number of jiffies between timer-based polls.
163 Set this to "100" to poll once a second.
164 This should get the card out of a stall if the driver
165 ever misses an interrupt. I've never seen this happen,
166 and if it does, that's a bug. Tell me.
167
168 sx_maxints: Number of interrupts to request from the card.
169 The card normally limits interrupts to about 100 per
170 second to offload the host CPU. You can increase this
171 number to reduce latency on the card a little.
172 Note that if you give a very high number you can overload
173 your CPU as well as the CPU on the host card. This setting
174 is inaccurate and not recommended for SI cards (But it
175 works).
176
177 sx_irqmask: The mask of allowable IRQs to use. I suggest you set
178 this to 0 (disable IRQs all together) and use polling if
179 the assignment of IRQs becomes problematic. This is defined
180 as the sum of (1 << irq) 's that you want to allow. So
181 sx_irqmask of 8 (1 << 3) specifies that only irq 3 may
182 be used by the SX driver. If you want to specify to the
183 driver: "Either irq 11 or 12 is ok for you to use", then
184 specify (1 << 11) | (1 << 12) = 0x1800 .
185
186 sx_debug: You can enable different sorts of debug traces with this.
187 At "-1" all debugging traces are active. You'll get several
188 times more debugging output than you'll get characters
189 transmitted.
190
191
192Baud rates
193==========
194
195Theoretically new SXDCs should be capable of more than 460k
196baud. However the line drivers usually give up before that. Also the
197CPU on the card may not be able to handle 8 channels going at full
198blast at that speed. Moreover, the buffers are not large enough to
199allow operation with 100 interrupts per second. You'll have to realize
200that the card has a 256 byte buffer, so you'll have to increase the
201number of interrupts per second if you have more than 256*100 bytes
202per second to transmit. If you do any performance testing in this
203area, I'd be glad to hear from you...
204
205(Psst Linux users..... I think the Linux driver is more efficient than
206the driver for other OSes. If you can and want to benchmark them
207against each other, be my guest, and report your findings...... :-)
208
209
210Ports and devices
211=================
212
213Port 0 is the top connector on the module closest to the host
214card. Oh, the ports on the SXDCs and TAs are labelled from 1 to 8
215instead of from 0 to 7, as they are numbered by linux. I'm stubborn in
216this: I know for sure that I wouldn't be able to calculate which port
217is which anymore if I would change that....
218
219
220Devices:
221
222You should make the device files as follows:
223
224#!/bin/sh
225# (I recommend that you cut-and-paste this into a file and run that)
226cd /dev
227t=0
228mknod specialix_sxctl c 10 167
229while [ $t -lt 64 ]
230 do
231 echo -n "$t "
232 mknod ttyX$t c 32 $t
233 mknod cux$t c 33 $t
234 t=`expr $t + 1`
235done
236echo ""
237rm /etc/psdevtab
238ps > /dev/null
239
240
241This creates 64 devices. If you have more, increase the constant on
242the line with "while". The devices start at 0, as is customary on
243Linux. Specialix seems to like starting the numbering at 1.
244
245If your system doesn't come with these devices pre-installed, bug your
246linux-vendor about this. They should have these devices
247"pre-installed" before the new millennium. The "ps" stuff at the end
248is to "tell" ps that the new devices exist.
249
250Officially the maximum number of cards per computer is 4. This driver
251however supports as many cards in one machine as you want. You'll run
252out of interrupts after a few, but you can switch to polled operation
253then. At about 256 ports (More than 8 cards), we run out of minor
254device numbers. Sorry. I suggest you buy a second computer.... (Or
255switch to RIO).
256
257------------------------------------------------------------------------
258
259
260 Fixed bugs and restrictions:
261 - Hangup processing.
262 -- Done.
263
264 - the write path in generic_serial (lockup / oops).
265 -- Done (Ugly: not the way I want it. Copied from serial.c).
266
267 - write buffer isn't flushed at close.
268 -- Done. I still seem to lose a few chars at close.
269 Sorry. I think that this is a firmware issue. (-> Specialix)
270
271 - drain hardware before changing termios
272 - Change debug on the fly.
273 - ISA free irq -1. (no firmware loaded).
274 - adding c8000 as a probe address. Added warning.
275 - Add a RAMtest for the RAM on the card.c
276 - Crash when opening a port "way" of the number of allowed ports.
277 (for example opening port 60 when there are only 24 ports attached)
278 - Sometimes the use-count strays a bit. After a few hours of
279 testing the use count is sometimes "3". If you are not like
280 me and can remember what you did to get it that way, I'd
281 appreciate an Email. Possibly fixed. Tell me if anyone still
282 sees this.
283 - TAs don't work right if you don't connect all the modem control
284 signals. SXDCs do. T225 firmware problem -> Specialix.
285 (Mostly fixed now, I think. Tell me if you encounter this!)
286
287 Bugs & restrictions:
288
289 - Arbitrary baud rates. Requires firmware update. (-> Specialix)
290
291 - Low latency (mostly firmware, -> Specialix)
292
293
294
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-27 22:21:35 -0500