/[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.2 - (show annotations) (download) (as text)
Thu Apr 14 10:34:20 2005 UTC (9 years, 4 months ago) by yoswink
Branch: MAIN
Changes since 1.1: +14 -9 lines
File MIME type: application/xml
Fixed gentoo-dev-sources issue and added less to dmesg, due to #89044

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.1</version>
22 <date>2005-04-14</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 <note>
153 Since the 2005.0 release, Gentoo Linux uses 2.6 as the default kernel. Unless
154 you are specifically using the 2.4 profile, <c>gentoo-sources</c> will be a
155 2.6 kernel on <e>most</e> architectures. Please check your kernel version and
156 then proceed with the configuration accordingly.
157 </note>
158
159 <p>
160 First emerge the kernel sources of your choice. Here we'll use the
161 <c>gentoo-sources</c> For more information on the various kernel sources available on Portage,
162 please look up the <uri 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
186 <section id="2.6.xconfig">
187 <title>Config options for the 2.6.x kernel</title>
188 <body>
189
190 <p>
191 Now we will look at some of the options we will have to enable in the 2.6
192 kernel to ensure proper USB support for our devices. If you are using a 2.4
193 kernel, please proceed with <uri link="#2.4.xconfig">Config options for the
194 2.4.x kernel</uri>.
195 </p>
196
197 <note>
198 Examples in this document will show configuration options for basic USB
199 support as well as those needed commonly, for example a USB mass storage
200 device (most cameras and USB pen drives). If you have a specific USB device
201 that needs to be configured, please look up your device's manual or search
202 online to see if that device has support built-in into the kernel or custom
203 drivers that you can use. Please note that for the sake of ease, all examples
204 have the options compiled into the kernel. If you would like to have a modular
205 kernel, ensure that you note down the various modules and adjust your config
206 files accordingly.
207 </note>
208
209 <pre caption="make menuconfig options for 2.6 kernels">
210 Device Drivers ---&gt;
211 SCSI device support ---&gt;
212
213 <comment>(Although SCSI will be enabled automatically when selecting USB Mass Storage, 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. If you'd like to compile this as a module,</comment>
221 <comment> 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. This is recommended.)</comment>
225 [*] USB device filesystem
226
227 <comment>(Select at least one of the HCDs. If you are unsure, picking all is fine.)</comment>
228 --- USB Host Controller Drivers
229 &lt;*&gt; EHCI HCD (USB 2.0) support
230 &lt; &gt; OHCI HCD support
231 &lt;*&gt; UHCI HCD (most Intel and VIA) support
232
233 <comment>(Moving a little further down, we come to CDC and mass storage.)</comment>
234 &lt; &gt; USB Modem (CDC ACM) support
235 &lt;*&gt; USB Printer support
236 &lt;*&gt; USB Mass Storage support
237 [*] USB Mass Storage Write-Protected Media Detection (EXPERIMENTAL)
238
239 <comment>(And then the HID bits. You have to select HID input support if you have a USB</comment>
240 <comment> keyboard, mouse, joystick or any other USB input device)</comment>
241 --- USB Input Devices
242 &lt;*&gt; USB Human Interface Device (full HID) support
243 [*] HID input layer support
244
245 <comment>(If you have a USB Network Card like the RTL8150, you'll need this)</comment>
246 USB Network Adapters --->
247 &lt;*&gt; USB RTL8150 based ethernet device support (EXPERIMENTAL)
248
249 <comment>(If you have a serial to USB converter like the Prolific 2303, you'll need this)</comment>
250 USB Serial Converter support --->
251 &lt;*&gt; USB Serial Converter support
252 &lt;*&gt; USB Prolific 2303 Single Port Serial Driver (NEW)
253 </pre>
254
255 <p>
256 Now that your options are set, you can (re)compile the kernel and USB support
257 should be functional once you reboot into the new kernel. You can now proceed
258 to <uri link="#postkern">Seeing USB at work</uri> and see if everything is
259 working as it should.
260 </p>
261 </body>
262 </section>
263
264 <section id="2.4.xconfig">
265 <title>Config options for the 2.4.x kernel</title>
266 <body>
267
268 <p>
269 We will look at the options the we will have to enable in the 2.4 kernel to
270 ensure proper USB support for our devices. If you are using a 2.6 kernel,
271 please look at <uri link="#2.6.xconfig">Config options for the 2.6.x
272 kernel</uri>.
273 </p>
274
275 <note>
276 Examples in this document will show configuration options for basic USB
277 support as well as those needed commonly, for example a USB mass storage
278 device (most cameras and USB pen drives). If you have a specific USB device
279 that needs to be configured, please look up your device's manual or search
280 online to see if that device has support built-in into the kernel or custom
281 drivers that you can use. Please note that for the sake of ease, all examples
282 have the options compiled into the kernel. If you would like to have a modular
283 kernel, ensure that you note down the various modules and adjust your config
284 files accordingly.
285 </note>
286
287 <pre caption="make menuconfig options for 2.4 kernels">
288 <comment>(This immediate config is only for those who have USB input devices. Input</comment>
289 <comment> core support is needed by USB HID later.)</comment>
290 Input core support ---&gt;
291 &lt;*&gt; Input core support
292 &lt; &gt; Keyboard support
293 &lt; &gt; Mouse support
294 &lt; &gt; Event interface support
295
296 USB support ---&gt;
297
298 <comment>(This is the root hub and is required for USB support. If you'd like to compile this as a module,</comment>
299 <comment> it will be called usbcore.o)</comment>
300 &lt;*&gt; Support for USB
301
302 <comment>(Enable this option to see your USB devices in /proc/bus/usb. This is recommended.)</comment>
303 [*] Preliminary USB device filesystem
304
305 <comment>(Select at least one of the HCDs. If you are unsure, picking all is fine.)</comment>
306 --- USB Host Controller Drivers
307 &lt;*&gt; UHCI Alternate Driver (JE) support
308 &lt; &gt; OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support
309
310 <comment>(This is the device section. Select only what you need.)</comment>
311 --- USB Device Class drivers
312 &lt; &gt; USB Audio support
313 &lt;*&gt; USB Mass Storage support
314 &lt; &gt; USB Modem (CDC ACM) support
315 &lt;*&gt; USB Printer support
316
317 <comment>(Followed by the HID section. This is needed if you have an USB based input device.)</comment>
318 --- USB Human Interface Devices (HID)
319 &lt;*&gt; USB Human Interface Device (full HID) support
320 [*] HID input layer support
321
322 <comment>(If you have a serial to USB converter like the Prolific 2303, you'll need this)</comment>
323 USB Serial Converter support --->
324 &lt;*&gt; USB Serial Converter support
325 &lt;*&gt; USB Prolific 2303 Single Port Serial Driver (NEW)
326 </pre>
327
328 <p>
329 Now that the options are set, you can (re)compile the kernel and USB support
330 should be functional once you reboot into the new kernel.
331 </p>
332 </body>
333 </section>
334 </chapter>
335
336 <chapter id="postkern">
337 <title>Seeing USB at work</title>
338 <section>
339 <title>dmesg is your friend!</title>
340 <body>
341
342 <p>
343 The time has finally come to play with those USB devices :) So let's get
344 started. In this chapter, we'll see how the system responds to various USB
345 devices. We'll start by plugging in a USB 512 MB Memory Stick/Pen Drive. You
346 could use some other similar mass storage device. We will primarily use
347 <c>dmesg</c> to see what is happening and how the system responds to the
348 device.
349 </p>
350
351 <note>
352 <c>dmesg</c> will generally give a lot of output up front before coming to the
353 info we need, as it reads the kernel ring buffer that has all the boot up
354 messages as well. The output in the following examples have only the relevant
355 portion(s) and extra spaces in between to enable better readability. If needed
356 please use a <c>dmesg | more</c> or <c>dmesg | less</c> to see the output
357 better in your system.
358 </note>
359
360 <pre caption="dmesg output for Memory Stick">
361 <comment>(Plug in Memory Stick into available USB port and then..)</comment>
362 # <i>dmesg | less</i>
363
364 <comment>(The device is picked up as a USB 1.1 and allocated an address. Also says what HCD it is using.)</comment>
365 usb 1-1: new full speed USB device using uhci_hcd and address 2
366
367 <comment>(SCSI emulation automatically kicks in)</comment>
368 scsi0 : SCSI emulation for USB Mass Storage devices
369 usb-storage: device found at 2
370
371 <comment>(Now the device information including model number is retrieved)</comment>
372 usb-storage: waiting for device to settle before scanning
373 Vendor: JetFlash Model: TS512MJF2A Rev: 1.00
374 Type: Direct-Access ANSI SCSI revision: 02
375 SCSI device sda: 1003600 512-byte hdwr sectors (514 MB)
376
377 <comment>(The write-protect sense is EXPERIMENTAL code in the later kernels)</comment>
378 sda: Write Protect is off
379 sda: Mode Sense: 0b 00 00 08
380 sda: assuming drive cache: write through
381 SCSI device sda: 1003600 512-byte hdwr sectors (514 MB)
382 /dev/scsi/host0/bus0/target0/lun0: p1
383 Attached scsi removable disk sda at scsi0, channel 0, id 0, lun 0
384 Attached scsi generic sg0 at scsi0, channel 0, id 0, lun 0, type 0
385 usb-storage: device scan complete
386 <comment>(At this point, the device is generally accessible by mounting /dev/sda1)</comment>
387
388 <comment>(When the device is disconnected, the system acknowledges the same)</comment>
389 usb 1-1: USB disconnect, address 2
390 </pre>
391
392 <p>
393 Once the device is connected and mounted, you can access it like a normal hard
394 disk. Usual operations like <c>cp</c>, <c>mv</c>, <c>rm</c> etc work fine. You
395 could also create a filesystem on the USB stick/format it.
396 </p>
397
398 <pre caption="Accessing the Memory Stick">
399 # <i>mount /dev/sda1 /mnt/usb</i>
400 # <i>df -h</i>
401 Filesystem Size Used Avail Use% Mounted on
402 /dev/hda8 9.4G 7.5G 1.9G 80% /
403 /dev/hda9 11G 8.1G 2.4G 78% /usr
404 none 189M 0 189M 0% /dev/shm
405 /dev/sda1 490M 34M 457M 7% /mnt/usb
406 </pre>
407
408 <note>
409 Digital cameras can be accessed the same way as memory sticks. I have a Nikon
410 Coolpix 5200 and this is the way I access it. The camera is set to behave like
411 a USB mass storage device (as against PTP mode, which most cameras have these
412 days) and the procedure is exactly the same, because of which I have not
413 explained in detail about the same. Please note that this may NOT work in all
414 cases and with all digital cameras that have USB support.
415 </note>
416
417 <p>
418 How would a USB mouse show up in case you had one? It will show up as an HID
419 device.
420 </p>
421
422 <pre caption="USB Optical Mouse">
423 # <i>dmesg | grep USB</i>
424 drivers/usb/input/hid-core.c: v2.0:USB HID core driver
425 usb 1-1: new low speed USB device using address 2
426 input: USB HID v1.10 Mouse [Logitech USB-PS/2 Optical Mouse] on usb-0000:00:07.2-1
427 </pre>
428
429 <p>
430 Another nifty command you can use to see the status of your USB ports is
431 <c>lsusb</c>. This is part of <c>sys-apps/usbutils</c> and will be covered in
432 the next chapter.
433 </p>
434
435 </body>
436 </section>
437 </chapter>
438
439 <chapter>
440 <title>Userspace USB</title>
441 <section>
442 <title>Nifty tools</title>
443 <body>
444
445 <p>
446 So far we've seen how much support exists on the kernel/system side for USB on
447 Linux. Now we'll take a peek into what kind of support is provided by Gentoo
448 for USB in the userspace.
449 </p>
450
451 <p>
452 One of the most useful tools around is <c>lsusb</c>. This lists all the usb
453 devices connected to the system. Installing it is a breeze.
454 </p>
455
456 <pre caption="Installing usbutils">
457 # <i>emerge usbutils</i>
458 </pre>
459
460 <p>
461 Once installed, you can just run <c>lsusb</c> to get simple info on the USB
462 devices attached to the machine.
463 </p>
464
465 <note>
466 You have to be root in most cases to run <c>lsusb</c>.
467 </note>
468
469 <warn>
470 <c>lsusb</c> reads the information for the USB devices from
471 <path>/proc/bus/usb</path>. If you have not enabled that in your kernel,
472 chances are that <c>lsusb</c> may not work at all. Please ensure you have
473 <path>/proc</path> filesystem support enabled in your kernel and that
474 <c>usbfs</c> is mounted at <path>/proc/bus/usb</path> (which should happen
475 automatically).
476 </warn>
477
478 <pre caption="lsusb at work">
479 # <i>lsusb</i>
480 <comment>(This is the 512 MB Memory Stick from Transcend)</comment>
481 Bus 001 Device 003: ID 0c76:0005 JMTek, LLC. USBdisk
482 <comment>(This is the Optical Mouse)</comment>
483 Bus 001 Device 002: ID 046d:c00e Logitech, Inc. Optical Mouse
484 <comment>(This is the root hub)</comment>
485 Bus 001 Device 001: ID 0000:0000
486 </pre>
487
488 <p>
489 If you are one of those types who love to see lots of information, you have
490 the option of running <c>lsusb -v</c>. Try that and see the amount of info it
491 gives out. Another good option is that <c>lsusb</c> dumps the current physical
492 USB hierarchy as a tree and thus makes it easier to understand the exact
493 device map. The command is <c>lsusb -t</c>. For example,
494 </p>
495
496 <pre caption="lsusb showing USB hierarchy">
497 # <i>lsusb -t</i>
498 Bus# 1
499 `-Dev# 1 Vendor 0x0000 Product 0x0000
500 |-Dev# 2 Vendor 0x046d Product 0xc00e
501 `-Dev# 3 Vendor 0x0c76 Product 0x0005
502 </pre>
503
504 <p>
505 You can easily correlate the outputs of <c>lsusb</c> and <c>lsusb -t</c>,
506 which helps debugging as well as understanding how USB works.
507 </p>
508
509 </body>
510 </section>
511
512 <section>
513 <title>Hot or Cold plug??</title>
514 <body>
515
516 <p>
517 Gentoo uses two packages, <c>sys-apps/hotplug</c> and <c>sys-apps/coldplug</c>
518 to do some magic with <e>hot-pluggable</e> devices. Just like any other magic
519 trick, there is a simple logic behind this one too. We shall now see what that
520 is, and in the process hopefully we will be able to understand these twins
521 better.
522 </p>
523
524 <p>
525 Firmware can be defined as the software on a piece of hardware that is loaded
526 and executed but can't be modified easily. Many devices have firmware in them
527 to ensure that they work properly and often firmware may contain code that is
528 critical to ensure that the hardware performs as expected. Firmware is present
529 in a wide variety of computer devices ranging from ROM chips to state of the
530 art USB and PCMCIA cards. When a device is plugged in, the firmware (which may
531 in some cases be the driver as well) is read and loaded onto memory after
532 which the device can be used by the system.
533 </p>
534
535 <p>
536 To cut the long story short, Gentoo uses <c>sys-apps/hotplug</c> to handle
537 the firmware side of things in <e>hot-pluggable</e> devices.
538 <c>sys-apps/hotplug</c> will use the required firmware to make that device
539 usable. The firmware should be put in the <path>/lib/firmware</path> directory
540 and is picked up from there. Getting it is simple, the usual emerge will do.
541 </p>
542
543 <pre caption="Installing hotplug">
544 # <i>emerge hotplug</i>
545 </pre>
546
547 <p>
548 Now the obvious question would be, what is coldplug and why is it needed?
549 <c>sys-apps/coldplug</c> does what hotplug does, but it does it for
550 <e>hot-pluggable</e> devices that are already connected at boot time. A good
551 example of this would be a USB Network card. Earlier hotplug was the package
552 responsible for handling both but then it was split into hotplug and coldplug,
553 each with their distinct purposes. Emerge it if you have <e>hot-pluggable</e>
554 devices that you need activated on boot up.
555 </p>
556
557 <pre caption="Installing coldplug">
558 # <i>emerge coldplug</i>
559 <comment>(And you can add it to the boot runlevel)</comment>
560 # <i>rc-update add coldplug boot</i>
561 * coldplug added to runlevel boot
562 * rc-update complete.
563 </pre>
564
565 <note>
566 The above initscript does what hotplug's initscript used to do (for already
567 attached hot-pluggable devices). hotplug does not have an initscript of its
568 own as of now.
569 </note>
570
571 </body>
572 </section>
573 </chapter>
574
575 <chapter>
576 <title>And thanks to...</title>
577 <section>
578 <title>References</title>
579 <body>
580
581 <p>
582 A good number of documents online helped me during writing this, and there are
583 some that are that are highly technical but truly interesting. I thought they
584 all deserve some credit. So here we go!
585 </p>
586 <p>
587 1) <uri link="http://www.usb.org">The Official USB Website</uri>
588 </p>
589 <p>
590 2) <uri link="http://www.usb.org/faq">The USB FAQ</uri>
591 </p>
592 <p>
593 3) <uri link="http://h18000.www1.hp.com/productinfo/development/openhci.html">Compaq's OHCI Standard</uri>
594 </p>
595 <p>
596 4) <uri link="http://developer.intel.com/technology/usb/uhci11d.htm">Intel's UHCI Standard</uri>
597 </p>
598 <p>
599 5) <uri link="http://www.intel.com/technology/usb/ehcispec.htm">Intel's EHCI Standard</uri>
600 </p>
601
602 </body>
603 </section>
604 </chapter>
605 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20