[linux.git] / Documentation / usb / anchors.txt

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.
Commit	Line	Data
e6a79f1f ON	1	What is anchor?
	2	===============
	3
	4	A USB driver needs to support some callbacks requiring
	5	a driver to cease all IO to an interface. To do so, a
	6	driver has to keep track of the URBs it has submitted
	7	to know they've all completed or to call usb_kill_urb
	8	for them. The anchor is a data structure takes care of
	9	keeping track of URBs and provides methods to deal with
	10	multiple URBs.
	11
	12	Allocation and Initialisation
	13	=============================
	14
	15	There's no API to allocate an anchor. It is simply declared
	16	as struct usb_anchor. init_usb_anchor() must be called to
	17	initialise the data structure.
	18
	19	Deallocation
	20	============
	21
	22	Once it has no more URBs associated with it, the anchor can be
	23	freed with normal memory management operations.
	24
	25	Association and disassociation of URBs with anchors
	26	===================================================
	27
	28	An association of URBs to an anchor is made by an explicit
	29	call to usb_anchor_urb(). The association is maintained until
19f59460	30	an URB is finished by (successful) completion. Thus disassociation
e6a79f1f ON	31	is automatic. A function is provided to forcibly finish (kill)
	32	all URBs associated with an anchor.
	33	Furthermore, disassociation can be made with usb_unanchor_urb()
	34
	35	Operations on multitudes of URBs
	36	================================
	37
	38	usb_kill_anchored_urbs()
	39	------------------------
	40
	41	This function kills all URBs associated with an anchor. The URBs
	42	are called in the reverse temporal order they were submitted.
	43	This way no data can be reordered.
	44
697e04db ON	45	usb_unlink_anchored_urbs()
	46	--------------------------
	47
	48	This function unlinks all URBs associated with an anchor. The URBs
	49	are processed in the reverse temporal order they were submitted.
	50	This is similar to usb_kill_anchored_urbs(), but it will not sleep.
	51	Therefore no guarantee is made that the URBs have been unlinked when
	52	the call returns. They may be unlinked later but will be unlinked in
	53	finite time.
	54
d1b19440 ON	55	usb_scuttle_anchored_urbs()
	56	---------------------------
	57
	58	All URBs of an anchor are unanchored en masse.
	59
e6a79f1f ON	60	usb_wait_anchor_empty_timeout()
	61	-------------------------------
	62
	63	This function waits for all URBs associated with an anchor to finish
	64	or a timeout, whichever comes first. Its return value will tell you
	65	whether the timeout was reached.
697e04db	66
d1b19440 ON	67	usb_anchor_empty()
	68	------------------
	69
	70	Returns true if no URBs are associated with an anchor. Locking
	71	is the caller's responsibility.
	72
	73	usb_get_from_anchor()
	74	---------------------
697e04db	75
d1b19440 ON	76	Returns the oldest anchored URB of an anchor. The URB is unanchored
	77	and returned with a reference. As you may mix URBs to several
	78	destinations in one anchor you have no guarantee the chronologically
19f59460	79	first submitted URB is returned.