install.sgml

usb develop guide

<chapter>
  <Title>How to get USB devices working under Linux</>

<Sect1><Title>Basic USB Configuration</>

<Para>
You need a late version kernel. Kernel versions 2.2.7 and later
contain the USB code. You should, in an ideal world, be running the
current 2.4.0-test kernel, ideally with any pre-patches for the next
kernel. The current 2.2.x kernels do contain some USB code, but it
is less well supported, and development is patchy.
USB code is in fairly early
development, so the changes between each version (and the bugs) tend
to change fairly fast. Support on the mailing list for anything except
the lastest version is scant at best.
</>

<Para>
The user assistance mailing list is 
<Email>[e-mail]</Email>. To 
subscribe or unsubscribe, go to <ulink url="http://lists.sourceforge.net/mailman/listinfo/linux-usb-devel">http://lists.sourceforge.net/mailman/listinfo/linux-usb-devel</ulink>
</>

<Para>
You need to configure USB into your kernel. Use of <UserInput> make
menuconfig </UserInput> is recommended.  Under <UserInput> USB
support</UserInput>, you need to select <UserInput>Support for
USB</UserInput>. You also need to select either <UserInput>UHCI (Intel
PIIX4, VIA, ...) support</UserInput>, <UserInput>UHCI Alternate
Driver (JE) support</UserInput> or
<UserInput>OHCI-HCD (Compaq, iMacs, OPTi, SiS, ALi, ...) support</UserInput>.
 Which one you select is dependent on what
kind of motherboard or adapter you have. Intel and Via motherboards,
and Via-based adapters are UHCI, and you can use either of the two
UHCI drivers - there seems to be little user visible difference
between them. Ali and SiS chipsets, Compaq and NEC
motherboards, iMacs and any adapter using Opti chips (just about all
of them) are OHCI, and you should use OHCI-HCD. If you do not know
what kind of controller to choose, check your motherboard
documentation.  You can also look at <FileName>/proc/pci</FileName>
for a hint - if the USB entry is of the form 0xHHHH, where HHHH are
hex digits (e.g. something like <UserInput>I/O at 0xe400</UserInput>),
then it is UHCI. If it is of the form <UserInput>32 bit memory at
0xHH000000</UserInput>, where HH are hex digits (e.g. something like
<UserInput>32 bit memory at 0xee000000</UserInput>), then it is OHCI.
Failing that, just try both.
</>

<Para>
Always build in the Preliminary USB device filesystem. Leaving this out
will make resolving problems almost impossible, and is essential if
you need to check that your kernel is configured correctly, and
your USB devices are being recognised correctly.
</para>

<Para>
You also need to select whichever devices you want to use, for example
<UserInput>USB Human Interface Device (HID) support</UserInput> for a
 USB keyboard, mouse,
joystick, tablet or gamepad, <UserInput>USB Scanner support</UserInput> for
certain scanners, <UserInput>USB Audio support</UserInput> for USB
speakers, <UserInput>USB Modem (CDC ACM) support</UserInput> for
a POTS or ISDN modem, <UserInput>USB Printer support</UserInput>
for a USB printer, <UserInput>USB Serial Converter support</UserInput>
(with the appropriate subordinate options) for some serial port type devices,
<UserInput>USB CPiA Camera support</UserInput> for cameras based on the
Vision CPiA chipset, <UserInput>USB IBM (Xirlink) C-it Camera support
</UserInput> for camera based on the IBM camera chipset,
<UserInput>USB OV511 Camera support</UserInput> for cameras
based on OmniVision's OV511 chipset, <UserInput>USB Kodak DC-2xx Camera
support</UserInput> for downloading images from Kodak's DC-200 series
cameras, <UserInput>USB Mass Storage support</UserInput> for
mass storage devices,
<UserInput>USS720 parport driver</UserInput> for certain parallel port
adapters, <UserInput>DABUSB driver</UserInput> for an experimental
Digital Audio Broadcast receiver and <UserInput>PLUSB Prolific USB-Network
driver</UserInput> for certain USB to USB type connections.
You should be able to use modules, kernel only, or split modules and
kernel code.
</>

<Para>
USB hubs are automatically supported. Some devices may stop and start
working between kernel versions. Remember that you are using
experimental code. Devices not listed in this document are not working
at the time of writing, although developers are always welcome to
contribute to the current codebase. 
</>

<Para>
Rebuild the kernel and the modules (if you configured to build as modules),
and install the new kernel and the new modules. Reboot the system. If you need
instruction on how to do this, refer to the
<ulink url="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html">Linux Kernel HOWTO</ulink>.
</>

<Para>
If you are using modules, you need to load the following modules:
<ItemizedList>
<ListItem>
<Para>
<filename>usbcore.o</filename>
</>
</ListItem>
<ListItem>
<Para>
<filename>usb-uhci.o</filename>, <filename>uhci.o</filename>
or <filename>usb-ohci.o</filename>
</>
</ListItem>
</ItemizedList>
and any driver modules, such as
<filename>scanner.o</filename> or <filename>printer.o</filename>.
</>

<Para>
Inspect the kernel logs.
If there isn't anything that could be USB related,
likely causes are use of the wrong driver (UHCI when you needed
OHCI or OHCI when you needed UHCI), not physically installing
the hardware, a BIOS configuration that disables USB or stuffing up
the configuration or installation of the kernel.
</>

</Sect1>

<Sect1><Title>USB Device Filesystem</title>
<para>
The USB device filesystem is a dynamically generated filesystem, similar to
the <FileName>/proc</FileName> filesystem. This filesystem can be mounted
just about anywhere, however it is customarily mounted on
<FileName>/proc/bus/usb</FileName>,
which is an entry node created by the USB code, intended to be used as a
mount point for this system. Mounting in other locations may break
user space utilities, but should not affect the kernel support.
</para>

<para>
You need to select "Preliminary USB Device Filesystem" to make this work.
You also need to enable general <FileName>/proc</Filename> support, and
to have it mounted (normally automatic).
</>

<para>
To mount the filesystem, you need to be root. Use the mount
command: <UserInput>mount -t usbdevfs none /proc/bus/usb</UserInput>.
Note that the <UserInput>none</UserInput> keyword is arbitrary - you
can use anything, and some people prefer to use <UserInput>usbdevfs
</UserInput>, as it makes the mount output look better.
</para>

<para>
If you do not want to have to mount the filesystem each time you reboot
the system, you can add the following to <FileName>/etc/fstab</FileName>
after the <FileName>/proc</FileName> entry:
<screen>
none            /proc/bus/usb             usbdevfs        defaults   0   0
</screen>
This has the same effect as the mount command.
</para>

<para>
After you have mounted the filesystem, the contents of
<FileName>/proc/bus/usb</FileName> should look something like:
<screen>
dr-xr-xr-x   1 root     root            0 Jan 26 10:40 001
-r--r--r--   1 root     root            0 Jan 26 10:40 devices
-r--r--r--   1 root     root            0 Jan 26 10:40 drivers
</screen>.
You may have more than one numbered directory entry if your machine
has more than one universal serial bus controller.
</para>

<para>
Full interpretation of the <FileName>devices</FileName> and
<FileName>drivers</FileName> files is provided later in this guide, in the
user's section. The numbered entries are machine readable, but are not
usually of any use to a user.
</para>
</Sect1>

<Sect1><Title>USB Human Interface Device (HID) Configuration</Title>

<Sect2><Title>General HID Configuration</Title>
<Para>
There are two options for using a USB mouse or a USB keyboard - the
standalone Boot Protocol (HIDBP) way and the full featured HID driver
way. The Boot Protocol way is generally inferior, and this document
describes the full featured way. The Boot Protocol way may be
appropriate for embedded systems and other systems with resource
constraints and no real need for the full keyboard and mouse
capabilities.
</Para>

<Para>
It is important to remember that the HID driver handles those devices
(or actually those interfaces on each device) that claim to comply
with the <ulink
url="http://www.usb.org/developers/data/devclass/hid1_1.pdf">Human Interface
Device (HID) specification</ulink>. However the HID specification
doesn't say anything about what the HID driver should do with
information received from a HID device, or where the information that
is sent to a device comes from, since this is obviously dependent on
what the device is supposed to be doing, and what the operating system
is. Linux (at the operating system kernel level) supports four
interfaces to a HID device - keyboard, mouse, joystick and a generic
interface, known as the event interface. These are implemented by the
Input device level.
</para>
</Sect2>

<Sect2><Title>HID Mouse Configuration</Title>
<Para>
In the kernel configuration stage, you need to turn on
<UserInput>USB Human Interface Device (HID) support</UserInput> in the
<UserInput>USB support</UserInput> and
<UserInput>Mouse Support</UserInput> in the <UserInput>Input core
support</UserInput>. You don't need to worry about the screen
resolution entries for a normal mouse - these are for mouse-like
devices such as a graphics tablet. Do <emphasis>not</emphasis> turn on
<UserInput>USB HIDBP Mouse support</UserInput>. Perform the normal
kernel rebuild and installation steps. If you are installing as
modules, you need to load the <FileName>input.o</FileName>,
<FileName>hid.o</FileName> and <FileName>mousedev.o</FileName> modules.
</para>

<Para>
Plug in a USB mouse and check that your mouse has been correctly sensed
by the kernel. If you don't have a kernel message, look for the
changes to <filename>/proc/bus/usb/devices</filename>.
</para>

<Para>
Since USB supports multiple identical devices, you can have multiple
mice plugged in. You can get each mouse seperately, or you can get
them all mixed together. You almost always want the mixed version, and
that is what will be used in this example.
You need to set up a device node entry for the mixed mice. It is
customary to create the entries for this device in the
<FileName>/dev/input/</FileName> directory. Use the following commands:
<screen>
mkdir /dev/input
mknod /dev/input/mice c 13 63
</screen>
</>

<Para>
If you <UserInput>cat /dev/input/mice</UserInput> you should see
some bizarre looking characters as you move the mouse or click any
of the buttons.
</para>

<Para>
If you want to use the mouse under X, you have various options. Which one
you select is dependent on what version of XFree86 you are using and
whether you are using only USB for your
mouse (or mice), or whether you want to use a USB mouse and some
other kind of pointer device.
</para>

<para>
<ItemizedList>
<ListItem>
<Para> You need to edit the <Filename>XF86Config</Filename> file
 (usually <Filename>/usr/X11R6/lib/X11/XF86Config</Filename> or
 <FileName>/etc/X11/XF86Config</FileName>).
</para>
</listitem>

<listitem>
<para>
If you are using XFree86 version 4.0 or later,
add a <SystemItem>InputDevice</SystemItem> section that looks
like the following:
<screen>
Section "InputDevice"
     Identifier  "USB Mice"
     Driver      "mouse"
     Option      "Protocol"   "IMPS/2"
     Option      "Device"     "/dev/input/mice"
EndSection
</screen>
or, if you want to use a wheel mouse, something like:
<screen>
Section "InputDevice"
     Identifier  "USB Mice"
     Driver      "mouse"
     Option      "Protocol"   "IMPS/2"
     Option      "Device"     "/dev/input/mice"
     Option      "ZAxisMapping"   "4 5"
     Option      "Buttons"        "5"
EndSection
</screen>
may be more useful. Consult the XFree86 documentation for a detailed
explaination and more examples.
</para>
<para>
You also need to add an entry to each applicable
<SystemItem>ServerLayout</SystemItem> Section. These are normally at the
end of the configuration file. If you only have a USB mouse (or USB mice),
then replace the line with the <SystemItem>"CorePointer"</Systemitem> entry
with the following line:
<screen>
     InputDevice "USB Mice" "CorePointer"
</screen>
If you want to use both a USB mouse (or USB mice) and some other kind of pointer
device, then add (do not replace) the following line to the applicable
<SystemItem>ServerLayout</SystemItem> sections:
<screen>
     InputDevice "USB Mice" "SendCoreEvents"
</screen>
</para>
</listitem>

<listitem>
<para>
If you are using only a USB mouse (or USB mice) with XFree86 3.3,
edit the <SystemItem>Pointer</SystemItem> section so that it
looks like the following:
<screen>
Section "Pointer"
    Protocol    "IMPS/2"
    Device      "/dev/input/mice"
EndSection
</screen>
</para>
</listitem>

<listitem>
<para>