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