annotate Documentation/sx.txt @ 854:950b9eb27661

usbback: fix urb interval value for interrupt urbs.

Signed-off-by: Noboru Iwamatsu <n_iwamatsu@jp.fujitsu.com>
author Keir Fraser <keir.fraser@citrix.com>
date Mon Apr 06 13:51:20 2009 +0100 (2009-04-06)
parents 831230e53067
rev   line source
ian@0 1
ian@0 2 sx.txt -- specialix SX/SI 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 support@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 (History)
ian@0 17 There used to be an SI driver by Simon Allan. This is a complete
ian@0 18 rewrite from scratch. Just a few lines-of-code have been snatched.
ian@0 19
ian@0 20 (Sources)
ian@0 21 Specialix document number 6210028: SX Host Card and Download Code
ian@0 22 Software Functional Specification.
ian@0 23
ian@0 24 (Copying)
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 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 (Addendum)
ian@0 41 I'd appreciate it that if you have fixes, that you send them
ian@0 42 to me first.
ian@0 43
ian@0 44
ian@0 45 Introduction
ian@0 46 ============
ian@0 47
ian@0 48 This file contains some random information, that I like to have online
ian@0 49 instead of in a manual that can get lost. Ever misplace your Linux
ian@0 50 kernel sources? And the manual of one of the boards in your computer?
ian@0 51
ian@0 52
ian@0 53 Theory of operation
ian@0 54 ===================
ian@0 55
ian@0 56 An important thing to know is that the driver itself doesn't have the
ian@0 57 firmware for the card. This means that you need the separate package
ian@0 58 "sx_firmware". For now you can get the source at
ian@0 59
ian@0 60 ftp://ftp.bitwizard.nl/specialix/sx_firmware_<version>.tgz
ian@0 61
ian@0 62 The firmware load needs a "misc" device, so you'll need to enable the
ian@0 63 "Support for user misc device modules" in your kernel configuration.
ian@0 64 The misc device needs to be called "/dev/specialix_sxctl". It needs
ian@0 65 misc major 10, and minor number 167 (assigned by HPA). The section
ian@0 66 on creating device files below also creates this device.
ian@0 67
ian@0 68 After loading the sx.o module into your kernel, the driver will report
ian@0 69 the number of cards detected, but because it doesn't have any
ian@0 70 firmware, it will not be able to determine the number of ports. Only
ian@0 71 when you then run "sx_firmware" will the firmware be downloaded and
ian@0 72 the rest of the driver initialized. At that time the sx_firmware
ian@0 73 program will report the number of ports installed.
ian@0 74
ian@0 75 In contrast with many other multi port serial cards, some of the data
ian@0 76 structures are only allocated when the card knows the number of ports
ian@0 77 that are connected. This means we won't waste memory for 120 port
ian@0 78 descriptor structures when you only have 8 ports. If you experience
ian@0 79 problems due to this, please report them: I haven't seen any.
ian@0 80
ian@0 81
ian@0 82 Interrupts
ian@0 83 ==========
ian@0 84
ian@0 85 A multi port serial card, would generate a horrendous amount of
ian@0 86 interrupts if it would interrupt the CPU for every received
ian@0 87 character. Even more than 10 years ago, the trick not to use
ian@0 88 interrupts but to poll the serial cards was invented.
ian@0 89
ian@0 90 The SX card allow us to do this two ways. First the card limits its
ian@0 91 own interrupt rate to a rate that won't overwhelm the CPU. Secondly,
ian@0 92 we could forget about the cards interrupt completely and use the
ian@0 93 internal timer for this purpose.
ian@0 94
ian@0 95 Polling the card can take up to a few percent of your CPU. Using the
ian@0 96 interrupts would be better if you have most of the ports idle. Using
ian@0 97 timer-based polling is better if your card almost always has work to
ian@0 98 do. You save the separate interrupt in that case.
ian@0 99
ian@0 100 In any case, it doesn't really matter all that much.
ian@0 101
ian@0 102 The most common problem with interrupts is that for ISA cards in a PCI
ian@0 103 system the BIOS has to be told to configure that interrupt as "legacy
ian@0 104 ISA". Otherwise the card can pull on the interrupt line all it wants
ian@0 105 but the CPU won't see this.
ian@0 106
ian@0 107 If you can't get the interrupt to work, remember that polling mode is
ian@0 108 more efficient (provided you actually use the card intensively).
ian@0 109
ian@0 110
ian@0 111 Allowed Configurations
ian@0 112 ======================
ian@0 113
ian@0 114 Some configurations are disallowed. Even though at a glance they might
ian@0 115 seem to work, they are known to lockup the bus between the host card
ian@0 116 and the device concentrators. You should respect the drivers decision
ian@0 117 not to support certain configurations. It's there for a reason.
ian@0 118
ian@0 119 Warning: Seriously technical stuff ahead. Executive summary: Don't use
ian@0 120 SX cards except configured at a 64k boundary. Skip the next paragraph.
ian@0 121
ian@0 122 The SX cards can theoretically be placed at a 32k boundary. So for
ian@0 123 instance you can put an SX card at 0xc8000-0xd7fff. This is not a
ian@0 124 "recommended configuration". ISA cards have to tell the bus controller
ian@0 125 how they like their timing. Due to timing issues they have to do this
ian@0 126 based on which 64k window the address falls into. This means that the
ian@0 127 32k window below and above the SX card have to use exactly the same
ian@0 128 timing as the SX card. That reportedly works for other SX cards. But
ian@0 129 you're still left with two useless 32k windows that should not be used
ian@0 130 by anybody else.
ian@0 131
ian@0 132
ian@0 133 Configuring the driver
ian@0 134 ======================
ian@0 135
ian@0 136 PCI cards are always detected. The driver auto-probes for ISA cards at
ian@0 137 some sensible addresses. Please report if the auto-probe causes trouble
ian@0 138 in your system, or when a card isn't detected.
ian@0 139
ian@0 140 I'm afraid I haven't implemented "kernel command line parameters" yet.
ian@0 141 This means that if the default doesn't work for you, you shouldn't use
ian@0 142 the compiled-into-the-kernel version of the driver. Use a module
ian@0 143 instead. If you convince me that you need this, I'll make it for
ian@0 144 you. Deal?
ian@0 145
ian@0 146 I'm afraid that the module parameters are a bit clumsy. If you have a
ian@0 147 better idea, please tell me.
ian@0 148
ian@0 149 You can specify several parameters:
ian@0 150
ian@0 151 sx_poll: number of jiffies between timer-based polls.
ian@0 152
ian@0 153 Set this to "0" to disable timer based polls.
ian@0 154 Initialization of cards without a working interrupt
ian@0 155 will fail.
ian@0 156
ian@0 157 Set this to "1" if you want a polling driver.
ian@0 158 (on Intel: 100 polls per second). If you don't use
ian@0 159 fast baud rates, you might consider a value like "5".
ian@0 160 (If you don't know how to do the math, use 1).
ian@0 161
ian@0 162 sx_slowpoll: Number of jiffies between timer-based polls.
ian@0 163 Set this to "100" to poll once a second.
ian@0 164 This should get the card out of a stall if the driver
ian@0 165 ever misses an interrupt. I've never seen this happen,
ian@0 166 and if it does, that's a bug. Tell me.
ian@0 167
ian@0 168 sx_maxints: Number of interrupts to request from the card.
ian@0 169 The card normally limits interrupts to about 100 per
ian@0 170 second to offload the host CPU. You can increase this
ian@0 171 number to reduce latency on the card a little.
ian@0 172 Note that if you give a very high number you can overload
ian@0 173 your CPU as well as the CPU on the host card. This setting
ian@0 174 is inaccurate and not recommended for SI cards (But it
ian@0 175 works).
ian@0 176
ian@0 177 sx_irqmask: The mask of allowable IRQs to use. I suggest you set
ian@0 178 this to 0 (disable IRQs all together) and use polling if
ian@0 179 the assignment of IRQs becomes problematic. This is defined
ian@0 180 as the sum of (1 << irq) 's that you want to allow. So
ian@0 181 sx_irqmask of 8 (1 << 3) specifies that only irq 3 may
ian@0 182 be used by the SX driver. If you want to specify to the
ian@0 183 driver: "Either irq 11 or 12 is ok for you to use", then
ian@0 184 specify (1 << 11) | (1 << 12) = 0x1800 .
ian@0 185
ian@0 186 sx_debug: You can enable different sorts of debug traces with this.
ian@0 187 At "-1" all debugging traces are active. You'll get several
ian@0 188 times more debugging output than you'll get characters
ian@0 189 transmitted.
ian@0 190
ian@0 191
ian@0 192 Baud rates
ian@0 193 ==========
ian@0 194
ian@0 195 Theoretically new SXDCs should be capable of more than 460k
ian@0 196 baud. However the line drivers usually give up before that. Also the
ian@0 197 CPU on the card may not be able to handle 8 channels going at full
ian@0 198 blast at that speed. Moreover, the buffers are not large enough to
ian@0 199 allow operation with 100 interrupts per second. You'll have to realize
ian@0 200 that the card has a 256 byte buffer, so you'll have to increase the
ian@0 201 number of interrupts per second if you have more than 256*100 bytes
ian@0 202 per second to transmit. If you do any performance testing in this
ian@0 203 area, I'd be glad to hear from you...
ian@0 204
ian@0 205 (Psst Linux users..... I think the Linux driver is more efficient than
ian@0 206 the driver for other OSes. If you can and want to benchmark them
ian@0 207 against each other, be my guest, and report your findings...... :-)
ian@0 208
ian@0 209
ian@0 210 Ports and devices
ian@0 211 =================
ian@0 212
ian@0 213 Port 0 is the top connector on the module closest to the host
ian@0 214 card. Oh, the ports on the SXDCs and TAs are labelled from 1 to 8
ian@0 215 instead of from 0 to 7, as they are numbered by linux. I'm stubborn in
ian@0 216 this: I know for sure that I wouldn't be able to calculate which port
ian@0 217 is which anymore if I would change that....
ian@0 218
ian@0 219
ian@0 220 Devices:
ian@0 221
ian@0 222 You should make the device files as follows:
ian@0 223
ian@0 224 #!/bin/sh
ian@0 225 # (I recommend that you cut-and-paste this into a file and run that)
ian@0 226 cd /dev
ian@0 227 t=0
ian@0 228 mknod specialix_sxctl c 10 167
ian@0 229 while [ $t -lt 64 ]
ian@0 230 do
ian@0 231 echo -n "$t "
ian@0 232 mknod ttyX$t c 32 $t
ian@0 233 mknod cux$t c 33 $t
ian@0 234 t=`expr $t + 1`
ian@0 235 done
ian@0 236 echo ""
ian@0 237 rm /etc/psdevtab
ian@0 238 ps > /dev/null
ian@0 239
ian@0 240
ian@0 241 This creates 64 devices. If you have more, increase the constant on
ian@0 242 the line with "while". The devices start at 0, as is customary on
ian@0 243 Linux. Specialix seems to like starting the numbering at 1.
ian@0 244
ian@0 245 If your system doesn't come with these devices pre-installed, bug your
ian@0 246 linux-vendor about this. They should have these devices
ian@0 247 "pre-installed" before the new millennium. The "ps" stuff at the end
ian@0 248 is to "tell" ps that the new devices exist.
ian@0 249
ian@0 250 Officially the maximum number of cards per computer is 4. This driver
ian@0 251 however supports as many cards in one machine as you want. You'll run
ian@0 252 out of interrupts after a few, but you can switch to polled operation
ian@0 253 then. At about 256 ports (More than 8 cards), we run out of minor
ian@0 254 device numbers. Sorry. I suggest you buy a second computer.... (Or
ian@0 255 switch to RIO).
ian@0 256
ian@0 257 ------------------------------------------------------------------------
ian@0 258
ian@0 259
ian@0 260 Fixed bugs and restrictions:
ian@0 261 - Hangup processing.
ian@0 262 -- Done.
ian@0 263
ian@0 264 - the write path in generic_serial (lockup / oops).
ian@0 265 -- Done (Ugly: not the way I want it. Copied from serial.c).
ian@0 266
ian@0 267 - write buffer isn't flushed at close.
ian@0 268 -- Done. I still seem to lose a few chars at close.
ian@0 269 Sorry. I think that this is a firmware issue. (-> Specialix)
ian@0 270
ian@0 271 - drain hardware before changing termios
ian@0 272 - Change debug on the fly.
ian@0 273 - ISA free irq -1. (no firmware loaded).
ian@0 274 - adding c8000 as a probe address. Added warning.
ian@0 275 - Add a RAMtest for the RAM on the card.c
ian@0 276 - Crash when opening a port "way" of the number of allowed ports.
ian@0 277 (for example opening port 60 when there are only 24 ports attached)
ian@0 278 - Sometimes the use-count strays a bit. After a few hours of
ian@0 279 testing the use count is sometimes "3". If you are not like
ian@0 280 me and can remember what you did to get it that way, I'd
ian@0 281 appreciate an Email. Possibly fixed. Tell me if anyone still
ian@0 282 sees this.
ian@0 283 - TAs don't work right if you don't connect all the modem control
ian@0 284 signals. SXDCs do. T225 firmware problem -> Specialix.
ian@0 285 (Mostly fixed now, I think. Tell me if you encounter this!)
ian@0 286
ian@0 287 Bugs & restrictions:
ian@0 288
ian@0 289 - Arbitrary baud rates. Requires firmware update. (-> Specialix)
ian@0 290
ian@0 291 - Low latency (mostly firmware, -> Specialix)
ian@0 292
ian@0 293
ian@0 294