diff options
author | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2017-04-05 16:23:02 +0300 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2017-04-11 23:38:44 +0300 |
commit | 79e0c2e6d4a382a7ac80cf082e3ca60bd42ab475 (patch) | |
tree | 4d20b6280e2efdeacb4b5578ebdc4b15ddafb8d7 /Documentation/driver-api/usb/anchors.rst | |
parent | 67cc20e0080479741e2328b97226cfab2eed91e9 (diff) | |
download | linux-79e0c2e6d4a382a7ac80cf082e3ca60bd42ab475.tar.xz |
usb/anchors.txt: convert to ReST and add to driver-api book
This document describe some USB core functions. Add it to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/driver-api/usb/anchors.rst')
-rw-r--r-- | Documentation/driver-api/usb/anchors.rst | 83 |
1 files changed, 83 insertions, 0 deletions
diff --git a/Documentation/driver-api/usb/anchors.rst b/Documentation/driver-api/usb/anchors.rst new file mode 100644 index 000000000000..4b248e691bd6 --- /dev/null +++ b/Documentation/driver-api/usb/anchors.rst @@ -0,0 +1,83 @@ +USB Anchors +~~~~~~~~~~~ + +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. :c:func:`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 :c:func:`usb_anchor_urb`. The association is maintained until +an URB is finished by (successful) 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 :c:func:`usb_unanchor_urb` + +Operations on multitudes of URBs +================================ + +:c:func:`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. + +:c:func:`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 :c:func:`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. + +:c:func:`usb_scuttle_anchored_urbs` +----------------------------------- + +All URBs of an anchor are unanchored en masse. + +:c:func:`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. + +:c:func:`usb_anchor_empty` +-------------------------- + +Returns true if no URBs are associated with an anchor. Locking +is the caller's responsibility. + +:c:func:`usb_get_from_anchor` +----------------------------- + +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 +first submitted URB is returned. |