| 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/psm.4,v 1.24.2.9 2002/12/29 16:35:38 schweikh Exp $ |
| 28 | .\" |
| 29 | .Dd October 15, 2010 |
| 30 | .Dt PSM 4 |
| 31 | .Os |
| 32 | .Sh NAME |
| 33 | .Nm psm |
| 34 | .Nd PS/2 mouse style pointing device driver |
| 35 | .Sh SYNOPSIS |
| 36 | .Cd "options KBD_RESETDELAY=N" |
| 37 | .Cd "options KBD_MAXWAIT=N" |
| 38 | .Cd "options PSM_DEBUG=N" |
| 39 | .Cd "options KBDIO_DEBUG=N" |
| 40 | .Cd "device psm0 at atkbdc? irq 12" |
| 41 | .Sh DESCRIPTION |
| 42 | The |
| 43 | .Nm |
| 44 | driver provides support for the PS/2 mouse style pointing device. |
| 45 | Currently there can be only one |
| 46 | .Nm |
| 47 | device node in the system. |
| 48 | As the PS/2 mouse port is located |
| 49 | at the auxiliary port of the keyboard controller, |
| 50 | the keyboard controller driver, |
| 51 | .Nm atkbdc , |
| 52 | must also be configured in the kernel. |
| 53 | Note that there is currently no provision of changing the |
| 54 | .Em irq |
| 55 | number. |
| 56 | .Pp |
| 57 | Basic PS/2 style pointing device has two or three buttons. |
| 58 | Some devices may have a roller or a wheel and/or additional buttons. |
| 59 | .Ss Device Resolution |
| 60 | The PS/2 style pointing device usually has several grades of resolution, |
| 61 | that is, sensitivity of movement. |
| 62 | They are typically 25, 50, 100 and 200 |
| 63 | pulse per inch. |
| 64 | Some devices may have finer resolution. |
| 65 | The current resolution can be changed at runtime. |
| 66 | The |
| 67 | .Nm |
| 68 | driver allows the user to initially set the resolution |
| 69 | via the driver flag |
| 70 | (see |
| 71 | .Sx "DRIVER CONFIGURATION" ) |
| 72 | or change it later via the |
| 73 | .Xr ioctl 2 |
| 74 | command |
| 75 | .Dv MOUSE_SETMODE |
| 76 | (see |
| 77 | .Sx IOCTLS ) . |
| 78 | .Ss Report Rate |
| 79 | Frequency, or report rate, at which the device sends movement |
| 80 | and button state reports to the host system is also configurable. |
| 81 | The PS/2 style pointing device typically supports 10, 20, 40, 60, 80, 100 |
| 82 | and 200 reports per second. |
| 83 | 60 or 100 appears to be the default value for many devices. |
| 84 | Note that when there is no movement and no button has changed its state, |
| 85 | the device won't send anything to the host system. |
| 86 | The report rate can be changed via an ioctl call. |
| 87 | .Ss Operation Levels |
| 88 | The |
| 89 | .Nm |
| 90 | driver has three levels of operation. |
| 91 | The current operation level can be set via an ioctl call. |
| 92 | .Pp |
| 93 | At the level zero the basic support is provided; the device driver will report |
| 94 | horizontal and vertical movement of the attached device |
| 95 | and state of up to three buttons. |
| 96 | The movement and status are encoded in a series of fixed-length data packets |
| 97 | (see |
| 98 | .Sx "Data Packet Format" ) . |
| 99 | This is the default level of operation and the driver is initially |
| 100 | at this level when opened by the user program. |
| 101 | .Pp |
| 102 | The operation level one, the `extended' level, supports a roller (or wheel), |
| 103 | if any, and up to 11 buttons. |
| 104 | The movement of the roller is reported as movement along the Z axis. |
| 105 | 8 byte data packets are sent to the user program at this level. |
| 106 | .Pp |
| 107 | At the operation level two, data from the pointing device is passed to the |
| 108 | user program as is. |
| 109 | Modern PS/2 type pointing devices often use proprietary data format. |
| 110 | Therefore, the user program is expected to have |
| 111 | intimate knowledge about the format from a particular device when operating |
| 112 | the driver at this level. |
| 113 | This level is called `native' level. |
| 114 | .Ss Data Packet Format |
| 115 | Data packets read from the |
| 116 | .Nm |
| 117 | driver are formatted differently at each operation level. |
| 118 | .Pp |
| 119 | A data packet from the PS/2 mouse style pointing device |
| 120 | is three bytes long at the operation level zero: |
| 121 | .Pp |
| 122 | .Bl -tag -width Byte_1 -compact |
| 123 | .It Byte 1 |
| 124 | .Bl -tag -width bit_7 -compact |
| 125 | .It bit 7 |
| 126 | One indicates overflow in the vertical movement count. |
| 127 | .It bit 6 |
| 128 | One indicates overflow in the horizontal movement count. |
| 129 | .It bit 5 |
| 130 | Set if the vertical movement count is negative. |
| 131 | .It bit 4 |
| 132 | Set if the horizontal movement count is negative. |
| 133 | .It bit 3 |
| 134 | Always one. |
| 135 | .\" The ALPS GlidePoint clears this bit when the user `taps' the surface of |
| 136 | .\" the pad, otherwise the bit is set. |
| 137 | .\" Most, if not all, other devices always set this bit. |
| 138 | .It bit 2 |
| 139 | Middle button status; set if pressed. |
| 140 | For devices without the middle |
| 141 | button, this bit is always zero. |
| 142 | .It bit 1 |
| 143 | Right button status; set if pressed. |
| 144 | .It bit 0 |
| 145 | Left button status; set if pressed. |
| 146 | .El |
| 147 | .It Byte 2 |
| 148 | Horizontal movement count in two's complement; |
| 149 | -256 through 255. |
| 150 | Note that the sign bit is in the first byte. |
| 151 | .It Byte 3 |
| 152 | Vertical movement count in two's complement; |
| 153 | -256 through 255. |
| 154 | Note that the sign bit is in the first byte. |
| 155 | .El |
| 156 | .Pp |
| 157 | At the level one, a data packet is encoded |
| 158 | in the standard format |
| 159 | .Dv MOUSE_PROTO_SYSMOUSE |
| 160 | as defined in |
| 161 | .Xr mouse 4 . |
| 162 | .Pp |
| 163 | At the level two, native level, there is no standard on the size and format |
| 164 | of the data packet. |
| 165 | .Ss Acceleration |
| 166 | The |
| 167 | .Nm |
| 168 | driver can somewhat `accelerate' the movement of the pointing device. |
| 169 | The faster you move the device, the further the pointer |
| 170 | travels on the screen. |
| 171 | The driver has an internal variable which governs the effect of |
| 172 | the acceleration. |
| 173 | Its value can be modified via the driver flag |
| 174 | or via an ioctl call. |
| 175 | .Ss Device Number |
| 176 | The minor device number of the |
| 177 | .Nm |
| 178 | is made up of: |
| 179 | .Bd -literal -offset indent |
| 180 | minor = (`unit' << 1) | `non-blocking' |
| 181 | .Ed |
| 182 | .Pp |
| 183 | where `unit' is the device number (usually 0) and the `non-blocking' bit |
| 184 | is set to indicate ``don't block waiting for mouse input, |
| 185 | return immediately''. |
| 186 | The `non-blocking' bit should be set for \fIXFree86\fP, |
| 187 | therefore the minor device number usually used for \fIXFree86\fP is 1. |
| 188 | See |
| 189 | .Sx FILES |
| 190 | for device node names. |
| 191 | .Sh DRIVER CONFIGURATION |
| 192 | .Ss Kernel Configuration Options |
| 193 | There are following kernel configuration options to control the |
| 194 | .Nm |
| 195 | driver. |
| 196 | They may be set in the kernel configuration file |
| 197 | (see |
| 198 | .Xr config 8 ) . |
| 199 | .Bl -tag -width MOUSE |
| 200 | .It Em KBD_RESETDELAY=X , KBD_MAXWAIT=Y |
| 201 | The |
| 202 | .Nm |
| 203 | driver will attempt to reset the pointing device during the boot process. |
| 204 | It sometimes takes a long while before the device will respond after |
| 205 | reset. |
| 206 | These options control how long the driver should wait before |
| 207 | it eventually gives up waiting. |
| 208 | The driver will wait |
| 209 | .Fa X |
| 210 | * |
| 211 | .Fa Y |
| 212 | msecs at most. |
| 213 | If the driver seems unable to detect your pointing |
| 214 | device, you may want to increase these values. |
| 215 | The default values are |
| 216 | 200 msec for |
| 217 | .Fa X |
| 218 | and 5 |
| 219 | for |
| 220 | .Fa Y . |
| 221 | .It Em PSM_DEBUG=N , KBDIO_DEBUG=N |
| 222 | Sets the debug level to |
| 223 | .Fa N . |
| 224 | The default debug level is zero. |
| 225 | See |
| 226 | .Sx DIAGNOSTICS |
| 227 | for debug logging. |
| 228 | .El |
| 229 | .Ss Driver Flags |
| 230 | The |
| 231 | .Nm |
| 232 | driver accepts the following driver flags. |
| 233 | Set them in the |
| 234 | kernel configuration file or in the User Configuration Menu at |
| 235 | the boot time |
| 236 | (see |
| 237 | .Xr boot 8 ) . |
| 238 | .Bl -tag -width MOUSE |
| 239 | .It bit 0..3 RESOLUTION |
| 240 | This flag specifies the resolution of the pointing device. |
| 241 | It must be zero through four. |
| 242 | The greater the value |
| 243 | is, the finer resolution the device will select. |
| 244 | Actual resolution selected by this field varies according to the model |
| 245 | of the device. |
| 246 | Typical resolutions are: |
| 247 | .Pp |
| 248 | .Bl -tag -width 0_(medium_high)__ -compact |
| 249 | .It Em 1 (low) |
| 250 | 25 pulse per inch (ppi) |
| 251 | .It Em 2 (medium low) |
| 252 | 50 ppi |
| 253 | .It Em 3 (medium high) |
| 254 | 100 ppi |
| 255 | .It Em 4 (high) |
| 256 | 200 ppi |
| 257 | .El |
| 258 | .Pp |
| 259 | Leaving this flag zero will selects the default resolution for the |
| 260 | device (whatever it is). |
| 261 | .It bit 4..7 ACCELERATION |
| 262 | This flag controls the amount of acceleration effect. |
| 263 | The smaller the value of this flag is, more sensitive the movement becomes. |
| 264 | The minimum value allowed, thus the value for the most sensitive setting, |
| 265 | is one. |
| 266 | Setting this flag to zero will completely disables the |
| 267 | acceleration effect. |
| 268 | .It bit 8 NOCHECKSYNC |
| 269 | The |
| 270 | .Nm |
| 271 | driver tries to detect the first byte of the data packet by checking |
| 272 | the bit pattern of that byte. |
| 273 | Although this method should work with most |
| 274 | PS/2 pointing devices, it may interfere with some devices which are not |
| 275 | so compatible with known devices. |
| 276 | If you think your pointing device is not functioning as expected, |
| 277 | and the kernel frequently prints the following message to the console, |
| 278 | .Bd -literal -offset indent |
| 279 | psmintr: out of sync (xxxx != yyyy). |
| 280 | .Ed |
| 281 | .Pp |
| 282 | set this flag to disable synchronization check and see if it helps. |
| 283 | .It bit 9 NOIDPROBE |
| 284 | The |
| 285 | .Nm |
| 286 | driver will not try to identify the model of the pointing device and |
| 287 | will not carry out model-specific initialization. |
| 288 | The device should always act like a standard PS/2 mouse without such |
| 289 | initialization. |
| 290 | Extra features, such as wheels and additional buttons, won't be |
| 291 | recognized by the |
| 292 | .Nm |
| 293 | driver. |
| 294 | .It bit 10 NORESET |
| 295 | When this flag is set, the |
| 296 | .Nm |
| 297 | driver won't reset the pointing device when initializing the device. |
| 298 | If the |
| 299 | .Dx |
| 300 | kernel |
| 301 | is started after another OS has run, the pointing device will inherit |
| 302 | settings from the previous OS. |
| 303 | However, because there is no way for the |
| 304 | .Nm |
| 305 | driver to know the settings, the device and the driver may not |
| 306 | work correctly. |
| 307 | The flag should never be necessary under normal circumstances. |
| 308 | .It bit 11 FORCETAP |
| 309 | Some pad devices report as if the fourth button is pressed |
| 310 | when the user `taps' the surface of the device (see |
| 311 | .Sx CAVEATS ) . |
| 312 | This flag will make the |
| 313 | .Nm |
| 314 | driver assume that the device behaves this way. |
| 315 | Without the flag, the driver will assume this behavior |
| 316 | for ALPS GlidePoint models only. |
| 317 | .It bit 12 IGNOREPORTERROR |
| 318 | This flag makes |
| 319 | .Nm |
| 320 | driver ignore certain error conditions when probing the PS/2 mouse port. |
| 321 | It should never be necessary under normal circumstances. |
| 322 | .It bit 13 HOOKRESUME |
| 323 | The built-in PS/2 pointing device of some laptop computers is somehow |
| 324 | not operable immediately after the system `resumes' from |
| 325 | the power saving mode, |
| 326 | though it will eventually become available. |
| 327 | There are reports that |
| 328 | stimulating the device by performing I/O will help |
| 329 | waking up the device quickly. |
| 330 | This flag will enable a piece of code in the |
| 331 | .Nm |
| 332 | driver to hook |
| 333 | the `resume' event and exercise some harmless I/O operations on the |
| 334 | device. |
| 335 | .It bit 14 INITAFTERSUSPEND |
| 336 | This flag adds more drastic action for the above problem. |
| 337 | It will cause the |
| 338 | .Nm |
| 339 | driver to reset and re-initialize the pointing device |
| 340 | after the `resume' event. |
| 341 | It has no effect unless the |
| 342 | .Em HOOKRESUME |
| 343 | flag is set as well. |
| 344 | .El |
| 345 | .Sh LOADER TUNABLES |
| 346 | Extended support for Synaptics touchpads can be enabled by setting |
| 347 | .Va hw.psm.synaptics_support |
| 348 | to |
| 349 | .Em 1 |
| 350 | at boot-time. |
| 351 | This will enable |
| 352 | .Nm |
| 353 | to handle packets from guest devices (sticks) and extra buttons. |
| 354 | .Pp |
| 355 | Tap and drag gestures can be disabled by setting |
| 356 | .Va hw.psm.tap_enabled |
| 357 | to |
| 358 | .Em 0 |
| 359 | at boot-time. |
| 360 | Currently, this is only supported on Synaptics touchpads with Extended |
| 361 | support disabled. The behaviour may be changed after boot by setting |
| 362 | the sysctl with the same name and by restarting |
| 363 | .Xr moused 8 |
| 364 | using |
| 365 | .Pa /etc/rc.d/moused . |
| 366 | .Sh IOCTLS |
| 367 | There are a few |
| 368 | .Xr ioctl 2 |
| 369 | commands for mouse drivers. |
| 370 | These commands and related structures and constants are defined in |
| 371 | .In sys/mouse.h . |
| 372 | General description of the commands is given in |
| 373 | .Xr mouse 4 . |
| 374 | This section explains the features specific to the |
| 375 | .Nm |
| 376 | driver. |
| 377 | .Pp |
| 378 | .Bl -tag -width MOUSE -compact |
| 379 | .It Dv MOUSE_GETLEVEL Ar int *level |
| 380 | .It Dv MOUSE_SETLEVEL Ar int *level |
| 381 | These commands manipulate the operation level of the |
| 382 | .Nm |
| 383 | driver. |
| 384 | .Pp |
| 385 | .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw |
| 386 | Returns the hardware information of the attached device in the following |
| 387 | structure. |
| 388 | .Bd -literal |
| 389 | typedef struct mousehw { |
| 390 | int buttons; /* number of buttons */ |
| 391 | int iftype; /* I/F type */ |
| 392 | int type; /* mouse/track ball/pad... */ |
| 393 | int model; /* I/F dependent model ID */ |
| 394 | int hwid; /* I/F dependent hardware ID */ |
| 395 | } mousehw_t; |
| 396 | .Ed |
| 397 | .Pp |
| 398 | The |
| 399 | .Dv buttons |
| 400 | field holds the number of buttons on the device. |
| 401 | The |
| 402 | .Nm |
| 403 | driver currently can detect the 3 button mouse from Logitech and report |
| 404 | accordingly. |
| 405 | The 3 button mouse from the other manufacturer may or may not be |
| 406 | reported correctly. |
| 407 | However, it will not affect the operation of |
| 408 | the driver. |
| 409 | .Pp |
| 410 | The |
| 411 | .Dv iftype |
| 412 | is always |
| 413 | .Dv MOUSE_IF_PS2 . |
| 414 | .Pp |
| 415 | The |
| 416 | .Dv type |
| 417 | tells the device type: |
| 418 | .Dv MOUSE_MOUSE , |
| 419 | .Dv MOUSE_TRACKBALL , |
| 420 | .Dv MOUSE_STICK , |
| 421 | .Dv MOUSE_PAD , |
| 422 | or |
| 423 | .Dv MOUSE_UNKNOWN . |
| 424 | The user should not heavily rely on this field, as the |
| 425 | driver may not always, in fact it is very rarely able to, identify |
| 426 | the device type. |
| 427 | .Pp |
| 428 | The |
| 429 | .Dv model |
| 430 | is always |
| 431 | .Dv MOUSE_MODEL_GENERIC |
| 432 | at the operation level 0. |
| 433 | It may be |
| 434 | .Dv MOUSE_MODEL_GENERIC |
| 435 | or one of |
| 436 | .Dv MOUSE_MODEL_XXX |
| 437 | constants at higher operation levels. |
| 438 | Again the |
| 439 | .Nm |
| 440 | driver may or may not set an appropriate value in this field. |
| 441 | .Pp |
| 442 | The |
| 443 | .Dv hwid |
| 444 | is the ID value returned by the device. |
| 445 | Known IDs include: |
| 446 | .Pp |
| 447 | .Bl -tag -width 0__ -compact |
| 448 | .It Em 0 |
| 449 | Mouse (Microsoft, Logitech and many other manufacturers) |
| 450 | .It Em 2 |
| 451 | Microsoft Ballpoint mouse |
| 452 | .It Em 3 |
| 453 | Microsoft IntelliMouse |
| 454 | .El |
| 455 | .Pp |
| 456 | .It Dv MOUSE_SYN_GETHWINFO Ar synapticshw_t *synhw |
| 457 | Retrieves extra information associated with Synaptics Touchpads. |
| 458 | Only available when |
| 459 | .Va hw.psm.synaptics_support |
| 460 | has been enabled. |
| 461 | .Bd -literal |
| 462 | typedef struct synapticshw { |
| 463 | int infoMajor; /* major hardware revision */ |
| 464 | int infoMinor; /* minor hardware revision */ |
| 465 | int infoRot180; /* touchpad is rotated */ |
| 466 | int infoPortrait; /* touchpad is a portrait */ |
| 467 | int infoSensor; /* sensor model */ |
| 468 | int infoHardware; /* hardware model */ |
| 469 | int infoNewAbs; /* supports the newabs format */ |
| 470 | int capPen; /* can detect a pen */ |
| 471 | int infoSimpleC; /* supports simple commands */ |
| 472 | int infoGeometry; /* touchpad dimensions */ |
| 473 | int capExtended; /* supports extended packets */ |
| 474 | int capSleep; /* can be suspended/resumed */ |
| 475 | int capFourButtons; /* has four buttons */ |
| 476 | int capMultiFinger; /* can detect multiple fingers */ |
| 477 | int capPalmDetect; /* can detect a palm */ |
| 478 | int capPassthrough; /* can passthrough guest packets */ |
| 479 | } synapticshw_t; |
| 480 | .Ed |
| 481 | .Pp |
| 482 | See the |
| 483 | .Em Synaptics TouchPad Interfacing Guide |
| 484 | for more information about the fields in this structure. |
| 485 | .Pp |
| 486 | .It Dv MOUSE_GETMODE Ar mousemode_t *mode |
| 487 | The command gets the current operation parameters of the mouse |
| 488 | driver. |
| 489 | .Bd -literal |
| 490 | typedef struct mousemode { |
| 491 | int protocol; /* MOUSE_PROTO_XXX */ |
| 492 | int rate; /* report rate (per sec), -1 if unknown */ |
| 493 | int resolution; /* MOUSE_RES_XXX, -1 if unknown */ |
| 494 | int accelfactor; /* acceleration factor */ |
| 495 | int level; /* driver operation level */ |
| 496 | int packetsize; /* the length of the data packet */ |
| 497 | unsigned char syncmask[2]; /* sync. bits */ |
| 498 | } mousemode_t; |
| 499 | .Ed |
| 500 | .Pp |
| 501 | The |
| 502 | .Dv protocol |
| 503 | is |
| 504 | .Dv MOUSE_PROTO_PS2 |
| 505 | at the operation level zero and two. |
| 506 | .Dv MOUSE_PROTO_SYSMOUSE |
| 507 | at the operation level one. |
| 508 | .Pp |
| 509 | The |
| 510 | .Dv rate |
| 511 | is the status report rate (reports/sec) at which the device will send |
| 512 | movement report to the host computer. |
| 513 | Typical supported values are 10, 20, 40, 60, 80, 100 and 200. |
| 514 | Some mice may accept other arbitrary values too. |
| 515 | .Pp |
| 516 | The |
| 517 | .Dv resolution |
| 518 | of the pointing device must be one of |
| 519 | .Dv MOUSE_RES_XXX |
| 520 | constants or a positive value. |
| 521 | The greater the value |
| 522 | is, the finer resolution the mouse will select. |
| 523 | Actual resolution selected by the |
| 524 | .Dv MOUSE_RES_XXX |
| 525 | constant varies according to the model of mouse. |
| 526 | Typical resolutions are: |
| 527 | .Pp |
| 528 | .Bl -tag -width MOUSE_RES_MEDIUMHIGH__ -compact |
| 529 | .It Dv MOUSE_RES_LOW |
| 530 | 25 ppi |
| 531 | .It Dv MOUSE_RES_MEDIUMLOW |
| 532 | 50 ppi |
| 533 | .It Dv MOUSE_RES_MEDIUMHIGH |
| 534 | 100 ppi |
| 535 | .It Dv MOUSE_RES_HIGH |
| 536 | 200 ppi |
| 537 | .El |
| 538 | .Pp |
| 539 | The |
| 540 | .Dv accelfactor |
| 541 | field holds a value to control acceleration feature |
| 542 | (see |
| 543 | .Sx Acceleration ) . |
| 544 | It must be zero or greater. If it is zero, acceleration is disabled. |
| 545 | .Pp |
| 546 | The |
| 547 | .Dv packetsize |
| 548 | field specifies the length of the data packet. |
| 549 | It depends on the |
| 550 | operation level and the model of the pointing device. |
| 551 | .Pp |
| 552 | .Bl -tag -width level_0__ -compact |
| 553 | .It Em level 0 |
| 554 | 3 bytes |
| 555 | .It Em level 1 |
| 556 | 8 bytes |
| 557 | .It Em level 2 |
| 558 | Depends on the model of the device |
| 559 | .El |
| 560 | .Pp |
| 561 | The array |
| 562 | .Dv syncmask |
| 563 | holds a bit mask and pattern to detect the first byte of the |
| 564 | data packet. |
| 565 | .Dv syncmask[0] |
| 566 | is the bit mask to be ANDed with a byte. |
| 567 | If the result is equal to |
| 568 | .Dv syncmask[1] , |
| 569 | the byte is likely to be the first byte of the data packet. |
| 570 | Note that this detection method is not 100% reliable, |
| 571 | thus, should be taken only as an advisory measure. |
| 572 | .Pp |
| 573 | .It Dv MOUSE_SETMODE Ar mousemode_t *mode |
| 574 | The command changes the current operation parameters of the mouse driver |
| 575 | as specified in |
| 576 | .Ar mode . |
| 577 | Only |
| 578 | .Dv rate , |
| 579 | .Dv resolution , |
| 580 | .Dv level |
| 581 | and |
| 582 | .Dv accelfactor |
| 583 | may be modifiable. |
| 584 | Setting values in the other field does not generate |
| 585 | error and has no effect. |
| 586 | .Pp |
| 587 | If you do not want to change the current setting of a field, put -1 |
| 588 | there. |
| 589 | You may also put zero in |
| 590 | .Dv resolution |
| 591 | and |
| 592 | .Dv rate , |
| 593 | and the default value for the fields will be selected. |
| 594 | .\" .Pp |
| 595 | .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars |
| 596 | .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars |
| 597 | .\" These commands are not supported by the |
| 598 | .\" .Nm |
| 599 | .\" driver. |
| 600 | .Pp |
| 601 | .It Dv MOUSE_READDATA Ar mousedata_t *data |
| 602 | .\" The command reads the raw data from the device. |
| 603 | .\" .Bd -literal |
| 604 | .\" typedef struct mousedata { |
| 605 | .\" int len; /* # of data in the buffer */ |
| 606 | .\" int buf[16]; /* data buffer */ |
| 607 | .\" } mousedata_t; |
| 608 | .\" .Ed |
| 609 | .\" .Pp |
| 610 | .\" Upon returning to the user program, the driver will place the number |
| 611 | .\" of valid data bytes in the buffer in the |
| 612 | .\" .Dv len |
| 613 | .\" field. |
| 614 | .\" .Pp |
| 615 | .It Dv MOUSE_READSTATE Ar mousedata_t *state |
| 616 | .\" The command reads the hardware settings from the device. |
| 617 | .\" Upon returning to the user program, the driver will place the number |
| 618 | .\" of valid data bytes in the buffer in the |
| 619 | .\" .Dv len |
| 620 | .\" field. It is usually 3 bytes. |
| 621 | .\" The buffer is formatted as follows: |
| 622 | .\" .Pp |
| 623 | .\" .Bl -tag -width Byte_1 -compact |
| 624 | .\" .It Byte 1 |
| 625 | .\" .Bl -tag -width bit_6 -compact |
| 626 | .\" .It bit 7 |
| 627 | .\" Reserved. |
| 628 | .\" .It bit 6 |
| 629 | .\" 0 - stream mode, 1 - remote mode. |
| 630 | .\" In the stream mode, the pointing device sends the device status |
| 631 | .\" whenever its state changes. In the remote mode, the host computer |
| 632 | .\" must request the status to be sent. |
| 633 | .\" The |
| 634 | .\" .Nm |
| 635 | .\" driver puts the device in the stream mode. |
| 636 | .\" .It bit 5 |
| 637 | .\" Set if the pointing device is currently enabled. Otherwise zero. |
| 638 | .\" .It bit 4 |
| 639 | .\" 0 - 1:1 scaling, 1 - 2:1 scaling. |
| 640 | .\" 1:1 scaling is the default. |
| 641 | .\" .It bit 3 |
| 642 | .\" Reserved. |
| 643 | .\" .It bit 2 |
| 644 | .\" Left button status; set if pressed. |
| 645 | .\" .It bit 1 |
| 646 | .\" Middle button status; set if pressed. |
| 647 | .\" .It bit 0 |
| 648 | .\" Right button status; set if pressed. |
| 649 | .\" .El |
| 650 | .\" .It Byte 2 |
| 651 | .\" .Bl -tag -width bit_6_0 -compact |
| 652 | .\" .It bit 7 |
| 653 | .\" Reserved. |
| 654 | .\" .It bit 6..0 |
| 655 | .\" Resolution code: zero through three. Actual resolution for |
| 656 | .\" the resolution code varies from one device to another. |
| 657 | .\" .El |
| 658 | .\" .It Byte 3 |
| 659 | .\" The status report rate (reports/sec) at which the device will send |
| 660 | .\" movement report to the host computer. |
| 661 | .\" .El |
| 662 | These commands are not currently supported by the |
| 663 | .Nm |
| 664 | driver. |
| 665 | .Pp |
| 666 | .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status |
| 667 | The command returns the current state of buttons and |
| 668 | movement counts as described in |
| 669 | .Xr mouse 4 . |
| 670 | .El |
| 671 | .Sh FILES |
| 672 | .Bl -tag -width /dev/npsm0 -compact |
| 673 | .It Pa /dev/psm0 |
| 674 | `non-blocking' device node |
| 675 | .It Pa /dev/bpsm0 |
| 676 | `blocking' device node |
| 677 | .El |
| 678 | .Sh EXAMPLES |
| 679 | .Dl "device psm0 at atkbdc? irq 12 flags 0x2000" |
| 680 | .Pp |
| 681 | Add the |
| 682 | .Nm |
| 683 | driver to the kernel with the optional code to stimulate the pointing device |
| 684 | after the `resume' event. |
| 685 | .Pp |
| 686 | .Dl "device psm0 at atkbdc? flags 0x024 irq 12" |
| 687 | .Pp |
| 688 | Set the device resolution high (4) and the acceleration factor to 2. |
| 689 | .Sh DIAGNOSTICS |
| 690 | At debug level 0, little information is logged except for the following |
| 691 | line during boot process: |
| 692 | .Bd -literal -offset indent |
| 693 | psm0: device ID X |
| 694 | .Ed |
| 695 | .Pp |
| 696 | where |
| 697 | .Fa X |
| 698 | the device ID code returned by the found pointing device. |
| 699 | See |
| 700 | .Dv MOUSE_GETINFO |
| 701 | for known IDs. |
| 702 | .Pp |
| 703 | At debug level 1 more information will be logged |
| 704 | while the driver probes the auxiliary port (mouse port). |
| 705 | Messages are logged with the LOG_KERN facility at the LOG_DEBUG level |
| 706 | (see |
| 707 | .Xr syslogd 8 ) . |
| 708 | .Bd -literal -offset indent |
| 709 | psm0: current command byte:xxxx |
| 710 | kbdio: TEST_AUX_PORT status:0000 |
| 711 | kbdio: RESET_AUX return code:00fa |
| 712 | kbdio: RESET_AUX status:00aa |
| 713 | kbdio: RESET_AUX ID:0000 |
| 714 | [...] |
| 715 | psm: status 00 02 64 |
| 716 | psm0 irq 12 on isa |
| 717 | psm0: model AAAA, device ID X, N buttons |
| 718 | psm0: config:00000www, flags:0000uuuu, packet size:M |
| 719 | psm0: syncmask:xx, syncbits:yy |
| 720 | .Ed |
| 721 | .Pp |
| 722 | The first line shows the command byte value of the keyboard |
| 723 | controller just before the auxiliary port is probed. |
| 724 | It usually is 4D, 45, 47 or 65, depending on how the motherboard BIOS |
| 725 | initialized the keyboard controller upon power-up. |
| 726 | .Pp |
| 727 | The second line shows the result of the keyboard controller's |
| 728 | test on the auxiliary port interface, with zero indicating |
| 729 | no error; note that some controllers report no error even if |
| 730 | the port does not exist in the system, however. |
| 731 | .Pp |
| 732 | The third through fifth lines show the reset status of the pointing device. |
| 733 | The functioning device should return the sequence of FA AA <ID>. |
| 734 | The ID code is described above. |
| 735 | .Pp |
| 736 | The seventh line shows the current hardware settings. |
| 737 | .\" See |
| 738 | .\" .Dv MOUSE_READSTATE |
| 739 | .\" for definitions. |
| 740 | These bytes are formatted as follows: |
| 741 | .Pp |
| 742 | .Bl -tag -width Byte_1 -compact |
| 743 | .It Byte 1 |
| 744 | .Bl -tag -width bit_6 -compact |
| 745 | .It bit 7 |
| 746 | Reserved. |
| 747 | .It bit 6 |
| 748 | 0 - stream mode, 1 - remote mode. |
| 749 | In the stream mode, the pointing device sends the device status |
| 750 | whenever its state changes. |
| 751 | In the remote mode, the host computer |
| 752 | must request the status to be sent. |
| 753 | The |
| 754 | .Nm |
| 755 | driver puts the device in the stream mode. |
| 756 | .It bit 5 |
| 757 | Set if the pointing device is currently enabled. |
| 758 | Otherwise zero. |
| 759 | .It bit 4 |
| 760 | 0 - 1:1 scaling, 1 - 2:1 scaling. |
| 761 | 1:1 scaling is the default. |
| 762 | .It bit 3 |
| 763 | Reserved. |
| 764 | .It bit 2 |
| 765 | Left button status; set if pressed. |
| 766 | .It bit 1 |
| 767 | Middle button status; set if pressed. |
| 768 | .It bit 0 |
| 769 | Right button status; set if pressed. |
| 770 | .El |
| 771 | .It Byte 2 |
| 772 | .Bl -tag -width bit_6_0 -compact |
| 773 | .It bit 7 |
| 774 | Reserved. |
| 775 | .It bit 6..0 |
| 776 | Resolution code: zero through three. |
| 777 | Actual resolution for |
| 778 | the resolution code varies from one device to another. |
| 779 | .El |
| 780 | .It Byte 3 |
| 781 | The status report rate (reports/sec) at which the device will send |
| 782 | movement report to the host computer. |
| 783 | .El |
| 784 | .Pp |
| 785 | Note that the pointing device will not be enabled until the |
| 786 | .Nm |
| 787 | driver is opened by the user program. |
| 788 | .Pp |
| 789 | The rest of the lines show the device ID code, the number of detected |
| 790 | buttons and internal variables. |
| 791 | .Pp |
| 792 | At debug level 2, much more detailed information is logged. |
| 793 | .Sh CAVEATS |
| 794 | Many pad devices behave as if the first (left) button were pressed if |
| 795 | the user `taps' the surface of the pad. |
| 796 | In contrast, some pad products, e.g. some versions of ALPS GlidePoint |
| 797 | and Interlink VersaPad, treat the tapping action |
| 798 | as fourth button events. |
| 799 | .Pp |
| 800 | It is reported that Interlink VersaPad requires both |
| 801 | .Em HOOKRESUME |
| 802 | and |
| 803 | .Em INITAFTERSUSPEND |
| 804 | flags in order to recover from suspended state. |
| 805 | These flags are automatically set when VersaPad is detected by the |
| 806 | .Nm |
| 807 | driver. |
| 808 | .Pp |
| 809 | Some PS/2 mouse models from MouseSystems require to be put in the |
| 810 | high resolution mode to work properly. |
| 811 | Use the driver flag to |
| 812 | set resolution. |
| 813 | .Pp |
| 814 | There is not a guaranteed way to re-synchronize with the first byte |
| 815 | of the packet once we are out of synchronization with the data |
| 816 | stream. |
| 817 | However, if you are using the \fIXFree86\fP server and experiencing |
| 818 | the problem, you may be able to make the X server synchronize with the mouse |
| 819 | by switching away to a virtual terminal and getting back to the X server, |
| 820 | unless the X server is accessing the mouse via |
| 821 | .Xr moused 8 . |
| 822 | Clicking any button without moving the mouse may also work. |
| 823 | .Sh SEE ALSO |
| 824 | .Xr ioctl 2 , |
| 825 | .Xr syslog 3 , |
| 826 | .Xr atkbdc 4 , |
| 827 | .Xr mouse 4 , |
| 828 | .Xr sysmouse 4 , |
| 829 | .Xr moused 8 , |
| 830 | .Xr syslogd 8 |
| 831 | .Rs |
| 832 | .%T Synaptics TouchPad Interfacing Guide |
| 833 | .%U http://www.synaptics.com/ |
| 834 | .Re |
| 835 | .\".Sh HISTORY |
| 836 | .Sh AUTHORS |
| 837 | .An -nosplit |
| 838 | The |
| 839 | .Nm |
| 840 | driver is based on the work done by quite a number of people, including |
| 841 | .An Eric Forsberg , |
| 842 | .An Sandi Donno , |
| 843 | .An Rick Macklem , |
| 844 | .An Andrew Herbert , |
| 845 | .An Charles Hannum , |
| 846 | .An Shoji Yuen |
| 847 | and |
| 848 | .An Kazutaka Yokota |
| 849 | to name the few. |
| 850 | .Pp |
| 851 | This manual page was written by |
| 852 | .An Kazutaka Yokota Aq yokota@FreeBSD.org . |
| 853 | .Sh BUGS |
| 854 | The ioctl command |
| 855 | .Dv MOUSEIOCREAD |
| 856 | has been removed. |
| 857 | It was never functional anyway. |