日志框架 API 参考

本节记录日志框架 API。

日志定义

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.

注意

Only used when LOG_USE_STATIC_ALLOC is enabled

LOG_STATIC_MEMORY_BUFFER_SIZE

Static memory backend buffer size.

注意

Only used when LOG_USE_STATIC_ALLOC is enabled

LOG_IS_OK(status)

Check if status is OK.

参数:

  • status -- [in] Status to check

返回值:

true if OK, false otherwise

LOG_IS_ERROR(status)

Check if status is error.

参数:

  • status -- [in] Status to check

返回值:

true if error, false otherwise

LOG_RETURN_IF_ERROR(status)

Return if status is error.

参数:

  • status -- [in] Status to check

LOG_UNUSED(x)

Unused parameter macro.

参数:

  • x -- [in] Parameter to mark as unused

日志宏

LOG_TRACE(fmt, ...)

Log a trace message.

参数:

  • fmt -- [in] Printf-style format string

  • ... -- [in] Format arguments

LOG_DEBUG(fmt, ...)

Log a debug message.

参数:

  • fmt -- [in] Printf-style format string

  • ... -- [in] Format arguments

LOG_INFO(fmt, ...)

Log an info message.

参数:

  • fmt -- [in] Printf-style format string

  • ... -- [in] Format arguments

LOG_WARN(fmt, ...)

Log a warning message.

参数:

  • fmt -- [in] Printf-style format string

  • ... -- [in] Format arguments

LOG_ERROR(fmt, ...)

Log an error message.

参数:

  • fmt -- [in] Printf-style format string

  • ... -- [in] Format arguments

LOG_FATAL(fmt, ...)

Log a fatal error message.

参数:

  • fmt -- [in] Printf-style format string

  • ... -- [in] Format arguments

LOG_MODULE

Default module name if not defined.

LOG_WRITE(level, fmt, ...)

Internal logging macro.

日志后端

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.

注意

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

参数:

backend -- [in] Pointer to backend structure

返回值:

LOG_OK on success, error code otherwise

log_status_t log_backend_unregister(const char *name)

Unregister a backend from the log system.

参数:

name -- [in] Name of the backend to unregister

返回值:

LOG_OK on success, error code otherwise

log_status_t log_backend_enable(const char *name, bool enable)

Enable or disable a backend.

参数:

  • name -- [in] Name of the backend

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

返回值:

LOG_OK on success, error code otherwise

log_backend_t *log_backend_get(const char *name)

Get a registered backend by name.

参数:

name -- [in] Name of the backend

返回值:

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 后端

log_backend_t *log_backend_console_create(void)

Create a console backend.

注意

Uses stdout for output (Native platform)

返回值:

Pointer to backend structure, or NULL on failure

void log_backend_console_destroy(log_backend_t *backend)

Destroy a console backend.

参数:

backend -- [in] Pointer to backend to destroy

UART 后端

log_backend_t *log_backend_uart_create(nx_uart_t *uart)

Create a UART backend.

参数:

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

返回值:

Pointer to backend structure, or NULL on failure

void log_backend_uart_destroy(log_backend_t *backend)

Destroy a UART backend.

参数:

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.

参数:

  • backend -- [in] Pointer to UART backend

  • timeout_ms -- [in] Timeout in milliseconds

返回值:

LOG_OK on success, error code otherwise

nx_uart_t *log_backend_uart_get_interface(log_backend_t *backend)

Get UART interface from backend.

参数:

backend -- [in] Pointer to UART backend

返回值:

UART interface pointer, or NULL on error

Memory 后端

log_backend_t *log_backend_memory_create(size_t size)

Create a memory backend.

参数:

size -- [in] Buffer size in bytes

返回值:

Pointer to backend structure, or NULL on failure

void log_backend_memory_destroy(log_backend_t *backend)

Destroy a memory backend.

参数:

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.

参数:

  • backend -- [in] Pointer to memory backend

  • buf -- [out] Buffer to read into

  • len -- [in] Maximum bytes to read

返回值:

Number of bytes read

void log_backend_memory_clear(log_backend_t *backend)

Clear the memory backend buffer.

参数:

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.

参数:

backend -- [in] Pointer to memory backend

返回值:

Number of bytes in buffer