1.. _usb-error-codes: 2 3USB Error codes 4~~~~~~~~~~~~~~~ 5 6:Revised: 2004-Oct-21 7 8This is the documentation of (hopefully) all possible error codes (and 9their interpretation) that can be returned from usbcore. 10 11Some of them are returned by the Host Controller Drivers (HCDs), which 12device drivers only see through usbcore. As a rule, all the HCDs should 13behave the same except for transfer speed dependent behaviors and the 14way 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 fine 25 26``-ENOMEM`` no memory for allocation of internal structures 27=============== =============================================== 28 29USB-specific: 30 31======================= ======================================================= 32``-EBUSY`` The URB is already active. 33 34``-ENODEV`` specified USB-device or bus doesn't exist 35 36``-ENOENT`` specified interface or endpoint does not exist or 37 is not enabled 38 39``-ENXIO`` host controller driver does not support queuing of 40 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 interval 44 c) ISO: attempted to change transfer interval 45 d) ISO: ``number_of_packets`` is < 0 46 e) various other cases 47 48``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the 49 frames the URB would be scheduled in have already 50 expired. 51 52``-EFBIG`` Host controller driver can't schedule that many ISO 53 frames. 54 55``-EPIPE`` The pipe type specified in the URB doesn't match the 56 endpoint's actual type. 57 58``-EMSGSIZE`` (a) endpoint maxpacket size is zero; it is not usable 59 in the current interface altsetting. 60 (b) ISO packet is larger than the endpoint maxpacket. 61 (c) requested data transfer length is invalid: negative 62 or too large for the host controller. 63 64``-EBADR`` The wLength value in a control URB's setup packet does 65 not match the URB's transfer_buffer_length. 66 67``-ENOSPC`` This request would overcommit the usb bandwidth reserved 68 for periodic transfers (interrupt, isochronous). 69 70``-ESHUTDOWN`` The device or host controller has been disabled due to 71 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 updating 85these 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 been 88reported. That's because transfers often involve several packets, so that 89one 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 is 92unlinked, the device is removed, the host controller is disabled, or the total 93transferred length is less than the requested length and the 94``URB_SHORT_NOT_OK`` flag is set. Completion handlers for isochronous URBs 95should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``, 96``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields 97may report more status codes. 98 99 100=============================== =============================================== 1010 Transfer completed successfully 102 103``-ENOENT`` URB was synchronously unlinked by 104 :c:func:`usb_unlink_urb` 105 106``-EINPROGRESS`` URB still pending, no results yet 107 (That is, if drivers see this it's a bug.) 108 109``-EPROTO`` [#f1]_, [#f2]_ a) bitstuff error 110 b) no response packet received within the 111 prescribed bus turn-around time 112 c) unknown USB error 113 114``-EILSEQ`` [#f1]_, [#f2]_ a) CRC mismatch 115 b) no response packet received within the 116 prescribed bus turn-around time 117 c) unknown USB error 118 119 Note that often the controller hardware does 120 not distinguish among cases a), b), and c), so 121 a driver cannot tell whether there was a 122 protocol error, a failure to respond (often 123 caused by device disconnect), or some other 124 fault. 125 126``-ETIME`` [#f2]_ No response packet received within the 127 prescribed bus turn-around time. This error 128 may instead be reported as 129 ``-EPROTO`` or ``-EILSEQ``. 130 131``-ETIMEDOUT`` Synchronous USB message functions use this code 132 to indicate timeout expired before the transfer 133 completed, and no other error was reported 134 by HC. 135 136``-EPIPE`` [#f2]_ Endpoint stalled. For non-control endpoints, 137 reset this status with 138 :c:func:`usb_clear_halt`. 139 140``-ECOMM`` During an IN transfer, the host controller 141 received data from an endpoint faster than it 142 could be written to system memory 143 144``-ENOSR`` During an OUT transfer, the host controller 145 could not retrieve data from system memory fast 146 enough to keep up with the USB data rate 147 148``-EOVERFLOW`` [#f1]_ The amount of data returned by the endpoint was 149 greater than either the max packet size of the 150 endpoint or the remaining buffer size. 151 "Babble". 152 153``-EREMOTEIO`` The data read from the endpoint did not fill 154 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 burst 158 of other errors, since the hub driver doesn't 159 detect device removal events immediately. 160 161``-EXDEV`` ISO transfer only partially completed 162 (only set in ``iso_frame_desc[n].status``, 163 not ``urb->status``) 164 165``-EINVAL`` ISO madness, if this happens: Log off and 166 go home 167 168``-ECONNRESET`` URB was asynchronously unlinked by 169 :c:func:`usb_unlink_urb` 170 171``-ESHUTDOWN`` The device or host controller has been 172 disabled due to some problem that could not 173 be worked around, such as a physical 174 disconnect. 175=============================== =============================================== 176 177 178.. [#f1] 179 180 Error codes like ``-EPROTO``, ``-EILSEQ`` and ``-EOVERFLOW`` normally 181 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 host 187 controller use to indicate a transfer has failed because of device 188 disconnect. In the interval before the hub driver starts disconnect 189 processing, devices may receive such fault reports for every request. 190 191 192 193Error codes returned by usbcore-functions 194========================================= 195 196.. note:: expect also other submit and transfer status codes 197 198:c:func:`usb_register`: 199 200======================= =================================== 201``-EINVAL`` error during registering new driver 202======================= =================================== 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