Documentation/driver-api/usb/anchors.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/usb/anchors.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/usb/anchors.rst
Extension
.rst
Size
2347 bytes
Lines
73
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

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

Annotation

Implementation Notes