1 .. _usb-error-codes: 1 .. _usb-error-codes:
2 2
3 USB Error codes 3 USB Error codes
4 ~~~~~~~~~~~~~~~ 4 ~~~~~~~~~~~~~~~
5 5
6 :Revised: 2004-Oct-21 6 :Revised: 2004-Oct-21
7 7
8 This is the documentation of (hopefully) all p 8 This is the documentation of (hopefully) all possible error codes (and
9 their interpretation) that can be returned fro 9 their interpretation) that can be returned from usbcore.
10 10
11 Some of them are returned by the Host Controll 11 Some of them are returned by the Host Controller Drivers (HCDs), which
12 device drivers only see through usbcore. As a 12 device drivers only see through usbcore. As a rule, all the HCDs should
13 behave the same except for transfer speed depe 13 behave the same except for transfer speed dependent behaviors and the
14 way certain faults are reported. 14 way certain faults are reported.
15 15
16 16
17 Error codes returned by :c:func:`usb_submit_ur 17 Error codes returned by :c:func:`usb_submit_urb`
18 ============================================== 18 ================================================
19 19
20 Non-USB-specific: 20 Non-USB-specific:
21 21
22 22
23 =============== ============================== 23 =============== ===============================================
24 0 URB submission went fine 24 0 URB submission went fine
25 25
26 ``-ENOMEM`` no memory for allocation of in 26 ``-ENOMEM`` no memory for allocation of internal structures
27 =============== ============================== 27 =============== ===============================================
28 28
29 USB-specific: 29 USB-specific:
30 30
31 ======================= ====================== 31 ======================= =======================================================
32 ``-EBUSY`` The URB is already act 32 ``-EBUSY`` The URB is already active.
33 33
34 ``-ENODEV`` specified USB-device o 34 ``-ENODEV`` specified USB-device or bus doesn't exist
35 35
36 ``-ENOENT`` specified interface or 36 ``-ENOENT`` specified interface or endpoint does not exist or
37 is not enabled 37 is not enabled
38 38
39 ``-ENXIO`` host controller driver 39 ``-ENXIO`` host controller driver does not support queuing of
40 this type of urb. (tr 40 this type of urb. (treat as a host controller bug.)
41 41
42 ``-EINVAL`` a) Invalid transfer ty 42 ``-EINVAL`` a) Invalid transfer type specified (or not supported)
43 b) Invalid or unsuppor 43 b) Invalid or unsupported periodic transfer interval
44 c) ISO: attempted to c 44 c) ISO: attempted to change transfer interval
45 d) ISO: ``number_of_pa 45 d) ISO: ``number_of_packets`` is < 0
46 e) various other cases 46 e) various other cases
47 47
48 ``-EXDEV`` ISO: ``URB_ISO_ASAP`` 48 ``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the
49 frames the URB would b 49 frames the URB would be scheduled in have already
50 expired. 50 expired.
51 51
52 ``-EFBIG`` Host controller driver 52 ``-EFBIG`` Host controller driver can't schedule that many ISO
53 frames. 53 frames.
54 54
55 ``-EPIPE`` The pipe type specifie 55 ``-EPIPE`` The pipe type specified in the URB doesn't match the
56 endpoint's actual type 56 endpoint's actual type.
57 57
58 ``-EMSGSIZE`` (a) endpoint maxpacket 58 ``-EMSGSIZE`` (a) endpoint maxpacket size is zero; it is not usable
59 in the current int 59 in the current interface altsetting.
60 (b) ISO packet is larg 60 (b) ISO packet is larger than the endpoint maxpacket.
61 (c) requested data tra 61 (c) requested data transfer length is invalid: negative
62 or too large for t 62 or too large for the host controller.
63 63
64 ``-EBADR`` The wLength value in a 64 ``-EBADR`` The wLength value in a control URB's setup packet does
65 not match the URB's tr 65 not match the URB's transfer_buffer_length.
66 66
67 ``-ENOSPC`` This request would ove 67 ``-ENOSPC`` This request would overcommit the usb bandwidth reserved
68 for periodic transfers 68 for periodic transfers (interrupt, isochronous).
69 69
70 ``-ESHUTDOWN`` The device or host con 70 ``-ESHUTDOWN`` The device or host controller has been disabled due to
71 some problem that coul 71 some problem that could not be worked around.
72 72
73 ``-EPERM`` Submission failed beca 73 ``-EPERM`` Submission failed because ``urb->reject`` was set.
74 74
75 ``-EHOSTUNREACH`` URB was rejected becau 75 ``-EHOSTUNREACH`` URB was rejected because the device is suspended.
76 76
77 ``-ENOEXEC`` A control URB doesn't 77 ``-ENOEXEC`` A control URB doesn't contain a Setup packet.
78 ======================= ====================== 78 ======================= =======================================================
79 79
80 Error codes returned by ``in urb->status`` or 80 Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` (for ISO)
81 ============================================== 81 =======================================================================================
82 82
83 USB device drivers may only test urb status va 83 USB device drivers may only test urb status values in completion handlers.
84 This is because otherwise there would be a rac 84 This is because otherwise there would be a race between HCDs updating
85 these values on one CPU, and device drivers te 85 these values on one CPU, and device drivers testing them on another CPU.
86 86
87 A transfer's actual_length may be positive eve 87 A transfer's actual_length may be positive even when an error has been
88 reported. That's because transfers often invo 88 reported. That's because transfers often involve several packets, so that
89 one or more packets could finish before an err 89 one or more packets could finish before an error stops further endpoint I/O.
90 90
91 For isochronous URBs, the urb status value is 91 For isochronous URBs, the urb status value is non-zero only if the URB is
92 unlinked, the device is removed, the host cont 92 unlinked, the device is removed, the host controller is disabled, or the total
93 transferred length is less than the requested 93 transferred length is less than the requested length and the
94 ``URB_SHORT_NOT_OK`` flag is set. Completion 94 ``URB_SHORT_NOT_OK`` flag is set. Completion handlers for isochronous URBs
95 should only see ``urb->status`` set to zero, ` 95 should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``,
96 ``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual 96 ``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields
97 may report more status codes. 97 may report more status codes.
98 98
99 99
100 =============================== ============== 100 =============================== ===============================================
101 0 Transfer compl 101 0 Transfer completed successfully
102 102
103 ``-ENOENT`` URB was synchr 103 ``-ENOENT`` URB was synchronously unlinked by
104 :c:func:`usb_u 104 :c:func:`usb_unlink_urb`
105 105
106 ``-EINPROGRESS`` URB still pend 106 ``-EINPROGRESS`` URB still pending, no results yet
107 (That is, if d 107 (That is, if drivers see this it's a bug.)
108 108
109 ``-EPROTO`` [#f1]_, [#f2]_ a) bitstuff er 109 ``-EPROTO`` [#f1]_, [#f2]_ a) bitstuff error
110 b) no response 110 b) no response packet received within the
111 prescribed 111 prescribed bus turn-around time
112 c) unknown USB 112 c) unknown USB error
113 113
114 ``-EILSEQ`` [#f1]_, [#f2]_ a) CRC mismatc 114 ``-EILSEQ`` [#f1]_, [#f2]_ a) CRC mismatch
115 b) no response 115 b) no response packet received within the
116 prescribed 116 prescribed bus turn-around time
117 c) unknown USB 117 c) unknown USB error
118 118
119 Note that ofte 119 Note that often the controller hardware does
120 not distinguis 120 not distinguish among cases a), b), and c), so
121 a driver canno 121 a driver cannot tell whether there was a
122 protocol error 122 protocol error, a failure to respond (often
123 caused by devi 123 caused by device disconnect), or some other
124 fault. 124 fault.
125 125
126 ``-ETIME`` [#f2]_ No response pa 126 ``-ETIME`` [#f2]_ No response packet received within the
127 prescribed bus 127 prescribed bus turn-around time. This error
128 may instead be 128 may instead be reported as
129 ``-EPROTO`` or 129 ``-EPROTO`` or ``-EILSEQ``.
130 130
131 ``-ETIMEDOUT`` Synchronous US 131 ``-ETIMEDOUT`` Synchronous USB message functions use this code
132 to indicate ti 132 to indicate timeout expired before the transfer
133 completed, and 133 completed, and no other error was reported
134 by HC. 134 by HC.
135 135
136 ``-EPIPE`` [#f2]_ Endpoint stall 136 ``-EPIPE`` [#f2]_ Endpoint stalled. For non-control endpoints,
137 reset this sta 137 reset this status with
138 :c:func:`usb_c 138 :c:func:`usb_clear_halt`.
139 139
140 ``-ECOMM`` During an IN t 140 ``-ECOMM`` During an IN transfer, the host controller
141 received data 141 received data from an endpoint faster than it
142 could be writt 142 could be written to system memory
143 143
144 ``-ENOSR`` During an OUT 144 ``-ENOSR`` During an OUT transfer, the host controller
145 could not retr 145 could not retrieve data from system memory fast
146 enough to keep 146 enough to keep up with the USB data rate
147 147
148 ``-EOVERFLOW`` [#f1]_ The amount of 148 ``-EOVERFLOW`` [#f1]_ The amount of data returned by the endpoint was
149 greater than e 149 greater than either the max packet size of the
150 endpoint or th 150 endpoint or the remaining buffer size.
151 "Babble". 151 "Babble".
152 152
153 ``-EREMOTEIO`` The data read 153 ``-EREMOTEIO`` The data read from the endpoint did not fill
154 the specified 154 the specified buffer, and ``URB_SHORT_NOT_OK``
155 was set in ``u 155 was set in ``urb->transfer_flags``.
156 156
157 ``-ENODEV`` Device was rem 157 ``-ENODEV`` Device was removed. Often preceded by a burst
158 of other error 158 of other errors, since the hub driver doesn't
159 detect device 159 detect device removal events immediately.
160 160
161 ``-EXDEV`` ISO transfer o 161 ``-EXDEV`` ISO transfer only partially completed
162 (only set in ` 162 (only set in ``iso_frame_desc[n].status``,
163 not ``urb->sta 163 not ``urb->status``)
164 164
165 ``-EINVAL`` ISO madness, i 165 ``-EINVAL`` ISO madness, if this happens: Log off and
166 go home 166 go home
167 167
168 ``-ECONNRESET`` URB was asynch 168 ``-ECONNRESET`` URB was asynchronously unlinked by
169 :c:func:`usb_u 169 :c:func:`usb_unlink_urb`
170 170
171 ``-ESHUTDOWN`` The device or 171 ``-ESHUTDOWN`` The device or host controller has been
172 disabled due t 172 disabled due to some problem that could not
173 be worked arou 173 be worked around, such as a physical
174 disconnect. 174 disconnect.
175 =============================== ============== 175 =============================== ===============================================
176 176
177 177
178 .. [#f1] 178 .. [#f1]
179 179
180 Error codes like ``-EPROTO``, ``-EILSEQ`` a 180 Error codes like ``-EPROTO``, ``-EILSEQ`` and ``-EOVERFLOW`` normally
181 indicate hardware problems such as bad devi 181 indicate hardware problems such as bad devices (including firmware)
182 or cables. 182 or cables.
183 183
184 .. [#f2] 184 .. [#f2]
185 185
186 This is also one of several codes that diff 186 This is also one of several codes that different kinds of host
187 controller use to indicate a transfer has f 187 controller use to indicate a transfer has failed because of device
188 disconnect. In the interval before the hub 188 disconnect. In the interval before the hub driver starts disconnect
189 processing, devices may receive such fault 189 processing, devices may receive such fault reports for every request.
190 190
191 191
192 192
193 Error codes returned by usbcore-functions 193 Error codes returned by usbcore-functions
194 ========================================= 194 =========================================
195 195
196 .. note:: expect also other submit and transfe 196 .. note:: expect also other submit and transfer status codes
197 197
198 :c:func:`usb_register`: 198 :c:func:`usb_register`:
199 199
200 ======================= ====================== 200 ======================= ===================================
201 ``-EINVAL`` error during registeri 201 ``-EINVAL`` error during registering new driver
202 ======================= ====================== 202 ======================= ===================================
203 203
204 ``usb_get_*/usb_set_*()``, 204 ``usb_get_*/usb_set_*()``,
205 :c:func:`usb_control_msg`, 205 :c:func:`usb_control_msg`,
206 :c:func:`usb_bulk_msg()`: 206 :c:func:`usb_bulk_msg()`:
207 207
208 ======================= ====================== 208 ======================= ==============================================
209 ``-ETIMEDOUT`` Timeout expired before 209 ``-ETIMEDOUT`` Timeout expired before the transfer completed.
210 ======================= ====================== 210 ======================= ==============================================
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.