rp2pio: background_write(loop=) delivers zero/partial data above ~150 MHz system clock (Metro RP2350)

[TheKitty]

CircuitPython version and board name

CircuitPython versions tested: 10.0.3, 10.1.3
  Hardware: Adafruit Metro RP2350 (RP2350B) using A2 stepping (that can have issues)

Code/REPL

import board, rp2pio, adafruit_pioasm, microcontroller, gc, time, digitalio

  microcontroller.cpu.frequency = 252_000_000

  vga_program = adafruit_pioasm.assemble("""
  .program vga_rgb_hsync
  .side_set 1
  .wrap_target
      set y, 15           side 1
  pixel_loop:
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      out pins, 8         side 1 [1]
      jmp y-- pixel_loop  side 1
      nop                 side 1 [7]
      set x, 4            side 0 [15]
  hsync_loop:
      nop                 side 0 [14]
      jmp x-- hsync_loop  side 0
      nop                 side 1 [15]
      nop                 side 1 [15]
      nop                 side 1 [6]
  .wrap
  """)

  # 320x525 frame buffer, all 0xFF (expected output: solid white)
  buf = bytearray([0xFF] * 320 * 525)

  vsync = digitalio.DigitalInOut(board.D11)
  vsync.direction = digitalio.Direction.OUTPUT
  vsync.value = True

  sm = rp2pio.StateMachine(
      vga_program,
      frequency=25_175_000,
      first_out_pin=board.D2,
      out_pin_count=8,
      first_sideset_pin=board.D10,
      sideset_pin_count=1,
      auto_pull=True,
      pull_threshold=8,
      out_shift_right=False,
  )

  sm.background_write(loop=buf)
  time.sleep(0.1)
  print(f"sm.writing: {sm.writing}")  # True
  # GPIO2–9 output: wrong data (see results table below)

Behavior

Expected: GPIO2–9 output matches buf contents (0xFF = solid white).

---

Results by version and configuration

Config A — v6 PIO: 25.175 MHz SM, out [1] (2 cycles/pixel), 252 MHz CPU:

  ┌─────────┬────────────┬──────────────────────────────────────────────────┐
  │ Version │ sm.writing │                      Screen                      │
  ├─────────┼────────────┼──────────────────────────────────────────────────┤
  │ 10.0.3  │ True       │ All black — zero data delivered                  │
  ├─────────┼────────────┼──────────────────────────────────────────────────┤
  │ 10.1.3  │ True       │ Top ~40% shows partial colour; bottom ~60% black │
  └─────────┴────────────┴──────────────────────────────────────────────────┘

Config B — 252 MHz PIO: 50.4 MHz SM, out [3] (4 cycles/pixel), 252 MHz CPU
(replace frequency=25_175_000 with frequency=50_400_000 and change [1] → [3] in pixel loop):

  ┌─────────┬────────────┬───────────┐
  │ Version │ sm.writing │  Screen   │
  ├─────────┼────────────┼───────────┤
  │ 10.0.3  │ True       │ All black │
  ├─────────┼────────────┼───────────┤
  │ 10.1.3  │ True       │ All black │
  └─────────┴────────────┴───────────┘

Description

StateMachine.background_write(loop=buffer) delivers incorrect pixel data at system clocks ≥ ~160 MHz. DMA reports active (sm.writing=True), HSYNC sideset runs correctly (monitor syncs), but pixel output is wrong. Behavior partially improved in 10.1.3 but is not fixed.

Tested at 200 MHz CPU to rule out other causes:

  ┌─────────────────────────────────────────────┬─────────────────────────────────────────────────┐
  │                    Test                     │                     Result                      │
  ├─────────────────────────────────────────────┼─────────────────────────────────────────────────┤
  │ sm.write(buf) in loop                       │ Completes at ~60 Hz — one-shot DMA works        │
  ├─────────────────────────────────────────────┼─────────────────────────────────────────────────┤
  │ initial_out_pin_state=0xFF, NOP pixel loop  │ Colour visible — GPIO output and PIO clock work │
  ├─────────────────────────────────────────────┼─────────────────────────────────────────────────┤
  │ background_write(loop=buf) with 0xFF buffer │ Sync ✓, pixel data wrong                        │
  └─────────────────────────────────────────────┴─────────────────────────────────────────────────┘

Conclusion: The fault is specifically in background_write's DMA loop restart mechanism. One-shot DMA, GPIO output, and
PIO timing all work correctly at 200 MHz+.

---

Clock threshold

  ┌───────────┬───────────────────────────┐
  │ CPU clock │          Result           │
  ├───────────┼───────────────────────────┤
  │ 150 MHz   │ Correct ✓                 │
  ├───────────┼───────────────────────────┤
  │ 160 MHz   │ Corrupted / sync unstable │
  ├───────────┼───────────────────────────┤
  │ 200 MHz   │ Sync ✓, wrong data        │
  ├───────────┼───────────────────────────┤
  │ 252 MHz   │ Sync ✓, wrong data        │
  └───────────┴───────────────────────────┘

150 MHz is the rated RP2350B speed; the bug manifests at all tested overclock frequencies.

Additional information

No response

[TheKitty]

Follow-up: corrected test files and updated results

The original report used a solid 0xFF buffer. Due to the resistor DAC, the output is never pure white, making it hard to distinguish correct output from corruption. Replacing with SMPTE color bars (8 clearly distinct colors) gives cleaner results. The two standalone test scripts below are the revised versions.

---

Confirmed working — 150 MHz, CircuitPython 10.0.3

VGA Video OK 150MHz.py — deployed and verified: SMPTE colour bars displayed continuously and stably.

VGA Video OK 150MHz.py

# SPDX-FileCopyrightText: 2026 Anne Barela
# SPDX-License-Identifier: MIT
"""
Bug report: rp2pio background_write(loop=) delivers wrong data above ~150 MHz.

THIS FILE -- working reference at 150 MHz (CircuitPython 10.0.3).
Companion:  "VGA Video Broken 252MHz.py" -- identical except CPU clock = 252 MHz.

Expected result: SMPTE colour bars (white, yellow, cyan, green, magenta, red, blue, black)
              displayed continuously and stably.
Actual result:   SMPTE colour bars displayed correctly.  <- CORRECT on 10.0.3

Note: CircuitPython 10.1.3 has regressed this case -- colour bars also broken at 150 MHz
on 10.1.3 (top ~40% partial colour, rest black). Use 10.0.3 to observe correct behaviour.

Hardware (Adafruit Metro RP2350):
  GPIO2-9:  RGB332 resistor DAC -> VGA colour pins
  GPIO10:   HSYNC (PIO sideset)
  GPIO11:   VSYNC (CPU digitalio)
  VGA DB15 connector required to observe output.

Colour encoding (hardware-specific DAC wiring):
  bits[7:5]  ->  GPIO2-4  ->  VGA Blue  (3-bit, 0-7)
  bits[4:2]  ->  GPIO5-7  ->  VGA Green (3-bit, 0-7)
  bits[1:0]  ->  GPIO8-9  ->  VGA Red   (2-bit, 0-3)
"""

import board
import rp2pio
import adafruit_pioasm
import digitalio
import supervisor
import microcontroller
import gc
import time

supervisor.runtime.autoreload = False
gc.collect()

microcontroller.cpu.frequency = 150_000_000   # <- only line that differs from broken version

VGA_RGB_BASE = board.D2
VGA_HSYNC    = board.D10
VGA_VSYNC    = board.D11

VGA_PIXEL_CLOCK = 25_175_000

VGA_V_VISIBLE = 480
VGA_V_FRONT   =  10
VGA_V_SYNC    =   2
VGA_V_BACK    =  33
VGA_V_TOTAL   = 525

VGA_BUF_W = 320
VGA_BUF_H = 240

vga_program = adafruit_pioasm.assemble("""
.program vga_rgb_hsync
.side_set 1

.wrap_target
    set y, 15           side 1
pixel_loop:
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    jmp y-- pixel_loop  side 1

    nop                 side 1 [7]

    set x, 4            side 0 [15]
hsync_loop:
    nop                 side 0 [14]
    jmp x-- hsync_loop  side 0

    nop                 side 1 [15]
    nop                 side 1 [15]
    nop                 side 1 [6]
.wrap
""")

_COLOR_BARS = [
    0xFF,  # White    B=7 G=7 R=3
    0x1F,  # Yellow   B=0 G=7 R=3
    0xFC,  # Cyan     B=7 G=7 R=0
    0x1C,  # Green    B=0 G=7 R=0
    0xE3,  # Magenta  B=7 G=0 R=3
    0x03,  # Red      B=0 G=0 R=3
    0xE0,  # Blue     B=7 G=0 R=0
    0x00,  # Black    B=0 G=0 R=0
]

class VGAOutput:
    def __init__(self):
        self.framebuffer = bytearray(VGA_BUF_W * VGA_BUF_H)
        self.full_frame  = bytearray(VGA_BUF_W * VGA_V_TOTAL)

    def sync_frame(self):
        w  = VGA_BUF_W
        fb = memoryview(self.framebuffer)
        ff = self.full_frame
        for y in range(VGA_BUF_H):
            row = fb[y * w:(y + 1) * w]
            ff[(2 * y)     * w:(2 * y + 1) * w] = row
            ff[(2 * y + 1) * w:(2 * y + 2) * w] = row

    def draw_color_bars(self):
        fb = self.framebuffer
        n  = len(_COLOR_BARS)
        bw = VGA_BUF_W // n
        for i, color in enumerate(_COLOR_BARS):
            x0    = i * bw
            seg_w = bw if i < n - 1 else VGA_BUF_W - x0
            seg   = bytes([color]) * seg_w
            for row in range(VGA_BUF_H):
                start = row * VGA_BUF_W + x0
                fb[start:start + seg_w] = seg

def main():
    print(f"VGA bug report - working reference at 150 MHz")
    print(f"CPU: {microcontroller.cpu.frequency // 1_000_000} MHz")

    vga = VGAOutput()
    vga.draw_color_bars()
    vga.sync_frame()
    gc.collect()
    print(f"Free memory: {gc.mem_free()} bytes")

    vsync = digitalio.DigitalInOut(VGA_VSYNC)
    vsync.direction = digitalio.Direction.OUTPUT
    vsync.value = True

    sm = rp2pio.StateMachine(
        vga_program,
        frequency=VGA_PIXEL_CLOCK,
        first_out_pin=VGA_RGB_BASE,
        out_pin_count=8,
        first_sideset_pin=VGA_HSYNC,
        sideset_pin_count=1,
        auto_pull=True,
        pull_threshold=8,
        out_shift_right=False,
    )

    actual        = sm.frequency
    _NS           = 1_000_000_000
    frame_ns      = VGA_V_TOTAL * 800 * _NS // actual
    vsync_low_ns  = (VGA_V_VISIBLE + VGA_V_FRONT) * 800 * _NS // actual
    vsync_high_ns = (VGA_V_VISIBLE + VGA_V_FRONT + VGA_V_SYNC) * 800 * _NS // actual
    print(f"PIO: {actual:,} Hz   HSYNC: {actual // 800 // 1000} kHz")

    # All prints and gc.collect() must complete BEFORE background_write().
    print("Screen should show SMPTE colour bars.  Press Auto-Adjust on monitor.")
    gc.collect()

    t0 = time.monotonic_ns()
    sm.background_write(loop=vga.full_frame)
    time.sleep(0.1)
    print(f"DMA looping: {sm.writing}")   # one diagnostic print after is OK

    now   = time.monotonic_ns()
    phase = (now - t0) % frame_ns
    next_low  = now + (frame_ns - phase) + vsync_low_ns
    next_high = now + (frame_ns - phase) + vsync_high_ns
    _LEAD_NS  = 1_000_000

    while True:
        gc.collect()
        sleep_ns = next_low - time.monotonic_ns() - _LEAD_NS
        if sleep_ns > 1_000_000:
            time.sleep(sleep_ns / _NS)
        while time.monotonic_ns() < next_low:
            pass
        vsync.value = False
        while time.monotonic_ns() < next_high:
            pass
        vsync.value = True
        next_low  += frame_ns
        next_high += frame_ns

main()

---

Confirmed broken — 252 MHz, CircuitPython 10.0.3

VGA Video Broken 252MHz.py — identical to the working file; only microcontroller.cpu.frequency differs.

VGA Video Broken 252MHz.py

# SPDX-FileCopyrightText: 2026 Anne Barela
# SPDX-License-Identifier: MIT
"""
Bug report: rp2pio background_write(loop=) delivers wrong data above ~150 MHz.

THIS FILE -- broken at 252 MHz.
Companion:  "VGA Video OK 150MHz.py" -- identical except CPU clock = 150 MHz.

Expected result: SMPTE colour bars (white, yellow, cyan, green, magenta, red, blue, black)
              displayed continuously and stably.
Actual result:
  CircuitPython 10.0.3 -- correct colour bars appear briefly (first DMA pass), then the
    monitor loses and re-acquires sync repeatedly. sm.writing is True throughout. The DMA
    loop restart fails above ~150 MHz: the PIO FIFO starves, the SM stalls on "out pins",
    and the HSYNC sideset stops firing until the FIFO refills -- causing the monitor to
    cycle through sync acquisition repeatedly.
  CircuitPython 10.1.3 -- top ~40% of screen shows partial/wrong colour; bottom ~60% black.

Hardware (Adafruit Metro RP2350):
  GPIO2-9:  RGB332 resistor DAC -> VGA colour pins
  GPIO10:   HSYNC (PIO sideset)
  GPIO11:   VSYNC (CPU digitalio)
  VGA DB15 connector required to observe output.

Colour encoding (hardware-specific DAC wiring):
  bits[7:5]  ->  GPIO2-4  ->  VGA Blue  (3-bit, 0-7)
  bits[4:2]  ->  GPIO5-7  ->  VGA Green (3-bit, 0-7)
  bits[1:0]  ->  GPIO8-9  ->  VGA Red   (2-bit, 0-3)
"""

import board
import rp2pio
import adafruit_pioasm
import digitalio
import supervisor
import microcontroller
import gc
import time

supervisor.runtime.autoreload = False
gc.collect()

microcontroller.cpu.frequency = 252_000_000   # <- only line that differs from working version

VGA_RGB_BASE = board.D2
VGA_HSYNC    = board.D10
VGA_VSYNC    = board.D11

VGA_PIXEL_CLOCK = 25_175_000

VGA_V_VISIBLE = 480
VGA_V_FRONT   =  10
VGA_V_SYNC    =   2
VGA_V_BACK    =  33
VGA_V_TOTAL   = 525

VGA_BUF_W = 320
VGA_BUF_H = 240

vga_program = adafruit_pioasm.assemble("""
.program vga_rgb_hsync
.side_set 1

.wrap_target
    set y, 15           side 1
pixel_loop:
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    out pins, 8         side 1 [1]
    jmp y-- pixel_loop  side 1

    nop                 side 1 [7]

    set x, 4            side 0 [15]
hsync_loop:
    nop                 side 0 [14]
    jmp x-- hsync_loop  side 0

    nop                 side 1 [15]
    nop                 side 1 [15]
    nop                 side 1 [6]
.wrap
""")

_COLOR_BARS = [
    0xFF,  # White    B=7 G=7 R=3
    0x1F,  # Yellow   B=0 G=7 R=3
    0xFC,  # Cyan     B=7 G=7 R=0
    0x1C,  # Green    B=0 G=7 R=0
    0xE3,  # Magenta  B=7 G=0 R=3
    0x03,  # Red      B=0 G=0 R=3
    0xE0,  # Blue     B=7 G=0 R=0
    0x00,  # Black    B=0 G=0 R=0
]

class VGAOutput:
    def __init__(self):
        self.framebuffer = bytearray(VGA_BUF_W * VGA_BUF_H)
        self.full_frame  = bytearray(VGA_BUF_W * VGA_V_TOTAL)

    def sync_frame(self):
        w  = VGA_BUF_W
        fb = memoryview(self.framebuffer)
        ff = self.full_frame
        for y in range(VGA_BUF_H):
            row = fb[y * w:(y + 1) * w]
            ff[(2 * y)     * w:(2 * y + 1) * w] = row
            ff[(2 * y + 1) * w:(2 * y + 2) * w] = row

    def draw_color_bars(self):
        fb = self.framebuffer
        n  = len(_COLOR_BARS)
        bw = VGA_BUF_W // n
        for i, color in enumerate(_COLOR_BARS):
            x0    = i * bw
            seg_w = bw if i < n - 1 else VGA_BUF_W - x0
            seg   = bytes([color]) * seg_w
            for row in range(VGA_BUF_H):
                start = row * VGA_BUF_W + x0
                fb[start:start + seg_w] = seg

def main():
    print(f"VGA bug report - broken at 252 MHz")
    print(f"CPU: {microcontroller.cpu.frequency // 1_000_000} MHz")

    vga = VGAOutput()
    vga.draw_color_bars()
    vga.sync_frame()
    gc.collect()
    print(f"Free memory: {gc.mem_free()} bytes")

    vsync = digitalio.DigitalInOut(VGA_VSYNC)
    vsync.direction = digitalio.Direction.OUTPUT
    vsync.value = True

    sm = rp2pio.StateMachine(
        vga_program,
        frequency=VGA_PIXEL_CLOCK,
        first_out_pin=VGA_RGB_BASE,
        out_pin_count=8,
        first_sideset_pin=VGA_HSYNC,
        sideset_pin_count=1,
        auto_pull=True,
        pull_threshold=8,
        out_shift_right=False,
    )

    actual        = sm.frequency
    _NS           = 1_000_000_000
    frame_ns      = VGA_V_TOTAL * 800 * _NS // actual
    vsync_low_ns  = (VGA_V_VISIBLE + VGA_V_FRONT) * 800 * _NS // actual
    vsync_high_ns = (VGA_V_VISIBLE + VGA_V_FRONT + VGA_V_SYNC) * 800 * _NS // actual
    print(f"PIO: {actual:,} Hz   HSYNC: {actual // 800 // 1000} kHz")

    # All prints and gc.collect() must complete BEFORE background_write().
    print("Screen should show SMPTE colour bars - if wrong or black, bug is present.")
    gc.collect()

    t0 = time.monotonic_ns()
    sm.background_write(loop=vga.full_frame)
    time.sleep(0.1)
    print(f"DMA looping: {sm.writing}")   # one diagnostic print after is OK

    now   = time.monotonic_ns()
    phase = (now - t0) % frame_ns
    next_low  = now + (frame_ns - phase) + vsync_low_ns
    next_high = now + (frame_ns - phase) + vsync_high_ns
    _LEAD_NS  = 1_000_000

    while True:
        gc.collect()
        sleep_ns = next_low - time.monotonic_ns() - _LEAD_NS
        if sleep_ns > 1_000_000:
            time.sleep(sleep_ns / _NS)
        while time.monotonic_ns() < next_low:
            pass
        vsync.value = False
        while time.monotonic_ns() < next_high:
            pass
        vsync.value = True
        next_low  += frame_ns
        next_high += frame_ns

main()

---

Updated results

CPU clock	CP version	sm.writing	Screen
150 MHz	10.0.3	True	Correct SMPTE colour bars, stable ✓
252 MHz	10.0.3	True	Correct bars briefly (first DMA pass), then repeated monitor sync loss
150 MHz	10.1.3	True	Top ~40% partial colour, rest black ← regression
252 MHz	10.1.3	True	Top ~40% partial colour, rest black

More precise failure description (252 MHz, 10.0.3)

The brief correct image on first boot makes the failure mode clearer: the initial DMA transfer works — the PIO program, auto_pull, and initial FIFO fill are all fine. The bug is in the loop restart: after background_write(loop=buf) reaches the end of the buffer and tries to restart from the beginning, the DMA channel does not refill the FIFO fast enough at ≥160 MHz. The PIO SM stalls on out pins, 8 while waiting for data, the HSYNC sideset on that instruction does not advance, and the monitor loses horizontal sync until the FIFO refills. This produces the visible flicker/sync-cycling rather than a stable wrong image.

sm.writing remains True throughout, confirming the DMA channel believes it is running correctly.

[TheKitty]

Root cause analysis and potential fixes

I've been investigating this while building a VGA signal generator on Metro RP2350 (background_write(loop=full_frame) streaming 168,000-byte framebuffers to a PIO state machine at 25.175 MHz). The failure mode at CPU clocks above ~150 MHz is consistent with PIO TX FIFO starvation during the DMA loop restart.

Why it starves:
The SM pulls one byte from the FIFO every 2 SM cycles (~79 ns at 25.175 MHz). With a 4-entry TX FIFO and
pull_threshold=8, the starvation window is approximately 318 ns. If the DMA takes longer than that to restart at the loop boundary, the SM stalls on out pins — and in my case, the HSYNC sideset stops firing, causing the monitor to lose and re-acquire sync repeatedly. The first DMA pass always shows correct output; it's the loop restart that fails.

Why CPU frequency matters:
If the loop restart involves any CPU or software component (interrupt handler retriggering the DMA), the latency in nanoseconds doesn't necessarily shrink as CPU frequency rises — and any jitter or scheduling delay at the boundary will exceed the fixed ~318 ns FIFO margin.

Three possible fixes, from simplest to most robust:

1. FIFO joining (quick win)
   RP2350 supports joining TX + RX FIFOs via SHIFTCTRL_FJOIN_TX, creating an 8-entry TX FIFO. This doubles the starvation margin to ~636 ns. Since background_write() is TX-only, the RX FIFO is unused. A fifo_join_tx=True parameter on StateMachine (or applying it automatically when background_write(loop=) is active and no RX is in use) would provide this margin at no cost. Doesn't fix the root cause but buys significant headroom.

2. Pure hardware DMA chaining (correct fix)
   The RP2350 DMA supports fully autonomous channel chaining with no CPU involvement. The two-channel loop pattern:

• Channel A: READ = buffer, WRITE = SM TX FIFO, COUNT = len, CHAIN_TO = B
• Channel B: READ = &control_block, WRITE = &DMA_CH_A_READ_ADDR_TRIG, COUNT = 1 (control block holds the buffer start address)

When channel A finishes, it fires channel B. Channel B writes the buffer address into channel A's READ_ADDR_TRIG
alias, which re-arms and starts channel A atomically — no CPU, no interrupt. The handoff is a handful of DMA clock cycles, ≈20–40 ns at 252 MHz, well within the 318 ns FIFO margin even before any FIFO join. If the current
implementation involves a CPU interrupt at the loop boundary, replacing it with this pattern should fix the starvation at any CPU frequency.

3. DMA ring mode (zero-gap)
   RP2350 DMA RING_SIZE/RING_SEL wraps the read address within a power-of-2 aligned region with zero restart gap. The constraint is that the buffer must be power-of-2 sized and aligned. For a 320×525 = 168,000-byte buffer the next power of 2 is 262,144 bytes — wasteful but feasible on RP2350B (520 KB SRAM). Could be offered as an opt-in with documented alignment requirements.

Recommended: Option 2 with Option 1 as defense-in-depth. Hardware chaining gives a ~30 ns restart gap against a 636 ns margin (with FIFO join) — 20× headroom at 252 MHz.

Test case: Minimal reproducer is a PIO SM at 25.175 MHz consuming 8-bit data, background_write(loop=buffer) where buffer is 168,000 bytes, CPU overclocked to 252 MHz. Failure is visible on first loop boundary (~16.7 ms after start).

[TheKitty]

Potential fix sketch (Claude Code analysis — unverified, for core developer reference)

The following is an AI-assisted code analysis suggesting how the bug might be fixed. It has not been tested or verified and is offered only as a starting point for developers familiar with the codebase.

---

Option 1: FIFO join — may already be usable with no code changes

fifo_type is already a StateMachine() parameter. Passing fifo_type="tx" maps to PIO_FIFO_JOIN_TX, joining the unused RX FIFO into TX to create an 8-entry TX FIFO. This doubles the starvation window from ~318 ns to ~636 ns and may be sufficient at moderate overclock frequencies.

sm = rp2pio.StateMachine(
    vga_program,
    frequency=25_175_000,
    ...
    fifo_type="tx",   # 8-entry TX FIFO; doubles starvation margin
)

No code change required — if this works, it just needs to be documented as the recommended mitigation when using background_write(loop=) at high clock speeds.

TheKitty note: I think this was tried in earlier code with an issue, request core developer verification it is a valid construct and if so we can add a note to ReadTheDocs to indicate it.

---

Option 2: Hardware DMA chaining — replace IRQ restart with pure hardware loop

Root cause (from reading the source):

background_write registers DMA_IRQ_0. When the data channel finishes, the ISR calls rp2pio_statemachine_dma_complete_write, which retriggers via:

dma_channel_set_read_addr(channel_write, buf, false);
dma_channel_set_trans_count(channel_write, count, true);  // true = trigger

The gap between the last DMA transfer and this retrigger is IRQ latency + ISR dispatch + handler code. During this gap the PIO TX FIFO drains. The pure-loop case — background_write(loop=buf) with no once and no loop2 — is deterministic and can use hardware chaining with no IRQ at all. The existing IRQ path handles the once/loop/loop2 sequencing and would be left completely untouched.

Sketch of changes:

StateMachine.h — add two fields to the struct:

    // NEW: hardware-chained loop support
    int ctrl_dma_channel;          // second DMA channel for hw loop; NO_DMA_CHANNEL if unused
    uint32_t loop_buf_addr_word;   // stable memory holding buf start address for ctrl channel to read

StateMachine.c — branch in common_hal_rp2pio_statemachine_background_write:

bool pure_loop = (self->once_write_buf_info.info.len == 0) &&
                 (self->loop2_write_buf_info.info.len == 0) &&
                 (self->loop_write_buf_info.info.len != 0);

if (pure_loop) {
    int ctrl_ch = dma_claim_unused_channel(false);
    if (ctrl_ch == NO_DMA_CHANNEL) {
        goto irq_path;   // fall back to existing IRQ path if no channel available
    }
    self->ctrl_dma_channel = ctrl_ch;
    self->loop_buf_addr_word = (uint32_t)self->loop_write_buf_info.info.buf;

    // Data channel: identical config to existing path, plus CHAIN_TO = ctrl_ch
    dma_channel_config c_write = dma_channel_get_default_config(channel_write);
    channel_config_set_transfer_data_size(&c_write, _stride_to_dma_size(stride_in_bytes));
    channel_config_set_dreq(&c_write, self->tx_dreq);
    channel_config_set_read_increment(&c_write, true);
    channel_config_set_write_increment(&c_write, false);
    channel_config_set_bswap(&c_write, swap);
    channel_config_set_chain_to(&c_write, ctrl_ch);          // ← fires ctrl_ch when done
    dma_channel_configure(channel_write, &c_write,
        tx_destination,
        self->loop_write_buf_info.info.buf,
        self->loop_write_buf_info.info.len / stride_in_bytes,
        false);

    // Control channel: reads loop_buf_addr_word, writes to data channel's
    // al3_read_addr_trig alias — sets READ_ADDR and triggers data channel
    // using its TRANS_COUNT RELOAD value. No DREQ; fires instantly.
    // ~5-10 DMA clock cycles total restart gap (~20-40 ns at 252 MHz).
    dma_channel_config c_ctrl = dma_channel_get_default_config(ctrl_ch);
    channel_config_set_transfer_data_size(&c_ctrl, DMA_SIZE_32);
    channel_config_set_read_increment(&c_ctrl, false);
    channel_config_set_write_increment(&c_ctrl, false);
    dma_channel_configure(ctrl_ch, &c_ctrl,
        &dma_hw->ch[channel_write].al3_read_addr_trig,
        &self->loop_buf_addr_word,
        1,
        false);

    // No IRQ registration needed — restart is fully hardware-driven.
    dma_start_channel_mask(1u << channel_write);
    return true;
}

irq_path:
self->ctrl_dma_channel = NO_DMA_CHANNEL;
// ... existing IRQ-based code unchanged ...

rp2pio_statemachine_clear_dma_write — abort ctrl channel on stop:

    if (self->ctrl_dma_channel != NO_DMA_CHANNEL) {
        dma_channel_abort(self->ctrl_dma_channel);
        dma_channel_unclaim(self->ctrl_dma_channel);
        self->ctrl_dma_channel = NO_DMA_CHANNEL;
    }
    // ... existing abort/unclaim code unchanged ...

Why this should be safe:

• loop_buf_addr_word is in the StateMachine struct (heap), not the stack — stable address for the ctrl channel to read.
• The entire once/loop/loop2 IRQ path is untouched; only the pure single-buffer loop takes the new path.
• If no second DMA channel is available, it falls back to the existing IRQ path.
• stop_background_write already calls clear_dma_write, so cleanup is covered by the addition above.

---

This analysis was produced by Claude Code and has not been compiled or tested. It is intended as a reference sketch for developers who know the codebase. Corrections and improvements welcome.

[TheKitty]

@dhalbert - hopefully this chain is not too scattered, I've looked to refine the issue and in the last post review the rp2pio code to suggest core changes that I myself am not familiar enough to suggest but that a core developer might better see what's going on. Again it's my understanding the PicoDVI implementation uses the chained DMA method to have video written out without stall. At stock clocks I could do it with one DMA channel. Above 640x480 pixel doubled, it needs the additional umph. The FIFO thing might work and be easiest if it's valid but does not really provide the strength of the DMA solution.

[TheKitty]

Test result: Option 1 (fifo_type="tx") does not fix the issue

Hardware tested: Adafruit Metro RP2350, CircuitPython 10.0.3, 252 MHz system clock.

Added fifo_type="tx" to the StateMachine() call in the broken 252 MHz test file. The parameter is accepted without error and the code runs cleanly:

VGA bug report — 252 MHz with fifo_type='tx' mitigation
CPU: 252 MHz
Free memory: 147488 bytes
PIO: 25,170,503 Hz   HSYNC: 31 kHz
Screen should show SMPTE colour bars — testing fifo_type='tx' mitigation.
DMA looping: True

Monitor reports sync lock, but no colour bars are displayed — the screen remains black. The doubled FIFO starvation margin (~636 ns with 8-entry TX FIFO vs ~318 ns with 4-entry) is not sufficient to bridge the DMA loop restart gap at 252 MHz.

This confirms that Option 1 (FIFO join) is not a viable fix at this clock speed with the current IRQ-based restart implementation. The DMA restart gap exceeds 636 ns above ~150 MHz, which is beyond what a simple FIFO size increase can compensate for.

Option 2 (pure hardware DMA chaining, no CPU/IRQ in the restart path) appears to be required. The fix sketch in the previous comment describes the approach.