aviron: Add comments to clarify push/pop semantics

Author: Grazfather

sim/aviron/build.zig

@@ -10,6 +10,9 @@ SECTIONS
     {
         KEEP(*(.vectors))
 
+        /* Ensure _start comes first */
+        KEEP(*(.text._start))
+
         *(.text*)
     } > flash
 

sim/aviron/linker.ld

@@ -1,6 +1,6 @@
 const std = @import("std");
 
-pub export fn _start() callconv(.c) noreturn {
+export fn _start() callconv(.c) noreturn {
     var a: usize = 1 + 2;
 
     for (0..10) |p| {

sim/aviron/samples/math.zig

@@ -59,6 +59,9 @@ sio: SpecialIoRegisters,
 flash: Flash,
 data: DataBus,
 io: IOBus,
+sram_base: u16 = 0,
+sram_size: u16 = 0,
+eeprom_size: u16 = 0,
 
 // State
 pc: u24 = 0,
@@ -84,6 +87,110 @@ pub const RunResult = enum {
     program_exit,
 };
 
+pub fn dump_system_state(cpu: *Cpu) void {
+    // Dump complete system state
+    std.debug.print("\n=== SYSTEM STATE DUMP ===\n", .{});
+    std.debug.print("PC: 0x{X:0>4}\n", .{cpu.pc});
+    std.debug.print("SP: 0x{X:0>4}\n", .{cpu.get_sp()});
+    std.debug.print("SREG: {f}\n", .{cpu.sreg});
+
+    // Dump X, Y, Z pointer registers
+    const x_reg = (@as(u16, cpu.regs[27]) << 8) | cpu.regs[26];
+    const y_reg = (@as(u16, cpu.regs[29]) << 8) | cpu.regs[28];
+    const z_reg = (@as(u16, cpu.regs[31]) << 8) | cpu.regs[30];
+    std.debug.print("\nPOINTER REGISTERS:\n", .{});
+    std.debug.print("X (r27:r26): 0x{X:0>4}\n", .{x_reg});
+    std.debug.print("Y (r29:r28): 0x{X:0>4}\n", .{y_reg});
+    std.debug.print("Z (r31:r30): 0x{X:0>4}\n", .{z_reg});
+
+    // Dump all registers
+    std.debug.print("\nREGISTERS:\n", .{});
+    for (cpu.regs, 0..) |reg, i| {
+        if (i % 8 == 0) std.debug.print("r{d:0>2}-r{d:0>2}: ", .{ i, @min(i + 7, 31) });
+        std.debug.print("{X:0>2} ", .{reg});
+        if ((i + 1) % 8 == 0) std.debug.print("\n", .{});
+    }
+
+    // Dump SRAM using absolute addresses based on configured base
+    const sram_end: u16 = cpu.sram_base + @as(u16, @truncate(cpu.sram_size - 1));
+    std.debug.print("\nSRAM DUMP (0x{X:0>4}-0x{X:0>4}, {d} bytes):\n", .{ cpu.sram_base, sram_end, cpu.sram_size });
+
+    const row_width = 16;
+    var prev_row: ?[row_width]u8 = null;
+    var prev_len: usize = 0;
+    var elided = false;
+
+    var i: usize = 0;
+    while (i < cpu.sram_size) : (i += @min(row_width, cpu.sram_size - i)) {
+        const row_len: usize = @min(row_width, cpu.sram_size - i);
+        var cur_row: [row_width]u8 = undefined;
+
+        var j: usize = 0;
+        while (j < row_len) : (j += 1) {
+            cur_row[j] = cpu.data.read(cpu.sram_base + @as(u16, @intCast(i + j)));
+        }
+
+        // Only elide repeated lines of all zeroes
+        const is_all_zeros = blk: {
+            for (cur_row[0..row_len]) |byte| {
+                if (byte != 0) break :blk false;
+            }
+            break :blk true;
+        };
+        const same_as_prev = if (prev_row) |prev|
+            prev_len == row_len and std.mem.eql(u8, prev[0..prev_len], cur_row[0..row_len])
+        else
+            false;
+        if (same_as_prev and is_all_zeros) {
+            elided = true;
+        } else {
+            if (elided) {
+                std.debug.print("*\n", .{});
+                elided = false;
+            }
+
+            std.debug.print("0x{X:0>4}: ", .{cpu.sram_base + i});
+            // hex bytes
+            j = 0;
+            while (j < row_len) : (j += 1) {
+                std.debug.print("{X:0>2} ", .{cur_row[j]});
+            }
+
+            // pad hex area for short rows to align ASCII column
+            if (row_len < row_width) {
+                var pad: usize = row_width - row_len;
+                while (pad > 0) : (pad -= 1) {
+                    std.debug.print("   ", .{});
+                }
+            }
+
+            // ASCII representation
+            std.debug.print(" |", .{});
+            j = 0;
+            while (j < row_len) : (j += 1) {
+                const b = cur_row[j];
+                if (b >= 32 and b <= 126) {
+                    std.debug.print("{c}", .{b});
+                } else {
+                    std.debug.print(".", .{});
+                }
+            }
+            std.debug.print("|\n", .{});
+
+            // store as previous row
+            if (prev_row == null) {
+                prev_row = [_]u8{0} ** row_width;
+            }
+            @memcpy(prev_row.?[0..row_len], cur_row[0..row_len]);
+            prev_len = row_len;
+        }
+    }
+    if (elided)
+        std.debug.print("*\n", .{});
+
+    std.debug.print("=== END DUMP ===\n", .{});
+}
+
 pub fn run(cpu: *Cpu, mileage: ?u64, breakpoint: ?u24) RunError!RunResult {
     var rest_gas = mileage;
 
@@ -172,12 +279,29 @@ fn shift_program_counter(cpu: *Cpu, by: i12) void {
 }
 
 fn fetch_code(cpu: *Cpu) u16 {
-    const value = cpu.flash.read(cpu.pc);
+    // Program memory is word-addressed; PC is in words.
+    const value: u16 = cpu.flash.read(@intCast(cpu.pc));
     cpu.pc +%= 1; // increment with wraparound
     cpu.pc &= @intFromEnum(cpu.code_model); // then wrap to lower bit size
     return value;
 }
 
+inline fn data_read(cpu: *Cpu, addr: u24) u8 {
+    return cpu.data.read8(addr) catch |e| switch (e) {
+        error.Unmapped => @panic("Read from unmapped memory address"),
+        error.OutOfRange => @panic("Read out of range"),
+        error.ReadOnly => @panic("ReadOnly error on read"),
+    };
+}
+
+inline fn data_write(cpu: *Cpu, addr: u24, value: u8) void {
+    cpu.data.write8(addr, value) catch |e| switch (e) {
+        error.Unmapped => @panic("Write to unmapped memory address"),
+        error.OutOfRange => @panic("Write out of range"),
+        error.ReadOnly => @panic("Write to read-only memory"),
+    };
+}
+
 fn push(cpu: *Cpu, val: u8) void {
     // AVR PUSH: Write to [SP] first, then decrement SP
     // SP points to the first unused location
@@ -213,6 +337,7 @@ fn push_code_loc(cpu: *Cpu, val: u24) void {
 fn pop_code_loc(cpu: *Cpu) u24 {
     const mask = @intFromEnum(cpu.code_model);
 
+    // With increment-then-read POP, we pop most significant byte first.
     var pc: u24 = 0;
     if ((mask & 0xFF0000) != 0) {
         pc |= (@as(u24, cpu.pop()) << 16);
@@ -242,11 +367,11 @@ fn read_wide_reg(cpu: *Cpu, comptime reg: WideReg, comptime mode: IndexRegReadMo
         switch (mode) {
             .raw => 0,
             .ramp => switch (reg) {
-                .x => if (cpu.sio.ramp_x) |ramp| cpu.io.read(ramp) else 0,
-                .y => if (cpu.sio.ramp_y) |ramp| cpu.io.read(ramp) else 0,
-                .z => if (cpu.sio.ramp_z) |ramp| cpu.io.read(ramp) else 0,
+                .x => if (cpu.sio.ramp_x) |ramp| (cpu.io.read(@intCast(ramp))) else 0,
+                .y => if (cpu.sio.ramp_y) |ramp| (cpu.io.read(@intCast(ramp))) else 0,
+                .z => if (cpu.sio.ramp_z) |ramp| (cpu.io.read(@intCast(ramp))) else 0,
             },
-            .eind => if (cpu.sio.e_ind) |e_ind| cpu.io.read(e_ind) else 0,
+            .eind => if (cpu.sio.e_ind) |e_ind| (cpu.io.read(@intCast(e_ind))) else 0,
         },
         cpu.regs[reg.base() + 1],
         cpu.regs[reg.base() + 0],
@@ -778,7 +903,7 @@ const instructions = struct {
     /// Loads data from the I/O Space (Ports, Timers, Configuration Registers, etc.) into register Rd in the Register File.
     inline fn in(cpu: *Cpu, info: isa.opinfo.a6d5) void {
         // Rd ← I/O(A)
-        cpu.regs[info.d.num()] = cpu.io.read(info.a);
+        cpu.regs[info.d.num()] = cpu.io.read(@intCast(info.a));
     }
 
     /// CBI – Clear Bit in I/O Register
@@ -828,7 +953,7 @@ const instructions = struct {
     /// instruction operates on the lower 32 I/O Registers – addresses 0-31.
     inline fn sbic(cpu: *Cpu, info: isa.opinfo.a5b3) void {
         // If I/O(A,b) = 0 then PC ← PC + 2 (or 3) else PC ← PC + 1
-        const val = cpu.io.read(info.a);
+        const val = cpu.io.read(@intCast(info.a));
         if ((val & info.b.mask()) == 0) {
             cpu.instr_effect = .skip_next;
         }
@@ -839,7 +964,7 @@ const instructions = struct {
     /// instruction operates on the lower 32 I/O Registers – addresses 0-31.
     inline fn sbis(cpu: *Cpu, info: isa.opinfo.a5b3) void {
         // If I/O(A,b) = 1 then PC ← PC + 2 (or 3) else PC ← PC + 1
-        const val = cpu.io.read(info.a);
+        const val = cpu.io.read(@intCast(info.a));
         if ((val & info.b.mask()) != 0) {
             cpu.instr_effect = .skip_next;
         }