USB scroll mouse driver for Solaris

LEGAL DISCLAIMER

The only NDA I have signed with Sun is the "Foundation Source License Agreement". I do not believe that releasing my USB driver code puts me in violation of that agreement, since:

I am not publicising any "Reference code". At no time did I cut-n-paste anything from Sun's foundation code into my own code. Additionally, at virtually no point is my code the same as Sun code, save where the USB interface requires identical syntax to function.
All the USB-related Solaris interfaces I use, have already been made public in Solaris 8 include files: /usr/include/sys/usb/usba.h and /usr/include/sys/usb/usbai.h. Therefore, I am not disclosing any private information; merely organizing existing public information into a more easily comprehensible form.
There are no warnings in usba.h and usbai.h that they are temporary, internal-only, or "uncommitted" interfaces. Therefore it is reasonable to assume, per standard Sun proceedure, that anyone is free to use them (if they can only figure out how!)
All other (non-USB) Solaris interfaces that I use, are long-standing public Solaris driver interfaces.

NEW RELEASE, v2.1, March 2004!

NOTE: there is much more flexibility to support almost any mouse now, since I have given the ability to set "packetoffset" for troublesome mice.

Note2: the v2 driver works directly with Xsun and solaris 8+ with no additional Xsun module required.

Note3: in very very rare cases, the pointer locks up and refuses to respond. Need someone to provide me with a reliable test case. I've only seen it once so far, in months of use.

If you want to add wheel mouse support to Xsun without patching to the latest revision, you have to both install a low-level kernel driver, and install an Xsun module to use instead of the sun one, since Sun's stock module does not handle more than 3 buttons.

Required patch level for new driver
S9/sparc: 112785-17 or later

S9/x86: 112786-07 or later

S8/sparc: 108652-68 or later

S8/x86: 108653-57 or later

Required patch level for new driver
S9/sparc:	112785-17 or later
S9/x86:	112786-07 or later
S8/sparc:	108652-68 or later
S8/x86:	108653-57 or later

Source to both the low-level driver, and the Xsun module is available. However, it is most tested on Solaris x86, since that is my primary development platform.

Use any of these drivers at your own risk No warantee, implied or explicit, is given. Author not responsible for damages stemming from use or misuse of the software. Warning: you may go blind from reading type this small.

Download Source

usbsm.tar v2.1, the hardware driver (updated March 2nd, 2004)

Xsun module (historical only)
You will not need this part any more. But for historical "how do I write an Xsun module?" information, I am still keeping this available. Note, however, that it has bugs anyways. Using the standard (patched) Sun Xsun module works much better.

usbsm-xinput.tar, the Xsun module
Old Solaris express version, ported by Toomas Soome

Download binary package (NOT AVAILABLE, currently)

NEW install instructions

For the new v2.0 driver, and a patched Xsun, you just have to extract the tarfile, and run "make reallyinstall". (you'll want to not be running X, and have your mouse UNPLUGGED, before doing this)

This will both install the driver, and an openwindows config file. On x86, that means you will be able to just run kdmconfig and select "USB mouse (Scrollwheel)" and have things work.

On sparc, you'll have to also manually edit /etc/openwin/server/etc/OWconfig, and add these lines:

class="XINPUT" name="IMOUSE"
        ddxHandler="ddxSUNWmouse.so.1"
        ddxInitFunc="ddxSUNWmouseProc"
        dev="/dev/usb/usbsm0";

Using the drivers

After you have followed the READMEs and install directions in either the source or binary packages, then reinserted your USB mouse into your system, you should now be able to use the "wheel" on your mouse, to 'scroll' windows, in programs that support it. The obvious biggie is mozilla. Play, and enjoy. But dont complain too hard if something breaks. Proper bug reports, with details and test cases, however, are appreciated.

SunPC

if you have the SunPC pci add-in board on sparc, you may want to add the following entries in /opt/SUNWspci3/defaults/Sunpci.ini and adjust as needed:

[Mouse]
XButton1MapsTo=1
XButton2MapsTo=2
XButton3MapsTo=3
XButton4MapsTo=4
XButton5MapsTo=5

Troubleshooting

Xsun lockups when starting gtk apps
It has been noted that when using newer patched versions of Xsun (later than patchlevel -10 or so) starting gtk based apps like mozilla or some window manageres, may lock up the server.
This may be due to having "extra" mouse entries laying around. Look through /usr/openwin/server/etc/OWconfig and see if there is a non-commented section for XINPUT that uses ddxSUNWmouseProc. If so, remove it or comment it out. This should fix the problem.

Mouse compatibilty issues
Unfortunately, not ALL USB wheel mice seem to work, even though there is some USB hid standard for this sort of thing. For example, the pseudo-mouse with a wacom tablet, does not work with this driver.

Fine-tuning: Adjusting packetsize
If the mouse doesnt work, you should start by downloading the usbsm.tar source, and compiling the "tester" program. "make tester" will compile either sun4u/tester, or i86pc/tester for you. Run the program on your console, by doing
tester /dev/usb/usbsm0
and you should see reasonable output to your manipulation of the mouse. If you see warnings like "ignoring data of len ..." then edit the usbsm.conf file, and set the packetsize to whatever len was reported on the console. Reload the driver, rerun the tester program, and see if it works.
If it does work, then please let me know your mouse type, and the packetsize needed. [also, please let me know if there is a "maxtransfer size" value on your console].
If it does not work, then please let me know anyway, so I can add it to the list of "does not work" mice. If you feel lucky, you might try using packetoffset at value 1 or 2 before giving up completely.

Mice that work

Hopefully, most USB mice should work. But in case you want to be 100% sure before buying a new mouse, here's the start of a list

Logitech "First Mouse" (Optical, with wheel obviously :-)
Logitech Wheel Mouse Optical ("Black Limited Edition", PN930808-0403)
Targus USB-PS2 Optical Mini Mouse
Micro Innovations Wheel Mouse
Microsoft Basic Optical Mouse
Microsoft 3button mouse with Intellieye
Microsoft Trackball Explorer 1.0
[Logitech MX310 can work, with a packet size tweak]
Logitech MX300 (configure packetsize=5 )
Logitech "MX700 Cordless Optical Mouse" (configure packetsize=6 )
Kensington PocketMousePro Wireless (Model#72117)
Targus Notebook Wireless Optical Mouse (Model PAWM10U)
Logitech "Cordless MouseMan, Optical" (configure packetsize=5 )
Microsoft Wireless Optical Mouse 2.0 (configure packetsize=6, packetoffset=1)

Mice that do NOT work

Logitech TrackMan Wheel (PN 804360) [But people say it can work now..?]
Logitech [MouseMan?] M-BA47 (PN 830357)
microsoft wireless optical mouse
(perhaps people can retest the above mice, with my new packetsize adjustment, and report back to me?)

Serial port(PS/2) support

If you need support for a PS/2 wheel mouse instead, you can use Juergen's driver instead

Solaris 10/Solaris Express

If you are looking for USB2 API suport, you may try a modified version of my driver by Toomas Soome, at his website. I unfortunately do not have time to integrate his extensive changes at this point. Legend has it that the new Xsun stuff comes with usb wheelmouse support anyway.

Written by:Philip Brown
Visit the Solaris driver pages at bolthole.com. Or Search Bolthole.com