retroDE_ps2/docs/wave2_dma_gif_plan.md

# Wave 2 Mini-Plan: DMAC Channel 2 to GIF to BGCOLOR

This document defines the first Wave 2 implementation target after the
completed Wave 1 milestones and the generated-golden Phase 1 harness.

The target is deliberately narrow:

- establish DMAC as real transfer ownership, not just register plumbing,
- establish GIF as the first programmatic ingress into the GS path,
- produce a visible result through the existing Milestone A video chain.

Working milestone name:

`programmable BGCOLOR via DMA/GIF`

That means:

- software- or testbench-visible programming of DMAC channel 2 intent,
- a minimal packet path into GIF,
- a narrow GIF-to-GS handoff that updates `gs_stub` BGCOLOR,
- visible raster output change through `platform_video_stub`,
- end-to-end traces proving each stage participated.

## Why this path goes first

This is the best next Wave 2 target because it:

- starts from the DMAC contract, which is central PS2 structure,
- keeps the first new ingress path graphics-visible,
- extends Milestone A instead of redoing it,
- avoids pulling in IOP/SIF policy too early,
- sets up a natural bridge into later VIF/VU and broader GIF work.

## Deliverables

The first Wave 2 pass should land:

1. `rtl/dmac/dmac_reg_stub.sv`
2. `rtl/gif_gs/gif_path_stub.sv`
3. one integrated testbench:
   - `sim/tb/integration/tb_bgcolor_via_dma.sv`
4. trace vocabulary additions in:
   - `rtl/debug/trace_pkg.sv`
5. a short README or note in the integration TB directory if one does not
   already exist

## Scope boundary

This plan is not trying to implement:

- generic EE main RAM,
- full DMAC arbitration,
- full GIF decoding,
- any drawing primitive,
- GS VRAM,
- VIF/VU,
- SIF,
- IOP interaction.

The point is to create the smallest correct-shaped programmatic path:

`channel 2 intent -> minimal DMA payload -> minimal GIF packet -> gs_stub BGCOLOR`

## `dmac_reg_stub` exact scope

Status target:

- channel-2-focused, not a pretend full DMAC

### Owns in this phase

- selected DMAC register shell for channel 2,
- channel state machine for a single programmed transfer,
- transfer-start / transfer-active / transfer-done transitions,
- narrow payload handoff into `gif_path_stub`,
- trace events for register writes and transfer lifecycle.

### Explicit non-goals

- multi-channel fairness or arbitration,
- linked-list / chain mode completeness,
- stall/ring semantics,
- interrupt-controller integration beyond trace-visible placeholders,
- memory-backed payload fetch from real EE RAM.

### First-pass data source

For the first integrated proof, allow a testbench-provided or locally-loaded
payload path rather than requiring real main RAM first.

Acceptable phase-1 shapes:

- a tiny internal payload register/FIFO loaded through a narrow debug/test port,
- or a direct payload input interface used only by the integration testbench.

Not acceptable:

- a `dmac_reg_stub` that stops at register writes and never emits payload.

### Recommended channel-2 register surface

Implement only what is needed to express one narrow transfer cleanly.

Suggested first surface:

- `CHCR` for channel 2
  - start bit / direction / mode subset as needed
- `MADR`
  - recorded for trace and future upgrade path
- `QWC`
  - transfer length in 16-byte units
- optional `TADR`
  - only if the implementation wants to reserve chain-mode shape early

Suggested interpretation for first pass:

- one direct transfer mode only
- `QWC == 1` is sufficient for the first visible proof
- `MADR` may be recorded and traced even if the payload is not yet fetched from
  real memory

### Minimal state machine

Recommended states:

- `IDLE`
- `ARMED`
- `ACTIVE`
- `DONE`

Behavior:

- CPU/testbench writes register values
- start condition on `CHCR`
- one payload issued toward `gif_path_stub`
- wait for `gif_path_stub` accept/done handshake
- transition to `DONE`
- optionally clear busy/start-visible state and return to `IDLE`

### `dmac_reg_stub` acceptance criteria

`dmac_reg_stub` is not "done" when registers can be written.

It is done for this phase when:

1. channel 2 can be programmed into a single transfer sequence,
2. it emits a payload/handshake toward `gif_path_stub`,
3. traces show start, active transfer, and done,
4. the integrated testbench proves that this sequence ultimately changes
   `gs_stub` BGCOLOR.

## `gif_path_stub` exact scope

Status target:

- minimal GIF ingress and decode sufficient for BGCOLOR update only

### Owns in this phase

- accepting one narrow DMA-fed packet stream,
- extracting just enough tag/selection information to identify the path,
- decoding only the BGCOLOR-relevant payload form,
- forwarding a GS privileged-register-style write into `gs_stub`,
- trace events for GIF tag and GS-write handoff.

### Explicit non-goals

- PATH arbitration completeness,
- packed register lists beyond what BGCOLOR requires,
- image transfer paths,
- primitive drawing,
- texture or VRAM-visible behavior.

### Recommended first packet shape

Keep the first proof simple and explicit.

Suggested approach:

- a synthetic single-packet format representing:
  - PATH source = channel 2 / GIF
  - destination register = BGCOLOR
  - payload = 24-bit RGB value

This can be encoded as either:

- a tiny project-local "GIF-like" packet for the first integrated proof, or
- a very narrow real GIFtag/register pair if Claude wants to stay closer to the
  real packet model immediately.

My recommendation:

- use a narrow real-looking shape, but only if it stays easy to trace
- otherwise use a project-local packet format and document it clearly as a
  temporary ingress format

### PATH selection

For this phase, hard-scope the path to one source:

- PATH = channel 2 / DMAC GIF path

No arbitration needed yet. Just make the trace name the source explicitly so
future work can preserve the boundary.

### `gif_path_stub` acceptance criteria

1. accepts one payload from `dmac_reg_stub`
2. emits a trace that identifies a GIF-side handoff/tag
3. issues one BGCOLOR update into `gs_stub`
4. integrated testbench sees the new color on the platform video side

## Trace vocabulary additions

Wave 2 needs trace events that express transfer ownership and GIF ingress
without overfitting future behavior.

Recommended additions to `trace_pkg.sv`:

- `EV_DMA_CFG`
- `EV_DMA_START`
- `EV_DMA_BEAT`
- `EV_DMA_DONE`
- `EV_GIFTAG`
- `EV_GS_WRITE`

These names keep the event model readable while leaving room for later detail.

### Recommended payload schemas

#### `DMAC EV_DMA_CFG`

- `arg0 = channel`
- `arg1 = CHCR subset`
- `arg2 = MADR`
- `arg3 = QWC`
- `flags = optional mode bits`

#### `DMAC EV_DMA_START`

- `arg0 = channel`
- `arg1 = qwc`
- `arg2 = payload words/beats planned`
- `arg3 = path id`

#### `DMAC EV_DMA_BEAT`

- `arg0 = channel`
- `arg1 = beat index`
- `arg2 = low payload word or packet id`
- `arg3 = remaining count`

For wide payloads, trace summary over full raw data is acceptable in this phase.

#### `DMAC EV_DMA_DONE`

- `arg0 = channel`
- `arg1 = beats transferred`
- `arg2 = completion code`
- `arg3 = path id`

#### `GIF EV_GIFTAG`

- `arg0 = path source`
- `arg1 = tag summary or local packet type`
- `arg2 = register target`
- `arg3 = payload summary`

#### `GS EV_GS_WRITE`

- `arg0 = register offset`
- `arg1 = write value`
- `arg2 = source id`
- `arg3 = reserved`

### Trace policy note

Do not delete or overload `EV_MODE` / `EV_BGCOLOR`.

Wave 2 should add ingress/transfer visibility, not destroy the simple Wave 1
events that already make debugging easy.

## Integrated testbench shape

Recommended file:

- `sim/tb/integration/tb_bgcolor_via_dma.sv`

This should be the first cross-subsystem Wave 2 harness.

### DUT chain

- `dmac_reg_stub`
- `gif_path_stub`
- `gs_stub`
- `platform_video_stub`
- `trace_sink_stub` instances for at least:
  - DMAC
  - GIF
  - GS
  - PLAT

### Suggested stimulus model

Use a fully controlled synthetic transfer first.

Sequence:

1. reset chain
2. confirm default mid-grey frame behavior
3. configure channel 2 registers
4. provide one payload representing a BGCOLOR update
5. trigger transfer start
6. wait for transfer-done trace/event
7. confirm:
   - GIF saw a tag/payload
   - GS latched the new BGCOLOR
   - platform output changed on active pixels
   - frame event occurred after the color change

### Recommended checks

- one `EV_DMA_CFG`
- one `EV_DMA_START`
- at least one `EV_DMA_BEAT`
- one `EV_DMA_DONE`
- one `EV_GIFTAG`
- one GS-side write event (`EV_GS_WRITE` and/or `EV_BGCOLOR`)
- visible raster color change during active pixels

### Pass criteria

Suggested summary line:

```text
[tb_bgcolor_via_dma] dma_start=1 dma_done=1 giftag=1 gs_write=1 frames=... errors=0
```

A pass requires:

- zero errors
- at least one trace event from each stage
- end-to-end visible color change

## Implementation order inside Wave 2

Recommended order:

1. extend `trace_pkg.sv` with Wave 2 events
2. implement `dmac_reg_stub`
3. implement `gif_path_stub`
4. add integration TB
5. wire `Makefile` target(s)
6. update `sim/README.md`

Rationale:

- event vocabulary first keeps instrumentation coherent
- DMAC first preserves ownership
- GIF second provides the first consumer
- the integration TB defines success better than isolated unit benches here

## Interaction with existing milestones

This work does not replace Wave 1 milestones.

It creates a new intermediate milestone:

`Milestone A+`: visible screen color change driven through DMAC/GIF ownership

That is the right next visible proof before:

- fuller EE work,
- real memory-backed command fetch,
- IOP/SIF bring-up.

## Guardrails

- Do not let `dmac_reg_stub` become a dead-end register shell.
- Do not let `gif_path_stub` accept direct testbench writes that bypass DMAC in
  the integrated proof.
- Do not broaden to generic drawing before the BGCOLOR path is working.
- Do not pull in IOP/SIF just to make Wave 2 feel larger.

## Exit criteria for mini-plan acceptance

This mini-plan is accepted when Claude can implement:

1. a channel-2-focused `dmac_reg_stub`,
2. a narrow `gif_path_stub`,
3. one integrated DMA/GIF/BGCOLOR testbench,
4. with traces proving each stage, not just end-state color.