About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / sx.txt


Based on kernel version 2.6.27. Page generated on 2008-10-13 09:54 EST.

1	
2	      sx.txt  -- specialix SX/SI multiport serial driver readme.
3	
4	
5	
6	      Copyright (C) 1997  Roger Wolff (R.E.Wolff[AT]BitWizard[DOT]nl)
7	
8	      Specialix pays for the development and support of this driver.
9	      Please DO contact support[AT]specialix.co[DOT]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[AT]BitWizard.nl for a quote[DOT]
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	
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog