ra8_esp_hosted_c6link.c File Reference

The three trampolines that put ra8_c6link on this board's wire. More...

#include "ra8_esp_hosted_c6link.h"
#include <stdint.h>
#include <string.h>
#include "esp_hosted_os_abstraction.h"
#include "port_esp_hosted_host_config.h"
#include "port_esp_hosted_host_os.h"
#include "port_esp_hosted_host_spi.h"
#include "ra8_attributes.h"
#include "ra8_c6link.h"
#include "ra8_c6link_transport.h"
#include "ra8_err.h"
#include "ra8_esp_hosted_port.h"
#include "transport_drv.h"

Include dependency graph for ra8_esp_hosted_c6link.c:

Go to the source code of this file.

Functions
static ra8_err_t	internal_ra8_esp_hosted_c6link_transfer (void *ctx, const uint8_t *tx, uint8_t *rx, uint16_t len)
	Clock one full-duplex transaction through the port's SPI slice.
static bool	internal_ra8_esp_hosted_c6link_handshake (void *ctx)
	Sample the HANDSHAKE line through the port's GPIO slice.
static void	internal_ra8_esp_hosted_c6link_delay (void *ctx, uint16_t ms)
	Yield for approximately the requested number of milliseconds.
ra8_err_t	ra8_esp_hosted_c6link_bind (ra8_c6link_transport_t *out)
	Fill a ra8_c6link transport seam with this port's implementations.

Variables
static uint8_t	s_ra8_esp_hosted_c6link_tx [k_ra8_c6link_frame_bytes]
	DMA-aligned staging buffer the transmit frame is clocked from.

Detailed Description

The three trampolines that put ra8_c6link on this board's wire.

Tag

[Ring 4 / PORT] {World: NS}

Each row goes through the vendored OS-abstraction vtable rather than straight to the HAL, so the facade clocks its transactions through exactly the code path the vendored driver would use. That is what makes a bench result from the facade a bench result about the port: if the two used different paths, a passing facade would say nothing about the driver.

Copyright

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

Since

0.1.0

Definition in file ra8_esp_hosted_c6link.c.

Function Documentation

internal_ra8_esp_hosted_c6link_delay()

void internal_ra8_esp_hosted_c6link_delay ( void * ctx, uint16_t ms )

static

Yield for approximately the requested number of milliseconds.

The port's sleep is an RTOS sleep; routing it through the seam is what lets a host test bind one that costs no wall time.

Parameters

[in]	ctx	Unused; the port is a singleton.
[in]	ms	Milliseconds to sleep.

Returns

Nothing.

Precondition

ra8_esp_hosted_port_init has succeeded, or the call is a no-op.

The caller is a thread, not an interrupt handler.

Postcondition

At least ms milliseconds of ThreadX ticks have elapsed.

No port state is modified.

Note

The whole point of routing this through the seam is that a host test binds a delay that costs no wall time.

Since

0.1.0

Definition at line 142 of file ra8_esp_hosted_c6link.c.

References g_h, ra8_esp_hosted_port_is_ready(), and RA8_INTERNAL.

Referenced by ra8_esp_hosted_c6link_bind().

internal_ra8_esp_hosted_c6link_handshake()

bool internal_ra8_esp_hosted_c6link_handshake ( void * ctx )

static

Sample the HANDSHAKE line through the port's GPIO slice.

Reads the line through the same vtable row the vendored driver reads it through, so a bench result about the facade is a bench result about the port.

Parameters

[in]

ctx

Unused; the port is a singleton.

Returns

true when the co-processor has armed itself for a transaction.

Return values

true	HANDSHAKE reads at its active level.
false	It does not, or the port is not up.

Precondition

ra8_esp_hosted_port_init has succeeded, or the answer is false.

HANDSHAKE has been configured as an input by the port.

Postcondition

No port state is modified.

Exactly one pin read was performed.

Note

Read through the vtable rather than the GPIO HAL, so the facade sees exactly what the vendored driver would see.

Since

0.1.0

Definition at line 116 of file ra8_esp_hosted_c6link.c.

References g_h, H_GPIO_HANDSHAKE_Pin, H_GPIO_HANDSHAKE_Port, H_HS_VAL_ACTIVE, ra8_esp_hosted_port_is_ready(), and RA8_INTERNAL.

Referenced by ra8_esp_hosted_c6link_bind().

internal_ra8_esp_hosted_c6link_transfer()

ra8_err_t internal_ra8_esp_hosted_c6link_transfer ( void * ctx, const uint8_t * tx, uint8_t * rx, uint16_t len )

static

Clock one full-duplex transaction through the port's SPI slice.

Goes through the vendored OS-abstraction vtable rather than the SPI HAL, so the facade's transactions take exactly the path the vendored driver would.

Parameters

[in]	ctx	Unused; the port is a singleton.
[in]	tx	Bytes to transmit; must be non-null.
[out]	rx	Where the received bytes land; must be non-null.
[in]	len	Transaction length in bytes.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The transaction completed.
k_ra8_err_not_initialized	The port is not up.
k_ra8_err_spi_error	The bus transfer did not return RET_OK.

Precondition

ra8_esp_hosted_port_init has succeeded.

len is at most k_ra8_c6link_frame_bytes and both buffers cover it.

Postcondition

On success rx holds exactly len received bytes.

No port state outside the staging buffer is modified.

Note

Runs on the caller's thread and blocks for the transaction.

Since

0.1.0

Definition at line 72 of file ra8_esp_hosted_c6link.c.

References g_h, k_ra8_c6link_frame_bytes, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_spi_error, k_ra8_ok, memcpy(), ra8_esp_hosted_port_is_ready(), RET_OK, and s_ra8_esp_hosted_c6link_tx.

Referenced by ra8_esp_hosted_c6link_bind().

ra8_esp_hosted_c6link_bind()

ra8_err_t ra8_esp_hosted_c6link_bind ( ra8_c6link_transport_t * out )

nodiscard

Fill a ra8_c6link transport seam with this port's implementations.

Sets the transfer, handshake and delay rows to trampolines onto g_h and leaves the context null – the port is a singleton, so there is nothing per-instance to carry. The seam is validated by ra8_c6link_open, which rejects any row this call failed to fill.

Parameters

[out]

out

Seam to fill; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The seam is bound and may be handed to ra8_c6link_open.
k_ra8_err_null_ptr	out was null.
k_ra8_err_not_initialized	The port is not up, so g_h.funcs would be unpopulated at the first transaction.

Precondition

ra8_esp_hosted_port_init has returned k_ra8_ok.

No link is currently clocking transactions through this port.

Postcondition

On success all three rows of out are non-null.

On failure out is cleared rather than left half-filled.

Note

Not thread-safe against a concurrent port teardown; bind during bring-up, before any pump starts.

Warning

The bound seam outlives nothing: tearing the port down while a link holds the seam leaves that link calling into a closed bus.

Example:

ra8_c6link_cfg_t cfg = {};
if (ra8_esp_hosted_c6link_bind(&cfg.transport) == k_ra8_ok) {
  cfg.arena       = arena;
  cfg.arena_bytes = (uint32_t)sizeof arena;
  (void)ra8_c6link_open(&link, &cfg);
}

See also

ra8_esp_hosted_port_init

ra8_c6link_open

Since

0.1.0

NASA Power of 10 Compliance:

• Rule 5: two preconditions and two postconditions are checked.

Definition at line 151 of file ra8_esp_hosted_c6link.c.

References ra8_c6link_transport::ctx, ra8_c6link_transport::delay_ms, ra8_c6link_transport::handshake_active, internal_ra8_esp_hosted_c6link_delay(), internal_ra8_esp_hosted_c6link_handshake(), internal_ra8_esp_hosted_c6link_transfer(), k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, ra8_esp_hosted_port_is_ready(), and ra8_c6link_transport::transfer.

Referenced by c6_join_open_link(), c6_wifi_open_link(), internal_c6_cam_open_link(), internal_open_and_join(), and wifi_hal_make_cfg().

Variable Documentation

s_ra8_esp_hosted_c6link_tx

uint8_t s_ra8_esp_hosted_c6link_tx[k_ra8_c6link_frame_bytes]

static

DMA-aligned staging buffer the transmit frame is clocked from.

The facade hands over a const pointer and the vendored transport context wants a mutable one; copying rather than casting keeps the port inside MISRA Rule 11.4 with no deviation to record, and guarantees the bus always sees an aligned buffer.

Note

Written only inside internal_ra8_esp_hosted_c6link_transfer, on the pumping thread, which is also the only thread allowed to drive the bus.

Warning

Not re-entrant: two threads pumping one link would interleave here, which is the same rule the facade already states about its handle.

Since

0.1.0

Definition at line 49 of file ra8_esp_hosted_c6link.c.

Referenced by internal_ra8_esp_hosted_c6link_transfer().