mirror of
https://github.com/torvalds/linux.git
synced 2024-12-05 02:23:16 +00:00
9ac6cb5fbb
A few drivers open code the handling of suspended adapters. It could be handled by the core, though, to ensure generic handling. This patch adds the flag and accessor functions. The usage of these helpers is optional, though. See the kerneldoc in this patch. Using the new flag, we now reject further transfers if the adapter is already marked suspended. Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com> Signed-off-by: Wolfram Sang <wsa@the-dreams.de>
129 lines
5.0 KiB
Plaintext
129 lines
5.0 KiB
Plaintext
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.
|
|
|