Mauro Carvalho Chehab | e1c3e6e | 2017-04-05 10:23:15 -0300 | [diff] [blame] | 1 | .. _usb-error-codes: |
| 2 | |
Mauro Carvalho Chehab | 360a7b5 | 2017-04-05 10:23:07 -0300 | [diff] [blame] | 3 | USB Error codes |
| 4 | ~~~~~~~~~~~~~~~ |
| 5 | |
| 6 | :Revised: 2004-Oct-21 |
| 7 | |
| 8 | This is the documentation of (hopefully) all possible error codes (and |
| 9 | their interpretation) that can be returned from usbcore. |
| 10 | |
| 11 | Some of them are returned by the Host Controller Drivers (HCDs), which |
| 12 | device drivers only see through usbcore. As a rule, all the HCDs should |
| 13 | behave the same except for transfer speed dependent behaviors and the |
| 14 | way certain faults are reported. |
| 15 | |
| 16 | |
| 17 | Error codes returned by :c:func:`usb_submit_urb` |
| 18 | ================================================ |
| 19 | |
| 20 | Non-USB-specific: |
| 21 | |
| 22 | |
| 23 | =============== =============================================== |
| 24 | 0 URB submission went fine |
| 25 | |
| 26 | ``-ENOMEM`` no memory for allocation of internal structures |
| 27 | =============== =============================================== |
| 28 | |
| 29 | USB-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 | |
| 77 | Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` (for ISO) |
| 78 | ======================================================================================= |
| 79 | |
| 80 | USB device drivers may only test urb status values in completion handlers. |
| 81 | This is because otherwise there would be a race between HCDs updating |
| 82 | these values on one CPU, and device drivers testing them on another CPU. |
| 83 | |
| 84 | A transfer's actual_length may be positive even when an error has been |
| 85 | reported. That's because transfers often involve several packets, so that |
| 86 | one or more packets could finish before an error stops further endpoint I/O. |
| 87 | |
| 88 | For isochronous URBs, the urb status value is non-zero only if the URB is |
| 89 | unlinked, the device is removed, the host controller is disabled, or the total |
| 90 | transferred length is less than the requested length and the |
| 91 | ``URB_SHORT_NOT_OK`` flag is set. Completion handlers for isochronous URBs |
| 92 | should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``, |
| 93 | ``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields |
| 94 | may report more status codes. |
| 95 | |
| 96 | |
| 97 | =============================== =============================================== |
| 98 | 0 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 | |
| 190 | Error 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 | ======================= ============================================== |