Commit | Line | Data |
---|---|---|
e6a79f1f ON |
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. |