/*
 *  Copyright 2003 by Texas Instruments Incorporated.
 *  All rights reserved. Property of Texas Instruments Incorporated.
 *  Restricted rights to use, duplicate or disclose this code are
 *  granted through contract.
 *  
 */
/* "@(#) ReferenceFrameworks 2.10.00.11 04-30-03 (swat-d15)" */
/* 
 *  ======== utl.h ========
 *
 *  Utility module for various debugging operations
 *
 *  The module provides several classes of features, each of which can be
 *  enabled or disabled individually, unless a *level* of debugging is
 *  defined (see below). Each debugging feature is implemented via a macro
 *  (or set of macros) which expands to code if the feature (class) is 
 *  turned on, otherwise it expands to nothing.
 *
 *  Each feature can be turned on or off with its specific flag, by defining
 *  it to be 0 or 1 (individual features are described at the place of their
 *  definitions in this file). Classes are described in detail further in
 *  this file. 
 * 
 *  Instead of defining individual class, the user can also define level
 *  of debugging, which automatically enables certain classes and disables
 *  others (unless they are already enabled or disabled by the user); a level
 *  enables all the classes the previous level enables and one other.
 *  (Also, a combination can be used: level + individual classes explicitly
 *  turned on or off). 
 *
 *  Here is the list of classes, their levels, flag names, and brief 
 *  descriptions:
 *
 *  - error messages                (level: 10, flag: UTL_LOGERROR): 
 *    printing user's error messages to a LOG object via UTL_logError();
 *  - warning messages              (level: 20, flag: UTL_LOGWARNING): 
 *    printing user's warning messages to a LOG object via UTL_logWarning();
 *  - general messages              (level: 30, flag: UTL_LOGMESSAGE):
 *    printing user's general messages to a LOG object via UTL_logMessage();
 *  - debug messages                (level: 40, flag: UTL_LOGDEBUG):
 *    printing user's debug messages to a LOG object via UTL_logDebug();
 *  - assertions                    (level: 50, flag: UTL_ASSERT):
 *    halting execution if the condition in assertion in UTL_assert() fails
 *  - time statistics               (level: 60, flag: UTL_STS):
 *    storing various real-time parameters into STS objects using UTL_sts*()
 *  - algorithm memory usage        (level: 70, flag: UTL_ALGMEM)
 *    reporting heap usage with UTL_showAlgMem(), UTL_showHeapUsage()
 *
 *  Defining UTL_DBGLEVEL automatically defines above flags to be 0 or 1,
 *  unless a flag for the class is already defined (to be 0 or 1).
 *  The levels are:
 *
 *  level  0: all debugging features disabled
 *  level 10: UTL_LOGERROR only is defined
 *  level 20: all in lower levels, plus UTL_LOGWARNING is defined
 *  level 30: all in lower levels, plus UTL_LOGMESSAGE is defined
 *  level 40: all in lower levels, plus UTL_LOGDEBUG   is defined
 *  level 50: all in lower levels, plus UTL_ASSERT     is defined
 *  level 60: all in lower levels, plus UTL_STS        is defined
 *  level 70: all in lower levels, plus UTL_ALGMEM     is defined
 *
 *  Example: compiling with -DUTL_DBGLEVEL=30 will enable classes
 *  error/warning/general messages (meaning macros for those features
 *  will be turned into actual code) and disable all others (meaning
 *  their macros will expand to nothing).
 *  Example 2: compiling with -DUTL_DBGLEVEL=20 and -DUTL_ASSERT=1
 *  will enable error/warning messages and assertions
 *  Example 3: compiling with-DUTL_DBGLEVEL=70 -DUTL_STS=0 
 *  will enable all classes except STS.
 *
 *  Note that usually levels 0-30 would be used in deployment mode, 
 *  and levels 40 and up in development mode).
 *
 *  Error/warning/message/debug logs can use same LOG objects or 
 *  different ones; assert and algmem use the LOG object used by
 *  UTL_logDebug. The choice of logs is made by
 *  
 *  UTL_setLogs( <LOG for errors>,   <LOG for warnings>, 
 *               <LOG for messages>, <LOG for debugging> );
 *
 *  This macro also expands to nothing if none of the classes that use
 *  log objects is enabled.
 */
#ifndef UTL_
#define UTL_

#include <log.h>
#include <sts.h>

#ifdef __cplusplus
extern "C" {
#endif

/* 
 *  If UTL_DBGLEVEL is defined, we define which debugging classes will be
 *  enabled or disabled by defining them here
 */
#ifdef UTL_DBGLEVEL 

    #if UTL_DBGLEVEL >= 10
        #ifndef     UTL_LOGERROR
            #define UTL_LOGERROR   1
        #endif
    #endif

    #if UTL_DBGLEVEL >= 20
        #ifndef     UTL_LOGWARNING
            #define UTL_LOGWARNING 1
        #endif
    #endif

    #if UTL_DBGLEVEL >= 30
        #ifndef     UTL_LOGMESSAGE
            #define UTL_LOGMESSAGE 1
        #endif
    #endif

    #if UTL_DBGLEVEL >= 40
        #ifndef     UTL_LOGDEBUG
            #define UTL_LOGDEBUG   1
        #endif
    #endif

    #if UTL_DBGLEVEL >= 50
        #ifndef     UTL_ASSERT
            #define UTL_ASSERT     1
        #endif
    #endif

    #if UTL_DBGLEVEL >= 60
        #ifndef     UTL_STS
            #define UTL_STS        1
        #endif
    #endif

    #if UTL_DBGLEVEL >= 70
        #ifndef     UTL_ALGMEM
            #define UTL_ALGMEM     1
        #endif
    #endif

#endif  /* UTL_DBGLEVEL */

/* flags which are not defined, are defined here to be 0 */
#ifndef     UTL_LOGERROR
    #define UTL_LOGERROR   0
#endif
#ifndef     UTL_LOGWARNING
    #define UTL_LOGWARNING 0
#endif
#ifndef     UTL_LOGMESSAGE
    #define UTL_LOGMESSAGE 0
#endif
#ifndef     UTL_LOGDEBUG
    #define UTL_LOGDEBUG   0
#endif
#ifndef     UTL_ASSERT
    #define UTL_ASSERT     0
#endif
#ifndef     UTL_STS     
    #define UTL_STS        0
#endif
#ifndef     UTL_ALGMEM  
    #define UTL_ALGMEM     0
#endif



/*
 *  Setting up LOG objects for classes:
 *  We have LOG objects for errors, warnings, messages, 
 *  and debug/assert/algmem. They are all set with UTL_setLogs() call,
 *  defined to be a macro that expands to nothing if none of the classes
 *  are enabled.
 */
#if UTL_LOGERROR == 1 || UTL_LOGWARNING == 1 || UTL_LOGMESSAGE == 1 || \
    UTL_LOGDEBUG == 1 || UTL_ASSERT == 1 || UTL_STS == 1 || UTL_ALGMEM == 1

    extern LOG_Handle UTL_logErrorHandle;
    extern LOG_Handle UTL_logWarningHandle;
    extern LOG_Handle UTL_logMessageHandle;
    extern LOG_Handle UTL_logDebugHandle;

    /*
     *  ========= UTL_setLogs ==========
     *  Names the LOG objects to be used for errors/warnings/messages/debugging;
     *  they do not have to be all different.
     */
    extern Void UTL_setLogs( LOG_Handle logErr, LOG_Handle logWarn, 
                             LOG_Handle logMsg, LOG_Handle logDbg );

#else   /* none of the classes enabled, so the macro is empty */
    #define UTL_setLogs( logErr, logWarn, logMsg, logDbg )
#endif



/*
 *  UTL_log{Error,Warning,Message,Debug}() macros
 *
 *  These four classes of debugging/diagnostics functions perform, if enabled,
 *  a LOG_printf of the given parameters to a default LOG object 
 *  for that class (as determined by UTL_setLogs(), see above)
 *
 *  Syntax: 
 *  UTL_log{Error,Warning,Message,Debug}[0,1,2]( <format>[, <arg1>[, <arg2>]] )
 *
 *  The suffix in the function name (nothing, 0, 1, or 2) determines how many
 *  parameters the formatted output has (none, none, one, or two, respectively).
 *  
 *  Example: UTL_logMessage1( "Current framesize: %d", fs );
 *  If UTL_LOGMESSAGE is defined to be 1 (UTL_DBGLEVEL >= 10), it will
 *  expand to LOG_printf( UTL_logErrorHandle, "Current framesize: %d", fs );
 *  where UTL_logErrorHandle contains the address of the LOG objects for
 *  errors as determined by the first parameter in a call to UTL_setLogs().
 */
#if UTL_LOGERROR == 1
    #define UTL_logError( format )  \
            LOG_printf( UTL_logErrorHandle, (format) )
    #define UTL_logError0( format )  \
            LOG_printf( UTL_logErrorHandle, (format) )
    #define UTL_logError1( format, arg1 )  \
            LOG_printf( UTL_logErrorHandle, (format), (arg1) )
    #define UTL_logError2( format, arg1, arg2 )  \
            LOG_printf( UTL_logErrorHandle, (format), (arg1), (arg2) )
#else   /* UTL_LOGERROR == 0 */
    #define UTL_logError( format )
    #define UTL_logError0( format )
    #define UTL_logError1( format, arg1 )
    #define UTL_logError2( format, arg1, arg2 )
#endif  /* UTL_LOGERROR */

#if UTL_LOGWARNING == 1
    #define UTL_logWarning( format )  \
            LOG_printf( UTL_logWarningHandle, (format) )
    #define UTL_logWarning0( format )  \
            LOG_printf( UTL_logWarningHandle, (format) )
    #define UTL_logWarning1( format, arg1 )  \
            LOG_printf( UTL_logWarningHandle, (format), (arg1) )
    #define UTL_logWarning2( format, arg1, arg2 )  \
            LOG_printf( UTL_logWarningHandle, (format), (arg1), (arg2) )
#else   /* UTL_LOGWARNING == 0 */
    #define UTL_logWarning( format )
    #define UTL_logWarning0( format )
    #define UTL_logWarning1( format, arg1 )
    #define UTL_logWarning2( format, arg1, arg2 )
#endif  /* UTL_LOGWARNING */

#if UTL_LOGMESSAGE == 1
    #define UTL_logMessage( format )  \
            LOG_printf( UTL_logMessageHandle, (format) )
    #define UTL_logMessage0( format )  \
            LOG_printf( UTL_logMessageHandle, (format) )
    #define UTL_logMessage1( format, arg1 )  \
            LOG_printf( UTL_logMessageHandle, (format), (arg1) )
    #define UTL_logMessage2( format, arg1, arg2 )  \
            LOG_printf( UTL_logMessageHandle, (format), (arg1), (arg2) )
#else   /* UTL_LOGMESSAGE == 0 */
    #define UTL_logMessage( format )
    #define UTL_logMessage0( format )
    #define UTL_logMessage1( format, arg1 )
    #define UTL_logMessage2( format, arg1, arg2 )
#endif  /* UTL_MESSAGE */

#if UTL_LOGDEBUG == 1