Orange Pi5 kernel

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