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. A press is a full-forced 59press which causes a physical lowering of the trackpad. A tap is a 60touch of the trackpad which does not depress the physical trackpad. 61.Pp 62The 63.Nm 64driver supports receiving evdev input device data if enabled. This data 65is used for extended usage of the touchpad like multi-finger support, 66pressure detection, tap support, and gestures. At least the second bit 67of the 68.Xr sysctl 8 69tunable 70.Va kern.evdev.rcpt_mask 71must be set. This can be enabled with 72.Va kern.evdev.rcpt_mask=3 . 73.Pp 74Vertical scrolling (z-axis) is enabled by default with a two-finger 75tap and the movement of a finger up and down. 76Horizontal scrolling (t-axis) is not natively supported by the sysmouse 77protocol, therefore must be enabled with evdev data. This can be enabled 78with the 79.Xr sysctl 8 80tunable 81.Va kern.evdev.sysmouse_t_axis=3. 82Horizontal scrolling can be used with a two-finger tap and the movement 83of a finger from side to side. The 84.Xr sysctl 8 85tunable 86.Va hw.usb.wsp.t_factor 87must be greater than 0 for horizontal scrolling to be enabled, too. 88.Pp 89Horizontal swiping with a three-finger tap is registered as mouse buttons 908 and 9, depending on the direction. These buttons default to backwards 91and forwards keyboard events. 92.Sh SYSCTL VARIABLES 93The following variables are available as 94.Xr sysctl 8 95tunables: 96.Bl -tag -width indent 97.It Va hw.usb.wsp.scale_factor 98Controls the pointer sensitivity. Default is 12. 99.El 100.Bl -tag -width indent 101.It Va hw.usb.wsp.enable_single_tap_clicks 102Enables single-tap to register as a left-click. Default is 1 (enabled). 103.El 104.Bl -tag -width indent 105.It Va hw.usb.wsp.enable_single_tap_movement 106Enables movement on the trackpad follow a partially-released left-click. 107Default is 1 (enabled). 108.El 109.Bl -tag -width indent 110.It Va hw.usb.wsp.max_finger_diameter 111Specifies the maximum finger diameter on the trackpad that is registered as a 112finger (a lower value is used for palm detection). Default is 1900. 113.El 114.Bl -tag -width indent 115.It Va max_scroll_finger_distance 116Specifies the maximum distance between two fingers where z-axis 117and t-axis movements are registered. Z-axis and T-axis movements 118are vertical and horizontal movements with more than one finger 119tapped (not clicked), respectively. Default is 8192. 120.El 121.Bl -tag -width indent 122.It Va hw.usb.wsp.max_double_tap_distance 123Specifies the maximum distance between two fingers that a two-finger 124click will be registered as a right-click. Default is 2500. 125.El 126.Bl -tag -width indent 127.It Va hw.usb.wsp.scr_threshold 128Specifies the minimum horizontal or vertical distance required to 129register as a scrolling gesture. Default is 20. 130.El 131.Bl -tag -width indent 132.It Va hw.usb.wsp.z_factor 133Z-axis sensitivity. Default is 5. 134.El 135.Bl -tag -width indent 136.It Va hw.usb.wsp.z_invert 137Z-axis inversion. Default is 0 (disabled). 138.El 139.Bl -tag -width indent 140.It Va hw.usb.wsp.t_factor 141T-axis sensitivity. Default is 0 (disabled). 142.El 143.Bl -tag -width indent 144.It Va hw.usb.wsp.t_invert 145T-axis inversion. Default is 0 (disabled). 146.El 147.Bl -tag -width indent 148.It Va hw.usb.wsp.scroll_finger_count 149Specifies the number of tapped fingers which registers as a scrolling 150movement. Default is 2. 151.El 152.Bl -tag -width indent 153.It Va hw.usb.wsp.horizontal_swipe_finger_count 154Speifies the number of tapped fingers which registers as a swipe 155gesture. Default is 3. 156.El 157.Bl -tag -width indent 158.It Va hw.usb.wsp.pressure_touch_threshold 159Specifies the threshold for a finger to be registered as a click. 160Default is 50. 161.El 162.Bl -tag -width indent 163.It Va hw.usb.wsp.pressure_untouch_threshold 164Specifies the threshold for a finger to be registered as an unclick. 165Default is 10. 166.El 167.Bl -tag -width indent 168.It Va hw.usb.wsp.pressure_tap_threshold 169Specifies the threadhold for a finger to be registered as a tap. 170Default is 120. 171.El 172.Bl -tag -width indent 173.It Va hw.usb.wsp.debug 174Specifies the 175.Nm 176driver debugging level (0-3). Default is 1. 177.Sh FILES 178.Nm 179creates a blocking pseudo-device file, 180.Pa /dev/wsp0 , 181which presents the mouse as a 182.Em sysmouse 183or 184.Em mousesystems 185type device--see 186.Xr moused 8 187for an explanation of these mouse 188types. 189.Sh SEE ALSO 190.Xr sysmouse 4 , 191.Xr usb 4 , 192.Xr loader.conf 5 , 193.Xr xorg.conf 5 Pq Pa ports/x11/xorg , 194.Xr moused 8 , 195.Xr sysctl 8 196.Sh AUTHORS 197.An -nosplit 198The 199.Nm 200driver was written by 201.An Huang Wen Hui Aq Mt huanghwh@gmail.com . 202