Abstract logging whose disabled levels cost nothing at all (PROTOCORE_LOG_LEVEL). More...

#include "protocore_config.h"

Classes
struct	LogFrameArgs
	One line to emit: its level, and the spec that shapes it. More...

struct	LogVars

struct	LogNs
	The entries. More...

Macros
#define	PROTOCORE_LOG_DISCARD(spec, v, nv)
	The discarded form: marks arguments used, emits nothing.

#define	PROTOCORE_LOG_EMIT(lvl, spec_, v_, nv_)
	Set the frame members and emit, as one statement.

#define	PROTOCORE_LOGD(spec, v, nv) PROTOCORE_LOG_EMIT(PROTOCORE_LOG_LEVEL_DEBUG, (spec), (v), (nv))

#define	PROTOCORE_LOGI(spec, v, nv) PROTOCORE_LOG_EMIT(PROTOCORE_LOG_LEVEL_INFO, (spec), (v), (nv))

#define	PROTOCORE_LOGW(spec, v, nv) PROTOCORE_LOG_EMIT(PROTOCORE_LOG_LEVEL_WARN, (spec), (v), (nv))

#define	PROTOCORE_LOGE(spec, v, nv) PROTOCORE_LOG_EMIT(PROTOCORE_LOG_LEVEL_ERROR, (spec), (v), (nv))

Typedefs
typedef void(*	protocore_log_sink_fn) (uint8_t level, const char *line)
	Receives an emitted line, already formatted. `level` is a PROTOCORE_LOG_LEVEL_* value.

Functions
int	protocore_log_discard_args (const struct protocore_field spec, const struct protocore_fval v, size_t nv)
	Declared, never defined: only ever named inside `sizeof`, so no call is ever generated.

void	protocore_log_emit (uint8_t *work)

void	protocore_log_set_sink (uint8_t *work)

uint8_t *	protocore_log_span (void)
	The PROTOCORE_LOG_BORROW bytes this module's state lives in.

Variables
LogVars	LogV
	The operands and the outcome.

Detailed Description

Abstract logging whose disabled levels cost nothing at all (PROTOCORE_LOG_LEVEL).

Instrumentation is only worth leaving in the source permanently if a build that does not want it pays nothing for it - not a branch, not a call, and not a format string sitting in flash. A runtime if (level >= threshold) fails that last part: every message is still linked in, and on a device flash is the scarce resource.

So the filter is the preprocessor. A call below PROTOCORE_LOG_LEVEL expands to a form that names its arguments only inside sizeof(...) - an unevaluated context - which emits no code and no string literal, yet still runs the compiler's printf format checking over them and marks the arguments used (so a variable read only by a log does not warn). Enable the level and the same line starts logging, with no source change.

Where an emitted line goes is the caller's choice: it is handed to server/logbuf's ring when PROTOCORE_ENABLE_LOGBUF is on, and to a sink callback registered with LogNs::set_sink (a serial port, syslog, a websocket console) if there is one.

Author: Douglas Quigg (dstroy0)

Date: 2026

Definition in file log.h.

Macro Definition Documentation

◆ PROTOCORE_LOG_DISCARD

#define PROTOCORE_LOG_DISCARD	(	spec,
		v,
		nv
	)

Value:

    do                                                                                                                 \
    {                                                                                                                  \
        (void)sizeof(protocore_log_discard_args((spec), (v), (nv)));                                                   \
    } while (0)

The discarded form: marks arguments used, emits nothing.

Definition at line 51 of file log.h.

◆ PROTOCORE_LOG_EMIT

#define PROTOCORE_LOG_EMIT	(	lvl,
		spec_,
		v_,
		nv_
	)

Value:

    do                                                                                                                 \
    {                                                                                                                  \
        LogV.frame.level = (lvl);                                                                                      \
        LogV.frame.spec = (spec_);                                                                                     \
        LogV.frame.v = (v_);                                                                                           \
        LogV.frame.nv = (nv_);                                                                                         \
        Log.emit(protocore_log_span());                                                                                \
    } while (0)

Set the frame members and emit, as one statement.

Definition at line 124 of file log.h.

◆ PROTOCORE_LOGD

#define PROTOCORE_LOGD	(	spec,
		v,
		nv
	)	PROTOCORE_LOG_EMIT(PROTOCORE_LOG_LEVEL_DEBUG, (spec), (v), (nv))

Definition at line 135 of file log.h.

◆ PROTOCORE_LOGI

#define PROTOCORE_LOGI	(	spec,
		v,
		nv
	)	PROTOCORE_LOG_EMIT(PROTOCORE_LOG_LEVEL_INFO, (spec), (v), (nv))

Definition at line 141 of file log.h.

◆ PROTOCORE_LOGW

#define PROTOCORE_LOGW	(	spec,
		v,
		nv
	)	PROTOCORE_LOG_EMIT(PROTOCORE_LOG_LEVEL_WARN, (spec), (v), (nv))

Definition at line 147 of file log.h.

◆ PROTOCORE_LOGE

#define PROTOCORE_LOGE	(	spec,
		v,
		nv
	)	PROTOCORE_LOG_EMIT(PROTOCORE_LOG_LEVEL_ERROR, (spec), (v), (nv))

Definition at line 153 of file log.h.

Typedef Documentation

◆ protocore_log_sink_fn

typedef void(* protocore_log_sink_fn) (uint8_t level, const char *line)

Receives an emitted line, already formatted. level is a PROTOCORE_LOG_LEVEL_* value.

Definition at line 40 of file log.h.

Function Documentation

◆ protocore_log_discard_args()

int protocore_log_discard_args	(	const struct protocore_field *	spec,
		const struct protocore_fval *	v,
		size_t	nv
	)

Declared, never defined: only ever named inside sizeof, so no call is ever generated.

It exists to mark a discarded statement's arguments as used, so a variable read only by a log does not warn its way into being deleted.

◆ protocore_log_emit()

void protocore_log_emit ( uint8_t * work )

◆ protocore_log_set_sink()

void protocore_log_set_sink ( uint8_t * work )

◆ protocore_log_span()

uint8_t * protocore_log_span ( void )

The PROTOCORE_LOG_BORROW bytes this module's state lives in.

Stated beside the namespace rather than on it: an entry takes a borrow, and this is where that borrow comes from. Taken once from the end of the pool, which no mark and no release walks, so the state lasts the life of the program.

Returns: the span.

Variable Documentation

◆ LogV

LogVars LogV

extern

The operands and the outcome.

Classes

Macros

Typedefs

Functions

Variables