Add Trace Hook Macros to all API calls (#786)

This pull-request adds out-of-the-box support for different tracing
tools. New trace hook macros have been added for all public API
functions, one for each function entry and one for each exit. There are
no functional changes, as the macros are by default empty.

For more information see following forum post:
https://forums.freertos.org/t/add-tracing-functionality-for-all-api-calls/18007.

Author: Techcore123

croutine.c

@@ -107,6 +107,8 @@
         BaseType_t xReturn;
         CRCB_t * pxCoRoutine;
 
+        traceENTER_xCoRoutineCreate( pxCoRoutineCode, uxPriority, uxIndex );
+
         /* Allocate the memory that will store the co-routine control block. */
         pxCoRoutine = ( CRCB_t * ) pvPortMalloc( sizeof( CRCB_t ) );
 
@@ -156,6 +158,8 @@
             xReturn = errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY;
         }
 
+        traceRETURN_xCoRoutineCreate( xReturn );
+
         return xReturn;
     }
 /*-----------------------------------------------------------*/
@@ -165,6 +169,8 @@
     {
         TickType_t xTimeToWake;
 
+        traceENTER_vCoRoutineAddToDelayedList( xTicksToDelay, pxEventList );
+
         /* Calculate the time to wake - this may overflow but this is
          * not a problem. */
         xTimeToWake = xCoRoutineTickCount + xTicksToDelay;
@@ -196,6 +202,8 @@
              * function must be called with interrupts disabled. */
             vListInsert( pxEventList, &( pxCurrentCoRoutine->xEventListItem ) );
         }
+
+        traceRETURN_vCoRoutineAddToDelayedList();
     }
 /*-----------------------------------------------------------*/
 
@@ -283,6 +291,8 @@
 
     void vCoRoutineSchedule( void )
     {
+        traceENTER_vCoRoutineSchedule();
+
         /* Only run a co-routine after prvInitialiseCoRoutineLists() has been
          * called.  prvInitialiseCoRoutineLists() is called automatically when a
          * co-routine is created. */
@@ -313,6 +323,8 @@
             /* Call the co-routine. */
             ( pxCurrentCoRoutine->pxCoRoutineFunction )( pxCurrentCoRoutine, pxCurrentCoRoutine->uxIndex );
         }
+
+        traceRETURN_vCoRoutineSchedule();
     }
 /*-----------------------------------------------------------*/
 
@@ -341,6 +353,8 @@
         CRCB_t * pxUnblockedCRCB;
         BaseType_t xReturn;
 
+        traceENTER_xCoRoutineRemoveFromEventList( pxEventList );
+
         /* This function is called from within an interrupt.  It can only access
          * event lists and the pending ready list.  This function assumes that a
          * check has already been made to ensure pxEventList is not empty. */
@@ -357,6 +371,8 @@
             xReturn = pdFALSE;
         }
 
+        traceRETURN_xCoRoutineRemoveFromEventList( xReturn );
+
         return xReturn;
     }
 

event_groups.c

@@ -82,6 +82,8 @@ static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits,
     {
         EventGroup_t * pxEventBits;
 
+        traceENTER_xEventGroupCreateStatic( pxEventGroupBuffer );
+
         /* A StaticEventGroup_t object must be provided. */
         configASSERT( pxEventGroupBuffer );
 
@@ -122,6 +124,8 @@ static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits,
             traceEVENT_GROUP_CREATE_FAILED();
         }
 
+        traceRETURN_xEventGroupCreateStatic( pxEventBits );
+
         return pxEventBits;
     }
 
@@ -134,6 +138,8 @@ static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits,
     {
         EventGroup_t * pxEventBits;
 
+        traceENTER_xEventGroupCreate();
+
         /* Allocate the event group.  Justification for MISRA deviation as
          * follows:  pvPortMalloc() always ensures returned memory blocks are
          * aligned per the requirements of the MCU stack.  In this case
@@ -170,6 +176,8 @@ static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits,
             traceEVENT_GROUP_CREATE_FAILED(); /*lint !e9063 Else branch only exists to allow tracing and does not generate code if trace macros are not defined. */
         }
 
+        traceRETURN_xEventGroupCreate( pxEventBits );
+
         return pxEventBits;
     }
 
@@ -186,6 +194,8 @@ EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
     BaseType_t xAlreadyYielded;
     BaseType_t xTimeoutOccurred = pdFALSE;
 
+    traceENTER_xEventGroupSync( xEventGroup, uxBitsToSet, uxBitsToWaitFor, xTicksToWait );
+
     configASSERT( ( uxBitsToWaitFor & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
     configASSERT( uxBitsToWaitFor != 0 );
     #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
@@ -303,6 +313,8 @@ EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
     /* Prevent compiler warnings when trace macros are not used. */
     ( void ) xTimeoutOccurred;
 
+    traceRETURN_xEventGroupSync( uxReturn );
+
     return uxReturn;
 }
 /*-----------------------------------------------------------*/
@@ -318,6 +330,8 @@ EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
     BaseType_t xWaitConditionMet, xAlreadyYielded;
     BaseType_t xTimeoutOccurred = pdFALSE;
 
+    traceENTER_xEventGroupWaitBits( xEventGroup, uxBitsToWaitFor, xClearOnExit, xWaitForAllBits, xTicksToWait );
+
     /* Check the user is not attempting to wait on the bits used by the kernel
      * itself, and that at least one bit is being requested. */
     configASSERT( xEventGroup );
@@ -467,6 +481,8 @@ EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
     /* Prevent compiler warnings when trace macros are not used. */
     ( void ) xTimeoutOccurred;
 
+    traceRETURN_xEventGroupWaitBits( uxReturn );
+
     return uxReturn;
 }
 /*-----------------------------------------------------------*/
@@ -477,6 +493,8 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup,
     EventGroup_t * pxEventBits = xEventGroup;
     EventBits_t uxReturn;
 
+    traceENTER_xEventGroupClearBits( xEventGroup, uxBitsToClear );
+
     /* Check the user is not attempting to clear the bits used by the kernel
      * itself. */
     configASSERT( xEventGroup );
@@ -495,6 +513,8 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup,
     }
     taskEXIT_CRITICAL();
 
+    traceRETURN_xEventGroupClearBits( uxReturn );
+
     return uxReturn;
 }
 /*-----------------------------------------------------------*/
@@ -506,9 +526,13 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup,
     {
         BaseType_t xReturn;
 
+        traceENTER_xEventGroupClearBitsFromISR( xEventGroup, uxBitsToClear );
+
         traceEVENT_GROUP_CLEAR_BITS_FROM_ISR( xEventGroup, uxBitsToClear );
         xReturn = xTimerPendFunctionCallFromISR( vEventGroupClearBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToClear, NULL ); /*lint !e9087 Can't avoid cast to void* as a generic callback function not specific to this use case. Callback casts back to original type so safe. */
 
+        traceRETURN_xEventGroupClearBitsFromISR( xReturn );
+
         return xReturn;
     }
 
@@ -521,12 +545,16 @@ EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup )
     EventGroup_t const * const pxEventBits = xEventGroup;
     EventBits_t uxReturn;
 
+    traceENTER_xEventGroupGetBitsFromISR( xEventGroup );
+
     uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();
     {
         uxReturn = pxEventBits->uxEventBits;
     }
     taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );
 
+    traceRETURN_xEventGroupGetBitsFromISR( uxReturn );
+
     return uxReturn;
 } /*lint !e818 EventGroupHandle_t is a typedef used in other functions to so can't be pointer to const. */
 /*-----------------------------------------------------------*/
@@ -542,6 +570,8 @@ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
     EventGroup_t * pxEventBits = xEventGroup;
     BaseType_t xMatchFound = pdFALSE;
 
+    traceENTER_xEventGroupSetBits( xEventGroup, uxBitsToSet );
+
     /* Check the user is not attempting to set the bits used by the kernel
      * itself. */
     configASSERT( xEventGroup );
@@ -623,6 +653,8 @@ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
     }
     ( void ) xTaskResumeAll();
 
+    traceRETURN_xEventGroupSetBits( pxEventBits->uxEventBits );
+
     return pxEventBits->uxEventBits;
 }
 /*-----------------------------------------------------------*/
@@ -632,6 +664,8 @@ void vEventGroupDelete( EventGroupHandle_t xEventGroup )
     EventGroup_t * pxEventBits = xEventGroup;
     const List_t * pxTasksWaitingForBits;
 
+    traceENTER_vEventGroupDelete( xEventGroup );
+
     configASSERT( pxEventBits );
 
     pxTasksWaitingForBits = &( pxEventBits->xTasksWaitingForBits );
@@ -670,6 +704,8 @@ void vEventGroupDelete( EventGroupHandle_t xEventGroup )
         }
     }
     #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
+
+    traceRETURN_vEventGroupDelete();
 }
 /*-----------------------------------------------------------*/
 
@@ -680,6 +716,8 @@ void vEventGroupDelete( EventGroupHandle_t xEventGroup )
         BaseType_t xReturn;
         EventGroup_t * pxEventBits = xEventGroup;
 
+        traceENTER_xEventGroupGetStaticBuffer( xEventGroup, ppxEventGroupBuffer );
+
         configASSERT( pxEventBits );
         configASSERT( ppxEventGroupBuffer );
 
@@ -704,6 +742,8 @@ void vEventGroupDelete( EventGroupHandle_t xEventGroup )
         }
         #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
 
+        traceRETURN_xEventGroupGetStaticBuffer( xReturn );
+
         return xReturn;
     }
 #endif /* configSUPPORT_STATIC_ALLOCATION */
@@ -714,7 +754,11 @@ void vEventGroupDelete( EventGroupHandle_t xEventGroup )
 void vEventGroupSetBitsCallback( void * pvEventGroup,
                                  const uint32_t ulBitsToSet )
 {
+    traceENTER_vEventGroupSetBitsCallback( pvEventGroup, ulBitsToSet );
+
     ( void ) xEventGroupSetBits( pvEventGroup, ( EventBits_t ) ulBitsToSet ); /*lint !e9079 Can't avoid cast to void* as a generic timer callback prototype. Callback casts back to original type so safe. */
+
+    traceRETURN_vEventGroupSetBitsCallback();
 }
 /*-----------------------------------------------------------*/
 
@@ -723,7 +767,11 @@ void vEventGroupSetBitsCallback( void * pvEventGroup,
 void vEventGroupClearBitsCallback( void * pvEventGroup,
                                    const uint32_t ulBitsToClear )
 {
+    traceENTER_vEventGroupClearBitsCallback( pvEventGroup, ulBitsToClear );
+
     ( void ) xEventGroupClearBits( pvEventGroup, ( EventBits_t ) ulBitsToClear ); /*lint !e9079 Can't avoid cast to void* as a generic timer callback prototype. Callback casts back to original type so safe. */
+
+    traceRETURN_vEventGroupClearBitsCallback();
 }
 /*-----------------------------------------------------------*/
 
@@ -772,9 +820,13 @@ static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits,
     {
         BaseType_t xReturn;
 
+        traceENTER_xEventGroupSetBitsFromISR( xEventGroup, uxBitsToSet, pxHigherPriorityTaskWoken );
+
         traceEVENT_GROUP_SET_BITS_FROM_ISR( xEventGroup, uxBitsToSet );
         xReturn = xTimerPendFunctionCallFromISR( vEventGroupSetBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToSet, pxHigherPriorityTaskWoken ); /*lint !e9087 Can't avoid cast to void* as a generic callback function not specific to this use case. Callback casts back to original type so safe. */
 
+        traceRETURN_xEventGroupSetBitsFromISR( xReturn );
+
         return xReturn;
     }
 
@@ -788,6 +840,8 @@ static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits,
         UBaseType_t xReturn;
         EventGroup_t const * pxEventBits = ( EventGroup_t * ) xEventGroup; /*lint !e9087 !e9079 EventGroupHandle_t is a pointer to an EventGroup_t, but EventGroupHandle_t is kept opaque outside of this file for data hiding purposes. */
 
+        traceENTER_uxEventGroupGetNumber( xEventGroup );
+
         if( xEventGroup == NULL )
         {
             xReturn = 0;
@@ -797,6 +851,8 @@ static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits,
             xReturn = pxEventBits->uxEventGroupNumber;
         }
 
+        traceRETURN_uxEventGroupGetNumber( xReturn );
+
         return xReturn;
     }
 
@@ -808,7 +864,11 @@ static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits,
     void vEventGroupSetNumber( void * xEventGroup,
                                UBaseType_t uxEventGroupNumber )
     {
+        traceENTER_vEventGroupSetNumber( xEventGroup, uxEventGroupNumber );
+
         ( ( EventGroup_t * ) xEventGroup )->uxEventGroupNumber = uxEventGroupNumber; /*lint !e9087 !e9079 EventGroupHandle_t is a pointer to an EventGroup_t, but EventGroupHandle_t is kept opaque outside of this file for data hiding purposes. */
+
+        traceRETURN_vEventGroupSetNumber();
     }
 
 #endif /* configUSE_TRACE_FACILITY */