This is an automated email from the ASF dual-hosted git repository.

xiaoxiang781216 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git

commit 6eb52fb5febc7fe38efb346fd83c55ccb7056dc9
Author: Bowen Wang <[email protected]>
AuthorDate: Fri May 15 22:49:10 2026 +0800

    include/ring: add usage guide comments
    
    Add comprehensive usage documentation at the top of ring.h
    covering declaration, initialization, mode selection (SPSC/MPSC/
    SPMC/MPMC), overwrite mode, zero-copy pattern, and query APIs.
    
    Signed-off-by: Bowen Wang <[email protected]>
---
 include/nuttx/ring.h | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/include/nuttx/ring.h b/include/nuttx/ring.h
index 0f2ae0eeefc..76a0c5248c5 100644
--- a/include/nuttx/ring.h
+++ b/include/nuttx/ring.h
@@ -26,6 +26,90 @@
  * algorithm packing {cnt:8, idx:24} into a single atomic_t for
  * multi-producer/multi-consumer coordination via single CAS,
  * eliminating tail-wait spin without disabling interrupts.
+ *
+ * Usage Guide:
+ *
+ * 1. Declaration and Initialization:
+ *
+ *   Static (compile-time):
+ *     RING_DEFINE(g_ring, uint32_t, 64);
+ *
+ *   Dynamic (runtime):
+ *     struct ring_s *r = ring_alloc(64, sizeof(uint32_t));
+ *     ring_free(r);
+ *
+ *   Multi-core safe init (SMP, uses atomic CAS):
+ *     ring_init(&g_ring, 64);
+ *
+ *   Single-side init (AMP/SPSC, no atomic needed):
+ *     ring_spsc_init(&g_ring, 64);
+ *     // Other side polls: while (!ring_is_ready(&g_ring));
+ *
+ * 2. Mode Selection:
+ *
+ *   SPSC - Single Producer, Single Consumer (volatile + barrier):
+ *     ring_spsc_enqueue(&g_ring, &val, 1);
+ *     ring_spsc_dequeue(&g_ring, &out, 1);
+ *
+ *   MPSC - Multiple Producers, Single Consumer:
+ *     ring_mpsc_enqueue(&g_ring, &val, 1);
+ *     ring_mpsc_dequeue(&g_ring, &out, 1);
+ *
+ *   SPMC - Single Producer, Multiple Consumers:
+ *     ring_spmc_enqueue(&g_ring, &val, 1);
+ *     ring_spmc_dequeue(&g_ring, &out, 1);
+ *
+ *   MPMC - Multiple Producers, Multiple Consumers:
+ *     ring_mpmc_enqueue(&g_ring, &val, 1);
+ *     ring_mpmc_dequeue(&g_ring, &out, 1);
+ *
+ * 3. Dequeue Skip (advance index without reading data):
+ *
+ *     ring_spsc_dequeue_skip(&g_ring, n);
+ *     ring_mpsc_dequeue_skip(&g_ring, n);
+ *     ring_spmc_dequeue_skip(&g_ring, n);
+ *     ring_mpmc_dequeue_skip(&g_ring, n);
+ *
+ * 4. Overwrite Mode (SPMC/MPMC only, discards oldest on full):
+ *
+ *     ring_spmc_enqueue_overwrite(&g_ring, &val, 1);
+ *     ring_mpmc_enqueue_overwrite(&g_ring, &val, 1);
+ *     // Consumer MUST use MC dequeue (ring_spmc/mpmc_dequeue)
+ *
+ * 5. Zero-copy enqueue/dequeue (start/finish pattern):
+ *
+ *     struct ring_buf_s buf;
+ *
+ *     // Enqueue (all modes: spsc/mpsc/spmc/mpmc):
+ *     ring_spsc_enqueue_start(&g_ring, count, elem_size, &buf);
+ *     memcpy(buf.ptr1, src, buf.len1 * elem_size);
+ *     if (buf.ptr2)
+ *       memcpy(buf.ptr2, src + buf.len1 * elem_size,
+ *              buf.len2 * elem_size);
+ *     ring_spsc_enqueue_finish(&g_ring, &buf);
+ *
+ *     // Dequeue (all modes):
+ *     ring_spsc_dequeue_start(&g_ring, count, elem_size, &buf);
+ *     // Read from buf.ptr1 (len1) and buf.ptr2 (len2)
+ *     ring_spsc_dequeue_finish(&g_ring, &buf);
+ *
+ * 6. Zero-copy overwrite enqueue (start/finish pattern):
+ *
+ *     struct ring_buf_s buf;
+ *     ring_spmc_enqueue_overwrite_start(&g_ring, count,
+ *                                       elem_size, &buf);
+ *     memcpy(buf.ptr1, src, buf.len1 * elem_size);
+ *     if (buf.ptr2)
+ *       memcpy(buf.ptr2, src + buf.len1 * elem_size,
+ *              buf.len2 * elem_size);
+ *     ring_spmc_enqueue_overwrite_finish(&g_ring, &buf);
+ *
+ * 7. Query:
+ *
+ *     ring_count(&g_ring);     // Elements currently in ring
+ *     ring_capacity(&g_ring);  // Max elements
+ *     ring_space(&g_ring);     // Free slots
+ *     ring_is_ready(&g_ring);  // true if initialized
  */
 
 #ifndef __INCLUDE_NUTTX_RING_H

Reply via email to