diff options
Diffstat (limited to 'share/man/man4/man4.i386/sysmouse.4')
| -rw-r--r-- | share/man/man4/man4.i386/sysmouse.4 | 411 |
1 files changed, 366 insertions, 45 deletions
diff --git a/share/man/man4/man4.i386/sysmouse.4 b/share/man/man4/man4.i386/sysmouse.4 index 41758ef..6bcc37b 100644 --- a/share/man/man4/man4.i386/sysmouse.4 +++ b/share/man/man4/man4.i386/sysmouse.4 @@ -25,51 +25,300 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id$ +.\" $Id: sysmouse.4,v 1.5 1997/03/07 02:49:59 jmg Exp $ .\" -.Dd February 14, 1997 +.Dd December 3, 1997 .Dt SYSMOUSE 4 i386 -.Os +.Os FreeBSD .Sh NAME .Nm sysmouse -.Nd supplies mouse data from syscons for other applications +.\" .Nd supplies mouse data from syscons for other applications +.Nd virtualized mouse driver .Sh SYNOPSIS +.Fd #include <machine/mouse.h> .Fd #include <machine/console.h> -.Ft int -.Fn ioctl cfd CONS_MOUSECTL struct\ *mouse_info .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 +.Pq 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 won't see any data coming from +the mouse. +.Pp +.Ss Operation Levels The -.Dv CONS_MOUSECTL -.Fn ioctl -call provides syscons with mouse information, which includes mouse movement -and button presses. 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 compliment; +-128 through 127. +.It Byte 3 +The first half of vertical movement count in two's compliment; +-128 through 127. +.It Byte 4 +The second half of the horizontal movement count in two's compliment; +-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 compliment; +-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 . +Followings 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 +.Dv 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 +.Dv buttons +field holds the number of buttons detected by the driver. +.Pp +The +.Dv iftype +is always +.Dv MOUSE_IF_SYSMOUSE. +.Pp +The +.Dv type +tells the device type: +.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 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 +.Dv 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 +.Dv rate +is always set to -1. +.Pp +The +.Dv resolution +is always set to -1. +.Pp +The +.Dv accelfactor +is always 0. +.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 method of detecting the first byte is not 100% reliable, +thus, 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 +.Dv 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_GETSTATE 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 -also provides a method for a process to receive a +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 this +uses .Fn ioctl -to inform the console of mouse actions. Applications -.Pq such as Tn X\ Windows -can use -.Pa /dev/sysmouse , -allowing syscons and the application to share the mouse. +calls to the console control device +.Pa /dev/consolectl +to inform the console of mouse actions including mouse movement +and button status. .Pp -.Bd -literal -offset indent +Both classes +.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; - }u; + int operation; + union { + struct mouse_data data; + struct mouse_mode mode; + struct mouse_event event; + } u; }; .Ed -.Bl -tag -width operation +.Pp +.Bl -tag -width operation -compact .It Dv operation This can be one of -.Bl -tag -width MOUSE_MOVEABS +.Pp +.Bl -tag -width MOUSE_MOVEABS -compact .It Dv MOUSE_SHOW Enables and displays mouse cursor. .It Dv MOUSE_HIDE @@ -78,11 +327,12 @@ Disables and hides mouse cursor. Moves mouse cursor to position supplied in .Dv u.data . .It Dv MOUSE_MOVEREL -Add position supplied in +Adds position supplied in .Dv u.data to current position. .It Dv MOUSE_GETINFO -Returns current mouse position and button status in +Returns current mouse position in the current virtual console +and button status in .Dv u.data . .It Dv MOUSE_MODE This sets the @@ -90,34 +340,99 @@ This sets the to be delivered to the current process when a button is pressed. The signal to be delivered is set in .Dv u.mode . +.El +.Pp +The above operations are for virtual consoles. The operations defined +below are for the console control device and used by +.Xr moused 8 +to pass mouse data to the console driver. +.Pp +.Bl -tag -width MOUSE_MOVEABS -compact .It Dv MOUSE_ACTION -This takes the information in +.It Dv MOUSE_MOTIONEVENT +These operations take the information in .Dv u.data -and acts upon it. It includes processing button presses if the current vty -is a text interface, and sending -.Tn Mouse System -protocol data to -.Pa /dev/sysmouse -if it is open. +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_BUTTONEVENT +.Dv 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_MOTIONEVENT +and +.Dv MOUSE_BUTTONEVENT +are newer interface and are designed to be used together. +They are intended to replace functions performed by +.Dv MOUSE_ACTION +alone. +.Pp .It Dv u This union is one of -.Bl -tag -width data +.Pp +.Bl -tag -width data -compact .It Dv data -.Bd -literal -offset indent +.Bd -literal struct mouse_data { - int x; - int y; - int buttons; + int x; + int y; + int z; + int buttons; }; .Ed +.Pp +.Dv x , +.Dv y +and +.Dv z +represent movement of the mouse along respective directions. +.Dv 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 Dv mode -.Bd -literal -offset indent +.Bd -literal struct mouse_mode { - int mode; - int signal; + int mode; + int signal; }; .Ed +.Pp +The +.Dv signal +field specifies the signal to be delivered to the process. It must be +one of the values defined in +.Ao Pa signal.h Ac . +The +.Dv mode +field is currently unused. +.Pp +.It Dv event +.Bd -literal +struct mouse_event { + int id; + int value; +}; +.Ed +.Pp +The +.Dv id +field specifies a button number as in +.Dv u.data.buttons . +Only one bit/button is set. +The +.Dv value +field +holds the click count: the number of times the user has clicked the button +successively. +.Pp .El .El .Sh FILES @@ -125,11 +440,15 @@ struct mouse_mode { .It Pa /dev/consolectl device to control the console .It Pa /dev/sysmouse -mouse action output +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 @@ -138,5 +457,7 @@ manual page example first appeared in .Fx 2.2 . .Sh AUTHOR This -manual page was written by John-Mark Gurney -.Aq gurney_j@efn.org . +manual page was written by +.An John-Mark Gurney Aq gurney_j@efn.org +and +.An Kazutaka YOKOTA Aq yokota@FreeBSD.org . |
