IIC_B (I3C unified IP) control-plane + diagnostics implementation. More...

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

Include dependency graph for ra8_i3c_i2c_control.c:

Enumerations
enum	internal_i3c_i2c_control_t : uint32_t { k_ra8_i3c_i2c_ctrl_poll_limit = 200000U , k_ra8_i3c_i2c_ctrl_addr_shift = 1U , k_ra8_i3c_i2c_ctrl_addr_rw_write = 0U }
	Implementation constants for the control-plane TU. More...

Functions
static uint8_t	internal_i3c_i2c_decode_errors (uint32_t bst)
	Decode latched BST error bits into a k_ra8_i3c_i2c_err_* mask.
ra8_err_t	ra8_i3c_i2c_abort (uint8_t channel)
	Cancel any in-flight transaction and return the channel to idle.
ra8_err_t	ra8_i3c_i2c_scan (uint8_t channel, uint8_t target_7b, bool *out_acked)
	Probe whether a 7-bit address ACKs.
ra8_err_t	ra8_i3c_i2c_get_errors (uint8_t channel, uint8_t *out_mask)
	Read latched error flags from BST (AL / NACKDF / TODF).
ra8_err_t	ra8_i3c_i2c_clear_errors (uint8_t channel)
	Clear latched error flags in BST.
ra8_err_t	ra8_i3c_i2c_attach_handler (uint8_t channel, ra8_i3c_i2c_complete_fn_t fn, void *ctx)
	Attach a completion / error callback for the channel.
void	ra8_i3c_i2c_dispatch_eri (uint8_t channel)
	Dispatch the bus-error IRQ source.

Variables
static const char *	s_tag = "IIC_B"
	Log tag for this driver's control-plane TU.

Detailed Description

IIC_B (I3C unified IP) control-plane + diagnostics implementation.

Tag: [Ring 3 / HAL] {World: NS}

Control-plane companion translation unit to ra8_i3c_i2c.c. Holds the non-data-path operations of the polling IIC_B driver:

ra8_i3c_i2c_abort cancel an in-flight transaction.
ra8_i3c_i2c_scan single-byte address-only bus probe.
ra8_i3c_i2c_get_errors / ra8_i3c_i2c_clear_errors latched bus-status decode + scrub.
ra8_i3c_i2c_attach_handler register a completion / error callback and toggle the IIC_B IRQ enable bits as a group.
ra8_i3c_i2c_dispatch_eri ERI service routine that decodes, clears, and forwards errors.

These functions share the s_iic_b_state channel table and the promoted START / STOP / clear-BST / send-address helpers with the transaction engine in ra8_i3c_i2c.c via ra8_i3c_i2c_internal.h. Each TU keeps its own read-only s_tag log-tag copy.

Owns its writes to the I3C register block. See HUM Ch 40 "I3C Bus Interface (I3C)", p 2445-2701.

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

Definition in file ra8_i3c_i2c_control.c.

Enumeration Type Documentation

◆ internal_i3c_i2c_control_t

enum internal_i3c_i2c_control_t : uint32_t

Implementation constants for the control-plane TU.

Enumerator

k_ra8_i3c_i2c_ctrl_poll_limit

Generic spin budget for status-flag polls.

~200k iters keeps the worst-case stall under ~5ms at 250MHz with the load/branch pair the compiler emits for the wait helpers.

k_ra8_i3c_i2c_ctrl_addr_shift

Shift count to convert a 7-bit address into the on-the-wire byte.

k_ra8_i3c_i2c_ctrl_addr_rw_write

R/W bit value for a write transaction (0 in LSB).

Definition at line 51 of file ra8_i3c_i2c_control.c.

Function Documentation

◆ internal_i3c_i2c_decode_errors()

uint8_t internal_i3c_i2c_decode_errors ( uint32_t bst )

static

Decode latched BST error bits into a k_ra8_i3c_i2c_err_* mask.

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

Parameters

[in] bst See header declaration for direction and constraints.

Returns: ra8_err_t error code (or void if the signature returns void).

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 79 of file ra8_i3c_i2c_control.c.

References k_ra8_i3c_i2c_err_arb_lost, k_ra8_i3c_i2c_err_nack, k_ra8_i3c_i2c_err_none, k_ra8_i3c_i2c_err_timeout, k_ra8_i3c_i2c_msk_bst_alf, k_ra8_i3c_i2c_msk_bst_nackdf, k_ra8_i3c_i2c_msk_bst_todf, and RA8_INTERNAL.

Referenced by ra8_i3c_i2c_get_errors().

◆ ra8_i3c_i2c_abort()

ra8_err_t ra8_i3c_i2c_abort ( uint8_t channel )

nodiscard

Cancel any in-flight transaction and return the channel to idle.

Mirrors FSP's R_IIC_B_MASTER_Abort controller abort-sequence helper for the polling driver. Steps:

Mask BIE / NTIE so a pending interrupt cannot fire mid-tear-down.
Issue STOP (unconditional). The hardware will eventually drive SPCNDDF; the polling helpers don't gate on it because no further bus traffic is expected from this channel until the next ra8_i3c_i2c_write / _read clears BST again.
Clear all latched bus-status flags.

Parameters

[in] channel Channel index.

Returns: ra8_err_t.

Return values

k_ra8_ok	Abort issued.
k_ra8_err_invalid_arg	Channel out of range.

Precondition: Channel previously initialized.

Postcondition: Channel is idle; BST flags cleared.

Since: 0.1.0

Definition at line 99 of file ra8_i3c_i2c_control.c.

References r_i3c_i2c_regs_t::BIE, i3c_i2c_regs(), k_ra8_err_invalid_arg, k_ra8_ok, r_i3c_i2c_regs_t::NTIE, priv_i3c_i2c_clear_bst(), priv_i3c_i2c_stop(), and s_iic_b_state.

Referenced by ra8_i3c_abort().

◆ ra8_i3c_i2c_attach_handler()

ra8_err_t ra8_i3c_i2c_attach_handler	(	uint8_t	channel,
		ra8_i3c_i2c_complete_fn_t	fn,
		void *	ctx )

nodiscard

Attach a completion / error callback for the channel.

Parameters

[in]	channel	Channel index.
[in]	fn	Callback fired from the dispatch helpers, or NULL to detach.
[in]	ctx	Context pointer passed to the callback.

Returns: ra8_err_t.

Return values

k_ra8_ok	Callback registered.
k_ra8_err_invalid_arg	Channel out of range.

Precondition: Channel previously initialized.

Postcondition: BIE / NTIE bits track fn non-null status.

Since: 0.1.0

Definition at line 201 of file ra8_i3c_i2c_control.c.

References r_i3c_i2c_regs_t::BIE, i3c_i2c_regs(), k_ra8_err_invalid_arg, k_ra8_i3c_i2c_msk_bie_alie, k_ra8_i3c_i2c_msk_bie_nackdie, k_ra8_i3c_i2c_msk_bie_tendie, k_ra8_i3c_i2c_msk_bie_todie, k_ra8_i3c_i2c_msk_ntie_rdbfie0, k_ra8_i3c_i2c_msk_ntie_tdbeie0, k_ra8_ok, r_i3c_i2c_regs_t::NTIE, and s_iic_b_state.

◆ ra8_i3c_i2c_clear_errors()

ra8_err_t ra8_i3c_i2c_clear_errors ( uint8_t channel )

nodiscard

Clear latched error flags in BST.

Parameters

[in] channel Channel index.

Returns: ra8_err_t.

Return values

k_ra8_ok	Error bits W0C cleared.
k_ra8_err_invalid_arg	Channel out of range.

Since: 0.1.0

< RA8 I3C I2C error clear mask.

Definition at line 181 of file ra8_i3c_i2c_control.c.

References r_i3c_i2c_regs_t::BST, i3c_i2c_regs(), k_ra8_err_invalid_arg, k_ra8_i3c_i2c_msk_bst_alf, k_ra8_i3c_i2c_msk_bst_nackdf, k_ra8_i3c_i2c_msk_bst_todf, and k_ra8_ok.

Referenced by ra8_i3c_clear_errors(), ra8_i3c_dispatch(), and ra8_i3c_i2c_dispatch_eri().

◆ ra8_i3c_i2c_dispatch_eri()

void ra8_i3c_i2c_dispatch_eri ( uint8_t channel )

Dispatch the bus-error IRQ source.

Test-callable shim that mirrors the ERI handler in FSP's r_iic_b_master: it samples BST, masks the latched error bits back to k_ra8_i3c_i2c_err_*, clears them, and fires the registered callback with that mask if it is non-zero.

Parameters

[in] channel Channel index.

Since: 0.1.0

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.

Definition at line 228 of file ra8_i3c_i2c_control.c.

References k_ra8_i3c_i2c_channel_count, priv_i3c_i2c_should_dispatch(), ra8_i3c_i2c_clear_errors(), ra8_i3c_i2c_get_errors(), and s_iic_b_state.

◆ ra8_i3c_i2c_get_errors()

ra8_err_t ra8_i3c_i2c_get_errors	(	uint8_t	channel,
		uint8_t *	out_mask )

nodiscard

Read latched error flags from BST (AL / NACKDF / TODF).

Parameters

[in]	channel	Channel index.
[out]	out_mask	OR of k_ra8_i3c_i2c_err_* bits.

Returns: ra8_err_t.

Return values

k_ra8_ok	out_mask populated.
k_ra8_err_null_ptr	out_mask is NULL.
k_ra8_err_invalid_arg	channel out of range.

Since: 0.1.0

Definition at line 170 of file ra8_i3c_i2c_control.c.

References r_i3c_i2c_regs_t::BST, i3c_i2c_regs(), internal_i3c_i2c_decode_errors(), k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by ra8_i3c_dispatch(), ra8_i3c_get_errors(), and ra8_i3c_i2c_dispatch_eri().

◆ ra8_i3c_i2c_scan()

ra8_err_t ra8_i3c_i2c_scan	(	uint8_t	channel,
		uint8_t	target_7b,
		bool *	out_acked )

nodiscard

Probe whether a 7-bit address ACKs.

Issues START, writes the address byte, waits for the ACK / NACK status, and issues STOP. Equivalent to a single i2cdetect sweep entry.

Parameters

[in]	channel	Channel index.
[in]	target_7b	7-bit peripheral address.
[out]	out_acked	Set to true when the peripheral ACKs, false on NACK.

Returns: ra8_err_t.

Return values

k_ra8_ok	Probe completed (ACK or NACK).
k_ra8_err_null_ptr	out_acked is NULL or channel invalid.
k_ra8_err_hw_timeout	Status poll timed out.

Precondition: Channel previously initialized.

Since: 0.1.0

Definition at line 122 of file ra8_i3c_i2c_control.c.

References r_i3c_i2c_regs_t::BST, i3c_i2c_regs(), k_ra8_err_hw_timeout, k_ra8_i3c_i2c_ctrl_addr_rw_write, k_ra8_i3c_i2c_ctrl_addr_shift, k_ra8_i3c_i2c_ctrl_poll_limit, k_ra8_i3c_i2c_msk_bst_nackdf, k_ra8_i3c_i2c_msk_bst_tendf, k_ra8_ok, priv_i3c_i2c_clear_bst(), priv_i3c_i2c_send_address(), priv_i3c_i2c_start(), priv_i3c_i2c_stop(), RA8_CHECK_NULL_PTR, and s_tag.

Referenced by ra8_i3c_scan().

Variable Documentation

◆ s_tag

const char* s_tag = "IIC_B"

static

Log tag for this driver's control-plane TU.

Definition at line 45 of file ra8_i3c_i2c_control.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ internal_i3c_i2c_control_t

Function Documentation

◆ internal_i3c_i2c_decode_errors()

◆ ra8_i3c_i2c_abort()

◆ ra8_i3c_i2c_attach_handler()

◆ ra8_i3c_i2c_clear_errors()

◆ ra8_i3c_i2c_dispatch_eri()

◆ ra8_i3c_i2c_get_errors()

◆ ra8_i3c_i2c_scan()

Variable Documentation

◆ s_tag