From 91b41e0cd5db47306ad5015951bb6aa758210a01 Mon Sep 17 00:00:00 2001
From: Egahp <2687434412@qq.com>
Date: Wed, 28 Jun 2023 20:03:56 +0800
Subject: [PATCH] [feat] add linear r/w setup done api, for dma use

---
 README.md         | 26 ++++++++++++-
 README_zh.md      | 26 ++++++++++++-
 chry_ringbuffer.c | 96 ++++++++++++++++++++++++++++++++++++++++++++++-
 chry_ringbuffer.h |  7 +++-
 4 files changed, 151 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 5e5e53f..df04502 100644
--- a/README.md
+++ b/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);
+
 ```
\ No newline at end of file
diff --git a/README_zh.md b/README_zh.md
index d576c12..16bda1e 100644
--- a/README_zh.md
+++ b/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);
+
 ```
\ No newline at end of file
diff --git a/chry_ringbuffer.c b/chry_ringbuffer.c
index 6a3342d..a5d06a0 100644
--- a/chry_ringbuffer.c
+++ b/chry_ringbuffer.c
@@ -377,4 +377,98 @@ uint32_t chry_ringbuffer_drop(chry_ringbuffer_t *rb, uint32_t size)
 
     rb->out += size;
     return size;
-}
\ No newline at end of file
+}
+
+/*****************************************************************************
+* @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);
+}
diff --git a/chry_ringbuffer.h b/chry_ringbuffer.h
index d6f0ba2..d40f74d 100644
--- a/chry_ringbuffer.h
+++ b/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
\ No newline at end of file
+#endif