WizziLab / WizziCom

WizziLab's serial protocol library

Dependents:   modem_ref_helper_for_v5_3_217 modem_ref_helper

kal_buf_circ.h@9:0140247bab90, 2021-01-25 (annotated)

Committer:
Jeej
Date:
Mon Jan 25 09:45:10 2021 +0000
Revision:
9:0140247bab90
Child:
10:c87566aded6e
Use single byte interrupt to be able to re-sync.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jeej 9:0140247bab90 1 /// @copyright
Jeej 9:0140247bab90 2 /// ========================================================================={{{
Jeej 9:0140247bab90 3 /// Copyright (c) 2013-2019 WizziLab /
Jeej 9:0140247bab90 4 /// All rights reserved /
Jeej 9:0140247bab90 5 /// /
Jeej 9:0140247bab90 6 /// IMPORTANT: This Software may not be modified, copied or distributed unless /
Jeej 9:0140247bab90 7 /// embedded on a WizziLab product. Other than for the foregoing purpose, this /
Jeej 9:0140247bab90 8 /// Software and/or its documentation may not be used, reproduced, copied, /
Jeej 9:0140247bab90 9 /// prepared derivative works of, modified, performed, distributed, displayed /
Jeej 9:0140247bab90 10 /// or sold for any purpose. For the sole purpose of embedding this Software /
Jeej 9:0140247bab90 11 /// on a WizziLab product, copy, modification and distribution of this /
Jeej 9:0140247bab90 12 /// Software is granted provided that the following conditions are respected: /
Jeej 9:0140247bab90 13 /// /
Jeej 9:0140247bab90 14 /// * Redistributions of source code must retain the above copyright notice, /
Jeej 9:0140247bab90 15 /// this list of conditions and the following disclaimer /
Jeej 9:0140247bab90 16 /// /
Jeej 9:0140247bab90 17 /// * Redistributions in binary form must reproduce the above copyright /
Jeej 9:0140247bab90 18 /// notice, this list of conditions and the following disclaimer in the /
Jeej 9:0140247bab90 19 /// documentation and/or other materials provided with the distribution. /
Jeej 9:0140247bab90 20 /// /
Jeej 9:0140247bab90 21 /// * The name of WizziLab can not be used to endorse or promote products /
Jeej 9:0140247bab90 22 /// derived from this software without specific prior written permission. /
Jeej 9:0140247bab90 23 /// /
Jeej 9:0140247bab90 24 /// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS /
Jeej 9:0140247bab90 25 /// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED /
Jeej 9:0140247bab90 26 /// TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR /
Jeej 9:0140247bab90 27 /// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR /
Jeej 9:0140247bab90 28 /// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, /
Jeej 9:0140247bab90 29 /// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, /
Jeej 9:0140247bab90 30 /// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, /
Jeej 9:0140247bab90 31 /// OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY /
Jeej 9:0140247bab90 32 /// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING /
Jeej 9:0140247bab90 33 /// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS /
Jeej 9:0140247bab90 34 /// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. /
Jeej 9:0140247bab90 35 /// WIZZILAB HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, /
Jeej 9:0140247bab90 36 /// ENHANCEMENTS OR MODIFICATIONS. /
Jeej 9:0140247bab90 37 /// /
Jeej 9:0140247bab90 38 /// Should you have any questions regarding your right to use this Software, /
Jeej 9:0140247bab90 39 /// contact WizziLab at www.wizzilab.com. /
Jeej 9:0140247bab90 40 /// /
Jeej 9:0140247bab90 41 /// =========================================================================}}}
Jeej 9:0140247bab90 42 /// @endcopyright
Jeej 9:0140247bab90 43
Jeej 9:0140247bab90 44 // =======================================================================
Jeej 9:0140247bab90 45 /// @file kal_buf.c
Jeej 9:0140247bab90 46 /// @brief Buffers header
Jeej 9:0140247bab90 47 // =======================================================================
Jeej 9:0140247bab90 48
Jeej 9:0140247bab90 49 #ifndef __KAL_BUF_CIRC_H__
Jeej 9:0140247bab90 50 #define __KAL_BUF_CIRC_H__
Jeej 9:0140247bab90 51
Jeej 9:0140247bab90 52 #include "mbed.h"
Jeej 9:0140247bab90 53
Jeej 9:0140247bab90 54 // define to create a static Circular buffer buffer
Jeej 9:0140247bab90 55 #define kal_buf_circ_static_buffer_t(_name, _nb_elements, _element_size) uint8_t _name[(_nb_elements+1)*_element_size]
Jeej 9:0140247bab90 56
Jeej 9:0140247bab90 57 typedef struct {
Jeej 9:0140247bab90 58 uint8_t* buffer;
Jeej 9:0140247bab90 59 volatile uint32_t head;
Jeej 9:0140247bab90 60 volatile uint32_t tail;
Jeej 9:0140247bab90 61 uint32_t element_size;
Jeej 9:0140247bab90 62 uint32_t max_length;
Jeej 9:0140247bab90 63 uint8_t is_static;
Jeej 9:0140247bab90 64 } kal_buf_circ_static_handle_t;
Jeej 9:0140247bab90 65
Jeej 9:0140247bab90 66 typedef void* kal_buf_circ_handle_t;
Jeej 9:0140247bab90 67
Jeej 9:0140247bab90 68 //--------------------
Jeej 9:0140247bab90 69 /// @brief Dynamically creates a Circular buffer
Jeej 9:0140247bab90 70 /// @param uint32_t Maximum number of elements in the buffer
Jeej 9:0140247bab90 71 /// @param uint32_t Size of each element
Jeej 9:0140247bab90 72 /// @retval kal_buf_circ_handle_t Circular buffer handle (NULL if create failed)
Jeej 9:0140247bab90 73 //--------------------
Jeej 9:0140247bab90 74 kal_buf_circ_handle_t kal_buf_circ_create(uint32_t nb_elements, uint32_t element_size);
Jeej 9:0140247bab90 75
Jeej 9:0140247bab90 76 //--------------------
Jeej 9:0140247bab90 77 /// @brief Statically creates a Circular buffer
Jeej 9:0140247bab90 78 /// @param kal_buf_circ_StaticHandle_t* Pointer to the static handle
Jeej 9:0140247bab90 79 /// @param uint8_t* Static buffer created with kal_buf_circ_StaticBuffer_t macro
Jeej 9:0140247bab90 80 /// @param uint32_t Maximum number of elements in the buffer
Jeej 9:0140247bab90 81 /// @param uint32_t Size of each element
Jeej 9:0140247bab90 82 /// @retval int 0 if function is successful, -1 otherwise
Jeej 9:0140247bab90 83 //--------------------
Jeej 9:0140247bab90 84 int kal_buf_circ_create_static(kal_buf_circ_static_handle_t* static_handle, uint8_t* buffer, uint32_t nb_elements, uint32_t element_size);
Jeej 9:0140247bab90 85
Jeej 9:0140247bab90 86 //--------------------
Jeej 9:0140247bab90 87 /// @brief Deletes a Circular buffer (Static or Dynamic)
Jeej 9:0140247bab90 88 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 89 /// @retval int 0 if function is successful, -1 otherwise
Jeej 9:0140247bab90 90 //--------------------
Jeej 9:0140247bab90 91 int kal_buf_circ_delete(kal_buf_circ_handle_t handle);
Jeej 9:0140247bab90 92
Jeej 9:0140247bab90 93 //--------------------
Jeej 9:0140247bab90 94 /// @brief Empty the Circular buffer
Jeej 9:0140247bab90 95 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 96 /// @retval int 0 if function is successful, -1 otherwise
Jeej 9:0140247bab90 97 //--------------------
Jeej 9:0140247bab90 98 int kal_buf_circ_reset(kal_buf_circ_handle_t handle);
Jeej 9:0140247bab90 99
Jeej 9:0140247bab90 100 //--------------------
Jeej 9:0140247bab90 101 /// @brief Check if buffer is full
Jeej 9:0140247bab90 102 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 103 /// @retval int TRUE if buffer is full, FALSE otherwise
Jeej 9:0140247bab90 104 //--------------------
Jeej 9:0140247bab90 105 int kal_buf_circ_full(kal_buf_circ_handle_t handle);
Jeej 9:0140247bab90 106
Jeej 9:0140247bab90 107 //--------------------
Jeej 9:0140247bab90 108 /// @brief Check if buffer is empty
Jeej 9:0140247bab90 109 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 110 /// @retval int TRUE if buffer is empty, FALSE otherwise
Jeej 9:0140247bab90 111 //--------------------
Jeej 9:0140247bab90 112 int kal_buf_circ_empty(kal_buf_circ_handle_t handle);
Jeej 9:0140247bab90 113
Jeej 9:0140247bab90 114 //--------------------
Jeej 9:0140247bab90 115 /// @brief Returns the number of elements currently in the buffer
Jeej 9:0140247bab90 116 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 117 /// @retval uint32_t Number of elements in the buffer
Jeej 9:0140247bab90 118 //--------------------
Jeej 9:0140247bab90 119 uint32_t kal_buf_circ_size(kal_buf_circ_handle_t handle);
Jeej 9:0140247bab90 120
Jeej 9:0140247bab90 121 //--------------------
Jeej 9:0140247bab90 122 /// @brief Adds an element to the buffer
Jeej 9:0140247bab90 123 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 124 /// @param uint8_t* Pointer to the element to push in the buffer
Jeej 9:0140247bab90 125 /// @retval int 0 if function is successful, -1 otherwise (buffer full)
Jeej 9:0140247bab90 126 //--------------------
Jeej 9:0140247bab90 127 int kal_buf_circ_push(kal_buf_circ_handle_t handle, uint8_t* p);
Jeej 9:0140247bab90 128
Jeej 9:0140247bab90 129 //--------------------
Jeej 9:0140247bab90 130 /// @brief Gets an element from the buffer
Jeej 9:0140247bab90 131 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 132 /// @param uint8_t* Pointer to the element to get from the buffer, can be NULL to discard data
Jeej 9:0140247bab90 133 /// @retval int 0 if function is successful, -1 otherwise (buffer empty)
Jeej 9:0140247bab90 134 //--------------------
Jeej 9:0140247bab90 135 int kal_buf_circ_pop(kal_buf_circ_handle_t handle, uint8_t* p);
Jeej 9:0140247bab90 136
Jeej 9:0140247bab90 137 //--------------------
Jeej 9:0140247bab90 138 /// @brief Gets an element from the buffer without removing it from the buffer
Jeej 9:0140247bab90 139 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 140 /// @param uint8_t* Pointer to the element to get from the buffer
Jeej 9:0140247bab90 141 /// @retval int 0 if function is successful, -1 otherwise (buffer empty)
Jeej 9:0140247bab90 142 //--------------------
Jeej 9:0140247bab90 143 int kal_buf_circ_peek(kal_buf_circ_handle_t handle, uint8_t* p);
Jeej 9:0140247bab90 144
Jeej 9:0140247bab90 145 //--------------------
Jeej 9:0140247bab90 146 /// @brief Write several elements to the buffer
Jeej 9:0140247bab90 147 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 148 /// @param uint8_t* Pointer to the element array to write to the buffer
Jeej 9:0140247bab90 149 /// @param uint32_t Number of elements to write
Jeej 9:0140247bab90 150 /// @retval int 0 if function is successful, -1 otherwise
Jeej 9:0140247bab90 151 //--------------------
Jeej 9:0140247bab90 152 int kal_buf_circ_put(kal_buf_circ_handle_t handle, uint8_t* p, uint32_t nb_elements);
Jeej 9:0140247bab90 153
Jeej 9:0140247bab90 154 //--------------------
Jeej 9:0140247bab90 155 /// @brief Gets several elements from the buffer
Jeej 9:0140247bab90 156 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 157 /// @param uint8_t* Pointer to the element array to get from the buffer, can be NULL to discard data
Jeej 9:0140247bab90 158 /// @param uint32_t Number of elements to get
Jeej 9:0140247bab90 159 /// @retval int 0 if function is successful, -1 otherwise
Jeej 9:0140247bab90 160 //--------------------
Jeej 9:0140247bab90 161 int kal_buf_circ_get(kal_buf_circ_handle_t handle, uint8_t* p, uint32_t nb_elements);
Jeej 9:0140247bab90 162
Jeej 9:0140247bab90 163 //--------------------
Jeej 9:0140247bab90 164 /// @brief Gets several elements from the buffer without removing them from the buffer
Jeej 9:0140247bab90 165 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 166 /// @param uint8_t* Pointer to the element array to get from the buffer
Jeej 9:0140247bab90 167 /// @param uint32_t Number of elements to get
Jeej 9:0140247bab90 168 /// @retval int 0 if function is successful, -1 otherwise
Jeej 9:0140247bab90 169 //--------------------
Jeej 9:0140247bab90 170 int kal_buf_circ_fetch(kal_buf_circ_handle_t handle, uint8_t* p, uint32_t nb_elements);
Jeej 9:0140247bab90 171
Jeej 9:0140247bab90 172 //--------------------
Jeej 9:0140247bab90 173 /// @brief Erase the last element written to the buffer
Jeej 9:0140247bab90 174 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 175 /// @retval int 0 if function is successful, -1 otherwise (buffer empty)
Jeej 9:0140247bab90 176 //--------------------
Jeej 9:0140247bab90 177 int kal_buf_circ_erase(kal_buf_circ_handle_t handle);
Jeej 9:0140247bab90 178
Jeej 9:0140247bab90 179 #endif // __KAL_BUF_CIRC_H__