aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorOliver Neukum <oliver@neukum.org>2008-04-09 09:37:34 -0400
committerGreg Kroah-Hartman <gregkh@suse.de>2008-04-25 00:16:51 -0400
commite6a79f1f07fc88a2efd6d0e8f0ccf591cb93cd34 (patch)
tree7026f8ab1d23ece94a327d5240ee52c95ef8285a
parenta082b5c7882bdbd8a86ace8470ca2ecda796d5a7 (diff)
USB: add Documentation about usb_anchor
This adds documentation about the new usb anchor infrastructure. Signed-off-by: Oliver Neukum <oneukum@suse.de> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
-rw-r--r--Documentation/usb/anchors.txt50
1 files changed, 50 insertions, 0 deletions
diff --git a/Documentation/usb/anchors.txt b/Documentation/usb/anchors.txt
new file mode 100644
index 000000000000..7304bcf5a306
--- /dev/null
+++ b/Documentation/usb/anchors.txt
@@ -0,0 +1,50 @@
1What is anchor?
2===============
3
4A USB driver needs to support some callbacks requiring
5a driver to cease all IO to an interface. To do so, a
6driver has to keep track of the URBs it has submitted
7to know they've all completed or to call usb_kill_urb
8for them. The anchor is a data structure takes care of
9keeping track of URBs and provides methods to deal with
10multiple URBs.
11
12Allocation and Initialisation
13=============================
14
15There's no API to allocate an anchor. It is simply declared
16as struct usb_anchor. init_usb_anchor() must be called to
17initialise the data structure.
18
19Deallocation
20============
21
22Once it has no more URBs associated with it, the anchor can be
23freed with normal memory management operations.
24
25Association and disassociation of URBs with anchors
26===================================================
27
28An association of URBs to an anchor is made by an explicit
29call to usb_anchor_urb(). The association is maintained until
30an URB is finished by (successfull) completion. Thus disassociation
31is automatic. A function is provided to forcibly finish (kill)
32all URBs associated with an anchor.
33Furthermore, disassociation can be made with usb_unanchor_urb()
34
35Operations on multitudes of URBs
36================================
37
38usb_kill_anchored_urbs()
39------------------------
40
41This function kills all URBs associated with an anchor. The URBs
42are called in the reverse temporal order they were submitted.
43This way no data can be reordered.
44
45usb_wait_anchor_empty_timeout()
46-------------------------------
47
48This function waits for all URBs associated with an anchor to finish
49or a timeout, whichever comes first. Its return value will tell you
50whether the timeout was reached.