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 的中文翻譯
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.
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().
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.
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_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_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.
