Aggiunte a documentazione

IMPLEMENTATION.md

@@ -22,6 +22,33 @@ for i, o in enumerate(ops):
     o.set_value(arr[i])
 ```
 
+# Assembling, labels and functions
+
+The enclosed assembler recognizes **labels** and **functions**. The **main** function has to be defined. Here is an example:
+
+```
+def foo:
+addi r0, 0x3
+movi r1, 0x1
+retn
+
+def main: # main is mandatory
+movi r0, 0xff
+nope
+jmpi label # jumping to label
+nope
+addi r0, 0x2
+label: # defining a label
+grmn
+call foo
+shit
+```
+In order to jump to a label or a function, an *immediate type* jump has to be used (`JMPI, JPBI, JPAI`, etc...). The `CALL` instruction is used to save where the program has to restore its execution after a function call.
+
+The assembler puts the **main** function as first in the code section meaning its code will be located at offset 0. Every other function will follow.
+
+![Functions]
+
 # Instruction set
 The instruction set I come out wants to be "RISC"-oriented but I have to admit that it is more "CISC"-oriented *(Confusing Instruction Set Computer)*.
 Also, since I decided that every instruction had to be 4 chars long, some name adaptation may have encountered some quality issue... (yes, `POP`, I'm looking at you)
@@ -96,141 +123,141 @@ Effect: R1 is decremented by R0
 ```
 ## ANDB
 ```
-Full name:
+Full name: AND Byte (immediate)
-Usage:
+Usage: ANDB R0, 0xFF
-Effect: 
+Effect: R0's lower byte is and-ed by 0xFF.
 ```
 ## ANDW
 ```
-Full name:
+Full name: AND Word (immediate)
-Usage:
+Usage: ANDW R0, 0xFFFF
-Effect: 
+Effect: R0's is and-ed by 0xFFFF.
 ```
 ## ANDR
 ```
-Full name:
+Full name: AND Register
-Usage:
+Usage: ANDR R0, R1
-Effect: 
+Effect: R0 is and-ed by R1.
 ```
 ## YORB
 ```
-Full name:
+Full name: (Y)OR Byte (immediate)
-Usage:
+Usage: YORB R0, 0xFF
-Effect: 
+Effect: R0's lower byte is or-ed by 0xFF.
 ```
 ## YORW
 ```
-Full name:
+Full name: (Y)OR Word (immediate)
-Usage:
+Usage: YORW R0, 0xFFFF
-Effect: 
+Effect: R0's is or-ed by 0xFFFF.
 ```
 ## YORR
 ```
-Full name:
+Full name: (Y)OR Register
-Usage:
+Usage: YORR R0, R1
-Effect: 
+Effect: R0 is or-ed by R1.
 ```
 ## XORB
 ```
-Full name:
+Full name: XOR Byte (immediate)
-Usage:
+Usage: XORB R0, 0xFF
-Effect: 
+Effect: R0's lower byte is xor-ed by 0xFF.
 ```
 ## XORW
 ```
-Full name:
+Full name: XOR Word (immediate)
-Usage:
+Usage: XORW R0, 0xFFFF
-Effect: 
+Effect: R0 is xor-ed by 0xFFFF.
 ```
 ## XORR
 ```
-Full name:
+Full name: XOR Register
-Usage:
+Usage: XORR R0, R1
-Effect: 
+Effect: R0 is xor-ed by R1.
 ```
 ## NOTR
 ```
-Full name:
+Full name: NOT Register
-Usage:
+Usage: NOTR R0
-Effect: 
+Effect: Bitwise negation of R0.
 ```
 ## MULI
 ```
-Full name:
+Full name: MULtiply by Immediate
-Usage:
+Usage: MULI R0, 2
-Effect: 
+Effect: R0 is multiplied by 2.
 ```
 ## MULR
 ```
-Full name:
+Full name: MULtiply by Register
-Usage:
+Usage: MULR R0, R1
-Effect: 
+Effect: R0 is multiplied by R1.
 ```
 ## DIVI
 ```
-Full name:
+Full name: DIVide by Immediate
-Usage:
+Usage: DIVI R0, 2
-Effect: 
+Effect: R0 is divided by 2. The remainder is not stored.
 ```
 ## DIVR
 ```
-Full name:
+Full name: DIVide by Register 
-Usage:
+Usage: DIVR R0, R1
-Effect: 
+Effect: R0 is divided by R1. The remainder is not stored.
 ```
 ## SHLI
 ```
-Full name:
+Full name: SHift Left by Immediate
-Usage:
+Usage: SHLI R0, 2
-Effect: 
+Effect: Effect: R0 is shifted 2 bits to the left.
 ```
 ## SHLR
 ```
-Full name:
+Full name: SHift Left by Register
-Usage:
+Usage: SHLR R0, R1
-Effect: 
+Effect: R0 is shifted R1 bits to the left.
 ```
 ## SHRI
 ```
-Full name:
+Full name: SHift Right by Immediate
-Usage:
+Usage: SHRI R0, 2
-Effect: 
+Effect: Effect: R0 is shifted 2 bits to the right.
 ```
 ## SHRR
 ```
-Full name:
+Full name: SHift Right by Register
-Usage:
+Usage: SHRR R0, R1
-Effect: 
+Effect: R0 is shifted R1 bits to the right.
 ```
 ## PUSH
 ```
-Full name:
+Full name: PUSH
-Usage:
+Usage: PUSH R1
-Effect: 
+Effect: Pushes R1 on top of the stack.
 ```
 ## POOP
 ```
-Full name:
+Full name: POP (+ 1 free 'O')
-Usage:
+Usage: POOP R1
-Effect: 
+Effect: Retrieves the element on top of the stack and puts it in R1.
 ```
 ## CMPB
 ```
-Full name:
+Full name: CoMPare register to Byte
-Usage:
+Usage: CMPB R0, 0xff
-Effect: 
+Effect: Compares R0 to 0xFF (R0's lower byte) and sets the ZF and CF flags.
 ```
 ## CMPW
 ```
-Full name:
+Full name: CoMPare register to Word
-Usage:
+Usage: CMPW R0, 0xffff
-Effect: 
+Effect: Compares R0 to 0xFFFF and sets the ZF and CF flags.
 ```
 ## CMPR
 ```
-Full name:
+Full name: CoMPare register to Register
-Usage:
+Usage: CMPR R0, R1
-Effect: 
+Effect: Compares R0 to R1 and sets the ZF and CF flags.
 ```
 ## JMPI
 ```
@@ -320,7 +347,7 @@ Effect: Does nothing for an instruction
 ```
 Full name: GeRMaNo
 Usage: GRMN
-Effect: Sets every register (excluding IP and RP) to GG
+Effect: Sets every register (excluding IP and RP) to GG (0x4747)
 ```
 ## DEBG
 ```
@@ -331,3 +358,4 @@ Effect: Prints the status of every register and the flags
 
 [Instruction]: ./res/instruction.png
 [Structure]: ./res/structure.png
+[Functions]: ./res/functions.png

README.md

@@ -11,7 +11,7 @@ The design and the implementation behind Pasticciotto are not state-of-the-art b
 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 [INSTRUCTION_SET.MD](IS) 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!
+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! 
@@ -44,4 +44,4 @@ OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 DEALINGS IN THE SOFTWARE.
 ```
 [Pasticciotto]: ./res/pasticciotto.png
-[IS]: ./INSTRUCTION_SET.md
+[IMPL]: ./IMPLEMENTATION.md