blob: 6f24f566955ada1439c0f34acb0a6c4e1573d704 [file] [log] [blame]
Oliver Neukume6a79f12008-04-09 15:37:34 +02001What 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
Oliver Neukum697e04d2008-09-02 10:52:08 +020045usb_unlink_anchored_urbs()
46--------------------------
47
48This function unlinks all URBs associated with an anchor. The URBs
49are processed in the reverse temporal order they were submitted.
50This is similar to usb_kill_anchored_urbs(), but it will not sleep.
51Therefore no guarantee is made that the URBs have been unlinked when
52the call returns. They may be unlinked later but will be unlinked in
53finite time.
54
Oliver Neukumd1b19442008-09-02 14:16:11 +020055usb_scuttle_anchored_urbs()
56---------------------------
57
58All URBs of an anchor are unanchored en masse.
59
Oliver Neukume6a79f12008-04-09 15:37:34 +020060usb_wait_anchor_empty_timeout()
61-------------------------------
62
63This function waits for all URBs associated with an anchor to finish
64or a timeout, whichever comes first. Its return value will tell you
65whether the timeout was reached.
Oliver Neukum697e04d2008-09-02 10:52:08 +020066
Oliver Neukumd1b19442008-09-02 14:16:11 +020067usb_anchor_empty()
68------------------
Oliver Neukum697e04d2008-09-02 10:52:08 +020069
Oliver Neukumd1b19442008-09-02 14:16:11 +020070Returns true if no URBs are associated with an anchor. Locking
71is the caller's responsibility.
72
73usb_get_from_anchor()
74---------------------
75
76Returns the oldest anchored URB of an anchor. The URB is unanchored
77and returned with a reference. As you may mix URBs to several
78destinations in one anchor you have no guarantee the chronologically
79first submitted URB is returned.