doc/en/usb-guide.xml

<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/usb-guide.xml,v 1.20 2011/09/04 17:53:40 swift Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide>
<title>Gentoo Linux USB Guide</title>

<author title="Author">
  <mail link="fox2mike@gentoo.org">Shyam Mani</mail>
</author>

<abstract>
This document helps a user setup USB on a Gentoo system and configure various
USB devices as well.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>2</version>
<date>2011-12-26</date>

<chapter>
<title>Introduction</title>
<section>
<title>What is USB?</title>
<body>

<p>
USB stands for Universal Serial Bus and is basically an external interface
standard that enables communication between the computer and various other
peripherals. Some of the most commonly used USB devices today are keyboards,
mice, pen drives, digital cameras, external CD &amp; DVD writers, printers etc.
</p>

<p>
There are currently two versions of USB in use, i.e. USB 1.1 and USB 2.0.
Since USB has always been backward compatible with its previous versions,
USB 2.0 is backwards compatible with USB 1.1. The latest USB devices are
typically USB 2.0 compatible. USB 2.0 supports a maximum data transmission
speed of 480 Mbps or 60 MBps and this is the major difference between the two
standards. Another advantage with USB is that the devices are all
<e>hot-pluggable</e>, which means that you do not have to restart your system
in order for you to be able to use these devices.
</p>

</body>
</section>
<section>
<title>A Technical Perspective</title>
<body>

<p>
Before we go onto the exact configuration options in the kernel, it would
be apt to look at USB in a little more detail. If you're in a hurry or want
to skip this section, please go to <uri link="#kernel">Kernel
Configuration</uri>.
</p>

<p>
A USB system has a host controller, hubs, a <e>root hub</e> amongst others
and can support up to 127 USB devices including the hubs. The host controller
is nothing but the hardware interface between the USB device and the
operating system. There are a couple of HCI (Host Controller Interface)
in use today and they are the OHCI (Open HCI) by Compaq, UHCI (Universal HCI)
and EHCI (Enhanced HCI), both from Intel. The OHCI/UHCI are the two industry
standard USB 1.1 interfaces whereas the EHCI is for USB 2.0.
</p>

<p>
The hardware vendor provides an interface for the programmer that allows
the system to interact with the hardware and this is called the HCD or Host
Controller Device. It is through this HCD that the device interacts with the
system software. The following diagram should make things easier to comprehend.
</p>

<pre caption="General USB Architecture">
<comment>(Software consists of other components as well like the device driver, but
for the sake of simplicity, they are not shown)</comment>

    + ----  Hardware  ----   + ----  Software  ---- +
    |                        |                      |
    | [USB Dev] -+-> {EHCI} -+--->  ( EHCD )        |
    |            |           |                      |  User
    |            `-> {UHCI} -+--->  ( UHCD )        |
    |                        |                      |
    + ----  Hardware  ----   + ----  Software  ---- +
</pre>

<p>
A USB device can either use a custom driver or use one already present in
the system and this is based on the concept of a device <e>class</e>. This
means that if a device belongs to a certain <e>class</e>, then other devices
belonging to the same <e>class</e> can make use of the same device driver.
Some of these <e>classes</e> are the USB HID (Human Interface Devices) class
which covers input devices like keyboards and mice, the USB Mass Storage
devices class which covers devices like pen drives, digital cameras, audio
players etc and the USB CDC (Communication Devices Class) which essentially
covers USB modems and similar devices.
</p>

</body>
</section>
<section>
<title>What's on your machine?</title>
<body>

<p>
It is very simple to find out whether your machine has USB 2.0 support or not.
We make use of the <c>lspci</c> command for this purpose.
</p>

<note>
The <c>lspci</c> tool is a part of the <c>sys-apps/pciutils</c> package. If
you do not have this installed, please <c>emerge pciutils</c>. Please note
that you have to be root while running the <c>lspci</c> command.
</note>

<pre caption="Various lspci outputs">
<comment>(In system that is USB 1.1 compliant, note the UHCI only)</comment>

# <i>lspci -v | grep USB</i>
0000:00:04.2 USB Controller: Intel Corp. 82371AB/EB/MB PIIX4 USB (rev 01) (prog-if 00 [UHCI])

<comment>(A system that is USB 2.0 compliant, note the EHCI and UHCI)</comment>

00:1d.0 USB Controller: Intel Corp. 82801DB USB (Hub #1) (rev 01) (prog-if 00 [UHCI])
00:1d.1 USB Controller: Intel Corp. 82801DB USB (Hub #2) (rev 01) (prog-if 00 [UHCI])
00:1d.2 USB Controller: Intel Corp. 82801DB USB (Hub #3) (rev 01) (prog-if 00 [UHCI])
00:1d.7 USB Controller: Intel Corp. 82801DB USB EHCI Controller (rev 01) (prog-if 20 [EHCI])
</pre>

<p>
So using the <c>lspci</c> command, we can find out if the system supports
USB 2.0. This is useful as we will be enabling the corresponding options in
the kernel.
</p>

</body>
</section>
</chapter>

<chapter id="kernel">
<title>Kernel Configuration</title>
<section>
<title>Getting the kernel</title>
<body>

<p>
First emerge the kernel sources of your choice. Here we'll use the
<c>gentoo-sources</c>. For more information on the various kernel sources
available on Portage, please look up the <uri
link="/doc/en/gentoo-kernel.xml">Gentoo Linux Kernel Guide</uri>.
</p>

<pre caption="Getting the kernel sources">
# <i>emerge gentoo-sources</i>
</pre>

<p>
Now, lets get on with the task of configuring the kernel.
</p>

<pre caption="Heading over to the source">
# <i>cd /usr/src/linux</i>
# <i>make menuconfig</i>
</pre>

<note>
The above example assumes that <path>/usr/src/linux</path> symlink points to
the kernel sources you want to use. Please ensure the same before proceeding.
</note>

</body>
</section>
<section>
<title>Config options for the kernel</title>
<body>

<p>
Now we will look at some of the options we will have to enable in the kernel to
ensure proper USB support for our devices.
</p>

<note>
Examples in this document will show configuration options for basic USB
support as well as those needed commonly, for example a USB mass storage
device (most cameras and USB pen drives). If you have a specific USB device
that needs to be configured, please look up your device's manual or search
online to see if that device has support built-in into the kernel or custom
drivers that you can use. Please note that for the sake of ease, all examples
have the options compiled into the kernel. If you would like to have a modular
kernel, ensure that you note down the various modules and adjust your config
files accordingly.
</note>

<pre caption="make menuconfig options">
Device Drivers  ---&gt;
  SCSI device support  ---&gt;

<comment>(Although SCSI will be enabled automatically when selecting USB Mass Storage,
we need to enable disk support.)</comment>
---   SCSI support type (disk, tape, CD-ROM)
&lt;*&gt;   SCSI disk support

<comment>(Then move back a level and go into USB support)</comment>
USB support  ---&gt;

<comment>(This is the root hub and is required for USB support.
If you'd like to compile this as a module, it will be called usbcore.)</comment>
&lt;*&gt; Support for Host-side USB

<comment>(Select at least one of the HCDs. If you are unsure, picking all is fine.)</comment>
--- USB Host Controller Drivers
&lt;*&gt; EHCI HCD (USB 2.0) support
&lt; &gt; OHCI HCD support
&lt;*&gt; UHCI HCD (most Intel and VIA) support

<comment>(Moving a little further down, we come to CDC and mass storage.)</comment>
&lt; &gt; USB Modem (CDC ACM) support
&lt;*&gt; USB Printer support
&lt;*&gt; USB Mass Storage support

<comment>(If you have a USB Network Card like the RTL8150, you'll need this)</comment>
USB Network Adapters  --->
    &lt;*&gt; USB RTL8150 based ethernet device support (EXPERIMENTAL)

<comment>(If you have a serial to USB converter like the Prolific 2303, you'll need this)</comment>
USB Serial Converter support  --->
    &lt;*&gt; USB Serial Converter support
    &lt;*&gt; USB Prolific 2303 Single Port Serial Driver (NEW)
</pre>

<p>
If you have a USB keyboard, mouse, joystick, or any other input device, you need
to enable HID support. Go back one level to "Device drivers" and enable HID
support as shown:
</p>

<pre caption="Enabling HID support">
Device Drivers ---&gt;
  [*] HID Devices  ---&gt;
    &lt;*&gt;   USB Human Interface Device (full HID) support
</pre>

<p>
Now that your options are set, you can (re)compile the kernel and USB support
should be functional once you reboot into the new kernel. You can now proceed
to <uri link="#postkern">Seeing USB at work</uri> and see if everything is
working as it should.
</p>

</body>
</section>
</chapter>

<chapter id="postkern">
<title>Seeing USB at work</title>
<section>
<title>dmesg is your friend!</title>
<body>

<p>
The time has finally come to play with those USB devices :) So let's get
started. In this chapter, we'll see how the system responds to various USB
devices. We'll start by plugging in a USB 512 MB Memory Stick/Pen Drive. You
could use some other similar mass storage device. We will primarily use
<c>dmesg</c> to see what is happening and how the system responds to the
device.
</p>

<note>
<c>dmesg</c> will generally give a lot of output up front before coming to the
info we need, as it reads the kernel ring buffer that has all the boot up
messages as well. The output in the following examples have only the relevant
portion(s) and extra spaces in between to enable better readability. If needed
please use a <c>dmesg | more</c> or <c>dmesg | less</c> to see the output
better in your system.
</note>

<pre caption="dmesg output for Memory Stick">
<comment>(Plug in Memory Stick into available USB port and then..)</comment>
# <i>dmesg | less</i>

<comment>(The device is picked up as a USB 1.1 and allocated an address.
Also says what HCD it is using.)</comment>
usb 1-1: new full speed USB device using uhci_hcd and address 2

<comment>(SCSI emulation automatically kicks in)</comment>
scsi0 : SCSI emulation for USB Mass Storage devices
usb-storage: device found at 2

<comment>(Now the device information including model number is retrieved)</comment>
usb-storage: waiting for device to settle before scanning
  Vendor: JetFlash  Model: TS512MJF2A        Rev: 1.00
  Type:   Direct-Access                      ANSI SCSI revision: 02
SCSI device sdb: 1003600 512-byte hdwr sectors (514 MB)

<comment>(The write-protect sense is EXPERIMENTAL code in the later kernels)</comment>
sdb: Write Protect is off
sdb: Mode Sense: 0b 00 00 08
sdb: assuming drive cache: write through
SCSI device sdb: 1003600 512-byte hdwr sectors (514 MB)
/dev/scsi/host0/bus0/target0/lun0: p1
Attached scsi removable disk sdb at scsi0, channel 0, id 0, lun 0
Attached scsi generic sg0 at scsi0, channel 0, id 0, lun 0,  type 0
usb-storage: device scan complete
<comment>(At this point, the device is generally accessible by mounting /dev/sdb1)</comment>

<comment>(When the device is disconnected, the system acknowledges the same)</comment>
usb 1-1: USB disconnect, address 2
</pre>

<p>
Once the device is connected and mounted, you can access it like a normal hard
disk. Usual operations like <c>cp</c>, <c>mv</c>, <c>rm</c>, etc work fine. You
could also create a filesystem on the USB stick/format it.
</p>

<pre caption="Accessing the Memory Stick">
# <i>mount /dev/sdb1 /mnt/usb</i>
# <i>df -h</i>
Filesystem            Size  Used Avail Use% Mounted on
/dev/sda8             9.4G  7.5G  1.9G  80% /
/dev/sda9              11G  8.1G  2.4G  78% /usr
none                  189M     0  189M   0% /dev/shm
/dev/sdb1             490M   34M  457M   7% /mnt/usb
</pre>

<note>
Digital cameras can be accessed the same way as memory sticks. I have a Nikon
Coolpix 5200 and this is the way I access it. Cameras these days usually have
two modes to transfer pictures; USB mass storage and PTP (Picture Transfer
Protocol). The camera is set to USB mass storage mode and hence the procedure is
exactly the same as that of accessing a memory stick because of which I have not
explained in detail about it. Please note that this may NOT work in all cases
and with all digital cameras that have USB support.
</note>

<p>
How would a USB mouse show up in case you had one? It will show up as an HID
device.
</p>

<pre caption="USB Optical Mouse">
# <i>dmesg | grep USB</i>
drivers/usb/input/hid-core.c: v2.0:USB HID core driver
usb 1-1: new low speed USB device using address 2
input: USB HID v1.10 Mouse [Logitech USB-PS/2 Optical Mouse] on usb-0000:00:07.2-1
</pre>

<p>
Another nifty command you can use to see the status of your USB ports is
<c>lsusb</c>. This is part of <c>sys-apps/usbutils</c> and will be covered in
the next chapter.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Userspace USB</title>
<section>
<title>Nifty tools</title>
<body>

<p>
So far we've seen how much support exists on the kernel/system side for USB on
Linux. Now we'll take a peek into what kind of support is provided by Gentoo
for USB in the userspace.
</p>

<p>
One of the most useful tools around is <c>lsusb</c>. This lists all the usb
devices connected to the system. Installing it is a breeze.
</p>

<pre caption="Installing usbutils">
# <i>emerge usbutils</i>
</pre>

<p>
Once installed, you can just run <c>lsusb</c> to get simple info on the USB
devices attached to the machine.
</p>

<note>
You have to be root in most cases to run <c>lsusb</c>.
</note>

<warn>
<c>lsusb</c> reads the information for the USB devices from
<path>/proc/bus/usb</path>. If you have not enabled that in your kernel,
chances are that <c>lsusb</c> may not work at all. Please ensure you have
<path>/proc</path> filesystem support enabled in your kernel and that
<c>usbfs</c> is mounted at <path>/proc/bus/usb</path> (which should happen
automatically).
</warn>

<pre caption="lsusb at work">
# <i>lsusb</i>
<comment>(This is the 512 MB Memory Stick from Transcend)</comment>
Bus 001 Device 003: ID 0c76:0005 JMTek, LLC. USBdisk
<comment>(This is the Optical Mouse)</comment>
Bus 001 Device 002: ID 046d:c00e Logitech, Inc. Optical Mouse
<comment>(This is the root hub)</comment>
Bus 001 Device 001: ID 0000:0000
</pre>

<p>
If you are one of those types who love to see lots of information, you have
the option of running <c>lsusb -v</c>. Try that and see the amount of info it
gives out. Another good option is that <c>lsusb</c> dumps the current physical
USB hierarchy as a tree and thus makes it easier to understand the exact
device map. The command is <c>lsusb -t</c>. For example,
</p>

<pre caption="lsusb showing USB hierarchy">
# <i>lsusb -t</i>
Bus#  1
`-Dev#   1 Vendor 0x0000 Product 0x0000
  |-Dev#   2 Vendor 0x046d Product 0xc00e
  `-Dev#   3 Vendor 0x0c76 Product 0x0005
</pre>

<p>
You can easily correlate the outputs of <c>lsusb</c> and <c>lsusb -t</c>,
which helps debugging as well as understanding how USB works.
</p>

</body>
</section>
</chapter>

<chapter>
<title>And thanks to...</title>
<section>
<title>References</title>
<body>

<p>
A good number of online documents helped me during the development of this
document and there are some that are highly technical but truly interesting.
I thought they all deserve some credit, so here we go!
</p>

<ul>
  <li><uri link="http://www.usb.org">The Official USB Website</uri></li>
  <li><uri link="http://www.usb.org/about/faq">The USB FAQ</uri></li>
  <li>
    <uri
    link="http://h18000.www1.hp.com/productinfo/development/openhci.html">Compaq's
    OHCI Standard</uri>
  </li>
  <li>
    <uri link="http://developer.intel.com/technology/usb/uhci11d.htm">Intel's
    UHCI Standard</uri>
  </li>
  <li>
    <uri link="http://www.intel.com/technology/usb/ehcispec.htm">Intel's EHCI
    Standard</uri>
  </li>
</ul>

</body>
</section>
<section>
<title>Other Interesting Links</title>
<body>

<ul>
  <li><uri link="/doc/en/liveusb.xml">Gentoo Linux LiveUSB HOWTO</uri></li>
</ul>

</body>
</section>
</chapter>
</guide>
1	swift	1.1	<?xml version='1.0' encoding="UTF-8"?>
2	swift	1.21	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/usb-guide.xml,v 1.20 2011/09/04 17:53:40 swift Exp $ -->
3	swift	1.1	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5	swift	1.20	<guide>
6	swift	1.1	<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	swift	1.21	<version>2</version>
22			<date>2011-12-26</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 & 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 --->
200			SCSI device support --->
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			<*> SCSI disk support
206
207			<comment>(Then move back a level and go into USB support)</comment>
208			USB support --->
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			<*> Support for Host-side USB
213	swift	1.1
214			<comment>(Select at least one of the HCDs. If you are unsure, picking all is fine.)</comment>
215	neysx	1.3	--- USB Host Controller Drivers
216	swift	1.1	<*> EHCI HCD (USB 2.0) support
217			< > OHCI HCD support
218			<*> UHCI HCD (most Intel and VIA) support
219
220			<comment>(Moving a little further down, we come to CDC and mass storage.)</comment>
221			< > USB Modem (CDC ACM) support
222			<*> USB Printer support
223			<*> USB Mass Storage support
224
225			<comment>(If you have a USB Network Card like the RTL8150, you'll need this)</comment>
226			USB Network Adapters --->
227			<*> USB RTL8150 based ethernet device support (EXPERIMENTAL)
228
229			<comment>(If you have a serial to USB converter like the Prolific 2303, you'll need this)</comment>
230			USB Serial Converter support --->
231			<*> USB Serial Converter support
232	neysx	1.3	<*> USB Prolific 2303 Single Port Serial Driver (NEW)
233	swift	1.1	</pre>
234
235			<p>
236	nightmorph	1.18	If you have a USB keyboard, mouse, joystick, or any other input device, you need
237			to enable HID support. Go back one level to "Device drivers" and enable HID
238			support as shown:
239	swift	1.1	</p>
240	neysx	1.3
241	nightmorph	1.18	<pre caption="Enabling HID support">
242			Device Drivers --->
243			[*] HID Devices --->
244			<*> USB Human Interface Device (full HID) support
245	swift	1.1	</pre>
246
247			<p>
248	nightmorph	1.18	Now that your options are set, you can (re)compile the kernel and USB support
249			should be functional once you reboot into the new kernel. You can now proceed
250			to <uri link="#postkern">Seeing USB at work</uri> and see if everything is
251			working as it should.
252	swift	1.1	</p>
253	neysx	1.3
254	swift	1.1	</body>
255			</section>
256			</chapter>
257
258			<chapter id="postkern">
259			<title>Seeing USB at work</title>
260			<section>
261			<title>dmesg is your friend!</title>
262			<body>
263
264			<p>
265	neysx	1.3	The time has finally come to play with those USB devices :) So let's get
266			started. In this chapter, we'll see how the system responds to various USB
267			devices. We'll start by plugging in a USB 512 MB Memory Stick/Pen Drive. You
268			could use some other similar mass storage device. We will primarily use
269			<c>dmesg</c> to see what is happening and how the system responds to the
270	swift	1.1	device.
271			</p>
272
273			<note>
274	neysx	1.3	<c>dmesg</c> will generally give a lot of output up front before coming to the
275	swift	1.1	info we need, as it reads the kernel ring buffer that has all the boot up
276	neysx	1.3	messages as well. The output in the following examples have only the relevant
277			portion(s) and extra spaces in between to enable better readability. If needed
278			please use a <c>dmesg \| more</c> or <c>dmesg \| less</c> to see the output
279	yoswink	1.2	better in your system.
280	swift	1.1	</note>
281
282			<pre caption="dmesg output for Memory Stick">
283			<comment>(Plug in Memory Stick into available USB port and then..)</comment>
284	yoswink	1.2	# <i>dmesg \| less</i>
285	swift	1.1
286	neysx	1.3	<comment>(The device is picked up as a USB 1.1 and allocated an address.
287			Also says what HCD it is using.)</comment>
288	swift	1.1	usb 1-1: new full speed USB device using uhci_hcd and address 2
289
290			<comment>(SCSI emulation automatically kicks in)</comment>
291			scsi0 : SCSI emulation for USB Mass Storage devices
292			usb-storage: device found at 2
293
294			<comment>(Now the device information including model number is retrieved)</comment>
295			usb-storage: waiting for device to settle before scanning
296			Vendor: JetFlash Model: TS512MJF2A Rev: 1.00
297			Type: Direct-Access ANSI SCSI revision: 02
298	swift	1.21	SCSI device sdb: 1003600 512-byte hdwr sectors (514 MB)
299	swift	1.1
300			<comment>(The write-protect sense is EXPERIMENTAL code in the later kernels)</comment>
301	swift	1.21	sdb: Write Protect is off
302			sdb: Mode Sense: 0b 00 00 08
303			sdb: assuming drive cache: write through
304			SCSI device sdb: 1003600 512-byte hdwr sectors (514 MB)
305	swift	1.1	/dev/scsi/host0/bus0/target0/lun0: p1
306	swift	1.21	Attached scsi removable disk sdb at scsi0, channel 0, id 0, lun 0
307	swift	1.1	Attached scsi generic sg0 at scsi0, channel 0, id 0, lun 0, type 0
308			usb-storage: device scan complete
309	swift	1.21	<comment>(At this point, the device is generally accessible by mounting /dev/sdb1)</comment>
310	swift	1.1
311			<comment>(When the device is disconnected, the system acknowledges the same)</comment>
312			usb 1-1: USB disconnect, address 2
313			</pre>
314
315			<p>
316	neysx	1.3	Once the device is connected and mounted, you can access it like a normal hard
317	swift	1.6	disk. Usual operations like <c>cp</c>, <c>mv</c>, <c>rm</c>, etc work fine. You
318	swift	1.1	could also create a filesystem on the USB stick/format it.
319			</p>
320
321			<pre caption="Accessing the Memory Stick">
322	swift	1.21	# <i>mount /dev/sdb1 /mnt/usb</i>
323	swift	1.1	# <i>df -h</i>
324			Filesystem Size Used Avail Use% Mounted on
325	swift	1.21	/dev/sda8 9.4G 7.5G 1.9G 80% /
326			/dev/sda9 11G 8.1G 2.4G 78% /usr
327	swift	1.1	none 189M 0 189M 0% /dev/shm
328	swift	1.21	/dev/sdb1 490M 34M 457M 7% /mnt/usb
329	swift	1.1	</pre>
330
331			<note>
332	neysx	1.3	Digital cameras can be accessed the same way as memory sticks. I have a Nikon
333	fox2mike	1.7	Coolpix 5200 and this is the way I access it. Cameras these days usually have
334			two modes to transfer pictures; USB mass storage and PTP (Picture Transfer
335			Protocol). The camera is set to USB mass storage mode and hence the procedure is
336			exactly the same as that of accessing a memory stick because of which I have not
337			explained in detail about it. Please note that this may NOT work in all cases
338			and with all digital cameras that have USB support.
339	swift	1.1	</note>
340
341			<p>
342	neysx	1.3	How would a USB mouse show up in case you had one? It will show up as an HID
343	swift	1.1	device.
344			</p>
345
346			<pre caption="USB Optical Mouse">
347			# <i>dmesg \| grep USB</i>
348			drivers/usb/input/hid-core.c: v2.0:USB HID core driver
349			usb 1-1: new low speed USB device using address 2
350			input: USB HID v1.10 Mouse [Logitech USB-PS/2 Optical Mouse] on usb-0000:00:07.2-1
351			</pre>
352
353			<p>
354	neysx	1.3	Another nifty command you can use to see the status of your USB ports is
355			<c>lsusb</c>. This is part of <c>sys-apps/usbutils</c> and will be covered in
356	swift	1.1	the next chapter.
357			</p>
358
359			</body>
360			</section>
361			</chapter>
362
363			<chapter>
364			<title>Userspace USB</title>
365			<section>
366			<title>Nifty tools</title>
367			<body>
368
369			<p>
370	neysx	1.3	So far we've seen how much support exists on the kernel/system side for USB on
371			Linux. Now we'll take a peek into what kind of support is provided by Gentoo
372	swift	1.1	for USB in the userspace.
373			</p>
374
375			<p>
376	neysx	1.3	One of the most useful tools around is <c>lsusb</c>. This lists all the usb
377	swift	1.1	devices connected to the system. Installing it is a breeze.
378			</p>
379
380			<pre caption="Installing usbutils">
381			# <i>emerge usbutils</i>
382			</pre>
383
384			<p>
385	neysx	1.3	Once installed, you can just run <c>lsusb</c> to get simple info on the USB
386	swift	1.1	devices attached to the machine.
387			</p>
388
389			<note>
390			You have to be root in most cases to run <c>lsusb</c>.
391			</note>
392
393			<warn>
394	neysx	1.3	<c>lsusb</c> reads the information for the USB devices from
395			<path>/proc/bus/usb</path>. If you have not enabled that in your kernel,
396			chances are that <c>lsusb</c> may not work at all. Please ensure you have
397	swift	1.1	<path>/proc</path> filesystem support enabled in your kernel and that
398			<c>usbfs</c> is mounted at <path>/proc/bus/usb</path> (which should happen
399			automatically).
400			</warn>
401
402			<pre caption="lsusb at work">
403			# <i>lsusb</i>
404			<comment>(This is the 512 MB Memory Stick from Transcend)</comment>
405			Bus 001 Device 003: ID 0c76:0005 JMTek, LLC. USBdisk
406			<comment>(This is the Optical Mouse)</comment>
407			Bus 001 Device 002: ID 046d:c00e Logitech, Inc. Optical Mouse
408			<comment>(This is the root hub)</comment>
409			Bus 001 Device 001: ID 0000:0000
410			</pre>
411
412			<p>
413	neysx	1.3	If you are one of those types who love to see lots of information, you have
414			the option of running <c>lsusb -v</c>. Try that and see the amount of info it
415			gives out. Another good option is that <c>lsusb</c> dumps the current physical
416			USB hierarchy as a tree and thus makes it easier to understand the exact
417	swift	1.1	device map. The command is <c>lsusb -t</c>. For example,
418			</p>
419
420			<pre caption="lsusb showing USB hierarchy">
421			# <i>lsusb -t</i>
422			Bus# 1
423			`-Dev# 1 Vendor 0x0000 Product 0x0000
424			\|-Dev# 2 Vendor 0x046d Product 0xc00e
425			`-Dev# 3 Vendor 0x0c76 Product 0x0005
426			</pre>
427
428			<p>
429	neysx	1.3	You can easily correlate the outputs of <c>lsusb</c> and <c>lsusb -t</c>,
430	swift	1.1	which helps debugging as well as understanding how USB works.
431			</p>
432
433			</body>
434			</section>
435			</chapter>
436
437			<chapter>
438			<title>And thanks to...</title>
439			<section>
440			<title>References</title>
441			<body>
442
443			<p>
444	swift	1.6	A good number of online documents helped me during the development of this
445	swift	1.17	document and there are some that are highly technical but truly interesting.
446	swift	1.6	I thought they all deserve some credit, so here we go!
447	swift	1.1	</p>
448	neysx	1.3
449			<ul>
450			<li><uri link="http://www.usb.org">The Official USB Website</uri></li>
451	swift	1.8	<li><uri link="http://www.usb.org/about/faq">The USB FAQ</uri></li>
452	neysx	1.3	<li>
453			<uri
454			link="http://h18000.www1.hp.com/productinfo/development/openhci.html">Compaq's
455			OHCI Standard</uri>
456			</li>
457			<li>
458			<uri link="http://developer.intel.com/technology/usb/uhci11d.htm">Intel's
459			UHCI Standard</uri>
460			</li>
461			<li>
462			<uri link="http://www.intel.com/technology/usb/ehcispec.htm">Intel's EHCI
463			Standard</uri>
464			</li>
465	fox2mike	1.10	</ul>
466
467			</body>
468			</section>
469			<section>
470			<title>Other Interesting Links</title>
471			<body>
472
473			<ul>
474	swift	1.17	<li><uri link="/doc/en/liveusb.xml">Gentoo Linux LiveUSB HOWTO</uri></li>
475	neysx	1.3	</ul>
476	swift	1.1
477			</body>
478			</section>
479			</chapter>
480			</guide>