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