c6_fwver_priv.c File Reference

The ESP_PRIV_IF control channel: host capabilities out, INIT in. More...

#include <stdint.h>
#include "c6_fwver.h"
#include "esp_hosted_host_fw_ver.h"
#include "esp_hosted_interface.h"
#include "esp_hosted_transport.h"
#include "esp_hosted_transport_init.h"
#include "port_esp_hosted_host_config_features.h"
#include "transport_drv.h"

Include dependency graph for c6_fwver_priv.c:

Go to the source code of this file.

Enumerations
enum	c6_fwver_priv_t : uint8_t {   k_c6_fwver_priv_evt_type = 0U ,   k_c6_fwver_priv_evt_len = 1U ,   k_c6_fwver_priv_evt_hdr = 2U ,   k_c6_fwver_priv_tlv_tag = 0U ,   k_c6_fwver_priv_tlv_size = 1U ,   k_c6_fwver_priv_tlv_value = 2U ,   k_c6_fwver_priv_tlv_len = 1U ,   k_c6_fwver_priv_tlv_stride = 3U ,   k_c6_fwver_priv_tag_count = 5U ,   k_c6_fwver_priv_host_cap = 0U }
	Layout and values of the ESP_PRIV_IF event this host sends. More...
enum	c6_fwver_priv_ver_t : uint8_t {   k_c6_fwver_priv_ver_b0 = 0U ,   k_c6_fwver_priv_ver_b1 = 1U ,   k_c6_fwver_priv_ver_b2 = 2U ,   k_c6_fwver_priv_ver_b3 = 3U ,   k_c6_fwver_priv_ver_bytes = 4U ,   k_c6_fwver_priv_shift_1 = 8U ,   k_c6_fwver_priv_shift_2 = 16U ,   k_c6_fwver_priv_shift_3 = 24U }
	Byte layout of the ESP_PRIV_FIRMWARE_VERSION tag's value. More...

Functions
static uint16_t	c6_fwver_priv_put_tlv (uint8_t *out, uint16_t at, uint8_t tag, uint8_t value)
	Append one one-byte-valued TLV at a cursor.
ra8_err_t	c6_fwver_priv_host_caps (uint8_t *out, uint16_t cap, uint16_t *out_len)
	Build the host-capabilities frame the reference host sends first.
static void	c6_fwver_priv_tlv (uint8_t tag, const uint8_t *value, uint8_t len)
	Decode and report one TLV of an INIT event.
bool	c6_fwver_priv_consume (uint8_t if_type, uint8_t if_num, const uint8_t *payload, uint16_t len)
	Decode an ESP_PRIV_IF frame and report what it announced.
uint32_t	c6_fwver_priv_init_version (void)
	Report the version the boot INIT event announced, if one arrived.

Variables
static uint32_t	s_c6_fwver_priv_version
	Version word the boot INIT event announced, or zero.

Detailed Description

The ESP_PRIV_IF control channel: host capabilities out, INIT in.

Tag

[Ring 6 / APP] {World: S}

ESP_PRIV_IF carries the two frames that bracket an esp-hosted link's bring-up. The co-processor queues an ESP_PRIV_EVENT_INIT event at boot announcing its capabilities, its chip id and its firmware version; the host answers with an event of the same shape carrying its own capabilities, the chip id it expects, and the flow-control thresholds it wants. Both are flat TLV lists behind a two-byte event header, and both are built here field for field from the two vendored functions that own them: send_slave_config() LEGACY-OK: upstream esp-hosted function name and process_init_event().

The INIT event matters beyond politeness: its ESP_PRIV_FIRMWARE_VERSION tag carries the co-processor's own version as a little-endian 32-bit word. That is a SECOND, independent reading of the number the RPC round-trip asks for, arriving by a different mechanism (an unsolicited event rather than a request/response) and decoded by different code. When both agree, the answer is not an artefact of either decoder.

It is genuinely optional, though: the co-processor queues it once per boot and holds it until a transaction drains it, so a run that follows an earlier run without power-cycling the C6 will not see one. This module therefore records it when it arrives and never requires it.

Copyright

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

Since

0.1.0

Definition in file c6_fwver_priv.c.

Enumeration Type Documentation

c6_fwver_priv_t

enum c6_fwver_priv_t : uint8_t

Layout and values of the ESP_PRIV_IF event this host sends.

The TLV tags themselves come from the vendored esp_hosted_transport.h and esp_hosted_transport_init.h; what is named here is the geometry – how wide a tag's value is, where the event header ends – plus the one policy value the host chooses.

Invariant

k_c6_fwver_priv_tlv_len is one for every tag this host emits, so the frame length is a fixed multiple of the TLV stride.

k_c6_fwver_priv_host_cap is zero, matching the vendored call send_slave_config(0, ...) LEGACY-OK: upstream function name – this host advertises no optional transport capability.

Example:

out[0] = (uint8_t)ESP_PRIV_EVENT_INIT;
out[1] = (uint8_t)tlv_bytes;

See also

c6_fwver_priv_host_caps

Since

0.1.0

Enumerator
k_c6_fwver_priv_evt_type	Offset of the event type byte.
k_c6_fwver_priv_evt_len	Offset of the event length byte.
k_c6_fwver_priv_evt_hdr	Bytes before the first TLV.
k_c6_fwver_priv_tlv_tag	Offset of a TLV's tag, from its start.
k_c6_fwver_priv_tlv_size	Offset of a TLV's length, from its start.
k_c6_fwver_priv_tlv_value	Offset of a TLV's value, from its start.
k_c6_fwver_priv_tlv_len	Value width of every tag this host emits.
k_c6_fwver_priv_tlv_stride	Bytes one one-byte-valued TLV occupies.
k_c6_fwver_priv_tag_count	TLVs this host emits.
k_c6_fwver_priv_host_cap	Host capability word; zero, as upstream.

Definition at line 66 of file c6_fwver_priv.c.

c6_fwver_priv_ver_t

enum c6_fwver_priv_ver_t : uint8_t

Byte layout of the ESP_PRIV_FIRMWARE_VERSION tag's value.

A little-endian 32-bit word, assembled here one byte at a time so the decode does not depend on the alignment of a payload the co-processor chose the offset of.

Invariant

The four offsets are consecutive and cover exactly four bytes.

k_c6_fwver_priv_ver_bytes equals the tag length the co-processor advertises for this tag.

Example:

ver = (uint32_t)value[k_c6_fwver_priv_ver_b0];

See also

c6_fwver_priv_consume

Since

0.1.0

Enumerator
k_c6_fwver_priv_ver_b0	Least significant byte.
k_c6_fwver_priv_ver_b1	Second byte.
k_c6_fwver_priv_ver_b2	Third byte.
k_c6_fwver_priv_ver_b3	Most significant byte.
k_c6_fwver_priv_ver_bytes	Width of the tag value.
k_c6_fwver_priv_shift_1	Shift for the 2nd byte.
k_c6_fwver_priv_shift_2	Shift for the 3rd byte.
k_c6_fwver_priv_shift_3	Shift for the 4th byte.

Definition at line 95 of file c6_fwver_priv.c.

Function Documentation

c6_fwver_priv_consume()

bool c6_fwver_priv_consume	(	uint8_t	if_type,
		uint8_t	if_num,
		const uint8_t *	payload,
		uint16_t	len )

Decode an ESP_PRIV_IF frame and report what it announced.

Walks the TLV list of an ESP_PRIV_EVENT_INIT event, printing the capability word, the firmware chip id and – the interesting one – the ESP_PRIV_FIRMWARE_VERSION tag, which carries the co-processor's own version as a little-endian 32-bit word. That is an independent second reading of the number the RPC round-trip asks for.

Parameters

[in]	if_type	Interface type from the received header.
[in]	if_num	Interface number from the received header.
[in]	payload	Frame payload; null is ignored.
[in]	len	Payload length in bytes.

Returns

false always: an announcement is never a reason to stop pumping.

Return values

false

The frame was decoded, ignored, or was not a priv frame.

Precondition

The console is up.

len bytes are readable at payload.

Postcondition

At most one line was emitted per recognised TLV.

The recorded init-event version is updated when the tag is present.

Note

Matches c6_fwver_sink_t so the pump can call it directly.

See also

c6_fwver_priv_init_version

Since

0.1.0

Definition at line 222 of file c6_fwver_priv.c.

References c6_fwver_priv_tlv(), c6_fwver_put_hex(), c6_fwver_put_u32(), c6_fwver_puts(), k_c6_fwver_hex_byte, k_c6_fwver_priv_evt_hdr, k_c6_fwver_priv_evt_len, k_c6_fwver_priv_evt_type, k_c6_fwver_priv_tlv_size, k_c6_fwver_priv_tlv_tag, and k_c6_fwver_priv_tlv_value.

Referenced by c6_fwver_dispatch().

c6_fwver_priv_host_caps()

ra8_err_t c6_fwver_priv_host_caps ( uint8_t * out, uint16_t cap, uint16_t * out_len )

nodiscard

Build the host-capabilities frame the reference host sends first.

Byte-for-byte the TLV set the vendored transport_drv.c composes in send_slave_config() LEGACY-OK: upstream esp-hosted function name – host capabilities, the firmware chip id the host expects, the raw-throughput direction, and the two flow-control thresholds, behind an ESP_PRIV_EVENT_INIT event header.

Parameters

[out]	out	Buffer to fill; must be non-null.
[in]	cap	Bytes available at out.
[out]	out_len	Bytes written; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The frame was built and out_len is its length.
k_ra8_err_null_ptr	out or out_len was null.
k_ra8_err_invalid_size	cap cannot hold the frame.

Precondition

cap bytes are writable at out.

The caller transmits the result on ESP_PRIV_IF, interface 0.

Postcondition

On success out_len is non-zero and at most cap.

On failure out is not modified.

Note

Pure formatting; touches no hardware and is safe from any thread.

See also

c6_fwver_priv_consume

Since

0.1.0

Definition at line 142 of file c6_fwver_priv.c.

References c6_fwver_priv_put_tlv(), H_TEST_RAW_TP_DIR, H_WIFI_TX_DATA_THROTTLE_HIGH_THRESHOLD, H_WIFI_TX_DATA_THROTTLE_LOW_THRESHOLD, k_c6_fwver_priv_evt_hdr, k_c6_fwver_priv_evt_len, k_c6_fwver_priv_evt_type, k_c6_fwver_priv_host_cap, k_c6_fwver_priv_tag_count, k_c6_fwver_priv_tlv_stride, k_ra8_err_invalid_size, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by c6_fwver_phase_caps().

c6_fwver_priv_init_version()

uint32_t c6_fwver_priv_init_version ( void )

nodiscard

Report the version the boot INIT event announced, if one arrived.

Returns

The packed (major << 16) | (minor << 8) | patch word, or zero when no INIT event carrying the tag has been decoded.

Return values

0	No ESP_PRIV_FIRMWARE_VERSION tag has been seen.

Precondition

None; safe to call before any frame has arrived.

The caller treats zero as "not observed", not as version 0.0.0.

Postcondition

No application state is modified.

The returned value reflects the last INIT event decoded.

Note

The co-processor queues this event once per boot, so a run that follows an earlier run without power-cycling the C6 will not see it.

See also

c6_fwver_priv_consume

Since

0.1.0

Definition at line 263 of file c6_fwver_priv.c.

References s_c6_fwver_priv_version.

Referenced by c6_fwver_rpc_print_crosscheck().

c6_fwver_priv_put_tlv()

uint16_t c6_fwver_priv_put_tlv ( uint8_t * out, uint16_t at, uint8_t tag, uint8_t value )

static

Append one one-byte-valued TLV at a cursor.

Parameters

[out]	out	Buffer being filled; must be non-null.
[in]	at	Offset to write at.
[in]	tag	TLV tag.
[in]	value	TLV value.

Returns

The offset just past the TLV written.

Precondition

At least k_c6_fwver_priv_tlv_stride bytes are writable at out + at.

The caller has already checked the buffer capacity.

Postcondition

Exactly k_c6_fwver_priv_tlv_stride bytes were written.

The returned offset is at plus that stride.

Note

Every tag this host emits has a one-byte value, which is why the length is not a parameter.

Since

0.1.0

Definition at line 134 of file c6_fwver_priv.c.

References k_c6_fwver_priv_tlv_len, k_c6_fwver_priv_tlv_size, k_c6_fwver_priv_tlv_stride, k_c6_fwver_priv_tlv_tag, and k_c6_fwver_priv_tlv_value.

Referenced by c6_fwver_priv_host_caps().

c6_fwver_priv_tlv()

void c6_fwver_priv_tlv ( uint8_t tag, const uint8_t * value, uint8_t len )

static

Decode and report one TLV of an INIT event.

Parameters

[in]	tag	TLV tag.
[in]	value	TLV value bytes; must be non-null.
[in]	len	TLV value length in bytes.

Returns

Nothing.

Precondition

len bytes are readable at value.

The console is up.

Postcondition

Recognised tags were printed; unrecognised ones were named with their tag number rather than dropped silently.

s_c6_fwver_priv_version is updated only by the version tag.

Note

An unrecognised tag is printed, not ignored: a co-processor that announces something this host does not know about is exactly the thing a bring-up wants to see.

Since

0.1.0

Definition at line 195 of file c6_fwver_priv.c.

References c6_fwver_put_hex(), c6_fwver_put_u32(), c6_fwver_puts(), k_c6_fwver_hex_byte, k_c6_fwver_priv_shift_1, k_c6_fwver_priv_shift_2, k_c6_fwver_priv_shift_3, k_c6_fwver_priv_tlv_len, k_c6_fwver_priv_ver_b0, k_c6_fwver_priv_ver_b1, k_c6_fwver_priv_ver_b2, k_c6_fwver_priv_ver_b3, k_c6_fwver_priv_ver_bytes, and s_c6_fwver_priv_version.

Referenced by c6_fwver_priv_consume().

Variable Documentation

s_c6_fwver_priv_version

uint32_t s_c6_fwver_priv_version

static

Version word the boot INIT event announced, or zero.

Packed the same way ESP_HOSTED_VERSION_VAL packs it, so it can be compared with the RPC answer without either side being re-derived.

Note

Written only from the pump thread, inside c6_fwver_priv_consume.

Warning

Zero means "no INIT event carrying the tag was seen", not version 0.0.0; the co-processor queues the event once per boot.

Since

0.1.0

Definition at line 116 of file c6_fwver_priv.c.

Referenced by c6_fwver_priv_init_version(), and c6_fwver_priv_tlv().