Aviron: Add breakpoint, set gas, detect infinite loop (#703)

* Update README
* Cleanup tests
* Add breakpoint and gas command line options
* tests: Make the expected value output hex
* aviron: Detect infinite loop used as halt
* Add check_exit method to IO to capture exit instead of killing the process

Author: Grazfather

sim/aviron/README.md

@@ -8,16 +8,16 @@ AVR simulator in Zig.
 
 ```sh
 .
-├── doc                 # Documents for Aviron or AVR 
+├── doc                 # Documents for Aviron or AVR
 ├── samples             # Source of examples that can be run on the simulator
 ├── src                 # Source code
 │   ├── lib             # - Aviron emulator
 │   ├── libtestsuite    # - Source code of the testsuite library
 │   └── shared          # - Shared code between the tools, generated code and simulator
 ├── testsuite           # Contains the test suite of Aviron
 │   ├── instructions    # - Tests for single instructions
-│   ├── lib             # - Tests for the libtestsuie  
-│   ├── simulator       # - Tests for the simulator per se 
+│   ├── lib             # - Tests for the libtestsuite
+│   ├── simulator       # - Tests for the simulator per se
 │   └── testrunner      # - Tests for the test runner (conditions, checks, ...)
 ├── testsuite.avr-gcc   # Contains code for the test suite that cannot be built with LLVM right now
 │   └── instructions
@@ -29,8 +29,7 @@ AVR simulator in Zig.
 Run the test suite by invoking
 
 ```sh-session
-[~/projects/aviron]$ zig build test
-[~/projects/aviron]$ 
+$ zig build test
 ```
 
 The `test` step will recursively scan the folder `testsuite` for files of the following types:
@@ -42,7 +41,9 @@ The `test` step will recursively scan the folder `testsuite` for files of the fo
 - *load* `.bin`
 - *load* `.elf`
 
-File extensions marked *compile* will be compiled or assembled with the Zig compiler, then executed with the test runner. Those files allow embedding a JSON configuration via Zig file documentation comments:
+File extensions marked *compile* will be compiled or assembled with the Zig compiler, then executed
+with the test runner. Those files allow embedding a JSON configuration via Zig file documentation
+comments:
 
 ```zig
 //! {
@@ -58,15 +59,19 @@ export fn _start() callconv(.c) noreturn {
 }
 ```
 
-For files marked as *load*, another companion file `.bin.json` or similar contains the configuration for this test.
+For files marked as *load*, another companion file `.bin.json` or similar contains the configuration
+for this test.
 
-The [JSON schema](src/testconfig.zig) allows description of how the file is built and the test runner is executed. It also contains a set of pre- and postconditions that can be used to set up the CPU and validate it after the program exits.
+The [JSON schema](src/testconfig.zig) allows description of how the file is built and the test
+runner is executed. It also contains a set of pre- and postconditions that can be used to set up the
+CPU and validate it after the program exits.
 
-If you're not sure if your code compiled correctly, you can use the `debug-testsuite` build step to inspect the generated files:
+If you're not sure if your code compiled correctly, you can use the `debug-testsuite` build step to
+inspect the generated files:
 
 ```sh-session
-[~/projects/aviron]$ zig build debug-testsuite
-[~/projects/aviron]$ tree zig-out/
+$ zig build debug-testsuite
+$ tree zig-out/
 zig-out/
 ├── bin
 │   └── aviron-test-runner
@@ -90,7 +95,7 @@ zig-out/
 You can then disassemble those files with either `llvm-objdump` or `avr-objdump`:
 
 ```sh-session
-[~/projects/aviron]$ llvm-objdump -d zig-out/testsuite/instructions/out-exit-0.elf 
+$ llvm-objdump -d zig-out/testsuite/instructions/out-exit-0.elf
 
 zig-out/testsuite/instructions/out-exit-0.elf:  file format elf32-avr
 
@@ -99,8 +104,8 @@ Disassembly of section .text:
 00000000 <_start>:
        0: 00 27         clr     r16
        2: 00 b9         out     0x0, r16
-       
-[~/projects/aviron]$ avr-objdump -d zig-out/testsuite/instructions/out-exit-0.elf 
+
+$ avr-objdump -d zig-out/testsuite/instructions/out-exit-0.elf
 
 zig-out/testsuite/instructions/out-exit-0.elf:     file format elf32-avr
 
@@ -110,23 +115,30 @@ Disassembly of section .text:
    0:   00 27           eor     r16, r16
    2:   00 b9           out     0x00, r16       ; 0
 
-[~/projects/aviron]$ 
+$
 ```
 
-The test runner is located at [src/testrunner.zig](src/testrunner.zig) and behaves similar to the main `aviron` executable, but introduces a good amount of checks we can use to inspect and validate the simulation.
+The test runner is located at [src/testrunner.zig](src/testrunner.zig) and behaves similar to the
+main `aviron` executable, but introduces a good amount of checks we can use to inspect and validate
+the simulation.
 
 ### Updating AVR-GCC tests
 
-To prevent a hard dependency on the `avr-gcc` toolchain, we vendor the binaries for all tests defined in the folder `testsuite.avr-gcc`. To update the files, you need to invoke the `update-testsuite` build step:
+To prevent a hard dependency on the `avr-gcc` toolchain, we vendor the binaries for all tests
+defined in the folder `testsuite.avr-gcc`. To update the files, you need to invoke the
+`update-testsuite` build step:
 
 ```sh-session
-[~/projects/aviron]$ zig build update-testsuite
-[~/projects/aviron]$ 
+$ zig build update-testsuite
+$
 ```
 
 After that, `zig build test` will run the regenerated tests.
 
-**NOTE:** The build will not detect changed files, so you have no guarantee that running `zig build update-testsuite test` will actually do the right thing. If you're working on the test suite, just use `zig build update-testsuite && zig build test` for this.
+> [!NOTE]
+> The build will not detect changed files, so you have no guarantee that running `zig build
+> update-testsuite test` will actually do the right thing. If you're working on the test suite, just
+> use `zig build update-testsuite && zig build test` for this.
 
 ## Links
 

sim/aviron/src/lib/Cpu.zig

@@ -44,6 +44,9 @@ const InstructionEffect = enum {
     sleep,
 
     watchdog_reset,
+
+    /// Detected infinite loop (typically __stop_program after main returns)
+    infinite_loop,
 };
 
 // Options:
@@ -62,6 +65,7 @@ io: IO,
 pc: u24 = 0,
 regs: [32]u8 = [1]u8{0} ** 32,
 sreg: SREG = @bitCast(@as(u8, 0)),
+instr_count: u64 = 0,
 
 instr_effect: InstructionEffect = .none,
 
@@ -77,9 +81,11 @@ pub const RunResult = enum {
     enter_sleep_mode,
     reset_watchdog,
     out_of_gas,
+    infinite_loop,
+    program_exit,
 };
 
-pub fn run(cpu: *Cpu, mileage: ?u64) RunError!RunResult {
+pub fn run(cpu: *Cpu, mileage: ?u64, breakpoint: ?u24) RunError!RunResult {
     var rest_gas = mileage;
 
     while (true) {
@@ -97,11 +103,21 @@ pub fn run(cpu: *Cpu, mileage: ?u64) RunError!RunResult {
                 .breakpoint => return .breakpoint,
                 .sleep => return .enter_sleep_mode,
                 .watchdog_reset => return .reset_watchdog,
+                .infinite_loop => return .infinite_loop,
             };
         };
 
         const pc = cpu.pc;
+
+        // Check breakpoint
+        if (breakpoint) |bp_addr| {
+            if (pc == bp_addr) {
+                return .breakpoint;
+            }
+        }
+
         const inst = try isa.decode(cpu.fetch_code());
+        cpu.instr_count += 1;
 
         if (cpu.trace) {
             // std.debug.print("TRACE {s} {} 0x{X:0>6}: {}\n", .{
@@ -111,7 +127,8 @@ pub fn run(cpu: *Cpu, mileage: ?u64) RunError!RunResult {
             //     fmtInstruction(inst),
             // });
 
-            std.debug.print("TRACE {s} {f} [", .{
+            std.debug.print("TRACE #{d: >6} {s} {f} [", .{
+                cpu.instr_count,
                 if (skip) "SKIP" else "    ",
                 cpu.sreg,
             });
@@ -141,6 +158,12 @@ pub fn run(cpu: *Cpu, mileage: ?u64) RunError!RunResult {
                     }
                 },
             }
+
+            // Check if the program requested exit via I/O
+            if (cpu.io.check_exit()) |exit_code| {
+                _ = exit_code; // The exit code is stored in the IO context for main() to use
+                return .program_exit;
+            }
         }
     }
 }
@@ -868,7 +891,14 @@ const instructions = struct {
     /// Program memory not exceeding 4K words (8KB) this instruction can address the entire memory from
     /// every address location. See also JMP.
     inline fn rjmp(cpu: *Cpu, bits: isa.opinfo.k12) void {
-        cpu.shift_program_counter(@as(i12, @bitCast(bits.k)));
+        const offset = @as(i12, @bitCast(bits.k));
+        // Detect infinite loop pattern (rjmp .-2, which is rjmp with k=-1)
+        // This is commonly used in __stop_program after main returns
+        if (offset == -1) {
+            cpu.instr_effect = .infinite_loop;
+            return;
+        }
+        cpu.shift_program_counter(offset);
     }
 
     /// RCALL – Relative Call to Subroutine

sim/aviron/src/lib/io.zig

@@ -154,14 +154,23 @@ pub const IO = struct {
         return mem.vtable.writeFn(mem.ctx, addr, mask, value);
     }
 
+    pub fn check_exit(mem: IO) ?u8 {
+        return mem.vtable.checkExitFn(mem.ctx);
+    }
+
     pub const VTable = struct {
         readFn: *const fn (ctx: ?*anyopaque, addr: Address) u8,
         writeFn: *const fn (ctx: ?*anyopaque, addr: Address, mask: u8, value: u8) void,
+        checkExitFn: *const fn (ctx: ?*anyopaque) ?u8,
     };
 
     pub const empty = IO{
         .ctx = null,
-        .vtable = &VTable{ .readFn = empty_read, .writeFn = empty_write },
+        .vtable = &VTable{
+            .readFn = empty_read,
+            .writeFn = empty_write,
+            .checkExitFn = empty_check_exit,
+        },
     };
 
     fn empty_read(ctx: ?*anyopaque, addr: Address) u8 {
@@ -176,4 +185,9 @@ pub const IO = struct {
         _ = addr;
         _ = ctx;
     }
+
+    fn empty_check_exit(ctx: ?*anyopaque) ?u8 {
+        _ = ctx;
+        return null;
+    }
 };

sim/aviron/src/main.zig

@@ -117,10 +117,15 @@ pub fn main() !u8 {
         }
     }
 
-    const result = try cpu.run(null);
+    const result = try cpu.run(null, cli.options.breakpoint);
 
     std.debug.print("STOP: {s}\n", .{@tagName(result)});
 
+    // Handle program exit - the defer block will still run
+    if (result == .program_exit) {
+        return io.exit_code.?;
+    }
+
     return 0;
 }
 
@@ -143,13 +148,17 @@ const Cli = struct {
     mcu: MCU = .atmega328p,
     info: bool = false,
     format: FileFormat = .elf,
+    breakpoint: ?u24 = null,
+    gas: ?u64 = null,
 
     pub const shorthands = .{
         .h = "help",
         .t = "trace",
         .m = "mcu",
         .I = "info",
         .f = "format",
+        .b = "breakpoint",
+        .g = "gas",
     };
     pub const meta = .{
         .summary = "[-h] [-t] [-m <mcu>] <file> ...",
@@ -166,6 +175,8 @@ const Cli = struct {
             .mcu = "Selects the emulated MCU.",
             .info = "Prints information about the given MCUs memory.",
             .format = "Specify file format.",
+            .breakpoint = "Break when PC reaches this address (hex or dec)",
+            .gas = "Stop after N instructions executed",
         },
     };
 };
@@ -176,6 +187,9 @@ const IO = struct {
     sp: u16,
     sreg: *aviron.Cpu.SREG,
 
+    // Exit status tracking
+    exit_code: ?u8 = null,
+
     pub fn memory(self: *IO) aviron.IO {
         return aviron.IO{
             .ctx = self,
@@ -186,6 +200,7 @@ const IO = struct {
     pub const vtable = aviron.IO.VTable{
         .readFn = read,
         .writeFn = write,
+        .checkExitFn = check_exit,
     };
 
     // This is our own "debug" device with it's own debug addresses:
@@ -262,7 +277,9 @@ const IO = struct {
         const io: *IO = @ptrCast(@alignCast(ctx.?));
         const reg: Register = @enumFromInt(addr);
         switch (reg) {
-            .exit => std.process.exit(value & mask),
+            .exit => {
+                io.exit_code = value & mask;
+            },
             .stdio => {
                 var stdout = std.fs.File.stdout().writer(&.{});
                 stdout.interface.writeByte(value & mask) catch @panic("i/o failure");
@@ -317,4 +334,12 @@ const IO = struct {
         dst.* &= ~mask;
         dst.* |= (val & mask);
     }
+
+    fn check_exit(ctx: ?*anyopaque) ?u8 {
+        const io: *IO = @ptrCast(@alignCast(ctx.?));
+        if (io.exit_code) |code| {
+            return code;
+        }
+        return null;
+    }
 };

sim/aviron/src/testconfig.zig

@@ -5,6 +5,8 @@ pub const ExitType = enum {
     enter_sleep_mode,
     reset_watchdog,
     out_of_gas,
+    infinite_loop,
+    program_exit,
     system_exit,
 };
 

sim/aviron/src/testrunner.zig

@@ -32,6 +32,8 @@ const ExitMode = union(testconfig.ExitType) {
     enter_sleep_mode,
     reset_watchdog,
     out_of_gas,
+    infinite_loop,
+    program_exit,
     system_exit: u8,
 };
 
@@ -40,7 +42,7 @@ fn validate_reg(ok: *bool, ts: *SystemState, comptime reg: aviron.Register) void
 
     const actual = ts.cpu.regs[reg.num()];
     if (expected != actual) {
-        std.debug.print("Invalid register value for register {s}: Expected {}, but got {}.\n", .{
+        std.debug.print("Invalid register value for register {s}: Expected 0x{X:0>2}, but got 0x{X:0>2}.\n", .{
             @tagName(reg),
             expected,
             actual,
@@ -217,7 +219,7 @@ pub fn main() !u8 {
         }
     }
 
-    const result = try test_system.cpu.run(null);
+    const result = try test_system.cpu.run(null, null);
     validate_syste_and_exit(switch (result) {
         inline else => |tag| @unionInit(ExitMode, @tagName(tag), {}),
     });
@@ -246,6 +248,7 @@ const IO = struct {
     pub const vtable = aviron.IO.VTable{
         .readFn = read,
         .writeFn = write,
+        .checkExitFn = check_exit,
     };
 
     // This is our own "debug" device with it's own debug addresses:
@@ -373,4 +376,9 @@ const IO = struct {
         dst.* &= ~mask;
         dst.* |= (val & mask);
     }
+
+    fn check_exit(ctx: ?*anyopaque) ?u8 {
+        _ = ctx;
+        return null; // Testrunner handles exits differently via validate_syste_and_exit
+    }
 };