From b5d1b972cc2483d4397bbc4f0046b07fc4c3b698 Mon Sep 17 00:00:00 2001 From: Gaurav-Aggarwal-AWS <33462878+aggarg@users.noreply.github.com> Date: Tue, 21 Jan 2025 15:17:10 +0530 Subject: [PATCH] Update stream and message buffer documentation (#1226) Signed-off-by: Gaurav Aggarwal --- include/message_buffer.h | 60 ++++++++++++++++++++-------------------- include/stream_buffer.h | 48 ++++++++++++++++---------------- 2 files changed, 54 insertions(+), 54 deletions(-) diff --git a/include/message_buffer.h b/include/message_buffer.h index 975a7e343..9fb97ffd0 100644 --- a/include/message_buffer.h +++ b/include/message_buffer.h @@ -43,12 +43,12 @@ * writer and reader to be different tasks or interrupts, but, unlike other * FreeRTOS objects, it is not safe to have multiple different writers or * multiple different readers. If there are to be multiple different writers - * then the application writer must place each call to a writing API function - * (such as xMessageBufferSend()) inside a critical section and set the send - * block time to 0. Likewise, if there are to be multiple different readers - * then the application writer must place each call to a reading API function - * (such as xMessageBufferRead()) inside a critical section and set the receive - * timeout to 0. + * then the application writer must serialize calls to writing API functions + * (such as xStreamBufferSend()). Likewise, if there are to be multiple + * different readers then the application writer must serialize calls to reading + * API functions (such as xStreamBufferReceive()). One way to achieve such + * serialization in single core or SMP kernel is to place each API call inside a + * critical section and use a block time of 0. * * Message buffers hold variable length messages. To enable that, when a * message is written to the message buffer an additional sizeof( size_t ) bytes @@ -306,12 +306,12 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * writer and reader to be different tasks or interrupts, but, unlike other * FreeRTOS objects, it is not safe to have multiple different writers or * multiple different readers. If there are to be multiple different writers - * then the application writer must place each call to a writing API function - * (such as xMessageBufferSend()) inside a critical section and set the send - * block time to 0. Likewise, if there are to be multiple different readers - * then the application writer must place each call to a reading API function - * (such as xMessageBufferRead()) inside a critical section and set the receive - * block time to 0. + * then the application writer must serialize calls to writing API functions + * (such as xStreamBufferSend()). Likewise, if there are to be multiple + * different readers then the application writer must serialize calls to reading + * API functions (such as xStreamBufferReceive()). One way to achieve such + * serialization in single core or SMP kernel is to place each API call inside a + * critical section and use a block time of 0. * * Use xMessageBufferSend() to write to a message buffer from a task. Use * xMessageBufferSendFromISR() to write to a message buffer from an interrupt @@ -409,12 +409,12 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * writer and reader to be different tasks or interrupts, but, unlike other * FreeRTOS objects, it is not safe to have multiple different writers or * multiple different readers. If there are to be multiple different writers - * then the application writer must place each call to a writing API function - * (such as xMessageBufferSend()) inside a critical section and set the send - * block time to 0. Likewise, if there are to be multiple different readers - * then the application writer must place each call to a reading API function - * (such as xMessageBufferRead()) inside a critical section and set the receive - * block time to 0. + * then the application writer must serialize calls to writing API functions + * (such as xStreamBufferSend()). Likewise, if there are to be multiple + * different readers then the application writer must serialize calls to reading + * API functions (such as xStreamBufferReceive()). One way to achieve such + * serialization in single core or SMP kernel is to place each API call inside a + * critical section and use a block time of 0. * * Use xMessageBufferSend() to write to a message buffer from a task. Use * xMessageBufferSendFromISR() to write to a message buffer from an interrupt @@ -516,12 +516,12 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * writer and reader to be different tasks or interrupts, but, unlike other * FreeRTOS objects, it is not safe to have multiple different writers or * multiple different readers. If there are to be multiple different writers - * then the application writer must place each call to a writing API function - * (such as xMessageBufferSend()) inside a critical section and set the send - * block time to 0. Likewise, if there are to be multiple different readers - * then the application writer must place each call to a reading API function - * (such as xMessageBufferRead()) inside a critical section and set the receive - * block time to 0. + * then the application writer must serialize calls to writing API functions + * (such as xStreamBufferSend()). Likewise, if there are to be multiple + * different readers then the application writer must serialize calls to reading + * API functions (such as xStreamBufferReceive()). One way to achieve such + * serialization in single core or SMP kernel is to place each API call inside a + * critical section and use a block time of 0. * * Use xMessageBufferReceive() to read from a message buffer from a task. Use * xMessageBufferReceiveFromISR() to read from a message buffer from an @@ -610,12 +610,12 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * writer and reader to be different tasks or interrupts, but, unlike other * FreeRTOS objects, it is not safe to have multiple different writers or * multiple different readers. If there are to be multiple different writers - * then the application writer must place each call to a writing API function - * (such as xMessageBufferSend()) inside a critical section and set the send - * block time to 0. Likewise, if there are to be multiple different readers - * then the application writer must place each call to a reading API function - * (such as xMessageBufferRead()) inside a critical section and set the receive - * block time to 0. + * then the application writer must serialize calls to writing API functions + * (such as xStreamBufferSend()). Likewise, if there are to be multiple + * different readers then the application writer must serialize calls to reading + * API functions (such as xStreamBufferReceive()). One way to achieve such + * serialization in single core or SMP kernel is to place each API call inside a + * critical section and use a block time of 0. * * Use xMessageBufferReceive() to read from a message buffer from a task. Use * xMessageBufferReceiveFromISR() to read from a message buffer from an diff --git a/include/stream_buffer.h b/include/stream_buffer.h index 9b15c8aff..b0093fc80 100644 --- a/include/stream_buffer.h +++ b/include/stream_buffer.h @@ -40,12 +40,12 @@ * writer and reader to be different tasks or interrupts, but, unlike other * FreeRTOS objects, it is not safe to have multiple different writers or * multiple different readers. If there are to be multiple different writers - * then the application writer must place each call to a writing API function - * (such as xStreamBufferSend()) inside a critical section and set the send - * block time to 0. Likewise, if there are to be multiple different readers - * then the application writer must place each call to a reading API function - * (such as xStreamBufferReceive()) inside a critical section section and set the - * receive block time to 0. + * then the application writer must serialize calls to writing API functions + * (such as xStreamBufferSend()). Likewise, if there are to be multiple + * different readers then the application writer must serialize calls to reading + * API functions (such as xStreamBufferReceive()). One way to achieve such + * serialization in single core or SMP kernel is to place each API call inside a + * critical section and use a block time of 0. * */ @@ -514,12 +514,12 @@ typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuf * writer and reader to be different tasks or interrupts, but, unlike other * FreeRTOS objects, it is not safe to have multiple different writers or * multiple different readers. If there are to be multiple different writers - * then the application writer must place each call to a writing API function - * (such as xStreamBufferSend()) inside a critical section and set the send - * block time to 0. Likewise, if there are to be multiple different readers - * then the application writer must place each call to a reading API function - * (such as xStreamBufferReceive()) inside a critical section and set the receive - * block time to 0. + * then the application writer must serialize calls to writing API functions + * (such as xStreamBufferSend()). Likewise, if there are to be multiple + * different readers then the application writer must serialize calls to reading + * API functions (such as xStreamBufferReceive()). One way to achieve such + * serialization in single core or SMP kernel is to place each API call inside a + * critical section and use a block time of 0. * * Use xStreamBufferSend() to write to a stream buffer from a task. Use * xStreamBufferSendFromISR() to write to a stream buffer from an interrupt @@ -615,12 +615,12 @@ size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer, * writer and reader to be different tasks or interrupts, but, unlike other * FreeRTOS objects, it is not safe to have multiple different writers or * multiple different readers. If there are to be multiple different writers - * then the application writer must place each call to a writing API function - * (such as xStreamBufferSend()) inside a critical section and set the send - * block time to 0. Likewise, if there are to be multiple different readers - * then the application writer must place each call to a reading API function - * (such as xStreamBufferReceive()) inside a critical section and set the receive - * block time to 0. + * then the application writer must serialize calls to writing API functions + * (such as xStreamBufferSend()). Likewise, if there are to be multiple + * different readers then the application writer must serialize calls to reading + * API functions (such as xStreamBufferReceive()). One way to achieve such + * serialization in single core or SMP kernel is to place each API call inside a + * critical section and use a block time of 0. * * Use xStreamBufferSend() to write to a stream buffer from a task. Use * xStreamBufferSendFromISR() to write to a stream buffer from an interrupt @@ -718,12 +718,12 @@ size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer, * writer and reader to be different tasks or interrupts, but, unlike other * FreeRTOS objects, it is not safe to have multiple different writers or * multiple different readers. If there are to be multiple different writers - * then the application writer must place each call to a writing API function - * (such as xStreamBufferSend()) inside a critical section and set the send - * block time to 0. Likewise, if there are to be multiple different readers - * then the application writer must place each call to a reading API function - * (such as xStreamBufferReceive()) inside a critical section and set the receive - * block time to 0. + * then the application writer must serialize calls to writing API functions + * (such as xStreamBufferSend()). Likewise, if there are to be multiple + * different readers then the application writer must serialize calls to reading + * API functions (such as xStreamBufferReceive()). One way to achieve such + * serialization in single core or SMP kernel is to place each API call inside a + * critical section and use a block time of 0. * * Use xStreamBufferReceive() to read from a stream buffer from a task. Use * xStreamBufferReceiveFromISR() to read from a stream buffer from an