ra8_i3c_i2c_internal.h File Reference

Test-access surface for ra8_i3c_i2c internal helpers (MC/DC). More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_i3c_i2c.h"
#include "ra8_i3c_i2c_regs.h"

Include dependency graph for ra8_i3c_i2c_internal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ra8_i3c_i2c_state_t
	Per-channel dispatch state shared across the driver's TUs. More...

Functions
void	priv_i3c_i2c_start (volatile r_i3c_i2c_regs_t *reg)
	Issue a START condition on the given channel registers.
void	priv_i3c_i2c_stop (volatile r_i3c_i2c_regs_t *reg)
	Issue a STOP condition and clear the prior STOP-detect flag.
void	priv_i3c_i2c_clear_bst (volatile r_i3c_i2c_regs_t *reg)
	Clear all latched bus-status flags ahead of a new transaction.
ra8_err_t	priv_i3c_i2c_send_address (volatile r_i3c_i2c_regs_t *reg, uint8_t address_byte)
	Send a single address byte and wait for TDBEF0 readiness.
bool	priv_i3c_i2c_len_buf_invalid (uint32_t len, const void *buf)
	Pure predicate: non-zero length AND a NULL buffer pointer.
bool	priv_i3c_i2c_should_dispatch (uint8_t mask, const void *cb)
	Pure predicate: non-zero error mask AND a non-NULL callback.

Variables
ra8_i3c_i2c_state_t	s_iic_b_state [k_ra8_i3c_i2c_channel_count]
	Per-channel state table indexed by channel.

Detailed Description

Test-access surface for ra8_i3c_i2c internal helpers (MC/DC).

Declares caller-invisible IIC_B state and cross-translation-unit transaction helpers used by the public compatibility API.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file ra8_i3c_i2c_internal.h.

Function Documentation

priv_i3c_i2c_clear_bst()

void priv_i3c_i2c_clear_bst

(

volatile r_i3c_i2c_regs_t *

reg

)

Clear all latched bus-status flags ahead of a new transaction.

Shared BST scrub used before every transaction. Promoted to TU-external linkage so the control-plane TU (abort / scan) and the data-path TU can both clear the latched flags.

Parameters

[in]

reg

Channel register block (non-NULL).

Precondition

reg points to a valid IIC_B register block.

The channel has been brought up by ra8_i3c_i2c_init.

Postcondition

The transaction-related BST flags are cleared (W0C).

No other register is modified.

Note

Not thread-safe; serialise per channel.

Since

0.1.0

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Parameters

[in]

reg

See header declaration for direction and constraints.

Precondition

Driver state has been initialized by the matching *_init.

Caller has validated all pointer parameters.

Postcondition

Side effects are limited to those documented in the header.

No global state is modified on the error path.

Note

Thread safety: see the header declaration.

Since

0.1.0

< RA8 I3C I2C bst clear mask.

Definition at line 347 of file ra8_i3c_i2c.c.

References r_i3c_i2c_regs_t::BST, k_ra8_i3c_i2c_msk_bst_alf, k_ra8_i3c_i2c_msk_bst_nackdf, k_ra8_i3c_i2c_msk_bst_spcnddf, k_ra8_i3c_i2c_msk_bst_stcnddf, k_ra8_i3c_i2c_msk_bst_tendf, and k_ra8_i3c_i2c_msk_bst_todf.

Referenced by internal_i3c_i2c_finalize(), ra8_i3c_i2c_abort(), ra8_i3c_i2c_read(), ra8_i3c_i2c_scan(), and ra8_i3c_i2c_write().

priv_i3c_i2c_len_buf_invalid()

bool priv_i3c_i2c_len_buf_invalid	(	uint32_t	len,
		const void *	buf )

Pure predicate: non-zero length AND a NULL buffer pointer.

Reusable for both the (tx_len != 0 && tx == NULL) and (rx_len != 0 && rx == NULL) checks at libs/ra8_hal/src/ra8_i3c_i2c.c lines 973 and 976 inside ra8_i3c_i2c_read.

Parameters

[in]	len	Length in bytes (zero means "not used").
[in]	buf	Buffer pointer (NULL means "not provided").

Returns

Boolean reject predicate.

Return values

true	Caller must return k_ra8_err_null_ptr.
false	Combination is valid.

Precondition

None.

None.

Postcondition

No state mutated.

Return depends solely on the two inputs.

Note

Test-access only. Pure function.

MC/DC:

2-condition AND; N+1 = 3 vectors:

• len=0, buf=NULL -> false
• len>0, buf=NULL -> true (varies left)
• len>0, buf!=NULL -> false (varies right)

Since

0.1.0

Pure predicate: non-zero length AND a NULL buffer pointer.

Promoted helper so the line-976 AND can be driven under MC/DC.

Parameters

[in]	len	Length in bytes.
[in]	buf	Buffer pointer.

Returns

Boolean reject predicate.

Return values

true	Caller returns null-ptr error.
false	Combination is OK.

Precondition

None.

None.

Postcondition

No state mutated.

Return depends solely on inputs.

Note

Pure; thread-safe.

Since

0.1.0

Definition at line 76 of file ra8_i3c_i2c.c.

Referenced by ra8_i3c_i2c_transfer().

priv_i3c_i2c_send_address()

ra8_err_t priv_i3c_i2c_send_address	(	volatile r_i3c_i2c_regs_t *	reg,
		uint8_t	address_byte )

Send a single address byte and wait for TDBEF0 readiness.

Shared address-phase helper. Promoted to TU-external linkage so the control-plane TU (ra8_i3c_i2c_scan) and the data-path TU can both push the pre-shifted address byte and forward timeout / NACK detection.

Parameters

[in]	reg	Channel registers (non-NULL).
[in]	address_byte	Pre-shifted 7-bit address with the R/W bit set.

Returns

ra8_err_t outcome of the address phase.

Return values

k_ra8_ok	Address byte written, TDBEF0 ready.
k_ra8_err_hw_timeout	TDBEF0 never set within the poll budget.

Precondition

reg points to a valid IIC_B register block.

A START / RESTART has already been requested.

Postcondition

On success the address byte is in NTDTBP0.

No global state is modified on the timeout path.

Note

Not thread-safe; serialise per channel.

Since

0.1.0

Send a single address byte and wait for TDBEF0 readiness.

Parameters

[in]	reg	Channel registers.
[in]	address_byte	Pre-shifted address with R/W bit.

Returns

ra8_err_t – forwards timeout / NACK detection.

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Return values

k_ra8_ok	Success path.
k_ra8_err_invalid_arg	Caller violated a precondition.

Precondition

Driver state has been initialized by the matching *_init.

Caller has validated all pointer parameters.

Postcondition

Side effects are limited to those documented in the header.

No global state is modified on the error path.

Note

Thread safety: see the header declaration.

Since

0.1.0

Definition at line 380 of file ra8_i3c_i2c.c.

References internal_i3c_i2c_wait_ntst(), k_ra8_i3c_i2c_msk_ntst_tdbef0, k_ra8_ok, and r_i3c_i2c_regs_t::NTDTBP0.

Referenced by ra8_i3c_i2c_read(), ra8_i3c_i2c_scan(), and ra8_i3c_i2c_write().

priv_i3c_i2c_should_dispatch()

bool priv_i3c_i2c_should_dispatch	(	uint8_t	mask,
		const void *	cb )

Pure predicate: non-zero error mask AND a non-NULL callback.

Promoted from the inline AND at libs/ra8_hal/src/ra8_i3c_i2c.c inside ra8_i3c_i2c_dispatch_eri.

Parameters

[in]	mask	Bitmask of pending error sources.
[in]	cb	Callback pointer (NULL when none registered).

Returns

Boolean dispatch-callback predicate.

Return values

true	Caller must invoke cb.
false	Skip the callback.

Precondition

None.

None.

Postcondition

No state mutated.

Return depends solely on the two inputs.

Note

Test-access only. Pure function.

MC/DC:

2-condition AND; N+1 = 3 vectors:

• mask=0, cb=NULL -> false
• mask!=0, cb=NULL -> false (varies right -> still false)
• mask!=0, cb!=NULL -> true (both true) Reorder for MC/DC isolation:
• V1: mask!=0, cb!=NULL -> true
• V2: mask=0, cb!=NULL -> false (varies mask)
• V3: mask!=0, cb=NULL -> false (varies cb)

Since

0.1.0

Pure predicate: non-zero error mask AND a non-NULL callback.

Promoted helper so the line-1235 AND can be driven under MC/DC.

Parameters

[in]	mask	Bitmask of pending error sources.
[in]	cb	Callback pointer.

Returns

Boolean predicate.

Return values

true	Caller invokes cb.
false	Skip callback.

Precondition

None.

None.

Postcondition

No state mutated.

Return depends solely on inputs.

Note

Pure; thread-safe.

Since

0.1.0

Definition at line 96 of file ra8_i3c_i2c.c.

Referenced by ra8_i3c_i2c_dispatch_eri().

priv_i3c_i2c_start()

void priv_i3c_i2c_start

(

volatile r_i3c_i2c_regs_t *

reg

)

Issue a START condition on the given channel registers.

Shared START helper writing CNDCTL.STCND. Promoted to TU-external linkage so the control-plane TU (ra8_i3c_i2c_scan) and the data-path TU can both issue it.

Parameters

[in]

reg

Channel register block (non-NULL).

Precondition

reg points to a valid IIC_B register block.

The channel has been brought up by ra8_i3c_i2c_init.

Postcondition

CNDCTL.STCND is set, requesting a START on the bus.

No other register is modified.

Note

Not thread-safe; serialise per channel.

Since

0.1.0

Issue a START condition on the given channel registers.

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Parameters

[in]

reg

See header declaration for direction and constraints.

Precondition

Driver state has been initialized by the matching *_init.

Caller has validated all pointer parameters.

Postcondition

Side effects are limited to those documented in the header.

No global state is modified on the error path.

Note

Thread safety: see the header declaration.

Since

0.1.0

Definition at line 277 of file ra8_i3c_i2c.c.

References r_i3c_i2c_regs_t::CNDCTL, and k_ra8_i3c_i2c_msk_cndctl_stcnd.

Referenced by internal_i3c_i2c_open_phase(), and ra8_i3c_i2c_scan().

priv_i3c_i2c_stop()

void priv_i3c_i2c_stop

(

volatile r_i3c_i2c_regs_t *

reg

)

Issue a STOP condition and clear the prior STOP-detect flag.

Shared STOP helper writing CNDCTL.SPCND after a W0C clear of BST.SPCNDDF. Promoted to TU-external linkage so the control-plane TU (abort / scan) and the data-path TU can both issue it.

Parameters

[in]

reg

Channel register block (non-NULL).

Precondition

reg points to a valid IIC_B register block.

The channel has been brought up by ra8_i3c_i2c_init.

Postcondition

CNDCTL.SPCND is set, requesting a STOP on the bus.

The prior BST.SPCNDDF flag is cleared.

Note

Not thread-safe; serialise per channel.

Since

0.1.0

Issue a STOP condition and clear the prior STOP-detect flag.

Mirrors FSP's stop-on-completion path (its RXI read + TEI end handlers). SPCNDDF is left for the ERI dispatcher to observe; the polling helpers don't gate on it because the synchronous flow is already past the data phase by the time we get here.

HUM Ch 40.2.32 "CNDCTL : Condition Control Register" p 2479

Parameters

[in]

reg

See header declaration for direction and constraints.

Precondition

Driver state has been initialized by the matching *_init.

Caller has validated all pointer parameters.

Postcondition

Side effects are limited to those documented in the header.

No global state is modified on the error path.

Note

Thread safety: see the header declaration.

Since

0.1.0

Definition at line 325 of file ra8_i3c_i2c.c.

References r_i3c_i2c_regs_t::BST, r_i3c_i2c_regs_t::CNDCTL, k_ra8_i3c_i2c_msk_bst_spcnddf, and k_ra8_i3c_i2c_msk_cndctl_spcnd.

Referenced by internal_i3c_i2c_finalize(), ra8_i3c_i2c_abort(), ra8_i3c_i2c_read(), ra8_i3c_i2c_scan(), and ra8_i3c_i2c_write().

Variable Documentation

s_iic_b_state

ra8_i3c_i2c_state_t s_iic_b_state[k_ra8_i3c_i2c_channel_count]

extern

Per-channel state table indexed by channel.

The ra8_i3c_i2c_state_t type and the matching extern declaration live in ra8_i3c_i2c_internal.h so the control-plane TU (ra8_i3c_i2c_control.c) can share this single definition.

Defined in ra8_i3c_i2c.c; the control-plane TU (abort / scan / attach_handler / dispatch_eri) reads and updates the held-bus and callback fields through this extern declaration.

Note

Not thread-safe; serialise channel access at a higher layer.

Warning

Owned by ra8_i3c_i2c.c; do not define elsewhere.

Since

0.1.0

Definition at line 132 of file ra8_i3c_i2c.c.

Referenced by internal_i3c_i2c_finalize(), ra8_i3c_i2c_abort(), ra8_i3c_i2c_attach_handler(), ra8_i3c_i2c_deinit(), ra8_i3c_i2c_dispatch_eri(), ra8_i3c_i2c_init(), ra8_i3c_i2c_read(), and ra8_i3c_i2c_write().