gold: Fix hardcoded library search path
[dragonfly.git] / share / man / man4 / man4.i386 / dgb.4
CommitLineData
984263bc
MD
1.\" Copyright (c) 1990, 1991 The Regents of the University of California.
2.\" All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the Systems Programming Group of the University of Utah Computer
6.\" Science Department.
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\" 3. All advertising materials mentioning features or use of this software
16.\" must display the following acknowledgement:
17.\" This product includes software developed by the University of
18.\" California, Berkeley and its contributors.
19.\" 4. Neither the name of the University nor the names of its contributors
20.\" may be used to endorse or promote products derived from this software
21.\" without specific prior written permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\" from: @(#)dca.4 5.2 (Berkeley) 3/27/91
36.\" from: com.4,v 1.1 1993/08/06 11:19:07 cgd Exp
37.\" from: sio.4,v 1.15 1994/12/06 20:14:30 bde Exp
38.\" $FreeBSD: src/share/man/man4/man4.i386/dgb.4,v 1.13.2.6 2001/08/17 13:08:45 ru Exp $
39.\"
2c272516 40.Dd August 6, 2009
984263bc
MD
41.Dt DGB 4 i386
42.Os
43.Sh NAME
44.Nm dgb
45.Nd DigiBoard intelligent serial cards driver
46.Sh SYNOPSIS
47.Cd "options NDGBPORTS=8"
48.Cd "device dgb0 at isa? port 0x220 iomem 0xfc0000 iosiz ? flags 0x0"
49All values are just examples.
50.Pp
51The
52.Dv NDGBPORTS
53option defines the total number of ports on all cards
54installed in the system.
55When not defined the number is computed:
984263bc
MD
56.Bd -ragged -offset 4n
57default
58.Dv NDGBPORTS
59= number_of_described_DigiBoard_cards * 16
60.Ed
61.Pp
62If it is less than the actual number of ports
63the system will be able to use only the
64first
65.Dv NDGBPORTS
66ports.
5fba7a97 67If it is greater than all ports will be usable
984263bc
MD
68but some memory will be wasted.
69.Pp
70Meaning of
71.Cm flags :
72.Bl -tag -width indent -compact
73.It 0x0001
74use alternate pinout (exchange DCD and DSR lines)
75.It 0x0002
76don't use 8K window mode of PC/Xe
77.El
78.Pp
79Device numbering:
80.Bd -literal -compact
810b\fICC\fPmmmmmmmm\fIOLIPPPPP\fP
82 \fBCC\fPard number
83 \fRmmmmmmmm\fPajor number
84 call\fBO\fPut
85 \fBL\fPock
86 \fBI\fPnitial
87 \fBPPPPP\fPort number
88.Ed
89.Sh DESCRIPTION
90The
91.Nm
92driver provides support for DigiBoard PC/Xe and PC/Xi series intelligent
93serial multiport cards with asynchronous interfaces based on the
94.Tn EIA
95.Tn RS-232C
96.Pf ( Tn CCITT
97.Tn V.24 )
98standard.
99.Pp
100Input and output for each line may set to one of following baud rates;
10150, 75, 110, 134.5, 150, 300, 600, 1200, 1800, 2400, 4800, 9600,
10219200, 38400, 57600, or for newer versions of cards 115200.
103.Pp
104The driver doesn't use any interrupts, it is
105.Dq polling\-based .
106This means that
107it uses clock interrupts instead of interrupts generated by DigiBoard cards and
108checks the state of cards 25 times per second.
109This is practical because the
110DigiBoard cards have large input and output buffers (more than 1Kbyte per
111port) and hardware that allows efficiently finding the port that needs
112attention.
113The only problem seen with this policy is slower
114SLIP and PPP response.
115.Pp
116Each line in the kernel configuration file describes one card, not one port
117as in the
118.Xr sio 4
119driver.
120.Pp
121The
122.Cm flags
123keyword may be used on each
124.Dq Li "device dgb"
125line in the kernel configuration file
126to change the pinout of the interface or to use new PC/Xe cards
127which can work with an 8K memory window in compatibility mode
128(with a 64K memory window).
129Note
130that using 8K memory window doesn't mean shorter input/output buffers, it means
131only that all buffers will be mapped to the same memory address and switched as
132needed.
133.Pp
134The
135.Cm port
136value must be the same
137as the
138port
139set on the card by jumpers.
140For PC/Xi cards the same rule is applicable to the
141.Cm iomem
142value.
143It must be the same as the memory address set on the card
144by jumpers.
145.\"Some documentation gives the address as a ``paragraph'' or ``segment'';
146.\"you can get the value of address by adding the digit "0" at end of
147.\"paragraph value, e.g., 0xfc000 -> 0xfc0000.
148For PC/Xe cards there is no need to use jumpers for this purpose.
149In fact there are no jumpers to do it.
150Just
151write the address you want as the
152.Cm iomem
153value in kernel config file and the card will be programmed
154to use this address.
155.Pp
156The same range of memory addresses may be used
157for all the DigiBoards installed
158(but not for any other card or real memory).
159DigiBoards
160with a large amount of memory (256K or 512K and perhaps
161even 128K) must be mapped
162to memory addresses outside of the first megabyte.
163If the computer
164has more than 15 megabytes of memory then there is no free address space
165outside of the first megabyte where such DigiBoards can be mapped.
166In this case you
167may need to reduce the amount of memory in the computer.
168But many machines provide a better solution.
169They have the ability to
170.Dq "turn off"
171the memory in the 16th megabyte (addresses 0xF00000 - 0xFFFFFF)
172using the
173BIOS setup.
174Then the DigiBoard's address space can be set to this
175.Dq hole .
176.\" XXX the following should be true for all serial drivers and
177.\" should not be repeated in the man pages for all serial drivers.
178.\" It was copied from sio.4. The only changes were s/sio/dgb/g.
179.Pp
180Serial ports controlled by the
181.Nm
182driver can be used for both
183.Dq callin
184and
185.Dq callout .
186For each port there is a callin device and a callout device.
187The minor number of the callout device is 128 higher
188than that of the corresponding callin port.
189The callin device is general purpose.
190Processes opening it normally wait for carrier
191and for the callout device to become inactive.
192The callout device is used to steal the port from
193processes waiting for carrier on the callin device.
194Processes opening it do not wait for carrier
195and put any processes waiting for carrier on the callin device into
196a deeper sleep so that they do not conflict with the callout session.
197The callout device is abused for handling programs that are supposed
198to work on general ports and need to open the port without waiting
199but are too stupid to do so.
200.Pp
201The
202.Nm
203driver also supports an initial-state and a lock-state control
204device for each of the callin and the callout
205.Dq data
206devices.
207The minor number of the initial-state device is 32 higher
208than that of the corresponding data device.
209The minor number of the lock-state device is 64 higher
210than that of the corresponding data device.
211The termios settings of a data device are copied
212from those of the corresponding initial-state device
213on first opens and are not inherited from previous opens.
214Use
215.Xr stty 1
216in the normal way on the initial-state devices to program
217initial termios states suitable for your setup.
218.Pp
219The lock termios state acts as flags to disable changing
220the termios state.
221E.g., to lock a flag variable such as
222.Dv CRTSCTS ,
223use
224.Dq Li "stty crtscts"
225on the lock-state device.
226Speeds and special characters
227may be locked by setting the corresponding value in the lock-state
228device to any nonzero value.
229.Pp
230Correct programs talking to correctly wired external devices
231.\" XXX change next line in other man pages too, and rewrite this paragraph.
232work with almost arbitrary initial states and no locking,
233but other setups may benefit from changing some of the default
234initial state and locking the state.
235In particular, the initial states for non (POSIX) standard flags
236should be set to suit the devices attached and may need to be
237locked to prevent buggy programs from changing them.
238E.g.,
239.Dv CRTSCTS
240should be locked on for devices that support
241RTS/CTS handshaking at all times and off for devices that don't
242support it at all.
243.Dv CLOCAL
244should be locked on for devices
245that don't support carrier.
246.Dv HUPCL
247may be locked off if you don't
248want to hang up for some reason.
249In general, very bad things happen
250if something is locked to the wrong state, and things should not
251be locked for devices that support more than one setting.
252The
253.Dv CLOCAL
254flag on callin ports should be locked off for logins
255to avoid certain security holes, but this needs to be done by
256getty if the callin port is used for anything else.
257.Sh FILES
258.Bl -tag -width /dev/ttyiD?? -compact
259.It Pa /dev/ttyD??
260for callin ports
261.It Pa /dev/ttyiD??
262.It Pa /dev/ttylD??
263corresponding callin initial-state and lock-state devices
264.Pp
265.It Pa /dev/cuaD??
266for callout ports
267.It Pa /dev/cuaiD??
268.It Pa /dev/cualD??
269corresponding callout initial-state and lock-state devices
270.El
271.Pp
be67b412
TN
272.Bl -tag -width /etc/rc.d/serial -compact
273.It Pa /etc/rc.d/serial
984263bc
MD
274examples of setting the initial-state and lock-state devices
275.El
276.Pp
277The first question mark in these device names is short for the
278card number
279(a decimal number between 0 and 65535 inclusive).
280The second question mark is short for the port number
281(a letter in the range [0-9a-v]).
282.Sh DIAGNOSTICS
283You may enable extended diagnostics by defining DEBUG at the
284start of the source file
285.Pa dgb.c .
286.Bl -diag
287.It dgb\fIX\fP: warning: address \fIN\fP truncated to \fIM\fP
288The memory address for the PC/Xe's 8K window is misaligned (it should be
289on an 8K boundary) or outside of the first megabyte.
290.It dgb\fIX\fP: 1st reset failed
291Problems with accessing I/O port of the card, probably
292the wrong
293.Cm port
294value is specified in the kernel config file.
295.It dgb\fIX\fP: 2nd reset failed
296Problems with hardware.
297.It dgb\fIX\fP: \fIN\fP[st,nd,rd,th] memory test failed
298Problems with accessing the memory of the card, probably
299the wrong
300.Cm iomem
301value is specified in the kernel config file.
302.It dgb\fIX\fP: BIOS start failed
303Problems with starting the on-board BIOS.
304Probably the memory addresses of the
305DigiBoard overlap with some other device or with RAM.
306.It dgb\fIX\fP: BIOS download failed
307Problems with the on-board BIOS.
308Probably the memory addresses of the
309DigiBoard overlap with some other device or with RAM.
310.It dgb\fIX\fP: FEP code download failed
311Problems with downloading of the Front-End Processor's micro-OS.
312Probably the memory addresses of the
313DigiBoard overlap with some other device or with RAM.
314.It dgb\fIX\fP: FEP/OS start failed
315Problems with starting of the Front-End Processor's micro-OS.
316Probably the memory addresses of the
317DigiBoard overlap with some other device or with RAM.
318.It dgb\fIX\fP: too many ports
319This DigiBoard reports that it has more than 32 ports.
320Perhaps a hardware problem or
321the memory addresses of the
322DigiBoard overlap with some other device or with RAM.
323.It dgb\fIX\fP: only \fIN\fP ports are usable
324The
325.Dv NDGBPORTS
326parameter is too small and there is only enough space allocated
327for
328.Ar N
329ports on this card.
330.It dgb\fIX\fP: port \fIY\fP is broken
331The on-board diagnostic has reported that the specified port has hardware
332problems.
333.It dgb\fIX\fP: polling of disabled board stopped
334Internal problems in the polling logic of driver.
335.It dgb\fIX\fP: event queue's head or tail is wrong!
336Internal problems in the driver or hardware.
337.It dgb\fIX\fP: port \fIY\fP: got event on nonexisting port
338Some status changed on a port that is physically present but is
339unusable due to misconfiguration.
340.It dgb\fIX\fP: port \fIY\fP: event \fIN\fP mstat \fIM\fP lstat \fIK\fP
341The driver got a strange event from card.
342Probably this means that you have a
343newer card with an extended list of events or some other hardware problem.
344.It dgb\fIX\fP: port \fIY\fP: overrun
345Input buffer has filled up.
346Problems in polling logic of driver.
347.It dgb\fIX\fP: port \fIY\fP: FEP command on disabled port
348Internal problems in driver.
349.It dgb\fIX\fP: port \fIY\fP: timeout on FEP command
350Problems in hardware.
351.El
352.Sh SEE ALSO
353.Xr stty 1 ,
354.Xr termios 4 ,
355.Xr tty 4 ,
2c272516 356.Xr comcontrol 8
984263bc
MD
357.Sh HISTORY
358The
359.Nm
360driver is derived from the
361.Xr sio 4
362driver and the DigiBoard driver from
363.Tn Linux
364and is
365.Ud
366.Sh BUGS
367The implementation of sending
368.Dv BREAK
369is broken.
370.Dv BREAK
aa0d550a 371of fixed length of \(14 s
984263bc
MD
372is sent anyway.
373.Pp
374There was a bug in implementation of
375.Xr select 2 .
376It is fixed now but not widely tested yet.
377.Pp
378There is no ditty command.
379Most of its functions (alternate pinout,
380speed up to 115200 baud, etc.) are implemented in the driver itself.
381Some
382other functions are missing.
510041ad
TN
383.Pp
384The
385.Nm
386driver is deprecated, please consider the
387.Xr digi 4
388driver.