Debug mode via cli option

CHANGELOG.md

@@ -9,6 +9,7 @@
 - Added `miden_core::utils::sync::racy_lock` module (#1463).
 - Updated `miden_core::utils` to re-export `std::sync::LazyLock` and `racy_lock::RacyLock as LazyLock` for std and no_std environments, respectively (#1463).
 - Made the undocumented behavior of the VM with regard to undefined behavior of u32 operations, stricter (#1480)
+- Debug instructions can be enabled in the cli `run` command using `--debug` flag
 
 #### Fixes
 
@@ -25,7 +26,6 @@
 
 - Added `PartialEq`, `Eq`, `Serialize` and `Deserialize` to `AdviceMap` and `AdviceInputs` structs (#1494).
 
-
 ## 0.10.5 (2024-08-21)
 
 #### Enhancements

Makefile

@@ -65,6 +65,10 @@ test-skip-proptests: ## Runs all tests, except property-based tests
 test-loom: ## Runs all loom-based tests
 	RUSTFLAGS="--cfg loom" cargo nextest run --cargo-profile test-release --features testing -E 'test(#*loom)'
 
+.PHONY: test-package
+test-package: ## Tests specific package: make test-package package=miden-vm
+	$(DEBUG_ASSERTIONS) cargo nextest run --cargo-profile test-release --features testing -p $(package)
+
 # --- checking ------------------------------------------------------------------------------------
 
 .PHONY: check

air/src/options.rs

@@ -192,6 +192,7 @@ impl ExecutionOptions {
         max_cycles: Option<u32>,
         expected_cycles: u32,
         enable_tracing: bool,
+        enable_debugging: bool,
     ) -> Result<Self, ExecutionOptionsError> {
         let max_cycles = max_cycles.unwrap_or(u32::MAX);
         if max_cycles < MIN_TRACE_LEN as u32 {
@@ -209,7 +210,7 @@ impl ExecutionOptions {
             max_cycles,
             expected_cycles,
             enable_tracing,
-            enable_debugging: false,
+            enable_debugging,
         })
     }
 

docs/src/intro/usage.md

@@ -38,7 +38,7 @@ Internally, Miden VM uses [rayon](https://github.com/rayon-rs/rayon) for paralle
 
 ### GPU acceleration
 
-Miden VM proof generation can be accelerated via GPUs. Currently, GPU acceleration is enabled only on Apple silicon hardware (via [Metal](<https://en.wikipedia.org/wiki/Metal_(API)>)). To compile Miden VM with Metal acceleration enabled, you can run the following command:
+Miden VM proof generation can be accelerated via GPUs. Currently, GPU acceleration is enabled only on Apple Silicon hardware (via [Metal](<https://en.wikipedia.org/wiki/Metal_(API)>)). To compile Miden VM with Metal acceleration enabled, you can run the following command:
 
 ```
 make exec-metal
@@ -85,7 +85,7 @@ Currently, Miden VM can be executed with the following subcommands:
 - `debug` - this will instantiate a [Miden debugger](../tools/debugger.md) against the specified Miden assembly program and inputs.
 - `analyze` - this will run a Miden assembly program against specific inputs and will output stats about its execution.
 - `repl` - this will initiate the [Miden REPL](../tools/repl.md) tool.
-- `example` - this will execute a Miden assembly example program, generate a STARK proof of execution and verify it. Currently it is possible to run `blake3` and `fibonacci` examples.
+- `example` - this will execute a Miden assembly example program, generate a STARK proof of execution and verify it. Currently, it is possible to run `blake3` and `fibonacci` examples.
 
 All of the above subcommands require various parameters to be provided. To get more detailed help on what is needed for a given subcommand, you can run the following:
 
@@ -111,6 +111,14 @@ MIDEN_LOG=trace ./target/optimized/miden [subcommand] [parameters]
 
 If the level is not specified, `warn` level is set as default.
 
+#### Enable Debugging features
+
+You can use the run command with `--debug` parameter to enable debugging with the [debug instruction](../user_docs/assembly/debugging.md) such as `debug.stack`:
+
+```shell
+./target/optimized/miden run -a [path_to.masm] --debug
+```
+
 ### Inputs
 
 As described [here](https://0xpolygonmiden.github.io/miden-vm/intro/overview.html#inputs-and-outputs) the Miden VM can consume public and secret inputs.
@@ -133,16 +141,28 @@ After a program finishes executing, the elements that remain on the stack become
 
 In the `miden/examples/fib` directory, we provide a very simple Fibonacci calculator example. This example computes the 1001st term of the Fibonacci sequence. You can execute this example on Miden VM like so:
 
-```
+```shell
 ./target/optimized/miden run -a miden/examples/fib/fib.masm -n 1
 ```
 
+### Capturing Output
+
 This will run the example code to completion and will output the top element remaining on the stack.
 
 If you want the output of the program in a file, you can use the `--output` or `-o` flag and specify the path to the output file. For example:
 
-```
+```shell
 ./target/optimized/miden run -a miden/examples/fib/fib.masm -o fib.out
 ```
 
 This will dump the output of the program into the `fib.out` file. The output file will contain the state of the stack at the end of the program execution.
+
+### Running with debug instruction enabled
+
+Inside `miden/examples/fib/fib.masm`, insert `debug.stack` instruction anywhere between `begin` and `end`. Then run:
+
+```shell
+./target/optimized/miden run -a miden/examples/fib/fib.masm -n 1 --debug
+```
+
+You should see output similar to "Stack state before step ..."

miden/src/cli/data.rs

@@ -42,6 +42,15 @@ impl Debug {
     }
 }
 
+impl From<bool> for Debug {
+    fn from(value: bool) -> Self {
+        match value {
+            true => Debug::On,
+            false => Debug::Off,
+        }
+    }
+}
+
 // MERKLE DATA
 // ================================================================================================
 
@@ -627,3 +636,20 @@ mod test {
         assert!(merkle_store.is_some());
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_debug_from_true() {
+        let debug_mode: Debug = true.into(); // true.into() will also test Debug.from(true)
+        assert!(matches!(debug_mode, Debug::On));
+    }
+
+    #[test]
+    fn test_debug_from_false() {
+        let debug_mode: Debug = false.into(); // false.into() will also test Debug.from(false)
+        assert!(matches!(debug_mode, Debug::Off));
+    }
+}

miden/src/cli/prove.rs

@@ -61,8 +61,12 @@ pub struct ProveCmd {
 
 impl ProveCmd {
     pub fn get_proof_options(&self) -> Result<ProvingOptions, ExecutionOptionsError> {
-        let exec_options =
-            ExecutionOptions::new(Some(self.max_cycles), self.expected_cycles, self.tracing)?;
+        let exec_options = ExecutionOptions::new(
+            Some(self.max_cycles),
+            self.expected_cycles,
+            self.tracing,
+            false,
+        )?;
         Ok(match self.security.as_str() {
             "96bits" => {
                 if self.rpx {

miden/src/cli/run.rs

@@ -40,6 +40,10 @@ pub struct RunCmd {
     /// Enable tracing to monitor execution of the VM
     #[clap(short = 't', long = "tracing")]
     tracing: bool,
+
+    /// Enable debug instructions
+    #[clap(short = 'd', long = "debug")]
+    debug: bool,
 }
 
 impl RunCmd {
@@ -106,16 +110,19 @@ fn run_program(params: &RunCmd) -> Result<(ExecutionTrace, [u8; 32]), Report> {
     let libraries = Libraries::new(&params.library_paths)?;
 
     // load program from file and compile
-    let program =
-        ProgramFile::read(&params.assembly_file)?.compile(&Debug::Off, &libraries.libraries)?;
+    let program = ProgramFile::read(&params.assembly_file)?
+        .compile(&Debug::from(params.debug), &libraries.libraries)?;
 
     // load input data from file
     let input_data = InputFile::read(&params.input_file, &params.assembly_file)?;
 
-    // get execution options
-    let execution_options =
-        ExecutionOptions::new(Some(params.max_cycles), params.expected_cycles, params.tracing)
-            .into_diagnostic()?;
+    let execution_options = ExecutionOptions::new(
+        Some(params.max_cycles),
+        params.expected_cycles,
+        params.tracing,
+        params.debug,
+    )
+    .into_diagnostic()?;
 
     // fetch the stack and program inputs from the arguments
     let stack_inputs = input_data.parse_stack_inputs().map_err(Report::msg)?;

miden/src/examples/mod.rs

@@ -76,8 +76,12 @@ pub enum ExampleType {
 
 impl ExampleOptions {
     pub fn get_proof_options(&self) -> Result<ProvingOptions, ExecutionOptionsError> {
-        let exec_options =
-            ExecutionOptions::new(Some(self.max_cycles), self.expected_cycles, self.tracing)?;
+        let exec_options = ExecutionOptions::new(
+            Some(self.max_cycles),
+            self.expected_cycles,
+            self.tracing,
+            false,
+        )?;
         Ok(match self.security.as_str() {
             "96bits" => {
                 if self.rpx {

miden/tests/integration/operations/decorators/events.rs

@@ -1,5 +1,6 @@
 use assembly::Assembler;
 use processor::{ExecutionOptions, Program};
+use prover::StackInputs;
 
 use super::TestHost;
 
@@ -16,7 +17,8 @@ fn test_event_handling() {
     // compile and execute program
     let program: Program = Assembler::default().assemble_program(source).unwrap();
     let mut host = TestHost::default();
-    processor::execute(&program, Default::default(), &mut host, Default::default()).unwrap();
+    processor::execute(&program, StackInputs::default(), &mut host, ExecutionOptions::default())
+        .unwrap();
 
     // make sure events were handled correctly
     let expected = vec![1, 2];
@@ -38,18 +40,64 @@ fn test_trace_handling() {
     let mut host = TestHost::default();
 
     // execute program with disabled tracing
-    processor::execute(&program, Default::default(), &mut host, Default::default()).unwrap();
+    processor::execute(&program, StackInputs::default(), &mut host, ExecutionOptions::default())
+        .unwrap();
     let expected = Vec::<u32>::new();
     assert_eq!(host.trace_handler, expected);
 
     // execute program with enabled tracing
     processor::execute(
         &program,
-        Default::default(),
+        StackInputs::default(),
         &mut host,
         ExecutionOptions::default().with_tracing(),
     )
     .unwrap();
     let expected = vec![1, 2];
     assert_eq!(host.trace_handler, expected);
 }
+
+#[test]
+fn test_debug_with_debugging() {
+    let source: &str = "\
+    begin
+        push.1
+        debug.stack
+        debug.mem
+    end";
+
+    // compile and execute program
+    let program: Program = Assembler::default().with_debug_mode(true).assemble_program(source).unwrap();
+    let mut host = TestHost::default();
+    processor::execute(
+        &program,
+        StackInputs::default(),
+        &mut host,
+        ExecutionOptions::default().with_debugging(),
+    )
+    .unwrap();
+
+    // Expect to see the debug.stack and debug.mem commands
+    let expected = vec!["stack", "mem"];
+    assert_eq!(host.debug_handler, expected);
+}
+
+#[test]
+fn test_debug_without_debugging() {
+    let source: &str = "\
+    begin
+        push.1
+        debug.stack
+        debug.mem
+    end";
+
+    // compile and execute program
+    let program: Program = Assembler::default().assemble_program(source).unwrap();
+    let mut host = TestHost::default();
+    processor::execute(&program, StackInputs::default(), &mut host, ExecutionOptions::default())
+        .unwrap();
+
+    // Expect to see no debug commands
+    let expected: Vec<String> = vec![];
+    assert_eq!(host.debug_handler, expected);
+}

miden/tests/integration/operations/decorators/mod.rs

@@ -4,7 +4,7 @@ use processor::{
     AdviceExtractor, AdviceProvider, ExecutionError, Host, HostResponse, MastForest,
     MemAdviceProvider, ProcessState,
 };
-use vm_core::AdviceInjector;
+use vm_core::{AdviceInjector, DebugOptions};
 
 mod advice;
 mod asmop;
@@ -16,6 +16,7 @@ pub struct TestHost<A> {
     pub adv_provider: A,
     pub event_handler: Vec<u32>,
     pub trace_handler: Vec<u32>,
+    pub debug_handler: Vec<String>,
 }
 
 impl Default for TestHost<MemAdviceProvider> {
@@ -24,6 +25,7 @@ impl Default for TestHost<MemAdviceProvider> {
             adv_provider: MemAdviceProvider::default(),
             event_handler: Vec::new(),
             trace_handler: Vec::new(),
+            debug_handler: Vec::new(),
         }
     }
 }
@@ -63,6 +65,15 @@ impl<A: AdviceProvider> Host for TestHost<A> {
         Ok(HostResponse::None)
     }
 
+    fn on_debug<S: ProcessState>(
+        &mut self,
+        _process: &S,
+        _options: &DebugOptions,
+    ) -> Result<HostResponse, ExecutionError> {
+        self.debug_handler.push(_options.to_string());
+        Ok(HostResponse::None)
+    }
+
     fn get_mast_forest(&self, _node_digest: &prover::Digest) -> Option<Arc<MastForest>> {
         // Empty MAST forest store
         None

processor/src/lib.rs

@@ -584,7 +584,9 @@ where
                 self.host.borrow_mut().set_advice(self, *injector)?;
             },
             Decorator::Debug(options) => {
-                self.host.borrow_mut().on_debug(self, options)?;
+                if self.decoder.in_debug_mode() {
+                    self.host.borrow_mut().on_debug(self, options)?;
+                }
             },
             Decorator::AsmOp(assembly_op) => {
                 if self.decoder.in_debug_mode() {

processor/src/system/tests.rs

@@ -9,7 +9,7 @@ fn cycles_num_exceeded() {
         Kernel::default(),
         stack,
         host,
-        ExecutionOptions::new(Some(64), 64, false).unwrap(),
+        ExecutionOptions::new(Some(64), 64, false, false).unwrap(),
     );
     for _ in 0..64 {
         process.execute_op(Operation::Noop).unwrap();