diff options
Diffstat (limited to 'Documentation/serial')
| -rw-r--r-- | Documentation/serial/00-INDEX | 26 | ||||
| -rw-r--r-- | Documentation/serial/README.cycladesZ | 8 | ||||
| -rw-r--r-- | Documentation/serial/computone.txt | 520 | ||||
| -rw-r--r-- | Documentation/serial/digiepca.txt | 98 | ||||
| -rw-r--r-- | Documentation/serial/driver | 397 | ||||
| -rw-r--r-- | Documentation/serial/moxa-smartio | 523 | ||||
| -rw-r--r-- | Documentation/serial/n_gsm.txt | 89 | ||||
| -rw-r--r-- | Documentation/serial/riscom8.txt | 36 | ||||
| -rw-r--r-- | Documentation/serial/rocket.txt | 189 | ||||
| -rw-r--r-- | Documentation/serial/serial-rs485.txt | 136 | ||||
| -rw-r--r-- | Documentation/serial/specialix.txt | 383 | ||||
| -rw-r--r-- | Documentation/serial/stallion.txt | 392 | ||||
| -rw-r--r-- | Documentation/serial/sx.txt | 294 | ||||
| -rw-r--r-- | Documentation/serial/tty.txt | 301 |
14 files changed, 3392 insertions, 0 deletions
diff --git a/Documentation/serial/00-INDEX b/Documentation/serial/00-INDEX new file mode 100644 index 00000000..e09468ad --- /dev/null +++ b/Documentation/serial/00-INDEX @@ -0,0 +1,26 @@ +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. +serial-rs485.txt + - info about RS485 structures and support in the kernel. +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. diff --git a/Documentation/serial/README.cycladesZ b/Documentation/serial/README.cycladesZ new file mode 100644 index 00000000..024a6944 --- /dev/null +++ b/Documentation/serial/README.cycladesZ @@ -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/ + diff --git a/Documentation/serial/computone.txt b/Documentation/serial/computone.txt new file mode 100644 index 00000000..a6a1158e --- /dev/null +++ b/Documentation/serial/computone.txt @@ -0,0 +1,520 @@ +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 + +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.d/*.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 config file in /etc/modprobe.d/ 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/x86/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.d/*.conf or both. +The options line is equivalent to the command line and takes precedence over +what is in ip2.c. + +config sample to put /etc/modprobe.d/*.conf: + 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 diff --git a/Documentation/serial/digiepca.txt b/Documentation/serial/digiepca.txt new file mode 100644 index 00000000..f2560e22 --- /dev/null +++ b/Documentation/serial/digiepca.txt @@ -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 diff --git a/Documentation/serial/driver b/Documentation/serial/driver new file mode 100644 index 00000000..0a25a919 --- /dev/null +++ b/Documentation/serial/driver @@ -0,0 +1,397 @@ + + Low Level Serial API + -------------------- + + +This document is meant as a brief overview of some aspects of the new serial +driver. It is not complete, any questions you have should be directed to +<rmk@arm.linux.org.uk> + +The reference implementation is contained within amba_pl011.c. + + + +Low Level Serial Hardware Driver +-------------------------------- + +The low level serial hardware driver is responsible for supplying port +information (defined by uart_port) and a set of control methods (defined +by uart_ops) to the core serial driver. The low level driver is also +responsible for handling interrupts for the port, and providing any +console support. + + +Console Support +--------------- + +The serial core provides a few helper functions. This includes identifing +the correct port structure (via uart_get_console) and decoding command line +arguments (uart_parse_options). + +There is also a helper function (uart_write_console) which performs a +character by character write, translating newlines to CRLF sequences. +Driver writers are recommended to use this function rather than implementing +their own version. + + +Locking +------- + +It is the responsibility of the low level hardware driver to perform the +necessary locking using port->lock. There are some exceptions (which +are described in the uart_ops listing below.) + +There are three locks. A per-port spinlock, a per-port tmpbuf semaphore, +and an overall semaphore. + +From the core driver perspective, the port->lock locks the following +data: + + port->mctrl + port->icount + info->xmit.head (circ->head) + info->xmit.tail (circ->tail) + +The low level driver is free to use this lock to provide any additional +locking. + +The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded +access to the info->tmpbuf bouncebuffer used for port writes. + +The port_sem semaphore is used to protect against ports being added/ +removed or reconfigured at inappropriate times. + + +uart_ops +-------- + +The uart_ops structure is the main interface between serial_core and the +hardware specific driver. It contains all the methods to control the +hardware. + + tx_empty(port) + This function tests whether the transmitter fifo and shifter + for the port described by 'port' is empty. If it is empty, + this function should return TIOCSER_TEMT, otherwise return 0. + If the port does not support this operation, then it should + return TIOCSER_TEMT. + + Locking: none. + Interrupts: caller dependent. + This call must not sleep + + set_mctrl(port, mctrl) + This function sets the modem control lines for port described + by 'port' to the state described by mctrl. The relevant bits + of mctrl are: + - TIOCM_RTS RTS signal. + - TIOCM_DTR DTR signal. + - TIOCM_OUT1 OUT1 signal. + - TIOCM_OUT2 OUT2 signal. + - TIOCM_LOOP Set the port into loopback mode. + If the appropriate bit is set, the signal should be driven + active. If the bit is clear, the signal should be driven + inactive. + + Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep + + get_mctrl(port) + Returns the current state of modem control inputs. The state + of the outputs should not be returned, since the core keeps + track of their state. The state information should include: + - TIOCM_CAR state of DCD signal + - TIOCM_CTS state of CTS signal + - TIOCM_DSR state of DSR signal + - TIOCM_RI state of RI signal + The bit is set if the signal is currently driven active. If + the port does not support CTS, DCD or DSR, the driver should + indicate that the signal is permanently active. If RI is + not available, the signal should not be indicated as active. + + Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep + + stop_tx(port) + Stop transmitting characters. This might be due to the CTS + line becoming inactive or the tty layer indicating we want + to stop transmission due to an XOFF character. + + The driver should stop transmitting characters as soon as + possible. + + Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep + + start_tx(port) + Start transmitting characters. + + Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep + + stop_rx(port) + Stop receiving characters; the port is in the process of + being closed. + + Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep + + enable_ms(port) + Enable the modem status interrupts. + + This method may be called multiple times. Modem status + interrupts should be disabled when the shutdown method is + called. + + Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep + + break_ctl(port,ctl) + Control the transmission of a break signal. If ctl is + nonzero, the break signal should be transmitted. The signal + should be terminated when another call is made with a zero + ctl. + + Locking: none. + Interrupts: caller dependent. + This call must not sleep + + startup(port) + Grab any interrupt resources and initialise any low level driver + state. Enable the port for reception. It should not activate + RTS nor DTR; this will be done via a separate call to set_mctrl. + + This method will only be called when the port is initially opened. + + Locking: port_sem taken. + Interrupts: globally disabled. + + shutdown(port) + Disable the port, disable any break condition that may be in + effect, and free any interrupt resources. It should not disable + RTS nor DTR; this will have already been done via a separate + call to set_mctrl. + + Drivers must not access port->info once this call has completed. + + This method will only be called when there are no more users of + this port. + + Locking: port_sem taken. + Interrupts: caller dependent. + + flush_buffer(port) + Flush any write buffers, reset any DMA state and stop any + ongoing DMA transfers. + + This will be called whenever the port->info->xmit circular + buffer is cleared. + + Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep + + set_termios(port,termios,oldtermios) + Change the port parameters, including word length, parity, stop + bits. Update read_status_mask and ignore_status_mask to indicate + the types of events we are interested in receiving. Relevant + termios->c_cflag bits are: + CSIZE - word size + CSTOPB - 2 stop bits + PARENB - parity enable + PARODD - odd parity (when PARENB is in force) + CREAD - enable reception of characters (if not set, + still receive characters from the port, but + throw them away. + CRTSCTS - if set, enable CTS status change reporting + CLOCAL - if not set, enable modem status change + reporting. + Relevant termios->c_iflag bits are: + INPCK - enable frame and parity error events to be + passed to the TTY layer. + BRKINT + PARMRK - both of these enable break events to be + passed to the TTY layer. + + IGNPAR - ignore parity and framing errors + IGNBRK - ignore break errors, If IGNPAR is also + set, ignore overrun errors as well. + The interaction of the iflag bits is as follows (parity error + given as an example): + Parity error INPCK IGNPAR + n/a 0 n/a character received, marked as + TTY_NORMAL + None 1 n/a character received, marked as + TTY_NORMAL + Yes 1 0 character received, marked as + TTY_PARITY + Yes 1 1 character discarded + + Other flags may be used (eg, xon/xoff characters) if your + hardware supports hardware "soft" flow control. + + Locking: none. + Interrupts: caller dependent. + This call must not sleep + + pm(port,state,oldstate) + Perform any power management related activities on the specified + port. State indicates the new state (defined by ACPI D0-D3), + oldstate indicates the previous state. Essentially, D0 means + fully on, D3 means powered down. + + This function should not be used to grab any resources. + + This will be called when the port is initially opened and finally + closed, except when the port is also the system console. This + will occur even if CONFIG_PM is not set. + + Locking: none. + Interrupts: caller dependent. + + type(port) + Return a pointer to a string constant describing the specified + port, or return NULL, in which case the string 'unknown' is + substituted. + + Locking: none. + Interrupts: caller dependent. + + release_port(port) + Release any memory and IO region resources currently in use by + the port. + + Locking: none. + Interrupts: caller dependent. + + request_port(port) + Request any memory and IO region resources required by the port. + If any fail, no resources should be registered when this function + returns, and it should return -EBUSY on failure. + + Locking: none. + Interrupts: caller dependent. + + config_port(port,type) + Perform any autoconfiguration steps required for the port. `type` + contains a bit mask of the required configuration. UART_CONFIG_TYPE + indicates that the port requires detection and identification. + port->type should be set to the type found, or PORT_UNKNOWN if + no port was detected. + + UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal, + which should be probed using standard kernel autoprobing techniques. + This is not necessary on platforms where ports have interrupts + internally hard wired (eg, system on a chip implementations). + + Locking: none. + Interrupts: caller dependent. + + verify_port(port,serinfo) + Verify the new serial port information contained within serinfo is + suitable for this port type. + + Locking: none. + Interrupts: caller dependent. + + ioctl(port,cmd,arg) + Perform any port specific IOCTLs. IOCTL commands must be defined + using the standard numbering system found in <asm/ioctl.h> + + Locking: none. + Interrupts: caller dependent. + +Other functions +--------------- + +uart_update_timeout(port,cflag,baud) + Update the FIFO drain timeout, port->timeout, according to the + number of bits, parity, stop bits and baud rate. + + Locking: caller is expected to take port->lock + Interrupts: n/a + +uart_get_baud_rate(port,termios,old,min,max) + Return the numeric baud rate for the specified termios, taking + account of the special 38400 baud "kludge". The B0 baud rate + is mapped to 9600 baud. + + If the baud rate is not within min..max, then if old is non-NULL, + the original baud rate will be tried. If that exceeds the + min..max constraint, 9600 baud will be returned. termios will + be updated to the baud rate in use. + + Note: min..max must always allow 9600 baud to be selected. + + Locking: caller dependent. + Interrupts: n/a + +uart_get_divisor(port,baud) + Return the divsor (baud_base / baud) for the specified baud + rate, appropriately rounded. + + If 38400 baud and custom divisor is selected, return the + custom divisor instead. + + Locking: caller dependent. + Interrupts: n/a + +uart_match_port(port1,port2) + This utility function can be used to determine whether two + uart_port structures describe the same port. + + Locking: n/a + Interrupts: n/a + +uart_write_wakeup(port) + A driver is expected to call this function when the number of + characters in the transmit buffer have dropped below a threshold. + + Locking: port->lock should be held. + Interrupts: n/a + +uart_register_driver(drv) + Register a uart driver with the core driver. We in turn register + with the tty layer, and initialise the core driver per-port state. + + drv->port should be NULL, and the per-port structures should be + registered using uart_add_one_port after this call has succeeded. + + Locking: none + Interrupts: enabled + +uart_unregister_driver() + Remove all references to a driver from the core driver. The low + level driver must have removed all its ports via the + uart_remove_one_port() if it registered them with uart_add_one_port(). + + Locking: none + Interrupts: enabled + +uart_suspend_port() + +uart_resume_port() + +uart_add_one_port() + +uart_remove_one_port() + +Other notes +----------- + +It is intended some day to drop the 'unused' entries from uart_port, and +allow low level drivers to register their own individual uart_port's with +the core. This will allow drivers to use uart_port as a pointer to a +structure containing both the uart_port entry with their own extensions, +thus: + + struct my_port { + struct uart_port port; + int my_stuff; + }; diff --git a/Documentation/serial/moxa-smartio b/Documentation/serial/moxa-smartio new file mode 100644 index 00000000..5d2a33be --- /dev/null +++ b/Documentation/serial/moxa-smartio @@ -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://www.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 division. + 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. + + +----------------------------------------------------------------------------- + diff --git a/Documentation/serial/n_gsm.txt b/Documentation/serial/n_gsm.txt new file mode 100644 index 00000000..a5d91126 --- /dev/null +++ b/Documentation/serial/n_gsm.txt @@ -0,0 +1,89 @@ +n_gsm.c GSM 0710 tty multiplexor HOWTO +=================================================== + +This line discipline implements the GSM 07.10 multiplexing protocol +detailed in the following 3GPP document : +http://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip + +This document give some hints on how to use this driver with GPRS and 3G +modems connected to a physical serial port. + +How to use it +------------- +1- initialize the modem in 0710 mux mode (usually AT+CMUX= command) through +its serial port. Depending on the modem used, you can pass more or less +parameters to this command, +2- switch the serial line to using the n_gsm line discipline by using +TIOCSETD ioctl, +3- configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl, + +Major parts of the initialization program : +(a good starting point is util-linux-ng/sys-utils/ldattach.c) +#include <linux/gsmmux.h> +#define N_GSM0710 21 /* GSM 0710 Mux */ +#define DEFAULT_SPEED B115200 +#define SERIAL_PORT /dev/ttyS0 + + int ldisc = N_GSM0710; + struct gsm_config c; + struct termios configuration; + + /* open the serial port connected to the modem */ + fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY); + + /* configure the serial port : speed, flow control ... */ + + /* send the AT commands to switch the modem to CMUX mode + and check that it's successful (should return OK) */ + write(fd, "AT+CMUX=0\r", 10); + + /* experience showed that some modems need some time before + being able to answer to the first MUX packet so a delay + may be needed here in some case */ + sleep(3); + + /* use n_gsm line discipline */ + ioctl(fd, TIOCSETD, &ldisc); + + /* get n_gsm configuration */ + ioctl(fd, GSMIOC_GETCONF, &c); + /* we are initiator and need encoding 0 (basic) */ + c.initiator = 1; + c.encapsulation = 0; + /* our modem defaults to a maximum size of 127 bytes */ + c.mru = 127; + c.mtu = 127; + /* set the new configuration */ + ioctl(fd, GSMIOC_SETCONF, &c); + + /* and wait for ever to keep the line discipline enabled */ + daemon(0,0); + pause(); + +4- create the devices corresponding to the "virtual" serial ports (take care, +each modem has its configuration and some DLC have dedicated functions, +for example GPS), starting with minor 1 (DLC0 is reserved for the management +of the mux) + +MAJOR=`cat /proc/devices |grep gsmtty | awk '{print $1}` +for i in `seq 1 4`; do + mknod /dev/ttygsm$i c $MAJOR $i +done + +5- use these devices as plain serial ports. +for example, it's possible : +- and to use gnokii to send / receive SMS on ttygsm1 +- to use ppp to establish a datalink on ttygsm2 + +6- first close all virtual ports before closing the physical port. + +Additional Documentation +------------------------ +More practical details on the protocol and how it's supported by industrial +modems can be found in the following documents : +http://www.telit.com/module/infopool/download.php?id=616 +http://www.u-blox.com/images/downloads/Product_Docs/LEON-G100-G200-MuxImplementation_ApplicationNote_%28GSM%20G1-CS-10002%29.pdf +http://www.sierrawireless.com/Support/Downloads/AirPrime/WMP_Series/~/media/Support_Downloads/AirPrime/Application_notes/CMUX_Feature_Application_Note-Rev004.ashx +http://wm.sim.com/sim/News/photo/2010721161442.pdf + +11-03-08 - Eric Bénard - <eric@eukrea.com> diff --git a/Documentation/serial/riscom8.txt b/Documentation/serial/riscom8.txt new file mode 100644 index 00000000..14f61fda --- /dev/null +++ b/Documentation/serial/riscom8.txt @@ -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. diff --git a/Documentation/serial/rocket.txt b/Documentation/serial/rocket.txt new file mode 100644 index 00000000..60b03989 --- /dev/null +++ b/Documentation/serial/rocket.txt @@ -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 a /etc/modprobe.d/*.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 + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- + + diff --git a/Documentation/serial/serial-rs485.txt b/Documentation/serial/serial-rs485.txt new file mode 100644 index 00000000..41c8378c --- /dev/null +++ b/Documentation/serial/serial-rs485.txt @@ -0,0 +1,136 @@ + RS485 SERIAL COMMUNICATIONS + +1. INTRODUCTION + + EIA-485, also known as TIA/EIA-485 or RS-485, is a standard defining the + electrical characteristics of drivers and receivers for use in balanced + digital multipoint systems. + This standard is widely used for communications in industrial automation + because it can be used effectively over long distances and in electrically + noisy environments. + +2. HARDWARE-RELATED CONSIDERATIONS + + Some CPUs/UARTs (e.g., Atmel AT91 or 16C950 UART) contain a built-in + half-duplex mode capable of automatically controlling line direction by + toggling RTS or DTR signals. That can be used to control external + half-duplex hardware like an RS485 transceiver or any RS232-connected + half-duplex devices like some modems. + + For these microcontrollers, the Linux driver should be made capable of + working in both modes, and proper ioctls (see later) should be made + available at user-level to allow switching from one mode to the other, and + vice versa. + +3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL + + The Linux kernel provides the serial_rs485 structure (see [1]) to handle + RS485 communications. This data structure is used to set and configure RS485 + parameters in the platform data and in ioctls. + + The device tree can also provide RS485 boot time parameters (see [2] + for bindings). The driver is in charge of filling this data structure from + the values given by the device tree. + + Any driver for devices capable of working both as RS232 and RS485 should + provide at least the following ioctls: + + - TIOCSRS485 (typically associated with number 0x542F). This ioctl is used + to enable/disable RS485 mode from user-space + + - TIOCGRS485 (typically associated with number 0x542E). This ioctl is used + to get RS485 mode from kernel-space (i.e., driver) to user-space. + + In other words, the serial driver should contain a code similar to the next + one: + + static struct uart_ops atmel_pops = { + /* ... */ + .ioctl = handle_ioctl, + }; + + static int handle_ioctl(struct uart_port *port, + unsigned int cmd, + unsigned long arg) + { + struct serial_rs485 rs485conf; + + switch (cmd) { + case TIOCSRS485: + if (copy_from_user(&rs485conf, + (struct serial_rs485 *) arg, + sizeof(rs485conf))) + return -EFAULT; + + /* ... */ + break; + + case TIOCGRS485: + if (copy_to_user((struct serial_rs485 *) arg, + ..., + sizeof(rs485conf))) + return -EFAULT; + /* ... */ + break; + + /* ... */ + } + } + + +4. USAGE FROM USER-LEVEL + + From user-level, RS485 configuration can be get/set using the previous + ioctls. For instance, to set RS485 you can use the following code: + + #include <linux/serial.h> + + /* Driver-specific ioctls: */ + #define TIOCGRS485 0x542E + #define TIOCSRS485 0x542F + + /* Open your specific device (e.g., /dev/mydevice): */ + int fd = open ("/dev/mydevice", O_RDWR); + if (fd < 0) { + /* Error handling. See errno. */ + } + + struct serial_rs485 rs485conf; + + /* Enable RS485 mode: */ + rs485conf.flags |= SER_RS485_ENABLED; + + /* Set logical level for RTS pin equal to 1 when sending: */ + rs485conf.flags |= SER_RS485_RTS_ON_SEND; + /* or, set logical level for RTS pin equal to 0 when sending: */ + rs485conf.flags &= ~(SER_RS485_RTS_ON_SEND); + + /* Set logical level for RTS pin equal to 1 after sending: */ + rs485conf.flags |= SER_RS485_RTS_AFTER_SEND; + /* or, set logical level for RTS pin equal to 0 after sending: */ + rs485conf.flags &= ~(SER_RS485_RTS_AFTER_SEND); + + /* Set rts delay before send, if needed: */ + rs485conf.delay_rts_before_send = ...; + + /* Set rts delay after send, if needed: */ + rs485conf.delay_rts_after_send = ...; + + /* Set this flag if you want to receive data even whilst sending data */ + rs485conf.flags |= SER_RS485_RX_DURING_TX; + + if (ioctl (fd, TIOCSRS485, &rs485conf) < 0) { + /* Error handling. See errno. */ + } + + /* Use read() and write() syscalls here... */ + + /* Close the device when finished: */ + if (close (fd) < 0) { + /* Error handling. See errno. */ + } + +5. REFERENCES + + [1] include/linux/serial.h + [2] Documentation/devicetree/bindings/serial/rs485.txt diff --git a/Documentation/serial/specialix.txt b/Documentation/serial/specialix.txt new file mode 100644 index 00000000..6eb6f3a3 --- /dev/null +++ b/Documentation/serial/specialix.txt @@ -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? + + diff --git a/Documentation/serial/stallion.txt b/Documentation/serial/stallion.txt new file mode 100644 index 00000000..55090914 --- /dev/null +++ b/Documentation/serial/stallion.txt @@ -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 configuration files are put in the +/etc/modprobe.d/ directory. + + +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. + diff --git a/Documentation/serial/sx.txt b/Documentation/serial/sx.txt new file mode 100644 index 00000000..cb4efa0f --- /dev/null +++ b/Documentation/serial/sx.txt @@ -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) + + + diff --git a/Documentation/serial/tty.txt b/Documentation/serial/tty.txt new file mode 100644 index 00000000..540db41d --- /dev/null +++ b/Documentation/serial/tty.txt @@ -0,0 +1,301 @@ + + 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. Returning an error will + prevent the ldisc from being attached. 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. + The return value is ignored. 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. + +compat_ioctl() - Called when a 32 bit 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. + +dcd_change() - Report to the tty line the current DCD pin status + changes and the relative timestamp. The timestamp + cannot be NULL. + + +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 ?? + |