0001 =====================
0002 I2C/SMBUS Fault Codes
0003 =====================
0004
0005 This is a summary of the most important conventions for use of fault
0006 codes in the I2C/SMBus stack.
0007
0008
0009 A "Fault" is not always an "Error"
0010 ----------------------------------
0011 Not all fault reports imply errors; "page faults" should be a familiar
0012 example. Software often retries idempotent operations after transient
0013 faults. There may be fancier recovery schemes that are appropriate in
0014 some cases, such as re-initializing (and maybe resetting). After such
0015 recovery, triggered by a fault report, there is no error.
0016
0017 In a similar way, sometimes a "fault" code just reports one defined
0018 result for an operation ... it doesn't indicate that anything is wrong
0019 at all, just that the outcome wasn't on the "golden path".
0020
0021 In short, your I2C driver code may need to know these codes in order
0022 to respond correctly. Other code may need to rely on YOUR code reporting
0023 the right fault code, so that it can (in turn) behave correctly.
0024
0025
0026 I2C and SMBus fault codes
0027 -------------------------
0028 These are returned as negative numbers from most calls, with zero or
0029 some positive number indicating a non-fault return. The specific
0030 numbers associated with these symbols differ between architectures,
0031 though most Linux systems use <asm-generic/errno*.h> numbering.
0032
0033 Note that the descriptions here are not exhaustive. There are other
0034 codes that may be returned, and other cases where these codes should
0035 be returned. However, drivers should not return other codes for these
0036 cases (unless the hardware doesn't provide unique fault reports).
0037
0038 Also, codes returned by adapter probe methods follow rules which are
0039 specific to their host bus (such as PCI, or the platform bus).
0040
0041
0042 EAGAIN
0043 Returned by I2C adapters when they lose arbitration in master
0044 transmit mode: some other master was transmitting different
0045 data at the same time.
0046
0047 Also returned when trying to invoke an I2C operation in an
0048 atomic context, when some task is already using that I2C bus
0049 to execute some other operation.
0050
0051 EBADMSG
0052 Returned by SMBus logic when an invalid Packet Error Code byte
0053 is received. This code is a CRC covering all bytes in the
0054 transaction, and is sent before the terminating STOP. This
0055 fault is only reported on read transactions; the SMBus slave
0056 may have a way to report PEC mismatches on writes from the
0057 host. Note that even if PECs are in use, you should not rely
0058 on these as the only way to detect incorrect data transfers.
0059
0060 EBUSY
0061 Returned by SMBus adapters when the bus was busy for longer
0062 than allowed. This usually indicates some device (maybe the
0063 SMBus adapter) needs some fault recovery (such as resetting),
0064 or that the reset was attempted but failed.
0065
0066 EINVAL
0067 This rather vague error means an invalid parameter has been
0068 detected before any I/O operation was started. Use a more
0069 specific fault code when you can.
0070
0071 EIO
0072 This rather vague error means something went wrong when
0073 performing an I/O operation. Use a more specific fault
0074 code when you can.
0075
0076 ENODEV
0077 Returned by driver probe() methods. This is a bit more
0078 specific than ENXIO, implying the problem isn't with the
0079 address, but with the device found there. Driver probes
0080 may verify the device returns *correct* responses, and
0081 return this as appropriate. (The driver core will warn
0082 about probe faults other than ENXIO and ENODEV.)
0083
0084 ENOMEM
0085 Returned by any component that can't allocate memory when
0086 it needs to do so.
0087
0088 ENXIO
0089 Returned by I2C adapters to indicate that the address phase
0090 of a transfer didn't get an ACK. While it might just mean
0091 an I2C device was temporarily not responding, usually it
0092 means there's nothing listening at that address.
0093
0094 Returned by driver probe() methods to indicate that they
0095 found no device to bind to. (ENODEV may also be used.)
0096
0097 EOPNOTSUPP
0098 Returned by an adapter when asked to perform an operation
0099 that it doesn't, or can't, support.
0100
0101 For example, this would be returned when an adapter that
0102 doesn't support SMBus block transfers is asked to execute
0103 one. In that case, the driver making that request should
0104 have verified that functionality was supported before it
0105 made that block transfer request.
0106
0107 Similarly, if an I2C adapter can't execute all legal I2C
0108 messages, it should return this when asked to perform a
0109 transaction it can't. (These limitations can't be seen in
0110 the adapter's functionality mask, since the assumption is
0111 that if an adapter supports I2C it supports all of I2C.)
0112
0113 EPROTO
0114 Returned when slave does not conform to the relevant I2C
0115 or SMBus (or chip-specific) protocol specifications. One
0116 case is when the length of an SMBus block data response
0117 (from the SMBus slave) is outside the range 1-32 bytes.
0118
0119 ESHUTDOWN
0120 Returned when a transfer was requested using an adapter
0121 which is already suspended.
0122
0123 ETIMEDOUT
0124 This is returned by drivers when an operation took too much
0125 time, and was aborted before it completed.
0126
0127 SMBus adapters may return it when an operation took more
0128 time than allowed by the SMBus specification; for example,
0129 when a slave stretches clocks too far. I2C has no such
0130 timeouts, but it's normal for I2C adapters to impose some
0131 arbitrary limits (much longer than SMBus!) too.
