diff options
| -rw-r--r-- | Documentation/usb/bulk-streams.txt | 78 | ||||
| -rw-r--r-- | drivers/usb/core/hcd.c | 69 | ||||
| -rw-r--r-- | drivers/usb/host/xhci-pci.c | 2 | ||||
| -rw-r--r-- | include/linux/usb.h | 10 | ||||
| -rw-r--r-- | include/linux/usb/hcd.h | 10 |
5 files changed, 169 insertions, 0 deletions
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/drivers/usb/core/hcd.c b/drivers/usb/core/hcd.c index 6a05e693445..3aaee2811f0 100644 --- a/drivers/usb/core/hcd.c +++ b/drivers/usb/core/hcd.c @@ -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 diff --git a/drivers/usb/host/xhci-pci.c b/drivers/usb/host/xhci-pci.c index 98a73cd20cc..d295bbc15eb 100644 --- a/drivers/usb/host/xhci-pci.c +++ b/drivers/usb/host/xhci-pci.c @@ -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, diff --git a/include/linux/usb.h b/include/linux/usb.h index 191af498c4f..1ea25377ca0 100644 --- a/include/linux/usb.h +++ b/include/linux/usb.h @@ -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); diff --git a/include/linux/usb/hcd.h b/include/linux/usb/hcd.h index d268415b7a4..aca73a5c3af 100644 --- a/include/linux/usb/hcd.h +++ b/include/linux/usb/hcd.h @@ -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 |