Quelle  fault-codes.rst   Sprache: unbekannt

=====================
I2C/SMBUS Fault Codes
=====================

This is a summary of the most important conventions for use of fault
codes in the I2C/SMBus stack.


A "Fault" is not always an "Error"
----------------------------------
Not all fault reports imply errors; "page faults" should be a familiar
example.  Software often retries idempotent operations after transient
faults.  There may be fancier recovery schemes that are appropriate in
some cases, such as re-initializing (and maybe resetting).  After such
recovery, triggered by a fault report, there is no error.

In a similar way, sometimes a "fault" code just reports one defined
result for an operation ... it doesn't indicate that anything is wrong
at all, just that the outcome wasn't on the "golden path".

In short, your I2C driver code may need to know these codes in order
to respond correctly.  Other code may need to rely on YOUR code reporting
the right fault code, so that it can (in turn) behave correctly.


I2C and SMBus fault codes
-------------------------
These are returned as negative numbers from most calls, with zero or
some positive number indicating a non-fault return.  The specific
numbers associated with these symbols differ between architectures,
though most Linux systems use <asm-generic/errno*.h> numbering.

Note that the descriptions here are not exhaustive.  There are other
codes that may be returned, and other cases where these codes should
be returned.  However, drivers should not return other codes for these
cases (unless the hardware doesn't provide unique fault reports).

Also, codes returned by adapter probe methods follow rules which are
specific to their host bus (such as PCI, or the platform bus).


EAFNOSUPPORT
 Returned by I2C adapters not supporting 10 bit addresses when
 they are requested to use such an address.

EAGAIN
 Returned by I2C adapters when they lose arbitration in master
 transmit mode:  some other master was transmitting different
 data at the same time.

 Also returned when trying to invoke an I2C operation in an
 atomic context, when some task is already using that I2C bus
 to execute some other operation.

EBADMSG
 Returned by SMBus logic when an invalid Packet Error Code byte
 is received.  This code is a CRC covering all bytes in the
 transaction, and is sent before the terminating STOP.  This
 fault is only reported on read transactions; the SMBus slave
 may have a way to report PEC mismatches on writes from the
 host.  Note that even if PECs are in use, you should not rely
 on these as the only way to detect incorrect data transfers.

EBUSY
 Returned by SMBus adapters when the bus was busy for longer
 than allowed.  This usually indicates some device (maybe the
 SMBus adapter) needs some fault recovery (such as resetting),
 or that the reset was attempted but failed.

EINVAL
 This rather vague error means an invalid parameter has been
 detected before any I/O operation was started.  Use a more
 specific fault code when you can.

EIO
 This rather vague error means something went wrong when
 performing an I/O operation.  Use a more specific fault
 code when you can.

ENODEV
 Returned by driver probe() methods.  This is a bit more
 specific than ENXIO, implying the problem isn't with the
 address, but with the device found there.  Driver probes
 may verify the device returns *correct* responses, and
 return this as appropriate.  (The driver core will warn
 about probe faults other than ENXIO and ENODEV.)

ENOMEM
 Returned by any component that can't allocate memory when
 it needs to do so.

ENXIO
 Returned by I2C adapters to indicate that the address phase
 of a transfer didn't get an ACK.  While it might just mean
 an I2C device was temporarily not responding, usually it
 means there's nothing listening at that address.

 Returned by driver probe() methods to indicate that they
 found no device to bind to.  (ENODEV may also be used.)

EOPNOTSUPP
 Returned by an adapter when asked to perform an operation
 that it doesn't, or can't, support.

 For example, this would be returned when an adapter that
 doesn't support SMBus block transfers is asked to execute
 one.  In that case, the driver making that request should
 have verified that functionality was supported before it
 made that block transfer request.

 Similarly, if an I2C adapter can't execute all legal I2C
 messages, it should return this when asked to perform a
 transaction it can't.  (These limitations can't be seen in
 the adapter's functionality mask, since the assumption is
 that if an adapter supports I2C it supports all of I2C.)

EPROTO
 Returned when slave does not conform to the relevant I2C
 or SMBus (or chip-specific) protocol specifications.  One
 case is when the length of an SMBus block data response
 (from the SMBus slave) is outside the range 1-32 bytes.

ESHUTDOWN
 Returned when a transfer was requested using an adapter
 which is already suspended.

ETIMEDOUT
 This is returned by drivers when an operation took too much
 time, and was aborted before it completed.

 SMBus adapters may return it when an operation took more
 time than allowed by the SMBus specification; for example,
 when a slave stretches clocks too far.  I2C has no such
 timeouts, but it's normal for I2C adapters to impose some
 arbitrary limits (much longer than SMBus!) too.