IndentWidth: 4

ColumnLimit: 80

UseTab: Never

AllowShortBlocksOnASingleLine: Always  # or use 'Empty' for only empty blocks

AllowShortFunctionsOnASingleLine: Empty

AlignConsecutiveMacros: AcrossComments

AlignAfterOpenBracket: BlockIndent

AlignConsecutiveBitFields: AcrossEmptyLinesAndComments

AlignConsecutiveDeclarations:

  Enabled: true

AlignConsecutiveAssignments:

  Enabled: true

  AlignCompound: true

  PadOperators: true

BinPackParameters: false

BinPackArguments: false

BreakAfterReturnType: Automatic

PenaltyReturnTypeOnItsOwnLine: 999

Cpp11BracedListStyle: false

/bin

alexis ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICpDRmIwBm4ajzW+METm9tBdK4CG2/v0qmO4bPfi+s+c alexis@radiant.computer

Copyright (c) 2025-2026 Radiant Computer (https://radiant.computer)

Permission is hereby granted, free of charge, to any person obtaining a copy of

this software and associated documentation files (the "Software"), to deal in

the Software without restriction, including without limitation the rights to

use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies

of the Software, and to permit persons to whom the Software is furnished to do

so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.

# Builds the RISC-V emulator.

PREFIX  ?= $(HOME)/bin

CC      := clang

CFLAGS  := -fvisibility=hidden -std=c99 -O3 -g \

           -Wall -Wextra -Wpedantic \

           -Wformat=2 -Wformat-security \

           -Wnull-dereference \

           -Wno-format-nonliteral \

           -Wcast-align \

           -Wunused -Wuninitialized \

           -Wmissing-field-initializers \

           -fno-common -fstack-protector-all \

           -mcmodel=medium \

           -march=native -flto

LDFLAGS := -fuse-ld=lld -Wl,-z,stack-size=33554432

EMULATOR_SRCS  := emulator.c jit.c riscv/debug.c io.c riscv.c

default: bin/emulator

bin/emulator: $(EMULATOR_SRCS) jit.h color.h types.h io.h riscv.h riscv/debug.h

	@echo "cc    emulator => $@"

	@mkdir -p bin

	@$(CC) $(CFLAGS) $(LDFLAGS) $(EMULATOR_SRCS) -o $@

install: bin/emulator

	@echo "copy  bin/emulator => $(PREFIX)/emulator"

	@mkdir -p $(PREFIX)

	@cp bin/emulator $(PREFIX)/emulator

fmt:

	git ls-files "*.c" "*.h" | xargs clang-format -i

clean:

	@rm -f bin/emulator

.PHONY: default clean install

.SUFFIXES:

.DELETE_ON_ERROR:

.SILENT:

RADIANT RISC-V EMULATOR

A RISC-V RV64I emulator with an x86-64 JIT compiler, interactive TUI

debugger, and headless execution mode. Part of the Radiant project.

Supports the RV64I base integer instruction set, M (multiply/divide)

extension, and F (single-precision floating-point) extension.

BUILDING

    $ make

  Requires `clang` and `lld`. The binary is written to `bin/emulator`.

INSTALLATION

    $ make install

  Installed as `~/bin/emulator` by default. Can be overridden via the `PREFIX`

  variable.

USAGE

  Interactive (TUI):

    $ bin/emulator <program.bin>

  Headless:

    $ bin/emulator -run <program.bin> [<option>..]

  The emulator loads a flat binary along with optional data sections:

    <program.bin>           Program text (machine instructions)

    <program.bin>.ro.data   Read-only data section

    <program.bin>.rw.data   Read-write data section

    <program.bin>.debug     Debug info (optional, for source locations)

OPTIONS

    -run                    Run headless (no TUI).

    -debug                  Load debug info for source-level diagnostics.

    -no-jit                 Disable the JIT compiler; interpret only.

    -memory-size=KB         Physical memory size in KB (default 128 MB).

    -data-size=KB           Data memory size in KB.

    -stack-size=KB          Stack size in KB (default 256 KB).

    -no-guard-stack         Disable stack guard zones (enabled by default, 16 bytes).

    -no-validate            Disable memory bounds checking.

    -trace                  Enable instruction tracing.

    -trace-headless         Enable instruction tracing in headless mode.

    -trace-instructions     Print each instruction during headless tracing.

    -trace-depth=N          Number of trace entries to display on fault.

    -max-steps=N            Maximum steps before timeout in headless mode.

    -count-instructions     Print instruction count on exit.

    -watch=ADDR             Set a memory watchpoint at ADDR.

    -watch-size=BYTES       Size of watched region (default 4).

    -watch-arm-pc=ADDR      Only trigger watchpoint after reaching ADDR.

    -watch-zero-only        Only trigger on zero-value stores.

    -watch-skip=N           Skip the first N watchpoint hits.

    -watch-backtrace        Print backtrace on watchpoint hit.

    -watch-bt-depth=N       Backtrace depth (default 8).

MEMORY LAYOUT

    0x00010000                 Read-only data (.ro.data)

    Program base               Program text (instructions)

    0x00FFFFF0                 Read-write data (.rw.data)

    Memory top - stack size    Stack

    Memory top                 Top of memory

ARCHITECTURE

  The emulator operates in two execution modes:

    Interpreter    Steps through instructions one at a time. Used for the

                   TUI debugger, ecalls, ebreak, and as a fallback.

    JIT            Translates basic blocks of RV64I instructions to native

                   x86-64 machine code. Blocks are compiled on first

                   encounter and cached (16 MB code cache, up to 256K

                   blocks). Falls back to the interpreter for system

                   calls and faults.

  The TUI debugger supports single-stepping, reverse execution (via

  snapshots), register and stack inspection, and memory watchpoints.

LICENSE

  Licensed under the MIT License,

  Copyright (c) 2025-2026 Radiant Computer (https://radiant.computer)

/*

 * ANSI color definitions.

 */

#define COLOR_NORMAL     ""

#define COLOR_RESET      "\033[m"

#define COLOR_BOLD       "\033[1m"

#define COLOR_ITALIC     "\033[3m"

#define COLOR_INVERSE    "\033[7m"

#define COLOR_RED        "\033[31m"

#define COLOR_GREEN      "\033[32m"

#define COLOR_YELLOW     "\033[33m"

#define COLOR_BLUE       "\033[34m"

#define COLOR_MAGENTA    "\033[35m"

#define COLOR_CYAN       "\033[36m"

#define COLOR_GREY       "\033[37m"

#define COLOR_BOLD_RED   "\033[1;31m"

#define COLOR_BOLD_GREEN "\033[1;32m"

#define COLOR_BOLD_BLUE  "\033[1;34m"

#include <errno.h>

#include <fcntl.h>

#include <limits.h>

#include <stdint.h>

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#include <sys/ioctl.h>

#include <termios.h>

#include <unistd.h>

#include "color.h"

#include "io.h"

#include "jit.h"

#include "riscv.h"

#include "riscv/debug.h"

#include "types.h"

#ifndef PATH_MAX

#define PATH_MAX 4096

#endif

/* Define BINARY for `bail` and `assert` functions. */

#undef BINARY

#define BINARY "emulator"

#undef assert

#define assert(condition)                                                      \

    ((condition) ? (void)0 : _assert_failed(#condition, __FILE__, __LINE__))

static inline __attribute__((noreturn)) void _assert_failed(

    const char *condition, const char *file, int line

) {

    fprintf(stderr, "%s:%d: assertion `%s` failed\n", file, line, condition);

    abort();

}

/* Maximum physical memory size (384MB). The runtime can choose any size up to

 * this value with `-memory-size=...`. */

#define MEMORY_SIZE              (384 * 1024 * 1024)

/* Default physical memory size (128MB). */

#define DEFAULT_MEMORY_SIZE      (128 * 1024 * 1024)

/* Program memory size (4MB), reserved at start of memory for program code. */

#define PROGRAM_SIZE             (4 * 1024 * 1024)

/* Writable data region base. */

#define DATA_RW_OFFSET           0xFFFFF0

/* Data memory starts at writable data region. */

#define DATA_MEMORY_START        DATA_RW_OFFSET

/* Default data memory size. */

#define DEFAULT_DATA_MEMORY_SIZE (DEFAULT_MEMORY_SIZE - DATA_MEMORY_START)

/* Default stack size (256KB), allocated at the end of memory. */

#define DEFAULT_STACK_SIZE       (256 * 1024)

/* Maximum instructions to show in the TUI. */

#define MAX_INSTR_DISPLAY        40

/* Stack words to display in the TUI. */

#define STACK_DISPLAY_WORDS      32

/* Maximum number of CPU state snapshots to store for undo. */

#define MAX_SNAPSHOTS            64

/* Maximum open files in guest runtime. */

#define MAX_OPEN_FILES           32

/* Number of history entries to print when reporting faults. */

#define FAULT_TRACE_DEPTH        8

/* Instruction trace depth for headless tracing. */

#define TRACE_HISTORY            64

/* Maximum number of steps executed in headless mode before timing out. */

#define HEADLESS_MAX_STEPS       ((u64)1000000000000)

/* Height of header and footer in rows. */

#define HEADER_HEIGHT            2

#define FOOTER_HEIGHT            3

/* Read-only data offset. */

#define DATA_RO_OFFSET           0x10000

/* TTY escape codes. */

#define TTY_CLEAR                "\033[2J\033[H"

#define TTY_GOTO_RC              "\033[%d;%dH"

/* Exit code returned on EBREAK. */

#define EBREAK_EXIT_CODE         133

/* Registers displayed in the TUI, in order. */

static const reg_t registers_displayed[] = {

    SP, FP, RA, A0, A1, A2, A3, A4, A5, A6, A7, T0, T1, T2, T3, T4, T5, T6

};

/* Display mode for immediates and values. */

enum display { DISPLAY_HEX, DISPLAY_DEC };

/* Debug info entry mapping PC to source location. */

struct debug_entry {

    u32  pc;

    u32  offset;

    char file[PATH_MAX];

};

/* Debug info table. */

struct debug_info {

    struct debug_entry *entries;

    size_t              count;

    size_t              capacity;

};

/* Global debug info. */

static struct debug_info g_debug = { 0 };

/* CPU state. */

struct cpu {

    u64      regs[REGISTERS];

    u32      pc;          /* Program counter. */

    u32      programsize; /* Size of loaded program. */

    instr_t *program;     /* Program instructions. */

    bool     running;     /* Execution status. */

    bool     faulted;     /* There was a fault in execution. */

    bool     ebreak;      /* Program terminated via EBREAK. */

    reg_t    modified;    /* Index of the last modified register. */

};

/* Snapshot of CPU and memory state for reversing execution. */

struct snapshot {

    struct cpu cpu;                 /* Copy of CPU state. */

    u8         memory[MEMORY_SIZE]; /* Copy of memory. */

};

/* Circular buffer for snapshots. */

struct snapshot_buffer {

    struct snapshot snapshots[MAX_SNAPSHOTS];

    int             head; /* Index of most recent snapshot. */

    int             count;

};

/* CPU memory. */

static u8 memory[MEMORY_SIZE];

/* Loaded section sizes, used for bounds checking and diagnostics. */

static u32 program_base  = 0;

static u32 program_bytes = 0;

static u32 rodata_bytes  = 0;

static u32 data_bytes    = 0;

/* Snapshot buffer. */

static struct snapshot_buffer snapshots;

/* File descriptor table for guest file operations. */

static int guest_fds[MAX_OPEN_FILES];

/* Initialize the guest file descriptor table. */

static void guest_fd_table_init(void) {

    for (int i = 0; i < MAX_OPEN_FILES; i++) {

        guest_fds[i] = -1;

    }

}

/* Add a host file descriptor to the guest table. */

static int guest_fd_table_add(int host_fd) {

    /* Start at 3 to skip stdin/stdout/stderr. */

    for (int i = 3; i < MAX_OPEN_FILES; i++) {

        if (guest_fds[i] == -1) {

            guest_fds[i] = host_fd;

            return i;

        }

    }

    return -1;

}

/* Get the host fd for a guest file descriptor. */

static int guest_fd_table_get(int guest_fd) {

    if (guest_fd < 0 || guest_fd >= MAX_OPEN_FILES) {

        return -1;

    }

    /* Standard streams map directly. */

    if (guest_fd < 3) {

        return guest_fd;

    }

    return guest_fds[guest_fd];

}

/* Remove a file descriptor from the guest table. */

static void guest_fd_table_remove(int guest_fd) {

    if (guest_fd >= 3 && guest_fd < MAX_OPEN_FILES) {

        guest_fds[guest_fd] = -1;

    }

}

/* Single entry in the instruction trace ring buffer. */

struct trace_entry {

    u32     pc;

    instr_t instr;

    u64     regs[REGISTERS];

};

/* Circular buffer of recent instruction traces. */

struct trace_ring {

    struct trace_entry entries[TRACE_HISTORY];

    int                head;

    int                count;

};

/* Headless-mode instruction trace buffer. */

static struct trace_ring headless_trace = { .head = -1, .count = 0 };

/* Terminal dimensions in rows and columns. */

struct termsize {

    int rows;

    int cols;

};

/* Forward declarations. */

static void ui_render_instructions(

    struct cpu *, int col, int width, int height

);

static void ui_render_registers(

    struct cpu *, enum display, int col, int height

);

static void ui_render_stack(struct cpu *, enum display, int col, int height);

static void ui_render(struct cpu *, enum display);

static void cpu_execute(struct cpu *, enum display, bool headless);

static void emit_fault_diagnostics(struct cpu *, u32 pc);

/* Emulator runtime options, populated from CLI flags. */

struct emulator_options {

    bool stack_guard;

    u32  stack_size;

    bool debug_enabled;

    bool trace_headless;

    bool trace_enabled;

    bool trace_print_instructions;

    u32  trace_depth;

    u64  headless_max_steps;

    u32  memory_size;

    u32  data_memory_size;

    bool watch_enabled;

    u32  watch_addr;

    u32  watch_size;

    u32  watch_arm_pc;

    bool watch_zero_only;

    u32  watch_skip;

    bool watch_backtrace;

    u32  watch_backtrace_depth;

    bool validate_memory;

    bool count_instructions;

    bool jit_disabled;

};

/* Global emulator options. */

static struct emulator_options g_opts = {

    .stack_guard              = true,

    .stack_size               = DEFAULT_STACK_SIZE,

    .debug_enabled            = false,

    .trace_headless           = false,

    .trace_enabled            = false,

    .trace_print_instructions = false,

    .trace_depth              = 32,

    .headless_max_steps       = HEADLESS_MAX_STEPS,

    .memory_size              = DEFAULT_MEMORY_SIZE,

    .data_memory_size         = DEFAULT_DATA_MEMORY_SIZE,

    .watch_enabled            = false,

    .watch_addr               = 0,

    .watch_size               = 0,

    .watch_arm_pc             = 0,

    .watch_zero_only          = false,

    .watch_skip               = 0,

    .watch_backtrace          = false,

    .watch_backtrace_depth    = 8,

    .validate_memory          = true,

    .count_instructions       = false,

    .jit_disabled             = false,

};

static void dump_watch_context(struct cpu *, u32 addr, u32 size, u32 value);

/* Return true if the given address range overlaps the watched region. */

static inline bool watch_hit(u32 addr, u32 size) {

    if (!g_opts.watch_enabled)

        return false;

    u32 start = g_opts.watch_addr;

    u32 end   = start + (g_opts.watch_size ? g_opts.watch_size : 1);

    return addr < end && (addr + size) > start;

}

/* Check a store against the memory watchpoint and halt on a hit. */

static inline void watch_store(struct cpu *cpu, u32 addr, u32 size, u32 value) {

    if (!watch_hit(addr, size))

        return;

    if (g_opts.watch_arm_pc && cpu && cpu->pc < g_opts.watch_arm_pc)

        return;

    if (g_opts.watch_zero_only && value != 0)

        return;

    if (g_opts.watch_skip > 0) {

        g_opts.watch_skip--;

        return;

    }

    fprintf(

        stderr,

        "[WATCH] pc=%08x addr=%08x size=%u value=%08x\n",

        cpu ? cpu->pc : 0,

        addr,

        size,

        value

    );

    dump_watch_context(cpu, addr, size, value);

    if (cpu) {

        cpu->running = false;

        cpu->faulted = true;

        cpu->ebreak  = true;

    }

}

/* Fixed stack guard zone size. */

#define STACK_GUARD_BYTES 16

/* Clamp and align stack size to a valid range. */

static inline u32 sanitize_stack_bytes(u32 bytes) {

    if (bytes < WORD_SIZE)

        bytes = WORD_SIZE;

    bytes = (u32)align((i32)bytes, WORD_SIZE);

    /* Keep at least one word for guard computations. */

    if (bytes >= g_opts.memory_size)

        bytes = g_opts.memory_size - WORD_SIZE;

    return bytes;

}

/* Return the active stack guard size, or 0 if guards are disabled. */

static inline u32 stack_guard_bytes(void) {

    if (!g_opts.stack_guard)

        return 0;

    return STACK_GUARD_BYTES;

}

/* Return the configured stack size. */

static inline u32 stack_size(void) {

    return g_opts.stack_size;

}

/* Return the highest addressable word-aligned memory address. */

static inline u32 memory_top(void) {

    return g_opts.memory_size - WORD_SIZE;

}

/* Return the lowest address in the stack region. */

static inline u32 stack_bottom(void) {

    return memory_top() - stack_size() + WORD_SIZE;

}

/* Return the highest usable stack address (inside the guard zone). */

static inline u32 stack_usable_top(void) {

    u32 guard = stack_guard_bytes();

    u32 size  = stack_size();

    if (guard >= size)

        guard = size - WORD_SIZE;

    return memory_top() - guard;

}

/* Return the lowest usable stack address (inside the guard zone). */

static inline u32 stack_usable_bottom(void) {

    u32 guard = stack_guard_bytes();

    u32 size  = stack_size();

    if (guard >= size)

        guard = size - WORD_SIZE;

    return stack_bottom() + guard;

}

/* Return true if addr falls within the stack region. */

static inline bool stack_contains(u32 addr) {

    return addr >= stack_bottom() && addr <= memory_top();

}

/* Return true if the range [start, end] overlaps a stack guard zone. */

static inline bool stack_guard_overlaps(u32 guard, u32 start, u32 end) {

    if (guard == 0)

        return false;

    u32 low_guard_end    = stack_bottom() + guard - 1;

    u32 high_guard_start = memory_top() - guard + 1;

    return (start <= low_guard_end && end >= stack_bottom()) ||

           (end >= high_guard_start && start <= memory_top());

}

/* Return true if addr falls inside a stack guard zone. */

static inline bool stack_guard_contains(u32 guard, u32 addr) {

    return stack_guard_overlaps(guard, addr, addr);

}

/* Load a 16-bit value from memory in little-endian byte order. */

static inline u16 memory_load_u16(u32 addr) {

    return (u16)(memory[addr] | (memory[addr + 1] << 8));

}

/* Load a 32-bit value from memory in little-endian byte order. */

static inline u32 memory_load_u32(u32 addr) {

    return memory[addr] | (memory[addr + 1] << 8) | (memory[addr + 2] << 16) |

           (memory[addr + 3] << 24);

}

/* Load a 64-bit value from memory in little-endian byte order. */

static inline u64 memory_load_u64(u32 addr) {

    return (u64)memory[addr] | ((u64)memory[addr + 1] << 8) |

           ((u64)memory[addr + 2] << 16) | ((u64)memory[addr + 3] << 24) |

           ((u64)memory[addr + 4] << 32) | ((u64)memory[addr + 5] << 40) |

           ((u64)memory[addr + 6] << 48) | ((u64)memory[addr + 7] << 56);

}

/* Store a byte to memory. */

static inline void memory_store_u8(u32 addr, u8 value) {

    memory[addr] = value;

}

/* Store a 16-bit value to memory in little-endian byte order. */

static inline void memory_store_u16(u32 addr, u16 value) {

    memory[addr]     = (u8)(value & 0xFF);

    memory[addr + 1] = (u8)((value >> 8) & 0xFF);

}

/* Store a 32-bit value to memory in little-endian byte order. */

static inline void memory_store_u32(u32 addr, u32 value) {

    assert(addr + 3 < g_opts.memory_size);

    memory[addr]     = (u8)(value & 0xFF);

    memory[addr + 1] = (u8)((value >> 8) & 0xFF);

    memory[addr + 2] = (u8)((value >> 16) & 0xFF);

    memory[addr + 3] = (u8)((value >> 24) & 0xFF);

}

/* Store a 64-bit value to memory in little-endian byte order. */

static inline void memory_store_u64(u32 addr, u64 value) {

    assert(addr + 7 < g_opts.memory_size);

    memory_store_u32(addr, (u32)(value & 0xFFFFFFFF));

    memory_store_u32(addr + 4, (u32)(value >> 32));

}

/* Load a 32-bit word from memory, returning false if out of bounds. */

static inline bool load_word_safe(u32 addr, u32 *out) {

    if (addr > g_opts.memory_size - WORD_SIZE)

        return false;

    *out = memory_load_u32(addr);

    return true;

}

/* Dump register state and backtrace when a watchpoint fires. */

static void dump_watch_context(struct cpu *cpu, u32 addr, u32 size, u32 value) {

    if (!g_opts.watch_backtrace || !cpu)

        return;

    (void)addr;

    (void)size;

    (void)value;

    fprintf(

        stderr,

        "         regs: SP=%08x FP=%08x RA=%08x A0=%08x A1=%08x A2=%08x "

        "A3=%08x\n",

        (u32)cpu->regs[SP],

        (u32)cpu->regs[FP],

        (u32)cpu->regs[RA],

        (u32)cpu->regs[A0],

        (u32)cpu->regs[A1],

        (u32)cpu->regs[A2],

        (u32)cpu->regs[A3]

    );

    u64 fp64 = cpu->regs[FP];

    u32 fp   = (fp64 <= (u64)UINT32_MAX) ? (u32)fp64 : 0;

    u32 pc   = cpu->pc;

    fprintf(

        stderr, "         backtrace (depth %u):\n", g_opts.watch_backtrace_depth

    );

    for (u32 depth = 0; depth < g_opts.watch_backtrace_depth; depth++) {

        bool has_frame = stack_contains(fp) && fp >= (2 * WORD_SIZE);

        u32  saved_ra  = 0;

        u32  prev_fp   = 0;

        if (has_frame) {

            has_frame = load_word_safe(fp - WORD_SIZE, &saved_ra) &&

                        load_word_safe(fp - 2 * WORD_SIZE, &prev_fp) &&

                        stack_contains(prev_fp);

        }

        fprintf(

            stderr,

            "           #%u pc=%08x fp=%08x ra=%08x%s\n",

            depth,

            pc,

            fp,

            has_frame ? saved_ra : 0,

            has_frame ? "" : " (?)"

        );

        if (!has_frame || prev_fp == fp || prev_fp == 0)

            break;

        pc = saved_ra;

        fp = prev_fp;

    }

}

/* Print usage information and return 1. */

static int usage(const char *prog) {

    fprintf(

        stderr,

        "usage: %s [-run] [-no-guard-stack]"

        " [-stack-size=KB] [-no-validate] [-debug]"

        " [-trace|-trace-headless] [-trace-depth=n] [-trace-instructions]"

        " [-max-steps=n] [-memory-size=KB] [-data-size=KB]"

        " [-watch=addr] [-watch-size=bytes] [-watch-arm-pc=addr]"

        " [-watch-zero-only] [-watch-skip=n]"

        " [-watch-backtrace] [-watch-bt-depth=n]"

        " [-count-instructions] [-no-jit]"

        " <file.bin> [program args...]\n",

        prog

    );

    return 1;

}

/* Configuration parsed from CLI flags prior to launching the emulator. */

struct cli_config {

    bool        headless;

    const char *program_path;

    int         arg_index;

};

/* Parse a string as an unsigned 32-bit integer.  Returns false on error. */

static bool parse_u32(const char *str, const char *label, int base, u32 *out) {

    char *end         = NULL;

    errno             = 0;

    unsigned long val = strtoul(str, &end, base);

    if (errno != 0 || end == str || *end != '\0') {

        fprintf(stderr, "invalid %s '%s'; expected integer\n", label, str);

        return false;

    }

    if (val > UINT32_MAX)

        val = UINT32_MAX;

    *out = (u32)val;

    return true;

}

/* Parse a string as an unsigned 64-bit integer.  Returns false on error. */

static bool parse_u64(const char *str, const char *label, u64 *out) {

    char *end              = NULL;

    errno                  = 0;

    unsigned long long val = strtoull(str, &end, 10);

    if (errno != 0 || end == str || *end != '\0') {

        fprintf(stderr, "invalid %s '%s'; expected integer\n", label, str);

        return false;

    }

    *out = (u64)val;

    return true;

}

/* Parse and validate the physical memory size passed to -memory-size=. */

static bool parse_memory_size_value(const char *value) {

    u64 parsed;

    if (!parse_u64(value, "memory size", &parsed))

        return false;

    u64 bytes = parsed * 1024;

    if (bytes <= (u64)(DATA_MEMORY_START + WORD_SIZE)) {

        fprintf(

            stderr,

            "memory size too small; minimum is %u KB\n",

            (DATA_MEMORY_START + WORD_SIZE + 1024) / 1024

        );

        return false;

    }

    if (bytes > (u64)MEMORY_SIZE) {

        fprintf(

            stderr,

            "memory size too large; maximum is %u KB (recompile emulator "

            "to increase)\n",

            MEMORY_SIZE / 1024

        );

        return false;

    }

    g_opts.memory_size = (u32)bytes;

    return true;

}

/* Parse and validate the depth passed to -trace-depth=. */

static bool parse_trace_depth_value(const char *value) {

    u32 parsed;

    if (!parse_u32(value, "trace depth", 10, &parsed))

        return false;

    if (parsed == 0) {

        fprintf(stderr, "trace depth must be greater than zero\n");

        return false;

    }

    if (parsed > TRACE_HISTORY)

        parsed = TRACE_HISTORY;

    g_opts.trace_depth = parsed;

    return true;

}

/* Parse and validate the step limit passed to -max-steps=. */

static bool parse_max_steps_value(const char *value) {

    u64 parsed;

    if (!parse_u64(value, "max steps", &parsed))

        return false;

    if (parsed == 0) {

        fprintf(stderr, "max steps must be greater than zero\n");

        return false;

    }

    g_opts.headless_max_steps = parsed;

    return true;

}

/* Parse and validate the stack size passed to -stack-size=. */

static bool parse_stack_size_value(const char *value) {

    u64 parsed;

    if (!parse_u64(value, "stack size", &parsed))

        return false;

    if (parsed == 0) {

        fprintf(stderr, "stack size must be greater than zero\n");

        return false;

    }

    u64 bytes = parsed * 1024;

    if (bytes >= MEMORY_SIZE) {

        fprintf(

            stderr,

            "stack size too large; maximum is %u KB\n",

            MEMORY_SIZE / 1024

        );

        return false;

    }

    g_opts.stack_size = sanitize_stack_bytes((u32)bytes);

    return true;

}

/* Parse and validate the data size passed to -data-size=. */

static bool parse_data_size_value(const char *value) {

    u64 parsed;

    if (!parse_u64(value, "data size", &parsed))

        return false;

    if (parsed == 0) {

        fprintf(stderr, "data size must be greater than zero\n");

        return false;

    }

    u64 bytes = parsed * 1024;

    if (bytes > (u64)MEMORY_SIZE) {

        fprintf(

            stderr,

            "data size too large; maximum is %u KB\n",

            MEMORY_SIZE / 1024

        );

        return false;

    }

    g_opts.data_memory_size = (u32)bytes;

    return true;

}

/* Validate that the stack fits within available memory. */

static bool validate_memory_layout(void) {

    if (g_opts.stack_size >= g_opts.memory_size) {

        fprintf(

            stderr,

            "stack size (%u) must be smaller than memory size (%u)\n",

            g_opts.stack_size,

            g_opts.memory_size

        );

        return false;

    }

    return true;

}

/* Parse emulator CLI arguments, returning the selected mode and file path. */

static bool parse_cli_args(int argc, char *argv[], struct cli_config *cfg) {

    bool headless = false;

    int  argi     = 1;

    while (argi < argc) {

        const char *arg = argv[argi];

        if (strcmp(arg, "--") == 0) {

            argi++;

            break;

        }

        if (arg[0] != '-')

            break;

        if (strcmp(arg, "-run") == 0) {

            headless = true;

            argi++;

            continue;

        }

        if (strncmp(arg, "-stack-size=", 12) == 0) {

            if (!parse_stack_size_value(arg + 12))

                return false;

            argi++;

            continue;

        }

        if (strcmp(arg, "-no-guard-stack") == 0) {

            g_opts.stack_guard = false;

            argi++;

            continue;

        }

        if (strcmp(arg, "-no-validate") == 0) {

            g_opts.validate_memory = false;

            argi++;

            continue;

        }

        if (strcmp(arg, "-debug") == 0) {

            g_opts.debug_enabled = true;

            argi++;

            continue;

        }

        if (strcmp(arg, "-trace") == 0 || strcmp(arg, "-trace-headless") == 0) {

            g_opts.trace_enabled = true;

            argi++;

            continue;

        }

        if (strcmp(arg, "-trace-instructions") == 0) {

            g_opts.trace_print_instructions = true;

            argi++;

            continue;

        }

        if (strncmp(arg, "-trace-depth=", 13) == 0) {

            if (!parse_trace_depth_value(arg + 13))

                return false;

            argi++;

            continue;

        }

        if (strncmp(arg, "-max-steps=", 11) == 0) {

            if (!parse_max_steps_value(arg + 11))

                return false;

            argi++;

            continue;

        }

        if (strncmp(arg, "-memory-size=", 13) == 0) {

            if (!parse_memory_size_value(arg + 13))

                return false;

            argi++;

            continue;

        }

        if (strncmp(arg, "-data-size=", 11) == 0) {

            if (!parse_data_size_value(arg + 11))

                return false;

            argi++;

            continue;

        }

        if (strncmp(arg, "-watch=", 7) == 0) {

            if (!parse_u32(arg + 7, "watch address", 0, &g_opts.watch_addr))

                return false;

            g_opts.watch_enabled = true;

            argi++;

            continue;

        }

        if (strncmp(arg, "-watch-size=", 12) == 0) {

            if (!parse_u32(arg + 12, "watch size", 0, &g_opts.watch_size))

                return false;

            if (g_opts.watch_size == 0) {

                fprintf(stderr, "watch size must be greater than zero\n");

                return false;

            }

            argi++;

            continue;

        }

        if (strcmp(arg, "-watch-zero-only") == 0) {

            g_opts.watch_zero_only = true;

            argi++;

            continue;

        }

        if (strncmp(arg, "-watch-skip=", 12) == 0) {

            if (!parse_u32(arg + 12, "watch skip", 0, &g_opts.watch_skip))

                return false;

            argi++;

            continue;

        }

        if (strcmp(arg, "-watch-disable") == 0) {

            g_opts.watch_enabled = false;

            argi++;

            continue;

        }

        if (strncmp(arg, "-watch-arm-pc=", 14) == 0) {

            if (!parse_u32(arg + 14, "watch arm pc", 0, &g_opts.watch_arm_pc))

                return false;

            argi++;

            continue;

        }

        if (strcmp(arg, "-watch-backtrace") == 0) {

            g_opts.watch_backtrace = true;

            argi++;

            continue;

        }

        if (strncmp(arg, "-watch-bt-depth=", 16) == 0) {

            u32 depth;

            if (!parse_u32(arg + 16, "watch backtrace depth", 0, &depth))

                return false;

            if (depth == 0) {

                fprintf(

                    stderr, "watch backtrace depth must be greater than zero\n"

                );

                return false;

            }

            g_opts.watch_backtrace       = true;

            g_opts.watch_backtrace_depth = depth;

            argi++;

            continue;

        }

        if (strcmp(arg, "-count-instructions") == 0) {

            g_opts.count_instructions = true;

            argi++;

            continue;

        }

        if (strcmp(arg, "-no-jit") == 0) {

            g_opts.jit_disabled = true;

            argi++;

            continue;

        }

        usage(argv[0]);

        return false;

    }

    if (argi >= argc) {

        usage(argv[0]);

        return false;

    }

    cfg->program_path = argv[argi++];

    cfg->arg_index    = argi;

    cfg->headless     = headless;

    if (g_opts.watch_enabled && g_opts.watch_size == 0)

        g_opts.watch_size = 4;

    if (!validate_memory_layout())

        return false;

    g_opts.stack_size = sanitize_stack_bytes(g_opts.stack_size);

    return true;

}

/* Validate a load or store against memory bounds and stack guards. */

static bool validate_memory_access(

    struct cpu *cpu,

    u64         addr,

    u32         size,

    reg_t       base_reg,

    const char *op,

    bool        is_store

) {

    /* Skip validation for performance if disabled. */

    if (!g_opts.validate_memory)

        return true;

    if (size == 0)

        size = 1;

    const char *kind = is_store ? "store" : "load";

    u64 span_end = addr + (u64)size;

    if (addr > (u64)g_opts.memory_size || span_end > (u64)g_opts.memory_size) {

        printf(

            "Memory %s out of bounds at PC=%08x: addr=%016llx size=%u (%s)\n",

            kind,

            cpu->pc,

            (unsigned long long)addr,

            size,

            op

        );

        cpu->running = false;

        emit_fault_diagnostics(cpu, cpu->pc);

        return false;

    }

    u32 addr32 = (u32)addr;

    u32 end    = (u32)(span_end - 1);

    if (addr32 < DATA_MEMORY_START) {

        if (is_store) {

            printf(

                "Read-only memory store at PC=%08x: addr=%08x size=%u (%s)\n",

                cpu->pc,

                addr32,

                size,

                op

            );

            cpu->running = false;

            emit_fault_diagnostics(cpu, cpu->pc);

            return false;

        }

        return true;

    }

    u32  guard    = stack_guard_bytes();

    u64  base_val = cpu->regs[base_reg];

    bool base_in_stack =

        base_val <= (u64)UINT32_MAX && stack_contains((u32)base_val);

    bool start_in_stack = stack_contains(addr32);

    bool end_in_stack   = stack_contains(end);

    if (base_in_stack || start_in_stack || end_in_stack) {

        u32 bottom = stack_bottom();

        if (addr32 < bottom || end > memory_top()) {

            printf(

                "Stack %s out of bounds at PC=%08x: base=%s (0x%08x) addr=%08x "

                "size=%u (%s)\n",

                kind,

                cpu->pc,

                reg_names[base_reg],

                (u32)cpu->regs[base_reg],

                addr32,

                size,

                op

            );

            cpu->running = false;

            emit_fault_diagnostics(cpu, cpu->pc);

            return false;

        }

        if (stack_guard_overlaps(guard, addr32, end)) {

            printf(

                "Stack guard %s violation at PC=%08x: base=%s (0x%08x) "

                "addr=%08x "

                "size=%u guard=%u (%s)\n",

                kind,

                cpu->pc,

                reg_names[base_reg],

                (u32)cpu->regs[base_reg],

                addr32,

                size,

                guard,

                op

            );

            cpu->running = false;

            emit_fault_diagnostics(cpu, cpu->pc);

            return false;

        }

    }

    return true;

}

/* Validate that a register holds a valid stack address. */

static bool validate_stack_register(

    struct cpu *cpu, reg_t reg, const char *label, u32 pc, bool optional

) {

    /* Skip validation for performance if disabled. */

    if (!g_opts.validate_memory)

        return true;

    u64 value = cpu->regs[reg];

    if (optional && value == 0)

        return true;

    /* Detect addresses with upper bits set -- these can never be valid

     * stack addresses in the emulator's physical memory. */

    if (value > (u64)UINT32_MAX || (u32)value < stack_bottom() ||

        (u32)value > memory_top()) {

        printf(

            "%s (%s) out of stack bounds at PC=%08x: value=%016llx\n",

            label,

            reg_names[reg],

            pc,

            (unsigned long long)value

        );

        cpu->running = false;

        emit_fault_diagnostics(cpu, pc);

        return false;

    }

    u32 guard = stack_guard_bytes();

    if (stack_guard_contains(guard, (u32)value)) {

        printf(

            "Stack guard triggered by %s (%s) at PC=%08x: value=%08x "

            "guard=%u\n",

            label,

            reg_names[reg],

            pc,

            (u32)value,

            guard

        );

        cpu->running = false;

        emit_fault_diagnostics(cpu, pc);

        return false;

    }

    return true;

}

/* Toggle stack guarding in the TUI and re-validate live stack registers. */

static void toggle_stack_guard(struct cpu *cpu) {

    g_opts.stack_guard = !g_opts.stack_guard;

    printf(

        "\nStack guard %s (%u bytes)\n",

        g_opts.stack_guard ? "enabled" : "disabled",

        STACK_GUARD_BYTES

    );

    if (g_opts.stack_guard && cpu->running) {

        validate_stack_register(cpu, SP, "SP", cpu->pc, false);

        if (cpu->running) {

            validate_stack_register(cpu, FP, "FP", cpu->pc, true);

        }

    }

}

/* Get terminal dimensions. */

static struct termsize termsize(void) {

    struct winsize  w;

    struct termsize size = { 24, 80 }; /* Default fallback. */

    if (ioctl(STDOUT_FILENO, TIOCGWINSZ, &w) != -1) {

        size.rows = w.ws_row;

        size.cols = w.ws_col;

    }

    return size;

}

/* Take a snapshot of the current CPU and memory state. */

static void snapshot_save(struct cpu *cpu) {

    int nexti = (snapshots.head + 1 + MAX_SNAPSHOTS) % MAX_SNAPSHOTS;

    memcpy(&snapshots.snapshots[nexti].cpu, cpu, sizeof(struct cpu));

    memcpy(snapshots.snapshots[nexti].memory, memory, g_opts.memory_size);

    /* Fix the program pointer to reference the snapshot's own memory. */

    snapshots.snapshots[nexti].cpu.program =

        (instr_t *)snapshots.snapshots[nexti].memory;

    snapshots.head = nexti;

    if (snapshots.count < MAX_SNAPSHOTS)

        snapshots.count++;

}

/* Restore the most recent snapshot, returning false if none remain. */

static bool snapshot_restore(struct cpu *cpu) {

    if (snapshots.count <= 1)

        return false;

    snapshots.head = (snapshots.head + MAX_SNAPSHOTS - 1) % MAX_SNAPSHOTS;

    snapshots.count--;

    int previ = snapshots.head;

    memcpy(cpu, &snapshots.snapshots[previ].cpu, sizeof(struct cpu));

    memcpy(memory, snapshots.snapshots[previ].memory, g_opts.memory_size);

    /* Fix the program pointer to reference the live memory buffer. */

    cpu->program = (instr_t *)memory;

    return true;

}

/* Initialize the snapshot buffer with an initial snapshot. */

static void snapshot_init(struct cpu *cpu) {

    snapshots.head  = -1;

    snapshots.count = 0;

    snapshot_save(cpu);

}

/* Reset the headless instruction trace buffer. */

static void trace_reset(void) {

    headless_trace.head  = -1;

    headless_trace.count = 0;

}

/* Record the current instruction into the trace ring buffer. */

static void trace_record(struct cpu *cpu, instr_t ins) {

    if (!g_opts.trace_enabled || !g_opts.trace_headless)

        return;

    int next = (headless_trace.head + 1 + TRACE_HISTORY) % TRACE_HISTORY;

    headless_trace.head                = next;

    headless_trace.entries[next].pc    = cpu->pc;

    headless_trace.entries[next].instr = ins;

    memcpy(headless_trace.entries[next].regs, cpu->regs, sizeof(cpu->regs));

    if (headless_trace.count < TRACE_HISTORY)

        headless_trace.count++;

}

/* Dump the headless instruction trace to stdout. */

static bool trace_dump(u32 fault_pc) {

    if (!g_opts.trace_enabled || !g_opts.trace_headless ||

        headless_trace.count == 0)

        return false;

    int limit = (int)g_opts.trace_depth;

    if (limit <= 0)

        limit = FAULT_TRACE_DEPTH;

    if (limit > TRACE_HISTORY)

        limit = TRACE_HISTORY;

    if (limit > headless_trace.count)

        limit = headless_trace.count;

    printf("Headless trace (newest first):\n");

    for (int i = 0; i < limit; i++) {

        int idx = (headless_trace.head - i + TRACE_HISTORY) % TRACE_HISTORY;

        struct trace_entry *entry = &headless_trace.entries[idx];

        char                istr[MAX_INSTR_STR_LEN] = { 0 };

        sprint_instr(entry->instr, istr, true);

        printf(

            "  [%d] PC=%08x %s%s\n",

            i,

            entry->pc,

            istr,

            (entry->pc == fault_pc) ? "  <-- fault" : ""

        );

        printf(

            "       SP=%08x FP=%08x RA=%08x A0=%08x A1=%08x A2=%08x\n",

            (u32)entry->regs[SP],

            (u32)entry->regs[FP],

            (u32)entry->regs[RA],

            (u32)entry->regs[A0],

            (u32)entry->regs[A1],

            (u32)entry->regs[A2]

        );

    }

    return true;

}

/* Dump recent snapshot history to stdout for fault diagnostics. */

static bool snapshot_dump_history(struct cpu *cpu, u32 fault_pc) {

    (void)cpu;

    if (snapshots.count == 0)

        return false;

    int limit = FAULT_TRACE_DEPTH;

    if (limit > snapshots.count)

        limit = snapshots.count;

    printf("Snapshot history (newest first):\n");

    for (int i = 0; i < limit; i++) {

        int idx = (snapshots.head - i + MAX_SNAPSHOTS) % MAX_SNAPSHOTS;