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