When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
following type of warnings:

Warning(drivers/usb/core/usb.c:76): No description found for return value of
'usb_find_alt_setting'

Fix them by:
- adding some missing descriptions of return values
- using "Return" sections for those descriptions
Signed-off-by: NYacine Belkadi <yacine.belkadi.1@gmail.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>

USB spec stats that short packet can only appear at the end
of transfer. Because lost of HC(EHCI/UHCI/OHCI/...) can't
build a full packet from discontinuous buffers, we introduce
the limit in usb_submit_urb() to avoid such kind of bad sg buffers
coming from driver.

The limit might be a bit strict:
	- platform has iommu to do sg list mapping
	- some host controllers may support to build full packet from
	discontinuous buffers.

But considered that most of HCs don't support that, and driver
need work well or keep consistent on different HCs and ARCHs, we
have to introduce the limit.

Currently, only usbtest is reported to pass such sg buffers to HC,
and other users(mass storage, usbfs) don't have the problem.

We don't check it on USB wireless device, because:
	- wireless devices can't be attached to common USB
	  bus(EHCI/UHCI/OHCI/...)
	- the max packet size of endpoint may be odd, and often can't
	devide 4KB which is a typical usage in usb mass storage application
Reported-by: NKonstantin Filatov <kfilatov@parallels.com>
Reported-by: NDenis V. Lunev <den@openvz.org>
Cc: Felipe Balbi <balbi@ti.com>
Acked-by: NAlan Stern <stern@rowland.harvard.edu>
Signed-off-by: NMing Lei <ming.lei@canonical.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>

The calls to usb_poison_urb and usb_unpoison_urb are expected to be
balanced. However, if an urb that has not yet been submitted is
poisoned, its reject counter will not be increased as its ep-field is
NULL. A consecutive call to unpoison will thus in fact poison the urb
as its reject counter will be decremented to a negative value,
effectively preventing the urb from being submitted.

Note that there are currently no in-kernel drivers affected by this.

Cc: Alan Stern <stern@rowland.harvard.edu>
Acked-by: NAlan Stern <stern@rowland.harvard.edu>
Signed-off-by: NJohan Hovold <jhovold@gmail.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>

This patch (as1633) changes slightly the way usbcore handled
submissions of URBs that are already active.  It will now return
-EBUSY rather than -EINVAL, and it will call WARN_ONCE to draw
people's attention to the bug.
Signed-off-by: NAlan Stern <stern@rowland.harvard.edu>
Signed-off-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>

This patch (as1611) updates the USB documentation and kerneldoc to
give a more precise meaning for the URB_ISO_ASAP flag and to explain
more of the details of scheduling for isochronous URBs.
Signed-off-by: NAlan Stern <stern@rowland.harvard.edu>
Signed-off-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>

On some HCDs usb_unlink_urb() can directly call the
completion handler. That limits the spinlocks that can
be taken in the handler to locks not held while calling
usb_unlink_urb()
To prevent a race with resubmission, this patch exposes
usbcore's infrastructure for blocking submission, uses it
and so drops the lock without causing a race in usbhid.
Signed-off-by: NOliver Neukum <oneukum@suse.de>
Acked-by: NJiri Kosina <jkosina@suse.cz>
Cc: stable <stable@vger.kernel.org>
Signed-off-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>

This patch (as1534c) updates the documentation for usb_unlink_urb and
related functions.  It explains that the caller must prevent the URB
being unlinked from getting deallocated while the unlink is taking
place.
Signed-off-by: NAlan Stern <stern@rowland.harvard.edu>
CC: Ming Lei <tom.leiming@gmail.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>

The kernel doc entry for usb_unlink_urb() contains the phrase "This
request is always asynchronous.". The "always" leads to the assumption
that the ->complete() callback is not called from within
usb_unlink_urb(). This is not true. The HCD is allowed to call the
->complete() from within ->urb_dequeue() if it is appropriate for the
hardware.
This patch updates the kernel doc so usb-device driver authors make sure
to drop all locks (and make sure it is okay to drop them) which are
acquired by the complete callback before calling usb_unlink_urb().
Signed-off-by: NSebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>

People have complained that debugging code shouldn't alter the flow of
control; it should restrict itself to printing out warnings and error
messages.  Bowing to popular opinion, this patch (as1518) changes the
debugging checks in usb_submit_urb() to follow this guideline.
Signed-off-by: NAlan Stern <stern@rowland.harvard.edu>
Reported-by: NKeith Packard <keithp@keithp.com>
CC: Pavel Machek <pavel@ucw.cz>
Signed-off-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>

Now ${LINUX}/drivers/usb/* can use usb_endpoint_maxp(desc) to get maximum packet size
instead of le16_to_cpu(desc->wMaxPacketSize).
This patch fix it up

Cc: Armin Fuerst <fuerst@in.tum.de>
Cc: Pavel Machek <pavel@ucw.cz>
Cc: Johannes Erdfelt <johannes@erdfelt.com>
Cc: Vojtech Pavlik <vojtech@suse.cz>
Cc: Oliver Neukum <oliver@neukum.name>
Cc: David Kubicek <dave@awk.cz>
Cc: Johan Hovold <jhovold@gmail.com>
Cc: Brad Hards <bhards@bigpond.net.au>
Acked-by: NFelipe Balbi <balbi@ti.com>
Cc: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Cc: Thomas Dahlmann <dahlmann.thomas@arcor.de>
Cc: David Brownell <david-b@pacbell.net>
Cc: David Lopo <dlopo@chipidea.mips.com>
Cc: Alan Stern <stern@rowland.harvard.edu>
Cc: Michal Nazarewicz <m.nazarewicz@samsung.com>
Cc: Xie Xiaobo <X.Xie@freescale.com>
Cc: Li Yang <leoli@freescale.com>
Cc: Jiang Bo <tanya.jiang@freescale.com>
Cc: Yuan-hsin Chen <yhchen@faraday-tech.com>
Cc: Darius Augulis <augulis.darius@gmail.com>
Cc: Xiaochen Shen <xiaochen.shen@intel.com>
Cc: Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com>
Cc: OKI SEMICONDUCTOR, <toshiharu-linux@dsn.okisemi.com>
Cc: Robert Jarzmik <robert.jarzmik@free.fr>
Cc: Ben Dooks <ben@simtec.co.uk>
Cc: Thomas Abraham <thomas.ab@samsung.com>
Cc: Herbert Pötzl <herbert@13thfloor.at>
Cc: Arnaud Patard <arnaud.patard@rtp-net.org>
Cc: Roman Weissgaerber <weissg@vienna.at>
Acked-by: NSarah Sharp <sarah.a.sharp@linux.intel.com>
Cc: Tony Olech <tony.olech@elandigitalsystems.com>
Cc: Florian Floe Echtler <echtler@fs.tum.de>
Cc: Christian Lucht <lucht@codemercs.com>
Cc: Juergen Stuber <starblue@sourceforge.net>
Cc: Georges Toth <g.toth@e-biz.lu>
Cc: Bill Ryder <bryder@sgi.com>
Cc: Kuba Ober <kuba@mareimbrium.org>
Cc: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
Signed-off-by: NKuninori Morimoto <kuninori.morimoto.gx@renesas.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

Use the Mult and bMaxBurst values from the endpoint companion
descriptor to calculate the max length of an isoc transfer.

Add USB_SS_MULT macro to access Mult field of bmAttributes, at
Sarah's suggestion.

This patch should be queued for the 2.6.36 and 2.6.37 stable trees, since
those were the first kernels to have isochronous support for SuperSpeed
devices.
Signed-off-by: NPaul Zimmerman <paulz@synopsys.com>
Signed-off-by: NSarah Sharp <sarah.a.sharp@linux.intel.com>
Cc: stable@kernel.org

Commit f661c6f8 adds a check of the pipe type if
CONFIG_USB_DEBUG is enabled, but it doesn't output anything if this scenario
occurs.
Signed-off-by: NSimon Arlott <simon@fire.lp0.eu>
Cc: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

This patch fixes a race condition in two utility routines
related to the removal/unlinking of urbs from an anchor.

If two threads are concurrently accessing the same anchor,
both could end up with the same urb - thinking they are
the exclusive owner.

Alan Stern pointed out a related issue in
usb_unlink_anchored_urbs:

"The URB isn't removed from the anchor until it completes
 (as a by-product of completion, in fact), which might not
 be for quite some time after the unlink call returns.
 In the meantime, the subroutine will keep trying to unlink
 it, over and over again."

Cc: stable <stable@kernel.org>
Cc: Oliver Neukum <oneukum@suse.de>
Cc: Greg Kroah-Hartman <greg@kroah.com>
Acked-by: NAlan Stern <stern@rowland.harvard.edu>
Signed-off-by: NChristian Lamparter <chunkeey@googlemail.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

Converting a pipe number to a struct usb_host_endpoint pointer is a little
messy.  Introduce a new convenience function to hide the mess.
Signed-off-by: NMatthew Wilcox <willy@linux.intel.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

This patch (as1368) fixes a rather obscure bug in usbmon: When tracing
URBs sent by the scatter-gather library, it accesses the data buffers
while they are still mapped for DMA.

The solution is to move the mapping and unmapping out of the s-g
library and into the usual place in hcd.c.  This requires the addition
of new URB flag bits to describe the kind of mapping needed, since we
have to call dma_map_sg() if the HCD supports native scatter-gather
operation and dma_map_page() if it doesn't.  The nice thing about
having the new flags is that they simplify the testing for unmapping.

The patch removes the only caller of usb_buffer_[un]map_sg(), so those
functions are #if'ed out.  A later patch will remove them entirely.

As a result of this change, urb->sg will be set in situations where
it wasn't set previously.  Hence the xhci and whci drivers are
adjusted to test urb->num_sgs instead, which retains its original
meaning and is nonzero only when the HCD has to handle a scatterlist.

Finally, even when a submission error occurs we don't want to hand
URBs to usbmon before they are unmapped.  The submission path is
rearranged so that map_urb_for_dma() is called only for non-root-hub
URBs and unmap_urb_for_dma() is called immediately after a submission
error.  This simplifies the error handling.
Signed-off-by: NAlan Stern <stern@rowland.harvard.edu>
CC: <stable@kernel.org>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

This patch (as1350) removes all usages of coherent buffers for USB
control-request setup-packet buffers.  There's no good reason to
reserve coherent memory for these things; control requests are hardly
ever used in large quantity (the major exception is firmware
transfers, and they aren't time-critical).  Furthermore, only seven
drivers used it.  We might as well always use streaming DMA mappings
for setup-packet buffers, and remove some extra complexity from
usbcore.

The DMA-mapping portion of hcd.c is currently in flux.  A separate
patch will be submitted to remove support for URB_NO_SETUP_DMA_MAP
after everything else settles down.  The removal should go smoothly,
as by then nobody will be using it.
Signed-off-by: NAlan Stern <stern@rowland.harvard.edu>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

The usbcore headers: hcd.h and hub.h are shared between usbcore,
HCDs and a couple of other drivers (e.g. USBIP modules).
So, it makes sense to move them into a more public location and
to cleanup dependency of those modules on kernel internal headers.
This patch moves hcd.h from drivers/usb/core into include/linux/usb/
Signed-of-by: NEric Lescouet <eric@lescouet.org>
Cc: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

USB 3 and Wireless USB specify a logarithmic encoding of the endpoint
interval that matches the USB 2 specification.  usb_fill_int_urb() didn't
know that and was filling in the interval as if it was USB 1.1.  Fix
usb_fill_int_urb() for SuperSpeed devices, but leave the wireless case
alone, because David Vrabel wants to keep the old encoding.

Update the struct urb kernel doc to note that SuperSpeed URBs must have
urb->interval specified in microframes.

Add a missing break statement in the usb_submit_urb() interrupt URB
checking, since wireless USB and SuperSpeed USB encode urb->interval
differently.  This allows xHCI roothubs to actually register with khubd.
Signed-off-by: NMatthew Wilcox <willy@linux.intel.com>
Signed-off-by: NSarah Sharp <sarah.a.sharp@linux.intel.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

It's really the wireless speed, so rename the thing to make
more sense.  Based on a recommendation from David Vrabel

Cc: David Vrabel <david.vrabel@csr.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

This patch (as1316) adds some error checking to usb_submit_urb().
It's conditional on CONFIG_USB_DEBUG, so it won't affect normal users.
The new check makes sure that the actual type of the endpoint
described by urb->pipe agrees with the type encoded in the pipe value.

The USB error code documentation is updated to include the code
returned by the new check, and the usbfs SUBMITURB handler is updated
to use the correct pipe type when legacy user code tries to submit a
bulk transfer to an interrupt endpoint.
Signed-off-by: NAlan Stern <stern@rowland.harvard.edu>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

Check urb->interval on interrupt transfers and allow those with valid
values (6 <= interval <= 16).
Signed-off-by: NDavid Vrabel <david.vrabel@csr.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

Originally, the USB core had no support for allocating bandwidth when a
particular configuration or alternate setting for an interface was
selected.  Instead, the device driver's URB submission would fail if
there was not enough bandwidth for a periodic endpoint.  Drivers could
work around this, by using the scatter-gather list API to guarantee
bandwidth.

This patch adds host controller API to allow the USB core to allocate or
deallocate bandwidth for an endpoint.  Endpoints are added to or dropped
from a copy of the current schedule by calling add_endpoint() or
drop_endpoint(), and then the schedule is atomically evaluated with a
call to check_bandwidth().  This allows all the endpoints for a new
configuration or alternate setting to be added at the same time that the
endpoints from the old configuration or alt setting are dropped.

Endpoints must be added to the schedule before any URBs are submitted to
them.  The HCD must be allowed to reject a new configuration or alt
setting before the control transfer is sent to the device requesting the
change.  It may reject the change because there is not enough bandwidth,
not enough internal resources (such as memory on an embedded host
controller), or perhaps even for security reasons in a virtualized
environment.

If the call to check_bandwidth() fails, the USB core must call
reset_bandwidth().  This causes the schedule to be reverted back to the
state it was in just after the last successful check_bandwidth() call.

If the call succeeds, the host controller driver (and hardware) will have
changed its internal state to match the new configuration or alternate
setting.  The USB core can then issue a control transfer to the device to
change the configuration or alt setting.  This allows the core to test new
configurations or alternate settings before unbinding drivers bound to
interfaces in the old configuration.

WIP:

The USB core must add endpoints from all interfaces in a configuration
to the schedule, because a driver may claim that interface at any time.
A slight optimization might be to add the endpoints to the schedule once
a driver claims that interface.  FIXME

This patch does not cover changing alternate settings, but it does
handle a configuration change or de-configuration.  FIXME

The code for managing the schedule is currently HCD specific.  A generic
scheduling algorithm could be added for host controllers without
built-in scheduling support.  For now, if a host controller does not
define the check_bandwidth() function, the call to
usb_hcd_check_bandwidth() will always succeed.
Signed-off-by: NSarah Sharp <sarah.a.sharp@linux.intel.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

Modify the USB core to handle the new USB 3.0 speed, "SuperSpeed".  This
is 5.0 Gbps (wire speed).  There are probably more places that check for
speed that I've missed.

SuperSpeed devices have a 512 byte endpoint 0 max packet size.  This shows
up as a bMaxPacketSize0 set to 0x09 (see table 9-8 of the USB 3.0 bus
spec).

xHCI spec says that the xHC can handle intervals up to 2^15 microframes.  That
might change when real silicon becomes available.

Add FIXME note for SuperSpeed isochronous endpoints.  They can transmit up
to 16 packets in one "burst" before they wait for an acknowledgment of the
packets.  They can do up to 3 bursts per microframe (determined by the
mult value in the endpoint companion descriptor).  The xHCI driver doesn't
have support for isoc yet, so fix this later.
Signed-off-by: NSarah Sharp <sarah.a.sharp@linux.intel.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

transfer_buffer_length and actual_length have become unsigned, therefore some
additional conversion of local variables, function arguments and print
specifications is desired.

A test for a negative urb->transfer_buffer_length became obsolete; instead
we ensure that it does not exceed INT_MAX. Also, urb->actual_length is always
less than urb->transfer_buffer_length.

rh_string() does no longer return -EPIPE in the case of an unsupported ID.
Instead its only caller, rh_call_control() does the check.
Signed-off-by: NRoel Kluin <roel.kluin@gmail.com>
Acked-by: NAlan Stern <stern@rowland.harvard.edu>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

To permit a userspace application to associate with WUSB devices
using numeric association, control transfers to unauthenticated WUSB
devices must be allowed.

This requires that wusbcore correctly sets the device state to
UNAUTHENTICATED, DEFAULT and ADDRESS and that control transfers can be
performed to UNAUTHENTICATED devices.
Signed-off-by: NDavid Vrabel <david.vrabel@csr.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

This extension allows unpoisoning an anchor allowing drivers that
resubmit URBs to reuse an anchor for methods like resume()
Signed-off-by: NOliver Neukum <oneukum@suse.de>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

It is enough to protect accesses to reject field of urb
by marking it as atomic_t,also it is the only reason of
existence of usb_reject_lock,so remove the lock to make
code more clean.
Signed-off-by: NMing Lei <tom.leiming@gmail.com>
Acked-off-by: NAlan Stern <stern@rowland.harvard.edu>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

The usb_free_urb comment says that the transfer buffer will not be
freed, but this is not the case when URB_FREE_BUFFER is set.
Signed-off-by: NRabin Vincent <rabin@rab.in>
Acked-by: NMarcel Holtmann <marcel@holtmann.org>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

This patch (as1151) protects usbcore against drivers that try to
unlink an URB after the URB's device or bus have been removed.  The
core does not currently check for this, and certain drivers can cause
a crash if they are running while an HCD is unloaded.

Certainly it would be best to fix the guilty drivers.  But a little
defensive programming doesn't hurt, especially since it appears that
quite a few drivers need to be fixed.

The patch prevents the problem by grabbing a reference to the device
while an unlink is in progress and using a new spinlock to synchronize
unlinks with device removal.  (There's no need to acquire a reference
to the bus as well, since the device structure itself keeps a
reference to the bus.)  In addition, the kerneldoc is updated to
indicate that URBs should not be unlinked after the disconnect method
returns.
Signed-off-by: NAlan Stern <stern@rowland.harvard.edu>
Cc: stable <stable@kernel.org>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

USB should not be having it's own printk macros, so remove err() and
use the system-wide standard of dev_err() wherever possible.  In the
few places that will not work out, use a basic printk().
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

This extends the anchor API as btusb needs for autosuspend.
Signed-off-by: NOliver Neukum <oneukum@suse.de>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

this extends the poisoning concept to anchors. This way poisoning
will work with fire and forget drivers.
Signed-off-by: NOliver Neukum <oneukum@suse.de>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

looking at usb_kill_urb() it seems to me that it is unnecessarily lenient.
In the use case of disconnect() you never want to use the URB again
(for the same device) But leaving urb->reject elevated will make it easier
to avoid races between read/write and disconnect.
Signed-off-by: NOliver Neukum <oneukum@suse.de>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

Irqs must not accidentally be reenabled.
Signed-off-by: NOliver Neukum <oneukum@suse.de>
Acked-by: NMarcel Holtmann <marcel@holtmann.org>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

__FUNCTION__ is gcc-specific, use __func__
Signed-off-by: NHarvey Harrison <harvey.harrison@gmail.com>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

This adds the ability to trigger asynchronous unlinks of anchored URBs. This
is needed for error handling in the comntext of completion handlers, which
cannot sleep.
Signed-off-by: NOliver Neukum <oneukum@suse.de>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

Fixes a number of coding style issues in the remaining .c files in
drivers/usb/core/
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

Over two years ago, the Linux USB developers stated that they believed
there was no way to create a USB kernel driver that was not under the
GPL.  This patch moves the USB apis to enforce that decision.

There are no known closed source USB drivers in the wild, so this patch
should cause no problems.
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

URB_FREE_BUFFER needs to be allowed in the sanity checks to use drivers that
use that flag.
Signed-off-by: NOliver Neukum <oneukum@suse.de>
Acked-by: NMarcel Holtmann <marcel@holtmann.org>
Cc: stable <stable@kernel.org>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

This patch (as989) makes usbcore flush all outstanding URBs for each
device as the device is suspended.  This will be true even when
CONFIG_USB_SUSPEND is not enabled.

In addition, an extra can_submit flag is added to the usb_device
structure.  That flag will be turned off whenever a suspend request
has been received for the device, even if the device isn't actually
suspended because CONFIG_USB_SUSPEND isn't set.

It's no longer necessary to check for the device state being equal to
USB_STATE_SUSPENDED during URB submission; that check can be replaced
by a check of the can_submit flag.  This also permits us to remove
some questionable references to the deprecated power.power_state field.
Signed-off-by: NAlan Stern <stern@rowland.harvard.edu>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>