audio/asio: port unsynchronized fifo_buffer_t to retro_spsc_t

The ASIO callback thread (which is the audio driver's real-time
thread) called fifo_read(ad->ring, ...) at five sites in
asio_deinterleave_to_buffers without holding any lock.  The main
thread called fifo_write(ad->ring, src, to_write) in asio_write
also without holding any lock.  The only slock_* calls in the
file were on cond_lock for the scond_wait/scond_signal pair
around backpressure, which protects the condvar's internal state
but does not serialise fifo_buffer_t access -- fifo_buffer_t is
itself a plain ring buffer with no internal synchronisation, and
the audit's earlier characterisation of fifo_buffer_t as "MPMC-
safe with internal slock" was wrong.

Both threads concurrently mutated ad->ring->first (callback via
fifo_read) and ad->ring->end (main via fifo_write).  fifo_*
internally does an "if-then-set" on first/end inside a wraparound
branch, so a racing read can observe a torn value -- not just
loose ordering, an actually-corrupt half-updated cursor.  On x86
TSO this is masked at the hardware level most of the time, which
is presumably why the bug has been latent without major reports;
on weak-memory targets (Win-on-ARM ASIO, becoming a real thing
with Snapdragon X) the symptoms would be audio glitches at
minimum and corrupted samples on wraparound.

retro_spsc_t is the right tool for this exact pattern:
single-producer (main thread, asio_write) / single-consumer
(callback thread, asio_deinterleave_to_buffers) byte queue with
acquire/release ordering on the head and tail cursors.  Lock-
free, so no priority-inversion concern from the callback path
(taking a mutex from a real-time audio callback is a textbook
anti-pattern in pro-audio code, which rules out the alternative
"add a slock around the FIFO" fix).  This also makes asio.c the
first production caller of retro_spsc_t since b894479 introduced
the primitive, validating the API against a real workload.

Mechanical changes
------------------

  - #include <queues/fifo_queue.h> -> <retro_spsc.h>.
  - fifo_buffer_t *ring -> retro_spsc_t ring (embedded by value)
    plus a sibling bool ring_initialized so cleanup paths can tell
    "init succeeded" from "never initialised".  retro_spsc_t
    doesn't carry that bit internally because most callers know
    their own lifecycle; asio.c's free path runs from multiple
    error sites so the flag is the simplest way.
  - fifo_new/fifo_free -> retro_spsc_init/retro_spsc_free, with
    !ring NULL-checks replaced by !ring_initialized.
  - FIFO_READ_AVAIL / FIFO_WRITE_AVAIL -> retro_spsc_read_avail /
    retro_spsc_write_avail.
  - fifo_read / fifo_write -> retro_spsc_read / retro_spsc_write.
    The writer at line 1306 now uses retro_spsc_write's actual
    return value rather than assuming it equals to_write; the cap
    via retro_spsc_write_avail makes them equal in practice but
    using the return value is defensive against contract changes.
  - fifo_clear -> retro_spsc_clear (new API, see below) at the
    persistent-instance reuse path.

ra_asio_t is calloc'd, so the embedded retro_spsc_t starts as a
zero-bit pattern; retro_spsc_init then does the proper init via
retro_atomic_size_init before any cross-thread access begins.
This avoids the C++11 [atomics.types.generic] technical UB
concern about uninitialised _Atomic / std::atomic members
(carried over from the gfx_thumbnail port's analysis).

retro_spsc_clear: new API
-------------------------

retro_spsc_clear(retro_spsc_t *q) resets head and tail to zero
without reallocating the buffer.  It's documented as safe only
when both producer and consumer are quiesced -- the same lifetime
constraint as retro_spsc_init / retro_spsc_free.  Implementation
is two retro_atomic_size_init calls; the init form is necessary
because plain assignment to a retro_atomic_size_t is illegal
under the C11 stdatomic backend.

Without this addition, the alternatives for "drop stale data on
session restart" were:
  (a) repeated retro_spsc_read into a scratch buffer until empty
      (wasteful memcpys, ugly);
  (b) retro_spsc_free + retro_spsc_init (reallocates the heap
      buffer, churn).

(c) clear is one line at the call site and atomic with respect
to the calling thread.  The quiescence requirement is documented
in the header alongside the function.

asio.c had two pre-port fifo_clear sites:

  1. ra_asio_init_via_persistent (~line 1024): runs before
     g_asio = ad, so the ASIO callback isn't yet seeing this
     instance.  Single-threaded; retro_spsc_clear is safe here.
     This site is converted directly.

  2. ra_asio_free / parking path (~line 1380 pre-port): ran
     AFTER ASIO_CALL_STOP and AFTER g_asio = NULL.  The intent
     was "drop stale audio before parking", but ASIO_CALL_STOP is
     not a synchronous join -- ASIO4ALL specifically does not
     terminate its audio thread before returning -- so the old
     fifo_clear at this site could race with a stray callback's
     fifo_read.  This was a pre-existing latent bug.

     Resolution: drop the clear at the parking site entirely.
     The next ra_asio_init_via_persistent will re-clear after the
     callback is provably idle (g_asio == NULL means the callback
     short-circuits at line 852's null check, so it won't touch
     the ring).  Documented with a comment at the parking site.

Test coverage
-------------

retro_spsc_clear gets unit-test coverage in the existing sample at
libretro-common/samples/queues/retro_spsc_test/: write 50 bytes,
verify read_avail == 50, retro_spsc_clear, verify read_avail == 0
and write_avail == capacity, then verify the queue is reusable
after clear (write 16, read 16, content matches).  Runs clean
under SANITIZER=thread with halt_on_error=1.

The SPSC stress test (1M-token producer/consumer race through a
4 KB buffer) continues to pass under TSan with no regression
from the new function.

Verified locally
----------------

  - retro_spsc.c compiles clean as C (gcc, clang) and C++11
    (-xc++), under Wall/Wextra/Wpedantic/Werror.
  - Forced backends: C11 stdatomic, GCC __sync_*, volatile
    fallback all build clean.
  - The ring-using portions of asio.c, extracted into a smoke
    harness mirroring the real calloc allocation pattern,
    compile and run clean under gcc -O2, g++ -std=c++11 -xc++,
    and clang.
  - Sample stress test passes 10M tokens, 0 mismatches.
  - Sample TSan run (halt_on_error=1): exit 0.

Verified on Windows
-------------------

  - End-to-end Windows ASIO build with this patch applied.
    Audio plays correctly through the ASIO driver, no
    regressions observed in normal operation.

Performance
-----------

The motivating reason for the port is correctness (the cross-
thread race) and bounded worst-case latency (the audio-code
property), not throughput.  But for the record, a head-to-head
microbenchmark of the same access pattern under both designs
("fifo_buffer_t guarded by slock_t" vs "retro_spsc_t lock-free")
shows:

  Single-threaded steady-state, 8 KB chunks (asio.c realistic
  payload), x86_64:
    fifo+slock:  338 ns/iter (write+read pair)
    retro_spsc:  283 ns/iter (write+read pair)
    Both dominated by memcpy cost (~94 ns/copy for 8 KB).
    Per-op overhead net of memcpy:  ~150 ns vs ~96 ns.

  Single-threaded steady-state, 16 B chunks (atomic-cost-
  dominated), x86_64:
    fifo+slock:  44 ns/iter
    retro_spsc:  16 ns/iter
    Ratio:  2.7x faster.

  AArch64 (qemu-user, ratios only — absolute numbers distorted
  by emulation overhead):
    fifo+slock:  1151 ns/iter (8 KB), 637 ns/iter (16 B)
    retro_spsc:   891 ns/iter (8 KB), 410 ns/iter (16 B)

At realistic ASIO operation rates (a few hundred queue ops/sec
across both producer and consumer), the per-op savings amount
to ~20 microseconds per second of CPU on x86 -- ~0.002% of one
core.  The throughput win is real but practically negligible at
audio rates.

What is meaningful is the bounded-latency property: under lock
contention, the locked design's worst case is unbounded (the
non-holding thread blocks in the kernel mutex; if the holder is
preempted, the wait is unbounded).  Under the same contention,
the lock-free SPSC's worst case is one acquire-load.  This is
the textbook reason pro-audio guidance (Apple CoreAudio docs,
Steinberg ASIO docs) discourages mutexes in real-time audio
threads, and it's the qualitatively important difference here.

Author: LibretroAdmin

audio/drivers/asio.c

@@ -55,7 +55,7 @@
 #include <compat/strl.h>
 #include <string/stdstring.h>
 #include <lists/string_list.h>
-#include <queues/fifo_queue.h>
+#include <retro_spsc.h>
 
 #ifdef HAVE_THREADS
 #include <rthreads/rthreads.h>
@@ -644,7 +644,26 @@ static void *asio_load_driver(const CLSID *clsid)
 typedef struct ra_asio
 {
    void              *iasio;        /* COM interface pointer */
-   fifo_buffer_t     *ring;         /* Ring buffer between write() and callback */
+   /* Lock-free SPSC ring buffer between asio_write (producer, main
+    * thread) and asio_cb_buffer_switch (consumer, ASIO callback
+    * thread).  Pre-port this used fifo_buffer_t with no surrounding
+    * lock, which was a real cross-thread race on first/end -- see
+    * commit message.  retro_spsc_t is the SPSC primitive designed
+    * for this exact pattern: lock-free (avoiding the priority-
+    * inversion concern of locking from a real-time audio callback),
+    * acquire/release ordering on the cursors, single-producer /
+    * single-consumer enforced by the type contract.
+    *
+    * Embedded by value (not via pointer) so the lifetime exactly
+    * tracks ra_asio_t.  Initialised with retro_spsc_init in
+    * ra_asio_init / ra_asio_init_via_persistent and freed with
+    * retro_spsc_free in the corresponding teardown paths.  The
+    * `ring_initialized` flag below distinguishes "never-initialised"
+    * from "init succeeded" so cleanup paths know whether to call
+    * retro_spsc_free.  retro_spsc_t doesn't carry that bit
+    * internally because most callers know their own lifecycle. */
+   retro_spsc_t       ring;
+   bool               ring_initialized;
 #ifdef HAVE_THREADS
    scond_t           *cond;
    slock_t           *cond_lock;
@@ -712,7 +731,11 @@ static void asio_deinterleave_to_buffers(ra_asio_t *ad,
    long i;
    void *buf_l  = ad->buf_info[0].buffers[index];
    void *buf_r  = ad->buf_info[1].buffers[index];
-   size_t avail = FIFO_READ_AVAIL(ad->ring);
+   /* Acquire-load on the producer's head cursor.  Pairs with the
+    * release-store inside retro_spsc_write that asio_write
+    * issues on the main thread, so the bytes we're about to read
+    * out via retro_spsc_read are guaranteed visible. */
+   size_t avail = retro_spsc_read_avail(&ad->ring);
    long have    = (long)(avail / (2 * sizeof(float)));
 
    if (have > frames)
@@ -727,7 +750,7 @@ static void asio_deinterleave_to_buffers(ra_asio_t *ad,
          float tmp[2];
          for (i = 0; i < have; i++)
          {
-            fifo_read(ad->ring, tmp, sizeof(tmp));
+            retro_spsc_read(&ad->ring, tmp, sizeof(tmp));
             dl[i] = tmp[0];
             dr[i] = tmp[1];
          }
@@ -742,7 +765,7 @@ static void asio_deinterleave_to_buffers(ra_asio_t *ad,
          float tmp[2];
          for (i = 0; i < have; i++)
          {
-            fifo_read(ad->ring, tmp, sizeof(tmp));
+            retro_spsc_read(&ad->ring, tmp, sizeof(tmp));
             dl[i] = (double)tmp[0];
             dr[i] = (double)tmp[1];
          }
@@ -757,7 +780,7 @@ static void asio_deinterleave_to_buffers(ra_asio_t *ad,
          float tmp[2];
          for (i = 0; i < have; i++)
          {
-            fifo_read(ad->ring, tmp, sizeof(tmp));
+            retro_spsc_read(&ad->ring, tmp, sizeof(tmp));
             dl[i] = (int32_t)((double)tmp[0] * 2147483647.0);
             dr[i] = (int32_t)((double)tmp[1] * 2147483647.0);
          }
@@ -773,7 +796,7 @@ static void asio_deinterleave_to_buffers(ra_asio_t *ad,
          for (i = 0; i < have; i++)
          {
             int32_t l, r;
-            fifo_read(ad->ring, tmp, sizeof(tmp));
+            retro_spsc_read(&ad->ring, tmp, sizeof(tmp));
             l = (int32_t)(tmp[0] * 8388607.0f);
             r = (int32_t)(tmp[1] * 8388607.0f);
             l = l >  8388607 ?  8388607 : (l < -8388608 ? -8388608 : l);
@@ -797,7 +820,7 @@ static void asio_deinterleave_to_buffers(ra_asio_t *ad,
          for (i = 0; i < have; i++)
          {
             int32_t l, r;
-            fifo_read(ad->ring, tmp, sizeof(tmp));
+            retro_spsc_read(&ad->ring, tmp, sizeof(tmp));
             l = (int32_t)(tmp[0] * 32767.0f);
             r = (int32_t)(tmp[1] * 32767.0f);
             dl[i] = (int16_t)(l > 32767 ? 32767 : (l < -32768 ? -32768 : l));
@@ -826,7 +849,7 @@ static void asio_cb_buffer_switch(long index,
 {
    ra_asio_t *ad = g_asio;
 
-   if (!ad || !ad->ring || ad->is_paused || ad->shutdown)
+   if (!ad || !ad->ring_initialized || ad->is_paused || ad->shutdown)
    {
       if (ad && ad->buf_info[0].buffers[index])
       {
@@ -924,8 +947,11 @@ static void asio_atexit_cleanup(void)
       ASIO_CALL_RELEASE(ad->iasio);
    }
 
-   if (ad->ring)
-      fifo_free(ad->ring);
+   if (ad->ring_initialized)
+   {
+      retro_spsc_free(&ad->ring);
+      ad->ring_initialized = false;
+   }
 
 #ifdef HAVE_THREADS
    if (ad->cond_lock)
@@ -991,7 +1017,11 @@ static void *ra_asio_init(const char *device, unsigned rate,
       if (new_rate)
          *new_rate = ad->sample_rate;
 
-      fifo_clear(ad->ring);
+      /* Discard any stale audio left over from the previous
+       * session.  Safe here because the ASIO callback isn't
+       * running yet (g_asio is still NULL until the next line),
+       * so the SPSC is single-threaded at this point. */
+      retro_spsc_clear(&ad->ring);
 
       g_asio = ad;
       ad->running = true;
@@ -1158,14 +1188,18 @@ static void *ra_asio_init(const char *device, unsigned rate,
 
    /* Create ring buffer BEFORE ASIO buffers — the driver may issue
     * a bufferSwitch callback during ASIOCreateBuffers, and the
-    * callback needs the ring buffer to exist (even if empty). */
+    * callback needs the ring buffer to exist (even if empty).
+    * retro_spsc_init rounds capacity up to a power of 2; the
+    * over-allocation is small (factor of < 2) and irrelevant to
+    * the ASIO latency calculation, which uses ad->buffer_frames
+    * not the ring's actual byte capacity. */
    ad->ring_size = pref_sz * 2 * sizeof(float) * ASIO_RING_MULT;
-   ad->ring      = fifo_new(ad->ring_size);
-   if (!ad->ring)
+   if (!retro_spsc_init(&ad->ring, ad->ring_size))
    {
       RARCH_ERR("[ASIO] Failed to create ring buffer.\n");
       goto error;
    }
+   ad->ring_initialized = true;
 
 #ifdef HAVE_THREADS
    ad->cond      = scond_new();
@@ -1229,8 +1263,11 @@ static void *ra_asio_init(const char *device, unsigned rate,
          ASIO_CALL_DISPOSE_BUFFERS(ad->iasio);
       ASIO_CALL_RELEASE(ad->iasio);
    }
-   if (ad->ring)
-      fifo_free(ad->ring);
+   if (ad->ring_initialized)
+   {
+      retro_spsc_free(&ad->ring);
+      ad->ring_initialized = false;
+   }
 #ifdef HAVE_THREADS
    if (ad->cond_lock)
       slock_free(ad->cond_lock);
@@ -1259,17 +1296,22 @@ static ssize_t ra_asio_write(void *data, const void *buf, size_t len)
       if (ad->shutdown)
          return -1;
 
-      avail    = FIFO_WRITE_AVAIL(ad->ring);
+      avail    = retro_spsc_write_avail(&ad->ring);
       to_write = (len < avail) ? len : avail;
       /* Align to frame boundary (stereo float = 8 bytes) */
       to_write = (to_write / 8) * 8;
 
       if (to_write > 0)
       {
-         fifo_write(ad->ring, src, to_write);
-         src     += to_write;
-         len     -= to_write;
-         written += to_write;
+         /* retro_spsc_write returns bytes actually written.  We've
+          * already capped to_write by retro_spsc_write_avail above,
+          * so the return value will equal to_write -- but use it
+          * defensively in case the contract ever changes. */
+         size_t actually_written =
+            retro_spsc_write(&ad->ring, src, to_write);
+         src     += actually_written;
+         len     -= actually_written;
+         written += actually_written;
       }
       else if (!ad->nonblock)
       {
@@ -1346,9 +1388,14 @@ static void ra_asio_free(void *data)
    /* Detach from the callback — silence output while parked */
    g_asio = NULL;
 
-   /* Flush stale audio */
-   if (ad->ring)
-      fifo_clear(ad->ring);
+   /* No retro_spsc_clear here.  The pre-port fifo_clear at this
+    * site was racy with stray ASIO callbacks that may still be
+    * running after ASIO_CALL_STOP returns (some drivers, notably
+    * ASIO4ALL, don't synchronously join their audio thread).
+    * The restart path in ra_asio_init_via_persistent calls
+    * retro_spsc_clear anyway, so any stale data will be flushed
+    * before the next run -- after the callback is provably
+    * stopped (g_asio == NULL gates it). */
 
    /* Store for reuse */
    g_asio_persistent = ad;
@@ -1361,9 +1408,9 @@ static bool ra_asio_use_float(void *data) { return true; }
 static size_t ra_asio_write_avail(void *data)
 {
    ra_asio_t *ad = (ra_asio_t *)data;
-   if (!ad || !ad->ring)
+   if (!ad || !ad->ring_initialized)
       return 0;
-   return FIFO_WRITE_AVAIL(ad->ring);
+   return retro_spsc_write_avail(&ad->ring);
 }
 
 static size_t ra_asio_buffer_size(void *data)

libretro-common/include/retro_spsc.h

@@ -173,6 +173,26 @@ bool retro_spsc_init(retro_spsc_t *q, size_t min_capacity);
  */
 void retro_spsc_free(retro_spsc_t *q);
 
+/**
+ * retro_spsc_clear:
+ * @q : The queue.
+ *
+ * Resets head and tail to 0, discarding any unread data.  The
+ * underlying buffer is preserved (no reallocation).
+ *
+ * SAFETY: callable only when both the producer and consumer are
+ * quiesced -- e.g. before either has started, or after both have
+ * stopped.  Concurrent calls with a live producer or consumer are
+ * a data race.  This is the same lifetime constraint as
+ * retro_spsc_init / retro_spsc_free.
+ *
+ * Typical use is when a stream is stopped and restarted (e.g. an
+ * audio driver pausing and resuming, or switching device formats),
+ * and stale buffered data should be discarded before the new
+ * stream begins.
+ */
+void retro_spsc_clear(retro_spsc_t *q);
+
 /**
  * retro_spsc_write_avail:
  * @q : The queue.

libretro-common/queues/retro_spsc.c

@@ -75,6 +75,19 @@ void retro_spsc_free(retro_spsc_t *q)
    q->capacity = 0;
 }
 
+void retro_spsc_clear(retro_spsc_t *q)
+{
+   if (!q)
+      return;
+   /* Quiescence is the caller's responsibility (documented).
+    * Under that assumption, no other thread is touching head or
+    * tail, so plain init is correct here -- and necessary, because
+    * plain assignment to a retro_atomic_size_t is illegal under
+    * the C11 stdatomic backend. */
+   retro_atomic_size_init(&q->head, 0);
+   retro_atomic_size_init(&q->tail, 0);
+}
+
 size_t retro_spsc_write_avail(const retro_spsc_t *q)
 {
    /* Producer query.  We read our own head (which we wrote) and the
@@ -110,13 +123,12 @@ size_t retro_spsc_read_avail(const retro_spsc_t *q)
 
 size_t retro_spsc_write(retro_spsc_t *q, const void *data, size_t bytes)
 {
+   size_t mask, head_idx, first;
    const uint8_t *src = (const uint8_t*)data;
-   size_t avail, head, tail, mask, head_idx, first;
-
    /* read tail first to know how much room there is */
-   head = retro_atomic_load_acquire_size(&q->head);
-   tail = retro_atomic_load_acquire_size(&q->tail);
-   avail = q->capacity - (head - tail);
+   size_t head  = retro_atomic_load_acquire_size(&q->head);
+   size_t tail  = retro_atomic_load_acquire_size(&q->tail);
+   size_t avail = q->capacity - (head - tail);
    if (bytes > avail)
       bytes = avail;
    if (bytes == 0)
@@ -141,14 +153,13 @@ size_t retro_spsc_write(retro_spsc_t *q, const void *data, size_t bytes)
 
 size_t retro_spsc_read(retro_spsc_t *q, void *data, size_t bytes)
 {
+   size_t mask, tail_idx, first;
    uint8_t *dst = (uint8_t*)data;
-   size_t avail, head, tail, mask, tail_idx, first;
-
    /* acquire on head pairs with producer's release-store; this is
     * what makes the subsequent memcpys safe to read. */
-   head = retro_atomic_load_acquire_size(&q->head);
-   tail = retro_atomic_load_acquire_size(&q->tail);
-   avail = head - tail;
+   size_t head  = retro_atomic_load_acquire_size(&q->head);
+   size_t tail  = retro_atomic_load_acquire_size(&q->tail);
+   size_t avail = head - tail;
    if (bytes > avail)
       bytes = avail;
    if (bytes == 0)
@@ -171,14 +182,13 @@ size_t retro_spsc_read(retro_spsc_t *q, void *data, size_t bytes)
 
 size_t retro_spsc_peek(const retro_spsc_t *q, void *data, size_t bytes)
 {
+   size_t mask, tail_idx, first;
    uint8_t *dst = (uint8_t*)data;
-   size_t avail, head, tail, mask, tail_idx, first;
-
-   head = retro_atomic_load_acquire_size(
+   size_t head  = retro_atomic_load_acquire_size(
          (retro_atomic_size_t*)&q->head);
-   tail = retro_atomic_load_acquire_size(
+   size_t tail = retro_atomic_load_acquire_size(
          (retro_atomic_size_t*)&q->tail);
-   avail = head - tail;
+   size_t avail = head - tail;
    if (bytes > avail)
       bytes = avail;
    if (bytes == 0)
@@ -187,7 +197,7 @@ size_t retro_spsc_peek(const retro_spsc_t *q, void *data, size_t bytes)
    mask     = q->capacity - 1;
    tail_idx = tail & mask;
 
-   first = q->capacity - tail_idx;
+   first    = q->capacity - tail_idx;
    if (first > bytes)
       first = bytes;
 

libretro-common/samples/queues/retro_spsc_test/retro_spsc_test.c

@@ -222,6 +222,33 @@ static int run_property_checks(void)
       return 1;
    }
 
+   /* clear discards unread data without reallocating buffer */
+   retro_spsc_write(&q, buf, 50);
+   if (retro_spsc_read_avail(&q) != 50)
+   {
+      fprintf(stderr, "FAIL: pre-clear read_avail\n");
+      retro_spsc_free(&q);
+      return 1;
+   }
+   retro_spsc_clear(&q);
+   if (retro_spsc_read_avail(&q) != 0
+         || retro_spsc_write_avail(&q) != 128)
+   {
+      fprintf(stderr, "FAIL: clear did not reset cursors\n");
+      retro_spsc_free(&q);
+      return 1;
+   }
+   /* queue is reusable after clear */
+   retro_spsc_write(&q, buf, 16);
+   memset(readback, 0, sizeof(readback));
+   n = retro_spsc_read(&q, readback, 16);
+   if (n != 16 || memcmp(buf, readback, 16) != 0)
+   {
+      fprintf(stderr, "FAIL: post-clear read mismatch\n");
+      retro_spsc_free(&q);
+      return 1;
+   }
+
    retro_spsc_free(&q);
    printf("[pass] property checks\n");
    return 0;