From 2b7325e6dbda03fc8831cb35c2416e15480d7f2c Mon Sep 17 00:00:00 2001
From: Oliver Neukum <oliver@neukum.org>
Date: Wed, 9 Apr 2008 15:37:34 +0200
Subject: [PATCH] --- yaml --- r: 93359 b: refs/heads/master c:
 e6a79f1f07fc88a2efd6d0e8f0ccf591cb93cd34 h: refs/heads/master i:   93357:
 a17b65940b47acc08dc81d5e36057af5a37bf867   93355:
 1f99b5e9e84a8c75a298a7a7b41c28eb6516d5cb   93351:
 6b5e35d97b991e95845957d1625ed0b32e800cee   93343:
 77c75e70f8054daacec19f7d24c2b48e079d0aaa v: v3

---
 [refs]                              |  2 +-
 trunk/Documentation/usb/anchors.txt | 50 +++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+), 1 deletion(-)
 create mode 100644 trunk/Documentation/usb/anchors.txt

diff --git a/[refs] b/[refs]
index cb99fb64edf3..0eb0ed5f24e3 100644
--- a/[refs]
+++ b/[refs]
@@ -1,2 +1,2 @@
 ---
-refs/heads/master: a082b5c7882bdbd8a86ace8470ca2ecda796d5a7
+refs/heads/master: e6a79f1f07fc88a2efd6d0e8f0ccf591cb93cd34
diff --git a/trunk/Documentation/usb/anchors.txt b/trunk/Documentation/usb/anchors.txt
new file mode 100644
index 000000000000..7304bcf5a306
--- /dev/null
+++ b/trunk/Documentation/usb/anchors.txt
@@ -0,0 +1,50 @@
+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.
+
+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.
+
+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 (successfull) 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_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.