Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
MOUSE(4)	       FreeBSD Kernel Interfaces Manual		      MOUSE(4)

NAME
     mouse -- mouse and	pointing device	drivers

SYNOPSIS
     #include <sys/mouse.h>

DESCRIPTION
     The mouse drivers mse(4), psm(4), ums(4) and sysmouse(4) provide user
     programs with movement and	button state information of the	mouse.	Cur-
     rently 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	cur-
     rent 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:

     Byte 1
	     bit 7  Always one.
	     bit 6..3
		    Always zero.
	     bit 2  Left button	status;	cleared	if pressed, otherwise 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, otherwise 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 horizontal 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.
     Byte 6  The bit 7 is always zero.	The lower 7 bits encode	the first half
	     of	Z axis movement	count in two's complement; -64 through 63.
     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	complement; -64
	     through 63.  To obtain the	full Z axis movement count, add	the
	     byte 6 and	7.
     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 corre-
	     sponding bit is cleared.  Otherwise the bit is set.

     The first 5 bytes of this format is compatible with the MouseSystems for-
     mat.  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 man-
     ual pages of individual drivers for details.

IOCTLS
     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	*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 device in the
	    following Except for the iftype 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 *mode
	    The	command	reports	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 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	fea-
	    ture.  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 *mode
	    The	command	changes	the current operation parameters of the	mouse
	    driver as specified	in mode.  Only rate, 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	*data
	    The	command	reads the raw data from	the device.

	    typedef 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 sup-
	    ported by all drivers.

     MOUSE_READSTATE 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.

     MOUSE_GETSTATUS mousestatus_t *status
	    The	command	returns	the current state of buttons and movement
	    counts in the following structure.

	    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;

	    The	button and obutton fields hold the current and the previous
	    state of the mouse buttons.	 When a	button is pressed, the corre-
	    sponding bit is set.  The mouse drivers may	support	up to 31 but-
	    tons with the bit 0	through	31.  Few button	bits are defined as
	    MOUSE_BUTTON1DOWN through MOUSE_BUTTON8DOWN.  The first three but-
	    tons 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.

FILES
     /dev/cuad%d      serial ports
     /dev/mse%d	      bus and InPort mouse device
     /dev/psm%d	      PS/2 mouse device
     /dev/sysmouse    virtual mouse device
     /dev/ums%d	      USB mouse	device

SEE ALSO
     ioctl(2), mse(4), psm(4), sysmouse(4), ums(4), moused(8)

AUTHORS
     This manual page was written by Kazutaka Yokota <yokota@FreeBSD.org>.

FreeBSD	10.1		       December	3, 1997			  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | IOCTLS | FILES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=mouse&sektion=4&manpath=FreeBSD+8.4-RELEASE>

home | help