BTnut System Software: btnut/btnode/include/debug/logging.h File Reference

Log messages consist of a log class, a log level, and the formatted string itself:

Log classes are assigned by the user before compile time. Note that the btnut system itself uses the event logger, thus log classes above LOG_SYSTEM_CLASSES have to be chosen.

level | define      | description
-------------------------------------------------------------
 1    | LOG_ERROR   | Severe errors that impact the system
 2    | LOG_WARNING | Warnings, indicating non-critical failures
 3    | LOG_INFO    | Informational messages
 4    | LOG_DEBUG   | Debug output intended for developers

Static log masking

These macros are available by including the file debug/log_set.h. For a proper setup, the follwing steps have to be taken:

ERROR(text, ...)	-> log_add_msg(LOG_CLASS, LOG_ERROR, text, ...)
WARNING(text, ...)	-> log_add_msg(LOG_CLASS, LOG_WARNING, text, ...)
INFO(text, ...)		-> log_add_msg(LOG_CLASS, LOG_INFO, text, ...)
DEBUG(text, ...)	-> log_add_msg(LOG_CLASS, LOG_DEBUG, text, ...),

Event masking at compile time is now done by defining LOG_LEVEL appropriately: only messages of levels that are greater or equal than the defined LOG_LEVEL are included in the final program code.

This allows to exclude partial or all (define LOG_LEVEL 0) log information from the final program code for saving program memory.

Dynamic log masking

A log mask consists of one bit for each log level and specifies whether the log message shall be written to the log buffer (1) or not (0).

E.g. if you want to prevent debug and info messages of log class 17 being written to the log buffer, call:

By default, the logmask of all log classes is set to LOG_FILTER_ALL, i.e. messages of all levels are written to the log buffer.

Printing

Setup

#include <debug/logging.h>
#include <terminal/btn-terminal.h>
#include <terminal/log-cmds.h>

// log setup
#define LOG_CLASS 18
#define LOG_LEVEL LOG_DEBUG
#include <log_set.h>

int main(void) {
	...

	// initialize event logger
	log_init();
	
	// initialize terminal
	btn_terminal_init(stdout, "[bt-cmd@btnode]$");
	
	// initialize log cmds
	log_cmds_init(stdout);
	
	...
}

#include <sys/types.h>


Data Structures
struct	_log_msg_tail_s
	Definition of the log message trailer. More...
Defines
#define	LOG_ALL_CLASSES 0
	to print out all log classes
#define	LOG_ALL_MESSAGES 0
	to print out all log messages
#define	LOG_DATA_CB void (log_data_cb) (u_char buf, log_msg_tail* tail, void* cb_arg)
	Definition ot the log data callback.
#define	LOG_MAX_CLASSES 32
	Maximal number of log classes.
#define	LOG_MAX_NR_ARGS 6
	Maximal number of optional arguments that can be written to the log buffer.
#define	LOG_MSG_TAIL_SIZE (sizeof(log_msg_tail))
	Size of the trailer that is attached to each log message.
#define	LOG_PSTR(x) x
#define	LOG_SYSTEM_CLASSES 16
	Number of system log classes.
#define	LOG_VERBOSITY_OFF 0
	to turn off log verbosity on all log levels
Log Levels
Definition of the different log levels supported by the event logger.
#define	LOG_DEBUG 4
	Log level: debug.
#define	LOG_ERROR 1
	Log level: error.
#define	LOG_INFO 3
	Log level: info.
#define	LOG_LEVELS 4
	Number of supported log levels.
#define	LOG_WARNING 2
	Log level: warning.
Log level masks
Definition of the log level masks. Each level mask can be used to filter log messages of a specific class on specific levels. Setting log masks can be done: before compile-time to reduce code size (see log_set.h) during runtime to log only specific events (see log_set_logmask, log_add_msg, log_write resp.) during printing to get only relevant messages (see log_get_messages) when registering a log event listener to get only messages of interest (see log_register_event_listener)
#define	LOG_MASK_ALL 0xff
	To mask no levels.
#define	LOG_MASK_DEBUG (1 << (LOG_DEBUG - 1))
	To filter debug statements, i.e. log messages of level LOG_DEBUG.
#define	LOG_MASK_ERROR (1 << (LOG_ERROR - 1))
	To filter errors, i.e. log messages of level LOG_ERROR.
#define	LOG_MASK_INFO (1 << (LOG_INFO - 1))
	To filter infos, i.e. log messages of level LOG_INFO.
#define	LOG_MASK_NONE 0x00
	To mask all levels.
#define	LOG_MASK_WARNING (1 << (LOG_WARNING - 1))
	To filter warnings, i.e. log messages of level LOG_WARNING.
Typedefs
typedef u_char	log_filter_t [LOG_MAX_CLASSES]
	Definition of a log filter.
typedef unsigned int	log_msg_args_t [LOG_MAX_NR_ARGS]
typedef _log_msg_tail_s	log_msg_tail
	Definition of the log message trailer.
Functions
void	log_add_msg (u_char class, u_char level, CONST char *fmt,...)
	Adds a message to the log buffer.
void	log_empty (void)
	Empties the log buffer.
void	log_evt_listener_clear (void)
void	log_evt_listener_pause (void)
short	log_evt_listener_register (LOG_DATA_CB, void *cb_arg, log_filter_t filter)
	Registers an event listener.
void	log_evt_listener_resume (void)
void	log_get (u_short max_nr_msgs, u_char class, u_char mask, LOG_DATA_CB, void *cb_arg)
	Prints the stored log messages using the callback passed.
short	log_get_logmask (u_char class)
void	log_get_messages (u_short id_newer, u_short nr_msgs, LOG_DATA_CB, void *cb_arg)
u_short	log_get_msg_id (void)
	Returns current message log ID.
void	log_init (void)
	Initializes event logging.
void	log_set_logmask (u_char class, u_char mask)
	Sets the logmask of a log class given.
void	log_write (u_char class, u_char level, CONST char *fmt,...)
	Adds a string message to the log buffer.

Define Documentation

#define LOG_DATA_CB void (*log_data_cb) (u_char* buf, log_msg_tail* tail, void* cb_arg)

Definition ot the log data callback.

This callback is called when printing the log (see log_get_messages)

#define LOG_MAX_NR_ARGS 6

Maximal number of optional arguments that can be written to the log buffer.

See also:: log_add_msg

#define LOG_SYSTEM_CLASSES 16

Number of system log classes.

System log classes are used internally by the btnut system. Thus, when using the logging facility for applications, make shure that you use a log class > LOG_SYSTEM_CLASS.

Typedef Documentation

typedef u_char log_filter_t[LOG_MAX_CLASSES]

Definition of a log filter.

A log filter is an array of logmasks, defining a logmask for each log class.

typedef struct _log_msg_tail_s log_msg_tail

Definition of the log message trailer.

This trailer is attached to each log message.

Function Documentation

void log_add_msg	(	u_char	class,
		u_char	level,
		CONST char *	fmt,
			...
	)

Adds a message to the log buffer.

Basically, this function can be used as you would use a 'printf()' function - there are only two restrictions:

no more than the first LOG_MSG_NR_ARGS optional arguments passed are actually written to the log buffer
strings are not written to the log buffer: log_msg_add simply writes the first LOG_MSG_NR_ARGS optional arguments to the log buffer. Thus, if a string is passed, only the pointer to it will be stored - no data is actually copied to the buffer

Note: applications typically do not call this function directely, but instead use the macros defined in log_set.h to enable event masking at compile-time.

Parameters:

	class	Log class the message should be added to
	level	Log level of the message
	fmt	String containing conversion specifications

Note: the function does not check the constraints listed above - this has to be done by the user itself. If you don't feel save with those constraints, use the less-efficient but more save log_write which has no restrictions compared to a standard printf().

Rem: If the string you would like to log is constant, i.e. resides in either static RAM or in the program memory (see LOG_USE_PROG_MEM), calling this function is legal because the pointer to the stored string will still be valid when calling e.g. log_show.

short log_evt_listener_register	(	LOG_DATA_CB	,
		void *	cb_arg,
		log_filter_t	filter
	)

Registers an event listener.

Registers an event listener that is called each time an event has been triggered, i.e. each time a message had been added to the log buffer, the registered callback LOG_DATA_CB is called. Use the log filter filter to listen to specific events only (see log_filter_t, log_get_messages).

Parameters:

	class	LOG_DATA_CB callback to signal
	cb_arg	(optional) callback argument
	filter	log filter to use

void log_get	(	u_short	max_nr_msgs,
		u_char	class,
		u_char	mask,
		LOG_DATA_CB	,
		void *	cb_arg
	)

Prints the stored log messages using the callback passed.

This function reads messages stored in the log buffer and signals the callback LOG_DATA_CB with every message read (see LOG_DATA_CB). It's the callback that defines how a message is printed.

Various filters can be set for getting relevant messages only:

Parameters:

	max_nr_msgs	Maximal number of messages to read. Pass LOG_ALL_MESSAGES for printing all messages.
	class	The log class to print. Pass LOG_CLASSES_ALL for printing all log classes.
	mask	Log levels to print, using a hex-mask for filtering: e.g. pass (LOG_MASK_ERROR & LOG_MASK_WARNING) (i.e. 0x03) to print out error and warning messages only.

E.g. if you'd like to print out all info and debug messages that have been added to the log class 17, call:

log_show(17, LOG_MASK_INFO & LOG_MASK_DEBUG, LOG_ALL_MESSAGES);

or equivalently:

log_show(17, 0x0c, LOG_ALL_MESSAGES);

Parameters:

id_newer

Only messages that have a higher id than the given id_newer are sent. Use 0 to get all messages.

void log_init ( void )

Initializes event logging.

Initializes the log buffer for event logging.

Note: call this function as soon as possible in your systm initialization routine for that events occurring during that phase can be logged properly.

Examples:: mhop_blink/mhop_blink.c.

void log_set_logmask	(	u_char	class,
		u_char	mask
	)

Sets the logmask of a log class given.

Use this function to enable the logging of events of specific levels at runtime: class specifies the log class for which a given logmask mask shall be set.

Parameters:

	class	Log class to filter
	mask	defines the log levels to consider

void log_write	(	u_char	class,
		u_char	level,
		CONST char *	fmt,
			...
	)

Adds a string message to the log buffer.

In contrast to log_add_msg, this function can be use like a "real" 'printf()' function: the format string is parsed and the arguments passed are extracted. The resulting output string is then written directly to the log buffer.

Note: it is recommanded to use this function only for logging strings (see remark below).

To make use of static log masking, applications typically do not call this function directely, but instead use one of the following macros:

#define ERROR_STR(text, ...)
#define WARNING_STR(text, ...)
#define INFO_STR(text, ...)
#define DEBUG_STR(text, ...)

Setup and usage are the same as for the macros explained in the header of this documenation.

Parameters:

	class	Log class the string message should be added to
	level	Log level of the message
	fmt	String containing conversion specifications

Rem: In contrast to log_add_msg, this function is rather slow due to the parsing and the establishment of the output string. Thus, adding a log message to the log buffer using log_write may alter your overall system performance considerably.

btnut/btnode/include/debug/logging.h File Reference

Detailed Description

Event logging

Static log masking

Dynamic log masking

Printing

Setup

Data Structures

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation