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 42 EAFNOSUPPORT
43 Returned by I2C adapters not supportin 43 Returned by I2C adapters not supporting 10 bit addresses when
44 they are requested to use such an addr 44 they are requested to use such an address.
45 45
46 EAGAIN 46 EAGAIN
47 Returned by I2C adapters when they los 47 Returned by I2C adapters when they lose arbitration in master
48 transmit mode: some other master was 48 transmit mode: some other master was transmitting different
49 data at the same time. 49 data at the same time.
50 50
51 Also returned when trying to invoke an 51 Also returned when trying to invoke an I2C operation in an
52 atomic context, when some task is alre 52 atomic context, when some task is already using that I2C bus
53 to execute some other operation. 53 to execute some other operation.
54 54
55 EBADMSG 55 EBADMSG
56 Returned by SMBus logic when an invali 56 Returned by SMBus logic when an invalid Packet Error Code byte
57 is received. This code is a CRC cover 57 is received. This code is a CRC covering all bytes in the
58 transaction, and is sent before the te 58 transaction, and is sent before the terminating STOP. This
59 fault is only reported on read transac 59 fault is only reported on read transactions; the SMBus slave
60 may have a way to report PEC mismatche 60 may have a way to report PEC mismatches on writes from the
61 host. Note that even if PECs are in u 61 host. Note that even if PECs are in use, you should not rely
62 on these as the only way to detect inc 62 on these as the only way to detect incorrect data transfers.
63 63
64 EBUSY 64 EBUSY
65 Returned by SMBus adapters when the bu 65 Returned by SMBus adapters when the bus was busy for longer
66 than allowed. This usually indicates 66 than allowed. This usually indicates some device (maybe the
67 SMBus adapter) needs some fault recove 67 SMBus adapter) needs some fault recovery (such as resetting),
68 or that the reset was attempted but fa 68 or that the reset was attempted but failed.
69 69
70 EINVAL 70 EINVAL
71 This rather vague error means an inval 71 This rather vague error means an invalid parameter has been
72 detected before any I/O operation was 72 detected before any I/O operation was started. Use a more
73 specific fault code when you can. 73 specific fault code when you can.
74 74
75 EIO 75 EIO
76 This rather vague error means somethin 76 This rather vague error means something went wrong when
77 performing an I/O operation. Use a mo 77 performing an I/O operation. Use a more specific fault
78 code when you can. 78 code when you can.
79 79
80 ENODEV 80 ENODEV
81 Returned by driver probe() methods. T 81 Returned by driver probe() methods. This is a bit more
82 specific than ENXIO, implying the prob 82 specific than ENXIO, implying the problem isn't with the
83 address, but with the device found the 83 address, but with the device found there. Driver probes
84 may verify the device returns *correct 84 may verify the device returns *correct* responses, and
85 return this as appropriate. (The driv 85 return this as appropriate. (The driver core will warn
86 about probe faults other than ENXIO an 86 about probe faults other than ENXIO and ENODEV.)
87 87
88 ENOMEM 88 ENOMEM
89 Returned by any component that can't a 89 Returned by any component that can't allocate memory when
90 it needs to do so. 90 it needs to do so.
91 91
92 ENXIO 92 ENXIO
93 Returned by I2C adapters to indicate t 93 Returned by I2C adapters to indicate that the address phase
94 of a transfer didn't get an ACK. Whil 94 of a transfer didn't get an ACK. While it might just mean
95 an I2C device was temporarily not resp 95 an I2C device was temporarily not responding, usually it
96 means there's nothing listening at tha 96 means there's nothing listening at that address.
97 97
98 Returned by driver probe() methods to 98 Returned by driver probe() methods to indicate that they
99 found no device to bind to. (ENODEV m 99 found no device to bind to. (ENODEV may also be used.)
100 100
101 EOPNOTSUPP 101 EOPNOTSUPP
102 Returned by an adapter when asked to p 102 Returned by an adapter when asked to perform an operation
103 that it doesn't, or can't, support. 103 that it doesn't, or can't, support.
104 104
105 For example, this would be returned wh 105 For example, this would be returned when an adapter that
106 doesn't support SMBus block transfers 106 doesn't support SMBus block transfers is asked to execute
107 one. In that case, the driver making 107 one. In that case, the driver making that request should
108 have verified that functionality was s 108 have verified that functionality was supported before it
109 made that block transfer request. 109 made that block transfer request.
110 110
111 Similarly, if an I2C adapter can't exe 111 Similarly, if an I2C adapter can't execute all legal I2C
112 messages, it should return this when a 112 messages, it should return this when asked to perform a
113 transaction it can't. (These limitati 113 transaction it can't. (These limitations can't be seen in
114 the adapter's functionality mask, sinc 114 the adapter's functionality mask, since the assumption is
115 that if an adapter supports I2C it sup 115 that if an adapter supports I2C it supports all of I2C.)
116 116
117 EPROTO 117 EPROTO
118 Returned when slave does not conform t 118 Returned when slave does not conform to the relevant I2C
119 or SMBus (or chip-specific) protocol s 119 or SMBus (or chip-specific) protocol specifications. One
120 case is when the length of an SMBus bl 120 case is when the length of an SMBus block data response
121 (from the SMBus slave) is outside the 121 (from the SMBus slave) is outside the range 1-32 bytes.
122 122
123 ESHUTDOWN 123 ESHUTDOWN
124 Returned when a transfer was requested 124 Returned when a transfer was requested using an adapter
125 which is already suspended. 125 which is already suspended.
126 126
127 ETIMEDOUT 127 ETIMEDOUT
128 This is returned by drivers when an op 128 This is returned by drivers when an operation took too much
129 time, and was aborted before it comple 129 time, and was aborted before it completed.
130 130
131 SMBus adapters may return it when an o 131 SMBus adapters may return it when an operation took more
132 time than allowed by the SMBus specifi 132 time than allowed by the SMBus specification; for example,
133 when a slave stretches clocks too far. 133 when a slave stretches clocks too far. I2C has no such
134 timeouts, but it's normal for I2C adap 134 timeouts, but it's normal for I2C adapters to impose some
135 arbitrary limits (much longer than SMB 135 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.