1.\" $Id: psm.4,v 1.2 1996/12/26 16:16:15 wosch Exp $ 2.\" 3.Dd Nov 8, 1996 4.Dt PSM 4 i386 5.Os 6.Sh NAME 7.Nm psm 8.Nd 9PS/2 mouse style pointing device driver 10.Sh SYNOPSIS 11.\".Cd "options PSM_NOCHECKSYNC" 12.\".Cd "options PSM_NOEMULATION" 13.\".Cd "options" \&"PSM_ACCEL=N\&" 14.Cd "options" \&"PSM_RESETDELAY=N\&" 15.Cd "options" \&"PSM_MAXWAIT=N\&" 16.Cd "options" \&"PSM_DEBUG=N\&" 17.Cd "device psm0 at isa? port" \&"IO_KBD\&" conflicts tty irq 12 vector psmintr 18.Sh DESCRIPTION 19The 20.Nm 21driver provides support for the PS/2 mouse style pointing device. 22 23Note that 24.Nm port \&"IO_KBD\&" 25and 26.Nm conflicts 27is required 28as the PS/2 mouse port is located 29at the auxially port of the keyboard controller, thus, the 30.Nm 31driver has to share the port with the keyboard driver. 32Note also that there is currently no provision of changing the 33.Nm irq 34number. 35.Pp 36A series of data packets is read from the 37.Nm 38driver. A data packet from the PS/2 mouse style pointing device 39is three bytes long: 40.Pp 41.Bl -tag -width Byte_1 42.It Byte 1 43.Bl -tag -width bit_7 44.It bit 7 45One indicates overflow in the vertical movement count. 46.It bit 6 47One indicates overflow in the horizontal movement count. 48.It bit 5 49Set if the vertical movement count is negative. 50.It bit 4 51Set if the horizontal movement count is negative. 52.It bit 3 53Always one?. 54.It bit 2 55Middle button status; set if pressed. For the device without the middle 56button, this bit is always one?. 57.It bit 1 58Right button status; set if pressed. 59.It bit 0 60Left button status; set if pressed. 61.El 62.It Byte 2 63Horizontal movement count in two's compliment; 64-128 through 127. 65.It Byte 3 66Vertical movement count in two's compliment; 67-128 through 127. 68.El 69.Pp 70The minor device number of the 71.Nm 72is made up of: 73.Bd -literal -offset indent 74minor = (`unit' << 1) | `non-blocking' 75.Ed 76.Pp 77where `unit' is the device number (usually 0) and the `non-blocking' bit 78is set to indicate "don't block waiting for mouse input, return immediately". 79The `non-blocking' bit should be set for \fIXFree86\fP, 80therefore the minor device number usually used for \fIXFree86\fP is 1. 81.Sh KERNEL CONFIGURATION 82There are following options to control the 83.Nm 84device. 85.Bl -tag -width MOUSE 86.\".It Em PSM_NOCHECKSYNC 87.\"By default, the driver tries to detect the first byte of 88.\"the three-byte-long data packet. However, this may not always be 89.\"reliable. This feature will be turned off by specifying this option. 90.\".It Em PSM_NOEMULATION 91.\"The 92.\".Nm 93.\"driver can emulate the Microsoft Serial Mouse's three-byte 94.\"data packet and the Mouse Systems Corp's five-byte data packet 95.\"when data is read by user programs, if so specified by the 96.\".Fn ioctl 97.\"command 98.\".Dv MOUSE_SETMODE . 99.\"The emulation will be disabled with this option. 100.\".It Em PSM_ACCEL=N 101.\"The 102.\".Nm 103.\"driver somewhat `accelerates' the movement of the pointing device. 104.\"That is, the faster you move the device, the longer the pointer 105.\"travels on the screen. This option controls the amount of acceleration. 106.\"The smaller 107.\".Fa N 108.\"is, more sensitive the movement becomes. The default value is 2. 109.\"The minimum value, thus the value for the most sensitive setting, allowed 110.\"is 1. Setting this option to zero will completely disables the 111.\"acceleration effect. 112.It Em PSM_RESETDELAY=X, PSM_MAXWAIT=Y 113The 114.Nm 115driver will attempt to reset the pointing device during the boot process. 116It sometimes takes a long while before the device will respond after 117reset. These options control how long the driver should wait before 118it eventually gives up waiting. The driver will wait 119.Fa X 120* 121.Fa Y 122msecs at most. If the driver seems unable to detect your pointing 123device, you may want to increase these values. The default values are 124200 msec for 125.Fa X 126and 5 127for 128.Fa Y . 129.It Em PSM_DEBUG=N 130Sets the debug level to 131.Fa N . 132The default debug level is zero. See 133.Em DIAGNOSTICS 134for debug logging. 135.El 136.\".Sh IOCTL 137.\".Bl -tag -width MOUSE 138.\".It Dv MOUSE_GETSTATE, MOUSECREAD 139.\"The command returns the current mouse state in the following structure 140.\"and remove the state information from the internal queue. 141.\".Bd -literal 142.\"struct mouseinfo { 143.\" unsigned char status; /* button and motion status bits */ 144.\" char xmotion; /* horizontal motion count */ 145.\" char ymotion; /* vertical motion count */ 146.\"}; 147.\".Ed 148.\".Pp 149.\"The 150.\".Dv status 151.\"holds a ORed value of the following constants: 152.\".Bl -tag -width BUTSTATMASK 153.\".It Dv BUT1STAT 154.\"The Button 1 (left button) is pressed. 155.\".It Dv BUT2STAT 156.\"The Button 2 (middle button) is pressed. 157.\".It Dv BUT3STAT 158.\"The Button 3 (right button) is pressed. 159.\".It Dv BUT1CHNG 160.\"The state of the button 1 has changed. 161.\".It Dv BUT2CHNG 162.\"The state of the button 2 has changed. 163.\".It Dv BUT3CHNG 164.\"The state of the button 3 has changed. 165.\".It Dv MOVEMENT 166.\"Either 167.\".Dv xmotion 168.\"or 169.\".Dv ymotion 170.\"is not zero. 171.\".El 172.\".Pp 173.\"Note that these commands and 174.\".Fn read 175.\"operation on the 176.\".Nm 177.\"driver uses the same internal queue. Therefore, interleaving 178.\"these commands and 179.\".Fn read 180.\"operation is not recommended. 181.\".It Dv MOUSE_GETINFO 182.\"Returns the hardware information in the following structure: 183.\".Bd -literal 184.\"typedef struct mousehw { 185.\" int buttons; /* number of buttons */ 186.\" int iftype; /* I/F type */ 187.\" int type; /* mouse/track ball/pad... */ 188.\" int hwid; /* I/F dependent hardware ID */ 189.\"} mousehw_t; 190.\".Ed 191.\".Pp 192.\"The 193.\".Dv iftype 194.\"is 195.\".Dv MOUSE_IF_PS2 196.\"for the 197.\".Nm 198.\"driver. The 199.\".Dv type 200.\"tells the device type: 201.\".Dv MOUSE_MOUSE , 202.\".Dv MOUSE_TRACKBALL , 203.\".Dv MOUSE_STICK , 204.\".Dv MOUSE_PAD , 205.\"or 206.\".Dv MOUSE_UNKNOWN . 207.\"The user should not heavily rely on this field, as the 208.\".Nm 209.\"driver may not always, in fact it is very rarely able to, identify 210.\"the device type. 211.\"The 212.\".Dv hwid 213.\"is the ID value returned by the pointing device. See below for possible 214.\"values. 215.\".It Dv MOUSE_GETMODE, MOUSE_SETMODE 216.\"The commands get and set operation mode of the 217.\".Nm 218.\"driver. 219.\".Bd -literal 220.\"typedef struct mousemode { 221.\" int protocol; /* MOUSE_PROTO_XXX */ 222.\" int rate; /* report rate (per sec), -1 if unknown */ 223.\" int resolution; /* ppi, -1 if unknown */ 224.\" int accelfactor; /* acceleration factor (must be 1 or greater) */ 225.\"} mousemode_t; 226.\".Ed 227.\".Pp 228.\"The 229.\".Dv protocol 230.\"selects the format with which the device status is returned by 231.\".Fn read . 232.\"The default is 233.\".Dv MOUSE_PROTO_PS2 , 234.\"that is, the data byte from the pointing device is returned as is. 235.\"Other possible values are: 236.\".Dv MOUSE_PROTO_MSS 237.\"and 238.\".Dv MOUSE_PROTO_MSC , 239.\"which specifies Microsoft Serial Mouse three-byte format and 240.\"Mouse Systems Corp.'s five-byte format respectively. 241.\"The 242.\".Dv rate 243.\"is the status report rate (reports/sec) at which the device will send 244.\"movement report to the host computer. 245.\"The 246.\".Dv resolution 247.\"of the pointing device is expressed in pulse-per-inch. Setting 248.\"this field to an arbitrary value may not always work. 249.\"The 250.\".Dv accelfactor 251.\"holds a value to control acceleration feature (see description on 252.\".Em PSM_ACCEL 253.\"above). It must be one or greater. 254.\"If acceleration is disabled by the kernel configuration, 255.\"setting this field has no effect. 256.\".El 257.Sh DIAGNOSTICS 258.Pp 259At debug level 0, little information is logged except for the following 260line during boot process: 261.Bd -literal -offset indent 262psm0: device ID X, N buttons? 263.Ed 264.Pp 265where 266.Fa X 267the device ID code returned by the found pointing device. 268Known IDs include: 269.Bl -tag -width 0__ 270.It Em 0 271Mouse (Microsoft, Logitech and many other manufacturers) 272.It Em 2 273Microsoft Ballpoint mouse 274.El 275.Pp 276Currently the 277.Nm 278driver can detect the 3 button mouse from Logitech and report 279accordingly. 280The 3 button mouse from the other manufacturer may or may not be 281reported correctly. However, it will not affect the operation of 282the driver. 283.Pp 284At debug level 1 more information will be logged 285while the driver probes the auxially (mouse) port. 286Messages are logged with the LOG_KERN facility at the LOG_DEBUG level. 287(See 288.Xr syslogd 8 . ) 289.Bd -literal -offset indent 290psm0: current command byte:xxxx 291psm: TEST_AUX_PORT status:0000 292psm: RESET_AUX return code:00fa 293psm: RESET_AUX status:00aa 294psm: RESET_AUX ID:0000 295psm: status xx yy zz (get_mouse_buttons) 296psm0: status 00 03 64 297.Ed 298.Pp 299The first line shows the command byte value of the keyboard 300controller just before the auxially port is probed. 301It usually is 4D, 45, 47 or 65, depending on the keyboard device 302driver. 303.Pp 304The second line shows the result of the keyboard controller's 305test on the auxially port interface, with zero indicating 306no error; note that some controllers report no error even if 307the port does not exist in the system, however. 308.Pp 309The third to fifth lines show the reset status of the pointing device. 310The functioning device should return the sequence of FA AA <ID>. 311The ID code is described above. 312.Pp 313The seventh line show the current hardware settings; it consists 314of three bytes: 315.Bl -tag -width Byte_1 316.It Byte 1 317.Bl -tag -width bit_6 318.It bit 6 3190: stream mode (default after reset), 1: remote mode. 320In the stream mode, the pointing device sends the device status 321whenever its state changes. In the remote mode, the host computer 322must request the status to be sent. 323.It bit 5 324Set if the pointing device is currently enabled. Otherwise zero. 325.It bit 4 3260 - 1:1 scaling, 1 - 2:1 scaling. 327.It bit 2 328Left button status; set if pressed. 329.It bit 1 330Middle button status; set if pressed. 331.It bit 0 332Right button status; set if pressed. 333.El 334.It Byte 2 335Resolution. 336.Bl -tag -width 100 337.It 0 33825 pulse per inch (ppi) 339.It 1 34050 ppi 341.It 2 342100 ppi 343.It 3 344200 ppi 345.El 346.It Byte 3 347The status report rate (reports/sec) at which the device will send 348movement report to the host computer. 349.El 350.Pp 351Note that the pointing device will not be enabled until the 352.Nm 353device is opened by the user programs. 354.Pp 355At debug level 2, much more detailed information is logged. 356.Sh CAVEATS 357There is not a guaranteed way to re-synchronize with the first byte 358of the packet once we are out of synchronization with the data 359stream, because there is not a unique bit pattern to identify 360the first byte with. 361.Sh BUGS 362The driver includes the code for the 363.Dv MOUSECREAD 364command of 365.Fn ioctl 366function, which fills a 367.Fa mouseinfo 368structure (see 369.Ao Pa machine/mouse.h Ac ). 370However, it currently is not functioning properly, and may be removed 371in the future. 372.Sh SEE ALSO 373.Xr syslog 3 , 374.Xr mse 4 , 375.Xr syslogd 8 376.\" .Sh HISTORY 377.\" .Sh AUTHOR 378