ra8_esp_hosted_osi_internal.h File Reference

Library-private surface of the esp-hosted OS-abstraction vtable. More...

#include <stddef.h>
#include <stdint.h>
#include "esp_hosted_os_abstraction.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for ra8_esp_hosted_osi_internal.h:

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

Go to the source code of this file.

Functions
ra8_err_t	priv_ra8_esp_hosted_osi_bind_all (hosted_osi_funcs_t *out)
	Fill every row of the OS-abstraction vtable.
void	priv_ra8_esp_hosted_osi_bind_absent (hosted_osi_funcs_t *out)
	Fill the rows belonging to transports this board does not carry.
bool	priv_ra8_esp_hosted_osi_is_complete (const hosted_osi_funcs_t *table)
	Report whether every row of a table is populated.
int	priv_ra8_esp_hosted_osi_dispatch_event (const char *base, int32_t event_id, const void *data, size_t data_len)
	Deliver one posted event to the registered application handler.

Detailed Description

Library-private surface of the esp-hosted OS-abstraction vtable.

Tag

[Ring 4 / PORT] {World: NS}

The vtable is assembled from four slices – RTOS, GPIO, SPI and the rows that belong to no slice – each of which keeps its implementations static and exposes exactly one binder. This header declares the binders that live in ra8_esp_hosted_osi.c and ra8_esp_hosted_osi_absent.c, plus the two decisions promoted out of static so host tests can drive them without a live co-processor.

Nothing outside port/esp-hosted/ and tests/ may include this.

Copyright

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

Since

0.1.0

Definition in file ra8_esp_hosted_osi_internal.h.

Function Documentation

priv_ra8_esp_hosted_osi_bind_absent()

void priv_ra8_esp_hosted_osi_bind_absent

(

hosted_osi_funcs_t *

out

)

Fill the rows belonging to transports this board does not carry.

The SDIO, half-duplex SPI and UART rows. Each reports the transport as absent and names the row that was called; none pretends to move data. See ra8_esp_hosted_osi_absent.c for why that is the truthful answer on this board rather than a placeholder.

Parameters

[out]

out

Table whose absent-transport rows are filled. Must be non-null. Only those rows are written.

Returns

Nothing.

Precondition

out points at writable storage for one table.

The caller zeroed the table, or accepts that other rows survive.

Postcondition

Every SDIO, half-duplex SPI and UART row is non-null.

No other row is modified.

Note

Not thread-safe; run once from priv_ra8_esp_hosted_osi_bind_all.

MC/DC:

Promoted from static so a test can assert the rows are filled without building the whole table. Tests and priv_ra8_esp_hosted_osi_bind_all only.

Example:

hosted_osi_funcs_t table = {};
priv_ra8_esp_hosted_osi_bind_absent(&table);
TEST_ASSERT_NOT_NULL((void*)table._h_sdio_card_init);

See also

priv_ra8_esp_hosted_osi_bind_all

Since

0.1.0

Fill the rows belonging to transports this board does not carry.

Definition at line 610 of file ra8_esp_hosted_osi_absent.c.

References internal_sdio_card_deinit(), internal_sdio_card_init(), internal_sdio_read_block(), internal_sdio_read_reg(), internal_sdio_wait_intr(), internal_sdio_write_block(), internal_sdio_write_reg(), internal_spi_hd_read_dma(), internal_spi_hd_read_reg(), internal_spi_hd_send_cmd9(), internal_spi_hd_set_data_lines(), internal_spi_hd_write_dma(), internal_spi_hd_write_reg(), internal_uart_flush_input(), internal_uart_read(), and internal_uart_write().

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

Fill every row of the OS-abstraction vtable.

Zeroes the table, runs the RTOS, GPIO, SPI and absent-transport binders, installs the rows this file owns, and then verifies that no row was left null. The verification is the point: a slice that gains a row and forgets to bind it becomes a test failure here rather than a null dereference somewhere inside the vendored core.

Parameters

[out]

out

Table to populate. Must be non-null. Entirely overwritten, so a partially populated table cannot survive a second call.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Every row is populated.
k_ra8_err_null_ptr	out was null.
k_ra8_err_invalid_state	A row was left null by its binder.

Precondition

out points at writable storage for one table.

The RTOS slice has been initialised, since some rows capture its state at bind time.

Postcondition

On success every row is non-null.

On failure the table is left populated as far as it got, which is what the caller needs to identify the missing row in a debugger.

Note

Not thread-safe; run once from the port's bring-up path.

MC/DC:

Promoted from static so a test can bind into a local table and assert completeness without initialising the board. Production callers reach it through ra8_esp_hosted_port_init.

Example:

hosted_osi_funcs_t table = {};
TEST_ASSERT_EQ(k_ra8_ok, priv_ra8_esp_hosted_osi_bind_all(&table));

See also

priv_ra8_esp_hosted_osi_is_complete

Since

0.1.0

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 )

Deliver one posted event to the registered application handler.

The single decision behind both event rows of the vtable, so the generic and Wi-Fi paths cannot drift apart. Reports whether the event was consumed, which is what lets the core distinguish "nobody is listening" from "delivered".

Parameters

[in]	base	Event namespace; a null pointer is delivered as an empty string rather than dereferenced by the handler.
[in]	event_id	Identifier within the namespace.
[in]	data	Payload, or null when data_len is zero.
[in]	data_len	Payload length in bytes.

Returns

Whether the event was consumed.

Return values

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

Precondition

A handler has been registered, or the caller tolerates a refusal.

The caller holds no lock the handler also takes.

Postcondition

No port state is modified.

The handler has run exactly once, or not at all.

Note

Runs on the posting thread.

MC/DC:

Promoted from static so the "no handler" and "payload disagrees" decisions can be driven without a live link. Production callers are the two event rows; tests may call it directly.

Example:

TEST_ASSERT_EQ(RET_FAIL, priv_ra8_esp_hosted_osi_dispatch_event("B", 1, nullptr, 0U));

See also

ra8_esp_hosted_port_set_event_cb

Since

0.1.0

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

Report whether every row of a table is populated.

Walks the table as an array of function pointers rather than naming sixty-odd fields, so a row added to the vendored structure is covered the moment it exists. That is deliberate: a hand-written field list would silently stop covering new rows, which is the exact failure this check exists to prevent.

Parameters

[in]

table

Table to inspect. Must be non-null.

Returns

Whether the table has no null row.

Return values

true	Every row is populated.
false	table was null, or at least one row is null.

Precondition

table points at one fully-sized table.

The table's rows are all function pointers of the same width, which the accompanying static assertion checks.

Postcondition

No state is modified.

The answer depends only on the table's contents.

Note

Reentrant; a bounded read-only scan.

MC/DC:

Promoted from static so the null-table guard and the null-row detection can be driven independently. Tests and priv_ra8_esp_hosted_osi_bind_all only.

Example:

TEST_ASSERT(!priv_ra8_esp_hosted_osi_is_complete(&(hosted_osi_funcs_t){}));

See also

priv_ra8_esp_hosted_osi_bind_all

Since

0.1.0

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().