From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Linux Media Mailing List <linux-media@vger.kernel.org>,
Linux Doc Mailing List <linux-doc@vger.kernel.org>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>,
Mauro Carvalho Chehab <mchehab@infradead.org>,
John Youn <johnyoun@synopsys.com>,
linux-usb@vger.kernel.org, linux-rpi-kernel@lists.infradead.org,
Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
Jonathan Corbet <corbet@lwn.net>,
Mauro Carvalho Chehab <mchehab@kernel.org>
Subject: [PATCH v2 08/22] usb/anchors.txt: convert to ReST and add to driver-api book
Date: Thu, 30 Mar 2017 07:45:42 -0300 [thread overview]
Message-ID: <27e02685a76dae589625368f18782d4a27f34c45.1490870599.git.mchehab@s-opensource.com> (raw)
In-Reply-To: <3068fc7fac09293300b9c59ece0adb985232de12.1490870599.git.mchehab@s-opensource.com>
In-Reply-To: <3068fc7fac09293300b9c59ece0adb985232de12.1490870599.git.mchehab@s-opensource.com>
This document describe some USB core functions. Add it to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
.../anchors.txt => driver-api/usb/anchors.rst} | 36 ++++++++++++----------
Documentation/driver-api/usb/index.rst | 1 +
2 files changed, 21 insertions(+), 16 deletions(-)
rename Documentation/{usb/anchors.txt => driver-api/usb/anchors.rst} (75%)
diff --git a/Documentation/usb/anchors.txt b/Documentation/driver-api/usb/anchors.rst
similarity index 75%
rename from Documentation/usb/anchors.txt
rename to Documentation/driver-api/usb/anchors.rst
index fe6a99a32bbd..4b248e691bd6 100644
--- a/Documentation/usb/anchors.txt
+++ b/Documentation/driver-api/usb/anchors.rst
@@ -1,3 +1,6 @@
+USB Anchors
+~~~~~~~~~~~
+
What is anchor?
===============
@@ -13,7 +16,7 @@ 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
+as struct usb_anchor. :c:func:`init_usb_anchor` must be called to
initialise the data structure.
Deallocation
@@ -26,52 +29,53 @@ 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
+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 usb_unanchor_urb()
+Furthermore, disassociation can be made with :c:func:`usb_unanchor_urb`
Operations on multitudes of URBs
================================
-usb_kill_anchored_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.
-usb_unlink_anchored_urbs()
---------------------------
+: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 usb_kill_anchored_urbs(), but it will not sleep.
+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.
-usb_scuttle_anchored_urbs()
----------------------------
+:c:func:`usb_scuttle_anchored_urbs`
+-----------------------------------
All URBs of an anchor are unanchored en masse.
-usb_wait_anchor_empty_timeout()
--------------------------------
+: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.
-usb_anchor_empty()
-------------------
+:c:func:`usb_anchor_empty`
+--------------------------
Returns true if no URBs are associated with an anchor. Locking
is the caller's responsibility.
-usb_get_from_anchor()
----------------------
+: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
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index cf2fa2e8d236..5dfb04b2d730 100644
--- 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
--
2.9.3
next prev parent reply other threads:[~2017-03-30 10:46 UTC|newest]
Thread overview: 27+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-03-30 10:45 [PATCH v2 01/22] tmplcvt: make the tool more robust Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 02/22] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 03/22] docs-rst: convert usb docbooks to ReST Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 04/22] usb.rst: Enrich its ReST representation Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 05/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 06/22] writing_usb_driver.rst: Enrich its ReST representation Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 07/22] writing_musb_glue_layer.rst: " Mauro Carvalho Chehab
2017-03-30 10:45 ` Mauro Carvalho Chehab [this message]
2017-03-30 10:45 ` [PATCH v2 09/22] usb/bulk-streams.txt: convert to ReST and add to driver-api book Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 10/22] usb/callbacks.txt: " Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 11/22] usb/power-management.txt: " Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 12/22] usb/dma.txt: " Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 13/22] error-codes.rst: " Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 14/22] usb/hotplug.txt: " Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 15/22] usb/persist.txt: " Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 16/22] usb/URB.txt: convert to ReST and update it Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 17/22] usb.rst: get rid of some Sphinx errors Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 18/22] usb: get rid of some ReST doc build errors Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 19/22] usb: composite.h: fix two warnings when building docs Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 20/22] usb: gadget.h: be consistent at kernel doc macros Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 21/22] docs-rst: fix usb cross-references Mauro Carvalho Chehab
2017-03-30 10:45 ` Mauro Carvalho Chehab
2017-03-30 10:45 ` [PATCH v2 22/22] usb: document that URB transfer_buffer should be aligned Mauro Carvalho Chehab
2017-03-30 10:58 ` [PATCH v2 01/22] tmplcvt: make the tool more robust Mauro Carvalho Chehab
2017-03-30 11:45 ` Jani Nikula
2017-04-02 21:32 ` Jonathan Corbet
2017-04-05 13:07 ` Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=27e02685a76dae589625368f18782d4a27f34c45.1490870599.git.mchehab@s-opensource.com \
--to=mchehab@s-opensource.com \
--cc=corbet@lwn.net \
--cc=gregkh@linuxfoundation.org \
--cc=johnyoun@synopsys.com \
--cc=laurent.pinchart@ideasonboard.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-media@vger.kernel.org \
--cc=linux-rpi-kernel@lists.infradead.org \
--cc=linux-usb@vger.kernel.org \
--cc=mchehab@infradead.org \
--cc=mchehab@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.