lk/linux-kernel-test
1
0
Fork 0
Code Issues Pull Requests 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

24
Documentation/serial/00-INDEX Normal file
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.

8
Documentation/serial/README.cycladesZ Normal file
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/

522
Documentation/serial/computone.txt Normal file
View File

@@ -0,0 +1,522 @@
NOTE: This is an unmaintained driver. It is not guaranteed to work due to
changes made in the tty layer in 2.6. If you wish to take over maintenance of
this driver, contact Michael Warfield <mhw@wittsend.com>.
Changelog:
----------
11-01-2001: Original Document
10-29-2004: Minor misspelling & format fix, update status of driver.
James Nelson <james4765@gmail.com>
Computone Intelliport II/Plus Multiport Serial Driver
-----------------------------------------------------
Release Notes For Linux Kernel 2.2 and higher.
These notes are for the drivers which have already been integrated into the
kernel and have been tested on Linux kernels 2.0, 2.2, 2.3, and 2.4.
Version: 1.2.14
Date: 11/01/2001
Historical Author: Andrew Manison <amanison@america.net>
Primary Author: Doug McNash
Support: support@computone.com
Fixes and Updates: Mike Warfield <mhw@wittsend.com>
This file assumes that you are using the Computone drivers which are
integrated into the kernel sources. For updating the drivers or installing
drivers into kernels which do not already have Computone drivers, please
refer to the instructions in the README.computone file in the driver patch.
1. INTRODUCTION
This driver supports the entire family of Intelliport II/Plus controllers
with the exception of the MicroChannel controllers. It does not support
products previous to the Intelliport II.
This driver was developed on the v2.0.x Linux tree and has been tested up
to v2.4.14; it will probably not work with earlier v1.X kernels,.
2. QUICK INSTALLATION
Hardware - If you have an ISA card, find a free interrupt and io port.
List those in use with `cat /proc/interrupts` and
`cat /proc/ioports`. Set the card dip switches to a free
address. You may need to configure your BIOS to reserve an
irq for an ISA card. PCI and EISA parameters are set
automagically. Insert card into computer with the power off
before or after drivers installation.
Note the hardware address from the Computone ISA cards installed into
the system. These are required for editing ip2.c or editing
/etc/modprobe.conf, or for specification on the modprobe
command line.
Note that the /etc/modules.conf should be used for older (pre-2.6)
kernels.
Software -
Module installation:
a) Determine free irq/address to use if any (configure BIOS if need be)
b) Run "make config" or "make menuconfig" or "make xconfig"
Select (m) module for CONFIG_COMPUTONE under character
devices. CONFIG_PCI and CONFIG_MODULES also may need to be set.
c) Set address on ISA cards then:
edit /usr/src/linux/drivers/char/ip2.c if needed
or
edit /etc/modprobe.conf if needed (module).
or both to match this setting.
d) Run "make modules"
e) Run "make modules_install"
f) Run "/sbin/depmod -a"
g) install driver using `modprobe ip2 <options>` (options listed below)
h) run ip2mkdev (either the script below or the binary version)
Kernel installation:
a) Determine free irq/address to use if any (configure BIOS if need be)
b) Run "make config" or "make menuconfig" or "make xconfig"
Select (y) kernel for CONFIG_COMPUTONE under character
devices. CONFIG_PCI may need to be set if you have PCI bus.
c) Set address on ISA cards then:
edit /usr/src/linux/drivers/char/ip2.c
(Optional - may be specified on kernel command line now)
d) Run "make zImage" or whatever target you prefer.
e) mv /usr/src/linux/arch/i386/boot/zImage to /boot.
f) Add new config for this kernel into /etc/lilo.conf, run "lilo"
or copy to a floppy disk and boot from that floppy disk.
g) Reboot using this kernel
h) run ip2mkdev (either the script below or the binary version)
Kernel command line options:
When compiling the driver into the kernel, io and irq may be
compiled into the driver by editing ip2.c and setting the values for
io and irq in the appropriate array. An alternative is to specify
a command line parameter to the kernel at boot up.
ip2=io0,irq0,io1,irq1,io2,irq2,io3,irq3
Note that this order is very different from the specifications for the
modload parameters which have separate IRQ and IO specifiers.
The io port also selects PCI (1) and EISA (2) boards.
io=0 No board
io=1 PCI board
io=2 EISA board
else ISA board io address
You only need to specify the boards which are present.
Examples:
2 PCI boards:
ip2=1,0,1,0
1 ISA board at 0x310 irq 5:
ip2=0x310,5
This can be added to and "append" option in lilo.conf similar to this:
append="ip2=1,0,1,0"
3. INSTALLATION
Previously, the driver sources were packaged with a set of patch files
to update the character drivers' makefile and configuration file, and other
kernel source files. A build script (ip2build) was included which applies
the patches if needed, and build any utilities needed.
What you receive may be a single patch file in conventional kernel
patch format build script. That form can also be applied by
running patch -p1 < ThePatchFile. Otherwise run ip2build.
The 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. If the driver is built
into the kernel you will need to edit the file ip2.c to match the boards
you are installing. See that file for instructions. If the driver is
installed as a module the configuration can also be specified on the
modprobe command line as follows:
modprobe ip2 irq=irq1,irq2,irq3,irq4 io=addr1,addr2,addr3,addr4
where irqnum is one of the valid Intelliport II interrupts (3,4,5,7,10,11,
12,15) and addr1-4 are the base addresses for up to four controllers. If
the irqs are not specified the driver uses the default in ip2.c (which
selects polled mode). If no base addresses are specified the defaults in
ip2.c are used. If you are autoloading the driver module with kerneld or
kmod the base addresses and interrupt number must also be set in ip2.c
and recompile or just insert and options line in /etc/modprobe.conf or both.
The options line is equivalent to the command line and takes precedence over
what is in ip2.c.
/etc/modprobe.conf sample:
options ip2 io=1,0x328 irq=1,10
alias char-major-71 ip2
alias char-major-72 ip2
alias char-major-73 ip2
The equivalent in ip2.c:
static int io[IP2_MAX_BOARDS]= { 1, 0x328, 0, 0 };
static int irq[IP2_MAX_BOARDS] = { 1, 10, -1, -1 };
The equivalent for the kernel command line (in lilo.conf):
append="ip2=1,1,0x328,10"
Note: Both io and irq should be updated to reflect YOUR system. An "io"
address of 1 or 2 indicates a PCI or EISA card in the board table.
The PCI or EISA irq will be assigned automatically.
Specifying an invalid or in-use irq will default the driver into
running in polled mode for that card. If all irq entries are 0 then
all cards will operate in polled mode.
If you select the driver as part of the kernel run :
make zlilo (or whatever you do to create a bootable kernel)
If you selected a module run :
make modules && make modules_install
The utility ip2mkdev (see 5 and 7 below) creates all the device nodes
required by the driver. For a device to be created it must be configured
in the driver and the board must be installed. Only devices corresponding
to real IntelliPort II ports are created. With multiple boards and expansion
boxes this will leave gaps in the sequence of device names. ip2mkdev uses
Linux tty naming conventions: ttyF0 - ttyF255 for normal devices, and
cuf0 - cuf255 for callout devices.
4. USING THE DRIVERS
As noted above, the driver implements the ports in accordance with Linux
conventions, and the devices should be interchangeable with the standard
serial devices. (This is a key point for problem reporting: please make
sure that what you are trying do works on the ttySx/cuax ports first; then
tell us what went wrong with the ip2 ports!)
Higher speeds can be obtained using the setserial utility which remaps
38,400 bps (extb) to 57,600 bps, 115,200 bps, or a custom speed.
Intelliport II installations using the PowerPort expansion module can
use the custom speed setting to select the highest speeds: 153,600 bps,
230,400 bps, 307,200 bps, 460,800bps and 921,600 bps. The base for
custom baud rate configuration is fixed at 921,600 for cards/expansion
modules with ST654's and 115200 for those with Cirrus CD1400's. This
corresponds to the maximum bit rates those chips are capable.
For example if the baud base is 921600 and the baud divisor is 18 then
the custom rate is 921600/18 = 51200 bps. See the setserial man page for
complete details. Of course if stty accepts the higher rates now you can
use that as well as the standard ioctls().
5. ip2mkdev and assorted utilities...
Several utilities, including the source for a binary ip2mkdev utility are
available under .../drivers/char/ip2. These can be build by changing to
that directory and typing "make" after the kernel has be built. If you do
not wish to compile the binary utilities, the shell script below can be
cut out and run as "ip2mkdev" to create the necessary device files. To
use the ip2mkdev script, you must have procfs enabled and the proc file
system mounted on /proc.
6. NOTES
This is a release version of the driver, but it is impossible to test it
in all configurations of Linux. If there is any anomalous behaviour that
does not match the standard serial port's behaviour please let us know.
7. ip2mkdev shell script
Previously, this script was simply attached here. It is now attached as a
shar archive to make it easier to extract the script from the documentation.
To create the ip2mkdev shell script change to a convenient directory (/tmp
works just fine) and run the following command:
unshar Documentation/serial/computone.txt
(This file)
You should now have a file ip2mkdev in your current working directory with
permissions set to execute. Running that script with then create the
necessary devices for the Computone boards, interfaces, and ports which
are present on you system at the time it is run.
#!/bin/sh
# This is a shell archive (produced by GNU sharutils 4.2.1).
# To extract the files from this archive, save it to some FILE, remove
# everything before the `!/bin/sh' line above, then type `sh FILE'.
#
# Made on 2001-10-29 10:32 EST by <mhw@alcove.wittsend.com>.
# Source directory was `/home2/src/tmp'.
#
# Existing files will *not* be overwritten unless `-c' is specified.
#
# This shar contains:
# length mode name
# ------ ---------- ------------------------------------------
# 4251 -rwxr-xr-x ip2mkdev
#
save_IFS="${IFS}"
IFS="${IFS}:"
gettext_dir=FAILED
locale_dir=FAILED
first_param="$1"
for dir in $PATH
do
if test "$gettext_dir" = FAILED && test -f $dir/gettext \
&& ($dir/gettext --version >/dev/null 2>&1)
then
set `$dir/gettext --version 2>&1`
if test "$3" = GNU
then
gettext_dir=$dir
fi
fi
if test "$locale_dir" = FAILED && test -f $dir/shar \
&& ($dir/shar --print-text-domain-dir >/dev/null 2>&1)
then
locale_dir=`$dir/shar --print-text-domain-dir`
fi
done
IFS="$save_IFS"
if test "$locale_dir" = FAILED || test "$gettext_dir" = FAILED
then
echo=echo
else
TEXTDOMAINDIR=$locale_dir
export TEXTDOMAINDIR
TEXTDOMAIN=sharutils
export TEXTDOMAIN
echo="$gettext_dir/gettext -s"
fi
if touch -am -t 200112312359.59 $$.touch >/dev/null 2>&1 && test ! -f 200112312359.59 -a -f $$.touch; then
shar_touch='touch -am -t $1$2$3$4$5$6.$7 "$8"'
elif touch -am 123123592001.59 $$.touch >/dev/null 2>&1 && test ! -f 123123592001.59 -a ! -f 123123592001.5 -a -f $$.touch; then
shar_touch='touch -am $3$4$5$6$1$2.$7 "$8"'
elif touch -am 1231235901 $$.touch >/dev/null 2>&1 && test ! -f 1231235901 -a -f $$.touch; then
shar_touch='touch -am $3$4$5$6$2 "$8"'
else
shar_touch=:
echo
$echo 'WARNING: not restoring timestamps. Consider getting and'
$echo "installing GNU \`touch', distributed in GNU File Utilities..."
echo
fi
rm -f 200112312359.59 123123592001.59 123123592001.5 1231235901 $$.touch
#
if mkdir _sh17581; then
$echo 'x -' 'creating lock directory'
else
$echo 'failed to create lock directory'
exit 1
fi
# ============= ip2mkdev ==============
if test -f 'ip2mkdev' && test "$first_param" != -c; then
$echo 'x -' SKIPPING 'ip2mkdev' '(file already exists)'
else
$echo 'x -' extracting 'ip2mkdev' '(text)'
sed 's/^X//' << 'SHAR_EOF' > 'ip2mkdev' &&
#!/bin/sh -
#
# ip2mkdev
#
# Make or remove devices as needed for Computone Intelliport drivers
#
# First rule! If the dev file exists and you need it, don't mess
# with it. That prevents us from screwing up open ttys, ownership
# and permissions on a running system!
#
# This script will NOT remove devices that no longer exist if their
# board or interface box has been removed. If you want to get rid
# of them, you can manually do an "rm -f /dev/ttyF* /dev/cuaf*"
# before running this script. Running this script will then recreate
# all the valid devices.
#
# Michael H. Warfield
# /\/\|=mhw=|\/\/
# mhw@wittsend.com
#
# Updated 10/29/2000 for version 1.2.13 naming convention
# under devfs. /\/\|=mhw=|\/\/
#
# Updated 03/09/2000 for devfs support in ip2 drivers. /\/\|=mhw=|\/\/
#
X
if test -d /dev/ip2 ; then
# This is devfs mode... We don't do anything except create symlinks
# from the real devices to the old names!
X cd /dev
X echo "Creating symbolic links to devfs devices"
X for i in `ls ip2` ; do
X if test ! -L ip2$i ; then
X # Remove it incase it wasn't a symlink (old device)
X rm -f ip2$i
X ln -s ip2/$i ip2$i
X fi
X done
X for i in `( cd tts ; ls F* )` ; do
X if test ! -L tty$i ; then
X # Remove it incase it wasn't a symlink (old device)
X rm -f tty$i
X ln -s tts/$i tty$i
X fi
X done
X for i in `( cd cua ; ls F* )` ; do
X DEVNUMBER=`expr $i : 'F\(.*\)'`
X if test ! -L cuf$DEVNUMBER ; then
X # Remove it incase it wasn't a symlink (old device)
X rm -f cuf$DEVNUMBER
X ln -s cua/$i cuf$DEVNUMBER
X fi
X done
X exit 0
fi
X
if test ! -f /proc/tty/drivers
then
X echo "\
Unable to check driver status.
Make sure proc file system is mounted."
X
X exit 255
fi
X
if test ! -f /proc/tty/driver/ip2
then
X echo "\
Unable to locate ip2 proc file.
Attempting to load driver"
X
X if /sbin/insmod ip2
X then
X if test ! -f /proc/tty/driver/ip2
X then
X echo "\
Unable to locate ip2 proc file after loading driver.
Driver initialization failure or driver version error.
"
X exit 255
X fi
X else
X echo "Unable to load ip2 driver."
X exit 255
X fi
fi
X
# Ok... So we got the driver loaded and we can locate the procfs files.
# Next we need our major numbers.
X
TTYMAJOR=`sed -e '/^ip2/!d' -e '/\/dev\/tt/!d' -e 's/.*tt[^ ]*[ ]*\([0-9]*\)[ ]*.*/\1/' < /proc/tty/drivers`
CUAMAJOR=`sed -e '/^ip2/!d' -e '/\/dev\/cu/!d' -e 's/.*cu[^ ]*[ ]*\([0-9]*\)[ ]*.*/\1/' < /proc/tty/drivers`
BRDMAJOR=`sed -e '/^Driver: /!d' -e 's/.*IMajor=\([0-9]*\)[ ]*.*/\1/' < /proc/tty/driver/ip2`
X
echo "\
TTYMAJOR = $TTYMAJOR
CUAMAJOR = $CUAMAJOR
BRDMAJOR = $BRDMAJOR
"
X
# Ok... Now we should know our major numbers, if appropriate...
# Now we need our boards and start the device loops.
X
grep '^Board [0-9]:' /proc/tty/driver/ip2 | while read token number type alltherest
do
X # The test for blank "type" will catch the stats lead-in lines
X # if they exist in the file
X if test "$type" = "vacant" -o "$type" = "Vacant" -o "$type" = ""
X then
X continue
X fi
X
X BOARDNO=`expr "$number" : '\([0-9]\):'`
X PORTS=`expr "$alltherest" : '.*ports=\([0-9]*\)' | tr ',' ' '`
X MINORS=`expr "$alltherest" : '.*minors=\([0-9,]*\)' | tr ',' ' '`
X
X if test "$BOARDNO" = "" -o "$PORTS" = ""
X then
# This may be a bug. We should at least get this much information
X echo "Unable to process board line"
X continue
X fi
X
X if test "$MINORS" = ""
X then
# Silently skip this one. This board seems to have no boxes
X continue
X fi
X
X echo "board $BOARDNO: $type ports = $PORTS; port numbers = $MINORS"
X
X if test "$BRDMAJOR" != ""
X then
X BRDMINOR=`expr $BOARDNO \* 4`
X STSMINOR=`expr $BRDMINOR + 1`
X if test ! -c /dev/ip2ipl$BOARDNO ; then
X mknod /dev/ip2ipl$BOARDNO c $BRDMAJOR $BRDMINOR
X fi
X if test ! -c /dev/ip2stat$BOARDNO ; then
X mknod /dev/ip2stat$BOARDNO c $BRDMAJOR $STSMINOR
X fi
X fi
X
X if test "$TTYMAJOR" != ""
X then
X PORTNO=$BOARDBASE
X
X for PORTNO in $MINORS
X do
X if test ! -c /dev/ttyF$PORTNO ; then
X # We got the hardware but no device - make it
X mknod /dev/ttyF$PORTNO c $TTYMAJOR $PORTNO
X fi
X done
X fi
X
X if test "$CUAMAJOR" != ""
X then
X PORTNO=$BOARDBASE
X
X for PORTNO in $MINORS
X do
X if test ! -c /dev/cuf$PORTNO ; then
X # We got the hardware but no device - make it
X mknod /dev/cuf$PORTNO c $CUAMAJOR $PORTNO
X fi
X done
X fi
done
X
Xexit 0
SHAR_EOF
(set 20 01 10 29 10 32 01 'ip2mkdev'; eval "$shar_touch") &&
chmod 0755 'ip2mkdev' ||
$echo 'restore of' 'ip2mkdev' 'failed'
if ( md5sum --help 2>&1 | grep 'sage: md5sum \[' ) >/dev/null 2>&1 \
&& ( md5sum --version 2>&1 | grep -v 'textutils 1.12' ) >/dev/null; then
md5sum -c << SHAR_EOF >/dev/null 2>&1 \
|| $echo 'ip2mkdev:' 'MD5 check failed'
cb5717134509f38bad9fde6b1f79b4a4 ip2mkdev
SHAR_EOF
else
shar_count="`LC_ALL= LC_CTYPE= LANG= wc -c < 'ip2mkdev'`"
test 4251 -eq "$shar_count" ||
$echo 'ip2mkdev:' 'original size' '4251,' 'current size' "$shar_count!"
fi
fi
rm -fr _sh17581
exit 0

98
Documentation/serial/digiepca.txt Normal file
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

154
Documentation/serial/hayes-esp.txt Normal file
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>

523
Documentation/serial/moxa-smartio Normal file
View File

@@ -0,0 +1,523 @@
=============================================================================
MOXA Smartio/Industio Family Device Driver Installation Guide
for Linux Kernel 2.4.x, 2.6.x
Copyright (C) 2008, Moxa Inc.
=============================================================================
Date: 01/21/2008
Content
1. Introduction
2. System Requirement
3. Installation
3.1 Hardware installation
3.2 Driver files
3.3 Device naming convention
3.4 Module driver configuration
3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x.
3.6 Custom configuration
3.7 Verify driver installation
4. Utilities
5. Setserial
6. Troubleshooting
-----------------------------------------------------------------------------
1. Introduction
The Smartio/Industio/UPCI family Linux driver supports following multiport
boards.
- 2 ports multiport board
CP-102U, CP-102UL, CP-102UF
CP-132U-I, CP-132UL,
CP-132, CP-132I, CP132S, CP-132IS,
CI-132, CI-132I, CI-132IS,
(C102H, C102HI, C102HIS, C102P, CP-102, CP-102S)
- 4 ports multiport board
CP-104EL,
CP-104UL, CP-104JU,
CP-134U, CP-134U-I,
C104H/PCI, C104HS/PCI,
CP-114, CP-114I, CP-114S, CP-114IS, CP-114UL,
C104H, C104HS,
CI-104J, CI-104JS,
CI-134, CI-134I, CI-134IS,
(C114HI, CT-114I, C104P)
POS-104UL,
CB-114,
CB-134I
- 8 ports multiport board
CP-118EL, CP-168EL,
CP-118U, CP-168U,
C168H/PCI,
C168H, C168HS,
(C168P),
CB-108
This driver and installation procedure have been developed upon Linux Kernel
2.4.x and 2.6.x. This driver supports Intel x86 hardware platform. In order
to maintain compatibility, this version has also been properly tested with
RedHat, Mandrake, Fedora and S.u.S.E Linux. However, if compatibility problem
occurs, please contact Moxa at support@moxa.com.tw.
In addition to device driver, useful utilities are also provided in this
version. They are
- msdiag Diagnostic program for displaying installed Moxa
Smartio/Industio boards.
- msmon Monitor program to observe data count and line status signals.
- msterm A simple terminal program which is useful in testing serial
ports.
- io-irq.exe Configuration program to setup ISA boards. Please note that
this program can only be executed under DOS.
All the drivers and utilities are published in form of source code under
GNU General Public License in this version. Please refer to GNU General
Public License announcement in each source code file for more detail.
In Moxa's Web sites, you may always find latest driver at http://web.moxa.com.
This version of driver can be installed as Loadable Module (Module driver)
or built-in into kernel (Static driver). You may refer to following
installation procedure for suitable one. Before you install the driver,
please refer to hardware installation procedure in the User's Manual.
We assume the user should be familiar with following documents.
- Serial-HOWTO
- Kernel-HOWTO
-----------------------------------------------------------------------------
2. System Requirement
- Hardware platform: Intel x86 machine
- Kernel version: 2.4.x or 2.6.x
- gcc version 2.72 or later
- Maximum 4 boards can be installed in combination
-----------------------------------------------------------------------------
3. Installation
3.1 Hardware installation
3.2 Driver files
3.3 Device naming convention
3.4 Module driver configuration
3.5 Static driver configuration for Linux kernel 2.4.x, 2.6.x.
3.6 Custom configuration
3.7 Verify driver installation
3.1 Hardware installation
There are two types of buses, ISA and PCI, for Smartio/Industio
family multiport board.
ISA board
---------
You'll have to configure CAP address, I/O address, Interrupt Vector
as well as IRQ before installing this driver. Please refer to hardware
installation procedure in User's Manual before proceed any further.
Please make sure the JP1 is open after the ISA board is set properly.
PCI/UPCI board
--------------
You may need to adjust IRQ usage in BIOS to avoid from IRQ conflict
with other ISA devices. Please refer to hardware installation
procedure in User's Manual in advance.
PCI IRQ Sharing
-----------
Each port within the same multiport board shares the same IRQ. Up to
4 Moxa Smartio/Industio PCI Family multiport boards can be installed
together on one system and they can share the same IRQ.
3.2 Driver files
The driver file may be obtained from ftp, CD-ROM or floppy disk. The
first step, anyway, is to copy driver file "mxser.tgz" into specified
directory. e.g. /moxa. The execute commands as below.
# cd /
# mkdir moxa
# cd /moxa
# tar xvf /dev/fd0
or
# cd /
# mkdir moxa
# cd /moxa
# cp /mnt/cdrom/<driver directory>/mxser.tgz .
# tar xvfz mxser.tgz
3.3 Device naming convention
You may find all the driver and utilities files in /moxa/mxser.
Following installation procedure depends on the model you'd like to
run the driver. If you prefer module driver, please refer to 3.4.
If static driver is required, please refer to 3.5.
Dialin and callout port
-----------------------
This driver remains traditional serial device properties. There are
two special file name for each serial port. One is dial-in port
which is named "ttyMxx". For callout port, the naming convention
is "cumxx".
Device naming when more than 2 boards installed
-----------------------------------------------
Naming convention for each Smartio/Industio multiport board is
pre-defined as below.
Board Num. Dial-in Port Callout port
1st board ttyM0 - ttyM7 cum0 - cum7
2nd board ttyM8 - ttyM15 cum8 - cum15
3rd board ttyM16 - ttyM23 cum16 - cum23
4th board ttyM24 - ttym31 cum24 - cum31
!!!!!!!!!!!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Under Kernel 2.6 the cum Device is Obsolete. So use ttyM*
device instead.
!!!!!!!!!!!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Board sequence
--------------
This driver will activate ISA boards according to the parameter set
in the driver. After all specified ISA board activated, PCI board
will be installed in the system automatically driven.
Therefore the board number is sorted by the CAP address of ISA boards.
For PCI boards, their sequence will be after ISA boards and C168H/PCI
has higher priority than C104H/PCI boards.
3.4 Module driver configuration
Module driver is easiest way to install. If you prefer static driver
installation, please skip this paragraph.
------------- Prepare to use the MOXA driver--------------------
3.4.1 Create tty device with correct major number
Before using MOXA driver, your system must have the tty devices
which are created with driver's major number. We offer one shell
script "msmknod" to simplify the procedure.
This step is only needed to be executed once. But you still
need to do this procedure when:
a. You change the driver's major number. Please refer the "3.7"
section.
b. Your total installed MOXA boards number is changed. Maybe you
add/delete one MOXA board.
c. You want to change the tty name. This needs to modify the
shell script "msmknod"
The procedure is:
# cd /moxa/mxser/driver
# ./msmknod
This shell script will require the major number for dial-in
device and callout device to create tty device. You also need
to specify the total installed MOXA board number. Default major
numbers for dial-in device and callout device are 30, 35. If
you need to change to other number, please refer section "3.7"
for more detailed procedure.
Msmknod will delete any special files occupying the same device
naming.
3.4.2 Build the MOXA driver and utilities
Before using the MOXA driver and utilities, you need compile the
all the source code. This step is only need to be executed once.
But you still re-compile the source code if you modify the source
code. For example, if you change the driver's major number (see
"3.7" section), then you need to do this step again.
Find "Makefile" in /moxa/mxser, then run
# make clean; make install
!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!
For Red Hat 9, Red Hat Enterprise Linux AS3/ES3/WS3 & Fedora Core1:
# make clean; make installsp1
For Red Hat Enterprise Linux AS4/ES4/WS4:
# make clean; make installsp2
!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!
The driver files "mxser.o" and utilities will be properly compiled
and copied to system directories respectively.
------------- Load MOXA driver--------------------
3.4.3 Load the MOXA driver
# modprobe mxser <argument>
will activate the module driver. You may run "lsmod" to check
if "mxser" is activated. If the MOXA board is ISA board, the
<argument> is needed. Please refer to section "3.4.5" for more
information.
------------- Load MOXA driver on boot --------------------
3.4.4 For the above description, you may manually execute
"modprobe mxser" to activate this driver and run
"rmmod mxser" to remove it.
However, it's better to have a boot time configuration to
eliminate manual operation. Boot time configuration can be
achieved by rc file. We offer one "rc.mxser" file to simplify
the procedure under "moxa/mxser/driver".
But if you use ISA board, please modify the "modprobe ..." command
to add the argument (see "3.4.5" section). After modifying the
rc.mxser, please try to execute "/moxa/mxser/driver/rc.mxser"
manually to make sure the modification is ok. If any error
encountered, please try to modify again. If the modification is
completed, follow the below step.
Run following command for setting rc files.
# cd /moxa/mxser/driver
# cp ./rc.mxser /etc/rc.d
# cd /etc/rc.d
Check "rc.serial" is existed or not. If "rc.serial" doesn't exist,
create it by vi, run "chmod 755 rc.serial" to change the permission.
Add "/etc/rc.d/rc.mxser" in last line,
Reboot and check if moxa.o activated by "lsmod" command.
3.4.5. If you'd like to drive Smartio/Industio ISA boards in the system,
you'll have to add parameter to specify CAP address of given
board while activating "mxser.o". The format for parameters are
as follows.
modprobe mxser ioaddr=0x???,0x???,0x???,0x???
| | | |
| | | +- 4th ISA board
| | +------ 3rd ISA board
| +------------ 2nd ISA board
+------------------- 1st ISA board
3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x
Note: To use static driver, you must install the linux kernel
source package.
3.5.1 Backup the built-in driver in the kernel.
# cd /usr/src/linux/drivers/char
# mv mxser.c mxser.c.old
For Red Hat 7.x user, you need to create link:
# cd /usr/src
# ln -s linux-2.4 linux
3.5.2 Create link
# cd /usr/src/linux/drivers/char
# ln -s /moxa/mxser/driver/mxser.c mxser.c
3.5.3 Add CAP address list for ISA boards. For PCI boards user,
please skip this step.
In module mode, the CAP address for ISA board is given by
parameter. In static driver configuration, you'll have to
assign it within driver's source code. If you will not
install any ISA boards, you may skip to next portion.
The instructions to modify driver source code are as
below.
a. # cd /moxa/mxser/driver
# vi mxser.c
b. Find the array mxserBoardCAP[] as below.
static int mxserBoardCAP[]
= {0x00, 0x00, 0x00, 0x00};
c. Change the address within this array using vi. For
example, to driver 2 ISA boards with CAP address
0x280 and 0x180 as 1st and 2nd board. Just to change
the source code as follows.
static int mxserBoardCAP[]
= {0x280, 0x180, 0x00, 0x00};
3.5.4 Setup kernel configuration
Configure the kernel:
# cd /usr/src/linux
# make menuconfig
You will go into a menu-driven system. Please select [Character
devices][Non-standard serial port support], enable the [Moxa
SmartIO support] driver with "[*]" for built-in (not "[M]"), then
select [Exit] to exit this program.
3.5.5 Rebuild kernel
The following are for Linux kernel rebuilding, for your
reference only.
For appropriate details, please refer to the Linux document.
a. cd /usr/src/linux
b. make clean /* take a few minutes */
c. make dep /* take a few minutes */
d. make bzImage /* take probably 10-20 minutes */
e. make install /* copy boot image to correct position */
f. Please make sure the boot kernel (vmlinuz) is in the
correct position.
g. If you use 'lilo' utility, you should check /etc/lilo.conf
'image' item specified the path which is the 'vmlinuz' path,
or you will load wrong (or old) boot kernel image (vmlinuz).
After checking /etc/lilo.conf, please run "lilo".
Note that if the result of "make bzImage" is ERROR, then you have to
go back to Linux configuration Setup. Type "make menuconfig" in
directory /usr/src/linux.
3.5.6 Make tty device and special file
# cd /moxa/mxser/driver
# ./msmknod
3.5.7 Make utility
# cd /moxa/mxser/utility
# make clean; make install
3.5.8 Reboot
3.6 Custom configuration
Although this driver already provides you default configuration, you
still can change the device name and major number. The instruction to
change these parameters are shown as below.
Change Device name
------------------
If you'd like to use other device names instead of default naming
convention, all you have to do is to modify the internal code
within the shell script "msmknod". First, you have to open "msmknod"
by vi. Locate each line contains "ttyM" and "cum" and change them
to the device name you desired. "msmknod" creates the device names
you need next time executed.
Change Major number
-------------------
If major number 30 and 35 had been occupied, you may have to select
2 free major numbers for this driver. There are 3 steps to change
major numbers.
3.6.1 Find free major numbers
In /proc/devices, you may find all the major numbers occupied
in the system. Please select 2 major numbers that are available.
e.g. 40, 45.
3.6.2 Create special files
Run /moxa/mxser/driver/msmknod to create special files with
specified major numbers.
3.6.3 Modify driver with new major number
Run vi to open /moxa/mxser/driver/mxser.c. Locate the line
contains "MXSERMAJOR". Change the content as below.
#define MXSERMAJOR 40
#define MXSERCUMAJOR 45
3.6.4 Run "make clean; make install" in /moxa/mxser/driver.
3.7 Verify driver installation
You may refer to /var/log/messages to check the latest status
log reported by this driver whenever it's activated.
-----------------------------------------------------------------------------
4. Utilities
There are 3 utilities contained in this driver. They are msdiag, msmon and
msterm. These 3 utilities are released in form of source code. They should
be compiled into executable file and copied into /usr/bin.
Before using these utilities, please load driver (refer 3.4 & 3.5) and
make sure you had run the "msmknod" utility.
msdiag - Diagnostic
--------------------
This utility provides the function to display what Moxa Smartio/Industio
board found by driver in the system.
msmon - Port Monitoring
-----------------------
This utility gives the user a quick view about all the MOXA ports'
activities. One can easily learn each port's total received/transmitted
(Rx/Tx) character count since the time when the monitoring is started.
Rx/Tx throughputs per second are also reported in interval basis (e.g.
the last 5 seconds) and in average basis (since the time the monitoring
is started). You can reset all ports' count by <HOME> key. <+> <->
(plus/minus) keys to change the displaying time interval. Press <ENTER>
on the port, that cursor stay, to view the port's communication
parameters, signal status, and input/output queue.
msterm - Terminal Emulation
---------------------------
This utility provides data sending and receiving ability of all tty ports,
especially for MOXA ports. It is quite useful for testing simple
application, for example, sending AT command to a modem connected to the
port or used as a terminal for login purpose. Note that this is only a
dumb terminal emulation without handling full screen operation.
-----------------------------------------------------------------------------
5. Setserial
Supported Setserial parameters are listed as below.
uart set UART type(16450-->disable FIFO, 16550A-->enable FIFO)
close_delay set the amount of time(in 1/100 of a second) that DTR
should be kept low while being closed.
closing_wait set the amount of time(in 1/100 of a second) that the
serial port should wait for data to be drained while
being closed, before the receiver is disable.
spd_hi Use 57.6kb when the application requests 38.4kb.
spd_vhi Use 115.2kb when the application requests 38.4kb.
spd_shi Use 230.4kb when the application requests 38.4kb.
spd_warp Use 460.8kb when the application requests 38.4kb.
spd_normal Use 38.4kb when the application requests 38.4kb.
spd_cust Use the custom divisor to set the speed when the
application requests 38.4kb.
divisor This option set the custom divison.
baud_base This option set the base baud rate.
-----------------------------------------------------------------------------
6. Troubleshooting
The boot time error messages and solutions are stated as clearly as
possible. If all the possible solutions fail, please contact our technical
support team to get more help.
Error msg: More than 4 Moxa Smartio/Industio family boards found. Fifth board
and after are ignored.
Solution:
To avoid this problem, please unplug fifth and after board, because Moxa
driver supports up to 4 boards.
Error msg: Request_irq fail, IRQ(?) may be conflict with another device.
Solution:
Other PCI or ISA devices occupy the assigned IRQ. If you are not sure
which device causes the situation, please check /proc/interrupts to find
free IRQ and simply change another free IRQ for Moxa board.
Error msg: Board #: C1xx Series(CAP=xxx) interrupt number invalid.
Solution:
Each port within the same multiport board shares the same IRQ. Please set
one IRQ (IRQ doesn't equal to zero) for one Moxa board.
Error msg: No interrupt vector be set for Moxa ISA board(CAP=xxx).
Solution:
Moxa ISA board needs an interrupt vector.Please refer to user's manual
"Hardware Installation" chapter to set interrupt vector.
Error msg: Couldn't install MOXA Smartio/Industio family driver!
Solution:
Load Moxa driver fail, the major number may conflict with other devices.
Please refer to previous section 3.7 to change a free major number for
Moxa driver.
Error msg: Couldn't install MOXA Smartio/Industio family callout driver!
Solution:
Load Moxa callout driver fail, the callout device major number may
conflict with other devices. Please refer to previous section 3.7 to
change a free callout device major number for Moxa driver.
-----------------------------------------------------------------------------

36
Documentation/serial/riscom8.txt Normal file
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.

189
Documentation/serial/rocket.txt Normal file
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
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

383
Documentation/serial/specialix.txt Normal file
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?

392
Documentation/serial/stallion.txt Normal file
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.

294
Documentation/serial/sx.txt Normal file
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)

292
Documentation/serial/tty.txt Normal file
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 ??