Blame view

Documentation/usb/anchors.txt 2.56 KB
e6a79f1f0   Oliver Neukum   USB: add Document...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
  What is anchor?
  ===============
  
  A USB driver needs to support some callbacks requiring
  a driver to cease all IO to an interface. To do so, a
  driver has to keep track of the URBs it has submitted
  to know they've all completed or to call usb_kill_urb
  for them. The anchor is a data structure takes care of
  keeping track of URBs and provides methods to deal with
  multiple URBs.
  
  Allocation and Initialisation
  =============================
  
  There's no API to allocate an anchor. It is simply declared
  as struct usb_anchor. init_usb_anchor() must be called to
  initialise the data structure.
  
  Deallocation
  ============
  
  Once it has no more URBs associated with it, the anchor can be
  freed with normal memory management operations.
  
  Association and disassociation of URBs with anchors
  ===================================================
  
  An association of URBs to an anchor is made by an explicit
  call to usb_anchor_urb(). The association is maintained until
19f594600   Matt LaPlante   trivial: Miscella...
30
  an URB is finished by (successful) completion. Thus disassociation
e6a79f1f0   Oliver Neukum   USB: add Document...
31
32
33
34
35
36
37
38
39
40
41
42
43
  is automatic. A function is provided to forcibly finish (kill)
  all URBs associated with an anchor.
  Furthermore, disassociation can be made with usb_unanchor_urb()
  
  Operations on multitudes of URBs
  ================================
  
  usb_kill_anchored_urbs()
  ------------------------
  
  This function kills all URBs associated with an anchor. The URBs
  are called in the reverse temporal order they were submitted.
  This way no data can be reordered.
697e04db5   Oliver Neukum   USB: update of Do...
44
45
46
47
48
49
50
51
52
  usb_unlink_anchored_urbs()
  --------------------------
  
  This function unlinks all URBs associated with an anchor. The URBs
  are processed in the reverse temporal order they were submitted.
  This is similar to usb_kill_anchored_urbs(), but it will not sleep.
  Therefore no guarantee is made that the URBs have been unlinked when
  the call returns. They may be unlinked later but will be unlinked in
  finite time.
d1b194408   Oliver Neukum   USB: Documentatio...
53
54
55
56
  usb_scuttle_anchored_urbs()
  ---------------------------
  
  All URBs of an anchor are unanchored en masse.
e6a79f1f0   Oliver Neukum   USB: add Document...
57
58
59
60
61
62
  usb_wait_anchor_empty_timeout()
  -------------------------------
  
  This function waits for all URBs associated with an anchor to finish
  or a timeout, whichever comes first. Its return value will tell you
  whether the timeout was reached.
697e04db5   Oliver Neukum   USB: update of Do...
63

d1b194408   Oliver Neukum   USB: Documentatio...
64
65
66
67
68
69
70
71
  usb_anchor_empty()
  ------------------
  
  Returns true if no URBs are associated with an anchor. Locking
  is the caller's responsibility.
  
  usb_get_from_anchor()
  ---------------------
697e04db5   Oliver Neukum   USB: update of Do...
72

d1b194408   Oliver Neukum   USB: Documentatio...
73
74
75
  Returns the oldest anchored URB of an anchor. The URB is unanchored
  and returned with a reference. As you may mix URBs to several
  destinations in one anchor you have no guarantee the chronologically
19f594600   Matt LaPlante   trivial: Miscella...
76
  first submitted URB is returned.