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>

diff --git a/Documentation/driver-api/usb/anchors.rst b/Documentation/driver-api/usb/anchors.rst
new file mode 100644 (file)
index 0000000..4b248e6
--- /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.

diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index cf2fa2e8d23665bfd80089bf74d9b6406c1c09c6..5dfb04b2d7304ee939d9b424bfa4f9d992f641a4 100644 (file)
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -6,6 +6,7 @@ Linux USB API
 
    usb
    gadget
+   anchors
    writing_usb_driver
    writing_musb_glue_layer
 

diff --git a/Documentation/usb/anchors.txt b/Documentation/usb/anchors.txt
deleted file mode 100644 (file)
index fe6a99a..0000000
--- a/Documentation/usb/anchors.txt
+++ /dev/null
@@ -1,79 +0,0 @@
-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 (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 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_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 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.
-
-usb_scuttle_anchored_urbs()
----------------------------
-
-All URBs of an anchor are unanchored en masse.
-
-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.
-
-usb_anchor_empty()
-------------------
-
-Returns true if no URBs are associated with an anchor. Locking
-is the caller's responsibility.
-
-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.