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