Skip to content

L
linux
Commit d80b5005 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Greg Kroah-Hartman
Browse files
Options

docs: usb: convert documents to ReST 

Convert USB documents to ReST, in order to prepare for adding it
to the kernel API book, as most of the stuff there are driver or
subsystem-related.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 5f9be5f3
Expand all Show whitespace changes
Inline Side-by-side
Showing with 1663 additions and 1239 deletions
Documentation/usb/WUSB-Design-overview.txt
View file @ d80b5005
================================
Linux UWB + Wireless USB + WiNET Linux UWB + Wireless USB + WiNET
================================
Copyright (C) 2005-2006 Intel Corporation
(C) 2005-2006 Intel Corporation
Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com> Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
This program is free software; you can redistribute it and/or This program is free software; you can redistribute it and/or
...@@ -29,6 +31,7 @@ drivers for the USB based UWB radio controllers defined in the ...@@ -29,6 +31,7 @@ drivers for the USB based UWB radio controllers defined in the
Wireless USB 1.0 specification (including Wireless USB host controller Wireless USB 1.0 specification (including Wireless USB host controller
and an Intel WiNET controller). and an Intel WiNET controller).
.. Contents
1. Introduction 1. Introduction
1. HWA: Host Wire adapters, your Wireless USB dongle 1. HWA: Host Wire adapters, your Wireless USB dongle
...@@ -51,7 +54,8 @@ and an Intel WiNET controller). ...@@ -51,7 +54,8 @@ and an Intel WiNET controller).
4. Glossary 4. Glossary
Introduction Introduction
============
UWB is a wide-band communication protocol that is to serve also as the UWB is a wide-band communication protocol that is to serve also as the
low-level protocol for others (much like TCP sits on IP). Currently low-level protocol for others (much like TCP sits on IP). Currently
...@@ -93,7 +97,8 @@ The different logical parts of this driver are: ...@@ -93,7 +97,8 @@ The different logical parts of this driver are:
do the actual WUSB. do the actual WUSB.
HWA: Host Wire adapters, your Wireless USB dongle HWA: Host Wire adapters, your Wireless USB dongle
-------------------------------------------------
WUSB also defines a device called a Host Wire Adaptor (HWA), which in WUSB also defines a device called a Host Wire Adaptor (HWA), which in
mere terms is a USB dongle that enables your PC to have UWB and Wireless mere terms is a USB dongle that enables your PC to have UWB and Wireless
...@@ -125,7 +130,8 @@ The HWA itself is broken in two or three main interfaces: ...@@ -125,7 +130,8 @@ The HWA itself is broken in two or three main interfaces:
their type and kick into gear. their type and kick into gear.
DWA: Device Wired Adaptor, a Wireless USB hub for wired devices DWA: Device Wired Adaptor, a Wireless USB hub for wired devices
---------------------------------------------------------------
These are the complement to HWAs. They are a USB host for connecting These are the complement to HWAs. They are a USB host for connecting
wired devices, but it is connected to your PC connected via Wireless wired devices, but it is connected to your PC connected via Wireless
...@@ -137,7 +143,8 @@ code with the HWA-RC driver; there is a bunch of factorization work that ...@@ -137,7 +143,8 @@ code with the HWA-RC driver; there is a bunch of factorization work that
has been done to support that in upcoming releases. has been done to support that in upcoming releases.
WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter
-------------------------------------------------------------------
This is your usual PCI device that implements WHCI. Similar in concept This is your usual PCI device that implements WHCI. Similar in concept
to EHCI, it allows your wireless USB devices (including DWAs) to connect to EHCI, it allows your wireless USB devices (including DWAs) to connect
...@@ -148,7 +155,8 @@ There is still no driver support for this, but will be in upcoming ...@@ -148,7 +155,8 @@ There is still no driver support for this, but will be in upcoming
releases. releases.
The UWB stack The UWB stack
=============
The main mission of the UWB stack is to keep a tally of which devices The main mission of the UWB stack is to keep a tally of which devices
are in radio proximity to allow drivers to connect to them. As well, it are in radio proximity to allow drivers to connect to them. As well, it
...@@ -156,7 +164,8 @@ provides an API for controlling the local radio controllers (RCs from ...@@ -156,7 +164,8 @@ provides an API for controlling the local radio controllers (RCs from
now on), such as to start/stop beaconing, scan, allocate bandwidth, etc. now on), such as to start/stop beaconing, scan, allocate bandwidth, etc.
Devices and hosts: the basic structure Devices and hosts: the basic structure
--------------------------------------
The main building block here is the UWB device (struct uwb_dev). For The main building block here is the UWB device (struct uwb_dev). For
each device that pops up in radio presence (ie: the UWB host receives a each device that pops up in radio presence (ie: the UWB host receives a
...@@ -187,7 +196,8 @@ the USB connected HWA. Eventually, drivers/whci-rc.c will do the same ...@@ -187,7 +196,8 @@ the USB connected HWA. Eventually, drivers/whci-rc.c will do the same
for the PCI connected WHCI controller. for the PCI connected WHCI controller.
Host Controller life cycle Host Controller life cycle
--------------------------
So let's say we connect a dongle to the system: it is detected and So let's say we connect a dongle to the system: it is detected and
firmware uploaded if needed [for Intel's i1480 firmware uploaded if needed [for Intel's i1480
...@@ -209,7 +219,8 @@ When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/ ...@@ -209,7 +219,8 @@ When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/
takes time of tearing everything down safely (or not...). takes time of tearing everything down safely (or not...).
On the air: beacons and enumerating the radio neighborhood On the air: beacons and enumerating the radio neighborhood
----------------------------------------------------------
So assuming we have devices and we have agreed for a channel to connect So assuming we have devices and we have agreed for a channel to connect
on (let's say 9), we put the new RC to beacon: on (let's say 9), we put the new RC to beacon:
...@@ -235,12 +246,14 @@ are received in some time, the device is considered gone and wiped out ...@@ -235,12 +246,14 @@ are received in some time, the device is considered gone and wiped out
the beacon cache of dead devices]. the beacon cache of dead devices].
Device lists Device lists
------------
All UWB devices are kept in the list of the struct bus_type uwb_bus_type. All UWB devices are kept in the list of the struct bus_type uwb_bus_type.
Bandwidth allocation Bandwidth allocation
--------------------
The UWB stack maintains a local copy of DRP availability through The UWB stack maintains a local copy of DRP availability through
processing of incoming *DRP Availability Change* notifications. This processing of incoming *DRP Availability Change* notifications. This
...@@ -260,7 +273,8 @@ completion. [Note: The bandwidth reservation work is in progress and ...@@ -260,7 +273,8 @@ completion. [Note: The bandwidth reservation work is in progress and
subject to change.] subject to change.]
Wireless USB Host Controller drivers Wireless USB Host Controller drivers
====================================
*WARNING* This section needs a lot of work! *WARNING* This section needs a lot of work!
...@@ -296,7 +310,8 @@ starts sending MMCs. ...@@ -296,7 +310,8 @@ starts sending MMCs.
Now it all depends on external stimuli. Now it all depends on external stimuli.
*New device connection* New device connection
---------------------
A new device pops up, it scans the radio looking for MMCs that give out A new device pops up, it scans the radio looking for MMCs that give out
the existence of Wireless USB channels. Once one (or more) are found, the existence of Wireless USB channels. Once one (or more) are found,
...@@ -322,7 +337,8 @@ has seen the port status changes, as we have been toggling them. It will ...@@ -322,7 +337,8 @@ has seen the port status changes, as we have been toggling them. It will
start enumerating and doing transfers through usb_hcd->urb_enqueue() to start enumerating and doing transfers through usb_hcd->urb_enqueue() to
read descriptors and move our data. read descriptors and move our data.
*Device life cycle and keep alives* Device life cycle and keep alives
---------------------------------
Every time there is a successful transfer to/from a device, we update a Every time there is a successful transfer to/from a device, we update a
per-device activity timestamp. If not, every now and then we check and per-device activity timestamp. If not, every now and then we check and
...@@ -340,7 +356,8 @@ device list looking for whom needs refreshing. ...@@ -340,7 +356,8 @@ device list looking for whom needs refreshing.
If the device wants to disconnect, it will either die (ugly) or send a If the device wants to disconnect, it will either die (ugly) or send a
/DN_Disconnect/ that will prompt a disconnection from the system. /DN_Disconnect/ that will prompt a disconnection from the system.
*Sending and receiving data* Sending and receiving data
--------------------------
Data is sent and received through /Remote Pipes/ (rpipes). An rpipe is Data is sent and received through /Remote Pipes/ (rpipes). An rpipe is
/aimed/ at an endpoint in a WUSB device. This is the same for HWAs and /aimed/ at an endpoint in a WUSB device. This is the same for HWAs and
...@@ -394,7 +411,8 @@ finalize the transfer. ...@@ -394,7 +411,8 @@ finalize the transfer.
For IN xfers, we only issue URBs for the segments we want to read and For IN xfers, we only issue URBs for the segments we want to read and
then wait for the xfer result data. then wait for the xfer result data.
*URB mapping into xfers* URB mapping into xfers
^^^^^^^^^^^^^^^^^^^^^^
This is done by hwahc_op_urb_[en|de]queue(). In enqueue() we aim an This is done by hwahc_op_urb_[en|de]queue(). In enqueue() we aim an
rpipe to the endpoint where we have to transmit, create a transfer rpipe to the endpoint where we have to transmit, create a transfer
...@@ -407,7 +425,8 @@ and not yet done and when all that is done, the xfer callback will be ...@@ -407,7 +425,8 @@ and not yet done and when all that is done, the xfer callback will be
called--this will call the URB callback. called--this will call the URB callback.
Glossary Glossary
========
*DWA* -- Device Wire Adapter *DWA* -- Device Wire Adapter
...@@ -436,4 +455,3 @@ the host. ...@@ -436,4 +455,3 @@ the host.
Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by
InakyPerezGonzalez) InakyPerezGonzalez)
Documentation/usb/acm.txt
View file @ d80b5005
Linux ACM driver v0.16 ======================
(c) 1999 Vojtech Pavlik <vojtech@suse.cz> Linux ACM driver v0.16
Sponsored by SuSE ======================
----------------------------------------------------------------------------
Copyright (c) 1999 Vojtech Pavlik <vojtech@suse.cz>
Sponsored by SuSE
0. Disclaimer 0. Disclaimer
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
This program is free software; you can redistribute it and/or modify it This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option) Software Foundation; either version 2 of the License, or (at your option)
any later version. any later version.
This program is distributed in the hope that it will be useful, but This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details. more details.
You should have received a copy of the GNU General Public License along You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc., 59 with this program; if not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA Temple Place, Suite 330, Boston, MA 02111-1307 USA
Should you need to contact me, the author, you can do so either by e-mail Should you need to contact me, the author, you can do so either by e-mail -
- mail your message to <vojtech@suse.cz>, or by paper mail: Vojtech Pavlik, mail your message to <vojtech@suse.cz>, or by paper mail: Vojtech Pavlik,
Ucitelska 1576, Prague 8, 182 00 Czech Republic Ucitelska 1576, Prague 8, 182 00 Czech Republic
For your convenience, the GNU General Public License version 2 is included For your convenience, the GNU General Public License version 2 is included
in the package: See the file COPYING. in the package: See the file COPYING.
1. Usage 1. Usage
~~~~~~~~ ~~~~~~~~
The drivers/usb/class/cdc-acm.c drivers works with USB modems and USB ISDN terminal The drivers/usb/class/cdc-acm.c drivers works with USB modems and USB ISDN terminal
adapters that conform to the Universal Serial Bus Communication Device Class adapters that conform to the Universal Serial Bus Communication Device Class
Abstract Control Model (USB CDC ACM) specification. Abstract Control Model (USB CDC ACM) specification.
Many modems do, here is a list of those I know of: Many modems do, here is a list of those I know of:
3Com OfficeConnect 56k - 3Com OfficeConnect 56k
3Com Voice FaxModem Pro - 3Com Voice FaxModem Pro
3Com Sportster - 3Com Sportster
MultiTech MultiModem 56k - MultiTech MultiModem 56k
Zoom 2986L FaxModem - Zoom 2986L FaxModem
Compaq 56k FaxModem - Compaq 56k FaxModem
ELSA Microlink 56k - ELSA Microlink 56k
I know of one ISDN TA that does work with the acm driver: I know of one ISDN TA that does work with the acm driver:
3Com USR ISDN Pro TA - 3Com USR ISDN Pro TA
Some cell phones also connect via USB. I know the following phones work: Some cell phones also connect via USB. I know the following phones work:
SonyEricsson K800i - SonyEricsson K800i
Unfortunately many modems and most ISDN TAs use proprietary interfaces and Unfortunately many modems and most ISDN TAs use proprietary interfaces and
thus won't work with this drivers. Check for ACM compliance before buying. thus won't work with this drivers. Check for ACM compliance before buying.
To use the modems you need these modules loaded: To use the modems you need these modules loaded::
usbcore.ko usbcore.ko
uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko
cdc-acm.ko cdc-acm.ko
After that, the modem[s] should be accessible. You should be able to use After that, the modem[s] should be accessible. You should be able to use
minicom, ppp and mgetty with them. minicom, ppp and mgetty with them.
2. Verifying that it works 2. Verifying that it works
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
The first step would be to check /sys/kernel/debug/usb/devices, it should look
like this: The first step would be to check /sys/kernel/debug/usb/devices, it should look
like this::
T: Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
B: Alloc= 0/900 us ( 0%), #Int= 0, #Iso= 0 T: Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 B: Alloc= 0/900 us ( 0%), #Int= 0, #Iso= 0
P: Vendor=0000 ProdID=0000 Rev= 0.00 D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
S: Product=USB UHCI Root Hub P: Vendor=0000 ProdID=0000 Rev= 0.00
S: SerialNumber=6800 S: Product=USB UHCI Root Hub
C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA S: SerialNumber=6800
I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA
E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms
D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2 T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=01 Dev#= 2 Spd=12 MxCh= 0
P: Vendor=04c1 ProdID=008f Rev= 2.07 D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2
S: Manufacturer=3Com Inc. P: Vendor=04c1 ProdID=008f Rev= 2.07
S: Product=3Com U.S. Robotics Pro ISDN TA S: Manufacturer=3Com Inc.
S: SerialNumber=UFT53A49BVT7 S: Product=3Com U.S. Robotics Pro ISDN TA
C: #Ifs= 1 Cfg#= 1 Atr=60 MxPwr= 0mA S: SerialNumber=UFT53A49BVT7
I: If#= 0 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=acm C: #Ifs= 1 Cfg#= 1 Atr=60 MxPwr= 0mA
E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms I: If#= 0 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=acm
E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms
E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms
C:* #Ifs= 2 Cfg#= 2 Atr=60 MxPwr= 0mA E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms
I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm C:* #Ifs= 2 Cfg#= 2 Atr=60 MxPwr= 0mA
E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms
E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms
E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms
The presence of these three lines (and the Cls= 'comm' and 'data' classes) The presence of these three lines (and the Cls= 'comm' and 'data' classes)
is important, it means it's an ACM device. The Driver=acm means the acm is important, it means it's an ACM device. The Driver=acm means the acm
driver is used for the device. If you see only Cls=ff(vend.) then you're out driver is used for the device. If you see only Cls=ff(vend.) then you're out
of luck, you have a device with vendor specific-interface. of luck, you have a device with vendor specific-interface::
D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2 D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2
I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
In the system log you should see: In the system log you should see::
usb.c: USB new device connect, assigned device number 2 usb.c: USB new device connect, assigned device number 2
usb.c: kmalloc IF c7691fa0, numif 1 usb.c: kmalloc IF c7691fa0, numif 1
usb.c: kmalloc IF c7b5f3e0, numif 2 usb.c: kmalloc IF c7b5f3e0, numif 2
usb.c: skipped 4 class/vendor specific interface descriptors usb.c: skipped 4 class/vendor specific interface descriptors
usb.c: new device strings: Mfr=1, Product=2, SerialNumber=3 usb.c: new device strings: Mfr=1, Product=2, SerialNumber=3
usb.c: USB device number 2 default language ID 0x409 usb.c: USB device number 2 default language ID 0x409
Manufacturer: 3Com Inc. Manufacturer: 3Com Inc.
Product: 3Com U.S. Robotics Pro ISDN TA Product: 3Com U.S. Robotics Pro ISDN TA
SerialNumber: UFT53A49BVT7 SerialNumber: UFT53A49BVT7
acm.c: probing config 1 acm.c: probing config 1
acm.c: probing config 2 acm.c: probing config 2
ttyACM0: USB ACM device ttyACM0: USB ACM device
acm.c: acm_control_msg: rq: 0x22 val: 0x0 len: 0x0 result: 0 acm.c: acm_control_msg: rq: 0x22 val: 0x0 len: 0x0 result: 0
acm.c: acm_control_msg: rq: 0x20 val: 0x0 len: 0x7 result: 7 acm.c: acm_control_msg: rq: 0x20 val: 0x0 len: 0x7 result: 7
usb.c: acm driver claimed interface c7b5f3e0 usb.c: acm driver claimed interface c7b5f3e0
usb.c: acm driver claimed interface c7b5f3f8 usb.c: acm driver claimed interface c7b5f3f8
usb.c: acm driver claimed interface c7691fa0 usb.c: acm driver claimed interface c7691fa0
If all this seems to be OK, fire up minicom and set it to talk to the ttyACM If all this seems to be OK, fire up minicom and set it to talk to the ttyACM
device and try typing 'at'. If it responds with 'OK', then everything is device and try typing 'at'. If it responds with 'OK', then everything is
......
Documentation/usb/authorization.txt
View file @ d80b5005
==============================================================
Authorizing (or not) your USB devices to connect to the system Authorizing (or not) your USB devices to connect to the system
==============================================================
(C) 2007 Inaky Perez-Gonzalez <inaky@linux.intel.com> Intel Corporation Copyright (C) 2007 Inaky Perez-Gonzalez <inaky@linux.intel.com> Intel Corporation
This feature allows you to control if a USB device can be used (or This feature allows you to control if a USB device can be used (or
not) in a system. This feature will allow you to implement a lock-down not) in a system. This feature will allow you to implement a lock-down
...@@ -12,24 +13,25 @@ its interfaces are immediately made available to the users. With this ...@@ -12,24 +13,25 @@ its interfaces are immediately made available to the users. With this
modification, only if root authorizes the device to be configured will modification, only if root authorizes the device to be configured will
then it be possible to use it. then it be possible to use it.
Usage: Usage
=====
Authorize a device to connect: Authorize a device to connect::
$ echo 1 > /sys/bus/usb/devices/DEVICE/authorized $ echo 1 > /sys/bus/usb/devices/DEVICE/authorized
Deauthorize a device: De-authorize a device::
$ echo 0 > /sys/bus/usb/devices/DEVICE/authorized $ echo 0 > /sys/bus/usb/devices/DEVICE/authorized
Set new devices connected to hostX to be deauthorized by default (ie: Set new devices connected to hostX to be deauthorized by default (ie:
lock down): lock down)::
$ echo 0 > /sys/bus/usb/devices/usbX/authorized_default $ echo 0 > /sys/bus/usb/devices/usbX/authorized_default
Remove the lock down: Remove the lock down::
$ echo 1 > /sys/bus/usb/devices/usbX/authorized_default $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default
By default, Wired USB devices are authorized by default to By default, Wired USB devices are authorized by default to
connect. Wireless USB hosts deauthorize by default all new connected connect. Wireless USB hosts deauthorize by default all new connected
...@@ -40,21 +42,21 @@ USB ports. ...@@ -40,21 +42,21 @@ USB ports.
Example system lockdown (lame) Example system lockdown (lame)
----------------------- ------------------------------
Imagine you want to implement a lockdown so only devices of type XYZ Imagine you want to implement a lockdown so only devices of type XYZ
can be connected (for example, it is a kiosk machine with a visible can be connected (for example, it is a kiosk machine with a visible
USB port): USB port)::
boot up boot up
rc.local -> rc.local ->
for host in /sys/bus/usb/devices/usb* for host in /sys/bus/usb/devices/usb*
do do
echo 0 > $host/authorized_default echo 0 > $host/authorized_default
done done
Hookup an script to udev, for new USB devices Hookup an script to udev, for new USB devices::
if device_is_my_type $DEV if device_is_my_type $DEV
then then
...@@ -67,10 +69,10 @@ checking if the class, type and protocol match something is the worse ...@@ -67,10 +69,10 @@ checking if the class, type and protocol match something is the worse
security verification you can make (or the best, for someone willing security verification you can make (or the best, for someone willing
to break it). If you need something secure, use crypto and Certificate to break it). If you need something secure, use crypto and Certificate
Authentication or stuff like that. Something simple for an storage key Authentication or stuff like that. Something simple for an storage key
could be: could be::
function device_is_my_type() function device_is_my_type()
{ {
echo 1 > authorized # temporarily authorize it echo 1 > authorized # temporarily authorize it
# FIXME: make sure none can mount it # FIXME: make sure none can mount it
mount DEVICENODE /mntpoint mount DEVICENODE /mntpoint
...@@ -83,7 +85,7 @@ function device_is_my_type() ...@@ -83,7 +85,7 @@ function device_is_my_type()
else else
echo 0 > authorized echo 0 > authorized
fi fi
} }
Of course, this is lame, you'd want to do a real certificate Of course, this is lame, you'd want to do a real certificate
...@@ -95,30 +97,35 @@ welcome. ...@@ -95,30 +97,35 @@ welcome.
Interface authorization Interface authorization
----------------------- -----------------------
There is a similar approach to allow or deny specific USB interfaces. There is a similar approach to allow or deny specific USB interfaces.
That allows to block only a subset of an USB device. That allows to block only a subset of an USB device.
Authorize an interface: Authorize an interface::
$ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized
$ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized
Deauthorize an interface: Deauthorize an interface::
$ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized
$ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized
The default value for new interfaces The default value for new interfaces
on a particular USB bus can be changed, too. on a particular USB bus can be changed, too.
Allow interfaces per default: Allow interfaces per default::
$ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default
$ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default
Deny interfaces per default::
Deny interfaces per default: $ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default
$ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default
Per default the interface_authorized_default bit is 1. Per default the interface_authorized_default bit is 1.
So all interfaces would authorized per default. So all interfaces would authorized per default.
Note: Note:
If a deauthorized interface will be authorized so the driver probing must If a deauthorized interface will be authorized so the driver probing must
be triggered manually by writing INTERFACE to /sys/bus/usb/drivers_probe be triggered manually by writing INTERFACE to /sys/bus/usb/drivers_probe
For drivers that need multiple interfaces all needed interfaces should be For drivers that need multiple interfaces all needed interfaces should be
authorized first. After that the drivers should be probed. authorized first. After that the drivers should be probed.
......
Documentation/usb/chipidea.txt
View file @ d80b5005
==============================================
ChipIdea Highspeed Dual Role Controller Driver
==============================================
1. How to test OTG FSM(HNP and SRP) 1. How to test OTG FSM(HNP and SRP)
----------------------------------- -----------------------------------
To show how to demo OTG HNP and SRP functions via sys input files To show how to demo OTG HNP and SRP functions via sys input files
with 2 Freescale i.MX6Q sabre SD boards. with 2 Freescale i.MX6Q sabre SD boards.
1.1 How to enable OTG FSM 1.1 How to enable OTG FSM
--------------------------------------- -------------------------
1.1.1 Select CONFIG_USB_OTG_FSM in menuconfig, rebuild kernel 1.1.1 Select CONFIG_USB_OTG_FSM in menuconfig, rebuild kernel
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Image and modules. If you want to check some internal Image and modules. If you want to check some internal
variables for otg fsm, mount debugfs, there are 2 files variables for otg fsm, mount debugfs, there are 2 files
which can show otg fsm variables and some controller registers value: which can show otg fsm variables and some controller registers value::
cat /sys/kernel/debug/ci_hdrc.0/otg
cat /sys/kernel/debug/ci_hdrc.0/registers cat /sys/kernel/debug/ci_hdrc.0/otg
cat /sys/kernel/debug/ci_hdrc.0/registers
1.1.2 Add below entries in your dts file for your controller node 1.1.2 Add below entries in your dts file for your controller node
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
otg-rev = <0x0200>; otg-rev = <0x0200>;
adp-disable; adp-disable;
1.2 Test operations 1.2 Test operations
------------------- -------------------
1) Power up 2 Freescale i.MX6Q sabre SD boards with gadget class driver loaded 1) Power up 2 Freescale i.MX6Q sabre SD boards with gadget class driver loaded
(e.g. g_mass_storage). (e.g. g_mass_storage).
...@@ -26,18 +41,23 @@ cat /sys/kernel/debug/ci_hdrc.0/registers ...@@ -26,18 +41,23 @@ cat /sys/kernel/debug/ci_hdrc.0/registers
The A-device(with micro A plug inserted) should enumerate B-device. The A-device(with micro A plug inserted) should enumerate B-device.
3) Role switch 3) Role switch
On B-device:
On B-device::
echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
B-device should take host role and enumerate A-device. B-device should take host role and enumerate A-device.
4) A-device switch back to host. 4) A-device switch back to host.
On B-device:
On B-device::
echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
or, by introducing HNP polling, B-Host can know when A-peripheral wish or, by introducing HNP polling, B-Host can know when A-peripheral wish
to be host role, so this role switch also can be trigged in A-peripheral to be host role, so this role switch also can be trigged in A-peripheral
side by answering the polling from B-Host, this can be done on A-device: side by answering the polling from B-Host, this can be done on A-device::
echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req
A-device should switch back to host and enumerate B-device. A-device should switch back to host and enumerate B-device.
...@@ -49,22 +69,30 @@ cat /sys/kernel/debug/ci_hdrc.0/registers ...@@ -49,22 +69,30 @@ cat /sys/kernel/debug/ci_hdrc.0/registers
A-device should NOT enumerate B-device. A-device should NOT enumerate B-device.
if A-device wants to use bus: if A-device wants to use bus:
On A-device:
On A-device::
echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop
echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req
if B-device wants to use bus: if B-device wants to use bus:
On B-device:
On B-device::
echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
7) A-device power down the bus. 7) A-device power down the bus.
On A-device:
On A-device::
echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop
A-device should disconnect with B-device and power down the bus. A-device should disconnect with B-device and power down the bus.
8) B-device does data pulse for SRP. 8) B-device does data pulse for SRP.
On B-device:
On B-device::
echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
A-device should resume usb bus and enumerate B-device. A-device should resume usb bus and enumerate B-device.
...@@ -75,22 +103,31 @@ cat /sys/kernel/debug/ci_hdrc.0/registers ...@@ -75,22 +103,31 @@ cat /sys/kernel/debug/ci_hdrc.0/registers
July 27, 2012 Revision 2.0 version 1.1a" July 27, 2012 Revision 2.0 version 1.1a"
2. How to enable USB as system wakeup source 2. How to enable USB as system wakeup source
----------------------------------- --------------------------------------------
Below is the example for how to enable USB as system wakeup source Below is the example for how to enable USB as system wakeup source
at imx6 platform. at imx6 platform.
2.1 Enable core's wakeup 2.1 Enable core's wakeup::
echo enabled > /sys/bus/platform/devices/ci_hdrc.0/power/wakeup
2.2 Enable glue layer's wakeup echo enabled > /sys/bus/platform/devices/ci_hdrc.0/power/wakeup
echo enabled > /sys/bus/platform/devices/2184000.usb/power/wakeup
2.3 Enable PHY's wakeup (optional) 2.2 Enable glue layer's wakeup::
echo enabled > /sys/bus/platform/devices/20c9000.usbphy/power/wakeup
2.4 Enable roothub's wakeup echo enabled > /sys/bus/platform/devices/2184000.usb/power/wakeup
echo enabled > /sys/bus/usb/devices/usb1/power/wakeup
2.5 Enable related device's wakeup 2.3 Enable PHY's wakeup (optional)::
echo enabled > /sys/bus/usb/devices/1-1/power/wakeup
echo enabled > /sys/bus/platform/devices/20c9000.usbphy/power/wakeup
2.4 Enable roothub's wakeup::
echo enabled > /sys/bus/usb/devices/usb1/power/wakeup
2.5 Enable related device's wakeup::
echo enabled > /sys/bus/usb/devices/1-1/power/wakeup
If the system has only one usb port, and you want usb wakeup at this port, you If the system has only one usb port, and you want usb wakeup at this port, you
can use below script to enable usb wakeup. can use below script to enable usb wakeup::
for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done;
for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done;
Documentation/usb/dwc3.txt
View file @ d80b5005
===========
DWC3 driver
===========
TODO
~~~~
TODO
~~~~~~
Please pick something while reading :) Please pick something while reading :)
- Convert interrupt handler to per-ep-thread-irq - Convert interrupt handler to per-ep-thread-irq
...@@ -9,6 +14,7 @@ Please pick something while reading :) ...@@ -9,6 +14,7 @@ Please pick something while reading :)
until the command completes which is bad. until the command completes which is bad.
Implementation idea: Implementation idea:
- dwc core implements a demultiplexing irq chip for interrupts per - dwc core implements a demultiplexing irq chip for interrupts per
endpoint. The interrupt numbers are allocated during probe and belong endpoint. The interrupt numbers are allocated during probe and belong
to the device. If MSI provides per-endpoint interrupt this dummy to the device. If MSI provides per-endpoint interrupt this dummy
...@@ -19,6 +25,7 @@ Please pick something while reading :) ...@@ -19,6 +25,7 @@ Please pick something while reading :)
- dwc3_send_gadget_ep_cmd() will sleep in wait_for_completion_timeout() - dwc3_send_gadget_ep_cmd() will sleep in wait_for_completion_timeout()
until the command completes. until the command completes.
- the interrupt handler is split into the following pieces: - the interrupt handler is split into the following pieces:
- primary handler of the device - primary handler of the device
goes through every event and calls generic_handle_irq() for event goes through every event and calls generic_handle_irq() for event
it. On return from generic_handle_irq() in acknowledges the event it. On return from generic_handle_irq() in acknowledges the event
...@@ -40,6 +47,7 @@ Please pick something while reading :) ...@@ -40,6 +47,7 @@ Please pick something while reading :)
for command completion. for command completion.
Latency: Latency:
There should be no increase in latency since the interrupt-thread has a There should be no increase in latency since the interrupt-thread has a
high priority and will be run before an average task in user land high priority and will be run before an average task in user land
(except the user changed priorities). (except the user changed priorities).
Documentation/usb/ehci.txt
View file @ d80b5005
===========
EHCI driver
===========
27-Dec-2002 27-Dec-2002
The EHCI driver is used to talk to high speed USB 2.0 devices using The EHCI driver is used to talk to high speed USB 2.0 devices using
...@@ -40,7 +44,8 @@ APIs exposed to USB device drivers. ...@@ -40,7 +44,8 @@ APIs exposed to USB device drivers.
<dbrownell@users.sourceforge.net> <dbrownell@users.sourceforge.net>
FUNCTIONALITY Functionality
=============
This driver is regularly tested on x86 hardware, and has also been This driver is regularly tested on x86 hardware, and has also been
used on PPC hardware so big/little endianness issues should be gone. used on PPC hardware so big/little endianness issues should be gone.
...@@ -48,6 +53,7 @@ It's believed to do all the right PCI magic so that I/O works even on ...@@ -48,6 +53,7 @@ It's believed to do all the right PCI magic so that I/O works even on
systems with interesting DMA mapping issues. systems with interesting DMA mapping issues.
Transfer Types Transfer Types
--------------
At this writing the driver should comfortably handle all control, bulk, At this writing the driver should comfortably handle all control, bulk,
and interrupt transfers, including requests to USB 1.1 devices through and interrupt transfers, including requests to USB 1.1 devices through
...@@ -63,6 +69,7 @@ since EHCI represents these with a different data structure. So for now, ...@@ -63,6 +69,7 @@ since EHCI represents these with a different data structure. So for now,
most USB audio and video devices can't be connected to high speed buses. most USB audio and video devices can't be connected to high speed buses.
Driver Behavior Driver Behavior
---------------
Transfers of all types can be queued. This means that control transfers Transfers of all types can be queued. This means that control transfers
from a driver on one interface (or through usbfs) won't interfere with from a driver on one interface (or through usbfs) won't interfere with
...@@ -83,14 +90,15 @@ limits on the number of periodic transactions that can be scheduled, ...@@ -83,14 +90,15 @@ limits on the number of periodic transactions that can be scheduled,
and prevent use of polling intervals of less than one frame. and prevent use of polling intervals of less than one frame.
USE BY Use by
======
Assuming you have an EHCI controller (on a PCI card or motherboard) Assuming you have an EHCI controller (on a PCI card or motherboard)
and have compiled this driver as a module, load this like: and have compiled this driver as a module, load this like::
# modprobe ehci-hcd # modprobe ehci-hcd
and remove it by: and remove it by::
# rmmod ehci-hcd # rmmod ehci-hcd
...@@ -112,13 +120,16 @@ If you're using this driver on a 2.5 kernel, and you've enabled USB ...@@ -112,13 +120,16 @@ If you're using this driver on a 2.5 kernel, and you've enabled USB
debugging support, you'll see three files in the "sysfs" directory for debugging support, you'll see three files in the "sysfs" directory for
any EHCI controller: any EHCI controller:
"async" dumps the asynchronous schedule, used for control "async"
dumps the asynchronous schedule, used for control
and bulk transfers. Shows each active qh and the qtds and bulk transfers. Shows each active qh and the qtds
pending, usually one qtd per urb. (Look at it with pending, usually one qtd per urb. (Look at it with
usb-storage doing disk I/O; watch the request queues!) usb-storage doing disk I/O; watch the request queues!)
"periodic" dumps the periodic schedule, used for interrupt "periodic"
dumps the periodic schedule, used for interrupt
and isochronous transfers. Doesn't show qtds. and isochronous transfers. Doesn't show qtds.
"registers" show controller register state, and "registers"
show controller register state, and
The contents of those files can help identify driver problems. The contents of those files can help identify driver problems.
...@@ -136,7 +147,8 @@ transaction translators are in use; some drivers have been seen to behave ...@@ -136,7 +147,8 @@ transaction translators are in use; some drivers have been seen to behave
badly when they see different faults than OHCI or UHCI report. badly when they see different faults than OHCI or UHCI report.
PERFORMANCE Performance
===========
USB 2.0 throughput is gated by two main factors: how fast the host USB 2.0 throughput is gated by two main factors: how fast the host
controller can process requests, and how fast devices can respond to controller can process requests, and how fast devices can respond to
...@@ -156,6 +168,7 @@ hardware and device driver software allow it. Periodic transfer modes ...@@ -156,6 +168,7 @@ hardware and device driver software allow it. Periodic transfer modes
approach the quoted 480 MBit/sec transfer rate. approach the quoted 480 MBit/sec transfer rate.
Hardware Performance Hardware Performance
--------------------
At this writing, individual USB 2.0 devices tend to max out at around At this writing, individual USB 2.0 devices tend to max out at around
20 MByte/sec transfer rates. This is of course subject to change; 20 MByte/sec transfer rates. This is of course subject to change;
...@@ -183,6 +196,7 @@ you issue a control or bulk request you can often expect to learn that ...@@ -183,6 +196,7 @@ you issue a control or bulk request you can often expect to learn that
it completed in less than 250 usec (depending on transfer size). it completed in less than 250 usec (depending on transfer size).
Software Performance Software Performance
--------------------
To get even 20 MByte/sec transfer rates, Linux-USB device drivers will To get even 20 MByte/sec transfer rates, Linux-USB device drivers will
need to keep the EHCI queue full. That means issuing large requests, need to keep the EHCI queue full. That means issuing large requests,
...@@ -206,9 +220,11 @@ mapping (which might apply an IOMMU) and IRQ reduction, all of which will ...@@ -206,9 +220,11 @@ mapping (which might apply an IOMMU) and IRQ reduction, all of which will
help make high speed transfers run as fast as they can. help make high speed transfers run as fast as they can.
TBD: Interrupt and ISO transfer performance issues. Those periodic TBD:
transfers are fully scheduled, so the main issue is likely to be how Interrupt and ISO transfer performance issues. Those periodic
to trigger "high bandwidth" modes. transfers are fully scheduled, so the main issue is likely to be how
to trigger "high bandwidth" modes.
TBD: More than standard 80% periodic bandwidth allocation is possible TBD:
through sysfs uframe_periodic_max parameter. Describe that. More than standard 80% periodic bandwidth allocation is possible
through sysfs uframe_periodic_max parameter. Describe that.
Documentation/usb/functionfs.txt
View file @ d80b5005
*How FunctionFS works* ====================
How FunctionFS works
====================
From kernel point of view it is just a composite function with some From kernel point of view it is just a composite function with some
unique behaviour. It may be added to an USB configuration only after unique behaviour. It may be added to an USB configuration only after
...@@ -38,13 +40,13 @@ when mounting. ...@@ -38,13 +40,13 @@ when mounting.
One can imagine a gadget that has an Ethernet, MTP and HID interfaces One can imagine a gadget that has an Ethernet, MTP and HID interfaces
where the last two are implemented via FunctionFS. On user space where the last two are implemented via FunctionFS. On user space
level it would look like this: level it would look like this::
$ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid $ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid
$ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp $ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp
$ ( cd /dev/ffs-mtp && mtp-daemon ) & $ ( cd /dev/ffs-mtp && mtp-daemon ) &
$ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid $ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid
$ ( cd /dev/ffs-hid && hid-daemon ) & $ ( cd /dev/ffs-hid && hid-daemon ) &
On kernel level the gadget checks ffs_data->dev_name to identify On kernel level the gadget checks ffs_data->dev_name to identify
whether it's FunctionFS designed for MTP ("mtp") or HID ("hid"). whether it's FunctionFS designed for MTP ("mtp") or HID ("hid").
...@@ -64,4 +66,3 @@ have been written to their ep0's. ...@@ -64,4 +66,3 @@ have been written to their ep0's.
Conversely, the gadget is unregistered after the first USB function Conversely, the gadget is unregistered after the first USB function
closes its endpoints. closes its endpoints.
Documentation/usb/gadget-testing.txt
View file @ d80b5005
This diff is collapsed.
Documentation/usb/gadget_configfs.txt
View file @ d80b5005
This diff is collapsed.
Documentation/usb/gadget_hid.txt
View file @ d80b5005
===========================
Linux USB HID gadget driver Linux USB HID gadget driver
===========================
Introduction Introduction
============
The HID Gadget driver provides emulation of USB Human Interface The HID Gadget driver provides emulation of USB Human Interface
Devices (HID). The basic HID handling is done in the kernel, Devices (HID). The basic HID handling is done in the kernel,
and HID reports can be sent/received through I/O on the and HID reports can be sent/received through I/O on the
/dev/hidgX character devices. /dev/hidgX character devices.
For more details about HID, see the developer page on For more details about HID, see the developer page on
http://www.usb.org/developers/hidpage/ http://www.usb.org/developers/hidpage/
Configuration Configuration
=============
g_hid is a platform driver, so to use it you need to add g_hid is a platform driver, so to use it you need to add
struct platform_device(s) to your platform code defining the struct platform_device(s) to your platform code defining the
HID function descriptors you want to use - E.G. something HID function descriptors you want to use - E.G. something
like: like::
#include <linux/platform_device.h> #include <linux/platform_device.h>
#include <linux/usb/g_hid.h> #include <linux/usb/g_hid.h>
/* hid descriptor for a keyboard */ /* hid descriptor for a keyboard */
static struct hidg_func_descriptor my_hid_data = { static struct hidg_func_descriptor my_hid_data = {
.subclass = 0, /* No subclass */ .subclass = 0, /* No subclass */
.protocol = 1, /* Keyboard */ .protocol = 1, /* Keyboard */
.report_length = 8, .report_length = 8,
...@@ -61,85 +64,87 @@ static struct hidg_func_descriptor my_hid_data = { ...@@ -61,85 +64,87 @@ static struct hidg_func_descriptor my_hid_data = {
0x81, 0x00, /* INPUT (Data,Ary,Abs) */ 0x81, 0x00, /* INPUT (Data,Ary,Abs) */
0xc0 /* END_COLLECTION */ 0xc0 /* END_COLLECTION */
} }
}; };
static struct platform_device my_hid = { static struct platform_device my_hid = {
.name = "hidg", .name = "hidg",
.id = 0, .id = 0,
.num_resources = 0, .num_resources = 0,
.resource = 0, .resource = 0,
.dev.platform_data = &my_hid_data, .dev.platform_data = &my_hid_data,
}; };
You can add as many HID functions as you want, only limited by You can add as many HID functions as you want, only limited by
the amount of interrupt endpoints your gadget driver supports. the amount of interrupt endpoints your gadget driver supports.
Configuration with configfs Configuration with configfs
===========================
Instead of adding fake platform devices and drivers in order to pass Instead of adding fake platform devices and drivers in order to pass
some data to the kernel, if HID is a part of a gadget composed with some data to the kernel, if HID is a part of a gadget composed with
configfs the hidg_func_descriptor.report_desc is passed to the kernel configfs the hidg_func_descriptor.report_desc is passed to the kernel
by writing the appropriate stream of bytes to a configfs attribute. by writing the appropriate stream of bytes to a configfs attribute.
Send and receive HID reports Send and receive HID reports
============================
HID reports can be sent/received using read/write on the HID reports can be sent/received using read/write on the
/dev/hidgX character devices. See below for an example program /dev/hidgX character devices. See below for an example program
to do this. to do this.
hid_gadget_test is a small interactive program to test the HID hid_gadget_test is a small interactive program to test the HID
gadget driver. To use, point it at a hidg device and set the gadget driver. To use, point it at a hidg device and set the
device type (keyboard / mouse / joystick) - E.G.: device type (keyboard / mouse / joystick) - E.G.::
# hid_gadget_test /dev/hidg0 keyboard # hid_gadget_test /dev/hidg0 keyboard
You are now in the prompt of hid_gadget_test. You can type any You are now in the prompt of hid_gadget_test. You can type any
combination of options and values. Available options and combination of options and values. Available options and
values are listed at program start. In keyboard mode you can values are listed at program start. In keyboard mode you can
send up to six values. send up to six values.
For example type: g i s t r --left-shift For example type: g i s t r --left-shift
Hit return and the corresponding report will be sent by the Hit return and the corresponding report will be sent by the
HID gadget. HID gadget.
Another interesting example is the caps lock test. Type Another interesting example is the caps lock test. Type
--caps-lock and hit return. A report is then sent by the --caps-lock and hit return. A report is then sent by the
gadget and you should receive the host answer, corresponding gadget and you should receive the host answer, corresponding
to the caps lock LED status. to the caps lock LED status::
--caps-lock --caps-lock
recv report:2 recv report:2
With this command: With this command::
# hid_gadget_test /dev/hidg1 mouse # hid_gadget_test /dev/hidg1 mouse
You can test the mouse emulation. Values are two signed numbers. You can test the mouse emulation. Values are two signed numbers.
Sample code Sample code::
/* hid_gadget_test */ /* hid_gadget_test */
#include <pthread.h> #include <pthread.h>
#include <string.h> #include <string.h>
#include <stdio.h> #include <stdio.h>
#include <ctype.h> #include <ctype.h>
#include <fcntl.h> #include <fcntl.h>
#include <errno.h> #include <errno.h>
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
#include <unistd.h> #include <unistd.h>
#define BUF_LEN 512 #define BUF_LEN 512
struct options { struct options {
const char *opt; const char *opt;
unsigned char val; unsigned char val;
}; };
static struct options kmod[] = { static struct options kmod[] = {
{.opt = "--left-ctrl", .val = 0x01}, {.opt = "--left-ctrl", .val = 0x01},
{.opt = "--right-ctrl", .val = 0x10}, {.opt = "--right-ctrl", .val = 0x10},
{.opt = "--left-shift", .val = 0x02}, {.opt = "--left-shift", .val = 0x02},
...@@ -149,9 +154,9 @@ static struct options kmod[] = { ...@@ -149,9 +154,9 @@ static struct options kmod[] = {
{.opt = "--left-meta", .val = 0x08}, {.opt = "--left-meta", .val = 0x08},
{.opt = "--right-meta", .val = 0x80}, {.opt = "--right-meta", .val = 0x80},
{.opt = NULL} {.opt = NULL}
}; };
static struct options kval[] = { static struct options kval[] = {
{.opt = "--return", .val = 0x28}, {.opt = "--return", .val = 0x28},
{.opt = "--esc", .val = 0x29}, {.opt = "--esc", .val = 0x29},
{.opt = "--bckspc", .val = 0x2a}, {.opt = "--bckspc", .val = 0x2a},
...@@ -183,10 +188,10 @@ static struct options kval[] = { ...@@ -183,10 +188,10 @@ static struct options kval[] = {
{.opt = "--up", .val = 0x52}, {.opt = "--up", .val = 0x52},
{.opt = "--num-lock", .val = 0x53}, {.opt = "--num-lock", .val = 0x53},
{.opt = NULL} {.opt = NULL}
}; };
int keyboard_fill_report(char report[8], char buf[BUF_LEN], int *hold) int keyboard_fill_report(char report[8], char buf[BUF_LEN], int *hold)
{ {
char *tok = strtok(buf, " "); char *tok = strtok(buf, " ");
int key = 0; int key = 0;
int i = 0; int i = 0;
...@@ -229,17 +234,17 @@ int keyboard_fill_report(char report[8], char buf[BUF_LEN], int *hold) ...@@ -229,17 +234,17 @@ int keyboard_fill_report(char report[8], char buf[BUF_LEN], int *hold)
fprintf(stderr, "unknown option: %s\n", tok); fprintf(stderr, "unknown option: %s\n", tok);
} }
return 8; return 8;
} }
static struct options mmod[] = { static struct options mmod[] = {
{.opt = "--b1", .val = 0x01}, {.opt = "--b1", .val = 0x01},
{.opt = "--b2", .val = 0x02}, {.opt = "--b2", .val = 0x02},
{.opt = "--b3", .val = 0x04}, {.opt = "--b3", .val = 0x04},
{.opt = NULL} {.opt = NULL}
}; };
int mouse_fill_report(char report[8], char buf[BUF_LEN], int *hold) int mouse_fill_report(char report[8], char buf[BUF_LEN], int *hold)
{ {
char *tok = strtok(buf, " "); char *tok = strtok(buf, " ");
int mvt = 0; int mvt = 0;
int i = 0; int i = 0;
...@@ -274,9 +279,9 @@ int mouse_fill_report(char report[8], char buf[BUF_LEN], int *hold) ...@@ -274,9 +279,9 @@ int mouse_fill_report(char report[8], char buf[BUF_LEN], int *hold)
fprintf(stderr, "unknown option: %s\n", tok); fprintf(stderr, "unknown option: %s\n", tok);
} }
return 3; return 3;
} }
static struct options jmod[] = { static struct options jmod[] = {
{.opt = "--b1", .val = 0x10}, {.opt = "--b1", .val = 0x10},
{.opt = "--b2", .val = 0x20}, {.opt = "--b2", .val = 0x20},
{.opt = "--b3", .val = 0x40}, {.opt = "--b3", .val = 0x40},
...@@ -287,10 +292,10 @@ static struct options jmod[] = { ...@@ -287,10 +292,10 @@ static struct options jmod[] = {
{.opt = "--hat4", .val = 0x03}, {.opt = "--hat4", .val = 0x03},
{.opt = "--hatneutral", .val = 0x04}, {.opt = "--hatneutral", .val = 0x04},
{.opt = NULL} {.opt = NULL}
}; };
int joystick_fill_report(char report[8], char buf[BUF_LEN], int *hold) int joystick_fill_report(char report[8], char buf[BUF_LEN], int *hold)
{ {
char *tok = strtok(buf, " "); char *tok = strtok(buf, " ");
int mvt = 0; int mvt = 0;
int i = 0; int i = 0;
...@@ -326,10 +331,10 @@ int joystick_fill_report(char report[8], char buf[BUF_LEN], int *hold) ...@@ -326,10 +331,10 @@ int joystick_fill_report(char report[8], char buf[BUF_LEN], int *hold)
fprintf(stderr, "unknown option: %s\n", tok); fprintf(stderr, "unknown option: %s\n", tok);
} }
return 4; return 4;
} }
void print_options(char c) void print_options(char c)
{ {
int i = 0; int i = 0;
if (c == 'k') { if (c == 'k') {
...@@ -358,10 +363,10 @@ void print_options(char c) ...@@ -358,10 +363,10 @@ void print_options(char c)
" three signed numbers\n" " three signed numbers\n"
"--quit to close\n"); "--quit to close\n");
} }
} }
int main(int argc, const char *argv[]) int main(int argc, const char *argv[])
{ {
const char *filename = NULL; const char *filename = NULL;
int fd = 0; int fd = 0;
char buf[BUF_LEN]; char buf[BUF_LEN];
...@@ -449,4 +454,4 @@ int main(int argc, const char *argv[]) ...@@ -449,4 +454,4 @@ int main(int argc, const char *argv[])
close(fd); close(fd);
return 0; return 0;
} }
Documentation/usb/gadget_multi.txt
View file @ d80b5005
-*- org -*- ==============================
Multifunction Composite Gadget
==============================
* Overview Overview
========
The Multifunction Composite Gadget (or g_multi) is a composite gadget The Multifunction Composite Gadget (or g_multi) is a composite gadget
that makes extensive use of the composite framework to provide that makes extensive use of the composite framework to provide
...@@ -17,13 +20,15 @@ have two configurations -- one with RNDIS and another with CDC ECM[3]. ...@@ -17,13 +20,15 @@ have two configurations -- one with RNDIS and another with CDC ECM[3].
Please note that if you use non-standard configuration (that is enable Please note that if you use non-standard configuration (that is enable
CDC ECM) you may need to change vendor and/or product ID. CDC ECM) you may need to change vendor and/or product ID.
* Host drivers Host drivers
============
To make use of the gadget one needs to make it work on host side -- To make use of the gadget one needs to make it work on host side --
without that there's no hope of achieving anything with the gadget. without that there's no hope of achieving anything with the gadget.
As one might expect, things one need to do very from system to system. As one might expect, things one need to do very from system to system.
** Linux host drivers Linux host drivers
------------------
Since the gadget uses standard composite framework and appears as such Since the gadget uses standard composite framework and appears as such
to Linux host it does not need any additional drivers on Linux host to Linux host it does not need any additional drivers on Linux host
...@@ -34,11 +39,13 @@ This is also true for two configuration set-up with RNDIS ...@@ -34,11 +39,13 @@ This is also true for two configuration set-up with RNDIS
configuration being the first one. Linux host will use the second configuration being the first one. Linux host will use the second
configuration with CDC ECM which should work better under Linux. configuration with CDC ECM which should work better under Linux.
** Windows host drivers Windows host drivers
--------------------
For the gadget to work under Windows two conditions have to be met: For the gadget to work under Windows two conditions have to be met:
*** Detecting as composite gadget Detecting as composite gadget
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
First of all, Windows need to detect the gadget as an USB composite First of all, Windows need to detect the gadget as an USB composite
gadget which on its own have some conditions[4]. If they are met, gadget which on its own have some conditions[4]. If they are met,
...@@ -53,7 +60,8 @@ The only thing to worry is that the gadget has to have a single ...@@ -53,7 +60,8 @@ The only thing to worry is that the gadget has to have a single
configuration so a dual RNDIS and CDC ECM gadget won't work unless you configuration so a dual RNDIS and CDC ECM gadget won't work unless you
create a proper INF -- and of course, if you do submit it! create a proper INF -- and of course, if you do submit it!
*** Installing drivers for each function Installing drivers for each function
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The other, trickier thing is making Windows install drivers for each The other, trickier thing is making Windows install drivers for each
individual function. individual function.
...@@ -63,7 +71,8 @@ implementing USB Mass Storage class and selects appropriate driver. ...@@ -63,7 +71,8 @@ implementing USB Mass Storage class and selects appropriate driver.
Things are harder with RDNIS and CDC ACM. Things are harder with RDNIS and CDC ACM.
**** RNDIS RNDIS
.....
To make Windows select RNDIS drivers for the first function in the To make Windows select RNDIS drivers for the first function in the
gadget, one needs to use the [[file:linux.inf]] file provided with this gadget, one needs to use the [[file:linux.inf]] file provided with this
...@@ -75,11 +84,13 @@ RNDIS was not the first interface. You do not need to worry abut it ...@@ -75,11 +84,13 @@ RNDIS was not the first interface. You do not need to worry abut it
unless you are trying to develop your own gadget in which case watch unless you are trying to develop your own gadget in which case watch
out for this bug. out for this bug.
**** CDC ACM CDC ACM
.......
Similarly, [[file:linux-cdc-acm.inf]] is provided for CDC ACM. Similarly, [[file:linux-cdc-acm.inf]] is provided for CDC ACM.
**** Customising the gadget Customising the gadget
......................
If you intend to hack the g_multi gadget be advised that rearranging If you intend to hack the g_multi gadget be advised that rearranging
functions will obviously change interface numbers for each of the functions will obviously change interface numbers for each of the
...@@ -97,14 +108,16 @@ things don't work as intended before realising Windows have cached ...@@ -97,14 +108,16 @@ things don't work as intended before realising Windows have cached
some drivers information (changing USB port may sometimes help plus some drivers information (changing USB port may sometimes help plus
you might try using USBDeview[8] to remove the phantom device). you might try using USBDeview[8] to remove the phantom device).
**** INF testing INF testing
...........
Provided INF files have been tested on Windows XP SP3, Windows Vista Provided INF files have been tested on Windows XP SP3, Windows Vista
and Windows 7, all 32-bit versions. It should work on 64-bit versions and Windows 7, all 32-bit versions. It should work on 64-bit versions
as well. It most likely won't work on Windows prior to Windows XP as well. It most likely won't work on Windows prior to Windows XP
SP2. SP2.
** Other systems Other systems
-------------
At this moment, drivers for any other systems have not been tested. At this moment, drivers for any other systems have not been tested.
Knowing how MacOS is based on BSD and BSD is an Open Source it is Knowing how MacOS is based on BSD and BSD is an Open Source it is
...@@ -115,7 +128,8 @@ For more exotic systems I have even less to say... ...@@ -115,7 +128,8 @@ For more exotic systems I have even less to say...
Any testing and drivers *are* *welcome*! Any testing and drivers *are* *welcome*!
* Authors Authors
=======
This document has been written by Michal Nazarewicz This document has been written by Michal Nazarewicz
([[mailto:mina86@mina86.com]]). INF files have been hacked with ([[mailto:mina86@mina86.com]]). INF files have been hacked with
...@@ -124,7 +138,8 @@ Xiaofan Chen ([[mailto:xiaofanc@gmail.com]]) basing on the MS RNDIS ...@@ -124,7 +138,8 @@ Xiaofan Chen ([[mailto:xiaofanc@gmail.com]]) basing on the MS RNDIS
template[9], Microchip's CDC ACM INF file and David Brownell's template[9], Microchip's CDC ACM INF file and David Brownell's
([[mailto:dbrownell@users.sourceforge.net]]) original INF files. ([[mailto:dbrownell@users.sourceforge.net]]) original INF files.
* Footnotes Footnotes
=========
[1] Remote Network Driver Interface Specification, [1] Remote Network Driver Interface Specification,
[[http://msdn.microsoft.com/en-us/library/ee484414.aspx]]. [[http://msdn.microsoft.com/en-us/library/ee484414.aspx]].
......
Documentation/usb/gadget_printer.txt
View file @ d80b5005
===============================
Linux USB Printer Gadget Driver
===============================
Linux USB Printer Gadget Driver 06/04/2007
06/04/2007
Copyright (C) 2007 Craig W. Nadler <craig@nadler.us> Copyright (C) 2007 Craig W. Nadler <craig@nadler.us>
GENERAL General
======= =======
This driver may be used if you are writing printer firmware using Linux as This driver may be used if you are writing printer firmware using Linux as
...@@ -29,52 +31,60 @@ user space firmware can read or write this status byte using a device file ...@@ -29,52 +31,60 @@ user space firmware can read or write this status byte using a device file
HOWTO USE THIS DRIVER Howto Use This Driver
===================== =====================
To load the USB device controller driver and the printer gadget driver. The To load the USB device controller driver and the printer gadget driver. The
following example uses the Netchip 2280 USB device controller driver: following example uses the Netchip 2280 USB device controller driver::
modprobe net2280 modprobe net2280
modprobe g_printer modprobe g_printer
The follow command line parameter can be used when loading the printer gadget The follow command line parameter can be used when loading the printer gadget
(ex: modprobe g_printer idVendor=0x0525 idProduct=0xa4a8 ): (ex: modprobe g_printer idVendor=0x0525 idProduct=0xa4a8 ):
idVendor - This is the Vendor ID used in the device descriptor. The default is idVendor
This is the Vendor ID used in the device descriptor. The default is
the Netchip vendor id 0x0525. YOU MUST CHANGE TO YOUR OWN VENDOR ID the Netchip vendor id 0x0525. YOU MUST CHANGE TO YOUR OWN VENDOR ID
BEFORE RELEASING A PRODUCT. If you plan to release a product and don't BEFORE RELEASING A PRODUCT. If you plan to release a product and don't
already have a Vendor ID please see www.usb.org for details on how to already have a Vendor ID please see www.usb.org for details on how to
get one. get one.
idProduct - This is the Product ID used in the device descriptor. The default idProduct
This is the Product ID used in the device descriptor. The default
is 0xa4a8, you should change this to an ID that's not used by any of is 0xa4a8, you should change this to an ID that's not used by any of
your other USB products if you have any. It would be a good idea to your other USB products if you have any. It would be a good idea to
start numbering your products starting with say 0x0001. start numbering your products starting with say 0x0001.
bcdDevice - This is the version number of your product. It would be a good idea bcdDevice
This is the version number of your product. It would be a good idea
to put your firmware version here. to put your firmware version here.
iManufacturer - A string containing the name of the Vendor. iManufacturer
A string containing the name of the Vendor.
iProduct - A string containing the Product Name. iProduct
A string containing the Product Name.
iSerialNum - A string containing the Serial Number. This should be changed for iSerialNum
A string containing the Serial Number. This should be changed for
each unit of your product. each unit of your product.
iPNPstring - The PNP ID string used for this printer. You will want to set iPNPstring
The PNP ID string used for this printer. You will want to set
either on the command line or hard code the PNP ID string used for either on the command line or hard code the PNP ID string used for
your printer product. your printer product.
qlen - The number of 8k buffers to use per endpoint. The default is 10, you qlen
The number of 8k buffers to use per endpoint. The default is 10, you
should tune this for your product. You may also want to tune the should tune this for your product. You may also want to tune the
size of each buffer for your product. size of each buffer for your product.
USING THE EXAMPLE CODE Using The Example Code
====================== ======================
This example code talks to stdout, instead of a print engine. This example code talks to stdout, instead of a print engine.
...@@ -82,22 +92,23 @@ This example code talks to stdout, instead of a print engine. ...@@ -82,22 +92,23 @@ This example code talks to stdout, instead of a print engine.
To compile the test code below: To compile the test code below:
1) save it to a file called prn_example.c 1) save it to a file called prn_example.c
2) compile the code with the follow command: 2) compile the code with the follow command::
gcc prn_example.c -o prn_example gcc prn_example.c -o prn_example
To read printer data from the host to stdout: To read printer data from the host to stdout::
# prn_example -read_data # prn_example -read_data
To write printer data from a file (data_file) to the host: To write printer data from a file (data_file) to the host::
# cat data_file | prn_example -write_data # cat data_file | prn_example -write_data
To get the current printer status for the gadget driver: To get the current printer status for the gadget driver:::
# prn_example -get_status # prn_example -get_status
...@@ -107,60 +118,62 @@ To get the current printer status for the gadget driver: ...@@ -107,60 +118,62 @@ To get the current printer status for the gadget driver:
Printer OK Printer OK
To set printer to Selected/On-line: To set printer to Selected/On-line::
# prn_example -selected # prn_example -selected
To set printer to Not Selected/Off-line: To set printer to Not Selected/Off-line::
# prn_example -not_selected # prn_example -not_selected
To set paper status to paper out: To set paper status to paper out::
# prn_example -paper_out # prn_example -paper_out
To set paper status to paper loaded: To set paper status to paper loaded::
# prn_example -paper_loaded # prn_example -paper_loaded
To set error status to printer OK: To set error status to printer OK::
# prn_example -no_error # prn_example -no_error
To set error status to ERROR: To set error status to ERROR::
# prn_example -error # prn_example -error
EXAMPLE CODE Example Code
============ ============
::
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
#include <fcntl.h> #include <fcntl.h>
#include <linux/poll.h> #include <linux/poll.h>
#include <sys/ioctl.h> #include <sys/ioctl.h>
#include <linux/usb/g_printer.h> #include <linux/usb/g_printer.h>
#define PRINTER_FILE "/dev/g_printer" #define PRINTER_FILE "/dev/g_printer"
#define BUF_SIZE 512 #define BUF_SIZE 512
/* /*
* 'usage()' - Show program usage. * 'usage()' - Show program usage.
*/ */
static void static void
usage(const char *option) /* I - Option string or NULL */ usage(const char *option) /* I - Option string or NULL */
{ {
if (option) { if (option) {
fprintf(stderr,"prn_example: Unknown option \"%s\"!\n", fprintf(stderr,"prn_example: Unknown option \"%s\"!\n",
option); option);
...@@ -186,12 +199,12 @@ usage(const char *option) /* I - Option string or NULL */ ...@@ -186,12 +199,12 @@ usage(const char *option) /* I - Option string or NULL */
fputs("\n\n", stderr); fputs("\n\n", stderr);
exit(1); exit(1);
} }
static int static int
read_printer_data() read_printer_data()
{ {
struct pollfd fd[1]; struct pollfd fd[1];
/* Open device file for printer gadget. */ /* Open device file for printer gadget. */
...@@ -236,12 +249,12 @@ read_printer_data() ...@@ -236,12 +249,12 @@ read_printer_data()
close(fd[0].fd); close(fd[0].fd);
return 0; return 0;
} }
static int static int
write_printer_data() write_printer_data()
{ {
struct pollfd fd[1]; struct pollfd fd[1];
/* Open device file for printer gadget. */ /* Open device file for printer gadget. */
...@@ -295,12 +308,12 @@ write_printer_data() ...@@ -295,12 +308,12 @@ write_printer_data()
close(fd[0].fd); close(fd[0].fd);
return 0; return 0;
} }
static int static int
read_NB_printer_data() read_NB_printer_data()
{ {
int fd; int fd;
static char buf[BUF_SIZE]; static char buf[BUF_SIZE];
int bytes_read; int bytes_read;
...@@ -329,12 +342,12 @@ read_NB_printer_data() ...@@ -329,12 +342,12 @@ read_NB_printer_data()
close(fd); close(fd);
return 0; return 0;
} }
static int static int
get_printer_status() get_printer_status()
{ {
int retval; int retval;
int fd; int fd;
...@@ -357,12 +370,12 @@ get_printer_status() ...@@ -357,12 +370,12 @@ get_printer_status()
close(fd); close(fd);
return(retval); return(retval);
} }
static int static int
set_printer_status(unsigned char buf, int clear_printer_status_bit) set_printer_status(unsigned char buf, int clear_printer_status_bit)
{ {
int retval; int retval;
int fd; int fd;
...@@ -397,12 +410,12 @@ set_printer_status(unsigned char buf, int clear_printer_status_bit) ...@@ -397,12 +410,12 @@ set_printer_status(unsigned char buf, int clear_printer_status_bit)
close(fd); close(fd);
return 0; return 0;
} }
static int static int
display_printer_status() display_printer_status()
{ {
char printer_status; char printer_status;
printer_status = get_printer_status(); printer_status = get_printer_status();
...@@ -429,12 +442,12 @@ display_printer_status() ...@@ -429,12 +442,12 @@ display_printer_status()
} }
return(0); return(0);
} }
int int
main(int argc, char *argv[]) main(int argc, char *argv[])
{ {
int i; /* Looping var */ int i; /* Looping var */
int retval = 0; int retval = 0;
...@@ -507,4 +520,4 @@ main(int argc, char *argv[]) ...@@ -507,4 +520,4 @@ main(int argc, char *argv[])
} }
exit(retval); exit(retval);
} }
Documentation/usb/gadget_serial.txt
View file @ d80b5005
===============================
Linux Gadget Serial Driver v2.0
===============================
Linux Gadget Serial Driver v2.0 11/20/2004
11/20/2004
(updated 8-May-2008 for v2.3) (updated 8-May-2008 for v2.3)
License and Disclaimer License and Disclaimer
...@@ -56,7 +59,7 @@ hardware; for example, a PDA, an embedded Linux system, or a PC ...@@ -56,7 +59,7 @@ hardware; for example, a PDA, an embedded Linux system, or a PC
with a USB development card. with a USB development card.
The gadget serial driver talks over USB to either a CDC ACM driver The gadget serial driver talks over USB to either a CDC ACM driver
or a generic USB serial driver running on a host PC. or a generic USB serial driver running on a host PC::
Host Host
-------------------------------------- --------------------------------------
...@@ -112,11 +115,11 @@ configuring the kernel. Then rebuild and install the kernel or ...@@ -112,11 +115,11 @@ configuring the kernel. Then rebuild and install the kernel or
modules. modules.
Then you must load the gadget serial driver. To load it as an Then you must load the gadget serial driver. To load it as an
ACM device (recommended for interoperability), do this: ACM device (recommended for interoperability), do this::
modprobe g_serial modprobe g_serial
To load it as a vendor specific bulk in/out device, do this: To load it as a vendor specific bulk in/out device, do this::
modprobe g_serial use_acm=0 modprobe g_serial use_acm=0
...@@ -127,7 +130,7 @@ desired. ...@@ -127,7 +130,7 @@ desired.
Your system should use mdev (from busybox) or udev to make the Your system should use mdev (from busybox) or udev to make the
device nodes. After this gadget driver has been set up you should device nodes. After this gadget driver has been set up you should
then see a /dev/ttyGS0 node: then see a /dev/ttyGS0 node::
# ls -l /dev/ttyGS0 | cat # ls -l /dev/ttyGS0 | cat
crw-rw---- 1 root root 253, 0 May 8 14:10 /dev/ttyGS0 crw-rw---- 1 root root 253, 0 May 8 14:10 /dev/ttyGS0
...@@ -187,24 +190,24 @@ support". ...@@ -187,24 +190,24 @@ support".
Once the gadget serial driver is loaded and the USB device connected Once the gadget serial driver is loaded and the USB device connected
to the Linux host with a USB cable, the host system should recognize to the Linux host with a USB cable, the host system should recognize
the gadget serial device. For example, the command the gadget serial device. For example, the command::
cat /sys/kernel/debug/usb/devices cat /sys/kernel/debug/usb/devices
should show something like this: should show something like this:::
T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 5 Spd=480 MxCh= 0 T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 5 Spd=480 MxCh= 0
D: Ver= 2.00 Cls=02(comm.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 D: Ver= 2.00 Cls=02(comm.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1
P: Vendor=0525 ProdID=a4a7 Rev= 2.01 P: Vendor=0525 ProdID=a4a7 Rev= 2.01
S: Manufacturer=Linux 2.6.8.1 with net2280 S: Manufacturer=Linux 2.6.8.1 with net2280
S: Product=Gadget Serial S: Product=Gadget Serial
S: SerialNumber=0 S: SerialNumber=0
C:* #Ifs= 2 Cfg#= 2 Atr=c0 MxPwr= 2mA C:* #Ifs= 2 Cfg#= 2 Atr=c0 MxPwr= 2mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
E: Ad=83(I) Atr=03(Int.) MxPS= 8 Ivl=32ms E: Ad=83(I) Atr=03(Int.) MxPS= 8 Ivl=32ms
I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms
E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms
If the host side Linux system is configured properly, the ACM driver If the host side Linux system is configured properly, the ACM driver
should be loaded automatically. The command "lsmod" should show the should be loaded automatically. The command "lsmod" should show the
...@@ -219,29 +222,29 @@ Serial Converter support", and for the "USB Generic Serial Driver". ...@@ -219,29 +222,29 @@ Serial Converter support", and for the "USB Generic Serial Driver".
Once the gadget serial driver is loaded and the USB device connected Once the gadget serial driver is loaded and the USB device connected
to the Linux host with a USB cable, the host system should recognize to the Linux host with a USB cable, the host system should recognize
the gadget serial device. For example, the command the gadget serial device. For example, the command::
cat /sys/kernel/debug/usb/devices cat /sys/kernel/debug/usb/devices
should show something like this: should show something like this:::
T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 6 Spd=480 MxCh= 0 T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 6 Spd=480 MxCh= 0
D: Ver= 2.00 Cls=ff(vend.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 D: Ver= 2.00 Cls=ff(vend.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1
P: Vendor=0525 ProdID=a4a6 Rev= 2.01 P: Vendor=0525 ProdID=a4a6 Rev= 2.01
S: Manufacturer=Linux 2.6.8.1 with net2280 S: Manufacturer=Linux 2.6.8.1 with net2280
S: Product=Gadget Serial S: Product=Gadget Serial
S: SerialNumber=0 S: SerialNumber=0
C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr= 2mA C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr= 2mA
I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial
E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms
E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms
You must load the usbserial driver and explicitly set its parameters You must load the usbserial driver and explicitly set its parameters
to configure it to recognize the gadget serial device, like this: to configure it to recognize the gadget serial device, like this::
echo 0x0525 0xA4A6 >/sys/bus/usb-serial/drivers/generic/new_id echo 0x0525 0xA4A6 >/sys/bus/usb-serial/drivers/generic/new_id
The legacy way is to use module parameters: The legacy way is to use module parameters::
modprobe usbserial vendor=0x0525 product=0xA4A6 modprobe usbserial vendor=0x0525 product=0xA4A6
......
Documentation/usb/iuu_phoenix.txt
View file @ d80b5005
=============================
Infinity Usb Unlimited Readme Infinity Usb Unlimited Readme
----------------------------- =============================
Hi all, Hi all,
...@@ -19,7 +20,8 @@ have his own device file(/dev/ttyUSB0,/dev/ttyUSB1,...) ...@@ -19,7 +20,8 @@ have his own device file(/dev/ttyUSB0,/dev/ttyUSB1,...)
How to tune the reader speed ? How to tune the reader speed?
=============================
A few parameters can be used at load time A few parameters can be used at load time
To use parameters, just unload the module if it is To use parameters, just unload the module if it is
...@@ -27,26 +29,33 @@ How to tune the reader speed ? ...@@ -27,26 +29,33 @@ How to tune the reader speed ?
In case of prebuilt module, use the command In case of prebuilt module, use the command
insmod iuu_phoenix param=value. insmod iuu_phoenix param=value.
Example: Example::
modprobe iuu_phoenix clockmode=3 modprobe iuu_phoenix clockmode=3
The parameters are: The parameters are:
parm: clockmode:1=3Mhz579,2=3Mhz680,3=6Mhz (int) clockmode:
parm: boost:overclock boost percent 100 to 500 (int) 1=3Mhz579,2=3Mhz680,3=6Mhz (int)
parm: cdmode:Card detect mode 0=none, 1=CD, 2=!CD, 3=DSR, 4=!DSR, 5=CTS, 6=!CTS, 7=RING, 8=!RING (int) boost:
parm: xmas:xmas color enabled or not (bool) overclock boost percent 100 to 500 (int)
parm: debug:Debug enabled or not (bool) cdmode:
Card detect mode
0=none, 1=CD, 2=!CD, 3=DSR, 4=!DSR, 5=CTS, 6=!CTS, 7=RING, 8=!RING (int)
xmas:
xmas color enabled or not (bool)
debug:
Debug enabled or not (bool)
- clockmode will provide 3 different base settings commonly adopted by - clockmode will provide 3 different base settings commonly adopted by
different software: different software:
1. 3Mhz579 1. 3Mhz579
2. 3Mhz680 2. 3Mhz680
3. 6Mhz 3. 6Mhz
- boost provide a way to overclock the reader ( my favorite :-) ) - boost provide a way to overclock the reader ( my favorite :-) )
For example to have best performance than a simple clockmode=3, try this: For example to have best performance than a simple clockmode=3, try this::
modprobe boost=195 modprobe boost=195
...@@ -66,7 +75,8 @@ How to tune the reader speed ? ...@@ -66,7 +75,8 @@ How to tune the reader speed ?
- debug will produce a lot of debugging messages... - debug will produce a lot of debugging messages...
Last notes: Last notes
==========
Don't worry about the serial settings, the serial emulation Don't worry about the serial settings, the serial emulation
is an abstraction, so use any speed or parity setting will is an abstraction, so use any speed or parity setting will
......
Documentation/usb/mass-storage.txt
View file @ d80b5005
* Overview =========================
Mass Storage Gadget (MSG)
=========================
Overview
========
Mass Storage Gadget (or MSG) acts as a USB Mass Storage device, Mass Storage Gadget (or MSG) acts as a USB Mass Storage device,
appearing to the host as a disk or a CD-ROM drive. It supports appearing to the host as a disk or a CD-ROM drive. It supports
...@@ -24,7 +29,8 @@ ...@@ -24,7 +29,8 @@
(which is no longer included in Linux). It will talk only briefly (which is no longer included in Linux). It will talk only briefly
about how to use MSF within composite gadgets. about how to use MSF within composite gadgets.
* Module parameters Module parameters
=================
The mass storage gadget accepts the following mass storage specific The mass storage gadget accepts the following mass storage specific
module parameters: module parameters:
...@@ -146,7 +152,8 @@ ...@@ -146,7 +152,8 @@
- iProduct -- USB Product string (string) - iProduct -- USB Product string (string)
- iSerialNumber -- SerialNumber string (sting) - iSerialNumber -- SerialNumber string (sting)
* sysfs entries sysfs entries
=============
For each logical unit, the gadget creates a directory in the sysfs For each logical unit, the gadget creates a directory in the sysfs
hierarchy. Inside of it the following three files are created: hierarchy. Inside of it the following three files are created:
...@@ -177,7 +184,8 @@ ...@@ -177,7 +184,8 @@
Other then those, as usual, the values of module parameters can be Other then those, as usual, the values of module parameters can be
read from /sys/module/g_mass_storage/parameters/* files. read from /sys/module/g_mass_storage/parameters/* files.
* Other gadgets using mass storage function Other gadgets using mass storage function
=========================================
The Mass Storage Gadget uses the Mass Storage Function to handle The Mass Storage Gadget uses the Mass Storage Function to handle
mass storage protocol. As a composite function, MSF may be used by mass storage protocol. As a composite function, MSF may be used by
...@@ -193,7 +201,8 @@ ...@@ -193,7 +201,8 @@
may take a look at mass_storage.c, acm_ms.c and multi.c (sorted by may take a look at mass_storage.c, acm_ms.c and multi.c (sorted by
complexity). complexity).
* Relation to file storage gadget Relation to file storage gadget
===============================
The Mass Storage Function and thus the Mass Storage Gadget has been The Mass Storage Function and thus the Mass Storage Gadget has been
based on the File Storage Gadget. The difference between the two is based on the File Storage Gadget. The difference between the two is
......
Documentation/usb/misc_usbsevseg.txt
View file @ d80b5005
=============================
USB 7-Segment Numeric Display USB 7-Segment Numeric Display
=============================
Manufactured by Delcom Engineering Manufactured by Delcom Engineering
Device Information Device Information
...@@ -13,9 +16,13 @@ Device Modes ...@@ -13,9 +16,13 @@ Device Modes
------------ ------------
By default, the driver assumes the display is only 6 characters By default, the driver assumes the display is only 6 characters
The mode for 6 characters is: The mode for 6 characters is:
MSB 0x06; LSB 0x3f MSB 0x06; LSB 0x3f
For the 8 character display: For the 8 character display:
MSB 0x08; LSB 0xff MSB 0x08; LSB 0xff
The device can accept "text" either in raw, hex, or ascii textmode. The device can accept "text" either in raw, hex, or ascii textmode.
raw controls each segment manually, raw controls each segment manually,
hex expects a value between 0-15 per character, hex expects a value between 0-15 per character,
...@@ -42,5 +49,3 @@ Device Operation ...@@ -42,5 +49,3 @@ Device Operation
To set multiple decimals points sum up each power. To set multiple decimals points sum up each power.
For example, to set the 0th and 3rd decimal place For example, to set the 0th and 3rd decimal place
echo 1001 > /sys/bus/usb/.../decimals echo 1001 > /sys/bus/usb/.../decimals
Documentation/usb/mtouchusb.txt
View file @ d80b5005
CHANGES ================
mtouchusb driver
================
Changes
=======
- 0.3 - Created based off of scanner & INSTALL from the original touchscreen - 0.3 - Created based off of scanner & INSTALL from the original touchscreen
driver on freecode (http://freecode.com/projects/3mtouchscreendriver) driver on freecode (http://freecode.com/projects/3mtouchscreendriver)
...@@ -13,7 +18,10 @@ CHANGES ...@@ -13,7 +18,10 @@ CHANGES
Eliminated vendor/product module params Eliminated vendor/product module params
Performed multiple successful tests with an EXII-5010UC Performed multiple successful tests with an EXII-5010UC
SUPPORTED HARDWARE: Supported Hardware
==================
::
All controllers have the Vendor: 0x0596 & Product: 0x0001 All controllers have the Vendor: 0x0596 & Product: 0x0001
...@@ -29,7 +37,8 @@ SUPPORTED HARDWARE: ...@@ -29,7 +37,8 @@ SUPPORTED HARDWARE:
USB Capacitive - Black Case EXII-5030UC USB Capacitive - Black Case EXII-5030UC
USB Capacitive - No Case EXII-5050UC USB Capacitive - No Case EXII-5050UC
DRIVER NOTES: Driver Notes
============
Installation is simple, you only need to add Linux Input, Linux USB, and the Installation is simple, you only need to add Linux Input, Linux USB, and the
driver to the kernel. The driver can also be optionally built as a module. driver to the kernel. The driver can also be optionally built as a module.
...@@ -54,19 +63,22 @@ generic functions like calibrations, resets, and vendor information can be ...@@ -54,19 +63,22 @@ generic functions like calibrations, resets, and vendor information can be
requested from the userspace (And the drivers would handle the vendor specific requested from the userspace (And the drivers would handle the vendor specific
tasks). tasks).
TODO: TODO
====
Implement a control urb again to handle requests to and from the device Implement a control urb again to handle requests to and from the device
such as calibration, etc once/if it becomes available. such as calibration, etc once/if it becomes available.
DISCLAIMER: Disclaimer
==========
I am not a MicroTouch/3M employee, nor have I ever been. 3M does not support I am not a MicroTouch/3M employee, nor have I ever been. 3M does not support
this driver! If you want touch drivers only supported within X, please go to: this driver! If you want touch drivers only supported within X, please go to:
http://www.3m.com/3MTouchSystems/ http://www.3m.com/3MTouchSystems/
THANKS: Thanks
======
A huge thank you to 3M Touch Systems for the EXII-5010UC controllers for A huge thank you to 3M Touch Systems for the EXII-5010UC controllers for
testing! testing!
Documentation/usb/ohci.txt
View file @ d80b5005
====
OHCI
====
23-Aug-2002 23-Aug-2002
The "ohci-hcd" driver is a USB Host Controller Driver (HCD) that is derived The "ohci-hcd" driver is a USB Host Controller Driver (HCD) that is derived
...@@ -29,4 +33,3 @@ work on while the OS is getting around to the relevant IRQ processing. ...@@ -29,4 +33,3 @@ work on while the OS is getting around to the relevant IRQ processing.
- David Brownell - David Brownell
<dbrownell@users.sourceforge.net> <dbrownell@users.sourceforge.net>
Documentation/usb/rio.txt
View file @ d80b5005
============
Diamonds Rio
============
Copyright (C) 1999, 2000 Bruce Tenison Copyright (C) 1999, 2000 Bruce Tenison
Portions Copyright (C) 1999, 2000 David Nelson Portions Copyright (C) 1999, 2000 David Nelson
Thanks to David Nelson for guidance and the usage of the scanner.txt Thanks to David Nelson for guidance and the usage of the scanner.txt
and scanner.c files to model our driver and this informative file. and scanner.c files to model our driver and this informative file.
Mar. 2, 2000 Mar. 2, 2000
CHANGES Changes
=======
- Initial Revision - Initial Revision
OVERVIEW Overview
========
This README will address issues regarding how to configure the kernel This README will address issues regarding how to configure the kernel
to access a RIO 500 mp3 player. to access a RIO 500 mp3 player.
Before I explain how to use this to access the Rio500 please be warned: Before I explain how to use this to access the Rio500 please be warned:
W A R N I N G: .. warning::
--------------
Please note that this software is still under development. The authors Please note that this software is still under development. The authors
are in no way responsible for any damage that may occur, no matter how are in no way responsible for any damage that may occur, no matter how
inconsequential. inconsequential.
It seems that the Rio has a problem when sending .mp3 with low batteries. It seems that the Rio has a problem when sending .mp3 with low batteries.
I suggest when the batteries are low and you want to transfer stuff that you I suggest when the batteries are low and you want to transfer stuff that you
...@@ -42,15 +49,15 @@ power on problems with some chipsets. If you are having problems ...@@ -42,15 +49,15 @@ power on problems with some chipsets. If you are having problems
connecting to your RIO 500, try turning it on first and then plugging it connecting to your RIO 500, try turning it on first and then plugging it
into the USB cable. into the USB cable.
Contact information: Contact Information
-------------------- -------------------
The main page for the project is hosted at sourceforge.net in the following The main page for the project is hosted at sourceforge.net in the following
URL: <http://rio500.sourceforge.net>. You can also go to the project's URL: <http://rio500.sourceforge.net>. You can also go to the project's
sourceforge home page at: <http://sourceforge.net/projects/rio500/>. sourceforge home page at: <http://sourceforge.net/projects/rio500/>.
There is also a mailing list: rio500-users@lists.sourceforge.net There is also a mailing list: rio500-users@lists.sourceforge.net
Authors: Authors
------- -------
Most of the code was written by Cesar Miquel <miquel@df.uba.ar>. Keith Most of the code was written by Cesar Miquel <miquel@df.uba.ar>. Keith
...@@ -61,12 +68,13 @@ re-written and Pete Ikusz along with the rest will re-design it. I would ...@@ -61,12 +68,13 @@ re-written and Pete Ikusz along with the rest will re-design it. I would
also like to thank Tri Nguyen <tmn_3022000@hotmail.com> who provided use also like to thank Tri Nguyen <tmn_3022000@hotmail.com> who provided use
with some important information regarding the communication with the Rio. with some important information regarding the communication with the Rio.
ADDITIONAL INFORMATION and Userspace tools Additional Information and userspace tools
http://rio500.sourceforge.net/ http://rio500.sourceforge.net/
REQUIREMENTS Requirements
============
A host with a USB port. Ideally, either a UHCI (Intel) or OHCI A host with a USB port. Ideally, either a UHCI (Intel) or OHCI
(Compaq and others) hardware port should work. (Compaq and others) hardware port should work.
...@@ -80,11 +88,11 @@ A Linux kernel with RIO 500 support enabled. ...@@ -80,11 +88,11 @@ A Linux kernel with RIO 500 support enabled.
'lspci' which is only needed to determine the type of USB hardware 'lspci' which is only needed to determine the type of USB hardware
available in your machine. available in your machine.
CONFIGURATION Configuration
Using `lspci -v`, determine the type of USB hardware available. Using `lspci -v`, determine the type of USB hardware available.
If you see something like: If you see something like::
USB Controller: ...... USB Controller: ......
Flags: ..... Flags: .....
...@@ -92,7 +100,7 @@ Using `lspci -v`, determine the type of USB hardware available. ...@@ -92,7 +100,7 @@ Using `lspci -v`, determine the type of USB hardware available.
Then you have a UHCI based controller. Then you have a UHCI based controller.
If you see something like: If you see something like::
USB Controller: ..... USB Controller: .....
Flags: .... Flags: ....
...@@ -107,8 +115,9 @@ hardware (determined from the steps above), 'USB Diamond Rio500 support', and ...@@ -107,8 +115,9 @@ hardware (determined from the steps above), 'USB Diamond Rio500 support', and
(you may need to execute `depmod -a` to update the module (you may need to execute `depmod -a` to update the module
dependencies). dependencies).
Add a device for the USB rio500: Add a device for the USB rio500::
`mknod /dev/usb/rio500 c 180 64`
mknod /dev/usb/rio500 c 180 64
Set appropriate permissions for /dev/usb/rio500 (don't forget about Set appropriate permissions for /dev/usb/rio500 (don't forget about
group and world permissions). Both read and write permissions are group and world permissions). Both read and write permissions are
...@@ -116,12 +125,14 @@ required for proper operation. ...@@ -116,12 +125,14 @@ required for proper operation.
Load the appropriate modules (if compiled as modules): Load the appropriate modules (if compiled as modules):
OHCI: OHCI::
modprobe usbcore modprobe usbcore
modprobe usb-ohci modprobe usb-ohci
modprobe rio500 modprobe rio500
UHCI: UHCI::
modprobe usbcore modprobe usbcore
modprobe usb-uhci (or uhci) modprobe usb-uhci (or uhci)
modprobe rio500 modprobe rio500
...@@ -129,10 +140,10 @@ Load the appropriate modules (if compiled as modules): ...@@ -129,10 +140,10 @@ Load the appropriate modules (if compiled as modules):
That's it. The Rio500 Utils at: http://rio500.sourceforge.net should That's it. The Rio500 Utils at: http://rio500.sourceforge.net should
be able to access the rio500. be able to access the rio500.
BUGS Bugs
====
If you encounter any problems feel free to drop me an email. If you encounter any problems feel free to drop me an email.
Bruce Tenison Bruce Tenison
btenison@dibbs.net btenison@dibbs.net
Documentation/usb/usb-help.txt
View file @ d80b5005
usb-help.txt ==============
USB references
==============
2008-Mar-7 2008-Mar-7
For USB help other than the readme files that are located in For USB help other than the readme files that are located in
Documentation/usb/*, see the following: `Documentation/usb/*`, see the following:
Linux-USB project: http://www.linux-usb.org - Linux-USB project: http://www.linux-usb.org
mirrors at http://usb.in.tum.de/linux-usb/ mirrors at http://usb.in.tum.de/linux-usb/
and http://it.linux-usb.org and http://it.linux-usb.org
Linux USB Guide: http://linux-usb.sourceforge.net - Linux USB Guide: http://linux-usb.sourceforge.net
Linux-USB device overview (working devices and drivers): - Linux-USB device overview (working devices and drivers):
http://www.qbik.ch/usb/devices/ http://www.qbik.ch/usb/devices/
The Linux-USB mailing list is at linux-usb@vger.kernel.org The Linux-USB mailing list is at linux-usb@vger.kernel.org
###
Documentation/usb/usb-serial.txt
View file @ d80b5005
This diff is collapsed.
Documentation/usb/usbip_protocol.txt
View file @ d80b5005
This diff is collapsed.
Documentation/usb/usbmon.txt
View file @ d80b5005
* Introduction ======
usbmon
======
Introduction
============
The name "usbmon" in lowercase refers to a facility in kernel which is The name "usbmon" in lowercase refers to a facility in kernel which is
used to collect traces of I/O on the USB bus. This function is analogous used to collect traces of I/O on the USB bus. This function is analogous
...@@ -16,7 +21,8 @@ Two APIs are currently implemented: "text" and "binary". The binary API ...@@ -16,7 +21,8 @@ Two APIs are currently implemented: "text" and "binary". The binary API
is available through a character device in /dev namespace and is an ABI. is available through a character device in /dev namespace and is an ABI.
The text API is deprecated since 2.6.35, but available for convenience. The text API is deprecated since 2.6.35, but available for convenience.
* How to use usbmon to collect raw text traces How to use usbmon to collect raw text traces
============================================
Unlike the packet socket, usbmon has an interface which provides traces Unlike the packet socket, usbmon has an interface which provides traces
in a text format. This is used for two purposes. First, it serves as a in a text format. This is used for two purposes. First, it serves as a
...@@ -26,38 +32,41 @@ are finalized. Second, humans can read it in case tools are not available. ...@@ -26,38 +32,41 @@ are finalized. Second, humans can read it in case tools are not available.
To collect a raw text trace, execute following steps. To collect a raw text trace, execute following steps.
1. Prepare 1. Prepare
----------
Mount debugfs (it has to be enabled in your kernel configuration), and Mount debugfs (it has to be enabled in your kernel configuration), and
load the usbmon module (if built as module). The second step is skipped load the usbmon module (if built as module). The second step is skipped
if usbmon is built into the kernel. if usbmon is built into the kernel::
# mount -t debugfs none_debugs /sys/kernel/debug # mount -t debugfs none_debugs /sys/kernel/debug
# modprobe usbmon # modprobe usbmon
# #
Verify that bus sockets are present. Verify that bus sockets are present:
# ls /sys/kernel/debug/usb/usbmon # ls /sys/kernel/debug/usb/usbmon
0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u
# #
Now you can choose to either use the socket '0u' (to capture packets on all Now you can choose to either use the socket '0u' (to capture packets on all
buses), and skip to step #3, or find the bus used by your device with step #2. buses), and skip to step #3, or find the bus used by your device with step #2.
This allows to filter away annoying devices that talk continuously. This allows to filter away annoying devices that talk continuously.
2. Find which bus connects to the desired device 2. Find which bus connects to the desired device
------------------------------------------------
Run "cat /sys/kernel/debug/usb/devices", and find the T-line which corresponds Run "cat /sys/kernel/debug/usb/devices", and find the T-line which corresponds
to the device. Usually you do it by looking for the vendor string. If you have to the device. Usually you do it by looking for the vendor string. If you have
many similar devices, unplug one and compare the two many similar devices, unplug one and compare the two
/sys/kernel/debug/usb/devices outputs. The T-line will have a bus number. /sys/kernel/debug/usb/devices outputs. The T-line will have a bus number.
Example:
T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 Example::
D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0557 ProdID=2004 Rev= 1.00 T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0
S: Manufacturer=ATEN D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
S: Product=UC100KM V2.00 P: Vendor=0557 ProdID=2004 Rev= 1.00
S: Manufacturer=ATEN
S: Product=UC100KM V2.00
"Bus=03" means it's bus 3. Alternatively, you can look at the output from "Bus=03" means it's bus 3. Alternatively, you can look at the output from
"lsusb" and get the bus number from the appropriate line. Example: "lsusb" and get the bus number from the appropriate line. Example:
...@@ -65,23 +74,28 @@ S: Product=UC100KM V2.00 ...@@ -65,23 +74,28 @@ S: Product=UC100KM V2.00
Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00 Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00
3. Start 'cat' 3. Start 'cat'
--------------
::
# cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out # cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out
to listen on a single bus, otherwise, to listen on all buses, type: to listen on a single bus, otherwise, to listen on all buses, type::
# cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out # cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out
This process will read until it is killed. Naturally, the output can be This process will read until it is killed. Naturally, the output can be
redirected to a desirable location. This is preferred, because it is going redirected to a desirable location. This is preferred, because it is going
to be quite long. to be quite long.
4. Perform the desired operation on the USB bus 4. Perform the desired operation on the USB bus
-----------------------------------------------
This is where you do something that creates the traffic: plug in a flash key, This is where you do something that creates the traffic: plug in a flash key,
copy files, control a webcam, etc. copy files, control a webcam, etc.
5. Kill cat 5. Kill cat
-----------
Usually it's done with a keyboard interrupt (Control-C). Usually it's done with a keyboard interrupt (Control-C).
...@@ -89,7 +103,8 @@ At this point the output file (/tmp/1.mon.out in this example) can be saved, ...@@ -89,7 +103,8 @@ At this point the output file (/tmp/1.mon.out in this example) can be saved,
sent by e-mail, or inspected with a text editor. In the last case make sure sent by e-mail, or inspected with a text editor. In the last case make sure
that the file size is not excessive for your favourite editor. that the file size is not excessive for your favourite editor.
* Raw text data format Raw text data format
====================
Two formats are supported currently: the original, or '1t' format, and Two formats are supported currently: the original, or '1t' format, and
the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u' the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u'
...@@ -122,10 +137,14 @@ Here is the list of words, from left to right: ...@@ -122,10 +137,14 @@ Here is the list of words, from left to right:
- "Address" word (formerly a "pipe"). It consists of four fields, separated by - "Address" word (formerly a "pipe"). It consists of four fields, separated by
colons: URB type and direction, Bus number, Device address, Endpoint number. colons: URB type and direction, Bus number, Device address, Endpoint number.
Type and direction are encoded with two bytes in the following manner: Type and direction are encoded with two bytes in the following manner:
== == =============================
Ci Co Control input and output Ci Co Control input and output
Zi Zo Isochronous input and output Zi Zo Isochronous input and output
Ii Io Interrupt input and output Ii Io Interrupt input and output
Bi Bo Bulk input and output Bi Bo Bulk input and output
== == =============================
Bus number, Device address, and Endpoint are decimal numbers, but they may Bus number, Device address, and Endpoint are decimal numbers, but they may
have leading zeros, for the sake of human readers. have leading zeros, for the sake of human readers.
...@@ -178,24 +197,25 @@ Here is the list of words, from left to right: ...@@ -178,24 +197,25 @@ Here is the list of words, from left to right:
Examples: Examples:
An input control transfer to get a port status. An input control transfer to get a port status::
d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 < d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 <
d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000 d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000
An output bulk transfer to send a SCSI command 0x28 (READ_10) in a 31-byte An output bulk transfer to send a SCSI command 0x28 (READ_10) in a 31-byte
Bulk wrapper to a storage device at address 5: Bulk wrapper to a storage device at address 5::
dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000 dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000
dd65f0e8 4128379808 C Bo:1:005:2 0 31 > dd65f0e8 4128379808 C Bo:1:005:2 0 31 >
* Raw binary format and API Raw binary format and API
=========================
The overall architecture of the API is about the same as the one above, The overall architecture of the API is about the same as the one above,
only the events are delivered in binary format. Each event is sent in only the events are delivered in binary format. Each event is sent in
the following structure (its name is made up, so that we can refer to it): the following structure (its name is made up, so that we can refer to it)::
struct usbmon_packet { struct usbmon_packet {
u64 id; /* 0: URB ID - from submission to callback */ u64 id; /* 0: URB ID - from submission to callback */
unsigned char type; /* 8: Same as text; extensible. */ unsigned char type; /* 8: Same as text; extensible. */
unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */ unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */
...@@ -220,7 +240,7 @@ struct usbmon_packet { ...@@ -220,7 +240,7 @@ struct usbmon_packet {
int start_frame; /* 52: For ISO */ int start_frame; /* 52: For ISO */
unsigned int xfer_flags; /* 56: copy of URB's transfer_flags */ unsigned int xfer_flags; /* 56: copy of URB's transfer_flags */
unsigned int ndesc; /* 60: Actual number of ISO descriptors */ unsigned int ndesc; /* 60: Actual number of ISO descriptors */
}; /* 64 total length */ }; /* 64 total length */
These events can be received from a character device by reading with read(2), These events can be received from a character device by reading with read(2),
with an ioctl(2), or by accessing the buffer with mmap. However, read(2) with an ioctl(2), or by accessing the buffer with mmap. However, read(2)
...@@ -244,12 +264,12 @@ no events are available. ...@@ -244,12 +264,12 @@ no events are available.
MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats) MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats)
The argument is a pointer to the following structure: The argument is a pointer to the following structure::
struct mon_bin_stats { struct mon_bin_stats {
u32 queued; u32 queued;
u32 dropped; u32 dropped;
}; };
The member "queued" refers to the number of events currently queued in the The member "queued" refers to the number of events currently queued in the
buffer (and not to the number of events processed since the last reset). buffer (and not to the number of events processed since the last reset).
...@@ -273,13 +293,13 @@ This call returns the current size of the buffer in bytes. ...@@ -273,13 +293,13 @@ This call returns the current size of the buffer in bytes.
These calls wait for events to arrive if none were in the kernel buffer, These calls wait for events to arrive if none were in the kernel buffer,
then return the first event. The argument is a pointer to the following then return the first event. The argument is a pointer to the following
structure: structure::
struct mon_get_arg { struct mon_get_arg {
struct usbmon_packet *hdr; struct usbmon_packet *hdr;
void *data; void *data;
size_t alloc; /* Length of data (can be zero) */ size_t alloc; /* Length of data (can be zero) */
}; };
Before the call, hdr, data, and alloc should be filled. Upon return, the area Before the call, hdr, data, and alloc should be filled. Upon return, the area
pointed by hdr contains the next event structure, and the data buffer contains pointed by hdr contains the next event structure, and the data buffer contains
...@@ -290,13 +310,13 @@ The MON_IOCX_GET copies 48 bytes to hdr area, MON_IOCX_GETX copies 64 bytes. ...@@ -290,13 +310,13 @@ The MON_IOCX_GET copies 48 bytes to hdr area, MON_IOCX_GETX copies 64 bytes.
MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg) MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)
This ioctl is primarily used when the application accesses the buffer This ioctl is primarily used when the application accesses the buffer
with mmap(2). Its argument is a pointer to the following structure: with mmap(2). Its argument is a pointer to the following structure::
struct mon_mfetch_arg { struct mon_mfetch_arg {
uint32_t *offvec; /* Vector of events fetched */ uint32_t *offvec; /* Vector of events fetched */
uint32_t nfetch; /* Number of events to fetch (out: fetched) */ uint32_t nfetch; /* Number of events to fetch (out: fetched) */
uint32_t nflush; /* Number of events to flush */ uint32_t nflush; /* Number of events to flush */
}; };
The ioctl operates in 3 stages. The ioctl operates in 3 stages.
...@@ -329,7 +349,7 @@ be polled with select(2) and poll(2). But lseek(2) does not work. ...@@ -329,7 +349,7 @@ be polled with select(2) and poll(2). But lseek(2) does not work.
The basic idea is simple: The basic idea is simple:
To prepare, map the buffer by getting the current size, then using mmap(2). To prepare, map the buffer by getting the current size, then using mmap(2).
Then, execute a loop similar to the one written in pseudo-code below: Then, execute a loop similar to the one written in pseudo-code below::
struct mon_mfetch_arg fetch; struct mon_mfetch_arg fetch;
struct usbmon_packet *hdr; struct usbmon_packet *hdr;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7