forked from Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
131 lines
5.1 KiB
131 lines
5.1 KiB
===================== |
|
I2C/SMBUS Fault Codes |
|
===================== |
|
|
|
This is a summary of the most important conventions for use of fault |
|
codes in the I2C/SMBus stack. |
|
|
|
|
|
A "Fault" is not always an "Error" |
|
---------------------------------- |
|
Not all fault reports imply errors; "page faults" should be a familiar |
|
example. Software often retries idempotent operations after transient |
|
faults. There may be fancier recovery schemes that are appropriate in |
|
some cases, such as re-initializing (and maybe resetting). After such |
|
recovery, triggered by a fault report, there is no error. |
|
|
|
In a similar way, sometimes a "fault" code just reports one defined |
|
result for an operation ... it doesn't indicate that anything is wrong |
|
at all, just that the outcome wasn't on the "golden path". |
|
|
|
In short, your I2C driver code may need to know these codes in order |
|
to respond correctly. Other code may need to rely on YOUR code reporting |
|
the right fault code, so that it can (in turn) behave correctly. |
|
|
|
|
|
I2C and SMBus fault codes |
|
------------------------- |
|
These are returned as negative numbers from most calls, with zero or |
|
some positive number indicating a non-fault return. The specific |
|
numbers associated with these symbols differ between architectures, |
|
though most Linux systems use <asm-generic/errno*.h> numbering. |
|
|
|
Note that the descriptions here are not exhaustive. There are other |
|
codes that may be returned, and other cases where these codes should |
|
be returned. However, drivers should not return other codes for these |
|
cases (unless the hardware doesn't provide unique fault reports). |
|
|
|
Also, codes returned by adapter probe methods follow rules which are |
|
specific to their host bus (such as PCI, or the platform bus). |
|
|
|
|
|
EAGAIN |
|
Returned by I2C adapters when they lose arbitration in master |
|
transmit mode: some other master was transmitting different |
|
data at the same time. |
|
|
|
Also returned when trying to invoke an I2C operation in an |
|
atomic context, when some task is already using that I2C bus |
|
to execute some other operation. |
|
|
|
EBADMSG |
|
Returned by SMBus logic when an invalid Packet Error Code byte |
|
is received. This code is a CRC covering all bytes in the |
|
transaction, and is sent before the terminating STOP. This |
|
fault is only reported on read transactions; the SMBus slave |
|
may have a way to report PEC mismatches on writes from the |
|
host. Note that even if PECs are in use, you should not rely |
|
on these as the only way to detect incorrect data transfers. |
|
|
|
EBUSY |
|
Returned by SMBus adapters when the bus was busy for longer |
|
than allowed. This usually indicates some device (maybe the |
|
SMBus adapter) needs some fault recovery (such as resetting), |
|
or that the reset was attempted but failed. |
|
|
|
EINVAL |
|
This rather vague error means an invalid parameter has been |
|
detected before any I/O operation was started. Use a more |
|
specific fault code when you can. |
|
|
|
EIO |
|
This rather vague error means something went wrong when |
|
performing an I/O operation. Use a more specific fault |
|
code when you can. |
|
|
|
ENODEV |
|
Returned by driver probe() methods. This is a bit more |
|
specific than ENXIO, implying the problem isn't with the |
|
address, but with the device found there. Driver probes |
|
may verify the device returns *correct* responses, and |
|
return this as appropriate. (The driver core will warn |
|
about probe faults other than ENXIO and ENODEV.) |
|
|
|
ENOMEM |
|
Returned by any component that can't allocate memory when |
|
it needs to do so. |
|
|
|
ENXIO |
|
Returned by I2C adapters to indicate that the address phase |
|
of a transfer didn't get an ACK. While it might just mean |
|
an I2C device was temporarily not responding, usually it |
|
means there's nothing listening at that address. |
|
|
|
Returned by driver probe() methods to indicate that they |
|
found no device to bind to. (ENODEV may also be used.) |
|
|
|
EOPNOTSUPP |
|
Returned by an adapter when asked to perform an operation |
|
that it doesn't, or can't, support. |
|
|
|
For example, this would be returned when an adapter that |
|
doesn't support SMBus block transfers is asked to execute |
|
one. In that case, the driver making that request should |
|
have verified that functionality was supported before it |
|
made that block transfer request. |
|
|
|
Similarly, if an I2C adapter can't execute all legal I2C |
|
messages, it should return this when asked to perform a |
|
transaction it can't. (These limitations can't be seen in |
|
the adapter's functionality mask, since the assumption is |
|
that if an adapter supports I2C it supports all of I2C.) |
|
|
|
EPROTO |
|
Returned when slave does not conform to the relevant I2C |
|
or SMBus (or chip-specific) protocol specifications. One |
|
case is when the length of an SMBus block data response |
|
(from the SMBus slave) is outside the range 1-32 bytes. |
|
|
|
ESHUTDOWN |
|
Returned when a transfer was requested using an adapter |
|
which is already suspended. |
|
|
|
ETIMEDOUT |
|
This is returned by drivers when an operation took too much |
|
time, and was aborted before it completed. |
|
|
|
SMBus adapters may return it when an operation took more |
|
time than allowed by the SMBus specification; for example, |
|
when a slave stretches clocks too far. I2C has no such |
|
timeouts, but it's normal for I2C adapters to impose some |
|
arbitrary limits (much longer than SMBus!) too.
|
|
|