From 6acb892697598e36622fb1f60f6ca986915c31c1 Mon Sep 17 00:00:00 2001 From: yokota Date: Sun, 7 Dec 1997 08:46:56 +0000 Subject: Document recent mouse code changes. --- share/man/man4/man4.i386/mouse.4 | 382 +++++++++++++++++++++ share/man/man4/man4.i386/mse.4 | 348 ++++++++++++++++++- share/man/man4/man4.i386/psm.4 | 648 +++++++++++++++++++++++++----------- share/man/man4/man4.i386/sysmouse.4 | 411 ++++++++++++++++++++--- share/man/man4/mouse.4 | 382 +++++++++++++++++++++ share/man/man4/psm.4 | 648 +++++++++++++++++++++++++----------- share/man/man4/sysmouse.4 | 411 ++++++++++++++++++++--- 7 files changed, 2733 insertions(+), 497 deletions(-) create mode 100644 share/man/man4/man4.i386/mouse.4 create mode 100644 share/man/man4/mouse.4 (limited to 'share/man/man4') diff --git a/share/man/man4/man4.i386/mouse.4 b/share/man/man4/man4.i386/mouse.4 new file mode 100644 index 0000000..7cb00ef --- /dev/null +++ b/share/man/man4/man4.i386/mouse.4 @@ -0,0 +1,382 @@ +.\" +.\" Copyright (c) 1997 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 THE AUTHOR ``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 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. +.\" +.\" $Id:$ +.\" +.Dd December 3, 1997 +.Dt MOUSE 4 i386 +.Os FreeBSD +.Sh NAME +.Nm mouse +.Nd mouse and pointing device drivers +.Sh SYNOPSIS +.Fd #include +.Sh DESCRIPTION +The mouse drivers +.Xr mse 4 , +.Xr psm 4 +and +.Xr sysmouse 4 +provide user programs with movement and button state information of the mouse. +Currently there are specific device drivers for bus, InPort and PS/2 mice. +The serial mouse is not directly supported by a dedicated driver, but +it is accessible via the serial device driver or via +.Xr moused 8 +and +.Xr sysmouse 4 . +.Pp +The user program simply opens a mouse device with a +.Xr open 2 +call and reads +mouse data from the device via +.Xr 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. +.Pp +The mouse drivers may have ``non-blocking'' attribute which will make +the driver return immediately if mouse data is not available. +.Pp +Mouse device drivers often offer several levels of operation. +The current operation level can be examined and changed via +.Xr 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 +.Dv MOUSE_PROTO_SYSMOUSE +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. +.It Byte 6 +The bit 7 is always zero. The lower 7 bits encode the first half of +Z axis movement count in two's compliment; -64 through 63. +.It 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 compliment; -64 through 63. +To obtain the full Z axis movement count, add the byte 6 and 7. +.It 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 corresponding bit is cleared. Otherwise +the bit is set. +.El +.Pp +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. +.Pp +Device drivers may offer operation levels higher than one. +Refer to manual pages of individual drivers for details. +.Sh IOCTLS +The following +.Xr 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. +.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 +Except for the +.Dv iftype +field, the device driver may not always fill the structure with correct +values. +Consult manual pages of individual drivers for details of support. +.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. The driver +may put an arbitrary value, such as two, in this field, if it cannot +determine the exact number. +.Pp +The +.Dv iftype +is the type of interface: +.Dv MOUSE_IF_SERIAL , +.Dv MOUSE_IF_BUS , +.Dv MOUSE_IF_INPORT , +.Dv MOUSE_IF_PS2 , +.Dv MOUSE_IF_SYSMOUSE +or +.Dv MOUSE_IF_UNKNOWN . +.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 +may be +.Dv MOUSE_MODEL_GENERIC +or one of +.Dv MOUSE_MODEL_XXX +constants. +.Pp +The +.Dv 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. +.Pp +.It Dv MOUSE_GETMODE Ar mousemode_t *mode +The command reports 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 one of +.Dv MOUSE_PROTO_XXX +constants. +.Pp +The +.Dv 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. +.Pp +The +.Dv resolution +field holds a value specifying resolution of the pointing device. +It is a positive value or one of +.Dv MOUSE_RES_XXX +constants. +.Pp +The +.Dv accelfactor +field holds a value to control acceleration feature. +It must be zero or greater. +If it is zero, acceleration is disabled. +.Pp +The +.Dv 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. +.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 rate , +.Dv resolution , +.Dv level +and +.Dv accelfactor +may be modifiable. Setting values in the other field does not generate +error and has no effect. +.Pp +If you do not want to change the current setting of a field, put -1 +there. +You may also put zero in +.Dv resolution +and +.Dv rate , +and the default value for the fields will be selected. +.\" .Pp +.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars +.\" Get internal variables of the mouse driver. +.\" The variables which can be manipulated through these commands +.\" are specific to each driver. +.\" This command may not be supported by all drivers. +.\" .Bd -literal +.\" typedef struct mousevar { +.\" int var[16]; /* internal variables */ +.\" } mousevar_t; +.\" .Ed +.\" .Pp +.\" If the commands are supported, the first element of the array is +.\" filled with a signature value. +.\" Apart from the signature data, there is currently no standard concerning +.\" the other elements of the buffer. +.\" .Pp +.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars +.\" Get internal variables of the mouse driver. +.\" The first element of the array must be a signature value. +.\" This command may not be supported by all drivers. +.Pp +.It Dv MOUSE_READDATA Ar mousedata_t *data +The command reads the raw data from the device. +.Bd -literal +typedef struct mousedata { + int len; /* # of data in the buffer */ + int buf[16]; /* data buffer */ +} mousedata_t; +.Ed +.Pp +The calling process must fill the +.Dv len +field with the number of bytes to be read into the buffer. +This command may not be supported by all drivers. +.Pp +.It Dv MOUSE_READSTATE Ar 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. +.Pp +.It Dv MOUSE_GETSTATE Ar mousestatus_t *status +The command returns the current state of buttons and +movement counts in the following structure. +.Bd -literal +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; +.Ed +.Pp +The +.Dv button +and +.Dv 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 +.Dv MOUSE_BUTTON1DOWN +through +.Dv MOUSE_BUTTON8DOWN . +The first three buttons correspond to left, middle and right buttons. +.Pp +If the state of the button has changed since the last +.Dv MOUSE_GETSTATE +call, the corresponding bit in the +.Dv flags +field will be set. +If the mouse has moved since the last call, the +.Dv MOUSE_POSCHANGED +bit in the +.Dv flags +field will also be set. +.Pp +The other fields hold movement counts since the last +.Dv MOUSE_GETSTATE +call. The internal counters will be reset after every call to this +command. +.El +.Sh FILES +.Bl -tag -width /dev/sysmouseXX -compact +.It Pa /dev/cuaa%d +serial ports +.It Pa /dev/mse%d +bus and InPort mouse device +.It Pa /dev/psm%d +PS/2 mouse device +.It Pa /dev/sysmouse +virtual mouse device +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr mse 4 , +.Xr psm 4 , +.Xr sysmouse 4 , +.Xr moused 8 +.\".Sh HISTORY +.Sh AUTHOR +This manual page was written by +.An Kazutaka YOKOTA Aq yokota@FreeBSD.org . diff --git a/share/man/man4/man4.i386/mse.4 b/share/man/man4/man4.i386/mse.4 index cca88e2..9e3202c 100644 --- a/share/man/man4/man4.i386/mse.4 +++ b/share/man/man4/man4.i386/mse.4 @@ -10,26 +10,344 @@ .\" this software for any purpose. It is provided "as is" .\" without express or implied warranty. .\" -.\" $Id$ +.\" $Id: mse.4,v 1.3 1997/03/07 02:49:53 jmg Exp $ .\" -.Dd Aug 16, 1992 +.Dd December 3, 1997 .Dt MSE 4 i386 -.Os +.Os FreeBSD .Sh NAME .Nm mse -.Nd bus mouse driver +.Nd bus and InPort mice driver +.Sh SYNOPSIS +.\" .Cd "options" \&"MSE_XXX=N\&" +.Cd "device mse0 at isa? port" 0x23c tty irq 5 vector mseintr .Sh DESCRIPTION -This is a simple driver for the Logitech and ATI Inport bus mouse interfaces -designed to be used with the X386 X11R5 X server. The minor device number is -made up of: +The +.Nm +driver provides support for the bus mouse and the InPort mouse, which +are often collectively called ``bus'' mice, as these mice are sold with +an interface card which needs to be installed in an expansion bus slot. +The interface circuit may come on an integrated I/O card or as an option +on video cards. +.Pp +The bus and InPort mice have two or three buttons, +and a D-sub 9-pin male connector or a round DIN 9-pin +male connector. +.Pp +The primary port address of the bus and InPort mouse interface cards +is usually 0x23c. Some cards may also be set to use the secondary port +address at 0x238. The interface cards require a single IRQ, which may be +2, 3, 4 or 5. Some cards may offer additional IRQs. +The port number and the IRQ number are configured by jumpers on the cards +or by software provided with the card. +.Pp +Frequency, or report rate, at which the device sends movement +and button state reports to the host system, may also be configurable on +some interface cards. It may be 15, 30, 60 or 120Hz. +.Pp +The difference between the two types of the mice is not in mouse devices +(in fact they are exactly the same). But in the circuit on the interface +cards. This means that the device from a bus mouse package can be +connected to the interface card from an InPort mouse package, or vice +versa, provided that their connectors match. +.Ss Operation Levels +The +.Nm +driver has two levels of operation. +The current operation level can be set via an ioctl call. +.Pp +At the level zero the basic support is provided; the device driver will report +horizontal and vertical movement of the attached device +and state of up to three buttons in the format described below. +It is a subset of the MouseSystems protocol. +.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 +Horizontal movement count in two's compliment; -128 through 127. +.It Byte 3 +Vertical movement count in two's compliment; -128 through 127. +.It Byte 4 +Always zero. +.It Byte 5 +Always zero. +.El +.Pp +This is the default level of operation and the driver is initially +at this level when opened by the user program. +.Pp +At the operation level one (extended level), a data packet 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. +.Ss Device Number +The minor device number of the +.Nm +is made up of: .Bd -literal -offset indent -minor = ('unit' << 1) | 'non-blocking' +minor = (`unit' << 1) | `non-blocking' .Ed .Pp -where 'unit' is the device number (usually 0) and the 'non-blocking' bit -is set to indicate "don't block waiting for mouse input, return 0 instead". -The 'non-blocking' bit should be set for X386, therefore the minor device -number usually used for X386 is 1. -.Sh Caveats -Most bus mice generate N interrupts/second when enabled, whether or not the -mouse state is changing. +where `unit' is the device number (usually 0) and the `non-blocking' bit +is set to indicate ``don't block waiting for mouse input, +return immediately''. +The `non-blocking' bit should be set for \fIXFree86\fP, +therefore the minor device number usually used for \fIXFree86\fP is 1. +See +.Sx FILES +for device node names. +.Sh DRIVER CONFIGURATION +.\" .Ss Kernel Configuration Options +.Ss Driver Flags +The +.Nm +driver accepts the following driver flag. Set it in the +kernel configuration file +.Pq see Xr config 8 +or in the User Configuration Menu at +the boot time +.Pq see Xr boot 8 . +.Pp +.Bl -tag -width MOUSE +.It bit 4..7 ACCELERATION +This flag controls the amount of acceleration effect. +The smaller the value of this flag is, more sensitive the movement becomes. +The minimum value allowed, thus the value for the most sensitive setting, +is one. Setting this flag to zero will completely disables the +acceleration effect. +.El +.Sh IOCTLS +There are a few +.Xr ioctl 2 +commands for mouse drivers. +These commands and related structures and constants are defined in +.Ao Pa machine/mouse.h Ac . +General description of the commands is given in +.Xr mouse 4 . +This section explains 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 +.Nm +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 by 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 on the device. +.Pp +The +.Dv iftype +is either +.Dv MOUSE_IF_BUS +or +.Dv MOUSE_IF_INPORT . +.Pp +The +.Dv type +may be +.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 0. +.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), -1 if unknown */ + 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 +is either +.Dv MOUSE_PROTO_BUS +or +.Dv MOUSE_PROTO_INPORT +at the operation level zero. +.Dv MOUSE_PROTO_SYSMOUSE +at the operation level one. +.Pp +The +.Dv rate +is the status report rate (reports/sec) at which the device will send +movement report to the host computer. +As there is no standard to detect the current setting, +this field is always set to -1. +.Pp +The +.Dv resolution +is always set to -1. +.Pp +The +.Dv accelfactor +field holds a value to control acceleration feature +.Pq see Sx Acceleration . +It is zero or greater. +If it is zero, acceleration is disabled. +.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 detection method is not 100% reliable, +thus, should be taken only as an advisory measure. +.Pp +Only +.Dv level +and +.Dv accelfactor +are modifiable by the +.Dv MOUSE_SETMODE +command. +Changing the other field doesn't cause error, but has no effect. +.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 +and +.Dv accelfactor +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 as described in +.Xr mouse 4 . +.El +.Sh FILES +.Bl -tag -width /dev/nmse0 -compact +.It Pa /dev/mse0 +`non-blocking' device node in the system without +.Em devfs , +`blocking' under +.Em devfs . +.It Pa /dev/nmse0 +`non-blocking' device node under +.Em devfs . +.El +.Sh EXAMPLE +.Dl "device mse0 at isa? port" 0x23c tty irq 5 vector mseintr +.Pp +Add the +.Nm +driver at the primary port address with the IRQ 5. +.Pp +.Dl "device mse1 at isa? port" 0x238 tty flags 0x30 irq 4 vector mseintr +.Pp +Define the +.Nm +driver at the secondary port address with the IRQ 4 and the acceleration +factor of 3. +.Sh CAVEAT +Some bus mouse interface cards generate interrupts at the fixed report rate +when enabled, whether or not the mouse state is changing. +The others generate interrupts only when the state is changing. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr mouse 4 , +.Xr psm 4 , +.Xr sysmouse 4 , +.Xr moused 8 +.\".Sh HISTORY diff --git a/share/man/man4/man4.i386/psm.4 b/share/man/man4/man4.i386/psm.4 index d154294..4797bab 100644 --- a/share/man/man4/man4.i386/psm.4 +++ b/share/man/man4/man4.i386/psm.4 @@ -1,6 +1,32 @@ -.\" $Id: psm.4,v 1.8 1997/10/19 10:45:18 yokota Exp $ .\" -.Dd January 13, 1997 +.\" Copyright (c) 1997 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 THE AUTHOR ``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 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. +.\" +.\" $Id: psm.4,v 1.7 1997/02/22 13:25:39 peter Exp $ +.\" +.Dd December 3, 1997 .Dt PSM 4 i386 .Os FreeBSD .Sh NAME @@ -8,9 +34,6 @@ .Nd PS/2 mouse style pointing device driver .Sh SYNOPSIS -.Cd "options PSM_CHECKSYNC" -.\".Cd "options PSM_EMULATION" -.Cd "options" \&"PSM_ACCEL=N\&" .Cd "options" \&"PSM_HOOKAPM\&" .Cd "options" \&"PSM_RESETAFTERSUSPEND\&" .Cd "options" \&"KBD_RESETDELAY=N\&" @@ -22,23 +45,79 @@ PS/2 mouse style pointing device driver The .Nm driver provides support for the PS/2 mouse style pointing device. - +Currently there can be only one +.Nm +device node in the system. .Em port \&"IO_KBD\&" and .Em conflicts are required, as the PS/2 mouse port is located -at the auxiliary port of the keyboard controller, thus, the +at the auxiliary port of the keyboard controller; the .Nm driver has to share the same I/O ports with the keyboard driver. Note also that there is currently no provision of changing the .Em irq number. .Pp -A series of data packets is read from the +Basic PS/2 style pointing device has two or three buttons. +Some devices may have a roller or a wheel and/or additional buttons. +.Ss Device Resolution +The PS/2 style pointing device usually has several grades of resolution, +that is, sensitivity of movement. They are typically 25, 50, 100 and 200 +pulse per inch. Some devices may have finer resolution. +The current resolution can be changed at runtime. The .Nm -driver. A data packet from the PS/2 mouse style pointing device -is three bytes long: +driver allows the user to initially set the resolution +via the driver flag +.Pq see Sx DRIVER CONFIGURATION +or change it later via the +.Xr ioctl 2 +command +.Dv MOUSE_SETMODE +.Pq see Sx IOCTLS . +.Ss Report Rate +Frequency, or report rate, at which the device sends movement +and button state reports to the host system is also configurable. +The PS/2 style pointing device typically supports 10, 20, 40, 60, 80, 100 +and 200 reports per second. +60 or 100 appears to be the default value for many devices. +Note that when there is no movement and no button has changed its state, +the device won't send anything to the host system. +The report rate can be changed via an ioctl call. +.Ss Operation Levels +The +.Nm +driver has three levels of operation. +The current operation level can be set via an ioctl call. +.Pp +At the level zero the basic support is provided; the device driver will report +horizontal and vertical movement of the attached device +and state of up to three buttons. +The movement and status are encoded in a series of fixed-length data packets +.Pq see Sx Data Packet Format . +This is the default level of operation and the driver is initially +at this level when opened by the user program. +.Pp +The operation level one, the `extended' level, supports a roller (or wheel), +if any, and up to 11 buttons. +The movement of the roller is reported as movement along the Z axis. +8 byte data packets are sent to the user program at this level. +.Pp +At the operation level two, data from the pointing device is passed to the +user program as is. +Modern PS/2 type pointing devices often use proprietary data format. +Therefore, the user program is expected to have +intimate knowledge about the format from a particular device when operating +the driver at this level. +This level is called `native' level. +.Ss Data Packet Format +Data packets read from the +.Nm +driver are formatted differently at each operation level. +.Pp +A data packet from the PS/2 mouse style pointing device +is three bytes long at the operation level zero: .Pp .Bl -tag -width Byte_1 -compact .It Byte 1 @@ -52,12 +131,13 @@ Set if the vertical movement count is negative. .It bit 4 Set if the horizontal movement count is negative. .It bit 3 -The ALPS GlidePoint clears this bit when the user `taps' the surface of -the pad, otherwise the bit is set. -Most, if not all, other devices always sets this bit. +Always one. +.\" The ALPS GlidePoint clears this bit when the user `taps' the surface of +.\" the pad, otherwise the bit is set. +.\" Most, if not all, other devices always set this bit. .It bit 2 Middle button status; set if pressed. For devices without the middle -button, this bit seems to be always zero. +button, this bit is always zero. .It bit 1 Right button status; set if pressed. .It bit 0 @@ -73,6 +153,24 @@ Vertical movement count in two's compliment; Note that the sign bit is in the first byte. .El .Pp +At the level one, a data packet is encoded +in the standard format +.Dv MOUSE_PROTO_SYSMOUSE +as defined in +.Xr mouse 4 . +.Pp +At the level two, native level, there is no standard on the size and format +of the data packet. +.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. +.Ss Device Number The minor device number of the .Nm is made up of: @@ -88,48 +186,14 @@ therefore the minor device number usually used for \fIXFree86\fP is 1. See .Sx FILES for device node names. -.Sh KERNEL CONFIGURATION -There are following options to control the +.Sh DRIVER CONFIGURATION +.Ss Kernel Configuration Options +There are following kernel configuration options to control the .Nm driver. +They may be set in the kernel configuration file +.Pq see Xr config 8 . .Bl -tag -width MOUSE -.It Em PSM_CHECKSYNC -If this option is defined, the driver tries to detect the first byte of -the three-byte data packet, by checking the bit pattern of that byte. -This may be useful if you often experience wierd mouse movement -cased by unsynchronization between the application program and the mouse. -However, the -.Em PSM_CHECKSYNC -code may not always work; some systems, mostly notebooks, set the bit -pattern differently from the others. -Note also that the `tapping' feature of the ALPS GlidePoint will be -lost when this option is used. -.\".It Em PSM_EMULATION -.\"The -.\".Nm -.\"driver can emulate the Microsoft Serial Mouse's three-byte -.\"data packet and the Mouse Systems Corp's five-byte data packet -.\"when data is read by user programs, if so specified by the -.\".Fn ioctl -.\"command -.\".Dv MOUSE_SETMODE . -.\"To enable the emulation feature, define this option. -.It Em PSM_ACCEL=N -The -.Nm -driver can somewhat `accelerate' the movement of the pointing device. -That is, the faster you move the device, the further the pointer -travels on the screen. This option controls the amount of acceleration. -The smaller -.Fa N -is, more sensitive the movement becomes. -The minimum value allowed, thus the value for the most sensitive setting, -is 1. Setting this option to zero will completely disables the -acceleration effect. The default value is 0 (acceleration disabled). -The acceleration effect can also be controlled via the -.Fn ioctl -command -.Dv MOUSE_SETMODE . .It Em PSM_HOOKAPM The built-in PS/2 pointing device of some laptop computers is somehow not operable immediately after the system `resumes' from @@ -175,70 +239,100 @@ The default debug level is zero. See .Sx DIAGNOSTICS for debug logging. .El -.Sh IOCTL -There are only few ioctls for the +.Ss Driver Flags +The .Nm -driver. These are defined in -.Ao Pa machine/mouse.h Ac . +driver accepts the following driver flags. Set them in the +kernel configuration file or in the User Configuration Menu at +the boot time +.Pq see Xr boot 8 . +.Pp .Bl -tag -width MOUSE -.It Dv MOUSEIOCREAD -The -.Dv MOUSEIOCREAD -command did NOT work before and does NOT work now. It is obsolete. -Use the -.Dv MOUSE_GETSTATE -command instead. -.It Dv MOUSE_GETSTATE -The command returns the current mouse state in the following structure -and remove the state information from the internal queue. -.Bd -literal -typedef struct mousestatus { - int button; /* button status */ - int obutton; /* previous button status */ - int dx; /* x movement */ - int dy; /* y movement */ -} mousestatus_t; -.Ed +.It bit 0..3 RESOLUTION +This flag specifies the resolution of the pointing device. +It must be zero through four. The greater the value +is, the finer resolution the device will select. +Actual resolution selected by this field varies according to the model +of the device. Typical resolutions are: .Pp +.Bl -tag -width 0_(medium_high)__ -compact +.It Em 1 (low) +25 pulse per inch (ppi) +.It Em 2 (medium low) +50 ppi +.It Em 3 (medium high) +100 ppi +.It Em 4 (high) +200 ppi +.El +.Pp +Leaving this flag zero will selects the default resolution for the +device (whatever it is). +.It bit 4..7 ACCELERATION +This flag controls the amount of acceleration effect. +The smaller the value of this flag is, more sensitive the movement becomes. +The minimum value allowed, thus the value for the most sensitive setting, +is one. Setting this flag to zero will completely disables the +acceleration effect. +.It bit 8 NOCHECKSYNC The -.Dv button -and the -.Dv obutton -fields hold the current and the previous state of the mouse buttons. -When a button is pressed, the corresponding bit is set. -These bits are defined as -.Dv MOUSE_BUTTON1DOWN -through -.Dv MOUSE_BUTTON8DOWN . -The first three buttons are left, middle and right buttons. -.Pp -Note that this command and -.Fn read -operation on the .Nm -driver uses the same internal queue. Therefore, interleaving the -.Dv MOUSE_GETSTATE -command and -.Fn read -operation is not recommended. -.It Dv MOUSE_GETHWINFO -Returns the hardware information in the following structure. +driver tries to detect the first byte of the data packet by checking +the bit pattern of that byte. Although this method should work with most +PS/2 pointing devices, it may interfere with some devices which are not +so compatible with known devices. +If you think your pointing device is not functioning as expected, +see if disabling synchronization check will help by setting this flag. +.El +.Sh IOCTLS +There are a few +.Xr ioctl 2 +commands for mouse drivers. +These commands and related structures and constants are defined in +.Ao Pa machine/mouse.h Ac . +General description of the commands is given in +.Xr mouse 4 . +This section explains 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 +.Nm +driver. +.Pp +.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw +Returns the hardware information of the attached device in the following +structure. .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 iftype -is -.Dv MOUSE_IF_PS2 -for the +.Dv buttons +field holds the number of buttons on the device. +The .Nm -driver. The +driver currently can detect the 3 button mouse from Logitech and report +accordingly. +The 3 button mouse from the other manufacturer may or may not be +reported correctly. However, it will not affect the operation of +the driver. +.Pp +The +.Dv iftype +is always +.Dv MOUSE_IF_PS2 . +.Pp +The .Dv type tells the device type: .Dv MOUSE_MOUSE , @@ -248,73 +342,240 @@ tells the device type: or .Dv MOUSE_UNKNOWN . The user should not heavily rely on this field, as the -.Nm driver may not always, in fact it is very rarely able to, identify the device type. +.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. +Again the +.Nm +driver may or may not set an appropriate value in this field. +.Pp The .Dv hwid -is the ID value returned by the pointing device. +is the ID value returned by the device. Known IDs include: +.Pp .Bl -tag -width 0__ -compact .It Em 0 Mouse (Microsoft, Logitech and many other manufacturers) .It Em 2 Microsoft Ballpoint mouse +.It Em 3 +Microsoft IntelliMouse .El -.It Dv MOUSE_GETMODE, MOUSE_SETMODE -The commands get and set the operation mode of the -.Nm +.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), -1 if unknown */ - int resolution; /* 1:low, 2:medium low, 3:medium high - * 4:high, 0: default, -1 if unknown - */ - int accelfactor; /* acceleration factor (must be 1 or greater) */ + 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 -selects the format with which the device status is returned by -.Fn read . -The default is -.Dv MOUSE_PROTO_PS2 , -that is, the data byte from the pointing device is read by user -programs as is. -No other value is allowed at the moment. -.\"Other possible values are: -.\".Dv MOUSE_PROTO_MSS -.\"and -.\".Dv MOUSE_PROTO_MSC , -.\"which specifies Microsoft Serial Mouse three-byte format and -.\"Mouse Systems Corp.'s five-byte format respectively. -.\"Note that the protocol cannot be set to anything other than -.\".Dv MOUSE_PROTO_PS2 -.\"unless the -.\".Em PSM_EMULATION -.\"option is specified in the kernel configuration file. +is +.Dv MOUSE_PROTO_PS2 +at the operation level zero and two. +.Dv MOUSE_PROTO_SYSMOUSE +at the operation level one. .Pp The .Dv rate is the status report rate (reports/sec) at which the device will send movement report to the host computer. +Typical supported values are 10, 20, 40, 60, 80, 100 and 200. +Some mice may accept other arbitrary values too. .Pp The .Dv resolution -of the pointing device must be zero through four. The higher the value -is, the finer resolution the mouse will select. Zero selects the -default resolution. +of the pointing device must be one of +.Dv MOUSE_RES_XXX +constants or a positive value. The greater the value +is, the finer resolution the mouse will select. +Actual resolution selected by the +.Dv MOUSE_RES_XXX +constant varies according to the model of mouse. Typical resolutions are: +.Pp +.Bl -tag -width MOUSE_RES_MEDIUMHIGH__ -compact +.It Dv MOUSE_RES_LOW +25 ppi +.It Dv MOUSE_RES_MEDIUMLOW +50 ppi +.It Dv MOUSE_RES_MEDIUMHIGH +100 ppi +.It Dv MOUSE_RES_HIGH +200 ppi +.El +.Pp +The +.Dv accelfactor +field holds a value to control acceleration feature +.Pq see Sx Acceleration . +It must be zero or greater. If it is zero, acceleration is disabled. .Pp The +.Dv packetsize +field specifies the length of the data packet. It depends on the +operation level and the model of the pointing device. +.Pp +.Bl -tag -width level_0__ -compact +.It Em level 0 +3 bytes +.It Em level 1 +8 bytes +.It Em level 2 +Depends on the model of the device +.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 detection method 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 rate , +.Dv resolution , +.Dv level +and .Dv accelfactor -holds a value to control acceleration feature (see description on -.Em PSM_ACCEL -above). It must be zero or greater. -If it is zero, acceleration is disabled. +may be modifiable. Setting values in the other field does not generate +error and has no effect. +.Pp +If you do not want to change the current setting of a field, put -1 +there. +You may also put zero in +.Dv resolution +and +.Dv rate , +and the default value for the fields will be selected. +.\" .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 +.\" The command reads the raw data from the device. +.\" .Bd -literal +.\" typedef struct mousedata { +.\" int len; /* # of data in the buffer */ +.\" int buf[16]; /* data buffer */ +.\" } mousedata_t; +.\" .Ed +.\" .Pp +.\" Upon returning to the user program, the driver will place the number +.\" of valid data bytes in the buffer in the +.\" .Dv len +.\" field. +.\" .Pp +.It Dv MOUSE_READSTATE Ar mousedata_t *state +.\" The command reads the hardware settings from the device. +.\" Upon returning to the user program, the driver will place the number +.\" of valid data bytes in the buffer in the +.\" .Dv len +.\" field. It is usually 3 bytes. +.\" The buffer is formatted as follows: +.\" .Pp +.\" .Bl -tag -width Byte_1 -compact +.\" .It Byte 1 +.\" .Bl -tag -width bit_6 -compact +.\" .It bit 7 +.\" Reserved. +.\" .It bit 6 +.\" 0 - stream mode, 1 - remote mode. +.\" In the stream mode, the pointing device sends the device status +.\" whenever its state changes. In the remote mode, the host computer +.\" must request the status to be sent. +.\" The +.\" .Nm +.\" driver puts the device in the stream mode. +.\" .It bit 5 +.\" Set if the pointing device is currently enabled. Otherwise zero. +.\" .It bit 4 +.\" 0 - 1:1 scaling, 1 - 2:1 scaling. +.\" 1:1 scaling is the default. +.\" .It bit 3 +.\" Reserved. +.\" .It bit 2 +.\" Left button status; set if pressed. +.\" .It bit 1 +.\" Middle button status; set if pressed. +.\" .It bit 0 +.\" Right button status; set if pressed. +.\" .El +.\" .It Byte 2 +.\" .Bl -tag -width bit_6_0 -compact +.\" .It bit 7 +.\" Reserved. +.\" .It bit 6..0 +.\" Resolution code: zero through three. Actual resolution for +.\" the resolution code varies from one device to another. +.\" .El +.\" .It Byte 3 +.\" The status report rate (reports/sec) at which the device will send +.\" movement report to the host computer. +.\" .El +These commands are not currently 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 as described in +.Xr mouse 4 . +.El +.Sh FILES +.Bl -tag -width /dev/npsm0 -compact +.It Pa /dev/psm0 +`non-blocking' device node in the system without +.Em devfs , +`blocking' under +.Em devfs . +.It Pa /dev/npsm0 +`non-blocking' device node under +.Em devfs . .El +.Sh EXAMPLE +.Dl "options" \&"PSM_HOOKAPM\&" +.Dl "device psm0 at isa? port" \&"IO_KBD\&" conflicts tty irq 12 vector psmintr +.Pp +Add the +.Nm +driver to the kernel with the optional code to stimulate the pointing device +after the `resume' event. +.Pp +.Dl "device psm0 at isa? port" \&"IO_KBD\&" conflicts tty flags 0x024 irq 12 +.Dl vector psmintr +.Pp +Set the device resolution high (4) and the acceleration factor to 2. .Sh DIAGNOSTICS .Pp At debug level 0, little information is logged except for the following @@ -332,23 +593,20 @@ for known IDs. .Pp At debug level 1 more information will be logged while the driver probes the auxiliary port (mouse port). -Messages are logged with the LOG_KERN facility at the LOG_DEBUG level. -(See -.Xr syslogd 8 . ) +Messages are logged with the LOG_KERN facility at the LOG_DEBUG level +.Pq see Xr syslogd 8 . .Bd -literal -offset indent psm0: current command byte:xxxx -kbdio: new command byte:yyyy (set_controller...) kbdio: TEST_AUX_PORT status:0000 kbdio: RESET_AUX return code:00fa kbdio: RESET_AUX status:00aa kbdio: RESET_AUX ID:0000 -psm0: status after reset 00 02 64 -psm: device ID: X -psm: status xx yy zz (get_mouse_buttons) -psm0: status 00 02 64 -kbdio: new command byte:zzzz (set_controller...) +[...] +psm: status 00 02 64 psm0 at 0x60-0x64 irq 12 on motherboard -psm0: device ID X, N buttons +psm0: model AAAA, device ID X, N buttons +psm0: config:00000www, flags:0000uuuu, packet size:M +psm0: syncmask:xx, syncbits:yy .Ed .Pp The first line shows the command byte value of the keyboard @@ -356,17 +614,20 @@ controller just before the auxiliary port is probed. It usually is 4D, 45, 47 or 65, depending on how the motherboard BIOS initialized the keyboard controller upon power-up. .Pp -The third line shows the result of the keyboard controller's +The second line shows the result of the keyboard controller's test on the auxiliary port interface, with zero indicating no error; note that some controllers report no error even if the port does not exist in the system, however. .Pp -The forth to sixth lines show the reset status of the pointing device. +The third through fifth lines show the reset status of the pointing device. The functioning device should return the sequence of FA AA . The ID code is described above. .Pp -The tenth line shows the current hardware settings; it consists -of three bytes: +The seventh line shows the current hardware settings. +.\" See +.\" .Dv MOUSE_READSTATE +.\" for definitions. +These bytes are formatted as follows: .Pp .Bl -tag -width Byte_1 -compact .It Byte 1 @@ -378,10 +639,14 @@ Reserved. In the stream mode, the pointing device sends the device status whenever its state changes. In the remote mode, the host computer must request the status to be sent. +The +.Nm +driver puts the device in the stream mode. .It bit 5 Set if the pointing device is currently enabled. Otherwise zero. .It bit 4 0 - 1:1 scaling, 1 - 2:1 scaling. +1:1 scaling is the default. .It bit 3 Reserved. .It bit 2 @@ -395,21 +660,9 @@ Right button status; set if pressed. .Bl -tag -width bit_6_0 -compact .It bit 7 Reserved. -.It bit 6-0 -Resolution code: zero through three. The higher the number is, -the finer resolution the device has. Actual resolution for +.It bit 6..0 +Resolution code: zero through three. Actual resolution for the resolution code varies from one device to another. -The typical values are: -.Bl -tag -width 100 -compact -.It 0 -25 pulse per inch (ppi) -.It 1 -50 ppi -.It 2 -100 ppi -.It 3 -200 ppi -.El .El .It Byte 3 The status report rate (reports/sec) at which the device will send @@ -418,30 +671,22 @@ movement report to the host computer. .Pp Note that the pointing device will not be enabled until the .Nm -driver is opened by the user programs. +driver is opened by the user program. .Pp -The last line shows the device ID code and the number of detected -buttons. Currently the -.Nm -driver can detect the 3 button mouse from Logitech and report -accordingly. -The 3 button mouse from the other manufacturer may or may not be -reported correctly. However, it will not affect the operation of -the driver. +The rest of the lines show the device ID code, the number of detected +buttons and internal variables. .Pp At debug level 2, much more detailed information is logged. -.Sh FILES -.Bl -tag -width /dev/npsm0 -compact -.It Pa /dev/psm0 -`non-blocking' device node in the system without -.Em devfs , -`blocking' under -.Em devfs . -.It Pa /dev/npsm0 -`non-blocking' device node under -.Em devfs . -.El .Sh CAVEATS +Many pad devices behave as if the first (left) button were pressed if +the user `taps' the surface of the pad. +In contrast, some ALPS GlidePoint pad models treat the tapping action +as fourth button events. +.Pp +Some PS/2 mouse models from MouseSystems require to be put in the +high resolution mode to work properly. Use the driver flag to +set resolution. +.Pp There is not a guaranteed way to re-synchronize with the first byte of the packet once we are out of synchronization with the data stream. However, if you are using the \fIXFree86\fP server and experiencing @@ -449,22 +694,33 @@ the problem, you may be able to make the X server synchronize with the mouse by switching away to a virtual terminal and getting back to the X server, unless the X server is accessing the mouse via .Xr moused 1 . -If you have specified the -.Em PSM_CHECKSYNC -option, clicking any button without moving the mouse may also work. +Clicking any button without moving the mouse may also work. .Sh BUGS -The -.Fn ioctl -command +The ioctl command .Dv MOUSEIOCREAD -(see -.Sx IOCTL -above) was never functional and will not be. The command name -still remains for compatibility reasons but may be removed in the future. +has been removed. It was never functional anyway. .Sh SEE ALSO -.Xr moused 1 , +.Xr ioctl 2 , .Xr syslog 3 , +.Xr mouse 4 , .Xr mse 4 , +.Xr sysmouse 4 , +.Xr moused 8 , .Xr syslogd 8 -.\" .Sh HISTORY -.\" .Sh AUTHOR +.\".Sh HISTORY +.Sh AUTHOR +The +.Nm +driver is based on the work done by quite a number of people, including +.An Eric Forsberg , +.An Sandi Donno , +.An Rick Macklem , +.An Andrew Herbert , +.An Charles Hannum , +.An Shoji Yuen +and +.An Kazutaka YOKOTA +to name the few. +.Pp +This manual page was written by +.An Kazutaka YOKOTA Aq yokota@FreeBSD.org . 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 .Fd #include -.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 . diff --git a/share/man/man4/mouse.4 b/share/man/man4/mouse.4 new file mode 100644 index 0000000..7cb00ef --- /dev/null +++ b/share/man/man4/mouse.4 @@ -0,0 +1,382 @@ +.\" +.\" Copyright (c) 1997 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 THE AUTHOR ``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 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. +.\" +.\" $Id:$ +.\" +.Dd December 3, 1997 +.Dt MOUSE 4 i386 +.Os FreeBSD +.Sh NAME +.Nm mouse +.Nd mouse and pointing device drivers +.Sh SYNOPSIS +.Fd #include +.Sh DESCRIPTION +The mouse drivers +.Xr mse 4 , +.Xr psm 4 +and +.Xr sysmouse 4 +provide user programs with movement and button state information of the mouse. +Currently there are specific device drivers for bus, InPort and PS/2 mice. +The serial mouse is not directly supported by a dedicated driver, but +it is accessible via the serial device driver or via +.Xr moused 8 +and +.Xr sysmouse 4 . +.Pp +The user program simply opens a mouse device with a +.Xr open 2 +call and reads +mouse data from the device via +.Xr 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. +.Pp +The mouse drivers may have ``non-blocking'' attribute which will make +the driver return immediately if mouse data is not available. +.Pp +Mouse device drivers often offer several levels of operation. +The current operation level can be examined and changed via +.Xr 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 +.Dv MOUSE_PROTO_SYSMOUSE +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. +.It Byte 6 +The bit 7 is always zero. The lower 7 bits encode the first half of +Z axis movement count in two's compliment; -64 through 63. +.It 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 compliment; -64 through 63. +To obtain the full Z axis movement count, add the byte 6 and 7. +.It 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 corresponding bit is cleared. Otherwise +the bit is set. +.El +.Pp +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. +.Pp +Device drivers may offer operation levels higher than one. +Refer to manual pages of individual drivers for details. +.Sh IOCTLS +The following +.Xr 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. +.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 +Except for the +.Dv iftype +field, the device driver may not always fill the structure with correct +values. +Consult manual pages of individual drivers for details of support. +.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. The driver +may put an arbitrary value, such as two, in this field, if it cannot +determine the exact number. +.Pp +The +.Dv iftype +is the type of interface: +.Dv MOUSE_IF_SERIAL , +.Dv MOUSE_IF_BUS , +.Dv MOUSE_IF_INPORT , +.Dv MOUSE_IF_PS2 , +.Dv MOUSE_IF_SYSMOUSE +or +.Dv MOUSE_IF_UNKNOWN . +.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 +may be +.Dv MOUSE_MODEL_GENERIC +or one of +.Dv MOUSE_MODEL_XXX +constants. +.Pp +The +.Dv 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. +.Pp +.It Dv MOUSE_GETMODE Ar mousemode_t *mode +The command reports 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 one of +.Dv MOUSE_PROTO_XXX +constants. +.Pp +The +.Dv 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. +.Pp +The +.Dv resolution +field holds a value specifying resolution of the pointing device. +It is a positive value or one of +.Dv MOUSE_RES_XXX +constants. +.Pp +The +.Dv accelfactor +field holds a value to control acceleration feature. +It must be zero or greater. +If it is zero, acceleration is disabled. +.Pp +The +.Dv 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. +.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 rate , +.Dv resolution , +.Dv level +and +.Dv accelfactor +may be modifiable. Setting values in the other field does not generate +error and has no effect. +.Pp +If you do not want to change the current setting of a field, put -1 +there. +You may also put zero in +.Dv resolution +and +.Dv rate , +and the default value for the fields will be selected. +.\" .Pp +.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars +.\" Get internal variables of the mouse driver. +.\" The variables which can be manipulated through these commands +.\" are specific to each driver. +.\" This command may not be supported by all drivers. +.\" .Bd -literal +.\" typedef struct mousevar { +.\" int var[16]; /* internal variables */ +.\" } mousevar_t; +.\" .Ed +.\" .Pp +.\" If the commands are supported, the first element of the array is +.\" filled with a signature value. +.\" Apart from the signature data, there is currently no standard concerning +.\" the other elements of the buffer. +.\" .Pp +.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars +.\" Get internal variables of the mouse driver. +.\" The first element of the array must be a signature value. +.\" This command may not be supported by all drivers. +.Pp +.It Dv MOUSE_READDATA Ar mousedata_t *data +The command reads the raw data from the device. +.Bd -literal +typedef struct mousedata { + int len; /* # of data in the buffer */ + int buf[16]; /* data buffer */ +} mousedata_t; +.Ed +.Pp +The calling process must fill the +.Dv len +field with the number of bytes to be read into the buffer. +This command may not be supported by all drivers. +.Pp +.It Dv MOUSE_READSTATE Ar 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. +.Pp +.It Dv MOUSE_GETSTATE Ar mousestatus_t *status +The command returns the current state of buttons and +movement counts in the following structure. +.Bd -literal +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; +.Ed +.Pp +The +.Dv button +and +.Dv 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 +.Dv MOUSE_BUTTON1DOWN +through +.Dv MOUSE_BUTTON8DOWN . +The first three buttons correspond to left, middle and right buttons. +.Pp +If the state of the button has changed since the last +.Dv MOUSE_GETSTATE +call, the corresponding bit in the +.Dv flags +field will be set. +If the mouse has moved since the last call, the +.Dv MOUSE_POSCHANGED +bit in the +.Dv flags +field will also be set. +.Pp +The other fields hold movement counts since the last +.Dv MOUSE_GETSTATE +call. The internal counters will be reset after every call to this +command. +.El +.Sh FILES +.Bl -tag -width /dev/sysmouseXX -compact +.It Pa /dev/cuaa%d +serial ports +.It Pa /dev/mse%d +bus and InPort mouse device +.It Pa /dev/psm%d +PS/2 mouse device +.It Pa /dev/sysmouse +virtual mouse device +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr mse 4 , +.Xr psm 4 , +.Xr sysmouse 4 , +.Xr moused 8 +.\".Sh HISTORY +.Sh AUTHOR +This manual page was written by +.An Kazutaka YOKOTA Aq yokota@FreeBSD.org . diff --git a/share/man/man4/psm.4 b/share/man/man4/psm.4 index d154294..4797bab 100644 --- a/share/man/man4/psm.4 +++ b/share/man/man4/psm.4 @@ -1,6 +1,32 @@ -.\" $Id: psm.4,v 1.8 1997/10/19 10:45:18 yokota Exp $ .\" -.Dd January 13, 1997 +.\" Copyright (c) 1997 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 THE AUTHOR ``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 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. +.\" +.\" $Id: psm.4,v 1.7 1997/02/22 13:25:39 peter Exp $ +.\" +.Dd December 3, 1997 .Dt PSM 4 i386 .Os FreeBSD .Sh NAME @@ -8,9 +34,6 @@ .Nd PS/2 mouse style pointing device driver .Sh SYNOPSIS -.Cd "options PSM_CHECKSYNC" -.\".Cd "options PSM_EMULATION" -.Cd "options" \&"PSM_ACCEL=N\&" .Cd "options" \&"PSM_HOOKAPM\&" .Cd "options" \&"PSM_RESETAFTERSUSPEND\&" .Cd "options" \&"KBD_RESETDELAY=N\&" @@ -22,23 +45,79 @@ PS/2 mouse style pointing device driver The .Nm driver provides support for the PS/2 mouse style pointing device. - +Currently there can be only one +.Nm +device node in the system. .Em port \&"IO_KBD\&" and .Em conflicts are required, as the PS/2 mouse port is located -at the auxiliary port of the keyboard controller, thus, the +at the auxiliary port of the keyboard controller; the .Nm driver has to share the same I/O ports with the keyboard driver. Note also that there is currently no provision of changing the .Em irq number. .Pp -A series of data packets is read from the +Basic PS/2 style pointing device has two or three buttons. +Some devices may have a roller or a wheel and/or additional buttons. +.Ss Device Resolution +The PS/2 style pointing device usually has several grades of resolution, +that is, sensitivity of movement. They are typically 25, 50, 100 and 200 +pulse per inch. Some devices may have finer resolution. +The current resolution can be changed at runtime. The .Nm -driver. A data packet from the PS/2 mouse style pointing device -is three bytes long: +driver allows the user to initially set the resolution +via the driver flag +.Pq see Sx DRIVER CONFIGURATION +or change it later via the +.Xr ioctl 2 +command +.Dv MOUSE_SETMODE +.Pq see Sx IOCTLS . +.Ss Report Rate +Frequency, or report rate, at which the device sends movement +and button state reports to the host system is also configurable. +The PS/2 style pointing device typically supports 10, 20, 40, 60, 80, 100 +and 200 reports per second. +60 or 100 appears to be the default value for many devices. +Note that when there is no movement and no button has changed its state, +the device won't send anything to the host system. +The report rate can be changed via an ioctl call. +.Ss Operation Levels +The +.Nm +driver has three levels of operation. +The current operation level can be set via an ioctl call. +.Pp +At the level zero the basic support is provided; the device driver will report +horizontal and vertical movement of the attached device +and state of up to three buttons. +The movement and status are encoded in a series of fixed-length data packets +.Pq see Sx Data Packet Format . +This is the default level of operation and the driver is initially +at this level when opened by the user program. +.Pp +The operation level one, the `extended' level, supports a roller (or wheel), +if any, and up to 11 buttons. +The movement of the roller is reported as movement along the Z axis. +8 byte data packets are sent to the user program at this level. +.Pp +At the operation level two, data from the pointing device is passed to the +user program as is. +Modern PS/2 type pointing devices often use proprietary data format. +Therefore, the user program is expected to have +intimate knowledge about the format from a particular device when operating +the driver at this level. +This level is called `native' level. +.Ss Data Packet Format +Data packets read from the +.Nm +driver are formatted differently at each operation level. +.Pp +A data packet from the PS/2 mouse style pointing device +is three bytes long at the operation level zero: .Pp .Bl -tag -width Byte_1 -compact .It Byte 1 @@ -52,12 +131,13 @@ Set if the vertical movement count is negative. .It bit 4 Set if the horizontal movement count is negative. .It bit 3 -The ALPS GlidePoint clears this bit when the user `taps' the surface of -the pad, otherwise the bit is set. -Most, if not all, other devices always sets this bit. +Always one. +.\" The ALPS GlidePoint clears this bit when the user `taps' the surface of +.\" the pad, otherwise the bit is set. +.\" Most, if not all, other devices always set this bit. .It bit 2 Middle button status; set if pressed. For devices without the middle -button, this bit seems to be always zero. +button, this bit is always zero. .It bit 1 Right button status; set if pressed. .It bit 0 @@ -73,6 +153,24 @@ Vertical movement count in two's compliment; Note that the sign bit is in the first byte. .El .Pp +At the level one, a data packet is encoded +in the standard format +.Dv MOUSE_PROTO_SYSMOUSE +as defined in +.Xr mouse 4 . +.Pp +At the level two, native level, there is no standard on the size and format +of the data packet. +.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. +.Ss Device Number The minor device number of the .Nm is made up of: @@ -88,48 +186,14 @@ therefore the minor device number usually used for \fIXFree86\fP is 1. See .Sx FILES for device node names. -.Sh KERNEL CONFIGURATION -There are following options to control the +.Sh DRIVER CONFIGURATION +.Ss Kernel Configuration Options +There are following kernel configuration options to control the .Nm driver. +They may be set in the kernel configuration file +.Pq see Xr config 8 . .Bl -tag -width MOUSE -.It Em PSM_CHECKSYNC -If this option is defined, the driver tries to detect the first byte of -the three-byte data packet, by checking the bit pattern of that byte. -This may be useful if you often experience wierd mouse movement -cased by unsynchronization between the application program and the mouse. -However, the -.Em PSM_CHECKSYNC -code may not always work; some systems, mostly notebooks, set the bit -pattern differently from the others. -Note also that the `tapping' feature of the ALPS GlidePoint will be -lost when this option is used. -.\".It Em PSM_EMULATION -.\"The -.\".Nm -.\"driver can emulate the Microsoft Serial Mouse's three-byte -.\"data packet and the Mouse Systems Corp's five-byte data packet -.\"when data is read by user programs, if so specified by the -.\".Fn ioctl -.\"command -.\".Dv MOUSE_SETMODE . -.\"To enable the emulation feature, define this option. -.It Em PSM_ACCEL=N -The -.Nm -driver can somewhat `accelerate' the movement of the pointing device. -That is, the faster you move the device, the further the pointer -travels on the screen. This option controls the amount of acceleration. -The smaller -.Fa N -is, more sensitive the movement becomes. -The minimum value allowed, thus the value for the most sensitive setting, -is 1. Setting this option to zero will completely disables the -acceleration effect. The default value is 0 (acceleration disabled). -The acceleration effect can also be controlled via the -.Fn ioctl -command -.Dv MOUSE_SETMODE . .It Em PSM_HOOKAPM The built-in PS/2 pointing device of some laptop computers is somehow not operable immediately after the system `resumes' from @@ -175,70 +239,100 @@ The default debug level is zero. See .Sx DIAGNOSTICS for debug logging. .El -.Sh IOCTL -There are only few ioctls for the +.Ss Driver Flags +The .Nm -driver. These are defined in -.Ao Pa machine/mouse.h Ac . +driver accepts the following driver flags. Set them in the +kernel configuration file or in the User Configuration Menu at +the boot time +.Pq see Xr boot 8 . +.Pp .Bl -tag -width MOUSE -.It Dv MOUSEIOCREAD -The -.Dv MOUSEIOCREAD -command did NOT work before and does NOT work now. It is obsolete. -Use the -.Dv MOUSE_GETSTATE -command instead. -.It Dv MOUSE_GETSTATE -The command returns the current mouse state in the following structure -and remove the state information from the internal queue. -.Bd -literal -typedef struct mousestatus { - int button; /* button status */ - int obutton; /* previous button status */ - int dx; /* x movement */ - int dy; /* y movement */ -} mousestatus_t; -.Ed +.It bit 0..3 RESOLUTION +This flag specifies the resolution of the pointing device. +It must be zero through four. The greater the value +is, the finer resolution the device will select. +Actual resolution selected by this field varies according to the model +of the device. Typical resolutions are: .Pp +.Bl -tag -width 0_(medium_high)__ -compact +.It Em 1 (low) +25 pulse per inch (ppi) +.It Em 2 (medium low) +50 ppi +.It Em 3 (medium high) +100 ppi +.It Em 4 (high) +200 ppi +.El +.Pp +Leaving this flag zero will selects the default resolution for the +device (whatever it is). +.It bit 4..7 ACCELERATION +This flag controls the amount of acceleration effect. +The smaller the value of this flag is, more sensitive the movement becomes. +The minimum value allowed, thus the value for the most sensitive setting, +is one. Setting this flag to zero will completely disables the +acceleration effect. +.It bit 8 NOCHECKSYNC The -.Dv button -and the -.Dv obutton -fields hold the current and the previous state of the mouse buttons. -When a button is pressed, the corresponding bit is set. -These bits are defined as -.Dv MOUSE_BUTTON1DOWN -through -.Dv MOUSE_BUTTON8DOWN . -The first three buttons are left, middle and right buttons. -.Pp -Note that this command and -.Fn read -operation on the .Nm -driver uses the same internal queue. Therefore, interleaving the -.Dv MOUSE_GETSTATE -command and -.Fn read -operation is not recommended. -.It Dv MOUSE_GETHWINFO -Returns the hardware information in the following structure. +driver tries to detect the first byte of the data packet by checking +the bit pattern of that byte. Although this method should work with most +PS/2 pointing devices, it may interfere with some devices which are not +so compatible with known devices. +If you think your pointing device is not functioning as expected, +see if disabling synchronization check will help by setting this flag. +.El +.Sh IOCTLS +There are a few +.Xr ioctl 2 +commands for mouse drivers. +These commands and related structures and constants are defined in +.Ao Pa machine/mouse.h Ac . +General description of the commands is given in +.Xr mouse 4 . +This section explains 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 +.Nm +driver. +.Pp +.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw +Returns the hardware information of the attached device in the following +structure. .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 iftype -is -.Dv MOUSE_IF_PS2 -for the +.Dv buttons +field holds the number of buttons on the device. +The .Nm -driver. The +driver currently can detect the 3 button mouse from Logitech and report +accordingly. +The 3 button mouse from the other manufacturer may or may not be +reported correctly. However, it will not affect the operation of +the driver. +.Pp +The +.Dv iftype +is always +.Dv MOUSE_IF_PS2 . +.Pp +The .Dv type tells the device type: .Dv MOUSE_MOUSE , @@ -248,73 +342,240 @@ tells the device type: or .Dv MOUSE_UNKNOWN . The user should not heavily rely on this field, as the -.Nm driver may not always, in fact it is very rarely able to, identify the device type. +.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. +Again the +.Nm +driver may or may not set an appropriate value in this field. +.Pp The .Dv hwid -is the ID value returned by the pointing device. +is the ID value returned by the device. Known IDs include: +.Pp .Bl -tag -width 0__ -compact .It Em 0 Mouse (Microsoft, Logitech and many other manufacturers) .It Em 2 Microsoft Ballpoint mouse +.It Em 3 +Microsoft IntelliMouse .El -.It Dv MOUSE_GETMODE, MOUSE_SETMODE -The commands get and set the operation mode of the -.Nm +.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), -1 if unknown */ - int resolution; /* 1:low, 2:medium low, 3:medium high - * 4:high, 0: default, -1 if unknown - */ - int accelfactor; /* acceleration factor (must be 1 or greater) */ + 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 -selects the format with which the device status is returned by -.Fn read . -The default is -.Dv MOUSE_PROTO_PS2 , -that is, the data byte from the pointing device is read by user -programs as is. -No other value is allowed at the moment. -.\"Other possible values are: -.\".Dv MOUSE_PROTO_MSS -.\"and -.\".Dv MOUSE_PROTO_MSC , -.\"which specifies Microsoft Serial Mouse three-byte format and -.\"Mouse Systems Corp.'s five-byte format respectively. -.\"Note that the protocol cannot be set to anything other than -.\".Dv MOUSE_PROTO_PS2 -.\"unless the -.\".Em PSM_EMULATION -.\"option is specified in the kernel configuration file. +is +.Dv MOUSE_PROTO_PS2 +at the operation level zero and two. +.Dv MOUSE_PROTO_SYSMOUSE +at the operation level one. .Pp The .Dv rate is the status report rate (reports/sec) at which the device will send movement report to the host computer. +Typical supported values are 10, 20, 40, 60, 80, 100 and 200. +Some mice may accept other arbitrary values too. .Pp The .Dv resolution -of the pointing device must be zero through four. The higher the value -is, the finer resolution the mouse will select. Zero selects the -default resolution. +of the pointing device must be one of +.Dv MOUSE_RES_XXX +constants or a positive value. The greater the value +is, the finer resolution the mouse will select. +Actual resolution selected by the +.Dv MOUSE_RES_XXX +constant varies according to the model of mouse. Typical resolutions are: +.Pp +.Bl -tag -width MOUSE_RES_MEDIUMHIGH__ -compact +.It Dv MOUSE_RES_LOW +25 ppi +.It Dv MOUSE_RES_MEDIUMLOW +50 ppi +.It Dv MOUSE_RES_MEDIUMHIGH +100 ppi +.It Dv MOUSE_RES_HIGH +200 ppi +.El +.Pp +The +.Dv accelfactor +field holds a value to control acceleration feature +.Pq see Sx Acceleration . +It must be zero or greater. If it is zero, acceleration is disabled. .Pp The +.Dv packetsize +field specifies the length of the data packet. It depends on the +operation level and the model of the pointing device. +.Pp +.Bl -tag -width level_0__ -compact +.It Em level 0 +3 bytes +.It Em level 1 +8 bytes +.It Em level 2 +Depends on the model of the device +.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 detection method 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 rate , +.Dv resolution , +.Dv level +and .Dv accelfactor -holds a value to control acceleration feature (see description on -.Em PSM_ACCEL -above). It must be zero or greater. -If it is zero, acceleration is disabled. +may be modifiable. Setting values in the other field does not generate +error and has no effect. +.Pp +If you do not want to change the current setting of a field, put -1 +there. +You may also put zero in +.Dv resolution +and +.Dv rate , +and the default value for the fields will be selected. +.\" .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 +.\" The command reads the raw data from the device. +.\" .Bd -literal +.\" typedef struct mousedata { +.\" int len; /* # of data in the buffer */ +.\" int buf[16]; /* data buffer */ +.\" } mousedata_t; +.\" .Ed +.\" .Pp +.\" Upon returning to the user program, the driver will place the number +.\" of valid data bytes in the buffer in the +.\" .Dv len +.\" field. +.\" .Pp +.It Dv MOUSE_READSTATE Ar mousedata_t *state +.\" The command reads the hardware settings from the device. +.\" Upon returning to the user program, the driver will place the number +.\" of valid data bytes in the buffer in the +.\" .Dv len +.\" field. It is usually 3 bytes. +.\" The buffer is formatted as follows: +.\" .Pp +.\" .Bl -tag -width Byte_1 -compact +.\" .It Byte 1 +.\" .Bl -tag -width bit_6 -compact +.\" .It bit 7 +.\" Reserved. +.\" .It bit 6 +.\" 0 - stream mode, 1 - remote mode. +.\" In the stream mode, the pointing device sends the device status +.\" whenever its state changes. In the remote mode, the host computer +.\" must request the status to be sent. +.\" The +.\" .Nm +.\" driver puts the device in the stream mode. +.\" .It bit 5 +.\" Set if the pointing device is currently enabled. Otherwise zero. +.\" .It bit 4 +.\" 0 - 1:1 scaling, 1 - 2:1 scaling. +.\" 1:1 scaling is the default. +.\" .It bit 3 +.\" Reserved. +.\" .It bit 2 +.\" Left button status; set if pressed. +.\" .It bit 1 +.\" Middle button status; set if pressed. +.\" .It bit 0 +.\" Right button status; set if pressed. +.\" .El +.\" .It Byte 2 +.\" .Bl -tag -width bit_6_0 -compact +.\" .It bit 7 +.\" Reserved. +.\" .It bit 6..0 +.\" Resolution code: zero through three. Actual resolution for +.\" the resolution code varies from one device to another. +.\" .El +.\" .It Byte 3 +.\" The status report rate (reports/sec) at which the device will send +.\" movement report to the host computer. +.\" .El +These commands are not currently 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 as described in +.Xr mouse 4 . +.El +.Sh FILES +.Bl -tag -width /dev/npsm0 -compact +.It Pa /dev/psm0 +`non-blocking' device node in the system without +.Em devfs , +`blocking' under +.Em devfs . +.It Pa /dev/npsm0 +`non-blocking' device node under +.Em devfs . .El +.Sh EXAMPLE +.Dl "options" \&"PSM_HOOKAPM\&" +.Dl "device psm0 at isa? port" \&"IO_KBD\&" conflicts tty irq 12 vector psmintr +.Pp +Add the +.Nm +driver to the kernel with the optional code to stimulate the pointing device +after the `resume' event. +.Pp +.Dl "device psm0 at isa? port" \&"IO_KBD\&" conflicts tty flags 0x024 irq 12 +.Dl vector psmintr +.Pp +Set the device resolution high (4) and the acceleration factor to 2. .Sh DIAGNOSTICS .Pp At debug level 0, little information is logged except for the following @@ -332,23 +593,20 @@ for known IDs. .Pp At debug level 1 more information will be logged while the driver probes the auxiliary port (mouse port). -Messages are logged with the LOG_KERN facility at the LOG_DEBUG level. -(See -.Xr syslogd 8 . ) +Messages are logged with the LOG_KERN facility at the LOG_DEBUG level +.Pq see Xr syslogd 8 . .Bd -literal -offset indent psm0: current command byte:xxxx -kbdio: new command byte:yyyy (set_controller...) kbdio: TEST_AUX_PORT status:0000 kbdio: RESET_AUX return code:00fa kbdio: RESET_AUX status:00aa kbdio: RESET_AUX ID:0000 -psm0: status after reset 00 02 64 -psm: device ID: X -psm: status xx yy zz (get_mouse_buttons) -psm0: status 00 02 64 -kbdio: new command byte:zzzz (set_controller...) +[...] +psm: status 00 02 64 psm0 at 0x60-0x64 irq 12 on motherboard -psm0: device ID X, N buttons +psm0: model AAAA, device ID X, N buttons +psm0: config:00000www, flags:0000uuuu, packet size:M +psm0: syncmask:xx, syncbits:yy .Ed .Pp The first line shows the command byte value of the keyboard @@ -356,17 +614,20 @@ controller just before the auxiliary port is probed. It usually is 4D, 45, 47 or 65, depending on how the motherboard BIOS initialized the keyboard controller upon power-up. .Pp -The third line shows the result of the keyboard controller's +The second line shows the result of the keyboard controller's test on the auxiliary port interface, with zero indicating no error; note that some controllers report no error even if the port does not exist in the system, however. .Pp -The forth to sixth lines show the reset status of the pointing device. +The third through fifth lines show the reset status of the pointing device. The functioning device should return the sequence of FA AA . The ID code is described above. .Pp -The tenth line shows the current hardware settings; it consists -of three bytes: +The seventh line shows the current hardware settings. +.\" See +.\" .Dv MOUSE_READSTATE +.\" for definitions. +These bytes are formatted as follows: .Pp .Bl -tag -width Byte_1 -compact .It Byte 1 @@ -378,10 +639,14 @@ Reserved. In the stream mode, the pointing device sends the device status whenever its state changes. In the remote mode, the host computer must request the status to be sent. +The +.Nm +driver puts the device in the stream mode. .It bit 5 Set if the pointing device is currently enabled. Otherwise zero. .It bit 4 0 - 1:1 scaling, 1 - 2:1 scaling. +1:1 scaling is the default. .It bit 3 Reserved. .It bit 2 @@ -395,21 +660,9 @@ Right button status; set if pressed. .Bl -tag -width bit_6_0 -compact .It bit 7 Reserved. -.It bit 6-0 -Resolution code: zero through three. The higher the number is, -the finer resolution the device has. Actual resolution for +.It bit 6..0 +Resolution code: zero through three. Actual resolution for the resolution code varies from one device to another. -The typical values are: -.Bl -tag -width 100 -compact -.It 0 -25 pulse per inch (ppi) -.It 1 -50 ppi -.It 2 -100 ppi -.It 3 -200 ppi -.El .El .It Byte 3 The status report rate (reports/sec) at which the device will send @@ -418,30 +671,22 @@ movement report to the host computer. .Pp Note that the pointing device will not be enabled until the .Nm -driver is opened by the user programs. +driver is opened by the user program. .Pp -The last line shows the device ID code and the number of detected -buttons. Currently the -.Nm -driver can detect the 3 button mouse from Logitech and report -accordingly. -The 3 button mouse from the other manufacturer may or may not be -reported correctly. However, it will not affect the operation of -the driver. +The rest of the lines show the device ID code, the number of detected +buttons and internal variables. .Pp At debug level 2, much more detailed information is logged. -.Sh FILES -.Bl -tag -width /dev/npsm0 -compact -.It Pa /dev/psm0 -`non-blocking' device node in the system without -.Em devfs , -`blocking' under -.Em devfs . -.It Pa /dev/npsm0 -`non-blocking' device node under -.Em devfs . -.El .Sh CAVEATS +Many pad devices behave as if the first (left) button were pressed if +the user `taps' the surface of the pad. +In contrast, some ALPS GlidePoint pad models treat the tapping action +as fourth button events. +.Pp +Some PS/2 mouse models from MouseSystems require to be put in the +high resolution mode to work properly. Use the driver flag to +set resolution. +.Pp There is not a guaranteed way to re-synchronize with the first byte of the packet once we are out of synchronization with the data stream. However, if you are using the \fIXFree86\fP server and experiencing @@ -449,22 +694,33 @@ the problem, you may be able to make the X server synchronize with the mouse by switching away to a virtual terminal and getting back to the X server, unless the X server is accessing the mouse via .Xr moused 1 . -If you have specified the -.Em PSM_CHECKSYNC -option, clicking any button without moving the mouse may also work. +Clicking any button without moving the mouse may also work. .Sh BUGS -The -.Fn ioctl -command +The ioctl command .Dv MOUSEIOCREAD -(see -.Sx IOCTL -above) was never functional and will not be. The command name -still remains for compatibility reasons but may be removed in the future. +has been removed. It was never functional anyway. .Sh SEE ALSO -.Xr moused 1 , +.Xr ioctl 2 , .Xr syslog 3 , +.Xr mouse 4 , .Xr mse 4 , +.Xr sysmouse 4 , +.Xr moused 8 , .Xr syslogd 8 -.\" .Sh HISTORY -.\" .Sh AUTHOR +.\".Sh HISTORY +.Sh AUTHOR +The +.Nm +driver is based on the work done by quite a number of people, including +.An Eric Forsberg , +.An Sandi Donno , +.An Rick Macklem , +.An Andrew Herbert , +.An Charles Hannum , +.An Shoji Yuen +and +.An Kazutaka YOKOTA +to name the few. +.Pp +This manual page was written by +.An Kazutaka YOKOTA Aq yokota@FreeBSD.org . diff --git a/share/man/man4/sysmouse.4 b/share/man/man4/sysmouse.4 index 41758ef..6bcc37b 100644 --- a/share/man/man4/sysmouse.4 +++ b/share/man/man4/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 .Fd #include -.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 . -- cgit v1.1