Added a manpage for the tw device. Changed the Makefile to install that

manpage into the proper place.

1 files changed, 111 insertions, 0 deletions

diff --git a/share/man/man4/man4.i386/tw.4 b/share/man/man4/man4.i386/tw.4
new file mode 100644
index 000000000000..8c093e58ae53
--- /dev/null
+++ b/share/man/man4/man4.i386/tw.4
@@ -0,0 +1,111 @@
+.\" Copyright (c) 1992, 1993 Eugene W. Stark
+.\" All rights reserved.
+.\"
+.\" 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 Eugene W. Stark.
+.\" 4. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY EUGENE W. STARK (THE AUTHOR) ``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 AUTHOR 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.
+.\"
+.Th XTEN 8 "30 Oct 1993"
+.Dd Oct 30, 1993
+.Dt TW 4
+.Os BSD FreeBSD
+.Sh NAME
+tw \- TW-523 X-10 device driver
+.Sh DESCRIPTION
+.Nm Tw
+is the driver for the TW-523 power line interface, for use with X-10 home
+control products.  The X-10 protocol is compatible with a number of home
+control systems, including Radio Shack ``Plug 'n Power(tm)'' and
+Stanley ``Lightmaker(tm).''
+.Pp
+The driver supports
+.Fn read
+.Fn write
+and
+.Fn select
+system calls.
+The driver allows multiple processes to read and write simultaneously,
+but there is probably not much sense in having more than one reader or more
+than one writer at a time, and in fact there may currently be a race
+condition in the driver if two processes try to transmit simultaneously
+(due to unsynchronized access to the sc_pkt structure in tw_sc).
+.Pp
+Transmission is done by calling
+.Fn write
+to send three byte packets of data.
+The first byte contains a four bit house code (0=A to 15=P).  The second byte
+contains a five bit unit/key code (0=unit 1 to 15=unit 16, 16=All Units Off
+to 31 = Status Request).  The third byte specifies the number of times the
+packet is to be transmitted without any gaps between successive transmissions.
+Normally this is 2, as per the X-10 documentation, but sometimes (e.g. for
+bright and dim codes) it can be another value.  Each call to
+.Fn write
+can specify
+an arbitrary number of data bytes, but at most one packet will actually be
+processed in any call.  Any incomplete packet is buffered until a subsequent
+call to
+.Fn write
+provides data to complete it.  Successive calls to
+.Fn write
+leave a three-cycle gap between transmissions, per the X-10 documentation.
+The driver transmits each bit only once per half cycle, not three times as
+the X-10 documentation states, because the TW523 only provides sync on
+each power line zero crossing.  So, the driver will probably not work
+properly if you have three-phase service.  Most residences use a two-wire
+system, for which the driver does work.
+.Pp
+Reception is done using
+.Fn read
+The driver produces a series of three
+character packets.  In each packet, the first character consists of flags,
+the second character is a four bit house code (0-15), and the third character
+is a five bit key/function code (0-31).  The flags are the following:
+.Bl -diag
+.It
+#define TW_RCV_LOCAL	1  /* The packet arrived during a local transmission */
+.It
+#define TW_RCV_ERROR	2  /* An invalid/corrupted packet was received */
+.El
+.Pp
+The
+.Fn select
+system call can be used in the usual way to determine if there
+is data ready for reading.
+.Sh SEE ALSO
+.Bl -diag
+.It
+.Xr xten 1
+.It
+.Xr xtend 8
+.It
+TW-523 documentation from X-10 Inc.
+.El
+.Sh FILES
+.Bl -tag -width /dev/tw
+.It Pa /dev/tw?
+the TW523 special file
+.El
+.Sh AUTHOR
+Eugene W. Stark (stark@cs.sunysb.edu)