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 compiled in two different ways. The default 274("Specialix DTR/RTS pin is RTS" is off) 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 DTR/RTS pin is RTS" 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 intialization, 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 - Arbitrary baud rates are not implemented yet. 383 If you need this, bug me about it. 384 385 386