Add a man page for the dgb driver.

Submitted by:	"Serge A. Babkin" <babkin@hq.icb.chel.su>
		(English improved a bit by me.)

2 files changed, 365 insertions, 1 deletions

diff --git a/share/man/man4/man4.i386/Makefile b/share/man/man4/man4.i386/Makefile
index dad6d41..891c259 100644
--- a/share/man/man4/man4.i386/Makefile
+++ b/share/man/man4/man4.i386/Makefile
@@ -1,6 +1,7 @@
 #	@(#)Makefile	0.1 (RWGrimes) 3/25/93
 
-MAN4=   aha.4 ahb.4 ahc.4 apm.4 asc.4 bt.4 cx.4 cy.4 ed.4 fdc.4 fe.4 ie.4 \
+MAN4=   aha.4 ahb.4 ahc.4 apm.4 asc.4 bt.4 cx.4 cy.4 dgb.4 \
+	ed.4 fdc.4 fe.4 ie.4 \
 	is.4 joy.4 keyboard.4 lpt.4 matcd.4 mcd.4 mem.4 meteor.4 \
 	mse.4 npx.4 pcvt.4 screen.4 si.4 sio.4 spkr.4 tw.4 uha.4 wd.4
 
@@ -12,6 +13,7 @@ MLINKS+=	asc.4 ../asc.4
 MLINKS+=	bt.4 ../bt.4
 MLINKS+=	cx.4 ../cx.4
 MLINKS+=	cy.4 ../cy.4
+MLINKS+=	dgb.4 ../dgb.4
 MLINKS+=	ed.4 ../ed.4
 MLINKS+=	fdc.4 ../fdc.4
 MLINKS+=	fe.4 ../fe.4
diff --git a/share/man/man4/man4.i386/dgb.4 b/share/man/man4/man4.i386/dgb.4
new file mode 100644
index 0000000..b72ae14
--- /dev/null
+++ b/share/man/man4/man4.i386/dgb.4
@@ -0,0 +1,362 @@
+.\" 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
+.\"	$Id$
+.\"
+.Dd Oct 13, 1995
+.Dt DGB 4 i386
+.Os FreeBSD
+.Sh NAME
+.Nm dgb
+.Nd
+DigiBoard intelligent serial cards driver
+.Sh SYNOPSIS
+.Cd "options" \&"NDGBPORTS=8\&"
+.Cd "device dgb0 at isa? tty port 0x220 iomem 0xfc0000 iosiz ? flags 0x0
+All values are just examples.
+.sp
+The \fBNDGBPORTS\fR option defines the total number of ports on all cards
+installed in the system. When not defined the number is computed:
+
+.br
+    default \fBNDGBPORTS\fR = number_of_described_DigiBoard_cards * 16
+
+If it is less than the actual number of ports 
+the system will be able to use only the
+first \fBNDGBPORTS\fR ports. If it is greater then all ports will be usable
+but some memory will be wasted.
+.sp
+Meaning of \fBflags\fR:
+.br
+\fB0x0001\fR use alternate pinout (exchange DCD and DSR lines)
+.br
+\fB0x0002\fR don't use 8K window mode of PC/Xe
+.sp
+Device numbering:
+.br
+0b\fICC\fRmmmmmmmm\fIOLIPPPPP\fR
+.br
+  \fBCC\fRard number
+.br
+    mmmmmmmm\fRajor number
+.br
+            call\fBO\fRut
+.br
+             \fBL\fRock
+.br
+              \fBI\fRnitial
+.br
+               \fBPPPPP\fRort number
+.Sh DESCRIPTION
+The
+.Nm dgb
+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 ``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.
+.sp
+Each line in the kernel configuration file describes one card, not one port 
+as in the
+.Nm sio
+driver.
+.sp
+The
+.Nm flags
+keyword may be used on each
+.Nm 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.
+.sp
+The
+.Nm port
+value must be the same
+as the 
+.Nm port
+set on the card by jumpers.
+For PC/Xi cards the same rule is applicable to the
+.Nm 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
+.Nm iomem
+value in kernel config file and the card will be programmed 
+to use this address.
+.sp
+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
+``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 ``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 dgb
+driver can be used for both `callin' and `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 dgb
+driver also supports an initial-state and a lock-state control
+device for each of the callin and the callout "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.
+.sp
+The lock termios state acts as flags to disable changing
+the termios state.  E.g., to lock a flag variable such as
+CRTSCTS, use
+.Nm 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.
+.sp
+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., 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.  CLOCAL should be locked on for devices
+that don't support carrier.  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
+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
+.sp
+.It Pa /dev/cuaD??
+for callout ports
+.It Pa /dev/cuaiD??
+.It Pa /dev/cualD??
+corresponding callout initial-state and lock-state devices
+.El
+.sp
+.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
+means the number of the card from the set [0-9] and the
+second question mark means the number of the port on the card from the set
+[0-9a-v].
+.Sh DIAGNOSTICS
+You may enable extended diagnostics by defining DEBUG at the
+start of the source file dgb.c.
+.Bl -diag
+.It dgb\fIX\fB: warning: address \fIN\fB truncated to \fIM\fB
+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.
+.El
+.Bl -diag
+.It dgb\fIX\fB: 1st reset failed
+Problems with accessing I/O port of the card, probably 
+the wrong \fBport\fR value is specified in the kernel config file.
+.El
+.Bl -diag
+.It dgb\fIX\fB: 2nd reset failed
+Problems with hardware.
+.El
+.Bl -diag
+.It dgb\fIX\fB: \fIN\fB[st,nd,rd,th] memory test failed
+Problems with accessing the memory of the card, probably
+the wrong \fBiomem\fR value is specified in the kernel config file.
+.El
+.Bl -diag
+.It dgb\fIX\fB: 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.
+.El
+.Bl -diag
+.It dgb\fIX\fB: BIOS download failed
+Problems with the on-board BIOS. Probably the memory addresses of the
+DigiBoard overlap with some other device or with RAM.
+.El
+.Bl -diag
+.It dgb\fIX\fB: 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.
+.El
+.Bl -diag
+.It dgb\fIX\fB: 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.
+.El
+.Bl -diag
+.It dgb\fIX\fB: 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.
+.El
+.Bl -diag
+.It dgb\fIX\fB: only \fIN\fB ports are usable
+The NDGBPORTS parameter is too small and there is only enough space allocated
+for \fIN\fR ports on this card.
+.El
+.Bl -diag
+.It dgb\fIX\fB: port \fIY\fB is broken
+The on-board diagnostic has reported that the specified port has hardware
+problems.
+.El
+.Bl -diag
+.It dgb\fIX\fB: polling of disabled board stopped
+Internal problems in the polling logic of driver.
+.El
+.Bl -diag
+.It dgb\fIX\fB: event queue's head or tail is wrong!
+Internal problems in the driver or hardware.
+.El
+.Bl -diag
+.It dgb\fIX\fB: port \fIY\fB: got event on nonexisting port
+Some status changed on a port that is physically present but is 
+unusable due to misconfiguration.
+.El
+.Bl -diag
+.It dgb\fIX\fB: port \fIY\fB: event \fIN\fB mstat \fIM\fB lstat \fIK\fB
+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.
+.El
+.Bl -diag
+.It dgb\fIX\fB: port \fIY\fB: overrun
+Input buffer has filled up. Problems in polling logic of driver.
+.El
+.Bl -diag
+.It dgb\fIX\fB: port \fIY\fB: FEP command on disabled port
+Internal problems in driver.
+.El
+.Bl -diag
+.It dgb\fIX\fB: port \fIY\fB: timeout on FEP command
+Problems in hardware.
+.Sh SEE ALSO
+.Xr tty 4 ,
+.Xr termios 4 ,
+.Xr comcontrol 8 ,
+.\" XXX add next line to many other drivers.
+.Xr MAKEDEV 8 ,
+.Xr stty 1 .
+.Sh HISTORY
+The
+.Nm
+driver is derived from the
+.Nm sio
+driver and the DigiBoard driver from 
+.Nm Linux 
+and is
+.Ud
+.Sh BUGS
+The implementation of sending BREAK is broken.  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.