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.

Chinese maintainer: keyingjing <342311642@qq.com>
---------------------------------------------------------------------
Documentation/usb/anchors.txt 的中文翻译

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

中文版维护者： 柯莹璟  <342311642@qq.com>
中文版翻译者： 柯莹璟  <342311642@qq.com>
中文版校译者： 柯莹璟  <342311642@qq.com>

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接口。要做到这一点，
驱动器需要跟踪URBs，它已提交知道URBs全部完成或为他们调用usb_kill_urb。锚是
一种数据结构，负责跟踪URBs并提供多个UEBs的处理方法。

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.

释放
====
一旦没有更多的URBs与锚相关，锚被释放与正常的内存管理操作。

Association and disassociation of URBs with anchors
==================================================
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.Furthermore,
disassociation can be made with usb_unanchor_urb().

URBs与锚的关联和分离
====================
锚与URBs的关联是由usb_anchor_urb()显式调用。该关联会一直保持到一个URB成功完成。
因此分离是自动的。一个函数被提供用来强行完成（或杀死）所有的与URBs相关的锚。
此外，可以用usb_unanchor_urb()分离。

Operations on multitudes of URBs
================================
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.

URBs的众多操作
==============
usb_kill_anchored_urbs()
------------------------
这个函数杀死所有URBs的相关锚。URBs被逆时间顺序调用提交，通过这种方式，没有数据可以
被重新排列。

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()
--------------------------
该函数解除所有URBs与锚的链接。URBs被逆时间顺序提交处理，这与usb_kill_anchored_urbs()
类似，但是它不会休眠。因此，概无保证URBs在调用返回时会被解除链接。他们可能被解除链接，
但在有限的时间里被解除链接。

usb_scuttle_anchored_urbs()
---------------------------
All URBs of an anchor are unanchored en masse.

usb_scuttle_anchored_urbs()
---------------------------
一个锚所有的URBs一齐被解开。

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()
-------------------------------
该函数等待所有URBs的相关锚完成或者超时，以先到者为准。其返回值反应是否超时。

usb_anchor_empty()
------------------
Returns true if no URBs are associated with an anchor. Locking is the caller's
responsibility.

usb_anchor_empty()
------------------
如果URBs没有相关锚函数返回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不是固定的并返回一个引用。你可能在一个锚里混合了多个URBs
目的地，你不能保证按时间顺序最先提交的URBs被返回。