Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages | Examples
include / sys

tracer.h File Reference

Detailed Description

Trace functions.

Author:
Philipp Blum <blum@tik.ee.ethz.ch>
Date:
22.12.2004


Defines

#define TRACE_MODE_FIRST   0
#define TRACE_MODE_OFF   0
#define TRACE_MODE_CIRCULAR   1
#define TRACE_MODE_ONESHOT   2
#define TRACE_MODE_LAST   2
#define TRACE_MODE_DEFAULT   TRACE_MODE_CIRCULAR
#define TRACE_SIZE_DEFAULT   500
#define TRACE_TAG_FIRST   0
#define TRACE_TAG_CRITICAL_FIRST   0
#define TRACE_TAG_CRITICAL_ENTER   0
#define TRACE_TAG_CRITICAL_EXIT   1
#define TRACE_TAG_CRITICAL_LAST   1
#define TRACE_TAG_THREAD_FIRST   2
#define TRACE_TAG_THREAD_YIELD   2
#define TRACE_TAG_THREAD_SETPRIO   3
#define TRACE_TAG_THREAD_WAIT   4
#define TRACE_TAG_THREAD_SLEEP   5
#define TRACE_TAG_THREAD_LAST   5
#define TRACE_TAG_INTERRUPT_FIRST   6
#define TRACE_TAG_INTERRUPT_ENTER   6
#define TRACE_TAG_INTERRUPT_EXIT   7
#define TRACE_TAG_INTERRUPT_LAST   7
#define TRACE_TAG_START   8
#define TRACE_TAG_STOP   9
#define TRACE_TAG_USER   10
#define TRACE_TAG_LAST   10
#define TRACE_MAX_USER   10
#define TRACE_INT_FIRST   0
#define TRACE_INT_UART0_CTS   0
#define TRACE_INT_UART0_RXCOMPL   1
#define TRACE_INT_UART0_TXEMPTY   2
#define TRACE_INT_UART1_CTS   3
#define TRACE_INT_UART1_RXCOMPL   4
#define TRACE_INT_UART1_TXEMPTY   5
#define TRACE_INT_TIMER0_OVERFL   6
#define TRACE_INT_TIMER1_OVERFL   7
#define TRACE_INT_SUART_TIMER   8
#define TRACE_INT_SUART_RX   9
#define TRACE_INT_LAST   9
#define TRACE_ADD_ITEM(TAG, PC)
#define TRACE_ADD_ITEM_PC(TAG)   TRACE_ADD_ITEM(TAG,NutTraceGetPC())

Typedefs

typedef _t_traceitem t_traceitem
 Item in the trace buffer.

Functions

int NutTraceInit (int size, char mode)
void NutTraceStop (void)
void NutTracePrint (int size)
void NutTraceTerminal (char *arg)
int NutTraceGetPC (void)
void NutTraceClear (void)
void NutTraceMaskPrint (void)
void NutTraceMaskClear (int tag)
void NutTraceMaskSet (int tag)
void NutTraceStatusPrint (void)
int NutTraceRegisterUserTag (int tag, char *tag_string)

Variables

u_int micros_high
 Upper 16 bits of microseconds clock, incremented on timer 1 overflow interrupts.
t_traceitem * trace_items
 Trace buffer, initialized by NutTraceInit.
t_traceitem * trace_current
 Pointer to the current item in the trace buffer.
int trace_head
 Current index in the trace buffer.
int trace_size
 Size of the trace buffer.
char trace_isfull
 Flag indicating whether all items in the trace buffer contain valid information.
char trace_mode
 Current state of the tracing facility.
char trace_mask [TRACE_TAG_LAST+1]
 Mask to individually disable tracing of specific event types.

Define Documentation

#define TRACE_ADD_ITEM (  TAG,
PC   ) 
 

Value:

if ((trace_mode != TRACE_MODE_OFF) &&           \
        (trace_mask[TAG] == 1))                     \
    {                                               \
        asm volatile(                               \
            "in  __tmp_reg__, __SREG__" "\n\t"      \
            "push __tmp_reg__"  "\n\t"              \
            "cli"                       "\n\t"      \
        );                                          \
        trace_current = &trace_items[trace_head++]; \
        trace_current->tag = TAG;                   \
        trace_current->pc = PC;                     \
        trace_current->time_h = micros_high;        \
        trace_current->time_l = TCNT1;              \
        if (trace_head >= trace_size) {             \
            trace_isfull = 1;                       \
            trace_head = 0;                         \
            if (trace_mode == TRACE_MODE_ONESHOT)   \
                trace_mode = TRACE_MODE_OFF;        \
        }                                           \
        asm volatile(                               \
            "pop __tmp_reg__"           "\n\t"      \
            "out __SREG__, __tmp_reg__" "\n\t"      \
        );                                          \
    }
Macro to insert an event in the trace buffer

Parameters:
TAG Type of event
PC Additional information, depending on the type of event

#define TRACE_ADD_ITEM_PC (  TAG   )     TRACE_ADD_ITEM(TAG,NutTraceGetPC())
 

Macro to insert an event in the trace buffer, filling the additional information field with the program counter (PC)

Parameters:
TAG Type of event

Function Documentation

int NutTraceInit (  int  size,
char  mode
) 
 

Initializes the trace buffer and activates tracing. Starts timer 1 for microsecond clock, enables interrupt on overflow

Parameters:
size Number of items in the trace buffer
mode Mode of operation
  • #TRACE_MODE_CIRCULAR Trace buffer wraps around when full
  • #TRACE_MODE_ONESHOT Traceing is stopped when buffer is full
Returns:
int Status

void NutTraceStop (  void   ) 
 

Sets trace_mode to #TRACE_MODE_OFF and thus stop tracing

void NutTracePrint (  int  size  ) 
 

Prints the current contents of the trace buffer

Parameters:
size can be used to limit the number of printed items, if size==0, then all items of the buffer are printed

void NutTraceTerminal (  char *  arg  ) 
 

Commands to manipulate the tracing facility

Parameters:
arg String containing the commands
  • print <size> calls NutPrintTrace
  • oneshot restarts tracing in the oneshot mode
  • circular restarts tracing in the ciruclar mode
  • size <size> restarts tracing in the current mode, using a buffer of length <size>
  • stop stops tracing

int NutTraceGetPC (  void   ) 
 

Returns the program counter (PC) of the instruction following NutGetPC The .map file of the application can be used to find the actual C Code

WARNING: Most likely only works on AVR. Works by inspecting the stack, thus the function breaks when local variables are introduced in NutGetPC

Returns:
int Program counter

void NutTraceClear (  void   ) 
 

Clears the trace buffer, but leaves trace_mode unaltered.

void NutTraceMaskPrint (  void   ) 
 

Prints the current state of trace_mask, which for every type of event (TRACE_TAG_XXX) determines, whether they are inserted in the trace buffer or not.

void NutTraceMaskClear (  int  tag  ) 
 

Disables tracing of a particular event type

Parameters:
tag of event to disable

void NutTraceMaskSet (  int  tag  ) 
 

Enables tracing of a particular event type

Parameters:
tag of event to enable

void NutTraceStatusPrint (  void   ) 
 

Prints current status of tracing facility

int NutTraceRegisterUserTag (  int  tag,
char *  tag_string
) 
 

Registers a user event type

Parameters:
tag of the new event type (e.g. #define TRACE_USER_SEND 0)
tag_string name of the event type used when printing the trace buffer

© 2000-2006 by egnite Software GmbH - visit http://www.ethernut.de/