Copy the old dgb man page to digi.4, plus very minor hacking. Add a

note that says that this man page is sub-optimal.  Bruce Mah should be
happier about this, but someone that groks the cards supported by the
digi driver is encouraged to make this man page suck less.

1 files changed, 382 insertions, 0 deletions

diff --git a/share/man/man4/digi.4 b/share/man/man4/digi.4
new file mode 100644
index 0000000..1eb13f4
--- /dev/null
+++ b/share/man/man4/digi.4
@@ -0,0 +1,382 @@
+.\" 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 i386
+.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:
+.Pp
+.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
+don't 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 doesn't 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 doesn't 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 don't
+support it at all.
+.Dv CLOCAL
+should be locked on for devices
+that don't support carrier.
+.Dv HUPCL
+may be locked off if you don't
+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.