1This is a summary of the most important conventions for use of fault
  2codes in the I2C/SMBus stack.
  3
  4
  5A "Fault" is not always an "Error"
  6----------------------------------
  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.
 12
 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".
 16
 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.
 20
 21
 22I2C and SMBus fault codes
 23-------------------------
 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.
 28
 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).
 33
 34Also, codes returned by adapter probe methods follow rules which are
 35specific to their host bus (such as PCI, or the platform bus).
 36
 37
 38EAGAIN
 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.
 42
 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.
 46
 47EBADMSG
 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.
 55
 56EBUSY
 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.
 61
 62EINVAL
 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.
 66
 67EIO
 68	This rather vague error means something went wrong when
 69	performing an I/O operation.  Use a more specific fault
 70	code when you can.
 71
 72ENODEV
 73	Returned by driver probe() methods.  This is a bit more
 74	specific than ENXIO, implying the problem isn't with the
 75	address, but with the device found there.  Driver probes
 76	may verify the device returns *correct* responses, and
 77	return this as appropriate.  (The driver core will warn
 78	about probe faults other than ENXIO and ENODEV.)
 79
 80ENOMEM
 81	Returned by any component that can't allocate memory when
 82	it needs to do so.
 83
 84ENXIO
 85	Returned by I2C adapters to indicate that the address phase
 86	of a transfer didn't get an ACK.  While it might just mean
 87	an I2C device was temporarily not responding, usually it
 88	means there's nothing listening at that address.
 89
 90	Returned by driver probe() methods to indicate that they
 91	found no device to bind to.  (ENODEV may also be used.)
 92
 93EOPNOTSUPP
 94	Returned by an adapter when asked to perform an operation
 95	that it doesn't, or can't, support.
 96
 97	For example, this would be returned when an adapter that
 98	doesn't support SMBus block transfers is asked to execute
 99	one.  In that case, the driver making that request should
100	have verified that functionality was supported before it
101	made that block transfer request.
102
103	Similarly, if an I2C adapter can't execute all legal I2C
104	messages, it should return this when asked to perform a
105	transaction it can't.  (These limitations can't be seen in
106	the adapter's functionality mask, since the assumption is
107	that if an adapter supports I2C it supports all of I2C.)
108
109EPROTO
110	Returned when slave does not conform to the relevant I2C
111	or SMBus (or chip-specific) protocol specifications.  One
112	case is when the length of an SMBus block data response
113	(from the SMBus slave) is outside the range 1-32 bytes.
114
115ETIMEDOUT
116	This is returned by drivers when an operation took too much
117	time, and was aborted before it completed.
118
119	SMBus adapters may return it when an operation took more
120	time than allowed by the SMBus specification; for example,
121	when a slave stretches clocks too far.  I2C has no such
122	timeouts, but it's normal for I2C adapters to impose some
123	arbitrary limits (much longer than SMBus!) too.
124