Orange Pi5 kernel

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