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


Detailed Description

API for event logging.

Author:
Kevin Martin <kevmarti@tik.ee.ethz.ch>
Date:
2006/03/23

Event logging

Logging of events can be done by writing log messages to the log buffer: To log a specific event occuring in your application call log_add_msg which takes a formatted string and writes it to the log buffer together with the local time log_add_msg was called.

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.

Currently, four (LOG_LEVELS) different log levels are supported:

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

Static log masks are used to define which log classes and levels are actually compiled and included into the final program code in order that the size of program memory needed for event logging can be controlled. To make use of static log masking, applications typically do not call log_add_msg directely, but instead use one of the macros below:
#define ERROR(text, ...)
#define WARNING(text, ...)
#define INFO(text, ...)
#define DEBUG(text, ...)

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

E.g.

#define LOG_CLASS 17
#define LOG_LEVEL 4
#include <log_set.h>

The macros defined above are then extracted in the following way:

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.

E.g. by setting up logging for log class 17 in the following way:

#define LOG_CLASS 17
#define LOG_LEVEL LOG_WARNING
#include <log_set.h>
only messages of level LOG_ERROR and LOG_WARNING 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

During runtime it is possible to set the logmask, which defines whether a message is written to the log buffer or not. The logmask can be set for each log class individually using log_set_logmask.

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:

log_set_logmask(17, LOG_MASK_ERROR & LOG_MASK_WARNING);
or equivalently:
log_set_logmask(17, 0x03);

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

The logged messages can be printed to the terminal by including the file include/terminal/log-cmds.h

See also:
log-cmds.h

Setup

A proper setup for using LOG_CLASS 18 for event logging, as well as the terminal to get access to the logger is given below:
#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:

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.


Generated on Wed Apr 29 11:12:29 2009 for BTnut System Software by doxygen 1.5.1