stream_buffer.h
Go to the documentation of this file.
/*
* FreeRTOS Kernel V10.0.0
* Copyright (C) 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of
* this software and associated documentation files (the "Software"), to deal in
* the Software without restriction, including without limitation the rights to
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
* the Software, and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software. If you wish to use our Amazon
* FreeRTOS name, please do so in a fair use way that does not cause confusion.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*
* http://www.FreeRTOS.org
* http://aws.amazon.com/freertos
*
* 1 tab == 4 spaces!
*/
/*
* Stream buffers are used to send a continuous stream of data from one task or
* interrupt to another. Their implementation is light weight, making them
* particularly suited for interrupt to task and core to core communication
* scenarios.
*
* ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
* implementation (so also the message buffer implementation, as message buffers
* are built on top of stream buffers) assumes there is only one task or
* interrupt that will write to the buffer (the writer), and only one task or
* interrupt that will read from the buffer (the reader). It is safe for the
* 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 xStreamBufferRead()) inside a critical section section and set the
* receive block time to 0.
*
*/
#ifndef STREAM_BUFFER_H
#define STREAM_BUFFER_H
typedef void * StreamBufferHandle_t;
#define xStreamBufferCreate( xBufferSizeBytes, xTriggerLevelBytes ) xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE )
#define xStreamBufferCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer ) xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE, pucStreamBufferStorageArea, pxStaticStreamBuffer )
size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
const void *pvTxData,
size_t xDataLengthBytes,
TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
const void *pvTxData,
size_t xDataLengthBytes,
BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
void *pvRxData,
size_t xBufferLengthBytes,
TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
void *pvRxData,
size_t xBufferLengthBytes,
BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel ) PRIVILEGED_FUNCTION;
BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
/* Functions below here are not part of the public API. */
StreamBufferHandle_t xStreamBufferGenericCreate( size_t xBufferSizeBytes,
size_t xTriggerLevelBytes,
BaseType_t xIsMessageBuffer ) PRIVILEGED_FUNCTION;
StreamBufferHandle_t xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes,
size_t xTriggerLevelBytes,
BaseType_t xIsMessageBuffer,
uint8_t * const pucStreamBufferStorageArea,
StaticStreamBuffer_t * const pxStaticStreamBuffer ) PRIVILEGED_FUNCTION;
#if( configUSE_TRACE_FACILITY == 1 )
void vStreamBufferSetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer, UBaseType_t uxStreamBufferNumber ) PRIVILEGED_FUNCTION;
UBaseType_t uxStreamBufferGetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
uint8_t ucStreamBufferGetStreamBufferType( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
#endif
#if defined( __cplusplus )
extern "C" {
#endif
#endif /* !defined( STREAM_BUFFER_H ) */
StreamBufferHandle_t
void * StreamBufferHandle_t
Definition: stream_buffer.h:61
xStreamBufferSetTriggerLevel
BaseType_t xStreamBufferSetTriggerLevel(StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:420
traceSTREAM_BUFFER_CREATE_FAILED
#define traceSTREAM_BUFFER_CREATE_FAILED(xIsMessageBuffer)
Definition: FreeRTOS.h:641
xTaskNotifyFromISR
#define xTaskNotifyFromISR(xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken)
Definition: task.h:1858
StreamBuffer_t
struct xSTREAM_BUFFER StreamBuffer_t
xStreamBufferReceiveCompletedFromISR
BaseType_t xStreamBufferReceiveCompletedFromISR(StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:988
task.h
vStreamBufferDelete
void vStreamBufferDelete(StreamBufferHandle_t xStreamBuffer)
Definition: stream_buffer.c:333
xStreamBufferReset
BaseType_t xStreamBufferReset(StreamBufferHandle_t xStreamBuffer) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:366
traceSTREAM_BUFFER_SEND_FAILED
#define traceSTREAM_BUFFER_SEND_FAILED(xStreamBuffer)
Definition: FreeRTOS.h:669
xStreamBufferIsEmpty
BaseType_t xStreamBufferIsEmpty(StreamBufferHandle_t xStreamBuffer) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:900
xStreamBufferReceiveCompletedFromISR
BaseType_t xStreamBufferReceiveCompletedFromISR(StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken)
Definition: stream_buffer.c:988
traceBLOCKING_ON_STREAM_BUFFER_SEND
#define traceBLOCKING_ON_STREAM_BUFFER_SEND(xStreamBuffer)
Definition: FreeRTOS.h:661
xSTATIC_STREAM_BUFFER
Definition: FreeRTOS.h:1152
prvReadBytesFromBuffer
static size_t prvReadBytesFromBuffer(StreamBuffer_t *pxStreamBuffer, uint8_t *pucData, size_t xMaxCount, size_t xBytesAvailable)
Definition: stream_buffer.c:1064
xSTREAM_BUFFER::xTaskWaitingToSend
volatile TaskHandle_t xTaskWaitingToSend
Definition: stream_buffer.c:145
xSTREAM_BUFFER::xLength
size_t xLength
Definition: stream_buffer.c:142
vPortFree
void vPortFree(void *pv)
Definition: heap_1.c:123
xStreamBufferReceiveFromISR
size_t xStreamBufferReceiveFromISR(StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, BaseType_t *const pxHigherPriorityTaskWoken)
Definition: stream_buffer.c:793
vTaskSetTimeOutState
void vTaskSetTimeOutState(TimeOut_t *const pxTimeOut) PRIVILEGED_FUNCTION
Definition: tasks.c:3085
xStreamBufferGenericCreateStatic
StreamBufferHandle_t xStreamBufferGenericCreateStatic(size_t xBufferSizeBytes, size_t xTriggerLevelBytes, BaseType_t xIsMessageBuffer, uint8_t *const pucStreamBufferStorageArea, StaticStreamBuffer_t *const pxStaticStreamBuffer) PRIVILEGED_FUNCTION
xStreamBufferSendCompletedFromISR
BaseType_t xStreamBufferSendCompletedFromISR(StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken)
Definition: stream_buffer.c:958
traceSTREAM_BUFFER_DELETE
#define traceSTREAM_BUFFER_DELETE(xStreamBuffer)
Definition: FreeRTOS.h:653
configMIN
#define configMIN(a, b)
Definition: FreeRTOS.h:895
xStreamBufferReceive
size_t xStreamBufferReceive(StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, TickType_t xTicksToWait) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:689
pdFAIL
#define pdFAIL
Definition: projdefs.h:49
eNoAction
@ eNoAction
Definition: task.h:84
xStreamBufferSend
size_t xStreamBufferSend(StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, TickType_t xTicksToWait)
Definition: stream_buffer.c:485
xStreamBufferSendFromISR
size_t xStreamBufferSendFromISR(StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, BaseType_t *const pxHigherPriorityTaskWoken)
Definition: stream_buffer.c:586
xTaskCheckForTimeOut
BaseType_t xTaskCheckForTimeOut(TimeOut_t *const pxTimeOut, TickType_t *const pxTicksToWait) PRIVILEGED_FUNCTION
Definition: tasks.c:3105
xTaskNotifyWait
BaseType_t xTaskNotifyWait(uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait) PRIVILEGED_FUNCTION
Definition: tasks.c:4483
xSTREAM_BUFFER::ucFlags
uint8_t ucFlags
Definition: stream_buffer.c:147
traceSTREAM_BUFFER_RECEIVE_FAILED
#define traceSTREAM_BUFFER_RECEIVE_FAILED(xStreamBuffer)
Definition: FreeRTOS.h:685
sbSEND_COMPLETED
#define sbSEND_COMPLETED(pxStreamBuffer)
Definition: stream_buffer.c:93
StaticStreamBuffer_t
struct xSTATIC_STREAM_BUFFER StaticStreamBuffer_t
vStreamBufferDelete
void vStreamBufferDelete(StreamBufferHandle_t xStreamBuffer) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:333
sbRECEIVE_COMPLETED
#define sbRECEIVE_COMPLETED(pxStreamBuffer)
Definition: stream_buffer.c:54
prvWriteBytesToBuffer
static size_t prvWriteBytesToBuffer(StreamBuffer_t *const pxStreamBuffer, const uint8_t *pucData, size_t xCount) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:1018
traceSTREAM_BUFFER_SEND
#define traceSTREAM_BUFFER_SEND(xStreamBuffer, xBytesSent)
Definition: FreeRTOS.h:665
pdPASS
#define pdPASS
Definition: projdefs.h:48
PRIVILEGED_FUNCTION
#define PRIVILEGED_FUNCTION
Definition: mpu_wrappers.h:174
TickType_t
uint32_t TickType_t
Definition: portmacro.h:64
traceSTREAM_BUFFER_RESET
#define traceSTREAM_BUFFER_RESET(xStreamBuffer)
Definition: FreeRTOS.h:657
traceBLOCKING_ON_STREAM_BUFFER_RECEIVE
#define traceBLOCKING_ON_STREAM_BUFFER_RECEIVE(xStreamBuffer)
Definition: FreeRTOS.h:677
taskENTER_CRITICAL
#define taskENTER_CRITICAL()
Definition: task.h:179
TaskHandle_t
void * TaskHandle_t
Definition: task.h:62
traceSTREAM_BUFFER_RECEIVE_FROM_ISR
#define traceSTREAM_BUFFER_RECEIVE_FROM_ISR(xStreamBuffer, xReceivedLength)
Definition: FreeRTOS.h:689
pdFALSE
#define pdFALSE
Definition: projdefs.h:45
sbSEND_COMPLETE_FROM_ISR
#define sbSEND_COMPLETE_FROM_ISR(pxStreamBuffer, pxHigherPriorityTaskWoken)
Definition: stream_buffer.c:108
UBaseType_t
unsigned long UBaseType_t
Definition: portmacro.h:58
prvInitialiseNewStreamBuffer
static PRIVILEGED_FUNCTION void prvInitialiseNewStreamBuffer(StreamBuffer_t *const pxStreamBuffer, uint8_t *const pucBuffer, size_t xBufferSizeBytes, size_t xTriggerLevelBytes, BaseType_t xIsMessageBuffer) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:1139
xSTREAM_BUFFER::xTriggerLevelBytes
size_t xTriggerLevelBytes
Definition: stream_buffer.c:143
xTIME_OUT
Definition: task.h:95
xStreamBufferBytesAvailable
size_t xStreamBufferBytesAvailable(StreamBufferHandle_t xStreamBuffer) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:473
xStreamBufferReceive
size_t xStreamBufferReceive(StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, TickType_t xTicksToWait)
Definition: stream_buffer.c:689
sbFLAGS_IS_STATICALLY_ALLOCATED
#define sbFLAGS_IS_STATICALLY_ALLOCATED
Definition: stream_buffer.c:133
xSTREAM_BUFFER
Definition: stream_buffer.c:139
traceSTREAM_BUFFER_CREATE_STATIC_FAILED
#define traceSTREAM_BUFFER_CREATE_STATIC_FAILED(xReturn, xIsMessageBuffer)
Definition: FreeRTOS.h:645
traceSTREAM_BUFFER_SEND_FROM_ISR
#define traceSTREAM_BUFFER_SEND_FROM_ISR(xStreamBuffer, xBytesSent)
Definition: FreeRTOS.h:673
xSTREAM_BUFFER::xHead
volatile size_t xHead
Definition: stream_buffer.c:141
xStreamBufferReceiveFromISR
size_t xStreamBufferReceiveFromISR(StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, BaseType_t *const pxHigherPriorityTaskWoken) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:793
xStreamBufferGenericCreate
StreamBufferHandle_t xStreamBufferGenericCreate(size_t xBufferSizeBytes, size_t xTriggerLevelBytes, BaseType_t xIsMessageBuffer)
Definition: stream_buffer.c:217
FreeRTOS.h
traceSTREAM_BUFFER_RECEIVE
#define traceSTREAM_BUFFER_RECEIVE(xStreamBuffer, xReceivedLength)
Definition: FreeRTOS.h:681
xSTREAM_BUFFER::xTaskWaitingToReceive
volatile TaskHandle_t xTaskWaitingToReceive
Definition: stream_buffer.c:144
portCLEAR_INTERRUPT_MASK_FROM_ISR
#define portCLEAR_INTERRUPT_MASK_FROM_ISR(x)
Definition: portmacro.h:110
xStreamBufferSendCompletedFromISR
BaseType_t xStreamBufferSendCompletedFromISR(StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:958
BaseType_t
long BaseType_t
Definition: portmacro.h:57
pdTRUE
#define pdTRUE
Definition: projdefs.h:46
xStreamBufferIsEmpty
BaseType_t xStreamBufferIsEmpty(StreamBufferHandle_t xStreamBuffer)
Definition: stream_buffer.c:900
xStreamBufferReset
BaseType_t xStreamBufferReset(StreamBufferHandle_t xStreamBuffer)
Definition: stream_buffer.c:366
xSTREAM_BUFFER::xTail
volatile size_t xTail
Definition: stream_buffer.c:140
xTaskGetCurrentTaskHandle
TaskHandle_t xTaskGetCurrentTaskHandle(void) PRIVILEGED_FUNCTION
Definition: tasks.c:3755
sbRECEIVE_COMPLETED_FROM_ISR
#define sbRECEIVE_COMPLETED_FROM_ISR(pxStreamBuffer, pxHigherPriorityTaskWoken)
Definition: stream_buffer.c:69
prvReadMessageFromBuffer
static size_t prvReadMessageFromBuffer(StreamBuffer_t *pxStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, size_t xBytesAvailable, size_t xBytesToStoreMessageLength) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:850
xStreamBufferBytesAvailable
size_t xStreamBufferBytesAvailable(StreamBufferHandle_t xStreamBuffer)
Definition: stream_buffer.c:473
xStreamBufferSpacesAvailable
size_t xStreamBufferSpacesAvailable(StreamBufferHandle_t xStreamBuffer) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:449
taskEXIT_CRITICAL
#define taskEXIT_CRITICAL()
Definition: task.h:194
stream_buffer.h
xStreamBufferSpacesAvailable
size_t xStreamBufferSpacesAvailable(StreamBufferHandle_t xStreamBuffer)
Definition: stream_buffer.c:449
xStreamBufferSendFromISR
size_t xStreamBufferSendFromISR(StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, BaseType_t *const pxHigherPriorityTaskWoken) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:586
xStreamBufferSetTriggerLevel
BaseType_t xStreamBufferSetTriggerLevel(StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel)
Definition: stream_buffer.c:420
prvBytesInBuffer
static size_t prvBytesInBuffer(const StreamBuffer_t *const pxStreamBuffer) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:1119
configASSERT
#define configASSERT(x)
Definition: FreeRTOS.h:235
sbBYTES_TO_STORE_MESSAGE_LENGTH
#define sbBYTES_TO_STORE_MESSAGE_LENGTH
Definition: stream_buffer.c:129
xSTREAM_BUFFER::pucBuffer
uint8_t * pucBuffer
Definition: stream_buffer.c:146
sbFLAGS_IS_MESSAGE_BUFFER
#define sbFLAGS_IS_MESSAGE_BUFFER
Definition: stream_buffer.c:132
xStreamBufferIsFull
BaseType_t xStreamBufferIsFull(StreamBufferHandle_t xStreamBuffer) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:923
xStreamBufferGenericCreate
StreamBufferHandle_t xStreamBufferGenericCreate(size_t xBufferSizeBytes, size_t xTriggerLevelBytes, BaseType_t xIsMessageBuffer) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:217
xStreamBufferSend
size_t xStreamBufferSend(StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, TickType_t xTicksToWait) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:485
xTaskNotifyStateClear
BaseType_t xTaskNotifyStateClear(TaskHandle_t xTask)
Definition: tasks.c:4882
prvWriteMessageToBuffer
static size_t prvWriteMessageToBuffer(StreamBuffer_t *const pxStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, size_t xSpace, size_t xRequiredSpace) PRIVILEGED_FUNCTION
Definition: stream_buffer.c:637
traceSTREAM_BUFFER_CREATE
#define traceSTREAM_BUFFER_CREATE(pxStreamBuffer, xIsMessageBuffer)
Definition: FreeRTOS.h:649
xStreamBufferIsFull
BaseType_t xStreamBufferIsFull(StreamBufferHandle_t xStreamBuffer)
Definition: stream_buffer.c:923
portSET_INTERRUPT_MASK_FROM_ISR
#define portSET_INTERRUPT_MASK_FROM_ISR()
Definition: portmacro.h:109
mtCOVERAGE_TEST_MARKER
#define mtCOVERAGE_TEST_MARKER()
Definition: FreeRTOS.h:787
pvPortMalloc
void * pvPortMalloc(size_t xWantedSize)
Definition: heap_1.c:71