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