€•ô2      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ//translations/zh_CN/driver-api/usb/bulk-streams”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ//translations/zh_TW/driver-api/usb/bulk-streams”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ//translations/it_IT/driver-api/usb/bulk-streams”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ//translations/ja_JP/driver-api/usb/bulk-streams”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ//translations/ko_KR/driver-api/usb/bulk-streams”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ//translations/sp_SP/driver-api/usb/bulk-streams”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒUSB bulk streams”h]”hŒUSB bulk streams”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒI/var/lib/git/docbuild/linux/Documentation/driver-api/usb/bulk-streams.rst”h Kubh¢)”}”(hhh]”(h§)”}”(hŒ
Background”h]”hŒ
Background”…””}”(hhºhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh·hžhhŸh¶h KubhŒ	paragraph”“”)”}”(hŒ«Bulk endpoint streams were added in the USB 3.0 specification.  Streams allow a
device driver to overload a bulk endpoint so that multiple transfers can be
queued at once.”h]”hŒ«Bulk endpoint streams were added in the USB 3.0 specification.  Streams allow a
device driver to overload a bulk endpoint so that multiple transfers can be
queued at once.”…””}”(hhÊhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubhÉ)”}”(hX  Streams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus
3.0 specification at https://www.usb.org/developers/docs/  The USB Attached SCSI
Protocol, which uses streams to queue multiple SCSI commands, can be found on
the T10 website (https://t10.org/).”h]”(hŒfStreams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus
3.0 specification at ”…””}”(hhØhžhhŸNh NubhŒ	reference”“”)”}”(hŒ$https://www.usb.org/developers/docs/”h]”hŒ$https://www.usb.org/developers/docs/”…””}”(hhâhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”häuh1hàhhØubhŒw  The USB Attached SCSI
Protocol, which uses streams to queue multiple SCSI commands, can be found on
the T10 website (”…””}”(hhØhžhhŸNh Nubhá)”}”(hŒhttps://t10.org/”h]”hŒhttps://t10.org/”…””}”(hhõhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”h÷uh1hàhhØubhŒ).”…””}”(hhØhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubeh}”(h]”Œ
background”ah ]”h"]”Œ
background”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒDevice-side implications”h]”hŒDevice-side implications”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h KubhÉ)”}”(hXŽ  Once a buffer has been queued to a stream ring, the device is notified (through
an out-of-band mechanism on another endpoint) that data is ready for that stream
ID.  The device then tells the host which "stream" it wants to start.  The host
can also initiate a transfer on a stream without the device asking, but the
device can refuse that transfer.  Devices can switch between streams at any
time.”h]”hX’  Once a buffer has been queued to a stream ring, the device is notified (through
an out-of-band mechanism on another endpoint) that data is ready for that stream
ID.  The device then tells the host which â€œstreamâ€ it wants to start.  The host
can also initiate a transfer on a stream without the device asking, but the
device can refuse that transfer.  Devices can switch between streams at any
time.”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khj  hžhubeh}”(h]”Œdevice-side-implications”ah ]”h"]”Œdevice-side implications”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒDriver implications”h]”hŒDriver implications”…””}”(hj@  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj=  hžhhŸh¶h KubhŒliteral_block”“”)”}”(hŒ´int usb_alloc_streams(struct usb_interface *interface,
              struct usb_host_endpoint **eps, unsigned int num_eps,
              unsigned int num_streams, gfp_t mem_flags);”h]”hŒ´int usb_alloc_streams(struct usb_interface *interface,
              struct usb_host_endpoint **eps, unsigned int num_eps,
              unsigned int num_streams, gfp_t mem_flags);”…””}”hjP  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1jN  hŸh¶h K!hj=  hžhubhÉ)”}”(hXˆ  Device drivers will call this API to request that the host controller driver
allocate memory so the driver can use up to num_streams stream IDs.  They must
pass an array of usb_host_endpoints that need to be setup with similar stream
IDs.  This is to ensure that a UASP driver will be able to use the same stream
ID for the bulk IN and OUT endpoints used in a Bi-directional command sequence.”h]”hXˆ  Device drivers will call this API to request that the host controller driver
allocate memory so the driver can use up to num_streams stream IDs.  They must
pass an array of usb_host_endpoints that need to be setup with similar stream
IDs.  This is to ensure that a UASP driver will be able to use the same stream
ID for the bulk IN and OUT endpoints used in a Bi-directional command sequence.”…””}”(hj`  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K%hj=  hžhubhÉ)”}”(hXØ  The return value is an error condition (if one of the endpoints doesn't support
streams, or the xHCI driver ran out of memory), or the number of streams the
host controller allocated for this endpoint.  The xHCI host controller hardware
declares how many stream IDs it can support, and each bulk endpoint on a
SuperSpeed device will say how many stream IDs it can handle.  Therefore,
drivers should be able to deal with being allocated less stream IDs than they
requested.”h]”hXÚ  The return value is an error condition (if one of the endpoints doesnâ€™t support
streams, or the xHCI driver ran out of memory), or the number of streams the
host controller allocated for this endpoint.  The xHCI host controller hardware
declares how many stream IDs it can support, and each bulk endpoint on a
SuperSpeed device will say how many stream IDs it can handle.  Therefore,
drivers should be able to deal with being allocated less stream IDs than they
requested.”…””}”(hjn  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K+hj=  hžhubhÉ)”}”(hŒ¡Do NOT call this function if you have URBs enqueued for any of the endpoints
passed in as arguments.  Do not call this function to request less than two
streams.”h]”hŒ¡Do NOT call this function if you have URBs enqueued for any of the endpoints
passed in as arguments.  Do not call this function to request less than two
streams.”…””}”(hj|  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K3hj=  hžhubhÉ)”}”(hŒÉDrivers will only be allowed to call this API once for the same endpoint
without calling usb_free_streams().  This is a simplification for the xHCI host
controller driver, and may change in the future.”h]”hŒÉDrivers will only be allowed to call this API once for the same endpoint
without calling usb_free_streams().  This is a simplification for the xHCI host
controller driver, and may change in the future.”…””}”(hjŠ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K7hj=  hžhubeh}”(h]”Œdriver-implications”ah ]”h"]”Œdriver implications”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒPicking new Stream IDs to use”h]”hŒPicking new Stream IDs to use”…””}”(hj£  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj   hžhhŸh¶h K=ubhÉ)”}”(hX*  Stream ID 0 is reserved, and should not be used to communicate with devices.  If
usb_alloc_streams() returns with a value of N, you may use streams 1 though N.
To queue an URB for a specific stream, set the urb->stream_id value.  If the
endpoint does not support streams, an error will be returned.”h]”hX*  Stream ID 0 is reserved, and should not be used to communicate with devices.  If
usb_alloc_streams() returns with a value of N, you may use streams 1 though N.
To queue an URB for a specific stream, set the urb->stream_id value.  If the
endpoint does not support streams, an error will be returned.”…””}”(hj±  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K?hj   hžhubhÉ)”}”(hŒvNote that new API to choose the next stream ID will have to be added if the xHCI
driver supports secondary stream IDs.”h]”hŒvNote that new API to choose the next stream ID will have to be added if the xHCI
driver supports secondary stream IDs.”…””}”(hj¿  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KDhj   hžhubeh}”(h]”Œpicking-new-stream-ids-to-use”ah ]”h"]”Œpicking new stream ids to use”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K=ubh¢)”}”(hhh]”(h§)”}”(hŒClean up”h]”hŒClean up”…””}”(hjØ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÕ  hžhhŸh¶h KIubhÉ)”}”(hŒYIf a driver wishes to stop using streams to communicate with the device, it
should call::”h]”hŒXIf a driver wishes to stop using streams to communicate with the device, it
should call:”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KKhjÕ  hžhubjO  )”}”(hŒšvoid usb_free_streams(struct usb_interface *interface,
              struct usb_host_endpoint **eps, unsigned int num_eps,
              gfp_t mem_flags);”h]”hŒšvoid usb_free_streams(struct usb_interface *interface,
              struct usb_host_endpoint **eps, unsigned int num_eps,
              gfp_t mem_flags);”…””}”hjô  sbah}”(h]”h ]”h"]”h$]”h&]”j^  j_  uh1jN  hŸh¶h KNhjÕ  hžhubhÉ)”}”(hŒžAll stream IDs will be deallocated when the driver releases the interface, to
ensure that drivers that don't support streams will be able to use the endpoint.”h]”hŒ All stream IDs will be deallocated when the driver releases the interface, to
ensure that drivers that donâ€™t support streams will be able to use the endpoint.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KRhjÕ  hžhubeh}”(h]”Œclean-up”ah ]”h"]”Œclean up”ah$]”h&]”uh1h¡hh£hžhhŸh¶h KIubeh}”(h]”Œusb-bulk-streams”ah ]”h"]”Œusb bulk streams”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jC  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j  j  j  j  j:  j7  j  jš  jÒ  jÏ  j  j  uŒ	nametypes”}”(j  ‰j  ‰j:  ‰j  ‰jÒ  ‰j  ‰uh}”(j  h£j  h·j7  j  jš  j=  jÏ  j   j  jÕ  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.