bef9a3bcaf028342a504e26545ff1e8b8c85f466
[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 .\" $DragonFly: src/share/man/man4/psm.4,v 1.5 2006/05/26 19:39:39 swildner Exp $
29 .\"
30 .Dd April 1, 2000
31 .Dt PSM 4
32 .Os
33 .Sh NAME
34 .Nm psm
35 .Nd PS/2 mouse style pointing device driver
36 .Sh SYNOPSIS
37 .Cd "options KBD_RESETDELAY=N"
38 .Cd "options KBD_MAXWAIT=N"
39 .Cd "options PSM_DEBUG=N"
40 .Cd "options KBDIO_DEBUG=N"
41 .Cd "device psm0 at atkbdc? irq 12"
42 .Sh DESCRIPTION
43 The
44 .Nm
45 driver provides support for the PS/2 mouse style pointing device.
46 Currently there can be only one
47 .Nm
48 device node in the system.
49 As the PS/2 mouse port is located
50 at the auxiliary port of the keyboard controller,
51 the keyboard controller driver,
52 .Nm atkbdc ,
53 must also be configured in the kernel.
54 Note that there is currently no provision of changing the
55 .Em irq
56 number.
57 .Pp
58 Basic PS/2 style pointing device has two or three buttons.
59 Some devices may have a roller or a wheel and/or additional buttons.
60 .Ss Device Resolution
61 The PS/2 style pointing device usually has several grades of resolution,
62 that is, sensitivity of movement.
63 They are typically 25, 50, 100 and 200
64 pulse per inch.
65 Some devices may have finer resolution.
66 The current resolution can be changed at runtime.
67 The
68 .Nm
69 driver allows the user to initially set the resolution
70 via the driver flag
71 (see
72 .Sx "DRIVER CONFIGURATION" )
73 or change it later via the
74 .Xr ioctl 2
75 command
76 .Dv MOUSE_SETMODE
77 (see
78 .Sx IOCTLS ) .
79 .Ss Report Rate
80 Frequency, or report rate, at which the device sends movement
81 and button state reports to the host system is also configurable.
82 The PS/2 style pointing device typically supports 10, 20, 40, 60, 80, 100
83 and 200 reports per second.
84 60 or 100 appears to be the default value for many devices.
85 Note that when there is no movement and no button has changed its state,
86 the device won't send anything to the host system.
87 The report rate can be changed via an ioctl call.
88 .Ss Operation Levels
89 The
90 .Nm
91 driver has three levels of operation.
92 The current operation level can be set via an ioctl call.
93 .Pp
94 At the level zero the basic support is provided; the device driver will report
95 horizontal and vertical movement of the attached device
96 and state of up to three buttons.
97 The movement and status are encoded in a series of fixed-length data packets
98 (see
99 .Sx "Data Packet Format" ) .
100 This is the default level of operation and the driver is initially
101 at this level when opened by the user program.
102 .Pp
103 The operation level one, the `extended' level, supports a roller (or wheel),
104 if any, and up to 11 buttons.
105 The movement of the roller is reported as movement along the Z axis.
106 8 byte data packets are sent to the user program at this level.
107 .Pp
108 At the operation level two, data from the pointing device is passed to the
109 user program as is.
110 Modern PS/2 type pointing devices often use proprietary data format.
111 Therefore, the user program is expected to have
112 intimate knowledge about the format from a particular device when operating
113 the driver at this level.
114 This level is called `native' level.
115 .Ss Data Packet Format
116 Data packets read from the
117 .Nm
118 driver are formatted differently at each operation level.
119 .Pp
120 A data packet from the PS/2 mouse style pointing device
121 is three bytes long at the operation level zero:
122 .Pp
123 .Bl -tag -width Byte_1 -compact
124 .It Byte 1
125 .Bl -tag -width bit_7 -compact
126 .It bit 7
127 One indicates overflow in the vertical movement count.
128 .It bit 6
129 One indicates overflow in the horizontal movement count.
130 .It bit 5
131 Set if the vertical movement count is negative.
132 .It bit 4
133 Set if the horizontal movement count is negative.
134 .It bit 3
135 Always one.
136 .\" The ALPS GlidePoint clears this bit when the user `taps' the surface of
137 .\" the pad, otherwise the bit is set.
138 .\" Most, if not all, other devices always set this bit.
139 .It bit 2
140 Middle button status; set if pressed.
141 For devices without the middle
142 button, this bit is always zero.
143 .It bit 1
144 Right button status; set if pressed.
145 .It bit 0
146 Left button status; set if pressed.
147 .El
148 .It Byte 2
149 Horizontal movement count in two's complement;
150 -256 through 255.
151 Note that the sign bit is in the first byte.
152 .It Byte 3
153 Vertical movement count in two's complement;
154 -256 through 255.
155 Note that the sign bit is in the first byte.
156 .El
157 .Pp
158 At the level one, a data packet is encoded
159 in the standard format
160 .Dv MOUSE_PROTO_SYSMOUSE
161 as defined in
162 .Xr mouse 4 .
163 .Pp
164 At the level two, native level, there is no standard on the size and format
165 of the data packet.
166 .Ss Acceleration
167 The
168 .Nm
169 driver can somewhat `accelerate' the movement of the pointing device.
170 The faster you move the device, the further the pointer
171 travels on the screen.
172 The driver has an internal variable which governs the effect of
173 the acceleration.
174 Its value can be modified via the driver flag
175 or via an ioctl call.
176 .Ss Device Number
177 The minor device number of the
178 .Nm
179 is made up of:
180 .Bd -literal -offset indent
181 minor = (`unit' << 1) | `non-blocking'
182 .Ed
183 .Pp
184 where `unit' is the device number (usually 0) and the `non-blocking' bit
185 is set to indicate ``don't block waiting for mouse input,
186 return immediately''.
187 The `non-blocking' bit should be set for \fIXFree86\fP,
188 therefore the minor device number usually used for \fIXFree86\fP is 1.
189 See
190 .Sx FILES
191 for device node names.
192 .Sh DRIVER CONFIGURATION
193 .Ss Kernel Configuration Options
194 There are following kernel configuration options to control the
195 .Nm
196 driver.
197 They may be set in the kernel configuration file
198 (see
199 .Xr config 8 ) .
200 .Bl -tag -width MOUSE
201 .It Em KBD_RESETDELAY=X , KBD_MAXWAIT=Y
202 The
203 .Nm
204 driver will attempt to reset the pointing device during the boot process.
205 It sometimes takes a long while before the device will respond after
206 reset.
207 These options control how long the driver should wait before
208 it eventually gives up waiting.
209 The driver will wait
210 .Fa X
211 *
212 .Fa Y
213 msecs at most.
214 If the driver seems unable to detect your pointing
215 device, you may want to increase these values.
216 The default values are
217 200 msec for
218 .Fa X
219 and 5
220 for
221 .Fa Y .
222 .It Em PSM_DEBUG=N , KBDIO_DEBUG=N
223 Sets the debug level to
224 .Fa N .
225 The default debug level is zero.
226 See
227 .Sx DIAGNOSTICS
228 for debug logging.
229 .El
230 .Ss Driver Flags
231 The
232 .Nm
233 driver accepts the following driver flags.
234 Set them in the
235 kernel configuration file or in the User Configuration Menu at
236 the boot time
237 (see
238 .Xr boot 8 ) .
239 .Pp
240 .Bl -tag -width MOUSE
241 .It bit 0..3 RESOLUTION
242 This flag specifies the resolution of the pointing device.
243 It must be zero through four.
244 The greater the value
245 is, the finer resolution the device will select.
246 Actual resolution selected by this field varies according to the model
247 of the device.
248 Typical resolutions are:
249 .Pp
250 .Bl -tag -width 0_(medium_high)__ -compact
251 .It Em 1 (low)
252 25 pulse per inch (ppi)
253 .It Em 2 (medium low)
254 50 ppi
255 .It Em 3 (medium high)
256 100 ppi
257 .It Em 4 (high)
258 200 ppi
259 .El
260 .Pp
261 Leaving this flag zero will selects the default resolution for the
262 device (whatever it is).
263 .It bit 4..7 ACCELERATION
264 This flag controls the amount of acceleration effect.
265 The smaller the value of this flag is, more sensitive the movement becomes.
266 The minimum value allowed, thus the value for the most sensitive setting,
267 is one.
268 Setting this flag to zero will completely disables the
269 acceleration effect.
270 .It bit 8 NOCHECKSYNC
271 The
272 .Nm
273 driver tries to detect the first byte of the data packet by checking
274 the bit pattern of that byte.
275 Although this method should work with most
276 PS/2 pointing devices, it may interfere with some devices which are not
277 so compatible with known devices.
278 If you think your pointing device is not functioning as expected,
279 and the kernel frequently prints the following message to the console,
280 .Bd -literal -offset indent
281 psmintr: out of sync (xxxx != yyyy).
282 .Ed
283 .Pp
284 set this flag to disable synchronization check and see if it helps.
285 .It bit 9 NOIDPROBE
286 The
287 .Nm
288 driver will not try to identify the model of the pointing device and
289 will not carry out model-specific initialization.
290 The device should always act like a standard PS/2 mouse without such
291 initialization.
292 Extra features, such as wheels and additional buttons, won't be
293 recognized by the
294 .Nm
295 driver.
296 .It bit 10 NORESET
297 When this flag is set, the
298 .Nm
299 driver won't reset the pointing device when initializing the device.
300 If the
301 .Dx
302 kernel
303 is started after another OS has run, the pointing device will inherit
304 settings from the previous OS.
305 However, because there is no way for the
306 .Nm
307 driver to know the settings, the device and the driver may not
308 work correctly.
309 The flag should never be necessary under normal circumstances.
310 .It bit 11 FORCETAP
311 Some pad devices report as if the fourth button is pressed
312 when the user `taps' the surface of the device (see
313 .Sx CAVEATS ) .
314 This flag will make the
315 .Nm
316 driver assume that the device behaves this way.
317 Without the flag, the driver will assume this behavior
318 for ALPS GlidePoint models only.
319 .It bit 12 IGNOREPORTERROR
320 This flag makes
321 .Nm
322 driver ignore certain error conditions when probing the PS/2 mouse port.
323 It should never be necessary under normal circumstances.
324 .It bit 13 HOOKRESUME
325 The built-in PS/2 pointing device of some laptop computers is somehow
326 not operable immediately after the system `resumes' from
327 the power saving mode,
328 though it will eventually become available.
329 There are reports that
330 stimulating the device by performing I/O will help
331 waking up the device quickly.
332 This flag will enable a piece of code in the
333 .Nm
334 driver to hook
335 the `resume' event and exercise some harmless I/O operations on the
336 device.
337 .It bit 14 INITAFTERSUSPEND
338 This flag adds more drastic action for the above problem.
339 It will cause the
340 .Nm
341 driver to reset and re-initialize the pointing device
342 after the `resume' event.
343 It has no effect unless the
344 .Em HOOKRESUME
345 flag is set as well.
346 .El
347 .Sh IOCTLS
348 There are a few
349 .Xr ioctl 2
350 commands for mouse drivers.
351 These commands and related structures and constants are defined in
352 .In machine/mouse.h .
353 General description of the commands is given in
354 .Xr mouse 4 .
355 This section explains the features specific to the
356 .Nm
357 driver.
358 .Pp
359 .Bl -tag -width MOUSE -compact
360 .It Dv MOUSE_GETLEVEL Ar int *level
361 .It Dv MOUSE_SETLEVEL Ar int *level
362 These commands manipulate the operation level of the
363 .Nm
364 driver.
365 .Pp
366 .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
367 Returns the hardware information of the attached device in the following
368 structure.
369 .Bd -literal
370 typedef struct mousehw {
371     int buttons;    /* number of buttons */
372     int iftype;     /* I/F type */
373     int type;       /* mouse/track ball/pad... */
374     int model;      /* I/F dependent model ID */
375     int hwid;       /* I/F dependent hardware ID */
376 } mousehw_t;
377 .Ed
378 .Pp
379 The
380 .Dv buttons
381 field holds the number of buttons on the device.
382 The
383 .Nm
384 driver currently can detect the 3 button mouse from Logitech and report
385 accordingly.
386 The 3 button mouse from the other manufacturer may or may not be
387 reported correctly.
388 However, it will not affect the operation of
389 the driver.
390 .Pp
391 The
392 .Dv iftype
393 is always
394 .Dv MOUSE_IF_PS2 .
395 .Pp
396 The
397 .Dv type
398 tells the device type:
399 .Dv MOUSE_MOUSE ,
400 .Dv MOUSE_TRACKBALL ,
401 .Dv MOUSE_STICK ,
402 .Dv MOUSE_PAD ,
403 or
404 .Dv MOUSE_UNKNOWN .
405 The user should not heavily rely on this field, as the
406 driver may not always, in fact it is very rarely able to, identify
407 the device type.
408 .Pp
409 The
410 .Dv model
411 is always
412 .Dv MOUSE_MODEL_GENERIC
413 at the operation level 0.
414 It may be
415 .Dv MOUSE_MODEL_GENERIC
416 or one of
417 .Dv MOUSE_MODEL_XXX
418 constants at higher operation levels.
419 Again the
420 .Nm
421 driver may or may not set an appropriate value in this field.
422 .Pp
423 The
424 .Dv hwid
425 is the ID value returned by the device.
426 Known IDs include:
427 .Pp
428 .Bl -tag -width 0__ -compact
429 .It Em 0
430 Mouse (Microsoft, Logitech and many other manufacturers)
431 .It Em 2
432 Microsoft Ballpoint mouse
433 .It Em 3
434 Microsoft IntelliMouse
435 .El
436 .Pp
437 .It Dv MOUSE_GETMODE Ar mousemode_t *mode
438 The command gets the current operation parameters of the mouse
439 driver.
440 .Bd -literal
441 typedef struct mousemode {
442     int protocol;    /* MOUSE_PROTO_XXX */
443     int rate;        /* report rate (per sec), -1 if unknown */
444     int resolution;  /* MOUSE_RES_XXX, -1 if unknown */
445     int accelfactor; /* acceleration factor */
446     int level;       /* driver operation level */
447     int packetsize;  /* the length of the data packet */
448     unsigned char syncmask[2]; /* sync. bits */
449 } mousemode_t;
450 .Ed
451 .Pp
452 The
453 .Dv protocol
454 is
455 .Dv MOUSE_PROTO_PS2
456 at the operation level zero and two.
457 .Dv MOUSE_PROTO_SYSMOUSE
458 at the operation level one.
459 .Pp
460 The
461 .Dv rate
462 is the status report rate (reports/sec) at which the device will send
463 movement report to the host computer.
464 Typical supported values are 10, 20, 40, 60, 80, 100 and 200.
465 Some mice may accept other arbitrary values too.
466 .Pp
467 The
468 .Dv resolution
469 of the pointing device must be one of
470 .Dv MOUSE_RES_XXX
471 constants or a positive value.
472 The greater the value
473 is, the finer resolution the mouse will select.
474 Actual resolution selected by the
475 .Dv MOUSE_RES_XXX
476 constant varies according to the model of mouse.
477 Typical resolutions are:
478 .Pp
479 .Bl -tag -width MOUSE_RES_MEDIUMHIGH__ -compact
480 .It Dv MOUSE_RES_LOW
481 25 ppi
482 .It Dv MOUSE_RES_MEDIUMLOW
483 50 ppi
484 .It Dv MOUSE_RES_MEDIUMHIGH
485 100 ppi
486 .It Dv MOUSE_RES_HIGH
487 200 ppi
488 .El
489 .Pp
490 The
491 .Dv accelfactor
492 field holds a value to control acceleration feature
493 (see
494 .Sx Acceleration ) .
495 It must be zero or greater.  If it is zero, acceleration is disabled.
496 .Pp
497 The
498 .Dv packetsize
499 field specifies the length of the data packet.
500 It depends on the
501 operation level and the model of the pointing device.
502 .Pp
503 .Bl -tag -width level_0__ -compact
504 .It Em level 0
505 3 bytes
506 .It Em level 1
507 8 bytes
508 .It Em level 2
509 Depends on the model of the device
510 .El
511 .Pp
512 The array
513 .Dv syncmask
514 holds a bit mask and pattern to detect the first byte of the
515 data packet.
516 .Dv syncmask[0]
517 is the bit mask to be ANDed with a byte.
518 If the result is equal to
519 .Dv syncmask[1] ,
520 the byte is likely to be the first byte of the data packet.
521 Note that this detection method is not 100% reliable,
522 thus, should be taken only as an advisory measure.
523 .Pp
524 .It Dv MOUSE_SETMODE Ar mousemode_t *mode
525 The command changes the current operation parameters of the mouse driver
526 as specified in
527 .Ar mode .
528 Only
529 .Dv rate ,
530 .Dv resolution ,
531 .Dv level
532 and
533 .Dv accelfactor
534 may be modifiable.
535 Setting values in the other field does not generate
536 error and has no effect.
537 .Pp
538 If you do not want to change the current setting of a field, put -1
539 there.
540 You may also put zero in
541 .Dv resolution
542 and
543 .Dv rate ,
544 and the default value for the fields will be selected.
545 .\" .Pp
546 .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
547 .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
548 .\" These commands are not supported by the
549 .\" .Nm
550 .\" driver.
551 .Pp
552 .It Dv MOUSE_READDATA Ar mousedata_t *data
553 .\" The command reads the raw data from the device.
554 .\" .Bd -literal
555 .\" typedef struct mousedata {
556 .\"     int len;        /* # of data in the buffer */
557 .\"     int buf[16];    /* data buffer */
558 .\" } mousedata_t;
559 .\" .Ed
560 .\" .Pp
561 .\" Upon returning to the user program, the driver will place the number
562 .\" of valid data bytes in the buffer in the
563 .\" .Dv len
564 .\" field.
565 .\" .Pp
566 .It Dv MOUSE_READSTATE Ar mousedata_t *state
567 .\" The command reads the hardware settings from the device.
568 .\" Upon returning to the user program, the driver will place the number
569 .\" of valid data bytes in the buffer in the
570 .\" .Dv len
571 .\" field. It is usually 3 bytes.
572 .\" The buffer is formatted as follows:
573 .\" .Pp
574 .\" .Bl -tag -width Byte_1 -compact
575 .\" .It Byte 1
576 .\" .Bl -tag -width bit_6 -compact
577 .\" .It bit 7
578 .\" Reserved.
579 .\" .It bit 6
580 .\" 0 - stream mode, 1 - remote mode.
581 .\" In the stream mode, the pointing device sends the device status
582 .\" whenever its state changes. In the remote mode, the host computer
583 .\" must request the status to be sent.
584 .\" The
585 .\" .Nm
586 .\" driver puts the device in the stream mode.
587 .\" .It bit 5
588 .\" Set if the pointing device is currently enabled. Otherwise zero.
589 .\" .It bit 4
590 .\" 0 - 1:1 scaling, 1 - 2:1 scaling.
591 .\" 1:1 scaling is the default.
592 .\" .It bit 3
593 .\" Reserved.
594 .\" .It bit 2
595 .\" Left button status; set if pressed.
596 .\" .It bit 1
597 .\" Middle button status; set if pressed.
598 .\" .It bit 0
599 .\" Right button status; set if pressed.
600 .\" .El
601 .\" .It Byte 2
602 .\" .Bl -tag -width bit_6_0 -compact
603 .\" .It bit 7
604 .\" Reserved.
605 .\" .It bit 6..0
606 .\" Resolution code: zero through three. Actual resolution for
607 .\" the resolution code varies from one device to another.
608 .\" .El
609 .\" .It Byte 3
610 .\" The status report rate (reports/sec) at which the device will send
611 .\" movement report to the host computer.
612 .\" .El
613 These commands are not currently supported by the
614 .Nm
615 driver.
616 .Pp
617 .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status
618 The command returns the current state of buttons and
619 movement counts as described in
620 .Xr mouse 4 .
621 .El
622 .Sh FILES
623 .Bl -tag -width /dev/npsm0 -compact
624 .It Pa /dev/psm0
625 `non-blocking' device node
626 .It Pa /dev/bpsm0
627 `blocking' device node
628 .El
629 .Sh EXAMPLES
630 .Dl "device psm0 at atkbdc? irq 12 flags 0x2000"
631 .Pp
632 Add the
633 .Nm
634 driver to the kernel with the optional code to stimulate the pointing device
635 after the `resume' event.
636 .Pp
637 .Dl "device psm0 at atkbdc? flags 0x024 irq 12"
638 .Pp
639 Set the device resolution high (4) and the acceleration factor to 2.
640 .Sh DIAGNOSTICS
641 At debug level 0, little information is logged except for the following
642 line during boot process:
643 .Bd -literal -offset indent
644 psm0: device ID X
645 .Ed
646 .Pp
647 where
648 .Fa X
649 the device ID code returned by the found pointing device.
650 See
651 .Dv MOUSE_GETINFO
652 for known IDs.
653 .Pp
654 At debug level 1 more information will be logged
655 while the driver probes the auxiliary port (mouse port).
656 Messages are logged with the LOG_KERN facility at the LOG_DEBUG level
657 (see
658 .Xr syslogd 8 ) .
659 .Bd -literal -offset indent
660 psm0: current command byte:xxxx
661 kbdio: TEST_AUX_PORT status:0000
662 kbdio: RESET_AUX return code:00fa
663 kbdio: RESET_AUX status:00aa
664 kbdio: RESET_AUX ID:0000
665 [...]
666 psm: status 00 02 64
667 psm0 irq 12 on isa
668 psm0: model AAAA, device ID X, N buttons
669 psm0: config:00000www, flags:0000uuuu, packet size:M
670 psm0: syncmask:xx, syncbits:yy
671 .Ed
672 .Pp
673 The first line shows the command byte value of the keyboard
674 controller just before the auxiliary port is probed.
675 It usually is 4D, 45, 47 or 65, depending on how the motherboard BIOS
676 initialized the keyboard controller upon power-up.
677 .Pp
678 The second line shows the result of the keyboard controller's
679 test on the auxiliary port interface, with zero indicating
680 no error; note that some controllers report no error even if
681 the port does not exist in the system, however.
682 .Pp
683 The third through fifth lines show the reset status of the pointing device.
684 The functioning device should return the sequence of FA AA <ID>.
685 The ID code is described above.
686 .Pp
687 The seventh line shows the current hardware settings.
688 .\" See
689 .\" .Dv MOUSE_READSTATE
690 .\" for definitions.
691 These bytes are formatted as follows:
692 .Pp
693 .Bl -tag -width Byte_1 -compact
694 .It Byte 1
695 .Bl -tag -width bit_6 -compact
696 .It bit 7
697 Reserved.
698 .It bit 6
699 0 - stream mode, 1 - remote mode.
700 In the stream mode, the pointing device sends the device status
701 whenever its state changes.
702 In the remote mode, the host computer
703 must request the status to be sent.
704 The
705 .Nm
706 driver puts the device in the stream mode.
707 .It bit 5
708 Set if the pointing device is currently enabled.
709 Otherwise zero.
710 .It bit 4
711 0 - 1:1 scaling, 1 - 2:1 scaling.
712 1:1 scaling is the default.
713 .It bit 3
714 Reserved.
715 .It bit 2
716 Left button status; set if pressed.
717 .It bit 1
718 Middle button status; set if pressed.
719 .It bit 0
720 Right button status; set if pressed.
721 .El
722 .It Byte 2
723 .Bl -tag -width bit_6_0 -compact
724 .It bit 7
725 Reserved.
726 .It bit 6..0
727 Resolution code: zero through three.
728 Actual resolution for
729 the resolution code varies from one device to another.
730 .El
731 .It Byte 3
732 The status report rate (reports/sec) at which the device will send
733 movement report to the host computer.
734 .El
735 .Pp
736 Note that the pointing device will not be enabled until the
737 .Nm
738 driver is opened by the user program.
739 .Pp
740 The rest of the lines show the device ID code, the number of detected
741 buttons and internal variables.
742 .Pp
743 At debug level 2, much more detailed information is logged.
744 .Sh CAVEATS
745 Many pad devices behave as if the first (left) button were pressed if
746 the user `taps' the surface of the pad.
747 In contrast, some pad products, e.g. some versions of ALPS GlidePoint
748 and Interlink VersaPad, treat the tapping action
749 as fourth button events.
750 .Pp
751 It is reported that Interlink VersaPad rquires both
752 .Em HOOKRESUME
753 and
754 .Em INITAFTERSUSPEND
755 flags in order to recover from suspended state.
756 These flags are automatically set when VersaPad is detected by the
757 .Nm
758 driver.
759 .Pp
760 Some PS/2 mouse models from MouseSystems require to be put in the
761 high resolution mode to work properly.
762 Use the driver flag to
763 set resolution.
764 .Pp
765 There is not a guaranteed way to re-synchronize with the first byte
766 of the packet once we are out of synchronization with the data
767 stream.
768 However, if you are using the \fIXFree86\fP server and experiencing
769 the problem, you may be able to make the X server synchronize with the mouse
770 by switching away to a virtual terminal and getting back to the X server,
771 unless the X server is accessing the mouse via
772 .Xr moused 8 .
773 Clicking any button without moving the mouse may also work.
774 .Sh SEE ALSO
775 .Xr ioctl 2 ,
776 .Xr syslog 3 ,
777 .Xr atkbdc 4 ,
778 .Xr mouse 4 ,
779 .Xr mse 4 ,
780 .Xr sysmouse 4 ,
781 .Xr moused 8 ,
782 .Xr syslogd 8
783 .\".Sh HISTORY
784 .Sh AUTHORS
785 .An -nosplit
786 The
787 .Nm
788 driver is based on the work done by quite a number of people, including
789 .An Eric Forsberg ,
790 .An Sandi Donno ,
791 .An Rick Macklem ,
792 .An Andrew Herbert ,
793 .An Charles Hannum ,
794 .An Shoji Yuen
795 and
796 .An Kazutaka Yokota
797 to name the few.
798 .Pp
799 This manual page was written by
800 .An Kazutaka Yokota Aq yokota@FreeBSD.org .
801 .Sh BUGS
802 The ioctl command
803 .Dv MOUSEIOCREAD
804 has been removed.
805 It was never functional anyway.