| MOUSE(4) | Device Drivers Manual | MOUSE(4) |
mouse — mouse and
pointing device drivers
#include
<sys/mouse.h>
The mouse drivers mse(4), psm(4), ums(4) and sysmouse(4) provide user programs with movement and button state information of the mouse. Currently there are specific device drivers for bus, InPort, PS/2, and USB mice. The serial mouse is not directly supported by a dedicated driver, but it is accessible via the serial device driver or via moused(8) and sysmouse(4).
The user program simply opens a mouse device with a open(2) call and reads mouse data from the device via 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.
The mouse drivers may have ``non-blocking'' attribute which will make the driver return immediately if mouse data is not available.
Mouse device drivers often offer several levels of operation. The
current operation level can be examined and changed via
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
MOUSE_PROTO_SYSMOUSE as follows:
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.
Device drivers may offer operation levels higher than one. Refer to manual pages of individual drivers for details.
The following 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.
MOUSE_GETLEVEL
int *levelMOUSE_SETLEVEL
int *levelMOUSE_GETHWINFO
mousehw_t *hwiftype field, the device driver may
not always fill the structure with correct values. Consult manual pages of
individual drivers for details of support.
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;
The 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.
The iftype is the type of interface:
MOUSE_IF_SERIAL,
MOUSE_IF_BUS,
MOUSE_IF_INPORT,
MOUSE_IF_PS2,
MOUSE_IF_USB,
MOUSE_IF_SYSMOUSE or
MOUSE_IF_UNKNOWN.
The type tells the device type:
MOUSE_MOUSE,
MOUSE_TRACKBALL,
MOUSE_STICK, MOUSE_PAD,
or MOUSE_UNKNOWN.
The model may be
MOUSE_MODEL_GENERIC or one of
MOUSE_MODEL_XXX constants.
The 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.
MOUSE_GETMODE
mousemode_t *modetypedef 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;
The 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 MOUSE_PROTO_XXX
constants.
The 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.
The resolution field holds a value
specifying resolution of the pointing device. It is a positive value or
one of MOUSE_RES_XXX constants.
The accelfactor field holds a value to
control acceleration feature. It must be zero or greater. If it is zero,
acceleration is disabled.
The 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.
The array syncmask holds a bit mask
and pattern to detect the first byte of the data packet.
syncmask[0] is the bit mask to be ANDed with a
byte. If the result is equal to 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.
MOUSE_SETMODE
mousemode_t *moderate, resolution,
level and accelfactor may
be modifiable. Setting values in the other field does not generate error
and has no effect.
If you do not want to change the current setting of a field,
put -1 there. You may also put zero in
resolution and rate, and
the default value for the fields will be selected.
MOUSE_READDATA
mousedata_t *datatypedef struct mousedata {
int len; /* # of data in the buffer */
int buf[16]; /* data buffer */
} mousedata_t;
The calling process must fill the len
field with the number of bytes to be read into the buffer. This command
may not be supported by all drivers.
MOUSE_READSTATE
mousedata_t *stateMOUSE_GETSTATUS
mousestatus_t *statustypedef 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;
The button and
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
MOUSE_BUTTON1DOWN through
MOUSE_BUTTON8DOWN. The first three buttons
correspond to left, middle and right buttons.
If the state of the button has changed since the last
MOUSE_GETSTATUS call, the corresponding bit in
the flags field will be set. If the mouse has
moved since the last call, the MOUSE_POSCHANGED
bit in the flags field will also be set.
The other fields hold movement counts since the last
MOUSE_GETSTATUS call. The internal counters will
be reset after every call to this command.
This manual page was written by Kazutaka Yokota <yokota@FreeBSD.org>.
| December 3, 1997 | Debian |