Errors

Normative

The error and return codes a conformant I2C driver reports. Development errors are only raised when development error reporting is enabled (see enable_development_error_reporting in Configuration Reference). Governed by CHI-I2C-MUST-20 and CHI-I2C-MUST-22 in I2c — Requirements.

Development errors

When development error reporting is enabled, each API detects the conditions below and raises the listed error via LogM_Report with development-error level.

Development errors by API

API	Condition	Error id
`I2c_Init`	Driver not in `I2C_DRV_STATE_UNINIT`	`I2C_DEVERR_INVALID_CH_STATE`
`I2c_Init`	`configPtr` is not `NULL_PTR`	`I2C_DEVERR_PARAM_POINTER`
`I2c_StartTxTransaction` / `I2c_StartRxTransaction`	Driver not initialized	`I2C_DEVERR_UNINIT`
`I2c_StartTxTransaction` / `I2c_StartRxTransaction` / `I2c_GetChannelState`	`channelId` out of range	`I2C_DEVERR_PARAM_CHANNELID`
`I2c_StartTxTransaction` / `I2c_StartRxTransaction`	Null data pointer	`I2C_DEVERR_PARAM_POINTER`
`I2c_StartTxTransaction` / `I2c_StartRxTransaction`	Invalid data length	`I2C_DEVERR_PARAM_DATA_LENGTH`
`I2c_StartTxTransaction` / `I2c_StartRxTransaction`	Called in an invalid channel state	`I2C_DEVERR_INVALID_CH_STATE`
`I2c_StartTxTransaction` / `I2c_StartRxTransaction` (target)	Direction opposite to the controller’s request	`I2C_DEVERR_INVALID_DIRECTION`

Development error code group

Development error type

Defines

I2C_DEVERR_UNINIT (1U): API service called without initialization.

I2C_DEVERR_PARAM_CHANNELID (2U): API service called with invalid channelId

I2C_DEVERR_PARAM_POINTER (3U): API service called with invalid pointer parameter

I2C_DEVERR_PARAM_DATA_LENGTH (4U): API service called with invalid data length parameter

I2C_DEVERR_INVALID_CH_STATE (5U): API service called in invalid state

I2C_DEVERR_INVALID_DIRECTION (6U): Target Mode only. I2c_StartTxTransaction/I2c_StartRxTransaction is called opposite direction of Controller Node request.

Available via: I2c_DriverTypes.h. Vendor-specific error definitions MUST be provided via I2c.h instead.

Runtime errors

Runtime errors are reported via LogM_Report with runtime-error level.

Runtime error code group

Error id	Reported when
`I2C_RTERR_BUS_FAILURE`	A bus failure is detected (e.g. SCL stuck low).
`I2C_RTERR_ARBITRATION_FAILURE`	The controller loses arbitration (e.g. SDA stuck low).

Specifies error types which are logged via LogM_Report with log level runtime error.

Defines

I2C_RTERR_BUS_FAILURE (1U): Any of bus failure. e.g. SCL line is stuck low due to clock stretching.

I2C_RTERR_ARBITRATION_FAILURE (2U): Error if the controller loses arbitration. This usually happens if the SDA is stuck low.

Available via: I2c_DriverTypes.h.

Transfer errors

Errors detected during a transfer are reported to the integration code via the I2c_Callout_OnError(channelId, error) callout with a value of I2c_ErrorType.

I2c_ErrorType values

Error id	Reported when
`I2C_ERR_NACK_RECEIVED`	The addressed device (or a data byte) was not acknowledged.