stream_buffer.h

/*
 * FreeRTOS Kernel V10.0.1
 * 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.
 *
 * 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 stream_buf_send()) 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
 
#if defined( __cplusplus )
extern "C" {
#endif

typedef void * stream_buf_t;
 

#define stream_buf_create( xBufferSizeBytes, xTriggerLevelBytes ) xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE )

#define stream_buf_create_static( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer ) xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE, pucStreamBufferStorageArea, pxStaticStreamBuffer )

size_t stream_buf_send( stream_buf_t xStreamBuffer,
                          const void *pvTxData,
                          size_t xDataLengthBytes,
                          uint32_t xTicksToWait ) ;

size_t xStreamBufferSendFromISR( stream_buf_t xStreamBuffer,
                                 const void *pvTxData,
                                 size_t xDataLengthBytes,
                                 int32_t * const pxHigherPriorityTaskWoken ) ;

size_t stream_buf_recv( stream_buf_t xStreamBuffer,
                             void *pvRxData,
                             size_t xBufferLengthBytes,
                             uint32_t xTicksToWait ) ;

size_t xStreamBufferReceiveFromISR( stream_buf_t xStreamBuffer,
                                    void *pvRxData,
                                    size_t xBufferLengthBytes,
                                    int32_t * const pxHigherPriorityTaskWoken ) ;

void vStreamBufferDelete( stream_buf_t xStreamBuffer ) ;

int32_t stream_buf_is_full( stream_buf_t xStreamBuffer ) ;

int32_t stream_buf_is_empty( stream_buf_t xStreamBuffer ) ;

int32_t stream_buf_reset( stream_buf_t xStreamBuffer ) ;

size_t stream_buf_get_unused( stream_buf_t xStreamBuffer ) ;

size_t stream_buf_get_used( stream_buf_t xStreamBuffer ) ;

int32_t stream_buf_set_trigger( stream_buf_t xStreamBuffer, size_t xTriggerLevel ) ;

int32_t xStreamBufferSendCompletedFromISR( stream_buf_t xStreamBuffer, int32_t *pxHigherPriorityTaskWoken ) ;

int32_t xStreamBufferReceiveCompletedFromISR( stream_buf_t xStreamBuffer, int32_t *pxHigherPriorityTaskWoken ) ;
 
/* Functions below here are not part of the public API. */
stream_buf_t xStreamBufferGenericCreate( size_t xBufferSizeBytes,
                                                 size_t xTriggerLevelBytes,
                                                 int32_t xIsMessageBuffer ) ;
 
stream_buf_t xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes,
                                                       size_t xTriggerLevelBytes,
                                                       int32_t xIsMessageBuffer,
                                                       uint8_t * const pucStreamBufferStorageArea,
                                                       static_stream_buf_s_t * const pxStaticStreamBuffer ) ;
 
#if( configUSE_TRACE_FACILITY == 1 )
    void vStreamBufferSetStreamBufferNumber( stream_buf_t xStreamBuffer, uint32_t uxStreamBufferNumber ) ;
    uint32_t uxStreamBufferGetStreamBufferNumber( stream_buf_t xStreamBuffer ) ;
    uint8_t ucStreamBufferGetStreamBufferType( stream_buf_t xStreamBuffer ) ;
#endif
 
#if defined( __cplusplus )
}
#endif
 
#endif  /* !defined( STREAM_BUFFER_H ) */