len0rd/FreeRTOS-Kernel
1
0
Fork 0
mirror of https://github.com/FreeRTOS/FreeRTOS-Kernel.git synced 2025-09-10 08:07:46 -04:00
Code Issues Projects Releases Packages Wiki Activity

Remove not needed file

Browse source 
Signed-off-by: Gaurav Aggarwal <aggarg@amazon.com>
This commit is contained in:
Gaurav Aggarwal 2024-04-16 11:45:30 +00:00
parent 630cad38b6
commit 64cafa45b0
1 changed files with 0 additions and 946 deletions
Download patch file Download diff file Expand all files Collapse all files

946
include/blocking_buffer.h
View file

@ -1,946 +0,0 @@
/*
* 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
*
*/
/*
* Blocking buffers are used to send a continuous blocking 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 blocking buffer
* implementation (so also the message buffer implementation, as message buffers
* are built on top of blocking 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 xBlockingBufferSend()) 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 xBlockingBufferReceive()) inside a critical section section and set the
* receive block time to 0.
*
*/
#ifndef BLOCKING_BUFFER_H
#define BLOCKING_BUFFER_H
#ifndef INC_FREERTOS_H
#error "include FreeRTOS.h must appear in source files before include blocking_buffer.h"
#endif
/* *INDENT-OFF* */
#if defined( __cplusplus )
extern "C" {
#endif
/* *INDENT-ON* */
/**
* Type by which blocking buffers are referenced. For example, a call to
* xBlockingBufferCreate() returns an BlockingBufferHandle_t variable that can
* then be used as a parameter to xBlockingBufferSend(), xBlockingBufferReceive(),
* etc.
*/
struct BlockingBufferDef_t;
typedef struct BlockingBufferDef_t * BlockingBufferHandle_t;
/**
* Type used as a blocking buffer's optional callback.
*/
typedef void (* BlockingBufferCallbackFunction_t)( BlockingBufferHandle_t xBlockingBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken );
/**
* blocking_buffer.h
*
* @code{c}
* BlockingBufferHandle_t xBlockingBufferCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes );
* @endcode
*
* Creates a new blocking buffer using dynamically allocated memory. See
* xBlockingBufferCreateStatic() 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 xBlockingBufferCreate() to be available.
*
* @param xBufferSizeBytes The total number of bytes the blocking buffer will be
* able to hold at any one time.
*
* @param xTriggerLevelBytes The number of bytes that must be in the blocking
* buffer before a task that is blocked on the blocking 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 blocking 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
* blocking buffer that has a trigger level of 10 then the task will not be
* unblocked until the blocking 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 blocking 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
* blocking 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 blocking buffer cannot be created
* because there is insufficient heap memory available for FreeRTOS to allocate
* the blocking buffer data structures and storage area. A non-NULL value being
* returned indicates that the blocking buffer has been created successfully -
* the returned value should be stored as the handle to the created blocking
* buffer.
*
* Example use:
* @code{c}
*
* void vAFunction( void )
* {
* BlockingBufferHandle_t xBlockingBuffer;
* const size_t xBlockingBufferSizeBytes = 100, xTriggerLevel = 10;
*
* // Create a blocking buffer that can hold 100 bytes. The memory used to hold
* // both the blocking buffer structure and the data in the blocking buffer is
* // allocated dynamically.
* xBlockingBuffer = xBlockingBufferCreate( xBlockingBufferSizeBytes, xTriggerLevel );
*
* if( xBlockingBuffer == NULL )
* {
* // There was not enough heap memory space available to create the
* // blocking buffer.
* }
* else
* {
* // The blocking buffer was created successfully and can now be used.
* }
* }
* @endcode
* \defgroup xBlockingBufferCreate xBlockingBufferCreate
* \ingroup BlockingBufferManagement
*/
#define xBlockingBufferCreate( xBufferSizeBytes, xTriggerLevelBytes ) \
xBlockingBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), pdFALSE, pdTRUE, NULL, NULL )
#if ( configUSE_SB_COMPLETED_CALLBACK == 1 )
#define xBlockingBufferCreateWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pxSendCompletedCallback, pxReceiveCompletedCallback ) \
xBlockingBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), pdFALSE, ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) )
#endif
/**
* blocking_buffer.h
*
* @code{c}
* BlockingBufferHandle_t xBlockingBufferCreateStatic( size_t xBufferSizeBytes,
* size_t xTriggerLevelBytes,
* uint8_t *pucBlockingBufferStorageArea,
* StaticBlockingBuffer_t *pxStaticBlockingBuffer );
* @endcode
* Creates a new blocking buffer using statically allocated memory. See
* xBlockingBufferCreate() for a version that uses dynamically allocated memory.
*
* configSUPPORT_STATIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h for
* xBlockingBufferCreateStatic() to be available.
*
* @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the
* pucBlockingBufferStorageArea parameter.
*
* @param xTriggerLevelBytes The number of bytes that must be in the blocking
* buffer before a task that is blocked on the blocking 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 blocking 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
* blocking buffer that has a trigger level of 10 then the task will not be
* unblocked until the blocking 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 pucBlockingBufferStorageArea Must point to a uint8_t array that is at
* least xBufferSizeBytes big. This is the array to which blockings are
* copied when they are written to the blocking buffer.
*
* @param pxStaticBlockingBuffer Must point to a variable of type
* StaticBlockingBuffer_t, which will be used to hold the blocking buffer's data
* structure.
*
* @param pxSendCompletedCallback Callback invoked when number of bytes at least equal to
* trigger level is sent to the blocking 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
* blocking 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 blocking buffer is created successfully then a handle to the
* created blocking buffer is returned. If either pucBlockingBufferStorageArea or
* pxStaticblockingBuffer are NULL then NULL is returned.
*
* Example use:
* @code{c}
*
* // Used to dimension the array used to hold the blockings. 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 blockings within the blocking
* // buffer.
* static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];
*
* // The variable used to hold the blocking buffer structure.
* StaticBlockingBuffer_t xBlockingBufferStruct;
*
* void MyFunction( void )
* {
* BlockingBufferHandle_t xBlockingBuffer;
* const size_t xTriggerLevel = 1;
*
* xBlockingBuffer = xBlockingBufferCreateStatic( sizeof( ucStorageBuffer ),
* xTriggerLevel,
* ucStorageBuffer,
* &xBlockingBufferStruct );
*
* // As neither the pucBlockingBufferStorageArea or pxStaticBlockingBuffer
* // parameters were NULL, xBlockingBuffer will not be NULL, and can be used to
* // reference the created blocking buffer in other blocking buffer API calls.
*
* // Other code that uses the blocking buffer can go here.
* }
*
* @endcode
* \defgroup xBlockingBufferCreateStatic xBlockingBufferCreateStatic
* \ingroup BlockingBufferManagement
*/
#define xBlockingBufferCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pucBlockingBufferStorageArea, pxStaticBlockingBuffer ) \
xBlockingBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), pdFALSE, ( pucBlockingBufferStorageArea ), ( pxStaticBlockingBuffer ), NULL, NULL )
#if ( configUSE_SB_COMPLETED_CALLBACK == 1 )
#define xBlockingBufferCreateStaticWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pucBlockingBufferStorageArea, pxStaticBlockingBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ) \
xBlockingBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), pdFALSE, ( pucBlockingBufferStorageArea ), ( pxStaticBlockingBuffer ), ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) )
#endif
/**
* blocking_buffer.h
*
* @code{c}
* BaseType_t xBlockingBufferGetStaticBuffers( BlockingBufferHandle_t xBlockingBuffer,
* uint8_t ** ppucBlockingBufferStorageArea,
* StaticBlockingBuffer_t ** ppxStaticBlockingBuffer );
* @endcode
*
* Retrieve pointers to a statically created blocking buffer's data structure
* buffer and storage area buffer. These are the same buffers that are supplied
* at the time of creation.
*
* @param xBlockingBuffer The blocking buffer for which to retrieve the buffers.
*
* @param ppucBlockingBufferStorageArea Used to return a pointer to the blocking
* buffer's storage area buffer.
*
* @param ppxStaticBlockingBuffer Used to return a pointer to the blocking
* buffer's data structure buffer.
*
* @return pdTRUE if buffers were retrieved, pdFALSE otherwise.
*
* \defgroup xBlockingBufferGetStaticBuffers xBlockingBufferGetStaticBuffers
* \ingroup BlockingBufferManagement
*/
#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
BaseType_t xBlockingBufferGetStaticBuffers( BlockingBufferHandle_t xBlockingBuffer,
uint8_t ** ppucBlockingBufferStorageArea,
StaticBlockingBuffer_t ** ppxStaticBlockingBuffer ) PRIVILEGED_FUNCTION;
#endif /* configSUPPORT_STATIC_ALLOCATION */
/**
* blocking_buffer.h
*
* @code{c}
* size_t xBlockingBufferSend( BlockingBufferHandle_t xBlockingBuffer,
* const void *pvTxData,
* size_t xDataLengthBytes,
* TickType_t xTicksToWait );
* @endcode
*
* Sends bytes to a blocking buffer. The bytes are copied into the blocking buffer.
*
* ***NOTE***: Uniquely among FreeRTOS objects, the blocking buffer
* implementation (so also the message buffer implementation, as message buffers
* are built on top of blocking 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 xBlockingBufferSend()) 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 xBlockingBufferReceive()) inside a critical section and set the receive
* block time to 0.
*
* Use xBlockingBufferSend() to write to a blocking buffer from a task. Use
* xBlockingBufferSendFromISR() to write to a blocking buffer from an interrupt
* service routine (ISR).
*
* @param xBlockingBuffer The handle of the blocking buffer to which a blocking is
* being sent.
*
* @param pvTxData A pointer to the buffer that holds the bytes to be copied
* into the blocking buffer.
*
* @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
* into the blocking 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 blocking
* buffer, should the blocking 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 blocking 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( BlockingBufferHandle_t xBlockingBuffer )
* {
* 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 blocking buffer, blocking for a maximum of 100ms to
* // wait for enough space to be available in the blocking buffer.
* xBytesSent = xBlockingBufferSend( xBlockingBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );
*
* if( xBytesSent != sizeof( ucArrayToSend ) )
* {
* // The call to xBlockingBufferSend() 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 blocking buffer. Return immediately if there is not
* // enough space in the buffer.
* xBytesSent = xBlockingBufferSend( xBlockingBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );
*
* if( xBytesSent != strlen( pcStringToSend ) )
* {
* // The entire string could not be added to the blocking 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 xBlockingBufferSend xBlockingBufferSend
* \ingroup BlockingBufferManagement
*/
size_t xBlockingBufferSend( BlockingBufferHandle_t xBlockingBuffer,
const void * pvTxData,
size_t xDataLengthBytes,
TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
/**
* blocking_buffer.h
*
* @code{c}
* size_t xBlockingBufferSendFromISR( BlockingBufferHandle_t xBlockingBuffer,
* const void *pvTxData,
* size_t xDataLengthBytes,
* BaseType_t *pxHigherPriorityTaskWoken );
* @endcode
*
* Interrupt safe version of the API function that sends a blocking of bytes to
* the blocking buffer.
*
* ***NOTE***: Uniquely among FreeRTOS objects, the blocking buffer
* implementation (so also the message buffer implementation, as message buffers
* are built on top of blocking 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 xBlockingBufferSend()) 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 xBlockingBufferReceive()) inside a critical section and set the receive
* block time to 0.
*
* Use xBlockingBufferSend() to write to a blocking buffer from a task. Use
* xBlockingBufferSendFromISR() to write to a blocking buffer from an interrupt
* service routine (ISR).
*
* @param xBlockingBuffer The handle of the blocking buffer to which a blocking is
* being sent.
*
* @param pvTxData A pointer to the data that is to be copied into the blocking
* buffer.
*
* @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
* into the blocking buffer.
*
* @param pxHigherPriorityTaskWoken It is possible that a blocking buffer will
* have a task blocked on it waiting for data. Calling
* xBlockingBufferSendFromISR() can make data available, and so cause a task that
* was waiting for data to leave the Blocked state. If calling
* xBlockingBufferSendFromISR() 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, xBlockingBufferSendFromISR()
* will set *pxHigherPriorityTaskWoken to pdTRUE. If
* xBlockingBufferSendFromISR() 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 blocking buffer, which will
* be less than xDataLengthBytes if the blocking buffer didn't have enough free
* space for all the bytes to be written.
*
* Example use:
* @code{c}
* // A blocking buffer that has already been created.
* BlockingBufferHandle_t xBlockingBuffer;
*
* 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 blocking buffer.
* xBytesSent = xBlockingBufferSendFromISR( xBlockingBuffer,
* ( void * ) pcStringToSend,
* strlen( pcStringToSend ),
* &xHigherPriorityTaskWoken );
*
* if( xBytesSent != strlen( pcStringToSend ) )
* {
* // There was not enough free space in the blocking buffer for the entire
* // string to be written, ut xBytesSent bytes were written.
* }
*
* // If xHigherPriorityTaskWoken was set to pdTRUE inside
* // xBlockingBufferSendFromISR() 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 xBlockingBufferSendFromISR xBlockingBufferSendFromISR
* \ingroup BlockingBufferManagement
*/
size_t xBlockingBufferSendFromISR( BlockingBufferHandle_t xBlockingBuffer,
const void * pvTxData,
size_t xDataLengthBytes,
BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
/**
* blocking_buffer.h
*
* @code{c}
* size_t xBlockingBufferReceive( BlockingBufferHandle_t xBlockingBuffer,
* void *pvRxData,
* size_t xBufferLengthBytes,
* TickType_t xTicksToWait );
* @endcode
*
* Receives bytes from a blocking buffer.
*
* ***NOTE***: Uniquely among FreeRTOS objects, the blocking buffer
* implementation (so also the message buffer implementation, as message buffers
* are built on top of blocking 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 xBlockingBufferSend()) 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 xBlockingBufferReceive()) inside a critical section and set the receive
* block time to 0.
*
* Use xBlockingBufferReceive() to read from a blocking buffer from a task. Use
* xBlockingBufferReceiveFromISR() to read from a blocking buffer from an
* interrupt service routine (ISR).
*
* @param xBlockingBuffer The handle of the blocking 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. xBlockingBufferReceive 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 blocking buffer is
* empty. xBlockingBufferReceive() 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 blocking buffer, which will
* be less than xBufferLengthBytes if the call to xBlockingBufferReceive() timed
* out before xBufferLengthBytes were available.
*
* Example use:
* @code{c}
* void vAFunction( BlockingBuffer_t xBlockingBuffer )
* {
* uint8_t ucRxData[ 20 ];
* size_t xReceivedBytes;
* const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );
*
* // Receive up to another sizeof( ucRxData ) bytes from the blocking 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 = xBlockingBufferReceive( xBlockingBuffer,
* ( void * ) ucRxData,
* sizeof( ucRxData ),
* xBlockTime );
*
* if( xReceivedBytes > 0 )
* {
* // A ucRxData contains another xReceivedBytes bytes of data, which can
* // be processed here....
* }
* }
* @endcode
* \defgroup xBlockingBufferReceive xBlockingBufferReceive
* \ingroup BlockingBufferManagement
*/
size_t xBlockingBufferReceive( BlockingBufferHandle_t xBlockingBuffer,
void * pvRxData,
size_t xBufferLengthBytes,
TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
/**
* blocking_buffer.h
*
* @code{c}
* size_t xBlockingBufferReceiveFromISR( BlockingBufferHandle_t xBlockingBuffer,
* void *pvRxData,
* size_t xBufferLengthBytes,
* BaseType_t *pxHigherPriorityTaskWoken );
* @endcode
*
* An interrupt safe version of the API function that receives bytes from a
* blocking buffer.
*
* Use xBlockingBufferReceive() to read bytes from a blocking buffer from a task.
* Use xBlockingBufferReceiveFromISR() to read bytes from a blocking buffer from an
* interrupt service routine (ISR).
*
* @param xBlockingBuffer The handle of the blocking buffer from which a blocking
* 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. xBlockingBufferReceive will return as many bytes as possible up to a
* maximum set by xBufferLengthBytes.
*
* @param pxHigherPriorityTaskWoken It is possible that a blocking buffer will
* have a task blocked on it waiting for space to become available. Calling
* xBlockingBufferReceiveFromISR() can make space available, and so cause a task
* that is waiting for space to leave the Blocked state. If calling
* xBlockingBufferReceiveFromISR() 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,
* xBlockingBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE.
* If xBlockingBufferReceiveFromISR() 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 blocking buffer, if any.
*
* Example use:
* @code{c}
* // A blocking buffer that has already been created.
* BlockingBuffer_t xBlockingBuffer;
*
* void vAnInterruptServiceRoutine( void )
* {
* uint8_t ucRxData[ 20 ];
* size_t xReceivedBytes;
* BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
*
* // Receive the next blocking from the blocking buffer.
* xReceivedBytes = xBlockingBufferReceiveFromISR( xBlockingBuffer,
* ( void * ) ucRxData,
* sizeof( ucRxData ),
* &xHigherPriorityTaskWoken );
*
* if( xReceivedBytes > 0 )
* {
* // ucRxData contains xReceivedBytes read from the blocking buffer.
* // Process the blocking here....
* }
*
* // If xHigherPriorityTaskWoken was set to pdTRUE inside
* // xBlockingBufferReceiveFromISR() 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 xBlockingBufferReceiveFromISR xBlockingBufferReceiveFromISR
* \ingroup BlockingBufferManagement
*/
size_t xBlockingBufferReceiveFromISR( BlockingBufferHandle_t xBlockingBuffer,
void * pvRxData,
size_t xBufferLengthBytes,
BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
/**
* blocking_buffer.h
*
* @code{c}
* void vBlockingBufferDelete( BlockingBufferHandle_t xBlockingBuffer );
* @endcode
*
* Deletes a blocking buffer that was previously created using a call to
* xBlockingBufferCreate() or xBlockingBufferCreateStatic(). If the blocking
* buffer was created using dynamic memory (that is, by xBlockingBufferCreate()),
* then the allocated memory is freed.
*
* A blocking buffer handle must not be used after the blocking buffer has been
* deleted.
*
* @param xBlockingBuffer The handle of the blocking buffer to be deleted.
*
* \defgroup vBlockingBufferDelete vBlockingBufferDelete
* \ingroup BlockingBufferManagement
*/
void vBlockingBufferDelete( BlockingBufferHandle_t xBlockingBuffer ) PRIVILEGED_FUNCTION;
/**
* blocking_buffer.h
*
* @code{c}
* BaseType_t xBlockingBufferIsFull( BlockingBufferHandle_t xBlockingBuffer );
* @endcode
*
* Queries a blocking buffer to see if it is full. A blocking buffer is full if it
* does not have any free space, and therefore cannot accept any more data.
*
* @param xBlockingBuffer The handle of the blocking buffer being queried.
*
* @return If the blocking buffer is full then pdTRUE is returned. Otherwise
* pdFALSE is returned.
*
* \defgroup xBlockingBufferIsFull xBlockingBufferIsFull
* \ingroup BlockingBufferManagement
*/
BaseType_t xBlockingBufferIsFull( BlockingBufferHandle_t xBlockingBuffer ) PRIVILEGED_FUNCTION;
/**
* blocking_buffer.h
*
* @code{c}
* BaseType_t xBlockingBufferIsEmpty( BlockingBufferHandle_t xBlockingBuffer );
* @endcode
*
* Queries a blocking buffer to see if it is empty. A blocking buffer is empty if
* it does not contain any data.
*
* @param xBlockingBuffer The handle of the blocking buffer being queried.
*
* @return If the blocking buffer is empty then pdTRUE is returned. Otherwise
* pdFALSE is returned.
*
* \defgroup xBlockingBufferIsEmpty xBlockingBufferIsEmpty
* \ingroup BlockingBufferManagement
*/
BaseType_t xBlockingBufferIsEmpty( BlockingBufferHandle_t xBlockingBuffer ) PRIVILEGED_FUNCTION;
/**
* blocking_buffer.h
*
* @code{c}
* BaseType_t xBlockingBufferReset( BlockingBufferHandle_t xBlockingBuffer );
* @endcode
*
* Resets a blocking buffer to its initial, empty, state. Any data that was in
* the blocking buffer is discarded. A blocking buffer can only be reset if there
* are no tasks blocked waiting to either send to or receive from the blocking
* buffer.
*
* @param xBlockingBuffer The handle of the blocking buffer being reset.
*
* @return If the blocking buffer is reset then pdPASS is returned. If there was
* a task blocked waiting to send to or read from the blocking buffer then the
* blocking buffer is not reset and pdFAIL is returned.
*
* \defgroup xBlockingBufferReset xBlockingBufferReset
* \ingroup BlockingBufferManagement
*/
BaseType_t xBlockingBufferReset( BlockingBufferHandle_t xBlockingBuffer ) PRIVILEGED_FUNCTION;
/**
* blocking_buffer.h
*
* @code{c}
* size_t xBlockingBufferSpacesAvailable( BlockingBufferHandle_t xBlockingBuffer );
* @endcode
*
* Queries a blocking buffer to see how much free space it contains, which is
* equal to the amount of data that can be sent to the blocking buffer before it
* is full.
*
* @param xBlockingBuffer The handle of the blocking buffer being queried.
*
* @return The number of bytes that can be written to the blocking buffer before
* the blocking buffer would be full.
*
* \defgroup xBlockingBufferSpacesAvailable xBlockingBufferSpacesAvailable
* \ingroup BlockingBufferManagement
*/
size_t xBlockingBufferSpacesAvailable( BlockingBufferHandle_t xBlockingBuffer ) PRIVILEGED_FUNCTION;
/**
* blocking_buffer.h
*
* @code{c}
* size_t xBlockingBufferBytesAvailable( BlockingBufferHandle_t xBlockingBuffer );
* @endcode
*
* Queries a blocking buffer to see how much data it contains, which is equal to
* the number of bytes that can be read from the blocking buffer before the blocking
* buffer would be empty.
*
* @param xBlockingBuffer The handle of the blocking buffer being queried.
*
* @return The number of bytes that can be read from the blocking buffer before
* the blocking buffer would be empty.
*
* \defgroup xBlockingBufferBytesAvailable xBlockingBufferBytesAvailable
* \ingroup BlockingBufferManagement
*/
size_t xBlockingBufferBytesAvailable( BlockingBufferHandle_t xBlockingBuffer ) PRIVILEGED_FUNCTION;
/**
* blocking_buffer.h
*
* @code{c}
* BaseType_t xBlockingBufferSetTriggerLevel( BlockingBufferHandle_t xBlockingBuffer, size_t xTriggerLevel );
* @endcode
*
* A blocking buffer's trigger level is the number of bytes that must be in the
* blocking buffer before a task that is blocked on the blocking 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 blocking 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 blocking buffer that has a trigger level of 10 then the
* task will not be unblocked until the blocking 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 blocking buffer is created, and can be modified
* using xBlockingBufferSetTriggerLevel().
*
* @param xBlockingBuffer The handle of the blocking buffer being updated.
*
* @param xTriggerLevel The new trigger level for the blocking buffer.
*
* @return If xTriggerLevel was less than or equal to the blocking buffer's length
* then the trigger level will be updated and pdTRUE is returned. Otherwise
* pdFALSE is returned.
*
* \defgroup xBlockingBufferSetTriggerLevel xBlockingBufferSetTriggerLevel
* \ingroup BlockingBufferManagement
*/
BaseType_t xBlockingBufferSetTriggerLevel( BlockingBufferHandle_t xBlockingBuffer,
size_t xTriggerLevel ) PRIVILEGED_FUNCTION;
/**
* blocking_buffer.h
*
* @code{c}
* BaseType_t xBlockingBufferSendCompletedFromISR( BlockingBufferHandle_t xBlockingBuffer, 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 blocking buffer. If there was a task that
* was blocked on the message or blocking buffer waiting for data to arrive then
* the sbSEND_COMPLETED() macro sends a notification to the task to remove it
* from the Blocked state. xBlockingBufferSendCompletedFromISR() 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 xBlockingBuffer The handle of the blocking buffer to which data was
* written.
*
* @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
* initialised to pdFALSE before it is passed into
* xBlockingBufferSendCompletedFromISR(). If calling
* xBlockingBufferSendCompletedFromISR() 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 xBlockingBufferSendCompletedFromISR xBlockingBufferSendCompletedFromISR
* \ingroup BlockingBufferManagement
*/
BaseType_t xBlockingBufferSendCompletedFromISR( BlockingBufferHandle_t xBlockingBuffer,
BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
/**
* blocking_buffer.h
*
* @code{c}
* BaseType_t xBlockingBufferReceiveCompletedFromISR( BlockingBufferHandle_t xBlockingBuffer, 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 blocking buffer. If there was a task
* that was blocked on the message or blocking buffer waiting for data to arrive
* then the sbRECEIVE_COMPLETED() macro sends a notification to the task to
* remove it from the Blocked state. xBlockingBufferReceiveCompletedFromISR()
* 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 xBlockingBuffer The handle of the blocking buffer from which data was
* read.
*
* @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
* initialised to pdFALSE before it is passed into
* xBlockingBufferReceiveCompletedFromISR(). If calling
* xBlockingBufferReceiveCompletedFromISR() 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 xBlockingBufferReceiveCompletedFromISR xBlockingBufferReceiveCompletedFromISR
* \ingroup BlockingBufferManagement
*/
BaseType_t xBlockingBufferReceiveCompletedFromISR( BlockingBufferHandle_t xBlockingBuffer,
BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
/* Functions below here are not part of the public API. */
BlockingBufferHandle_t xBlockingBufferGenericCreate( size_t xBufferSizeBytes,
size_t xTriggerLevelBytes,
BaseType_t xIsMessageBuffer,
BaseType_t xIsBlockingBuffer,
BlockingBufferCallbackFunction_t pxSendCompletedCallback,
BlockingBufferCallbackFunction_t pxReceiveCompletedCallback ) PRIVILEGED_FUNCTION;
BlockingBufferHandle_t xBlockingBufferGenericCreateStatic( size_t xBufferSizeBytes,
size_t xTriggerLevelBytes,
BaseType_t xIsMessageBuffer,
uint8_t * const pucBlockingBufferStorageArea,
StaticBlockingBuffer_t * const pxStaticBlockingBuffer,
BlockingBufferCallbackFunction_t pxSendCompletedCallback,
BlockingBufferCallbackFunction_t pxReceiveCompletedCallback ) PRIVILEGED_FUNCTION;
size_t xBlockingBufferNextMessageLengthBytes( BlockingBufferHandle_t xBlockingBuffer ) PRIVILEGED_FUNCTION;
#if ( configUSE_TRACE_FACILITY == 1 )
void vBlockingBufferSetBlockingBufferNumber( BlockingBufferHandle_t xBlockingBuffer,
UBaseType_t uxBlockingBufferNumber ) PRIVILEGED_FUNCTION;
UBaseType_t uxBlockingBufferGetBlockingBufferNumber( BlockingBufferHandle_t xBlockingBuffer ) PRIVILEGED_FUNCTION;
uint8_t ucBlockingBufferGetBlockingBufferType( BlockingBufferHandle_t xBlockingBuffer ) PRIVILEGED_FUNCTION;
#endif
/* *INDENT-OFF* */
#if defined( __cplusplus )
}
#endif
/* *INDENT-ON* */
#endif /* !defined( STREAM_BUFFER_H ) */