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