ra8_esp_hosted_log_internal.h File Reference

Library-private surface of the esp-hosted logging bridge. More...

#include <stdarg.h>
#include <stdint.h>
#include "ra8_attributes.h"

Include dependency graph for ra8_esp_hosted_log_internal.h:

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

Go to the source code of this file.

Enumerations
enum	ra8_esp_hosted_log_dump_t : uint8_t {   k_ra8_esp_hosted_log_dump_radix = 16U ,   k_ra8_esp_hosted_log_dump_nibbles = 2U }
	Constants the hexdump renderer works from. More...

Functions
void	priv_ra8_esp_hosted_log_vwrite (int level, const char *tag, const char *fmt, va_list ap)
	Emit one formatted line from an already-started argument list.
bool	priv_ra8_esp_hosted_log_accepts (int level)
	Decide whether a line at this level reaches the sink.
int	priv_ra8_esp_hosted_log_level_get (void)
	Report the current runtime verbosity threshold.

Detailed Description

Library-private surface of the esp-hosted logging bridge.

Tag

[Ring 4 / PORT] {World: NS}

The bridge's public face is port/esp-hosted/inc/idf_compat/esp_log.h, which the vendored core includes by name. This header carries the two pieces that are not part of that face: the runtime level decision, which is promoted out of static so its conditions can be driven directly by a host test, and the threshold reader that lets a test observe what esp_log_level_set did without reaching into the module.

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

Enumeration Type Documentation

ra8_esp_hosted_log_dump_t

enum ra8_esp_hosted_log_dump_t : uint8_t

Constants the hexdump renderer works from.

Named here rather than left as literals so the dump width and the zero-padding rule are stated once and are visible to the test that checks them.

Invariant

k_ra8_esp_hosted_log_dump_nibbles is the number of hexadecimal digits one byte occupies, so a shorter render is left-padded with a zero.

Example:

const uint8_t base = (uint8_t)k_ra8_esp_hosted_log_dump_radix;

See also

ra8_esp_hosted_log_hexdump

Since

0.1.0

Enumerator
k_ra8_esp_hosted_log_dump_radix	Hexadecimal.
k_ra8_esp_hosted_log_dump_nibbles	Digits one byte renders as.

Definition at line 94 of file ra8_esp_hosted_log_internal.h.

Function Documentation

priv_ra8_esp_hosted_log_accepts()

bool priv_ra8_esp_hosted_log_accepts ( int level )

nodiscard

Decide whether a line at this level reaches the sink.

Applies the runtime threshold that esp_log_level_set maintains. The compile-time LOG_LOCAL_LEVEL filter has already run at the call site; this is the second, adjustable gate.

Parameters

[in]

level

ESP-IDF level of the candidate line. Any integer is accepted, including values outside the enumeration.

Returns

Whether the line should be emitted.

Return values

true	The level is a real level and is at or above the threshold.
false	The level is the suppress-everything value, is below the threshold, or is outside the enumeration.

Precondition

None; the function is total over the integers.

The threshold has been left at its default or set by the setter.

Postcondition

No state is modified.

The answer depends only on level and the current threshold.

Note

Reentrant; a single read of one integer.

MC/DC:

Promoted from static so both conditions of (level > ESP_LOG_NONE) && (level <= threshold) can be varied independently. Production callers are the write and hexdump entry points; nothing outside tests/ may call it.

Example:

if (priv_ra8_esp_hosted_log_accepts((int)ESP_LOG_WARN)) { emit(); }

See also

priv_ra8_esp_hosted_log_level_get

Since

0.1.0

Decide whether a line at this level reaches the sink.

Definition at line 144 of file ra8_esp_hosted_log.c.

References ESP_LOG_NONE, and s_ra8_esp_hosted_log_level.

Referenced by priv_ra8_esp_hosted_log_vwrite(), and ra8_esp_hosted_log_hexdump().

priv_ra8_esp_hosted_log_level_get()

int priv_ra8_esp_hosted_log_level_get ( void )

nodiscard

Report the current runtime verbosity threshold.

Exists so a test can assert what esp_log_level_set stored, including the clamping it applies, without declaring the module's static.

Returns

The threshold, as an esp_log_level_t value widened to int.

Return values

0	Every line is suppressed.

Precondition

None; safe before any logging call.

The caller tolerates a value a concurrent setter may stale.

Postcondition

No state is modified.

The result is within the esp_log_level_t range.

Note

Reentrant; a single read of one integer.

MC/DC:

Branch-free observer; carries no decision of its own. Tests only.

Example:

esp_log_level_set(nullptr, ESP_LOG_DEBUG);
TEST_ASSERT_EQ((int)ESP_LOG_DEBUG, priv_ra8_esp_hosted_log_level_get());

See also

priv_ra8_esp_hosted_log_accepts

Since

0.1.0

Report the current runtime verbosity threshold.

Definition at line 233 of file ra8_esp_hosted_log.c.

References s_ra8_esp_hosted_log_level.

priv_ra8_esp_hosted_log_vwrite()

void priv_ra8_esp_hosted_log_vwrite	(	int	level,
		const char *	tag,
		const char *	fmt,
		va_list	ap )

Emit one formatted line from an already-started argument list.

The body of the logging bridge. ra8_esp_hosted_log_write is a thin varargs face over it, and the vtable's log row is another, so a line emitted through either path is formatted and filtered identically.

Parameters

[in]	level	ESP-IDF level of the line.
[in]	tag	Tag to attribute the line to; null is replaced with the port's own tag rather than dereferenced.
[in]	fmt	Format string; null suppresses the line.
[in]	ap	Argument list positioned at the first conversion argument. The caller owns starting and ending it.

Returns

Nothing.

Precondition

The caller has started ap and will end it.

The variable arguments match the conversions in fmt.

Postcondition

At most one line reaches the sink.

No module state is modified.

Note

Reentrant; formats onto a bounded stack line and holds no lock, so it is safe from interrupt context as far as this module is concerned.

MC/DC:

Shares the level and null-format decision with priv_ra8_esp_hosted_log_accepts, which the tests drive directly.

Example:

va_start(ap, format);
priv_ra8_esp_hosted_log_vwrite(level, tag, format, ap);
va_end(ap);

See also

priv_ra8_esp_hosted_log_accepts

Since

0.1.0

Emit one formatted line from an already-started argument list.

Definition at line 152 of file ra8_esp_hosted_log.c.

References internal_emit(), k_ra8_esp_hosted_log_line_max, priv_ra8_esp_hosted_fmt_vformat(), priv_ra8_esp_hosted_log_accepts(), and s_ra8_esp_hosted_log_tag.

Referenced by internal_printf(), and ra8_esp_hosted_log_write().