d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document recent mouse code changes.

Browse Source
This commit is contained in:
Kazutaka YOKOTA 1997-12-07 08:46:56 +00:00
parent f8d795fb89
commit 369a889c64
7 changed files with 2743 additions and 507 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

382
share/man/man4/man4.i386/mouse.4 Normal file
View File

@ -0,0 +1,382 @@
.\"
.\" Copyright (c) 1997
.\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id:$
.\"
.Dd December 3, 1997
.Dt MOUSE 4 i386
.Os FreeBSD
.Sh NAME
.Nm mouse
.Nd mouse and pointing device drivers
.Sh SYNOPSIS
.Fd #include <machine/mouse.h>
.Sh DESCRIPTION
The mouse drivers
.Xr mse 4 ,
.Xr psm 4
and
.Xr sysmouse 4
provide user programs with movement and button state information of the mouse.
Currently there are specific device drivers for bus, InPort and PS/2 mice.
The serial mouse is not directly supported by a dedicated driver, but
it is accessible via the serial device driver or via
.Xr moused 8
and
.Xr sysmouse 4 .
.Pp
The user program simply opens a mouse device with a
.Xr open 2
call and reads
mouse data from the device via
.Xr read 2 .
Movement and button states are usually encoded in fixed-length data packets.
Some mouse devices may send data in variable length of packets.
Actual protocol (data format) used by each driver differs widely.
.Pp
The mouse drivers may have ``non-blocking'' attribute which will make
the driver return immediately if mouse data is not available.
.Pp
Mouse device drivers often offer several levels of operation.
The current operation level can be examined and changed via
.Xr ioctl 2
commands.
The level zero is the lowest level at which the driver offers the basic
service to user programs.
Most drivers provide horizontal and vertical movement of the mouse
and state of up to three buttons at this level.
At the level one, if supported by the driver, mouse data is encoded
in the standard format
.Dv MOUSE_PROTO_SYSMOUSE
as follows:
.Pp
.Bl -tag -width Byte_1 -compact
.It Byte 1
.Bl -tag -width bit_7 -compact
.It bit 7
Always one.
.It bit 6..3
Always zero.
.It bit 2
Left button status; cleared if pressed, otherwise set.
.It bit 1
Middle button status; cleared if pressed, otherwise set. Always one,
if the device does not have the middle button.
.It bit 0
Right button status; cleared if pressed, otherwise set.
.El
.It Byte 2
The first half of horizontal movement count in two's compliment;
-128 through 127.
.It Byte 3
The first half of vertical movement count in two's compliment;
-128 through 127.
.It Byte 4
The second half of the horizontal movement count in two's compliment;
-128 through 127. To obtain the full horizontal movement count, add
the byte 2 and 4.
.It Byte 5
The second half of the vertical movement count in two's compliment;
-128 through 127. To obtain the full vertical movement count, add
the byte 3 and 5.
.It Byte 6
The bit 7 is always zero. The lower 7 bits encode the first half of
Z axis movement count in two's compliment; -64 through 63.
.It Byte 7
The bit 7 is always zero. The lower 7 bits encode the second half of
the Z axis movement count in two's compliment; -64 through 63.
To obtain the full Z axis movement count, add the byte 6 and 7.
.It Byte 8
The bit 7 is always zero. The bits 0 through 6 reflect the state
of the buttons 4 through 10.
If a button is pressed, the corresponding bit is cleared. Otherwise
the bit is set.
.El
.Pp
The first 5 bytes of this format is compatible with the MouseSystems
format. The additional 3 bytes have their MSBs always set to zero.
Thus, if the user program can interpret the MouseSystems data format and
tries to find the first byte of the format by detecting the bit pattern
10000xxxb,
it will discard the additional bytes, thus, be able to decode x, y
and states of 3 buttons correctly.
.Pp
Device drivers may offer operation levels higher than one.
Refer to manual pages of individual drivers for details.
.Sh IOCTLS
The following
.Xr ioctl 2
commands are defined for the mouse drivers. The degree of support
varies from one driver to another. This section gives general
description of the commands.
Refer to manual pages of individual drivers for specific details.
.Pp
.Bl -tag -width MOUSE -compact
.It Dv MOUSE_GETLEVEL Ar int *level
.It Dv MOUSE_SETLEVEL Ar int *level
These commands manipulate the operation level of the mouse driver.
.Pp
.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
Returns the hardware information of the attached device in the following
Except for the
.Dv iftype
field, the device driver may not always fill the structure with correct
values.
Consult manual pages of individual drivers for details of support.
.Bd -literal
typedef struct mousehw {
int buttons; /* number of buttons */
int iftype; /* I/F type */
int type; /* mouse/track ball/pad... */
int model; /* I/F dependent model ID */
int hwid; /* I/F dependent hardware ID */
} mousehw_t;
.Ed
.Pp
The
.Dv buttons
field holds the number of buttons detected by the driver. The driver
may put an arbitrary value, such as two, in this field, if it cannot
determine the exact number.
.Pp
The
.Dv iftype
is the type of interface:
.Dv MOUSE_IF_SERIAL ,
.Dv MOUSE_IF_BUS ,
.Dv MOUSE_IF_INPORT ,
.Dv MOUSE_IF_PS2 ,
.Dv MOUSE_IF_SYSMOUSE
or
.Dv MOUSE_IF_UNKNOWN .
.Pp
The
.Dv type
tells the device type:
.Dv MOUSE_MOUSE ,
.Dv MOUSE_TRACKBALL ,
.Dv MOUSE_STICK ,
.Dv MOUSE_PAD ,
or
.Dv MOUSE_UNKNOWN .
.Pp
The
.Dv model
may be
.Dv MOUSE_MODEL_GENERIC
or one of
.Dv MOUSE_MODEL_XXX
constants.
.Pp
The
.Dv hwid
is the ID value returned by the pointing device. It
depend on the interface type; refer to the manual page of
specific mouse drivers for possible values.
.Pp
.It Dv MOUSE_GETMODE Ar mousemode_t *mode
The command reports the current operation parameters of the mouse driver.
.Bd -literal
typedef struct mousemode {
int protocol; /* MOUSE_PROTO_XXX */
int rate; /* report rate (per sec) */
int resolution; /* MOUSE_RES_XXX, -1 if unknown */
int accelfactor; /* acceleration factor */
int level; /* driver operation level */
int packetsize; /* the length of the data packet */
unsigned char syncmask[2]; /* sync. bits */
} mousemode_t;
.Ed
.Pp
The
.Dv protocol
field tells the format in which the device status is returned
when the mouse data is read by the user program.
It is one of
.Dv MOUSE_PROTO_XXX
constants.
.Pp
The
.Dv rate
field is the status report rate (reports/sec) at which the device will send
movement reports to the host computer. -1 if unknown or not applicable.
.Pp
The
.Dv resolution
field holds a value specifying resolution of the pointing device.
It is a positive value or one of
.Dv MOUSE_RES_XXX
constants.
.Pp
The
.Dv accelfactor
field holds a value to control acceleration feature.
It must be zero or greater.
If it is zero, acceleration is disabled.
.Pp
The
.Dv packetsize
field tells the length of the fixed-size data packet or the length
of the fixed part of the variable-length packet.
The size depends on the interface type, the device type and model, the
protocol and the operation level of the driver.
.Pp
The array
.Dv syncmask
holds a bit mask and pattern to detect the first byte of the
data packet.
.Dv syncmask[0]
is the bit mask to be ANDed with a byte. If the result is equal to
.Dv syncmask[1] ,
the byte is likely to be the first byte of the data packet.
Note that this method of detecting the first byte is not 100% reliable,
thus, should be taken only as an advisory measure.
.Pp
.It Dv MOUSE_SETMODE Ar mousemode_t *mode
The command changes the current operation parameters of the mouse driver
as specified in
.Ar mode .
Only
.Dv rate ,
.Dv resolution ,
.Dv level
and
.Dv accelfactor
may be modifiable. Setting values in the other field does not generate
error and has no effect.
.Pp
If you do not want to change the current setting of a field, put -1
there.
You may also put zero in
.Dv resolution
and
.Dv rate ,
and the default value for the fields will be selected.
.\" .Pp
.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
.\" Get internal variables of the mouse driver.
.\" The variables which can be manipulated through these commands
.\" are specific to each driver.
.\" This command may not be supported by all drivers.
.\" .Bd -literal
.\" typedef struct mousevar {
.\" int var[16]; /* internal variables */
.\" } mousevar_t;
.\" .Ed
.\" .Pp
.\" If the commands are supported, the first element of the array is
.\" filled with a signature value.
.\" Apart from the signature data, there is currently no standard concerning
.\" the other elements of the buffer.
.\" .Pp
.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
.\" Get internal variables of the mouse driver.
.\" The first element of the array must be a signature value.
.\" This command may not be supported by all drivers.
.Pp
.It Dv MOUSE_READDATA Ar mousedata_t *data
The command reads the raw data from the device.
.Bd -literal
typedef struct mousedata {
int len; /* # of data in the buffer */
int buf[16]; /* data buffer */
} mousedata_t;
.Ed
.Pp
The calling process must fill the
.Dv len
field with the number of bytes to be read into the buffer.
This command may not be supported by all drivers.
.Pp
.It Dv MOUSE_READSTATE Ar mousedata_t *state
The command reads the raw state data from the device.
It uses the same structure as above.
This command may not be supported by all drivers.
.Pp
.It Dv MOUSE_GETSTATE Ar mousestatus_t *status
The command returns the current state of buttons and
movement counts in the following structure.
.Bd -literal
typedef struct mousestatus {
int flags; /* state change flags */
int button; /* button status */
int obutton; /* previous button status */
int dx; /* x movement */
int dy; /* y movement */
int dz; /* z movement */
} mousestatus_t;
.Ed
.Pp
The
.Dv button
and
.Dv obutton
fields hold the current and the previous state of the mouse buttons.
When a button is pressed, the corresponding bit is set.
The mouse drivers may support up to 31 buttons with the bit 0 through 31.
Few button bits are defined as
.Dv MOUSE_BUTTON1DOWN
through
.Dv MOUSE_BUTTON8DOWN .
The first three buttons correspond to left, middle and right buttons.
.Pp
If the state of the button has changed since the last
.Dv MOUSE_GETSTATE
call, the corresponding bit in the
.Dv flags
field will be set.
If the mouse has moved since the last call, the
.Dv MOUSE_POSCHANGED
bit in the
.Dv flags
field will also be set.
.Pp
The other fields hold movement counts since the last
.Dv MOUSE_GETSTATE
call. The internal counters will be reset after every call to this
command.
.El
.Sh FILES
.Bl -tag -width /dev/sysmouseXX -compact
.It Pa /dev/cuaa%d
serial ports
.It Pa /dev/mse%d
bus and InPort mouse device
.It Pa /dev/psm%d
PS/2 mouse device
.It Pa /dev/sysmouse
virtual mouse device
.El
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr mse 4 ,
.Xr psm 4 ,
.Xr sysmouse 4 ,
.Xr moused 8
.\".Sh HISTORY
.Sh AUTHOR
This manual page was written by
.An Kazutaka YOKOTA Aq yokota@FreeBSD.org .

348
share/man/man4/man4.i386/mse.4
View File

@ -10,26 +10,344 @@
.\" this software for any purpose. It is provided "as is"
.\" without express or implied warranty.
.\"
.\" $Id$
.\" $Id: mse.4,v 1.3 1997/03/07 02:49:53 jmg Exp $
.\"
.Dd Aug 16, 1992
.Dd December 3, 1997
.Dt MSE 4 i386
.Os
.Os FreeBSD
.Sh NAME
.Nm mse
.Nd bus mouse driver
.Nd bus and InPort mice driver
.Sh SYNOPSIS
.\" .Cd "options" \&"MSE_XXX=N\&"
.Cd "device mse0 at isa? port" 0x23c tty irq 5 vector mseintr
.Sh DESCRIPTION
This is a simple driver for the Logitech and ATI Inport bus mouse interfaces
designed to be used with the X386 X11R5 X server. The minor device number is
made up of:
The
.Nm
driver provides support for the bus mouse and the InPort mouse, which
are often collectively called ``bus'' mice, as these mice are sold with
an interface card which needs to be installed in an expansion bus slot.
The interface circuit may come on an integrated I/O card or as an option
on video cards.
.Pp
The bus and InPort mice have two or three buttons,
and a D-sub 9-pin male connector or a round DIN 9-pin
male connector.
.Pp
The primary port address of the bus and InPort mouse interface cards
is usually 0x23c. Some cards may also be set to use the secondary port
address at 0x238. The interface cards require a single IRQ, which may be
2, 3, 4 or 5. Some cards may offer additional IRQs.
The port number and the IRQ number are configured by jumpers on the cards
or by software provided with the card.
.Pp
Frequency, or report rate, at which the device sends movement
and button state reports to the host system, may also be configurable on
some interface cards. It may be 15, 30, 60 or 120Hz.
.Pp
The difference between the two types of the mice is not in mouse devices
(in fact they are exactly the same). But in the circuit on the interface
cards. This means that the device from a bus mouse package can be
connected to the interface card from an InPort mouse package, or vice
versa, provided that their connectors match.
.Ss Operation Levels
The
.Nm
driver has two levels of operation.
The current operation level can be set via an ioctl call.
.Pp
At the level zero the basic support is provided; the device driver will report
horizontal and vertical movement of the attached device
and state of up to three buttons in the format described below.
It is a subset of the MouseSystems protocol.
.Pp
.Bl -tag -width Byte_1 -compact
.It Byte 1
.Bl -tag -width bit_7 -compact
.It bit 7
Always one.
.It bit 6..3
Always zero.
.It bit 2
Left button status; cleared if pressed, otherwise set.
.It bit 1
Middle button status; cleared if pressed, otherwise set. Always one,
if the device does not have the middle button.
.It bit 0
Right button status; cleared if pressed, otherwise set.
.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.
.It Byte 4
Always zero.
.It Byte 5
Always zero.
.El
.Pp
This is the default level of operation and the driver is initially
at this level when opened by the user program.
.Pp
At the operation level one (extended level), a data packet is encoded
in the standard format
.Dv MOUSE_PROTO_SYSMOUSE
as defined in
.Xr mouse 4 .
.Ss Acceleration
The
.Nm
driver can somewhat `accelerate' the movement of the pointing device.
The faster you move the device, the further the pointer
travels on the screen.
The driver has an internal variable which governs the effect of
the acceleration. Its value can be modified via the driver flag
or via an ioctl call.
.Ss Device Number
The minor device number of the
.Nm
is made up of:
.Bd -literal -offset indent
minor = ('unit' << 1) | 'non-blocking'
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 0 instead".
The 'non-blocking' bit should be set for X386, therefore the minor device
number usually used for X386 is 1.
.Sh Caveats
Most bus mice generate N interrupts/second when enabled, whether or not the
mouse state is changing.
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.
See
.Sx FILES
for device node names.
.Sh DRIVER CONFIGURATION
.\" .Ss Kernel Configuration Options
.Ss Driver Flags
The
.Nm
driver accepts the following driver flag. Set it in the
kernel configuration file
.Pq see Xr config 8
or in the User Configuration Menu at
the boot time
.Pq see Xr boot 8 .
.Pp
.Bl -tag -width MOUSE
.It bit 4..7 ACCELERATION
This flag controls the amount of acceleration effect.
The smaller the value of this flag is, more sensitive the movement becomes.
The minimum value allowed, thus the value for the most sensitive setting,
is one. Setting this flag to zero will completely disables the
acceleration effect.
.El
.Sh IOCTLS
There are a few
.Xr ioctl 2
commands for mouse drivers.
These commands and related structures and constants are defined in
.Ao Pa machine/mouse.h Ac .
General description of the commands is given in
.Xr mouse 4 .
This section explains the features specific to the
.Nm
driver.
.Pp
.Bl -tag -width MOUSE -compact
.It Dv MOUSE_GETLEVEL Ar int *level
.It Dv MOUSE_SETLEVEL Ar int *level
These commands manipulate the operation level of the
.Nm
driver.
.Pp
.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
Returns the hardware information of the attached device in the following
structure.
Only the
.Dv iftype
field is guaranteed to be filled with the correct value by the current
version of the
.Nm
driver.
.Bd -literal
typedef struct mousehw {
int buttons; /* number of buttons */
int iftype; /* I/F type */
int type; /* mouse/track ball/pad... */
int model; /* I/F dependent model ID */
int hwid; /* I/F dependent hardware ID */
} mousehw_t;
.Ed
.Pp
The
.Dv buttons
field holds the number of buttons on the device.
.Pp
The
.Dv iftype
is either
.Dv MOUSE_IF_BUS
or
.Dv MOUSE_IF_INPORT .
.Pp
The
.Dv type
may be
.Dv MOUSE_MOUSE ,
.Dv MOUSE_TRACKBALL ,
.Dv MOUSE_STICK ,
.Dv MOUSE_PAD ,
or
.Dv MOUSE_UNKNOWN .
.Pp
The
.Dv model
is always
.Dv MOUSE_MODEL_GENERIC
at the operation level 0.
It may be
.Dv MOUSE_MODEL_GENERIC
or one of
.Dv MOUSE_MODEL_XXX
constants at higher operation levels.
.Pp
The
.Dv hwid
is always 0.
.Pp
.It Dv MOUSE_GETMODE Ar mousemode_t *mode
The command gets the current operation parameters of the mouse
driver.
.Bd -literal
typedef struct mousemode {
int protocol; /* MOUSE_PROTO_XXX */
int rate; /* report rate (per sec), -1 if unknown */
int resolution; /* MOUSE_RES_XXX, -1 if unknown */
int accelfactor; /* acceleration factor */
int level; /* driver operation level */
int packetsize; /* the length of the data packet */
unsigned char syncmask[2]; /* sync. bits */
} mousemode_t;
.Ed
.Pp
The
.Dv protocol
is either
.Dv MOUSE_PROTO_BUS
or
.Dv MOUSE_PROTO_INPORT
at the operation level zero.
.Dv MOUSE_PROTO_SYSMOUSE
at the operation level one.
.Pp
The
.Dv rate
is the status report rate (reports/sec) at which the device will send
movement report to the host computer.
As there is no standard to detect the current setting,
this field is always set to -1.
.Pp
The
.Dv resolution
is always set to -1.
.Pp
The
.Dv accelfactor
field holds a value to control acceleration feature
.Pq see Sx Acceleration .
It is zero or greater.
If it is zero, acceleration is disabled.
.Pp
The
.Dv packetsize
field specifies the length of the data packet. It depends on the
operation level.
.Pp
.Bl -tag -width level_0__ -compact
.It Em level 0
5 bytes
.It Em level 1
8 bytes
.El
.Pp
The array
.Dv syncmask
holds a bit mask and pattern to detect the first byte of the
data packet.
.Dv syncmask[0]
is the bit mask to be ANDed with a byte. If the result is equal to
.Dv syncmask[1] ,
the byte is likely to be the first byte of the data packet.
Note that this detection method is not 100% reliable,
thus, should be taken only as an advisory measure.
.Pp
Only
.Dv level
and
.Dv accelfactor
are modifiable by the
.Dv MOUSE_SETMODE
command.
Changing the other field doesn't cause error, but has no effect.
.Pp
.It Dv MOUSE_SETMODE Ar mousemode_t *mode
The command changes the current operation parameters of the mouse driver
as specified in
.Ar mode .
Only
.Dv level
and
.Dv accelfactor
may be modifiable. Setting values in the other field does not generate
error and has no effect.
.\" .Pp
.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
.\" These commands are not supported by the
.\" .Nm
.\" driver.
.Pp
.It Dv MOUSE_READDATA Ar mousedata_t *data
.It Dv MOUSE_READSTATE Ar mousedata_t *state
These commands are not supported by the
.Nm
driver.
.Pp
.It Dv MOUSE_GETSTATE Ar mousestatus_t *status
The command returns the current state of buttons and
movement counts as described in
.Xr mouse 4 .
.El
.Sh FILES
.Bl -tag -width /dev/nmse0 -compact
.It Pa /dev/mse0
`non-blocking' device node in the system without
.Em devfs ,
`blocking' under
.Em devfs .
.It Pa /dev/nmse0
`non-blocking' device node under
.Em devfs .
.El
.Sh EXAMPLE
.Dl "device mse0 at isa? port" 0x23c tty irq 5 vector mseintr
.Pp
Add the
.Nm
driver at the primary port address with the IRQ 5.
.Pp
.Dl "device mse1 at isa? port" 0x238 tty flags 0x30 irq 4 vector mseintr
.Pp
Define the
.Nm
driver at the secondary port address with the IRQ 4 and the acceleration
factor of 3.
.Sh CAVEAT
Some bus mouse interface cards generate interrupts at the fixed report rate
when enabled, whether or not the mouse state is changing.
The others generate interrupts only when the state is changing.
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr mouse 4 ,
.Xr psm 4 ,
.Xr sysmouse 4 ,
.Xr moused 8
.\".Sh HISTORY

654
share/man/man4/man4.i386/psm.4
View File

@ -1,6 +1,32 @@
.\" $Id: psm.4,v 1.8 1997/10/19 10:45:18 yokota Exp $
.\"
.Dd January 13, 1997
.\" Copyright (c) 1997
.\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id: psm.4,v 1.7 1997/02/22 13:25:39 peter Exp $
.\"
.Dd December 3, 1997
.Dt PSM 4 i386
.Os FreeBSD
.Sh NAME
@ -8,9 +34,6 @@
.Nd
PS/2 mouse style pointing device driver
.Sh SYNOPSIS
.Cd "options PSM_CHECKSYNC"
.\".Cd "options PSM_EMULATION"
.Cd "options" \&"PSM_ACCEL=N\&"
.Cd "options" \&"PSM_HOOKAPM\&"
.Cd "options" \&"PSM_RESETAFTERSUSPEND\&"
.Cd "options" \&"KBD_RESETDELAY=N\&"
@ -22,23 +45,79 @@ PS/2 mouse style pointing device driver
The
.Nm
driver provides support for the PS/2 mouse style pointing device.
Currently there can be only one
.Nm
device node in the system.
.Em port \&"IO_KBD\&"
and
.Em conflicts
are required,
as the PS/2 mouse port is located
at the auxiliary port of the keyboard controller, thus, the
at the auxiliary port of the keyboard controller; the
.Nm
driver has to share the same I/O ports with the keyboard driver.
Note also that there is currently no provision of changing the
.Em irq
number.
.Pp
A series of data packets is read from the
Basic PS/2 style pointing device has two or three buttons.
Some devices may have a roller or a wheel and/or additional buttons.
.Ss Device Resolution
The PS/2 style pointing device usually has several grades of resolution,
that is, sensitivity of movement. They are typically 25, 50, 100 and 200
pulse per inch. Some devices may have finer resolution.
The current resolution can be changed at runtime. The
.Nm
driver. A data packet from the PS/2 mouse style pointing device
is three bytes long:
driver allows the user to initially set the resolution
via the driver flag
.Pq see Sx DRIVER CONFIGURATION
or change it later via the
.Xr ioctl 2
command
.Dv MOUSE_SETMODE
.Pq see Sx IOCTLS .
.Ss Report Rate
Frequency, or report rate, at which the device sends movement
and button state reports to the host system is also configurable.
The PS/2 style pointing device typically supports 10, 20, 40, 60, 80, 100
and 200 reports per second.
60 or 100 appears to be the default value for many devices.
Note that when there is no movement and no button has changed its state,
the device won't send anything to the host system.
The report rate can be changed via an ioctl call.
.Ss Operation Levels
The
.Nm
driver has three levels of operation.
The current operation level can be set via an ioctl call.
.Pp
At the level zero the basic support is provided; the device driver will report
horizontal and vertical movement of the attached device
and state of up to three buttons.
The movement and status are encoded in a series of fixed-length data packets
.Pq see Sx Data Packet Format .
This is the default level of operation and the driver is initially
at this level when opened by the user program.
.Pp
The operation level one, the `extended' level, supports a roller (or wheel),
if any, and up to 11 buttons.
The movement of the roller is reported as movement along the Z axis.
8 byte data packets are sent to the user program at this level.
.Pp
At the operation level two, data from the pointing device is passed to the
user program as is.
Modern PS/2 type pointing devices often use proprietary data format.
Therefore, the user program is expected to have
intimate knowledge about the format from a particular device when operating
the driver at this level.
This level is called `native' level.
.Ss Data Packet Format
Data packets read from the
.Nm
driver are formatted differently at each operation level.
.Pp
A data packet from the PS/2 mouse style pointing device
is three bytes long at the operation level zero:
.Pp
.Bl -tag -width Byte_1 -compact
.It Byte 1
@ -52,12 +131,13 @@ Set if the vertical movement count is negative.
.It bit 4
Set if the horizontal movement count is negative.
.It bit 3
The ALPS GlidePoint clears this bit when the user `taps' the surface of
the pad, otherwise the bit is set.
Most, if not all, other devices always sets this bit.
Always one.
.\" The ALPS GlidePoint clears this bit when the user `taps' the surface of
.\" the pad, otherwise the bit is set.
.\" Most, if not all, other devices always set this bit.
.It bit 2
Middle button status; set if pressed. For devices without the middle
button, this bit seems to be always zero.
button, this bit is always zero.
.It bit 1
Right button status; set if pressed.
.It bit 0
@ -73,6 +153,24 @@ Vertical movement count in two's compliment;
Note that the sign bit is in the first byte.
.El
.Pp
At the level one, a data packet is encoded
in the standard format
.Dv MOUSE_PROTO_SYSMOUSE
as defined in
.Xr mouse 4 .
.Pp
At the level two, native level, there is no standard on the size and format
of the data packet.
.Ss Acceleration
The
.Nm
driver can somewhat `accelerate' the movement of the pointing device.
The faster you move the device, the further the pointer
travels on the screen.
The driver has an internal variable which governs the effect of
the acceleration. Its value can be modified via the driver flag
or via an ioctl call.
.Ss Device Number
The minor device number of the
.Nm
is made up of:
@ -88,48 +186,14 @@ therefore the minor device number usually used for \fIXFree86\fP is 1.
See
.Sx FILES
for device node names.
.Sh KERNEL CONFIGURATION
There are following options to control the
.Sh DRIVER CONFIGURATION
.Ss Kernel Configuration Options
There are following kernel configuration options to control the
.Nm
driver.
They may be set in the kernel configuration file
.Pq see Xr config 8 .
.Bl -tag -width MOUSE
.It Em PSM_CHECKSYNC
If this option is defined, the driver tries to detect the first byte of
the three-byte data packet, by checking the bit pattern of that byte.
This may be useful if you often experience wierd mouse movement
cased by unsynchronization between the application program and the mouse.
However, the
.Em PSM_CHECKSYNC
code may not always work; some systems, mostly notebooks, set the bit
pattern differently from the others.
Note also that the `tapping' feature of the ALPS GlidePoint will be
lost when this option is used.
.\".It Em PSM_EMULATION
.\"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 .
.\"To enable the emulation feature, define this option.
.It Em PSM_ACCEL=N
The
.Nm
driver can somewhat `accelerate' the movement of the pointing device.
That is, the faster you move the device, the further the pointer
travels on the screen. This option controls the amount of acceleration.
The smaller
.Fa N
is, more sensitive the movement becomes.
The minimum value allowed, thus the value for the most sensitive setting,
is 1. Setting this option to zero will completely disables the
acceleration effect. The default value is 0 (acceleration disabled).
The acceleration effect can also be controlled via the
.Fn ioctl
command
.Dv MOUSE_SETMODE .
.It Em PSM_HOOKAPM
The built-in PS/2 pointing device of some laptop computers is somehow
not operable immediately after the system `resumes' from
@ -175,70 +239,100 @@ The default debug level is zero. See
.Sx DIAGNOSTICS
for debug logging.
.El
.Sh IOCTL
There are only few ioctls for the
.Nm
driver. These are defined in
.Ao Pa machine/mouse.h Ac .
.Bl -tag -width MOUSE
.It Dv MOUSEIOCREAD
The
.Dv MOUSEIOCREAD
command did NOT work before and does NOT work now. It is obsolete.
Use the
.Dv MOUSE_GETSTATE
command instead.
.It Dv MOUSE_GETSTATE
The command returns the current mouse state in the following structure
and remove the state information from the internal queue.
.Bd -literal
typedef struct mousestatus {
int button; /* button status */
int obutton; /* previous button status */
int dx; /* x movement */
int dy; /* y movement */
} mousestatus_t;
.Ed
.Pp
.Ss Driver Flags
The
.Dv button
and the
.Dv obutton
fields hold the current and the previous state of the mouse buttons.
When a button is pressed, the corresponding bit is set.
These bits are defined as
.Dv MOUSE_BUTTON1DOWN
through
.Dv MOUSE_BUTTON8DOWN .
The first three buttons are left, middle and right buttons.
.Pp
Note that this command and
.Fn read
operation on the
.Nm
driver uses the same internal queue. Therefore, interleaving the
.Dv MOUSE_GETSTATE
command and
.Fn read
operation is not recommended.
.It Dv MOUSE_GETHWINFO
Returns the hardware information in the following structure.
driver accepts the following driver flags. Set them in the
kernel configuration file or in the User Configuration Menu at
the boot time
.Pq see Xr boot 8 .
.Pp
.Bl -tag -width MOUSE
.It bit 0..3 RESOLUTION
This flag specifies the resolution of the pointing device.
It must be zero through four. The greater the value
is, the finer resolution the device will select.
Actual resolution selected by this field varies according to the model
of the device. Typical resolutions are:
.Pp
.Bl -tag -width 0_(medium_high)__ -compact
.It Em 1 (low)
25 pulse per inch (ppi)
.It Em 2 (medium low)
50 ppi
.It Em 3 (medium high)
100 ppi
.It Em 4 (high)
200 ppi
.El
.Pp
Leaving this flag zero will selects the default resolution for the
device (whatever it is).
.It bit 4..7 ACCELERATION
This flag controls the amount of acceleration effect.
The smaller the value of this flag is, more sensitive the movement becomes.
The minimum value allowed, thus the value for the most sensitive setting,
is one. Setting this flag to zero will completely disables the
acceleration effect.
.It bit 8 NOCHECKSYNC
The
.Nm
driver tries to detect the first byte of the data packet by checking
the bit pattern of that byte. Although this method should work with most
PS/2 pointing devices, it may interfere with some devices which are not
so compatible with known devices.
If you think your pointing device is not functioning as expected,
see if disabling synchronization check will help by setting this flag.
.El
.Sh IOCTLS
There are a few
.Xr ioctl 2
commands for mouse drivers.
These commands and related structures and constants are defined in
.Ao Pa machine/mouse.h Ac .
General description of the commands is given in
.Xr mouse 4 .
This section explains the features specific to the
.Nm
driver.
.Pp
.Bl -tag -width MOUSE -compact
.It Dv MOUSE_GETLEVEL Ar int *level
.It Dv MOUSE_SETLEVEL Ar int *level
These commands manipulate the operation level of the
.Nm
driver.
.Pp
.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
Returns the hardware information of the attached device 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 model; /* I/F dependent model ID */
int hwid; /* I/F dependent hardware ID */
} mousehw_t;
.Ed
.Pp
The
.Dv iftype
is
.Dv MOUSE_IF_PS2
for the
.Dv buttons
field holds the number of buttons on the device.
The
.Nm
driver. The
driver currently 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
The
.Dv iftype
is always
.Dv MOUSE_IF_PS2 .
.Pp
The
.Dv type
tells the device type:
.Dv MOUSE_MOUSE ,
@ -248,73 +342,240 @@ tells the device type:
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.
.Pp
The
.Dv model
is always
.Dv MOUSE_MODEL_GENERIC
at the operation level 0.
It may be
.Dv MOUSE_MODEL_GENERIC
or one of
.Dv MOUSE_MODEL_XXX
constants at higher operation levels.
Again the
.Nm
driver may or may not set an appropriate value in this field.
.Pp
The
.Dv hwid
is the ID value returned by the pointing device.
is the ID value returned by the device.
Known IDs include:
.Pp
.Bl -tag -width 0__ -compact
.It Em 0
Mouse (Microsoft, Logitech and many other manufacturers)
.It Em 2
Microsoft Ballpoint mouse
.It Em 3
Microsoft IntelliMouse
.El
.It Dv MOUSE_GETMODE, MOUSE_SETMODE
The commands get and set the operation mode of the
.Nm
.Pp
.It Dv MOUSE_GETMODE Ar mousemode_t *mode
The command gets the current operation parameters of the mouse
driver.
.Bd -literal
typedef struct mousemode {
int protocol; /* MOUSE_PROTO_XXX */
int rate; /* report rate (per sec), -1 if unknown */
int resolution; /* 1:low, 2:medium low, 3:medium high
* 4:high, 0: default, -1 if unknown
*/
int accelfactor; /* acceleration factor (must be 1 or greater) */
int resolution; /* MOUSE_RES_XXX, -1 if unknown */
int accelfactor; /* acceleration factor */
int level; /* driver operation level */
int packetsize; /* the length of the data packet */
unsigned char syncmask[2]; /* sync. bits */
} 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 read by user
programs as is.
No other value is allowed at the moment.
.\"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.
.\"Note that the protocol cannot be set to anything other than
.\".Dv MOUSE_PROTO_PS2
.\"unless the
.\".Em PSM_EMULATION
.\"option is specified in the kernel configuration file.
is
.Dv MOUSE_PROTO_PS2
at the operation level zero and two.
.Dv MOUSE_PROTO_SYSMOUSE
at the operation level one.
.Pp
The
.Dv rate
is the status report rate (reports/sec) at which the device will send
movement report to the host computer.
Typical supported values are 10, 20, 40, 60, 80, 100 and 200.
Some mice may accept other arbitrary values too.
.Pp
The
.Dv resolution
of the pointing device must be zero through four. The higher the value
is, the finer resolution the mouse will select. Zero selects the
default resolution.
of the pointing device must be one of
.Dv MOUSE_RES_XXX
constants or a positive value. The greater the value
is, the finer resolution the mouse will select.
Actual resolution selected by the
.Dv MOUSE_RES_XXX
constant varies according to the model of mouse. Typical resolutions are:
.Pp
.Bl -tag -width MOUSE_RES_MEDIUMHIGH__ -compact
.It Dv MOUSE_RES_LOW
25 ppi
.It Dv MOUSE_RES_MEDIUMLOW
50 ppi
.It Dv MOUSE_RES_MEDIUMHIGH
100 ppi
.It Dv MOUSE_RES_HIGH
200 ppi
.El
.Pp
The
.Dv accelfactor
holds a value to control acceleration feature (see description on
.Em PSM_ACCEL
above). It must be zero or greater.
If it is zero, acceleration is disabled.
field holds a value to control acceleration feature
.Pq see Sx Acceleration .
It must be zero or greater. If it is zero, acceleration is disabled.
.Pp
The
.Dv packetsize
field specifies the length of the data packet. It depends on the
operation level and the model of the pointing device.
.Pp
.Bl -tag -width level_0__ -compact
.It Em level 0
3 bytes
.It Em level 1
8 bytes
.It Em level 2
Depends on the model of the device
.El
.Pp
The array
.Dv syncmask
holds a bit mask and pattern to detect the first byte of the
data packet.
.Dv syncmask[0]
is the bit mask to be ANDed with a byte. If the result is equal to
.Dv syncmask[1] ,
the byte is likely to be the first byte of the data packet.
Note that this detection method is not 100% reliable,
thus, should be taken only as an advisory measure.
.Pp
.It Dv MOUSE_SETMODE Ar mousemode_t *mode
The command changes the current operation parameters of the mouse driver
as specified in
.Ar mode .
Only
.Dv rate ,
.Dv resolution ,
.Dv level
and
.Dv accelfactor
may be modifiable. Setting values in the other field does not generate
error and has no effect.
.Pp
If you do not want to change the current setting of a field, put -1
there.
You may also put zero in
.Dv resolution
and
.Dv rate ,
and the default value for the fields will be selected.
.\" .Pp
.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
.\" These commands are not supported by the
.\" .Nm
.\" driver.
.Pp
.It Dv MOUSE_READDATA Ar mousedata_t *data
.\" The command reads the raw data from the device.
.\" .Bd -literal
.\" typedef struct mousedata {
.\" int len; /* # of data in the buffer */
.\" int buf[16]; /* data buffer */
.\" } mousedata_t;
.\" .Ed
.\" .Pp
.\" Upon returning to the user program, the driver will place the number
.\" of valid data bytes in the buffer in the
.\" .Dv len
.\" field.
.\" .Pp
.It Dv MOUSE_READSTATE Ar mousedata_t *state
.\" The command reads the hardware settings from the device.
.\" Upon returning to the user program, the driver will place the number
.\" of valid data bytes in the buffer in the
.\" .Dv len
.\" field. It is usually 3 bytes.
.\" The buffer is formatted as follows:
.\" .Pp
.\" .Bl -tag -width Byte_1 -compact
.\" .It Byte 1
.\" .Bl -tag -width bit_6 -compact
.\" .It bit 7
.\" Reserved.
.\" .It bit 6
.\" 0 - stream mode, 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.
.\" The
.\" .Nm
.\" driver puts the device in the stream mode.
.\" .It bit 5
.\" Set if the pointing device is currently enabled. Otherwise zero.
.\" .It bit 4
.\" 0 - 1:1 scaling, 1 - 2:1 scaling.
.\" 1:1 scaling is the default.
.\" .It bit 3
.\" Reserved.
.\" .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
.\" .Bl -tag -width bit_6_0 -compact
.\" .It bit 7
.\" Reserved.
.\" .It bit 6..0
.\" Resolution code: zero through three. Actual resolution for
.\" the resolution code varies from one device to another.
.\" .El
.\" .It Byte 3
.\" The status report rate (reports/sec) at which the device will send
.\" movement report to the host computer.
.\" .El
These commands are not currently supported by the
.Nm
driver.
.Pp
.It Dv MOUSE_GETSTATE Ar mousestatus_t *status
The command returns the current state of buttons and
movement counts as described in
.Xr mouse 4 .
.El
.Sh FILES
.Bl -tag -width /dev/npsm0 -compact
.It Pa /dev/psm0
`non-blocking' device node in the system without
.Em devfs ,
`blocking' under
.Em devfs .
.It Pa /dev/npsm0
`non-blocking' device node under
.Em devfs .
.El
.Sh EXAMPLE
.Dl "options" \&"PSM_HOOKAPM\&"
.Dl "device psm0 at isa? port" \&"IO_KBD\&" conflicts tty irq 12 vector psmintr
.Pp
Add the
.Nm
driver to the kernel with the optional code to stimulate the pointing device
after the `resume' event.
.Pp
.Dl "device psm0 at isa? port" \&"IO_KBD\&" conflicts tty flags 0x024 irq 12
.Dl vector psmintr
.Pp
Set the device resolution high (4) and the acceleration factor to 2.
.Sh DIAGNOSTICS
.Pp
At debug level 0, little information is logged except for the following
@ -332,23 +593,20 @@ for known IDs.
.Pp
At debug level 1 more information will be logged
while the driver probes the auxiliary port (mouse port).
Messages are logged with the LOG_KERN facility at the LOG_DEBUG level.
(See
.Xr syslogd 8 . )
Messages are logged with the LOG_KERN facility at the LOG_DEBUG level
.Pq see Xr syslogd 8 .
.Bd -literal -offset indent
psm0: current command byte:xxxx
kbdio: new command byte:yyyy (set_controller...)
kbdio: TEST_AUX_PORT status:0000
kbdio: RESET_AUX return code:00fa
kbdio: RESET_AUX status:00aa
kbdio: RESET_AUX ID:0000
psm0: status after reset 00 02 64
psm: device ID: X
psm: status xx yy zz (get_mouse_buttons)
psm0: status 00 02 64
kbdio: new command byte:zzzz (set_controller...)
[...]
psm: status 00 02 64
psm0 at 0x60-0x64 irq 12 on motherboard
psm0: device ID X, N buttons
psm0: model AAAA, device ID X, N buttons
psm0: config:00000www, flags:0000uuuu, packet size:M
psm0: syncmask:xx, syncbits:yy
.Ed
.Pp
The first line shows the command byte value of the keyboard
@ -356,17 +614,20 @@ controller just before the auxiliary port is probed.
It usually is 4D, 45, 47 or 65, depending on how the motherboard BIOS
initialized the keyboard controller upon power-up.
.Pp
The third line shows the result of the keyboard controller's
The second line shows the result of the keyboard controller's
test on the auxiliary 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 forth to sixth lines show the reset status of the pointing device.
The third through 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 tenth line shows the current hardware settings; it consists
of three bytes:
The seventh line shows the current hardware settings.
.\" See
.\" .Dv MOUSE_READSTATE
.\" for definitions.
These bytes are formatted as follows:
.Pp
.Bl -tag -width Byte_1 -compact
.It Byte 1
@ -378,10 +639,14 @@ Reserved.
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.
The
.Nm
driver puts the device in the stream mode.
.It bit 5
Set if the pointing device is currently enabled. Otherwise zero.
.It bit 4
0 - 1:1 scaling, 1 - 2:1 scaling.
1:1 scaling is the default.
.It bit 3
Reserved.
.It bit 2
@ -395,21 +660,9 @@ Right button status; set if pressed.
.Bl -tag -width bit_6_0 -compact
.It bit 7
Reserved.
.It bit 6-0
Resolution code: zero through three. The higher the number is,
the finer resolution the device has. Actual resolution for
.It bit 6..0
Resolution code: zero through three. Actual resolution for
the resolution code varies from one device to another.
The typical values are:
.Bl -tag -width 100 -compact
.It 0
25 pulse per inch (ppi)
.It 1
50 ppi
.It 2
100 ppi
.It 3
200 ppi
.El
.El
.It Byte 3
The status report rate (reports/sec) at which the device will send
@ -418,30 +671,22 @@ movement report to the host computer.
.Pp
Note that the pointing device will not be enabled until the
.Nm
driver is opened by the user programs.
driver is opened by the user program.
.Pp
The last line shows the device ID code and the number of detected
buttons. 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.
The rest of the lines show the device ID code, the number of detected
buttons and internal variables.
.Pp
At debug level 2, much more detailed information is logged.
.Sh FILES
.Bl -tag -width /dev/npsm0 -compact
.It Pa /dev/psm0
`non-blocking' device node in the system without
.Em devfs ,
`blocking' under
.Em devfs .
.It Pa /dev/npsm0
`non-blocking' device node under
.Em devfs .
.El
.Sh CAVEATS
Many pad devices behave as if the first (left) button were pressed if
the user `taps' the surface of the pad.
In contrast, some ALPS GlidePoint pad models treat the tapping action
as fourth button events.
.Pp
Some PS/2 mouse models from MouseSystems require to be put in the
high resolution mode to work properly. Use the driver flag to
set resolution.
.Pp
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. However, if you are using the \fIXFree86\fP server and experiencing
@ -449,22 +694,33 @@ the problem, you may be able to make the X server synchronize with the mouse
by switching away to a virtual terminal and getting back to the X server,
unless the X server is accessing the mouse via
.Xr moused 1 .
If you have specified the
.Em PSM_CHECKSYNC
option, clicking any button without moving the mouse may also work.
Clicking any button without moving the mouse may also work.
.Sh BUGS
The
.Fn ioctl
command
The ioctl command
.Dv MOUSEIOCREAD
(see
.Sx IOCTL
above) was never functional and will not be. The command name
still remains for compatibility reasons but may be removed in the future.
has been removed. It was never functional anyway.
.Sh SEE ALSO
.Xr moused 1 ,
.Xr ioctl 2 ,
.Xr syslog 3 ,
.Xr mouse 4 ,
.Xr mse 4 ,
.Xr sysmouse 4 ,
.Xr moused 8 ,
.Xr syslogd 8
.\" .Sh HISTORY
.\" .Sh AUTHOR
.\".Sh HISTORY
.Sh AUTHOR
The
.Nm
driver is based on the work done by quite a number of people, including
.An Eric Forsberg ,
.An Sandi Donno ,
.An Rick Macklem ,
.An Andrew Herbert ,
.An Charles Hannum ,
.An Shoji Yuen
and
.An Kazutaka YOKOTA
to name the few.
.Pp
This manual page was written by
.An Kazutaka YOKOTA Aq yokota@FreeBSD.org .

415
share/man/man4/man4.i386/sysmouse.4
View File

@ -25,51 +25,300 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $Id$
.\" $Id: sysmouse.4,v 1.5 1997/03/07 02:49:59 jmg Exp $
.\"
.Dd February 14, 1997
.Dd December 3, 1997
.Dt SYSMOUSE 4 i386
.Os
.Os FreeBSD
.Sh NAME
.Nm sysmouse
.Nd supplies mouse data from syscons for other applications
.\" .Nd supplies mouse data from syscons for other applications
.Nd virtualized mouse driver
.Sh SYNOPSIS
.Fd #include <machine/mouse.h>
.Fd #include <machine/console.h>
.Ft int
.Fn ioctl cfd CONS_MOUSECTL struct\ *mouse_info
.Sh DESCRIPTION
The console driver, in conjunction with the mouse daemon
.Xr moused 8 ,
supplies mouse data to the user process in the standardized way via the
.Nm
driver.
This arrangement makes it possible for the console and the user process
.Pq such as the Tn X\ Window System
to share the mouse.
.Pp
The user process which wants to utilize mouse operation simply opens
.Pa /dev/sysmouse
with a
.Xr open 2
call and reads
mouse data from the device via
.Xr read 2 .
Make sure that
.Xr moused 8
is running, otherwise the user process won't see any data coming from
the mouse.
.Pp
.Ss Operation Levels
The
.Dv CONS_MOUSECTL
.Nm
driver has two levels of operation.
The current operation level can be referred to and changed via ioctl calls.
.Pp
The level zero, the basic level, is the lowest level at which the driver
offers the basic service to user programs.
The
.Nm
driver
provides horizontal and vertical movement of the mouse
and state of up to three buttons in the
.Tn MouseSystems
format as follows.
.Pp
.Bl -tag -width Byte_1 -compact
.It Byte 1
.Bl -tag -width bit_7 -compact
.It bit 7
Always one.
.It bit 6..3
Always zero.
.It bit 2
Left button status; cleared if pressed, otherwise set.
.It bit 1
Middle button status; cleared if pressed, otherwise set. Always one,
if the device does not have the middle button.
.It bit 0
Right button status; cleared if pressed, otherwise set.
.El
.It Byte 2
The first half of horizontal movement count in two's compliment;
-128 through 127.
.It Byte 3
The first half of vertical movement count in two's compliment;
-128 through 127.
.It Byte 4
The second half of the horizontal movement count in two's compliment;
-128 through 127. To obtain the full horizontal movement count, add
the byte 2 and 4.
.It Byte 5
The second half of the vertical movement count in two's compliment;
-128 through 127. To obtain the full vertical movement count, add
the byte 3 and 5.
.El
.Pp
At the level one, the extended level, mouse data is encoded
in the standard format
.Dv MOUSE_PROTO_SYSMOUSE
as defined in
.Xr mouse 4 .
.\" .Ss Acceleration
.\" The
.\" .Nm
.\" driver can somewhat `accelerate' the movement of the pointing device.
.\" The faster you move the device, the further the pointer
.\" travels on the screen.
.\" The driver has an internal variable which governs the effect of
.\" the acceleration. Its value can be modified via the driver flag
.\" or via an ioctl call.
.Sh IOCTLS
This section describes two classes of
.Xr ioctl 2
commands:
commands for the
.Nm
driver itself, and commands for the console and the console control drivers.
.Ss Sysmouse Ioctls
There are a few commands for mouse drivers.
General description of the commands is given in
.Xr mouse 4 .
Followings are the features specific to the
.Nm
driver.
.Pp
.Bl -tag -width MOUSE -compact
.It Dv MOUSE_GETLEVEL Ar int *level
.It Dv MOUSE_SETLEVEL Ar int *level
These commands manipulate the operation level of the mouse driver.
.Pp
.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
Returns the hardware information of the attached device in the following
structure. Only the
.Dv iftype
field is guaranteed to be filled with the correct value in the current
version of the
.Nm
driver.
.Bd -literal
typedef struct mousehw {
int buttons; /* number of buttons */
int iftype; /* I/F type */
int type; /* mouse/track ball/pad... */
int model; /* I/F dependent model ID */
int hwid; /* I/F dependent hardware ID */
} mousehw_t;
.Ed
.Pp
The
.Dv buttons
field holds the number of buttons detected by the driver.
.Pp
The
.Dv iftype
is always
.Dv MOUSE_IF_SYSMOUSE.
.Pp
The
.Dv type
tells the device type:
.Dv MOUSE_MOUSE ,
.Dv MOUSE_TRACKBALL ,
.Dv MOUSE_STICK ,
.Dv MOUSE_PAD ,
or
.Dv MOUSE_UNKNOWN .
.Pp
The
.Dv model
is always
.Dv MOUSE_MODEL_GENERIC
at the operation level 0.
It may be
.Dv MOUSE_MODEL_GENERIC
or one of
.Dv MOUSE_MODEL_XXX
constants at higher operation levels.
.Pp
The
.Dv hwid
is always zero.
.Pp
.It Dv MOUSE_GETMODE Ar mousemode_t *mode
The command gets the current operation parameters of the mouse
driver.
.Bd -literal
typedef struct mousemode {
int protocol; /* MOUSE_PROTO_XXX */
int rate; /* report rate (per sec) */
int resolution; /* MOUSE_RES_XXX, -1 if unknown */
int accelfactor; /* acceleration factor */
int level; /* driver operation level */
int packetsize; /* the length of the data packet */
unsigned char syncmask[2]; /* sync. bits */
} mousemode_t;
.Ed
.Pp
The
.Dv protocol
field tells the format in which the device status is returned
when the mouse data is read by the user program.
It is
.Dv MOUSE_PROTO_MSC
at the operation level zero.
.Dv MOUSE_PROTO_SYSMOUSE
at the operation level one.
.Pp
The
.Dv rate
is always set to -1.
.Pp
The
.Dv resolution
is always set to -1.
.Pp
The
.Dv accelfactor
is always 0.
.Pp
The
.Dv packetsize
field specifies the length of the data packet. It depends on the
operation level.
.Pp
.Bl -tag -width level_0__ -compact
.It Em level 0
5 bytes
.It Em level 1
8 bytes
.El
.Pp
The array
.Dv syncmask
holds a bit mask and pattern to detect the first byte of the
data packet.
.Dv syncmask[0]
is the bit mask to be ANDed with a byte. If the result is equal to
.Dv syncmask[1] ,
the byte is likely to be the first byte of the data packet.
Note that this method of detecting the first byte is not 100% reliable,
thus, should be taken only as an advisory measure.
.Pp
.It Dv MOUSE_SETMODE Ar mousemode_t *mode
The command changes the current operation parameters of the mouse driver
as specified in
.Ar mode .
Only
.Dv level
may be modifiable. Setting values in the other field does not generate
error and has no effect.
.\" .Pp
.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
.\" These commands are not supported by the
.\" .Nm
.\" driver.
.Pp
.It Dv MOUSE_READDATA Ar mousedata_t *data
.It Dv MOUSE_READSTATE Ar mousedata_t *state
These commands are not supported by the
.Nm
driver.
.Pp
.It Dv MOUSE_GETSTATE Ar mousestatus_t *status
The command returns the current state of buttons and
movement counts in the structure as defined in
.Xr mouse 4 .
.El
.Ss Console and Consolectl Ioctls
The user process issues console
.Fn ioctl
call provides syscons with mouse information, which includes mouse movement
and button presses. The
.Fn ioctl
also provides a method for a process to receive a
calls to the current virtual console in order to control
the mouse pointer.
The console
.Fn ioctl
also provides a method for the user process to receive a
.Xr signal 3
when a button is pressed.
.Pp
The mouse daemon
.Xr moused 8
uses this
uses
.Fn ioctl
to inform the console of mouse actions. Applications
.Pq such as Tn X\ Windows
can use
.Pa /dev/sysmouse ,
allowing syscons and the application to share the mouse.
calls to the console control device
.Pa /dev/consolectl
to inform the console of mouse actions including mouse movement
and button status.
.Pp
.Bd -literal -offset indent
Both classes
.Fn ioctl
commands are defined as
.Dv CONS_MOUSECTL
which takes the following argument.
.Bd -literal
struct mouse_info {
int operation;
union {
struct mouse_data data;
struct mouse_mode mode;
}u;
int operation;
union {
struct mouse_data data;
struct mouse_mode mode;
struct mouse_event event;
} u;
};
.Ed
.Bl -tag -width operation
.Pp
.Bl -tag -width operation -compact
.It Dv operation
This can be one of
.Bl -tag -width MOUSE_MOVEABS
.Pp
.Bl -tag -width MOUSE_MOVEABS -compact
.It Dv MOUSE_SHOW
Enables and displays mouse cursor.
.It Dv MOUSE_HIDE
@ -78,11 +327,12 @@ Disables and hides mouse cursor.
Moves mouse cursor to position supplied in
.Dv u.data .
.It Dv MOUSE_MOVEREL
Add position supplied in
Adds position supplied in
.Dv u.data
to current position.
.It Dv MOUSE_GETINFO
Returns current mouse position and button status in
Returns current mouse position in the current virtual console
and button status in
.Dv u.data .
.It Dv MOUSE_MODE
This sets the
@ -90,34 +340,99 @@ This sets the
to be delivered to the current process when a button is pressed.
The signal to be delivered is set in
.Dv u.mode .
.It Dv MOUSE_ACTION
This takes the information in
.Dv u.data
and acts upon it. It includes processing button presses if the current vty
is a text interface, and sending
.Tn Mouse System
protocol data to
.Pa /dev/sysmouse
if it is open.
.El
.Pp
The above operations are for virtual consoles. The operations defined
below are for the console control device and used by
.Xr moused 8
to pass mouse data to the console driver.
.Pp
.Bl -tag -width MOUSE_MOVEABS -compact
.It Dv MOUSE_ACTION
.It Dv MOUSE_MOTIONEVENT
These operations take the information in
.Dv u.data
and act upon it. Mouse data will be sent to the
.Nm
driver if it is open.
.Dv MOUSE_ACTION
also processes button press actions and sends signal to the process if
requested or performs cut and paste operations
if the current console is a text interface.
.It Dv MOUSE_BUTTONEVENT
.Dv u.data
specifies a button and its click count. The console driver will
use this information for signal delivery if requested or
for cut and paste operations if the console is in text mode.
.El
.Pp
.Dv MOUSE_MOTIONEVENT
and
.Dv MOUSE_BUTTONEVENT
are newer interface and are designed to be used together.
They are intended to replace functions performed by
.Dv MOUSE_ACTION
alone.
.Pp
.It Dv u
This union is one of
.Bl -tag -width data
.Pp
.Bl -tag -width data -compact
.It Dv data
.Bd -literal -offset indent
.Bd -literal
struct mouse_data {
int x;
int y;
int buttons;
int x;
int y;
int z;
int buttons;
};
.Ed
.Pp
.Dv x ,
.Dv y
and
.Dv z
represent movement of the mouse along respective directions.
.Dv buttons
tells the state of buttons. It encodes up to 31 buttons in the bit 0 though
the bit 30. If a button is held down, the corresponding bit is set.
.Pp
.It Dv mode
.Bd -literal -offset indent
.Bd -literal
struct mouse_mode {
int mode;
int signal;
int mode;
int signal;
};
.Ed
.Pp
The
.Dv signal
field specifies the signal to be delivered to the process. It must be
one of the values defined in
.Ao Pa signal.h Ac .
The
.Dv mode
field is currently unused.
.Pp
.It Dv event
.Bd -literal
struct mouse_event {
int id;
int value;
};
.Ed
.Pp
The
.Dv id
field specifies a button number as in
.Dv u.data.buttons .
Only one bit/button is set.
The
.Dv value
field
holds the click count: the number of times the user has clicked the button
successively.
.Pp
.El
.El
.Sh FILES
@ -125,11 +440,15 @@ struct mouse_mode {
.It Pa /dev/consolectl
device to control the console
.It Pa /dev/sysmouse
mouse action output
virtualized mouse driver
.It Pa /dev/ttyv%d
virtual consoles
.El
.Sh SEE ALSO
.Xr vidcontrol 1 ,
.Xr ioctl 2 ,
.Xr signal 3 ,
.Xr mouse 4 ,
.Xr moused 8
.Sh HISTORY
The
@ -138,5 +457,7 @@ manual page example first appeared in
.Fx 2.2 .
.Sh AUTHOR
This
manual page was written by John-Mark Gurney
.Aq gurney_j@efn.org .
manual page was written by
.An John-Mark Gurney Aq gurney_j@efn.org
and
.An Kazutaka YOKOTA Aq yokota@FreeBSD.org .

382
share/man/man4/mouse.4 Normal file
View File

@ -0,0 +1,382 @@
.\"
.\" Copyright (c) 1997
.\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id:$
.\"
.Dd December 3, 1997
.Dt MOUSE 4 i386
.Os FreeBSD
.Sh NAME
.Nm mouse
.Nd mouse and pointing device drivers
.Sh SYNOPSIS
.Fd #include <machine/mouse.h>
.Sh DESCRIPTION
The mouse drivers
.Xr mse 4 ,
.Xr psm 4
and
.Xr sysmouse 4
provide user programs with movement and button state information of the mouse.
Currently there are specific device drivers for bus, InPort and PS/2 mice.
The serial mouse is not directly supported by a dedicated driver, but
it is accessible via the serial device driver or via
.Xr moused 8
and
.Xr sysmouse 4 .
.Pp
The user program simply opens a mouse device with a
.Xr open 2
call and reads
mouse data from the device via
.Xr read 2 .
Movement and button states are usually encoded in fixed-length data packets.
Some mouse devices may send data in variable length of packets.
Actual protocol (data format) used by each driver differs widely.
.Pp
The mouse drivers may have ``non-blocking'' attribute which will make
the driver return immediately if mouse data is not available.
.Pp
Mouse device drivers often offer several levels of operation.
The current operation level can be examined and changed via
.Xr ioctl 2
commands.
The level zero is the lowest level at which the driver offers the basic
service to user programs.
Most drivers provide horizontal and vertical movement of the mouse
and state of up to three buttons at this level.
At the level one, if supported by the driver, mouse data is encoded
in the standard format
.Dv MOUSE_PROTO_SYSMOUSE
as follows:
.Pp
.Bl -tag -width Byte_1 -compact
.It Byte 1
.Bl -tag -width bit_7 -compact
.It bit 7
Always one.
.It bit 6..3
Always zero.
.It bit 2
Left button status; cleared if pressed, otherwise set.
.It bit 1
Middle button status; cleared if pressed, otherwise set. Always one,
if the device does not have the middle button.
.It bit 0
Right button status; cleared if pressed, otherwise set.
.El
.It Byte 2
The first half of horizontal movement count in two's compliment;
-128 through 127.
.It Byte 3
The first half of vertical movement count in two's compliment;
-128 through 127.
.It Byte 4
The second half of the horizontal movement count in two's compliment;
-128 through 127. To obtain the full horizontal movement count, add
the byte 2 and 4.
.It Byte 5
The second half of the vertical movement count in two's compliment;
-128 through 127. To obtain the full vertical movement count, add
the byte 3 and 5.
.It Byte 6
The bit 7 is always zero. The lower 7 bits encode the first half of
Z axis movement count in two's compliment; -64 through 63.
.It Byte 7
The bit 7 is always zero. The lower 7 bits encode the second half of
the Z axis movement count in two's compliment; -64 through 63.
To obtain the full Z axis movement count, add the byte 6 and 7.
.It Byte 8
The bit 7 is always zero. The bits 0 through 6 reflect the state
of the buttons 4 through 10.
If a button is pressed, the corresponding bit is cleared. Otherwise
the bit is set.
.El
.Pp
The first 5 bytes of this format is compatible with the MouseSystems
format. The additional 3 bytes have their MSBs always set to zero.
Thus, if the user program can interpret the MouseSystems data format and
tries to find the first byte of the format by detecting the bit pattern
10000xxxb,
it will discard the additional bytes, thus, be able to decode x, y
and states of 3 buttons correctly.
.Pp
Device drivers may offer operation levels higher than one.
Refer to manual pages of individual drivers for details.
.Sh IOCTLS
The following
.Xr ioctl 2
commands are defined for the mouse drivers. The degree of support
varies from one driver to another. This section gives general
description of the commands.
Refer to manual pages of individual drivers for specific details.
.Pp
.Bl -tag -width MOUSE -compact
.It Dv MOUSE_GETLEVEL Ar int *level
.It Dv MOUSE_SETLEVEL Ar int *level
These commands manipulate the operation level of the mouse driver.
.Pp
.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
Returns the hardware information of the attached device in the following
Except for the
.Dv iftype
field, the device driver may not always fill the structure with correct
values.
Consult manual pages of individual drivers for details of support.
.Bd -literal
typedef struct mousehw {
int buttons; /* number of buttons */
int iftype; /* I/F type */
int type; /* mouse/track ball/pad... */
int model; /* I/F dependent model ID */
int hwid; /* I/F dependent hardware ID */
} mousehw_t;
.Ed
.Pp
The
.Dv buttons
field holds the number of buttons detected by the driver. The driver
may put an arbitrary value, such as two, in this field, if it cannot
determine the exact number.
.Pp
The
.Dv iftype
is the type of interface:
.Dv MOUSE_IF_SERIAL ,
.Dv MOUSE_IF_BUS ,
.Dv MOUSE_IF_INPORT ,
.Dv MOUSE_IF_PS2 ,
.Dv MOUSE_IF_SYSMOUSE
or
.Dv MOUSE_IF_UNKNOWN .
.Pp
The
.Dv type
tells the device type:
.Dv MOUSE_MOUSE ,
.Dv MOUSE_TRACKBALL ,
.Dv MOUSE_STICK ,
.Dv MOUSE_PAD ,
or
.Dv MOUSE_UNKNOWN .
.Pp
The
.Dv model
may be
.Dv MOUSE_MODEL_GENERIC
or one of
.Dv MOUSE_MODEL_XXX
constants.
.Pp
The
.Dv hwid
is the ID value returned by the pointing device. It
depend on the interface type; refer to the manual page of
specific mouse drivers for possible values.
.Pp
.It Dv MOUSE_GETMODE Ar mousemode_t *mode
The command reports the current operation parameters of the mouse driver.
.Bd -literal
typedef struct mousemode {
int protocol; /* MOUSE_PROTO_XXX */
int rate; /* report rate (per sec) */
int resolution; /* MOUSE_RES_XXX, -1 if unknown */
int accelfactor; /* acceleration factor */
int level; /* driver operation level */
int packetsize; /* the length of the data packet */
unsigned char syncmask[2]; /* sync. bits */
} mousemode_t;
.Ed
.Pp
The
.Dv protocol
field tells the format in which the device status is returned
when the mouse data is read by the user program.
It is one of
.Dv MOUSE_PROTO_XXX
constants.
.Pp
The
.Dv rate
field is the status report rate (reports/sec) at which the device will send
movement reports to the host computer. -1 if unknown or not applicable.
.Pp
The
.Dv resolution
field holds a value specifying resolution of the pointing device.
It is a positive value or one of
.Dv MOUSE_RES_XXX
constants.
.Pp
The
.Dv accelfactor
field holds a value to control acceleration feature.
It must be zero or greater.
If it is zero, acceleration is disabled.
.Pp
The
.Dv packetsize
field tells the length of the fixed-size data packet or the length
of the fixed part of the variable-length packet.
The size depends on the interface type, the device type and model, the
protocol and the operation level of the driver.
.Pp
The array
.Dv syncmask
holds a bit mask and pattern to detect the first byte of the
data packet.
.Dv syncmask[0]
is the bit mask to be ANDed with a byte. If the result is equal to
.Dv syncmask[1] ,
the byte is likely to be the first byte of the data packet.
Note that this method of detecting the first byte is not 100% reliable,
thus, should be taken only as an advisory measure.
.Pp
.It Dv MOUSE_SETMODE Ar mousemode_t *mode
The command changes the current operation parameters of the mouse driver
as specified in
.Ar mode .
Only
.Dv rate ,
.Dv resolution ,
.Dv level
and
.Dv accelfactor
may be modifiable. Setting values in the other field does not generate
error and has no effect.
.Pp
If you do not want to change the current setting of a field, put -1
there.
You may also put zero in
.Dv resolution
and
.Dv rate ,
and the default value for the fields will be selected.
.\" .Pp
.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
.\" Get internal variables of the mouse driver.
.\" The variables which can be manipulated through these commands
.\" are specific to each driver.
.\" This command may not be supported by all drivers.
.\" .Bd -literal
.\" typedef struct mousevar {
.\" int var[16]; /* internal variables */
.\" } mousevar_t;
.\" .Ed
.\" .Pp
.\" If the commands are supported, the first element of the array is
.\" filled with a signature value.
.\" Apart from the signature data, there is currently no standard concerning
.\" the other elements of the buffer.
.\" .Pp
.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
.\" Get internal variables of the mouse driver.
.\" The first element of the array must be a signature value.
.\" This command may not be supported by all drivers.
.Pp
.It Dv MOUSE_READDATA Ar mousedata_t *data
The command reads the raw data from the device.
.Bd -literal
typedef struct mousedata {
int len; /* # of data in the buffer */
int buf[16]; /* data buffer */
} mousedata_t;
.Ed
.Pp
The calling process must fill the
.Dv len
field with the number of bytes to be read into the buffer.
This command may not be supported by all drivers.
.Pp
.It Dv MOUSE_READSTATE Ar mousedata_t *state
The command reads the raw state data from the device.
It uses the same structure as above.
This command may not be supported by all drivers.
.Pp
.It Dv MOUSE_GETSTATE Ar mousestatus_t *status
The command returns the current state of buttons and
movement counts in the following structure.
.Bd -literal
typedef struct mousestatus {
int flags; /* state change flags */
int button; /* button status */
int obutton; /* previous button status */
int dx; /* x movement */
int dy; /* y movement */
int dz; /* z movement */
} mousestatus_t;
.Ed
.Pp
The
.Dv button
and
.Dv obutton
fields hold the current and the previous state of the mouse buttons.
When a button is pressed, the corresponding bit is set.
The mouse drivers may support up to 31 buttons with the bit 0 through 31.
Few button bits are defined as
.Dv MOUSE_BUTTON1DOWN
through
.Dv MOUSE_BUTTON8DOWN .
The first three buttons correspond to left, middle and right buttons.
.Pp
If the state of the button has changed since the last
.Dv MOUSE_GETSTATE
call, the corresponding bit in the
.Dv flags
field will be set.
If the mouse has moved since the last call, the
.Dv MOUSE_POSCHANGED
bit in the
.Dv flags
field will also be set.
.Pp
The other fields hold movement counts since the last
.Dv MOUSE_GETSTATE
call. The internal counters will be reset after every call to this
command.
.El
.Sh FILES
.Bl -tag -width /dev/sysmouseXX -compact
.It Pa /dev/cuaa%d
serial ports
.It Pa /dev/mse%d
bus and InPort mouse device
.It Pa /dev/psm%d
PS/2 mouse device
.It Pa /dev/sysmouse
virtual mouse device
.El
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr mse 4 ,
.Xr psm 4 ,
.Xr sysmouse 4 ,
.Xr moused 8
.\".Sh HISTORY
.Sh AUTHOR
This manual page was written by
.An Kazutaka YOKOTA Aq yokota@FreeBSD.org .

654
share/man/man4/psm.4
View File

@ -1,6 +1,32 @@
.\" $Id: psm.4,v 1.8 1997/10/19 10:45:18 yokota Exp $
.\"
.Dd January 13, 1997
.\" Copyright (c) 1997
.\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id: psm.4,v 1.7 1997/02/22 13:25:39 peter Exp $
.\"
.Dd December 3, 1997
.Dt PSM 4 i386
.Os FreeBSD
.Sh NAME
@ -8,9 +34,6 @@
.Nd
PS/2 mouse style pointing device driver
.Sh SYNOPSIS
.Cd "options PSM_CHECKSYNC"
.\".Cd "options PSM_EMULATION"
.Cd "options" \&"PSM_ACCEL=N\&"
.Cd "options" \&"PSM_HOOKAPM\&"
.Cd "options" \&"PSM_RESETAFTERSUSPEND\&"
.Cd "options" \&"KBD_RESETDELAY=N\&"
@ -22,23 +45,79 @@ PS/2 mouse style pointing device driver
The
.Nm
driver provides support for the PS/2 mouse style pointing device.
Currently there can be only one
.Nm
device node in the system.
.Em port \&"IO_KBD\&"
and
.Em conflicts
are required,
as the PS/2 mouse port is located
at the auxiliary port of the keyboard controller, thus, the
at the auxiliary port of the keyboard controller; the
.Nm
driver has to share the same I/O ports with the keyboard driver.
Note also that there is currently no provision of changing the
.Em irq
number.
.Pp
A series of data packets is read from the
Basic PS/2 style pointing device has two or three buttons.
Some devices may have a roller or a wheel and/or additional buttons.
.Ss Device Resolution
The PS/2 style pointing device usually has several grades of resolution,
that is, sensitivity of movement. They are typically 25, 50, 100 and 200
pulse per inch. Some devices may have finer resolution.
The current resolution can be changed at runtime. The
.Nm
driver. A data packet from the PS/2 mouse style pointing device
is three bytes long:
driver allows the user to initially set the resolution
via the driver flag
.Pq see Sx DRIVER CONFIGURATION
or change it later via the
.Xr ioctl 2
command
.Dv MOUSE_SETMODE
.Pq see Sx IOCTLS .
.Ss Report Rate
Frequency, or report rate, at which the device sends movement
and button state reports to the host system is also configurable.
The PS/2 style pointing device typically supports 10, 20, 40, 60, 80, 100
and 200 reports per second.
60 or 100 appears to be the default value for many devices.
Note that when there is no movement and no button has changed its state,
the device won't send anything to the host system.
The report rate can be changed via an ioctl call.
.Ss Operation Levels
The
.Nm
driver has three levels of operation.
The current operation level can be set via an ioctl call.
.Pp
At the level zero the basic support is provided; the device driver will report
horizontal and vertical movement of the attached device
and state of up to three buttons.
The movement and status are encoded in a series of fixed-length data packets
.Pq see Sx Data Packet Format .
This is the default level of operation and the driver is initially
at this level when opened by the user program.
.Pp
The operation level one, the `extended' level, supports a roller (or wheel),
if any, and up to 11 buttons.
The movement of the roller is reported as movement along the Z axis.
8 byte data packets are sent to the user program at this level.
.Pp
At the operation level two, data from the pointing device is passed to the
user program as is.
Modern PS/2 type pointing devices often use proprietary data format.
Therefore, the user program is expected to have
intimate knowledge about the format from a particular device when operating
the driver at this level.
This level is called `native' level.
.Ss Data Packet Format
Data packets read from the
.Nm
driver are formatted differently at each operation level.
.Pp
A data packet from the PS/2 mouse style pointing device
is three bytes long at the operation level zero:
.Pp
.Bl -tag -width Byte_1 -compact
.It Byte 1
@ -52,12 +131,13 @@ Set if the vertical movement count is negative.
.It bit 4
Set if the horizontal movement count is negative.
.It bit 3
The ALPS GlidePoint clears this bit when the user `taps' the surface of
the pad, otherwise the bit is set.
Most, if not all, other devices always sets this bit.
Always one.
.\" The ALPS GlidePoint clears this bit when the user `taps' the surface of
.\" the pad, otherwise the bit is set.
.\" Most, if not all, other devices always set this bit.
.It bit 2
Middle button status; set if pressed. For devices without the middle
button, this bit seems to be always zero.
button, this bit is always zero.
.It bit 1
Right button status; set if pressed.
.It bit 0
@ -73,6 +153,24 @@ Vertical movement count in two's compliment;
Note that the sign bit is in the first byte.
.El
.Pp
At the level one, a data packet is encoded
in the standard format
.Dv MOUSE_PROTO_SYSMOUSE
as defined in
.Xr mouse 4 .
.Pp
At the level two, native level, there is no standard on the size and format
of the data packet.
.Ss Acceleration
The
.Nm
driver can somewhat `accelerate' the movement of the pointing device.
The faster you move the device, the further the pointer
travels on the screen.
The driver has an internal variable which governs the effect of
the acceleration. Its value can be modified via the driver flag
or via an ioctl call.
.Ss Device Number
The minor device number of the
.Nm
is made up of:
@ -88,48 +186,14 @@ therefore the minor device number usually used for \fIXFree86\fP is 1.
See
.Sx FILES
for device node names.
.Sh KERNEL CONFIGURATION
There are following options to control the
.Sh DRIVER CONFIGURATION
.Ss Kernel Configuration Options
There are following kernel configuration options to control the
.Nm
driver.
They may be set in the kernel configuration file
.Pq see Xr config 8 .
.Bl -tag -width MOUSE
.It Em PSM_CHECKSYNC
If this option is defined, the driver tries to detect the first byte of
the three-byte data packet, by checking the bit pattern of that byte.
This may be useful if you often experience wierd mouse movement
cased by unsynchronization between the application program and the mouse.
However, the
.Em PSM_CHECKSYNC
code may not always work; some systems, mostly notebooks, set the bit
pattern differently from the others.
Note also that the `tapping' feature of the ALPS GlidePoint will be
lost when this option is used.
.\".It Em PSM_EMULATION
.\"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 .
.\"To enable the emulation feature, define this option.
.It Em PSM_ACCEL=N
The
.Nm
driver can somewhat `accelerate' the movement of the pointing device.
That is, the faster you move the device, the further the pointer
travels on the screen. This option controls the amount of acceleration.
The smaller
.Fa N
is, more sensitive the movement becomes.
The minimum value allowed, thus the value for the most sensitive setting,
is 1. Setting this option to zero will completely disables the
acceleration effect. The default value is 0 (acceleration disabled).
The acceleration effect can also be controlled via the
.Fn ioctl
command
.Dv MOUSE_SETMODE .
.It Em PSM_HOOKAPM
The built-in PS/2 pointing device of some laptop computers is somehow
not operable immediately after the system `resumes' from
@ -175,70 +239,100 @@ The default debug level is zero. See
.Sx DIAGNOSTICS
for debug logging.
.El
.Sh IOCTL
There are only few ioctls for the
.Nm
driver. These are defined in
.Ao Pa machine/mouse.h Ac .
.Bl -tag -width MOUSE
.It Dv MOUSEIOCREAD
The
.Dv MOUSEIOCREAD
command did NOT work before and does NOT work now. It is obsolete.
Use the
.Dv MOUSE_GETSTATE
command instead.
.It Dv MOUSE_GETSTATE
The command returns the current mouse state in the following structure
and remove the state information from the internal queue.
.Bd -literal
typedef struct mousestatus {
int button; /* button status */
int obutton; /* previous button status */
int dx; /* x movement */
int dy; /* y movement */
} mousestatus_t;
.Ed
.Pp
.Ss Driver Flags
The
.Dv button
and the
.Dv obutton
fields hold the current and the previous state of the mouse buttons.
When a button is pressed, the corresponding bit is set.
These bits are defined as
.Dv MOUSE_BUTTON1DOWN
through
.Dv MOUSE_BUTTON8DOWN .
The first three buttons are left, middle and right buttons.
.Pp
Note that this command and
.Fn read
operation on the
.Nm
driver uses the same internal queue. Therefore, interleaving the
.Dv MOUSE_GETSTATE
command and
.Fn read
operation is not recommended.
.It Dv MOUSE_GETHWINFO
Returns the hardware information in the following structure.
driver accepts the following driver flags. Set them in the
kernel configuration file or in the User Configuration Menu at
the boot time
.Pq see Xr boot 8 .
.Pp
.Bl -tag -width MOUSE
.It bit 0..3 RESOLUTION
This flag specifies the resolution of the pointing device.
It must be zero through four. The greater the value
is, the finer resolution the device will select.
Actual resolution selected by this field varies according to the model
of the device. Typical resolutions are:
.Pp
.Bl -tag -width 0_(medium_high)__ -compact
.It Em 1 (low)
25 pulse per inch (ppi)
.It Em 2 (medium low)
50 ppi
.It Em 3 (medium high)
100 ppi
.It Em 4 (high)
200 ppi
.El
.Pp
Leaving this flag zero will selects the default resolution for the
device (whatever it is).
.It bit 4..7 ACCELERATION
This flag controls the amount of acceleration effect.
The smaller the value of this flag is, more sensitive the movement becomes.
The minimum value allowed, thus the value for the most sensitive setting,
is one. Setting this flag to zero will completely disables the
acceleration effect.
.It bit 8 NOCHECKSYNC
The
.Nm
driver tries to detect the first byte of the data packet by checking
the bit pattern of that byte. Although this method should work with most
PS/2 pointing devices, it may interfere with some devices which are not
so compatible with known devices.
If you think your pointing device is not functioning as expected,
see if disabling synchronization check will help by setting this flag.
.El
.Sh IOCTLS
There are a few
.Xr ioctl 2
commands for mouse drivers.
These commands and related structures and constants are defined in
.Ao Pa machine/mouse.h Ac .
General description of the commands is given in
.Xr mouse 4 .
This section explains the features specific to the
.Nm
driver.
.Pp
.Bl -tag -width MOUSE -compact
.It Dv MOUSE_GETLEVEL Ar int *level
.It Dv MOUSE_SETLEVEL Ar int *level
These commands manipulate the operation level of the
.Nm
driver.
.Pp
.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
Returns the hardware information of the attached device 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 model; /* I/F dependent model ID */
int hwid; /* I/F dependent hardware ID */
} mousehw_t;
.Ed
.Pp
The
.Dv iftype
is
.Dv MOUSE_IF_PS2
for the
.Dv buttons
field holds the number of buttons on the device.
The
.Nm
driver. The
driver currently 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
The
.Dv iftype
is always
.Dv MOUSE_IF_PS2 .
.Pp
The
.Dv type
tells the device type:
.Dv MOUSE_MOUSE ,
@ -248,73 +342,240 @@ tells the device type:
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.
.Pp
The
.Dv model
is always
.Dv MOUSE_MODEL_GENERIC
at the operation level 0.
It may be
.Dv MOUSE_MODEL_GENERIC
or one of
.Dv MOUSE_MODEL_XXX
constants at higher operation levels.
Again the
.Nm
driver may or may not set an appropriate value in this field.
.Pp
The
.Dv hwid
is the ID value returned by the pointing device.
is the ID value returned by the device.
Known IDs include:
.Pp
.Bl -tag -width 0__ -compact
.It Em 0
Mouse (Microsoft, Logitech and many other manufacturers)
.It Em 2
Microsoft Ballpoint mouse
.It Em 3
Microsoft IntelliMouse
.El
.It Dv MOUSE_GETMODE, MOUSE_SETMODE
The commands get and set the operation mode of the
.Nm
.Pp
.It Dv MOUSE_GETMODE Ar mousemode_t *mode
The command gets the current operation parameters of the mouse
driver.
.Bd -literal
typedef struct mousemode {
int protocol; /* MOUSE_PROTO_XXX */
int rate; /* report rate (per sec), -1 if unknown */
int resolution; /* 1:low, 2:medium low, 3:medium high
* 4:high, 0: default, -1 if unknown
*/
int accelfactor; /* acceleration factor (must be 1 or greater) */
int resolution; /* MOUSE_RES_XXX, -1 if unknown */
int accelfactor; /* acceleration factor */
int level; /* driver operation level */
int packetsize; /* the length of the data packet */
unsigned char syncmask[2]; /* sync. bits */
} 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 read by user
programs as is.
No other value is allowed at the moment.
.\"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.
.\"Note that the protocol cannot be set to anything other than
.\".Dv MOUSE_PROTO_PS2
.\"unless the
.\".Em PSM_EMULATION
.\"option is specified in the kernel configuration file.
is
.Dv MOUSE_PROTO_PS2
at the operation level zero and two.
.Dv MOUSE_PROTO_SYSMOUSE
at the operation level one.
.Pp
The
.Dv rate
is the status report rate (reports/sec) at which the device will send
movement report to the host computer.
Typical supported values are 10, 20, 40, 60, 80, 100 and 200.
Some mice may accept other arbitrary values too.
.Pp
The
.Dv resolution
of the pointing device must be zero through four. The higher the value
is, the finer resolution the mouse will select. Zero selects the
default resolution.
of the pointing device must be one of
.Dv MOUSE_RES_XXX
constants or a positive value. The greater the value
is, the finer resolution the mouse will select.
Actual resolution selected by the
.Dv MOUSE_RES_XXX
constant varies according to the model of mouse. Typical resolutions are:
.Pp
.Bl -tag -width MOUSE_RES_MEDIUMHIGH__ -compact
.It Dv MOUSE_RES_LOW
25 ppi
.It Dv MOUSE_RES_MEDIUMLOW
50 ppi
.It Dv MOUSE_RES_MEDIUMHIGH
100 ppi
.It Dv MOUSE_RES_HIGH
200 ppi
.El
.Pp
The
.Dv accelfactor
holds a value to control acceleration feature (see description on
.Em PSM_ACCEL
above). It must be zero or greater.
If it is zero, acceleration is disabled.
field holds a value to control acceleration feature
.Pq see Sx Acceleration .
It must be zero or greater. If it is zero, acceleration is disabled.
.Pp
The
.Dv packetsize
field specifies the length of the data packet. It depends on the
operation level and the model of the pointing device.
.Pp
.Bl -tag -width level_0__ -compact
.It Em level 0
3 bytes
.It Em level 1
8 bytes
.It Em level 2
Depends on the model of the device
.El
.Pp
The array
.Dv syncmask
holds a bit mask and pattern to detect the first byte of the
data packet.
.Dv syncmask[0]
is the bit mask to be ANDed with a byte. If the result is equal to
.Dv syncmask[1] ,
the byte is likely to be the first byte of the data packet.
Note that this detection method is not 100% reliable,
thus, should be taken only as an advisory measure.
.Pp
.It Dv MOUSE_SETMODE Ar mousemode_t *mode
The command changes the current operation parameters of the mouse driver
as specified in
.Ar mode .
Only
.Dv rate ,
.Dv resolution ,
.Dv level
and
.Dv accelfactor
may be modifiable. Setting values in the other field does not generate
error and has no effect.
.Pp
If you do not want to change the current setting of a field, put -1
there.
You may also put zero in
.Dv resolution
and
.Dv rate ,
and the default value for the fields will be selected.
.\" .Pp
.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
.\" These commands are not supported by the
.\" .Nm
.\" driver.
.Pp
.It Dv MOUSE_READDATA Ar mousedata_t *data
.\" The command reads the raw data from the device.
.\" .Bd -literal
.\" typedef struct mousedata {
.\" int len; /* # of data in the buffer */
.\" int buf[16]; /* data buffer */
.\" } mousedata_t;
.\" .Ed
.\" .Pp
.\" Upon returning to the user program, the driver will place the number
.\" of valid data bytes in the buffer in the
.\" .Dv len
.\" field.
.\" .Pp
.It Dv MOUSE_READSTATE Ar mousedata_t *state
.\" The command reads the hardware settings from the device.
.\" Upon returning to the user program, the driver will place the number
.\" of valid data bytes in the buffer in the
.\" .Dv len
.\" field. It is usually 3 bytes.
.\" The buffer is formatted as follows:
.\" .Pp
.\" .Bl -tag -width Byte_1 -compact
.\" .It Byte 1
.\" .Bl -tag -width bit_6 -compact
.\" .It bit 7
.\" Reserved.
.\" .It bit 6
.\" 0 - stream mode, 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.
.\" The
.\" .Nm
.\" driver puts the device in the stream mode.
.\" .It bit 5
.\" Set if the pointing device is currently enabled. Otherwise zero.
.\" .It bit 4
.\" 0 - 1:1 scaling, 1 - 2:1 scaling.
.\" 1:1 scaling is the default.
.\" .It bit 3
.\" Reserved.
.\" .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
.\" .Bl -tag -width bit_6_0 -compact
.\" .It bit 7
.\" Reserved.
.\" .It bit 6..0
.\" Resolution code: zero through three. Actual resolution for
.\" the resolution code varies from one device to another.
.\" .El
.\" .It Byte 3
.\" The status report rate (reports/sec) at which the device will send
.\" movement report to the host computer.
.\" .El
These commands are not currently supported by the
.Nm
driver.
.Pp
.It Dv MOUSE_GETSTATE Ar mousestatus_t *status
The command returns the current state of buttons and
movement counts as described in
.Xr mouse 4 .
.El
.Sh FILES
.Bl -tag -width /dev/npsm0 -compact
.It Pa /dev/psm0
`non-blocking' device node in the system without
.Em devfs ,
`blocking' under
.Em devfs .
.It Pa /dev/npsm0
`non-blocking' device node under
.Em devfs .
.El
.Sh EXAMPLE
.Dl "options" \&"PSM_HOOKAPM\&"
.Dl "device psm0 at isa? port" \&"IO_KBD\&" conflicts tty irq 12 vector psmintr
.Pp
Add the
.Nm
driver to the kernel with the optional code to stimulate the pointing device
after the `resume' event.
.Pp
.Dl "device psm0 at isa? port" \&"IO_KBD\&" conflicts tty flags 0x024 irq 12
.Dl vector psmintr
.Pp
Set the device resolution high (4) and the acceleration factor to 2.
.Sh DIAGNOSTICS
.Pp
At debug level 0, little information is logged except for the following
@ -332,23 +593,20 @@ for known IDs.
.Pp
At debug level 1 more information will be logged
while the driver probes the auxiliary port (mouse port).
Messages are logged with the LOG_KERN facility at the LOG_DEBUG level.
(See
.Xr syslogd 8 . )
Messages are logged with the LOG_KERN facility at the LOG_DEBUG level
.Pq see Xr syslogd 8 .
.Bd -literal -offset indent
psm0: current command byte:xxxx
kbdio: new command byte:yyyy (set_controller...)
kbdio: TEST_AUX_PORT status:0000
kbdio: RESET_AUX return code:00fa
kbdio: RESET_AUX status:00aa
kbdio: RESET_AUX ID:0000
psm0: status after reset 00 02 64
psm: device ID: X
psm: status xx yy zz (get_mouse_buttons)
psm0: status 00 02 64
kbdio: new command byte:zzzz (set_controller...)
[...]
psm: status 00 02 64
psm0 at 0x60-0x64 irq 12 on motherboard
psm0: device ID X, N buttons
psm0: model AAAA, device ID X, N buttons
psm0: config:00000www, flags:0000uuuu, packet size:M
psm0: syncmask:xx, syncbits:yy
.Ed
.Pp
The first line shows the command byte value of the keyboard
@ -356,17 +614,20 @@ controller just before the auxiliary port is probed.
It usually is 4D, 45, 47 or 65, depending on how the motherboard BIOS
initialized the keyboard controller upon power-up.
.Pp
The third line shows the result of the keyboard controller's
The second line shows the result of the keyboard controller's
test on the auxiliary 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 forth to sixth lines show the reset status of the pointing device.
The third through 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 tenth line shows the current hardware settings; it consists
of three bytes:
The seventh line shows the current hardware settings.
.\" See
.\" .Dv MOUSE_READSTATE
.\" for definitions.
These bytes are formatted as follows:
.Pp
.Bl -tag -width Byte_1 -compact
.It Byte 1
@ -378,10 +639,14 @@ Reserved.
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.
The
.Nm
driver puts the device in the stream mode.
.It bit 5
Set if the pointing device is currently enabled. Otherwise zero.
.It bit 4
0 - 1:1 scaling, 1 - 2:1 scaling.
1:1 scaling is the default.
.It bit 3
Reserved.
.It bit 2
@ -395,21 +660,9 @@ Right button status; set if pressed.
.Bl -tag -width bit_6_0 -compact
.It bit 7
Reserved.
.It bit 6-0
Resolution code: zero through three. The higher the number is,
the finer resolution the device has. Actual resolution for
.It bit 6..0
Resolution code: zero through three. Actual resolution for
the resolution code varies from one device to another.
The typical values are:
.Bl -tag -width 100 -compact
.It 0
25 pulse per inch (ppi)
.It 1
50 ppi
.It 2
100 ppi
.It 3
200 ppi
.El
.El
.It Byte 3
The status report rate (reports/sec) at which the device will send
@ -418,30 +671,22 @@ movement report to the host computer.
.Pp
Note that the pointing device will not be enabled until the
.Nm
driver is opened by the user programs.
driver is opened by the user program.
.Pp
The last line shows the device ID code and the number of detected
buttons. 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.
The rest of the lines show the device ID code, the number of detected
buttons and internal variables.
.Pp
At debug level 2, much more detailed information is logged.
.Sh FILES
.Bl -tag -width /dev/npsm0 -compact
.It Pa /dev/psm0
`non-blocking' device node in the system without
.Em devfs ,
`blocking' under
.Em devfs .
.It Pa /dev/npsm0
`non-blocking' device node under
.Em devfs .
.El
.Sh CAVEATS
Many pad devices behave as if the first (left) button were pressed if
the user `taps' the surface of the pad.
In contrast, some ALPS GlidePoint pad models treat the tapping action
as fourth button events.
.Pp
Some PS/2 mouse models from MouseSystems require to be put in the
high resolution mode to work properly. Use the driver flag to
set resolution.
.Pp
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. However, if you are using the \fIXFree86\fP server and experiencing
@ -449,22 +694,33 @@ the problem, you may be able to make the X server synchronize with the mouse
by switching away to a virtual terminal and getting back to the X server,
unless the X server is accessing the mouse via
.Xr moused 1 .
If you have specified the
.Em PSM_CHECKSYNC
option, clicking any button without moving the mouse may also work.
Clicking any button without moving the mouse may also work.
.Sh BUGS
The
.Fn ioctl
command
The ioctl command
.Dv MOUSEIOCREAD
(see
.Sx IOCTL
above) was never functional and will not be. The command name
still remains for compatibility reasons but may be removed in the future.
has been removed. It was never functional anyway.
.Sh SEE ALSO
.Xr moused 1 ,
.Xr ioctl 2 ,
.Xr syslog 3 ,
.Xr mouse 4 ,
.Xr mse 4 ,
.Xr sysmouse 4 ,
.Xr moused 8 ,
.Xr syslogd 8
.\" .Sh HISTORY
.\" .Sh AUTHOR
.\".Sh HISTORY
.Sh AUTHOR
The
.Nm
driver is based on the work done by quite a number of people, including
.An Eric Forsberg ,
.An Sandi Donno ,
.An Rick Macklem ,
.An Andrew Herbert ,
.An Charles Hannum ,
.An Shoji Yuen
and
.An Kazutaka YOKOTA
to name the few.
.Pp
This manual page was written by
.An Kazutaka YOKOTA Aq yokota@FreeBSD.org .

415
share/man/man4/sysmouse.4
View File

@ -25,51 +25,300 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $Id$
.\" $Id: sysmouse.4,v 1.5 1997/03/07 02:49:59 jmg Exp $
.\"
.Dd February 14, 1997
.Dd December 3, 1997
.Dt SYSMOUSE 4 i386
.Os
.Os FreeBSD
.Sh NAME
.Nm sysmouse
.Nd supplies mouse data from syscons for other applications
.\" .Nd supplies mouse data from syscons for other applications
.Nd virtualized mouse driver
.Sh SYNOPSIS
.Fd #include <machine/mouse.h>
.Fd #include <machine/console.h>
.Ft int
.Fn ioctl cfd CONS_MOUSECTL struct\ *mouse_info
.Sh DESCRIPTION
The console driver, in conjunction with the mouse daemon
.Xr moused 8 ,
supplies mouse data to the user process in the standardized way via the
.Nm
driver.
This arrangement makes it possible for the console and the user process
.Pq such as the Tn X\ Window System
to share the mouse.
.Pp
The user process which wants to utilize mouse operation simply opens
.Pa /dev/sysmouse
with a
.Xr open 2
call and reads
mouse data from the device via
.Xr read 2 .
Make sure that
.Xr moused 8
is running, otherwise the user process won't see any data coming from
the mouse.
.Pp
.Ss Operation Levels
The
.Dv CONS_MOUSECTL
.Nm
driver has two levels of operation.
The current operation level can be referred to and changed via ioctl calls.
.Pp
The level zero, the basic level, is the lowest level at which the driver
offers the basic service to user programs.
The
.Nm
driver
provides horizontal and vertical movement of the mouse
and state of up to three buttons in the
.Tn MouseSystems
format as follows.
.Pp
.Bl -tag -width Byte_1 -compact
.It Byte 1
.Bl -tag -width bit_7 -compact
.It bit 7
Always one.
.It bit 6..3
Always zero.
.It bit 2
Left button status; cleared if pressed, otherwise set.
.It bit 1
Middle button status; cleared if pressed, otherwise set. Always one,
if the device does not have the middle button.
.It bit 0
Right button status; cleared if pressed, otherwise set.
.El
.It Byte 2
The first half of horizontal movement count in two's compliment;
-128 through 127.
.It Byte 3
The first half of vertical movement count in two's compliment;
-128 through 127.
.It Byte 4
The second half of the horizontal movement count in two's compliment;
-128 through 127. To obtain the full horizontal movement count, add
the byte 2 and 4.
.It Byte 5
The second half of the vertical movement count in two's compliment;
-128 through 127. To obtain the full vertical movement count, add
the byte 3 and 5.
.El
.Pp
At the level one, the extended level, mouse data is encoded
in the standard format
.Dv MOUSE_PROTO_SYSMOUSE
as defined in
.Xr mouse 4 .
.\" .Ss Acceleration
.\" The
.\" .Nm
.\" driver can somewhat `accelerate' the movement of the pointing device.
.\" The faster you move the device, the further the pointer
.\" travels on the screen.
.\" The driver has an internal variable which governs the effect of
.\" the acceleration. Its value can be modified via the driver flag
.\" or via an ioctl call.
.Sh IOCTLS
This section describes two classes of
.Xr ioctl 2
commands:
commands for the
.Nm
driver itself, and commands for the console and the console control drivers.
.Ss Sysmouse Ioctls
There are a few commands for mouse drivers.
General description of the commands is given in
.Xr mouse 4 .
Followings are the features specific to the
.Nm
driver.
.Pp
.Bl -tag -width MOUSE -compact
.It Dv MOUSE_GETLEVEL Ar int *level
.It Dv MOUSE_SETLEVEL Ar int *level
These commands manipulate the operation level of the mouse driver.
.Pp
.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
Returns the hardware information of the attached device in the following
structure. Only the
.Dv iftype
field is guaranteed to be filled with the correct value in the current
version of the
.Nm
driver.
.Bd -literal
typedef struct mousehw {
int buttons; /* number of buttons */
int iftype; /* I/F type */
int type; /* mouse/track ball/pad... */
int model; /* I/F dependent model ID */
int hwid; /* I/F dependent hardware ID */
} mousehw_t;
.Ed
.Pp
The
.Dv buttons
field holds the number of buttons detected by the driver.
.Pp
The
.Dv iftype
is always
.Dv MOUSE_IF_SYSMOUSE.
.Pp
The
.Dv type
tells the device type:
.Dv MOUSE_MOUSE ,
.Dv MOUSE_TRACKBALL ,
.Dv MOUSE_STICK ,
.Dv MOUSE_PAD ,
or
.Dv MOUSE_UNKNOWN .
.Pp
The
.Dv model
is always
.Dv MOUSE_MODEL_GENERIC
at the operation level 0.
It may be
.Dv MOUSE_MODEL_GENERIC
or one of
.Dv MOUSE_MODEL_XXX
constants at higher operation levels.
.Pp
The
.Dv hwid
is always zero.
.Pp
.It Dv MOUSE_GETMODE Ar mousemode_t *mode
The command gets the current operation parameters of the mouse
driver.
.Bd -literal
typedef struct mousemode {
int protocol; /* MOUSE_PROTO_XXX */
int rate; /* report rate (per sec) */
int resolution; /* MOUSE_RES_XXX, -1 if unknown */
int accelfactor; /* acceleration factor */
int level; /* driver operation level */
int packetsize; /* the length of the data packet */
unsigned char syncmask[2]; /* sync. bits */
} mousemode_t;
.Ed
.Pp
The
.Dv protocol
field tells the format in which the device status is returned
when the mouse data is read by the user program.
It is
.Dv MOUSE_PROTO_MSC
at the operation level zero.
.Dv MOUSE_PROTO_SYSMOUSE
at the operation level one.
.Pp
The
.Dv rate
is always set to -1.
.Pp
The
.Dv resolution
is always set to -1.
.Pp
The
.Dv accelfactor
is always 0.
.Pp
The
.Dv packetsize
field specifies the length of the data packet. It depends on the
operation level.
.Pp
.Bl -tag -width level_0__ -compact
.It Em level 0
5 bytes
.It Em level 1
8 bytes
.El
.Pp
The array
.Dv syncmask
holds a bit mask and pattern to detect the first byte of the
data packet.
.Dv syncmask[0]
is the bit mask to be ANDed with a byte. If the result is equal to
.Dv syncmask[1] ,
the byte is likely to be the first byte of the data packet.
Note that this method of detecting the first byte is not 100% reliable,
thus, should be taken only as an advisory measure.
.Pp
.It Dv MOUSE_SETMODE Ar mousemode_t *mode
The command changes the current operation parameters of the mouse driver
as specified in
.Ar mode .
Only
.Dv level
may be modifiable. Setting values in the other field does not generate
error and has no effect.
.\" .Pp
.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
.\" These commands are not supported by the
.\" .Nm
.\" driver.
.Pp
.It Dv MOUSE_READDATA Ar mousedata_t *data
.It Dv MOUSE_READSTATE Ar mousedata_t *state
These commands are not supported by the
.Nm
driver.
.Pp
.It Dv MOUSE_GETSTATE Ar mousestatus_t *status
The command returns the current state of buttons and
movement counts in the structure as defined in
.Xr mouse 4 .
.El
.Ss Console and Consolectl Ioctls
The user process issues console
.Fn ioctl
call provides syscons with mouse information, which includes mouse movement
and button presses. The
.Fn ioctl
also provides a method for a process to receive a
calls to the current virtual console in order to control
the mouse pointer.
The console
.Fn ioctl
also provides a method for the user process to receive a
.Xr signal 3
when a button is pressed.
.Pp
The mouse daemon
.Xr moused 8
uses this
uses
.Fn ioctl
to inform the console of mouse actions. Applications
.Pq such as Tn X\ Windows
can use
.Pa /dev/sysmouse ,
allowing syscons and the application to share the mouse.
calls to the console control device
.Pa /dev/consolectl
to inform the console of mouse actions including mouse movement
and button status.
.Pp
.Bd -literal -offset indent
Both classes
.Fn ioctl
commands are defined as
.Dv CONS_MOUSECTL
which takes the following argument.
.Bd -literal
struct mouse_info {
int operation;
union {
struct mouse_data data;
struct mouse_mode mode;
}u;
int operation;
union {
struct mouse_data data;
struct mouse_mode mode;
struct mouse_event event;
} u;
};
.Ed
.Bl -tag -width operation
.Pp
.Bl -tag -width operation -compact
.It Dv operation
This can be one of
.Bl -tag -width MOUSE_MOVEABS
.Pp
.Bl -tag -width MOUSE_MOVEABS -compact
.It Dv MOUSE_SHOW
Enables and displays mouse cursor.
.It Dv MOUSE_HIDE
@ -78,11 +327,12 @@ Disables and hides mouse cursor.
Moves mouse cursor to position supplied in
.Dv u.data .
.It Dv MOUSE_MOVEREL
Add position supplied in
Adds position supplied in
.Dv u.data
to current position.
.It Dv MOUSE_GETINFO
Returns current mouse position and button status in
Returns current mouse position in the current virtual console
and button status in
.Dv u.data .
.It Dv MOUSE_MODE
This sets the
@ -90,34 +340,99 @@ This sets the
to be delivered to the current process when a button is pressed.
The signal to be delivered is set in
.Dv u.mode .
.It Dv MOUSE_ACTION
This takes the information in
.Dv u.data
and acts upon it. It includes processing button presses if the current vty
is a text interface, and sending
.Tn Mouse System
protocol data to
.Pa /dev/sysmouse
if it is open.
.El
.Pp
The above operations are for virtual consoles. The operations defined
below are for the console control device and used by
.Xr moused 8
to pass mouse data to the console driver.
.Pp
.Bl -tag -width MOUSE_MOVEABS -compact
.It Dv MOUSE_ACTION
.It Dv MOUSE_MOTIONEVENT
These operations take the information in
.Dv u.data
and act upon it. Mouse data will be sent to the
.Nm
driver if it is open.
.Dv MOUSE_ACTION
also processes button press actions and sends signal to the process if
requested or performs cut and paste operations
if the current console is a text interface.
.It Dv MOUSE_BUTTONEVENT
.Dv u.data
specifies a button and its click count. The console driver will
use this information for signal delivery if requested or
for cut and paste operations if the console is in text mode.
.El
.Pp
.Dv MOUSE_MOTIONEVENT
and
.Dv MOUSE_BUTTONEVENT
are newer interface and are designed to be used together.
They are intended to replace functions performed by
.Dv MOUSE_ACTION
alone.
.Pp
.It Dv u
This union is one of
.Bl -tag -width data
.Pp
.Bl -tag -width data -compact
.It Dv data
.Bd -literal -offset indent
.Bd -literal
struct mouse_data {
int x;
int y;
int buttons;
int x;
int y;
int z;
int buttons;
};
.Ed
.Pp
.Dv x ,
.Dv y
and
.Dv z
represent movement of the mouse along respective directions.
.Dv buttons
tells the state of buttons. It encodes up to 31 buttons in the bit 0 though
the bit 30. If a button is held down, the corresponding bit is set.
.Pp
.It Dv mode
.Bd -literal -offset indent
.Bd -literal
struct mouse_mode {
int mode;
int signal;
int mode;
int signal;
};
.Ed
.Pp
The
.Dv signal
field specifies the signal to be delivered to the process. It must be
one of the values defined in
.Ao Pa signal.h Ac .
The
.Dv mode
field is currently unused.
.Pp
.It Dv event
.Bd -literal
struct mouse_event {
int id;
int value;
};
.Ed
.Pp
The
.Dv id
field specifies a button number as in
.Dv u.data.buttons .
Only one bit/button is set.
The
.Dv value
field
holds the click count: the number of times the user has clicked the button
successively.
.Pp
.El
.El
.Sh FILES
@ -125,11 +440,15 @@ struct mouse_mode {
.It Pa /dev/consolectl
device to control the console
.It Pa /dev/sysmouse
mouse action output
virtualized mouse driver
.It Pa /dev/ttyv%d
virtual consoles
.El
.Sh SEE ALSO
.Xr vidcontrol 1 ,
.Xr ioctl 2 ,
.Xr signal 3 ,
.Xr mouse 4 ,
.Xr moused 8
.Sh HISTORY
The
@ -138,5 +457,7 @@ manual page example first appeared in
.Fx 2.2 .
.Sh AUTHOR
This
manual page was written by John-Mark Gurney
.Aq gurney_j@efn.org .
manual page was written by
.An John-Mark Gurney Aq gurney_j@efn.org
and
.An Kazutaka YOKOTA Aq yokota@FreeBSD.org .