patch from David Probnell, updating the USB error-codes.txt file
[opensuse:kernel.git] / Documentation / usb / error-codes.txt
1 Revised: 2002-Feb-09.
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.
9
10
11 **************************************************************************
12 *                   Error codes returned by usb_submit_urb               *
13 **************************************************************************
14
15 Non-USB-specific:
16
17 0               URB submission went fine
18
19 -ENOMEM         no memory for allocation of internal structures 
20
21 USB-specific:
22
23 -ENODEV         specified USB-device or bus doesn't exist
24
25 -ENXIO          a control or interrupt URB is already queued to this endpoint;
26                 or (UHCI only) a bulk URB is already queued to this endpoint
27                 and USB_QUEUE_BULK wasn't used
28
29 -EINVAL         a) Invalid transfer type specified (or not supported)
30                 b) Invalid interrupt interval (0<=n<256)
31                 c) more than one interrupt packet requested
32                 d) ISO: number_of_packets is < 0
33
34 -EAGAIN         a) specified ISO start frame too early
35                 b) (using ISO-ASAP) too much scheduled for the future
36                    wait some time and try again.
37
38 -EFBIG          too much ISO frames requested (currently uhci>900)
39
40 -EPIPE          Specified endpoint is stalled.  For non-control endpoints,
41                 reset this status with usb_clear_halt().
42
43 -EMSGSIZE       endpoint message size is zero, do interface/alternate setting
44
45 -ENOSPC         The host controller's bandwidth is already consumed and
46                 this request would push it past its allowed limit.
47
48 -ESHUTDOWN      The host controller has been disabled due to some
49                 problem that could not be worked around.
50
51
52 **************************************************************************
53 *                   Error codes returned by in urb->status               *
54 *                   or in iso_frame_desc[n].status (for ISO)             *
55 **************************************************************************
56
57 USB device drivers may only test urb status values in completion handlers.
58 This is because otherwise there would be a race between HCDs updating
59 these values on one CPU, and device drivers testing them on another CPU.
60
61 A transfer's actual_length may be positive even when an error has been
62 reported.  That's because transfers often involve several packets, so that
63 one or more packets could finish before an error stops further endpoint I/O.
64
65
66 0                       Transfer completed successfully
67
68 -ENOENT                 URB was synchronously unlinked by usb_unlink_urb
69
70 -EINPROGRESS            URB still pending, no results yet
71                         (That is, if drivers see this it's a bug.)
72
73 -EPROTO (*)             a) bitstuff error
74                         b) unknown USB error 
75
76 -EILSEQ (*)             CRC mismatch
77
78 -EPIPE                  Endpoint stalled.  For non-control endpoints,
79                         reset this status with usb_clear_halt().
80
81 -ECOMM                  During an IN transfer, the host controller
82                         received data from an endpoint faster than it
83                         could be written to system memory
84
85 -ENOSR                  During an OUT transfer, the host controller
86                         could not retrieve data from system memory fast
87                         enough to keep up with the USB data rate
88
89 -EOVERFLOW (*)          The amount of data returned by the endpoint was
90                         greater than either the max packet size of the
91                         endpoint or the remaining buffer size.  "Babble".
92
93 -EREMOTEIO              The endpoint returned less than max packet size
94                         and that amount did not fill the specified buffer
95                         (and USB_DISBLE_SPD was not set in transfer_flags)
96
97 -ETIMEDOUT              transfer timed out, NAK
98
99 -ENODEV                 Device was removed.  Often preceded by a burst of
100                         other errors, since the hub driver does't detect
101                         device removal events immediately.
102
103 -EXDEV                  ISO transfer only partially completed
104                         look at individual frame status for details
105
106 -EINVAL                 ISO madness, if this happens: Log off and go home
107
108 -ECONNRESET             URB was asynchronously unlinked by usb_unlink_urb
109
110 -ESHUTDOWN              The host controller has been disabled due to some
111                         problem that could not be worked around.
112
113
114 (*) Error codes like -EPROTO, -EILSEQ and -EOVERFLOW normally indicate
115 hardware problems such as bad devices (including firmware) or cables.
116
117
118
119 **************************************************************************
120 *              Error codes returned by usbcore-functions                 *
121 *           (expect also other submit and transfer status codes)         *
122 **************************************************************************
123
124 usb_register():
125 -EINVAL                 error during registering new driver
126
127 usb_get_*/usb_set_*():
128 usb_control_msg():
129 usb_bulk_msg():
130                         All USB errors (submit/status) can occur