Package usb.linux

This package has a Linux implementation of a usb.core.Host object, bootstrapping support, and other classes leveraging Linux USB support.

See:
Description

Class Summary

HID	Simple Linux-specific HID access, using the kernel hid and evdev driver modules.
HID.Event	Encapsulates HID i/o event reports.
Linux	Provides access to native USB host object for this process.

Package usb.linux Description

This package has a Linux implementation of a usb.core.Host object, bootstrapping support, and other classes leveraging Linux USB support. It accesses the "usbdevfs" userspace APIs (a set of currently undocumented ioctl calls) using a small bit of native code. Both Free Software (GCJ/CNI) and commercially legislated (Sun's JNI) APIs to native code have current implementations.

Multiple CPU types are supported. Only x86 and compatible systems have gotten substantial testing. Testing hasn't yet turned up problems when using Kaffe, and GCJ has worked well too; so you can freely choose your technology partners. (You aren't forced to license some specific commercial JVM, such as Sun's or IBM's.)

The rest of this package overview is a summary of Linux-specific issues you may need to know about.

usbdevfs permissions

For the moment, either work as root or set up /etc/fstab to have your /proc/bus/usb entry use the devmode=0666 option. That option means anyone can claim use of any USB device that's not got a kernel driver. For a true single-user machine, that's the model you'll expect. There are other usbdevfs mount options that can help you set up for other configurations; the Linux default is set up for use as root.

Bulk Messaging Throughput and Latency

Bulk I/O is currently limited by "usbdevfs" to single page (4KBytes) chunks, so larger writes are broken up before usbdevfs sees them. At peak throughput, that means less than four milliseconds data time before needing to schedule your Java thread again, just to keep the request queue full. Sends and receives will have a minimum latency of around a millisecond; this implementation currently does not support asynchronously queued I/O requests.

Kernel Drivers for Interfaces

At this time, interfaces with native Linux drivers can't be accessed using usb.core APIs unless that kernel driver is not loaded into the Linux kernel. The reason for this is that kernel drivers always have the first chance to claim bind to interfaces, and there is no current mechanism for unbinding them. You would normally use filesystem APIs to access such devices; they will often appear in /dev/usb/..., or as SCSI devices, or so on. See the experimental HID driver for an example of device access using such filesystem APIs. (There are a lot of kinds of HID devices. The Linux model for accessing them involves ignoring the fact that they happen to be connected using USB.)

Nonconformant USB Devices

Some devices (often early USB 1.0 ones, or "cheap" ones that haven't been tested effectively -- perhaps only against some Win98 release) will not correctly expose device descriptors after they are configured. At this writing, you can't work with such devices. (A fix is now possible, since the kernel's copies of the descriptors are now available.)

Control Messaging Issues

At this writing, some of the USB host controllers won't queue control messages. That means that drivers can interfere with each other: if one driver issues a control request, it can cause an unexpected errors in another driver. (This ought to be improved by the time Linux 2.4.0-final arrives.)

Also, the Linux kernel has no sort of mutual exclusion mechanism ("baton passing", etc.) to ensure that control requests are only made at "safe" moments. There are two risks here, which apply exclusively in cases where multiple drivers (such as a kernel one and any user program accessing usbdevfs) are both talking to that device:

1. The primary risk is from lower quality USB devices, which aren't truly conformant to the USB specification. The risk is that these devices misbehave in the face of some standard USB requests, for example by locking up until after manual reset. Just don't use such faulty devices. These likely won't be the only problems you would have with them.
2. Another risk is from devices which incorporate control messaging into their application protocols. When multiple drivers are talking to such devices, message sequencing requirements could be violated if sequencing isn't done. The risk is that these devices may also misbehave. (At this point it is not suspected to be a substantial risk except for mass storage devices.)

Some common devices (such as audio devices with a HID control for volume) can require multiple driver support. In some cases even single-interface devices may benefit from multiple-driver support. For example a standard kernel driver, plus a user mode controller to manage device-specific features not handled by the kernel.

Threading Issues

At this writing, concurrent I/O requests to a given device are don't work well because the usbdevfs driver doesn't support it through synchronous APIs. Each synchronous API request (read, write) on a given device endpoint blocks all other such requests. This is clearly not appropriate behavior.