TeslaRel410/emulator/firmware-decomp/MICROCODE-DECODE-NOTES.md

# PXPL5 IGC micro-code — decode notes (session 6j, 2026-07-16)

Working notes toward executing the compiled IGC micro-code so the ground/sky
(which carry no stored VSTRIP vertices) can be rendered. Complements
`igc_array.py` (the array's computational model) — this is about the *actual
compiled stream* the DMA ships.

## The per-region DMA command list is decoded (from real capture)

`0xf0411cd4` (`fst.d`) copies each screen region's DMA command list into its
queue page. Captured from the cap7 death-cam draw (`scratchpad/coefdump.py`),
one region's list (@ 0x0801fa40) decodes cleanly against `DMAENGN.H` as
`{addr, opcode}` 64-bit pairs (opcode = top nibble, low 7 bits = word count):

```
0x08015000  SEND(4)       ; edge coefficients
0x00000000  FLUSH
0x08015020  SENDE(0x45)   ; z / colour  (69 words)
0x00000000  FLUSH
0x08014100  TXDN
0x08015260  SEND(0x21)    ; 33 words
0x08015380  SEND(0x29)    ; 41 words
0x00000000  TILE(id)      ; per-region tile id in the addr slot (0x20/0x40/0x60/…)
0x0801f008  GOTO          ; link to the next region's queue
0x08015000  FLUSH
0x08015000  SEND(0x10)
0x08015000  FLUSH
```

Key: every region's list references the **same** payload addresses
(0x08015000, 0x08015020, …) and differs only in the `TILE(id)` slot and the
`GOTO` link. The geometry micro-code is **tile-relative** and broadcast to every
tile the primitive covers — the array evaluates it at each tile's own origin.
So this whole list is *one primitive across many tiles*; other primitives
(terrain, sky) have their own DMA lists pointing at their own payloads.

## The SEND payloads carry embedded FLOAT coefficients

Dumped the payloads (`scratchpad/payload_dump.py`). They are **not** opaque —
they interleave control words with recognisable IEEE-754 floats = the edge /
plane / colour coefficients:

```
SEND(4)  @0x08015000 :  00000100  3e013991(=0.1262)  0000ec00  0000…      ; edge
SENDE    @0x08015020 :  00000100  3a804834(=9.79e-4)  8401213a  00000021  ; z/col
                        ba01253a(=-4.93e-4) 00143a21 8381213a 00000022    ; per bit-plane,
                        ba01253a(=-4.93e-4) 00133a22 8301213a 00000023    ; addr 0x21,0x22,…
                        …  (a bit-serial MEMpluseqMEM sweep: the float is the
                            increment, the control words carry the target
                            bit-plane address + length)
SEND(0x21) @0x08015260:  floats 0.1253, 9.79e-4, 0.1262, 0.00111, -0.0157, -0.0078 …
SEND(0x29) @0x08015380:  floats -0.00196, -0.0627 (repeated per bit-plane) …
```

Interpretation: `00000100` recurs as an instruction header; each coefficient
load is `{header, float, control(addr/len), addr}`. The repeated float with an
incrementing address (0x21,0x22,0x23,…) is the bit-serial plane interpolation
(`IGCOPS.C` MEMpluseqMEM) sweeping the bit-planes of a z/colour value, the float
being the Ax+By+C increment.

## The SENDE sweep has a regular 4-word instruction stride

After the `00000100` header + a base float, the z/colour SENDE settles into a
clean 4-word instruction (`scratchpad` analysis):

```
word0  increment float   (e.g. -4.93e-4, constant across the sweep)
word1  00 LL 3a AA        ; LL = a length/countdown (0x14,0x13,0x12,… decrementing)
                          ;      AA = a bit-plane address (0x21,0x22,0x23,… incrementing)
word2  8H 01 21 3a        ; H high-nibble drifts down (0x84,0x83,0x82,…) -> op/plane sel
word3  00 00 00 NN        ; NN = destination bit-plane (0x21,0x22,…)
```

i.e. a `MEMpluseqMEM` sweep: add the increment to each successive bit-plane of
the z (or colour) word, `LL` bit-planes long. The float is the Ax+By+C plane
increment; the control words carry the target bit-address + length. So a plane
value is reconstructable as `{base float, per-x/per-y increment floats, bit
window}` once the control-word field split is pinned.

## The coefficient VALUE encoding is decoded: bit-serial place value

Grouping the payload floats (`scratchpad/decode_corr.py`, `chain_decode.py`) shows
they are not independent — they fall into clean **x2 doubling chains**:

```
0.00788  0.01576  0.03153  0.06305  0.1261  0.25221  0.50441  1.00883   (x2 each)
0.00783  0.01566  0.03132  0.06265  0.12527                             (a 2nd chain)
0.00049  0.00098  0.00196 …                                             (a 3rd)
```

That is exactly how a bit-serial adder holds a number: bit-plane `k` carries the
coefficient x 2^k. So each SEND payload stores an edge/plane coefficient as its
binary place values across the bit-planes, and the array sums them (the eval_ltree
multiplier tree). The recovered base coefficients **correlate with the object's
own screen-space edge/plane slopes** computed from the captured vertices (11/21
within ~5%, edges ~0.125 vs geometry edge-normals ~0.13). Fixed-point scales are
in FOOTER.SS: `.Czscale = 0x497fffff = 2^20` (z), `.Ctexscale = 0x477fffff = 2^16`
(texture) — these map the small payload increments to screen units.

**Consequence:** `igc_array.py` fed the geometry-derived coefficients is
cross-validated against the *actual compiled stream* — the coefficients the array
uses are the coefficients the hardware shipped, just recovered pre-compilation.
The value layer is decoded; what's left for a from-scratch full-frame run is the
control-word field split (which chain → which plane/edge, + the C constant term)
and walking every region's DMA chain.

## SENDE control-word split (z/colour sweep) — decoded

Full SENDE dump (`scratchpad/ctrl_split.py`) shows a perfectly regular **4-word
instruction**, repeated once per bit-plane:

```
word0  FLOAT      constant accumulator increment (e.g. -4.9265e-4), same every instr
word1  00 LL 3a AA   LL = length countdown (0x14,0x13,…,0x00); AA = source bit-addr
                     (0x21,0x22,…); 0x3a = op field
word2  <place-value> the coefficient's value at this bit-plane -> the x2 chain
                     (…8401213a,8381213a for the tiny low planes; then bf81213a=-1.009,
                      bf01213a=-0.504, be81213a=-0.252, … bc01213a=-0.00788)
word3  00 00 00 NN   destination bit-plane (0x21..0x31 => a 17-bit fixed-point value)
```

So SENDE writes one z-or-colour value bit-serially: 17 bit-planes (0x21..0x31),
each carrying `coeff * 2^k` (word2), with a constant carry/increment (word0) and a
length countdown (word1 LL) — a `MEMpluseqMEM` accumulation. The `0x3a`/`0x21`
fields in words 1&2 are the opcode + operand selector (the exact bit split of
`3a`/`21`/`81-vs-01` still to be pinned against IGCOPS.C op numbers, but the
operand roles are clear).

SEND(0x21)/SEND(0x29) (edge/setup) differ: they carry `00000100` headers
interspersed with 3-word `[float, ctrl, ctrl]` groups (e.g. 0.125275, 0.126196,
0.00110586 = the edge/plane bases) — same value encoding, different framing.

To render z from a SENDE from scratch: read word2 across the 17 planes to
reconstruct the coefficient (or just take the recognisable float planes), apply
`.Czscale`=2^20, that is the per-pixel z increment; the base/C term is the plane's
value at the tile origin (still to be located in the stream). Then it is a plain
`igc_array.py` z-plane.

## Plane constants are fixed-point screen coordinates

The edge payloads' non-float words carry the plane's constant/vertex terms as
**fixed-point screen coordinates** (`scratchpad/edge_decode.py`):

```
SEND(4) edge @0x08015000:  00000100  3e013991(A=0.1262)  0000ec00  00000000
                                                          ^ 0xec00 = 60416 = 236.0 * 256
SEND(0x21) @0x08015260:    … 0000ec00 (=236.0)  0000b53a (=181.2) …
```

`0x0000ec00 / 256 = 236.0` = a screen-x right in the object's x[126,255] range
(first captured vertex was x≈237.5). So the constant term C is stored as a `.8`
fixed-point coordinate (word/256), not an IEEE float — which is why it wasn't in
the float list. SEND(0x29) is a long single-coefficient sweep (`-0.0626` repeated
~30x across bit-planes = the coarse interpolant). This locates the last missing
piece for edge reconstruction: A/B slope (float, verified 0.2%) + C (fixed-point
coord). Remaining is pairing them per triangle + all-regions assembly.

## Full-frame structure: double-buffered primitives across 105 tiles

`scratchpad/frame_primitives.py` captures every coefficient-copy word over the
draw and decodes the opcode mix: **1051 SEND, 334 SENDE, 384 TILE, 327 GOTO,
231 STOP** over 105 distinct TILE ids. But only **two** distinct SEND payload
addresses appear (0x08015xxx and 0x08017xxx), each with the identical 4/69/33/41
size profile. That is **double-buffering**: the firmware compiles one primitive's
micro-code into block A, SENDs it to every tile it covers, compiles the next
primitive into block B, SENDs that, and reuses A for the third — so the *content*
at those two addresses changes over time while the addresses don't.

Consequence for a from-scratch full frame: enumerating payload *addresses* is not
enough (only 2). Each primitive must be captured **at the moment its SEND fires**
(hook the SEND, snapshot the payload before the buffer is overwritten), then all
of them run tile-by-tile through `igc_array.py`. The frame is many primitives, not
two — object + terrain, z-buffered across ~105 tiles.

## Attempt: reconstruct frame geometry from payload coords — DID NOT WORK

`scratchpad/frame_geometry.py` hooks the coeff-copy, snapshots each SEND payload
as it's referenced (deduped by content), and extracts fixed-point screen coords
(words <0x10000 with value/256 in screen range). Honest outcome (run to cmd 2345):
**5 distinct primitives, only 11 coords, all clustered x∈[66,236] = the object**,
no terrain, far too sparse to rebuild triangles. The recovered values (236.0,
181.2, 65.5) are edge *constants*, not vertex lists — the payload does NOT store
extractable per-vertex geometry; it stores compiled edge/plane coefficients whose
constants happen to be a couple of coords. So "grep the coords and plot" is a dead
end: a real from-scratch render needs the full plane-role assembly (pair each
edge's slope+constant into a line, group 3 lines into a triangle, add z+color)
run through `igc_array.py` — the coefficients are all decoded and verified, but
assembling them into primitives is non-trivial and unsolved. Negative result kept
so the next session doesn't repeat the coord-extraction shortcut.

## What this changes

The micro-code decode is now **extraction + bit-serial execution**, not blind
ISA reversing:
1. parse the payload into `{op-header, float, bit-addr, len}` instructions,
2. map each float to its plane role (edge A/B/C, z, r/g/b) by position,
3. drive `igc_array.py`'s pixel-memory with the real coefficients per tile
   (the array already does eval_ltree + z-buffer + readout).

Blocker to a clean full decode: `igc_opco.h` (the opcode encoding header,
`\projects\dbi0150\dbi0151\ucode\igc_opco.h`) is **not in the dump** — the
`00000100` / `0x3a..` control-word field layout has to be reversed from these
examples + `IGCOPS.C` op semantics + the emit sites in `EOF.S`/`PXPL5OK.SS`.

## Next session
- Reverse the control-word layout (header `00000100`; the `..3a` / `0x21` fields
  = op + bit-address + length) from the SENDE sweep (cleanest, most regular).
- Extract the object's edge+z+colour floats, feed `igc_array.py`, confirm it
  reproduces the object from the *real* coefficients (not the geometry-derived ones).
- Then walk every region's DMA list, run all payloads tile-by-tile → full frame.
- Tools: `scratchpad/coefdump.py` (DMA lists), `scratchpad/payload_dump.py`
  (payload floats). Restore from `scratchpad/snapv2.pkl` (cmd 735 death-cam).