share/man/man4/sysmouse.4

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