[deliverable/linux.git] / Documentation / i2c / fault-codes

This is a summary of the most important conventions for use of fault
codes in the I2C/SMBus stack.


A "Fault" is not always an "Error"
----------------------------------
Not all fault reports imply errors; "page faults" should be a familiar
example.  Software often retries idempotent operations after transient
faults.  There may be fancier recovery schemes that are appropriate in
some cases, such as re-initializing (and maybe resetting).  After such
recovery, triggered by a fault report, there is no error.

In a similar way, sometimes a "fault" code just reports one defined
result for an operation ... it doesn't indicate that anything is wrong
at all, just that the outcome wasn't on the "golden path".

In short, your I2C driver code may need to know these codes in order
to respond correctly.  Other code may need to rely on YOUR code reporting
the right fault code, so that it can (in turn) behave correctly.


I2C and SMBus fault codes
-------------------------
These are returned as negative numbers from most calls, with zero or
some positive number indicating a non-fault return.  The specific
numbers associated with these symbols differ between architectures,
though most Linux systems use <asm-generic/errno*.h> numbering.

Note that the descriptions here are not exhaustive.  There are other
codes that may be returned, and other cases where these codes should
be returned.  However, drivers should not return other codes for these
cases (unless the hardware doesn't provide unique fault reports).

Also, codes returned by adapter probe methods follow rules which are
specific to their host bus (such as PCI, or the platform bus).


EAGAIN
	Returned by I2C adapters when they lose arbitration in master
	transmit mode:  some other master was transmitting different
	data at the same time.

	Also returned when trying to invoke an I2C operation in an
	atomic context, when some task is already using that I2C bus
	to execute some other operation.

EBADMSG
	Returned by SMBus logic when an invalid Packet Error Code byte
	is received.  This code is a CRC covering all bytes in the
	transaction, and is sent before the terminating STOP.  This
	fault is only reported on read transactions; the SMBus slave
	may have a way to report PEC mismatches on writes from the
	host.  Note that even if PECs are in use, you should not rely
	on these as the only way to detect incorrect data transfers.

EBUSY
	Returned by SMBus adapters when the bus was busy for longer
	than allowed.  This usually indicates some device (maybe the
	SMBus adapter) needs some fault recovery (such as resetting),
	or that the reset was attempted but failed.

EINVAL
	This rather vague error means an invalid parameter has been
	detected before any I/O operation was started.  Use a more
	specific fault code when you can.

EIO
	This rather vague error means something went wrong when
	performing an I/O operation.  Use a more specific fault
	code when you can.

ENODEV
	Returned by driver probe() methods.  This is a bit more
	specific than ENXIO, implying the problem isn't with the
	address, but with the device found there.  Driver probes
	may verify the device returns *correct* responses, and
	return this as appropriate.  (The driver core will warn
	about probe faults other than ENXIO and ENODEV.)

ENOMEM
	Returned by any component that can't allocate memory when
	it needs to do so.

ENXIO
	Returned by I2C adapters to indicate that the address phase
	of a transfer didn't get an ACK.  While it might just mean
	an I2C device was temporarily not responding, usually it
	means there's nothing listening at that address.

	Returned by driver probe() methods to indicate that they
	found no device to bind to.  (ENODEV may also be used.)

EOPNOTSUPP
	Returned by an adapter when asked to perform an operation
	that it doesn't, or can't, support.

	For example, this would be returned when an adapter that
	doesn't support SMBus block transfers is asked to execute
	one.  In that case, the driver making that request should
	have verified that functionality was supported before it
	made that block transfer request.

	Similarly, if an I2C adapter can't execute all legal I2C
	messages, it should return this when asked to perform a
	transaction it can't.  (These limitations can't be seen in
	the adapter's functionality mask, since the assumption is
	that if an adapter supports I2C it supports all of I2C.)

EPROTO
	Returned when slave does not conform to the relevant I2C
	or SMBus (or chip-specific) protocol specifications.  One
	case is when the length of an SMBus block data response
	(from the SMBus slave) is outside the range 1-32 bytes.

ETIMEDOUT
	This is returned by drivers when an operation took too much
	time, and was aborted before it completed.

	SMBus adapters may return it when an operation took more
	time than allowed by the SMBus specification; for example,
	when a slave stretches clocks too far.  I2C has no such
	timeouts, but it's normal for I2C adapters to impose some
	arbitrary limits (much longer than SMBus!) too.
Commit	Line	Data
81fded1f DB	1	This is a summary of the most important conventions for use of fault
	2	codes in the I2C/SMBus stack.
	3
	4
	5	A "Fault" is not always an "Error"
	6	----------------------------------
	7	Not all fault reports imply errors; "page faults" should be a familiar
	8	example. Software often retries idempotent operations after transient
	9	faults. There may be fancier recovery schemes that are appropriate in
	10	some cases, such as re-initializing (and maybe resetting). After such
	11	recovery, triggered by a fault report, there is no error.
	12
	13	In a similar way, sometimes a "fault" code just reports one defined
	14	result for an operation ... it doesn't indicate that anything is wrong
	15	at all, just that the outcome wasn't on the "golden path".
	16
	17	In short, your I2C driver code may need to know these codes in order
	18	to respond correctly. Other code may need to rely on YOUR code reporting
	19	the right fault code, so that it can (in turn) behave correctly.
	20
	21
	22	I2C and SMBus fault codes
	23	-------------------------
	24	These are returned as negative numbers from most calls, with zero or
	25	some positive number indicating a non-fault return. The specific
	26	numbers associated with these symbols differ between architectures,
	27	though most Linux systems use <asm-generic/errno*.h> numbering.
	28
	29	Note that the descriptions here are not exhaustive. There are other
	30	codes that may be returned, and other cases where these codes should
	31	be returned. However, drivers should not return other codes for these
	32	cases (unless the hardware doesn't provide unique fault reports).
	33
	34	Also, codes returned by adapter probe methods follow rules which are
	35	specific to their host bus (such as PCI, or the platform bus).
	36
	37
	38	EAGAIN
	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
	47	EBADMSG
	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
	56	EBUSY
	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
	62	EINVAL
	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
81fded1f DB	67	EIO
	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
	72	ENODEV
	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
	80	ENOMEM
	81	Returned by any component that can't allocate memory when
	82	it needs to do so.
	83
	84	ENXIO
	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
	93	EOPNOTSUPP
	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
	109	EPROTO
	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
	115	ETIMEDOUT
	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