code wiki / _hdl_build / rv64im_min_sim.nx
`rv64im_min_sim.nx` source

↩ module page · 1246 lines · 59654 B
1// rv64im_min_sim.nx -- single-cycle RV64IM-min behavioural simulator.
2//
3// First runnable thing in nishi-silicon.  Ties the previously-shipped
4// modules together so RV64IM programs execute end-to-end in pure
5// NishiLang:
6//
7//   decoder (rv64im_min_decoder)  -> opcode kind + operand fields
8//   ALU (rv64im_min_alu)          -> arithmetic compute
9//   regfile (rv64im_min_regfile)  -> 32 GPRs storage
10//   CSR (rv64im_min_csr)          -> M-mode CSRs
11//   CLINT (rv64im_min_clint)      -> MTIP interrupt source
12//   UART (rv64im_min_uart)        -> debug console
13//
14// Why "single-cycle" not "pipelined": a single-cycle model is the
15// canonical "first simulator" -- one instruction per simulator step,
16// no pipeline hazards, no fetch/decode/execute overlap.  Verifies
17// the combinational + sequential modules without the complexity of
18// IF/ID/EX latches or hazard detection.  Pipelined model lands in a
19// follow-on commit; Tier A FPGA bitstream gets the pipelined version
20// (no point fabbing a single-cycle core when the pipelined one is
21// also single-issue in-order and only marginally larger).
22//
23// What this enables:
24//   - Run RV64IM .text segments emitted by the SOVEREIGN toolchain (nx_cc
25//     -> nxasm rv64 backend); gcc/llvm are a diff-lane reference ONLY, never on
26//     the chain (this sim IS the genesis ISA spec + the sovereign-cycle yardstick)
27//   - Validate the decoder + ALU against any RV64IM disassembler
28//   - Boot the nishi-os kernel ELF (after the load/store unit + memory
29//     bus land in a follow-on commit) before fabbing FPGA bitstream
30//
31// Status: SEED.  2026-05-26.  Single-cycle non-interrupt loop.
32// Interrupt handling, load/store, mret/ecall flow land per the TODO
33// markers below.
34
35import "nx_syscalls.nx"
36import "nishi_hdl_primitives.nx"
37import "rv64im_min_decoder.nx"
38import "rv64im_min_alu.nx"
39import "rv64im_min_regfile.nx"
40import "rv64im_min_csr.nx"
41import "rv64im_min_clint.nx"
42import "rv64im_min_uart.nx"
43import "rv64im_min_virtio.nx"
44import "rv64im_min_nvme.nx"
45import "rv64im_min_nndev.nx"
46import "rv64im_min_mmu.nx"
47import "rv64im_min_gpu.nx"
48import "nx_rvc_expand.nx"   // RV64 C (compressed) extension: expand 16-bit -> 32-bit at fetch
49
50// ===== Sim state =================================================
51//
52// The simulator owns instances of every device and a PC register.
53// Memory is a flat byte buffer with the CLINT + UART carve-outs
54// dispatched by the load/store path.
55
56struct NxRv64imSim {
  pc:        i64
  rf:        *NxRv64imRegfile
  csr:       *NxRv64imCsrFile
  clint:     *NxClint
  uart:      *NxUart
  virtio:    *NxVirtioMmio  // legacy virtio-MMIO transport, blk @0x10001000 (K-R2-001a)
  virtio_net:*NxVirtioMmio  // second legacy virtio-MMIO transport, net @0x10002000 (K-R2-001c1)
  nvme:      *NxNvmeCtrl    // NVMe-class controller, admin SQ/CQ @0x10003000 (X-DRV-W1 stage B)
  nndev:     *NxNnDev      // Nishi-native device protocol (NNDP) @0x10005000 (sovereign-device-protocol exceed)
  mmu:       *NxMmu        // Sv39 page-table-walk device @0x10006000 (virtual-memory-paging-mmu)
  xlate_fault: i64         // set by nx_rv64im_xlate on a data-access page fault; step loop traps on it
  gpu:       *NxGpu        // GPU-class command-submission controller @0x10007000 (driver-from-spec D)
  mem_base:  i64           // physical address of mem_buf[0] (e.g., 0x80000000)
  mem_buf:   *u8           // byte-addressable RAM
  mem_size:  i64           // bytes
  valid:     i64
  halted:    i64
  halt_code: i64           // exit code on halt
  steps:     i64           // instructions executed
  priv:      i64           // current privilege: 3=M, 1=S, 0=U (reset M).  Sv39 translation
                           // applies only in S/U; M-mode is always Bare (riscv-priv-spec).
  xlate_store: i64         // 1 if the in-flight data access is a store (page-fault cause select)
  // ----- Per-PC cycle attribution (M2 silicon-feedback foundation) -----
  // pc_cycles[i] = total cycles attributable to PC = mem_base + (i << 2).
  // Indexed by word (4-byte stride) since RV64IM instructions are 32-bit.
  // Caller allocates pc_cycles_buf with at least (mem_size >> 2) i64s.
  // Without these the substrate has no per-instruction perf data; with
  // them the silicon-feedback loop (M3) can pick out top-N hot PCs.
  pc_cycles_buf: *i64
  pc_cycles_cap: i64       // capacity in i64 slots
  pc_cycles_on: i64        // 1 = attribution active; 0 = skip (cheaper hot loop)
  // ----- A-extension (atomics) LR/SC reservation (F107h, 2026-07-18) -----
  // Single-address reservation set: lr.w/d records (resv_addr, resv_valid); sc.w/d succeeds
  // iff still valid AND matches; any sc or amo* clears it.  Single-hart model -> an lr/sc pair
  // with no intervening reservation-breaker succeeds (matches QEMU on the canonical CAS loop);
  // multi-hart contention is the F107g follow-on.
  resv_addr: i64
  resv_valid: i64
95}
96
97// ===== Sim init =================================================
98//
99// Caller provides allocated regfile/csr/clint/uart + memory buffer.
100// Sim init initialises PC to mem_base + entry_offset (typically 0
101// for kernel ELFs which start at the base of mem).
102
103func nx_rv64im_sim_init(s: *NxRv64imSim,
                       rf: *NxRv64imRegfile,
                       csr: *NxRv64imCsrFile,
                       clint: *NxClint,
                       uart: *NxUart,
                       mem_base: i64,
                       mem_buf: *u8,
                       mem_size: i64,
                       entry_offset: i64) -> i64 {
  if (s as i64) == 0 { return 0 - NX_HDL_BAD_KIND }
  if (mem_buf as i64) == 0 { return 0 - NX_HDL_BAD_KIND }
  if mem_size <= 0 { return 0 - NX_HDL_BAD_KIND }
  s.pc = mem_base + entry_offset
  s.rf = rf
  s.csr = csr
  s.clint = clint
  s.uart = uart
  // virtio attaches separately via nx_rv64im_sim_attach_virtio (keeps the init
  // signature stable -- API contract stability).  Null until the runner wires it.
  s.virtio = (0 as i64) as *NxVirtioMmio
  s.virtio_net = (0 as i64) as *NxVirtioMmio
  s.nvme = (0 as i64) as *NxNvmeCtrl
  s.nndev = (0 as i64) as *NxNnDev
  s.mmu = (0 as i64) as *NxMmu
  s.gpu = (0 as i64) as *NxGpu
  s.xlate_fault = 0
  s.priv = 3                // reset to M-mode
  s.xlate_store = 0
  s.mem_base = mem_base
  s.mem_buf = mem_buf
  s.mem_size = mem_size
  s.valid = 1
  s.halted = 0
  s.halt_code = 0
  s.steps = 0
  // Cycle attribution opt-in: caller wires nx_rv64im_sim_enable_pc_cycles
  // after init.  Default off so the hot step loop stays branch-free for
  // bench runs that don't need profiling.
  s.pc_cycles_buf = (0 as i64) as *i64
  s.pc_cycles_cap = 0
  s.pc_cycles_on = 0
  // A-extension reservation starts clear (no lr outstanding).
  s.resv_addr = 0
  s.resv_valid = 0
  return NX_HDL_OK
148}
149
150// ===== virtio-MMIO attach (K-R2-001a) =================================================
151//
152// Wires a (already-init'd) virtio-MMIO transport into the sim so load32/store32 route
153// the 0x10001000..NX_VIRTIO_END window to it.  Kept separate from sim_init so the init
154// signature stays stable.  Null virtio = no device (load32/store32 fall through to 0).
155func nx_rv64im_sim_attach_virtio(s: *NxRv64imSim, virtio: *NxVirtioMmio) -> i64 {
  if s.valid != 1 { return 0 - NX_HDL_BAD_KIND }
  s.virtio = virtio
  return NX_HDL_OK
159}
160
161// ===== second virtio-MMIO attach: virtio-net (K-R2-001c1) =================================
162// Wires the net device (DeviceID=1) so load32/store32 route the 0x10002000..NX_VIRTIO_NET_END
163// window to it.  Independent of the blk device -- the blk window (0x10001000) is untouched.
164func nx_rv64im_sim_attach_virtio_net(s: *NxRv64imSim, virtio_net: *NxVirtioMmio) -> i64 {
  if s.valid != 1 { return 0 - NX_HDL_BAD_KIND }
  s.virtio_net = virtio_net
  return NX_HDL_OK
168}
169
170// ===== NVMe-class controller attach (X-DRV-W1 stage B) =================================
171// Wires the NVMe controller (admin SQ/CQ @0x10003000) so load32/store32 route the
172// 0x10003000..NX_NVME_END window to it.  Independent of the virtio devices -- the blk + net
173// windows are untouched (additive).  Null nvme = no device (the window falls through to 0).
174func nx_rv64im_sim_attach_nvme(s: *NxRv64imSim, nvme: *NxNvmeCtrl) -> i64 {
  if s.valid != 1 { return 0 - NX_HDL_BAD_KIND }
  s.nvme = nvme
  return NX_HDL_OK
178}
179
180// ===== Nishi-native device protocol attach (sovereign-device-protocol exceed) =================
181// Wires the NNDP device (NND1 @0x10004000) so load32/store32 route the 0x10004000..NX_NNDEV_END
182// window to it.  Independent of virtio + nvme (their windows are untouched -- additive).  Null
183// nndev = no device (the window falls through to 0).
184func nx_rv64im_sim_attach_nndev(s: *NxRv64imSim, nndev: *NxNnDev) -> i64 {
  if s.valid != 1 { return 0 - NX_HDL_BAD_KIND }
  s.nndev = nndev
  return NX_HDL_OK
188}
189
190// ===== GPU-class controller attach (driver-from-spec instance D, GPU trajectory) =================
191// Wires the GPU controller (command ring @0x10007000) so load32/store32 route the 0x10007000..
192// NX_GPU_END window to it.  Independent of the other devices -- their windows are untouched (additive).
193func nx_rv64im_sim_attach_gpu(s: *NxRv64imSim, gpu: *NxGpu) -> i64 {
  if s.valid != 1 { return 0 - NX_HDL_BAD_KIND }
  s.gpu = gpu
  return NX_HDL_OK
197}
198
199// ===== Sv39 MMU walk device attach (virtual-memory-paging-mmu) =================================
200// Wires the Sv39 page-table-walk device (@0x10006000) so load32/store32 route the 0x10006000..
201// NX_MMU_END window to it.  Independent of all other devices (additive).  Null mmu = no device.
202func nx_rv64im_sim_attach_mmu(s: *NxRv64imSim, mmu: *NxMmu) -> i64 {
  if s.valid != 1 { return 0 - NX_HDL_BAD_KIND }
  s.mmu = mmu
  return NX_HDL_OK
206}
207
208// ===== Cycle attribution opt-in =================================================
209//
210// Hand in a pre-allocated buffer of (mem_size >> 2) i64s (one slot per
211// 4-byte instruction word).  Once enabled, every step() bumps the slot
212// for the executing PC.  Disabled paths skip the bump in 1 branch.
213
214func nx_rv64im_sim_enable_pc_cycles(s: *NxRv64imSim,
                                    buf: *i64, cap: i64) -> i64 {
  if s.valid != 1 { return 0 - NX_HDL_BAD_KIND }
  if (buf as i64) == 0 { return 0 - NX_HDL_BAD_KIND }
  let need: i64 = s.mem_size >> 2
  if cap < need { return 0 - NX_HDL_GRAPH_FULL }
  s.pc_cycles_buf = buf
  s.pc_cycles_cap = cap
  s.pc_cycles_on = 1
  var i: i64 = 0
  while i < cap { buf[i] = 0; i = i + 1 }
  return NX_HDL_OK
226}
227
228// Read cycles attributable to a specific PC (returns 0 if out of range
229// or attribution disabled).
230func nx_rv64im_sim_pc_cycles_at(s: *NxRv64imSim, pc: i64) -> i64 {
  if s.pc_cycles_on != 1 { return 0 }
  if pc < s.mem_base { return 0 }
  let off: i64 = (pc - s.mem_base) >> 2
  if off < 0 { return 0 }
  if off >= s.pc_cycles_cap { return 0 }
  return s.pc_cycles_buf[off]
237}
238
239// Pick the top-N hottest PCs.  out_pcs[i] / out_cycles[i] filled with
240// the i-th hottest (descending).  Returns count actually filled (<= n).
241// V1 is O(cap * n) -- fine for n <= ~50; better algorithm when N gets
242// large.
243func nx_rv64im_sim_pc_cycles_topn(s: *NxRv64imSim, n: i64,
                                  out_pcs: *i64, out_cycles: *i64) -> i64 {
  if s.pc_cycles_on != 1 { return 0 }
  if (out_pcs as i64) == 0 { return 0 - NX_HDL_BAD_KIND }
  if (out_cycles as i64) == 0 { return 0 - NX_HDL_BAD_KIND }
  var filled: i64 = 0
  while filled < n {
      var best_off: i64 = 0 - 1
      var best_val: i64 = 0
      var i: i64 = 0
      while i < s.pc_cycles_cap {
          let v: i64 = s.pc_cycles_buf[i]
          // Skip slots already picked (encoded by negating after pick).
          if v > best_val {
              best_val = v
              best_off = i
          }
          i = i + 1
      }
      if best_off < 0 { return filled }
      if best_val == 0 { return filled }
      out_pcs[filled] = s.mem_base + (best_off << 2)
      out_cycles[filled] = best_val
      // Mark picked by zeroing the slot.  Destructive but acceptable
      // for a one-shot top-N read; caller can re-enable + re-run if
      // they need fresh data.
      s.pc_cycles_buf[best_off] = 0
      filled = filled + 1
  }
  return filled
273}
274
275// ===== Memory access (load/store) =================================================
276//
277// Routes physical addresses to the right device:
278//   - RAM (mem_base..mem_base+mem_size) -> mem_buf
279//   - CLINT (0x02000000..0x0200C000)     -> clint MMIO
280//   - UART  (0x10000000..0x10000008)     -> uart MMIO
281//   - Anything else                       -> halt (illegal access)
282
283func nx_rv64im_sim_load8(s: *NxRv64imSim, addr: i64) -> i64 {
  if addr >= s.mem_base {
      let off: i64 = addr - s.mem_base
      if off < s.mem_size {
          return s.mem_buf[off] as i64
      }
  }
  // UART path: LSR polling reads via lbu.  Returns the byte in
  // the low 8 bits; sign-extension done by the caller per funct3.
  if addr >= NX_UART_BASE { if addr < NX_UART_END {
      let out: *i64 = (sys_mmap(8)) as *i64
      out[0] = 0
      nx_uart_read8(s.uart, addr, out)
      return out[0] & 0xff
  }}
  // CLINT byte reads not used by kernel; return 0.
  return 0
300}
301
302func nx_rv64im_sim_load16(s: *NxRv64imSim, addr: i64) -> i64 {
  if addr >= s.mem_base {
      let off: i64 = addr - s.mem_base
      if off < s.mem_size - 1 {
          let b0: i64 = s.mem_buf[off] as i64
          let b1: i64 = s.mem_buf[off + 1] as i64
          return b0 | (b1 << 8)
      }
  }
  return 0
312}
313
314func nx_rv64im_sim_load32(s: *NxRv64imSim, addr: i64) -> i64 {
  if addr >= s.mem_base {
      let off: i64 = addr - s.mem_base
      if off < s.mem_size - 3 {
          let b0: i64 = s.mem_buf[off] as i64
          let b1: i64 = s.mem_buf[off + 1] as i64
          let b2: i64 = s.mem_buf[off + 2] as i64
          let b3: i64 = s.mem_buf[off + 3] as i64
          return b0 | (b1 << 8) | (b2 << 16) | (b3 << 24)
      }
  }
  // virtio-MMIO transport path (K-R2-001a): lw from the device register window
  // returns the device-modelled 32-bit register value (identity / features / status).
  if addr >= NX_VIRTIO_BASE { if addr < NX_VIRTIO_END {
      if (s.virtio as i64) != 0 {
          let vout: *i64 = (sys_mmap(8)) as *i64
          vout[0] = 0
          nx_virtio_read32(s.virtio, addr, vout)
          return vout[0] & 0xffffffff
      }
  }}
  // virtio-net device register window (K-R2-001c1): lw from the second transport block
  // at 0x10002000 returns DeviceID=1 + the same identity/feature/status surface as blk.
  if addr >= NX_VIRTIO_NET_BASE { if addr < NX_VIRTIO_NET_END {
      if (s.virtio_net as i64) != 0 {
          let nout: *i64 = (sys_mmap(8)) as *i64
          nout[0] = 0
          nx_virtio_read32(s.virtio_net, addr, nout)
          return nout[0] & 0xffffffff
      }
  }}
  // NVMe controller register window (X-DRV-W1 stage B): lw from 0x10003000.. returns CAP/VS,
  // the latched CC/AQA/ASQ/ACQ regs, CSTS (RDY flop the driver polls), and the CQPEEK binding-
  // proof instrument.  An INDEPENDENT device instance -- the virtio windows are untouched.
  if addr >= NX_NVME_BASE { if addr < NX_NVME_END {
      if (s.nvme as i64) != 0 {
          let mout: *i64 = (sys_mmap(8)) as *i64
          mout[0] = 0
          nx_nvme_read32(s.nvme, addr, mout)
          return mout[0] & 0xffffffff
      }
  }}
  // Nishi-native device window (sovereign-device-protocol): lw from 0x10004000.. returns MAGIC/
  // DEVCLASS identity, the latched ENABLE/CMD_ADDR, and the STATUS/RESULT completion the driver
  // reads back after a doorbell.  An INDEPENDENT instance -- virtio + nvme windows untouched.
  if addr >= NX_NNDEV_BASE { if addr < NX_NNDEV_END {
      if (s.nndev as i64) != 0 {
          let dout: *i64 = (sys_mmap(8)) as *i64
          dout[0] = 0
          nx_nndev_read32(s.nndev, addr, dout)
          return dout[0] & 0xffffffff
      }
  }}
  // Sv39 MMU walk device window (virtual-memory-paging-mmu): lw from 0x10006000.. returns the
  // translated PADDR + FAULT the device latched on the last doorbell walk.  Independent instance.
  if addr >= NX_MMU_BASE { if addr < NX_MMU_END {
      if (s.mmu as i64) != 0 {
          let uout: *i64 = (sys_mmap(8)) as *i64
          uout[0] = 0
          nx_mmu_read32(s.mmu, addr, uout)
          return uout[0] & 0xffffffff
      }
  }}
  // GPU-class controller register window (driver-from-spec D): lw from 0x10007000.. returns ID,
  // CTRL/STATUS, RING base, the FENCE seqno + the RESULTPEEK binding-proof word.  Independent instance.
  if addr >= NX_GPU_BASE { if addr < NX_GPU_END {
      if (s.gpu as i64) != 0 {
          let gout: *i64 = (sys_mmap(8)) as *i64
          gout[0] = 0
          nx_gpu_read32(s.gpu, addr, gout)
          return gout[0] & 0xffffffff
      }
  }}
  return 0
388}
389
390// Sign-extend an 8/16/32-bit value to 64 bits.
391func nx_rv64im_sext8(v: i64) -> i64 {
  let low: i64 = v & 0xff
  if (low & 0x80) != 0 { return low | (0 - 256) }
  return low
395}
396func nx_rv64im_sext16(v: i64) -> i64 {
  let low: i64 = v & 0xffff
  if (low & 0x8000) != 0 { return low | (0 - 65536) }
  return low
400}
401
402func nx_rv64im_sim_load64(s: *NxRv64imSim, addr: i64) -> i64 {
  if addr >= s.mem_base {
      let off: i64 = addr - s.mem_base
      if off < s.mem_size - 7 {
          var v: i64 = 0
          var i: i64 = 0
          while i < 8 {
              let b: i64 = s.mem_buf[off + i] as i64
              v = v | (b << (i * 8))
              i = i + 1
          }
          return v
      }
  }
  // CLINT MMIO path
  if addr >= NX_CLINT_BASE { if addr < NX_CLINT_END {
      let out: *i64 = (sys_mmap(8)) as *i64
      out[0] = 0
      nx_clint_read64(s.clint, addr, out)
      return out[0]
  }}
  return 0
424}
425
426func nx_rv64im_sim_store64(s: *NxRv64imSim, addr: i64, value: i64) -> i64 {
  if addr >= s.mem_base {
      let off: i64 = addr - s.mem_base
      if off < s.mem_size - 7 {
          var i: i64 = 0
          while i < 8 {
              s.mem_buf[off + i] = ((value >> (i * 8)) & 0xff) as u8
              i = i + 1
          }
          return NX_HDL_OK
      }
  }
  if addr >= NX_CLINT_BASE { if addr < NX_CLINT_END {
      return nx_clint_write64(s.clint, addr, value)
  }}
  // UART path (8-bit writes only at THR; 64-bit writes get low byte)
  if addr >= NX_UART_BASE { if addr < NX_UART_END {
      return nx_uart_write8(s.uart, addr, value & 0xff)
  }}
  return 0 - NX_HDL_BAD_KIND
446}
447
448func nx_rv64im_sim_store8(s: *NxRv64imSim, addr: i64, value: i64) -> i64 {
  if addr >= s.mem_base {
      let off: i64 = addr - s.mem_base
      if off < s.mem_size {
          s.mem_buf[off] = (value & 0xff) as u8
          return NX_HDL_OK
      }
  }
  if addr >= NX_UART_BASE { if addr < NX_UART_END {
      return nx_uart_write8(s.uart, addr, value & 0xff)
  }}
  return 0 - NX_HDL_BAD_KIND
460}
461
462func nx_rv64im_sim_store16(s: *NxRv64imSim, addr: i64, value: i64) -> i64 {
  if addr >= s.mem_base {
      let off: i64 = addr - s.mem_base
      if off < s.mem_size - 1 {
          s.mem_buf[off]     = (value & 0xff) as u8
          s.mem_buf[off + 1] = ((value >> 8) & 0xff) as u8
          return NX_HDL_OK
      }
  }
  return 0 - NX_HDL_BAD_KIND
472}
473
474func nx_rv64im_sim_store32(s: *NxRv64imSim, addr: i64, value: i64) -> i64 {
  if addr >= s.mem_base {
      let off: i64 = addr - s.mem_base
      if off < s.mem_size - 3 {
          s.mem_buf[off]     = (value & 0xff) as u8
          s.mem_buf[off + 1] = ((value >> 8) & 0xff) as u8
          s.mem_buf[off + 2] = ((value >> 16) & 0xff) as u8
          s.mem_buf[off + 3] = ((value >> 24) & 0xff) as u8
          return NX_HDL_OK
      }
  }
  // virtio-MMIO transport path (K-R2-001a): sw into the device register window
  // latches GuestFeatures / drives the Status handshake (ACK/DRIVER/FEATURES_OK/
  // DRIVER_OK) or resets the device (Status write of 0).  On a QueueNotify kick
  // (K-R2-001b2a) the device DMA-reads descriptor 0's first field from the QueuePFN-
  // bound ring page in guest RAM (the sim owns mem_buf, so we hand it in) and latches
  // it into QueueDescPeek -- proving the device walked the descriptor the driver laid.
  if addr >= NX_VIRTIO_BASE { if addr < NX_VIRTIO_END {
      if (s.virtio as i64) != 0 {
          let wr: i64 = nx_virtio_write32(s.virtio, addr, value)
          if addr == (NX_VIRTIO_BASE + NX_VIRTIO_OFF_QUEUENOTIFY) {
              nx_virtio_notify_dma(s.virtio, s.mem_buf, s.mem_base, s.mem_size)
          }
          return wr
      }
  }}
  // virtio-net device register window (K-R2-001c1/c2/c3): sw into the second transport block
  // at 0x10002000 latches GuestFeatures / drives the Status handshake (c1) + the legacy
  // virtqueue-config registers (c2).  On a QueueNotify kick (K-R2-001c3) the net device DMA-
  // walks the driver's tx ring EXACTLY like the blk branch above: nx_virtio_notify_dma is
  // device-instance-generic (it walks v.storage[QPFN] -> desc-read + avail/used + the data
  // round-trip), so handing it s.virtio_net makes the net FRAME word the driver laid in the
  // tx descriptor's data buffer round-trip into QueueSectPeek with NO new DMA code.  The blk
  // device at 0x10001000 is untouched -- this is the net block's own QueueNotify trigger.
  if addr >= NX_VIRTIO_NET_BASE { if addr < NX_VIRTIO_NET_END {
      if (s.virtio_net as i64) != 0 {
          let wrn: i64 = nx_virtio_write32(s.virtio_net, addr, value)
          if addr == (NX_VIRTIO_NET_BASE + NX_VIRTIO_OFF_QUEUENOTIFY) {
              nx_virtio_notify_dma(s.virtio_net, s.mem_buf, s.mem_base, s.mem_size)
          }
          return wrn
      }
  }}
  // NVMe controller register window (X-DRV-W1 stage B): sw into 0x10003000.. latches CC (and
  // sets/clears the CSTS.RDY flop on CC.EN), AQA, the ASQ/ACQ base-address registers, and the
  // doorbells.  On the SQ-Tail doorbell (off_sq0tdbl) the device runs the doorbell DMA: it
  // fetches the 64-byte SQE from ASQ_base (reads opcode+CID), posts a phase-tagged 16-byte CQE
  // into ACQ_base, and latches NvmeCqPeek = (CID<<16)|status|phase.  The sim owns mem_buf, so
  // it hands guest RAM in -- mirroring the virtio QueueNotify branch.  The virtio devices are
  // untouched -- this is the NVMe instance's own doorbell trigger.
  if addr >= NX_NVME_BASE { if addr < NX_NVME_END {
      if (s.nvme as i64) != 0 {
          let wrm: i64 = nx_nvme_write32(s.nvme, addr, value)
          if addr == (NX_NVME_BASE + NX_NVME_OFF_SQ0TDBL) {
              nx_nvme_doorbell_dma(s.nvme, s.mem_buf, s.mem_base, s.mem_size)
          }
          return wrm
      }
  }}
  // Nishi-native device window (sovereign-device-protocol): sw into 0x10004000.. latches ENABLE
  // (single-step bring-up) / CMD_ADDR.  On the DOORBELL write the device runs the inline command
  // at CMD_ADDR (DMA-reads the descriptor + the data buffer in guest RAM, the sim owns mem_buf so
  // we hand it in) and latches STATUS + RESULT inline -- ONE descriptor, ONE round-trip, NO rings.
  // virtio + nvme devices are untouched -- this is the NNDP instance's own doorbell trigger.
  if addr >= NX_NNDEV_BASE { if addr < NX_NNDEV_END {
      if (s.nndev as i64) != 0 {
          let wrd: i64 = nx_nndev_write32(s.nndev, addr, value)
          if addr == (NX_NNDEV_BASE + NX_NNDEV_OFF_DOORBELL) {
              nx_nndev_doorbell_dma(s.nndev, s.mem_buf, s.mem_base, s.mem_size)
          }
          return wrd
      }
  }}
  // Sv39 MMU walk device window (virtual-memory-paging-mmu): sw into 0x10006000.. latches satp /
  // vaddr.  On the DOORBELL write the device WALKS the 3-level Sv39 page table in guest RAM (the
  // sim owns mem_buf, so we hand it in) and latches PADDR + FAULT.  Other devices untouched.
  if addr >= NX_MMU_BASE { if addr < NX_MMU_END {
      if (s.mmu as i64) != 0 {
          let wru: i64 = nx_mmu_write32(s.mmu, addr, value)
          if addr == (NX_MMU_BASE + NX_MMU_OFF_DOORBELL) {
              nx_mmu_doorbell_walk(s.mmu, s.mem_buf, s.mem_base, s.mem_size)
          }
          return wru
      }
  }}
  // GPU-class controller window (driver-from-spec D): sw into 0x10007000.. latches CTRL (sets/clears
  // STATUS.READY on CTRL.EN) + the RING base.  On the DOORBELL write the device runs the dispatch DMA:
  // it fetches the command packet from RING base, validates the SPIR-V magic, signals the FENCE + latches
  // RESULTPEEK.  The sim owns mem_buf, so it hands guest RAM in.  Other devices untouched.
  if addr >= NX_GPU_BASE { if addr < NX_GPU_END {
      if (s.gpu as i64) != 0 {
          let wrg: i64 = nx_gpu_write32(s.gpu, addr, value)
          if addr == (NX_GPU_BASE + NX_GPU_OFF_DOORBELL) {
              nx_gpu_doorbell_dma(s.gpu, s.mem_buf, s.mem_base, s.mem_size)
          }
          return wrg
      }
  }}
  // SiFive test/finisher at 0x100000: 32-bit write of 0x5555 = clean
  // poweroff per kernel tasks.nx:203-204.
  if addr == 0x100000 {
      if (value & 0xffff) == 0x5555 {
          s.halted = 1
          s.halt_code = 0    // clean exit
          return NX_HDL_OK
      }
  }
  return 0 - NX_HDL_BAD_KIND
582}
583
584// ===== CPU-datapath Sv39 translation (virtual-memory-paging-mmu, integration rung) ============
585//
586// When satp.MODE == Sv39 (8), DATA loads/stores translate their address through the page table in
587// guest RAM (the SAME nx_sv39_walk the MMU walk device uses).  satp.MODE == 0 (Bare, the reset +
588// every existing test) -> identity, so there is ZERO change to all prior gates.  Device MMIO
589// windows stay physical (identity) even under Sv39 in this slice so a paging test can still drive
590// the UART/finisher.  Instruction FETCH is NOT translated here (the image is physically addressed);
591// fetch-translation + the page-fault TRAP on a bad data walk are the documented follow-on rungs --
592// on a walk fault this returns the vaddr unchanged (a tampered mapping then reads out-of-range -> 0,
593// which the gate's verify catches).
594func nx_rv64im_is_device(addr: i64) -> i64 {
  if addr >= 0x100000   { if addr < 0x100008   { return 1 } }   // SiFive finisher
  if addr >= 0x02000000 { if addr < 0x0200C000 { return 1 } }   // CLINT
  if addr >= 0x10000000 { if addr < 0x10000008 { return 1 } }   // UART
  if addr >= 0x10001000 { if addr < 0x10007000 { return 1 } }   // virtio/nvme/nndev/mmu windows
  return 0
600}
601const NX_ACC_FETCH: i64 = 0
602const NX_ACC_LOAD:  i64 = 1
603const NX_ACC_STORE: i64 = 2
604// Translate `vaddr` for an access of type `access` (FETCH/LOAD/STORE) and ENFORCE the page's permission
605// bits (riscv-priv-spec): a fetch needs X (the NX-bit / W^X foundation -- a data page is not executable),
606// a load needs R, a store needs W.  A valid leaf lacking the required bit signals xlate_fault, which the
607// step loop routes to the SAME page-fault cause it already uses per access (instr=12/load=13/store=15).
608// Identity in M-mode and under Bare, and device MMIO stays physical -> every physically-addressed path
609// is unchanged (perm enforcement applies only to S/U-mode Sv39 RAM accesses).
610func nx_rv64im_xlate(s: *NxRv64imSim, vaddr: i64, access: i64) -> i64 {
  if s.priv == 3 { return vaddr }                        // M-mode: always Bare (riscv-priv-spec)
  let satp: i64 = nx_rv64im_csr_read(s.csr, NX_CSR_SATP)
  if ((satp >> 60) & 0xf) != 8 { return vaddr }          // Bare / non-Sv39: identity
  if nx_rv64im_is_device(vaddr) == 1 { return vaddr }    // device MMIO stays physical
  let fb: *i64 = sys_mmap(16) as *i64
  let pb: *i64 = sys_mmap(16) as *i64                    // leaf PTE perm bits (V|R|W|X) from the walk
  let pab: *i64 = sys_mmap(16) as *i64                   // leaf PTE physical address (A/D write-back target)
  let pa: i64 = nx_sv39_walk(satp, s.mem_buf, s.mem_base, s.mem_size, vaddr, fb, pb, pab)
  if fb[0] == 1 { s.xlate_fault = 1; return vaddr }      // walk fault: signal the step loop to trap
  var need: i64 = 8                                      // FETCH needs X (bit 3)
  if access == NX_ACC_LOAD  { need = 2 }                 // LOAD  needs R (bit 1)
  if access == NX_ACC_STORE { need = 4 }                 // STORE needs W (bit 2)
  if (pb[0] & need) == 0 { s.xlate_fault = 1; return vaddr }   // R/W/X permission violation -> page fault
  // USER/SUPERVISOR isolation (riscv-priv-spec, the U-bit = bit 4): a U-mode access REQUIRES a
  // user page; an S-mode access to a USER page is denied unless mstatus.SUM (Supervisor User Memory).
  let is_user_page: i64 = pb[0] & 0x10
  if s.priv == 0 { if is_user_page == 0 { s.xlate_fault = 1; return vaddr } }   // U-mode: page must be U=1
  if s.priv == 1 { if is_user_page != 0 {                                       // S-mode touching a U=1 page
      let mstatus: i64 = nx_rv64im_csr_read(s.csr, NX_CSR_MSTATUS)
      if (mstatus & 0x40000) == 0 { s.xlate_fault = 1; return vaddr }           // SUM=0 -> deny (kernel can't deref user memory by default)
  } }
  // ACCESSED/DIRTY bits (hardware-managed, riscv-priv-spec Svadu): a SUCCESSFUL translation sets A on
  // any access + D on a store, in the leaf PTE.  Additive -- A/D (bits 6/7) don't affect the PA/perm
  // decode, so every prior test is unchanged; they let the OS drive page replacement + dirty write-back.
  let pte_off: i64 = pab[0] - s.mem_base
  if nx_mmu_inrange(pte_off, 8, s.mem_size) == 1 {
      let cur: i64 = nx_mmu_rd64(s.mem_buf, pte_off)
      var npte: i64 = cur | 0x40                                               // A (bit 6)
      if access == NX_ACC_STORE { npte = npte | 0x80 }                         // D (bit 7) on a store
      if npte != cur { nx_mmu_wr64(s.mem_buf, pte_off, npte) }
  }
  return pa
643}
644
645// ===== Map decoded {opcode, funct3, funct7} -> ALU op =================================================
646//
647// The decoder gave us NX_RV64IM_OP_OP / OP_IMM / OP_32 / etc.; we
648// need the finer-grained ALU op for the compute call.
649
650func nx_rv64im_sim_alu_select(op_kind: i64, funct3: i64, funct7: i64) -> i64 {
  if op_kind == NX_RV64IM_OP_OP {
      if funct7 == 0x01 {
          // M extension
          if funct3 == 0 { return NX_RV64IM_ALU_MUL }
          if funct3 == 1 { return NX_RV64IM_ALU_MULH }
          if funct3 == 2 { return NX_RV64IM_ALU_MULHSU }
          if funct3 == 3 { return NX_RV64IM_ALU_MULHU }
          if funct3 == 4 { return NX_RV64IM_ALU_DIV }
          if funct3 == 5 { return NX_RV64IM_ALU_DIVU }
          if funct3 == 6 { return NX_RV64IM_ALU_REM }
          if funct3 == 7 { return NX_RV64IM_ALU_REMU }
      }
      if funct3 == 0 {
          if funct7 == 0x20 { return NX_RV64IM_ALU_SUB }
          return NX_RV64IM_ALU_ADD
      }
      if funct3 == 1 { return NX_RV64IM_ALU_SLL }
      if funct3 == 2 { return NX_RV64IM_ALU_SLT }
      if funct3 == 3 { return NX_RV64IM_ALU_SLTU }
      if funct3 == 4 { return NX_RV64IM_ALU_XOR }
      if funct3 == 5 {
          if funct7 == 0x20 { return NX_RV64IM_ALU_SRA }
          return NX_RV64IM_ALU_SRL
      }
      if funct3 == 6 { return NX_RV64IM_ALU_OR }
      if funct3 == 7 { return NX_RV64IM_ALU_AND }
  }
  if op_kind == NX_RV64IM_OP_OP_IMM {
      // Same as OP except immediates; ALU is the same compute layer
      // (the executor swaps operand b for the immediate value).
      if funct3 == 0 { return NX_RV64IM_ALU_ADD }
      if funct3 == 1 { return NX_RV64IM_ALU_SLL }
      if funct3 == 2 { return NX_RV64IM_ALU_SLT }
      if funct3 == 3 { return NX_RV64IM_ALU_SLTU }
      if funct3 == 4 { return NX_RV64IM_ALU_XOR }
      if funct3 == 5 {
          // SRLI vs SRAI distinguished by funct7 bit 30
          if funct7 == 0x20 { return NX_RV64IM_ALU_SRA }
          return NX_RV64IM_ALU_SRL
      }
      if funct3 == 6 { return NX_RV64IM_ALU_OR }
      if funct3 == 7 { return NX_RV64IM_ALU_AND }
  }
  if op_kind == NX_RV64IM_OP_OP_32 {
      if funct7 == 0x01 {
          if funct3 == 0 { return NX_RV64IM_ALU_MULW }
          if funct3 == 4 { return NX_RV64IM_ALU_DIVW }
          if funct3 == 5 { return NX_RV64IM_ALU_DIVUW }
          if funct3 == 6 { return NX_RV64IM_ALU_REMW }
          if funct3 == 7 { return NX_RV64IM_ALU_REMUW }
      }
      if funct3 == 0 {
          if funct7 == 0x20 { return NX_RV64IM_ALU_SUBW }
          return NX_RV64IM_ALU_ADDW
      }
      if funct3 == 1 { return NX_RV64IM_ALU_SLLW }
      if funct3 == 5 {
          if funct7 == 0x20 { return NX_RV64IM_ALU_SRAW }
          return NX_RV64IM_ALU_SRLW
      }
  }
  if op_kind == NX_RV64IM_OP_OP_IMM_32 {
      if funct3 == 0 { return NX_RV64IM_ALU_ADDW }
      if funct3 == 1 { return NX_RV64IM_ALU_SLLW }
      if funct3 == 5 {
          if funct7 == 0x20 { return NX_RV64IM_ALU_SRAW }
          return NX_RV64IM_ALU_SRLW
      }
  }
  return NX_RV64IM_ALU_INVALID
721}
722
723// ===== Trap entry =================================================
724//
725// Common path for all exceptions + interrupts.  Saves mepc, sets
726// mcause, transitions mstatus per riscv-privileged-spec §3.1.6.2:
727//   mstatus.MPIE <- mstatus.MIE      (save the interrupt-enable bit)
728//   mstatus.MIE  <- 0                (disable interrupts in handler)
729//   mstatus.MPP  <- current privilege (M-mode in Tier A)
730//   mepc <- pc-of-faulting-instruction
731//   pc   <- mtvec (direct mode; vectored mode unused)
732
733const NX_MCAUSE_INT_MACHINE_TIMER: i64 = 0 - 9223372036854775801    // (1<<63)|7
734const NX_MCAUSE_EXC_ECALL_U:       i64 = 8    // environment call from U-mode
735const NX_MCAUSE_EXC_ECALL_S:       i64 = 9    // environment call from S-mode
736const NX_MCAUSE_EXC_ECALL_M:       i64 = 11
737const NX_MCAUSE_EXC_ILLEGAL_INSTR: i64 = 2
738const NX_MCAUSE_EXC_INSTR_PAGE_FAULT: i64 = 12   // Sv39 instruction-FETCH walk fault
739const NX_MCAUSE_EXC_LOAD_PAGE_FAULT:  i64 = 13   // Sv39 data-load walk fault
740const NX_MCAUSE_EXC_STORE_PAGE_FAULT: i64 = 15   // Sv39 data-store walk fault
741
742const NX_MSTATUS_MIE_BIT:  i64 = 0x08      // bit 3
743const NX_MSTATUS_MPIE_BIT: i64 = 0x80      // bit 7
744const NX_MSTATUS_MPP_MASK: i64 = 0x1800    // bits 11..12
745const NX_MIE_MTIE_BIT:     i64 = 0x80      // bit 7
746
747func nx_rv64im_sim_take_trap(s: *NxRv64imSim, cause: i64, mepc_val: i64) -> i64 {
  // S-MODE DELEGATION (the real OS trap path): an EXCEPTION (cause>=0, not an interrupt) taken from
  // S/U-mode (priv<3) whose medeleg bit is set traps to S-mode -- stvec/sepc/scause/sstatus.SPP -- so
  // the kernel handles its own page-faults/syscalls in S-mode and sret's back.  medeleg resets to 0
  // (mmap-zeroed) so with no delegation every trap still goes to M-mode exactly as before (no regression).
  if cause >= 0 { if s.priv < 3 {
      let medeleg: i64 = nx_rv64im_csr_read(s.csr, NX_CSR_MEDELEG)
      if ((medeleg >> cause) & 1) == 1 {
          let sst: i64 = nx_rv64im_csr_read(s.csr, NX_CSR_MSTATUS)
          var nsst: i64 = sst & (0 - 1 ^ 0x100)            // clear SPP (mstatus bit 8)
          nsst = nsst | ((s.priv & 1) << 8)                // SPP <- the privilege we trap FROM (S=1 / U=0)
          nx_rv64im_csr_write(s.csr, NX_CSR_MSTATUS, nsst)
          nx_rv64im_csr_write(s.csr, NX_CSR_SEPC, mepc_val)
          nx_rv64im_csr_write(s.csr, NX_CSR_SCAUSE, cause)
          s.priv = 1                                       // enter S-mode (the kernel)
          let stvec: i64 = nx_rv64im_csr_read(s.csr, NX_CSR_STVEC)
          s.pc = stvec & (0 - 4)
          return NX_HDL_OK
      }
  } }
  let mstatus: i64 = nx_rv64im_csr_read(s.csr, NX_CSR_MSTATUS)
  var new_mstatus: i64 = mstatus
  // Save MIE into MPIE.
  if (mstatus & NX_MSTATUS_MIE_BIT) != 0 {
      new_mstatus = new_mstatus | NX_MSTATUS_MPIE_BIT
  }
  if (mstatus & NX_MSTATUS_MIE_BIT) == 0 {
      new_mstatus = new_mstatus & (0 - 1 ^ NX_MSTATUS_MPIE_BIT)
  }
  // Disable interrupts.
  new_mstatus = new_mstatus & (0 - 1 ^ NX_MSTATUS_MIE_BIT)
  // MPP <- the privilege we are trapping FROM (so mret can restore it); then enter M-mode.
  new_mstatus = (new_mstatus & (0 - 1 ^ NX_MSTATUS_MPP_MASK)) | ((s.priv & 0x3) << 11)
  nx_rv64im_csr_write(s.csr, NX_CSR_MSTATUS, new_mstatus)
  nx_rv64im_csr_write(s.csr, NX_CSR_MEPC, mepc_val)
  nx_rv64im_csr_write(s.csr, NX_CSR_MCAUSE, cause)
  s.priv = 3    // the handler runs in M-mode
  // Jump to handler.  Direct mode: low 2 bits of mtvec are 00.
  let mtvec: i64 = nx_rv64im_csr_read(s.csr, NX_CSR_MTVEC)
  s.pc = mtvec & (0 - 4)    // clear low 2 bits
  return NX_HDL_OK
788}
789
790func nx_rv64im_sim_mret(s: *NxRv64imSim) -> i64 {
  let mstatus: i64 = nx_rv64im_csr_read(s.csr, NX_CSR_MSTATUS)
  var new_mstatus: i64 = mstatus
  // MIE <- MPIE
  if (mstatus & NX_MSTATUS_MPIE_BIT) != 0 {
      new_mstatus = new_mstatus | NX_MSTATUS_MIE_BIT
  }
  if (mstatus & NX_MSTATUS_MPIE_BIT) == 0 {
      new_mstatus = new_mstatus & (0 - 1 ^ NX_MSTATUS_MIE_BIT)
  }
  // MPIE <- 1
  new_mstatus = new_mstatus | NX_MSTATUS_MPIE_BIT
  // privilege <- MPP (the saved mode); then MPP <- U (0), per riscv-priv-spec mret.
  let mpp: i64 = (mstatus >> 11) & 0x3
  new_mstatus = new_mstatus & (0 - 1 ^ NX_MSTATUS_MPP_MASK)
  nx_rv64im_csr_write(s.csr, NX_CSR_MSTATUS, new_mstatus)
  s.priv = mpp
  s.pc = nx_rv64im_csr_read(s.csr, NX_CSR_MEPC)
  return NX_HDL_OK
809}
810
811// S-mode trap return -- the S-mode twin of mret (riscv-priv-spec): privilege <- sstatus.SPP (mstatus
812// bit 8: 1=S / 0=U); pc <- sepc; then SPP <- U.  Lets an S-mode kernel return to the trapped context.
813func nx_rv64im_sim_sret(s: *NxRv64imSim) -> i64 {
  let sst: i64 = nx_rv64im_csr_read(s.csr, NX_CSR_MSTATUS)
  let spp: i64 = (sst >> 8) & 1
  let nsst: i64 = sst & (0 - 1 ^ 0x100)        // SPP <- U(0) after sret
  nx_rv64im_csr_write(s.csr, NX_CSR_MSTATUS, nsst)
  s.priv = spp
  s.pc = nx_rv64im_csr_read(s.csr, NX_CSR_SEPC)
  return NX_HDL_OK
821}
822
823// ===== CSR address extraction =================================================
824//
825// SYSTEM-op CSR address is inst[31:20] treated as UNSIGNED 12-bit.
826// Note this is the same bit slice as imm_i but NOT sign-extended.
827
828func nx_rv64im_csr_addr(inst: i64) -> i64 {
  return (inst >> 20) & 0xfff
830}
831
832// ===== Single-cycle step =================================================
833//
834// Executes ONE instruction at PC, advances PC + steps counter, ticks
835// CLINT once.  Returns NX_HDL_OK on success, 0 - <verdict> on halt.
836
837func nx_rv64im_sim_step(s: *NxRv64imSim) -> i64 {
  if s.valid != 1 { return 0 - NX_HDL_BAD_KIND }
  if s.halted == 1 { return 0 - NX_HDL_BAD_KIND }
840
  // Tick CLINT first so MTIME advances per cycle (kernel polls it).
  nx_clint_tick(s.clint)
  nx_rv64im_csr_tick_mcycle(s.csr)
844
  // Per-PC cycle attribution (M2 silicon-feedback foundation).  Bumps
  // the slot indexed by the executing PC; single branch when disabled.
  if s.pc_cycles_on == 1 {
      if s.pc >= s.mem_base {
          let _attr_off: i64 = (s.pc - s.mem_base) >> 2
          if _attr_off < s.pc_cycles_cap {
              s.pc_cycles_buf[_attr_off] = s.pc_cycles_buf[_attr_off] + 1
          }
      }
  }
855
  // Interrupt check.  CLINT asserts MTIP via nx_clint_tick; CPU
  // takes the timer trap if mstatus.MIE && mie.MTIE.  This is the
  // path that fires kernel preemption every TICK_CYCLES.
  if nx_clint_mtip_get(s.clint) == 1 {
      let mstatus: i64 = nx_rv64im_csr_read(s.csr, NX_CSR_MSTATUS)
      let mie:     i64 = nx_rv64im_csr_read(s.csr, NX_CSR_MIE)
      if (mstatus & NX_MSTATUS_MIE_BIT) != 0 {
          if (mie & NX_MIE_MTIE_BIT) != 0 {
              nx_rv64im_sim_take_trap(s, NX_MCAUSE_INT_MACHINE_TIMER, s.pc)
              s.steps = s.steps + 1
              return NX_HDL_OK
          }
      }
  }
870
  // Fetch -- the PC is a VIRTUAL address in S/U-mode under Sv39, so the instruction fetch translates
  // through the page table just like a data access (nx_rv64im_xlate returns identity in M-mode and
  // under Bare, so every physically-addressed test -- M-mode boot, handlers, Bare programs -- is
  // unchanged).  A walk fault on the code page raises an instruction-page-fault (mcause=12) and
  // aborts the fetch, vectoring to mtvec (where the M-mode handler is fetched physically).
  s.xlate_fault = 0
  let fetch_pa: i64 = nx_rv64im_xlate(s, s.pc, NX_ACC_FETCH)   // fetch enforces the X bit
  if s.xlate_fault == 1 {                            // code-page walk fault -> instruction-page-fault trap
      nx_rv64im_csr_write(s.csr, NX_CSR_MTVAL, s.pc)
      nx_rv64im_sim_take_trap(s, NX_MCAUSE_EXC_INSTR_PAGE_FAULT, s.pc)
      s.steps = s.steps + 1
      return NX_HDL_OK
  }
  // C extension: read a halfword; if compressed (low 2 bits != 11) expand it to the 32-bit equivalent + advance pc by
  // 2, else read the full 32-bit word + advance by 4. TRANSPARENT to 32-bit code (low bits 11 -> not compressed).
  // Fetch the code word ONCE and reuse it.  Was two load32 calls per 32-bit instruction (the low
  // 16 bits drive the compressed-check; the full 32 bits are the instruction) -- a redundant
  // memory read every step.  JIT-ladder rung 0: eliminate it.  Behaviour-identical.
  let fetch_word: i64 = nx_rv64im_sim_load32(s, fetch_pa) & 0xffffffff
  let half: i64 = fetch_word & 0xffff
  var inst: i64 = 0
  var instr_len: i64 = 4
  if nx_rvc_is_compressed(half) == 1 { inst = nx_rvc_expand(half); instr_len = 2 }
  else { inst = fetch_word }
  if inst == 0 {
      // All-zero instruction: treat as halt sentinel.  Kernel never
      // emits these; real RV64 would raise illegal-instr.  V1 sim
      // uses this as a clean test-end signal.
      s.halted = 1
      s.halt_code = nx_rv64im_rf_read(s.rf, 10)   // exit code in a0
      return 0
  }
903
  // Decode
  let op_kind: i64 = nx_rv64im_decode_kind(inst)
  let rd:  i64 = nx_rv64im_rd(inst)
  let rs1: i64 = nx_rv64im_rs1(inst)
  let rs2: i64 = nx_rv64im_rs2(inst)
  let funct3: i64 = nx_rv64im_funct3(inst)
  let funct7: i64 = nx_rv64im_funct7(inst)
911
  let rs1_val: i64 = nx_rv64im_rf_read(s.rf, rs1)
  let rs2_val: i64 = nx_rv64im_rf_read(s.rf, rs2)
914
  var next_pc: i64 = s.pc + instr_len   // C ext: +2 for compressed, +4 for 32-bit
916
  if op_kind == NX_RV64IM_OP_LUI {
      nx_rv64im_rf_write(s.rf, rd, nx_rv64im_imm_u(inst))
  }
  if op_kind == NX_RV64IM_OP_AUIPC {
      nx_rv64im_rf_write(s.rf, rd, s.pc + nx_rv64im_imm_u(inst))
  }
  if op_kind == NX_RV64IM_OP_JAL {
      nx_rv64im_rf_write(s.rf, rd, s.pc + instr_len)
      next_pc = s.pc + nx_rv64im_imm_j(inst)
  }
  if op_kind == NX_RV64IM_OP_JALR {
      let tgt: i64 = (rs1_val + nx_rv64im_imm_i(inst)) & (0 - 2)
      nx_rv64im_rf_write(s.rf, rd, s.pc + instr_len)
      next_pc = tgt
  }
  if op_kind == NX_RV64IM_OP_BRANCH {
      var take: i64 = 0
      if funct3 == 0 { if rs1_val == rs2_val { take = 1 } }            // beq
      if funct3 == 1 { if rs1_val != rs2_val { take = 1 } }            // bne
      if funct3 == 4 { if rs1_val <  rs2_val { take = 1 } }            // blt
      if funct3 == 5 { if rs1_val >= rs2_val { take = 1 } }            // bge
      if funct3 == 6 { take = nx_rv64im_ltu(rs1_val, rs2_val) }        // bltu
      if funct3 == 7 {
          let lt: i64 = nx_rv64im_ltu(rs1_val, rs2_val)
          if lt == 0 { take = 1 }                                      // bgeu
      }
      if take == 1 { next_pc = s.pc + nx_rv64im_imm_b(inst) }
  }
  if op_kind == NX_RV64IM_OP_LOAD {
      let vaddr: i64 = rs1_val + nx_rv64im_imm_i(inst)
      s.xlate_fault = 0
      let addr: i64 = nx_rv64im_xlate(s, vaddr, NX_ACC_LOAD)     // Sv39 data translation + R enforcement
      if s.xlate_fault == 1 {                       // walk/perm fault -> load-page-fault trap (instr aborted)
          nx_rv64im_csr_write(s.csr, NX_CSR_MTVAL, vaddr)
          nx_rv64im_sim_take_trap(s, NX_MCAUSE_EXC_LOAD_PAGE_FAULT, s.pc)
          s.steps = s.steps + 1
          return NX_HDL_OK
      }
      if funct3 == 0 { nx_rv64im_rf_write(s.rf, rd, nx_rv64im_sext8(nx_rv64im_sim_load8(s, addr))) }     // lb
      if funct3 == 1 { nx_rv64im_rf_write(s.rf, rd, nx_rv64im_sext16(nx_rv64im_sim_load16(s, addr))) }   // lh
      if funct3 == 2 { nx_rv64im_rf_write(s.rf, rd, nx_rv64im_sext32(nx_rv64im_sim_load32(s, addr))) }   // lw
      if funct3 == 3 { nx_rv64im_rf_write(s.rf, rd, nx_rv64im_sim_load64(s, addr)) }                     // ld
      if funct3 == 4 { nx_rv64im_rf_write(s.rf, rd, nx_rv64im_sim_load8(s, addr) & 0xff) }              // lbu
      if funct3 == 5 { nx_rv64im_rf_write(s.rf, rd, nx_rv64im_sim_load16(s, addr) & 0xffff) }           // lhu
      if funct3 == 6 { nx_rv64im_rf_write(s.rf, rd, nx_rv64im_sim_load32(s, addr) & 0xffffffff) }       // lwu
  }
  if op_kind == NX_RV64IM_OP_STORE {
      let vaddr: i64 = rs1_val + nx_rv64im_imm_s(inst)
      s.xlate_fault = 0
      let addr: i64 = nx_rv64im_xlate(s, vaddr, NX_ACC_STORE)     // Sv39 data translation + W enforcement
      if s.xlate_fault == 1 {                       // walk/perm fault -> store-page-fault trap (instr aborted)
          nx_rv64im_csr_write(s.csr, NX_CSR_MTVAL, vaddr)
          nx_rv64im_sim_take_trap(s, NX_MCAUSE_EXC_STORE_PAGE_FAULT, s.pc)
          s.steps = s.steps + 1
          return NX_HDL_OK
      }
      if funct3 == 0 { nx_rv64im_sim_store8(s, addr, rs2_val) }        // sb (UART THR + general)
      if funct3 == 1 { nx_rv64im_sim_store16(s, addr, rs2_val) }       // sh
      if funct3 == 2 { nx_rv64im_sim_store32(s, addr, rs2_val) }       // sw (+ finisher 0x100000)
      if funct3 == 3 { nx_rv64im_sim_store64(s, addr, rs2_val) }       // sd
  }
  if op_kind == NX_RV64IM_OP_OP {
      let alu_op: i64 = nx_rv64im_sim_alu_select(op_kind, funct3, funct7)
      nx_rv64im_rf_write(s.rf, rd, nx_rv64im_alu_compute(alu_op, rs1_val, rs2_val))
  }
  if op_kind == NX_RV64IM_OP_OP_IMM {
      let alu_op: i64 = nx_rv64im_sim_alu_select(op_kind, funct3, funct7)
      let imm: i64 = nx_rv64im_imm_i(inst)
      // SLLI/SRLI/SRAI shamt is encoded in the immediate's low 6 bits.
      nx_rv64im_rf_write(s.rf, rd, nx_rv64im_alu_compute(alu_op, rs1_val, imm))
  }
  if op_kind == NX_RV64IM_OP_OP_32 {
      let alu_op: i64 = nx_rv64im_sim_alu_select(op_kind, funct3, funct7)
      nx_rv64im_rf_write(s.rf, rd, nx_rv64im_alu_compute(alu_op, rs1_val, rs2_val))
  }
  // M-extension R-type ops (mul/div/rem family).  The decoder gives
  // them their own op_kind (OP_M_MUL / OP_M_DIV / *_32); alu_select
  // keys on the base OP / OP_32 kind + funct7=0x01, so route through
  // those.  Without these four cases the sim silently skipped every
  // multiply/divide/remainder and left rd unwritten.
  if op_kind == NX_RV64IM_OP_M_MUL {
      let alu_op: i64 = nx_rv64im_sim_alu_select(NX_RV64IM_OP_OP, funct3, funct7)
      nx_rv64im_rf_write(s.rf, rd, nx_rv64im_alu_compute(alu_op, rs1_val, rs2_val))
  }
  if op_kind == NX_RV64IM_OP_M_DIV {
      let alu_op: i64 = nx_rv64im_sim_alu_select(NX_RV64IM_OP_OP, funct3, funct7)
      nx_rv64im_rf_write(s.rf, rd, nx_rv64im_alu_compute(alu_op, rs1_val, rs2_val))
  }
  if op_kind == NX_RV64IM_OP_M_MUL_32 {
      let alu_op: i64 = nx_rv64im_sim_alu_select(NX_RV64IM_OP_OP_32, funct3, funct7)
      nx_rv64im_rf_write(s.rf, rd, nx_rv64im_alu_compute(alu_op, rs1_val, rs2_val))
  }
  if op_kind == NX_RV64IM_OP_M_DIV_32 {
      let alu_op: i64 = nx_rv64im_sim_alu_select(NX_RV64IM_OP_OP_32, funct3, funct7)
      nx_rv64im_rf_write(s.rf, rd, nx_rv64im_alu_compute(alu_op, rs1_val, rs2_val))
  }
  if op_kind == NX_RV64IM_OP_OP_IMM_32 {
      let alu_op: i64 = nx_rv64im_sim_alu_select(op_kind, funct3, funct7)
      nx_rv64im_rf_write(s.rf, rd, nx_rv64im_alu_compute(alu_op, rs1_val, nx_rv64im_imm_i(inst)))
  }
  if op_kind == NX_RV64IM_OP_FENCE {
      // No-op in single-cycle in-order sim (no memory reordering).
  }
  if op_kind == NX_RV64IM_OP_SYSTEM {
      let csr_addr: i64 = nx_rv64im_csr_addr(inst)
1022
      if funct3 == 0 {
          // ecall / ebreak / mret -- distinguished by inst[31:20].
          // Per spec table 3.4 / 9.1:
          //   ecall  -> imm[11:0] = 000000000000
          //   ebreak -> imm[11:0] = 000000000001
          //   mret   -> imm[11:0] = 001100000010 (0x302)
          if csr_addr == 0x000 {
              // ecall -- the cause depends on the originating privilege (8=U, 9=S, 11=M); the
              // handler at mtvec is the kernel's syscall dispatcher.
              var ecause: i64 = NX_MCAUSE_EXC_ECALL_M
              if s.priv == 0 { ecause = NX_MCAUSE_EXC_ECALL_U }
              if s.priv == 1 { ecause = NX_MCAUSE_EXC_ECALL_S }
              nx_rv64im_sim_take_trap(s, ecause, s.pc)
              s.steps = s.steps + 1
              return NX_HDL_OK
          }
          if csr_addr == 0x001 {
              // ebreak -- treat as halt for the V1 sim (kernel
              // never executes ebreak in normal flow).
              s.halted = 1
              s.halt_code = nx_rv64im_rf_read(s.rf, 10)
              return 0
          }
          if csr_addr == 0x302 {
              // mret -- pc <- mepc, restore MIE from MPIE.
              nx_rv64im_sim_mret(s)
              s.steps = s.steps + 1
              return NX_HDL_OK
          }
          if csr_addr == 0x102 {
              // sret -- S-mode trap return: pc <- sepc, privilege <- sstatus.SPP.
              nx_rv64im_sim_sret(s)
              s.steps = s.steps + 1
              return NX_HDL_OK
          }
          // Unrecognised SYSTEM/funct3=0 op -- illegal.
          nx_rv64im_sim_take_trap(s, NX_MCAUSE_EXC_ILLEGAL_INSTR, s.pc)
          s.steps = s.steps + 1
          return NX_HDL_OK
      }
1063
      // csrr* family.  Build the "operand" -- register value for
      // funct3 = 1/2/3; zero-extended 5-bit immediate for 5/6/7.
      var operand: i64 = 0
      if funct3 == 1 { operand = rs1_val }
      if funct3 == 2 { operand = rs1_val }
      if funct3 == 3 { operand = rs1_val }
      if funct3 == 5 { operand = rs1 & 0x1f }       // csrrwi uimm = rs1 field
      if funct3 == 6 { operand = rs1 & 0x1f }
      if funct3 == 7 { operand = rs1 & 0x1f }
1073
      let old_out: *i64 = (sys_mmap(8)) as *i64
      old_out[0] = 0
      let cur: i64 = nx_rv64im_csr_read(s.csr, csr_addr)
1077
      if funct3 == 1 { // csrrw
          nx_rv64im_csr_swap(s.csr, csr_addr, operand, old_out)
          nx_rv64im_rf_write(s.rf, rd, old_out[0])
      }
      if funct3 == 5 { // csrrwi
          nx_rv64im_csr_swap(s.csr, csr_addr, operand, old_out)
          nx_rv64im_rf_write(s.rf, rd, old_out[0])
      }
      if funct3 == 2 { // csrrs -- set bits indicated by operand
          nx_rv64im_csr_write(s.csr, csr_addr, cur | operand)
          nx_rv64im_rf_write(s.rf, rd, cur)
      }
      if funct3 == 6 { // csrrsi
          nx_rv64im_csr_write(s.csr, csr_addr, cur | operand)
          nx_rv64im_rf_write(s.rf, rd, cur)
      }
      if funct3 == 3 { // csrrc -- clear bits indicated by operand
          nx_rv64im_csr_write(s.csr, csr_addr, cur & (0 - 1 ^ operand))
          nx_rv64im_rf_write(s.rf, rd, cur)
      }
      if funct3 == 7 { // csrrci
          nx_rv64im_csr_write(s.csr, csr_addr, cur & (0 - 1 ^ operand))
          nx_rv64im_rf_write(s.rf, rd, cur)
      }
  }
  if op_kind == NX_RV64IM_OP_AMO {
      // RV64A atomics: lr/sc + amo* (F107h).  funct5 = inst[31:27] selects the op; funct3 = 2 (.w,
      // 32-bit) or 3 (.d, 64-bit).  The address is rs1 EXACTLY (no immediate offset, per spec).
      let funct5: i64 = (inst >> 27) & 0x1f
      var is_d: i64 = 0
      if funct3 == 3 { is_d = 1 }
      let amo_va: i64 = rs1_val
      s.xlate_fault = 0
      let amo_pa: i64 = nx_rv64im_xlate(s, amo_va, NX_ACC_STORE)   // amo needs R+W; enforce W (identity in M/Bare)
      if s.xlate_fault == 1 {
          nx_rv64im_csr_write(s.csr, NX_CSR_MTVAL, amo_va)
          nx_rv64im_sim_take_trap(s, NX_MCAUSE_EXC_STORE_PAGE_FAULT, s.pc)
          s.steps = s.steps + 1
          return NX_HDL_OK
      }
      // old value: sign-extended 32-bit for .w (so rd + signed compares are correct); full 64 for .d.
      var amo_old: i64 = 0
      if is_d == 1 { amo_old = nx_rv64im_sim_load64(s, amo_pa) }
      if is_d == 0 { amo_old = nx_rv64im_sext32(nx_rv64im_sim_load32(s, amo_pa)) }
1122
      if funct5 == 0x02 {
          // lr.w/d: record the reservation; rd <- old.
          s.resv_addr = amo_pa
          s.resv_valid = 1
          nx_rv64im_rf_write(s.rf, rd, amo_old)
      }
      if funct5 == 0x03 {
          // sc.w/d: success iff the reservation is still valid AND matches this address.
          var sc_ok: i64 = 0
          if s.resv_valid == 1 { if s.resv_addr == amo_pa { sc_ok = 1 } }
          if sc_ok == 1 {
              if is_d == 1 { nx_rv64im_sim_store64(s, amo_pa, rs2_val) }
              if is_d == 0 { nx_rv64im_sim_store32(s, amo_pa, rs2_val & 0xffffffff) }
              nx_rv64im_rf_write(s.rf, rd, 0)      // 0 = success
          }
          if sc_ok == 0 { nx_rv64im_rf_write(s.rf, rd, 1) }   // 1 = failure
          s.resv_valid = 0                          // sc always clears the reservation
      }
      // amo* arithmetic/logical/min-max family (every funct5 except lr=0x02 / sc=0x03).
      if funct5 != 0x02 { if funct5 != 0x03 {
          // second operand: full 64 for .d; sign-extended low-32 for .w.
          var amo_src: i64 = rs2_val
          if is_d == 0 { amo_src = nx_rv64im_sext32(rs2_val & 0xffffffff) }
          var amo_new: i64 = amo_old
          if funct5 == 0x01 { amo_new = amo_src }                 // amoswap
          if funct5 == 0x00 { amo_new = amo_old + amo_src }       // amoadd
          if funct5 == 0x04 { amo_new = amo_old ^ amo_src }       // amoxor
          if funct5 == 0x0c { amo_new = amo_old & amo_src }       // amoand
          if funct5 == 0x08 { amo_new = amo_old | amo_src }       // amoor
          if funct5 == 0x10 { if amo_old < amo_src { amo_new = amo_old } if amo_old >= amo_src { amo_new = amo_src } }   // amomin  (signed)
          if funct5 == 0x14 { if amo_old < amo_src { amo_new = amo_src } if amo_old >= amo_src { amo_new = amo_old } }   // amomax  (signed)
          if funct5 == 0x18 {                                     // amominu (unsigned)
              var uo: i64 = amo_old
              var us: i64 = amo_src
              if is_d == 0 { uo = amo_old & 0xffffffff; us = amo_src & 0xffffffff }
              if nx_rv64im_ltu(uo, us) == 1 { amo_new = amo_old }
              if nx_rv64im_ltu(uo, us) == 0 { amo_new = amo_src }
          }
          if funct5 == 0x1c {                                     // amomaxu (unsigned)
              var uo2: i64 = amo_old
              var us2: i64 = amo_src
              if is_d == 0 { uo2 = amo_old & 0xffffffff; us2 = amo_src & 0xffffffff }
              if nx_rv64im_ltu(uo2, us2) == 1 { amo_new = amo_src }
              if nx_rv64im_ltu(uo2, us2) == 0 { amo_new = amo_old }
          }
          s.resv_valid = 0                                        // an amo writes the line -> breaks any reservation
          if is_d == 1 { nx_rv64im_sim_store64(s, amo_pa, amo_new) }
          if is_d == 0 { nx_rv64im_sim_store32(s, amo_pa, amo_new & 0xffffffff) }
          nx_rv64im_rf_write(s.rf, rd, amo_old)
      } }
  }
  if op_kind == NX_RV64IM_OP_INVALID {
      // Illegal instruction.  Real kernel: trap with mcause=2.
      // V1 sim: halt loud.
      s.halted = 1
      s.halt_code = 0 - 2
      return 0 - NX_HDL_BAD_KIND
  }
1181
  s.pc = next_pc
  s.steps = s.steps + 1
  return NX_HDL_OK
1185}
1186
1187// ===== Run loop =================================================
1188//
1189// Steps until halted or max_steps reached (guard against infinite
1190// loops in misbehaving test programs).  Returns the final exit code
1191// from the halt path.
1192
1193func nx_rv64im_sim_run(s: *NxRv64imSim, max_steps: i64) -> i64 {
  var i: i64 = 0
  while i < max_steps {
      if s.halted == 1 { return s.halt_code }
      nx_rv64im_sim_step(s)
      i = i + 1
  }
  return 0 - 1   // exceeded max_steps; not halted cleanly
1201}
1202
1203// ===== Deterministic snapshot / restore (F107i, 2026-07-19) =================================================
1204//
1205// Save + restore the ARCHITECTURAL machine state (32 GPRs + pc/priv/reservation/step-counters + all of RAM)
1206// to/from a caller buffer.  Because the sovereign emulator is bit-DETERMINISTIC (no floating point, no host
1207// nondeterminism -- the determinism exceed bet), a restore is EXACT: continuing from a restored snapshot is
1208// byte-identical to never having stopped.  This is what QEMU needs icount + savevm to approximate; here it
1209// is free.  (CSR/CLINT/UART device state is the documented follow-on rung; this covers register+memory-
1210// defined behaviour -- the common case.)  Buffer must be >= NX_RV64IM_SNAP_HDR + mem_size bytes.
1211const NX_RV64IM_SNAP_HDR: i64 = 312    // (7 scalars + 32 GPRs) * 8 bytes
1212
1213func nx_snap_wr64(b: *u8, off: i64, v: i64) -> i64 { var i: i64=0; while i<8 { b[off+i]=((v>>(i*8))&0xff) as u8; i=i+1 } return 0 }
1214func nx_snap_rd64(b: *u8, off: i64) -> i64 { var v: i64=0; var i: i64=0; while i<8 { v=v|((b[off+i] as i64)<<(i*8)); i=i+1 } return v }
1215
1216func nx_rv64im_sim_snapshot(s: *NxRv64imSim, buf: *u8) -> i64 {
  if s.valid != 1 { return 0 - NX_HDL_BAD_KIND }
  nx_snap_wr64(buf, 0,  s.pc)
  nx_snap_wr64(buf, 8,  s.priv)
  nx_snap_wr64(buf, 16, s.halted)
  nx_snap_wr64(buf, 24, s.halt_code)
  nx_snap_wr64(buf, 32, s.steps)
  nx_snap_wr64(buf, 40, s.resv_addr)
  nx_snap_wr64(buf, 48, s.resv_valid)
  var i: i64 = 0
  while i < 32 { nx_snap_wr64(buf, 56 + i*8, nx_rv64im_rf_read(s.rf, i)); i = i + 1 }
  var m: i64 = 0
  while m < s.mem_size { buf[NX_RV64IM_SNAP_HDR + m] = s.mem_buf[m]; m = m + 1 }
  return NX_RV64IM_SNAP_HDR + s.mem_size
1230}
1231
1232func nx_rv64im_sim_restore(s: *NxRv64imSim, buf: *u8) -> i64 {
  if s.valid != 1 { return 0 - NX_HDL_BAD_KIND }
  s.pc         = nx_snap_rd64(buf, 0)
  s.priv       = nx_snap_rd64(buf, 8)
  s.halted     = nx_snap_rd64(buf, 16)
  s.halt_code  = nx_snap_rd64(buf, 24)
  s.steps      = nx_snap_rd64(buf, 32)
  s.resv_addr  = nx_snap_rd64(buf, 40)
  s.resv_valid = nx_snap_rd64(buf, 48)
  var i: i64 = 0
  while i < 32 { nx_rv64im_rf_write(s.rf, i, nx_snap_rd64(buf, 56 + i*8)); i = i + 1 }
  var m: i64 = 0
  while m < s.mem_size { s.mem_buf[m] = buf[NX_RV64IM_SNAP_HDR + m]; m = m + 1 }
  return NX_HDL_OK
1246}
rv64im_min_sim.nx source

`rv64im_min_sim.nx` source
