Document recent mouse code changes.

1 files changed, 452 insertions, 196 deletions

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 .