Add config option for event groups and stream buffers (#994)

* Add configUSE_EVENT_GROUPS in source files

* Add configUSE_EVENT_GROUPS macro in MPU wrapper files

* Add configUSE_EVENT_GROUPS macro in MPU port files for GCC and RVDS compilers

* Fix Formatting

* Add configUSE_STREAM_BUFFERS in source files

* Add configUSE_STREAM_BUFFERS  macro in MPU wrapper files

* Add configUSE_STREAM_BUFFERS macro in MPU port files for GCC and RVDS compilers

* Update FreeRTOS.h post latest commit

* Update the ARM_CRx_MPU Port to account for the new configuration changes

* Formatting suggestions

Signed-off-by: Gaurav Aggarwal <aggarg@amazon.com>

* Code review suggestions

---------

Signed-off-by: Gaurav Aggarwal <aggarg@amazon.com>
Co-authored-by: joshzarr <joshzarr@amazon.com>
Co-authored-by: Gaurav Aggarwal <aggarg@amazon.com>
Co-authored-by: Soren Ptak <ptaksoren@gmail.com>
Co-authored-by: Gaurav-Aggarwal-AWS <33462878+aggarg@users.noreply.github.com>

Author: 4 people

event_groups.c

@@ -318,6 +318,14 @@
     #define configUSE_TIMERS    0
 #endif
 
+#ifndef configUSE_EVENT_GROUPS
+    #define configUSE_EVENT_GROUPS    1
+#endif
+
+#ifndef configUSE_STREAM_BUFFERS
+    #define configUSE_STREAM_BUFFERS    1
+#endif
+
 #ifndef configUSE_DAEMON_TASK_STARTUP_HOOK
     #define configUSE_DAEMON_TASK_STARTUP_HOOK    0
 #endif

include/FreeRTOS.h

@@ -139,6 +139,9 @@ typedef TickType_t               EventBits_t;
  * each event group has 56 usable bits (bit 0 to bit 53). The EventBits_t type
  * is used to store event bits within an event group.
  *
+ * The configUSE_EVENT_GROUPS configuration constant must be set to 1 for xEventGroupCreate()
+ * to be available.
+ *
  * @return If the event group was created then a handle to the event group is
  * returned.  If there was insufficient FreeRTOS heap available to create the
  * event group then NULL is returned.  See https://www.FreeRTOS.org/a00111.html
@@ -196,6 +199,9 @@ typedef TickType_t               EventBits_t;
  * each event group has 56 usable bits (bit 0 to bit 53).  The EventBits_t type
  * is used to store event bits within an event group.
  *
+ * The configUSE_EVENT_GROUPS configuration constant must be set to 1 for xEventGroupCreateStatic()
+ * to be available.
+ *
  * @param pxEventGroupBuffer pxEventGroupBuffer must point to a variable of type
  * StaticEventGroup_t, which will be then be used to hold the event group's data
  * structures, removing the need for the memory to be allocated dynamically.
@@ -238,6 +244,9 @@ typedef TickType_t               EventBits_t;
  *
  * This function cannot be called from an interrupt.
  *
+ * The configUSE_EVENT_GROUPS configuration constant must be set to 1 for xEventGroupWaitBits()
+ * to be available.
+ *
  * @param xEventGroup The event group in which the bits are being tested.  The
  * event group must have previously been created using a call to
  * xEventGroupCreate().
@@ -331,6 +340,9 @@ EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
  * Clear bits within an event group.  This function cannot be called from an
  * interrupt.
  *
+ * The configUSE_EVENT_GROUPS configuration constant must be set to 1 for xEventGroupClearBits()
+ * to be available.
+ *
  * @param xEventGroup The event group in which the bits are to be cleared.
  *
  * @param uxBitsToClear A bitwise value that indicates the bit or bits to clear
@@ -461,6 +473,9 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup,
  * Setting bits in an event group will automatically unblock tasks that are
  * blocked waiting for the bits.
  *
+ * The configUSE_EVENT_GROUPS configuration constant must be set to 1 for xEventGroupSetBits()
+ * to be available.
+ *
  * @param xEventGroup The event group in which the bits are to be set.
  *
  * @param uxBitsToSet A bitwise value that indicates the bit or bits to set.
@@ -625,6 +640,9 @@ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
  * this case all the bits specified by uxBitsToWait will be automatically
  * cleared before the function returns.
  *
+ * The configUSE_EVENT_GROUPS configuration constant must be set to 1 for xEventGroupSync()
+ * to be available.
+ *
  * @param xEventGroup The event group in which the bits are being tested.  The
  * event group must have previously been created using a call to
  * xEventGroupCreate().
@@ -743,6 +761,9 @@ EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
  * Returns the current value of the bits in an event group.  This function
  * cannot be used from an interrupt.
  *
+ * The configUSE_EVENT_GROUPS configuration constant must be set to 1 for xEventGroupGetBits()
+ * to be available.
+ *
  * @param xEventGroup The event group being queried.
  *
  * @return The event group bits at the time xEventGroupGetBits() was called.
@@ -760,6 +781,9 @@ EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
  *
  * A version of xEventGroupGetBits() that can be called from an ISR.
  *
+ * The configUSE_EVENT_GROUPS configuration constant must be set to 1 for xEventGroupGetBitsFromISR()
+ * to be available.
+ *
  * @param xEventGroup The event group being queried.
  *
  * @return The event group bits at the time xEventGroupGetBitsFromISR() was called.
@@ -779,6 +803,9 @@ EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup ) PRIVILEG
  * xEventGroupCreate().  Tasks that are blocked on the event group will be
  * unblocked and obtain 0 as the event group's value.
  *
+ * The configUSE_EVENT_GROUPS configuration constant must be set to 1 for vEventGroupDelete()
+ * to be available.
+ *
  * @param xEventGroup The event group being deleted.
  */
 void vEventGroupDelete( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION;
@@ -793,6 +820,9 @@ void vEventGroupDelete( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION;
  * Retrieve a pointer to a statically created event groups's data structure
  * buffer. It is the same buffer that is supplied at the time of creation.
  *
+ * The configUSE_EVENT_GROUPS configuration constant must be set to 1 for xEventGroupGetStaticBuffer()
+ * to be available.
+ *
  * @param xEventGroup The event group for which to retrieve the buffer.
  *
  * @param ppxEventGroupBuffer Used to return a pointer to the event groups's

include/event_groups.h

@@ -100,6 +100,8 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  *
  * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in
  * FreeRTOSConfig.h for xMessageBufferCreate() to be available.
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferCreate() to be available.
  *
  * @param xBufferSizeBytes The total number of bytes (not messages) the message
  * buffer will be able to hold at any one time.  When a message is written to
@@ -168,12 +170,15 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  *
  * @code{c}
  * MessageBufferHandle_t xMessageBufferCreateStatic( size_t xBufferSizeBytes,
- *                                                uint8_t *pucMessageBufferStorageArea,
- *                                                StaticMessageBuffer_t *pxStaticMessageBuffer );
+ *                                                   uint8_t *pucMessageBufferStorageArea,
+ *                                                   StaticMessageBuffer_t *pxStaticMessageBuffer );
  * @endcode
  * Creates a new message buffer using statically allocated memory.  See
  * xMessageBufferCreate() for a version that uses dynamically allocated memory.
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferCreateStatic() to be available.
+ *
  * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the
  * pucMessageBufferStorageArea parameter.  When a message is written to the
  * message buffer an additional sizeof( size_t ) bytes are also written to store
@@ -258,6 +263,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  * buffer and storage area buffer. These are the same buffers that are supplied
  * at the time of creation.
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferGetStaticBuffers() to be available.
+ *
  * @param xMessageBuffer The message buffer for which to retrieve the buffers.
  *
  * @param ppucMessageBufferStorageArea Used to return a pointer to the
@@ -281,9 +289,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  *
  * @code{c}
  * size_t xMessageBufferSend( MessageBufferHandle_t xMessageBuffer,
- *                         const void *pvTxData,
- *                         size_t xDataLengthBytes,
- *                         TickType_t xTicksToWait );
+ *                            const void *pvTxData,
+ *                            size_t xDataLengthBytes,
+ *                            TickType_t xTicksToWait );
  * @endcode
  *
  * Sends a discrete message to the message buffer.  The message can be any
@@ -309,6 +317,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  * xMessageBufferSendFromISR() to write to a message buffer from an interrupt
  * service routine (ISR).
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferSend() to be available.
+ *
  * @param xMessageBuffer The handle of the message buffer to which a message is
  * being sent.
  *
@@ -381,9 +392,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  *
  * @code{c}
  * size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer,
- *                                const void *pvTxData,
- *                                size_t xDataLengthBytes,
- *                                BaseType_t *pxHigherPriorityTaskWoken );
+ *                                   const void *pvTxData,
+ *                                   size_t xDataLengthBytes,
+ *                                   BaseType_t *pxHigherPriorityTaskWoken );
  * @endcode
  *
  * Interrupt safe version of the API function that sends a discrete message to
@@ -409,6 +420,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  * xMessageBufferSendFromISR() to write to a message buffer from an interrupt
  * service routine (ISR).
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferSendFromISR() to be available.
+ *
  * @param xMessageBuffer The handle of the message buffer to which a message is
  * being sent.
  *
@@ -486,9 +500,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  *
  * @code{c}
  * size_t xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer,
- *                            void *pvRxData,
- *                            size_t xBufferLengthBytes,
- *                            TickType_t xTicksToWait );
+ *                               void *pvRxData,
+ *                               size_t xBufferLengthBytes,
+ *                               TickType_t xTicksToWait );
  * @endcode
  *
  * Receives a discrete message from a message buffer.  Messages can be of
@@ -513,6 +527,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  * xMessageBufferReceiveFromISR() to read from a message buffer from an
  * interrupt service routine (ISR).
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferReceive() to be available.
+ *
  * @param xMessageBuffer The handle of the message buffer from which a message
  * is being received.
  *
@@ -576,9 +593,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  *
  * @code{c}
  * size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer,
- *                                   void *pvRxData,
- *                                   size_t xBufferLengthBytes,
- *                                   BaseType_t *pxHigherPriorityTaskWoken );
+ *                                      void *pvRxData,
+ *                                      size_t xBufferLengthBytes,
+ *                                      BaseType_t *pxHigherPriorityTaskWoken );
  * @endcode
  *
  * An interrupt safe version of the API function that receives a discrete
@@ -604,6 +621,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  * xMessageBufferReceiveFromISR() to read from a message buffer from an
  * interrupt service routine (ISR).
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferReceiveFromISR() to be available.
+ *
  * @param xMessageBuffer The handle of the message buffer from which a message
  * is being received.
  *
@@ -687,6 +707,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  * A message buffer handle must not be used after the message buffer has been
  * deleted.
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * vMessageBufferDelete() to be available.
+ *
  * @param xMessageBuffer The handle of the message buffer to be deleted.
  *
  */
@@ -703,6 +726,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  * cannot accept any more messages, of any size, until space is made available
  * by a message being removed from the message buffer.
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferIsFull() to be available.
+ *
  * @param xMessageBuffer The handle of the message buffer being queried.
  *
  * @return If the message buffer referenced by xMessageBuffer is full then
@@ -719,6 +745,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  *
  * Tests to see if a message buffer is empty (does not contain any messages).
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferIsEmpty() to be available.
+ *
  * @param xMessageBuffer The handle of the message buffer being queried.
  *
  * @return If the message buffer referenced by xMessageBuffer is empty then
@@ -739,6 +768,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  *
  * A message buffer can only be reset if there are no tasks blocked on it.
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferReset() 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
@@ -760,6 +792,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  * @endcode
  * Returns the number of bytes of free space in the message buffer.
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferSpaceAvailable() to be available.
+ *
  * @param xMessageBuffer The handle of the message buffer being queried.
  *
  * @return The number of bytes that can be written to the message buffer before
@@ -786,6 +821,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  * Useful if xMessageBufferReceive() returned 0 because the size of the buffer
  * passed into xMessageBufferReceive() was too small to hold the next message.
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferNextLengthBytes() to be available.
+ *
  * @param xMessageBuffer The handle of the message buffer being queried.
  *
  * @return The length (in bytes) of the next message in the message buffer, or 0
@@ -817,6 +855,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
  * additional information.
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferSendCompletedFromISR() to be available.
+ *
  * @param xMessageBuffer The handle of the stream buffer to which data was
  * written.
  *
@@ -858,6 +899,9 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
  * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
  * additional information.
  *
+ * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for
+ * xMessageBufferReceiveCompletedFromISR() to be available.
+ *
  * @param xMessageBuffer The handle of the stream buffer from which data was
  * read.
  *