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