fault-codes.rst 5.1 KB

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