WizziLab / WizziCom

WizziLab's serial protocol library

Dependents:   modem_ref_helper_for_v5_3_217 modem_ref_helper

kal_buf_circ.h@12:9edd3fd978d2, 2021-02-19 (annotated)

Committer:
Jeej
Date:
Fri Feb 19 10:59:27 2021 +0000
Revision:
12:9edd3fd978d2
Parent:
10:c87566aded6e 
Removed debug

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jeej 9:0140247bab90 1 /// @copyright
Jeej 9:0140247bab90 2 /// ========================================================================={{{
Jeej 10:c87566aded6e 3 /// Copyright (c) 2013-2021 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 10:c87566aded6e 70 /// @param uint32_t Maximum number of elements in the buffer
Jeej 10:c87566aded6e 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 10:c87566aded6e 79 /// @param uint8_t* Static buffer created with kal_buf_circ_StaticBuffer_t macro
Jeej 10:c87566aded6e 80 /// @param uint32_t Maximum number of elements in the buffer
Jeej 10:c87566aded6e 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 10:c87566aded6e 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 10:c87566aded6e 122 /// @brief Returns the number of free elements in the buffer
Jeej 10:c87566aded6e 123 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 10:c87566aded6e 124 /// @retval uint32_t Number of elements in the buffer
Jeej 10:c87566aded6e 125 //--------------------
Jeej 10:c87566aded6e 126 uint32_t kal_buf_circ_space(kal_buf_circ_handle_t handle);
Jeej 10:c87566aded6e 127
Jeej 10:c87566aded6e 128 //--------------------
Jeej 9:0140247bab90 129 /// @brief Adds an element to the buffer
Jeej 9:0140247bab90 130 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 10:c87566aded6e 131 /// @param uint8_t* Pointer to the element to push in the buffer
Jeej 9:0140247bab90 132 /// @retval int 0 if function is successful, -1 otherwise (buffer full)
Jeej 9:0140247bab90 133 //--------------------
Jeej 9:0140247bab90 134 int kal_buf_circ_push(kal_buf_circ_handle_t handle, uint8_t* p);
Jeej 9:0140247bab90 135
Jeej 9:0140247bab90 136 //--------------------
Jeej 9:0140247bab90 137 /// @brief Gets an element from the buffer
Jeej 9:0140247bab90 138 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 10:c87566aded6e 139 /// @param uint8_t* Pointer to the element to get from the buffer, can be NULL to discard data
Jeej 9:0140247bab90 140 /// @retval int 0 if function is successful, -1 otherwise (buffer empty)
Jeej 9:0140247bab90 141 //--------------------
Jeej 9:0140247bab90 142 int kal_buf_circ_pop(kal_buf_circ_handle_t handle, uint8_t* p);
Jeej 9:0140247bab90 143
Jeej 9:0140247bab90 144 //--------------------
Jeej 9:0140247bab90 145 /// @brief Gets an element from the buffer without removing it from the buffer
Jeej 9:0140247bab90 146 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 10:c87566aded6e 147 /// @param uint8_t* Pointer to the element to get from the buffer
Jeej 9:0140247bab90 148 /// @retval int 0 if function is successful, -1 otherwise (buffer empty)
Jeej 9:0140247bab90 149 //--------------------
Jeej 9:0140247bab90 150 int kal_buf_circ_peek(kal_buf_circ_handle_t handle, uint8_t* p);
Jeej 9:0140247bab90 151
Jeej 9:0140247bab90 152 //--------------------
Jeej 9:0140247bab90 153 /// @brief Write several elements to the buffer
Jeej 9:0140247bab90 154 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 10:c87566aded6e 155 /// @param uint8_t* Pointer to the element array to write to the buffer
Jeej 10:c87566aded6e 156 /// @param uint32_t Number of elements to write
Jeej 9:0140247bab90 157 /// @retval int 0 if function is successful, -1 otherwise
Jeej 9:0140247bab90 158 //--------------------
Jeej 9:0140247bab90 159 int kal_buf_circ_put(kal_buf_circ_handle_t handle, uint8_t* p, uint32_t nb_elements);
Jeej 9:0140247bab90 160
Jeej 9:0140247bab90 161 //--------------------
Jeej 9:0140247bab90 162 /// @brief Gets several elements from the buffer
Jeej 9:0140247bab90 163 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 10:c87566aded6e 164 /// @param uint8_t* Pointer to the element array to get from the buffer, can be NULL to discard data
Jeej 10:c87566aded6e 165 /// @param uint32_t Number of elements to get
Jeej 9:0140247bab90 166 /// @retval int 0 if function is successful, -1 otherwise
Jeej 9:0140247bab90 167 //--------------------
Jeej 9:0140247bab90 168 int kal_buf_circ_get(kal_buf_circ_handle_t handle, uint8_t* p, uint32_t nb_elements);
Jeej 9:0140247bab90 169
Jeej 9:0140247bab90 170 //--------------------
Jeej 9:0140247bab90 171 /// @brief Gets several elements from the buffer without removing them from the buffer
Jeej 9:0140247bab90 172 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 10:c87566aded6e 173 /// @param uint8_t* Pointer to the element array to get from the buffer
Jeej 10:c87566aded6e 174 /// @param uint32_t Number of elements to get
Jeej 9:0140247bab90 175 /// @retval int 0 if function is successful, -1 otherwise
Jeej 9:0140247bab90 176 //--------------------
Jeej 9:0140247bab90 177 int kal_buf_circ_fetch(kal_buf_circ_handle_t handle, uint8_t* p, uint32_t nb_elements);
Jeej 9:0140247bab90 178
Jeej 9:0140247bab90 179 //--------------------
Jeej 9:0140247bab90 180 /// @brief Erase the last element written to the buffer
Jeej 9:0140247bab90 181 /// @param kal_buf_circ_handle_t Handle to the Circular buffer
Jeej 9:0140247bab90 182 /// @retval int 0 if function is successful, -1 otherwise (buffer empty)
Jeej 9:0140247bab90 183 //--------------------
Jeej 9:0140247bab90 184 int kal_buf_circ_erase(kal_buf_circ_handle_t handle);
Jeej 9:0140247bab90 185
Jeej 10:c87566aded6e 186 #endif // __KAL_BUF_CIRC_H__