Linux USB Frequently Asked Questions

Getting Started

1. How do I use my XXX USB device with Linux?
2. How do I make sure the correct modules are loaded?
3. Why doesn't /proc/bus/usb exist?
4. What's the fastest way to get USB HotPlugging set up?
5. Is my device supported?
6. Does Linux talk to USB 2.0 devices?
7. What "Host Controller Driver" should I use?

Information

1. What is a good book on USB?
2. What APIs are available to USB Device Drivers?
3. Got any testing tips for Linux USB Device Drivers?

Trouble Shooting

1. How do I report a bug?
2. How do I make USB be detected on my machine?
3. I've upgraded and USB doesn't work on my machine anymore.
4. Why doesn't usb-storage work in 2.2.x kernels?
5. Why is /proc/bus/usb/devices empty?
6. I get "device not accepting address"; why doesn't USB work?
7. How do I see the "USB Verbose Debug Messages" that I enabled in the kernel config?
8. Why isn't usbmgr working correctly?
9. Why do I only see one device from my multipurpose storage device?

Specific Hardware Problems

1. How do I make USB work on my Sony Vaio laptop?
2. My Asus motherboard doesn't work, or works with only one device
3. My Epson printer doesn't print anything.
4. My USB Palm device can't sync with pilot-link, why?
5. How do I get my printer working?
6. I'm having trouble using SANE 1.0.3 with my scanner.
7. My Athlon system, with AMD-756, doesn't like low speed devices.
8. Why can't I write to my ZipCD 650 with cdrecord?

Getting Started

A: You need to build a kernel with support for USB. Kernels since 2.2.18 have USB, although the 2.4.x kernels are supported better. The Linux Kernel HOWTO will tell you how to build and install your new kernel. You should then follow the "USB Guide" to setup your device.

A: You can either manually configure /etc/conf.modules (or /etc/modules.conf with 2.4-ready versions of modutils) to load the modules you require like this;

alias usb uhci
post-install uhci modprobe printer
post-install printer modprobe joydev
post-install joydev modprobe hid 

This makes sure the modules I need for my joystick and printer are loaded, if you modify your system startup to "modprobe usb".

Or ... a better way would be to set up the hotplug scripts; that sets things up to match your current hardware, instead of using a static configuration. And you may not even need to modify your system startup beyond telling it to use /etc/rc.d/init.d/hotplug to start things.

A: If you've setup the hotplug scripts it should be there, please report this to the user's mailing list.

If you don't want to use those scripts you'll need to add the following line to you're /etc/fstab;

none                    /proc/bus/usb           usbdevfs noauto         0 0

And mount this after the usbcore module has been loaded.

More information is available in the "USB Guide" under "USB Device Filesystem".

In 2.2 and 2.4 kernels this directory should be created when you load usbcore, however there will be no content till you mount usbfs (which will be the new name for usbdevfs). In 2.5 this directory will remain empty till you load a host controller.

Q: What's the fastest way to get USB HotPlugging set up?

A: HotPlugging is a facility that can load and configure drivers as you plug in your devices. The idea is that you should be able to just plug in your device and use it, even if that cuts into sales of Linux sysadmin bibles. It's not USB-specific; Cardbus hotplugging works the same way, and other kernel subsystems should be taking the same approach.

Make sure your kernel is up-to-date. Configure all your kernel USB facilities as modular, including support for both UHCI and OHCI host controllers (unless you're positive you know which type you have), and enable HOTPLUG. Then get the hotplug scripts release over at the linux-hotplug project and install it. The RPM works on RedHat systems, otherwise use the tarball and follow the instructions in the README. The setup instructions (on the web) tell you about "usbutils" and "pciutils" updates you should probably get to handle "cold-plugging", at boot time, as well as "hot-plugging" after the GNU/Linux OS has initialized.

Q: Is my device supported?

A: You should be able to tell this from the working device database. If you're device isn't there you could ask on the Linux USB User/Help mailing list. You should include the kernel version you are using (including the names of any patches you have applied) and the contents of the /proc/bus/usb/devices file while the device is plugged in.

Q: Does Linux talk to USB 2.0 devices?

A: Yes, in two ways. First the backward-compatible way: all high speed (480 Mbit/sec) devices can be used at full speed (12 Mbit/sec) in all current Linux kernels. Second if you have the EHCI driver, and a USB 2.0 host controller (EHCI, currently available as add-on PCI cards) then you can use these devices at high speed. EHCI support is available in the Linux 2.5 development kernels, and also in 2.4.19 kernels. (The 2.4.19 code should handle USB disks nicely, but for more complete USB 2.0 support, use 2.5 instead.) At this writing the EHCI driver is labeled "experimental".

Q: What "Host Controller Driver" should I use?

A: That answer comes in two stages.

First, you need to know what kind of USB "Host Controller" hardware you have. Mainstream hardware has one of three kinds, named after the hardware register-level "Host Controller Interface" (HCI) they implement. The first one was Intel's "Universal" HCI (UHCI). That type of controller doesn't do very much in hardware, which makes the software do more work (and need more memory). Most controllers on Intel or Via chipsets use UHCI. The second kind of USB 1.1 host controller was organized by Compaq and several other companies, and had fewer "Intellectual Property" restrictions. That was called the "Open" HCI (OHCI), and does quite a bit more of USB in hardware. Learning that two kinds of register interface was one too many, USB 2.0 defined just one, with much less legal encumbrance. The third, and newest, kind is the "Enhanced" HCI (EHCI), and is the only kind used to talk to high speed devices. You can tell which kind you have by output of lspci -v|grep HCI:

00:02.2 USB Controller: Silicon Integrated Systems [SiS] 7001 (rev 07) (prog-if 10 [OHCI])
00:02.3 USB Controller: Silicon Integrated Systems [SiS] 7001 (rev 07) (prog-if 10 [OHCI])
00:0b.0 USB Controller: NEC Corporation USB (rev 41) (prog-if 10 [OHCI])
00:0b.1 USB Controller: NEC Corporation USB (rev 41) (prog-if 10 [OHCI])
00:0b.2 USB Controller: NEC Corporation USB 2.0 (rev 01) (prog-if 20 [EHCI])
00:0f.0 USB Controller: VIA Technologies, Inc. USB (rev 50) (prog-if 00 [UHCI])
00:0f.1 USB Controller: VIA Technologies, Inc. USB (rev 50) (prog-if 00 [UHCI])
00:0f.2 USB Controller: VIA Technologies, Inc. USB 2.0 (rev 51) (prog-if 20 [EHCI])
00:11.0 USB Controller: OPTi Inc. 82C861 (rev 10) (prog-if 10 [OHCI])

Second, you need to know what Host Controller Driver (HCD) to use. There's only one Linux EHCI driver, ehci-hcd. (If you use it, you'll also need to use an OHCI or UHCI driver.) On 2.5 and later kernels, there's also only one OHCI driver (ohci-hcd) and one UHCI driver (uhci-hcd). On 2.4 and earlier kernels, the names are different. And while there's only one OHCI driver (usb-ohci), you probably have a choice of two UHCI drivers, usb-uhci and the "alternate (JE)" driver uhci. You probably need to load those drivers as modules, in which case lsmod will tell you whether it's already there or not. If you don't have a modular build, it's harder to tell what is working unless you mount usbfs and look at /proc/bus/usb/devices to see whether it lists a root hub for each host controller you have.

If you don't have one of those host controllers, you may need to consult more platform-specific documentation. There are host controllers that appear on custom busses and don't use the standard register interfaces; they'll show up in /proc/bus/usb/devices if they don't need additional setup. And there are also gadgets (such as PDAs running Linux on StrongARM SA-1100 processors) that act as usb devices instead of hosts. Those might have only "function" drivers, perhaps networking IP-over-USB or emulating a serial link.

Information

A: I have only read one, and thought it was very poor. I suggest that you get the specifications from http://www.usb.org, which are at no cost, are quite readable (as specifications go), and are up to date.

A: See the kerneldoc ("make htmldocs" in the root of your kernel), which should be relatively complete in current 2.5 kernels. There is also the Programming Guide for Linux USB Device Drivers, which is less current (even for 2.4 kernels) and in some cases describes behavior specific to the usb-uhci driver. (Note that in the 2.5 kernels, usb-uhci has been obsoleted.)

A: One basic thing is to make sure you make sure there are no dependencies on particular host controller hardware or drivers. You may be able to verify this with only one additional USB PCI card, and a USB 2.0 hub; borrow or own this hardware if you're maintaining a driver. Hardware differences show up particularly with error handling, so do what you can to make your driver break on each kind of controller.

Another is to make sure you test unplugging the device. That's a common way for driver bugs to panic kernels, and there are at least three different scenarios to test: driver unused, driver in use but in active, and driver active. You may find testing information page to be useful.

Trouble Shooting

A:First make sure that it's a bug that hasn't yet been fixed. Try using a recent stable kernel, the most current one if possible, to see if the bug is still "alive". If it's fixed already, keep using that kernel! Otherwise, once you've verified that the bug is still munching away, post a good description of it to the right Linux-USB mailing list.

In addition to the information required in /usr/src/linux/REPORTING-BUGS, it also helps enormously if you provide the output of /proc/bus/usb/devices. If you are having problems with your host controller being recognised, it helps to have the output of lspci -v. If it is supposed to be UHCI, it helps to know whether interrupts are being generated every second. You should send this information to the user/help mailing list.

If you are using UHCI, try to reproduce the problem with the "other" UHCI host controller driver (HCD). There are currently two UHCI drivers, which don't always behave the same: usb-uhci and uhci (the "alt" or "JE" driver). If you find that you have a workaround, please still report the problem! And make sure you say which HCD(s) you're using.

If you have access to both OHCI and UHCI host controllers, please try to reproduce your problem with both kinds of controller. Since these use different HCDs, they may behave differently in some situations. The reason might be a device drivers assuming some HCD-specific behavior, or an HCD not doing the right thing.

A: If you are sure that you actually have a suitable hardware setup, look for a BIOS option that could be applicable. It might be labelled as USB, or it might be more obscure, discussing Plug-n-Play, or having options for various types of operating systems. You may need to try various combinations.

A: If you have an SMP motherboard with BIOS set to MPS 1.4, try MPS 1.1. Some SMP motherboards need a "noapic" boot option.

A: There are many changes to the SCSI subsystem in 2.4 which means the back-port is unlikely to fully functional. Therefore the usb-storage parts of the back-port are not supported.

A: Most likely because you didn't configure your system with a USB host controller: uhci ("alt"), usb-ohci, or usb-uhci. The simplest way to set up is to build these as dynamically linked kernel modules, and use the hotplug scripts (above). You can statically link those drivers, if you make sure you've got the right one(s) for your hardware!

A: You may have some problem with your PCI setup that's preventing your USB host controller from getting hardware interrupts. When Linux submits a request, but never hears back from the controller, this is the diagnostic you'll see. To see if this is the problem, look at /proc/interrupts to see if the interrupt count for your host controller driver ever goes up. If it doesn't, this is the problem: either your BIOS isn't telling the truth to Linux (ACPI sometimes confuses these things, or setting the expected OS to windows in your BIOS), or Linux doesn't understand what it's saying.

Sometimes a BIOS fix will be available for your motherboard, and in other cases a more recent kernel will have a Linux fix. You may be able to work around this by passing the noapic boot option to your kernel, or (when you're using an add-in PCI card) moving the USB adapter to some other PCI slot. If you're using a current kernel and BIOS, report this problem to the Linux-kernel mailing list, with details about your motherboard and BIOS.

A user with an AOpen AK73Pro motherboard reported that turning off the BIOS option "Assign IRQ for USB" solved this problem for him.

A: There are two ways to see these messages, which are shown the same way that other kernel debug messages are shown. You can use dmesg, or syslog.

It's easiest to use the dmesg command to see the kernel debug messages. This accesses a fixed size "ring buffer", so that older messages get overwritten by newer ones. So it's good for seeing messages that don't oops or hang your system, so long as they're recent enough. If you are tracking a problem that oopses or hangs your system, you'll either want to make the dmesg output go to the console, so you can see what happened before the oops/hang, or use syslog.

The syslog mechanism is slightly harder to use, because you have to set it up yourself by configuring /etc/syslog.conf to save the messages. I usually set it up so kern.debug messages get saved to the /var/log/kernel file, and then clean it up by hand when it gets too big. If you're setting it up for the first time, you may want to reboot to make sure everything acts as you expect ... or at least, to kill -HUP the syslog daemon so it rereads its config file. Syslog will usually not be able to save the last few messages before an oops or a hang, since it takes time to read the dmesg output and save it.

Those two mechanisms will show you the kernel messages that are printed with KERN_DEBUG or, in the USB subsystem, with the dbg() macro when #define DEBUG is done before <linux/usb.h> is included. Much USB-related code will automatically enable this if CONFIG_USB_DEBUG is set in kernel config, but some drivers will need to be manually tweaked to define DEBUG.

A:This application was an addition to SUSE Linux. You should now be using the hotplug scripts.

A:Some distributions (notably Red Hat) turn off the kernel option CONFIG_SCSI_MULTI_LUN. This prevents usb-storage from automatically detecting all the devices in your removable storage device. You can either recompile your kernel with this option enabled or try;

echo >/proc/scsi/scsi "scsi add-single-device 0 0 0 1"

Where IIRC, the first zero is the host (so it is zero if this is your first "SCSI" adapter), the second the channel (which for usb-storage should always be zero I believe), the third is the target (which again is always 0 for usb-storage) and the last is the LUN. LUN 0 is the only one probed if this kernel option is off, so you'd need to repeat this command as root for every media type your device accepts.

Specific Hardware Problems

A:You may need to turn off the BIOS option for Plug-n-Play operating system support on some models of Vaio. Then USB should work fine, although you may have problems with using the modem. This is only needed on some models. This solution also worked on the Gateway 2000 Solo 5150 notebook.

A: Some early Asus P2B-DS and P2B-D motherboards have a design flaw that means that the chipset doesn't get sufficient voltage. I suggest returning the motherboard. Alternatively, check the Asus website at http://www.asus.com.tw/supportnews/english/mainboard/p2bx/17695.html for a hardware solution.

A: Many Epson printers (the 740 does not) need a special set of characters sent to the printer for it to use the USB interface. You can do this using a uniprint - stcany.upp - ghostscript combination, by inserting an extra initialisation string in the -dupBeginPageCommand part of stcany.upp. The string is

00 00 00
1b01 40 45 4a 4c 20 31 32 38 34 2e 34 0a
40 45 4a 4c 20 20 20 20 20 0a

A: The Palm OS 4.0 devices changed their hotsync protocol. Currently only coldsync works properly with these kinds of devices. pilot-link versions since 0.11.4 work with most devices.

A: There is a good article on this at this web site http://www.linuxnewbie.org/nhf/intel/hardware/usbprinter.html.

A: Version 1.0.1 of SANE seems to work better, you should try that. You also might want to look at the Linux USB scanner FAQ.

Q: My Athlon system, with AMD-756, doesn't like low speed devices.

A: Athlon systems using some early versions of the AMD-756 chip (up to sometime before May 2000) have a USB bug. It affects handling of low speed devices (such as some mice and keyboards) when they're connected to the root hub. Recent 2.4.x kernels (such as 2.4.5) have AMD's workaround; upgrade your kernel.

Q: Why can't I write to my ZipCD 650 with cdrecord?

A: You need to have a version of cdrecord of at least 1.10a4.