Log Framework API Reference¶

This section documents the Log Framework API.

Overview¶

The Nexus Log Framework provides a flexible logging system with multiple backends, async mode support, and module-level filtering. It’s designed for embedded systems with minimal overhead and configurable output destinations.

Usage Examples¶

Basic Logging¶

#include "log/log.h"

/* Initialize log framework */
log_init();

/* Log messages at different levels */
LOG_ERROR("System", "Critical error occurred: %d", error_code);
LOG_WARN("System", "Warning: low memory");
LOG_INFO("System", "System initialized successfully");
LOG_DEBUG("System", "Debug info: value=%d", value);

Module-Specific Logging¶

#include "log/log.h"

/* Define module name */
#define MODULE_NAME "MyModule"

void my_function(void) {
    LOG_INFO(MODULE_NAME, "Function started");

    /* Your code here */

    LOG_DEBUG(MODULE_NAME, "Processing data: count=%d", count);
}

Async Logging¶

#include "log/log.h"

/* Configure async mode */
log_config_t config = {
    .async_mode = true,
    .async_buffer_size = 1024,
    .backend = LOG_BACKEND_UART
};

log_init_with_config(&config);

/* Log messages - they're buffered and output asynchronously */
LOG_INFO("App", "Async logging enabled");

Custom Backend¶

#include "log/log.h"
#include "log/log_backend.h"

/* Implement custom backend */
static void my_backend_write(const char* msg, size_t len) {
    /* Write to custom output */
}

static log_backend custom_backend = {
    .write = my_backend_write,
    .flush = NULL  /* Optional */
};

/* Register custom backend */
log_set_backend(&custom_backend);

Thread Safety¶

The Log Framework is thread-safe when async mode is enabled. In synchronous mode, logging from multiple threads requires external synchronization.

Async mode: Thread-safe, uses internal buffering and locking
Sync mode: Not thread-safe, requires external mutex

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

Nexus Embedded Platform

Navigation

Related Topics

Log Framework API Reference¶

Overview¶

Usage Examples¶

Basic Logging¶

Module-Specific Logging¶

Async Logging¶

Custom Backend¶

Thread Safety¶

Log Definitions¶

Log Macros¶

Log Backend¶

Console Backend¶

UART Backend¶

Memory Backend¶

See Also¶

Log Framework API Reference¶

Overview¶

Usage Examples¶

Basic Logging¶

Module-Specific Logging¶

Async Logging¶

Custom Backend¶

Thread Safety¶

Log Definitions¶

Log Macros¶

Log Backend¶

Console Backend¶

UART Backend¶

Memory Backend¶

Related APIs¶

See Also¶