From 73acc9f20deb36fdddf5ce88022427de8d222983 Mon Sep 17 00:00:00 2001 From: Federica Date: Fri, 23 Jun 2023 12:49:34 -0300 Subject: [PATCH 1/8] Hide some fns add some doc --- vm/src/vm/vm_core.rs | 46 +++++++++++++++++++++++++++++++------------- 1 file changed, 33 insertions(+), 13 deletions(-) diff --git a/vm/src/vm/vm_core.rs b/vm/src/vm/vm_core.rs index 427087d24f..97eb3ac20f 100644 --- a/vm/src/vm/vm_core.rs +++ b/vm/src/vm/vm_core.rs @@ -118,6 +118,7 @@ impl VirtualMachine { } } + #[doc(hidden)] pub fn compute_segments_effective_sizes(&mut self) { self.segments.compute_effective_sizes(); } @@ -443,6 +444,7 @@ impl VirtualMachine { decode_instruction(instruction) } + #[doc(hidden)] pub fn step_hint( &mut self, hint_executor: &mut dyn HintProcessor, @@ -461,6 +463,7 @@ impl VirtualMachine { Ok(()) } + #[doc(hidden)] pub fn step_instruction(&mut self) -> Result<(), VirtualMachineError> { let pc = self.run_context.pc.offset; @@ -482,6 +485,7 @@ impl VirtualMachine { Ok(()) } + /// Executes the hints at the current pc + the next cairo instruction pub fn step( &mut self, hint_executor: &mut dyn HintProcessor, @@ -578,9 +582,9 @@ impl VirtualMachine { Ok(dst) } - /// Compute operands and result, trying to deduce them if normal memory access returns a None - /// value. - pub fn compute_operands( + //Compute operands and result, trying to deduce them if normal memory access returns a None + // value. + fn compute_operands( &self, instruction: &Instruction, ) -> Result<(Operands, OperandsAddresses, DeducedOperands), VirtualMachineError> { @@ -669,8 +673,8 @@ impl VirtualMachine { Ok(()) } - //Makes sure that the value at the given address is consistent with the auto deduction rules. - pub fn verify_auto_deductions_for_addr( + // Makes sure that the value at the given address is consistent with the auto deduction rules. + pub(crate) fn verify_auto_deductions_for_addr( &self, addr: Relocatable, builtin: &BuiltinRunner, @@ -702,6 +706,8 @@ impl VirtualMachine { } } + /// Marks the memory addresses from base to base + len as accessed + /// Accessed addresses are accounted for when calculating memory holes pub fn mark_address_range_as_accessed( &mut self, base: Relocatable, @@ -773,34 +779,37 @@ impl VirtualMachine { entries } - ///Adds a new segment and to the memory and returns its starting location as a Relocatable value. + /// Adds a new segment to the memory and returns its starting location as a Relocatable value. pub fn add_memory_segment(&mut self) -> Relocatable { self.segments.add() } + /// Returns the current value of the allocation pointer pub fn get_ap(&self) -> Relocatable { self.run_context.get_ap() } + /// Returns the current value of the frame pointer pub fn get_fp(&self) -> Relocatable { self.run_context.get_fp() } + /// Returns the current value of the program counter pub fn get_pc(&self) -> Relocatable { self.run_context.get_pc() } - ///Gets the integer value corresponding to the Relocatable address + /// Gets the felt value stored in the memory address indicated by `key` pub fn get_integer(&self, key: Relocatable) -> Result, MemoryError> { self.segments.memory.get_integer(key) } - ///Gets the relocatable value corresponding to the Relocatable address + /// Gets the relocatable value stored in the memory address indicated by `key` pub fn get_relocatable(&self, key: Relocatable) -> Result { self.segments.memory.get_relocatable(key) } - ///Gets a MaybeRelocatable value from memory indicated by a generic address + /// Gets the MaybeRelocatable value from memory indicated by a generic address pub fn get_maybe<'a, 'b: 'a, K: 'a>(&'b self, key: &'a K) -> Option where Relocatable: TryFrom<&'a K>, @@ -808,17 +817,17 @@ impl VirtualMachine { self.segments.memory.get(key).map(|x| x.into_owned()) } - /// Returns a reference to the vector with all builtins present in the virtual machine + /// Returns a reference to the vector with all builtin runners present in the VM pub fn get_builtin_runners(&self) -> &Vec { &self.builtin_runners } - /// Returns a mutable reference to the vector with all builtins present in the virtual machine + /// Returns a mutable reference to the vector with all builtins present in the VM pub fn get_builtin_runners_as_mut(&mut self) -> &mut Vec { &mut self.builtin_runners } - ///Inserts a value into a memory address given by a Relocatable value + /// Inserts a value into a memory address given by a Relocatable value pub fn insert_value>( &mut self, key: Relocatable, @@ -827,7 +836,7 @@ impl VirtualMachine { self.segments.memory.insert_value(key, val) } - ///Writes data into the memory from address ptr and returns the first address after the data. + /// Writes data into the memory from address ptr and returns the first address after the data. pub fn load_data( &mut self, ptr: Relocatable, @@ -848,10 +857,12 @@ impl VirtualMachine { self.segments.write_arg(ptr, arg) } + /// Compares the memory at two ranges indicated by their base and length pub fn memcmp(&self, lhs: Relocatable, rhs: Relocatable, len: usize) -> (Ordering, usize) { self.segments.memory.memcmp(lhs, rhs, len) } + /// Checks if the memory at two ranges indicated by their base and length is equal pub fn mem_eq(&self, lhs: Relocatable, rhs: Relocatable, len: usize) -> bool { self.segments.memory.mem_eq(lhs, rhs, len) } @@ -886,6 +897,8 @@ impl VirtualMachine { self.segments.memory.get_integer_range(addr, size) } + #[doc(hidden)] + // Returns a reference to the range_check builtin if present pub fn get_range_check_builtin(&self) -> Result<&RangeCheckBuiltinRunner, VirtualMachineError> { for builtin in &self.builtin_runners { if let BuiltinRunner::RangeCheck(range_check_builtin) = builtin { @@ -895,6 +908,8 @@ impl VirtualMachine { Err(VirtualMachineError::NoRangeCheckBuiltin) } + #[doc(hidden)] + // Returns a reference to the signature builtin if present pub fn get_signature_builtin( &mut self, ) -> Result<&mut SignatureBuiltinRunner, VirtualMachineError> { @@ -906,6 +921,8 @@ impl VirtualMachine { Err(VirtualMachineError::NoSignatureBuiltin) } + + #[doc(hidden)] pub fn disable_trace(&mut self) { self.trace = None } @@ -930,10 +947,13 @@ impl VirtualMachine { self.run_context.set_pc(pc) } + /// Returns the size of a memory segment indicated by its index pub fn get_segment_used_size(&self, index: usize) -> Option { self.segments.get_segment_used_size(index) } + /// Returns the finalized size of a given segment. If the segment has not been finalized, + /// returns its used size. pub fn get_segment_size(&self, index: usize) -> Option { self.segments.get_segment_size(index) } From ca16fc9a2e67ca9857f359d7957dcab3d2c2f68c Mon Sep 17 00:00:00 2001 From: Federica Date: Fri, 23 Jun 2023 14:20:03 -0300 Subject: [PATCH 2/8] Document functions --- vm/src/vm/vm_core.rs | 11 +++++++++-- vm/src/vm/vm_memory/memory_segments.rs | 3 +++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/vm/src/vm/vm_core.rs b/vm/src/vm/vm_core.rs index 97eb3ac20f..c042307e10 100644 --- a/vm/src/vm/vm_core.rs +++ b/vm/src/vm/vm_core.rs @@ -958,11 +958,13 @@ impl VirtualMachine { self.segments.get_segment_size(index) } + /// Adds a new temporary segment to the memory and returns its starting location as a Relocatable value. + /// temporary segments have a negative index and are not present in the relocated memory unless a relocation rule is added for that segment pub fn add_temporary_segment(&mut self) -> Relocatable { self.segments.add_temporary_segment() } - /// Add a new relocation rule. + /// Adds a new relocation rule. /// /// Will return an error if any of the following conditions are not met: /// - Source address's segment must be negative (temporary). @@ -976,6 +978,9 @@ impl VirtualMachine { self.segments.memory.add_relocation_rule(src_ptr, dst_ptr) } + /// Converts args to Cairo-friendly ones. + /// Currently accepts only `MaybeRelocatable`, `Vec`, other inputs will fail + /// If an argument is a `Vec`, it is written into a new memory segment and it's base is returned pub fn gen_arg(&mut self, arg: &dyn Any) -> Result { self.segments.gen_arg(arg) } @@ -1017,7 +1022,7 @@ impl VirtualMachine { Ok(()) } - ///Relocates the VM's trace, turning relocatable registers to numbered ones + /// Relocates the VM's trace, turning relocatable registers to numbered ones pub fn relocate_trace(&mut self, relocation_table: &[usize]) -> Result<(), TraceError> { if let Some(ref mut trace) = self.trace { if self.trace_relocated { @@ -1037,6 +1042,8 @@ impl VirtualMachine { Ok(()) } + /// Returns the relocated trace + /// Fails if the trace has not been relocated pub fn get_relocated_trace(&self) -> Result<&Vec, TraceError> { if self.trace_relocated { self.trace.as_ref().ok_or(TraceError::TraceNotEnabled) diff --git a/vm/src/vm/vm_memory/memory_segments.rs b/vm/src/vm/vm_memory/memory_segments.rs index da089ce5f8..be66a51ecf 100644 --- a/vm/src/vm/vm_memory/memory_segments.rs +++ b/vm/src/vm/vm_memory/memory_segments.rs @@ -112,6 +112,9 @@ impl MemorySegmentManager { Ok(relocation_table) } + /// Converts args to Cairo-friendly ones. + /// Currently accepts only `MaybeRelocatable`, `Vec`, other inputs will fail + /// If an argument is a `Vec`, it is written into a new memory segment and it's base is returned pub fn gen_arg(&mut self, arg: &dyn Any) -> Result { if let Some(value) = arg.downcast_ref::() { Ok(value.clone()) From ddc13cb25786598c070243c034d6dda984e7f493 Mon Sep 17 00:00:00 2001 From: Federica Date: Fri, 23 Jun 2023 14:22:05 -0300 Subject: [PATCH 3/8] Hide internal structs --- vm/src/vm/vm_core.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vm/src/vm/vm_core.rs b/vm/src/vm/vm_core.rs index c042307e10..6595cc8603 100644 --- a/vm/src/vm/vm_core.rs +++ b/vm/src/vm/vm_core.rs @@ -42,14 +42,14 @@ pub struct Operands { } #[derive(PartialEq, Eq, Debug)] -pub struct OperandsAddresses { +struct OperandsAddresses { dst_addr: Relocatable, op0_addr: Relocatable, op1_addr: Relocatable, } #[derive(Default, Debug, Clone, Copy)] -pub struct DeducedOperands(u8); +struct DeducedOperands(u8); impl DeducedOperands { fn set_dst(&mut self, value: bool) { From 63bd53c24dda3b009f3933c8a1fda0b1f517c439 Mon Sep 17 00:00:00 2001 From: Federica Date: Fri, 23 Jun 2023 14:22:35 -0300 Subject: [PATCH 4/8] Hide internal structs --- vm/src/vm/vm_core.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vm/src/vm/vm_core.rs b/vm/src/vm/vm_core.rs index 6595cc8603..ee0ac8346f 100644 --- a/vm/src/vm/vm_core.rs +++ b/vm/src/vm/vm_core.rs @@ -34,7 +34,7 @@ use super::runners::cairo_runner::RunResources; const MAX_TRACEBACK_ENTRIES: u32 = 20; #[derive(PartialEq, Eq, Debug)] -pub struct Operands { +struct Operands { dst: MaybeRelocatable, res: Option, op0: MaybeRelocatable, From f7e8dbbb8ff2cd0c9e993a23599d6b155a4ca99b Mon Sep 17 00:00:00 2001 From: Federica Date: Fri, 23 Jun 2023 15:20:35 -0300 Subject: [PATCH 5/8] Document extenal & hide internal functions of run_context module --- vm/src/vm/context/run_context.rs | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/vm/src/vm/context/run_context.rs b/vm/src/vm/context/run_context.rs index 4867a154de..8f19d714e3 100644 --- a/vm/src/vm/context/run_context.rs +++ b/vm/src/vm/context/run_context.rs @@ -16,17 +16,20 @@ pub struct RunContext { } impl RunContext { + /// Returns the current value of the allocation pointer pub fn get_ap(&self) -> Relocatable { Relocatable::from((1, self.ap)) } + /// Returns the current value of the frame pointer pub fn get_fp(&self) -> Relocatable { Relocatable::from((1, self.fp)) } + /// Returns the current value of the program counter pub fn get_pc(&self) -> Relocatable { self.pc } - pub fn compute_dst_addr( + pub(crate) fn compute_dst_addr( &self, instruction: &Instruction, ) -> Result { @@ -41,7 +44,7 @@ impl RunContext { } } - pub fn compute_op0_addr( + pub(crate) fn compute_op0_addr( &self, instruction: &Instruction, ) -> Result { @@ -56,7 +59,7 @@ impl RunContext { } } - pub fn compute_op1_addr( + pub(crate) fn compute_op1_addr( &self, instruction: &Instruction, op0: Option<&MaybeRelocatable>, From d77545f04e9aa49615a226010f85765aeaa6f45c Mon Sep 17 00:00:00 2001 From: Federica Date: Fri, 23 Jun 2023 18:26:57 -0300 Subject: [PATCH 6/8] Make decoding module private --- vm/src/vm/decoding/decoder.rs | 2 +- vm/src/vm/decoding/mod.rs | 2 +- vm/src/vm/mod.rs | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/vm/src/vm/decoding/decoder.rs b/vm/src/vm/decoding/decoder.rs index 35a98e7812..b2fe41101c 100644 --- a/vm/src/vm/decoding/decoder.rs +++ b/vm/src/vm/decoding/decoder.rs @@ -9,7 +9,7 @@ use crate::{ // 15|14 13 12| 11 10| 9 8 7| 6 5|4 3 2| 1| 0 /// Decodes an instruction. The encoding is little endian, so flags go from bit 63 to 48. -pub fn decode_instruction(encoded_instr: u64) -> Result { +pub(crate) fn decode_instruction(encoded_instr: u64) -> Result { const HIGH_BIT: u64 = 1u64 << 63; const DST_REG_MASK: u64 = 0x0001; const DST_REG_OFF: u64 = 0; diff --git a/vm/src/vm/decoding/mod.rs b/vm/src/vm/decoding/mod.rs index 56812db3ac..99753de58a 100644 --- a/vm/src/vm/decoding/mod.rs +++ b/vm/src/vm/decoding/mod.rs @@ -1 +1 @@ -pub mod decoder; +pub(crate) mod decoder; diff --git a/vm/src/vm/mod.rs b/vm/src/vm/mod.rs index 4fb3779f25..ebd6098c5d 100644 --- a/vm/src/vm/mod.rs +++ b/vm/src/vm/mod.rs @@ -1,5 +1,5 @@ pub mod context; -pub mod decoding; +pub(crate) mod decoding; pub mod errors; pub mod runners; pub mod security; From f33e0ca5af954ceaec339777000c7ff573f53818 Mon Sep 17 00:00:00 2001 From: Federica Date: Fri, 23 Jun 2023 18:45:36 -0300 Subject: [PATCH 7/8] Add doc for RunResources methods --- vm/src/vm/runners/cairo_runner.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/vm/src/vm/runners/cairo_runner.rs b/vm/src/vm/runners/cairo_runner.rs index 185360db1e..7bfef0edef 100644 --- a/vm/src/vm/runners/cairo_runner.rs +++ b/vm/src/vm/runners/cairo_runner.rs @@ -74,7 +74,7 @@ impl From> for CairoArg { // RunResources // ================ -/// Maintains the resources of a cairo run. Can be used across multiple runners. +/// Keeps track of the resources used by cairo run. Can be used across multiple runners. #[derive(Clone, Default, Debug, PartialEq)] pub struct RunResources { n_steps: Option, @@ -87,6 +87,8 @@ impl RunResources { } } + /// Returns true if the resources have been consumed + /// no more steps can be run if the resources are consumed pub fn consumed(&self) -> bool { if self.n_steps == Some(0) { return true; @@ -94,12 +96,14 @@ impl RunResources { false } + /// Consumes a single step pub fn consume_step(&mut self) { if let Some(n_steps) = self.n_steps { self.n_steps = Some(n_steps.saturating_sub(1)); } } + /// Returns the number of remaining steps pub fn get_n_steps(&self) -> Option { self.n_steps } From b428f3385392f80d8a069687571e87586ba6727f Mon Sep 17 00:00:00 2001 From: Federica Date: Fri, 23 Jun 2023 18:57:41 -0300 Subject: [PATCH 8/8] Document cairo-runner methods --- vm/src/vm/runners/cairo_runner.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/vm/src/vm/runners/cairo_runner.rs b/vm/src/vm/runners/cairo_runner.rs index 7bfef0edef..7d1a10210d 100644 --- a/vm/src/vm/runners/cairo_runner.rs +++ b/vm/src/vm/runners/cairo_runner.rs @@ -171,6 +171,7 @@ impl CairoRunner { }) } + /// Performs the full initialization step, including builtins, segments and vm pub fn initialize(&mut self, vm: &mut VirtualMachine) -> Result { self.initialize_builtins(vm)?; self.initialize_segments(vm, None); @@ -179,6 +180,7 @@ impl CairoRunner { Ok(end) } + /// Initializes the builtins according to the cairo layout and program builtins pub fn initialize_builtins(&self, vm: &mut VirtualMachine) -> Result<(), RunnerError> { let builtin_ordered_list = vec![ BuiltinName::output, @@ -339,7 +341,7 @@ impl CairoRunner { Ok(()) } - ///Creates the necessary segments for the program, execution, and each builtin on the MemorySegmentManager and stores the first adress of each of this new segments as each owner's base + /// Creates the necessary segments for the program, execution, and each builtin on the MemorySegmentManager and stores the first adress of each of this new segments as each owner's base pub fn initialize_segments( &mut self, vm: &mut VirtualMachine, @@ -389,6 +391,7 @@ impl CairoRunner { Ok(()) } + /// Initializes the given function entrypoint with the given args and returns the end pc pub fn initialize_function_entrypoint( &mut self, vm: &mut VirtualMachine, @@ -476,6 +479,7 @@ impl CairoRunner { } } + // Initializes the vm's run_context and validation rules, validates the existing memory pub fn initialize_vm(&mut self, vm: &mut VirtualMachine) -> Result<(), RunnerError> { vm.run_context.pc = *self.initial_pc.as_ref().ok_or(RunnerError::NoPC)?; vm.run_context.ap = self.initial_ap.as_ref().ok_or(RunnerError::NoAP)?.offset;