1 USB Anchors 1 USB Anchors
2 ~~~~~~~~~~~ 2 ~~~~~~~~~~~
3 3
4 What is anchor? 4 What is anchor?
5 =============== 5 ===============
6 6
7 A USB driver needs to support some callbacks r 7 A USB driver needs to support some callbacks requiring
8 a driver to cease all IO to an interface. To d 8 a driver to cease all IO to an interface. To do so, a
9 driver has to keep track of the URBs it has su 9 driver has to keep track of the URBs it has submitted
10 to know they've all completed or to call usb_k 10 to know they've all completed or to call usb_kill_urb
11 for them. The anchor is a data structure takes 11 for them. The anchor is a data structure takes care of
12 keeping track of URBs and provides methods to 12 keeping track of URBs and provides methods to deal with
13 multiple URBs. 13 multiple URBs.
14 14
15 Allocation and Initialisation 15 Allocation and Initialisation
16 ============================= 16 =============================
17 17
18 There's no API to allocate an anchor. It is si 18 There's no API to allocate an anchor. It is simply declared
19 as struct usb_anchor. :c:func:`init_usb_anchor 19 as struct usb_anchor. :c:func:`init_usb_anchor` must be called to
20 initialise the data structure. 20 initialise the data structure.
21 21
22 Deallocation 22 Deallocation
23 ============ 23 ============
24 24
25 Once it has no more URBs associated with it, t 25 Once it has no more URBs associated with it, the anchor can be
26 freed with normal memory management operations 26 freed with normal memory management operations.
27 27
28 Association and disassociation of URBs with an 28 Association and disassociation of URBs with anchors
29 ============================================== 29 ===================================================
30 30
31 An association of URBs to an anchor is made by 31 An association of URBs to an anchor is made by an explicit
32 call to :c:func:`usb_anchor_urb`. The associat 32 call to :c:func:`usb_anchor_urb`. The association is maintained until
33 an URB is finished by (successful) completion. 33 an URB is finished by (successful) completion. Thus disassociation
34 is automatic. A function is provided to forcib 34 is automatic. A function is provided to forcibly finish (kill)
35 all URBs associated with an anchor. 35 all URBs associated with an anchor.
36 Furthermore, disassociation can be made with : 36 Furthermore, disassociation can be made with :c:func:`usb_unanchor_urb`
37 37
38 Operations on multitudes of URBs 38 Operations on multitudes of URBs
39 ================================ 39 ================================
40 40
41 :c:func:`usb_kill_anchored_urbs` 41 :c:func:`usb_kill_anchored_urbs`
42 -------------------------------- 42 --------------------------------
43 43
44 This function kills all URBs associated with a 44 This function kills all URBs associated with an anchor. The URBs
45 are called in the reverse temporal order they 45 are called in the reverse temporal order they were submitted.
46 This way no data can be reordered. 46 This way no data can be reordered.
47 47
48 :c:func:`usb_unlink_anchored_urbs` 48 :c:func:`usb_unlink_anchored_urbs`
49 ---------------------------------- 49 ----------------------------------
50 50
51 51
52 This function unlinks all URBs associated with 52 This function unlinks all URBs associated with an anchor. The URBs
53 are processed in the reverse temporal order th 53 are processed in the reverse temporal order they were submitted.
54 This is similar to :c:func:`usb_kill_anchored_ 54 This is similar to :c:func:`usb_kill_anchored_urbs`, but it will not sleep.
55 Therefore no guarantee is made that the URBs h 55 Therefore no guarantee is made that the URBs have been unlinked when
56 the call returns. They may be unlinked later b 56 the call returns. They may be unlinked later but will be unlinked in
57 finite time. 57 finite time.
58 58
59 :c:func:`usb_scuttle_anchored_urbs` 59 :c:func:`usb_scuttle_anchored_urbs`
60 ----------------------------------- 60 -----------------------------------
61 61
62 All URBs of an anchor are unanchored en masse. 62 All URBs of an anchor are unanchored en masse.
63 63
64 :c:func:`usb_wait_anchor_empty_timeout` 64 :c:func:`usb_wait_anchor_empty_timeout`
65 --------------------------------------- 65 ---------------------------------------
66 66
67 This function waits for all URBs associated wi 67 This function waits for all URBs associated with an anchor to finish
68 or a timeout, whichever comes first. Its retur 68 or a timeout, whichever comes first. Its return value will tell you
69 whether the timeout was reached. 69 whether the timeout was reached.
70 70
71 :c:func:`usb_anchor_empty` 71 :c:func:`usb_anchor_empty`
72 -------------------------- 72 --------------------------
73 73
74 Returns true if no URBs are associated with an 74 Returns true if no URBs are associated with an anchor. Locking
75 is the caller's responsibility. 75 is the caller's responsibility.
76 76
77 :c:func:`usb_get_from_anchor` 77 :c:func:`usb_get_from_anchor`
78 ----------------------------- 78 -----------------------------
79 79
80 Returns the oldest anchored URB of an anchor. 80 Returns the oldest anchored URB of an anchor. The URB is unanchored
81 and returned with a reference. As you may mix 81 and returned with a reference. As you may mix URBs to several
82 destinations in one anchor you have no guarant 82 destinations in one anchor you have no guarantee the chronologically
83 first submitted URB is returned. 83 first submitted URB is returned.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.