Struct midenc_codegen_masm::Emulator

pub struct Emulator { /* private fields */ }

Emulator provides us with a means to execute our MASM IR directly without having to emit “real” MASM and run it via the Miden VM. In other words, it’s a convenient way to run tests to verify the expected behavior of a program without all of the baggage of the Miden VM.

Emulator is necessarily a more limited execution environment:

• It only handles instructions which are defined in the Op enum
• Anything related to proving, calling contracts, etc. is not supported
• The default environment is empty, i.e. there are no Miden VM standard library functions available. Users must emit Miden IR for all functions they wish to call, or alternatively, provide native stubs.

Implementations

impl Emulator

pub const DEFAULT_HEAP_SIZE: u32 = 16_384u32

pub const DEFAULT_HEAP_START: u32 = 8_192u32

pub const DEFAULT_LOCALS_START: u32 = 12_288u32

pub fn new(memory_size: u32, hp: u32, lp: u32, print_stack: bool) -> Self

Construct a new, empty emulator with:

• A linear memory heap of memory_size words
• The start of the usable heap set to hp (an address in words)
• The start of the reserved heap used for locals set to lp (an address in words)

pub fn set_max_cycles(&mut self, max: usize)

Place a cap on the number of cycles the emulator will execute before failing with an error

pub fn watchpoints(&self) -> impl Iterator<Item = Watchpoint> + '_

Returns all watchpoints that are currently managed by this [BreakpointManager]

pub fn breakpoints(&self) -> impl Iterator<Item = Breakpoint>

Returns all breakpoints that are currently managed by this [BreakpointManager]

pub fn set_breakpoint(&mut self, bp: Breakpoint)

Sets a breakpoint for the emulator

pub fn clear_breakpoint(&mut self, bp: Breakpoint)

Removes the given breakpoint from the emulator

pub fn clear_breakpoints(&mut self)

Removes the all breakpoints from the emulator

pub fn set_watchpoint( &mut self, addr: u32, size: u32, mode: WatchMode, ) -> WatchpointId

Sets a watchpoint in the emulator

pub fn clear_watchpoint(&mut self, id: WatchpointId)

Sets a watchpoint in the emulator

pub fn watchpoint_mode(&mut self, id: WatchpointId, mode: WatchMode)

Set the watch mode for a Watchpoint using the identifier returned by [watch]

pub fn clear_watchpoints(&mut self)

Clears all watchpoints

pub fn clear_break_and_watchpoints(&mut self)

Clear all breakpoints and watchpoints

pub fn info(&self) -> Option<DebugInfo<'_>>

Get’s debug information about the current emulator state

pub fn stacktrace(&self) -> Vec<CallFrame>

Get a stacktrace for the code running in the emulator

pub fn current_ip(&self) -> Option<Instruction>

Get the instruction pointer that will be next executed by the emulator

pub fn current_function(&self) -> Option<FunctionIdent>

Get the name of the function that is currently executing

pub fn stack(&mut self) -> &OperandStack<Felt>

Get access to the current state of the operand stack

pub fn stack_mut(&mut self) -> &mut OperandStack<Felt>

Get mutable access to the current state of the operand stack

pub fn load_program( &mut self, program: Arc<Program>, ) -> Result<(), EmulationError>

Load program into this emulator

This resets the emulator state, as only one program may be loaded at a time.

pub fn load_module(&mut self, module: Arc<Module>) -> Result<(), EmulationError>

Load module into this emulator

An error is returned if a module with the same name is already loaded.

pub fn reload_module( &mut self, module: Arc<Module>, ) -> Result<(), EmulationError>

Reloads a loaded module, name.

This function will panic if the named module is not currently loaded.

pub fn unload_module(&mut self, name: Ident)

Unloads a loaded module, name.

This function will panic if the named module is not currently loaded.

pub fn load_nif( &mut self, id: FunctionIdent, function: Box<dyn FnMut(&mut Emulator, &[Felt]) -> Result<(), EmulationError>>, ) -> Result<(), EmulationError>

Load function into this emulator, with the given identifier

Because we don’t know the set of [FuncId] that have already been allocated, we leave the choice up to the caller. We assert that functions do not get defined twice to catch conflicts, just in case.

pub fn write_bytes_to_memory(&mut self, value: &[u8]) -> u32

Allocate space for value on the emulator heap, and copy it’s contents there.

NOTE: The smallest unit of addressable memory is 4 bytes (32 bits). If you provide a value that is smaller than this, or is not a multiple of 4, the data will be padded with zeroes to ensure that it is.

pub fn malloc(&mut self, size: usize) -> u32

Allocate enough words to hold size bytes of memory

Returns the pointer as a byte-addressable address

pub fn store(&mut self, addr: usize, value: Felt)

Write value to the word at addr, and element index

pub fn start(&mut self) -> Result<OperandStack<Felt>, EmulationError>

Start executing the current program by invokeing the top-level initialization block (the entrypoint).

This function will run the program to completion, and return the state of the operand stack on exit.

NOTE: If no entrypoint has been loaded, an error is returned.

The emulator is automatically reset when it exits successfully.

pub fn init(&mut self) -> Result<EmulatorEvent, EmulationError>

Start emulation by entering the top-level initialization block (the entrypoint).

This should be called instead of start when stepping through a program rather than executing it to completion in one call.

NOTE: If no entrypoint has been loaded, an error is returned.

It is up to the caller to reset the emulator when the program exits, unlike start.

pub fn stop(&mut self)

Stop running the currently executing function, and reset the cycle counter, operand stack, and linear memory.

This function preserves loaded code, breakpoints, and other configuration items.

If an attempt is made to run the emulator in the stopped state, a panic will occur

pub fn reset(&mut self)

Reset the emulator state to its initial state at creation.

In addition to resetting the cycle counter, operand stack, and linear memory, this function also unloads all code, and clears all breakpoints. Only the configuration used to initialize the emulator is preserved.

To use the emulator after calling this function, you must load a program or module again.

pub fn invoke( &mut self, callee: FunctionIdent, args: &[Felt], ) -> Result<OperandStack<Felt>, EmulationError>

Run the emulator by invoking callee with args placed on the operand stack in FIFO order.

If a fatal error occurs during emulation, Err is returned, e.g. if callee has not been loaded.

When callee returns, it’s result will be returned wrapped in Ok. For functions with no return value, this will be Ok(None), or all others it will be Ok(Some(value)).

pub fn enter( &mut self, callee: FunctionIdent, args: &[Felt], ) -> Result<EmulatorEvent, EmulationError>

Run the emulator by invoking callee with args placed on the operand stack in FIFO order.

If a fatal error occurs during emulation, Err is returned, e.g. if callee has not been loaded.

When callee returns, it’s result will be returned wrapped in Ok. For functions with no return value, this will be Ok(None), or all others it will be Ok(Some(value)).

pub fn resume(&mut self) -> Result<EmulatorEvent, EmulationError>

Resume execution when the emulator suspended due to a breakpoint

impl Emulator

pub fn step(&mut self) -> Result<EmulatorEvent, EmulationError>

Step the emulator forward one cycle, returning the type of event produced during that cycle, or an error.

pub fn step_over(&mut self) -> Result<EmulatorEvent, EmulationError>

Step the emulator forward one step, but stepping past any nested blocks or function calls, returning the type of event produced during that cycle, or an error.

pub fn step_out(&mut self) -> Result<EmulatorEvent, EmulationError>

Step the emulator forward until control returns from the current function.

Trait Implementations

impl Default for Emulator

fn default() -> Self

Returns the “default value” for a type.