share/man/man4/digi.4

   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. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     from: @(#)dca.4 5.2 (Berkeley) 3/27/91
  32 .\"     from: com.4,v 1.1 1993/08/06 11:19:07 cgd Exp
  33 .\"     from: sio.4,v 1.15 1994/12/06 20:14:30 bde Exp
  34 .\" $FreeBSD: src/share/man/man4/man4.i386/dgb.4,v 1.13.2.6 2001/08/17 13:08:45 ru Exp $
  35 .\"
  36 .Dd August 6, 2009
  37 .Dt DIGI 4
  38 .Os
  39 .Sh NAME
  40 .Nm digi
  41 .Nd DigiBoard intelligent serial cards driver
  42 .Sh SYNOPSIS
  43 To compile this driver into the kernel, place the following line in your
  44 kernel configuration file:
  45 .Bd -ragged -offset indent
  46 .Cd "device digi"
  47 .Ed
  48 .Pp
  49 To load this driver as a module at boot time, place the following line in
  50 .Xr loader.conf 5 :
  51 .Bd -literal -offset indent
  52 digi_load="YES"
  53 .Ed
  54 .Sh DESCRIPTION
  55 The
  56 .Nm
  57 driver provides support for DigiBoard PC/Xe and PC/Xi series intelligent
  58 serial multiport cards with asynchronous interfaces based on the
  59 .Tn EIA
  60 .Tn RS-232C
  61 .Pf ( Tn CCITT
  62 .Tn V.24 )
  63 standard.
  64 .Pp
  65 Input and output for each line may set to one of following baud rates;
  66 50, 75, 110, 134.5, 150, 300, 600, 1200, 1800, 2400, 4800, 9600,
  67 19200, 38400, 57600, or for newer versions of cards 115200.
  68 .Pp
  69 The driver doesn't use any interrupts, it is
  70 .Dq polling\-based .
  71 This means that
  72 it uses clock interrupts instead of interrupts generated by DigiBoard cards and
  73 checks the state of cards 25 times per second.
  74 This is practical because the
  75 DigiBoard cards have large input and output buffers (more than 1Kbyte per
  76 port) and hardware that allows efficiently finding the port that needs
  77 attention.
  78 The only problem seen with this policy is slower
  79 SLIP and PPP response.
  80 .Pp
  81 Each line in the kernel configuration file describes one card, not one port
  82 as in the
  83 .Xr sio 4
  84 driver.
  85 .Pp
  86 Serial ports controlled by the
  87 .Nm
  88 driver can be used for both
  89 .Dq callin
  90 and
  91 .Dq callout .
  92 For each port there is a callin device and a callout device.
  93 The minor number of the callout device is 128 higher
  94 than that of the corresponding callin port.
  95 The callin device is general purpose.
  96 Processes opening it normally wait for carrier
  97 and for the callout device to become inactive.
  98 The callout device is used to steal the port from
  99 processes waiting for carrier on the callin device.
 100 Processes opening it do not wait for carrier
 101 and put any processes waiting for carrier on the callin device into
 102 a deeper sleep so that they do not conflict with the callout session.
 103 The callout device is abused for handling programs that are supposed
 104 to work on general ports and need to open the port without waiting
 105 but are too stupid to do so.
 106 .Pp
 107 The
 108 .Nm
 109 driver also supports an initial-state and a lock-state control
 110 device for each of the callin and the callout
 111 .Dq data
 112 devices.
 113 The minor number of the initial-state device is 32 higher
 114 than that of the corresponding data device.
 115 The minor number of the lock-state device is 64 higher
 116 than that of the corresponding data device.
 117 The termios settings of a data device are copied
 118 from those of the corresponding initial-state device
 119 on first opens and are not inherited from previous opens.
 120 Use
 121 .Xr stty 1
 122 in the normal way on the initial-state devices to program
 123 initial termios states suitable for your setup.
 124 .Pp
 125 The lock termios state acts as flags to disable changing
 126 the termios state.
 127 E.g., to lock a flag variable such as
 128 .Dv CRTSCTS ,
 129 use
 130 .Dq Li "stty crtscts"
 131 on the lock-state device.
 132 Speeds and special characters
 133 may be locked by setting the corresponding value in the lock-state
 134 device to any nonzero value.
 135 .Pp
 136 Correct programs talking to correctly wired external devices
 137 .\" XXX change next line in other man pages too, and rewrite this paragraph.
 138 work with almost arbitrary initial states and no locking,
 139 but other setups may benefit from changing some of the default
 140 initial state and locking the state.
 141 In particular, the initial states for non (POSIX) standard flags
 142 should be set to suit the devices attached and may need to be
 143 locked to prevent buggy programs from changing them.
 144 E.g.,
 145 .Dv CRTSCTS
 146 should be locked on for devices that support
 147 RTS/CTS handshaking at all times and off for devices that don't
 148 support it at all.
 149 .Dv CLOCAL
 150 should be locked on for devices
 151 that don't support carrier.
 152 .Dv HUPCL
 153 may be locked off if you don't
 154 want to hang up for some reason.
 155 In general, very bad things happen
 156 if something is locked to the wrong state, and things should not
 157 be locked for devices that support more than one setting.
 158 The
 159 .Dv CLOCAL
 160 flag on callin ports should be locked off for logins
 161 to avoid certain security holes, but this needs to be done by
 162 getty if the callin port is used for anything else.
 163 .Sh FILES
 164 .Bl -tag -width /dev/ttyiD?? -compact
 165 .It Pa /dev/ttyD??
 166 for callin ports
 167 .It Pa /dev/ttyiD??
 168 .It Pa /dev/ttylD??
 169 corresponding callin initial-state and lock-state devices
 170 .Pp
 171 .It Pa /dev/cuaD??
 172 for callout ports
 173 .It Pa /dev/cuaiD??
 174 .It Pa /dev/cualD??
 175 corresponding callout initial-state and lock-state devices
 176 .El
 177 .Pp
 178 .Bl -tag -width /etc/rc.d/serial -compact
 179 .It Pa /etc/rc.d/serial
 180 examples of setting the initial-state and lock-state devices
 181 .El
 182 .Pp
 183 The first question mark in these device names is short for the
 184 card number
 185 (a decimal number between 0 and 65535 inclusive).
 186 The second question mark is short for the port number
 187 (a letter in the range [0-9a-v]).
 188 .Sh DIAGNOSTICS
 189 You may enable extended diagnostics by defining DEBUG at the
 190 start of the source file
 191 .Pa digi.c .
 192 .Bl -diag
 193 .It digi\fIX\fP: warning: address \fIN\fP truncated to \fIM\fP
 194 The memory address for the PC/Xe's 8K window is misaligned (it should be
 195 on an 8K boundary) or outside of the first megabyte.
 196 .It digi\fIX\fP: 1st reset failed
 197 Problems with accessing I/O port of the card, probably
 198 the wrong
 199 .Cm port
 200 value is specified in the kernel config file.
 201 .It digi\fIX\fP: 2nd reset failed
 202 Problems with hardware.
 203 .It digi\fIX\fP: \fIN\fP[st,nd,rd,th] memory test failed
 204 Problems with accessing the memory of the card, probably
 205 the wrong
 206 .Cm iomem
 207 value is specified in the kernel config file.
 208 .It digi\fIX\fP: BIOS start failed
 209 Problems with starting the on-board BIOS.
 210 Probably the memory addresses of the
 211 DigiBoard overlap with some other device or with RAM.
 212 .It digi\fIX\fP: BIOS download failed
 213 Problems with the on-board BIOS.
 214 Probably the memory addresses of the
 215 DigiBoard overlap with some other device or with RAM.
 216 .It digi\fIX\fP: FEP code download failed
 217 Problems with downloading of the Front-End Processor's micro-OS.
 218 Probably the memory addresses of the
 219 DigiBoard overlap with some other device or with RAM.
 220 .It digi\fIX\fP: FEP/OS start failed
 221 Problems with starting of the Front-End Processor's micro-OS.
 222 Probably the memory addresses of the
 223 DigiBoard overlap with some other device or with RAM.
 224 .It digi\fIX\fP: too many ports
 225 This DigiBoard reports that it has more than 32 ports.
 226 Perhaps a hardware problem or
 227 the memory addresses of the
 228 DigiBoard overlap with some other device or with RAM.
 229 .It digi\fIX\fP: port \fIY\fP is broken
 230 The on-board diagnostic has reported that the specified port has hardware
 231 problems.
 232 .It digi\fIX\fP: polling of disabled board stopped
 233 Internal problems in the polling logic of driver.
 234 .It digi\fIX\fP: event queue's head or tail is wrong!
 235 Internal problems in the driver or hardware.
 236 .It digi\fIX\fP: port \fIY\fP: got event on nonexisting port
 237 Some status changed on a port that is physically present but is
 238 unusable due to misconfiguration.
 239 .It digi\fIX\fP: port \fIY\fP: event \fIN\fP mstat \fIM\fP lstat \fIK\fP
 240 The driver got a strange event from card.
 241 Probably this means that you have a
 242 newer card with an extended list of events or some other hardware problem.
 243 .It digi\fIX\fP: port \fIY\fP: overrun
 244 Input buffer has filled up.
 245 Problems in polling logic of driver.
 246 .It digi\fIX\fP: port \fIY\fP: FEP command on disabled port
 247 Internal problems in driver.
 248 .It digi\fIX\fP: port \fIY\fP: timeout on FEP command
 249 Problems in hardware.
 250 .El
 251 .Sh SEE ALSO
 252 .Xr stty 1 ,
 253 .Xr termios 4 ,
 254 .Xr tty 4 ,
 255 .Xr comcontrol 8
 256 .Sh HISTORY
 257 The
 258 .Nm
 259 driver is derived from the
 260 .Xr sio 4
 261 driver and the DigiBoard driver from
 262 .Tn Linux
 263 and is
 264 .Ud
 265 .Sh BUGS
 266 The implementation of sending
 267 .Dv BREAK
 268 is broken.
 269 .Dv BREAK
 270 of fixed length of \(14 s
 271 is sent anyway.
 272 .Pp
 273 There was a bug in implementation of
 274 .Xr select 2 .
 275 It is fixed now but not widely tested yet.
 276 .Pp
 277 There is no ditty command.
 278 Most of its functions (alternate pinout,
 279 speed up to 115200 baud, etc.) are implemented in the driver itself.
 280 Some
 281 other functions are missing.