anchors.rst (2779B)
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_unlink_anchored_urbs` 49---------------------------------- 50 51 52This function unlinks all URBs associated with an anchor. The URBs 53are processed in the reverse temporal order they were submitted. 54This is similar to :c:func:`usb_kill_anchored_urbs`, but it will not sleep. 55Therefore no guarantee is made that the URBs have been unlinked when 56the call returns. They may be unlinked later but will be unlinked in 57finite time. 58 59:c:func:`usb_scuttle_anchored_urbs` 60----------------------------------- 61 62All URBs of an anchor are unanchored en masse. 63 64:c:func:`usb_wait_anchor_empty_timeout` 65--------------------------------------- 66 67This function waits for all URBs associated with an anchor to finish 68or a timeout, whichever comes first. Its return value will tell you 69whether the timeout was reached. 70 71:c:func:`usb_anchor_empty` 72-------------------------- 73 74Returns true if no URBs are associated with an anchor. Locking 75is the caller's responsibility. 76 77:c:func:`usb_get_from_anchor` 78----------------------------- 79 80Returns the oldest anchored URB of an anchor. The URB is unanchored 81and returned with a reference. As you may mix URBs to several 82destinations in one anchor you have no guarantee the chronologically 83first submitted URB is returned.