Documentation-usb-anchors.txt

Chinese translated version of Documentation/usb/anchors.txt


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.


Maintainer: Eric W. Biederman <[e-mail]>
Chinese maintainer: Shao Qi <[e-mail]>
---------------------------------------------------------------------
Documentation/usb/anchors.txt 的中文翻译


如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
译存在问题，请联系中文版维护者。
英文版维护者： Eric W. Biederman <[e-mail]>
中文版维护者： 邵奇 Shao Qi <[e-mail]>
中文版翻译者： 邵奇 Shao Qi <[e-mail]>
中文版校译者： 邵奇 Shao Qi <[e-mail]>


以下为正文
---------------------------------------------------------------------
What is anchor?
什么是锚节点？
===============


A USB driver needs to support some callbacks requiring
a driver to cease all IO to an interface. To do so, a
driver has to keep track of the URBs it has submitted
to know they've all completed or to call usb_kill_urb
for them. The anchor is a data structure takes care of
keeping track of URBs and provides methods to deal with
multiple URBs.
USB驱动需要支持一些请求驱动停止所有对接口IO的回调函数。
要做到这一点，驱动必须与提交的USB请求块（URB）保持联系，
来知道它们已经完成或是要调用usb_kill_urb。锚节点是一种
数据结构，关注对URB的跟踪，提供处理多个URB的方法。


Allocation and Initialisation
分配和初始化
=============================


There's no API to allocate an anchor. It is simply declared
as struct usb_anchor. init_usb_anchor() must be called to
initialise the data structure.
没有分配锚节点的API。只简单的被作为usb_anchor结构声明。
必须调用init_usb_anchor()来初始化次数据结构。


Deallocation
重分配
============


Once it has no more URBs associated with it, the anchor can be
freed with normal memory management operations.
一旦没有更多相关的URB，锚节点能被正常内存管理操作所释放。




Association and disassociation of URBs with anchors
URB和锚节点的连接和断开
===================================================


An association of URBs to an anchor is made by an explicit
call to usb_anchor_urb(). The association is maintained until
an URB is finished by (successful) completion. Thus disassociation
is automatic. A function is provided to forcibly finish (kill)
all URBs associated with an anchor.
连接URB和锚节点的方式是通过明确的对usb_anchor_urb()的调用。该连接
会一直保持，直到URB成功结束。所以断开是自动的。提供强行结束（杀死）
所以和锚节点有连接的URB的函数。


Furthermore, disassociation can be made with usb_unanchor_urb()
此外，可用usb_unanchor_urb()完成断开。


Operations on multitudes of URBs
众多URB操作
================================


usb_kill_anchored_urbs()
------------------------
This function kills all URBs associated with an anchor. The URBs
are called in the reverse temporal order they were submitted.
This way no data can be reordered.
usb_kill_anchored_urbs()
------------------------
此函数杀死所有和锚节点有连接的URB。URB以与提交时相反的时间顺序被
调用。这样没有数据可以重排序。




usb_unlink_anchored_urbs()
--------------------------


This function unlinks all URBs associated with an anchor. The URBs
are processed in the reverse temporal order they were submitted.
This is similar to usb_kill_anchored_urbs(), but it will not sleep.
Therefore no guarantee is made that the URBs have been unlinked when
the call returns. They may be unlinked later but will be unlinked in
finite time.
usb_unlink_anchored_urbs()
--------------------------
此函数断开所有URB和锚节点之间的连接。URB以与被提交时相反的时间顺序被
处理。这和usb_kill_anchored_urbs()很相似，但它不会休眠。因此不保证当
调用返回时URB都断开连接了。可能是在之后断开，但一定会在有限时间内断开。


usb_scuttle_anchored_urbs()
---------------------------


All URBs of an anchor are unanchored en masse.
usb_scuttle_anchored_urbs()
---------------------------
锚节点的所有URB一同被非锚定。


usb_wait_anchor_empty_timeout()
-------------------------------


This function waits for all URBs associated with an anchor to finish
or a timeout, whichever comes first. Its return value will tell you
whether the timeout was reached.
usb_wait_anchor_empty_timeout()
-------------------------------
此函数等待所以和锚节点连接的URB完成或超时，以先到者为准。它的返回值
会告诉你是否超时了。


usb_anchor_empty()
------------------


Returns true if no URBs are associated with an anchor. Locking
is the caller's responsibility.
usb_anchor_empty()
------------------
如果没有URB和锚节点有连接，就返回true。锁定时调用者的责任。


usb_get_from_anchor()
---------------------


Returns the oldest anchored URB of an anchor. The URB is unanchored
and returned with a reference. As you may mix URBs to several
destinations in one anchor you have no guarantee the chronologically
first submitted URB is returned.
usb_get_from_anchor()
---------------------
返回最早的锚节点的URB。次URB不是锚定的，并被引用返回。当你可能在
一个锚节点中混合有多个目的的URB，不能保证最先被提交的URB按顺序返回。