The ESP32-C6 backend: each ra8_wifi operation onto ra8_c6link. More...

#include "ra8_wifi_c6link.h"
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_c6link.h"
#include "ra8_c6link_wifi.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_secure.h"
#include "ra8_wifi.h"
#include "ra8_wifi_backend.h"

Include dependency graph for ra8_wifi_c6link.c:

Macros
#define	RA8_WIFI_C6_TAG "WIFI-C6"
	Component tag for this backend's log lines.

Functions
static void	internal_c6link_on_event (void ctx, const ra8_c6link_event_t ev)
	Latch a station event so ::ra8_wifi_c6link_service can report it.
static ra8_err_t	internal_c6link_op_open (void *ctx)
	Bring the link up: open it and prove the co-processor answers.
static ra8_err_t	internal_c6link_op_close (void *ctx)
	Release the link this backend opened.
static ra8_err_t	internal_c6link_op_radio_up (void *ctx)
	Start the co-processor's radio in station mode.
static ra8_err_t	internal_c6link_op_radio_down (void *ctx)
	Stop the radio and release the co-processor's Wi-Fi resources.
static ra8_err_t	internal_c6link_op_join (void ctx, const char ssid, const char *psk)
	Ask the station to associate with a network.
static ra8_err_t	internal_c6link_op_leave (void *ctx)
	Disassociate the station from its current network.
static ra8_err_t	internal_c6link_op_service (void ctx, ra8_wifi_link_t out_link)
	Service the link once and report whether the station is associated.
static ra8_err_t	internal_c6link_op_get_mac (void ctx, ra8_wifi_mac_t out)
	Read the station's own MAC address.
static ra8_err_t	internal_c6link_op_get_ap (void ctx, ra8_wifi_ap_t out)
	Read what the co-processor knows about the associated AP.
static void	internal_c6link_op_idle (void *ctx, uint16_t ms)
	Idle for the requested milliseconds, on the transport's own clock.
ra8_err_t	ra8_wifi_c6link_setup (ra8_wifi_c6link_t self, const ra8_wifi_c6link_cfg_t cfg, ra8_wifi_cfg_t *out_wcfg)
	Wire this backend into the backend half of an ra8_wifi_cfg_t.

Variables
const ra8_wifi_backend_t	k_ra8_wifi_backend_c6link
	The ESP32-C6 ra8_wifi_backend_t, exported for ra8_wifi_cfg::backend.

Detailed Description

The ESP32-C6 backend: each ra8_wifi operation onto ra8_c6link.

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

Implements k_ra8_wifi_backend_c6link. Every function here is one thin mapping from a facade operation to the ra8_c6link station call that performs it, plus the one piece of state the facade cannot see for itself: whether the co-processor has announced that the station is associated. That announcement is asynchronous, so this backend registers an event callback at ra8_c6link_open that latches the two station events, and reports the latched result whenever the facade services the link.

All the machinery the facade exists to hide – RPC ids, the transaction pump, the interface index, wifi_mode_t – is reached only from this file.

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

Since: 0.1.0

Definition in file ra8_wifi_c6link.c.

Macro Definition Documentation

◆ RA8_WIFI_C6_TAG

#define RA8_WIFI_C6_TAG "WIFI-C6"

Component tag for this backend's log lines.

Definition at line 42 of file ra8_wifi_c6link.c.

Referenced by internal_c6link_op_close(), internal_c6link_op_get_ap(), internal_c6link_op_get_mac(), internal_c6link_op_join(), internal_c6link_op_leave(), internal_c6link_op_open(), internal_c6link_op_radio_down(), internal_c6link_op_radio_up(), internal_c6link_op_service(), and ra8_wifi_c6link_setup().

Function Documentation

◆ internal_c6link_on_event()

void internal_c6link_on_event	(	void *	ctx,
		const ra8_c6link_event_t *	ev )

static

Latch a station event so ::ra8_wifi_c6link_service can report it.

Registered as the link's event callback. It records only the two station transitions; boot and bare Wi-Fi events are informational and left for the counters. ra8_c6link guarantees a non-null event and the context set at open, so no defensive guard is needed.

Parameters

[in,out]	ctx	The ra8_wifi_c6link_t handed to ra8_c6link_open.
[in]	ev	The decoded announcement; valid only during this call.

Returns: Nothing.

Precondition: ctx is the backend context registered at open.; ev is non-null, per the ra8_c6link_event_cb_t contract.

Postcondition: A station-connected event sets connected.; A station-disconnected event sets disconnected and reason.

Note: Runs inside ra8_c6link_poll on the polling thread.

Since: 0.1.0

Definition at line 65 of file ra8_wifi_c6link.c.

References ra8_wifi_c6link::connected, ra8_wifi_c6link::disconnected, k_ra8_c6link_event_sta_connected, k_ra8_c6link_event_sta_disconnected, ra8_c6link_event::kind, RA8_INTERNAL, ra8_c6link_event::reason, and ra8_wifi_c6link::reason.

Referenced by internal_c6link_op_open().

◆ internal_c6link_op_close()

ra8_err_t internal_c6link_op_close ( void * ctx )

static

Release the link this backend opened.

Maps onto ra8_c6link_close. The transport itself is not torn down; whoever brought it up owns that. The facade calls it from ra8_wifi_deinit.

Parameters

[in,out] ctx The ra8_wifi_c6link_t for this backend; must be non-null.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	The link is closed.
k_ra8_err_null_ptr	`ctx` or its link was null.
k_ra8_err_not_initialized	The link was not open.

Precondition: ctx was opened by internal_c6link_op_open.; No pump is running against the link.

Postcondition: The link reports closed.; No further event reaches this backend's latch.

Note: Not thread-safe; dispatched once per handle.

Since: 0.1.0

Definition at line 137 of file ra8_wifi_c6link.c.

References ra8_wifi_c6link::link, ra8_c6link_close(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, and RA8_WIFI_C6_TAG.

◆ internal_c6link_op_get_ap()

ra8_err_t internal_c6link_op_get_ap	(	void *	ctx,
		ra8_wifi_ap_t *	out )

static

Read what the co-processor knows about the associated AP.

Maps onto ra8_c6link_wifi_ap_info and copies the record – BSSID, SSID, channel, RSSI and auth mode – into the facade's ra8_wifi_ap_t. The facade calls it from ra8_wifi_get_ap.

Parameters

[in,out]	ctx	The ra8_wifi_c6link_t for this backend; must be non-null.
[out]	out	Record to fill; must be non-null.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	`out` describes the current association.
k_ra8_err_null_ptr	`ctx` or `out` was null.
k_ra8_err_protocol_error	The co-processor reported no AP record.

Precondition: The station is associated.; out is writable.

Postcondition: On success out is fully written.; On failure out is cleared rather than left half-written.

Note: Not thread-safe; it pumps the link.

Since: 0.1.0

Definition at line 360 of file ra8_wifi_c6link.c.

References ra8_c6link_ap_info::authmode, ra8_wifi_ap::authmode, ra8_c6link_ap_info::bssid, ra8_wifi_ap::bssid, ra8_c6link_ap_info::channel, ra8_wifi_ap::channel, k_ra8_ok, k_ra8_wifi_mac_bytes, ra8_wifi_c6link::link, memcpy(), ra8_c6link_mac::octet, ra8_wifi_mac::octet, ra8_c6link_wifi_ap_info(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, RA8_WIFI_C6_TAG, ra8_c6link_ap_info::rssi, ra8_wifi_ap::rssi, ra8_c6link_ap_info::ssid, ra8_wifi_ap::ssid, ra8_c6link_ap_info::ssid_len, and ra8_wifi_ap::ssid_len.

◆ internal_c6link_op_get_mac()

ra8_err_t internal_c6link_op_get_mac	(	void *	ctx,
		ra8_wifi_mac_t *	out )

static

Read the station's own MAC address.

Maps onto ra8_c6link_wifi_mac and copies the six octets into the facade's ra8_wifi_mac_t. The facade calls it from ra8_wifi_connect and ra8_wifi_get_mac.

Parameters

[in,out]	ctx	The ra8_wifi_c6link_t for this backend; must be non-null.
[out]	out	Address to fill; must be non-null.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	`out` holds the station address.
k_ra8_err_null_ptr	`ctx` or `out` was null.
k_ra8_err_protocol_error	The co-processor reported no valid address.

Precondition: The radio has been started.; out is writable.

Postcondition: On success out holds k_ra8_wifi_mac_bytes octets.; On failure out is not written.

Note: Not thread-safe; it pumps the link.

Since: 0.1.0

Definition at line 327 of file ra8_wifi_c6link.c.

References k_ra8_ok, k_ra8_wifi_mac_bytes, ra8_wifi_c6link::link, memcpy(), ra8_c6link_mac::octet, ra8_wifi_mac::octet, ra8_c6link_wifi_mac(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, and RA8_WIFI_C6_TAG.

◆ internal_c6link_op_idle()

void internal_c6link_op_idle	(	void *	ctx,
		uint16_t	ms )

static

Idle for the requested milliseconds, on the transport's own clock.

The facade counts attempts and has no clock of its own; this is the seam through which it paces one. The delay used is the transport's delay_ms – the same one ra8_c6link's pump waits on – so the facade's association wait is paced by exactly the mechanism the bench proved, and a co-processor model can make it free.

Parameters

[in,out]	ctx	The ra8_wifi_c6link_t for this backend; may be null.
[in]	ms	Milliseconds to idle for.

Returns: Nothing.

Precondition: The transport in ctx is bound, or ctx is null and this is a no-op.; The caller is not holding a lock the delay would extend.

Postcondition: At least ms elapsed, unless there was no transport to wait on.; No link or backend state was touched.

Note: Blocks the calling context; it is a delay, not a yield.

Since: 0.1.0

Definition at line 398 of file ra8_wifi_c6link.c.

References ra8_c6link_transport::ctx, ra8_c6link_transport::delay_ms, RA8_INTERNAL, and ra8_wifi_c6link::transport.

◆ internal_c6link_op_join()

ra8_err_t internal_c6link_op_join	(	void *	ctx,
		const char *	ssid,
		const char *	psk )

static

Ask the station to associate with a network.

Clears the event latches so a stale association cannot be mistaken for this one, fills an ra8_c6link_sta_cfg_t with ra8_c6link_sta_cfg_set, and issues the join with ra8_c6link_wifi_join. Returns once the request is accepted; the result arrives later as an event this backend latches.

Parameters

[in,out]	ctx	The ra8_wifi_c6link_t for this backend; must be non-null.
[in]	ssid	Target SSID, NUL-terminated; must be non-null.
[in]	psk	Passphrase, NUL-terminated, or null for an open network.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	The association request was accepted.
k_ra8_err_null_ptr	`ctx` or `ssid` was null.
k_ra8_err_invalid_size	`ssid` was empty or a credential too long.
k_ra8_err_protocol_error	The co-processor refused the request.

Precondition: The radio has been started.; ssid names a network in range.

Postcondition: On success an association attempt is in progress and the latches are clear.; On failure the latches are still clear for a retry.

Note: Not thread-safe; it pumps the link.

Since: 0.1.0

Definition at line 216 of file ra8_wifi_c6link.c.

References ra8_wifi_c6link::connected, ra8_wifi_c6link::disconnected, k_ra8_ok, ra8_wifi_c6link::link, ra8_c6link_sta_cfg_set(), ra8_c6link_wifi_join(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, ra8_secure_memzero(), RA8_WIFI_C6_TAG, and ra8_wifi_c6link::reason.

◆ internal_c6link_op_leave()

ra8_err_t internal_c6link_op_leave ( void * ctx )

static

Disassociate the station from its current network.

Maps onto ra8_c6link_wifi_leave. A disconnect event follows, which this backend's latch records. The facade calls it from ra8_wifi_disconnect before stopping the radio.

Parameters

[in,out] ctx The ra8_wifi_c6link_t for this backend; must be non-null.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	The disassociation was accepted.
k_ra8_err_null_ptr	`ctx` or its link was null.
k_ra8_err_protocol_error	The co-processor refused the request.

Precondition: The link is open.; The caller expects a disconnect event to follow.

Postcondition: On success a disassociation is in progress.; On failure the link's last fault names the request.

Note: Not thread-safe; it pumps the link.

Since: 0.1.0

Definition at line 254 of file ra8_wifi_c6link.c.

References ra8_wifi_c6link::link, ra8_c6link_wifi_leave(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, and RA8_WIFI_C6_TAG.

◆ internal_c6link_op_open()

ra8_err_t internal_c6link_op_open ( void * ctx )

static

Bring the link up: open it and prove the co-processor answers.

Builds an ra8_c6link_cfg_t from the context – the bound transport, the arena, this backend's event latch and the IP-stack receive sink – opens the link with ra8_c6link_open, then establishes liveness with ra8_c6link_await_ready. The facade calls it from ra8_wifi_init.

Parameters

[in,out] ctx The ra8_wifi_c6link_t for this backend; must be non-null.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	The link is open and the radio is answering.
k_ra8_err_null_ptr	`ctx` or its link was null.
k_ra8_err_invalid_state	The link was already open.

Precondition: The transport in ctx is bound and its hardware is up.; The link storage in ctx is zero-initialised.

Postcondition: On success the link reports open.; On failure the link is not left half-open.

Note: Not thread-safe; dispatched once per handle.

Since: 0.1.0

Definition at line 97 of file ra8_wifi_c6link.c.

References ra8_c6link_cfg::arena, ra8_wifi_c6link::arena, ra8_c6link_cfg::arena_bytes, ra8_wifi_c6link::arena_bytes, ra8_c6link_cfg::cb_ctx, ra8_c6link_cfg::event_cb, internal_c6link_on_event(), k_ra8_c6link_announce_transfers, k_ra8_ok, ra8_wifi_c6link::link, ra8_c6link_await_ready(), ra8_c6link_open(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, RA8_WIFI_C6_TAG, ra8_c6link_cfg::rx_cb, ra8_wifi_c6link::rx_cb, ra8_c6link_cfg::transport, and ra8_wifi_c6link::transport.

◆ internal_c6link_op_radio_down()

ra8_err_t internal_c6link_op_radio_down ( void * ctx )

static

Stop the radio and release the co-processor's Wi-Fi resources.

Maps onto ra8_c6link_wifi_stop, which issues the stop and deinit requests. The facade calls it from ra8_wifi_disconnect.

Parameters

[in,out] ctx The ra8_wifi_c6link_t for this backend; must be non-null.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	The radio is stopped.
k_ra8_err_null_ptr	`ctx` or its link was null.
k_ra8_err_protocol_error	A teardown step was refused; the rest ran.

Precondition: The link is open.; The caller has stopped transmitting frames.

Postcondition: Every teardown step was attempted.; On failure the link's last fault names the first failure.

Note: Not thread-safe; it pumps the link.

Since: 0.1.0

Definition at line 186 of file ra8_wifi_c6link.c.

References ra8_wifi_c6link::link, ra8_c6link_wifi_stop(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, and RA8_WIFI_C6_TAG.

◆ internal_c6link_op_radio_up()

ra8_err_t internal_c6link_op_radio_up ( void * ctx )

static

Start the co-processor's radio in station mode.

Maps onto ra8_c6link_wifi_start, which issues the init, mode and start requests in sequence. The facade calls it from ra8_wifi_connect when the radio is not already on.

Parameters

[in,out] ctx The ra8_wifi_c6link_t for this backend; must be non-null.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	The radio is up in station mode.
k_ra8_err_null_ptr	`ctx` or its link was null.
k_ra8_err_protocol_error	The co-processor refused a step.

Precondition: The link is open.; The radio is not already started.

Postcondition: On success the co-processor is in station mode.; On failure the link's last fault names the step that failed.

Note: Not thread-safe; it pumps the link.

Since: 0.1.0

Definition at line 162 of file ra8_wifi_c6link.c.

References ra8_wifi_c6link::link, ra8_c6link_wifi_start(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, and RA8_WIFI_C6_TAG.

◆ internal_c6link_op_service()

ra8_err_t internal_c6link_op_service	(	void *	ctx,
		ra8_wifi_link_t *	out_link )

static

Service the link once and report whether the station is associated.

Pumps ra8_c6link_poll, which delivers any pending events to this backend's latch, then reports the latched state: associated only when a connect has arrived and no later disconnect has. The facade calls it from ra8_wifi_poll and its connect wait loop.

Parameters

[in,out]	ctx	The ra8_wifi_c6link_t for this backend; must be non-null.
[out]	out_link	Association state after the cycle; must be non-null.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	The cycle ran and `out_link` holds the reading.
k_ra8_err_null_ptr	`ctx` or `out_link` was null.
k_ra8_err_hw_timeout	The co-processor never armed HANDSHAKE.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition: The link is open and no other context is driving it.; out_link is writable.

Postcondition: out_link reflects the latched association state.; At most one pump ran.

Note: Not thread-safe; it pumps the link.

Since: 0.1.0

Definition at line 282 of file ra8_wifi_c6link.c.

References ra8_wifi_c6link::connected, ra8_wifi_c6link::disconnected, k_ra8_c6link_announce_transfers, k_ra8_ok, k_ra8_wifi_link_down, k_ra8_wifi_link_up, ra8_wifi_c6link::link, ra8_c6link_poll(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, and RA8_WIFI_C6_TAG.

◆ ra8_wifi_c6link_setup()

ra8_err_t ra8_wifi_c6link_setup	(	ra8_wifi_c6link_t *	self,
		const ra8_wifi_c6link_cfg_t *	cfg,
		ra8_wifi_cfg_t *	out_wcfg )

nodiscard

Wire this backend into the backend half of an ra8_wifi_cfg_t.

Copies cfg into self, clears the event latches, and fills out_wcfg 's backend and backend_ctx. It leaves ip_bind and ip_ctx untouched so the application can set its IP provider on the same structure. No hardware is touched; the link is opened later, from ra8_wifi_init.

Parameters

[out]	self	Backend context to populate; must be non-null.
[in]	cfg	Backend configuration; must be non-null with a link and an arena of at least k_ra8_c6link_arena_min bytes.
[out]	out_wcfg	Facade configuration whose backend half is filled; must be non-null.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	`out_wcfg` selects this backend with `self` as context.
k_ra8_err_null_ptr	`self`, `cfg`, `out_wcfg`, or cfg->link was null.
k_ra8_err_invalid_size	cfg->arena_bytes is below k_ra8_c6link_arena_min.

Precondition: The transport's hardware bring-up has run or will run before ra8_wifi_init.; cfg->link is zero-initialised storage.

Postcondition: On success out_wcfg->backend is k_ra8_wifi_backend_c6link.; On failure out_wcfg is not modified.

Note: Not thread-safe; call once during bring-up.

Example:: (void)ra8_wifi_c6link_setup(&s_c6, &bcfg, &cfg);

s_c6
static ra8_wifi_c6link_t s_c6
The ESP32-C6 ra8_wifi backend context.
Definition main.c:64

ra8_wifi_c6link_setup
ra8_err_t ra8_wifi_c6link_setup(ra8_wifi_c6link_t *self, const ra8_wifi_c6link_cfg_t *cfg, ra8_wifi_cfg_t *out_wcfg)
Wire this backend into the backend half of an ra8_wifi_cfg_t.
Definition ra8_wifi_c6link.c:430

See also: ra8_wifi_init

Since: 0.1.0

NASA Power of 10 Compliance:

Rule 5: preconditions on every pointer plus a size floor, two postconditions.

Definition at line 430 of file ra8_wifi_c6link.c.

References ra8_wifi_c6link::arena, ra8_wifi_c6link_cfg::arena, ra8_wifi_c6link::arena_bytes, ra8_wifi_c6link_cfg::arena_bytes, ra8_wifi_cfg::backend, ra8_wifi_cfg::backend_ctx, k_ra8_c6link_arena_min, k_ra8_err_invalid_size, k_ra8_ok, k_ra8_wifi_backend_c6link, ra8_wifi_c6link::link, ra8_wifi_c6link_cfg::link, RA8_CHECK_NULL_PTR, RA8_WIFI_C6_TAG, ra8_wifi_c6link::rx_cb, ra8_wifi_c6link_cfg::rx_cb, ra8_wifi_c6link::transport, and ra8_wifi_c6link_cfg::transport.

Referenced by wifi_hal_make_cfg().

Variable Documentation

◆ k_ra8_wifi_backend_c6link

const ra8_wifi_backend_t k_ra8_wifi_backend_c6link

Initial value:

                                                   = {
  .open       = internal_c6link_op_open,
  .close      = internal_c6link_op_close,
  .radio_up   = internal_c6link_op_radio_up,
  .radio_down = internal_c6link_op_radio_down,
  .join       = internal_c6link_op_join,
  .leave      = internal_c6link_op_leave,
  .service    = internal_c6link_op_service,
  .get_mac    = internal_c6link_op_get_mac,
  .get_ap     = internal_c6link_op_get_ap,
  .idle       = internal_c6link_op_idle,
}

The ESP32-C6 ra8_wifi_backend_t, exported for ra8_wifi_cfg::backend.

The one ESP32-C6 backend table; see the header for the contract.

A single const table shared by every handle that runs on the co-processor. Applications take its address through ra8_wifi_c6link_setup rather than naming it directly, but it is exported so a test or a bespoke wiring can reference it.

Note: Immutable; every row points at a translation-unit-local function.

Warning: Do not copy or mutate it; pass its address.

See also: ra8_wifi_c6link_setup

Since: 0.1.0

Every row points at a translation-unit-local mapping above.

Note: Immutable and shared by every handle on the co-processor.

Since: 0.1.0

Definition at line 417 of file ra8_wifi_c6link.c.

Referenced by ra8_wifi_c6link_setup().

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ RA8_WIFI_C6_TAG

Function Documentation

◆ internal_c6link_on_event()

◆ internal_c6link_op_close()

◆ internal_c6link_op_get_ap()

◆ internal_c6link_op_get_mac()

◆ internal_c6link_op_idle()

◆ internal_c6link_op_join()

◆ internal_c6link_op_leave()

◆ internal_c6link_op_open()

◆ internal_c6link_op_radio_down()

◆ internal_c6link_op_radio_up()

◆ internal_c6link_op_service()

◆ ra8_wifi_c6link_setup()

Variable Documentation

◆ k_ra8_wifi_backend_c6link