ia64/linux-2.6.18-xen.hg

annotate Documentation/specialix.txt @ 0:831230e53067

Import 2.6.18 from kernel.org tarball.
author Ian Campbell <ian.campbell@xensource.com>
date Wed Apr 11 14:15:44 2007 +0100 (2007-04-11)
parents
children
rev   line source
ian@0 1
ian@0 2 specialix.txt -- specialix IO8+ multiport serial driver readme.
ian@0 3
ian@0 4
ian@0 5
ian@0 6 Copyright (C) 1997 Roger Wolff (R.E.Wolff@BitWizard.nl)
ian@0 7
ian@0 8 Specialix pays for the development and support of this driver.
ian@0 9 Please DO contact io8-linux@specialix.co.uk if you require
ian@0 10 support.
ian@0 11
ian@0 12 This driver was developed in the BitWizard linux device
ian@0 13 driver service. If you require a linux device driver for your
ian@0 14 product, please contact devices@BitWizard.nl for a quote.
ian@0 15
ian@0 16 This code is firmly based on the riscom/8 serial driver,
ian@0 17 written by Dmitry Gorodchanin. The specialix IO8+ card
ian@0 18 programming information was obtained from the CL-CD1865 Data
ian@0 19 Book, and Specialix document number 6200059: IO8+ Hardware
ian@0 20 Functional Specification, augmented by document number 6200088:
ian@0 21 Merak Hardware Functional Specification. (IO8+/PCI is also
ian@0 22 called Merak)
ian@0 23
ian@0 24
ian@0 25 This program is free software; you can redistribute it and/or
ian@0 26 modify it under the terms of the GNU General Public License as
ian@0 27 published by the Free Software Foundation; either version 2 of
ian@0 28 the License, or (at your option) any later version.
ian@0 29
ian@0 30 This program is distributed in the hope that it will be
ian@0 31 useful, but WITHOUT ANY WARRANTY; without even the implied
ian@0 32 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
ian@0 33 PURPOSE. See the GNU General Public License for more details.
ian@0 34
ian@0 35 You should have received a copy of the GNU General Public
ian@0 36 License along with this program; if not, write to the Free
ian@0 37 Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
ian@0 38 USA.
ian@0 39
ian@0 40
ian@0 41 Intro
ian@0 42 =====
ian@0 43
ian@0 44
ian@0 45 This file contains some random information, that I like to have online
ian@0 46 instead of in a manual that can get lost. Ever misplace your Linux
ian@0 47 kernel sources? And the manual of one of the boards in your computer?
ian@0 48
ian@0 49
ian@0 50 Addresses and interrupts
ian@0 51 ========================
ian@0 52
ian@0 53 Address dip switch settings:
ian@0 54 The dip switch sets bits 2-9 of the IO address.
ian@0 55
ian@0 56 9 8 7 6 5 4 3 2
ian@0 57 +-----------------+
ian@0 58 0 | X X X X X X X |
ian@0 59 | | = IoBase = 0x100
ian@0 60 1 | X |
ian@0 61 +-----------------+ ------ RS232 connectors ---->
ian@0 62
ian@0 63 | | |
ian@0 64 edge connector
ian@0 65 | | |
ian@0 66 V V V
ian@0 67
ian@0 68 Base address 0x100 caused a conflict in one of my computers once. I
ian@0 69 haven't the foggiest why. My Specialix card is now at 0x180. My
ian@0 70 other computer runs just fine with the Specialix card at 0x100....
ian@0 71 The card occupies 4 addresses, but actually only two are really used.
ian@0 72
ian@0 73 The PCI version doesn't have any dip switches. The BIOS assigns
ian@0 74 an IO address.
ian@0 75
ian@0 76 The driver now still autoprobes at 0x100, 0x180, 0x250 and 0x260. If
ian@0 77 that causes trouble for you, please report that. I'll remove
ian@0 78 autoprobing then.
ian@0 79
ian@0 80 The driver will tell the card what IRQ to use, so you don't have to
ian@0 81 change any jumpers to change the IRQ. Just use a command line
ian@0 82 argument (irq=xx) to the insmod program to set the interrupt.
ian@0 83
ian@0 84 The BIOS assigns the IRQ on the PCI version. You have no say in what
ian@0 85 IRQ to use in that case.
ian@0 86
ian@0 87 If your specialix cards are not at the default locations, you can use
ian@0 88 the kernel command line argument "specialix=io0,irq0,io1,irq1...".
ian@0 89 Here "io0" is the io address for the first card, and "irq0" is the
ian@0 90 irq line that the first card should use. And so on.
ian@0 91
ian@0 92 Examples.
ian@0 93
ian@0 94 You use the driver as a module and have three cards at 0x100, 0x250
ian@0 95 and 0x180. And some way or another you want them detected in that
ian@0 96 order. Moreover irq 12 is taken (e.g. by your PS/2 mouse).
ian@0 97
ian@0 98 insmod specialix.o iobase=0x100,0x250,0x180 irq=9,11,15
ian@0 99
ian@0 100 The same three cards, but now in the kernel would require you to
ian@0 101 add
ian@0 102
ian@0 103 specialix=0x100,9,0x250,11,0x180,15
ian@0 104
ian@0 105 to the command line. This would become
ian@0 106
ian@0 107 append="specialix=0x100,9,0x250,11,0x180,15"
ian@0 108
ian@0 109 in your /etc/lilo.conf file if you use lilo.
ian@0 110
ian@0 111 The Specialix driver is slightly odd: It allows you to have the second
ian@0 112 or third card detected without having a first card. This has
ian@0 113 advantages and disadvantages. A slot that isn't filled by an ISA card,
ian@0 114 might be filled if a PCI card is detected. Thus if you have an ISA
ian@0 115 card at 0x250 and a PCI card, you would get:
ian@0 116
ian@0 117 sx0: specialix IO8+ Board at 0x100 not found.
ian@0 118 sx1: specialix IO8+ Board at 0x180 not found.
ian@0 119 sx2: specialix IO8+ board detected at 0x250, IRQ 12, CD1865 Rev. B.
ian@0 120 sx3: specialix IO8+ Board at 0x260 not found.
ian@0 121 sx0: specialix IO8+ board detected at 0xd800, IRQ 9, CD1865 Rev. B.
ian@0 122
ian@0 123 This would happen if you don't give any probe hints to the driver.
ian@0 124 If you would specify:
ian@0 125
ian@0 126 specialix=0x250,11
ian@0 127
ian@0 128 you'd get the following messages:
ian@0 129
ian@0 130 sx0: specialix IO8+ board detected at 0x250, IRQ 11, CD1865 Rev. B.
ian@0 131 sx1: specialix IO8+ board detected at 0xd800, IRQ 9, CD1865 Rev. B.
ian@0 132
ian@0 133 ISA probing is aborted after the IO address you gave is exhausted, and
ian@0 134 the PCI card is now detected as the second card. The ISA card is now
ian@0 135 also forced to IRQ11....
ian@0 136
ian@0 137
ian@0 138 Baud rates
ian@0 139 ==========
ian@0 140
ian@0 141 The rev 1.2 and below boards use a CL-CD1864. These chips can only
ian@0 142 do 64kbit. The rev 1.3 and newer boards use a CL-CD1865. These chips
ian@0 143 are officially capable of 115k2.
ian@0 144
ian@0 145 The Specialix card uses a 25MHz crystal (in times two mode, which in
ian@0 146 fact is a divided by two mode). This is not enough to reach the rated
ian@0 147 115k2 on all ports at the same time. With this clock rate you can only
ian@0 148 do 37% of this rate. This means that at 115k2 on all ports you are
ian@0 149 going to lose characters (The chip cannot handle that many incoming
ian@0 150 bits at this clock rate.) (Yes, you read that correctly: there is a
ian@0 151 limit to the number of -=bits=- per second that the chip can handle.)
ian@0 152
ian@0 153 If you near the "limit" you will first start to see a graceful
ian@0 154 degradation in that the chip cannot keep the transmitter busy at all
ian@0 155 times. However with a central clock this slow, you can also get it to
ian@0 156 miss incoming characters. The driver will print a warning message when
ian@0 157 you are outside the official specs. The messages usually show up in
ian@0 158 the file /var/log/messages .
ian@0 159
ian@0 160 The specialix card cannot reliably do 115k2. If you use it, you have
ian@0 161 to do "extensive testing" (*) to verify if it actually works.
ian@0 162
ian@0 163 When "mgetty" communicates with my modem at 115k2 it reports:
ian@0 164 got: +++[0d]ATQ0V1H0[0d][0d][8a]O[cb][0d][8a]
ian@0 165 ^^^^ ^^^^ ^^^^
ian@0 166
ian@0 167 The three characters that have the "^^^" under them have suffered a
ian@0 168 bit error in the highest bit. In conclusion: I've tested it, and found
ian@0 169 that it simply DOESN'T work for me. I also suspect that this is also
ian@0 170 caused by the baud rate being just a little bit out of tune.
ian@0 171
ian@0 172 I upgraded the crystal to 66Mhz on one of my Specialix cards. Works
ian@0 173 great! Contact me for details. (Voids warranty, requires a steady hand
ian@0 174 and more such restrictions....)
ian@0 175
ian@0 176
ian@0 177 (*) Cirrus logic CD1864 databook, page 40.
ian@0 178
ian@0 179
ian@0 180 Cables for the Specialix IO8+
ian@0 181 =============================
ian@0 182
ian@0 183 The pinout of the connectors on the IO8+ is:
ian@0 184
ian@0 185 pin short direction long name
ian@0 186 name
ian@0 187 Pin 1 DCD input Data Carrier Detect
ian@0 188 Pin 2 RXD input Receive
ian@0 189 Pin 3 DTR/RTS output Data Terminal Ready/Ready To Send
ian@0 190 Pin 4 GND - Ground
ian@0 191 Pin 5 TXD output Transmit
ian@0 192 Pin 6 CTS input Clear To Send
ian@0 193
ian@0 194
ian@0 195 -- 6 5 4 3 2 1 --
ian@0 196 | |
ian@0 197 | |
ian@0 198 | |
ian@0 199 | |
ian@0 200 +----- -----+
ian@0 201 |__________|
ian@0 202 clip
ian@0 203
ian@0 204 Front view of an RJ12 connector. Cable moves "into" the paper.
ian@0 205 (the plug is ready to plug into your mouth this way...)
ian@0 206
ian@0 207
ian@0 208 NULL cable. I don't know who is going to use these except for
ian@0 209 testing purposes, but I tested the cards with this cable. (It
ian@0 210 took quite a while to figure out, so I'm not going to delete
ian@0 211 it. So there! :-)
ian@0 212
ian@0 213
ian@0 214 This end goes This end needs
ian@0 215 straight into the some twists in
ian@0 216 RJ12 plug. the wiring.
ian@0 217 IO8+ RJ12 IO8+ RJ12
ian@0 218 1 DCD white -
ian@0 219 - - 1 DCD
ian@0 220 2 RXD black 5 TXD
ian@0 221 3 DTR/RTS red 6 CTS
ian@0 222 4 GND green 4 GND
ian@0 223 5 TXD yellow 2 RXD
ian@0 224 6 CTS blue 3 DTR/RTS
ian@0 225
ian@0 226
ian@0 227 Same NULL cable, but now sorted on the second column.
ian@0 228
ian@0 229 1 DCD white -
ian@0 230 - - 1 DCD
ian@0 231 5 TXD yellow 2 RXD
ian@0 232 6 CTS blue 3 DTR/RTS
ian@0 233 4 GND green 4 GND
ian@0 234 2 RXD black 5 TXD
ian@0 235 3 DTR/RTS red 6 CTS
ian@0 236
ian@0 237
ian@0 238
ian@0 239 This is a modem cable usable for hardware handshaking:
ian@0 240 RJ12 DB25 DB9
ian@0 241 1 DCD white 8 DCD 1 DCD
ian@0 242 2 RXD black 3 RXD 2 RXD
ian@0 243 3 DTR/RTS red 4 RTS 7 RTS
ian@0 244 4 GND green 7 GND 5 GND
ian@0 245 5 TXD yellow 2 TXD 3 TXD
ian@0 246 6 CTS blue 5 CTS 8 CTS
ian@0 247 +---- 6 DSR 6 DSR
ian@0 248 +---- 20 DTR 4 DTR
ian@0 249
ian@0 250 This is a modem cable usable for software handshaking:
ian@0 251 It allows you to reset the modem using the DTR ioctls.
ian@0 252 I (REW) have never tested this, "but xxxxxxxxxxxxx
ian@0 253 says that it works." If you test this, please
ian@0 254 tell me and I'll fill in your name on the xxx's.
ian@0 255
ian@0 256 RJ12 DB25 DB9
ian@0 257 1 DCD white 8 DCD 1 DCD
ian@0 258 2 RXD black 3 RXD 2 RXD
ian@0 259 3 DTR/RTS red 20 DTR 4 DTR
ian@0 260 4 GND green 7 GND 5 GND
ian@0 261 5 TXD yellow 2 TXD 3 TXD
ian@0 262 6 CTS blue 5 CTS 8 CTS
ian@0 263 +---- 6 DSR 6 DSR
ian@0 264 +---- 4 RTS 7 RTS
ian@0 265
ian@0 266 I bought a 6 wire flat cable. It was colored as indicated.
ian@0 267 Check that yours is the same before you trust me on this.
ian@0 268
ian@0 269
ian@0 270 Hardware handshaking issues.
ian@0 271 ============================
ian@0 272
ian@0 273 The driver can be compiled in two different ways. The default
ian@0 274 ("Specialix DTR/RTS pin is RTS" is off) the pin behaves as DTR when
ian@0 275 hardware handshaking is off. It behaves as the RTS hardware
ian@0 276 handshaking signal when hardware handshaking is selected.
ian@0 277
ian@0 278 When you use this, you have to use the appropriate cable. The
ian@0 279 cable will either be compatible with hardware handshaking or with
ian@0 280 software handshaking. So switching on the fly is not really an
ian@0 281 option.
ian@0 282
ian@0 283 I actually prefer to use the "Specialix DTR/RTS pin is RTS" option.
ian@0 284 This makes the DTR/RTS pin always an RTS pin, and ioctls to
ian@0 285 change DTR are always ignored. I have a cable that is configured
ian@0 286 for this.
ian@0 287
ian@0 288
ian@0 289 Ports and devices
ian@0 290 =================
ian@0 291
ian@0 292 Port 0 is the one furthest from the card-edge connector.
ian@0 293
ian@0 294 Devices:
ian@0 295
ian@0 296 You should make the devices as follows:
ian@0 297
ian@0 298 bash
ian@0 299 cd /dev
ian@0 300 for i in 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 \
ian@0 301 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
ian@0 302 do
ian@0 303 echo -n "$i "
ian@0 304 mknod /dev/ttyW$i c 75 $i
ian@0 305 mknod /dev/cuw$i c 76 $i
ian@0 306 done
ian@0 307 echo ""
ian@0 308
ian@0 309 If your system doesn't come with these devices preinstalled, bug your
ian@0 310 linux-vendor about this. They have had ample time to get this
ian@0 311 implemented by now.
ian@0 312
ian@0 313 You cannot have more than 4 boards in one computer. The card only
ian@0 314 supports 4 different interrupts. If you really want this, contact me
ian@0 315 about this and I'll give you a few tips (requires soldering iron)....
ian@0 316
ian@0 317 If you have enough PCI slots, you can probably use more than 4 PCI
ian@0 318 versions of the card though....
ian@0 319
ian@0 320 The PCI version of the card cannot adhere to the mechanical part of
ian@0 321 the PCI spec because the 8 serial connectors are simply too large. If
ian@0 322 it doesn't fit in your computer, bring back the card.
ian@0 323
ian@0 324
ian@0 325 ------------------------------------------------------------------------
ian@0 326
ian@0 327
ian@0 328 Fixed bugs and restrictions:
ian@0 329 - During initialization, interrupts are blindly turned on.
ian@0 330 Having a shadow variable would cause an extra memory
ian@0 331 access on every IO instruction.
ian@0 332 - The interrupt (on the card) should be disabled when we
ian@0 333 don't allocate the Linux end of the interrupt. This allows
ian@0 334 a different driver/card to use it while all ports are not in
ian@0 335 use..... (a la standard serial port)
ian@0 336 == An extra _off variant of the sx_in and sx_out macros are
ian@0 337 now available. They don't set the interrupt enable bit.
ian@0 338 These are used during initialization. Normal operation uses
ian@0 339 the old variant which enables the interrupt line.
ian@0 340 - RTS/DTR issue needs to be implemented according to
ian@0 341 specialix' spec.
ian@0 342 I kind of like the "determinism" of the current
ian@0 343 implementation. Compile time flag?
ian@0 344 == Ok. Compile time flag! Default is how Specialix likes it.
ian@0 345 == Now a config time flag! Gets saved in your config file. Neat!
ian@0 346 - Can you set the IO address from the lilo command line?
ian@0 347 If you need this, bug me about it, I'll make it.
ian@0 348 == Hah! No bugging needed. Fixed! :-)
ian@0 349 - Cirrus logic hasn't gotten back to me yet why the CD1865 can
ian@0 350 and the CD1864 can't do 115k2. I suspect that this is
ian@0 351 because the CD1864 is not rated for 33MHz operation.
ian@0 352 Therefore the CD1864 versions of the card can't do 115k2 on
ian@0 353 all ports just like the CD1865 versions. The driver does
ian@0 354 not block 115k2 on CD1864 cards.
ian@0 355 == I called the Cirrus Logic representative here in Holland.
ian@0 356 The CD1864 databook is identical to the CD1865 databook,
ian@0 357 except for an extra warning at the end. Similar Bit errors
ian@0 358 have been observed in testing at 115k2 on both an 1865 and
ian@0 359 a 1864 chip. I see no reason why I would prohibit 115k2 on
ian@0 360 1864 chips and not do it on 1865 chips. Actually there is
ian@0 361 reason to prohibit it on BOTH chips. I print a warning.
ian@0 362 If you use 115k2, you're on your own.
ian@0 363 - A spiky CD may send spurious HUPs. Also in CLOCAL???
ian@0 364 -- A fix for this turned out to be counter productive.
ian@0 365 Different fix? Current behaviour is acceptable?
ian@0 366 -- Maybe the current implementation is correct. If anybody
ian@0 367 gets bitten by this, please report, and it will get fixed.
ian@0 368
ian@0 369 -- Testing revealed that when in CLOCAL, the problem doesn't
ian@0 370 occur. As warned for in the CD1865 manual, the chip may
ian@0 371 send modem intr's on a spike. We could filter those out,
ian@0 372 but that would be a cludge anyway (You'd still risk getting
ian@0 373 a spurious HUP when two spikes occur.).....
ian@0 374
ian@0 375
ian@0 376
ian@0 377 Bugs & restrictions:
ian@0 378 - This is a difficult card to autoprobe.
ian@0 379 You have to WRITE to the address register to even
ian@0 380 read-probe a CD186x register. Disable autodetection?
ian@0 381 -- Specialix: any suggestions?
ian@0 382 - Arbitrary baud rates are not implemented yet.
ian@0 383 If you need this, bug me about it.
ian@0 384
ian@0 385