| 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.4 2008/05/02 02:05:06 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 complement; -128 through 127. |
| 87 | .It Byte 3 |
| 88 | Vertical movement count in two's complement; -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 | .Bl -tag -width MOUSE |
| 144 | .It bit 4..7 ACCELERATION |
| 145 | This flag controls the amount of acceleration effect. |
| 146 | The smaller the value of this flag is, more sensitive the movement becomes. |
| 147 | The minimum value allowed, thus the value for the most sensitive setting, |
| 148 | is one. |
| 149 | Setting this flag to zero will completely disables the |
| 150 | acceleration effect. |
| 151 | .El |
| 152 | .Sh IOCTLS |
| 153 | There are a few |
| 154 | .Xr ioctl 2 |
| 155 | commands for mouse drivers. |
| 156 | These commands and related structures and constants are defined in |
| 157 | .In machine/mouse.h . |
| 158 | General description of the commands is given in |
| 159 | .Xr mouse 4 . |
| 160 | This section explains the features specific to the |
| 161 | .Nm |
| 162 | driver. |
| 163 | .Pp |
| 164 | .Bl -tag -width MOUSE -compact |
| 165 | .It Dv MOUSE_GETLEVEL Ar int *level |
| 166 | .It Dv MOUSE_SETLEVEL Ar int *level |
| 167 | These commands manipulate the operation level of the |
| 168 | .Nm |
| 169 | driver. |
| 170 | .Pp |
| 171 | .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw |
| 172 | Returns the hardware information of the attached device in the following |
| 173 | structure. |
| 174 | Only the |
| 175 | .Dv iftype |
| 176 | field is guaranteed to be filled with the correct value by the current |
| 177 | version of the |
| 178 | .Nm |
| 179 | driver. |
| 180 | .Bd -literal |
| 181 | typedef struct mousehw { |
| 182 | int buttons; /* number of buttons */ |
| 183 | int iftype; /* I/F type */ |
| 184 | int type; /* mouse/track ball/pad... */ |
| 185 | int model; /* I/F dependent model ID */ |
| 186 | int hwid; /* I/F dependent hardware ID */ |
| 187 | } mousehw_t; |
| 188 | .Ed |
| 189 | .Pp |
| 190 | The |
| 191 | .Dv buttons |
| 192 | field holds the number of buttons on the device. |
| 193 | .Pp |
| 194 | The |
| 195 | .Dv iftype |
| 196 | is either |
| 197 | .Dv MOUSE_IF_BUS |
| 198 | or |
| 199 | .Dv MOUSE_IF_INPORT . |
| 200 | .Pp |
| 201 | The |
| 202 | .Dv type |
| 203 | may be |
| 204 | .Dv MOUSE_MOUSE , |
| 205 | .Dv MOUSE_TRACKBALL , |
| 206 | .Dv MOUSE_STICK , |
| 207 | .Dv MOUSE_PAD , |
| 208 | or |
| 209 | .Dv MOUSE_UNKNOWN . |
| 210 | .Pp |
| 211 | The |
| 212 | .Dv model |
| 213 | is always |
| 214 | .Dv MOUSE_MODEL_GENERIC |
| 215 | at the operation level 0. |
| 216 | It may be |
| 217 | .Dv MOUSE_MODEL_GENERIC |
| 218 | or one of |
| 219 | .Dv MOUSE_MODEL_XXX |
| 220 | constants at higher operation levels. |
| 221 | .Pp |
| 222 | The |
| 223 | .Dv hwid |
| 224 | is always 0. |
| 225 | .Pp |
| 226 | .It Dv MOUSE_GETMODE Ar mousemode_t *mode |
| 227 | The command gets the current operation parameters of the mouse |
| 228 | driver. |
| 229 | .Bd -literal |
| 230 | typedef struct mousemode { |
| 231 | int protocol; /* MOUSE_PROTO_XXX */ |
| 232 | int rate; /* report rate (per sec), -1 if unknown */ |
| 233 | int resolution; /* MOUSE_RES_XXX, -1 if unknown */ |
| 234 | int accelfactor; /* acceleration factor */ |
| 235 | int level; /* driver operation level */ |
| 236 | int packetsize; /* the length of the data packet */ |
| 237 | unsigned char syncmask[2]; /* sync. bits */ |
| 238 | } mousemode_t; |
| 239 | .Ed |
| 240 | .Pp |
| 241 | The |
| 242 | .Dv protocol |
| 243 | is either |
| 244 | .Dv MOUSE_PROTO_BUS |
| 245 | or |
| 246 | .Dv MOUSE_PROTO_INPORT |
| 247 | at the operation level zero. |
| 248 | .Dv MOUSE_PROTO_SYSMOUSE |
| 249 | at the operation level one. |
| 250 | .Pp |
| 251 | The |
| 252 | .Dv rate |
| 253 | is the status report rate (reports/sec) at which the device will send |
| 254 | movement report to the host computer. |
| 255 | As there is no standard to detect the current setting, |
| 256 | this field is always set to -1. |
| 257 | .Pp |
| 258 | The |
| 259 | .Dv resolution |
| 260 | is always set to -1. |
| 261 | .Pp |
| 262 | The |
| 263 | .Dv accelfactor |
| 264 | field holds a value to control acceleration feature |
| 265 | (see |
| 266 | .Sx Acceleration ) . |
| 267 | It is zero or greater. |
| 268 | If it is zero, acceleration is disabled. |
| 269 | .Pp |
| 270 | The |
| 271 | .Dv packetsize |
| 272 | field specifies the length of the data packet. |
| 273 | It depends on the |
| 274 | operation level. |
| 275 | .Pp |
| 276 | .Bl -tag -width level_0__ -compact |
| 277 | .It Em level 0 |
| 278 | 5 bytes |
| 279 | .It Em level 1 |
| 280 | 8 bytes |
| 281 | .El |
| 282 | .Pp |
| 283 | The array |
| 284 | .Dv syncmask |
| 285 | holds a bit mask and pattern to detect the first byte of the |
| 286 | data packet. |
| 287 | .Dv syncmask[0] |
| 288 | is the bit mask to be ANDed with a byte. |
| 289 | If the result is equal to |
| 290 | .Dv syncmask[1] , |
| 291 | the byte is likely to be the first byte of the data packet. |
| 292 | Note that this detection method is not 100% reliable, |
| 293 | thus, should be taken only as an advisory measure. |
| 294 | .Pp |
| 295 | Only |
| 296 | .Dv level |
| 297 | and |
| 298 | .Dv accelfactor |
| 299 | are modifiable by the |
| 300 | .Dv MOUSE_SETMODE |
| 301 | command. |
| 302 | Changing the other field doesn't cause error, but has no effect. |
| 303 | .Pp |
| 304 | .It Dv MOUSE_SETMODE Ar mousemode_t *mode |
| 305 | The command changes the current operation parameters of the mouse driver |
| 306 | as specified in |
| 307 | .Ar mode . |
| 308 | Only |
| 309 | .Dv level |
| 310 | and |
| 311 | .Dv accelfactor |
| 312 | may be modifiable. |
| 313 | Setting values in the other field does not generate |
| 314 | error and has no effect. |
| 315 | .\" .Pp |
| 316 | .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars |
| 317 | .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars |
| 318 | .\" These commands are not supported by the |
| 319 | .\" .Nm |
| 320 | .\" driver. |
| 321 | .Pp |
| 322 | .It Dv MOUSE_READDATA Ar mousedata_t *data |
| 323 | .It Dv MOUSE_READSTATE Ar mousedata_t *state |
| 324 | These commands are not supported by the |
| 325 | .Nm |
| 326 | driver. |
| 327 | .Pp |
| 328 | .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status |
| 329 | The command returns the current state of buttons and |
| 330 | movement counts as described in |
| 331 | .Xr mouse 4 . |
| 332 | .El |
| 333 | .Sh FILES |
| 334 | .Bl -tag -width /dev/nmse0 -compact |
| 335 | .It Pa /dev/mse0 |
| 336 | `non-blocking' device node |
| 337 | .It Pa /dev/nmse0 |
| 338 | `non-blocking' device node |
| 339 | .El |
| 340 | .Sh EXAMPLES |
| 341 | .Dl "device mse0 at isa? port 0x23c irq 5" |
| 342 | .Pp |
| 343 | Add the |
| 344 | .Nm |
| 345 | driver at the primary port address with the IRQ 5. |
| 346 | .Pp |
| 347 | .Dl "device mse1 at isa? port 0x238 flags 0x30 irq 4" |
| 348 | .Pp |
| 349 | Define the |
| 350 | .Nm |
| 351 | driver at the secondary port address with the IRQ 4 and the acceleration |
| 352 | factor of 3. |
| 353 | .Sh CAVEAT |
| 354 | Some bus mouse interface cards generate interrupts at the fixed report rate |
| 355 | when enabled, whether or not the mouse state is changing. |
| 356 | The others generate interrupts only when the state is changing. |
| 357 | .Sh SEE ALSO |
| 358 | .Xr ioctl 2 , |
| 359 | .Xr mouse 4 , |
| 360 | .Xr psm 4 , |
| 361 | .Xr sysmouse 4 , |
| 362 | .Xr moused 8 |
| 363 | .\".Sh HISTORY |