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.
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"
43 .Pa /boot/device.hints :
44 .Cd hint.psm.0.at="atkbdc"
45 .Cd hint.psm.0.irq="12"
49 driver provides support for the PS/2 mouse style pointing device.
50 Currently there can be only one
52 device node in the system.
53 As the PS/2 mouse port is located
54 at the auxiliary port of the keyboard controller,
55 the keyboard controller driver,
57 must also be configured in the kernel.
58 Note that there is currently no provision of changing the
62 Basic PS/2 style pointing device has two or three buttons.
63 Some devices may have a roller or a wheel and/or additional buttons.
65 The PS/2 style pointing device usually has several grades of resolution,
66 that is, sensitivity of movement.
67 They are typically 25, 50, 100 and 200
69 Some devices may have finer resolution.
70 The current resolution can be changed at runtime.
73 driver allows the user to initially set the resolution
76 .Sx "DRIVER CONFIGURATION" )
77 or change it later via the
84 Frequency, or report rate, at which the device sends movement
85 and button state reports to the host system is also configurable.
86 The PS/2 style pointing device typically supports 10, 20, 40, 60, 80, 100
87 and 200 reports per second.
88 60 or 100 appears to be the default value for many devices.
89 Note that when there is no movement and no button has changed its state,
90 the device will not send anything to the host system.
91 The report rate can be changed via an ioctl call.
95 driver has three levels of operation.
96 The current operation level can be set via an ioctl call.
98 At the level zero the basic support is provided; the device driver will report
99 horizontal and vertical movement of the attached device
100 and state of up to three buttons.
101 The movement and status are encoded in a series of fixed-length data packets
103 .Sx "Data Packet Format" ) .
104 This is the default level of operation and the driver is initially
105 at this level when opened by the user program.
107 The operation level one, the `extended' level, supports a roller (or wheel),
108 if any, and up to 11 buttons.
109 The movement of the roller is reported as movement along the Z axis.
110 8 byte data packets are sent to the user program at this level.
112 At the operation level two, data from the pointing device is passed to the
113 user program as is. Conversely, command from the user program is passed
114 to the pointing device as is and the user program is responsible for
115 status validation and error recovery.
116 Modern PS/2 type pointing devices often use proprietary data format.
117 Therefore, the user program is expected to have
118 intimate knowledge about the format from a particular device when operating
119 the driver at this level.
120 This level is called `native' level.
121 .Ss Data Packet Format
122 Data packets read from the
124 driver are formatted differently at each operation level.
126 A data packet from the PS/2 mouse style pointing device
127 is three bytes long at the operation level zero:
129 .Bl -tag -width Byte_1 -compact
131 .Bl -tag -width bit_7 -compact
133 One indicates overflow in the vertical movement count.
135 One indicates overflow in the horizontal movement count.
137 Set if the vertical movement count is negative.
139 Set if the horizontal movement count is negative.
142 .\" The ALPS GlidePoint clears this bit when the user `taps' the surface of
143 .\" the pad, otherwise the bit is set.
144 .\" Most, if not all, other devices always set this bit.
146 Middle button status; set if pressed.
147 For devices without the middle
148 button, this bit is always zero.
150 Right button status; set if pressed.
152 Left button status; set if pressed.
155 Horizontal movement count in two's complement;
157 Note that the sign bit is in the first byte.
159 Vertical movement count in two's complement;
161 Note that the sign bit is in the first byte.
164 At the level one, a data packet is encoded
165 in the standard format
166 .Dv MOUSE_PROTO_SYSMOUSE
170 At the level two, native level, there is no standard on the size and format
175 driver can somewhat `accelerate' the movement of the pointing device.
176 The faster you move the device, the further the pointer
177 travels on the screen.
178 The driver has an internal variable which governs the effect of
180 Its value can be modified via the driver flag
181 or via an ioctl call.
182 .Sh DRIVER CONFIGURATION
183 .Ss Kernel Configuration Options
184 There are following kernel configuration options to control the
187 They may be set in the kernel configuration file
190 .Bl -tag -width MOUSE
191 .It Em KBD_RESETDELAY=X , KBD_MAXWAIT=Y
194 driver will attempt to reset the pointing device during the boot process.
195 It sometimes takes a long while before the device will respond after
197 These options control how long the driver should wait before
198 it eventually gives up waiting.
204 If the driver seems unable to detect your pointing
205 device, you may want to increase these values.
206 The default values are
212 .It Em PSM_DEBUG=N , KBDIO_DEBUG=N
213 Sets the debug level to
215 The default debug level is zero.
223 driver accepts the following driver flags.
225 .Pa /boot/device.hints
229 .Bl -tag -width MOUSE
230 .It bit 0..3 RESOLUTION
231 This flag specifies the resolution of the pointing device.
232 It must be zero through four.
233 The greater the value
234 is, the finer resolution the device will select.
235 Actual resolution selected by this field varies according to the model
237 Typical resolutions are:
239 .Bl -tag -width 0_(medium_high)__ -compact
241 25 pulse per inch (ppi)
242 .It Em 2 (medium low)
244 .It Em 3 (medium high)
250 Leaving this flag zero will selects the default resolution for the
251 device (whatever it is).
252 .It bit 4..7 ACCELERATION
253 This flag controls the amount of acceleration effect.
254 The smaller the value of this flag is, more sensitive the movement becomes.
255 The minimum value allowed, thus the value for the most sensitive setting,
257 Setting this flag to zero will completely disables the
259 .It bit 8 NOCHECKSYNC
262 driver tries to detect the first byte of the data packet by checking
263 the bit pattern of that byte.
264 Although this method should work with most
265 PS/2 pointing devices, it may interfere with some devices which are not
266 so compatible with known devices.
267 If you think your pointing device is not functioning as expected,
268 and the kernel frequently prints the following message to the console,
269 .Bd -literal -offset indent
270 psmintr: out of sync (xxxx != yyyy).
273 set this flag to disable synchronization check and see if it helps.
277 driver will not try to identify the model of the pointing device and
278 will not carry out model-specific initialization.
279 The device should always act like a standard PS/2 mouse without such
281 Extra features, such as wheels and additional buttons, will not be
286 When this flag is set, the
288 driver will not reset the pointing device when initializing the device.
292 is started after another OS has run, the pointing device will inherit
293 settings from the previous OS.
294 However, because there is no way for the
296 driver to know the settings, the device and the driver may not
298 The flag should never be necessary under normal circumstances.
300 Some pad devices report as if the fourth button is pressed
301 when the user `taps' the surface of the device (see
303 This flag will make the
305 driver assume that the device behaves this way.
306 Without the flag, the driver will assume this behavior
307 for ALPS GlidePoint models only.
308 .It bit 12 IGNOREPORTERROR
311 driver ignore certain error conditions when probing the PS/2 mouse port.
312 It should never be necessary under normal circumstances.
313 .It bit 13 HOOKRESUME
314 The built-in PS/2 pointing device of some laptop computers is somehow
315 not operable immediately after the system `resumes' from
316 the power saving mode,
317 though it will eventually become available.
318 There are reports that
319 stimulating the device by performing I/O will help
320 waking up the device quickly.
321 This flag will enable a piece of code in the
324 the `resume' event and exercise some harmless I/O operations on the
326 .It bit 14 INITAFTERSUSPEND
327 This flag adds more drastic action for the above problem.
330 driver to reset and re-initialize the pointing device
331 after the `resume' event.
334 Extended support for Synaptics touchpads can be enabled by setting
335 .Va hw.psm.synaptics_support
341 to handle packets from guest devices (sticks) and extra buttons.
342 Similarly, extended support for IBM/Lenovo TrackPoint can be enabled
344 .Va hw.psm.trackpoint_support
349 Tap and drag gestures can be disabled by setting
350 .Va hw.psm.tap_enabled
354 Currently, this is only supported on Synaptics touchpads with Extended
355 support disabled. The behaviour may be changed after boot by setting
356 the sysctl with the same name and by restarting
359 .Pa /etc/rc.d/moused .
363 commands for mouse drivers.
364 These commands and related structures and constants are defined in
366 General description of the commands is given in
368 This section explains the features specific to the
372 .Bl -tag -width MOUSE -compact
373 .It Dv MOUSE_GETLEVEL Ar int *level
374 .It Dv MOUSE_SETLEVEL Ar int *level
375 These commands manipulate the operation level of the
379 .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
380 Returns the hardware information of the attached device in the following
383 typedef struct mousehw {
384 int buttons; /* number of buttons */
385 int iftype; /* I/F type */
386 int type; /* mouse/track ball/pad... */
387 int model; /* I/F dependent model ID */
388 int hwid; /* I/F dependent hardware ID */
394 field holds the number of buttons on the device.
397 driver currently can detect the 3 button mouse from Logitech and report
399 The 3 button mouse from the other manufacturer may or may not be
401 However, it will not affect the operation of
411 tells the device type:
413 .Dv MOUSE_TRACKBALL ,
418 The user should not heavily rely on this field, as the
419 driver may not always, in fact it is very rarely able to, identify
425 .Dv MOUSE_MODEL_GENERIC
426 at the operation level 0.
428 .Dv MOUSE_MODEL_GENERIC
431 constants at higher operation levels.
434 driver may or may not set an appropriate value in this field.
438 is the ID value returned by the device.
441 .Bl -tag -width 0__ -compact
443 Mouse (Microsoft, Logitech and many other manufacturers)
445 Microsoft Ballpoint mouse
447 Microsoft IntelliMouse
450 .It Dv MOUSE_SYN_GETHWINFO Ar synapticshw_t *synhw
451 Retrieves extra information associated with Synaptics Touchpad.
452 Only available when a supported device has been detected.
454 typedef struct synapticshw {
455 int infoMajor; /* major hardware revision */
456 int infoMinor; /* minor hardware revision */
457 int infoRot180; /* touchpad is rotated */
458 int infoPortrait; /* touchpad is a portrait */
459 int infoSensor; /* sensor model */
460 int infoHardware; /* hardware model */
461 int infoNewAbs; /* supports the newabs format */
462 int capPen; /* can detect a pen */
463 int infoSimplC; /* supports simple commands */
464 int infoGeometry; /* touchpad dimensions */
465 int capExtended; /* supports extended packets */
466 int capSleep; /* can be suspended/resumed */
467 int capFourButtons; /* has four buttons */
468 int capMultiFinger; /* can detect multiple fingers */
469 int capPalmDetect; /* can detect a palm */
470 int capPassthrough; /* can passthrough guest packets */
471 int capMiddle; /* has a physical middle button */
472 int nExtendedButtons; /* has N additionnal buttons */
473 int nExtendedQueries; /* supports N extended queries */
478 .Em Synaptics TouchPad Interfacing Guide
479 for more information about the fields in this structure.
481 .It Dv MOUSE_GETMODE Ar mousemode_t *mode
482 The command gets the current operation parameters of the mouse
485 typedef struct mousemode {
486 int protocol; /* MOUSE_PROTO_XXX */
487 int rate; /* report rate (per sec), -1 if unknown */
488 int resolution; /* MOUSE_RES_XXX, -1 if unknown */
489 int accelfactor; /* acceleration factor */
490 int level; /* driver operation level */
491 int packetsize; /* the length of the data packet */
492 unsigned char syncmask[2]; /* sync. bits */
500 at the operation level zero and two.
501 .Dv MOUSE_PROTO_SYSMOUSE
502 at the operation level one.
506 is the status report rate (reports/sec) at which the device will send
507 movement report to the host computer.
508 Typical supported values are 10, 20, 40, 60, 80, 100 and 200.
509 Some mice may accept other arbitrary values too.
513 of the pointing device must be one of
515 constants or a positive value.
516 The greater the value
517 is, the finer resolution the mouse will select.
518 Actual resolution selected by the
520 constant varies according to the model of mouse.
521 Typical resolutions are:
523 .Bl -tag -width MOUSE_RES_MEDIUMHIGH__ -compact
526 .It Dv MOUSE_RES_MEDIUMLOW
528 .It Dv MOUSE_RES_MEDIUMHIGH
530 .It Dv MOUSE_RES_HIGH
536 field holds a value to control acceleration feature
539 It must be zero or greater.
540 If it is zero, acceleration is disabled.
544 field specifies the length of the data packet.
546 operation level and the model of the pointing device.
548 .Bl -tag -width level_0__ -compact
554 Depends on the model of the device
559 holds a bit mask and pattern to detect the first byte of the
562 is the bit mask to be ANDed with a byte.
563 If the result is equal to
565 the byte is likely to be the first byte of the data packet.
566 Note that this detection method is not 100% reliable,
567 thus, should be taken only as an advisory measure.
569 .It Dv MOUSE_SETMODE Ar mousemode_t *mode
570 The command changes the current operation parameters of the mouse driver
580 Setting values in the other field does not generate
581 error and has no effect.
583 If you do not want to change the current setting of a field, put -1
585 You may also put zero in
589 and the default value for the fields will be selected.
591 .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
592 .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
593 .\" These commands are not supported by the
597 .It Dv MOUSE_READDATA Ar mousedata_t *data
598 .\" The command reads the raw data from the device.
600 .\" typedef struct mousedata {
601 .\" int len; /* # of data in the buffer */
602 .\" int buf[16]; /* data buffer */
606 .\" Upon returning to the user program, the driver will place the number
607 .\" of valid data bytes in the buffer in the
611 .It Dv MOUSE_READSTATE Ar mousedata_t *state
612 .\" The command reads the hardware settings from the device.
613 .\" Upon returning to the user program, the driver will place the number
614 .\" of valid data bytes in the buffer in the
616 .\" field. It is usually 3 bytes.
617 .\" The buffer is formatted as follows:
619 .\" .Bl -tag -width Byte_1 -compact
621 .\" .Bl -tag -width bit_6 -compact
625 .\" 0 - stream mode, 1 - remote mode.
626 .\" In the stream mode, the pointing device sends the device status
627 .\" whenever its state changes. In the remote mode, the host computer
628 .\" must request the status to be sent.
631 .\" driver puts the device in the stream mode.
633 .\" Set if the pointing device is currently enabled. Otherwise zero.
635 .\" 0 - 1:1 scaling, 1 - 2:1 scaling.
636 .\" 1:1 scaling is the default.
640 .\" Left button status; set if pressed.
642 .\" Middle button status; set if pressed.
644 .\" Right button status; set if pressed.
647 .\" .Bl -tag -width bit_6_0 -compact
651 .\" Resolution code: zero through three. Actual resolution for
652 .\" the resolution code varies from one device to another.
655 .\" The status report rate (reports/sec) at which the device will send
656 .\" movement report to the host computer.
658 These commands are not currently supported by the
662 .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status
663 The command returns the current state of buttons and
664 movement counts as described in
668 .Bl -tag -width /dev/npsm0 -compact
670 `non-blocking' device node
672 `blocking' device node
675 In order to install the
677 driver, you need to add
682 to your kernel configuration file, and put the following lines to
683 .Pa /boot/device.hints .
685 .Dl hint.atkbdc.0.at="isa"
686 .Dl hint.atkbdc.0.port="0x060"
687 .Dl hint.psm.0.at="atkbdc"
688 .Dl hint.psm.0.irq="12"
690 If you add the following statement to
691 .Pa /boot/device.hints ,
693 .Dl hint.psm.0.flags="0x2000"
695 you will add the optional code to stimulate the pointing device
696 after the `resume' event.
698 .Dl hint.psm.0.flags="0x24"
700 The above line will set the device resolution high (4)
701 and the acceleration factor to 2.
703 At debug level 0, little information is logged except for the following
704 line during boot process:
705 .Bd -literal -offset indent
711 the device ID code returned by the found pointing device.
716 At debug level 1 more information will be logged
717 while the driver probes the auxiliary port (mouse port).
718 Messages are logged with the LOG_KERN facility at the LOG_DEBUG level
721 .Bd -literal -offset indent
722 psm0: current command byte:xxxx
723 kbdio: TEST_AUX_PORT status:0000
724 kbdio: RESET_AUX return code:00fa
725 kbdio: RESET_AUX status:00aa
726 kbdio: RESET_AUX ID:0000
730 psm0: model AAAA, device ID X, N buttons
731 psm0: config:00000www, flags:0000uuuu, packet size:M
732 psm0: syncmask:xx, syncbits:yy
735 The first line shows the command byte value of the keyboard
736 controller just before the auxiliary port is probed.
737 It usually is 40, 45, 47 or 65, depending on how the motherboard BIOS
738 initialized the keyboard controller upon power-up.
740 The second line shows the result of the keyboard controller's
741 test on the auxiliary port interface, with zero indicating
742 no error; note that some controllers report no error even if
743 the port does not exist in the system, however.
745 The third through fifth lines show the reset status of the pointing device.
746 The functioning device should return the sequence of FA AA <ID>.
747 The ID code is described above.
749 The seventh line shows the current hardware settings.
751 .\" .Dv MOUSE_READSTATE
753 These bytes are formatted as follows:
755 .Bl -tag -width Byte_1 -compact
757 .Bl -tag -width bit_6 -compact
761 0 - stream mode, 1 - remote mode.
762 In the stream mode, the pointing device sends the device status
763 whenever its state changes.
764 In the remote mode, the host computer
765 must request the status to be sent.
768 driver puts the device in the stream mode.
770 Set if the pointing device is currently enabled.
773 0 - 1:1 scaling, 1 - 2:1 scaling.
774 1:1 scaling is the default.
778 Left button status; set if pressed.
780 Middle button status; set if pressed.
782 Right button status; set if pressed.
785 .Bl -tag -width bit_6_0 -compact
789 Resolution code: zero through three.
790 Actual resolution for
791 the resolution code varies from one device to another.
794 The status report rate (reports/sec) at which the device will send
795 movement report to the host computer.
798 Note that the pointing device will not be enabled until the
800 driver is opened by the user program.
802 The rest of the lines show the device ID code, the number of detected
803 buttons and internal variables.
805 At debug level 2, much more detailed information is logged.
816 .%T Synaptics TouchPad Interfacing Guide
817 .%U http://www.synaptics.com/
824 driver is based on the work done by quite a number of people, including
835 This manual page was written by
836 .An Kazutaka Yokota Aq yokota@FreeBSD.org .
838 Many pad devices behave as if the first (left) button were pressed if
839 the user `taps' the surface of the pad.
840 In contrast, some pad products, e.g.\& some versions of ALPS GlidePoint
841 and Interlink VersaPad, treat the tapping action
842 as fourth button events.
844 It is reported that ALPS GlidePoint, Synaptics Touchpad, IBM/Lenovo
845 TrackPoint, and Interlink VersaPad require
847 flag in order to recover from suspended state.
848 This flag is automatically set when one of these devices is detected by the
852 Some PS/2 mouse models from MouseSystems require to be put in the
853 high resolution mode to work properly.
854 Use the driver flag to
857 There is not a guaranteed way to re-synchronize with the first byte
858 of the packet once we are out of synchronization with the data
860 However, if you are using the \fIXFree86\fP server and experiencing
861 the problem, you may be able to make the X server synchronize with the mouse
862 by switching away to a virtual terminal and getting back to the X server,
863 unless the X server is accessing the mouse via
865 Clicking any button without moving the mouse may also work.
870 It was never functional anyway.
872 Enabling the extended support for Synaptics touchpads has been reported to
873 cause problems with responsivity on some (newer) models of Synaptics
874 hardware, particularly those with guest devices.