Add and enable a man page for si(4) - the specialix serial driver..

I couldn't use the original, as it had unusable copyright on the manpage..

(now that must be a first.. the source copyright was fine, the manpage
was not..)

1 files changed, 169 insertions, 0 deletions

diff --git a/share/man/man4/si.4 b/share/man/man4/si.4
new file mode 100644
index 0000000..aa346f6
--- /dev/null
+++ b/share/man/man4/si.4
@@ -0,0 +1,169 @@
+.\" $Id$
+.\" The following requests are required for all man pages.
+.Dd September 16, 1995
+.Os FreeBSD
+.Dt SI 4
+.Sh NAME
+.Nm si
+- Driver for Specialix International SI/XIO 8-32 port intelligent serial card.
+.Sh SYNOPSIS
+.Nm "device si0 at isa? tty irq 12 iomem 0xd0000 vector siintr"
+.Sh DESCRIPTION
+The Specialix SI and XIO hardware makes up an 8 to 32 port RS-232 serial
+multiplexor.
+.Pp
+This driver was ported and tested on an ISA bus machine, and has rudimentry
+support for operation on an EISA bus system as well, but as of this time the
+EISA version has not been tested by the Author - it may or may not work.
+.Pp
+The system uses two components..  A "Host adapter", which is plugged into
+an ISA/EISA slot and provides intelligence and buffering/processing
+capabilities, as well as an external bus in the form of a 50 pin cable.
+.Pp
+On this cable, "modules" are connected.  The "SI" module comes in a 4 and 8
+port version, and has simple UARTS.  The "XIO" module comes only in an 8 port
+version, and has two powerful RISC-like UARTS as well.
+.Pp
+The host adapter polls and transfers data between the modules and the main
+Operating system.  The Host adapter provides a 256 byte transmit and 256 byte
+receive FIFO for each of the 32 ports that it can maintain.
+.Pp
+The XIO module panels can operate each of their 8 ports at 115,200 baud, while
+the SI version can run at 57,600 baud.
+.Pp
+The host adapter uses a shared memory block in the traditional ISA bus
+"hole" betweem 0xA0000 and 0xEFFFF.  The adapter can be configured outside
+range, but requires the memory range to be explicitly non-cached.  The
+driver does not yet support this mode of operation.
+.Pp
+The adapter can use Irq's 11, 12 or 15.  It is rumoured that the ISA adapter
+cards provide their own tri-state drivers and pullups, and may be able to
+share an IRQ between all SI/XIO host cards.  This has not been tested, and
+the driver does not support this mode of operation.  The actual IRQ used is 
+soft-configured onto the host card at boot time, but automatic selection
+of a free IRQ is not yet implemented in the FreeBSD version.
+.Pp
+The si device driver may have some of it's configuration settings changed
+at run-time with the
+.Xr sicontrol 8
+utility.
+.Pp
+The si device driver also responds to the
+.Xr comcontrol 8
+utility for configuring drain-on-close timeouts.
+.Pp
+An open on a /dev device node controlled by the si driver obeys the same
+semantics as the
+.Xr sio 4
+driver.  It fully supports the usual semantics of the cua ports, and the
+"initial termios" and "locked termios" settings.  In summary, an open on a
+tty port will block until DCD is raised, unless O_NONBLOCK is specified.
+CLOCAL is honored.  An open on a cua port will always succeed, but DCD
+transitions will be honored after DCD rises for the first time.
+by the si driver obeys the same
+semantics as the
+.Xr sio 4
+driver.  It fully supports the usual semantics of the cua ports, and the
+"initial termios" and "locked termios" settings.  In summary, an open on a
+tty port will block until DCD is raised, unless O_NONBLOCK is specified.
+CLOCAL is honored.  An open on a cua port will always succeed, but DCD
+transitions will be honored after DCD rises for the first time.
+.Pp
+Normally, up to four SI/XIO host cards may be controlled by the si driver,
+but due to the lack of available interrupts that the card can be configured
+to use, only three may be presently used.  Polling operation is not currently
+implemented, although it is a standard mode of operation for Specialix shipped
+drivers.  Once this is implemented, all four cards may be used.
+.Pp
+The lowest 5 bits of the minor device number are used to select the port
+number on the mudule cluster.
+si driver,
+but due to the lack of available interrupts that the card can be configured
+to use, only three may be presently used.  Polling operation is not currently
+implemented, although it is a standard mode of operation for Specialix shipped
+drivers.  Once this is implemented, all four cards may be used.
+.Pp
+The lowest 5 bits of the minor device number are used to select the port
+number on the mudule cluster. The next 2 bits select which of 4 host adapter
+cards.  This allows a maximum of 128 ports on this driver.
+.Pp
+Bit 7 is used to differentiate a tty/dialin port (bit 7=0) and a
+cua/callout port (bit 7=1).
+.Pp
+Bit 8 through 15 (on FreeBSD) are unavailable as they are a shadow of the
+major device number.
+.Pp
+If bit 16 is a 1, the device node is referring to the "initial state" device.
+This "initial state" is used to prime the
+.Xr termios 4
+settings of the device when it is initially opened.
+If bit 17 is a 1, the device node is referring to the "locked state" device.
+The "locked state" is used to prevent the
+.Xr termios 4
+settings from being changed.
+.Pp
+To manipulate the initial/locked settings, the 
+.Xr stty 1
+command is useful.  When setting the "locked" variables, enabling the mode
+on the lock device will lock the termios mode, while disabling the mode will
+unlock it.
+.\" The following requests should be uncommented and used where appropriate.
+.\" This next request is for sections 2 and 3 function return values only.
+.\" .Sh RETURN VALUES
+.\" This next request is for sections 1, 6, 7 & 8 only
+.\" .Sh ENVIRONMENT
+.Sh FILES
+.Bl -tag -width /dev/si_control -compact
+.It Pa /dev/si_control
+global driver control file for
+.Xr sicontrol 8
+.It Pa /dev/ttyA*
+terminal/dialin ports
+.It Pa /dev/cuaA*
+dialout ports
+.It Pa /dev/ttyiA*
+initial termios state devices
+.It Pa /dev/ttylA*
+locked termios state devices
+.El
+.\" .Sh EXAMPLES
+.\" This next request is for sections 1, 6, 7 & 8 only
+.\"     (command return values (to shell) and fprintf/stderr type diagnostics)
+.\" .Sh DIAGNOSTICS
+.\" The next request is for sections 2 and 3 error and signal handling only.
+.\" .Sh ERRORS
+.Sh SEE ALSO
+.Xr stty 1 ,
+.Xr termios 4 ,
+.Xr tty 4 ,
+.Xr sio 4 ,
+.Xr sicontrol 8 ,
+.Xr comcontrol 8 .
+.\" .Sh STANDARDS
+.Sh HISTORY
+This driver is loosely based on driver code originating at Specialix, which
+was ported to run on BSDI by
+.Nm Andy Rutter <andy@specialix.co.uk> .
+The System V driver source is/was available by ftp from
+.Nm ftp.specialix.co.uk .
+.Pp
+This driver is not supported by Specialix International. 
+.Sh AUTHORS
+.Nm Peter Wemm <peter@freebsd.org>
+obtained the code from Andy Rutter and ported it to FreeBSD, with a large
+amount of invalueable assistance from
+.Nm Bruce Evans <bde@zeta.org.au>
+.Pp
+Man page by Peter Wemm.
+.Sh BUGS
+The EISA support is untested.
+.Pp
+The interrupt tuning rate is not believed to be optimal at this time for
+maximum efficiency.
+.Pp
+Receiver tty buffer flushing is not yet enabled, like many other drivers.
+.Pp
+POLL mode is not implemented yet.
+.Pp
+Operation outside the traditional ISA "hole" is not yet supported, although it
+should work if the test is removed from the probe routine.