1.\" $NetBSD: wsmouse.9,v 1.19 2021/10/11 18:19:27 nia Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Gregory McGarry. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 11, 2021 31.Dt WSMOUSE 9 32.Os 33.Sh NAME 34.Nm wsmouse , 35.Nm wsmouse_input , 36.Nm wsmousedevprint 37.Nd wscons mouse support 38.Sh SYNOPSIS 39.In dev/wscons/wsconsio.h 40.In dev/wscons/wsmousevar.h 41.Ft void 42.Fn wsmouse_input "struct device *msdev" "u_int btns" \ 43"int x" "int y" "int z" "int w" "u_int flags" 44.Ft int 45.Fn wsmousedevprint "void *aux" "const char *pnp" 46.Sh DESCRIPTION 47The 48.Nm 49module is a component of the 50.Xr wscons 9 51framework to provide machine-independent mouse support. 52Most of the support is provided by the 53.Xr wsmouse 4 54device driver, which must be a child of the hardware device driver. 55.Sh DATA TYPES 56Mouse drivers providing support for wscons pointer devices will make use 57of the following data types: 58.Bl -tag -width compact 59.It Fa struct wsmouse_accessops 60A structure used to specify the mouse access functions. 61All pointer devices must provide this structure and pass it to the 62.Xr wsmouse 4 63child device. 64It has the following members: 65.Bd -literal 66 int (*enable)(void *); 67 int (*ioctl)(void *v, u_long cmd, void *data, 68 int flag, struct lwp *l); 69 void (*disable)(void *); 70.Ed 71.Pp 72The 73.Fa enable 74member defines the function to be called to enable monitoring pointer 75movements and passing these events to 76wscons. 77The 78.Fa disable 79member defines the function to disable movement events. 80The 81.Fa ioctl 82member defines the function to be called to perform mouse-specific 83ioctl calls. 84.Pp 85There is a 86.Fa void * 87cookie provided by the mouse driver associated with these functions, 88which is passed to them when they are invoked. 89.It Fa struct wsmousedev_attach_args 90A structure used to attach the 91.Xr wsmouse 4 92child device. 93It has the following members: 94.Bd -literal 95 const struct wsmouse_accessops *accessops; 96 void *accesscookie; 97.Ed 98.El 99.Sh FUNCTIONS 100.Bl -tag -width compact 101.It Fn wsmouse_input "msdev" "btns" "x" "y" "z" "w" "flags" 102Callback from the mouse driver to the wsmouse interface driver. 103Arguments are as follows: 104.Bl -tag -width msdev -compact 105.It Fa msdev 106This is the 107.Fa struct device 108pointer passed from 109.Fn config_found 110on attaching the child 111.Xr wsmouse 4 112to specify the mouse device. 113.It Fa btns 114This specifies the current button status. 115Bits for pressed buttons (which will cause the 116.Dv WSCONS_EVENT_MOUSE_DOWN 117event on 118.Xr wsmouse 4 119device) should be set, and bits for released buttons (which will cause the 120.Dv WSCONS_EVENT_MOUSE_UP 121event) should be zero. 122The left most button state should be in LSB, 123i.e. for typical three button mouse, 124the left button is 0x01, 125the middle button is 0x02, 126and the right button is 0x04. 127.It Fa x 128Absolute or relative X-axis value to specify the pointer coordinate. 129Rightward (moving the mouse right) is positive. 130.It Fa y 131Absolute or relative Y-axis value to specify the pointer coordinate. 132Upward (moving the mouse forward) is positive. 133Note that this aspect is opposite from the one used in the X server dix layer. 134.It Fa z 135Absolute or relative Z-axis value to specify the pointer coordinate. 136Usually this axis is used for the wheel. 137Downward (turning the wheel backward) is positive. 138.It Fa w 139Absolute or relative W-axis value to specify the pointer coordinate. 140Usually this axis would be used for the horizontal component of the wheel. 141.It Fa flags 142This argument specifies whether the pointer device and the measurement 143of the 144.Fa x , 145.Fa y , 146.Fa z , 147and 148.Fa w 149axes is in relative or absolute mode. 150Valid values for 151.Fa flags 152are: 153.Bl -tag -width compact 154.It WSMOUSE_INPUT_DELTA 155Relative mode. 156.It WSMOUSE_INPUT_ABSOLUTE_X 157Absolute mode in 158.Fa x 159axis. 160.It WSMOUSE_INPUT_ABSOLUTE_Y 161Absolute mode in 162.Fa y 163axis. 164.It WSMOUSE_INPUT_ABSOLUTE_Z 165Absolute mode in 166.Fa z 167axis. 168.It WSMOUSE_INPUT_ABSOLUTE_W 169Absolute mode in 170.Fa w 171axis. 172.El 173.El 174.It Fn wsmouse_precision_scroll "msdev" "x" "y" 175Callback from the mouse driver to the wsmouse interface driver. 176.Pp 177This is used when higher precision scrolling events are required 178than what can be provided by a typical scroll wheel. 179This function generates 180.Dv WSCONS_EVENT_HSCROLL 181(for scrolling on the X axis) and 182.Dv WSCONS_EVENT_VSCROLL 183(for scrolling on the X axis) events. 184.Pp 185The coordinates are adjusted for speed according to the formula: 186.Li x * 4096 / scroll_unit 187.Pp 188The 189.Dv scroll_unit 190is configured through the 191.Xr wsmouse 4 192ioctl interface, specifically the 193.Dv WSMOUSEIO_SETPARAMS 194keys 195.Dv WSMOUSECFG_HORIZSCROLLDIST 196and 197.Dv WSMOUSECFG_VERTSCROLLDIST . 198.It Fn wsmousedevprint "aux" "pnp" 199The default wsmouse printing routine used by 200.Fn config_found . 201(see 202.Xr autoconf 9 ) . 203.El 204.Sh AUTOCONFIGURATION 205Mouse drivers which want to use the wsmouse module must be a 206parent to the 207.Xr wsmouse 4 208device and provide an attachment interface. 209To attach the 210.Xr wsmouse 4 211device, the mouse driver must allocate and populate a 212.Fa wsmousedev_attach_args 213structure with the supported operations and callbacks and call 214.Fn config_found 215to perform the attach (see 216.Xr autoconf 9 ) . 217.Sh OPERATION 218When a mouse-movement event is received, the device driver must 219perform any necessary movement decoding to wscons events and pass the 220events to wscons via 221.Fn wsmouse_input . 222.Pp 223The wscons framework calls back into the hardware driver by invoking 224the functions that are specified in the 225.Em accessops 226structure. 227The 228.Fn enable 229and 230.Fn disable 231functions are relatively simple and self-explanatory. 232The 233.Fn ioctl 234function is called by the wscons interface to perform 235mouse-specific ioctl operations (see 236.Xr ioctl 2 ) . 237The argument 238.Fa cmd 239to the 240.Fn ioctl 241function specifies the specific command to perform using the data 242.Fa data . 243Valid commands are listed in 244.Pa sys/dev/wscons/wsconsio.h . 245.Sh CODE REFERENCES 246The wscons subsystem is implemented within the directory 247.Pa sys/dev/wscons . 248The 249.Nm 250module itself is implemented within the file 251.Pa sys/dev/wscons/wsmouse.c . 252.Xr ioctl 2 253operations are listed in 254.Pa sys/dev/wscons/wsconsio.h . 255.Sh SEE ALSO 256.Xr ioctl 2 , 257.Xr pms 4 , 258.Xr wscons 4 , 259.Xr wsmouse 4 , 260.Xr autoconf 9 , 261.Xr driver 9 , 262.Xr intro 9 , 263.Xr wscons 9 , 264.Xr wsdisplay 9 , 265.Xr wskbd 9 266