I3C Bus Interface driver implementation. More...

#include "ra8_i3c.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_i3c_i2c.h"
#include "ra8_i3c_i2c_peripheral.h"
#include "ra8_i3c_i2c_regs.h"
#include "ra8_i3c_internal.h"
#include "ra8_i3c_regs.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_mstp_regs.h"

Include dependency graph for ra8_i3c.c:

Data Structures
struct	ra8_i3c_chan_state_t
	Per-channel driver bookkeeping for the unified driver. More...

Functions
bool	priv_ra8_i3c_internal_recv_ccc_invalid (uint8_t addr_mask, uint8_t target, uint8_t max_len)
	Pure recv-ccc-invalid predicate – see header for full contract.
bool	priv_ra8_i3c_internal_hdr_mode_invalid (uint32_t sdr_val, uint32_t ddr_val, uint32_t ts_val, uint32_t mode)
	Pure HDR-mode-invalid predicate – see header for full contract.
static void	internal_ra8_i3c_reset_sequence (volatile r_i3c_regs_t *reg)
	Internal-error reset bring-up sequence per FSP R_I3C_Open.
static uint32_t	internal_ra8_i3c_xfer_cmd_word (uint8_t target_addr, bool rnw)
	Build the first word of a regular-transfer command descriptor.
static uint32_t	internal_ra8_i3c_ccc_cmd_word (uint8_t ccc, uint8_t target_addr, bool rnw)
	Build a CCC-type command descriptor word.
static void	internal_ra8_i3c_fifo_write (volatile r_i3c_regs_t reg, const uint8_t data, uint32_t len)
	Push a payload buffer through NTDTBP0 in 32-bit chunks.
static void	internal_ra8_i3c_fifo_read (volatile const r_i3c_regs_t reg, uint8_t out, uint32_t len)
	Drain `len` bytes from NTDTBP0 into `out`.
ra8_err_t	ra8_i3c_init (uint8_t channel, const ra8_i3c_cfg_t *cfg)
	Initialise an I3C channel in the configured mode.
ra8_err_t	ra8_i3c_deinit (uint8_t channel)
	Tear down an I3C channel and gate the peripheral.
ra8_err_t	ra8_i3c_set_address (uint32_t addr)
	Programme the primary dynamic address (native mode).
ra8_err_t	ra8_i3c_bus_enable (bool enable)
	Enable/disable bus-primary operation via BCTL.BUSE (native mode).
ra8_err_t	ra8_i3c_get_status (uint32_t *out_mask)
	Read the native INST status register (native mode).
ra8_err_t	ra8_i3c_clear_status (uint32_t mask)
	Clear native INST status bits (native mode).
ra8_err_t	ra8_i3c_attach_handler (uint8_t channel, ra8_i3c_event_fn_t fn, void *ctx)
	Attach an event callback for a channel.
void	ra8_i3c_dispatch (uint8_t channel)
	Snapshot status and fire the channel's callback.
ra8_err_t	ra8_i3c_enter_stop (void)
	Put native I3C0 into MSTP-gated stop (native mode).
ra8_err_t	ra8_i3c_exit_stop (void)
	Exit MSTP-gated stop (native mode).
ra8_err_t	ra8_i3c_dynamic_address_assign (ra8_i3c_daa_target_t *targets, uint8_t target_count)
	Issue ENTDAA to enumerate I3C targets (native mode).
ra8_err_t	ra8_i3c_set_dynamic_address (uint8_t static_addr, uint8_t dynamic_addr)
	Issue SETDASA to assign one target a dynamic address (native mode).
ra8_err_t	ra8_i3c_reset_dynamic_addresses (void)
	Issue RSTDAA to clear all dynamic addresses (native mode).
ra8_err_t	ra8_i3c_send_ccc (uint8_t ccc, uint8_t target_addr, const uint8_t *payload, uint8_t len)
	Generic CCC send – broadcast or directed write (native mode).
ra8_err_t	ra8_i3c_recv_ccc (uint8_t ccc, uint8_t target_addr, uint8_t buf, uint8_t max_len, uint8_t got_len)
	Generic CCC receive – directed read (native mode).
ra8_err_t	ra8_i3c_write (uint8_t channel, uint8_t addr, const uint8_t *data, uint32_t len, bool restart)
	Write `len` bytes to `addr`.
ra8_err_t	ra8_i3c_read (uint8_t channel, uint8_t addr, uint8_t *buf, uint32_t len, bool restart)
	Read `len` bytes from `addr`.
ra8_err_t	ra8_i3c_transfer (uint8_t channel, uint8_t addr, const uint8_t wr, uint32_t wr_len, uint8_t rd, uint32_t rd_len)
	Write-then-read with repeated-START framing (I2C mode).
ra8_err_t	ra8_i3c_set_clock (uint8_t channel, uint32_t bus_hz, uint32_t pclka_hz)
	Re-programme the I2C bit rate (I2C mode).
ra8_err_t	ra8_i3c_scan (uint8_t channel, uint8_t addr, bool *out_acked)
	Probe whether a 7-bit address acknowledges (I2C mode).
ra8_err_t	ra8_i3c_get_errors (uint8_t channel, uint8_t *out_mask)
	Read the latched I2C error mask (I2C mode).
ra8_err_t	ra8_i3c_clear_errors (uint8_t channel)
	Clear latched I2C error bits (I2C mode).
ra8_err_t	ra8_i3c_abort (uint8_t channel)
	Abort an in-flight I2C transfer and release the bus (I2C mode).
ra8_err_t	ra8_i3c_peripheral_open (uint8_t channel, const ra8_i3c_peripheral_cfg_t *cfg)
	Open a channel in I2C-compat responder mode.
ra8_err_t	ra8_i3c_peripheral_close (uint8_t channel)
	Close responder mode on a channel.
ra8_err_t	ra8_i3c_peripheral_send (uint8_t channel, const uint8_t *data, uint32_t len)
	Queue bytes for the controller to read (responder mode).
ra8_err_t	ra8_i3c_peripheral_receive (uint8_t channel, uint8_t *buf, uint32_t len)
	Read bytes the controller wrote (responder mode).
ra8_err_t	ra8_i3c_peripheral_status (uint8_t channel, uint8_t *out_mask)
	Read the latched responder-mode status (responder mode).
ra8_err_t	ra8_i3c_set_hdr_mode (uint8_t target_addr, ra8_i3c_hdr_mode_t mode)
	Programme the NCMDQP transfer-mode field for a target (native mode).
ra8_err_t	ra8_i3c_ibi_enable (uint8_t target_addr)
	Enable inbound IBI capture for a target (native mode).
ra8_err_t	ra8_i3c_ibi_drain (ra8_i3c_ibi_t *ibi)
	Pop one inbound IBI (alias of ra8_i3c_ibi_read, native mode).
ra8_err_t	ra8_i3c_target_open (uint8_t static_addr)
	Enter peripheral (target) mode (native mode).
ra8_err_t	ra8_i3c_ibi_read (ra8_i3c_ibi_t *out_ibi)
	Drain one inbound IBI from NIBIQP (native mode).

Variables
static const char *	s_tag = "I3C"
	Logging tag for this module.
static ra8_i3c_event_fn_t	s_i3c_fn
	Currently registered IRQ callback (NULL when detached).
static void *	s_i3c_ctx
	Opaque context handed back to s_i3c_fn.
static ra8_i3c_chan_state_t	s_i3c_chan [k_ra8_i3c_i2c_channel_count]
	One state slot per I3C channel (RA8D2 exposes I3C0 only).

Detailed Description

I3C Bus Interface driver implementation.

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

Primary-mode driver for the RA8D2 I3C0 controller. The transfer engine mirrors FSP r_i3c: every operation is encoded as a 32-bit (or two-word) command descriptor written to the NCMDQP port, with payload bytes flowing through NTDTBP0. IBI events arrive via the NIBIQP queue.

Bring-up order matches the FSP R_I3C_Open reference sequence: enable the module clock (CECTL.CLKE), drop BCTL.BUSE, assert RSTCTL.RI3CRST and wait for hardware to clear it, then assert RSTCTL.INTLRST, clear PRTS, release RSTCTL. Primary dynamic address (MSDVAD.MDYAD) is programmed before BCTL.BUSE is set per HUM Ch 40 BCTL description (pp 2445-2701).

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

Definition in file ra8_i3c.c.

Function Documentation

◆ internal_ra8_i3c_ccc_cmd_word()

uint32_t internal_ra8_i3c_ccc_cmd_word	(	uint8_t	ccc,
		uint8_t	target_addr,
		bool	rnw )

static

Build a CCC-type command descriptor word.

Parameters

[in]	ccc	Common Command Code opcode.
[in]	target_addr	Dynamic address (used only for direct CCCs).
[in]	rnw	True for direct-get CCCs.

Returns: Word 0 of the descriptor.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 206 of file ra8_i3c.c.

References k_ra8_i3c_cmd_code_shift, k_ra8_i3c_cmd_cp_shift, k_ra8_i3c_cmd_dev_index_shift, k_ra8_i3c_cmd_rnw_shift, k_ra8_i3c_cmd_roc_shift, and k_ra8_i3c_cmd_toc_shift.

Referenced by ra8_i3c_recv_ccc(), ra8_i3c_reset_dynamic_addresses(), ra8_i3c_send_ccc(), and ra8_i3c_set_dynamic_address().

◆ internal_ra8_i3c_fifo_read()

void internal_ra8_i3c_fifo_read	(	volatile const r_i3c_regs_t *	reg,
		uint8_t *	out,
		uint32_t	len )

static

Drain len bytes from NTDTBP0 into out.

Hardware exposes the receive buffer as a 32-bit FIFO – the driver reads one word and unpacks LE bytes; trailing partial words are masked to the requested length.

Parameters

[in]	reg	See implementation.
[in]	out	See implementation.
[in]	len	See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 283 of file ra8_i3c.c.

References k_ra8_i3c_byte_mask, k_ra8_i3c_byte_shift, k_ra8_i3c_shift_b1, k_ra8_i3c_shift_b2, k_ra8_i3c_shift_b3, k_ra8_i3c_word_size, and r_i3c_regs_t::NTDTBP0.

Referenced by ra8_i3c_dynamic_address_assign(), ra8_i3c_ibi_read(), ra8_i3c_read(), and ra8_i3c_recv_ccc().

◆ internal_ra8_i3c_fifo_write()

void internal_ra8_i3c_fifo_write	(	volatile r_i3c_regs_t *	reg,
		const uint8_t *	data,
		uint32_t	len )

static

Push a payload buffer through NTDTBP0 in 32-bit chunks.

NTDTBP0 is a 32-bit FIFO; partial trailing words are padded with zero, matching FSP i3c_fifo_write. The fake-mmap test back-end is happy to accept the writes – on silicon the controller drains them onto the bus.

Parameters

[in]	reg	See implementation.
[in]	data	See implementation.
[in]	len	See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 240 of file ra8_i3c.c.

References k_ra8_i3c_byte_shift, k_ra8_i3c_shift_b1, k_ra8_i3c_shift_b2, k_ra8_i3c_shift_b3, k_ra8_i3c_word_size, and r_i3c_regs_t::NTDTBP0.

Referenced by ra8_i3c_send_ccc(), and ra8_i3c_write().

◆ internal_ra8_i3c_reset_sequence()

void internal_ra8_i3c_reset_sequence ( volatile r_i3c_regs_t * reg )

static

Internal-error reset bring-up sequence per FSP R_I3C_Open.

Enable the module clock via CECTL.CLKE.
Drop BCTL.BUSE so the bus is idle before any reset.
Pulse RSTCTL.RI3CRST – on real silicon the bit auto-clears when the I3C internal reset completes; here we issue an explicit clear so the fake-mmap unit-test back-end does not spin forever (FSP relies on FSP_HARDWARE_REGISTER_WAIT for the same thing on target).
Pulse RSTCTL.INTLRST to flush the internal state machines.
Clear PRTS so we start in I2C-fast/I3C-mixed mode 0.

Each step follows HUM Ch 40 "RSTCTL : Reset Control Register" description (pp 2445-2701).

Parameters

[in] reg See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 139 of file ra8_i3c.c.

References r_i3c_regs_t::BCTL, r_i3c_regs_t::CECTL, k_ra8_i3c_rstctl_intlrst_mask, k_ra8_i3c_rstctl_ri3crst_mask, r_i3c_regs_t::PRTS, RA8_INTERNAL, and r_i3c_regs_t::RSTCTL.

Referenced by ra8_i3c_init().

◆ internal_ra8_i3c_xfer_cmd_word()

uint32_t internal_ra8_i3c_xfer_cmd_word	(	uint8_t	target_addr,
		bool	rnw )

static

Build the first word of a regular-transfer command descriptor.

Mirrors the FSP i3c_xfer_command_calculate helper (HUM Ch 40 "Command Descriptor" pp 2445-2701). The device-table index is encoded directly as the dynamic address – the FSP driver looks the index up in DATBASn first, but until the device-address table is wired in, plumbing the address through the index field lets the test harness verify the round-trip.

Parameters

[in]	target_addr	7-bit dynamic address.
[in]	rnw	True for read transfers.

Returns: Word 0 of the command descriptor (Word 1 is the length).

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 176 of file ra8_i3c.c.

References k_ra8_i3c_cmd_dev_index_shift, k_ra8_i3c_cmd_rnw_shift, k_ra8_i3c_cmd_roc_shift, k_ra8_i3c_cmd_toc_shift, and RA8_INTERNAL.

Referenced by ra8_i3c_read(), ra8_i3c_set_hdr_mode(), and ra8_i3c_write().

◆ priv_ra8_i3c_internal_hdr_mode_invalid()

bool priv_ra8_i3c_internal_hdr_mode_invalid	(	uint32_t	sdr_val,
		uint32_t	ddr_val,
		uint32_t	ts_val,
		uint32_t	mode )

Pure HDR-mode-invalid predicate – see header for full contract.

Pure predicate: HDR mode value is not one of {SDR, DDR, TS}.

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

Parameters

[in]	sdr_val	Numeric value of `k_ra8_i3c_hdr_mode_sdr`.
[in]	ddr_val	Numeric value of `k_ra8_i3c_hdr_mode_ddr`.
[in]	ts_val	Numeric value of `k_ra8_i3c_hdr_mode_ts`.
[in]	mode	Candidate mode value.

Returns: Boolean reject predicate.

Return values

true	Mode is not legal.
false	Mode is legal.

Precondition: None.; None.

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

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 80 of file ra8_i3c.c.

Referenced by ra8_i3c_set_hdr_mode().

◆ priv_ra8_i3c_internal_recv_ccc_invalid()

bool priv_ra8_i3c_internal_recv_ccc_invalid	(	uint8_t	addr_mask,
		uint8_t	target,
		uint8_t	max_len )

Pure recv-ccc-invalid predicate – see header for full contract.

Pure predicate: target_addr out of range OR max_len is zero.

Promoted helper so the line-688 OR can be driven under MC/DC.

Parameters

[in]	addr_mask	Maximum valid 7-bit address mask.
[in]	target	Candidate target address.
[in]	max_len	Caller-supplied max read length.

Returns: Boolean reject predicate.

Return values

true	Inputs invalid.
false	Inputs OK.

Precondition: None.; None.

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

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 58 of file ra8_i3c.c.

Referenced by ra8_i3c_recv_ccc().

◆ ra8_i3c_abort()

ra8_err_t ra8_i3c_abort ( uint8_t channel )

nodiscard

Abort an in-flight I2C transfer and release the bus (I2C mode).

Parameters

[in] channel I3C channel index.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Bus released.
k_ra8_err_invalid_state	Channel is in native mode.

Precondition: Channel initialized in I2C mode.; Caller is single-threaded.

Postcondition: The bus is idle and any held state is cleared.; A subsequent transfer starts from a clean state.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 762 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_abort(), and s_i3c_chan.

◆ ra8_i3c_attach_handler()

ra8_err_t ra8_i3c_attach_handler	(	uint8_t	channel,
		ra8_i3c_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach an event callback for a channel.

Parameters

[in]	channel	I3C channel index.
[in]	fn	Callback (NULL to detach).
[in]	ctx	Opaque context passed back to `fn`.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Handler registered.
k_ra8_err_invalid_arg	`channel` out of range.

Precondition: Channel initialized.; Caller is single-threaded with respect to dispatch.

Postcondition: The channel's handler equals fn.; The channel's context equals ctx.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 415 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_i3c_i2c_channel_count, k_ra8_ok, s_i3c_ctx, and s_i3c_fn.

◆ ra8_i3c_bus_enable()

ra8_err_t ra8_i3c_bus_enable ( bool enable )

nodiscard

Enable/disable bus-primary operation via BCTL.BUSE (native mode).

Parameters

[in] enable True to enable primary operation.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	BUSE updated.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; Caller is single-threaded.

Postcondition: BCTL.BUSE reflects enable.; No transfer is in progress.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 385 of file ra8_i3c.c.

References r_i3c_regs_t::BCTL, k_ra8_i3c_bctl_buse_mask, k_ra8_ok, and ra8_i3c().

◆ ra8_i3c_clear_errors()

ra8_err_t ra8_i3c_clear_errors ( uint8_t channel )

nodiscard

Clear latched I2C error bits (I2C mode).

Parameters

[in] channel I3C channel index.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Errors cleared.
k_ra8_err_invalid_state	Channel is in native mode.

Precondition: Channel initialized in I2C mode.; Caller is single-threaded.

Postcondition: The latched error mask reads k_ra8_i3c_err_none.; No transfer is in progress.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 751 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_clear_errors(), and s_i3c_chan.

◆ ra8_i3c_clear_status()

ra8_err_t ra8_i3c_clear_status ( uint32_t mask )

nodiscard

Clear native INST status bits (native mode).

Parameters

[in] mask Bits to clear.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Bits cleared.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; Caller is single-threaded.

Postcondition: The requested INST bits read 0.; Other bits are unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 406 of file ra8_i3c.c.

References r_i3c_regs_t::INST, k_ra8_ok, and ra8_i3c().

◆ ra8_i3c_deinit()

ra8_err_t ra8_i3c_deinit ( uint8_t channel )

nodiscard

Tear down an I3C channel and gate the peripheral.

Parameters

[in] channel I3C channel index.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Channel torn down, MSTP gated.
k_ra8_err_invalid_arg	`channel` out of range.

Precondition: channel was previously initialized.; Caller is single-threaded with respect to the peripheral.

Postcondition: The channel is marked uninitialized.; The I3C MSTP is gated when no channel remains active.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 348 of file ra8_i3c.c.

References r_i3c_regs_t::BCTL, r_i3c_regs_t::CECTL, r_i3c_regs_t::INIE, r_i3c_regs_t::INSTE, k_ra8_err_invalid_arg, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, k_ra8_mstp_i3c, ra8_i3c(), ra8_i3c_i2c_deinit(), ra8_mstp_disable(), s_i3c_chan, s_i3c_ctx, and s_i3c_fn.

◆ ra8_i3c_dispatch()

void ra8_i3c_dispatch ( uint8_t channel )

Snapshot status and fire the channel's callback.

In native mode reads and clears the INST register and passes the snapshot to the handler; in I2C mode reads and clears the latched IIC_B error mask and passes it instead. A no-op when no handler is attached.

Parameters

[in] channel I3C channel index.

Precondition: Channel initialized.; A handler may or may not be attached.

Postcondition: The status flags are cleared after snapshot.; The handler (if any) has been invoked once.

Note: Not thread-safe; call from IRQ or polled context.

Since: 0.1.0

Definition at line 426 of file ra8_i3c.c.

References r_i3c_regs_t::INST, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c(), ra8_i3c_i2c_clear_errors(), ra8_i3c_i2c_get_errors(), s_i3c_chan, s_i3c_ctx, and s_i3c_fn.

◆ ra8_i3c_dynamic_address_assign()

ra8_err_t ra8_i3c_dynamic_address_assign	(	ra8_i3c_daa_target_t *	targets,
		uint8_t	target_count )

nodiscard

Issue ENTDAA to enumerate I3C targets (native mode).

Parameters

[in,out]	targets	Caller array; rows updated in place.
[in]	target_count	Number of valid rows (1..max).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Command queued; FIFOs read.
k_ra8_err_null_ptr	`targets` NULL.
k_ra8_err_invalid_arg	`target_count` 0 or out of range.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode and bus enabled.; targets non-NULL.

Postcondition: NCMDQP holds the ENTDAA descriptor.; targets reflect responses received before STOP.

Note: Not thread-safe.

Since: 0.1.0

< Pid bcr dcr bytes.

< Index bcr.

< Index dcr.

Definition at line 470 of file ra8_i3c.c.

References internal_ra8_i3c_fifo_read(), k_ra8_err_invalid_arg, k_ra8_i3c_ccc_b_entdaa, k_ra8_i3c_cmd_addr_count_shift, k_ra8_i3c_cmd_attr_addr_assgn, k_ra8_i3c_cmd_attr_shift, k_ra8_i3c_cmd_code_shift, k_ra8_i3c_cmd_roc_shift, k_ra8_i3c_cmd_toc_shift, k_ra8_i3c_max_targets, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_i3c_pid_bytes, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, RA8_CHECK_NULL_PTR, ra8_i3c(), and s_tag.

◆ ra8_i3c_enter_stop()

ra8_err_t ra8_i3c_enter_stop ( void )

nodiscard

Put native I3C0 into MSTP-gated stop (native mode).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Stopped.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; Caller is single-threaded.

Postcondition: BCTL/CECTL cleared and the MSTP gated.; The bus is idle.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 452 of file ra8_i3c.c.

References r_i3c_regs_t::BCTL, r_i3c_regs_t::CECTL, k_ra8_mstp_i3c, ra8_i3c(), and ra8_mstp_disable().

◆ ra8_i3c_exit_stop()

ra8_err_t ra8_i3c_exit_stop ( void )

nodiscard

Exit MSTP-gated stop (native mode).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Resumed.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 was put into stop via ra8_i3c_enter_stop.; Caller is single-threaded.

Postcondition: The I3C MSTP is ungated.; The peripheral is ready for re-init of bus state.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 460 of file ra8_i3c.c.

References k_ra8_mstp_i3c, and ra8_mstp_enable().

◆ ra8_i3c_get_errors()

ra8_err_t ra8_i3c_get_errors	(	uint8_t	channel,
		uint8_t *	out_mask )

nodiscard

Read the latched I2C error mask (I2C mode).

Parameters

[in]	channel	I3C channel index.
[out]	out_mask	OR of ra8_i3c_err_t bits since the last clear.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Mask returned.
k_ra8_err_null_ptr	`out_mask` NULL.
k_ra8_err_invalid_state	Channel is in native mode.

Precondition: Channel initialized in I2C mode.; out_mask is non-NULL.

Postcondition: out_mask holds the latched error bits.; No peripheral state is mutated.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 740 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_get_errors(), and s_i3c_chan.

◆ ra8_i3c_get_status()

ra8_err_t ra8_i3c_get_status ( uint32_t * out_mask )

nodiscard

Read the native INST status register (native mode).

Parameters

[out] out_mask INST snapshot.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Status returned.
k_ra8_err_null_ptr	`out_mask` NULL.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; out_mask non-NULL.

Postcondition: out_mask holds the INST snapshot.; No peripheral state is mutated.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 398 of file ra8_i3c.c.

References r_i3c_regs_t::INST, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_i3c(), and s_tag.

◆ ra8_i3c_ibi_drain()

ra8_err_t ra8_i3c_ibi_drain ( ra8_i3c_ibi_t * ibi )

nodiscard

Pop one inbound IBI (alias of ra8_i3c_ibi_read, native mode).

Parameters

[out] ibi Descriptor populated on success.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	One IBI dequeued.
k_ra8_err_no_data	IBI queue empty.
k_ra8_err_null_ptr	`ibi` NULL.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; ibi non-NULL.

Postcondition: On success ibi holds the descriptor.; NTST.IBIQEFF cleared on success.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 888 of file ra8_i3c.c.

References ra8_i3c_ibi_read().

◆ ra8_i3c_ibi_enable()

ra8_err_t ra8_i3c_ibi_enable ( uint8_t target_addr )

nodiscard

Enable inbound IBI capture for a target (native mode).

Parameters

[in] target_addr 7-bit dynamic address authorised to push an IBI.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	IBI capture enabled.
k_ra8_err_invalid_arg	`target_addr` out of range.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; Caller is in IRQ-masked or init context.

Postcondition: NTIBIVCTL.VLCNT is set for the target.; Subsequent IBIs from the target are queued.

Note: Not thread-safe.

Since: 0.1.0

< RA8 I3C ntibivctl one target.

Definition at line 871 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_i3c_addr_mask, k_ra8_i3c_ntibivctl_vlcnt_mask, k_ra8_i3c_ntibivctl_vlcnt_shift, k_ra8_ok, r_i3c_regs_t::NTIBIVCTL, and ra8_i3c().

◆ ra8_i3c_ibi_read()

ra8_err_t ra8_i3c_ibi_read ( ra8_i3c_ibi_t * out_ibi )

nodiscard

Drain one inbound IBI from NIBIQP (native mode).

Parameters

[out] out_ibi Descriptor populated on success.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	One IBI dequeued.
k_ra8_err_no_data	IBI queue empty.
k_ra8_err_null_ptr	`out_ibi` NULL.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; out_ibi non-NULL.

Postcondition: On success out_ibi holds the descriptor.; NTST.IBIQEFF cleared on success.

Note: Not thread-safe.

Since: 0.1.0

< Ibi ID hot join.

< Ibi last mask.

Definition at line 920 of file ra8_i3c.c.

References ra8_i3c_ibi_t::address, internal_ra8_i3c_fifo_read(), k_ra8_err_no_data, k_ra8_i3c_addr_shift_in_ibi_id, k_ra8_i3c_ibi_status_ibi_st_mask, k_ra8_i3c_ibi_status_id_mask, k_ra8_i3c_ibi_status_id_shift, k_ra8_i3c_ibi_status_last_shift, k_ra8_i3c_ibi_status_length_mask, k_ra8_i3c_ibi_status_length_shift, k_ra8_i3c_ibi_type_hot_join, k_ra8_i3c_ibi_type_interrupt, k_ra8_i3c_ibi_type_main_request, k_ra8_i3c_ntst_ibiqeff_mask, k_ra8_ok, ra8_i3c_ibi_t::last, r_i3c_regs_t::NIBIQP, r_i3c_regs_t::NTST, ra8_i3c_ibi_t::payload, ra8_i3c_ibi_t::payload_len, RA8_CHECK_NULL_PTR, ra8_i3c(), s_tag, and ra8_i3c_ibi_t::type.

Referenced by ra8_i3c_ibi_drain().

◆ ra8_i3c_init()

ra8_err_t ra8_i3c_init	(	uint8_t	channel,
		const ra8_i3c_cfg_t *	cfg )

nodiscard

Initialise an I3C channel in the configured mode.

Ungates the I3C MSTP, runs the FSP-mirrored bring-up, and – in I2C mode – programmes the bit-rate from cfg. The channel's mode is recorded so later data-path calls dispatch correctly. Native mode leaves the bus disabled (call ra8_i3c_bus_enable separately).

Parameters

[in]	channel	I3C channel index (0 on RA8D2).
[in]	cfg	Bring-up configuration; must be non-NULL.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Channel ready in the requested mode.
k_ra8_err_null_ptr	`cfg` was NULL.
k_ra8_err_invalid_arg	`channel` out of range, or zero clocks in I2C mode.
k_ra8_err_hw_init_failed	MSTP enable failed.

Precondition: MSTP module is initialized.; No other driver owns the I3C peripheral.

Postcondition: On success the channel's mode equals cfg->mode.; On failure no peripheral state is left half-configured.

Note: Not thread-safe; call from single-threaded init.

Since: 0.1.0

Definition at line 311 of file ra8_i3c.c.

References ra8_i3c_cfg_t::bus_hz, r_i3c_regs_t::INIE, r_i3c_regs_t::INST, r_i3c_regs_t::INSTE, r_i3c_regs_t::INSTFC, internal_ra8_i3c_reset_sequence(), k_ra8_err_invalid_arg, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, k_ra8_mstp_i3c, k_ra8_ok, ra8_i3c_cfg_t::mode, r_i3c_regs_t::MSDVAD, ra8_i3c_cfg_t::pclka_hz, RA8_CHECK_NULL_PTR, ra8_i3c(), ra8_i3c_i2c_init(), ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, s_i3c_chan, and s_tag.

Referenced by combo_setup_or_halt(), i3c_demo_setup_or_halt(), imu_demo_setup_or_halt(), main(), ra8_board_touch_open(), and ra8_nsc_iic_init().

◆ ra8_i3c_peripheral_close()

ra8_err_t ra8_i3c_peripheral_close ( uint8_t channel )

nodiscard

Close responder mode on a channel.

Parameters

[in] channel I3C channel index.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Responder mode closed.
k_ra8_err_invalid_arg	`channel` out of range.
k_ra8_err_invalid_state	Channel is not in I2C mode.

Precondition: Channel was opened in responder mode.; Caller is single-threaded.

Postcondition: The channel no longer answers as a responder.; The bus is released.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 796 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_peripheral_close(), and s_i3c_chan.

◆ ra8_i3c_peripheral_open()

ra8_err_t ra8_i3c_peripheral_open	(	uint8_t	channel,
		const ra8_i3c_peripheral_cfg_t *	cfg )

nodiscard

Open a channel in I2C-compat responder mode.

Parameters

[in]	channel	I3C channel index.
[in]	cfg	Responder configuration; non-NULL.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Responder mode entered.
k_ra8_err_null_ptr	`cfg` NULL.
k_ra8_err_invalid_arg	`channel` or address out of range.
k_ra8_err_invalid_state	Channel is not in I2C mode.

Precondition: Channel initialized in I2C mode.; cfg non-NULL.

Postcondition: The channel answers cfg->peripheral_addr_7b.; No transfer is in progress.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 778 of file ra8_i3c.c.

References ra8_i3c_peripheral_cfg_t::general_call, k_ra8_err_invalid_arg, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, k_ra8_ok, ra8_i3c_peripheral_cfg_t::peripheral_addr_7b, RA8_CHECK_NULL_PTR, ra8_i3c_i2c_peripheral_open(), s_i3c_chan, and s_tag.

Referenced by iic_facade_peripheral_phase(), and internal_iic_peripheral_setup_or_halt().

◆ ra8_i3c_peripheral_receive()

ra8_err_t ra8_i3c_peripheral_receive	(	uint8_t	channel,
		uint8_t *	buf,
		uint32_t	len )

nodiscard

Read bytes the controller wrote (responder mode).

Parameters

[in]	channel	I3C channel index.
[out]	buf	Destination buffer; non-NULL.
[in]	len	Byte count (> 0).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Bytes read.
k_ra8_err_null_ptr	`buf` NULL.
k_ra8_err_invalid_state	Channel is not in I2C mode.

Precondition: Channel opened in responder mode.; buf valid for len.

Postcondition: buf holds the received bytes.; The receive buffer is drained.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 818 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_peripheral_receive(), and s_i3c_chan.

Referenced by iic_facade_service(), and internal_iic_peripheral_service().

◆ ra8_i3c_peripheral_send()

ra8_err_t ra8_i3c_peripheral_send	(	uint8_t	channel,
		const uint8_t *	data,
		uint32_t	len )

nodiscard

Queue bytes for the controller to read (responder mode).

Parameters

[in]	channel	I3C channel index.
[in]	data	Bytes to send; non-NULL when `len` > 0.
[in]	len	Byte count.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Bytes queued.
k_ra8_err_null_ptr	`data` NULL with `len` > 0.
k_ra8_err_invalid_state	Channel is not in I2C mode.

Precondition: Channel opened in responder mode.; data valid for len.

Postcondition: The bytes are staged for the next controller read.; No controller transfer is corrupted.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 807 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_peripheral_send(), and s_i3c_chan.

Referenced by iic_facade_service(), and internal_iic_peripheral_service().

◆ ra8_i3c_peripheral_status()

ra8_err_t ra8_i3c_peripheral_status	(	uint8_t	channel,
		uint8_t *	out_mask )

nodiscard

Read the latched responder-mode status (responder mode).

Parameters

[in]	channel	I3C channel index.
[out]	out_mask	OR of ra8_i3c_peripheral_status_t bits; non-NULL.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Status returned.
k_ra8_err_null_ptr	`out_mask` NULL.
k_ra8_err_invalid_state	Channel is not in I2C mode.

Precondition: Channel opened in responder mode.; out_mask non-NULL.

Postcondition: out_mask holds the latched event bits.; No peripheral state is mutated.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 829 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_peripheral_status(), and s_i3c_chan.

Referenced by iic_facade_service(), and internal_iic_peripheral_service().

◆ ra8_i3c_read()

ra8_err_t ra8_i3c_read	(	uint8_t	channel,
		uint8_t	addr,
		uint8_t *	buf,
		uint32_t	len,
		bool	restart )

nodiscard

Read len bytes from addr.

I2C mode: controller receive from 7-bit addr. Native mode: private SDR read from dynamic address addr; restart is ignored.

Parameters

[in]	channel	I3C channel index.
[in]	addr	7-bit target/dynamic address.
[out]	buf	Destination buffer; must be non-NULL.
[in]	len	Byte count (> 0).
[in]	restart	True to hold the bus for a following transfer (I2C).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	All bytes received.
k_ra8_err_null_ptr	`buf` NULL.
k_ra8_err_invalid_arg	`channel/addr out` of range, or `len` 0.
k_ra8_err_nack	Target did not acknowledge (I2C).
k_ra8_err_hw_timeout	Bus stalled (I2C).

Precondition: Channel initialized.; In native mode the bus is enabled.

Postcondition: On success buf holds the received bytes.; On failure the bus is released (I2C) where possible.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 666 of file ra8_i3c.c.

References internal_ra8_i3c_fifo_read(), internal_ra8_i3c_xfer_cmd_word(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_addr_mask, k_ra8_i3c_cmd_xfer_length_max, k_ra8_i3c_cmd_xfer_length_shift, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, RA8_CHECK_NULL_PTR, ra8_i3c(), ra8_i3c_i2c_read(), s_i3c_chan, and s_tag.

Referenced by er_fg_read(), internal_i3c_compat_read(), and ra8_nsc_iic_read().

◆ ra8_i3c_recv_ccc()

ra8_err_t ra8_i3c_recv_ccc	(	uint8_t	ccc,
		uint8_t	target_addr,
		uint8_t *	buf,
		uint8_t	max_len,
		uint8_t *	got_len )

nodiscard

Generic CCC receive – directed read (native mode).

Parameters

[in]	ccc	Direct CCC opcode (bit 7 set).
[in]	target_addr	Dynamic address.
[out]	buf	Destination buffer.
[in]	max_len	Maximum bytes to drain (> 0).
[out]	got_len	Bytes actually drained.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Read complete.
k_ra8_err_invalid_arg	Non-direct CCC, address bad, or `max_len` 0.
k_ra8_err_null_ptr	Output pointers NULL.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; buf and got_len non-NULL.

Postcondition: buf holds the response bytes.; got_len holds the drained count.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 593 of file ra8_i3c.c.

References internal_ra8_i3c_ccc_cmd_word(), internal_ra8_i3c_fifo_read(), k_ra8_err_invalid_arg, k_ra8_i3c_addr_mask, k_ra8_i3c_ccc_direct_mask, k_ra8_i3c_cmd_xfer_length_shift, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, priv_ra8_i3c_internal_recv_ccc_invalid(), RA8_CHECK_NULL_PTR, ra8_i3c(), and s_tag.

◆ ra8_i3c_reset_dynamic_addresses()

ra8_err_t ra8_i3c_reset_dynamic_addresses ( void )

nodiscard

Issue RSTDAA to clear all dynamic addresses (native mode).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Descriptor queued.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; Caller is single-threaded.

Postcondition: NCMDQP holds the RSTDAA descriptor.; The command-queue-empty flag is cleared.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 539 of file ra8_i3c.c.

References internal_ra8_i3c_ccc_cmd_word(), k_ra8_i3c_ccc_b_rstdaa, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, and ra8_i3c().

◆ ra8_i3c_scan()

ra8_err_t ra8_i3c_scan	(	uint8_t	channel,
		uint8_t	addr,
		bool *	out_acked )

nodiscard

Probe whether a 7-bit address acknowledges (I2C mode).

Parameters

[in]	channel	I3C channel index.
[in]	addr	7-bit address to probe.
[out]	out_acked	Set true if the address ACKed; false otherwise.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Probe completed (see `out_acked`).
k_ra8_err_null_ptr	`out_acked` NULL.
k_ra8_err_invalid_state	Channel is in native mode.

Precondition: Channel initialized in I2C mode.; out_acked is non-NULL.

Postcondition: out_acked reflects the ACK/NACK outcome.; The bus is released with a STOP.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 729 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_scan(), and s_i3c_chan.

Referenced by main().

◆ ra8_i3c_send_ccc()

ra8_err_t ra8_i3c_send_ccc	(	uint8_t	ccc,
		uint8_t	target_addr,
		const uint8_t *	payload,
		uint8_t	len )

nodiscard

Generic CCC send – broadcast or directed write (native mode).

Parameters

[in]	ccc	CCC opcode.
[in]	target_addr	Dynamic address (directed CCCs only).
[in]	payload	Optional payload; NULL when `len` is 0.
[in]	len	Payload byte count.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Descriptor queued.
k_ra8_err_invalid_arg	Address out of range.
k_ra8_err_null_ptr	`payload` NULL with `len` > 0.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; Caller is single-threaded.

Postcondition: NCMDQP holds the CCC descriptor.; Payload (if any) was pushed to NTDTBP0.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 555 of file ra8_i3c.c.

References internal_ra8_i3c_ccc_cmd_word(), internal_ra8_i3c_fifo_write(), k_ra8_err_invalid_arg, k_ra8_err_null_ptr, k_ra8_i3c_addr_mask, k_ra8_i3c_byte_shift, k_ra8_i3c_cmd_attr_immed, k_ra8_i3c_cmd_attr_shift, k_ra8_i3c_cmd_immed_bytes_shift, k_ra8_i3c_cmd_xfer_length_shift, k_ra8_i3c_immediate_max_bytes, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, and ra8_i3c().

◆ ra8_i3c_set_address()

ra8_err_t ra8_i3c_set_address ( uint32_t addr )

nodiscard

Programme the primary dynamic address (native mode).

Parameters

[in] addr 7-bit primary address.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Address programmed.
k_ra8_err_invalid_arg	`addr` out of range.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; Caller is single-threaded.

Postcondition: MSDVAD reflects addr with the valid bit set.; The bus may still be disabled.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 372 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_i3c_msdvad_addr_max, k_ra8_i3c_msdvad_mdyad_mask, k_ra8_i3c_msdvad_mdyad_shift, k_ra8_i3c_msdvad_mdyadv_mask, k_ra8_ok, r_i3c_regs_t::MSDVAD, and ra8_i3c().

◆ ra8_i3c_set_clock()

ra8_err_t ra8_i3c_set_clock	(	uint8_t	channel,
		uint32_t	bus_hz,
		uint32_t	pclka_hz )

nodiscard

Re-programme the I2C bit rate (I2C mode).

Parameters

[in]	channel	I3C channel index.
[in]	bus_hz	Target bus clock in Hz.
[in]	pclka_hz	Source clock for the divider calculation.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Bit rate updated.
k_ra8_err_invalid_arg	`channel` out of range or zero clocks.
k_ra8_err_invalid_state	Channel is in native mode.

Precondition: Channel initialized in I2C mode.; bus_hz and pclka_hz are non-zero.

Postcondition: On success the divider reflects bus_hz / pclka_hz.; On failure the previous divider is unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 718 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_set_clock(), and s_i3c_chan.

◆ ra8_i3c_set_dynamic_address()

ra8_err_t ra8_i3c_set_dynamic_address	(	uint8_t	static_addr,
		uint8_t	dynamic_addr )

nodiscard

Issue SETDASA to assign one target a dynamic address (native mode).

Parameters

[in]	static_addr	7-bit static address in use by the target.
[in]	dynamic_addr	7-bit dynamic address to assign.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Descriptor queued.
k_ra8_err_invalid_arg	Address out of range.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; Caller is single-threaded.

Postcondition: NCMDQP holds the SETDASA descriptor.; The command-queue-empty flag is cleared.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 518 of file ra8_i3c.c.

References internal_ra8_i3c_ccc_cmd_word(), k_ra8_err_invalid_arg, k_ra8_i3c_addr_mask, k_ra8_i3c_ccc_d_setdasa, k_ra8_i3c_cmd_attr_immed, k_ra8_i3c_cmd_attr_shift, k_ra8_i3c_cmd_immed_bytes_shift, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_i3c_setdasa_payload_bytes, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, and ra8_i3c().

◆ ra8_i3c_set_hdr_mode()

ra8_err_t ra8_i3c_set_hdr_mode	(	uint8_t	target_addr,
		ra8_i3c_hdr_mode_t	mode )

nodiscard

Programme the NCMDQP transfer-mode field for a target (native mode).

Parameters

[in]	target_addr	7-bit dynamic address.
[in]	mode	HDR-mode selector.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Descriptor queued.
k_ra8_err_invalid_arg	`target_addr` or `mode` out of range.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode and bus enabled.; Caller is single-threaded.

Postcondition: NCMDQP holds an HDR-mode descriptor.; The command-queue-empty flag is cleared.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 845 of file ra8_i3c.c.

References internal_ra8_i3c_xfer_cmd_word(), k_ra8_err_invalid_arg, k_ra8_i3c_addr_mask, k_ra8_i3c_cmd_hdr_mode_mask, k_ra8_i3c_cmd_xfer_mode_shift, k_ra8_i3c_hdr_mode_ddr, k_ra8_i3c_hdr_mode_sdr, k_ra8_i3c_hdr_mode_ts, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, priv_ra8_i3c_internal_hdr_mode_invalid(), and ra8_i3c().

◆ ra8_i3c_target_open()

ra8_err_t ra8_i3c_target_open ( uint8_t static_addr )

nodiscard

Enter peripheral (target) mode (native mode).

Parameters

[in] static_addr Static (pre-DAA) 7-bit address.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Peripheral mode entered.
k_ra8_err_invalid_arg	`static_addr` out of range.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition: I3C0 initialized in native mode.; Caller is single-threaded init context.

Postcondition: BCTL.SLVE set; BCTL.BUSE clear.; NSDVAD reflects static_addr with the valid bit set.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 893 of file ra8_i3c.c.

References r_i3c_regs_t::BCTL, k_ra8_err_invalid_arg, k_ra8_i3c_addr_mask, k_ra8_i3c_bctl_buse_mask, k_ra8_i3c_bctl_slve_mask, k_ra8_i3c_nsdvad_sdyad_mask, k_ra8_i3c_nsdvad_sdyad_shift, k_ra8_i3c_nsdvad_sdyadv_mask, k_ra8_ok, r_i3c_regs_t::NSDVAD, and ra8_i3c().

◆ ra8_i3c_transfer()

ra8_err_t ra8_i3c_transfer	(	uint8_t	channel,
		uint8_t	addr,
		const uint8_t *	wr,
		uint32_t	wr_len,
		uint8_t *	rd,
		uint32_t	rd_len )

nodiscard

Write-then-read with repeated-START framing (I2C mode).

Transmits wr_len bytes, issues a repeated START, then reads rd_len bytes from the same address. Native mode returns k_ra8_err_invalid_state (use ra8_i3c_write / ra8_i3c_read or CCCs).

Parameters

[in]	channel	I3C channel index.
[in]	addr	7-bit target address.
[in]	wr	Bytes to write; non-NULL when `wr_len` > 0.
[in]	wr_len	Write byte count.
[out]	rd	Read destination; non-NULL when `rd_len` > 0.
[in]	rd_len	Read byte count.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Transfer completed.
k_ra8_err_null_ptr	A required buffer was NULL.
k_ra8_err_invalid_arg	`channel/addr out` of range.
k_ra8_err_invalid_state	Channel is in native mode.
k_ra8_err_nack	Target did not acknowledge.

Precondition: Channel initialized in I2C mode.; wr_len + rd_len > 0.

Postcondition: On success both phases completed and STOP was issued.; On failure the bus is released.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 702 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_transfer(), and s_i3c_chan.

Referenced by imu_demo_iic_read(), and internal_i3c_compat_transfer().

◆ ra8_i3c_write()

ra8_err_t ra8_i3c_write	(	uint8_t	channel,
		uint8_t	addr,
		const uint8_t *	data,
		uint32_t	len,
		bool	restart )

nodiscard

Write len bytes to addr.

In I2C mode this is a controller transmit to 7-bit addr with optional repeated-START framing. In native mode it is a private SDR write to the dynamic address addr; restart is ignored.

Parameters

[in]	channel	I3C channel index.
[in]	addr	7-bit target/dynamic address.
[in]	data	Bytes to transmit; may be NULL only when `len` is 0.
[in]	len	Byte count.
[in]	restart	True to hold the bus for a following transfer (I2C).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	All bytes transmitted.
k_ra8_err_null_ptr	`data` NULL with `len` > 0.
k_ra8_err_invalid_arg	`channel` or `addr` out of range.
k_ra8_err_nack	Target did not acknowledge (I2C).
k_ra8_err_hw_timeout	Bus stalled (I2C).

Precondition: Channel initialized.; In native mode the bus is enabled.

Postcondition: On success the payload has been queued/transmitted.; On failure the bus is released (I2C) where possible.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 621 of file ra8_i3c.c.

References internal_ra8_i3c_fifo_write(), internal_ra8_i3c_xfer_cmd_word(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_i3c_addr_mask, k_ra8_i3c_byte_shift, k_ra8_i3c_cmd_attr_immed, k_ra8_i3c_cmd_attr_shift, k_ra8_i3c_cmd_immed_bytes_shift, k_ra8_i3c_cmd_xfer_length_max, k_ra8_i3c_cmd_xfer_length_shift, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_immediate_max_bytes, k_ra8_i3c_mode_i2c, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, ra8_i3c(), ra8_i3c_i2c_write(), and s_i3c_chan.

Referenced by er_fg_read(), imu_demo_iic_write(), internal_i3c_compat_write(), and ra8_nsc_iic_write().

Variable Documentation

◆ s_i3c_chan

ra8_i3c_chan_state_t s_i3c_chan[k_ra8_i3c_i2c_channel_count]

static

One state slot per I3C channel (RA8D2 exposes I3C0 only).

Definition at line 107 of file ra8_i3c.c.

Referenced by ra8_i3c_abort(), ra8_i3c_clear_errors(), ra8_i3c_deinit(), ra8_i3c_dispatch(), ra8_i3c_get_errors(), ra8_i3c_init(), ra8_i3c_peripheral_close(), ra8_i3c_peripheral_open(), ra8_i3c_peripheral_receive(), ra8_i3c_peripheral_send(), ra8_i3c_peripheral_status(), ra8_i3c_read(), ra8_i3c_scan(), ra8_i3c_set_clock(), ra8_i3c_transfer(), and ra8_i3c_write().

◆ s_i3c_ctx

void* s_i3c_ctx

static

Opaque context handed back to s_i3c_fn.

Definition at line 95 of file ra8_i3c.c.

Referenced by ra8_i3c_attach_handler(), ra8_i3c_deinit(), and ra8_i3c_dispatch().

◆ s_i3c_fn

ra8_i3c_event_fn_t s_i3c_fn

static

Currently registered IRQ callback (NULL when detached).

Definition at line 92 of file ra8_i3c.c.

Referenced by ra8_i3c_attach_handler(), ra8_i3c_deinit(), and ra8_i3c_dispatch().

◆ s_tag

const char* s_tag = "I3C"

static

Logging tag for this module.

Definition at line 89 of file ra8_i3c.c.

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ internal_ra8_i3c_ccc_cmd_word()

◆ internal_ra8_i3c_fifo_read()

◆ internal_ra8_i3c_fifo_write()

◆ internal_ra8_i3c_reset_sequence()

◆ internal_ra8_i3c_xfer_cmd_word()

◆ priv_ra8_i3c_internal_hdr_mode_invalid()

◆ priv_ra8_i3c_internal_recv_ccc_invalid()

◆ ra8_i3c_abort()

◆ ra8_i3c_attach_handler()

◆ ra8_i3c_bus_enable()

◆ ra8_i3c_clear_errors()

◆ ra8_i3c_clear_status()

◆ ra8_i3c_deinit()

◆ ra8_i3c_dispatch()

◆ ra8_i3c_dynamic_address_assign()

◆ ra8_i3c_enter_stop()

◆ ra8_i3c_exit_stop()

◆ ra8_i3c_get_errors()

◆ ra8_i3c_get_status()

◆ ra8_i3c_ibi_drain()

◆ ra8_i3c_ibi_enable()

◆ ra8_i3c_ibi_read()

◆ ra8_i3c_init()

◆ ra8_i3c_peripheral_close()

◆ ra8_i3c_peripheral_open()

◆ ra8_i3c_peripheral_receive()

◆ ra8_i3c_peripheral_send()

◆ ra8_i3c_peripheral_status()

◆ ra8_i3c_read()

◆ ra8_i3c_recv_ccc()

◆ ra8_i3c_reset_dynamic_addresses()

◆ ra8_i3c_scan()

◆ ra8_i3c_send_ccc()

◆ ra8_i3c_set_address()

◆ ra8_i3c_set_clock()

◆ ra8_i3c_set_dynamic_address()

◆ ra8_i3c_set_hdr_mode()

◆ ra8_i3c_target_open()

◆ ra8_i3c_transfer()

◆ ra8_i3c_write()

Variable Documentation

◆ s_i3c_chan

◆ s_i3c_ctx

◆ s_i3c_fn

◆ s_tag