1 ===================== 1 =====================
2 I2C/SMBUS Fault Codes 2 I2C/SMBUS Fault Codes
3 ===================== 3 =====================
4 4
5 This is a summary of the most important conven 5 This is a summary of the most important conventions for use of fault
6 codes in the I2C/SMBus stack. 6 codes in the I2C/SMBus stack.
7 7
8 8
9 A "Fault" is not always an "Error" 9 A "Fault" is not always an "Error"
10 ---------------------------------- 10 ----------------------------------
11 Not all fault reports imply errors; "page faul 11 Not all fault reports imply errors; "page faults" should be a familiar
12 example. Software often retries idempotent op 12 example. Software often retries idempotent operations after transient
13 faults. There may be fancier recovery schemes 13 faults. There may be fancier recovery schemes that are appropriate in
14 some cases, such as re-initializing (and maybe 14 some cases, such as re-initializing (and maybe resetting). After such
15 recovery, triggered by a fault report, there i 15 recovery, triggered by a fault report, there is no error.
16 16
17 In a similar way, sometimes a "fault" code jus 17 In a similar way, sometimes a "fault" code just reports one defined
18 result for an operation ... it doesn't indicat 18 result for an operation ... it doesn't indicate that anything is wrong
19 at all, just that the outcome wasn't on the "g 19 at all, just that the outcome wasn't on the "golden path".
20 20
21 In short, your I2C driver code may need to kno 21 In short, your I2C driver code may need to know these codes in order
22 to respond correctly. Other code may need to 22 to respond correctly. Other code may need to rely on YOUR code reporting
23 the right fault code, so that it can (in turn) 23 the right fault code, so that it can (in turn) behave correctly.
24 24
25 25
26 I2C and SMBus fault codes 26 I2C and SMBus fault codes
27 ------------------------- 27 -------------------------
28 These are returned as negative numbers from mo 28 These are returned as negative numbers from most calls, with zero or
29 some positive number indicating a non-fault re 29 some positive number indicating a non-fault return. The specific
30 numbers associated with these symbols differ b 30 numbers associated with these symbols differ between architectures,
31 though most Linux systems use <asm-generic/err 31 though most Linux systems use <asm-generic/errno*.h> numbering.
32 32
33 Note that the descriptions here are not exhaus 33 Note that the descriptions here are not exhaustive. There are other
34 codes that may be returned, and other cases wh 34 codes that may be returned, and other cases where these codes should
35 be returned. However, drivers should not retu 35 be returned. However, drivers should not return other codes for these
36 cases (unless the hardware doesn't provide uni 36 cases (unless the hardware doesn't provide unique fault reports).
37 37
38 Also, codes returned by adapter probe methods 38 Also, codes returned by adapter probe methods follow rules which are
39 specific to their host bus (such as PCI, or th 39 specific to their host bus (such as PCI, or the platform bus).
40 40
41 41
42 EAFNOSUPPORT <<
43 Returned by I2C adapters not supportin <<
44 they are requested to use such an addr <<
45 <<
46 EAGAIN 42 EAGAIN
47 Returned by I2C adapters when they los 43 Returned by I2C adapters when they lose arbitration in master
48 transmit mode: some other master was 44 transmit mode: some other master was transmitting different
49 data at the same time. 45 data at the same time.
50 46
51 Also returned when trying to invoke an 47 Also returned when trying to invoke an I2C operation in an
52 atomic context, when some task is alre 48 atomic context, when some task is already using that I2C bus
53 to execute some other operation. 49 to execute some other operation.
54 50
55 EBADMSG 51 EBADMSG
56 Returned by SMBus logic when an invali 52 Returned by SMBus logic when an invalid Packet Error Code byte
57 is received. This code is a CRC cover 53 is received. This code is a CRC covering all bytes in the
58 transaction, and is sent before the te 54 transaction, and is sent before the terminating STOP. This
59 fault is only reported on read transac 55 fault is only reported on read transactions; the SMBus slave
60 may have a way to report PEC mismatche 56 may have a way to report PEC mismatches on writes from the
61 host. Note that even if PECs are in u 57 host. Note that even if PECs are in use, you should not rely
62 on these as the only way to detect inc 58 on these as the only way to detect incorrect data transfers.
63 59
64 EBUSY 60 EBUSY
65 Returned by SMBus adapters when the bu 61 Returned by SMBus adapters when the bus was busy for longer
66 than allowed. This usually indicates 62 than allowed. This usually indicates some device (maybe the
67 SMBus adapter) needs some fault recove 63 SMBus adapter) needs some fault recovery (such as resetting),
68 or that the reset was attempted but fa 64 or that the reset was attempted but failed.
69 65
70 EINVAL 66 EINVAL
71 This rather vague error means an inval 67 This rather vague error means an invalid parameter has been
72 detected before any I/O operation was 68 detected before any I/O operation was started. Use a more
73 specific fault code when you can. 69 specific fault code when you can.
74 70
75 EIO 71 EIO
76 This rather vague error means somethin 72 This rather vague error means something went wrong when
77 performing an I/O operation. Use a mo 73 performing an I/O operation. Use a more specific fault
78 code when you can. 74 code when you can.
79 75
80 ENODEV 76 ENODEV
81 Returned by driver probe() methods. T 77 Returned by driver probe() methods. This is a bit more
82 specific than ENXIO, implying the prob 78 specific than ENXIO, implying the problem isn't with the
83 address, but with the device found the 79 address, but with the device found there. Driver probes
84 may verify the device returns *correct 80 may verify the device returns *correct* responses, and
85 return this as appropriate. (The driv 81 return this as appropriate. (The driver core will warn
86 about probe faults other than ENXIO an 82 about probe faults other than ENXIO and ENODEV.)
87 83
88 ENOMEM 84 ENOMEM
89 Returned by any component that can't a 85 Returned by any component that can't allocate memory when
90 it needs to do so. 86 it needs to do so.
91 87
92 ENXIO 88 ENXIO
93 Returned by I2C adapters to indicate t 89 Returned by I2C adapters to indicate that the address phase
94 of a transfer didn't get an ACK. Whil 90 of a transfer didn't get an ACK. While it might just mean
95 an I2C device was temporarily not resp 91 an I2C device was temporarily not responding, usually it
96 means there's nothing listening at tha 92 means there's nothing listening at that address.
97 93
98 Returned by driver probe() methods to 94 Returned by driver probe() methods to indicate that they
99 found no device to bind to. (ENODEV m 95 found no device to bind to. (ENODEV may also be used.)
100 96
101 EOPNOTSUPP 97 EOPNOTSUPP
102 Returned by an adapter when asked to p 98 Returned by an adapter when asked to perform an operation
103 that it doesn't, or can't, support. 99 that it doesn't, or can't, support.
104 100
105 For example, this would be returned wh 101 For example, this would be returned when an adapter that
106 doesn't support SMBus block transfers 102 doesn't support SMBus block transfers is asked to execute
107 one. In that case, the driver making 103 one. In that case, the driver making that request should
108 have verified that functionality was s 104 have verified that functionality was supported before it
109 made that block transfer request. 105 made that block transfer request.
110 106
111 Similarly, if an I2C adapter can't exe 107 Similarly, if an I2C adapter can't execute all legal I2C
112 messages, it should return this when a 108 messages, it should return this when asked to perform a
113 transaction it can't. (These limitati 109 transaction it can't. (These limitations can't be seen in
114 the adapter's functionality mask, sinc 110 the adapter's functionality mask, since the assumption is
115 that if an adapter supports I2C it sup 111 that if an adapter supports I2C it supports all of I2C.)
116 112
117 EPROTO 113 EPROTO
118 Returned when slave does not conform t 114 Returned when slave does not conform to the relevant I2C
119 or SMBus (or chip-specific) protocol s 115 or SMBus (or chip-specific) protocol specifications. One
120 case is when the length of an SMBus bl 116 case is when the length of an SMBus block data response
121 (from the SMBus slave) is outside the 117 (from the SMBus slave) is outside the range 1-32 bytes.
122 118
123 ESHUTDOWN 119 ESHUTDOWN
124 Returned when a transfer was requested 120 Returned when a transfer was requested using an adapter
125 which is already suspended. 121 which is already suspended.
126 122
127 ETIMEDOUT 123 ETIMEDOUT
128 This is returned by drivers when an op 124 This is returned by drivers when an operation took too much
129 time, and was aborted before it comple 125 time, and was aborted before it completed.
130 126
131 SMBus adapters may return it when an o 127 SMBus adapters may return it when an operation took more
132 time than allowed by the SMBus specifi 128 time than allowed by the SMBus specification; for example,
133 when a slave stretches clocks too far. 129 when a slave stretches clocks too far. I2C has no such
134 timeouts, but it's normal for I2C adap 130 timeouts, but it's normal for I2C adapters to impose some
135 arbitrary limits (much longer than SMB 131 arbitrary limits (much longer than SMBus!) too.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.