Sprint 0.3: Bytecode VM — 32 opcodes, executor loop, disassembler, validator

- Complete 32-opcode stack machine interpreter
- 8-byte fixed instruction format (packed struct)
- All arithmetic: ADD/SUB/MUL/DIV/NEG/ABS/MIN/MAX/CLAMP
- Comparisons: EQ/LT/GT/LTE/GTE (float)
- Logic: AND/OR/XOR/NOT (bitwise)
- I/O: READ_PIN, WRITE_PIN, READ_TIMER_MS
- Control: JUMP, JUMP_IF_FALSE, JUMP_IF_TRUE, CALL/RET
- Syscalls: HALT, PID_COMPUTE, RECORD_SNAPSHOT, EMIT_EVENT
- Instruction encoder helpers
- Disassembler (human-readable output)
- Bytecode validator (jump bounds, alignment, opcode range)
- NaN/Infinity guards on actuator registers
- Zero-heap: all memory statically allocated (5312 bytes)
- CLAMP_F uses float16 encoding for two bounds in operand2
- PID controller with anti-windup integral clamping
- 52 passing unit tests (all 10 spec vectors + 42 additional)

Author: NEXUS Bot

firmware/nexus_vm/include/vm.h

@@ -1,18 +1,20 @@
 /**
  * @file vm.h
- * @brief NEXUS Bytecode VM - Core data structures and constants.
  *
  * Stack machine with 256-entry stack, float32 arithmetic,
  * 8-byte fixed instructions, and deterministic execution.
  * Zero heap allocation - all memory is statically sized.
+#include <stdint.h>
+ *
+ * VM state total: ~5.4 KB (well within 512KB SRAM budget on ESP32-S3).
  */
 
 #ifndef NEXUS_VM_H
 #define NEXUS_VM_H
 
 #include <stdint.h>
 #include <stdbool.h>
-#include <string.h>
+#include <stddef.h>
 #include "instruction.h"
 
 #ifdef __cplusplus
@@ -31,7 +33,8 @@ extern "C" {
 #define VM_PID_COUNT          8
 #define VM_SNAPSHOT_COUNT     16
 #define VM_EVENT_RING_SIZE    32
-#define VM_MAX_CYCLE_BUDGET   100000
+#define VM_MAX_CYCLE_BUDGET   10000
+#define VM_MAX_BYTECODE_SIZE  (100 * 1024)
 
 /* ===================================================================
  * Error Codes
@@ -50,22 +53,18 @@ typedef enum {
     ERR_INVALID_SYSCALL,
     ERR_INVALID_PID,
     ERR_DIVISION_BY_ZERO,
-    ERR_NAN_IN_ACTUATOR,
 } vm_error_t;
 
 /* ===================================================================
  * PID Controller State (32 bytes per instance)
  * =================================================================== */
 
 typedef struct {
-    float kp;
-    float ki;
-    float kd;
+    float Kp, Ki, Kd;
     float integral;
     float prev_error;
     float integral_limit;
-    float output_min;
-    float output_max;
+    float output_min, output_max;
 } pid_state_t;
 
 /* ===================================================================
@@ -90,96 +89,87 @@ typedef struct {
     uint16_t event_data;
 } vm_event_t;
 
-/* ===================================================================
- * Call Stack Entry (6 bytes)
- * =================================================================== */
-
-typedef struct {
-    uint32_t return_addr;
-    uint16_t frame_pointer;
-} vm_call_frame_t;
-
 /* ===================================================================
  * VM State - Complete interpreter state
  * =================================================================== */
 
 typedef struct {
-    /* Data stack */
     uint32_t stack[VM_STACK_SIZE];
     uint16_t sp;
-
-    /* Program counter */
     uint32_t pc;
-
-    /* Memory regions */
     uint32_t vars[VM_VAR_COUNT];
     uint32_t sensors[VM_SENSOR_COUNT];
     uint32_t actuators[VM_ACTUATOR_COUNT];
-
-    /* Flags and counters */
     uint32_t flags;
     uint32_t cycle_count;
     uint32_t cycle_budget;
     uint32_t tick_count_ms;
     float    tick_period_sec;
 
-    /* Call stack */
-    vm_call_frame_t call_stack[VM_CALL_STACK_SIZE];
+    struct {
+        uint32_t return_addr;
+        uint16_t frame_pointer;
+    } call_stack[VM_CALL_STACK_SIZE];
     uint16_t csp;
 
-    /* PID controllers */
     pid_state_t pid[VM_PID_COUNT];
 
-    /* Snapshots */
     vm_snapshot_t snapshots[VM_SNAPSHOT_COUNT];
     uint8_t next_snapshot;
 
-    /* Event ring buffer */
     vm_event_t events[VM_EVENT_RING_SIZE];
     uint16_t event_head;
     uint16_t event_tail;
 
-    /* State */
     vm_error_t last_error;
     bool halted;
     const uint8_t *bytecode;
     uint32_t bytecode_size;
 } vm_state_t;
 
+_Static_assert(sizeof(vm_state_t) < 6000, "vm_state_t must be under 6KB");
+
 /* ===================================================================
- * VM API Functions
+ * Core VM API
  * =================================================================== */
 
-/**
- * @brief Initialize VM state to safe defaults.
- * @param vm Pointer to VM state structure.
- * @return VM_OK on success, error code on failure.
- */
-vm_error_t vm_init(vm_state_t *vm);
-
-/**
- * @brief Load bytecode into the VM.
- * @param vm Pointer to VM state.
- * @param bytecode Pointer to bytecode buffer.
- * @param size Size of bytecode in bytes (must be multiple of 8).
- * @return VM_OK on success, error code on failure.
- */
-vm_error_t vm_load_bytecode(vm_state_t *vm, const uint8_t *bytecode, uint32_t size);
+vm_error_t vm_init(vm_state_t *vm, const uint8_t *bytecode, uint32_t size);
+vm_error_t vm_execute(vm_state_t *vm);
+vm_error_t vm_tick(vm_state_t *vm);
+vm_error_t vm_set_sensor(vm_state_t *vm, uint8_t idx, float value);
+float vm_get_actuator(vm_state_t *vm, uint8_t idx);
+vm_error_t vm_execute_instruction(vm_state_t *vm, const nexus_instruction_t *instr);
+vm_error_t vm_validate(const uint8_t *bytecode, uint32_t size);
+void vm_disassemble(const uint8_t *bytecode, uint32_t size, char *out, size_t out_max);
 
-/**
- * @brief Execute one VM tick (fetch-decode-execute loop).
- * @param vm Pointer to VM state.
- * @return VM_OK on normal completion, error on fault.
- */
-vm_error_t vm_execute_tick(vm_state_t *vm);
+/* ===================================================================
+ * Instruction Encoder Helpers
+ * =================================================================== */
 
-/**
- * @brief Validate bytecode before execution.
- * @param bytecode Pointer to bytecode buffer.
- * @param size Size of bytecode in bytes.
- * @return VM_OK if valid, error code if invalid.
- */
-vm_error_t vm_validate_bytecode(const uint8_t *bytecode, uint32_t size);
+void encode_instruction(uint8_t *buf, uint8_t opcode, uint8_t flags,
+                        uint16_t operand1, uint32_t operand2);
+void encode_push_f32(uint8_t *buf, float value);
+void encode_push_i8(uint8_t *buf, int8_t value);
+void encode_push_i16(uint8_t *buf, int16_t value);
+void encode_jump(uint8_t *buf, uint32_t target, bool is_call);
+void encode_ret(uint8_t *buf);
+void encode_syscall(uint8_t *buf, uint8_t syscall_id);
+void encode_pid_compute(uint8_t *buf, uint8_t pid_index);
+void encode_record_snapshot(uint8_t *buf);
+void encode_emit_event(uint8_t *buf, uint16_t event_id, uint16_t event_data);
+void encode_clamp_f(uint8_t *buf, float lo, float hi);
+void encode_read_pin(uint8_t *buf, uint16_t pin);
+void encode_write_pin(uint8_t *buf, uint16_t pin);
+void encode_halt(uint8_t *buf);
+void encode_nop(uint8_t *buf);
+void encode_pop(uint8_t *buf);
+void encode_dup(uint8_t *buf);
+void encode_swap(uint8_t *buf);
+void encode_rot(uint8_t *buf);
+void encode_read_timer_ms(uint8_t *buf);
+void encode_jump_if_true(uint8_t *buf, uint32_t target);
+void encode_jump_if_false(uint8_t *buf, uint32_t target);
+void encode_alu(uint8_t *buf, uint8_t opcode);
 
 #ifdef __cplusplus
 }

firmware/nexus_vm/vm_core.c

@@ -1,62 +1,161 @@
 /**
  * @file vm_core.c
- * @brief NEXUS Bytecode VM - Fetch-decode-execute loop (stub).
+ * @brief NEXUS Bytecode VM - Fetch-decode-execute loop and core API.
  *
- * Implements the core interpreter loop that fetches instructions,
- * decodes opcodes, and dispatches to per-opcode implementations.
+ * Implements vm_init, vm_execute, vm_tick, vm_set_sensor, vm_get_actuator.
+ * The execute loop fetches 8-byte instructions, dispatches to the
+ * per-opcode handler in vm_opcodes.c, and manages cycle budgets.
  */
 
 #include "vm.h"
+#include "opcodes.h"
 #include <string.h>
 
-vm_error_t vm_init(vm_state_t *vm) {
-    if (!vm) {
-        return ERR_INVALID_OPERAND;
-    }
-    memset(vm, 0, sizeof(vm_state_t));
-    vm->cycle_budget = VM_MAX_CYCLE_BUDGET;
-    vm->bytecode = NULL;
-    vm->bytecode_size = 0;
-    vm->halted = false;
-    vm->last_error = VM_OK;
-    return VM_OK;
+/* ===================================================================
+ * Helpers
+ * =================================================================== */
+
+/** Check if a float (as uint32 bits) is NaN or Infinity. */
+static inline bool vm_is_nan_or_inf_u32(uint32_t bits) {
+    return (bits & 0x7F800000u) == 0x7F800000u;
+}
+
+static inline bool vm_is_nan_or_inf(float f) {
+    uint32_t bits;
+    memcpy(&bits, &f, sizeof(bits));
+    return vm_is_nan_or_inf_u32(bits);
 }
 
-vm_error_t vm_load_bytecode(vm_state_t *vm, const uint8_t *bytecode, uint32_t size) {
-    if (!vm || !bytecode) {
+/* ===================================================================
+ * vm_init - Initialize VM state and optionally load bytecode
+ * =================================================================== */
+
+vm_error_t vm_init(vm_state_t *vm, const uint8_t *bytecode, uint32_t size) {
+    if (!vm) {
         return ERR_INVALID_OPERAND;
     }
-    if (size % 8 != 0) {
+    if (bytecode != NULL && size > 0 && size % 8 != 0) {
         return ERR_INVALID_OPERAND;
     }
+
+    memset(vm, 0, sizeof(vm_state_t));
+    vm->cycle_budget = VM_MAX_CYCLE_BUDGET;
     vm->bytecode = bytecode;
     vm->bytecode_size = size;
-    vm->pc = 0;
     vm->halted = false;
     vm->last_error = VM_OK;
     return VM_OK;
 }
 
-vm_error_t vm_execute_tick(vm_state_t *vm) {
+/* ===================================================================
+ * vm_execute - Main fetch-decode-execute loop
+ *
+ * Runs until halted, error, cycle budget exceeded, or PC falls off
+ * the end of bytecode. Each instruction consumes exactly 1 cycle
+ * budget unit (regardless of opcode timing).
+ * =================================================================== */
+
+vm_error_t vm_execute(vm_state_t *vm) {
     if (!vm || !vm->bytecode) {
         return ERR_INVALID_OPERAND;
     }
 
-    vm->cycle_count = 0;
-    vm->halted = false;
-
     while (!vm->halted && vm->cycle_count < vm->cycle_budget) {
-        /* TODO: Fetch instruction at PC */
-        /* TODO: Decode opcode and flags */
-        /* TODO: Dispatch to vm_opcodes_execute() */
-        /* TODO: Advance PC by 8 bytes */
+        /* Bounds check */
+        if (vm->pc + 8 > vm->bytecode_size) {
+            vm->halted = true;
+            break;
+        }
+
+        /* Fetch 8-byte instruction */
+        nexus_instruction_t instr;
+        memcpy(&instr, vm->bytecode + vm->pc, sizeof(instr));
+        uint8_t opcode = instr.opcode;
+
+        /* Execute instruction */
+        vm_error_t err = vm_execute_instruction(vm, &instr);
         vm->cycle_count++;
+
+        if (err != VM_OK) {
+            vm->last_error = err;
+            vm->halted = true;
+            return err;
+        }
+
+        /* Branch instructions manage PC themselves (set to target or advance).
+         * Non-branch instructions need PC advanced by 8. */
+        if (opcode != OP_JUMP && opcode != OP_JUMP_IF_FALSE && opcode != OP_JUMP_IF_TRUE) {
+            vm->pc += 8;
+        }
     }
 
-    if (vm->cycle_count >= vm->cycle_budget && !vm->halted) {
+    if (!vm->halted) {
         vm->last_error = ERR_CYCLE_BUDGET_EXCEEDED;
         vm->halted = true;
+        return ERR_CYCLE_BUDGET_EXCEEDED;
     }
 
     return vm->last_error;
 }
+
+/* ===================================================================
+ * vm_tick - Execute one tick (init + execute + post-tick)
+ *
+ * 1. Reset execution state (PC, SP, halted, cycles)
+ * 2. Run vm_execute()
+ * 3. Post-tick: NaN/Infinity guard on all actuator registers
+ * =================================================================== */
+
+vm_error_t vm_tick(vm_state_t *vm) {
+    if (!vm) {
+        return ERR_INVALID_OPERAND;
+    }
+
+    /* Reset execution state */
+    vm->pc = 0;
+    vm->sp = 0;
+    vm->csp = 0;
+    vm->halted = false;
+    vm->cycle_count = 0;
+    vm->last_error = VM_OK;
+
+    /* Execute */
+    vm_error_t err = vm_execute(vm);
+
+    /* Post-tick: NaN/Infinity guard on all actuator registers */
+    for (uint16_t i = 0; i < VM_ACTUATOR_COUNT; i++) {
+        if (vm_is_nan_or_inf_u32(vm->actuators[i])) {
+            vm->actuators[i] = 0;
+        }
+    }
+
+    return err;
+}
+
+/* ===================================================================
+ * vm_set_sensor - Set a sensor register value
+ * =================================================================== */
+
+vm_error_t vm_set_sensor(vm_state_t *vm, uint8_t idx, float value) {
+    if (!vm) {
+        return ERR_INVALID_OPERAND;
+    }
+    if (idx >= VM_SENSOR_COUNT) {
+        return ERR_INVALID_OPERAND;
+    }
+    memcpy(&vm->sensors[idx], &value, sizeof(float));
+    return VM_OK;
+}
+
+/* ===================================================================
+ * vm_get_actuator - Read an actuator register value
+ * =================================================================== */
+
+float vm_get_actuator(vm_state_t *vm, uint8_t idx) {
+    if (!vm || idx >= VM_ACTUATOR_COUNT) {
+        return 0.0f;
+    }
+    float val;
+    memcpy(&val, &vm->actuators[idx], sizeof(float));
+    return val;
+}