[src/trunk]: src/share/man/man4 Document PPS_SYNC for com(4) and zstty(4) (th...

[fair <fair%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/be750359d965
branches:  trunk
changeset: 765847:be750359d965
user:      fair <fair%NetBSD.org@localhost>
date:      Tue Jun 07 18:02:35 2011 +0000

description:
Document PPS_SYNC for com(4) and zstty(4) (the only serial drivers
in which NetBSD currently supports the option), with cross reference
to ntpd(8) and options(4).

diffstat:

 share/man/man4/com.4     |  27 ++++++++++++++++++++++++---
 share/man/man4/options.4 |  25 +++++++++++++++++++------
 share/man/man4/zstty.4   |  32 +++++++++++++++++++++++++++++---
 3 files changed, 72 insertions(+), 12 deletions(-)

diffs (209 lines):

diff -r 27f80c525cb2 -r be750359d965 share/man/man4/com.4
--- a/share/man/man4/com.4      Tue Jun 07 17:51:58 2011 +0000
+++ b/share/man/man4/com.4      Tue Jun 07 18:02:35 2011 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: com.4,v 1.16 2010/05/31 09:30:55 skrll Exp $
+.\"    $NetBSD: com.4,v 1.17 2011/06/07 18:02:35 fair Exp $
 .\"
 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
 .\" All rights reserved.
@@ -32,12 +32,13 @@
 .\"
 .\"     from: @(#)dca.4        5.2 (Berkeley) 3/27/91
 .\"
-.Dd May 31, 2010
+.Dd June 7, 2011
 .Dt COM 4
 .Os
 .Sh NAME
 .Nm com
-.Nd serial communications interface
+.Nd serial communications interface for
+.Tn RS-232C
 .Sh SYNOPSIS
 .Cd "com0 at isa? port" \&"IO_COM1\&" irq 4
 .Cd "com1 at isa? port" \&"IO_COM2\&" irq 3
@@ -53,6 +54,8 @@
 .Cd "com* at puc? port ?"
 .Cd "com* at xirc?"
 .Cd options COM_HAYESP
+.Cd options PPS_SYNC
+.Cd options PPS_TRAILING_EDGE
 .Cd options RND_COM
 .Ss Arm32
 .Cd "com0 at mainbus? base 0x00210fe0"
@@ -94,6 +97,22 @@
 .Cd options COM_HAYESP
 adds support for the Hayes ESP serial board.
 .Pp
+.Cd options PPS_SYNC
+enables code to use the Data Carrier Detect (DCD) signal line for attachment
+to an external precision clock source
+.Po
+e.g., 
+.Tn GPS ,
+.Tn CDMA
+.Pc
+which generates a Pulse Per Second (PPS) signal.
+This is used by
+.Xr ntpd 8
+to discipline the system clock, and more accurately count/measure time.
+See
+.Xr options 4
+for more discussion.
+.Pp
 With
 .Cd options RND_COM
 enabled, the
@@ -141,7 +160,9 @@
 .Xr isapnp 4 ,
 .Xr mca 4 ,
 .Xr mhzc 4 ,
+.Xr ntpd 8 ,
 .Xr ofisa 4 ,
+.Xr options 4 ,
 .Xr pcmcia 4 ,
 .Xr pcmcom 4 ,
 .Xr pnpbios 4 ,
diff -r 27f80c525cb2 -r be750359d965 share/man/man4/options.4
--- a/share/man/man4/options.4  Tue Jun 07 17:51:58 2011 +0000
+++ b/share/man/man4/options.4  Tue Jun 07 18:02:35 2011 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: options.4,v 1.404 2011/04/26 22:17:17 wiz Exp $
+.\"    $NetBSD: options.4,v 1.405 2011/06/07 18:02:35 fair Exp $
 .\"
 .\" Copyright (c) 1996
 .\"    Perry E. Metzger.  All rights reserved.
@@ -1211,6 +1211,7 @@
 will employ a user-level PLL when kernel support is unavailable,
 but the in-kernel version has lower latency and more precision, and
 so typically keeps much better time.
+.Pp
 The interface to the kernel
 .Em NTP
 support is provided by the
@@ -1228,17 +1229,20 @@
 .It Cd options PPS_SYNC
 This option enables a kernel serial line discipline for receiving time
 phase signals from an external reference clock such as a radio clock.
-(The
+.Po
+The
 .Em NTP
 option (which see) must be on if the
 .Em PPS_SYNC
-option is used.)
+option is used
+.Pc .
 Some reference clocks generate a Pulse Per Second (PPS) signal in
 phase with their time source.
 The
 .Em PPS
 line discipline receives this signal on either the data leads
 or the DCD control lead of a serial port.
+.Pp
 .Em NTP
 uses the PPS signal to discipline the local clock oscillator to a high
 degree of precision (typically less than 50 microseconds in time and
@@ -1251,14 +1255,23 @@
 to account for it.
 Using
 .Em PPS
-usually requires a
-gadget box
-to convert from TTL to RS-232 signal levels.
+usually requires a gadget box
+to convert from
+.Tn TTL
+to
+.Tn RS-232
+signal levels.
 The gadget box and PPS are described in more detail in the HTML documentation
 for
 .Xr ntpd 8
 in
 .Pa /usr/share/doc/html/ntp .
+.Pp
+.Nx
+currently suppors this option in
+.Xr com 4
+and
+.Xr zsc 4 .
 .It Cd options SETUIDSCRIPTS
 Allows scripts with the setuid bit set to execute as the effective
 user rather than the real user, just like binary executables.
diff -r 27f80c525cb2 -r be750359d965 share/man/man4/zstty.4
--- a/share/man/man4/zstty.4    Tue Jun 07 17:51:58 2011 +0000
+++ b/share/man/man4/zstty.4    Tue Jun 07 18:02:35 2011 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: zstty.4,v 1.12 2008/04/30 13:10:55 martin Exp $
+.\"    $NetBSD: zstty.4,v 1.13 2011/06/07 18:02:35 fair Exp $
 .\"
 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd May 12, 2007
+.Dd June 7, 2011
 .Dt ZSTTY 4
 .Os
 .Sh NAME
@@ -36,8 +36,14 @@
 .Nm zs
 .Nd
 .Tn Zilog
-8530 serial communications interface
+8530 Serial Communications Controller (SCC) for
+.Tn RS-232C ,
+.Tn RS-422 ,
+and
+.Tn RS-423
 .Sh SYNOPSIS
+.Cd options PPS_SYNC
+.Cd options PPS_TRAILING_EDGE
 .Ss alpha ( DEC 3000 )
 .Cd "zsc0      at ioasic? offset 0x100000"
 .Cd "zsc1      at ioasic? offset 0x180000"
@@ -51,6 +57,7 @@
 .Ss mac68k and macppc
 .Cd "zsc0      at obio?"
 .Cd "zstty*    at zsc? channel ?"
+.Cd options ZS_TXDMA
 .Ss mipsco
 .Cd "zsc0      at obio0 addr 0xbb000000"
 .Cd "zstty0    at zsc0 channel 0"
@@ -139,6 +146,23 @@
 .Pp
 Input and output for each line may set to any baud rate in the
 range 50 to 38400 (and higher on some machines).
+.Pp
+The
+.Em PPS_SYNC
+option enables code to use the Data Carrier Detect (DCD) signal line for attachment
+to an external precision clock source
+.Po
+e.g., 
+.Tn GPS ,
+.Tn CDMA
+.Pc
+which generates a Pulse Per Second (PPS) signal.
+This is used by
+.Xr ntpd 8
+to discipline the system clock, and more accurately count/measure time.
+See
+.Xr options 4
+for more discussion.
 .Sh FILES
 .Ss alpha
 .Bl -tag -width Pa
@@ -171,6 +195,8 @@
 .Sh SEE ALSO
 .Xr kbd 4 ,
 .Xr ms 4 ,
+.Xr ntpd 8 ,
+.Xr options 4 ,
 .Xr scc 4 ,
 .Xr tty 4
 .Sh HISTORY