0001 USB Anchors
0002 ~~~~~~~~~~~
0003
0004 What is anchor?
0005 ===============
0006
0007 A USB driver needs to support some callbacks requiring
0008 a driver to cease all IO to an interface. To do so, a
0009 driver has to keep track of the URBs it has submitted
0010 to know they've all completed or to call usb_kill_urb
0011 for them. The anchor is a data structure takes care of
0012 keeping track of URBs and provides methods to deal with
0013 multiple URBs.
0014
0015 Allocation and Initialisation
0016 =============================
0017
0018 There's no API to allocate an anchor. It is simply declared
0019 as struct usb_anchor. :c:func:`init_usb_anchor` must be called to
0020 initialise the data structure.
0021
0022 Deallocation
0023 ============
0024
0025 Once it has no more URBs associated with it, the anchor can be
0026 freed with normal memory management operations.
0027
0028 Association and disassociation of URBs with anchors
0029 ===================================================
0030
0031 An association of URBs to an anchor is made by an explicit
0032 call to :c:func:`usb_anchor_urb`. The association is maintained until
0033 an URB is finished by (successful) completion. Thus disassociation
0034 is automatic. A function is provided to forcibly finish (kill)
0035 all URBs associated with an anchor.
0036 Furthermore, disassociation can be made with :c:func:`usb_unanchor_urb`
0037
0038 Operations on multitudes of URBs
0039 ================================
0040
0041 :c:func:`usb_kill_anchored_urbs`
0042 --------------------------------
0043
0044 This function kills all URBs associated with an anchor. The URBs
0045 are called in the reverse temporal order they were submitted.
0046 This way no data can be reordered.
0047
0048 :c:func:`usb_unlink_anchored_urbs`
0049 ----------------------------------
0050
0051
0052 This function unlinks all URBs associated with an anchor. The URBs
0053 are processed in the reverse temporal order they were submitted.
0054 This is similar to :c:func:`usb_kill_anchored_urbs`, but it will not sleep.
0055 Therefore no guarantee is made that the URBs have been unlinked when
0056 the call returns. They may be unlinked later but will be unlinked in
0057 finite time.
0058
0059 :c:func:`usb_scuttle_anchored_urbs`
0060 -----------------------------------
0061
0062 All URBs of an anchor are unanchored en masse.
0063
0064 :c:func:`usb_wait_anchor_empty_timeout`
0065 ---------------------------------------
0066
0067 This function waits for all URBs associated with an anchor to finish
0068 or a timeout, whichever comes first. Its return value will tell you
0069 whether the timeout was reached.
0070
0071 :c:func:`usb_anchor_empty`
0072 --------------------------
0073
0074 Returns true if no URBs are associated with an anchor. Locking
0075 is the caller's responsibility.
0076
0077 :c:func:`usb_get_from_anchor`
0078 -----------------------------
0079
0080 Returns the oldest anchored URB of an anchor. The URB is unanchored
0081 and returned with a reference. As you may mix URBs to several
0082 destinations in one anchor you have no guarantee the chronologically
0083 first submitted URB is returned.
