I2C-bus dispatcher – forwards each public call into the bound backend vtable, and bridges any backend to an ra8_i2c_bus_ops_t. More...

#include "ra8_io_i2c_bus.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_i2c_bus_ops.h"
#include "ra8_io_i2c_bus_internal.h"

Include dependency graph for ra8_io_i2c_bus.c:

Functions
static ra8_err_t	internal_validate (const ra8_io_i2c_bus_t *bus)
	Reject a handle that is NULL or has no backend bound.
ra8_err_t	ra8_io_i2c_bus_write (const ra8_io_i2c_bus_t bus, uint8_t addr, const uint8_t data, uint32_t len, bool send_stop)
	Controller write of len bytes to 7-bit address addr.
ra8_err_t	ra8_io_i2c_bus_read (const ra8_io_i2c_bus_t bus, uint8_t addr, uint8_t data, uint32_t len)
	Controller read of len bytes from 7-bit address addr.
ra8_err_t	ra8_io_i2c_bus_transfer (const ra8_io_i2c_bus_t bus, uint8_t addr, const uint8_t wr, uint32_t wr_len, uint8_t *rd, uint32_t rd_len)
	Combined write-then-RESTART-then-read in one bus transaction.
static ra8_err_t	internal_ops_write (void ctx, uint8_t addr, const uint8_t data, uint32_t len, bool send_stop)
	Seam trampoline – forward a controller write into the bound bus.
static ra8_err_t	internal_ops_read (void ctx, uint8_t addr, uint8_t data, uint32_t len)
	Seam trampoline – forward a controller read into the bound bus.
static ra8_err_t	internal_ops_transfer (void ctx, uint8_t addr, const uint8_t wr, uint32_t wr_len, uint8_t *rd, uint32_t rd_len)
	Seam trampoline – forward a combined transfer into the bound bus.
ra8_err_t	ra8_io_i2c_bus_as_ops (const ra8_io_i2c_bus_t bus, ra8_i2c_bus_ops_t out)
	Expose a bound bus through the Ring-3 seam ra8_i2c_bus_ops_t.

Variables
static const char *const	s_tag = "ra8_io_i2c_bus"
	Module log tag.

Detailed Description

I2C-bus dispatcher – forwards each public call into the bound backend vtable, and bridges any backend to an ra8_i2c_bus_ops_t.

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

Stateless dispatcher: it validates the handle, then forwards through the bound ra8_io_i2c_bus_iface. The bridge installs static trampolines whose ctx is the ra8_io_i2c_bus_t itself, mirroring the ra8_io_blockdev_as_fs_backend() idiom. No MMIO is touched here; the wrapped drivers carry every HUM citation.

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

Definition in file ra8_io_i2c_bus.c.

Function Documentation

◆ internal_ops_read()

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

static

Seam trampoline – forward a controller read into the bound bus.

Casts the seam cookie back to the bus handle and dispatches the read through ra8_io_i2c_bus_read.

Parameters

[in]	ctx	The ra8_io_i2c_bus_t handle (as a void cookie).
[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	ctx was NULL.
k_ra8_err_*	Propagated from ra8_io_i2c_bus_read.

Precondition: ctx is a bound ra8_io_i2c_bus_t.; The underlying channel was initialised by its own driver init.

Postcondition: On success data holds the received bytes.; No handle state is mutated.

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

Since: 0.1.0

Definition at line 185 of file ra8_io_i2c_bus.c.

References RA8_CHECK_NULL_PTR, ra8_io_i2c_bus_read(), and s_tag.

Referenced by ra8_io_i2c_bus_as_ops().

◆ internal_ops_transfer()

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

static

Seam trampoline – forward a combined transfer into the bound bus.

Casts the seam cookie back to the bus handle and dispatches the write-then-RESTART-then-read through ra8_io_i2c_bus_transfer.

Parameters

[in]	ctx	The ra8_io_i2c_bus_t handle (as a void cookie).
[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.
k_ra8_err_null_ptr	ctx was NULL.
k_ra8_err_*	Propagated from ra8_io_i2c_bus_transfer.

Precondition: ctx is a bound ra8_io_i2c_bus_t.; The underlying channel was initialised by its own driver init.

Postcondition: On success both phases completed and STOP was issued.; No handle state is mutated.

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

Since: 0.1.0

Definition at line 220 of file ra8_io_i2c_bus.c.

References RA8_CHECK_NULL_PTR, ra8_io_i2c_bus_transfer(), and s_tag.

Referenced by ra8_io_i2c_bus_as_ops().

◆ internal_ops_write()

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

static

Seam trampoline – forward a controller write into the bound bus.

Casts the seam cookie back to the bus handle and dispatches the write through ra8_io_i2c_bus_write.

Parameters

[in]	ctx	The ra8_io_i2c_bus_t handle (as a void cookie).
[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	ctx was NULL.
k_ra8_err_*	Propagated from ra8_io_i2c_bus_write.

Precondition: ctx is a bound ra8_io_i2c_bus_t.; The underlying channel was initialised by its own driver init.

Postcondition: On success the payload has been transmitted.; No handle state is mutated.

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

Since: 0.1.0

Definition at line 152 of file ra8_io_i2c_bus.c.

References RA8_CHECK_NULL_PTR, ra8_io_i2c_bus_write(), and s_tag.

Referenced by ra8_io_i2c_bus_as_ops().

◆ internal_validate()

ra8_err_t internal_validate ( const ra8_io_i2c_bus_t * bus )

static

Reject a handle that is NULL or has no backend bound.

Run on every dispatch path. Kept tiny so each public entry point stays well under the NASA Power-of-10 Rule 4 sixty-line cap.

Parameters

[in] bus Candidate handle.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	bus is non-NULL with a bound backend.
k_ra8_err_null_ptr	bus was NULL.
k_ra8_err_not_initialized	bus->iface was NULL (never bound).

Precondition: None.; None.

Postcondition: No state is mutated.; The return reflects only the binding state of bus.

Note: Thread-safe.

Since: 0.1.0

Definition at line 62 of file ra8_io_i2c_bus.c.

References ra8_io_i2c_bus_t::iface, k_ra8_err_not_initialized, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by ra8_io_i2c_bus_as_ops(), ra8_io_i2c_bus_read(), ra8_io_i2c_bus_transfer(), and ra8_io_i2c_bus_write().

◆ ra8_io_i2c_bus_as_ops()

ra8_err_t ra8_io_i2c_bus_as_ops	(	const ra8_io_i2c_bus_t *	bus,
		ra8_i2c_bus_ops_t *	out )

nodiscard

Expose a bound bus through the Ring-3 seam ra8_i2c_bus_ops_t.

Fills out with trampolines that forward the seam's write / read / transfer into this facade, with out->ctx pointing at bus. This is the sanctioned bridge for handing a bound bus to a Ring-3 device driver (e.g. ra8_touch, ra8_smbus) without the driver depending upward on ra8_io – the exact analogue of ra8_io_blockdev_as_fs_backend().

Parameters

[in]	bus	Bound bus handle (must out-live every seam call).
[out]	out	Seam to populate.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	*out wired to bus.
k_ra8_err_null_ptr	bus or out was NULL.
k_ra8_err_not_initialized	No backend is bound to bus.

Precondition: A backend has been bound into bus.; out is writable and out-lives no call made through it after bus is destroyed.

Postcondition: On success all three seam rows are non-NULL and out->ctx references bus.; No bus or handle state is mutated.

Note: bus must remain valid for the entire lifetime of the seam.

See also: ra8_i2c_bus_ops_t The Ring-3 seam definition.

Since: 0.1.0

Definition at line 231 of file ra8_io_i2c_bus.c.

References ra8_i2c_bus_ops_t::ctx, internal_ops_read(), internal_ops_transfer(), internal_ops_write(), internal_validate(), k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_i2c_bus_ops_t::read, s_tag, ra8_i2c_bus_ops_t::transfer, and ra8_i2c_bus_ops_t::write.

Referenced by main(), and ra8_board_touch_open().

◆ ra8_io_i2c_bus_read()

ra8_err_t ra8_io_i2c_bus_read	(	const ra8_io_i2c_bus_t *	bus,
		uint8_t	addr,
		uint8_t *	data,
		uint32_t	len )

nodiscard

Controller read of len bytes from 7-bit address addr.

Forwards to the bound backend's read primitive (ra8_i2c_read or ra8_i3c_read). Issues START, the address byte with R/W# = 1, drains len bytes, then issues STOP and releases the bus.

Parameters

[in]	bus	Bound bus handle.
[out]	data	Destination buffer (non-NULL).
[in]	addr	7-bit peripheral address.
[in]	len	Byte count (non-zero).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Bytes received.
k_ra8_err_null_ptr	bus or data was NULL.
k_ra8_err_not_initialized	No backend is bound to bus.
k_ra8_err_invalid_arg	len is zero.
k_ra8_err_nack	Peripheral did not acknowledge.
k_ra8_err_hw_timeout	Bus stalled.

Precondition: A backend has been bound into bus.; The underlying channel was initialised by its own driver init.

Postcondition: On success data[0 .. len) holds the received bytes.; STOP was issued and the bus released (success or failure).

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

See also: ra8_io_i2c_bus_write Controller-write counterpart.

Since: 0.1.0

Definition at line 93 of file ra8_io_i2c_bus.c.

References ra8_io_i2c_bus_t::ctx, ra8_io_i2c_bus_t::iface, internal_validate(), k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_io_i2c_bus_iface::read, and s_tag.

Referenced by internal_ops_read().

◆ ra8_io_i2c_bus_transfer()

ra8_err_t ra8_io_i2c_bus_transfer	(	const ra8_io_i2c_bus_t *	bus,
		uint8_t	addr,
		const uint8_t *	wr,
		uint32_t	wr_len,
		uint8_t *	rd,
		uint32_t	rd_len )

nodiscard

Combined write-then-RESTART-then-read in one bus transaction.

Forwards to the bound backend's combined primitive (ra8_i2c_transfer or ra8_i3c_transfer) – the classic "address a register, read its contents" shape: write wr_len bytes, repeated START, read rd_len bytes, STOP.

Parameters

[in]	bus	Bound bus handle.
[in]	addr	7-bit peripheral address.
[in]	wr	Bytes to send first (NULL only when wr_len 0).
[in]	wr_len	Number of bytes to send.
[out]	rd	Destination buffer (NULL only when rd_len 0).
[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	bus was NULL, or a required buffer was NULL.
k_ra8_err_not_initialized	No backend is bound to bus.
k_ra8_err_invalid_arg	Both lengths zero.
k_ra8_err_nack	Peripheral did not acknowledge.
k_ra8_err_hw_timeout	Bus stalled.

Precondition: A backend has been bound into bus.; The underlying channel was initialised by its own driver init.

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

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

Since: 0.1.0

Definition at line 103 of file ra8_io_i2c_bus.c.

References ra8_io_i2c_bus_t::ctx, ra8_io_i2c_bus_t::iface, internal_validate(), k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_io_i2c_bus_iface::transfer.

Referenced by iic_facade_controller_phase(), and internal_ops_transfer().

◆ ra8_io_i2c_bus_write()

ra8_err_t ra8_io_i2c_bus_write	(	const ra8_io_i2c_bus_t *	bus,
		uint8_t	addr,
		const uint8_t *	data,
		uint32_t	len,
		bool	send_stop )

nodiscard

Controller write of len bytes to 7-bit address addr.

Forwards to the bound backend's write primitive (ra8_i2c_write or ra8_i3c_write; the I3C driver's inverted restart flag is adapted by the backend). When send_stop is true the transaction ends with STOP; when false the bus is held so the next call injects a repeated-START.

Parameters

[in]	bus	Bound bus handle.
[in]	addr	7-bit peripheral address.
[in]	data	Bytes to send (non-NULL when len > 0).
[in]	len	Byte count.
[in]	send_stop	true = STOP after the payload; false = hold the bus.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Payload transmitted.
k_ra8_err_null_ptr	bus was NULL, or data NULL with len > 0.
k_ra8_err_not_initialized	No backend is bound to bus.
k_ra8_err_nack	Peripheral did not acknowledge.
k_ra8_err_hw_timeout	Bus stalled.

Precondition: A backend has been bound into bus.; The underlying channel was initialised by its own driver init.

Postcondition: On success the payload has been transmitted per send_stop.; On failure the bus is released where the transport allows.

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

See also: ra8_io_i2c_bus_transfer Write-then-read in one transaction.

Since: 0.1.0

Definition at line 78 of file ra8_io_i2c_bus.c.

References ra8_io_i2c_bus_t::ctx, ra8_io_i2c_bus_t::iface, internal_validate(), k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_io_i2c_bus_iface::write.

Referenced by internal_ops_write().

Variable Documentation

◆ s_tag

const char* const s_tag = "ra8_io_i2c_bus"

static

Module log tag.

Definition at line 31 of file ra8_io_i2c_bus.c.

Functions

Variables

Detailed Description

Function Documentation

◆ internal_ops_read()

◆ internal_ops_transfer()

◆ internal_ops_write()

◆ internal_validate()

◆ ra8_io_i2c_bus_as_ops()

◆ ra8_io_i2c_bus_read()

◆ ra8_io_i2c_bus_transfer()

◆ ra8_io_i2c_bus_write()

Variable Documentation

◆ s_tag