mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2025-01-08 14:13:53 +00:00
error-codes.rst: convert to ReST and add to driver-api book
This document describe some USB core features. Add it to the driver-api book. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab
Jonathan Corbet
parent
2a373331dd
commit
360a7b5f57
205
Documentation/driver-api/usb/error-codes.rst
Normal file
205
Documentation/driver-api/usb/error-codes.rst
Normal file
@ -0,0 +1,205 @@
|
|||||||
|
USB Error codes
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
:Revised: 2004-Oct-21
|
||||||
|
|
||||||
|
This is the documentation of (hopefully) all possible error codes (and
|
||||||
|
their interpretation) that can be returned from usbcore.
|
||||||
|
|
||||||
|
Some of them are returned by the Host Controller Drivers (HCDs), which
|
||||||
|
device drivers only see through usbcore. As a rule, all the HCDs should
|
||||||
|
behave the same except for transfer speed dependent behaviors and the
|
||||||
|
way certain faults are reported.
|
||||||
|
|
||||||
|
|
||||||
|
Error codes returned by :c:func:`usb_submit_urb`
|
||||||
|
================================================
|
||||||
|
|
||||||
|
Non-USB-specific:
|
||||||
|
|
||||||
|
|
||||||
|
=============== ===============================================
|
||||||
|
0 URB submission went fine
|
||||||
|
|
||||||
|
``-ENOMEM`` no memory for allocation of internal structures
|
||||||
|
=============== ===============================================
|
||||||
|
|
||||||
|
USB-specific:
|
||||||
|
|
||||||
|
======================= =======================================================
|
||||||
|
``-EBUSY`` The URB is already active.
|
||||||
|
|
||||||
|
``-ENODEV`` specified USB-device or bus doesn't exist
|
||||||
|
|
||||||
|
``-ENOENT`` specified interface or endpoint does not exist or
|
||||||
|
is not enabled
|
||||||
|
|
||||||
|
``-ENXIO`` host controller driver does not support queuing of
|
||||||
|
this type of urb. (treat as a host controller bug.)
|
||||||
|
|
||||||
|
``-EINVAL`` a) Invalid transfer type specified (or not supported)
|
||||||
|
b) Invalid or unsupported periodic transfer interval
|
||||||
|
c) ISO: attempted to change transfer interval
|
||||||
|
d) ISO: ``number_of_packets`` is < 0
|
||||||
|
e) various other cases
|
||||||
|
|
||||||
|
``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the
|
||||||
|
frames the URB would be scheduled in have already
|
||||||
|
expired.
|
||||||
|
|
||||||
|
``-EFBIG`` Host controller driver can't schedule that many ISO
|
||||||
|
frames.
|
||||||
|
|
||||||
|
``-EPIPE`` The pipe type specified in the URB doesn't match the
|
||||||
|
endpoint's actual type.
|
||||||
|
|
||||||
|
``-EMSGSIZE`` (a) endpoint maxpacket size is zero; it is not usable
|
||||||
|
in the current interface altsetting.
|
||||||
|
(b) ISO packet is larger than the endpoint maxpacket.
|
||||||
|
(c) requested data transfer length is invalid: negative
|
||||||
|
or too large for the host controller.
|
||||||
|
|
||||||
|
``-ENOSPC`` This request would overcommit the usb bandwidth reserved
|
||||||
|
for periodic transfers (interrupt, isochronous).
|
||||||
|
|
||||||
|
``-ESHUTDOWN`` The device or host controller has been disabled due to
|
||||||
|
some problem that could not be worked around.
|
||||||
|
|
||||||
|
``-EPERM`` Submission failed because ``urb->reject`` was set.
|
||||||
|
|
||||||
|
``-EHOSTUNREACH`` URB was rejected because the device is suspended.
|
||||||
|
|
||||||
|
``-ENOEXEC`` A control URB doesn't contain a Setup packet.
|
||||||
|
======================= =======================================================
|
||||||
|
|
||||||
|
Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` (for ISO)
|
||||||
|
=======================================================================================
|
||||||
|
|
||||||
|
USB device drivers may only test urb status values in completion handlers.
|
||||||
|
This is because otherwise there would be a race between HCDs updating
|
||||||
|
these values on one CPU, and device drivers testing them on another CPU.
|
||||||
|
|
||||||
|
A transfer's actual_length may be positive even when an error has been
|
||||||
|
reported. That's because transfers often involve several packets, so that
|
||||||
|
one or more packets could finish before an error stops further endpoint I/O.
|
||||||
|
|
||||||
|
For isochronous URBs, the urb status value is non-zero only if the URB is
|
||||||
|
unlinked, the device is removed, the host controller is disabled, or the total
|
||||||
|
transferred length is less than the requested length and the
|
||||||
|
``URB_SHORT_NOT_OK`` flag is set. Completion handlers for isochronous URBs
|
||||||
|
should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``,
|
||||||
|
``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields
|
||||||
|
may report more status codes.
|
||||||
|
|
||||||
|
|
||||||
|
=============================== ===============================================
|
||||||
|
0 Transfer completed successfully
|
||||||
|
|
||||||
|
``-ENOENT`` URB was synchronously unlinked by
|
||||||
|
:c:func:`usb_unlink_urb`
|
||||||
|
|
||||||
|
``-EINPROGRESS`` URB still pending, no results yet
|
||||||
|
(That is, if drivers see this it's a bug.)
|
||||||
|
|
||||||
|
``-EPROTO`` [#f1]_, [#f2]_ a) bitstuff error
|
||||||
|
b) no response packet received within the
|
||||||
|
prescribed bus turn-around time
|
||||||
|
c) unknown USB error
|
||||||
|
|
||||||
|
``-EILSEQ`` [#f1]_, [#f2]_ a) CRC mismatch
|
||||||
|
b) no response packet received within the
|
||||||
|
prescribed bus turn-around time
|
||||||
|
c) unknown USB error
|
||||||
|
|
||||||
|
Note that often the controller hardware does
|
||||||
|
not distinguish among cases a), b), and c), so
|
||||||
|
a driver cannot tell whether there was a
|
||||||
|
protocol error, a failure to respond (often
|
||||||
|
caused by device disconnect), or some other
|
||||||
|
fault.
|
||||||
|
|
||||||
|
``-ETIME`` [#f2]_ No response packet received within the
|
||||||
|
prescribed bus turn-around time. This error
|
||||||
|
may instead be reported as
|
||||||
|
``-EPROTO`` or ``-EILSEQ``.
|
||||||
|
|
||||||
|
``-ETIMEDOUT`` Synchronous USB message functions use this code
|
||||||
|
to indicate timeout expired before the transfer
|
||||||
|
completed, and no other error was reported
|
||||||
|
by HC.
|
||||||
|
|
||||||
|
``-EPIPE`` [#f2]_ Endpoint stalled. For non-control endpoints,
|
||||||
|
reset this status with
|
||||||
|
:c:func:`usb_clear_halt`.
|
||||||
|
|
||||||
|
``-ECOMM`` During an IN transfer, the host controller
|
||||||
|
received data from an endpoint faster than it
|
||||||
|
could be written to system memory
|
||||||
|
|
||||||
|
``-ENOSR`` During an OUT transfer, the host controller
|
||||||
|
could not retrieve data from system memory fast
|
||||||
|
enough to keep up with the USB data rate
|
||||||
|
|
||||||
|
``-EOVERFLOW`` [#f1]_ The amount of data returned by the endpoint was
|
||||||
|
greater than either the max packet size of the
|
||||||
|
endpoint or the remaining buffer size.
|
||||||
|
"Babble".
|
||||||
|
|
||||||
|
``-EREMOTEIO`` The data read from the endpoint did not fill
|
||||||
|
the specified buffer, and ``URB_SHORT_NOT_OK``
|
||||||
|
was set in ``urb->transfer_flags``.
|
||||||
|
|
||||||
|
``-ENODEV`` Device was removed. Often preceded by a burst
|
||||||
|
of other errors, since the hub driver doesn't
|
||||||
|
detect device removal events immediately.
|
||||||
|
|
||||||
|
``-EXDEV`` ISO transfer only partially completed
|
||||||
|
(only set in ``iso_frame_desc[n].status``,
|
||||||
|
not ``urb->status``)
|
||||||
|
|
||||||
|
``-EINVAL`` ISO madness, if this happens: Log off and
|
||||||
|
go home
|
||||||
|
|
||||||
|
``-ECONNRESET`` URB was asynchronously unlinked by
|
||||||
|
:c:func:`usb_unlink_urb`
|
||||||
|
|
||||||
|
``-ESHUTDOWN`` The device or host controller has been
|
||||||
|
disabled due to some problem that could not
|
||||||
|
be worked around, such as a physical
|
||||||
|
disconnect.
|
||||||
|
=============================== ===============================================
|
||||||
|
|
||||||
|
|
||||||
|
.. [#f1]
|
||||||
|
|
||||||
|
Error codes like ``-EPROTO``, ``-EILSEQ`` and ``-EOVERFLOW`` normally
|
||||||
|
indicate hardware problems such as bad devices (including firmware)
|
||||||
|
or cables.
|
||||||
|
|
||||||
|
.. [#f2]
|
||||||
|
|
||||||
|
This is also one of several codes that different kinds of host
|
||||||
|
controller use to indicate a transfer has failed because of device
|
||||||
|
disconnect. In the interval before the hub driver starts disconnect
|
||||||
|
processing, devices may receive such fault reports for every request.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Error codes returned by usbcore-functions
|
||||||
|
=========================================
|
||||||
|
|
||||||
|
.. note:: expect also other submit and transfer status codes
|
||||||
|
|
||||||
|
:c:func:`usb_register`:
|
||||||
|
|
||||||
|
======================= ===================================
|
||||||
|
``-EINVAL`` error during registering new driver
|
||||||
|
======================= ===================================
|
||||||
|
|
||||||
|
``usb_get_*/usb_set_*()``,
|
||||||
|
:c:func:`usb_control_msg`,
|
||||||
|
:c:func:`usb_bulk_msg()`:
|
||||||
|
|
||||||
|
======================= ==============================================
|
||||||
|
``-ETIMEDOUT`` Timeout expired before the transfer completed.
|
||||||
|
======================= ==============================================
|
||||||
@ -11,6 +11,7 @@ Linux USB API
|
|||||||
callbacks
|
callbacks
|
||||||
dma
|
dma
|
||||||
power-management
|
power-management
|
||||||
|
error-codes
|
||||||
writing_usb_driver
|
writing_usb_driver
|
||||||
writing_musb_glue_layer
|
writing_musb_glue_layer
|
||||||
|
|
||||||
|
|||||||
@ -1,175 +0,0 @@
|
|||||||
Revised: 2004-Oct-21
|
|
||||||
|
|
||||||
This is the documentation of (hopefully) all possible error codes (and
|
|
||||||
their interpretation) that can be returned from usbcore.
|
|
||||||
|
|
||||||
Some of them are returned by the Host Controller Drivers (HCDs), which
|
|
||||||
device drivers only see through usbcore. As a rule, all the HCDs should
|
|
||||||
behave the same except for transfer speed dependent behaviors and the
|
|
||||||
way certain faults are reported.
|
|
||||||
|
|
||||||
|
|
||||||
**************************************************************************
|
|
||||||
* Error codes returned by usb_submit_urb *
|
|
||||||
**************************************************************************
|
|
||||||
|
|
||||||
Non-USB-specific:
|
|
||||||
|
|
||||||
0 URB submission went fine
|
|
||||||
|
|
||||||
-ENOMEM no memory for allocation of internal structures
|
|
||||||
|
|
||||||
USB-specific:
|
|
||||||
|
|
||||||
-EBUSY The URB is already active.
|
|
||||||
|
|
||||||
-ENODEV specified USB-device or bus doesn't exist
|
|
||||||
|
|
||||||
-ENOENT specified interface or endpoint does not exist or
|
|
||||||
is not enabled
|
|
||||||
|
|
||||||
-ENXIO host controller driver does not support queuing of this type
|
|
||||||
of urb. (treat as a host controller bug.)
|
|
||||||
|
|
||||||
-EINVAL a) Invalid transfer type specified (or not supported)
|
|
||||||
b) Invalid or unsupported periodic transfer interval
|
|
||||||
c) ISO: attempted to change transfer interval
|
|
||||||
d) ISO: number_of_packets is < 0
|
|
||||||
e) various other cases
|
|
||||||
|
|
||||||
-EXDEV ISO: URB_ISO_ASAP wasn't specified and all the frames
|
|
||||||
the URB would be scheduled in have already expired.
|
|
||||||
|
|
||||||
-EFBIG Host controller driver can't schedule that many ISO frames.
|
|
||||||
|
|
||||||
-EPIPE The pipe type specified in the URB doesn't match the
|
|
||||||
endpoint's actual type.
|
|
||||||
|
|
||||||
-EMSGSIZE (a) endpoint maxpacket size is zero; it is not usable
|
|
||||||
in the current interface altsetting.
|
|
||||||
(b) ISO packet is larger than the endpoint maxpacket.
|
|
||||||
(c) requested data transfer length is invalid: negative
|
|
||||||
or too large for the host controller.
|
|
||||||
|
|
||||||
-ENOSPC This request would overcommit the usb bandwidth reserved
|
|
||||||
for periodic transfers (interrupt, isochronous).
|
|
||||||
|
|
||||||
-ESHUTDOWN The device or host controller has been disabled due to some
|
|
||||||
problem that could not be worked around.
|
|
||||||
|
|
||||||
-EPERM Submission failed because urb->reject was set.
|
|
||||||
|
|
||||||
-EHOSTUNREACH URB was rejected because the device is suspended.
|
|
||||||
|
|
||||||
-ENOEXEC A control URB doesn't contain a Setup packet.
|
|
||||||
|
|
||||||
|
|
||||||
**************************************************************************
|
|
||||||
* Error codes returned by in urb->status *
|
|
||||||
* or in iso_frame_desc[n].status (for ISO) *
|
|
||||||
**************************************************************************
|
|
||||||
|
|
||||||
USB device drivers may only test urb status values in completion handlers.
|
|
||||||
This is because otherwise there would be a race between HCDs updating
|
|
||||||
these values on one CPU, and device drivers testing them on another CPU.
|
|
||||||
|
|
||||||
A transfer's actual_length may be positive even when an error has been
|
|
||||||
reported. That's because transfers often involve several packets, so that
|
|
||||||
one or more packets could finish before an error stops further endpoint I/O.
|
|
||||||
|
|
||||||
For isochronous URBs, the urb status value is non-zero only if the URB is
|
|
||||||
unlinked, the device is removed, the host controller is disabled, or the total
|
|
||||||
transferred length is less than the requested length and the URB_SHORT_NOT_OK
|
|
||||||
flag is set. Completion handlers for isochronous URBs should only see
|
|
||||||
urb->status set to zero, -ENOENT, -ECONNRESET, -ESHUTDOWN, or -EREMOTEIO.
|
|
||||||
Individual frame descriptor status fields may report more status codes.
|
|
||||||
|
|
||||||
|
|
||||||
0 Transfer completed successfully
|
|
||||||
|
|
||||||
-ENOENT URB was synchronously unlinked by usb_unlink_urb
|
|
||||||
|
|
||||||
-EINPROGRESS URB still pending, no results yet
|
|
||||||
(That is, if drivers see this it's a bug.)
|
|
||||||
|
|
||||||
-EPROTO (*, **) a) bitstuff error
|
|
||||||
b) no response packet received within the
|
|
||||||
prescribed bus turn-around time
|
|
||||||
c) unknown USB error
|
|
||||||
|
|
||||||
-EILSEQ (*, **) a) CRC mismatch
|
|
||||||
b) no response packet received within the
|
|
||||||
prescribed bus turn-around time
|
|
||||||
c) unknown USB error
|
|
||||||
|
|
||||||
Note that often the controller hardware does not
|
|
||||||
distinguish among cases a), b), and c), so a
|
|
||||||
driver cannot tell whether there was a protocol
|
|
||||||
error, a failure to respond (often caused by
|
|
||||||
device disconnect), or some other fault.
|
|
||||||
|
|
||||||
-ETIME (**) No response packet received within the prescribed
|
|
||||||
bus turn-around time. This error may instead be
|
|
||||||
reported as -EPROTO or -EILSEQ.
|
|
||||||
|
|
||||||
-ETIMEDOUT Synchronous USB message functions use this code
|
|
||||||
to indicate timeout expired before the transfer
|
|
||||||
completed, and no other error was reported by HC.
|
|
||||||
|
|
||||||
-EPIPE (**) Endpoint stalled. For non-control endpoints,
|
|
||||||
reset this status with usb_clear_halt().
|
|
||||||
|
|
||||||
-ECOMM During an IN transfer, the host controller
|
|
||||||
received data from an endpoint faster than it
|
|
||||||
could be written to system memory
|
|
||||||
|
|
||||||
-ENOSR During an OUT transfer, the host controller
|
|
||||||
could not retrieve data from system memory fast
|
|
||||||
enough to keep up with the USB data rate
|
|
||||||
|
|
||||||
-EOVERFLOW (*) The amount of data returned by the endpoint was
|
|
||||||
greater than either the max packet size of the
|
|
||||||
endpoint or the remaining buffer size. "Babble".
|
|
||||||
|
|
||||||
-EREMOTEIO The data read from the endpoint did not fill the
|
|
||||||
specified buffer, and URB_SHORT_NOT_OK was set in
|
|
||||||
urb->transfer_flags.
|
|
||||||
|
|
||||||
-ENODEV Device was removed. Often preceded by a burst of
|
|
||||||
other errors, since the hub driver doesn't detect
|
|
||||||
device removal events immediately.
|
|
||||||
|
|
||||||
-EXDEV ISO transfer only partially completed
|
|
||||||
(only set in iso_frame_desc[n].status, not urb->status)
|
|
||||||
|
|
||||||
-EINVAL ISO madness, if this happens: Log off and go home
|
|
||||||
|
|
||||||
-ECONNRESET URB was asynchronously unlinked by usb_unlink_urb
|
|
||||||
|
|
||||||
-ESHUTDOWN The device or host controller has been disabled due
|
|
||||||
to some problem that could not be worked around,
|
|
||||||
such as a physical disconnect.
|
|
||||||
|
|
||||||
|
|
||||||
(*) Error codes like -EPROTO, -EILSEQ and -EOVERFLOW normally indicate
|
|
||||||
hardware problems such as bad devices (including firmware) or cables.
|
|
||||||
|
|
||||||
(**) This is also one of several codes that different kinds of host
|
|
||||||
controller use to indicate a transfer has failed because of device
|
|
||||||
disconnect. In the interval before the hub driver starts disconnect
|
|
||||||
processing, devices may receive such fault reports for every request.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
**************************************************************************
|
|
||||||
* Error codes returned by usbcore-functions *
|
|
||||||
* (expect also other submit and transfer status codes) *
|
|
||||||
**************************************************************************
|
|
||||||
|
|
||||||
usb_register():
|
|
||||||
-EINVAL error during registering new driver
|
|
||||||
|
|
||||||
usb_get_*/usb_set_*():
|
|
||||||
usb_control_msg():
|
|
||||||
usb_bulk_msg():
|
|
||||||
-ETIMEDOUT Timeout expired before the transfer completed.
|
|
||||||
Loading…
Reference in New Issue
Block a user