1.\" $NetBSD: pms.4,v 1.37 2020/03/16 09:31:41 nia Exp $ 2.\" 3.\" Copyright (c) 1993 Christopher G. Demetriou 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed for the 17.\" NetBSD Project. See http://www.NetBSD.org/ for 18.\" information about NetBSD. 19.\" 4. The name of the author may not be used to endorse or promote products 20.\" derived from this software without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 27.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 31.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32.\" 33.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>> 34.\" 35.Dd March 14, 2020 36.Dt PMS 4 37.Os 38.Sh NAME 39.Nm pms 40.Nd PS/2 auxiliary port mouse driver 41.Sh SYNOPSIS 42.Cd pckbc* at isa? 43.Cd pms* at pckbc? 44.Cd wsmouse* at pms? 45.Pp 46.Cd options PMS_DISABLE_POWERHOOK 47.Cd options PMS_SYNAPTICS_TOUCHPAD 48.Cd options PMS_ELANTECH_TOUCHPAD 49.Cd options PMS_ALPS_TOUCHPAD 50.Sh DESCRIPTION 51The 52.Nm 53driver provides an interface to PS/2 auxiliary port mice within the 54.Xr wscons 4 55framework. 56Parent device in terms of the autoconfiguration framework is 57.Xr pckbc 4 , 58the PC keyboard controller. 59.Dq pms 60is a generic driver which supports mice using common variants of the PS/2 61protocol, including wheel mice of the 62.Dq IntelliMouse 63breed. 64Wheel movements are mapped to a third (z-) axis. 65The driver is 66believed to work with both 3-button and 5-button mice with scroll wheels. 67Mice which use other protocol extensions are not currently supported, but 68might be if protocol documentation could be found. 69Mouse related data are accessed by 70.Xr wsmouse 4 71devices. 72.Pp 73The 74.Nm 75driver has been updated to attempt to renegotiate mouse protocol after seeing 76suspicious or defective mouse protocol packets, or unusual delays in the 77middle of a packet; this should improve the chances that a mouse will recover 78after being switched away or reset (for instance, by a console switch). 79.Pp 80The 81.Va PMS_DISABLE_POWERHOOK 82kernel option disables PS/2 reset on resume. 83.Pp 84In addition, the 85.Nm 86driver supports the 87.Dq Synaptics , 88.Dq Elantech 89and 90.Dq ALPS 91touchpads in native mode, enabled with the 92.Va PMS_SYNAPTICS_TOUCHPAD , 93.Va PMS_ELANTECH_TOUCHPAD 94and 95.Va PMS_ALPS_TOUCHPAD 96kernel options. 97This allows the driver to take advantage of extra 98features available on Synaptics, Elantech and ALPS Touchpads. 99.Pp 100The following 101.Xr sysctl 8 102variables control behavior of Synaptics touchpads: 103.Bl -tag -width 8n 104.It Dv hw.synaptics.up_down_emulation 105If the touchpad reports the existence of extra ("Up/Down") buttons, this 106value determines what kind of mouse events they should generate. 107On certain clickpads, the Up/Down buttons may be physical buttons that 108can be used instead of pressing the pad down, or used as additional 109buttons. 110.Bl -bullet 111.It 112If set to 0, Up/Down events generate button 4 and 5 clicks. 113.It 114If set to 1, Up/Down events generate middle button clicks. 115.It 116If set to 2, the Up and Down buttons are used for Z-axis emulation, 117which more closely resembles how mouse wheels operate. 118.It 119If set to 3 (default), Up/Down events generate left/right clicks. 120.El 121.It Dv hw.synaptics.up_down_motion_delta 122When the Up/Down buttons are used for Z-axis emulation, this value specifies 123the emulated delta-Z value per click. 124.It Dv hw.synaptics.gesture_move 125Gestures will not be recognised if the finger moves by more than this 126amount between taps. 127.It Dv hw.synaptics.gesture_length 128Gestures will not be recognised if the number of packets (at 80 packets 129per second) between taps exceeds this value. 130.It Dv hw.synaptics.edge_left 131.It Dv hw.synaptics.edge_right 132.It Dv hw.synaptics.edge_top 133.It Dv hw.synaptics.edge_bottom 134These values define a border around the touchpad which will be used for 135edge motion emulation during a drag gesture. 136If a drag gesture is in progress and the finger moves into this border, 137the driver will behave as if the finger continues to move in the same 138direction beyond the edge of the touchpad. 139.It Dv hw.synaptics.edge_motion_delta 140This specifies the pointer speed when edge motion is in effect. 141.It Dv hw.synaptics.finger_high 142The driver will ignore new finger events until the reported pressure exceeds 143this value. 144.It Dv hw.synaptics.finger_low 145The driver will assume a finger remains on the touchpad until the 146reported pressure drops below this value. 147.It Dv hw.synaptics.two_fingers_emulation 148More recent touchpads can report the presence of more than one finger 149on the pad. 150This value determines how such events are used. 151.Bl -bullet 152.It 153If set to 0 (default), two-finger events are ignored. 154.It 155If set to 1, two-finger events generate a right button click. 156.It 157If set to 2, two-finger events generate a middle button click. 158.El 159.It Dv hw.synaptics.scale_x 160.It Dv hw.synaptics.scale_y 161.It Dv hw.synaptics.scale_z 162Scale factor used to divide movement deltas derived from Synaptics 163coordinates (0-6143) to yield more reasonable values (default 16 for x 164and y, 1 for z). 165.It Dv hw.synaptics.max_speed_x 166.It Dv hw.synaptics.max_speed_y 167.It Dv hw.synaptics.max_speed_z 168Limits pointer rate of change (after scaling) per reported movement 169event (default 32 for x and y, 2 for z). 170.It Dv hw.synaptics.movement_threshold 171Movements of less than this value (in Synaptics coordinates) are 172ignored (default 4). 173.It Dv hw.synaptics.button_boundary 174Sets the top edge of the button emulation region on a clickpad. 175Since a clickpad only reports left clicks this region is used to emulate 176two or three buttons by detecting the finger location and reporting 177either a button 2 or button 3 click if the click occurs within 178the region bounded by button_boundary and the bottom of the clickpad. 179.It Dv hw.synaptics.button3_edge 180This defines the left hand edge of the button 3 region. 181If a click occurs in the region bounded by button_boundary, button3_edge 182and the right hand edge of the click pad then the click will be reported 183as a button3 event. 184Button 3 emulation can be disabled by setting 185button3_edge to the right hand edge of the clickpad. 186.It Dv hw.synaptics.button2_edge 187This defines the left hand edge of the button 2 region. 188The button 2 region is bounded by button2_edge, button3_edge and 189button_boundary. 190If a click occurs in this region then it will be reported as a button2 191event. 192For completeness, the region between the left hand side of the clickpad, 193button2_edge and button_boundary will be reported as a button1 event 194as will any clicks that occur outside the button emulation region. 195.It Dv hw.synaptics.finger_scroll-min 196The minimum finger width at which the driver will start reporting 197vertical movements as Z axis events. 198Effectively, this emulates a mouse scroll wheel by the user using two 199fingers together on the click pad. 200The default value is 5, this value cannot be less than 5 due to the way 201the clickpad reports finger width. 202.It Dv hw.synaptics.finger_scroll-max 203The maximum finger width at which the driver will report finger 204movement as Z axis events. 205The default value is 12 and cannot be greater than 14. 206.It Dv hw.synaptics.finger_scroll-hysteresis 207This defines the number of packets to continue with the Z axis emulation. 208Due to the nature of the clickpad maintaining constant contact can be 209difficult. 210This hysteresis value prevents the driver flipping between two finger 211scroll and normal mouse movement erratically. 212Each time a valid finger scroll width is detected the packet count is 213reset. 214If this variable is set too high then mouse movements will be interpreted 215as Z-axis events after the two finger scoll has finished. 216If the variable is set too low then there will be mouse movements observed 217during the two finger scroll. 218.El 219.Pp 220The following 221.Xr sysctl 8 222variables control behavior of Elantech touchpads: 223.Bl -tag -width 8n 224.It Dv hw.elantech.xy_precision_shift 225.It Dv hw.elantech.z_precision_shift 226Increased values improve the accuracy of X, Y, and Z-axis reporting 227at the expense of slower mouse movement (default 2 for xy, 228and 3 for z). 229.El 230.Pp 231For Elantech touchpads, the Z-axis is emulated using two-finger 232Y-axis reporting. 233.Pp 234The following 235.Xr sysctl 8 236variables control behavior of ALPS touchpads: 237.Bl -tag -width 8n 238.It Dv hw.alps.touchpad_xy_precision_shift 239.It Dv hw.alps.trackstick_xy_precision_shift 240Decreased values improve the accuracy of X and Y-axis reporting 241at the expense of slower mouse movement (default 2 for touchpad 242and 1 for TrackStick). 243.It Dv hw.alps.touchpad_movement_threshold 244Movements of less than this value (in ALPS coordinates) are 245ignored (default 4). 246.El 247.Sh SEE ALSO 248.Xr pckbc 4 , 249.Xr ums 4 , 250.Xr wsmouse 4 251.Sh AUTHORS 252.An -nosplit 253The 254.Nm 255driver was originally written by 256.An Christopher G. Demetriou . 257The changes to merge the 258.Dq IntelliMouse 259protocol in, and reset the mouse in the event of protocol problems, were 260contributed by 261.An Peter Seebach . 262Special thanks to Ray Trent, at Synaptics, who contributed valuable 263insight into how to identify bogus mouse data. 264The changes to add 265.Dq Synaptics 266pad support were by 267.An Ales Krenek , 268.An Kentaro A. Kurahone , 269and 270.An Steve C. Woodford . 271The changes to add 272.Dq Elantech 273pad support were by 274.An Jared D. McNeill . 275.Sh BUGS 276It is possible for the driver to mistakenly negotiate the non-scroll-wheel 277protocol, after which it is unlikely to recover until the device is closed 278and reopened. 279.Pp 280The 281.Dq Elantech 282pad code only supports trackpads with firmware version 2.48 or above. 283