Contents of /alx-src/tags/kernel26-2.6.12-alx-r9/Documentation/sx.txt
Parent Directory | Revision Log
Revision 630 -
(show annotations)
(download)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 11619 byte(s)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 11619 byte(s)
Tag kernel26-2.6.12-alx-r9
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 | |
45 | Introduction |
46 | ============ |
47 | |
48 | This file contains some random information, that I like to have online |
49 | instead of in a manual that can get lost. Ever misplace your Linux |
50 | kernel sources? And the manual of one of the boards in your computer? |
51 | |
52 | |
53 | Theory of operation |
54 | =================== |
55 | |
56 | An important thing to know is that the driver itself doesn't have the |
57 | firmware 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 | |
62 | The firmware load needs a "misc" device, so you'll need to enable the |
63 | "Support for user misc device modules" in your kernel configuration. |
64 | The misc device needs to be called "/dev/specialix_sxctl". It needs |
65 | misc major 10, and minor number 167 (assigned by HPA). The section |
66 | on creating device files below also creates this device. |
67 | |
68 | After loading the sx.o module into your kernel, the driver will report |
69 | the number of cards detected, but because it doesn't have any |
70 | firmware, it will not be able to determine the number of ports. Only |
71 | when you then run "sx_firmware" will the firmware be downloaded and |
72 | the rest of the driver initialized. At that time the sx_firmware |
73 | program will report the number of ports installed. |
74 | |
75 | In contrast with many other multi port serial cards, some of the data |
76 | structures are only allocated when the card knows the number of ports |
77 | that are connected. This means we won't waste memory for 120 port |
78 | descriptor structures when you only have 8 ports. If you experience |
79 | problems due to this, please report them: I haven't seen any. |
80 | |
81 | |
82 | Interrupts |
83 | ========== |
84 | |
85 | A multi port serial card, would generate a horrendous amount of |
86 | interrupts if it would interrupt the CPU for every received |
87 | character. Even more than 10 years ago, the trick not to use |
88 | interrupts but to poll the serial cards was invented. |
89 | |
90 | The SX card allow us to do this two ways. First the card limits its |
91 | own interrupt rate to a rate that won't overwhelm the CPU. Secondly, |
92 | we could forget about the cards interrupt completely and use the |
93 | internal timer for this purpose. |
94 | |
95 | Polling the card can take up to a few percent of your CPU. Using the |
96 | interrupts would be better if you have most of the ports idle. Using |
97 | timer-based polling is better if your card almost always has work to |
98 | do. You save the separate interrupt in that case. |
99 | |
100 | In any case, it doesn't really matter all that much. |
101 | |
102 | The most common problem with interrupts is that for ISA cards in a PCI |
103 | system the BIOS has to be told to configure that interrupt as "legacy |
104 | ISA". Otherwise the card can pull on the interrupt line all it wants |
105 | but the CPU won't see this. |
106 | |
107 | If you can't get the interrupt to work, remember that polling mode is |
108 | more efficient (provided you actually use the card intensively). |
109 | |
110 | |
111 | Allowed Configurations |
112 | ====================== |
113 | |
114 | Some configurations are disallowed. Even though at a glance they might |
115 | seem to work, they are known to lockup the bus between the host card |
116 | and the device concentrators. You should respect the drivers decision |
117 | not to support certain configurations. It's there for a reason. |
118 | |
119 | Warning: Seriously technical stuff ahead. Executive summary: Don't use |
120 | SX cards except configured at a 64k boundary. Skip the next paragraph. |
121 | |
122 | The SX cards can theoretically be placed at a 32k boundary. So for |
123 | instance you can put an SX card at 0xc8000-0xd7fff. This is not a |
124 | "recommended configuration". ISA cards have to tell the bus controller |
125 | how they like their timing. Due to timing issues they have to do this |
126 | based on which 64k window the address falls into. This means that the |
127 | 32k window below and above the SX card have to use exactly the same |
128 | timing as the SX card. That reportedly works for other SX cards. But |
129 | you're still left with two useless 32k windows that should not be used |
130 | by anybody else. |
131 | |
132 | |
133 | Configuring the driver |
134 | ====================== |
135 | |
136 | PCI cards are always detected. The driver auto-probes for ISA cards at |
137 | some sensible addresses. Please report if the auto-probe causes trouble |
138 | in your system, or when a card isn't detected. |
139 | |
140 | I'm afraid I haven't implemented "kernel command line parameters" yet. |
141 | This means that if the default doesn't work for you, you shouldn't use |
142 | the compiled-into-the-kernel version of the driver. Use a module |
143 | instead. If you convince me that you need this, I'll make it for |
144 | you. Deal? |
145 | |
146 | I'm afraid that the module parameters are a bit clumsy. If you have a |
147 | better idea, please tell me. |
148 | |
149 | You 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 | |
192 | Baud rates |
193 | ========== |
194 | |
195 | Theoretically new SXDCs should be capable of more than 460k |
196 | baud. However the line drivers usually give up before that. Also the |
197 | CPU on the card may not be able to handle 8 channels going at full |
198 | blast at that speed. Moreover, the buffers are not large enough to |
199 | allow operation with 100 interrupts per second. You'll have to realize |
200 | that the card has a 256 byte buffer, so you'll have to increase the |
201 | number of interrupts per second if you have more than 256*100 bytes |
202 | per second to transmit. If you do any performance testing in this |
203 | area, I'd be glad to hear from you... |
204 | |
205 | (Psst Linux users..... I think the Linux driver is more efficient than |
206 | the driver for other OSes. If you can and want to benchmark them |
207 | against each other, be my guest, and report your findings...... :-) |
208 | |
209 | |
210 | Ports and devices |
211 | ================= |
212 | |
213 | Port 0 is the top connector on the module closest to the host |
214 | card. Oh, the ports on the SXDCs and TAs are labelled from 1 to 8 |
215 | instead of from 0 to 7, as they are numbered by linux. I'm stubborn in |
216 | this: I know for sure that I wouldn't be able to calculate which port |
217 | is which anymore if I would change that.... |
218 | |
219 | |
220 | Devices: |
221 | |
222 | You 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) |
226 | cd /dev |
227 | t=0 |
228 | mknod specialix_sxctl c 10 167 |
229 | while [ $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` |
235 | done |
236 | echo "" |
237 | rm /etc/psdevtab |
238 | ps > /dev/null |
239 | |
240 | |
241 | This creates 64 devices. If you have more, increase the constant on |
242 | the line with "while". The devices start at 0, as is customary on |
243 | Linux. Specialix seems to like starting the numbering at 1. |
244 | |
245 | If your system doesn't come with these devices pre-installed, bug your |
246 | linux-vendor about this. They should have these devices |
247 | "pre-installed" before the new millennium. The "ps" stuff at the end |
248 | is to "tell" ps that the new devices exist. |
249 | |
250 | Officially the maximum number of cards per computer is 4. This driver |
251 | however supports as many cards in one machine as you want. You'll run |
252 | out of interrupts after a few, but you can switch to polled operation |
253 | then. At about 256 ports (More than 8 cards), we run out of minor |
254 | device numbers. Sorry. I suggest you buy a second computer.... (Or |
255 | switch 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 |