sx.txt 11 KB

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