Macros
#define	DOCA_LOG(level, format, ...) doca_log(level, log_source, __FILE__, __LINE__, __func__, format, ##__VA_ARGS__)
	Generates an application log message. More...

#define	DOCA_LOG_CRIT(format, ...) DOCA_LOG(DOCA_LOG_LEVEL_CRIT, format, ##__VA_ARGS__)
	Generates a CRITICAL application log message. More...

#define	DOCA_LOG_ERR(format, ...) DOCA_LOG(DOCA_LOG_LEVEL_ERROR, format, ##__VA_ARGS__)
	Generates an ERROR application log message. More...

#define	DOCA_LOG_WARN(format, ...) DOCA_LOG(DOCA_LOG_LEVEL_WARNING, format, ##__VA_ARGS__)
	Generates a WARNING application log message. More...

#define	DOCA_LOG_INFO(format, ...) DOCA_LOG(DOCA_LOG_LEVEL_INFO, format, ##__VA_ARGS__)
	Generates an INFO application log message. More...

#define	DOCA_LOG_DBG(format, ...) DOCA_LOG(DOCA_LOG_LEVEL_DEBUG, format, ##__VA_ARGS__)
	Generates a DEBUG application log message. More...

#define	DOCA_LOG_TRC(format, ...)
	Generates a TRACE application log message. More...

#define	DOCA_LOG_REGISTER(source)
	Registers log source on program start. More...

Typedefs
typedef void(*	log_flush_callback) (char *buf)
	logging backend flush() handler More...

Enumerations
enum	doca_log_level { DOCA_LOG_LEVEL_DISABLE = 10 , DOCA_LOG_LEVEL_CRIT = 20 , DOCA_LOG_LEVEL_ERROR = 30 , DOCA_LOG_LEVEL_WARNING = 40 , DOCA_LOG_LEVEL_INFO = 50 , DOCA_LOG_LEVEL_DEBUG = 60 , DOCA_LOG_LEVEL_TRACE = 70 }
	log levels, sorted by verbosity level from high to low More...

Functions
DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_set_level_lower_limit (struct doca_log_backend *backend, uint32_t level)
	Set the lower log level of a specific logging backend for application messages. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_set_level_upper_limit (struct doca_log_backend *backend, uint32_t upper_limit)
	Set the upper log level limit of a specific logging backend for application messages. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_set_level_lower_limit_strict (struct doca_log_backend *backend)
	Mark the lower log level limit of a specific logging backend for application messages as strict. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_set_level_upper_limit_strict (struct doca_log_backend *backend)
	Mark the upper log level limit of a specific application logging backend for application messages as strict. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_level_set_global_lower_limit (uint32_t level)
	Set the log level of ALL logging backends for application messages. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_level_set_global_upper_limit (uint32_t upper_limit)
	Set the log upper level limit of ALL logging backends for application messages. More...

DOCA_EXPERIMENTAL uint32_t	doca_log_level_get_global_lower_limit (void)
	Get the global log level for application messages. More...

DOCA_EXPERIMENTAL uint32_t	doca_log_level_get_global_upper_limit (void)
	Get the global upper log level for application messages. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_register_source (const char source_name, int source)
	Register a log source. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_unregister_source (int source)
	Unregister a log source. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_create_with_file (FILE fptr, struct doca_log_backend *backend)
	Create a logging backend for application messages with a FILE* stream. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_create_with_fd (int fd, struct doca_log_backend **backend)
	Create a logging backend for application messages with an fd stream. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_create_with_buf (char buf, size_t capacity, log_flush_callback handler, struct doca_log_backend *backend)
	Create a logging backend for application messages with a char buffer stream. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_create_with_syslog (const char name, struct doca_log_backend *backend)
	Create a logging backend for application messages with a syslog output. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_set_sdk_level (struct doca_log_backend *backend, uint32_t level)
	Set the log level limit for SDK logging backends. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_create_with_file_sdk (FILE fptr, struct doca_log_backend *backend)
	Create a logging backend with a FILE* stream for SDK messages. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_create_with_fd_sdk (int fd, struct doca_log_backend **backend)
	Create a logging backend with an fd stream for SDK messages. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_create_with_buf_sdk (char buf, size_t capacity, log_flush_callback handler, struct doca_log_backend *backend)
	Create a logging backend with a char buffer stream for SDK messages. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_create_with_syslog_sdk (const char name, struct doca_log_backend *backend)
	Create a logging backend with a syslog output for SDK messages. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_level_set_global_sdk_limit (uint32_t level)
	Set the log level of ALL logging backends for SDK messages. More...

DOCA_EXPERIMENTAL uint32_t	doca_log_level_get_global_sdk_limit (void)
	Get the global log level for SDK messages. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log_backend_create_standard (void)
	Create default, non configurable backend for application messages. More...

DOCA_EXPERIMENTAL doca_error_t	doca_log (uint32_t level, int source, const char fname, int line, const char func, const char *format,...) __attribute__((format(printf
	Generates an application log message. More...

Detailed Description

Define functions for internal and external logging management

To add DOCA trace level compile with "-D DOCA_LOGGING_ALLOW_TRACE"

Macro Definition Documentation

◆ DOCA_LOG

#define DOCA_LOG	(	level,
		format,
		...
	)	doca_log(level, log_source, __FILE__, __LINE__, __func__, format, ##__VA_ARGS__)

Generates an application log message.

The DOCA_LOG() is the main log function for logging. This call affects the performance. Consider using the specific level DOCA_LOG for better code readability (i.e. DOCA_LOG_ERR).

Parameters

level	Log level enum DOCA_LOG_LEVEL (just ERROR, WARNING...).
format	printf(3) arguments, format and variables.

Definition at line 446 of file doca_log.h.

◆ DOCA_LOG_CRIT

#define DOCA_LOG_CRIT	(	format,
		...
	)	DOCA_LOG(DOCA_LOG_LEVEL_CRIT, format, ##__VA_ARGS__)

Generates a CRITICAL application log message.

Will generate critical application log. This call affects the performance.

Parameters

format printf(3) arguments, format and variables.

Definition at line 456 of file doca_log.h.

◆ DOCA_LOG_DBG

#define DOCA_LOG_DBG	(	format,
		...
	)	DOCA_LOG(DOCA_LOG_LEVEL_DEBUG, format, ##__VA_ARGS__)

Generates a DEBUG application log message.

Will generate debug application log. This call affects the performance.

Parameters

format printf(3) arguments, format and variables.

Definition at line 496 of file doca_log.h.

◆ DOCA_LOG_ERR

#define DOCA_LOG_ERR	(	format,
		...
	)	DOCA_LOG(DOCA_LOG_LEVEL_ERROR, format, ##__VA_ARGS__)

Generates an ERROR application log message.

Will generate error application log. This call affects the performance.

Parameters

format printf(3) arguments, format and variables.

Definition at line 466 of file doca_log.h.

◆ DOCA_LOG_INFO

#define DOCA_LOG_INFO	(	format,
		...
	)	DOCA_LOG(DOCA_LOG_LEVEL_INFO, format, ##__VA_ARGS__)

Generates an INFO application log message.

Will generate info application log. This call affects the performance.

Parameters

format printf(3) arguments, format and variables.

Definition at line 486 of file doca_log.h.

◆ DOCA_LOG_REGISTER

#define DOCA_LOG_REGISTER ( source )

Value:

    static int log_source = 0; \
    static void _log_ctor_func(void); \
    __pragma(data_seg(".CRT$XCU")) static void (*__doca_log_initializer)() = _log_ctor_func; \
    __pragma(data_seg()) static void _log_ctor_func(void) \
    { \
        doca_log_register_source(#source, &log_source); \
    }

Registers log source on program start.

Should be used to register the log source. For example:

DOCA_LOG_REGISTER(dpi)

void foo { DOCA_LOG_INFO("Message"); }

Note: The macro also takes care of the dtor() logic on teardown.

Parameters

source A string representing the source name. MSVC CRT Initialization, used for C based Windows applications. CRT$XCU holds pointers to initializers. This is why the macro below contains a pointer to a static function in the data segment. #pragma section(".CRT$XCU", read) guarantees that doca_log_register_source will be called before any compiler generated C++ dynamic initializer

Definition at line 580 of file doca_log.h.

◆ DOCA_LOG_TRC

#define DOCA_LOG_TRC	(	format,
		...
	)

Value:

do { \

} while (0)

Generates a TRACE application log message.

To show the logs define DOCA_LOGGING_ALLOW_TRACE in the compilation variables. This will not effect performance if compiled without DOCA_LOGGING_ALLOW_TRACE, as it will be removed by the compiler.

Will generate trace application log. This call affects the performance.

Parameters

format printf(3) arguments, format and variables.

Definition at line 513 of file doca_log.h.

◆ DOCA_LOG_WARN

#define DOCA_LOG_WARN	(	format,
		...
	)	DOCA_LOG(DOCA_LOG_LEVEL_WARNING, format, ##__VA_ARGS__)

Generates a WARNING application log message.

Will generate warning application log. This call affects the performance.

Parameters

format printf(3) arguments, format and variables.

Definition at line 476 of file doca_log.h.

Typedef Documentation

◆ log_flush_callback

typedef void(* log_flush_callback) (char *buf)

logging backend flush() handler

Definition at line 61 of file doca_log.h.

Enumeration Type Documentation

◆ doca_log_level

enum doca_log_level

log levels, sorted by verbosity level from high to low

Enumerator
DOCA_LOG_LEVEL_DISABLE	Disable log messages
DOCA_LOG_LEVEL_CRIT	Critical log level
DOCA_LOG_LEVEL_ERROR	Error log level
DOCA_LOG_LEVEL_WARNING	Warning log level
DOCA_LOG_LEVEL_INFO	Info log level
DOCA_LOG_LEVEL_DEBUG	Debug log level
DOCA_LOG_LEVEL_TRACE	Trace log level

Definition at line 43 of file doca_log.h.

Function Documentation

◆ doca_log()

DOCA_EXPERIMENTAL doca_error_t doca_log	(	uint32_t	level,
		int	source,
		const char *	fname,
		int	line,
		const char *	func,
		const char *	format,
			...
	)

Generates an application log message.

This should not be used, please prefer using DOCA_LOG.

Parameters

[in]	level	Log level enum DOCA_LOG_LEVEL.
[in]	source	The log source identifier defined by doca_log_register_source.
[in]	fname	The file name this log originated from.
[in]	line	The line number this log originated from.
[in]	func	The function name this log originated from.
[in]	format	printf(3) arguments, format and variables.

Returns: DOCA error code.

◆ doca_log_backend_create_standard()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_create_standard ( void )

Create default, non configurable backend for application messages.

Creates a set of 2 backends for application messages: stdout shall print the range from global lower level up to DOCA_LOG_LEVEL_INFO stderr shall print the range from DOCA_LOG_LEVEL_WARNING up to global upper level

Returns: DOCA error code.

◆ doca_log_backend_create_with_buf()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_create_with_buf	(	char *	buf,
		size_t	capacity,
		log_flush_callback	handler,
		struct doca_log_backend **	backend
	)

Create a logging backend for application messages with a char buffer stream.

Creates a new logging backend for application messages. The logging backend will write each log record at the beginning of this buffer and call the handler.

Parameters

[in]	buf	The char buffer (char *) for the logging backend stream.
[in]	capacity	Maximal amount of chars that could be written to the stream.
[in]	handler	Handler to be called when the log record should be flushed from the stream.
[out]	backend	Logging backend that wraps the given buffer (only valid if no error occurred).

Returns: DOCA error code.

◆ doca_log_backend_create_with_buf_sdk()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_create_with_buf_sdk	(	char *	buf,
		size_t	capacity,
		log_flush_callback	handler,
		struct doca_log_backend **	backend
	)

Create a logging backend with a char buffer stream for SDK messages.

Creates a new logging backend. The logging backend will write each log record at the beginning of this buffer.

Parameters

[in]	buf	The char buffer (char *) for the logging backend stream.
[in]	capacity	Maximal amount of chars that could be written to the stream.
[in]	handler	Handler to be called when the log record should be flushed from the stream.
[out]	backend	Logging backend that wraps the given buffer (only valid if no error occurred).

Returns: DOCA error code.

◆ doca_log_backend_create_with_fd()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_create_with_fd	(	int	fd,
		struct doca_log_backend **	backend
	)

Create a logging backend for application messages with an fd stream.

Creates a new logging backend for application messages.

Parameters

[in]	fd	The file descriptor (int) for the logging backend.
[out]	backend	Logging backend that wraps the given fd (only valid if no error occurred).

Returns: DOCA error code.

◆ doca_log_backend_create_with_fd_sdk()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_create_with_fd_sdk	(	int	fd,
		struct doca_log_backend **	backend
	)

Create a logging backend with an fd stream for SDK messages.

Creates a new logging backend.

Parameters

[in]	fd	The file descriptor (int) for the logging backend.
[out]	backend	Logging backend that wraps the given fd (only valid if no error occurred).

Returns: DOCA error code.

◆ doca_log_backend_create_with_file()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_create_with_file	(	FILE *	fptr,
		struct doca_log_backend **	backend
	)

Create a logging backend for application messages with a FILE* stream.

Creates a new logging backend for application messages.

Parameters

[in]	fptr	The FILE * for the logging backend stream.
[out]	backend	Logging backend that wraps the given fptr (only valid if no error occurred).

Returns: DOCA error code.

◆ doca_log_backend_create_with_file_sdk()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_create_with_file_sdk	(	FILE *	fptr,
		struct doca_log_backend **	backend
	)

Create a logging backend with a FILE* stream for SDK messages.

Creates a new logging backend.

Parameters

[in]	fptr	The FILE * for the logging backend stream.
[out]	backend	Logging backend that wraps the given fptr (only valid if no error occurred).

Returns: DOCA error code.

◆ doca_log_backend_create_with_syslog()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_create_with_syslog	(	const char *	name,
		struct doca_log_backend **	backend
	)

Create a logging backend for application messages with a syslog output.

Creates a new logging backend for application messages.

Parameters

[in]	name	The syslog name for the logging backend.
[out]	backend	Logging backend that exposes the desired syslog functionality (only valid if no error occurred).

Returns: DOCA error code.

◆ doca_log_backend_create_with_syslog_sdk()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_create_with_syslog_sdk	(	const char *	name,
		struct doca_log_backend **	backend
	)

Create a logging backend with a syslog output for SDK messages.

Creates a new logging backend.

Parameters

[in]	name	The syslog name for the logging backend.
[out]	backend	Logging backend that exposes the desired syslog functionality (only valid if no error occurred).

Returns: DOCA error code.

◆ doca_log_backend_set_level_lower_limit()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_set_level_lower_limit	(	struct doca_log_backend *	backend,
		uint32_t	level
	)

Set the lower log level of a specific logging backend for application messages.

Dynamically change the lower log level of the given logging backend, any application message with verbosity level equal or above this level will be shown.

Parameters

[in]	backend	Logging backend to update.
[in]	level	Log level enum DOCA_LOG_LEVEL.

Returns: DOCA error code.

◆ doca_log_backend_set_level_lower_limit_strict()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_set_level_lower_limit_strict ( struct doca_log_backend * backend )

Mark the lower log level limit of a specific logging backend for application messages as strict.

Mark the lower log level limit of a specific logging backend for application messages as strict, preventing it from being lowered by any future log level changes, both global and direct.

Parameters

[in] backend Logging backend to update.

Returns: DOCA error code.

◆ doca_log_backend_set_level_upper_limit()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_set_level_upper_limit	(	struct doca_log_backend *	backend,
		uint32_t	upper_limit
	)

Set the upper log level limit of a specific logging backend for application messages.

Dynamically change the upper log level limit of the given logging backend, any application message with verbosity level above this level will not be shown.

Parameters

[in]	backend	Logging backend to update.
[in]	upper_limit	Log level enum DOCA_LOG_LEVEL.

Returns: DOCA error code.

◆ doca_log_backend_set_level_upper_limit_strict()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_set_level_upper_limit_strict ( struct doca_log_backend * backend )

Mark the upper log level limit of a specific application logging backend for application messages as strict.

Mark the upper log level limit of a specific logging backend for application messages as strict, preventing it from being raised by any future log level changes, both global and direct.

Parameters

[in] backend Logging backend to update.

Returns: DOCA error code.

◆ doca_log_backend_set_sdk_level()

DOCA_EXPERIMENTAL doca_error_t doca_log_backend_set_sdk_level	(	struct doca_log_backend *	backend,
		uint32_t	level
	)

Set the log level limit for SDK logging backends.

Dynamically change the log level limit of the given SDK logging backend, any log under this level will not be shown.

Parameters

[in]	backend	SDK logging backend to update.
[in]	level	Log level enum DOCA_LOG_LEVEL.

Returns: DOCA error code.

◆ doca_log_level_get_global_lower_limit()

DOCA_EXPERIMENTAL uint32_t doca_log_level_get_global_lower_limit ( void )

Get the global log level for application messages.

Dynamically query for the global lower log level, any application message with verbosity level equal or above this level will be shown. The global lower level is used as the initial value when a new logging backend for application messages is created.

Returns: Log level enum DOCA_LOG_LEVEL.

◆ doca_log_level_get_global_sdk_limit()

DOCA_EXPERIMENTAL uint32_t doca_log_level_get_global_sdk_limit ( void )

Get the global log level for SDK messages.

Dynamically query for the global log level, any SDK message with verbosity level equal or above this level will be shown. The global lower level is used as the initial value when a new logging backend for SDK messages is created.

Returns: Log level enum DOCA_LOG_LEVEL.

◆ doca_log_level_get_global_upper_limit()

DOCA_EXPERIMENTAL uint32_t doca_log_level_get_global_upper_limit ( void )

Get the global upper log level for application messages.

Dynamically query for the global upper log level, any application message with verbosity level above this level will not be shown. The global upper level is used as the initial value when a new logging backend for application messages is created.

Returns: Log level enum DOCA_LOG_LEVEL.

◆ doca_log_level_set_global_lower_limit()

DOCA_EXPERIMENTAL doca_error_t doca_log_level_set_global_lower_limit ( uint32_t level )

Set the log level of ALL logging backends for application messages.

Dynamically change the log level of ALL the logging backends for application messages, any application message with verbosity level equal or above this level will be shown. Newly created logging backends for application messages will use this as their default lower log level limit.

Default value of the global lower level limit is DOCA_LOG_LEVEL_INFO.

Parameters

[in] level Log level enum DOCA_LOG_LEVEL.

Returns: DOCA error code.

◆ doca_log_level_set_global_sdk_limit()

DOCA_EXPERIMENTAL doca_error_t doca_log_level_set_global_sdk_limit ( uint32_t level )

Set the log level of ALL logging backends for SDK messages.

Dynamically change the log level of ALL the logging backends for SDK messages, any SDK message with verbosity level equal or above this level will be shown. Newly created logging backends for SDK messages will use this as their default log level limit.

Default value of the level limit is DOCA_LOG_LEVEL_INFO.

Parameters

[in] level Log level enum DOCA_LOG_LEVEL.

Returns: DOCA error code.

◆ doca_log_level_set_global_upper_limit()

DOCA_EXPERIMENTAL doca_error_t doca_log_level_set_global_upper_limit ( uint32_t upper_limit )

Set the log upper level limit of ALL logging backends for application messages.

Dynamically change the log upper level limit of ALL the application logging backends, any application message with verbosity level above this level will not be shown. Newly created logging backends for application messages will use this as their default upper log level limit.

Default value of the global upper level limit is DOCA_LOG_LEVEL_CRIT.

Parameters

[in] upper_limit Log level enum DOCA_LOG_LEVEL.

Returns: DOCA error code.

◆ doca_log_register_source()

DOCA_EXPERIMENTAL doca_error_t doca_log_register_source	(	const char *	source_name,
		int *	source
	)

Register a log source.

Will return the identifier associated with the log source. Log source is used to describe the logging module of the messages in that source file.

Note: Recommended to only be used via DOCA_LOG_REGISTER.

Parameters

[in]	source_name	The string identifying the log source. Should be in an hierarchic form (i.e. DPI::Parser).
[out]	source	Source identifier that was allocated to this log source name (only valid if no error occurred).

Returns: DOCA error code.

◆ doca_log_unregister_source()

DOCA_EXPERIMENTAL doca_error_t doca_log_unregister_source ( int source )

Unregister a log source.

Unregisters a given log source as part of the teardown process of the running program.

Note: Used automatically via DOCA_LOG_REGISTER, not recommended to call it directly.

Parameters

[in] source The source identifier of source to be unregistered, as allocated by doca_log_register_source.

Returns: DOCA error code.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DOCA_LOG

◆ DOCA_LOG_CRIT

◆ DOCA_LOG_DBG

◆ DOCA_LOG_ERR

◆ DOCA_LOG_INFO

◆ DOCA_LOG_REGISTER

◆ DOCA_LOG_TRC

◆ DOCA_LOG_WARN

Typedef Documentation

◆ log_flush_callback

Enumeration Type Documentation

◆ doca_log_level

Function Documentation

◆ doca_log()

◆ doca_log_backend_create_standard()

◆ doca_log_backend_create_with_buf()

◆ doca_log_backend_create_with_buf_sdk()

◆ doca_log_backend_create_with_fd()

◆ doca_log_backend_create_with_fd_sdk()

◆ doca_log_backend_create_with_file()

◆ doca_log_backend_create_with_file_sdk()

◆ doca_log_backend_create_with_syslog()

◆ doca_log_backend_create_with_syslog_sdk()

◆ doca_log_backend_set_level_lower_limit()

◆ doca_log_backend_set_level_lower_limit_strict()

◆ doca_log_backend_set_level_upper_limit()

◆ doca_log_backend_set_level_upper_limit_strict()

◆ doca_log_backend_set_sdk_level()

◆ doca_log_level_get_global_lower_limit()

◆ doca_log_level_get_global_sdk_limit()

◆ doca_log_level_get_global_upper_limit()

◆ doca_log_level_set_global_lower_limit()

◆ doca_log_level_set_global_sdk_limit()

◆ doca_log_level_set_global_upper_limit()

◆ doca_log_register_source()

◆ doca_log_unregister_source()