[feat] add linear r/w setup done api, for dma use

Author: Egahp

README.md

@@ -178,5 +178,29 @@ void thread_consumer(void* param)
      */
     chry_ringbuffer_drop(&rb, 1);
 
-    
+    void *pdata;
+    uint32_t size;
+
+    /**
+     * For dma start, get read memory address and max linear read size
+     */
+    pdata = chry_ringbuffer_linear_read_setup(&rb, &size);
+
+    /**
+     * For dma done, add read pointer
+     * Returns the length of the actual add
+     */
+    size = chry_ringbuffer_linear_read_done(&rb, 512);
+
+    /**
+     * For dma start, get write memory address and max linear write size
+     */
+    pdata = chry_ringbuffer_linear_write_setup(&rb, &size);
+
+    /**
+     * For dma done, add write pointer
+     * Returns the length of the actual add
+     */
+    size = chry_ringbuffer_linear_write_done(&rb, 512);
+
 ```

README_zh.md

@@ -172,5 +172,29 @@ void thread_consumer(void* param)
      */
     chry_ringbuffer_drop(&rb, 1);
 
-    
+    void *pdata;
+    uint32_t size;
+
+    /**
+     * 用于启动DMA，获取读取起始内存地址和最大线性可读取长度
+     */
+    pdata = chry_ringbuffer_linear_read_setup(&rb, &size);
+
+    /**
+     * 用于DMA完成，增加读指针
+     * 返回实际增加长度
+     */
+    size = chry_ringbuffer_linear_read_done(&rb, 512);
+
+    /**
+     * 用于启动DMA，获取写入起始内存地址和最大线性可写入长度
+     */
+    pdata = chry_ringbuffer_linear_write_setup(&rb, &size);
+
+    /**
+     * 用于DMA完成，增加写指针
+     * 返回实际增加长度
+     */
+    size = chry_ringbuffer_linear_write_done(&rb, 512);
+
 ```

chry_ringbuffer.c

@@ -377,4 +377,98 @@ uint32_t chry_ringbuffer_drop(chry_ringbuffer_t *rb, uint32_t size)
 
     rb->out += size;
     return size;
-}
+}
+
+/*****************************************************************************
+* @brief        linear write setup, get write pointer and max linear size.
+*               
+* @param[in]    rb          ringbuffer instance
+* @param[in]    size        pointer to store max linear size in byte
+* 
+* @retval void*             write memory pointer
+*****************************************************************************/
+void *chry_ringbuffer_linear_write_setup(chry_ringbuffer_t *rb, uint32_t *size)
+{
+    uint32_t unused;
+    uint32_t offset;
+    uint32_t remain;
+
+    unused = (rb->mask + 1) - (rb->in - rb->out);
+
+    offset = rb->in & rb->mask;
+
+    remain = rb->mask + 1 - offset;
+    remain = remain > unused ? unused : remain;
+
+    if (remain) {
+        *size = remain;
+        return ((uint8_t *)(rb->pool)) + offset;
+    } else {
+        *size = unused - remain;
+        return rb->pool;
+    }
+}
+
+/*****************************************************************************
+* @brief        linear read setup, get read pointer and max linear size.
+* 
+* @param[in]    rb          ringbuffer instance
+* @param[in]    size        pointer to store max linear size in byte
+* 
+* @retval void*             
+*****************************************************************************/
+void *chry_ringbuffer_linear_read_setup(chry_ringbuffer_t *rb, uint32_t *size)
+{
+    uint32_t used;
+    uint32_t offset;
+    uint32_t remain;
+
+    used = rb->in - rb->out;
+
+    offset = rb->out & rb->mask;
+
+    remain = rb->mask + 1 - offset;
+    remain = remain > used ? used : remain;
+
+    if (remain) {
+        *size = remain;
+        return ((uint8_t *)(rb->pool)) + offset;
+    } else {
+        *size = used - remain;
+        return rb->pool;
+    }
+}
+
+/*****************************************************************************
+* @brief        linear write done, add write pointer only
+* 
+* @param[in]    rb          ringbuffer instance
+* @param[in]    size        write size in byte
+* 
+* @retval uint32_t          actual write size in byte
+*****************************************************************************/
+uint32_t chry_ringbuffer_linear_write_done(chry_ringbuffer_t *rb, uint32_t size)
+{
+    uint32_t unused;
+
+    unused = (rb->mask + 1) - (rb->in - rb->out);
+    if (size > unused) {
+        size = unused;
+    }
+    rb->in += size;
+
+    return size;
+}
+
+/*****************************************************************************
+* @brief        linear read done, add read pointer only
+* 
+* @param[in]    rb          ringbuffer instance
+* @param[in]    size        read size in byte
+* 
+* @retval uint32_t          actual read size in byte
+*****************************************************************************/
+uint32_t chry_ringbuffer_linear_read_done(chry_ringbuffer_t *rb, uint32_t size)
+{
+    return chry_ringbuffer_drop(rb, size);
+}

chry_ringbuffer.h

@@ -44,8 +44,13 @@ extern uint32_t chry_ringbuffer_peek(chry_ringbuffer_t *rb, void *data, uint32_t
 extern uint32_t chry_ringbuffer_read(chry_ringbuffer_t *rb, void *data, uint32_t size);
 extern uint32_t chry_ringbuffer_drop(chry_ringbuffer_t *rb, uint32_t size);
 
+extern void *chry_ringbuffer_linear_write_setup(chry_ringbuffer_t *rb, uint32_t *size);
+extern void *chry_ringbuffer_linear_read_setup(chry_ringbuffer_t *rb, uint32_t *size);
+extern uint32_t chry_ringbuffer_linear_write_done(chry_ringbuffer_t *rb, uint32_t size);
+extern uint32_t chry_ringbuffer_linear_read_done(chry_ringbuffer_t *rb, uint32_t size);
+
 #ifdef __cplusplus
 }
 #endif
 
-#endif
+#endif