mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-09-29 13:53:33 +00:00
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:
parent
67cc20e008
commit
79e0c2e6d4
2 changed files with 21 additions and 16 deletions
|
@ -1,3 +1,6 @@
|
||||||
|
USB Anchors
|
||||||
|
~~~~~~~~~~~
|
||||||
|
|
||||||
What is anchor?
|
What is anchor?
|
||||||
===============
|
===============
|
||||||
|
|
||||||
|
@ -13,7 +16,7 @@ Allocation and Initialisation
|
||||||
=============================
|
=============================
|
||||||
|
|
||||||
There's no API to allocate an anchor. It is simply declared
|
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.
|
initialise the data structure.
|
||||||
|
|
||||||
Deallocation
|
Deallocation
|
||||||
|
@ -26,52 +29,53 @@ Association and disassociation of URBs with anchors
|
||||||
===================================================
|
===================================================
|
||||||
|
|
||||||
An association of URBs to an anchor is made by an explicit
|
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
|
an URB is finished by (successful) completion. Thus disassociation
|
||||||
is automatic. A function is provided to forcibly finish (kill)
|
is automatic. A function is provided to forcibly finish (kill)
|
||||||
all URBs associated with an anchor.
|
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
|
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
|
This function kills all URBs associated with an anchor. The URBs
|
||||||
are called in the reverse temporal order they were submitted.
|
are called in the reverse temporal order they were submitted.
|
||||||
This way no data can be reordered.
|
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
|
This function unlinks all URBs associated with an anchor. The URBs
|
||||||
are processed in the reverse temporal order they were submitted.
|
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
|
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
|
the call returns. They may be unlinked later but will be unlinked in
|
||||||
finite time.
|
finite time.
|
||||||
|
|
||||||
usb_scuttle_anchored_urbs()
|
:c:func:`usb_scuttle_anchored_urbs`
|
||||||
---------------------------
|
-----------------------------------
|
||||||
|
|
||||||
All URBs of an anchor are unanchored en masse.
|
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
|
This function waits for all URBs associated with an anchor to finish
|
||||||
or a timeout, whichever comes first. Its return value will tell you
|
or a timeout, whichever comes first. Its return value will tell you
|
||||||
whether the timeout was reached.
|
whether the timeout was reached.
|
||||||
|
|
||||||
usb_anchor_empty()
|
:c:func:`usb_anchor_empty`
|
||||||
------------------
|
--------------------------
|
||||||
|
|
||||||
Returns true if no URBs are associated with an anchor. Locking
|
Returns true if no URBs are associated with an anchor. Locking
|
||||||
is the caller's responsibility.
|
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
|
Returns the oldest anchored URB of an anchor. The URB is unanchored
|
||||||
and returned with a reference. As you may mix URBs to several
|
and returned with a reference. As you may mix URBs to several
|
|
@ -6,6 +6,7 @@ Linux USB API
|
||||||
|
|
||||||
usb
|
usb
|
||||||
gadget
|
gadget
|
||||||
|
anchors
|
||||||
writing_usb_driver
|
writing_usb_driver
|
||||||
writing_musb_glue_layer
|
writing_musb_glue_layer
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue