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

#include "ra8_io_spi_bus.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_io_spi_bus_internal.h"
#include "ra8_spi.h"
#include "ra8_spi_bus_ops.h"

Include dependency graph for ra8_io_spi_bus.c:

Functions
static ra8_err_t	internal_validate (const ra8_io_spi_bus_t *bus)
	Reject a handle that is NULL or has no backend bound.
ra8_err_t	ra8_io_spi_bus_xfer8 (const ra8_io_spi_bus_t bus, uint8_t tx, uint8_t rx)
	Full-duplex single-byte exchange on the bound bus.
ra8_err_t	ra8_io_spi_bus_write_read (const ra8_io_spi_bus_t bus, const void tx, void *rx, uint32_t len, ra8_spi_bit_width_t width)
	Full-duplex multi-frame transfer on the bound bus.
ra8_err_t	ra8_io_spi_bus_set_clock (const ra8_io_spi_bus_t *bus, uint32_t baud_hz, uint32_t pclk_hz)
	Re-program the bound bus bit-rate without reconfiguring.
static ra8_err_t	internal_ops_xfer8 (void ctx, uint8_t tx, uint8_t rx)
	Seam trampoline – forward an xfer8 into the bound bus.
ra8_err_t	ra8_io_spi_bus_as_ops (const ra8_io_spi_bus_t bus, ra8_spi_bus_ops_t out)
	Expose a bound bus through the Ring-3 seam ra8_spi_bus_ops_t.

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

Detailed Description

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

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

Stateless dispatcher: it validates the handle, then forwards through the bound ra8_io_spi_bus_iface. The bridge installs a static trampoline whose ctx is the ra8_io_spi_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_spi_bus.c.

Function Documentation

◆ internal_ops_xfer8()

ra8_err_t internal_ops_xfer8	(	void *	ctx,
		uint8_t	tx,
		uint8_t *	rx )

static

Seam trampoline – forward an xfer8 into the bound bus.

Casts the seam cookie back to the bus handle and dispatches the byte exchange through ra8_io_spi_bus_xfer8.

Parameters

[in]	ctx	The ra8_io_spi_bus_t handle (as a void cookie).
[in]	tx	Byte to transmit.
[out]	rx	Receive slot; may be NULL to discard.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Frame exchanged.
k_ra8_err_null_ptr	ctx was NULL.
k_ra8_err_*	Propagated from ra8_io_spi_bus_xfer8.

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

Postcondition: On success one frame was clocked.; No handle state is mutated.

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

Since: 0.1.0

Definition at line 144 of file ra8_io_spi_bus.c.

References RA8_CHECK_NULL_PTR, ra8_io_spi_bus_xfer8(), and s_tag.

Referenced by ra8_io_spi_bus_as_ops().

◆ internal_validate()

ra8_err_t internal_validate ( const ra8_io_spi_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 63 of file ra8_io_spi_bus.c.

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

Referenced by ra8_io_spi_bus_as_ops(), ra8_io_spi_bus_set_clock(), ra8_io_spi_bus_write_read(), and ra8_io_spi_bus_xfer8().

◆ ra8_io_spi_bus_as_ops()

ra8_err_t ra8_io_spi_bus_as_ops	(	const ra8_io_spi_bus_t *	bus,
		ra8_spi_bus_ops_t *	out )

nodiscard

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

Fills out with a trampoline that forwards the seam's xfer8 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_epaper) 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 out->xfer8 is 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_spi_bus_ops_t The Ring-3 seam definition.

Since: 0.1.0

Definition at line 150 of file ra8_io_spi_bus.c.

References ra8_spi_bus_ops_t::ctx, internal_ops_xfer8(), internal_validate(), k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_spi_bus_ops_t::xfer8.

Referenced by ep_bringup_panel_bus().

◆ ra8_io_spi_bus_set_clock()

ra8_err_t ra8_io_spi_bus_set_clock	(	const ra8_io_spi_bus_t *	bus,
		uint32_t	baud_hz,
		uint32_t	pclk_hz )

nodiscard

Re-program the bound bus bit-rate without reconfiguring.

Forwards to ra8_spi_set_clock / ra8_sci_spi_set_clock. Used by protocols that must start slow and speed up after negotiation (e.g. the SD-card 400 kHz identification phase).

Parameters

[in]	bus	Bound bus handle.
[in]	baud_hz	Target bit-rate in Hz (non-zero).
[in]	pclk_hz	Current peripheral clock in Hz (PCLKA on RA8D2).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Bit-rate divider reprogrammed.
k_ra8_err_null_ptr	bus was NULL.
k_ra8_err_not_initialized	No backend is bound to bus.
k_ra8_err_invalid_arg	baud_hz zero or divider out of range.

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

Postcondition: On success the channel's divider reflects the new rate.; On any non-ok return no caller-visible handle state changed.

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

Since: 0.1.0

Definition at line 103 of file ra8_io_spi_bus.c.

References ra8_io_spi_bus_t::ctx, ra8_io_spi_bus_t::iface, internal_validate(), k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_io_spi_bus_iface::set_clock.

◆ ra8_io_spi_bus_write_read()

ra8_err_t ra8_io_spi_bus_write_read	(	const ra8_io_spi_bus_t *	bus,
		const void *	tx,
		void *	rx,
		uint32_t	len,
		ra8_spi_bit_width_t	width )

nodiscard

Full-duplex multi-frame transfer on the bound bus.

Forwards to the backend's bulk primitive (ra8_spi_write_read or ra8_sci_spi_xfer). Either buffer may be NULL: a NULL tx shifts idle fill bytes (SD / SPI-flash read convention) and a NULL rx discards the received bytes; both NULL is rejected by the backend. len == 0 is a no-op success. The SCI Simple-SPI backend supports 8-bit frames only and reports k_ra8_err_not_supported for wider width values.

Parameters

[in]	bus	Bound bus handle.
[in]	tx	Source buffer (len units of width) or NULL.
[out]	rx	Destination buffer (len units of width) or NULL.
[in]	len	Number of frames to exchange.
[in]	width	Per-frame bit width (ra8_spi_bit_width_t).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Every frame exchanged.
k_ra8_err_null_ptr	bus was NULL, or both buffers NULL with len > 0.
k_ra8_err_not_initialized	No backend is bound to bus.
k_ra8_err_not_supported	Backend cannot do width (SCI != 8).
k_ra8_err_hw_timeout	The transport's status poll expired.

Precondition: A backend has been bound into bus.; Buffer alignment matches width (16/32-bit frames need aligned pointers on the SPI_B backend).

Postcondition: On success len frames were clocked in both directions.; On any non-ok return no caller-visible handle state changed.

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

See also: ra8_io_spi_bus_xfer8 Single-byte variant.

Since: 0.1.0

Definition at line 89 of file ra8_io_spi_bus.c.

References ra8_io_spi_bus_t::ctx, ra8_io_spi_bus_t::iface, internal_validate(), k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_io_spi_bus_iface::write_read.

Referenced by internal_do_bus_transfer().

◆ ra8_io_spi_bus_xfer8()

ra8_err_t ra8_io_spi_bus_xfer8	(	const ra8_io_spi_bus_t *	bus,
		uint8_t	tx,
		uint8_t *	rx )

nodiscard

Full-duplex single-byte exchange on the bound bus.

Forwards to the bound backend's xfer8 primitive (ra8_spi_xfer8 or ra8_sci_spi_xfer8): shifts tx out on COPI and captures the CIPO byte into *rx.

Parameters

[in]	bus	Bound bus handle.
[in]	tx	Byte to transmit.
[out]	rx	Receive slot; may be NULL to discard the received byte.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Frame exchanged.
k_ra8_err_null_ptr	bus was NULL.
k_ra8_err_not_initialized	No backend is bound to bus.
k_ra8_err_hw_timeout	The transport's status poll expired.

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

Postcondition: On success one frame was clocked; *rx (if non-NULL) holds the received byte.; On any non-ok return no caller-visible handle state changed.

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

See also: ra8_io_spi_bus_write_read Multi-frame variant.

Since: 0.1.0

Definition at line 79 of file ra8_io_spi_bus.c.

References ra8_io_spi_bus_t::ctx, ra8_io_spi_bus_t::iface, internal_validate(), k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_io_spi_bus_iface::xfer8.

Referenced by internal_ops_xfer8().

Variable Documentation

◆ s_tag

const char* const s_tag = "ra8_io_spi_bus"

static

Module log tag.

Definition at line 32 of file ra8_io_spi_bus.c.

Functions

Variables

Detailed Description

Function Documentation

◆ internal_ops_xfer8()

◆ internal_validate()

◆ ra8_io_spi_bus_as_ops()

◆ ra8_io_spi_bus_set_clock()

◆ ra8_io_spi_bus_write_read()

◆ ra8_io_spi_bus_xfer8()

Variable Documentation

◆ s_tag