1*4882a593SmuzhiyunUSB Anchors 2*4882a593Smuzhiyun~~~~~~~~~~~ 3*4882a593Smuzhiyun 4*4882a593SmuzhiyunWhat is anchor? 5*4882a593Smuzhiyun=============== 6*4882a593Smuzhiyun 7*4882a593SmuzhiyunA USB driver needs to support some callbacks requiring 8*4882a593Smuzhiyuna driver to cease all IO to an interface. To do so, a 9*4882a593Smuzhiyundriver has to keep track of the URBs it has submitted 10*4882a593Smuzhiyunto know they've all completed or to call usb_kill_urb 11*4882a593Smuzhiyunfor them. The anchor is a data structure takes care of 12*4882a593Smuzhiyunkeeping track of URBs and provides methods to deal with 13*4882a593Smuzhiyunmultiple URBs. 14*4882a593Smuzhiyun 15*4882a593SmuzhiyunAllocation and Initialisation 16*4882a593Smuzhiyun============================= 17*4882a593Smuzhiyun 18*4882a593SmuzhiyunThere's no API to allocate an anchor. It is simply declared 19*4882a593Smuzhiyunas struct usb_anchor. :c:func:`init_usb_anchor` must be called to 20*4882a593Smuzhiyuninitialise the data structure. 21*4882a593Smuzhiyun 22*4882a593SmuzhiyunDeallocation 23*4882a593Smuzhiyun============ 24*4882a593Smuzhiyun 25*4882a593SmuzhiyunOnce it has no more URBs associated with it, the anchor can be 26*4882a593Smuzhiyunfreed with normal memory management operations. 27*4882a593Smuzhiyun 28*4882a593SmuzhiyunAssociation and disassociation of URBs with anchors 29*4882a593Smuzhiyun=================================================== 30*4882a593Smuzhiyun 31*4882a593SmuzhiyunAn association of URBs to an anchor is made by an explicit 32*4882a593Smuzhiyuncall to :c:func:`usb_anchor_urb`. The association is maintained until 33*4882a593Smuzhiyunan URB is finished by (successful) completion. Thus disassociation 34*4882a593Smuzhiyunis automatic. A function is provided to forcibly finish (kill) 35*4882a593Smuzhiyunall URBs associated with an anchor. 36*4882a593SmuzhiyunFurthermore, disassociation can be made with :c:func:`usb_unanchor_urb` 37*4882a593Smuzhiyun 38*4882a593SmuzhiyunOperations on multitudes of URBs 39*4882a593Smuzhiyun================================ 40*4882a593Smuzhiyun 41*4882a593Smuzhiyun:c:func:`usb_kill_anchored_urbs` 42*4882a593Smuzhiyun-------------------------------- 43*4882a593Smuzhiyun 44*4882a593SmuzhiyunThis function kills all URBs associated with an anchor. The URBs 45*4882a593Smuzhiyunare called in the reverse temporal order they were submitted. 46*4882a593SmuzhiyunThis way no data can be reordered. 47*4882a593Smuzhiyun 48*4882a593Smuzhiyun:c:func:`usb_unlink_anchored_urbs` 49*4882a593Smuzhiyun---------------------------------- 50*4882a593Smuzhiyun 51*4882a593Smuzhiyun 52*4882a593SmuzhiyunThis function unlinks all URBs associated with an anchor. The URBs 53*4882a593Smuzhiyunare processed in the reverse temporal order they were submitted. 54*4882a593SmuzhiyunThis is similar to :c:func:`usb_kill_anchored_urbs`, but it will not sleep. 55*4882a593SmuzhiyunTherefore no guarantee is made that the URBs have been unlinked when 56*4882a593Smuzhiyunthe call returns. They may be unlinked later but will be unlinked in 57*4882a593Smuzhiyunfinite time. 58*4882a593Smuzhiyun 59*4882a593Smuzhiyun:c:func:`usb_scuttle_anchored_urbs` 60*4882a593Smuzhiyun----------------------------------- 61*4882a593Smuzhiyun 62*4882a593SmuzhiyunAll URBs of an anchor are unanchored en masse. 63*4882a593Smuzhiyun 64*4882a593Smuzhiyun:c:func:`usb_wait_anchor_empty_timeout` 65*4882a593Smuzhiyun--------------------------------------- 66*4882a593Smuzhiyun 67*4882a593SmuzhiyunThis function waits for all URBs associated with an anchor to finish 68*4882a593Smuzhiyunor a timeout, whichever comes first. Its return value will tell you 69*4882a593Smuzhiyunwhether the timeout was reached. 70*4882a593Smuzhiyun 71*4882a593Smuzhiyun:c:func:`usb_anchor_empty` 72*4882a593Smuzhiyun-------------------------- 73*4882a593Smuzhiyun 74*4882a593SmuzhiyunReturns true if no URBs are associated with an anchor. Locking 75*4882a593Smuzhiyunis the caller's responsibility. 76*4882a593Smuzhiyun 77*4882a593Smuzhiyun:c:func:`usb_get_from_anchor` 78*4882a593Smuzhiyun----------------------------- 79*4882a593Smuzhiyun 80*4882a593SmuzhiyunReturns the oldest anchored URB of an anchor. The URB is unanchored 81*4882a593Smuzhiyunand returned with a reference. As you may mix URBs to several 82*4882a593Smuzhiyundestinations in one anchor you have no guarantee the chronologically 83*4882a593Smuzhiyunfirst submitted URB is returned. 84