ra8_esp_hosted_log.c File Reference

Bridge from the esp-hosted logging surface onto ra8_log. More...

#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>
#include "esp_log.h"
#include "ra8_attributes.h"
#include "ra8_esp_hosted_fmt_internal.h"
#include "ra8_esp_hosted_log_internal.h"
#include "ra8_esp_hosted_port.h"
#include "ra8_esp_hosted_rtos_internal.h"
#include "ra8_log.h"

Include dependency graph for ra8_esp_hosted_log.c:

Go to the source code of this file.

Enumerations
enum	ra8_esp_hosted_log_bound_t : uint16_t {   k_ra8_esp_hosted_log_line_max = 160U ,   k_ra8_esp_hosted_log_dump_bytes = 32U ,   k_ra8_esp_hosted_log_dump_cost = 3U }
	Fixed sizes the log bridge works within. More...

Functions
static void	internal_emit (int level, const char *tag, const char *line)
	Hand a finished line to the project logger at the mapped level.
bool	priv_ra8_esp_hosted_log_accepts (int level)
	Implementation of priv_ra8_esp_hosted_log_accepts() – the single runtime level decision, promoted so its two conditions are testable.
void	priv_ra8_esp_hosted_log_vwrite (int level, const char *tag, const char *fmt, va_list ap)
	Implementation of priv_ra8_esp_hosted_log_vwrite() – formats onto a bounded stack line, so it allocates nothing and is reentrant.
void	ra8_esp_hosted_log_write (int level, const char *tag, const char *fmt,...)
	Implementation of ra8_esp_hosted_log_write() – the varargs face of priv_ra8_esp_hosted_log_vwrite().
void	ra8_esp_hosted_log_hexdump (int level, const char *tag, const void *buf, uint32_t len)
	Implementation of ra8_esp_hosted_log_hexdump() – renders at most k_ra8_esp_hosted_log_dump_bytes bytes onto one bounded line.
void	ra8_esp_hosted_log_level_set (const char *tag, int level)
	Implementation of ra8_esp_hosted_log_level_set() – one global threshold rather than the per-tag table ESP-IDF keeps; see the file header for why.
int	priv_ra8_esp_hosted_log_level_get (void)
	Implementation of priv_ra8_esp_hosted_log_level_get() – reads the threshold the setter last clamped.
void	ra8_esp_hosted_log_fatal (const char *tag, const char *expr, int code)
	Implementation of ra8_esp_hosted_log_fatal() – reports and parks; the caller's check already proved the state is unrecoverable.
void	ra8_esp_hosted_mem_dump (const char *label)
	Implementation of ra8_esp_hosted_mem_dump() – reads the live ThreadX byte-pool statistics, so the numbers are real.
void	ra8_esp_hosted_alloc_failed (const char *func, size_t bytes)
	Implementation of ra8_esp_hosted_alloc_failed() – names the requester and the size, which together size the pool without guesswork.

Variables
static int	s_ra8_esp_hosted_log_level = (int)ESP_LOG_INFO
	Runtime verbosity threshold for the esp-hosted bridge.
static const char *const	s_ra8_esp_hosted_log_tag = "C6LINK"
	Fallback tag used when a caller passes none.

Detailed Description

Bridge from the esp-hosted logging surface onto ra8_log.

Tag

[Ring 4 / PORT] {World: NS}

Implements the four entry points declared in port/esp-hosted/inc/idf_compat/esp_log.h plus the two allocator reporting hooks declared in ra8_esp_hosted_port.h.

The vendored core logs with printf-style calls; this project's logger takes a plain message and, optionally, one integer. The bridge closes that gap by formatting into a stack line through priv_ra8_esp_hosted_fmt_vformat – a bounded, allocation-free formatter – and handing the finished string to the matching ra8_log_* macro. Nothing here allocates, and the only module state is the runtime level threshold, which is read but never written on a logging path.

Level filtering happens twice, deliberately

LOG_LOCAL_LEVEL folds out call sites at compile time, and the runtime threshold below rejects what survives. The compile-time filter keeps unreachable formatting out of the image; the runtime one lets an application raise verbosity during bring-up without a rebuild. esp_log_level_set is per-tag in ESP-IDF; here it sets one global threshold, which is stated in its contract rather than pretended otherwise – a per-tag table would need dynamic registration this image has no allocator for.

Copyright

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

Since

0.1.0

Definition in file ra8_esp_hosted_log.c.

Enumeration Type Documentation

ra8_esp_hosted_log_bound_t

enum ra8_esp_hosted_log_bound_t : uint16_t

Fixed sizes the log bridge works within.

One stack line and one hexdump line, both bounded so a format string or a co-processor-supplied buffer cannot decide how much stack the logger uses. The line budget is the dominant term in this module's stack frame, which the project's -Wstack-usage build measures.

Invariant

k_ra8_esp_hosted_log_line_max leaves room for the longest format the vendored core uses at its widest arguments.

k_ra8_esp_hosted_log_dump_bytes multiplied by three, plus a terminator, fits inside the line budget.

Example:

char line[k_ra8_esp_hosted_log_line_max] = {};

See also

ra8_esp_hosted_log_write

Since

0.1.0

Enumerator
k_ra8_esp_hosted_log_line_max	Bytes of stack the formatted line may occupy, terminator included.
k_ra8_esp_hosted_log_dump_bytes	Bytes of a buffer a single hexdump line renders.
k_ra8_esp_hosted_log_dump_cost	Characters one dumped byte costs: two nibbles and a separator.

Definition at line 71 of file ra8_esp_hosted_log.c.

Function Documentation

internal_emit()

void internal_emit ( int level, const char * tag, const char * line )

static

Hand a finished line to the project logger at the mapped level.

ESP-IDF has five levels and ra8_log has four, so verbose folds into debug. That is the only lossy step and it is stated here rather than spread across the call sites.

Parameters

[in]	level	ESP-IDF level of the line.
[in]	tag	Tag to attribute the line to. Must be non-null.
[in]	line	Formatted text. Must be non-null.

Returns

Nothing.

Precondition

tag and line are non-null.

The runtime threshold has already accepted this level.

Postcondition

Exactly one line is handed to the project logger.

No module state is modified.

Note

Reentrant with respect to this module; the sink beneath decides its own concurrency rules.

Since

0.1.0

Definition at line 128 of file ra8_esp_hosted_log.c.

References ESP_LOG_ERROR, ESP_LOG_INFO, ESP_LOG_WARN, ra8_log_debug, ra8_log_error, ra8_log_info, and ra8_log_warn.

Referenced by priv_ra8_esp_hosted_log_vwrite(), and ra8_esp_hosted_log_hexdump().

priv_ra8_esp_hosted_log_accepts()

bool priv_ra8_esp_hosted_log_accepts ( int level )

nodiscard

Implementation of priv_ra8_esp_hosted_log_accepts() – the single runtime level decision, promoted so its two conditions are testable.

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

Implementation of priv_ra8_esp_hosted_log_level_get() – reads the threshold the setter last clamped.

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 )

Implementation of priv_ra8_esp_hosted_log_vwrite() – formats onto a bounded stack line, so it allocates nothing and is reentrant.

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

ra8_esp_hosted_alloc_failed()

void ra8_esp_hosted_alloc_failed	(	const char *	func,
		size_t	bytes )

Implementation of ra8_esp_hosted_alloc_failed() – names the requester and the size, which together size the pool without guesswork.

Record that an allocation through the vtable could not be served.

Definition at line 275 of file ra8_esp_hosted_log.c.

References ESP_LOG_ERROR, ra8_esp_hosted_log_write(), and s_ra8_esp_hosted_log_tag.

ra8_esp_hosted_log_fatal()

void ra8_esp_hosted_log_fatal	(	const char *	tag,
		const char *	expr,
		int	code )

Implementation of ra8_esp_hosted_log_fatal() – reports and parks; the caller's check already proved the state is unrecoverable.

Report a failed ESP_ERROR_CHECK and stop.

Definition at line 240 of file ra8_esp_hosted_log.c.

References ESP_LOG_ERROR, ra8_esp_hosted_log_write(), and s_ra8_esp_hosted_log_tag.

ra8_esp_hosted_log_hexdump()

void ra8_esp_hosted_log_hexdump	(	int	level,
		const char *	tag,
		const void *	buf,
		uint32_t	len )

Implementation of ra8_esp_hosted_log_hexdump() – renders at most k_ra8_esp_hosted_log_dump_bytes bytes onto one bounded line.

Emit a hex dump of a buffer at a given severity.

Definition at line 175 of file ra8_esp_hosted_log.c.

References internal_emit(), k_ra8_esp_hosted_fmt_digits_max, k_ra8_esp_hosted_log_dump_bytes, k_ra8_esp_hosted_log_dump_cost, k_ra8_esp_hosted_log_dump_nibbles, k_ra8_esp_hosted_log_dump_radix, k_ra8_esp_hosted_log_line_max, priv_ra8_esp_hosted_fmt_utoa(), priv_ra8_esp_hosted_log_accepts(), and s_ra8_esp_hosted_log_tag.

ra8_esp_hosted_log_level_set()

void ra8_esp_hosted_log_level_set	(	const char *	tag,
		int	level )

Implementation of ra8_esp_hosted_log_level_set() – one global threshold rather than the per-tag table ESP-IDF keeps; see the file header for why.

Raise the console threshold for one module at run time.

Definition at line 217 of file ra8_esp_hosted_log.c.

References ESP_LOG_NONE, ESP_LOG_VERBOSE, and s_ra8_esp_hosted_log_level.

ra8_esp_hosted_log_write()

void ra8_esp_hosted_log_write	(	int	level,
		const char *	tag,
		const char *	fmt,
			... )

Implementation of ra8_esp_hosted_log_write() – the varargs face of priv_ra8_esp_hosted_log_vwrite().

Emit one formatted esp-hosted log line.

Definition at line 165 of file ra8_esp_hosted_log.c.

References priv_ra8_esp_hosted_log_vwrite().

Referenced by ra8_esp_hosted_alloc_failed(), ra8_esp_hosted_log_fatal(), and ra8_esp_hosted_mem_dump().

ra8_esp_hosted_mem_dump()

void ra8_esp_hosted_mem_dump

(

const char *

label

)

Implementation of ra8_esp_hosted_mem_dump() – reads the live ThreadX byte-pool statistics, so the numbers are real.

Report transport pool occupancy at a named point.

Definition at line 260 of file ra8_esp_hosted_log.c.

References ESP_LOG_INFO, priv_ra8_esp_hosted_rtos_pool_stats(), ra8_esp_hosted_log_write(), and s_ra8_esp_hosted_log_tag.

Referenced by c6_fwver_worker_entry(), c6_hosted_worker_entry(), c6_wifi_worker_entry(), and internal_init_hook().

Variable Documentation

s_ra8_esp_hosted_log_level

int s_ra8_esp_hosted_log_level = (int)ESP_LOG_INFO

static

Runtime verbosity threshold for the esp-hosted bridge.

Lines at a level numerically greater than this are dropped. Starts at the informational level so a default build reports link life-cycle events without per-frame noise.

Note

Read on every logging call; written only by ra8_esp_hosted_log_level_set.

Warning

Do not modify directly; the setter clamps the value.

Since

0.1.0

Definition at line 91 of file ra8_esp_hosted_log.c.

Referenced by priv_ra8_esp_hosted_log_accepts(), priv_ra8_esp_hosted_log_level_get(), and ra8_esp_hosted_log_level_set().

s_ra8_esp_hosted_log_tag

const char* const s_ra8_esp_hosted_log_tag = "C6LINK"

static

Fallback tag used when a caller passes none.

Keeps a null tag from reaching ra8_log_*, which would dereference it.

Note

Read-only.

Warning

Never freed; it is a string literal.

Since

0.1.0

Definition at line 102 of file ra8_esp_hosted_log.c.

Referenced by priv_ra8_esp_hosted_log_vwrite(), ra8_esp_hosted_alloc_failed(), ra8_esp_hosted_log_fatal(), ra8_esp_hosted_log_hexdump(), and ra8_esp_hosted_mem_dump().