enhanced (experimental) ums mouse driver (USB) and mouse_report tool

[Duane H. Hesser]

I have posted to the web experimental patches to the FreeBSD usb
mouse driver.  I would appreciate reports from anyone willing to
test the revised driver, with particular attention to possible
regressions.

URL: http://accima.com/members/dhesser/fbsd_mouse_stuff/

The current FreeBSD mouse driver accomodates only mice which offer
a single input report, with the exception of a few mice which have
been "quirked" or special-cased.

The revised driver will also recognize and attach mice which offer
multiple input reports.  Quirks are not needed for HID conforming
mice, and existing quirks and specialized code branches have been
removed from the code.  The driver also includes several ioctl
targets which allow user-level application code access to mouse data.

A command-line tool, 'mouse_report' is also posted to the web at
the above location, which will report all of the device information
and the decoded report descriptor, and read and display data from
the mouse.  The patched driver is needed for this to work.

The current patches are against recent 6.3 sources acquired in
the normal manner via csup.  I have some manually patched files
which may work in the 7.x branch, but they are entirely untested,
and are subject to typos.  I can send them to a volunteer for
initial testing.

Here is an expanded description of the changes:

    -   Routines are included in hid.c to replace
        the defective hid_report_size() function, and to
        allow a replacment for the h_locate() function, to
        acquire and report the proper input data report ID,
        if one exists.  The new functions are given altered
        names to avoid impacting other drivers which may
        use these functions (although thought should be
        given to replacing hid_report_size() anywhere that
        multiple reports may be present in an hid report
        descriptor).  The ums driver attach routine uses
        these functions to explore and configure the mouse.

    -   the driver now sports a number of new ioctls which permit
        user level programs to display the device, interface and
        report descriptors, driver "mode", etc.  A new program
        "mouse_report" will display all of this information, and
        will read and display the protocol data sent from the
        driver to the consumer (e.g. X).  Several examples of
        mouse_report output are provided along with the program
        and USB patches.  NOTE that the program REQUIRES the
        updated ums driver.

    -   some simple changes to usb_subr.c in the probe and attach
        routine to report interface data.  There are no funcional
        changes in this file, but until you change some defines
        at the top of the  file your boot messages will include
        some additional information about device and interface ids.
        This information should be prettied up and made standard.
        Note that this provides info on all usb devices scanned,
        not just the mouse driver.

    -   an "extended sysmouse" protocol has been added to permit
        the driver to send "tilt" data to the consumer, for use
        in horizontal scrolling.  This extended protocol is not
        used unless the consumer app asks for it (mode level 3).
        Patches are available to allow the current Xorg mouse
        driver to read this protocol and set the mode level on
        open of the device.  Note that the existing ums driver
        (at least the 7.0 one) and X mouse driver "handle" tilt
        data, but are unable to communicate the data because
        the protocol packetsize is too small; this establishes
        a protocol by a new number which is nearly identical,
        save for a larger packetsize and inclusion of the tilt
        data.

        Additional changes to the sysmouse driver and moused
        will be required to allow the "tilt enabled" version of
        the Xorg server to work with moused (and it may be necessary
        to update the psm driver to allow it to share an expanded
        pipe when X is configured to use both PS/2 and usb mice).

        The mods are straightforward, but I won't make them until
        there is some likelihood that this work will be adopted.
        It's not certain that "tilt" is worth the effort (and
        there may be a better way).

        It is not necessary to install the X patches in order to
        use the new ums driver.  The X server/driver changes are
        needed only to enable "tilt" processing for horizontal
        scrolling.

The new driver has been tested on 5 mice [2 Logitech, 2 Microsoft,
and 1 HP (BTC)]:

ums0: Logitech N48, class 0/0, rev 1.00/4.01, addr 4, iclass 3/1
    (Old, corded, roller ball)
ums1: Microsoft Microsoft Wireless Optical Mouse_ 1.00, class 0/0, rev 2.00/0.07, addr 2, iclass 3/1
    (Microsoft Wireless Notebook Optical Mouse 3000, Model 1056)
ums2: Microsoft Microsoft_ 2.4GHz Transceiver V2.0, class 0/0, rev 2.00/2.50, addr 3, iclass 3/1
    (Microsoft 2.4 Ghz wireless notebook mouse)
ums3: BTC USB Multimedia Cordless Kit, rev 2.00/1.30, addr 2, iclass 3/1
    (HP Model 5189URF)
ums4: Logitech USB-PS/2 Optical Mouse, class 0/0, rev 2.00/27.20, addr 6, iclass 3/1
    (Logitech Model M-BZ96C)


I EXPECT this driver to recognize and operate, without quirk, most
'normal' USB mice with 2-8 buttons and X and Y data axes, as well
as wheels which provide a third (Z) axis (for vertical scrolling).
The objective is to allow most run-of-the-mill mice to 'just work'.

Most existing quirks (including those added in 7.0) have been
removed, because I believe the problems they addressed are handled
more directly by this version of the driver.  This could well be
a foolish expectation, hence the emphasis on testing for regressions.

The files may be found at

http://accima.com/members/dhesser/freebsd/mousestuff/

--
Duane H. Hesser
uane.hesser at gmail.com