port_esp_hosted_host_os.h File Reference

esp-hosted port header: RTOS handle types, return codes and budgets. More...

#include "ra8_check.h"
#include <inttypes.h>
#include <stddef.h>
#include <stdint.h>
#include "esp_heap_caps.h"
#include "esp_hosted_os_abstraction.h"
#include "ra8_esp_hosted_port.h"

Include dependency graph for port_esp_hosted_host_os.h:

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

Go to the source code of this file.

Macros
#define	assert(expr)
	Route vendored ESP-hosted assertions through the RA8 assertion policy.
#define	RET_OK   (0)
	Operation completed.
#define	RET_FAIL   (-1)
	Operation failed for an unspecified reason.
#define	RET_INVALID   (-2)
	A parameter was out of contract (null handle, bad size).
#define	RET_FAIL_TIMEOUT   (-3)
	The requested wait expired before the operation could complete.
#define	HOSTED_BLOCKING   (1)
	Marker meaning "this call may block".
#define	HOSTED_BLOCK_MAX   (0xFFFFFFFF)
	Timeout value meaning "wait until satisfied".
#define	SEC_TO_MILLISEC(x)
	Convert whole seconds to milliseconds.
#define	HOSTED_MEM_ALIGNMENT_64   (64)
	Alignment, in bytes, demanded of transport buffers.
#define	HOSTED_UNLIKELY(x)
	Branch hint: the controlling expression is expected to be false.
#define	HOSTED_LIKELY(x)
	Branch hint: the controlling expression is expected to be true.
#define	HOSTED_FREE(buff)
	Release a pointer through the vtable and null the variable.
#define	MEM_DUMP(s)
	Report heap occupancy at a named point.
#define	DFLT_TASK_PRIO   (12)
	ThreadX priority for the SPI transaction and receive threads.
#define	DFLT_TASK_STACK_SIZE   (4096)
	Stack, in bytes, for each esp-hosted transport thread.
#define	RPC_TASK_PRIO   (14)
	ThreadX priority for the RPC request/response thread.
#define	RPC_TASK_STACK_SIZE   (5120)
	Stack, in bytes, for the RPC thread.
#define	H_TIMER_TYPE_ONESHOT   (1)
	Timer that fires once and then stops.
#define	H_TIMER_TYPE_PERIODIC   (2)
	Timer that reschedules itself after every expiry.
#define	H_GPIO_MODE_DEF_INPUT   (0)
	Configure a side-band pin as a digital input.
#define	H_GPIO_MODE_DEF_OUTPUT   (1)
	Configure a side-band pin as a push-pull digital output.
#define	H_GPIO_PULL_UP   (0)
	Select the internal pull-up when configuring a pin.
#define	H_GPIO_PULL_DOWN   (1)
	Select the internal pull-down when configuring a pin.
#define	MAX_PAYLOAD_SIZE   (MAX_TRANSPORT_BUFFER_SIZE - H_ESP_PAYLOAD_HEADER_OFFSET)
	Largest payload one transport frame can carry, in bytes.
#define	FAST_RAM_ATTR
	Place a function in tightly-coupled RAM for interrupt latency.
#define	H_IRAM_ATTR
	Upstream alias of FAST_RAM_ATTR.
#define	H_WEAK_REF   [[gnu::weak]]
	Mark a definition as overridable at link time.

Typedefs
typedef void *	queue_handle_t
	Opaque handle to a port-owned message queue.
typedef void *	semaphore_handle_t
	Opaque handle to a port-owned counting semaphore.
typedef void *	mutex_handle_t
	Opaque handle to a port-owned mutex.
typedef void *	thread_handle_t
	Opaque handle to a port-owned thread.
typedef void *	spinlock_handle_t
	Opaque handle to a port-owned mempool lock.
typedef uint8_t	gpio_pin_state_t
	Logic level read back from, or driven onto, a side-band pin.

Functions
static void *	heap_caps_malloc (size_t size, uint32_t caps)
	ESP-IDF capability-aware allocation, served from the port pool.

Detailed Description

esp-hosted port header: RTOS handle types, return codes and budgets.

Tag

[Ring 4 / PORT] {World: NS}

One of the ten port headers the vendored esp-hosted core includes by name (see docs/SOUP/esp-hosted-host.md); twelve vendored translation units reach it. Upstream ships an ESP-IDF / FreeRTOS version under host/port/, which this project excludes; this file is its first-party ThreadX replacement and therefore keeps the upstream file name and every upstream symbol spelling exactly.

The core never names a ThreadX type. It moves opaque handles produced by the OS-abstraction vtable (hosted_osi_funcs_t) around, so every handle typedef here is void* and the concrete control block lives behind it in port/esp-hosted/src/. That is what makes the whole hardware- and RTOS-facing surface of this SOUP first-party code.

Timeout units

Every timeout the core passes is in milliseconds, never ticks. Two values are special and both are spelled by the core, not invented here:

• 0 means "do not block" – spi_drv.c relies on this for its non-blocking queue drain and its try-take of the transmit-pending semaphore;
• HOSTED_BLOCK_MAX means "block until satisfied". ThreadX on this board runs a 1 kHz tick (TX_TIMER_TICKS_PER_SECOND is 1000 in port/threadx/inc/tx_user.h), so the millisecond-to-tick conversion in the port is the identity.

Copyright

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

Since

0.1.0

Definition in file port_esp_hosted_host_os.h.

Macro Definition Documentation

assert

#define assert

(

expr

)

Value:

RA8_ASSERT(expr, "esp-hosted assertion")

Route vendored ESP-hosted assertions through the RA8 assertion policy.

Definition at line 44 of file port_esp_hosted_host_os.h.

Referenced by ra8__mdl__accepted__free_unpacked(), ra8__mdl__accepted__get_packed_size(), ra8__mdl__accepted__pack(), ra8__mdl__accepted__pack_to_buffer(), ra8__mdl__cancel_request__free_unpacked(), ra8__mdl__cancel_request__get_packed_size(), ra8__mdl__cancel_request__pack(), ra8__mdl__cancel_request__pack_to_buffer(), ra8__mdl__cancelled__free_unpacked(), ra8__mdl__cancelled__get_packed_size(), ra8__mdl__cancelled__pack(), ra8__mdl__cancelled__pack_to_buffer(), ra8__mdl__chunk__free_unpacked(), ra8__mdl__chunk__get_packed_size(), ra8__mdl__chunk__pack(), ra8__mdl__chunk__pack_to_buffer(), ra8__mdl__next_request__free_unpacked(), ra8__mdl__next_request__get_packed_size(), ra8__mdl__next_request__pack(), ra8__mdl__next_request__pack_to_buffer(), ra8__mdl__start_request__free_unpacked(), ra8__mdl__start_request__get_packed_size(), ra8__mdl__start_request__pack(), and ra8__mdl__start_request__pack_to_buffer().

DFLT_TASK_PRIO

#define DFLT_TASK_PRIO   (12)

ThreadX priority for the SPI transaction and receive threads.

Twelve, comfortably above application work and below the kernel timer thread, so a co-processor edge is serviced promptly without starving anything that owns the display or storage.

Note

Read-only build configuration.

Warning

Zero is the highest ThreadX priority; do not copy a FreeRTOS value here.

Example:

g_h.funcs->_h_thread_create("spi_trans", DFLT_TASK_PRIO, ...);

Since

0.1.0

Definition at line 479 of file port_esp_hosted_host_os.h.

DFLT_TASK_STACK_SIZE

#define DFLT_TASK_STACK_SIZE   (4096)

Stack, in bytes, for each esp-hosted transport thread.

Four kibibytes. The deepest path is the receive dispatcher running the payload-header decode and the checksum sweep over a 1600-byte frame, all of which works out of the caller's buffers rather than the stack.

Note

Read-only build configuration.

Warning

Must be at least TX_MINIMUM_STACK (512) or thread creation fails.

Example:

g_h.funcs->_h_thread_create("spi_rx", DFLT_TASK_PRIO, DFLT_TASK_STACK_SIZE, fn, NULL);

Since

0.1.0

Definition at line 497 of file port_esp_hosted_host_os.h.

FAST_RAM_ATTR

#define FAST_RAM_ATTR

Place a function in tightly-coupled RAM for interrupt latency.

Empty on this target. The RA8D2 executes from 1 MB of MRAM behind the Cortex-M85 caches; there is no separate low-latency instruction RAM to relocate into, so an attribute here would name a section the linker script does not define. The two functions upstream marks with it are the side-band edge handlers, which the port already services through the ICU with a dedicated NVIC priority.

Note

Read-only build configuration.

Warning

Do not point this at a section that no linker script places.

Example:

static void FAST_RAM_ATTR gpio_dr_isr_handler(void *arg) { ... }

Since

0.1.0

Definition at line 670 of file port_esp_hosted_host_os.h.

H_GPIO_MODE_DEF_INPUT

#define H_GPIO_MODE_DEF_INPUT   (0)

Configure a side-band pin as a digital input.

Passed as the mode argument of _h_config_gpio.

Note

Read-only build configuration.

Warning

The RA8D2 pin must not already be claimed by a peripheral.

Example:

g_h.funcs->_h_config_gpio(port, pin, H_GPIO_MODE_DEF_INPUT);

Since

0.1.0

Definition at line 578 of file port_esp_hosted_host_os.h.

Referenced by internal_configure_sideband().

H_GPIO_MODE_DEF_OUTPUT

#define H_GPIO_MODE_DEF_OUTPUT   (1)

Configure a side-band pin as a push-pull digital output.

Passed as the mode argument of _h_config_gpio; the co-processor reset line is the only pin the host drives this way.

Note

Read-only build configuration.

Warning

Never apply this to HANDSHAKE or DATA_READY – the C6 drives both push-pull and the pins would contend.

Example:

g_h.funcs->_h_config_gpio(port, pin, H_GPIO_MODE_DEF_OUTPUT);

Since

0.1.0

Definition at line 594 of file port_esp_hosted_host_os.h.

H_GPIO_PULL_DOWN

#define H_GPIO_PULL_DOWN   (1)

Select the internal pull-down when configuring a pin.

Passed as pull_value to _h_pull_gpio. The RA8D2 PFS carries a pull-up bit only, so the port accepts this selector, reports it honestly through its return code and does not pretend a pull-down was installed.

Note

Read-only build configuration.

Warning

The RA8D2 has no internal pull-down; fit an external resistor.

Example:

g_h.funcs->_h_pull_gpio(port, pin, H_GPIO_PULL_DOWN, H_ENABLE);

Since

0.1.0

Definition at line 625 of file port_esp_hosted_host_os.h.

H_GPIO_PULL_UP

#define H_GPIO_PULL_UP   (0)

Select the internal pull-up when configuring a pin.

Passed as pull_value to _h_pull_gpio.

Note

Read-only build configuration.

Warning

Only meaningful on an input.

Example:

g_h.funcs->_h_pull_gpio(port, pin, H_GPIO_PULL_UP, H_ENABLE);

Since

0.1.0

Definition at line 608 of file port_esp_hosted_host_os.h.

H_IRAM_ATTR

#define H_IRAM_ATTR

Upstream alias of FAST_RAM_ATTR.

Empty for the same reason: the RA8D2 has no instruction RAM distinct from the MRAM the image already executes from.

Note

Read-only build configuration.

Warning

See FAST_RAM_ATTR.

Example:

H_IRAM_ATTR void handler(void) { ... }

Since

0.1.0

Definition at line 685 of file port_esp_hosted_host_os.h.

H_TIMER_TYPE_ONESHOT

#define H_TIMER_TYPE_ONESHOT   (1)

Timer that fires once and then stops.

Selector passed to _h_timer_start.

Note

Read-only build configuration.

Warning

The handle stays valid after expiry; stop it to release it.

Example:

g_h.funcs->_h_timer_start("rpc_tmo", 5000, H_TIMER_TYPE_ONESHOT, cb, arg);

Since

0.1.0

Definition at line 546 of file port_esp_hosted_host_os.h.

Referenced by internal_h_timer_start().

H_TIMER_TYPE_PERIODIC

#define H_TIMER_TYPE_PERIODIC   (2)

Timer that reschedules itself after every expiry.

Selector passed to _h_timer_start.

Note

Read-only build configuration.

Warning

Runs until explicitly stopped with _h_timer_stop.

Example:

g_h.funcs->_h_timer_start("hb", 1000, H_TIMER_TYPE_PERIODIC, cb, arg);

Since

0.1.0

Definition at line 560 of file port_esp_hosted_host_os.h.

Referenced by internal_h_timer_start().

H_WEAK_REF

#define H_WEAK_REF   [[gnu::weak]]

Mark a definition as overridable at link time.

The vendored Bluetooth drivers define hci_rx_handler weakly so an application can replace it. Spelled in the C23 attribute form the project mandates, which GCC accepts on both the ARM cross build and the host test build.

Note

Read-only build configuration.

Warning

A weak symbol that nothing overrides still links; check that the intended strong definition is actually in the image.

Example:

H_WEAK_REF int hci_rx_handler(uint8_t *buf, size_t len) { return 0; }

Since

0.1.0

Definition at line 703 of file port_esp_hosted_host_os.h.

HOSTED_BLOCK_MAX

#define HOSTED_BLOCK_MAX   (0xFFFFFFFF)

Timeout value meaning "wait until satisfied".

All ones. The port maps exactly this value onto ThreadX's TX_WAIT_FOREVER; every other value is a millisecond count. The vtable takes int timeouts, so this arrives as -1 after conversion – the port therefore treats "all ones or any negative value" as forever, which keeps a sign-extension bug from silently becoming a busy loop.

Note

Read-only build configuration.

Warning

A thread blocked on this can only be released by a post or by thread termination.

Example:

g_h.funcs->_h_get_semaphore(sem, HOSTED_BLOCK_MAX);

Since

0.1.0

Definition at line 246 of file port_esp_hosted_host_os.h.

HOSTED_BLOCKING

#define HOSTED_BLOCKING   (1)

Marker meaning "this call may block".

Passed where the core wants a blocking flag rather than a duration.

Note

Read-only build configuration.

Warning

Not a timeout; do not pass it where milliseconds are expected.

Example:

serial_drv_open(SERIAL_IF_FILE, HOSTED_BLOCKING);

Since

0.1.0

Definition at line 227 of file port_esp_hosted_host_os.h.

HOSTED_FREE

#define HOSTED_FREE

(

buff

)

Value:

do {                                                                                             \
  if (buff) {                                                                                    \
    g_h.funcs->_h_free(buff);                                                                    \
    (buff) = nullptr;                                                                            \
  }                                                                                              \
} while (0)

Release a pointer through the vtable and null the variable.

Nulling is part of the contract: the vendored code frees a buffer on one path and tests the same variable on another.

Parameters

[in,out]

buff

Pointer variable to release and clear.

Note

Read-only build configuration.

Warning

buff must be an lvalue; the macro assigns to it.

Example:

HOSTED_FREE(copy_payload);

Since

0.1.0

Definition at line 401 of file port_esp_hosted_host_os.h.

HOSTED_LIKELY

#define HOSTED_LIKELY

(

x

)

Value:

(__builtin_expect(!!(x), 1))

Branch hint: the controlling expression is expected to be true.

The companion of HOSTED_UNLIKELY. The vendored likely token is mapped to this macro only while compiling esp_hosted_objs.

Parameters

[in]

x

Expression to test; evaluated exactly once.

Note

Read-only build configuration.

Warning

A wrong hint costs a mispredict, never correctness.

Example:

if (HOSTED_LIKELY(len > 0)) { transmit(buf, len); }

Since

0.1.0

Definition at line 320 of file port_esp_hosted_host_os.h.

HOSTED_MEM_ALIGNMENT_64

#define HOSTED_MEM_ALIGNMENT_64   (64)

Alignment, in bytes, demanded of transport buffers.

Sixty-four. Upstream chose it for ESP DMA; it is equally correct here because the Cortex-M85 data cache line on this part is 64 bytes, so a buffer aligned to it can be cleaned and invalidated without touching a neighbouring allocation.

Note

Read-only build configuration.

Warning

Lowering this would make cache maintenance around a DMA-driven SPI transfer corrupt adjacent data.

Example:

void *p = g_h.funcs->_h_malloc_align(len, HOSTED_MEM_ALIGNMENT_64);

Since

0.1.0

Definition at line 285 of file port_esp_hosted_host_os.h.

Referenced by heap_caps_malloc().

HOSTED_UNLIKELY

#define HOSTED_UNLIKELY

(

x

)

Value:

(__builtin_expect(!!(x), 0))

Branch hint: the controlling expression is expected to be false.

ESP-IDF supplies the vendor-facing unlikely spelling from esp_compiler.h. The esp_hosted_objs target maps that token to this first-party macro without modifying the pinned vendor tree. A macro, not a function: __builtin_expect has to see the expression at the call site to steer code layout.

Parameters

[in]

x

Expression to test; evaluated exactly once.

Note

Read-only build configuration.

Warning

A wrong hint costs a mispredict, never correctness.

Example:

if (HOSTED_UNLIKELY(ret)) { HOSTED_FREE(copy_payload); }

Since

0.1.0

Definition at line 304 of file port_esp_hosted_host_os.h.

MAX_PAYLOAD_SIZE

#define MAX_PAYLOAD_SIZE   (MAX_TRANSPORT_BUFFER_SIZE - H_ESP_PAYLOAD_HEADER_OFFSET)

Largest payload one transport frame can carry, in bytes.

The frame size less the twelve-byte esp-hosted payload header, so 1588 for the SPI transport. The receive path rejects any header claiming more than this, which is the first bound applied to co-processor-supplied data.

Note

Read-only build configuration.

Warning

Derived from MAX_TRANSPORT_BUFFER_SIZE; the transport- specific port header must be included first.

Example:

if (len > MAX_PAYLOAD_SIZE) { drop_frame(); }

Since

0.1.0

Definition at line 647 of file port_esp_hosted_host_os.h.

Referenced by c6_fwver_print_banner().

MEM_DUMP

#define MEM_DUMP

(

s

)

Value:

ra8_esp_hosted_mem_dump(s)

Report heap occupancy at a named point.

Routed to the port's allocator statistics, which are real numbers here: the transport pool is a fixed ThreadX byte pool, so "largest free block" and "bytes available" are both meaningful and are exactly what a fragmentation problem shows up in.

Parameters

[in]

s

Short label naming the call site.

Note

Read-only build configuration.

Warning

Emits at info level; noisy if placed on a per-packet path.

Example:

MEM_DUMP("spi_mempool_create");

Since

0.1.0

Definition at line 454 of file port_esp_hosted_host_os.h.

RET_FAIL

#define RET_FAIL   (-1)

Operation failed for an unspecified reason.

Minus one, matching the vendored FAILURE spelling.

Note

Read-only build configuration.

Warning

Distinct from RET_FAIL_TIMEOUT so callers can retry sensibly.

Example:

return RET_FAIL;

Since

0.1.0

Definition at line 178 of file port_esp_hosted_host_os.h.

Referenced by internal_absent(), internal_bus_deinit(), internal_config_gpio(), internal_config_gpio_as_interrupt(), internal_config_host_power_save(), internal_do_bus_transfer(), internal_h_dequeue_item(), internal_h_destroy_mutex(), internal_h_destroy_queue(), internal_h_destroy_semaphore(), internal_h_post_semaphore(), internal_h_post_semaphore_from_isr(), internal_h_queue_item(), internal_h_reset_queue(), internal_h_thread_cancel(), internal_h_timer_stop(), internal_h_unlock_mutex(), internal_hold_gpio(), internal_pull_gpio(), internal_read_gpio(), internal_restart_host(), internal_start_host_power_save(), internal_teardown_gpio_interrupt(), internal_write_gpio(), and priv_ra8_esp_hosted_osi_dispatch_event().

RET_FAIL_TIMEOUT

#define RET_FAIL_TIMEOUT   (-3)

The requested wait expired before the operation could complete.

Distinguishes "nothing arrived in time" from a hard failure so the SPI transaction pump can keep polling rather than tear down.

Note

Read-only build configuration.

Warning

A zero-millisecond wait that finds nothing reports this too.

Example:

if (rc == RET_FAIL_TIMEOUT) { continue; }

Since

0.1.0

Definition at line 208 of file port_esp_hosted_host_os.h.

Referenced by internal_h_dequeue_item(), internal_h_get_semaphore(), internal_h_lock_mutex(), and internal_h_queue_item().

RET_INVALID

#define RET_INVALID   (-2)

A parameter was out of contract (null handle, bad size).

Reported for programming errors rather than runtime conditions.

Note

Read-only build configuration.

Warning

The core mostly treats any non-zero code alike; the distinction exists for the port's own logs and tests.

Example:

if (queue_handle == nullptr) { return RET_INVALID; }

Since

0.1.0

Definition at line 193 of file port_esp_hosted_host_os.h.

Referenced by internal_bus_deinit(), internal_config_gpio(), internal_config_gpio_as_interrupt(), internal_do_bus_transfer(), internal_h_dequeue_item(), internal_h_destroy_mutex(), internal_h_destroy_queue(), internal_h_destroy_semaphore(), internal_h_get_semaphore(), internal_h_lock_mutex(), internal_h_post_semaphore(), internal_h_post_semaphore_from_isr(), internal_h_queue_item(), internal_h_queue_msg_waiting(), internal_h_reset_queue(), internal_h_thread_cancel(), internal_h_timer_stop(), internal_h_unlock_mutex(), internal_hold_gpio(), internal_pull_gpio(), internal_read_gpio(), 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_set_data_lines(), internal_spi_hd_write_dma(), internal_spi_hd_write_reg(), internal_teardown_gpio_interrupt(), internal_uart_flush_input(), internal_uart_read(), internal_uart_write(), internal_write_gpio(), and priv_ra8_esp_hosted_osi_dispatch_event().

RET_OK

#define RET_OK   (0)

Operation completed.

Zero, so if (!g_h.funcs->_h_get_semaphore(sem, 0)) reads as "the take succeeded" – a spelling the vendored SPI driver depends on.

Note

Read-only build configuration.

Warning

Must stay zero; the core tests these codes for truthiness.

Example:

if (rc == RET_OK) { proceed(); }

Since

0.1.0

Definition at line 164 of file port_esp_hosted_host_os.h.

Referenced by c6_fwver_link_pump(), c6_hosted_classify(), internal_bus_deinit(), internal_config_gpio(), internal_config_gpio_as_interrupt(), internal_configure_sideband(), internal_do_bus_transfer(), internal_h_dequeue_item(), internal_h_destroy_mutex(), internal_h_destroy_queue(), internal_h_destroy_semaphore(), internal_h_get_semaphore(), internal_h_lock_mutex(), internal_h_post_semaphore(), internal_h_post_semaphore_from_isr(), internal_h_queue_item(), internal_h_reset_queue(), internal_h_thread_cancel(), internal_h_timer_stop(), internal_h_unlock_mutex(), internal_pull_gpio(), internal_ra8_esp_hosted_c6link_transfer(), internal_teardown_gpio_interrupt(), internal_write_gpio(), priv_ra8_esp_hosted_osi_dispatch_event(), priv_ra8_esp_hosted_rtos_deinit(), and priv_ra8_esp_hosted_rtos_sync_deinit().

RPC_TASK_PRIO

#define RPC_TASK_PRIO   (14)

ThreadX priority for the RPC request/response thread.

Fourteen – one notch below the transport threads, because RPC work is only meaningful once the transport has already delivered a frame.

Note

Read-only build configuration.

Warning

Raising it above DFLT_TASK_PRIO can starve the transport.

Example:

g_h.funcs->_h_thread_create("rpc", RPC_TASK_PRIO, RPC_TASK_STACK_SIZE, fn, NULL);

Since

0.1.0

Definition at line 513 of file port_esp_hosted_host_os.h.

RPC_TASK_STACK_SIZE

#define RPC_TASK_STACK_SIZE   (5120)

Stack, in bytes, for the RPC thread.

Five kibibytes: the protobuf-c decoder recurses through nested messages, so this thread is deeper than the transport ones.

Note

Read-only build configuration.

Warning

Must be at least TX_MINIMUM_STACK (512).

Example:

g_h.funcs->_h_thread_create("rpc", RPC_TASK_PRIO, RPC_TASK_STACK_SIZE, fn, NULL);

Since

0.1.0

Definition at line 528 of file port_esp_hosted_host_os.h.

SEC_TO_MILLISEC

#define SEC_TO_MILLISEC

(

x

)

Value:

((x) * (1000))

Convert whole seconds to milliseconds.

The core expresses a few waits in seconds and multiplies by this to reach the millisecond-based vtable.

Parameters

[in]

x

Seconds to convert.

Note

Read-only build configuration.

Warning

Argument is evaluated once but is not parenthesised by the caller; pass a simple expression.

Example:

g_h.funcs->_h_msleep(SEC_TO_MILLISEC(2));

Since

0.1.0

Definition at line 263 of file port_esp_hosted_host_os.h.

Typedef Documentation

gpio_pin_state_t

typedef uint8_t gpio_pin_state_t

Logic level read back from, or driven onto, a side-band pin.

The core compares values of this type against H_HS_VAL_ACTIVE and friends, so it must be an integer type wide enough for a zero/one level. _h_read_gpio returns int, which converts to this without loss.

Note

Zero is a low level, one is a high level.

Since

0.1.0

Definition at line 145 of file port_esp_hosted_host_os.h.

mutex_handle_t

typedef void* mutex_handle_t

Opaque handle to a port-owned mutex.

Produced by _h_create_mutex; guards the SPI bus so a direct power-save transaction cannot interleave with the transaction task.

Note

Priority inheritance is enabled by the port.

Since

0.1.0

Definition at line 111 of file port_esp_hosted_host_os.h.

queue_handle_t

typedef void* queue_handle_t

Opaque handle to a port-owned message queue.

Produced by _h_create_queue and consumed by _h_queue_item / _h_dequeue_item / _h_destroy_queue. Backed by a TX_QUEUE plus its storage inside the port.

Note

Never dereferenced by the vendored core.

Since

0.1.0

Definition at line 89 of file port_esp_hosted_host_os.h.

semaphore_handle_t

typedef void* semaphore_handle_t

Opaque handle to a port-owned counting semaphore.

Produced by _h_create_semaphore. The SPI driver keeps three of these (transaction-ready, transmit-queue-pending, receive-queue- pending) as file-scope globals.

Note

Posted from interrupt context via _h_post_semaphore_from_isr.

Since

0.1.0

Definition at line 100 of file port_esp_hosted_host_os.h.

spinlock_handle_t

typedef void* spinlock_handle_t

Opaque handle to a port-owned mempool lock.

Produced by _h_create_lock_mempool. Despite the upstream name it is not a spin lock here: on a single-core RTOS the correct primitive is a mutex, and that is what the port supplies.

Note

Only used when ::H_USE_MEMPOOL is set.

Since

0.1.0

Definition at line 133 of file port_esp_hosted_host_os.h.

thread_handle_t

typedef void* thread_handle_t

Opaque handle to a port-owned thread.

Produced by _h_thread_create and passed back to _h_thread_cancel. The SPI transport creates two: the transaction pump and the receive dispatcher.

Note

Threads are drawn from a fixed pool; there is no heap.

Since

0.1.0

Definition at line 122 of file port_esp_hosted_host_os.h.

Function Documentation

heap_caps_malloc()

void * heap_caps_malloc ( size_t size, uint32_t caps )

inlinestatic

ESP-IDF capability-aware allocation, served from the port pool.

host/drivers/transport/transport_util.c calls this on the capability-carrying arm of transport_util_calloc. ESP-IDF implements it in its heap component; this host has no such component, and until this definition existed the call compiled under the C89 implicit-declaration rule as int heap_caps_malloc() – an int return assigned straight into a void * – and left an undefined heap_caps_malloc reference in the object that only linker garbage collection kept out of the image.

The RA8D2 has one transport pool and it is internal, byte-addressable SRAM reachable by both the DMAC and the SCI, so every capability the vendored tree asks for is satisfiable from it. The one bit that changes the ANSWER rather than the question is MALLOC_CAP_DMA, which is routed through the aligned allocator so the block starts on a HOSTED_MEM_ALIGNMENT_64 boundary and cache maintenance around a DMA-driven transfer cannot touch a neighbouring allocation. That is the identical treatment transport_util_malloc gives HOSTED_MEM_CAP_DMA two functions above the call site.

Parameters

[in]	size	Payload bytes required; must be non-zero.
[in]	caps	Bitwise or of ra8_esp_hosted_malloc_cap_t values.

Returns

Pointer to the payload, or null on failure.

Return values

nullptr	The vtable is not bound, size is zero, or the pool could not serve the request.
non-null	A block of at least size bytes, aligned to HOSTED_MEM_ALIGNMENT_64 when MALLOC_CAP_DMA was requested.

Precondition

ra8_esp_hosted_port_init has bound the OS-abstraction vtable.

size is non-zero.

Postcondition

On success the pool reports fewer bytes available.

On failure the pool is unchanged.

Note

Thread-safe; ThreadX serialises the underlying byte pool.

Warning

Release the block with g_h.funcs->_h_free_align when MALLOC_CAP_DMA was requested and _h_free otherwise; the port uses one header for both, so either spelling is correct, but free() is not.

Example:

void *dma = heap_caps_malloc(len, MALLOC_CAP_INTERNAL | MALLOC_CAP_DMA);

See also

ra8_esp_hosted_malloc_cap_t The capability bits.

Since

0.1.0

Definition at line 372 of file port_esp_hosted_host_os.h.

References g_h, HOSTED_MEM_ALIGNMENT_64, and MALLOC_CAP_DMA.