Trace Hook Macros

Description

Key points of interest within the FreeRTOS source code contain empty macros that an application can re-define for the purpose of providing application specific trace facilities. The application need only implement those macros of particular interest - with unused macros remaining empty and therefore not impacting the application timing.

Examples

• Setting a digital output to indicate which task is executing - allowing a logic analyzer to be used to view and record the task execution sequence and timing.
• Similarly - setting an analogue output to a voltage that represents which task is executing - allowing an oscilloscope to be used to view and record the task execution sequence and timing.
• Logging task execution sequences, task timing, RTOS kernel events and API calls for offline analysis.
• Integrating RTOS kernel events into third party debuggers.

Example 1

    /* First task sets its tag value to 1. */
void vTask1( void *pvParameters )
{
    /* This task is going to be represented by a voltage scale of 1. */
    vTaskSetApplicationTaskTag( NULL, ( void * ) 1 );

    for( ;; )
    {
        /* Task code goes here. */
    }
}
/*************************************************/

/* Second task sets its tag value to 2. */
void vTask2( void *pvParameters )
{
    /* This task is going to be represented by a voltage scale of 2. */
    vTaskSetApplicationTaskTag( NULL, ( void * ) 2 );

    for( ;; )
    {
        /* Task code goes here. */
    }
}
/*************************************************/

/* Define the traceTASK_SWITCHED_IN() macro to output the voltage associated
with the task being selected to run on port 0. */
#define traceTASK_SWITCHED_IN() vSetAnalogueOutput( 0, (int)pxCurrentTCB->pxTaskTag )

Example 2

/* traceBLOCKING_ON_QUEUE_RECEIVE() is just one of the macros that can be used to
record why a context switch is about to occur. */
#define traceBLOCKING_ON_QUEUE_RECEIVE(xQueue)      
    ulSwitchReason = reasonBLOCKING_ON_QUEUE_READ;

/* log_event() is an application defined function that logs which tasks ran when,
and why. */
#define traceTASK_SWITCHED_OUT()                    
    log_event( pxCurrentTCB, ulSwitchReason );

Defining

Macro definitions must occur before the inclusion of FreeRTOS.h. The easiest place to define trace macros is at the bottom of FreeRTOSConfig.h, or in a separate header file that is included from the bottom of FreeRTOSConfig.h.

The table below describes the available macros. The macro parameters are used to indicate which task, queue, semaphore or mutex was associated with the event being recorded.