bulk-streams.rst (3286B)
1USB bulk streams 2~~~~~~~~~~~~~~~~ 3 4Background 5========== 6 7Bulk endpoint streams were added in the USB 3.0 specification. Streams allow a 8device driver to overload a bulk endpoint so that multiple transfers can be 9queued at once. 10 11Streams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus 123.0 specification at https://www.usb.org/developers/docs/ The USB Attached SCSI 13Protocol, which uses streams to queue multiple SCSI commands, can be found on 14the T10 website (https://t10.org/). 15 16 17Device-side implications 18======================== 19 20Once a buffer has been queued to a stream ring, the device is notified (through 21an out-of-band mechanism on another endpoint) that data is ready for that stream 22ID. The device then tells the host which "stream" it wants to start. The host 23can also initiate a transfer on a stream without the device asking, but the 24device can refuse that transfer. Devices can switch between streams at any 25time. 26 27 28Driver implications 29=================== 30 31:: 32 33 int usb_alloc_streams(struct usb_interface *interface, 34 struct usb_host_endpoint **eps, unsigned int num_eps, 35 unsigned int num_streams, gfp_t mem_flags); 36 37Device drivers will call this API to request that the host controller driver 38allocate memory so the driver can use up to num_streams stream IDs. They must 39pass an array of usb_host_endpoints that need to be setup with similar stream 40IDs. This is to ensure that a UASP driver will be able to use the same stream 41ID for the bulk IN and OUT endpoints used in a Bi-directional command sequence. 42 43The return value is an error condition (if one of the endpoints doesn't support 44streams, or the xHCI driver ran out of memory), or the number of streams the 45host controller allocated for this endpoint. The xHCI host controller hardware 46declares how many stream IDs it can support, and each bulk endpoint on a 47SuperSpeed device will say how many stream IDs it can handle. Therefore, 48drivers should be able to deal with being allocated less stream IDs than they 49requested. 50 51Do NOT call this function if you have URBs enqueued for any of the endpoints 52passed in as arguments. Do not call this function to request less than two 53streams. 54 55Drivers will only be allowed to call this API once for the same endpoint 56without calling usb_free_streams(). This is a simplification for the xHCI host 57controller driver, and may change in the future. 58 59 60Picking new Stream IDs to use 61============================= 62 63Stream ID 0 is reserved, and should not be used to communicate with devices. If 64usb_alloc_streams() returns with a value of N, you may use streams 1 though N. 65To queue an URB for a specific stream, set the urb->stream_id value. If the 66endpoint does not support streams, an error will be returned. 67 68Note that new API to choose the next stream ID will have to be added if the xHCI 69driver supports secondary stream IDs. 70 71 72Clean up 73======== 74 75If a driver wishes to stop using streams to communicate with the device, it 76should call:: 77 78 void usb_free_streams(struct usb_interface *interface, 79 struct usb_host_endpoint **eps, unsigned int num_eps, 80 gfp_t mem_flags); 81 82All stream IDs will be deallocated when the driver releases the interface, to 83ensure that drivers that don't support streams will be able to use the endpoint.