openkylin
/
linux
mirror of https://gitee.com/openkylin/linux.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

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>
This commit is contained in:
Mauro Carvalho Chehab 2017-04-05 10:23:02 -03:00 committed by Jonathan Corbet
parent 67cc20e008
commit 79e0c2e6d4
2 changed files with 21 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
Documentation/usb/anchors.txt → Documentation/driver-api/usb/anchors.rst
View File

@ -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

1
Documentation/driver-api/usb/index.rst
View File

@ -6,6 +6,7 @@ Linux USB API
usb
gadget
anchors
writing_usb_driver
writing_musb_glue_layer