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``-ENOSPC`` This request would overcommit the usb bandwidth reserved 65 for periodic transfers (interrupt, isochronous). 66 67``-ESHUTDOWN`` The device or host controller has been disabled due to 68 some problem that could not be worked around. 69 70``-EPERM`` Submission failed because ``urb->reject`` was set. 71 72``-EHOSTUNREACH`` URB was rejected because the device is suspended. 73 74``-ENOEXEC`` A control URB doesn't contain a Setup packet. 75======================= ======================================================= 76 77Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` (for ISO) 78======================================================================================= 79 80USB device drivers may only test urb status values in completion handlers. 81This is because otherwise there would be a race between HCDs updating 82these values on one CPU, and device drivers testing them on another CPU. 83 84A transfer's actual_length may be positive even when an error has been 85reported. That's because transfers often involve several packets, so that 86one or more packets could finish before an error stops further endpoint I/O. 87 88For isochronous URBs, the urb status value is non-zero only if the URB is 89unlinked, the device is removed, the host controller is disabled, or the total 90transferred length is less than the requested length and the 91``URB_SHORT_NOT_OK`` flag is set. Completion handlers for isochronous URBs 92should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``, 93``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields 94may report more status codes. 95 96 97=============================== =============================================== 980 Transfer completed successfully 99 100``-ENOENT`` URB was synchronously unlinked by 101 :c:func:`usb_unlink_urb` 102 103``-EINPROGRESS`` URB still pending, no results yet 104 (That is, if drivers see this it's a bug.) 105 106``-EPROTO`` [#f1]_, [#f2]_ a) bitstuff error 107 b) no response packet received within the 108 prescribed bus turn-around time 109 c) unknown USB error 110 111``-EILSEQ`` [#f1]_, [#f2]_ a) CRC mismatch 112 b) no response packet received within the 113 prescribed bus turn-around time 114 c) unknown USB error 115 116 Note that often the controller hardware does 117 not distinguish among cases a), b), and c), so 118 a driver cannot tell whether there was a 119 protocol error, a failure to respond (often 120 caused by device disconnect), or some other 121 fault. 122 123``-ETIME`` [#f2]_ No response packet received within the 124 prescribed bus turn-around time. This error 125 may instead be reported as 126 ``-EPROTO`` or ``-EILSEQ``. 127 128``-ETIMEDOUT`` Synchronous USB message functions use this code 129 to indicate timeout expired before the transfer 130 completed, and no other error was reported 131 by HC. 132 133``-EPIPE`` [#f2]_ Endpoint stalled. For non-control endpoints, 134 reset this status with 135 :c:func:`usb_clear_halt`. 136 137``-ECOMM`` During an IN transfer, the host controller 138 received data from an endpoint faster than it 139 could be written to system memory 140 141``-ENOSR`` During an OUT transfer, the host controller 142 could not retrieve data from system memory fast 143 enough to keep up with the USB data rate 144 145``-EOVERFLOW`` [#f1]_ The amount of data returned by the endpoint was 146 greater than either the max packet size of the 147 endpoint or the remaining buffer size. 148 "Babble". 149 150``-EREMOTEIO`` The data read from the endpoint did not fill 151 the specified buffer, and ``URB_SHORT_NOT_OK`` 152 was set in ``urb->transfer_flags``. 153 154``-ENODEV`` Device was removed. Often preceded by a burst 155 of other errors, since the hub driver doesn't 156 detect device removal events immediately. 157 158``-EXDEV`` ISO transfer only partially completed 159 (only set in ``iso_frame_desc[n].status``, 160 not ``urb->status``) 161 162``-EINVAL`` ISO madness, if this happens: Log off and 163 go home 164 165``-ECONNRESET`` URB was asynchronously unlinked by 166 :c:func:`usb_unlink_urb` 167 168``-ESHUTDOWN`` The device or host controller has been 169 disabled due to some problem that could not 170 be worked around, such as a physical 171 disconnect. 172=============================== =============================================== 173 174 175.. [#f1] 176 177 Error codes like ``-EPROTO``, ``-EILSEQ`` and ``-EOVERFLOW`` normally 178 indicate hardware problems such as bad devices (including firmware) 179 or cables. 180 181.. [#f2] 182 183 This is also one of several codes that different kinds of host 184 controller use to indicate a transfer has failed because of device 185 disconnect. In the interval before the hub driver starts disconnect 186 processing, devices may receive such fault reports for every request. 187 188 189 190Error codes returned by usbcore-functions 191========================================= 192 193.. note:: expect also other submit and transfer status codes 194 195:c:func:`usb_register`: 196 197======================= =================================== 198``-EINVAL`` error during registering new driver 199======================= =================================== 200 201``usb_get_*/usb_set_*()``, 202:c:func:`usb_control_msg`, 203:c:func:`usb_bulk_msg()`: 204 205======================= ============================================== 206``-ETIMEDOUT`` Timeout expired before the transfer completed. 207======================= ============================================== 208