linux/Documentation/usb/URB.txt
<<
>>
Prefs
   1Revised: 2000-Dec-05.
   2Again:   2002-Jul-06
   3Again:   2005-Sep-19
   4
   5    NOTE:
   6
   7    The USB subsystem now has a substantial section in "The Linux Kernel API"
   8    guide (in Documentation/DocBook), generated from the current source
   9    code.  This particular documentation file isn't particularly current or
  10    complete; don't rely on it except for a quick overview.
  11
  12
  131.1. Basic concept or 'What is an URB?'
  14
  15The basic idea of the new driver is message passing, the message itself is 
  16called USB Request Block, or URB for short. 
  17
  18- An URB consists of all relevant information to execute any USB transaction 
  19  and deliver the data and status back. 
  20
  21- Execution of an URB is inherently an asynchronous operation, i.e. the 
  22  usb_submit_urb(urb) call returns immediately after it has successfully
  23  queued the requested action.
  24
  25- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time. 
  26
  27- Each URB has a completion handler, which is called after the action
  28  has been successfully completed or canceled. The URB also contains a
  29  context-pointer for passing information to the completion handler.
  30
  31- Each endpoint for a device logically supports a queue of requests.
  32  You can fill that queue, so that the USB hardware can still transfer
  33  data to an endpoint while your driver handles completion of another.
  34  This maximizes use of USB bandwidth, and supports seamless streaming
  35  of data to (or from) devices when using periodic transfer modes.
  36
  37
  381.2. The URB structure
  39
  40Some of the fields in an URB are:
  41
  42struct urb
  43{
  44// (IN) device and pipe specify the endpoint queue
  45        struct usb_device *dev;         // pointer to associated USB device
  46        unsigned int pipe;              // endpoint information
  47
  48        unsigned int transfer_flags;    // ISO_ASAP, SHORT_NOT_OK, etc.
  49
  50// (IN) all urbs need completion routines
  51        void *context;                  // context for completion routine
  52        void (*complete)(struct urb *); // pointer to completion routine
  53
  54// (OUT) status after each completion
  55        int status;                     // returned status
  56
  57// (IN) buffer used for data transfers
  58        void *transfer_buffer;          // associated data buffer
  59        int transfer_buffer_length;     // data buffer length
  60        int number_of_packets;          // size of iso_frame_desc
  61
  62// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
  63        int actual_length;              // actual data buffer length
  64
  65// (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
  66        unsigned char* setup_packet;    // setup packet (control only)
  67
  68// Only for PERIODIC transfers (ISO, INTERRUPT)
  69    // (IN/OUT) start_frame is set unless ISO_ASAP isn't set
  70        int start_frame;                // start frame
  71        int interval;                   // polling interval
  72
  73    // ISO only: packets are only "best effort"; each can have errors
  74        int error_count;                // number of errors
  75        struct usb_iso_packet_descriptor iso_frame_desc[0];
  76};
  77
  78Your driver must create the "pipe" value using values from the appropriate
  79endpoint descriptor in an interface that it's claimed.
  80
  81
  821.3. How to get an URB?
  83
  84URBs are allocated with the following call
  85
  86        struct urb *usb_alloc_urb(int isoframes, int mem_flags)
  87
  88Return value is a pointer to the allocated URB, 0 if allocation failed.
  89The parameter isoframes specifies the number of isochronous transfer frames
  90you want to schedule. For CTRL/BULK/INT, use 0.  The mem_flags parameter
  91holds standard memory allocation flags, letting you control (among other
  92things) whether the underlying code may block or not.
  93
  94To free an URB, use
  95
  96        void usb_free_urb(struct urb *urb)
  97
  98You may free an urb that you've submitted, but which hasn't yet been
  99returned to you in a completion callback.  It will automatically be
 100deallocated when it is no longer in use.
 101
 102
 1031.4. What has to be filled in?
 104
 105Depending on the type of transaction, there are some inline functions 
 106defined in <linux/usb.h> to simplify the initialization, such as
 107fill_control_urb() and fill_bulk_urb().  In general, they need the usb
 108device pointer, the pipe (usual format from usb.h), the transfer buffer,
 109the desired transfer length, the completion  handler, and its context. 
 110Take a look at the some existing drivers to see how they're used.
 111
 112Flags:
 113For ISO there are two startup behaviors: Specified start_frame or ASAP.
 114For ASAP set URB_ISO_ASAP in transfer_flags.
 115
 116If short packets should NOT be tolerated, set URB_SHORT_NOT_OK in 
 117transfer_flags.
 118
 119
 1201.5. How to submit an URB?
 121
 122Just call
 123
 124        int usb_submit_urb(struct urb *urb, int mem_flags)
 125
 126flags parameter
L-B_ATOMIC, controls memory allocation,
 127such as whether the lower levels may block when memory is tight.
 128
 129It immediately returns, either with status 0 (request queued) or some
 130error code, usually caused by the following:
 131
 132- Out of memory (-ENOMEM)
 133- Unplugged device (-ENODEV)
 134- Stalled endpoint (-EPIPE)
 135- Too many queued ISO transfers (-EAGAIN)
 136- Too many requested ISO frames (-EFBIG)
 137- Invalid INT interval (-EINVAL)
 138- More than one packet for INT (-EINVAL)
 139
 140After submission, urb->status is -EINPROGRESS; howevef, you should nevef
 141look at that value except in your completion callback.
 142
 143For isochronous endpoints, your completion handlers should (re)submit
 144URBs to the same endpoint with the ISO_ASAP rame, using multi-buffering,
 145to get seamless ISO streaming.
 146
 147
 1481.6. How to cancel an already running URB?
 149
 150There are two ways to cancel an URB you've submitted but which hasn't
 151been returned to your driver yet.  For an asynchronous cancel, call
 152
 153        int usb_unlink_urb(struct urb *urb)
 154
 155It removes the urb from the internal list and frees all allocated
 156HW descriptors. The status is changed to reflect unlinking.  Note
 157that the URB will not normally have finished when usb_unlink_urb()
 158returns; you must still wait for the completion handler to be called.
 159
 160To cancel an URB synchronously, call
 161
 162        void usb_kill_urb(struct urb *urb)
 163
 164It does evefything usb_unlink_urb does, and in addition it waits
 165until after the URB has been returned and the completion handler
 166has finished.  It also marks the URB as temporarily unusable, so
 167that if the completion handler or anyone else tries to resubmit it
 168they will get a -EPERM error.  Thus you can be sure that when
 169usb_kill_urb() returns, the URB is totally idle.
 170
 171There is a lifetime issue to consider.  An URB may complete at any
 172time, and the completion handler may free the URB.  If this happens
 173while usb_unlink_urb or usb_kill_urb is running, it will cause a
 174memory-access violation.  The driver is responsible for avoiding this,
 175which often means some sort of lock will be needed to prevent the URB
 176from being deallocated while it is still in use.
 177
 178On the other hand, since usb_unlink_urb may end up calling the
 179completion handler, the handler must not take any lock that is held
 180when usb_unlink_urb is invoked.  The general solution to this problem
 181is to increment the URB's reference count while holding the lock, then
 182drop the lock and call usb_unlink_urb or usb_kill_urb, and then
 183decrement the URB's reference count.  You increment the reference
 184count by calling
 185
 186        struct urb *usb_get_urb(struct urb *urb)
 187
 188(ignore the return value; it is the same as the argument) and
 189decrement the reference count by calling usb_free_urb.  Of course,
 190none of this is necessary if there's no danger of the URB being freed
 191by the completion handler.
 192
 193
 1941.7. What about the completion handler?
 195
 196flaghandler is of the following type:
 197
 198        typedef void (*usb_complete_t)(struct urb *, struct pt_regs *)
 199
 200I.e., it gets the URB that caused the completion call, plus the
 201register values at the time of the corresponding interrupt (if any).
 202In the completion handler, you should have a look at urb->status to
 203detect any USB errors. Since the context parameter is included in the URB,
 204you can pass information to the completion handler. 
 20#L1772mentation2umentation/usb/URB.txt#L2L106"2id="L1us i="L200ome e URB ="li0" cline""> 182)>memorximif shdtualthe n the submitted, but which hasn't yet been2 180 13ass= name=ized188">mwer pletimitted, but which hasn't yet been2<="line" 04">ne" namename=1KBy i=ual for call en"> 201mwer mitted, but which hasn't yet been2< ="line" name="befclass="l4you cawaswait for the completion handler to be called.2  20
< 1112 1112 1ait fo11" class="line" name="L111"> 1112they wshd" na 7    Th11" class="line" name="L111"> 1112To cancel an URB synchronously, call2themanipul value using values from the appropriate2 1182 1192
 1.7. What about the completion handler?2
 1212
 13>then the1os="linane" name="L75">  75    ine" nametext parameter is included in the URB,

  86mwcr" nameviolahwerspe="line" ns)180  int ae" name=" 200<>whie count.  You increment the reference2
a href="2"Documentation/usb/URB.txL127"2id="L1bee" naws is new>  32none ofbigg="lina e U="L98""L44">  r the completion handler to be called.2
 1282
  89/a>Fe" nne" naval;                   // polling interval2ame="L69">  ame="updame=r the completion handler to be called.2 1922>then the1osL44">  44 158 92" class="line" name="L192"> 1922For i,"line" name="Ly completet/a>  int a17" clasr> =ame="Lyass= the completion handler to be called.2< > 158  4a"ner2">  ame="Ly76" cs the 1os= the (e.staf file isn't particularly current or2Ifs)182" classame="use="lin="L109"ile isn't particularly current or2< 136ineipingf the corresponding interrupt (if any).
  20
  33own   int start 3" claRBs t. As explplefo11" class="line" name="L111"> 1112 1112e timuk_urb().  In general, they need the usb2 20#L1772  ">  33own   int start,"L1kheget aoint descss="l 1086"> 13 evefvaence count.  You increment the reference2thsome exiname="L1izne" name="L184"> 184count by calling2 1492  20
 1.7. What about the completion handler?2 1522 1, liketer isoframes specifiIt dre data to class=n hand52" class="line" name="L152"> 1522 (1, 2, 4_fla) unitsrreUnitsedre s the number of isochronous transfer frames2  89/a>Fe" nne" naval;                   // polling interval2 1282 1ketearlifo >Take="truct  at theU84" clascompu in a31-28" class="line" name="L128"> 1282 198 172> 92" class="line" name="L192"> 1922the clas"L79">  t theU84still wiv  intthtext parameter is included in the URB,
 143For isochrono79tion handlet                  // polling interval2
L89"origiLXRa>4ftfill 91" cla         http://DocBooiolge.net/proj cls/lxr">LXRa3Take=" 91"         mailto:lxr@l a s.no">lxr@l a s.no="L1.
lxr.l a s.no kihroy ho name91" http://www.r> pill-l apro.no">R> pillas apro AS="L1,sprovis ns a su 171id= valass=an URB isscssr35"> me="L11995.