0001 .. _usb-error-codes:
0002
0003 USB Error codes
0004 ~~~~~~~~~~~~~~~
0005
0006 :Revised: 2004-Oct-21
0007
0008 This is the documentation of (hopefully) all possible error codes (and
0009 their interpretation) that can be returned from usbcore.
0010
0011 Some of them are returned by the Host Controller Drivers (HCDs), which
0012 device drivers only see through usbcore. As a rule, all the HCDs should
0013 behave the same except for transfer speed dependent behaviors and the
0014 way certain faults are reported.
0015
0016
0017 Error codes returned by :c:func:`usb_submit_urb`
0018 ================================================
0019
0020 Non-USB-specific:
0021
0022
0023 =============== ===============================================
0024 0 URB submission went fine
0025
0026 ``-ENOMEM`` no memory for allocation of internal structures
0027 =============== ===============================================
0028
0029 USB-specific:
0030
0031 ======================= =======================================================
0032 ``-EBUSY`` The URB is already active.
0033
0034 ``-ENODEV`` specified USB-device or bus doesn't exist
0035
0036 ``-ENOENT`` specified interface or endpoint does not exist or
0037 is not enabled
0038
0039 ``-ENXIO`` host controller driver does not support queuing of
0040 this type of urb. (treat as a host controller bug.)
0041
0042 ``-EINVAL`` a) Invalid transfer type specified (or not supported)
0043 b) Invalid or unsupported periodic transfer interval
0044 c) ISO: attempted to change transfer interval
0045 d) ISO: ``number_of_packets`` is < 0
0046 e) various other cases
0047
0048 ``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the
0049 frames the URB would be scheduled in have already
0050 expired.
0051
0052 ``-EFBIG`` Host controller driver can't schedule that many ISO
0053 frames.
0054
0055 ``-EPIPE`` The pipe type specified in the URB doesn't match the
0056 endpoint's actual type.
0057
0058 ``-EMSGSIZE`` (a) endpoint maxpacket size is zero; it is not usable
0059 in the current interface altsetting.
0060 (b) ISO packet is larger than the endpoint maxpacket.
0061 (c) requested data transfer length is invalid: negative
0062 or too large for the host controller.
0063
0064 ``-EBADR`` The wLength value in a control URB's setup packet does
0065 not match the URB's transfer_buffer_length.
0066
0067 ``-ENOSPC`` This request would overcommit the usb bandwidth reserved
0068 for periodic transfers (interrupt, isochronous).
0069
0070 ``-ESHUTDOWN`` The device or host controller has been disabled due to
0071 some problem that could not be worked around.
0072
0073 ``-EPERM`` Submission failed because ``urb->reject`` was set.
0074
0075 ``-EHOSTUNREACH`` URB was rejected because the device is suspended.
0076
0077 ``-ENOEXEC`` A control URB doesn't contain a Setup packet.
0078 ======================= =======================================================
0079
0080 Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` (for ISO)
0081 =======================================================================================
0082
0083 USB device drivers may only test urb status values in completion handlers.
0084 This is because otherwise there would be a race between HCDs updating
0085 these values on one CPU, and device drivers testing them on another CPU.
0086
0087 A transfer's actual_length may be positive even when an error has been
0088 reported. That's because transfers often involve several packets, so that
0089 one or more packets could finish before an error stops further endpoint I/O.
0090
0091 For isochronous URBs, the urb status value is non-zero only if the URB is
0092 unlinked, the device is removed, the host controller is disabled, or the total
0093 transferred length is less than the requested length and the
0094 ``URB_SHORT_NOT_OK`` flag is set. Completion handlers for isochronous URBs
0095 should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``,
0096 ``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields
0097 may report more status codes.
0098
0099
0100 =============================== ===============================================
0101 0 Transfer completed successfully
0102
0103 ``-ENOENT`` URB was synchronously unlinked by
0104 :c:func:`usb_unlink_urb`
0105
0106 ``-EINPROGRESS`` URB still pending, no results yet
0107 (That is, if drivers see this it's a bug.)
0108
0109 ``-EPROTO`` [#f1]_, [#f2]_ a) bitstuff error
0110 b) no response packet received within the
0111 prescribed bus turn-around time
0112 c) unknown USB error
0113
0114 ``-EILSEQ`` [#f1]_, [#f2]_ a) CRC mismatch
0115 b) no response packet received within the
0116 prescribed bus turn-around time
0117 c) unknown USB error
0118
0119 Note that often the controller hardware does
0120 not distinguish among cases a), b), and c), so
0121 a driver cannot tell whether there was a
0122 protocol error, a failure to respond (often
0123 caused by device disconnect), or some other
0124 fault.
0125
0126 ``-ETIME`` [#f2]_ No response packet received within the
0127 prescribed bus turn-around time. This error
0128 may instead be reported as
0129 ``-EPROTO`` or ``-EILSEQ``.
0130
0131 ``-ETIMEDOUT`` Synchronous USB message functions use this code
0132 to indicate timeout expired before the transfer
0133 completed, and no other error was reported
0134 by HC.
0135
0136 ``-EPIPE`` [#f2]_ Endpoint stalled. For non-control endpoints,
0137 reset this status with
0138 :c:func:`usb_clear_halt`.
0139
0140 ``-ECOMM`` During an IN transfer, the host controller
0141 received data from an endpoint faster than it
0142 could be written to system memory
0143
0144 ``-ENOSR`` During an OUT transfer, the host controller
0145 could not retrieve data from system memory fast
0146 enough to keep up with the USB data rate
0147
0148 ``-EOVERFLOW`` [#f1]_ The amount of data returned by the endpoint was
0149 greater than either the max packet size of the
0150 endpoint or the remaining buffer size.
0151 "Babble".
0152
0153 ``-EREMOTEIO`` The data read from the endpoint did not fill
0154 the specified buffer, and ``URB_SHORT_NOT_OK``
0155 was set in ``urb->transfer_flags``.
0156
0157 ``-ENODEV`` Device was removed. Often preceded by a burst
0158 of other errors, since the hub driver doesn't
0159 detect device removal events immediately.
0160
0161 ``-EXDEV`` ISO transfer only partially completed
0162 (only set in ``iso_frame_desc[n].status``,
0163 not ``urb->status``)
0164
0165 ``-EINVAL`` ISO madness, if this happens: Log off and
0166 go home
0167
0168 ``-ECONNRESET`` URB was asynchronously unlinked by
0169 :c:func:`usb_unlink_urb`
0170
0171 ``-ESHUTDOWN`` The device or host controller has been
0172 disabled due to some problem that could not
0173 be worked around, such as a physical
0174 disconnect.
0175 =============================== ===============================================
0176
0177
0178 .. [#f1]
0179
0180 Error codes like ``-EPROTO``, ``-EILSEQ`` and ``-EOVERFLOW`` normally
0181 indicate hardware problems such as bad devices (including firmware)
0182 or cables.
0183
0184 .. [#f2]
0185
0186 This is also one of several codes that different kinds of host
0187 controller use to indicate a transfer has failed because of device
0188 disconnect. In the interval before the hub driver starts disconnect
0189 processing, devices may receive such fault reports for every request.
0190
0191
0192
0193 Error codes returned by usbcore-functions
0194 =========================================
0195
0196 .. note:: expect also other submit and transfer status codes
0197
0198 :c:func:`usb_register`:
0199
0200 ======================= ===================================
0201 ``-EINVAL`` error during registering new driver
0202 ======================= ===================================
0203
0204 ``usb_get_*/usb_set_*()``,
0205 :c:func:`usb_control_msg`,
0206 :c:func:`usb_bulk_msg()`:
0207
0208 ======================= ==============================================
0209 ``-ETIMEDOUT`` Timeout expired before the transfer completed.
0210 ======================= ==============================================
