port_esp_hosted_host_config_transports.h File Reference

esp-hosted port header: constants for the transports not in use. More...

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

Go to the source code of this file.

Macros
#define	H_SPI_HD_HOST_INTERFACE   (0)
	Whether the host drives the half-duplex SPI interface.
#define	H_SPI_HD_HOST_NUM_DATA_LINES   (4)
	Data lines the host would use in half-duplex mode.
#define	H_SPI_HD_CONFIG_1_DATA_LINE   (1)
	Selector passed to the port when one data line is negotiated.
#define	H_SPI_HD_CONFIG_2_DATA_LINES   (2)
	Selector passed to the port when two data lines are negotiated.
#define	H_SPI_HD_CONFIG_4_DATA_LINES   (4)
	Selector passed to the port when four data lines are negotiated.
#define	H_SPI_HD_CLK_MHZ   (5)
	Half-duplex SPI clock, in megahertz.
#define	H_SPI_HD_CHECKSUM   (1)
	Whether half-duplex frames carry the esp-hosted checksum.
#define	H_SPI_HD_DATA_READY_ENABLED   (1)
	Whether half-duplex uses a DATA_READY line rather than polling.
#define	H_SPI_HD_PORT_DATA_READY   (H_GPIO_DATA_READY_Port)
	Opaque port handle of the half-duplex DATA_READY input.
#define	H_SPI_HD_PIN_DATA_READY   (H_GPIO_DATA_READY_Pin)
	Pin index of the half-duplex DATA_READY input.
#define	H_SPI_HD_DR_INTR_EDGE   (H_DR_INTR_EDGE)
	Interrupt sense for the half-duplex DATA_READY input.
#define	H_SPI_HD_POLL_INTERVAL_MS   (10)
	Fallback poll period when half-duplex has no DATA_READY line.
#define	H_SPI_HD_TX_QUEUE_SIZE   (H_TRANSPORT_QUEUE_SIZE)
	Frames queued towards the co-processor in half-duplex mode.
#define	H_SPI_HD_RX_QUEUE_SIZE   (H_TRANSPORT_QUEUE_SIZE)
	Frames queued from the co-processor in half-duplex mode.
#define	H_SDIO_ALWAYS_HOST_RX_MAX_TRANSPORT_SIZE   (1)
	Receive-mode id: always read a whole maximum-size transport buffer.
#define	H_SDIO_HOST_STREAMING_MODE   (2)
	Receive-mode id: treat the SDIO link as a byte stream.
#define	H_SDIO_HOST_RX_MODE   (0)
	Which SDIO receive mode the host would use.
#define	H_SDIO_CHECKSUM   (1)
	Whether SDIO frames carry the esp-hosted checksum.
#define	H_SDIO_CLOCK_FREQ_KHZ   (40000)
	SDIO clock, in kilohertz.
#define	H_SDIO_TX_BLOCK_ONLY_XFER   (0)
	Whether SDIO transmits are padded up to whole blocks.
#define	H_SDIO_RX_BLOCK_ONLY_XFER   (0)
	Whether SDIO receives are padded up to whole blocks.
#define	H_HOST_SDIO_RESET_DELAY_MS   (100)
	Milliseconds the host waits after resetting the SDIO co-processor.
#define	H_SLAVE_RESET_ONLY_IF_NECESSARY   (0) /* LEGACY-OK: upstream esp-hosted macro name */
	Whether the host resets the co-processor only when it looks stuck.
#define	H_RESET_ON_EVERY_BOOTUP   (1)
	The complement of the conditional-reset switch above.
#define	H_TRANSPORT_RESTART_ON_FAILURE   (0)
	Whether a transport failure restarts the whole host.
#define	H_UART_HOST_TRANSPORT   (0)
	Whether the host drives the UART transport.
#define	H_UART_CHECKSUM   (1)
	Whether UART frames carry the esp-hosted checksum.
#define	H_UART_TX_QUEUE_SIZE   (H_TRANSPORT_QUEUE_SIZE)
	Frames queued towards the co-processor over UART.
#define	H_UART_RX_QUEUE_SIZE   (H_TRANSPORT_QUEUE_SIZE)
	Frames queued from the co-processor over UART.

Detailed Description

esp-hosted port header: constants for the transports not in use.

Tag

[Ring 4 / PORT] {World: NS}

Included from the bottom of port_esp_hosted_host_config.h, which is the file name the vendored core knows. It exists because that header would otherwise cross the repository's 1000-line maintainability cap, and because these constants answer a different question from the ones there: not "how is this board wired" but "what do the three transports this board does not use need in order to compile".

Why constants for unused transports exist at all

H_TRANSPORT_IN_USE selects full-duplex SPI, but the vendored sdio_drv.c, spi_hd_drv.c and uart_drv.c are still translation units in the build, and transport_drv.c reads a handful of their constants unconditionally when it decodes the co-processor's capability word. Leaving a symbol undefined would make the preprocessor substitute zero and silently pick a different branch, so each one is given a real, defensible value instead.

Where the values come from

The SDIO and half-duplex numbers describe what those transports would need on an EK-RA8D2 if they were ever wired: the SDHI slot's 40 MHz ceiling, the same DATA_READY net and polarity the full-duplex link already uses, and the same queue depth. They are not aspirational defaults copied from an Espressif development kit.

Copyright

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

Since

0.1.0

Definition in file port_esp_hosted_host_config_transports.h.

Macro Definition Documentation

H_HOST_SDIO_RESET_DELAY_MS

#define H_HOST_SDIO_RESET_DELAY_MS   (100)

Milliseconds the host waits after resetting the SDIO co-processor.

One hundred, comfortably past an ESP32 part's boot-ROM handoff, so the first CMD0 is not answered by a half-initialised card interface.

Note

Read-only build configuration.

Warning

Too short a delay looks exactly like a dead co-processor: the host reports no response and gives up.

Example:

g_h.funcs->_h_msleep(H_HOST_SDIO_RESET_DELAY_MS);

Since

0.1.0

Definition at line 419 of file port_esp_hosted_host_config_transports.h.

H_RESET_ON_EVERY_BOOTUP

#define H_RESET_ON_EVERY_BOOTUP   (1)

The complement of the conditional-reset switch above.

One. The vendored SDIO driver names this only in the comment on the #else half of its reset selector, so nothing reads it; it is defined here so the pair is stated explicitly rather than left implied by a comment.

Note

Read-only build configuration.

Warning

Setting both this and the conditional-reset switch to 1 would be self-contradictory, and nothing checks.

Example:

static_assert(H_RESET_ON_EVERY_BOOTUP == 1, "reset policy");

Since

0.1.0

Definition at line 456 of file port_esp_hosted_host_config_transports.h.

H_SDIO_ALWAYS_HOST_RX_MAX_TRANSPORT_SIZE

#define H_SDIO_ALWAYS_HOST_RX_MAX_TRANSPORT_SIZE   (1)

Receive-mode id: always read a whole maximum-size transport buffer.

One. Trades bus time for never having to ask the co-processor how many bytes are waiting.

Note

Read-only build configuration.

Warning

An id, not a switch. Compare it against H_SDIO_HOST_RX_MODE.

Example:

#if H_SDIO_HOST_RX_MODE == H_SDIO_ALWAYS_HOST_RX_MAX_TRANSPORT_SIZE
read_fixed_size_block();
#endif

Since

0.1.0

Definition at line 292 of file port_esp_hosted_host_config_transports.h.

H_SDIO_CHECKSUM

#define H_SDIO_CHECKSUM   (1)

Whether SDIO frames carry the esp-hosted checksum.

One, for the same reason as H_SPI_HD_CHECKSUM: the header checksum is the receiver's only integrity evidence.

Note

Read-only build configuration.

Warning

Both ends must agree.

Example:

#if H_SDIO_CHECKSUM
rx_checksum = le16toh(header->checksum);
#endif

Since

0.1.0

Definition at line 348 of file port_esp_hosted_host_config_transports.h.

H_SDIO_CLOCK_FREQ_KHZ

#define H_SDIO_CLOCK_FREQ_KHZ   (40000)

SDIO clock, in kilohertz.

Forty thousand. Forty megahertz is the ceiling the driver itself names for a PCB-routed SDIO bus, and it is what the EK-RA8D2 SDHI slot is qualified for with the SD card already fitted.

Note

Read-only build configuration.

Warning

The driver logs a hint below 40000; that hint is about signal integrity headroom, not a defect.

Example:

sdio_config.clock_freq_khz = H_SDIO_CLOCK_FREQ_KHZ;

Since

0.1.0

Definition at line 365 of file port_esp_hosted_host_config_transports.h.

H_SDIO_HOST_RX_MODE

#define H_SDIO_HOST_RX_MODE   (0)

Which SDIO receive mode the host would use.

Zero, which matches neither named id and therefore selects the driver's plain packet mode: read the length the co-processor advertises in its register, then read exactly that many bytes. That is the mode with the least bus waste and no reassembly state, and it is what an EK-RA8D2 SDHI slot would want.

Note

Read-only build configuration.

Warning

Never set this to an id the driver does not know; the mode is chosen by != comparisons, so an unknown value quietly selects packet mode.

Example:

#if H_SDIO_HOST_RX_MODE != H_SDIO_HOST_STREAMING_MODE
packet_mode_rx();
#endif

Since

0.1.0

Definition at line 331 of file port_esp_hosted_host_config_transports.h.

H_SDIO_HOST_STREAMING_MODE

#define H_SDIO_HOST_STREAMING_MODE   (2)

Receive-mode id: treat the SDIO link as a byte stream.

Two. Removes the per-packet framing at the cost of a double-buffer and a reassembly state machine in the driver.

Note

Read-only build configuration.

Warning

An id, not a switch. Compare it against H_SDIO_HOST_RX_MODE.

Example:

#if H_SDIO_HOST_RX_MODE == H_SDIO_HOST_STREAMING_MODE
stream_reassemble();
#endif

Since

0.1.0

Definition at line 309 of file port_esp_hosted_host_config_transports.h.

H_SDIO_RX_BLOCK_ONLY_XFER

#define H_SDIO_RX_BLOCK_ONLY_XFER   (0)

Whether SDIO receives are padded up to whole blocks.

Zero, matching H_SDIO_TX_BLOCK_ONLY_XFER so both directions agree about framing.

Note

Read-only build configuration.

Warning

With this at 1 every receive buffer must be rounded up before it is allocated, or the transfer overruns it.

Example:

#if H_SDIO_RX_BLOCK_ONLY_XFER
len = round_up_to_block(len);
#endif

Since

0.1.0

Definition at line 403 of file port_esp_hosted_host_config_transports.h.

H_SDIO_TX_BLOCK_ONLY_XFER

#define H_SDIO_TX_BLOCK_ONLY_XFER   (0)

Whether SDIO transmits are padded up to whole blocks.

Zero. Padding every frame to a block boundary wastes bus time on the short RPC frames that dominate this link, and the co-processor already accepts byte-granular transfers.

Note

Read-only build configuration.

Warning

Turning this on also changes how much memory the receive path allocates; the two block-only switches are not independent of the buffer sizing.

Example:

#if H_SDIO_TX_BLOCK_ONLY_XFER
len_to_send = round_up_to_block(len_to_send);
#endif

Since

0.1.0

Definition at line 385 of file port_esp_hosted_host_config_transports.h.

H_SLAVE_RESET_ONLY_IF_NECESSARY

#define H_SLAVE_RESET_ONLY_IF_NECESSARY   (0) /* LEGACY-OK: upstream esp-hosted macro name */

Whether the host resets the co-processor only when it looks stuck.

Zero, so the host resets on every boot. Conditional reset needs a reliable "is it already up" probe, and this harness has no reset wire at all (H_GPIO_PIN_RESET is -1), so the conditional path would be deciding between two things it cannot do.

Note

Read-only build configuration.

Warning

Only reachable in the SDIO driver; the full-duplex SPI driver resets unconditionally when a reset pin exists.

Example:

#if H_SLAVE_RESET_ONLY_IF_NECESSARY // LEGACY-OK: upstream macro name
reset_if_unresponsive();
#endif

Since

0.1.0

Definition at line 438 of file port_esp_hosted_host_config_transports.h.

H_SPI_HD_CHECKSUM

#define H_SPI_HD_CHECKSUM   (1)

Whether half-duplex frames carry the esp-hosted checksum.

One. A half-duplex link has no return path to corroborate a frame, so the 16-bit header checksum is the only integrity evidence the receiver gets.

Note

Read-only build configuration.

Warning

Both ends must agree; the co-processor drops frames whose checksum field it was not expecting.

Example:

#if H_SPI_HD_CHECKSUM
header->checksum = htole16(compute_checksum(buf, len));
#endif

Since

0.1.0

Definition at line 157 of file port_esp_hosted_host_config_transports.h.

H_SPI_HD_CLK_MHZ

#define H_SPI_HD_CLK_MHZ   (5)

Half-duplex SPI clock, in megahertz.

Five, the same conservative first-light rate as the full-duplex link: the RA8 side would use the same polled Simple-SPI backend, so the software ceiling is identical.

Note

Read-only build configuration.

Warning

spi_hd_drv.c logs a hint below 40 MHz; that is the co-processor's limit, not this board's.

Example:

spi_hd_config.clk_mhz = H_SPI_HD_CLK_MHZ;

Since

0.1.0

Definition at line 138 of file port_esp_hosted_host_config_transports.h.

H_SPI_HD_CONFIG_1_DATA_LINE

#define H_SPI_HD_CONFIG_1_DATA_LINE   (1)

Selector passed to the port when one data line is negotiated.

One, so the selector value and the line count are the same number and a mismatch is visible by inspection.

Note

Read-only build configuration.

Warning

Consumed by _h_spi_hd_set_data_lines; changing it changes a vtable argument, not just a constant.

Example:

g_h.funcs->_h_spi_hd_set_data_lines(H_SPI_HD_CONFIG_1_DATA_LINE);

Since

0.1.0

Definition at line 93 of file port_esp_hosted_host_config_transports.h.

Referenced by internal_spi_hd_set_data_lines().

H_SPI_HD_CONFIG_2_DATA_LINES

#define H_SPI_HD_CONFIG_2_DATA_LINES   (2)

Selector passed to the port when two data lines are negotiated.

Two; see H_SPI_HD_CONFIG_1_DATA_LINE for the numbering.

Note

Read-only build configuration.

Warning

Consumed by _h_spi_hd_set_data_lines.

Example:

g_h.funcs->_h_spi_hd_set_data_lines(H_SPI_HD_CONFIG_2_DATA_LINES);

Since

0.1.0

Definition at line 107 of file port_esp_hosted_host_config_transports.h.

Referenced by internal_spi_hd_set_data_lines().

H_SPI_HD_CONFIG_4_DATA_LINES

#define H_SPI_HD_CONFIG_4_DATA_LINES   (4)

Selector passed to the port when four data lines are negotiated.

Four; see H_SPI_HD_CONFIG_1_DATA_LINE for the numbering.

Note

Read-only build configuration.

Warning

Consumed by _h_spi_hd_set_data_lines.

Example:

g_h.funcs->_h_spi_hd_set_data_lines(H_SPI_HD_CONFIG_4_DATA_LINES);

Since

0.1.0

Definition at line 121 of file port_esp_hosted_host_config_transports.h.

Referenced by internal_spi_hd_set_data_lines().

H_SPI_HD_DATA_READY_ENABLED

#define H_SPI_HD_DATA_READY_ENABLED   (1)

Whether half-duplex uses a DATA_READY line rather than polling.

One. The DATA_READY net is already wired and already has the board's only Pmod1 ICU channel, so an interrupt is available and polling would be a needless waste of the transaction thread.

Note

Read-only build configuration.

Warning

With this at 0 the driver falls back to H_SPI_HD_POLL_INTERVAL_MS, which must then be non-zero.

Example:

#if H_SPI_HD_DATA_READY_ENABLED
attach_data_ready_interrupt();
#endif

Since

0.1.0

Definition at line 176 of file port_esp_hosted_host_config_transports.h.

H_SPI_HD_DR_INTR_EDGE

#define H_SPI_HD_DR_INTR_EDGE   (H_DR_INTR_EDGE)

Interrupt sense for the half-duplex DATA_READY input.

Derived from H_DR_INTR_EDGE, so one polarity fact governs both SPI transports and an inverted harness needs a single edit.

Note

Read-only build configuration.

Warning

Integer-encoded against ra8_icu_irqmd_t; see H_DR_INTR_EDGE.

Example:

uint32_t sense = H_SPI_HD_DR_INTR_EDGE;

Since

0.1.0

Definition at line 223 of file port_esp_hosted_host_config_transports.h.

H_SPI_HD_HOST_INTERFACE

#define H_SPI_HD_HOST_INTERFACE   (0)

Whether the host drives the half-duplex SPI interface.

Zero. transport_drv.c uses this to decide which half of the co-processor's capability word to report, and reporting half-duplex capabilities on a full-duplex link would be a lie in the boot log.

Note

Read-only build configuration.

Warning

Must agree with H_TRANSPORT_IN_USE; the two are separate switches upstream and nothing cross-checks them.

Example:

#if H_SPI_HD_HOST_INTERFACE
report_spi_hd_capabilities(cap);
#endif

Since

0.1.0

Definition at line 60 of file port_esp_hosted_host_config_transports.h.

H_SPI_HD_HOST_NUM_DATA_LINES

#define H_SPI_HD_HOST_NUM_DATA_LINES   (4)

Data lines the host would use in half-duplex mode.

Four. If half-duplex were ever wired on this board it would use the quad-capable Pmod position, and the negotiation in transport_drv.c falls back to two and then one line when the co-processor cannot manage four.

Note

Read-only build configuration.

Warning

Only meaningful when H_SPI_HD_HOST_INTERFACE is 1.

Example:

if (H_SPI_HD_HOST_NUM_DATA_LINES == 4) { negotiate_quad(); }

Since

0.1.0

Definition at line 77 of file port_esp_hosted_host_config_transports.h.

H_SPI_HD_PIN_DATA_READY

#define H_SPI_HD_PIN_DATA_READY   (H_GPIO_DATA_READY_Pin)

Pin index of the half-duplex DATA_READY input.

The same net the full-duplex link uses; see H_SPI_HD_PORT_DATA_READY.

Note

Read-only build configuration.

Warning

Carries the same -1 "not wired" convention as H_GPIO_DATA_READY_Pin.

Example:

int pin = H_SPI_HD_PIN_DATA_READY;

Since

0.1.0

Definition at line 208 of file port_esp_hosted_host_config_transports.h.

H_SPI_HD_POLL_INTERVAL_MS

#define H_SPI_HD_POLL_INTERVAL_MS   (10)

Fallback poll period when half-duplex has no DATA_READY line.

Ten milliseconds. The driver refuses to start when this is zero and DATA_READY is disabled, because that combination is a busy loop on the transaction thread.

Note

Read-only build configuration.

Warning

Dead code while H_SPI_HD_DATA_READY_ENABLED is 1, but it must still be non-zero for the driver's own guard to pass.

Example:

g_h.funcs->_h_msleep(H_SPI_HD_POLL_INTERVAL_MS);

Since

0.1.0

Definition at line 240 of file port_esp_hosted_host_config_transports.h.

H_SPI_HD_PORT_DATA_READY

#define H_SPI_HD_PORT_DATA_READY   (H_GPIO_DATA_READY_Port)

Opaque port handle of the half-duplex DATA_READY input.

The same net the full-duplex link uses, so the two transports cannot disagree about which wire carries readiness.

Note

Read-only build configuration.

Warning

Only read when H_SPI_HD_DATA_READY_ENABLED is 1.

Example:

g_h.funcs->_h_config_gpio_as_interrupt(H_SPI_HD_PORT_DATA_READY,
    H_SPI_HD_PIN_DATA_READY, H_SPI_HD_DR_INTR_EDGE, handler, NULL);

Since

0.1.0

Definition at line 192 of file port_esp_hosted_host_config_transports.h.

H_SPI_HD_RX_QUEUE_SIZE

#define H_SPI_HD_RX_QUEUE_SIZE   (H_TRANSPORT_QUEUE_SIZE)

Frames queued from the co-processor in half-duplex mode.

H_TRANSPORT_QUEUE_SIZE; see H_SPI_HD_TX_QUEUE_SIZE.

Note

Read-only build configuration.

Warning

Also sizes the data-ready semaphore, so it bounds how many readiness edges can be outstanding.

Example:

queue = g_h.funcs->_h_create_queue(H_SPI_HD_RX_QUEUE_SIZE, sizeof(h));

Since

0.1.0

Definition at line 271 of file port_esp_hosted_host_config_transports.h.

H_SPI_HD_TX_QUEUE_SIZE

#define H_SPI_HD_TX_QUEUE_SIZE   (H_TRANSPORT_QUEUE_SIZE)

Frames queued towards the co-processor in half-duplex mode.

H_TRANSPORT_QUEUE_SIZE, so every transport in this port sizes its queues and its pool from one number.

Note

Read-only build configuration.

Warning

The driver multiplies this by the priority-queue count when it sizes its semaphore; raising it costs memory in two places.

Example:

spi_hd_mempool_create(H_SPI_HD_TX_QUEUE_SIZE, H_SPI_HD_RX_QUEUE_SIZE);

Since

0.1.0

Definition at line 256 of file port_esp_hosted_host_config_transports.h.

H_TRANSPORT_RESTART_ON_FAILURE

#define H_TRANSPORT_RESTART_ON_FAILURE   (0)

Whether a transport failure restarts the whole host.

Zero. On this board the RA8 owns the display, the storage and the reader state; rebooting it because a radio co-processor stopped answering would turn a recoverable link fault into a lost reading position. The transport-failure event is raised either way, and the application decides.

Note

Read-only build configuration.

Warning

With this at 1 the SDIO driver calls _h_restart_host() from the receive path, which on this port is a system reset.

Example:

#if H_TRANSPORT_RESTART_ON_FAILURE
g_h.funcs->_h_restart_host();
#endif

Since

0.1.0

Definition at line 476 of file port_esp_hosted_host_config_transports.h.

H_UART_CHECKSUM

#define H_UART_CHECKSUM   (1)

Whether UART frames carry the esp-hosted checksum.

One. A UART has no framing beyond the start bit, so the header checksum is what tells a resynchronising receiver that it has found a real frame boundary rather than payload that happens to look like one.

Note

Read-only build configuration.

Warning

The vendored driver also has one #if on a misspelt HOSTED_UART_CHECKSUM, which is undefined upstream and stays undefined here; do not define it to paper over that.

Example:

#if H_UART_CHECKSUM
header->checksum = htole16(compute_checksum(buf, len));
#endif

Since

0.1.0

Definition at line 518 of file port_esp_hosted_host_config_transports.h.

H_UART_HOST_TRANSPORT

#define H_UART_HOST_TRANSPORT   (0)

Whether the host drives the UART transport.

Zero, for the same reason as H_SPI_HD_HOST_INTERFACE: it feeds the capability report in transport_drv.c, which must describe the link this image actually opens.

Note

Read-only build configuration.

Warning

Must agree with H_TRANSPORT_IN_USE.

Example:

#elif H_UART_HOST_TRANSPORT
report_uart_capabilities(cap);
#endif

Since

0.1.0

Definition at line 498 of file port_esp_hosted_host_config_transports.h.

H_UART_RX_QUEUE_SIZE

#define H_UART_RX_QUEUE_SIZE   (H_TRANSPORT_QUEUE_SIZE)

Frames queued from the co-processor over UART.

H_TRANSPORT_QUEUE_SIZE; see H_UART_TX_QUEUE_SIZE.

Note

Read-only build configuration.

Warning

Also multiplies into the receive semaphore count.

Example:

queue = g_h.funcs->_h_create_queue(H_UART_RX_QUEUE_SIZE, sizeof(h));

Since

0.1.0

Definition at line 547 of file port_esp_hosted_host_config_transports.h.

H_UART_TX_QUEUE_SIZE

#define H_UART_TX_QUEUE_SIZE   (H_TRANSPORT_QUEUE_SIZE)

Frames queued towards the co-processor over UART.

H_TRANSPORT_QUEUE_SIZE, keeping every transport's queue depth derived from one number.

Note

Read-only build configuration.

Warning

Also multiplies into the transmit semaphore count.

Example:

h_uart_mempool_create(H_UART_TX_QUEUE_SIZE, H_UART_RX_QUEUE_SIZE);

Since

0.1.0

Definition at line 533 of file port_esp_hosted_host_config_transports.h.