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.
27 .\" $FreeBSD: src/share/man/man4/psm.4,v 1.24.2.9 2002/12/29 16:35:38 schweikh Exp $
34 .Nd PS/2 mouse style pointing device driver
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"
44 driver provides support for the PS/2 mouse style pointing device.
45 Currently there can be only one
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,
52 must also be configured in the kernel.
53 Note that there is currently no provision of changing the
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.
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
64 Some devices may have finer resolution.
65 The current resolution can be changed at runtime.
68 driver allows the user to initially set the resolution
71 .Sx "DRIVER CONFIGURATION" )
72 or change it later via the
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.
90 driver has three levels of operation.
91 The current operation level can be set via an ioctl call.
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
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.
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.
107 At the operation level two, data from the pointing device is passed to the
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
117 driver are formatted differently at each operation level.
119 A data packet from the PS/2 mouse style pointing device
120 is three bytes long at the operation level zero:
122 .Bl -tag -width Byte_1 -compact
124 .Bl -tag -width bit_7 -compact
126 One indicates overflow in the vertical movement count.
128 One indicates overflow in the horizontal movement count.
130 Set if the vertical movement count is negative.
132 Set if the horizontal movement count is negative.
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.
139 Middle button status; set if pressed.
140 For devices without the middle
141 button, this bit is always zero.
143 Right button status; set if pressed.
145 Left button status; set if pressed.
148 Horizontal movement count in two's complement;
150 Note that the sign bit is in the first byte.
152 Vertical movement count in two's complement;
154 Note that the sign bit is in the first byte.
157 At the level one, a data packet is encoded
158 in the standard format
159 .Dv MOUSE_PROTO_SYSMOUSE
163 At the level two, native level, there is no standard on the size and format
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
173 Its value can be modified via the driver flag
174 or via an ioctl call.
175 .Sh DRIVER CONFIGURATION
176 .Ss Kernel Configuration Options
177 There are following kernel configuration options to control the
180 They may be set in the kernel configuration file
183 .Bl -tag -width MOUSE
184 .It Em KBD_RESETDELAY=X , KBD_MAXWAIT=Y
187 driver will attempt to reset the pointing device during the boot process.
188 It sometimes takes a long while before the device will respond after
190 These options control how long the driver should wait before
191 it eventually gives up waiting.
197 If the driver seems unable to detect your pointing
198 device, you may want to increase these values.
199 The default values are
205 .It Em PSM_DEBUG=N , KBDIO_DEBUG=N
206 Sets the debug level to
208 The default debug level is zero.
216 driver accepts the following driver flags.
218 kernel configuration file or in the User Configuration Menu at
222 .Bl -tag -width MOUSE
223 .It bit 0..3 RESOLUTION
224 This flag specifies the resolution of the pointing device.
225 It must be zero through four.
226 The greater the value
227 is, the finer resolution the device will select.
228 Actual resolution selected by this field varies according to the model
230 Typical resolutions are:
232 .Bl -tag -width 0_(medium_high)__ -compact
234 25 pulse per inch (ppi)
235 .It Em 2 (medium low)
237 .It Em 3 (medium high)
243 Leaving this flag zero will selects the default resolution for the
244 device (whatever it is).
245 .It bit 4..7 ACCELERATION
246 This flag controls the amount of acceleration effect.
247 The smaller the value of this flag is, more sensitive the movement becomes.
248 The minimum value allowed, thus the value for the most sensitive setting,
250 Setting this flag to zero will completely disables the
252 .It bit 8 NOCHECKSYNC
255 driver tries to detect the first byte of the data packet by checking
256 the bit pattern of that byte.
257 Although this method should work with most
258 PS/2 pointing devices, it may interfere with some devices which are not
259 so compatible with known devices.
260 If you think your pointing device is not functioning as expected,
261 and the kernel frequently prints the following message to the console,
262 .Bd -literal -offset indent
263 psmintr: out of sync (xxxx != yyyy).
266 set this flag to disable synchronization check and see if it helps.
270 driver will not try to identify the model of the pointing device and
271 will not carry out model-specific initialization.
272 The device should always act like a standard PS/2 mouse without such
274 Extra features, such as wheels and additional buttons, won't be
279 When this flag is set, the
281 driver won't reset the pointing device when initializing the device.
285 is started after another OS has run, the pointing device will inherit
286 settings from the previous OS.
287 However, because there is no way for the
289 driver to know the settings, the device and the driver may not
291 The flag should never be necessary under normal circumstances.
293 Some pad devices report as if the fourth button is pressed
294 when the user `taps' the surface of the device (see
296 This flag will make the
298 driver assume that the device behaves this way.
299 Without the flag, the driver will assume this behavior
300 for ALPS GlidePoint models only.
301 .It bit 12 IGNOREPORTERROR
304 driver ignore certain error conditions when probing the PS/2 mouse port.
305 It should never be necessary under normal circumstances.
306 .It bit 13 HOOKRESUME
307 The built-in PS/2 pointing device of some laptop computers is somehow
308 not operable immediately after the system `resumes' from
309 the power saving mode,
310 though it will eventually become available.
311 There are reports that
312 stimulating the device by performing I/O will help
313 waking up the device quickly.
314 This flag will enable a piece of code in the
317 the `resume' event and exercise some harmless I/O operations on the
319 .It bit 14 INITAFTERSUSPEND
320 This flag adds more drastic action for the above problem.
323 driver to reset and re-initialize the pointing device
324 after the `resume' event.
325 It has no effect unless the
330 Extended support for Synaptics touchpads can be enabled by setting
331 .Va hw.psm.synaptics_support
337 to handle packets from guest devices (sticks) and extra buttons.
339 Tap and drag gestures can be disabled by setting
340 .Va hw.psm.tap_enabled
344 Currently, this is only supported on Synaptics touchpads with Extended
345 support disabled. The behaviour may be changed after boot by setting
346 the sysctl with the same name and by restarting
349 .Pa /etc/rc.d/moused .
353 commands for mouse drivers.
354 These commands and related structures and constants are defined in
356 General description of the commands is given in
358 This section explains the features specific to the
362 .Bl -tag -width MOUSE -compact
363 .It Dv MOUSE_GETLEVEL Ar int *level
364 .It Dv MOUSE_SETLEVEL Ar int *level
365 These commands manipulate the operation level of the
369 .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
370 Returns the hardware information of the attached device in the following
373 typedef struct mousehw {
374 int buttons; /* number of buttons */
375 int iftype; /* I/F type */
376 int type; /* mouse/track ball/pad... */
377 int model; /* I/F dependent model ID */
378 int hwid; /* I/F dependent hardware ID */
384 field holds the number of buttons on the device.
387 driver currently can detect the 3 button mouse from Logitech and report
389 The 3 button mouse from the other manufacturer may or may not be
391 However, it will not affect the operation of
401 tells the device type:
403 .Dv MOUSE_TRACKBALL ,
408 The user should not heavily rely on this field, as the
409 driver may not always, in fact it is very rarely able to, identify
415 .Dv MOUSE_MODEL_GENERIC
416 at the operation level 0.
418 .Dv MOUSE_MODEL_GENERIC
421 constants at higher operation levels.
424 driver may or may not set an appropriate value in this field.
428 is the ID value returned by the device.
431 .Bl -tag -width 0__ -compact
433 Mouse (Microsoft, Logitech and many other manufacturers)
435 Microsoft Ballpoint mouse
437 Microsoft IntelliMouse
440 .It Dv MOUSE_SYN_GETHWINFO Ar synapticshw_t *synhw
441 Retrieves extra information associated with Synaptics Touchpads.
443 .Va hw.psm.synaptics_support
446 typedef struct synapticshw {
447 int infoMajor; /* major hardware revision */
448 int infoMinor; /* minor hardware revision */
449 int infoRot180; /* touchpad is rotated */
450 int infoPortrait; /* touchpad is a portrait */
451 int infoSensor; /* sensor model */
452 int infoHardware; /* hardware model */
453 int infoNewAbs; /* supports the newabs format */
454 int capPen; /* can detect a pen */
455 int infoSimpleC; /* supports simple commands */
456 int infoGeometry; /* touchpad dimensions */
457 int capExtended; /* supports extended packets */
458 int capSleep; /* can be suspended/resumed */
459 int capFourButtons; /* has four buttons */
460 int capMultiFinger; /* can detect multiple fingers */
461 int capPalmDetect; /* can detect a palm */
462 int capPassthrough; /* can passthrough guest packets */
467 .Em Synaptics TouchPad Interfacing Guide
468 for more information about the fields in this structure.
470 .It Dv MOUSE_GETMODE Ar mousemode_t *mode
471 The command gets the current operation parameters of the mouse
474 typedef struct mousemode {
475 int protocol; /* MOUSE_PROTO_XXX */
476 int rate; /* report rate (per sec), -1 if unknown */
477 int resolution; /* MOUSE_RES_XXX, -1 if unknown */
478 int accelfactor; /* acceleration factor */
479 int level; /* driver operation level */
480 int packetsize; /* the length of the data packet */
481 unsigned char syncmask[2]; /* sync. bits */
489 at the operation level zero and two.
490 .Dv MOUSE_PROTO_SYSMOUSE
491 at the operation level one.
495 is the status report rate (reports/sec) at which the device will send
496 movement report to the host computer.
497 Typical supported values are 10, 20, 40, 60, 80, 100 and 200.
498 Some mice may accept other arbitrary values too.
502 of the pointing device must be one of
504 constants or a positive value.
505 The greater the value
506 is, the finer resolution the mouse will select.
507 Actual resolution selected by the
509 constant varies according to the model of mouse.
510 Typical resolutions are:
512 .Bl -tag -width MOUSE_RES_MEDIUMHIGH__ -compact
515 .It Dv MOUSE_RES_MEDIUMLOW
517 .It Dv MOUSE_RES_MEDIUMHIGH
519 .It Dv MOUSE_RES_HIGH
525 field holds a value to control acceleration feature
528 It must be zero or greater. If it is zero, acceleration is disabled.
532 field specifies the length of the data packet.
534 operation level and the model of the pointing device.
536 .Bl -tag -width level_0__ -compact
542 Depends on the model of the device
547 holds a bit mask and pattern to detect the first byte of the
550 is the bit mask to be ANDed with a byte.
551 If the result is equal to
552 .Fa syncmask Ns Bq 1 ,
553 the byte is likely to be the first byte of the data packet.
554 Note that this detection method is not 100% reliable,
555 thus, should be taken only as an advisory measure.
557 .It Dv MOUSE_SETMODE Ar mousemode_t *mode
558 The command changes the current operation parameters of the mouse driver
568 Setting values in the other field does not generate
569 error and has no effect.
571 If you do not want to change the current setting of a field, put -1
573 You may also put zero in
577 and the default value for the fields will be selected.
579 .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
580 .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
581 .\" These commands are not supported by the
585 .It Dv MOUSE_READDATA Ar mousedata_t *data
586 .\" The command reads the raw data from the device.
588 .\" typedef struct mousedata {
589 .\" int len; /* # of data in the buffer */
590 .\" int buf[16]; /* data buffer */
594 .\" Upon returning to the user program, the driver will place the number
595 .\" of valid data bytes in the buffer in the
599 .It Dv MOUSE_READSTATE Ar mousedata_t *state
600 .\" The command reads the hardware settings from the device.
601 .\" Upon returning to the user program, the driver will place the number
602 .\" of valid data bytes in the buffer in the
604 .\" field. It is usually 3 bytes.
605 .\" The buffer is formatted as follows:
607 .\" .Bl -tag -width Byte_1 -compact
609 .\" .Bl -tag -width bit_6 -compact
613 .\" 0 - stream mode, 1 - remote mode.
614 .\" In the stream mode, the pointing device sends the device status
615 .\" whenever its state changes. In the remote mode, the host computer
616 .\" must request the status to be sent.
619 .\" driver puts the device in the stream mode.
621 .\" Set if the pointing device is currently enabled. Otherwise zero.
623 .\" 0 - 1:1 scaling, 1 - 2:1 scaling.
624 .\" 1:1 scaling is the default.
628 .\" Left button status; set if pressed.
630 .\" Middle button status; set if pressed.
632 .\" Right button status; set if pressed.
635 .\" .Bl -tag -width bit_6_0 -compact
639 .\" Resolution code: zero through three. Actual resolution for
640 .\" the resolution code varies from one device to another.
643 .\" The status report rate (reports/sec) at which the device will send
644 .\" movement report to the host computer.
646 These commands are not currently supported by the
650 .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status
651 The command returns the current state of buttons and
652 movement counts as described in
656 .Bl -tag -width /dev/npsm0 -compact
661 .Dl "device psm0 at atkbdc? irq 12 flags 0x2000"
665 driver to the kernel with the optional code to stimulate the pointing device
666 after the `resume' event.
668 .Dl "device psm0 at atkbdc? flags 0x024 irq 12"
670 Set the device resolution high (4) and the acceleration factor to 2.
672 At debug level 0, little information is logged except for the following
673 line during boot process:
674 .Bd -literal -offset indent
680 the device ID code returned by the found pointing device.
685 At debug level 1 more information will be logged
686 while the driver probes the auxiliary port (mouse port).
687 Messages are logged with the LOG_KERN facility at the LOG_DEBUG level
690 .Bd -literal -offset indent
691 psm0: current command byte:xxxx
692 kbdio: TEST_AUX_PORT status:0000
693 kbdio: RESET_AUX return code:00fa
694 kbdio: RESET_AUX status:00aa
695 kbdio: RESET_AUX ID:0000
699 psm0: model AAAA, device ID X, N buttons
700 psm0: config:00000www, flags:0000uuuu, packet size:M
701 psm0: syncmask:xx, syncbits:yy
704 The first line shows the command byte value of the keyboard
705 controller just before the auxiliary port is probed.
706 It usually is 4D, 45, 47 or 65, depending on how the motherboard BIOS
707 initialized the keyboard controller upon power-up.
709 The second line shows the result of the keyboard controller's
710 test on the auxiliary port interface, with zero indicating
711 no error; note that some controllers report no error even if
712 the port does not exist in the system, however.
714 The third through fifth lines show the reset status of the pointing device.
715 The functioning device should return the sequence of FA AA <ID>.
716 The ID code is described above.
718 The seventh line shows the current hardware settings.
720 .\" .Dv MOUSE_READSTATE
722 These bytes are formatted as follows:
724 .Bl -tag -width Byte_1 -compact
726 .Bl -tag -width bit_6 -compact
730 0 - stream mode, 1 - remote mode.
731 In the stream mode, the pointing device sends the device status
732 whenever its state changes.
733 In the remote mode, the host computer
734 must request the status to be sent.
737 driver puts the device in the stream mode.
739 Set if the pointing device is currently enabled.
742 0 - 1:1 scaling, 1 - 2:1 scaling.
743 1:1 scaling is the default.
747 Left button status; set if pressed.
749 Middle button status; set if pressed.
751 Right button status; set if pressed.
754 .Bl -tag -width bit_6_0 -compact
758 Resolution code: zero through three.
759 Actual resolution for
760 the resolution code varies from one device to another.
763 The status report rate (reports/sec) at which the device will send
764 movement report to the host computer.
767 Note that the pointing device will not be enabled until the
769 driver is opened by the user program.
771 The rest of the lines show the device ID code, the number of detected
772 buttons and internal variables.
774 At debug level 2, much more detailed information is logged.
776 Many pad devices behave as if the first (left) button were pressed if
777 the user `taps' the surface of the pad.
778 In contrast, some pad products, e.g. some versions of ALPS GlidePoint
779 and Interlink VersaPad, treat the tapping action
780 as fourth button events.
782 It is reported that Interlink VersaPad requires both
786 flags in order to recover from suspended state.
787 These flags are automatically set when VersaPad is detected by the
791 Some PS/2 mouse models from MouseSystems require to be put in the
792 high resolution mode to work properly.
793 Use the driver flag to
796 There is not a guaranteed way to re-synchronize with the first byte
797 of the packet once we are out of synchronization with the data
799 However, if you are using the \fIXFree86\fP server and experiencing
800 the problem, you may be able to make the X server synchronize with the mouse
801 by switching away to a virtual terminal and getting back to the X server,
802 unless the X server is accessing the mouse via
804 Clicking any button without moving the mouse may also work.
814 .%T Synaptics TouchPad Interfacing Guide
815 .%O http://www.synaptics.com/
821 driver is based on the work done by quite a number of people, including
832 This manual page was written by
833 .An Kazutaka Yokota Aq Mt yokota@FreeBSD.org .