1.\" $NetBSD: pms.4,v 1.42 2024/09/07 19:13:27 rillig 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 https://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 October 21, 2021 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.movement_enable 174This value determines whether or not the touchpad will respond to 175touch. 176If set to 1 then the touchpad will respond to touch, if set to 0 177will not respond effectively disabling the touchpad. 178.It Dv hw.synaptics.button_region_movement_enable 179This value determines if finger movement events will be reported for 180fingers that are located in the button emulation region defined by 181.Va hw.synaptics.button_boundary 182If set to 0 (the default) finger movements will not be reported. 183If set to 1 finger movements will be reported. 184.It Dv hw.synaptics.button_boundary 185.It Dv hw.synaptics.button_region_percent 186These two items are interrelated in that setting one will affect 187the value of the other. 188Since a clickpad only reports left clicks this region is used to emulate 189two or three buttons by detecting the finger location and reporting 190either a button 2 or button 3 click if the click occurs within 191the region bounded by button_boundary and the bottom of the clickpad. 192.Va hw.synaptics.button_boundary 193sets the top edge of the button emulation region on a clickpad and 194the percentage that represents this value is calculated and stored 195in 196.Va hw.synaptics.button_region_percent 197Conversely, if 198.Va hw.synaptics.button_region_percent 199is set then the equivalent value for 200.Va hw.synaptics.button_boundary 201is calculated and stored. 202Using a percentage allows the button region for trackpads that are able 203to report their maximum and minimum values to be reliably set to 204occupy a defined portion of the trackpad area instead of the user having 205to tweak an arbitrary number. 206.It Dv hw.synaptics.button3_edge 207This defines the left hand edge of the button 3 region. 208If a click occurs in the region bounded by button_boundary, button3_edge 209and the right hand edge of the click pad then the click will be reported 210as a button3 event. 211Button 3 emulation can be disabled by setting 212button3_edge to the right hand edge of the clickpad. 213.It Dv hw.synaptics.button2_edge 214This defines the left hand edge of the button 2 region. 215The button 2 region is bounded by button2_edge, button3_edge and 216button_boundary. 217If a click occurs in this region then it will be reported as a button2 218event. 219For completeness, the region between the left hand side of the clickpad, 220button2_edge and button_boundary will be reported as a button1 event 221as will any clicks that occur outside the button emulation region. 222.It Dv hw.synaptics.aux_mid_button_scroll 223This causes Y-axis movement on the "passthrough device" (e.g. the TrackPoint 224on ThinkPads) to result in scrolling events instead of Y-axis movement when 225the middle button is held. 226.It Dv hw.synaptics.vert_scroll_percent 227Reserve this percentage of the trackpad for a vertical scroll region. 228This will reduce 229.Va hw.synaptics.edge_right 230by this percentage. 231.It Dv hw.synaptics.horizontal_scroll_percent 232Reserve this percentage of the trackpad for a horizontal scroll region. 233This will reduce 234.Va hw.synaptics.edge_bottom 235by this percentage. 236The 237.Va hw.synaptics.button_boundary 238will be recalculated as a result of the change. 239.El 240.Pp 241The following 242.Xr sysctl 8 243variables control behavior of Elantech touchpads: 244.Bl -tag -width 8n 245.It Dv hw.elantech.xy_precision_shift 246.It Dv hw.elantech.z_precision_shift 247Increased values improve the accuracy of X, Y, and Z-axis reporting 248at the expense of slower mouse movement (default 2 for xy, 249and 3 for z). 250.El 251.Pp 252For Elantech touchpads, the Z-axis is emulated using two-finger 253Y-axis reporting. 254.Pp 255The following 256.Xr sysctl 8 257variables control behavior of ALPS touchpads: 258.Bl -tag -width 8n 259.It Dv hw.alps.touchpad_xy_precision_shift 260.It Dv hw.alps.trackstick_xy_precision_shift 261Decreased values improve the accuracy of X and Y-axis reporting 262at the expense of slower mouse movement (default 2 for touchpad 263and 1 for TrackStick). 264.It Dv hw.alps.touchpad_movement_threshold 265Movements of less than this value (in ALPS coordinates) are 266ignored (default 4). 267.El 268.Sh SEE ALSO 269.Xr pckbc 4 , 270.Xr ums 4 , 271.Xr wsmouse 4 272.Sh AUTHORS 273.An -nosplit 274The 275.Nm 276driver was originally written by 277.An Christopher G. Demetriou . 278The changes to merge the 279.Dq IntelliMouse 280protocol in, and reset the mouse in the event of protocol problems, were 281contributed by 282.An Peter Seebach . 283Special thanks to Ray Trent, at Synaptics, who contributed valuable 284insight into how to identify bogus mouse data. 285The changes to add 286.Dq Synaptics 287pad support were by 288.An Ales Krenek , 289.An Kentaro A. Kurahone , 290and 291.An Steve C. Woodford . 292The changes to add 293.Dq Elantech 294pad support were by 295.An Jared D. McNeill . 296.Sh BUGS 297It is possible for the driver to mistakenly negotiate the non-scroll-wheel 298protocol, after which it is unlikely to recover until the device is closed 299and reopened. 300.Pp 301The 302.Dq Elantech 303pad code only supports trackpads with firmware version 2.48 or above. 304