The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/Documentation/sx.txt

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    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 

Cache object: bb26e5fc6a5752eb2e8e03abb539093c


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.