mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-15 10:17:20 +00:00
378 lines
10 KiB
Groff
378 lines
10 KiB
Groff
.\" $Id$
|
|
.\"
|
|
.Dd Nov 8, 1996
|
|
.Dt PSM 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm psm
|
|
.Nd
|
|
PS/2 mouse style pointing device driver
|
|
.Sh SYNOPSIS
|
|
.\".Cd "options PSM_NOCHECKSYNC"
|
|
.\".Cd "options PSM_NOEMULATION"
|
|
.\".Cd "options" \&"PSM_ACCEL=N\&"
|
|
.Cd "options" \&"PSM_RESETDELAY=N\&"
|
|
.Cd "options" \&"PSM_MAXWAIT=N\&"
|
|
.Cd "options" \&"PSM_DEBUG=N\&"
|
|
.Cd "device psm0 at isa? port" \&"IO_KBD\&" conflicts tty irq 12 vector psmintr
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver provides support for the PS/2 mouse style pointing device.
|
|
|
|
Note that
|
|
.Nm port \&"IO_KBD\&"
|
|
and
|
|
.Nm conflicts
|
|
is required
|
|
as the PS/2 mouse port is located
|
|
at the auxially port of the keyboard controller, thus, the
|
|
.Nm
|
|
driver has to share the port with the keyboard driver.
|
|
Note also that there is currently no provision of changing the
|
|
.Nm irq
|
|
number.
|
|
.Pp
|
|
A series of data packets is read from the
|
|
.Nm
|
|
driver. A data packet from the PS/2 mouse style pointing device
|
|
is three bytes long:
|
|
.Pp
|
|
.Bl -tag -width Byte_1
|
|
.It Byte 1
|
|
.Bl -tag -width bit_7
|
|
.It bit 7
|
|
One indicates overflow in the vertical movement count.
|
|
.It bit 6
|
|
One indicates overflow in the horizontal movement count.
|
|
.It bit 5
|
|
Set if the vertical movement count is negative.
|
|
.It bit 4
|
|
Set if the horizontal movement count is negative.
|
|
.It bit 3
|
|
Always one?.
|
|
.It bit 2
|
|
Middle button status; set if pressed. For the device without the middle
|
|
button, this bit is always one?.
|
|
.It bit 1
|
|
Right button status; set if pressed.
|
|
.It bit 0
|
|
Left button status; set if pressed.
|
|
.El
|
|
.It Byte 2
|
|
Horizontal movement count in two's compliment;
|
|
-128 through 127.
|
|
.It Byte 3
|
|
Vertical movement count in two's compliment;
|
|
-128 through 127.
|
|
.El
|
|
.Pp
|
|
The minor device number of the
|
|
.Nm
|
|
is made up of:
|
|
.Bd -literal -offset indent
|
|
minor = (`unit' << 1) | `non-blocking'
|
|
.Ed
|
|
.Pp
|
|
where `unit' is the device number (usually 0) and the `non-blocking' bit
|
|
is set to indicate "don't block waiting for mouse input, return immediately".
|
|
The `non-blocking' bit should be set for \fIXFree86\fP,
|
|
therefore the minor device number usually used for \fIXFree86\fP is 1.
|
|
.Sh KERNEL CONFIGURATION
|
|
There are following options to control the
|
|
.Nm
|
|
device.
|
|
.Bl -tag -width MOUSE
|
|
.\".It Em PSM_NOCHECKSYNC
|
|
.\"By default, the driver tries to detect the first byte of
|
|
.\"the three-byte-long data packet. However, this may not always be
|
|
.\"reliable. This feature will be turned off by specifying this option.
|
|
.\".It Em PSM_NOEMULATION
|
|
.\"The
|
|
.\".Nm
|
|
.\"driver can emulate the Microsoft Serial Mouse's three-byte
|
|
.\"data packet and the Mouse Systems Corp's five-byte data packet
|
|
.\"when data is read by user programs, if so specified by the
|
|
.\".Fn ioctl
|
|
.\"command
|
|
.\".Dv MOUSE_SETMODE .
|
|
.\"The emulation will be disabled with this option.
|
|
.\".It Em PSM_ACCEL=N
|
|
.\"The
|
|
.\".Nm
|
|
.\"driver somewhat `accelerates' the movement of the pointing device.
|
|
.\"That is, the faster you move the device, the longer the pointer
|
|
.\"travels on the screen. This option controls the amount of acceleration.
|
|
.\"The smaller
|
|
.\".Fa N
|
|
.\"is, more sensitive the movement becomes. The default value is 2.
|
|
.\"The minimum value, thus the value for the most sensitive setting, allowed
|
|
.\"is 1. Setting this option to zero will completely disables the
|
|
.\"acceleration effect.
|
|
.It Em PSM_RESETDELAY=X, PSM_MAXWAIT=Y
|
|
The
|
|
.Nm
|
|
driver will attempt to reset the pointing device during the boot process.
|
|
It sometimes takes a long while before the device will respond after
|
|
reset. These options control how long the driver should wait before
|
|
it eventually gives up waiting. The driver will wait
|
|
.Fa X
|
|
*
|
|
.Fa Y
|
|
msecs at most. If the driver seems unable to detect your pointing
|
|
device, you may want to increase these values. The default values are
|
|
200 msec for
|
|
.Fa X
|
|
and 5
|
|
for
|
|
.Fa Y .
|
|
.It Em PSM_DEBUG=N
|
|
Sets the debug level to
|
|
.Fa N .
|
|
The default debug level is zero. See
|
|
.Em DIAGNOSTICS
|
|
for debug logging.
|
|
.El
|
|
.\".Sh IOCTL
|
|
.\".Bl -tag -width MOUSE
|
|
.\".It Dv MOUSE_GETSTATE, MOUSECREAD
|
|
.\"The command returns the current mouse state in the following structure
|
|
.\"and remove the state information from the internal queue.
|
|
.\".Bd -literal
|
|
.\"struct mouseinfo {
|
|
.\" unsigned char status; /* button and motion status bits */
|
|
.\" char xmotion; /* horizontal motion count */
|
|
.\" char ymotion; /* vertical motion count */
|
|
.\"};
|
|
.\".Ed
|
|
.\".Pp
|
|
.\"The
|
|
.\".Dv status
|
|
.\"holds a ORed value of the following constants:
|
|
.\".Bl -tag -width BUTSTATMASK
|
|
.\".It Dv BUT1STAT
|
|
.\"The Button 1 (left button) is pressed.
|
|
.\".It Dv BUT2STAT
|
|
.\"The Button 2 (middle button) is pressed.
|
|
.\".It Dv BUT3STAT
|
|
.\"The Button 3 (right button) is pressed.
|
|
.\".It Dv BUT1CHNG
|
|
.\"The state of the button 1 has changed.
|
|
.\".It Dv BUT2CHNG
|
|
.\"The state of the button 2 has changed.
|
|
.\".It Dv BUT3CHNG
|
|
.\"The state of the button 3 has changed.
|
|
.\".It Dv MOVEMENT
|
|
.\"Either
|
|
.\".Dv xmotion
|
|
.\"or
|
|
.\".Dv ymotion
|
|
.\"is not zero.
|
|
.\".El
|
|
.\".Pp
|
|
.\"Note that these commands and
|
|
.\".Fn read
|
|
.\"operation on the
|
|
.\".Nm
|
|
.\"driver uses the same internal queue. Therefore, interleaving
|
|
.\"these commands and
|
|
.\".Fn read
|
|
.\"operation is not recommended.
|
|
.\".It Dv MOUSE_GETINFO
|
|
.\"Returns the hardware information in the following structure:
|
|
.\".Bd -literal
|
|
.\"typedef struct mousehw {
|
|
.\" int buttons; /* number of buttons */
|
|
.\" int iftype; /* I/F type */
|
|
.\" int type; /* mouse/track ball/pad... */
|
|
.\" int hwid; /* I/F dependent hardware ID */
|
|
.\"} mousehw_t;
|
|
.\".Ed
|
|
.\".Pp
|
|
.\"The
|
|
.\".Dv iftype
|
|
.\"is
|
|
.\".Dv MOUSE_IF_PS2
|
|
.\"for the
|
|
.\".Nm
|
|
.\"driver. The
|
|
.\".Dv type
|
|
.\"tells the device type:
|
|
.\".Dv MOUSE_MOUSE ,
|
|
.\".Dv MOUSE_TRACKBALL ,
|
|
.\".Dv MOUSE_STICK ,
|
|
.\".Dv MOUSE_PAD ,
|
|
.\"or
|
|
.\".Dv MOUSE_UNKNOWN .
|
|
.\"The user should not heavily rely on this field, as the
|
|
.\".Nm
|
|
.\"driver may not always, in fact it is very rarely able to, identify
|
|
.\"the device type.
|
|
.\"The
|
|
.\".Dv hwid
|
|
.\"is the ID value returned by the pointing device. See below for possible
|
|
.\"values.
|
|
.\".It Dv MOUSE_GETMODE, MOUSE_SETMODE
|
|
.\"The commands get and set operation mode of the
|
|
.\".Nm
|
|
.\"driver.
|
|
.\".Bd -literal
|
|
.\"typedef struct mousemode {
|
|
.\" int protocol; /* MOUSE_PROTO_XXX */
|
|
.\" int rate; /* report rate (per sec), -1 if unknown */
|
|
.\" int resolution; /* ppi, -1 if unknown */
|
|
.\" int accelfactor; /* acceleration factor (must be 1 or greater) */
|
|
.\"} mousemode_t;
|
|
.\".Ed
|
|
.\".Pp
|
|
.\"The
|
|
.\".Dv protocol
|
|
.\"selects the format with which the device status is returned by
|
|
.\".Fn read .
|
|
.\"The default is
|
|
.\".Dv MOUSE_PROTO_PS2 ,
|
|
.\"that is, the data byte from the pointing device is returned as is.
|
|
.\"Other possible values are:
|
|
.\".Dv MOUSE_PROTO_MSS
|
|
.\"and
|
|
.\".Dv MOUSE_PROTO_MSC ,
|
|
.\"which specifies Microsoft Serial Mouse three-byte format and
|
|
.\"Mouse Systems Corp.'s five-byte format respectively.
|
|
.\"The
|
|
.\".Dv rate
|
|
.\"is the status report rate (reports/sec) at which the device will send
|
|
.\"movement report to the host computer.
|
|
.\"The
|
|
.\".Dv resolution
|
|
.\"of the pointing device is expressed in pulse-per-inch. Setting
|
|
.\"this field to an arbitrary value may not always work.
|
|
.\"The
|
|
.\".Dv accelfactor
|
|
.\"holds a value to control acceleration feature (see description on
|
|
.\".Em PSM_ACCEL
|
|
.\"above). It must be one or greater.
|
|
.\"If acceleration is disabled by the kernel configuration,
|
|
.\"setting this field has no effect.
|
|
.\".El
|
|
.Sh DIAGNOSTICS
|
|
.Pp
|
|
At debug level 0, little information is logged except for the following
|
|
line during boot process:
|
|
.Bd -literal -offset indent
|
|
psm0: device ID X, N buttons?
|
|
.Ed
|
|
.Pp
|
|
where
|
|
.Fa X
|
|
the device ID code returned by the found pointing device.
|
|
Known IDs include:
|
|
.Bl -tag -width 0__
|
|
.It Em 0
|
|
Mouse (Microsoft, Logitech and many other manufacturers)
|
|
.It Em 2
|
|
Microsoft Ballpoint mouse
|
|
.El
|
|
.Pp
|
|
Currently the
|
|
.Nm
|
|
driver can detect the 3 button mouse from Logitech and report
|
|
accordingly.
|
|
The 3 button mouse from the other manufacturer may or may not be
|
|
reported correctly. However, it will not affect the operation of
|
|
the driver.
|
|
.Pp
|
|
At debug level 1 more information will be logged
|
|
while the driver probes the auxially (mouse) port.
|
|
Messages are logged with the LOG_KERN facility at the LOG_DEBUG level.
|
|
(See
|
|
.Xr syslogd 8 . )
|
|
.Bd -literal -offset indent
|
|
psm0: current command byte:xxxx
|
|
psm: TEST_AUX_PORT status:0000
|
|
psm: RESET_AUX return code:00fa
|
|
psm: RESET_AUX status:00aa
|
|
psm: RESET_AUX ID:0000
|
|
psm: status xx yy zz (get_mouse_buttons)
|
|
psm0: status 00 03 64
|
|
.Ed
|
|
.Pp
|
|
The first line shows the command byte value of the keyboard
|
|
controller just before the auxially port is probed.
|
|
It usually is 4D, 45, 47 or 65, depending on the keyboard device
|
|
driver.
|
|
.Pp
|
|
The second line shows the result of the keyboard controller's
|
|
test on the auxially port interface, with zero indicating
|
|
no error; note that some controllers report no error even if
|
|
the port does not exist in the system, however.
|
|
.Pp
|
|
The third to fifth lines show the reset status of the pointing device.
|
|
The functioning device should return the sequence of FA AA <ID>.
|
|
The ID code is described above.
|
|
.Pp
|
|
The seventh line show the current hardware settings; it consists
|
|
of three bytes:
|
|
.Bl -tag -width Byte_1
|
|
.It Byte 1
|
|
.Bl -tag -width bit_6
|
|
.It bit 6
|
|
0: stream mode (default after reset), 1: remote mode.
|
|
In the stream mode, the pointing device sends the device status
|
|
whenever its state changes. In the remote mode, the host computer
|
|
must request the status to be sent.
|
|
.It bit 5
|
|
Set if the pointing device is currently enabled. Otherwise zero.
|
|
.It bit 4
|
|
0 - 1:1 scaling, 1 - 2:1 scaling.
|
|
.It bit 2
|
|
Left button status; set if pressed.
|
|
.It bit 1
|
|
Middle button status; set if pressed.
|
|
.It bit 0
|
|
Right button status; set if pressed.
|
|
.El
|
|
.It Byte 2
|
|
Resolution.
|
|
.Bl -tag -width 100
|
|
.It 0
|
|
25 pulse per inch (ppi)
|
|
.It 1
|
|
50 ppi
|
|
.It 2
|
|
100 ppi
|
|
.It 3
|
|
200 ppi
|
|
.El
|
|
.It Byte 3
|
|
The status report rate (reports/sec) at which the device will send
|
|
movement report to the host computer.
|
|
.El
|
|
.Pp
|
|
Note that the pointing device will not be enabled until the
|
|
.Nm
|
|
device is opened by the user programs.
|
|
.Pp
|
|
At debug level 2, much more detailed information is logged.
|
|
.Sh CAVEATS
|
|
There is not a guaranteed way to re-synchronize with the first byte
|
|
of the packet once we are out of synchronization with the data
|
|
stream, because there is not a unique bit pattern to identify
|
|
the first byte with.
|
|
.Sh BUGS
|
|
The driver includes the code for the
|
|
.Dv MOUSECREAD
|
|
command of
|
|
.Fn ioctl
|
|
function, which fills a
|
|
.Fa mouseinfo
|
|
structure (see
|
|
.Ao Pa machine/mouse.h Ac ).
|
|
However, it currently is not functioning properly, and may be removed
|
|
in the future.
|
|
.Sh SEE ALSO
|
|
.Xr syslog 3 ,
|
|
.Xr mse 4 ,
|
|
.Xr syslogd 8
|
|
.\" .Sh HISTORY
|
|
.\" .Sh AUTHOR
|