更新 'stm32 环形缓冲/ringbuffer.h'

不限制大小2的次方

stm32 环形缓冲/ringbuffer.h

@@ -3,7 +3,7 @@
 #include <assert.h>
 /**
  * @file
- * Prototypes and structures for the ring buffer module.
+ * 环形缓冲模块的原型和结构。
  */
 
 #ifndef RINGBUFFER_H
@@ -15,127 +15,126 @@ extern "C"
 #endif
 
 #define RING_BUFFER_ASSERT(x) assert(x)
+#define inline __inline
 
 /**
- * Checks if the buffer_size is a power of two.
- * Due to the design only <tt> RING_BUFFER_SIZE-1 </tt> items
- * can be contained in the buffer.
- * buffer_size must be a power of two.
- * 限制2^N ​​预计总耗时1.5 ms(位运算和内存对齐优势)​， 可修改不限制但是​预计总耗时12 ms
+ * 检查 buffer_size 是否为 2 的幂。
+ * 由于设计仅 <tt> RING_BUFFER_SIZE-1 </tt> 项目
+ * 可以包含在缓冲区中。
+ * buffer_size 必须是 2 的幂。
 */
-#define RING_BUFFER_IS_POWER_OF_TWO(buffer_size) ((buffer_size & (buffer_size - 1)) == 0)
+// 移除
+// #define RING_BUFFER_IS_POWER_OF_TWO（buffer_size） （（buffer_size & （buffer_size - 1）） == 0）
+
 
 /**
- * The type which is used to hold the size
- * and the indicies of the buffer.
+ * 用于保存大小的类型
+ * 和缓冲区的指示。
  */
 typedef size_t ring_buffer_size_t;
 
 /**
- * Used as a modulo operator
- * as <tt> a % b = (a & (b ? 1)) </tt>
- * where \c a is a positive index in the buffer and
- * \c b is the (power of two) size of the buffer.
+ * 用作模运算符
+ * 作为 <tt> a % b = （a & （b ？ 1）） </tt>
+ * 其中 \c a 是缓冲区中的正索引，
+ * \c b 是缓冲区的 （2 的幂） 大小。
  */
-#define RING_BUFFER_MASK(rb) (rb->buffer_mask)
+// 移除
+// #define RING_BUFFER_MASK(rb) (rb->buffer_mask)
 
 /**
- * Simplifies the use of <tt>struct ring_buffer_t</tt>.
+ * 简化了 <tt>struct ring_buffer_t</tt> 的使用。
  */
 typedef struct ring_buffer_t ring_buffer_t;
 
 /**
- * Structure which holds a ring buffer.
- * The buffer contains a buffer array
- * as well as metadata for the ring buffer.
+ * 保存环形缓冲区的结构。
+ * 缓冲区包含一个缓冲区数组
+ * 以及 Ring Buffer 的元数据。
  */
 struct ring_buffer_t {
-  /** Buffer memory. */
+  /** 缓冲内存。 */
   char *buffer;
-  /** Buffer mask. */
-  ring_buffer_size_t buffer_mask;
-  /** Index of tail. */
+  /** 缓冲区大小。 */
+  ring_buffer_size_t buf_size;
+  /** 尾巴索引。 */
   ring_buffer_size_t tail_index;
-  /** Index of head. */
+  /** 头部索引。 */
   ring_buffer_size_t head_index;
+  /** 计数掩码。 */
+  ring_buffer_size_t count;
 };
 
 /**
- * Initializes the ring buffer pointed to by <em>buffer</em>.
- * This function can also be used to empty/reset the buffer.
- * @param buffer The ring buffer to initialize.
- * @param buf The buffer allocated for the ringbuffer.
- * @param buf_size The size of the allocated ringbuffer.
+ * 初始化<em>缓冲区</em>指向的环形缓冲区。
+ * 此功能也可用于清空/重置缓冲区。
+ * @param buffer 要初始化的环形缓冲区。
+ * @param buf 为 ringbuffer 分配的缓冲区。
+ * @param buf_size 分配的 ringbuffer 的大小。
  */
 void ring_buffer_init(ring_buffer_t *buffer, char *buf, size_t buf_size);
 
 /**
- * Adds a byte to a ring buffer.
- * @param buffer The buffer in which the data should be placed.
- * @param data The byte to place.
+ * 向环形缓冲区添加一个字节。
+ * @param buffer （ 缓冲区） 应放置数据的缓冲区。
+ * @param data 要放置的字节。
  */
 void ring_buffer_queue(ring_buffer_t *buffer, char data);
 
 /**
- * Adds an array of bytes to a ring buffer.
- * @param buffer The buffer in which the data should be placed.
- * @param data A pointer to the array of bytes to place in the queue.
- * @param size The size of the array.
+ * 将字节数组添加到环形缓冲区。
+ * @param buffer （ 缓冲区） 应放置数据的缓冲区。
+ * @param data 指向要放置在队列中的字节数组的指针。
+ * @param size 数组的大小。
  */
 void ring_buffer_queue_arr(ring_buffer_t *buffer, const char *data, ring_buffer_size_t size);
 
 /**
- * Returns the oldest byte in a ring buffer.
- * @param buffer The buffer from which the data should be returned.
- * @param data A pointer to the location at which the data should be placed.
- * @return 1 if data was returned; 0 otherwise.
+ * 返回环形缓冲区中最早的字节。
+ * @param buffer 应从中返回数据的缓冲区。
+ * @param data 指向数据应放置位置的指针。
+ * 如果返回数据，则@return 1;否则为 0。
  */
 uint8_t ring_buffer_dequeue(ring_buffer_t *buffer, char *data);
 
 /**
- * Returns the <em>len</em> oldest bytes in a ring buffer.
- * @param buffer The buffer from which the data should be returned.
- * @param data A pointer to the array at which the data should be placed.
- * @param len The maximum number of bytes to return.
- * @return The number of bytes returned.
+ * 返回环形缓冲区中 <em>len</em> 最早的字节。
+ * @param buffer 应从中返回数据的缓冲区。
+ * @param data 指向应放置数据的数组的指针。
+ * @param len 要返回的最大字节数。
+ * @return 返回的字节数。
  */
 ring_buffer_size_t ring_buffer_dequeue_arr(ring_buffer_t *buffer, char *data, ring_buffer_size_t len);
 /**
- * Peeks a ring buffer, i.e. returns an element without removing it.
- * @param buffer The buffer from which the data should be returned.
- * @param data A pointer to the location at which the data should be placed.
- * @param index The index to peek.
- * @return 1 if data was returned; 0 otherwise.
+ * Peeks a ring buffer，即返回一个元素而不删除它。
+ * @param buffer 应从中返回数据的缓冲区。
+ * @param data 指向数据应放置位置的指针。
+ * @param index 要速览的索引。
+ * 如果返回数据，则@return 1;否则为 0。
  */
 uint8_t ring_buffer_peek(ring_buffer_t *buffer, char *data, ring_buffer_size_t index);
 
 
 /**
- * Returns whether a ring buffer is empty.
- * @param buffer The buffer for which it should be returned whether it is empty.
- * @return 1 if empty; 0 otherwise.
+ * 返回 ring buffer 是否为空。
+ * @param buffer 无论是否为空，都应该返回的缓冲区。
+ * @return 1 为空;否则为 0。
  */
-inline uint8_t ring_buffer_is_empty(ring_buffer_t *buffer) {
-  return (buffer->head_index == buffer->tail_index);
-}
+inline uint8_t ring_buffer_is_empty(ring_buffer_t *buffer);
 
 /**
- * Returns whether a ring buffer is full.
- * @param buffer The buffer for which it should be returned whether it is full.
- * @return 1 if full; 0 otherwise.
+ * 返回环形缓冲区是否已满。
+ * @param buffer 缓冲区 无论缓冲区是否已满，都应返回其缓冲区。
+ * @return 1 如果已满;否则为 0。
  */
-inline uint8_t ring_buffer_is_full(ring_buffer_t *buffer) {
-  return ((buffer->head_index - buffer->tail_index) & RING_BUFFER_MASK(buffer)) == RING_BUFFER_MASK(buffer);
-}
+inline uint8_t ring_buffer_is_full(ring_buffer_t *buffer);
 
 /**
- * Returns the number of items in a ring buffer.
- * @param buffer The buffer for which the number of items should be returned.
- * @return The number of items in the ring buffer.
+ * 返回环形缓冲区中的项数。
+ * @param buffer 应为其返回项目数的缓冲区。
+ * @return 环形缓冲区中的项数。
  */
-inline ring_buffer_size_t ring_buffer_num_items(ring_buffer_t *buffer) {
-  return ((buffer->head_index - buffer->tail_index) & RING_BUFFER_MASK(buffer));
-}
+inline ring_buffer_size_t ring_buffer_num_items(ring_buffer_t *buffer);
 
 #ifdef __cplusplus
 }