I3C I2C-compatibility backend for the ra8_io I2C-bus facade – thin shim over ra8_i3c. More...

#include "ra8_io_i2c_bus_i3c_compat.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_i3c.h"
#include "ra8_i3c_i2c_regs.h"
#include "ra8_io_i2c_bus.h"
#include "ra8_io_i2c_bus_internal.h"

Include dependency graph for ra8_io_i2c_bus_i3c_compat.c:

Functions
static ra8_err_t	internal_i3c_compat_write (void ctx, uint8_t addr, const uint8_t data, uint32_t len, bool send_stop)
	I3C-compat backend: controller write.
static ra8_err_t	internal_i3c_compat_read (void ctx, uint8_t addr, uint8_t data, uint32_t len)
	I3C-compat backend: controller read.
static ra8_err_t	internal_i3c_compat_transfer (void ctx, uint8_t addr, const uint8_t wr, uint32_t wr_len, uint8_t *rd, uint32_t rd_len)
	I3C-compat backend: write-then-RESTART-then-read.
ra8_err_t	ra8_io_i2c_bus_bind_i3c_compat (ra8_io_i2c_bus_t *bus, uint8_t channel)
	Bind bus to I3C channel channel in I2C-compatibility mode.

Variables
static const char *const	s_tag = "ra8_io_i2c_bus_i3c"
	Module log tag.
static const ra8_io_i2c_bus_iface_t	s_i3c_compat_iface
	I3C I2C-compat backend vtable – every row forwards to ra8_i3c_*.

Detailed Description

I3C I2C-compatibility backend for the ra8_io I2C-bus facade – thin shim over ra8_i3c.

Tag: [Ring 4 / PAL] {World: NS}

Implements ra8_io_i2c_bus_iface by forwarding to the unified I3C driver (ra8_i3c.h) in its I2C-compatibility controller mode, unmodified. The bound channel index travels in the handle context ((void*)(uintptr_t)channel), so the backend keeps no static state.

Semantics adaptation: the facade (like ra8_i2c_write) exposes a send_stop flag, while ra8_i3c_write takes the inverted restart flag ("hold the bus for a following transfer"); the write trampoline negates accordingly. ra8_i3c_read gets restart = false because the facade read always releases the bus, matching ra8_i2c_read. No raw MMIO is touched here; the driver carries every HUM citation.

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

Definition in file ra8_io_i2c_bus_i3c_compat.c.

Function Documentation

◆ internal_i3c_compat_read()

ra8_err_t internal_i3c_compat_read	(	void *	ctx,
		uint8_t	addr,
		uint8_t *	data,
		uint32_t	len )

static

I3C-compat backend: controller read.

Decodes the channel from the handle context and forwards to ra8_i3c_read with restart = false, so the transaction always ends with STOP – the same contract as ra8_i2c_read.

Parameters

[in]	ctx	Bound channel index, encoded as (void*)(uintptr_t).
[in]	addr	7-bit peripheral address.
[out]	data	Destination buffer.
[in]	len	Byte count.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Bytes received.
k_ra8_err_null_ptr	data was NULL.
k_ra8_err_invalid_arg	Channel/addr out of range or len zero.
k_ra8_err_nack	Peripheral NACKed.

Precondition: The channel was initialised via ra8_i3c_init in I2C mode.; ctx carries a channel bound by ra8_io_i2c_bus_bind_i3c_compat.

Postcondition: On success data holds the received bytes.; STOP was issued and the bus released.

Note: Not thread-safe with respect to the same channel.

Since: 0.1.0

Definition at line 110 of file ra8_io_i2c_bus_i3c_compat.c.

References ra8_i3c_read().

◆ internal_i3c_compat_transfer()

ra8_err_t internal_i3c_compat_transfer	(	void *	ctx,
		uint8_t	addr,
		const uint8_t *	wr,
		uint32_t	wr_len,
		uint8_t *	rd,
		uint32_t	rd_len )

static

I3C-compat backend: write-then-RESTART-then-read.

Decodes the channel from the handle context and forwards to ra8_i3c_transfer, which owns the repeated-START framing in I2C mode.

Parameters

[in]	ctx	Bound channel index, encoded as (void*)(uintptr_t).
[in]	addr	7-bit peripheral address.
[in]	wr	Bytes to send first.
[in]	wr_len	Number of bytes to send.
[out]	rd	Destination buffer.
[in]	rd_len	Number of bytes to read.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Both phases completed; STOP issued.
k_ra8_err_null_ptr	A required buffer was NULL.
k_ra8_err_invalid_state	Channel is in native I3C mode.
k_ra8_err_nack	Peripheral NACKed.

Precondition: The channel was initialised via ra8_i3c_init in I2C mode.; ctx carries a channel bound by ra8_io_i2c_bus_bind_i3c_compat.

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

Note: Not thread-safe with respect to the same channel.

Since: 0.1.0

Definition at line 145 of file ra8_io_i2c_bus_i3c_compat.c.

References ra8_i3c_transfer(), and RA8_INTERNAL.

◆ internal_i3c_compat_write()

ra8_err_t internal_i3c_compat_write	(	void *	ctx,
		uint8_t	addr,
		const uint8_t *	data,
		uint32_t	len,
		bool	send_stop )

static

I3C-compat backend: controller write.

Decodes the channel from the handle context and forwards to ra8_i3c_write with restart = !send_stop (the I3C driver's flag says "hold the bus", the facade's says "release it").

Parameters

[in]	ctx	Bound channel index, encoded as (void*)(uintptr_t).
[in]	addr	7-bit peripheral address.
[in]	data	Bytes to send.
[in]	len	Byte count.
[in]	send_stop	true = STOP after payload; false = hold the bus.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Payload transmitted.
k_ra8_err_null_ptr	data NULL with len > 0.
k_ra8_err_nack	Peripheral NACKed.
k_ra8_err_hw_timeout	Bus stalled.

Precondition: The channel was initialised via ra8_i3c_init in I2C mode.; ctx carries a channel bound by ra8_io_i2c_bus_bind_i3c_compat.

Postcondition: On success the payload was transmitted per send_stop.; On failure the bus is released where the driver allows.

Note: Not thread-safe with respect to the same channel.

Since: 0.1.0

Definition at line 71 of file ra8_io_i2c_bus_i3c_compat.c.

References ra8_i3c_write(), and RA8_INTERNAL.

◆ ra8_io_i2c_bus_bind_i3c_compat()

ra8_err_t ra8_io_i2c_bus_bind_i3c_compat	(	ra8_io_i2c_bus_t *	bus,
		uint8_t	channel )

nodiscard

Bind bus to I3C channel channel in I2C-compatibility mode.

Installs the I3C-compat trampoline vtable and records the channel in the handle context. No hardware is touched: initialise the channel with ra8_i3c_init(channel, ...) using k_ra8_i3c_mode_i2c (before or after binding) and route the SCL/SDA pins yourself.

Parameters

[in,out]	bus	Caller-owned handle to bind (non-NULL).
[in]	channel	I3C channel index (only 0 on RA8D2).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	bus now dispatches to ra8_i3c_*.
k_ra8_err_null_ptr	bus was NULL.
k_ra8_err_invalid_arg	channel is out of range.

Precondition: bus points to writable storage.; channel < 1 (the RA8D2 has a single I3C instance).

Postcondition: On success bus->iface is non-NULL and every ra8_io_i2c_bus_* call forwards to I3C channel channel in I2C-compat mode.; On failure bus is left unmodified.

Note: Thread-safe (writes only the caller's handle).

See also: ra8_io_i2c_bus_bind_riic The classic RIIC twin.

Since: 0.1.0

Definition at line 162 of file ra8_io_i2c_bus_i3c_compat.c.

References ra8_io_i2c_bus_t::ctx, ra8_io_i2c_bus_t::iface, k_ra8_err_invalid_arg, k_ra8_i3c_i2c_channel_count, k_ra8_ok, RA8_CHECK_NULL_PTR, s_i3c_compat_iface, and s_tag.

Referenced by main(), and ra8_board_touch_open().

Variable Documentation

◆ s_i3c_compat_iface

const ra8_io_i2c_bus_iface_t s_i3c_compat_iface

static

Initial value:

                                                       = {
  .write    = internal_i3c_compat_write,
  .read     = internal_i3c_compat_read,
  .transfer = internal_i3c_compat_transfer,
}