share/man/man4/man4.i386/mse.4

   1 .\" Copyright 1992 by the University of Guelph
   2 .\"
   3 .\" Permission to use, copy and modify this
   4 .\" software and its documentation for any purpose and without
   5 .\" fee is hereby granted, provided that the above copyright
   6 .\" notice appear in all copies and that both that copyright
   7 .\" notice and this permission notice appear in supporting
   8 .\" documentation.
   9 .\" University of Guelph makes no representations about the suitability of
  10 .\" this software for any purpose.  It is provided "as is"
  11 .\" without express or implied warranty.
  12 .\"
  13 .\" $FreeBSD$
  14 .\"
  15 .Dd December 3, 1997
  16 .Dt MSE 4 i386
  17 .Os
  18 .Sh NAME
  19 .Nm mse
  20 .Nd bus and InPort mice driver
  21 .Sh SYNOPSIS
  22 .\" .Cd "options MSE_XXX=N"
  23 .Cd "device mse"
  24 .Pp
  25 In
  26 .Pa /boot/device.hints :
  27 .Cd hint.mse.0.at="isa"
  28 .Cd hint.mse.0.port="0x23c"
  29 .Cd hint.mse.0.irq="5"
  30 .Sh DESCRIPTION
  31 The
  32 .Nm
  33 driver provides support for the bus mouse and the InPort mouse, which
  34 are often collectively called ``bus'' mice, as these mice are sold with
  35 an interface card which needs to be installed in an expansion bus slot.
  36 The interface circuit may come on an integrated I/O card or as an option
  37 on video cards.
  38 .Pp
  39 The bus and InPort mice have two or three buttons,
  40 and a D-sub 9-pin male connector or a round DIN 9-pin
  41 male connector.
  42 .Pp
  43 The primary port address of the bus and InPort mouse interface cards
  44 is usually 0x23c.
  45 Some cards may also be set to use the secondary port
  46 address at 0x238.
  47 The interface cards require a single IRQ, which may be
  48 2, 3, 4 or 5.
  49 Some cards may offer additional IRQs.
  50 The port number and the IRQ number are configured by jumpers on the cards
  51 or by software provided with the card.
  52 .Pp
  53 Frequency, or report rate, at which the device sends movement
  54 and button state reports to the host system, may also be configurable on
  55 some interface cards.
  56 It may be 15, 30, 60 or 120Hz.
  57 .Pp
  58 The difference between the two types of the mice is not in mouse devices
  59 (in fact they are exactly the same).
  60 But in the circuit on the interface
  61 cards.
  62 This means that the device from a bus mouse package can be
  63 connected to the interface card from an InPort mouse package, or vice
  64 versa, provided that their connectors match.
  65 .Ss Operation Levels
  66 The
  67 .Nm
  68 driver has two levels of operation.
  69 The current operation level can be set via an ioctl call.
  70 .Pp
  71 At the level zero the basic support is provided; the device driver will report
  72 horizontal and vertical movement of the attached device
  73 and state of up to three buttons in the format described below.
  74 It is a subset of the MouseSystems protocol.
  75 .Pp
  76 .Bl -tag -width Byte_1 -compact
  77 .It Byte 1
  78 .Bl -tag -width bit_7 -compact
  79 .It bit 7
  80 Always one.
  81 .It bit 6..3
  82 Always zero.
  83 .It bit 2
  84 Left button status; cleared if pressed, otherwise set.
  85 .It bit 1
  86 Middle button status; cleared if pressed, otherwise set.
  87 Always one,
  88 if the device does not have the middle button.
  89 .It bit 0
  90 Right button status; cleared if pressed, otherwise set.
  91 .El
  92 .It Byte 2
  93 Horizontal movement count in two's compliment; -128 through 127.
  94 .It Byte 3
  95 Vertical movement count in two's compliment; -128 through 127.
  96 .It Byte 4
  97 Always zero.
  98 .It Byte 5
  99 Always zero.
 100 .El
 101 .Pp
 102 This is the default level of operation and the driver is initially
 103 at this level when opened by the user program.
 104 .Pp
 105 At the operation level one (extended level), a data packet is encoded
 106 in the standard format
 107 .Dv MOUSE_PROTO_SYSMOUSE
 108 as defined in
 109 .Xr mouse 4 .
 110 .Ss Acceleration
 111 The
 112 .Nm
 113 driver can somewhat `accelerate' the movement of the pointing device.
 114 The faster you move the device, the further the pointer
 115 travels on the screen.
 116 The driver has an internal variable which governs the effect of
 117 the acceleration.
 118 Its value can be modified via the driver flag
 119 or via an ioctl call.
 120 .Ss Device Number
 121 The minor device number of the
 122 .Nm
 123 is made up of:
 124 .Bd -literal -offset indent
 125 minor = (`unit' << 1) | `non-blocking'
 126 .Ed
 127 .Pp
 128 where `unit' is the device number (usually 0) and the `non-blocking' bit
 129 is set to indicate ``do not block waiting for mouse input,
 130 return immediately''.
 131 The `non-blocking' bit should be set for \fIXFree86\fP,
 132 therefore the minor device number usually used for \fIXFree86\fP is 1.
 133 See
 134 .Sx FILES
 135 for device node names.
 136 .Sh DRIVER CONFIGURATION
 137 .\" .Ss Kernel Configuration Options
 138 .Ss Driver Flags
 139 The
 140 .Nm
 141 driver accepts the following driver flag.
 142 Set it in the
 143 kernel configuration file
 144 (see
 145 .Xr config 8 )
 146 or in the User Configuration Menu at
 147 the boot time
 148 (see
 149 .Xr boot 8 ) .
 150 .Bl -tag -width MOUSE
 151 .It bit 4..7 ACCELERATION
 152 This flag controls the amount of acceleration effect.
 153 The smaller the value of this flag is, more sensitive the movement becomes.
 154 The minimum value allowed, thus the value for the most sensitive setting,
 155 is one.
 156 Setting this flag to zero will completely disables the
 157 acceleration effect.
 158 .El
 159 .Sh IOCTLS
 160 There are a few
 161 .Xr ioctl 2
 162 commands for mouse drivers.
 163 These commands and related structures and constants are defined in
 164 .In sys/mouse.h .
 165 General description of the commands is given in
 166 .Xr mouse 4 .
 167 This section explains the features specific to the
 168 .Nm
 169 driver.
 170 .Pp
 171 .Bl -tag -width MOUSE -compact
 172 .It Dv MOUSE_GETLEVEL Ar int *level
 173 .It Dv MOUSE_SETLEVEL Ar int *level
 174 These commands manipulate the operation level of the
 175 .Nm
 176 driver.
 177 .Pp
 178 .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
 179 Returns the hardware information of the attached device in the following
 180 structure.
 181 Only the
 182 .Dv iftype
 183 field is guaranteed to be filled with the correct value by the current
 184 version of the
 185 .Nm
 186 driver.
 187 .Bd -literal
 188 typedef struct mousehw {
 189     int buttons;    /* number of buttons */
 190     int iftype;     /* I/F type */
 191     int type;       /* mouse/track ball/pad... */
 192     int model;      /* I/F dependent model ID */
 193     int hwid;       /* I/F dependent hardware ID */
 194 } mousehw_t;
 195 .Ed
 196 .Pp
 197 The
 198 .Dv buttons
 199 field holds the number of buttons on the device.
 200 .Pp
 201 The
 202 .Dv iftype
 203 is either
 204 .Dv MOUSE_IF_BUS
 205 or
 206 .Dv MOUSE_IF_INPORT .
 207 .Pp
 208 The
 209 .Dv type
 210 may be
 211 .Dv MOUSE_MOUSE ,
 212 .Dv MOUSE_TRACKBALL ,
 213 .Dv MOUSE_STICK ,
 214 .Dv MOUSE_PAD ,
 215 or
 216 .Dv MOUSE_UNKNOWN .
 217 .Pp
 218 The
 219 .Dv model
 220 is always
 221 .Dv MOUSE_MODEL_GENERIC
 222 at the operation level 0.
 223 It may be
 224 .Dv MOUSE_MODEL_GENERIC
 225 or one of
 226 .Dv MOUSE_MODEL_XXX
 227 constants at higher operation levels.
 228 .Pp
 229 The
 230 .Dv hwid
 231 is always 0.
 232 .Pp
 233 .It Dv MOUSE_GETMODE Ar mousemode_t *mode
 234 The command gets the current operation parameters of the mouse
 235 driver.
 236 .Bd -literal
 237 typedef struct mousemode {
 238     int protocol;    /* MOUSE_PROTO_XXX */
 239     int rate;        /* report rate (per sec), -1 if unknown */
 240     int resolution;  /* MOUSE_RES_XXX, -1 if unknown */
 241     int accelfactor; /* acceleration factor */
 242     int level;       /* driver operation level */
 243     int packetsize;  /* the length of the data packet */
 244     unsigned char syncmask[2]; /* sync. bits */
 245 } mousemode_t;
 246 .Ed
 247 .Pp
 248 The
 249 .Dv protocol
 250 is either
 251 .Dv MOUSE_PROTO_BUS
 252 or
 253 .Dv MOUSE_PROTO_INPORT
 254 at the operation level zero.
 255 .Dv MOUSE_PROTO_SYSMOUSE
 256 at the operation level one.
 257 .Pp
 258 The
 259 .Dv rate
 260 is the status report rate (reports/sec) at which the device will send
 261 movement report to the host computer.
 262 As there is no standard to detect the current setting,
 263 this field is always set to -1.
 264 .Pp
 265 The
 266 .Dv resolution
 267 is always set to -1.
 268 .Pp
 269 The
 270 .Dv accelfactor
 271 field holds a value to control acceleration feature
 272 (see
 273 .Sx Acceleration ) .
 274 It is zero or greater.
 275 If it is zero, acceleration is disabled.
 276 .Pp
 277 The
 278 .Dv packetsize
 279 field specifies the length of the data packet.
 280 It depends on the
 281 operation level.
 282 .Pp
 283 .Bl -tag -width level_0__ -compact
 284 .It Em level 0
 285 5 bytes
 286 .It Em level 1
 287 8 bytes
 288 .El
 289 .Pp
 290 The array
 291 .Dv syncmask
 292 holds a bit mask and pattern to detect the first byte of the
 293 data packet.
 294 .Dv syncmask[0]
 295 is the bit mask to be ANDed with a byte.
 296 If the result is equal to
 297 .Dv syncmask[1] ,
 298 the byte is likely to be the first byte of the data packet.
 299 Note that this detection method is not 100% reliable,
 300 thus, should be taken only as an advisory measure.
 301 .Pp
 302 Only
 303 .Dv level
 304 and
 305 .Dv accelfactor
 306 are modifiable by the
 307 .Dv MOUSE_SETMODE
 308 command.
 309 Changing the other field does not cause error, but has no effect.
 310 .Pp
 311 .It Dv MOUSE_SETMODE Ar mousemode_t *mode
 312 The command changes the current operation parameters of the mouse driver
 313 as specified in
 314 .Ar mode .
 315 Only
 316 .Dv level
 317 and
 318 .Dv accelfactor
 319 may be modifiable.
 320 Setting values in the other field does not generate
 321 error and has no effect.
 322 .\" .Pp
 323 .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
 324 .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
 325 .\" These commands are not supported by the
 326 .\" .Nm
 327 .\" driver.
 328 .Pp
 329 .It Dv MOUSE_READDATA Ar mousedata_t *data
 330 .It Dv MOUSE_READSTATE Ar mousedata_t *state
 331 These commands are not supported by the
 332 .Nm
 333 driver.
 334 .Pp
 335 .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status
 336 The command returns the current state of buttons and
 337 movement counts as described in
 338 .Xr mouse 4 .
 339 .El
 340 .Sh FILES
 341 .Bl -tag -width /dev/nmse0 -compact
 342 .It Pa /dev/mse0
 343 `non-blocking' device node in the system without
 344 .Em devfs ,
 345 `blocking' under
 346 .Em devfs .
 347 .It Pa /dev/nmse0
 348 `non-blocking' device node under
 349 .Em devfs .
 350 .El
 351 .Sh EXAMPLES
 352 .Dl "device mse"
 353 .Pp
 354 In
 355 .Pa /boot/device.hints :
 356 .Dl hint.mse.0.at="isa"
 357 .Dl hint.mse.0.port="0x23c"
 358 .Dl hint.mse.0.irq="5"
 359 .Pp
 360 Add the
 361 .Nm
 362 driver at the primary port address with the IRQ 5.
 363 .Pp
 364 .Dl "device mse"
 365 .Pp
 366 .Dl hint.mse.1.at="isa"
 367 .Dl hint.mse.1.port="0x238"
 368 .Dl hint.mse.1.irq="4"
 369 .Dl hint.mse.1.flags="0x30"
 370 .Pp
 371 Define the
 372 .Nm
 373 driver at the secondary port address with the IRQ 4 and the acceleration
 374 factor of 3.
 375 .Sh SEE ALSO
 376 .Xr ioctl 2 ,
 377 .Xr mouse 4 ,
 378 .Xr psm 4 ,
 379 .Xr sysmouse 4 ,
 380 .Xr moused 8
 381 .\".Sh HISTORY
 382 .Sh CAVEATS
 383 Some bus mouse interface cards generate interrupts at the fixed report rate
 384 when enabled, whether or not the mouse state is changing.
 385 The others generate interrupts only when the state is changing.