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