1This is a summary of the most important conventions for use of fault
   2codes in the I2C/SMBus stack.
   5A "Fault" is not always an "Error"
   7Not all fault reports imply errors; "page faults" should be a familiar
   8example.  Software often retries idempotent operations after transient
   9faults.  There may be fancier recovery schemes that are appropriate in
  10some cases, such as re-initializing (and maybe resetting).  After such
  11recovery, triggered by a fault report, there is no error.
  13In a similar way, sometimes a "fault" code just reports one defined
  14result for an operation ... it doesn't indicate that anything is wrong
  15at all, just that the outcome wasn't on the "golden path".
  17In short, your I2C driver code may need to know these codes in order
  18to respond correctly.  Other code may need to rely on YOUR code reporting
  19the right fault code, so that it can (in turn) behave correctly.
  22I2C and SMBus fault codes
  24These are returned as negative numbers from most calls, with zero or
  25some positive number indicating a non-fault return.  The specific
  26numbers associated with these symbols differ between architectures,
  27though most Linux systems use <asm-generic/errno*.h> numbering.
  29Note that the descriptions here are not exhaustive.  There are other
  30codes that may be returned, and other cases where these codes should
  31be returned.  However, drivers should not return other codes for these
  32cases (unless the hardware doesn't provide unique fault reports).
  34Also, codes returned by adapter probe methods follow rules which are
  35specific to their host bus (such as PCI, or the platform bus).
  39        Returned by I2C adapters when they lose arbitration in master
  40        transmit mode:  some other master was transmitting different
  41        data at the same time.
  43        Also returned when trying to invoke an I2C operation in an
  44        atomic context, when some task is already using that I2C bus
  45        to execute some other operation.
  48        Returned by SMBus logic when an invalid Packet Error Code byte
  49        is received.  This code is a CRC covering all bytes in the
  50        transaction, and is sent before the terminating STOP.  This
  51        fault is only reported on read transactions; the SMBus slave
  52        may have a way to report PEC mismatches on writes from the
  53        host.  Note that even if PECs are in use, you should not rely
  54        on these as the only way to detect incorrect data transfers.
  57        Returned by SMBus adapters when the bus was busy for longer
  58        than allowed.  This usually indicates some device (maybe the
  59        SMBus adapter) needs some fault recovery (such as resetting),
  60        or that the reset was attempted but failed.
  63        This rather vague error means an invalid parameter has been
  64        detected before any I/O operation was started.  Use a more
  65        specific fault code when you can.
  67        One example would be a driver trying an SMBus Block Write
  68        with block size outside the range of 1-32 bytes.
  71        This rather vague error means something went wrong when
  72        performing an I/O operation.  Use a more specific fault
  73        code when you can.
  76        Returned by driver probe() methods.  This is a bit more
  77        specific than ENXIO, implying the problem isn't with the
  78        address, but with the device found there.  Driver probes
  79        may verify the device returns *correct* responses, and
  80        return this as appropriate.  (The driver core will warn
  81        about probe faults other than ENXIO and ENODEV.)
  84        Returned by any component that can't allocate memory when
  85        it needs to do so.
  88        Returned by I2C adapters to indicate that the address phase
  89        of a transfer didn't get an ACK.  While it might just mean
  90        an I2C device was temporarily not responding, usually it
  91        means there's nothing listening at that address.
  93        Returned by driver probe() methods to indicate that they
  94        found no device to bind to.  (ENODEV may also be used.)
  97        Returned by an adapter when asked to perform an operation
  98        that it doesn't, or can't, support.
 100        For example, this would be returned when an adapter that
 101        doesn't support SMBus block transfers is asked to execute
 102        one.  In that case, the driver making that request should
 103        have verified that functionality was supported before it
 104        made that block transfer request.
 106        Similarly, if an I2C adapter can't execute all legal I2C
 107        messages, it should return this when asked to perform a
 108        transaction it can't.  (These limitations can't be seen in
 109        the adapter's functionality mask, since the assumption is
 110        that if an adapter supports I2C it supports all of I2C.)
 113        Returned when slave does not conform to the relevant I2C
 114        or SMBus (or chip-specific) protocol specifications.  One
 115        case is when the length of an SMBus block data response
 116        (from the SMBus slave) is outside the range 1-32 bytes.
 119        This is returned by drivers when an operation took too much
 120        time, and was aborted before it completed.
 122        SMBus adapters may return it when an operation took more
 123        time than allowed by the SMBus specification; for example,
 124        when a slave stretches clocks too far.  I2C has no such
 125        timeouts, but it's normal for I2C adapters to impose some
 126        arbitrary limits (much longer than SMBus!) too.
 128 kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.