share/man/man4/sysmouse.4

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