211 lines · plain
1.. _usb-error-codes:2 3USB Error codes4~~~~~~~~~~~~~~~5 6:Revised: 2004-Oct-217 8This is the documentation of (hopefully) all possible error codes (and9their interpretation) that can be returned from usbcore.10 11Some of them are returned by the Host Controller Drivers (HCDs), which12device drivers only see through usbcore. As a rule, all the HCDs should13behave the same except for transfer speed dependent behaviors and the14way certain faults are reported.15 16 17Error codes returned by :c:func:`usb_submit_urb`18================================================19 20Non-USB-specific:21 22 23=============== ===============================================240 URB submission went fine25 26``-ENOMEM`` no memory for allocation of internal structures27=============== ===============================================28 29USB-specific:30 31======================= =======================================================32``-EBUSY`` The URB is already active.33 34``-ENODEV`` specified USB-device or bus doesn't exist35 36``-ENOENT`` specified interface or endpoint does not exist or37 is not enabled38 39``-ENXIO`` host controller driver does not support queuing of40 this type of urb. (treat as a host controller bug.)41 42``-EINVAL`` a) Invalid transfer type specified (or not supported)43 b) Invalid or unsupported periodic transfer interval44 c) ISO: attempted to change transfer interval45 d) ISO: ``number_of_packets`` is < 046 e) various other cases47 48``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the49 frames the URB would be scheduled in have already50 expired.51 52``-EFBIG`` Host controller driver can't schedule that many ISO53 frames.54 55``-EPIPE`` The pipe type specified in the URB doesn't match the56 endpoint's actual type.57 58``-EMSGSIZE`` (a) endpoint maxpacket size is zero; it is not usable59 in the current interface altsetting.60 (b) ISO packet is larger than the endpoint maxpacket.61 (c) requested data transfer length is invalid: negative62 or too large for the host controller.63 64``-EBADR`` The wLength value in a control URB's setup packet does65 not match the URB's transfer_buffer_length.66 67``-ENOSPC`` This request would overcommit the usb bandwidth reserved68 for periodic transfers (interrupt, isochronous).69 70``-ESHUTDOWN`` The device or host controller has been disabled due to71 some problem that could not be worked around.72 73``-EPERM`` Submission failed because ``urb->reject`` was set.74 75``-EHOSTUNREACH`` URB was rejected because the device is suspended.76 77``-ENOEXEC`` A control URB doesn't contain a Setup packet.78======================= =======================================================79 80Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` (for ISO)81=======================================================================================82 83USB device drivers may only test urb status values in completion handlers.84This is because otherwise there would be a race between HCDs updating85these values on one CPU, and device drivers testing them on another CPU.86 87A transfer's actual_length may be positive even when an error has been88reported. That's because transfers often involve several packets, so that89one or more packets could finish before an error stops further endpoint I/O.90 91For isochronous URBs, the urb status value is non-zero only if the URB is92unlinked, the device is removed, the host controller is disabled, or the total93transferred length is less than the requested length and the94``URB_SHORT_NOT_OK`` flag is set. Completion handlers for isochronous URBs95should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``,96``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields97may report more status codes.98 99 100=============================== ===============================================1010 Transfer completed successfully102 103``-ENOENT`` URB was synchronously unlinked by104 :c:func:`usb_unlink_urb`105 106``-EINPROGRESS`` URB still pending, no results yet107 (That is, if drivers see this it's a bug.)108 109``-EPROTO`` [#f1]_, [#f2]_ a) bitstuff error110 b) no response packet received within the111 prescribed bus turn-around time112 c) unknown USB error113 114``-EILSEQ`` [#f1]_, [#f2]_ a) CRC mismatch115 b) no response packet received within the116 prescribed bus turn-around time117 c) unknown USB error118 119 Note that often the controller hardware does120 not distinguish among cases a), b), and c), so121 a driver cannot tell whether there was a122 protocol error, a failure to respond (often123 caused by device disconnect), or some other124 fault.125 126``-ETIME`` [#f2]_ No response packet received within the127 prescribed bus turn-around time. This error128 may instead be reported as129 ``-EPROTO`` or ``-EILSEQ``.130 131``-ETIMEDOUT`` Synchronous USB message functions use this code132 to indicate timeout expired before the transfer133 completed, and no other error was reported134 by HC.135 136``-EPIPE`` [#f2]_ Endpoint stalled. For non-control endpoints,137 reset this status with138 :c:func:`usb_clear_halt`.139 140``-ECOMM`` During an IN transfer, the host controller141 received data from an endpoint faster than it142 could be written to system memory143 144``-ENOSR`` During an OUT transfer, the host controller145 could not retrieve data from system memory fast146 enough to keep up with the USB data rate147 148``-EOVERFLOW`` [#f1]_ The amount of data returned by the endpoint was149 greater than either the max packet size of the150 endpoint or the remaining buffer size.151 "Babble".152 153``-EREMOTEIO`` The data read from the endpoint did not fill154 the specified buffer, and ``URB_SHORT_NOT_OK``155 was set in ``urb->transfer_flags``.156 157``-ENODEV`` Device was removed. Often preceded by a burst158 of other errors, since the hub driver doesn't159 detect device removal events immediately.160 161``-EXDEV`` ISO transfer only partially completed162 (only set in ``iso_frame_desc[n].status``,163 not ``urb->status``)164 165``-EINVAL`` ISO madness, if this happens: Log off and166 go home167 168``-ECONNRESET`` URB was asynchronously unlinked by169 :c:func:`usb_unlink_urb`170 171``-ESHUTDOWN`` The device or host controller has been172 disabled due to some problem that could not173 be worked around, such as a physical174 disconnect.175=============================== ===============================================176 177 178.. [#f1]179 180 Error codes like ``-EPROTO``, ``-EILSEQ`` and ``-EOVERFLOW`` normally181 indicate hardware problems such as bad devices (including firmware)182 or cables.183 184.. [#f2]185 186 This is also one of several codes that different kinds of host187 controller use to indicate a transfer has failed because of device188 disconnect. In the interval before the hub driver starts disconnect189 processing, devices may receive such fault reports for every request.190 191 192 193Error codes returned by usbcore-functions194=========================================195 196.. note:: expect also other submit and transfer status codes197 198:c:func:`usb_register`:199 200======================= ===================================201``-EINVAL`` error during registering new driver202======================= ===================================203 204``usb_get_*/usb_set_*()``,205:c:func:`usb_control_msg`,206:c:func:`usb_bulk_msg()`:207 208======================= ==============================================209``-ETIMEDOUT`` Timeout expired before the transfer completed.210======================= ==============================================211