sysmouse(4)

NAME

sysmouse - virtualized mouse driver

SYNOPSIS

#include <sys/mouse.h>
#include <sys/consio.h>

DESCRIPTION

The console driver, in conjunction with the mouse daemon

moused(8), supplies mouse data to the user process in the standardized way

via the
sysmouse driver. This arrangement makes it possible for the

console and
the user process (such as the X Window System) to share the

mouse.

The user process which wants to utilize mouse operation sim

ply opens
/dev/sysmouse with a open(2) call and reads mouse data from

the device
via read(2). Make sure that moused(8) is running, otherwise

the user
process will not see any data coming from the mouse.

Operation Levels

The sysmouse driver has two levels of operation. The cur

rent operation
level can be referred to and changed via ioctl calls.

The level zero, the basic level, is the lowest level at

which the driver
offers the basic service to user programs. The sysmouse

driver provides
horizontal and vertical movement of the mouse and state of

up to three
buttons in the MouseSystems format as follows.

Byte 1

bit 7 Always one.
bit 6..3

Always zero.

bit 2 Left button status; cleared if pressed, oth

erwise set.
bit 1 Middle button status; cleared if pressed,

otherwise set.

Always one, if the device does not have the

middle button.

bit 0 Right button status; cleared if pressed, oth

erwise set.

Byte 2 The first half of horizontal movement count in two's

complement;

-128 through 127.

Byte 3 The first half of vertical movement count in two's

complement;

-128 through 127.

Byte 4 The second half of the horizontal movement count in

two's comple

ment; -128 through 127. To obtain the full horizon

tal movement
count, add the byte 2 and 4.

Byte 5 The second half of the vertical movement count in

two's comple

ment; -128 through 127. To obtain the full vertical

movement
count, add the byte 3 and 5.

At the level one, the extended level, mouse data is encoded

in the standard format MOUSE_PROTO_SYSMOUSE as defined in mouse(4).

IOCTLS

This section describes two classes of ioctl(2) commands:

commands for the
sysmouse driver itself, and commands for the console and the

console control drivers.

Sysmouse Ioctls

There are a few commands for mouse drivers. General de

scription of the
commands is given in mouse(4). Following are the features

specific to
the sysmouse driver.

MOUSE_GETLEVEL int *level
MOUSE_SETLEVEL int *level

These commands manipulate the operation level of the

mouse driver.

MOUSE_GETHWINFO mousehw_t *hw

Returns the hardware information of the attached de

vice in the
following structure. Only the iftype field is guar

anteed to be
filled with the correct value in the current version

of the
sysmouse driver.

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 detect

ed by the
driver.

The iftype is always MOUSE_IF_SYSMOUSE.

The type tells the device type: MOUSE_MOUSE,

MOUSE_TRACKBALL,
MOUSE_STICK, MOUSE_PAD, or MOUSE_UNKNOWN.

The model is always MOUSE_MODEL_GENERIC at the opera

tion level 0.
It may be MOUSE_MODEL_GENERIC or one of MOUSE_MOD

EL_XXX constants
at higher operation levels.

The hwid is always zero.

MOUSE_GETMODE mousemode_t *mode

The command gets the current operation parameters of

the mouse
driver.

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;

The protocol field tells the format in which the de

vice status is
returned when the mouse data is read by the user pro

gram. It is
MOUSE_PROTO_MSC at the operation level zero.

MOUSE_PROTO_SYSMOUSE
at the operation level one.

The rate is always set to -1.

The resolution is always set to -1.

The accelfactor is always 0.

The packetsize field specifies the length of the data

packet. It
depends on the operation level.

level 0 5 bytes
level 1 8 bytes

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 sync

mask[1], the
byte is likely to be the first byte of the data pack

et. Note that
this method of detecting the first byte is not 100%

reliable;
thus, it should be taken only as an advisory measure.

MOUSE_SETMODE mousemode_t *mode

The command changes the current operation parameters

of the mouse
driver as specified in mode. Only level may be modi

fiable. Setting values in the other field does not generate er

ror and has no
effect.

MOUSE_READDATA mousedata_t *data
MOUSE_READSTATE mousedata_t *state

These commands are not supported by the sysmouse

driver.

MOUSE_GETSTATUS mousestatus_t *status

The command returns the current state of buttons and

movement
counts in the structure as defined in mouse(4).

Console and Consolectl Ioctls

The user process issues console ioctl() calls to the current

virtual console in order to control the mouse pointer. The console

ioctl() also
provides a method for the user process to receive a sig

nal(3) when a button is pressed.

The mouse daemon moused(8) uses ioctl() calls to the console

control
device /dev/consolectl to inform the console of mouse ac

tions including
mouse movement and button status.

Both classes of ioctl() commands are defined as CONS_MOU

SECTL which takes
the following argument.

struct mouse_info {

int operation;
union {

struct mouse_data data;
struct mouse_mode mode;
struct mouse_event event;

} u;

};

operation This can be one of

MOUSE_SHOW Enables and displays mouse cursor.
MOUSE_HIDE Disables and hides mouse cursor.
MOUSE_MOVEABS Moves mouse cursor to position

supplied in

u.data.

MOUSE_MOVEREL Adds position supplied in u.data

to current

position.

MOUSE_GETINFO Returns current mouse position in

the current

virtual console and button status

in u.data.

MOUSE_MODE This sets the signal(3) to be de

livered to the

current process when a button is

pressed. The
signal to be delivered is set in

u.mode.

The above operations are for virtual consoles.

The operations
defined below are for the console control device

and are used
by moused(8) to pass mouse data to the console

driver.

MOUSE_ACTION
MOUSE_MOTIONEVENT

These operations take the informa

tion in u.data
and act upon it. Mouse data will

be sent to
the sysmouse driver if it is open. 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.

MOUSE_BUTTONEVENT

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.

MOUSE_MOTIONEVENT and MOUSE_BUTTONEVENT are newer

interface
and are designed to be used together. They are

intended to
replace functions performed by MOUSE_ACTION

alone.

u This union is one of

data

struct mouse_data {

int x;
int y;
int z;
int buttons;

};

x, y and z represent movement of the mouse

along respective directions. 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 corre

sponding bit is
set.

mode

struct mouse_mode {
int mode;
int signal;

};

The signal field specifies the signal to be

delivered to
the process. It must be one of the values

defined in
The mode field is currently unused.

event

struct mouse_event {
int id;
int value;

};

The id field specifies a button number as

in
u.data.buttons. Only one bit/button is

set. The value
field holds the click count: the number of

times the
user has clicked the button successively.

FILES

/dev/consolectl device to control the console
/dev/sysmouse virtualized mouse driver
/dev/ttyv%d virtual consoles

SEE ALSO

vidcontrol(1), ioctl(2), signal(3), mouse(4), moused(8)

HISTORY

The sysmouse manual page example first appeared in FreeBSD

2.2.

AUTHORS

This manual page was written by John-Mark Gurney <gur

ney_j@efn.org> and
Kazutaka Yokota <yokota@FreeBSD.org>.

BSD December 3, 1997

BSD