1.\" $NetBSD: wsmouse.9,v 1.12 2005/12/20 19:53:15 rpaulo 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 December 20, 2005 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" "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, caddr_t 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" "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 flags 146This argument specifies whether the pointer device and the measurement 147of the 148.Fa x , 149.Fa y , 150and 151.Fa z 152axes is in relative or absolute mode. 153Valid values for 154.Fa flags 155are: 156.Bl -tag -width compact 157.It WSMOUSE_INPUT_DELTA 158Relative mode. 159.It WSMOUSE_INPUT_ABSOLUTE_X 160Absolute mode in 161.Fa x 162axis. 163.It WSMOUSE_INPUT_ABSOLUTE_Y 164Absolute mode in 165.Fa y 166axis. 167.It WSMOUSE_INPUT_ABSOLUTE_Z 168Absolute mode in 169.Fa z 170axis. 171.El 172.El 173.It Fn wsmousedevprint "aux" "pnp" 174The default wsmouse printing routine used by 175.Fn config_found . 176(see 177.Xr autoconf 9 ) . 178.El 179.Sh AUTOCONFIGURATION 180Mouse drivers which want to use the wsmouse module must be a 181parent to the 182.Xr wsmouse 4 183device and provide an attachment interface. 184To attach the 185.Xr wsmouse 4 186device, the mouse driver must allocate and populate a 187.Fa wsmousedev_attach_args 188structure with the supported operations and callbacks and call 189.Fn config_found 190to perform the attach (see 191.Xr autoconf 9 ) . 192.Sh OPERATION 193When a mouse-movement event is received, the device driver must 194perform any necessary movement decoding to wscons events and pass the 195events to wscons via 196.Fn wsmouse_input . 197.Pp 198The wscons framework calls back into the hardware driver by invoking 199the functions that are specified in the 200.Em accessops 201structure. 202The 203.Fn enable 204and 205.Fn disable 206functions are relatively simple and self-explanatory. 207The 208.Fn ioctl 209function is called by the wscons interface to perform 210mouse-specific ioctl operations (see 211.Xr ioctl 2 ) . 212The argument 213.Fa cmd 214to the 215.Fn ioctl 216function specifies the specific command to perform using the data 217.Fa data . 218Valid commands are listed in 219.Pa sys/dev/wscons/wsconsio.h . 220.Sh CODE REFERENCES 221This section describes places within the 222.Nx 223source tree where actual code implementing or using the 224machine-independent wscons subsystem can be found. 225All pathnames are relative to 226.Pa /usr/src . 227.Pp 228The wscons subsystem is implemented within the directory 229.Pa sys/dev/wscons . 230The 231.Nm 232module itself is implement within the file 233.Pa sys/dev/wscons/wsmouse.c . 234.Xr ioctl 2 235operations are listed in 236.Pa sys/dev/wscons/wsconsio.h . 237.Sh SEE ALSO 238.Xr ioctl 2 , 239.Xr pms 4 , 240.Xr wscons 4 , 241.Xr wsmouse 4 , 242.Xr autoconf 9 , 243.Xr driver 9 , 244.Xr intro 9 , 245.Xr wscons 9 , 246.Xr wsdisplay 9 , 247.Xr wskbd 9 248