Commit eab1cafc authored by Sarah Sharp's avatar Sarah Sharp Committed by Greg Kroah-Hartman
Browse files

USB: Support for allocating USB 3.0 streams. 



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.

The device then decides which transfer it wants to work on first, and can
queue part of a transfer before it switches to a new stream.  All this
switching is invisible to the device driver, which just gets a completion
for the URB.  Drivers that use streams must be able to handle URBs
completing in a different order than they were submitted to the endpoint.

This requires adding new API to set up xHCI data structures to support
multiple queues ("stream rings") per endpoint.  Drivers will allocate a
number of stream IDs before enqueueing URBs to the bulk endpoints of the
device, and free the stream IDs in their disconnect function.  See
Documentation/usb/bulk-streams.txt for details.

The new mass storage device class, USB Attached SCSI Protocol (UASP), uses
these streams API.

Signed-off-by: default avatarSarah Sharp <sarah.a.sharp@linux.intel.com>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@suse.de>
parent e9df17eb

Documentation/usb/bulk-streams.txt

0 → 100644
+78 −0
Original line number Diff line number Diff line 
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.

drivers/usb/core/hcd.c

+69 −0
Original line number Diff line number Diff line
@@ -1814,6 +1814,75 @@ void usb_hcd_reset_endpoint(struct usb_device *udev, 
	}

}



/**

 * usb_alloc_streams - allocate bulk endpoint stream IDs.

 * @interface:		alternate setting that includes all endpoints.

 * @eps:		array of endpoints that need streams.

 * @num_eps:		number of endpoints in the array.

 * @num_streams:	number of streams to allocate.

 * @mem_flags:		flags hcd should use to allocate memory.

 *

 * Sets up a group of bulk endpoints to have num_streams stream IDs available.

 * Drivers may queue multiple transfers to different stream IDs, which may

 * complete in a different order than they were queued.

 */

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)

{

	struct usb_hcd *hcd;

	struct usb_device *dev;

	int i;



	dev = interface_to_usbdev(interface);

	hcd = bus_to_hcd(dev->bus);

	if (!hcd->driver->alloc_streams || !hcd->driver->free_streams)

		return -EINVAL;

	if (dev->speed != USB_SPEED_SUPER)

		return -EINVAL;



	/* Streams only apply to bulk endpoints. */

	for (i = 0; i < num_eps; i++)

		if (!usb_endpoint_xfer_bulk(&eps[i]->desc))

			return -EINVAL;



	return hcd->driver->alloc_streams(hcd, dev, eps, num_eps,

			num_streams, mem_flags);

}

EXPORT_SYMBOL_GPL(usb_alloc_streams);



/**

 * usb_free_streams - free bulk endpoint stream IDs.

 * @interface:	alternate setting that includes all endpoints.

 * @eps:	array of endpoints to remove streams from.

 * @num_eps:	number of endpoints in the array.

 * @mem_flags:	flags hcd should use to allocate memory.

 *

 * Reverts a group of bulk endpoints back to not using stream IDs.

 * Can fail if we are given bad arguments, or HCD is broken.

 */

void usb_free_streams(struct usb_interface *interface,

		struct usb_host_endpoint **eps, unsigned int num_eps,

		gfp_t mem_flags)

{

	struct usb_hcd *hcd;

	struct usb_device *dev;

	int i;



	dev = interface_to_usbdev(interface);

	hcd = bus_to_hcd(dev->bus);

	if (dev->speed != USB_SPEED_SUPER)

		return;



	/* Streams only apply to bulk endpoints. */

	for (i = 0; i < num_eps; i++)

		if (!usb_endpoint_xfer_bulk(&eps[i]->desc))

			return;



	hcd->driver->free_streams(hcd, dev, eps, num_eps, mem_flags);

}

EXPORT_SYMBOL_GPL(usb_free_streams);



/* Protect against drivers that try to unlink URBs after the device

 * is gone, by waiting until all unlinks for @udev are finished.

 * Since we don't currently track URBs by device, simply wait until

drivers/usb/host/xhci-pci.c

+2 −0
Original line number Diff line number Diff line
@@ -132,6 +132,8 @@ static const struct hc_driver xhci_pci_hc_driver = { 
	.urb_dequeue =		xhci_urb_dequeue,

	.alloc_dev =		xhci_alloc_dev,

	.free_dev =		xhci_free_dev,

	.alloc_streams =	xhci_alloc_streams,

	.free_streams =		xhci_free_streams,

	.add_endpoint =		xhci_add_endpoint,

	.drop_endpoint =	xhci_drop_endpoint,

	.endpoint_reset =	xhci_endpoint_reset,

include/linux/usb.h

+10 −0
Original line number Diff line number Diff line
@@ -570,6 +570,16 @@ static inline void usb_mark_last_busy(struct usb_device *udev) 
/* for drivers using iso endpoints */

extern int usb_get_current_frame_number(struct usb_device *usb_dev);



/* Sets up a group of bulk endpoints to support multiple stream IDs. */

extern 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);



/* Reverts a group of bulk endpoints back to not using stream IDs. */

extern void usb_free_streams(struct usb_interface *interface,

		struct usb_host_endpoint **eps, unsigned int num_eps,

		gfp_t mem_flags);



/* used these for multi-interface device registration */

extern int usb_driver_claim_interface(struct usb_driver *driver,

			struct usb_interface *iface, void *priv);

include/linux/usb/hcd.h

+10 −0
Original line number Diff line number Diff line
@@ -250,6 +250,16 @@ struct hc_driver { 
	int	(*alloc_dev)(struct usb_hcd *, struct usb_device *);

		/* Called by usb_disconnect to free HC device structures */

	void	(*free_dev)(struct usb_hcd *, struct usb_device *);

	/* Change a group of bulk endpoints to support multiple stream IDs */

	int	(*alloc_streams)(struct usb_hcd *hcd, struct usb_device *udev,

		struct usb_host_endpoint **eps, unsigned int num_eps,

		unsigned int num_streams, gfp_t mem_flags);

	/* Reverts a group of bulk endpoints back to not using stream IDs.

	 * Can fail if we run out of memory.

	 */

	int	(*free_streams)(struct usb_hcd *hcd, struct usb_device *udev,

		struct usb_host_endpoint **eps, unsigned int num_eps,

		gfp_t mem_flags);



	/* Bandwidth computation functions */

	/* Note that add_endpoint() can only be called once per endpoint before

CRA Git | Maintained and supported by SUSTech CRA and CCSE