0b46492740
* Let each stream/message can use its own sbSEND_COMPLETED In FreeRTOS.h, set the default value of configUSE_SB_COMPLETED_CALLBACK to zero, and add additional space for the function pointer when the buffer created statically. In stream_buffer.c, modify the macro of sbSEND_COMPLETED which let the stream buffer to use its own implementation, and then add an pointer to the stream buffer's structure, and modify the implementation of the buffer creating and initializing Co-authored-by: eddie9712 <qw1562435@gmail.com>
914 lines
42 KiB
C
914 lines
42 KiB
C
/*
|
|
* FreeRTOS Kernel <DEVELOPMENT BRANCH>
|
|
* Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
|
|
*
|
|
* SPDX-License-Identifier: MIT
|
|
*
|
|
* 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.
|
|
*
|
|
* 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.
|
|
*
|
|
* https://www.FreeRTOS.org
|
|
* https://github.com/FreeRTOS
|
|
*
|
|
*/
|
|
|
|
/*
|
|
* 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 xStreamBufferReceive()) inside a critical section section and set the
|
|
* receive block time to 0.
|
|
*
|
|
*/
|
|
|
|
#ifndef STREAM_BUFFER_H
|
|
#define STREAM_BUFFER_H
|
|
|
|
#ifndef INC_FREERTOS_H
|
|
#error "include FreeRTOS.h must appear in source files before include stream_buffer.h"
|
|
#endif
|
|
|
|
/* *INDENT-OFF* */
|
|
#if defined( __cplusplus )
|
|
extern "C" {
|
|
#endif
|
|
/* *INDENT-ON* */
|
|
|
|
/**
|
|
* Type by which stream buffers are referenced. For example, a call to
|
|
* xStreamBufferCreate() returns an StreamBufferHandle_t variable that can
|
|
* then be used as a parameter to xStreamBufferSend(), xStreamBufferReceive(),
|
|
* etc.
|
|
*/
|
|
struct StreamBufferDef_t;
|
|
typedef struct StreamBufferDef_t * StreamBufferHandle_t;
|
|
|
|
/**
|
|
* Type used as a stream buffer's optional callback.
|
|
*/
|
|
typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuffer,
|
|
BaseType_t xIsInsideISR,
|
|
BaseType_t * const pxHigherPriorityTaskWoken );
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes );
|
|
* @endcode
|
|
*
|
|
* Creates a new stream buffer using dynamically allocated memory. See
|
|
* xStreamBufferCreateStatic() for a version that uses statically allocated
|
|
* memory (memory that is allocated at compile time).
|
|
*
|
|
* configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in
|
|
* FreeRTOSConfig.h for xStreamBufferCreate() to be available.
|
|
*
|
|
* @param xBufferSizeBytes The total number of bytes the stream buffer will be
|
|
* able to hold at any one time.
|
|
*
|
|
* @param xTriggerLevelBytes The number of bytes that must be in the stream
|
|
* buffer before a task that is blocked on the stream buffer to wait for data is
|
|
* moved out of the blocked state. For example, if a task is blocked on a read
|
|
* of an empty stream buffer that has a trigger level of 1 then the task will be
|
|
* unblocked when a single byte is written to the buffer or the task's block
|
|
* time expires. As another example, if a task is blocked on a read of an empty
|
|
* stream buffer that has a trigger level of 10 then the task will not be
|
|
* unblocked until the stream buffer contains at least 10 bytes or the task's
|
|
* block time expires. If a reading task's block time expires before the
|
|
* trigger level is reached then the task will still receive however many bytes
|
|
* are actually available. Setting a trigger level of 0 will result in a
|
|
* trigger level of 1 being used. It is not valid to specify a trigger level
|
|
* that is greater than the buffer size.
|
|
*
|
|
* @param pxSendCompletedCallback Callback invoked when number of bytes at least equal to
|
|
* trigger level is sent to the stream buffer. If the parameter is NULL, it will use the default
|
|
* implementation provided by sbSEND_COMPLETED macro. To enable the callback,
|
|
* configUSE_SB_COMPLETED_CALLBACK must be set to 1 in FreeRTOSConfig.h.
|
|
*
|
|
* @param pxReceiveCompletedCallback Callback invoked when more than zero bytes are read from a
|
|
* stream buffer. If the parameter is NULL, it will use the default
|
|
* implementation provided by sbRECEIVE_COMPLETED macro. To enable the callback,
|
|
* configUSE_SB_COMPLETED_CALLBACK must be set to 1 in FreeRTOSConfig.h.
|
|
*
|
|
* @return If NULL is returned, then the stream buffer cannot be created
|
|
* because there is insufficient heap memory available for FreeRTOS to allocate
|
|
* the stream buffer data structures and storage area. A non-NULL value being
|
|
* returned indicates that the stream buffer has been created successfully -
|
|
* the returned value should be stored as the handle to the created stream
|
|
* buffer.
|
|
*
|
|
* Example use:
|
|
* @code{c}
|
|
*
|
|
* void vAFunction( void )
|
|
* {
|
|
* StreamBufferHandle_t xStreamBuffer;
|
|
* const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10;
|
|
*
|
|
* // Create a stream buffer that can hold 100 bytes. The memory used to hold
|
|
* // both the stream buffer structure and the data in the stream buffer is
|
|
* // allocated dynamically.
|
|
* xStreamBuffer = xStreamBufferCreate( xStreamBufferSizeBytes, xTriggerLevel );
|
|
*
|
|
* if( xStreamBuffer == NULL )
|
|
* {
|
|
* // There was not enough heap memory space available to create the
|
|
* // stream buffer.
|
|
* }
|
|
* else
|
|
* {
|
|
* // The stream buffer was created successfully and can now be used.
|
|
* }
|
|
* }
|
|
* @endcode
|
|
* \defgroup xStreamBufferCreate xStreamBufferCreate
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
|
|
#define xStreamBufferCreate( xBufferSizeBytes, xTriggerLevelBytes ) \
|
|
xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE, NULL, NULL )
|
|
|
|
#if ( configUSE_SB_COMPLETED_CALLBACK == 1 )
|
|
#define xStreamBufferCreateWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pxSendCompletedCallback, pxReceiveCompletedCallback ) \
|
|
xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE, pxSendCompletedCallback, pxReceiveCompletedCallback )
|
|
#endif
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* StreamBufferHandle_t xStreamBufferCreateStatic( size_t xBufferSizeBytes,
|
|
* size_t xTriggerLevelBytes,
|
|
* uint8_t *pucStreamBufferStorageArea,
|
|
* StaticStreamBuffer_t *pxStaticStreamBuffer );
|
|
* @endcode
|
|
* Creates a new stream buffer using statically allocated memory. See
|
|
* xStreamBufferCreate() for a version that uses dynamically allocated memory.
|
|
*
|
|
* configSUPPORT_STATIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h for
|
|
* xStreamBufferCreateStatic() to be available.
|
|
*
|
|
* @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the
|
|
* pucStreamBufferStorageArea parameter.
|
|
*
|
|
* @param xTriggerLevelBytes The number of bytes that must be in the stream
|
|
* buffer before a task that is blocked on the stream buffer to wait for data is
|
|
* moved out of the blocked state. For example, if a task is blocked on a read
|
|
* of an empty stream buffer that has a trigger level of 1 then the task will be
|
|
* unblocked when a single byte is written to the buffer or the task's block
|
|
* time expires. As another example, if a task is blocked on a read of an empty
|
|
* stream buffer that has a trigger level of 10 then the task will not be
|
|
* unblocked until the stream buffer contains at least 10 bytes or the task's
|
|
* block time expires. If a reading task's block time expires before the
|
|
* trigger level is reached then the task will still receive however many bytes
|
|
* are actually available. Setting a trigger level of 0 will result in a
|
|
* trigger level of 1 being used. It is not valid to specify a trigger level
|
|
* that is greater than the buffer size.
|
|
*
|
|
* @param pucStreamBufferStorageArea Must point to a uint8_t array that is at
|
|
* least xBufferSizeBytes big. This is the array to which streams are
|
|
* copied when they are written to the stream buffer.
|
|
*
|
|
* @param pxStaticStreamBuffer Must point to a variable of type
|
|
* StaticStreamBuffer_t, which will be used to hold the stream buffer's data
|
|
* structure.
|
|
*
|
|
* @param pxSendCompletedCallback Callback invoked when number of bytes at least equal to
|
|
* trigger level is sent to the stream buffer. If the parameter is NULL, it will use the default
|
|
* implementation provided by sbSEND_COMPLETED macro. To enable the callback,
|
|
* configUSE_SB_COMPLETED_CALLBACK must be set to 1 in FreeRTOSConfig.h.
|
|
*
|
|
* @param pxReceiveCompletedCallback Callback invoked when more than zero bytes are read from a
|
|
* stream buffer. If the parameter is NULL, it will use the default
|
|
* implementation provided by sbRECEIVE_COMPLETED macro. To enable the callback,
|
|
* configUSE_SB_COMPLETED_CALLBACK must be set to 1 in FreeRTOSConfig.h.
|
|
*
|
|
* @return If the stream buffer is created successfully then a handle to the
|
|
* created stream buffer is returned. If either pucStreamBufferStorageArea or
|
|
* pxStaticstreamBuffer are NULL then NULL is returned.
|
|
*
|
|
* Example use:
|
|
* @code{c}
|
|
*
|
|
* // Used to dimension the array used to hold the streams. The available space
|
|
* // will actually be one less than this, so 999.
|
|
#define STORAGE_SIZE_BYTES 1000
|
|
*
|
|
* // Defines the memory that will actually hold the streams within the stream
|
|
* // buffer.
|
|
* static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];
|
|
*
|
|
* // The variable used to hold the stream buffer structure.
|
|
* StaticStreamBuffer_t xStreamBufferStruct;
|
|
*
|
|
* void MyFunction( void )
|
|
* {
|
|
* StreamBufferHandle_t xStreamBuffer;
|
|
* const size_t xTriggerLevel = 1;
|
|
*
|
|
* xStreamBuffer = xStreamBufferCreateStatic( sizeof( ucStorageBuffer ),
|
|
* xTriggerLevel,
|
|
* ucStorageBuffer,
|
|
* &xStreamBufferStruct );
|
|
*
|
|
* // As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer
|
|
* // parameters were NULL, xStreamBuffer will not be NULL, and can be used to
|
|
* // reference the created stream buffer in other stream buffer API calls.
|
|
*
|
|
* // Other code that uses the stream buffer can go here.
|
|
* }
|
|
*
|
|
* @endcode
|
|
* \defgroup xStreamBufferCreateStatic xStreamBufferCreateStatic
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
|
|
#define xStreamBufferCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer ) \
|
|
xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE, pucStreamBufferStorageArea, pxStaticStreamBuffer, NULL, NULL )
|
|
|
|
#if ( configUSE_SB_COMPLETED_CALLBACK == 1 )
|
|
#define xStreamBufferCreateStaticWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ) \
|
|
xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback )
|
|
#endif
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
|
|
* const void *pvTxData,
|
|
* size_t xDataLengthBytes,
|
|
* TickType_t xTicksToWait );
|
|
* @endcode
|
|
*
|
|
* Sends bytes to a stream buffer. The bytes are copied into the stream buffer.
|
|
*
|
|
* ***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 xStreamBufferReceive()) inside a critical section and set the receive
|
|
* block time to 0.
|
|
*
|
|
* Use xStreamBufferSend() to write to a stream buffer from a task. Use
|
|
* xStreamBufferSendFromISR() to write to a stream buffer from an interrupt
|
|
* service routine (ISR).
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer to which a stream is
|
|
* being sent.
|
|
*
|
|
* @param pvTxData A pointer to the buffer that holds the bytes to be copied
|
|
* into the stream buffer.
|
|
*
|
|
* @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
|
|
* into the stream buffer.
|
|
*
|
|
* @param xTicksToWait The maximum amount of time the task should remain in the
|
|
* Blocked state to wait for enough space to become available in the stream
|
|
* buffer, should the stream buffer contain too little space to hold the
|
|
* another xDataLengthBytes bytes. The block time is specified in tick periods,
|
|
* so the absolute time it represents is dependent on the tick frequency. The
|
|
* macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds
|
|
* into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will
|
|
* cause the task to wait indefinitely (without timing out), provided
|
|
* INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. If a task times out
|
|
* before it can write all xDataLengthBytes into the buffer it will still write
|
|
* as many bytes as possible. A task does not use any CPU time when it is in
|
|
* the blocked state.
|
|
*
|
|
* @return The number of bytes written to the stream buffer. If a task times
|
|
* out before it can write all xDataLengthBytes into the buffer it will still
|
|
* write as many bytes as possible.
|
|
*
|
|
* Example use:
|
|
* @code{c}
|
|
* void vAFunction( StreamBufferHandle_t xStreamBuffer )
|
|
* {
|
|
* size_t xBytesSent;
|
|
* uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };
|
|
* char *pcStringToSend = "String to send";
|
|
* const TickType_t x100ms = pdMS_TO_TICKS( 100 );
|
|
*
|
|
* // Send an array to the stream buffer, blocking for a maximum of 100ms to
|
|
* // wait for enough space to be available in the stream buffer.
|
|
* xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );
|
|
*
|
|
* if( xBytesSent != sizeof( ucArrayToSend ) )
|
|
* {
|
|
* // The call to xStreamBufferSend() times out before there was enough
|
|
* // space in the buffer for the data to be written, but it did
|
|
* // successfully write xBytesSent bytes.
|
|
* }
|
|
*
|
|
* // Send the string to the stream buffer. Return immediately if there is not
|
|
* // enough space in the buffer.
|
|
* xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );
|
|
*
|
|
* if( xBytesSent != strlen( pcStringToSend ) )
|
|
* {
|
|
* // The entire string could not be added to the stream buffer because
|
|
* // there was not enough free space in the buffer, but xBytesSent bytes
|
|
* // were sent. Could try again to send the remaining bytes.
|
|
* }
|
|
* }
|
|
* @endcode
|
|
* \defgroup xStreamBufferSend xStreamBufferSend
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
|
|
const void * pvTxData,
|
|
size_t xDataLengthBytes,
|
|
TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
|
|
* const void *pvTxData,
|
|
* size_t xDataLengthBytes,
|
|
* BaseType_t *pxHigherPriorityTaskWoken );
|
|
* @endcode
|
|
*
|
|
* Interrupt safe version of the API function that sends a stream of bytes to
|
|
* the stream buffer.
|
|
*
|
|
* ***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 xStreamBufferReceive()) inside a critical section and set the receive
|
|
* block time to 0.
|
|
*
|
|
* Use xStreamBufferSend() to write to a stream buffer from a task. Use
|
|
* xStreamBufferSendFromISR() to write to a stream buffer from an interrupt
|
|
* service routine (ISR).
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer to which a stream is
|
|
* being sent.
|
|
*
|
|
* @param pvTxData A pointer to the data that is to be copied into the stream
|
|
* buffer.
|
|
*
|
|
* @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
|
|
* into the stream buffer.
|
|
*
|
|
* @param pxHigherPriorityTaskWoken It is possible that a stream buffer will
|
|
* have a task blocked on it waiting for data. Calling
|
|
* xStreamBufferSendFromISR() can make data available, and so cause a task that
|
|
* was waiting for data to leave the Blocked state. If calling
|
|
* xStreamBufferSendFromISR() causes a task to leave the Blocked state, and the
|
|
* unblocked task has a priority higher than the currently executing task (the
|
|
* task that was interrupted), then, internally, xStreamBufferSendFromISR()
|
|
* will set *pxHigherPriorityTaskWoken to pdTRUE. If
|
|
* xStreamBufferSendFromISR() sets this value to pdTRUE, then normally a
|
|
* context switch should be performed before the interrupt is exited. This will
|
|
* ensure that the interrupt returns directly to the highest priority Ready
|
|
* state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it
|
|
* is passed into the function. See the example code below for an example.
|
|
*
|
|
* @return The number of bytes actually written to the stream buffer, which will
|
|
* be less than xDataLengthBytes if the stream buffer didn't have enough free
|
|
* space for all the bytes to be written.
|
|
*
|
|
* Example use:
|
|
* @code{c}
|
|
* // A stream buffer that has already been created.
|
|
* StreamBufferHandle_t xStreamBuffer;
|
|
*
|
|
* void vAnInterruptServiceRoutine( void )
|
|
* {
|
|
* size_t xBytesSent;
|
|
* char *pcStringToSend = "String to send";
|
|
* BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
|
|
*
|
|
* // Attempt to send the string to the stream buffer.
|
|
* xBytesSent = xStreamBufferSendFromISR( xStreamBuffer,
|
|
* ( void * ) pcStringToSend,
|
|
* strlen( pcStringToSend ),
|
|
* &xHigherPriorityTaskWoken );
|
|
*
|
|
* if( xBytesSent != strlen( pcStringToSend ) )
|
|
* {
|
|
* // There was not enough free space in the stream buffer for the entire
|
|
* // string to be written, ut xBytesSent bytes were written.
|
|
* }
|
|
*
|
|
* // If xHigherPriorityTaskWoken was set to pdTRUE inside
|
|
* // xStreamBufferSendFromISR() then a task that has a priority above the
|
|
* // priority of the currently executing task was unblocked and a context
|
|
* // switch should be performed to ensure the ISR returns to the unblocked
|
|
* // task. In most FreeRTOS ports this is done by simply passing
|
|
* // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the
|
|
* // variables value, and perform the context switch if necessary. Check the
|
|
* // documentation for the port in use for port specific instructions.
|
|
* portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
|
|
* }
|
|
* @endcode
|
|
* \defgroup xStreamBufferSendFromISR xStreamBufferSendFromISR
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
|
|
const void * pvTxData,
|
|
size_t xDataLengthBytes,
|
|
BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
|
|
* void *pvRxData,
|
|
* size_t xBufferLengthBytes,
|
|
* TickType_t xTicksToWait );
|
|
* @endcode
|
|
*
|
|
* Receives bytes from a stream buffer.
|
|
*
|
|
* ***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 xStreamBufferReceive()) inside a critical section and set the receive
|
|
* block time to 0.
|
|
*
|
|
* Use xStreamBufferReceive() to read from a stream buffer from a task. Use
|
|
* xStreamBufferReceiveFromISR() to read from a stream buffer from an
|
|
* interrupt service routine (ISR).
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer from which bytes are to
|
|
* be received.
|
|
*
|
|
* @param pvRxData A pointer to the buffer into which the received bytes will be
|
|
* copied.
|
|
*
|
|
* @param xBufferLengthBytes The length of the buffer pointed to by the
|
|
* pvRxData parameter. This sets the maximum number of bytes to receive in one
|
|
* call. xStreamBufferReceive will return as many bytes as possible up to a
|
|
* maximum set by xBufferLengthBytes.
|
|
*
|
|
* @param xTicksToWait The maximum amount of time the task should remain in the
|
|
* Blocked state to wait for data to become available if the stream buffer is
|
|
* empty. xStreamBufferReceive() will return immediately if xTicksToWait is
|
|
* zero. The block time is specified in tick periods, so the absolute time it
|
|
* represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can
|
|
* be used to convert a time specified in milliseconds into a time specified in
|
|
* ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait
|
|
* indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1
|
|
* in FreeRTOSConfig.h. A task does not use any CPU time when it is in the
|
|
* Blocked state.
|
|
*
|
|
* @return The number of bytes actually read from the stream buffer, which will
|
|
* be less than xBufferLengthBytes if the call to xStreamBufferReceive() timed
|
|
* out before xBufferLengthBytes were available.
|
|
*
|
|
* Example use:
|
|
* @code{c}
|
|
* void vAFunction( StreamBuffer_t xStreamBuffer )
|
|
* {
|
|
* uint8_t ucRxData[ 20 ];
|
|
* size_t xReceivedBytes;
|
|
* const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );
|
|
*
|
|
* // Receive up to another sizeof( ucRxData ) bytes from the stream buffer.
|
|
* // Wait in the Blocked state (so not using any CPU processing time) for a
|
|
* // maximum of 100ms for the full sizeof( ucRxData ) number of bytes to be
|
|
* // available.
|
|
* xReceivedBytes = xStreamBufferReceive( xStreamBuffer,
|
|
* ( void * ) ucRxData,
|
|
* sizeof( ucRxData ),
|
|
* xBlockTime );
|
|
*
|
|
* if( xReceivedBytes > 0 )
|
|
* {
|
|
* // A ucRxData contains another xReceivedBytes bytes of data, which can
|
|
* // be processed here....
|
|
* }
|
|
* }
|
|
* @endcode
|
|
* \defgroup xStreamBufferReceive xStreamBufferReceive
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
|
|
void * pvRxData,
|
|
size_t xBufferLengthBytes,
|
|
TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
|
|
* void *pvRxData,
|
|
* size_t xBufferLengthBytes,
|
|
* BaseType_t *pxHigherPriorityTaskWoken );
|
|
* @endcode
|
|
*
|
|
* An interrupt safe version of the API function that receives bytes from a
|
|
* stream buffer.
|
|
*
|
|
* Use xStreamBufferReceive() to read bytes from a stream buffer from a task.
|
|
* Use xStreamBufferReceiveFromISR() to read bytes from a stream buffer from an
|
|
* interrupt service routine (ISR).
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer from which a stream
|
|
* is being received.
|
|
*
|
|
* @param pvRxData A pointer to the buffer into which the received bytes are
|
|
* copied.
|
|
*
|
|
* @param xBufferLengthBytes The length of the buffer pointed to by the
|
|
* pvRxData parameter. This sets the maximum number of bytes to receive in one
|
|
* call. xStreamBufferReceive will return as many bytes as possible up to a
|
|
* maximum set by xBufferLengthBytes.
|
|
*
|
|
* @param pxHigherPriorityTaskWoken It is possible that a stream buffer will
|
|
* have a task blocked on it waiting for space to become available. Calling
|
|
* xStreamBufferReceiveFromISR() can make space available, and so cause a task
|
|
* that is waiting for space to leave the Blocked state. If calling
|
|
* xStreamBufferReceiveFromISR() causes a task to leave the Blocked state, and
|
|
* the unblocked task has a priority higher than the currently executing task
|
|
* (the task that was interrupted), then, internally,
|
|
* xStreamBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE.
|
|
* If xStreamBufferReceiveFromISR() sets this value to pdTRUE, then normally a
|
|
* context switch should be performed before the interrupt is exited. That will
|
|
* ensure the interrupt returns directly to the highest priority Ready state
|
|
* task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is
|
|
* passed into the function. See the code example below for an example.
|
|
*
|
|
* @return The number of bytes read from the stream buffer, if any.
|
|
*
|
|
* Example use:
|
|
* @code{c}
|
|
* // A stream buffer that has already been created.
|
|
* StreamBuffer_t xStreamBuffer;
|
|
*
|
|
* void vAnInterruptServiceRoutine( void )
|
|
* {
|
|
* uint8_t ucRxData[ 20 ];
|
|
* size_t xReceivedBytes;
|
|
* BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
|
|
*
|
|
* // Receive the next stream from the stream buffer.
|
|
* xReceivedBytes = xStreamBufferReceiveFromISR( xStreamBuffer,
|
|
* ( void * ) ucRxData,
|
|
* sizeof( ucRxData ),
|
|
* &xHigherPriorityTaskWoken );
|
|
*
|
|
* if( xReceivedBytes > 0 )
|
|
* {
|
|
* // ucRxData contains xReceivedBytes read from the stream buffer.
|
|
* // Process the stream here....
|
|
* }
|
|
*
|
|
* // If xHigherPriorityTaskWoken was set to pdTRUE inside
|
|
* // xStreamBufferReceiveFromISR() then a task that has a priority above the
|
|
* // priority of the currently executing task was unblocked and a context
|
|
* // switch should be performed to ensure the ISR returns to the unblocked
|
|
* // task. In most FreeRTOS ports this is done by simply passing
|
|
* // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the
|
|
* // variables value, and perform the context switch if necessary. Check the
|
|
* // documentation for the port in use for port specific instructions.
|
|
* portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
|
|
* }
|
|
* @endcode
|
|
* \defgroup xStreamBufferReceiveFromISR xStreamBufferReceiveFromISR
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
|
|
void * pvRxData,
|
|
size_t xBufferLengthBytes,
|
|
BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer );
|
|
* @endcode
|
|
*
|
|
* Deletes a stream buffer that was previously created using a call to
|
|
* xStreamBufferCreate() or xStreamBufferCreateStatic(). If the stream
|
|
* buffer was created using dynamic memory (that is, by xStreamBufferCreate()),
|
|
* then the allocated memory is freed.
|
|
*
|
|
* A stream buffer handle must not be used after the stream buffer has been
|
|
* deleted.
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer to be deleted.
|
|
*
|
|
* \defgroup vStreamBufferDelete vStreamBufferDelete
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer );
|
|
* @endcode
|
|
*
|
|
* Queries a stream buffer to see if it is full. A stream buffer is full if it
|
|
* does not have any free space, and therefore cannot accept any more data.
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer being queried.
|
|
*
|
|
* @return If the stream buffer is full then pdTRUE is returned. Otherwise
|
|
* pdFALSE is returned.
|
|
*
|
|
* \defgroup xStreamBufferIsFull xStreamBufferIsFull
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer );
|
|
* @endcode
|
|
*
|
|
* Queries a stream buffer to see if it is empty. A stream buffer is empty if
|
|
* it does not contain any data.
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer being queried.
|
|
*
|
|
* @return If the stream buffer is empty then pdTRUE is returned. Otherwise
|
|
* pdFALSE is returned.
|
|
*
|
|
* \defgroup xStreamBufferIsEmpty xStreamBufferIsEmpty
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer );
|
|
* @endcode
|
|
*
|
|
* Resets a stream buffer to its initial, empty, state. Any data that was in
|
|
* the stream buffer is discarded. A stream buffer can only be reset if there
|
|
* are no tasks blocked waiting to either send to or receive from the stream
|
|
* buffer.
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer being reset.
|
|
*
|
|
* @return If the stream buffer is reset then pdPASS is returned. If there was
|
|
* a task blocked waiting to send to or read from the stream buffer then the
|
|
* stream buffer is not reset and pdFAIL is returned.
|
|
*
|
|
* \defgroup xStreamBufferReset xStreamBufferReset
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer );
|
|
* @endcode
|
|
*
|
|
* Queries a stream buffer to see how much free space it contains, which is
|
|
* equal to the amount of data that can be sent to the stream buffer before it
|
|
* is full.
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer being queried.
|
|
*
|
|
* @return The number of bytes that can be written to the stream buffer before
|
|
* the stream buffer would be full.
|
|
*
|
|
* \defgroup xStreamBufferSpacesAvailable xStreamBufferSpacesAvailable
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer );
|
|
* @endcode
|
|
*
|
|
* Queries a stream buffer to see how much data it contains, which is equal to
|
|
* the number of bytes that can be read from the stream buffer before the stream
|
|
* buffer would be empty.
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer being queried.
|
|
*
|
|
* @return The number of bytes that can be read from the stream buffer before
|
|
* the stream buffer would be empty.
|
|
*
|
|
* \defgroup xStreamBufferBytesAvailable xStreamBufferBytesAvailable
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel );
|
|
* @endcode
|
|
*
|
|
* A stream buffer's trigger level is the number of bytes that must be in the
|
|
* stream buffer before a task that is blocked on the stream buffer to
|
|
* wait for data is moved out of the blocked state. For example, if a task is
|
|
* blocked on a read of an empty stream buffer that has a trigger level of 1
|
|
* then the task will be unblocked when a single byte is written to the buffer
|
|
* or the task's block time expires. As another example, if a task is blocked
|
|
* on a read of an empty stream buffer that has a trigger level of 10 then the
|
|
* task will not be unblocked until the stream buffer contains at least 10 bytes
|
|
* or the task's block time expires. If a reading task's block time expires
|
|
* before the trigger level is reached then the task will still receive however
|
|
* many bytes are actually available. Setting a trigger level of 0 will result
|
|
* in a trigger level of 1 being used. It is not valid to specify a trigger
|
|
* level that is greater than the buffer size.
|
|
*
|
|
* A trigger level is set when the stream buffer is created, and can be modified
|
|
* using xStreamBufferSetTriggerLevel().
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer being updated.
|
|
*
|
|
* @param xTriggerLevel The new trigger level for the stream buffer.
|
|
*
|
|
* @return If xTriggerLevel was less than or equal to the stream buffer's length
|
|
* then the trigger level will be updated and pdTRUE is returned. Otherwise
|
|
* pdFALSE is returned.
|
|
*
|
|
* \defgroup xStreamBufferSetTriggerLevel xStreamBufferSetTriggerLevel
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer,
|
|
size_t xTriggerLevel ) PRIVILEGED_FUNCTION;
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
|
|
* @endcode
|
|
*
|
|
* For advanced users only.
|
|
*
|
|
* The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when
|
|
* data is sent to a message buffer or stream buffer. If there was a task that
|
|
* was blocked on the message or stream buffer waiting for data to arrive then
|
|
* the sbSEND_COMPLETED() macro sends a notification to the task to remove it
|
|
* from the Blocked state. xStreamBufferSendCompletedFromISR() does the same
|
|
* thing. It is provided to enable application writers to implement their own
|
|
* version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.
|
|
*
|
|
* See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
|
|
* additional information.
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer to which data was
|
|
* written.
|
|
*
|
|
* @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
|
|
* initialised to pdFALSE before it is passed into
|
|
* xStreamBufferSendCompletedFromISR(). If calling
|
|
* xStreamBufferSendCompletedFromISR() removes a task from the Blocked state,
|
|
* and the task has a priority above the priority of the currently running task,
|
|
* then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
|
|
* context switch should be performed before exiting the ISR.
|
|
*
|
|
* @return If a task was removed from the Blocked state then pdTRUE is returned.
|
|
* Otherwise pdFALSE is returned.
|
|
*
|
|
* \defgroup xStreamBufferSendCompletedFromISR xStreamBufferSendCompletedFromISR
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer,
|
|
BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
|
|
|
|
/**
|
|
* stream_buffer.h
|
|
*
|
|
* @code{c}
|
|
* BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
|
|
* @endcode
|
|
*
|
|
* For advanced users only.
|
|
*
|
|
* The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when
|
|
* data is read out of a message buffer or stream buffer. If there was a task
|
|
* that was blocked on the message or stream buffer waiting for data to arrive
|
|
* then the sbRECEIVE_COMPLETED() macro sends a notification to the task to
|
|
* remove it from the Blocked state. xStreamBufferReceiveCompletedFromISR()
|
|
* does the same thing. It is provided to enable application writers to
|
|
* implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT
|
|
* ANY OTHER TIME.
|
|
*
|
|
* See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
|
|
* additional information.
|
|
*
|
|
* @param xStreamBuffer The handle of the stream buffer from which data was
|
|
* read.
|
|
*
|
|
* @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
|
|
* initialised to pdFALSE before it is passed into
|
|
* xStreamBufferReceiveCompletedFromISR(). If calling
|
|
* xStreamBufferReceiveCompletedFromISR() removes a task from the Blocked state,
|
|
* and the task has a priority above the priority of the currently running task,
|
|
* then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
|
|
* context switch should be performed before exiting the ISR.
|
|
*
|
|
* @return If a task was removed from the Blocked state then pdTRUE is returned.
|
|
* Otherwise pdFALSE is returned.
|
|
*
|
|
* \defgroup xStreamBufferReceiveCompletedFromISR xStreamBufferReceiveCompletedFromISR
|
|
* \ingroup StreamBufferManagement
|
|
*/
|
|
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,
|
|
StreamBufferCallbackFunction_t pxSendCompletedCallback,
|
|
StreamBufferCallbackFunction_t pxReceiveCompletedCallback ) PRIVILEGED_FUNCTION;
|
|
|
|
|
|
StreamBufferHandle_t xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes,
|
|
size_t xTriggerLevelBytes,
|
|
BaseType_t xIsMessageBuffer,
|
|
uint8_t * const pucStreamBufferStorageArea,
|
|
StaticStreamBuffer_t * const pxStaticStreamBuffer,
|
|
StreamBufferCallbackFunction_t pxSendCompletedCallback,
|
|
StreamBufferCallbackFunction_t pxReceiveCompletedCallback ) PRIVILEGED_FUNCTION;
|
|
|
|
size_t xStreamBufferNextMessageLengthBytes( StreamBufferHandle_t xStreamBuffer ) 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
|
|
|
|
/* *INDENT-OFF* */
|
|
#if defined( __cplusplus )
|
|
}
|
|
#endif
|
|
/* *INDENT-ON* */
|
|
|
|
#endif /* !defined( STREAM_BUFFER_H ) */
|