diff options
Diffstat (limited to 'Documentation/usb')
31 files changed, 2919 insertions, 1040 deletions
diff --git a/Documentation/usb/URB.txt b/Documentation/usb/URB.txt index 8ffce746d49..50da0d45544 100644 --- a/Documentation/usb/URB.txt +++ b/Documentation/usb/URB.txt @@ -168,18 +168,39 @@ that if the completion handler or anyone else tries to resubmit it they will get a -EPERM error. Thus you can be sure that when usb_kill_urb() returns, the URB is totally idle. +There is a lifetime issue to consider. An URB may complete at any +time, and the completion handler may free the URB. If this happens +while usb_unlink_urb or usb_kill_urb is running, it will cause a +memory-access violation. The driver is responsible for avoiding this, +which often means some sort of lock will be needed to prevent the URB +from being deallocated while it is still in use. + +On the other hand, since usb_unlink_urb may end up calling the +completion handler, the handler must not take any lock that is held +when usb_unlink_urb is invoked. The general solution to this problem +is to increment the URB's reference count while holding the lock, then +drop the lock and call usb_unlink_urb or usb_kill_urb, and then +decrement the URB's reference count. You increment the reference +count by calling + + struct urb *usb_get_urb(struct urb *urb) + +(ignore the return value; it is the same as the argument) and +decrement the reference count by calling usb_free_urb. Of course, +none of this is necessary if there's no danger of the URB being freed +by the completion handler. + 1.7. What about the completion handler? The handler is of the following type: - typedef void (*usb_complete_t)(struct urb *, struct pt_regs *) + typedef void (*usb_complete_t)(struct urb *) -I.e., it gets the URB that caused the completion call, plus the -register values at the time of the corresponding interrupt (if any). -In the completion handler, you should have a look at urb->status to -detect any USB errors. Since the context parameter is included in the URB, -you can pass information to the completion handler. +I.e., it gets the URB that caused the completion call. In the completion +handler, you should have a look at urb->status to detect any USB errors. +Since the context parameter is included in the URB, you can pass +information to the completion handler. Note that even when an error (or unlink) is reported, data may have been transferred. That's because USB transfers are packetized; it might take @@ -188,12 +209,12 @@ have transferred successfully before the completion was called. NOTE: ***** WARNING ***** -NEVER SLEEP IN A COMPLETION HANDLER. These are normally called -during hardware interrupt processing. If you can, defer substantial -work to a tasklet (bottom half) to keep system latencies low. You'll -probably need to use spinlocks to protect data structures you manipulate -in completion handlers. +NEVER SLEEP IN A COMPLETION HANDLER. These are often called in atomic +context. +In the current kernel, completion handlers run with local interrupts +disabled, but in the future this will be changed, so don't assume that +local IRQs are always disabled inside completion handlers. 1.8. How to do isochronous (ISO) transfers? diff --git a/Documentation/usb/WUSB-Design-overview.txt b/Documentation/usb/WUSB-Design-overview.txt new file mode 100644 index 00000000000..1cd07c017cf --- /dev/null +++ b/Documentation/usb/WUSB-Design-overview.txt @@ -0,0 +1,448 @@ + +Linux UWB + Wireless USB + WiNET + + (C) 2005-2006 Intel Corporation + Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com> + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License version + 2 as published by the Free Software Foundation. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + 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., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA. + + +Please visit http://bughost.org/thewiki/Design-overview.txt-1.8 for +updated content. + + * Design-overview.txt-1.8 + +This code implements a Ultra Wide Band stack for Linux, as well as +drivers for the USB based UWB radio controllers defined in the +Wireless USB 1.0 specification (including Wireless USB host controller +and an Intel WiNET controller). + + 1. Introduction + 1. HWA: Host Wire adapters, your Wireless USB dongle + + 2. DWA: Device Wired Adaptor, a Wireless USB hub for wired + devices + 3. WHCI: Wireless Host Controller Interface, the PCI WUSB host + adapter + 2. The UWB stack + 1. Devices and hosts: the basic structure + + 2. Host Controller life cycle + + 3. On the air: beacons and enumerating the radio neighborhood + + 4. Device lists + 5. Bandwidth allocation + + 3. Wireless USB Host Controller drivers + + 4. Glossary + + + Introduction + +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 +these others are Wireless USB and TCP/IP, but seems Bluetooth and +Firewire/1394 are coming along. + +UWB uses a band from roughly 3 to 10 GHz, transmitting at a max of +~-41dB (or 0.074 uW/MHz--geography specific data is still being +negotiated w/ regulators, so watch for changes). That band is divided in +a bunch of ~1.5 GHz wide channels (or band groups) composed of three +subbands/subchannels (528 MHz each). Each channel is independent of each +other, so you could consider them different "busses". Initially this +driver considers them all a single one. + +Radio time is divided in 65536 us long /superframes/, each one divided +in 256 256us long /MASs/ (Media Allocation Slots), which are the basic +time/media allocation units for transferring data. At the beginning of +each superframe there is a Beacon Period (BP), where every device +transmit its beacon on a single MAS. The length of the BP depends on how +many devices are present and the length of their beacons. + +Devices have a MAC (fixed, 48 bit address) and a device (changeable, 16 +bit address) and send periodic beacons to advertise themselves and pass +info on what they are and do. They advertise their capabilities and a +bunch of other stuff. + +The different logical parts of this driver are: + + * + + *UWB*: the Ultra-Wide-Band stack -- manages the radio and + associated spectrum to allow for devices sharing it. Allows to + control bandwidth assignment, beaconing, scanning, etc + + * + + *WUSB*: the layer that sits on top of UWB to provide Wireless USB. + The Wireless USB spec defines means to control a UWB radio and to + do the actual WUSB. + + + HWA: Host Wire adapters, your Wireless USB dongle + +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 +USB. The Wireless USB Host Controller in a HWA looks to the host like a +[Wireless] USB controller connected via USB (!) + +The HWA itself is broken in two or three main interfaces: + + * + + *RC*: Radio control -- this implements an interface to the + Ultra-Wide-Band radio controller. The driver for this implements a + USB-based UWB Radio Controller to the UWB stack. + + * + + *HC*: the wireless USB host controller. It looks like a USB host + whose root port is the radio and the WUSB devices connect to it. + To the system it looks like a separate USB host. The driver (will) + implement a USB host controller (similar to UHCI, OHCI or EHCI) + for which the root hub is the radio...To reiterate: it is a USB + controller that is connected via USB instead of PCI. + + * + + *WINET*: some HW provide a WiNET interface (IP over UWB). This + package provides a driver for it (it looks like a network + interface, winetX). The driver detects when there is a link up for + their type and kick into gear. + + + DWA: Device Wired Adaptor, a Wireless USB hub for wired devices + +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 +USB. To the system it looks like yet another USB host. To the untrained +eye, it looks like a hub that connects upstream wirelessly. + +We still offer no support for this; however, it should share a lot of +code with the HWA-RC driver; there is a bunch of factorization work that +has been done to support that in upcoming releases. + + + WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter + +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 your host via a PCI interface. As in the case of the HWA, it has a +Radio Control interface and the WUSB Host Controller interface per se. + +There is still no driver support for this, but will be in upcoming +releases. + + + The UWB stack + +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 +provides an API for controlling the local radio controllers (RCs from +now on), such as to start/stop beaconing, scan, allocate bandwidth, etc. + + + Devices and hosts: the basic structure + +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 +beacon from it) you get a struct uwb_dev that will show up in +/sys/class/uwb and in /sys/bus/uwb/devices. + +For each RC that is detected, a new struct uwb_rc is created. In turn, a +RC is also a device, so they also show in /sys/class/uwb and +/sys/bus/uwb/devices, but at the same time, only radio controllers show +up in /sys/class/uwb_rc. + + * + + [*] The reason for RCs being also devices is that not only we can + see them while enumerating the system device tree, but also on the + radio (their beacons and stuff), so the handling has to be + likewise to that of a device. + +Each RC driver is implemented by a separate driver that plugs into the +interface that the UWB stack provides through a struct uwb_rc_ops. The +spec creators have been nice enough to make the message format the same +for HWA and WHCI RCs, so the driver is really a very thin transport that +moves the requests from the UWB API to the device [/uwb_rc_ops->cmd()/] +and sends the replies and notifications back to the API +[/uwb_rc_neh_grok()/]. Notifications are handled to the UWB daemon, that +is chartered, among other things, to keep the tab of how the UWB radio +neighborhood looks, creating and destroying devices as they show up or +disappear. + +Command execution is very simple: a command block is sent and a event +block or reply is expected back. For sending/receiving command/events, a +handle called /neh/ (Notification/Event Handle) is opened with +/uwb_rc_neh_open()/. + +The HWA-RC (USB dongle) driver (drivers/uwb/hwa-rc.c) does this job for +the USB connected HWA. Eventually, drivers/whci-rc.c will do the same +for the PCI connected WHCI controller. + + + Host Controller life cycle + +So let's say we connect a dongle to the system: it is detected and +firmware uploaded if needed [for Intel's i1480 +/drivers/uwb/ptc/usb.c:ptc_usb_probe()/] and then it is reenumerated. +Now we have a real HWA device connected and +/drivers/uwb/hwa-rc.c:hwarc_probe()/ picks it up, that will set up the +Wire-Adaptor environment and then suck it into the UWB stack's vision of +the world [/drivers/uwb/lc-rc.c:uwb_rc_add()/]. + + * + + [*] The stack should put a new RC to scan for devices + [/uwb_rc_scan()/] so it finds what's available around and tries to + connect to them, but this is policy stuff and should be driven + from user space. As of now, the operator is expected to do it + manually; see the release notes for documentation on the procedure. + +When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/ +takes time of tearing everything down safely (or not...). + + + On the air: beacons and enumerating the radio neighborhood + +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: + + * + + $ echo 9 0 > /sys/class/uwb_rc/uwb0/beacon + +Now it is visible. If there were other devices in the same radio channel +and beacon group (that's what the zero is for), the dongle's radio +control interface will send beacon notifications on its +notification/event endpoint (NEEP). The beacon notifications are part of +the event stream that is funneled into the API with +/drivers/uwb/neh.c:uwb_rc_neh_grok()/ and delivered to the UWBD, the UWB +daemon through a notification list. + +UWBD wakes up and scans the event list; finds a beacon and adds it to +the BEACON CACHE (/uwb_beca/). If he receives a number of beacons from +the same device, he considers it to be 'onair' and creates a new device +[/drivers/uwb/lc-dev.c:uwbd_dev_onair()/]. Similarly, when no beacons +are received in some time, the device is considered gone and wiped out +[uwbd calls periodically /uwb/beacon.c:uwb_beca_purge()/ that will purge +the beacon cache of dead devices]. + + + Device lists + +All UWB devices are kept in the list of the struct bus_type uwb_bus. + + + Bandwidth allocation + +The UWB stack maintains a local copy of DRP availability through +processing of incoming *DRP Availability Change* notifications. This +local copy is currently used to present the current bandwidth +availability to the user through the sysfs file +/sys/class/uwb_rc/uwbx/bw_avail. In the future the bandwidth +availability information will be used by the bandwidth reservation +routines. + +The bandwidth reservation routines are in progress and are thus not +present in the current release. When completed they will enable a user +to initiate DRP reservation requests through interaction with sysfs. DRP +reservation requests from remote UWB devices will also be handled. The +bandwidth management done by the UWB stack will include callbacks to the +higher layers will enable the higher layers to use the reservations upon +completion. [Note: The bandwidth reservation work is in progress and +subject to change.] + + + Wireless USB Host Controller drivers + +*WARNING* This section needs a lot of work! + +As explained above, there are three different types of HCs in the WUSB +world: HWA-HC, DWA-HC and WHCI-HC. + +HWA-HC and DWA-HC share that they are Wire-Adapters (USB or WUSB +connected controllers), and their transfer management system is almost +identical. So is their notification delivery system. + +HWA-HC and WHCI-HC share that they are both WUSB host controllers, so +they have to deal with WUSB device life cycle and maintenance, wireless +root-hub + +HWA exposes a Host Controller interface (HWA-HC 0xe0/02/02). This has +three endpoints (Notifications, Data Transfer In and Data Transfer +Out--known as NEP, DTI and DTO in the code). + +We reserve UWB bandwidth for our Wireless USB Cluster, create a Cluster +ID and tell the HC to use all that. Then we start it. This means the HC +starts sending MMCs. + + * + + The MMCs are blocks of data defined somewhere in the WUSB1.0 spec + that define a stream in the UWB channel time allocated for sending + WUSB IEs (host to device commands/notifications) and Device + Notifications (device initiated to host). Each host defines a + unique Wireless USB cluster through MMCs. Devices can connect to a + single cluster at the time. The IEs are Information Elements, and + among them are the bandwidth allocations that tell each device + when can they transmit or receive. + +Now it all depends on external stimuli. + +*New device connection* + +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, +selects which one to connect to. Sends a /DN_Connect/ (device +notification connect) during the DNTS (Device Notification Time +Slot--announced in the MMCs + +HC picks the /DN_Connect/ out (nep module sends to notif.c for delivery +into /devconnect/). This process starts the authentication process for +the device. First we allocate a /fake port/ and assign an +unauthenticated address (128 to 255--what we really do is +0x80 | fake_port_idx). We fiddle with the fake port status and /khubd/ +sees a new connection, so he moves on to enable the fake port with a reset. + +So now we are in the reset path -- we know we have a non-yet enumerated +device with an unauthorized address; we ask user space to authenticate +(FIXME: not yet done, similar to bluetooth pairing), then we do the key +exchange (FIXME: not yet done) and issue a /set address 0/ to bring the +device to the default state. Device is authenticated. + +From here, the USB stack takes control through the usb_hcd ops. khubd +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 +read descriptors and move our data. + +*Device life cycle and keep alives* + +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 +if the activity timestamp gets old, we ping the device by sending it a +Keep Alive IE; it responds with a /DN_Alive/ pong during the DNTS (this +arrives to us as a notification through +devconnect.c:wusb_handle_dn_alive(). If a device times out, we +disconnect it from the system (cleaning up internal information and +toggling the bits in the fake hub port, which kicks khubd into removing +the rest of the stuff). + +This is done through devconnect:__wusb_check_devs(), which will scan the +device list looking for whom needs refreshing. + +If the device wants to disconnect, it will either die (ugly) or send a +/DN_Disconnect/ that will prompt a disconnection from the system. + +*Sending and receiving data* + +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 +DWAs. + +Each HC has a number of rpipes and buffers that can be assigned to them; +when doing a data transfer (xfer), first the rpipe has to be aimed and +prepared (buffers assigned), then we can start queueing requests for +data in or out. + +Data buffers have to be segmented out before sending--so we send first a +header (segment request) and then if there is any data, a data buffer +immediately after to the DTI interface (yep, even the request). If our +buffer is bigger than the max segment size, then we just do multiple +requests. + +[This sucks, because doing USB scatter gatter in Linux is resource +intensive, if any...not that the current approach is not. It just has to +be cleaned up a lot :)]. + +If reading, we don't send data buffers, just the segment headers saying +we want to read segments. + +When the xfer is executed, we receive a notification that says data is +ready in the DTI endpoint (handled through +xfer.c:wa_handle_notif_xfer()). In there we read from the DTI endpoint a +descriptor that gives us the status of the transfer, its identification +(given when we issued it) and the segment number. If it was a data read, +we issue another URB to read into the destination buffer the chunk of +data coming out of the remote endpoint. Done, wait for the next guy. The +callbacks for the URBs issued from here are the ones that will declare +the xfer complete at some point and call its callback. + +Seems simple, but the implementation is not trivial. + + * + + *WARNING* Old!! + +The main xfer descriptor, wa_xfer (equivalent to a URB) contains an +array of segments, tallys on segments and buffers and callback +information. Buried in there is a lot of URBs for executing the segments +and buffer transfers. + +For OUT xfers, there is an array of segments, one URB for each, another +one of buffer URB. When submitting, we submit URBs for segment request +1, buffer 1, segment 2, buffer 2...etc. Then we wait on the DTI for xfer +result data; when all the segments are complete, we call the callback to +finalize the transfer. + +For IN xfers, we only issue URBs for the segments we want to read and +then wait for the xfer result data. + +*URB mapping into xfers* + +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 +context (wa_xfer) and submit it. When the xfer is done, our callback is +called and we assign the status bits and release the xfer resources. + +In dequeue() we are basically cancelling/aborting the transfer. We issue +a xfer abort request to the HC, cancel all the URBs we had submitted +and not yet done and when all that is done, the xfer callback will be +called--this will call the URB callback. + + + Glossary + +*DWA* -- Device Wire Adapter + +USB host, wired for downstream devices, upstream connects wirelessly +with Wireless USB. + +*EVENT* -- Response to a command on the NEEP + +*HWA* -- Host Wire Adapter / USB dongle for UWB and Wireless USB + +*NEH* -- Notification/Event Handle + +Handle/file descriptor for receiving notifications or events. The WA +code requires you to get one of this to listen for notifications or +events on the NEEP. + +*NEEP* -- Notification/Event EndPoint + +Stuff related to the management of the first endpoint of a HWA USB +dongle that is used to deliver an stream of events and notifications to +the host. + +*NOTIFICATION* -- Message coming in the NEEP as response to something. + +*RC* -- Radio Control + +Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by +InakyPerezGonzalez) + diff --git a/Documentation/usb/anchors.txt b/Documentation/usb/anchors.txt new file mode 100644 index 00000000000..fe6a99a32bb --- /dev/null +++ b/Documentation/usb/anchors.txt @@ -0,0 +1,79 @@ +What is anchor? +=============== + +A USB driver needs to support some callbacks requiring +a driver to cease all IO to an interface. To do so, a +driver has to keep track of the URBs it has submitted +to know they've all completed or to call usb_kill_urb +for them. The anchor is a data structure takes care of +keeping track of URBs and provides methods to deal with +multiple URBs. + +Allocation and Initialisation +============================= + +There's no API to allocate an anchor. It is simply declared +as struct usb_anchor. init_usb_anchor() must be called to +initialise the data structure. + +Deallocation +============ + +Once it has no more URBs associated with it, the anchor can be +freed with normal memory management operations. + +Association and disassociation of URBs with anchors +=================================================== + +An association of URBs to an anchor is made by an explicit +call to usb_anchor_urb(). The association is maintained until +an URB is finished by (successful) completion. Thus disassociation +is automatic. A function is provided to forcibly finish (kill) +all URBs associated with an anchor. +Furthermore, disassociation can be made with usb_unanchor_urb() + +Operations on multitudes of URBs +================================ + +usb_kill_anchored_urbs() +------------------------ + +This function kills all URBs associated with an anchor. The URBs +are called in the reverse temporal order they were submitted. +This way no data can be reordered. + +usb_unlink_anchored_urbs() +-------------------------- + +This function unlinks all URBs associated with an anchor. The URBs +are processed in the reverse temporal order they were submitted. +This is similar to usb_kill_anchored_urbs(), but it will not sleep. +Therefore no guarantee is made that the URBs have been unlinked when +the call returns. They may be unlinked later but will be unlinked in +finite time. + +usb_scuttle_anchored_urbs() +--------------------------- + +All URBs of an anchor are unanchored en masse. + +usb_wait_anchor_empty_timeout() +------------------------------- + +This function waits for all URBs associated with an anchor to finish +or a timeout, whichever comes first. Its return value will tell you +whether the timeout was reached. + +usb_anchor_empty() +------------------ + +Returns true if no URBs are associated with an anchor. Locking +is the caller's responsibility. + +usb_get_from_anchor() +--------------------- + +Returns the oldest anchored URB of an anchor. The URB is unanchored +and returned with a reference. As you may mix URBs to several +destinations in one anchor you have no guarantee the chronologically +first submitted URB is returned. diff --git a/Documentation/usb/auerswald.txt b/Documentation/usb/auerswald.txt deleted file mode 100644 index 7ee4d8f6911..00000000000 --- a/Documentation/usb/auerswald.txt +++ /dev/null @@ -1,30 +0,0 @@ - Auerswald USB kernel driver - =========================== - -What is it? What can I do with it? -================================== -The auerswald USB kernel driver connects your linux 2.4.x -system to the auerswald usb-enabled devices. - -There are two types of auerswald usb devices: -a) small PBX systems (ISDN) -b) COMfort system telephones (ISDN) - -The driver installation creates the devices -/dev/usb/auer0..15. These devices carry a vendor- -specific protocol. You may run all auerswald java -software on it. The java software needs a native -library "libAuerUsbJNINative.so" installed on -your system. This library is available from -auerswald and shipped as part of the java software. - -You may create the devices with: - mknod -m 666 /dev/usb/auer0 c 180 112 - ... - mknod -m 666 /dev/usb/auer15 c 180 127 - -Future plans -============ -- Connection to ISDN4LINUX (the hisax interface) - -The maintainer of this driver is wolfgang@iksw-muees.de diff --git a/Documentation/usb/authorization.txt b/Documentation/usb/authorization.txt index 2af40060949..c069b6884c7 100644 --- a/Documentation/usb/authorization.txt +++ b/Documentation/usb/authorization.txt @@ -8,7 +8,7 @@ not) in a system. This feature will allow you to implement a lock-down of USB devices, fully controlled by user space. As of now, when a USB device is connected it is configured and -it's interfaces inmediately made available to the users. With this +its interfaces are immediately made available to the users. With this modification, only if root authorizes the device to be configured will then it be possible to use it. @@ -16,20 +16,20 @@ Usage: Authorize a device to connect: -$ echo 1 > /sys/usb/devices/DEVICE/authorized +$ echo 1 > /sys/bus/usb/devices/DEVICE/authorized Deauthorize a device: -$ echo 0 > /sys/usb/devices/DEVICE/authorized +$ echo 0 > /sys/bus/usb/devices/DEVICE/authorized Set new devices connected to hostX to be deauthorized by default (ie: lock down): -$ echo 0 > /sys/bus/devices/usbX/authorized_default +$ echo 0 > /sys/bus/usb/devices/usbX/authorized_default Remove the lock down: -$ echo 1 > /sys/bus/devices/usbX/authorized_default +$ echo 1 > /sys/bus/usb/devices/usbX/authorized_default By default, Wired USB devices are authorized by default to connect. Wireless USB hosts deauthorize by default all new connected @@ -47,7 +47,7 @@ USB port): boot up rc.local -> - for host in /sys/bus/devices/usb* + for host in /sys/bus/usb/devices/usb* do echo 0 > $host/authorized_default done diff --git a/Documentation/usb/bulk-streams.txt b/Documentation/usb/bulk-streams.txt new file mode 100644 index 00000000000..ffc02021863 --- /dev/null +++ b/Documentation/usb/bulk-streams.txt @@ -0,0 +1,78 @@ +Background +========== + +Bulk endpoint streams were added in the USB 3.0 specification. Streams allow a +device driver to overload a bulk endpoint so that multiple transfers can be +queued at once. + +Streams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus +3.0 specification at http://www.usb.org/developers/docs/ The USB Attached SCSI +Protocol, which uses streams to queue multiple SCSI commands, can be found on +the T10 website (http://t10.org/). + + +Device-side implications +======================== + +Once a buffer has been queued to a stream ring, the device is notified (through +an out-of-band mechanism on another endpoint) that data is ready for that stream +ID. The device then tells the host which "stream" it wants to start. The host +can also initiate a transfer on a stream without the device asking, but the +device can refuse that transfer. Devices can switch between streams at any +time. + + +Driver implications +=================== + +int usb_alloc_streams(struct usb_interface *interface, + struct usb_host_endpoint **eps, unsigned int num_eps, + unsigned int num_streams, gfp_t mem_flags); + +Device drivers will call this API to request that the host controller driver +allocate memory so the driver can use up to num_streams stream IDs. They must +pass an array of usb_host_endpoints that need to be setup with similar stream +IDs. This is to ensure that a UASP driver will be able to use the same stream +ID for the bulk IN and OUT endpoints used in a Bi-directional command sequence. + +The return value is an error condition (if one of the endpoints doesn't support +streams, or the xHCI driver ran out of memory), or the number of streams the +host controller allocated for this endpoint. The xHCI host controller hardware +declares how many stream IDs it can support, and each bulk endpoint on a +SuperSpeed device will say how many stream IDs it can handle. Therefore, +drivers should be able to deal with being allocated less stream IDs than they +requested. + +Do NOT call this function if you have URBs enqueued for any of the endpoints +passed in as arguments. Do not call this function to request less than two +streams. + +Drivers will only be allowed to call this API once for the same endpoint +without calling usb_free_streams(). This is a simplification for the xHCI host +controller driver, and may change in the future. + + +Picking new Stream IDs to use +============================ + +Stream ID 0 is reserved, and should not be used to communicate with devices. If +usb_alloc_streams() returns with a value of N, you may use streams 1 though N. +To queue an URB for a specific stream, set the urb->stream_id value. If the +endpoint does not support streams, an error will be returned. + +Note that new API to choose the next stream ID will have to be added if the xHCI +driver supports secondary stream IDs. + + +Clean up +======== + +If a driver wishes to stop using streams to communicate with the device, it +should call + +void usb_free_streams(struct usb_interface *interface, + struct usb_host_endpoint **eps, unsigned int num_eps, + gfp_t mem_flags); + +All stream IDs will be deallocated when the driver releases the interface, to +ensure that drivers that don't support streams will be able to use the endpoint. diff --git a/Documentation/usb/callbacks.txt b/Documentation/usb/callbacks.txt new file mode 100644 index 00000000000..9e85846bdb9 --- /dev/null +++ b/Documentation/usb/callbacks.txt @@ -0,0 +1,134 @@ +What callbacks will usbcore do? +=============================== + +Usbcore will call into a driver through callbacks defined in the driver +structure and through the completion handler of URBs a driver submits. +Only the former are in the scope of this document. These two kinds of +callbacks are completely independent of each other. Information on the +completion callback can be found in Documentation/usb/URB.txt. + +The callbacks defined in the driver structure are: + +1. Hotplugging callbacks: + + * @probe: Called to see if the driver is willing to manage a particular + * interface on a device. + * @disconnect: Called when the interface is no longer accessible, usually + * because its device has been (or is being) disconnected or the + * driver module is being unloaded. + +2. Odd backdoor through usbfs: + + * @ioctl: Used for drivers that want to talk to userspace through + * the "usbfs" filesystem. This lets devices provide ways to + * expose information to user space regardless of where they + * do (or don't) show up otherwise in the filesystem. + +3. Power management (PM) callbacks: + + * @suspend: Called when the device is going to be suspended. + * @resume: Called when the device is being resumed. + * @reset_resume: Called when the suspended device has been reset instead + * of being resumed. + +4. Device level operations: + + * @pre_reset: Called when the device is about to be reset. + * @post_reset: Called after the device has been reset + +The ioctl interface (2) should be used only if you have a very good +reason. Sysfs is preferred these days. The PM callbacks are covered +separately in Documentation/usb/power-management.txt. + +Calling conventions +=================== + +All callbacks are mutually exclusive. There's no need for locking +against other USB callbacks. All callbacks are called from a task +context. You may sleep. However, it is important that all sleeps have a +small fixed upper limit in time. In particular you must not call out to +user space and await results. + +Hotplugging callbacks +===================== + +These callbacks are intended to associate and disassociate a driver with +an interface. A driver's bond to an interface is exclusive. + +The probe() callback +-------------------- + +int (*probe) (struct usb_interface *intf, + const struct usb_device_id *id); + +Accept or decline an interface. If you accept the device return 0, +otherwise -ENODEV or -ENXIO. Other error codes should be used only if a +genuine error occurred during initialisation which prevented a driver +from accepting a device that would else have been accepted. +You are strongly encouraged to use usbcore's facility, +usb_set_intfdata(), to associate a data structure with an interface, so +that you know which internal state and identity you associate with a +particular interface. The device will not be suspended and you may do IO +to the interface you are called for and endpoint 0 of the device. Device +initialisation that doesn't take too long is a good idea here. + +The disconnect() callback +------------------------- + +void (*disconnect) (struct usb_interface *intf); + +This callback is a signal to break any connection with an interface. +You are not allowed any IO to a device after returning from this +callback. You also may not do any other operation that may interfere +with another driver bound the interface, eg. a power management +operation. +If you are called due to a physical disconnection, all your URBs will be +killed by usbcore. Note that in this case disconnect will be called some +time after the physical disconnection. Thus your driver must be prepared +to deal with failing IO even prior to the callback. + +Device level callbacks +====================== + +pre_reset +--------- + +int (*pre_reset)(struct usb_interface *intf); + +A driver or user space is triggering a reset on the device which +contains the interface passed as an argument. Cease IO, wait for all +outstanding URBs to complete, and save any device state you need to +restore. No more URBs may be submitted until the post_reset method +is called. + +If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you +are in atomic context. + +post_reset +---------- + +int (*post_reset)(struct usb_interface *intf); + +The reset has completed. Restore any saved device state and begin +using the device again. + +If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you +are in atomic context. + +Call sequences +============== + +No callbacks other than probe will be invoked for an interface +that isn't bound to your driver. + +Probe will never be called for an interface bound to a driver. +Hence following a successful probe, disconnect will be called +before there is another probe for the same interface. + +Once your driver is bound to an interface, disconnect can be +called at any time except in between pre_reset and post_reset. +pre_reset is always followed by post_reset, even if the reset +failed or the device has been unplugged. + +suspend is always followed by one of: resume, reset_resume, or +disconnect. diff --git a/Documentation/usb/chipidea.txt b/Documentation/usb/chipidea.txt new file mode 100644 index 00000000000..995c8bca40e --- /dev/null +++ b/Documentation/usb/chipidea.txt @@ -0,0 +1,71 @@ +1. How to test OTG FSM(HNP and SRP) +----------------------------------- +To show how to demo OTG HNP and SRP functions via sys input files +with 2 Freescale i.MX6Q sabre SD boards. + +1.1 How to enable OTG FSM in menuconfig +--------------------------------------- +Select CONFIG_USB_OTG_FSM, rebuild kernel Image and modules. +If you want to check some internal variables for otg fsm, +select CONFIG_USB_CHIPIDEA_DEBUG, there are 2 files 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 + +1.2 Test operations +------------------- +1) Power up 2 Freescale i.MX6Q sabre SD boards with gadget class driver loaded + (e.g. g_mass_storage). + +2) Connect 2 boards with usb cable with one end is micro A plug, the other end + is micro B plug. + + The A-device(with micro A plug inserted) should enumrate B-device. + +3) Role switch + On B-device: + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + if HNP polling is not supported, also need: + On A-device: + echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req + + B-device should take host role and enumrate A-device. + +4) A-device switch back to host. + On B-device: + echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + A-device should switch back to host and enumrate B-device. + +5) Remove B-device(unplug micro B plug) and insert again in 10 seconds, + A-device should enumrate B-device again. + +6) Remove B-device(unplug micro B plug) and insert again after 10 seconds, + A-device should NOT enumrate B-device. + + if A-device wants to use bus: + On A-device: + 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 + + if B-device wants to use bus: + On B-device: + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + +7) A-device power down the bus. + On A-device: + 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. + +8) B-device does data pulse for SRP. + On B-device: + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + A-device should resume usb bus and enumrate B-device. + +1.3 Reference document +---------------------- +"On-The-Go and Embedded Host Supplement to the USB Revision 2.0 Specification +July 27, 2012 Revision 2.0 version 1.1a" diff --git a/Documentation/usb/dma.txt b/Documentation/usb/dma.txt index e8b50b7de9d..444651e70d9 100644 --- a/Documentation/usb/dma.txt +++ b/Documentation/usb/dma.txt @@ -6,8 +6,9 @@ in the kernel usb programming guide (kerneldoc, from the source code). API OVERVIEW The big picture is that USB drivers can continue to ignore most DMA issues, -though they still must provide DMA-ready buffers (see DMA-mapping.txt). -That's how they've worked through the 2.4 (and earlier) kernels. +though they still must provide DMA-ready buffers (see +Documentation/DMA-API-HOWTO.txt). That's how they've worked through +the 2.4 (and earlier) kernels. OR: they can now be DMA-aware. @@ -15,11 +16,11 @@ OR: they can now be DMA-aware. manage dma mappings for existing dma-ready buffers (see below). - URBs have an additional "transfer_dma" field, as well as a transfer_flags - bit saying if it's valid. (Control requests also have "setup_dma" and a - corresponding transfer_flags bit.) + bit saying if it's valid. (Control requests also have "setup_dma", but + drivers must not use it.) -- "usbcore" will map those DMA addresses, if a DMA-aware driver didn't do - it first and set URB_NO_TRANSFER_DMA_MAP or URB_NO_SETUP_DMA_MAP. HCDs +- "usbcore" will map this DMA address, if a DMA-aware driver didn't do + it first and set URB_NO_TRANSFER_DMA_MAP. HCDs don't manage dma mappings for URBs. - There's a new "generic DMA API", parts of which are usable by USB device @@ -42,28 +43,22 @@ and effects like cache-trashing can impose subtle penalties. kind of addresses to store in urb->transfer_buffer and urb->transfer_dma. You'd also set URB_NO_TRANSFER_DMA_MAP in urb->transfer_flags: - void *usb_buffer_alloc (struct usb_device *dev, size_t size, + void *usb_alloc_coherent (struct usb_device *dev, size_t size, int mem_flags, dma_addr_t *dma); - void usb_buffer_free (struct usb_device *dev, size_t size, + void usb_free_coherent (struct usb_device *dev, size_t size, void *addr, dma_addr_t dma); Most drivers should *NOT* be using these primitives; they don't need to use this type of memory ("dma-coherent"), and memory returned from kmalloc() will work just fine. - For control transfers you can use the buffer primitives or not for each - of the transfer buffer and setup buffer independently. Set the flag bits - URB_NO_TRANSFER_DMA_MAP and URB_NO_SETUP_DMA_MAP to indicate which - buffers you have prepared. For non-control transfers URB_NO_SETUP_DMA_MAP - is ignored. - The memory buffer returned is "dma-coherent"; sometimes you might need to force a consistent memory access ordering by using memory barriers. It's not using a streaming DMA mapping, so it's good for small transfers on systems where the I/O would otherwise thrash an IOMMU mapping. (See - Documentation/DMA-mapping.txt for definitions of "coherent" and "streaming" - DMA mappings.) + Documentation/DMA-API-HOWTO.txt for definitions of "coherent" and + "streaming" DMA mappings.) Asking for 1/Nth of a page (as well as asking for N pages) is reasonably space-efficient. @@ -93,7 +88,7 @@ WORKING WITH EXISTING BUFFERS Existing buffers aren't usable for DMA without first being mapped into the DMA address space of the device. However, most buffers passed to your driver can safely be used with such DMA mapping. (See the first section -of DMA-mapping.txt, titled "What memory is DMA-able?") +of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") - When you're using scatterlists, you can map everything at once. On some systems, this kicks in an IOMMU and turns the scatterlists into single @@ -129,8 +124,8 @@ of DMA-mapping.txt, titled "What memory is DMA-able?") void usb_buffer_unmap (struct urb *urb); The calls manage urb->transfer_dma for you, and set URB_NO_TRANSFER_DMA_MAP - so that usbcore won't map or unmap the buffer. The same goes for - urb->setup_dma and URB_NO_SETUP_DMA_MAP for control requests. + so that usbcore won't map or unmap the buffer. They cannot be used for + setup_packet buffers in control requests. Note that several of those interfaces are currently commented out, since they don't have current users. See the source code. Other than the dmasync diff --git a/Documentation/usb/dwc3.txt b/Documentation/usb/dwc3.txt new file mode 100644 index 00000000000..1d02c01d1c7 --- /dev/null +++ b/Documentation/usb/dwc3.txt @@ -0,0 +1,45 @@ + + TODO +~~~~~~ +Please pick something while reading :) + +- Convert interrupt handler to per-ep-thread-irq + + As it turns out some DWC3-commands ~1ms to complete. Currently we spin + until the command completes which is bad. + + Implementation idea: + - dwc core implements a demultiplexing irq chip for interrupts per + endpoint. The interrupt numbers are allocated during probe and belong + to the device. If MSI provides per-endpoint interrupt this dummy + interrupt chip can be replaced with "real" interrupts. + - interrupts are requested / allocated on usb_ep_enable() and removed on + usb_ep_disable(). Worst case are 32 interrupts, the lower limit is two + for ep0/1. + - dwc3_send_gadget_ep_cmd() will sleep in wait_for_completion_timeout() + until the command completes. + - the interrupt handler is split into the following pieces: + - primary handler of the device + goes through every event and calls generic_handle_irq() for event + it. On return from generic_handle_irq() in acknowledges the event + counter so interrupt goes away (eventually). + + - threaded handler of the device + none + + - primary handler of the EP-interrupt + reads the event and tries to process it. Everything that requires + sleeping is handed over to the Thread. The event is saved in an + per-endpoint data-structure. + We probably have to pay attention not to process events once we + handed something to thread so we don't process event X prio Y + where X > Y. + + - threaded handler of the EP-interrupt + handles the remaining EP work which might sleep such as waiting + for command completion. + + Latency: + 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 + (except the user changed priorities). diff --git a/Documentation/usb/ehci.txt b/Documentation/usb/ehci.txt index 1536b7e7513..160bd6c3ab7 100644 --- a/Documentation/usb/ehci.txt +++ b/Documentation/usb/ehci.txt @@ -9,7 +9,7 @@ compatible with the USB 1.1 standard. It defines three transfer speeds: - "Low Speed" 1.5 Mbit/sec USB 1.1 only addressed full speed and low speed. High speed devices -can be used on USB 1.1 systems, but they slow down to USB 1.1 speeds. +can be used on USB 1.1 systems, but they slow down to USB 1.1 speeds. USB 1.1 devices may also be used on USB 2.0 systems. When plugged into an EHCI controller, they are given to a USB 1.1 "companion" @@ -210,3 +210,5 @@ TBD: Interrupt and ISO transfer performance issues. Those periodic 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 +through sysfs uframe_periodic_max parameter. Describe that. diff --git a/Documentation/usb/error-codes.txt b/Documentation/usb/error-codes.txt index 9cf83e8c27b..9c3eb845ebe 100644 --- a/Documentation/usb/error-codes.txt +++ b/Documentation/usb/error-codes.txt @@ -21,6 +21,8 @@ Non-USB-specific: USB-specific: +-EBUSY The URB is already active. + -ENODEV specified USB-device or bus doesn't exist -ENOENT specified interface or endpoint does not exist or @@ -35,14 +37,13 @@ USB-specific: d) ISO: number_of_packets is < 0 e) various other cases --EAGAIN a) specified ISO start frame too early - b) (using ISO-ASAP) too much scheduled for the future - wait some time and try again. +-EXDEV ISO: URB_ISO_ASAP wasn't specified and all the frames + the URB would be scheduled in have already expired. -EFBIG Host controller driver can't schedule that many ISO frames. --EPIPE Specified endpoint is stalled. For non-control endpoints, - reset this status with usb_clear_halt(). +-EPIPE The pipe type specified in the URB doesn't match the + endpoint's actual type. -EMSGSIZE (a) endpoint maxpacket size is zero; it is not usable in the current interface altsetting. @@ -60,6 +61,8 @@ USB-specific: -EHOSTUNREACH URB was rejected because the device is suspended. +-ENOEXEC A control URB doesn't contain a Setup packet. + ************************************************************************** * Error codes returned by in urb->status * @@ -74,6 +77,13 @@ A transfer's actual_length may be positive even when an error has been reported. That's because transfers often involve several packets, so that one or more packets could finish before an error stops further endpoint I/O. +For isochronous URBs, the urb status value is non-zero only if the URB is +unlinked, the device is removed, the host controller is disabled, or the total +transferred length is less than the requested length and the URB_SHORT_NOT_OK +flag is set. Completion handlers for isochronous URBs should only see +urb->status set to zero, -ENOENT, -ECONNRESET, -ESHUTDOWN, or -EREMOTEIO. +Individual frame descriptor status fields may report more status codes. + 0 Transfer completed successfully @@ -130,7 +140,7 @@ one or more packets could finish before an error stops further endpoint I/O. device removal events immediately. -EXDEV ISO transfer only partially completed - look at individual frame status for details + (only set in iso_frame_desc[n].status, not urb->status) -EINVAL ISO madness, if this happens: Log off and go home diff --git a/Documentation/usb/functionfs.txt b/Documentation/usb/functionfs.txt new file mode 100644 index 00000000000..eaaaea019fc --- /dev/null +++ b/Documentation/usb/functionfs.txt @@ -0,0 +1,67 @@ +*How FunctionFS works* + +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 +the user space driver has registered by writing descriptors and +strings (the user space program has to provide the same information +that kernel level composite functions provide when they are added to +the configuration). + +This in particular means that the composite initialisation functions +may not be in init section (ie. may not use the __init tag). + +From user space point of view it is a file system which when +mounted provides an "ep0" file. User space driver need to +write descriptors and strings to that file. It does not need +to worry about endpoints, interfaces or strings numbers but +simply provide descriptors such as if the function was the +only one (endpoints and strings numbers starting from one and +interface numbers starting from zero). The FunctionFS changes +them as needed also handling situation when numbers differ in +different configurations. + +When descriptors and strings are written "ep#" files appear +(one for each declared endpoint) which handle communication on +a single endpoint. Again, FunctionFS takes care of the real +numbers and changing of the configuration (which means that +"ep1" file may be really mapped to (say) endpoint 3 (and when +configuration changes to (say) endpoint 2)). "ep0" is used +for receiving events and handling setup requests. + +When all files are closed the function disables itself. + +What I also want to mention is that the FunctionFS is designed in such +a way that it is possible to mount it several times so in the end +a gadget could use several FunctionFS functions. The idea is that +each FunctionFS instance is identified by the device name used +when mounting. + +One can imagine a gadget that has an Ethernet, MTP and HID interfaces +where the last two are implemented via FunctionFS. On user space +level it would look like this: + +$ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid +$ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp +$ ( cd /dev/ffs-mtp && mtp-daemon ) & +$ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid +$ ( cd /dev/ffs-hid && hid-daemon ) & + +On kernel level the gadget checks ffs_data->dev_name to identify +whether it's FunctionFS designed for MTP ("mtp") or HID ("hid"). + +If no "functions" module parameters is supplied, the driver accepts +just one function with any name. + +When "functions" module parameter is supplied, only functions +with listed names are accepted. In particular, if the "functions" +parameter's value is just a one-element list, then the behaviour +is similar to when there is no "functions" at all; however, +only a function with the specified name is accepted. + +The gadget is registered only after all the declared function +filesystems have been mounted and USB descriptors of all functions +have been written to their ep0's. + +Conversely, the gadget is unregistered after the first USB function +closes its endpoints. + diff --git a/Documentation/usb/gadget_configfs.txt b/Documentation/usb/gadget_configfs.txt new file mode 100644 index 00000000000..4cf53e40661 --- /dev/null +++ b/Documentation/usb/gadget_configfs.txt @@ -0,0 +1,384 @@ + + + + + Linux USB gadget configured through configfs + + + 25th April 2013 + + + + +Overview +======== + +A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can +be connected to a USB Host to extend it with additional functions like a serial +port or a mass storage capability. + +A gadget is seen by its host as a set of configurations, each of which contains +a number of interfaces which, from the gadget's perspective, are known as +functions, each function representing e.g. a serial connection or a SCSI disk. + +Linux provides a number of functions for gadgets to use. + +Creating a gadget means deciding what configurations there will be +and which functions each configuration will provide. + +Configfs (please see Documentation/filesystems/configfs/*) lends itself nicely +for the purpose of telling the kernel about the above mentioned decision. +This document is about how to do it. + +It also describes how configfs integration into gadget is designed. + + + + +Requirements +============ + +In order for this to work configfs must be available, so CONFIGFS_FS must be +'y' or 'm' in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS. + + + + +Usage +===== + +(The original post describing the first function +made available through configfs can be seen here: +http://www.spinics.net/lists/linux-usb/msg76388.html) + +$ modprobe libcomposite +$ mount none $CONFIGFS_HOME -t configfs + +where CONFIGFS_HOME is the mount point for configfs + +1. Creating the gadgets +----------------------- + +For each gadget to be created its corresponding directory must be created: + +$ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name> + +e.g.: + +$ mkdir $CONFIGFS_HOME/usb_gadget/g1 + +... +... +... + +$ cd $CONFIGFS_HOME/usb_gadget/g1 + +Each gadget needs to have its vendor id <VID> and product id <PID> specified: + +$ echo <VID> > idVendor +$ echo <PID> > idProduct + +A gadget also needs its serial number, manufacturer and product strings. +In order to have a place to store them, a strings subdirectory must be created +for each language, e.g.: + +$ mkdir strings/0x409 + +Then the strings can be specified: + +$ echo <serial number> > strings/0x409/serialnumber +$ echo <manufacturer> > strings/0x409/manufacturer +$ echo <product> > strings/0x409/product + +2. Creating the configurations +------------------------------ + +Each gadget will consist of a number of configurations, their corresponding +directories must be created: + +$ mkdir configs/<name>.<number> + +where <name> can be any string which is legal in a filesystem and the +<number> is the configuration's number, e.g.: + +$ mkdir configs/c.1 + +... +... +... + +Each configuration also needs its strings, so a subdirectory must be created +for each language, e.g.: + +$ mkdir configs/c.1/strings/0x409 + +Then the configuration string can be specified: + +$ echo <configuration> > configs/c.1/strings/0x409/configuration + +Some attributes can also be set for a configuration, e.g.: + +$ echo 120 > configs/c.1/MaxPower + +3. Creating the functions +------------------------- + +The gadget will provide some functions, for each function its corresponding +directory must be created: + +$ mkdir functions/<name>.<instance name> + +where <name> corresponds to one of allowed function names and instance name +is an arbitrary string allowed in a filesystem, e.g.: + +$ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module() + +... +... +... + +Each function provides its specific set of attributes, with either read-only +or read-write access. Where applicable they need to be written to as +appropriate. +Please refer to Documentation/ABI/*/configfs-usb-gadget* for more information. + +4. Associating the functions with their configurations +------------------------------------------------------ + +At this moment a number of gadgets is created, each of which has a number of +configurations specified and a number of functions available. What remains +is specifying which function is available in which configuration (the same +function can be used in multiple configurations). This is achieved with +creating symbolic links: + +$ ln -s functions/<name>.<instance name> configs/<name>.<number> + +e.g.: + +$ ln -s functions/ncm.usb0 configs/c.1 + +... +... +... + +5. Enabling the gadget +---------------------- + +All the above steps serve the purpose of composing the gadget of +configurations and functions. + +An example directory structure might look like this: + +. +./strings +./strings/0x409 +./strings/0x409/serialnumber +./strings/0x409/product +./strings/0x409/manufacturer +./configs +./configs/c.1 +./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0 +./configs/c.1/strings +./configs/c.1/strings/0x409 +./configs/c.1/strings/0x409/configuration +./configs/c.1/bmAttributes +./configs/c.1/MaxPower +./functions +./functions/ncm.usb0 +./functions/ncm.usb0/ifname +./functions/ncm.usb0/qmult +./functions/ncm.usb0/host_addr +./functions/ncm.usb0/dev_addr +./UDC +./bcdUSB +./bcdDevice +./idProduct +./idVendor +./bMaxPacketSize0 +./bDeviceProtocol +./bDeviceSubClass +./bDeviceClass + + +Such a gadget must be finally enabled so that the USB host can enumerate it. +In order to enable the gadget it must be bound to a UDC (USB Device Controller). + +$ echo <udc name> > UDC + +where <udc name> is one of those found in /sys/class/udc/* +e.g.: + +$ echo s3c-hsotg > UDC + + +6. Disabling the gadget +----------------------- + +$ echo "" > UDC + +7. Cleaning up +-------------- + +Remove functions from configurations: + +$ rm configs/<config name>.<number>/<function> + +where <config name>.<number> specify the configuration and <function> is +a symlink to a function being removed from the configuration, e.g.: + +$ rm configfs/c.1/ncm.usb0 + +... +... +... + +Remove strings directories in configurations + +$ rmdir configs/<config name>.<number>/strings/<lang> + +e.g.: + +$ rmdir configs/c.1/strings/0x409 + +... +... +... + +and remove the configurations + +$ rmdir configs/<config name>.<number> + +e.g.: + +rmdir configs/c.1 + +... +... +... + +Remove functions (function modules are not unloaded, though) + +$ rmdir functions/<name>.<instance name> + +e.g.: + +$ rmdir functions/ncm.usb0 + +... +... +... + +Remove strings directories in the gadget + +$ rmdir strings/<lang> + +e.g.: + +$ rmdir strings/0x409 + +and finally remove the gadget: + +$ cd .. +$ rmdir <gadget name> + +e.g.: + +$ rmdir g1 + + + + +Implementation design +===================== + +Below the idea of how configfs works is presented. +In configfs there are items and groups, both represented as directories. +The difference between an item and a group is that a group can contain +other groups. In the picture below only an item is shown. +Both items and groups can have attributes, which are represented as files. +The user can create and remove directories, but cannot remove files, +which can be read-only or read-write, depending on what they represent. + +The filesystem part of configfs operates on config_items/groups and +configfs_attributes which are generic and of the same type for all +configured elements. However, they are embedded in usage-specific +larger structures. In the picture below there is a "cs" which contains +a config_item and an "sa" which contains a configfs_attribute. + +The filesystem view would be like this: + +./ +./cs (directory) + | + +--sa (file) + | + . + . + . + +Whenever a user reads/writes the "sa" file, a function is called +which accepts a struct config_item and a struct configfs_attribute. +In the said function the "cs" and "sa" are retrieved using the well +known container_of technique and an appropriate sa's function (show or +store) is called and passed the "cs" and a character buffer. The "show" +is for displaying the file's contents (copy data from the cs to the +buffer), while the "store" is for modifying the file's contents (copy data +from the buffer to the cs), but it is up to the implementer of the +two functions to decide what they actually do. + +typedef struct configured_structure cs; +typedef struct specific_attribute sa; + + sa + +----------------------------------+ + cs | (*show)(cs *, buffer); | ++-----------------+ | (*store)(cs *, buffer, length); | +| | | | +| +-------------+ | | +------------------+ | +| | struct |-|----|------>|struct | | +| | config_item | | | |configfs_attribute| | +| +-------------+ | | +------------------+ | +| | +----------------------------------+ +| data to be set | . +| | . ++-----------------+ . + +The file names are decided by the config item/group designer, while +the directories in general can be named at will. A group can have +a number of its default sub-groups created automatically. + +For more information on configfs please see +Documentation/filesystems/configfs/*. + +The concepts described above translate to USB gadgets like this: + +1. A gadget has its config group, which has some attributes (idVendor, +idProduct etc) and default sub-groups (configs, functions, strings). +Writing to the attributes causes the information to be stored in +appropriate locations. In the configs, functions and strings sub-groups +a user can create their sub-groups to represent configurations, functions, +and groups of strings in a given language. + +2. The user creates configurations and functions, in the configurations +creates symbolic links to functions. This information is used when the +gadget's UDC attribute is written to, which means binding the gadget +to the UDC. The code in drivers/usb/gadget/configfs.c iterates over +all configurations, and in each configuration it iterates over all +functions and binds them. This way the whole gadget is bound. + +3. The file drivers/usb/gadget/configfs.c contains code for + + - gadget's config_group + - gadget's default groups (configs, functions, strings) + - associating functions with configurations (symlinks) + +4. Each USB function naturally has its own view of what it wants +configured, so config_groups for particular functions are defined +in the functions implementation files drivers/usb/gadget/f_*.c. + +5. Funciton's code is written in such a way that it uses + +usb_get_function_instance(), which, in turn, calls request_module. +So, provided that modprobe works, modules for particular functions +are loaded automatically. Please note that the converse is not true: +after a gadget is disabled and torn down, the modules remain loaded. diff --git a/Documentation/usb/gadget_hid.txt b/Documentation/usb/gadget_hid.txt new file mode 100644 index 00000000000..12696c2e43f --- /dev/null +++ b/Documentation/usb/gadget_hid.txt @@ -0,0 +1,445 @@ + + Linux USB HID gadget driver + +Introduction + + The HID Gadget driver provides emulation of USB Human Interface + Devices (HID). The basic HID handling is done in the kernel, + and HID reports can be sent/received through I/O on the + /dev/hidgX character devices. + + For more details about HID, see the developer page on + http://www.usb.org/developers/hidpage/ + +Configuration + + g_hid is a platform driver, so to use it you need to add + struct platform_device(s) to your platform code defining the + HID function descriptors you want to use - E.G. something + like: + +#include <linux/platform_device.h> +#include <linux/usb/g_hid.h> + +/* hid descriptor for a keyboard */ +static struct hidg_func_descriptor my_hid_data = { + .subclass = 0, /* No subclass */ + .protocol = 1, /* Keyboard */ + .report_length = 8, + .report_desc_length = 63, + .report_desc = { + 0x05, 0x01, /* USAGE_PAGE (Generic Desktop) */ + 0x09, 0x06, /* USAGE (Keyboard) */ + 0xa1, 0x01, /* COLLECTION (Application) */ + 0x05, 0x07, /* USAGE_PAGE (Keyboard) */ + 0x19, 0xe0, /* USAGE_MINIMUM (Keyboard LeftControl) */ + 0x29, 0xe7, /* USAGE_MAXIMUM (Keyboard Right GUI) */ + 0x15, 0x00, /* LOGICAL_MINIMUM (0) */ + 0x25, 0x01, /* LOGICAL_MAXIMUM (1) */ + 0x75, 0x01, /* REPORT_SIZE (1) */ + 0x95, 0x08, /* REPORT_COUNT (8) */ + 0x81, 0x02, /* INPUT (Data,Var,Abs) */ + 0x95, 0x01, /* REPORT_COUNT (1) */ + 0x75, 0x08, /* REPORT_SIZE (8) */ + 0x81, 0x03, /* INPUT (Cnst,Var,Abs) */ + 0x95, 0x05, /* REPORT_COUNT (5) */ + 0x75, 0x01, /* REPORT_SIZE (1) */ + 0x05, 0x08, /* USAGE_PAGE (LEDs) */ + 0x19, 0x01, /* USAGE_MINIMUM (Num Lock) */ + 0x29, 0x05, /* USAGE_MAXIMUM (Kana) */ + 0x91, 0x02, /* OUTPUT (Data,Var,Abs) */ + 0x95, 0x01, /* REPORT_COUNT (1) */ + 0x75, 0x03, /* REPORT_SIZE (3) */ + 0x91, 0x03, /* OUTPUT (Cnst,Var,Abs) */ + 0x95, 0x06, /* REPORT_COUNT (6) */ + 0x75, 0x08, /* REPORT_SIZE (8) */ + 0x15, 0x00, /* LOGICAL_MINIMUM (0) */ + 0x25, 0x65, /* LOGICAL_MAXIMUM (101) */ + 0x05, 0x07, /* USAGE_PAGE (Keyboard) */ + 0x19, 0x00, /* USAGE_MINIMUM (Reserved) */ + 0x29, 0x65, /* USAGE_MAXIMUM (Keyboard Application) */ + 0x81, 0x00, /* INPUT (Data,Ary,Abs) */ + 0xc0 /* END_COLLECTION */ + } +}; + +static struct platform_device my_hid = { + .name = "hidg", + .id = 0, + .num_resources = 0, + .resource = 0, + .dev.platform_data = &my_hid_data, +}; + + You can add as many HID functions as you want, only limited by + the amount of interrupt endpoints your gadget driver supports. + +Send and receive HID reports + + HID reports can be sent/received using read/write on the + /dev/hidgX character devices. See below for an example program + to do this. + + 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 + device type (keyboard / mouse / joystick) - E.G.: + + # hid_gadget_test /dev/hidg0 keyboard + + You are now in the prompt of hid_gadget_test. You can type any + combination of options and values. Available options and + values are listed at program start. In keyboard mode you can + send up to six values. + + For example type: g i s t r --left-shift + + Hit return and the corresponding report will be sent by the + HID gadget. + + Another interesting example is the caps lock test. Type + --caps-lock and hit return. A report is then sent by the + gadget and you should receive the host answer, corresponding + to the caps lock LED status. + + --caps-lock + recv report:2 + + With this command: + + # hid_gadget_test /dev/hidg1 mouse + + You can test the mouse emulation. Values are two signed numbers. + + +Sample code + +/* hid_gadget_test */ + +#include <pthread.h> +#include <string.h> +#include <stdio.h> +#include <ctype.h> +#include <fcntl.h> +#include <errno.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> + +#define BUF_LEN 512 + +struct options { + const char *opt; + unsigned char val; +}; + +static struct options kmod[] = { + {.opt = "--left-ctrl", .val = 0x01}, + {.opt = "--right-ctrl", .val = 0x10}, + {.opt = "--left-shift", .val = 0x02}, + {.opt = "--right-shift", .val = 0x20}, + {.opt = "--left-alt", .val = 0x04}, + {.opt = "--right-alt", .val = 0x40}, + {.opt = "--left-meta", .val = 0x08}, + {.opt = "--right-meta", .val = 0x80}, + {.opt = NULL} +}; + +static struct options kval[] = { + {.opt = "--return", .val = 0x28}, + {.opt = "--esc", .val = 0x29}, + {.opt = "--bckspc", .val = 0x2a}, + {.opt = "--tab", .val = 0x2b}, + {.opt = "--spacebar", .val = 0x2c}, + {.opt = "--caps-lock", .val = 0x39}, + {.opt = "--f1", .val = 0x3a}, + {.opt = "--f2", .val = 0x3b}, + {.opt = "--f3", .val = 0x3c}, + {.opt = "--f4", .val = 0x3d}, + {.opt = "--f5", .val = 0x3e}, + {.opt = "--f6", .val = 0x3f}, + {.opt = "--f7", .val = 0x40}, + {.opt = "--f8", .val = 0x41}, + {.opt = "--f9", .val = 0x42}, + {.opt = "--f10", .val = 0x43}, + {.opt = "--f11", .val = 0x44}, + {.opt = "--f12", .val = 0x45}, + {.opt = "--insert", .val = 0x49}, + {.opt = "--home", .val = 0x4a}, + {.opt = "--pageup", .val = 0x4b}, + {.opt = "--del", .val = 0x4c}, + {.opt = "--end", .val = 0x4d}, + {.opt = "--pagedown", .val = 0x4e}, + {.opt = "--right", .val = 0x4f}, + {.opt = "--left", .val = 0x50}, + {.opt = "--down", .val = 0x51}, + {.opt = "--kp-enter", .val = 0x58}, + {.opt = "--up", .val = 0x52}, + {.opt = "--num-lock", .val = 0x53}, + {.opt = NULL} +}; + +int keyboard_fill_report(char report[8], char buf[BUF_LEN], int *hold) +{ + char *tok = strtok(buf, " "); + int key = 0; + int i = 0; + + for (; tok != NULL; tok = strtok(NULL, " ")) { + + if (strcmp(tok, "--quit") == 0) + return -1; + + if (strcmp(tok, "--hold") == 0) { + *hold = 1; + continue; + } + + if (key < 6) { + for (i = 0; kval[i].opt != NULL; i++) + if (strcmp(tok, kval[i].opt) == 0) { + report[2 + key++] = kval[i].val; + break; + } + if (kval[i].opt != NULL) + continue; + } + + if (key < 6) + if (islower(tok[0])) { + report[2 + key++] = (tok[0] - ('a' - 0x04)); + continue; + } + + for (i = 0; kmod[i].opt != NULL; i++) + if (strcmp(tok, kmod[i].opt) == 0) { + report[0] = report[0] | kmod[i].val; + break; + } + if (kmod[i].opt != NULL) + continue; + + if (key < 6) + fprintf(stderr, "unknown option: %s\n", tok); + } + return 8; +} + +static struct options mmod[] = { + {.opt = "--b1", .val = 0x01}, + {.opt = "--b2", .val = 0x02}, + {.opt = "--b3", .val = 0x04}, + {.opt = NULL} +}; + +int mouse_fill_report(char report[8], char buf[BUF_LEN], int *hold) +{ + char *tok = strtok(buf, " "); + int mvt = 0; + int i = 0; + for (; tok != NULL; tok = strtok(NULL, " ")) { + + if (strcmp(tok, "--quit") == 0) + return -1; + + if (strcmp(tok, "--hold") == 0) { + *hold = 1; + continue; + } + + for (i = 0; mmod[i].opt != NULL; i++) + if (strcmp(tok, mmod[i].opt) == 0) { + report[0] = report[0] | mmod[i].val; + break; + } + if (mmod[i].opt != NULL) + continue; + + if (!(tok[0] == '-' && tok[1] == '-') && mvt < 2) { + errno = 0; + report[1 + mvt++] = (char)strtol(tok, NULL, 0); + if (errno != 0) { + fprintf(stderr, "Bad value:'%s'\n", tok); + report[1 + mvt--] = 0; + } + continue; + } + + fprintf(stderr, "unknown option: %s\n", tok); + } + return 3; +} + +static struct options jmod[] = { + {.opt = "--b1", .val = 0x10}, + {.opt = "--b2", .val = 0x20}, + {.opt = "--b3", .val = 0x40}, + {.opt = "--b4", .val = 0x80}, + {.opt = "--hat1", .val = 0x00}, + {.opt = "--hat2", .val = 0x01}, + {.opt = "--hat3", .val = 0x02}, + {.opt = "--hat4", .val = 0x03}, + {.opt = "--hatneutral", .val = 0x04}, + {.opt = NULL} +}; + +int joystick_fill_report(char report[8], char buf[BUF_LEN], int *hold) +{ + char *tok = strtok(buf, " "); + int mvt = 0; + int i = 0; + + *hold = 1; + + /* set default hat position: neutral */ + report[3] = 0x04; + + for (; tok != NULL; tok = strtok(NULL, " ")) { + + if (strcmp(tok, "--quit") == 0) + return -1; + + for (i = 0; jmod[i].opt != NULL; i++) + if (strcmp(tok, jmod[i].opt) == 0) { + report[3] = (report[3] & 0xF0) | jmod[i].val; + break; + } + if (jmod[i].opt != NULL) + continue; + + if (!(tok[0] == '-' && tok[1] == '-') && mvt < 3) { + errno = 0; + report[mvt++] = (char)strtol(tok, NULL, 0); + if (errno != 0) { + fprintf(stderr, "Bad value:'%s'\n", tok); + report[mvt--] = 0; + } + continue; + } + + fprintf(stderr, "unknown option: %s\n", tok); + } + return 4; +} + +void print_options(char c) +{ + int i = 0; + + if (c == 'k') { + printf(" keyboard options:\n" + " --hold\n"); + for (i = 0; kmod[i].opt != NULL; i++) + printf("\t\t%s\n", kmod[i].opt); + printf("\n keyboard values:\n" + " [a-z] or\n"); + for (i = 0; kval[i].opt != NULL; i++) + printf("\t\t%-8s%s", kval[i].opt, i % 2 ? "\n" : ""); + printf("\n"); + } else if (c == 'm') { + printf(" mouse options:\n" + " --hold\n"); + for (i = 0; mmod[i].opt != NULL; i++) + printf("\t\t%s\n", mmod[i].opt); + printf("\n mouse values:\n" + " Two signed numbers\n" + "--quit to close\n"); + } else { + printf(" joystick options:\n"); + for (i = 0; jmod[i].opt != NULL; i++) + printf("\t\t%s\n", jmod[i].opt); + printf("\n joystick values:\n" + " three signed numbers\n" + "--quit to close\n"); + } +} + +int main(int argc, const char *argv[]) +{ + const char *filename = NULL; + int fd = 0; + char buf[BUF_LEN]; + int cmd_len; + char report[8]; + int to_send = 8; + int hold = 0; + fd_set rfds; + int retval, i; + + if (argc < 3) { + fprintf(stderr, "Usage: %s devname mouse|keyboard|joystick\n", + argv[0]); + return 1; + } + + if (argv[2][0] != 'k' && argv[2][0] != 'm' && argv[2][0] != 'j') + return 2; + + filename = argv[1]; + + if ((fd = open(filename, O_RDWR, 0666)) == -1) { + perror(filename); + return 3; + } + + print_options(argv[2][0]); + + while (42) { + + FD_ZERO(&rfds); + FD_SET(STDIN_FILENO, &rfds); + FD_SET(fd, &rfds); + + retval = select(fd + 1, &rfds, NULL, NULL, NULL); + if (retval == -1 && errno == EINTR) + continue; + if (retval < 0) { + perror("select()"); + return 4; + } + + if (FD_ISSET(fd, &rfds)) { + cmd_len = read(fd, buf, BUF_LEN - 1); + printf("recv report:"); + for (i = 0; i < cmd_len; i++) + printf(" %02x", buf[i]); + printf("\n"); + } + + if (FD_ISSET(STDIN_FILENO, &rfds)) { + memset(report, 0x0, sizeof(report)); + cmd_len = read(STDIN_FILENO, buf, BUF_LEN - 1); + + if (cmd_len == 0) + break; + + buf[cmd_len - 1] = '\0'; + hold = 0; + + memset(report, 0x0, sizeof(report)); + if (argv[2][0] == 'k') + to_send = keyboard_fill_report(report, buf, &hold); + else if (argv[2][0] == 'm') + to_send = mouse_fill_report(report, buf, &hold); + else + to_send = joystick_fill_report(report, buf, &hold); + + if (to_send == -1) + break; + + if (write(fd, report, to_send) != to_send) { + perror(filename); + return 5; + } + if (!hold) { + memset(report, 0x0, sizeof(report)); + if (write(fd, report, to_send) != to_send) { + perror(filename); + return 6; + } + } + } + } + + close(fd); + return 0; +} diff --git a/Documentation/usb/gadget_multi.txt b/Documentation/usb/gadget_multi.txt new file mode 100644 index 00000000000..7d66a8636cb --- /dev/null +++ b/Documentation/usb/gadget_multi.txt @@ -0,0 +1,150 @@ + -*- org -*- + +* Overview + +The Multifunction Composite Gadget (or g_multi) is a composite gadget +that makes extensive use of the composite framework to provide +a... multifunction gadget. + +In it's standard configuration it provides a single USB configuration +with RNDIS[1] (that is Ethernet), USB CDC[2] ACM (that is serial) and +USB Mass Storage functions. + +A CDC ECM (Ethernet) function may be turned on via a Kconfig option +and RNDIS can be turned off. If they are both enabled the gadget will +have two configurations -- one with RNDIS and another with CDC ECM[3]. + +Please note that if you use non-standard configuration (that is enable +CDC ECM) you may need to change vendor and/or product ID. + +* Host drivers + +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. +As one might expect, things one need to do very from system to system. + +** Linux host drivers + +Since the gadget uses standard composite framework and appears as such +to Linux host it does not need any additional drivers on Linux host +side. All the functions are handled by respective drivers developed +for them. + +This is also true for two configuration set-up with RNDIS +configuration being the first one. Linux host will use the second +configuration with CDC ECM which should work better under Linux. + +** Windows host drivers + +For the gadget two work under Windows two conditions have to be met: + +*** Detecting as composite gadget + +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, +Windows lets USB Generic Parent Driver[5] handle the device which then +tries to much drivers for each individual interface (sort of, don't +get into too many details). + +The good news is: you do not have to worry about most of the +conditions! + +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 +create a proper INF -- and of course, if you do submit it! + +*** Installing drivers for each function + +The other, trickier thing is making Windows install drivers for each +individual function. + +For mass storage it is trivial since Windows detect it's an interface +implementing USB Mass Storage class and selects appropriate driver. + +Things are harder with RDNIS and CDC ACM. + +**** RNDIS + +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 +document. It "attaches" Window's RNDIS driver to the first interface +of the gadget. + +Please note, that while testing we encountered some issues[6] when +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 +out for this bug. + +**** CDC ACM + +Similarly, [[file:linux-cdc-acm.inf]] is provided for CDC ACM. + +**** Customising the gadget + +If you intend to hack the g_multi gadget be advised that rearranging +functions will obviously change interface numbers for each of the +functionality. As an effect provided INFs won't work since they have +interface numbers hard-coded in them (it's not hard to change those +though[7]). + +This also means, that after experimenting with g_multi and changing +provided functions one should change gadget's vendor and/or product ID +so there will be no collision with other customised gadgets or the +original gadget. + +Failing to comply may cause brain damage after wondering for hours why +things don't work as intended before realising Windows have cached +some drivers information (changing USB port may sometimes help plus +you might try using USBDeview[8] to remove the phantom device). + +**** INF testing + +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 +as well. It most likely won't work on Windows prior to Windows XP +SP2. + +** Other systems + +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 +believed that it should (read: "I have no idea whether it will") work +out-of-the-box. + +For more exotic systems I have even less to say... + +Any testing and drivers *are* *welcome*! + +* Authors + +This document has been written by Michal Nazarewicz +([[mailto:mina86@mina86.com]]). INF files have been hacked with +support of Marek Szyprowski ([[mailto:m.szyprowski@samsung.com]]) and +Xiaofan Chen ([[mailto:xiaofanc@gmail.com]]) basing on the MS RNDIS +template[9], Microchip's CDC ACM INF file and David Brownell's +([[mailto:dbrownell@users.sourceforge.net]]) original INF files. + +* Footnotes + +[1] Remote Network Driver Interface Specification, +[[http://msdn.microsoft.com/en-us/library/ee484414.aspx]]. + +[2] Communications Device Class Abstract Control Model, spec for this +and other USB classes can be found at +[[http://www.usb.org/developers/devclass_docs/]]. + +[3] CDC Ethernet Control Model. + +[4] [[http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]] + +[5] [[http://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]] + +[6] To put it in some other nice words, Windows failed to respond to +any user input. + +[7] You may find [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]] +useful. + +[8] http://www.nirsoft.net/utils/usb_devices_view.html + +[9] [[http://msdn.microsoft.com/en-us/library/ff570620.aspx]] diff --git a/Documentation/usb/gadget_serial.txt b/Documentation/usb/gadget_serial.txt index 815f5c2301f..61e67f6a20a 100644 --- a/Documentation/usb/gadget_serial.txt +++ b/Documentation/usb/gadget_serial.txt @@ -1,6 +1,7 @@ Linux Gadget Serial Driver v2.0 11/20/2004 + (updated 8-May-2008 for v2.3) License and Disclaimer @@ -31,7 +32,7 @@ Prerequisites ------------- Versions of the gadget serial driver are available for the 2.4 Linux kernels, but this document assumes you are using -version 2.0 or later of the gadget serial driver in a 2.6 +version 2.3 or later of the gadget serial driver in a 2.6 Linux kernel. This document assumes that you are familiar with Linux and @@ -40,6 +41,12 @@ standard utilities, use minicom and HyperTerminal, and work with USB and serial devices. It also assumes you configure the Linux gadget and usb drivers as modules. +With version 2.3 of the driver, major and minor device nodes are +no longer statically defined. Your Linux based system should mount +sysfs in /sys, and use "mdev" (in Busybox) or "udev" to make the +/dev nodes matching the sysfs /sys/class/tty files. + + Overview -------- @@ -104,27 +111,37 @@ driver. All this are listed under "USB Gadget Support" when configuring the kernel. Then rebuild and install the kernel or modules. -The gadget serial driver uses major number 127, for now. So you -will need to create a device node for it, like this: - - mknod /dev/ttygserial c 127 0 - -You only need to do this once. - Then you must load the gadget serial driver. To load it as an -ACM device, do this: +ACM device (recommended for interoperability), do this: - modprobe g_serial use_acm=1 + modprobe g_serial To load it as a vendor specific bulk in/out device, do this: - modprobe g_serial + modprobe g_serial use_acm=0 This will also automatically load the underlying gadget peripheral controller driver. This must be done each time you reboot the gadget side Linux system. You can add this to the start up scripts, if desired. +Your system should use mdev (from busybox) or udev to make the +device nodes. After this gadget driver has been set up you should +then see a /dev/ttyGS0 node: + + # ls -l /dev/ttyGS0 | cat + crw-rw---- 1 root root 253, 0 May 8 14:10 /dev/ttyGS0 + # + +Note that the major number (253, above) is system-specific. If +you need to create /dev nodes by hand, the right numbers to use +will be in the /sys/class/tty/ttyGS0/dev file. + +When you link this gadget driver early, perhaps even statically, +you may want to set up an /etc/inittab entry to run "getty" on it. +The /dev/ttyGS0 line should work like most any other serial port. + + If gadget serial is loaded as an ACM device you will want to use either the Windows or Linux ACM driver on the host side. If gadget serial is loaded as a bulk in/out device, you will want to use the @@ -134,88 +151,23 @@ instructions below to install the host side driver. Installing the Windows Host ACM Driver -------------------------------------- -To use the Windows ACM driver you must have the files "gserial.inf" -and "usbser.sys" together in a folder on the Windows machine. - -The "gserial.inf" file is given here. - --------------------- CUT HERE -------------------- -[Version] -Signature="$Windows NT$" -Class=Ports -ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318} -Provider=%LINUX% -DriverVer=08/17/2004,0.0.2.0 -; Copyright (C) 2004 Al Borchers (alborchers@steinerpoint.com) - -[Manufacturer] -%LINUX%=GSerialDeviceList - -[GSerialDeviceList] -%GSERIAL%=GSerialInstall, USB\VID_0525&PID_A4A7 - -[DestinationDirs] -DefaultDestDir=10,System32\Drivers - -[GSerialInstall] -CopyFiles=GSerialCopyFiles -AddReg=GSerialAddReg - -[GSerialCopyFiles] -usbser.sys - -[GSerialAddReg] -HKR,,DevLoader,,*ntkern -HKR,,NTMPDriver,,usbser.sys -HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" - -[GSerialInstall.Services] -AddService = usbser,0x0002,GSerialService - -[GSerialService] -DisplayName = %GSERIAL_DISPLAY_NAME% -ServiceType = 1 ; SERVICE_KERNEL_DRIVER -StartType = 3 ; SERVICE_DEMAND_START -ErrorControl = 1 ; SERVICE_ERROR_NORMAL -ServiceBinary = %10%\System32\Drivers\usbser.sys -LoadOrderGroup = Base - -[Strings] -LINUX = "Linux" -GSERIAL = "Gadget Serial" -GSERIAL_DISPLAY_NAME = "USB Gadget Serial Driver" --------------------- CUT HERE -------------------- - -The "usbser.sys" file comes with various versions of Windows. -For example, it can be found on Windows XP typically in - - C:\WINDOWS\Driver Cache\i386\driver.cab - -Or it can be found on the Windows 98SE CD in the "win98" folder -in the "DRIVER11.CAB" through "DRIVER20.CAB" cab files. You will -need the DOS "expand" program, the Cygwin "cabextract" program, or -a similar program to unpack these cab files and extract "usbser.sys". - -For example, to extract "usbser.sys" into the current directory -on Windows XP, open a DOS window and run a command like - - expand C:\WINDOWS\Driver~1\i386\driver.cab -F:usbser.sys . - -(Thanks to Nishant Kamat for pointing out this DOS command.) +To use the Windows ACM driver you must have the "linux-cdc-acm.inf" +file (provided along this document) which supports all recent versions +of Windows. When the gadget serial driver is loaded and the USB device connected to the Windows host with a USB cable, Windows should recognize the gadget serial device and ask for a driver. Tell Windows to find the -driver in the folder that contains "gserial.inf" and "usbser.sys". +driver in the folder that contains the "linux-cdc-acm.inf" file. For example, on Windows XP, when the gadget serial device is first plugged in, the "Found New Hardware Wizard" starts up. Select -"Install from a list or specific location (Advanced)", then on -the next screen select "Include this location in the search" and -enter the path or browse to the folder containing "gserial.inf" and -"usbser.sys". Windows will complain that the Gadget Serial driver -has not passed Windows Logo testing, but select "Continue anyway" -and finish the driver installation. +"Install from a list or specific location (Advanced)", then on the +next screen select "Include this location in the search" and enter the +path or browse to the folder containing the "linux-cdc-acm.inf" file. +Windows will complain that the Gadget Serial driver has not passed +Windows Logo testing, but select "Continue anyway" and finish the +driver installation. On Windows XP, in the "Device Manager" (under "Control Panel", "System", "Hardware") expand the "Ports (COM & LPT)" entry and you @@ -328,5 +280,3 @@ you should be able to send data back and forth between the gadget side and host side systems. Anything you type on the terminal window on the gadget side should appear in the terminal window on the host side and vice versa. - - diff --git a/Documentation/usb/hiddev.txt b/Documentation/usb/hiddev.txt deleted file mode 100644 index 6e8c9f1d2f2..00000000000 --- a/Documentation/usb/hiddev.txt +++ /dev/null @@ -1,205 +0,0 @@ -Care and feeding of your Human Interface Devices - -INTRODUCTION - -In addition to the normal input type HID devices, USB also uses the -human interface device protocols for things that are not really human -interfaces, but have similar sorts of communication needs. The two big -examples for this are power devices (especially uninterruptable power -supplies) and monitor control on higher end monitors. - -To support these disparate requirements, the Linux USB system provides -HID events to two separate interfaces: -* the input subsystem, which converts HID events into normal input -device interfaces (such as keyboard, mouse and joystick) and a -normalised event interface - see Documentation/input/input.txt -* the hiddev interface, which provides fairly raw HID events - -The data flow for a HID event produced by a device is something like -the following : - - usb.c ---> hid-core.c ----> hid-input.c ----> [keyboard/mouse/joystick/event] - | - | - --> hiddev.c ----> POWER / MONITOR CONTROL - -In addition, other subsystems (apart from USB) can potentially feed -events into the input subsystem, but these have no effect on the hid -device interface. - -USING THE HID DEVICE INTERFACE - -The hiddev interface is a char interface using the normal USB major, -with the minor numbers starting at 96 and finishing at 111. Therefore, -you need the following commands: -mknod /dev/usb/hiddev0 c 180 96 -mknod /dev/usb/hiddev1 c 180 97 -mknod /dev/usb/hiddev2 c 180 98 -mknod /dev/usb/hiddev3 c 180 99 -mknod /dev/usb/hiddev4 c 180 100 -mknod /dev/usb/hiddev5 c 180 101 -mknod /dev/usb/hiddev6 c 180 102 -mknod /dev/usb/hiddev7 c 180 103 -mknod /dev/usb/hiddev8 c 180 104 -mknod /dev/usb/hiddev9 c 180 105 -mknod /dev/usb/hiddev10 c 180 106 -mknod /dev/usb/hiddev11 c 180 107 -mknod /dev/usb/hiddev12 c 180 108 -mknod /dev/usb/hiddev13 c 180 109 -mknod /dev/usb/hiddev14 c 180 110 -mknod /dev/usb/hiddev15 c 180 111 - -So you point your hiddev compliant user-space program at the correct -interface for your device, and it all just works. - -Assuming that you have a hiddev compliant user-space program, of -course. If you need to write one, read on. - - -THE HIDDEV API -This description should be read in conjunction with the HID -specification, freely available from http://www.usb.org, and -conveniently linked of http://www.linux-usb.org. - -The hiddev API uses a read() interface, and a set of ioctl() calls. - -HID devices exchange data with the host computer using data -bundles called "reports". Each report is divided into "fields", -each of which can have one or more "usages". In the hid-core, -each one of these usages has a single signed 32 bit value. - -read(): -This is the event interface. When the HID device's state changes, -it performs an interrupt transfer containing a report which contains -the changed value. The hid-core.c module parses the report, and -returns to hiddev.c the individual usages that have changed within -the report. In its basic mode, the hiddev will make these individual -usage changes available to the reader using a struct hiddev_event: - - struct hiddev_event { - unsigned hid; - signed int value; - }; - -containing the HID usage identifier for the status that changed, and -the value that it was changed to. Note that the structure is defined -within <linux/hiddev.h>, along with some other useful #defines and -structures. The HID usage identifier is a composite of the HID usage -page shifted to the 16 high order bits ORed with the usage code. The -behavior of the read() function can be modified using the HIDIOCSFLAG -ioctl() described below. - - -ioctl(): -This is the control interface. There are a number of controls: - -HIDIOCGVERSION - int (read) -Gets the version code out of the hiddev driver. - -HIDIOCAPPLICATION - (none) -This ioctl call returns the HID application usage associated with the -hid device. The third argument to ioctl() specifies which application -index to get. This is useful when the device has more than one -application collection. If the index is invalid (greater or equal to -the number of application collections this device has) the ioctl -returns -1. You can find out beforehand how many application -collections the device has from the num_applications field from the -hiddev_devinfo structure. - -HIDIOCGCOLLECTIONINFO - struct hiddev_collection_info (read/write) -This returns a superset of the information above, providing not only -application collections, but all the collections the device has. It -also returns the level the collection lives in the hierarchy. -The user passes in a hiddev_collection_info struct with the index -field set to the index that should be returned. The ioctl fills in -the other fields. If the index is larger than the last collection -index, the ioctl returns -1 and sets errno to -EINVAL. - -HIDIOCGDEVINFO - struct hiddev_devinfo (read) -Gets a hiddev_devinfo structure which describes the device. - -HIDIOCGSTRING - struct hiddev_string_descriptor (read/write) -Gets a string descriptor from the device. The caller must fill in the -"index" field to indicate which descriptor should be returned. - -HIDIOCINITREPORT - (none) -Instructs the kernel to retrieve all input and feature report values -from the device. At this point, all the usage structures will contain -current values for the device, and will maintain it as the device -changes. Note that the use of this ioctl is unnecessary in general, -since later kernels automatically initialize the reports from the -device at attach time. - -HIDIOCGNAME - string (variable length) -Gets the device name - -HIDIOCGREPORT - struct hiddev_report_info (write) -Instructs the kernel to get a feature or input report from the device, -in order to selectively update the usage structures (in contrast to -INITREPORT). - -HIDIOCSREPORT - struct hiddev_report_info (write) -Instructs the kernel to send a report to the device. This report can -be filled in by the user through HIDIOCSUSAGE calls (below) to fill in -individual usage values in the report before sending the report in full -to the device. - -HIDIOCGREPORTINFO - struct hiddev_report_info (read/write) -Fills in a hiddev_report_info structure for the user. The report is -looked up by type (input, output or feature) and id, so these fields -must be filled in by the user. The ID can be absolute -- the actual -report id as reported by the device -- or relative -- -HID_REPORT_ID_FIRST for the first report, and (HID_REPORT_ID_NEXT | -report_id) for the next report after report_id. Without a-priori -information about report ids, the right way to use this ioctl is to -use the relative IDs above to enumerate the valid IDs. The ioctl -returns non-zero when there is no more next ID. The real report ID is -filled into the returned hiddev_report_info structure. - -HIDIOCGFIELDINFO - struct hiddev_field_info (read/write) -Returns the field information associated with a report in a -hiddev_field_info structure. The user must fill in report_id and -report_type in this structure, as above. The field_index should also -be filled in, which should be a number from 0 and maxfield-1, as -returned from a previous HIDIOCGREPORTINFO call. - -HIDIOCGUCODE - struct hiddev_usage_ref (read/write) -Returns the usage_code in a hiddev_usage_ref structure, given that -given its report type, report id, field index, and index within the -field have already been filled into the structure. - -HIDIOCGUSAGE - struct hiddev_usage_ref (read/write) -Returns the value of a usage in a hiddev_usage_ref structure. The -usage to be retrieved can be specified as above, or the user can -choose to fill in the report_type field and specify the report_id as -HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be -filled in with the report and field information associated with this -usage if it is found. - -HIDIOCSUSAGE - struct hiddev_usage_ref (write) -Sets the value of a usage in an output report. The user fills in -the hiddev_usage_ref structure as above, but additionally fills in -the value field. - -HIDIOGCOLLECTIONINDEX - struct hiddev_usage_ref (write) -Returns the collection index associated with this usage. This -indicates where in the collection hierarchy this usage sits. - -HIDIOCGFLAG - int (read) -HIDIOCSFLAG - int (write) -These operations respectively inspect and replace the mode flags -that influence the read() call above. The flags are as follows: - - HIDDEV_FLAG_UREF - read() calls will now return - struct hiddev_usage_ref instead of struct hiddev_event. - This is a larger structure, but in situations where the - device has more than one usage in its reports with the - same usage code, this mode serves to resolve such - ambiguity. - - HIDDEV_FLAG_REPORT - This flag can only be used in conjunction - with HIDDEV_FLAG_UREF. With this flag set, when the device - sends a report, a struct hiddev_usage_ref will be returned - to read() filled in with the report_type and report_id, but - with field_index set to FIELD_INDEX_NONE. This serves as - additional notification when the device has sent a report. diff --git a/Documentation/usb/hotplug.txt b/Documentation/usb/hotplug.txt index f53170665f3..6424b130485 100644 --- a/Documentation/usb/hotplug.txt +++ b/Documentation/usb/hotplug.txt @@ -10,7 +10,7 @@ immediately usable. That means the system must do many things, including: - Bind a driver to that device. Bus frameworks do that using a device driver's probe() routine. - + - Tell other subsystems to configure the new device. Print queues may need to be enabled, networks brought up, disk partitions mounted, and so on. In some cases these will @@ -33,9 +33,9 @@ you get the best hotplugging when you configure a highly modular system. KERNEL HOTPLUG HELPER (/sbin/hotplug) -When you compile with CONFIG_HOTPLUG, you get a new kernel parameter: -/proc/sys/kernel/hotplug, which normally holds the pathname "/sbin/hotplug". -That parameter names a program which the kernel may invoke at various times. +There is a kernel parameter: /proc/sys/kernel/hotplug, which normally +holds the pathname "/sbin/hotplug". That parameter names a program +which the kernel may invoke at various times. The /sbin/hotplug program can be invoked by any subsystem as part of its reaction to a configuration change, from a thread in that subsystem. @@ -84,7 +84,7 @@ USB MODUTILS SUPPORT Current versions of module-init-tools will create a "modules.usbmap" file which contains the entries from each driver's MODULE_DEVICE_TABLE. Such files can be used by various user mode policy agents to make sure all the -right driver modules get loaded, either at boot time or later. +right driver modules get loaded, either at boot time or later. See <linux/usb.h> for full information about such table entries; or look at existing drivers. Each table entry describes one or more criteria to diff --git a/Documentation/usb/linux-cdc-acm.inf b/Documentation/usb/linux-cdc-acm.inf new file mode 100644 index 00000000000..f0ffc27d4c0 --- /dev/null +++ b/Documentation/usb/linux-cdc-acm.inf @@ -0,0 +1,107 @@ +; Windows USB CDC ACM Setup File + +; Based on INF template which was: +; Copyright (c) 2000 Microsoft Corporation +; Copyright (c) 2007 Microchip Technology Inc. +; likely to be covered by the MLPL as found at: +; <http://msdn.microsoft.com/en-us/cc300389.aspx#MLPL>. +; For use only on Windows operating systems. + +[Version] +Signature="$Windows NT$" +Class=Ports +ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318} +Provider=%Linux% +DriverVer=11/15/2007,5.1.2600.0 + +[Manufacturer] +%Linux%=DeviceList, NTamd64 + +[DestinationDirs] +DefaultDestDir=12 + + +;------------------------------------------------------------------------------ +; Windows 2000/XP/Vista-32bit Sections +;------------------------------------------------------------------------------ + +[DriverInstall.nt] +include=mdmcpq.inf +CopyFiles=DriverCopyFiles.nt +AddReg=DriverInstall.nt.AddReg + +[DriverCopyFiles.nt] +usbser.sys,,,0x20 + +[DriverInstall.nt.AddReg] +HKR,,DevLoader,,*ntkern +HKR,,NTMPDriver,,USBSER.sys +HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" + +[DriverInstall.nt.Services] +AddService=usbser, 0x00000002, DriverService.nt + +[DriverService.nt] +DisplayName=%SERVICE% +ServiceType=1 +StartType=3 +ErrorControl=1 +ServiceBinary=%12%\USBSER.sys + +;------------------------------------------------------------------------------ +; Vista-64bit Sections +;------------------------------------------------------------------------------ + +[DriverInstall.NTamd64] +include=mdmcpq.inf +CopyFiles=DriverCopyFiles.NTamd64 +AddReg=DriverInstall.NTamd64.AddReg + +[DriverCopyFiles.NTamd64] +USBSER.sys,,,0x20 + +[DriverInstall.NTamd64.AddReg] +HKR,,DevLoader,,*ntkern +HKR,,NTMPDriver,,USBSER.sys +HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" + +[DriverInstall.NTamd64.Services] +AddService=usbser, 0x00000002, DriverService.NTamd64 + +[DriverService.NTamd64] +DisplayName=%SERVICE% +ServiceType=1 +StartType=3 +ErrorControl=1 +ServiceBinary=%12%\USBSER.sys + + +;------------------------------------------------------------------------------ +; Vendor and Product ID Definitions +;------------------------------------------------------------------------------ +; When developing your USB device, the VID and PID used in the PC side +; application program and the firmware on the microcontroller must match. +; Modify the below line to use your VID and PID. Use the format as shown +; below. +; Note: One INF file can be used for multiple devices with different +; VID and PIDs. For each supported device, append +; ",USB\VID_xxxx&PID_yyyy" to the end of the line. +;------------------------------------------------------------------------------ +[SourceDisksFiles] +[SourceDisksNames] +[DeviceList] +%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_1D6B&PID_0104&MI_02, USB\VID_1D6B&PID_0106&MI_00 + +[DeviceList.NTamd64] +%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_1D6B&PID_0104&MI_02, USB\VID_1D6B&PID_0106&MI_00 + + +;------------------------------------------------------------------------------ +; String Definitions +;------------------------------------------------------------------------------ +;Modify these strings to customize your device +;------------------------------------------------------------------------------ +[Strings] +Linux = "Linux Developer Community" +DESCRIPTION = "Gadget Serial" +SERVICE = "USB RS-232 Emulation Driver" diff --git a/Documentation/usb/linux.inf b/Documentation/usb/linux.inf index 2f7217d124f..4ffa715b0ae 100644 --- a/Documentation/usb/linux.inf +++ b/Documentation/usb/linux.inf @@ -1,200 +1,66 @@ -; MS-Windows driver config matching some basic modes of the -; Linux-USB Ethernet/RNDIS gadget firmware: -; -; - RNDIS plus CDC Ethernet ... this may be familiar as a DOCSIS -; cable modem profile, and supports most non-Microsoft USB hosts -; -; - RNDIS plus CDC Subset ... used by hardware that incapable of -; full CDC Ethernet support. -; -; Microsoft only directly supports RNDIS drivers, and bundled them into XP. -; The Microsoft "Remote NDIS USB Driver Kit" is currently found at: -; http://www.microsoft.com/whdc/hwdev/resources/HWservices/rndis.mspx - +; Based on template INF file found at +; <http://msdn.microsoft.com/en-us/library/ff570620.aspx> +; which was: +; Copyright (c) Microsoft Corporation +; and released under the MLPL as found at: +; <http://msdn.microsoft.com/en-us/cc300389.aspx#MLPL>. +; For use only on Windows operating systems. [Version] -Signature = "$CHICAGO$" +Signature = "$Windows NT$" Class = Net ClassGUID = {4d36e972-e325-11ce-bfc1-08002be10318} Provider = %Linux% -Compatible = 1 -MillenniumPreferred = .ME -DriverVer = 03/30/2004,0.0.0.0 -; catalog file would be used by WHQL -;CatalogFile = Linux.cat +DriverVer = 06/21/2006,6.0.6000.16384 [Manufacturer] -%Linux% = LinuxDevices,NT.5.1 +%Linux% = LinuxDevices,NTx86,NTamd64,NTia64 + +; Decoration for x86 architecture +[LinuxDevices.NTx86] +%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_1d6b&PID_0104&MI_00 -[LinuxDevices] -; NetChip IDs, used by both firmware modes -%LinuxDevice% = RNDIS, USB\VID_0525&PID_a4a2 +; Decoration for x64 architecture +[LinuxDevices.NTamd64] +%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_1d6b&PID_0104&MI_00 -[LinuxDevices.NT.5.1] -%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2 +; Decoration for ia64 architecture +[LinuxDevices.NTia64] +%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_1d6b&PID_0104&MI_00 +;@@@ This is the common setting for setup [ControlFlags] ExcludeFromSelect=* -; Windows 98, Windows 98 Second Edition specific sections -------- - -[RNDIS] -DeviceID = usb8023 -MaxInstance = 512 -DriverVer = 03/30/2004,0.0.0.0 -AddReg = RNDIS_AddReg_98, RNDIS_AddReg_Common - -[RNDIS_AddReg_98] -HKR, , DevLoader, 0, *ndis -HKR, , DeviceVxDs, 0, usb8023.sys -HKR, NDIS, LogDriverName, 0, "usb8023" -HKR, NDIS, MajorNdisVersion, 1, 5 -HKR, NDIS, MinorNdisVersion, 1, 0 -HKR, Ndi\Interfaces, DefUpper, 0, "ndis3,ndis4,ndis5" -HKR, Ndi\Interfaces, DefLower, 0, "ethernet" -HKR, Ndi\Interfaces, UpperRange, 0, "ndis3,ndis4,ndis5" -HKR, Ndi\Interfaces, LowerRange, 0, "ethernet" -HKR, Ndi\Install, ndis3, 0, "RNDIS_Install_98" -HKR, Ndi\Install, ndis4, 0, "RNDIS_Install_98" -HKR, Ndi\Install, ndis5, 0, "RNDIS_Install_98" -HKR, Ndi, DeviceId, 0, "USB\VID_0525&PID_a4a2" - -[RNDIS_Install_98] -CopyFiles=RNDIS_CopyFiles_98 - -[RNDIS_CopyFiles_98] -usb8023.sys, usb8023w.sys, , 0 -rndismp.sys, rndismpw.sys, , 0 - -; Windows Millennium Edition specific sections -------------------- - -[RNDIS.ME] -DeviceID = usb8023 -MaxInstance = 512 -DriverVer = 03/30/2004,0.0.0.0 -AddReg = RNDIS_AddReg_ME, RNDIS_AddReg_Common -Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI -BusType = 15 - -[RNDIS_AddReg_ME] -HKR, , DevLoader, 0, *ndis -HKR, , DeviceVxDs, 0, usb8023.sys -HKR, NDIS, LogDriverName, 0, "usb8023" -HKR, NDIS, MajorNdisVersion, 1, 5 -HKR, NDIS, MinorNdisVersion, 1, 0 -HKR, Ndi\Interfaces, DefUpper, 0, "ndis3,ndis4,ndis5" -HKR, Ndi\Interfaces, DefLower, 0, "ethernet" -HKR, Ndi\Interfaces, UpperRange, 0, "ndis3,ndis4,ndis5" -HKR, Ndi\Interfaces, LowerRange, 0, "ethernet" -HKR, Ndi\Install, ndis3, 0, "RNDIS_Install_ME" -HKR, Ndi\Install, ndis4, 0, "RNDIS_Install_ME" -HKR, Ndi\Install, ndis5, 0, "RNDIS_Install_ME" -HKR, Ndi, DeviceId, 0, "USB\VID_0525&PID_a4a2" - -[RNDIS_Install_ME] -CopyFiles=RNDIS_CopyFiles_ME - -[RNDIS_CopyFiles_ME] -usb8023.sys, usb8023m.sys, , 0 -rndismp.sys, rndismpm.sys, , 0 - -; Windows 2000 specific sections --------------------------------- - -[RNDIS.NT] -Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI -BusType = 15 -DriverVer = 03/30/2004,0.0.0.0 -AddReg = RNDIS_AddReg_NT, RNDIS_AddReg_Common -CopyFiles = RNDIS_CopyFiles_NT - -[RNDIS.NT.Services] -AddService = USB_RNDIS, 2, RNDIS_ServiceInst_NT, RNDIS_EventLog - -[RNDIS_CopyFiles_NT] -; no rename of files on Windows 2000, use the 'k' names as is -usb8023k.sys, , , 0 -rndismpk.sys, , , 0 - -[RNDIS_ServiceInst_NT] -DisplayName = %ServiceDisplayName% -ServiceType = 1 -StartType = 3 -ErrorControl = 1 -ServiceBinary = %12%\usb8023k.sys -LoadOrderGroup = NDIS -AddReg = RNDIS_WMI_AddReg_NT - -[RNDIS_WMI_AddReg_NT] -HKR, , MofImagePath, 0x00020000, "System32\drivers\rndismpk.sys" - -; Windows XP specific sections ----------------------------------- - +; DDInstall section +; References the in-build Netrndis.inf [RNDIS.NT.5.1] -Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI -BusType = 15 -DriverVer = 03/30/2004,0.0.0.0 -AddReg = RNDIS_AddReg_NT, RNDIS_AddReg_Common -; no copyfiles - the files are already in place - +Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI +BusType = 15 +; NEVER REMOVE THE FOLLOWING REFERENCE FOR NETRNDIS.INF +include = netrndis.inf +needs = Usb_Rndis.ndi +AddReg = Rndis_AddReg_Vista + +; DDInstal.Services section [RNDIS.NT.5.1.Services] -AddService = USB_RNDIS, 2, RNDIS_ServiceInst_51, RNDIS_EventLog - -[RNDIS_ServiceInst_51] -DisplayName = %ServiceDisplayName% -ServiceType = 1 -StartType = 3 -ErrorControl = 1 -ServiceBinary = %12%\usb8023.sys -LoadOrderGroup = NDIS -AddReg = RNDIS_WMI_AddReg_51 - -[RNDIS_WMI_AddReg_51] -HKR, , MofImagePath, 0x00020000, "System32\drivers\rndismp.sys" - -; Windows 2000 and Windows XP common sections -------------------- - -[RNDIS_AddReg_NT] -HKR, Ndi, Service, 0, "USB_RNDIS" -HKR, Ndi\Interfaces, UpperRange, 0, "ndis5" -HKR, Ndi\Interfaces, LowerRange, 0, "ethernet" - -[RNDIS_EventLog] -AddReg = RNDIS_EventLog_AddReg - -[RNDIS_EventLog_AddReg] -HKR, , EventMessageFile, 0x00020000, "%%SystemRoot%%\System32\netevent.dll" -HKR, , TypesSupported, 0x00010001, 7 - -; Common Sections ------------------------------------------------- - -[RNDIS_AddReg_Common] -HKR, NDI\params\NetworkAddress, ParamDesc, 0, %NetworkAddress% -HKR, NDI\params\NetworkAddress, type, 0, "edit" -HKR, NDI\params\NetworkAddress, LimitText, 0, "12" -HKR, NDI\params\NetworkAddress, UpperCase, 0, "1" -HKR, NDI\params\NetworkAddress, default, 0, " " -HKR, NDI\params\NetworkAddress, optional, 0, "1" - -[SourceDisksNames] -1=%SourceDisk%,,1 - -[SourceDisksFiles] -usb8023m.sys=1 -rndismpm.sys=1 -usb8023w.sys=1 -rndismpw.sys=1 -usb8023k.sys=1 -rndismpk.sys=1 - -[DestinationDirs] -RNDIS_CopyFiles_98 = 10, system32/drivers -RNDIS_CopyFiles_ME = 10, system32/drivers -RNDIS_CopyFiles_NT = 12 +include = netrndis.inf +needs = Usb_Rndis.ndi.Services + +; Optional registry settings. You can modify as needed. +[RNDIS_AddReg_Vista] +HKR, NDI\params\VistaProperty, ParamDesc, 0, %Vista_Property% +HKR, NDI\params\VistaProperty, type, 0, "edit" +HKR, NDI\params\VistaProperty, LimitText, 0, "12" +HKR, NDI\params\VistaProperty, UpperCase, 0, "1" +HKR, NDI\params\VistaProperty, default, 0, " " +HKR, NDI\params\VistaProperty, optional, 0, "1" + +; No sys copyfiles - the sys files are already in-build +; (part of the operating system). +; We do not support XP SP1-, 2003 SP1-, ME, 9x. [Strings] -ServiceDisplayName = "USB Remote NDIS Network Device Driver" -NetworkAddress = "Network Address" Linux = "Linux Developer Community" LinuxDevice = "Linux USB Ethernet/RNDIS Gadget" -SourceDisk = "Ethernet/RNDIS Gadget Driver Install Disk" - +Vista_Property = "Optional Vista Property" diff --git a/Documentation/usb/mass-storage.txt b/Documentation/usb/mass-storage.txt new file mode 100644 index 00000000000..e89803a5a96 --- /dev/null +++ b/Documentation/usb/mass-storage.txt @@ -0,0 +1,225 @@ +* Overview + + 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 + multiple logical units (LUNs). Backing storage for each LUN is + provided by a regular file or a block device, access can be limited + to read-only, and gadget can indicate that it is removable and/or + CD-ROM (the latter implies read-only access). + + Its requirements are modest; only a bulk-in and a bulk-out endpoint + are needed. The memory requirement amounts to two 16K buffers. + Support is included for full-speed, high-speed and SuperSpeed + operation. + + Note that the driver is slightly non-portable in that it assumes + a single memory/DMA buffer will be usable for bulk-in and bulk-out + endpoints. With most device controllers this is not an issue, but + there may be some with hardware restrictions that prevent a buffer + from being used by more than one endpoint. + + This document describes how to use the gadget from user space, its + relation to mass storage function (or MSF) and different gadgets + using it, and how it differs from File Storage Gadget (or FSG) + (which is no longer included in Linux). It will talk only briefly + about how to use MSF within composite gadgets. + +* Module parameters + + The mass storage gadget accepts the following mass storage specific + module parameters: + + - file=filename[,filename...] + + This parameter lists paths to files or block devices used for + backing storage for each logical unit. There may be at most + FSG_MAX_LUNS (8) LUNs set. If more files are specified, they will + be silently ignored. See also “luns” parameter. + + *BEWARE* that if a file is used as a backing storage, it may not + be modified by any other process. This is because the host + assumes the data does not change without its knowledge. It may be + read, but (if the logical unit is writable) due to buffering on + the host side, the contents are not well defined. + + The size of the logical unit will be rounded down to a full + logical block. The logical block size is 2048 bytes for LUNs + simulating CD-ROM, block size of the device if the backing file is + a block device, or 512 bytes otherwise. + + - removable=b[,b...] + + This parameter specifies whether each logical unit should be + removable. “b” here is either “y”, “Y” or “1” for true or “n”, + “N” or “0” for false. + + If this option is set for a logical unit, gadget will accept an + “eject” SCSI request (Start/Stop Unit). When it is sent, the + backing file will be closed to simulate ejection and the logical + unit will not be mountable by the host until a new backing file is + specified by userspace on the device (see “sysfs entries” + section). + + If a logical unit is not removable (the default), a backing file + must be specified for it with the “file” parameter as the module + is loaded. The same applies if the module is built in, no + exceptions. + + The default value of the flag is false, *HOWEVER* it used to be + true. This has been changed to better match File Storage Gadget + and because it seems like a saner default after all. Thus to + maintain compatibility with older kernels, it's best to specify + the default values. Also, if one relied on old default, explicit + “n” needs to be specified now. + + Note that “removable” means the logical unit's media can be + ejected or removed (as is true for a CD-ROM drive or a card + reader). It does *not* mean that the entire gadget can be + unplugged from the host; the proper term for that is + “hot-unpluggable”. + + - cdrom=b[,b...] + + This parameter specifies whether each logical unit should simulate + CD-ROM. The default is false. + + - ro=b[,b...] + + This parameter specifies whether each logical unit should be + reported as read only. This will prevent host from modifying the + backing files. + + Note that if this flag for given logical unit is false but the + backing file could not be opened in read/write mode, the gadget + will fall back to read only mode anyway. + + The default value for non-CD-ROM logical units is false; for + logical units simulating CD-ROM it is forced to true. + + - nofua=b[,b...] + + This parameter specifies whether FUA flag should be ignored in SCSI + Write10 and Write12 commands sent to given logical units. + + MS Windows mounts removable storage in “Removal optimised mode” by + default. All the writes to the media are synchronous, which is + achieved by setting the FUA (Force Unit Access) bit in SCSI + Write(10,12) commands. This forces each write to wait until the + data has actually been written out and prevents I/O requests + aggregation in block layer dramatically decreasing performance. + + Note that this may mean that if the device is powered from USB and + the user unplugs the device without unmounting it first (which at + least some Windows users do), the data may be lost. + + The default value is false. + + - luns=N + + This parameter specifies number of logical units the gadget will + have. It is limited by FSG_MAX_LUNS (8) and higher value will be + capped. + + If this parameter is provided, and the number of files specified + in “file” argument is greater then the value of “luns”, all excess + files will be ignored. + + If this parameter is not present, the number of logical units will + be deduced from the number of files specified in the “file” + parameter. If the file parameter is missing as well, one is + assumed. + + - stall=b + + Specifies whether the gadget is allowed to halt bulk endpoints. + The default is determined according to the type of USB device + controller, but usually true. + + In addition to the above, the gadget also accepts the following + parameters defined by the composite framework (they are common to + all composite gadgets so just a quick listing): + + - idVendor -- USB Vendor ID (16 bit integer) + - idProduct -- USB Product ID (16 bit integer) + - bcdDevice -- USB Device version (BCD) (16 bit integer) + - iManufacturer -- USB Manufacturer string (string) + - iProduct -- USB Product string (string) + - iSerialNumber -- SerialNumber string (sting) + +* sysfs entries + + For each logical unit, the gadget creates a directory in the sysfs + hierarchy. Inside of it the following three files are created: + + - file + + When read it returns the path to the backing file for the given + logical unit. If there is no backing file (possible only if the + logical unit is removable), the content is empty. + + When written into, it changes the backing file for given logical + unit. This change can be performed even if given logical unit is + not specified as removable (but that may look strange to the + host). It may fail, however, if host disallowed medium removal + with the Prevent-Allow Medium Removal SCSI command. + + - ro + + Reflects the state of ro flag for the given logical unit. It can + be read any time, and written to when there is no backing file + open for given logical unit. + + - nofua + + Reflects the state of nofua flag for given logical unit. It can + be read and written. + + Other then those, as usual, the values of module parameters can be + read from /sys/module/g_mass_storage/parameters/* files. + +* Other gadgets using mass storage function + + The Mass Storage Gadget uses the Mass Storage Function to handle + mass storage protocol. As a composite function, MSF may be used by + other gadgets as well (eg. g_multi and acm_ms). + + All of the information in previous sections are valid for other + gadgets using MSF, except that support for mass storage related + module parameters may be missing, or the parameters may have + a prefix. To figure out whether any of this is true one needs to + consult the gadget's documentation or its source code. + + For examples of how to include mass storage function in gadgets, one + may take a look at mass_storage.c, acm_ms.c and multi.c (sorted by + complexity). + +* Relation to file storage gadget + + The Mass Storage Function and thus the Mass Storage Gadget has been + based on the File Storage Gadget. The difference between the two is + that MSG is a composite gadget (ie. uses the composite framework) + while file storage gadget was a traditional gadget. From userspace + point of view this distinction does not really matter, but from + kernel hacker's point of view, this means that (i) MSG does not + duplicate code needed for handling basic USB protocol commands and + (ii) MSF can be used in any other composite gadget. + + Because of that, File Storage Gadget has been removed in Linux 3.8. + All users need to transition to the Mass Storage Gadget. The two + gadgets behave mostly the same from the outside except: + + 1. In FSG the “removable” and “cdrom” module parameters set the flag + for all logical units whereas in MSG they accept a list of y/n + values for each logical unit. If one uses only a single logical + unit this does not matter, but if there are more, the y/n value + needs to be repeated for each logical unit. + + 2. FSG's “serial”, “vendor”, “product” and “release” module + parameters are handled in MSG by the composite layer's parameters + named respectively: “iSerialnumber”, “idVendor”, “idProduct” and + “bcdDevice”. + + 3. MSG does not support FSG's test mode, thus “transport”, + “protocol” and “buflen” FSG's module parameters are not + supported. MSG always uses SCSI protocol with bulk only + transport mode and 16 KiB buffers. diff --git a/Documentation/usb/misc_usbsevseg.txt b/Documentation/usb/misc_usbsevseg.txt new file mode 100644 index 00000000000..0f6be4f9930 --- /dev/null +++ b/Documentation/usb/misc_usbsevseg.txt @@ -0,0 +1,46 @@ +USB 7-Segment Numeric Display +Manufactured by Delcom Engineering + +Device Information +------------------ +USB VENDOR_ID 0x0fc5 +USB PRODUCT_ID 0x1227 +Both the 6 character and 8 character displays have PRODUCT_ID, +and according to Delcom Engineering no queryable information +can be obtained from the device to tell them apart. + +Device Modes +------------ +By default, the driver assumes the display is only 6 characters +The mode for 6 characters is: + MSB 0x06; LSB 0x3f +For the 8 character display: + MSB 0x08; LSB 0xff +The device can accept "text" either in raw, hex, or ascii textmode. +raw controls each segment manually, +hex expects a value between 0-15 per character, +ascii expects a value between '0'-'9' and 'A'-'F'. +The default is ascii. + +Device Operation +---------------- +1. Turn on the device: + echo 1 > /sys/bus/usb/.../powered +2. Set the device's mode: + echo $mode_msb > /sys/bus/usb/.../mode_msb + echo $mode_lsb > /sys/bus/usb/.../mode_lsb +3. Set the textmode: + echo $textmode > /sys/bus/usb/.../textmode +4. set the text (for example): + echo "123ABC" > /sys/bus/usb/.../text (ascii) + echo "A1B2" > /sys/bus/usb/.../text (ascii) + echo -ne "\x01\x02\x03" > /sys/bus/usb/.../text (hex) +5. Set the decimal places. + The device has either 6 or 8 decimal points. + to set the nth decimal place calculate 10 ** n + and echo it in to /sys/bus/usb/.../decimals + To set multiple decimals points sum up each power. + For example, to set the 0th and 3rd decimal place + echo 1001 > /sys/bus/usb/.../decimals + + diff --git a/Documentation/usb/mtouchusb.txt b/Documentation/usb/mtouchusb.txt index e43cfffaa10..a91adb26ea7 100644 --- a/Documentation/usb/mtouchusb.txt +++ b/Documentation/usb/mtouchusb.txt @@ -1,7 +1,7 @@ CHANGES - 0.3 - Created based off of scanner & INSTALL from the original touchscreen - driver on freshmeat (http://freshmeat.net/projects/3mtouchscreendriver) + driver on freecode (http://freecode.com/projects/3mtouchscreendriver) - Amended for linux-2.4.18, then 2.4.19 - 0.5 - Complete rewrite using Linux Input in 2.6.3 @@ -54,10 +54,6 @@ generic functions like calibrations, resets, and vendor information can be requested from the userspace (And the drivers would handle the vendor specific tasks). -ADDITIONAL INFORMATION/UPDATES/X CONFIGURATION EXAMPLE: - -http://groomlakelabs.com/grandamp/code/microtouch/ - TODO: Implement a control urb again to handle requests to and from the device @@ -68,7 +64,7 @@ DISCLAIMER: 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: -http://www.3m.com/3MTouchSystems/downloads/ +http://www.3m.com/3MTouchSystems/ THANKS: diff --git a/Documentation/usb/persist.txt b/Documentation/usb/persist.txt index df54d645cbb..35d70eda9ad 100644 --- a/Documentation/usb/persist.txt +++ b/Documentation/usb/persist.txt @@ -2,7 +2,7 @@ Alan Stern <stern@rowland.harvard.edu> - September 2, 2006 (Updated May 29, 2007) + September 2, 2006 (Updated February 25, 2008) What is the problem? @@ -65,9 +65,10 @@ much better.) What is the solution? -Setting CONFIG_USB_PERSIST will cause the kernel to work around these -issues. It enables a mode in which the core USB device data -structures are allowed to persist across a power-session disruption. +The kernel includes a feature called USB-persist. It tries to work +around these issues by allowing the core USB device data structures to +persist across a power-session disruption. + It works like this. If the kernel sees that a USB host controller is not in the expected state during resume (i.e., if the controller was reset or otherwise had lost power) then it applies a persistence check @@ -82,26 +83,31 @@ the kernel continues to use the same device structure. In effect, the kernel treats the device as though it had merely been reset instead of unplugged. +The same thing happens if the host controller is in the expected state +but a USB device was unplugged and then replugged, or if a USB device +fails to carry out a normal resume. + If no device is now attached to the port, or if the descriptors are different from what the kernel remembers, then the treatment is what you would expect. The kernel destroys the old device structure and behaves as though the old device had been unplugged and a new device -plugged in, just as it would without the CONFIG_USB_PERSIST option. +plugged in. The end result is that the USB device remains available and usable. Filesystem mounts and memory mappings are unaffected, and the world is now a good and happy place. -Note that even when CONFIG_USB_PERSIST is set, the "persist" feature -will be applied only to those devices for which it is enabled. You -can enable the feature by doing (as root): +Note that the "USB-persist" feature will be applied only to those +devices for which it is enabled. You can enable the feature by doing +(as root): echo 1 >/sys/bus/usb/devices/.../power/persist where the "..." should be filled in the with the device's ID. Disable the feature by writing 0 instead of 1. For hubs the feature is -automatically and permanently enabled, so you only have to worry about -setting it for devices where it really matters. +automatically and permanently enabled and the power/persist file +doesn't even exist, so you only have to worry about setting it for +devices where it really matters. Is this the best solution? @@ -112,19 +118,19 @@ centralized Logical Volume Manager. Such a solution would allow you to plug in a USB flash device, create a persistent volume associated with it, unplug the flash device, plug it back in later, and still have the same persistent volume associated with the device. As such -it would be more far-reaching than CONFIG_USB_PERSIST. +it would be more far-reaching than USB-persist. On the other hand, writing a persistent volume manager would be a big job and using it would require significant input from the user. This solution is much quicker and easier -- and it exists now, a giant point in its favor! -Furthermore, the USB_PERSIST option applies to _all_ USB devices, not +Furthermore, the USB-persist feature applies to _all_ USB devices, not just mass-storage devices. It might turn out to be equally useful for other device types, such as network interfaces. - WARNING: Using CONFIG_USB_PERSIST can be dangerous!! + WARNING: USB-persist can be dangerous!! When recovering an interrupted power session the kernel does its best to make sure the USB device hasn't been changed; that is, the same @@ -133,10 +139,10 @@ aren't guaranteed to be 100% accurate. If you replace one USB device with another of the same type (same manufacturer, same IDs, and so on) there's an excellent chance the -kernel won't detect the change. Serial numbers and other strings are -not compared. In many cases it wouldn't help if they were, because -manufacturers frequently omit serial numbers entirely in their -devices. +kernel won't detect the change. The serial number string and other +descriptors are compared with the kernel's stored values, but this +might not help since manufacturers frequently omit serial numbers +entirely in their devices. Furthermore it's quite possible to leave a USB device exactly the same while changing its media. If you replace the flash memory card in a @@ -149,8 +155,11 @@ If the kernel gets fooled in this way, it's almost certain to cause data corruption and to crash your system. You'll have no one to blame but yourself. +For those devices with avoid_reset_quirk attribute being set, persist +maybe fail because they may morph after reset. + YOU HAVE BEEN WARNED! USE AT YOUR OWN RISK! That having been said, most of the time there shouldn't be any trouble -at all. The "persist" feature can be extremely useful. Make the most -of it. +at all. The USB-persist feature can be extremely useful. Make the +most of it. diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt index b2fc4d4a991..1392b61d6eb 100644 --- a/Documentation/usb/power-management.txt +++ b/Documentation/usb/power-management.txt @@ -2,7 +2,7 @@ Alan Stern <stern@rowland.harvard.edu> - October 5, 2007 + October 28, 2010 @@ -29,9 +29,13 @@ covered to some extent (see Documentation/power/*.txt for more information about system PM). Note: Dynamic PM support for USB is present only if the kernel was -built with CONFIG_USB_SUSPEND enabled. System PM support is present -only if the kernel was built with CONFIG_SUSPEND or CONFIG_HIBERNATION -enabled. +built with CONFIG_USB_SUSPEND enabled (which depends on +CONFIG_PM_RUNTIME). System PM support is present only if the kernel +was built with CONFIG_SUSPEND or CONFIG_HIBERNATION enabled. + +(Starting with the 3.10 kernel release, dynamic PM support for USB is +present whenever the kernel was built with CONFIG_PM_RUNTIME enabled. +The CONFIG_USB_SUSPEND option has been eliminated.) What is Remote Wakeup? @@ -71,12 +75,10 @@ being accessed through sysfs, then it definitely is idle. Forms of dynamic PM ------------------- -Dynamic suspends can occur in two ways: manual and automatic. -"Manual" means that the user has told the kernel to suspend a device, -whereas "automatic" means that the kernel has decided all by itself to -suspend a device. Automatic suspend is called "autosuspend" for -short. In general, a device won't be autosuspended unless it has been -idle for some minimum period of time, the so-called idle-delay time. +Dynamic suspends occur when the kernel decides to suspend an idle +device. This is called "autosuspend" for short. In general, a device +won't be autosuspended unless it has been idle for some minimum period +of time, the so-called idle-delay time. Of course, nothing the kernel does on its own initiative should prevent the computer or its devices from working properly. If a @@ -96,10 +98,11 @@ idle. We can categorize power management events in two broad classes: external and internal. External events are those triggered by some agent outside the USB stack: system suspend/resume (triggered by -userspace), manual dynamic suspend/resume (also triggered by -userspace), and remote wakeup (triggered by the device). Internal -events are those triggered within the USB stack: autosuspend and -autoresume. +userspace), manual dynamic resume (also triggered by userspace), and +remote wakeup (triggered by the device). Internal events are those +triggered within the USB stack: autosuspend and autoresume. Note that +all dynamic suspend events are internal; external agents are not +allowed to issue dynamic suspends. The user interface for dynamic PM @@ -108,7 +111,14 @@ autoresume. The user interface for controlling dynamic PM is located in the power/ subdirectory of each USB device's sysfs directory, that is, in /sys/bus/usb/devices/.../power/ where "..." is the device's ID. The -relevant attribute files are: wakeup, level, and autosuspend. +relevant attribute files are: wakeup, control, and +autosuspend_delay_ms. (There may also be a file named "level"; this +file was deprecated as of the 2.6.35 kernel and replaced by the +"control" file. In 2.6.38 the "autosuspend" file will be deprecated +and replaced by the "autosuspend_delay_ms" file. The only difference +is that the newer file expresses the delay in milliseconds whereas the +older file uses seconds. Confusingly, both files are present in 2.6.37 +but only "autosuspend" works.) power/wakeup @@ -121,11 +131,11 @@ relevant attribute files are: wakeup, level, and autosuspend. while the device is suspended, the change won't take effect until the following suspend.) - power/level + power/control - This file contains one of three words: "on", "auto", - or "suspend". You can write those words to the file - to change the device's setting. + This file contains one of two words: "on" or "auto". + You can write those words to the file to change the + device's setting. "on" means that the device should be resumed and autosuspend is not allowed. (Of course, system @@ -134,42 +144,47 @@ relevant attribute files are: wakeup, level, and autosuspend. "auto" is the normal state in which the kernel is allowed to autosuspend and autoresume the device. - "suspend" means that the device should remain - suspended, and autoresume is not allowed. (But remote - wakeup may still be allowed, since it is controlled - separately by the power/wakeup attribute.) + (In kernels up to 2.6.32, you could also specify + "suspend", meaning that the device should remain + suspended and autoresume was not allowed. This + setting is no longer supported.) - power/autosuspend + power/autosuspend_delay_ms This file contains an integer value, which is the - number of seconds the device should remain idle before - the kernel will autosuspend it (the idle-delay time). - The default is 2. 0 means to autosuspend as soon as - the device becomes idle, and -1 means never to - autosuspend. You can write a number to the file to - change the autosuspend idle-delay time. - -Writing "-1" to power/autosuspend and writing "on" to power/level do -essentially the same thing -- they both prevent the device from being -autosuspended. Yes, this is a redundancy in the API. + number of milliseconds the device should remain idle + before the kernel will autosuspend it (the idle-delay + time). The default is 2000. 0 means to autosuspend + as soon as the device becomes idle, and negative + values mean never to autosuspend. You can write a + number to the file to change the autosuspend + idle-delay time. + +Writing "-1" to power/autosuspend_delay_ms and writing "on" to +power/control do essentially the same thing -- they both prevent the +device from being autosuspended. Yes, this is a redundancy in the +API. (In 2.6.21 writing "0" to power/autosuspend would prevent the device from being autosuspended; the behavior was changed in 2.6.22. The power/autosuspend attribute did not exist prior to 2.6.21, and the -power/level attribute did not exist prior to 2.6.22.) +power/level attribute did not exist prior to 2.6.22. power/control +was added in 2.6.34, and power/autosuspend_delay_ms was added in +2.6.37 but did not become functional until 2.6.38.) Changing the default idle-delay time ------------------------------------ -The default autosuspend idle-delay time is controlled by a module -parameter in usbcore. You can specify the value when usbcore is -loaded. For example, to set it to 5 seconds instead of 2 you would +The default autosuspend idle-delay time (in seconds) is controlled by +a module parameter in usbcore. You can specify the value when usbcore +is loaded. For example, to set it to 5 seconds instead of 2 you would do: modprobe usbcore autosuspend=5 -Equivalently, you could add to /etc/modprobe.conf a line saying: +Equivalently, you could add to a configuration file in /etc/modprobe.d +a line saying: options usbcore autosuspend=5 @@ -195,10 +210,8 @@ initialized to 5. (The idle-delay values for already existing devices will not be affected.) Setting the initial default idle-delay to -1 will prevent any -autosuspend of any USB device. This is a simple alternative to -disabling CONFIG_USB_SUSPEND and rebuilding the kernel, and it has the -added benefit of allowing you to enable autosuspend for selected -devices. +autosuspend of any USB device. This has the benefit of allowing you +then to enable autosuspend for selected devices. Warnings @@ -213,7 +226,7 @@ among printers and scanners, but plenty of other types of device have the same deficiency. For this reason, by default the kernel disables autosuspend (the -power/level attribute is initialized to "on") for all devices other +power/control attribute is initialized to "on") for all devices other than hubs. Hubs, at least, appear to be reasonably well-behaved in this regard. @@ -230,22 +243,25 @@ necessary operations by hand or add them to a udev script. You can also change the idle-delay time; 2 seconds is not the best choice for every device. +If a driver knows that its device has proper suspend/resume support, +it can enable autosuspend all by itself. For example, the video +driver for a laptop's webcam might do this (in recent kernels they +do), since these devices are rarely used and so should normally be +autosuspended. + Sometimes it turns out that even when a device does work okay with -autosuspend there are still problems. For example, there are -experimental patches adding autosuspend support to the usbhid driver, -which manages keyboards and mice, among other things. Tests with a -number of keyboards showed that typing on a suspended keyboard, while -causing the keyboard to do a remote wakeup all right, would -nonetheless frequently result in lost keystrokes. Tests with mice -showed that some of them would issue a remote-wakeup request in -response to button presses but not to motion, and some in response to -neither. +autosuspend there are still problems. For example, the usbhid driver, +which manages keyboards and mice, has autosuspend support. Tests with +a number of keyboards show that typing on a suspended keyboard, while +causing the keyboard to do a remote wakeup all right, will nonetheless +frequently result in lost keystrokes. Tests with mice show that some +of them will issue a remote-wakeup request in response to button +presses but not to motion, and some in response to neither. The kernel will not prevent you from enabling autosuspend on devices that can't handle it. It is even possible in theory to damage a -device by suspending it at the wrong time -- for example, suspending a -USB hard disk might cause it to spin down without parking the heads. -(Highly unlikely, but possible.) Take care. +device by suspending it at the wrong time. (Highly unlikely, but +possible.) Take care. The driver interface for Power Management @@ -313,171 +329,141 @@ three of the methods listed above. In addition, a driver indicates that it supports autosuspend by setting the .supports_autosuspend flag in its usb_driver structure. It is then responsible for informing the USB core whenever one of its interfaces becomes busy or idle. The -driver does so by calling these three functions: +driver does so by calling these six functions: int usb_autopm_get_interface(struct usb_interface *intf); void usb_autopm_put_interface(struct usb_interface *intf); - int usb_autopm_set_interface(struct usb_interface *intf); - -The functions work by maintaining a counter in the usb_interface -structure. When intf->pm_usage_count is > 0 then the interface is -deemed to be busy, and the kernel will not autosuspend the interface's -device. When intf->pm_usage_count is <= 0 then the interface is -considered to be idle, and the kernel may autosuspend the device. - -(There is a similar pm_usage_count field in struct usb_device, -associated with the device itself rather than any of its interfaces. -This field is used only by the USB core.) - -The driver owns intf->pm_usage_count; it can modify the value however -and whenever it likes. A nice aspect of the usb_autopm_* routines is -that the changes they make are protected by the usb_device structure's -PM mutex (udev->pm_mutex); however drivers may change pm_usage_count -without holding the mutex. - - usb_autopm_get_interface() increments pm_usage_count and - attempts an autoresume if the new value is > 0 and the - device is suspended. - - usb_autopm_put_interface() decrements pm_usage_count and - attempts an autosuspend if the new value is <= 0 and the - device isn't suspended. - - usb_autopm_set_interface() leaves pm_usage_count alone. - It attempts an autoresume if the value is > 0 and the device - is suspended, and it attempts an autosuspend if the value is - <= 0 and the device isn't suspended. - -There also are a couple of utility routines drivers can use: - - usb_autopm_enable() sets pm_usage_cnt to 1 and then calls - usb_autopm_set_interface(), which will attempt an autoresume. - - usb_autopm_disable() sets pm_usage_cnt to 0 and then calls - usb_autopm_set_interface(), which will attempt an autosuspend. - -The conventional usage pattern is that a driver calls + int usb_autopm_get_interface_async(struct usb_interface *intf); + void usb_autopm_put_interface_async(struct usb_interface *intf); + void usb_autopm_get_interface_no_resume(struct usb_interface *intf); + void usb_autopm_put_interface_no_suspend(struct usb_interface *intf); + +The functions work by maintaining a usage counter in the +usb_interface's embedded device structure. When the counter is > 0 +then the interface is deemed to be busy, and the kernel will not +autosuspend the interface's device. When the usage counter is = 0 +then the interface is considered to be idle, and the kernel may +autosuspend the device. + +Drivers need not be concerned about balancing changes to the usage +counter; the USB core will undo any remaining "get"s when a driver +is unbound from its interface. As a corollary, drivers must not call +any of the usb_autopm_* functions after their disconnect() routine has +returned. + +Drivers using the async routines are responsible for their own +synchronization and mutual exclusion. + + usb_autopm_get_interface() increments the usage counter and + does an autoresume if the device is suspended. If the + autoresume fails, the counter is decremented back. + + usb_autopm_put_interface() decrements the usage counter and + attempts an autosuspend if the new value is = 0. + + usb_autopm_get_interface_async() and + usb_autopm_put_interface_async() do almost the same things as + their non-async counterparts. The big difference is that they + use a workqueue to do the resume or suspend part of their + jobs. As a result they can be called in an atomic context, + such as an URB's completion handler, but when they return the + device will generally not yet be in the desired state. + + usb_autopm_get_interface_no_resume() and + usb_autopm_put_interface_no_suspend() merely increment or + decrement the usage counter; they do not attempt to carry out + an autoresume or an autosuspend. Hence they can be called in + an atomic context. + +The simplest usage pattern is that a driver calls usb_autopm_get_interface() in its open routine and -usb_autopm_put_interface() in its close or release routine. But -other patterns are possible. +usb_autopm_put_interface() in its close or release routine. But other +patterns are possible. The autosuspend attempts mentioned above will often fail for one -reason or another. For example, the power/level attribute might be +reason or another. For example, the power/control attribute might be set to "on", or another interface in the same device might not be idle. This is perfectly normal. If the reason for failure was that -the device hasn't been idle for long enough, a delayed workqueue -routine is automatically set up to carry out the operation when the -autosuspend idle-delay has expired. +the device hasn't been idle for long enough, a timer is scheduled to +carry out the operation automatically when the autosuspend idle-delay +has expired. -Autoresume attempts also can fail. This will happen if power/level is -set to "suspend" or if the device doesn't manage to resume properly. -Unlike autosuspend, there's no delay for an autoresume. +Autoresume attempts also can fail, although failure would mean that +the device is no longer present or operating properly. Unlike +autosuspend, there's no idle-delay for an autoresume. Other parts of the driver interface ----------------------------------- +Drivers can enable autosuspend for their devices by calling + + usb_enable_autosuspend(struct usb_device *udev); + +in their probe() routine, if they know that the device is capable of +suspending and resuming correctly. This is exactly equivalent to +writing "auto" to the device's power/control attribute. Likewise, +drivers can disable autosuspend by calling + + usb_disable_autosuspend(struct usb_device *udev); + +This is exactly the same as writing "on" to the power/control attribute. + Sometimes a driver needs to make sure that remote wakeup is enabled during autosuspend. For example, there's not much point autosuspending a keyboard if the user can't cause the keyboard to do a remote wakeup by typing on it. If the driver sets intf->needs_remote_wakeup to 1, the kernel won't autosuspend the -device if remote wakeup isn't available or has been disabled through -the power/wakeup attribute. (If the device is already autosuspended, -though, setting this flag won't cause the kernel to autoresume it. -Normally a driver would set this flag in its probe method, at which -time the device is guaranteed not to be autosuspended.) - -The usb_autopm_* routines have to run in a sleepable process context; -they must not be called from an interrupt handler or while holding a -spinlock. In fact, the entire autosuspend mechanism is not well geared -toward interrupt-driven operation. However there is one thing a -driver can do in an interrupt handler: +device if remote wakeup isn't available. (If the device is already +autosuspended, though, setting this flag won't cause the kernel to +autoresume it. Normally a driver would set this flag in its probe +method, at which time the device is guaranteed not to be +autosuspended.) + +If a driver does its I/O asynchronously in interrupt context, it +should call usb_autopm_get_interface_async() before starting output and +usb_autopm_put_interface_async() when the output queue drains. When +it receives an input event, it should call usb_mark_last_busy(struct usb_device *udev); -This sets udev->last_busy to the current time. udev->last_busy is the -field used for idle-delay calculations; updating it will cause any -pending autosuspend to be moved back. The usb_autopm_* routines will -also set the last_busy field to the current time. +in the event handler. This tells the PM core that the device was just +busy and therefore the next autosuspend idle-delay expiration should +be pushed back. Many of the usb_autopm_* routines also make this call, +so drivers need to worry only when interrupt-driven input arrives. -Calling urb_mark_last_busy() from within an URB completion handler is -subject to races: The kernel may have just finished deciding the -device has been idle for long enough but not yet gotten around to -calling the driver's suspend method. The driver would have to be -responsible for synchronizing its suspend method with its URB -completion handler and causing the autosuspend to fail with -EBUSY if -an URB had completed too recently. +Asynchronous operation is always subject to races. For example, a +driver may call the usb_autopm_get_interface_async() routine at a time +when the core has just finished deciding the device has been idle for +long enough but not yet gotten around to calling the driver's suspend +method. The suspend method must be responsible for synchronizing with +the I/O request routine and the URB completion handler; it should +cause autosuspends to fail with -EBUSY if the driver needs to use the +device. External suspend calls should never be allowed to fail in this way, -only autosuspend calls. The driver can tell them apart by checking -udev->auto_pm; this flag will be set to 1 for internal PM events -(autosuspend or autoresume) and 0 for external PM events. - -Many of the ingredients in the autosuspend framework are oriented -towards interfaces: The usb_interface structure contains the -pm_usage_cnt field, and the usb_autopm_* routines take an interface -pointer as their argument. But somewhat confusingly, a few of the -pieces (usb_mark_last_busy() and udev->auto_pm) use the usb_device -structure instead. Drivers need to keep this straight; they can call -interface_to_usbdev() to find the device structure for a given -interface. - - - Locking requirements - -------------------- - -All three suspend/resume methods are always called while holding the -usb_device's PM mutex. For external events -- but not necessarily for -autosuspend or autoresume -- the device semaphore (udev->dev.sem) will -also be held. This implies that external suspend/resume events are -mutually exclusive with calls to probe, disconnect, pre_reset, and -post_reset; the USB core guarantees that this is true of internal -suspend/resume events as well. - -If a driver wants to block all suspend/resume calls during some -critical section, it can simply acquire udev->pm_mutex. -Alternatively, if the critical section might call some of the -usb_autopm_* routines, the driver can avoid deadlock by doing: - - down(&udev->dev.sem); - rc = usb_autopm_get_interface(intf); - -and at the end of the critical section: - - if (!rc) - usb_autopm_put_interface(intf); - up(&udev->dev.sem); - -Holding the device semaphore will block all external PM calls, and the -usb_autopm_get_interface() will prevent any internal PM calls, even if -it fails. (Exercise: Why?) +only autosuspend calls. The driver can tell them apart by applying +the PMSG_IS_AUTO() macro to the message argument to the suspend +method; it will return True for internal PM events (autosuspend) and +False for external PM events. -The rules for locking order are: - Never acquire any device semaphore while holding any PM mutex. + Mutual exclusion + ---------------- - Never acquire udev->pm_mutex while holding the PM mutex for - a device that isn't a descendant of udev. +For external events -- but not necessarily for autosuspend or +autoresume -- the device semaphore (udev->dev.sem) will be held when a +suspend or resume method is called. This implies that external +suspend/resume events are mutually exclusive with calls to probe, +disconnect, pre_reset, and post_reset; the USB core guarantees that +this is true of autosuspend/autoresume events as well. -In other words, PM mutexes should only be acquired going up the device -tree, and they should be acquired only after locking all the device -semaphores you need to hold. These rules don't matter to drivers very -much; they usually affect just the USB core. - -Still, drivers do need to be careful. For example, many drivers use a -private mutex to synchronize their normal I/O activities with their -disconnect method. Now if the driver supports autosuspend then it -must call usb_autopm_put_interface() from somewhere -- maybe from its -close method. It should make the call while holding the private mutex, -since a driver shouldn't call any of the usb_autopm_* functions for an -interface from which it has been unbound. - -But the usb_autpm_* routines always acquire the device's PM mutex, and -consequently the locking order has to be: private mutex first, PM -mutex second. Since the suspend method is always called with the PM -mutex held, it mustn't try to acquire the private mutex. It has to -synchronize with the driver's I/O activities in some other way. +If a driver wants to block all suspend/resume calls during some +critical section, the best way is to lock the device and call +usb_autopm_get_interface() (and do the reverse at the end of the +critical section). Holding the device semaphore will block all +external PM calls, and the usb_autopm_get_interface() will prevent any +internal PM calls, even if it fails. (Exercise: Why?) Interaction between dynamic PM and system PM @@ -486,22 +472,13 @@ synchronize with the driver's I/O activities in some other way. Dynamic power management and system power management can interact in a couple of ways. -Firstly, a device may already be manually suspended or autosuspended -when a system suspend occurs. Since system suspends are supposed to -be as transparent as possible, the device should remain suspended -following the system resume. The 2.6.23 kernel obeys this principle -for manually suspended devices but not for autosuspended devices; they -do get resumed when the system wakes up. (Presumably they will be -autosuspended again after their idle-delay time expires.) In later -kernels this behavior will be fixed. - -(There is an exception. If a device would undergo a reset-resume -instead of a normal resume, and the device is enabled for remote -wakeup, then the reset-resume takes place even if the device was -already suspended when the system suspend began. The justification is -that a reset-resume is a kind of remote-wakeup event. Or to put it -another way, a device which needs a reset won't be able to generate -normal remote-wakeup signals, so it ought to be resumed immediately.) +Firstly, a device may already be autosuspended when a system suspend +occurs. Since system suspends are supposed to be as transparent as +possible, the device should remain suspended following the system +resume. But this theory may not work out well in practice; over time +the kernel's behavior in this regard has changed. As of 2.6.37 the +policy is to resume all devices during a system resume and let them +handle their own runtime suspends afterward. Secondly, a dynamic power-management event may occur as a system suspend is underway. The window for this is short, since system @@ -514,12 +491,28 @@ resume as soon as the system suspend is complete. Or the remote wakeup may fail and get lost. Which outcome occurs depends on timing and on the hardware and firmware design. -More interestingly, a device might undergo a manual resume or -autoresume during system suspend. With current kernels this shouldn't -happen, because manual resumes must be initiated by userspace and -autoresumes happen in response to I/O requests, but all user processes -and I/O should be quiescent during a system suspend -- thanks to the -freezer. However there are plans to do away with the freezer, which -would mean these things would become possible. If and when this comes -about, the USB core will carefully arrange matters so that either type -of resume will block until the entire system has resumed. + + xHCI hardware link PM + --------------------- + +xHCI host controller provides hardware link power management to usb2.0 +(xHCI 1.0 feature) and usb3.0 devices which support link PM. By +enabling hardware LPM, the host can automatically put the device into +lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices), +which state device can enter and resume very quickly. + +The user interface for controlling USB2 hardware LPM is located in the +power/ subdirectory of each USB device's sysfs directory, that is, in +/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The +relevant attribute files is usb2_hardware_lpm. + + power/usb2_hardware_lpm + + When a USB2 device which support LPM is plugged to a + xHCI host root hub which support software LPM, the + host will run a software LPM test for it; if the device + enters L1 state and resume successfully and the host + supports USB2 hardware LPM, this file will show up and + driver will enable hardware LPM for the device. You + can write y/Y/1 or n/N/0 to the file to enable/disable + USB2 hardware LPM manually. This is for test purpose mainly. diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt index 077e9032d0c..98be9198267 100644 --- a/Documentation/usb/proc_usb_info.txt +++ b/Documentation/usb/proc_usb_info.txt @@ -1,12 +1,17 @@ /proc/bus/usb filesystem output =============================== -(version 2003.05.30) +(version 2010.09.13) The usbfs filesystem for USB devices is traditionally mounted at /proc/bus/usb. It provides the /proc/bus/usb/devices file, as well as the /proc/bus/usb/BBB/DDD files. +In many modern systems the usbfs filesystem isn't used at all. Instead +USB device nodes are created under /dev/usb/ or someplace similar. The +"devices" file is available in debugfs, typically as +/sys/kernel/debug/usb/devices. + **NOTE**: If /proc/bus/usb appears empty, and a host controller driver has been linked, then you need to mount the @@ -49,8 +54,13 @@ it and 002/048 sometime later. These files can be read as binary data. The binary data consists of first the device descriptor, then the descriptors for each -configuration of the device. That information is also shown in -text form by the /proc/bus/usb/devices file, described later. +configuration of the device. Multi-byte fields in the device descriptor +are converted to host endianness by the kernel. The configuration +descriptors are in bus endian format! The configuration descriptor +are wTotalLength bytes apart. If a device returns less configuration +descriptor data than indicated by wTotalLength there will be a hole in +the file for the missing bytes. This information is also shown +in text form by the /proc/bus/usb/devices file, described later. These files may also be used to write user-level drivers for the USB devices. You would open the /proc/bus/usb/BBB/DDD file read/write, @@ -104,8 +114,8 @@ Legend: Topology info: -T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=ddd MxCh=dd -| | | | | | | | |__MaxChildren +T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd +| | | | | | | | |__MaxChildren | | | | | | | |__Device Speed in Mbps | | | | | | |__DeviceNumber | | | | | |__Count of devices at this level @@ -118,8 +128,13 @@ T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=ddd MxCh=dd Speed may be: 1.5 Mbit/s for low speed USB 12 Mbit/s for full speed USB - 480 Mbit/s for high speed USB (added for USB 2.0) + 480 Mbit/s for high speed USB (added for USB 2.0); + also used for Wireless USB, which has no fixed speed + 5000 Mbit/s for SuperSpeed USB (added for USB 3.0) + For reasons lost in the mists of time, the Port number is always + too low by 1. For example, a device plugged into port 4 will + show up with "Port=03". Bandwidth info: B: Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd @@ -289,7 +304,7 @@ Here's an example, from a system which has a UHCI root hub, an external hub connected to the root hub, and a mouse and a serial converter connected to the external hub. -T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 +T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0 D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=0000 ProdID=0000 Rev= 0.00 @@ -299,21 +314,21 @@ C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms -T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 +T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=0451 ProdID=1446 Rev= 1.00 C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms -T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 +T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=04b4 ProdID=0001 Rev= 0.00 C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms -T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 +T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=0565 ProdID=0001 Rev= 1.08 S: Manufacturer=Peracom Networks, Inc. @@ -328,12 +343,12 @@ E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms Selecting only the "T:" and "I:" lines from this (for example, by using "procusb ti"), we have: -T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 -T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 +T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 +T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub -T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 +T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse -T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 +T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial diff --git a/Documentation/usb/uhci.txt b/Documentation/usb/uhci.txt deleted file mode 100644 index 2f25952c86c..00000000000 --- a/Documentation/usb/uhci.txt +++ /dev/null @@ -1,165 +0,0 @@ -Specification and Internals for the New UHCI Driver (Whitepaper...) - - brought to you by - - Georg Acher, acher@in.tum.de (executive slave) (base guitar) - Deti Fliegl, deti@fliegl.de (executive slave) (lead voice) - Thomas Sailer, sailer@ife.ee.ethz.ch (chief consultant) (cheer leader) - - $Id: README.uhci,v 1.1 1999/12/14 14:03:02 fliegl Exp $ - -This document and the new uhci sources can be found on - http://hotswap.in.tum.de/usb - -1. General issues - -1.1 Why a new UHCI driver, we already have one?!? - -Correct, but its internal structure got more and more mixed up by the (still -ongoing) efforts to get isochronous transfers (ISO) to work. -Since there is an increasing need for reliable ISO-transfers (especially -for USB-audio needed by TS and for a DAB-USB-Receiver build by GA and DF), -this state was a bit unsatisfying in our opinion, so we've decided (based -on knowledge and experiences with the old UHCI driver) to start -from scratch with a new approach, much simpler but at the same time more -powerful. -It is inspired by the way Win98/Win2000 handles USB requests via URBs, -but it's definitely 100% free of MS-code and doesn't crash while -unplugging an used ISO-device like Win98 ;-) -Some code for HW setup and root hub management was taken from the -original UHCI driver, but heavily modified to fit into the new code. -The invention of the basic concept, and major coding were completed in two -days (and nights) on the 16th and 17th of October 1999, now known as the -great USB-October-Revolution started by GA, DF, and TS ;-) - -Since the concept is in no way UHCI dependent, we hope that it will also be -transferred to the OHCI-driver, so both drivers share a common API. - -1.2. Advantages and disadvantages - -+ All USB transfer types work now! -+ Asynchronous operation -+ Simple, but powerful interface (only two calls for start and cancel) -+ Easy migration to the new API, simplified by a compatibility API -+ Simple usage of ISO transfers -+ Automatic linking of requests -+ ISO transfers allow variable length for each frame and striping -+ No CPU dependent and non-portable atomic memory access, no asm()-inlines -+ Tested on x86 and Alpha - -- Rewriting for ISO transfers needed - -1.3. Is there some compatibility to the old API? - -Yes, but only for control, bulk and interrupt transfers. We've implemented -some wrapper calls for these transfer types. The usbcore works fine with -these wrappers. For ISO there's no compatibility, because the old ISO-API -and its semantics were unnecessary complicated in our opinion. - -1.4. What's really working? - -As said above, CTRL and BULK already work fine even with the wrappers, -so legacy code wouldn't notice the change. -Regarding to Thomas, ISO transfers now run stable with USB audio. -INT transfers (e.g. mouse driver) work fine, too. - -1.5. Are there any bugs? - -No ;-) -Hm... -Well, of course this implementation needs extensive testing on all available -hardware, but we believe that any fixes shouldn't harm the overall concept. - -1.6. What should be done next? - -A large part of the request handling seems to be identical for UHCI and -OHCI, so it would be a good idea to extract the common parts and have only -the HW specific stuff in uhci.c. Furthermore, all other USB device drivers -should need URBification, if they use isochronous or interrupt transfers. -One thing missing in the current implementation (and the old UHCI driver) -is fair queueing for BULK transfers. Since this would need (in principle) -the alteration of already constructed TD chains (to switch from depth to -breadth execution), another way has to be found. Maybe some simple -heuristics work with the same effect. - ---------------------------------------------------------------------------- - -2. Internal structure and mechanisms - -To get quickly familiar with the internal structures, here's a short -description how the new UHCI driver works. However, the ultimate source of -truth is only uhci.c! - -2.1. Descriptor structure (QHs and TDs) - -During initialization, the following skeleton is allocated in init_skel: - - framespecific | common chain - -framelist[] -[ 0 ]-----> TD --> TD -------\ -[ 1 ]-----> TD --> TD --------> TD ----> QH -------> QH -------> QH ---> NULL - ... TD --> TD -------/ -[1023]-----> TD --> TD ------/ - - ^^ ^^ ^^ ^^ ^^ ^^ - 1024 TDs for 7 TDs for 1 TD for Start of Start of End Chain - ISO INT (2-128ms) 1ms-INT CTRL Chain BULK Chain - -For each CTRL or BULK transfer a new QH is allocated and the containing data -transfers are appended as (vertical) TDs. After building the whole QH with its -dangling TDs, the QH is inserted before the BULK Chain QH (for CTRL) or -before the End Chain QH (for BULK). Since only the QH->next pointers are -affected, no atomic memory operation is required. The three QHs in the -common chain are never equipped with TDs! - -For ISO or INT, the TD for each frame is simply inserted into the appropriate -ISO/INT-TD-chain for the desired frame. The 7 skeleton INT-TDs are scattered -among the 1024 frames similar to the old UHCI driver. - -For CTRL/BULK/ISO, the last TD in the transfer has the IOC-bit set. For INT, -every TD (there is only one...) has the IOC-bit set. - -Besides the data for the UHCI controller (2 or 4 32bit words), the descriptors -are double-linked through the .vertical and .horizontal elements in the -SW data of the descriptor (using the double-linked list structures and -operations), but SW-linking occurs only in closed domains, i.e. for each of -the 1024 ISO-chains and the 8 INT-chains there is a closed cycle. This -simplifies all insertions and unlinking operations and avoids costly -bus_to_virt()-calls. - -2.2. URB structure and linking to QH/TDs - -During assembly of the QH and TDs of the requested action, these descriptors -are stored in urb->urb_list, so the allocated QH/TD descriptors are bound to -this URB. -If the assembly was successful and the descriptors were added to the HW chain, -the corresponding URB is inserted into a global URB list for this controller. -This list stores all pending URBs. - -2.3. Interrupt processing - -Since UHCI provides no means to directly detect completed transactions, the -following is done in each UHCI interrupt (uhci_interrupt()): - -For each URB in the pending queue (process_urb()), the ACTIVE-flag of the -associated TDs are processed (depending on the transfer type -process_{transfer|interrupt|iso}()). If the TDs are not active anymore, -they indicate the completion of the transaction and the status is calculated. -Inactive QH/TDs are removed from the HW chain (since the host controller -already removed the TDs from the QH, no atomic access is needed) and -eventually the URB is marked as completed (OK or errors) and removed from the -pending queue. Then the next linked URB is submitted. After (or immediately -before) that, the completion handler is called. - -2.4. Unlinking URBs - -First, all QH/TDs stored in the URB are unlinked from the HW chain. -To ensure that the host controller really left a vertical TD chain, we -wait for one frame. After that, the TDs are physically destroyed. - -2.5. URB linking and the consequences - -Since URBs can be linked and the corresponding submit_urb is called in -the UHCI-interrupt, all work associated with URB/QH/TD assembly has to be -interrupt save. This forces kmalloc to use GFP_ATOMIC in the interrupt. diff --git a/Documentation/usb/usb-serial.txt b/Documentation/usb/usb-serial.txt index 8b077e43eee..5bd7926185e 100644 --- a/Documentation/usb/usb-serial.txt +++ b/Documentation/usb/usb-serial.txt @@ -83,7 +83,7 @@ HandSpring Visor, Palm USB, and Clié USB driver parameters. e.g. modprobe visor vendor=0x54c product=0x66 There is a webpage and mailing lists for this portion of the driver at: - http://usbvisor.sourceforge.net/ + http://sourceforge.net/projects/usbvisor/ For any questions or problems with this driver, please contact Greg Kroah-Hartman at greg@kroah.com @@ -184,7 +184,7 @@ Keyspan USA-series Serial Adapters functionality. More information is available at: - http://misc.nu/hugh/keyspan.html + http://www.carnationsoftware.com/carnation/Keyspan.html For any questions or problems with this driver, please contact Hugh Blemings at hugh@misc.nu @@ -192,12 +192,13 @@ Keyspan USA-series Serial Adapters FTDI Single Port Serial Driver - This is a single port DB-25 serial adapter. More information about this - device and the Linux driver can be found at: - http://reality.sgi.com/bryder_wellington/ftdi_sio/ + This is a single port DB-25 serial adapter. - For any questions or problems with this driver, please contact Bill Ryder - at bryder@sgi.com + Devices supported include: + -TripNav TN-200 USB GPS + -Navis Engineering Bureau CH-4711 USB GPS + + For any questions or problems with this driver, please contact Bill Ryder. ZyXEL omni.net lcd plus ISDN TA @@ -219,7 +220,7 @@ Cypress M8 CY4601 Family Serial Driver Devices supported: - -DeLorme's USB Earthmate (SiRF Star II lp arch) + -DeLorme's USB Earthmate GPS (SiRF Star II lp arch) -Cypress HID->COM RS232 adapter Note: Cypress Semiconductor claims no affiliation with the @@ -395,9 +396,10 @@ REINER SCT cyberJack pinpad/e-com USB chipcard reader Prolific PL2303 Driver This driver supports any device that has the PL2303 chip from Prolific - in it. This includes a number of single port USB to serial - converters and USB GPS devices. Devices from Aten (the UC-232) and - IO-Data work with this driver, as does the DCU-11 mobile-phone cable. + in it. This includes a number of single port USB to serial converters, + more than 70% of USB GPS devices (in 2010), and some USB UPSes. Devices + from Aten (the UC-232) and IO-Data work with this driver, as does + the DCU-11 mobile-phone cable. For any questions or problems with this driver, please contact Greg Kroah-Hartman at greg@kroah.com @@ -438,6 +440,22 @@ Winchiphead CH341 Driver For any questions or problems with this driver, please contact frank@kingswood-consulting.co.uk. +Moschip MCS7720, MCS7715 driver + + These chips are present in devices sold by various manufacturers, such as Syba + and Cables Unlimited. There may be others. The 7720 provides two serial + ports, and the 7715 provides one serial and one standard PC parallel port. + Support for the 7715's parallel port is enabled by a separate option, which + will not appear unless parallel port support is first enabled at the top-level + of the Device Drivers config menu. Currently only compatibility mode is + supported on the parallel port (no ECP/EPP). + + TODO: + - Implement ECP/EPP modes for the parallel port. + - Baud rates higher than 115200 are currently broken. + - Devices with a single serial port based on the Moschip MCS7703 may work + with this driver with a simple addition to the usb_device_id table. I + don't have one of these devices, so I can't say for sure. Generic Serial driver diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt index 2917ce4ffdc..c42bb9cd3b4 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -12,6 +12,10 @@ Controller Drivers (HCD). So, if HCD is buggy, the traces reported by usbmon may not correspond to bus transactions precisely. This is the same situation as with tcpdump. +Two APIs are currently implemented: "text" and "binary". The binary API +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. + * How to use usbmon to collect raw text traces Unlike the packet socket, usbmon has an interface which provides traces @@ -33,19 +37,21 @@ if usbmon is built into the kernel. Verify that bus sockets are present. -# ls /sys/kernel/debug/usbmon -0s 0t 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u +# ls /sys/kernel/debug/usb/usbmon +0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u # -Now you can choose to either use the sockets numbered '0' (to capture packets on -all buses), and skip to step #3, or find the bus used by your device with step #2. +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. +This allows to filter away annoying devices that talk continuously. 2. Find which bus connects to the desired device -Run "cat /proc/bus/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 -many similar devices, unplug one and compare two /proc/bus/usb/devices outputs. -The T-line will have a bus number. Example: +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 +many similar devices, unplug one and compare the two +/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 D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 @@ -53,15 +59,18 @@ P: Vendor=0557 ProdID=2004 Rev= 1.00 S: Manufacturer=ATEN S: Product=UC100KM V2.00 -Bus=03 means it's bus 3. +"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: + +Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00 3. Start 'cat' -# cat /sys/kernel/debug/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: -# cat /sys/kernel/debug/usbmon/0u > /tmp/1.mon.out +# cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out This process will be reading until killed. Naturally, the output can be redirected to a desirable location. This is preferred, because it is going @@ -99,8 +108,9 @@ on the event type, but there is a set of words, common for all types. Here is the list of words, from left to right: -- URB Tag. This is used to identify URBs is normally a kernel mode address - of the URB structure in hexadecimal. +- URB Tag. This is used to identify URBs, and is normally an in-kernel address + of the URB structure in hexadecimal, but can be a sequence number or any + other unique string, within reason. - Timestamp in microseconds, a decimal number. The timestamp's resolution depends on available clock, and so it can be much worse than a microsecond @@ -160,39 +170,11 @@ Here is the list of words, from left to right: not machine words, but really just a byte stream split into words to make it easier to read. Thus, the last word may contain from one to four bytes. The length of collected data is limited and can be less than the data length - report in Data Length word. - -Here is an example of code to read the data stream in a well known programming -language: - -class ParsedLine { - int data_len; /* Available length of data */ - byte data[]; - - void parseData(StringTokenizer st) { - int availwords = st.countTokens(); - data = new byte[availwords * 4]; - data_len = 0; - while (st.hasMoreTokens()) { - String data_str = st.nextToken(); - int len = data_str.length() / 2; - int i; - int b; // byte is signed, apparently?! XXX - for (i = 0; i < len; i++) { - // data[data_len] = Byte.parseByte( - // data_str.substring(i*2, i*2 + 2), - // 16); - b = Integer.parseInt( - data_str.substring(i*2, i*2 + 2), - 16); - if (b >= 128) - b *= -1; - data[data_len] = (byte) b; - data_len++; - } - } - } -} + reported in the Data Length word. In the case of an Isochronous input (Zi) + completion where the received data is sparse in the buffer, the length of + the collected data can be greater than the Data Length value (because Data + Length counts only the bytes that were received whereas the Data words + contain the entire transfer buffer). Examples: @@ -201,10 +183,10 @@ An input control transfer to get a port status. d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 < d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000 -An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper -to a storage device at address 5: +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: -dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 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 > * Raw binary format and API @@ -227,16 +209,26 @@ struct usbmon_packet { int status; /* 28: */ unsigned int length; /* 32: Length of data (submitted or actual) */ unsigned int len_cap; /* 36: Delivered length */ - unsigned char setup[8]; /* 40: Only for Control 'S' */ -}; /* 48 bytes total */ + union { /* 40: */ + unsigned char setup[SETUP_LEN]; /* Only for Control S-type */ + struct iso_rec { /* Only for ISO */ + int error_count; + int numdesc; + } iso; + } s; + int interval; /* 48: Only for Interrupt and ISO */ + int start_frame; /* 52: For ISO */ + unsigned int xfer_flags; /* 56: copy of URB's transfer_flags */ + unsigned int ndesc; /* 60: Actual number of ISO descriptors */ +}; /* 64 total length */ 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. +with an ioctl(2), or by accessing the buffer with mmap. However, read(2) +only returns first 48 bytes for compatibility reasons. The character device is usually called /dev/usbmonN, where N is the USB bus number. Number zero (/dev/usbmon0) is special and means "all buses". -However, this feature is not implemented yet. Note that specific naming -policy is set by your Linux distribution. +Note that specific naming policy is set by your Linux distribution. If you create /dev/usbmon0 by hand, make sure that it is owned by root and has mode 0600. Otherwise, unpriviledged users will be able to snoop @@ -277,9 +269,10 @@ size is out of [unspecified] bounds for this kernel, the call fails with This call returns the current size of the buffer in bytes. MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg) + MON_IOCX_GETX, defined as _IOW(MON_IOC_MAGIC, 10, struct mon_get_arg) -This call waits for events to arrive if none were in the kernel buffer, -then returns the first event. Its argument is a pointer to the following +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 structure: struct mon_get_arg { @@ -292,6 +285,8 @@ 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 the data, if any. The event is removed from the kernel buffer. +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) This ioctl is primarily used when the application accesses the buffer diff --git a/Documentation/usb/wusb-cbaf b/Documentation/usb/wusb-cbaf new file mode 100644 index 00000000000..8b3d43efce9 --- /dev/null +++ b/Documentation/usb/wusb-cbaf @@ -0,0 +1,130 @@ +#! /bin/bash +# + +set -e + +progname=$(basename $0) +function help +{ + cat <<EOF +Usage: $progname COMMAND DEVICEs [ARGS] + +Command for manipulating the pairing/authentication credentials of a +Wireless USB device that supports wired-mode Cable-Based-Association. + +Works in conjunction with the wusb-cba.ko driver from http://linuxuwb.org. + + +DEVICE + + sysfs path to the device to authenticate; for example, both this + guys are the same: + + /sys/devices/pci0000:00/0000:00:1d.7/usb1/1-4/1-4.4/1-4.4:1.1 + /sys/bus/usb/drivers/wusb-cbaf/1-4.4:1.1 + +COMMAND/ARGS are + + start + + Start a WUSB host controller (by setting up a CHID) + + set-chid DEVICE HOST-CHID HOST-BANDGROUP HOST-NAME + + Sets host information in the device; after this you can call the + get-cdid to see how does this device report itself to us. + + get-cdid DEVICE + + Get the device ID associated to the HOST-CHID we sent with + 'set-chid'. We might not know about it. + + set-cc DEVICE + + If we allow the device to connect, set a random new CDID and CK + (connection key). Device saves them for the next time it wants to + connect wireless. We save them for that next time also so we can + authenticate the device (when we see the CDID he uses to id + itself) and the CK to crypto talk to it. + +CHID is always 16 hex bytes in 'XX YY ZZ...' form +BANDGROUP is almost always 0001 + +Examples: + + You can default most arguments to '' to get a sane value: + + $ $progname set-chid '' '' '' "My host name" + + A full sequence: + + $ $progname set-chid '' '' '' "My host name" + $ $progname get-cdid '' + $ $progname set-cc '' + +EOF +} + + +# Defaults +# FIXME: CHID should come from a database :), band group from the host +host_CHID="00 11 22 33 44 55 66 77 88 99 aa bb cc dd ee ff" +host_band_group="0001" +host_name=$(hostname) + +devs="$(echo /sys/bus/usb/drivers/wusb-cbaf/[0-9]*)" +hdevs="$(for h in /sys/class/uwb_rc/*/wusbhc; do readlink -f $h; done)" + +result=0 +case $1 in + start) + for dev in ${2:-$hdevs} + do + echo $host_CHID > $dev/wusb_chid + echo I: started host $(basename $dev) >&2 + done + ;; + stop) + for dev in ${2:-$hdevs} + do + echo 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 > $dev/wusb_chid + echo I: stopped host $(basename $dev) >&2 + done + ;; + set-chid) + shift + for dev in ${2:-$devs}; do + echo "${4:-$host_name}" > $dev/wusb_host_name + echo "${3:-$host_band_group}" > $dev/wusb_host_band_groups + echo ${2:-$host_CHID} > $dev/wusb_chid + done + ;; + get-cdid) + for dev in ${2:-$devs} + do + cat $dev/wusb_cdid + done + ;; + set-cc) + for dev in ${2:-$devs}; do + shift + CDID="$(head --bytes=16 /dev/urandom | od -tx1 -An)" + CK="$(head --bytes=16 /dev/urandom | od -tx1 -An)" + echo "$CDID" > $dev/wusb_cdid + echo "$CK" > $dev/wusb_ck + + echo I: CC set >&2 + echo "CHID: $(cat $dev/wusb_chid)" + echo "CDID:$CDID" + echo "CK: $CK" + done + ;; + help|h|--help|-h) + help + ;; + *) + echo "E: Unknown usage" 1>&2 + help 1>&2 + result=1 +esac +exit $result |