c6_hosted.h File Reference

Shared contract for the esp-hosted port bring-up application. More...

#include <stddef.h>
#include <stdint.h>
#include "esp_hosted_header.h"
#include "port_esp_hosted_host_spi.h"
#include "ra8_esp_hosted_pins.h"

Include dependency graph for c6_hosted.h:

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

Go to the source code of this file.

Data Structures
union	c6_hosted_frame
	One esp-hosted transaction buffer, addressable either way. More...

Typedefs
typedef union c6_hosted_frame	c6_hosted_frame_t

Enumerations
enum	c6_hosted_cfg_t : uint32_t {   k_c6_hosted_uart_baud = 115200U ,   k_c6_hosted_sck_hz = 5000000U ,   k_c6_hosted_edge_poll_ms = 2U ,   k_c6_hosted_heartbeat_ms = 2000U ,   k_c6_hosted_boot_wait_ms = 200U ,   k_c6_hosted_dma_align = 64U ,   k_c6_hosted_worker_stack = 4096U ,   k_c6_hosted_worker_prio = 8U }
	Link and storage parameters this application chooses. More...
enum	c6_hosted_fmt_t : uint16_t {   k_c6_hosted_str_max = 256U ,   k_c6_hosted_dec_radix = 10U ,   k_c6_hosted_dec_digits = 10U ,   k_c6_hosted_hex_digits = 8U ,   k_c6_hosted_hex_bits = 4U ,   k_c6_hosted_hex_mask = 0x0FU ,   k_c6_hosted_hex_alpha = 10U ,   k_c6_hosted_hex_byte = 2U ,   k_c6_hosted_hex_csum = 4U }
	Bounds for the console formatters in src/c6_hosted_console.c. More...
enum	c6_hosted_link_t : uint16_t { k_c6_hosted_frame_bytes = (uint16_t)MAX_TRANSPORT_BUFFER_SIZE }
	Frame geometry both ends of the link must agree on. More...

Functions
void	c6_hosted_puts (const char *text)
	Write a NUL-terminated string to the board console.
void	c6_hosted_put_u32 (uint32_t value)
	Emit an unsigned 32-bit value in decimal.
void	c6_hosted_put_i32 (int32_t value)
	Emit a signed 32-bit value in decimal.
void	c6_hosted_put_hex (uint32_t value, uint8_t digits)
	Emit a value as a fixed-width lower-case hexadecimal field.
void	c6_hosted_print_gpio (const char *label, const void *gpio_port, int32_t gpio_pin)
	Print an H_GPIO_*_Port / H_GPIO_*_Pin pair as one field.
void	c6_hosted_print_pin (const char *label, ra8_esp_hosted_pin_t pin)
	Print one packed board pin as <label>=port<n>.pin<n>.
void	c6_hosted_print_banner (uint32_t cpuclk_hz, uint32_t pclka_hz)
	Print the port identity, the clocks and the SPI parameters.
void	c6_hosted_print_pin_map (void)
	Print the resolved pin map, bus pins and side-band alike.
void	c6_hosted_report_sideband (void)
	Sample both side-band lines through the vtable and report them.
void	c6_hosted_on_event (void *ctx, const char *base, int32_t event_id, const void *data, size_t data_len)
	Report an event the port delivered from the vendored core.
uint32_t	c6_hosted_event_count (void)
	Report how many events c6_hosted_on_event has seen.
void	c6_hosted_run_transaction (void)
	Clock one full-duplex transaction and report the verdict.

Detailed Description

Shared contract for the esp-hosted port bring-up application.

Tag

[Ring 6 / APP] {World: S}

The application is split into one module per concern, all driven by main.c:

• src/c6_hosted_console.c – bounded console formatters and the two pin printers, so the image links no newlib printf.
• src/c6_hosted_report.c – the banner, the resolved pin map with each side-band pin's interrupt path, the side-band sampler that reads through the OS-abstraction vtable, and the event handler.
• src/c6_hosted_frame.c – the transmitted idle frame, the single full-duplex transaction, and the decode and verdict of what came back.

Every parameter an application owns is stated once here. Pin identity is a board fact and lives in port/esp-hosted/inc/ra8_esp_hosted_pins.h; protocol sizes are read from the vendored esp-hosted headers, never restated. The frame type below is the one place the two meet: it is declared here because both the transaction buffers and the decode need it.

Copyright

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

Since

0.1.0

Definition in file c6_hosted.h.

Typedef Documentation

c6_hosted_frame_t

typedef union c6_hosted_frame c6_hosted_frame_t

Enumeration Type Documentation

c6_hosted_cfg_t

enum c6_hosted_cfg_t : uint32_t

Link and storage parameters this application chooses.

Only values an application owns live here. NASA Power of 10 Rule 3 forbids allocation after initialisation and this image has no heap, so the transaction-buffer alignment and the worker stack are sized here as well as the link timing.

Invariant

k_c6_hosted_sck_hz stays below the 40 MHz the C6 full-duplex peripheral accepts and inside what the SCI Simple-SPI divider can reach from PCLKA.

k_c6_hosted_edge_poll_ms is non-zero; the port's software edge detector arms a ThreadX timer, which rejects a zero tick.

Example:

cfg.sck_hz = (uint32_t)k_c6_hosted_sck_hz;

See also

ra8_esp_hosted_port_cfg_t

Since

0.1.0

Enumerator
k_c6_hosted_uart_baud	Console rate, 8N1, over the J-Link OB VCOM.
k_c6_hosted_sck_hz	SPI bit rate: the 5 MHz upstream recommends for first light, an order above the probe's 1 MHz.
k_c6_hosted_edge_poll_ms	Poll period for a side-band pin with no ICU channel.
k_c6_hosted_heartbeat_ms	Heartbeat gap; the ThreadX tick is 1 ms, so this is also the sleep expressed in ticks.
k_c6_hosted_boot_wait_ms	Settling delay before the first vtable read.
k_c6_hosted_dma_align	Transaction-buffer alignment, in bytes.
k_c6_hosted_worker_stack	Worker-thread stack, in bytes.
k_c6_hosted_worker_prio	Worker priority and preemption threshold.

Definition at line 59 of file c6_hosted.h.

c6_hosted_fmt_t

enum c6_hosted_fmt_t : uint16_t

Bounds for the console formatters in src/c6_hosted_console.c.

The image links no newlib printf, so the serialisers do their own digit extraction; every loop they run is bounded by a value from this enumeration, which is what satisfies NASA Power of 10 Rule 2.

Invariant

k_c6_hosted_dec_digits holds the widest 32-bit decimal value.

k_c6_hosted_hex_digits holds the widest 32-bit hex value.

Example:

c6_hosted_put_hex(csum, (uint8_t)k_c6_hosted_hex_csum);

See also

c6_hosted_put_u32

Since

0.1.0

Enumerator
k_c6_hosted_str_max	Longest string the console helper emits.
k_c6_hosted_dec_radix	Decimal radix.
k_c6_hosted_dec_digits	Digits in the widest 32-bit decimal value.
k_c6_hosted_hex_digits	Digits in the widest 32-bit hex value.
k_c6_hosted_hex_bits	Bits per hexadecimal digit.
k_c6_hosted_hex_mask	Nibble mask.
k_c6_hosted_hex_alpha	First nibble value spelled with a letter.
k_c6_hosted_hex_byte	Hex digits printed for a byte-wide field.
k_c6_hosted_hex_csum	Hex digits printed for a 16-bit checksum.

Definition at line 87 of file c6_hosted.h.

c6_hosted_link_t

enum c6_hosted_link_t : uint16_t

Frame geometry both ends of the link must agree on.

Derived from the vendored transport header rather than restated, so an upstream change to the transaction size moves this application with it instead of leaving a stale literal behind.

Invariant

k_c6_hosted_frame_bytes is exactly the byte count the co-processor clocks in one full-duplex transaction; a mismatch mis-decodes every frame.

k_c6_hosted_frame_bytes is at least sizeof(struct esp_payload_header), so a frame always has room for its own header.

Example:

c6_hosted_put_u32((uint32_t)k_c6_hosted_frame_bytes);

See also

c6_hosted_frame_t

Since

0.1.0

Enumerator
k_c6_hosted_frame_bytes	Bytes clocked in one full-duplex transaction.

Definition at line 118 of file c6_hosted.h.

Function Documentation

c6_hosted_event_count()

uint32_t c6_hosted_event_count

(

void

)

Report how many events c6_hosted_on_event has seen.

Returns

The running count, which starts at zero and never resets.

Return values

0	The co-processor has never announced anything.

Precondition

None; safe to call before any event has arrived.

The caller tolerates a value a concurrent post may stale.

Postcondition

No application state is modified.

The returned value reflects the counter at the moment of the read.

Note

Diagnostic only; a single aligned load, not an atomic read.

See also

c6_hosted_on_event

Since

0.1.0

Definition at line 182 of file c6_hosted_report.c.

References s_c6_hosted_events.

Referenced by c6_hosted_heartbeat().

c6_hosted_on_event()

void c6_hosted_on_event	(	void *	ctx,
		const char *	base,
		int32_t	event_id,
		const void *	data,
		size_t	data_len )

Report an event the port delivered from the vendored core.

Parameters

[in]	ctx	Registered context; unused, the counter is file-scope.
[in]	base	Event namespace; never null per the port contract.
[in]	event_id	Identifier within that namespace.
[in]	data	Payload, or null; not decoded here.
[in]	data_len	Payload length in bytes.

Returns

Nothing.

Precondition

The console is up.

The port has been told about this handler.

Postcondition

The event counter was incremented.

One line naming the base and the identifier was emitted.

Note

Runs on the posting thread, so it only formats: it never blocks and never calls back into the transport.

See also

c6_hosted_event_count

Since

0.1.0

Definition at line 164 of file c6_hosted_report.c.

References c6_hosted_put_i32(), c6_hosted_put_u32(), c6_hosted_puts(), and s_c6_hosted_events.

Referenced by tx_application_define().

c6_hosted_print_banner()

void c6_hosted_print_banner	(	uint32_t	cpuclk_hz,
		uint32_t	pclka_hz )

Print the port identity, the clocks and the SPI parameters.

Parameters

[in]	cpuclk_hz	Live CPUCLK0 rate in hertz.
[in]	pclka_hz	Live PCLKA rate in hertz, the SCI baud-clock source.

Returns

Nothing.

Precondition

The console is up.

Both rates were read from the CGC rather than assumed.

Postcondition

Three banner lines were emitted.

No application state is modified.

Note

The SPI mode printed is the co-processor's: the C6 image in coprocessor/esp32c6/ is built with CONFIG_ESP_SPI_MODE=3 and the port opens the bus to match.

See also

c6_hosted_print_pin_map

Since

0.1.0

Definition at line 118 of file c6_hosted_report.c.

References c6_hosted_put_u32(), c6_hosted_puts(), k_c6_hosted_sck_hz, k_ra8_board_pmod1_sci_channel, and k_ra8_spi_mode_3.

Referenced by main().

c6_hosted_print_gpio()

void c6_hosted_print_gpio	(	const char *	label,
		const void *	gpio_port,
		int32_t	gpio_pin )

Print an H_GPIO_*_Port / H_GPIO_*_Pin pair as one field.

Parameters

[in]	label	Field name, printed verbatim; null prints nothing.
[in]	gpio_port	Opaque port handle – an index in pointer clothing, never dereferenced.
[in]	gpio_pin	Pin index, or negative when the signal is unwired.

Returns

Nothing.

Precondition

The console is up.

gpio_port and gpio_pin are the two halves of one macro pair.

Postcondition

One field was emitted, =unwired for a negative pin.

No application state is modified.

Note

This is the encoding the vendored driver itself consumes, so printing it shows what the driver will act on.

See also

c6_hosted_print_pin

Since

0.1.0

Definition at line 90 of file c6_hosted_console.c.

References c6_hosted_put_i32(), c6_hosted_put_u32(), and c6_hosted_puts().

Referenced by c6_hosted_print_pin(), and c6_hosted_print_pin_map().

c6_hosted_print_pin()

void c6_hosted_print_pin	(	const char *	label,
		ra8_esp_hosted_pin_t	pin )

Print one packed board pin as <label>=port<n>.pin<n>.

Parameters

[in]	label	Field name, printed verbatim; null prints nothing.
[in]	pin	Packed pin from ra8_esp_hosted_pins.h, possibly the k_ra8_pin_none sentinel.

Returns

Nothing.

Precondition

The console is up.

pin came from the port's pin table, never from a literal.

Postcondition

One field was emitted, =unwired for the sentinel.

No application state is modified.

Note

Port and pin indices are decoded at run time, so this application states no board pin of its own.

See also

c6_hosted_print_gpio

Since

0.1.0

Print one packed board pin as <label>=port<n>.pin<n>.

Definition at line 104 of file c6_hosted_console.c.

References c6_hosted_print_gpio(), k_ra8_pin_none, pin, RA8_PIN_PIN, and RA8_PIN_PORT.

Referenced by c6_hosted_print_pin_map(), and c6_hosted_print_route().

c6_hosted_print_pin_map()

void c6_hosted_print_pin_map

(

void

)

Print the resolved pin map, bus pins and side-band alike.

Returns

Nothing.

Precondition

The console is up.

ra8_esp_hosted_pins.h describes the harness currently fitted.

Postcondition

Four lines were emitted: bus pins, the driver's view of the side-band pair and the reset pin, then one route line per side-band signal.

No application state is modified.

Note

Every value is decoded from the port's own headers at run time, so a harness change shows up here with no edit to this application.

See also

c6_hosted_print_banner

Since

0.1.0

Definition at line 136 of file c6_hosted_report.c.

References c6_hosted_print_gpio(), c6_hosted_print_pin(), c6_hosted_print_route(), c6_hosted_puts(), H_GPIO_DATA_READY_Pin, H_GPIO_DATA_READY_Port, H_GPIO_HANDSHAKE_Pin, H_GPIO_HANDSHAKE_Port, H_GPIO_PIN_RESET, H_GPIO_PORT_RESET, k_ra8_esp_hosted_pin_chip_select, k_ra8_esp_hosted_pin_cipo, k_ra8_esp_hosted_pin_copi, k_ra8_esp_hosted_pin_data_ready, k_ra8_esp_hosted_pin_handshake, and k_ra8_esp_hosted_pin_sck.

Referenced by main().

c6_hosted_put_hex()

void c6_hosted_put_hex	(	uint32_t	value,
		uint8_t	digits )

Emit a value as a fixed-width lower-case hexadecimal field.

Parameters

[in]	value	Value to print.
[in]	digits	Field width, 1..k_c6_hosted_hex_digits; an out-of-range width prints nothing rather than overrunning the output array.

Returns

Nothing.

Precondition

The console is up.

digits is within 1..k_c6_hosted_hex_digits.

Postcondition

Exactly digits characters were emitted, or none on a bad width.

No application state is modified.

Note

The loop is bounded by the range-checked digits (NASA Rule 2).

See also

c6_hosted_put_u32

Since

0.1.0

Definition at line 74 of file c6_hosted_console.c.

References k_c6_hosted_hex_alpha, k_c6_hosted_hex_bits, k_c6_hosted_hex_digits, k_c6_hosted_hex_mask, and ra8_board_uart_console_write().

Referenced by c6_hosted_print_rx_header().

c6_hosted_put_i32()

void c6_hosted_put_i32

(

int32_t

value

)

Emit a signed 32-bit value in decimal.

Parameters

[in]

value

Value to print, including INT32_MIN.

Returns

Nothing.

Precondition

The console is up.

The caller accepts a leading minus sign on negative values.

Postcondition

One optional sign plus the decimal magnitude were emitted.

No application state is modified.

Note

The magnitude is formed in unsigned arithmetic, so INT32_MIN does not overflow on negation.

See also

c6_hosted_put_u32

Since

0.1.0

Emit a signed 32-bit value in decimal.

Definition at line 64 of file c6_hosted_console.c.

References c6_hosted_put_u32(), and c6_hosted_puts().

Referenced by c6_hosted_on_event(), c6_hosted_print_gpio(), c6_hosted_read_sideband(), and c6_hosted_run_transaction().

c6_hosted_put_u32()

void c6_hosted_put_u32

(

uint32_t

value

)

Emit an unsigned 32-bit value in decimal.

Parameters

[in]

value

Value to print; the whole 32-bit range is representable.

Returns

Nothing.

Precondition

The console is up.

The caller wants no padding; zero prints as a single digit.

Postcondition

Between one and k_c6_hosted_dec_digits characters were emitted.

No application state is modified.

Note

Not thread-safe, for the same reason as c6_hosted_puts.

See also

c6_hosted_put_i32

Since

0.1.0

Emit an unsigned 32-bit value in decimal.

Definition at line 45 of file c6_hosted_console.c.

References k_c6_hosted_dec_digits, k_c6_hosted_dec_radix, and ra8_board_uart_console_write().

Referenced by c6_hosted_heartbeat(), c6_hosted_on_event(), c6_hosted_print_banner(), c6_hosted_print_gpio(), c6_hosted_print_route(), c6_hosted_print_rx_header(), c6_hosted_put_i32(), and c6_hosted_run_transaction().

c6_hosted_puts()

void c6_hosted_puts

(

const char *

text

)

Write a NUL-terminated string to the board console.

Parameters

[in]

text

String to emit; null is ignored rather than dereferenced and the length is capped at k_c6_hosted_str_max.

Returns

Nothing.

Precondition

ra8_board_uart_console_init has succeeded.

text is NUL-terminated within k_c6_hosted_str_max bytes.

Postcondition

The bytes are queued on the console transmitter.

No application state is modified.

Note

Not thread-safe; only pre-kernel bring-up and the single worker thread call it, and those never overlap.

See also

c6_hosted_put_u32

Since

0.1.0

Definition at line 32 of file c6_hosted_console.c.

References k_c6_hosted_str_max, and ra8_board_uart_console_write().

Referenced by c6_hosted_heartbeat(), c6_hosted_on_event(), c6_hosted_print_banner(), c6_hosted_print_gpio(), c6_hosted_print_pin_map(), c6_hosted_print_route(), c6_hosted_print_rx_header(), c6_hosted_put_i32(), c6_hosted_read_sideband(), c6_hosted_run_transaction(), c6_hosted_worker_entry(), main(), and tx_application_define().

c6_hosted_report_sideband()

void c6_hosted_report_sideband

(

void

)

Sample both side-band lines through the vtable and report them.

Returns

Nothing.

Precondition

ra8_esp_hosted_port_init returned k_ra8_ok, so g_h.funcs is populated.

The console is up.

Postcondition

One line per side-band signal was emitted.

No application state is modified.

Note

Each level is compared against the active level the port config derives, so the line says "asserted" rather than leaving the reader to recall the polarity.

See also

c6_hosted_print_pin_map

Since

0.1.0

Definition at line 152 of file c6_hosted_report.c.

References c6_hosted_read_sideband(), H_DR_VAL_ACTIVE, H_GPIO_DATA_READY_Pin, H_GPIO_DATA_READY_Port, H_GPIO_HANDSHAKE_Pin, H_GPIO_HANDSHAKE_Port, and H_HS_VAL_ACTIVE.

Referenced by c6_hosted_heartbeat(), and c6_hosted_worker_entry().

c6_hosted_run_transaction()

void c6_hosted_run_transaction

(

void

)

Clock one full-duplex transaction and report the verdict.

Returns

Nothing.

Precondition

ra8_esp_hosted_port_init returned k_ra8_ok.

The console is up.

Postcondition

Exactly one transfer line, one header line and one verdict line were emitted.

The receive buffer holds whatever the co-processor drove.

Note

Runs once, on the worker thread. The first completed transaction drains the co-processor's queued boot event for good, so a rerun needs the C6 reset.

See also

c6_hosted_report_sideband

Since

0.1.0

Definition at line 373 of file c6_hosted_frame.c.

References c6_hosted_build_idle_frame(), c6_hosted_classify(), c6_hosted_print_rx_header(), c6_hosted_put_i32(), c6_hosted_put_u32(), c6_hosted_puts(), c6_hosted_rx_checksum(), c6_hosted_verdict_text(), g_h, k_c6_hosted_frame_bytes, k_c6_hosted_verdict_idle, k_c6_hosted_verdict_pass, s_c6_hosted_rx, and s_c6_hosted_tx.

Referenced by c6_hosted_worker_entry().