Registers & Memory - Documentation

Registers

Romasm has 9 general-purpose registers, named R0 through R8, which map to Roman numerals I through IX.

Register Name	Roman Numeral	Internal Name	Usage
`R0`	I	`I`	General purpose, often used for return values
`R1`	II	`II`	General purpose, often used for constants
`R2`	III	`III`	General purpose
`R3`	IV	`IV`	General purpose
`R4`	V	`V`	General purpose
`R5`	VI	`VI`	General purpose
`R6`	VII	`VII`	General purpose
`R7`	VIII	`VIII`	General purpose
`R8`	IX	`IX`	General purpose

Register Conventions

While all registers are general-purpose, common conventions include:

R0: Often used for function arguments and return values
R1: Frequently used for constants (like 1, 2, 100, 1000)
R2-R4: Temporary values and intermediate calculations
R5-R8: Additional temporary storage

Memory

Romasm has a memory system that allows you to store and retrieve values at specific addresses.

Memory Addressing

Access memory using square brackets [address]:

; Store value to memory
LOAD R0, 42
STORE R0, [100]    ; Store R0 to memory address 100

; Load value from memory
LOAD R1, [100]     ; Load from memory address 100 into R1

Memory Characteristics

Memory addresses are integers (0, 1, 2, ...)
Memory is sparse - only accessed addresses are allocated
Uninitialized memory returns 0
Memory persists for the duration of program execution

Stack

Romasm includes a stack for function calls and temporary storage.

Stack Operations

; Push a value onto the stack
PUSH R0           ; Push R0's value onto stack

; Pop a value from the stack
POP R1            ; Pop value from stack into R1

Stack Usage

Function Calls: The CALL instruction automatically pushes the return address
Register Preservation: Save registers before function calls
Temporary Storage: Store values temporarily when registers are full

Example: Function with Stack

my_function:
    ; Save registers we'll modify
    PUSH R2
    PUSH R3
    
    ; Function body
    LOAD R2, 10
    LOAD R3, 20
    ADD R2, R3
    
    ; Restore registers
    POP R3
    POP R2
    
    RET

Program Counter

The Program Counter (PC) tracks the current instruction being executed. It's automatically managed by the VM, but you can control it with jump instructions:

JMP - Unconditional jump
JEQ, JNE, etc. - Conditional jumps
CALL - Jump to function (saves return address)
RET - Return from function (restores PC from stack)

Flags

The VM maintains flags that are set by the CMP (compare) instruction:

equal: Set when two values are equal
lessThan: Set when first value < second value
greaterThan: Set when first value > second value

These flags are used by conditional jump instructions:

LOAD R0, 10
LOAD R1, 5
CMP R0, R1        ; Compare R0 with R1, sets flags
JGT greater      ; Jump if R0 > R1 (uses greaterThan flag)
; R0 <= R1
JMP done
greater:
; R0 > R1
done: