Added psm manpage.

Submitted by:	Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>

1 files changed, 376 insertions, 0 deletions

diff --git a/share/man/man4/psm.4 b/share/man/man4/psm.4
new file mode 100644
index 0000000..e78277c
--- /dev/null
+++ b/share/man/man4/psm.4
@@ -0,0 +1,376 @@
+.\"
+.Dd Nov 8, 1996
+.Dt PSM 4
+.Os
+.Sh NAME
+.Nm psm
+.Nd
+PS/2 mouse style pointing device driver
+.Sh SYNOPSIS
+.\".Cd "options PSM_NOCHECKSYNC"
+.\".Cd "options PSM_NOEMULATION"
+.\".Cd "options" \&"PSM_ACCEL=N\&"
+.Cd "options" \&"PSM_RESETDELAY=N\&"
+.Cd "options" \&"PSM_MAXWAIT=N\&"
+.Cd "options" \&"PSM_DEBUG=N\&"
+.Cd "device psm0 at isa? port" \&"IO_KBD\&" conflicts tty irq 12 vector psmintr
+.Sh DESCRIPTION
+The
+.Nm
+driver provides support for the PS/2 mouse style pointing device.
+
+Note that 
+.Nm port \&"IO_KBD\&"
+and
+.Nm conflicts
+is required 
+as the PS/2 mouse port is located
+at the auxially port of the keyboard controller, thus, the 
+.Nm
+driver has to share the port with the keyboard driver.
+Note also that there is currently no provision of changing the 
+.Nm irq
+number.
+.Pp
+A series of data packets is read from the
+.Nm
+driver. A data packet from the PS/2 mouse style pointing device
+is three bytes long:
+.Pp
+.Bl -tag -width Byte_1
+.It Byte 1 
+.Bl -tag -width bit_7
+.It bit 7
+One indicates overflow in the vertical movement count.
+.It bit 6
+One indicates overflow in the horizontal movement count.
+.It bit 5
+Set if the vertical movement count is negative.
+.It bit 4
+Set if the horizontal movement count is negative.
+.It bit 3
+Always one?.
+.It bit 2
+Middle button status; set if pressed. For the device without the middle
+button, this bit is always one?.
+.It bit 1
+Right button status; set if pressed.
+.It bit 0
+Left button status; set if pressed.
+.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.
+.El
+.Pp
+The minor device number of the
+.Nm
+is made up of:
+.Bd -literal -offset indent
+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 immediately".
+The `non-blocking' bit should be set for \fIXFree86\fP, 
+therefore the minor device number usually used for \fIXFree86\fP is 1.
+.Sh KERNEL CONFIGURATION
+There are following options to control the
+.Nm
+device.
+.Bl -tag -width MOUSE
+.\".It Em PSM_NOCHECKSYNC
+.\"By default, the driver tries to detect the first byte of 
+.\"the three-byte-long data packet. However, this may not always be 
+.\"reliable. This feature will be turned off by specifying this option.
+.\".It Em PSM_NOEMULATION
+.\"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 .
+.\"The emulation will be disabled with this option.
+.\".It Em PSM_ACCEL=N
+.\"The
+.\".Nm
+.\"driver somewhat `accelerates' the movement of the pointing device.
+.\"That is, the faster you move the device, the longer the pointer 
+.\"travels on the screen. This option controls the amount of acceleration.
+.\"The smaller
+.\".Fa N
+.\"is, more sensitive the movement becomes. The default value is 2.
+.\"The minimum value, thus the value for the most sensitive setting, allowed
+.\"is 1. Setting this option to zero will completely disables the
+.\"acceleration effect.
+.It Em PSM_RESETDELAY=X, PSM_MAXWAIT=Y
+The
+.Nm
+driver will attempt to reset the pointing device during the boot process.
+It sometimes takes a long while before the device will respond after
+reset. These options control how long the driver should wait before
+it eventually gives up waiting. The driver will wait
+.Fa X
+*
+.Fa Y
+msecs at most. If the driver seems unable to detect your pointing
+device, you may want to increase these values. The default values are
+200 msec for 
+.Fa X
+and 5
+for
+.Fa Y .
+.It Em PSM_DEBUG=N
+Sets the debug level to 
+.Fa N .
+The default debug level is zero. See
+.Em DIAGNOSTICS
+for debug logging.
+.El
+.\".Sh IOCTL
+.\".Bl -tag -width MOUSE
+.\".It Dv MOUSE_GETSTATE, MOUSECREAD
+.\"The command returns the current mouse state in the following structure
+.\"and remove the state information from the internal queue.
+.\".Bd -literal
+.\"struct mouseinfo {
+.\"    unsigned char status;    /* button and motion status bits */
+.\"    char xmotion;            /* horizontal motion count */
+.\"    char ymotion;            /* vertical motion count */
+.\"};
+.\".Ed
+.\".Pp
+.\"The
+.\".Dv status
+.\"holds a ORed value of the following constants:
+.\".Bl -tag -width BUTSTATMASK
+.\".It Dv BUT1STAT
+.\"The Button 1 (left button) is pressed.
+.\".It Dv BUT2STAT
+.\"The Button 2 (middle button) is pressed.
+.\".It Dv BUT3STAT
+.\"The Button 3 (right button) is pressed.
+.\".It Dv BUT1CHNG
+.\"The state of the button 1 has changed.
+.\".It Dv BUT2CHNG
+.\"The state of the button 2 has changed.
+.\".It Dv BUT3CHNG
+.\"The state of the button 3 has changed.
+.\".It Dv MOVEMENT
+.\"Either
+.\".Dv xmotion
+.\"or
+.\".Dv ymotion
+.\"is not zero.
+.\".El
+.\".Pp
+.\"Note that these commands and
+.\".Fn read
+.\"operation on the 
+.\".Nm
+.\"driver uses the same internal queue. Therefore, interleaving
+.\"these commands and 
+.\".Fn read
+.\"operation is not recommended.
+.\".It Dv MOUSE_GETINFO
+.\"Returns the hardware information 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 hwid;       /* I/F dependent hardware ID */
+.\"} mousehw_t;
+.\".Ed
+.\".Pp
+.\"The
+.\".Dv iftype
+.\"is 
+.\".Dv MOUSE_IF_PS2
+.\"for the 
+.\".Nm
+.\"driver. The
+.\".Dv type
+.\"tells the device type:
+.\".Dv MOUSE_MOUSE ,
+.\".Dv MOUSE_TRACKBALL ,
+.\".Dv MOUSE_STICK ,
+.\".Dv MOUSE_PAD ,
+.\"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.
+.\"The
+.\".Dv hwid
+.\"is the ID value returned by the pointing device. See below for possible
+.\"values.
+.\".It Dv MOUSE_GETMODE, MOUSE_SETMODE
+.\"The commands get and set operation mode of the 
+.\".Nm
+.\"driver.
+.\".Bd -literal
+.\"typedef struct mousemode {
+.\"    int protocol;    /* MOUSE_PROTO_XXX */
+.\"    int rate;        /* report rate (per sec), -1 if unknown */
+.\"    int resolution;  /* ppi, -1 if unknown */
+.\"    int accelfactor; /* acceleration factor (must be 1 or greater) */
+.\"} 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 returned as is.
+.\"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.
+.\"The
+.\".Dv rate
+.\"is the status report rate (reports/sec) at which the device will send 
+.\"movement report to the host computer.
+.\"The
+.\".Dv resolution
+.\"of the pointing device is expressed in pulse-per-inch. Setting
+.\"this field to an arbitrary value may not always work.
+.\"The
+.\".Dv accelfactor
+.\"holds a value to control acceleration feature (see description on
+.\".Em PSM_ACCEL
+.\"above). It must be one or greater.
+.\"If acceleration is disabled by the kernel configuration, 
+.\"setting this field has no effect.
+.\".El
+.Sh DIAGNOSTICS
+.Pp
+At debug level 0, little information is logged except for the following
+line during boot process:
+.Bd -literal -offset indent
+psm0: device ID X, N buttons?
+.Ed
+.Pp
+where
+.Fa X
+the device ID code returned by the found pointing device.
+Known IDs include:
+.Bl -tag -width 0__
+.It Em 0
+Mouse (Microsoft, Logitech and many other manufacturers)
+.It Em 2
+Microsoft Ballpoint mouse
+.El
+.Pp
+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.
+.Pp
+At debug level 1 more information will be logged
+while the driver probes the auxially (mouse) port.
+Messages are logged with the LOG_KERN facility at the LOG_DEBUG level.
+(See 
+.Xr syslogd 8 . )
+.Bd -literal -offset indent
+psm0: current command byte:xxxx
+psm: TEST_AUX_PORT status:0000
+psm: RESET_AUX return code:00fa
+psm: RESET_AUX status:00aa
+psm: RESET_AUX ID:0000
+psm: status xx yy zz (get_mouse_buttons)
+psm0: status 00 03 64
+.Ed
+.Pp
+The first line shows the command byte value of the keyboard
+controller just before the auxially port is probed.
+It usually is 4D, 45, 47 or 65, depending on the keyboard device
+driver.
+.Pp
+The second line shows the result of the keyboard controller's
+test on the auxially 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 third to 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 seventh line show the current hardware settings; it consists 
+of three bytes:
+.Bl -tag -width Byte_1
+.It Byte 1
+.Bl -tag -width bit_6
+.It bit 6
+0: stream mode (default after reset), 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.
+.It bit 5
+Set if the pointing device is currently enabled. Otherwise zero.
+.It bit 4
+0 - 1:1 scaling, 1 - 2:1 scaling.
+.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
+Resolution.
+.Bl -tag -width 100
+.It 0
+25 pulse per inch (ppi)
+.It 1
+50 ppi
+.It 2
+100 ppi
+.It 3
+200 ppi
+.El
+.It Byte 3
+The status report rate (reports/sec) at which the device will send 
+movement report to the host computer.
+.El
+.Pp
+Note that the pointing device will not be enabled until the 
+.Nm
+device is opened by the user programs.
+.Pp
+At debug level 2, much more detailed information is logged.
+.Sh CAVEATS
+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, because there is not a unique bit pattern to identify
+the first byte with.
+.Sh BUGS
+The driver includes the code for the 
+.Dv MOUSECREAD
+command of
+.Fn ioctl
+function, which fills a 
+.Fa mouseinfo
+structure (see 
+.Ao Pa machine/mouse.h Ac ).
+However, it currently is not functioning properly, and may be removed
+in the future.
+.Sh SEE ALSO
+.Xr mse 4 ,
+.Xr syslog 3 ,
+.Xr syslogd 8
+.\" .Sh HISTORY
+.\" .Sh AUTHOR