git.oblomov.eu Git - linux-2.6/blob - Documentation/usb/anchors.txt

   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 (successfull) 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_wait_anchor_empty_timeout()
  46 -------------------------------
  47
  48 This function waits for all URBs associated with an anchor to finish
  49 or a timeout, whichever comes first. Its return value will tell you
  50 whether the timeout was reached.