feat: allow enabling debug mode via ExecutionOptions (#1316)

air/src/options.rs

@@ -151,6 +151,7 @@ pub struct ExecutionOptions {
     max_cycles: u32,
     expected_cycles: u32,
     enable_tracing: bool,
+    enable_debugging: bool,
 }
 
 impl Default for ExecutionOptions {
@@ -159,6 +160,7 @@ impl Default for ExecutionOptions {
             max_cycles: u32::MAX,
             expected_cycles: MIN_TRACE_LEN as u32,
             enable_tracing: false,
+            enable_debugging: false,
         }
     }
 }
@@ -191,30 +193,51 @@ impl ExecutionOptions {
             max_cycles,
             expected_cycles,
             enable_tracing,
+            enable_debugging: false,
         })
     }
 
-    /// Enables Host to handle the `tracing` instructions.
+    /// Enables execution of the `trace` instructions.
     pub fn with_tracing(mut self) -> Self {
         self.enable_tracing = true;
         self
     }
 
+    /// Enables execution of programs in debug mode.
+    ///
+    /// In debug mode the VM does the following:
+    /// - Executes `debug` instructions (these are ignored in regular mode).
+    /// - Records additional info about program execution (e.g., keeps track of stack state at
+    ///   every cycle of the VM) which enables stepping through the program forward and backward.
+    pub fn with_debugging(mut self) -> Self {
+        self.enable_debugging = true;
+        self
+    }
+
     // PUBLIC ACCESSORS
     // --------------------------------------------------------------------------------------------
 
-    /// Returns maximum number of cycles
+    /// Returns maximum number of cycles a program is allowed to execute for.
     pub fn max_cycles(&self) -> u32 {
         self.max_cycles
     }
 
-    /// Returns number of the expected cycles
+    /// Returns the number of cycles a program is expected to take.
+    ///
+    /// This will serve as a hint to the VM for how much memory to allocate for a program's
+    /// execution trace and may result in performance improvements when the number of expected
+    /// cycles is equal to the number of actual cycles.
     pub fn expected_cycles(&self) -> u32 {
         self.expected_cycles
     }
 
-    /// Returns a flag indicating whether the Host should handle `trace` instructions
+    /// Returns a flag indicating whether the VM should execute `trace` instructions.
     pub fn enable_tracing(&self) -> bool {
         self.enable_tracing
     }
+
+    /// Returns a flag indicating whether the VM should execute a program in debug mode.
+    pub fn enable_debugging(&self) -> bool {
+        self.enable_debugging
+    }
 }

processor/src/host/mod.rs

@@ -82,7 +82,7 @@ pub trait Host {
         Ok(HostResponse::None)
     }
 
-    /// Handles the trace emmited from the VM.
+    /// Handles the trace emitted from the VM.
     fn on_trace<S: ProcessState>(
         &mut self,
         process: &S,

processor/src/lib.rs

@@ -184,7 +184,7 @@ where
         host: H,
         execution_options: ExecutionOptions,
     ) -> Self {
-        Self::initialize(kernel, stack_inputs, host, false, execution_options)
+        Self::initialize(kernel, stack_inputs, host, execution_options)
     }
 
     /// Creates a new process with provided inputs and debug options enabled.
@@ -193,18 +193,17 @@ where
             kernel,
             stack_inputs,
             host,
-            true,
-            ExecutionOptions::default().with_tracing(),
+            ExecutionOptions::default().with_tracing().with_debugging(),
         )
     }
 
     fn initialize(
         kernel: Kernel,
         stack: StackInputs,
         host: H,
-        in_debug_mode: bool,
         execution_options: ExecutionOptions,
     ) -> Self {
+        let in_debug_mode = execution_options.enable_debugging();
         Self {
             system: System::new(execution_options.expected_cycles() as usize),
             decoder: Decoder::new(in_debug_mode),