ra8_esp_hosted_port_internal.h File Reference

Library-private surface of the esp-hosted port bring-up. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_esp_hosted_port.h"

Include dependency graph for ra8_esp_hosted_port_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_port_cfg_check (const ra8_esp_hosted_port_cfg_t *cfg)
	Check a port configuration against its documented contract.
ra8_err_t	priv_ra8_esp_hosted_port_pins_check (void)
	Check the compiled-in pin map for self-consistency.
ra8_err_t	priv_ra8_esp_hosted_port_pins_check_values (uint16_t chip_select, uint16_t handshake, uint16_t data_ready)
	Check three candidate pin assignments for self-consistency.
ra8_err_t	priv_ra8_esp_hosted_port_first_error (ra8_err_t first, ra8_err_t next)
	Keep the first error of a teardown sequence, discarding later ones.

Detailed Description

Library-private surface of the esp-hosted port bring-up.

Tag

[Ring 4 / PORT] {World: NS}

ra8_esp_hosted_port.c sequences the slices – RTOS pools, the vtable, the SPI channel, the side-band pins – and unwinds them in the opposite order. The two decisions that are worth testing on their own, configuration validation and pin-map validation, are promoted out of static here so a host test can drive every rejection path without a board.

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_port_internal.h.

Function Documentation

priv_ra8_esp_hosted_port_cfg_check()

ra8_err_t priv_ra8_esp_hosted_port_cfg_check ( const ra8_esp_hosted_port_cfg_t * cfg )

nodiscard

Check a port configuration against its documented contract.

Every field has a reason it cannot be zero: a zero peripheral clock makes the bit-rate divider undefined, a zero bit rate asks the SCI for a rate it cannot produce, a zero poll period arms a ThreadX timer with a zero tick count – which ThreadX rejects – and an out-of-range SCI channel indexes past the peripheral. Rejecting them here, before any hardware is touched, is what lets initialisation fail without having claimed a pin.

Parameters

[in]

cfg

Configuration to validate. May be null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Every field is within contract.
k_ra8_err_null_ptr	cfg was null.
k_ra8_err_invalid_arg	A field was zero or out of range.

Precondition

None; the function is total over its input.

The caller has not yet touched any hardware.

Postcondition

No state is modified.

The answer depends only on cfg.

Note

Reentrant; a pure predicate.

MC/DC:

Promoted from static so each field's rejection can be driven independently – the decision is a four-condition disjunction, so it takes five vectors to prove each field influences the outcome on its own. Production callers reach it through ra8_esp_hosted_port_init.

Example:

ra8_esp_hosted_port_cfg_t cfg = { .pclk_hz = 0U };
TEST_ASSERT_EQ(k_ra8_err_invalid_arg, priv_ra8_esp_hosted_port_cfg_check(&cfg));

See also

ra8_esp_hosted_port_init

Since

0.1.0

Check a port configuration against its documented contract.

Definition at line 95 of file ra8_esp_hosted_port.c.

References ra8_esp_hosted_port_cfg::edge_poll_ms, k_ra8_err_invalid_arg, k_ra8_esp_hosted_port_sci_channels, k_ra8_ok, ra8_esp_hosted_port_cfg::pclk_hz, RA8_CHECK_NULL_PTR, s_esp_hosted_tag, ra8_esp_hosted_port_cfg::sci_channel, and ra8_esp_hosted_port_cfg::sck_hz.

Referenced by ra8_esp_hosted_port_init().

priv_ra8_esp_hosted_port_first_error()

ra8_err_t priv_ra8_esp_hosted_port_first_error ( ra8_err_t first, ra8_err_t next )

nodiscard

Keep the first error of a teardown sequence, discarding later ones.

The unwind path runs every release step regardless of what the previous one reported, because a teardown that stops at the first error strands exactly the resource it was meant to release. It therefore needs the "first error wins" fold in one place: given what has been reported so far and what the next step reported, the earlier failure survives and a clean step never overwrites a failure.

Parameters

[in]	first	What the sequence has reported so far.
[in]	next	What the step just run reported.

Returns

ra8_err_t The error the sequence should carry onwards.

Return values

k_ra8_ok	Both arguments were k_ra8_ok.
first	first was already an error, whatever next was.
next	first was k_ra8_ok and next was not.

Precondition

Both arguments are ra8_err_t values from release steps.

The step producing next has already run; this fold never decides whether a step runs.

Postcondition

No state is modified.

The answer depends only on the two arguments.

Note

Reentrant; a pure fold.

MC/DC:

Promoted from static because the fold is the only compound decision on the unwind path and the unwind path itself needs a brought-up port – a board – to reach. As a pure two-argument function it takes the minimal three vectors: (ok, ok), (error, ok) and (ok, error).

Example:

ra8_err_t first = priv_ra8_esp_hosted_port_first_error(k_ra8_ok, close_err);
first           = priv_ra8_esp_hosted_port_first_error(first, deinit_err);

See also

ra8_esp_hosted_port_deinit

Since

0.1.0

Keep the first error of a teardown sequence, discarding later ones.

Definition at line 258 of file ra8_esp_hosted_port.c.

References k_ra8_ok.

Referenced by internal_unwind().

priv_ra8_esp_hosted_port_pins_check()

ra8_err_t priv_ra8_esp_hosted_port_pins_check ( void )

nodiscard

Check the compiled-in pin map for self-consistency.

The pin map in ra8_esp_hosted_pins.h is the one file the owner edits when the harness changes, so it is exactly where a copy-and-paste mistake would land. Two properties are worth proving before anything claims a pin: the chip select and the two side-band nets must be three distinct pins, and each must decode to a legal port and pin index. A duplicated assignment would otherwise show up as an unexplained pin-claim conflict deep in bring-up.

The reset pin is deliberately exempt from the distinctness check: it is legitimately k_ra8_pin_none, the harness having no reset wire.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The map is self-consistent.
k_ra8_err_invalid_arg	Two signals share a pin, or a pin decodes to an out-of-range port or pin index.

Precondition

The pin map header describes this board.

No pin has been claimed yet.

Postcondition

No state is modified.

The answer depends only on compile-time constants.

Note

Reentrant; a pure predicate over compile-time values.

MC/DC:

Promoted from static so a test can assert the property holds for the shipped map. The decision's conditions are compile-time constants, so the shipped configuration exercises one vector; the remaining vectors are driven through priv_ra8_esp_hosted_port_pins_check_values.

Example:

TEST_ASSERT_EQ(k_ra8_ok, priv_ra8_esp_hosted_port_pins_check());

See also

priv_ra8_esp_hosted_port_pins_check_values

Since

0.1.0

Check the compiled-in pin map for self-consistency.

Definition at line 170 of file ra8_esp_hosted_port.c.

References k_ra8_esp_hosted_pin_chip_select, k_ra8_esp_hosted_pin_data_ready, k_ra8_esp_hosted_pin_handshake, and priv_ra8_esp_hosted_port_pins_check_values().

Referenced by ra8_esp_hosted_port_init().

priv_ra8_esp_hosted_port_pins_check_values()

ra8_err_t priv_ra8_esp_hosted_port_pins_check_values ( uint16_t chip_select, uint16_t handshake, uint16_t data_ready )

nodiscard

Check three candidate pin assignments for self-consistency.

The body of priv_ra8_esp_hosted_port_pins_check, taking its inputs as parameters so every rejection path can be reached. The shipped map is a set of compile-time constants and therefore exercises exactly one path; without this seam the other paths would be unreachable from a test, which is the same as being unverified.

Parameters

[in]	chip_select	Packed chip-select pin code.
[in]	handshake	Packed HANDSHAKE pin code.
[in]	data_ready	Packed DATA_READY pin code.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The three are distinct and each decodes legally.
k_ra8_err_invalid_arg	Two share a pin, or one decodes to an out-of-range port or pin index.

Precondition

The values are packed RA8_PIN(port, pin) codes.

The caller treats k_ra8_pin_none as an illegal assignment for all three of these signals, since the link cannot work without any of them.

Postcondition

No state is modified.

The answer depends only on the three arguments.

Note

Reentrant; a pure predicate.

MC/DC:

Promoted from static so the three distinctness comparisons and the range checks can each be varied independently. Five vectors cover the distinctness disjunction; the range checks add one vector per signal.

Example:

TEST_ASSERT_EQ(k_ra8_err_invalid_arg,
               priv_ra8_esp_hosted_port_pins_check_values(0x0804U, 0x0804U, 0x0006U));

See also

priv_ra8_esp_hosted_port_pins_check

Since

0.1.0

Check three candidate pin assignments for self-consistency.

Definition at line 148 of file ra8_esp_hosted_port.c.

References internal_pin_in_range(), k_ra8_err_invalid_arg, and k_ra8_ok.

Referenced by priv_ra8_esp_hosted_port_pins_check().