API Reference

Normative

The I2C driver API contract. A conformant driver MUST provide these types and functions with the behavior described. Function and type signatures are extracted from the driver headers with Doxygen/Breathe; only the interrupt handler is hand-framed, because its name is vendor-specific. Keywords per Requirement Keywords; behavioral rules in I2c — Requirements; error codes in Errors.

Data types at a glance

Type	Kind	Purpose
I2c_ConfigType	struct	Root configuration structure (build-time; `I2c_Init` takes `NULL_PTR`).
I2c_DirectionType	enum	Transfer direction (controller write / read).
I2c_ChannelStateType	enum	Channel state (UNINIT / IDLE / READY / BUSY).
I2c_ErrorType	enum	Transfer error reported via `I2c_Callout_OnError` (e.g. NACK).

API at a glance

Function	Group	Purpose
I2c_Init	Initialization and shutdown	Initialize the driver and every channel.
I2c_DeInit	Initialization and shutdown	Abort transfers and de-initialize the driver.
I2c_StartTxTransaction	Transactions	Start (controller) or stage (target) a write.
I2c_StartRxTransaction	Transactions	Start (controller) or stage (target) a read.
I2c_GetChannelState	Status and scheduling	Read a channel’s current state.
I2c_PollFunction	Status and scheduling	Service events for polled channels.
I2c_Interrupt	Status and scheduling	Driver interrupt service routine.

Callouts and expected interfaces at a glance

The functions the integrator MUST provide (CHI-I2C-MUST-21); see the Callouts group below. I2cDrv has no upper-layer interface stack, so it reports its events through callouts that the integrator implements in the generated I2c_Callout_Stubs.c (see The Callout Stub File).

Function	Kind	Purpose
I2c_Callout_OnReception	Callout	A read transaction completed.
I2c_Callout_OnTransmission	Callout	A write transaction completed.
I2c_Callout_OnError	Callout	A transfer error occurred (e.g. NACK).
I2c_Callout_OnAddress	Callout	Target mode: this channel’s address was matched.
LogM_Report	Common	Reports development / runtime errors with a log level.
`<Mip>_EnterCriticalSection` / `<Mip>_ExitCriticalSection`	Common (optional)	Bracket sections requiring exclusive access — see critical sections.

Transactions

I2c_StartTxTransaction

Std_ReturnType I2c_StartTxTransaction(uint8 channelId, uint8 deviceAddr, const uint8 *txDataPtr, uint16 txDataLength)

For Controller Mode channel, initiates the transaction with the given data and deviceAddr. For Target Mode channel, setup TX data with the given data for Controller Node request.

Sync/Async:

Asynchronous

Reentrancy:

Conditionally reentrant (reentrant when called with different channelIds)

Service ID [hex]:

0x02

Development error(s):

I2C_DEVERR_UNINIT Called when the internal state is I2C_CH_STATE_UNINIT.
I2C_DEVERR_PARAM_CHANNELID channelId is out of range from configured channelIds.
I2C_DEVERR_PARAM_POINTER txDataPtr is null pointer.
I2C_DEVERR_PARAM_DATA_LENGTH txDataLength is 0.
I2C_DEVERR_INVALID_CH_STATE Controller channel: Called when the internal state is NOT I2C_CH_STATE_IDLE or I2C_CH_STATE_READY.
I2C_DEVERR_INVALID_CH_STATE Target Mode channel: Called when the internal state is NOT I2C_CH_STATE_READY.
I2C_DEVERR_INVALID_DIRECTION Only for Target Mode channel: Called when the direction of I2c_Callout_OnAddress is NOT I2C_DIR_CONTROLLER_READ.

Parameters:

channelId – [in] ID of the I2C channel to be addressed.
deviceAddr – [in]
The Target Node device address. I2C_ADDR_UNSPECIFIED is set for the channel in Target Mode.

Note: If the channel is the target node, I2cDrv should not check the deviceAddr parameter. Even if deviceAddr is not I2C_ADDR_UNSPECIFIED, I2cDrv will not log a development error.
txDataPtr – [in] Buffer address for transmit data.
txDataLength – [in] Specifies the buffer length. Must be > 0.

Return values:

E_OK – Request has been accepted.
E_NOT_OK – Development error occurred.

When to call: on an IDLE controller channel to start a write, or from I2c_Callout_OnAddress on a target channel (with I2C_ADDR_UNSPECIFIED) to stage the response. Returns: E_OK if accepted, else E_NOT_OK (development error). The caller MUST keep txDataPtr valid until completion. Errors: see Errors. Available via: I2c.h

I2c_StartRxTransaction

Std_ReturnType I2c_StartRxTransaction(uint8 channelId, uint8 deviceAddr, uint8 *rxDataPtr, uint16 rxDataLength)

For Controller Mode channel, initiates the transaction with the given data and deviceAddr. For Target Mode channel, setup RX with the given data for Controller Node request.

Sync/Async:

Asynchronous

Reentrancy:

Conditionally reentrant (reentrant when called with different channelIds)

Service ID [hex]:

0x03

Development error(s):

I2C_DEVERR_UNINIT Called when the internal state is I2C_CH_STATE_UNINIT.
I2C_DEVERR_PARAM_CHANNELID channelId is out of range from configured channelIds.
I2C_DEVERR_PARAM_POINTER rxDataPtr is null pointer.
I2C_DEVERR_PARAM_DATA_LENGTH rxDataLength is 0.
I2C_DEVERR_INVALID_CH_STATE Controller channel: Called when the internal state is NOT I2C_CH_STATE_IDLE or I2C_CH_STATE_READY.
I2C_DEVERR_INVALID_CH_STATE Target Mode channel: Called when the internal state is NOT I2C_CH_STATE_READY.
I2C_DEVERR_INVALID_DIRECTION Only for Target Mode channel: Called when the direction of I2c_Callout_OnAddress is NOT I2C_DIR_CONTROLLER_WRITE.

Parameters:

channelId – [in] ID of the I2C channel to be addressed.
deviceAddr – [in]
The Target Node device address. I2C_ADDR_UNSPECIFIED is set for the channel in Target Mode.

Note: If the channel is the target node, I2cDrv should not check the deviceAddr parameter. Even if deviceAddr is not I2C_ADDR_UNSPECIFIED, I2cDrv will not log a development error.
rxDataPtr – [in] Buffer address for received data.
rxDataLength – [in] Specifies the buffer length. Must be > 0.

Return values:

E_OK – Request has been accepted.
E_NOT_OK – Development error occurred.

When to call: on an IDLE controller channel to start a read, or from I2c_Callout_OnAddress on a target channel (with I2C_ADDR_UNSPECIFIED). The caller MUST keep rxDataPtr valid until completion. Errors: see Errors. Available via: I2c.h

Callouts the integrator provides

The driver calls these callouts to report events. The integrator MUST provide them (CHI-I2C-MUST-21) by filling in the matching user code block in I2c_Callout_Stubs.c (see The Callout Stub File); the prototypes are declared in I2c.h. LogM_Report and the critical-section services are documented in the general reference.

I2c_Callout_OnReception

void I2c_Callout_OnReception(uint8 channelId, uint16 length)

Indicates completion of RX transaction. This function will be called by I2c_Interrupt and I2c_PollFunction when the event is detected. For Controller Mode channel: If I2c_StartTxTransaction or I2c_StartRxTransaction is called at this interface, I2cDrv will sends START condition into the bus without sending STOP condition (REPEATED_START). If neither of the start transaction function is not called, then I2cDrv will send STOP condition.

Sync/Async:: Synchronous
Reentrancy:: Conditionally reentrant (reentrant when called with different channelIds)

Parameters:

channelId – [in] ID of the I2C channel which informs the event.
length – [in] Inform transferred buffer length. In Target Mode and if Controller Node sends more data than RX buffer length, the length is saturated to the buffer length and data more than the buffer length is ignored.

Returns:

None.

A read transaction completed; length bytes were received. Available via: I2c.h; implement it in I2c_Callout_Stubs.c.

I2c_Callout_OnTransmission

void I2c_Callout_OnTransmission(uint8 channelId, uint16 length)

Indicates completion of TX transaction. This function will be called by I2c_Interrupt and I2c_PollFunction when the event is detected. For Controller Mode channel: RESTRICTED Chiisai HAL I2C Driver Specification If I2c_StartTxTransaction or I2c_StartRxTransaction is called at this interface, I2cDrv will sends START condition into the bus without sending STOP condition (REPEATED_START). If neither of the start transaction function is not called, then I2cDrv will send STOP condition.

Sync/Async:: Synchronous
Reentrancy:: Conditionally reentrant (reentrant when called with different channelIds)

Parameters:

channelId – [in] ID of the I2C channel which informs the event.
length – [in] Specifies the transmitted data length. If the Controller Node has sent more data than fits in the Target Node’s buffer, the length is truncated at the buffer length.

Returns:

None.

A write transaction completed; length bytes were sent. Available via: I2c.h; implement it in I2c_Callout_Stubs.c.

I2c_Callout_OnError

void I2c_Callout_OnError(uint8 channelId, I2c_ErrorType error)

Indicates error occurrence during transaction. This function will be called by I2c_Interrupt and I2c_PollFunction when the event is detected.

Sync/Async:: Synchronous
Reentrancy:: Conditionally reentrant (reentrant when called with different channelIds)

Parameters:

channelId – [in] ID of the I2C channel which informs the event.
error – [in] Indicates the error kind.

Returns:

None.

A transfer error occurred (e.g. I2C_ERR_NACK_RECEIVED). Available via: I2c.h; implement it in I2c_Callout_Stubs.c.

I2c_Callout_OnAddress

void I2c_Callout_OnAddress(uint8 channelId, I2c_DirectionType direction)

Target Mode only. Indicates the reception of an address that is tied to the channel. This function will be called by I2c_Interrupt and I2c_PollFunction when the received address matches the Target Node channel.

Sync/Async:: Synchronous
Reentrancy:: Conditionally reentrant (reentrant when called with different channelIds)

Parameters:

channelId – [in] ID of the I2C channel which informs the event.
direction – [in] Indicates requested direction (read/write).

Returns:

None.

Target mode only: this channel’s address was matched; direction is the controller’s intent. Available via: I2c.h; implement it in I2c_Callout_Stubs.c.