retroDE_ps2/docs/wave26_multi_beat_dma_plan.md

Wave 2.6 Mini-Plan: Multi-Beat DMAC to GIF to GS

This document defines the next consolidation step after the completed Wave 2.5 memory-backed BGCOLOR via DMA/GIF milestone.

Goal:

• prove the DMAC/GIF path across more than one qword,
• validate address stepping from MADR,
• validate end-of-packet signaling on the final beat only,
• preserve the visible Milestone A+ outcome through the existing GS/platform chain,
• do all of that without expanding packet-format scope prematurely.

Working milestone name:

multi-beat BGCOLOR via DMA/GIF

That means:

• DMAC channel 2 is programmed with QWC = 2,
• DMAC performs two memory-backed qword fetches,
• GIF accepts two qwords as two standalone register-write packets,
• GS observes two consecutive writes,
• platform video reflects the final written color,
• traces prove beat ordering, source-address stepping, and gif_tag_last behavior.

Why this goes before memory-map routing

Wave 2.5 established the right ownership seam:

• DMAC is now a memory client,
• MADR is real,
• RAM is owned by the memory subsystem,
• the graphics-visible path is intact.

The next most valuable risk to retire is not topology, it is transfer shape.

Multi-beat transfer support is the first place where subtle bugs are likely to hide:

• off-by-one address stepping,
• incorrect remaining-count bookkeeping,
• gif_tag_last asserted too early or too late,
• state-machine stalls between fetch and send,
• final-color behavior when multiple writes land back-to-back.

Once that is stable, routing the same traffic through ee_memory_map_stub becomes a narrower structural refactor instead of a behavioral and structural change combined.

Deliverables

The first Wave 2.6 pass should land:

1. an updated rtl/dmac/dmac_reg_stub.sv
2. a small comment/README update in rtl/gif_gs/gif_path_stub.sv if needed to make multi-beat behavior explicit
3. an updated sim/tb/integration/tb_bgcolor_via_dma.sv
4. sim/Makefile updates only if the run flow changes
5. optional README note if the integration-TB expectations materially change

No new subsystem contracts or decision records are required for this step.

Scope boundary

This plan is intentionally narrow.

It does not attempt to implement:

• real GIFtag decode,
• packed register lists,
• chain mode,
• linked-list DMA,
• path arbitration,
• full EE memory-map routing,
• any IOP or SIF behavior,
• GS drawing primitives or VRAM.

The purpose is to prove:

QWC > 1 works correctly on the already-established temporary topology.

Transfer length scope

Recommendation:

• sign off this phase on QWC = 2

Do not require QWC = 4 for first signoff.

Why two qwords is enough

Two beats cover every new behavior category this phase is meant to validate:

• beat 0 source address = MADR
• beat 1 source address = MADR + 16
• beat 0 has gif_tag_last = 0
• beat 1 has gif_tag_last = 1
• the transfer must remain active across an intermediate beat
• the final beat must retire cleanly into DMA_DONE

Four beats would add more distance but not a new category of behavior. If the implementation naturally supports QWC > 2, that is welcome, but the required directed proof for this phase should stay at 2.

Payload semantics

Recommendation:

• keep the current project-local packet model:
  • one qword = one standalone GS register write
• use the same destination register twice:
  • BGCOLOR on beat 0
  • BGCOLOR again on beat 1 with a different RGB value

This is the simplest high-signal option.

Why this goes over the alternatives

Using one register twice keeps the focus on transport, not packet-model growth.

It gives us:

• two visible GS-side events,
• two visible GIF-side accepts,
• a deterministic final platform-visible color,
• no need to invent a tag-qword/data-qword pairing before we are ready to tackle real GIFtag structure.

Using two different GS registers would blur the phase boundary by making the test partly about GS register-surface breadth. That coverage already exists in the single-register-path and can expand later when GIFtag work begins.

Recommended concrete payload

Preload two qwords at consecutive addresses:

• beat 0 packet:
  • register = BGCOLOR
  • value = a clearly non-final color, for example blue
• beat 1 packet:
  • register = BGCOLOR
  • value = the intended final visible color, for example red

That gives a clean final assertion:

• two EV_BGCOLOR events occurred,
• final bg_* equals the second payload.

dmac_reg_stub exact scope

Status target:

• the current state machine becomes genuinely multi-beat for the signoff case

Owns in this phase

• repeated qword fetches based on QWC
• source-address stepping by 16 bytes per beat
• repeated send/accept handshakes into gif_path_stub
• correct gif_tag_last behavior on the final beat only
• transfer completion only after the final beat is accepted

Explicit non-goals

• channel arbitration
• chain-mode TADR behavior
• interrupt-driven completion semantics
• routing through ee_memory_map_stub

Required behavioral rules

For QWC = 2:

1. DMA_START.arg2 reports the latched MADR
2. beat 0 fetch/read uses MADR
3. beat 1 fetch/read uses MADR + 16
4. beat 0 emits gif_tag_last = 0
5. beat 1 emits gif_tag_last = 1
6. DMA_DONE occurs only after beat 1 is accepted downstream

Implementation note:

• if the RTL naturally supports arbitrary QWC > 0, that is fine
• the TB and acceptance criteria only need to lock QWC = 2

gif_path_stub behavior in Wave 2.6

Recommendation:

• keep gif_path_stub stateless with respect to packet framing
• keep the current project-local interpretation:
  • every accepted qword is one standalone register write
• preserve in_last as trace-visible metadata only

This means no new internal "tag phase vs. data phase" state is added yet.

Why this is the right boundary

Wave 2.6 is about transfer length, not packet-model realism.

If we introduce tag/data pairing now, we turn one scoped extension into two:

• multi-beat DMA sequencing
• a new packet parser contract

That is exactly the kind of scope expansion we have been avoiding well so far.

Trace policy

No new event names are required for Wave 2.6.

Reuse the current vocabulary:

• EV_DMA_CFG
• EV_DMA_START
• EV_DMA_BEAT
• EV_DMA_DONE
• EV_GIFTAG
• EV_BGCOLOR

Required trace-visible facts

The Wave 2.6 proof must make the following visible in traces:

• two DMAC-backed RAM reads from consecutive qword addresses
• two EV_DMA_BEAT events with:
  • beat index 0, source address MADR
  • beat index 1, source address MADR + 16
• two EV_GIFTAG events with:
  • flags[0] = 0 on beat 0
  • flags[0] = 1 on beat 1
• two GS-side EV_BGCOLOR events
• one EV_DMA_DONE after the second beat completes

Cycle-perfect alignment between subsystems is not the primary comparison rule. Order and causality are the primary rules:

• read for beat 0 precedes send for beat 0
• read for beat 1 precedes send for beat 1
• done follows final acceptance

Integration testbench shape

Recommendation:

• update the existing sim/tb/integration/tb_bgcolor_via_dma.sv

Do not create a second near-duplicate integration TB for first signoff.

Why update instead of fork

Wave 2.6 is a strict extension of the current Milestone A+ proof:

• same subsystem chain
• same top-level outcome
• same trace sinks

Keeping one canonical integration TB reduces maintenance churn and makes the current path's expectations clearer.

If later we want a minimal single-beat smoke test, that can be added as a focused DMAC unit TB rather than cloning the whole platform chain.

TB preload shape

The TB should preload two qwords into ee_ram_stub:

• first qword at MADR
• second qword at MADR + 16

Suggested values:

• beat 0: BGCOLOR = blue
• beat 1: BGCOLOR = red

TB pass criteria

At minimum, the updated integration TB should require:

1. mem_reads_dmac >= 2
2. dma_cfg_count >= 3
3. dma_start_count == 1
4. dma_beat_count == 2
5. dma_done_count == 1
6. giftag_count == 2
7. gs_bgcolor_count == 2
8. first observed beat source address = MADR
9. second observed beat source address = MADR + 16
10. first GIF end-of-packet flag = 0
11. second GIF end-of-packet flag = 1
12. final bg_* equals the second payload color
13. platform still renders active pixels correctly after transfer completion

Optional but useful:

• count post-transfer frames as before
• assert that DMA_DONE is observed only after the second EV_GIFTAG

Exit criteria

Wave 2.6 is complete when all of the following are true:

• dmac_reg_stub performs a two-beat memory-backed transfer
• MADR stepping is trace-visible and correct
• gif_tag_last is false on beat 0 and true on beat 1
• GIF accepts two qwords without new packet-state machinery
• GS observes two BGCOLOR writes
• platform video settles to the second color
• make full_checks remains green

Next step after Wave 2.6

If this passes cleanly, the next recommended step is:

• route DMAC through ee_memory_map_stub

That is the right moment for topology cleanup, because the transfer behavior itself will already be stable and trace-proven.