kernel: Remove some old ISA only drivers.
[dragonfly.git] / share / man / man4 / psm.4
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.