Documentation/driver-api/usb/error-codes.rst

   1 .. _usb-error-codes:
   2
   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 ``-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
  80 Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` (for ISO)
  81 =======================================================================================
  82
  83 USB device drivers may only test urb status values in completion handlers.
  84 This is because otherwise there would be a race between HCDs updating
  85 these values on one CPU, and device drivers testing them on another CPU.
  86
  87 A transfer's actual_length may be positive even when an error has been
  88 reported.  That's because transfers often involve several packets, so that
  89 one or more packets could finish before an error stops further endpoint I/O.
  90
  91 For isochronous URBs, the urb status value is non-zero only if the URB is
  92 unlinked, the device is removed, the host controller is disabled, or the total
  93 transferred length is less than the requested length and the
  94 ``URB_SHORT_NOT_OK`` flag is set.  Completion handlers for isochronous URBs
  95 should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``,
  96 ``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields
  97 may report more status codes.
  98
  99
 100 =============================== ===============================================
 101 0                               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
 193 Error 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 ======================= ==============================================