                          Mouse Support in XFree86

                               Kazutaka Yokota

                                20 April 1999

1.  Introduction

This document describes mouse support in XFree86 3.3.6, whose X servers have
the revised mouse driver.

Mouse configuration has often been mysterious task for novice users.  How-
ever, once you learn several basics, it is straightforward to choose options
in XF86Setup or write the "Pointer" section in the XF86Config file by hand.

2.  Supported Hardware

XFree86 X servers support four classes of mice: serial, bus, PS/2 mice and
USB.

      Serial mouse
            The serial mouse has been the most popular pointing device for
            PCs.  There have been numerous serial mouse models from a number
            of manufactures.  Despite the wide range of variations, there
            have been relatively few protocols (data format) with which the
            serial mouse talks to the host computer.

            The modern serial mouse conforms to the PnP COM device specifica-
            tion so that the host computer can automatically detect the mouse
            and load an appropriate driver.  The XFree86 3.3.2 X servers sup-
            port this specification and can detect popular PnP serial mouse
            models.

      Bus mouse
            The bus mouse connects to a dedicated interface card in an expan-
            sion slot.  Some video cards, notably those from ATI, and inte-
            grated I/O cards may also have a bus mouse connector.  Some bus
            mice are known as `InPort mouse'.

            Note that some mouse manufactures have sold a package including a
            serial mouse and a serial interface card.  Don't confuse this
            type of products with the genuine bus mouse.

      PS/2 mouse
            They are sometimes called `Mouse-port mouse'.  The PS/2 mouse is
            becoming increasingly common and popular.

            The PS/2 mouse is an intelligent device and may have more than
            three buttons and a wheel or a roller.  The PS/2 mouse is usually
            compatible with the original PS/2 mouse from IBM immediately
            after power up.  The PS/2 mouse with additional features requires
            a specialized initialization procedure to enable these features.
            Without proper initialization, it behaves as though it were an
            ordinary two or three button mouse.

      USB mouse
            USB (Universal Serial Bus) ports are present on most modern com-
            puters. Several devices can be plugged into this bus, including
            mices and keyboards.

            XFree86 3.3.6 includes support for USB mices on some systems.

Many mice nowadays can be used both as a serial mouse and as a PS/2 mouse.
They has a logic to distinguish which interface it is connected to.  However,
the mouse which is not marketed as compatible with both serial and PS/2 mouse
interface lacks this logic and cannot be used in such a way, even if you can
find an appropriate adapter with which you can connect the PS/2 mouse to a
serial port or visa versa.

XFree86 now supports the mouse with a wheel, a roller or a knob.  Its action
is detected as the Z (third) axis motion of the mouse.  As the X server or
clients normally do not use the Z axis movement of the pointing device, a new
configuration option, ZAxisMapping, is provided to assign the Z axis movement
to another axis or a pair of buttons (see below).

3.  OS Support for Mice

3.1  Summary of Supported Mouse Protocol Types

                                     Protocol Types
                     serial     PnP     BusMouse    PS/2   Extended PS/2
     OS platforms   protocols  serial   protocol  protocol  protocols
                               "Auto"  "BusMouse"  "PS/2"   "xxxPS/2"    USB
     -------------------------------------------------------------------------
     BSD/OS            Ok        ?         ?         ?         ?          ?
     FreeBSD           Ok        Ok        Ok        Ok        SP*1       SP*1
     FreeBSD(98)       Ok        ?         Ok        NA        NA         ?
     Interactive Unix  Ok        NA        ?*1       ?*1       NA         ?
     Linux             Ok        Ok        Ok        Ok        Ok         ?
     Linux/98          Ok        ?         Ok        NA        NA         ?
     LynxOS            Ok        NA        Ok        Ok        NA         ?
     NetBSD            Ok        Ok        Ok        SP*1      SP*1       SP*1
     NetBSD/pc98       Ok        ?         Ok        NA        NA         NA
     OpenBSD           Ok        Ok        Ok        Ok*1      OK*1       OK*1
     OS/2              SP*2      SP*2      SP*2      SP*2      SP*2       ?
     SCO               Ok        ?         SP*1      SP*1      NA         ?
     Solaris 2.x       Ok        NA*1      ?*1       Ok        NA         ?
     SVR4              Ok        NA*1      SP*1      SP*1      NA         ?
     PANIX             Ok        ?         SP*1      SP*1      NA         ?

     Ok: support is available,  NA: not available, ?: untested or unknown.
     SP: support is available in a different form

     *1 Refer to the following sections for details.
     *2 XFree86/OS2 will support any type of mouse that the OS supports,
        whether it is serial, bus mouse, or PnP type.

3.2  BSD/OS

No testing has been done with BSD/OS.

3.3  FreeBSD

FreeBSD supports the "SysMouse" protocol which must be specified when the
moused daemon is running in versions 2.2.1 or later.  When running the
mouseddaemon, you must always specify the /dev/sysmouse device and the "Sys-
Mouse" protocol to the X server, regardless of the actual type of your mouse.

FreeBSD versions 2.2.5 or earlier do not support extended PS/2 mouse proto-
cols ("xxxPS/2").  Always specify the "PS/2" protocol for any PS/2 mouse in
these versions regardless of the brand of the mouse.

FreeBSD versions 2.2.6 or later include the kernel-level support for these
PS/2 mice.  Specify the "PS/2" or "Auto" protocol and the X server will auto-
matically make use of the kernel-level support.  In fact, you may always
specify "Auto" to any mouse in these versions unless the mouse is an old
serial model which doesn't support PnP.

FreeBSD versions 3.1 or later have support for USB mice.  Specify the "Auto"
protocol for the /dev/ums0 device.  (If the moused daemon is running for the
USB mouse, you must use /dev/sysmouse instead of /dev/ums0 as explained
above.) See the ums(4) manual page for details.

3.4  FreeBSD(98)

The PS/2 mouse is not supported.

3.5  Interactive Unix

The PnP serial mouse support (the "Auto" protocol) is not supported for the
moment.

The bus mouse and PS/2 mouse should be supported by using the appropriate
device drivers.  Use /dev/mouse for the "BusMouse" protocol and /dev/kdmouse
for the "PS/2" protocol.  These protocols are untested but may work.  Please
send success/failure reports to <michael.rohleder@stadt-frankfurt.de>.

3.6  Linux

All protocol types should work.

3.7  Linux/98

The PS/2 mouse is not supported.

3.8  LynxOS

The PnP serial mouse support (the "Auto" protocol) is disabled in LynxOS,
because of limited TTY device driver functionality.

3.9  NetBSD

NetBSD 1.3.x and former does not support extended PS/2 mouse protocols
("xxxPS/2").  The PS/2 mouse device driver /dev/pms emulates the bus mouse.
Therefore, you should always specify the "BusMouse" protocol for any PS/2
mouse regardless of the brand of the mouse.

XFree86 3.3.6 supports the "wsmouse" protocol introduced in NetBSD 1.4 along
with the wscons console driver. You need to run binaries compiled on NetBSD
1.4 to have support for it though. Use "/dev/wsmouse0" for the device. Refer
to the wsmouse(4) manual page for kernel configuration informations.

This driver also provides support for USB mices. See the ums(4) manual page
for details.

3.10  NetBSD/pc98

The PS/2 mouse is not supported.

3.11  OpenBSD

The raw PS/2 mouse device driver /dev/psm0 uses the raw PS/2 mouse protocol.

OpenBSD 2.2 and earlier does not support extended PS/2 mouse protocols
("xxxPS/2") .  Therefore, you should specify the "PS/2" protocol for any PS/2
mouse regardless of the brand of the mouse.

OpenBSD 2.3 and later support all extended PS/2 mouse protocols.  You can
select the "Auto" protocol for PnP PS/2 mice or any specific extended
("xxxPS/2") protocol for non PnP mice.

There is also a cooked PS/2 mouse device driver /dev/pms0 which emulates the
bus mouse.  Specify the "BusMouse" protocol for any PS/2 mouse regardless of
the brand of the mouse when using this device.

XFree86 3.3.6 support USB mices on OpenBSD 2.6 and later though the generic
Human Interface Device (hid) /dev/uhid*. Select the "usb" protocol and the
/dev/uhid* instance corresponding to your mouse as the device name.

3.12  OS/2

XFree86/OS2 always uses the native mouse driver of the operating system and
will support any type of pointer that the OS supports, whether it is serial,
bus mouse, or PnP type.  If the mouse works under Presentation Manager, it
will also work under XFree86/OS2.

Always specify "OSMouse" as the protocol type.

3.13  SCO

The bus and PS/2 mouse are supported with the "OSMouse" protocol type.

The "OSMouse" may also be used with the serial mouse.

3.14  Solaris

Testing has been done with Solaris 2.5.1 and 2.6.  Logitech and Microsoft bus
mice have not been tested, but might work with the /dev/logi and /dev/msm
devices.  Standard 2 and 3 button PS/2 mice work with the "PS/2" protocol
type and the /dev/kdmouse device.  The PnP serial mouse support (the "Auto"
protocol) has been tested and does not work.

3.15  SVR4

The bus and PS/2 mouse may be supported with the "Xqueue" protocol type.

The "Xqueue" may also be used with the serial mouse.

The PnP serial mouse support (the "Auto" protocol) is not tested.

3.16  PANIX

The PC/AT version of PANIX supports the bus and PS/2 mouse with the "Xqueue"
protocol type.  The PC-98 version of PANIX supports the bus mouse with the
"Xqueue" protocol type.

4.  Configuring Your Mouse

Before using the XF86Setup or xf86config programs to set up mouse configura-
tion, you must identify the interface type, the device name and the protocol
type of your mouse.  Blindly trying every possible combination of mouse set-
tings will lead you nowhere.

The first thing you need to know is the interface type of the mouse you are
going to use.  It can be determined by looking at the connector of the mouse.
The serial mouse has a D-Sub female 9- or 25-pin connector.  The bus mice
have either a D-Sub male 9-pin connector or a round DIN 9-pin connector.  The
PS/2 mouse is equipped with a small, round DIN 6-pin connector.  Some mice
come with adapters with which the connector can be converted to another.  If
you are to use such an adapter, remember that the connector at the very end
of the mouse/adapter pair is what matters.

The next thing to decide is a device node to use for the given interface.
For the bus and PS/2 mice, there is little choice; your OS most possibly
offers just one device node each for the bus mouse and PS/2 mouse.  There may
be more than one serial port to which the serial mouse can be attached.

The next step is to guess the appropriate protocol type for the mouse.  The X
server may be able to select a protocol type for the given mouse automati-
cally in some cases.  Otherwise, the user has to choose one manually.  Follow
the guidelines below.

      Bus mouse
            The bus and InPort mice always use "BusMouse" protocol regardless
            of the brand of the mouse.

            Some OSs may allow you to specify "Auto" as the protocol type for
            the bus mouse.

      PS/2 mouse
            The "PS/2" protocol should always be tried first for the PS/2
            mouse regardless of the brand of the mouse.  Any PS/2 mouse
            should work with this protocol type, although wheels and other
            additional features are unavailable in the X server.

            After verifying the mouse works with this protocol, you may
            choose to specify one of "xxxPS/2" protocols so that extra fea-
            tures are made available in the X server.  However, support for
            these PS/2 mice assumes certain behavior of the underlying OS and
            may not always work as expected.  Support for some PS/2 mouse
            models may be disabled all together for some OS platforms for
            this reason.

            Some OSs may allow you to specify "Auto" as the protocol type for
            the PS/2 mouse and the X server will automatically adjust itself.

      Serial mouse
            The XFree86 server supports a wide range of mice, both old and
            new.  If your mouse is of a relatively new model, it may conform
            to the PnP COM device specification and the X server may be able
            to detect an appropriate protocol type for the mouse automati-
            cally.

            Specify "Auto" as the protocol type and start the X server.  If
            the mouse is not a PnP mouse, or the X server cannot determine a
            suitable protocol type, the server will print the following error
            message and abort.

                 xf86SetupMouse: Cannot determine the mouse protocol

            If the X server generates the above error message, you need to
            manually specify a protocol type for your mouse.  Choose one from
            the following list:

               o GlidePoint

               o IntelliMouse

               o Logictech

               o Microsoft

               o MMHittab

               o MMSeries

               o MouseMan

               o MouseSystems

               o ThinkingMouse

            When you choose, keep in mind the following rule of thumb:

              1.  "Logitech" protocol is for old serial mouse models from
                  Logitech.  Modern Logitech mice use either "MouseMan" or
                  "Microsoft" protocol.

              2.  Most 2-button serial mice support the "Microsoft" protocol.

              3.  3-button serial mice may work with the "Mousesystems" pro-
                  tocol. If it doesn't, it may work instead with the
                  "Microsoft" protocol although the third (middle) button
                  won't function.  3-button serial mice may also work with
                  the "Mouseman" protocol under which the third button may
                  function as expected.

              4.  3-button serial mice may have a small switch at the bottom
                  of the mouse to choose between ``MS'' and ``PC'', or ``2''
                  and ``3''.  ``MS'' or ``2'' usually mean the "Microsoft"
                  protocol.  ``PC'' or ``3'' will choose the "MouseSystems"
                  protocol.

              5.  If the serial mouse has a roller or a wheel, it may be com-
                  patible with the "IntelliMouse" protocol.

              6.  If the serial mouse has a roller or a wheel and it doesn't
                  work with the "IntelliMouse" protocol, you have to use it
                  as a regular 2- or 3-button serial mouse.

            If the "Auto" protocol is specified and the mouse seems working,
            but you find that not all features of the mouse is available,
            that is because the X server does not have native support for
            that model of mouse and is using a ``compatible'' protocol
            according to PnP information.

            If you suspect this is the case with your mouse, please send
            report to <XFree86@XFree86.Org>.

      USB mouse
            If your mouse is connected to the USB port, it can either be sup-
            ported by an OS-specific protocol (see below), or as a generic
            Human Interface Device by the "usb" protocol.

      Standardized protocols
            Mouse device drivers in your OS may use the standardized protocol
            regardless of the model or the class of the mouse.  For example,
            SVR4 systems may support "Xqueue" protocol.  In FreeBSD the sys-
            tem mouse device /dev/sysmouse uses the "SysMouse" protocol.
            Please refer to the OS support section of this file for more
            information.

5.  XF86Config Options

The following new options are available for the Pointer section of the
XF86Config file.

5.1  Buttons

This option tells the X server the number of buttons on the mouse.  Currently
there is no reliable way to automatically detect the correct number.  This
option is the only means for the X server to obtain it.  The default value is
three.

Note that if you intend to assign Z axis movement to button events using the
ZAxisMapping option below, you need to take account of those buttons into N
too.

          Buttons N

5.2  ZAxisMappping

This option maps the Z axis (wheel) motion to a pair of buttons or to another
axis.

          ZAxisMapping X
          ZAxisMapping Y
          ZAxisMapping N M

The first example will map the Z axis motion to the X axis motion.  Whenever
the user moves the wheel/roller, its movement is reported as the X axis
motion.  When the wheel/roller stays still, the real X axis motion is
reported as is.  The last example will map negative Z axis motion to the but-
ton N and positive Z axis motion to the button M.  If this option is used and
the buttons N or M actually exists in the mouse, their actions won't be
detected by the X server.

Currently this option can not be set in the XF86Setup program.  You need to
edit the XF86Config file by hand to add this option.

5.3  Resolution

The following option will set the mouse device resolution to N counts per
inch, if possible:

          Resolution N

Not all mice and OSs can support this option.  This option can be set in the
XF86Setup program.

6.  Mouse Gallery

6.1  MS IntelliMouse  (serial, PS/2)

This mouse has been supported since XFree86 3.3.  However, support in 3.3.2
is slightly different; the wheel movement is recognized as the Z axis motion.
This behavior is not compatible with XFree86 3.3, but is more consistent with
the support for other mice with wheels or rollers.  If you want to make the
wheel behave like before, you can use the new option "ZAxisMapping" as
described above.

IntelliMouse supports the PnP COM device specification.

To use this mouse as a serial device:

          Protocol "Auto" or "IntelliMouse"
          Device   "/dev/xxxx" (where xxxx is a serial port)

To use this mouse as the PS/2 device and the OS supports PS/2 mouse initial-
ization:

          Protocol "IMPS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device but the OS does not support PS/2 mouse
initialization (the wheel won't work in this case):

          Protocol "PS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device and the OS supports automatic PS/2 mouse
detection:

          Protocol "Auto"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

6.2  MS Intellimouse Explorer (PS/2, USB)

This mouse has an optical sensor which produces a nifty red glowing under it.
It has 5 buttons and a wheel, and comes with an adaptor to be used as either
PS/2 or USB.

To use this mouse as the PS/2 device and the OS supports PS/2 mouse initial-
ization:

          Protocol "IMPS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device but the OS does not support PS/2 mouse
initialization (the wheel won't work in this case):

          Protocol "PS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device and the OS supports automatic PS/2 mouse
detection:

          Protocol "Auto"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the USB device and the OS supports the generic HID pro-
tocol:

          Protocol "usb"
          Device   "/dev/uhidx" (where x is the USB device number)

To use this mouse as the USB device and the OS supports automatic mouse
detection:

          Protocol "Auto"
          Device   "/dev/xxxx"  (where xxxx is the USB mouse device)

6.3  Kensington Thinking Mouse (serial, PS/2)

This mouse has four buttons.  Thinking Mouse supports the PnP COM device
specification.

To use this mouse as a serial device:

          Protocol "Auto" or "ThinkingMouse"
          Device   "/dev/xxxx" (where xxxx is a serial port)

To use this mouse as the PS/2 device and the OS supports PS/2 mouse initial-
ization:

          Protocol "ThinkingMousePS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device but the OS does not support PS/2 mouse
initialization (the third and the fourth buttons act as though they were the
first and the second buttons):

          Protocol "PS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device and the OS supports automatic PS/2 mouse
detection:

          Protocol "Auto"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

6.4  Genius NetScroll (PS/2)

This mouse has four buttons and a roller.  The roller movement is recognized
as the Z axis motion.

To use this mouse as the PS/2 device and the OS supports PS/2 mouse initial-
ization:

          Protocol "NetScrollPS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device but the OS does not support PS/2 mouse
initialization (the roller and the fourth button won't work):

          Protocol "PS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device and the OS supports automatic PS/2 mouse
detection:

          Protocol "Auto"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

6.5  Genius NetMouse and NetMouse Pro (serial, PS/2)

These mice have a "magic button" which is used like a wheel or a roller.  The
"magic button" action is recognized as the Z axis motion.  NetMouse Pro is
identical to NetMouse except that it has the third button on the left hand
side.

NetMouse and NetMouse Pro support the PnP COM device specification.  When
used as a serial mouse, they are compatible with MS IntelliMouse.

To use these mice as a serial device:

          Protocol "Auto" or "IntelliMouse"
          Device   "/dev/xxxx" (where xxxx is a serial port)

To use this mouse as the PS/2 device and the OS supports PS/2 mouse initial-
ization:

          Protocol "NetMousePS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device but the OS does not support PS/2 mouse
initialization (the "magic button" and the third button won't work):

          Protocol "PS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device and the OS supports automatic PS/2 mouse
detection:

          Protocol "Auto"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

6.6  ALPS GlidePoint (serial, PS/2)

The serial version of this pad device has been supported since XFree86 3.2.
`Tapping' action is interpreted as the fourth button press.  (IMHO, the
fourth button of GlidePoint should always be mapped to the first button in
order to make this pad behave like the other pad products.)

To use this pad as a serial device:

          Protocol "GlidePoint"
          Device   "/dev/xxxx" (where xxxx is a serial port)

To use this mouse as the PS/2 device and the OS supports PS/2 mouse initial-
ization:

          Protocol "GlidePointPS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device but the OS does not support PS/2 mouse
initialization:

          Protocol "PS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device and the OS supports automatic PS/2 mouse
detection:

          Protocol "Auto"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

6.7  ASCII MieMouse (serial, PS/2)

This mouse appears to be OEM from Genius.  Although its shape is quite dif-
ferent, it works like Genius NetMouse Pro.  This mouse has a "knob" which is
used like a wheel or a roller.  The "knob" action is recognized as the Z axis
motion.

MieMouse supports the PnP COM device specification.  When used as a serial
mouse, it is compatible with MS IntelliMouse.

To use this mouse as a serial device:

          Protocol "Auto" or "IntelliMouse"
          Device   "/dev/xxxx" (where xxxx is a serial port)

To use this mouse as the PS/2 device and the OS supports PS/2 mouse initial-
ization:

          Protocol "NetMousePS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device but the OS does not support PS/2 mouse
initialization (the knob and the third button won't work):

          Protocol "PS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device and the OS supports automatic PS/2 mouse
detection:

          Protocol "Auto"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

6.8  Logitech MouseMan+ and FirstMouse+ (serial, PS/2)

MouseMan+ has two buttons on top, one side button and a roller.  FirstMouse+
has two buttons and a roller.  The roller movement is recognized as the Z
axis motion.  The roller also acts as the third button.  The side button is
recognized as the fourth button.

MouseMan+ and FirstMouse+ support the PnP COM device specification.  They
have MS IntelliMouse compatible mode when used as a serial mouse.

To use these mice as a serial device:

          Protocol "Auto" or "IntelliMouse"
          Device   "/dev/xxxx" (where xxxx is a serial port)

To use this mouse as the PS/2 device and the OS supports PS/2 mouse initial-
ization:

          Protocol "MouseManPlusPS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device but the OS does not support PS/2 mouse
initialization (the wheel and the fourth button won't work):

          Protocol "PS/2"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

To use this mouse as the PS/2 device and the OS supports automatic PS/2 mouse
detection:

          Protocol "Auto"
          Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)

     Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/mouse.sgml,v 1.1.2.14 1999/12/10 12:38:21 hohndel Exp $

