# 环形缓冲管理

SylixOS 的环形缓冲管理兼容 VxWorks。环形缓冲区主要是为了节省内存空间。用户使用环形缓冲区可以重复的对同一块内存空间进行读写操作，当用户的读写操作到达缓冲区尾端时，会重新从缓冲区的开始继续读写。但当多个进程使用同一个环形缓冲区时，则需要用户在不同进程间进行互斥操作，此时可以使用信号量或者互斥锁来保证在同一时段只有一个进程访问环形缓冲区，环形缓冲区的主要函数位于“libsylixos/system/util/rngLib.c”中。

VX_RING 是环形缓冲的结构体，其详细描述如下：

#include <SylixOS.h>
typedef struct {
INT                  VXRING_iToBuf;
INT                  VXRING_iFromBuf;
INT                  VXRING_iBufByteSize;
PCHAR                VXRING_pcBuf;
} VX_RING;
typedef VX_RING     *VX_RING_ID; 

• VXRING_iToBuf：写入位置相对于缓冲区头指针的偏移。
• VXRING_iFromBuf：读出位置相对于缓冲区头指针的偏移。
• VXRING_iBufByteSize：缓冲区长度。
• VXRING_pcBuf：缓冲区头指针。

说明：
用户在管理环形缓冲区结构体中的相关成员时，请使用系统提供的管理接口，以便驱动可以向后兼容。

# 创建环形缓冲区

函数 _rngCreate 的功能是建立一个兼容 VxWorks 的 ring buffer 缓冲区，用户需要提供的参数是缓冲区的大小。其详细描述如下：

#include <SylixOS.h>
VX_RING_ID  _rngCreate (INT  iNBytes);

函数 _rngCreate 的原型分析：

• 函数正确返回缓冲区结构体指针，否则返回 LW_NULL 。
• 参数 iNBytes 是缓冲区大小。

# 删除环形缓冲区

函数 _rngDelete 的功能是删除一个已经创建的环形缓冲区，用户需要提供的参数是已创建的环形缓冲区的结构体指针，其详细描述如下：

#include <SylixOS.h>
VOID  _rngDelete (VX_RING_ID  vxringid);

函数 _rngDelete 的原型分析：

• 参数 vxringid 是缓冲区控制块指针。

# 环形缓冲区读写函数

函数 _rngBufGet 的功能是读取缓冲区数据，用户需要提供的参数是已创建的环形缓冲区的结构体指针、读出的数据存放位置的地址和需要读出的最大字节数。其详细描述如下：

#include <SylixOS.h>
INT  _rngBufGet (VX_RING_ID      vxringid,
PCHAR            pcBuffer,
INT              iMaxBytes);

函数 _rngBufGet 的原型分析：

• 函数的返回值为成功从缓冲区读取的字节数。
• 参数 vxringid 是缓冲区控制块指针。
• 参数 pcBuffer 是读出的数据存放位置的地址。
• 参数 iMaxBytes 是读出最多的字节数。

函数 _rngBufPut 的功能是写缓冲区，用户需要提供的参数是已创建的环形缓冲区的结构体指针、需要写入的数据存放位置的首地址和需要写入的最大字节数。其详细描述如下：

#include <SylixOS.h>
INT  _rngBufPut (VX_RING_ID      vxringid,
                 PCHAR           pcBuffer,
                 INT             iNBytes);

函数 _rngBufPut 的原型分析：

• 函数的返回值为成功写入缓冲区的字节数。
• 参数 vxringid 是缓冲区控制块地址。
• 参数 pcBuffer 是写入的数据存放位置的首地址。
• 参数 iNBytes 是最大写入的字节数。

# 环形缓冲区管理函数

函数 _rngSizeGet 的功能是获得一个已创建的缓冲区的大小，用户需要提供的参数是已创建的环形缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
INT  _rngSizeGet (VX_RING_ID  vxringid);

函数 _rngSizeGet 的原型分析：

• 函数成功返回已分配的缓冲区大小，失败时返回 PX_ERROR 。
• vxringid 参数是缓冲区控制块指针。

函数 _rngFlush 的功能是将一个已创建的缓冲区清空，用户需要提供的参数是已创建的环形缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
INT  _rngFlush (VX_RING_ID  vxringid);

函数 _rngFlush 的原型分析：

• vxringid 参数是缓冲区控制块指针。

函数 _rngIsEmpty 的功能是判断缓冲区是否为空，用户需要提供的参数是已创建的环形缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
INT  _rngIsEmpty (VX_RING_ID  vxringid);

函数 _rngIsEmpty 的原型分析：

• 当函数的返回值为 1 时表示缓冲区为空，返回值为 0 时表示缓冲区不为空。
• vxringid 参数是缓冲区控制块指针。

函数 _rngIsFull 的功能是判断缓冲区是否已满，用户需要提供的参数是已创建的环形缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
INT  _rngIsFull (VX_RING_ID  vxringid);

函数 _rngIsFull 的原型分析：

• 当函数的返回值为 1 时缓冲区已满，返回值为 0 时为缓冲区未满。
• vxringid 参数是缓冲区控制块指针。

函数 _rngFreeBytes 的功能是检查缓冲区的空闲字节数，用户需要提供的参数是已创建的环形缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
INT  _rngFreeBytes (VX_RING_ID  vxringid);

函数 _rngFreeBytes 的原型分析：

• 函数的返回值为空闲字节数。
• vxringid 参数是缓冲区控制块指针。

函数 _rngNBytes 的功能是检查缓冲区的有效字节数，用户需要提供的参数是已创建的环形缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
INT  _rngNBytes (VX_RING_ID  vxringid);

函数 _rngNBytes 的原型分析：

• 函数的返回值为有效字节数。
• vxringid 参数是缓冲区控制块指针。

函数 _rngPutAhead 的功能是将一个字符的信息放入一个缓冲区，用户需要提供的参数是已创建的环形缓冲区的结构体指针、要插入的字符和插入字节位置的偏移量。其详细描述如下：

#include <SylixOS.h>
VOID  _rngPutAhead  (VX_RING_ID      vxringid,
                     CHAR            cByte,
                     INT             iOffset);

函数 _rngPutAhead 的原型分析：

• vxringid 参数是缓冲区控制块指针。
• cByte 参数是要插入的字节。
• iOffset 参数是插入字节位置的偏移量。

函数 _rngMoveAhead 的功能是改变一个缓冲区的写入位置相对于开始指针的偏移（VXRING_iToBuf），用户需要提供的参数是已创建的环形缓冲区的结构体指针、需要的推移量。其详细描述如下：

#include <SylixOS.h>
VOID  _rngMoveAhead    (VX_RING_ID      vxringid,
                        INT             iNum);

函数 _rngMoveAhead 的原型分析：

• vxringid 参数是缓冲区控制块指针。
• iNum 参数是推移量。

用户调用 _rngMoveAhead，当传入的 iNum 大于等于 vxringid 的缓冲区长度（VXRING_iBufByteSize）成员时， iNum 要减去缓冲区长度，然后再被赋值给 VXRING_iToBuf；否则 iNum 直接赋值给 VXRING_iToBuf。

环形缓冲区节省了内存的使用，提高了内存使用的利用率。只要读者、写者一直不断的操作环形缓冲区，缓冲区就可以循环使用。在 TTY 内部库中的数据缓冲区管理中就使用了环形缓冲区，TTY 内部库在“libsylixos/system/device/ty/tyLib.c”文件中。