Logging

Leveled logging to the serial console (or PULSE) and to flash. More...

Modules
	Binary logging
	Wire format of binary log messages.
	Log hashing
	Compile-time replacement of log strings by tokens (CONFIG_LOG_HASHED).

Macros
#define	SPLIT_64_BIT_ARG(x)   (uint32_t)((x >> 32) & 0xFFFFFFFF), (uint32_t)(x & 0xFFFFFFFF)
	Expand a 64-bit value into two 32-bit arguments, high word first.
#define	LOG_BUFFER_LENGTH   128
	Size of the buffer a log message is formatted into, header included.
#define	LOGGING_MIN_STACK_FOR_SPRINTF   240
	Minimum free stack, in bytes, to format a message; below it the message is replaced.
#define	LOGGING_STACK_FULL_MSG   ((const char *)" [STK FULL]")
	Message logged instead when the stack is too full to format it.
#define	LOG_LEVEL_ALWAYS   0
	Level of messages that are never filtered.
#define	LOG_LEVEL_ERROR   1
	Error level.
#define	LOG_LEVEL_WARNING   50
	Warning level.
#define	LOG_LEVEL_INFO   100
	Info level.
#define	LOG_LEVEL_DEBUG   200
	Debug level.
#define	LOG_LEVEL_DEBUG_VERBOSE   255
	Verbose debug level.
#define	LOG_LEVEL_OFF   (-1)
	Module level that disables every message of the module.
#define	DEFAULT_LOG_LEVEL   LOG_LEVEL_DEBUG
	Compile-time level of files without a log module, from CONFIG_DEFAULT_LOG_LEVEL.
#define	FLASH_LOG_LEVEL   LOG_LEVEL_INFO
	Highest level written to the flash log, from the CONFIG_FLASH_LOG_LEVEL_ choice.
#define	STRINGIFY_NX(a)   #a
	Turn the argument into a string literal without expanding it.
#define	STRINGIFY(a)   STRINGIFY_NX(a)
	Turn the expansion of the argument into a string literal.
#define	STATUS_STRING(s)   STRINGIFY(s)
	Turn the expansion of a status code into a string literal.
#define	PBL_LOG_MODULE_DEFINE(name, level)   PBL_UNUSED static const int16_t _pbl_log_module_level = 0
	Put the current file in a log module, defining the module.
#define	PBL_LOG_MODULE_DECLARE(name, level)   PBL_LOG_MODULE_DEFINE(name, level)
	Put the current file in a log module defined in another file.
#define	PBL_LOG_MODULE_LEVEL_GET(name)
	Get the runtime level of a module built with CONFIG_<module>_LOG_LEVEL_RUNTIME.
#define	PBL_LOG_MODULE_LEVEL_SET(name, level)
	Set the runtime level of a module built with CONFIG_<module>_LOG_LEVEL_RUNTIME.
#define	PBL_SHOULD_LOG(level)
	Check whether the current file logs messages of a level.
#define	PBL_LOG_COLOR(level, color, fmt, ...)
	Log a message with an explicit level and color, possibly queued.
#define	PBL_LOG_COLOR_SYNC(level, color, fmt, ...)
	Log a message with an explicit level and color, sent before returning.
#define	PBL_LOG_ALWAYS(fmt, ...)    PBL_LOG_COLOR(LOG_LEVEL_ALWAYS, LOG_COLOR_FOR_ALWAYS, fmt, ##__VA_ARGS__)
	Log a message that is never filtered, possibly queued.
#define	PBL_LOG_ERR(fmt, ...)    PBL_LOG_COLOR(LOG_LEVEL_ERROR, LOG_COLOR_FOR_ERROR, fmt, ##__VA_ARGS__)
	Log an error, possibly queued.
#define	PBL_LOG_WRN(fmt, ...)    PBL_LOG_COLOR(LOG_LEVEL_WARNING, LOG_COLOR_FOR_WARNING, fmt, ##__VA_ARGS__)
	Log a warning, possibly queued.
#define	PBL_LOG_INFO(fmt, ...)   PBL_LOG_COLOR(LOG_LEVEL_INFO, LOG_COLOR_FOR_INFO, fmt, ##__VA_ARGS__)
	Log an attention-worthy event, possibly queued.
#define	PBL_LOG_DBG(fmt, ...)    PBL_LOG_COLOR(LOG_LEVEL_DEBUG, LOG_COLOR_FOR_DEBUG, fmt, ##__VA_ARGS__)
	Log a routine debug message, possibly queued.
#define	PBL_LOG_VERBOSE(fmt, ...)    PBL_LOG_COLOR(LOG_LEVEL_DEBUG_VERBOSE, LOG_COLOR_FOR_VERBOSE, fmt, ##__VA_ARGS__)
	Log a verbose debug message, possibly queued.
#define	PBL_LOG_SYNC_ALWAYS(fmt, ...)    PBL_LOG_COLOR_SYNC(LOG_LEVEL_ALWAYS, LOG_COLOR_FOR_ALWAYS, fmt, ##__VA_ARGS__)
	Log a message that is never filtered, sent before returning.
#define	PBL_LOG_SYNC_ERR(fmt, ...)    PBL_LOG_COLOR_SYNC(LOG_LEVEL_ERROR, LOG_COLOR_FOR_ERROR, fmt, ##__VA_ARGS__)
	Log an error, sent before returning.
#define	PBL_LOG_SYNC_WRN(fmt, ...)    PBL_LOG_COLOR_SYNC(LOG_LEVEL_WARNING, LOG_COLOR_FOR_WARNING, fmt, ##__VA_ARGS__)
	Log a warning, sent before returning.
#define	PBL_LOG_SYNC_INFO(fmt, ...)    PBL_LOG_COLOR_SYNC(LOG_LEVEL_INFO, LOG_COLOR_FOR_INFO, fmt, ##__VA_ARGS__)
	Log an attention-worthy event, sent before returning.
#define	PBL_LOG_SYNC_DBG(fmt, ...)    PBL_LOG_COLOR_SYNC(LOG_LEVEL_DEBUG, LOG_COLOR_FOR_DEBUG, fmt, ##__VA_ARGS__)
	Log a routine debug message, sent before returning.
#define	PBL_LOG_SYNC_VERBOSE(fmt, ...)    PBL_LOG_COLOR_SYNC(LOG_LEVEL_DEBUG_VERBOSE, LOG_COLOR_FOR_VERBOSE, fmt, ##__VA_ARGS__)
	Log a verbose debug message, sent before returning.
#define	RETURN_STATUS(st)   return (st)
	Return a status code, logging a warning if it is a failure.
#define	RETURN_STATUS_UP(st)   return ((st) == E_INVALID_ARGUMENT ? E_INTERNAL : (st))
	Return a status code to the caller, turning E_INVALID_ARGUMENT into E_INTERNAL.

Functions
void	pbl_log_hashed_async (const uint32_t packed_loghash,...)
	Log a hashed message, possibly queued.
void	pbl_log_hashed_sync (const uint32_t packed_loghash,...)
	Log a hashed message, sent before returning.
void	pbl_log_hashed_filtered_async (const uint32_t packed_loghash,...)
	pbl_log_hashed_async() for modules with a runtime level, bypassing the sink filters.
void	pbl_log_hashed_filtered_sync (const uint32_t packed_loghash,...)
	pbl_log_hashed_sync() for modules with a runtime level, bypassing the sink filters.
void	pbl_log_hashed_core (const uint32_t core_number, const uint32_t packed_loghash,...)
	Log a hashed message from another core, possibly queued.
void	pbl_log_hashed_vargs (const bool async, const uint32_t core_number, const uint32_t packed_loghash, va_list fmt_args)
	Log a hashed message from another core, with a va_list.
void	pbl_log_vargs (uint8_t log_level, const char *src_filename, int src_line_number, const char *fmt, va_list args)
	Log a message with a va_list, possibly queued.
void	pbl_log (uint8_t log_level, const char *src_filename, int src_line_number, const char *fmt,...)
	Log a message, possibly queued.
void	pbl_log_sync (uint8_t log_level, const char *src_filename, int src_line_number, const char *fmt,...)
	Log a message, sent before returning.
void	pbl_log_filtered (uint8_t log_level, const char *src_filename, int src_line_number, const char *fmt,...)
	pbl_log() for modules with a runtime level, bypassing the sink filters.
void	pbl_log_filtered_sync (uint8_t log_level, const char *src_filename, int src_line_number, const char *fmt,...)
	pbl_log_sync() for modules with a runtime level, bypassing the sink filters.
int	pbl_log_binary_format (char *buffer, int buffer_len, const uint8_t log_level, const char *src_filename_path, int src_line_number, const char *fmt, va_list args)
	Format a message as a binary log record.
int	pbl_log_get_bin_format (char *buffer, int buffer_len, const uint8_t log_level, const char *src_filename_path, int src_line_number, const char *fmt,...)
	pbl_log_binary_format() with variadic arguments.

Log colors
Color names stored with hashed messages, used by the host console.
#define	LOG_COLOR_BLACK   "BLACK"
	Black, hardly readable.
#define	LOG_COLOR_RED   "RED"
	Red.
#define	LOG_COLOR_GREEN   "GREEN"
	Green.
#define	LOG_COLOR_YELLOW   "YELLOW"
	Yellow.
#define	LOG_COLOR_BLUE   "BLUE"
	Blue.
#define	LOG_COLOR_MAGENTA   "MAGENTA"
	Magenta.
#define	LOG_COLOR_CYAN   "CYAN"
	Cyan.
#define	LOG_COLOR_GREY   "GREY"
	Grey.
#define	LOG_COLOR_LIGHT_GREY   "LIGHT_GREY"
	Light grey, reserved for bold like the other light colors.
#define	LOG_COLOR_LIGHT_RED   "LIGHT_RED"
	Light red.
#define	LOG_COLOR_LIGHT_GREEN   "LIGHT_GREEN"
	Light green.
#define	LOG_COLOR_LIGHT_YELLOW   "LIGHT_YELLOW"
	Light yellow.
#define	LOG_COLOR_LIGHT_BLUE   "LIGHT_BLUE"
	Light blue.
#define	LOG_COLOR_LIGHT_MAGENTA   "LIGHT_MAGENTA"
	Light magenta.
#define	LOG_COLOR_LIGHT_CYAN   "LIGHT_CYAN"
	Light cyan.
#define	LOG_COLOR_WHITE   "WHITE"
	White.
#define	LOG_COLOR_FOR_ALWAYS   LOG_COLOR_BLUE
	Color of LOG_LEVEL_ALWAYS messages.
#define	LOG_COLOR_FOR_ERROR   LOG_COLOR_RED
	Color of LOG_LEVEL_ERROR messages.
#define	LOG_COLOR_FOR_WARNING   LOG_COLOR_YELLOW
	Color of LOG_LEVEL_WARNING messages.
#define	LOG_COLOR_FOR_INFO   LOG_COLOR_GREEN
	Color of LOG_LEVEL_INFO messages.
#define	LOG_COLOR_FOR_DEBUG   LOG_COLOR_GREY
	Color of LOG_LEVEL_DEBUG messages.
#define	LOG_COLOR_FOR_VERBOSE   LOG_COLOR_GREY
	Color of LOG_LEVEL_DEBUG_VERBOSE messages.

Detailed Description

Leveled logging to the serial console (or PULSE) and to flash.

Use the level-named macros: PBL_LOG_ERR() and PBL_LOG_WRN() for errors and warnings, PBL_LOG_DBG() for routine lifecycle and state-transition messages, and PBL_LOG_INFO() only for events that deserve attention in a default-level capture; code paths that can fire repeatedly in normal use must not log at INFO. PBL_LOG_ALWAYS() is never filtered.

Each source file can belong to a log module with a Kconfig level, generated by subsys/logging/Kconfig.template.log_level; messages above the module level are compiled out. Files without a module use DEFAULT_LOG_LEVEL. A module built with CONFIG_<module>_LOG_LEVEL_RUNTIME keeps all its messages and filters them at runtime, see PBL_LOG_MODULE_LEVEL_SET().

The async macros may queue the message when called from an interrupt or with interrupts or the scheduler locked; the sync variants send it before returning in every context, for fault paths. With CONFIG_LOG_HASHED the format strings are replaced by tokens at build time (see Log hashing), which limits them to 7 conversions, 2 of them %s, 32-bit arguments and no %%.

Note

Do not mix %s with %x or %X in one message; the log dehasher cannot decode it. Split the message instead.

PBL_LOG_MODULE_DEFINE(my_service, CONFIG_MY_SERVICE_LOG_LEVEL);
 
PBL_LOG_DBG("Connected, interval %u ms", interval_ms);
PBL_LOG_WRN("Write failed: %d", rc);
PBL_LOG_ERR("Bad header 0x%" PRIx32, hdr);
PBL_LOG_DBG("Peer %s", name);

Other files of the same module use PBL_LOG_MODULE_DECLARE() with the same arguments.

Macro Definition Documentation

DEFAULT_LOG_LEVEL

#define DEFAULT_LOG_LEVEL   LOG_LEVEL_DEBUG

Compile-time level of files without a log module, from CONFIG_DEFAULT_LOG_LEVEL.

FLASH_LOG_LEVEL

#define FLASH_LOG_LEVEL   LOG_LEVEL_INFO

Highest level written to the flash log, from the CONFIG_FLASH_LOG_LEVEL_ choice.

LOG_BUFFER_LENGTH

#define LOG_BUFFER_LENGTH   128

Size of the buffer a log message is formatted into, header included.

LOG_COLOR_BLACK

#define LOG_COLOR_BLACK   "BLACK"

Black, hardly readable.

LOG_COLOR_BLUE

#define LOG_COLOR_BLUE   "BLUE"

Blue.

LOG_COLOR_CYAN

#define LOG_COLOR_CYAN   "CYAN"

Cyan.

LOG_COLOR_FOR_ALWAYS

#define LOG_COLOR_FOR_ALWAYS   LOG_COLOR_BLUE

Color of LOG_LEVEL_ALWAYS messages.

LOG_COLOR_FOR_DEBUG

#define LOG_COLOR_FOR_DEBUG   LOG_COLOR_GREY

Color of LOG_LEVEL_DEBUG messages.

LOG_COLOR_FOR_ERROR

#define LOG_COLOR_FOR_ERROR   LOG_COLOR_RED

Color of LOG_LEVEL_ERROR messages.

LOG_COLOR_FOR_INFO

#define LOG_COLOR_FOR_INFO   LOG_COLOR_GREEN

Color of LOG_LEVEL_INFO messages.

LOG_COLOR_FOR_VERBOSE

#define LOG_COLOR_FOR_VERBOSE   LOG_COLOR_GREY

Color of LOG_LEVEL_DEBUG_VERBOSE messages.

LOG_COLOR_FOR_WARNING

#define LOG_COLOR_FOR_WARNING   LOG_COLOR_YELLOW

Color of LOG_LEVEL_WARNING messages.

LOG_COLOR_GREEN

#define LOG_COLOR_GREEN   "GREEN"

Green.

LOG_COLOR_GREY

#define LOG_COLOR_GREY   "GREY"

Grey.

LOG_COLOR_LIGHT_BLUE

#define LOG_COLOR_LIGHT_BLUE   "LIGHT_BLUE"

Light blue.

LOG_COLOR_LIGHT_CYAN

#define LOG_COLOR_LIGHT_CYAN   "LIGHT_CYAN"

Light cyan.

LOG_COLOR_LIGHT_GREEN

#define LOG_COLOR_LIGHT_GREEN   "LIGHT_GREEN"

Light green.

LOG_COLOR_LIGHT_GREY

#define LOG_COLOR_LIGHT_GREY   "LIGHT_GREY"

Light grey, reserved for bold like the other light colors.

Use sparingly.

LOG_COLOR_LIGHT_MAGENTA

#define LOG_COLOR_LIGHT_MAGENTA   "LIGHT_MAGENTA"

Light magenta.

LOG_COLOR_LIGHT_RED

#define LOG_COLOR_LIGHT_RED   "LIGHT_RED"

Light red.

LOG_COLOR_LIGHT_YELLOW

#define LOG_COLOR_LIGHT_YELLOW   "LIGHT_YELLOW"

Light yellow.

LOG_COLOR_MAGENTA

#define LOG_COLOR_MAGENTA   "MAGENTA"

Magenta.

LOG_COLOR_RED

#define LOG_COLOR_RED   "RED"

Red.

LOG_COLOR_WHITE

#define LOG_COLOR_WHITE   "WHITE"

White.

LOG_COLOR_YELLOW

#define LOG_COLOR_YELLOW   "YELLOW"

Yellow.

LOG_LEVEL_ALWAYS

#define LOG_LEVEL_ALWAYS   0

Level of messages that are never filtered.

LOG_LEVEL_DEBUG

#define LOG_LEVEL_DEBUG   200

Debug level.

LOG_LEVEL_DEBUG_VERBOSE

#define LOG_LEVEL_DEBUG_VERBOSE   255

Verbose debug level.

LOG_LEVEL_ERROR

#define LOG_LEVEL_ERROR   1

Error level.

LOG_LEVEL_INFO

#define LOG_LEVEL_INFO   100

Info level.

LOG_LEVEL_OFF

#define LOG_LEVEL_OFF   (-1)

Module level that disables every message of the module.

LOG_LEVEL_WARNING

#define LOG_LEVEL_WARNING   50

Warning level.

LOGGING_MIN_STACK_FOR_SPRINTF

#define LOGGING_MIN_STACK_FOR_SPRINTF   240

Minimum free stack, in bytes, to format a message; below it the message is replaced.

LOGGING_STACK_FULL_MSG

#define LOGGING_STACK_FULL_MSG   ((const char *)" [STK FULL]")

Message logged instead when the stack is too full to format it.

PBL_LOG_ALWAYS

#define PBL_LOG_ALWAYS	(		fmt,
			...
	)		PBL_LOG_COLOR(LOG_LEVEL_ALWAYS, LOG_COLOR_FOR_ALWAYS, fmt, ##__VA_ARGS__)

Log a message that is never filtered, possibly queued.

Parameters

fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_COLOR

#define PBL_LOG_COLOR	(		level,
			color,
			fmt,
			...
	)

Log a message with an explicit level and color, possibly queued.

Prefer the level-named macros.

Parameters

level	Level, one of the LOG_LEVEL_ values.
color	Color, one of the LOG_COLOR_ values.
fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_COLOR_SYNC

#define PBL_LOG_COLOR_SYNC	(		level,
			color,
			fmt,
			...
	)

Log a message with an explicit level and color, sent before returning.

Prefer the level-named macros.

Parameters

level	Level, one of the LOG_LEVEL_ values.
color	Color, one of the LOG_COLOR_ values.
fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_DBG

#define PBL_LOG_DBG	(		fmt,
			...
	)		PBL_LOG_COLOR(LOG_LEVEL_DEBUG, LOG_COLOR_FOR_DEBUG, fmt, ##__VA_ARGS__)

Log a routine debug message, possibly queued.

Parameters

fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_ERR

#define PBL_LOG_ERR	(		fmt,
			...
	)		PBL_LOG_COLOR(LOG_LEVEL_ERROR, LOG_COLOR_FOR_ERROR, fmt, ##__VA_ARGS__)

Log an error, possibly queued.

Parameters

fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_INFO

#define PBL_LOG_INFO	(		fmt,
			...
	)		PBL_LOG_COLOR(LOG_LEVEL_INFO, LOG_COLOR_FOR_INFO, fmt, ##__VA_ARGS__)

Log an attention-worthy event, possibly queued.

Parameters

fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_MODULE_DECLARE

#define PBL_LOG_MODULE_DECLARE	(		name,
			level
	)		PBL_LOG_MODULE_DEFINE(name, level)

Put the current file in a log module defined in another file.

Parameters

name	Module name, as given to PBL_LOG_MODULE_DEFINE().
level	Kconfig level symbol, as given to PBL_LOG_MODULE_DEFINE().

PBL_LOG_MODULE_DEFINE

#define PBL_LOG_MODULE_DEFINE	(		name,
			level
	)		PBL_UNUSED static const int16_t _pbl_log_module_level = 0

Put the current file in a log module, defining the module.

Use it once per module, in one source file, before any PBL_LOG macro.

Parameters

name	Module name, an identifier.
level	Kconfig level symbol, CONFIG_<module>_LOG_LEVEL.

PBL_LOG_MODULE_LEVEL_GET

#define PBL_LOG_MODULE_LEVEL_GET

(

name

)

Value:

  ({                                                                   \
    extern int16_t _pbl_log_runtime_level_##name;                      \
    __atomic_load_n(&_pbl_log_runtime_level_##name, __ATOMIC_RELAXED); \
  })

Get the runtime level of a module built with CONFIG_<module>_LOG_LEVEL_RUNTIME.

Parameters

name	Module name.

Returns

Current level.

PBL_LOG_MODULE_LEVEL_SET

#define PBL_LOG_MODULE_LEVEL_SET	(		name,
			level
	)

Value:

  do {                                                                           \
    extern int16_t _pbl_log_runtime_level_##name;                                \
    __atomic_store_n(&_pbl_log_runtime_level_##name, (level), __ATOMIC_RELAXED); \
  } while (0)

Set the runtime level of a module built with CONFIG_<module>_LOG_LEVEL_RUNTIME.

Messages above the level are dropped; the global sink levels no longer apply to the module.

Parameters

name	Module name.
level	New level, one of the LOG_LEVEL_ values.

PBL_LOG_SYNC_ALWAYS

#define PBL_LOG_SYNC_ALWAYS	(		fmt,
			...
	)		PBL_LOG_COLOR_SYNC(LOG_LEVEL_ALWAYS, LOG_COLOR_FOR_ALWAYS, fmt, ##__VA_ARGS__)

Log a message that is never filtered, sent before returning.

Parameters

fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_SYNC_DBG

#define PBL_LOG_SYNC_DBG	(		fmt,
			...
	)		PBL_LOG_COLOR_SYNC(LOG_LEVEL_DEBUG, LOG_COLOR_FOR_DEBUG, fmt, ##__VA_ARGS__)

Log a routine debug message, sent before returning.

Parameters

fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_SYNC_ERR

#define PBL_LOG_SYNC_ERR	(		fmt,
			...
	)		PBL_LOG_COLOR_SYNC(LOG_LEVEL_ERROR, LOG_COLOR_FOR_ERROR, fmt, ##__VA_ARGS__)

Log an error, sent before returning.

Parameters

fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_SYNC_INFO

#define PBL_LOG_SYNC_INFO	(		fmt,
			...
	)		PBL_LOG_COLOR_SYNC(LOG_LEVEL_INFO, LOG_COLOR_FOR_INFO, fmt, ##__VA_ARGS__)

Log an attention-worthy event, sent before returning.

Parameters

fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_SYNC_VERBOSE

#define PBL_LOG_SYNC_VERBOSE	(		fmt,
			...
	)		PBL_LOG_COLOR_SYNC(LOG_LEVEL_DEBUG_VERBOSE, LOG_COLOR_FOR_VERBOSE, fmt, ##__VA_ARGS__)

Log a verbose debug message, sent before returning.

Parameters

fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_SYNC_WRN

#define PBL_LOG_SYNC_WRN	(		fmt,
			...
	)		PBL_LOG_COLOR_SYNC(LOG_LEVEL_WARNING, LOG_COLOR_FOR_WARNING, fmt, ##__VA_ARGS__)

Log a warning, sent before returning.

Parameters

fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_VERBOSE

#define PBL_LOG_VERBOSE	(		fmt,
			...
	)		PBL_LOG_COLOR(LOG_LEVEL_DEBUG_VERBOSE, LOG_COLOR_FOR_VERBOSE, fmt, ##__VA_ARGS__)

Log a verbose debug message, possibly queued.

Parameters

fmt	printf-style format, a string literal.
...	Format arguments.

PBL_LOG_WRN

#define PBL_LOG_WRN	(		fmt,
			...
	)		PBL_LOG_COLOR(LOG_LEVEL_WARNING, LOG_COLOR_FOR_WARNING, fmt, ##__VA_ARGS__)

Log a warning, possibly queued.

Parameters

fmt	printf-style format, a string literal.
...	Format arguments.

PBL_SHOULD_LOG

#define PBL_SHOULD_LOG

(

level

)

Value:

  ((level) <= (_pbl_log_module_level != 0 ? _pbl_log_module_level : DEFAULT_LOG_LEVEL) && \
   (_pbl_log_module_runtime_level == NULL ||                                              \
    (level) <= __atomic_load_n(_pbl_log_module_runtime_level, __ATOMIC_RELAXED)))

Check whether the current file logs messages of a level.

Applies the module (or default) compile-time level and the module runtime level, if any.

Parameters

level

Level, one of the LOG_LEVEL_ values.

RETURN_STATUS

#define RETURN_STATUS

(

st

)

return (st)

Return a status code, logging a warning if it is a failure.

Parameters

st	Status code.

RETURN_STATUS_UP

#define RETURN_STATUS_UP

(

st

)

return ((st) == E_INVALID_ARGUMENT ? E_INTERNAL : (st))

Return a status code to the caller, turning E_INVALID_ARGUMENT into E_INTERNAL.

An invalid argument passed down by this layer is an internal error for its caller.

Parameters

st	Status code.

SPLIT_64_BIT_ARG

#define SPLIT_64_BIT_ARG

(

x

)

(uint32_t)((x >> 32) & 0xFFFFFFFF), (uint32_t)(x & 0xFFFFFFFF)

Expand a 64-bit value into two 32-bit arguments, high word first.

Hashed logs only take 32-bit arguments; print the result with two conversions.

Parameters

x	64-bit value.

STATUS_STRING

#define STATUS_STRING

(

s

)

STRINGIFY(s)

Turn the expansion of a status code into a string literal.

Parameters

s	Status code.

STRINGIFY

#define STRINGIFY

(

a

)

STRINGIFY_NX(a)

Turn the expansion of the argument into a string literal.

Parameters

a

Argument.

STRINGIFY_NX

#define STRINGIFY_NX

(

a

)

#a

Turn the argument into a string literal without expanding it.

Parameters

a

Argument.

Function Documentation

pbl_log()

void pbl_log	(	uint8_t	log_level,
		const char *	src_filename,
		int	src_line_number,
		const char *	fmt,
			...
	)

Log a message, possibly queued.

Prefer the PBL_LOG macros, which filter by level and hash the format.

Parameters

log_level	Level, one of the LOG_LEVEL_ values.
src_filename	Source file path.
src_line_number	Source line number.
fmt	printf-style format.
...	Format arguments.

pbl_log_binary_format()

int pbl_log_binary_format	(	char *	buffer,
		int	buffer_len,
		const uint8_t	log_level,
		const char *	src_filename_path,
		int	src_line_number,
		const char *	fmt,
		va_list	args
	)

Format a message as a binary log record.

The record holds a timestamp, the level, the line number, the last 15 characters of the file name and the formatted message, truncated to fit.

Parameters

[out]	buffer	Destination, larger than the record header.
	buffer_len	Size of buffer in bytes.
	log_level	Level, one of the LOG_LEVEL_ values.
	src_filename_path	Source file path.
	src_line_number	Source line number.
	fmt	printf-style format.
	args	Format arguments.

Returns

Length of the record in bytes.

pbl_log_filtered()

void pbl_log_filtered	(	uint8_t	log_level,
		const char *	src_filename,
		int	src_line_number,
		const char *	fmt,
			...
	)

pbl_log() for modules with a runtime level, bypassing the sink filters.

Parameters

log_level	Level, one of the LOG_LEVEL_ values.
src_filename	Source file path.
src_line_number	Source line number.
fmt	printf-style format.
...	Format arguments.

pbl_log_filtered_sync()

void pbl_log_filtered_sync	(	uint8_t	log_level,
		const char *	src_filename,
		int	src_line_number,
		const char *	fmt,
			...
	)

pbl_log_sync() for modules with a runtime level, bypassing the sink filters.

Parameters

log_level	Level, one of the LOG_LEVEL_ values.
src_filename	Source file path.
src_line_number	Source line number.
fmt	printf-style format.
...	Format arguments.

pbl_log_get_bin_format()

int pbl_log_get_bin_format	(	char *	buffer,
		int	buffer_len,
		const uint8_t	log_level,
		const char *	src_filename_path,
		int	src_line_number,
		const char *	fmt,
			...
	)

pbl_log_binary_format() with variadic arguments.

Parameters

[out]	buffer	Destination, larger than the record header.
	buffer_len	Size of buffer in bytes.
	log_level	Level, one of the LOG_LEVEL_ values.
	src_filename_path	Source file path.
	src_line_number	Source line number.
	fmt	printf-style format.
	...	Format arguments.

Returns

Length of the record in bytes.

pbl_log_hashed_async()

void pbl_log_hashed_async	(	const uint32_t	packed_loghash,
			...
	)

Log a hashed message, possibly queued.

Called by the PBL_LOG macros.

Parameters

packed_loghash	Message token, see Log hashing.
...	Message arguments, 32 bits each.

pbl_log_hashed_core()

void pbl_log_hashed_core	(	const uint32_t	core_number,
		const uint32_t	packed_loghash,
			...
	)

Log a hashed message from another core, possibly queued.

Parameters

core_number	Core number, already shifted to PACKED_CORE_OFFSET.
packed_loghash	Message token, see Log hashing.
...	Message arguments, 32 bits each.

pbl_log_hashed_filtered_async()

void pbl_log_hashed_filtered_async	(	const uint32_t	packed_loghash,
			...
	)

pbl_log_hashed_async() for modules with a runtime level, bypassing the sink filters.

Parameters

packed_loghash	Message token, see Log hashing.
...	Message arguments, 32 bits each.

pbl_log_hashed_filtered_sync()

void pbl_log_hashed_filtered_sync	(	const uint32_t	packed_loghash,
			...
	)

pbl_log_hashed_sync() for modules with a runtime level, bypassing the sink filters.

Parameters

packed_loghash	Message token, see Log hashing.
...	Message arguments, 32 bits each.

pbl_log_hashed_sync()

void pbl_log_hashed_sync	(	const uint32_t	packed_loghash,
			...
	)

Log a hashed message, sent before returning.

Called by the PBL_LOG_SYNC macros.

Parameters

packed_loghash	Message token, see Log hashing.
...	Message arguments, 32 bits each.

pbl_log_hashed_vargs()

void pbl_log_hashed_vargs	(	const bool	async,
		const uint32_t	core_number,
		const uint32_t	packed_loghash,
		va_list	fmt_args
	)

Log a hashed message from another core, with a va_list.

Parameters

async	Whether the message may be queued.
core_number	Core number, already shifted to PACKED_CORE_OFFSET.
packed_loghash	Message token, see Log hashing.
fmt_args	Message arguments, 32 bits each.

pbl_log_sync()

void pbl_log_sync	(	uint8_t	log_level,
		const char *	src_filename,
		int	src_line_number,
		const char *	fmt,
			...
	)

Log a message, sent before returning.

Parameters

log_level	Level, one of the LOG_LEVEL_ values.
src_filename	Source file path.
src_line_number	Source line number.
fmt	printf-style format.
...	Format arguments.

pbl_log_vargs()

void pbl_log_vargs	(	uint8_t	log_level,
		const char *	src_filename,
		int	src_line_number,
		const char *	fmt,
		va_list	args
	)

Log a message with a va_list, possibly queued.

Parameters

log_level	Level, one of the LOG_LEVEL_ values.
src_filename	Source file path.
src_line_number	Source line number.
fmt	printf-style format.
args	Format arguments.