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.

1 files changed, 79 insertions, 0 deletions

diff --git a/stream_buffer.c b/stream_buffer.c
index 7c91ec316..32aa8e4f2 100644
--- a/stream_buffer.c
+++ b/stream_buffer.c
@@ -326,6 +326,8 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer,
         void * pvAllocatedMemory;
         uint8_t ucFlags;
 
+        traceENTER_xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, xIsMessageBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback );
+
         /* In case the stream buffer is going to be used as a message buffer
          * (that is, it will hold discrete messages with a little meta data that
          * says how big the next message is) check the buffer will be large enough
@@ -387,6 +389,8 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer,
             traceSTREAM_BUFFER_CREATE_FAILED( xIsMessageBuffer );
         }
 
+        traceRETURN_xStreamBufferGenericCreate( pvAllocatedMemory );
+
         return ( StreamBufferHandle_t ) pvAllocatedMemory; /*lint !e9087 !e826 Safe cast as allocated memory is aligned. */
     }
 #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
@@ -406,6 +410,8 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer,
         StreamBufferHandle_t xReturn;
         uint8_t ucFlags;
 
+        traceENTER_xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, xIsMessageBuffer, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback );
+
         configASSERT( pucStreamBufferStorageArea );
         configASSERT( pxStaticStreamBuffer );
         configASSERT( xTriggerLevelBytes <= xBufferSizeBytes );
@@ -468,6 +474,8 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer,
             traceSTREAM_BUFFER_CREATE_STATIC_FAILED( xReturn, xIsMessageBuffer );
         }
 
+        traceRETURN_xStreamBufferGenericCreateStatic( xReturn );
+
         return xReturn;
     }
 #endif /* ( configSUPPORT_STATIC_ALLOCATION == 1 ) */
@@ -481,6 +489,8 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer,
         BaseType_t xReturn;
         StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
 
+        traceENTER_xStreamBufferGetStaticBuffers( xStreamBuffer, ppucStreamBufferStorageArea, ppxStaticStreamBuffer );
+
         configASSERT( pxStreamBuffer );
         configASSERT( ppucStreamBufferStorageArea );
         configASSERT( ppxStaticStreamBuffer );
@@ -496,6 +506,8 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer,
             xReturn = pdFALSE;
         }
 
+        traceRETURN_xStreamBufferGetStaticBuffers( xReturn );
+
         return xReturn;
     }
 #endif /* configSUPPORT_STATIC_ALLOCATION */
@@ -505,6 +517,8 @@ void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer )
 {
     StreamBuffer_t * pxStreamBuffer = xStreamBuffer;
 
+    traceENTER_vStreamBufferDelete( xStreamBuffer );
+
     configASSERT( pxStreamBuffer );
 
     traceSTREAM_BUFFER_DELETE( xStreamBuffer );
@@ -531,6 +545,8 @@ void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer )
          * freed - just scrub the structure so future use will assert. */
         ( void ) memset( pxStreamBuffer, 0x00, sizeof( StreamBuffer_t ) );
     }
+
+    traceRETURN_vStreamBufferDelete();
 }
 /*-----------------------------------------------------------*/
 
@@ -544,6 +560,8 @@ BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer )
         UBaseType_t uxStreamBufferNumber;
     #endif
 
+    traceENTER_xStreamBufferReset( xStreamBuffer );
+
     configASSERT( pxStreamBuffer );
 
     #if ( configUSE_TRACE_FACILITY == 1 )
@@ -587,6 +605,8 @@ BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer )
     }
     taskEXIT_CRITICAL();
 
+    traceRETURN_xStreamBufferReset( xReturn );
+
     return xReturn;
 }
 /*-----------------------------------------------------------*/
@@ -597,6 +617,8 @@ BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer,
     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
     BaseType_t xReturn;
 
+    traceENTER_xStreamBufferSetTriggerLevel( xStreamBuffer, xTriggerLevel );
+
     configASSERT( pxStreamBuffer );
 
     /* It is not valid for the trigger level to be 0. */
@@ -617,6 +639,8 @@ BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer,
         xReturn = pdFALSE;
     }
 
+    traceRETURN_xStreamBufferSetTriggerLevel( xReturn );
+
     return xReturn;
 }
 /*-----------------------------------------------------------*/
@@ -627,6 +651,8 @@ size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer )
     size_t xSpace;
     size_t xOriginalTail;
 
+    traceENTER_xStreamBufferSpacesAvailable( xStreamBuffer );
+
     configASSERT( pxStreamBuffer );
 
     /* The code below reads xTail and then xHead.  This is safe if the stream
@@ -650,6 +676,8 @@ size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer )
         mtCOVERAGE_TEST_MARKER();
     }
 
+    traceRETURN_xStreamBufferSpacesAvailable( xSpace );
+
     return xSpace;
 }
 /*-----------------------------------------------------------*/
@@ -659,9 +687,14 @@ size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer )
     const StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
     size_t xReturn;
 
+    traceENTER_xStreamBufferBytesAvailable( xStreamBuffer );
+
     configASSERT( pxStreamBuffer );
 
     xReturn = prvBytesInBuffer( pxStreamBuffer );
+
+    traceRETURN_xStreamBufferBytesAvailable( xReturn );
+
     return xReturn;
 }
 /*-----------------------------------------------------------*/
@@ -677,6 +710,8 @@ size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
     TimeOut_t xTimeOut;
     size_t xMaxReportedSpace = 0;
 
+    traceENTER_xStreamBufferSend( xStreamBuffer, pvTxData, xDataLengthBytes, xTicksToWait );
+
     configASSERT( pvTxData );
     configASSERT( pxStreamBuffer );
 
@@ -793,6 +828,8 @@ size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
         traceSTREAM_BUFFER_SEND_FAILED( xStreamBuffer );
     }
 
+    traceRETURN_xStreamBufferSend( xReturn );
+
     return xReturn;
 }
 /*-----------------------------------------------------------*/
@@ -806,6 +843,8 @@ size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
     size_t xReturn, xSpace;
     size_t xRequiredSpace = xDataLengthBytes;
 
+    traceENTER_xStreamBufferSendFromISR( xStreamBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken );
+
     configASSERT( pvTxData );
     configASSERT( pxStreamBuffer );
 
@@ -843,6 +882,7 @@ size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
     }
 
     traceSTREAM_BUFFER_SEND_FROM_ISR( xStreamBuffer, xReturn );
+    traceRETURN_xStreamBufferSendFromISR( xReturn );
 
     return xReturn;
 }
@@ -906,6 +946,8 @@ size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
     size_t xReceivedLength = 0, xBytesAvailable, xBytesToStoreMessageLength;
 
+    traceENTER_xStreamBufferReceive( xStreamBuffer, pvRxData, xBufferLengthBytes, xTicksToWait );
+
     configASSERT( pvRxData );
     configASSERT( pxStreamBuffer );
 
@@ -998,6 +1040,8 @@ size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
         mtCOVERAGE_TEST_MARKER();
     }
 
+    traceRETURN_xStreamBufferReceive( xReceivedLength );
+
     return xReceivedLength;
 }
 /*-----------------------------------------------------------*/
@@ -1008,6 +1052,8 @@ size_t xStreamBufferNextMessageLengthBytes( StreamBufferHandle_t xStreamBuffer )
     size_t xReturn, xBytesAvailable;
     configMESSAGE_BUFFER_LENGTH_TYPE xTempReturn;
 
+    traceENTER_xStreamBufferNextMessageLengthBytes( xStreamBuffer );
+
     configASSERT( pxStreamBuffer );
 
     /* Ensure the stream buffer is being used as a message buffer. */
@@ -1038,6 +1084,8 @@ size_t xStreamBufferNextMessageLengthBytes( StreamBufferHandle_t xStreamBuffer )
         xReturn = 0;
     }
 
+    traceRETURN_xStreamBufferNextMessageLengthBytes( xReturn );
+
     return xReturn;
 }
 /*-----------------------------------------------------------*/
@@ -1050,6 +1098,8 @@ size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
     size_t xReceivedLength = 0, xBytesAvailable, xBytesToStoreMessageLength;
 
+    traceENTER_xStreamBufferReceiveFromISR( xStreamBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken );
+
     configASSERT( pvRxData );
     configASSERT( pxStreamBuffer );
 
@@ -1094,6 +1144,7 @@ size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
     }
 
     traceSTREAM_BUFFER_RECEIVE_FROM_ISR( xStreamBuffer, xReceivedLength );
+    traceRETURN_xStreamBufferReceiveFromISR( xReceivedLength );
 
     return xReceivedLength;
 }
@@ -1157,6 +1208,8 @@ BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer )
     BaseType_t xReturn;
     size_t xTail;
 
+    traceENTER_xStreamBufferIsEmpty( xStreamBuffer );
+
     configASSERT( pxStreamBuffer );
 
     /* True if no bytes are available. */
@@ -1171,6 +1224,8 @@ BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer )
         xReturn = pdFALSE;
     }
 
+    traceRETURN_xStreamBufferIsEmpty( xReturn );
+
     return xReturn;
 }
 /*-----------------------------------------------------------*/
@@ -1181,6 +1236,8 @@ BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer )
     size_t xBytesToStoreMessageLength;
     const StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
 
+    traceENTER_xStreamBufferIsFull( xStreamBuffer );
+
     configASSERT( pxStreamBuffer );
 
     /* This generic version of the receive function is used by both message
@@ -1206,6 +1263,8 @@ BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer )
         xReturn = pdFALSE;
     }
 
+    traceRETURN_xStreamBufferIsFull( xReturn );
+
     return xReturn;
 }
 /*-----------------------------------------------------------*/
@@ -1217,6 +1276,8 @@ BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer
     BaseType_t xReturn;
     UBaseType_t uxSavedInterruptStatus;
 
+    traceENTER_xStreamBufferSendCompletedFromISR( xStreamBuffer, pxHigherPriorityTaskWoken );
+
     configASSERT( pxStreamBuffer );
 
     uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();
@@ -1237,6 +1298,8 @@ BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer
     }
     taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );
 
+    traceRETURN_xStreamBufferSendCompletedFromISR( xReturn );
+
     return xReturn;
 }
 /*-----------------------------------------------------------*/
@@ -1248,6 +1311,8 @@ BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuf
     BaseType_t xReturn;
     UBaseType_t uxSavedInterruptStatus;
 
+    traceENTER_xStreamBufferReceiveCompletedFromISR( xStreamBuffer, pxHigherPriorityTaskWoken );
+
     configASSERT( pxStreamBuffer );
 
     uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();
@@ -1268,6 +1333,8 @@ BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuf
     }
     taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );
 
+    traceRETURN_xStreamBufferReceiveCompletedFromISR( xReturn );
+
     return xReturn;
 }
 /*-----------------------------------------------------------*/
@@ -1426,6 +1493,10 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer,
 
     UBaseType_t uxStreamBufferGetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer )
     {
+        traceENTER_uxStreamBufferGetStreamBufferNumber( xStreamBuffer );
+
+        traceRETURN_uxStreamBufferGetStreamBufferNumber( xStreamBuffer->uxStreamBufferNumber );
+
         return xStreamBuffer->uxStreamBufferNumber;
     }
 
@@ -1437,7 +1508,11 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer,
     void vStreamBufferSetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer,
                                              UBaseType_t uxStreamBufferNumber )
     {
+        traceENTER_vStreamBufferSetStreamBufferNumber( xStreamBuffer, uxStreamBufferNumber );
+
         xStreamBuffer->uxStreamBufferNumber = uxStreamBufferNumber;
+
+        traceRETURN_vStreamBufferSetStreamBufferNumber();
     }
 
 #endif /* configUSE_TRACE_FACILITY */
@@ -1447,6 +1522,10 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer,
 
     uint8_t ucStreamBufferGetStreamBufferType( StreamBufferHandle_t xStreamBuffer )
     {
+        traceENTER_ucStreamBufferGetStreamBufferType( xStreamBuffer );
+
+        traceRETURN_ucStreamBufferGetStreamBufferType( ( uint8_t ) ( xStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) );
+
         return( ( uint8_t ) ( xStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) );
     }