From 32ca1d25c6493a5e897b929b9be112e9a214ba70 Mon Sep 17 00:00:00 2001 From: Milton Date: Wed, 26 Jul 2023 14:16:09 -0300 Subject: [PATCH 1/7] Decoder Documentation --- README.md | 26 ++++++++++++++++++++++++++ src/instruction.h | 18 ------------------ 2 files changed, 26 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index ff66c75..3d988a9 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,32 @@ TODO: Short explanation of Felts and the Cairo/Stark field we use through Lambda Go through the main parts of a compiled program `Json` file. `data` field with instructions, identifiers, program entrypoint, etc. + +### Program decoding + +Once the VM has been feed with a compiled cairo program it has to be decoded. The decoder takes as input the hexadecimal number in little endian format that represents the instruction an generates an Instruction structs with it. +Instruction is the representation of the first word of each Cairo instruction. Some instructions spread over two words when they use an immediate value, so representing the first one with this struct is enougth. + + Structure of the 63-bit that form the first word of each instruction. + See Cairo whitepaper, page 32 - https://eprint.iacr.org/2021/1063.pdf. + ┌─────────────────────────────────────────────────────────────────────────┐ + │ off_dst (biased representation) │ + ├─────────────────────────────────────────────────────────────────────────┤ + │ off_op0 (biased representation) │ + ├─────────────────────────────────────────────────────────────────────────┤ + │ off_op1 (biased representation) │ + ├─────┬─────┬───────┬───────┬───────────┬────────┬───────────────────┬────┤ + │ dst │ op0 │ op1 │ res │ pc │ ap │ opcode │ 0 │ + │ reg │ reg │ src │ logic │ update │ update │ │ │ + ├─────┼─────┼───┬───┼───┬───┼───┬───┬───┼───┬────┼────┬────┬────┬────┼────┤ + │ 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 │ 9 │ 10 │ 11 │ 12 │ 13 │ 14 │ 15 │ + └─────┴─────┴───┴───┴───┴───┴───┴───┴───┴───┴────┴────┴────┴────┴────┴────┘ + +The decoder perform masks and bitwise operations to extract the fields from the hexadecimal values and store them in the struct representation, each value of the masks and padding can be deduced from the table above. +for example to extract the dst_reg flag we can define a mask 'DST_REG_MASK' with value 0x0001 and and a padding 'DST_REG_OFF' with value 0 because it is the less significant bit, then we can perform the operation +'(((encoded_instr) >> 48) & DST_REG_MASK) >> DST_REG_OFF' to obtain the dst_reg flag. We shifted 48 bits first because there is where the flags start. + + ### Code walkthrough/Write your own Cairo VM TODO diff --git a/src/instruction.h b/src/instruction.h index 7bd3fa3..1ee512b 100644 --- a/src/instruction.h +++ b/src/instruction.h @@ -3,24 +3,6 @@ #include #include -// Structure of the 63-bit that form the first word of each instruction. -// See Cairo whitepaper, page 32 - https://eprint.iacr.org/2021/1063.pdf. -// ┌─────────────────────────────────────────────────────────────────────────┐ -// │ off_dst (biased representation) │ -// ├─────────────────────────────────────────────────────────────────────────┤ -// │ off_op0 (biased representation) │ -// ├─────────────────────────────────────────────────────────────────────────┤ -// │ off_op1 (biased representation) │ -// ├─────┬─────┬───────┬───────┬───────────┬────────┬───────────────────┬────┤ -// │ dst │ op0 │ op1 │ res │ pc │ ap │ opcode │ 0 │ -// │ reg │ reg │ src │ logic │ update │ update │ │ │ -// ├─────┼─────┼───┬───┼───┬───┼───┬───┬───┼───┬────┼────┬────┬────┬────┼────┤ -// │ 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 │ 9 │ 10 │ 11 │ 12 │ 13 │ 14 │ 15 │ -// └─────┴─────┴───┴───┴───┴───┴───┴───┴───┴───┴────┴────┴────┴────┴────┴────┘ - -// Instruction is the representation of the first word of each Cairo instruction. -// Some instructions spread over two words when they use an immediate value, so -// representing the first one with this struct is enougth. // --------------------- // structures From c70c9004d32bdd857b3459903ec60a28f0f5a8e5 Mon Sep 17 00:00:00 2001 From: Milton Date: Wed, 26 Jul 2023 17:21:40 -0300 Subject: [PATCH 2/7] Fix fmt --- src/instruction.h | 1 - 1 file changed, 1 deletion(-) diff --git a/src/instruction.h b/src/instruction.h index 1ee512b..25e2967 100644 --- a/src/instruction.h +++ b/src/instruction.h @@ -3,7 +3,6 @@ #include #include - // --------------------- // structures // --------------------- From 2550803b7feefc6e6fb904809212e6a0e6da620c Mon Sep 17 00:00:00 2001 From: Milton Date: Wed, 26 Jul 2023 19:13:49 -0300 Subject: [PATCH 3/7] fix typos --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3d988a9..8eda36b 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,7 @@ Go through the main parts of a compiled program `Json` file. `data` field with i ### Program decoding -Once the VM has been feed with a compiled cairo program it has to be decoded. The decoder takes as input the hexadecimal number in little endian format that represents the instruction an generates an Instruction structs with it. +Once the VM has been fed with a compiled cairo program it has to be decoded. The decoder takes as input the hexadecimal number in little endian format that represents the instruction an generates an Instruction struct with it. Instruction is the representation of the first word of each Cairo instruction. Some instructions spread over two words when they use an immediate value, so representing the first one with this struct is enougth. Structure of the 63-bit that form the first word of each instruction. @@ -148,7 +148,7 @@ Instruction is the representation of the first word of each Cairo instruction. S │ 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 │ 9 │ 10 │ 11 │ 12 │ 13 │ 14 │ 15 │ └─────┴─────┴───┴───┴───┴───┴───┴───┴───┴───┴────┴────┴────┴────┴────┴────┘ -The decoder perform masks and bitwise operations to extract the fields from the hexadecimal values and store them in the struct representation, each value of the masks and padding can be deduced from the table above. +The decoder perform bitwise operations with masks to extract the fields from the hexadecimal values and store them in the struct representation, each value of the masks and padding can be deduced from the table above. for example to extract the dst_reg flag we can define a mask 'DST_REG_MASK' with value 0x0001 and and a padding 'DST_REG_OFF' with value 0 because it is the less significant bit, then we can perform the operation '(((encoded_instr) >> 48) & DST_REG_MASK) >> DST_REG_OFF' to obtain the dst_reg flag. We shifted 48 bits first because there is where the flags start. From 146509e58a2289e4b62ac8645f0c68e8928b3b1f Mon Sep 17 00:00:00 2001 From: Milton Date: Mon, 31 Jul 2023 08:05:54 -0300 Subject: [PATCH 4/7] Add more info --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 8eda36b..5dbdd04 100644 --- a/README.md +++ b/README.md @@ -135,6 +135,8 @@ Instruction is the representation of the first word of each Cairo instruction. S Structure of the 63-bit that form the first word of each instruction. See Cairo whitepaper, page 32 - https://eprint.iacr.org/2021/1063.pdf. + +``` ┌─────────────────────────────────────────────────────────────────────────┐ │ off_dst (biased representation) │ ├─────────────────────────────────────────────────────────────────────────┤ @@ -147,6 +149,7 @@ Instruction is the representation of the first word of each Cairo instruction. S ├─────┼─────┼───┬───┼───┬───┼───┬───┬───┼───┬────┼────┬────┬────┬────┼────┤ │ 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 │ 9 │ 10 │ 11 │ 12 │ 13 │ 14 │ 15 │ └─────┴─────┴───┴───┴───┴───┴───┴───┴───┴───┴────┴────┴────┴────┴────┴────┘ +``` The decoder perform bitwise operations with masks to extract the fields from the hexadecimal values and store them in the struct representation, each value of the masks and padding can be deduced from the table above. for example to extract the dst_reg flag we can define a mask 'DST_REG_MASK' with value 0x0001 and and a padding 'DST_REG_OFF' with value 0 because it is the less significant bit, then we can perform the operation From 2fb79b567922e817c5a5952c257c896bc3bf4dcd Mon Sep 17 00:00:00 2001 From: Milton Date: Mon, 31 Jul 2023 08:07:43 -0300 Subject: [PATCH 5/7] fix typo --- README.md | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5dbdd04..3d17935 100644 --- a/README.md +++ b/README.md @@ -131,7 +131,8 @@ Go through the main parts of a compiled program `Json` file. `data` field with i ### Program decoding Once the VM has been fed with a compiled cairo program it has to be decoded. The decoder takes as input the hexadecimal number in little endian format that represents the instruction an generates an Instruction struct with it. -Instruction is the representation of the first word of each Cairo instruction. Some instructions spread over two words when they use an immediate value, so representing the first one with this struct is enougth. +the CPU native word is a field element that is some fixed finite field of characteristic P > 263 (P is the prime number of the field), as such Instruction is the representation of the first word of each Cairo instruction. Some instructions spread over two words when they use an immediate value, so representing the first one with this struct is enougth. +The first word of each instruction consists of: (1) three 16-bit signed integer offsets offdst, offop0, offop1 in the range [−215, 215) encoded using biased representation25; and (2) 15 bits of flags divided into seven Structure of the 63-bit that form the first word of each instruction. See Cairo whitepaper, page 32 - https://eprint.iacr.org/2021/1063.pdf. @@ -152,9 +153,33 @@ Instruction is the representation of the first word of each Cairo instruction. S ``` The decoder perform bitwise operations with masks to extract the fields from the hexadecimal values and store them in the struct representation, each value of the masks and padding can be deduced from the table above. -for example to extract the dst_reg flag we can define a mask 'DST_REG_MASK' with value 0x0001 and and a padding 'DST_REG_OFF' with value 0 because it is the less significant bit, then we can perform the operation +for example the following hexadecimal encoding '0x480680017fff8000, 1,'represent the next instruction: +``` +[ap] = 1; ap++ +``` +which stores 1 in the direction stored in the ap register and increases it in one to point to the next direction. +we can declare an structure to store the data as follows: +``` +struct Instruction { + int64_t off0; + int64_t off1; + int64_t off2; + enum Register dst_register; + enum Register op0_register; + enum Op1Addr op1_addr; + enum Res res; + enum PcUpdate pc_update; + enum ApUpdate ap_update; + enum FpUpdate fp_update; + enum Opcode opcode; +}; +``` +to extract the dst_reg flag we can define a mask 'DST_REG_MASK' with value 0x0001 and and a padding 'DST_REG_OFF' with value 0 because it is the less significant bit, then we can perform the operation '(((encoded_instr) >> 48) & DST_REG_MASK) >> DST_REG_OFF' to obtain the dst_reg flag. We shifted 48 bits first because there is where the flags start. - +the code would be as follow, nameing the hex value as encoded_instr: +``` +struct Instruction instrunction.dst_register = '(((encoded_instr) >> 48) & DST_REG_MASK) >> DST_REG_OFF' +``` ### Code walkthrough/Write your own Cairo VM From eee6fb02f0406d3263aad8a9d842f3360439eb8d Mon Sep 17 00:00:00 2001 From: Milton Date: Wed, 2 Aug 2023 21:07:23 -0300 Subject: [PATCH 6/7] Fix typos --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3d17935..ebc70fc 100644 --- a/README.md +++ b/README.md @@ -131,7 +131,7 @@ Go through the main parts of a compiled program `Json` file. `data` field with i ### Program decoding Once the VM has been fed with a compiled cairo program it has to be decoded. The decoder takes as input the hexadecimal number in little endian format that represents the instruction an generates an Instruction struct with it. -the CPU native word is a field element that is some fixed finite field of characteristic P > 263 (P is the prime number of the field), as such Instruction is the representation of the first word of each Cairo instruction. Some instructions spread over two words when they use an immediate value, so representing the first one with this struct is enougth. +The CPU native word is a field element that is some fixed finite field of characteristic CAIRO_PRIME > 263 (CAIRO_PRIME is the prime number of the field), as such Instruction is the representation of the first word of each Cairo instruction. Some instructions spread over two words when they use an immediate value, so representing the first one with this struct is enough. The first word of each instruction consists of: (1) three 16-bit signed integer offsets offdst, offop0, offop1 in the range [−215, 215) encoded using biased representation25; and (2) 15 bits of flags divided into seven Structure of the 63-bit that form the first word of each instruction. @@ -158,7 +158,7 @@ for example the following hexadecimal encoding '0x480680017fff8000, 1,'represent [ap] = 1; ap++ ``` which stores 1 in the direction stored in the ap register and increases it in one to point to the next direction. -we can declare an structure to store the data as follows: +We can declare an structure to store the data as follows: ``` struct Instruction { int64_t off0; @@ -175,7 +175,7 @@ struct Instruction { }; ``` to extract the dst_reg flag we can define a mask 'DST_REG_MASK' with value 0x0001 and and a padding 'DST_REG_OFF' with value 0 because it is the less significant bit, then we can perform the operation -'(((encoded_instr) >> 48) & DST_REG_MASK) >> DST_REG_OFF' to obtain the dst_reg flag. We shifted 48 bits first because there is where the flags start. +```(((encoded_instr) >> 48) & DST_REG_MASK) >> DST_REG_OFF``` to obtain the dst_reg flag. We shifted 48 bits first because there is where the flags start. the code would be as follow, nameing the hex value as encoded_instr: ``` struct Instruction instrunction.dst_register = '(((encoded_instr) >> 48) & DST_REG_MASK) >> DST_REG_OFF' From 7ce827667f2e55478477e8c7e0710ffc54221b72 Mon Sep 17 00:00:00 2001 From: Milton Date: Fri, 4 Aug 2023 12:00:39 -0300 Subject: [PATCH 7/7] Fix comments --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ebc70fc..fae5a9b 100644 --- a/README.md +++ b/README.md @@ -131,8 +131,8 @@ Go through the main parts of a compiled program `Json` file. `data` field with i ### Program decoding Once the VM has been fed with a compiled cairo program it has to be decoded. The decoder takes as input the hexadecimal number in little endian format that represents the instruction an generates an Instruction struct with it. -The CPU native word is a field element that is some fixed finite field of characteristic CAIRO_PRIME > 263 (CAIRO_PRIME is the prime number of the field), as such Instruction is the representation of the first word of each Cairo instruction. Some instructions spread over two words when they use an immediate value, so representing the first one with this struct is enough. -The first word of each instruction consists of: (1) three 16-bit signed integer offsets offdst, offop0, offop1 in the range [−215, 215) encoded using biased representation25; and (2) 15 bits of flags divided into seven +The CPU native word is a field element that is some fixed finite field of characteristic CAIRO_PRIME > 2^63 (CAIRO_PRIME is the prime number of the field), as such Instruction is the representation of the first word of each Cairo instruction. Some instructions spread over two words when they use an immediate value, so representing the first one with this struct is enough. +The first word of each instruction consists of: (1) three 16-bit signed integer offsets offdst, offop0, offop1 in the range [−2^15, 2^15) encoded using biased representation25; and (2) 15 bits of flags divided into seven Structure of the 63-bit that form the first word of each instruction. See Cairo whitepaper, page 32 - https://eprint.iacr.org/2021/1063.pdf.