share/man/man4/mouse.4

   1 .\"
   2 .\" Copyright (c) 1997
   3 .\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer as
  11 .\"    the first lines of this file unmodified.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD: src/share/man/man4/mouse.4,v 1.8.2.3 2001/12/17 11:30:12 ru Exp $
  28 .\"
  29 .Dd December 3, 1997
  30 .Dt MOUSE 4
  31 .Os
  32 .Sh NAME
  33 .Nm mouse
  34 .Nd mouse and pointing device drivers
  35 .Sh SYNOPSIS
  36 .In machine/mouse.h
  37 .Sh DESCRIPTION
  38 The mouse drivers
  39 .Xr mse 4 ,
  40 .Xr psm 4 ,
  41 .Xr ums 4
  42 and
  43 .Xr sysmouse 4
  44 provide user programs with movement and button state information of the mouse.
  45 Currently there are specific device drivers for bus, InPort, PS/2, and USB mice.
  46 The serial mouse is not directly supported by a dedicated driver, but
  47 it is accessible via the serial device driver or via
  48 .Xr moused 8
  49 and
  50 .Xr sysmouse 4 .
  51 .Pp
  52 The user program simply opens a mouse device with a
  53 .Xr open 2
  54 call and reads
  55 mouse data from the device via
  56 .Xr read 2 .
  57 Movement and button states are usually encoded in fixed-length data packets.
  58 Some mouse devices may send data in variable length of packets.
  59 Actual protocol (data format) used by each driver differs widely.
  60 .Pp
  61 The mouse drivers may have ``non-blocking'' attribute which will make
  62 the driver return immediately if mouse data is not available.
  63 .Pp
  64 Mouse device drivers often offer several levels of operation.
  65 The current operation level can be examined and changed via
  66 .Xr ioctl 2
  67 commands.
  68 The level zero is the lowest level at which the driver offers the basic
  69 service to user programs.
  70 Most drivers provide horizontal and vertical movement of the mouse
  71 and state of up to three buttons at this level.
  72 At the level one, if supported by the driver, mouse data is encoded
  73 in the standard format
  74 .Dv MOUSE_PROTO_SYSMOUSE
  75 as follows:
  76 .Pp
  77 .Bl -tag -width Byte_1 -compact
  78 .It Byte 1
  79 .Bl -tag -width bit_7 -compact
  80 .It bit 7
  81 Always one.
  82 .It bit 6..3
  83 Always zero.
  84 .It bit 2
  85 Left button status; cleared if pressed, otherwise set.
  86 .It bit 1
  87 Middle button status; cleared if pressed, otherwise set.
  88 Always one,
  89 if the device does not have the middle button.
  90 .It bit 0
  91 Right button status; cleared if pressed, otherwise set.
  92 .El
  93 .It Byte 2
  94 The first half of horizontal movement count in two's complement;
  95 -128 through 127.
  96 .It Byte 3
  97 The first half of vertical movement count in two's complement;
  98 -128 through 127.
  99 .It Byte 4
 100 The second half of the horizontal movement count in two's complement;
 101 -128 through 127. To obtain the full horizontal movement count, add
 102 the byte 2 and 4.
 103 .It Byte 5
 104 The second half of the vertical movement count in two's complement;
 105 -128 through 127. To obtain the full vertical movement count, add
 106 the byte 3 and 5.
 107 .It Byte 6
 108 The bit 7 is always zero.
 109 The lower 7 bits encode the first half of
 110 Z axis movement count in two's complement; -64 through 63.
 111 .It Byte 7
 112 The bit 7 is always zero.
 113 The lower 7 bits encode the second half of
 114 the Z axis movement count in two's complement; -64 through 63.
 115 To obtain the full Z axis movement count, add the byte 6 and 7.
 116 .It Byte 8
 117 The bit 7 is always zero.
 118 The bits 0 through 6 reflect the state
 119 of the buttons 4 through 10.
 120 If a button is pressed, the corresponding bit is cleared.
 121 Otherwise
 122 the bit is set.
 123 .El
 124 .Pp
 125 The first 5 bytes of this format is compatible with the MouseSystems
 126 format.
 127 The additional 3 bytes have their MSBs always set to zero.
 128 Thus, if the user program can interpret the MouseSystems data format and
 129 tries to find the first byte of the format by detecting the bit pattern
 130 10000xxxb,
 131 it will discard the additional bytes, thus, be able to decode x, y
 132 and states of 3 buttons correctly.
 133 .Pp
 134 Device drivers may offer operation levels higher than one.
 135 Refer to manual pages of individual drivers for details.
 136 .Sh IOCTLS
 137 The following
 138 .Xr ioctl 2
 139 commands are defined for the mouse drivers.
 140 The degree of support
 141 varies from one driver to another.
 142 This section gives general
 143 description of the commands.
 144 Refer to manual pages of individual drivers for specific details.
 145 .Pp
 146 .Bl -tag -width MOUSE -compact
 147 .It Dv MOUSE_GETLEVEL Ar int *level
 148 .It Dv MOUSE_SETLEVEL Ar int *level
 149 These commands manipulate the operation level of the mouse driver.
 150 .Pp
 151 .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
 152 Returns the hardware information of the attached device in the following
 153 Except for the
 154 .Dv iftype
 155 field, the device driver may not always fill the structure with correct
 156 values.
 157 Consult manual pages of individual drivers for details of support.
 158 .Bd -literal
 159 typedef struct mousehw {
 160     int buttons;    /* number of buttons */
 161     int iftype;     /* I/F type */
 162     int type;       /* mouse/track ball/pad... */
 163     int model;      /* I/F dependent model ID */
 164     int hwid;       /* I/F dependent hardware ID */
 165 } mousehw_t;
 166 .Ed
 167 .Pp
 168 The
 169 .Dv buttons
 170 field holds the number of buttons detected by the driver.
 171 The driver
 172 may put an arbitrary value, such as two, in this field, if it cannot
 173 determine the exact number.
 174 .Pp
 175 The
 176 .Dv iftype
 177 is the type of interface:
 178 .Dv MOUSE_IF_SERIAL ,
 179 .Dv MOUSE_IF_BUS ,
 180 .Dv MOUSE_IF_INPORT ,
 181 .Dv MOUSE_IF_PS2 ,
 182 .Dv MOUSE_IF_USB ,
 183 .Dv MOUSE_IF_SYSMOUSE
 184 or
 185 .Dv MOUSE_IF_UNKNOWN .
 186 .Pp
 187 The
 188 .Dv type
 189 tells the device type:
 190 .Dv MOUSE_MOUSE ,
 191 .Dv MOUSE_TRACKBALL ,
 192 .Dv MOUSE_STICK ,
 193 .Dv MOUSE_PAD ,
 194 or
 195 .Dv MOUSE_UNKNOWN .
 196 .Pp
 197 The
 198 .Dv model
 199 may be
 200 .Dv MOUSE_MODEL_GENERIC
 201 or one of
 202 .Dv MOUSE_MODEL_XXX
 203 constants.
 204 .Pp
 205 The
 206 .Dv hwid
 207 is the ID value returned by the pointing device.
 208 It
 209 depend on the interface type; refer to the manual page of
 210 specific mouse drivers for possible values.
 211 .Pp
 212 .It Dv MOUSE_GETMODE Ar mousemode_t *mode
 213 The command reports the current operation parameters of the mouse driver.
 214 .Bd -literal
 215 typedef struct mousemode {
 216     int protocol;    /* MOUSE_PROTO_XXX */
 217     int rate;        /* report rate (per sec) */
 218     int resolution;  /* MOUSE_RES_XXX, -1 if unknown */
 219     int accelfactor; /* acceleration factor */
 220     int level;       /* driver operation level */
 221     int packetsize;  /* the length of the data packet */
 222     unsigned char syncmask[2]; /* sync. bits */
 223 } mousemode_t;
 224 .Ed
 225 .Pp
 226 The
 227 .Dv protocol
 228 field tells the format in which the device status is returned
 229 when the mouse data is read by the user program.
 230 It is one of
 231 .Dv MOUSE_PROTO_XXX
 232 constants.
 233 .Pp
 234 The
 235 .Dv rate
 236 field is the status report rate (reports/sec) at which the device will send
 237 movement reports to the host computer. -1 if unknown or not applicable.
 238 .Pp
 239 The
 240 .Dv resolution
 241 field holds a value specifying resolution of the pointing device.
 242 It is a positive value or one of
 243 .Dv MOUSE_RES_XXX
 244 constants.
 245 .Pp
 246 The
 247 .Dv accelfactor
 248 field holds a value to control acceleration feature.
 249 It must be zero or greater.
 250 If it is zero, acceleration is disabled.
 251 .Pp
 252 The
 253 .Dv packetsize
 254 field tells the length of the fixed-size data packet or the length
 255 of the fixed part of the variable-length packet.
 256 The size depends on the interface type, the device type and model, the
 257 protocol and the operation level of the driver.
 258 .Pp
 259 The array
 260 .Dv syncmask
 261 holds a bit mask and pattern to detect the first byte of the
 262 data packet.
 263 .Dv syncmask[0]
 264 is the bit mask to be ANDed with a byte.
 265 If the result is equal to
 266 .Dv syncmask[1] ,
 267 the byte is likely to be the first byte of the data packet.
 268 Note that this method of detecting the first byte is not 100% reliable,
 269 thus, should be taken only as an advisory measure.
 270 .Pp
 271 .It Dv MOUSE_SETMODE Ar mousemode_t *mode
 272 The command changes the current operation parameters of the mouse driver
 273 as specified in
 274 .Ar mode .
 275 Only
 276 .Dv rate ,
 277 .Dv resolution ,
 278 .Dv level
 279 and
 280 .Dv accelfactor
 281 may be modifiable.
 282 Setting values in the other field does not generate
 283 error and has no effect.
 284 .Pp
 285 If you do not want to change the current setting of a field, put -1
 286 there.
 287 You may also put zero in
 288 .Dv resolution
 289 and
 290 .Dv rate ,
 291 and the default value for the fields will be selected.
 292 .\" .Pp
 293 .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
 294 .\" Get internal variables of the mouse driver.
 295 .\" The variables which can be manipulated through these commands
 296 .\" are specific to each driver.
 297 .\" This command may not be supported by all drivers.
 298 .\" .Bd -literal
 299 .\" typedef struct mousevar {
 300 .\"     int var[16];    /* internal variables */
 301 .\" } mousevar_t;
 302 .\" .Ed
 303 .\" .Pp
 304 .\" If the commands are supported, the first element of the array is
 305 .\" filled with a signature value.
 306 .\" Apart from the signature data, there is currently no standard concerning
 307 .\" the other elements of the buffer.
 308 .\" .Pp
 309 .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
 310 .\" Get internal variables of the mouse driver.
 311 .\" The first element of the array must be a signature value.
 312 .\" This command may not be supported by all drivers.
 313 .Pp
 314 .It Dv MOUSE_READDATA Ar mousedata_t *data
 315 The command reads the raw data from the device.
 316 .Bd -literal
 317 typedef struct mousedata {
 318     int len;        /* # of data in the buffer */
 319     int buf[16];    /* data buffer */
 320 } mousedata_t;
 321 .Ed
 322 .Pp
 323 The calling process must fill the
 324 .Dv len
 325 field with the number of bytes to be read into the buffer.
 326 This command may not be supported by all drivers.
 327 .Pp
 328 .It Dv MOUSE_READSTATE Ar mousedata_t *state
 329 The command reads the raw state data from the device.
 330 It uses the same structure as above.
 331 This command may not be supported by all drivers.
 332 .Pp
 333 .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status
 334 The command returns the current state of buttons and
 335 movement counts in the following structure.
 336 .Bd -literal
 337 typedef struct mousestatus {
 338     int flags;      /* state change flags */
 339     int button;     /* button status */
 340     int obutton;    /* previous button status */
 341     int dx;         /* x movement */
 342     int dy;         /* y movement */
 343     int dz;         /* z movement */
 344 } mousestatus_t;
 345 .Ed
 346 .Pp
 347 The
 348 .Dv button
 349 and
 350 .Dv obutton
 351 fields hold the current and the previous state of the mouse buttons.
 352 When a button is pressed, the corresponding bit is set.
 353 The mouse drivers may support up to 31 buttons with the bit 0 through 31.
 354 Few button bits are defined as
 355 .Dv MOUSE_BUTTON1DOWN
 356 through
 357 .Dv MOUSE_BUTTON8DOWN .
 358 The first three buttons correspond to left, middle and right buttons.
 359 .Pp
 360 If the state of the button has changed since the last
 361 .Dv MOUSE_GETSTATUS
 362 call, the corresponding bit in the
 363 .Dv flags
 364 field will be set.
 365 If the mouse has moved since the last call, the
 366 .Dv MOUSE_POSCHANGED
 367 bit in the
 368 .Dv flags
 369 field will also be set.
 370 .Pp
 371 The other fields hold movement counts since the last
 372 .Dv MOUSE_GETSTATUS
 373 call.
 374 The internal counters will be reset after every call to this
 375 command.
 376 .El
 377 .Sh FILES
 378 .Bl -tag -width /dev/sysmouseXX -compact
 379 .It Pa /dev/cuaa%d
 380 serial ports
 381 .It Pa /dev/mse%d
 382 bus and InPort mouse device
 383 .It Pa /dev/psm%d
 384 PS/2 mouse device
 385 .It Pa /dev/sysmouse
 386 virtual mouse device
 387 .It Pa /dev/ums%d
 388 USB mouse device
 389 .El
 390 .Sh SEE ALSO
 391 .Xr ioctl 2 ,
 392 .Xr mse 4 ,
 393 .Xr psm 4 ,
 394 .Xr sysmouse 4 ,
 395 .Xr ums 4 ,
 396 .Xr moused 8
 397 .\".Sh HISTORY
 398 .Sh AUTHORS
 399 This manual page was written by
 400 .An Kazutaka Yokota Aq yokota@FreeBSD.org .