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.
Q: How do I make sure the correct modules are loaded?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.
Q: Why doesn't /proc/bus/usb exist?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 your /etc/fstab;
none /proc/bus/usb usbfs 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 (the new name for usbdevfs). In 2.6 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, if your Linux distribution for some reason hasn't included hotplug support, you can get the hotplug scripts release over at the linux-hotplug project and install it using the instructions there.
Q: Is my device supported?
A: 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.6 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.6 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.
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.
Q: What APIs are available to USB Device Drivers?A: See the kerneldoc ("make htmldocs" in the root of your kernel), which should be relatively complete in current 2.6 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 and later kernels, usb-uhci has been obsoleted.)
Q: Got any testing tips for Linux USB Device Drivers?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 inactive, and driver active. You may find this testing information page to be useful.
Q: Is it possible to boot off a USB Device?A:There are (at least) three things you need for this to be able to happen.
The first of these is something outside your control, either your BIOS supports it or not. However, you could put your kernel and initrd on a floppy and then use a USB root file system to get around this.
In your boot kernel or initial RAM disk you need to include support for all the needed items to support using a USB disk. These are documented in the Linux USB User Guide.
You also need to patch this kernel to delay when it tries to open the root file system, as the USB subsystem takes longer than is allowed to initialise and make the device available to the kernel. You'll find a patch suitable for 2.2 and 2.4 here (although the 2.4 patch could be put in init/do_mounts.c:mount_block_root() instead of fs/super.c which would be cleaner). A patch may be added to kernels later than 2.4.20 (latest current released version as I type this) to remove the need for this patch, but this hasn't happened yet.
Some external references are available here and here.
Q: What is max_sectors and how should I use it?A:For USB Mass Storage devices (that is, devices which use the usb-storage driver) max_sectors controls the maximum amount of data that will be transferred to or from the device in a single command. As the name implies this transfer length is measured in sectors, where a sector is 512 bytes (that's a logical sector size, not necessarily the same as the size of a physical sector on the device). Thus for example, max_sectors = 240 means that a single command will not transfer more than 120 KB of data.
Linux 2.6 gives you the ability to see and to change the max_sectors value for each USB storage device, independently. Assuming you have a sysfs filesystem mounted on /sys and assuming /dev/sdb is a USB drive, you can see the max_sectors value for /dev/sdb simply by running:
cat /sys/block/sdb/device/max_sectors
and you can set max_sectors to 64 by running (as root):
echo 64 >/sys/block/sdb/device/max_sectors
Values should be positive multiples of 8 (16 on the Alpha and other 64-bit platforms). There is no upper limit, but you probably shouldn't make max_sectors much bigger than 2048 (corresponding to 1 MB, which is quite a lot).
In general, increasing max_sectors will improve throughput since it means that larger amounts of data can be transferred in a single command with no need for being split up among multiple commands. Of course this is subject to diminishing returns when max_sectors is very big. More importantly, it's true only up to a point. Many devices have limits on the amount of data they can transfer, and if you try to exceed that limit you will most likely crash the device.
The default value of 240 works well with most devices. If you're not running at USB 2.0's high speed (480 Mb/s) there's no reason to increase max_sectors. If you are running at high speed and your device can take it, feel free to go as high as you like. Note that with many devices there isn't much penalty for using a smaller-than-optimum value unless you set max_sectors to something really low! Go ahead and experiment to find what value works best with your hardware.
Some devices can only transfer 64 KB or less at a time. The most notable example is the suite of USB-IDE adapters made by Genesys Logic. According to their technical support staff transfers should be limited to 32 KB (max_sectors = 64), and usb-storage automatically sets max_sectors to this value when it detects a Genesys Logic device. However people have had no trouble using 64 KB transfers (max_sectors = 128), and that's what Windows uses. You can always increase the value above 64 using sysfs, but don't go beyond 128 as Genesys Logic devices are known to fail when transferring more than 64 KB.
Q: What are the sysfs structures for Linux USB?A: For example the directory will have something like:
# ls /sys/bus/usb/devices/ 1-0:1.0 1-1.3 1-1.3.1:1.0 1-1:1.0 1-1 1-1.3.1 1-1.3:1.0 usb1
The names that begin with "usb" refer to USB controllers. More accurately, they refer to the "root hub" associated with each controller. The number is the USB bus number. In the example there is only one controller, so its bus is number 1. Hence the name "usb1".
"1-0:1.0" is a special case. It refers to the root hub's interface. This acts just like the interface in an actual hub an almost every respect; see below.
All the other entries refer to genuine USB devices and their interfaces. The devices are named by a scheme like this:
bus-port.port.port ...
In other words, the name starts with the bus number followed by a '-'. Then comes the sequence of port numbers for each of the intermediate hubs along the path to the device.
For example, "1-1" is a device plugged into bus 1, port 1. It happens to be a hub, and "1-1.3" is the device plugged into port 3 of that hub. That device is another hub, and "1-1.3.1" is the device plugged into its port 1.
The interfaces are indicated by suffixes having this form:
:config.interface
That is, a ':' followed by the configuration number followed by '.' followed by the interface number. In the above example, each of the devices is using configuration 1 and this configuration has only a single interface, number 0. So the interfaces show up as;
1-1:1.0 1-1.3:1.0 1-1.3.1:1.0
A hub will never have more than a single interface; that's part of the USB spec. But other devices can and do have multiple interfaces (and sometimes multiple configurations). Each interface gets its own entry in sysfs and can have its own driver.
A:First make sure that it's a bug that hasn't yet been fixed. Try reproducing this with the most current stable kernel (and if that doesn't work, then the latest pre-release version) 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. Avoid reporting problems except with kernels from kernel.org; for vendor/distro kernels, use your vendor/distro support channels.
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 or the output of lsusb -v. (The "lsusb" output is far more detailed and informative.) Also, say what kind of host controller you're using, including the chip vendor. (It's usually EHCI, OHCI or UHCI, with vendors like Intel, NEC, NVidia, VIA, and so on. If there's any question, just include lspci -v output.) If you are having problems with your host controller being recognised, include output of lspci -v (at least for PCI based host controllers). 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.
Because USB is a specialized data transfer protocol stack, sometimes it can be helpful to use hardware debugging tools like USB sniffers. While low-end sniffers might cost only $US400, more functional ones can easily run over $US25K. If you have access to such equipment, please mention it. Information from such tools can be the difference between being able to solve your problem, and just having to blame it on small malicious mythological evildoers.
If you have access to both OHCI and UHCI host controllers, please try to reproduce your problem with both kinds of controller. If the problem comes up using EHCI, try to reproduce it using one of the other controller drivers (e.g. by rmmod ehci-hcd). 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.
If by this point you haven't already found and fixed the problem, then you have several places to report the bug. These include your Linux vendor, and mailing lists including linux-usb-users, linux-usb-devel, and linux-kernel. Remember, always say what kernel version you're using including summarizing any custom patches you're running. If your bug report includes a patch, the USB developers list is the best way to get it evaluated and/or merged.
If you are using Linux 2.4, don't expect community assistance unless you first upgrade to a recent 2.6 kernel. If you're using any kernel that old, you should probably have some sort of vendor support agreement to handle issues that come up. If you are using UHCI on a 2.4 kernel, 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.
Q: How do I make USB be detected on my machine?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. Unless you rely on a USB keyboard or mouse during booting, it's probably safest to disable support for those in your BIOS; lots of BIOS writers seem to get that wrong, making trouble when Linux tries to take over USB.
Q: I've upgraded and USB doesn't work on my machine anymore.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.
Q: Why doesn't usb-storage work in 2.2.x kernels?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.
Q: Why is /proc/bus/usb/devices empty?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!
Q: Why doesn't USB work at all? I get "device not accepting address".A: This can be one of several problems:
Various users have had success with some specific strategy. I've collectioned their notes here.
Q: How do I see the "USB Verbose Debug Messages" that I enabled in the kernel config?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 (although kenels
since 2015 no longer have this option), but some drivers will need to
be manually tweaked to define DEBUG.
A:This application was an addition to old SUSE Linux distributions, and has been obsolete for some years now. You should be using the hotplug scripts.
Q: Why do I only see one device from my multipurpose storage device?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 (if your distribution supports this) add the following line to /etc/modules.conf;
options scsi_mod max_scsi_luns=15
If you do not want to do this for all SCSI devices then you can tell the kernel to scan for a specific device using;
echo >/proc/scsi/scsi "scsi add-single-device 0 0 0 1"
The first zero is the host id (so it is zero if this is your first "SCSI" adapter, check "cat /proc/scsi/scsi" to see which is your USB Storage device), 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 increasing the LUN number.
Q: My device stopped working in 2.6.10, what can I do?A:In the 2.6.10 kernel the method of enumerating devices was changed to follow a similar algorithm as Windows (while the standard allows both many devices require the Windows method). It seems some devices do not like this new method though. If you have started having a problem since this kernel with some of your devices you might want to use the option "old_scheme_first=y" with the usbcore module.
Q: Cdrecord fails with a "Cannot allocate memory" message.A:This might be caused by a max_sectors limitation. For certain USB mass-storage devices (most notably the USB-IDE adapters made by Genesys Logic) usb-storage automatically sets max_sectors to 64, which corresponds to a maximum transfer length of 32 KB. However cdrecord doesn't know about this maximum length and has no good way to find out, so it uses its default transfer length, which is 63 KB. The result is that data transfers fail and nothing can be written to the disc.
You can see if this is the case by checking the max_sectors value. If it is, there are two ways of solving the problem.
First, you can try increasing max_sectors to 128, corresponding to 64 KB. usb-storage sometimes is overly conservative and sets the value lower than it needs to be. In particular, the Genesys Logic adapters seem to work just fine with max_sectors = 128, even though engineers from that company have claimed differently.
Second, if you prefer not to fiddle with kernel settings, you can simply tell cdrecord to reduce its transfer size to 32 KB. The command-line option to use is ts=32k and it is described in the man page for cdrecord.
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.
Q: My Asus motherboard doesn't work, or works with only one deviceA: 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.
Q: My Epson printer doesn't print anything.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.
Q: How do I get my printer working?A: There is a good article on this at this web site http://www.justlinux.com/nhf/Hardware/Getting_USB_and_Your_Printer_Working.html.
Q: I'm having trouble using SANE 1.0.3 with my scanner.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.
Q: PCChips M801 with SIS7001 USB Controller provides too little current.
A: A user reported this. If this is the case then using a powered hub should help.