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