Log links

Interface for log links bringing in messages from remote domains. More...

Files
file	log_link.h
	Header file for the log link interface.

Data Structures
struct	log_link_config
	Log link configuration passed to the link at initiation time. More...
struct	log_link_api
	Log link API. More...
struct	log_link_ctrl_blk
	Run-time control block for a Log links instance. More...
struct	log_link
	Log link instance. More...

Macros
#define	LOG_LINK_DEF(_name, _api, _buf_wlen, _ctx)
	Create instance of a log link.

Typedefs
typedef void(*	log_link_callback_t) (const struct log_link *link, union log_msg_generic *msg)
	Callback invoked by a link for each received log message.
typedef void(*	log_link_dropped_cb_t) (const struct log_link *link, uint32_t dropped)
	Callback invoked by a link to report dropped messages.

Functions
static int	log_link_initiate (const struct log_link *link, struct log_link_config *config)
	Initiate log link.
static int	log_link_activate (const struct log_link *link)
	Activate log link.
static int	log_link_is_active (const struct log_link *link)
	Check if link is activated.
static uint8_t	log_link_domains_count (const struct log_link *link)
	Get number of domains in the link.
static uint16_t	log_link_sources_count (const struct log_link *link, uint32_t domain_id)
	Get number of sources in the domain.
static int	log_link_get_domain_name (const struct log_link *link, uint32_t domain_id, char *buf, size_t *length)
	Get domain name.
static int	log_link_get_source_name (const struct log_link *link, uint32_t domain_id, uint16_t source_id, char *buf, size_t *length)
	Get source name.
static int	log_link_get_levels (const struct log_link *link, uint32_t domain_id, uint16_t source_id, uint8_t *level, uint8_t *runtime_level)
	Get level settings of the given source.
static int	log_link_set_runtime_level (const struct log_link *link, uint32_t domain_id, uint16_t source_id, uint8_t level)
	Set runtime level of the given source.

Detailed Description

Interface for log links bringing in messages from remote domains.

Macro Definition Documentation

LOG_LINK_DEF

#define LOG_LINK_DEF	(		_name,
			_api,
			_buf_wlen,
			_ctx )

#include <log_link.h>

Value:

static uint32_t __aligned(Z_LOG_MSG_ALIGNMENT) _name##_buf32[_buf_wlen]; \
static const struct mpsc_pbuf_buffer_config _name##_mpsc_pbuf_config = { \
        .buf = (uint32_t *)_name##_buf32, \
        .size = _buf_wlen, \
        .notify_drop = z_log_notify_drop, \
        .get_wlen = log_msg_generic_get_wlen, \
        .flags = IS_ENABLED(CONFIG_LOG_MODE_OVERFLOW) ? \
                MPSC_PBUF_MODE_OVERWRITE : 0 \
}; \
COND_CODE_0(_buf_wlen, (), (static STRUCT_SECTION_ITERABLE(log_msg_ptr, \
                                                           _name##_log_msg_ptr);)) \
static STRUCT_SECTION_ITERABLE_ALTERNATE(log_mpsc_pbuf, \
                                         mpsc_pbuf_buffer, \
                                         _name##_log_mpsc_pbuf); \
static struct log_link_ctrl_blk _name##_ctrl_blk; \
static const STRUCT_SECTION_ITERABLE(log_link, _name) = \
{ \
        .api = &_api, \
        .name = STRINGIFY(_name), \
        .ctrl_blk = &_name##_ctrl_blk, \
        .ctx = _ctx, \
        .mpsc_pbuf = _buf_wlen ? &_name##_log_mpsc_pbuf : NULL, \
        .mpsc_pbuf_config = _buf_wlen ? &_name##_mpsc_pbuf_config : NULL \
}

Create instance of a log link.

Link can have dedicated buffer for messages if _buf_len is positive. In that case messages will be processed in an order since logging core will attempt to fetch message from all available buffers (default and links) and process the one with the earliest timestamp. If strict ordering is not needed then dedicated buffer may be omitted (_buf_len set to 0). That results in better memory utilization but unordered messages passed to backends.

Parameters

_name	Instance name.
_api	API list. See log_link_api.
_buf_wlen	Size (in words) of dedicated buffer for messages from this buffer. If 0 default buffer is used.
_ctx	Context (void *) associated with the link.

Typedef Documentation

log_link_callback_t

typedef void(* log_link_callback_t) (const struct log_link *link, union log_msg_generic *msg)

#include <log_link.h>

Callback invoked by a link for each received log message.

Parameters

link	Link instance.
msg	Message received from the remote domain.

log_link_dropped_cb_t

typedef void(* log_link_dropped_cb_t) (const struct log_link *link, uint32_t dropped)

#include <log_link.h>

Callback invoked by a link to report dropped messages.

Parameters

link	Link instance.
dropped	Number of messages dropped since the previous notification.

Function Documentation

log_link_activate()

int log_link_activate ( const struct log_link * link )

inlinestatic

#include <log_link.h>

Activate log link.

Function checks if link is initialized and completes initialization process. When successfully returns, link is ready with domain and sources count fetched and timestamp details updated.

Parameters

link	Log link instance.

Return values

0	When successfully activated.
-EINPROGRESS	Activation in progress.

log_link_domains_count()

uint8_t log_link_domains_count ( const struct log_link * link )

inlinestatic

#include <log_link.h>

Get number of domains in the link.

Parameters

[in]

link

Log link instance.

Returns

Number of domains.

log_link_get_domain_name()

int log_link_get_domain_name ( const struct log_link * link, uint32_t domain_id, char * buf, size_t * length )

inlinestatic

#include <log_link.h>

Get domain name.

Parameters

[in]	link	Log link instance.
[in]	domain_id	Relative domain ID.
[out]	buf	Output buffer filled with domain name. If NULL then name length is returned.
[in,out]	length	Buffer size. Name is trimmed if it does not fit in the buffer and field is set to actual name length.

Returns

0 on success or error code.

log_link_get_levels()

int log_link_get_levels ( const struct log_link * link, uint32_t domain_id, uint16_t source_id, uint8_t * level, uint8_t * runtime_level )

inlinestatic

#include <log_link.h>

Get level settings of the given source.

Parameters

[in]	link	Log link instance.
[in]	domain_id	Relative domain ID.
[in]	source_id	Source ID.
[out]	level	Location to store requested compile time level.
[out]	runtime_level	Location to store requested runtime time level.

Returns

0 on success or error code.

log_link_get_source_name()

int log_link_get_source_name ( const struct log_link * link, uint32_t domain_id, uint16_t source_id, char * buf, size_t * length )

inlinestatic

#include <log_link.h>

Get source name.

Parameters

[in]	link	Log link instance.
[in]	domain_id	Relative domain ID.
[in]	source_id	Source ID.
[out]	buf	Output buffer filled with source name.
[in,out]	length	Buffer size. Name is trimmed if it does not fit in the buffer and field is set to actual name length.

Returns

0 on success or error code.

log_link_initiate()

int log_link_initiate ( const struct log_link * link, struct log_link_config * config )

inlinestatic

#include <log_link.h>

Initiate log link.

Function initiates the link. Since initialization procedure may be time consuming, function returns before link is ready to not block logging initialization. log_link_activate is called to complete link initialization.

Parameters

link	Log link instance.
config	Configuration.

Returns

0 on success or error code.

log_link_is_active()

int log_link_is_active ( const struct log_link * link )

inlinestatic

#include <log_link.h>

Check if link is activated.

Parameters

link	Log link instance.

Return values

0	When successfully activated.
-EINPROGRESS	Activation in progress.

log_link_set_runtime_level()

int log_link_set_runtime_level ( const struct log_link * link, uint32_t domain_id, uint16_t source_id, uint8_t level )

inlinestatic

#include <log_link.h>

Set runtime level of the given source.

Parameters

[in]	link	Log link instance.
[in]	domain_id	Relative domain ID.
[in]	source_id	Source ID.
[in]	level	Requested level.

Returns

0 on success or error code.

log_link_sources_count()

uint16_t log_link_sources_count ( const struct log_link * link, uint32_t domain_id )

inlinestatic

#include <log_link.h>

Get number of sources in the domain.

Parameters

[in]	link	Log link instance.
[in]	domain_id	Relative domain ID.

Returns

Source count.