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 461b1b897a2a955c21cc087bd6edf0ffc51e7d37
Author: Bowen Wang <[email protected]>
AuthorDate: Fri Jul 3 16:01:58 2026 +0800

    include/ring: add ring_mpmc_init/ring_mpsc_init/ring_spmc_init function
    
    User pass *init to judge whether this init is the first init
    of the ring to avoid race condition when user want to
    initialize their own data struct.
    
    Signed-off-by: Bowen Wang <[email protected]>
---
 include/nuttx/ring.h | 51 ++++++++++++++++++---------------------------------
 1 file changed, 18 insertions(+), 33 deletions(-)

diff --git a/include/nuttx/ring.h b/include/nuttx/ring.h
index 12835cc011e..a8ac80bab2d 100644
--- a/include/nuttx/ring.h
+++ b/include/nuttx/ring.h
@@ -38,8 +38,10 @@
  *     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);
+ *   Multi-core safe init (SMP, uses atomic CAS).
+ *     ring_mpmc_init(&g_ring, 64);
+ *     ring_mpsc_init(&g_ring, 64);
+ *     ring_spmc_init(&g_ring, 64);
  *
  *   Single-side init (AMP/SPSC, no atomic needed):
  *     ring_spsc_init(&g_ring, 64);
@@ -187,7 +189,7 @@
 /* Magic values for warm-restart detection.
  *
  * When a ring resides in memory that survives reboot (e.g. shared
- * SRAM), ring_init() uses an atomic magic field to decide whether
+ * SRAM), ring_mpmc_init() uses an atomic magic field to decide whether
  * to perform a fresh initialization or recover the previous state.
  *
  * Three-state protocol (multi-core safe):
@@ -217,11 +219,11 @@
   }
 
 /* RING_DECLARE - declare a ring variable (uninitialized).
- * Must call ring_init() or RING_INIT() before use.
+ * Must call ring_mpmc_init() or RING_INIT() before use.
  *
  * Usage:
  *   RING_DECLARE(g_my_ring, uint32_t, 64);
- *   ring_init(g_my_ring, 64);
+ *   ring_mpmc_init(g_my_ring, 64);
  *   or
  *   RING_DECLARE(g_my_ring, uint32_t, 64) = RING_INIT(64);
  *
@@ -275,26 +277,6 @@
 
 #define ring_reset(r)       ring_reset_indices(RING_BASE(r))
 
-/* ring_init - runtime initialization with warm-restart recovery.
- *
- * If the ring resides in memory that survives reboot (shared SRAM,
- * battery-backed RAM), ring_init detects prior initialization via
- * an atomic magic field and attempts to recover the previous state
- * instead of zeroing everything.
- *
- * Multi-core safe: concurrent ring_init calls from different cores
- * are serialized via CAS on the magic field. Cores that lose the
- * race spin-wait until the winner finishes, so no core can use the
- * ring before initialization is complete.
- *
- * Protocol:
- *   magic == 0 / garbage  -> fresh init (zero all indices)
- *   magic == RING_MAGIC_INIT  -> another core is initializing; spin
- *   magic == RING_MAGIC_READY -> warm restart; validate & recover
- */
-
-#define ring_init(buf, buflen)   ring_init_magic(buf, buflen)
-
 /* ring_data - return pointer to the embedded data buffer that immediately
  * follows the ring_s header in memory.
  */
@@ -311,7 +293,7 @@
 
 /* ring_spsc_init - lightweight initialization for SPSC mode.
  *
- * Unlike ring_init (which uses atomic CAS for multi-core safe
+ * Unlike ring_mpmc_init (which uses atomic CAS for multi-core safe
  * concurrent initialization), ring_spsc_init uses only volatile
  * writes. It can be called by either the producer or consumer
  * side, but NOT concurrently from both — the caller must ensure
@@ -320,7 +302,7 @@
  *
  * Use ring_spsc_init for AMP/SHM scenarios where atomic
  * instructions are unavailable on shared memory.
- * Use ring_init for SMP/BMP scenarios where multiple cores may
+ * Use ring_mpmc_init for SMP/BMP scenarios where multiple cores may
  * race to initialize the same ring.
  */
 
@@ -344,6 +326,9 @@
     }                                                    \
   while (0)
 
+#define ring_mpsc_init(r, cap)  ring_mpmc_init(r, cap)
+#define ring_spmc_init(r, cap)  ring_mpmc_init(r, cap)
+
 #define ring_is_ready(r) \
   (RING_FIELD(&RING_BASE(r)->magic) == RING_MAGIC_READY)
 
@@ -601,8 +586,7 @@ static inline_function uint32_t ring_idx(FAR struct ring_s 
*r, uint32_t idx)
  *   before the reset (i.e. the number of elements discarded by the reset
  *   operation).  Called by the ring_reset() macro after RING_BASE()
  *   conversion, and may also be invoked directly when the caller already
- *   holds a FAR struct ring_s * (e.g. from inside other inline helpers
- *   such as ring_init_magic).
+ *   holds a FAR struct ring_s *.
  *
  *   Callers may either use the return value (e.g. to bump a "dropped"
  *   counter) or discard it.  Safe to call on a freshly-zeroed ring whose
@@ -630,11 +614,12 @@ static inline_function uint32_t ring_reset_indices(FAR 
struct ring_s *r)
 }
 
 /****************************************************************************
- * Name: ring_init_magic
+ * Name: ring_mpmc_init
  *
  * Description:
  *   Runtime initialization with warm-restart recovery and multi-core
- *   safety.  Called by the ring_init() macro after capacity is set.
+ *   safety.  This is the unified init entry point; the ring_mpmc_init /
+ *   ring_mpsc_init / ring_spmc_init macros are thin wrappers around it.
  *
  *   Three outcomes based on the magic field:
  *     1. Uninitialized (magic != READY and != INIT):
@@ -649,7 +634,7 @@ static inline_function uint32_t ring_reset_indices(FAR 
struct ring_s *r)
  ****************************************************************************/
 
 static inline_function FAR struct ring_s *
-ring_init_magic(FAR void *buf, uint32_t buflen)
+ring_mpmc_init(FAR void *buf, uint32_t buflen)
 {
   FAR struct ring_s *r = (FAR struct ring_s *)buf;
   irqstate_t flags;
@@ -759,7 +744,7 @@ static inline_function FAR struct ring_s 
*ring_alloc(uint32_t cap,
       return NULL;
     }
 
-  ring_init(r, cap);
+  ring_spsc_init(r, cap);
   return r;
 }
 

Reply via email to