diff options
Diffstat (limited to 'share/man/man4/sysmouse.4')
| -rw-r--r-- | share/man/man4/sysmouse.4 | 472 |
1 files changed, 472 insertions, 0 deletions
diff --git a/share/man/man4/sysmouse.4 b/share/man/man4/sysmouse.4 new file mode 100644 index 0000000..f93fa8e --- /dev/null +++ b/share/man/man4/sysmouse.4 @@ -0,0 +1,472 @@ +.\" Copyright 1997 John-Mark Gurney. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY John-Mark Gurney AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 25, 2014 +.Dt SYSMOUSE 4 +.Os +.Sh NAME +.Nm sysmouse +.\" .Nd supplies mouse data from syscons for other applications +.Nd virtualized mouse driver +.Sh SYNOPSIS +.In sys/mouse.h +.In sys/consio.h +.Sh DESCRIPTION +The console driver, in conjunction with the mouse daemon +.Xr moused 8 , +supplies mouse data to the user process in the standardized way via the +.Nm +driver. +This arrangement makes it possible for the console and the user process +(such as the +.Tn X\ Window System ) +to share the mouse. +.Pp +The user process which wants to utilize mouse operation simply opens +.Pa /dev/sysmouse +with a +.Xr open 2 +call and reads +mouse data from the device via +.Xr read 2 . +Make sure that +.Xr moused 8 +is running, otherwise the user process will not see any data coming from +the mouse. +.Pp +.Ss Operation Levels +The +.Nm +driver has two levels of operation. +The current operation level can be referred to and changed via ioctl calls. +.Pp +The level zero, the basic level, is the lowest level at which the driver +offers the basic service to user programs. +The +.Nm +driver +provides horizontal and vertical movement of the mouse +and state of up to three buttons in the +.Tn MouseSystems +format as follows. +.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 +The first half of horizontal movement count in two's complement; +\-128 through 127. +.It Byte 3 +The first half of vertical movement count in two's complement; +\-128 through 127. +.It Byte 4 +The second half of the horizontal movement count in two's complement; +\-128 through 127. +To obtain the full horizontal movement count, add +the byte 2 and 4. +.It Byte 5 +The second half of the vertical movement count in two's complement; +\-128 through 127. +To obtain the full vertical movement count, add +the byte 3 and 5. +.El +.Pp +At the level one, the extended level, mouse data 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. +.Sh IOCTLS +This section describes two classes of +.Xr ioctl 2 +commands: +commands for the +.Nm +driver itself, and commands for the console and the console control drivers. +.Ss Sysmouse Ioctls +There are a few commands for mouse drivers. +General description of the commands is given in +.Xr mouse 4 . +Following are 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 mouse driver. +.Pp +.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw +Returns the hardware information of the attached device in the following +structure. +Only the +.Va iftype +field is guaranteed to be filled with the correct value in 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 +.Va buttons +field holds the number of buttons detected by the driver. +.Pp +The +.Va iftype +is always +.Dv MOUSE_IF_SYSMOUSE . +.Pp +The +.Va type +tells the device type: +.Dv MOUSE_MOUSE , +.Dv MOUSE_TRACKBALL , +.Dv MOUSE_STICK , +.Dv MOUSE_PAD , +or +.Dv MOUSE_UNKNOWN . +.Pp +The +.Va 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 +.Va hwid +is always zero. +.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) */ + 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 +.Va protocol +field tells the format in which the device status is returned +when the mouse data is read by the user program. +It is +.Dv MOUSE_PROTO_MSC +at the operation level zero. +.Dv MOUSE_PROTO_SYSMOUSE +at the operation level one. +.Pp +The +.Va rate +is always set to \-1. +.Pp +The +.Va resolution +is always set to \-1. +.Pp +The +.Va accelfactor +is always 0. +.Pp +The +.Va 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 +.Va syncmask +holds a bit mask and pattern to detect the first byte of the +data packet. +.Va syncmask[0] +is the bit mask to be ANDed with a byte. +If the result is equal to +.Va 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, it should be taken only as an advisory measure. +.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 +.Va level +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 in the structure as defined in +.Xr mouse 4 . +.El +.Ss Console and Consolectl Ioctls +The user process issues console +.Fn ioctl +calls to the current virtual console in order to control +the mouse pointer. +The console +.Fn ioctl +also provides a method for the user process to receive a +.Xr signal 3 +when a button is pressed. +.Pp +The mouse daemon +.Xr moused 8 +uses +.Fn ioctl +calls to the console control device +.Pa /dev/consolectl +to inform the console of mouse actions including mouse movement +and button status. +.Pp +Both classes of +.Fn ioctl +commands are defined as +.Dv CONS_MOUSECTL +which takes the following argument. +.Bd -literal +struct mouse_info { + int operation; + union { + struct mouse_data data; + struct mouse_mode mode; + struct mouse_event event; + } u; +}; +.Ed +.Pp +.Bl -tag -width operation -compact +.It Va operation +This can be one of +.Pp +.Bl -tag -width MOUSE_MOVEABS -compact +.It Dv MOUSE_SHOW +Enables and displays mouse cursor. +.It Dv MOUSE_HIDE +Disables and hides mouse cursor. +.It Dv MOUSE_MOVEABS +Moves mouse cursor to position supplied in +.Va u.data . +.It Dv MOUSE_MOVEREL +Adds position supplied in +.Va u.data +to current position. +.It Dv MOUSE_GETINFO +Returns current mouse position in the current virtual console +and button status in +.Va u.data . +.It Dv MOUSE_MODE +This sets the +.Xr signal 3 +to be delivered to the current process when a button is pressed. +The signal to be delivered is set in +.Va u.mode . +.El +.Pp +The above operations are for virtual consoles. +The operations defined +below are for the console control device and are used by +.Xr moused 8 +to pass mouse data to the console driver. +.Pp +.Bl -tag -width MOUSE_MOVEABS -compact +.It Dv MOUSE_ACTION +.It Dv MOUSE_MOTION_EVENT +These operations take the information in +.Va u.data +and act upon it. +Mouse data will be sent to the +.Nm +driver if it is open. +.Dv 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. +.It Dv MOUSE_BUTTON_EVENT +.Va 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. +.El +.Pp +.Dv MOUSE_MOTION_EVENT +and +.Dv MOUSE_BUTTON_EVENT +are newer interface and are designed to be used together. +They are intended to replace functions performed by +.Dv MOUSE_ACTION +alone. +.Pp +.It Va u +This union is one of +.Pp +.Bl -tag -width data -compact +.It Va data +.Bd -literal +struct mouse_data { + int x; + int y; + int z; + int buttons; +}; +.Ed +.Pp +.Va x , y +and +.Va z +represent movement of the mouse along respective directions. +.Va 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 corresponding bit is set. +.Pp +.It Va mode +.Bd -literal +struct mouse_mode { + int mode; + int signal; +}; +.Ed +.Pp +The +.Va signal +field specifies the signal to be delivered to the process. +It must be +one of the values defined in +.In signal.h . +The +.Va mode +field is currently unused. +.Pp +.It Va event +.Bd -literal +struct mouse_event { + int id; + int value; +}; +.Ed +.Pp +The +.Va id +field specifies a button number as in +.Va u.data.buttons . +Only one bit/button is set. +The +.Va value +field +holds the click count: the number of times the user has clicked the button +successively. +.El +.El +.Sh FILES +.Bl -tag -width /dev/consolectl -compact +.It Pa /dev/consolectl +device to control the console +.It Pa /dev/sysmouse +virtualized mouse driver +.It Pa /dev/ttyv%d +virtual consoles +.El +.Sh SEE ALSO +.Xr vidcontrol 1 , +.Xr ioctl 2 , +.Xr signal 3 , +.Xr mouse 4 , +.Xr moused 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 2.2 . +.Sh AUTHORS +.An -nosplit +This +manual page was written by +.An John-Mark Gurney Aq jmg@FreeBSD.org +and +.An Kazutaka Yokota Aq yokota@FreeBSD.org . |
