usb/106565: [PATCH] ums(4) does not work if the mouse defaults to boot protocol

[Eugene M. Kim]

>Number:         106565
>Category:       usb
>Synopsis:       [PATCH] ums(4) does not work if the mouse defaults to boot protocol
>Confidential:   no
>Severity:       serious
>Priority:       high
>Responsible:    freebsd-usb
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          sw-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Dec 10 15:30:15 GMT 2006
>Closed-Date:
>Last-Modified:
>Originator:     Eugene M. Kim
>Release:        FreeBSD 7.0-CURRENT i386
>Organization:
>Environment:
System: FreeBSD seerajeane.astralblue.net 7.0-CURRENT FreeBSD 7.0-CURRENT #12: Fri Dec 1 05:37:54 PST 2006 ab at seerajeane.astralblue.net:/home/FreeBSD/build/MAIN/obj/home/FreeBSD/build/MAIN/src/sys/PL-SEERAJEANE i386
>Description:
Most USB mice support two protocols (data formats) for reporting their
status:

- The "report protocol," which is the default protocol (at least in the
  HID specification version 1.11), and supports a wide arrange of
  button/axis layouts, including wheels as well as more than three
  buttons, and

- The "boot protocol," which is an optional protocol where the status
  data follows the "boot interface" report descriptor (see HID 1.11,
  section B.2) instead of the mouse's own report descriptor.  (A HID
  report descriptor is metadata stored in a HID (such as a mouse or a
  keyboard), and describes what kind of data (such as keypresses, mouse
  movements and button presses) is available and how a "report" from the
  device should be parsed to recover the data.)

HID 1.11, section 7.2.6 recommends that all devices default to report
protocol, and that the host make no assumptions about the device's state
and set the desired protocol whenever initializing a device.

ums(4) does not, however, set the protocol as recommended, and fails to
work properly with mouse models that default errneously to the boot
protocol.  The most common symptoms are:

- The mouse wheel does not work.  This is because the mouse follows the
  boot interface report descriptor, which does not have the Z-axis or
  wheel information.

- In some cases, when the user moves the mouse cursor and/or presses a
  button, the mouse behaves as if its wheel were turned (and
  consequently moves the scrollbar of the current window, for example).
  This is because a report has only 3 bytes under the boot protocol,
  while ums(4) expects and uses more data (which is uninitialized
  garbage) after the first 3 bytes of valid data.

- Rarely, the mouse is recognized but does not work at all, except when
  a button is pressed and the cursor moves erratically and spurious
  button events are generated (i.e. the mouse behaves as if some other
  buttons are pressed).  This is because the mouse's own report
  descriptor uses Report ID tags, which cause the report ID byte to be
  included at the beginning of a report before other data, while the
  reports that the mouse generates in its default, boot mode do not have
  the ID byte.  ums(4), assuming the mouse is operating under the
  "report protocol" (that is, non-boot), expects this ID byte and
  incorrectly parses the reports.
>How-To-Repeat:
Use ums(4) with any mouse that defaults to the boot protocol, including:

- Gyration GyroPoint RF Technology Receiver (Gyration Ultra Cordless)
>Fix:
Apply the following patch:

-------------------- snip -------------------- snip --------------------
--- sys/dev/usb/ums.c	Wed Sep  6 17:06:42 2006
+++ sys/dev/usb/ums.c.new	Sun Dec 10 02:19:15 2006
@@ -597,6 +597,14 @@
 
 	callout_handle_init((struct callout_handle *)&sc->callout_handle);
 
+	/*
+	 * Force the report (non-boot) protocol.
+	 *
+	 * Mice without boot protocol support may choose not to implement
+	 * Set_Protocol at all; do not check for error.
+	 */
+	usbd_set_protocol(sc->sc_iface, 1);
+
 	/* Set up interrupt pipe. */
 	err = usbd_open_pipe_intr(sc->sc_iface, sc->sc_ep_addr,
 				USBD_SHORT_XFER_OK, &sc->sc_intrpipe, sc,
-------------------- snip -------------------- snip --------------------
>Release-Note:
>Audit-Trail:
>Unformatted: