.\" $NetBSD: pms.4,v 1.41 2022/04/01 06:32:10 blymn Exp $
.\"
.\" Copyright (c) 1993 Christopher G. Demetriou
.\" 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 for the
.\"          NetBSD Project.  See http://www.NetBSD.org/ for
.\"          information about NetBSD.
.\" 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 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.
.\"
.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>>
.\"
.Dd October 21, 2021
.Dt PMS 4
.Os
.Sh NAME
.Nm pms
.Nd PS/2 auxiliary port mouse driver
.Sh SYNOPSIS
.Cd pckbc* at isa?
.Cd pms* at pckbc?
.Cd wsmouse* at pms?
.Pp
.Cd options PMS_DISABLE_POWERHOOK
.Cd options PMS_SYNAPTICS_TOUCHPAD
.Cd options PMS_ELANTECH_TOUCHPAD
.Cd options PMS_ALPS_TOUCHPAD
.Sh DESCRIPTION
The
.Nm
driver provides an interface to PS/2 auxiliary port mice within the
.Xr wscons 4
framework.
Parent device in terms of the autoconfiguration framework is
.Xr pckbc 4 ,
the PC keyboard controller.
.Dq pms
is a generic driver which supports mice using common variants of the PS/2
protocol, including wheel mice of the
.Dq IntelliMouse
breed.
Wheel movements are mapped to a third (z-) axis.
The driver is
believed to work with both 3-button and 5-button mice with scroll wheels.
Mice which use other protocol extensions are not currently supported, but
might be if protocol documentation could be found.
Mouse related data are accessed by
.Xr wsmouse 4
devices.
.Pp
The
.Nm
driver has been updated to attempt to renegotiate mouse protocol after seeing
suspicious or defective mouse protocol packets, or unusual delays in the
middle of a packet; this should improve the chances that a mouse will recover
after being switched away or reset (for instance, by a console switch).
.Pp
The
.Va PMS_DISABLE_POWERHOOK
kernel option disables PS/2 reset on resume.
.Pp
In addition, the
.Nm
driver supports the
.Dq Synaptics ,
.Dq Elantech
and
.Dq ALPS
touchpads in native mode, enabled with the
.Va PMS_SYNAPTICS_TOUCHPAD ,
.Va PMS_ELANTECH_TOUCHPAD
and
.Va PMS_ALPS_TOUCHPAD
kernel options.
This allows the driver to take advantage of extra
features available on Synaptics, Elantech and ALPS Touchpads.
.Pp
The following
.Xr sysctl 8
variables control behavior of Synaptics touchpads:
.Bl -tag -width 8n
.It Dv hw.synaptics.up_down_emulation
If the touchpad reports the existence of extra ("Up/Down") buttons, this
value determines what kind of mouse events they should generate.
On certain clickpads, the Up/Down buttons may be physical buttons that
can be used instead of pressing the pad down, or used as additional
buttons.
.Bl -bullet
.It
If set to 0, Up/Down events generate button 4 and 5 clicks.
.It
If set to 1, Up/Down events generate middle button clicks.
.It
If set to 2, the Up and Down buttons are used for Z-axis emulation,
which more closely resembles how mouse wheels operate.
.It
If set to 3 (default), Up/Down events generate left/right clicks.
.El
.It Dv hw.synaptics.up_down_motion_delta
When the Up/Down buttons are used for Z-axis emulation, this value specifies
the emulated delta-Z value per click.
.It Dv hw.synaptics.gesture_move
Gestures will not be recognised if the finger moves by more than this
amount between taps.
.It Dv hw.synaptics.gesture_length
Gestures will not be recognised if the number of packets (at 80 packets
per second) between taps exceeds this value.
.It Dv hw.synaptics.edge_left
.It Dv hw.synaptics.edge_right
.It Dv hw.synaptics.edge_top
.It Dv hw.synaptics.edge_bottom
These values define a border around the touchpad which will be used for
edge motion emulation during a drag gesture.
If a drag gesture is in progress and the finger moves into this border,
the driver will behave as if the finger continues to move in the same
direction beyond the edge of the touchpad.
.It Dv hw.synaptics.edge_motion_delta
This specifies the pointer speed when edge motion is in effect.
.It Dv hw.synaptics.finger_high
The driver will ignore new finger events until the reported pressure exceeds
this value.
.It Dv hw.synaptics.finger_low
The driver will assume a finger remains on the touchpad until the
reported pressure drops below this value.
.It Dv hw.synaptics.two_fingers_emulation
More recent touchpads can report the presence of more than one finger
on the pad.
This value determines how such events are used.
.Bl -bullet
.It
If set to 0 (default), two-finger events are ignored.
.It
If set to 1, two-finger events generate a right button click.
.It
If set to 2, two-finger events generate a middle button click.
.El
.It Dv hw.synaptics.scale_x
.It Dv hw.synaptics.scale_y
.It Dv hw.synaptics.scale_z
Scale factor used to divide movement deltas derived from Synaptics
coordinates (0-6143) to yield more reasonable values (default 16 for x
and y, 1 for z).
.It Dv hw.synaptics.max_speed_x
.It Dv hw.synaptics.max_speed_y
.It Dv hw.synaptics.max_speed_z
Limits pointer rate of change (after scaling) per reported movement
event (default 32 for x and y, 2 for z).
.It Dv hw.synaptics.movement_threshold
Movements of less than this value (in Synaptics coordinates) are
ignored (default 4).
.It Dv hw.synaptics.movement_enable
This value determines whether or not the touchpad will respond to
touch.
If set to 1 then the touchpad will respond to touch, if set to 0
will not respond effectively disabling the touchpad.
.It Dv hw.synaptics.button_region_movement_enable
This value determines if finger movement events will be reported for
fingers that are located in the button emulation region defined by
.Va hw.synaptics.button_boundary
If set to 0 (the default) finger movements will not be reported.
If set to 1 finger movements will be reported.
.It Dv hw.synaptics.button_boundary
.It Dv hw.synaptics.button_region_percent
These two items are interrelated in that setting one will affect
the value of the other.
Since a clickpad only reports left clicks this region is used to emulate
two or three buttons by detecting the finger location and reporting
either a button 2 or button 3 click if the click occurs within
the region bounded by button_boundary and the bottom of the clickpad.
.Va hw.synaptics.button_boundary
sets the top edge of the button emulation region on a clickpad and
the percentage that represents this value is calculated and stored
in
.Va hw.synaptics.button_region_percent
Conversely, if
.Va hw.synaptics.button_region_percent
is set then the equivalent value for
.Va hw.synaptics.button_boundary
is calculated and stored.
Using a percentage allows the button region for trackpads that are able
to report their maximum and minimum values to be reliably set to
occupy a defined portion of the trackpad area instead of the user having
to tweak an arbitrary number.
.It Dv hw.synaptics.button3_edge
This defines the left hand edge of the button 3 region.
If a click occurs in the region bounded by button_boundary, button3_edge
and the right hand edge of the click pad then the click will be reported
as a button3 event.
Button 3 emulation can be disabled by setting
button3_edge to the right hand edge of the clickpad.
.It Dv hw.synaptics.button2_edge
This defines the left hand edge of the button 2 region.
The button 2 region is bounded by button2_edge, button3_edge and
button_boundary.
If a click occurs in this region then it will be reported as a button2
event.
For completeness, the region between the left hand side of the clickpad,
button2_edge and button_boundary will be reported as a button1 event
as will any clicks that occur outside the button emulation region.
.It Dv hw.synaptics.aux_mid_button_scroll
This causes Y-axis movement on the "passthrough device" (e.g. the TrackPoint
on ThinkPads) to result in scrolling events instead of Y-axis movement when
the middle button is held.
.It Dv hw.synaptics.vert_scroll_percent
Reserve this percentage of the trackpad for a vertical scroll region.
This will reduce
.Va hw.synaptics.edge_right
by this percentage.
.It Dv hw.synaptics.horizontal_scroll_percent
Reserve this percentage of the trackpad for a horizontal scroll region.
This will reduce
.Va hw.synaptics.edge_bottom
by this percentage.
The 
.Va hw.synaptics.button_boundary
will be recalculated as a result of the change.
.El
.Pp
The following
.Xr sysctl 8
variables control behavior of Elantech touchpads:
.Bl -tag -width 8n
.It Dv hw.elantech.xy_precision_shift
.It Dv hw.elantech.z_precision_shift
Increased values improve the accuracy of X, Y, and Z-axis reporting
at the expense of slower mouse movement (default 2 for xy,
and 3 for z).
.El
.Pp
For Elantech touchpads, the Z-axis is emulated using two-finger
Y-axis reporting.
.Pp
The following
.Xr sysctl 8
variables control behavior of ALPS touchpads:
.Bl -tag -width 8n
.It Dv hw.alps.touchpad_xy_precision_shift
.It Dv hw.alps.trackstick_xy_precision_shift
Decreased values improve the accuracy of X and Y-axis reporting
at the expense of slower mouse movement (default 2 for touchpad
and 1 for TrackStick).
.It Dv hw.alps.touchpad_movement_threshold
Movements of less than this value (in ALPS coordinates) are
ignored (default 4).
.El
.Sh SEE ALSO
.Xr pckbc 4 ,
.Xr ums 4 ,
.Xr wsmouse 4
.Sh AUTHORS
.An -nosplit
The
.Nm
driver was originally written by
.An Christopher G. Demetriou .
The changes to merge the
.Dq IntelliMouse
protocol in, and reset the mouse in the event of protocol problems, were
contributed by
.An Peter Seebach .
Special thanks to Ray Trent, at Synaptics, who contributed valuable
insight into how to identify bogus mouse data.
The changes to add
.Dq Synaptics
pad support were by
.An Ales Krenek ,
.An Kentaro A. Kurahone ,
and
.An Steve C. Woodford .
The changes to add
.Dq Elantech
pad support were by
.An Jared D. McNeill .
.Sh BUGS
It is possible for the driver to mistakenly negotiate the non-scroll-wheel
protocol, after which it is unlikely to recover until the device is closed
and reopened.
.Pp
The
.Dq Elantech
pad code only supports trackpads with firmware version 2.48 or above.