The esp-hosted OS-abstraction vtable and its non-RTOS slots. More...

#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>
#include "esp_hosted_os_abstraction.h"
#include "esp_hosted_transport_config.h"
#include "esp_log.h"
#include "port_esp_hosted_host_config.h"
#include "port_esp_hosted_host_log.h"
#include "port_esp_hosted_host_os.h"
#include "port_esp_hosted_host_spi.h"
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_esp_hosted_gpio_internal.h"
#include "ra8_esp_hosted_log_internal.h"
#include "ra8_esp_hosted_osi_internal.h"
#include "ra8_esp_hosted_pins.h"
#include "ra8_esp_hosted_port.h"
#include "ra8_esp_hosted_rtos_internal.h"
#include "ra8_esp_hosted_spi_internal.h"

Include dependency graph for ra8_esp_hosted_osi.c:

Data Structures
union	ra8_esp_hosted_osi_view
	Row-wise view of the vtable, for the completeness scan. More...

Typedefs
typedef union ra8_esp_hosted_osi_view	ra8_esp_hosted_osi_view_t

Enumerations
enum	ra8_esp_hosted_osi_const_t : uint8_t { k_ra8_esp_hosted_osi_queue_depth = (uint8_t)H_TRANSPORT_QUEUE_SIZE , k_ra8_esp_hosted_osi_spi_mode = 3U , k_ra8_esp_hosted_osi_wakeup_reboot = 1U }
	Fixed values the non-slice vtable rows report. More...

Functions
ra8_err_t	ra8_esp_hosted_port_set_event_cb (ra8_esp_hosted_event_cb_t cb, void *ctx)
	Implementation of ra8_esp_hosted_port_set_event_cb() – stores the pair atomically enough for a bring-up path; see the contract.
int	priv_ra8_esp_hosted_osi_dispatch_event (const char base, int32_t event_id, const void data, size_t data_len)
	Implementation of priv_ra8_esp_hosted_osi_dispatch_event() – the one decision behind both event rows, promoted so it is testable.
static int	internal_event_post (esp_event_base_t event_base, int32_t event_id, void *event_data, size_t event_data_size, uint32_t ticks_to_wait)
	Vtable row: post a generic esp-hosted event.
static int	internal_event_wifi_post (int32_t event_id, void *event_data, size_t event_data_size, uint32_t ticks_to_wait)
	Vtable row: post a Wi-Fi event.
static void	internal_printf (int level, const char tag, const char format,...)
	Vtable row: emit one formatted log line.
static void	internal_init_hook (void)
	Vtable row: run whatever the host needs before the core starts.
static int	internal_restart_host (void)
	Vtable row: restart the host processor.
static int	internal_config_host_power_save (uint32_t power_save_type, void *gpio_port, uint32_t gpio_num, int level)
	Vtable row: configure the host's power-save wake source.
static int	internal_start_host_power_save (uint32_t power_save_type)
	Vtable row: enter host power save.
bool	priv_ra8_esp_hosted_osi_is_complete (const hosted_osi_funcs_t *table)
	Implementation of priv_ra8_esp_hosted_osi_is_complete() – scans the table row-wise through a union, so a row added upstream is covered without editing a field list.
ra8_err_t	priv_ra8_esp_hosted_osi_bind_all (hosted_osi_funcs_t *out)
	Implementation of priv_ra8_esp_hosted_osi_bind_all() – fills every row, then proves none was missed.
struct esp_hosted_spi_config	esp_hosted_get_default_spi_config (void)

Variables
static const char *	s_esp_hosted_tag = "H_" "osi"
static const char *const	s_tag = "C6OSI"
	Tag the project logger attributes this module's lines to.
static const char *const	s_event_base_wifi = "WIFI_EVENT"
	Namespace reported for events the core posts as Wi-Fi events.
static ra8_esp_hosted_event_cb_t	s_ra8_esp_hosted_event_cb
	Application callback invoked when the core posts a link event.
static void *	s_ra8_esp_hosted_event_ctx
	Opaque context handed back to s_ra8_esp_hosted_event_cb.
hosted_osi_funcs_t	g_hosted_osi_funcs
	The OS-abstraction vtable the vendored core calls through.
struct hosted_config_t	g_h = HOSTED_CONFIG_INIT_DEFAULT()
	The handle the vendored core dereferences to reach the vtable.

Detailed Description

The esp-hosted OS-abstraction vtable and its non-RTOS slots.

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

The vendored esp-hosted core reaches every service it needs through one 72-entry function-pointer table found behind the global g_h. This file owns that table: it defines g_hosted_osi_funcs and g_h, it calls the three slice binders that fill the RTOS, GPIO and SPI rows, and it implements the rows that belong to no slice – event posting, the log shim, the restart and power-save hooks, and the sixteen rows that belong to transports this board does not carry.

Why the table is bound at run time rather than statically: A static initialiser would need all sixty-odd slot functions to have external linkage and a declaration apiece, turning the port's internal headers into a second copy of the vtable. Binding instead lets each slice keep its implementations static and expose one function, which is both a smaller surface and a testable unit: a binder that forgets a row is a test failure rather than a null dereference at run time.

Rows for absent transports: The SDIO, half-duplex SPI and UART rows are filled with functions that report the transport as unavailable and name the slot that was called. They are not silently-succeeding stubs: the C6 on this board is reached over full-duplex SPI only – there is no SDIO or UART connection to it at all – so "this transport is not present" is the truthful answer, and saying it loudly is what a caller needs. Leaving the rows null would turn the same mistake into a null-pointer fault with no diagnosis.

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

Since: 0.1.0

Definition in file ra8_esp_hosted_osi.c.

Typedef Documentation

◆ ra8_esp_hosted_osi_view_t

typedef union ra8_esp_hosted_osi_view ra8_esp_hosted_osi_view_t

Enumeration Type Documentation

◆ ra8_esp_hosted_osi_const_t

enum ra8_esp_hosted_osi_const_t : uint8_t

Fixed values the non-slice vtable rows report.

Named so the reasons behind each answer are readable at the point of use rather than encoded as bare integers.

Invariant: k_ra8_esp_hosted_osi_wakeup_reboot matches the value the vendored power-save driver treats as "ordinary reboot".

Example:: return (int)k_ra8_esp_hosted_osi_wakeup_reboot;

k_ra8_esp_hosted_osi_wakeup_reboot
@ k_ra8_esp_hosted_osi_wakeup_reboot
Wake-up reason meaning the host performed an ordinary reboot.
Definition ra8_esp_hosted_osi.c:89

See also: priv_ra8_esp_hosted_osi_bind_all

Since: 0.1.0

Enumerator
k_ra8_esp_hosted_osi_queue_depth	Queue depth for each of the two transmit and receive priority queues, restated here so the SPI configuration the port publishes matches what the transport actually creates.
k_ra8_esp_hosted_osi_spi_mode	SPI mode the co-processor image is built for.
k_ra8_esp_hosted_osi_wakeup_reboot	Wake-up reason meaning the host performed an ordinary reboot.

Definition at line 81 of file ra8_esp_hosted_osi.c.

Function Documentation

◆ esp_hosted_get_default_spi_config()

struct esp_hosted_spi_config esp_hosted_get_default_spi_config ( void )

Definition at line 529 of file ra8_esp_hosted_osi.c.

References esp_hosted_get_default_spi_config(), 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, H_SPI_FD_CLK_MHZ, k_ra8_esp_hosted_osi_queue_depth, k_ra8_esp_hosted_osi_spi_mode, k_ra8_esp_hosted_pin_chip_select, k_ra8_esp_hosted_pin_cipo, k_ra8_esp_hosted_pin_copi, k_ra8_esp_hosted_pin_sck, RA8_ESP_HOSTED_GPIO_PIN, and RA8_ESP_HOSTED_GPIO_PORT.

Referenced by esp_hosted_get_default_spi_config().

◆ internal_config_host_power_save()

int internal_config_host_power_save	(	uint32_t	power_save_type,
		void *	gpio_port,
		uint32_t	gpio_num,
		int	level )

static

Vtable row: configure the host's power-save wake source.

Host power save is disabled in this build (H_HOST_PS_ALLOWED is zero), so the core never reaches this row. It reports the request rather than pretending to have configured a wake source that would then never fire.

Parameters

[in]	power_save_type	Requested power-save mode.
[in]	gpio_port	Wake pin's port, in the port's encoding.
[in]	gpio_num	Wake pin's index within that port.
[in]	level	Level that should wake the host.

Returns: Always the failure code.

Return values

RET_FAIL Host power save is not enabled in this build.

Precondition: H_HOST_PS_ALLOWED is zero, so this row is unreachable.; Logging has been initialised, or the line is dropped.

Postcondition: No board state is modified.; Exactly one line is emitted.

Note: Reentrant.

Since: 0.1.0

Definition at line 389 of file ra8_esp_hosted_osi.c.

References ESP_LOGW, RET_FAIL, and s_esp_hosted_tag.

Referenced by priv_ra8_esp_hosted_osi_bind_all().

◆ internal_event_post()

int internal_event_post	(	esp_event_base_t	event_base,
		int32_t	event_id,
		void *	event_data,
		size_t	event_data_size,
		uint32_t	ticks_to_wait )

static

Vtable row: post a generic esp-hosted event.

Hands the event to the registered application callback. There is no ESP-IDF event loop on this host, and inventing one would add a thread and a queue for a path the application can serve directly.

Parameters

[in]	event_base	Event namespace supplied by the core.
[in]	event_id	Event identifier within the namespace.
[in]	event_data	Event payload; may be null when the length is zero.
[in]	event_data_size	Payload length in bytes.
[in]	ticks_to_wait	Ignored; delivery is synchronous, so there is nothing to wait for.

Returns: Whether the event was consumed.

Return values

RET_OK	The callback ran.
RET_FAIL	No callback is registered.
RET_INVALID	The payload pointer and length disagree.

Precondition: The port has been initialised.; The caller is not holding a lock the callback also takes.

Postcondition: No port state is modified.; The callback has run exactly once, or not at all.

Note: Runs on the posting thread; the callback must not block it.

Since: 0.1.0

Definition at line 224 of file ra8_esp_hosted_osi.c.

References priv_ra8_esp_hosted_osi_dispatch_event().

Referenced by priv_ra8_esp_hosted_osi_bind_all().

◆ internal_event_wifi_post()

int internal_event_wifi_post	(	int32_t	event_id,
		void *	event_data,
		size_t	event_data_size,
		uint32_t	ticks_to_wait )

static

Vtable row: post a Wi-Fi event.

Routed to the same application callback as the generic row, under a fixed namespace, so an application sees one delivery path.

Parameters

[in]	event_id	Wi-Fi event identifier.
[in]	event_data	Event payload; may be null when the length is zero.
[in]	event_data_size	Payload length in bytes.
[in]	ticks_to_wait	Ignored; delivery is synchronous.

Returns: Whether the event was consumed.

Return values

RET_OK	The callback ran.
RET_FAIL	No callback is registered.
RET_INVALID	The payload pointer and length disagree.

Precondition: The port has been initialised.; The caller is not holding a lock the callback also takes.

Postcondition: No port state is modified.; The callback has run exactly once, or not at all.

Note: Runs on the posting thread; the callback must not block it.

Since: 0.1.0

Definition at line 260 of file ra8_esp_hosted_osi.c.

References priv_ra8_esp_hosted_osi_dispatch_event(), and s_event_base_wifi.

Referenced by priv_ra8_esp_hosted_osi_bind_all().

◆ internal_init_hook()

void internal_init_hook ( void )

static

Vtable row: run whatever the host needs before the core starts.

The core calls this once, from setup_transport, to give the port a last chance to prepare. Everything this port needs is already done by ra8_esp_hosted_port_init, which must run first, so the hook confirms that and reports the pool state – which is exactly the moment a budgeting mistake is cheapest to see.

Returns: Nothing.

Precondition: ra8_esp_hosted_port_init has completed.; The ThreadX kernel is running.

Postcondition: No port state is modified.; One pool-state line is emitted.

Note: Runs on the core's setup thread.

Since: 0.1.0

Definition at line 325 of file ra8_esp_hosted_osi.c.

References ESP_LOGE, ra8_esp_hosted_mem_dump(), ra8_esp_hosted_port_is_ready(), and s_esp_hosted_tag.

Referenced by priv_ra8_esp_hosted_osi_bind_all().

◆ internal_printf()

void internal_printf	(	int	level,
		const char *	tag,
		const char *	format,
			... )

static

Vtable row: emit one formatted log line.

Forwards to the port's log bridge, which is the same path the ESP_LOGx macros take, so a line emitted through the vtable and one emitted directly are indistinguishable at the sink.

Parameters

[in]	level	ESP-IDF level of the line.
[in]	tag	Tag to attribute the line to; null is replaced.
[in]	format	Format string; null suppresses the line.

Returns: Nothing.

Precondition: Logging has been initialised, or the line is dropped.; The variable arguments match the conversions in format.

Postcondition: No port state is modified.; At most one line is emitted.

Note: Reentrant; formats onto a bounded stack line.

Since: 0.1.0

Definition at line 296 of file ra8_esp_hosted_osi.c.

References priv_ra8_esp_hosted_log_vwrite().

Referenced by priv_ra8_esp_hosted_osi_bind_all().

◆ internal_restart_host()

int internal_restart_host ( void )

static

Vtable row: restart the host processor.

The core reaches for this when the link is unrecoverable. This port declines rather than resetting the board: the C6 link carries connectivity only, and a reader that is displaying a page has far more to lose from an unannounced reset than it gains from a fresh transport. The refusal is reported so the condition is visible, and the application decides what to do.

Returns: Always the failure code.

Return values

RET_FAIL The port does not reset the host on its own authority.

Precondition: The caller has already decided the link is unrecoverable.; Logging has been initialised, or the line is dropped.

Postcondition: No board state is modified.; Exactly one line is emitted.

Note: Reentrant.

Since: 0.1.0

Definition at line 357 of file ra8_esp_hosted_osi.c.

References ESP_LOGE, RET_FAIL, and s_esp_hosted_tag.

Referenced by priv_ra8_esp_hosted_osi_bind_all().

◆ internal_start_host_power_save()

int internal_start_host_power_save ( uint32_t power_save_type )

static

Vtable row: enter host power save.

Companion to internal_config_host_power_save and unreachable for the same reason.

Parameters

[in] power_save_type Requested power-save mode.

Returns: Always the failure code.

Return values

RET_FAIL Host power save is not enabled in this build.

Precondition: H_HOST_PS_ALLOWED is zero, so this row is unreachable.; Logging has been initialised, or the line is dropped.

Postcondition: No board state is modified.; Exactly one line is emitted.

Note: Reentrant.

Since: 0.1.0

Definition at line 424 of file ra8_esp_hosted_osi.c.

References ESP_LOGW, RET_FAIL, and s_esp_hosted_tag.

Referenced by priv_ra8_esp_hosted_osi_bind_all().

◆ priv_ra8_esp_hosted_osi_bind_all()

ra8_err_t priv_ra8_esp_hosted_osi_bind_all ( hosted_osi_funcs_t * out )

nodiscard

Implementation of priv_ra8_esp_hosted_osi_bind_all() – fills every row, then proves none was missed.

Fill every row of the OS-abstraction vtable.

Definition at line 485 of file ra8_esp_hosted_osi.c.

References internal_config_host_power_save(), internal_event_post(), internal_event_wifi_post(), internal_init_hook(), internal_printf(), internal_restart_host(), internal_start_host_power_save(), k_ra8_err_invalid_state, k_ra8_ok, priv_ra8_esp_hosted_gpio_bind(), priv_ra8_esp_hosted_osi_bind_absent(), priv_ra8_esp_hosted_osi_is_complete(), priv_ra8_esp_hosted_rtos_bind(), priv_ra8_esp_hosted_rtos_bind_pool(), priv_ra8_esp_hosted_rtos_bind_sync(), priv_ra8_esp_hosted_spi_bind(), RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_bring_up().

◆ priv_ra8_esp_hosted_osi_dispatch_event()

int priv_ra8_esp_hosted_osi_dispatch_event	(	const char *	base,
		int32_t	event_id,
		const void *	data,
		size_t	data_len )

Implementation of priv_ra8_esp_hosted_osi_dispatch_event() – the one decision behind both event rows, promoted so it is testable.

Deliver one posted event to the registered application handler.

Definition at line 176 of file ra8_esp_hosted_osi.c.

References RET_FAIL, RET_INVALID, RET_OK, s_ra8_esp_hosted_event_cb, and s_ra8_esp_hosted_event_ctx.

Referenced by internal_event_post(), and internal_event_wifi_post().

◆ priv_ra8_esp_hosted_osi_is_complete()

bool priv_ra8_esp_hosted_osi_is_complete ( const hosted_osi_funcs_t * table )

nodiscard

Implementation of priv_ra8_esp_hosted_osi_is_complete() – scans the table row-wise through a union, so a row added upstream is covered without editing a field list.

Report whether every row of a table is populated.

Definition at line 465 of file ra8_esp_hosted_osi.c.

References ra8_esp_hosted_osi_view::rows.

Referenced by priv_ra8_esp_hosted_osi_bind_all().

◆ ra8_esp_hosted_port_set_event_cb()

ra8_err_t ra8_esp_hosted_port_set_event_cb	(	ra8_esp_hosted_event_cb_t	cb,
		void *	ctx )

nodiscard

Implementation of ra8_esp_hosted_port_set_event_cb() – stores the pair atomically enough for a bring-up path; see the contract.

Register the handler the port calls when the core posts an event.

Definition at line 163 of file ra8_esp_hosted_osi.c.

References k_ra8_err_invalid_arg, k_ra8_ok, s_ra8_esp_hosted_event_cb, and s_ra8_esp_hosted_event_ctx.

Referenced by tx_application_define().

Variable Documentation

◆ g_h

struct hosted_config_t g_h = HOSTED_CONFIG_INIT_DEFAULT()

The handle the vendored core dereferences to reach the vtable.

Statically bound to g_hosted_osi_funcs, matching the upstream HOSTED_CONFIG_INIT_DEFAULT shape.

Note: The name and type are fixed by the vendored esp_hosted_os_abstraction.h.

Warning: Never reassign funcs; the core caches nothing but expects the table to stay put.

Since: 0.1.0

Definition at line 159 of file ra8_esp_hosted_osi.c.

Referenced by c6_fwver_link_pump(), c6_fwver_rpc_pool_alloc(), c6_fwver_rpc_pool_free(), c6_fwver_wait_handshake(), c6_hosted_read_sideband(), c6_hosted_run_transaction(), heap_caps_malloc(), internal_configure_sideband(), internal_ra8_esp_hosted_c6link_delay(), internal_ra8_esp_hosted_c6link_handshake(), internal_ra8_esp_hosted_c6link_transfer(), and ra8_esp_hosted_port_rx_pending().

◆ g_hosted_osi_funcs

hosted_osi_funcs_t g_hosted_osi_funcs

The OS-abstraction vtable the vendored core calls through.

Zero at reset and populated by priv_ra8_esp_hosted_osi_bind_all, which ra8_esp_hosted_port_init runs before anything can reach it.

Note: The name and type are fixed by the vendored esp_hosted_os_abstraction.h.

Warning: Calling through it before the port is initialised dereferences a null row; check ra8_esp_hosted_port_is_ready first.

Since: 0.1.0

Definition at line 146 of file ra8_esp_hosted_osi.c.

Referenced by internal_bring_up(), and internal_unwind().

◆ s_esp_hosted_tag

const char* s_esp_hosted_tag = "H_" "osi"

static

Definition at line 60 of file ra8_esp_hosted_osi.c.

Referenced by internal_absent(), internal_bring_up(), internal_config_host_power_save(), internal_configure_sideband(), internal_init_hook(), internal_restart_host(), internal_start_host_power_save(), priv_ra8_esp_hosted_port_cfg_check(), and ra8_esp_hosted_port_init().

◆ s_event_base_wifi

const char* const s_event_base_wifi = "WIFI_EVENT"

static

Namespace reported for events the core posts as Wi-Fi events.

Matches the ESP-IDF base name so an application that already knows the co-processor's event vocabulary needs no translation table.

Note: Read-only.

Warning: Changing it silently changes what handlers must match on.

Since: 0.1.0

Definition at line 112 of file ra8_esp_hosted_osi.c.

Referenced by internal_event_wifi_post().

◆ s_ra8_esp_hosted_event_cb

ra8_esp_hosted_event_cb_t s_ra8_esp_hosted_event_cb

static

Application callback invoked when the core posts a link event.

Null until an application registers one, in which case posted events are reported as unconsumed rather than dropped silently.

Note: Written only by ra8_esp_hosted_port_set_event_cb.

Warning: Invoked from whichever thread posted the event.

Since: 0.1.0

Definition at line 123 of file ra8_esp_hosted_osi.c.

Referenced by priv_ra8_esp_hosted_osi_dispatch_event(), and ra8_esp_hosted_port_set_event_cb().

◆ s_ra8_esp_hosted_event_ctx

void* s_ra8_esp_hosted_event_ctx

static

Opaque context handed back to s_ra8_esp_hosted_event_cb.

Owned by the application; the port never dereferences it.

Note: Written only by ra8_esp_hosted_port_set_event_cb.

Warning: Must outlive the registration.

Since: 0.1.0

Definition at line 133 of file ra8_esp_hosted_osi.c.

Referenced by priv_ra8_esp_hosted_osi_dispatch_event(), and ra8_esp_hosted_port_set_event_cb().

◆ s_tag

const char* const s_tag = "C6OSI"

static

Tag the project logger attributes this module's lines to.

Distinct from the vendored s_esp_hosted_tag so a line from the port itself is separable from a line the vendored core emitted.

Note: Read-only.

Warning: Keep it short; the sink does not wrap.

Since: 0.1.0

Definition at line 101 of file ra8_esp_hosted_osi.c.

Data Structures

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ ra8_esp_hosted_osi_view_t

Enumeration Type Documentation

◆ ra8_esp_hosted_osi_const_t

Function Documentation

◆ esp_hosted_get_default_spi_config()

◆ internal_config_host_power_save()

◆ internal_event_post()

◆ internal_event_wifi_post()

◆ internal_init_hook()

◆ internal_printf()

◆ internal_restart_host()

◆ internal_start_host_power_save()

◆ priv_ra8_esp_hosted_osi_bind_all()

◆ priv_ra8_esp_hosted_osi_dispatch_event()

◆ priv_ra8_esp_hosted_osi_is_complete()

◆ ra8_esp_hosted_port_set_event_cb()

Variable Documentation

◆ g_h

◆ g_hosted_osi_funcs

◆ s_esp_hosted_tag

◆ s_event_base_wifi

◆ s_ra8_esp_hosted_event_cb

◆ s_ra8_esp_hosted_event_ctx

◆ s_tag