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