1e1c3e6e1SMauro Carvalho Chehab.. _usb-urb: 2e1c3e6e1SMauro Carvalho Chehab 3e463c063SMauro Carvalho ChehabUSB Request Block (URB) 4e463c063SMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~ 5e463c063SMauro Carvalho Chehab 6e463c063SMauro Carvalho Chehab:Revised: 2000-Dec-05 7e463c063SMauro Carvalho Chehab:Again: 2002-Jul-06 8e463c063SMauro Carvalho Chehab:Again: 2005-Sep-19 9e463c063SMauro Carvalho Chehab:Again: 2017-Mar-29 10e463c063SMauro Carvalho Chehab 11e463c063SMauro Carvalho Chehab 12e463c063SMauro Carvalho Chehab.. note:: 13e463c063SMauro Carvalho Chehab 14e463c063SMauro Carvalho Chehab The USB subsystem now has a substantial section at :ref:`usb-hostside-api` 15e463c063SMauro Carvalho Chehab section, generated from the current source code. 16e463c063SMauro Carvalho Chehab This particular documentation file isn't complete and may not be 17e463c063SMauro Carvalho Chehab updated to the last version; don't rely on it except for a quick 18e463c063SMauro Carvalho Chehab overview. 19e463c063SMauro Carvalho Chehab 20e463c063SMauro Carvalho ChehabBasic concept or 'What is an URB?' 21e463c063SMauro Carvalho Chehab================================== 22e463c063SMauro Carvalho Chehab 23e463c063SMauro Carvalho ChehabThe basic idea of the new driver is message passing, the message itself is 24e463c063SMauro Carvalho Chehabcalled USB Request Block, or URB for short. 25e463c063SMauro Carvalho Chehab 26e463c063SMauro Carvalho Chehab- An URB consists of all relevant information to execute any USB transaction 27e463c063SMauro Carvalho Chehab and deliver the data and status back. 28e463c063SMauro Carvalho Chehab 29e463c063SMauro Carvalho Chehab- Execution of an URB is inherently an asynchronous operation, i.e. the 30e463c063SMauro Carvalho Chehab :c:func:`usb_submit_urb` call returns immediately after it has successfully 31e463c063SMauro Carvalho Chehab queued the requested action. 32e463c063SMauro Carvalho Chehab 33e463c063SMauro Carvalho Chehab- Transfers for one URB can be canceled with :c:func:`usb_unlink_urb` 34e463c063SMauro Carvalho Chehab at any time. 35e463c063SMauro Carvalho Chehab 36e463c063SMauro Carvalho Chehab- Each URB has a completion handler, which is called after the action 37e463c063SMauro Carvalho Chehab has been successfully completed or canceled. The URB also contains a 38e463c063SMauro Carvalho Chehab context-pointer for passing information to the completion handler. 39e463c063SMauro Carvalho Chehab 40e463c063SMauro Carvalho Chehab- Each endpoint for a device logically supports a queue of requests. 41e463c063SMauro Carvalho Chehab You can fill that queue, so that the USB hardware can still transfer 42e463c063SMauro Carvalho Chehab data to an endpoint while your driver handles completion of another. 43e463c063SMauro Carvalho Chehab This maximizes use of USB bandwidth, and supports seamless streaming 44e463c063SMauro Carvalho Chehab of data to (or from) devices when using periodic transfer modes. 45e463c063SMauro Carvalho Chehab 46e463c063SMauro Carvalho Chehab 47e463c063SMauro Carvalho ChehabThe URB structure 48e463c063SMauro Carvalho Chehab================= 49e463c063SMauro Carvalho Chehab 50*9303c9d5SMauro Carvalho ChehabSome of the fields in struct urb are:: 51e463c063SMauro Carvalho Chehab 52e463c063SMauro Carvalho Chehab struct urb 53e463c063SMauro Carvalho Chehab { 54e463c063SMauro Carvalho Chehab // (IN) device and pipe specify the endpoint queue 55e463c063SMauro Carvalho Chehab struct usb_device *dev; // pointer to associated USB device 56e463c063SMauro Carvalho Chehab unsigned int pipe; // endpoint information 57e463c063SMauro Carvalho Chehab 58e463c063SMauro Carvalho Chehab unsigned int transfer_flags; // URB_ISO_ASAP, URB_SHORT_NOT_OK, etc. 59e463c063SMauro Carvalho Chehab 60e463c063SMauro Carvalho Chehab // (IN) all urbs need completion routines 61e463c063SMauro Carvalho Chehab void *context; // context for completion routine 62e463c063SMauro Carvalho Chehab usb_complete_t complete; // pointer to completion routine 63e463c063SMauro Carvalho Chehab 64e463c063SMauro Carvalho Chehab // (OUT) status after each completion 65e463c063SMauro Carvalho Chehab int status; // returned status 66e463c063SMauro Carvalho Chehab 67e463c063SMauro Carvalho Chehab // (IN) buffer used for data transfers 68e463c063SMauro Carvalho Chehab void *transfer_buffer; // associated data buffer 69e463c063SMauro Carvalho Chehab u32 transfer_buffer_length; // data buffer length 70e463c063SMauro Carvalho Chehab int number_of_packets; // size of iso_frame_desc 71e463c063SMauro Carvalho Chehab 72e463c063SMauro Carvalho Chehab // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used 73e463c063SMauro Carvalho Chehab u32 actual_length; // actual data buffer length 74e463c063SMauro Carvalho Chehab 75e463c063SMauro Carvalho Chehab // (IN) setup stage for CTRL (pass a struct usb_ctrlrequest) 76e463c063SMauro Carvalho Chehab unsigned char *setup_packet; // setup packet (control only) 77e463c063SMauro Carvalho Chehab 78e463c063SMauro Carvalho Chehab // Only for PERIODIC transfers (ISO, INTERRUPT) 79e463c063SMauro Carvalho Chehab // (IN/OUT) start_frame is set unless URB_ISO_ASAP isn't set 80e463c063SMauro Carvalho Chehab int start_frame; // start frame 81e463c063SMauro Carvalho Chehab int interval; // polling interval 82e463c063SMauro Carvalho Chehab 83e463c063SMauro Carvalho Chehab // ISO only: packets are only "best effort"; each can have errors 84e463c063SMauro Carvalho Chehab int error_count; // number of errors 85e463c063SMauro Carvalho Chehab struct usb_iso_packet_descriptor iso_frame_desc[0]; 86e463c063SMauro Carvalho Chehab }; 87e463c063SMauro Carvalho Chehab 88e463c063SMauro Carvalho ChehabYour driver must create the "pipe" value using values from the appropriate 89e463c063SMauro Carvalho Chehabendpoint descriptor in an interface that it's claimed. 90e463c063SMauro Carvalho Chehab 91e463c063SMauro Carvalho Chehab 92e463c063SMauro Carvalho ChehabHow to get an URB? 93e463c063SMauro Carvalho Chehab================== 94e463c063SMauro Carvalho Chehab 95e463c063SMauro Carvalho ChehabURBs are allocated by calling :c:func:`usb_alloc_urb`:: 96e463c063SMauro Carvalho Chehab 97e463c063SMauro Carvalho Chehab struct urb *usb_alloc_urb(int isoframes, int mem_flags) 98e463c063SMauro Carvalho Chehab 99e463c063SMauro Carvalho ChehabReturn value is a pointer to the allocated URB, 0 if allocation failed. 100e463c063SMauro Carvalho ChehabThe parameter isoframes specifies the number of isochronous transfer frames 101e463c063SMauro Carvalho Chehabyou want to schedule. For CTRL/BULK/INT, use 0. The mem_flags parameter 102e463c063SMauro Carvalho Chehabholds standard memory allocation flags, letting you control (among other 103e463c063SMauro Carvalho Chehabthings) whether the underlying code may block or not. 104e463c063SMauro Carvalho Chehab 105e463c063SMauro Carvalho ChehabTo free an URB, use :c:func:`usb_free_urb`:: 106e463c063SMauro Carvalho Chehab 107e463c063SMauro Carvalho Chehab void usb_free_urb(struct urb *urb) 108e463c063SMauro Carvalho Chehab 109e463c063SMauro Carvalho ChehabYou may free an urb that you've submitted, but which hasn't yet been 110e463c063SMauro Carvalho Chehabreturned to you in a completion callback. It will automatically be 111e463c063SMauro Carvalho Chehabdeallocated when it is no longer in use. 112e463c063SMauro Carvalho Chehab 113e463c063SMauro Carvalho Chehab 114e463c063SMauro Carvalho ChehabWhat has to be filled in? 115e463c063SMauro Carvalho Chehab========================= 116e463c063SMauro Carvalho Chehab 117e463c063SMauro Carvalho ChehabDepending on the type of transaction, there are some inline functions 118e463c063SMauro Carvalho Chehabdefined in ``linux/usb.h`` to simplify the initialization, such as 119e463c063SMauro Carvalho Chehab:c:func:`usb_fill_control_urb`, :c:func:`usb_fill_bulk_urb` and 120e463c063SMauro Carvalho Chehab:c:func:`usb_fill_int_urb`. In general, they need the usb device pointer, 121e463c063SMauro Carvalho Chehabthe pipe (usual format from usb.h), the transfer buffer, the desired transfer 122e463c063SMauro Carvalho Chehablength, the completion handler, and its context. Take a look at the some 123e463c063SMauro Carvalho Chehabexisting drivers to see how they're used. 124e463c063SMauro Carvalho Chehab 125e463c063SMauro Carvalho ChehabFlags: 126e463c063SMauro Carvalho Chehab 127e463c063SMauro Carvalho Chehab- For ISO there are two startup behaviors: Specified start_frame or ASAP. 128e463c063SMauro Carvalho Chehab- For ASAP set ``URB_ISO_ASAP`` in transfer_flags. 129e463c063SMauro Carvalho Chehab 130e463c063SMauro Carvalho ChehabIf short packets should NOT be tolerated, set ``URB_SHORT_NOT_OK`` in 131e463c063SMauro Carvalho Chehabtransfer_flags. 132e463c063SMauro Carvalho Chehab 133e463c063SMauro Carvalho Chehab 134e463c063SMauro Carvalho ChehabHow to submit an URB? 135e463c063SMauro Carvalho Chehab===================== 136e463c063SMauro Carvalho Chehab 137e463c063SMauro Carvalho ChehabJust call :c:func:`usb_submit_urb`:: 138e463c063SMauro Carvalho Chehab 139e463c063SMauro Carvalho Chehab int usb_submit_urb(struct urb *urb, int mem_flags) 140e463c063SMauro Carvalho Chehab 141e463c063SMauro Carvalho ChehabThe ``mem_flags`` parameter, such as ``GFP_ATOMIC``, controls memory 142e463c063SMauro Carvalho Chehaballocation, such as whether the lower levels may block when memory is tight. 143e463c063SMauro Carvalho Chehab 144e463c063SMauro Carvalho ChehabIt immediately returns, either with status 0 (request queued) or some 145e463c063SMauro Carvalho Chehaberror code, usually caused by the following: 146e463c063SMauro Carvalho Chehab 147e463c063SMauro Carvalho Chehab- Out of memory (``-ENOMEM``) 148e463c063SMauro Carvalho Chehab- Unplugged device (``-ENODEV``) 149e463c063SMauro Carvalho Chehab- Stalled endpoint (``-EPIPE``) 150e463c063SMauro Carvalho Chehab- Too many queued ISO transfers (``-EAGAIN``) 151e463c063SMauro Carvalho Chehab- Too many requested ISO frames (``-EFBIG``) 152e463c063SMauro Carvalho Chehab- Invalid INT interval (``-EINVAL``) 153e463c063SMauro Carvalho Chehab- More than one packet for INT (``-EINVAL``) 154e463c063SMauro Carvalho Chehab 155e463c063SMauro Carvalho ChehabAfter submission, ``urb->status`` is ``-EINPROGRESS``; however, you should 156e463c063SMauro Carvalho Chehabnever look at that value except in your completion callback. 157e463c063SMauro Carvalho Chehab 158e463c063SMauro Carvalho ChehabFor isochronous endpoints, your completion handlers should (re)submit 159e463c063SMauro Carvalho ChehabURBs to the same endpoint with the ``URB_ISO_ASAP`` flag, using 160e463c063SMauro Carvalho Chehabmulti-buffering, to get seamless ISO streaming. 161e463c063SMauro Carvalho Chehab 162e463c063SMauro Carvalho Chehab 163e463c063SMauro Carvalho ChehabHow to cancel an already running URB? 164e463c063SMauro Carvalho Chehab===================================== 165e463c063SMauro Carvalho Chehab 166e463c063SMauro Carvalho ChehabThere are two ways to cancel an URB you've submitted but which hasn't 167e463c063SMauro Carvalho Chehabbeen returned to your driver yet. For an asynchronous cancel, call 168e463c063SMauro Carvalho Chehab:c:func:`usb_unlink_urb`:: 169e463c063SMauro Carvalho Chehab 170e463c063SMauro Carvalho Chehab int usb_unlink_urb(struct urb *urb) 171e463c063SMauro Carvalho Chehab 172e463c063SMauro Carvalho ChehabIt removes the urb from the internal list and frees all allocated 173e463c063SMauro Carvalho ChehabHW descriptors. The status is changed to reflect unlinking. Note 174e463c063SMauro Carvalho Chehabthat the URB will not normally have finished when :c:func:`usb_unlink_urb` 175e463c063SMauro Carvalho Chehabreturns; you must still wait for the completion handler to be called. 176e463c063SMauro Carvalho Chehab 177e463c063SMauro Carvalho ChehabTo cancel an URB synchronously, call :c:func:`usb_kill_urb`:: 178e463c063SMauro Carvalho Chehab 179e463c063SMauro Carvalho Chehab void usb_kill_urb(struct urb *urb) 180e463c063SMauro Carvalho Chehab 181e463c063SMauro Carvalho ChehabIt does everything :c:func:`usb_unlink_urb` does, and in addition it waits 182e463c063SMauro Carvalho Chehabuntil after the URB has been returned and the completion handler 183e463c063SMauro Carvalho Chehabhas finished. It also marks the URB as temporarily unusable, so 184e463c063SMauro Carvalho Chehabthat if the completion handler or anyone else tries to resubmit it 185e463c063SMauro Carvalho Chehabthey will get a ``-EPERM`` error. Thus you can be sure that when 186e463c063SMauro Carvalho Chehab:c:func:`usb_kill_urb` returns, the URB is totally idle. 187e463c063SMauro Carvalho Chehab 188e463c063SMauro Carvalho ChehabThere is a lifetime issue to consider. An URB may complete at any 189e463c063SMauro Carvalho Chehabtime, and the completion handler may free the URB. If this happens 190e463c063SMauro Carvalho Chehabwhile :c:func:`usb_unlink_urb` or :c:func:`usb_kill_urb` is running, it will 191e463c063SMauro Carvalho Chehabcause a memory-access violation. The driver is responsible for avoiding this, 192e463c063SMauro Carvalho Chehabwhich often means some sort of lock will be needed to prevent the URB 193e463c063SMauro Carvalho Chehabfrom being deallocated while it is still in use. 194e463c063SMauro Carvalho Chehab 195e463c063SMauro Carvalho ChehabOn the other hand, since usb_unlink_urb may end up calling the 196e463c063SMauro Carvalho Chehabcompletion handler, the handler must not take any lock that is held 197e463c063SMauro Carvalho Chehabwhen usb_unlink_urb is invoked. The general solution to this problem 198e463c063SMauro Carvalho Chehabis to increment the URB's reference count while holding the lock, then 199e463c063SMauro Carvalho Chehabdrop the lock and call usb_unlink_urb or usb_kill_urb, and then 200e463c063SMauro Carvalho Chehabdecrement the URB's reference count. You increment the reference 201e463c063SMauro Carvalho Chehabcount by calling :c:func`usb_get_urb`:: 202e463c063SMauro Carvalho Chehab 203e463c063SMauro Carvalho Chehab struct urb *usb_get_urb(struct urb *urb) 204e463c063SMauro Carvalho Chehab 205e463c063SMauro Carvalho Chehab(ignore the return value; it is the same as the argument) and 206e463c063SMauro Carvalho Chehabdecrement the reference count by calling :c:func:`usb_free_urb`. Of course, 207e463c063SMauro Carvalho Chehabnone of this is necessary if there's no danger of the URB being freed 208e463c063SMauro Carvalho Chehabby the completion handler. 209e463c063SMauro Carvalho Chehab 210e463c063SMauro Carvalho Chehab 211e463c063SMauro Carvalho ChehabWhat about the completion handler? 212e463c063SMauro Carvalho Chehab================================== 213e463c063SMauro Carvalho Chehab 214e463c063SMauro Carvalho ChehabThe handler is of the following type:: 215e463c063SMauro Carvalho Chehab 216e463c063SMauro Carvalho Chehab typedef void (*usb_complete_t)(struct urb *) 217e463c063SMauro Carvalho Chehab 218e463c063SMauro Carvalho ChehabI.e., it gets the URB that caused the completion call. In the completion 219e463c063SMauro Carvalho Chehabhandler, you should have a look at ``urb->status`` to detect any USB errors. 220e463c063SMauro Carvalho ChehabSince the context parameter is included in the URB, you can pass 221e463c063SMauro Carvalho Chehabinformation to the completion handler. 222e463c063SMauro Carvalho Chehab 223e463c063SMauro Carvalho ChehabNote that even when an error (or unlink) is reported, data may have been 224e463c063SMauro Carvalho Chehabtransferred. That's because USB transfers are packetized; it might take 225e463c063SMauro Carvalho Chehabsixteen packets to transfer your 1KByte buffer, and ten of them might 226e463c063SMauro Carvalho Chehabhave transferred successfully before the completion was called. 227e463c063SMauro Carvalho Chehab 228e463c063SMauro Carvalho Chehab 229e463c063SMauro Carvalho Chehab.. warning:: 230e463c063SMauro Carvalho Chehab 231e463c063SMauro Carvalho Chehab NEVER SLEEP IN A COMPLETION HANDLER. 232e463c063SMauro Carvalho Chehab 233e463c063SMauro Carvalho Chehab These are often called in atomic context. 234e463c063SMauro Carvalho Chehab 235e463c063SMauro Carvalho ChehabIn the current kernel, completion handlers run with local interrupts 236e463c063SMauro Carvalho Chehabdisabled, but in the future this will be changed, so don't assume that 237e463c063SMauro Carvalho Chehablocal IRQs are always disabled inside completion handlers. 238e463c063SMauro Carvalho Chehab 239e463c063SMauro Carvalho ChehabHow to do isochronous (ISO) transfers? 240e463c063SMauro Carvalho Chehab====================================== 241e463c063SMauro Carvalho Chehab 242e463c063SMauro Carvalho ChehabBesides the fields present on a bulk transfer, for ISO, you also 243ec326c9dSRandy Dunlaphave to set ``urb->interval`` to say how often to make transfers; it's 244e463c063SMauro Carvalho Chehaboften one per frame (which is once every microframe for highspeed devices). 245e463c063SMauro Carvalho ChehabThe actual interval used will be a power of two that's no bigger than what 246e463c063SMauro Carvalho Chehabyou specify. You can use the :c:func:`usb_fill_int_urb` macro to fill 247e463c063SMauro Carvalho Chehabmost ISO transfer fields. 248e463c063SMauro Carvalho Chehab 249e463c063SMauro Carvalho ChehabFor ISO transfers you also have to fill a :c:type:`usb_iso_packet_descriptor` 250e463c063SMauro Carvalho Chehabstructure, allocated at the end of the URB by :c:func:`usb_alloc_urb`, for 251e463c063SMauro Carvalho Chehabeach packet you want to schedule. 252e463c063SMauro Carvalho Chehab 253e463c063SMauro Carvalho ChehabThe :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented 254e463c063SMauro Carvalho Chehabinterval value that is less than or equal to the requested interval value. If 255e463c063SMauro Carvalho Chehab``URB_ISO_ASAP`` scheduling is used, ``urb->start_frame`` is also updated. 256e463c063SMauro Carvalho Chehab 257e463c063SMauro Carvalho ChehabFor each entry you have to specify the data offset for this frame (base is 258e463c063SMauro Carvalho Chehabtransfer_buffer), and the length you want to write/expect to read. 259e463c063SMauro Carvalho ChehabAfter completion, actual_length contains the actual transferred length and 260e463c063SMauro Carvalho Chehabstatus contains the resulting status for the ISO transfer for this frame. 261e463c063SMauro Carvalho ChehabIt is allowed to specify a varying length from frame to frame (e.g. for 262e463c063SMauro Carvalho Chehabaudio synchronisation/adaptive transfer rates). You can also use the length 263e463c063SMauro Carvalho Chehab0 to omit one or more frames (striping). 264e463c063SMauro Carvalho Chehab 265e463c063SMauro Carvalho ChehabFor scheduling you can choose your own start frame or ``URB_ISO_ASAP``. As 266e463c063SMauro Carvalho Chehabexplained earlier, if you always keep at least one URB queued and your 267e463c063SMauro Carvalho Chehabcompletion keeps (re)submitting a later URB, you'll get smooth ISO streaming 268e463c063SMauro Carvalho Chehab(if usb bandwidth utilization allows). 269e463c063SMauro Carvalho Chehab 270e463c063SMauro Carvalho ChehabIf you specify your own start frame, make sure it's several frames in advance 271e463c063SMauro Carvalho Chehabof the current frame. You might want this model if you're synchronizing 272e463c063SMauro Carvalho ChehabISO data with some other event stream. 273e463c063SMauro Carvalho Chehab 274e463c063SMauro Carvalho Chehab 275e463c063SMauro Carvalho ChehabHow to start interrupt (INT) transfers? 276e463c063SMauro Carvalho Chehab======================================= 277e463c063SMauro Carvalho Chehab 278e463c063SMauro Carvalho ChehabInterrupt transfers, like isochronous transfers, are periodic, and happen 279e463c063SMauro Carvalho Chehabin intervals that are powers of two (1, 2, 4 etc) units. Units are frames 280e463c063SMauro Carvalho Chehabfor full and low speed devices, and microframes for high speed ones. 281e463c063SMauro Carvalho ChehabYou can use the :c:func:`usb_fill_int_urb` macro to fill INT transfer fields. 282e463c063SMauro Carvalho Chehab 283e463c063SMauro Carvalho ChehabThe :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented 284e463c063SMauro Carvalho Chehabinterval value that is less than or equal to the requested interval value. 285e463c063SMauro Carvalho Chehab 286e463c063SMauro Carvalho ChehabIn Linux 2.6, unlike earlier versions, interrupt URBs are not automagically 287e463c063SMauro Carvalho Chehabrestarted when they complete. They end when the completion handler is 288e463c063SMauro Carvalho Chehabcalled, just like other URBs. If you want an interrupt URB to be restarted, 289e463c063SMauro Carvalho Chehabyour completion handler must resubmit it. 290e463c063SMauro Carvalho Chehabs 291