About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / i2c / fault-codes




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:03 EST.

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	
67		One example would be a driver trying an SMBus Block Write
68		with block size outside the range of 1-32 bytes.
69	
70	EIO
71		This rather vague error means something went wrong when
72		performing an I/O operation.  Use a more specific fault
73		code when you can.
74	
75	ENODEV
76		Returned by driver probe() methods.  This is a bit more
77		specific than ENXIO, implying the problem isn't with the
78		address, but with the device found there.  Driver probes
79		may verify the device returns *correct* responses, and
80		return this as appropriate.  (The driver core will warn
81		about probe faults other than ENXIO and ENODEV.)
82	
83	ENOMEM
84		Returned by any component that can't allocate memory when
85		it needs to do so.
86	
87	ENXIO
88		Returned by I2C adapters to indicate that the address phase
89		of a transfer didn't get an ACK.  While it might just mean
90		an I2C device was temporarily not responding, usually it
91		means there's nothing listening at that address.
92	
93		Returned by driver probe() methods to indicate that they
94		found no device to bind to.  (ENODEV may also be used.)
95	
96	EOPNOTSUPP
97		Returned by an adapter when asked to perform an operation
98		that it doesn't, or can't, support.
99	
100		For example, this would be returned when an adapter that
101		doesn't support SMBus block transfers is asked to execute
102		one.  In that case, the driver making that request should
103		have verified that functionality was supported before it
104		made that block transfer request.
105	
106		Similarly, if an I2C adapter can't execute all legal I2C
107		messages, it should return this when asked to perform a
108		transaction it can't.  (These limitations can't be seen in
109		the adapter's functionality mask, since the assumption is
110		that if an adapter supports I2C it supports all of I2C.)
111	
112	EPROTO
113		Returned when slave does not conform to the relevant I2C
114		or SMBus (or chip-specific) protocol specifications.  One
115		case is when the length of an SMBus block data response
116		(from the SMBus slave) is outside the range 1-32 bytes.
117	
118	ETIMEDOUT
119		This is returned by drivers when an operation took too much
120		time, and was aborted before it completed.
121	
122		SMBus adapters may return it when an operation took more
123		time than allowed by the SMBus specification; for example,
124		when a slave stretches clocks too far.  I2C has no such
125		timeouts, but it's normal for I2C adapters to impose some
126		arbitrary limits (much longer than SMBus!) too.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.