From f6dbb3225d18f606f4dee0a5bdf39aa9c8eab2c3 Mon Sep 17 00:00:00 2001
From: Bobbin Threadbare <bobbinth@protonmail.com>
Date: Thu, 25 Apr 2024 15:12:39 -0700
Subject: [PATCH 1/2] feat: allow enabling debug mode via ExecutionOptions

---
 air/src/options.rs        | 31 +++++++++++++++++++++++++++----
 processor/src/host/mod.rs |  2 +-
 processor/src/lib.rs      |  7 +++----
 3 files changed, 31 insertions(+), 9 deletions(-)

diff --git a/air/src/options.rs b/air/src/options.rs
index 1308060bf2..5f97172404 100644
--- a/air/src/options.rs
+++ b/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
+    }
 }
diff --git a/processor/src/host/mod.rs b/processor/src/host/mod.rs
index 7886563aeb..5206a8e053 100644
--- a/processor/src/host/mod.rs
+++ b/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,
diff --git a/processor/src/lib.rs b/processor/src/lib.rs
index d885436c61..86529a2ffd 100644
--- a/processor/src/lib.rs
+++ b/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,8 +193,7 @@ where
             kernel,
             stack_inputs,
             host,
-            true,
-            ExecutionOptions::default().with_tracing(),
+            ExecutionOptions::default().with_tracing().with_debugging(),
         )
     }
 
@@ -202,9 +201,9 @@ where
         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),

From b6829c8e9ec5cababa50358c0a7e14cb24d67001 Mon Sep 17 00:00:00 2001
From: Bobbin Threadbare <bobbinth@protonmail.com>
Date: Thu, 25 Apr 2024 15:19:32 -0700
Subject: [PATCH 2/2] chore: pacify rustfmt

---
 air/src/options.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/air/src/options.rs b/air/src/options.rs
index 5f97172404..51f01a1260 100644
--- a/air/src/options.rs
+++ b/air/src/options.rs
@@ -204,7 +204,7 @@ impl ExecutionOptions {
     }
 
     /// 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
@@ -223,7 +223,7 @@ impl ExecutionOptions {
     }
 
     /// 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.