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