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 ``-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 ======================= ==============================================