1.\" Copyright 1997 John-Mark Gurney. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY John-Mark Gurney AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.Dd March 25, 2014 25.Dt SYSMOUSE 4 26.Os 27.Sh NAME 28.Nm sysmouse 29.\" .Nd supplies mouse data from syscons for other applications 30.Nd virtualized mouse driver 31.Sh SYNOPSIS 32.In sys/mouse.h 33.In sys/consio.h 34.Sh DESCRIPTION 35The console driver, in conjunction with the mouse daemon 36.Xr moused 8 , 37supplies mouse data to the user process in the standardized way via the 38.Nm 39driver. 40This arrangement makes it possible for the console and the user process 41(such as the 42.Tn X\ Window System ) 43to share the mouse. 44.Pp 45The user process which wants to utilize mouse operation simply opens 46.Pa /dev/sysmouse 47with a 48.Xr open 2 49call and reads 50mouse data from the device via 51.Xr read 2 . 52Make sure that 53.Xr moused 8 54is running, otherwise the user process will not see any data coming from 55the mouse. 56.Ss Operation Levels 57The 58.Nm 59driver has two levels of operation. 60The current operation level can be referred to and changed via ioctl calls. 61.Pp 62The level zero, the basic level, is the lowest level at which the driver 63offers the basic service to user programs. 64The 65.Nm 66driver 67provides horizontal and vertical movement of the mouse 68and state of up to three buttons in the 69.Tn MouseSystems 70format as follows. 71.Pp 72.Bl -tag -width Byte_1 -compact 73.It Byte 1 74.Bl -tag -width bit_7 -compact 75.It bit 7 76Always one. 77.It bit 6..3 78Always zero. 79.It bit 2 80Left button status; cleared if pressed, otherwise set. 81.It bit 1 82Middle button status; cleared if pressed, otherwise set. 83Always one, 84if the device does not have the middle button. 85.It bit 0 86Right button status; cleared if pressed, otherwise set. 87.El 88.It Byte 2 89The first half of horizontal movement count in two's complement; 90\-128 through 127. 91.It Byte 3 92The first half of vertical movement count in two's complement; 93\-128 through 127. 94.It Byte 4 95The second half of the horizontal movement count in two's complement; 96\-128 through 127. 97To obtain the full horizontal movement count, add 98the byte 2 and 4. 99.It Byte 5 100The second half of the vertical movement count in two's complement; 101\-128 through 127. 102To obtain the full vertical movement count, add 103the byte 3 and 5. 104.El 105.Pp 106At the level one, the extended level, mouse data is encoded 107in the standard format 108.Dv MOUSE_PROTO_SYSMOUSE 109as defined in 110.Xr mouse 4 . 111.\" .Ss Acceleration 112.\" The 113.\" .Nm 114.\" driver can somewhat `accelerate' the movement of the pointing device. 115.\" The faster you move the device, the further the pointer 116.\" travels on the screen. 117.\" The driver has an internal variable which governs the effect of 118.\" the acceleration. Its value can be modified via the driver flag 119.\" or via an ioctl call. 120.Sh IOCTLS 121This section describes two classes of 122.Xr ioctl 2 123commands: 124commands for the 125.Nm 126driver itself, and commands for the console and the console control drivers. 127.Ss Sysmouse Ioctls 128There are a few commands for mouse drivers. 129General description of the commands is given in 130.Xr mouse 4 . 131Following are the features specific to the 132.Nm 133driver. 134.Pp 135.Bl -tag -width MOUSE -compact 136.It Dv MOUSE_GETLEVEL Ar int *level 137.It Dv MOUSE_SETLEVEL Ar int *level 138These commands manipulate the operation level of the mouse driver. 139.Pp 140.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw 141Returns the hardware information of the attached device in the following 142structure. 143Only the 144.Va iftype 145field is guaranteed to be filled with the correct value in the current 146version of the 147.Nm 148driver. 149.Bd -literal 150typedef struct mousehw { 151 int buttons; /* number of buttons */ 152 int iftype; /* I/F type */ 153 int type; /* mouse/track ball/pad... */ 154 int model; /* I/F dependent model ID */ 155 int hwid; /* I/F dependent hardware ID */ 156} mousehw_t; 157.Ed 158.Pp 159The 160.Va buttons 161field holds the number of buttons detected by the driver. 162.Pp 163The 164.Va iftype 165is always 166.Dv MOUSE_IF_SYSMOUSE . 167.Pp 168The 169.Va type 170tells the device type: 171.Dv MOUSE_MOUSE , 172.Dv MOUSE_TRACKBALL , 173.Dv MOUSE_STICK , 174.Dv MOUSE_PAD , 175or 176.Dv MOUSE_UNKNOWN . 177.Pp 178The 179.Va model 180is always 181.Dv MOUSE_MODEL_GENERIC 182at the operation level 0. 183It may be 184.Dv MOUSE_MODEL_GENERIC 185or one of 186.Dv MOUSE_MODEL_XXX 187constants at higher operation levels. 188.Pp 189The 190.Va hwid 191is always zero. 192.Pp 193.It Dv MOUSE_GETMODE Ar mousemode_t *mode 194The command gets the current operation parameters of the mouse 195driver. 196.Bd -literal 197typedef struct mousemode { 198 int protocol; /* MOUSE_PROTO_XXX */ 199 int rate; /* report rate (per sec) */ 200 int resolution; /* MOUSE_RES_XXX, -1 if unknown */ 201 int accelfactor; /* acceleration factor */ 202 int level; /* driver operation level */ 203 int packetsize; /* the length of the data packet */ 204 unsigned char syncmask[2]; /* sync. bits */ 205} mousemode_t; 206.Ed 207.Pp 208The 209.Va protocol 210field tells the format in which the device status is returned 211when the mouse data is read by the user program. 212It is 213.Dv MOUSE_PROTO_MSC 214at the operation level zero. 215.Dv MOUSE_PROTO_SYSMOUSE 216at the operation level one. 217.Pp 218The 219.Va rate 220is always set to \-1. 221.Pp 222The 223.Va resolution 224is always set to \-1. 225.Pp 226The 227.Va accelfactor 228is always 0. 229.Pp 230The 231.Va packetsize 232field specifies the length of the data packet. 233It depends on the 234operation level. 235.Pp 236.Bl -tag -width level_0__ -compact 237.It Em level 0 2385 bytes 239.It Em level 1 2408 bytes 241.El 242.Pp 243The array 244.Va syncmask 245holds a bit mask and pattern to detect the first byte of the 246data packet. 247.Va syncmask[0] 248is the bit mask to be ANDed with a byte. 249If the result is equal to 250.Va syncmask[1] , 251the byte is likely to be the first byte of the data packet. 252Note that this method of detecting the first byte is not 100% reliable; 253thus, it should be taken only as an advisory measure. 254.Pp 255.It Dv MOUSE_SETMODE Ar mousemode_t *mode 256The command changes the current operation parameters of the mouse driver 257as specified in 258.Ar mode . 259Only 260.Va level 261may be modifiable. 262Setting values in the other field does not generate 263error and has no effect. 264.Pp 265.It Dv MOUSE_READDATA Ar mousedata_t *data 266.It Dv MOUSE_READSTATE Ar mousedata_t *state 267These commands are not supported by the 268.Nm 269driver. 270.Pp 271.It Dv MOUSE_GETSTATUS Ar mousestatus_t *status 272The command returns the current state of buttons and 273movement counts in the structure as defined in 274.Xr mouse 4 . 275.El 276.Ss Console and Consolectl Ioctls 277The user process issues console 278.Fn ioctl 279calls to the current virtual console in order to control 280the mouse pointer. 281The console 282.Fn ioctl 283also provides a method for the user process to receive a 284.Xr signal 3 285when a button is pressed. 286.Pp 287The mouse daemon 288.Xr moused 8 289uses 290.Fn ioctl 291calls to the console control device 292.Pa /dev/consolectl 293to inform the console of mouse actions including mouse movement 294and button status. 295.Pp 296Both classes of 297.Fn ioctl 298commands are defined as 299.Dv CONS_MOUSECTL 300which takes the following argument. 301.Bd -literal 302struct mouse_info { 303 int operation; 304 union { 305 struct mouse_data data; 306 struct mouse_mode mode; 307 struct mouse_event event; 308 } u; 309}; 310.Ed 311.Pp 312.Bl -tag -width operation -compact 313.It Va operation 314This can be one of 315.Pp 316.Bl -tag -width MOUSE_MOVEABS -compact 317.It Dv MOUSE_SHOW 318Enables and displays mouse cursor. 319.It Dv MOUSE_HIDE 320Disables and hides mouse cursor. 321.It Dv MOUSE_MOVEABS 322Moves mouse cursor to position supplied in 323.Va u.data . 324.It Dv MOUSE_MOVEREL 325Adds position supplied in 326.Va u.data 327to current position. 328.It Dv MOUSE_GETINFO 329Returns current mouse position in the current virtual console 330and button status in 331.Va u.data . 332.It Dv MOUSE_MODE 333This sets the 334.Xr signal 3 335to be delivered to the current process when a button is pressed. 336The signal to be delivered is set in 337.Va u.mode . 338.El 339.Pp 340The above operations are for virtual consoles. 341The operations defined 342below are for the console control device and are used by 343.Xr moused 8 344to pass mouse data to the console driver. 345.Pp 346.Bl -tag -width MOUSE_MOVEABS -compact 347.It Dv MOUSE_ACTION 348.It Dv MOUSE_MOTION_EVENT 349These operations take the information in 350.Va u.data 351and act upon it. 352Mouse data will be sent to the 353.Nm 354driver if it is open. 355.Dv MOUSE_ACTION 356also processes button press actions and sends signal to the process if 357requested or performs cut and paste operations 358if the current console is a text interface. 359.It Dv MOUSE_BUTTON_EVENT 360.Va u.data 361specifies a button and its click count. 362The console driver will 363use this information for signal delivery if requested or 364for cut and paste operations if the console is in text mode. 365.El 366.Pp 367.Dv MOUSE_MOTION_EVENT 368and 369.Dv MOUSE_BUTTON_EVENT 370are newer interface and are designed to be used together. 371They are intended to replace functions performed by 372.Dv MOUSE_ACTION 373alone. 374.Pp 375.It Va u 376This union is one of 377.Pp 378.Bl -tag -width data -compact 379.It Va data 380.Bd -literal 381struct mouse_data { 382 int x; 383 int y; 384 int z; 385 int buttons; 386}; 387.Ed 388.Pp 389.Va x , y 390and 391.Va z 392represent movement of the mouse along respective directions. 393.Va buttons 394tells the state of buttons. 395It encodes up to 31 buttons in the bit 0 though 396the bit 30. 397If a button is held down, the corresponding bit is set. 398.Pp 399.It Va mode 400.Bd -literal 401struct mouse_mode { 402 int mode; 403 int signal; 404}; 405.Ed 406.Pp 407The 408.Va signal 409field specifies the signal to be delivered to the process. 410It must be 411one of the values defined in 412.In signal.h . 413The 414.Va mode 415field is currently unused. 416.Pp 417.It Va event 418.Bd -literal 419struct mouse_event { 420 int id; 421 int value; 422}; 423.Ed 424.Pp 425The 426.Va id 427field specifies a button number as in 428.Va u.data.buttons . 429Only one bit/button is set. 430The 431.Va value 432field 433holds the click count: the number of times the user has clicked the button 434successively. 435.El 436.El 437.Sh FILES 438.Bl -tag -width /dev/consolectl -compact 439.It Pa /dev/consolectl 440device to control the console 441.It Pa /dev/sysmouse 442virtualized mouse driver 443.It Pa /dev/ttyv%d 444virtual consoles 445.El 446.Sh SEE ALSO 447.Xr vidcontrol 1 , 448.Xr ioctl 2 , 449.Xr signal 3 , 450.Xr mouse 4 , 451.Xr moused 8 452.Sh HISTORY 453The 454.Nm 455driver first appeared in 456.Fx 2.2 . 457.Sh AUTHORS 458.An -nosplit 459This 460manual page was written by 461.An John-Mark Gurney Aq Mt jmg@FreeBSD.org 462and 463.An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . 464