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