Documentation/i2c/fault-codes.rst

Source file repositories/reference/linux-study-clean/Documentation/i2c/fault-codes.rst

File Facts

System
Linux kernel
Corpus path
Documentation/i2c/fault-codes.rst
Extension
.rst
Size
5326 bytes
Lines
136
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

=====================
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).


EAFNOSUPPORT
	Returned by I2C adapters not supporting 10 bit addresses when
	they are requested to use such an address.

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

Annotation

Implementation Notes