1401c7be2SMauro Carvalho ChehabUSB bulk streams 2401c7be2SMauro Carvalho Chehab~~~~~~~~~~~~~~~~ 3401c7be2SMauro Carvalho Chehab 4401c7be2SMauro Carvalho ChehabBackground 5401c7be2SMauro Carvalho Chehab========== 6401c7be2SMauro Carvalho Chehab 7401c7be2SMauro Carvalho ChehabBulk endpoint streams were added in the USB 3.0 specification. Streams allow a 8401c7be2SMauro Carvalho Chehabdevice driver to overload a bulk endpoint so that multiple transfers can be 9401c7be2SMauro Carvalho Chehabqueued at once. 10401c7be2SMauro Carvalho Chehab 11401c7be2SMauro Carvalho ChehabStreams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus 1293431e06SAlexander A. Klimov3.0 specification at https://www.usb.org/developers/docs/ The USB Attached SCSI 13401c7be2SMauro Carvalho ChehabProtocol, which uses streams to queue multiple SCSI commands, can be found on 1493431e06SAlexander A. Klimovthe T10 website (https://t10.org/). 15401c7be2SMauro Carvalho Chehab 16401c7be2SMauro Carvalho Chehab 17401c7be2SMauro Carvalho ChehabDevice-side implications 18401c7be2SMauro Carvalho Chehab======================== 19401c7be2SMauro Carvalho Chehab 20401c7be2SMauro Carvalho ChehabOnce a buffer has been queued to a stream ring, the device is notified (through 21401c7be2SMauro Carvalho Chehaban out-of-band mechanism on another endpoint) that data is ready for that stream 22401c7be2SMauro Carvalho ChehabID. The device then tells the host which "stream" it wants to start. The host 23401c7be2SMauro Carvalho Chehabcan also initiate a transfer on a stream without the device asking, but the 24401c7be2SMauro Carvalho Chehabdevice can refuse that transfer. Devices can switch between streams at any 25401c7be2SMauro Carvalho Chehabtime. 26401c7be2SMauro Carvalho Chehab 27401c7be2SMauro Carvalho Chehab 28401c7be2SMauro Carvalho ChehabDriver implications 29401c7be2SMauro Carvalho Chehab=================== 30401c7be2SMauro Carvalho Chehab 31401c7be2SMauro Carvalho Chehab:: 32401c7be2SMauro Carvalho Chehab 33401c7be2SMauro Carvalho Chehab int usb_alloc_streams(struct usb_interface *interface, 34401c7be2SMauro Carvalho Chehab struct usb_host_endpoint **eps, unsigned int num_eps, 35401c7be2SMauro Carvalho Chehab unsigned int num_streams, gfp_t mem_flags); 36401c7be2SMauro Carvalho Chehab 37401c7be2SMauro Carvalho ChehabDevice drivers will call this API to request that the host controller driver 38401c7be2SMauro Carvalho Chehaballocate memory so the driver can use up to num_streams stream IDs. They must 39401c7be2SMauro Carvalho Chehabpass an array of usb_host_endpoints that need to be setup with similar stream 40401c7be2SMauro Carvalho ChehabIDs. This is to ensure that a UASP driver will be able to use the same stream 41401c7be2SMauro Carvalho ChehabID for the bulk IN and OUT endpoints used in a Bi-directional command sequence. 42401c7be2SMauro Carvalho Chehab 43401c7be2SMauro Carvalho ChehabThe return value is an error condition (if one of the endpoints doesn't support 44401c7be2SMauro Carvalho Chehabstreams, or the xHCI driver ran out of memory), or the number of streams the 45401c7be2SMauro Carvalho Chehabhost controller allocated for this endpoint. The xHCI host controller hardware 46401c7be2SMauro Carvalho Chehabdeclares how many stream IDs it can support, and each bulk endpoint on a 47401c7be2SMauro Carvalho ChehabSuperSpeed device will say how many stream IDs it can handle. Therefore, 48401c7be2SMauro Carvalho Chehabdrivers should be able to deal with being allocated less stream IDs than they 49401c7be2SMauro Carvalho Chehabrequested. 50401c7be2SMauro Carvalho Chehab 51401c7be2SMauro Carvalho ChehabDo NOT call this function if you have URBs enqueued for any of the endpoints 52401c7be2SMauro Carvalho Chehabpassed in as arguments. Do not call this function to request less than two 53401c7be2SMauro Carvalho Chehabstreams. 54401c7be2SMauro Carvalho Chehab 55401c7be2SMauro Carvalho ChehabDrivers will only be allowed to call this API once for the same endpoint 56401c7be2SMauro Carvalho Chehabwithout calling usb_free_streams(). This is a simplification for the xHCI host 57401c7be2SMauro Carvalho Chehabcontroller driver, and may change in the future. 58401c7be2SMauro Carvalho Chehab 59401c7be2SMauro Carvalho Chehab 60401c7be2SMauro Carvalho ChehabPicking new Stream IDs to use 61401c7be2SMauro Carvalho Chehab============================= 62401c7be2SMauro Carvalho Chehab 63401c7be2SMauro Carvalho ChehabStream ID 0 is reserved, and should not be used to communicate with devices. If 64401c7be2SMauro Carvalho Chehabusb_alloc_streams() returns with a value of N, you may use streams 1 though N. 65401c7be2SMauro Carvalho ChehabTo queue an URB for a specific stream, set the urb->stream_id value. If the 66401c7be2SMauro Carvalho Chehabendpoint does not support streams, an error will be returned. 67401c7be2SMauro Carvalho Chehab 68401c7be2SMauro Carvalho ChehabNote that new API to choose the next stream ID will have to be added if the xHCI 69401c7be2SMauro Carvalho Chehabdriver supports secondary stream IDs. 70401c7be2SMauro Carvalho Chehab 71401c7be2SMauro Carvalho Chehab 72401c7be2SMauro Carvalho ChehabClean up 73401c7be2SMauro Carvalho Chehab======== 74401c7be2SMauro Carvalho Chehab 75401c7be2SMauro Carvalho ChehabIf a driver wishes to stop using streams to communicate with the device, it 76401c7be2SMauro Carvalho Chehabshould call:: 77401c7be2SMauro Carvalho Chehab 78401c7be2SMauro Carvalho Chehab void usb_free_streams(struct usb_interface *interface, 79401c7be2SMauro Carvalho Chehab struct usb_host_endpoint **eps, unsigned int num_eps, 80401c7be2SMauro Carvalho Chehab gfp_t mem_flags); 81401c7be2SMauro Carvalho Chehab 82401c7be2SMauro Carvalho ChehabAll stream IDs will be deallocated when the driver releases the interface, to 83401c7be2SMauro Carvalho Chehabensure that drivers that don't support streams will be able to use the endpoint. 84