Oops, cvs add a man page for the cy driver.

1 files changed, 241 insertions, 0 deletions

diff --git a/share/man/man4/cy.4 b/share/man/man4/cy.4
new file mode 100644
index 0000000..c1e2dbd
--- /dev/null
+++ b/share/man/man4/cy.4
@@ -0,0 +1,241 @@
+.\" 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.16 1995/06/26 06:05:30 bde Exp $
+.\"	$Id$
+.\"
+.Dd October 10, 1995
+.Dt CY 4 i386
+.Os FreeBSD
+.Sh NAME
+.Nm cy
+.Nd
+Cyclades Cyclom-8Y and Cyclom-16Y serial driver
+.Sh SYNOPSIS
+.Cd "device cy0 at isa? tty irq 10 iomem 0xd4000 iosiz 0x2000 vector cyintr
+.Cd "device cy1 at isa? tty irq 11 iomem 0xd6000 iosiz 0x2000 vector cyintr
+.sp
+Minor numbering:
+.br
+0b\fIOLIMMMMM\fR
+.br
+  call\fBO\fRut
+.br
+   \fBL\fRock
+.br
+    \fBI\fRnitial
+.br
+     \fBMMMMMM\fRinor
+.Sh DESCRIPTION
+The
+.Nm cy
+driver provides support for Cyrix CD1400-based
+.Tn EIA
+.Tn RS-232C
+.Pf ( Tn CCITT
+.Tn V.24 )
+communications interfaces (ports) on Cyclades Cyclom-Y boards.
+Each CD1400 provides 4 ports.
+Each Cyclom-8Y has 2 CD1400's giving 8 ports.
+Each Cyclom-16Y's has 4 CD1400's giving 16 ports.
+.Pp
+Input and output for each line may set independently
+to the following speeds:
+50, 75, 110, 134.5, 150, 300, 600, 1200, 1800, 2400, 4800, 9600,
+19200, 38400, 57600, or 115200 bps.
+Other speeds of up to 150000 are supported by the termios interface
+but not by the sgttyb compatibility interface.
+The CD1400 is not fast enough to handle speeds above 115200 bps
+effectively.
+It can transmit on a single line at slightly more than 115200 bps,
+but when 4 lines are active in both directions its limit is about
+90000 bps on each line.
+.\" 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 change was s/sio/cy/g.
+.Pp
+Serial ports controlled by the
+.Nm cy
+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 cy
+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
+work with almost arbitrary initial states and almost 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/ttyic? -compact
+.\" XXX more cloning: s/d/c/g.
+.It Pa /dev/ttyc?
+for callin ports
+.It Pa /dev/ttyic?
+.It Pa /dev/ttylc?
+corresponding callin initial-state and lock-state devices
+.sp
+.\" XXX more cloning: s/a/c/g.  No consistency :-(.
+.It Pa /dev/cuac?
+for callout ports
+.It Pa /dev/cuaic?
+.It Pa /dev/cualc?
+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
+.\" XXX no examples in rc.serial for cy ports specifically.
+for sio ports (change the device names for cy ports)
+.El
+.Pp
+The devices numbers are made from the set [0-9a-v] so that more than
+10 ports can be supported.
+.\" XXX this is for cy only.
+[0-9a-f] are for the cy0 and [g-v] are for cy1.
+For Cyclom-8Y's, only the first 8 of these are used.
+.Sh DIAGNOSTICS
+.Bl -diag
+.\" XXX back to s/sio/cy/g.
+.It cy%d: silo overflow.
+Problem in the interrupt handler.
+.El
+.Bl -diag
+.It cy%d: interrupt-level buffer overflow.
+Problem in the bottom half of the driver.
+.El
+.Bl -diag
+.It cy%d: tty-level buffer overflow.
+Problem in the application.
+Input has arrived faster than the given module could process it
+and some has been lost.
+.El
+.\" .Bl -diag
+.\" .It sio%d: reduced fifo trigger level to %d.
+.\" Attempting to avoid further silo overflows.
+.\" .El
+.Sh SEE ALSO
+.Xr tty 4 ,
+.Xr termios 4 ,
+.Xr comcontrol 8 ,
+.Xr stty 1 .
+.Sh HISTORY
+The
+.Nm
+driver is derived from the
+.Nm sio
+driver and the NetBSD
+.Nm
+driver and is
+.Ud
+.Sh BUGS
+The naming scheme and the minor numbering scheme limit the number
+of ports to 32.
+.Pp
+BREAK is not yet implemented.
+.Pp
+Serial consoles are not implemented.
+.Pp
+Data loss may occur at very high baud rates on slow systems,
+or with too many ports on any system,
+or on heavily loaded systems when crtscts cannot be used.
+.Pp
+There are too many compile-time-only flags.
+The CD1400 has slightly smaller fifos than the NS16550 (12 bytes
+instead of 16), so it needs pseudo-dma more than a NS16550.  The
+default configuration is optimized for generality at about a 30%
+relative cost in efficiency.  These compile-time defines may be
+changed for higher efficiency:
+.Pp
+RxFifoThreshold: default 6; on a 486DX-33, this works for 8 ports
+talking to each other at 115200 bps; 11 works for 8 ports talking
+to each other at 57600 bps.  The low threshold is not for FreeBSD,
+it's for the CD1400, which can't really keep up with 115200 bps.
+.Pp
+PollMode: required for Cyclom-16Y's; costs 10-20% relative efficiency
+on Cyclom-8Y's (more with a low RxFifoThreshold).
+.Pp
+SOFT_HOTCHAR: required in addition to the small RxFifoThreshold
+to avoid overruns with SLIP and PPP for 8 ports at 115200 bps.
+Costs 5% relative efficiency.