1=====================
  2I2C/SMBUS Fault Codes
  3=====================
  4
  5This is a summary of the most important conventions for use of fault
  6codes in the I2C/SMBus stack.
  7
  8
  9A "Fault" is not always an "Error"
 10----------------------------------
 11Not all fault reports imply errors; "page faults" should be a familiar
 12example.  Software often retries idempotent operations after transient
 13faults.  There may be fancier recovery schemes that are appropriate in
 14some cases, such as re-initializing (and maybe resetting).  After such
 15recovery, triggered by a fault report, there is no error.
 16
 17In a similar way, sometimes a "fault" code just reports one defined
 18result for an operation ... it doesn't indicate that anything is wrong
 19at all, just that the outcome wasn't on the "golden path".
 20
 21In short, your I2C driver code may need to know these codes in order
 22to respond correctly.  Other code may need to rely on YOUR code reporting
 23the right fault code, so that it can (in turn) behave correctly.
 24
 25
 26I2C and SMBus fault codes
 27-------------------------
 28These are returned as negative numbers from most calls, with zero or
 29some positive number indicating a non-fault return.  The specific
 30numbers associated with these symbols differ between architectures,
 31though most Linux systems use <asm-generic/errno*.h> numbering.
 32
 33Note that the descriptions here are not exhaustive.  There are other
 34codes that may be returned, and other cases where these codes should
 35be returned.  However, drivers should not return other codes for these
 36cases (unless the hardware doesn't provide unique fault reports).
 37
 38Also, codes returned by adapter probe methods follow rules which are
 39specific to their host bus (such as PCI, or the platform bus).
 40
 41
 42EAFNOSUPPORT
 43	Returned by I2C adapters not supporting 10 bit addresses when
 44	they are requested to use such an address.
 45
 46EAGAIN
 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
 55EBADMSG
 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
 64EBUSY
 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
 70EINVAL
 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
 75EIO
 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
 80ENODEV
 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
 88ENOMEM
 89	Returned by any component that can't allocate memory when
 90	it needs to do so.
 91
 92ENXIO
 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
101EOPNOTSUPP
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
117EPROTO
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
123ESHUTDOWN
124	Returned when a transfer was requested using an adapter
125	which is already suspended.
126
127ETIMEDOUT
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.