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: src/share/man/man4/sysmouse.4,v 1.12.2.5 2001/12/17 11:30:12 ru Exp $ 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 machine/console.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.Ss Operation Levels 63The 64.Nm 65driver has two levels of operation. 66The current operation level can be referred to and changed via ioctl calls. 67.Pp 68The level zero, the basic level, is the lowest level at which the driver 69offers the basic service to user programs. 70The 71.Nm 72driver 73provides horizontal and vertical movement of the mouse 74and state of up to three buttons in the 75.Tn MouseSystems 76format as follows. 77.Pp 78.Bl -tag -width Byte_1 -compact 79.It Byte 1 80.Bl -tag -width bit_7 -compact 81.It bit 7 82Always one. 83.It bit 6..3 84Always zero. 85.It bit 2 86Left button status; cleared if pressed, otherwise set. 87.It bit 1 88Middle button status; cleared if pressed, otherwise set. 89Always one, 90if the device does not have the middle button. 91.It bit 0 92Right button status; cleared if pressed, otherwise set. 93.El 94.It Byte 2 95The first half of horizontal movement count in two's complement; 96-128 through 127. 97.It Byte 3 98The first half of vertical movement count in two's complement; 99-128 through 127. 100.It Byte 4 101The second half of the horizontal movement count in two's complement; 102-128 through 127. To obtain the full horizontal movement count, add 103the byte 2 and 4. 104.It Byte 5 105The second half of the vertical movement count in two's complement; 106-128 through 127. To obtain the full vertical movement count, add 107the byte 3 and 5. 108.El 109.Pp 110At the level one, the extended level, mouse data is encoded 111in the standard format 112.Dv MOUSE_PROTO_SYSMOUSE 113as defined in 114.Xr mouse 4 . 115.\" .Ss Acceleration 116.\" The 117.\" .Nm 118.\" driver can somewhat `accelerate' the movement of the pointing device. 119.\" The faster you move the device, the further the pointer 120.\" travels on the screen. 121.\" The driver has an internal variable which governs the effect of 122.\" the acceleration. Its value can be modified via the driver flag 123.\" or via an ioctl call. 124.Sh IOCTLS 125This section describes two classes of 126.Xr ioctl 2 127commands: 128commands for the 129.Nm 130driver itself, and commands for the console and the console control drivers. 131.Ss Sysmouse Ioctls 132There are a few commands for mouse drivers. 133General description of the commands is given in 134.Xr mouse 4 . 135Following are the features specific to the 136.Nm 137driver. 138.Pp 139.Bl -tag -width MOUSE -compact 140.It Dv MOUSE_GETLEVEL Ar int *level 141.It Dv MOUSE_SETLEVEL Ar int *level 142These commands manipulate the operation level of the mouse driver. 143.Pp 144.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw 145Returns the hardware information of the attached device in the following 146structure. Only the 147.Dv 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.Dv buttons 164field holds the number of buttons detected by the driver. 165.Pp 166The 167.Dv iftype 168is always 169.Dv MOUSE_IF_SYSMOUSE . 170.Pp 171The 172.Dv 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.Dv 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.Dv 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.Dv 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.Dv rate 223is always set to -1. 224.Pp 225The 226.Dv resolution 227is always set to -1. 228.Pp 229The 230.Dv accelfactor 231is always 0. 232.Pp 233The 234.Dv 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.Dv syncmask 248holds a bit mask and pattern to detect the first byte of the 249data packet. 250.Dv syncmask[0] 251is the bit mask to be ANDed with a byte. 252If the result is equal to 253.Dv 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.Dv 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 Dv 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.Dv u.data . 333.It Dv MOUSE_MOVEREL 334Adds position supplied in 335.Dv u.data 336to current position. 337.It Dv MOUSE_GETINFO 338Returns current mouse position in the current virtual console 339and button status in 340.Dv 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.Dv 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_MOTIONEVENT 358These operations take the information in 359.Dv u.data 360and act upon it. Mouse data will be sent to the 361.Nm 362driver if it is open. 363.Dv MOUSE_ACTION 364also processes button press actions and sends signal to the process if 365requested or performs cut and paste operations 366if the current console is a text interface. 367.It Dv MOUSE_BUTTONEVENT 368.Dv u.data 369specifies a button and its click count. 370The console driver will 371use this information for signal delivery if requested or 372for cut and paste operations if the console is in text mode. 373.El 374.Pp 375.Dv MOUSE_MOTIONEVENT 376and 377.Dv MOUSE_BUTTONEVENT 378are newer interface and are designed to be used together. 379They are intended to replace functions performed by 380.Dv MOUSE_ACTION 381alone. 382.Pp 383.It Dv u 384This union is one of 385.Pp 386.Bl -tag -width data -compact 387.It Dv data 388.Bd -literal 389struct mouse_data { 390 int x; 391 int y; 392 int z; 393 int buttons; 394}; 395.Ed 396.Pp 397.Dv x , 398.Dv y 399and 400.Dv z 401represent movement of the mouse along respective directions. 402.Dv buttons 403tells the state of buttons. 404It encodes up to 31 buttons in the bit 0 though 405the bit 30. If a button is held down, the corresponding bit is set. 406.Pp 407.It Dv mode 408.Bd -literal 409struct mouse_mode { 410 int mode; 411 int signal; 412}; 413.Ed 414.Pp 415The 416.Dv signal 417field specifies the signal to be delivered to the process. 418It must be 419one of the values defined in 420.In signal.h . 421The 422.Dv mode 423field is currently unused. 424.Pp 425.It Dv event 426.Bd -literal 427struct mouse_event { 428 int id; 429 int value; 430}; 431.Ed 432.Pp 433The 434.Dv id 435field specifies a button number as in 436.Dv u.data.buttons . 437Only one bit/button is set. 438The 439.Dv value 440field 441holds the click count: the number of times the user has clicked the button 442successively. 443.El 444.El 445.Sh FILES 446.Bl -tag -width /dev/consolectl -compact 447.It Pa /dev/consolectl 448device to control the console 449.It Pa /dev/sysmouse 450virtualized mouse driver 451.It Pa /dev/ttyv%d 452virtual consoles 453.El 454.Sh SEE ALSO 455.Xr vidcontrol 1 , 456.Xr ioctl 2 , 457.Xr signal 3 , 458.Xr mouse 4 , 459.Xr moused 8 460.Sh HISTORY 461The 462.Nm 463manual page example first appeared in 464.Fx 2.2 . 465.Sh AUTHORS 466.An -nosplit 467This 468manual page was written by 469.An John-Mark Gurney Aq Mt gurney_j@efn.org 470and 471.An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . 472