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 c225436100079b9c21fadd88f4ab6520a72c2101
Author: Bowen Wang <[email protected]>
AuthorDate: Wed Apr 22 23:26:47 2026 +0800

    include/ring: add atomic magic for warm-restart recovery
    
    Add an atomic_t magic field to ring_s for detecting whether a ring
    has been previously initialized.  This supports rings placed in
    memory that survives reboot (shared SRAM, battery-backed RAM).
    
    ring_init() now uses a three-state CAS protocol:
      - Uninitialized (magic != READY/INIT): fresh init, zero indices
      - RING_MAGIC_READY: warm restart, validate and recover indices
      - RING_MAGIC_INIT: another core is initializing, spin-wait
    
    Multi-core safe: concurrent ring_init() calls are serialized via
    CAS on the magic field.  Loser cores spin until the winner sets
    RING_MAGIC_READY, ensuring no core uses the ring before init
    completes.
    
    Signed-off-by: Bowen Wang <[email protected]>
---
 include/nuttx/ring.h | 153 +++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 141 insertions(+), 12 deletions(-)

diff --git a/include/nuttx/ring.h b/include/nuttx/ring.h
index 632eb475c0f..fec9c7c5453 100644
--- a/include/nuttx/ring.h
+++ b/include/nuttx/ring.h
@@ -38,6 +38,7 @@
 #include <nuttx/config.h>
 #include <nuttx/compiler.h>
 #include <nuttx/atomic.h>
+#include <nuttx/irq.h>
 #include <nuttx/lib/lib.h>
 
 #include <assert.h>
@@ -75,6 +76,21 @@
 #  define CACHELINE_SIZE 64
 #endif
 
+/* 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
+ * to perform a fresh initialization or recover the previous state.
+ *
+ * Three-state protocol (multi-core safe):
+ *   0                -> uninitialized (or garbage != READY/INIT)
+ *   RING_MAGIC_INIT  -> one core is initializing; others spin-wait
+ *   RING_MAGIC_READY -> init complete; ring is usable
+ */
+
+#define RING_MAGIC_INIT   ((int32_t)0x52494e49)   /* "RINI" */
+#define RING_MAGIC_READY  ((int32_t)0x52494e47)   /* "RING" */
+
 /* RING_INIT - static initialize a ring
  *
  * cap   - capacity (must be power-of-2)
@@ -85,7 +101,8 @@
 
 #define RING_INIT(cap)                                   \
   {                                                      \
-    .base.capacity  = cap,                               \
+    .base.magic    = RING_MAGIC_READY,                   \
+    .base.capacity = cap,                                \
   }
 
 /* RING_DECLARE - declare a ring variable (uninitialized).
@@ -142,13 +159,25 @@
     }                                                    \
   while (0)
 
-#define ring_init(r, cap)                                \
-  do                                                     \
-    {                                                    \
-      RING_BASE(r)->capacity = (cap);                    \
-      ring_reset(r);                                     \
-    }                                                    \
-  while (0)
+/* 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(r, cap)   ring_init_magic(RING_BASE(r), cap)
 
 #define ring_count(r)                                    \
   ((RTS_IDX(atomic_read(&RING_BASE(r)->prod_tail)) -     \
@@ -247,21 +276,27 @@
 
 struct aligned_data(CACHELINE_SIZE) ring_s
 {
+  /* Read-only metadata - cache-line aligned */
+
+  atomic_t     magic;             /* Warm-restart detection */
+  uint32_t     capacity;          /* Power-of-2, max 16777215 */
+  uint8_t      pad0[CACHELINE_SIZE - sizeof(atomic_t) -
+                    sizeof(uint32_t) - sizeof(size_t)];
+
   /* Producer side - cache-line aligned */
 
   atomic_t     prod_head;         /* SP: unused; MP: RTS CAS */
   atomic_t     prod_tail;         /* SP: store_release; MP: RTS CAS */
-  uint8_t      pad0[CACHELINE_SIZE - sizeof(atomic_t) * 2];
+  uint8_t      pad1[CACHELINE_SIZE - sizeof(atomic_t) * 2];
 
   /* Consumer side - cache-line aligned */
 
   atomic_t     cons_head;         /* SC: unused; MC: RTS CAS */
   atomic_t     cons_tail;         /* SC: store_release; MC: RTS CAS */
-  uint8_t      pad1[CACHELINE_SIZE - sizeof(atomic_t) * 2];
+  uint8_t      pad2[CACHELINE_SIZE - sizeof(atomic_t) * 2];
 
-  /* Read-only metadata - cache-line aligned */
+  /* Flexible array for embedded buffer */
 
-  uint32_t     capacity;          /* Power-of-2, max 16777215 */
   char         ring[];            /* Flexible array for embedded buffer */
 };
 
@@ -279,6 +314,100 @@ struct ring_buf_s
  * Inline Functions
  ****************************************************************************/
 
+/****************************************************************************
+ * Name: ring_init_magic
+ *
+ * Description:
+ *   Runtime initialization with warm-restart recovery and multi-core
+ *   safety.  Called by the ring_init() macro after capacity is set.
+ *
+ *   Three outcomes based on the magic field:
+ *     1. Uninitialized (magic != READY and != INIT):
+ *        Winner CAS to INIT, zeroes indices, sets READY.
+ *        Losers spin until READY.
+ *     2. Already READY (warm restart):
+ *        Winner CAS to INIT, validates/recovers indices, sets READY.
+ *        Losers spin until READY.
+ *     3. INIT in progress:
+ *        Another core is initializing; spin until READY.
+ *
+ ****************************************************************************/
+
+static inline_function void ring_init_magic(FAR struct ring_s *r,
+                                            uint32_t cap)
+{
+  irqstate_t flags;
+  int32_t old_magic;
+
+  flags = irq_save();
+
+  do
+    {
+      old_magic = atomic_read(&r->magic);
+
+      if (old_magic == RING_MAGIC_INIT)
+        {
+          irq_restore(flags);
+
+          /* Another core is initializing - spin until READY */
+
+          while (atomic_read_acquire(&r->magic) != RING_MAGIC_READY);
+
+          return;
+        }
+    }
+  while (!atomic_cmpxchg(&r->magic, &old_magic, RING_MAGIC_INIT));
+
+  r->capacity = cap;
+
+  if (old_magic == RING_MAGIC_READY)
+    {
+      /* Warm restart: validate indices.
+       *
+       * Invariant: count = (prod_idx - cons_idx) must be in
+       * [0, capacity].  If violated, the indices are corrupt
+       * and we fall back to a fresh reset.
+       */
+
+      uint32_t prod_index = RTS_IDX(atomic_read(&r->prod_tail));
+      uint32_t cons_index = RTS_IDX(atomic_read(&r->cons_tail));
+      uint32_t count = (prod_index - cons_index) & RING_IDX_MASK;
+
+      if (count > r->capacity)
+        {
+          ring_reset(r);
+        }
+      else
+        {
+          /* Indices are valid - rebuild with cnt=0.
+           *
+           * A reboot mid-enqueue/dequeue can leave head.cnt != tail.cnt,
+           * which deadlocks the RTS commit (tail can never catch head).
+           * Reset cnt to 0 on all four atomics, keeping only the idx.
+           */
+
+          uint32_t prod_tail = RTS_PACK(0, prod_index);
+          uint32_t cons_tail = RTS_PACK(0, cons_index);
+
+          atomic_set(&r->prod_tail, prod_tail);
+          atomic_set(&r->prod_head, prod_tail);
+          atomic_set(&r->cons_tail, cons_tail);
+          atomic_set(&r->cons_head, cons_tail);
+        }
+    }
+  else
+    {
+      /* First-time init: zero everything */
+
+      ring_reset(r);
+    }
+
+  /* Publish: all stores above are visible before magic becomes READY */
+
+  atomic_set_release(&r->magic, RING_MAGIC_READY);
+  irq_restore(flags);
+}
+
 /****************************************************************************
  * Name: ring_alloc
  *

Reply via email to