/[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.17 - (show annotations) (download) (as text)
Mon May 19 21:04:48 2008 UTC (6 years, 4 months ago) by swift
Branch: MAIN
Changes since 1.16: +5 -4 lines
File MIME type: application/xml
Coding style

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

  ViewVC Help
Powered by ViewVC 1.1.20