291 lines · plain
1.. _usb-urb:2 3USB Request Block (URB)4~~~~~~~~~~~~~~~~~~~~~~~5 6:Revised: 2000-Dec-057:Again: 2002-Jul-068:Again: 2005-Sep-199:Again: 2017-Mar-2910 11 12.. note::13 14 The USB subsystem now has a substantial section at :ref:`usb-hostside-api`15 section, generated from the current source code.16 This particular documentation file isn't complete and may not be17 updated to the last version; don't rely on it except for a quick18 overview.19 20Basic concept or 'What is an URB?'21==================================22 23The basic idea of the new driver is message passing, the message itself is24called USB Request Block, or URB for short.25 26- An URB consists of all relevant information to execute any USB transaction27 and deliver the data and status back.28 29- Execution of an URB is inherently an asynchronous operation, i.e. the30 :c:func:`usb_submit_urb` call returns immediately after it has successfully31 queued the requested action.32 33- Transfers for one URB can be canceled with :c:func:`usb_unlink_urb`34 at any time.35 36- Each URB has a completion handler, which is called after the action37 has been successfully completed or canceled. The URB also contains a38 context-pointer for passing information to the completion handler.39 40- Each endpoint for a device logically supports a queue of requests.41 You can fill that queue, so that the USB hardware can still transfer42 data to an endpoint while your driver handles completion of another.43 This maximizes use of USB bandwidth, and supports seamless streaming44 of data to (or from) devices when using periodic transfer modes.45 46 47The URB structure48=================49 50Some of the fields in struct urb are::51 52 struct urb53 {54 // (IN) device and pipe specify the endpoint queue55 struct usb_device *dev; // pointer to associated USB device56 unsigned int pipe; // endpoint information57 58 unsigned int transfer_flags; // URB_ISO_ASAP, URB_SHORT_NOT_OK, etc.59 60 // (IN) all urbs need completion routines61 void *context; // context for completion routine62 usb_complete_t complete; // pointer to completion routine63 64 // (OUT) status after each completion65 int status; // returned status66 67 // (IN) buffer used for data transfers68 void *transfer_buffer; // associated data buffer69 u32 transfer_buffer_length; // data buffer length70 int number_of_packets; // size of iso_frame_desc71 72 // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used73 u32 actual_length; // actual data buffer length74 75 // (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)76 unsigned char *setup_packet; // setup packet (control only)77 78 // Only for PERIODIC transfers (ISO, INTERRUPT)79 // (IN/OUT) start_frame is set unless URB_ISO_ASAP isn't set80 int start_frame; // start frame81 int interval; // polling interval82 83 // ISO only: packets are only "best effort"; each can have errors84 int error_count; // number of errors85 struct usb_iso_packet_descriptor iso_frame_desc[0];86 };87 88Your driver must create the "pipe" value using values from the appropriate89endpoint descriptor in an interface that it's claimed.90 91 92How to get an URB?93==================94 95URBs are allocated by calling :c:func:`usb_alloc_urb`::96 97 struct urb *usb_alloc_urb(int isoframes, int mem_flags)98 99Return value is a pointer to the allocated URB, 0 if allocation failed.100The parameter isoframes specifies the number of isochronous transfer frames101you want to schedule. For CTRL/BULK/INT, use 0. The mem_flags parameter102holds standard memory allocation flags, letting you control (among other103things) whether the underlying code may block or not.104 105To free an URB, use :c:func:`usb_free_urb`::106 107 void usb_free_urb(struct urb *urb)108 109You may free an urb that you've submitted, but which hasn't yet been110returned to you in a completion callback. It will automatically be111deallocated when it is no longer in use.112 113 114What has to be filled in?115=========================116 117Depending on the type of transaction, there are some inline functions118defined in ``linux/usb.h`` to simplify the initialization, such as119:c:func:`usb_fill_control_urb`, :c:func:`usb_fill_bulk_urb` and120:c:func:`usb_fill_int_urb`. In general, they need the usb device pointer,121the pipe (usual format from usb.h), the transfer buffer, the desired transfer122length, the completion handler, and its context. Take a look at the some123existing drivers to see how they're used.124 125Flags:126 127- For ISO there are two startup behaviors: Specified start_frame or ASAP.128- For ASAP set ``URB_ISO_ASAP`` in transfer_flags.129 130If short packets should NOT be tolerated, set ``URB_SHORT_NOT_OK`` in131transfer_flags.132 133 134How to submit an URB?135=====================136 137Just call :c:func:`usb_submit_urb`::138 139 int usb_submit_urb(struct urb *urb, int mem_flags)140 141The ``mem_flags`` parameter, such as ``GFP_ATOMIC``, controls memory142allocation, such as whether the lower levels may block when memory is tight.143 144It immediately returns, either with status 0 (request queued) or some145error code, usually caused by the following:146 147- Out of memory (``-ENOMEM``)148- Unplugged device (``-ENODEV``)149- Stalled endpoint (``-EPIPE``)150- Too many queued ISO transfers (``-EAGAIN``)151- Too many requested ISO frames (``-EFBIG``)152- Invalid INT interval (``-EINVAL``)153- More than one packet for INT (``-EINVAL``)154 155After submission, ``urb->status`` is ``-EINPROGRESS``; however, you should156never look at that value except in your completion callback.157 158For isochronous endpoints, your completion handlers should (re)submit159URBs to the same endpoint with the ``URB_ISO_ASAP`` flag, using160multi-buffering, to get seamless ISO streaming.161 162 163How to cancel an already running URB?164=====================================165 166There are two ways to cancel an URB you've submitted but which hasn't167been returned to your driver yet. For an asynchronous cancel, call168:c:func:`usb_unlink_urb`::169 170 int usb_unlink_urb(struct urb *urb)171 172It removes the urb from the internal list and frees all allocated173HW descriptors. The status is changed to reflect unlinking. Note174that the URB will not normally have finished when :c:func:`usb_unlink_urb`175returns; you must still wait for the completion handler to be called.176 177To cancel an URB synchronously, call :c:func:`usb_kill_urb`::178 179 void usb_kill_urb(struct urb *urb)180 181It does everything :c:func:`usb_unlink_urb` does, and in addition it waits182until after the URB has been returned and the completion handler183has finished. It also marks the URB as temporarily unusable, so184that if the completion handler or anyone else tries to resubmit it185they will get a ``-EPERM`` error. Thus you can be sure that when186:c:func:`usb_kill_urb` returns, the URB is totally idle.187 188There is a lifetime issue to consider. An URB may complete at any189time, and the completion handler may free the URB. If this happens190while :c:func:`usb_unlink_urb` or :c:func:`usb_kill_urb` is running, it will191cause a memory-access violation. The driver is responsible for avoiding this,192which often means some sort of lock will be needed to prevent the URB193from being deallocated while it is still in use.194 195On the other hand, since usb_unlink_urb may end up calling the196completion handler, the handler must not take any lock that is held197when usb_unlink_urb is invoked. The general solution to this problem198is to increment the URB's reference count while holding the lock, then199drop the lock and call usb_unlink_urb or usb_kill_urb, and then200decrement the URB's reference count. You increment the reference201count by calling :c:func`usb_get_urb`::202 203 struct urb *usb_get_urb(struct urb *urb)204 205(ignore the return value; it is the same as the argument) and206decrement the reference count by calling :c:func:`usb_free_urb`. Of course,207none of this is necessary if there's no danger of the URB being freed208by the completion handler.209 210 211What about the completion handler?212==================================213 214The handler is of the following type::215 216 typedef void (*usb_complete_t)(struct urb *)217 218I.e., it gets the URB that caused the completion call. In the completion219handler, you should have a look at ``urb->status`` to detect any USB errors.220Since the context parameter is included in the URB, you can pass221information to the completion handler.222 223Note that even when an error (or unlink) is reported, data may have been224transferred. That's because USB transfers are packetized; it might take225sixteen packets to transfer your 1KByte buffer, and ten of them might226have transferred successfully before the completion was called.227 228 229.. warning::230 231 NEVER SLEEP IN A COMPLETION HANDLER.232 233 These are often called in atomic context.234 235In the current kernel, completion handlers run with local interrupts236disabled, but in the future this will be changed, so don't assume that237local IRQs are always disabled inside completion handlers.238 239How to do isochronous (ISO) transfers?240======================================241 242Besides the fields present on a bulk transfer, for ISO, you also243have to set ``urb->interval`` to say how often to make transfers; it's244often one per frame (which is once every microframe for highspeed devices).245The actual interval used will be a power of two that's no bigger than what246you specify. You can use the :c:func:`usb_fill_int_urb` macro to fill247most ISO transfer fields.248 249For ISO transfers you also have to fill a :c:type:`usb_iso_packet_descriptor`250structure, allocated at the end of the URB by :c:func:`usb_alloc_urb`, for251each packet you want to schedule.252 253The :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented254interval value that is less than or equal to the requested interval value. If255``URB_ISO_ASAP`` scheduling is used, ``urb->start_frame`` is also updated.256 257For each entry you have to specify the data offset for this frame (base is258transfer_buffer), and the length you want to write/expect to read.259After completion, actual_length contains the actual transferred length and260status contains the resulting status for the ISO transfer for this frame.261It is allowed to specify a varying length from frame to frame (e.g. for262audio synchronisation/adaptive transfer rates). You can also use the length2630 to omit one or more frames (striping).264 265For scheduling you can choose your own start frame or ``URB_ISO_ASAP``. As266explained earlier, if you always keep at least one URB queued and your267completion keeps (re)submitting a later URB, you'll get smooth ISO streaming268(if usb bandwidth utilization allows).269 270If you specify your own start frame, make sure it's several frames in advance271of the current frame. You might want this model if you're synchronizing272ISO data with some other event stream.273 274 275How to start interrupt (INT) transfers?276=======================================277 278Interrupt transfers, like isochronous transfers, are periodic, and happen279in intervals that are powers of two (1, 2, 4 etc) units. Units are frames280for full and low speed devices, and microframes for high speed ones.281You can use the :c:func:`usb_fill_int_urb` macro to fill INT transfer fields.282 283The :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented284interval value that is less than or equal to the requested interval value.285 286In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically287restarted when they complete. They end when the completion handler is288called, just like other URBs. If you want an interrupt URB to be restarted,289your completion handler must resubmit it.290s291