Log Framework API Reference

This section documents the Log Framework API.

Log Definitions

enum log_async_policy_t

Async buffer full policy.

Values:

enumerator LOG_ASYNC_POLICY_DROP_OLDEST

Drop oldest message when full

enumerator LOG_ASYNC_POLICY_DROP_NEWEST

Drop newest message when full

enumerator LOG_ASYNC_POLICY_BLOCK

Block until space available

LOG_DEFAULT_LEVEL

Default configuration values.

LOG_MAX_MSG_LEN

LOG_MAX_BACKENDS

LOG_MAX_MODULE_FILTERS

LOG_MODULE_NAME_LEN

LOG_DEFAULT_FORMAT

LOG_ASYNC_BUFFER_SIZE

LOG_ASYNC_QUEUE_SIZE

LOG_ASYNC_TASK_STACK_SIZE

LOG_ASYNC_TASK_PRIORITY

enum log_status_t

Log status codes.

Values:

enumerator LOG_OK

Operation successful

enumerator LOG_ERROR

Generic error

enumerator LOG_ERROR_INVALID_PARAM

Invalid parameter

enumerator LOG_ERROR_NOT_INIT

Not initialized

enumerator LOG_ERROR_NO_MEMORY

Out of memory

enumerator LOG_ERROR_FULL

Buffer full

enumerator LOG_ERROR_BACKEND

Backend error

enumerator LOG_ERROR_ALREADY_INIT

Already initialized

enum log_level_t

Log levels.

Log levels are ordered from most verbose (TRACE) to least verbose (FATAL). LOG_LEVEL_NONE disables all logging.

Values:

enumerator LOG_LEVEL_TRACE

Most detailed tracing information

enumerator LOG_LEVEL_DEBUG

Debug information

enumerator LOG_LEVEL_INFO

General information

enumerator LOG_LEVEL_WARN

Warning messages

enumerator LOG_LEVEL_ERROR

Error messages

enumerator LOG_LEVEL_FATAL

Fatal error messages

enumerator LOG_LEVEL_NONE

Disable all logging

LOG_COMPILE_LEVEL

Compile-time log level.

Messages below this level will be compiled out entirely. Set to LOG_LEVEL_NONE to disable all logging at compile time. This reduces code size by eliminating log calls at compile time.

Example usage in build system:

• CMake: add_definitions(-DLOG_COMPILE_LEVEL=LOG_LEVEL_INFO)

• GCC: -DLOG_COMPILE_LEVEL=LOG_LEVEL_INFO

Requirements: 7.2, 7.3

LOG_USE_STATIC_ALLOC

Static allocation mode.

When enabled (set to 1), the log framework uses static allocation instead of dynamic memory allocation (malloc/free). This is useful for embedded systems where dynamic allocation is not available or not desired.

When static allocation is enabled:

• Backend structures are allocated from a static pool

• Memory backend uses a static buffer

• No malloc/free calls are made

Requirements: 7.4

LOG_STATIC_BACKEND_COUNT

Maximum number of statically allocated backends.

Note

Only used when LOG_USE_STATIC_ALLOC is enabled

LOG_STATIC_MEMORY_BUFFER_SIZE

Static memory backend buffer size.

Note

Only used when LOG_USE_STATIC_ALLOC is enabled

LOG_IS_OK(status)

Check if status is OK.

Parameters:

• status – [in] Status to check

Returns:

true if OK, false otherwise

LOG_IS_ERROR(status)

Check if status is error.

Parameters:

• status – [in] Status to check

Returns:

true if error, false otherwise

LOG_RETURN_IF_ERROR(status)

Return if status is error.

Parameters:

• status – [in] Status to check

LOG_UNUSED(x)

Unused parameter macro.

Parameters:

• x – [in] Parameter to mark as unused

Log Macros

LOG_TRACE(fmt, ...)

Log a trace message.

Parameters:

• fmt – [in] Printf-style format string

• ... – [in] Format arguments

LOG_DEBUG(fmt, ...)

Log a debug message.

Parameters:

• fmt – [in] Printf-style format string

• ... – [in] Format arguments

LOG_INFO(fmt, ...)

Log an info message.

Parameters:

• fmt – [in] Printf-style format string

• ... – [in] Format arguments

LOG_WARN(fmt, ...)

Log a warning message.

Parameters:

• fmt – [in] Printf-style format string

• ... – [in] Format arguments

LOG_ERROR(fmt, ...)

Log an error message.

Parameters:

• fmt – [in] Printf-style format string

• ... – [in] Format arguments

LOG_FATAL(fmt, ...)

Log a fatal error message.

Parameters:

• fmt – [in] Printf-style format string

• ... – [in] Format arguments

LOG_MODULE

Default module name if not defined.

LOG_WRITE(level, fmt, ...)

Internal logging macro.

Log Backend

typedef struct log_backend log_backend_t

Forward declaration of backend structure.

typedef log_status_t (*log_backend_init_fn)(void *ctx)

Backend initialization function type.

Param ctx:

[in] Backend context

Return:

LOG_OK on success, error code otherwise

typedef log_status_t (*log_backend_write_fn)(void *ctx, const char *msg, size_t len)

Backend write function type.

Param ctx:

[in] Backend context

Param msg:

[in] Message to write

Param len:

[in] Message length

Return:

LOG_OK on success, error code otherwise

typedef log_status_t (*log_backend_flush_fn)(void *ctx)

Backend flush function type.

Param ctx:

[in] Backend context

Return:

LOG_OK on success, error code otherwise

typedef log_status_t (*log_backend_deinit_fn)(void *ctx)

Backend deinitialization function type.

Param ctx:

[in] Backend context

Return:

LOG_OK on success, error code otherwise

log_status_t log_backend_register(log_backend_t *backend)

Register a backend with the log system.

Note

The backend structure must remain valid for the lifetime of the registration

Parameters:

backend – [in] Pointer to backend structure

Returns:

LOG_OK on success, error code otherwise

log_status_t log_backend_unregister(const char *name)

Unregister a backend from the log system.

Parameters:

name – [in] Name of the backend to unregister

Returns:

LOG_OK on success, error code otherwise

log_status_t log_backend_enable(const char *name, bool enable)

Enable or disable a backend.

Parameters:

• name – [in] Name of the backend

• enable – [in] true to enable, false to disable

Returns:

LOG_OK on success, error code otherwise

log_backend_t *log_backend_get(const char *name)

Get a registered backend by name.

Parameters:

name – [in] Name of the backend

Returns:

Pointer to backend, or NULL if not found

struct log_backend

#include <log_backend.h>

Log backend structure.

Defines the interface for log output backends. Each backend must implement at least the write function.

Public Members

const char *name

Backend name (must be unique)

log_backend_init_fn init

Initialization function (optional)

log_backend_write_fn write

Write function (required)

log_backend_flush_fn flush

Flush function (optional)

log_backend_deinit_fn deinit

Deinitialization function (optional)

void *ctx

Backend-specific context

log_level_t min_level

Minimum level for this backend

bool enabled

Whether backend is enabled

Console Backend

log_backend_t *log_backend_console_create(void)

Create a console backend.

Note

Uses stdout for output (Native platform)

Returns:

Pointer to backend structure, or NULL on failure

void log_backend_console_destroy(log_backend_t *backend)

Destroy a console backend.

Parameters:

backend – [in] Pointer to backend to destroy

UART Backend

log_backend_t *log_backend_uart_create(nx_uart_t *uart)

Create a UART backend.

Parameters:

uart – [in] UART interface pointer (nx_uart_t*)

Returns:

Pointer to backend structure, or NULL on failure

void log_backend_uart_destroy(log_backend_t *backend)

Destroy a UART backend.

Parameters:

backend – [in] Pointer to backend to destroy

log_status_t log_backend_uart_set_timeout(log_backend_t *backend, uint32_t timeout_ms)

Set UART backend transmit timeout.

Parameters:

• backend – [in] Pointer to UART backend

• timeout_ms – [in] Timeout in milliseconds

Returns:

LOG_OK on success, error code otherwise

nx_uart_t *log_backend_uart_get_interface(log_backend_t *backend)

Get UART interface from backend.

Parameters:

backend – [in] Pointer to UART backend

Returns:

UART interface pointer, or NULL on error

Memory Backend

log_backend_t *log_backend_memory_create(size_t size)

Create a memory backend.

Parameters:

size – [in] Buffer size in bytes

Returns:

Pointer to backend structure, or NULL on failure

void log_backend_memory_destroy(log_backend_t *backend)

Destroy a memory backend.

Parameters:

backend – [in] Pointer to backend to destroy

size_t log_backend_memory_read(log_backend_t *backend, char *buf, size_t len)

Read data from memory backend buffer.

Parameters:

• backend – [in] Pointer to memory backend

• buf – [out] Buffer to read into

• len – [in] Maximum bytes to read

Returns:

Number of bytes read

void log_backend_memory_clear(log_backend_t *backend)

Clear the memory backend buffer.

Parameters:

backend – [in] Pointer to memory backend

size_t log_backend_memory_size(log_backend_t *backend)

Get the number of bytes in the memory backend buffer.

Parameters:

backend – [in] Pointer to memory backend

Returns:

Number of bytes in buffer