Document the compat-mode settings.

Thanks to Ingo for his help.

ok schwarze@

1 files changed, 93 insertions, 4 deletions

diff --git a/share/man/man4/wsmouse.4 b/share/man/man4/wsmouse.4
index 66cfc0e9f07..b238b1bf7ef 100644
--- a/share/man/man4/wsmouse.4
+++ b/share/man/man4/wsmouse.4
@@ -1,6 +1,7 @@
-.\" $OpenBSD: wsmouse.4,v 1.19 2016/09/03 14:36:14 jmc Exp $
+.\" $OpenBSD: wsmouse.4,v 1.20 2018/02/04 20:29:59 bru Exp $
 .\" $NetBSD: wsmouse.4,v 1.3 1999/12/06 14:52:08 augustss Exp $
 .\"
+.\" Copyright (c) 2018 Ulf Brosziewski <bru@openbsd.org>
 .\" Copyright (c) 1999
 .\" 	Matthias Drochner.  All rights reserved.
 .\"
@@ -25,7 +26,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: September 3 2016 $
+.Dd $Mdocdate: February 4 2018 $
 .Dt WSMOUSE 4
 .Os
 .Sh NAME
@@ -36,16 +37,18 @@
 .Sh DESCRIPTION
 The
 .Nm
-driver is an abstraction layer for mice within the
+driver is an abstraction layer for mice and other pointing devices within the
 .Xr wscons 4
 framework.
-It is attached to the hardware specific mouse drivers and
+It is attached to the hardware specific drivers and
 provides a character device interface which returns
 .Fa struct wscons_event
 via
 .Xr read 2 .
 For use with X servers,
 .Dq mouse events
+or
+.Dq touch events
 can be generated.
 .Pp
 The
@@ -55,6 +58,92 @@ driver provides a number of ioctl functions to control various parameters (see
 The
 .Xr wsconsctl 8
 utility gives access to these variables.
+.Pp
+Touchpad input is processed in one of two modes:
+In
+.Dq absolute mode ,
+the
+.Nm
+driver generates touch events.
+Absolute mode is activated by
+.Xr synaptics 4 .
+In
+.Dq compatibility mode ,
+which is the default,
+.Nm
+converts the input internally and generates mouse events.
+.Xr wsconsctl 8
+can query and set several configuration parameters for this mode.
+The composite field names have the form
+.Cm mouse Ns Oo Ar N Oc . Ns Cm tp . Ns Ar field
+where
+.Ar N
+is the index of the
+.Nm
+device.
+If
+.Ar N
+is omitted, commands apply to
+.Pa /dev/wsmouse0 .
+.Bl -tag -width Ds
+.It Cm mouse.tp.tapping
+Setting this parameter to a non-zero value enables tap gestures.
+Contacts on the touchpad that are immediately released again
+trigger click events.
+One-finger, two-finger, and three-finger taps generate left-button,
+right-button, and middle-button clicks, respectively.
+If, within a short time interval, a second touch follows a one-finger
+tap, the button-up event is not issued until that touch ends
+.Pq Dq tap-and-drag .
+.It Cm mouse.tp.scaling
+The value is a scale coefficient that is applied to the relative
+coordinates.
+It determines the base speed of the pointer.
+.It Cm mouse.tp.swapsides
+If this parameter has a non-zero value, the order of software
+button areas is inverted.
+If edge scrolling is enabled, the scroll area is set up at the left
+edge of the touchpad.
+.It Cm mouse.tp.disable
+A non-zero value disables pointer movement, tapping, and scrolling.
+Software buttons (and external physical buttons) will work as usual.
+.It Cm mouse.tp.edges
+This field contains a list of four values that define the relative
+sizes of the edge areas, in the order:
+.Bd -literal -offset indent
+.Sm off
+.Ar top , right , bottom , left
+.Sm on
+.Ed
+.Pp
+The unit is percent of the total height of the touchpad surface, or
+of its total width, respectively.
+In order to mitigate the effects of accidental touches, the driver
+ignores most types of input from an edge area (see below).
+If an edge area contains software buttons, they fill up the space
+provided.
+.El
+.Pp
+The automatic configuration enables two-finger scrolling and sets up
+edge areas at the vertical edges.
+On clickpads - where the device surface serves as a single, large
+button - it provides three software button areas at the bottom edge,
+for left-button, middle-button, and right-button clicks.
+On some laptops with a trackpoint, the software buttons are at the
+top edge.
+Vertical edge scrolling will be enabled on older touchpads that do not
+report contact counts.
+.Pp
+A touch that starts and remains in an edge area does not trigger pointer
+movement.
+At the vertical edges and the top edge, tapping and two-finger scrolling
+require that at least one touch is in the main area of the touchpad (the
+exact behaviour of a single-touch device depends on its firmware in this
+case).
+When multi-touch input is available, a touch is ignored if it rests in
+the bottom area while there are other inputs - movement, scrolling, or
+tapping -, and the driver continues to ignore it as long as and whenever
+other touches are present.
 .Sh FILES
 .Bl -tag -width /usr/include/dev/wscons/wsconsio.h -compact
 .It Pa /dev/wsmouse*