diff options
author | Oliver Neukum <oliver@neukum.org> | 2008-04-09 17:37:34 +0400 |
---|---|---|
committer | Greg Kroah-Hartman <gregkh@suse.de> | 2008-04-25 08:16:51 +0400 |
commit | e6a79f1f07fc88a2efd6d0e8f0ccf591cb93cd34 (patch) | |
tree | 7026f8ab1d23ece94a327d5240ee52c95ef8285a /Documentation/usb/anchors.txt | |
parent | a082b5c7882bdbd8a86ace8470ca2ecda796d5a7 (diff) |
USB: add Documentation about usb_anchor
This adds documentation about the new usb anchor infrastructure.
Signed-off-by: Oliver Neukum <oneukum@suse.de>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Diffstat (limited to 'Documentation/usb/anchors.txt')
-rw-r--r-- | Documentation/usb/anchors.txt | 50 |
1 files changed, 50 insertions, 0 deletions
diff --git a/Documentation/usb/anchors.txt b/Documentation/usb/anchors.txt new file mode 100644 index 000000000000..7304bcf5a306 --- /dev/null +++ b/Documentation/usb/anchors.txt @@ -0,0 +1,50 @@ +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 +an URB is finished by (successfull) completion. Thus disassociation +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. + +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. |