ra8_esp_hosted_osi_absent.c File Reference

Vtable rows for transports this board does not carry. More...

#include <stddef.h>
#include <stdint.h>
#include "esp_hosted_os_abstraction.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 "ra8_attributes.h"
#include "ra8_esp_hosted_osi_internal.h"

Include dependency graph for ra8_esp_hosted_osi_absent.c:

Go to the source code of this file.

Functions
	DEFINE_LOG_TAG (absent)
static int	internal_absent (const char *slot)
	Report a call into a transport this board does not carry.
static int	internal_sdio_card_init (void *ctx, bool show_config)
	Vtable row: bring an SDIO card up.
static int	internal_sdio_card_deinit (void *ctx)
	Vtable row: shut an SDIO card down.
static int	internal_sdio_read_reg (void *ctx, uint32_t reg, uint8_t *data, uint16_t size, bool lock_required)
	Vtable row: read an SDIO peripheral register.
static int	internal_sdio_write_reg (void *ctx, uint32_t reg, uint8_t *data, uint16_t size, bool lock_required)
	Vtable row: write an SDIO peripheral register.
static int	internal_sdio_read_block (void *ctx, uint32_t reg, uint8_t *data, uint16_t size, bool lock_required)
	Vtable row: read an SDIO data block.
static int	internal_sdio_write_block (void *ctx, uint32_t reg, uint8_t *data, uint16_t size, bool lock_required)
	Vtable row: write an SDIO data block.
static int	internal_sdio_wait_intr (void *ctx, uint32_t ticks_to_wait)
	Vtable row: wait for an SDIO peripheral interrupt.
static int	internal_spi_hd_read_reg (uint32_t reg, uint32_t *data, int poll, bool lock_required)
	Vtable row: read a half-duplex SPI register.
static int	internal_spi_hd_write_reg (uint32_t reg, uint32_t *data, bool lock_required)
	Vtable row: write a half-duplex SPI register.
static int	internal_spi_hd_read_dma (uint8_t *data, uint16_t size, bool lock_required)
	Vtable row: read a half-duplex SPI data burst.
static int	internal_spi_hd_write_dma (uint8_t *data, uint16_t size, bool lock_required)
	Vtable row: write a half-duplex SPI data burst.
static int	internal_spi_hd_set_data_lines (uint32_t data_lines)
	Vtable row: choose how many half-duplex SPI data lines to use.
static int	internal_spi_hd_send_cmd9 (void)
	Vtable row: issue the half-duplex SPI command-nine sequence.
static int	internal_uart_read (void *ctx, uint8_t *data, uint16_t size)
	Vtable row: read from the UART transport.
static int	internal_uart_write (void *ctx, uint8_t *data, uint16_t size)
	Vtable row: write to the UART transport.
static int	internal_uart_flush_input (void *ctx)
	Vtable row: discard whatever the UART transport has buffered.
void	priv_ra8_esp_hosted_osi_bind_absent (hosted_osi_funcs_t *out)
	Implementation of priv_ra8_esp_hosted_osi_bind_absent() – fills all sixteen rows so none is ever left null.

Detailed Description

Vtable rows for transports this board does not carry.

Tag

[Ring 4 / PORT] {World: NS}

Sixteen of the seventy-two OS-abstraction rows belong to the SDIO, half-duplex SPI and UART transports. On this board none of those three exists: the ESP32-C6 is reached over full-duplex SPI and nothing else. The co-processor image is built with CONFIG_ESP_SPI_HOST_INTERFACE=y (coprocessor/esp32c6/sdkconfig.defaults), the harness carries a four-wire SPI bus plus two side-band signals (coprocessor/esp32c6/pins.env), and the decision is recorded in docs/design/c6_wireless_architecture.md.

These are answers, not placeholders

"That transport is not present on this board" is the truth, and it is the whole truth: no implementation of these rows could ever move a byte, because there is no wire for them to move it on. So each row here validates its own arguments – a caller passing a null buffer has made a different mistake and deserves a different answer – and then reports the absence, naming the row it was called through so the log identifies the caller without a debugger.

The alternative, leaving the rows null, is strictly worse: the same mistake becomes a null-pointer fault with no diagnosis, at whatever moment the vendored core first reaches for a transport that was never configured.

Copyright

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

Since

0.1.0

Definition in file ra8_esp_hosted_osi_absent.c.

Function Documentation

DEFINE_LOG_TAG()

DEFINE_LOG_TAG

(

absent

)

References RA8_INTERNAL.

internal_absent()

int internal_absent ( const char * slot )

static

Report a call into a transport this board does not carry.

The single place the absence is reported, so every row says the same thing and names itself. Kept separate from the rows so the message cannot drift between them.

Parameters

[in]

slot

Name of the vtable row that was called. Every call site in this file passes a string literal, so it is never null; the log bridge would render a null as (null) anyway, which is why no guard is spent on a case that cannot arise.

Returns

Always the failure code.

Return values

RET_FAIL

The transport is not present on this board.

Precondition

The caller is a vtable row for a transport other than full-duplex SPI.

Logging has been initialised, or the line is dropped.

Postcondition

No state is modified.

Exactly one line is emitted per call.

Note

Reentrant; formats onto the logger's own bounded stack line.

Since

0.1.0

Definition at line 76 of file ra8_esp_hosted_osi_absent.c.

References ESP_LOGE, RET_FAIL, and s_esp_hosted_tag.

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

internal_sdio_card_deinit()

int internal_sdio_card_deinit ( void * ctx )

static

Vtable row: shut an SDIO card down.

See the file header; no SDIO transport exists here.

Parameters

[in]

ctx

Transport context supplied by the caller.

Returns

Failure, always.

Return values

RET_INVALID	ctx was null.
RET_FAIL	No SDIO transport exists on this board.

Precondition

The caller selected the SDIO transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

No hardware is touched.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 135 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_sdio_card_init()

int internal_sdio_card_init ( void * ctx, bool show_config )

static

Vtable row: bring an SDIO card up.

There is no SDIO connection to the co-processor on this board; see the file header.

Parameters

[in]	ctx	Transport context supplied by the caller.
[in]	show_config	Whether the caller wanted the configuration logged.

Returns

Failure, always.

Return values

RET_INVALID	ctx was null.
RET_FAIL	No SDIO transport exists on this board.

Precondition

The caller selected the SDIO transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

No hardware is touched.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 106 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_sdio_read_block()

int internal_sdio_read_block ( void * ctx, uint32_t reg, uint8_t * data, uint16_t size, bool lock_required )

static

Vtable row: read an SDIO data block.

See the file header; no SDIO transport exists here.

Parameters

[in]	ctx	Transport context supplied by the caller.
[in]	reg	Register offset the caller wanted.
[out]	data	Destination buffer.
[in]	size	Bytes the caller wanted.
[in]	lock_required	Whether the caller wanted the bus lock taken.

Returns

Failure, always.

Return values

RET_INVALID	ctx or data was null, or size was zero.
RET_FAIL	No SDIO transport exists on this board.

Precondition

The caller selected the SDIO transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

data is not written.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 241 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_sdio_read_reg()

int internal_sdio_read_reg ( void * ctx, uint32_t reg, uint8_t * data, uint16_t size, bool lock_required )

static

Vtable row: read an SDIO peripheral register.

See the file header; no SDIO transport exists here.

Parameters

[in]	ctx	Transport context supplied by the caller.
[in]	reg	Register offset the caller wanted.
[out]	data	Destination buffer.
[in]	size	Bytes the caller wanted.
[in]	lock_required	Whether the caller wanted the bus lock taken.

Returns

Failure, always.

Return values

RET_INVALID	ctx or data was null, or size was zero.
RET_FAIL	No SDIO transport exists on this board.

Precondition

The caller selected the SDIO transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

data is not written.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 169 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_sdio_wait_intr()

int internal_sdio_wait_intr ( void * ctx, uint32_t ticks_to_wait )

static

Vtable row: wait for an SDIO peripheral interrupt.

See the file header; no SDIO transport exists here.

Parameters

[in]	ctx	Transport context supplied by the caller.
[in]	ticks_to_wait	How long the caller was prepared to wait.

Returns

Failure, always.

Return values

RET_INVALID	ctx was null.
RET_FAIL	No SDIO transport exists on this board.

Precondition

The caller selected the SDIO transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

The caller is not blocked; the answer is immediate.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 308 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_sdio_write_block()

int internal_sdio_write_block ( void * ctx, uint32_t reg, uint8_t * data, uint16_t size, bool lock_required )

static

Vtable row: write an SDIO data block.

See the file header; no SDIO transport exists here.

Parameters

[in]	ctx	Transport context supplied by the caller.
[in]	reg	Register offset the caller wanted.
[in]	data	Source buffer.
[in]	size	Bytes the caller wanted.
[in]	lock_required	Whether the caller wanted the bus lock taken.

Returns

Failure, always.

Return values

RET_INVALID	ctx or data was null, or size was zero.
RET_FAIL	No SDIO transport exists on this board.

Precondition

The caller selected the SDIO transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

data is not read.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 277 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_sdio_write_reg()

int internal_sdio_write_reg ( void * ctx, uint32_t reg, uint8_t * data, uint16_t size, bool lock_required )

static

Vtable row: write an SDIO peripheral register.

See the file header; no SDIO transport exists here.

Parameters

[in]	ctx	Transport context supplied by the caller.
[in]	reg	Register offset the caller wanted.
[in]	data	Source buffer.
[in]	size	Bytes the caller wanted.
[in]	lock_required	Whether the caller wanted the bus lock taken.

Returns

Failure, always.

Return values

RET_INVALID	ctx or data was null, or size was zero.
RET_FAIL	No SDIO transport exists on this board.

Precondition

The caller selected the SDIO transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

data is not read.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 205 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_spi_hd_read_dma()

int internal_spi_hd_read_dma ( uint8_t * data, uint16_t size, bool lock_required )

static

Vtable row: read a half-duplex SPI data burst.

See the file header; no half-duplex SPI transport exists here.

Parameters

[out]	data	Destination buffer.
[in]	size	Bytes the caller wanted.
[in]	lock_required	Whether the caller wanted the bus lock taken.

Returns

Failure, always.

Return values

RET_INVALID	data was null or size was zero.
RET_FAIL	No half-duplex SPI transport exists on this board.

Precondition

The caller selected the half-duplex SPI transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

data is not written.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 413 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_spi_hd_read_reg()

int internal_spi_hd_read_reg ( uint32_t reg, uint32_t * data, int poll, bool lock_required )

static

Vtable row: read a half-duplex SPI register.

See the file header; the link is full-duplex SPI, not half-duplex, and the two are different bus configurations rather than two modes of one.

Parameters

[in]	reg	Register offset the caller wanted.
[out]	data	Destination word.
[in]	poll	Whether the caller wanted the read polled.
[in]	lock_required	Whether the caller wanted the bus lock taken.

Returns

Failure, always.

Return values

RET_INVALID	data was null.
RET_FAIL	No half-duplex SPI transport exists on this board.

Precondition

The caller selected the half-duplex SPI transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

data is not written.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 344 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_spi_hd_send_cmd9()

int internal_spi_hd_send_cmd9 ( void )

static

Vtable row: issue the half-duplex SPI command-nine sequence.

See the file header; no half-duplex SPI transport exists here. The row takes no parameters, so its only validation is of the module state – which is exactly the condition it reports.

Returns

Failure, always.

Return values

RET_FAIL

No half-duplex SPI transport exists on this board.

Precondition

The caller selected the half-duplex SPI transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

No bus activity occurs.

Exactly one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 512 of file ra8_esp_hosted_osi_absent.c.

References internal_absent().

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_spi_hd_set_data_lines()

int internal_spi_hd_set_data_lines ( uint32_t data_lines )

static

Vtable row: choose how many half-duplex SPI data lines to use.

See the file header; no half-duplex SPI transport exists here.

Parameters

[in]

data_lines

Line count the caller wanted. The half-duplex transport defines exactly three legal widths, named by H_SPI_HD_CONFIG_{1_DATA_LINE,2_DATA_LINES, 4_DATA_LINES}; anything else is a malformed request rather than an unsupported one, and is reported as such.

Returns

Failure, always.

Return values

RET_INVALID	data_lines was not one of the three legal widths.
RET_FAIL	No half-duplex SPI transport exists on this board.

Precondition

The caller selected the half-duplex SPI transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

No bus configuration is changed.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 481 of file ra8_esp_hosted_osi_absent.c.

References H_SPI_HD_CONFIG_1_DATA_LINE, H_SPI_HD_CONFIG_2_DATA_LINES, H_SPI_HD_CONFIG_4_DATA_LINES, internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_spi_hd_write_dma()

int internal_spi_hd_write_dma ( uint8_t * data, uint16_t size, bool lock_required )

static

Vtable row: write a half-duplex SPI data burst.

See the file header; no half-duplex SPI transport exists here.

Parameters

[in]	data	Source buffer.
[in]	size	Bytes the caller wanted.
[in]	lock_required	Whether the caller wanted the bus lock taken.

Returns

Failure, always.

Return values

RET_INVALID	data was null or size was zero.
RET_FAIL	No half-duplex SPI transport exists on this board.

Precondition

The caller selected the half-duplex SPI transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

data is not read.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 446 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_spi_hd_write_reg()

int internal_spi_hd_write_reg ( uint32_t reg, uint32_t * data, bool lock_required )

static

Vtable row: write a half-duplex SPI register.

See the file header; no half-duplex SPI transport exists here.

Parameters

[in]	reg	Register offset the caller wanted.
[in]	data	Source word.
[in]	lock_required	Whether the caller wanted the bus lock taken.

Returns

Failure, always.

Return values

RET_INVALID	data was null.
RET_FAIL	No half-duplex SPI transport exists on this board.

Precondition

The caller selected the half-duplex SPI transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

data is not read.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 379 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_uart_flush_input()

int internal_uart_flush_input ( void * ctx )

static

Vtable row: discard whatever the UART transport has buffered.

See the file header; no UART link to the co-processor exists.

Parameters

[in]

ctx

Transport context supplied by the caller.

Returns

Failure, always.

Return values

RET_INVALID	ctx was null.
RET_FAIL	No UART transport exists on this board.

Precondition

The caller selected the UART transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

No buffer is discarded, because none exists.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 599 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_uart_read()

int internal_uart_read ( void * ctx, uint8_t * data, uint16_t size )

static

Vtable row: read from the UART transport.

See the file header; no UART link to the co-processor exists.

Parameters

[in]	ctx	Transport context supplied by the caller.
[out]	data	Destination buffer.
[in]	size	Bytes the caller wanted.

Returns

Failure, always.

Return values

RET_INVALID	ctx or data was null, or size was zero.
RET_FAIL	No UART transport exists on this board.

Precondition

The caller selected the UART transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

data is not written.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 540 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

Referenced by priv_ra8_esp_hosted_osi_bind_absent().

internal_uart_write()

int internal_uart_write ( void * ctx, uint8_t * data, uint16_t size )

static

Vtable row: write to the UART transport.

See the file header; no UART link to the co-processor exists.

Parameters

[in]	ctx	Transport context supplied by the caller.
[in]	data	Source buffer.
[in]	size	Bytes the caller wanted.

Returns

Failure, always.

Return values

RET_INVALID	ctx or data was null, or size was zero.
RET_FAIL	No UART transport exists on this board.

Precondition

The caller selected the UART transport, which this build does not.

Logging has been initialised, or the line is dropped.

Postcondition

data is not read.

At most one line is emitted.

Note

Reentrant.

Since

0.1.0

Definition at line 571 of file ra8_esp_hosted_osi_absent.c.

References internal_absent(), and RET_INVALID.

priv_ra8_esp_hosted_osi_bind_absent()

void priv_ra8_esp_hosted_osi_bind_absent

(

hosted_osi_funcs_t *

out

)

Implementation of priv_ra8_esp_hosted_osi_bind_absent() – fills all sixteen rows so none is ever left null.

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