TeslaRel410/emulator/firmware-decomp/IGC-ENCODING-DERIVATION.md

IGC instruction-word encoding — derivation from EOF.C ↔ EOF.S (2026-07-17)

Goal: the Tier-1 decoder (coefficient stream → pixels). igc_opco.h (the macro definitions) is NOT in the dump — but sda4/DPL3/VRENDER/PXPL5SUP/ has both EOF.C (ordered IGC_* macro calls) and EOF.S (its PGC-compiled output with every emitted literal visible). Aligning them derives each macro's word template. This supersedes blind reversing; MICROCODE-DECODE-NOTES.md has the value layer (x2 doubling chains, 4-word SENDE stride, fixed-point constants) already decoded.

Derived so far (from _init_screenbin, EOF.S lines 330-510 ↔ EOF.C 269-360)

macro	emitted words	encoding
IGC_SETENABS	1	0x00000100
IGC_MEMintoENAB(ix)	1	0x0300 | ix
IGC_ENABxoreqMEM(ix)	1	0x10A00 | ix (bit16 set)
IGC_ENABintoMEM(ix)	1	0xB500 | ix
IGC_TREEintoMEM_L3(dst,len,A,B,C)	4	{hdr, A.f32, B.f32, C.f32}

TREE header samples: (dst=57,len=7) → 0x3d2a4339; (dst=64,len=15) → 0x412a4340.

• bits 0-7 = dst bit-address (0x39=57 ✓, 0x40=64 ✓)
• bits 8-15 = op code 0x43 (cf. 0x3a in the captured SENDE sweep = the MEMpluseqMEM-family op; 0x03/0xB5/0x0A+bit16 above — op byte is bits 8-15)
• bits 16-23 = 0x2a in both (probably format/variant field for _L3)
• bits 24-31 = 0x3d vs 0x41 for len 7 vs 15 — length-derived, exact formula needs more samples (Δ=4 for Δlen=8 → maybe (len>>1)+base? PIN WITH MINER).

Also from the same region: the coeff stream is written via st.l/fst.l through the rolling pointer; float args go through .C00741-style data literals (= the float constants, e.g. -1.0f, 1.0f) — EOF.S shows them as fld.l l%.C00741; read the .data section at the end of EOF.S for their values.

The captured-stream correspondence (already verified earlier)

• SENDE z/colour sweep instruction (4 words): {inc.f32, 00 LL 3a AA, place-value.f32, 000000NN} → op 0x3a at bits 8-15 of word1, LL=countdown at bits 16-23, AA=src addr bits 0-7. This is consistent with the header field layout above (op byte = bits 8-15).
• 0x00000100 recurs as "header" in captured payloads = SETENABS (or the 1-word op family with op=0x01 at bits 8-15).

Key sources

• sda4/DPL3/VRENDER/PXPL5SUP/EOF.C — macro call sequences (init_screenbin @224, linterp @396 = MEMpluseqMEM samples, multuu_unc @451, send_em @499, perspective_divides @592 has TREEgeZERO/ltZERO/TREEintoMEM_C1/SCAintoMEM_S1/ MEMintoENAB/CLEAR samples, texture path further down).
• sda4/DPL3/VRENDER/PXPL5SUP/EOF.S — compiled, all literals visible (_init_screenbin @330, _send_em @1442, _configEMCs @221/@58).
• DIVPXMAP.H — dvpx_* bit map: io=0(32b), texz=32(20b), opacity=52(5b), texu=57(20b), texv=77(20b), zbuf=97(20b), r24=117 g24=125 b24=133, scalar=141(13b: texsize@141/2,texid@143/6,rampsel@149/2,texmode@151/3), enblpush=154, eof block @160+ (fog=160/8, subu=168/5, subv=173/5, ramp=178/2, mode=180/3...).
• GOODEQNS.C — edgeize/planarize/binitize math + binchunk DMA layout (BIN_FULL=63*2, {addr, count|opcode} 64-bit pairs, GOTO chaining).
• NUREGMAP.SS — dpl_REMOTE_VERTEX (80B: pos@48, normcol@64, tex@32) and dpl_REMOTE_CONNECTION (next@0, n_verts@4, indices[6]@8, planeEqn@32, rgb@48).
• FOOTER.SS — scales: .Czscale=0x497fffff≈2^20, .Ctexscale=0x477fffff≈2^16, Cturn_z_to_tex(=5.1118e5, /4, /8 variants).
• IGCOPS.C — op vocabulary + pixel-memory semantics (read/write_pixmem_word, eval_ltree=int(Ax+By+C)).
• PXPL5001/2.DOC (WinWord2) — design notes: flat-shaded textured quad packet = edge×4, plane Z/S/T/MIP, const colour/type (~25 regs); texturing math.

Miner results (eofs_mine.py, round 1 — scratchpad, uses EOF.S // lineno: markers)

macro	words	encoding (op byte = bits 8-15 unless noted)
IGC_NOOP	1	0x00000000
IGC_FBITS(15)	2	{0x80000000, 0x48000000} (n=15 packing TBD — need a 2nd sample)
IGC_SETENABS	1	0x00000100
IGC_MEMintoENAB(x)	1	0x0300 | x (confirmed symbolically: rN&0xff|0x0300)
IGC_MEMBARintoENAB(x)	1	0x4800 | x (NEW — linterp line 426)
IGC_ENABxoreqMEM(x)	1	0x10A00 | x
IGC_ENABintoMEM(x)	1	0xB500 | x
IGC_TREEintoMEM_L3(d,l,A,B,C)	4	{hdr, A.f32, B.f32, C.f32}; hdr bits0-7=d, bits8-15=0x43, bits16-23=0x2a, bits24-31=0x39+ceil(l/2) (fits l=5:0x3c, 7:0x3d, 15:0x41)
IGC_CPY(d,s,l)	2	{0x80|((0x39+ceil(l/2))<<24) | 0x4c00 | d, s} (sample d=0x34,s=0x40,l=5 → 0xbc004c34, 0x40)
IGC_MEMgeSCA_S1(d,l,sca)	2	sample → {0xbc916c00, 0x34} (op 0x6c; hdr low byte NOT dst here — per-op layouts differ)
IGC_SCAintoMEM_S1(d,l,sca)	2	sample → {0x3c90f734, 0x1d} (dst 0x34 bits0-7, operand word = scalar 29)
DMA SEND(n)	—	0x10000000 | n, chunked at 127 longwords (send_em)

Byte 24-31 = 0x39+ceil(len/2) looks like the bit-serial cycle count (2 bits/clock)

• 0x80 flag on the enable-conditioned (S1?) forms. Bits 16-23 vary per op (0x2a TREE / 0x00 CPY / 0x91 geSCA / 0x90 SCAinto) — likely aux operand/format. Word-constructor macros also exist (Ix_TBLENTRY_S1, P_TBLENTRY — EOF.C:1104) = more single-word samples in EOF.S.

THE ENCODING FORMULA (cracked 2026-07-17 — PXPL5OPT.S:1649, expanded macro in the clear)

_zbuffer_fn (PXPL5SUP/PXPL5OPT.S line 1649) contains the fully-expanded constructor:

( ( 0x422100 | ((addr & 0xff) << 0) | (((len+2)+115 & 0xff) << 23) ) |(2<<18)|(2<<20) )

Universal IGC instruction-word template:

• bits 0-7 = operand bit-plane address
• bits 8-15 = opcode (0x21=MEMltTREE, 0x43=TREEintoMEM, 0x03=MEMintoENAB, 0x48=MEMBARintoENAB, 0xB5=ENABintoMEM, 0x4c=CPY, 0x6c=MEMgeSCA, 0x01=SETENABS...)
• bits 16-22 = aux/format field (0x2a for TREE_L3, 0x42 for MEMltTREE(+flag bits 18-21 e.g. (2<<18)|(2<<20)), 0x00 CPY, ...)
• bits 23-30 = (len + 115) [zbuffer uses len+2+115] — VERIFIED: TREE l=7→0x3D..., l=15→0x41..., CPY l=5→0x3C...
• bit 31 = flag on the S1/enable-conditioned forms (CPY sample had it)

Edge headers are tiny constants: 0x601, 0x602, 0x603 (edgize_tri_fn: edge 1/2/3, each followed by A,B,C floats — 4-word instructions). Suffix system: _L3 = +3 coeff floats; _L0 = 0 args (reuses the live tree state); _C1 = +1 const; _S1 = +1 scalar. The tree is loaded by one instruction and REUSED by the next (z-compare loads the z plane; z-write is a bare 1-word TREEintoMEM_L0).

The triangle packet (tri_zb_f, PXPL5OK.SS:1063): 3× edge{hdr,A,B,C} → z-test {Ix_MEMltTREE_L3(texz? zbuf,20), zA,zB,zC} → z-write {Ix_TREEintoMEM_L0} → 3× colour {Ix_TREEclmpintoMEM_C1(r/g/b24,8), P_TREEclmpintoMEM(...), col.f32} → {Ix_SCAintoMEM_S1(scalar,13), material.f32} → 0-pad. C-callable wrappers (PXPL5TRI.S) call edgize_tri_fn + zbuffer_fn + planarize_fn(0x666, vert-field-idx).

Harvest sources (expanded, numeric): PXPL5SUP/PXPL5OPT.S (edgize@1492, zbuffer@1646, planarize@1743, preplanarize@1137) + PXPL5SUP/PXPL5TRI.S + parent PXPL5OPT.S (rev differs, both useful) + EOF.S. Grep pattern: 0x[0-9a-f]{4,6} \| parenthesized expressions — eval them with the known (op,addr,len) from the .SS source lines to fill the whole op table.

The bit-serial SWEEP family (firmware's builder) — 2-word format DERIVED

The firmware's own packet builder (and EOF.C's linterp/multuu_unc) emit 2-word memory-op instructions. From _linterp compiled (EOF.S 663-860):

op-word  = BASE | dstaddr | ((len1+116)&0x7f)<<23      (BASE e.g. 0x80006c00 = MEMpluseqMEM-family K)
operand  = srcaddr | dstaddr<<8 | (len2&0x7f)<<16

VERIFIED against capture: {0xba01253a, 0x00143a21} → op 0x25 dst=58, operand src=0x21(33) dst=0x3a(58)✓ len=0x14(20). The 0x48-family builds as (len+116)<<23 | 0x4800 | addr (linterp line 699-707, emitted right after SETENABS). 104192 = 0x19700 = the 0x97-family base (bit16 set) — captured 0x0001979d = 0x19700|0x9d ✓; bare 0x0001008f = bit16 operand words. CPY 2-word pairs in the eof blocks: {0xbb004cb3, 0x0001008f} = CPY(dst=179, src=143=texid) etc. Known family bases so far: 0x25??, 0x21 (with decrementing len = the multuu cascade), 0x6c (K=0x80006c00), 0x4c (CPY), 0x48, 0x97(+bit16), 0x1f, 0xfa, 0x39, 0xec (last four TBD — likely SHIFTL/TBLENTRY/OVFIX/SPLAT-family from IGCOPS.C).

The 69-word SENDE block structure: SETENABS + 3-word lead-in + 16 pairs of {0x25-op, operand}/{0x21-op, operand} with len1 decrementing 9..0 and src walking 0x21..0x31 = a bit-serial multiply cascade (multuu_unc's exact shape: IGC_MEMpluseqMEM(res+j, Ub, Rlen-j, Ublen)).

Builder-trace tooling: scratchpad/builder_trace.py logs (pc, addr, val) for all firmware writes into 0x08015000-0x08015800 during cap7 build → writer pc histogram names the firmware's builder fns for disassembly.

FIRMWARE SWEEP EMITTER READ (builder trace + disasm @0xf041db90-dc50) — the

"x2 doubling chain" was an ARTIFACT, not data

builder_trace.py pinned the SENDE(69) emitter (writes at cmd 737 = draw#1): loop constants r9 = 0x80012500|dst|(116<<23) (= 0xba01253a for dst=0x3a), r10 = 0x80012100|dst, r8 = dst<<8. Per bit k (k=0..19, 4 words):

w0 = 0x80012100 | dst | (((136-k)&0x7f)<<23)   ; op 0x21 aux 1, len-field decrementing
w1 = src+k                                      ; bare operand word
w2 = 0x80012500 | dst | (116<<23)               ; op 0x25 aux 1, len=0 (constant)
w3 = (src+k) | dst<<8 | ((20-k)<<16)            ; operand: src | dst<<8 | len<<16

The len-field (136-k) walks straight through the IEEE exponent bits, so w0 "decodes" as a float that halves each step — the earlier doubling-chain reading (MICROCODE-DECODE-NOTES.md) was a coincidence artifact. These words are INSTRUCTIONS, not coefficients. The SENDE(69) is a fixed bit-serial transform program: src bits 33..52 (texz) → dst bit 58 (texu region) — per-frame plumbing, not per-triangle data. The real primitive coefficients live in the SEND(33)/ SEND(41) blocks (builders = the 0xf04126xx cluster, 336-344 writes each) and the SEND(4) edge block (0xf041fc64/fc84/fc9c; word1 0x3e013991 computed = a real float, word2 0xec00 = fixed-point .8 coordinate 236.0).

Lead-in confirmed: {0x100 SETENABS, 0x3a804834 = op 0x48 addr 52 (opacity) len 1 = the 50% stipple enable}.

NEXT for the decoder: (1) disassemble the 0xf04126xx builders (the 33/41-block emitters) the same way — builder_trace.py already exists, just widen the range / dump more words; (2) implement the sweep ops (0x21/0x25 pair = bit-serial add/carry per IGCOPS.C MEMpluseqMEM semantics) + run the whole per-tile program in igc_exec; (3) bars.

GOLDMINE: PXPL5SUP/ADDR + PXPL5SUP/DUMP (found 2026-07-17 late)

ADDR = a literal fragment of the missing igc_opco.h — exact bases: I_MCWRITE=0x20000|(a&0x1ff)<<8, I_MCREAD=(a&0x1ff)<<8, MEMintoENAB=0x300, ENABandeqMEM=0x500, ENABandeqMEMBAR=0x800, SEDGE=0x400a00, CRYintoMEM=0xb300, ENABintoMEM=0xb500, MEMoreqENAB=0xb700, MEMandeqENAB=0xb900, OVFIX=0x8000e600, ENABxoreqMEM=0x10a00, MEMEDGE=0x413c00, SEDGEBAR=0x413f00 (+ P_* second-word forms: bare (addr&0xff)).

DUMP = pxpl5tst run log that PRINTS the op table with names: SETENABS=0x100, CLRENABS=0x200, TREEltZERO_L3=0x3ae94200, TREEgeZERO_L3=0x3ae80d00, MEMltTREE_L3=0x44ea2120(texz)/0x...61(zbuf), TREEintoMEM_L0(zbuf)=0x438a4320, TREEintoMEM_L3: diff=0x3daa4352 spec=0x3daa435a texu=0x41aa4362 texv=0x41aa4372 texz=0x41aa4382 — plus TWO complete live triangle packets word-by-word (edges {0x3ae94200,A,B,C}×3 with real coefficients, z-test 4W, z-write 1W, diff/spec/texu/texv/texz planes 4W each, SCAintoMEM 0x0910f734+1.0). SUPCODES = the emission-sequence listing.

RETROACTIVE UNIFICATION: the old tri_recover stride-0x10 groups' "scale ≈0.00178" IS 0x3ae94200 read as a float — those DRAM groups were always {TREEltZERO_L3, A, B, C} edge instructions. The direct-float DPL3 packet format (already in igc_exec.py) is what per-triangle payloads use; the fixed 33/41/69-word blocks are the eof/background program (bars). Remaining unnamed: the eof-block ops 0xfa/0x7c/0x1f/0xf2/0x97/0x05/0x49/0x30/0x75/0xdb (builder = one linear fn 0xf041ee30-0xf041f7b0, per-word pcs logged in builder_trace2.log — disasm each site to name them).

NEXT (the miner)

Write eofs_mine.py: parse EOF.S per function; track st.l/fst.l stores through the coeff pointer; recover, in order, each emitted word (int literals from or/orh pairs; floats from the fld of .data literals — parse EOF.S's .data tail for values). Align against EOF.C's macro sequence per function (start with init_screenbin, perspective_divides, linterp — together they cover: FBITS, NOOP, TREEintoMEM_L3/_C1, TREEgeZERO_L3, TREEltZERO_L3, MEMintoENAB, ENABxoreqMEM, ENABintoMEM, SETENABS, CPY, MEMgeSCA_S1, SCAintoMEM_S1, CLEAR, MEMpluseqMEM, MEMintoENAB, SHIFTL-family, send_em's DMA emit). Output: the op table (op byte, word count, arg-field packing). Then:

1. parse captured payloads (fxtest_frame.pkl / cap7 bench) into instruction sequences with the table — every word must decode (acceptance: 0 unknown ops);
2. execute per-tile via igc_array.py (pixel-memory model exists there);
3. acceptance 1 = SMPTE bars from the cap7 bench stream; acceptance 2 = the fxtest asset frame.