cyg_trac.h

eCos操作系统源码

CYG_TRACE1DVB( args... ) to CYG_TRACE8DVB()     use "arg=%d", no bool

Function tracing
----------------

CYG_REPORT_FUNCTION()                           default function entry
CYG_REPORT_FUNCNAME( name )                     name the function
CYG_REPORT_FUNCTYPE( exitmsg )                  printf for retval
CYG_REPORT_FUNCNAMETYPE( name, exitmsg )        both

CYG_REPORT_FUNCTIONC()                          as above, but conditional
CYG_REPORT_FUNCNAMEC( name )                    on CYG_REPORT_USER_BOOL
CYG_REPORT_FUNCTYPEC( exitmsg )                 however it is defined
CYG_REPORT_FUNCNAMETYPEC( name, exitmsg )       ...

CYG_REPORT_RETURN()                             void function exit
CYG_REPORT_RETVAL( value )                      returning value

CYG_REPORT_FUNCARGVOID()                        void function entry
CYG_REPORT_FUNCARG1( format, arg )              printf-style
        to
CYG_REPORT_FUNCARG8( format, arg1...arg8 )      printf-style

CYG_REPORT_FUNCARG1X( arg )
        to
CYG_REPORT_FUNCARG8X( arg1...arg8 )             use %08x
CYG_REPORT_FUNCARG1Y...                         use %x
CYG_REPORT_FUNCARG1D...                         use %d

CYG_REPORT_FUNCARG1XV...                        use "arg=%08x"
CYG_REPORT_FUNCARG1YV...                        use "arg=%x"
CYG_REPORT_FUNCARG1DV...                        use "arg=%d"

Other
-----

CYG_TRACE_DUMP()                                dumps kernel state
CYG_TRACE_PRINT()                               prints buffered tracing


---------------------------------------------------------------------------

Internal Documentation
======================

The required functions which are used by the tracing macros are

    externC void
    cyg_tracenomsg( const char *psz_func, const char *psz_file, 
                    cyg_uint32 linenum );
    
    externC void
    cyg_tracemsg( cyg_uint32 what, const char *psz_func, const char *psz_file,
                  cyg_uint32 linenum, const char *psz_msg );
    
    externC void
    cyg_tracemsg2( cyg_uint32 what, 
                   const char *psz_func, const char *psz_file,
                   cyg_uint32 linenum, const char *psz_msg,
                   CYG_ADDRWORD arg0,  CYG_ADDRWORD arg1 );
    // extended in the obvious way for 4,6,8 arguments

These functions should expect psz_func and psz_file to possibly be NULL in
case those facilities are not available in the compilation environment, and
do something safe in such cases.  A NULL message should really be dealt
with safely also, just logging "execution here" info like cyg_tracenomsg().

Discussion of possible underlying implementations
-------------------------------------------------

It is intended that the functions that get called can simply print the info
they are given in as fancy a format as you like, or they could do the
printf-type formatting and log the resulting text in a buffer.  They get
told the type of event (function-entry, function-arguments, function-exit
or plain tracing info) and so can perform fancy indenting, for example, to
make call stack inspection more obvious to humans.  It is also intended
that a more compact logging arrangement be possible, for example one which
records, in 32-bit words (CYG_ADDRWORDs), the addresses of the file,
function and msg strings, the line number and the arguments.  This has the
implication that the msg string should not be constructed dynamically but
be static ie. a plain quoted C string.  The number of arguments also must
be recorded, and if it is chosen to save string arguments in the buffer
rather than just their addresses (which could be invalid by the time the
logged information is processed) some flagging of which arguments are
strings must be provided.  The system could also be extended to deal with
floats of whichever size fir in a CYG_ADDRWORD; these would probably
require special treatment also.  With these considerations in mind, the
maximum number of parameters in a single trace message has been set to 8,
so that a byte bitset could be used to indicate which arguments are
strings, another for those which are floats, and the count of arguments
also fits in a byte as number or a bitset.


****************************************************************************/

#include <pkgconf/infra.h>

#include <cyg/infra/cyg_ass.h>

// -------------------------------------------------------------------------
// CYGDBG_INFRA_DEBUG_FUNCTION_PSEUDOMACRO is dealt with in cyg_ass.h.
// -------------------------------------------------------------------------

#ifdef CYGDBG_USE_TRACING

// -------------------------------------------------------------------------
// We define macros and appropriate prototypes for the trace/fail
// system.  These are:
//      CYG_TRACE0..8     - trace if boolean
//      CYG_TRACEPROC     - default no comment proc entry
//      CYG_TRACEPROCOUT  - default no comment proc exit
//      CYG_TRACE_DUMP    - outputs a form of "core dump", including the state
//                          of the kernel scheduler, threads, etc.
//      CYG_TRACE_PRINT   - Forces manual output of any trace info that has
//                          been buffered up.

// these are executed to deal with tracing - breakpoint?

externC void
cyg_tracenomsg( const char *psz_func, const char *psz_file, cyg_uint32 linenum );

externC void
cyg_trace_dump(void);

#define CYG_TRACE_DUMP() cyg_trace_dump()

#ifdef CYGDBG_INFRA_DEBUG_TRACE_ASSERT_BUFFER

externC void
cyg_trace_print(void);

#define CYG_TRACE_PRINT() cyg_trace_print()

#else
#define CYG_TRACE_PRINT() CYG_EMPTY_STATEMENT
#endif

// provide every other one of these as a space/caller bloat compromise.

# ifdef CYGDBG_INFRA_DEBUG_TRACE_MESSAGE

enum cyg_trace_what{
    cyg_trace_trace = 0,
    cyg_trace_enter,
    cyg_trace_args,
    cyg_trace_return,
//    cyg_trace_,
//    cyg_trace_,
};

externC void
cyg_tracemsg( cyg_uint32 what, 
              const char *psz_func, const char *psz_file, cyg_uint32 linenum, 
              const char *psz_msg );

externC void
cyg_tracemsg2( cyg_uint32 what, 
               const char *psz_func, const char *psz_file, cyg_uint32 linenum, 
               const char *psz_msg,
               CYG_ADDRWORD arg0,  CYG_ADDRWORD arg1 );
externC void
cyg_tracemsg4( cyg_uint32 what, 
               const char *psz_func, const char *psz_file, cyg_uint32 linenum, 
               const char *psz_msg,
               CYG_ADDRWORD arg0,  CYG_ADDRWORD arg1,
               CYG_ADDRWORD arg2,  CYG_ADDRWORD arg3 );
externC void
cyg_tracemsg6( cyg_uint32 what, 
               const char *psz_func, const char *psz_file, cyg_uint32 linenum, 
               const char *psz_msg,
               CYG_ADDRWORD arg0,  CYG_ADDRWORD arg1,
               CYG_ADDRWORD arg2,  CYG_ADDRWORD arg3,
               CYG_ADDRWORD arg4,  CYG_ADDRWORD arg5 );
externC void
cyg_tracemsg8( cyg_uint32 what, 
               const char *psz_func, const char *psz_file, cyg_uint32 linenum, 
               const char *psz_msg,
               CYG_ADDRWORD arg0,  CYG_ADDRWORD arg1,
               CYG_ADDRWORD arg2,  CYG_ADDRWORD arg3,
               CYG_ADDRWORD arg4,  CYG_ADDRWORD arg5,
               CYG_ADDRWORD arg6,  CYG_ADDRWORD arg7 );

#endif // CYGDBG_INFRA_DEBUG_TRACE_MESSAGE

// -------------------------------------------------------------------------

# ifdef CYGDBG_INFRA_DEBUG_TRACE_MESSAGE

#  define CYG_TRACE_docall0( _msg_ )                                    \
    cyg_tracemsg( cyg_trace_trace,                                      \
                  __PRETTY_FUNCTION__, __FILE__, __LINE__, _msg_ );

#  define CYG_TRACE_docall2( _msg_, _arg0_, _arg1_ )                    \
    cyg_tracemsg2( cyg_trace_trace,                                     \
                   __PRETTY_FUNCTION__, __FILE__, __LINE__, _msg_,      \
                 (CYG_ADDRWORD)_arg0_, (CYG_ADDRWORD)_arg1_ );

#  define CYG_TRACE_docall4( _msg_, _arg0_, _arg1_ , _arg2_, _arg3_  )  \
    cyg_tracemsg4( cyg_trace_trace,                                     \
                   __PRETTY_FUNCTION__, __FILE__, __LINE__, _msg_,      \
                 (CYG_ADDRWORD)_arg0_, (CYG_ADDRWORD)_arg1_,            \
                 (CYG_ADDRWORD)_arg2_, (CYG_ADDRWORD)_arg3_ );

#  define CYG_TRACE_docall6( _msg_, _arg0_, _arg1_ , _arg2_, _arg3_,    \
                                    _arg4_, _arg5_                   )  \
    cyg_tracemsg6( cyg_trace_trace,                                     \
                   __PRETTY_FUNCTION__, __FILE__, __LINE__, _msg_,      \
                 (CYG_ADDRWORD)_arg0_, (CYG_ADDRWORD)_arg1_,            \
                 (CYG_ADDRWORD)_arg2_, (CYG_ADDRWORD)_arg3_,            \
                 (CYG_ADDRWORD)_arg4_, (CYG_ADDRWORD)_arg5_ );

#  define CYG_TRACE_docall8( _msg_, _arg0_, _arg1_ , _arg2_, _arg3_,    \
                                    _arg4_,  _arg5_, _arg6_, _arg7_ )   \
    cyg_tracemsg8( cyg_trace_trace,                                     \
                   __PRETTY_FUNCTION__, __FILE__, __LINE__, _msg_,      \
                 (CYG_ADDRWORD)_arg0_, (CYG_ADDRWORD)_arg1_,            \
                 (CYG_ADDRWORD)_arg2_, (CYG_ADDRWORD)_arg3_,            \
                 (CYG_ADDRWORD)_arg4_, (CYG_ADDRWORD)_arg5_,            \
                 (CYG_ADDRWORD)_arg6_, (CYG_ADDRWORD)_arg7_ );

# else // do not CYGDBG_INFRA_DEBUG_TRACE_MESSAGE

#  define CYG_TRACE_docall0( _msg_ )                                    \
    cyg_tracenomsg( __PRETTY_FUNCTION__, __FILE__, __LINE__ );

#  define CYG_TRACE_docall2( _msg_, _arg0_, _arg1_ )                    \
    cyg_tracenomsg( __PRETTY_FUNCTION__, __FILE__, __LINE__ );

#  define CYG_TRACE_docall4( _msg_, _arg0_, _arg1_ , _arg2_, _arg3_  )  \
    cyg_tracenomsg( __PRETTY_FUNCTION__, __FILE__, __LINE__ );

#  define CYG_TRACE_docall6( _msg_, _arg0_, _arg1_ , _arg2_, _arg3_,    \
                                    _arg4_, _arg5_                   )  \
    cyg_tracenomsg( __PRETTY_FUNCTION__, __FILE__, __LINE__ );

#  define CYG_TRACE_docall8( _msg_, _arg0_, _arg1_, _arg2_, _arg3_,     \
                                    _arg4_, _arg5_, _arg6_, _arg7_   )  \
    cyg_tracenomsg( __PRETTY_FUNCTION__, __FILE__, __LINE__ );

#endif

// -------------------------------------------------------------------------
// Conditioned trace; if the condition is false, fail.

#define CYG_TRACE0( _bool_, _msg_ )                             \
    CYG_MACRO_START                                             \
    if ( ( _bool_ ) )                                           \
        CYG_TRACE_docall0( _msg_ );                             \
    CYG_MACRO_END

#define CYG_TRACE1( _bool_, _msg_, a )                          \
    CYG_MACRO_START                                             \
    if ( ( _bool_ ) )                                           \
        CYG_TRACE_docall2( _msg_, a, 0 );                       \
    CYG_MACRO_END
 
#define CYG_TRACE2( _bool_, _msg_, a, b )                       \
    CYG_MACRO_START                                             \
    if ( ( _bool_ ) )                                           \
        CYG_TRACE_docall2( _msg_, a, b );                       \
    CYG_MACRO_END

#define CYG_TRACE3( _bool_, _msg_, a, b, c )                    \
    CYG_MACRO_START                                             \
    if ( ( _bool_ ) )                                           \
        CYG_TRACE_docall4( _msg_, a, b, c, 0 );                 \
    CYG_MACRO_END
 
#define CYG_TRACE4( _bool_, _msg_, a, b, c, d )                 \
    CYG_MACRO_START                                             \
    if ( ( _bool_ ) )                                           \
        CYG_TRACE_docall4( _msg_, a, b, c, d );                 \
    CYG_MACRO_END

#define CYG_TRACE5( _bool_, _msg_, a, b, c, d, e )              \
    CYG_MACRO_START                                             \
    if ( ( _bool_ ) )                                           \
        CYG_TRACE_docall6( _msg_, a, b, c, d, e, 0 );           \
    CYG_MACRO_END
 
#define CYG_TRACE6( _bool_, _msg_, a, b, c, d, e, f )           \
    CYG_MACRO_START                                             \
    if ( ( _bool_ ) )                                           \
        CYG_TRACE_docall6( _msg_, a, b, c, d, e, f );           \
    CYG_MACRO_END

#define CYG_TRACE7( _bool_, _msg_, a, b, c, d, e, f, g )        \
    CYG_MACRO_START                                             \
    if ( ( _bool_ ) )                                           \
        CYG_TRACE_docall8( _msg_, a, b, c, d, e, f, g, 0 );     \
    CYG_MACRO_END
 
#define CYG_TRACE8( _bool_, _msg_, a, b, c, d, e, f, g, h )     \
    CYG_MACRO_START                                             \
    if ( ( _bool_ ) )                                           \
        CYG_TRACE_docall8( _msg_, a, b, c, d, e, f, g, h );     \