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