136 lines · plain
1=====================2I2C/SMBUS Fault Codes3=====================4 5This is a summary of the most important conventions for use of fault6codes 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 familiar12example. Software often retries idempotent operations after transient13faults. There may be fancier recovery schemes that are appropriate in14some cases, such as re-initializing (and maybe resetting). After such15recovery, triggered by a fault report, there is no error.16 17In a similar way, sometimes a "fault" code just reports one defined18result for an operation ... it doesn't indicate that anything is wrong19at 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 order22to respond correctly. Other code may need to rely on YOUR code reporting23the right fault code, so that it can (in turn) behave correctly.24 25 26I2C and SMBus fault codes27-------------------------28These are returned as negative numbers from most calls, with zero or29some positive number indicating a non-fault return. The specific30numbers 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 other34codes that may be returned, and other cases where these codes should35be returned. However, drivers should not return other codes for these36cases (unless the hardware doesn't provide unique fault reports).37 38Also, codes returned by adapter probe methods follow rules which are39specific to their host bus (such as PCI, or the platform bus).40 41 42EAFNOSUPPORT43 Returned by I2C adapters not supporting 10 bit addresses when44 they are requested to use such an address.45 46EAGAIN47 Returned by I2C adapters when they lose arbitration in master48 transmit mode: some other master was transmitting different49 data at the same time.50 51 Also returned when trying to invoke an I2C operation in an52 atomic context, when some task is already using that I2C bus53 to execute some other operation.54 55EBADMSG56 Returned by SMBus logic when an invalid Packet Error Code byte57 is received. This code is a CRC covering all bytes in the58 transaction, and is sent before the terminating STOP. This59 fault is only reported on read transactions; the SMBus slave60 may have a way to report PEC mismatches on writes from the61 host. Note that even if PECs are in use, you should not rely62 on these as the only way to detect incorrect data transfers.63 64EBUSY65 Returned by SMBus adapters when the bus was busy for longer66 than allowed. This usually indicates some device (maybe the67 SMBus adapter) needs some fault recovery (such as resetting),68 or that the reset was attempted but failed.69 70EINVAL71 This rather vague error means an invalid parameter has been72 detected before any I/O operation was started. Use a more73 specific fault code when you can.74 75EIO76 This rather vague error means something went wrong when77 performing an I/O operation. Use a more specific fault78 code when you can.79 80ENODEV81 Returned by driver probe() methods. This is a bit more82 specific than ENXIO, implying the problem isn't with the83 address, but with the device found there. Driver probes84 may verify the device returns *correct* responses, and85 return this as appropriate. (The driver core will warn86 about probe faults other than ENXIO and ENODEV.)87 88ENOMEM89 Returned by any component that can't allocate memory when90 it needs to do so.91 92ENXIO93 Returned by I2C adapters to indicate that the address phase94 of a transfer didn't get an ACK. While it might just mean95 an I2C device was temporarily not responding, usually it96 means there's nothing listening at that address.97 98 Returned by driver probe() methods to indicate that they99 found no device to bind to. (ENODEV may also be used.)100 101EOPNOTSUPP102 Returned by an adapter when asked to perform an operation103 that it doesn't, or can't, support.104 105 For example, this would be returned when an adapter that106 doesn't support SMBus block transfers is asked to execute107 one. In that case, the driver making that request should108 have verified that functionality was supported before it109 made that block transfer request.110 111 Similarly, if an I2C adapter can't execute all legal I2C112 messages, it should return this when asked to perform a113 transaction it can't. (These limitations can't be seen in114 the adapter's functionality mask, since the assumption is115 that if an adapter supports I2C it supports all of I2C.)116 117EPROTO118 Returned when slave does not conform to the relevant I2C119 or SMBus (or chip-specific) protocol specifications. One120 case is when the length of an SMBus block data response121 (from the SMBus slave) is outside the range 1-32 bytes.122 123ESHUTDOWN124 Returned when a transfer was requested using an adapter125 which is already suspended.126 127ETIMEDOUT128 This is returned by drivers when an operation took too much129 time, and was aborted before it completed.130 131 SMBus adapters may return it when an operation took more132 time than allowed by the SMBus specification; for example,133 when a slave stretches clocks too far. I2C has no such134 timeouts, but it's normal for I2C adapters to impose some135 arbitrary limits (much longer than SMBus!) too.136