blob: a3e84bfac77649bc62a73a3575cb56f3e1645c5d [file] [log] [blame]
Mauro Carvalho Chehabe1c3e6e2017-04-05 10:23:15 -03001.. _usb-error-codes:
2
Mauro Carvalho Chehab360a7b52017-04-05 10:23:07 -03003USB 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======================= ==============================================