Add functions to get the buffers of statically created objects (#641)
Added various ...GetStaticBuffer() functions to get the buffers of statically
created objects.
---------
Co-authored-by: Paul Bartell <pbartell@amazon.com>
Co-authored-by: Nikhil Kamath <110539926+amazonKamath@users.noreply.github.com>
Co-authored-by: Gaurav Aggarwal <aggarg@amazon.com>
diff --git a/.github/lexicon.txt b/.github/lexicon.txt
index 47d2349..e7ded97 100644
--- a/.github/lexicon.txt
+++ b/.github/lexicon.txt
@@ -1464,13 +1464,24 @@
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 @@
xeventgroupdelete
xeventgroupgetbits
xeventgroupgetbitsfromisr
+xeventgroupgetstaticbuffer
xeventgroupsetbits
xeventgroupsetbitsfromisr
xeventgroupsync
@@ -2796,6 +2808,7 @@
xmessagebuffer
xmessagebuffercreate
xmessagebuffercreatestatic
+xmessagebuffergetstaticbuffers
xmessagebufferisempty
xmessagebufferisfull
xmessagebuffernextlengthbytes
@@ -2865,6 +2878,7 @@
xqueuegenericsend
xqueuegenericsendfromisr
xqueuegetmutexholder
+xqueuegetstaticbuffers
xqueuegivefromisr
xqueuegivemutexrecursive
xqueueorsemaphore
@@ -2919,6 +2933,7 @@
xsemaphorecreaterecursivemutexstatic
xsemaphoregetmutexholder
xsemaphoregetmutexholderfromisr
+xsemaphoregetstaticbuffer
xsemaphoregive
xsemaphoregivefromisr
xsemaphoregivemutexrecursive
@@ -2943,6 +2958,7 @@
xstreambufferbytesavailable
xstreambuffercreate
xstreambuffercreatestatic
+xstreambuffergetstaticbuffers
xstreambufferisempty
xstreambufferisfull
xstreambuffernextmessagelengthbytes
@@ -2981,6 +2997,7 @@
xtaskgethandle
xtaskgetidletaskhandle
xtaskgetschedulerstate
+xtaskgetstaticbuffers
xtaskgettickcount
xtaskgettickcountfromisr
xtaskhandle
@@ -3048,6 +3065,7 @@
xtimergetexpirytime
xtimergetperiod
xtimergetreloadmode
+xtimergetstaticbuffer
xtimergettimerdaemontaskhandle
xtimeristimeractive
xtimerlistitem
@@ -3081,3 +3099,4 @@
xxr
xyieldpending
xzr
+
diff --git a/event_groups.c b/event_groups.c
index 7c86e60..5c4b429 100644
--- a/event_groups.c
+++ b/event_groups.c
@@ -677,6 +677,42 @@
}
/*-----------------------------------------------------------*/
+#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
index 3f37d90..47572ce 100644
--- a/include/event_groups.h
+++ b/include/event_groups.h
@@ -763,6 +763,28 @@
*/
void vEventGroupDelete( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION;
+/**
+ * event_groups.h
+ * @code{c}
+ * BaseType_t xEventGroupGetStaticBuffer( EventGroupHandle_t xEventGroup,
+ * StaticEventGroup_t ** ppxEventGroupBuffer );
+ * @endcode
+ *
+ * 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.
+ *
+ * @param xEventGroup The event group for which to retrieve the buffer.
+ *
+ * @param ppxEventGroupBuffer Used to return a pointer to the event groups's
+ * data structure buffer.
+ *
+ * @return pdTRUE if the buffer was retrieved, pdFALSE otherwise.
+ */
+#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
index b56dd35..74fab11 100644
--- a/include/message_buffer.h
+++ b/include/message_buffer.h
@@ -249,6 +249,37 @@
* message_buffer.h
*
* @code{c}
+ * BaseType_t xMessageBufferGetStaticBuffers( MessageBufferHandle_t xMessageBuffer,
+ * uint8_t ** ppucMessageBufferStorageArea,
+ * StaticMessageBuffer_t ** ppxStaticMessageBuffer );
+ * @endcode
+ *
+ * Retrieve pointers to a statically created message buffer's data structure
+ * buffer and storage area buffer. These are the same buffers that are supplied
+ * at the time of creation.
+ *
+ * @param xMessageBuffer The message buffer for which to retrieve the buffers.
+ *
+ * @param ppucMessageBufferStorageArea Used to return a pointer to the
+ * message buffer's storage area buffer.
+ *
+ * @param ppxStaticMessageBuffer Used to return a pointer to the message
+ * buffer's data structure buffer.
+ *
+ * @return pdTRUE if buffers were retrieved, pdFALSE otherwise..
+ *
+ * \defgroup xMessageBufferGetStaticBuffers xMessageBufferGetStaticBuffers
+ * \ingroup MessageBufferManagement
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+ #define xMessageBufferGetStaticBuffers( xMessageBuffer, ppucMessageBufferStorageArea, ppxStaticMessageBuffer ) \
+ xStreamBufferGetStaticBuffers( ( xMessageBuffer ), ( ppucMessageBufferStorageArea ), ( ppxStaticMessageBuffer ) )
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+
+/**
+ * message_buffer.h
+ *
+ * @code{c}
* size_t xMessageBufferSend( MessageBufferHandle_t xMessageBuffer,
* const void *pvTxData,
* size_t xDataLengthBytes,
diff --git a/include/queue.h b/include/queue.h
index f488a2e..66c8286 100644
--- a/include/queue.h
+++ b/include/queue.h
@@ -238,6 +238,35 @@
/**
* queue. h
* @code{c}
+ * BaseType_t xQueueGetStaticBuffers( QueueHandle_t xQueue,
+ * uint8_t ** ppucQueueStorage,
+ * StaticQueue_t ** ppxStaticQueue );
+ * @endcode
+ *
+ * Retrieve pointers to a statically created queue's data structure buffer
+ * and storage area buffer. These are the same buffers that are supplied
+ * at the time of creation.
+ *
+ * @param xQueue The queue for which to retrieve the buffers.
+ *
+ * @param ppucQueueStorage Used to return a pointer to the queue's storage
+ * area buffer.
+ *
+ * @param ppxStaticQueue Used to return a pointer to the queue's data
+ * structure buffer.
+ *
+ * @return pdTRUE if buffers were retrieved, pdFALSE otherwise.
+ *
+ * \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}
* BaseType_t xQueueSendToToFront(
* QueueHandle_t xQueue,
* const void *pvItemToQueue,
@@ -1543,6 +1572,18 @@
#endif
/*
+ * Generic version of the function used to retrieve the buffers of statically
+ * created queues. This is called by other functions and macros that retrieve
+ * 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
index c2206fa..7977a01 100644
--- a/include/semphr.h
+++ b/include/semphr.h
@@ -1190,4 +1190,25 @@
*/
#define uxSemaphoreGetCountFromISR( xSemaphore ) uxQueueMessagesWaitingFromISR( ( QueueHandle_t ) ( xSemaphore ) )
+/**
+ * semphr.h
+ * @code{c}
+ * BaseType_t xSemaphoreGetStaticBuffer( SemaphoreHandle_t xSemaphore );
+ * @endcode
+ *
+ * Retrieve pointer to a statically created binary semaphore, counting semaphore,
+ * or mutex semaphore's data structure buffer. This is the same buffer that is
+ * supplied at the time of creation.
+ *
+ * @param xSemaphore The semaphore for which to retrieve the buffer.
+ *
+ * @param ppxSemaphoreBuffer Used to return a pointer to the semaphore's
+ * data structure buffer.
+ *
+ * @return pdTRUE if buffer was retrieved, pdFALSE otherwise.
+ */
+#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
index d65ed9e..521c178 100644
--- a/include/stream_buffer.h
+++ b/include/stream_buffer.h
@@ -264,6 +264,38 @@
* stream_buffer.h
*
* @code{c}
+ * BaseType_t xStreamBufferGetStaticBuffers( StreamBufferHandle_t xStreamBuffer,
+ * uint8_t ** ppucStreamBufferStorageArea,
+ * StaticStreamBuffer_t ** ppxStaticStreamBuffer );
+ * @endcode
+ *
+ * Retrieve pointers to a statically created stream buffer's data structure
+ * buffer and storage area buffer. These are the same buffers that are supplied
+ * at the time of creation.
+ *
+ * @param xStreamBuffer The stream buffer for which to retrieve the buffers.
+ *
+ * @param ppucStreamBufferStorageArea Used to return a pointer to the stream
+ * buffer's storage area buffer.
+ *
+ * @param ppxStaticStreamBuffer Used to return a pointer to the stream
+ * buffer's data structure buffer.
+ *
+ * @return pdTRUE if buffers were retrieved, pdFALSE otherwise.
+ *
+ * \defgroup xStreamBufferGetStaticBuffers xStreamBufferGetStaticBuffers
+ * \ingroup StreamBufferManagement
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+ BaseType_t xStreamBufferGetStaticBuffers( StreamBufferHandle_t xStreamBuffer,
+ uint8_t ** ppucStreamBufferStorageArea,
+ StaticStreamBuffer_t ** ppxStaticStreamBuffer ) PRIVILEGED_FUNCTION;
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+
+/**
+ * stream_buffer.h
+ *
+ * @code{c}
* size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
* const void *pvTxData,
* size_t xDataLengthBytes,
diff --git a/include/task.h b/include/task.h
index 08c14dd..054f436 100644
--- a/include/task.h
+++ b/include/task.h
@@ -1510,6 +1510,36 @@
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
+ *
+ * Retrieve pointers to a statically created task's data structure
+ * buffer and stack buffer. These are the same buffers that are supplied
+ * at the time of creation.
+ *
+ * @param xTask The task for which to retrieve the buffers.
+ *
+ * @param ppuxStackBuffer Used to return a pointer to the task's stack buffer.
+ *
+ * @param ppxTaskBuffer Used to return a pointer to the task's data structure
+ * buffer.
+ *
+ * @return pdTRUE if buffers were retrieved, pdFALSE otherwise.
+ *
+ * \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}
* UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );
diff --git a/include/timers.h b/include/timers.h
index 6a064d6..2967a46 100644
--- a/include/timers.h
+++ b/include/timers.h
@@ -1323,6 +1323,26 @@
*/
TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
+/**
+ * BaseType_t xTimerGetStaticBuffer( TimerHandle_t xTimer,
+ * StaticTimer_t ** ppxTimerBuffer );
+ *
+ * Retrieve pointer to a statically created timer's data structure
+ * buffer. This is the same buffer that is supplied at the time of
+ * creation.
+ *
+ * @param xTimer The timer for which to retrieve the buffer.
+ *
+ * @param ppxTaskBuffer Used to return a pointer to the timers's data
+ * structure buffer.
+ *
+ * @return pdTRUE if the buffer was retrieved, pdFALSE otherwise.
+ */
+#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
index ca6bfbc..662052f 100644
--- a/queue.c
+++ b/queue.c
@@ -419,6 +419,55 @@
#endif /* configSUPPORT_STATIC_ALLOCATION */
/*-----------------------------------------------------------*/
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+
+ BaseType_t xQueueGenericGetStaticBuffers( QueueHandle_t xQueue,
+ uint8_t ** ppucQueueStorage,
+ StaticQueue_t ** ppxStaticQueue )
+ {
+ BaseType_t xReturn;
+ Queue_t * const pxQueue = xQueue;
+
+ configASSERT( pxQueue );
+ configASSERT( ppxStaticQueue );
+
+ #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
+ {
+ /* Check if the queue was statically allocated. */
+ if( pxQueue->ucStaticallyAllocated == ( uint8_t ) pdTRUE )
+ {
+ if( ppucQueueStorage != NULL )
+ {
+ *ppucQueueStorage = ( uint8_t * ) pxQueue->pcHead;
+ }
+
+ *ppxStaticQueue = ( StaticQueue_t * ) pxQueue;
+ xReturn = pdTRUE;
+ }
+ else
+ {
+ xReturn = pdFALSE;
+ }
+ }
+ #else /* configSUPPORT_DYNAMIC_ALLOCATION */
+ {
+ /* Queue must have been statically allocated. */
+ if( ppucQueueStorage != NULL )
+ {
+ *ppucQueueStorage = ( uint8_t * ) pxQueue->pcHead;
+ }
+
+ *ppxStaticQueue = ( StaticQueue_t * ) pxQueue;
+ xReturn = pdTRUE;
+ }
+ #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
+
+ return xReturn;
+ }
+
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+/*-----------------------------------------------------------*/
+
#if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
QueueHandle_t xQueueGenericCreate( const UBaseType_t uxQueueLength,
diff --git a/stream_buffer.c b/stream_buffer.c
index 0d0b335..938c405 100644
--- a/stream_buffer.c
+++ b/stream_buffer.c
@@ -472,6 +472,34 @@
#endif /* ( configSUPPORT_STATIC_ALLOCATION == 1 ) */
/*-----------------------------------------------------------*/
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+ BaseType_t xStreamBufferGetStaticBuffers( StreamBufferHandle_t xStreamBuffer,
+ uint8_t ** ppucStreamBufferStorageArea,
+ StaticStreamBuffer_t ** ppxStaticStreamBuffer )
+ {
+ BaseType_t xReturn;
+ const StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
+
+ configASSERT( pxStreamBuffer );
+ configASSERT( ppucStreamBufferStorageArea );
+ configASSERT( ppxStaticStreamBuffer );
+
+ if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_STATICALLY_ALLOCATED ) != ( uint8_t ) 0 )
+ {
+ *ppucStreamBufferStorageArea = pxStreamBuffer->pucBuffer;
+ *ppxStaticStreamBuffer = ( StaticStreamBuffer_t * ) pxStreamBuffer;
+ xReturn = pdTRUE;
+ }
+ else
+ {
+ xReturn = pdFALSE;
+ }
+
+ return xReturn;
+ }
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+/*-----------------------------------------------------------*/
+
void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer )
{
StreamBuffer_t * pxStreamBuffer = xStreamBuffer;
diff --git a/tasks.c b/tasks.c
index 0e7a56c..befd63e 100644
--- a/tasks.c
+++ b/tasks.c
@@ -2489,6 +2489,53 @@
#endif /* INCLUDE_xTaskGetHandle */
/*-----------------------------------------------------------*/
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+
+ BaseType_t xTaskGetStaticBuffers( TaskHandle_t xTask,
+ StackType_t ** ppuxStackBuffer,
+ StaticTask_t ** ppxTaskBuffer )
+ {
+ BaseType_t xReturn;
+ TCB_t * pxTCB;
+
+ configASSERT( ppuxStackBuffer != NULL );
+ configASSERT( ppxTaskBuffer != NULL );
+
+ pxTCB = prvGetTCBFromHandle( xTask );
+
+ #if ( tskSTATIC_AND_DYNAMIC_ALLOCATION_POSSIBLE == 1 )
+ {
+ if( pxTCB->ucStaticallyAllocated == tskSTATICALLY_ALLOCATED_STACK_AND_TCB )
+ {
+ *ppuxStackBuffer = pxTCB->pxStack;
+ *ppxTaskBuffer = ( StaticTask_t * ) pxTCB;
+ xReturn = pdTRUE;
+ }
+ else if( pxTCB->ucStaticallyAllocated == tskSTATICALLY_ALLOCATED_STACK_ONLY )
+ {
+ *ppuxStackBuffer = pxTCB->pxStack;
+ *ppxTaskBuffer = NULL;
+ xReturn = pdTRUE;
+ }
+ else
+ {
+ xReturn = pdFALSE;
+ }
+ }
+ #else /* tskSTATIC_AND_DYNAMIC_ALLOCATION_POSSIBLE == 1 */
+ {
+ *ppuxStackBuffer = pxTCB->pxStack;
+ *ppxTaskBuffer = ( StaticTask_t * ) pxTCB;
+ xReturn = pdTRUE;
+ }
+ #endif /* tskSTATIC_AND_DYNAMIC_ALLOCATION_POSSIBLE == 1 */
+
+ return xReturn;
+ }
+
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+/*-----------------------------------------------------------*/
+
#if ( configUSE_TRACE_FACILITY == 1 )
UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray,
diff --git a/timers.c b/timers.c
index 06a2927..76a59a8 100644
--- a/timers.c
+++ b/timers.c
@@ -510,6 +510,30 @@
}
/*-----------------------------------------------------------*/
+ #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+ BaseType_t xTimerGetStaticBuffer( TimerHandle_t xTimer,
+ StaticTimer_t ** ppxTimerBuffer )
+ {
+ BaseType_t xReturn;
+ Timer_t * pxTimer = xTimer;
+
+ configASSERT( ppxTimerBuffer != NULL );
+
+ if( ( pxTimer->ucStatus & tmrSTATUS_IS_STATICALLY_ALLOCATED ) != 0 )
+ {
+ *ppxTimerBuffer = ( StaticTimer_t * ) pxTimer;
+ xReturn = pdTRUE;
+ }
+ else
+ {
+ xReturn = pdFALSE;
+ }
+
+ return xReturn;
+ }
+ #endif /* configSUPPORT_STATIC_ALLOCATION */
+/*-----------------------------------------------------------*/
+
const char * pcTimerGetName( TimerHandle_t xTimer ) /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
{
Timer_t * pxTimer = xTimer;
