Add functions to get the buffers of statically created objects

Dazza0 · Dazza0 · commit ad48deccfa65 · 2023-03-13T14:33:33.000+08:00
Added various ...GetStaticBuffer() functions to get the buffers of statically
created objects.
diff --git a/.github/lexicon.txt b/.github/lexicon.txt
@@ -1464,13 +1464,24 @@ ppdc
 ppio
 ppitc
 ppmc
+ppucmessagebufferstoragearea
+ppucqueuestorage
+ppucstreambufferstoragearea
 ppudr
 ppuer
 ppusr
+ppuxstackbuffer
 ppvdestination
 ppwm
+ppxeventgroupbuffer
 ppxidletaskstackbuffer
 ppxidletasktcbbuffer
+ppxsemaphorebuffer
+ppxstaticmessagebuffer
+ppxstaticqueue
+ppxstaticstreambuffer
+ppxtaskbuffer
+ppxtimerbuffer
 ppxtimertaskstackbuffer
 ppxtimertasktcbbuffer
 pr
@@ -2723,6 +2734,7 @@ xeventgroupcreatestatic
 xeventgroupdelete
 xeventgroupgetbits
 xeventgroupgetbitsfromisr
+xeventgroupgetstaticbuffer
 xeventgroupsetbits
 xeventgroupsetbitsfromisr
 xeventgroupsync
@@ -2796,6 +2808,7 @@ xmessage
 xmessagebuffer
 xmessagebuffercreate
 xmessagebuffercreatestatic
+xmessagebuffergetstaticbuffers
 xmessagebufferisempty
 xmessagebufferisfull
 xmessagebuffernextlengthbytes
@@ -2865,6 +2878,7 @@ xqueuecreatestatic
 xqueuegenericsend
 xqueuegenericsendfromisr
 xqueuegetmutexholder
+xqueuegetstaticbuffers
 xqueuegivefromisr
 xqueuegivemutexrecursive
 xqueueorsemaphore
@@ -2919,6 +2933,7 @@ xsemaphorecreaterecursivemutex
 xsemaphorecreaterecursivemutexstatic
 xsemaphoregetmutexholder
 xsemaphoregetmutexholderfromisr
+xsemaphoregetstaticbuffer
 xsemaphoregive
 xsemaphoregivefromisr
 xsemaphoregivemutexrecursive
@@ -2943,6 +2958,7 @@ xstreambuffer
 xstreambufferbytesavailable
 xstreambuffercreate
 xstreambuffercreatestatic
+xstreambuffergetstaticbuffers
 xstreambufferisempty
 xstreambufferisfull
 xstreambuffernextmessagelengthbytes
@@ -2981,6 +2997,7 @@ xtaskgetcurrenttaskhandle
 xtaskgethandle
 xtaskgetidletaskhandle
 xtaskgetschedulerstate
+xtaskgetstaticbuffers
 xtaskgettickcount
 xtaskgettickcountfromisr
 xtaskhandle
@@ -3048,6 +3065,7 @@ xtimerdelete
 xtimergetexpirytime
 xtimergetperiod
 xtimergetreloadmode
+xtimergetstaticbuffer
 xtimergettimerdaemontaskhandle
 xtimeristimeractive
 xtimerlistitem
diff --git a/event_groups.c b/event_groups.c
@@ -677,6 +677,42 @@ void vEventGroupDelete( EventGroupHandle_t xEventGroup )
 }
 /*-----------------------------------------------------------*/
 
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+    BaseType_t xEventGroupGetStaticBuffer( EventGroupHandle_t xEventGroup,
+                                           StaticEventGroup_t ** ppxEventGroupBuffer )
+    {
+        BaseType_t xReturn;
+        EventGroup_t * pxEventBits = xEventGroup;
+
+        configASSERT( pxEventBits );
+        configASSERT( ppxEventGroupBuffer );
+
+        #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
+        {
+            /* Check if the event group was statically allocated */
+            if( pxEventBits->ucStaticallyAllocated == ( uint8_t ) pdTRUE )
+            {
+                *ppxEventGroupBuffer = ( StaticEventGroup_t * ) pxEventBits;
+                xReturn = pdTRUE;
+            }
+            else
+            {
+                xReturn = pdFALSE;
+            }
+        }
+        #else /* configSUPPORT_DYNAMIC_ALLOCATION */
+        {
+            /* Event group must have been statically allocated */
+            *ppxEventGroupBuffer = ( StaticEventGroup_t * ) pxEventBits;
+            xReturn = pdTRUE;
+        }
+        #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
+
+        return xReturn;
+    }
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+/*-----------------------------------------------------------*/
+
 /* For internal use only - execute a 'set bits' command that was pended from
  * an interrupt. */
 void vEventGroupSetBitsCallback( void * pvEventGroup,
diff --git a/include/event_groups.h b/include/event_groups.h
@@ -763,6 +763,29 @@ EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup ) PRIVILEG
  */
 void vEventGroupDelete( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION;
 
+/**
+ * event_groups.h
+ * @code{c}
+ *  BaseType_t xEventGroupGetStaticBuffer( EventGroupHandle_t xEventGroup,
+ *                                         StaticEventGroup_t ** ppxEventGroupBuffer );
+ * @endcode
+ *
+ * This function fetches a pointer to the memory buffer of a statically created
+ * event group.
+ *
+ * @param xEventGroup The handle of the event group
+ *
+ * @param ppxEventGroupBuffer Used to pass back a pointer to the event groups's
+ * data structure buffer.
+ *
+ * @return pdTRUE if the buffer were fetched. pdFALSE if the event group was not
+ * statically created.
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+    BaseType_t xEventGroupGetStaticBuffer( EventGroupHandle_t xEventGroup,
+                                           StaticEventGroup_t ** ppxEventGroupBuffer ) PRIVILEGED_FUNCTION;
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+
 /* For internal use only. */
 void vEventGroupSetBitsCallback( void * pvEventGroup,
                                  const uint32_t ulBitsToSet ) PRIVILEGED_FUNCTION;
diff --git a/include/message_buffer.h b/include/message_buffer.h
@@ -245,6 +245,37 @@ typedef StreamBufferHandle_t MessageBufferHandle_t;
     xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), 0, pdTRUE, ( pucMessageBufferStorageArea ), ( pxStaticMessageBuffer ), ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) )
 #endif
 
+/**
+ * message_buffer.h
+ *
+ * @code{c}
+ * BaseType_t xMessageBufferGetStaticBuffers( MessageBufferHandle_t xMessageBuffer,
+ *                                          uint8_t ** ppucMessageBufferStorageArea,
+ *                                          StaticMessageBuffer_t ** ppxStaticMessageBuffer );
+ * @endcode
+ *
+ * This function fetches the pointers to the memory buffers of a statically
+ * created message buffer.
+ *
+ * @param xMessageBuffer The handle to the message buffer
+ *
+ * @param ppucMessageBufferStorageArea Used to pass back a pointer to the
+ * message buffer's storage area buffer.
+ *
+ * @param ppxStaticMessageBuffer Used to pass back a pointer to the message
+ * buffer's data structure buffer.
+ *
+ * @return pdTRUE if buffers were fetched. pdFALSE if the message buffer was not
+ * statically created.
+ *
+ * \defgroup xMessageBufferGetStaticBuffers xMessageBufferGetStaticBuffers
+ * \ingroup MessageBufferManagement
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+    #define xMessageBufferGetStaticBuffers( xMessageBuffer, ppucMessageBufferStorageArea, ppxStaticMessageBuffer ) \
+    xStreamBufferGenericGetStaticBuffers( ( xMessageBuffer ), ( ppucMessageBufferStorageArea ), ( ppxStaticMessageBuffer ) )
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+
 /**
  * message_buffer.h
  *
diff --git a/include/queue.h b/include/queue.h
@@ -235,6 +235,35 @@ typedef struct QueueDefinition   * QueueSetMemberHandle_t;
     #define xQueueCreateStatic( uxQueueLength, uxItemSize, pucQueueStorage, pxQueueBuffer )    xQueueGenericCreateStatic( ( uxQueueLength ), ( uxItemSize ), ( pucQueueStorage ), ( pxQueueBuffer ), ( queueQUEUE_TYPE_BASE ) )
 #endif /* configSUPPORT_STATIC_ALLOCATION */
 
+/**
+ * queue. h
+ * @code{c}
+ * BaseType_t xQueueGetStaticBuffers( QueueHandle_t xQueue,
+ *                                    uint8_t ** ppucQueueStorage,
+ *                                    StaticQueue_t ** ppxStaticQueue );
+ * @endcode
+ *
+ * This function fetches the pointers to the memory buffers of a statically
+ * created queue.
+ *
+ * @param xQueue The handle to the queue
+ *
+ * @param ppucQueueStorage Used to pass back a pointer to the queue's storage
+ * area buffer.
+ *
+ * @param ppxStaticQueue Used to pass back a pointer to the queue's data
+ * structure buffer.
+ *
+ * @return pdTRUE if buffers were fetched. pdFALSE if the queue was not
+ * created using xQueueCreateStatic().
+ *
+ * \defgroup xQueueGetStaticBuffers xQueueGetStaticBuffers
+ * \ingroup QueueManagement
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+    #define xQueueGetStaticBuffers( xQueue, ppucQueueStorage, ppxStaticQueue )    xQueueGenericGetStaticBuffers( ( xQueue ), ( ppucQueueStorage ), ( ppxStaticQueue ) )
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+
 /**
  * queue. h
  * @code{c}
@@ -1542,6 +1571,18 @@ BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION;
                                              const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;
 #endif
 
+/*
+ * Generic version of the function used to get the buffers of statically created
+ * queues. This is called by other functions and macros that get the buffers
+ * of other statically created RTOS objects that use the queue structure as
+ * their base.
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+    BaseType_t xQueueGenericGetStaticBuffers( QueueHandle_t xQueue,
+                                              uint8_t ** ppucQueueStorage,
+                                              StaticQueue_t ** ppxStaticQueue ) PRIVILEGED_FUNCTION;
+#endif
+
 /*
  * Queue sets provide a mechanism to allow a task to block (pend) on a read
  * operation from multiple queues or semaphores simultaneously.
diff --git a/include/semphr.h b/include/semphr.h
@@ -1190,4 +1190,25 @@ typedef QueueHandle_t SemaphoreHandle_t;
  */
 #define uxSemaphoreGetCountFromISR( xSemaphore )    uxQueueMessagesWaitingFromISR( ( QueueHandle_t ) ( xSemaphore ) )
 
+/**
+ * semphr.h
+ * @code{c}
+ * BaseType_t xSemaphoreGetStaticBuffer( SemaphoreHandle_t xSemaphore );
+ * @endcode
+ *
+ * This function fetches a pointer to the memory buffer of a statically created
+ * binary semaphore, counting semaphore, or mutex semaphore.
+ *
+ * @param xSemaphore The handle of the statically created semaphore
+ *
+ * @param ppxSemaphoreBuffer Used to pass back a pointer to the semaphore's
+ * data structure buffer
+ *
+ * @return pdTRUE if buffer was fetched. pdFALSE if the semaphore was not
+ * statically allocated.
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+    #define xSemaphoreGetStaticBuffer( xSemaphore, ppxSemaphoreBuffer )    xQueueGenericGetStaticBuffers( ( QueueHandle_t ) ( xSemaphore ), NULL, ( ppxSemaphoreBuffer ) )
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+
 #endif /* SEMAPHORE_H */
diff --git a/include/stream_buffer.h b/include/stream_buffer.h
@@ -260,6 +260,37 @@ typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuf
     xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), pdFALSE, ( pucStreamBufferStorageArea ), ( pxStaticStreamBuffer ), ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) )
 #endif
 
+/**
+ * stream_buffer.h
+ *
+ * @code{c}
+ * BaseType_t xStreamBufferGetStaticBuffers( StreamBufferHandle_t xStreamBuffer,
+ *                                           uint8_t ** ppucStreamBufferStorageArea,
+ *                                           StaticStreamBuffer_t ** ppxStaticStreamBuffer );
+ * @endcode
+ *
+ * This function fetches the pointers to the memory buffers of a statically
+ * created stream buffer.
+ *
+ * @param xStreamBuffer The handle to the stream buffer
+ *
+ * @param ppucStreamBufferStorageArea Used to pass back a pointer to the stream
+ * buffer's storage area buffer.
+ *
+ * @param ppxStaticStreamBuffer Used to pass back a pointer to the stream
+ * buffer's data structure buffer.
+ *
+ * @return pdTRUE if buffers were fetched. pdFALSE if the stream buffer was not
+ * statically created.
+ *
+ * \defgroup xStreamBufferGetStaticBuffers xStreamBufferGetStaticBuffers
+ * \ingroup StreamBufferManagement
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+    #define xStreamBufferGetStaticBuffers( xStreamBuffer, ppucStreamBufferStorageArea, ppxStaticStreamBuffer ) \
+    xStreamBufferGenericGetStaticBuffers( ( xStreamBuffer ), ( ppucStreamBufferStorageArea ), ( ppxStaticStreamBuffer ) )
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+
 /**
  * stream_buffer.h
  *
@@ -895,6 +926,16 @@ StreamBufferHandle_t xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes,
                                                        StreamBufferCallbackFunction_t pxSendCompletedCallback,
                                                        StreamBufferCallbackFunction_t pxReceiveCompletedCallback ) PRIVILEGED_FUNCTION;
 
+/*
+ * Generic version of the function used to get the buffers of statically created
+ * stream or message buffer.
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+    BaseType_t xStreamBufferGenericGetStaticBuffers( StreamBufferHandle_t xStreamBuffer,
+                                                     uint8_t ** ppucStreamBufferStorageArea,
+                                                     StaticStreamBuffer_t ** ppxStaticStreamBuffer ) PRIVILEGED_FUNCTION;
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+
 size_t xStreamBufferNextMessageLengthBytes( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
 
 #if ( configUSE_TRACE_FACILITY == 1 )
diff --git a/include/task.h b/include/task.h
@@ -1509,6 +1509,36 @@ char * pcTaskGetName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint !e
  */
 TaskHandle_t xTaskGetHandle( const char * pcNameToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
 
+/**
+ * task. h
+ * @code{c}
+ * BaseType_t xTaskGetStaticBuffers( TaskHandle_t xTask,
+ *                                   StackType_t ** ppuxStackBuffer,
+ *                                   StaticTask_t ** ppxTaskBuffer );
+ * @endcode
+ *
+ * This function fetches a pointer to the memory buffers of a statically created
+ * task.
+ *
+ * @param xTask The handle of the statically created task
+ *
+ * @param ppuxStackBuffer Used to pass back a pointer to the task's stack buffer
+ *
+ * @param ppxTaskBuffer Used to pass back a pointer to the task's data structure
+ * buffer
+ *
+ * @return pdTRUE if buffers were fetched. pdFALSE if the task was not
+ * statically created.
+ *
+ * \defgroup xTaskGetStaticBuffers xTaskGetStaticBuffers
+ * \ingroup TaskUtils
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+    BaseType_t xTaskGetStaticBuffers( TaskHandle_t xTask,
+                                      StackType_t ** ppuxStackBuffer,
+                                      StaticTask_t ** ppxTaskBuffer ) PRIVILEGED_FUNCTION;
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+
 /**
  * task.h
  * @code{c}
diff --git a/include/timers.h b/include/timers.h
@@ -1323,6 +1323,26 @@ TickType_t xTimerGetPeriod( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  */
 TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
 
+/**
+ * BaseType_t xTimerGetStaticBuffer( TimerHandle_t xTimer,
+ *                                   StaticTimer_t ** ppxTimerBuffer );
+ *
+ * This function fetches a pointer to the memory buffer of a statically created
+ * timer.
+ *
+ * @param xTimer The handle of the timer
+ *
+ * @param ppxTaskBuffer Used to pass back a pointer to the timers's data
+ * structure buffer.
+ *
+ * @return pdTRUE if the buffer were fetched. pdFALSE if the timer was not
+ * statically created.
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+    BaseType_t xTimerGetStaticBuffer( TimerHandle_t xTimer,
+                                      StaticTimer_t ** ppxTimerBuffer ) PRIVILEGED_FUNCTION;
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+
 /*
  * Functions beyond this part are not part of the public API and are intended
  * for use by the kernel only.
diff --git a/queue.c b/queue.c
diff --git a/stream_buffer.c b/stream_buffer.c
diff --git a/tasks.c b/tasks.c
diff --git a/timers.c b/timers.c
