From 322f967b8bc6949068bd85a1ae84de838ce940d5 Mon Sep 17 00:00:00 2001 From: Federica Date: Tue, 1 Aug 2023 18:50:13 -0300 Subject: [PATCH 1/3] Add CairoRunner section --- README.md | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) diff --git a/README.md b/README.md index 3fd1507d..cbb3b437 100644 --- a/README.md +++ b/README.md @@ -435,6 +435,131 @@ type VirtualMachine struct { To begin coding the basic execution functionality of our VM, we only need these basic fields, we will be adding more fields as we dive deeper into this guide. +### Instrcution Decoding and Execution + +### CairoRunner + +Now that can can execute cairo steps, lets look at the VM's initialization step. +We will begin by creating our `CairoRunner`: + +```go +type CairoRunner struct { + Program vm.Program + Vm vm.VirtualMachine + ProgramBase memory.Relocatable + executionBase memory.Relocatable + initialPc memory.Relocatable + initialAp memory.Relocatable + initialFp memory.Relocatable + finalPc memory.Relocatable + mainOffset uint +} + +func NewCairoRunner(program vm.Program) *CairoRunner { + // TODO line below is fake + main_offset := program.identifiers["__main__.main"] + return &CairoRunner{Program: program, Vm: *vm.NewVirtualMachine(), mainOffset: main_offset} + +} +``` + +Now we will create our `Initialize` method step by step: + +```go +// Performs the initialization step, returns the end pointer (pc upon which execution should stop) +func (r *CairoRunner) Initialize() (memory.Relocatable, error) { + r.initializeSegments() + end, err := r.initializeMainEntrypoint() + r.initializeVM() + return end, err +} +``` + +*InitializeSegments* + +This method will create our program and execution segments + +```go +func (r *CairoRunner) initializeSegments() { + // Program Segment + r.ProgramBase = r.Vm.Segments.AddSegment() + // Execution Segment + r.executionBase = r.Vm.Segments.AddSegment() +} +``` + +*initializeMainEntrypoint* + +This method will initialize the memory and initial register values to begin execution from the main entrypoint, and return the final pc + +```go +func (r *CairoRunner) initializeMainEntrypoint() (memory.Relocatable, error) { + stack := make([]memory.MaybeRelocatable, 0, 2) + return_fp := r.Vm.Segments.AddSegment() + return r.initializeFunctionEntrypoint(r.mainOffset, &stack, return_fp) +} +``` + +*initializeFunctionEntrypoint* + +This method will initialize the memory and initial register values to execute a cairo function given its offset within the program segment (aka entrypoint) and return the final pc. In our case, this function will be the main entrypoint, but later on we will be able to use this method to run starknet contract entrypoints + +```go +func (r *CairoRunner) initializeFunctionEntrypoint(entrypoint uint, stack *[]memory.MaybeRelocatable, return_fp memory.Relocatable) (memory.Relocatable, error) { + end := r.Vm.Segments.AddSegment() + *stack = append(*stack, *memory.NewMaybeRelocatableRelocatable(end), *memory.NewMaybeRelocatableRelocatable(return_fp)) + r.initialFp = r.executionBase + r.initialFp.Offset += uint(len(*stack)) + r.initialAp = r.initialFp + r.finalPc = end + return end, r.initializeState(entrypoint, stack) +} +``` + +*InitializeState* + +This method will be in charge of loading the program data into the program segment and the stack into the execution segment + +```go +func (r *CairoRunner) initializeState(entrypoint uint, stack *[]memory.MaybeRelocatable) error { + r.initialPc = r.ProgramBase + r.initialPc.Offset += entrypoint + // Load program data + _, err := r.Vm.Segments.LoadData(r.ProgramBase, &r.Program.Data) + if err == nil { + _, err = r.Vm.Segments.LoadData(r.executionBase, stack) + } + return err +} +``` + +*initializeVm* + +This method will set the values of the VM's `RunContext` with our `CairoRunner`'s initial values + +```go +func (r *CairoRunner) initializeVM() { + r.Vm.RunContext.Ap = r.initialAp + r.Vm.RunContext.Fp = r.initialFp + r.Vm.RunContext.Pc = r.initialPc +} +``` + +With `CairoRunner.Initialize()` now complete we can move on to the execution step: + +*RunUntilPc* + +This method will continuously execute cairo steps until the end pc, returned by 'CairoRunner.Initialize()' is reached + +```go + //TODO +``` + +Once we are done executing, we can relocate our memory & trace and output them into files + +### Memory Relocation +TODO + ### Builtins TODO From 632b0788489b4e598d4c583b74d1b8367637ac03 Mon Sep 17 00:00:00 2001 From: Federica Date: Wed, 2 Aug 2023 10:54:57 -0300 Subject: [PATCH 2/3] Explain what the stack is for and what it contains --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cbb3b437..ea252c62 100644 --- a/README.md +++ b/README.md @@ -502,7 +502,8 @@ func (r *CairoRunner) initializeMainEntrypoint() (memory.Relocatable, error) { *initializeFunctionEntrypoint* -This method will initialize the memory and initial register values to execute a cairo function given its offset within the program segment (aka entrypoint) and return the final pc. In our case, this function will be the main entrypoint, but later on we will be able to use this method to run starknet contract entrypoints +This method will initialize the memory and initial register values to execute a cairo function given its offset within the program segment (aka entrypoint) and return the final pc. In our case, this function will be the main entrypoint, but later on we will be able to use this method to run starknet contract entrypoints. +The stack will then be loaded into the execution segment in the next method. For now, the stack will be empty, but later on it will contain the builtin bases (which are the arguments for the main function), and the function arguments when running a function from a starknet contract. ```go func (r *CairoRunner) initializeFunctionEntrypoint(entrypoint uint, stack *[]memory.MaybeRelocatable, return_fp memory.Relocatable) (memory.Relocatable, error) { From 8011b7a05108e654e741601af54b3ad98f8d9194 Mon Sep 17 00:00:00 2001 From: fmoletta <99273364+fmoletta@users.noreply.github.com> Date: Thu, 3 Aug 2023 15:52:39 -0300 Subject: [PATCH 3/3] Fix typo Co-authored-by: Gabriel Bosio <38794644+gabrielbosio@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ea252c62..905b3927 100644 --- a/README.md +++ b/README.md @@ -435,7 +435,7 @@ type VirtualMachine struct { To begin coding the basic execution functionality of our VM, we only need these basic fields, we will be adding more fields as we dive deeper into this guide. -### Instrcution Decoding and Execution +### Instruction Decoding and Execution ### CairoRunner