ra8_c6link_wifi.c File Reference

Radio lifecycle: initialise, choose station mode, start, tear down. More...

#include "ra8_c6link_wifi.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_c6link.h"
#include "ra8_c6link_internal.h"

Include dependency graph for ra8_c6link_wifi.c:

Go to the source code of this file.

Data Structures
struct	ra8_c6link_bare_body
	Storage for whichever empty request body a bare call needs. More...

Typedefs
typedef struct ra8_c6link_bare_body	ra8_c6link_bare_body_t

Enumerations
enum	ra8_c6link_wifi_mode_t : int32_t {   k_ra8_c6link_mode_null = 0 ,   k_ra8_c6link_mode_sta = 1 ,   k_ra8_c6link_mode_ap = 2 }
	The co-processor's own wifi_mode_t values, as transmitted. More...
enum	ra8_c6link_wifi_init_t : int32_t {   k_ra8_c6link_wifi_magic = 0x1F2F3F4F ,   k_ra8_c6link_wifi_static_rx = 10 ,   k_ra8_c6link_wifi_dynamic_rx = 32 ,   k_ra8_c6link_wifi_tx_type = 1 ,   k_ra8_c6link_wifi_static_tx = 0 ,   k_ra8_c6link_wifi_dynamic_tx = 32 ,   k_ra8_c6link_wifi_rx_mgmt_type = 0 ,   k_ra8_c6link_wifi_rx_mgmt_num = 5 ,   k_ra8_c6link_wifi_ampdu_on = 1 ,   k_ra8_c6link_wifi_nvs_on = 1 ,   k_ra8_c6link_wifi_ba_win = 6 ,   k_ra8_c6link_wifi_beacon_max = 752 ,   k_ra8_c6link_wifi_mgmt_sbuf = 32 ,   k_ra8_c6link_wifi_feature_caps = 1 ,   k_ra8_c6link_wifi_espnow_keys = 7 ,   k_ra8_c6link_wifi_hetb_queues = 3 }
	The Req_WifiInit configuration this host transmits. More...

Functions
ra8_err_t	priv_c6link_take_resp (void *ctx, const void *msg_v)
	Extract the result code from an answer that carries nothing else.
static bool	internal_c6link_wifi_bare_body (Rpc *req, ra8_c6link_bare_body_t *body, uint32_t req_id, uint32_t *resp_id)
	Populate an Rpc with the empty body a bare request needs.
ra8_err_t	priv_c6link_bare_req (ra8_c6link_t *link, uint32_t req_id)
	Issue a request whose body carries no fields and whose answer carries only a result code.
static ra8_err_t	internal_c6link_wifi_do_init (ra8_c6link_t *link)
	Send Req_WifiInit carrying the default configuration set.
static ra8_err_t	internal_c6link_wifi_do_mode (ra8_c6link_t *link)
	Send Req_SetWifiMode selecting station mode.
ra8_err_t	ra8_c6link_wifi_start (ra8_c6link_t *link)
	Start the co-processor's Wi-Fi radio in station mode.
ra8_err_t	ra8_c6link_wifi_stop (ra8_c6link_t *link)
	Stop the radio and release the co-processor's Wi-Fi resources.
ra8_err_t	ra8_c6link_wifi_leave (ra8_c6link_t *link)
	Disassociate the station from its current network.

Detailed Description

Radio lifecycle: initialise, choose station mode, start, tear down.

Tag

[Ring 4 / PAL] {World: NS}

Five of the eleven RPC ids a station join needs live here, plus the shared machinery for the requests whose body is empty and whose answer is a bare result code.

The initialisation configuration, field by field

Req_WifiInit is the one request that carries real numbers rather than a credential. On an ESP-IDF host those numbers come from WIFI_INIT_CONFIG_DEFAULT(), a macro this host does not have; the co-processor validates the magic word and then uses the rest to size its own buffers. ra8_c6link_wifi_init_t restates that default set for an ESP32-C6 built at the pinned IDF version, with the reason for each value beside it, so a mismatch is visible rather than buried in a macro expansion nobody in this tree can read.

Copyright

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

Since

0.1.0

Definition in file ra8_c6link_wifi.c.

Typedef Documentation

ra8_c6link_bare_body_t

typedef struct ra8_c6link_bare_body ra8_c6link_bare_body_t

Enumeration Type Documentation

ra8_c6link_wifi_init_t

enum ra8_c6link_wifi_init_t : int32_t

The Req_WifiInit configuration this host transmits.

ESP-IDF's default set for an ESP32-C6, restated. The co-processor supplies its own OS and crypto function tables – those are pointers and are not on the wire at all – and takes these scalars from the request.

Invariant

k_ra8_c6link_wifi_magic is the word esp_wifi_init() checks before it looks at anything else; a wrong value is refused with ESP_ERR_INVALID_ARG and nothing else happens.

Every buffer count is within the range the co-processor's own build accepts, which is what makes the request succeed rather than merely arrive.

Example:

cfg.magic = (int32_t)k_ra8_c6link_wifi_magic;

See also

ra8_c6link_wifi_start

Since

0.1.0

Enumerator
k_ra8_c6link_wifi_magic	WIFI_INIT_CONFIG_MAGIC; the first thing the far side validates.
k_ra8_c6link_wifi_static_rx	Static receive buffers.
k_ra8_c6link_wifi_dynamic_rx	Dynamic receive buffers.
k_ra8_c6link_wifi_tx_type	Transmit buffer type: dynamic, which is the IDF default.
k_ra8_c6link_wifi_static_tx	Static transmit buffers; zero because the type above is dynamic.
k_ra8_c6link_wifi_dynamic_tx	Dynamic transmit buffers.
k_ra8_c6link_wifi_rx_mgmt_type	Management receive buffers are static by default.
k_ra8_c6link_wifi_rx_mgmt_num	Management receive buffers.
k_ra8_c6link_wifi_ampdu_on	Aggregation enabled in both directions, as IDF defaults it.
k_ra8_c6link_wifi_nvs_on	Let the co-processor persist calibration in its own NVS.
k_ra8_c6link_wifi_ba_win	Block-ack window.
k_ra8_c6link_wifi_beacon_max	Longest beacon the soft-AP path would build; unused by a station but part of the validated set.
k_ra8_c6link_wifi_mgmt_sbuf	Management short-buffer count.
k_ra8_c6link_wifi_feature_caps	Feature bitmap; bit zero is WPA3-SAE, which the bench network does not use but which costs nothing to advertise.
k_ra8_c6link_wifi_espnow_keys	ESP-NOW encrypted peer slots.
k_ra8_c6link_wifi_hetb_queues	HE trigger-based queues.

Definition at line 89 of file ra8_c6link_wifi.c.

ra8_c6link_wifi_mode_t

enum ra8_c6link_wifi_mode_t : int32_t

The co-processor's own wifi_mode_t values, as transmitted.

These cross the link as a plain int32_t, so they are the co-processor's numbering and not this host's choice. Only the station value is used; the others are named so the transmitted number is never a bare literal.

Invariant

k_ra8_c6link_mode_sta is what Req_SetWifiMode must carry for a station.

The numbering matches ESP-IDF's wifi_mode_t, which the co-processor decodes it as.

Example:

body.mode = (int32_t)k_ra8_c6link_mode_sta;

See also

ra8_c6link_wifi_start

Since

0.1.0

Enumerator
k_ra8_c6link_mode_null	Radio configured for neither role.
k_ra8_c6link_mode_sta	Station.
k_ra8_c6link_mode_ap	Access point.

Definition at line 59 of file ra8_c6link_wifi.c.

Function Documentation

internal_c6link_wifi_bare_body()

bool internal_c6link_wifi_bare_body ( Rpc * req, ra8_c6link_bare_body_t * body, uint32_t req_id, uint32_t * resp_id )

static

Populate an Rpc with the empty body a bare request needs.

Five requests share the shape 'empty body, result code back' but not their generated types, so this is where the one that was asked for is selected.

Parameters

[out]	req	Message to populate; must be non-null.
[out]	body	Storage for the empty body; must be non-null.
[in]	req_id	RPC_ID__Req_* to send.
[out]	resp_id	RPC_ID__Resp_* that answers it; must be non-null.

Returns

true when req_id is one this helper knows.

Return values

true	req carries the right body and resp_id names its answer.
false	req_id is not a bare request.

Precondition

body outlives the request, which a caller stack frame guarantees.

req has been initialised by rpc__init().

Postcondition

On true the payload case matches req_id.

On false req is left with no payload and resp_id is zero.

Note

The answer id is stated per arm rather than derived by arithmetic on the request id: the two happen to differ by a constant today, and a facade that silently depended on that would break quietly.

Since

0.1.0

Definition at line 220 of file ra8_c6link_wifi.c.

References ra8_c6link_bare_body::connect, ra8_c6link_bare_body::deinit, ra8_c6link_bare_body::disconnect, RA8_INTERNAL, ra8_c6link_bare_body::start, and ra8_c6link_bare_body::stop.

Referenced by priv_c6link_bare_req().

internal_c6link_wifi_do_init()

ra8_err_t internal_c6link_wifi_do_init ( ra8_c6link_t * link )

static

Send Req_WifiInit carrying the default configuration set.

The one request that carries real numbers rather than a credential. Every value is documented in ra8_c6link_wifi_init_t, and the co-processor's own esp_wifi_init() is what validates them.

Parameters

[in,out]

link

Open handle; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The co-processor initialised its Wi-Fi stack.
k_ra8_err_timeout	It did not answer within the budget.
k_ra8_err_protocol_error	It refused; the fault slot carries its esp_err_t, and ESP_ERR_INVALID_ARG there means the magic word or a buffer count was not one this co-processor build accepts.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition

link is open and the co-processor has booted.

The radio is not already initialised.

Postcondition

On success the co-processor's Wi-Fi stack exists but is not started.

On failure the fault slot names this request.

Note

Every value transmitted is documented in ra8_c6link_wifi_init_t.

Since

0.1.0

Definition at line 304 of file ra8_c6link_wifi.c.

References k_ra8_c6link_wifi_ampdu_on, k_ra8_c6link_wifi_ba_win, k_ra8_c6link_wifi_beacon_max, k_ra8_c6link_wifi_dynamic_rx, k_ra8_c6link_wifi_dynamic_tx, k_ra8_c6link_wifi_espnow_keys, k_ra8_c6link_wifi_feature_caps, k_ra8_c6link_wifi_hetb_queues, k_ra8_c6link_wifi_magic, k_ra8_c6link_wifi_mgmt_sbuf, k_ra8_c6link_wifi_nvs_on, k_ra8_c6link_wifi_rx_mgmt_num, k_ra8_c6link_wifi_rx_mgmt_type, k_ra8_c6link_wifi_static_rx, k_ra8_c6link_wifi_static_tx, k_ra8_c6link_wifi_tx_type, priv_c6link_rpc_call(), priv_c6link_take_resp(), and RA8_INTERNAL.

Referenced by ra8_c6link_wifi_start().

internal_c6link_wifi_do_mode()

ra8_err_t internal_c6link_wifi_do_mode ( ra8_c6link_t * link )

static

Send Req_SetWifiMode selecting station mode.

Fixes the radio's role before any credential is sent, which is the order ESP-IDF's own station bring-up uses.

Parameters

[in,out]

link

Open handle; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The co-processor is in station mode.
k_ra8_err_timeout	It did not answer within the budget.
k_ra8_err_protocol_error	It refused the mode.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition

internal_c6link_wifi_do_init has succeeded.

link is open.

Postcondition

On success the radio's role is fixed until it is set again.

On failure the fault slot names this request.

Note

The mode number is the co-processor's wifi_mode_t, not a local id.

Since

0.1.0

Definition at line 365 of file ra8_c6link_wifi.c.

References k_ra8_c6link_mode_sta, priv_c6link_rpc_call(), priv_c6link_take_resp(), and RA8_INTERNAL.

Referenced by ra8_c6link_wifi_start().

priv_c6link_bare_req()

ra8_err_t priv_c6link_bare_req ( ra8_c6link_t * link, uint32_t req_id )

nodiscard

Issue a request whose body carries no fields and whose answer carries only a result code.

Req_WifiStart, Req_WifiStop, Req_WifiDeinit, Req_WifiConnect and Req_WifiDisconnect are all this shape: an empty body, a result code back. They differ only in which generated initialiser and which pair of ids they name, so they share one implementation.

Parameters

[in,out]	link	Open handle; must be non-null.
[in]	req_id	RPC_ID__Req_* to send.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The co-processor reported success.
k_ra8_err_not_supported	req_id is not one of the five.
k_ra8_err_timeout	No answer arrived within the budget.
k_ra8_err_hw_timeout	The co-processor never armed HANDSHAKE, so no transaction was clocked.
k_ra8_err_protocol_error	The answer reported a failure.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition

link is open.

No other request is outstanding.

Postcondition

The link's fault slot reflects the outcome.

The wait slot is disarmed.

Note

Not thread-safe; it pumps.

Example:

return priv_c6link_bare_req(link, (uint32_t)RPC_ID__Req_WifiStart);

See also

priv_c6link_rpc_call

Since

0.1.0

Definition at line 263 of file ra8_c6link_wifi.c.

References internal_c6link_wifi_bare_body(), k_ra8_err_not_supported, k_ra8_err_null_ptr, priv_c6link_rpc_call(), priv_c6link_take_resp(), and RA8_PRIV.

Referenced by ra8_c6link_wifi_join(), ra8_c6link_wifi_leave(), ra8_c6link_wifi_start(), and ra8_c6link_wifi_stop().

priv_c6link_take_resp()

ra8_err_t priv_c6link_take_resp ( void * ctx, const void * msg_v )

nodiscard

Extract the result code from an answer that carries nothing else.

Most requests are answered by a message whose only field is resp. Which arm of the payload union holds it depends on the message id, so this switches on that rather than existing eight times over.

Parameters

[in]	ctx	A ra8_c6link_take_ctx_t naming the link and the request id.
[in]	msg_v	The decoded Rpc; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The co-processor reported success.
k_ra8_err_protocol_error	It reported a failure, or the answer was one this extractor does not know how to read.

Precondition

ctx names a live link.

msg_v is still owned by the decoder.

Postcondition

The link's fault slot reflects exactly this answer.

No other link state is modified.

Note

Runs inside the pump, on the polling thread.

Example:

ra8_c6link_take_ctx_t take = { .link = link, .rpc_id = RPC_ID__Req_WifiStart };

See also

priv_c6link_resp

Since

0.1.0

Definition at line 126 of file ra8_c6link_wifi.c.

References ra8_c6link_take_ctx::link, priv_c6link_resp(), RA8_PRIV, and ra8_c6link_take_ctx::rpc_id.

Referenced by internal_c6link_sta_set_config(), internal_c6link_wifi_do_init(), internal_c6link_wifi_do_mode(), and priv_c6link_bare_req().

ra8_c6link_wifi_leave()

ra8_err_t ra8_c6link_wifi_leave ( ra8_c6link_t * link )

nodiscard

Disassociate the station from its current network.

Parameters

[in,out]

link

Open handle; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The co-processor accepted the disassociation.
k_ra8_err_null_ptr	link was null.
k_ra8_err_not_initialized	link is not open.
k_ra8_err_busy	A request is already outstanding on link.
k_ra8_err_timeout	The co-processor did not answer.
k_ra8_err_hw_timeout	The co-processor never armed HANDSHAKE, so no transaction was clocked.
k_ra8_err_protocol_error	The answer reported a failure code.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition

The transport is up.

The caller expects a k_ra8_c6link_event_sta_disconnected to follow.

Postcondition

On success a disassociation is in progress.

On failure the handle's last fault names this request.

Note

Not thread-safe; it pumps.

Example:

(void)ra8_c6link_wifi_leave(&link);

See also

ra8_c6link_wifi_join

Since

0.1.0

Definition at line 422 of file ra8_c6link_wifi.c.

References k_ra8_err_not_initialized, k_ra8_err_null_ptr, priv_c6link_bare_req(), and ra8_c6link_is_open().

Referenced by internal_c6link_op_leave().

ra8_c6link_wifi_start()

ra8_err_t ra8_c6link_wifi_start ( ra8_c6link_t * link )

nodiscard

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

Issues Req_WifiInit, Req_SetWifiMode for station mode, and Req_WifiStart, in that order, stopping at the first one the co-processor refuses. The initialisation configuration transmitted is the ESP-IDF default set for this co-processor, field by field – see ra8_c6link_wifi_init_t in the implementation for what each value is and why it has that value.

Parameters

[in,out]

link

Open handle; 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	link was null.
k_ra8_err_not_initialized	link is not open.
k_ra8_err_busy	A request is already outstanding on link.
k_ra8_err_timeout	The co-processor did not answer a step.
k_ra8_err_hw_timeout	The co-processor never armed HANDSHAKE, so no transaction was clocked.
k_ra8_err_protocol_error	A step was answered with a failure code; ra8_c6link_last_fault names which.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition

The transport is up and the co-processor has booted.

The radio is not already started; starting twice is refused by the far side, not by this host.

Postcondition

On success the co-processor is in station mode with its radio on.

On failure the handle's last fault names the step that failed.

Note

Not thread-safe; it pumps.

Example:

if (ra8_c6link_wifi_start(&link) != k_ra8_ok) { report(&link); }

See also

ra8_c6link_wifi_stop

Since

0.1.0

NASA Power of 10 Compliance:

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

Definition at line 388 of file ra8_c6link_wifi.c.

References internal_c6link_wifi_do_init(), internal_c6link_wifi_do_mode(), k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, priv_c6link_bare_req(), and ra8_c6link_is_open().

Referenced by c6_join_phase_associate(), c6_wifi_phase_station(), internal_c6_cam_associate(), internal_c6link_op_radio_up(), and internal_open_and_join().

ra8_c6link_wifi_stop()

ra8_err_t ra8_c6link_wifi_stop ( ra8_c6link_t * link )

nodiscard

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

Issues Req_WifiStop then Req_WifiDeinit. Unlike the start sequence this continues past a refusal: a teardown that stops at the first error leaves the co-processor half-configured, which is worse than reporting the first fault and finishing the job.

Parameters

[in,out]

link

Open handle; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Both steps succeeded.
k_ra8_err_null_ptr	link was null.
k_ra8_err_not_initialized	link is not open.
k_ra8_err_busy	A request is already outstanding on link.
k_ra8_err_timeout	A step went unanswered; the rest still ran.
k_ra8_err_hw_timeout	The co-processor never armed HANDSHAKE, so no transaction was clocked.
k_ra8_err_protocol_error	A step reported a failure code; the rest still ran and ra8_c6link_last_fault names the first failure.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition

The transport is up.

The caller has stopped transmitting Ethernet frames.

Postcondition

Every teardown step was attempted.

On failure the handle's last fault names the first step that failed.

Note

Not thread-safe; it pumps.

Example:

(void)ra8_c6link_wifi_stop(&link);

See also

ra8_c6link_wifi_start

Since

0.1.0

Definition at line 408 of file ra8_c6link_wifi.c.

References k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, priv_c6link_bare_req(), and ra8_c6link_is_open().

Referenced by c6_wifi_phase_station(), and internal_c6link_op_radio_down().