3 .\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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.
35 PS/2 mouse style pointing device driver
37 .Cd "options" \&"PSM_HOOKAPM\&"
38 .Cd "options" \&"PSM_RESETAFTERSUSPEND\&"
39 .Cd "options" \&"KBD_RESETDELAY=N\&"
40 .Cd "options" \&"KBD_MAXWAIT=N\&"
41 .Cd "options" \&"PSM_DEBUG=N\&"
42 .Cd "options" \&"KBDIO_DEBUG=N\&"
43 .Cd "device psm0 at atkbdc? irq 12"
47 driver provides support for the PS/2 mouse style pointing device.
48 Currently there can be only one
50 device node in the system.
51 As the PS/2 mouse port is located
52 at the auxiliary port of the keyboard controller,
53 the keyboard controller driver,
55 must also be configured in the kernel.
56 Note that there is currently no provision of changing the
60 Basic PS/2 style pointing device has two or three buttons.
61 Some devices may have a roller or a wheel and/or additional buttons.
63 The PS/2 style pointing device usually has several grades of resolution,
64 that is, sensitivity of movement. They are typically 25, 50, 100 and 200
65 pulse per inch. Some devices may have finer resolution.
66 The current resolution can be changed at runtime. The
68 driver allows the user to initially set the resolution
70 .Pq see Sx DRIVER CONFIGURATION
71 or change it later via the
77 Frequency, or report rate, at which the device sends movement
78 and button state reports to the host system is also configurable.
79 The PS/2 style pointing device typically supports 10, 20, 40, 60, 80, 100
80 and 200 reports per second.
81 60 or 100 appears to be the default value for many devices.
82 Note that when there is no movement and no button has changed its state,
83 the device won't send anything to the host system.
84 The report rate can be changed via an ioctl call.
88 driver has three levels of operation.
89 The current operation level can be set via an ioctl call.
91 At the level zero the basic support is provided; the device driver will report
92 horizontal and vertical movement of the attached device
93 and state of up to three buttons.
94 The movement and status are encoded in a series of fixed-length data packets
95 .Pq see Sx Data Packet Format .
96 This is the default level of operation and the driver is initially
97 at this level when opened by the user program.
99 The operation level one, the `extended' level, supports a roller (or wheel),
100 if any, and up to 11 buttons.
101 The movement of the roller is reported as movement along the Z axis.
102 8 byte data packets are sent to the user program at this level.
104 At the operation level two, data from the pointing device is passed to the
106 Modern PS/2 type pointing devices often use proprietary data format.
107 Therefore, the user program is expected to have
108 intimate knowledge about the format from a particular device when operating
109 the driver at this level.
110 This level is called `native' level.
111 .Ss Data Packet Format
112 Data packets read from the
114 driver are formatted differently at each operation level.
116 A data packet from the PS/2 mouse style pointing device
117 is three bytes long at the operation level zero:
119 .Bl -tag -width Byte_1 -compact
121 .Bl -tag -width bit_7 -compact
123 One indicates overflow in the vertical movement count.
125 One indicates overflow in the horizontal movement count.
127 Set if the vertical movement count is negative.
129 Set if the horizontal movement count is negative.
132 .\" The ALPS GlidePoint clears this bit when the user `taps' the surface of
133 .\" the pad, otherwise the bit is set.
134 .\" Most, if not all, other devices always set this bit.
136 Middle button status; set if pressed. For devices without the middle
137 button, this bit is always zero.
139 Right button status; set if pressed.
141 Left button status; set if pressed.
144 Horizontal movement count in two's compliment;
146 Note that the sign bit is in the first byte.
148 Vertical movement count in two's compliment;
150 Note that the sign bit is in the first byte.
153 At the level one, a data packet is encoded
154 in the standard format
155 .Dv MOUSE_PROTO_SYSMOUSE
159 At the level two, native level, there is no standard on the size and format
164 driver can somewhat `accelerate' the movement of the pointing device.
165 The faster you move the device, the further the pointer
166 travels on the screen.
167 The driver has an internal variable which governs the effect of
168 the acceleration. Its value can be modified via the driver flag
169 or via an ioctl call.
171 The minor device number of the
174 .Bd -literal -offset indent
175 minor = (`unit' << 1) | `non-blocking'
178 where `unit' is the device number (usually 0) and the `non-blocking' bit
179 is set to indicate ``don't block waiting for mouse input,
180 return immediately''.
181 The `non-blocking' bit should be set for \fIXFree86\fP,
182 therefore the minor device number usually used for \fIXFree86\fP is 1.
185 for device node names.
186 .Sh DRIVER CONFIGURATION
187 .Ss Kernel Configuration Options
188 There are following kernel configuration options to control the
191 They may be set in the kernel configuration file
192 .Pq see Xr config 8 .
193 .Bl -tag -width MOUSE
195 The built-in PS/2 pointing device of some laptop computers is somehow
196 not operable immediately after the system `resumes' from
197 the power saving mode,
198 though it will eventually become available.
199 There are reports that
200 stimulating the device by performing I/O will help
201 waking up the device quickly. This option will add a piece of code
205 the APM `resume' event and exercise some harmless I/O operations to the
207 .It Em PSM_RESETAFTERSUSPEND
208 This option adds more drastic action for the above problem.
211 driver to reset the pointing device after the APM resume event.
212 It has no effect unless the
214 option is enabled as well.
215 .It Em KBD_RESETDELAY=X, KBD_MAXWAIT=Y
218 driver will attempt to reset the pointing device during the boot process.
219 It sometimes takes a long while before the device will respond after
220 reset. These options control how long the driver should wait before
221 it eventually gives up waiting. The driver will wait
225 msecs at most. If the driver seems unable to detect your pointing
226 device, you may want to increase these values. The default values are
232 .It Em PSM_DEBUG=N, KBDIO_DEBUG=N
233 Sets the debug level to
235 The default debug level is zero. See
242 driver accepts the following driver flags. Set them in the
243 kernel configuration file or in the User Configuration Menu at
247 .Bl -tag -width MOUSE
248 .It bit 0..3 RESOLUTION
249 This flag specifies the resolution of the pointing device.
250 It must be zero through four. The greater the value
251 is, the finer resolution the device will select.
252 Actual resolution selected by this field varies according to the model
253 of the device. Typical resolutions are:
255 .Bl -tag -width 0_(medium_high)__ -compact
257 25 pulse per inch (ppi)
258 .It Em 2 (medium low)
260 .It Em 3 (medium high)
266 Leaving this flag zero will selects the default resolution for the
267 device (whatever it is).
268 .It bit 4..7 ACCELERATION
269 This flag controls the amount of acceleration effect.
270 The smaller the value of this flag is, more sensitive the movement becomes.
271 The minimum value allowed, thus the value for the most sensitive setting,
272 is one. Setting this flag to zero will completely disables the
274 .It bit 8 NOCHECKSYNC
277 driver tries to detect the first byte of the data packet by checking
278 the bit pattern of that byte. Although this method should work with most
279 PS/2 pointing devices, it may interfere with some devices which are not
280 so compatible with known devices.
281 If you think your pointing device is not functioning as expected,
282 and the kernel frequently prints the following message to the console,
283 .Bd -literal -offset indent
284 psmintr: out of sync (xxxx != yyyy).
287 set this flag to disable synchronization check and see if it helps.
291 driver will not try to identify the model of the pointing device and
292 will not carry out model-specific initialization.
293 The device should always act like a standard PS/2 mouse without such
295 Extra features, such as wheels and additional buttons, won't be
300 When this flag is set, the
302 driver won't reset the pointing device when initializing the device.
303 If the FreeBSD kernel
304 is started after another OS has run, the pointing device will inherit
305 settings from the previous OS.
306 However, because there is no way for the
308 driver to know the settings, the device and the driver may not
310 The flag should never be necessary under normal circumstances.
312 Some pad devices report as if the fourth button is pressed
313 when the user `taps' the surface of the device (see
315 This flag will make the
317 driver assume that the device behaves this way.
318 Without the flag, the driver will assume this behavior
319 for ALPS GlidePoint models only.
320 .It bit 12 IGNOREPORTERROR
323 driver ignore certain error conditions when probing the PS/2 mouse port.
324 It should never be necessary under normal circumstances.
329 commands for mouse drivers.
330 These commands and related structures and constants are defined in
331 .Ao Pa machine/mouse.h Ac .
332 General description of the commands is given in
334 This section explains the features specific to the
338 .Bl -tag -width MOUSE -compact
339 .It Dv MOUSE_GETLEVEL Ar int *level
340 .It Dv MOUSE_SETLEVEL Ar int *level
341 These commands manipulate the operation level of the
345 .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
346 Returns the hardware information of the attached device in the following
349 typedef struct mousehw {
350 int buttons; /* number of buttons */
351 int iftype; /* I/F type */
352 int type; /* mouse/track ball/pad... */
353 int model; /* I/F dependent model ID */
354 int hwid; /* I/F dependent hardware ID */
360 field holds the number of buttons on the device.
363 driver currently can detect the 3 button mouse from Logitech and report
365 The 3 button mouse from the other manufacturer may or may not be
366 reported correctly. However, it will not affect the operation of
376 tells the device type:
378 .Dv MOUSE_TRACKBALL ,
383 The user should not heavily rely on this field, as the
384 driver may not always, in fact it is very rarely able to, identify
390 .Dv MOUSE_MODEL_GENERIC
391 at the operation level 0.
393 .Dv MOUSE_MODEL_GENERIC
396 constants at higher operation levels.
399 driver may or may not set an appropriate value in this field.
403 is the ID value returned by the device.
406 .Bl -tag -width 0__ -compact
408 Mouse (Microsoft, Logitech and many other manufacturers)
410 Microsoft Ballpoint mouse
412 Microsoft IntelliMouse
415 .It Dv MOUSE_GETMODE Ar mousemode_t *mode
416 The command gets the current operation parameters of the mouse
419 typedef struct mousemode {
420 int protocol; /* MOUSE_PROTO_XXX */
421 int rate; /* report rate (per sec), -1 if unknown */
422 int resolution; /* MOUSE_RES_XXX, -1 if unknown */
423 int accelfactor; /* acceleration factor */
424 int level; /* driver operation level */
425 int packetsize; /* the length of the data packet */
426 unsigned char syncmask[2]; /* sync. bits */
434 at the operation level zero and two.
435 .Dv MOUSE_PROTO_SYSMOUSE
436 at the operation level one.
440 is the status report rate (reports/sec) at which the device will send
441 movement report to the host computer.
442 Typical supported values are 10, 20, 40, 60, 80, 100 and 200.
443 Some mice may accept other arbitrary values too.
447 of the pointing device must be one of
449 constants or a positive value. The greater the value
450 is, the finer resolution the mouse will select.
451 Actual resolution selected by the
453 constant varies according to the model of mouse. Typical resolutions are:
455 .Bl -tag -width MOUSE_RES_MEDIUMHIGH__ -compact
458 .It Dv MOUSE_RES_MEDIUMLOW
460 .It Dv MOUSE_RES_MEDIUMHIGH
462 .It Dv MOUSE_RES_HIGH
468 field holds a value to control acceleration feature
469 .Pq see Sx Acceleration .
470 It must be zero or greater. If it is zero, acceleration is disabled.
474 field specifies the length of the data packet. It depends on the
475 operation level and the model of the pointing device.
477 .Bl -tag -width level_0__ -compact
483 Depends on the model of the device
488 holds a bit mask and pattern to detect the first byte of the
491 is the bit mask to be ANDed with a byte. If the result is equal to
493 the byte is likely to be the first byte of the data packet.
494 Note that this detection method is not 100% reliable,
495 thus, should be taken only as an advisory measure.
497 .It Dv MOUSE_SETMODE Ar mousemode_t *mode
498 The command changes the current operation parameters of the mouse driver
507 may be modifiable. Setting values in the other field does not generate
508 error and has no effect.
510 If you do not want to change the current setting of a field, put -1
512 You may also put zero in
516 and the default value for the fields will be selected.
518 .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
519 .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
520 .\" These commands are not supported by the
524 .It Dv MOUSE_READDATA Ar mousedata_t *data
525 .\" The command reads the raw data from the device.
527 .\" typedef struct mousedata {
528 .\" int len; /* # of data in the buffer */
529 .\" int buf[16]; /* data buffer */
533 .\" Upon returning to the user program, the driver will place the number
534 .\" of valid data bytes in the buffer in the
538 .It Dv MOUSE_READSTATE Ar mousedata_t *state
539 .\" The command reads the hardware settings from the device.
540 .\" Upon returning to the user program, the driver will place the number
541 .\" of valid data bytes in the buffer in the
543 .\" field. It is usually 3 bytes.
544 .\" The buffer is formatted as follows:
546 .\" .Bl -tag -width Byte_1 -compact
548 .\" .Bl -tag -width bit_6 -compact
552 .\" 0 - stream mode, 1 - remote mode.
553 .\" In the stream mode, the pointing device sends the device status
554 .\" whenever its state changes. In the remote mode, the host computer
555 .\" must request the status to be sent.
558 .\" driver puts the device in the stream mode.
560 .\" Set if the pointing device is currently enabled. Otherwise zero.
562 .\" 0 - 1:1 scaling, 1 - 2:1 scaling.
563 .\" 1:1 scaling is the default.
567 .\" Left button status; set if pressed.
569 .\" Middle button status; set if pressed.
571 .\" Right button status; set if pressed.
574 .\" .Bl -tag -width bit_6_0 -compact
578 .\" Resolution code: zero through three. Actual resolution for
579 .\" the resolution code varies from one device to another.
582 .\" The status report rate (reports/sec) at which the device will send
583 .\" movement report to the host computer.
585 These commands are not currently supported by the
589 .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status
590 The command returns the current state of buttons and
591 movement counts as described in
595 .Bl -tag -width /dev/npsm0 -compact
597 `non-blocking' device node
599 `blocking' device node under
603 .Dl "options" \&"PSM_HOOKAPM\&"
604 .Dl "device psm0 at atkbdc? irq 12"
608 driver to the kernel with the optional code to stimulate the pointing device
609 after the `resume' event.
611 .Dl "device psm0 at atkbdc? flags 0x024 irq 12"
613 Set the device resolution high (4) and the acceleration factor to 2.
616 At debug level 0, little information is logged except for the following
617 line during boot process:
618 .Bd -literal -offset indent
624 the device ID code returned by the found pointing device.
629 At debug level 1 more information will be logged
630 while the driver probes the auxiliary port (mouse port).
631 Messages are logged with the LOG_KERN facility at the LOG_DEBUG level
632 .Pq see Xr syslogd 8 .
633 .Bd -literal -offset indent
634 psm0: current command byte:xxxx
635 kbdio: TEST_AUX_PORT status:0000
636 kbdio: RESET_AUX return code:00fa
637 kbdio: RESET_AUX status:00aa
638 kbdio: RESET_AUX ID:0000
642 psm0: model AAAA, device ID X, N buttons
643 psm0: config:00000www, flags:0000uuuu, packet size:M
644 psm0: syncmask:xx, syncbits:yy
647 The first line shows the command byte value of the keyboard
648 controller just before the auxiliary port is probed.
649 It usually is 4D, 45, 47 or 65, depending on how the motherboard BIOS
650 initialized the keyboard controller upon power-up.
652 The second line shows the result of the keyboard controller's
653 test on the auxiliary port interface, with zero indicating
654 no error; note that some controllers report no error even if
655 the port does not exist in the system, however.
657 The third through fifth lines show the reset status of the pointing device.
658 The functioning device should return the sequence of FA AA <ID>.
659 The ID code is described above.
661 The seventh line shows the current hardware settings.
663 .\" .Dv MOUSE_READSTATE
665 These bytes are formatted as follows:
667 .Bl -tag -width Byte_1 -compact
669 .Bl -tag -width bit_6 -compact
673 0 - stream mode, 1 - remote mode.
674 In the stream mode, the pointing device sends the device status
675 whenever its state changes. In the remote mode, the host computer
676 must request the status to be sent.
679 driver puts the device in the stream mode.
681 Set if the pointing device is currently enabled. Otherwise zero.
683 0 - 1:1 scaling, 1 - 2:1 scaling.
684 1:1 scaling is the default.
688 Left button status; set if pressed.
690 Middle button status; set if pressed.
692 Right button status; set if pressed.
695 .Bl -tag -width bit_6_0 -compact
699 Resolution code: zero through three. Actual resolution for
700 the resolution code varies from one device to another.
703 The status report rate (reports/sec) at which the device will send
704 movement report to the host computer.
707 Note that the pointing device will not be enabled until the
709 driver is opened by the user program.
711 The rest of the lines show the device ID code, the number of detected
712 buttons and internal variables.
714 At debug level 2, much more detailed information is logged.
716 Many pad devices behave as if the first (left) button were pressed if
717 the user `taps' the surface of the pad.
718 In contrast, some pad products, e.g. some verions of ALPS GlidePoint
719 and Interlink VersaPad, treat the tapping action
720 as fourth button events.
722 It is reported that Interlink VersaPad rquires both
725 .Em PSM_RESETAFTERSUSPEND
726 options in order to recover from suspended state.
727 Add these options to your kernel configuration file if the device
728 does not seem to work properly after the system is resumed.
730 Some PS/2 mouse models from MouseSystems require to be put in the
731 high resolution mode to work properly. Use the driver flag to
734 There is not a guaranteed way to re-synchronize with the first byte
735 of the packet once we are out of synchronization with the data
736 stream. However, if you are using the \fIXFree86\fP server and experiencing
737 the problem, you may be able to make the X server synchronize with the mouse
738 by switching away to a virtual terminal and getting back to the X server,
739 unless the X server is accessing the mouse via
741 Clicking any button without moving the mouse may also work.
745 has been removed. It was never functional anyway.
759 driver is based on the work done by quite a number of people, including
770 This manual page was written by
771 .An Kazutaka Yokota Aq yokota@FreeBSD.org .