ra8_esp_hosted_spi_internal.h File Reference

Module-private surface of the esp-hosted full-duplex SPI transport. More...

#include <stdint.h>
#include "esp_hosted_os_abstraction.h"
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_io_spi_bus.h"
#include "ra8_pin_interface.h"

Include dependency graph for ra8_esp_hosted_spi_internal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	ra8_esp_hosted_spi_limits_t : uint8_t {   k_ra8_esp_hosted_spi_mode = 3U ,   k_ra8_esp_hosted_spi_channel_max = 10U }
	Fixed facts about the wire this transport drives. More...

Functions
ra8_err_t	priv_ra8_esp_hosted_spi_bind (hosted_osi_funcs_t *out)
	Populate the three transport slots of the OS-abstraction vtable.
ra8_err_t	priv_ra8_esp_hosted_spi_open (uint8_t sci_channel, uint32_t pclk_hz, uint32_t sck_hz)
	Route the Pmod1 SPI pins and open the SCI Simple-SPI channel.
ra8_err_t	priv_ra8_esp_hosted_spi_close (void)
	Close the SCI Simple-SPI channel and release every pin it took.
bool	priv_ra8_esp_hosted_spi_is_open (void)
	Report whether the SCI Simple-SPI channel is currently open.
void	priv_ra8_esp_hosted_spi_set_bus (const ra8_io_spi_bus_t *bus)
	Replace the SPI bus the transfer slot clocks frames through.
void	priv_ra8_esp_hosted_spi_set_pin_interface (const ra8_pin_interface_t *iface)
	Replace the pin driver the transfer slot drives chip select with.

Detailed Description

Module-private surface of the esp-hosted full-duplex SPI transport.

Tag

[Ring 4 / PORT] {World: NS}

The vendored transport reaches the wire through three slots of hosted_osi_funcs_t – _h_bus_init, _h_bus_deinit and _h_do_bus_transfer – and nothing else. This header declares the first-party side: the slot binder, the two port-facing entry points that open and close the SCI Simple-SPI channel, and the two dependency-injection seams that make the transfer path testable on a host with no silicon.

The link this transport drives

One 1600-byte full-duplex frame per transaction, mode 3, MSB first, with the chip select held low for the whole frame. Mode 3 is not a preference: the co-processor image in coprocessor/esp32c6/ is built CONFIG_ESP_SPI_MODE=3, and k_ra8_esp_hosted_spi_mode is asserted against k_ra8_spi_mode_3 so the two cannot drift apart silently.

Copyright

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

Since

0.1.0

Definition in file ra8_esp_hosted_spi_internal.h.

Enumeration Type Documentation

ra8_esp_hosted_spi_limits_t

enum ra8_esp_hosted_spi_limits_t : uint8_t

Fixed facts about the wire this transport drives.

Both ends of the link agree these values out of band – the co-processor image is built with them – so they are stated once here and asserted against the HAL's own encodings in the implementation.

Invariant

k_ra8_esp_hosted_spi_mode equals k_ra8_spi_mode_3.

k_ra8_esp_hosted_spi_channel_max bounds every channel index the SCI Simple-SPI driver accepts.

Example:

static_assert(k_ra8_esp_hosted_spi_mode == 3U, "C6 is built CONFIG_ESP_SPI_MODE=3");

See also

priv_ra8_esp_hosted_spi_open

Since

0.1.0

Enumerator
k_ra8_esp_hosted_spi_mode	Clock polarity/phase both high: the C6 image's CONFIG_ESP_SPI_MODE.
k_ra8_esp_hosted_spi_channel_max	One past the highest SCI channel index the HAL accepts.

Definition at line 59 of file ra8_esp_hosted_spi_internal.h.

Function Documentation

priv_ra8_esp_hosted_spi_bind()

ra8_err_t priv_ra8_esp_hosted_spi_bind ( hosted_osi_funcs_t * out )

nodiscard

Populate the three transport slots of the OS-abstraction vtable.

Writes _h_bus_init, _h_bus_deinit and _h_do_bus_transfer into out and touches nothing else, so the GPIO and RTOS slices may fill theirs in any order relative to this call.

Parameters

[out]

out

Vtable to populate; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The three rows are populated.
k_ra8_err_null_ptr	out was null.

Precondition

out points at storage that out-lives the vendored core.

priv_ra8_esp_hosted_spi_open has run, or will run before the vendored transport is started.

Postcondition

The three transport rows of out are non-null.

No non-transport row of out is modified.

Note

Not thread-safe; call once from the port's bring-up path.

Example:

(void)priv_ra8_esp_hosted_spi_bind(&g_hosted_osi_funcs);

See also

priv_ra8_esp_hosted_gpio_bind

Since

0.1.0

Definition at line 524 of file ra8_esp_hosted_spi.c.

References internal_bus_deinit(), internal_bus_init(), internal_do_bus_transfer(), k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_PRIV, and s_tag.

Referenced by priv_ra8_esp_hosted_osi_bind_all().

priv_ra8_esp_hosted_spi_close()

ra8_err_t priv_ra8_esp_hosted_spi_close ( void )

nodiscard

Close the SCI Simple-SPI channel and release every pin it took.

Exact reverse of priv_ra8_esp_hosted_spi_open: the channel is disabled and its module-stop gate released, then the chip select and the three routed data pins are handed back to the pin validator. The bound bus handle is cleared so a later transfer attempt fails rather than driving a dead channel.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Everything was released.
k_ra8_err_not_initialized	The bus was not open.
k_ra8_err_spi_error	The HAL refused to disable the channel.

Precondition

The vendored transport has stopped clocking frames.

No transfer is in flight.

Postcondition

Every pin priv_ra8_esp_hosted_spi_open claimed is released.

A later _h_do_bus_transfer reports failure rather than clocking.

Note

Not thread-safe; call from the same context as the open.

Example:

(void)priv_ra8_esp_hosted_spi_close();

See also

priv_ra8_esp_hosted_spi_open

Since

0.1.0

Definition at line 360 of file ra8_esp_hosted_spi.c.

References internal_release_pins(), k_ra8_err_not_initialized, k_ra8_err_spi_error, k_ra8_ok, RA8_PRIV, ra8_sci_spi_deinit(), s_bus, s_channel, and s_open.

Referenced by internal_bus_deinit(), and internal_unwind().

priv_ra8_esp_hosted_spi_is_open()

bool priv_ra8_esp_hosted_spi_is_open ( void )

nodiscard

Report whether the SCI Simple-SPI channel is currently open.

Reads the single module-state flag, so the port can decide whether a close is needed and tests can assert the open/close state machine without reaching into the module.

Returns

Whether priv_ra8_esp_hosted_spi_open has completed with no close since.

Return values

true	The channel is open and bound.
false	The channel was never opened, failed to open, or was closed.

Precondition

None; safe to call at any time.

The caller tolerates a value a concurrent close may stale.

Postcondition

No module state is modified.

The result reflects the flag at the moment of the read.

Note

Safe from interrupt context; a single aligned load.

Example:

if (priv_ra8_esp_hosted_spi_is_open()) { (void)priv_ra8_esp_hosted_spi_close(); }

See also

priv_ra8_esp_hosted_spi_open

Since

0.1.0

Definition at line 372 of file ra8_esp_hosted_spi.c.

References RA8_PRIV, and s_open.

priv_ra8_esp_hosted_spi_open()

ra8_err_t priv_ra8_esp_hosted_spi_open ( uint8_t sci_channel, uint32_t pclk_hz, uint32_t sck_hz )

nodiscard

Route the Pmod1 SPI pins and open the SCI Simple-SPI channel.

Performs, in order: route SCK, COPI and CIPO to the SCI peripheral through the PFS; take the chip select as a GPIO output idling high (deasserted); bring the SCI channel up at mode 3, MSB first, at the requested bit rate; and bind the channel into the ra8_io SPI-bus facade so the transfer slot can drive it. Any failure unwinds the steps already taken, so a failed open leaves no pin claimed.

The channel argument must name the Pmod1 Simple-SPI channel. The port routes the Pmod1 pin trio and nothing else, so accepting a different channel would clock a peripheral whose pins were never routed.

Parameters

[in]	sci_channel	SCI channel carrying Simple-SPI; must equal the board's Pmod1 channel.
[in]	pclk_hz	Live PCLKA rate in hertz; non-zero.
[in]	sck_hz	Requested bit rate in hertz; non-zero.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The bus is open and bound.
k_ra8_err_invalid_arg	A clock was zero, or the channel is not the Pmod1 one.
k_ra8_err_invalid_state	The bus is already open.
k_ra8_err_gpio_conflict	A link pin is owned by another module.
k_ra8_err_spi_error	The SCI channel would not come up.

Precondition

The CGC is configured and pclk_hz reflects the live PCLKA rate.

The Pmod1 mode mux is in its SPI position (board switch SW4-3 on).

Postcondition

On success the chip select idles high and the channel is enabled.

On failure no pin is left claimed and the channel is left disabled.

Note

Not thread-safe; call once from the port's bring-up path.

Warning

Opening the bus does not talk to the co-processor; the first traffic is whatever the vendored transport clocks out.

Example:

(void)priv_ra8_esp_hosted_spi_open(cfg->sci_channel, cfg->pclk_hz, cfg->sck_hz);

See also

priv_ra8_esp_hosted_spi_close

Since

0.1.0

Definition at line 311 of file ra8_esp_hosted_spi.c.

References ra8_pin_interface_t::ctx, internal_pin_if(), internal_release_pins(), internal_route_data_pins(), k_ra8_board_pmod1_sci_channel, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_spi_error, k_ra8_esp_hosted_pin_chip_select, k_ra8_esp_hosted_spi_mode, k_ra8_level_high, k_ra8_ok, ra8_pin_interface_t::output_init, ra8_io_spi_bus_bind_sci_spi(), ra8_log_error_val, ra8_log_info_val, RA8_PRIV, ra8_sci_spi_deinit(), ra8_sci_spi_init(), s_bus, s_channel, s_open, and s_tag.

Referenced by internal_bring_up().

priv_ra8_esp_hosted_spi_set_bus()

void priv_ra8_esp_hosted_spi_set_bus

(

const ra8_io_spi_bus_t *

bus

)

Replace the SPI bus the transfer slot clocks frames through.

Dependency-injection seam. Production leaves it unset, in which case the slot uses the handle priv_ra8_esp_hosted_spi_open bound to the SCI channel. Host tests point it at a recording ra8_io_spi_bus_iface so the whole transfer path – argument validation, chip-select sequencing, error propagation – runs with no silicon and no open channel.

Parameters

[in]

bus

Replacement bus handle, or null to fall back on the handle the open bound. Must out-live every later transfer.

Precondition

bus, when non-null, has a bound backend vtable.

No transfer is in flight.

Postcondition

Later transfers clock through bus.

Passing null restores the internally bound handle.

Note

Not thread-safe; intended for bring-up and for tests.

Warning

Injecting a bus does not open a channel; the two are independent.

Example:

priv_ra8_esp_hosted_spi_set_bus(&mock_bus);

See also

priv_ra8_esp_hosted_spi_open

Since

0.1.0

Definition at line 377 of file ra8_esp_hosted_spi.c.

References RA8_PRIV, and s_injected_bus.

priv_ra8_esp_hosted_spi_set_pin_interface()

void priv_ra8_esp_hosted_spi_set_pin_interface

(

const ra8_pin_interface_t *

iface

)

Replace the pin driver the transfer slot drives chip select with.

Dependency-injection seam, separate from the GPIO slice's own seam because the two translation units are independent. Production leaves it at g_ra8_gpio_pin_interface; tests point it at a recorder so the order of "chip select low, frame, chip select high" can be asserted rather than assumed.

Parameters

[in]

iface

Replacement interface, or null to restore the production instance. Must out-live every later transfer.

Precondition

iface, when non-null, has non-null output_init and write rows.

No transfer is in flight.

Postcondition

Later chip-select transitions go through iface.

Passing null restores the production pin driver.

Note

Not thread-safe; intended for bring-up and for tests.

Example:

priv_ra8_esp_hosted_spi_set_pin_interface(&mock_pin_iface);

See also

priv_ra8_esp_hosted_spi_set_bus

Since

0.1.0

Definition at line 382 of file ra8_esp_hosted_spi.c.

References RA8_PRIV, and s_pin_if.