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 won't 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
114 Modern PS/2 type pointing devices often use proprietary data format.
115 Therefore, the user program is expected to have
116 intimate knowledge about the format from a particular device when operating
117 the driver at this level.
118 This level is called `native' level.
119 .Ss Data Packet Format
120 Data packets read from the
122 driver are formatted differently at each operation level.
124 A data packet from the PS/2 mouse style pointing device
125 is three bytes long at the operation level zero:
127 .Bl -tag -width Byte_1 -compact
129 .Bl -tag -width bit_7 -compact
131 One indicates overflow in the vertical movement count.
133 One indicates overflow in the horizontal movement count.
135 Set if the vertical movement count is negative.
137 Set if the horizontal movement count is negative.
140 .\" The ALPS GlidePoint clears this bit when the user `taps' the surface of
141 .\" the pad, otherwise the bit is set.
142 .\" Most, if not all, other devices always set this bit.
144 Middle button status; set if pressed.
145 For devices without the middle
146 button, this bit is always zero.
148 Right button status; set if pressed.
150 Left button status; set if pressed.
153 Horizontal movement count in two's complement;
155 Note that the sign bit is in the first byte.
157 Vertical movement count in two's complement;
159 Note that the sign bit is in the first byte.
162 At the level one, a data packet is encoded
163 in the standard format
164 .Dv MOUSE_PROTO_SYSMOUSE
168 At the level two, native level, there is no standard on the size and format
173 driver can somewhat `accelerate' the movement of the pointing device.
174 The faster you move the device, the further the pointer
175 travels on the screen.
176 The driver has an internal variable which governs the effect of
178 Its value can be modified via the driver flag
179 or via an ioctl call.
181 The minor device number of the
184 .Bd -literal -offset indent
185 minor = (`unit' << 1) | `non-blocking'
188 where `unit' is the device number (usually 0) and the `non-blocking' bit
189 is set to indicate ``don't block waiting for mouse input,
190 return immediately''.
191 The `non-blocking' bit should be set for \fIXFree86\fP,
192 therefore the minor device number usually used for \fIXFree86\fP is 1.
195 for device node names.
196 .Sh DRIVER CONFIGURATION
197 .Ss Kernel Configuration Options
198 There are following kernel configuration options to control the
201 They may be set in the kernel configuration file
204 .Bl -tag -width MOUSE
205 .It Em KBD_RESETDELAY=X , KBD_MAXWAIT=Y
208 driver will attempt to reset the pointing device during the boot process.
209 It sometimes takes a long while before the device will respond after
211 These options control how long the driver should wait before
212 it eventually gives up waiting.
218 If the driver seems unable to detect your pointing
219 device, you may want to increase these values.
220 The default values are
226 .It Em PSM_DEBUG=N , KBDIO_DEBUG=N
227 Sets the debug level to
229 The default debug level is zero.
237 driver accepts the following driver flags.
239 .Pa /boot/device.hints
244 .Bl -tag -width MOUSE
245 .It bit 0..3 RESOLUTION
246 This flag specifies the resolution of the pointing device.
247 It must be zero through four.
248 The greater the value
249 is, the finer resolution the device will select.
250 Actual resolution selected by this field varies according to the model
252 Typical resolutions are:
254 .Bl -tag -width 0_(medium_high)__ -compact
256 25 pulse per inch (ppi)
257 .It Em 2 (medium low)
259 .It Em 3 (medium high)
265 Leaving this flag zero will selects the default resolution for the
266 device (whatever it is).
267 .It bit 4..7 ACCELERATION
268 This flag controls the amount of acceleration effect.
269 The smaller the value of this flag is, more sensitive the movement becomes.
270 The minimum value allowed, thus the value for the most sensitive setting,
272 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.
279 Although this method should work with most
280 PS/2 pointing devices, it may interfere with some devices which are not
281 so compatible with known devices.
282 If you think your pointing device is not functioning as expected,
283 and the kernel frequently prints the following message to the console,
284 .Bd -literal -offset indent
285 psmintr: out of sync (xxxx != yyyy).
288 set this flag to disable synchronization check and see if it helps.
292 driver will not try to identify the model of the pointing device and
293 will not carry out model-specific initialization.
294 The device should always act like a standard PS/2 mouse without such
296 Extra features, such as wheels and additional buttons, won't be
301 When this flag is set, the
303 driver won't reset the pointing device when initializing the device.
307 is started after another OS has run, the pointing device will inherit
308 settings from the previous OS.
309 However, because there is no way for the
311 driver to know the settings, the device and the driver may not
313 The flag should never be necessary under normal circumstances.
315 Some pad devices report as if the fourth button is pressed
316 when the user `taps' the surface of the device (see
318 This flag will make the
320 driver assume that the device behaves this way.
321 Without the flag, the driver will assume this behavior
322 for ALPS GlidePoint models only.
323 .It bit 12 IGNOREPORTERROR
326 driver ignore certain error conditions when probing the PS/2 mouse port.
327 It should never be necessary under normal circumstances.
328 .It bit 13 HOOKRESUME
329 The built-in PS/2 pointing device of some laptop computers is somehow
330 not operable immediately after the system `resumes' from
331 the power saving mode,
332 though it will eventually become available.
333 There are reports that
334 stimulating the device by performing I/O will help
335 waking up the device quickly.
336 This flag will enable a piece of code in the
339 the `resume' event and exercise some harmless I/O operations on the
341 .It bit 14 INITAFTERSUSPEND
342 This flag adds more drastic action for the above problem.
345 driver to reset and re-initialize the pointing device
346 after the `resume' event.
347 It has no effect unless the
354 commands for mouse drivers.
355 These commands and related structures and constants are defined in
357 General description of the commands is given in
359 This section explains the features specific to the
363 .Bl -tag -width MOUSE -compact
364 .It Dv MOUSE_GETLEVEL Ar int *level
365 .It Dv MOUSE_SETLEVEL Ar int *level
366 These commands manipulate the operation level of the
370 .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
371 Returns the hardware information of the attached device in the following
374 typedef struct mousehw {
375 int buttons; /* number of buttons */
376 int iftype; /* I/F type */
377 int type; /* mouse/track ball/pad... */
378 int model; /* I/F dependent model ID */
379 int hwid; /* I/F dependent hardware ID */
385 field holds the number of buttons on the device.
388 driver currently can detect the 3 button mouse from Logitech and report
390 The 3 button mouse from the other manufacturer may or may not be
392 However, it will not affect the operation of
402 tells the device type:
404 .Dv MOUSE_TRACKBALL ,
409 The user should not heavily rely on this field, as the
410 driver may not always, in fact it is very rarely able to, identify
416 .Dv MOUSE_MODEL_GENERIC
417 at the operation level 0.
419 .Dv MOUSE_MODEL_GENERIC
422 constants at higher operation levels.
425 driver may or may not set an appropriate value in this field.
429 is the ID value returned by the device.
432 .Bl -tag -width 0__ -compact
434 Mouse (Microsoft, Logitech and many other manufacturers)
436 Microsoft Ballpoint mouse
438 Microsoft IntelliMouse
441 .It Dv MOUSE_GETMODE Ar mousemode_t *mode
442 The command gets the current operation parameters of the mouse
445 typedef struct mousemode {
446 int protocol; /* MOUSE_PROTO_XXX */
447 int rate; /* report rate (per sec), -1 if unknown */
448 int resolution; /* MOUSE_RES_XXX, -1 if unknown */
449 int accelfactor; /* acceleration factor */
450 int level; /* driver operation level */
451 int packetsize; /* the length of the data packet */
452 unsigned char syncmask[2]; /* sync. bits */
460 at the operation level zero and two.
461 .Dv MOUSE_PROTO_SYSMOUSE
462 at the operation level one.
466 is the status report rate (reports/sec) at which the device will send
467 movement report to the host computer.
468 Typical supported values are 10, 20, 40, 60, 80, 100 and 200.
469 Some mice may accept other arbitrary values too.
473 of the pointing device must be one of
475 constants or a positive value.
476 The greater the value
477 is, the finer resolution the mouse will select.
478 Actual resolution selected by the
480 constant varies according to the model of mouse.
481 Typical resolutions are:
483 .Bl -tag -width MOUSE_RES_MEDIUMHIGH__ -compact
486 .It Dv MOUSE_RES_MEDIUMLOW
488 .It Dv MOUSE_RES_MEDIUMHIGH
490 .It Dv MOUSE_RES_HIGH
496 field holds a value to control acceleration feature
499 It must be zero or greater.
500 If it is zero, acceleration is disabled.
504 field specifies the length of the data packet.
506 operation level and the model of the pointing device.
508 .Bl -tag -width level_0__ -compact
514 Depends on the model of the device
519 holds a bit mask and pattern to detect the first byte of the
522 is the bit mask to be ANDed with a byte.
523 If the result is equal to
525 the byte is likely to be the first byte of the data packet.
526 Note that this detection method is not 100% reliable,
527 thus, should be taken only as an advisory measure.
529 .It Dv MOUSE_SETMODE Ar mousemode_t *mode
530 The command changes the current operation parameters of the mouse driver
540 Setting values in the other field does not generate
541 error and has no effect.
543 If you do not want to change the current setting of a field, put -1
545 You may also put zero in
549 and the default value for the fields will be selected.
551 .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
552 .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
553 .\" These commands are not supported by the
557 .It Dv MOUSE_READDATA Ar mousedata_t *data
558 .\" The command reads the raw data from the device.
560 .\" typedef struct mousedata {
561 .\" int len; /* # of data in the buffer */
562 .\" int buf[16]; /* data buffer */
566 .\" Upon returning to the user program, the driver will place the number
567 .\" of valid data bytes in the buffer in the
571 .It Dv MOUSE_READSTATE Ar mousedata_t *state
572 .\" The command reads the hardware settings from the device.
573 .\" Upon returning to the user program, the driver will place the number
574 .\" of valid data bytes in the buffer in the
576 .\" field. It is usually 3 bytes.
577 .\" The buffer is formatted as follows:
579 .\" .Bl -tag -width Byte_1 -compact
581 .\" .Bl -tag -width bit_6 -compact
585 .\" 0 - stream mode, 1 - remote mode.
586 .\" In the stream mode, the pointing device sends the device status
587 .\" whenever its state changes. In the remote mode, the host computer
588 .\" must request the status to be sent.
591 .\" driver puts the device in the stream mode.
593 .\" Set if the pointing device is currently enabled. Otherwise zero.
595 .\" 0 - 1:1 scaling, 1 - 2:1 scaling.
596 .\" 1:1 scaling is the default.
600 .\" Left button status; set if pressed.
602 .\" Middle button status; set if pressed.
604 .\" Right button status; set if pressed.
607 .\" .Bl -tag -width bit_6_0 -compact
611 .\" Resolution code: zero through three. Actual resolution for
612 .\" the resolution code varies from one device to another.
615 .\" The status report rate (reports/sec) at which the device will send
616 .\" movement report to the host computer.
618 These commands are not currently supported by the
622 .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status
623 The command returns the current state of buttons and
624 movement counts as described in
628 .Bl -tag -width /dev/npsm0 -compact
630 `non-blocking' device node
632 `blocking' device node under
636 In order to install the
638 driver, you need to add
643 to your kernel configuration file, and put the following lines to
644 .Pa /boot/device.hints .
646 .Dl hint.atkbdc.0.at="isa"
647 .Dl hint.atkbdc.0.port="0x060"
648 .Dl hint.psm.0.at="atkbdc"
649 .Dl hint.psm.0.irq="12"
651 If you add the following statement to
652 .Pa /boot/device.hints ,
654 .Dl hint.psm.0.flags="0x2000"
656 you will add the optional code to stimulate the pointing device
657 after the `resume' event.
659 .Dl hint.psm.0.flags="0x24"
661 The above line will set the device resolution high (4)
662 and the acceleration factor to 2.
664 At debug level 0, little information is logged except for the following
665 line during boot process:
666 .Bd -literal -offset indent
672 the device ID code returned by the found pointing device.
677 At debug level 1 more information will be logged
678 while the driver probes the auxiliary port (mouse port).
679 Messages are logged with the LOG_KERN facility at the LOG_DEBUG level
682 .Bd -literal -offset indent
683 psm0: current command byte:xxxx
684 kbdio: TEST_AUX_PORT status:0000
685 kbdio: RESET_AUX return code:00fa
686 kbdio: RESET_AUX status:00aa
687 kbdio: RESET_AUX ID:0000
691 psm0: model AAAA, device ID X, N buttons
692 psm0: config:00000www, flags:0000uuuu, packet size:M
693 psm0: syncmask:xx, syncbits:yy
696 The first line shows the command byte value of the keyboard
697 controller just before the auxiliary port is probed.
698 It usually is 4D, 45, 47 or 65, depending on how the motherboard BIOS
699 initialized the keyboard controller upon power-up.
701 The second line shows the result of the keyboard controller's
702 test on the auxiliary port interface, with zero indicating
703 no error; note that some controllers report no error even if
704 the port does not exist in the system, however.
706 The third through fifth lines show the reset status of the pointing device.
707 The functioning device should return the sequence of FA AA <ID>.
708 The ID code is described above.
710 The seventh line shows the current hardware settings.
712 .\" .Dv MOUSE_READSTATE
714 These bytes are formatted as follows:
716 .Bl -tag -width Byte_1 -compact
718 .Bl -tag -width bit_6 -compact
722 0 - stream mode, 1 - remote mode.
723 In the stream mode, the pointing device sends the device status
724 whenever its state changes.
725 In the remote mode, the host computer
726 must request the status to be sent.
729 driver puts the device in the stream mode.
731 Set if the pointing device is currently enabled.
734 0 - 1:1 scaling, 1 - 2:1 scaling.
735 1:1 scaling is the default.
739 Left button status; set if pressed.
741 Middle button status; set if pressed.
743 Right button status; set if pressed.
746 .Bl -tag -width bit_6_0 -compact
750 Resolution code: zero through three.
751 Actual resolution for
752 the resolution code varies from one device to another.
755 The status report rate (reports/sec) at which the device will send
756 movement report to the host computer.
759 Note that the pointing device will not be enabled until the
761 driver is opened by the user program.
763 The rest of the lines show the device ID code, the number of detected
764 buttons and internal variables.
766 At debug level 2, much more detailed information is logged.
768 Many pad devices behave as if the first (left) button were pressed if
769 the user `taps' the surface of the pad.
770 In contrast, some pad products, e.g.\& some versions of ALPS GlidePoint
771 and Interlink VersaPad, treat the tapping action
772 as fourth button events.
774 It is reported that Interlink VersaPad requires both
778 flags in order to recover from suspended state.
779 These flags are automatically set when VersaPad is detected by the
783 Some PS/2 mouse models from MouseSystems require to be put in the
784 high resolution mode to work properly.
785 Use the driver flag to
788 There is not a guaranteed way to re-synchronize with the first byte
789 of the packet once we are out of synchronization with the data
791 However, if you are using the \fIXFree86\fP server and experiencing
792 the problem, you may be able to make the X server synchronize with the mouse
793 by switching away to a virtual terminal and getting back to the X server,
794 unless the X server is accessing the mouse via
796 Clicking any button without moving the mouse may also work.
801 It was never functional anyway.
816 driver is based on the work done by quite a number of people, including
827 This manual page was written by
828 .An Kazutaka Yokota Aq yokota@FreeBSD.org .