/[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.18 - (hide annotations) (download) (as text)
Sun Jun 22 01:13:02 2008 UTC (6 years, 3 months ago) by nightmorph
Branch: MAIN
Changes since 1.17: +19 -96 lines
File MIME type: application/xml
updated USB HID config location. this update covers the handbooks and the USB guide. for the latter, i removed the section on kernel 2.4 configuration, as there are no 2.4 kernels supported by gentoo.

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2 nightmorph 1.18 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/usb-guide.xml,v 1.17 2008/05/19 21:04:48 swift Exp $ -->
3 swift 1.1 <!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 fox2mike 1.4 <mail link="fox2mike@gentoo.org">Shyam Mani</mail>
10 swift 1.1 </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 fox2mike 1.5 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
19 swift 1.1 <license/>
20    
21 nightmorph 1.18 <version>1.14</version>
22     <date>2008-06-21</date>
23 swift 1.1
24     <chapter>
25     <title>Introduction</title>
26     <section>
27     <title>What is USB?</title>
28     <body>
29    
30     <p>
31 neysx 1.3 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 swift 1.1 </p>
36    
37     <p>
38 neysx 1.3 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 swift 1.1 in order for you to be able to use these devices.
46     </p>
47    
48     </body>
49     </section>
50     <section>
51     <title>A Technical Perspective</title>
52     <body>
53    
54     <p>
55 neysx 1.3 Before we go onto the exact configuration options in the kernel, it would
56     be apt to look at USB in a little more detail. If you're in a hurry or want
57 swift 1.17 to skip this section, please go to <uri link="#kernel">Kernel
58     Configuration</uri>.
59 swift 1.1 </p>
60    
61     <p>
62 neysx 1.3 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 swift 1.1 standard USB 1.1 interfaces whereas the EHCI is for USB 2.0.
69     </p>
70    
71     <p>
72 neysx 1.3 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 swift 1.1 system software. The following diagram should make things easier to comprehend.
76     </p>
77    
78     <pre caption="General USB Architecture">
79 neysx 1.3 <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 swift 1.1
82 neysx 1.3 + ---- Hardware ---- + ---- Software ---- +
83 swift 1.1 | | |
84 neysx 1.3 | [USB Dev] -+-> {EHCI} -+---> ( EHCD ) |
85 swift 1.1 | | | | User
86     | `-> {UHCI} -+---> ( UHCD ) |
87     | | |
88     + ---- Hardware ---- + ---- Software ---- +
89 neysx 1.3 </pre>
90 swift 1.1
91     <p>
92 neysx 1.3 A USB device can either use a custom driver or use one already present in
93     the system and this is based on the concept of a device <e>class</e>. This
94     means that if a device belongs to a certain <e>class</e>, then other devices
95     belonging to the same <e>class</e> can make use of the same device driver.
96     Some of these <e>classes</e> are the USB HID (Human Interface Devices) class
97     which covers input devices like keyboards and mice, the USB Mass Storage
98     devices class which covers devices like pen drives, digital cameras, audio
99     players etc and the USB CDC (Communication Devices Class) which essentially
100 swift 1.1 covers USB modems and similar devices.
101     </p>
102    
103     </body>
104     </section>
105 fox2mike 1.5 <section>
106 swift 1.1 <title>What's on your machine?</title>
107     <body>
108    
109     <p>
110     It is very simple to find out whether your machine has USB 2.0 support or not.
111     We make use of the <c>lspci</c> command for this purpose.
112     </p>
113    
114     <note>
115 neysx 1.3 The <c>lspci</c> tool is a part of the <c>sys-apps/pciutils</c> package. If
116     you do not have this installed, please <c>emerge pciutils</c>. Please note
117 swift 1.1 that you have to be root while running the <c>lspci</c> command.
118     </note>
119    
120     <pre caption="Various lspci outputs">
121     <comment>(In system that is USB 1.1 compliant, note the UHCI only)</comment>
122    
123     # <i>lspci -v | grep USB</i>
124     0000:00:04.2 USB Controller: Intel Corp. 82371AB/EB/MB PIIX4 USB (rev 01) (prog-if 00 [UHCI])
125    
126     <comment>(A system that is USB 2.0 compliant, note the EHCI and UHCI)</comment>
127    
128     00:1d.0 USB Controller: Intel Corp. 82801DB USB (Hub #1) (rev 01) (prog-if 00 [UHCI])
129     00:1d.1 USB Controller: Intel Corp. 82801DB USB (Hub #2) (rev 01) (prog-if 00 [UHCI])
130     00:1d.2 USB Controller: Intel Corp. 82801DB USB (Hub #3) (rev 01) (prog-if 00 [UHCI])
131     00:1d.7 USB Controller: Intel Corp. 82801DB USB EHCI Controller (rev 01) (prog-if 20 [EHCI])
132     </pre>
133    
134     <p>
135 neysx 1.3 So using the <c>lspci</c> command, we can find out if the system supports
136     USB 2.0. This is useful as we will be enabling the corresponding options in
137 swift 1.1 the kernel.
138     </p>
139    
140     </body>
141     </section>
142     </chapter>
143    
144     <chapter id="kernel">
145     <title>Kernel Configuration</title>
146     <section>
147     <title>Getting the kernel</title>
148     <body>
149    
150     <p>
151 neysx 1.3 First emerge the kernel sources of your choice. Here we'll use the
152 swift 1.6 <c>gentoo-sources</c>. For more information on the various kernel sources
153 neysx 1.3 available on Portage, please look up the <uri
154     link="/doc/en/gentoo-kernel.xml">Gentoo Linux Kernel Guide</uri>.
155 swift 1.1 </p>
156    
157     <pre caption="Getting the kernel sources">
158 neysx 1.3 # <i>emerge gentoo-sources</i>
159 swift 1.1 </pre>
160    
161     <p>
162     Now, lets get on with the task of configuring the kernel.
163     </p>
164    
165     <pre caption="Heading over to the source">
166 neysx 1.3 # <i>cd /usr/src/linux</i>
167     # <i>make menuconfig</i>
168 swift 1.1 </pre>
169    
170     <note>
171 neysx 1.3 The above example assumes that <path>/usr/src/linux</path> symlink points to
172 swift 1.1 the kernel sources you want to use. Please ensure the same before proceeding.
173     </note>
174    
175     </body>
176     </section>
177 nightmorph 1.18 <section>
178     <title>Config options for the kernel</title>
179 swift 1.1 <body>
180    
181     <p>
182 nightmorph 1.18 Now we will look at some of the options we will have to enable in the kernel to
183     ensure proper USB support for our devices.
184 swift 1.1 </p>
185    
186     <note>
187 neysx 1.3 Examples in this document will show configuration options for basic USB
188     support as well as those needed commonly, for example a USB mass storage
189     device (most cameras and USB pen drives). If you have a specific USB device
190     that needs to be configured, please look up your device's manual or search
191     online to see if that device has support built-in into the kernel or custom
192     drivers that you can use. Please note that for the sake of ease, all examples
193     have the options compiled into the kernel. If you would like to have a modular
194     kernel, ensure that you note down the various modules and adjust your config
195 swift 1.1 files accordingly.
196     </note>
197    
198 nightmorph 1.18 <pre caption="make menuconfig options">
199 swift 1.1 Device Drivers ---&gt;
200     SCSI device support ---&gt;
201    
202 neysx 1.3 <comment>(Although SCSI will be enabled automatically when selecting USB Mass Storage,
203     we need to enable disk support.)</comment>
204 swift 1.1 --- SCSI support type (disk, tape, CD-ROM)
205     &lt;*&gt; SCSI disk support
206    
207     <comment>(Then move back a level and go into USB support)</comment>
208     USB support ---&gt;
209    
210 neysx 1.3 <comment>(This is the root hub and is required for USB support.
211     If you'd like to compile this as a module, it will be called usbcore.)</comment>
212     &lt;*&gt; Support for Host-side USB
213 swift 1.1
214 neysx 1.3 <comment>(Enable this option to see your USB devices in /proc/bus/usb.
215     This is recommended.)</comment>
216 swift 1.1 [*] USB device filesystem
217    
218     <comment>(Select at least one of the HCDs. If you are unsure, picking all is fine.)</comment>
219 neysx 1.3 --- USB Host Controller Drivers
220 swift 1.1 &lt;*&gt; EHCI HCD (USB 2.0) support
221     &lt; &gt; OHCI HCD support
222     &lt;*&gt; UHCI HCD (most Intel and VIA) support
223    
224     <comment>(Moving a little further down, we come to CDC and mass storage.)</comment>
225     &lt; &gt; USB Modem (CDC ACM) support
226     &lt;*&gt; USB Printer support
227     &lt;*&gt; USB Mass Storage support
228    
229     <comment>(If you have a USB Network Card like the RTL8150, you'll need this)</comment>
230     USB Network Adapters --->
231     &lt;*&gt; USB RTL8150 based ethernet device support (EXPERIMENTAL)
232    
233     <comment>(If you have a serial to USB converter like the Prolific 2303, you'll need this)</comment>
234     USB Serial Converter support --->
235     &lt;*&gt; USB Serial Converter support
236 neysx 1.3 &lt;*&gt; USB Prolific 2303 Single Port Serial Driver (NEW)
237 swift 1.1 </pre>
238    
239     <p>
240 nightmorph 1.18 If you have a USB keyboard, mouse, joystick, or any other input device, you need
241     to enable HID support. Go back one level to "Device drivers" and enable HID
242     support as shown:
243 swift 1.1 </p>
244 neysx 1.3
245 nightmorph 1.18 <pre caption="Enabling HID support">
246     Device Drivers ---&gt;
247     [*] HID Devices ---&gt;
248     &lt;*&gt; USB Human Interface Device (full HID) support
249 swift 1.1 </pre>
250    
251     <p>
252 nightmorph 1.18 Now that your options are set, you can (re)compile the kernel and USB support
253     should be functional once you reboot into the new kernel. You can now proceed
254     to <uri link="#postkern">Seeing USB at work</uri> and see if everything is
255     working as it should.
256 swift 1.1 </p>
257 neysx 1.3
258 swift 1.1 </body>
259     </section>
260     </chapter>
261    
262     <chapter id="postkern">
263     <title>Seeing USB at work</title>
264     <section>
265     <title>dmesg is your friend!</title>
266     <body>
267    
268     <p>
269 neysx 1.3 The time has finally come to play with those USB devices :) So let's get
270     started. In this chapter, we'll see how the system responds to various USB
271     devices. We'll start by plugging in a USB 512 MB Memory Stick/Pen Drive. You
272     could use some other similar mass storage device. We will primarily use
273     <c>dmesg</c> to see what is happening and how the system responds to the
274 swift 1.1 device.
275     </p>
276    
277     <note>
278 neysx 1.3 <c>dmesg</c> will generally give a lot of output up front before coming to the
279 swift 1.1 info we need, as it reads the kernel ring buffer that has all the boot up
280 neysx 1.3 messages as well. The output in the following examples have only the relevant
281     portion(s) and extra spaces in between to enable better readability. If needed
282     please use a <c>dmesg | more</c> or <c>dmesg | less</c> to see the output
283 yoswink 1.2 better in your system.
284 swift 1.1 </note>
285    
286     <pre caption="dmesg output for Memory Stick">
287     <comment>(Plug in Memory Stick into available USB port and then..)</comment>
288 yoswink 1.2 # <i>dmesg | less</i>
289 swift 1.1
290 neysx 1.3 <comment>(The device is picked up as a USB 1.1 and allocated an address.
291     Also says what HCD it is using.)</comment>
292 swift 1.1 usb 1-1: new full speed USB device using uhci_hcd and address 2
293    
294     <comment>(SCSI emulation automatically kicks in)</comment>
295     scsi0 : SCSI emulation for USB Mass Storage devices
296     usb-storage: device found at 2
297    
298     <comment>(Now the device information including model number is retrieved)</comment>
299     usb-storage: waiting for device to settle before scanning
300     Vendor: JetFlash Model: TS512MJF2A Rev: 1.00
301     Type: Direct-Access ANSI SCSI revision: 02
302     SCSI device sda: 1003600 512-byte hdwr sectors (514 MB)
303    
304     <comment>(The write-protect sense is EXPERIMENTAL code in the later kernels)</comment>
305     sda: Write Protect is off
306     sda: Mode Sense: 0b 00 00 08
307     sda: assuming drive cache: write through
308     SCSI device sda: 1003600 512-byte hdwr sectors (514 MB)
309     /dev/scsi/host0/bus0/target0/lun0: p1
310     Attached scsi removable disk sda at scsi0, channel 0, id 0, lun 0
311     Attached scsi generic sg0 at scsi0, channel 0, id 0, lun 0, type 0
312     usb-storage: device scan complete
313     <comment>(At this point, the device is generally accessible by mounting /dev/sda1)</comment>
314    
315     <comment>(When the device is disconnected, the system acknowledges the same)</comment>
316     usb 1-1: USB disconnect, address 2
317     </pre>
318    
319     <p>
320 neysx 1.3 Once the device is connected and mounted, you can access it like a normal hard
321 swift 1.6 disk. Usual operations like <c>cp</c>, <c>mv</c>, <c>rm</c>, etc work fine. You
322 swift 1.1 could also create a filesystem on the USB stick/format it.
323     </p>
324    
325     <pre caption="Accessing the Memory Stick">
326     # <i>mount /dev/sda1 /mnt/usb</i>
327     # <i>df -h</i>
328     Filesystem Size Used Avail Use% Mounted on
329     /dev/hda8 9.4G 7.5G 1.9G 80% /
330     /dev/hda9 11G 8.1G 2.4G 78% /usr
331     none 189M 0 189M 0% /dev/shm
332     /dev/sda1 490M 34M 457M 7% /mnt/usb
333     </pre>
334    
335     <note>
336 neysx 1.3 Digital cameras can be accessed the same way as memory sticks. I have a Nikon
337 fox2mike 1.7 Coolpix 5200 and this is the way I access it. Cameras these days usually have
338     two modes to transfer pictures; USB mass storage and PTP (Picture Transfer
339     Protocol). The camera is set to USB mass storage mode and hence the procedure is
340     exactly the same as that of accessing a memory stick because of which I have not
341     explained in detail about it. Please note that this may NOT work in all cases
342     and with all digital cameras that have USB support.
343 swift 1.1 </note>
344    
345     <p>
346 neysx 1.3 How would a USB mouse show up in case you had one? It will show up as an HID
347 swift 1.1 device.
348     </p>
349    
350     <pre caption="USB Optical Mouse">
351     # <i>dmesg | grep USB</i>
352     drivers/usb/input/hid-core.c: v2.0:USB HID core driver
353     usb 1-1: new low speed USB device using address 2
354     input: USB HID v1.10 Mouse [Logitech USB-PS/2 Optical Mouse] on usb-0000:00:07.2-1
355     </pre>
356    
357     <p>
358 neysx 1.3 Another nifty command you can use to see the status of your USB ports is
359     <c>lsusb</c>. This is part of <c>sys-apps/usbutils</c> and will be covered in
360 swift 1.1 the next chapter.
361     </p>
362    
363     </body>
364     </section>
365     </chapter>
366    
367     <chapter>
368     <title>Userspace USB</title>
369     <section>
370     <title>Nifty tools</title>
371     <body>
372    
373     <p>
374 neysx 1.3 So far we've seen how much support exists on the kernel/system side for USB on
375     Linux. Now we'll take a peek into what kind of support is provided by Gentoo
376 swift 1.1 for USB in the userspace.
377     </p>
378    
379     <p>
380 neysx 1.3 One of the most useful tools around is <c>lsusb</c>. This lists all the usb
381 swift 1.1 devices connected to the system. Installing it is a breeze.
382     </p>
383    
384     <pre caption="Installing usbutils">
385     # <i>emerge usbutils</i>
386     </pre>
387    
388     <p>
389 neysx 1.3 Once installed, you can just run <c>lsusb</c> to get simple info on the USB
390 swift 1.1 devices attached to the machine.
391     </p>
392    
393     <note>
394     You have to be root in most cases to run <c>lsusb</c>.
395     </note>
396    
397     <warn>
398 neysx 1.3 <c>lsusb</c> reads the information for the USB devices from
399     <path>/proc/bus/usb</path>. If you have not enabled that in your kernel,
400     chances are that <c>lsusb</c> may not work at all. Please ensure you have
401 swift 1.1 <path>/proc</path> filesystem support enabled in your kernel and that
402     <c>usbfs</c> is mounted at <path>/proc/bus/usb</path> (which should happen
403     automatically).
404     </warn>
405    
406     <pre caption="lsusb at work">
407     # <i>lsusb</i>
408     <comment>(This is the 512 MB Memory Stick from Transcend)</comment>
409     Bus 001 Device 003: ID 0c76:0005 JMTek, LLC. USBdisk
410     <comment>(This is the Optical Mouse)</comment>
411     Bus 001 Device 002: ID 046d:c00e Logitech, Inc. Optical Mouse
412     <comment>(This is the root hub)</comment>
413     Bus 001 Device 001: ID 0000:0000
414     </pre>
415    
416     <p>
417 neysx 1.3 If you are one of those types who love to see lots of information, you have
418     the option of running <c>lsusb -v</c>. Try that and see the amount of info it
419     gives out. Another good option is that <c>lsusb</c> dumps the current physical
420     USB hierarchy as a tree and thus makes it easier to understand the exact
421 swift 1.1 device map. The command is <c>lsusb -t</c>. For example,
422     </p>
423    
424     <pre caption="lsusb showing USB hierarchy">
425     # <i>lsusb -t</i>
426     Bus# 1
427     `-Dev# 1 Vendor 0x0000 Product 0x0000
428     |-Dev# 2 Vendor 0x046d Product 0xc00e
429     `-Dev# 3 Vendor 0x0c76 Product 0x0005
430     </pre>
431    
432     <p>
433 neysx 1.3 You can easily correlate the outputs of <c>lsusb</c> and <c>lsusb -t</c>,
434 swift 1.1 which helps debugging as well as understanding how USB works.
435     </p>
436    
437     </body>
438     </section>
439     </chapter>
440    
441     <chapter>
442     <title>And thanks to...</title>
443     <section>
444     <title>References</title>
445     <body>
446    
447     <p>
448 swift 1.6 A good number of online documents helped me during the development of this
449 swift 1.17 document and there are some that are highly technical but truly interesting.
450 swift 1.6 I thought they all deserve some credit, so here we go!
451 swift 1.1 </p>
452 neysx 1.3
453     <ul>
454     <li><uri link="http://www.usb.org">The Official USB Website</uri></li>
455 swift 1.8 <li><uri link="http://www.usb.org/about/faq">The USB FAQ</uri></li>
456 neysx 1.3 <li>
457     <uri
458     link="http://h18000.www1.hp.com/productinfo/development/openhci.html">Compaq's
459     OHCI Standard</uri>
460     </li>
461     <li>
462     <uri link="http://developer.intel.com/technology/usb/uhci11d.htm">Intel's
463     UHCI Standard</uri>
464     </li>
465     <li>
466     <uri link="http://www.intel.com/technology/usb/ehcispec.htm">Intel's EHCI
467     Standard</uri>
468     </li>
469 fox2mike 1.10 </ul>
470    
471     </body>
472     </section>
473     <section>
474     <title>Other Interesting Links</title>
475     <body>
476    
477     <ul>
478 swift 1.17 <li><uri link="/doc/en/liveusb.xml">Gentoo Linux LiveUSB HOWTO</uri></li>
479 neysx 1.3 </ul>
480 swift 1.1
481     </body>
482     </section>
483     </chapter>
484     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20