Aggiunti esempi

README.md

@@ -7,21 +7,114 @@ I wanted to experiment with VM obfuscation since it was a topic that caught my a
 
 The design and the implementation behind Pasticciotto are not state-of-the-art but hey, it works!
 
-# What about the challenge?
-I do not want to spoil the challenge for those that haven't completed it yet. Check out some write-up online!
-
-# Instruction set
-Check out the file [IMPLEMENTATION.MD](IMPL) to understand how the VM works and which operations it can do! Watch out for some spoilers if you haven't completed the challenge though!
-
 # Why "Pasticciotto"?
 In Italian, "Pasticciotto" has two meanings! 
 
 The first one is **"little mess"** which perfectly describes how I put up this project. The second one is a typical dessert from Southern Italy, Salento! It's filled with cream! Yum!
 
+# Quick start
+
+You can use `pasticciotto` in your own binary! It's easy to do!
+
+## Assemble!
+Let's say you want to run this `C` code into `pasticciotto`:
+```c
+void main() {
+    uint16_t i, a, b;
+    a = 0;
+    b = 0x10;
+
+    for (i = 0; i < b; i++) {
+        a += b;
+    }
+    return;
+}
+```
+
+It can be translated into this `pasticciotto`'s assembly snippet:
+```
+$ cat example.pstc
+def main:
+movi r0, 0x0  # a
+movi r1, 0x10 # b
+movi s1, 0x0  # i
+loop:
+addr r0, r1
+addi s1, 1
+cmpr s1, r1
+jpbi loop
+shit
+```
+Let's assemble it with key `HelloWorld`:
+```
+$ python3 assembler.py HelloWorld example.pstc example_assembled.pstc
+```
+
+Now we are ready to embed the VM in a `.c` program:
+```c++
+#include "vm/vm.h"
+#include <fstream>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int main(int argc, char *argv[]) {
+    */
+    In order to create the bytecode for pasticciotto, you can use
+    the assembler in the assembler/ directory. You can include it with
+    `xxd -i example_assembled.pstc`
+    */
+    unsigned char example_assembled_pstc[] = {
+    0x32, 0x00, 0x00, 0x00, 0x32, 0x01, 0x10, 0x00, 0x32, 0x05, 0x00, 0x00,
+    0xaf, 0x01, 0xcf, 0x05, 0x01, 0x00, 0x8b, 0x51, 0xc5, 0x0c, 0x00, 0x0c
+    };
+    unsigned int example_assembled_pstc_len = 24;
+    unsigned char key[] = {
+    0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x0a
+    };
+
+
+    puts("I should try to eat a pasticciotto...\n");
+    VM vm(key, example_assembled_pstc, example_assembled_pstc_len);
+    vm.run();
+    return 0;
+}
+```
+That's it!
+
+## Accessing to the VM's sections and registers
+
+The VM **data / code / stack sections** are represented through the `VMAddrSpace` object. It is defined [here](vm/vmas.h). The **registers** are in a `uint16_t` array in the `VM` object defined [here](vm/vm.h).
+
+```c++
+void foo() {
+    // creating the VM with some code
+    VM vm(key, code, codelen);
+
+    // accessing the data section
+    printf("First data byte: 0x%x", VM.as.data[0]);
+    // accessing the code section
+    printf("First code byte: 0x%x", VM.as.code[0]);    
+    // accessing the stack section
+    printf("First stack byte: 0x%x", VM.as.stack[0]);
+    // accessing the IP register
+    printf("The IP is: 0x%x", VM.regs[IP]);
+    return;
+}
+```
+
+
+# What about the challenge?
+You can find the client and the server under the `polictf/` directory. I do not want to spoil the challenge for those that haven't completed it yet so you won't find the "specifics" of it. Check out some write-up online!
+
+# Implementation details
+Check out the file [IMPLEMENTATION.MD](IMPL) to understand how the VM works and which operations it can do! Watch out for some spoilers if you haven't completed the challenge though!
+
 # Contributions
 
-Any contribution is **very** welcome! Feel free to open issues and pull requests!
+I wanted to polish the VM even more but I haven't got the time to do it. There are rough edges for sure!
 
+Any contribution is **very** welcome! Feel free to open issues and pull requests!
 
 # License
 ```

vm/vm.h

@@ -15,8 +15,6 @@ private:
   // VARIABLES
   ////////////////////////
 
-  uint16_t regs[0xb];
-  flags_t flags;
 
   ////////////////////////
   // FUNCTIONS
@@ -81,6 +79,8 @@ private:
 public:
   VM(uint8_t *key);
   VM(uint8_t *key, uint8_t *code, uint32_t codesize);
+  uint16_t regs[0xb];
+  flags_t flags;
   VMAddrSpace as;
   void status(void);
   void run();