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