wip: starting to review and update lua metaprogram with more modeling of gte.

code/duffle/gte.h

@@ -191,6 +191,30 @@ enum {
 	gte_mask_fake_cmd  = 0x1F,
 };
 
+/* --- GTE Control Register Aliases (Pitfall 1) ---
+ * Three pairs of aliases map to the SAME C2 control-register slot on real silicon:
+ *   C2[24] = gte_cr_RBK (background R)         | gte_cr_OFX (screen offset X)
+ *   C2[25] = gte_cr_GBK (background G)         | gte_cr_OFY (screen offset Y)
+ *   C2[26] = gte_cr_BBK (background B)         | gte_cr_H   (projection plane distance H)
+ * Cross-alias writes inside one atom body, or across the wave-context boundary,
+ * silently clobber each other. The metaprogram's check_gte_cr_alias_writes
+ * (CHECK_RULES row) warns about each pair per source. See
+ * docs/gte_reference.md §"Control-register alias table" for the silicon
+ * rationale and the libgte outer-product convention.
+ */
+
+/* --- RT-matrix packed-slot convention (Pitfall 4) ---
+ * The silicon packs two 16-bit RT elements per 32-bit C2 slot:
+ *   C2[2] = (RT22 << 16) | RT13       (gte_cr_RT13 writes the low  half, gte_cr_RT22 writes the high half)
+ *   C2[4] = (RT33 << 16) | RT22       (gte_cr_RT22 writes the low  half — clobbers prior RT22 value if RT13 was also written)
+ * OP and MVMVA read D1/D2/D3 from these packed slots. The libgte outer-product
+ * convention (see ac_apply_matrix_lv at gte.atom.c:108-122) writes C2[2] then
+ * C2[4] in sequence; the SECOND write's low half is RT22, not RT13. An agent
+ * who writes gte_cr_RT13 then gte_cr_RT22 to the SAME source GPR clobbers the
+ * RT13 value. See docs/gte_reference.md §"RT-matrix packed-slot convention"
+ * for the canonical write pattern.
+ */
+
 /* --- GTE Control Register Indices (for ctc2/cfc2) ---
  * Preprocessor-visible integer ids for the COP2 control register file.
  * Each enum value is bound to a parallel `_Code` `#define` so the preprocessor can stringify the integer (for `reg_str`/`rgcc` paths).

code/duffle/lottes_tape.h

@@ -103,7 +103,15 @@ enum {
 typedef U4 const MipsCode; // Underlying type to mips asm words.
 typedef Slice_(MipsCode);
 
-typedef U4 const MipsAtom; // Underlying type to an array of mips asm words that must terminate with an ac_yield.
+typedef U4 const MipsAtom; 
+typedef Slice_(MipsAtom); 
+// Sometimes a user will define a bundle of atoms that represent a procedure of work as:
+//   MipsAtom* <identifier>[...];
+// Unfortuantely if using slice_from_array it will make the slice's pointer: MipsAtom** so this enforce its defined as MipsAtom*
+// TODO(Ed): Alternatively we can make the MipsAtom an opaque pointer to the atom... so that the blow returns 'MipsAtom'.
+#define atombundle_from_array(array) (Slice_MipsAtom){.ptr=array[0],.len=Array_len(array)}
+
+// Underlying type to an ptr to an array of mips asm words that must terminate with an ac_yield.
 #define MipsAtom_(sym) MipsCode sym [] align_(4) =
 
 // Used for atoms with value-args
@@ -139,7 +147,7 @@ typedef U4 const MipsAtom; // Underlying type to an array of mips asm words that
 	 (the identifier embeds the source line, so duplicates across `#include`d files don't collide). */
 #define ATOM_FILE_DEBUGGER_LINE_MARKER(file_name) internal U4 const tmpl(atom_file_debugger_line_marker,file_name) = 0
 
- typedef Slice_(MipsAtom); typedef Slice_MipsAtom Tape;
+typedef Slice_MipsAtom Tape;
 
 /* The 'Exit' Atom */
 atom_dbg_skip MipsAtom_(tape_exit) { jump_reg(rret_addr), nop };
@@ -276,6 +284,34 @@ FI_ MipsAtom* atomarena_push(AtomArena_R aa, Slice_MipsCode code) {
 FI_ void atomarena_reset(AtomArena_R aa) { aa->used = 0; }
 #pragma region Atom Arena
 
+#pragma region RegFile (Register File Allocator)
+// A specialized allocator utilized to help the user track which registers are bound to values
+// that must be preserved for the arena's bounds.
+
+enum {
+	RegFileArena_Len,
+};
+typedef Enum_(U4, RegFileEntry) {
+	// TODO(Ed): Define RF_Field, each field is maped by index + bit pos.
+	// the index is the upper portion of a U4 and the bit pos in the lower pos.
+
+	regfileentry_todo_,
+	// TODO(Ed): Is there a trick we can do with the current register enums to 
+	// just resolve an entry automatically when doing a pin?
+};
+typedef Struct_(RegFile) {
+	U1 GPR[RegFileArena_Len];
+	U1 GTE[RegFileArena_Len];
+	U1 GP[RegFileArena_Len];
+};
+
+void regfile_pin(U4 register) {
+
+	assert(false);
+}
+
+#pragma endregion RegFileArena (Register File Allocator)
+
 #pragma region Mips Atom Procs
 
 #pragma endregion Mips Atom Procs