|author||Oliver Neukum <firstname.lastname@example.org>||2008-04-09 15:37:34 +0200|
|committer||Greg Kroah-Hartman <email@example.com>||2008-04-24 21:16:51 -0700|
USB: add Documentation about usb_anchor
This adds documentation about the new usb anchor infrastructure. Signed-off-by: Oliver Neukum <firstname.lastname@example.org> Signed-off-by: Greg Kroah-Hartman <email@example.com>
Diffstat (limited to 'Documentation')
1 files changed, 50 insertions, 0 deletions
diff --git a/Documentation/usb/anchors.txt b/Documentation/usb/anchors.txt
new file mode 100644
@@ -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
+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.
+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
+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.
+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.