382 lines
13 KiB
Groff
382 lines
13 KiB
Groff
.\" Copyright (c) 1990, 1991 The Regents of the University of California.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" the Systems Programming Group of the University of Utah Computer
|
|
.\" Science Department.
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" from: @(#)dca.4 5.2 (Berkeley) 3/27/91
|
|
.\" from: com.4,v 1.1 1993/08/06 11:19:07 cgd Exp
|
|
.\" from: sio.4,v 1.15 1994/12/06 20:14:30 bde Exp
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd December 7, 2003
|
|
.Dt DIGI 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm digi
|
|
.Nd DigiBoard intelligent serial cards driver
|
|
.Sh SYNOPSIS
|
|
.Cd "device digi"
|
|
.Pp
|
|
This man page was originally written for the dgb driver, and should
|
|
likely be gone over with a fine tooth comb to reflect differences
|
|
with the digi driver.
|
|
.Pp
|
|
When not defined the number is computed:
|
|
.Bd -ragged -offset 4n
|
|
default
|
|
.Dv NDGBPORTS
|
|
= number_of_described_DigiBoard_cards * 16
|
|
.Ed
|
|
.Pp
|
|
If it is less than the actual number of ports
|
|
the system will be able to use only the
|
|
first
|
|
.Dv NDGBPORTS
|
|
ports.
|
|
If it is greater then all ports will be usable
|
|
but some memory will be wasted.
|
|
.Pp
|
|
Meaning of
|
|
.Cm flags :
|
|
.Bl -tag -width indent -compact
|
|
.It 0x0001
|
|
use alternate pinout (exchange DCD and DSR lines)
|
|
.It 0x0002
|
|
do not use 8K window mode of PC/Xe
|
|
.El
|
|
.Pp
|
|
Device numbering:
|
|
.Bd -literal -compact
|
|
0b\fICC\fPmmmmmmmm\fIOLIPPPPP\fP
|
|
\fBCC\fPard number
|
|
\fRmmmmmmmm\fPajor number
|
|
call\fBO\fPut
|
|
\fBL\fPock
|
|
\fBI\fPnitial
|
|
\fBPPPPP\fPort number
|
|
.Ed
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver provides support for DigiBoard PC/Xe and PC/Xi series intelligent
|
|
serial multiport cards with asynchronous interfaces based on the
|
|
.Tn EIA
|
|
.Tn RS-232C
|
|
.Pf ( Tn CCITT
|
|
.Tn V.24 )
|
|
standard.
|
|
.Pp
|
|
Input and output for each line may set to one of following baud rates;
|
|
50, 75, 110, 134.5, 150, 300, 600, 1200, 1800, 2400, 4800, 9600,
|
|
19200, 38400, 57600, or for newer versions of cards 115200.
|
|
.Pp
|
|
The driver does not use any interrupts, it is
|
|
.Dq polling-based .
|
|
This means that
|
|
it uses clock interrupts instead of interrupts generated by DigiBoard cards and
|
|
checks the state of cards 25 times per second.
|
|
This is practical because the
|
|
DigiBoard cards have large input and output buffers (more than 1Kbyte per
|
|
port) and hardware that allows efficiently finding the port that needs
|
|
attention.
|
|
The only problem seen with this policy is slower
|
|
SLIP and PPP response.
|
|
.Pp
|
|
Each line in the kernel configuration file describes one card, not one port
|
|
as in the
|
|
.Xr sio 4
|
|
driver.
|
|
.Pp
|
|
The
|
|
.Cm flags
|
|
keyword may be used on each
|
|
.Dq Li "device dgb"
|
|
line in the kernel configuration file
|
|
to change the pinout of the interface or to use new PC/Xe cards
|
|
which can work with an 8K memory window in compatibility mode
|
|
(with a 64K memory window).
|
|
Note
|
|
that using 8K memory window does not mean shorter input/output buffers, it means
|
|
only that all buffers will be mapped to the same memory address and switched as
|
|
needed.
|
|
.Pp
|
|
The
|
|
.Cm port
|
|
value must be the same
|
|
as the
|
|
port
|
|
set on the card by jumpers.
|
|
For PC/Xi cards the same rule is applicable to the
|
|
.Cm iomem
|
|
value.
|
|
It must be the same as the memory address set on the card
|
|
by jumpers.
|
|
.\"Some documentation gives the address as a ``paragraph'' or ``segment'';
|
|
.\"you can get the value of address by adding the digit "0" at end of
|
|
.\"paragraph value, e.g., 0xfc000 -> 0xfc0000.
|
|
For PC/Xe cards there is no need to use jumpers for this purpose.
|
|
In fact there are no jumpers to do it.
|
|
Just
|
|
write the address you want as the
|
|
.Cm iomem
|
|
value in kernel config file and the card will be programmed
|
|
to use this address.
|
|
.Pp
|
|
The same range of memory addresses may be used
|
|
for all the DigiBoards installed
|
|
(but not for any other card or real memory).
|
|
DigiBoards
|
|
with a large amount of memory (256K or 512K and perhaps
|
|
even 128K) must be mapped
|
|
to memory addresses outside of the first megabyte.
|
|
If the computer
|
|
has more than 15 megabytes of memory then there is no free address space
|
|
outside of the first megabyte where such DigiBoards can be mapped.
|
|
In this case you
|
|
may need to reduce the amount of memory in the computer.
|
|
But many machines provide a better solution.
|
|
They have the ability to
|
|
.Dq "turn off"
|
|
the memory in the 16th megabyte (addresses 0xF00000 - 0xFFFFFF)
|
|
using the
|
|
BIOS setup.
|
|
Then the DigiBoard's address space can be set to this
|
|
.Dq hole .
|
|
.\" XXX the following should be true for all serial drivers and
|
|
.\" should not be repeated in the man pages for all serial drivers.
|
|
.\" It was copied from sio.4. The only changes were s/sio/dgb/g.
|
|
.Pp
|
|
Serial ports controlled by the
|
|
.Nm
|
|
driver can be used for both
|
|
.Dq callin
|
|
and
|
|
.Dq callout .
|
|
For each port there is a callin device and a callout device.
|
|
The minor number of the callout device is 128 higher
|
|
than that of the corresponding callin port.
|
|
The callin device is general purpose.
|
|
Processes opening it normally wait for carrier
|
|
and for the callout device to become inactive.
|
|
The callout device is used to steal the port from
|
|
processes waiting for carrier on the callin device.
|
|
Processes opening it do not wait for carrier
|
|
and put any processes waiting for carrier on the callin device into
|
|
a deeper sleep so that they do not conflict with the callout session.
|
|
The callout device is abused for handling programs that are supposed
|
|
to work on general ports and need to open the port without waiting
|
|
but are too stupid to do so.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
driver also supports an initial-state and a lock-state control
|
|
device for each of the callin and the callout
|
|
.Dq data
|
|
devices.
|
|
The minor number of the initial-state device is 32 higher
|
|
than that of the corresponding data device.
|
|
The minor number of the lock-state device is 64 higher
|
|
than that of the corresponding data device.
|
|
The termios settings of a data device are copied
|
|
from those of the corresponding initial-state device
|
|
on first opens and are not inherited from previous opens.
|
|
Use
|
|
.Xr stty 1
|
|
in the normal way on the initial-state devices to program
|
|
initial termios states suitable for your setup.
|
|
.Pp
|
|
The lock termios state acts as flags to disable changing
|
|
the termios state.
|
|
E.g., to lock a flag variable such as
|
|
.Dv CRTSCTS ,
|
|
use
|
|
.Dq Li "stty crtscts"
|
|
on the lock-state device.
|
|
Speeds and special characters
|
|
may be locked by setting the corresponding value in the lock-state
|
|
device to any nonzero value.
|
|
.Pp
|
|
Correct programs talking to correctly wired external devices
|
|
.\" XXX change next line in other man pages too, and rewrite this paragraph.
|
|
work with almost arbitrary initial states and no locking,
|
|
but other setups may benefit from changing some of the default
|
|
initial state and locking the state.
|
|
In particular, the initial states for non (POSIX) standard flags
|
|
should be set to suit the devices attached and may need to be
|
|
locked to prevent buggy programs from changing them.
|
|
E.g.,
|
|
.Dv CRTSCTS
|
|
should be locked on for devices that support
|
|
RTS/CTS handshaking at all times and off for devices that do not
|
|
support it at all.
|
|
.Dv CLOCAL
|
|
should be locked on for devices
|
|
that do not support carrier.
|
|
.Dv HUPCL
|
|
may be locked off if you do not
|
|
want to hang up for some reason.
|
|
In general, very bad things happen
|
|
if something is locked to the wrong state, and things should not
|
|
be locked for devices that support more than one setting.
|
|
The
|
|
.Dv CLOCAL
|
|
flag on callin ports should be locked off for logins
|
|
to avoid certain security holes, but this needs to be done by
|
|
getty if the callin port is used for anything else.
|
|
.Sh FILES
|
|
.Bl -tag -width /dev/ttyiD?? -compact
|
|
.It Pa /dev/ttyD??
|
|
for callin ports
|
|
.It Pa /dev/ttyiD??
|
|
.It Pa /dev/ttylD??
|
|
corresponding callin initial-state and lock-state devices
|
|
.Pp
|
|
.It Pa /dev/cuaD??
|
|
for callout ports
|
|
.It Pa /dev/cuaiD??
|
|
.It Pa /dev/cualD??
|
|
corresponding callout initial-state and lock-state devices
|
|
.El
|
|
.Pp
|
|
.Bl -tag -width /etc/rc.serial -compact
|
|
.It Pa /etc/rc.serial
|
|
examples of setting the initial-state and lock-state devices
|
|
.El
|
|
.Pp
|
|
The first question mark in these device names is short for the
|
|
card number
|
|
(a decimal number between 0 and 65535 inclusive).
|
|
The second question mark is short for the port number
|
|
(a letter in the range [0-9a-v]).
|
|
.Sh DIAGNOSTICS
|
|
You may enable extended diagnostics by defining DEBUG at the
|
|
start of the source file
|
|
.Pa dgb.c .
|
|
.Bl -diag
|
|
.It dgb\fIX\fP: warning: address \fIN\fP truncated to \fIM\fP
|
|
The memory address for the PC/Xe's 8K window is misaligned (it should be
|
|
on an 8K boundary) or outside of the first megabyte.
|
|
.It dgb\fIX\fP: 1st reset failed
|
|
Problems with accessing I/O port of the card, probably
|
|
the wrong
|
|
.Cm port
|
|
value is specified in the kernel config file.
|
|
.It dgb\fIX\fP: 2nd reset failed
|
|
Problems with hardware.
|
|
.It dgb\fIX\fP: \fIN\fP[st,nd,rd,th] memory test failed
|
|
Problems with accessing the memory of the card, probably
|
|
the wrong
|
|
.Cm iomem
|
|
value is specified in the kernel config file.
|
|
.It dgb\fIX\fP: BIOS start failed
|
|
Problems with starting the on-board BIOS.
|
|
Probably the memory addresses of the
|
|
DigiBoard overlap with some other device or with RAM.
|
|
.It dgb\fIX\fP: BIOS download failed
|
|
Problems with the on-board BIOS.
|
|
Probably the memory addresses of the
|
|
DigiBoard overlap with some other device or with RAM.
|
|
.It dgb\fIX\fP: FEP code download failed
|
|
Problems with downloading of the Front-End Processor's micro-OS.
|
|
Probably the memory addresses of the
|
|
DigiBoard overlap with some other device or with RAM.
|
|
.It dgb\fIX\fP: FEP/OS start failed
|
|
Problems with starting of the Front-End Processor's micro-OS.
|
|
Probably the memory addresses of the
|
|
DigiBoard overlap with some other device or with RAM.
|
|
.It dgb\fIX\fP: too many ports
|
|
This DigiBoard reports that it has more than 32 ports.
|
|
Perhaps a hardware problem or
|
|
the memory addresses of the
|
|
DigiBoard overlap with some other device or with RAM.
|
|
.It dgb\fIX\fP: only \fIN\fP ports are usable
|
|
The
|
|
.Dv NDGBPORTS
|
|
parameter is too small and there is only enough space allocated
|
|
for
|
|
.Ar N
|
|
ports on this card.
|
|
.It dgb\fIX\fP: port \fIY\fP is broken
|
|
The on-board diagnostic has reported that the specified port has hardware
|
|
problems.
|
|
.It dgb\fIX\fP: polling of disabled board stopped
|
|
Internal problems in the polling logic of driver.
|
|
.It dgb\fIX\fP: event queue's head or tail is wrong!
|
|
Internal problems in the driver or hardware.
|
|
.It dgb\fIX\fP: port \fIY\fP: got event on nonexisting port
|
|
Some status changed on a port that is physically present but is
|
|
unusable due to misconfiguration.
|
|
.It dgb\fIX\fP: port \fIY\fP: event \fIN\fP mstat \fIM\fP lstat \fIK\fP
|
|
The driver got a strange event from card.
|
|
Probably this means that you have a
|
|
newer card with an extended list of events or some other hardware problem.
|
|
.It dgb\fIX\fP: port \fIY\fP: overrun
|
|
Input buffer has filled up.
|
|
Problems in polling logic of driver.
|
|
.It dgb\fIX\fP: port \fIY\fP: FEP command on disabled port
|
|
Internal problems in driver.
|
|
.It dgb\fIX\fP: port \fIY\fP: timeout on FEP command
|
|
Problems in hardware.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr stty 1 ,
|
|
.Xr termios 4 ,
|
|
.Xr tty 4 ,
|
|
.Xr comcontrol 8
|
|
.\" XXX add next line to many other drivers.
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
driver is derived from the
|
|
.Xr sio 4
|
|
driver and the DigiBoard driver from
|
|
.Tn Linux
|
|
and is
|
|
.Ud
|
|
.Sh BUGS
|
|
The implementation of sending
|
|
.Dv BREAK
|
|
is broken.
|
|
.Dv BREAK
|
|
of fixed length of 1/4 s
|
|
is sent anyway.
|
|
.Pp
|
|
There was a bug in implementation of
|
|
.Xr select 2 .
|
|
It is fixed now but not widely tested yet.
|
|
.Pp
|
|
There is no ditty command.
|
|
Most of its functions (alternate pinout,
|
|
speed up to 115200 baud, etc.) are implemented in the driver itself.
|
|
Some
|
|
other functions are missing.
|