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