Merge pull request #24 from lcapossio/startup-arm-force-idle

Add `force_idle()` to fix intermittent captures on startup-armed cores

Author: lcapossio

docs/05_ela_core.md

@@ -648,6 +648,28 @@ cfg = CaptureConfig(
 )
 ```
 
+> **Host-initiated captures on a startup-armed bitstream.** Because
+> `STARTUP_ARM=1` makes the core boot armed, it may already be armed — or even
+> triggered/done — before your host code runs. A bare `configure(cfg); arm()`
+> then races that power-up window and can read back a valid-but-unexpected
+> capture (clean data, wrong window). Call `Analyzer.force_idle()` between
+> `configure()` and `arm()` to reset the core and poll `STATUS` until it is
+> verifiably idle:
+>
+> ```python
+> a.configure(cfg)   # cfg.startup_arm defaults False -> clears STARTUP_ARM reg
+> a.force_idle()     # discard the boot window; start from known idle
+> a.arm()
+> result = a.capture()
+> ```
+>
+> `force_idle()` issues a soft reset and re-resets if the cleared `STARTUP_ARM`
+> register has not yet crossed the clock domain, so a single call is enough. It
+> is intentionally lossy — skip it when you *want* the from-boot capture (e.g.
+> the `STARTUP_ARM` validation tests, which deliberately use raw
+> `reset()`/`arm()`). For streaming, `capture_continuous(force_idle=True)`
+> establishes idle once before the first arm.
+
 What happens at runtime:
 
 1. The core arms (explicit `ARM`, segmented auto-rearm, or RESET with

docs/09_python_api.md

@@ -238,10 +238,13 @@ result = a.capture(timeout=10.0)
 print(f"got {len(result.samples)} samples, overflow={result.overflow}")
 ```
 
-### `capture_continuous(count=0, timeout_per=10.0)`
+### `capture_continuous(count=0, timeout_per=10.0, force_idle=False)`
 
 Generator that arms, waits, captures, re-arms, repeats.  `count=0`
-means "forever".
+means "forever".  Pass `force_idle=True` to establish a known-idle state
+once before the first arm (see `force_idle()` below) — this matters on a
+bitstream that boots with `STARTUP_ARM=1`, where the first iteration would
+otherwise inherit the power-up capture window.
 
 ```python
 for i, result in enumerate(a.capture_continuous(count=10)):
@@ -254,6 +257,7 @@ For `NUM_SEGMENTS > 1`:
 
 ```python
 a.configure(cfg)
+a.force_idle()      # on a STARTUP_ARM=1 bitstream; start from known idle
 a.arm()
 a.wait_all_segments_done(timeout=10.0)
 
@@ -286,6 +290,31 @@ abort an in-progress capture or recover from a stuck state.  If
 `CaptureConfig.startup_arm` is enabled, a later RESET leaves the
 core armed again instead of idle.
 
+### `force_idle(timeout=1.0, poll_interval=0.01, max_resets=3) -> None`
+
+Drives the core to a *verified* idle state: soft-resets, then polls
+`STATUS` until `armed`/`triggered`/`done` are all clear, re-resetting if a
+startup-armed core re-armed before the cleared `STARTUP_ARM` register
+crossed the sample-clock domain.  Raises `RuntimeError` if it cannot reach
+idle within `max_resets` resets.
+
+Use it between `configure()` and `arm()` on a bitstream built with the
+`STARTUP_ARM=1` RTL parameter: such a core boots already armed and may even
+be triggered/done before the host runs, so a bare `configure(); arm()` can
+read back a valid-but-unexpected window.  It is intentionally lossy (it
+discards any in-flight or boot capture) — skip it when you *want* the
+from-boot window.
+
+```python
+a.configure(cfg)
+a.force_idle()      # discard the boot window; start from known idle
+a.arm()
+result = a.capture()
+```
+
+See [chapter 5](05_ela_core.md#startup-arm-and-trigger-holdoff) for the
+full startup-arm discussion.
+
 ## `CaptureConfig` and friends
 
 ### `CaptureConfig`

docs/17_troubleshooting.md

@@ -183,6 +183,27 @@ trigger sample is at `samples[pretrigger]`.
 
 **Fix**: `result.samples[result.config.pretrigger]`.
 
+### Capture returns valid data but not the window you armed (intermittent, passes on rerun)
+
+**Cause**: the bitstream was built with the `STARTUP_ARM=1` RTL parameter,
+so the core boots already armed — it may be armed, or even triggered/done,
+before your host code runs.  A bare `configure(); arm()` then races that
+power-up window and reads back a clean-but-unexpected capture.
+Reprogramming or rerunning often "fixes" it because the timing shifts.
+
+**Fix**: call `force_idle()` between `configure()` and `arm()` to reset the
+core and poll `STATUS` until it is verifiably idle:
+
+```python
+a.configure(cfg)
+a.force_idle()
+a.arm()
+result = a.capture()
+```
+
+For streaming, use `capture_continuous(force_idle=True)`.  See
+[chapter 5](05_ela_core.md#startup-arm-and-trigger-holdoff).
+
 ## GUI
 
 ### `qt.qpa.plugin: Could not load the Qt platform plugin "xcb"`

examples/arty_a7/test_hw_integration.py

@@ -250,6 +250,8 @@ def test_first_ela_captures_150mhz_counter(self):
                 sample_clock_hz=ELA0_SAMPLE_CLOCK_HZ,
             )
             a.configure(cfg)
+            # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+            a.force_idle()
             a.arm()
             result = a.capture(timeout=5.0)
             samples = [s & 0xFF for s in result.samples]
@@ -289,6 +291,8 @@ def test_second_ela_captures_130mhz_xored_counter(self):
                 sample_clock_hz=ELA1_SAMPLE_CLOCK_HZ,
             )
             a.configure(cfg)
+            # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+            a.force_idle()
             a.arm()
             result = a.capture(timeout=5.0)
             samples = [s & 0xFF for s in result.samples]
@@ -404,6 +408,8 @@ def _capture(self, pretrig, posttrig, trig_val=0, trig_mask=0xFF, mode="value_ma
             depth=1024,
         )
         self.a.configure(cfg)
+        # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+        self.a.force_idle()
         self.a.arm()
         return self.a.capture(timeout=5.0)
 
@@ -429,6 +435,8 @@ def test_trigger_delay_shifts_window(self):
             trigger_delay=4,
         )
         self.a.configure(cfg)
+        # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+        self.a.force_idle()
         self.a.arm()
         result = self.a.capture(timeout=5.0)
         self.assertEqual(len(result.samples), 6)
@@ -454,6 +462,8 @@ def test_trigger_delay_zero_equivalence(self):
             trigger_delay=0,
         )
         self.a.configure(cfg)
+        # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+        self.a.force_idle()
         self.a.arm()
         result = self.a.capture(timeout=5.0)
         self.assertEqual(len(result.samples), 6)
@@ -702,6 +712,8 @@ def _capture_result(self):
             sample_width=8, depth=1024,
         )
         self.a.configure(cfg)
+        # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+        self.a.force_idle()
         self.a.arm()
         return self.a.capture(timeout=5.0)
 
@@ -771,6 +783,8 @@ def test_decim_zero_baseline(self):
             decimation=0,
         )
         self.a.configure(cfg)
+        # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+        self.a.force_idle()
         self.a.arm()
         result = self.a.capture(timeout=5.0)
         self.assertEqual(len(result.samples), 6)
@@ -791,6 +805,8 @@ def test_decim_3_stores_every_4th(self):
             decimation=3,
         )
         self.a.configure(cfg)
+        # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+        self.a.force_idle()
         self.a.arm()
         result = self.a.capture(timeout=5.0)
         self.assertEqual(len(result.samples), 8)
@@ -842,6 +858,8 @@ def test_timestamps_monotonic(self):
             trigger=self.TriggerConfig(mode="value_match", value=0x30, mask=0xFF),
         )
         self.a.configure(cfg)
+        # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+        self.a.force_idle()
         self.a.arm()
         result = self.a.capture(timeout=5.0)
         self.assertGreater(len(result.timestamps), 0, "No timestamps returned")
@@ -861,6 +879,8 @@ def test_timestamps_with_decimation(self):
             decimation=3,
         )
         self.a.configure(cfg)
+        # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+        self.a.force_idle()
         self.a.arm()
         result = self.a.capture(timeout=5.0)
         self.assertGreater(len(result.timestamps), 1)
@@ -912,6 +932,8 @@ def test_four_segments_captured(self):
             trigger=self.TriggerConfig(mode="value_match", value=0x00, mask=0xFF),
         )
         self.a.configure(cfg)
+        # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+        self.a.force_idle()
         self.a.arm()
         # Wait for all 4 segments to complete
         done = self.a.wait_all_segments_done(timeout=10.0)
@@ -934,6 +956,8 @@ def test_segment_data_independent(self):
             trigger=self.TriggerConfig(mode="value_match", value=0x00, mask=0xFF),
         )
         self.a.configure(cfg)
+        # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+        self.a.force_idle()
         self.a.arm()
         done = self.a.wait_all_segments_done(timeout=10.0)
         self.assertTrue(done)
@@ -982,6 +1006,8 @@ def test_ext_trigger_disabled_normal_capture(self):
             ext_trigger_mode=0,
         )
         self.a.configure(cfg)
+        # bitstream boots STARTUP_ARM=1 — establish known idle before arming
+        self.a.force_idle()
         self.a.arm()
         result = self.a.capture(timeout=5.0)
         self.assertEqual(len(result.samples), 6)

host/fcapz/analyzer.py

@@ -102,12 +102,21 @@ def expected_ela_version_reg() -> int:
 _ADDR_SQ_MASK = 0x0038
 _ADDR_DATA_BASE = 0x0100
 
+_STATUS_ARMED = 1 << 0
+_STATUS_TRIGGERED = 1 << 1
 _STATUS_DONE = 1 << 2
 _STATUS_OVERFLOW = 1 << 3
+# Capture FSM is "busy" (i.e. not idle) if any of armed/triggered/done is set.
+_STATUS_BUSY = _STATUS_ARMED | _STATUS_TRIGGERED | _STATUS_DONE
 
 _CTRL_ARM = 1 << 0
 _CTRL_RESET = 1 << 1
 
+# force_idle(): per-reset settle window. A re-armed core (startup-arm CDC race)
+# reveals itself within a couple of sample clocks of reset deassert, so a short
+# bounded wait suffices before spending another reset.
+_FORCE_IDLE_SETTLE_S = 0.05
+
 _TRIG_VALUE_MATCH = 1 << 0
 _TRIG_EDGE_DETECT = 1 << 1
 
@@ -197,7 +206,10 @@ class CaptureConfig:
     stor_qual_mode: int = 0    # 0=disabled; 1=store when match, 2=store when no match
     stor_qual_value: int = 0   # storage qualification comparison value
     stor_qual_mask: int = 0    # storage qualification mask
-    startup_arm: bool = False  # if True, reset leaves the core armed
+    startup_arm: bool = False  # runtime STARTUP_ARM register (0xD8): if True a
+                               # soft reset re-arms the core. Distinct from the
+                               # compile-time STARTUP_ARM RTL parameter, which
+                               # sets the power-up (boot-armed) value.
     trigger_holdoff: int = 0   # sample-clock cycles to ignore triggers after arm/re-arm
     trigger_delay: int = 0     # post-trigger delay in sample-clock cycles
                                # (0..65535) — shifts the committed trigger
@@ -329,6 +341,101 @@ def reset(self) -> None:
         self._select_instance()
         self.transport.write_reg(_ADDR_CTRL, _CTRL_RESET)
 
+    def force_idle(
+        self,
+        timeout: float = 1.0,
+        poll_interval: float = 0.01,
+        max_resets: int = 3,
+    ) -> None:
+        """Drive the core to a *verified* idle state before arming.
+
+        A bitstream built with ``STARTUP_ARM=1`` (e.g. the Arty example) comes
+        up already armed -- it may even be triggered/done -- before the host
+        issues a single command. Arming and capturing on top of that yields a
+        valid but *unexpected* window. ``force_idle`` issues a soft reset and
+        confirms the core actually settled to idle (armed=0, triggered=0,
+        done=0) so the next capture is deterministic.
+
+        This is a *soft* reset only: it clears the sample-domain capture FSM
+        (armed/triggered/done and the buffer pointers). It does **not** touch
+        configuration registers, so the canonical sequence is::
+
+            a.configure(cfg)   # cfg.startup_arm defaults False, clearing the
+                               # runtime STARTUP_ARM register (addr 0xD8)
+            a.force_idle()
+            a.arm()
+            result = a.capture()
+
+        Note the boot-armed behavior comes from the *compile-time* ``STARTUP_ARM``
+        RTL parameter, which seeds the auto-arm flag at configuration time and
+        cannot be changed from the host. :meth:`configure` instead clears the
+        *runtime* STARTUP_ARM register (addr 0xD8), which overrides that flag for
+        subsequent resets.
+
+        A startup-armed core re-loads its auto-arm flag from that register on
+        every soft reset, so a single reset can race the configuration
+        clock-domain crossing and come back still armed. ``force_idle`` polls
+        STATUS after the reset and, if the core re-armed, resets again -- by which
+        point the runtime STARTUP_ARM register cleared by :meth:`configure` has
+        crossed into the sample domain -- up to ``max_resets`` times.
+
+        Timing assumption: a STATUS read round-trips over JTAG far slower than
+        the core's reset-to-re-arm latency (a couple of sample clocks), so the
+        first post-reset STATUS read reliably observes the settled state. This
+        holds for any practical sample clock; only a sample clock so slow that a
+        full JTAG access spans fewer than ~2 sample cycles could read a
+        transient idle before a pending re-arm propagates.
+
+        Note this is intentionally lossy: it discards any in-flight or
+        startup-armed capture. Workflows that *want* the from-boot capture
+        (including tests that validate ``STARTUP_ARM`` behavior) should not call
+        it and should use :meth:`reset`/:meth:`arm` directly.
+
+        Args:
+            timeout: overall budget, in seconds, to reach idle across all resets.
+            poll_interval: STATUS poll spacing in seconds.
+            max_resets: maximum soft resets to attempt.
+
+        Raises:
+            RuntimeError: if the core is still busy after ``max_resets`` resets
+                (e.g. ``STARTUP_ARM`` is still enabled because :meth:`configure`
+                was not called first).
+        """
+        read_status = getattr(
+            self.transport, "read_reg_verified", self.transport.read_reg
+        )
+        deadline = time.monotonic() + timeout
+        last_status = -1
+        attempt = 0
+        for attempt in range(max(1, max_resets)):
+            with self.transport.transaction_lock():
+                self._select_instance()
+                self.transport.write_reg(_ADDR_CTRL, _CTRL_RESET)
+            # A re-armed core (startup-arm CDC race) will not clear on its own,
+            # so cap each attempt's wait and fall through to another reset.
+            attempt_deadline = time.monotonic() + _FORCE_IDLE_SETTLE_S
+            while True:
+                with self.transport.transaction_lock():
+                    self._select_instance()
+                    last_status = read_status(_ADDR_STATUS)
+                if (last_status & _STATUS_BUSY) == 0:
+                    return
+                now = time.monotonic()
+                if now >= attempt_deadline or now >= deadline:
+                    break
+                time.sleep(poll_interval)
+            if time.monotonic() >= deadline:
+                break
+        raise RuntimeError(
+            f"force_idle: core still busy after {attempt + 1} reset(s); "
+            f"last STATUS=0x{last_status & 0xFFFFFFFF:08x} "
+            f"(armed={bool(last_status & _STATUS_ARMED)}, "
+            f"triggered={bool(last_status & _STATUS_TRIGGERED)}, "
+            f"done={bool(last_status & _STATUS_DONE)}). "
+            f"If the core keeps re-arming, the runtime STARTUP_ARM register is "
+            f"still set -- call configure() (startup_arm=False) before force_idle()."
+        )
+
     @staticmethod
     def _validate_probes(probes: List[ProbeSpec], sample_width: int) -> None:
         occupied: set[int] = set()
@@ -758,6 +865,7 @@ def capture_continuous(
         self,
         count: int = 0,
         timeout_per: float = 10.0,
+        force_idle: bool = False,
     ):
         """Generator that yields successive ``CaptureResult`` objects.
 
@@ -766,9 +874,18 @@ def capture_continuous(
         iteration calls :meth:`arm`, then :meth:`capture` to wait for the next
         trigger and read back. Yields *count* results, or runs indefinitely if
         *count* is 0.
+
+        On a bitstream that boots with ``STARTUP_ARM=1`` the first iteration
+        would otherwise inherit the power-up capture window. Pass
+        ``force_idle=True`` to call :meth:`force_idle` once before the first
+        arm so the stream starts from a known-idle state. Defaults to ``False``
+        to preserve the original behavior (and leave the from-boot window
+        observable for callers that want it).
         """
         if self._config is None:
             raise RuntimeError("call configure() before capture_continuous()")
+        if force_idle:
+            self.force_idle()
         yielded = 0
         while count == 0 or yielded < count:
             self.arm()