diff options
author | bde <bde@FreeBSD.org> | 1995-10-17 17:38:42 +0000 |
---|---|---|
committer | bde <bde@FreeBSD.org> | 1995-10-17 17:38:42 +0000 |
commit | 85b40e7947ac4f883d699d92d617a998830b3592 (patch) | |
tree | 614c09a138f5ba29a3b76479d540698e323a64f1 /share/man | |
parent | e28ffae1a80b8eb0d97905ef7c3cac19d941cf78 (diff) | |
download | FreeBSD-src-85b40e7947ac4f883d699d92d617a998830b3592.zip FreeBSD-src-85b40e7947ac4f883d699d92d617a998830b3592.tar.gz |
Add a man page for the dgb driver.
Submitted by: "Serge A. Babkin" <babkin@hq.icb.chel.su>
(English improved a bit by me.)
Diffstat (limited to 'share/man')
-rw-r--r-- | share/man/man4/man4.i386/Makefile | 4 | ||||
-rw-r--r-- | share/man/man4/man4.i386/dgb.4 | 362 |
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. |