Struct VM

pub struct VM<'a, F, B: BlackBoxFunctionSolver<F>> {
    pub(crate) calldata: Vec<F>,
    pub(crate) program_counter: usize,
    pub(crate) foreign_call_counter: usize,
    pub(crate) foreign_call_results: Vec<ForeignCallResult<F>>,
    pub(crate) bytecode: &'a [Opcode<F>],
    pub(crate) status: VMStatus<F>,
    pub(crate) memory: Memory<F>,
    pub(crate) call_stack: Vec<usize>,
    pub(crate) black_box_solver: &'a B,
    pub(crate) profiling_active: bool,
    pub(crate) profiling_samples: BrilligProfilingSamples,
    pub(crate) fuzzing_trace: Option<FuzzingTrace>,
}

VM encapsulates the state of the Brillig VM during execution.

Fields

calldata: Vec<F>

Calldata to the brillig function.

program_counter: usize

Instruction pointer.

foreign_call_counter: usize

A counter maintained throughout a Brillig process that determines whether the caller has resolved the results of a foreign call.

Incremented when the results of a foreign call have been processed and the output values were written to memory.

• When the counter is less than the length of the results, it indicates that we have unprocessed responses returned from the external foreign call handler.

foreign_call_results: Vec<ForeignCallResult<F>>

Accumulates the outputs of all foreign calls during a Brillig process. The list is appended onto by the caller upon reaching a VMStatus::ForeignCallWait.

bytecode: &'a [Opcode<F>]

Executable opcodes.

status: VMStatus<F>

Status of the VM.

memory: Memory<F>

Memory of the VM.

call_stack: Vec<usize>

Call stack.

black_box_solver: &'a B

The solver for blackbox functions.

profiling_active: bool

profiling_samples: BrilligProfilingSamples

fuzzing_trace: Option<FuzzingTrace>

Fuzzing trace structure. If the field is None then fuzzing is inactive.

Implementations

impl<F: AcirField, B: BlackBoxFunctionSolver<F>> VM<'_, F, B>

pub(crate) fn process_foreign_call( &mut self, function: &str, destinations: &[ValueOrArray], destination_value_types: &[HeapValueType], inputs: &[ValueOrArray], input_value_types: &[HeapValueType], ) -> &VMStatus<F>

Handles the execution of a single ForeignCall opcode.

This method performs the following steps:

1. Checks if the foreign call results are already available. If not, it resolves the input values from memory and pauses execution by returning VMStatus::ForeignCallWait. For vectors, the preceding u32 length field is used to truncate the slice input to its semantic length.
2. If results are available, it writes them to memory, ensuring that the returned data matches the expected types and sizes. Nested arrays are reconstructed from flat outputs when necessary. Nested vectors are an unsupported return type and will trigger an error.
3. Increments the foreign call counter and advances the program counter.

Parameters

The borrowed fields of a ForeignCall opcode. They are listed again below:

• function: Name of the foreign function being called.
• destinations: Pointers or heap structures where the return values will be written.
• destination_value_types: Expected type layout for each destination.
• inputs: Pointers or heap structures representing the inputs for the foreign call.
• input_value_types: Expected type layout for each input.

Returns

• VMStatus indicating the next state of the VM:
  • VMStatus::ForeignCallWait if the results are not yet available.
  • VMStatus::Finished or VMStatus::Failure depending on whether writing the results succeeded.

Panics

• If inputs and input_value_types lengths do not match.
• If destinations and destination_value_types lengths do not match.

fn get_memory_values( &self, input: ValueOrArray, value_type: &HeapValueType, ) -> ForeignCallParam<F>

Get input data from memory to pass to foreign calls.

fn read_slice_of_values_from_memory( &self, start: MemoryAddress, size: usize, value_types: &[HeapValueType], ) -> Vec<MemoryValue<F>>

Reads an array/vector from memory but recursively reads pointers to nested arrays/vectors according to the sequence of value types.

fn wait_for_foreign_call( &mut self, function: String, inputs: Vec<ForeignCallParam<F>>, ) -> &VMStatus<F>

Sets the status of the VM to ForeignCallWait. Indicating that the VM is now waiting for a foreign call to be resolved.

fn write_foreign_call_result( &mut self, destinations: &[ValueOrArray], destination_value_types: &[HeapValueType], foreign_call_index: usize, ) -> Result<(), String>

Write a foreign call’s results to the VM memory.

We match the expected types with the actual results. However foreign call results do not support nested structures: They are either a single integer value or a vector of integer values (field elements). Therefore, nested arrays returned from foreign call results are flattened. If the expected array sizes do not match the actual size, we reconstruct the nested structure from the flat output array.

fn write_value_to_memory( &mut self, destination: MemoryAddress, value: &F, value_bit_size: BitSize, ) -> Result<(), String>

Write a single numeric value to the destination address, ensuring that the bit size matches the expectation.

fn write_values_to_memory( &mut self, pointer: MemoryAddress, values: &[F], value_types: &[HeapValueType], ) -> Result<(), String>

Write an array or slice to the destination under the pointer.

fn write_flattened_values_to_memory( &mut self, destination: MemoryAddress, values: &Vec<F>, values_idx: &mut usize, value_type: &HeapValueType, ) -> Result<(), String>

Writes flattened values to memory, using the provided type.

The method calls itself recursively in order to work with recursive types (nested arrays). values_idx is the current index in the values vector and is incremented every time a value is written to memory.

impl<F: AcirField, B: BlackBoxFunctionSolver<F>> VM<'_, F, B>

pub(crate) fn fuzzing_trace_binary_field_op_comparison( &mut self, op: &BinaryFieldOp, lhs: MemoryValue<F>, rhs: MemoryValue<F>, result: MemoryValue<F>, )

Collect information about the comparison of two field values in the fuzzing trace

pub(crate) fn fuzzing_trace_binary_int_op_comparison( &mut self, op: &BinaryIntOp, lhs: MemoryValue<F>, rhs: MemoryValue<F>, result: MemoryValue<F>, )

Collect information about the comparison of two integer values in the fuzzing trace

pub(crate) fn fuzzing_trace_branching( &mut self, destination: NextOpcodePositionOrState, )

Mark the execution of a particular branch in the fuzzing trace

pub(crate) fn fuzzing_trace_conditional_mov(&mut self, branch: bool)

Mark the execution of a conditional move in the fuzzing trace

impl<'a, F: AcirField, B: BlackBoxFunctionSolver<F>> VM<'a, F, B>

pub fn new( calldata: Vec<F>, bytecode: &'a [Opcode<F>], black_box_solver: &'a B, profiling_active: bool, with_branch_to_feature_map: Option<&BranchToFeatureMap>, ) -> Self

Constructs a new VM instance.

pub fn is_profiling_active(&self) -> bool

pub fn is_fuzzing_active(&self) -> bool

pub fn take_profiling_samples(&mut self) -> BrilligProfilingSamples

pub(crate) fn status(&mut self, status: VMStatus<F>) -> &VMStatus<F>

Updates the current status of the VM. Returns the given status.

pub fn get_status(&self) -> VMStatus<F>

pub(crate) fn finish( &mut self, return_data_offset: usize, return_data_size: usize, ) -> &VMStatus<F>

Sets the current status of the VM to Finished (completed execution).

pub(crate) fn has_unprocessed_foreign_call_result(&self) -> bool

Check whether the latest foreign call result is available yet.

pub fn resolve_foreign_call( &mut self, foreign_call_result: ForeignCallResult<F>, )

Provide the results of a Foreign Call to the VM and resume execution of the VM.

pub(crate) fn trap( &mut self, revert_data_offset: usize, revert_data_size: usize, ) -> &VMStatus<F>

Sets the current status of the VM to Failure, indicating that the VM encountered a Trap Opcode.

pub(crate) fn fail(&mut self, message: String) -> &VMStatus<F>

Sets the current status of the VM to Failure, indicating that the VM encountered an invalid state.

pub fn process_opcodes(&mut self) -> VMStatus<F>

Process opcodes in a loop until a status of Finished, Failure or ForeignCallWait is encountered.

pub fn get_memory(&self) -> &[MemoryValue<F>]

Read memory slots.

Used by the debugger to inspect the contents of the memory.

pub fn take_memory(self) -> Memory<F>

Take all the contents of the memory, leaving it empty.

Used only for testing purposes.

pub fn foreign_call_counter(&self) -> usize

pub fn write_memory_at(&mut self, ptr: usize, value: MemoryValue<F>)

Write a numeric value to direct memory slot.

Used by the debugger to alter memory.

pub fn get_call_stack(&self) -> Vec<usize>

Returns the VM’s current call stack, including the actual program counter in the last position of the returned vector.

pub fn get_call_stack_no_current_counter(&self) -> Vec<usize>

Returns the VM’s call stack, but unlike Self::get_call_stack without the attaching the program counter in the last position of the returned vector. This is meant only for fetching the call stack after execution has completed.

pub fn process_opcode(&mut self) -> &VMStatus<F>

Process a single opcode and modify the program counter.

pub fn get_fuzzing_trace(&self) -> Vec<u32>

pub(crate) fn process_opcode_internal(&mut self) -> &VMStatus<F>

Execute a single opcode:

1. Retrieve the current opcode using the program counter
2. Execute the opcode.
   • For instance a binary ‘result = lhs+rhs’ opcode will read the VM memory at the ‘lhs’ and ‘rhs’ addresses, compute the sum and write it to the ‘result’ memory address.
3. Update the program counter, usually by incrementing it.

• Control flow opcodes jump around the bytecode by setting the program counter.
• Foreign call opcodes pause the VM until the foreign call results are available.
• Function call opcodes backup the current program counter into the call stack and jump to the function entry point. The stack frame for function calls is handled during codegen.

pub fn program_counter(&self) -> usize

Returns the current value of the program counter.

pub(crate) fn increment_program_counter(&mut self) -> &VMStatus<F>

Increments the program counter by 1.

pub(crate) fn set_program_counter(&mut self, value: usize) -> &VMStatus<F>

Sets the program counter to value. If the program counter no longer points to an opcode in the bytecode, then the VMStatus reports Finished.

pub(crate) fn process_binary_field_op( &mut self, op: BinaryFieldOp, lhs: MemoryAddress, rhs: MemoryAddress, result: MemoryAddress, ) -> Result<(), BrilligArithmeticError>

Process a binary field operation. This method will not modify the program counter.

pub(crate) fn process_binary_int_op( &mut self, op: BinaryIntOp, bit_size: IntegerBitSize, lhs: MemoryAddress, rhs: MemoryAddress, result: MemoryAddress, ) -> Result<(), BrilligArithmeticError>

Process a binary integer operation. This method will not modify the program counter.

pub(crate) fn process_not( &mut self, source: MemoryAddress, destination: MemoryAddress, op_bit_size: IntegerBitSize, ) -> Result<(), MemoryTypeError>

Process a unary negation operation.

It returns MemoryTypeError if the value type does not match the type indicated by op_bit_size.

Trait Implementations

impl<'a, F: Clone, B: Clone + BlackBoxFunctionSolver<F>> Clone for VM<'a, F, B>

fn clone(&self) -> VM<'a, F, B>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, F: Debug, B: Debug + BlackBoxFunctionSolver<F>> Debug for VM<'a, F, B>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, F: PartialEq, B: PartialEq + BlackBoxFunctionSolver<F>> PartialEq for VM<'a, F, B>

fn eq(&self, other: &VM<'a, F, B>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, F: Eq, B: Eq + BlackBoxFunctionSolver<F>> Eq for VM<'a, F, B>

impl<'a, F, B: BlackBoxFunctionSolver<F>> StructuralPartialEq for VM<'a, F, B>