I2c — Requirements

Normative

Defines what a conformant I2C driver MUST do. Keywords per Requirement Keywords; conformance per Conformance. Requirements do not carry individual status — the set-level status applies to all of them. Signatures, error codes, and configuration properties are in the API Reference, Errors, and Configuration Reference pages. Cross-module rules (types, error model, naming, memory mapping) are in General.

Mandatory (MUST) - 23 Requirements

The conformance contract — an implementation MUST satisfy every requirement here.

Modes and event handling

CHI-I2C-MUST-01 — Controller mode

The driver MUST support operating a channel as an I2C controller, initiating write and read transactions to a 7-bit-addressed device.

CHI-I2C-MUST-02 — Target mode

The driver MUST support operating a channel as an I2C target, responding to a controller that addresses it with the channel’s configured address.

CHI-I2C-MUST-03 — Event handling mode

For each channel, event handling MUST be statically configurable as interrupt or polling. In interrupt mode I2c_Init MUST enable the interrupt and I2c_Interrupt MUST service it; in polling mode the interrupt MUST be disabled and I2c_PollFunction MUST service events.

State machine

CHI-I2C-MUST-04 — State after reset

After reset the driver MUST be in I2C_DRV_STATE_UNINIT with every channel in I2C_CH_STATE_UNINIT.

CHI-I2C-MUST-05 — State after initialization

I2c_Init MUST move the driver to I2C_DRV_STATE_INIT and every channel to I2C_CH_STATE_IDLE.

CHI-I2C-MUST-06 — State after de-initialization

I2c_DeInit MUST abort any ongoing transaction and return the driver to I2C_DRV_STATE_UNINIT.

CHI-I2C-MUST-07 — Controller channel state transitions

A controller channel MUST follow the controller-mode state machine in Concepts: IDLE → BUSY on a start transaction; BUSY → READY at transfer completion; READY → BUSY for a repeated START; READY → IDLE on STOP; BUSY → IDLE on error.

CHI-I2C-MUST-08 — Target channel state transitions

A target channel MUST follow the target-mode state machine: IDLE → READY on an address match; READY → BUSY after I2c_Callout_OnAddress returns; BUSY → IDLE at completion or on error.

Initialization and shutdown

CHI-I2C-MUST-09 — Initialization

I2c_Init MUST initialize driver state and the hardware per the configuration. configPtr MUST be NULL_PTR. A target channel MUST begin accepting its configured address.

CHI-I2C-MUST-10 — De-initialization

I2c_DeInit MUST abort ongoing transfers and de-initialize the hardware.

Transactions

CHI-I2C-MUST-11 — Start a transmit transaction

I2c_StartTxTransaction MUST, on a controller channel, initiate a write (START, address, data); on a target channel it MUST stage the response data. It MUST support a repeated START when a new transaction is started from within a completion callout before STOP.

CHI-I2C-MUST-12 — Start a receive transaction

I2c_StartRxTransaction MUST, on a controller channel, initiate a read; on a target channel it MUST stage the receive buffer. It MUST support a repeated START as above.

CHI-I2C-MUST-13 — Data transfer

During interrupt or poll handling the driver MUST transfer the bytes to/from the buffers supplied to the start call. The caller’s buffer MUST remain valid until the matching completion callout fires; the driver MUST NOT rely on it afterwards.

CHI-I2C-MUST-14 — Controller completion and bus release

On completing a controller transfer the driver MUST move the channel to READY and call I2c_Callout_OnTransmission / I2c_Callout_OnReception. If no new transaction is started in the callout it MUST issue STOP and return the channel to IDLE; otherwise it MUST issue a repeated START.

Target-mode handling

CHI-I2C-MUST-15 — Target address and completion notification

On an address match the driver MUST report I2c_Callout_OnAddress with the controller’s direction, and on completion it MUST call I2c_Callout_OnReception (controller write) or I2c_Callout_OnTransmission (controller read).

CHI-I2C-MUST-16 — Target over-request handling

If the integration code stages no response in I2c_Callout_OnAddress, the driver MUST transmit the channel’s configured default_data on a controller read, and MUST accept and discard the bytes on a controller write.

Errors, status, and scheduling

CHI-I2C-MUST-17 — Error handling

On a NACK the driver MUST report I2c_Callout_OnError with I2C_ERR_NACK_RECEIVED. On a bus or arbitration failure it MUST report the corresponding runtime error via LogM_Report and return the channel to a safe state.

CHI-I2C-MUST-18 — Poll function

Where a module provides I2c_PollFunction it MUST handle the same events as I2c_Interrupt for polled channels, and MUST be provided regardless of configuration (it MAY be empty when all channels are interrupt-driven).

CHI-I2C-MUST-19 — Channel state query

I2c_GetChannelState MUST return the current state of the requested channel.

CHI-I2C-MUST-20 — Development error detection

When development error reporting is enabled, each API MUST detect the conditions listed in Errors and report them via LogM_Report (CHI-GEN-MUST-10).

Types, callouts, and configuration

CHI-I2C-MUST-21 — Callout notifications

The driver MUST call I2c_Callout_OnReception, I2c_Callout_OnTransmission, I2c_Callout_OnError, and (target mode) I2c_Callout_OnAddress with the parameters and at the points defined in API Reference.

CHI-I2C-MUST-22 — Public types and error identifiers

The driver MUST provide I2c_ConfigType, I2c_DirectionType, I2c_ChannelStateType, I2c_ErrorType, the development and runtime error identifiers, and I2C_ADDR_UNSPECIFIED as defined in API Reference, and MUST use the shared type system from General (CHI-GEN-MUST-09).

CHI-I2C-MUST-23 — Configuration model

The driver MUST support the configuration model in Configuration Reference — a General section and a ConfigSet with ControllerChannel and TargetChannel entries — following the common model in General (CHI-GEN-MUST-12).