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

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_i2c.h"
#include "ra8_i2c_regs.h"

Include dependency graph for ra8_i2c_internal.h:

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

Data Structures
struct	ra8_i2c_state_t
	Per-channel driver state shared by both I2C translation units. More...

Functions
bool	priv_ra8_i2c_internal_clk_invalid (uint32_t bus_hz, uint32_t pclkb_hz)
	Pure predicate: either clock argument is zero.
bool	priv_ra8_i2c_internal_peripheral_poll_done (uint8_t icsr1, uint8_t icsr2)
	Poll-exit predicate: an own-address match or a STOP was observed.
bool	priv_ra8_i2c_internal_peripheral_rx_continue (uint8_t icsr2, uint32_t received, uint32_t capacity)
	Receive-loop predicate: keep draining while no STOP and room remains.
ra8_err_t	priv_ra8_i2c_internal_target_drain_rx (volatile r_i2c_regs_t reg, uint8_t buf, uint32_t capacity, uint32_t *out_count)
	Drain controller-write data bytes from ICDRR into buf.
bool	priv_ra8_i2c_internal_peripheral_tx_done (uint8_t icsr2)
	Transmit-completion predicate: the controller ended the read.
bool	priv_ra8_i2c_internal_peripheral_tx_continue (uint8_t icsr2, uint32_t sent, uint32_t len)
	Transmit-loop predicate: keep sending while no NACK and data remains.

Variables
const char *const	g_i2c_tag
	Log tag for this driver, shared with ra8_i2c_config.c.
ra8_i2c_state_t	s_i2c_state [k_ra8_i2c_channel_count]
	Per-channel state table indexed by channel.

Detailed Description

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

Declares bounded module-private RIIC predicates and transfer helpers shared across the I2C driver translation units.

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

Since: 0.1.0

Definition in file ra8_i2c_internal.h.

Function Documentation

◆ priv_ra8_i2c_internal_clk_invalid()

bool priv_ra8_i2c_internal_clk_invalid	(	uint32_t	bus_hz,
		uint32_t	pclkb_hz )

Pure predicate: either clock argument is zero.

Promoted from the OR decision in internal_i2c_bitrate (also used by ra8_i2c_init) so the two conditions can be exercised with independent influence under MC/DC.

Parameters

[in]	bus_hz	Target bus clock in Hz.
[in]	pclkb_hz	Reference PCLKB clock in Hz.

Returns: Boolean reject predicate.

Return values

true	At least one clock is zero (invalid).
false	Both clocks are non-zero.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on the two inputs.

Note: Test-access only. Pure function.

MC/DC:

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

V1: bus!=0, pclkb!=0 -> false
V2: bus=0, pclkb!=0 -> true (varies left)
V3: bus!=0, pclkb=0 -> true (varies right)

Since: 0.1.0

Promoted so the OR decision can be driven under MC/DC.

Parameters

[in]	bus_hz	Target bus clock.
[in]	pclkb_hz	Reference PCLKB clock.

Returns: Boolean reject predicate.

Return values

true	At least one clock is zero (invalid).
false	Both clocks are non-zero.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on inputs.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 114 of file ra8_i2c.c.

Referenced by internal_i2c_bitrate().

◆ priv_ra8_i2c_internal_peripheral_poll_done()

bool priv_ra8_i2c_internal_peripheral_poll_done	(	uint8_t	icsr1,
		uint8_t	icsr2 )

Poll-exit predicate: an own-address match or a STOP was observed.

Drives the bounded wait in ra8_i2c_peripheral_poll. The match flags come from ICSR1 (AAS0/1/2, GCA); STOP comes from ICSR2. Promoted so the OR can be exercised with independent influence under MC/DC.

Parameters

[in]	icsr1	Snapshot of ICSR1 (own-address detection flags).
[in]	icsr2	Snapshot of ICSR2 (STOP detection flag).

Returns: Whether the poll loop should stop spinning.

Return values

true	An own-address match or a STOP condition is latched.
false	Neither – keep spinning.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on the two inputs.

Note: Test-access only. Pure function.

MC/DC:

Decision: (icsr1 & match) != 0 || (icsr2 & stop) != 0 (2 conditions); N+1 = 3 vectors:

V1: match=0, stop=0 -> false (control: both false)
V2: match=1, stop=0 -> true (varies left)
V3: match=0, stop=1 -> true (varies right)

Since: 0.1.0

Definition at line 99 of file ra8_i2c_peripheral.c.

References k_ra8_i2c_msk_icsr1_match, and k_ra8_i2c_msk_icsr2_stop.

Referenced by ra8_i2c_peripheral_poll().

◆ priv_ra8_i2c_internal_peripheral_rx_continue()

bool priv_ra8_i2c_internal_peripheral_rx_continue	(	uint8_t	icsr2,
		uint32_t	received,
		uint32_t	capacity )

Receive-loop predicate: keep draining while no STOP and room remains.

Drives the per-byte loop in ra8_i2c_peripheral_receive. Promoted so the AND can be exercised with independent influence under MC/DC.

Parameters

[in]	icsr2	Snapshot of ICSR2 (STOP detection flag).
[in]	received	Bytes stored so far.
[in]	capacity	Destination buffer size.

Returns: Whether another byte may be received into the buffer.

Return values

true	No STOP latched and received < capacity.
false	A STOP is latched or the buffer is full.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on the inputs.

Note: Test-access only. Pure function.

MC/DC:

Decision: (icsr2 & stop) == 0 && received < capacity (2 conditions); N+1 = 3 vectors:

V1: stop=0, received<capacity -> true (control: both true)
V2: stop=1, received<capacity -> false (varies left)
V3: stop=0, received==capacity -> false (varies right)

Since: 0.1.0

Definition at line 105 of file ra8_i2c_peripheral.c.

References k_ra8_i2c_msk_icsr2_stop.

Referenced by priv_ra8_i2c_internal_target_drain_rx().

◆ priv_ra8_i2c_internal_peripheral_tx_continue()

bool priv_ra8_i2c_internal_peripheral_tx_continue	(	uint8_t	icsr2,
		uint32_t	sent,
		uint32_t	len )

Transmit-loop predicate: keep sending while no NACK and data remains.

Drives the per-byte loop in ra8_i2c_peripheral_transmit. Promoted so the AND can be exercised with independent influence under MC/DC.

Parameters

[in]	icsr2	Snapshot of ICSR2 (NACKF detection flag).
[in]	sent	Bytes accepted by the controller so far.
[in]	len	Number of bytes available to send.

Returns: Whether another byte should be queued to ICDRT.

Return values

true	No NACK latched and sent < len.
false	The controller NACKed or all bytes are queued.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on the inputs.

Note: Test-access only. Pure function.

MC/DC:

Decision: (icsr2 & nackf) == 0 && sent < len (2 conditions); N+1 = 3 vectors:

V1: nackf=0, sent<len -> true (control: both true)
V2: nackf=1, sent<len -> false (varies left)
V3: nackf=0, sent==len -> false (varies right)

Since: 0.1.0

Definition at line 118 of file ra8_i2c_peripheral.c.

References k_ra8_i2c_msk_icsr2_nackf.

Referenced by internal_i2c_target_fill_tx().

◆ priv_ra8_i2c_internal_peripheral_tx_done()

bool priv_ra8_i2c_internal_peripheral_tx_done ( uint8_t icsr2 )

Transmit-completion predicate: the controller ended the read.

Used by ra8_i2c_peripheral_transmit after the data loop to confirm the frame closed cleanly. Promoted so the OR can be exercised under MC/DC.

Parameters

[in] icsr2 Snapshot of ICSR2 (NACKF and TEND flags).

Returns: Whether the controller has ended the read transaction.

Return values

true	NACKF or TEND is latched.
false	Neither – transmission is still in progress.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on the input snapshot.

Note: Test-access only. Pure function.

MC/DC:

Decision: (icsr2 & nackf) != 0 || (icsr2 & tend) != 0 (2 conditions); N+1 = 3 vectors:

V1: nackf=0, tend=0 -> false (control: both false)
V2: nackf=1, tend=0 -> true (varies left)
V3: nackf=0, tend=1 -> true (varies right)

Since: 0.1.0

Definition at line 112 of file ra8_i2c_peripheral.c.

References k_ra8_i2c_msk_icsr2_nackf, and k_ra8_i2c_msk_icsr2_tend.

Referenced by internal_i2c_target_finish_tx().

◆ priv_ra8_i2c_internal_target_drain_rx()

ra8_err_t priv_ra8_i2c_internal_target_drain_rx	(	volatile r_i2c_regs_t *	reg,
		uint8_t *	buf,
		uint32_t	capacity,
		uint32_t *	out_count )

Drain controller-write data bytes from ICDRR into buf.

The per-byte receive loop extracted from ra8_i2c_peripheral_receive so the public entry stays within the NASA Rule 4 statement budget. Each iteration waits for ICSR2.RDRF or STOP, then – while priv_ra8_i2c_internal_peripheral_rx_continue holds (no STOP and room remains) – copies one ICDRR byte. On STOP or a full buffer it drains a final pending byte (only when RDRF is set and room is left) and stops. The loop is bounded by capacity + 1 (NASA P10 Rule 2). Promoted to TU-external linkage so the final-byte drain guard can be exercised with independent influence: the ra8_fake MMIO window is side-effect-free, so the public ra8_i2c_peripheral_receive path cannot present RDRF set at the address-phase wait and clear at this guard.

Parameters

[in]	reg	Channel register block.
[out]	buf	Destination buffer.
[in]	capacity	Buffer size in bytes (non-zero).
[out]	out_count	Number of bytes stored.

Returns: ra8_err_t outcome of the last status poll.

Return values

k_ra8_ok	Loop ended on STOP or a full buffer.
k_ra8_err_hw_timeout	A status poll exhausted its spin budget.

Precondition: reg, buf and out_count are non-NULL.; The address-phase dummy read already consumed the matched address.

Postcondition: *out_count <= capacity.; Bytes [0, *out_count) of buf hold the received payload.

Note: Thread safety: not thread-safe (drives a single channel).; Test-access only outside the defining TU.

MC/DC:

Decision: ((icsr2 & rdrf) != 0) && (count < capacity) (2 conditions, the final-pending-byte drain guard); N+1 = 3 vectors:

V1: rdrf set, count<capacity -> true (control: drains one trailing byte)
V2: rdrf clear -> false (varies left)
V3: rdrf set, count==capacity -> false (varies right)

Since: 0.1.0

Drain controller-write data bytes from ICDRR into buf.

Definition at line 274 of file ra8_i2c_peripheral.c.

References r_i2c_regs_t::ICDRR, r_i2c_regs_t::ICSR2, internal_i2c_target_wait(), k_ra8_i2c_msk_icsr2_rdrf, k_ra8_i2c_msk_icsr2_stop, k_ra8_ok, and priv_ra8_i2c_internal_peripheral_rx_continue().

Referenced by ra8_i2c_peripheral_receive().

Variable Documentation

◆ g_i2c_tag

const char* const g_i2c_tag

extern

Log tag for this driver, shared with ra8_i2c_config.c.

Log tag shared by the I2C transfer and configuration planes.

Owning definition for the g_i2c_tag symbol declared extern in ra8_i2c_internal.h; both I2C translation units log under "I2C".

Note: Read-only string pointer; not mutated after static init.

Since: 0.1.0

Defined once in ra8_i2c.c (the data-transfer translation unit) and consumed by both ra8_i2c.c and ra8_i2c_config.c so the two halves of the split driver log under the same "I2C" tag.

Note: Read-only string pointer; not mutated after static init.

Since: 0.1.0

Definition at line 65 of file ra8_i2c.c.

Referenced by internal_i2c_bitrate(), ra8_i2c_get_errors(), ra8_i2c_init(), ra8_i2c_peripheral_init(), ra8_i2c_peripheral_poll(), ra8_i2c_peripheral_receive(), ra8_i2c_peripheral_transmit(), ra8_i2c_read(), ra8_i2c_scan(), and ra8_i2c_write().

◆ s_i2c_state

ra8_i2c_state_t s_i2c_state[k_ra8_i2c_channel_count]

extern

Per-channel state table indexed by channel.

Owning definition for the s_i2c_state array declared extern in ra8_i2c_internal.h so the bring-up plane in ra8_i2c_config.c and the transfer plane here observe identical bus-ownership state.

Warning: Mutated only by the driver under the not-thread-safe contract.

Since: 0.1.0

Defined once in ra8_i2c.c and shared with ra8_i2c_config.c so the bring-up and transfer planes observe the same bus-ownership state.

Warning: Mutated only by the driver under the not-thread-safe contract.

See also: ra8_i2c_state_t

Since: 0.1.0

Definition at line 132 of file ra8_i2c.c.

Referenced by internal_i2c_finish_tx(), ra8_i2c_deinit(), ra8_i2c_init(), ra8_i2c_peripheral_attach_handler(), ra8_i2c_peripheral_deinit(), ra8_i2c_peripheral_dispatch(), ra8_i2c_peripheral_init(), ra8_i2c_peripheral_poll(), ra8_i2c_peripheral_receive(), ra8_i2c_peripheral_transmit(), ra8_i2c_read(), ra8_i2c_scan(), and ra8_i2c_write().

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ priv_ra8_i2c_internal_clk_invalid()

◆ priv_ra8_i2c_internal_peripheral_poll_done()

◆ priv_ra8_i2c_internal_peripheral_rx_continue()

◆ priv_ra8_i2c_internal_peripheral_tx_continue()

◆ priv_ra8_i2c_internal_peripheral_tx_done()

◆ priv_ra8_i2c_internal_target_drain_rx()

Variable Documentation

◆ g_i2c_tag

◆ s_i2c_state