/* ---------------------------------------------------------------------------- * Copyright (c) Huawei Technologies Co., Ltd. 2019-2019. All rights reserved. * Description: Ring Buffer Public HeadFile * Author: Huawei LiteOS Team * Create: 2019-10-10 * Redistribution and use in source and binary forms, with or without modification, * are permitted provided that the following conditions are met: * 1. Redistributions of source code must retain the above copyright notice, this list of * conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright notice, this list * of conditions and the following disclaimer in the documentation and/or other materials * provided with the distribution. * 3. Neither the name of the copyright holder nor the names of its contributors may be used * to endorse or promote products derived from this software without specific prior written * permission. * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * --------------------------------------------------------------------------- */ /** * @defgroup los_ringbuf RingBuffer * @ingroup kernel */ #ifndef _LOS_RINGBUF_H #define _LOS_RINGBUF_H #include "los_typedef.h" #include "los_spinlock.h" #ifdef __cplusplus #if __cplusplus extern "C" { #endif /* __cplusplus */ #endif /* __cplusplus */ /** * @ingroup los_ringbuf * Ringbuf Status. */ typedef enum { RBUF_UNINIT, /**< Ringbuf is not inited. */ RBUF_INITED /**< Ringbuf is inited. */ } RingbufStatus; /*这段代码定义了一个名为 RingbufStatus 的枚举类型，表示环形缓冲区的状态。 该枚举类型包含两个枚举值： RBUF_UNINIT：表示环形缓冲区尚未初始化。 RBUF_INITED：表示环形缓冲区已经初始化。 通过使用这个枚举类型，可以方便地标识和判断环形缓冲区的状态。 在使用环形缓冲区时，可以根据不同的状态进行相应的操作或处理。*/ /** * @ingroup los_ringbuf * Ringbuf information structure. * */ typedef struct { UINT32 startIdx; /**< Ringbuf read index */ UINT32 endIdx; /**< Ringbuf write index */ UINT32 size; /**< Ringbuf total size */ UINT32 remain; /**< Ringbuf free size */ SPIN_LOCK_S lock; /**< Lock for read and write */ RingbufStatus status; /**< Ringbuf status */ CHAR *fifo; /**< Buf to store data */ } Ringbuf; /*这段代码定义了一个名为 Ringbuf 的结构体，用于表示环形缓冲区的属性和状态。 该结构体包含以下成员： startIdx：环形缓冲区的读取索引。 endIdx：环形缓冲区的写入索引。 size：环形缓冲区的总大小。 remain：环形缓冲区的剩余可用空间大小。 lock：用于读取和写入操作的自旋锁。 status：环形缓冲区的状态，类型为 RingbufStatus 枚举类型。 fifo：用于存储数据的缓冲区。 通过这个结构体，可以方便地管理环形缓冲区的属性和状态，并进行相应的数据读写操作。*/ /** * @ingroup los_ringbuf * @brief Init a ringbuf. * * @par Description: * This API is used to init a ringbuf. * @attention * The size must not be bigger than the fifo's actual size. * * @param ringbuf [OUT] Ringbuf control block. * @param fifo [IN] Data buf address. * @param size [IN] Data buf size. * * @retval #LOS_NOK Init failed, check the legality of function parameters. * @retval #LOS_OK Init success. * * @par Dependency: * * @see LOS_RingbufInit * @since Huawei LiteOS V200R005C00 */ extern UINT32 LOS_RingbufInit(Ringbuf *ringbuf, CHAR *fifo, UINT32 size); /*该函数的作用是根据给定的参数初始化环形缓冲区对象，并分配必要的资源。通过调用这个函数，可以将一个已经定义的 Ringbuf 结构体对象与指定的缓冲区关联起来，并设置初始状态和属性。*/ /** * @ingroup los_ringbuf * @brief Reset a ringbuf. * * @par Description: * This API is used to reset a ringbuf to the init status. * @attention * The specific ringbuf must be inited first. * * @param ringbuf [IN] Ringbuf created by LOS_RingbufInit. * * @retval None. * * @par Dependency: * * @see LOS_RingbufReset * @since Huawei LiteOS V200R005C00 */ extern VOID LOS_RingbufReset(Ringbuf *ringbuf); /** * @ingroup los_ringbuf * @brief Write data to ringbuf. * * @par Description: * This API is used to write data to ringbuf. * @attention * The specific ringbuf must be inited first. * * @param ringbuf [IN] The ringbuf write data to. * @param buf [IN] The source buf address. * @param size [IN] The source buf size. * * @retval #UINT32 The actual written size. * * @par Dependency: * * @see LOS_RingbufWrite * @since Huawei LiteOS V200R005C00 */ extern UINT32 LOS_RingbufWrite(Ringbuf *ringbuf, const CHAR *buf, UINT32 size); /*该函数的作用是将指定大小的数据从源缓冲区写入到目标环形缓冲区中。写入操作会更新环形缓冲区的写入索引，并根据需要循环覆盖已有数据。如果环形缓冲区的空间不足以容纳全部数据，只会写入部分数据。 通过调用这个函数，可以方便地将数据写入到环形缓冲区中，并实现数据的循环存储和覆盖。*/ /** * @ingroup los_ringbuf * @brief Read data from ringbuf. * * @par Description: * This API is used to get data from ringbuf. * @attention * The specific ringbuf must be inited first. * * @param ringbuf [IN] The ringbuf read data from. * @param buf [OUT] The dest buf address. * @param size [IN] The dest buf size. * * @retval #UINT32 The actual read size. * * @par Dependency: * * @see LOS_RingbufRead * @since Huawei LiteOS V200R005C00 */ extern UINT32 LOS_RingbufRead(Ringbuf *ringbuf, CHAR *buf, UINT32 size); /*该函数的作用是从指定大小的数据中读取数据，并将其存储到目标缓冲区。读取操作会更新环形缓冲区的读取索引，并根据需要循环读取已有数据。如果环形缓冲区中的数据不足以满足全部读取请求，只会读取部分数据。 通过调用这个函数，可以方便地从环形缓冲区中读取数据，并实现数据的循环读取和覆盖。*/ /** * @ingroup los_ringbuf * @brief Get a ringbuf's used size. * * @par Description: * This API is used to get a ringbuf's used size. * @attention * The specific ringbuf must be inited first. * * @param ringbuf [IN] The ringbuf address * * @retval #UINT32 The used size of ringbuf. * * @par Dependency: * * @see LOS_RingbufUsedSize * @since Huawei LiteOS V200R005C00 */ extern UINT32 LOS_RingbufUsedSize(Ringbuf *ringbuf); #ifdef __cplusplus #if __cplusplus } #endif /* __cplusplus */ #endif /* __cplusplus */ #endif /* _LOS_RINGBUF_H */