TODO: need to review snapshot

code/duffle/atom_dsl.h

@@ -18,11 +18,13 @@
  *     - atom word-counts in word_counts.metadata.h agree with the body's
  *       actual .word count.
  *
- *   WHY A PURE MACRO (atom_info, atom_bind, atom_reads, atom_writes, atom_label)
- *   -----------------------------------------------------------------
- *   Each of these expands to a C comment or to nothing. The C preprocessor
- *   strips them to whitespace. The metaprogram reads the literal token from
- *   source-as-written, NOT from the preprocessed output. This means:
+ *   WHY PURE MACROS
+ *   ---------------
+ *   atom_info, atom_bind, atom_reads, atom_writes, atom_label,
+ *   atom_dbg_skip_over each expand to a C comment or to nothing. The C
+ *   comment or to nothing. The C preprocessor strips them to whitespace.
+ *   The metaprogram reads the literal tokens from source-as-written, NOT from
+ *   the preprocessed output. This means:
  *     - the C compiler does no work for them (no __attribute__, no
  *       _Pragma, no asm side-effects)
  *     - they can never silently drift from the metaprogram's view
@@ -150,6 +152,20 @@
  * ============================================================================*/
 #define atom_info(...)  /* atom_info(__VA_ARGS__) */
 
+/* ----------------------------------------------------------------------------
+ * DEBUG SOURCE-STEP MARKERS
+ *
+ * Place atom_dbg_skip_over() before a MipsAtom_, MipsAtomComp_, or
+ * MipsAtomComp_Proc_ declaration. The following declaration kind determines
+ * whether the marker selects a whole atom or a component inline view. The
+ * source scanner associates the marker with that declaration; placement
+ * diagnostics are handled by the annotation pass.
+ *
+ * The macro expands to a comment only. It emits no C data or MIPS words and
+ * therefore cannot affect runtime output.
+ * ----------------------------------------------------------------------------*/
+#define atom_dbg_skip_over() /* atom_dbg_skip_over: skip the following atom or component source view */
+
 /* ----------------------------------------------------------------------------
  * atom_bind(Binds_X) -- rbind sub-call of atom_info
  *

code/duffle/gen/duffle.macs.h

@@ -23,7 +23,6 @@ WORD_COUNT(mac_yield, 4)
 ,	load_half_u(R_T2, R_FaceCursor, 2 * S_(S2))
 WORD_COUNT(mac_load_tri_indices, 3)
 
-/* Words: 18; Translates indices to vertex addresses and pushes them to GTE  */
 #define mac_gte_load_tri_verts(...) \
 	shift_lleft(R_AT, R_T0, v3s2_byteoff) \
 ,	add_u_self(R_AT, R_VertBase) \
@@ -77,7 +76,7 @@ WORD_COUNT(mac_insert_ot_tag_g4, 11)
 
 #define mac_pack_color_word(off, cmd, r, g, b) \
 	load_upper_i(R_AT, (cmd) << 8  | (b)) \
-,	or_i_self(   R_AT, ((g)   << 8) | (r)) \
+,	or_i_self(   R_AT, ((g)  << 8) | (r)) \
 ,	store_word(  R_AT, R_PrimCursor, (off))
 WORD_COUNT(mac_pack_color_word, 3)
 

code/duffle/lottes_tape.h

@@ -121,6 +121,7 @@ MipsAtomComp_(ac_load_tri_indices) {
 };
 
 /* Words: 18; Translates indices to vertex addresses and pushes them to GTE  */
+atom_dbg_skip_over()
 MipsAtomComp_(ac_gte_load_tri_verts) {
 	shift_lleft(R_AT, R_T0, v3s2_byteoff), add_u_self(R_AT, R_VertBase), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), gte_mv_to_data_r(R_V0, C2_VXY0), gte_mv_to_data_r(R_V1, C2_VZ0),
 	shift_lleft(R_AT, R_T1, v3s2_byteoff), add_u_self(R_AT, R_VertBase), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), gte_mv_to_data_r(R_V0, C2_VXY1), gte_mv_to_data_r(R_V1, C2_VZ1),
@@ -162,7 +163,7 @@ MipsAtomComp_(ac_insert_ot_tag_g4) {
 FI_ MipsAtom ac_pack_color_word(U4 off, U4 cmd, U1 r, U1 g, U1 b)
 MipsAtomComp_Proc_(ac_pack_color_word, {
 	load_upper_i(R_AT, (cmd) << 8  | (b)),
-	or_i_self(   R_AT, ((g)   << 8) | (r)),
+	or_i_self(   R_AT, ((g)  << 8) | (r)),
 	store_word(  R_AT, R_PrimCursor, (off)),
 })
 

code/gte_hello/hello_gte_tape.c

@@ -109,6 +109,7 @@ MipsAtom_(rbind_floor_f3_face) atom_info(atom_bind(Binds_FloorTri)
 };
 
 internal
+atom_dbg_skip_over()
 MipsAtom_(floor_f3_face) atom_info(
 	, atom_reads( R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 	, atom_writes(R_PrimCursor, R_FaceCursor)