lib/picodbg.h

/*
 * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 *
 * @file picodbg.h
 *
 * Provides functions and macros to debug the Pico system and to trace
 * the execution of its code.
 *
 * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland
 * All rights reserved.
 *
 * History:
 * - 2009-04-20 -- initial version
 */

/**
 * @addtogroup picodbg
 * ---------------------------------------------------\n
 * <b> Pico Debug Support </b>\n
 * ---------------------------------------------------\n
 * GENERAL REMARKS
 * ---------------
 * This module provides a set of macros to help debug the Pico system.
 * The usage of macros allows for completely removing debug code from
 * the binaries delivered to customers. To enable diagnostic output
 * the preprocessor symbol PICO_DEBUG has to be defined.
 *
 * By using global variables (to store the current log level etc.)
 * this module violates a basic Pico design principle!
 *
 * Justification:\n
 * - going without global data would reduce the functionality
 *   of this module considerably (e.g., log level could not be
 *   changed at runtime etc.)
 * - at the moment, the only known system interdicting global
 *   variables is Symbian; but even there global variables are
 *   possible by using thread-local storage
 * - allocating global data on the heap would require to pass
 *   a handle to this memory block to all routines of this
 *   module which in turn implies that _every_ function in the
 *   Pico system would require a pointer to some global data;
 *   obviously, this would be very awkward
 *
 * Furthermore, this module uses the non-standardized but handy
 * __FUNCTION__ macro. It expands to the name of the enclosing
 * function. For compilers not supporting this macro simply
 * define __FUNCTION__ as an empty string.
 *
 *
 * INITIALIZATION/TERMINATION\n
 * --------------------------\n
 * Before using any debug macros, this module has to be initialized
 * by calling PICODBG_INITIALIZE(). If the routines are not needed
 * anymore, PICODBG_TERMINATE() has to be called to terminate the
 * module (e.g., to close the log file).
 *
 *
 * TRACING\n
 * -------\n
 * Each tracing message is associated with a log level which describes
 * its severity. The following levels are supported:
 * - Trace - Very detailed log messages, potentially of a high
 *            frequency and volume
 * - Debug - Less detailed and/or less frequent debugging messages
 * - Info  - Informational messages
 * - Warn  - Warnings which don't appear to the Pico user
 * - Error - Error messages
 *
 * Tracing messages can use the well-known printf format specification.
 * But because variadic macros (macros with a variable no. arguments)
 * are not commonly supported by compilers a little trick is used
 * which requires the format string and its arguments to be enclosed
 * in double parenthesis:
 *
 * - PICODBG_INFO(("hello, world!"));
 * - PICODBG_TRACE(("argc=%d", argc));
 *    ...
 *
 * Each tracing message is expected to be a single line of text. Some
 * contextual information (e.g., log level, time and date, source file
 * and line number) and a newline are automatically added. The output
 * format can be customized by a call to PICODBG_SET_OUTPUT_FORMAT().
 *
 * Sample output:
 *    - *** info|2008-04-03|14:51:36|dbgdemo.c(15)|hello world
 *    - *** trace|2008-04-03|14:51:36|dbgdemo.c(16)|argc=2
 *    - ...
 *
 * To compose a tracing message line consisting of, e.g. the elements
 * of an array, on the Info level two additional macros shown in the
 * following example are provided:
 *
 *    PICODBG_INFO_CTX();\n
 *    for (i = 0; i < len; i++)\n
 *        ...some calc with arr and i\n
 *        PICODBG_INFO_MSG((" %d", arr[i]));\n
 *    }\n
 *    PICODBG_INFO_MSG(("\n"));\n
 *
 * Colored output of tracing messages helps to capture severe problems
 * quickly. This feature is supported on the Windows platform and on
 * platforms supporting ANSI escape codes. PICODBG_ENABLE_COLORS() lets
 * you turn on and off colored output.
 *
 *
 * FILTERING\n
 * ---------\n
 * By calling PICODBG_SET_LOG_LEVEL() the log level may be changed at
 * any time to increase/decrease the amount of debugging output.
 *
 * By calling PICODBG_SET_LOG_FILTERFN() the log filter may be changed
 * at any time to change the source file name being used as filter for
 * log messages (ie. only tracing info of the specified file will be
 * logged). To disable the file name based filter set the filter file
 * name to an empty string.
 *
 * Future version of this module might provide further filtering
 * possibilities (e.g., filtering based on function names * etc.).
 *
 *
 * LOGGING\n
 * -------\n
 * By default, tracing messages are output to the console (stderr).
 * This allows for separating diagnostic output from other console
 * output to stdout. In addition, tracing messages may be saved to
 * a file by calling PICODBG_SET_LOG_FILE().
 * Currently, file output is the only additional output target; but
 * on embedded systems, more output targets may be required (e.g.,
 * sending output to a serial port or over the network).
 *
 *
 * ASSERTIONS\n
 * ----------\n
 * To support the 'design/programming by contract' paradigm, this
 * module also provides assertions. PICODBG_ASSERT(expr) evualuates
 * an expression and, when the result is false, prints a diagnostic
 * message and aborts the program.
 *
 *
 * FUTURE EXTENSIONS\n
 * -----------------\n
 * - advanced tracing functions to dump complex data
 * - debug memory allocation that can be used to assist in
 *   finding memory problems
 */


#if !defined(__PICODBG_H__)
#define __PICODBG_H__

#ifdef __cplusplus
extern "C" {
#endif
#if 0
}
#endif


/* Not all compilers support the __FUNCTION__ macro */
#if !defined(__FUNCTION__) && !defined(__GNUC__)
#define __FUNCTION__ ""
#endif


/* Log levels sorted by severity */
#define PICODBG_LOG_LEVEL_ERROR     1
#define PICODBG_LOG_LEVEL_WARN      2
#define PICODBG_LOG_LEVEL_INFO      3
#define PICODBG_LOG_LEVEL_DEBUG     4
#define PICODBG_LOG_LEVEL_TRACE     5

/* Output format flags */
#define PICODBG_SHOW_LEVEL          0x0001
#define PICODBG_SHOW_DATE           0x0002
#define PICODBG_SHOW_TIME           0x0004
#define PICODBG_SHOW_SRCNAME        0x0008
#define PICODBG_SHOW_SRCLINE        0x0010
#define PICODBG_SHOW_SRCALL         (PICODBG_SHOW_SRCNAME | PICODBG_SHOW_SRCLINE)
#define PICODBG_SHOW_FUNCTION       0x0020
#define PICODBG_SHOW_POS            (PICODBG_SHOW_SRCALL | PICODBG_SHOW_FUNCTION)

/* definition of PICO_DEBUG enables debugging code */
#if defined(PICO_DEBUG)

#define PICODBG_INITIALIZE(level) \
    picodbg_initialize(level)

#define PICODBG_TERMINATE() \
    picodbg_terminate()

#define PICODBG_SET_LOG_LEVEL(level) \
    picodbg_setLogLevel(level)

#define PICODBG_SET_LOG_FILTERFN(name) \
    picodbg_setLogFilterFN(name)

#define PICODBG_SET_LOG_FILE(name) \
    picodbg_setLogFile(name)

#define PICODBG_ENABLE_COLORS(flag) \
    picodbg_enableColors(flag)

#define PICODBG_SET_OUTPUT_FORMAT(format) \
    picodbg_setOutputFormat(format)


#define PICODBG_ASSERT(expr) \
    for (;!(expr);picodbg_assert(__FILE__, __LINE__, __FUNCTION__, #expr))

#define PICODBG_ASSERT_RANGE(val, min, max) \
    PICODBG_ASSERT(((val) >= (min)) && ((val) <= (max)))


#define PICODBG_LOG(level, msg) \
    picodbg_log(level, 1,  __FILE__, __LINE__, __FUNCTION__, picodbg_varargs msg)

#define PICODBG_ERROR(msg) \
    PICODBG_LOG(PICODBG_LOG_LEVEL_ERROR, msg)

#define PICODBG_WARN(msg) \
    PICODBG_LOG(PICODBG_LOG_LEVEL_WARN, msg)

#define PICODBG_INFO(msg) \
    PICODBG_LOG(PICODBG_LOG_LEVEL_INFO, msg)

#define PICODBG_DEBUG(msg) \
    PICODBG_LOG(PICODBG_LOG_LEVEL_DEBUG, msg)

#define PICODBG_TRACE(msg) \
    PICODBG_LOG(PICODBG_LOG_LEVEL_TRACE, msg)


#define PICODBG_INFO_CTX() \
    picodbg_log(PICODBG_LOG_LEVEL_INFO, 0, __FILE__, __LINE__, __FUNCTION__, "")

#define PICODBG_INFO_MSG(msg) \
    picodbg_log_msg(PICODBG_LOG_LEVEL_INFO, __FILE__, picodbg_varargs msg)

#define PICODBG_INFO_MSG_F(filterfn, msg) \
    picodbg_log_msg(PICODBG_LOG_LEVEL_INFO, (const char *)filterfn, picodbg_varargs msg)



/* helper routines; should NOT be used directly! */

void picodbg_initialize(int level);
void picodbg_terminate();

void picodbg_setLogLevel(int level);
void picodbg_setLogFilterFN(const char *name);
void picodbg_setLogFile(const char *name);
void picodbg_enableColors(int flag);
void picodbg_setOutputFormat(unsigned int format);

const char *picodbg_varargs(const char *format, ...);

void picodbg_log(int level, int donewline, const char *file, int line,
                 const char *func, const char *msg);
void picodbg_assert(const char *file, int line, const char *func,
                    const char *expr);

void picodbg_log_msg(int level, const char *file, const char *msg);


#else  /* release version; omit debugging code */

#define PICODBG_INITIALIZE(level)
#define PICODBG_TERMINATE()
#define PICODBG_SET_LOG_LEVEL(level)
#define PICODBG_SET_LOG_FILTERFN(name)
#define PICODBG_SET_LOG_FILE(name)
#define PICODBG_ENABLE_COLORS(flag)
#define PICODBG_SET_OUTPUT_FORMAT(format)

#define PICODBG_ASSERT(expr)
#define PICODBG_ASSERT_RANGE(val, min, max)

#define PICODBG_LOG(level, msg)
#define PICODBG_ERROR(msg)
#define PICODBG_WARN(msg)
#define PICODBG_INFO(msg)
#define PICODBG_DEBUG(msg)
#define PICODBG_TRACE(msg)

#define PICODBG_INFO_CTX()
#define PICODBG_INFO_MSG(msg)
#define PICODBG_INFO_MSG_F(filterfn, msg)


#endif /* defined(PICO_DEBUG) */

#ifdef __cplusplus
}
#endif


#endif /* !defined(__PICODBG_H__) */