using.sgml

usb develop guide

<chapter>
  <Title>Using Linux USB</>

<Sect1><Title>Reading the Linux USB Device Filesystem output</>
<Para>
The USB device filesystem is a dynamically generated filesystem that
complements the normal device node system, and can be used to write
user space device drivers. Writing of user space device drivers is
covered in the programmer's section of this guide. In addition to the
device nodes, there are two files that are also generated - the
<FileName>drivers</FileName> and <FileName>devices</FileName> files.
If you followed the instructions in the installation chapter, you
should find them as <FileName>/proc/bus/usb/drivers</FileName> and
<FileName>/proc/bus/usb/device</FileName> respectively. If the
<FileName>/proc/bus/usb</FileName> directory is empty, you have not
mounted the filesystem, or you have mounted it in the wrong location.
</>

<Para>
<FileName>/proc/bus/usb/drivers</FileName> just lists the currently
registered drivers (even if the driver is not being used by any device). 
This is most useful when testing module installation, and checking for
USB support in an unknown kernel. Here is an example of its use:
<screen>
[bradh@rachel bradh]$ more /proc/bus/usb/drivers
hid
ov511
cpia
printer
hub
</screen>
</>

<Para>
<FileName>/proc/bus/usb/devices</FileName> lists information about
the devices currently attached to the USB bus. This is very useful when
trying to figure out if the device is correctly enumerated. Here is an
example of its use, showing the root hub, a hub, a mouse and a
camera:
<screen>
T:  Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12  MxCh= 2
B:  Alloc= 28/900 us ( 3%), #Int=  2, #Iso=  0
D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=0000 ProdID=0000 Rev= 0.00
C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr=  0mA
I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl=255ms
T:  Bus=00 Lev=01 Prnt=01 Port=01 Cnt=01 Dev#=  2 Spd=12  MxCh= 4
D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=0451 ProdID=1446 Rev= 1.00
C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
E:  Ad=81(I) Atr=03(Int.) MxPS=   1 Ivl=255ms
T:  Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#=  3 Spd=12  MxCh= 0
D:  Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=0553 ProdID=0002 Rev= 1.00
C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=400mA
I:  If#= 1 Alt= 0 #EPs= 1 Cls=ff(vend.) Sub=00 Prot=ff Driver=cpia
E:  Ad=81(I) Atr=01(Isoc) MxPS=   0 Ivl=  1ms
I:  If#= 1 Alt= 1 #EPs= 1 Cls=ff(vend.) Sub=00 Prot=ff Driver=cpia
E:  Ad=81(I) Atr=01(Isoc) MxPS= 448 Ivl=  1ms
I:  If#= 1 Alt= 2 #EPs= 1 Cls=ff(vend.) Sub=00 Prot=ff Driver=cpia
E:  Ad=81(I) Atr=01(Isoc) MxPS= 704 Ivl=  1ms
I:  If#= 1 Alt= 3 #EPs= 1 Cls=ff(vend.) Sub=00 Prot=ff Driver=cpia
E:  Ad=81(I) Atr=01(Isoc) MxPS= 960 Ivl=  1ms
T:  Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#=  5 Spd=1.5 MxCh= 0
D:  Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=046d ProdID=c001 Rev= 1.10
S:  Manufacturer=Logitech
S:  Product=USB-PS/2 Mouse
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 50mA
I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=01 Prot=02 Driver=hid
E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl= 10ms
</screen>
</>

<para>
The information in the <FileName>/proc/bus/usb/devices</FileName> output
is arranged in groups:
<ItemizedList>
<ListItem>

<para>
The line that starts with <UserInput>T:</UserInput> is the topology.
<UserInput>Bus</UserInput> indicates which bus the device is on.
<UserInput>Lev</UserInput> indicates the level of the device, starting
at level 00 for the root hub, level 01 for any device attached to the
root hub, level 02 for devices attached to hubs at level 01, and so
on. <UserInput>Prnt</UserInput> is the parent device for this device
(always 00 for the root hub, and 01 for the devices attached to the root
hub). <UserInput>Port</UserInput> is the port on the parent device,
starting at 00 for the first port on each
device. <UserInput>Prnt/Port</UserInput> is unique per
bus. <UserInput> Cnt</UserInput> indicates what number device this is,
at this level, based on the enumeration order within that level of the
topology, starting at 01 for the first
device. <UserInput>Dev#</UserInput> indicates what number device this
is, irrespective of level, based on the bus enumeration order. This is
unique per bus.
<UserInput>Spd</UserInput> indicates what speed this device is running
at, in Mbps (either 1.5 or 12 with the current version of USB).
 <UserInput>MxCh</UserInput> indicates how many
devices can be connected to this device, and is 00 for anything except
a hub.  <UserInput>Driver</UserInput> indicates which device driver is
being used for this device - an entry of <UserInput>(none)</UserInput>
indicates that no driver is being used.
</>
</ListItem>

<ListItem>
<para>
The line that starts with <UserInput>D:</UserInput> is information
  from the device descriptor. <UserInput>Ver</UserInput> indicates
  which USB specification version the device claims to
  meet. <UserInput>Cls</UserInput> indicates which device class the
  device is claiming to meet, in both hexadecimal and as a string. A
  <UserInput>Cls</UserInput> entry of <UserInput>00(>ifc)</UserInput>
  indicates that the device class specification compliance is
  interface dependent, and the interface descriptor should be read for
  device class information. <UserInput>Sub</UserInput> indicates which
  sub-class (within the <UserInput>Cls</UserInput> entry), the device
  meets. <UserInput>Prot</UserInput> indicates which protocol within
a class or sub-class the device claims to meet.
<UserInput>MxPS</UserInput> indicates how big the packets
  from Endpoint 0 are. <UserInput>#Cfgs</UserInput> indicates how many
  configurations this device has.
</>
</ListItem>

<ListItem>
<para>
Much like <UserInput>D:</UserInput>, the line that starts with
<UserInput>P:</UserInput> is information from the device descriptor,
and is seperated mainly because it wouldn't all fit on one
line. <UserInput>Vendor</UserInput> indicates the Vendor
Identification code for the device, and <UserInput>ProdID</UserInput>
indicates the Product Identification code for the
device. <UserInput>Rev</UserInput> indicates the product revision
number.
</>
</ListItem>

<ListItem>
<para>
Refer to the USB specification clause 9.7.1 for further information on
device descriptors.
</>
</ListItem>

<ListItem>
<para>
The lines that start with <UserInput>S:</UserInput>, if any, are the
vendor and product strings that the device returned.
</>
</ListItem

<ListItem>
<para>
The line that starts with <UserInput>C:</UserInput> is information
  from the configuration descriptor - the number of
  <UserInput>C:</UserInput>lines per device is given by
  <UserInput>#Cfgs</UserInput>, and the entry followed by an asterisk
  is the current configuration. <UserInput>#If</UserInput> indicates
  how many interfaces the device has. <UserInput>Cfg#</UserInput>
  indicates which configuration is being
  described. <UserInput>Atr</UserInput> is a hexadecimal indication of
  the device attributes (0x80 for bus-powered, 0x40 for self-powered,
  0x20 for remote wake-up capable). <UserInput>MxPwr</UserInput> is the
  maximum power draw for this device configuration, in
  milliamps. Refer to USB specification clause 9.7.2 for further
  information on configuration descriptors.
</>
</ListItem>

<ListItem>
<para>
The line that starts with <UserInput>I:</UserInput>
is information from the interface descriptor - the number of
<UserInput>I:</UserInput> lines per <UserInput>C:</UserInput> line is
given by the <UserInput>#Ifs</UserInput>
entry. <UserInput>If#</UserInput> indicates which interface is being
described within a given device
configuration. <UserInput>Alt</UserInput> indicates which alternate
setting of this interface is being
described. <UserInput>#EPs</UserInput> indicates how many endpoints
there are within the alternate setting for this
endpoint. <UserInput>Cls</UserInput> indicates which class the
alternate setting of the interface corresponds to, in both hexadecimal
and as a character string. <UserInput>Sub</UserInput> indicates which
sub-class the alternate setting of the interface belongs
to. <UserInput>Prot</UserInput> indicates which interface protocol
(within a class and sub-class tuple) the alternate setting of the
interface conforms to. <UserInput>Driver</UserInput> indicates which
of the various USB drivers has claimed this interface.
See USB specification clause 9.7.3 for further information.
</>
</ListItem>

<ListItem>
<para>
The line that starts with <UserInput>E:</UserInput> is information
from the endpoint descriptor - the number of
<UserInput>E:</UserInput> lines per <UserInput>I:</UserInput> line is
given by the <UserInput>#EPs</UserInput> entry. Endpoint 0 is not
displayed. <UserInput>Ad</UserInput> indicates the endpoint address,
with a letter to indicate whether the endpoint is an In or Out
endpoint. <UserInput>Atr</UserInput> indicate the attribute (transfer
type) associated with the endpoint, followed by a string translating
the transfer type. <UserInput>MxPS</UserInput> indicates the maximum
packet size this endpoint is capable of sending or receiving, as
appropriate.  <UserInput>Ivl</UserInput> indicates the interval, in
milliseconds, between polling of interrupt
endpoints. <UserInput>Ivl</UserInput> is ignored for bulk and control
transfers, and is set to 1 for isochronous transfers. See USB specification
clause 9.7.4 for further information on endpoint descriptors.
</>
</ListItem>
</ItemizedList>
</>

<para>
Refer to <FileName>linux/Documentation/usb/proc_usb_info.txt</FileName> for
more information on using the USB device filesystem information.
</>
</Sect1>

<Sect1>
<title>Configuring extra keys on USB keyboards</title>

<para>
To understand how to configure the additional keys that are provided on
some USB keyboards, it helps to understand they way in which key processing
works under Linux and X.
</para>

<para>
The most fundamental level of keyboard processing is a scancode. The USB
keyboard driver pipes scancodes into the normal kernel keyboard driver.
Depending on the mode in which the keyboard is operated, these can
either be sent to the application directly (known as scancode or raw mode)
or translated using a keyboard mapping table (known as the keymap)
before being sent to the application (known as keycode or intepreted mode).
</para>

<para>
X uses the raw scancodes, which are known as keycodes in X documentation.
These are translated inside the X server to a functional equivalent, known
as a key symbol or keysym using a mapping table, although this is not the
same format and performs a subtly different function. This means that
translations in console mode and under X are not the same.
</para>