fix(BBShiftPanel): prime the SMEM ring before starting a PWM frame

6543a19 moved the self-PWM panel types onto the shared-memory ring along
with the shift panels.  The ring delivers every byte - the produced and
consumed counters stay exact and aligned to the PRU's 48 byte load, which
is what that commit verified - but it delivers them late.  Measured on
FM6363C hardware, the PRU entered RINGWAIT about seven times per frame for
40-50us each.

That is harmless for a shift panel, where the same PRU drives both the data
and the row address.  A self-PWM panel is different: it refreshes from its
own engine while its row scan free runs, so a gap in the shift out lets the
scan walk away from the data.  Roughly 300us of gaps per frame against a
~13.8us row period is more than a full pass of drift, which is why the
image slid vertically by a different amount every frame while every
byte-level check came back clean.

The ring was empty at the start of every frame (produced == consumed there),
so the dominant term was the pump's wakeup latency: it polled the frame
sequence on a 500us sleep, and the DATA command went out before any bytes
had been written.  So wake the pump from PrepDataPWM rather than having it
poll, hold the DATA command until the pump reports the ring full, and back
off in 20us steps instead of 150us once it is running.

The stall count is unchanged afterwards but every RINGWAIT entry now
resolves on the first reload of the producer counter, so the wait drops
from ~300us per frame to nothing measurable.  Checked on 8 and 16 output
capes driving an 80x40 1/10 scan panel.  The shift path is untouched and
was re-checked with 64x32 1/16 scan panels on a 16 output cape.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dkulp

src/non-gpl/BBShiftPanel/BBShiftPanel.cpp

@@ -992,22 +992,40 @@ void BBShiftPanelManager::runPumpThread() {
         // command so the byte flow stays in step with the commands
         while (m_pumpRunning) {
             if (m_pumpedSeq == m_pumpSeq.load(std::memory_order_acquire)) {
-                struct timespec ts = { 0, 500000 };
-                nanosleep(&ts, nullptr);
+                // PrepDataPWM wakes this the moment a frame is published; the
+                // timeout is only a backstop so shutdown cannot wedge here.
+                // Polling on a 500us sleep used to leave the PRU shifting
+                // against an empty ring for most of that wakeup latency.
+                std::unique_lock<std::mutex> lk(m_pumpMutex);
+                m_pumpCV.wait_for(lk, std::chrono::microseconds(200), [this] {
+                    return !m_pumpRunning || m_pumpSeq.load(std::memory_order_acquire) != m_pumpedSeq;
+                });
                 continue;
             }
             ++m_pumpedSeq;
             uint8_t* src = m_frontBuffer.load(std::memory_order_acquire);
             uint32_t srcOff = 0;
+            bool primed = false;
             while (srcOff < m_frameBytes && m_pumpRunning) {
                 uint32_t n = m_ring.write(src + srcOff, std::min(PUMP_BLOCK_SIZE, m_frameBytes - srcOff));
                 if (n == 0) {
-                    struct timespec ts = { 0, 150000 };
+                    // the ring holds as much as it can - the PRU may start.
+                    // Back off in small steps: at the drain rate a 150us sleep
+                    // was long enough to open a gap the panel could see.
+                    if (!primed) {
+                        primed = true;
+                        m_pumpPrimed.store(m_pumpedSeq, std::memory_order_release);
+                    }
+                    struct timespec ts = { 0, 20000 };
                     nanosleep(&ts, nullptr);
                     continue;
                 }
                 srcOff += n;
             }
+            // a frame smaller than the ring never fills it
+            if (!primed) {
+                m_pumpPrimed.store(m_pumpedSeq, std::memory_order_release);
+            }
         }
         return;
     }
@@ -1306,10 +1324,20 @@ void BBShiftPanelManager::PrepDataPWM() {
                                  : "memory");
     }
 
-    // hand the frame to the pump thread; the PRU is paced by the ring so the
-    // DATA command can be queued immediately
+    // hand the frame to the pump thread
     m_frontBuffer.store(buf, std::memory_order_release);
-    m_pumpSeq.fetch_add(1, std::memory_order_release);
+    uint32_t seq = m_pumpSeq.fetch_add(1, std::memory_order_release) + 1;
+    m_pumpCV.notify_one();
+    // Hold the DATA command until the ring is primed.  Starting the PRU
+    // against an empty ring left it in RINGWAIT for the pump's wakeup
+    // latency, and an FM6363C reads that gap as its row scan running away
+    // from the data.  Filling the ring takes ~65us; the loop bound is only a
+    // backstop so a stopped pump cannot hang the output thread.
+    for (int i = 0; i < 4000 && m_pumpRunning && bgThreadsRunning &&
+                    m_pumpPrimed.load(std::memory_order_acquire) != seq;
+         ++i) {
+        std::this_thread::yield();
+    }
 
     pruData->numBlocks = rowLen / 16;
     pruData->numRows = numRows;

src/non-gpl/BBShiftPanel/BBShiftPanel.h

@@ -254,6 +254,14 @@ class BBShiftPanelManager {
     // sequence bump so the byte flow stays in step with the commands
     std::atomic<uint32_t> m_pumpSeq{ 0 };
     uint32_t m_pumpedSeq = 0;
+    // A self-PWM panel refreshes from its own engine while its row scan free
+    // runs, so a gap in the shift out shows up as the image drifting
+    // vertically rather than as a glitch.  The frame is therefore not handed
+    // to the PRU until the pump has the ring as full as it will go, and the
+    // pump is woken directly rather than found by polling.
+    std::mutex m_pumpMutex;
+    std::condition_variable m_pumpCV;
+    std::atomic<uint32_t> m_pumpPrimed{ 0 };
     uint32_t m_frameBytes = 0;
     BBBPruSMEMRing m_ring;
     bool m_heapBuffers = false;