Documentation/usb/bulk-streams.txt

Chinese translated version of Documentation/00-INDEX

If you have any comment or update to the content, please contact the
original document maintainer directly.  However, if you have a problem
communicating in English you can also ask the Chinese maintainer for
help.  Contact the Chinese maintainer if this translation is outdated
or if there is a problem with the translation.

Chinese maintainer: LiuLu <541748097@qq.com>
---------------------------------------------------------------------
Documentation/00-INDEX 的中文翻译

如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
译存在问题，请联系中文版维护者。

中文版维护者： 刘璐  <541748097@qq.com>
中文版翻译者： 刘璐  <541748097@qq.com>
中文版校译者： 刘璐  <541748097@qq.com>

Background
背景
==========


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.
批量端点流中添加了USB 3.0规范。流允许一个批量端点的设备驱动程序超载，这样可以使
多个传输立刻排队。


Streams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus
3.0 specification at http://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 (http://t10.org/).
流在通用串行总线3.0的4.4.6.4 和 8.12.1.4的区域中具体定义了，网址是
http://www.usb.org/developers/docs/。USB连接SCSI协议，它使用多个SCSI命令队列的流
，可以在T10网站找到（http://t10.org/）。




Device-side implications
设备端的影响
========================


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.


一旦一个缓冲已被排队流环，该设备通知（通过
波段机制的另一个端点）的数据为流ID准备好。主机设备然后告诉它“流”要开始。主机
也可以发起传输流的设备要求的情况下，但设备可以拒绝这种转移。任何时间移动设备都
可以在数据流之间切换。




Driver implications
驱动影响
===================


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);


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.


设备驱动程序会调用这个API来请求主机控制器驱动程序分配内存，所以驱动程序可以使用
到num_streams的流ID。他们必须传递usb_host_endpoints数组需要设置类似的流标识。这
是为了确保UASP驱动程序将能够使用相同的流用于在一个双向的命令序列的ID的大容量IN和
OUT端点，


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.


返回值是一个错误条件（如果一个端点不支持流，或的xHCI驱动程序的内存溢出），或流
分配给这个端点的主机控制器。 xHCI主机控制器硬件声明它可以支持多少流的ID，每个批
量端点上超设备会说，它可以处理多少流的ID。因此，驱动程序应该能够处理比他们被分
配较少的流ID请求。


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.


如果你有URB的任何端点队列，不调用此函数作为参数传递。不要调用这个函数来请求少于两
个数目的流。


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.


驱动程序将只允许一次相同的端点调用这个API，而不调用usb_free_streams（）。这是一种
简化的xHCI主机控制器的驱动程序，并可能会在未来发生改变。




Picking new Stream IDs to use
采用新的流ID供使用
============================


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.


数据流ID0是保留的，不应该被使用的设备进行通信。如果usb_alloc_streams（）返回N的值，
你可以使用流1虽然它是N的值。要对一个特定的数据流进行排队，设定一个URB URB-> stream_id
的值。如果端点不支持流，将返回一个错误。


Note that new API to choose the next stream ID will have to be added if the xHCI
driver supports secondary stream IDs.


请注意，如果的xHCI驱动支持二次流ID，将要添加的新的API来选择下一个数据流ID，




Clean up
清除
========


If a driver wishes to stop using streams to communicate with the device, it
should call
如果希望停止使用流与设备进行通信，它的驱动程序应该调用


void usb_free_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
gfp_t mem_flags);


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.


当驱动程序释放掉接口。所有的流ID也将会被释放，以确保驱动程序将不会支持可能会用于
端点的流。