Documentation/driver-api/usb/anchors.rst

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