1.\" $NetBSD: pms.4,v 1.31 2018/02/04 18:17:59 christos 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 February 4, 2018 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 Up/Down buttons, this value 106determines if they should be reported as button 4 and 5 events or if 107they should be used to emulate some other event. 108When set to 0, report Up/Down events as buttons 4 and 5. 109When set to 1, the Up and Down buttons are both mapped to the middle button. 110When set to 2 (default), the Up and Down buttons are used for Z-axis 111emulation, which more closely resembles how mouse wheels operate. 112.It Dv hw.synaptics.up_down_motion_delta 113When the Up/Down buttons are used for Z-axis emulation, this value specifies 114the emulated delta-Z value per click. 115.It Dv hw.synaptics.gesture_move 116Gestures will not be recognised if the finger moves by more than this 117amount between taps. 118.It Dv hw.synaptics.gesture_length 119Gestures will not be recognised if the number of packets (at 80 packets 120per second) between taps exceeds this value. 121.It Dv hw.synaptics.edge_left 122.It Dv hw.synaptics.edge_right 123.It Dv hw.synaptics.edge_top 124.It Dv hw.synaptics.edge_bottom 125These values define a border around the touchpad which will be used for 126edge motion emulation during a drag gesture. 127If a drag gesture is in progress and the finger moves into this border, 128the driver will behave as if the finger continues to move in the same 129direction beyond the edge of the touchpad. 130.It Dv hw.synaptics.edge_motion_delta 131This specifies the pointer speed when edge motion is in effect. 132.It Dv hw.synaptics.finger_high 133The driver will ignore new finger events until the reported pressure exceeds 134this value. 135.It Dv hw.synaptics.finger_low 136The driver will assume a finger remains on the touchpad until the 137reported pressure drops below this value. 138.It Dv hw.synaptics.two_fingers_emulation 139More recent touchpads can report the presence of more than one finger 140on the pad. 141This value determines how such events are used. 142If set to 0 (default), two-finger events are ignored. 143If set to 1, two-finger events generate a right button click. 144If set to 2, two-finger events generate a middle button click. 145.It Dv hw.synaptics.scale_x 146.It Dv hw.synaptics.scale_y 147Scale factor used to divide movement deltas derived from Synaptics 148coordinates (0-6143) to yield more reasonable values (default 16). 149.It Dv hw.synaptics.max_speed_x 150.It Dv hw.synaptics.max_speed_y 151Limits pointer rate of change (after scaling) per reported movement 152event (default 32). 153.It Dv hw.synaptics.movement_threshold 154Movements of less than this value (in Synaptics coordinates) are 155ignored (default 4). 156.It Dv hw.synaptics.button_boundary 157Sets the top edge of the button emulation region on a clickpad. 158Since a clickpad only reports left clicks this region is used to emulate 159two or three buttons by detecting the finger location and reporting 160either a button 2 or button 3 click iff the click occurs within 161the region bounded by button_boundary and the bottom of the clickpad. 162.It Dv hw.synaptics.button3_edge 163This defines the left hand edge of the button 3 region. 164If a click occurs in the region bounded by button_boundary, button3_edge 165and the right hand edge of the click pad then the click will be reported 166as a button3 event. 167Button 3 emulation can be disabled by setting 168button3_edge to the right hand edge of the clickpad. 169.It Dv hw.synaptics.button2_edge 170This defines the left hand edge of the button 2 region. 171The button 2 region is bounded by button2_edge, button3_edge and 172button_boundary. 173If a click occurs in this region then it will be reported as a button2 174event. 175For completeness, the region between the left hand side of the clickpad, 176button2_edge and button_boundary will be reported as a button1 event 177as will any clicks that occur outside the button emulation region. 178.El 179.Pp 180The following 181.Xr sysctl 8 182variables control behavior of Elantech touchpads: 183.Bl -tag -width 8n 184.It Dv hw.elantech.xy_precision_shift 185.It Dv hw.elantech.z_precision_shift 186Increased values improve the accuracy of X, Y, and Z-axis reporting 187at the expense of slower mouse movement (default 2 for xy, 188and 3 for z). 189.El 190.Pp 191For Elantech touchpads, the Z-axis is emulated using two-finger 192Y-axis reporting. 193.Pp 194The following 195.Xr sysctl 8 196variables control behavior of ALPS touchpads: 197.Bl -tag -width 8n 198.It Dv hw.alps.touchpad_xy_precision_shift 199.It Dv hw.alps.tackstick_xy_precision_shift 200Decreased values improve the accuracy of X and Y-axis reporting 201at the expense of slower mouse movement (default 2 for touchpad 202and 1 for TrackStick). 203.El 204.Sh SEE ALSO 205.Xr pckbc 4 , 206.Xr ums 4 , 207.Xr wsmouse 4 208.Sh AUTHORS 209.An -nosplit 210The 211.Nm 212driver was originally written by 213.An Christopher G. Demetriou . 214The changes to merge the 215.Dq IntelliMouse 216protocol in, and reset the mouse in the event of protocol problems, were 217contributed by 218.An Peter Seebach . 219Special thanks to Ray Trent, at Synaptics, who contributed valuable 220insight into how to identify bogus mouse data. 221The changes to add 222.Dq Synaptics 223pad support were by 224.An Ales Krenek , 225.An Kentaro A. Kurahone , 226and 227.An Steve C. Woodford . 228The changes to add 229.Dq Elantech 230pad support were by 231.An Jared D. McNeill . 232.Sh BUGS 233It is possible for the driver to mistakenly negotiate the non-scroll-wheel 234protocol, after which it is unlikely to recover until the device is closed 235and reopened. 236.Pp 237The 238.Dq Elantech 239pad code only supports trackpads with firmware version 2.48 or above. 240