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