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