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