1.\" $NetBSD: wsmouse.9,v 1.16 2008/04/30 13:10:59 martin 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 November 12, 2006 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 wsmousedevprint "aux" "pnp" 175The default wsmouse printing routine used by 176.Fn config_found . 177(see 178.Xr autoconf 9 ) . 179.El 180.Sh AUTOCONFIGURATION 181Mouse drivers which want to use the wsmouse module must be a 182parent to the 183.Xr wsmouse 4 184device and provide an attachment interface. 185To attach the 186.Xr wsmouse 4 187device, the mouse driver must allocate and populate a 188.Fa wsmousedev_attach_args 189structure with the supported operations and callbacks and call 190.Fn config_found 191to perform the attach (see 192.Xr autoconf 9 ) . 193.Sh OPERATION 194When a mouse-movement event is received, the device driver must 195perform any necessary movement decoding to wscons events and pass the 196events to wscons via 197.Fn wsmouse_input . 198.Pp 199The wscons framework calls back into the hardware driver by invoking 200the functions that are specified in the 201.Em accessops 202structure. 203The 204.Fn enable 205and 206.Fn disable 207functions are relatively simple and self-explanatory. 208The 209.Fn ioctl 210function is called by the wscons interface to perform 211mouse-specific ioctl operations (see 212.Xr ioctl 2 ) . 213The argument 214.Fa cmd 215to the 216.Fn ioctl 217function specifies the specific command to perform using the data 218.Fa data . 219Valid commands are listed in 220.Pa sys/dev/wscons/wsconsio.h . 221.Sh CODE REFERENCES 222This section describes places within the 223.Nx 224source tree where actual code implementing or using the 225machine-independent wscons subsystem can be found. 226All pathnames are relative to 227.Pa /usr/src . 228.Pp 229The wscons subsystem is implemented within the directory 230.Pa sys/dev/wscons . 231The 232.Nm 233module itself is implement within the file 234.Pa sys/dev/wscons/wsmouse.c . 235.Xr ioctl 2 236operations are listed in 237.Pa sys/dev/wscons/wsconsio.h . 238.Sh SEE ALSO 239.Xr ioctl 2 , 240.Xr pms 4 , 241.Xr wscons 4 , 242.Xr wsmouse 4 , 243.Xr autoconf 9 , 244.Xr driver 9 , 245.Xr intro 9 , 246.Xr wscons 9 , 247.Xr wsdisplay 9 , 248.Xr wskbd 9 249