apfs/linux-apfs
0
0
Fork 0
mirror of https://github.com/linux-apfs/linux-apfs.git synced 2026-05-01 15:00:59 -07:00
Code Issues Packages Projects Releases Wiki Activity

Create/use more directory structure in the Documentation/ tree.

Browse Source 
Create Documentation/blockdev/ sub-directory and populate it.
Populate the Documentation/serial/ sub-directory.
Move MSI-HOWTO.txt to Documentation/PCI/.
Move ioctl-number.txt to Documentation/ioctl/.
Update all relevant 00-INDEX files.
Update all relevant Kconfig files and source files.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
This commit is contained in:
Randy Dunlap
2008-11-13 21:33:24 +00:00
parent 3edac25f2e
commit 31c00fc15e
30 changed files with 96 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/serial/00-INDEX
+24
View File
@@ -0,0 +1,24 @@
00-INDEX
- this file.
README.cycladesZ
- info on Cyclades-Z firmware loading.
computone.txt
- info on Computone Intelliport II/Plus Multiport Serial Driver.
digiepca.txt
- info on Digi Intl. {PC,PCI,EISA}Xx and Xem series cards.
hayes-esp.txt
- info on using the Hayes ESP serial driver.
moxa-smartio
- file with info on installing/using Moxa multiport serial driver.
riscom8.txt
- notes on using the RISCom/8 multi-port serial driver.
rocket.txt
- info on the Comtrol RocketPort multiport serial driver.
specialix.txt
- info on hardware/driver for specialix IO8+ multiport serial card.
stallion.txt
- info on using the Stallion multiport serial driver.
sx.txt
- info on the Specialix SX/SI multiport serial driver.
tty.txt
- guide to the locking policies of the tty layer.
Documentation/serial/README.cycladesZ
+8
View File
@@ -0,0 +1,8 @@
The Cyclades-Z must have firmware loaded onto the card before it will
operate. This operation should be performed during system startup,
The firmware, loader program and the latest device driver code are
available from Cyclades at
ftp://ftp.cyclades.com/pub/cyclades/cyclades-z/linux/
Documentation/serial/computone.txt
+522
View File
File diff suppressed because it is too large Load Diff
Documentation/serial/digiepca.txt
+98
View File
@@ -0,0 +1,98 @@
NOTE: This driver is obsolete. Digi provides a 2.6 driver (dgdm) at
http://www.digi.com for PCI cards. They no longer maintain this driver,
and have no 2.6 driver for ISA cards.
This driver requires a number of user-space tools. They can be acquired from
http://www.digi.com, but only works with 2.4 kernels.
The Digi Intl. epca driver.
----------------------------
The Digi Intl. epca driver for Linux supports the following boards:
Digi PC/Xem, PC/Xr, PC/Xe, PC/Xi, PC/Xeve
Digi EISA/Xem, PCI/Xem, PCI/Xr
Limitations:
------------
Currently the driver only autoprobes for supported PCI boards.
The Linux MAKEDEV command does not support generating the Digiboard
Devices. Users executing digiConfig to setup EISA and PC series cards
will have their device nodes automatically constructed (cud?? for ~CLOCAL,
and ttyD?? for CLOCAL). Users wishing to boot their board from the LILO
prompt, or those users booting PCI cards may use buildDIGI to construct
the necessary nodes.
Notes:
------
This driver may be configured via LILO. For users who have already configured
their driver using digiConfig, configuring from LILO will override previous
settings. Multiple boards may be configured by issuing multiple LILO command
lines. For examples see the bottom of this document.
Device names start at 0 and continue up. Beware of this as previous Digi
drivers started device names with 1.
PCI boards are auto-detected and configured by the driver. PCI boards will
be allocated device numbers (internally) beginning with the lowest PCI slot
first. In other words a PCI card in slot 3 will always have higher device
nodes than a PCI card in slot 1.
LILO config examples:
---------------------
Using LILO's APPEND command, a string of comma separated identifiers or
integers can be used to configure supported boards. The six values in order
are:
Enable/Disable this card or Override,
Type of card: PC/Xe (AccelePort) (0), PC/Xeve (1), PC/Xem or PC/Xr (2),
EISA/Xem (3), PC/64Xe (4), PC/Xi (5),
Enable/Disable alternate pin arrangement,
Number of ports on this card,
I/O Port where card is configured (in HEX if using string identifiers),
Base of memory window (in HEX if using string identifiers),
NOTE : PCI boards are auto-detected and configured. Do not attempt to
configure PCI boards with the LILO append command. If you wish to override
previous configuration data (As set by digiConfig), but you do not wish to
configure any specific card (Example if there are PCI cards in the system)
the following override command will accomplish this:
-> append="digi=2"
Samples:
append="digiepca=E,PC/Xe,D,16,200,D0000"
or
append="digi=1,0,0,16,512,851968"
Supporting Tools:
-----------------
Supporting tools include digiDload, digiConfig, buildPCI, and ditty. See
drivers/char/README.epca for more details. Note,
this driver REQUIRES that digiDload be executed prior to it being used.
Failure to do this will result in an ENODEV error.
Documentation:
--------------
Complete documentation for this product may be found in the tool package.
Sources of information and support:
-----------------------------------
Digi Intl. support site for this product:
-> http://www.digi.com
Acknowledgments:
----------------
Much of this work (And even text) was derived from a similar document
supporting the original public domain DigiBoard driver Copyright (C)
1994,1995 Troy De Jongh. Many thanks to Christoph Lameter
(christoph@lameter.com) and Mike McLagan (mike.mclagan@linux.org) who authored
and contributed to the original document.
Changelog:
----------
10-29-04: Update status of driver, remove dead links in document
James Nelson <james4765@gmail.com>
2000 (?) Original Document
Documentation/serial/hayes-esp.txt
+154
View File
@@ -0,0 +1,154 @@
HAYES ESP DRIVER VERSION 2.1
A big thanks to the people at Hayes, especially Alan Adamson. Their support
has enabled me to provide enhancements to the driver.
Please report your experiences with this driver to me (arobinso@nyx.net). I
am looking for both positive and negative feedback.
*** IMPORTANT CHANGES FOR 2.1 ***
Support for PIO mode. Five situations will cause PIO mode to be used:
1) A multiport card is detected. PIO mode will always be used. (8 port cards
do not support DMA).
2) The DMA channel is set to an invalid value (anything other than 1 or 3).
3) The DMA buffer/channel could not be allocated. The port will revert to PIO
mode until it is reopened.
4) Less than a specified number of bytes need to be transferred to/from the
FIFOs. PIO mode will be used for that transfer only.
5) A port needs to do a DMA transfer and another port is already using the
DMA channel. PIO mode will be used for that transfer only.
Since the Hayes ESP seems to conflict with other cards (notably sound cards)
when using DMA, DMA is turned off by default. To use DMA, it must be turned
on explicitly, either with the "dma=" option described below or with
setserial. A multiport card can be forced into DMA mode by using setserial;
however, most multiport cards don't support DMA.
The latest version of setserial allows the enhanced configuration of the ESP
card to be viewed and modified.
***
This package contains the files needed to compile a module to support the Hayes
ESP card. The drivers are basically a modified version of the serial drivers.
Features:
- Uses the enhanced mode of the ESP card, allowing a wider range of
interrupts and features than compatibility mode
- Uses DMA and 16 bit PIO mode to transfer data to and from the ESP's FIFOs,
reducing CPU load
- Supports primary and secondary ports
If the driver is compiled as a module, the IRQs to use can be specified by
using the irq= option. The format is:
irq=[0x100],[0x140],[0x180],[0x200],[0x240],[0x280],[0x300],[0x380]
The address in brackets is the base address of the card. The IRQ of
nonexistent cards can be set to 0. If an IRQ of a card that does exist is set
to 0, the driver will attempt to guess at the correct IRQ. For example, to set
the IRQ of the card at address 0x300 to 12, the insmod command would be:
insmod esp irq=0,0,0,0,0,0,12,0
The custom divisor can be set by using the divisor= option. The format is the
same as for the irq= option. Each divisor value is a series of hex digits,
with each digit representing the divisor to use for a corresponding port. The
divisor value is constructed RIGHT TO LEFT. Specifying a nonzero divisor value
will automatically set the spd_cust flag. To calculate the divisor to use for
a certain baud rate, divide the port's base baud (generally 921600) by the
desired rate. For example, to set the divisor of the primary port at 0x300 to
4 and the divisor of the secondary port at 0x308 to 8, the insmod command would
be:
insmod esp divisor=0,0,0,0,0,0,0x84,0
The dma= option can be used to set the DMA channel. The channel can be either
1 or 3. Specifying any other value will force the driver to use PIO mode.
For example, to set the DMA channel to 3, the insmod command would be:
insmod esp dma=3
The rx_trigger= and tx_trigger= options can be used to set the FIFO trigger
levels. They specify when the ESP card should send an interrupt. Larger
values will decrease the number of interrupts; however, a value too high may
result in data loss. Valid values are 1 through 1023, with 768 being the
default. For example, to set the receive trigger level to 512 bytes and the
transmit trigger level to 700 bytes, the insmod command would be:
insmod esp rx_trigger=512 tx_trigger=700
The flow_off= and flow_on= options can be used to set the hardware flow off/
flow on levels. The flow on level must be lower than the flow off level, and
the flow off level should be higher than rx_trigger. Valid values are 1
through 1023, with 1016 being the default flow off level and 944 being the
default flow on level. For example, to set the flow off level to 1000 bytes
and the flow on level to 935 bytes, the insmod command would be:
insmod esp flow_off=1000 flow_on=935
The rx_timeout= option can be used to set the receive timeout value. This
value indicates how long after receiving the last character that the ESP card
should wait before signalling an interrupt. Valid values are 0 though 255,
with 128 being the default. A value too high will increase latency, and a
value too low will cause unnecessary interrupts. For example, to set the
receive timeout to 255, the insmod command would be:
insmod esp rx_timeout=255
The pio_threshold= option sets the threshold (in number of characters) for
using PIO mode instead of DMA mode. For example, if this value is 32,
transfers of 32 bytes or less will always use PIO mode.
insmod esp pio_threshold=32
Multiple options can be listed on the insmod command line by separating each
option with a space. For example:
insmod esp dma=3 trigger=512
The esp module can be automatically loaded when needed. To cause this to
happen, add the following lines to /etc/modprobe.conf (replacing the last line
with options for your configuration):
alias char-major-57 esp
alias char-major-58 esp
options esp irq=0,0,0,0,0,0,3,0 divisor=0,0,0,0,0,0,0x4,0
You may also need to run 'depmod -a'.
Devices must be created manually. To create the devices, note the output from
the module after it is inserted. The output will appear in the location where
kernel messages usually appear (usually /var/adm/messages). Create two devices
for each 'tty' mentioned, one with major of 57 and the other with major of 58.
The minor number should be the same as the tty number reported. The commands
would be (replace ? with the tty number):
mknod /dev/ttyP? c 57 ?
mknod /dev/cup? c 58 ?
For example, if the following line appears:
Oct 24 18:17:23 techno kernel: ttyP8 at 0x0140 (irq = 3) is an ESP primary port
...two devices should be created:
mknod /dev/ttyP8 c 57 8
mknod /dev/cup8 c 58 8
You may need to set the permissions on the devices:
chmod 666 /dev/ttyP*
chmod 666 /dev/cup*
The ESP module and the serial module should not conflict (they can be used at
the same time). After the ESP module has been loaded the ports on the ESP card
will no longer be accessible by the serial driver.
If I/O errors are experienced when accessing the port, check for IRQ and DMA
conflicts ('cat /proc/interrupts' and 'cat /proc/dma' for a list of IRQs and
DMAs currently in use).
Enjoy!
Andrew J. Robinson <arobinso@nyx.net>
Documentation/serial/moxa-smartio
+523
View File
File diff suppressed because it is too large Load Diff
Documentation/serial/riscom8.txt
+36
View File
@@ -0,0 +1,36 @@
* NOTE - this is an unmaintained driver. The original author cannot be located.
SDL Communications is now SBS Technologies, and does not have any
information on these ancient ISA cards on their website.
James Nelson <james4765@gmail.com> - 12-12-2004
This is the README for RISCom/8 multi-port serial driver
(C) 1994-1996 D.Gorodchanin
See file LICENSE for terms and conditions.
NOTE: English is not my native language.
I'm sorry for any mistakes in this text.
Misc. notes for RISCom/8 serial driver, in no particular order :)
1) This driver can support up to 4 boards at time.
Use string "riscom8=0xXXX,0xXXX,0xXXX,0xXXX" at LILO prompt, for
setting I/O base addresses for boards. If you compile driver
as module use modprobe options "iobase=0xXXX iobase1=0xXXX iobase2=..."
2) The driver partially supports famous 'setserial' program, you can use almost
any of its options, excluding port & irq settings.
3) There are some misc. defines at the beginning of riscom8.c, please read the
comments and try to change some of them in case of problems.
4) I consider the current state of the driver as BETA.
5) SDL Communications WWW page is http://www.sdlcomm.com.
6) You can use the MAKEDEV program to create RISCom/8 /dev/ttyL* entries.
7) Minor numbers for first board are 0-7, for second 8-15, etc.
22 Apr 1996.
Documentation/serial/rocket.txt
+189
View File
@@ -0,0 +1,189 @@
Comtrol(tm) RocketPort(R)/RocketModem(TM) Series
Device Driver for the Linux Operating System
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
PRODUCT OVERVIEW
----------------
This driver provides a loadable kernel driver for the Comtrol RocketPort
and RocketModem PCI boards. These boards provide, 2, 4, 8, 16, or 32
high-speed serial ports or modems. This driver supports up to a combination
of four RocketPort or RocketModems boards in one machine simultaneously.
This file assumes that you are using the RocketPort driver which is
integrated into the kernel sources.
The driver can also be installed as an external module using the usual
"make;make install" routine. This external module driver, obtainable
from the Comtrol website listed below, is useful for updating the driver
or installing it into kernels which do not have the driver configured
into them. Installations instructions for the external module
are in the included README and HW_INSTALL files.
RocketPort ISA and RocketModem II PCI boards currently are only supported by
this driver in module form.
The RocketPort ISA board requires I/O ports to be configured by the DIP
switches on the board. See the section "ISA Rocketport Boards" below for
information on how to set the DIP switches.
You pass the I/O port to the driver using the following module parameters:
board1 : I/O port for the first ISA board
board2 : I/O port for the second ISA board
board3 : I/O port for the third ISA board
board4 : I/O port for the fourth ISA board
There is a set of utilities and scripts provided with the external driver
( downloadable from http://www.comtrol.com ) that ease the configuration and
setup of the ISA cards.
The RocketModem II PCI boards require firmware to be loaded into the card
before it will function. The driver has only been tested as a module for this
board.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
INSTALLATION PROCEDURES
-----------------------
RocketPort/RocketModem PCI cards require no driver configuration, they are
automatically detected and configured.
The RocketPort driver can be installed as a module (recommended) or built
into the kernel. This is selected, as for other drivers, through the `make config`
command from the root of the Linux source tree during the kernel build process.
The RocketPort/RocketModem serial ports installed by this driver are assigned
device major number 46, and will be named /dev/ttyRx, where x is the port number
starting at zero (ex. /dev/ttyR0, /devttyR1, ...). If you have multiple cards
installed in the system, the mapping of port names to serial ports is displayed
in the system log at /var/log/messages.
If installed as a module, the module must be loaded. This can be done
manually by entering "modprobe rocket". To have the module loaded automatically
upon system boot, edit the /etc/modprobe.conf file and add the line
"alias char-major-46 rocket".
In order to use the ports, their device names (nodes) must be created with mknod.
This is only required once, the system will retain the names once created. To
create the RocketPort/RocketModem device names, use the command
"mknod /dev/ttyRx c 46 x" where x is the port number starting at zero. For example:
>mknod /dev/ttyR0 c 46 0
>mknod /dev/ttyR1 c 46 1
>mknod /dev/ttyR2 c 46 2
The Linux script MAKEDEV will create the first 16 ttyRx device names (nodes)
for you:
>/dev/MAKEDEV ttyR
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
ISA Rocketport Boards
---------------------
You must assign and configure the I/O addresses used by the ISA Rocketport
card before installing and using it. This is done by setting a set of DIP
switches on the Rocketport board.
SETTING THE I/O ADDRESS
-----------------------
Before installing RocketPort(R) or RocketPort RA boards, you must find
a range of I/O addresses for it to use. The first RocketPort card
requires a 68-byte contiguous block of I/O addresses, starting at one
of the following: 0x100h, 0x140h, 0x180h, 0x200h, 0x240h, 0x280h,
0x300h, 0x340h, 0x380h. This I/O address must be reflected in the DIP
switches of *all* of the Rocketport cards.
The second, third, and fourth RocketPort cards require a 64-byte
contiguous block of I/O addresses, starting at one of the following
I/O addresses: 0x100h, 0x140h, 0x180h, 0x1C0h, 0x200h, 0x240h, 0x280h,
0x2C0h, 0x300h, 0x340h, 0x380h, 0x3C0h. The I/O address used by the
second, third, and fourth Rocketport cards (if present) are set via
software control. The DIP switch settings for the I/O address must be
set to the value of the first Rocketport cards.
In order to distinguish each of the card from the others, each card
must have a unique board ID set on the dip switches. The first
Rocketport board must be set with the DIP switches corresponding to
the first board, the second board must be set with the DIP switches
corresponding to the second board, etc. IMPORTANT: The board ID is
the only place where the DIP switch settings should differ between the
various Rocketport boards in a system.
The I/O address range used by any of the RocketPort cards must not
conflict with any other cards in the system, including other
RocketPort cards. Below, you will find a list of commonly used I/O
address ranges which may be in use by other devices in your system.
On a Linux system, "cat /proc/ioports" will also be helpful in
identifying what I/O addresses are being used by devices on your
system.
Remember, the FIRST RocketPort uses 68 I/O addresses. So, if you set it
for 0x100, it will occupy 0x100 to 0x143. This would mean that you
CAN NOT set the second, third or fourth board for address 0x140 since
the first 4 bytes of that range are used by the first board. You would
need to set the second, third, or fourth board to one of the next available
blocks such as 0x180.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
RocketPort and RocketPort RA SW1 Settings:
+-------------------------------+
| 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 |
+-------+-------+---------------+
| Unused| Card | I/O Port Block|
+-------------------------------+
DIP Switches DIP Switches
7 8 6 5
=================== ===================
On On UNUSED, MUST BE ON. On On First Card <==== Default
On Off Second Card
Off On Third Card
Off Off Fourth Card
DIP Switches I/O Address Range
4 3 2 1 Used by the First Card
=====================================
On Off On Off 100-143
On Off Off On 140-183
On Off Off Off 180-1C3 <==== Default
Off On On Off 200-243
Off On Off On 240-283
Off On Off Off 280-2C3
Off Off On Off 300-343
Off Off Off On 340-383
Off Off Off Off 380-3C3
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
REPORTING BUGS
--------------
For technical support, please provide the following
information: Driver version, kernel release, distribution of
kernel, and type of board you are using. Error messages and log
printouts port configuration details are especially helpful.
USA
Phone: (612) 494-4100
FAX: (612) 494-4199
email: support@comtrol.com
Comtrol Europe
Phone: +44 (0) 1 869 323-220
FAX: +44 (0) 1 869 323-211
email: support@comtrol.co.uk
Web: http://www.comtrol.com
FTP: ftp.comtrol.com
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Documentation/serial/specialix.txt
+383
View File
@@ -0,0 +1,383 @@
specialix.txt -- specialix IO8+ multiport serial driver readme.
Copyright (C) 1997 Roger Wolff (R.E.Wolff@BitWizard.nl)
Specialix pays for the development and support of this driver.
Please DO contact io8-linux@specialix.co.uk if you require
support.
This driver was developed in the BitWizard linux device
driver service. If you require a linux device driver for your
product, please contact devices@BitWizard.nl for a quote.
This code is firmly based on the riscom/8 serial driver,
written by Dmitry Gorodchanin. The specialix IO8+ card
programming information was obtained from the CL-CD1865 Data
Book, and Specialix document number 6200059: IO8+ Hardware
Functional Specification, augmented by document number 6200088:
Merak Hardware Functional Specification. (IO8+/PCI is also
called Merak)
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
USA.
Intro
=====
This file contains some random information, that I like to have online
instead of in a manual that can get lost. Ever misplace your Linux
kernel sources? And the manual of one of the boards in your computer?
Addresses and interrupts
========================
Address dip switch settings:
The dip switch sets bits 2-9 of the IO address.
9 8 7 6 5 4 3 2
+-----------------+
0 | X X X X X X X |
| | = IoBase = 0x100
1 | X |
+-----------------+ ------ RS232 connectors ---->
| | |
edge connector
| | |
V V V
Base address 0x100 caused a conflict in one of my computers once. I
haven't the foggiest why. My Specialix card is now at 0x180. My
other computer runs just fine with the Specialix card at 0x100....
The card occupies 4 addresses, but actually only two are really used.
The PCI version doesn't have any dip switches. The BIOS assigns
an IO address.
The driver now still autoprobes at 0x100, 0x180, 0x250 and 0x260. If
that causes trouble for you, please report that. I'll remove
autoprobing then.
The driver will tell the card what IRQ to use, so you don't have to
change any jumpers to change the IRQ. Just use a command line
argument (irq=xx) to the insmod program to set the interrupt.
The BIOS assigns the IRQ on the PCI version. You have no say in what
IRQ to use in that case.
If your specialix cards are not at the default locations, you can use
the kernel command line argument "specialix=io0,irq0,io1,irq1...".
Here "io0" is the io address for the first card, and "irq0" is the
irq line that the first card should use. And so on.
Examples.
You use the driver as a module and have three cards at 0x100, 0x250
and 0x180. And some way or another you want them detected in that
order. Moreover irq 12 is taken (e.g. by your PS/2 mouse).
insmod specialix.o iobase=0x100,0x250,0x180 irq=9,11,15
The same three cards, but now in the kernel would require you to
add
specialix=0x100,9,0x250,11,0x180,15
to the command line. This would become
append="specialix=0x100,9,0x250,11,0x180,15"
in your /etc/lilo.conf file if you use lilo.
The Specialix driver is slightly odd: It allows you to have the second
or third card detected without having a first card. This has
advantages and disadvantages. A slot that isn't filled by an ISA card,
might be filled if a PCI card is detected. Thus if you have an ISA
card at 0x250 and a PCI card, you would get:
sx0: specialix IO8+ Board at 0x100 not found.
sx1: specialix IO8+ Board at 0x180 not found.
sx2: specialix IO8+ board detected at 0x250, IRQ 12, CD1865 Rev. B.
sx3: specialix IO8+ Board at 0x260 not found.
sx0: specialix IO8+ board detected at 0xd800, IRQ 9, CD1865 Rev. B.
This would happen if you don't give any probe hints to the driver.
If you would specify:
specialix=0x250,11
you'd get the following messages:
sx0: specialix IO8+ board detected at 0x250, IRQ 11, CD1865 Rev. B.
sx1: specialix IO8+ board detected at 0xd800, IRQ 9, CD1865 Rev. B.
ISA probing is aborted after the IO address you gave is exhausted, and
the PCI card is now detected as the second card. The ISA card is now
also forced to IRQ11....
Baud rates
==========
The rev 1.2 and below boards use a CL-CD1864. These chips can only
do 64kbit. The rev 1.3 and newer boards use a CL-CD1865. These chips
are officially capable of 115k2.
The Specialix card uses a 25MHz crystal (in times two mode, which in
fact is a divided by two mode). This is not enough to reach the rated
115k2 on all ports at the same time. With this clock rate you can only
do 37% of this rate. This means that at 115k2 on all ports you are
going to lose characters (The chip cannot handle that many incoming
bits at this clock rate.) (Yes, you read that correctly: there is a
limit to the number of -=bits=- per second that the chip can handle.)
If you near the "limit" you will first start to see a graceful
degradation in that the chip cannot keep the transmitter busy at all
times. However with a central clock this slow, you can also get it to
miss incoming characters. The driver will print a warning message when
you are outside the official specs. The messages usually show up in
the file /var/log/messages .
The specialix card cannot reliably do 115k2. If you use it, you have
to do "extensive testing" (*) to verify if it actually works.
When "mgetty" communicates with my modem at 115k2 it reports:
got: +++[0d]ATQ0V1H0[0d][0d][8a]O[cb][0d][8a]
^^^^ ^^^^ ^^^^
The three characters that have the "^^^" under them have suffered a
bit error in the highest bit. In conclusion: I've tested it, and found
that it simply DOESN'T work for me. I also suspect that this is also
caused by the baud rate being just a little bit out of tune.
I upgraded the crystal to 66Mhz on one of my Specialix cards. Works
great! Contact me for details. (Voids warranty, requires a steady hand
and more such restrictions....)
(*) Cirrus logic CD1864 databook, page 40.
Cables for the Specialix IO8+
=============================
The pinout of the connectors on the IO8+ is:
pin short direction long name
name
Pin 1 DCD input Data Carrier Detect
Pin 2 RXD input Receive
Pin 3 DTR/RTS output Data Terminal Ready/Ready To Send
Pin 4 GND - Ground
Pin 5 TXD output Transmit
Pin 6 CTS input Clear To Send
-- 6 5 4 3 2 1 --
| |
| |
| |
| |
+----- -----+
|__________|
clip
Front view of an RJ12 connector. Cable moves "into" the paper.
(the plug is ready to plug into your mouth this way...)
NULL cable. I don't know who is going to use these except for
testing purposes, but I tested the cards with this cable. (It
took quite a while to figure out, so I'm not going to delete
it. So there! :-)
This end goes This end needs
straight into the some twists in
RJ12 plug. the wiring.
IO8+ RJ12 IO8+ RJ12
1 DCD white -
- - 1 DCD
2 RXD black 5 TXD
3 DTR/RTS red 6 CTS
4 GND green 4 GND
5 TXD yellow 2 RXD
6 CTS blue 3 DTR/RTS
Same NULL cable, but now sorted on the second column.
1 DCD white -
- - 1 DCD
5 TXD yellow 2 RXD
6 CTS blue 3 DTR/RTS
4 GND green 4 GND
2 RXD black 5 TXD
3 DTR/RTS red 6 CTS
This is a modem cable usable for hardware handshaking:
RJ12 DB25 DB9
1 DCD white 8 DCD 1 DCD
2 RXD black 3 RXD 2 RXD
3 DTR/RTS red 4 RTS 7 RTS
4 GND green 7 GND 5 GND
5 TXD yellow 2 TXD 3 TXD
6 CTS blue 5 CTS 8 CTS
+---- 6 DSR 6 DSR
+---- 20 DTR 4 DTR
This is a modem cable usable for software handshaking:
It allows you to reset the modem using the DTR ioctls.
I (REW) have never tested this, "but xxxxxxxxxxxxx
says that it works." If you test this, please
tell me and I'll fill in your name on the xxx's.
RJ12 DB25 DB9
1 DCD white 8 DCD 1 DCD
2 RXD black 3 RXD 2 RXD
3 DTR/RTS red 20 DTR 4 DTR
4 GND green 7 GND 5 GND
5 TXD yellow 2 TXD 3 TXD
6 CTS blue 5 CTS 8 CTS
+---- 6 DSR 6 DSR
+---- 4 RTS 7 RTS
I bought a 6 wire flat cable. It was colored as indicated.
Check that yours is the same before you trust me on this.
Hardware handshaking issues.
============================
The driver can be told to operate in two different ways. The default
behaviour is specialix.sx_rtscts = 0 where the pin behaves as DTR when
hardware handshaking is off. It behaves as the RTS hardware
handshaking signal when hardware handshaking is selected.
When you use this, you have to use the appropriate cable. The
cable will either be compatible with hardware handshaking or with
software handshaking. So switching on the fly is not really an
option.
I actually prefer to use the "specialix.sx_rtscts=1" option.
This makes the DTR/RTS pin always an RTS pin, and ioctls to
change DTR are always ignored. I have a cable that is configured
for this.
Ports and devices
=================
Port 0 is the one furthest from the card-edge connector.
Devices:
You should make the devices as follows:
bash
cd /dev
for i in 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 \
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
do
echo -n "$i "
mknod /dev/ttyW$i c 75 $i
mknod /dev/cuw$i c 76 $i
done
echo ""
If your system doesn't come with these devices preinstalled, bug your
linux-vendor about this. They have had ample time to get this
implemented by now.
You cannot have more than 4 boards in one computer. The card only
supports 4 different interrupts. If you really want this, contact me
about this and I'll give you a few tips (requires soldering iron)....
If you have enough PCI slots, you can probably use more than 4 PCI
versions of the card though....
The PCI version of the card cannot adhere to the mechanical part of
the PCI spec because the 8 serial connectors are simply too large. If
it doesn't fit in your computer, bring back the card.
------------------------------------------------------------------------
Fixed bugs and restrictions:
- During initialization, interrupts are blindly turned on.
Having a shadow variable would cause an extra memory
access on every IO instruction.
- The interrupt (on the card) should be disabled when we
don't allocate the Linux end of the interrupt. This allows
a different driver/card to use it while all ports are not in
use..... (a la standard serial port)
== An extra _off variant of the sx_in and sx_out macros are
now available. They don't set the interrupt enable bit.
These are used during initialization. Normal operation uses
the old variant which enables the interrupt line.
- RTS/DTR issue needs to be implemented according to
specialix' spec.
I kind of like the "determinism" of the current
implementation. Compile time flag?
== Ok. Compile time flag! Default is how Specialix likes it.
== Now a config time flag! Gets saved in your config file. Neat!
- Can you set the IO address from the lilo command line?
If you need this, bug me about it, I'll make it.
== Hah! No bugging needed. Fixed! :-)
- Cirrus logic hasn't gotten back to me yet why the CD1865 can
and the CD1864 can't do 115k2. I suspect that this is
because the CD1864 is not rated for 33MHz operation.
Therefore the CD1864 versions of the card can't do 115k2 on
all ports just like the CD1865 versions. The driver does
not block 115k2 on CD1864 cards.
== I called the Cirrus Logic representative here in Holland.
The CD1864 databook is identical to the CD1865 databook,
except for an extra warning at the end. Similar Bit errors
have been observed in testing at 115k2 on both an 1865 and
a 1864 chip. I see no reason why I would prohibit 115k2 on
1864 chips and not do it on 1865 chips. Actually there is
reason to prohibit it on BOTH chips. I print a warning.
If you use 115k2, you're on your own.
- A spiky CD may send spurious HUPs. Also in CLOCAL???
-- A fix for this turned out to be counter productive.
Different fix? Current behaviour is acceptable?
-- Maybe the current implementation is correct. If anybody
gets bitten by this, please report, and it will get fixed.
-- Testing revealed that when in CLOCAL, the problem doesn't
occur. As warned for in the CD1865 manual, the chip may
send modem intr's on a spike. We could filter those out,
but that would be a cludge anyway (You'd still risk getting
a spurious HUP when two spikes occur.).....
Bugs & restrictions:
- This is a difficult card to autoprobe.
You have to WRITE to the address register to even
read-probe a CD186x register. Disable autodetection?
-- Specialix: any suggestions?
Documentation/serial/stallion.txt
+392
View File
@@ -0,0 +1,392 @@
* NOTE - This is an unmaintained driver. Lantronix, which bought Stallion
technologies, is not active in driver maintenance, and they have no information
on when or if they will have a 2.6 driver.
James Nelson <james4765@gmail.com> - 12-12-2004
Stallion Multiport Serial Driver Readme
---------------------------------------
Copyright (C) 1994-1999, Stallion Technologies.
Version: 5.5.1
Date: 28MAR99
1. INTRODUCTION
There are two drivers that work with the different families of Stallion
multiport serial boards. One is for the Stallion smart boards - that is
EasyIO, EasyConnection 8/32 and EasyConnection 8/64-PCI, the other for
the true Stallion intelligent multiport boards - EasyConnection 8/64
(ISA, EISA, MCA), EasyConnection/RA-PCI, ONboard and Brumby.
If you are using any of the Stallion intelligent multiport boards (Brumby,
ONboard, EasyConnection 8/64 (ISA, EISA, MCA), EasyConnection/RA-PCI) with
Linux you will need to get the driver utility package. This contains a
firmware loader and the firmware images necessary to make the devices operate.
The Stallion Technologies ftp site, ftp.stallion.com, will always have
the latest version of the driver utility package.
ftp://ftp.stallion.com/drivers/ata5/Linux/ata-linux-550.tar.gz
As of the printing of this document the latest version of the driver
utility package is 5.5.0. If a later version is now available then you
should use the latest version.
If you are using the EasyIO, EasyConnection 8/32 or EasyConnection 8/64-PCI
boards then you don't need this package, although it does have a serial stats
display program.
If you require DIP switch settings, EISA or MCA configuration files, or any
other information related to Stallion boards then have a look at Stallion's
web pages at http://www.stallion.com.
2. INSTALLATION
The drivers can be used as loadable modules or compiled into the kernel.
You can choose which when doing a "config" on the kernel.
All ISA, EISA and MCA boards that you want to use need to be configured into
the driver(s). All PCI boards will be automatically detected when you load
the driver - so they do not need to be entered into the driver(s)
configuration structure. Note that kernel PCI support is required to use PCI
boards.
There are two methods of configuring ISA, EISA and MCA boards into the drivers.
If using the driver as a loadable module then the simplest method is to pass
the driver configuration as module arguments. The other method is to modify
the driver source to add configuration lines for each board in use.
If you have pre-built Stallion driver modules then the module argument
configuration method should be used. A lot of Linux distributions come with
pre-built driver modules in /lib/modules/X.Y.Z/misc for the kernel in use.
That makes things pretty simple to get going.
2.1 MODULE DRIVER CONFIGURATION:
The simplest configuration for modules is to use the module load arguments
to configure any ISA, EISA or MCA boards. PCI boards are automatically
detected, so do not need any additional configuration at all.
If using EasyIO, EasyConnection 8/32 ISA or MCA, or EasyConnection 8/63-PCI
boards then use the "stallion" driver module, Otherwise if you are using
an EasyConnection 8/64 ISA, EISA or MCA, EasyConnection/RA-PCI, ONboard,
Brumby or original Stallion board then use the "istallion" driver module.
Typically to load up the smart board driver use:
modprobe stallion
This will load the EasyIO and EasyConnection 8/32 driver. It will output a
message to say that it loaded and print the driver version number. It will
also print out whether it found the configured boards or not. These messages
may not appear on the console, but typically are always logged to
/var/adm/messages or /var/log/syslog files - depending on how the klogd and
syslogd daemons are setup on your system.
To load the intelligent board driver use:
modprobe istallion
It will output similar messages to the smart board driver.
If not using an auto-detectable board type (that is a PCI board) then you
will also need to supply command line arguments to the modprobe command
when loading the driver. The general form of the configuration argument is
board?=<name>[,<ioaddr>[,<addr>][,<irq>]]
where:
board? -- specifies the arbitrary board number of this board,
can be in the range 0 to 3.
name -- textual name of this board. The board name is the common
board name, or any "shortened" version of that. The board
type number may also be used here.
ioaddr -- specifies the I/O address of this board. This argument is
optional, but should generally be specified.
addr -- optional second address argument. Some board types require
a second I/O address, some require a memory address. The
exact meaning of this argument depends on the board type.
irq -- optional IRQ line used by this board.
Up to 4 board configuration arguments can be specified on the load line.
Here is some examples:
modprobe stallion board0=easyio,0x2a0,5
This configures an EasyIO board as board 0 at I/O address 0x2a0 and IRQ 5.
modprobe istallion board3=ec8/64,0x2c0,0xcc000
This configures an EasyConnection 8/64 ISA as board 3 at I/O address 0x2c0 at
memory address 0xcc000.
modprobe stallion board1=ec8/32-at,0x2a0,0x280,10
This configures an EasyConnection 8/32 ISA board at primary I/O address 0x2a0,
secondary address 0x280 and IRQ 10.
You will probably want to enter this module load and configuration information
into your system startup scripts so that the drivers are loaded and configured
on each system boot. Typically the start up script would be something like
/etc/modprobe.conf.
2.2 STATIC DRIVER CONFIGURATION:
For static driver configuration you need to modify the driver source code.
Entering ISA, EISA and MCA boards into the driver(s) configuration structure
involves editing the driver(s) source file. It's pretty easy if you follow
the instructions below. Both drivers can support up to 4 boards. The smart
card driver (the stallion.c driver) supports any combination of EasyIO and
EasyConnection 8/32 boards (up to a total of 4). The intelligent driver
supports any combination of ONboards, Brumbys, Stallions and EasyConnection
8/64 (ISA and EISA) boards (up to a total of 4).
To set up the driver(s) for the boards that you want to use you need to
edit the appropriate driver file and add configuration entries.
If using EasyIO or EasyConnection 8/32 ISA or MCA boards,
In drivers/char/stallion.c:
- find the definition of the stl_brdconf array (of structures)
near the top of the file
- modify this to match the boards you are going to install
(the comments before this structure should help)
- save and exit
If using ONboard, Brumby, Stallion or EasyConnection 8/64 (ISA or EISA)
boards,
In drivers/char/istallion.c:
- find the definition of the stli_brdconf array (of structures)
near the top of the file
- modify this to match the boards you are going to install
(the comments before this structure should help)
- save and exit
Once you have set up the board configurations then you are ready to build
the kernel or modules.
When the new kernel is booted, or the loadable module loaded then the
driver will emit some kernel trace messages about whether the configured
boards were detected or not. Depending on how your system logger is set
up these may come out on the console, or just be logged to
/var/adm/messages or /var/log/syslog. You should check the messages to
confirm that all is well.
2.3 SHARING INTERRUPTS
It is possible to share interrupts between multiple EasyIO and
EasyConnection 8/32 boards in an EISA system. To do this you must be using
static driver configuration, modifying the driver source code to add driver
configuration. Then a couple of extra things are required:
1. When entering the board resources into the stallion.c file you need to
mark the boards as using level triggered interrupts. Do this by replacing
the "0" entry at field position 6 (the last field) in the board
configuration structure with a "1". (This is the structure that defines
the board type, I/O locations, etc. for each board). All boards that are
sharing an interrupt must be set this way, and each board should have the
same interrupt number specified here as well. Now build the module or
kernel as you would normally.
2. When physically installing the boards into the system you must enter
the system EISA configuration utility. You will need to install the EISA
configuration files for *all* the EasyIO and EasyConnection 8/32 boards
that are sharing interrupts. The Stallion EasyIO and EasyConnection 8/32
EISA configuration files required are supplied by Stallion Technologies
on the EASY Utilities floppy diskette (usually supplied in the box with
the board when purchased. If not, you can pick it up from Stallion's FTP
site, ftp.stallion.com). You will need to edit the board resources to
choose level triggered interrupts, and make sure to set each board's
interrupt to the same IRQ number.
You must complete both the above steps for this to work. When you reboot
or load the driver your EasyIO and EasyConnection 8/32 boards will be
sharing interrupts.
2.4 USING HIGH SHARED MEMORY
The EasyConnection 8/64-EI, ONboard and Stallion boards are capable of
using shared memory addresses above the usual 640K - 1Mb range. The ONboard
ISA and the Stallion boards can be programmed to use memory addresses up to
16Mb (the ISA bus addressing limit), and the EasyConnection 8/64-EI and
ONboard/E can be programmed for memory addresses up to 4Gb (the EISA bus
addressing limit).
The higher than 1Mb memory addresses are fully supported by this driver.
Just enter the address as you normally would for a lower than 1Mb address
(in the driver's board configuration structure).
2.5 TROUBLE SHOOTING
If a board is not found by the driver but is actually in the system then the
most likely problem is that the I/O address is wrong. Change the module load
argument for the loadable module form. Or change it in the driver stallion.c
or istallion.c configuration structure and rebuild the kernel or modules, or
change it on the board.
On EasyIO and EasyConnection 8/32 boards the IRQ is software programmable, so
if there is a conflict you may need to change the IRQ used for a board. There
are no interrupts to worry about for ONboard, Brumby or EasyConnection 8/64
(ISA, EISA and MCA) boards. The memory region on EasyConnection 8/64 and
ONboard boards is software programmable, but not on the Brumby boards.
3. USING THE DRIVERS
3.1 INTELLIGENT DRIVER OPERATION
The intelligent boards also need to have their "firmware" code downloaded
to them. This is done via a user level application supplied in the driver
utility package called "stlload". Compile this program wherever you dropped
the package files, by typing "make". In its simplest form you can then type
./stlload -i cdk.sys
in this directory and that will download board 0 (assuming board 0 is an
EasyConnection 8/64 or EasyConnection/RA board). To download to an
ONboard, Brumby or Stallion do:
./stlload -i 2681.sys
Normally you would want all boards to be downloaded as part of the standard
system startup. To achieve this, add one of the lines above into the
/etc/rc.d/rc.S or /etc/rc.d/rc.serial file. To download each board just add
the "-b <brd-number>" option to the line. You will need to download code for
every board. You should probably move the stlload program into a system
directory, such as /usr/sbin. Also, the default location of the cdk.sys image
file in the stlload down-loader is /usr/lib/stallion. Create that directory
and put the cdk.sys and 2681.sys files in it. (It's a convenient place to put
them anyway). As an example your /etc/rc.d/rc.S file might have the
following lines added to it (if you had 3 boards):
/usr/sbin/stlload -b 0 -i /usr/lib/stallion/cdk.sys
/usr/sbin/stlload -b 1 -i /usr/lib/stallion/2681.sys
/usr/sbin/stlload -b 2 -i /usr/lib/stallion/2681.sys
The image files cdk.sys and 2681.sys are specific to the board types. The
cdk.sys will only function correctly on an EasyConnection 8/64 board. Similarly
the 2681.sys image fill only operate on ONboard, Brumby and Stallion boards.
If you load the wrong image file into a board it will fail to start up, and
of course the ports will not be operational!
If you are using the modularized version of the driver you might want to put
the modprobe calls in the startup script as well (before the download lines
obviously).
3.2 USING THE SERIAL PORTS
Once the driver is installed you will need to setup some device nodes to
access the serial ports. The simplest method is to use the /dev/MAKEDEV program.
It will automatically create device entries for Stallion boards. This will
create the normal serial port devices as /dev/ttyE# where# is the port number
starting from 0. A bank of 64 minor device numbers is allocated to each board,
so the first port on the second board is port 64,etc. A set of callout type
devices may also be created. They are created as the devices /dev/cue# where #
is the same as for the ttyE devices.
For the most part the Stallion driver tries to emulate the standard PC system
COM ports and the standard Linux serial driver. The idea is that you should
be able to use Stallion board ports and COM ports interchangeably without
modifying anything but the device name. Anything that doesn't work like that
should be considered a bug in this driver!
If you look at the driver code you will notice that it is fairly closely
based on the Linux serial driver (linux/drivers/char/serial.c). This is
intentional, obviously this is the easiest way to emulate its behavior!
Since this driver tries to emulate the standard serial ports as much as
possible, most system utilities should work as they do for the standard
COM ports. Most importantly "stty" works as expected and "setserial" can
also be used (excepting the ability to auto-configure the I/O and IRQ
addresses of boards). Higher baud rates are supported in the usual fashion
through setserial or using the CBAUDEX extensions. Note that the EasyIO and
EasyConnection (all types) support at least 57600 and 115200 baud. The newer
EasyConnection XP modules and new EasyIO boards support 230400 and 460800
baud as well. The older boards including ONboard and Brumby support a
maximum baud rate of 38400.
If you are unfamiliar with how to use serial ports, then get the Serial-HOWTO
by Greg Hankins. It will explain everything you need to know!
4. NOTES
You can use both drivers at once if you have a mix of board types installed
in a system. However to do this you will need to change the major numbers
used by one of the drivers. Currently both drivers use major numbers 24, 25
and 28 for their devices. Change one driver to use some other major numbers,
and then modify the mkdevnods script to make device nodes based on those new
major numbers. For example, you could change the istallion.c driver to use
major numbers 60, 61 and 62. You will also need to create device nodes with
different names for the ports, for example ttyF# and cuf#.
The original Stallion board is no longer supported by Stallion Technologies.
Although it is known to work with the istallion driver.
Finding a free physical memory address range can be a problem. The older
boards like the Stallion and ONboard need large areas (64K or even 128K), so
they can be very difficult to get into a system. If you have 16 Mb of RAM
then you have no choice but to put them somewhere in the 640K -> 1Mb range.
ONboards require 64K, so typically 0xd0000 is good, or 0xe0000 on some
systems. If you have an original Stallion board, "V4.0" or Rev.O, then you
need a 64K memory address space, so again 0xd0000 and 0xe0000 are good.
Older Stallion boards are a much bigger problem. They need 128K of address
space and must be on a 128K boundary. If you don't have a VGA card then
0xc0000 might be usable - there is really no other place you can put them
below 1Mb.
Both the ONboard and old Stallion boards can use higher memory addresses as
well, but you must have less than 16Mb of RAM to be able to use them. Usual
high memory addresses used include 0xec0000 and 0xf00000.
The Brumby boards only require 16Kb of address space, so you can usually
squeeze them in somewhere. Common addresses are 0xc8000, 0xcc000, or in
the 0xd0000 range. EasyConnection 8/64 boards are even better, they only
require 4Kb of address space, again usually 0xc8000, 0xcc000 or 0xd0000
are good.
If you are using an EasyConnection 8/64-EI or ONboard/E then usually the
0xd0000 or 0xe0000 ranges are the best options below 1Mb. If neither of
them can be used then the high memory support to use the really high address
ranges is the best option. Typically the 2Gb range is convenient for them,
and gets them well out of the way.
The ports of the EasyIO-8M board do not have DCD or DTR signals. So these
ports cannot be used as real modem devices. Generally, when using these
ports you should only use the cueX devices.
The driver utility package contains a couple of very useful programs. One
is a serial port statistics collection and display program - very handy
for solving serial port problems. The other is an extended option setting
program that works with the intelligent boards.
5. DISCLAIMER
The information contained in this document is believed to be accurate and
reliable. However, no responsibility is assumed by Stallion Technologies
Pty. Ltd. for its use, nor any infringements of patents or other rights
of third parties resulting from its use. Stallion Technologies reserves
the right to modify the design of its products and will endeavour to change
the information in manuals and accompanying documentation accordingly.
Documentation/serial/sx.txt
+294
View File
@@ -0,0 +1,294 @@
sx.txt -- specialix SX/SI multiport serial driver readme.
Copyright (C) 1997 Roger Wolff (R.E.Wolff@BitWizard.nl)
Specialix pays for the development and support of this driver.
Please DO contact support@specialix.co.uk if you require
support.
This driver was developed in the BitWizard linux device
driver service. If you require a linux device driver for your
product, please contact devices@BitWizard.nl for a quote.
(History)
There used to be an SI driver by Simon Allan. This is a complete
rewrite from scratch. Just a few lines-of-code have been snatched.
(Sources)
Specialix document number 6210028: SX Host Card and Download Code
Software Functional Specification.
(Copying)
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
USA.
(Addendum)
I'd appreciate it that if you have fixes, that you send them
to me first.
Introduction
============
This file contains some random information, that I like to have online
instead of in a manual that can get lost. Ever misplace your Linux
kernel sources? And the manual of one of the boards in your computer?
Theory of operation
===================
An important thing to know is that the driver itself doesn't have the
firmware for the card. This means that you need the separate package
"sx_firmware". For now you can get the source at
ftp://ftp.bitwizard.nl/specialix/sx_firmware_<version>.tgz
The firmware load needs a "misc" device, so you'll need to enable the
"Support for user misc device modules" in your kernel configuration.
The misc device needs to be called "/dev/specialix_sxctl". It needs
misc major 10, and minor number 167 (assigned by HPA). The section
on creating device files below also creates this device.
After loading the sx.o module into your kernel, the driver will report
the number of cards detected, but because it doesn't have any
firmware, it will not be able to determine the number of ports. Only
when you then run "sx_firmware" will the firmware be downloaded and
the rest of the driver initialized. At that time the sx_firmware
program will report the number of ports installed.
In contrast with many other multi port serial cards, some of the data
structures are only allocated when the card knows the number of ports
that are connected. This means we won't waste memory for 120 port
descriptor structures when you only have 8 ports. If you experience
problems due to this, please report them: I haven't seen any.
Interrupts
==========
A multi port serial card, would generate a horrendous amount of
interrupts if it would interrupt the CPU for every received
character. Even more than 10 years ago, the trick not to use
interrupts but to poll the serial cards was invented.
The SX card allow us to do this two ways. First the card limits its
own interrupt rate to a rate that won't overwhelm the CPU. Secondly,
we could forget about the cards interrupt completely and use the
internal timer for this purpose.
Polling the card can take up to a few percent of your CPU. Using the
interrupts would be better if you have most of the ports idle. Using
timer-based polling is better if your card almost always has work to
do. You save the separate interrupt in that case.
In any case, it doesn't really matter all that much.
The most common problem with interrupts is that for ISA cards in a PCI
system the BIOS has to be told to configure that interrupt as "legacy
ISA". Otherwise the card can pull on the interrupt line all it wants
but the CPU won't see this.
If you can't get the interrupt to work, remember that polling mode is
more efficient (provided you actually use the card intensively).
Allowed Configurations
======================
Some configurations are disallowed. Even though at a glance they might
seem to work, they are known to lockup the bus between the host card
and the device concentrators. You should respect the drivers decision
not to support certain configurations. It's there for a reason.
Warning: Seriously technical stuff ahead. Executive summary: Don't use
SX cards except configured at a 64k boundary. Skip the next paragraph.
The SX cards can theoretically be placed at a 32k boundary. So for
instance you can put an SX card at 0xc8000-0xd7fff. This is not a
"recommended configuration". ISA cards have to tell the bus controller
how they like their timing. Due to timing issues they have to do this
based on which 64k window the address falls into. This means that the
32k window below and above the SX card have to use exactly the same
timing as the SX card. That reportedly works for other SX cards. But
you're still left with two useless 32k windows that should not be used
by anybody else.
Configuring the driver
======================
PCI cards are always detected. The driver auto-probes for ISA cards at
some sensible addresses. Please report if the auto-probe causes trouble
in your system, or when a card isn't detected.
I'm afraid I haven't implemented "kernel command line parameters" yet.
This means that if the default doesn't work for you, you shouldn't use
the compiled-into-the-kernel version of the driver. Use a module
instead. If you convince me that you need this, I'll make it for
you. Deal?
I'm afraid that the module parameters are a bit clumsy. If you have a
better idea, please tell me.
You can specify several parameters:
sx_poll: number of jiffies between timer-based polls.
Set this to "0" to disable timer based polls.
Initialization of cards without a working interrupt
will fail.
Set this to "1" if you want a polling driver.
(on Intel: 100 polls per second). If you don't use
fast baud rates, you might consider a value like "5".
(If you don't know how to do the math, use 1).
sx_slowpoll: Number of jiffies between timer-based polls.
Set this to "100" to poll once a second.
This should get the card out of a stall if the driver
ever misses an interrupt. I've never seen this happen,
and if it does, that's a bug. Tell me.
sx_maxints: Number of interrupts to request from the card.
The card normally limits interrupts to about 100 per
second to offload the host CPU. You can increase this
number to reduce latency on the card a little.
Note that if you give a very high number you can overload
your CPU as well as the CPU on the host card. This setting
is inaccurate and not recommended for SI cards (But it
works).
sx_irqmask: The mask of allowable IRQs to use. I suggest you set
this to 0 (disable IRQs all together) and use polling if
the assignment of IRQs becomes problematic. This is defined
as the sum of (1 << irq) 's that you want to allow. So
sx_irqmask of 8 (1 << 3) specifies that only irq 3 may
be used by the SX driver. If you want to specify to the
driver: "Either irq 11 or 12 is ok for you to use", then
specify (1 << 11) | (1 << 12) = 0x1800 .
sx_debug: You can enable different sorts of debug traces with this.
At "-1" all debugging traces are active. You'll get several
times more debugging output than you'll get characters
transmitted.
Baud rates
==========
Theoretically new SXDCs should be capable of more than 460k
baud. However the line drivers usually give up before that. Also the
CPU on the card may not be able to handle 8 channels going at full
blast at that speed. Moreover, the buffers are not large enough to
allow operation with 100 interrupts per second. You'll have to realize
that the card has a 256 byte buffer, so you'll have to increase the
number of interrupts per second if you have more than 256*100 bytes
per second to transmit. If you do any performance testing in this
area, I'd be glad to hear from you...
(Psst Linux users..... I think the Linux driver is more efficient than
the driver for other OSes. If you can and want to benchmark them
against each other, be my guest, and report your findings...... :-)
Ports and devices
=================
Port 0 is the top connector on the module closest to the host
card. Oh, the ports on the SXDCs and TAs are labelled from 1 to 8
instead of from 0 to 7, as they are numbered by linux. I'm stubborn in
this: I know for sure that I wouldn't be able to calculate which port
is which anymore if I would change that....
Devices:
You should make the device files as follows:
#!/bin/sh
# (I recommend that you cut-and-paste this into a file and run that)
cd /dev
t=0
mknod specialix_sxctl c 10 167
while [ $t -lt 64 ]
do
echo -n "$t "
mknod ttyX$t c 32 $t
mknod cux$t c 33 $t
t=`expr $t + 1`
done
echo ""
rm /etc/psdevtab
ps > /dev/null
This creates 64 devices. If you have more, increase the constant on
the line with "while". The devices start at 0, as is customary on
Linux. Specialix seems to like starting the numbering at 1.
If your system doesn't come with these devices pre-installed, bug your
linux-vendor about this. They should have these devices
"pre-installed" before the new millennium. The "ps" stuff at the end
is to "tell" ps that the new devices exist.
Officially the maximum number of cards per computer is 4. This driver
however supports as many cards in one machine as you want. You'll run
out of interrupts after a few, but you can switch to polled operation
then. At about 256 ports (More than 8 cards), we run out of minor
device numbers. Sorry. I suggest you buy a second computer.... (Or
switch to RIO).
------------------------------------------------------------------------
Fixed bugs and restrictions:
- Hangup processing.
-- Done.
- the write path in generic_serial (lockup / oops).
-- Done (Ugly: not the way I want it. Copied from serial.c).
- write buffer isn't flushed at close.
-- Done. I still seem to lose a few chars at close.
Sorry. I think that this is a firmware issue. (-> Specialix)
- drain hardware before changing termios
- Change debug on the fly.
- ISA free irq -1. (no firmware loaded).
- adding c8000 as a probe address. Added warning.
- Add a RAMtest for the RAM on the card.c
- Crash when opening a port "way" of the number of allowed ports.
(for example opening port 60 when there are only 24 ports attached)
- Sometimes the use-count strays a bit. After a few hours of
testing the use count is sometimes "3". If you are not like
me and can remember what you did to get it that way, I'd
appreciate an Email. Possibly fixed. Tell me if anyone still
sees this.
- TAs don't work right if you don't connect all the modem control
signals. SXDCs do. T225 firmware problem -> Specialix.
(Mostly fixed now, I think. Tell me if you encounter this!)
Bugs & restrictions:
- Arbitrary baud rates. Requires firmware update. (-> Specialix)
- Low latency (mostly firmware, -> Specialix)
Documentation/serial/tty.txt
+292
View File
@@ -0,0 +1,292 @@
The Lockronomicon
Your guide to the ancient and twisted locking policies of the tty layer and
the warped logic behind them. Beware all ye who read on.
FIXME: still need to work out the full set of BKL assumptions and document
them so they can eventually be killed off.
Line Discipline
---------------
Line disciplines are registered with tty_register_ldisc() passing the
discipline number and the ldisc structure. At the point of registration the
discipline must be ready to use and it is possible it will get used before
the call returns success. If the call returns an error then it won't get
called. Do not re-use ldisc numbers as they are part of the userspace ABI
and writing over an existing ldisc will cause demons to eat your computer.
After the return the ldisc data has been copied so you may free your own
copy of the structure. You must not re-register over the top of the line
discipline even with the same data or your computer again will be eaten by
demons.
In order to remove a line discipline call tty_unregister_ldisc().
In ancient times this always worked. In modern times the function will
return -EBUSY if the ldisc is currently in use. Since the ldisc referencing
code manages the module counts this should not usually be a concern.
Heed this warning: the reference count field of the registered copies of the
tty_ldisc structure in the ldisc table counts the number of lines using this
discipline. The reference count of the tty_ldisc structure within a tty
counts the number of active users of the ldisc at this instant. In effect it
counts the number of threads of execution within an ldisc method (plus those
about to enter and exit although this detail matters not).
Line Discipline Methods
-----------------------
TTY side interfaces:
open() - Called when the line discipline is attached to
the terminal. No other call into the line
discipline for this tty will occur until it
completes successfully. Can sleep.
close() - This is called on a terminal when the line
discipline is being unplugged. At the point of
execution no further users will enter the
ldisc code for this tty. Can sleep.
hangup() - Called when the tty line is hung up.
The line discipline should cease I/O to the tty.
No further calls into the ldisc code will occur.
Can sleep.
write() - A process is writing data through the line
discipline. Multiple write calls are serialized
by the tty layer for the ldisc. May sleep.
flush_buffer() - (optional) May be called at any point between
open and close, and instructs the line discipline
to empty its input buffer.
chars_in_buffer() - (optional) Report the number of bytes in the input
buffer.
set_termios() - (optional) Called on termios structure changes.
The caller passes the old termios data and the
current data is in the tty. Called under the
termios semaphore so allowed to sleep. Serialized
against itself only.
read() - Move data from the line discipline to the user.
Multiple read calls may occur in parallel and the
ldisc must deal with serialization issues. May
sleep.
poll() - Check the status for the poll/select calls. Multiple
poll calls may occur in parallel. May sleep.
ioctl() - Called when an ioctl is handed to the tty layer
that might be for the ldisc. Multiple ioctl calls
may occur in parallel. May sleep.
Driver Side Interfaces:
receive_buf() - Hand buffers of bytes from the driver to the ldisc
for processing. Semantics currently rather
mysterious 8(
write_wakeup() - May be called at any point between open and close.
The TTY_DO_WRITE_WAKEUP flag indicates if a call
is needed but always races versus calls. Thus the
ldisc must be careful about setting order and to
handle unexpected calls. Must not sleep.
The driver is forbidden from calling this directly
from the ->write call from the ldisc as the ldisc
is permitted to call the driver write method from
this function. In such a situation defer it.
Driver Access
Line discipline methods can call the following methods of the underlying
hardware driver through the function pointers within the tty->driver
structure:
write() Write a block of characters to the tty device.
Returns the number of characters accepted. The
character buffer passed to this method is already
in kernel space.
put_char() Queues a character for writing to the tty device.
If there is no room in the queue, the character is
ignored.
flush_chars() (Optional) If defined, must be called after
queueing characters with put_char() in order to
start transmission.
write_room() Returns the numbers of characters the tty driver
will accept for queueing to be written.
ioctl() Invoke device specific ioctl.
Expects data pointers to refer to userspace.
Returns ENOIOCTLCMD for unrecognized ioctl numbers.
set_termios() Notify the tty driver that the device's termios
settings have changed. New settings are in
tty->termios. Previous settings should be passed in
the "old" argument.
The API is defined such that the driver should return
the actual modes selected. This means that the
driver function is responsible for modifying any
bits in the request it cannot fulfill to indicate
the actual modes being used. A device with no
hardware capability for change (eg a USB dongle or
virtual port) can provide NULL for this method.
throttle() Notify the tty driver that input buffers for the
line discipline are close to full, and it should
somehow signal that no more characters should be
sent to the tty.
unthrottle() Notify the tty driver that characters can now be
sent to the tty without fear of overrunning the
input buffers of the line disciplines.
stop() Ask the tty driver to stop outputting characters
to the tty device.
start() Ask the tty driver to resume sending characters
to the tty device.
hangup() Ask the tty driver to hang up the tty device.
break_ctl() (Optional) Ask the tty driver to turn on or off
BREAK status on the RS-232 port. If state is -1,
then the BREAK status should be turned on; if
state is 0, then BREAK should be turned off.
If this routine is not implemented, use ioctls
TIOCSBRK / TIOCCBRK instead.
wait_until_sent() Waits until the device has written out all of the
characters in its transmitter FIFO.
send_xchar() Send a high-priority XON/XOFF character to the device.
Flags
Line discipline methods have access to tty->flags field containing the
following interesting flags:
TTY_THROTTLED Driver input is throttled. The ldisc should call
tty->driver->unthrottle() in order to resume
reception when it is ready to process more data.
TTY_DO_WRITE_WAKEUP If set, causes the driver to call the ldisc's
write_wakeup() method in order to resume
transmission when it can accept more data
to transmit.
TTY_IO_ERROR If set, causes all subsequent userspace read/write
calls on the tty to fail, returning -EIO.
TTY_OTHER_CLOSED Device is a pty and the other side has closed.
TTY_NO_WRITE_SPLIT Prevent driver from splitting up writes into
smaller chunks.
Locking
Callers to the line discipline functions from the tty layer are required to
take line discipline locks. The same is true of calls from the driver side
but not yet enforced.
Three calls are now provided
ldisc = tty_ldisc_ref(tty);
takes a handle to the line discipline in the tty and returns it. If no ldisc
is currently attached or the ldisc is being closed and re-opened at this
point then NULL is returned. While this handle is held the ldisc will not
change or go away.
tty_ldisc_deref(ldisc)
Returns the ldisc reference and allows the ldisc to be closed. Returning the
reference takes away your right to call the ldisc functions until you take
a new reference.
ldisc = tty_ldisc_ref_wait(tty);
Performs the same function as tty_ldisc_ref except that it will wait for an
ldisc change to complete and then return a reference to the new ldisc.
While these functions are slightly slower than the old code they should have
minimal impact as most receive logic uses the flip buffers and they only
need to take a reference when they push bits up through the driver.
A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc
functions are called with the ldisc unavailable. Thus tty_ldisc_ref will
fail in this situation if used within these functions. Ldisc and driver
code calling its own functions must be careful in this case.
Driver Interface
----------------
open() - Called when a device is opened. May sleep
close() - Called when a device is closed. At the point of
return from this call the driver must make no
further ldisc calls of any kind. May sleep
write() - Called to write bytes to the device. May not
sleep. May occur in parallel in special cases.
Because this includes panic paths drivers generally
shouldn't try and do clever locking here.
put_char() - Stuff a single character onto the queue. The
driver is guaranteed following up calls to
flush_chars.
flush_chars() - Ask the kernel to write put_char queue
write_room() - Return the number of characters tht can be stuffed
into the port buffers without overflow (or less).
The ldisc is responsible for being intelligent
about multi-threading of write_room/write calls
ioctl() - Called when an ioctl may be for the driver
set_termios() - Called on termios change, serialized against
itself by a semaphore. May sleep.
set_ldisc() - Notifier for discipline change. At the point this
is done the discipline is not yet usable. Can now
sleep (I think)
throttle() - Called by the ldisc to ask the driver to do flow
control. Serialization including with unthrottle
is the job of the ldisc layer.
unthrottle() - Called by the ldisc to ask the driver to stop flow
control.
stop() - Ldisc notifier to the driver to stop output. As with
throttle the serializations with start() are down
to the ldisc layer.
start() - Ldisc notifier to the driver to start output.
hangup() - Ask the tty driver to cause a hangup initiated
from the host side. [Can sleep ??]
break_ctl() - Send RS232 break. Can sleep. Can get called in
parallel, driver must serialize (for now), and
with write calls.
wait_until_sent() - Wait for characters to exit the hardware queue
of the driver. Can sleep
send_xchar() - Send XON/XOFF and if possible jump the queue with
it in order to get fast flow control responses.
Cannot sleep ??