From 9bfd0abb55e660a7040c6f38cd31f27b51ab23f5 Mon Sep 17 00:00:00 2001 From: HagaiMoshe <121489522+HagaiMoshe@users.noreply.github.com> Date: Wed, 17 Apr 2024 01:41:55 +0300 Subject: [PATCH 1/3] Add IRQ safe API for message buffer reset (#1033) * Add API xStreamBufferResetFromISR Allow reseting the stream buffer from ISR context Signed-off-by: hagai.moshe Signed-off-by: Gaurav Aggarwal Co-authored-by: hagai.moshe Co-authored-by: Rahul Kar <118818625+kar-rahul-aws@users.noreply.github.com> Co-authored-by: kar-rahul-aws Co-authored-by: Gaurav Aggarwal --- include/FreeRTOS.h | 12 ++++++++ include/message_buffer.h | 36 +++++++++++++++++++++++ include/stream_buffer.h | 36 +++++++++++++++++++++++ stream_buffer.c | 62 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 146 insertions(+) diff --git a/include/FreeRTOS.h b/include/FreeRTOS.h index 69611842a..662c5ea15 100644 --- a/include/FreeRTOS.h +++ b/include/FreeRTOS.h @@ -1001,6 +1001,10 @@ #define traceSTREAM_BUFFER_RESET( xStreamBuffer ) #endif +#ifndef traceSTREAM_BUFFER_RESET_FROM_ISR + #define traceSTREAM_BUFFER_RESET_FROM_ISR( xStreamBuffer ) +#endif + #ifndef traceBLOCKING_ON_STREAM_BUFFER_SEND #define traceBLOCKING_ON_STREAM_BUFFER_SEND( xStreamBuffer ) #endif @@ -2437,6 +2441,14 @@ #define traceRETURN_xStreamBufferReset( xReturn ) #endif +#ifndef traceENTER_xStreamBufferResetFromISR + #define traceENTER_xStreamBufferResetFromISR( xStreamBuffer ) +#endif + +#ifndef traceRETURN_xStreamBufferResetFromISR + #define traceRETURN_xStreamBufferResetFromISR( xReturn ) +#endif + #ifndef traceENTER_xStreamBufferSetTriggerLevel #define traceENTER_xStreamBufferSetTriggerLevel( xStreamBuffer, xTriggerLevel ) #endif diff --git a/include/message_buffer.h b/include/message_buffer.h index 1b1356ca4..b58f33f47 100644 --- a/include/message_buffer.h +++ b/include/message_buffer.h @@ -768,6 +768,10 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * * A message buffer can only be reset if there are no tasks blocked on it. * + * Use xMessageBufferReset() to reset a message buffer from a task. + * Use xMessageBufferResetFromISR() to reset a message buffer from an + * interrupt service routine (ISR). + * * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for * xMessageBufferReset() to be available. * @@ -785,6 +789,38 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; xStreamBufferReset( xMessageBuffer ) +/** + * message_buffer.h + * @code{c} + * BaseType_t xMessageBufferResetFromISR( MessageBufferHandle_t xMessageBuffer ); + * @endcode + * + * An interrupt safe version of the API function that resets the message buffer. + * Resets a message buffer to its initial empty state, discarding any message it + * contained. + * + * A message buffer can only be reset if there are no tasks blocked on it. + * + * Use xMessageBufferReset() to reset a message buffer from a task. + * Use xMessageBufferResetFromISR() to reset a message buffer from an + * interrupt service routine (ISR). + * + * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for + * xMessageBufferResetFromISR() to be available. + * + * @param xMessageBuffer The handle of the message buffer being reset. + * + * @return If the message buffer was reset then pdPASS is returned. If the + * message buffer could not be reset because either there was a task blocked on + * the message queue to wait for space to become available, or to wait for a + * a message to be available, then pdFAIL is returned. + * + * \defgroup xMessageBufferResetFromISR xMessageBufferResetFromISR + * \ingroup MessageBufferManagement + */ +#define xMessageBufferResetFromISR( xMessageBuffer ) \ + xStreamBufferResetFromISR( xMessageBuffer ) + /** * message_buffer.h * @code{c} diff --git a/include/stream_buffer.h b/include/stream_buffer.h index 94a0e0cd7..dca9851a5 100644 --- a/include/stream_buffer.h +++ b/include/stream_buffer.h @@ -767,6 +767,10 @@ BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED * are no tasks blocked waiting to either send to or receive from the stream * buffer. * + * Use xStreamBufferReset() to reset a stream buffer from a task. + * Use xStreamBufferResetFromISR() to reset a stream buffer from an + * interrupt service routine (ISR). + * * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for * xStreamBufferReset() to be available. * @@ -781,6 +785,38 @@ BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED */ BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; +/** + * stream_buffer.h + * + * @code{c} + * BaseType_t xStreamBufferResetFromISR( StreamBufferHandle_t xStreamBuffer ); + * @endcode + * + * An interrupt safe version of the API function that resets the stream buffer. + * + * Resets a stream buffer to its initial, empty, state. Any data that was in + * the stream buffer is discarded. A stream buffer can only be reset if there + * are no tasks blocked waiting to either send to or receive from the stream + * buffer. + * + * Use xStreamBufferReset() to reset a stream buffer from a task. + * Use xStreamBufferResetFromISR() to reset a stream buffer from an + * interrupt service routine (ISR). + * + * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for + * xStreamBufferResetFromISR() to be available. + * + * @param xStreamBuffer The handle of the stream buffer being reset. + * + * @return If the stream buffer is reset then pdPASS is returned. If there was + * a task blocked waiting to send to or read from the stream buffer then the + * stream buffer is not reset and pdFAIL is returned. + * + * \defgroup xStreamBufferResetFromISR xStreamBufferResetFromISR + * \ingroup StreamBufferManagement + */ +BaseType_t xStreamBufferResetFromISR( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; + /** * stream_buffer.h * diff --git a/stream_buffer.c b/stream_buffer.c index 44354fba3..17a898d45 100644 --- a/stream_buffer.c +++ b/stream_buffer.c @@ -639,6 +639,68 @@ BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ) } /*-----------------------------------------------------------*/ +BaseType_t xStreamBufferResetFromISR( StreamBufferHandle_t xStreamBuffer ) +{ + StreamBuffer_t * const pxStreamBuffer = xStreamBuffer; + BaseType_t xReturn = pdFAIL; + StreamBufferCallbackFunction_t pxSendCallback = NULL, pxReceiveCallback = NULL; + UBaseType_t uxSavedInterruptStatus; + + #if ( configUSE_TRACE_FACILITY == 1 ) + UBaseType_t uxStreamBufferNumber; + #endif + + traceENTER_xStreamBufferResetFromISR( xStreamBuffer ); + + configASSERT( pxStreamBuffer ); + + #if ( configUSE_TRACE_FACILITY == 1 ) + { + /* Store the stream buffer number so it can be restored after the + * reset. */ + uxStreamBufferNumber = pxStreamBuffer->uxStreamBufferNumber; + } + #endif + + /* Can only reset a message buffer if there are no tasks blocked on it. */ + uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR(); + { + if( ( pxStreamBuffer->xTaskWaitingToReceive == NULL ) && ( pxStreamBuffer->xTaskWaitingToSend == NULL ) ) + { + #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) + { + pxSendCallback = pxStreamBuffer->pxSendCompletedCallback; + pxReceiveCallback = pxStreamBuffer->pxReceiveCompletedCallback; + } + #endif + + prvInitialiseNewStreamBuffer( pxStreamBuffer, + pxStreamBuffer->pucBuffer, + pxStreamBuffer->xLength, + pxStreamBuffer->xTriggerLevelBytes, + pxStreamBuffer->ucFlags, + pxSendCallback, + pxReceiveCallback ); + + #if ( configUSE_TRACE_FACILITY == 1 ) + { + pxStreamBuffer->uxStreamBufferNumber = uxStreamBufferNumber; + } + #endif + + traceSTREAM_BUFFER_RESET_FROM_ISR( xStreamBuffer ); + + xReturn = pdPASS; + } + } + taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus ); + + traceRETURN_xStreamBufferResetFromISR( xReturn ); + + return xReturn; +} +/*-----------------------------------------------------------*/ + BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel ) { From 5a72344c9a57306d175c20e117b2b82b16fa332e Mon Sep 17 00:00:00 2001 From: Rahul Kar <118818625+kar-rahul-aws@users.noreply.github.com> Date: Wed, 17 Apr 2024 14:27:58 +0530 Subject: [PATCH 2/3] Add MPU wrapper from xStreamBufferResetFromISR (#1034) * Add MPU wrapper from xStreamBufferResetFromISR in V10.6.x * Code review suggestions Signed-off-by: Gaurav Aggarwal --------- Signed-off-by: Gaurav Aggarwal Co-authored-by: chinglee-iot <61685396+chinglee-iot@users.noreply.github.com> Co-authored-by: Gaurav Aggarwal --- include/mpu_prototypes.h | 1 + include/mpu_wrappers.h | 1 + portable/Common/mpu_wrappers_v2.c | 27 +++++++++++++++++++++++++++ 3 files changed, 29 insertions(+) diff --git a/include/mpu_prototypes.h b/include/mpu_prototypes.h index d51f6e1d2..10da35bf8 100644 --- a/include/mpu_prototypes.h +++ b/include/mpu_prototypes.h @@ -384,5 +384,6 @@ BaseType_t MPU_xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBu BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; BaseType_t MPU_xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; +BaseType_t MPU_xStreamBufferResetFromISR( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; #endif /* MPU_PROTOTYPES_H */ diff --git a/include/mpu_wrappers.h b/include/mpu_wrappers.h index 19c5e779f..dea7c0d2a 100644 --- a/include/mpu_wrappers.h +++ b/include/mpu_wrappers.h @@ -227,6 +227,7 @@ #define xStreamBufferReceiveFromISR MPU_xStreamBufferReceiveFromISR #define xStreamBufferSendCompletedFromISR MPU_xStreamBufferSendCompletedFromISR #define xStreamBufferReceiveCompletedFromISR MPU_xStreamBufferReceiveCompletedFromISR + #define xStreamBufferResetFromISR MPU_xStreamBufferResetFromISR #endif /* #if ( configUSE_MPU_WRAPPERS_V1 == 0 ) */ #if ( ( configUSE_MPU_WRAPPERS_V1 == 0 ) && ( configENABLE_ACCESS_CONTROL_LIST == 1 ) ) diff --git a/portable/Common/mpu_wrappers_v2.c b/portable/Common/mpu_wrappers_v2.c index a7ab6669a..f8d14b1df 100644 --- a/portable/Common/mpu_wrappers_v2.c +++ b/portable/Common/mpu_wrappers_v2.c @@ -4962,6 +4962,33 @@ #endif /* #if ( configUSE_STREAM_BUFFERS == 1 ) */ +/*-----------------------------------------------------------*/ + + #if ( configUSE_STREAM_BUFFERS == 1 ) + + BaseType_t MPU_xStreamBufferResetFromISR( StreamBufferHandle_t xStreamBuffer ) /*PRIVILEGED_FUNCTION */ + { + BaseType_t xReturn = pdFAIL; + StreamBufferHandle_t xInternalStreamBufferHandle = NULL; + int32_t lIndex; + + lIndex = ( int32_t ) xStreamBuffer; + + if( IS_EXTERNAL_INDEX_VALID( lIndex ) != pdFALSE ) + { + xInternalStreamBufferHandle = MPU_GetStreamBufferHandleAtIndex( CONVERT_TO_INTERNAL_INDEX( lIndex ) ); + + if( xInternalStreamBufferHandle != NULL ) + { + xReturn = xStreamBufferResetFromISR( xInternalStreamBufferHandle ); + } + } + + return xReturn; + } + + #endif /* #if ( configUSE_STREAM_BUFFERS == 1 ) */ + /*-----------------------------------------------------------*/ /* Functions that the application writer wants to execute in privileged mode From f69b1db45c294444306f9cc840feef2ead1bca03 Mon Sep 17 00:00:00 2001 From: Caleb Perkinson <60443297+cperkulator@users.noreply.github.com> Date: Wed, 17 Apr 2024 10:54:00 -0400 Subject: [PATCH 3/3] Add Stream Batching Buffer (#916) The difference between a stream buffer and a stream batching buffer is when a task performs read on a non-empty buffer: - The task reading from a non-empty stream buffer returns immediately regardless of the amount of data in the buffer. - The task reading from a non-empty steam batching buffer blocks until the amount of data in the buffer exceeds the trigger level or the block time expires. --- include/FreeRTOS.h | 10 +- include/message_buffer.h | 8 +- include/mpu_prototypes.h | 4 +- include/stream_buffer.h | 207 +++++++++++++++++++++++++++++- portable/Common/mpu_wrappers.c | 20 +-- portable/Common/mpu_wrappers_v2.c | 12 +- stream_buffer.c | 43 +++++-- 7 files changed, 260 insertions(+), 44 deletions(-) diff --git a/include/FreeRTOS.h b/include/FreeRTOS.h index 662c5ea15..f7a59a765 100644 --- a/include/FreeRTOS.h +++ b/include/FreeRTOS.h @@ -982,15 +982,15 @@ #endif #ifndef traceSTREAM_BUFFER_CREATE_FAILED - #define traceSTREAM_BUFFER_CREATE_FAILED( xIsMessageBuffer ) + #define traceSTREAM_BUFFER_CREATE_FAILED( xStreamBufferType ) #endif #ifndef traceSTREAM_BUFFER_CREATE_STATIC_FAILED - #define traceSTREAM_BUFFER_CREATE_STATIC_FAILED( xReturn, xIsMessageBuffer ) + #define traceSTREAM_BUFFER_CREATE_STATIC_FAILED( xReturn, xStreamBufferType ) #endif #ifndef traceSTREAM_BUFFER_CREATE - #define traceSTREAM_BUFFER_CREATE( pxStreamBuffer, xIsMessageBuffer ) + #define traceSTREAM_BUFFER_CREATE( pxStreamBuffer, xStreamBufferType ) #endif #ifndef traceSTREAM_BUFFER_DELETE @@ -2402,7 +2402,7 @@ #endif #ifndef traceENTER_xStreamBufferGenericCreate - #define traceENTER_xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, xIsMessageBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ) + #define traceENTER_xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, xStreamBufferType, pxSendCompletedCallback, pxReceiveCompletedCallback ) #endif #ifndef traceRETURN_xStreamBufferGenericCreate @@ -2410,7 +2410,7 @@ #endif #ifndef traceENTER_xStreamBufferGenericCreateStatic - #define traceENTER_xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, xIsMessageBuffer, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ) + #define traceENTER_xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, xStreamBufferType, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ) #endif #ifndef traceRETURN_xStreamBufferGenericCreateStatic diff --git a/include/message_buffer.h b/include/message_buffer.h index b58f33f47..975a7e343 100644 --- a/include/message_buffer.h +++ b/include/message_buffer.h @@ -158,11 +158,11 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * \ingroup MessageBufferManagement */ #define xMessageBufferCreate( xBufferSizeBytes ) \ - xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( size_t ) 0, pdTRUE, NULL, NULL ) + xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( size_t ) 0, sbTYPE_MESSAGE_BUFFER, NULL, NULL ) #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) #define xMessageBufferCreateWithCallback( xBufferSizeBytes, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ - xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( size_t ) 0, pdTRUE, ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) + xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( size_t ) 0, sbTYPE_MESSAGE_BUFFER, ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) #endif /** @@ -243,11 +243,11 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * \ingroup MessageBufferManagement */ #define xMessageBufferCreateStatic( xBufferSizeBytes, pucMessageBufferStorageArea, pxStaticMessageBuffer ) \ - xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), 0, pdTRUE, ( pucMessageBufferStorageArea ), ( pxStaticMessageBuffer ), NULL, NULL ) + xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), 0, sbTYPE_MESSAGE_BUFFER, ( pucMessageBufferStorageArea ), ( pxStaticMessageBuffer ), NULL, NULL ) #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) #define xMessageBufferCreateStaticWithCallback( xBufferSizeBytes, pucMessageBufferStorageArea, pxStaticMessageBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ - xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), 0, pdTRUE, ( pucMessageBufferStorageArea ), ( pxStaticMessageBuffer ), ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) + xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), 0, sbTYPE_MESSAGE_BUFFER, ( pucMessageBufferStorageArea ), ( pxStaticMessageBuffer ), ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) #endif /** diff --git a/include/mpu_prototypes.h b/include/mpu_prototypes.h index 10da35bf8..d51547cd6 100644 --- a/include/mpu_prototypes.h +++ b/include/mpu_prototypes.h @@ -357,12 +357,12 @@ size_t MPU_xStreamBufferNextMessageLengthBytes( StreamBufferHandle_t xStreamBuff * with all the APIs. */ StreamBufferHandle_t MPU_xStreamBufferGenericCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes, - BaseType_t xIsMessageBuffer, + BaseType_t xStreamBufferType, StreamBufferCallbackFunction_t pxSendCompletedCallback, StreamBufferCallbackFunction_t pxReceiveCompletedCallback ) PRIVILEGED_FUNCTION; StreamBufferHandle_t MPU_xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes, size_t xTriggerLevelBytes, - BaseType_t xIsMessageBuffer, + BaseType_t xStreamBufferType, uint8_t * const pucStreamBufferStorageArea, StaticStreamBuffer_t * const pxStaticStreamBuffer, StreamBufferCallbackFunction_t pxSendCompletedCallback, diff --git a/include/stream_buffer.h b/include/stream_buffer.h index dca9851a5..9b15c8aff 100644 --- a/include/stream_buffer.h +++ b/include/stream_buffer.h @@ -62,6 +62,13 @@ #endif /* *INDENT-ON* */ +/** + * Type of stream buffer. For internal use only. + */ +#define sbTYPE_STREAM_BUFFER ( ( BaseType_t ) 0 ) +#define sbTYPE_MESSAGE_BUFFER ( ( BaseType_t ) 1 ) +#define sbTYPE_STREAM_BATCHING_BUFFER ( ( BaseType_t ) 2 ) + /** * Type by which stream buffers are referenced. For example, a call to * xStreamBufferCreate() returns an StreamBufferHandle_t variable that can @@ -157,11 +164,11 @@ typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuf */ #define xStreamBufferCreate( xBufferSizeBytes, xTriggerLevelBytes ) \ - xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), pdFALSE, NULL, NULL ) + xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BUFFER, NULL, NULL ) #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) #define xStreamBufferCreateWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ - xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), pdFALSE, ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) + xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BUFFER, ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) #endif /** @@ -257,11 +264,199 @@ typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuf */ #define xStreamBufferCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer ) \ - xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), pdFALSE, ( pucStreamBufferStorageArea ), ( pxStaticStreamBuffer ), NULL, NULL ) + xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BUFFER, ( pucStreamBufferStorageArea ), ( pxStaticStreamBuffer ), NULL, NULL ) #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) #define xStreamBufferCreateStaticWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ - xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), pdFALSE, ( pucStreamBufferStorageArea ), ( pxStaticStreamBuffer ), ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) + xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BUFFER, ( pucStreamBufferStorageArea ), ( pxStaticStreamBuffer ), ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) +#endif + +/** + * stream_buffer.h + * + * @code{c} + * StreamBufferHandle_t xStreamBatchingBufferCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes ); + * @endcode + * + * Creates a new stream batching buffer using dynamically allocated memory. See + * xStreamBatchingBufferCreateStatic() for a version that uses statically + * allocated memory (memory that is allocated at compile time). + * + * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in + * FreeRTOSConfig.h for xStreamBatchingBufferCreate() to be available. + * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for + * xStreamBatchingBufferCreate() to be available. + * + * The difference between a stream buffer and a stream batching buffer is when + * a task performs read on a non-empty buffer: + * - The task reading from a non-empty stream buffer returns immediately + * regardless of the amount of data in the buffer. + * - The task reading from a non-empty steam batching buffer blocks until the + * amount of data in the buffer exceeds the trigger level or the block time + * expires. + * + * @param xBufferSizeBytes The total number of bytes the stream batching buffer + * will be able to hold at any one time. + * + * @param xTriggerLevelBytes The number of bytes that must be in the stream + * batching buffer to unblock a task calling xStreamBufferReceive before the + * block time expires. + * + * @param pxSendCompletedCallback Callback invoked when number of bytes at least + * equal to trigger level is sent to the stream batching buffer. If the + * parameter is NULL, it will use the default implementation provided by + * sbSEND_COMPLETED macro. To enable the callback, configUSE_SB_COMPLETED_CALLBACK + * must be set to 1 in FreeRTOSConfig.h. + * + * @param pxReceiveCompletedCallback Callback invoked when more than zero bytes + * are read from a stream batching buffer. If the parameter is NULL, it will use + * the default implementation provided by sbRECEIVE_COMPLETED macro. To enable + * the callback, configUSE_SB_COMPLETED_CALLBACK must be set to 1 in + * FreeRTOSConfig.h. + * + * @return If NULL is returned, then the stream batching buffer cannot be created + * because there is insufficient heap memory available for FreeRTOS to allocate + * the stream batching buffer data structures and storage area. A non-NULL value + * being returned indicates that the stream batching buffer has been created + * successfully - the returned value should be stored as the handle to the + * created stream batching buffer. + * + * Example use: + * @code{c} + * + * void vAFunction( void ) + * { + * StreamBufferHandle_t xStreamBatchingBuffer; + * const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10; + * + * // Create a stream batching buffer that can hold 100 bytes. The memory used + * // to hold both the stream batching buffer structure and the data in the stream + * // batching buffer is allocated dynamically. + * xStreamBatchingBuffer = xStreamBatchingBufferCreate( xStreamBufferSizeBytes, xTriggerLevel ); + * + * if( xStreamBatchingBuffer == NULL ) + * { + * // There was not enough heap memory space available to create the + * // stream batching buffer. + * } + * else + * { + * // The stream batching buffer was created successfully and can now be used. + * } + * } + * @endcode + * \defgroup xStreamBatchingBufferCreate xStreamBatchingBufferCreate + * \ingroup StreamBatchingBufferManagement + */ + +#define xStreamBatchingBufferCreate( xBufferSizeBytes, xTriggerLevelBytes ) \ + xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BATCHING_BUFFER, NULL, NULL ) + +#if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) + #define xStreamBatchingBufferCreateWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ + xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BATCHING_BUFFER, ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) +#endif + +/** + * stream_buffer.h + * + * @code{c} + * StreamBufferHandle_t xStreamBatchingBufferCreateStatic( size_t xBufferSizeBytes, + * size_t xTriggerLevelBytes, + * uint8_t *pucStreamBufferStorageArea, + * StaticStreamBuffer_t *pxStaticStreamBuffer ); + * @endcode + * Creates a new stream batching buffer using statically allocated memory. See + * xStreamBatchingBufferCreate() for a version that uses dynamically allocated + * memory. + * + * configSUPPORT_STATIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h for + * xStreamBatchingBufferCreateStatic() to be available. configUSE_STREAM_BUFFERS + * must be set to 1 in for FreeRTOSConfig.h for xStreamBatchingBufferCreateStatic() + * to be available. + * + * The difference between a stream buffer and a stream batching buffer is when + * a task performs read on a non-empty buffer: + * - The task reading from a non-empty stream buffer returns immediately + * regardless of the amount of data in the buffer. + * - The task reading from a non-empty steam batching buffer blocks until the + * amount of data in the buffer exceeds the trigger level or the block time + * expires. + * + * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the + * pucStreamBufferStorageArea parameter. + * + * @param xTriggerLevelBytes The number of bytes that must be in the stream + * batching buffer to unblock a task calling xStreamBufferReceive before the + * block time expires. + * + * @param pucStreamBufferStorageArea Must point to a uint8_t array that is at + * least xBufferSizeBytes big. This is the array to which streams are + * copied when they are written to the stream batching buffer. + * + * @param pxStaticStreamBuffer Must point to a variable of type + * StaticStreamBuffer_t, which will be used to hold the stream batching buffer's + * data structure. + * + * @param pxSendCompletedCallback Callback invoked when number of bytes at least + * equal to trigger level is sent to the stream batching buffer. If the parameter + * is NULL, it will use the default implementation provided by sbSEND_COMPLETED + * macro. To enable the callback, configUSE_SB_COMPLETED_CALLBACK must be set to + * 1 in FreeRTOSConfig.h. + * + * @param pxReceiveCompletedCallback Callback invoked when more than zero bytes + * are read from a stream batching buffer. If the parameter is NULL, it will use + * the default implementation provided by sbRECEIVE_COMPLETED macro. To enable + * the callback, configUSE_SB_COMPLETED_CALLBACK must be set to 1 in + * FreeRTOSConfig.h. + * + * @return If the stream batching buffer is created successfully then a handle + * to the created stream batching buffer is returned. If either pucStreamBufferStorageArea + * or pxStaticstreamBuffer are NULL then NULL is returned. + * + * Example use: + * @code{c} + * + * // Used to dimension the array used to hold the streams. The available space + * // will actually be one less than this, so 999. + * #define STORAGE_SIZE_BYTES 1000 + * + * // Defines the memory that will actually hold the streams within the stream + * // batching buffer. + * static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ]; + * + * // The variable used to hold the stream batching buffer structure. + * StaticStreamBuffer_t xStreamBufferStruct; + * + * void MyFunction( void ) + * { + * StreamBufferHandle_t xStreamBatchingBuffer; + * const size_t xTriggerLevel = 1; + * + * xStreamBatchingBuffer = xStreamBatchingBufferCreateStatic( sizeof( ucStorageBuffer ), + * xTriggerLevel, + * ucStorageBuffer, + * &xStreamBufferStruct ); + * + * // As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer + * // parameters were NULL, xStreamBatchingBuffer will not be NULL, and can be + * // used to reference the created stream batching buffer in other stream + * // buffer API calls. + * + * // Other code that uses the stream batching buffer can go here. + * } + * + * @endcode + * \defgroup xStreamBatchingBufferCreateStatic xStreamBatchingBufferCreateStatic + * \ingroup StreamBatchingBufferManagement + */ + +#define xStreamBatchingBufferCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer ) \ + xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BATCHING_BUFFER, ( pucStreamBufferStorageArea ), ( pxStaticStreamBuffer ), NULL, NULL ) + +#if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) + #define xStreamBatchingBufferCreateStaticWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ + xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BATCHING_BUFFER, ( pucStreamBufferStorageArea ), ( pxStaticStreamBuffer ), ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) #endif /** @@ -1053,14 +1248,14 @@ void vStreamBufferSetStreamBufferNotificationIndex( StreamBufferHandle_t xStream /* Functions below here are not part of the public API. */ StreamBufferHandle_t xStreamBufferGenericCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes, - BaseType_t xIsMessageBuffer, + BaseType_t xStreamBufferType, StreamBufferCallbackFunction_t pxSendCompletedCallback, StreamBufferCallbackFunction_t pxReceiveCompletedCallback ) PRIVILEGED_FUNCTION; #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) StreamBufferHandle_t xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes, size_t xTriggerLevelBytes, - BaseType_t xIsMessageBuffer, + BaseType_t xStreamBufferType, uint8_t * const pucStreamBufferStorageArea, StaticStreamBuffer_t * const pxStaticStreamBuffer, StreamBufferCallbackFunction_t pxSendCompletedCallback, diff --git a/portable/Common/mpu_wrappers.c b/portable/Common/mpu_wrappers.c index 85facbd79..be1a9954d 100644 --- a/portable/Common/mpu_wrappers.c +++ b/portable/Common/mpu_wrappers.c @@ -2404,14 +2404,14 @@ #if ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configUSE_STREAM_BUFFERS == 1 ) ) StreamBufferHandle_t MPU_xStreamBufferGenericCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes, - BaseType_t xIsMessageBuffer, + BaseType_t xStreamBufferType, StreamBufferCallbackFunction_t pxSendCompletedCallback, StreamBufferCallbackFunction_t pxReceiveCompletedCallback ) /* FREERTOS_SYSTEM_CALL */ { StreamBufferHandle_t xReturn; /** - * Streambuffer application level callback functionality is disabled for MPU + * Stream buffer application level callback functionality is disabled for MPU * enabled ports. */ configASSERT( ( pxSendCompletedCallback == NULL ) && @@ -2427,7 +2427,7 @@ xReturn = xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, - xIsMessageBuffer, + xStreamBufferType, NULL, NULL ); portMEMORY_BARRIER(); @@ -2439,14 +2439,14 @@ { xReturn = xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, - xIsMessageBuffer, + xStreamBufferType, NULL, NULL ); } } else { - traceSTREAM_BUFFER_CREATE_FAILED( xIsMessageBuffer ); + traceSTREAM_BUFFER_CREATE_FAILED( xStreamBufferType ); xReturn = NULL; } @@ -2458,7 +2458,7 @@ #if ( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configUSE_STREAM_BUFFERS == 1 ) ) StreamBufferHandle_t MPU_xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes, size_t xTriggerLevelBytes, - BaseType_t xIsMessageBuffer, + BaseType_t xStreamBufferType, uint8_t * const pucStreamBufferStorageArea, StaticStreamBuffer_t * const pxStaticStreamBuffer, StreamBufferCallbackFunction_t pxSendCompletedCallback, @@ -2467,7 +2467,7 @@ StreamBufferHandle_t xReturn; /** - * Streambuffer application level callback functionality is disabled for MPU + * Stream buffer application level callback functionality is disabled for MPU * enabled ports. */ configASSERT( ( pxSendCompletedCallback == NULL ) && @@ -2483,7 +2483,7 @@ xReturn = xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, - xIsMessageBuffer, + xStreamBufferType, pucStreamBufferStorageArea, pxStaticStreamBuffer, NULL, @@ -2497,7 +2497,7 @@ { xReturn = xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, - xIsMessageBuffer, + xStreamBufferType, pucStreamBufferStorageArea, pxStaticStreamBuffer, NULL, @@ -2506,7 +2506,7 @@ } else { - traceSTREAM_BUFFER_CREATE_STATIC_FAILED( xReturn, xIsMessageBuffer ); + traceSTREAM_BUFFER_CREATE_STATIC_FAILED( xReturn, xStreamBufferType ); xReturn = NULL; } diff --git a/portable/Common/mpu_wrappers_v2.c b/portable/Common/mpu_wrappers_v2.c index f8d14b1df..2dc36b33b 100644 --- a/portable/Common/mpu_wrappers_v2.c +++ b/portable/Common/mpu_wrappers_v2.c @@ -4662,7 +4662,7 @@ StreamBufferHandle_t MPU_xStreamBufferGenericCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes, - BaseType_t xIsMessageBuffer, + BaseType_t xStreamBufferType, StreamBufferCallbackFunction_t pxSendCompletedCallback, StreamBufferCallbackFunction_t pxReceiveCompletedCallback ) /* PRIVILEGED_FUNCTION */ { @@ -4686,7 +4686,7 @@ { xInternalStreamBufferHandle = xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, - xIsMessageBuffer, + xStreamBufferType, NULL, NULL ); @@ -4703,7 +4703,7 @@ } else { - traceSTREAM_BUFFER_CREATE_FAILED( xIsMessageBuffer ); + traceSTREAM_BUFFER_CREATE_FAILED( xStreamBufferType ); xExternalStreamBufferHandle = NULL; } @@ -4717,7 +4717,7 @@ StreamBufferHandle_t MPU_xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes, size_t xTriggerLevelBytes, - BaseType_t xIsMessageBuffer, + BaseType_t xStreamBufferType, uint8_t * const pucStreamBufferStorageArea, StaticStreamBuffer_t * const pxStaticStreamBuffer, StreamBufferCallbackFunction_t pxSendCompletedCallback, @@ -4743,7 +4743,7 @@ { xInternalStreamBufferHandle = xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, - xIsMessageBuffer, + xStreamBufferType, pucStreamBufferStorageArea, pxStaticStreamBuffer, NULL, @@ -4762,7 +4762,7 @@ } else { - traceSTREAM_BUFFER_CREATE_STATIC_FAILED( xReturn, xIsMessageBuffer ); + traceSTREAM_BUFFER_CREATE_STATIC_FAILED( xReturn, xStreamBufferType ); xExternalStreamBufferHandle = NULL; } diff --git a/stream_buffer.c b/stream_buffer.c index 17a898d45..4471b4f3c 100644 --- a/stream_buffer.c +++ b/stream_buffer.c @@ -224,6 +224,7 @@ /* Bits stored in the ucFlags field of the stream buffer. */ #define sbFLAGS_IS_MESSAGE_BUFFER ( ( uint8_t ) 1 ) /* Set if the stream buffer was created as a message buffer, in which case it holds discrete messages rather than a stream. */ #define sbFLAGS_IS_STATICALLY_ALLOCATED ( ( uint8_t ) 2 ) /* Set if the stream buffer was created using statically allocated memory. */ + #define sbFLAGS_IS_BATCHING_BUFFER ( ( uint8_t ) 4 ) /* Set if the stream buffer was created as a batching buffer, meaning the receiver task will only unblock when the trigger level exceededs. */ /*-----------------------------------------------------------*/ @@ -329,25 +330,31 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer, #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) StreamBufferHandle_t xStreamBufferGenericCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes, - BaseType_t xIsMessageBuffer, + BaseType_t xStreamBufferType, StreamBufferCallbackFunction_t pxSendCompletedCallback, StreamBufferCallbackFunction_t pxReceiveCompletedCallback ) { void * pvAllocatedMemory; uint8_t ucFlags; - traceENTER_xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, xIsMessageBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ); + traceENTER_xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, xStreamBufferType, 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 * to hold at least one message. */ - if( xIsMessageBuffer == pdTRUE ) + if( xStreamBufferType == sbTYPE_MESSAGE_BUFFER ) { /* Is a message buffer but not statically allocated. */ ucFlags = sbFLAGS_IS_MESSAGE_BUFFER; configASSERT( xBufferSizeBytes > sbBYTES_TO_STORE_MESSAGE_LENGTH ); } + else if( xStreamBufferType == sbTYPE_STREAM_BATCHING_BUFFER ) + { + /* Is a batching buffer but not statically allocated. */ + ucFlags = sbFLAGS_IS_BATCHING_BUFFER; + configASSERT( xBufferSizeBytes > 0 ); + } else { /* Not a message buffer and not statically allocated. */ @@ -398,11 +405,11 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ); - traceSTREAM_BUFFER_CREATE( ( ( StreamBuffer_t * ) pvAllocatedMemory ), xIsMessageBuffer ); + traceSTREAM_BUFFER_CREATE( ( ( StreamBuffer_t * ) pvAllocatedMemory ), xStreamBufferType ); } else { - traceSTREAM_BUFFER_CREATE_FAILED( xIsMessageBuffer ); + traceSTREAM_BUFFER_CREATE_FAILED( xStreamBufferType ); } traceRETURN_xStreamBufferGenericCreate( pvAllocatedMemory ); @@ -419,7 +426,7 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer, StreamBufferHandle_t xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes, size_t xTriggerLevelBytes, - BaseType_t xIsMessageBuffer, + BaseType_t xStreamBufferType, uint8_t * const pucStreamBufferStorageArea, StaticStreamBuffer_t * const pxStaticStreamBuffer, StreamBufferCallbackFunction_t pxSendCompletedCallback, @@ -432,7 +439,7 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer, StreamBufferHandle_t xReturn; uint8_t ucFlags; - traceENTER_xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, xIsMessageBuffer, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ); + traceENTER_xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, xStreamBufferType, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ); configASSERT( pucStreamBufferStorageArea ); configASSERT( pxStaticStreamBuffer ); @@ -450,12 +457,18 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer, * says how big the next message is) check the buffer will be large enough * to hold at least one message. */ - if( xIsMessageBuffer != pdFALSE ) + if( xStreamBufferType == sbTYPE_MESSAGE_BUFFER ) { /* Statically allocated message buffer. */ ucFlags = sbFLAGS_IS_MESSAGE_BUFFER | sbFLAGS_IS_STATICALLY_ALLOCATED; configASSERT( xBufferSizeBytes > sbBYTES_TO_STORE_MESSAGE_LENGTH ); } + else if( xStreamBufferType == sbTYPE_STREAM_BATCHING_BUFFER ) + { + /* Statically allocated batching buffer. */ + ucFlags = sbFLAGS_IS_BATCHING_BUFFER | sbFLAGS_IS_STATICALLY_ALLOCATED; + configASSERT( xBufferSizeBytes > 0 ); + } else { /* Statically allocated stream buffer. */ @@ -486,7 +499,7 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer, * again. */ pxStreamBuffer->ucFlags |= sbFLAGS_IS_STATICALLY_ALLOCATED; - traceSTREAM_BUFFER_CREATE( pxStreamBuffer, xIsMessageBuffer ); + traceSTREAM_BUFFER_CREATE( pxStreamBuffer, xStreamBufferType ); /* MISRA Ref 11.3.1 [Misaligned access] */ /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-113 */ @@ -496,7 +509,7 @@ static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer, else { xReturn = NULL; - traceSTREAM_BUFFER_CREATE_STATIC_FAILED( xReturn, xIsMessageBuffer ); + traceSTREAM_BUFFER_CREATE_STATIC_FAILED( xReturn, xStreamBufferType ); } traceRETURN_xStreamBufferGenericCreateStatic( xReturn ); @@ -1053,6 +1066,12 @@ size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer, { xBytesToStoreMessageLength = sbBYTES_TO_STORE_MESSAGE_LENGTH; } + else if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_BATCHING_BUFFER ) != ( uint8_t ) 0 ) + { + /* Force task to block if the batching buffer contains less bytes than + * the trigger level. */ + xBytesToStoreMessageLength = pxStreamBuffer->xTriggerLevelBytes; + } else { xBytesToStoreMessageLength = 0; @@ -1070,7 +1089,9 @@ size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer, * xBytesToStoreMessageLength holds the number of bytes used to hold * the length of the next discrete message. If this function was * invoked by a stream buffer read then xBytesToStoreMessageLength will - * be 0. */ + * be 0. If this function was invoked by a stream batch buffer read + * then xBytesToStoreMessageLength will be xTriggerLevelBytes value + * for the buffer.*/ if( xBytesAvailable <= xBytesToStoreMessageLength ) { /* Clear notification state as going to wait for data. */