xref: /FreeRTOS-Plus-TCP-v4.0.0/source/include/FreeRTOS_Stream_Buffer.h (revision 1ab6eb88857cf1011bf1f8349b43a1c34c7ced0f) 
1 /*
2  * FreeRTOS+TCP <DEVELOPMENT BRANCH>
3  * Copyright (C) 2022 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
4  *
5  * SPDX-License-Identifier: MIT
6  *
7  * Permission is hereby granted, free of charge, to any person obtaining a copy of
8  * this software and associated documentation files (the "Software"), to deal in
9  * the Software without restriction, including without limitation the rights to
10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
11  * the Software, and to permit persons to whom the Software is furnished to do so,
12  * subject to the following conditions:
13  *
14  * The above copyright notice and this permission notice shall be included in all
15  * copies or substantial portions of the Software.
16  *
17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
20  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
21  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23  *
24  * http://aws.amazon.com/freertos
25  * http://www.FreeRTOS.org
26  */
27 
28 /*
29  *  FreeRTOS_Stream_Buffer.h
30  *
31  *  A circular character buffer
32  *  An implementation of a circular buffer without a length field
33  *  If LENGTH defines the size of the buffer, a maximum of (LENGTH-1) bytes can be stored
34  *  In order to add or read data from the buffer, memcpy() will be called at most 2 times
35  */
36 
37 #ifndef FREERTOS_STREAM_BUFFER_H
38 #define FREERTOS_STREAM_BUFFER_H
39 
40 /* *INDENT-OFF* */
41 #ifdef __cplusplus
42     extern "C" {
43 #endif
44 /* *INDENT-ON* */
45 
46 /**
47  * structure to store all the details of a stream buffer.
48  */
49 typedef struct xSTREAM_BUFFER
50 {
51     volatile size_t uxTail;              /**< next item to read */
52     volatile size_t uxMid;               /**< iterator within the valid items */
53     volatile size_t uxHead;              /**< next position store a new item */
54     volatile size_t uxFront;             /**< iterator within the free space */
55     size_t LENGTH;                       /**< const value: number of reserved elements */
56     uint8_t ucArray[ sizeof( size_t ) ]; /**< array big enough to store any pointer address */
57 } StreamBuffer_t;
58 
59 void vStreamBufferClear( StreamBuffer_t * pxBuffer );
60 /*-----------------------------------------------------------*/
61 
62 size_t uxStreamBufferSpace( const StreamBuffer_t * pxBuffer,
63                             const size_t uxLower,
64                             const size_t uxUpper );
65 /*-----------------------------------------------------------*/
66 
67 size_t uxStreamBufferDistance( const StreamBuffer_t * pxBuffer,
68                                const size_t uxLower,
69                                const size_t uxUpper );
70 /*-----------------------------------------------------------*/
71 
72 size_t uxStreamBufferGetSpace( const StreamBuffer_t * pxBuffer );
73 /*-----------------------------------------------------------*/
74 
75 size_t uxStreamBufferFrontSpace( const StreamBuffer_t * pxBuffer );
76 /*-----------------------------------------------------------*/
77 
78 size_t uxStreamBufferGetSize( const StreamBuffer_t * pxBuffer );
79 /*-----------------------------------------------------------*/
80 
81 size_t uxStreamBufferMidSpace( const StreamBuffer_t * pxBuffer );
82 /*-----------------------------------------------------------*/
83 
84 void vStreamBufferMoveMid( StreamBuffer_t * pxBuffer,
85                            size_t uxCount );
86 /*-----------------------------------------------------------*/
87 
88 BaseType_t xStreamBufferLessThenEqual( const StreamBuffer_t * pxBuffer,
89                                        const size_t uxLeft,
90                                        const size_t uxRight );
91 /*-----------------------------------------------------------*/
92 
93 size_t uxStreamBufferGetPtr( StreamBuffer_t * pxBuffer,
94                              uint8_t ** ppucData );
95 
96 /*
97  * Add bytes to a stream buffer.
98  *
99  * pxBuffer -   The buffer to which the bytes will be added.
100  * uxOffset -   If uxOffset > 0, data will be written at an offset from uxHead
101  *              while uxHead will not be moved yet.
102  * pucData -    A pointer to the data to be added.
103  * uxCount -    The number of bytes to add.
104  */
105 size_t uxStreamBufferAdd( StreamBuffer_t * pxBuffer,
106                           size_t uxOffset,
107                           const uint8_t * pucData,
108                           size_t uxByteCount );
109 
110 /*
111  * Read bytes from a stream buffer.
112  *
113  * pxBuffer -   The buffer from which the bytes will be read.
114  * uxOffset -   Can be used to read data located at a certain offset from 'uxTail'.
115  * pucData -    A pointer to the buffer into which data will be read.
116  * uxMaxCount - The number of bytes to read.
117  * xPeek -      If set to pdTRUE the data will remain in the buffer.
118  */
119 size_t uxStreamBufferGet( StreamBuffer_t * pxBuffer,
120                           size_t uxOffset,
121                           uint8_t * pucData,
122                           size_t uxMaxCount,
123                           BaseType_t xPeek );
124 
125 /* *INDENT-OFF* */
126 #ifdef __cplusplus
127     } /* extern "C" */
128 #endif
129 /* *INDENT-ON* */
130 
131 #endif /* !defined( FREERTOS_STREAM_BUFFER_H ) */
132