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 loose 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 295