1 /* ---------------------------------------------------------------------------- 2 * Copyright (c) Huawei Technologies Co., Ltd. 2019-2019. All rights reserved. 3 * Description: Ring Buffer Public HeadFile 4 * Author: Huawei LiteOS Team 5 * Create: 2019-10-10 6 * Redistribution and use in source and binary forms, with or without modification, 7 * are permitted provided that the following conditions are met: 8 * 1. Redistributions of source code must retain the above copyright notice, this list of 9 * conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list 11 * of conditions and the following disclaimer in the documentation and/or other materials 12 * provided with the distribution. 13 * 3. Neither the name of the copyright holder nor the names of its contributors may be used 14 * to endorse or promote products derived from this software without specific prior written 15 * permission. 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 17 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 18 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 20 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 21 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 22 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 23 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 25 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 26 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 * --------------------------------------------------------------------------- */ 28 29 /** 30 * @defgroup los_ringbuf RingBuffer 31 * @ingroup kernel 32 */ 33 34 #ifndef _LOS_RINGBUF_H 35 #define _LOS_RINGBUF_H 36 37 #include "los_typedef.h" 38 #include "los_spinlock.h" 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif /* __cplusplus */ 43 44 /** 45 * @ingroup los_ringbuf 46 * Ringbuf Status. 47 */ 48 typedef enum { 49 RBUF_UNINIT, /**< Ringbuf is not inited. */ 50 RBUF_INITED /**< Ringbuf is inited. */ 51 } RingbufStatus; 52 53 /** 54 * @ingroup los_ringbuf 55 * Ringbuf Flag. 56 */ 57 typedef enum { 58 RBUF_NORMAL, /**< Ringbuf is normal. */ 59 RBUF_OVERWRITE /**< Ringbuf can be overwritten. */ 60 } RingbufFlag; 61 62 /** 63 * @ingroup los_ringbuf 64 * Ringbuf information structure. 65 * 66 */ 67 typedef struct { 68 UINT32 startIdx; /**< Ringbuf read index */ 69 UINT32 endIdx; /**< Ringbuf write index */ 70 UINT32 size; /**< Ringbuf total size */ 71 UINT32 remain; /**< Ringbuf free size */ 72 SPIN_LOCK_S lock; /**< Lock for read and write */ 73 RingbufStatus status; /**< Ringbuf status */ 74 RingbufFlag flag; /**< Ringbuf flag */ 75 CHAR *fifo; /**< Buf to store data */ 76 } Ringbuf; 77 78 /** 79 * @ingroup los_ringbuf 80 * @brief Init a ringbuf. 81 * 82 * @par Description: 83 * This API is used to init a ringbuf. 84 * @attention 85 * The size must not be bigger than the fifo's actual size. 86 * 87 * @param ringbuf [OUT] Ringbuf control block. 88 * @param fifo [IN] Data buf address. 89 * @param size [IN] Data buf size. 90 * @param flag [IN] Data buf flag. 91 * 92 * @retval #LOS_NOK Init failed, check the legality of function parameters. 93 * @retval #LOS_OK Init success. 94 * 95 * @par Dependency: 96 * <ul><li>los_ringbuf.h: the header file that contains the API declaration.</li></ul> 97 * @see LOS_RingbufInit 98 * @since Huawei LiteOS V200R005C10 99 */ 100 extern UINT32 LOS_RingbufInit(Ringbuf *ringbuf, CHAR *fifo, UINT32 size, RingbufFlag flag); 101 102 /** 103 * @ingroup los_ringbuf 104 * @brief Reset a ringbuf. 105 * 106 * @par Description: 107 * This API is used to reset a ringbuf to the init status. 108 * @attention 109 * The specific ringbuf must be inited first. 110 * 111 * @param ringbuf [IN] Ringbuf created by LOS_RingbufInit. 112 * 113 * @retval None. 114 * 115 * @par Dependency: 116 * <ul><li>los_ringbuf.h: the header file that contains the API declaration.</li></ul> 117 * @see LOS_RingbufReset 118 * @since Huawei LiteOS V200R005C10 119 */ 120 extern VOID LOS_RingbufReset(Ringbuf *ringbuf); 121 122 /** 123 * @ingroup los_ringbuf 124 * @brief Write data to ringbuf. 125 * 126 * @par Description: 127 * This API is used to write data to ringbuf. 128 * @attention 129 * The specific ringbuf must be inited first. 130 * 131 * @param ringbuf [IN] The ringbuf write data to. 132 * @param buf [IN] The source buf address. 133 * @param size [IN] The source buf size. 134 * 135 * @retval #UINT32 The actual written size. 136 * 137 * @par Dependency: 138 * <ul><li>los_ringbuf.h: the header file that contains the API declaration.</li></ul> 139 * @see LOS_RingbufWrite 140 * @since Huawei LiteOS V200R005C10 141 */ 142 extern UINT32 LOS_RingbufWrite(Ringbuf *ringbuf, const CHAR *buf, UINT32 size); 143 144 /** 145 * @ingroup los_ringbuf 146 * @brief Read data from ringbuf. 147 * 148 * @par Description: 149 * This API is used to get data from ringbuf. 150 * @attention 151 * The specific ringbuf must be inited first. 152 * 153 * @param ringbuf [IN] The ringbuf read data from. 154 * @param buf [OUT] The dest buf address. 155 * @param size [IN] The dest buf size. 156 * 157 * @retval #UINT32 The actual read size. 158 * 159 * @par Dependency: 160 * <ul><li>los_ring.h: the header file that contains the API declaration.</li></ul> 161 * @see LOS_RingbufRead 162 * @since Huawei LiteOS V200R005C10 163 */ 164 extern UINT32 LOS_RingbufRead(Ringbuf *ringbuf, CHAR *buf, UINT32 size); 165 166 /** 167 * @ingroup los_ringbuf 168 * @brief Read data from ringbuf but does not consume the data. 169 * 170 * @par Description: 171 * This API is used to get data from ringbuf but does not consume the data. 172 * @attention 173 * The specific ringbuf must be inited first. 174 * 175 * @param ringbuf [IN] The ringbuf read data from. 176 * @param buf [OUT] The dest buf address. 177 * @param size [IN] The dest buf size. 178 * 179 * @retval #UINT32 The actual read size. 180 * 181 * @par Dependency: 182 * <ul><li>los_ring.h: the header file that contains the API declaration.</li></ul> 183 * @see LOS_RingbufPeek 184 * @since Huawei LiteOS V200R006C20 185 */ 186 extern UINT32 LOS_RingbufPeek(Ringbuf *ringbuf, CHAR *buf, UINT32 size); 187 188 /** 189 * @ingroup los_ringbuf 190 * @brief Get a ringbuf's used size. 191 * 192 * @par Description: 193 * This API is used to get a ringbuf's used size. 194 * @attention 195 * The specific ringbuf must be inited first. 196 * 197 * @param ringbuf [IN] The ringbuf address 198 * 199 * @retval #UINT32 The used size of ringbuf. 200 * 201 * @par Dependency: 202 * <ul><li>los_ringbuf.h: the header file that contains the API declaration.</li></ul> 203 * @see LOS_RingbufUsedSize 204 * @since Huawei LiteOS V200R005C10 205 */ 206 extern UINT32 LOS_RingbufUsedSize(Ringbuf *ringbuf); 207 208 #ifdef __cplusplus 209 } 210 #endif /* __cplusplus */ 211 212 #endif /* _LOS_RINGBUF_H */ 213