usbwcm: STREAMS module for Wacom USB Tablets

Description

The usbwcm STREAMS module adds support for a limited number of Wacom tablets to Solaris 10 / OpenIndiana / illumos. When used alongside a suitable Xorg driver such as that provided by the linuxwacom project, it is possible to use these tablets in programs like GIMP, Inkscape, etc. For more information, please see man usbwcm(7M).

This module has been forked from the illumos project to provide access to out-of-tree patches that add support for a wider range of devices. Please see the uwacom_devs array contained within usr/src/uts/common/sys/usb/clients/usbinput/usbwcm/usbwcm.h for a complete list.

• Wacom Graphire
• Wacom Graphire 2
• Wacom Graphire 3
• Wacom Graphire 4
• Wacom Bamboo Fun
• Wacom Bamboo
• Wacom Bamboo One
• Wacom Volito
• Wacom PenStation 2
• Wacom Volito 2 (4x5 and 2x3)
• Wacom PenPartner 2
• Wacom Intuos3 (4x5, 6x8, 9x12, 12x12, 12x19, 6x11, 4x6)
• Wacom Intuos4 (4x6, 6x9, 8x13, 12x19)
• Wacom Cintiq 21UX (DTZ-2100)
• Wacom Cintiq 21UX (DTK-2100)
• Wacom DTU-2231

Usage

The usbwcm STREAMS module requires no user interaction or configuration. Once installed, the module should be automatically found and used by compatible software (e.g. the linuxwacom Xorg driver).

We encourage software developers to make use of higher-level APIs such as GTK+ or Xlib / XI2 which provide cross-platform access to tablet data. Developers requiring raw device access can find detailed information about interfacing with STREAMS modules inside Oracle's "STREAMS Programming Guide". Briefly, the I_FIND and I_PUSH ioctl commands should be used to add the usbwcm module onto stream head of a STREAMS device node such as /dev/usb/hid<N>. These calls will fail if the module is incompatible with the attached Wacom device. The sys/usb/clients/usbinput/usbwcm/usbwcm.h header includes structure and ioctl definitions which will be needed to interface with the module.

Build, Install, and Uninstall

Building of the usbwcm STREAMS module has only been tested in a limited number of environments. It is known to work in Solaris 10 05/09 ("U7") with the use of gcc4 and gmake from the OpenCSW archive. Different build systems or packages may or may not work.

Prerequisites

Your system must have a compatible compiler, linker, and make utility installed to build the usbwcm module. A full install of Solaris 10 should include a copy of gcc3, Solaris ld, and GNU make in the indicated locations. If your system is missing a required tool, you can find versions on your Solaris CD or third-party package archives such as OpenCSW.

Compatible Compilers:

• gcc3 (e.g. /usr/sfw/bin/gcc)
• gcc4 (e.g. /opt/csw/bin/gcc)
• Solaris Studio 9
• Solaris Studio 10
• Solaris Studio 11
• Solaris Studio 12

Compatible Linkers:

• Solaris ld (e.g. /usr/ccs/bin/ld)

Compatible Make Utilities:

• GNU make (e.g. /usr/sfw/bin/gmake or /opt/csw/bin/gmake)

Prior to building, please check that your $PATH variable is properly set and that the $CC variable is either empty (for Solaris Studio) or set to gcc.

$ export PATH=$PATH:/usr/sfw/bin
$ export CC=gcc

Extract the source code for usbwcm from its tarball into a directory. You can find the latest version at either the linuxwacom project on SourceForge or the linuxwacom project Github mirror.

$ bzcat usbwcm-<version>.tar.bz2 | tar xvf -
$ cd usbwcm-<version>

Build & Install

Run gmake to start the build process. If no errors occur, you can switch to the root account and install the driver with gmake install. Afterwards, reboot the system to ensure it is made aware of the newly- installed module.

$ gmake
$ su root -c "PATH=\"$PATH\" gmake install"
$ su root -c reboot

Uninstalling

To remove the module, simply run gmake uninstall and reboot.

$ su root -c "PATH=\$PATH\" gmake uninstall"
$ su root -c reboot

Packaging

The "package" make target generates a Solaris package suitable for distribution. The PKGVERSION variable defines what version number the package should receive. This must be explicitly defined unless usbwcm was cloned from git and the git command is available.

$ gmake package PKGVERSION=<version>

Development

The linuxwacom project maintains a git repository which is used for module development. This repository may be cloned with the third-party git utility (e.g. from OpenCSW) with the following command:

$ git clone git://git.code.sf.net/p/linuxwacom/usbwcm

While developing the driver, it may be useful to manually load and unload the module from memory. Neither of these commands will have an effect on the running system since the module must be pushed / popped from a specific stream head, but they may provide valuable output in the dmesg log.

# modload usbwcm
# modunload -i `modinfo | awk '/usbwcm/ {print $1}'`

Troubleshooting

Is the module installed?

To confirm that the module is installed, run the following command and examine its output. At least one result should be listed which shares your machine's architecture. That file should be located in the proper directory: /usr/kernel/strmod for an x86 ELF, /usr/kernel/strmod/amd64 for an x86-64 ELF, or /usr/kernel/strmod/sparcv9 for a SPARC v9 ELF.

# file `find /usr/kernel/strmod -name usbwcm`

Is the module loaded?

STREAMS modules are loaded on-demand by programs which require their functionality. Before running the following command, make sure that a program which uses the tablet is running (e.g. Xorg with the linuxwacom driver). The command will only print output if the module is loaded.

# modinfo | grep usbwcm

Is the software configured properly?

Your software may need to be configured before it is able to use a tablet. The Xorg linuxwacom driver, for instance, you may need to edit the /etc/X11/xorg.conf file before the Xorg libwacom driver will work. Verify your software has been configured to use the tablet and that it is using the appropriate device node (the kernel's dmesg log should contain information about which device node is associated with the tablet).

Are there any errors?

If any errors occurred while setting up the tablet or initializing the usbwcm module, valuable information may be stored in the dmesg log. Check this and other logs for information that may shed light on your particular problem. It may be that the installed version of usbwcm does not support your particular tablet.

# dmesg | egrep -i "usba|hid|usbwcm|wacom"
# ls /dev/usb/hid*

Acknowledgements

This module was originally developed by Pengcheng Chen and is based on the FreeBSD uwacom driver. Subsequent modifications have been made by the linuxwacom project to expand the number of supported devices.