/[gentoo]/xml/htdocs/doc/en/usb-guide.xml
Gentoo

Contents of /xml/htdocs/doc/en/usb-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (hide annotations) (download) (as text)
Sat Mar 26 17:01:21 2005 UTC (9 years, 8 months ago) by swift
Branch: MAIN
File MIME type: application/xml
#72958 - Add USB Guide

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2    
3     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5     <guide link="/doc/en/usb-guide.xml">
6     <title>Gentoo Linux USB Guide</title>
7    
8     <author title="Author">
9     <mail link="fox2mike@gmail.com">Shyam Mani</mail>
10     </author>
11    
12     <abstract>
13     This document helps a user setup USB on a Gentoo system and configure various
14     USB devices as well.
15     </abstract>
16    
17     <!-- The content of this document is licensed under the CC-BY-SA license -->
18     <!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
19     <license/>
20    
21     <version>1.0</version>
22     <date>2005-03-02</date>
23    
24     <chapter>
25     <title>Introduction</title>
26     <section>
27     <title>What is USB?</title>
28     <body>
29    
30     <p>
31     USB stands for Universal Serial Bus and is basically an external interface
32     standard that enables communication between the computer and various other
33     peripherals. Some of the most commonly used USB devices today are keyboards,
34     mice, pen drives, digital cameras, external CD &amp; DVD writers, printers etc.
35     </p>
36    
37     <p>
38     There are currently two versions of USB in use, i.e. USB 1.1 and USB 2.0.
39     Since USB has always been backward compatible with its previous versions,
40     USB 2.0 is backwards compatible with USB 1.1. The latest USB devices are
41     typically USB 2.0 compatible. USB 2.0 supports a maximum data transmission
42     speed of 480 Mbps or 60 MBps and this is the major difference between the two
43     standards. Another advantage with USB is that the devices are all
44     <e>hot-pluggable</e>, which means that you do not have to restart your system
45     in order for you to be able to use these devices.
46     </p>
47    
48     </body>
49     </section>
50    
51     <section>
52     <title>A Technical Perspective</title>
53     <body>
54    
55     <p>
56     Before we go onto the exact configuration options in the kernel, it would
57     be apt to look at USB in a little more detail. If you're in a hurry or want
58     to skip this section, please go to <uri link="#kernel">Kernel Configuration</uri>.
59     </p>
60    
61     <p>
62     A USB system has a host controller, hubs, a <e>root hub</e> amongst others
63     and can support up to 127 USB devices including the hubs. The host controller
64     is nothing but the hardware interface between the USB device and the
65     operating system. There are a couple of HCI (Host Controller Interface)
66     in use today and they are the OHCI (Open HCI) by Compaq, UHCI (Universal HCI)
67     and EHCI (Enhanced HCI), both from Intel. The OHCI/UHCI are the two industry
68     standard USB 1.1 interfaces whereas the EHCI is for USB 2.0.
69     </p>
70    
71     <p>
72     The hardware vendor provides an interface for the programmer that allows
73     the system to interact with the hardware and this is called the HCD or Host
74     Controller Device. It is through this HCD that the device interacts with the
75     system software. The following diagram should make things easier to comprehend.
76     </p>
77    
78     <pre caption="General USB Architecture">
79     <comment>(Software consists of other components as well like the device driver, but
80     for the sake of simplicity, they are not shown)</comment>
81    
82     + ---- Hardware ---- + ---- Software ---- +
83     | | |
84     | [USB Dev] -+-> {EHCI} -+---> ( EHCD ) |
85     | | | | User
86     | `-> {UHCI} -+---> ( UHCD ) |
87     | | |
88     + ---- Hardware ---- + ---- Software ---- +
89    
90     </pre>
91    
92     <p>
93     A USB device can either use a custom driver or use one already present in
94     the system and this is based on the concept of a device <e>class</e>. This
95     means that if a device belongs to a certain <e>class</e>, then other devices
96     belonging to the same <e>class</e> can make use of the same device driver.
97     Some of these <e>classes</e> are the USB HID (Human Interface Devices) class
98     which covers input devices like keyboards and mice, the USB Mass Storage
99     devices class which covers devices like pen drives, digital cameras, audio
100     players etc and the USB CDC (Communication Devices Class) which essentially
101     covers USB modems and similar devices.
102     </p>
103    
104     </body>
105     </section>
106    
107     <section id="#lspci">
108     <title>What's on your machine?</title>
109     <body>
110    
111     <p>
112     It is very simple to find out whether your machine has USB 2.0 support or not.
113     We make use of the <c>lspci</c> command for this purpose.
114     </p>
115    
116     <note>
117     The <c>lspci</c> tool is a part of the <c>sys-apps/pciutils</c> package. If
118     you do not have this installed, please <c>emerge pciutils</c>. Please note
119     that you have to be root while running the <c>lspci</c> command.
120     </note>
121    
122     <pre caption="Various lspci outputs">
123     <comment>(In system that is USB 1.1 compliant, note the UHCI only)</comment>
124    
125     # <i>lspci -v | grep USB</i>
126     0000:00:04.2 USB Controller: Intel Corp. 82371AB/EB/MB PIIX4 USB (rev 01) (prog-if 00 [UHCI])
127    
128     <comment>(A system that is USB 2.0 compliant, note the EHCI and UHCI)</comment>
129    
130     00:1d.0 USB Controller: Intel Corp. 82801DB USB (Hub #1) (rev 01) (prog-if 00 [UHCI])
131     00:1d.1 USB Controller: Intel Corp. 82801DB USB (Hub #2) (rev 01) (prog-if 00 [UHCI])
132     00:1d.2 USB Controller: Intel Corp. 82801DB USB (Hub #3) (rev 01) (prog-if 00 [UHCI])
133     00:1d.7 USB Controller: Intel Corp. 82801DB USB EHCI Controller (rev 01) (prog-if 20 [EHCI])
134     </pre>
135    
136     <p>
137     So using the <c>lspci</c> command, we can find out if the system supports
138     USB 2.0. This is useful as we will be enabling the corresponding options in
139     the kernel.
140     </p>
141    
142     </body>
143     </section>
144     </chapter>
145    
146     <chapter id="kernel">
147     <title>Kernel Configuration</title>
148     <section>
149     <title>Getting the kernel</title>
150     <body>
151    
152     <p>
153     First emerge the kernel sources of your choice. Here we'll use the
154     <c>gentoo-dev-sources</c> (for 2.6.x) and <c>gentoo-sources</c> (for 2.4.x).
155     For more information on the various kernel sources available on Portage,
156     please look up the <uri link="/doc/en/gentoo-kernel.xml">Gentoo Linux Kernel Guide</uri>.
157     </p>
158    
159     <pre caption="Getting the kernel sources">
160     <comment>(For 2.6.x)</comment>
161     # <i> emerge gentoo-dev-sources</i>
162     <comment>(For 2.4.x)</comment>
163     # <i> emerge gentoo-sources</i>
164     </pre>
165    
166     <p>
167     Now, lets get on with the task of configuring the kernel.
168     </p>
169    
170     <pre caption="Heading over to the source">
171     # <i> cd /usr/src/linux</i>
172     # <i> make menuconfig</i>
173     </pre>
174    
175     <note>
176     The above example assumes that <path>/usr/src/linux</path> symlink points to
177     the kernel sources you want to use. Please ensure the same before proceeding.
178     </note>
179    
180     </body>
181     </section>
182    
183     <section id="2.6.xconfig">
184     <title>Config options for the 2.6.x kernel</title>
185     <body>
186    
187     <p>
188     Now we will look at some of the options we will have to enable in the 2.6
189     kernel to ensure proper USB support for our devices. If you are using a 2.4
190     kernel, please proceed with <uri link="#2.4.xconfig">Config options for the
191     2.4.x kernel</uri>.
192     </p>
193    
194     <note>
195     Examples in this document will show configuration options for basic USB
196     support as well as those needed commonly, for example a USB mass storage
197     device (most cameras and USB pen drives). If you have a specific USB device
198     that needs to be configured, please look up your device's manual or search
199     online to see if that device has support built-in into the kernel or custom
200     drivers that you can use. Please note that for the sake of ease, all examples
201     have the options compiled into the kernel. If you would like to have a modular
202     kernel, ensure that you note down the various modules and adjust your config
203     files accordingly.
204     </note>
205    
206     <pre caption="make menuconfig options for 2.6 kernels">
207     Device Drivers ---&gt;
208     SCSI device support ---&gt;
209    
210     <comment>(Although SCSI will be enabled automatically when selecting USB Mass Storage, we need to enable disk support.)</comment>
211     --- SCSI support type (disk, tape, CD-ROM)
212     &lt;*&gt; SCSI disk support
213    
214     <comment>(Then move back a level and go into USB support)</comment>
215     USB support ---&gt;
216    
217     <comment>(This is the root hub and is required for USB support. If you'd like to compile this as a module,</comment>
218     <comment> it will be called usbcore.)</comment>
219     &lt;*&gt; Support for Host-side USB
220    
221     <comment>(Enable this option to see your USB devices in /proc/bus/usb. This is recommended.)</comment>
222     [*] USB device filesystem
223    
224     <comment>(Select at least one of the HCDs. If you are unsure, picking all is fine.)</comment>
225     --- USB Host Controller Drivers
226     &lt;*&gt; EHCI HCD (USB 2.0) support
227     &lt; &gt; OHCI HCD support
228     &lt;*&gt; UHCI HCD (most Intel and VIA) support
229    
230     <comment>(Moving a little further down, we come to CDC and mass storage.)</comment>
231     &lt; &gt; USB Modem (CDC ACM) support
232     &lt;*&gt; USB Printer support
233     &lt;*&gt; USB Mass Storage support
234     [*] USB Mass Storage Write-Protected Media Detection (EXPERIMENTAL)
235    
236     <comment>(And then the HID bits. You have to select HID input support if you have a USB</comment>
237     <comment> keyboard, mouse, joystick or any other USB input device)</comment>
238     --- USB Input Devices
239     &lt;*&gt; USB Human Interface Device (full HID) support
240     [*] HID input layer support
241    
242     <comment>(If you have a USB Network Card like the RTL8150, you'll need this)</comment>
243     USB Network Adapters --->
244     &lt;*&gt; USB RTL8150 based ethernet device support (EXPERIMENTAL)
245    
246     <comment>(If you have a serial to USB converter like the Prolific 2303, you'll need this)</comment>
247     USB Serial Converter support --->
248     &lt;*&gt; USB Serial Converter support
249     &lt;*&gt; USB Prolific 2303 Single Port Serial Driver (NEW)
250     </pre>
251    
252     <p>
253     Now that your options are set, you can (re)compile the kernel and USB support
254     should be functional once you reboot into the new kernel. You can now proceed
255     to <uri link="#postkern">Seeing USB at work</uri> and see if everything is
256     working as it should.
257     </p>
258     </body>
259     </section>
260    
261     <section id="2.4.xconfig">
262     <title>Config options for the 2.4.x kernel</title>
263     <body>
264    
265     <p>
266     We will look at the options the we will have to enable in the 2.4 kernel to
267     ensure proper USB support for our devices. If you are using a 2.6 kernel,
268     please look at <uri link="#2.6.xconfig">Config options for the 2.6.x
269     kernel</uri>.
270     </p>
271    
272     <note>
273     Examples in this document will show configuration options for basic USB
274     support as well as those needed commonly, for example a USB mass storage
275     device (most cameras and USB pen drives). If you have a specific USB device
276     that needs to be configured, please look up your device's manual or search
277     online to see if that device has support built-in into the kernel or custom
278     drivers that you can use. Please note that for the sake of ease, all examples
279     have the options compiled into the kernel. If you would like to have a modular
280     kernel, ensure that you note down the various modules and adjust your config
281     files accordingly.
282     </note>
283    
284     <pre caption="make menuconfig options for 2.4 kernels">
285     <comment>(This immediate config is only for those who have USB input devices. Input</comment>
286     <comment> core support is needed by USB HID later.)</comment>
287     Input core support ---&gt;
288     &lt;*&gt; Input core support
289     &lt; &gt; Keyboard support
290     &lt; &gt; Mouse support
291     &lt; &gt; Event interface support
292    
293     USB support ---&gt;
294    
295     <comment>(This is the root hub and is required for USB support. If you'd like to compile this as a module,</comment>
296     <comment> it will be called usbcore.o)</comment>
297     &lt;*&gt; Support for USB
298    
299     <comment>(Enable this option to see your USB devices in /proc/bus/usb. This is recommended.)</comment>
300     [*] Preliminary USB device filesystem
301    
302     <comment>(Select at least one of the HCDs. If you are unsure, picking all is fine.)</comment>
303     --- USB Host Controller Drivers
304     &lt;*&gt; UHCI Alternate Driver (JE) support
305     &lt; &gt; OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support
306    
307     <comment>(This is the device section. Select only what you need.)</comment>
308     --- USB Device Class drivers
309     &lt; &gt; USB Audio support
310     &lt;*&gt; USB Mass Storage support
311     &lt; &gt; USB Modem (CDC ACM) support
312     &lt;*&gt; USB Printer support
313    
314     <comment>(Followed by the HID section. This is needed if you have an USB based input device.)</comment>
315     --- USB Human Interface Devices (HID)
316     &lt;*&gt; USB Human Interface Device (full HID) support
317     [*] HID input layer support
318    
319     <comment>(If you have a serial to USB converter like the Prolific 2303, you'll need this)</comment>
320     USB Serial Converter support --->
321     &lt;*&gt; USB Serial Converter support
322     &lt;*&gt; USB Prolific 2303 Single Port Serial Driver (NEW)
323     </pre>
324    
325     <p>
326     Now that the options are set, you can (re)compile the kernel and USB support
327     should be functional once you reboot into the new kernel.
328     </p>
329     </body>
330     </section>
331     </chapter>
332    
333     <chapter id="postkern">
334     <title>Seeing USB at work</title>
335     <section>
336     <title>dmesg is your friend!</title>
337     <body>
338    
339     <p>
340     The time has finally come to play with those USB devices :) So let's get
341     started. In this chapter, we'll see how the system responds to various USB
342     devices. We'll start by plugging in a USB 512 MB Memory Stick/Pen Drive. You
343     could use some other similar mass storage device. We will primarily use
344     <c>dmesg</c> to see what is happening and how the system responds to the
345     device.
346     </p>
347    
348     <note>
349     <c>dmesg</c> will generally give a lot of output up front before coming to the
350     info we need, as it reads the kernel ring buffer that has all the boot up
351     messages as well. The output in the following examples have only the relevant
352     portion(s) ans extra spaces in between to enable better readability.
353     </note>
354    
355     <pre caption="dmesg output for Memory Stick">
356     <comment>(Plug in Memory Stick into available USB port and then..)</comment>
357     # <i>dmesg</i>
358    
359     <comment>(The device is picked up as a USB 1.1 and allocated an address. Also says what HCD it is using.)</comment>
360     usb 1-1: new full speed USB device using uhci_hcd and address 2
361    
362     <comment>(SCSI emulation automatically kicks in)</comment>
363     scsi0 : SCSI emulation for USB Mass Storage devices
364     usb-storage: device found at 2
365    
366     <comment>(Now the device information including model number is retrieved)</comment>
367     usb-storage: waiting for device to settle before scanning
368     Vendor: JetFlash Model: TS512MJF2A Rev: 1.00
369     Type: Direct-Access ANSI SCSI revision: 02
370     SCSI device sda: 1003600 512-byte hdwr sectors (514 MB)
371    
372     <comment>(The write-protect sense is EXPERIMENTAL code in the later kernels)</comment>
373     sda: Write Protect is off
374     sda: Mode Sense: 0b 00 00 08
375     sda: assuming drive cache: write through
376     SCSI device sda: 1003600 512-byte hdwr sectors (514 MB)
377     /dev/scsi/host0/bus0/target0/lun0: p1
378     Attached scsi removable disk sda at scsi0, channel 0, id 0, lun 0
379     Attached scsi generic sg0 at scsi0, channel 0, id 0, lun 0, type 0
380     usb-storage: device scan complete
381     <comment>(At this point, the device is generally accessible by mounting /dev/sda1)</comment>
382    
383     <comment>(When the device is disconnected, the system acknowledges the same)</comment>
384     usb 1-1: USB disconnect, address 2
385     </pre>
386    
387     <p>
388     Once the device is connected and mounted, you can access it like a normal hard
389     disk. Usual operations like <c>cp</c>, <c>mv</c>, <c>rm</c> etc work fine. You
390     could also create a filesystem on the USB stick/format it.
391     </p>
392    
393     <pre caption="Accessing the Memory Stick">
394     # <i>mount /dev/sda1 /mnt/usb</i>
395     # <i>df -h</i>
396     Filesystem Size Used Avail Use% Mounted on
397     /dev/hda8 9.4G 7.5G 1.9G 80% /
398     /dev/hda9 11G 8.1G 2.4G 78% /usr
399     none 189M 0 189M 0% /dev/shm
400     /dev/sda1 490M 34M 457M 7% /mnt/usb
401     </pre>
402    
403     <note>
404     Digital cameras can be accessed the same way as memory sticks. I have a Nikon
405     Coolpix 5200 and this is the way I access it. The camera is set to behave like
406     a USB mass storage device (as against PTP mode, which most cameras have these
407     days) and the procedure is exactly the same, because of which I have not
408     explained in detail about the same. Please note that this may NOT work in all
409     cases and with all digital cameras that have USB support.
410     </note>
411    
412     <p>
413     How would a USB mouse show up in case you had one? It will show up as an HID
414     device.
415     </p>
416    
417     <pre caption="USB Optical Mouse">
418     # <i>dmesg | grep USB</i>
419     drivers/usb/input/hid-core.c: v2.0:USB HID core driver
420     usb 1-1: new low speed USB device using address 2
421     input: USB HID v1.10 Mouse [Logitech USB-PS/2 Optical Mouse] on usb-0000:00:07.2-1
422     </pre>
423    
424     <p>
425     Another nifty command you can use to see the status of your USB ports is
426     <c>lsusb</c>. This is part of <c>sys-apps/usbutils</c> and will be covered in
427     the next chapter.
428     </p>
429    
430     </body>
431     </section>
432     </chapter>
433    
434     <chapter>
435     <title>Userspace USB</title>
436     <section>
437     <title>Nifty tools</title>
438     <body>
439    
440     <p>
441     So far we've seen how much support exists on the kernel/system side for USB on
442     Linux. Now we'll take a peek into what kind of support is provided by Gentoo
443     for USB in the userspace.
444     </p>
445    
446     <p>
447     One of the most useful tools around is <c>lsusb</c>. This lists all the usb
448     devices connected to the system. Installing it is a breeze.
449     </p>
450    
451     <pre caption="Installing usbutils">
452     # <i>emerge usbutils</i>
453     </pre>
454    
455     <p>
456     Once installed, you can just run <c>lsusb</c> to get simple info on the USB
457     devices attached to the machine.
458     </p>
459    
460     <note>
461     You have to be root in most cases to run <c>lsusb</c>.
462     </note>
463    
464     <warn>
465     <c>lsusb</c> reads the information for the USB devices from
466     <path>/proc/bus/usb</path>. If you have not enabled that in your kernel,
467     chances are that <c>lsusb</c> may not work at all. Please ensure you have
468     <path>/proc</path> filesystem support enabled in your kernel and that
469     <c>usbfs</c> is mounted at <path>/proc/bus/usb</path> (which should happen
470     automatically).
471     </warn>
472    
473     <pre caption="lsusb at work">
474     # <i>lsusb</i>
475     <comment>(This is the 512 MB Memory Stick from Transcend)</comment>
476     Bus 001 Device 003: ID 0c76:0005 JMTek, LLC. USBdisk
477     <comment>(This is the Optical Mouse)</comment>
478     Bus 001 Device 002: ID 046d:c00e Logitech, Inc. Optical Mouse
479     <comment>(This is the root hub)</comment>
480     Bus 001 Device 001: ID 0000:0000
481     </pre>
482    
483     <p>
484     If you are one of those types who love to see lots of information, you have
485     the option of running <c>lsusb -v</c>. Try that and see the amount of info it
486     gives out. Another good option is that <c>lsusb</c> dumps the current physical
487     USB hierarchy as a tree and thus makes it easier to understand the exact
488     device map. The command is <c>lsusb -t</c>. For example,
489     </p>
490    
491     <pre caption="lsusb showing USB hierarchy">
492     # <i>lsusb -t</i>
493     Bus# 1
494     `-Dev# 1 Vendor 0x0000 Product 0x0000
495     |-Dev# 2 Vendor 0x046d Product 0xc00e
496     `-Dev# 3 Vendor 0x0c76 Product 0x0005
497     </pre>
498    
499     <p>
500     You can easily correlate the outputs of <c>lsusb</c> and <c>lsusb -t</c>,
501     which helps debugging as well as understanding how USB works.
502     </p>
503    
504     </body>
505     </section>
506    
507     <section>
508     <title>Hot or Cold plug??</title>
509     <body>
510    
511     <p>
512     Gentoo uses two packages, <c>sys-apps/hotplug</c> and <c>sys-apps/coldplug</c>
513     to do some magic with <e>hot-pluggable</e> devices. Just like any other magic
514     trick, there is a simple logic behind this one too. We shall now see what that
515     is, and in the process hopefully we will be able to understand these twins
516     better.
517     </p>
518    
519     <p>
520     Firmware can be defined as the software on a piece of hardware that is loaded
521     and executed but can't be modified easily. Many devices have firmware in them
522     to ensure that they work properly and often firmware may contain code that is
523     critical to ensure that the hardware performs as expected. Firmware is present
524     in a wide variety of computer devices ranging from ROM chips to state of the
525     art USB and PCMCIA cards. When a device is plugged in, the firmware (which may
526     in some cases be the driver as well) is read and loaded onto memory after
527     which the device can be used by the system.
528     </p>
529    
530     <p>
531     To cut the long story short, Gentoo uses <c>sys-apps/hotplug</c> to handle
532     the firmware side of things in <e>hot-pluggable</e> devices.
533     <c>sys-apps/hotplug</c> will use the required firmware to make that device
534     usable. The firmware should be put in the <path>/lib/firmware</path> directory
535     and is picked up from there. Getting it is simple, the usual emerge will do.
536     </p>
537    
538     <pre caption="Installing hotplug">
539     # <i>emerge hotplug</i>
540     </pre>
541    
542     <p>
543     Now the obvious question would be, what is coldplug and why is it needed?
544     <c>sys-apps/coldplug</c> does what hotplug does, but it does it for
545     <e>hot-pluggable</e> devices that are already connected at boot time. A good
546     example of this would be a USB Network card. Earlier hotplug was the package
547     responsible for handling both but then it was split into hotplug and coldplug,
548     each with their distinct purposes. Emerge it if you have <e>hot-pluggable</e>
549     devices that you need activated on boot up.
550     </p>
551    
552     <pre caption="Installing coldplug">
553     # <i>emerge coldplug</i>
554     <comment>(And you can add it to the boot runlevel)</comment>
555     # <i>rc-update add coldplug boot</i>
556     * coldplug added to runlevel boot
557     * rc-update complete.
558     </pre>
559    
560     <note>
561     The above initscript does what hotplug's initscript used to do (for already
562     attached hot-pluggable devices). hotplug does not have an initscript of its
563     own as of now.
564     </note>
565    
566     </body>
567     </section>
568     </chapter>
569    
570     <chapter>
571     <title>And thanks to...</title>
572     <section>
573     <title>References</title>
574     <body>
575    
576     <p>
577     A good number of documents online helped me during writing this, and there are
578     some that are that are highly technical but truly interesting. I thought they
579     all deserve some credit. So here we go!
580     </p>
581     <p>
582     1) <uri link="http://www.usb.org">The Official USB Website</uri>
583     </p>
584     <p>
585     2) <uri link="http://www.usb.org/faq">The USB FAQ</uri>
586     </p>
587     <p>
588     3) <uri link="http://h18000.www1.hp.com/productinfo/development/openhci.html">Compaq's OHCI Standard</uri>
589     </p>
590     <p>
591     4) <uri link="http://developer.intel.com/technology/usb/uhci11d.htm">Intel's UHCI Standard</uri>
592     </p>
593     <p>
594     5) <uri link="http://www.intel.com/technology/usb/ehcispec.htm">Intel's EHCI Standard</uri>
595     </p>
596    
597     </body>
598     </section>
599     </chapter>
600     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20