1.\" Copyright (c) 2014 Hans Petter Selasky <hselasky at freebsd dot org>. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd February 9, 2021 26.Dt WSP 4 27.Os 28.Sh NAME 29.Nm wsp 30.Nd Wellspring touchpad driver 31.Sh SYNOPSIS 32To compile this driver into the kernel, place the following lines into 33your kernel configuration file: 34.Bd -ragged -offset indent 35.Cd "device wsp" 36.Cd "device hid" 37.Cd "device usb" 38.Ed 39.Pp 40Alternatively, to load the driver as a module at boot time, 41place the following line in 42.Xr loader.conf 5 : 43.Bd -literal -offset indent 44wsp_load="YES" 45.Ed 46.Sh DESCRIPTION 47The 48.Nm 49driver provides support for the Apple Internal Trackpad 50device found in many Apple laptops. 51.Pp 52The driver simulates a three-button mouse using multi-finger press/tap 53detection. 54A single-finger press generates a left button click. 55A two-finger press maps to the right button; whereas a three-finger 56press gets treated as a middle button click. 57.Pp 58The trackpad functions with presses and taps. 59A press is a full-forced 60press which causes a physical lowering of the trackpad. 61A tap is a 62touch of the trackpad which does not depress the physical trackpad. 63.Pp 64The 65.Nm 66driver supports receiving evdev input device data if enabled. 67This data 68is used for extended usage of the touchpad like multi-finger support, 69pressure detection, tap support, and gestures. 70At least the second bit of the 71.Xr sysctl 8 72tunable 73.Va kern.evdev.rcpt_mask 74must be set. 75This can be enabled with 76.Va kern.evdev.rcpt_mask=3 . 77.Pp 78Vertical scrolling (z-axis) is enabled by default with a two-finger 79tap and the movement of a finger up and down. 80Horizontal scrolling (t-axis) is not natively supported by the sysmouse 81protocol, therefore must be enabled with evdev data. 82This can be enabled with the 83.Xr sysctl 8 84tunable 85.Va kern.evdev.sysmouse_t_axis=3 . 86Horizontal scrolling can be used with a two-finger tap and the movement 87of a finger from side to side. 88The 89.Xr sysctl 8 90tunable 91.Va hw.usb.wsp.t_factor 92must be greater than 0 for horizontal scrolling to be enabled, too. 93.Pp 94Horizontal swiping with a three-finger tap is registered as mouse buttons 958 and 9, depending on the direction. 96These buttons default to backwards and forwards keyboard events. 97.Sh SYSCTL VARIABLES 98The following variables are available as 99.Xr sysctl 8 100tunables: 101.Bl -tag -width indent 102.It Va hw.usb.wsp.scale_factor 103Controls the pointer sensitivity. 104Default is 12. 105.El 106.Bl -tag -width indent 107.It Va hw.usb.wsp.enable_single_tap_clicks 108Enables single-tap to register as a left-click. 109Default is 1 (enabled). 110.El 111.Bl -tag -width indent 112.It Va hw.usb.wsp.enable_single_tap_movement 113Enables movement on the trackpad follow a partially-released left-click. 114Default is 1 (enabled). 115.El 116.Bl -tag -width indent 117.It Va hw.usb.wsp.max_finger_diameter 118Specifies the maximum finger diameter on the trackpad that is registered as a 119finger (a lower value is used for palm detection). Default is 1900. 120.El 121.Bl -tag -width indent 122.It Va max_scroll_finger_distance 123Specifies the maximum distance between two fingers where z-axis 124and t-axis movements are registered. 125Z-axis and T-axis movements 126are vertical and horizontal movements with more than one finger 127tapped (not clicked), respectively. 128Default is 8192. 129.El 130.Bl -tag -width indent 131.It Va hw.usb.wsp.max_double_tap_distance 132Specifies the maximum distance between two fingers that a two-finger 133click will be registered as a right-click. 134Default is 2500. 135.El 136.Bl -tag -width indent 137.It Va hw.usb.wsp.scr_threshold 138Specifies the minimum horizontal or vertical distance required to 139register as a scrolling gesture. 140Default is 20. 141.El 142.Bl -tag -width indent 143.It Va hw.usb.wsp.z_factor 144Z-axis sensitivity. 145Default is 5. 146.El 147.Bl -tag -width indent 148.It Va hw.usb.wsp.z_invert 149Z-axis inversion. 150Default is 0 (disabled). 151.El 152.Bl -tag -width indent 153.It Va hw.usb.wsp.t_factor 154T-axis sensitivity. 155Default is 0 (disabled). 156.El 157.Bl -tag -width indent 158.It Va hw.usb.wsp.t_invert 159T-axis inversion. 160Default is 0 (disabled). 161.El 162.Bl -tag -width indent 163.It Va hw.usb.wsp.scroll_finger_count 164Specifies the number of tapped fingers which registers as a scrolling 165movement. 166Default is 2. 167.El 168.Bl -tag -width indent 169.It Va hw.usb.wsp.horizontal_swipe_finger_count 170Speifies the number of tapped fingers which registers as a swipe 171gesture. 172Default is 3. 173.El 174.Bl -tag -width indent 175.It Va hw.usb.wsp.pressure_touch_threshold 176Specifies the threshold for a finger to be registered as a click. 177Default is 50. 178.El 179.Bl -tag -width indent 180.It Va hw.usb.wsp.pressure_untouch_threshold 181Specifies the threshold for a finger to be registered as an unclick. 182Default is 10. 183.El 184.Bl -tag -width indent 185.It Va hw.usb.wsp.pressure_tap_threshold 186Specifies the threadhold for a finger to be registered as a tap. 187Default is 120. 188.El 189.Bl -tag -width indent 190.It Va hw.usb.wsp.debug 191Specifies the 192.Nm 193driver debugging level (0-3). 194Default is 1. 195.El 196.Sh FILES 197.Nm 198creates a blocking pseudo-device file, 199.Pa /dev/wsp0 , 200which presents the mouse as a 201.Em sysmouse 202or 203.Em mousesystems 204type device--see 205.Xr moused 8 206for an explanation of these mouse types. 207.Sh SEE ALSO 208.Xr sysmouse 4 , 209.Xr usb 4 , 210.Xr loader.conf 5 , 211.Xr xorg.conf 5 Pq Pa ports/x11/xorg , 212.Xr moused 8 , 213.Xr sysctl 8 214.Sh AUTHORS 215.An -nosplit 216The 217.Nm 218driver was written by 219.An Huang Wen Hui Aq Mt huanghwh@gmail.com . 220