0afc94c17a
bottom of the manpages and order them consistently. GNU groff doesn't care about the ordering, and doesn't even mention CAVEATS and SECURITY CONSIDERATIONS as common sections and where to put them. Found by: mdocml lint run Reviewed by: ru
387 lines
9.5 KiB
Groff
387 lines
9.5 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd December 3, 1997
|
|
.Dt MSE 4 i386
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mse
|
|
.Nd bus and InPort mice driver
|
|
.Sh SYNOPSIS
|
|
.\" .Cd "options MSE_XXX=N"
|
|
.Cd "device mse"
|
|
.Pp
|
|
In
|
|
.Pa /boot/device.hints :
|
|
.Cd hint.mse.0.at="isa"
|
|
.Cd hint.mse.0.port="0x23c"
|
|
.Cd hint.mse.0.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 ``do not 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
|
|
(see
|
|
.Xr config 8 )
|
|
or in the User Configuration Menu at
|
|
the boot time
|
|
(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
|
|
.In sys/mouse.h .
|
|
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
|
|
(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 does not 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_GETSTATUS 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 EXAMPLES
|
|
.Dl "device mse"
|
|
.Pp
|
|
In
|
|
.Pa /boot/device.hints :
|
|
.Dl hint.mse.0.at="isa"
|
|
.Dl hint.mse.0.port="0x23c"
|
|
.Dl hint.mse.0.irq="5"
|
|
.Pp
|
|
Add the
|
|
.Nm
|
|
driver at the primary port address with the IRQ 5.
|
|
.Pp
|
|
.Dl "device mse"
|
|
.Pp
|
|
.Dl hint.mse.1.at="isa"
|
|
.Dl hint.mse.1.port="0x238"
|
|
.Dl hint.mse.1.irq="4"
|
|
.Dl hint.mse.1.flags="0x30"
|
|
.Pp
|
|
Define the
|
|
.Nm
|
|
driver at the secondary port address with the IRQ 4 and the acceleration
|
|
factor of 3.
|
|
.Sh SEE ALSO
|
|
.Xr ioctl 2 ,
|
|
.Xr mouse 4 ,
|
|
.Xr psm 4 ,
|
|
.Xr sysmouse 4 ,
|
|
.Xr moused 8
|
|
.\".Sh HISTORY
|
|
.Sh CAVEATS
|
|
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.
|