Update assembler/usage

Assembler.md

@@ -1,16 +0,0 @@
-# Pseudo Instructions Reference
-
-| Mnemonic | Args | Description |
-|----------|------|-------------|
-| DB | name, u8[..] | Takes a comma separated list of bytes and inserts them into the binary at a location addressable by 'name' |
-| DH | name, u16[..] | Takes a comma separated list of 16-bit values and inserts them into the binary at a location addressable by 'name' |
-| DW | name, u32[..] | Takes a comma separated list of 32-bit values and inserts them into the binary at a location addressable by 'name' |
-| RESB | name, size | Reserves space for 'size' 8-bit values at a location addressable by 'name' |
-| RESH | name, size | Reserves space for 'size' 16-bit values at a location addressable by 'name' |
-| RESW | name, size | Reserves space for 'size' 32-bit values at a location addressable by 'name' |
-| PUSH | reg | Pushes the value in 'reg' to the stack. Equivalent to: `INC SPR` then `STW register, SPR` |
-| POP | reg | Pops the top value in the stack to 'reg'. Equivalent to: `LDW SPR, register` then `DEC SPR` |
-| LDB | name, reg | Loads the 8-bit value at the address referenced by name into reg. Equivalent to: `LLI varname, reg`, `LUI varname, reg`, `LDB reg, reg` |
-| LDH | name, reg | Loads the top 16-bits of the value at the address referenced by name into reg. Equivalent to: `LLI varname, reg`, `LUI varname, reg`, `LDH (0)reg, reg` |
-| LDW | name, reg | Loads the 32-bit value at the address referenced by name into reg. Equivalent to: `LLI varname, reg`, `LUI varname, reg`, `LDW reg, reg` |
-| LWI | name, reg | Loads the address of 'name' into reg. Equivalent to: `LLI name, reg`, `LUI name, reg` |

assembler%2Fusage.md

@@ -0,0 +1,883 @@
+# DSA Assembly Language Instruction Reference
+
+## Overview
+
+This document provides a comprehensive reference for the DSA (Damn Simple Architecture) assembly language, including all hardware instructions and pseudo-instructions with their syntax variations and usage examples.
+
+## Syntax Conventions
+
+- `reg` - Register operand
+- `imm` - Immediate value (16-bit for I-type instructions)
+- `addr` - Memory address or label
+- `offset` - Memory offset (optional, defaults to 0)
+- `[]` - Optional parameters
+- `|` - Alternative syntax options
+
+## Registers
+
+- general purpose: `rg0-rgf`
+	- be careful when using `rgf` for storing data as some pseduo-instructions may implicitly overwrite this register.
+- special registers:
+	- ``
+## Hardware Instructions
+
+### Data Movement Instructions
+
+#### MOV - Move Register to Register
+
+```assembly
+mov src_reg, dest_reg
+```
+
+**Example:**
+
+```assembly
+mov rg0, rg1        ; Copy value from rg0 to rg1
+mov acc, rg2        ; Copy accumulator to rg2
+```
+
+#### MOVS - Move with Sign Extension
+
+```assembly
+movs src_reg, dest_reg
+```
+
+**Example:**
+
+```assembly
+movs rg0, rg1       ; Copy rg0 to rg1 with sign extension
+```
+
+### Memory Access Instructions
+
+#### Load Instructions
+
+##### LDB - Load Byte
+
+```assembly
+ldb base_reg, dest_reg [, offset]
+ldb label, dest_reg [, offset]
+```
+
+**Examples:**
+
+```assembly
+; Direct register addressing
+ldb rg0, rg1        ; Load byte from address in rg0 to rg1
+ldb rg0, rg1, 5     ; Load byte from (rg0 + 5) to rg1
+
+; Label addressing - expands to multiple instructions
+ldb buffer, rg2     ; Load byte from label 'buffer' to rg2
+```
+
+**Label expansion:** When using a label, `ldb buffer, rg2` expands to:
+
+```assembly
+lli buffer, rg2     ; Load lower 16 bits of buffer address
+lui buffer, rg2     ; Load upper 16 bits of buffer address  
+ldb rg2, rg2        ; Load byte from address in rg2 to rg2
+```
+
+**With offset:** `ldb buffer, rg2, 10` expands to:
+
+```assembly
+lli buffer, rg2     ; Load lower 16 bits of buffer address
+lui buffer, rg2     ; Load upper 16 bits of buffer address
+ldb rg2, rg2, 10    ; Load byte from (rg2 + 10) to rg2
+```
+
+##### LDBS - Load Byte (Sign Extended)
+
+```assembly
+ldbs base_reg, dest_reg [, offset]
+ldbs label, dest_reg [, offset]
+```
+
+**Examples:**
+
+```assembly
+; Direct register addressing
+ldbs rg0, rg1       ; Load sign-extended byte from rg0 to rg1
+ldbs rg0, rg1, 10   ; Load sign-extended byte from (rg0 + 10)
+
+; Label addressing
+ldbs data_array, rg3 ; Load sign-extended byte from 'data_array'
+```
+
+**Label expansion:** `ldbs data_array, rg3` expands to:
+
+```assembly
+lli data_array, rg3 ; Load lower 16 bits of data_array address
+lui data_array, rg3 ; Load upper 16 bits of data_array address
+ldbs rg3, rg3       ; Load sign-extended byte from rg3 to rg3
+```
+
+##### LDH - Load Half-word
+
+```assembly
+ldh base_reg, dest_reg [, offset]
+ldh label, dest_reg [, offset]
+```
+
+**Examples:**
+
+```assembly
+; Direct register addressing
+ldh rg0, rg1        ; Load 16-bit value from rg0 to rg1
+ldh rg0, rg1, 2     ; Load 16-bit value from (rg0 + 2)
+
+; Label addressing
+ldh config_table, rg4 ; Load half-word from 'config_table'
+```
+
+**Label expansion:** `ldh config_table, rg4, 6` expands to:
+
+```assembly
+lli config_table, rg4 ; Load lower 16 bits of config_table address
+lui config_table, rg4 ; Load upper 16 bits of config_table address
+ldh rg4, rg4, 6       ; Load half-word from (rg4 + 6) to rg4
+```
+
+##### LDHS - Load Half-word (Sign Extended)
+
+```assembly
+ldhs base_reg, dest_reg [, offset]
+ldhs label, dest_reg [, offset]
+```
+
+**Examples:**
+
+```assembly
+; Direct register addressing
+ldhs rg0, rg1       ; Load sign-extended 16-bit value
+ldhs rg0, rg1, 4    ; Load from (rg0 + 4) with sign extension
+
+; Label addressing
+ldhs signed_values, rg5 ; Load sign-extended half-word from label
+```
+
+**Label expansion:** `ldhs signed_values, rg5` expands to:
+
+```assembly
+lli signed_values, rg5 ; Load lower 16 bits of signed_values address
+lui signed_values, rg5 ; Load upper 16 bits of signed_values address
+ldhs rg5, rg5          ; Load sign-extended half-word from rg5 to rg5
+```
+
+##### LDW - Load Word
+
+```assembly
+ldw base_reg, dest_reg [, offset]
+ldw label, dest_reg [, offset]
+```
+
+**Examples:**
+
+```assembly
+; Direct register addressing
+ldw rg0, rg1        ; Load 32-bit word from rg0 to rg1
+ldw rg0, rg1, 8     ; Load word from (rg0 + 8)
+
+; Label addressing
+ldw stack, bpr      ; Load stack address into base pointer
+ldw current, rg1    ; Load word from 'current' variable
+```
+
+**Label expansion:** `ldw stack, bpr` expands to:
+
+```assembly
+lli stack, bpr      ; Load lower 16 bits of stack address
+lui stack, bpr      ; Load upper 16 bits of stack address
+ldw bpr, bpr        ; Load word from address in bpr to bpr
+```
+
+#### Store Instructions
+
+##### STB - Store Byte
+
+```assembly
+stb src_reg, base_reg [, offset]
+stb src_reg, label [, offset]
+```
+
+**Examples:**
+
+```assembly
+; Direct register addressing
+stb rg0, rg1        ; Store byte from rg0 to address in rg1
+stb rg0, rg1, 3     ; Store byte to (rg1 + 3)
+
+; Label addressing
+stb acc, buffer     ; Store byte from accumulator to 'buffer'
+stb rg2, output, 5  ; Store byte to (output + 5)
+```
+
+**Label expansion:** When using a label, `stb acc, buffer` expands to:
+
+```assembly
+lli buffer, rgf     ; Load lower 16 bits of buffer address to temp register
+lui buffer, rgf     ; Load upper 16 bits of buffer address to temp register
+stb acc, rgf        ; Store byte from acc to address in rgf
+```
+
+**With offset:** `stb rg2, output, 5` expands to:
+
+```assembly
+lli output, rgf     ; Load lower 16 bits of output address
+lui output, rgf     ; Load upper 16 bits of output address
+stb rg2, rgf, 5     ; Store byte to (rgf + 5)
+```
+
+##### STH - Store Half-word
+
+```assembly
+sth src_reg, base_reg [, offset]
+sth src_reg, label [, offset]
+```
+
+**Examples:**
+
+```assembly
+; Direct register addressing
+sth rg0, rg1        ; Store 16-bit value from rg0
+sth rg0, rg1, 6     ; Store to (rg1 + 6)
+
+; Label addressing
+sth rg3, config_word ; Store half-word to 'config_word'
+sth acc, data_table, 12 ; Store to (data_table + 12)
+```
+
+**Label expansion:** `sth rg3, config_word` expands to:
+
+```assembly
+lli config_word, rgf ; Load lower 16 bits of config_word address
+lui config_word, rgf ; Load upper 16 bits of config_word address
+sth rg3, rgf         ; Store half-word from rg3 to address in rgf
+```
+
+##### STW - Store Word
+
+```assembly
+stw src_reg, base_reg [, offset]
+stw src_reg, label [, offset]
+```
+
+**Examples:**
+
+```assembly
+; Direct register addressing
+stw rg0, rg1        ; Store 32-bit word from rg0
+stw rg0, rg1, 12    ; Store to (rg1 + 12)
+
+; Label addressing
+stw rg1, current    ; Store word to 'current' variable
+stw acc, result_buffer, 8 ; Store accumulator to (result_buffer + 8)
+```
+
+**Label expansion:** `stw rg1, current` expands to:
+
+```assembly
+lli current, rgf    ; Load lower 16 bits of current address
+lui current, rgf    ; Load upper 16 bits of current address
+stw rg1, rgf        ; Store word from rg1 to address in rgf
+```
+
+**Complex example with label and offset:** `stw acc, array_base, 16` expands to:
+
+```assembly
+lli array_base, rgf ; Load lower 16 bits of array_base address
+lui array_base, rgf ; Load upper 16 bits of array_base address
+stw acc, rgf, 16    ; Store accumulator to (rgf + 16)
+```
+
+### Immediate Load Instructions
+
+#### LLI - Load Lower Immediate
+
+```assembly
+lli imm, dest_reg
+```
+
+**Examples:**
+
+```assembly
+lli 0x1234, rg0     ; Load 0x1234 into lower 16 bits of rg0
+lli 100, acc        ; Load 100 into lower 16 bits of accumulator
+```
+
+#### LUI - Load Upper Immediate
+
+```assembly
+lui imm, dest_reg
+```
+
+**Examples:**
+
+```assembly
+lui 0xABCD, rg0     ; Load 0xABCD into upper 16 bits of rg0
+lui 200, acc        ; Load 200 into upper 16 bits of accumulator
+```
+
+### Jump Instructions
+
+#### JMP - Unconditional Jump
+
+```assembly
+jmp addr [, offset_reg]
+jmp imm, offset_reg
+```
+
+**Examples:**
+
+```assembly
+jmp start           ; Jump to label 'start'
+jmp 4, ret          ; Jump to address (4 + ret register)
+jmp loop            ; Jump to label 'loop'
+```
+
+#### Conditional Jumps
+
+##### JEQ - Jump if Equal
+
+```assembly
+jeq addr [, offset_reg]
+```
+
+**Examples:**
+
+```assembly
+jeq end             ; Jump to 'end' if equal flag set
+jeq 8, ret          ; Jump to (8 + ret) if equal
+```
+
+##### JNE - Jump if Not Equal
+
+```assembly
+jne addr [, offset_reg]
+```
+
+**Examples:**
+
+```assembly
+jne loop            ; Jump to 'loop' if not equal
+jne continue        ; Jump to 'continue' if not equal
+```
+
+##### JGT - Jump if Greater Than
+
+```assembly
+jgt addr [, offset_reg]
+```
+
+**Examples:**
+
+```assembly
+jgt start           ; Jump to 'start' if greater than flag set
+jgt positive        ; Jump to 'positive' if greater
+```
+
+##### JGE - Jump if Greater or Equal
+
+```assembly
+jge addr [, offset_reg]
+```
+
+##### JLT - Jump if Less Than
+
+```assembly
+jlt addr [, offset_reg]
+```
+
+##### JLE - Jump if Less or Equal
+
+```assembly
+jle addr [, offset_reg]
+```
+
+### Arithmetic Instructions
+
+#### ADD - Addition
+
+```assembly
+add src1_reg, src2_reg, dest_reg
+```
+
+**Examples:**
+
+```assembly
+add rg0, rg1, rg2   ; rg2 = rg0 + rg1
+add rg1, rg2, acc   ; acc = rg1 + rg2
+```
+
+#### SUB - Subtraction
+
+```assembly
+sub src1_reg, src2_reg, dest_reg
+```
+
+**Examples:**
+
+```assembly
+sub rg0, rg1, rg2   ; rg2 = rg0 - rg1
+sub acc, rg1, acc   ; acc = acc - rg1
+```
+
+#### IADD - Immediate Addition
+
+```assembly
+iadd src_reg, imm [, dest_reg]
+```
+
+**Examples:**
+
+```assembly
+iadd rg0, 10        ; rg0 = rg0 + 10
+iadd rg0, 5, rg1    ; rg1 = rg0 + 5
+```
+
+#### ISUB - Immediate Subtraction
+
+```assembly
+isub src_reg, imm [, dest_reg]
+```
+
+**Examples:**
+
+```assembly
+isub rg0, 7         ; rg0 = rg0 - 7
+isub rg0, 3, rg1    ; rg1 = rg0 - 3
+```
+
+#### INC - Increment
+
+```assembly
+inc reg
+```
+
+**Examples:**
+
+```assembly
+inc rg0             ; rg0 = rg0 + 1
+inc spr             ; Increment stack pointer
+```
+
+#### DEC - Decrement
+
+```assembly
+dec reg
+```
+
+**Examples:**
+
+```assembly
+dec rg0             ; rg0 = rg0 - 1
+dec rg1             ; Decrement rg1
+```
+
+### Bitwise Operations
+
+#### AND - Bitwise AND
+
+```assembly
+and src1_reg, src2_reg, dest_reg
+```
+
+**Examples:**
+
+```assembly
+and rg0, rg1, rg2   ; rg2 = rg0 & rg1
+```
+
+#### OR - Bitwise OR
+
+```assembly
+or src1_reg, src2_reg, dest_reg
+```
+
+#### XOR - Bitwise XOR
+
+```assembly
+xor src1_reg, src2_reg, dest_reg
+```
+
+#### NOT - Bitwise NOT
+
+```assembly
+not src_reg, dest_reg
+```
+
+**Examples:**
+
+```assembly
+not rg0, rg1        ; rg1 = ~rg0
+```
+
+#### NAND - Bitwise NAND
+
+```assembly
+nand src1_reg, src2_reg, dest_reg
+```
+
+#### NOR - Bitwise NOR
+
+```assembly
+nor src1_reg, src2_reg, dest_reg
+```
+
+#### XNOR - Bitwise XNOR
+
+```assembly
+xnor src1_reg, src2_reg, dest_reg
+```
+
+### Shift Operations
+
+#### SHL - Shift Left
+
+```assembly
+shl reg, shift_amount
+```
+
+**Examples:**
+
+```assembly
+shl rg0, 2          ; Shift rg0 left by 2 bits
+shl acc, 4          ; Shift accumulator left by 4 bits
+```
+
+#### SHR - Shift Right
+
+```assembly
+shr reg, shift_amount
+```
+
+**Examples:**
+
+```assembly
+shr rg0, 3          ; Shift rg0 right by 3 bits
+```
+
+### Comparison and Control
+
+#### CMP - Compare
+
+```assembly
+cmp reg1, reg2
+```
+
+**Examples:**
+
+```assembly
+cmp rg0, zero       ; Compare rg0 with zero register
+cmp rg1, rg2        ; Compare rg1 with rg2
+```
+
+### System Instructions
+
+#### HLT - Halt
+
+```assembly
+hlt
+```
+
+**Examples:**
+
+```assembly
+hlt                 ; Stop processor execution
+```
+
+#### NOP - No Operation
+
+```assembly
+nop
+```
+
+**Examples:**
+
+```assembly
+nop                 ; Do nothing for one cycle
+```
+
+#### INT - Interrupt
+
+```assembly
+int interrupt_code
+```
+
+**Examples:**
+
+```assembly
+int 0x21            ; Trigger interrupt 0x21
+```
+
+#### IRT - Interrupt Return
+
+```assembly
+irt
+```
+
+**Examples:**
+
+```assembly
+irt                 ; Return from interrupt
+```
+
+## Pseudo-Instructions
+
+### Data Definition
+
+#### DB - Define Bytes
+
+```assembly
+db name: value1 [, value2, ...]
+```
+
+**Examples:**
+
+```assembly
+db message: "Hello World", 0
+db values: 10, 20, 30, 0xFF
+db fib_count: 10
+```
+
+#### DH - Define Half-words
+
+```assembly
+dh name: value1 [, value2, ...]
+```
+
+**Examples:**
+
+```assembly
+dh numbers: 1000, 2000, 3000
+dh coordinates: 0x1234, 0x5678
+```
+
+#### DW - Define Words
+
+```assembly
+dw name: value1 [, value2, ...]
+```
+
+**Examples:**
+
+```assembly
+dw stack: 0x10000
+dw display: 0x20000
+dw buffer: 0x8000, 0x9000
+```
+
+### Memory Reservation
+
+#### RESB - Reserve Bytes
+
+```assembly
+resb name: size
+```
+
+**Examples:**
+
+```assembly
+resb buffer: 256    ; Reserve 256 bytes
+```
+
+#### RESH - Reserve Half-words
+
+```assembly
+resh name: size
+```
+
+**Examples:**
+
+```assembly
+resh array: 100     ; Reserve space for 100 half-words
+```
+
+#### RESW - Reserve Words
+
+```assembly
+resw name: size
+```
+
+**Examples:**
+
+```assembly
+resw heap: 1024     ; Reserve space for 1024 words
+```
+
+### Stack Operations
+
+#### PUSH - Push to Stack
+
+```assembly
+push reg
+```
+
+**Examples:**
+
+```assembly
+push rg0            ; Push rg0 value onto stack
+push pcx            ; Push program counter
+push ret            ; Push return address
+```
+
+#### POP - Pop from Stack
+
+```assembly
+pop reg
+```
+
+**Examples:**
+
+```assembly
+pop rg0             ; Pop top stack value into rg0
+pop ret             ; Pop return address
+```
+
+### Memory Access Shortcuts
+
+#### LWI - Load Word Immediate (Address)
+
+```assembly
+lwi name, reg
+```
+
+**Examples:**
+
+```assembly
+lwi string, rg1     ; Load address of 'string' into rg1
+lwi buffer, rg0     ; Load address of 'buffer' into rg0
+```
+
+### Module System
+
+#### INCLUDE - Include Module
+
+```assembly
+include module_name "path"
+```
+
+**Examples:**
+
+```assembly
+include print "../resources/dsa/print.dsa"
+include fib "../resources/dsa/fib.dsa"
+```
+
+## Complete Example Program
+
+Here's a complete example showing various instruction usage, including label-based memory operations:
+
+```assembly
+include print "../resources/dsa/print.dsa"
+include fib "../resources/dsa/fib.dsa"
+
+; Data definitions
+dw stack: 0x10000
+dw display: 0x20000
+dw current: 0x20000
+db message: "Computing Fibonacci sequence...", 0
+db result_buffer: 0, 0, 0, 0    ; Space for 32-bit result
+dh config_values: 100, 200, 300
+
+init:
+    ; Load stack address using label expansion
+    ldw stack, bpr          ; Expands to: lli stack,bpr; lui stack,bpr; ldw bpr,bpr
+    mov bpr, spr            ; Set stack pointer
+
+    ; Store display address to current using label expansion  
+    ldw display, rg0        ; Load display address
+    stw rg0, current        ; Expands to: lli current,rgf; lui current,rgf; stw rg0,rgf
+
+start:
+    ; Load message address for printing
+    lwi message, rg1        ; Load message address directly
+    
+    ; Print message
+    push rg1                ; Push message address
+    push pcx                ; Push return address
+    jmp print::print        ; Call print function
+    
+    ; Calculate 25th Fibonacci number
+    lli 25, rg0             ; Load 25 into rg0
+    push rg0                ; Push argument
+    push pcx                ; Push return address
+    jmp fib::fib_n          ; Call Fibonacci function
+    
+    ; Store result using label expansion
+    stw acc, result_buffer  ; Expands to: lli result_buffer,rgf; lui result_buffer,rgf; stw acc,rgf
+    
+    ; Load and modify config value
+    ldh config_values, rg2, 2 ; Load second config value (offset 2)
+                              ; Expands to: lli config_values,rg2; lui config_values,rg2; ldh rg2,rg2,2
+    iadd rg2, 50            ; Add 50 to the config value
+    sth rg2, config_values, 2 ; Store back to second position
+                              ; Expands to: lli config_values,rgf; lui config_values,rgf; sth rg2,rgf,2
+    
+    hlt                     ; Halt execution
+
+; Example of label addressing in a loop
+copy_data:
+    lli 0, rg0              ; Counter = 0
+    lli 10, rg1             ; Loop limit = 10
+    
+copy_loop:
+    ; Load byte from source array
+    ldb source_array, rg2, rg0  ; Load source_array[counter]
+                                 ; Note: This would need array indexing logic in practice
+    
+    ; Store to destination array  
+    stb rg2, dest_array, rg0     ; Store to dest_array[counter]
+    
+    inc rg0                      ; counter++
+    cmp rg0, rg1                 ; Compare with limit
+    jlt copy_loop                ; Continue if less than limit
+    
+    jmp 4, ret                   ; Return
+
+; Data arrays for copy example
+db source_array: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
+resb dest_array: 10             ; Reserve 10 bytes for destination
+```
+
+## Label Addressing Summary
+
+**Load Instructions with Labels:**
+
+- All load instructions (`ldb`, `ldbs`, `ldh`, `ldhs`, `ldw`) can use labels
+- They expand into 3 instructions: `lli` → `lui` → original load instruction
+- The destination register is used as a temporary for the address calculation
+
+**Store Instructions with Labels:**
+
+- All store instructions (`stb`, `sth`, `stw`) can use labels
+- They expand into 3 instructions: `lli` → `lui` → original store instruction
+- The `rgf` register is used as a temporary for the address calculation
+- Source register remains unchanged
+
+**Key Points:**
+
+- Label expansion happens at assembly time, not runtime
+- Offsets work the same way with labels as with direct register addressing
+- The temporary register (`rgf` for stores) should not be used for other purposes during store operations
+- Load operations modify the destination register during address calculation
+
+## Register Usage
+
+The DSA architecture includes several special registers:
+
+- `acc` - Accumulator register
+- `zero` - Always contains zero
+- `pcx` - Program counter
+- `spr` - Stack pointer
+- `bpr` - Base pointer
+- `ret` - Return address register
+- `rg0`-`rg15` - General purpose registers
+
+## Addressing Modes
+
+1. **Register Direct**: `mov rg0, rg1`
+2. **Immediate**: `lli 100, rg0`
+3. **Memory Direct**: `ldw buffer, rg0`
+4. **Memory with Offset**: `ldw rg0, rg1, 8`
+5. **Label/Symbol**: `jmp start`