Add two-pass assembly and require explicit ISA specification

timsherwood · claude · timsherwood · commit f4b5044c5e62 · 2026-01-10T18:22:19.000-08:00
- Implement two-pass assembly for forward label references
- Require .isa directive or --isa flag (remove heuristic detection)
- Add pseudo-instruction expansion for MIPS (blt, bge, ble, bgt)
- Add pseudo-branch handling for RISC-V (ble, bgt, bleu, bgtu, etc.)
- Fix x86-64 AT&amp;T syntax (movslq, decq, incq, SIB addressing)
- Fix ARM64 comment parsing for negative immediates (#-32)
- Collect labels from all sections (not just standard ones)
- Add .bss stack sections to RISC-V fibonacci/matrix examples
- Add .isa directive to all 20 example programs
- Add tests for ISA specification and forward references

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/examples/arm/array_stats/array_stats.s b/examples/arm/array_stats/array_stats.s
@@ -10,6 +10,8 @@
 #   5. Conditional branches (b.lt, b.gt, b.eq)
 #
 # ============================================================================
+.isa arm64
+
 
     .data
 
diff --git a/examples/arm/fibonacci/fibonacci.s b/examples/arm/fibonacci/fibonacci.s
@@ -15,6 +15,8 @@
 # - Base case and recursive case handling
 # - Register save/restore conventions
 # ============================================================================
+.isa arm64
+
 
 .section .data
     # Input value: calculate Fibonacci(7)
diff --git a/examples/arm/guess_game/guess_game.s b/examples/arm/guess_game/guess_game.s
@@ -12,6 +12,8 @@
 # guess is too high or too low.
 #
 # ============================================================================
+.isa arm64
+
 
     .data
 
diff --git a/examples/arm/hello_asm/hello_asm.s b/examples/arm/hello_asm/hello_asm.s
@@ -14,6 +14,8 @@
 #   (mapachespim) run
 #
 # ============================================================================
+.isa arm64
+
 
 # ----------------------------------------------------------------------------
 # DATA SECTION
diff --git a/examples/arm/matrix_multiply/matrix_mult.s b/examples/arm/matrix_multiply/matrix_mult.s
@@ -13,6 +13,8 @@
 # - Register allocation and management
 # - ARM64 calling convention
 # ============================================================================
+.isa arm64
+
 
 .section .data
     # Matrix A (3x3) - stored in row-major order
diff --git a/examples/mips/array_stats/array_stats.s b/examples/mips/array_stats/array_stats.s
@@ -10,6 +10,8 @@
 #   5. Conditional jumps (blt, bgt, beq)
 #
 # ============================================================================
+.isa mips32
+
 
     .data
 
diff --git a/examples/mips/fibonacci/fibonacci.s b/examples/mips/fibonacci/fibonacci.s
@@ -15,6 +15,8 @@
 # - Base case and recursive case handling
 # - Callee-saved register preservation ($s0-$s7)
 # ============================================================================
+.isa mips32
+
 
 .section .data
     # Input value: calculate Fibonacci(7)
diff --git a/examples/mips/guess_game/guess_game.s b/examples/mips/guess_game/guess_game.s
@@ -12,6 +12,8 @@
 # guess is too high or too low.
 #
 # ============================================================================
+.isa mips32
+
 
     .data
 
diff --git a/examples/mips/hello_asm/hello_asm.s b/examples/mips/hello_asm/hello_asm.s
@@ -14,6 +14,8 @@
 #   (mapachespim) run
 #
 # ============================================================================
+.isa mips32
+
 
 # ----------------------------------------------------------------------------
 # DATA SECTION
diff --git a/examples/mips/matrix_multiply/matrix_mult.s b/examples/mips/matrix_multiply/matrix_mult.s
@@ -13,6 +13,8 @@
 # - Register allocation and management
 # - MIPS calling convention
 # ============================================================================
+.isa mips32
+
 
 .section .data
     # Matrix A (3x3) - stored in row-major order
diff --git a/examples/riscv/array_stats/array_stats.s b/examples/riscv/array_stats/array_stats.s
@@ -10,6 +10,8 @@
 #   5. Conditional branches (blt, bgt, beq)
 #
 # ============================================================================
+.isa riscv64
+
 
     .data
 
diff --git a/examples/riscv/fibonacci/fibonacci.s b/examples/riscv/fibonacci/fibonacci.s
@@ -15,6 +15,8 @@
 # - Base case and recursive case handling
 # - Register save/restore conventions
 # ============================================================================
+.isa riscv64
+
 
 .section .data
     # Input value: calculate Fibonacci(7)
@@ -25,6 +27,13 @@
     fib_result:
         .word 0
 
+.section .bss
+    # Stack space (4KB)
+    .align 4
+    _stack_bottom:
+        .space 4096
+    _stack_start:
+
 .section .text
 .globl _start
 
diff --git a/examples/riscv/guess_game/guess_game.s b/examples/riscv/guess_game/guess_game.s
@@ -12,6 +12,8 @@
 # guess is too high or too low.
 #
 # ============================================================================
+.isa riscv64
+
 
     .data
 
diff --git a/examples/riscv/hello_asm/hello_asm.s b/examples/riscv/hello_asm/hello_asm.s
@@ -14,6 +14,8 @@
 #   (mapachespim) run
 #
 # ============================================================================
+.isa riscv64
+
 
 # ----------------------------------------------------------------------------
 # DATA SECTION
diff --git a/examples/riscv/matrix_multiply/matrix_mult.s b/examples/riscv/matrix_multiply/matrix_mult.s
@@ -13,6 +13,8 @@
 # - Register allocation and management
 # - RISC-V calling convention
 # ============================================================================
+.isa riscv64
+
 
 .section .data
     # Matrix A (3x3) - stored in row-major order
@@ -181,6 +183,13 @@ end_outer:
 # [138  114   90 ]     (7*9+8*6+9*3=138, 7*8+8*5+9*2=114, 7*7+8*4+9*1=90)
 # ============================================================================
 
+# Stack space in .bss section
+.section .bss
+    .align 4
+    _stack_bottom:
+        .space 4096
+    _stack_start:
+
 # HTIF (Host-Target Interface) section for Sail emulator
 .section .tohost,"aw",@progbits
 .align 6
diff --git a/examples/x86_64/array_stats/array_stats.s b/examples/x86_64/array_stats/array_stats.s
@@ -11,6 +11,8 @@
 #
 # Note: This uses AT&T syntax (GNU assembler style)
 # ============================================================================
+.isa x86_64
+
 
     .data
 
diff --git a/examples/x86_64/fibonacci/fibonacci.S b/examples/x86_64/fibonacci/fibonacci.S
@@ -15,6 +15,8 @@
 # - Base case and recursive case handling
 # - Callee-saved register preservation
 # ============================================================================
+.isa x86_64
+
 
 .section .data
     # Input value: calculate Fibonacci(7)
diff --git a/examples/x86_64/guess_game/guess_game.s b/examples/x86_64/guess_game/guess_game.s
@@ -13,6 +13,8 @@
 #
 # Note: This uses AT&T syntax (GNU assembler style)
 # ============================================================================
+.isa x86_64
+
 
     .data
 
diff --git a/examples/x86_64/hello_asm/hello_asm.s b/examples/x86_64/hello_asm/hello_asm.s
@@ -15,6 +15,8 @@
 #
 # Note: This uses AT&T syntax (GNU assembler style)
 # ============================================================================
+.isa x86_64
+
 
 # ----------------------------------------------------------------------------
 # DATA SECTION
diff --git a/examples/x86_64/matrix_multiply/matrix_mult.S b/examples/x86_64/matrix_multiply/matrix_mult.S
@@ -13,6 +13,8 @@
 # - Register allocation and management
 # - x86-64 calling convention
 # ============================================================================
+.isa x86_64
+
 
 .section .data
     # Matrix A (3x3) - stored in row-major order
diff --git a/mapachespim/toolchain/__init__.py b/mapachespim/toolchain/__init__.py
@@ -108,7 +108,7 @@ def assemble_file(
         source_path: Path to the assembly source file.
         output_path: Path for the output ELF file. If None, uses source
                      path with .elf extension.
-        isa: Target ISA. If None, attempts to auto-detect from source.
+        isa: Target ISA. If None, looks for .isa directive in source.
         entry_symbol: Entry point symbol name (default: "_start").
 
     Returns:
@@ -120,6 +120,8 @@ def assemble_file(
         >>> if result.success:
         ...     print(f"Assembled to {result.entry_point:#x}")
     """
+    from .directives import DirectiveParser
+
     source_path = Path(source_path)
 
     if not source_path.exists():
@@ -137,13 +139,13 @@ def assemble_file(
             errors=[f"Failed to read source file: {e}"],
         )
 
-    # Auto-detect ISA if not specified
+    # If ISA not specified via flag, check for .isa directive in source
     if isa is None:
-        isa = _detect_isa_from_source(source, source_path)
+        isa = _detect_isa_from_directive(source)
         if isa is None:
             return AssemblyResult(
                 elf_bytes=b"",
-                errors=["Could not auto-detect ISA. Please specify --isa."],
+                errors=[_isa_not_specified_error()],
             )
 
     # Assemble
@@ -160,46 +162,45 @@ def assemble_file(
     return result
 
 
-def _detect_isa_from_source(source: str, path: Path) -> Optional[str]:
+def _detect_isa_from_directive(source: str) -> Optional[str]:
     """
-    Attempt to detect ISA from source code or file path.
+    Look for .isa directive in source code.
 
-    Detection heuristics:
-    1. Look for .arch or .isa directive
-    2. Check for ISA-specific instructions
-    3. Check directory name hints
+    Returns the ISA if found, None otherwise.
     """
-    source_lower = source.lower()
-
-    # Check for explicit ISA directives
-    if ".arch rv64" in source_lower or ".riscv" in source_lower:
-        return "riscv64"
-    if ".arch armv8" in source_lower or ".aarch64" in source_lower:
-        return "arm64"
-    if ".code64" in source_lower or ".intel_syntax" in source_lower:
-        return "x86_64"
-    if ".mips" in source_lower or ".set mips" in source_lower:
-        return "mips32"
-
-    # Check for ISA-specific instructions
-    if "ecall" in source_lower or "addi " in source_lower:
-        return "riscv64"
-    if "svc " in source_lower or "mov x" in source_lower:
-        return "arm64"
-    if "syscall" in source_lower or "mov %rax" in source_lower:
-        return "x86_64"
-    if "syscall" in source_lower and "$v0" in source_lower:
-        return "mips32"
-
-    # Check directory path for hints
-    path_str = str(path).lower()
-    if "riscv" in path_str or "rv64" in path_str:
-        return "riscv64"
-    if "arm" in path_str or "aarch64" in path_str:
-        return "arm64"
-    if "x86" in path_str or "x64" in path_str:
-        return "x86_64"
-    if "mips" in path_str:
-        return "mips32"
+    from .directives import DirectiveParser
+
+    # Quick scan for .isa directive without full parse
+    for line in source.splitlines():
+        line = line.strip()
+        # Skip empty lines and comments
+        if not line or line.startswith('#') or line.startswith('//') or line.startswith(';'):
+            continue
+        # Check for .isa directive
+        if line.lower().startswith('.isa'):
+            parts = line.split(None, 1)
+            if len(parts) >= 2:
+                isa_value = parts[1].strip().lower().replace("-", "_")
+                if isa_value in DirectiveParser.VALID_ISAS:
+                    return isa_value
+        # Stop after first non-empty, non-comment, non-.isa line
+        # (the .isa directive should be at the top of the file)
+        if not line.startswith('.'):
+            break
 
     return None
+
+
+def _isa_not_specified_error() -> str:
+    """Generate helpful error message when ISA is not specified."""
+    return """ISA not specified
+
+Please specify the target architecture using one of:
+
+  1. Command-line flag:
+     mapachespim-as program.s --isa riscv64
+
+  2. File directive (add at start of file):
+     .isa riscv64
+
+Supported ISAs: arm64, mips32, riscv64, x86_64"""
diff --git a/mapachespim/toolchain/assembler.py b/mapachespim/toolchain/assembler.py
diff --git a/mapachespim/toolchain/directives.py b/mapachespim/toolchain/directives.py
diff --git a/tests/test_forward_references.py b/tests/test_forward_references.py
diff --git a/tests/test_isa_specification.py b/tests/test_isa_specification.py

Original file line number	Diff line number	Diff line change
`@@ -10,6 +10,8 @@`
`10`	`10`	`# 5. Conditional branches (b.lt, b.gt, b.eq)`
`11`	`11`	`#`
`12`	`12`	`# ============================================================================`
	`13`	`+.isa arm64`
	`14`	`+`
`13`	`15`
`14`	`16`	`.data`
`15`	`17`
Original file line number	Diff line number	Diff line change
`@@ -12,6 +12,8 @@`
`12`	`12`	`# guess is too high or too low.`
`13`	`13`	`#`
`14`	`14`	`# ============================================================================`
	`15`	`+.isa arm64`
	`16`	`+`
`15`	`17`
`16`	`18`	`.data`
`17`	`19`
Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,8 @@`
`14`	`14`	`# (mapachespim) run`
`15`	`15`	`#`
`16`	`16`	`# ============================================================================`
	`17`	`+.isa arm64`
	`18`	`+`
`17`	`19`
`18`	`20`	`# ----------------------------------------------------------------------------`
`19`	`21`	`# DATA SECTION`