354 lines
9.4 KiB
Groff
354 lines
9.4 KiB
Groff
.\" Copyright 1992 by the University of Guelph
|
|
.\"
|
|
.\" Permission to use, copy and modify this
|
|
.\" software and its documentation for any purpose and without
|
|
.\" fee is hereby granted, provided that the above copyright
|
|
.\" notice appear in all copies and that both that copyright
|
|
.\" notice and this permission notice appear in supporting
|
|
.\" documentation.
|
|
.\" University of Guelph makes no representations about the suitability of
|
|
.\" this software for any purpose. It is provided "as is"
|
|
.\" without express or implied warranty.
|
|
.\"
|
|
.\" $Id: mse.4,v 1.4 1997/12/07 08:46:53 yokota Exp $
|
|
.\"
|
|
.Dd December 3, 1997
|
|
.Dt MSE 4 i386
|
|
.Os FreeBSD
|
|
.Sh NAME
|
|
.Nm mse
|
|
.Nd bus and InPort mice driver
|
|
.Sh SYNOPSIS
|
|
.\" .Cd "options" \&"MSE_XXX=N\&"
|
|
.Cd "device mse0 at isa? port 0x23c tty irq 5"
|
|
.Sh DESCRIPTION
|
|
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'
|
|
.Ed
|
|
.Pp
|
|
where `unit' is the device number (usually 0) and the `non-blocking' bit
|
|
is set to indicate ``don't block waiting for mouse input,
|
|
return immediately''.
|
|
The `non-blocking' bit should be set for \fIXFree86\fP,
|
|
therefore the minor device number usually used for \fIXFree86\fP is 1.
|
|
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"
|
|
.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"
|
|
.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
|