Document recent mouse code changes.

7 files changed, 2733 insertions, 497 deletions

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 <yokota@zodiac.mech.utsunomiya-u.ac.jp>
+.\" 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 <machine/mouse.h>
+.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 <yokota@zodiac.mech.utsunomiya-u.ac.jp>
+.\" 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 <ID>.
 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 <machine/mouse.h>
 .Fd #include <machine/console.h>
-.Ft int
-.Fn ioctl cfd CONS_MOUSECTL struct\ *mouse_info
 .Sh DESCRIPTION
+The console driver, in conjunction with the mouse daemon
+.Xr moused 8 ,
+supplies mouse data to the user process in the standardized way via the
+.Nm
+driver.
+This arrangement makes it possible for the console and the user process
+.Pq such as the Tn X\ Window System
+to share the mouse.
+.Pp
+The user process which wants to utilize mouse operation simply opens 
+.Pa /dev/sysmouse
+with a
+.Xr open 2
+call and reads
+mouse data from the device via
+.Xr read 2 .
+Make sure that
+.Xr moused 8
+is running, otherwise the user process won't see any data coming from
+the mouse.
+.Pp
+.Ss Operation Levels
 The
-.Dv CONS_MOUSECTL
-.Fn ioctl
-call provides syscons with mouse information, which includes mouse movement
-and button presses.  The
+.Nm
+driver has two levels of operation. 
+The current operation level can be referred to and changed via ioctl calls.
+.Pp
+The level zero, the basic level, is the lowest level at which the driver 
+offers the basic service to user programs. 
+The
+.Nm
+driver
+provides horizontal and vertical movement of the mouse
+and state of up to three buttons in the 
+.Tn MouseSystems 
+format as follows.
+.Pp
+.Bl -tag -width Byte_1 -compact
+.It Byte 1 
+.Bl -tag -width bit_7 -compact
+.It bit 7
+Always one.
+.It bit 6..3
+Always zero.
+.It bit 2
+Left button status; cleared if pressed, otherwise set.
+.It bit 1
+Middle button status; cleared if pressed, otherwise set. Always one,
+if the device does not have the middle button.
+.It bit 0
+Right button status; cleared if pressed, otherwise set.
+.El
+.It Byte 2
+The first half of horizontal movement count in two's compliment; 
+-128 through 127.
+.It Byte 3
+The first half of vertical movement count in two's compliment; 
+-128 through 127.
+.It Byte 4
+The second half of the horizontal movement count in two's compliment; 
+-128 through 127. To obtain the full horizontal movement count, add
+the byte 2 and 4.
+.It Byte 5
+The second half of the vertical movement count in two's compliment; 
+-128 through 127. To obtain the full vertical movement count, add
+the byte 3 and 5.
+.El
+.Pp
+At the level one, the extended level, mouse data is encoded
+in the standard format
+.Dv MOUSE_PROTO_SYSMOUSE
+as defined in 
+.Xr mouse 4 .
+.\" .Ss Acceleration
+.\" The
+.\" .Nm
+.\" driver can somewhat `accelerate' the movement of the pointing device.
+.\" The faster you move the device, the further the pointer 
+.\" travels on the screen. 
+.\" The driver has an internal variable which governs the effect of 
+.\" the acceleration. Its value can be modified via the driver flag 
+.\" or via an ioctl call.
+.Sh IOCTLS
+This section describes two classes of 
+.Xr ioctl 2
+commands: 
+commands for the
+.Nm
+driver itself, and commands for the console and the console control drivers.
+.Ss Sysmouse Ioctls
+There are a few commands for mouse drivers.
+General description of the commands is given in
+.Xr mouse 4 .
+Followings are the features specific to the
+.Nm
+driver.
+.Pp
+.Bl -tag -width MOUSE -compact
+.It Dv MOUSE_GETLEVEL Ar int *level
+.It Dv MOUSE_SETLEVEL Ar int *level
+These commands manipulate the operation level of the mouse driver.
+.Pp
+.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
+Returns the hardware information of the attached device in the following 
+structure.  Only the
+.Dv iftype
+field is guaranteed to be filled with the correct value in the current
+version of the
+.Nm
+driver.
+.Bd -literal
+typedef struct mousehw {
+    int buttons;    /* number of buttons */
+    int iftype;     /* I/F type */
+    int type;       /* mouse/track ball/pad... */
+    int model;      /* I/F dependent model ID */
+    int hwid;       /* I/F dependent hardware ID */
+} mousehw_t;
+.Ed
+.Pp
+The
+.Dv buttons
+field holds the number of buttons detected by the driver.
+.Pp
+The
+.Dv iftype
+is always
+.Dv MOUSE_IF_SYSMOUSE.
+.Pp
+The
+.Dv type
+tells the device type:
+.Dv MOUSE_MOUSE ,
+.Dv MOUSE_TRACKBALL ,
+.Dv MOUSE_STICK ,
+.Dv MOUSE_PAD ,
+or
+.Dv MOUSE_UNKNOWN .
+.Pp
+The
+.Dv model
+is always 
+.Dv MOUSE_MODEL_GENERIC
+at the operation level 0.
+It may be 
+.Dv MOUSE_MODEL_GENERIC
+or one of 
+.Dv MOUSE_MODEL_XXX
+constants at higher operation levels.
+.Pp
+The
+.Dv hwid
+is always zero.
+.Pp
+.It Dv MOUSE_GETMODE Ar mousemode_t *mode
+The command gets the current operation parameters of the mouse
+driver.
+.Bd -literal
+typedef struct mousemode {
+    int protocol;    /* MOUSE_PROTO_XXX */
+    int rate;        /* report rate (per sec) */
+    int resolution;  /* MOUSE_RES_XXX, -1 if unknown */
+    int accelfactor; /* acceleration factor */
+    int level;       /* driver operation level */
+    int packetsize;  /* the length of the data packet */
+    unsigned char syncmask[2]; /* sync. bits */
+} mousemode_t;
+.Ed
+.Pp
+The
+.Dv protocol
+field tells the format in which the device status is returned 
+when the mouse data is read by the user program.
+It is
+.Dv MOUSE_PROTO_MSC
+at the operation level zero.
+.Dv MOUSE_PROTO_SYSMOUSE
+at the operation level one.
+.Pp
+The
+.Dv rate
+is always set to -1.
+.Pp
+The
+.Dv resolution
+is always set to -1.
+.Pp
+The
+.Dv accelfactor
+is always 0.
+.Pp
+The
+.Dv packetsize
+field specifies the length of the data packet. It depends on the
+operation level.
+.Pp
+.Bl -tag -width level_0__ -compact
+.It Em level 0
+5 bytes
+.It Em level 1
+8 bytes
+.El
+.Pp
+The array
+.Dv syncmask
+holds a bit mask and pattern to detect the first byte of the
+data packet.
+.Dv syncmask[0]
+is the bit mask to be ANDed with a byte. If the result is equal to
+.Dv syncmask[1] ,
+the byte is likely to be the first byte of the data packet.
+Note that this method of detecting the first byte is not 100% reliable,
+thus, should be taken only as an advisory measure.
+.Pp
+.It Dv MOUSE_SETMODE Ar mousemode_t *mode
+The command changes the current operation parameters of the mouse driver
+as specified in
+.Ar mode .
+Only
+.Dv level 
+may be modifiable. Setting values in the other field does not generate
+error and has no effect.
+.\" .Pp
+.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
+.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
+.\" These commands are not supported by the
+.\" .Nm
+.\" driver.
+.Pp
+.It Dv MOUSE_READDATA Ar mousedata_t *data
+.It Dv MOUSE_READSTATE Ar mousedata_t *state
+These commands are not supported by the
+.Nm
+driver.
+.Pp
+.It Dv MOUSE_GETSTATE Ar mousestatus_t *status
+The command returns the current state of buttons and 
+movement counts in the structure as defined in
+.Xr mouse 4 .
+.El
+.Ss Console and Consolectl Ioctls
+The user process issues console 
 .Fn ioctl
-also provides a method for a process to receive a
+calls to the current virtual console in order to control
+the mouse pointer.
+The console
+.Fn ioctl 
+also provides a method for the user process to receive a
 .Xr signal 3
 when a button is pressed.
 .Pp
+The mouse daemon
 .Xr moused 8
-uses this
+uses 
 .Fn ioctl
-to inform the console of mouse actions.  Applications
-.Pq such as Tn X\ Windows
-can use
-.Pa /dev/sysmouse ,
-allowing syscons and the application to share the mouse.
+calls to the console control device
+.Pa /dev/consolectl
+to inform the console of mouse actions including mouse movement
+and button status.
 .Pp
-.Bd -literal -offset indent
+Both classes
+.Fn ioctl
+commands are defined as
+.Dv CONS_MOUSECTL
+which takes the following argument.
+.Bd -literal
 struct mouse_info {
-        int     operation;
-        union {
-                struct mouse_data data;
-                struct mouse_mode mode;
-        }u;
+    int operation;
+    union {
+        struct mouse_data data;
+        struct mouse_mode mode;
+        struct mouse_event event;
+    } u;
 };
 .Ed
-.Bl -tag -width operation
+.Pp
+.Bl -tag -width operation -compact
 .It Dv operation
 This can be one of
-.Bl -tag -width MOUSE_MOVEABS
+.Pp
+.Bl -tag -width MOUSE_MOVEABS -compact
 .It Dv MOUSE_SHOW
 Enables and displays mouse cursor.
 .It Dv MOUSE_HIDE
@@ -78,11 +327,12 @@ Disables and hides mouse cursor.
 Moves mouse cursor to position supplied in
 .Dv u.data .
 .It Dv MOUSE_MOVEREL
-Add position supplied in
+Adds position supplied in
 .Dv u.data
 to current position.
 .It Dv MOUSE_GETINFO
-Returns current mouse position and button status in
+Returns current mouse position in the current virtual console 
+and button status in
 .Dv u.data .
 .It Dv MOUSE_MODE
 This sets the
@@ -90,34 +340,99 @@ This sets the
 to be delivered to the current process when a button is pressed.
 The signal to be delivered is set in
 .Dv u.mode .
+.El
+.Pp
+The above operations are for virtual consoles. The operations defined 
+below are for the console control device and used by 
+.Xr moused 8
+to pass mouse data to the console driver.
+.Pp
+.Bl -tag -width MOUSE_MOVEABS -compact
 .It Dv MOUSE_ACTION
-This takes the information in
+.It Dv MOUSE_MOTIONEVENT
+These operations take the information in
 .Dv u.data
-and acts upon it.  It includes processing button presses if the current vty
-is a text interface, and sending
-.Tn Mouse System
-protocol data to
-.Pa /dev/sysmouse
-if it is open.
+and act upon it.  Mouse data will be sent to the
+.Nm
+driver if it is open.
+.Dv MOUSE_ACTION
+also processes button press actions and sends signal to the process if
+requested or performs cut and paste operations
+if the current console is a text interface. 
+.It Dv MOUSE_BUTTONEVENT
+.Dv u.data
+specifies a button and its click count. The console driver will
+use this information for signal delivery if requested or 
+for cut and paste operations if the console is in text mode.
 .El
+.Pp
+.Dv MOUSE_MOTIONEVENT
+and 
+.Dv MOUSE_BUTTONEVENT
+are newer interface and are designed to be used together.
+They are intended to replace functions performed by
+.Dv MOUSE_ACTION
+alone.
+.Pp
 .It Dv u
 This union is one of
-.Bl -tag -width data
+.Pp
+.Bl -tag -width data -compact
 .It Dv data
-.Bd -literal -offset indent
+.Bd -literal
 struct mouse_data {
-        int     x;
-        int     y;
-        int     buttons;
+    int x;
+    int y;
+    int z;
+    int buttons;
 };
 .Ed
+.Pp
+.Dv x ,
+.Dv y 
+and
+.Dv z
+represent movement of the mouse along respective directions.
+.Dv buttons
+tells the state of buttons. It encodes up to 31 buttons in the bit 0 though
+the bit 30.  If a button is held down, the corresponding bit is set. 
+.Pp
 .It Dv mode
-.Bd -literal -offset indent
+.Bd -literal
 struct mouse_mode {
-        int     mode;
-        int     signal;
+    int mode;
+    int signal;
 };
 .Ed
+.Pp
+The
+.Dv signal
+field specifies the signal to be delivered to the process. It must be 
+one of the values defined in
+.Ao Pa signal.h Ac .
+The
+.Dv mode
+field is currently unused.
+.Pp
+.It Dv event
+.Bd -literal
+struct mouse_event {
+    int id;
+    int value;
+};
+.Ed
+.Pp
+The
+.Dv id
+field specifies a button number as in 
+.Dv u.data.buttons .
+Only one bit/button is set.
+The
+.Dv value
+field
+holds the click count: the number of times the user has clicked the button
+successively.
+.Pp
 .El
 .El
 .Sh FILES
@@ -125,11 +440,15 @@ struct mouse_mode {
 .It Pa /dev/consolectl
 device to control the console
 .It Pa /dev/sysmouse
-mouse action output
+virtualized mouse driver
+.It Pa /dev/ttyv%d
+virtual consoles
 .El
 .Sh SEE ALSO
 .Xr vidcontrol 1 ,
+.Xr ioctl 2 ,
 .Xr signal 3 ,
+.Xr mouse 4 ,
 .Xr moused 8
 .Sh HISTORY
 The
@@ -138,5 +457,7 @@ manual page example first appeared in
 .Fx 2.2 .
 .Sh AUTHOR
 This
-manual page was written by John-Mark Gurney
-.Aq gurney_j@efn.org .
+manual page was written by
+.An John-Mark Gurney Aq gurney_j@efn.org 
+and 
+.An Kazutaka YOKOTA Aq yokota@FreeBSD.org .
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 <yokota@zodiac.mech.utsunomiya-u.ac.jp>
+.\" 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 <machine/mouse.h>
+.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 <yokota@zodiac.mech.utsunomiya-u.ac.jp>
+.\" 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 <ID>.
 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 <machine/mouse.h>
 .Fd #include <machine/console.h>
-.Ft int
-.Fn ioctl cfd CONS_MOUSECTL struct\ *mouse_info
 .Sh DESCRIPTION
+The console driver, in conjunction with the mouse daemon
+.Xr moused 8 ,
+supplies mouse data to the user process in the standardized way via the
+.Nm
+driver.
+This arrangement makes it possible for the console and the user process
+.Pq such as the Tn X\ Window System
+to share the mouse.
+.Pp
+The user process which wants to utilize mouse operation simply opens 
+.Pa /dev/sysmouse
+with a
+.Xr open 2
+call and reads
+mouse data from the device via
+.Xr read 2 .
+Make sure that
+.Xr moused 8
+is running, otherwise the user process won't see any data coming from
+the mouse.
+.Pp
+.Ss Operation Levels
 The
-.Dv CONS_MOUSECTL
-.Fn ioctl
-call provides syscons with mouse information, which includes mouse movement
-and button presses.  The
+.Nm
+driver has two levels of operation. 
+The current operation level can be referred to and changed via ioctl calls.
+.Pp
+The level zero, the basic level, is the lowest level at which the driver 
+offers the basic service to user programs. 
+The
+.Nm
+driver
+provides horizontal and vertical movement of the mouse
+and state of up to three buttons in the 
+.Tn MouseSystems 
+format as follows.
+.Pp
+.Bl -tag -width Byte_1 -compact
+.It Byte 1 
+.Bl -tag -width bit_7 -compact
+.It bit 7
+Always one.
+.It bit 6..3
+Always zero.
+.It bit 2
+Left button status; cleared if pressed, otherwise set.
+.It bit 1
+Middle button status; cleared if pressed, otherwise set. Always one,
+if the device does not have the middle button.
+.It bit 0
+Right button status; cleared if pressed, otherwise set.
+.El
+.It Byte 2
+The first half of horizontal movement count in two's compliment; 
+-128 through 127.
+.It Byte 3
+The first half of vertical movement count in two's compliment; 
+-128 through 127.
+.It Byte 4
+The second half of the horizontal movement count in two's compliment; 
+-128 through 127. To obtain the full horizontal movement count, add
+the byte 2 and 4.
+.It Byte 5
+The second half of the vertical movement count in two's compliment; 
+-128 through 127. To obtain the full vertical movement count, add
+the byte 3 and 5.
+.El
+.Pp
+At the level one, the extended level, mouse data is encoded
+in the standard format
+.Dv MOUSE_PROTO_SYSMOUSE
+as defined in 
+.Xr mouse 4 .
+.\" .Ss Acceleration
+.\" The
+.\" .Nm
+.\" driver can somewhat `accelerate' the movement of the pointing device.
+.\" The faster you move the device, the further the pointer 
+.\" travels on the screen. 
+.\" The driver has an internal variable which governs the effect of 
+.\" the acceleration. Its value can be modified via the driver flag 
+.\" or via an ioctl call.
+.Sh IOCTLS
+This section describes two classes of 
+.Xr ioctl 2
+commands: 
+commands for the
+.Nm
+driver itself, and commands for the console and the console control drivers.
+.Ss Sysmouse Ioctls
+There are a few commands for mouse drivers.
+General description of the commands is given in
+.Xr mouse 4 .
+Followings are the features specific to the
+.Nm
+driver.
+.Pp
+.Bl -tag -width MOUSE -compact
+.It Dv MOUSE_GETLEVEL Ar int *level
+.It Dv MOUSE_SETLEVEL Ar int *level
+These commands manipulate the operation level of the mouse driver.
+.Pp
+.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
+Returns the hardware information of the attached device in the following 
+structure.  Only the
+.Dv iftype
+field is guaranteed to be filled with the correct value in the current
+version of the
+.Nm
+driver.
+.Bd -literal
+typedef struct mousehw {
+    int buttons;    /* number of buttons */
+    int iftype;     /* I/F type */
+    int type;       /* mouse/track ball/pad... */
+    int model;      /* I/F dependent model ID */
+    int hwid;       /* I/F dependent hardware ID */
+} mousehw_t;
+.Ed
+.Pp
+The
+.Dv buttons
+field holds the number of buttons detected by the driver.
+.Pp
+The
+.Dv iftype
+is always
+.Dv MOUSE_IF_SYSMOUSE.
+.Pp
+The
+.Dv type
+tells the device type:
+.Dv MOUSE_MOUSE ,
+.Dv MOUSE_TRACKBALL ,
+.Dv MOUSE_STICK ,
+.Dv MOUSE_PAD ,
+or
+.Dv MOUSE_UNKNOWN .
+.Pp
+The
+.Dv model
+is always 
+.Dv MOUSE_MODEL_GENERIC
+at the operation level 0.
+It may be 
+.Dv MOUSE_MODEL_GENERIC
+or one of 
+.Dv MOUSE_MODEL_XXX
+constants at higher operation levels.
+.Pp
+The
+.Dv hwid
+is always zero.
+.Pp
+.It Dv MOUSE_GETMODE Ar mousemode_t *mode
+The command gets the current operation parameters of the mouse
+driver.
+.Bd -literal
+typedef struct mousemode {
+    int protocol;    /* MOUSE_PROTO_XXX */
+    int rate;        /* report rate (per sec) */
+    int resolution;  /* MOUSE_RES_XXX, -1 if unknown */
+    int accelfactor; /* acceleration factor */
+    int level;       /* driver operation level */
+    int packetsize;  /* the length of the data packet */
+    unsigned char syncmask[2]; /* sync. bits */
+} mousemode_t;
+.Ed
+.Pp
+The
+.Dv protocol
+field tells the format in which the device status is returned 
+when the mouse data is read by the user program.
+It is
+.Dv MOUSE_PROTO_MSC
+at the operation level zero.
+.Dv MOUSE_PROTO_SYSMOUSE
+at the operation level one.
+.Pp
+The
+.Dv rate
+is always set to -1.
+.Pp
+The
+.Dv resolution
+is always set to -1.
+.Pp
+The
+.Dv accelfactor
+is always 0.
+.Pp
+The
+.Dv packetsize
+field specifies the length of the data packet. It depends on the
+operation level.
+.Pp
+.Bl -tag -width level_0__ -compact
+.It Em level 0
+5 bytes
+.It Em level 1
+8 bytes
+.El
+.Pp
+The array
+.Dv syncmask
+holds a bit mask and pattern to detect the first byte of the
+data packet.
+.Dv syncmask[0]
+is the bit mask to be ANDed with a byte. If the result is equal to
+.Dv syncmask[1] ,
+the byte is likely to be the first byte of the data packet.
+Note that this method of detecting the first byte is not 100% reliable,
+thus, should be taken only as an advisory measure.
+.Pp
+.It Dv MOUSE_SETMODE Ar mousemode_t *mode
+The command changes the current operation parameters of the mouse driver
+as specified in
+.Ar mode .
+Only
+.Dv level 
+may be modifiable. Setting values in the other field does not generate
+error and has no effect.
+.\" .Pp
+.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
+.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
+.\" These commands are not supported by the
+.\" .Nm
+.\" driver.
+.Pp
+.It Dv MOUSE_READDATA Ar mousedata_t *data
+.It Dv MOUSE_READSTATE Ar mousedata_t *state
+These commands are not supported by the
+.Nm
+driver.
+.Pp
+.It Dv MOUSE_GETSTATE Ar mousestatus_t *status
+The command returns the current state of buttons and 
+movement counts in the structure as defined in
+.Xr mouse 4 .
+.El
+.Ss Console and Consolectl Ioctls
+The user process issues console 
 .Fn ioctl
-also provides a method for a process to receive a
+calls to the current virtual console in order to control
+the mouse pointer.
+The console
+.Fn ioctl 
+also provides a method for the user process to receive a
 .Xr signal 3
 when a button is pressed.
 .Pp
+The mouse daemon
 .Xr moused 8
-uses this
+uses 
 .Fn ioctl
-to inform the console of mouse actions.  Applications
-.Pq such as Tn X\ Windows
-can use
-.Pa /dev/sysmouse ,
-allowing syscons and the application to share the mouse.
+calls to the console control device
+.Pa /dev/consolectl
+to inform the console of mouse actions including mouse movement
+and button status.
 .Pp
-.Bd -literal -offset indent
+Both classes
+.Fn ioctl
+commands are defined as
+.Dv CONS_MOUSECTL
+which takes the following argument.
+.Bd -literal
 struct mouse_info {
-        int     operation;
-        union {
-                struct mouse_data data;
-                struct mouse_mode mode;
-        }u;
+    int operation;
+    union {
+        struct mouse_data data;
+        struct mouse_mode mode;
+        struct mouse_event event;
+    } u;
 };
 .Ed
-.Bl -tag -width operation
+.Pp
+.Bl -tag -width operation -compact
 .It Dv operation
 This can be one of
-.Bl -tag -width MOUSE_MOVEABS
+.Pp
+.Bl -tag -width MOUSE_MOVEABS -compact
 .It Dv MOUSE_SHOW
 Enables and displays mouse cursor.
 .It Dv MOUSE_HIDE
@@ -78,11 +327,12 @@ Disables and hides mouse cursor.
 Moves mouse cursor to position supplied in
 .Dv u.data .
 .It Dv MOUSE_MOVEREL
-Add position supplied in
+Adds position supplied in
 .Dv u.data
 to current position.
 .It Dv MOUSE_GETINFO
-Returns current mouse position and button status in
+Returns current mouse position in the current virtual console 
+and button status in
 .Dv u.data .
 .It Dv MOUSE_MODE
 This sets the
@@ -90,34 +340,99 @@ This sets the
 to be delivered to the current process when a button is pressed.
 The signal to be delivered is set in
 .Dv u.mode .
+.El
+.Pp
+The above operations are for virtual consoles. The operations defined 
+below are for the console control device and used by 
+.Xr moused 8
+to pass mouse data to the console driver.
+.Pp
+.Bl -tag -width MOUSE_MOVEABS -compact
 .It Dv MOUSE_ACTION
-This takes the information in
+.It Dv MOUSE_MOTIONEVENT
+These operations take the information in
 .Dv u.data
-and acts upon it.  It includes processing button presses if the current vty
-is a text interface, and sending
-.Tn Mouse System
-protocol data to
-.Pa /dev/sysmouse
-if it is open.
+and act upon it.  Mouse data will be sent to the
+.Nm
+driver if it is open.
+.Dv MOUSE_ACTION
+also processes button press actions and sends signal to the process if
+requested or performs cut and paste operations
+if the current console is a text interface. 
+.It Dv MOUSE_BUTTONEVENT
+.Dv u.data
+specifies a button and its click count. The console driver will
+use this information for signal delivery if requested or 
+for cut and paste operations if the console is in text mode.
 .El
+.Pp
+.Dv MOUSE_MOTIONEVENT
+and 
+.Dv MOUSE_BUTTONEVENT
+are newer interface and are designed to be used together.
+They are intended to replace functions performed by
+.Dv MOUSE_ACTION
+alone.
+.Pp
 .It Dv u
 This union is one of
-.Bl -tag -width data
+.Pp
+.Bl -tag -width data -compact
 .It Dv data
-.Bd -literal -offset indent
+.Bd -literal
 struct mouse_data {
-        int     x;
-        int     y;
-        int     buttons;
+    int x;
+    int y;
+    int z;
+    int buttons;
 };
 .Ed
+.Pp
+.Dv x ,
+.Dv y 
+and
+.Dv z
+represent movement of the mouse along respective directions.
+.Dv buttons
+tells the state of buttons. It encodes up to 31 buttons in the bit 0 though
+the bit 30.  If a button is held down, the corresponding bit is set. 
+.Pp
 .It Dv mode
-.Bd -literal -offset indent
+.Bd -literal
 struct mouse_mode {
-        int     mode;
-        int     signal;
+    int mode;
+    int signal;
 };
 .Ed
+.Pp
+The
+.Dv signal
+field specifies the signal to be delivered to the process. It must be 
+one of the values defined in
+.Ao Pa signal.h Ac .
+The
+.Dv mode
+field is currently unused.
+.Pp
+.It Dv event
+.Bd -literal
+struct mouse_event {
+    int id;
+    int value;
+};
+.Ed
+.Pp
+The
+.Dv id
+field specifies a button number as in 
+.Dv u.data.buttons .
+Only one bit/button is set.
+The
+.Dv value
+field
+holds the click count: the number of times the user has clicked the button
+successively.
+.Pp
 .El
 .El
 .Sh FILES
@@ -125,11 +440,15 @@ struct mouse_mode {
 .It Pa /dev/consolectl
 device to control the console
 .It Pa /dev/sysmouse
-mouse action output
+virtualized mouse driver
+.It Pa /dev/ttyv%d
+virtual consoles
 .El
 .Sh SEE ALSO
 .Xr vidcontrol 1 ,
+.Xr ioctl 2 ,
 .Xr signal 3 ,
+.Xr mouse 4 ,
 .Xr moused 8
 .Sh HISTORY
 The
@@ -138,5 +457,7 @@ manual page example first appeared in
 .Fx 2.2 .
 .Sh AUTHOR
 This
-manual page was written by John-Mark Gurney
-.Aq gurney_j@efn.org .
+manual page was written by
+.An John-Mark Gurney Aq gurney_j@efn.org 
+and 
+.An Kazutaka YOKOTA Aq yokota@FreeBSD.org .