[src/trunk]: src Add man page for uatp(4).

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

details:   https://anonhg.NetBSD.org/src/rev/52626276d129
branches:  trunk
changeset: 780758:52626276d129
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sun Aug 05 14:28:50 2012 +0000

description:
Add man page for uatp(4).

diffstat:

 distrib/sets/lists/man/mi |    5 +-
 share/man/man4/Makefile   |    4 +-
 share/man/man4/uatp.4     |  176 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 182 insertions(+), 3 deletions(-)

diffs (231 lines):

diff -r f7dd8127ec5c -r 52626276d129 distrib/sets/lists/man/mi
--- a/distrib/sets/lists/man/mi Sun Aug 05 09:16:54 2012 +0000
+++ b/distrib/sets/lists/man/mi Sun Aug 05 14:28:50 2012 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1400 2012/07/30 18:57:17 degroote Exp $
+# $NetBSD: mi,v 1.1401 2012/08/05 14:28:50 riastradh Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 #
@@ -1678,6 +1678,7 @@
 ./usr/share/man/cat4/txp.0                     man-sys-catman          .cat
 ./usr/share/man/cat4/u3g.0                     man-sys-catman          .cat
 ./usr/share/man/cat4/uark.0                    man-sys-catman          .cat
+./usr/share/man/cat4/uatp.0                    man-sys-catman          .cat
 ./usr/share/man/cat4/uaudio.0                  man-sys-catman          .cat
 ./usr/share/man/cat4/uax.0                     man-obsolete            obsolete
 ./usr/share/man/cat4/uberry.0                  man-sys-catman          .cat
@@ -4487,6 +4488,7 @@
 ./usr/share/man/html4/txp.html                 man-sys-htmlman         html
 ./usr/share/man/html4/u3g.html                 man-sys-htmlman         html
 ./usr/share/man/html4/uark.html                man-sys-htmlman         html
+./usr/share/man/html4/uatp.html                man-sys-htmlman         html
 ./usr/share/man/html4/uaudio.html              man-sys-htmlman         html
 ./usr/share/man/html4/uberry.html              man-sys-htmlman         html
 ./usr/share/man/html4/ubsa.html                        man-sys-htmlman         html
@@ -7219,6 +7221,7 @@
 ./usr/share/man/man4/txp.4                     man-sys-man             .man
 ./usr/share/man/man4/u3g.4                     man-sys-man             .man
 ./usr/share/man/man4/uark.4                    man-sys-man             .man
+./usr/share/man/man4/uatp.4                    man-sys-man             .man
 ./usr/share/man/man4/uaudio.4                  man-sys-man             .man
 ./usr/share/man/man4/uax.4                     man-obsolete            obsolete
 ./usr/share/man/man4/uberry.4                  man-sys-man             .man
diff -r f7dd8127ec5c -r 52626276d129 share/man/man4/Makefile
--- a/share/man/man4/Makefile   Sun Aug 05 09:16:54 2012 +0000
+++ b/share/man/man4/Makefile   Sun Aug 05 14:28:50 2012 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.590 2012/07/30 18:57:18 degroote Exp $
+#      $NetBSD: Makefile,v 1.591 2012/08/05 14:28:50 riastradh Exp $
 #      @(#)Makefile    8.1 (Berkeley) 6/18/93
 
 MAN=   aac.4 ac97.4 acardide.4 aceride.4 acphy.4 \
@@ -71,7 +71,7 @@
 
 # USB devices
 MAN+=  atu.4 aubtfwl.4 aue.4 axe.4 cdce.4 cue.4 ehci.4 kue.4 ohci.4 slhci.4 \
-       stuirda.4 u3g.4 uaudio.4 uberry.4 ubsa.4 ubt.4 uchcom.4 ucom.4 \
+       stuirda.4 u3g.4 uatp.4 uaudio.4 uberry.4 ubsa.4 ubt.4 uchcom.4 ucom.4 \
        ucycom.4 udav.4 udsbr.4 uftdi.4 ugen.4 ugensa.4 uhci.4 uhid.4 \
        uhidev.4 uhmodem.4 uhso.4 uipaq.4 uirda.4 ukbd.4 ukyopon.4 ulpt.4 \
        umass.4 umct.4 umidi.4 umodem.4 ums.4 upgt.4 upl.4 uplcom.4 \
diff -r f7dd8127ec5c -r 52626276d129 share/man/man4/uatp.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/uatp.4     Sun Aug 05 14:28:50 2012 +0000
@@ -0,0 +1,176 @@
+.\" $NetBSD: uatp.4,v 1.1 2012/08/05 14:28:50 riastradh Exp $
+.\"
+.\" Copyright (c) 2012 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Taylor R. Campbell.
+.\"
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
+.\"
+.Dd August 4, 2012
+.Dt UATP 4
+.Os
+.Sh NAME
+.Nm uatp
+.Nd USB Apple trackpad driver
+.Sh SYNOPSIS
+.Cd uatp* at uhidev? reportid ?
+.Cd wsmouse* at uatp? mux 0
+.Sh DESCRIPTION
+The
+.Nm
+driver provides support for the USB trackpads found in Apple laptops
+since 2005, exposed through
+.Xr wsmouse 4 .
+Some USB Apple trackpads are standard USB HID mice supported by
+.Xr ums 4 ,
+but
+.Nm
+supports more features.
+The following
+.Xr sysctl 8
+variables control behavior of USB Apple trackpads:
+.Bl -tag -width hw.uatpN.tap_track_distance_limit
+.It Dv hw.uatpN.two_finger_buttons
+Bit mask of buttons to emulate when two fingers are on the trackpad
+while the button is pressed.
+.It Dv hw.uatpN.three_finger_buttons
+Bit mask of buttons to emulate when three fingers are on the trackpad
+while the button is pressed.
+.It Dv hw.uatpN.multifinger_track
+What to do when multiple fingers are moved on the trackpad.
+If set to 0, ignore the input.
+If set to 1, move as if a single finger were at the mean position of
+the fingers.
+If set to 2, scroll.
+Note that scrolling is currently broken.
+.It Dv hw.uatpN.x_sensors
+Number of sensor columns detecting the x positions of fingers on the
+trackpad.
+The driver should detect this based on the model of hardware, so you
+should not have to set this, and likewise for the x ratio and y
+sensors and ratio.
+.It Dv hw.uatpN.x_ratio
+Ratio of the number of sensor columns in the trackpad to the number of
+distinct cursor x positions.
+.It Dv hw.uatpN.y_sensors
+Number of sensor rows detecting the y positions of fingers on the
+trackpad.
+.It Dv hw.uatpN.y_ratio
+Ratio of the number of sensor rows in the trackpad to the number of
+distinct cursor y positions.
+.It Dv hw.uatpN.sensor_threshold
+Nonnegative integer giving a lower bound on the
+.Dq pressure
+a sensor must report for the driver to recognize input from it.
+.It Dv hw.uatpN.sensor_normalizer
+Nonnegative integer to subtract from the
+.Dq pressure
+reported by a sensor when averaging them to estimate the pressure of a
+single finger.
+.It Dv hw.uatpN.palm_width
+If zero, palm detection is disabled.
+Otherwise, a positive integer giving the number of consecutive sensors
+wide or high that will be interpreted as a palm instead of a finger and
+therefore ignored.
+.It Dv hw.uatpN.old_raw_weight
+.It Dv hw.uatpN.old_smoothed_weight
+.It Dv hw.uatpN.new_raw_weight
+When a finger moves on the trackpad, the new smoothed (cursor) position
+is computed as a positive linear combination of the old raw (trackpad)
+position, the old smoothed position, and the new raw position.
+The weights of the linear combination are given by these sysctl knobs.
+.It Dv hw.uatpN.motion_threshold
+Threshold below which a difference in smoothed position will not be
+reported as an input event to userland.
+.It Dv hw.uatpN.motion_multiplier
+Positive integer by which a difference in smoothed position will be
+multiplied before passing it as an input event to userland.
+.It Dv hw.uatpN.motion_divisor
+Positive integer by which a difference in smoothed position will be
+divided, after multiplying it by the motion multiplier, before passing
+it as an input event to userland.
+.It Dv hw.uatpN.fast_motion_threshold
+Threshold above which to use the fast motion factors below.
+.It Dv hw.uatpN.fast_motion_multiplier
+Positive integer by which to multiply a large difference in smoothed
+position.
+.It Dv hw.uatpN.fast_motion_divisor
+Positive integer by which to divide a large difference in smoothed
+position, after multiplying it by the fast motion multiplier.
+.It Dv hw.uatpN.motion_delay
+Number of input packets before
+.Nm
+reports motion to userland.
+.It Dv hw.uatpN.tap_limit_msec
+Positive integer giving the number of milliseconds of a finger's
+contact with the trackpad before it will not be considered a tap.
+.It Dv hw.uatpN.double_tap_limit_msec
+Positive integer giving the maximum number of milliseconds after a tap
+before a second tap will keep the button down.
+.It Dv hw.uatpN.one_finger_tap_buttons
+Bit mask of buttons that a one-finger tap will press.
+.It Dv hw.uatpN.two_finger_tap_buttons
+Bit mask of buttons that a two-finger tap will press.
+.It Dv hw.uatpN.three_finger_tap_buttons
+Bit mask of buttons that a three-finger tap will press.
+.It Dv hw.uatpN.tap_track_distance_limit
+Maximum distance in smoothed position that will be interpreted as a tap
+instead of motion.
+.El
+.Sh SEE ALSO
+.Xr ums 4 ,
+.Xr wsmouse 4
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Nx 7.0 .
+.Sh AUTHORS
+The
+.Nm
+driver was originally written by
+.An Taylor R. Campbell Aq riastradh%NetBSD.org@localhost .
+.Sh BUGS
+Sometimes, particularly when X starts up, the driver gets wedged in an
+interrupt storm and does not reset the device.
+Setting
+.Li hw.uatpN.sensor_threshold
+to a large number, say 1000, and then back to its original value, can
+fix this.
+.Pp
+Palm detection is not very robust.
+.Pp
+Multi-touch scrolling is currently broken.
+.Pp
+Pinch-to-zoom and other fancy multi-touch input is not implemented.
+.Pp
+On suspending and resuming,
+.Nm
+detaches and reattaches, and loses all sysctl settings in the process.
+.Pp
+Do not submerge your
+.Nm
+devices in water: USB adenosine triphosphate is unstable in water, and
+will hydrolyze to USB adenosine diphosphate and phosphate, which is a
+lower energy state that makes your mouse narcoleptic in X.