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