USB Anchors

USB anchor의 역할

USB driver의 일부 callback은 interface에 대한 모든 I/O를 중단해야 합니다. Driver는 제출한 URB를 추적해 모두 완료됐는지 확인하거나 각 URB에 `usb_kill_urb`를 호출할 수 있어야 합니다.

Anchor는 URB 추적을 담당하고 여러 URB를 함께 처리하는 method를 제공하는 data structure입니다.

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.

할당·초기화와 해제

Anchor 전용 allocation API는 없습니다. `struct usb_anchor`를 직접 선언하고 `init_usb_anchor()`를 호출해 data structure를 초기화합니다.

더 이상 연결된 URB가 없으면 일반 memory management operation으로 anchor를 해제할 수 있습니다.

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.

URB 연결과 연결 해제

URB는 `usb_anchor_urb()`를 명시적으로 호출해 anchor에 연결합니다. 성공적인 completion으로 URB가 끝날 때까지 연결이 유지되며 completion 시 자동으로 해제됩니다.

Anchor에 연결된 모든 URB를 강제로 끝내는 함수가 제공됩니다. 개별 URB는 `usb_unanchor_urb()`로 직접 연결 해제할 수도 있습니다.

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`

여러 URB에 대한 일괄 operation

`usb_kill_anchored_urbs()`는 anchor에 연결된 모든 URB를 kill합니다. URB는 제출한 시간의 역순으로 처리되므로 data 순서가 뒤바뀌지 않습니다.

`usb_scuttle_anchored_urbs()`는 anchor의 모든 URB를 한꺼번에 unanchor합니다.

`usb_wait_anchor_empty_timeout()`은 연결된 모든 URB가 끝나거나 timeout에 도달할 때까지 기다리며 반환값으로 timeout 도달 여부를 알립니다.

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.

Anchor 상태 조회와 오래된 URB 회수

`usb_anchor_empty()`는 anchor에 연결된 URB가 없으면 true를 반환합니다. Locking은 caller가 책임집니다.

`usb_get_from_anchor()`는 anchor에서 가장 오래된 anchored URB를 unanchor하고 reference를 보유한 상태로 반환합니다. 하나의 anchor에 여러 destination용 URB를 섞을 수 있으므로 시간상 가장 먼저 제출된 URB가 반드시 반환된다는 보장은 없습니다.

: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
destinations in one anchor you have no guarantee the chronologically
first submitted URB is returned.