Implemented statement comments. Assignments are working OK. Some are still thrown away during optimizations.

src/main/java/dk/camelot64/kickc/Compiler.java

@@ -1,5 +1,6 @@
 package dk.camelot64.kickc;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.CompileError;
 import dk.camelot64.kickc.model.Program;
 import dk.camelot64.kickc.model.StatementSequence;
@@ -121,7 +122,7 @@ public class Compiler {
          loadAndParseFile(fileName, program, currentPath.toPath());
 
          StatementSequence sequence = program.getStatementSequence();
-         sequence.addStatement(new StatementCall(null, "main", new ArrayList<>(), new StatementSource(RuleContext.EMPTY)));
+         sequence.addStatement(new StatementCall(null, "main", new ArrayList<>(), new StatementSource(RuleContext.EMPTY), Comment.NO_COMMENTS));
          program.setStatementSequence(sequence);
 
          pass1GenerateSSA();

src/main/java/dk/camelot64/kickc/model/Comment.java

@@ -1,5 +1,7 @@
 package dk.camelot64.kickc.model;
 
+import java.util.ArrayList;
+
 /**
  * A comment in the source code.
  * Comments are attached to symbols and statements and
@@ -7,6 +9,11 @@ package dk.camelot64.kickc.model;
  **/
 public class Comment {
 
+   /** Empty comments collection. */
+   public static final ArrayList<Comment> NO_COMMENTS = new ArrayList<>();
+
+
+   /** The comment. */
    private String comment;
 
    /** The index of the hidden parser token containing the comment.

src/main/java/dk/camelot64/kickc/model/ControlFlowBlock.java

@@ -204,7 +204,7 @@ public class ControlFlowBlock {
          phiBlock = (StatementPhiBlock) statements.get(0);
       }
       if(phiBlock == null) {
-         phiBlock = new StatementPhiBlock();
+         phiBlock = new StatementPhiBlock(new ArrayList<>());
          statements.add(0, phiBlock);
       }
       return phiBlock;

src/main/java/dk/camelot64/kickc/model/ControlFlowGraphCopyVisitor.java

@@ -124,9 +124,9 @@ public class ControlFlowGraphCopyVisitor extends ControlFlowGraphBaseVisitor<Obj
    }
 
    @Override
-   public StatementPhiBlock visitPhiBlock(StatementPhiBlock phi) {
-      StatementPhiBlock copyPhi = new StatementPhiBlock();
-      for(StatementPhiBlock.PhiVariable phiVariable : phi.getPhiVariables()) {
+   public StatementPhiBlock visitPhiBlock(StatementPhiBlock orig) {
+      StatementPhiBlock copyPhi = new StatementPhiBlock(orig.getComments());
+      for(StatementPhiBlock.PhiVariable phiVariable : orig.getPhiVariables()) {
          VariableRef variable = phiVariable.getVariable();
          StatementPhiBlock.PhiVariable copyVar = copyPhi.addPhiVariable(variable);
          for(StatementPhiBlock.PhiRValue phiRValue : phiVariable.getValues()) {
@@ -137,68 +137,64 @@ public class ControlFlowGraphCopyVisitor extends ControlFlowGraphBaseVisitor<Obj
    }
 
    @Override
-   public StatementAssignment visitAssignment(StatementAssignment origAssignment) {
-      LValue lValue = origAssignment.getlValue();
-      RValue rValue1 = origAssignment.getrValue1();
-      Operator operator = origAssignment.getOperator();
-      RValue rValue2 = origAssignment.getrValue2();
-      return new StatementAssignment(lValue, rValue1, operator, rValue2, origAssignment.getSource());
+   public StatementAssignment visitAssignment(StatementAssignment orig) {
+      return new StatementAssignment(orig.getlValue(), orig.getrValue1(), orig.getOperator(), orig.getrValue2(), orig.getSource(), orig.getComments());
    }
 
    @Override
-   public StatementConditionalJump visitConditionalJump(StatementConditionalJump origConditionalJump) {
-      RValue rValue1 = origConditionalJump.getrValue1();
-      Operator operator = origConditionalJump.getOperator();
-      RValue rValue2 = origConditionalJump.getrValue2();
-      LabelRef destination = origConditionalJump.getDestination();
-      StatementConditionalJump conditionalJump = new StatementConditionalJump(rValue1, operator, rValue2, destination, origConditionalJump.getSource());
-      conditionalJump.setDeclaredUnroll(origConditionalJump.isDeclaredUnroll());
+   public StatementConditionalJump visitConditionalJump(StatementConditionalJump orig) {
+      RValue rValue1 = orig.getrValue1();
+      Operator operator = orig.getOperator();
+      RValue rValue2 = orig.getrValue2();
+      LabelRef destination = orig.getDestination();
+      StatementConditionalJump conditionalJump = new StatementConditionalJump(rValue1, operator, rValue2, destination, orig.getSource(), orig.getComments());
+      conditionalJump.setDeclaredUnroll(orig.isDeclaredUnroll());
       return conditionalJump;
    }
 
    @Override
-   public StatementJump visitJump(StatementJump origJump) {
-      LabelRef destination = origJump.getDestination();
-      return new StatementJump(destination, origJump.getSource());
+   public StatementJump visitJump(StatementJump orig) {
+      LabelRef destination = orig.getDestination();
+      return new StatementJump(destination, orig.getSource(), orig.getComments());
    }
 
    @Override
-   public StatementLabel visitJumpTarget(StatementLabel origJump) {
-      LabelRef label = origJump.getLabel();
-      return new StatementLabel(label, origJump.getSource());
+   public StatementLabel visitJumpTarget(StatementLabel orig) {
+      LabelRef label = orig.getLabel();
+      return new StatementLabel(label, orig.getSource(), orig.getComments());
    }
 
    @Override
-   public StatementCall visitCall(StatementCall origCall) {
-      LValue lValue = origCall.getlValue();
-      String procedureName = origCall.getProcedureName();
-      List<RValue> parameters = origCall.getParameters();
-      return new StatementCall(lValue, procedureName, parameters, origCall.getSource());
+   public StatementCall visitCall(StatementCall orig) {
+      LValue lValue = orig.getlValue();
+      String procedureName = orig.getProcedureName();
+      List<RValue> parameters = orig.getParameters();
+      return new StatementCall(lValue, procedureName, parameters, orig.getSource(), orig.getComments());
    }
 
    @Override
-   public StatementProcedureBegin visitProcedureBegin(StatementProcedureBegin origProcedureBegin) {
-      return new StatementProcedureBegin(origProcedureBegin.getProcedure(), origProcedureBegin.getSource());
+   public StatementProcedureBegin visitProcedureBegin(StatementProcedureBegin orig) {
+      return new StatementProcedureBegin(orig.getProcedure(), orig.getSource(), orig.getComments());
    }
 
    @Override
-   public StatementProcedureEnd visitProcedureEnd(StatementProcedureEnd origProcedureEnd) {
-      return new StatementProcedureEnd(origProcedureEnd.getProcedure(), origProcedureEnd.getSource());
+   public StatementProcedureEnd visitProcedureEnd(StatementProcedureEnd orig) {
+      return new StatementProcedureEnd(orig.getProcedure(), orig.getSource(), orig.getComments());
    }
 
    @Override
-   public StatementReturn visitReturn(StatementReturn origReturn) {
-      return new StatementReturn(origReturn.getValue(), origReturn.getSource());
+   public StatementReturn visitReturn(StatementReturn orig) {
+      return new StatementReturn(orig.getValue(), orig.getSource(), orig.getComments());
    }
 
    @Override
-   public Object visitAsm(StatementAsm asm) {
-      return new StatementAsm(asm.getAsmLines(), asm.getSource());
+   public Object visitAsm(StatementAsm orig) {
+      return new StatementAsm(orig.getAsmLines(), orig.getSource(), orig.getComments());
    }
 
    @Override
-   public Object visitKickAsm(StatementKickAsm kasm) {
-      return new StatementKickAsm(kasm.getKickAsmCode(), kasm.getLocation(), kasm.getBytes(), kasm.getCycles(), kasm.getSource());
+   public Object visitKickAsm(StatementKickAsm orig) {
+      return new StatementKickAsm(orig.getKickAsmCode(), orig.getLocation(), orig.getBytes(), orig.getCycles(), orig.getSource(), orig.getComments());
    }
 
 }

src/main/java/dk/camelot64/kickc/model/statements/Statement.java

@@ -1,8 +1,11 @@
 package dk.camelot64.kickc.model.statements;
 
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.Program;
 
+import java.util.List;
+
 /**
  * Single Static Assignment Form Statement.
  * Intermediate form used for compiler optimization.
@@ -17,13 +20,16 @@ public interface Statement {
    /** Set the index of the statement. Indexes are used during live range analysis. */
    void setIndex(Integer idx);
 
-   /**
-    * Get the source for the statement
-    */
+   /** Get the source for the statement */
     StatementSource getSource();
 
-   /**
-    * Set the source for the statement
-    */
+   /** Set the source for the statement */
    void setSource(StatementSource source);
+
+   /** Get the comments  of the statement */
+   List<Comment> getComments();
+
+   /** Get the comments  of the statement */
+   void setComments(List<Comment> comments);
+
 }

src/main/java/dk/camelot64/kickc/model/statements/StatementAsm.java

@@ -1,17 +1,19 @@
 package dk.camelot64.kickc.model.statements;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.Program;
 import dk.camelot64.kickc.parser.KickCParser;
 
+import java.util.List;
+
 /** Inline ASM code */
 public class StatementAsm extends StatementBase {
 
    /** ASM Fragment code. */
    private KickCParser.AsmLinesContext asmLines;
 
-   public StatementAsm(KickCParser.AsmLinesContext asmLines,
-                       StatementSource source) {
-      super(null, source);
+   public StatementAsm(KickCParser.AsmLinesContext asmLines, StatementSource source, List<Comment> comments) {
+      super(null, source, comments);
       this.asmLines = asmLines;
    }
 

src/main/java/dk/camelot64/kickc/model/statements/StatementAssignment.java

@@ -1,11 +1,14 @@
 package dk.camelot64.kickc.model.statements;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.Program;
 import dk.camelot64.kickc.model.operators.Operator;
 import dk.camelot64.kickc.model.values.LValue;
 import dk.camelot64.kickc.model.values.RValue;
 import dk.camelot64.kickc.model.symbols.Variable;
 
+import java.util.List;
+
 /**
  * Single Static Assignment Form Statement.
  * Intermediate form used for compiler optimization.
@@ -22,16 +25,16 @@ public class StatementAssignment extends StatementBase implements StatementLValu
    private Operator operator;
    private RValue rValue2;
 
-   public StatementAssignment(LValue lValue, RValue rValue2, StatementSource source) {
-      this(lValue, null, null, rValue2, null, source);
+   public StatementAssignment(LValue lValue, RValue rValue2, StatementSource source, List<Comment> comments) {
+      this(lValue, null, null, rValue2, null, source, comments);
    }
 
-   public StatementAssignment(LValue lValue, Operator operator, RValue rValue2,StatementSource source) {
-      this(lValue, null, operator, rValue2, null, source);
+   public StatementAssignment(LValue lValue, Operator operator, RValue rValue2,StatementSource source, List<Comment> comments) {
+      this(lValue, null, operator, rValue2, null, source, comments);
    }
 
-   public StatementAssignment(LValue lValue, RValue rValue1, Operator operator, RValue rValue2, StatementSource source) {
-      this(lValue, rValue1, operator, rValue2, null, source);
+   public StatementAssignment(LValue lValue, RValue rValue1, Operator operator, RValue rValue2, StatementSource source, List<Comment> comments) {
+      this(lValue, rValue1, operator, rValue2, null, source, comments);
    }
 
    public StatementAssignment(
@@ -40,8 +43,9 @@ public class StatementAssignment extends StatementBase implements StatementLValu
          Operator operator,
          RValue rValue2,
          Integer index,
-         StatementSource source) {
-      super(index, source);
+         StatementSource source,
+         List<Comment> comments) {
+      super(index, source, comments);
       this.lValue = lValue;
       this.rValue1 = rValue1;
       this.operator = operator;

src/main/java/dk/camelot64/kickc/model/statements/StatementBase.java

@@ -1,9 +1,6 @@
 package dk.camelot64.kickc.model.statements;
 
-import dk.camelot64.kickc.model.CallGraph;
-import dk.camelot64.kickc.model.LiveRangeVariables;
-import dk.camelot64.kickc.model.LiveRangeVariablesEffective;
-import dk.camelot64.kickc.model.Program;
+import dk.camelot64.kickc.model.*;
 import dk.camelot64.kickc.model.values.VariableRef;
 
 import java.util.Collection;
@@ -16,9 +13,13 @@ public abstract class StatementBase implements Statement {
 
    private Integer index;
 
-   public StatementBase(Integer index, StatementSource source) {
+   /** Comments preceding the statement in the source code. */
+   private List<Comment> comments;
+
+   public StatementBase(Integer index, StatementSource source, List<Comment> comments) {
       this.index = index;
       this.source = source;
+      this.comments = comments;
    }
 
    @Override
@@ -41,6 +42,16 @@ public abstract class StatementBase implements Statement {
       this.index = index;
    }
 
+   @Override
+   public List<Comment> getComments() {
+      return comments;
+   }
+
+   @Override
+   public void setComments(List<Comment> comments) {
+      this.comments = comments;
+   }
+
    @Override
    public boolean equals(Object o) {
       if(this == o) return true;

src/main/java/dk/camelot64/kickc/model/statements/StatementCall.java

@@ -1,5 +1,6 @@
 package dk.camelot64.kickc.model.statements;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.values.ProcedureRef;
 import dk.camelot64.kickc.model.Program;
 import dk.camelot64.kickc.model.values.LValue;
@@ -22,8 +23,8 @@ public class StatementCall extends StatementBase implements StatementLValue {
    private ProcedureRef procedure;
    private List<RValue> parameters;
 
-   public StatementCall(LValue lValue, String procedureName, List<RValue> parameters, StatementSource source) {
-      super(null, source);
+   public StatementCall(LValue lValue, String procedureName, List<RValue> parameters, StatementSource source, List<Comment> comments) {
+      super(null, source, comments);
       this.lValue = lValue;
       this.procedureName = procedureName;
       this.parameters = parameters;

src/main/java/dk/camelot64/kickc/model/statements/StatementConditionalJump.java

@@ -1,10 +1,13 @@
 package dk.camelot64.kickc.model.statements;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.values.LabelRef;
 import dk.camelot64.kickc.model.Program;
 import dk.camelot64.kickc.model.operators.Operator;
 import dk.camelot64.kickc.model.values.RValue;
 
+import java.util.List;
+
 /**
  * SSA form conditional jump. Intermediate form used for compiler optimization.
  * <br>
@@ -23,8 +26,8 @@ public class StatementConditionalJump extends StatementBase {
    /** This conditional has been unrolled. Constant propagation must ensure the conditional is deleted - or the compilation will fail. */
    private boolean wasUnrolled;
 
-   public StatementConditionalJump(RValue condition, LabelRef destination,StatementSource source) {
-      super(null, source);
+   public StatementConditionalJump(RValue condition, LabelRef destination,StatementSource source, List<Comment> comments) {
+      super(null, source, comments);
       this.rValue1 = null;
       this.operator = null;
       this.rValue2 = condition;
@@ -36,8 +39,9 @@ public class StatementConditionalJump extends StatementBase {
          Operator operator,
          RValue rValue2,
          LabelRef destination,
-         StatementSource source) {
-      super(null, source);
+         StatementSource source,
+         List<Comment> comments) {
+      super(null, source, comments);
       this.rValue1 = rValue1;
       this.operator = operator;
       this.rValue2 = rValue2;

src/main/java/dk/camelot64/kickc/model/statements/StatementJump.java

@@ -1,8 +1,11 @@
 package dk.camelot64.kickc.model.statements;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.values.LabelRef;
 import dk.camelot64.kickc.model.Program;
 
+import java.util.List;
+
 /**
  * Single Static Assignment Form Statement unconditional jump.
  * Intermediate form used for compiler optimization.
@@ -13,9 +16,8 @@ public class StatementJump extends StatementBase {
 
    private LabelRef destination;
 
-   public StatementJump(LabelRef destination,
-                        StatementSource source) {
-      super(null, source);
+   public StatementJump(LabelRef destination, StatementSource source, List<Comment> comments) {
+      super(null, source, comments);
       this.destination = destination;
    }
 

src/main/java/dk/camelot64/kickc/model/statements/StatementKickAsm.java

@@ -1,8 +1,11 @@
 package dk.camelot64.kickc.model.statements;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.Program;
 import dk.camelot64.kickc.model.values.RValue;
 
+import java.util.List;
+
 /** Inline KickAssembler code */
 public class StatementKickAsm extends StatementBase {
 
@@ -16,13 +19,13 @@ public class StatementKickAsm extends StatementBase {
    /** The number of cycles used by the generated kick-assembler code. */
    private RValue cycles;
 
-   public StatementKickAsm(String kickAsmCode, StatementSource source) {
-      super(null, source);
+   public StatementKickAsm(String kickAsmCode, StatementSource source, List<Comment> comments) {
+      super(null, source, comments);
       this.kickAsmCode = kickAsmCode;
    }
 
-   public StatementKickAsm(String kickAsmCode, RValue location, RValue bytes, RValue cycles, StatementSource source) {
-      super(null, source);
+   public StatementKickAsm(String kickAsmCode, RValue location, RValue bytes, RValue cycles, StatementSource source, List<Comment> comments) {
+      super(null, source, comments);
       this.kickAsmCode = kickAsmCode;
       this.location = location;
       this.bytes = bytes;

src/main/java/dk/camelot64/kickc/model/statements/StatementLabel.java

@@ -1,8 +1,12 @@
 package dk.camelot64.kickc.model.statements;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.values.LabelRef;
 import dk.camelot64.kickc.model.Program;
 
+import java.util.ArrayList;
+import java.util.List;
+
 /**
  * Single Static Assignment Form Statement Jump target.
  */
@@ -10,9 +14,8 @@ public class StatementLabel extends StatementBase {
 
    private LabelRef label;
 
-   public StatementLabel(LabelRef label,
-                         StatementSource source) {
-      super(null, source);
+   public StatementLabel(LabelRef label, StatementSource source, List<Comment> comments) {
+      super(null, source, comments);
       this.label = label;
    }
 

src/main/java/dk/camelot64/kickc/model/statements/StatementPhiBlock.java

@@ -1,5 +1,6 @@
 package dk.camelot64.kickc.model.statements;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.values.LabelRef;
 import dk.camelot64.kickc.model.Program;
 import dk.camelot64.kickc.model.values.RValue;
@@ -21,8 +22,8 @@ public class StatementPhiBlock extends StatementBase {
     */
    private List<PhiVariable> phiVariables;
 
-   public StatementPhiBlock() {
-      super(null, new StatementSource(RuleContext.EMPTY));
+   public StatementPhiBlock(List<Comment> comments) {
+      super(null, new StatementSource(RuleContext.EMPTY), comments);
       this.phiVariables = new ArrayList<>();
    }
 

src/main/java/dk/camelot64/kickc/model/statements/StatementProcedureBegin.java

@@ -1,8 +1,12 @@
 package dk.camelot64.kickc.model.statements;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.values.ProcedureRef;
 import dk.camelot64.kickc.model.Program;
 
+import java.util.ArrayList;
+import java.util.List;
+
 /** Procedure declaration in SSA */
 public class StatementProcedureBegin extends StatementBase {
 
@@ -10,8 +14,8 @@ public class StatementProcedureBegin extends StatementBase {
 
    private Strategy strategy;
 
-   public StatementProcedureBegin(ProcedureRef procedure,StatementSource source) {
-      super(null, source);
+   public StatementProcedureBegin(ProcedureRef procedure,StatementSource source, List<Comment> comments) {
+      super(null, source, comments);
       this.procedure = procedure;
    }
 

src/main/java/dk/camelot64/kickc/model/statements/StatementProcedureEnd.java

@@ -1,8 +1,11 @@
 package dk.camelot64.kickc.model.statements;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.values.ProcedureRef;
 import dk.camelot64.kickc.model.Program;
 
+import java.util.List;
+
 /**
  * Procedure declaration in SSA
  */
@@ -10,8 +13,8 @@ public class StatementProcedureEnd extends StatementBase {
 
    private ProcedureRef procedure;
 
-   public StatementProcedureEnd(ProcedureRef procedure, StatementSource source) {
-      super(null, source);
+   public StatementProcedureEnd(ProcedureRef procedure, StatementSource source, List<Comment> comments) {
+      super(null, source, comments);
       this.procedure = procedure;
    }
 

src/main/java/dk/camelot64/kickc/model/statements/StatementReturn.java

@@ -1,8 +1,11 @@
 package dk.camelot64.kickc.model.statements;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.Program;
 import dk.camelot64.kickc.model.values.RValue;
 
+import java.util.List;
+
 /**
  * Return Statement inside procedure in Single Static Assignment Form.
  */
@@ -13,8 +16,8 @@ public class StatementReturn extends StatementBase {
     */
    private RValue value;
 
-   public StatementReturn(RValue value, StatementSource source) {
-      super(null, source);
+   public StatementReturn(RValue value, StatementSource source, List<Comment> comments) {
+      super(null, source, comments);
       this.value = value;
    }
 

src/main/java/dk/camelot64/kickc/passes/Pass0GenerateStatementSequence.java

@@ -78,7 +78,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
    public Void visitFile(KickCParser.FileContext ctx) {
       if(program.getFileComments()==null) {
          // Only set program file level comments for the first file.
-         program.setFileComments(getCommentsFile(ctx));
+         program.setFileComments(ensureUnusedComments(getCommentsFile(ctx)));
       }
       this.visit(ctx.importSeq());
       this.visit(ctx.declSeq());
@@ -119,7 +119,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       String name = ctx.NAME().getText();
       Procedure procedure = getCurrentSymbols().addProcedure(name, type);
       addDirectives(procedure, ctx.directive());
-      procedure.setComments(getCommentsSymbol(ctx));
+      procedure.setComments(ensureUnusedComments(getCommentsSymbol(ctx)));
       scopeStack.push(procedure);
       Label procExit = procedure.addLabel(SymbolRef.PROCEXIT_BLOCK_NAME);
       VariableUnversioned returnVar = null;
@@ -131,21 +131,21 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
          parameterList = (List<Variable>) this.visit(ctx.parameterListDecl());
       }
       procedure.setParameters(parameterList);
-      sequence.addStatement(new StatementProcedureBegin(procedure.getRef(), new StatementSource(ctx)));
+      sequence.addStatement(new StatementProcedureBegin(procedure.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS));
       if(ctx.stmtSeq() != null) {
          this.visit(ctx.stmtSeq());
       }
-      sequence.addStatement(new StatementLabel(procExit.getRef(), new StatementSource(ctx)));
+      sequence.addStatement(new StatementLabel(procExit.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS));
       if(returnVar != null) {
-         sequence.addStatement(new StatementAssignment(returnVar.getRef(), returnVar.getRef(), new StatementSource(ctx)));
+         sequence.addStatement(new StatementAssignment(returnVar.getRef(), returnVar.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS));
       }
       VariableRef returnVarRef = null;
       if(returnVar != null) {
          returnVarRef = returnVar.getRef();
       }
-      sequence.addStatement(new StatementReturn(returnVarRef, new StatementSource(ctx)));
+      sequence.addStatement(new StatementReturn(returnVarRef, new StatementSource(ctx), Comment.NO_COMMENTS));
       scopeStack.pop();
-      sequence.addStatement(new StatementProcedureEnd(procedure.getRef(), new StatementSource(ctx)));
+      sequence.addStatement(new StatementProcedureEnd(procedure.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS));
       return null;
    }
 
@@ -176,7 +176,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       Matcher m = p.matcher(kasm);
       if(m.find()) {
          String kickAsmCode = m.group(1).replaceAll("\r", "");
-         StatementKickAsm statementKickAsm = new StatementKickAsm(kickAsmCode, new StatementSource(ctx));
+         StatementKickAsm statementKickAsm = new StatementKickAsm(kickAsmCode, new StatementSource(ctx), ensureUnusedComments(getCommentsSymbol(ctx)));
          if(ctx.kasmDirectives() != null) {
             List<KasmDirective> kasmDirectives = this.visitKasmDirectives(ctx.kasmDirectives());
             for(KasmDirective kasmDirective : kasmDirectives) {
@@ -309,13 +309,14 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       if(type instanceof SymbolTypeArray || type.equals(SymbolType.STRING)) {
          lValue.setDeclaredConstant(true);
       }
+      List<Comment> comments = getCommentsSymbol(ctx);
       if(lValue.isDeclaredConstant()) {
          // Add comments to constant
-         lValue.setComments(getCommentsSymbol(ctx));
+         lValue.setComments(ensureUnusedComments(comments));
       }
       KickCParser.ExprContext initializer = ctx.expr();
       if(initializer != null) {
-         addInitialAssignment(initializer, lValue);
+         addInitialAssignment(initializer, lValue, comments);
       } else if(type instanceof SymbolTypeArray) {
          // Add an zero-array initializer
          SymbolTypeArray typeArray = (SymbolTypeArray) type;
@@ -323,7 +324,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
          if(size == null) {
             throw new CompileError("Error! Array has no declared size. " + lValue.toString(program), new StatementSource(ctx));
          }
-         Statement stmt = new StatementAssignment(lValue.getRef(), new ArrayFilled(typeArray.getElementType(), size), new StatementSource(ctx));
+         Statement stmt = new StatementAssignment(lValue.getRef(), new ArrayFilled(typeArray.getElementType(), size), new StatementSource(ctx), ensureUnusedComments(comments));
          sequence.addStatement(stmt);
       }
       return null;
@@ -483,29 +484,31 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       PrePostModifierHandler.addPreModifiers(this, ctx.expr());
       RValue rValue = (RValue) this.visit(ctx.expr());
 
+      List<Comment> comments = ensureUnusedComments(getCommentsSymbol(ctx));
+
       if(elseStmt == null) {
          // If without else - skip the entire section if condition not met
          VariableRef notExprVar = getCurrentSymbols().addVariableIntermediate().getRef();
-         sequence.addStatement(new StatementAssignment(notExprVar, null, Operators.LOGIC_NOT, rValue, new StatementSource(ctx)));
+         sequence.addStatement(new StatementAssignment(notExprVar, null, Operators.LOGIC_NOT, rValue, new StatementSource(ctx), comments));
          PrePostModifierHandler.addPostModifiers(this, ctx.expr());
          Label endJumpLabel = getCurrentSymbols().addLabelIntermediate();
-         sequence.addStatement(new StatementConditionalJump(notExprVar, endJumpLabel.getRef(), new StatementSource(ctx)));
+         sequence.addStatement(new StatementConditionalJump(notExprVar, endJumpLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS));
          this.visit(ifStmt);
          // No else statement - just add the label
-         sequence.addStatement(new StatementLabel(endJumpLabel.getRef(), new StatementSource(ctx)));
+         sequence.addStatement(new StatementLabel(endJumpLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS));
       } else {
          // If with else - jump to if section if condition met - fall into else otherwise.
          PrePostModifierHandler.addPostModifiers(this, ctx.expr());
          Label ifJumpLabel = getCurrentSymbols().addLabelIntermediate();
-         sequence.addStatement(new StatementConditionalJump(rValue, ifJumpLabel.getRef(), new StatementSource(ctx)));
+         sequence.addStatement(new StatementConditionalJump(rValue, ifJumpLabel.getRef(), new StatementSource(ctx), comments));
          // Add else body
          this.visit(elseStmt);
          // There is an else statement - add the if part and any needed labels/jumps
          Label endJumpLabel = getCurrentSymbols().addLabelIntermediate();
-         sequence.addStatement(new StatementJump(endJumpLabel.getRef(), new StatementSource(ctx)));
-         sequence.addStatement(new StatementLabel(ifJumpLabel.getRef(), new StatementSource(ctx)));
+         sequence.addStatement(new StatementJump(endJumpLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS));
+         sequence.addStatement(new StatementLabel(ifJumpLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS));
          this.visit(ifStmt);
-         StatementLabel endJumpTarget = new StatementLabel(endJumpLabel.getRef(), new StatementSource(ctx));
+         StatementLabel endJumpTarget = new StatementLabel(endJumpLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS);
          sequence.addStatement(endJumpTarget);
       }
       return null;
@@ -516,21 +519,22 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       Label beginJumpLabel = getCurrentSymbols().addLabelIntermediate();
       Label doJumpLabel = getCurrentSymbols().addLabelIntermediate();
       Label endJumpLabel = getCurrentSymbols().addLabelIntermediate();
-      StatementLabel beginJumpTarget = new StatementLabel(beginJumpLabel.getRef(), new StatementSource(ctx));
+      List<Comment> comments = ensureUnusedComments(getCommentsSymbol(ctx));
+      StatementLabel beginJumpTarget = new StatementLabel(beginJumpLabel.getRef(), new StatementSource(ctx),comments);
       sequence.addStatement(beginJumpTarget);
       PrePostModifierHandler.addPreModifiers(this, ctx.expr());
       RValue rValue = (RValue) this.visit(ctx.expr());
       PrePostModifierHandler.addPostModifiers(this, ctx.expr());
-      StatementConditionalJump doJmpStmt = new StatementConditionalJump(rValue, doJumpLabel.getRef(), new StatementSource(ctx));
+      StatementConditionalJump doJmpStmt = new StatementConditionalJump(rValue, doJumpLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS);
       sequence.addStatement(doJmpStmt);
-      Statement endJmpStmt = new StatementJump(endJumpLabel.getRef(), new StatementSource(ctx));
+      Statement endJmpStmt = new StatementJump(endJumpLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS);
       sequence.addStatement(endJmpStmt);
-      StatementLabel doJumpTarget = new StatementLabel(doJumpLabel.getRef(), new StatementSource(ctx));
+      StatementLabel doJumpTarget = new StatementLabel(doJumpLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS);
       sequence.addStatement(doJumpTarget);
       this.visit(ctx.stmt());
-      Statement beginJmpStmt = new StatementJump(beginJumpLabel.getRef(), new StatementSource(ctx));
+      Statement beginJmpStmt = new StatementJump(beginJumpLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS);
       sequence.addStatement(beginJmpStmt);
-      StatementLabel endJumpTarget = new StatementLabel(endJumpLabel.getRef(), new StatementSource(ctx));
+      StatementLabel endJumpTarget = new StatementLabel(endJumpLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS);
       sequence.addStatement(endJumpTarget);
 
       // Add directives
@@ -540,8 +544,9 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
 
    @Override
    public Void visitStmtDoWhile(KickCParser.StmtDoWhileContext ctx) {
+      List<Comment> comments = ensureUnusedComments(getCommentsSymbol(ctx));
       Label beginJumpLabel = getCurrentSymbols().addLabelIntermediate();
-      StatementLabel beginJumpTarget = new StatementLabel(beginJumpLabel.getRef(), new StatementSource(ctx));
+      StatementLabel beginJumpTarget = new StatementLabel(beginJumpLabel.getRef(), new StatementSource(ctx), comments);
       sequence.addStatement(beginJumpTarget);
       if(ctx.stmt() != null) {
          this.visit(ctx.stmt());
@@ -549,11 +554,9 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       PrePostModifierHandler.addPreModifiers(this, ctx.expr());
       RValue rValue = (RValue) this.visit(ctx.expr());
       PrePostModifierHandler.addPostModifiers(this, ctx.expr());
-      StatementConditionalJump doJmpStmt = new StatementConditionalJump(rValue, beginJumpLabel.getRef(), new StatementSource(ctx));
+      StatementConditionalJump doJmpStmt = new StatementConditionalJump(rValue, beginJumpLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS);
       sequence.addStatement(doJmpStmt);
-
       addDirectives(doJmpStmt, ctx.directive());
-
       return null;
    }
 
@@ -575,12 +578,13 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       // Create and assign declared loop variable
       Variable lValue = getForVariable(forDeclCtx);
       KickCParser.ExprContext initializer = forDeclCtx.expr();
+      List<Comment> comments = getCommentsSymbol(ctx);
       if(initializer != null) {
-         addInitialAssignment(initializer, lValue);
+         addInitialAssignment(initializer, lValue, comments);
       }
       // Add label
       Label repeatLabel = getCurrentSymbols().addLabelIntermediate();
-      StatementLabel repeatTarget = new StatementLabel(repeatLabel.getRef(), new StatementSource(ctx));
+      StatementLabel repeatTarget = new StatementLabel(repeatLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS);
       sequence.addStatement(repeatTarget);
       // Add body
       if(stmtForCtx.stmt() != null) {
@@ -597,7 +601,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       RValue rValue = (RValue) this.visit(ctx.expr(0));
       PrePostModifierHandler.addPostModifiers(this, ctx.expr(0));
       // Add jump if condition was met
-      StatementConditionalJump doJmpStmt = new StatementConditionalJump(rValue, repeatLabel.getRef(), new StatementSource(ctx));
+      StatementConditionalJump doJmpStmt = new StatementConditionalJump(rValue, repeatLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS);
       sequence.addStatement(doJmpStmt);
       addDirectives(doJmpStmt, stmtForCtx.directive());
       return null;
@@ -614,27 +618,28 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       // Assign loop variable with first value
       RValue rangeLastValue = (RValue) visit(rangeLastCtx);
       RValue rangeFirstValue = (RValue) visit(rangeFirstCtx);
-      Statement stmtInit = new StatementAssignment(lValue.getRef(), rangeFirstValue, new StatementSource(ctx));
+      List<Comment> comments = ensureUnusedComments(getCommentsSymbol(ctx));
+      Statement stmtInit = new StatementAssignment(lValue.getRef(), rangeFirstValue, new StatementSource(ctx), comments);
       sequence.addStatement(stmtInit);
       // Add label
       Label repeatLabel = getCurrentSymbols().addLabelIntermediate();
-      StatementLabel repeatTarget = new StatementLabel(repeatLabel.getRef(), new StatementSource(ctx));
+      StatementLabel repeatTarget = new StatementLabel(repeatLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS);
       sequence.addStatement(repeatTarget);
       // Add body
       if(stmtForCtx.stmt() != null) {
          this.visit(stmtForCtx.stmt());
       }
       // Add increment
-      Statement stmtNxt = new StatementAssignment(lValue.getRef(), lValue.getRef(), Operators.PLUS, new RangeNext(rangeFirstValue, rangeLastValue), new StatementSource(ctx));
+      Statement stmtNxt = new StatementAssignment(lValue.getRef(), lValue.getRef(), Operators.PLUS, new RangeNext(rangeFirstValue, rangeLastValue), new StatementSource(ctx), Comment.NO_COMMENTS);
       sequence.addStatement(stmtNxt);
       // Add condition i!=last+1 or i!=last-1
       RValue beyondLastVal = new RangeComparison(rangeFirstValue, rangeLastValue, lValue.getType());
       VariableIntermediate tmpVar = getCurrentSymbols().addVariableIntermediate();
       VariableRef tmpVarRef = tmpVar.getRef();
-      Statement stmtTmpVar = new StatementAssignment(tmpVarRef, lValue.getRef(), Operators.NEQ, beyondLastVal, new StatementSource(ctx));
+      Statement stmtTmpVar = new StatementAssignment(tmpVarRef, lValue.getRef(), Operators.NEQ, beyondLastVal, new StatementSource(ctx), Comment.NO_COMMENTS);
       sequence.addStatement(stmtTmpVar);
       // Add jump if condition was met
-      StatementConditionalJump doJmpStmt = new StatementConditionalJump(tmpVarRef, repeatLabel.getRef(), new StatementSource(ctx));
+      StatementConditionalJump doJmpStmt = new StatementConditionalJump(tmpVarRef, repeatLabel.getRef(), new StatementSource(ctx), Comment.NO_COMMENTS);
       sequence.addStatement(doJmpStmt);
       addDirectives(doJmpStmt, stmtForCtx.directive());
       return null;
@@ -666,7 +671,8 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
 
    @Override
    public Object visitStmtAsm(KickCParser.StmtAsmContext ctx) {
-      sequence.addStatement(new StatementAsm(ctx.asmLines(), new StatementSource(ctx)));
+      List<Comment> comments = ensureUnusedComments(getCommentsSymbol(ctx));
+      sequence.addStatement(new StatementAsm(ctx.asmLines(), new StatementSource(ctx), comments));
       return null;
    }
 
@@ -679,18 +685,18 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
          PrePostModifierHandler.addPreModifiers(this, exprCtx);
          rValue = (RValue) this.visit(exprCtx);
          Variable returnVar = procedure.getVariable("return");
-         sequence.addStatement(new StatementAssignment(returnVar.getRef(), rValue, new StatementSource(ctx)));
+         sequence.addStatement(new StatementAssignment(returnVar.getRef(), rValue, new StatementSource(ctx), ensureUnusedComments(getCommentsSymbol(ctx))));
          PrePostModifierHandler.addPostModifiers(this, exprCtx);
       }
       Label returnLabel = procedure.getLabel(SymbolRef.PROCEXIT_BLOCK_NAME);
-      sequence.addStatement(new StatementJump(returnLabel.getRef(), new StatementSource(ctx)));
+      sequence.addStatement(new StatementJump(returnLabel.getRef(), new StatementSource(ctx), ensureUnusedComments(getCommentsSymbol(ctx))));
       return null;
    }
 
-   private void addInitialAssignment(KickCParser.ExprContext initializer, Variable lValue) {
+   private void addInitialAssignment(KickCParser.ExprContext initializer, Variable lValue, List<Comment> comments) {
       PrePostModifierHandler.addPreModifiers(this, initializer);
       RValue rValue = (RValue) visit(initializer);
-      Statement stmt = new StatementAssignment(lValue.getRef(), rValue, new StatementSource(initializer));
+      Statement stmt = new StatementAssignment(lValue.getRef(), rValue, new StatementSource(initializer), ensureUnusedComments(comments));
       sequence.addStatement(stmt);
       PrePostModifierHandler.addPostModifiers(this, initializer);
    }
@@ -752,7 +758,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
          lValue = new LvalueIntermediate((VariableRef) lValue);
       }
       RValue rValue = (RValue) this.visit(ctx.expr(1));
-      Statement stmt = new StatementAssignment(lValue, rValue, new StatementSource(ctx));
+      Statement stmt = new StatementAssignment(lValue, rValue, new StatementSource(ctx), ensureUnusedComments(getCommentsSymbol(ctx)));
       sequence.addStatement(stmt);
       return lValue;
    }
@@ -774,7 +780,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       String op = ((TerminalNode) ctx.getChild(1)).getSymbol().getText();
       Operator operator = Operators.getBinaryCompound(op);
       // Assignment with operator
-      Statement stmt = new StatementAssignment(lValue, lValue, operator, rValue, new StatementSource(ctx));
+      Statement stmt = new StatementAssignment(lValue, lValue, operator, rValue, new StatementSource(ctx), ensureUnusedComments(getCommentsSymbol(ctx)));
       sequence.addStatement(stmt);
       return lValue;
    }
@@ -786,7 +792,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       Operator operator = Operators.getCastUnary(castType);
       VariableIntermediate tmpVar = getCurrentSymbols().addVariableIntermediate();
       VariableRef tmpVarRef = tmpVar.getRef();
-      Statement stmt = new StatementAssignment(tmpVarRef, operator, child, new StatementSource(ctx));
+      Statement stmt = new StatementAssignment(tmpVarRef, operator, child, new StatementSource(ctx), ensureUnusedComments(getCommentsSymbol(ctx)));
       sequence.addStatement(stmt);
       return tmpVarRef;
    }
@@ -802,7 +808,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       }
       VariableIntermediate tmpVar = getCurrentSymbols().addVariableIntermediate();
       VariableRef tmpVarRef = tmpVar.getRef();
-      sequence.addStatement(new StatementCall(tmpVarRef, ctx.NAME().getText(), parameters, new StatementSource(ctx)));
+      sequence.addStatement(new StatementCall(tmpVarRef, ctx.NAME().getText(), parameters, new StatementSource(ctx), ensureUnusedComments(getCommentsSymbol(ctx))));
       return tmpVarRef;
    }
 
@@ -858,7 +864,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       Operator operator = Operators.getBinary(op);
       VariableIntermediate tmpVar = getCurrentSymbols().addVariableIntermediate();
       VariableRef tmpVarRef = tmpVar.getRef();
-      Statement stmt = new StatementAssignment(tmpVarRef, left, operator, right, new StatementSource(ctx));
+      Statement stmt = new StatementAssignment(tmpVarRef, left, operator, right, new StatementSource(ctx), ensureUnusedComments(getCommentsSymbol(ctx)));
       sequence.addStatement(stmt);
       return tmpVarRef;
    }
@@ -876,7 +882,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       Operator operator = Operators.getUnary(op);
       VariableIntermediate tmpVar = getCurrentSymbols().addVariableIntermediate();
       VariableRef tmpVarRef = tmpVar.getRef();
-      Statement stmt = new StatementAssignment(tmpVarRef, operator, child, new StatementSource(ctx));
+      Statement stmt = new StatementAssignment(tmpVarRef, operator, child, new StatementSource(ctx), ensureUnusedComments(getCommentsSymbol(ctx)));
       sequence.addStatement(stmt);
       return tmpVarRef;
    }
@@ -967,6 +973,9 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
     * @return The comments if they are unused. An empty comment if they had already been used.
     */
    private List<Comment> ensureUnusedComments(List<Comment> candidate) {
+      if(candidate.size()==0) {
+         return candidate;
+      }
       int tokenIndex = candidate.get(0).getTokenIndex();
       if(usedCommentTokenIndices.contains(tokenIndex)) {
          // Comment was already used - Return an empty list
@@ -990,7 +999,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       if(commentBlocks.size()==0) {
          return new ArrayList<>();
       }
-      return ensureUnusedComments(commentBlocks.get(0));
+      return commentBlocks.get(0);
    }
 
    /**
@@ -1005,7 +1014,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       if(commentBlocks.size()==0) {
          return new ArrayList<>();
       }
-      return ensureUnusedComments(commentBlocks.get(commentBlocks.size() - 1));
+      return commentBlocks.get(commentBlocks.size() - 1);
    }
 
    /** A declaration directive. */
@@ -1095,7 +1104,7 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
             List<PrePostModifier> modifiers,
             StatementSource source) {
          for(PrePostModifier mod : modifiers) {
-            Statement stmt = new StatementAssignment((LValue) mod.child, mod.operator, mod.child, source);
+            Statement stmt = new StatementAssignment((LValue) mod.child, mod.operator, mod.child, source, Comment.NO_COMMENTS);
             parser.sequence.addStatement(stmt);
             if(parser.program.getLog().isVerboseParse()) {
                parser.program.getLog().append("Adding pre/post-modifier " + stmt.toString(parser.program, false));
@@ -1103,11 +1112,11 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
          }
       }
 
-      public List<PrePostModifier> getPreMods() {
+      List<PrePostModifier> getPreMods() {
          return preMods;
       }
 
-      public List<PrePostModifier> getPostMods() {
+      List<PrePostModifier> getPostMods() {
          return postMods;
       }
 
@@ -1132,10 +1141,10 @@ public class Pass0GenerateStatementSequence extends KickCBaseVisitor<Object> {
       }
 
       private static class PrePostModifier {
-         public RValue child;
+         RValue child;
          public Operator operator;
 
-         public PrePostModifier(RValue child, Operator operator) {
+         PrePostModifier(RValue child, Operator operator) {
             this.child = child;
             this.operator = operator;
          }

src/main/java/dk/camelot64/kickc/passes/Pass1FixLValuesLoHi.java

@@ -14,6 +14,7 @@ import dk.camelot64.kickc.model.symbols.Variable;
 import dk.camelot64.kickc.model.symbols.VariableIntermediate;
 import dk.camelot64.kickc.model.types.SymbolTypeInference;
 
+import java.util.ArrayList;
 import java.util.List;
 import java.util.ListIterator;
 
@@ -69,7 +70,7 @@ public class Pass1FixLValuesLoHi extends Pass1Base {
       statementLValue.setlValue(tmpVarRef);
       SymbolTypeInference.inferLValue(getProgram(), statementLValue, false);
       // Insert an extra "set low" assignment statement
-      Statement setLoHiAssignment = new StatementAssignment(loHiVar, loHiVar, loHiOperator, tmpVarRef, statementLValue.getSource());
+      Statement setLoHiAssignment = new StatementAssignment(loHiVar, loHiVar, loHiOperator, tmpVarRef, statementLValue.getSource(), new ArrayList<>());
       statementsIt.add(setLoHiAssignment);
       if(getLog().isVerbosePass1CreateSsa()) {
          getLog().append("Fixing lo/hi-lvalue with new tmpVar " + tmpVarRef + " " + statementLValue.toString());

src/main/java/dk/camelot64/kickc/passes/Pass1GenerateControlFlowGraph.java

@@ -1,9 +1,6 @@
 package dk.camelot64.kickc.passes;
 
-import dk.camelot64.kickc.model.ControlFlowBlock;
-import dk.camelot64.kickc.model.ControlFlowGraph;
-import dk.camelot64.kickc.model.Program;
-import dk.camelot64.kickc.model.StatementSequence;
+import dk.camelot64.kickc.model.*;
 import dk.camelot64.kickc.model.statements.*;
 import dk.camelot64.kickc.model.symbols.*;
 import dk.camelot64.kickc.model.values.LabelRef;
@@ -33,7 +30,7 @@ public class Pass1GenerateControlFlowGraph extends Pass1Base {
       ControlFlowBlock firstBlock = getOrCreateBlock(scope.addLabel(SymbolRef.BEGIN_BLOCK_NAME).getRef(), ScopeRef.ROOT);
       Stack<ControlFlowBlock> blockStack = new Stack<>();
       blockStack.push(firstBlock);
-      sequence.addStatement(new StatementLabel(scope.addLabel(SymbolRef.END_BLOCK_NAME).getRef(), new StatementSource(RuleContext.EMPTY)));
+      sequence.addStatement(new StatementLabel(scope.addLabel(SymbolRef.END_BLOCK_NAME).getRef(), new StatementSource(RuleContext.EMPTY), Comment.NO_COMMENTS));
       for(Statement statement : sequence.getStatements()) {
          ControlFlowBlock currentBlock = blockStack.peek();
          Symbol currentBlockLabel = scope.getSymbol(currentBlock.getLabel());

src/main/java/dk/camelot64/kickc/passes/Pass1ProcedureCallParameters.java

@@ -43,7 +43,7 @@ public class Pass1ProcedureCallParameters extends ControlFlowGraphCopyVisitor {
       for(int i = 0; i < parameterDecls.size(); i++) {
          Variable parameterDecl = parameterDecls.get(i);
          RValue parameterValue = parameterValues.get(i);
-         addStatementToCurrentBlock(new StatementAssignment(parameterDecl.getRef(), parameterValue, origCall.getSource()));
+         addStatementToCurrentBlock(new StatementAssignment(parameterDecl.getRef(), parameterValue, origCall.getSource(), Comment.NO_COMMENTS));
       }
       String procedureName = origCall.getProcedureName();
       Variable procReturnVar = procedure.getVariable("return");
@@ -51,7 +51,7 @@ public class Pass1ProcedureCallParameters extends ControlFlowGraphCopyVisitor {
       if(procReturnVar != null) {
          procReturnVarRef = procReturnVar.getRef();
       }
-      StatementCall copyCall = new StatementCall(procReturnVarRef, procedureName, null, origCall.getSource());
+      StatementCall copyCall = new StatementCall(procReturnVarRef, procedureName, null, origCall.getSource(), Comment.NO_COMMENTS);
       copyCall.setProcedure(procedureRef);
       addStatementToCurrentBlock(copyCall);
       getCurrentBlock().setCallSuccessor(procedure.getLabel().getRef());
@@ -64,7 +64,7 @@ public class Pass1ProcedureCallParameters extends ControlFlowGraphCopyVisitor {
       }
       splitCurrentBlock(currentBlockScope.addLabelIntermediate().getRef());
       if(!SymbolType.VOID.equals(procedure.getReturnType()) && origCall.getlValue() != null) {
-         addStatementToCurrentBlock(new StatementAssignment(origCall.getlValue(), procReturnVarRef, origCall.getSource()));
+         addStatementToCurrentBlock(new StatementAssignment(origCall.getlValue(), procReturnVarRef, origCall.getSource(), Comment.NO_COMMENTS));
       } else {
          // No return type. Remove variable receiving the result.
          LValue lValue = origCall.getlValue();
@@ -77,22 +77,22 @@ public class Pass1ProcedureCallParameters extends ControlFlowGraphCopyVisitor {
       // Add self-assignments for all variables modified in the procedure
       Set<VariableRef> modifiedVars = program.getProcedureModifiedVars().getModifiedVars(procedure.getRef());
       for(VariableRef modifiedVar : modifiedVars) {
-         addStatementToCurrentBlock(new StatementAssignment(modifiedVar, modifiedVar, origCall.getSource()));
+         addStatementToCurrentBlock(new StatementAssignment(modifiedVar, modifiedVar, origCall.getSource(), Comment.NO_COMMENTS));
       }
       return null;
    }
 
    @Override
-   public StatementReturn visitReturn(StatementReturn origReturn) {
+   public StatementReturn visitReturn(StatementReturn orig) {
       ControlFlowBlock currentBlock = getCurrentBlock();
       String currentProcName = currentBlock.getLabel().getScopeNames();
       Procedure procedure = program.getScope().getProcedure(currentProcName);
       // Add self-assignments for all variables modified in the procedure
       Set<VariableRef> modifiedVars = program.getProcedureModifiedVars().getModifiedVars(procedure.getRef());
       for(VariableRef modifiedVar : modifiedVars) {
-         addStatementToCurrentBlock(new StatementAssignment(modifiedVar, modifiedVar, origReturn.getSource()));
+         addStatementToCurrentBlock(new StatementAssignment(modifiedVar, modifiedVar, orig.getSource(), Comment.NO_COMMENTS));
       }
-      return super.visitReturn(origReturn);
+      return super.visitReturn(orig);
    }
 
 

src/main/java/dk/camelot64/kickc/passes/Pass1ProcedureCallsReturnValue.java

@@ -8,6 +8,7 @@ import dk.camelot64.kickc.model.symbols.Procedure;
 import dk.camelot64.kickc.model.types.SymbolType;
 import org.antlr.v4.runtime.RuleContext;
 
+import java.util.ArrayList;
 import java.util.Set;
 
 /**
@@ -33,7 +34,7 @@ public class Pass1ProcedureCallsReturnValue extends ControlFlowGraphCopyVisitor
       ProcedureRef procedureRef = origCall.getProcedure();
       Procedure procedure = program.getScope().getProcedure(procedureRef);
       String procedureName = origCall.getProcedureName();
-      StatementCall copyCall = new StatementCall(null, procedureName, null, origCall.getSource());
+      StatementCall copyCall = new StatementCall(null, procedureName, null, origCall.getSource(), origCall.getComments());
       copyCall.setProcedure(procedureRef);
       addStatementToCurrentBlock(copyCall);
       getCurrentBlock().setCallSuccessor(procedure.getLabel().getRef());
@@ -54,7 +55,7 @@ public class Pass1ProcedureCallsReturnValue extends ControlFlowGraphCopyVisitor
          if(returnVarFinal == null) {
             throw new RuntimeException("Error! Cannot find final return variable for " + procedure.getFullName());
          }
-         StatementAssignment returnAssignment = new StatementAssignment(origCall.getlValue(), returnVarFinal, origCall.getSource());
+         StatementAssignment returnAssignment = new StatementAssignment(origCall.getlValue(), returnVarFinal, origCall.getSource(), new ArrayList<>());
          addStatementToCurrentBlock(returnAssignment);
       }
 
@@ -102,8 +103,8 @@ public class Pass1ProcedureCallsReturnValue extends ControlFlowGraphCopyVisitor
    }
 
    @Override
-   public StatementReturn visitReturn(StatementReturn origReturn) {
-      addStatementToCurrentBlock(new StatementReturn(null, origReturn.getSource()));
+   public StatementReturn visitReturn(StatementReturn orig) {
+      addStatementToCurrentBlock(new StatementReturn(null, orig.getSource(), orig.getComments()));
       return null;
    }
 }

src/main/java/dk/camelot64/kickc/passes/Pass1ProcedureInline.java

@@ -1,5 +1,6 @@
 package dk.camelot64.kickc.passes;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.CompileError;
 import dk.camelot64.kickc.model.ControlFlowBlock;
 import dk.camelot64.kickc.model.Program;
@@ -111,7 +112,7 @@ public class Pass1ProcedureInline extends Pass1Base {
          Variable procReturnVar = procedure.getVariable("return");
          String inlinedReturnVarName = getInlineSymbolName(procedure, procReturnVar, serial);
          Variable inlinedReturnVar = callScope.getVariable(inlinedReturnVarName);
-         restBlock.addStatement(new StatementAssignment(call.getlValue(), inlinedReturnVar.getRef(), call.getSource()));
+         restBlock.addStatement(new StatementAssignment(call.getlValue(), inlinedReturnVar.getRef(), call.getSource(), Comment.NO_COMMENTS));
       } else {
          // Remove the tmp var receiving the result
          LValue lValue = call.getlValue();
@@ -186,10 +187,10 @@ public class Pass1ProcedureInline extends Pass1Base {
       Statement inlinedStatement;
       if(procStatement instanceof StatementAssignment) {
          StatementAssignment procAssignment = (StatementAssignment) procStatement;
-         inlinedStatement = new StatementAssignment(procAssignment.getlValue(), procAssignment.getrValue1(), procAssignment.getOperator(), procAssignment.getrValue2(), procAssignment.getSource());
+         inlinedStatement = new StatementAssignment(procAssignment.getlValue(), procAssignment.getrValue1(), procAssignment.getOperator(), procAssignment.getrValue2(), procAssignment.getSource(), Comment.NO_COMMENTS);
       } else if(procStatement instanceof StatementCall) {
          StatementCall procCall = (StatementCall) procStatement;
-         StatementCall inlinedCall = new StatementCall(procCall.getlValue(), procCall.getProcedureName(), new ArrayList<>(procCall.getParameters()), procCall.getSource());
+         StatementCall inlinedCall = new StatementCall(procCall.getlValue(), procCall.getProcedureName(), new ArrayList<>(procCall.getParameters()), procCall.getSource(), Comment.NO_COMMENTS);
          inlinedCall.setProcedure(procCall.getProcedure());
          inlinedStatement = inlinedCall;
       } else if(procStatement instanceof StatementConditionalJump) {
@@ -201,7 +202,7 @@ public class Pass1ProcedureInline extends Pass1Base {
             String inlineSymbolName = getInlineSymbolName(procedure, procDestination, serial);
             inlinedDest = callScope.getLabel(inlineSymbolName);
          }
-         StatementConditionalJump inlinedConditionalJump = new StatementConditionalJump(procConditional.getrValue1(), procConditional.getOperator(), procConditional.getrValue2(), inlinedDest.getRef(), procConditional.getSource());
+         StatementConditionalJump inlinedConditionalJump = new StatementConditionalJump(procConditional.getrValue1(), procConditional.getOperator(), procConditional.getrValue2(), inlinedDest.getRef(), procConditional.getSource(), Comment.NO_COMMENTS);
          inlinedConditionalJump.setDeclaredUnroll(procConditional.isDeclaredUnroll());
          inlinedStatement = inlinedConditionalJump;
       } else if(procStatement instanceof StatementReturn) {
@@ -275,7 +276,7 @@ public class Pass1ProcedureInline extends Pass1Base {
          String inlineParameterVarName = getInlineSymbolName(procedure, parameterDecl, serial);
          Variable inlineParameterVar = callScope.getVariable(inlineParameterVarName);
          RValue parameterValue = parameterValues.get(i);
-         statementsIt.add(new StatementAssignment(inlineParameterVar.getRef(), parameterValue, call.getSource()));
+         statementsIt.add(new StatementAssignment(inlineParameterVar.getRef(), parameterValue, call.getSource(), Comment.NO_COMMENTS));
       }
    }
 

src/main/java/dk/camelot64/kickc/passes/Pass2ConditionalAndOrRewriting.java

@@ -1,5 +1,6 @@
 package dk.camelot64.kickc.passes;
 
+import dk.camelot64.kickc.model.Comment;
 import dk.camelot64.kickc.model.ControlFlowBlock;
 import dk.camelot64.kickc.model.Program;
 import dk.camelot64.kickc.model.operators.Operators;
@@ -89,7 +90,7 @@ public class Pass2ConditionalAndOrRewriting extends Pass2SsaOptimization {
       ControlFlowBlock newBlock = new ControlFlowBlock(newBlockLabel.getRef(), currentScopeRef);
       getGraph().addBlock(newBlock);
       LabelRef destLabel = conditional.getDestination();
-      StatementConditionalJump newConditional = new StatementConditionalJump(conditionAssignment.getrValue2(), destLabel, conditional.getSource());
+      StatementConditionalJump newConditional = new StatementConditionalJump(conditionAssignment.getrValue2(), destLabel, conditional.getSource(), Comment.NO_COMMENTS);
       newConditional.setDeclaredUnroll(conditional.isDeclaredUnroll());
       newBlock.getStatements().add(newConditional);
       newBlock.setDefaultSuccessor(block.getDefaultSuccessor());
@@ -121,7 +122,7 @@ public class Pass2ConditionalAndOrRewriting extends Pass2SsaOptimization {
       Label newBlockLabel = currentScope.addLabelIntermediate();
       ControlFlowBlock newBlock = new ControlFlowBlock(newBlockLabel.getRef(), currentScopeRef);
       getGraph().addBlock(newBlock);
-      StatementConditionalJump newConditional = new StatementConditionalJump(conditionAssignment.getrValue2(), conditional.getDestination(), conditional.getSource());
+      StatementConditionalJump newConditional = new StatementConditionalJump(conditionAssignment.getrValue2(), conditional.getDestination(), conditional.getSource(), Comment.NO_COMMENTS);
       // Copy unrolling to the new conditional
       newConditional.setDeclaredUnroll(conditional.isDeclaredUnroll());
       newBlock.getStatements().add(newConditional);

src/main/java/dk/camelot64/kickc/passes/Pass2FixInlineConstructors.java

@@ -112,7 +112,7 @@ public class Pass2FixInlineConstructors extends Pass2SsaOptimization {
                   // Move backward - to insert before the current statement
                   stmtIt.previous();
                   // Add assignment of the new tmpVar
-                  StatementAssignment assignment = new StatementAssignment(tmpVar.getRef(), list.getList().get(0), constructOperator, list.getList().get(1), currentStmt.getSource());
+                  StatementAssignment assignment = new StatementAssignment(tmpVar.getRef(), list.getList().get(0), constructOperator, list.getList().get(1), currentStmt.getSource(), Comment.NO_COMMENTS);
                   stmtIt.add(assignment);
                   // Move back before the current statement
                   stmtIt.next();

src/main/java/dk/camelot64/kickc/passes/Pass2LoopUnroll.java

@@ -152,7 +152,7 @@ public class Pass2LoopUnroll extends Pass2SsaOptimization {
    private Statement unrollStatement(Statement statement, NaturalLoop unrollLoop, Map<LabelRef, LabelRef> blockToNewBlock, Map<VariableRef, VariableRef> definedToNewVar) {
       if(statement instanceof StatementPhiBlock) {
          StatementPhiBlock phiBlock = (StatementPhiBlock) statement;
-         StatementPhiBlock newPhiBlock = new StatementPhiBlock();
+         StatementPhiBlock newPhiBlock = new StatementPhiBlock(Comment.NO_COMMENTS);
          for(StatementPhiBlock.PhiVariable phiVariable : phiBlock.getPhiVariables()) {
             VariableRef phiVar = phiVariable.getVariable();
             VariableRef newVar = definedToNewVar.get(phiVar);
@@ -180,7 +180,8 @@ public class Pass2LoopUnroll extends Pass2SsaOptimization {
                unrollValue(assignment.getrValue1(), definedToNewVar),
                assignment.getOperator(),
                unrollValue(assignment.getrValue2(), definedToNewVar),
-               assignment.getSource()
+               assignment.getSource(),
+               Comment.NO_COMMENTS
          );
       } else if(statement instanceof StatementConditionalJump) {
          StatementConditionalJump conditional = (StatementConditionalJump) statement;
@@ -190,13 +191,14 @@ public class Pass2LoopUnroll extends Pass2SsaOptimization {
                conditional.getOperator(),
                unrollValue(conditional.getrValue2(), definedToNewVar),
                unrollLabel(labelRef, blockToNewBlock),
-               conditional.getSource()
+               conditional.getSource(),
+               Comment.NO_COMMENTS
          );
          newConditional.setDeclaredUnroll(conditional.isDeclaredUnroll());
          return newConditional;
       } else if(statement instanceof StatementCall) {
          StatementCall call = (StatementCall) statement;
-         StatementCall newCall = new StatementCall(null, call.getProcedureName(), null, call.getSource());
+         StatementCall newCall = new StatementCall(null, call.getProcedureName(), null, call.getSource(), Comment.NO_COMMENTS);
          newCall.setProcedure(call.getProcedure());
          return newCall;
       } else {

src/main/java/dk/camelot64/kickc/passes/Pass3AddNopBeforeCallOns.java

@@ -25,12 +25,12 @@ public class Pass3AddNopBeforeCallOns extends Pass2Base {
       for(ControlFlowBlock block : getProgram().getGraph().getAllBlocks()) {
          List<Statement> statements = block.getStatements();
          if(statements.size() == 0) {
-            statements.add(0, new StatementPhiBlock());
+            statements.add(0, new StatementPhiBlock(Comment.NO_COMMENTS));
             getLog().append("Adding NOP phi() at start of " + block.getLabel());
          } else {
             Statement firstStmt = statements.get(0);
             if(firstStmt instanceof StatementCall) {
-               statements.add(0, new StatementPhiBlock());
+               statements.add(0, new StatementPhiBlock(Comment.NO_COMMENTS));
                getLog().append("Adding NOP phi() at start of " + block.getLabel());
             }
          }

src/main/java/dk/camelot64/kickc/passes/Pass3PhiLifting.java

@@ -61,7 +61,7 @@ public class Pass3PhiLifting {
                      if(predecessorStatements.size() > 0) {
                         lastPredecessorStatement = predecessorStatements.get(predecessorStatements.size() - 1);
                      }
-                     StatementAssignment newAssignment = new StatementAssignment(newVar.getRef(), phiRValue.getrValue(), phiBlock.getSource());
+                     StatementAssignment newAssignment = new StatementAssignment(newVar.getRef(), phiRValue.getrValue(), phiBlock.getSource(), Comment.NO_COMMENTS);
                      if(lastPredecessorStatement instanceof StatementConditionalJump) {
                         // Use or Create a new block between the predecessor and this one - replace labels where appropriate
                         ControlFlowBlock newBlock;

src/main/java/dk/camelot64/kickc/passes/Pass4CodeGeneration.java

@@ -47,7 +47,7 @@ public class Pass4CodeGeneration {
 
       // Add file level comments
       asm.startSegment(currentScope, null, "File Comments");
-      addComments(asm, program.getFileComments());
+      generateComments(asm, program.getFileComments());
 
       asm.startSegment(currentScope, null, "Basic Upstart");
       asm.addLine(new AsmSetPc("Basic", AsmFormat.getAsmNumber(0x0801)));
@@ -70,7 +70,7 @@ public class Pass4CodeGeneration {
             // Add any procedure comments
             if(block.isProcedureEntry(program)) {
                Procedure procedure = block.getProcedure(program);
-               addComments(asm, procedure.getComments());
+               generateComments(asm, procedure.getComments());
             }
             // Start the new scope
             asm.addScopeBegin(block.getLabel().getFullName().replace('@', 'b').replace(':', '_'));
@@ -156,7 +156,7 @@ public class Pass4CodeGeneration {
             if(asmName != null && !added.contains(asmName)) {
                added.add(asmName);
                // Add any comments
-               addComments(asm, constantVar.getComments());
+               generateComments(asm, constantVar.getComments());
                // Find the constant value calculation
                String asmConstant = AsmFormat.getAsmConstant(program, constantVar.getValue(), 99, scopeRef);
                if(constantVar.getType() instanceof SymbolTypePointer) {
@@ -186,7 +186,7 @@ public class Pass4CodeGeneration {
     * @param asm The assembler program
     * @param comments The comments to add
     */
-   private void addComments(AsmProgram asm, List<Comment> comments) {
+   private void generateComments(AsmProgram asm, List<Comment> comments) {
       for(Comment comment : comments) {
          asm.addComment(comment.getComment());
       }
@@ -294,7 +294,7 @@ public class Pass4CodeGeneration {
                continue;
             }
             // Add any comments
-            addComments(asm, constantVar.getComments());
+            generateComments(asm, constantVar.getComments());
             // Add any alignment
             Integer declaredAlignment = constantVar.getDeclaredAlignment();
             if(declaredAlignment != null) {
@@ -393,7 +393,7 @@ public class Pass4CodeGeneration {
             String asmName = scopeVar.getAsmName();
             if(asmName != null && !added.contains(asmName)) {
                // Add any comments
-               addComments(asm, scopeVar.getComments());
+               generateComments(asm, scopeVar.getComments());
                // Add the label declaration
                asm.addLabelDecl(asmName.replace("#", "_").replace("$", "_"), registerZp.getZp());
                added.add(asmName);
@@ -429,7 +429,7 @@ public class Pass4CodeGeneration {
    public void generateStatementAsm(AsmProgram asm, ControlFlowBlock block, Statement statement, AsmCodegenAluState aluState, boolean genCallPhiEntry) {
 
       asm.startSegment(block.getScope(), statement.getIndex(), statement.toString(program, verboseAliveInfo));
-
+      generateComments(asm, statement.getComments());
       // IF the previous statement was added to the ALU register - generate the composite ASM fragment
       if(aluState.hasAluAssignment()) {
          StatementAssignment assignmentAlu = aluState.getAluAssignment();

src/test/ref/assignment-chained.asm

@@ -12,6 +12,7 @@ main: {
     sta screen+$29
     lda #1+'l'
     sta screen+2
+    //  Chained assignment with a modification of the result
     lda #'l'
     sta screen+$2a
     rts

src/test/ref/assignment-chained.log

@@ -156,6 +156,7 @@ main: {
     lda #1+'l'
     sta screen+2
   //SEG16 [10] *((const byte*) main::screen#0+(byte/signed byte/word/signed word/dword/signed dword) 42) ← (byte) 'l' -- _deref_pbuc1=vbuc2 
+    //  Chained assignment with a modification of the result
     lda #'l'
     sta screen+$2a
     jmp breturn
@@ -222,6 +223,7 @@ main: {
     lda #1+'l'
     sta screen+2
   //SEG16 [10] *((const byte*) main::screen#0+(byte/signed byte/word/signed word/dword/signed dword) 42) ← (byte) 'l' -- _deref_pbuc1=vbuc2 
+    //  Chained assignment with a modification of the result
     lda #'l'
     sta screen+$2a
     jmp breturn
@@ -300,6 +302,7 @@ main: {
     lda #1+'l'
     sta screen+2
   //SEG16 [10] *((const byte*) main::screen#0+(byte/signed byte/word/signed word/dword/signed dword) 42) ← (byte) 'l' -- _deref_pbuc1=vbuc2 
+    //  Chained assignment with a modification of the result
     lda #'l'
     sta screen+$2a
   //SEG17 main::@return

src/test/ref/bitmap-plotter.asm

@@ -55,6 +55,7 @@ plot: {
     sta plotter_x+1
     lda #<0
     sta plotter_x
+  //  Needs word arrays arranged as two underlying byte arrays to allow byte* plotter_x = plot_x[x]; - and eventually - byte* plotter = plot_x[x] + plot_y[y];
     lda plot_xlo,y
     sta plotter_x
     ldy y

src/test/ref/bitmap-plotter.log

@@ -1179,6 +1179,7 @@ plot: {
     lda #<0
     sta plotter_x
   //SEG45 [25] (byte~) plot::$1 ← < (byte*) plot::plotter_x#1 -- vbuz1=_lo_pbuz2 
+    //  Needs word arrays arranged as two underlying byte arrays to allow byte* plotter_x = plot_x[x]; - and eventually - byte* plotter = plot_x[x] + plot_y[y];
     lda plotter_x
     sta _1
   //SEG46 [26] (byte~) plot::$7 ← *((const byte[256]) plot_xlo#0 + (byte) plot::x#0) -- vbuz1=pbuc1_derefidx_vbuz2 
@@ -1727,6 +1728,7 @@ plot: {
     lda #<0
     sta plotter_x
   //SEG45 [25] (byte~) plot::$1 ← < (byte*) plot::plotter_x#1 -- vbuaa=_lo_pbuz1 
+    //  Needs word arrays arranged as two underlying byte arrays to allow byte* plotter_x = plot_x[x]; - and eventually - byte* plotter = plot_x[x] + plot_y[y];
     lda plotter_x
   //SEG46 [26] (byte~) plot::$7 ← *((const byte[256]) plot_xlo#0 + (byte) plot::x#0) -- vbuaa=pbuc1_derefidx_vbuz1 
     ldy x
@@ -2307,6 +2309,7 @@ plot: {
     lda #<0
     sta plotter_x
   //SEG45 [25] (byte~) plot::$1 ← < (byte*) plot::plotter_x#1 -- vbuaa=_lo_pbuz1 
+  //  Needs word arrays arranged as two underlying byte arrays to allow byte* plotter_x = plot_x[x]; - and eventually - byte* plotter = plot_x[x] + plot_y[y];
   //SEG46 [26] (byte~) plot::$7 ← *((const byte[256]) plot_xlo#0 + (byte) plot::x#0) -- vbuaa=pbuc1_derefidx_vbuz1 
     lda plot_xlo,y
   //SEG47 [27] (byte*) plot::plotter_x#2 ← (byte*) plot::plotter_x#1 lo= (byte~) plot::$7 -- pbuz1=pbuz1_setlo_vbuaa 

src/test/ref/c64dtv-8bppcharstretch.asm

@@ -59,19 +59,24 @@
   .label CHARSET8 = $8000
 main: {
     sei
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
     lda #PROCPORT_RAM_IO
     sta PROCPORT
     jsr gfx_init
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
+    //  8BPP Pixel Cell Mode
     lda #DTV_HIGHCOLOR|DTV_LINEAR|DTV_CHUNKY|DTV_BADLINE_OFF
     sta DTV_CONTROL
     lda #VIC_DEN|VIC_ECM|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_MCM|VIC_CSEL
     sta VIC_CONTROL2
+    //  Plane A: SCREEN
     lda #<SCREEN
     sta DTV_PLANEA_START_LO
     lda #>SCREEN
@@ -83,6 +88,7 @@ main: {
     lda #0
     sta DTV_PLANEA_MODULO_LO
     sta DTV_PLANEA_MODULO_HI
+    //  Plane B: CHARSET8
     lda #<CHARSET8
     sta DTV_PLANEB_START_LO
     lda #>CHARSET8
@@ -92,10 +98,14 @@ main: {
     sta DTV_PLANEB_STEP
     sta DTV_PLANEB_MODULO_LO
     sta DTV_PLANEB_MODULO_HI
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
+    //  Set VIC Bank bits to output - all others to input
     lda #3^SCREEN/$4000
     sta CIA2_PORT_A
+    //  Set VIC Bank
+    //  VIC memory
     lda #(SCREEN&$3fff)>>6|(>(SCREEN&$3fff))>>2
     sta VIC_MEMORY
     ldx #0
@@ -106,6 +116,7 @@ main: {
     cpx #$10
     bne b1
   b3:
+    //  Stabilize Raster
     ldx #$ff
   rff:
     cpx RASTER

src/test/ref/c64dtv-8bppcharstretch.log

@@ -2000,6 +2000,8 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
@@ -2013,9 +2015,11 @@ main: {
   //SEG15 main::@17
   b17:
   //SEG16 [8] *((const byte*) DTV_FEATURE#0) ← (const byte) DTV_FEATURE_ENABLE#0 -- _deref_pbuc1=vbuc2 
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   //SEG17 [9] *((const byte*) DTV_CONTROL#0) ← (const byte) DTV_HIGHCOLOR#0|(const byte) DTV_LINEAR#0|(const byte) DTV_CHUNKY#0|(const byte) DTV_BADLINE_OFF#0 -- _deref_pbuc1=vbuc2 
+    //  8BPP Pixel Cell Mode
     lda #DTV_HIGHCOLOR|DTV_LINEAR|DTV_CHUNKY|DTV_BADLINE_OFF
     sta DTV_CONTROL
   //SEG18 [10] *((const byte*) VIC_CONTROL#0) ← (const byte) VIC_DEN#0|(const byte) VIC_ECM#0|(const byte) VIC_RSEL#0|(byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
@@ -2025,6 +2029,7 @@ main: {
     lda #VIC_MCM|VIC_CSEL
     sta VIC_CONTROL2
   //SEG20 [12] *((const byte*) DTV_PLANEA_START_LO#0) ← <(const byte*) SCREEN#0 -- _deref_pbuc1=vbuc2 
+    //  Plane A: SCREEN
     lda #<SCREEN
     sta DTV_PLANEA_START_LO
   //SEG21 [13] *((const byte*) DTV_PLANEA_START_MI#0) ← >(const byte*) SCREEN#0 -- _deref_pbuc1=vbuc2 
@@ -2043,6 +2048,7 @@ main: {
     lda #0
     sta DTV_PLANEA_MODULO_HI
   //SEG26 [18] *((const byte*) DTV_PLANEB_START_LO#0) ← <(const byte*) CHARSET8#0 -- _deref_pbuc1=vbuc2 
+    //  Plane B: CHARSET8
     lda #<CHARSET8
     sta DTV_PLANEB_START_LO
   //SEG27 [19] *((const byte*) DTV_PLANEB_START_MI#0) ← >(const byte*) CHARSET8#0 -- _deref_pbuc1=vbuc2 
@@ -2061,12 +2067,16 @@ main: {
     lda #0
     sta DTV_PLANEB_MODULO_HI
   //SEG32 [24] *((const byte*) CIA2_PORT_A_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
   //SEG33 [25] *((const byte*) CIA2_PORT_A#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3^((byte))((word))(const byte*) SCREEN#0/(word/signed word/dword/signed dword) 16384 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank bits to output - all others to input
     lda #3^SCREEN/$4000
     sta CIA2_PORT_A
   //SEG34 [26] *((const byte*) VIC_MEMORY#0) ← ((byte))((word))(const byte*) SCREEN#0&(word/signed word/dword/signed dword) 16383>>(byte/signed byte/word/signed word/dword/signed dword) 6|>((word))(const byte*) SCREEN#0&(word/signed word/dword/signed dword) 16383>>(byte/signed byte/word/signed word/dword/signed dword) 2 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank
+    //  VIC memory
     lda #(SCREEN&$3fff)>>6|(>(SCREEN&$3fff))>>2
     sta VIC_MEMORY
   //SEG35 [27] phi from main::@17 to main::@1 [phi:main::@17->main::@1]
@@ -2095,6 +2105,7 @@ main: {
   //SEG43 main::@3
   b3:
   //SEG44 asm { ldx#$ff rff: cpxRASTER bnerff stabilize: nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop cpxRASTER beqeat+0 eat: inx cpx#$08 bnestabilize  }
+    //  Stabilize Raster
     ldx #$ff
   rff:
     cpx RASTER
@@ -2769,6 +2780,8 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
@@ -2782,9 +2795,11 @@ main: {
   //SEG15 main::@17
   b17:
   //SEG16 [8] *((const byte*) DTV_FEATURE#0) ← (const byte) DTV_FEATURE_ENABLE#0 -- _deref_pbuc1=vbuc2 
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   //SEG17 [9] *((const byte*) DTV_CONTROL#0) ← (const byte) DTV_HIGHCOLOR#0|(const byte) DTV_LINEAR#0|(const byte) DTV_CHUNKY#0|(const byte) DTV_BADLINE_OFF#0 -- _deref_pbuc1=vbuc2 
+    //  8BPP Pixel Cell Mode
     lda #DTV_HIGHCOLOR|DTV_LINEAR|DTV_CHUNKY|DTV_BADLINE_OFF
     sta DTV_CONTROL
   //SEG18 [10] *((const byte*) VIC_CONTROL#0) ← (const byte) VIC_DEN#0|(const byte) VIC_ECM#0|(const byte) VIC_RSEL#0|(byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
@@ -2794,6 +2809,7 @@ main: {
     lda #VIC_MCM|VIC_CSEL
     sta VIC_CONTROL2
   //SEG20 [12] *((const byte*) DTV_PLANEA_START_LO#0) ← <(const byte*) SCREEN#0 -- _deref_pbuc1=vbuc2 
+    //  Plane A: SCREEN
     lda #<SCREEN
     sta DTV_PLANEA_START_LO
   //SEG21 [13] *((const byte*) DTV_PLANEA_START_MI#0) ← >(const byte*) SCREEN#0 -- _deref_pbuc1=vbuc2 
@@ -2812,6 +2828,7 @@ main: {
     lda #0
     sta DTV_PLANEA_MODULO_HI
   //SEG26 [18] *((const byte*) DTV_PLANEB_START_LO#0) ← <(const byte*) CHARSET8#0 -- _deref_pbuc1=vbuc2 
+    //  Plane B: CHARSET8
     lda #<CHARSET8
     sta DTV_PLANEB_START_LO
   //SEG27 [19] *((const byte*) DTV_PLANEB_START_MI#0) ← >(const byte*) CHARSET8#0 -- _deref_pbuc1=vbuc2 
@@ -2830,12 +2847,16 @@ main: {
     lda #0
     sta DTV_PLANEB_MODULO_HI
   //SEG32 [24] *((const byte*) CIA2_PORT_A_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
   //SEG33 [25] *((const byte*) CIA2_PORT_A#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3^((byte))((word))(const byte*) SCREEN#0/(word/signed word/dword/signed dword) 16384 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank bits to output - all others to input
     lda #3^SCREEN/$4000
     sta CIA2_PORT_A
   //SEG34 [26] *((const byte*) VIC_MEMORY#0) ← ((byte))((word))(const byte*) SCREEN#0&(word/signed word/dword/signed dword) 16383>>(byte/signed byte/word/signed word/dword/signed dword) 6|>((word))(const byte*) SCREEN#0&(word/signed word/dword/signed dword) 16383>>(byte/signed byte/word/signed word/dword/signed dword) 2 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank
+    //  VIC memory
     lda #(SCREEN&$3fff)>>6|(>(SCREEN&$3fff))>>2
     sta VIC_MEMORY
   //SEG35 [27] phi from main::@17 to main::@1 [phi:main::@17->main::@1]
@@ -2861,6 +2882,7 @@ main: {
   //SEG43 main::@3
   b3:
   //SEG44 asm { ldx#$ff rff: cpxRASTER bnerff stabilize: nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop cpxRASTER beqeat+0 eat: inx cpx#$08 bnestabilize  }
+    //  Stabilize Raster
     ldx #$ff
   rff:
     cpx RASTER
@@ -3759,6 +3781,8 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
@@ -3769,9 +3793,11 @@ main: {
     jsr gfx_init
   //SEG15 main::@17
   //SEG16 [8] *((const byte*) DTV_FEATURE#0) ← (const byte) DTV_FEATURE_ENABLE#0 -- _deref_pbuc1=vbuc2 
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   //SEG17 [9] *((const byte*) DTV_CONTROL#0) ← (const byte) DTV_HIGHCOLOR#0|(const byte) DTV_LINEAR#0|(const byte) DTV_CHUNKY#0|(const byte) DTV_BADLINE_OFF#0 -- _deref_pbuc1=vbuc2 
+    //  8BPP Pixel Cell Mode
     lda #DTV_HIGHCOLOR|DTV_LINEAR|DTV_CHUNKY|DTV_BADLINE_OFF
     sta DTV_CONTROL
   //SEG18 [10] *((const byte*) VIC_CONTROL#0) ← (const byte) VIC_DEN#0|(const byte) VIC_ECM#0|(const byte) VIC_RSEL#0|(byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
@@ -3781,6 +3807,7 @@ main: {
     lda #VIC_MCM|VIC_CSEL
     sta VIC_CONTROL2
   //SEG20 [12] *((const byte*) DTV_PLANEA_START_LO#0) ← <(const byte*) SCREEN#0 -- _deref_pbuc1=vbuc2 
+    //  Plane A: SCREEN
     lda #<SCREEN
     sta DTV_PLANEA_START_LO
   //SEG21 [13] *((const byte*) DTV_PLANEA_START_MI#0) ← >(const byte*) SCREEN#0 -- _deref_pbuc1=vbuc2 
@@ -3798,6 +3825,7 @@ main: {
   //SEG25 [17] *((const byte*) DTV_PLANEA_MODULO_HI#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
     sta DTV_PLANEA_MODULO_HI
   //SEG26 [18] *((const byte*) DTV_PLANEB_START_LO#0) ← <(const byte*) CHARSET8#0 -- _deref_pbuc1=vbuc2 
+    //  Plane B: CHARSET8
     lda #<CHARSET8
     sta DTV_PLANEB_START_LO
   //SEG27 [19] *((const byte*) DTV_PLANEB_START_MI#0) ← >(const byte*) CHARSET8#0 -- _deref_pbuc1=vbuc2 
@@ -3813,12 +3841,16 @@ main: {
   //SEG31 [23] *((const byte*) DTV_PLANEB_MODULO_HI#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
     sta DTV_PLANEB_MODULO_HI
   //SEG32 [24] *((const byte*) CIA2_PORT_A_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
   //SEG33 [25] *((const byte*) CIA2_PORT_A#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3^((byte))((word))(const byte*) SCREEN#0/(word/signed word/dword/signed dword) 16384 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank bits to output - all others to input
     lda #3^SCREEN/$4000
     sta CIA2_PORT_A
   //SEG34 [26] *((const byte*) VIC_MEMORY#0) ← ((byte))((word))(const byte*) SCREEN#0&(word/signed word/dword/signed dword) 16383>>(byte/signed byte/word/signed word/dword/signed dword) 6|>((word))(const byte*) SCREEN#0&(word/signed word/dword/signed dword) 16383>>(byte/signed byte/word/signed word/dword/signed dword) 2 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank
+    //  VIC memory
     lda #(SCREEN&$3fff)>>6|(>(SCREEN&$3fff))>>2
     sta VIC_MEMORY
   //SEG35 [27] phi from main::@17 to main::@1 [phi:main::@17->main::@1]
@@ -3839,6 +3871,7 @@ main: {
   //SEG43 main::@3
   b3:
   //SEG44 asm { ldx#$ff rff: cpxRASTER bnerff stabilize: nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop cpxRASTER beqeat+0 eat: inx cpx#$08 bnestabilize  }
+    //  Stabilize Raster
     ldx #$ff
   rff:
     cpx RASTER

src/test/ref/c64dtv-8bppchunkystretch.asm

@@ -47,19 +47,24 @@
   .label CHUNKY = $8000
 main: {
     sei
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
     lda #PROCPORT_RAM_IO
     sta PROCPORT
     jsr gfx_init_chunky
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
+    //  8BPP Pixel Cell Mode
     lda #DTV_HIGHCOLOR|DTV_LINEAR|DTV_COLORRAM_OFF|DTV_CHUNKY|DTV_BADLINE_OFF
     sta DTV_CONTROL
     lda #VIC_DEN|VIC_ECM|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_MCM|VIC_CSEL
     sta VIC_CONTROL2
+    //  Plane B: CHUNKY
     lda #<CHUNKY
     sta DTV_PLANEB_START_LO
     lda #>CHUNKY
@@ -71,10 +76,14 @@ main: {
     lda #0
     sta DTV_PLANEB_MODULO_LO
     sta DTV_PLANEB_MODULO_HI
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
+    //  Set VIC Bank bits to output - all others to input
     lda #3^CHUNKY/$4000
     sta CIA2_PORT_A
+    //  Set VIC Bank
+    //  VIC memory
     lda #(CHUNKY&$3fff)>>6|(0)>>2
     sta VIC_MEMORY
     ldx #0
@@ -85,6 +94,7 @@ main: {
     cpx #$10
     bne b1
   b3:
+    //  Stabilize Raster
     ldx #$ff
   rff:
     cpx RASTER

src/test/ref/c64dtv-8bppchunkystretch.log

@@ -1639,6 +1639,8 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
@@ -1652,9 +1654,11 @@ main: {
   //SEG15 main::@17
   b17:
   //SEG16 [8] *((const byte*) DTV_FEATURE#0) ← (const byte) DTV_FEATURE_ENABLE#0 -- _deref_pbuc1=vbuc2 
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   //SEG17 [9] *((const byte*) DTV_CONTROL#0) ← (const byte) DTV_HIGHCOLOR#0|(const byte) DTV_LINEAR#0|(const byte) DTV_COLORRAM_OFF#0|(const byte) DTV_CHUNKY#0|(const byte) DTV_BADLINE_OFF#0 -- _deref_pbuc1=vbuc2 
+    //  8BPP Pixel Cell Mode
     lda #DTV_HIGHCOLOR|DTV_LINEAR|DTV_COLORRAM_OFF|DTV_CHUNKY|DTV_BADLINE_OFF
     sta DTV_CONTROL
   //SEG18 [10] *((const byte*) VIC_CONTROL#0) ← (const byte) VIC_DEN#0|(const byte) VIC_ECM#0|(const byte) VIC_RSEL#0|(byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
@@ -1664,6 +1668,7 @@ main: {
     lda #VIC_MCM|VIC_CSEL
     sta VIC_CONTROL2
   //SEG20 [12] *((const byte*) DTV_PLANEB_START_LO#0) ← <(const byte*) CHUNKY#0 -- _deref_pbuc1=vbuc2 
+    //  Plane B: CHUNKY
     lda #<CHUNKY
     sta DTV_PLANEB_START_LO
   //SEG21 [13] *((const byte*) DTV_PLANEB_START_MI#0) ← >(const byte*) CHUNKY#0 -- _deref_pbuc1=vbuc2 
@@ -1682,12 +1687,16 @@ main: {
     lda #0
     sta DTV_PLANEB_MODULO_HI
   //SEG26 [18] *((const byte*) CIA2_PORT_A_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
   //SEG27 [19] *((const byte*) CIA2_PORT_A#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3^((byte))((word))(const byte*) CHUNKY#0/(word/signed word/dword/signed dword) 16384 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank bits to output - all others to input
     lda #3^CHUNKY/$4000
     sta CIA2_PORT_A
   //SEG28 [20] *((const byte*) VIC_MEMORY#0) ← ((byte))((word))(const byte*) CHUNKY#0&(word/signed word/dword/signed dword) 16383>>(byte/signed byte/word/signed word/dword/signed dword) 6|>((word))(const byte*) CHUNKY#0&(word/signed word/dword/signed dword) 16383>>(byte/signed byte/word/signed word/dword/signed dword) 2 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank
+    //  VIC memory
     lda #(CHUNKY&$3fff)>>6|(0)>>2
     sta VIC_MEMORY
   //SEG29 [21] phi from main::@17 to main::@1 [phi:main::@17->main::@1]
@@ -1716,6 +1725,7 @@ main: {
   //SEG37 main::@3
   b3:
   //SEG38 asm { ldx#$ff rff: cpxRASTER bnerff stabilize: nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop cpxRASTER beqeat+0 eat: inx cpx#$08 bnestabilize  }
+    //  Stabilize Raster
     ldx #$ff
   rff:
     cpx RASTER
@@ -2176,6 +2186,8 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
@@ -2189,9 +2201,11 @@ main: {
   //SEG15 main::@17
   b17:
   //SEG16 [8] *((const byte*) DTV_FEATURE#0) ← (const byte) DTV_FEATURE_ENABLE#0 -- _deref_pbuc1=vbuc2 
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   //SEG17 [9] *((const byte*) DTV_CONTROL#0) ← (const byte) DTV_HIGHCOLOR#0|(const byte) DTV_LINEAR#0|(const byte) DTV_COLORRAM_OFF#0|(const byte) DTV_CHUNKY#0|(const byte) DTV_BADLINE_OFF#0 -- _deref_pbuc1=vbuc2 
+    //  8BPP Pixel Cell Mode
     lda #DTV_HIGHCOLOR|DTV_LINEAR|DTV_COLORRAM_OFF|DTV_CHUNKY|DTV_BADLINE_OFF
     sta DTV_CONTROL
   //SEG18 [10] *((const byte*) VIC_CONTROL#0) ← (const byte) VIC_DEN#0|(const byte) VIC_ECM#0|(const byte) VIC_RSEL#0|(byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
@@ -2201,6 +2215,7 @@ main: {
     lda #VIC_MCM|VIC_CSEL
     sta VIC_CONTROL2
   //SEG20 [12] *((const byte*) DTV_PLANEB_START_LO#0) ← <(const byte*) CHUNKY#0 -- _deref_pbuc1=vbuc2 
+    //  Plane B: CHUNKY
     lda #<CHUNKY
     sta DTV_PLANEB_START_LO
   //SEG21 [13] *((const byte*) DTV_PLANEB_START_MI#0) ← >(const byte*) CHUNKY#0 -- _deref_pbuc1=vbuc2 
@@ -2219,12 +2234,16 @@ main: {
     lda #0
     sta DTV_PLANEB_MODULO_HI
   //SEG26 [18] *((const byte*) CIA2_PORT_A_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
   //SEG27 [19] *((const byte*) CIA2_PORT_A#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3^((byte))((word))(const byte*) CHUNKY#0/(word/signed word/dword/signed dword) 16384 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank bits to output - all others to input
     lda #3^CHUNKY/$4000
     sta CIA2_PORT_A
   //SEG28 [20] *((const byte*) VIC_MEMORY#0) ← ((byte))((word))(const byte*) CHUNKY#0&(word/signed word/dword/signed dword) 16383>>(byte/signed byte/word/signed word/dword/signed dword) 6|>((word))(const byte*) CHUNKY#0&(word/signed word/dword/signed dword) 16383>>(byte/signed byte/word/signed word/dword/signed dword) 2 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank
+    //  VIC memory
     lda #(CHUNKY&$3fff)>>6|(0)>>2
     sta VIC_MEMORY
   //SEG29 [21] phi from main::@17 to main::@1 [phi:main::@17->main::@1]
@@ -2250,6 +2269,7 @@ main: {
   //SEG37 main::@3
   b3:
   //SEG38 asm { ldx#$ff rff: cpxRASTER bnerff stabilize: nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop cpxRASTER beqeat+0 eat: inx cpx#$08 bnestabilize  }
+    //  Stabilize Raster
     ldx #$ff
   rff:
     cpx RASTER
@@ -2933,6 +2953,8 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
@@ -2943,9 +2965,11 @@ main: {
     jsr gfx_init_chunky
   //SEG15 main::@17
   //SEG16 [8] *((const byte*) DTV_FEATURE#0) ← (const byte) DTV_FEATURE_ENABLE#0 -- _deref_pbuc1=vbuc2 
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   //SEG17 [9] *((const byte*) DTV_CONTROL#0) ← (const byte) DTV_HIGHCOLOR#0|(const byte) DTV_LINEAR#0|(const byte) DTV_COLORRAM_OFF#0|(const byte) DTV_CHUNKY#0|(const byte) DTV_BADLINE_OFF#0 -- _deref_pbuc1=vbuc2 
+    //  8BPP Pixel Cell Mode
     lda #DTV_HIGHCOLOR|DTV_LINEAR|DTV_COLORRAM_OFF|DTV_CHUNKY|DTV_BADLINE_OFF
     sta DTV_CONTROL
   //SEG18 [10] *((const byte*) VIC_CONTROL#0) ← (const byte) VIC_DEN#0|(const byte) VIC_ECM#0|(const byte) VIC_RSEL#0|(byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
@@ -2955,6 +2979,7 @@ main: {
     lda #VIC_MCM|VIC_CSEL
     sta VIC_CONTROL2
   //SEG20 [12] *((const byte*) DTV_PLANEB_START_LO#0) ← <(const byte*) CHUNKY#0 -- _deref_pbuc1=vbuc2 
+    //  Plane B: CHUNKY
     lda #<CHUNKY
     sta DTV_PLANEB_START_LO
   //SEG21 [13] *((const byte*) DTV_PLANEB_START_MI#0) ← >(const byte*) CHUNKY#0 -- _deref_pbuc1=vbuc2 
@@ -2972,12 +2997,16 @@ main: {
   //SEG25 [17] *((const byte*) DTV_PLANEB_MODULO_HI#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
     sta DTV_PLANEB_MODULO_HI
   //SEG26 [18] *((const byte*) CIA2_PORT_A_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
   //SEG27 [19] *((const byte*) CIA2_PORT_A#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3^((byte))((word))(const byte*) CHUNKY#0/(word/signed word/dword/signed dword) 16384 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank bits to output - all others to input
     lda #3^CHUNKY/$4000
     sta CIA2_PORT_A
   //SEG28 [20] *((const byte*) VIC_MEMORY#0) ← ((byte))((word))(const byte*) CHUNKY#0&(word/signed word/dword/signed dword) 16383>>(byte/signed byte/word/signed word/dword/signed dword) 6|>((word))(const byte*) CHUNKY#0&(word/signed word/dword/signed dword) 16383>>(byte/signed byte/word/signed word/dword/signed dword) 2 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank
+    //  VIC memory
     lda #(CHUNKY&$3fff)>>6|(0)>>2
     sta VIC_MEMORY
   //SEG29 [21] phi from main::@17 to main::@1 [phi:main::@17->main::@1]
@@ -2998,6 +3027,7 @@ main: {
   //SEG37 main::@3
   b3:
   //SEG38 asm { ldx#$ff rff: cpxRASTER bnerff stabilize: nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop nop cpxRASTER beqeat+0 eat: inx cpx#$08 bnestabilize  }
+    //  Stabilize Raster
     ldx #$ff
   rff:
     cpx RASTER

src/test/ref/c64dtv-blittermin.asm

@@ -73,6 +73,7 @@
 main: {
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
+    //  Instruct blitter not to continue previous blit
     lda #DTV_BLIT_CLEAR_IRQ
     sta DTV_BLITTER_CONTROL2
     lda #<SRCA
@@ -89,6 +90,7 @@ main: {
     sta DTV_BLITTER_SRCA_LIN_HI
     lda #$10
     sta DTV_BLITTER_SRCA_STEP
+    //  Step 1.0
     lda #<SRCB
     sta DTV_BLITTER_SRCB_LO
     lda #>SRCB
@@ -103,6 +105,7 @@ main: {
     sta DTV_BLITTER_SRCB_LIN_HI
     lda #0
     sta DTV_BLITTER_SRCB_STEP
+    //  Step 0.0
     lda #<SCREEN
     sta DTV_BLITTER_DEST_LO
     lda #>SCREEN
@@ -117,6 +120,7 @@ main: {
     sta DTV_BLITTER_DEST_LIN_HI
     lda #$10
     sta DTV_BLITTER_DEST_STEP
+    //  Step 1.0
     lda #SRCA_LEN
     sta DTV_BLITTER_LEN_LO
     lda #0
@@ -125,8 +129,10 @@ main: {
     sta DTV_BLITTER_ALU
     lda #DTV_BLIT_TRANSPARANCY_NONE
     sta DTV_BLITTER_TRANSPARANCY
+    //  Start blitter
     lda #DTV_BLIT_FORCE_START|DTV_BLIT_SRCA_FWD|DTV_BLIT_SRCB_FWD|DTV_BLIT_DEST_FWD
     sta DTV_BLITTER_CONTROL
+    //  Instruct blitter to continue at DEST and restart SRC A/B
     lda #DTV_BLIT_DEST_CONT
     sta DTV_BLITTER_CONTROL2
     ldx #0
@@ -135,6 +141,7 @@ main: {
     and #DTV_BLIT_STATUS_BUSY
     cmp #0
     bne b2
+    //  restart
     lda #DTV_BLIT_FORCE_START|DTV_BLIT_SRCA_FWD|DTV_BLIT_SRCB_FWD|DTV_BLIT_DEST_FWD
     sta DTV_BLITTER_CONTROL
     inx

src/test/ref/c64dtv-blittermin.log

@@ -1272,6 +1272,7 @@ main: {
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   //SEG11 [5] *((const byte*) DTV_BLITTER_CONTROL2#0) ← (const byte) DTV_BLIT_CLEAR_IRQ#0 -- _deref_pbuc1=vbuc2 
+    //  Instruct blitter not to continue previous blit
     lda #DTV_BLIT_CLEAR_IRQ
     sta DTV_BLITTER_CONTROL2
   //SEG12 [6] *((const byte*) DTV_BLITTER_SRCA_LO#0) ← <(const byte[]) SRCA#0 -- _deref_pbuc1=vbuc2 
@@ -1299,6 +1300,7 @@ main: {
     lda #$10
     sta DTV_BLITTER_SRCA_STEP
   //SEG20 [14] *((const byte*) DTV_BLITTER_SRCB_LO#0) ← <(const byte[]) SRCB#0 -- _deref_pbuc1=vbuc2 
+    //  Step 1.0
     lda #<SRCB
     sta DTV_BLITTER_SRCB_LO
   //SEG21 [15] *((const byte*) DTV_BLITTER_SRCB_MI#0) ← >(const byte[]) SRCB#0 -- _deref_pbuc1=vbuc2 
@@ -1323,6 +1325,7 @@ main: {
     lda #0
     sta DTV_BLITTER_SRCB_STEP
   //SEG28 [22] *((const byte*) DTV_BLITTER_DEST_LO#0) ← <(const byte*) SCREEN#0 -- _deref_pbuc1=vbuc2 
+    //  Step 0.0
     lda #<SCREEN
     sta DTV_BLITTER_DEST_LO
   //SEG29 [23] *((const byte*) DTV_BLITTER_DEST_MI#0) ← >(const byte*) SCREEN#0 -- _deref_pbuc1=vbuc2 
@@ -1347,6 +1350,7 @@ main: {
     lda #$10
     sta DTV_BLITTER_DEST_STEP
   //SEG36 [30] *((const byte*) DTV_BLITTER_LEN_LO#0) ← (const byte) SRCA_LEN#0 -- _deref_pbuc1=vbuc2 
+    //  Step 1.0
     lda #SRCA_LEN
     sta DTV_BLITTER_LEN_LO
   //SEG37 [31] *((const byte*) DTV_BLITTER_LEN_HI#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
@@ -1359,9 +1363,11 @@ main: {
     lda #DTV_BLIT_TRANSPARANCY_NONE
     sta DTV_BLITTER_TRANSPARANCY
   //SEG40 [34] *((const byte*) DTV_BLITTER_CONTROL#0) ← (const byte) DTV_BLIT_FORCE_START#0|(const byte) DTV_BLIT_SRCA_FWD#0|(const byte) DTV_BLIT_SRCB_FWD#0|(const byte) DTV_BLIT_DEST_FWD#0 -- _deref_pbuc1=vbuc2 
+    //  Start blitter
     lda #DTV_BLIT_FORCE_START|DTV_BLIT_SRCA_FWD|DTV_BLIT_SRCB_FWD|DTV_BLIT_DEST_FWD
     sta DTV_BLITTER_CONTROL
   //SEG41 [35] *((const byte*) DTV_BLITTER_CONTROL2#0) ← (const byte) DTV_BLIT_DEST_CONT#0 -- _deref_pbuc1=vbuc2 
+    //  Instruct blitter to continue at DEST and restart SRC A/B
     lda #DTV_BLIT_DEST_CONT
     sta DTV_BLITTER_CONTROL2
   //SEG42 [36] phi from main to main::@2 [phi:main->main::@2]
@@ -1391,6 +1397,7 @@ main: {
   //SEG50 main::@3
   b3:
   //SEG51 [39] *((const byte*) DTV_BLITTER_CONTROL#0) ← (const byte) DTV_BLIT_FORCE_START#0|(const byte) DTV_BLIT_SRCA_FWD#0|(const byte) DTV_BLIT_SRCB_FWD#0|(const byte) DTV_BLIT_DEST_FWD#0 -- _deref_pbuc1=vbuc2 
+    //  restart
     lda #DTV_BLIT_FORCE_START|DTV_BLIT_SRCA_FWD|DTV_BLIT_SRCB_FWD|DTV_BLIT_DEST_FWD
     sta DTV_BLITTER_CONTROL
   //SEG52 [40] (byte) main::r#1 ← ++ (byte) main::r#2 -- vbuz1=_inc_vbuz1 
@@ -1584,6 +1591,7 @@ main: {
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   //SEG11 [5] *((const byte*) DTV_BLITTER_CONTROL2#0) ← (const byte) DTV_BLIT_CLEAR_IRQ#0 -- _deref_pbuc1=vbuc2 
+    //  Instruct blitter not to continue previous blit
     lda #DTV_BLIT_CLEAR_IRQ
     sta DTV_BLITTER_CONTROL2
   //SEG12 [6] *((const byte*) DTV_BLITTER_SRCA_LO#0) ← <(const byte[]) SRCA#0 -- _deref_pbuc1=vbuc2 
@@ -1611,6 +1619,7 @@ main: {
     lda #$10
     sta DTV_BLITTER_SRCA_STEP
   //SEG20 [14] *((const byte*) DTV_BLITTER_SRCB_LO#0) ← <(const byte[]) SRCB#0 -- _deref_pbuc1=vbuc2 
+    //  Step 1.0
     lda #<SRCB
     sta DTV_BLITTER_SRCB_LO
   //SEG21 [15] *((const byte*) DTV_BLITTER_SRCB_MI#0) ← >(const byte[]) SRCB#0 -- _deref_pbuc1=vbuc2 
@@ -1635,6 +1644,7 @@ main: {
     lda #0
     sta DTV_BLITTER_SRCB_STEP
   //SEG28 [22] *((const byte*) DTV_BLITTER_DEST_LO#0) ← <(const byte*) SCREEN#0 -- _deref_pbuc1=vbuc2 
+    //  Step 0.0
     lda #<SCREEN
     sta DTV_BLITTER_DEST_LO
   //SEG29 [23] *((const byte*) DTV_BLITTER_DEST_MI#0) ← >(const byte*) SCREEN#0 -- _deref_pbuc1=vbuc2 
@@ -1659,6 +1669,7 @@ main: {
     lda #$10
     sta DTV_BLITTER_DEST_STEP
   //SEG36 [30] *((const byte*) DTV_BLITTER_LEN_LO#0) ← (const byte) SRCA_LEN#0 -- _deref_pbuc1=vbuc2 
+    //  Step 1.0
     lda #SRCA_LEN
     sta DTV_BLITTER_LEN_LO
   //SEG37 [31] *((const byte*) DTV_BLITTER_LEN_HI#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
@@ -1671,9 +1682,11 @@ main: {
     lda #DTV_BLIT_TRANSPARANCY_NONE
     sta DTV_BLITTER_TRANSPARANCY
   //SEG40 [34] *((const byte*) DTV_BLITTER_CONTROL#0) ← (const byte) DTV_BLIT_FORCE_START#0|(const byte) DTV_BLIT_SRCA_FWD#0|(const byte) DTV_BLIT_SRCB_FWD#0|(const byte) DTV_BLIT_DEST_FWD#0 -- _deref_pbuc1=vbuc2 
+    //  Start blitter
     lda #DTV_BLIT_FORCE_START|DTV_BLIT_SRCA_FWD|DTV_BLIT_SRCB_FWD|DTV_BLIT_DEST_FWD
     sta DTV_BLITTER_CONTROL
   //SEG41 [35] *((const byte*) DTV_BLITTER_CONTROL2#0) ← (const byte) DTV_BLIT_DEST_CONT#0 -- _deref_pbuc1=vbuc2 
+    //  Instruct blitter to continue at DEST and restart SRC A/B
     lda #DTV_BLIT_DEST_CONT
     sta DTV_BLITTER_CONTROL2
   //SEG42 [36] phi from main to main::@2 [phi:main->main::@2]
@@ -1700,6 +1713,7 @@ main: {
   //SEG50 main::@3
   b3:
   //SEG51 [39] *((const byte*) DTV_BLITTER_CONTROL#0) ← (const byte) DTV_BLIT_FORCE_START#0|(const byte) DTV_BLIT_SRCA_FWD#0|(const byte) DTV_BLIT_SRCB_FWD#0|(const byte) DTV_BLIT_DEST_FWD#0 -- _deref_pbuc1=vbuc2 
+    //  restart
     lda #DTV_BLIT_FORCE_START|DTV_BLIT_SRCA_FWD|DTV_BLIT_SRCB_FWD|DTV_BLIT_DEST_FWD
     sta DTV_BLITTER_CONTROL
   //SEG52 [40] (byte) main::r#1 ← ++ (byte) main::r#2 -- vbuxx=_inc_vbuxx 
@@ -2087,6 +2101,7 @@ main: {
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   //SEG11 [5] *((const byte*) DTV_BLITTER_CONTROL2#0) ← (const byte) DTV_BLIT_CLEAR_IRQ#0 -- _deref_pbuc1=vbuc2 
+    //  Instruct blitter not to continue previous blit
     lda #DTV_BLIT_CLEAR_IRQ
     sta DTV_BLITTER_CONTROL2
   //SEG12 [6] *((const byte*) DTV_BLITTER_SRCA_LO#0) ← <(const byte[]) SRCA#0 -- _deref_pbuc1=vbuc2 
@@ -2112,6 +2127,7 @@ main: {
     lda #$10
     sta DTV_BLITTER_SRCA_STEP
   //SEG20 [14] *((const byte*) DTV_BLITTER_SRCB_LO#0) ← <(const byte[]) SRCB#0 -- _deref_pbuc1=vbuc2 
+    //  Step 1.0
     lda #<SRCB
     sta DTV_BLITTER_SRCB_LO
   //SEG21 [15] *((const byte*) DTV_BLITTER_SRCB_MI#0) ← >(const byte[]) SRCB#0 -- _deref_pbuc1=vbuc2 
@@ -2134,6 +2150,7 @@ main: {
     lda #0
     sta DTV_BLITTER_SRCB_STEP
   //SEG28 [22] *((const byte*) DTV_BLITTER_DEST_LO#0) ← <(const byte*) SCREEN#0 -- _deref_pbuc1=vbuc2 
+    //  Step 0.0
     lda #<SCREEN
     sta DTV_BLITTER_DEST_LO
   //SEG29 [23] *((const byte*) DTV_BLITTER_DEST_MI#0) ← >(const byte*) SCREEN#0 -- _deref_pbuc1=vbuc2 
@@ -2156,6 +2173,7 @@ main: {
     lda #$10
     sta DTV_BLITTER_DEST_STEP
   //SEG36 [30] *((const byte*) DTV_BLITTER_LEN_LO#0) ← (const byte) SRCA_LEN#0 -- _deref_pbuc1=vbuc2 
+    //  Step 1.0
     lda #SRCA_LEN
     sta DTV_BLITTER_LEN_LO
   //SEG37 [31] *((const byte*) DTV_BLITTER_LEN_HI#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
@@ -2168,9 +2186,11 @@ main: {
     lda #DTV_BLIT_TRANSPARANCY_NONE
     sta DTV_BLITTER_TRANSPARANCY
   //SEG40 [34] *((const byte*) DTV_BLITTER_CONTROL#0) ← (const byte) DTV_BLIT_FORCE_START#0|(const byte) DTV_BLIT_SRCA_FWD#0|(const byte) DTV_BLIT_SRCB_FWD#0|(const byte) DTV_BLIT_DEST_FWD#0 -- _deref_pbuc1=vbuc2 
+    //  Start blitter
     lda #DTV_BLIT_FORCE_START|DTV_BLIT_SRCA_FWD|DTV_BLIT_SRCB_FWD|DTV_BLIT_DEST_FWD
     sta DTV_BLITTER_CONTROL
   //SEG41 [35] *((const byte*) DTV_BLITTER_CONTROL2#0) ← (const byte) DTV_BLIT_DEST_CONT#0 -- _deref_pbuc1=vbuc2 
+    //  Instruct blitter to continue at DEST and restart SRC A/B
     lda #DTV_BLIT_DEST_CONT
     sta DTV_BLITTER_CONTROL2
   //SEG42 [36] phi from main to main::@2 [phi:main->main::@2]
@@ -2189,6 +2209,7 @@ main: {
     bne b2
   //SEG50 main::@3
   //SEG51 [39] *((const byte*) DTV_BLITTER_CONTROL#0) ← (const byte) DTV_BLIT_FORCE_START#0|(const byte) DTV_BLIT_SRCA_FWD#0|(const byte) DTV_BLIT_SRCB_FWD#0|(const byte) DTV_BLIT_DEST_FWD#0 -- _deref_pbuc1=vbuc2 
+    //  restart
     lda #DTV_BLIT_FORCE_START|DTV_BLIT_SRCA_FWD|DTV_BLIT_SRCB_FWD|DTV_BLIT_DEST_FWD
     sta DTV_BLITTER_CONTROL
   //SEG52 [40] (byte) main::r#1 ← ++ (byte) main::r#2 -- vbuxx=_inc_vbuxx 

src/test/ref/c64dtv-color.asm

@@ -24,6 +24,7 @@ main: {
     lda RASTER
     cmp #$40
     bne b4
+    //  Create rasterbars
     lda #0
     sta BGCOL
     ldx #$31

src/test/ref/c64dtv-color.log

@@ -1130,6 +1130,7 @@ main: {
   //SEG15 main::@6
   b6:
   //SEG16 [8] *((const byte*) BGCOL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Create rasterbars
     lda #0
     sta BGCOL
   //SEG17 [9] phi from main::@6 to main::@7 [phi:main::@6->main::@7]
@@ -1284,6 +1285,7 @@ main: {
   //SEG15 main::@6
   b6:
   //SEG16 [8] *((const byte*) BGCOL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Create rasterbars
     lda #0
     sta BGCOL
   //SEG17 [9] phi from main::@6 to main::@7 [phi:main::@6->main::@7]
@@ -1636,6 +1638,7 @@ main: {
     bne b4
   //SEG15 main::@6
   //SEG16 [8] *((const byte*) BGCOL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Create rasterbars
     lda #0
     sta BGCOL
   //SEG17 [9] phi from main::@6 to main::@7 [phi:main::@6->main::@7]

src/test/ref/c64dtv-gfxexplorer.asm

@@ -171,10 +171,13 @@
   .label form_cursor_count = $e
 main: {
     sei
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
     lda #PROCPORT_RAM_IO
     sta PROCPORT
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
     jsr keyboard_init
@@ -390,8 +393,10 @@ gfx_mode: {
     sta DTV_PLANEB_MODULO_LO
     lda #0
     sta DTV_PLANEB_MODULO_HI
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
+    //  Set VIC Bank bits to output - all others to input
     lda #3^VIC_SCREEN0/$4000
     sta CIA2_PORT_A
     lda form_vic_screen
@@ -421,6 +426,8 @@ gfx_mode: {
     lsr
     lsr
     ora _65
+    //  Set VIC Bank
+    //  VIC memory
     sta VIC_MEMORY
     lda form_vic_cols
     jsr get_vic_screen
@@ -453,6 +460,7 @@ gfx_mode: {
     lda cy
     cmp #$19
     bne b10
+    //  Background colors
     lda #0
     sta BORDERCOL
     lda form_vic_bg0_hi
@@ -483,6 +491,7 @@ gfx_mode: {
     asl
     ora form_vic_bg3_lo
     sta BGCOL4
+    //  DTV Palette
     lda form_dtv_palet
     cmp #0
     beq b18
@@ -614,6 +623,7 @@ keyboard_event_scan: {
     and keyboard_matrix_col_bitmask,y
     cmp #0
     beq b7
+    //  Key pressed
     lda keycode
     ldy keyboard_events_size
     sta keyboard_events,y
@@ -624,6 +634,7 @@ keyboard_event_scan: {
     lda col
     cmp #8
     bne b4
+    //  Store the current keyboard status for the row to debounce
     lda row_scan
     ldy row
     sta keyboard_scan_values,y
@@ -631,6 +642,7 @@ keyboard_event_scan: {
   b7:
     lda #$40
     ora keycode
+    //  Key released
     ldy keyboard_events_size
     sta keyboard_events,y
     inc keyboard_events_size
@@ -955,24 +967,33 @@ form_mode: {
     jsr form_render_values
     lda form_fields_val
     jsr render_preset_name
+    //  DTV Graphics Bank
     lda #($ffffffff&FORM_CHARSET)/$10000
     sta DTV_GRAPHICS_VIC_BANK
+    //  DTV Color Bank
     lda #DTV_COLOR_BANK_DEFAULT/$400
     sta DTV_COLOR_BANK_LO
     lda #0
     sta DTV_COLOR_BANK_HI
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
+    //  Set VIC Bank bits to output - all others to input
     lda #3^FORM_CHARSET/$4000
     sta CIA2_PORT_A
+    //  Set VIC Bank
+    //  DTV Graphics Mode
     lda #0
     sta DTV_CONTROL
+    //  VIC Graphics Mode
     lda #VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_CSEL
     sta VIC_CONTROL2
+    //  VIC Memory Pointers
     lda #(FORM_SCREEN&$3fff)/$40|(FORM_CHARSET&$3fff)/$400
     sta VIC_MEMORY
+    //  DTV Plane A to FORM_SCREEN also
     lda #<FORM_SCREEN
     sta DTV_PLANEA_START_LO
     lda #>FORM_SCREEN
@@ -986,6 +1007,7 @@ form_mode: {
     iny
     cpy #$10
     bne b1
+    //  Screen colors
     lda #0
     sta BGCOL
     sta BORDERCOL
@@ -1330,6 +1352,7 @@ form_control: {
     lda #$7f
     ldy #0
     and (field),y
+    //  Unblink the cursor
     sta (field),y
     lda #KEY_MODIFIER_SHIFT
     and keyboard_modifiers
@@ -1365,6 +1388,7 @@ form_control: {
     lda form_fields_max,x
     sta form_fields_val,x
   b12:
+    //  Render field value
     lda form_fields_val,x
     tay
     lda print_hextab,y
@@ -2527,8 +2551,10 @@ gfx_init_screen0: {
 }
 //  Initialize keyboard reading by setting CIA#$ Data Direction Registers
 keyboard_init: {
+    //  Keyboard Matrix Columns Write Mode
     lda #$ff
     sta CIA1_PORT_A_DDR
+    //  Keyboard Matrix Columns Read Mode
     lda #0
     sta CIA1_PORT_B_DDR
     rts

src/test/ref/c64dtv-gfxexplorer.log

@@ -13930,12 +13930,15 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG13 [7] *((const byte*) DTV_FEATURE#0) ← (const byte) DTV_FEATURE_ENABLE#0 -- _deref_pbuc1=vbuc2 
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   //SEG14 [8] call keyboard_init 
@@ -14467,9 +14470,11 @@ gfx_mode: {
     lda #0
     sta DTV_PLANEB_MODULO_HI
   //SEG151 [92] *((const byte*) CIA2_PORT_A_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
   //SEG152 [93] *((const byte*) CIA2_PORT_A#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3^((byte))((word))(const byte*) VIC_SCREEN0#0/(word/signed word/dword/signed dword) 16384 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank bits to output - all others to input
     lda #3^VIC_SCREEN0/$4000
     sta CIA2_PORT_A
   //SEG153 [94] (byte) get_vic_screen::idx#0 ← *((const byte*) form_vic_screen#0) -- vbuz1=_deref_pbuc1 
@@ -14552,6 +14557,8 @@ gfx_mode: {
     ora _70
     sta _71
   //SEG172 [109] *((const byte*) VIC_MEMORY#0) ← (byte~) gfx_mode::$71 -- _deref_pbuc1=vbuz1 
+    //  Set VIC Bank
+    //  VIC memory
     lda _71
     sta VIC_MEMORY
   //SEG173 [110] (byte) get_vic_screen::idx#1 ← *((const byte*) form_vic_cols#0) -- vbuz1=_deref_pbuc1 
@@ -14645,6 +14652,7 @@ gfx_mode: {
   //SEG206 gfx_mode::@33
   b33:
   //SEG207 [123] *((const byte*) BORDERCOL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Background colors
     lda #0
     sta BORDERCOL
   //SEG208 [124] (byte~) gfx_mode::$75 ← *((const byte*) form_vic_bg0_hi#0) << (byte/signed byte/word/signed word/dword/signed dword) 4 -- vbuz1=_deref_pbuc1_rol_4 
@@ -14704,6 +14712,7 @@ gfx_mode: {
     lda _82
     sta BGCOL4
   //SEG220 [136] if(*((const byte*) form_dtv_palet#0)==(byte/signed byte/word/signed word/dword/signed dword) 0) goto gfx_mode::@15 -- _deref_pbuc1_eq_0_then_la1 
+    //  DTV Palette
     lda form_dtv_palet
     cmp #0
     beq b15_from_b33
@@ -15111,6 +15120,7 @@ keyboard_event_scan: {
   //SEG360 keyboard_event_scan::@17
   b17:
   //SEG361 [203] *((const byte[8]) keyboard_events#0 + (byte) keyboard_events_size#18) ← (byte) keyboard_event_scan::keycode#10 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Key pressed
     lda keycode
     ldy keyboard_events_size
     sta keyboard_events,y
@@ -15137,6 +15147,7 @@ keyboard_event_scan: {
   //SEG369 keyboard_event_scan::@19
   b19:
   //SEG370 [209] *((const byte[8]) keyboard_scan_values#0 + (byte) keyboard_event_scan::row#2) ← (byte) keyboard_event_scan::row_scan#0 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Store the current keyboard status for the row to debounce
     lda row_scan
     ldy row
     sta keyboard_scan_values,y
@@ -15148,6 +15159,7 @@ keyboard_event_scan: {
     ora keycode
     sta _11
   //SEG373 [211] *((const byte[8]) keyboard_events#0 + (byte) keyboard_events_size#18) ← (byte/word/dword~) keyboard_event_scan::$11 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Key released
     lda _11
     ldy keyboard_events_size
     sta keyboard_events,y
@@ -15739,33 +15751,42 @@ form_mode: {
   //SEG521 form_mode::@29
   b29:
   //SEG522 [272] *((const byte*) DTV_GRAPHICS_VIC_BANK#0) ← ((byte))((dword))(const byte*) FORM_CHARSET#0/(dword/signed dword) 65536 -- _deref_pbuc1=vbuc2 
+    //  DTV Graphics Bank
     lda #($ffffffff&FORM_CHARSET)/$10000
     sta DTV_GRAPHICS_VIC_BANK
   //SEG523 [273] *((const byte*) DTV_COLOR_BANK_LO#0) ← <((word))(const dword) DTV_COLOR_BANK_DEFAULT#0/(word/signed word/dword/signed dword) 1024 -- _deref_pbuc1=vbuc2 
+    //  DTV Color Bank
     lda #DTV_COLOR_BANK_DEFAULT/$400
     sta DTV_COLOR_BANK_LO
   //SEG524 [274] *((const byte*) DTV_COLOR_BANK_HI#0) ← >((word))(const dword) DTV_COLOR_BANK_DEFAULT#0/(word/signed word/dword/signed dword) 1024 -- _deref_pbuc1=vbuc2 
     lda #0
     sta DTV_COLOR_BANK_HI
   //SEG525 [275] *((const byte*) CIA2_PORT_A_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
   //SEG526 [276] *((const byte*) CIA2_PORT_A#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3^((byte))((word))(const byte*) FORM_CHARSET#0/(word/signed word/dword/signed dword) 16384 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank bits to output - all others to input
     lda #3^FORM_CHARSET/$4000
     sta CIA2_PORT_A
   //SEG527 [277] *((const byte*) DTV_CONTROL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank
+    //  DTV Graphics Mode
     lda #0
     sta DTV_CONTROL
   //SEG528 [278] *((const byte*) VIC_CONTROL#0) ← (const byte) VIC_DEN#0|(const byte) VIC_RSEL#0|(byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Mode
     lda #VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
   //SEG529 [279] *((const byte*) VIC_CONTROL2#0) ← (const byte) VIC_CSEL#0 -- _deref_pbuc1=vbuc2 
     lda #VIC_CSEL
     sta VIC_CONTROL2
   //SEG530 [280] *((const byte*) VIC_MEMORY#0) ← ((byte))((word))(const byte*) FORM_SCREEN#0&(word/signed word/dword/signed dword) 16383/(byte/signed byte/word/signed word/dword/signed dword) 64|((word))(const byte*) FORM_CHARSET#0&(word/signed word/dword/signed dword) 16383/(word/signed word/dword/signed dword) 1024 -- _deref_pbuc1=vbuc2 
+    //  VIC Memory Pointers
     lda #(FORM_SCREEN&$3fff)/$40|(FORM_CHARSET&$3fff)/$400
     sta VIC_MEMORY
   //SEG531 [281] *((const byte*) DTV_PLANEA_START_LO#0) ← <(const byte*) FORM_SCREEN#0 -- _deref_pbuc1=vbuc2 
+    //  DTV Plane A to FORM_SCREEN also
     lda #<FORM_SCREEN
     sta DTV_PLANEA_START_LO
   //SEG532 [282] *((const byte*) DTV_PLANEA_START_MI#0) ← >(const byte*) FORM_SCREEN#0 -- _deref_pbuc1=vbuc2 
@@ -15800,6 +15821,7 @@ form_mode: {
   //SEG542 form_mode::@10
   b10:
   //SEG543 [288] *((const byte*) BGCOL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Screen colors
     lda #0
     sta BGCOL
   //SEG544 [289] *((const byte*) BORDERCOL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
@@ -16561,6 +16583,7 @@ form_control: {
     and (field),y
     sta _11
   //SEG763 [382] *((byte*) form_control::field#0) ← (byte~) form_control::$11 -- _deref_pbuz1=vbuz2 
+    //  Unblink the cursor
     lda _11
     ldy #0
     sta (field),y
@@ -16672,6 +16695,7 @@ form_control: {
   //SEG799 form_control::@12
   b12:
   //SEG800 [400] *((byte*) form_control::field#0) ← *((const byte[]) print_hextab#0 + *((const byte[]) form_fields_val#0 + (byte) form_field_idx#28)) -- _deref_pbuz1=pbuc1_derefidx_pbuc2_derefidx_vbuz2 
+    //  Render field value
     ldy form_field_idx
     lda form_fields_val,y
     tay
@@ -19499,9 +19523,11 @@ gfx_init_screen0: {
 //  Initialize keyboard reading by setting CIA#$ Data Direction Registers
 keyboard_init: {
   //SEG1758 [862] *((const byte*) CIA1_PORT_A_DDR#0) ← (byte/word/signed word/dword/signed dword) 255 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Write Mode
     lda #$ff
     sta CIA1_PORT_A_DDR
   //SEG1759 [863] *((const byte*) CIA1_PORT_B_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Read Mode
     lda #0
     sta CIA1_PORT_B_DDR
     jmp breturn
@@ -21187,12 +21213,15 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG13 [7] *((const byte*) DTV_FEATURE#0) ← (const byte) DTV_FEATURE_ENABLE#0 -- _deref_pbuc1=vbuc2 
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   //SEG14 [8] call keyboard_init 
@@ -21613,9 +21642,11 @@ gfx_mode: {
     lda #0
     sta DTV_PLANEB_MODULO_HI
   //SEG151 [92] *((const byte*) CIA2_PORT_A_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
   //SEG152 [93] *((const byte*) CIA2_PORT_A#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3^((byte))((word))(const byte*) VIC_SCREEN0#0/(word/signed word/dword/signed dword) 16384 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank bits to output - all others to input
     lda #3^VIC_SCREEN0/$4000
     sta CIA2_PORT_A
   //SEG153 [94] (byte) get_vic_screen::idx#0 ← *((const byte*) form_vic_screen#0) -- vbuaa=_deref_pbuc1 
@@ -21671,6 +21702,8 @@ gfx_mode: {
   //SEG171 [108] (byte~) gfx_mode::$71 ← (byte~) gfx_mode::$65 | (byte~) gfx_mode::$70 -- vbuaa=vbuz1_bor_vbuaa 
     ora _65
   //SEG172 [109] *((const byte*) VIC_MEMORY#0) ← (byte~) gfx_mode::$71 -- _deref_pbuc1=vbuaa 
+    //  Set VIC Bank
+    //  VIC memory
     sta VIC_MEMORY
   //SEG173 [110] (byte) get_vic_screen::idx#1 ← *((const byte*) form_vic_cols#0) -- vbuaa=_deref_pbuc1 
     lda form_vic_cols
@@ -21754,6 +21787,7 @@ gfx_mode: {
   //SEG206 gfx_mode::@33
   b33:
   //SEG207 [123] *((const byte*) BORDERCOL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Background colors
     lda #0
     sta BORDERCOL
   //SEG208 [124] (byte~) gfx_mode::$75 ← *((const byte*) form_vic_bg0_hi#0) << (byte/signed byte/word/signed word/dword/signed dword) 4 -- vbuaa=_deref_pbuc1_rol_4 
@@ -21797,6 +21831,7 @@ gfx_mode: {
   //SEG219 [135] *((const byte*) BGCOL4#0) ← (byte~) gfx_mode::$82 -- _deref_pbuc1=vbuaa 
     sta BGCOL4
   //SEG220 [136] if(*((const byte*) form_dtv_palet#0)==(byte/signed byte/word/signed word/dword/signed dword) 0) goto gfx_mode::@15 -- _deref_pbuc1_eq_0_then_la1 
+    //  DTV Palette
     lda form_dtv_palet
     cmp #0
     beq b15_from_b33
@@ -22150,6 +22185,7 @@ keyboard_event_scan: {
   //SEG360 keyboard_event_scan::@17
   b17:
   //SEG361 [203] *((const byte[8]) keyboard_events#0 + (byte) keyboard_events_size#18) ← (byte) keyboard_event_scan::keycode#10 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Key pressed
     lda keycode
     ldy keyboard_events_size
     sta keyboard_events,y
@@ -22176,6 +22212,7 @@ keyboard_event_scan: {
   //SEG369 keyboard_event_scan::@19
   b19:
   //SEG370 [209] *((const byte[8]) keyboard_scan_values#0 + (byte) keyboard_event_scan::row#2) ← (byte) keyboard_event_scan::row_scan#0 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Store the current keyboard status for the row to debounce
     lda row_scan
     ldy row
     sta keyboard_scan_values,y
@@ -22186,6 +22223,7 @@ keyboard_event_scan: {
     lda #$40
     ora keycode
   //SEG373 [211] *((const byte[8]) keyboard_events#0 + (byte) keyboard_events_size#18) ← (byte/word/dword~) keyboard_event_scan::$11 -- pbuc1_derefidx_vbuz1=vbuaa 
+    //  Key released
     ldy keyboard_events_size
     sta keyboard_events,y
   //SEG374 [212] (byte) keyboard_events_size#1 ← ++ (byte) keyboard_events_size#18 -- vbuz1=_inc_vbuz1 
@@ -22730,33 +22768,42 @@ form_mode: {
   //SEG521 form_mode::@29
   b29:
   //SEG522 [272] *((const byte*) DTV_GRAPHICS_VIC_BANK#0) ← ((byte))((dword))(const byte*) FORM_CHARSET#0/(dword/signed dword) 65536 -- _deref_pbuc1=vbuc2 
+    //  DTV Graphics Bank
     lda #($ffffffff&FORM_CHARSET)/$10000
     sta DTV_GRAPHICS_VIC_BANK
   //SEG523 [273] *((const byte*) DTV_COLOR_BANK_LO#0) ← <((word))(const dword) DTV_COLOR_BANK_DEFAULT#0/(word/signed word/dword/signed dword) 1024 -- _deref_pbuc1=vbuc2 
+    //  DTV Color Bank
     lda #DTV_COLOR_BANK_DEFAULT/$400
     sta DTV_COLOR_BANK_LO
   //SEG524 [274] *((const byte*) DTV_COLOR_BANK_HI#0) ← >((word))(const dword) DTV_COLOR_BANK_DEFAULT#0/(word/signed word/dword/signed dword) 1024 -- _deref_pbuc1=vbuc2 
     lda #0
     sta DTV_COLOR_BANK_HI
   //SEG525 [275] *((const byte*) CIA2_PORT_A_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
   //SEG526 [276] *((const byte*) CIA2_PORT_A#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3^((byte))((word))(const byte*) FORM_CHARSET#0/(word/signed word/dword/signed dword) 16384 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank bits to output - all others to input
     lda #3^FORM_CHARSET/$4000
     sta CIA2_PORT_A
   //SEG527 [277] *((const byte*) DTV_CONTROL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank
+    //  DTV Graphics Mode
     lda #0
     sta DTV_CONTROL
   //SEG528 [278] *((const byte*) VIC_CONTROL#0) ← (const byte) VIC_DEN#0|(const byte) VIC_RSEL#0|(byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Mode
     lda #VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
   //SEG529 [279] *((const byte*) VIC_CONTROL2#0) ← (const byte) VIC_CSEL#0 -- _deref_pbuc1=vbuc2 
     lda #VIC_CSEL
     sta VIC_CONTROL2
   //SEG530 [280] *((const byte*) VIC_MEMORY#0) ← ((byte))((word))(const byte*) FORM_SCREEN#0&(word/signed word/dword/signed dword) 16383/(byte/signed byte/word/signed word/dword/signed dword) 64|((word))(const byte*) FORM_CHARSET#0&(word/signed word/dword/signed dword) 16383/(word/signed word/dword/signed dword) 1024 -- _deref_pbuc1=vbuc2 
+    //  VIC Memory Pointers
     lda #(FORM_SCREEN&$3fff)/$40|(FORM_CHARSET&$3fff)/$400
     sta VIC_MEMORY
   //SEG531 [281] *((const byte*) DTV_PLANEA_START_LO#0) ← <(const byte*) FORM_SCREEN#0 -- _deref_pbuc1=vbuc2 
+    //  DTV Plane A to FORM_SCREEN also
     lda #<FORM_SCREEN
     sta DTV_PLANEA_START_LO
   //SEG532 [282] *((const byte*) DTV_PLANEA_START_MI#0) ← >(const byte*) FORM_SCREEN#0 -- _deref_pbuc1=vbuc2 
@@ -22788,6 +22835,7 @@ form_mode: {
   //SEG542 form_mode::@10
   b10:
   //SEG543 [288] *((const byte*) BGCOL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Screen colors
     lda #0
     sta BGCOL
   //SEG544 [289] *((const byte*) BORDERCOL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
@@ -23469,6 +23517,7 @@ form_control: {
     ldy #0
     and (field),y
   //SEG763 [382] *((byte*) form_control::field#0) ← (byte~) form_control::$11 -- _deref_pbuz1=vbuaa 
+    //  Unblink the cursor
     ldy #0
     sta (field),y
   //SEG764 [383] (byte~) form_control::$12 ← (byte) keyboard_modifiers#21 & (const byte) KEY_MODIFIER_SHIFT#0 -- vbuaa=vbuz1_band_vbuc1 
@@ -23566,6 +23615,7 @@ form_control: {
   //SEG799 form_control::@12
   b12:
   //SEG800 [400] *((byte*) form_control::field#0) ← *((const byte[]) print_hextab#0 + *((const byte[]) form_fields_val#0 + (byte) form_field_idx#28)) -- _deref_pbuz1=pbuc1_derefidx_pbuc2_derefidx_vbuxx 
+    //  Render field value
     lda form_fields_val,x
     tay
     lda print_hextab,y
@@ -26142,9 +26192,11 @@ gfx_init_screen0: {
 //  Initialize keyboard reading by setting CIA#$ Data Direction Registers
 keyboard_init: {
   //SEG1758 [862] *((const byte*) CIA1_PORT_A_DDR#0) ← (byte/word/signed word/dword/signed dword) 255 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Write Mode
     lda #$ff
     sta CIA1_PORT_A_DDR
   //SEG1759 [863] *((const byte*) CIA1_PORT_B_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Read Mode
     lda #0
     sta CIA1_PORT_B_DDR
     jmp breturn
@@ -27267,18 +27319,18 @@ Removing instruction b37:
 Succesful ASM optimization Pass5UnusedLabelElimination
 Removing unreachable instruction jmp b7
 Succesful ASM optimization Pass5UnreachableCodeElimination
-Fixing long branch [746] beq b5 to bne
-Fixing long branch [750] beq b6 to bne
-Fixing long branch [754] beq b7 to bne
-Fixing long branch [758] beq b8 to bne
-Fixing long branch [744] beq b4 to bne
-Fixing long branch [764] beq b9 to bne
-Fixing long branch [768] beq b10 to bne
-Fixing long branch [772] beq b11 to bne
-Fixing long branch [776] beq b12 to bne
-Fixing long branch [742] beq b3 to bne
-Fixing long branch [782] beq b13 to bne
-Fixing long branch [1317] bmi b2 to bpl
+Fixing long branch [758] beq b5 to bne
+Fixing long branch [762] beq b6 to bne
+Fixing long branch [766] beq b7 to bne
+Fixing long branch [770] beq b8 to bne
+Fixing long branch [756] beq b4 to bne
+Fixing long branch [776] beq b9 to bne
+Fixing long branch [780] beq b10 to bne
+Fixing long branch [784] beq b11 to bne
+Fixing long branch [788] beq b12 to bne
+Fixing long branch [754] beq b3 to bne
+Fixing long branch [794] beq b13 to bne
+Fixing long branch [1339] bmi b2 to bpl
 
 FINAL SYMBOL TABLE
 (label) @68
@@ -29172,12 +29224,15 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG13 [7] *((const byte*) DTV_FEATURE#0) ← (const byte) DTV_FEATURE_ENABLE#0 -- _deref_pbuc1=vbuc2 
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   //SEG14 [8] call keyboard_init 
@@ -29531,9 +29586,11 @@ gfx_mode: {
     lda #0
     sta DTV_PLANEB_MODULO_HI
   //SEG151 [92] *((const byte*) CIA2_PORT_A_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
   //SEG152 [93] *((const byte*) CIA2_PORT_A#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3^((byte))((word))(const byte*) VIC_SCREEN0#0/(word/signed word/dword/signed dword) 16384 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank bits to output - all others to input
     lda #3^VIC_SCREEN0/$4000
     sta CIA2_PORT_A
   //SEG153 [94] (byte) get_vic_screen::idx#0 ← *((const byte*) form_vic_screen#0) -- vbuaa=_deref_pbuc1 
@@ -29583,6 +29640,8 @@ gfx_mode: {
   //SEG171 [108] (byte~) gfx_mode::$71 ← (byte~) gfx_mode::$65 | (byte~) gfx_mode::$70 -- vbuaa=vbuz1_bor_vbuaa 
     ora _65
   //SEG172 [109] *((const byte*) VIC_MEMORY#0) ← (byte~) gfx_mode::$71 -- _deref_pbuc1=vbuaa 
+    //  Set VIC Bank
+    //  VIC memory
     sta VIC_MEMORY
   //SEG173 [110] (byte) get_vic_screen::idx#1 ← *((const byte*) form_vic_cols#0) -- vbuaa=_deref_pbuc1 
     lda form_vic_cols
@@ -29650,6 +29709,7 @@ gfx_mode: {
     bne b10
   //SEG206 gfx_mode::@33
   //SEG207 [123] *((const byte*) BORDERCOL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Background colors
     lda #0
     sta BORDERCOL
   //SEG208 [124] (byte~) gfx_mode::$75 ← *((const byte*) form_vic_bg0_hi#0) << (byte/signed byte/word/signed word/dword/signed dword) 4 -- vbuaa=_deref_pbuc1_rol_4 
@@ -29693,6 +29753,7 @@ gfx_mode: {
   //SEG219 [135] *((const byte*) BGCOL4#0) ← (byte~) gfx_mode::$82 -- _deref_pbuc1=vbuaa 
     sta BGCOL4
   //SEG220 [136] if(*((const byte*) form_dtv_palet#0)==(byte/signed byte/word/signed word/dword/signed dword) 0) goto gfx_mode::@15 -- _deref_pbuc1_eq_0_then_la1 
+    //  DTV Palette
     lda form_dtv_palet
     cmp #0
     beq b18
@@ -29965,6 +30026,7 @@ keyboard_event_scan: {
     beq b7
   //SEG360 keyboard_event_scan::@17
   //SEG361 [203] *((const byte[8]) keyboard_events#0 + (byte) keyboard_events_size#18) ← (byte) keyboard_event_scan::keycode#10 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Key pressed
     lda keycode
     ldy keyboard_events_size
     sta keyboard_events,y
@@ -29984,6 +30046,7 @@ keyboard_event_scan: {
     bne b4
   //SEG369 keyboard_event_scan::@19
   //SEG370 [209] *((const byte[8]) keyboard_scan_values#0 + (byte) keyboard_event_scan::row#2) ← (byte) keyboard_event_scan::row_scan#0 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Store the current keyboard status for the row to debounce
     lda row_scan
     ldy row
     sta keyboard_scan_values,y
@@ -29994,6 +30057,7 @@ keyboard_event_scan: {
     lda #$40
     ora keycode
   //SEG373 [211] *((const byte[8]) keyboard_events#0 + (byte) keyboard_events_size#18) ← (byte/word/dword~) keyboard_event_scan::$11 -- pbuc1_derefidx_vbuz1=vbuaa 
+    //  Key released
     ldy keyboard_events_size
     sta keyboard_events,y
   //SEG374 [212] (byte) keyboard_events_size#1 ← ++ (byte) keyboard_events_size#18 -- vbuz1=_inc_vbuz1 
@@ -30467,33 +30531,42 @@ form_mode: {
     jsr render_preset_name
   //SEG521 form_mode::@29
   //SEG522 [272] *((const byte*) DTV_GRAPHICS_VIC_BANK#0) ← ((byte))((dword))(const byte*) FORM_CHARSET#0/(dword/signed dword) 65536 -- _deref_pbuc1=vbuc2 
+    //  DTV Graphics Bank
     lda #($ffffffff&FORM_CHARSET)/$10000
     sta DTV_GRAPHICS_VIC_BANK
   //SEG523 [273] *((const byte*) DTV_COLOR_BANK_LO#0) ← <((word))(const dword) DTV_COLOR_BANK_DEFAULT#0/(word/signed word/dword/signed dword) 1024 -- _deref_pbuc1=vbuc2 
+    //  DTV Color Bank
     lda #DTV_COLOR_BANK_DEFAULT/$400
     sta DTV_COLOR_BANK_LO
   //SEG524 [274] *((const byte*) DTV_COLOR_BANK_HI#0) ← >((word))(const dword) DTV_COLOR_BANK_DEFAULT#0/(word/signed word/dword/signed dword) 1024 -- _deref_pbuc1=vbuc2 
     lda #0
     sta DTV_COLOR_BANK_HI
   //SEG525 [275] *((const byte*) CIA2_PORT_A_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
   //SEG526 [276] *((const byte*) CIA2_PORT_A#0) ← (byte/signed byte/word/signed word/dword/signed dword) 3^((byte))((word))(const byte*) FORM_CHARSET#0/(word/signed word/dword/signed dword) 16384 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank bits to output - all others to input
     lda #3^FORM_CHARSET/$4000
     sta CIA2_PORT_A
   //SEG527 [277] *((const byte*) DTV_CONTROL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Set VIC Bank
+    //  DTV Graphics Mode
     lda #0
     sta DTV_CONTROL
   //SEG528 [278] *((const byte*) VIC_CONTROL#0) ← (const byte) VIC_DEN#0|(const byte) VIC_RSEL#0|(byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  VIC Graphics Mode
     lda #VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
   //SEG529 [279] *((const byte*) VIC_CONTROL2#0) ← (const byte) VIC_CSEL#0 -- _deref_pbuc1=vbuc2 
     lda #VIC_CSEL
     sta VIC_CONTROL2
   //SEG530 [280] *((const byte*) VIC_MEMORY#0) ← ((byte))((word))(const byte*) FORM_SCREEN#0&(word/signed word/dword/signed dword) 16383/(byte/signed byte/word/signed word/dword/signed dword) 64|((word))(const byte*) FORM_CHARSET#0&(word/signed word/dword/signed dword) 16383/(word/signed word/dword/signed dword) 1024 -- _deref_pbuc1=vbuc2 
+    //  VIC Memory Pointers
     lda #(FORM_SCREEN&$3fff)/$40|(FORM_CHARSET&$3fff)/$400
     sta VIC_MEMORY
   //SEG531 [281] *((const byte*) DTV_PLANEA_START_LO#0) ← <(const byte*) FORM_SCREEN#0 -- _deref_pbuc1=vbuc2 
+    //  DTV Plane A to FORM_SCREEN also
     lda #<FORM_SCREEN
     sta DTV_PLANEA_START_LO
   //SEG532 [282] *((const byte*) DTV_PLANEA_START_MI#0) ← >(const byte*) FORM_SCREEN#0 -- _deref_pbuc1=vbuc2 
@@ -30519,6 +30592,7 @@ form_mode: {
     bne b1
   //SEG542 form_mode::@10
   //SEG543 [288] *((const byte*) BGCOL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Screen colors
     lda #0
     sta BGCOL
   //SEG544 [289] *((const byte*) BORDERCOL#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
@@ -31083,6 +31157,7 @@ form_control: {
     ldy #0
     and (field),y
   //SEG763 [382] *((byte*) form_control::field#0) ← (byte~) form_control::$11 -- _deref_pbuz1=vbuaa 
+    //  Unblink the cursor
     sta (field),y
   //SEG764 [383] (byte~) form_control::$12 ← (byte) keyboard_modifiers#21 & (const byte) KEY_MODIFIER_SHIFT#0 -- vbuaa=vbuz1_band_vbuc1 
     lda #KEY_MODIFIER_SHIFT
@@ -31155,6 +31230,7 @@ form_control: {
   //SEG799 form_control::@12
   b12:
   //SEG800 [400] *((byte*) form_control::field#0) ← *((const byte[]) print_hextab#0 + *((const byte[]) form_fields_val#0 + (byte) form_field_idx#28)) -- _deref_pbuz1=pbuc1_derefidx_pbuc2_derefidx_vbuxx 
+    //  Render field value
     lda form_fields_val,x
     tay
     lda print_hextab,y
@@ -33275,9 +33351,11 @@ gfx_init_screen0: {
 //  Initialize keyboard reading by setting CIA#$ Data Direction Registers
 keyboard_init: {
   //SEG1758 [862] *((const byte*) CIA1_PORT_A_DDR#0) ← (byte/word/signed word/dword/signed dword) 255 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Write Mode
     lda #$ff
     sta CIA1_PORT_A_DDR
   //SEG1759 [863] *((const byte*) CIA1_PORT_B_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Read Mode
     lda #0
     sta CIA1_PORT_B_DDR
   //SEG1760 keyboard_init::@return

src/test/ref/c64dtv-gfxmodes.asm

@@ -101,10 +101,13 @@
   .label print_line_cursor = $d
 main: {
     sei
+    //  Disable normal interrupt (prevent keyboard reading glitches and allows to hide basic/kernal)
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
     lda #PROCPORT_RAM_IO
     sta PROCPORT
+    //  Enable DTV extended modes
     lda #DTV_FEATURE_ENABLE
     sta DTV_FEATURE
   b2:
@@ -115,21 +118,30 @@ menu: {
     .label SCREEN = $8000
     .label CHARSET = $9800
     .label c = 2
+    //  Charset ROM
+    //  DTV Graphics Bank
     lda #($ffffffff&CHARSET)/$10000
     sta DTV_GRAPHICS_VIC_BANK
+    //  DTV Color Bank
     lda #DTV_COLOR_BANK_DEFAULT/$400
     sta DTV_COLOR_BANK_LO
     lda #0
     sta DTV_COLOR_BANK_HI
+    //  DTV Graphics Mode
     sta DTV_CONTROL
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
+    //  Set VIC Bank bits to output - all others to input
     lda #3^CHARSET/$4000
     sta CIA2_PORT_A
+    //  Set VIC Bank
+    //  VIC Graphics Mode
     lda #VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_CSEL
     sta VIC_CONTROL2
+    //  VIC Memory Pointers
     lda #(SCREEN&$3fff)/$40|(CHARSET&$3fff)/$400
     sta VIC_MEMORY
     ldx #0
@@ -157,6 +169,7 @@ menu: {
     lda c
     cmp #<COLS+$3e8
     bne b2
+    //  Screen colors
     lda #0
     sta BGCOL
     sta BORDERCOL
@@ -266,10 +279,12 @@ mode_8bppchunkybmm: {
     .label y = 4
     lda #DTV_HIGHCOLOR|DTV_LINEAR|DTV_CHUNKY|DTV_COLORRAM_OFF
     sta DTV_CONTROL
+    //  VIC Graphics Mode
     lda #VIC_ECM|VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_MCM|VIC_CSEL
     sta VIC_CONTROL2
+    //  Linear Graphics Plane B Counter
     lda #PLANEB&$ffff
     sta DTV_PLANEB_START_LO
     lda #0
@@ -281,6 +296,7 @@ mode_8bppchunkybmm: {
     lda #0
     sta DTV_PLANEB_MODULO_LO
     sta DTV_PLANEB_MODULO_HI
+    //  Border color
     sta BORDERCOL
     tax
   b1:
@@ -364,6 +380,7 @@ mode_ctrl: {
     beq b7
     rts
   b7:
+    //  Read the current control byte
     ldx dtv_control
     ldy #KEY_L
     jsr keyboard_key_pressed
@@ -493,10 +510,12 @@ mode_8bpppixelcell: {
     .label ch = 4
     lda #DTV_HIGHCOLOR|DTV_LINEAR|DTV_CHUNKY
     sta DTV_CONTROL
+    //  VIC Graphics Mode
     lda #VIC_ECM|VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_MCM|VIC_CSEL
     sta VIC_CONTROL2
+    //  Linear Graphics Plane A Counter
     lda #<PLANEA
     sta DTV_PLANEA_START_LO
     lda #>PLANEA
@@ -508,6 +527,7 @@ mode_8bpppixelcell: {
     lda #0
     sta DTV_PLANEA_MODULO_LO
     sta DTV_PLANEA_MODULO_HI
+    //  Linear Graphics Plane B Counter
     lda #<PLANEB
     sta DTV_PLANEB_START_LO
     lda #>PLANEB
@@ -517,6 +537,7 @@ mode_8bpppixelcell: {
     sta DTV_PLANEB_STEP
     sta DTV_PLANEB_MODULO_LO
     sta DTV_PLANEB_MODULO_HI
+    //  Border color
     sta BORDERCOL
     tax
   b1:
@@ -557,6 +578,7 @@ mode_8bpppixelcell: {
     lda ay
     cmp #$19
     bne b2
+    //  8bpp cells for Plane B (charset) - ROM charset with 256 colors
     lda #PROCPORT_RAM_CHARROM
     sta PROCPORT
     lda #0
@@ -636,10 +658,12 @@ mode_sixsfred: {
     .label by = 4
     lda #DTV_HIGHCOLOR|DTV_LINEAR
     sta DTV_CONTROL
+    //  VIC Graphics Mode
     lda #VIC_ECM|VIC_BMM|VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_MCM|VIC_CSEL
     sta VIC_CONTROL2
+    //  Linear Graphics Plane A Counter
     lda #<PLANEA
     sta DTV_PLANEA_START_LO
     lda #>PLANEA
@@ -651,6 +675,7 @@ mode_sixsfred: {
     lda #0
     sta DTV_PLANEA_MODULO_LO
     sta DTV_PLANEA_MODULO_HI
+    //  Linear Graphics Plane B Counter
     lda #<PLANEB
     sta DTV_PLANEB_START_LO
     lda #>PLANEB
@@ -662,6 +687,7 @@ mode_sixsfred: {
     lda #0
     sta DTV_PLANEB_MODULO_LO
     sta DTV_PLANEB_MODULO_HI
+    //  DTV Color Bank
     lda #<COLORS/$400
     sta DTV_COLOR_BANK_LO
     lda #>COLORS/$400
@@ -673,6 +699,7 @@ mode_sixsfred: {
     inx
     cpx #$10
     bne b1
+    //  Screen colors
     lda #0
     sta BORDERCOL
     lda #<COLORS
@@ -779,10 +806,12 @@ mode_twoplanebitmap: {
     .label by = 4
     lda #DTV_HIGHCOLOR|DTV_LINEAR
     sta DTV_CONTROL
+    //  VIC Graphics Mode
     lda #VIC_ECM|VIC_BMM|VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_CSEL
     sta VIC_CONTROL2
+    //  Linear Graphics Plane A Counter
     lda #<PLANEA
     sta DTV_PLANEA_START_LO
     lda #>PLANEA
@@ -794,6 +823,7 @@ mode_twoplanebitmap: {
     lda #0
     sta DTV_PLANEA_MODULO_LO
     sta DTV_PLANEA_MODULO_HI
+    //  Linear Graphics Plane B Counter
     lda #<PLANEB
     sta DTV_PLANEB_START_LO
     lda #>PLANEB
@@ -805,6 +835,7 @@ mode_twoplanebitmap: {
     lda #0
     sta DTV_PLANEB_MODULO_LO
     sta DTV_PLANEB_MODULO_HI
+    //  DTV Color Bank
     lda #<COLORS/$400
     sta DTV_COLOR_BANK_LO
     lda #>COLORS/$400
@@ -816,10 +847,12 @@ mode_twoplanebitmap: {
     inx
     cpx #$10
     bne b1
+    //  Screen colors
     lda #0
     sta BORDERCOL
     lda #$70
     sta BGCOL1
+    //  Color for bits 00
     lda #$d4
     sta BGCOL2
     lda #<COLORS
@@ -938,10 +971,12 @@ mode_sixsfred2: {
     .label by = 4
     lda #DTV_LINEAR
     sta DTV_CONTROL
+    //  VIC Graphics Mode
     lda #VIC_ECM|VIC_BMM|VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_MCM|VIC_CSEL
     sta VIC_CONTROL2
+    //  Linear Graphics Plane A Counter
     lda #<PLANEA
     sta DTV_PLANEA_START_LO
     lda #>PLANEA
@@ -953,6 +988,7 @@ mode_sixsfred2: {
     lda #0
     sta DTV_PLANEA_MODULO_LO
     sta DTV_PLANEA_MODULO_HI
+    //  Linear Graphics Plane B Counter
     lda #<PLANEB
     sta DTV_PLANEB_START_LO
     lda #>PLANEB
@@ -964,6 +1000,7 @@ mode_sixsfred2: {
     lda #0
     sta DTV_PLANEB_MODULO_LO
     sta DTV_PLANEB_MODULO_HI
+    //  DTV Color Bank
     lda #<COLORS/$400
     sta DTV_COLOR_BANK_LO
     lda #>COLORS/$400
@@ -975,6 +1012,7 @@ mode_sixsfred2: {
     inx
     cpx #$10
     bne b1
+    //  Screen colors
     lda #0
     sta BORDERCOL
     lda #<COLORS
@@ -1086,22 +1124,29 @@ mode_hicolmcchar: {
     .label col = 2
     .label ch = 5
     .label cy = 4
+    //  DTV Graphics Bank
     lda #($ffffffff&CHARSET)/$10000
     sta DTV_GRAPHICS_VIC_BANK
+    //  DTV Color Bank
     lda #COLORS/$400
     sta DTV_COLOR_BANK_LO
     lda #0
     sta DTV_COLOR_BANK_HI
     lda #DTV_HIGHCOLOR
     sta DTV_CONTROL
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
+    //  Set VIC Bank bits to output - all others to input
     lda #3^CHARSET/$4000
     sta CIA2_PORT_A
+    //  Set VIC Bank
+    //  VIC Graphics Mode
     lda #VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_CSEL|VIC_MCM
     sta VIC_CONTROL2
+    //  VIC Memory Pointers
     lda #(SCREEN&$3fff)/$40|(CHARSET&$3fff)/$400
     sta VIC_MEMORY
     ldx #0
@@ -1111,6 +1156,7 @@ mode_hicolmcchar: {
     inx
     cpx #$10
     bne b1
+    //  Screen colors
     lda #0
     sta BORDERCOL
     lda #$50
@@ -1186,22 +1232,29 @@ mode_hicolecmchar: {
     .label col = 2
     .label ch = 5
     .label cy = 4
+    //  DTV Graphics Bank
     lda #($ffffffff&CHARSET)/$10000
     sta DTV_GRAPHICS_VIC_BANK
+    //  DTV Color Bank
     lda #COLORS/$400
     sta DTV_COLOR_BANK_LO
     lda #0
     sta DTV_COLOR_BANK_HI
     lda #DTV_HIGHCOLOR
     sta DTV_CONTROL
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
+    //  Set VIC Bank bits to output - all others to input
     lda #3^CHARSET/$4000
     sta CIA2_PORT_A
+    //  Set VIC Bank
+    //  VIC Graphics Mode
     lda #VIC_DEN|VIC_RSEL|VIC_ECM|3
     sta VIC_CONTROL
     lda #VIC_CSEL
     sta VIC_CONTROL2
+    //  VIC Memory Pointers
     lda #(SCREEN&$3fff)/$40|(CHARSET&$3fff)/$400
     sta VIC_MEMORY
     ldx #0
@@ -1211,6 +1264,7 @@ mode_hicolecmchar: {
     inx
     cpx #$10
     bne b1
+    //  Screen colors
     lda #0
     sta BORDERCOL
     lda #$50
@@ -1284,22 +1338,29 @@ mode_hicolstdchar: {
     .label col = 2
     .label ch = 5
     .label cy = 4
+    //  DTV Graphics Bank
     lda #($ffffffff&CHARSET)/$10000
     sta DTV_GRAPHICS_VIC_BANK
+    //  DTV Color Bank
     lda #COLORS/$400
     sta DTV_COLOR_BANK_LO
     lda #0
     sta DTV_COLOR_BANK_HI
     lda #DTV_HIGHCOLOR
     sta DTV_CONTROL
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
+    //  Set VIC Bank bits to output - all others to input
     lda #3^CHARSET/$4000
     sta CIA2_PORT_A
+    //  Set VIC Bank
+    //  VIC Graphics Mode
     lda #VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_CSEL
     sta VIC_CONTROL2
+    //  VIC Memory Pointers
     lda #(SCREEN&$3fff)/$40|(CHARSET&$3fff)/$400
     sta VIC_MEMORY
     ldx #0
@@ -1309,6 +1370,7 @@ mode_hicolstdchar: {
     inx
     cpx #$10
     bne b1
+    //  Screen colors
     lda #0
     sta BGCOL
     sta BORDERCOL
@@ -1374,18 +1436,24 @@ mode_stdbitmap: {
     .label ch = 2
     .label cy = 4
     .label l = 4
+    //  DTV Graphics Bank
     lda #($ffffffff&BITMAP)/$10000
     sta DTV_GRAPHICS_VIC_BANK
     lda #0
     sta DTV_CONTROL
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
+    //  Set VIC Bank bits to output - all others to input
     lda #3^BITMAP/$4000
     sta CIA2_PORT_A
+    //  Set VIC Bank
+    //  VIC Graphics Mode
     lda #VIC_BMM|VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_CSEL
     sta VIC_CONTROL2
+    //  VIC Memory Pointers
     lda #(SCREEN&$3fff)/$40|(BITMAP&$3fff)/$400
     sta VIC_MEMORY
     ldx #0
@@ -1395,6 +1463,7 @@ mode_stdbitmap: {
     inx
     cpx #$10
     bne b1
+    //  Screen colors
     lda #BLACK
     sta BGCOL
     sta BORDERCOL
@@ -1830,21 +1899,28 @@ mode_mcchar: {
     .label col = 2
     .label ch = 5
     .label cy = 4
+    //  DTV Graphics Bank
     lda #($ffffffff&CHARSET)/$10000
     sta DTV_GRAPHICS_VIC_BANK
+    //  DTV Color Bank
     lda #DTV_COLOR_BANK_DEFAULT/$400
     sta DTV_COLOR_BANK_LO
     lda #0
     sta DTV_COLOR_BANK_HI
     sta DTV_CONTROL
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
+    //  Set VIC Bank bits to output - all others to input
     lda #3^CHARSET/$4000
     sta CIA2_PORT_A
+    //  Set VIC Bank
+    //  VIC Graphics Mode
     lda #VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_CSEL|VIC_MCM
     sta VIC_CONTROL2
+    //  VIC Memory Pointers
     lda #(SCREEN&$3fff)/$40|(CHARSET&$3fff)/$400
     sta VIC_MEMORY
     ldx #0
@@ -1854,6 +1930,7 @@ mode_mcchar: {
     inx
     cpx #$10
     bne b1
+    //  Screen colors
     lda #0
     sta BORDERCOL
     lda #BLACK
@@ -1933,21 +2010,28 @@ mode_ecmchar: {
     .label col = 2
     .label ch = 5
     .label cy = 4
+    //  DTV Graphics Bank
     lda #($ffffffff&CHARSET)/$10000
     sta DTV_GRAPHICS_VIC_BANK
+    //  DTV Color Bank
     lda #DTV_COLOR_BANK_DEFAULT/$400
     sta DTV_COLOR_BANK_LO
     lda #0
     sta DTV_COLOR_BANK_HI
     sta DTV_CONTROL
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
+    //  Set VIC Bank bits to output - all others to input
     lda #3^CHARSET/$4000
     sta CIA2_PORT_A
+    //  Set VIC Bank
+    //  VIC Graphics Mode
     lda #VIC_DEN|VIC_RSEL|VIC_ECM|3
     sta VIC_CONTROL
     lda #VIC_CSEL
     sta VIC_CONTROL2
+    //  VIC Memory Pointers
     lda #(SCREEN&$3fff)/$40|(CHARSET&$3fff)/$400
     sta VIC_MEMORY
     ldx #0
@@ -1957,6 +2041,7 @@ mode_ecmchar: {
     inx
     cpx #$10
     bne b1
+    //  Screen colors
     lda #0
     sta BORDERCOL
     sta BGCOL1
@@ -2033,21 +2118,28 @@ mode_stdchar: {
     .label col = 2
     .label ch = 5
     .label cy = 4
+    //  DTV Graphics Bank
     lda #($ffffffff&CHARSET)/$10000
     sta DTV_GRAPHICS_VIC_BANK
+    //  DTV Color Bank
     lda #DTV_COLOR_BANK_DEFAULT/$400
     sta DTV_COLOR_BANK_LO
     lda #0
     sta DTV_COLOR_BANK_HI
     sta DTV_CONTROL
+    //  VIC Graphics Bank
     lda #3
     sta CIA2_PORT_A_DDR
+    //  Set VIC Bank bits to output - all others to input
     lda #3^CHARSET/$4000
     sta CIA2_PORT_A
+    //  Set VIC Bank
+    //  VIC Graphics Mode
     lda #VIC_DEN|VIC_RSEL|3
     sta VIC_CONTROL
     lda #VIC_CSEL
     sta VIC_CONTROL2
+    //  VIC Memory Pointers
     lda #(SCREEN&$3fff)/$40|(CHARSET&$3fff)/$400
     sta VIC_MEMORY
     ldx #0
@@ -2057,6 +2149,7 @@ mode_stdchar: {
     inx
     cpx #$10
     bne b1
+    //  Screen colors
     lda #0
     sta BGCOL
     sta BORDERCOL

src/test/ref/clobber-a-problem.asm

@@ -27,6 +27,7 @@ irq: {
     clc
     adc irq_raster_next
     sta irq_raster_next
+    //  Setup next interrupt
     tax
     txa
     and #7

src/test/ref/clobber-a-problem.log

@@ -318,6 +318,7 @@ irq: {
     adc irq_raster_next
     sta irq_raster_next_1
   //SEG19 [9] (byte) irq::raster_next#0 ← (byte) irq_raster_next#1 -- vbuz1=vbuz2 
+    //  Setup next interrupt
     lda irq_raster_next_1
     sta raster_next
   //SEG20 [10] (byte~) irq::$0 ← (byte) irq::raster_next#0 & (byte/signed byte/word/signed word/dword/signed dword) 7 -- vbuz1=vbuz2_band_vbuc1 
@@ -459,6 +460,7 @@ irq: {
     adc irq_raster_next
     sta irq_raster_next
   //SEG19 [9] (byte) irq::raster_next#0 ← (byte) irq_raster_next#1 -- vbuxx=vbuz1 
+    //  Setup next interrupt
     ldx irq_raster_next
   //SEG20 [10] (byte~) irq::$0 ← (byte) irq::raster_next#0 & (byte/signed byte/word/signed word/dword/signed dword) 7 -- vbuaa=vbuxx_band_vbuc1 
     txa
@@ -605,6 +607,7 @@ irq: {
     adc irq_raster_next
     sta irq_raster_next
   //SEG19 [9] (byte) irq::raster_next#0 ← (byte) irq_raster_next#1 -- vbuxx=vbuz1 
+    //  Setup next interrupt
     tax
   //SEG20 [10] (byte~) irq::$0 ← (byte) irq::raster_next#0 & (byte/signed byte/word/signed word/dword/signed dword) 7 -- vbuaa=vbuxx_band_vbuc1 
     txa

src/test/ref/complex/tetris/test-sprites.asm

@@ -68,14 +68,19 @@
   .label irq_cnt = 8
   .label sin_idx = 2
 bbegin:
+  //  The screen currently being showed to the user. $00 for screen 1 / $40 for screen 2.
   lda #0
   sta render_screen_showing
+  //  The raster line of the next IRQ
   lda #IRQ_RASTER_FIRST
   sta irq_raster_next
+  //  Y-pos of the sprites on the next IRQ
   lda #SPRITES_FIRST_YPOS+$15
   sta irq_sprite_ypos
+  //  Index of the sprites to show on the next IRQ
   lda #toSpritePtr1_return+3
   sta irq_sprite_ptr
+  //  Counting the 10 IRQs
   lda #0
   sta irq_cnt
   jsr main
@@ -161,22 +166,28 @@ loop: {
 //  Setup the IRQ
 sprites_irq_init: {
     sei
+    //  Acknowledge any IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
     lda CIA1_INTERRUPT
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
     lda #PROCPORT_RAM_IO
     sta PROCPORT
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
+    //  Set raster line
     lda VIC_CONTROL
     and #$7f
     sta VIC_CONTROL
     lda #IRQ_RASTER_FIRST
     sta RASTER
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
+    //  Set the IRQ routine
     lda #<sprites_irq
     sta HARDWARE_IRQ
     lda #>sprites_irq
@@ -221,7 +232,10 @@ sprites_irq: {
     .label raster_sprite_gfx_modify = $a
     sta rega+1
     stx regx+1
+    // (*BGCOL)++;
+    //  Clear decimal flag (because it is used by the score algorithm)
     cld
+    //  Place the sprites
     lda irq_sprite_ypos
     sta SPRITES_YPOS
     sta SPRITES_YPOS+2
@@ -229,6 +243,7 @@ sprites_irq: {
     sta SPRITES_YPOS+6
     ldx irq_raster_next
     inx
+    //  Wait for the y-position before changing sprite pointers
     stx raster_sprite_gfx_modify
   b1:
     lda RASTER
@@ -267,8 +282,10 @@ sprites_irq: {
     adc irq_sprite_ptr
     sta irq_sprite_ptr
   b7:
+    //  Setup next interrupt
     lda irq_raster_next
     sta RASTER
+    //  Acknowledge the IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
   rega:

src/test/ref/complex/tetris/test-sprites.log

@@ -2275,6 +2275,7 @@ bbegin:
 //SEG4 @4
 b4:
 //SEG5 [1] (byte) render_screen_showing#0 ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- vbuz1=vbuc1 
+  //  The screen currently being showed to the user. $00 for screen 1 / $40 for screen 2.
   lda #0
   sta render_screen_showing
 //SEG6 kickasm(location (const byte*) PLAYFIELD_SPRITES#0) {{ .var sprites = LoadPicture("playfield-sprites.png", List().add($010101, $000000)) 	// Put the sprites into memory  	.for(var sy=0;sy<10;sy++) { 	    .var sprite_gfx_y = sy*20 		.for(var sx=0;sx<3;sx++) { 	    	.for (var y=0;y<21; y++) { 	    	    .var gfx_y =  sprite_gfx_y + mod(2100+y-sprite_gfx_y,21) 		    	.for (var c=0; c<3; c++) { 	            	.byte sprites.getSinglecolorByte(sx*3+c,gfx_y) 	            } 	        } 	    	.byte 0 	  	} 	}  }}
@@ -2282,9 +2283,11 @@ b4:
 //SEG7 @5
 b5:
 //SEG8 [3] (byte) irq_raster_next#0 ← (const byte) IRQ_RASTER_FIRST#0 -- vbuz1=vbuc1 
+  //  The raster line of the next IRQ
   lda #IRQ_RASTER_FIRST
   sta irq_raster_next
 //SEG9 [4] (byte) irq_sprite_ypos#0 ← (const byte) SPRITES_FIRST_YPOS#0+(byte/signed byte/word/signed word/dword/signed dword) 21 -- vbuz1=vbuc1 
+  //  Y-pos of the sprites on the next IRQ
   lda #SPRITES_FIRST_YPOS+$15
   sta irq_sprite_ypos
 //SEG10 [5] phi from @5 to toSpritePtr1 [phi:@5->toSpritePtr1]
@@ -2296,9 +2299,11 @@ toSpritePtr1:
 //SEG12 @10
 b10:
 //SEG13 [6] (byte) irq_sprite_ptr#0 ← (const byte) toSpritePtr1_return#0+(byte/signed byte/word/signed word/dword/signed dword) 3 -- vbuz1=vbuc1 
+  //  Index of the sprites to show on the next IRQ
   lda #toSpritePtr1_return+3
   sta irq_sprite_ptr
 //SEG14 [7] (byte) irq_cnt#0 ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- vbuz1=vbuc1 
+  //  Counting the 10 IRQs
   lda #0
   sta irq_cnt
   jmp b7
@@ -2533,20 +2538,24 @@ sprites_irq_init: {
   //SEG94 asm { sei  }
     sei
   //SEG95 [50] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge any IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG96 asm { ldaCIA1_INTERRUPT  }
     lda CIA1_INTERRUPT
   //SEG97 [52] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG98 [53] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG99 [54] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG100 [55] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) & (byte/signed byte/word/signed word/dword/signed dword) 127 -- _deref_pbuc1=_deref_pbuc1_band_vbuc2 
+    //  Set raster line
     lda VIC_CONTROL
     and #$7f
     sta VIC_CONTROL
@@ -2554,9 +2563,11 @@ sprites_irq_init: {
     lda #IRQ_RASTER_FIRST
     sta RASTER
   //SEG102 [57] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG103 [58] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_CLOBBER)(void()) sprites_irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<sprites_irq
     sta HARDWARE_IRQ
     lda #>sprites_irq
@@ -2651,8 +2662,11 @@ sprites_irq: {
     stx regx+1
     sty regy+1
   //SEG129 asm { cld  }
+    // (*BGCOL)++;
+    //  Clear decimal flag (because it is used by the score algorithm)
     cld
   //SEG130 [74] (byte) sprites_irq::ypos#0 ← (byte) irq_sprite_ypos#0 -- vbuz1=vbuz2 
+    //  Place the sprites
     lda irq_sprite_ypos
     sta ypos
   //SEG131 [75] *((const byte*) SPRITES_YPOS#0) ← (byte) sprites_irq::ypos#0 -- _deref_pbuc1=vbuz1 
@@ -2672,6 +2686,7 @@ sprites_irq: {
     iny
     sty _0
   //SEG136 [80] (byte) sprites_irq::raster_sprite_gfx_modify#0 ← (byte/signed word/word/dword/signed dword~) sprites_irq::$0 -- vbuz1=vbuz2 
+    //  Wait for the y-position before changing sprite pointers
     lda _0
     sta raster_sprite_gfx_modify
     jmp b1
@@ -2759,9 +2774,11 @@ sprites_irq: {
   //SEG160 sprites_irq::@7
   b7:
   //SEG161 [97] *((const byte*) RASTER#0) ← (byte) irq_raster_next#4 -- _deref_pbuc1=vbuz1 
+    //  Setup next interrupt
     lda irq_raster_next_4
     sta RASTER
   //SEG162 [98] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -3191,6 +3208,7 @@ bbegin:
 //SEG4 @4
 b4:
 //SEG5 [1] (byte) render_screen_showing#0 ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- vbuz1=vbuc1 
+  //  The screen currently being showed to the user. $00 for screen 1 / $40 for screen 2.
   lda #0
   sta render_screen_showing
 //SEG6 kickasm(location (const byte*) PLAYFIELD_SPRITES#0) {{ .var sprites = LoadPicture("playfield-sprites.png", List().add($010101, $000000)) 	// Put the sprites into memory  	.for(var sy=0;sy<10;sy++) { 	    .var sprite_gfx_y = sy*20 		.for(var sx=0;sx<3;sx++) { 	    	.for (var y=0;y<21; y++) { 	    	    .var gfx_y =  sprite_gfx_y + mod(2100+y-sprite_gfx_y,21) 		    	.for (var c=0; c<3; c++) { 	            	.byte sprites.getSinglecolorByte(sx*3+c,gfx_y) 	            } 	        } 	    	.byte 0 	  	} 	}  }}
@@ -3198,9 +3216,11 @@ b4:
 //SEG7 @5
 b5:
 //SEG8 [3] (byte) irq_raster_next#0 ← (const byte) IRQ_RASTER_FIRST#0 -- vbuz1=vbuc1 
+  //  The raster line of the next IRQ
   lda #IRQ_RASTER_FIRST
   sta irq_raster_next
 //SEG9 [4] (byte) irq_sprite_ypos#0 ← (const byte) SPRITES_FIRST_YPOS#0+(byte/signed byte/word/signed word/dword/signed dword) 21 -- vbuz1=vbuc1 
+  //  Y-pos of the sprites on the next IRQ
   lda #SPRITES_FIRST_YPOS+$15
   sta irq_sprite_ypos
 //SEG10 [5] phi from @5 to toSpritePtr1 [phi:@5->toSpritePtr1]
@@ -3212,9 +3232,11 @@ toSpritePtr1:
 //SEG12 @10
 b10:
 //SEG13 [6] (byte) irq_sprite_ptr#0 ← (const byte) toSpritePtr1_return#0+(byte/signed byte/word/signed word/dword/signed dword) 3 -- vbuz1=vbuc1 
+  //  Index of the sprites to show on the next IRQ
   lda #toSpritePtr1_return+3
   sta irq_sprite_ptr
 //SEG14 [7] (byte) irq_cnt#0 ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- vbuz1=vbuc1 
+  //  Counting the 10 IRQs
   lda #0
   sta irq_cnt
   jmp b7
@@ -3435,20 +3457,24 @@ sprites_irq_init: {
   //SEG94 asm { sei  }
     sei
   //SEG95 [50] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge any IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG96 asm { ldaCIA1_INTERRUPT  }
     lda CIA1_INTERRUPT
   //SEG97 [52] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG98 [53] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG99 [54] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG100 [55] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) & (byte/signed byte/word/signed word/dword/signed dword) 127 -- _deref_pbuc1=_deref_pbuc1_band_vbuc2 
+    //  Set raster line
     lda VIC_CONTROL
     and #$7f
     sta VIC_CONTROL
@@ -3456,9 +3482,11 @@ sprites_irq_init: {
     lda #IRQ_RASTER_FIRST
     sta RASTER
   //SEG102 [57] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG103 [58] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_CLOBBER)(void()) sprites_irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<sprites_irq
     sta HARDWARE_IRQ
     lda #>sprites_irq
@@ -3539,8 +3567,11 @@ sprites_irq: {
     sta rega+1
     stx regx+1
   //SEG129 asm { cld  }
+    // (*BGCOL)++;
+    //  Clear decimal flag (because it is used by the score algorithm)
     cld
   //SEG130 [74] (byte) sprites_irq::ypos#0 ← (byte) irq_sprite_ypos#0 -- vbuaa=vbuz1 
+    //  Place the sprites
     lda irq_sprite_ypos
   //SEG131 [75] *((const byte*) SPRITES_YPOS#0) ← (byte) sprites_irq::ypos#0 -- _deref_pbuc1=vbuaa 
     sta SPRITES_YPOS
@@ -3554,6 +3585,7 @@ sprites_irq: {
     ldx irq_raster_next
     inx
   //SEG136 [80] (byte) sprites_irq::raster_sprite_gfx_modify#0 ← (byte/signed word/word/dword/signed dword~) sprites_irq::$0 -- vbuz1=vbuxx 
+    //  Wait for the y-position before changing sprite pointers
     stx raster_sprite_gfx_modify
     jmp b1
   //SEG137 sprites_irq::@1
@@ -3632,9 +3664,11 @@ sprites_irq: {
   //SEG160 sprites_irq::@7
   b7:
   //SEG161 [97] *((const byte*) RASTER#0) ← (byte) irq_raster_next#4 -- _deref_pbuc1=vbuz1 
+    //  Setup next interrupt
     lda irq_raster_next
     sta RASTER
   //SEG162 [98] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -4237,23 +4271,28 @@ Score: 7709
 bbegin:
 //SEG4 @4
 //SEG5 [1] (byte) render_screen_showing#0 ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- vbuz1=vbuc1 
+  //  The screen currently being showed to the user. $00 for screen 1 / $40 for screen 2.
   lda #0
   sta render_screen_showing
 //SEG6 kickasm(location (const byte*) PLAYFIELD_SPRITES#0) {{ .var sprites = LoadPicture("playfield-sprites.png", List().add($010101, $000000)) 	// Put the sprites into memory  	.for(var sy=0;sy<10;sy++) { 	    .var sprite_gfx_y = sy*20 		.for(var sx=0;sx<3;sx++) { 	    	.for (var y=0;y<21; y++) { 	    	    .var gfx_y =  sprite_gfx_y + mod(2100+y-sprite_gfx_y,21) 		    	.for (var c=0; c<3; c++) { 	            	.byte sprites.getSinglecolorByte(sx*3+c,gfx_y) 	            } 	        } 	    	.byte 0 	  	} 	}  }}
 //SEG7 @5
 //SEG8 [3] (byte) irq_raster_next#0 ← (const byte) IRQ_RASTER_FIRST#0 -- vbuz1=vbuc1 
+  //  The raster line of the next IRQ
   lda #IRQ_RASTER_FIRST
   sta irq_raster_next
 //SEG9 [4] (byte) irq_sprite_ypos#0 ← (const byte) SPRITES_FIRST_YPOS#0+(byte/signed byte/word/signed word/dword/signed dword) 21 -- vbuz1=vbuc1 
+  //  Y-pos of the sprites on the next IRQ
   lda #SPRITES_FIRST_YPOS+$15
   sta irq_sprite_ypos
 //SEG10 [5] phi from @5 to toSpritePtr1 [phi:@5->toSpritePtr1]
 //SEG11 toSpritePtr1
 //SEG12 @10
 //SEG13 [6] (byte) irq_sprite_ptr#0 ← (const byte) toSpritePtr1_return#0+(byte/signed byte/word/signed word/dword/signed dword) 3 -- vbuz1=vbuc1 
+  //  Index of the sprites to show on the next IRQ
   lda #toSpritePtr1_return+3
   sta irq_sprite_ptr
 //SEG14 [7] (byte) irq_cnt#0 ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- vbuz1=vbuc1 
+  //  Counting the 10 IRQs
   lda #0
   sta irq_cnt
 //SEG15 @7
@@ -4420,20 +4459,24 @@ sprites_irq_init: {
   //SEG94 asm { sei  }
     sei
   //SEG95 [50] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge any IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG96 asm { ldaCIA1_INTERRUPT  }
     lda CIA1_INTERRUPT
   //SEG97 [52] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG98 [53] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG99 [54] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG100 [55] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) & (byte/signed byte/word/signed word/dword/signed dword) 127 -- _deref_pbuc1=_deref_pbuc1_band_vbuc2 
+    //  Set raster line
     lda VIC_CONTROL
     and #$7f
     sta VIC_CONTROL
@@ -4441,9 +4484,11 @@ sprites_irq_init: {
     lda #IRQ_RASTER_FIRST
     sta RASTER
   //SEG102 [57] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG103 [58] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_CLOBBER)(void()) sprites_irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<sprites_irq
     sta HARDWARE_IRQ
     lda #>sprites_irq
@@ -4514,8 +4559,11 @@ sprites_irq: {
     sta rega+1
     stx regx+1
   //SEG129 asm { cld  }
+    // (*BGCOL)++;
+    //  Clear decimal flag (because it is used by the score algorithm)
     cld
   //SEG130 [74] (byte) sprites_irq::ypos#0 ← (byte) irq_sprite_ypos#0 -- vbuaa=vbuz1 
+    //  Place the sprites
     lda irq_sprite_ypos
   //SEG131 [75] *((const byte*) SPRITES_YPOS#0) ← (byte) sprites_irq::ypos#0 -- _deref_pbuc1=vbuaa 
     sta SPRITES_YPOS
@@ -4529,6 +4577,7 @@ sprites_irq: {
     ldx irq_raster_next
     inx
   //SEG136 [80] (byte) sprites_irq::raster_sprite_gfx_modify#0 ← (byte/signed word/word/dword/signed dword~) sprites_irq::$0 -- vbuz1=vbuxx 
+    //  Wait for the y-position before changing sprite pointers
     stx raster_sprite_gfx_modify
   //SEG137 sprites_irq::@1
   b1:
@@ -4592,9 +4641,11 @@ sprites_irq: {
   //SEG160 sprites_irq::@7
   b7:
   //SEG161 [97] *((const byte*) RASTER#0) ← (byte) irq_raster_next#4 -- _deref_pbuc1=vbuz1 
+    //  Setup next interrupt
     lda irq_raster_next
     sta RASTER
   //SEG162 [98] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG163 sprites_irq::@return

src/test/ref/complex/tetris/tetris.asm

@@ -163,14 +163,20 @@
   .label current_piece_101 = 5
   .label current_piece_102 = 5
 bbegin:
+  //  The screen currently being showed to the user. $00 for screen 1 / $40 for screen 2.
   lda #0
   sta render_screen_showing
+//  Original Color Data
+  //  The raster line of the next IRQ
   lda #IRQ_RASTER_FIRST
   sta irq_raster_next
+  //  Y-pos of the sprites on the next IRQ
   lda #SPRITES_FIRST_YPOS+$15
   sta irq_sprite_ypos
+  //  Index of the sprites to show on the next IRQ
   lda #toSpritePtr1_return+3
   sta irq_sprite_ptr
+  //  Counting the 10 IRQs
   lda #0
   sta irq_cnt
   jsr main
@@ -739,6 +745,7 @@ play_collision: {
 //  Move left/right or rotate the current piece
 //  Return non-zero if a render is needed
 play_move_leftright: {
+    //  Handle keyboard events
     cmp #KEY_COMMA
     beq b1
     cmp #KEY_DOT
@@ -853,6 +860,7 @@ play_move_down: {
 play_spawn_current: {
     .label _0 = 4
     .label piece_idx = $21
+    //  Move next piece into current
     ldx next_piece_idx
     txa
     asl
@@ -956,6 +964,7 @@ play_update_score: {
 //  Increase the level
 play_increase_level: {
     inc level
+    //  Update speed of moving tetrominos down
     lda level
     cmp #$1d
     beq !+
@@ -974,11 +983,13 @@ play_increase_level: {
     and level_bcd
     cmp #$a
     bne b3
+    //  If level low nybble hits $a change to $10
     lda #6
     clc
     adc level_bcd
     sta level_bcd
   b3:
+    //  Increase the score values gained
     sed
     ldx #0
   b4:
@@ -1238,6 +1249,7 @@ keyboard_event_scan: {
     and row_scan
     cmp #0
     beq b7
+    //  Key pressed
     lda keycode
     ldy keyboard_events_size
     sta keyboard_events,y
@@ -1247,6 +1259,7 @@ keyboard_event_scan: {
     inx
     cpx #8
     bne b4
+    //  Store the current keyboard status for the row to debounce
     lda row_scan
     ldy row
     sta keyboard_scan_values,y
@@ -1254,6 +1267,7 @@ keyboard_event_scan: {
   b7:
     lda #$40
     ora keycode
+    //  Key released
     ldy keyboard_events_size
     sta keyboard_events,y
     inc keyboard_events_size
@@ -1330,6 +1344,7 @@ play_init: {
     bne b1
     lda #PLAYFIELD_COLS*PLAYFIELD_LINES
     sta playfield_lines_idx+PLAYFIELD_LINES
+    //  Set initial speed of moving down a tetromino
     lda MOVEDOWN_SLOW_SPEEDS
     sta current_movedown_slow
     ldx #0
@@ -1354,22 +1369,28 @@ play_init: {
 //  Setup the IRQ
 sprites_irq_init: {
     sei
+    //  Acknowledge any IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
     lda CIA1_INTERRUPT
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
     lda #PROCPORT_RAM_IO
     sta PROCPORT
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
+    //  Set raster line
     lda VIC_CONTROL
     and #$7f
     sta VIC_CONTROL
     lda #IRQ_RASTER_FIRST
     sta RASTER
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
+    //  Set the IRQ routine
     lda #<sprites_irq
     sta HARDWARE_IRQ
     lda #>sprites_irq
@@ -1415,6 +1436,7 @@ render_init: {
     sta CIA2_PORT_A_DDR
     lda #vicSelectGfxBank1_toDd001_return
     sta CIA2_PORT_A
+    //  Enable Extended Background Color Mode
     lda #VIC_ECM|VIC_DEN|VIC_RSEL|3
     sta D011
     lda #BLACK
@@ -1590,7 +1612,10 @@ sprites_irq: {
     .label raster_sprite_gfx_modify = $2f
     sta rega+1
     stx regx+1
+    // (*BGCOL)++;
+    //  Clear decimal flag (because it is used by the score algorithm)
     cld
+    //  Place the sprites
     lda irq_sprite_ypos
     sta SPRITES_YPOS
     sta SPRITES_YPOS+2
@@ -1598,6 +1623,7 @@ sprites_irq: {
     sta SPRITES_YPOS+6
     ldx irq_raster_next
     inx
+    //  Wait for the y-position before changing sprite pointers
     stx raster_sprite_gfx_modify
   b1:
     lda RASTER
@@ -1636,8 +1662,10 @@ sprites_irq: {
     adc irq_sprite_ptr
     sta irq_sprite_ptr
   b7:
+    //  Setup next interrupt
     lda irq_raster_next
     sta RASTER
+    //  Acknowledge the IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
   rega:

src/test/ref/complex/tetris/tetris.log

@@ -13006,11 +13006,13 @@ bbegin:
 //SEG4 @14
 b14:
 //SEG5 [1] (byte) render_screen_showing#0 ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- vbuz1=vbuc1 
+  //  The screen currently being showed to the user. $00 for screen 1 / $40 for screen 2.
   lda #0
   sta render_screen_showing
 //SEG6 kickasm(location (const byte*) PLAYFIELD_CHARSET#0) {{ .fill 8,$00 // Place a filled char at the start of the charset     .import binary "playfield-screen.imap"  }}
 //SEG7 kickasm(location (const byte*) PLAYFIELD_SCREEN_ORIGINAL#0) {{ // Load chars for the screen   .var screen = LoadBinary("playfield-screen.iscr")    // Load extended colors for the screen   .var extended = LoadBinary("playfield-extended.col")   // screen.get(i)+1 because the charset is loaded into PLAYFIELD_CHARSET+8   // extended.get(i)-1 because the extended colors are 1-based (1/2/3/4)   // <<6 to move extended colors to the upper 2 bits   .fill screen.getSize(), ( (screen.get(i)+1) | (extended.get(i)-1)<<6 )  }}
 //SEG8 kickasm(location (const byte*) PLAYFIELD_COLORS_ORIGINAL#0) {{ .import binary "playfield-screen.col"  }}
+  //  Original Color Data
   jmp b23
 //SEG9 @23
 b23:
@@ -13019,9 +13021,11 @@ b23:
 //SEG11 @24
 b24:
 //SEG12 [6] (byte) irq_raster_next#0 ← (const byte) IRQ_RASTER_FIRST#0 -- vbuz1=vbuc1 
+  //  The raster line of the next IRQ
   lda #IRQ_RASTER_FIRST
   sta irq_raster_next
 //SEG13 [7] (byte) irq_sprite_ypos#0 ← (const byte) SPRITES_FIRST_YPOS#0+(byte/signed byte/word/signed word/dword/signed dword) 21 -- vbuz1=vbuc1 
+  //  Y-pos of the sprites on the next IRQ
   lda #SPRITES_FIRST_YPOS+$15
   sta irq_sprite_ypos
 //SEG14 [8] phi from @24 to toSpritePtr1 [phi:@24->toSpritePtr1]
@@ -13033,9 +13037,11 @@ toSpritePtr1:
 //SEG16 @39
 b39:
 //SEG17 [9] (byte) irq_sprite_ptr#0 ← (const byte) toSpritePtr1_return#0+(byte/signed byte/word/signed word/dword/signed dword) 3 -- vbuz1=vbuc1 
+  //  Index of the sprites to show on the next IRQ
   lda #toSpritePtr1_return+3
   sta irq_sprite_ptr
 //SEG18 [10] (byte) irq_cnt#0 ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- vbuz1=vbuc1 
+  //  Counting the 10 IRQs
   lda #0
   sta irq_cnt
 //SEG19 [11] phi from @39 to @38 [phi:@39->@38]
@@ -14476,6 +14482,7 @@ play_move_leftright: {
     .label return = $94
     .label return_2 = $36
   //SEG521 [225] if((byte) play_move_leftright::key_event#0==(const byte) KEY_COMMA#0) goto play_move_leftright::@1 -- vbuz1_eq_vbuc1_then_la1 
+    //  Handle keyboard events
     lda key_event
     cmp #KEY_COMMA
     beq b1
@@ -14875,6 +14882,7 @@ play_spawn_current: {
     .label current_piece_idx = $af
     .label piece_idx = $4a
   //SEG697 [286] (byte) play_spawn_current::current_piece_idx#0 ← (byte) next_piece_idx#17 -- vbuz1=vbuz2 
+    //  Move next piece into current
     lda next_piece_idx
     sta current_piece_idx
   //SEG698 [287] (byte~) play_spawn_current::$0 ← (byte) play_spawn_current::current_piece_idx#0 << (byte/signed byte/word/signed word/dword/signed dword) 1 -- vbuz1=vbuz2_rol_1 
@@ -15115,6 +15123,7 @@ play_increase_level: {
   //SEG768 [327] (byte) level#21 ← ++ (byte) level#10 -- vbuz1=_inc_vbuz1 
     inc level
   //SEG769 [328] if((byte) level#21>(byte/signed byte/word/signed word/dword/signed dword) 29) goto play_increase_level::@2 -- vbuz1_gt_vbuc1_then_la1 
+    //  Update speed of moving tetrominos down
     lda level
     cmp #$1d
     beq !+
@@ -15153,6 +15162,7 @@ play_increase_level: {
   //SEG780 play_increase_level::@7
   b7:
   //SEG781 [334] (byte) level_bcd#8 ← (byte) level_bcd#21 + (byte/signed byte/word/signed word/dword/signed dword) 6 -- vbuz1=vbuz1_plus_vbuc1 
+    //  If level low nybble hits $a change to $10
     lda #6
     clc
     adc level_bcd
@@ -15165,6 +15175,7 @@ play_increase_level: {
   //SEG784 play_increase_level::@3
   b3:
   //SEG785 asm { sed  }
+    //  Increase the score values gained
     sed
   //SEG786 [337] phi from play_increase_level::@3 to play_increase_level::@4 [phi:play_increase_level::@3->play_increase_level::@4]
   b4_from_b3:
@@ -15836,6 +15847,7 @@ keyboard_event_scan: {
   //SEG1008 keyboard_event_scan::@17
   b17:
   //SEG1009 [438] *((const byte[8]) keyboard_events#0 + (byte) keyboard_events_size#10) ← (byte) keyboard_event_scan::keycode#10 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Key pressed
     lda keycode
     ldy keyboard_events_size
     sta keyboard_events,y
@@ -15862,6 +15874,7 @@ keyboard_event_scan: {
   //SEG1017 keyboard_event_scan::@19
   b19:
   //SEG1018 [444] *((const byte[8]) keyboard_scan_values#0 + (byte) keyboard_event_scan::row#2) ← (byte) keyboard_event_scan::row_scan#0 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Store the current keyboard status for the row to debounce
     lda row_scan
     ldy row
     sta keyboard_scan_values,y
@@ -15873,6 +15886,7 @@ keyboard_event_scan: {
     ora keycode
     sta _11
   //SEG1021 [446] *((const byte[8]) keyboard_events#0 + (byte) keyboard_events_size#10) ← (byte/word/dword~) keyboard_event_scan::$11 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Key released
     lda _11
     ldy keyboard_events_size
     sta keyboard_events,y
@@ -16029,6 +16043,7 @@ play_init: {
     lda #PLAYFIELD_COLS*PLAYFIELD_LINES
     sta playfield_lines_idx+PLAYFIELD_LINES
   //SEG1064 [470] (byte) current_movedown_slow#1 ← *((const byte[]) MOVEDOWN_SLOW_SPEEDS#0) -- vbuz1=_deref_pbuc1 
+    //  Set initial speed of moving down a tetromino
     lda MOVEDOWN_SLOW_SPEEDS
     sta current_movedown_slow
   //SEG1065 [471] phi from play_init::@3 to play_init::@2 [phi:play_init::@3->play_init::@2]
@@ -16076,20 +16091,24 @@ sprites_irq_init: {
   //SEG1077 asm { sei  }
     sei
   //SEG1078 [478] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge any IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG1079 asm { ldaCIA1_INTERRUPT  }
     lda CIA1_INTERRUPT
   //SEG1080 [480] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG1081 [481] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG1082 [482] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG1083 [483] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) & (byte/signed byte/word/signed word/dword/signed dword) 127 -- _deref_pbuc1=_deref_pbuc1_band_vbuc2 
+    //  Set raster line
     lda VIC_CONTROL
     and #$7f
     sta VIC_CONTROL
@@ -16097,9 +16116,11 @@ sprites_irq_init: {
     lda #IRQ_RASTER_FIRST
     sta RASTER
   //SEG1085 [485] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG1086 [486] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_CLOBBER)(void()) sprites_irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<sprites_irq
     sta HARDWARE_IRQ
     lda #>sprites_irq
@@ -16205,6 +16226,7 @@ render_init: {
   //SEG1117 render_init::@3
   b3:
   //SEG1118 [505] *((const byte*) D011#0) ← (const byte) VIC_ECM#0|(const byte) VIC_DEN#0|(const byte) VIC_RSEL#0|(byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  Enable Extended Background Color Mode
     lda #VIC_ECM|VIC_DEN|VIC_RSEL|3
     sta D011
   //SEG1119 [506] *((const byte*) BORDERCOL#0) ← (const byte) BLACK#0 -- _deref_pbuc1=vbuc2 
@@ -16531,8 +16553,11 @@ sprites_irq: {
     stx regx+1
     sty regy+1
   //SEG1218 asm { cld  }
+    // (*BGCOL)++;
+    //  Clear decimal flag (because it is used by the score algorithm)
     cld
   //SEG1219 [556] (byte) sprites_irq::ypos#0 ← (byte) irq_sprite_ypos#0 -- vbuz1=vbuz2 
+    //  Place the sprites
     lda irq_sprite_ypos
     sta ypos
   //SEG1220 [557] *((const byte*) SPRITES_YPOS#0) ← (byte) sprites_irq::ypos#0 -- _deref_pbuc1=vbuz1 
@@ -16552,6 +16577,7 @@ sprites_irq: {
     iny
     sty _0
   //SEG1225 [562] (byte) sprites_irq::raster_sprite_gfx_modify#0 ← (byte/signed word/word/dword/signed dword~) sprites_irq::$0 -- vbuz1=vbuz2 
+    //  Wait for the y-position before changing sprite pointers
     lda _0
     sta raster_sprite_gfx_modify
     jmp b1
@@ -16639,9 +16665,11 @@ sprites_irq: {
   //SEG1249 sprites_irq::@7
   b7:
   //SEG1250 [579] *((const byte*) RASTER#0) ← (byte) irq_raster_next#4 -- _deref_pbuc1=vbuz1 
+    //  Setup next interrupt
     lda irq_raster_next_4
     sta RASTER
   //SEG1251 [580] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -18222,11 +18250,13 @@ bbegin:
 //SEG4 @14
 b14:
 //SEG5 [1] (byte) render_screen_showing#0 ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- vbuz1=vbuc1 
+  //  The screen currently being showed to the user. $00 for screen 1 / $40 for screen 2.
   lda #0
   sta render_screen_showing
 //SEG6 kickasm(location (const byte*) PLAYFIELD_CHARSET#0) {{ .fill 8,$00 // Place a filled char at the start of the charset     .import binary "playfield-screen.imap"  }}
 //SEG7 kickasm(location (const byte*) PLAYFIELD_SCREEN_ORIGINAL#0) {{ // Load chars for the screen   .var screen = LoadBinary("playfield-screen.iscr")    // Load extended colors for the screen   .var extended = LoadBinary("playfield-extended.col")   // screen.get(i)+1 because the charset is loaded into PLAYFIELD_CHARSET+8   // extended.get(i)-1 because the extended colors are 1-based (1/2/3/4)   // <<6 to move extended colors to the upper 2 bits   .fill screen.getSize(), ( (screen.get(i)+1) | (extended.get(i)-1)<<6 )  }}
 //SEG8 kickasm(location (const byte*) PLAYFIELD_COLORS_ORIGINAL#0) {{ .import binary "playfield-screen.col"  }}
+  //  Original Color Data
   jmp b23
 //SEG9 @23
 b23:
@@ -18235,9 +18265,11 @@ b23:
 //SEG11 @24
 b24:
 //SEG12 [6] (byte) irq_raster_next#0 ← (const byte) IRQ_RASTER_FIRST#0 -- vbuz1=vbuc1 
+  //  The raster line of the next IRQ
   lda #IRQ_RASTER_FIRST
   sta irq_raster_next
 //SEG13 [7] (byte) irq_sprite_ypos#0 ← (const byte) SPRITES_FIRST_YPOS#0+(byte/signed byte/word/signed word/dword/signed dword) 21 -- vbuz1=vbuc1 
+  //  Y-pos of the sprites on the next IRQ
   lda #SPRITES_FIRST_YPOS+$15
   sta irq_sprite_ypos
 //SEG14 [8] phi from @24 to toSpritePtr1 [phi:@24->toSpritePtr1]
@@ -18249,9 +18281,11 @@ toSpritePtr1:
 //SEG16 @39
 b39:
 //SEG17 [9] (byte) irq_sprite_ptr#0 ← (const byte) toSpritePtr1_return#0+(byte/signed byte/word/signed word/dword/signed dword) 3 -- vbuz1=vbuc1 
+  //  Index of the sprites to show on the next IRQ
   lda #toSpritePtr1_return+3
   sta irq_sprite_ptr
 //SEG18 [10] (byte) irq_cnt#0 ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- vbuz1=vbuc1 
+  //  Counting the 10 IRQs
   lda #0
   sta irq_cnt
 //SEG19 [11] phi from @39 to @38 [phi:@39->@38]
@@ -19532,6 +19566,7 @@ play_collision: {
 //  Return non-zero if a render is needed
 play_move_leftright: {
   //SEG521 [225] if((byte) play_move_leftright::key_event#0==(const byte) KEY_COMMA#0) goto play_move_leftright::@1 -- vbuaa_eq_vbuc1_then_la1 
+    //  Handle keyboard events
     cmp #KEY_COMMA
     beq b1
     jmp b6
@@ -19884,6 +19919,7 @@ play_spawn_current: {
     .label _0 = 4
     .label piece_idx = $21
   //SEG697 [286] (byte) play_spawn_current::current_piece_idx#0 ← (byte) next_piece_idx#17 -- vbuxx=vbuz1 
+    //  Move next piece into current
     ldx next_piece_idx
   //SEG698 [287] (byte~) play_spawn_current::$0 ← (byte) play_spawn_current::current_piece_idx#0 << (byte/signed byte/word/signed word/dword/signed dword) 1 -- vbuz1=vbuxx_rol_1 
     txa
@@ -20090,6 +20126,7 @@ play_increase_level: {
   //SEG768 [327] (byte) level#21 ← ++ (byte) level#10 -- vbuz1=_inc_vbuz1 
     inc level
   //SEG769 [328] if((byte) level#21>(byte/signed byte/word/signed word/dword/signed dword) 29) goto play_increase_level::@2 -- vbuz1_gt_vbuc1_then_la1 
+    //  Update speed of moving tetrominos down
     lda level
     cmp #$1d
     beq !+
@@ -20126,6 +20163,7 @@ play_increase_level: {
   //SEG780 play_increase_level::@7
   b7:
   //SEG781 [334] (byte) level_bcd#8 ← (byte) level_bcd#21 + (byte/signed byte/word/signed word/dword/signed dword) 6 -- vbuz1=vbuz1_plus_vbuc1 
+    //  If level low nybble hits $a change to $10
     lda #6
     clc
     adc level_bcd
@@ -20138,6 +20176,7 @@ play_increase_level: {
   //SEG784 play_increase_level::@3
   b3:
   //SEG785 asm { sed  }
+    //  Increase the score values gained
     sed
   //SEG786 [337] phi from play_increase_level::@3 to play_increase_level::@4 [phi:play_increase_level::@3->play_increase_level::@4]
   b4_from_b3:
@@ -20733,6 +20772,7 @@ keyboard_event_scan: {
   //SEG1008 keyboard_event_scan::@17
   b17:
   //SEG1009 [438] *((const byte[8]) keyboard_events#0 + (byte) keyboard_events_size#10) ← (byte) keyboard_event_scan::keycode#10 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Key pressed
     lda keycode
     ldy keyboard_events_size
     sta keyboard_events,y
@@ -20758,6 +20798,7 @@ keyboard_event_scan: {
   //SEG1017 keyboard_event_scan::@19
   b19:
   //SEG1018 [444] *((const byte[8]) keyboard_scan_values#0 + (byte) keyboard_event_scan::row#2) ← (byte) keyboard_event_scan::row_scan#0 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Store the current keyboard status for the row to debounce
     lda row_scan
     ldy row
     sta keyboard_scan_values,y
@@ -20768,6 +20809,7 @@ keyboard_event_scan: {
     lda #$40
     ora keycode
   //SEG1021 [446] *((const byte[8]) keyboard_events#0 + (byte) keyboard_events_size#10) ← (byte/word/dword~) keyboard_event_scan::$11 -- pbuc1_derefidx_vbuz1=vbuaa 
+    //  Key released
     ldy keyboard_events_size
     sta keyboard_events,y
   //SEG1022 [447] (byte) keyboard_events_size#1 ← ++ (byte) keyboard_events_size#10 -- vbuz1=_inc_vbuz1 
@@ -20906,6 +20948,7 @@ play_init: {
     lda #PLAYFIELD_COLS*PLAYFIELD_LINES
     sta playfield_lines_idx+PLAYFIELD_LINES
   //SEG1064 [470] (byte) current_movedown_slow#1 ← *((const byte[]) MOVEDOWN_SLOW_SPEEDS#0) -- vbuz1=_deref_pbuc1 
+    //  Set initial speed of moving down a tetromino
     lda MOVEDOWN_SLOW_SPEEDS
     sta current_movedown_slow
   //SEG1065 [471] phi from play_init::@3 to play_init::@2 [phi:play_init::@3->play_init::@2]
@@ -20950,20 +20993,24 @@ sprites_irq_init: {
   //SEG1077 asm { sei  }
     sei
   //SEG1078 [478] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge any IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG1079 asm { ldaCIA1_INTERRUPT  }
     lda CIA1_INTERRUPT
   //SEG1080 [480] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG1081 [481] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG1082 [482] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG1083 [483] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) & (byte/signed byte/word/signed word/dword/signed dword) 127 -- _deref_pbuc1=_deref_pbuc1_band_vbuc2 
+    //  Set raster line
     lda VIC_CONTROL
     and #$7f
     sta VIC_CONTROL
@@ -20971,9 +21018,11 @@ sprites_irq_init: {
     lda #IRQ_RASTER_FIRST
     sta RASTER
   //SEG1085 [485] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG1086 [486] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_CLOBBER)(void()) sprites_irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<sprites_irq
     sta HARDWARE_IRQ
     lda #>sprites_irq
@@ -21070,6 +21119,7 @@ render_init: {
   //SEG1117 render_init::@3
   b3:
   //SEG1118 [505] *((const byte*) D011#0) ← (const byte) VIC_ECM#0|(const byte) VIC_DEN#0|(const byte) VIC_RSEL#0|(byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  Enable Extended Background Color Mode
     lda #VIC_ECM|VIC_DEN|VIC_RSEL|3
     sta D011
   //SEG1119 [506] *((const byte*) BORDERCOL#0) ← (const byte) BLACK#0 -- _deref_pbuc1=vbuc2 
@@ -21379,8 +21429,11 @@ sprites_irq: {
     sta rega+1
     stx regx+1
   //SEG1218 asm { cld  }
+    // (*BGCOL)++;
+    //  Clear decimal flag (because it is used by the score algorithm)
     cld
   //SEG1219 [556] (byte) sprites_irq::ypos#0 ← (byte) irq_sprite_ypos#0 -- vbuaa=vbuz1 
+    //  Place the sprites
     lda irq_sprite_ypos
   //SEG1220 [557] *((const byte*) SPRITES_YPOS#0) ← (byte) sprites_irq::ypos#0 -- _deref_pbuc1=vbuaa 
     sta SPRITES_YPOS
@@ -21394,6 +21447,7 @@ sprites_irq: {
     ldx irq_raster_next
     inx
   //SEG1225 [562] (byte) sprites_irq::raster_sprite_gfx_modify#0 ← (byte/signed word/word/dword/signed dword~) sprites_irq::$0 -- vbuz1=vbuxx 
+    //  Wait for the y-position before changing sprite pointers
     stx raster_sprite_gfx_modify
     jmp b1
   //SEG1226 sprites_irq::@1
@@ -21472,9 +21526,11 @@ sprites_irq: {
   //SEG1249 sprites_irq::@7
   b7:
   //SEG1250 [579] *((const byte*) RASTER#0) ← (byte) irq_raster_next#4 -- _deref_pbuc1=vbuz1 
+    //  Setup next interrupt
     lda irq_raster_next
     sta RASTER
   //SEG1251 [580] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -23771,27 +23827,33 @@ Score: 3365357
 bbegin:
 //SEG4 @14
 //SEG5 [1] (byte) render_screen_showing#0 ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- vbuz1=vbuc1 
+  //  The screen currently being showed to the user. $00 for screen 1 / $40 for screen 2.
   lda #0
   sta render_screen_showing
 //SEG6 kickasm(location (const byte*) PLAYFIELD_CHARSET#0) {{ .fill 8,$00 // Place a filled char at the start of the charset     .import binary "playfield-screen.imap"  }}
 //SEG7 kickasm(location (const byte*) PLAYFIELD_SCREEN_ORIGINAL#0) {{ // Load chars for the screen   .var screen = LoadBinary("playfield-screen.iscr")    // Load extended colors for the screen   .var extended = LoadBinary("playfield-extended.col")   // screen.get(i)+1 because the charset is loaded into PLAYFIELD_CHARSET+8   // extended.get(i)-1 because the extended colors are 1-based (1/2/3/4)   // <<6 to move extended colors to the upper 2 bits   .fill screen.getSize(), ( (screen.get(i)+1) | (extended.get(i)-1)<<6 )  }}
 //SEG8 kickasm(location (const byte*) PLAYFIELD_COLORS_ORIGINAL#0) {{ .import binary "playfield-screen.col"  }}
+//  Original Color Data
 //SEG9 @23
 //SEG10 kickasm(location (const byte*) PLAYFIELD_SPRITES#0) {{ .var sprites = LoadPicture("playfield-sprites.png", List().add($010101, $000000)) 	// Put the sprites into memory  	.for(var sy=0;sy<10;sy++) { 	    .var sprite_gfx_y = sy*20 		.for(var sx=0;sx<3;sx++) { 	    	.for (var y=0;y<21; y++) { 	    	    .var gfx_y =  sprite_gfx_y + mod(2100+y-sprite_gfx_y,21) 		    	.for (var c=0; c<3; c++) { 	            	.byte sprites.getSinglecolorByte(sx*3+c,gfx_y) 	            } 	        } 	    	.byte 0 	  	} 	}  }}
 //SEG11 @24
 //SEG12 [6] (byte) irq_raster_next#0 ← (const byte) IRQ_RASTER_FIRST#0 -- vbuz1=vbuc1 
+  //  The raster line of the next IRQ
   lda #IRQ_RASTER_FIRST
   sta irq_raster_next
 //SEG13 [7] (byte) irq_sprite_ypos#0 ← (const byte) SPRITES_FIRST_YPOS#0+(byte/signed byte/word/signed word/dword/signed dword) 21 -- vbuz1=vbuc1 
+  //  Y-pos of the sprites on the next IRQ
   lda #SPRITES_FIRST_YPOS+$15
   sta irq_sprite_ypos
 //SEG14 [8] phi from @24 to toSpritePtr1 [phi:@24->toSpritePtr1]
 //SEG15 toSpritePtr1
 //SEG16 @39
 //SEG17 [9] (byte) irq_sprite_ptr#0 ← (const byte) toSpritePtr1_return#0+(byte/signed byte/word/signed word/dword/signed dword) 3 -- vbuz1=vbuc1 
+  //  Index of the sprites to show on the next IRQ
   lda #toSpritePtr1_return+3
   sta irq_sprite_ptr
 //SEG18 [10] (byte) irq_cnt#0 ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- vbuz1=vbuc1 
+  //  Counting the 10 IRQs
   lda #0
   sta irq_cnt
 //SEG19 [11] phi from @39 to @38 [phi:@39->@38]
@@ -24863,6 +24925,7 @@ play_collision: {
 //  Return non-zero if a render is needed
 play_move_leftright: {
   //SEG521 [225] if((byte) play_move_leftright::key_event#0==(const byte) KEY_COMMA#0) goto play_move_leftright::@1 -- vbuaa_eq_vbuc1_then_la1 
+    //  Handle keyboard events
     cmp #KEY_COMMA
     beq b1
   //SEG522 play_move_leftright::@6
@@ -25153,6 +25216,7 @@ play_spawn_current: {
     .label _0 = 4
     .label piece_idx = $21
   //SEG697 [286] (byte) play_spawn_current::current_piece_idx#0 ← (byte) next_piece_idx#17 -- vbuxx=vbuz1 
+    //  Move next piece into current
     ldx next_piece_idx
   //SEG698 [287] (byte~) play_spawn_current::$0 ← (byte) play_spawn_current::current_piece_idx#0 << (byte/signed byte/word/signed word/dword/signed dword) 1 -- vbuz1=vbuxx_rol_1 
     txa
@@ -25328,6 +25392,7 @@ play_increase_level: {
   //SEG768 [327] (byte) level#21 ← ++ (byte) level#10 -- vbuz1=_inc_vbuz1 
     inc level
   //SEG769 [328] if((byte) level#21>(byte/signed byte/word/signed word/dword/signed dword) 29) goto play_increase_level::@2 -- vbuz1_gt_vbuc1_then_la1 
+    //  Update speed of moving tetrominos down
     lda level
     cmp #$1d
     beq !+
@@ -25358,6 +25423,7 @@ play_increase_level: {
     bne b3
   //SEG780 play_increase_level::@7
   //SEG781 [334] (byte) level_bcd#8 ← (byte) level_bcd#21 + (byte/signed byte/word/signed word/dword/signed dword) 6 -- vbuz1=vbuz1_plus_vbuc1 
+    //  If level low nybble hits $a change to $10
     lda #6
     clc
     adc level_bcd
@@ -25367,6 +25433,7 @@ play_increase_level: {
   //SEG784 play_increase_level::@3
   b3:
   //SEG785 asm { sed  }
+    //  Increase the score values gained
     sed
   //SEG786 [337] phi from play_increase_level::@3 to play_increase_level::@4 [phi:play_increase_level::@3->play_increase_level::@4]
   //SEG787 [337] phi (byte) play_increase_level::b#2 = (byte/signed byte/word/signed word/dword/signed dword) 0 [phi:play_increase_level::@3->play_increase_level::@4#0] -- vbuxx=vbuc1 
@@ -25850,6 +25917,7 @@ keyboard_event_scan: {
     beq b7
   //SEG1008 keyboard_event_scan::@17
   //SEG1009 [438] *((const byte[8]) keyboard_events#0 + (byte) keyboard_events_size#10) ← (byte) keyboard_event_scan::keycode#10 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Key pressed
     lda keycode
     ldy keyboard_events_size
     sta keyboard_events,y
@@ -25868,6 +25936,7 @@ keyboard_event_scan: {
     bne b4
   //SEG1017 keyboard_event_scan::@19
   //SEG1018 [444] *((const byte[8]) keyboard_scan_values#0 + (byte) keyboard_event_scan::row#2) ← (byte) keyboard_event_scan::row_scan#0 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Store the current keyboard status for the row to debounce
     lda row_scan
     ldy row
     sta keyboard_scan_values,y
@@ -25878,6 +25947,7 @@ keyboard_event_scan: {
     lda #$40
     ora keycode
   //SEG1021 [446] *((const byte[8]) keyboard_events#0 + (byte) keyboard_events_size#10) ← (byte/word/dword~) keyboard_event_scan::$11 -- pbuc1_derefidx_vbuz1=vbuaa 
+    //  Key released
     ldy keyboard_events_size
     sta keyboard_events,y
   //SEG1022 [447] (byte) keyboard_events_size#1 ← ++ (byte) keyboard_events_size#10 -- vbuz1=_inc_vbuz1 
@@ -25997,6 +26067,7 @@ play_init: {
     lda #PLAYFIELD_COLS*PLAYFIELD_LINES
     sta playfield_lines_idx+PLAYFIELD_LINES
   //SEG1064 [470] (byte) current_movedown_slow#1 ← *((const byte[]) MOVEDOWN_SLOW_SPEEDS#0) -- vbuz1=_deref_pbuc1 
+    //  Set initial speed of moving down a tetromino
     lda MOVEDOWN_SLOW_SPEEDS
     sta current_movedown_slow
   //SEG1065 [471] phi from play_init::@3 to play_init::@2 [phi:play_init::@3->play_init::@2]
@@ -26035,20 +26106,24 @@ sprites_irq_init: {
   //SEG1077 asm { sei  }
     sei
   //SEG1078 [478] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge any IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG1079 asm { ldaCIA1_INTERRUPT  }
     lda CIA1_INTERRUPT
   //SEG1080 [480] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG1081 [481] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG1082 [482] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG1083 [483] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) & (byte/signed byte/word/signed word/dword/signed dword) 127 -- _deref_pbuc1=_deref_pbuc1_band_vbuc2 
+    //  Set raster line
     lda VIC_CONTROL
     and #$7f
     sta VIC_CONTROL
@@ -26056,9 +26131,11 @@ sprites_irq_init: {
     lda #IRQ_RASTER_FIRST
     sta RASTER
   //SEG1085 [485] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG1086 [486] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_CLOBBER)(void()) sprites_irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<sprites_irq
     sta HARDWARE_IRQ
     lda #>sprites_irq
@@ -26136,6 +26213,7 @@ render_init: {
     sta CIA2_PORT_A
   //SEG1117 render_init::@3
   //SEG1118 [505] *((const byte*) D011#0) ← (const byte) VIC_ECM#0|(const byte) VIC_DEN#0|(const byte) VIC_RSEL#0|(byte/signed byte/word/signed word/dword/signed dword) 3 -- _deref_pbuc1=vbuc2 
+    //  Enable Extended Background Color Mode
     lda #VIC_ECM|VIC_DEN|VIC_RSEL|3
     sta D011
   //SEG1119 [506] *((const byte*) BORDERCOL#0) ← (const byte) BLACK#0 -- _deref_pbuc1=vbuc2 
@@ -26411,8 +26489,11 @@ sprites_irq: {
     sta rega+1
     stx regx+1
   //SEG1218 asm { cld  }
+    // (*BGCOL)++;
+    //  Clear decimal flag (because it is used by the score algorithm)
     cld
   //SEG1219 [556] (byte) sprites_irq::ypos#0 ← (byte) irq_sprite_ypos#0 -- vbuaa=vbuz1 
+    //  Place the sprites
     lda irq_sprite_ypos
   //SEG1220 [557] *((const byte*) SPRITES_YPOS#0) ← (byte) sprites_irq::ypos#0 -- _deref_pbuc1=vbuaa 
     sta SPRITES_YPOS
@@ -26426,6 +26507,7 @@ sprites_irq: {
     ldx irq_raster_next
     inx
   //SEG1225 [562] (byte) sprites_irq::raster_sprite_gfx_modify#0 ← (byte/signed word/word/dword/signed dword~) sprites_irq::$0 -- vbuz1=vbuxx 
+    //  Wait for the y-position before changing sprite pointers
     stx raster_sprite_gfx_modify
   //SEG1226 sprites_irq::@1
   b1:
@@ -26489,9 +26571,11 @@ sprites_irq: {
   //SEG1249 sprites_irq::@7
   b7:
   //SEG1250 [579] *((const byte*) RASTER#0) ← (byte) irq_raster_next#4 -- _deref_pbuc1=vbuz1 
+    //  Setup next interrupt
     lda irq_raster_next
     sta RASTER
   //SEG1251 [580] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ and setup the next one
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG1252 sprites_irq::@return

src/test/ref/examples/3d/3d.asm

@@ -39,9 +39,12 @@
   .label COSQ = SINQ+$40
   .label sx = 2
   .label sy = 3
+//  sin(x) = cos(x+PI/2)
+//  sin(x) = cos(x+PI/2)
 main: {
     sei
     jsr sprites_init
+    // mulf_init();
     lda #<mulf_sqr1
     sta psp1
     lda #>mulf_sqr1
@@ -87,6 +90,8 @@ anim: {
     lda zs,x
     tax
     jsr rotate_matrix
+    // if(*xr<xmin) xmin = *xr;
+    // if(*xr>xmax) xmax = *xr;
     ldy i
     lda xr
     sta xrs,y
@@ -120,6 +125,7 @@ anim: {
     jsr debug_print
     lda #LIGHT_BLUE
     sta BORDERCOL
+    //  Increment angles        
     inc sx
     inc sx
     lda sy

src/test/ref/examples/3d/3d.log

@@ -5710,8 +5710,10 @@ b33:
 //SEG7 kickasm(location (const byte*) SPRITE#0) {{ .var pic = LoadPicture("balloon.png", List().add($000000, $ffffff))     .for (var y=0; y<21; y++)         .for (var x=0;x<3; x++)             .byte pic.getSinglecolorByte(x,y)  }}
 //SEG8 kickasm(location (const signed byte*) PERSP_Z#0) {{ {     .var d = 256.0	     .var z0 = 6.0	     // These values of d/z0 result in table values from $20 to $40 (effectively max is $3f)     .for(var z=0;z<$100;z++) {     	.if(z>127) {     		.byte round(d / (z0 - ((z - 256) / 64.0)));     	} else {     		.byte round(d / (z0 - (z / 64.0)));     	}     } 	}  }}
 //SEG9 kickasm(location (const signed byte*) SINH#0) {{ {     .var min = -$2000     .var max = $2000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte round((min+(ampl/2)+(ampl/2)*sin(rad))/256)     }     }  }}
+//  sin(x) = cos(x+PI/2)
 //SEG10 kickasm(location (const signed byte*) SINQ#0) {{ {     .var min = -$1000     .var max = $1000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte round((min+(ampl/2)+(ampl/2)*sin(rad))/256)     }     }  }}
 //SEG11 kickasm(location (const byte*) SINH_LO#0) {{ {     .var min = -$2000     .var max = $2000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte <(min+(ampl/2)+(ampl/2)*sin(rad))     }     }  }}
+//  sin(x) = cos(x+PI/2)
 //SEG12 kickasm(location (const byte*) SINH_HI#0) {{ {     .var min = -$2000     .var max = $2000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte >(min+(ampl/2)+(ampl/2)*sin(rad))     }     }  }}
 //SEG13 kickasm(location (const byte*) SINQ_LO#0) {{ {     .var min = -$1000     .var max = $1000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte <(min+(ampl/2)+(ampl/2)*sin(rad))     }     }  }}
 //SEG14 kickasm(location (const byte*) SINQ_HI#0) {{ {     .var min = -$1000     .var max = $1000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte >(min+(ampl/2)+(ampl/2)*sin(rad))     }     }  }}
@@ -5732,6 +5734,7 @@ main: {
   //SEG21 main::@1
   b1:
   //SEG22 [15] *((const word*) psp1#0) ← ((word))(const byte*) mulf_sqr1#0 -- _deref_pwuc1=vwuc2 
+    // mulf_init();
     lda #<mulf_sqr1
     sta psp1
     lda #>mulf_sqr1
@@ -5850,6 +5853,8 @@ anim: {
   //SEG61 anim::@29
   b29:
   //SEG62 [38] *((const signed byte[8]) xrs#0 + (byte) anim::i#2) ← *((const signed byte*) xr#0) -- pbsc1_derefidx_vbuz1=_deref_pbsc2 
+    // if(*xr<xmin) xmin = *xr;
+    // if(*xr>xmax) xmax = *xr;
     ldy i
     lda xr
     sta xrs,y
@@ -5916,6 +5921,7 @@ anim: {
     lda #LIGHT_BLUE
     sta BORDERCOL
   //SEG80 [54] (signed byte) sx#3 ← (signed byte) sx#10 + (byte/signed byte/word/signed word/dword/signed dword) 2 -- vbsz1=vbsz1_plus_2 
+    //  Increment angles        
     inc sx
     inc sx
   //SEG81 [55] (signed byte) sy#3 ← (signed byte) sy#10 - (byte/signed byte/word/signed word/dword/signed dword) 3 -- vbsz1=vbsz1_minus_vbuc1 
@@ -8488,8 +8494,10 @@ b33:
 //SEG7 kickasm(location (const byte*) SPRITE#0) {{ .var pic = LoadPicture("balloon.png", List().add($000000, $ffffff))     .for (var y=0; y<21; y++)         .for (var x=0;x<3; x++)             .byte pic.getSinglecolorByte(x,y)  }}
 //SEG8 kickasm(location (const signed byte*) PERSP_Z#0) {{ {     .var d = 256.0	     .var z0 = 6.0	     // These values of d/z0 result in table values from $20 to $40 (effectively max is $3f)     .for(var z=0;z<$100;z++) {     	.if(z>127) {     		.byte round(d / (z0 - ((z - 256) / 64.0)));     	} else {     		.byte round(d / (z0 - (z / 64.0)));     	}     } 	}  }}
 //SEG9 kickasm(location (const signed byte*) SINH#0) {{ {     .var min = -$2000     .var max = $2000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte round((min+(ampl/2)+(ampl/2)*sin(rad))/256)     }     }  }}
+//  sin(x) = cos(x+PI/2)
 //SEG10 kickasm(location (const signed byte*) SINQ#0) {{ {     .var min = -$1000     .var max = $1000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte round((min+(ampl/2)+(ampl/2)*sin(rad))/256)     }     }  }}
 //SEG11 kickasm(location (const byte*) SINH_LO#0) {{ {     .var min = -$2000     .var max = $2000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte <(min+(ampl/2)+(ampl/2)*sin(rad))     }     }  }}
+//  sin(x) = cos(x+PI/2)
 //SEG12 kickasm(location (const byte*) SINH_HI#0) {{ {     .var min = -$2000     .var max = $2000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte >(min+(ampl/2)+(ampl/2)*sin(rad))     }     }  }}
 //SEG13 kickasm(location (const byte*) SINQ_LO#0) {{ {     .var min = -$1000     .var max = $1000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte <(min+(ampl/2)+(ampl/2)*sin(rad))     }     }  }}
 //SEG14 kickasm(location (const byte*) SINQ_HI#0) {{ {     .var min = -$1000     .var max = $1000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte >(min+(ampl/2)+(ampl/2)*sin(rad))     }     }  }}
@@ -8510,6 +8518,7 @@ main: {
   //SEG21 main::@1
   b1:
   //SEG22 [15] *((const word*) psp1#0) ← ((word))(const byte*) mulf_sqr1#0 -- _deref_pwuc1=vwuc2 
+    // mulf_init();
     lda #<mulf_sqr1
     sta psp1
     lda #>mulf_sqr1
@@ -8621,6 +8630,8 @@ anim: {
   //SEG61 anim::@29
   b29:
   //SEG62 [38] *((const signed byte[8]) xrs#0 + (byte) anim::i#2) ← *((const signed byte*) xr#0) -- pbsc1_derefidx_vbuz1=_deref_pbsc2 
+    // if(*xr<xmin) xmin = *xr;
+    // if(*xr>xmax) xmax = *xr;
     ldy i
     lda xr
     sta xrs,y
@@ -8681,6 +8692,7 @@ anim: {
     lda #LIGHT_BLUE
     sta BORDERCOL
   //SEG80 [54] (signed byte) sx#3 ← (signed byte) sx#10 + (byte/signed byte/word/signed word/dword/signed dword) 2 -- vbsz1=vbsz1_plus_2 
+    //  Increment angles        
     inc sx
     inc sx
   //SEG81 [55] (signed byte) sy#3 ← (signed byte) sy#10 - (byte/signed byte/word/signed word/dword/signed dword) 3 -- vbsz1=vbsz1_minus_vbuc1 
@@ -10671,9 +10683,9 @@ Removing instruction jmp b1
 Succesful ASM optimization Pass5NextJumpElimination
 Removing instruction bbegin:
 Succesful ASM optimization Pass5UnusedLabelElimination
-Fixing long branch [310] bne b1 to beq
-Fixing long branch [997] bne b2 to beq
-Fixing long branch [1007] bne b1 to beq
+Fixing long branch [316] bne b1 to beq
+Fixing long branch [1003] bne b2 to beq
+Fixing long branch [1013] bne b1 to beq
 
 FINAL SYMBOL TABLE
 (label) @33
@@ -11350,8 +11362,10 @@ Score: 85538
 //SEG7 kickasm(location (const byte*) SPRITE#0) {{ .var pic = LoadPicture("balloon.png", List().add($000000, $ffffff))     .for (var y=0; y<21; y++)         .for (var x=0;x<3; x++)             .byte pic.getSinglecolorByte(x,y)  }}
 //SEG8 kickasm(location (const signed byte*) PERSP_Z#0) {{ {     .var d = 256.0	     .var z0 = 6.0	     // These values of d/z0 result in table values from $20 to $40 (effectively max is $3f)     .for(var z=0;z<$100;z++) {     	.if(z>127) {     		.byte round(d / (z0 - ((z - 256) / 64.0)));     	} else {     		.byte round(d / (z0 - (z / 64.0)));     	}     } 	}  }}
 //SEG9 kickasm(location (const signed byte*) SINH#0) {{ {     .var min = -$2000     .var max = $2000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte round((min+(ampl/2)+(ampl/2)*sin(rad))/256)     }     }  }}
+//  sin(x) = cos(x+PI/2)
 //SEG10 kickasm(location (const signed byte*) SINQ#0) {{ {     .var min = -$1000     .var max = $1000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte round((min+(ampl/2)+(ampl/2)*sin(rad))/256)     }     }  }}
 //SEG11 kickasm(location (const byte*) SINH_LO#0) {{ {     .var min = -$2000     .var max = $2000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte <(min+(ampl/2)+(ampl/2)*sin(rad))     }     }  }}
+//  sin(x) = cos(x+PI/2)
 //SEG12 kickasm(location (const byte*) SINH_HI#0) {{ {     .var min = -$2000     .var max = $2000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte >(min+(ampl/2)+(ampl/2)*sin(rad))     }     }  }}
 //SEG13 kickasm(location (const byte*) SINQ_LO#0) {{ {     .var min = -$1000     .var max = $1000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte <(min+(ampl/2)+(ampl/2)*sin(rad))     }     }  }}
 //SEG14 kickasm(location (const byte*) SINQ_HI#0) {{ {     .var min = -$1000     .var max = $1000     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte >(min+(ampl/2)+(ampl/2)*sin(rad))     }     }  }}
@@ -11366,6 +11380,7 @@ main: {
     jsr sprites_init
   //SEG21 main::@1
   //SEG22 [15] *((const word*) psp1#0) ← ((word))(const byte*) mulf_sqr1#0 -- _deref_pwuc1=vwuc2 
+    // mulf_init();
     lda #<mulf_sqr1
     sta psp1
     lda #>mulf_sqr1
@@ -11451,6 +11466,8 @@ anim: {
     jsr rotate_matrix
   //SEG61 anim::@29
   //SEG62 [38] *((const signed byte[8]) xrs#0 + (byte) anim::i#2) ← *((const signed byte*) xr#0) -- pbsc1_derefidx_vbuz1=_deref_pbsc2 
+    // if(*xr<xmin) xmin = *xr;
+    // if(*xr>xmax) xmax = *xr;
     ldy i
     lda xr
     sta xrs,y
@@ -11502,6 +11519,7 @@ anim: {
     lda #LIGHT_BLUE
     sta BORDERCOL
   //SEG80 [54] (signed byte) sx#3 ← (signed byte) sx#10 + (byte/signed byte/word/signed word/dword/signed dword) 2 -- vbsz1=vbsz1_plus_2 
+    //  Increment angles        
     inc sx
     inc sx
   //SEG81 [55] (signed byte) sy#3 ← (signed byte) sy#10 - (byte/signed byte/word/signed word/dword/signed dword) 3 -- vbsz1=vbsz1_minus_vbuc1 

src/test/ref/examples/irq/irq-hyperscreen.asm

@@ -25,15 +25,19 @@ main: {
     lda #0
     sta GHOST_BYTE
     sei
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
+    //  Set raster line to $fa
     lda VIC_CONTROL
     and #$7f
     sta VIC_CONTROL
     lda #$fa
     sta RASTER
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
+    //  Set the IRQ routine
     lda #<irq_bottom_1
     sta KERNEL_IRQ
     lda #>irq_bottom_1
@@ -45,11 +49,14 @@ main: {
 irq_bottom_2: {
     lda #WHITE
     sta BORDERCOL
+    //  Set screen height back to 25 lines (preparing for the next screen)
     lda VIC_CONTROL
     ora #VIC_RSEL
     sta VIC_CONTROL
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
+    //  Trigger IRQ 1 at line $fa
     lda #$fa
     sta RASTER
     lda #<irq_bottom_1
@@ -64,11 +71,14 @@ irq_bottom_2: {
 irq_bottom_1: {
     lda #WHITE
     sta BORDERCOL
+    //  Set screen height to 24 lines - this is done after the border should have started drawing - so it wont start
     lda VIC_CONTROL
     and #$ff^VIC_RSEL
     sta VIC_CONTROL
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
+    //  Trigger IRQ 2 at line $fd
     lda #$fd
     sta RASTER
     lda #<irq_bottom_2

src/test/ref/examples/irq/irq-hyperscreen.log

@@ -602,9 +602,11 @@ main: {
   //SEG11 asm { sei  }
     sei
   //SEG12 [6] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG13 [7] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) & (byte/signed byte/word/signed word/dword/signed dword) 127 -- _deref_pbuc1=_deref_pbuc1_band_vbuc2 
+    //  Set raster line to $fa
     lda VIC_CONTROL
     and #$7f
     sta VIC_CONTROL
@@ -612,9 +614,11 @@ main: {
     lda #$fa
     sta RASTER
   //SEG15 [9] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG16 [10] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_MIN)(void()) irq_bottom_1() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq_bottom_1
     sta KERNEL_IRQ
     lda #>irq_bottom_1
@@ -635,13 +639,16 @@ irq_bottom_2: {
     lda #WHITE
     sta BORDERCOL
   //SEG23 [14] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (const byte) VIC_RSEL#0 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set screen height back to 25 lines (preparing for the next screen)
     lda VIC_CONTROL
     ora #VIC_RSEL
     sta VIC_CONTROL
   //SEG24 [15] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG25 [16] *((const byte*) RASTER#0) ← (byte/word/signed word/dword/signed dword) 250 -- _deref_pbuc1=vbuc2 
+    //  Trigger IRQ 1 at line $fa
     lda #$fa
     sta RASTER
   //SEG26 [17] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_MIN)(void()) irq_bottom_1() -- _deref_pptc1=pprc2 
@@ -666,13 +673,16 @@ irq_bottom_1: {
     lda #WHITE
     sta BORDERCOL
   //SEG33 [21] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) & (byte/word/signed word/dword/signed dword) 255^(const byte) VIC_RSEL#0 -- _deref_pbuc1=_deref_pbuc1_band_vbuc2 
+    //  Set screen height to 24 lines - this is done after the border should have started drawing - so it wont start
     lda VIC_CONTROL
     and #$ff^VIC_RSEL
     sta VIC_CONTROL
   //SEG34 [22] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG35 [23] *((const byte*) RASTER#0) ← (byte/word/signed word/dword/signed dword) 253 -- _deref_pbuc1=vbuc2 
+    //  Trigger IRQ 2 at line $fd
     lda #$fd
     sta RASTER
   //SEG36 [24] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_KEYBOARD)(void()) irq_bottom_2() -- _deref_pptc1=pprc2 
@@ -770,9 +780,11 @@ main: {
   //SEG11 asm { sei  }
     sei
   //SEG12 [6] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG13 [7] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) & (byte/signed byte/word/signed word/dword/signed dword) 127 -- _deref_pbuc1=_deref_pbuc1_band_vbuc2 
+    //  Set raster line to $fa
     lda VIC_CONTROL
     and #$7f
     sta VIC_CONTROL
@@ -780,9 +792,11 @@ main: {
     lda #$fa
     sta RASTER
   //SEG15 [9] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG16 [10] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_MIN)(void()) irq_bottom_1() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq_bottom_1
     sta KERNEL_IRQ
     lda #>irq_bottom_1
@@ -803,13 +817,16 @@ irq_bottom_2: {
     lda #WHITE
     sta BORDERCOL
   //SEG23 [14] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (const byte) VIC_RSEL#0 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set screen height back to 25 lines (preparing for the next screen)
     lda VIC_CONTROL
     ora #VIC_RSEL
     sta VIC_CONTROL
   //SEG24 [15] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG25 [16] *((const byte*) RASTER#0) ← (byte/word/signed word/dword/signed dword) 250 -- _deref_pbuc1=vbuc2 
+    //  Trigger IRQ 1 at line $fa
     lda #$fa
     sta RASTER
   //SEG26 [17] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_MIN)(void()) irq_bottom_1() -- _deref_pptc1=pprc2 
@@ -834,13 +851,16 @@ irq_bottom_1: {
     lda #WHITE
     sta BORDERCOL
   //SEG33 [21] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) & (byte/word/signed word/dword/signed dword) 255^(const byte) VIC_RSEL#0 -- _deref_pbuc1=_deref_pbuc1_band_vbuc2 
+    //  Set screen height to 24 lines - this is done after the border should have started drawing - so it wont start
     lda VIC_CONTROL
     and #$ff^VIC_RSEL
     sta VIC_CONTROL
   //SEG34 [22] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG35 [23] *((const byte*) RASTER#0) ← (byte/word/signed word/dword/signed dword) 253 -- _deref_pbuc1=vbuc2 
+    //  Trigger IRQ 2 at line $fd
     lda #$fd
     sta RASTER
   //SEG36 [24] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_KEYBOARD)(void()) irq_bottom_2() -- _deref_pptc1=pprc2 
@@ -1029,9 +1049,11 @@ main: {
   //SEG11 asm { sei  }
     sei
   //SEG12 [6] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG13 [7] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) & (byte/signed byte/word/signed word/dword/signed dword) 127 -- _deref_pbuc1=_deref_pbuc1_band_vbuc2 
+    //  Set raster line to $fa
     lda VIC_CONTROL
     and #$7f
     sta VIC_CONTROL
@@ -1039,9 +1061,11 @@ main: {
     lda #$fa
     sta RASTER
   //SEG15 [9] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG16 [10] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_MIN)(void()) irq_bottom_1() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq_bottom_1
     sta KERNEL_IRQ
     lda #>irq_bottom_1
@@ -1060,13 +1084,16 @@ irq_bottom_2: {
     lda #WHITE
     sta BORDERCOL
   //SEG23 [14] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (const byte) VIC_RSEL#0 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set screen height back to 25 lines (preparing for the next screen)
     lda VIC_CONTROL
     ora #VIC_RSEL
     sta VIC_CONTROL
   //SEG24 [15] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG25 [16] *((const byte*) RASTER#0) ← (byte/word/signed word/dword/signed dword) 250 -- _deref_pbuc1=vbuc2 
+    //  Trigger IRQ 1 at line $fa
     lda #$fa
     sta RASTER
   //SEG26 [17] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_MIN)(void()) irq_bottom_1() -- _deref_pptc1=pprc2 
@@ -1089,13 +1116,16 @@ irq_bottom_1: {
     lda #WHITE
     sta BORDERCOL
   //SEG33 [21] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) & (byte/word/signed word/dword/signed dword) 255^(const byte) VIC_RSEL#0 -- _deref_pbuc1=_deref_pbuc1_band_vbuc2 
+    //  Set screen height to 24 lines - this is done after the border should have started drawing - so it wont start
     lda VIC_CONTROL
     and #$ff^VIC_RSEL
     sta VIC_CONTROL
   //SEG34 [22] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG35 [23] *((const byte*) RASTER#0) ← (byte/word/signed word/dword/signed dword) 253 -- _deref_pbuc1=vbuc2 
+    //  Trigger IRQ 2 at line $fd
     lda #$fd
     sta RASTER
   //SEG36 [24] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_KEYBOARD)(void()) irq_bottom_2() -- _deref_pptc1=pprc2 

src/test/ref/examples/multiplexer/simple-multiplexer.asm

@@ -244,6 +244,7 @@ init: {
     inx
     cpx #PLEX_COUNT-1+1
     bne b1
+    //  Enable & initialize sprites
     lda #$ff
     sta SPRITES_ENABLE
     ldx #0

src/test/ref/examples/multiplexer/simple-multiplexer.log

@@ -3012,6 +3012,7 @@ init: {
   //SEG168 init::@3
   b3:
   //SEG169 [90] *((const byte*) SPRITES_ENABLE#0) ← (byte/word/signed word/dword/signed dword) 255 -- _deref_pbuc1=vbuc2 
+    //  Enable & initialize sprites
     lda #$ff
     sta SPRITES_ENABLE
   //SEG170 [91] phi from init::@3 to init::@2 [phi:init::@3->init::@2]
@@ -3795,6 +3796,7 @@ init: {
   //SEG168 init::@3
   b3:
   //SEG169 [90] *((const byte*) SPRITES_ENABLE#0) ← (byte/word/signed word/dword/signed dword) 255 -- _deref_pbuc1=vbuc2 
+    //  Enable & initialize sprites
     lda #$ff
     sta SPRITES_ENABLE
   //SEG170 [91] phi from init::@3 to init::@2 [phi:init::@3->init::@2]
@@ -4699,6 +4701,7 @@ init: {
     bne b1
   //SEG168 init::@3
   //SEG169 [90] *((const byte*) SPRITES_ENABLE#0) ← (byte/word/signed word/dword/signed dword) 255 -- _deref_pbuc1=vbuc2 
+    //  Enable & initialize sprites
     lda #$ff
     sta SPRITES_ENABLE
   //SEG170 [91] phi from init::@3 to init::@2 [phi:init::@3->init::@2]

src/test/ref/examples/rotate/rotate.asm

@@ -15,6 +15,7 @@
   .label COS = $2000
   .label SPRITE = $3000
   .label SIN = COS+$40
+//  sin(x) = cos(x+PI/2)
 main: {
     sei
     jsr init
@@ -50,6 +51,7 @@ anim: {
     ldy i
     lda xs,y
     sta x
+    //  signed fixed[7.0]
     lda ys,y
     sta y
     ldy angle
@@ -89,6 +91,7 @@ anim: {
     jsr mulf8s_prepared
     asl _12
     rol _12+1
+    //  signed fixed[8.8] 
     lda yr
     clc
     adc _12
@@ -319,6 +322,7 @@ mulf_init: {
     lda sqr2_lo
     cmp #<mulf_sqr2_lo+$1ff
     bne b3
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
     lda mulf_sqr1_hi+$100

src/test/ref/examples/rotate/rotate.log

@@ -2298,6 +2298,7 @@ bbegin:
 //SEG4 @13
 b13:
 //SEG5 kickasm(location (const byte*) COS#0) {{ {     .var min = -$7fff     .var max = $7fff     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte >round(min+(ampl/2)+(ampl/2)*cos(rad))     }     }  }}
+  //  sin(x) = cos(x+PI/2)
   jmp b16
 //SEG6 @16
 b16:
@@ -2398,6 +2399,7 @@ anim: {
     lda xs,y
     sta x
   //SEG37 [16] (signed byte) anim::y#0 ← *((const signed byte[8]) ys#0 + (byte) anim::i#10) -- vbsz1=pbsc1_derefidx_vbuz2 
+    //  signed fixed[7.0]
     ldy i
     lda ys,y
     sta y
@@ -2552,6 +2554,7 @@ anim: {
     rol
     sta _12+1
   //SEG83 [42] (signed word) anim::yr#1 ← (signed word) anim::yr#0 + (signed word~) anim::$12 -- vwsz1=vwsz2_plus_vwsz3 
+    //  signed fixed[8.8] 
     lda yr
     clc
     adc _12
@@ -3036,6 +3039,7 @@ mulf_init: {
   //SEG214 mulf_init::@8
   b8:
   //SEG215 [121] *((const byte[512]) mulf_sqr2_lo#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_lo#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
   //SEG216 [122] *((const byte[512]) mulf_sqr2_hi#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_hi#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
@@ -3381,6 +3385,7 @@ bbegin:
 //SEG4 @13
 b13:
 //SEG5 kickasm(location (const byte*) COS#0) {{ {     .var min = -$7fff     .var max = $7fff     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte >round(min+(ampl/2)+(ampl/2)*cos(rad))     }     }  }}
+  //  sin(x) = cos(x+PI/2)
   jmp b16
 //SEG6 @16
 b16:
@@ -3472,6 +3477,7 @@ anim: {
     lda xs,y
     sta x
   //SEG37 [16] (signed byte) anim::y#0 ← *((const signed byte[8]) ys#0 + (byte) anim::i#10) -- vbsz1=pbsc1_derefidx_vbuz2 
+    //  signed fixed[7.0]
     ldy i
     lda ys,y
     sta y
@@ -3580,6 +3586,7 @@ anim: {
     asl _12
     rol _12+1
   //SEG83 [42] (signed word) anim::yr#1 ← (signed word) anim::yr#0 + (signed word~) anim::$12 -- vwsz1=vwsz1_plus_vwsz2 
+    //  signed fixed[8.8] 
     lda yr
     clc
     adc _12
@@ -3999,6 +4006,7 @@ mulf_init: {
   //SEG214 mulf_init::@8
   b8:
   //SEG215 [121] *((const byte[512]) mulf_sqr2_lo#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_lo#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
   //SEG216 [122] *((const byte[512]) mulf_sqr2_hi#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_hi#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
@@ -4118,7 +4126,6 @@ Replacing label b12_from_b3 with b12
 Replacing label b3_from_b4 with b3
 Replacing label b3_from_b4 with b3
 Removing instruction b13:
-Removing instruction b16:
 Removing instruction bend_from_b16:
 Removing instruction b1_from_main:
 Removing instruction anim_from_b1:
@@ -4139,6 +4146,7 @@ Removing instruction b3_from_b4:
 Removing instruction b12_from_b3:
 Removing instruction b4_from_b12:
 Succesful ASM optimization Pass5RedundantLabelElimination
+Removing instruction b16:
 Removing instruction bend:
 Removing instruction init_from_main:
 Removing instruction b1:
@@ -4194,7 +4202,7 @@ Removing instruction b12:
 Succesful ASM optimization Pass5UnusedLabelElimination
 Removing unreachable instruction jmp b4
 Succesful ASM optimization Pass5UnreachableCodeElimination
-Fixing long branch [133] bne b7 to beq
+Fixing long branch [136] bne b7 to beq
 
 FINAL SYMBOL TABLE
 (label) @13
@@ -4531,6 +4539,7 @@ Score: 34700
 //SEG3 @begin
 //SEG4 @13
 //SEG5 kickasm(location (const byte*) COS#0) {{ {     .var min = -$7fff     .var max = $7fff     .var ampl = max-min;     .for(var i=0;i<$140;i++) {         .var rad = i*2*PI/256;         .byte >round(min+(ampl/2)+(ampl/2)*cos(rad))     }     }  }}
+//  sin(x) = cos(x+PI/2)
 //SEG6 @16
 //SEG7 kickasm(location (const byte*) SPRITE#0) {{ .var pic = LoadPicture("balloon.png", List().add($000000, $ffffff))     .for (var y=0; y<21; y++)         .for (var x=0;x<3; x++)             .byte pic.getSinglecolorByte(x,y)  }}
 //SEG8 [3] call main 
@@ -4598,6 +4607,7 @@ anim: {
     lda xs,y
     sta x
   //SEG37 [16] (signed byte) anim::y#0 ← *((const signed byte[8]) ys#0 + (byte) anim::i#10) -- vbsz1=pbsc1_derefidx_vbuz2 
+    //  signed fixed[7.0]
     lda ys,y
     sta y
   //SEG38 anim::mulf8s_prepare1
@@ -4683,6 +4693,7 @@ anim: {
     asl _12
     rol _12+1
   //SEG83 [42] (signed word) anim::yr#1 ← (signed word) anim::yr#0 + (signed word~) anim::$12 -- vwsz1=vwsz1_plus_vwsz2 
+    //  signed fixed[8.8] 
     lda yr
     clc
     adc _12
@@ -5045,6 +5056,7 @@ mulf_init: {
     bne b3
   //SEG214 mulf_init::@8
   //SEG215 [121] *((const byte[512]) mulf_sqr2_lo#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_lo#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
   //SEG216 [122] *((const byte[512]) mulf_sqr2_hi#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_hi#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 

src/test/ref/examples/scroll/scroll.asm

@@ -33,6 +33,7 @@ main: {
     inx
     cpx #$27
     bne b5
+    //  Render next char
     ldy #0
     lda (nxt),y
     tax

src/test/ref/examples/scroll/scroll.log

@@ -720,6 +720,7 @@ main: {
   //SEG33 main::@10
   b10:
   //SEG34 [16] (byte) main::c#0 ← *((byte*) main::nxt#9) -- vbuz1=_deref_pbuz2 
+    //  Render next char
     ldy #0
     lda (nxt),y
     sta c
@@ -952,6 +953,7 @@ main: {
   //SEG33 main::@10
   b10:
   //SEG34 [16] (byte) main::c#0 ← *((byte*) main::nxt#9) -- vbuxx=_deref_pbuz1 
+    //  Render next char
     ldy #0
     lda (nxt),y
     tax
@@ -1238,6 +1240,7 @@ main: {
     bne b5
   //SEG33 main::@10
   //SEG34 [16] (byte) main::c#0 ← *((byte*) main::nxt#9) -- vbuxx=_deref_pbuz1 
+    //  Render next char
     ldy #0
     lda (nxt),y
     tax

src/test/ref/examples/sinplotter/sine-plotter.asm

@@ -38,6 +38,8 @@ main: {
     .const vicSelectGfxBank1_toDd001_return = 3^(>SCREEN)>>6
     .const toD0181_return = (>(SCREEN&$3fff)<<2)|(>BITMAP)>>2&$f
     sei
+    //  Disable normal interrupt
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
     lda #PROCPORT_RAM_IO

src/test/ref/examples/sinplotter/sine-plotter.log

@@ -3791,6 +3791,8 @@ main: {
   //SEG12 asm { sei  }
     sei
   //SEG13 [6] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG14 [7] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
@@ -5984,6 +5986,8 @@ main: {
   //SEG12 asm { sei  }
     sei
   //SEG13 [6] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG14 [7] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
@@ -7677,8 +7681,8 @@ Removing unreachable instruction jmp b2
 Removing unreachable instruction jmp b3
 Removing unreachable instruction jmp b2
 Succesful ASM optimization Pass5UnreachableCodeElimination
-Fixing long branch [151] bcc b1 to bcs
-Fixing long branch [157] bcc b1 to bcs
+Fixing long branch [153] bcc b1 to bcs
+Fixing long branch [159] bcc b1 to bcs
 
 FINAL SYMBOL TABLE
 (label) @29
@@ -8251,6 +8255,8 @@ main: {
   //SEG12 asm { sei  }
     sei
   //SEG13 [6] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG14 [7] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 

src/test/ref/examples/sinsprites/sinus-sprites.asm

@@ -207,6 +207,8 @@ gen_sintab: {
     sta setFAC.w+1
     jsr setFAC
     jsr setARGtoFAC
+    //  arg = max
+    //  TODO: Kernel JSR clobbers A,X,Y
     lda #0
     tax
     tay
@@ -285,6 +287,7 @@ gen_sintab: {
     jsr addMEMtoFAC
     jsr getFAC
     lda _23
+    //  fac =  sin( i * 2 * PI / length ) * (max - min) / 2 + min + (max - min) / 2
     ldy i
     sta (sintab),y
     jsr progress_inc
@@ -329,6 +332,7 @@ progress_inc: {
 //  Destroys the value in the FAC in the process
 getFAC: {
     .label return = $c
+    //  Load FAC (floating point accumulator) integer part into word register Y,A
     jsr $b1aa
     sty $fe
     sta $ff
@@ -395,6 +399,7 @@ divMEMbyFAC: {
 setFAC: {
     .label w = $c
     jsr prepareMEM
+    //  Load word register Y,A into FAC (floating point accumulator)
     ldy $fe
     lda $ff
     jsr $b391
@@ -495,6 +500,7 @@ gen_chargen_sprite: {
     lda #0
     sta y
   b1:
+    //  current chargen line
     ldy y
     lda (chargen),y
     sta bits
@@ -523,6 +529,7 @@ gen_chargen_sprite: {
     iny
     cpy #8
     bne b5
+    //  sprite byte filled - store and move to next byte
     ldy #0
     sta (sprite),y
     ldy #3

src/test/ref/examples/sinsprites/sinus-sprites.log

@@ -3990,6 +3990,8 @@ gen_sintab: {
   //SEG159 gen_sintab::@4
   b4:
   //SEG160 asm { lda#0 ldx#0 ldy#0  }
+    //  arg = max
+    //  TODO: Kernel JSR clobbers A,X,Y
     lda #0
     ldx #0
     ldy #0
@@ -4240,6 +4242,7 @@ gen_sintab: {
     lda _23
     sta _24
   //SEG254 [117] *((byte*) gen_sintab::sintab#12 + (byte) gen_sintab::i#10) ← (byte~) gen_sintab::$24 -- pbuz1_derefidx_vbuz2=vbuz3 
+    //  fac =  sin( i * 2 * PI / length ) * (max - min) / 2 + min + (max - min) / 2
     lda _24
     ldy i
     sta (sintab),y
@@ -4322,6 +4325,7 @@ getFAC: {
     .label return = $3a
     .label return_2 = $35
   //SEG278 asm { jsr$b1aa sty$fe sta$ff  }
+    //  Load FAC (floating point accumulator) integer part into word register Y,A
     jsr $b1aa
     sty $fe
     sta $ff
@@ -4477,6 +4481,7 @@ setFAC: {
   //SEG324 setFAC::@1
   b1:
   //SEG325 asm { ldy$fe lda$ff jsr$b391  }
+    //  Load word register Y,A into FAC (floating point accumulator)
     ldy $fe
     lda $ff
     jsr $b391
@@ -4669,6 +4674,7 @@ gen_chargen_sprite: {
   //SEG377 gen_chargen_sprite::@1
   b1:
   //SEG378 [185] (byte) gen_chargen_sprite::bits#0 ← *((byte*) gen_chargen_sprite::chargen#0 + (byte) gen_chargen_sprite::y#2) -- vbuz1=pbuz2_derefidx_vbuz3 
+    //  current chargen line
     ldy y
     lda (chargen),y
     sta bits
@@ -4759,6 +4765,7 @@ gen_chargen_sprite: {
   //SEG416 gen_chargen_sprite::@7
   b7:
   //SEG417 [196] *((byte*) gen_chargen_sprite::sprite#3 + (byte/signed byte/word/signed word/dword/signed dword) 0) ← (byte) gen_chargen_sprite::s_gen#1 -- pbuz1_derefidx_vbuc1=vbuz2 
+    //  sprite byte filled - store and move to next byte
     lda s_gen
     ldy #0
     sta (sprite),y
@@ -5742,6 +5749,8 @@ gen_sintab: {
   //SEG159 gen_sintab::@4
   b4:
   //SEG160 asm { lda#0 ldx#0 ldy#0  }
+    //  arg = max
+    //  TODO: Kernel JSR clobbers A,X,Y
     lda #0
     ldx #0
     ldy #0
@@ -5983,6 +5992,7 @@ gen_sintab: {
   //SEG253 [116] (byte~) gen_sintab::$24 ← ((byte)) (word~) gen_sintab::$23 -- vbuaa=_byte_vwuz1 
     lda _23
   //SEG254 [117] *((byte*) gen_sintab::sintab#12 + (byte) gen_sintab::i#10) ← (byte~) gen_sintab::$24 -- pbuz1_derefidx_vbuz2=vbuaa 
+    //  fac =  sin( i * 2 * PI / length ) * (max - min) / 2 + min + (max - min) / 2
     ldy i
     sta (sintab),y
   //SEG255 [118] call progress_inc 
@@ -6063,6 +6073,7 @@ progress_inc: {
 getFAC: {
     .label return = $c
   //SEG278 asm { jsr$b1aa sty$fe sta$ff  }
+    //  Load FAC (floating point accumulator) integer part into word register Y,A
     jsr $b1aa
     sty $fe
     sta $ff
@@ -6200,6 +6211,7 @@ setFAC: {
   //SEG324 setFAC::@1
   b1:
   //SEG325 asm { ldy$fe lda$ff jsr$b391  }
+    //  Load word register Y,A into FAC (floating point accumulator)
     ldy $fe
     lda $ff
     jsr $b391
@@ -6378,6 +6390,7 @@ gen_chargen_sprite: {
   //SEG377 gen_chargen_sprite::@1
   b1:
   //SEG378 [185] (byte) gen_chargen_sprite::bits#0 ← *((byte*) gen_chargen_sprite::chargen#0 + (byte) gen_chargen_sprite::y#2) -- vbuz1=pbuz2_derefidx_vbuz3 
+    //  current chargen line
     ldy y
     lda (chargen),y
     sta bits
@@ -6461,6 +6474,7 @@ gen_chargen_sprite: {
   //SEG416 gen_chargen_sprite::@7
   b7:
   //SEG417 [196] *((byte*) gen_chargen_sprite::sprite#3 + (byte/signed byte/word/signed word/dword/signed dword) 0) ← (byte) gen_chargen_sprite::s_gen#1 -- pbuz1_derefidx_vbuc1=vbuz2 
+    //  sprite byte filled - store and move to next byte
     lda s_gen
     ldy #0
     sta (sprite),y
@@ -7714,6 +7728,8 @@ gen_sintab: {
     jsr setARGtoFAC
   //SEG159 gen_sintab::@4
   //SEG160 asm { lda#0 ldx#0 ldy#0  }
+    //  arg = max
+    //  TODO: Kernel JSR clobbers A,X,Y
     lda #0
     tax
     tay
@@ -7886,6 +7902,7 @@ gen_sintab: {
   //SEG253 [116] (byte~) gen_sintab::$24 ← ((byte)) (word~) gen_sintab::$23 -- vbuaa=_byte_vwuz1 
     lda _23
   //SEG254 [117] *((byte*) gen_sintab::sintab#12 + (byte) gen_sintab::i#10) ← (byte~) gen_sintab::$24 -- pbuz1_derefidx_vbuz2=vbuaa 
+    //  fac =  sin( i * 2 * PI / length ) * (max - min) / 2 + min + (max - min) / 2
     ldy i
     sta (sintab),y
   //SEG255 [118] call progress_inc 
@@ -7954,6 +7971,7 @@ progress_inc: {
 getFAC: {
     .label return = $c
   //SEG278 asm { jsr$b1aa sty$fe sta$ff  }
+    //  Load FAC (floating point accumulator) integer part into word register Y,A
     jsr $b1aa
     sty $fe
     sta $ff
@@ -8067,6 +8085,7 @@ setFAC: {
     jsr prepareMEM
   //SEG324 setFAC::@1
   //SEG325 asm { ldy$fe lda$ff jsr$b391  }
+    //  Load word register Y,A into FAC (floating point accumulator)
     ldy $fe
     lda $ff
     jsr $b391
@@ -8220,6 +8239,7 @@ gen_chargen_sprite: {
   //SEG377 gen_chargen_sprite::@1
   b1:
   //SEG378 [185] (byte) gen_chargen_sprite::bits#0 ← *((byte*) gen_chargen_sprite::chargen#0 + (byte) gen_chargen_sprite::y#2) -- vbuz1=pbuz2_derefidx_vbuz3 
+    //  current chargen line
     ldy y
     lda (chargen),y
     sta bits
@@ -8287,6 +8307,7 @@ gen_chargen_sprite: {
     bne b5
   //SEG416 gen_chargen_sprite::@7
   //SEG417 [196] *((byte*) gen_chargen_sprite::sprite#3 + (byte/signed byte/word/signed word/dword/signed dword) 0) ← (byte) gen_chargen_sprite::s_gen#1 -- pbuz1_derefidx_vbuc1=vbuz2 
+    //  sprite byte filled - store and move to next byte
     ldy #0
     sta (sprite),y
   //SEG418 [197] *((byte*) gen_chargen_sprite::sprite#3 + (byte/signed byte/word/signed word/dword/signed dword) 3) ← (byte) gen_chargen_sprite::s_gen#1 -- pbuz1_derefidx_vbuc1=vbuz2 

src/test/ref/interrupt-volatile-reuse-problem2.asm

@@ -41,6 +41,7 @@ main: {
     jmp b1
 }
 irq: {
+    //  Acknowledge the IRQ
     lda #1
     sta IRQ_STATUS
     lda $dc0d

src/test/ref/interrupt-volatile-reuse-problem2.log

@@ -415,6 +415,7 @@ main: {
 irq: {
   //SEG40 entry interrupt(KERNEL_MIN)
   //SEG41 [17] *((const byte*) IRQ_STATUS#0) ← (byte/signed byte/word/signed word/dword/signed dword) 1 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #1
     sta IRQ_STATUS
   //SEG42 asm { lda$dc0d  }
@@ -588,6 +589,7 @@ main: {
 irq: {
   //SEG40 entry interrupt(KERNEL_MIN)
   //SEG41 [17] *((const byte*) IRQ_STATUS#0) ← (byte/signed byte/word/signed word/dword/signed dword) 1 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #1
     sta IRQ_STATUS
   //SEG42 asm { lda$dc0d  }
@@ -775,6 +777,7 @@ main: {
 irq: {
   //SEG40 entry interrupt(KERNEL_MIN)
   //SEG41 [17] *((const byte*) IRQ_STATUS#0) ← (byte/signed byte/word/signed word/dword/signed dword) 1 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #1
     sta IRQ_STATUS
   //SEG42 asm { lda$dc0d  }

src/test/ref/irq-hardware-clobber-jsr.asm

@@ -31,19 +31,24 @@
   .const WHITE = 1
 main: {
     sei
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
     lda #PROCPORT_RAM_IO
     sta PROCPORT
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
     lda #0
     sta RASTER
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
+    //  Set the IRQ routine
     lda #<irq
     sta HARDWARE_IRQ
     lda #>irq
@@ -66,6 +71,7 @@ do_irq: {
     sta BGCOL
     lda #BLACK
     sta BGCOL
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     rts

src/test/ref/irq-hardware-clobber-jsr.log

@@ -591,15 +591,18 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG13 [7] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG14 [8] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -607,9 +610,11 @@ main: {
     lda #0
     sta RASTER
   //SEG16 [10] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG17 [11] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_CLOBBER)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta HARDWARE_IRQ
     lda #>irq
@@ -653,6 +658,7 @@ do_irq: {
     lda #BLACK
     sta BGCOL
   //SEG29 [19] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -747,15 +753,18 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG13 [7] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG14 [8] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -763,9 +772,11 @@ main: {
     lda #0
     sta RASTER
   //SEG16 [10] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG17 [11] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_CLOBBER)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta HARDWARE_IRQ
     lda #>irq
@@ -803,6 +814,7 @@ do_irq: {
     lda #BLACK
     sta BGCOL
   //SEG29 [19] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -989,15 +1001,18 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG13 [7] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG14 [8] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -1005,9 +1020,11 @@ main: {
     lda #0
     sta RASTER
   //SEG16 [10] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG17 [11] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_CLOBBER)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta HARDWARE_IRQ
     lda #>irq
@@ -1042,6 +1059,7 @@ do_irq: {
     lda #BLACK
     sta BGCOL
   //SEG29 [19] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG30 do_irq::@return

src/test/ref/irq-hardware-clobber.asm

@@ -25,19 +25,24 @@
 //  RAM in $A000, $E000 CHAR ROM in $D000
 main: {
     sei
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
     lda #PROCPORT_RAM_IO
     sta PROCPORT
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
     lda #0
     sta RASTER
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
+    //  Set the IRQ routine
     lda #<irq
     sta HARDWARE_IRQ
     lda #>irq
@@ -54,6 +59,7 @@ irq: {
     sta BGCOL
     lda #BLACK
     sta BGCOL
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   rega:

src/test/ref/irq-hardware-clobber.log

@@ -266,15 +266,18 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG13 [7] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG14 [8] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -282,9 +285,11 @@ main: {
     lda #0
     sta RASTER
   //SEG16 [10] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG17 [11] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_CLOBBER)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta HARDWARE_IRQ
     lda #>irq
@@ -312,6 +317,7 @@ irq: {
     lda #BLACK
     sta BGCOL
   //SEG25 [16] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -404,15 +410,18 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG13 [7] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG14 [8] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -420,9 +429,11 @@ main: {
     lda #0
     sta RASTER
   //SEG16 [10] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG17 [11] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_CLOBBER)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta HARDWARE_IRQ
     lda #>irq
@@ -448,6 +459,7 @@ irq: {
     lda #BLACK
     sta BGCOL
   //SEG25 [16] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -567,15 +579,18 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG13 [7] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG14 [8] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -583,9 +598,11 @@ main: {
     lda #0
     sta RASTER
   //SEG16 [10] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG17 [11] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_CLOBBER)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta HARDWARE_IRQ
     lda #>irq
@@ -610,6 +627,7 @@ irq: {
     lda #BLACK
     sta BGCOL
   //SEG25 [16] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG26 irq::@return

src/test/ref/irq-hardware.asm

@@ -25,19 +25,24 @@
 //  RAM in $A000, $E000 CHAR ROM in $D000
 main: {
     sei
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
     lda #PROCPORT_RAM_IO
     sta PROCPORT
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
     lda #0
     sta RASTER
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
+    //  Set the IRQ routine
     lda #<irq
     sta HARDWARE_IRQ
     lda #>irq
@@ -56,6 +61,7 @@ irq: {
     sta BGCOL
     lda #BLACK
     sta BGCOL
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   rega:

src/test/ref/irq-hardware.log

@@ -266,15 +266,18 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG13 [7] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG14 [8] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -282,9 +285,11 @@ main: {
     lda #0
     sta RASTER
   //SEG16 [10] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG17 [11] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_ALL)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta HARDWARE_IRQ
     lda #>irq
@@ -312,6 +317,7 @@ irq: {
     lda #BLACK
     sta BGCOL
   //SEG25 [16] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -397,15 +403,18 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG13 [7] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG14 [8] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -413,9 +422,11 @@ main: {
     lda #0
     sta RASTER
   //SEG16 [10] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG17 [11] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_ALL)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta HARDWARE_IRQ
     lda #>irq
@@ -443,6 +454,7 @@ irq: {
     lda #BLACK
     sta BGCOL
   //SEG25 [16] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -566,15 +578,18 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
     lda #PROCPORT_RAM_IO
     sta PROCPORT
   //SEG13 [7] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG14 [8] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -582,9 +597,11 @@ main: {
     lda #0
     sta RASTER
   //SEG16 [10] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG17 [11] *((const void()**) HARDWARE_IRQ#0) ← &interrupt(HARDWARE_ALL)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta HARDWARE_IRQ
     lda #>irq
@@ -611,6 +628,7 @@ irq: {
     lda #BLACK
     sta BGCOL
   //SEG25 [16] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG26 irq::@return

src/test/ref/irq-kernel.asm

@@ -15,15 +15,19 @@
   .const CIA_INTERRUPT_CLEAR = $7f
 main: {
     sei
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
     lda #0
     sta RASTER
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
+    //  Set the IRQ routine
     lda #<irq
     sta KERNEL_IRQ
     lda #>irq
@@ -37,6 +41,7 @@ irq: {
     sta BGCOL
     lda #BLACK
     sta BGCOL
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp $ea31

src/test/ref/irq-kernel.log

@@ -208,9 +208,11 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG12 [6] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -218,9 +220,11 @@ main: {
     lda #0
     sta RASTER
   //SEG14 [8] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG15 [9] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_KEYBOARD)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta KERNEL_IRQ
     lda #>irq
@@ -244,6 +248,7 @@ irq: {
     lda #BLACK
     sta BGCOL
   //SEG23 [14] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -310,9 +315,11 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG12 [6] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -320,9 +327,11 @@ main: {
     lda #0
     sta RASTER
   //SEG14 [8] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG15 [9] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_KEYBOARD)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta KERNEL_IRQ
     lda #>irq
@@ -346,6 +355,7 @@ irq: {
     lda #BLACK
     sta BGCOL
   //SEG23 [14] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -443,9 +453,11 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG12 [6] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -453,9 +465,11 @@ main: {
     lda #0
     sta RASTER
   //SEG14 [8] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG15 [9] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_KEYBOARD)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta KERNEL_IRQ
     lda #>irq
@@ -477,6 +491,7 @@ irq: {
     lda #BLACK
     sta BGCOL
   //SEG23 [14] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG24 irq::@return

src/test/ref/irq-raster.asm

@@ -15,15 +15,19 @@
   .const CIA_INTERRUPT_CLEAR = $7f
 main: {
     sei
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
     lda #0
     sta RASTER
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
+    //  Set the IRQ routine
     lda #<irq
     sta KERNEL_IRQ
     lda #>irq
@@ -37,6 +41,7 @@ irq: {
     sta BGCOL
     lda #BLACK
     sta BGCOL
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp $ea81

src/test/ref/irq-raster.log

@@ -208,9 +208,11 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG12 [6] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -218,9 +220,11 @@ main: {
     lda #0
     sta RASTER
   //SEG14 [8] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG15 [9] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_MIN)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta KERNEL_IRQ
     lda #>irq
@@ -244,6 +248,7 @@ irq: {
     lda #BLACK
     sta BGCOL
   //SEG23 [14] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -310,9 +315,11 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG12 [6] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -320,9 +327,11 @@ main: {
     lda #0
     sta RASTER
   //SEG14 [8] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG15 [9] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_MIN)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta KERNEL_IRQ
     lda #>irq
@@ -346,6 +355,7 @@ irq: {
     lda #BLACK
     sta BGCOL
   //SEG23 [14] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
     jmp breturn
@@ -443,9 +453,11 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) CIA1_INTERRUPT#0) ← (const byte) CIA_INTERRUPT_CLEAR#0 -- _deref_pbuc1=vbuc2 
+    //  Disable CIA 1 Timer IRQ
     lda #CIA_INTERRUPT_CLEAR
     sta CIA1_INTERRUPT
   //SEG12 [6] *((const byte*) VIC_CONTROL#0) ← *((const byte*) VIC_CONTROL#0) | (byte/word/signed word/dword/signed dword) 128 -- _deref_pbuc1=_deref_pbuc1_bor_vbuc2 
+    //  Set raster line to $100
     lda VIC_CONTROL
     ora #$80
     sta VIC_CONTROL
@@ -453,9 +465,11 @@ main: {
     lda #0
     sta RASTER
   //SEG14 [8] *((const byte*) IRQ_ENABLE#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Enable Raster Interrupt
     lda #IRQ_RASTER
     sta IRQ_ENABLE
   //SEG15 [9] *((const void()**) KERNEL_IRQ#0) ← &interrupt(KERNEL_MIN)(void()) irq() -- _deref_pptc1=pprc2 
+    //  Set the IRQ routine
     lda #<irq
     sta KERNEL_IRQ
     lda #>irq
@@ -477,6 +491,7 @@ irq: {
     lda #BLACK
     sta BGCOL
   //SEG23 [14] *((const byte*) IRQ_STATUS#0) ← (const byte) IRQ_RASTER#0 -- _deref_pbuc1=vbuc2 
+    //  Acknowledge the IRQ
     lda #IRQ_RASTER
     sta IRQ_STATUS
   //SEG24 irq::@return

src/test/ref/line-anim.asm

@@ -32,6 +32,8 @@ main: {
     .const toD0181_return = (>(SCREEN&$3fff)<<2)|(>BITMAP)>>2&$f
     .label i = 2
     sei
+    //  Disable normal interrupt
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
     lda #PROCPORT_RAM_IO
@@ -219,8 +221,10 @@ point_init: {
     sta delay,y
     rts
   b1:
+    //  X is driver - abs(y/x) is < 1
     lda x_diff+1
     bmi b3
+    //  x add = 1.0
     ldy point_idx
     lda #$10
     sta x_add,y
@@ -239,6 +243,7 @@ point_init: {
     sta y_add,y
     jmp b2
   b3:
+    //  x add = -1.0
     ldy point_idx
     lda #-$10
     sta x_add,y

src/test/ref/line-anim.log

@@ -3160,6 +3160,8 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
@@ -3507,12 +3509,14 @@ point_init: {
   //SEG98 point_init::@1
   b1:
   //SEG99 [55] if((signed word) point_init::x_diff#1<(byte/signed byte/word/signed word/dword/signed dword) 0) goto point_init::@3 -- vwsz1_lt_0_then_la1 
+    //  X is driver - abs(y/x) is < 1
     lda x_diff+1
     bmi b3
     jmp b7
   //SEG100 point_init::@7
   b7:
   //SEG101 [56] *((const signed byte[4]) x_add#0 + (byte) point_init::point_idx#0) ← (byte/signed byte/word/signed word/dword/signed dword) 16 -- pbsc1_derefidx_vbuz1=vbuc2 
+    //  x add = 1.0
     ldy point_idx
     lda #$10
     sta x_add,y
@@ -3564,6 +3568,7 @@ point_init: {
   //SEG113 point_init::@3
   b3:
   //SEG114 [65] *((const signed byte[4]) x_add#0 + (byte) point_init::point_idx#0) ← -(byte/signed byte/word/signed word/dword/signed dword) 16 -- pbsc1_derefidx_vbuz1=vbsc2 
+    //  x add = -1.0
     ldy point_idx
     lda #-$10
     sta x_add,y
@@ -4582,6 +4587,8 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
@@ -4915,12 +4922,14 @@ point_init: {
   //SEG98 point_init::@1
   b1:
   //SEG99 [55] if((signed word) point_init::x_diff#1<(byte/signed byte/word/signed word/dword/signed dword) 0) goto point_init::@3 -- vwsz1_lt_0_then_la1 
+    //  X is driver - abs(y/x) is < 1
     lda x_diff+1
     bmi b3
     jmp b7
   //SEG100 point_init::@7
   b7:
   //SEG101 [56] *((const signed byte[4]) x_add#0 + (byte) point_init::point_idx#0) ← (byte/signed byte/word/signed word/dword/signed dword) 16 -- pbsc1_derefidx_vbuz1=vbuc2 
+    //  x add = 1.0
     ldy point_idx
     lda #$10
     sta x_add,y
@@ -4956,6 +4965,7 @@ point_init: {
   //SEG113 point_init::@3
   b3:
   //SEG114 [65] *((const signed byte[4]) x_add#0 + (byte) point_init::point_idx#0) ← -(byte/signed byte/word/signed word/dword/signed dword) 16 -- pbsc1_derefidx_vbuz1=vbsc2 
+    //  x add = -1.0
     ldy point_idx
     lda #-$10
     sta x_add,y
@@ -5707,8 +5717,8 @@ Removing instruction b10:
 Succesful ASM optimization Pass5UnusedLabelElimination
 Removing unreachable instruction jmp b2
 Succesful ASM optimization Pass5UnreachableCodeElimination
-Fixing long branch [155] bmi abs16s1_b1 to bpl
-Fixing long branch [164] bmi abs16s2_b1 to bpl
+Fixing long branch [157] bmi abs16s1_b1 to bpl
+Fixing long branch [166] bmi abs16s2_b1 to bpl
 
 FINAL SYMBOL TABLE
 (label) @19
@@ -6167,6 +6177,8 @@ main: {
   //SEG10 asm { sei  }
     sei
   //SEG11 [5] *((const byte*) PROCPORT_DDR#0) ← (const byte) PROCPORT_DDR_MEMORY_MASK#0 -- _deref_pbuc1=vbuc2 
+    //  Disable normal interrupt
+    //  Disable kernal & basic
     lda #PROCPORT_DDR_MEMORY_MASK
     sta PROCPORT_DDR
   //SEG12 [6] *((const byte*) PROCPORT#0) ← (const byte) PROCPORT_RAM_IO#0 -- _deref_pbuc1=vbuc2 
@@ -6442,10 +6454,12 @@ point_init: {
   //SEG98 point_init::@1
   b1:
   //SEG99 [55] if((signed word) point_init::x_diff#1<(byte/signed byte/word/signed word/dword/signed dword) 0) goto point_init::@3 -- vwsz1_lt_0_then_la1 
+    //  X is driver - abs(y/x) is < 1
     lda x_diff+1
     bmi b3
   //SEG100 point_init::@7
   //SEG101 [56] *((const signed byte[4]) x_add#0 + (byte) point_init::point_idx#0) ← (byte/signed byte/word/signed word/dword/signed dword) 16 -- pbsc1_derefidx_vbuz1=vbuc2 
+    //  x add = 1.0
     ldy point_idx
     lda #$10
     sta x_add,y
@@ -6477,6 +6491,7 @@ point_init: {
   //SEG113 point_init::@3
   b3:
   //SEG114 [65] *((const signed byte[4]) x_add#0 + (byte) point_init::point_idx#0) ← -(byte/signed byte/word/signed word/dword/signed dword) 16 -- pbsc1_derefidx_vbuz1=vbsc2 
+    //  x add = -1.0
     ldy point_idx
     lda #-$10
     sta x_add,y

src/test/ref/min-fmul-16.asm

@@ -305,6 +305,7 @@ mulf_init: {
     lda sqr2_lo
     cmp #<mulf_sqr2_lo+$1ff
     bne b3
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
     lda mulf_sqr1_hi+$100

src/test/ref/min-fmul-16.log

@@ -1909,6 +1909,7 @@ mulf_init: {
   //SEG147 mulf_init::@8
   b8:
   //SEG148 [73] *((const byte[512]) mulf_sqr2_lo#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_lo#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
   //SEG149 [74] *((const byte[512]) mulf_sqr2_hi#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_hi#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
@@ -2600,6 +2601,7 @@ mulf_init: {
   //SEG147 mulf_init::@8
   b8:
   //SEG148 [73] *((const byte[512]) mulf_sqr2_lo#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_lo#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
   //SEG149 [74] *((const byte[512]) mulf_sqr2_hi#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_hi#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
@@ -3334,6 +3336,7 @@ mulf_init: {
     bne b3
   //SEG147 mulf_init::@8
   //SEG148 [73] *((const byte[512]) mulf_sqr2_lo#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_lo#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
   //SEG149 [74] *((const byte[512]) mulf_sqr2_hi#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_hi#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 

src/test/ref/ptr-complex.asm

@@ -27,6 +27,7 @@ main: {
     bne b1
     lda screen+$79
     sta sc2
+    //  LValue pointer expression (constant - directly)
     lda screen+$7a
     sta screen+$52
     ldx #0

src/test/ref/ptr-complex.log

@@ -349,6 +349,7 @@ main: {
     lda screen+$79
     sta sc2
   //SEG22 [11] *((const byte*) main::screen#0+(byte/signed byte/word/signed word/dword/signed dword) 82) ← *((const byte*) main::screen#0+(byte/signed byte/word/signed word/dword/signed dword) 122) -- _deref_pbuc1=_deref_pbuc2 
+    //  LValue pointer expression (constant - directly)
     lda screen+$7a
     sta screen+$52
   //SEG23 [12] phi from main::@3 to main::@2 [phi:main::@3->main::@2]
@@ -509,6 +510,7 @@ main: {
     lda screen+$79
     sta sc2
   //SEG22 [11] *((const byte*) main::screen#0+(byte/signed byte/word/signed word/dword/signed dword) 82) ← *((const byte*) main::screen#0+(byte/signed byte/word/signed word/dword/signed dword) 122) -- _deref_pbuc1=_deref_pbuc2 
+    //  LValue pointer expression (constant - directly)
     lda screen+$7a
     sta screen+$52
   //SEG23 [12] phi from main::@3 to main::@2 [phi:main::@3->main::@2]
@@ -689,6 +691,7 @@ main: {
     lda screen+$79
     sta sc2
   //SEG22 [11] *((const byte*) main::screen#0+(byte/signed byte/word/signed word/dword/signed dword) 82) ← *((const byte*) main::screen#0+(byte/signed byte/word/signed word/dword/signed dword) 122) -- _deref_pbuc1=_deref_pbuc2 
+    //  LValue pointer expression (constant - directly)
     lda screen+$7a
     sta screen+$52
   //SEG23 [12] phi from main::@3 to main::@2 [phi:main::@3->main::@2]

src/test/ref/ptrtest.asm

@@ -56,7 +56,9 @@ rvaluevar: {
 rvalue: {
     //  A constant pointer
     .label SCREEN = $400
+    //  RValue constant pointer
     lda SCREEN
+    //  RValue constant array pointer constant index
     lda SCREEN+1
     ldx #2
   b1:
@@ -71,8 +73,10 @@ rvalue: {
 lvalue: {
     //  A constant pointer
     .label SCREEN = $400
+    //  LValue constant pointer dereference
     lda #1
     sta SCREEN
+    //  LValue constant array constant indexing
     lda #2
     sta SCREEN+1
     tax

src/test/ref/ptrtest.log

@@ -580,9 +580,11 @@ rvalue: {
     .label b_2 = $d
     .label i = 8
   //SEG56 [27] (byte) rvalue::b#0 ← *((const byte[1024]) rvalue::SCREEN#0) -- vbuz1=_deref_pbuc1 
+    //  RValue constant pointer
     lda SCREEN
     sta b
   //SEG57 [28] (byte) rvalue::b#1 ← *((const byte[1024]) rvalue::SCREEN#0+(byte/signed byte/word/signed word/dword/signed dword) 1) -- vbuz1=_deref_pbuc1 
+    //  RValue constant array pointer constant index
     lda SCREEN+1
     sta b_1
   //SEG58 [29] phi from rvalue to rvalue::@1 [phi:rvalue->rvalue::@1]
@@ -621,9 +623,11 @@ lvalue: {
     .label SCREEN = $400
     .label i = 9
   //SEG70 [34] *((const byte[1024]) lvalue::SCREEN#0) ← (byte/signed byte/word/signed word/dword/signed dword) 1 -- _deref_pbuc1=vbuc2 
+    //  LValue constant pointer dereference
     lda #1
     sta SCREEN
   //SEG71 [35] *((const byte[1024]) lvalue::SCREEN#0+(byte/signed byte/word/signed word/dword/signed dword) 1) ← (byte/signed byte/word/signed word/dword/signed dword) 2 -- _deref_pbuc1=vbuc2 
+    //  LValue constant array constant indexing
     lda #2
     sta SCREEN+1
   //SEG72 [36] phi from lvalue to lvalue::@1 [phi:lvalue->lvalue::@1]
@@ -850,8 +854,10 @@ rvalue: {
     //  A constant pointer
     .label SCREEN = $400
   //SEG56 [27] (byte) rvalue::b#0 ← *((const byte[1024]) rvalue::SCREEN#0) -- vbuaa=_deref_pbuc1 
+    //  RValue constant pointer
     lda SCREEN
   //SEG57 [28] (byte) rvalue::b#1 ← *((const byte[1024]) rvalue::SCREEN#0+(byte/signed byte/word/signed word/dword/signed dword) 1) -- vbuaa=_deref_pbuc1 
+    //  RValue constant array pointer constant index
     lda SCREEN+1
   //SEG58 [29] phi from rvalue to rvalue::@1 [phi:rvalue->rvalue::@1]
   b1_from_rvalue:
@@ -884,9 +890,11 @@ lvalue: {
     //  A constant pointer
     .label SCREEN = $400
   //SEG70 [34] *((const byte[1024]) lvalue::SCREEN#0) ← (byte/signed byte/word/signed word/dword/signed dword) 1 -- _deref_pbuc1=vbuc2 
+    //  LValue constant pointer dereference
     lda #1
     sta SCREEN
   //SEG71 [35] *((const byte[1024]) lvalue::SCREEN#0+(byte/signed byte/word/signed word/dword/signed dword) 1) ← (byte/signed byte/word/signed word/dword/signed dword) 2 -- _deref_pbuc1=vbuc2 
+    //  LValue constant array constant indexing
     lda #2
     sta SCREEN+1
   //SEG72 [36] phi from lvalue to lvalue::@1 [phi:lvalue->lvalue::@1]
@@ -1153,8 +1161,10 @@ rvalue: {
     //  A constant pointer
     .label SCREEN = $400
   //SEG56 [27] (byte) rvalue::b#0 ← *((const byte[1024]) rvalue::SCREEN#0) -- vbuaa=_deref_pbuc1 
+    //  RValue constant pointer
     lda SCREEN
   //SEG57 [28] (byte) rvalue::b#1 ← *((const byte[1024]) rvalue::SCREEN#0+(byte/signed byte/word/signed word/dword/signed dword) 1) -- vbuaa=_deref_pbuc1 
+    //  RValue constant array pointer constant index
     lda SCREEN+1
   //SEG58 [29] phi from rvalue to rvalue::@1 [phi:rvalue->rvalue::@1]
   //SEG59 [29] phi (byte) rvalue::i#2 = (byte/signed byte/word/signed word/dword/signed dword) 2 [phi:rvalue->rvalue::@1#0] -- vbuxx=vbuc1 
@@ -1182,9 +1192,11 @@ lvalue: {
     //  A constant pointer
     .label SCREEN = $400
   //SEG70 [34] *((const byte[1024]) lvalue::SCREEN#0) ← (byte/signed byte/word/signed word/dword/signed dword) 1 -- _deref_pbuc1=vbuc2 
+    //  LValue constant pointer dereference
     lda #1
     sta SCREEN
   //SEG71 [35] *((const byte[1024]) lvalue::SCREEN#0+(byte/signed byte/word/signed word/dword/signed dword) 1) ← (byte/signed byte/word/signed word/dword/signed dword) 2 -- _deref_pbuc1=vbuc2 
+    //  LValue constant array constant indexing
     lda #2
     sta SCREEN+1
   //SEG72 [36] phi from lvalue to lvalue::@1 [phi:lvalue->lvalue::@1]

src/test/ref/scan-desire-problem.asm

@@ -262,6 +262,7 @@ fill: {
 init_sprites: {
     lda #1
     sta SPRITES_ENABLE
+    //  one sprite enabled
     lda #0
     sta SPRITES_EXPAND_X
     sta SPRITES_EXPAND_Y

src/test/ref/scan-desire-problem.log

@@ -2163,6 +2163,7 @@ init_sprites: {
     lda #1
     sta SPRITES_ENABLE
   //SEG121 [71] *((const byte*) SPRITES_EXPAND_X#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  one sprite enabled
     lda #0
     sta SPRITES_EXPAND_X
   //SEG122 [72] *((const byte*) SPRITES_EXPAND_Y#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
@@ -2771,6 +2772,7 @@ init_sprites: {
     lda #1
     sta SPRITES_ENABLE
   //SEG121 [71] *((const byte*) SPRITES_EXPAND_X#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  one sprite enabled
     lda #0
     sta SPRITES_EXPAND_X
   //SEG122 [72] *((const byte*) SPRITES_EXPAND_Y#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
@@ -3562,6 +3564,7 @@ init_sprites: {
     lda #1
     sta SPRITES_ENABLE
   //SEG121 [71] *((const byte*) SPRITES_EXPAND_X#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  one sprite enabled
     lda #0
     sta SPRITES_EXPAND_X
   //SEG122 [72] *((const byte*) SPRITES_EXPAND_Y#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 

src/test/ref/sinus-basic.asm

@@ -139,6 +139,7 @@ print_char: {
 //  Destroys the value in the FAC in the process
 getFAC: {
     .label return = 7
+    //  Load FAC (floating point accumulator) integer part into word register Y,A
     jsr $b1aa
     sty $fe
     sta $ff
@@ -208,6 +209,7 @@ divMEMbyFAC: {
 setFAC: {
     .label w = 7
     jsr prepareMEM
+    //  Load word register Y,A into FAC (floating point accumulator)
     ldy $fe
     lda $ff
     jsr $b391

src/test/ref/sinus-basic.log

@@ -1431,6 +1431,7 @@ getFAC: {
     .label return = $17
     .label return_2 = $11
   //SEG128 asm { jsr$b1aa sty$fe sta$ff  }
+    //  Load FAC (floating point accumulator) integer part into word register Y,A
     jsr $b1aa
     sty $fe
     sta $ff
@@ -1584,6 +1585,7 @@ setFAC: {
   //SEG173 setFAC::@1
   b1:
   //SEG174 asm { ldy$fe lda$ff jsr$b391  }
+    //  Load word register Y,A into FAC (floating point accumulator)
     ldy $fe
     lda $ff
     jsr $b391
@@ -2094,6 +2096,7 @@ print_char: {
 getFAC: {
     .label return = 7
   //SEG128 asm { jsr$b1aa sty$fe sta$ff  }
+    //  Load FAC (floating point accumulator) integer part into word register Y,A
     jsr $b1aa
     sty $fe
     sta $ff
@@ -2233,6 +2236,7 @@ setFAC: {
   //SEG173 setFAC::@1
   b1:
   //SEG174 asm { ldy$fe lda$ff jsr$b391  }
+    //  Load word register Y,A into FAC (floating point accumulator)
     ldy $fe
     lda $ff
     jsr $b391
@@ -2803,6 +2807,7 @@ print_char: {
 getFAC: {
     .label return = 7
   //SEG128 asm { jsr$b1aa sty$fe sta$ff  }
+    //  Load FAC (floating point accumulator) integer part into word register Y,A
     jsr $b1aa
     sty $fe
     sta $ff
@@ -2918,6 +2923,7 @@ setFAC: {
     jsr prepareMEM
   //SEG173 setFAC::@1
   //SEG174 asm { ldy$fe lda$ff jsr$b391  }
+    //  Load word register Y,A into FAC (floating point accumulator)
     ldy $fe
     lda $ff
     jsr $b391

src/test/ref/test-comments-single.asm

@@ -12,6 +12,7 @@ main: {
     ldy #0
   b1:
     jsr sum
+    //  Output the result on the screen
     sta SCREEN,x
     inx
     iny

src/test/ref/test-comments-single.log

@@ -296,6 +296,7 @@ main: {
     lda sum.return
     sta _0
   //SEG23 [10] *((const byte*) SCREEN#0 + (byte) main::i#2) ← (byte~) main::$0 -- pbuc1_derefidx_vbuz1=vbuz2 
+    //  Output the result on the screen
     lda _0
     ldy i
     sta SCREEN,y
@@ -409,6 +410,7 @@ main: {
   b3:
   //SEG22 [9] (byte~) main::$0 ← (byte) sum::return#0
   //SEG23 [10] *((const byte*) SCREEN#0 + (byte) main::i#2) ← (byte~) main::$0 -- pbuc1_derefidx_vbuxx=vbuaa 
+    //  Output the result on the screen
     sta SCREEN,x
   //SEG24 [11] (byte) main::i#1 ← ++ (byte) main::i#2 -- vbuxx=_inc_vbuxx 
     inx
@@ -547,6 +549,7 @@ main: {
   //SEG21 main::@3
   //SEG22 [9] (byte~) main::$0 ← (byte) sum::return#0
   //SEG23 [10] *((const byte*) SCREEN#0 + (byte) main::i#2) ← (byte~) main::$0 -- pbuc1_derefidx_vbuxx=vbuaa 
+    //  Output the result on the screen
     sta SCREEN,x
   //SEG24 [11] (byte) main::i#1 ← ++ (byte) main::i#2 -- vbuxx=_inc_vbuxx 
     inx

src/test/ref/test-keyboard-space.asm

@@ -57,8 +57,10 @@ keyboard_matrix_read: {
 }
 //  Initialize keyboard reading by setting CIA#$ Data Direction Registers
 keyboard_init: {
+    //  Keyboard Matrix Columns Write Mode
     lda #$ff
     sta CIA1_PORT_A_DDR
+    //  Keyboard Matrix Columns Read Mode
     lda #0
     sta CIA1_PORT_B_DDR
     rts

src/test/ref/test-keyboard-space.log

@@ -1229,9 +1229,11 @@ keyboard_matrix_read: {
 //  Initialize keyboard reading by setting CIA#$ Data Direction Registers
 keyboard_init: {
   //SEG40 [23] *((const byte*) CIA1_PORT_A_DDR#0) ← (byte/word/signed word/dword/signed dword) 255 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Write Mode
     lda #$ff
     sta CIA1_PORT_A_DDR
   //SEG41 [24] *((const byte*) CIA1_PORT_B_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Read Mode
     lda #0
     sta CIA1_PORT_B_DDR
     jmp breturn
@@ -1399,9 +1401,11 @@ keyboard_matrix_read: {
 //  Initialize keyboard reading by setting CIA#$ Data Direction Registers
 keyboard_init: {
   //SEG40 [23] *((const byte*) CIA1_PORT_A_DDR#0) ← (byte/word/signed word/dword/signed dword) 255 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Write Mode
     lda #$ff
     sta CIA1_PORT_A_DDR
   //SEG41 [24] *((const byte*) CIA1_PORT_B_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Read Mode
     lda #0
     sta CIA1_PORT_B_DDR
     jmp breturn
@@ -1759,9 +1763,11 @@ keyboard_matrix_read: {
 //  Initialize keyboard reading by setting CIA#$ Data Direction Registers
 keyboard_init: {
   //SEG40 [23] *((const byte*) CIA1_PORT_A_DDR#0) ← (byte/word/signed word/dword/signed dword) 255 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Write Mode
     lda #$ff
     sta CIA1_PORT_A_DDR
   //SEG41 [24] *((const byte*) CIA1_PORT_B_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Read Mode
     lda #0
     sta CIA1_PORT_B_DDR
   //SEG42 keyboard_init::@return

src/test/ref/test-keyboard.asm

@@ -211,8 +211,10 @@ keyboard_get_keycode: {
 }
 //  Initialize keyboard reading by setting CIA#$ Data Direction Registers
 keyboard_init: {
+    //  Keyboard Matrix Columns Write Mode
     lda #$ff
     sta CIA1_PORT_A_DDR
+    //  Keyboard Matrix Columns Read Mode
     lda #0
     sta CIA1_PORT_B_DDR
     rts

src/test/ref/test-keyboard.log

@@ -2049,9 +2049,11 @@ keyboard_get_keycode: {
 //  Initialize keyboard reading by setting CIA#$ Data Direction Registers
 keyboard_init: {
   //SEG118 [63] *((const byte*) CIA1_PORT_A_DDR#0) ← (byte/word/signed word/dword/signed dword) 255 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Write Mode
     lda #$ff
     sta CIA1_PORT_A_DDR
   //SEG119 [64] *((const byte*) CIA1_PORT_B_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Read Mode
     lda #0
     sta CIA1_PORT_B_DDR
     jmp breturn
@@ -2564,9 +2566,11 @@ keyboard_get_keycode: {
 //  Initialize keyboard reading by setting CIA#$ Data Direction Registers
 keyboard_init: {
   //SEG118 [63] *((const byte*) CIA1_PORT_A_DDR#0) ← (byte/word/signed word/dword/signed dword) 255 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Write Mode
     lda #$ff
     sta CIA1_PORT_A_DDR
   //SEG119 [64] *((const byte*) CIA1_PORT_B_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Read Mode
     lda #0
     sta CIA1_PORT_B_DDR
     jmp breturn
@@ -3324,9 +3328,11 @@ keyboard_get_keycode: {
 //  Initialize keyboard reading by setting CIA#$ Data Direction Registers
 keyboard_init: {
   //SEG118 [63] *((const byte*) CIA1_PORT_A_DDR#0) ← (byte/word/signed word/dword/signed dword) 255 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Write Mode
     lda #$ff
     sta CIA1_PORT_A_DDR
   //SEG119 [64] *((const byte*) CIA1_PORT_B_DDR#0) ← (byte/signed byte/word/signed word/dword/signed dword) 0 -- _deref_pbuc1=vbuc2 
+    //  Keyboard Matrix Columns Read Mode
     lda #0
     sta CIA1_PORT_B_DDR
   //SEG120 keyboard_init::@return

src/test/ref/test-lowhigh.asm

@@ -57,6 +57,7 @@ main: {
     sta dw2+2
     lda _32+1
     sta dw2+3
+    //  Test set/get high word of dword
     lda dw2
     sta _4
     lda dw2+1

src/test/ref/test-lowhigh.log

@@ -1193,6 +1193,7 @@ main: {
     lda _32+1
     sta dw2+3
   //SEG22 [11] (word~) main::$4 ← < (dword) main::dw2#1 -- vwuz1=_lo_vduz2 
+    //  Test set/get high word of dword
     lda dw2
     sta _4
     lda dw2+1
@@ -1881,6 +1882,7 @@ main: {
     lda _32+1
     sta dw2+3
   //SEG22 [11] (word~) main::$4 ← < (dword) main::dw2#1 -- vwuz1=_lo_vduz2 
+    //  Test set/get high word of dword
     lda dw2
     sta _4
     lda dw2+1
@@ -2625,6 +2627,7 @@ main: {
     lda _32+1
     sta dw2+3
   //SEG22 [11] (word~) main::$4 ← < (dword) main::dw2#1 -- vwuz1=_lo_vduz2 
+    //  Test set/get high word of dword
     lda dw2
     sta _4
     lda dw2+1

src/test/ref/test-multiply-16bit.asm

@@ -1093,6 +1093,7 @@ mulf_init: {
     lda sqr2_lo
     cmp #<mulf_sqr2_lo+$1ff
     bne b3
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
     lda mulf_sqr1_hi+$100

src/test/ref/test-multiply-16bit.log

@@ -7153,6 +7153,7 @@ mulf_init: {
   //SEG663 mulf_init::@8
   b8:
   //SEG664 [304] *((const byte[512]) mulf_sqr2_lo#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_lo#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
   //SEG665 [305] *((const byte[512]) mulf_sqr2_hi#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_hi#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
@@ -9864,6 +9865,7 @@ mulf_init: {
   //SEG663 mulf_init::@8
   b8:
   //SEG664 [304] *((const byte[512]) mulf_sqr2_lo#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_lo#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
   //SEG665 [305] *((const byte[512]) mulf_sqr2_hi#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_hi#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
@@ -12583,6 +12585,7 @@ mulf_init: {
     bne b3
   //SEG663 mulf_init::@8
   //SEG664 [304] *((const byte[512]) mulf_sqr2_lo#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_lo#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
   //SEG665 [305] *((const byte[512]) mulf_sqr2_hi#0+(word/signed word/dword/signed dword) 511) ← *((const byte[512]) mulf_sqr1_hi#0+(word/signed word/dword/signed dword) 256) -- _deref_pbuc1=_deref_pbuc2 

src/test/ref/test-multiply-8bit.asm

@@ -856,6 +856,7 @@ mulf_init: {
     lda sqr2_lo
     cmp #<mulf_sqr2_lo+$1ff
     bne b3
+    //  Set the very last value g(511) = f(256)
     lda mulf_sqr1_lo+$100
     sta mulf_sqr2_lo+$1ff
     lda mulf_sqr1_hi+$100