diff options
Diffstat (limited to 'share/man/man4/digi.4')
| -rw-r--r-- | share/man/man4/digi.4 | 377 |
1 files changed, 377 insertions, 0 deletions
diff --git a/share/man/man4/digi.4 b/share/man/man4/digi.4 new file mode 100644 index 0000000..1e34119 --- /dev/null +++ b/share/man/man4/digi.4 @@ -0,0 +1,377 @@ +.\" 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. 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. |
