Documentation/i2c/fault-codes.rst

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