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