feat(tvix/eval): implement optional runtime tracing r/4533

This adds a `disassembler` feature to the crate configuration that
traces the operations executed and the state of the stack at runtime.

This can be enabled by compiling with `--feature disassembler`.

This will also gain a more sensible layout of code slices eventually.

Change-Id: I34c15e1cd346ecc4362b5afba6bf82dd49359d20
Reviewed-on: https://cl.tvl.fyi/c/depot/+/6193
Tested-by: BuildkiteCI
Reviewed-by: sterni <sternenseemann@systemli.org>

5 files changed, 67 insertions, 1 deletions

diff --git a/tvix/eval/Cargo.lock b/tvix/eval/Cargo.lock
index ecd0f05e409d..38fbb539309e 100644
--- a/tvix/eval/Cargo.lock
+++ b/tvix/eval/Cargo.lock
@@ -778,6 +778,15 @@ dependencies = [
 ]
 
 [[package]]
+name = "tabwriter"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36205cfc997faadcc4b0b87aaef3fbedafe20d38d4959a7ca6ff803564051111"
+dependencies = [
+ "unicode-width",
+]
+
+[[package]]
 name = "test-generator"
 version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ -844,6 +853,7 @@ dependencies = [
  "rnix",
  "rustyline",
  "smol_str",
+ "tabwriter",
  "test-generator",
 ]
 
diff --git a/tvix/eval/Cargo.toml b/tvix/eval/Cargo.toml
index 836b5deed10b..b0ccabed2e02 100644
--- a/tvix/eval/Cargo.toml
+++ b/tvix/eval/Cargo.toml
@@ -11,6 +11,7 @@ smol_str = "0.1"
 rustyline = "10.0.0"
 dirs = "4.0.0"
 path-clean = "0.1"
+tabwriter = { version = "1.2", optional = true }
 
 [dev-dependencies]
 criterion = "0.3.6"
@@ -21,6 +22,9 @@ test-generator = "0.3.0"
 # Nix implementation (at version 2.3) against Tvix.
 nix_tests = []
 
+# Enables printing compiled code and tracing the stack state at runtime.
+disassembler = ["dep:tabwriter"]
+
 [[bench]]
 name = "eval"
 harness = false
diff --git a/tvix/eval/src/disassembler.rs b/tvix/eval/src/disassembler.rs
new file mode 100644
index 000000000000..98a6dac9afc4
--- /dev/null
+++ b/tvix/eval/src/disassembler.rs
@@ -0,0 +1,37 @@
+//! Implements methods for disassembling and printing a representation
+//! of compiled code, as well as tracing the runtime stack during
+//! execution.
+use std::io::{Stderr, Write};
+use tabwriter::TabWriter;
+
+use crate::opcode::OpCode;
+use crate::value::Value;
+
+/// Helper struct to trace runtime values and automatically flush the
+/// output after the value is dropped (i.e. in both success and
+/// failure exits from the VM).
+pub struct Tracer(TabWriter<Stderr>);
+
+impl Tracer {
+    pub fn new() -> Self {
+        let mut tw = TabWriter::new(std::io::stderr());
+        write!(&mut tw, "=== runtime trace ===\n").ok();
+        Tracer(tw)
+    }
+
+    pub fn trace(&mut self, op: &OpCode, ip: usize, stack: &[Value]) {
+        write!(&mut self.0, "{:04} {:?}\t[ ", ip, op).ok();
+
+        for val in stack {
+            write!(&mut self.0, "{} ", val).ok();
+        }
+
+        write!(&mut self.0, "]\n").ok();
+    }
+}
+
+impl Drop for Tracer {
+    fn drop(&mut self) {
+        self.0.flush().ok();
+    }
+}
diff --git a/tvix/eval/src/lib.rs b/tvix/eval/src/lib.rs
index ba037d6c8a0a..f796034ded98 100644
--- a/tvix/eval/src/lib.rs
+++ b/tvix/eval/src/lib.rs
@@ -7,6 +7,9 @@ mod value;
 mod vm;
 mod warnings;
 
+#[cfg(feature = "disassembler")]
+mod disassembler;
+
 #[cfg(test)]
 mod tests;
 
diff --git a/tvix/eval/src/vm.rs b/tvix/eval/src/vm.rs
index 8ee17258602e..0d0249e3f6c0 100644
--- a/tvix/eval/src/vm.rs
+++ b/tvix/eval/src/vm.rs
@@ -10,6 +10,9 @@ use crate::{
     value::{NixAttrs, NixList, Value},
 };
 
+#[cfg(feature = "disassembler")]
+use crate::disassembler::Tracer;
+
 pub struct VM {
     ip: usize,
     chunk: Chunk,
@@ -88,8 +91,12 @@ impl VM {
     }
 
     fn run(&mut self) -> EvalResult<Value> {
+        #[cfg(feature = "disassembler")]
+        let mut tracer = Tracer::new();
+
         loop {
-            match self.inc_ip() {
+            let op = self.inc_ip();
+            match op {
                 OpCode::OpConstant(idx) => {
                     let c = self.chunk.constant(idx).clone();
                     self.push(c);
@@ -261,6 +268,11 @@ impl VM {
                 }
             }
 
+            #[cfg(feature = "disassembler")]
+            {
+                tracer.trace(&op, self.ip, &self.stack);
+            }
+
             if self.ip == self.chunk.code.len() {
                 return Ok(self.pop());
             }