Romasm Instruction Set - Documentation

Arithmetic Instructions

Instruction	Opcode	Operands	Description
`ADD`	A	reg1, reg2	Adds reg2 to reg1: `reg1 = reg1 + reg2`
`SUB`	S	reg1, reg2	Subtracts reg2 from reg1: `reg1 = reg1 - reg2`
`MUL`	M	reg1, reg2	Multiplies reg1 by reg2: `reg1 = reg1 * reg2`
`DIV`	DI	reg1, reg2	Divides reg1 by reg2 (integer division): `reg1 = reg1 / reg2`
`MOD`	MO	reg1, reg2	Modulo operation: `reg1 = reg1 % reg2`
`INC`	I	reg	Increments register by 1: `reg = reg + 1`
`DEC`	D	reg	Decrements register by 1: `reg = reg - 1`

Example:

LOAD R0, 10
LOAD R1, 5
ADD R0, R1    ; R0 = 15
MUL R0, R1    ; R0 = 75
DIV R0, R1    ; R0 = 15

Bitwise & Shift Instructions

Instruction	Opcode	Operands	Description
`SHL`	SL	reg1, reg2	Shift left (multiply by 2^n): `reg1 = reg1 << reg2`
`SHR`	SR	reg1, reg2	Shift right (divide by 2^n): `reg1 = reg1 >> reg2`

Example:

LOAD R0, 8
LOAD R1, 2
SHL R0, R1    ; R0 = 32 (8 << 2 = 8 * 4)
SHR R0, R1    ; R0 = 8 (32 >> 2 = 32 / 4)

Memory Instructions

Instruction	Opcode	Operands	Description
`LOAD`	L	reg, value/reg/[addr]	Loads a value into a register. Can load immediate value, copy from another register, or load from memory address.
`STORE`	X	reg, reg/[addr]	Stores register value to another register or memory address.

Example:

LOAD R0, 42           ; R0 = 42 (immediate)
LOAD R1, R0            ; R1 = R0 (copy register)
LOAD R2, [100]         ; R2 = memory[100]
STORE R0, R1           ; R1 = R0
STORE R0, [100]        ; memory[100] = R0

Control Flow Instructions

Instruction	Opcode	Operands	Description
`JMP`	V	label/address	Unconditional jump to label or address
`JEQ`	JE	label/address	Jump if equal (last CMP result was equal)
`JNE`	JN	label/address	Jump if not equal
`JLT`	JL	label/address	Jump if less than
`JGT`	JG	label/address	Jump if greater than
`JLE`	JLE	label/address	Jump if less than or equal
`JGE`	JGE	label/address	Jump if greater than or equal
`CMP`	C	reg1, reg2/value	Compares two values and sets flags for conditional jumps

Example:

LOAD R0, 10
LOAD R1, 5
CMP R0, R1
JGT greater        ; Jump if R0 > R1
; R0 <= R1
JMP end
greater:
; R0 > R1
end:

Function Call Instructions

Instruction	Opcode	Operands	Description
`CALL`	CA	label/function	Calls a function or subroutine. Pushes return address to stack.
`RET`	R	(none)	Returns from function. Pops return address from stack.
`PUSH`	P	reg	Pushes register value onto stack
`POP`	PO	reg	Pops value from stack into register

Example:

; Call stdlib function
LOAD R0, 3000        ; angle in degrees (scaled by 100)
CALL sin             ; Call sin function from stdlib
; Result in R0

; Custom function
my_function:
    PUSH R1
    ; function body
    POP R1
    RET

I/O Instructions

Instruction	Opcode	Operands	Description
`PRINT`	PR	reg	Prints register value to output console

Example:

LOAD R0, 42
PRINT R0             ; Outputs: 42

Canvas Drawing Instructions

Instruction	Opcode	Operands	Description
`CLEAR`	CLR	(none)	Clears the canvas
`MOVE`	MOV	reg_x, reg_y	Moves drawing cursor to (x, y) without drawing
`DRAW`	DRW	reg_x, reg_y	Draws a line from current position to (x, y)
`STROKE`	STR	(none)	Strokes the current path (renders the drawn lines)

Example:

; Draw a line from (-5, -5) to (5, 5)
CLEAR
LOAD R0, -500        ; x1 (scaled by 100)
LOAD R1, -500        ; y1
MOVE R0, R1          ; Move to start point
LOAD R0, 500         ; x2
LOAD R1, 500         ; y2
DRAW R0, R1          ; Draw line
STROKE               ; Render it

System Instructions (RomanOS)

These instructions are available when building bootable OS programs with RomanOS. They compile to real x86 system instructions.

Instruction	Opcode	Operands	Description
`INT`	INT	number	Software interrupt (e.g., BIOS calls: `INT 0x10` for video, `INT 0x16` for keyboard)
`IRET`	IRET	(none)	Return from interrupt
`CLI`	CLI	(none)	Clear interrupt flag (disable interrupts)
`STI`	STI	(none)	Set interrupt flag (enable interrupts)
`HLT`	HLT	(none)	Halt CPU (used in bootable OS to stop execution)
`NOP`	NOP	(none)	No operation (useful for loops and delays)
`IN`	IN	reg, port	Input from I/O port
`OUT`	OUT	port, reg	Output to I/O port
`MOV_SEG`	MSEG	seg_reg, src	Move to segment register (DS, SS, ES, etc.)
`LOAD8`	L8	reg, src	Load 8-bit value (for byte operations)
`STORE8`	X8	src, dst	Store 8-bit value

Example: BIOS Interrupt Call

; Clear screen using BIOS interrupt 0x10
LOAD R0, 3          ; Video mode 3 (text mode)
MOV AX, R0          ; Set up AX register
INT 0x10            ; Call BIOS video interrupt

Note: These instructions require RomanOS to compile to x86. In the browser VM, some may be emulated or unavailable.

String Instructions (Efficient Memory Operations)

String instructions provide efficient memory operations for OS development. They automatically handle pointer increment/decrement based on the Direction Flag. Support REP prefix for repeated operations.

Instruction	Opcode	Operands	Description
`MOVS`	MOVS	dest, src	Move string: Copy memory from [src] to [dest]. Uses RSI/ESI (source) and RDI/EDI (destination). Increments/decrements automatically.
`STOS`	STOS	dest, value	Store string: Store value to [dest]. Uses RDI/EDI (destination) and RAX/EAX/AX (value). Perfect for clearing/filling memory (framebuffers).
`LODS`	LODS	dest_reg, src	Load string: Load from [src] to dest_reg. Uses RSI/ESI (source) and RAX/EAX/AX (destination).
`CMPS`	CMPS	addr1, addr2	Compare string: Compare [addr1] with [addr2]. Uses RSI/ESI and RDI/EDI. Sets flags for comparison.
`SCAS`	SCAS	addr, value	Scan string: Search for value in [addr]. Uses RDI/EDI (address) and RAX/EAX/AX (value). Useful for finding null terminators.

Example: Clear Framebuffer

; Efficiently clear framebuffer using REP STOS
CLD                      ; Clear direction flag (forward)
LOAD R0, framebuffer_base
LOAD R0, [R0]            ; R0 = framebuffer address
LOAD R1, 0x00000000      ; Black color (32-bit RGBA)
LOAD R2, 1920000         ; Pixel count (e.g., 800x600x4 bytes)
REP STOS R0, R1          ; Repeat: Store R1 to [R0], repeat R2 times

REP Prefix: Can use REP, REPE (or REPZ), REPNE (or REPNZ). REP repeats while RCX > 0. REPE repeats while equal. REPNE repeats while not equal.

Flag Control Instructions

Control CPU flags, especially the Direction Flag (required for string instructions) and save/restore flags for interrupt handlers.

Instruction	Opcode	Operands	Description
`CLD`	CLD	(none)	Clear Direction Flag: Set forward direction (increment pointers) for string instructions
`STD`	STD	(none)	Set Direction Flag: Set backward direction (decrement pointers) for string instructions
`PUSHF`	PUSHF	(none)	Push Flags: Save flags register to stack (essential for interrupt handlers)
`POPF`	POPF	(none)	Pop Flags: Restore flags register from stack
`TEST`	TEST	reg1, reg2/imm	Test bits: Performs bitwise AND but doesn't store result, only sets flags. Useful for conditional logic without modifying operands.

Example: Bit Testing

; Check if bit 0 is set without modifying register
LOAD R0, 5
LOAD R1, 1
TEST R0, R1      ; R0 & R1 (sets flags, doesn't modify R0)
JNE bit_set      ; Jump if bit was set
; Bit was not set
JMP done
bit_set:
; Bit was set
done:

SETcc Instructions (Set Byte on Condition)

SETcc instructions convert flag states to boolean byte values (0 or 1). Perfect for converting conditional logic to values without branching.

Instruction	Opcode	Operands	Description
`SETZ`	SETZ	reg	Set to 1 if Zero flag set (equal), 0 otherwise
`SETNZ`	SETNZ	reg	Set to 1 if Zero flag clear (not equal), 0 otherwise
`SETL`	SETL	reg	Set to 1 if Less (signed comparison), 0 otherwise
`SETG`	SETG	reg	Set to 1 if Greater (signed comparison), 0 otherwise
`SETLE`	SETLE	reg	Set to 1 if Less or Equal (signed), 0 otherwise
`SETGE`	SETGE	reg	Set to 1 if Greater or Equal (signed), 0 otherwise
`SETC`	SETC	reg	Set to 1 if Carry flag set, 0 otherwise
`SETNC`	SETNC	reg	Set to 1 if Carry flag clear, 0 otherwise

Example: Convert Condition to Boolean

; Check if value equals 10, store result as boolean
LOAD R0, 10
LOAD R1, 10
CMP R0, R1      ; Compare (sets flags)
SETZ R2         ; R2 = 1 if equal, 0 if not equal

; Now R2 contains boolean result (1 = true, 0 = false)
; Can be used in calculations without branching

Extended Arithmetic Instructions

Extended arithmetic operations for multi-precision calculations and negation.

Instruction	Opcode	Operands	Description
`ADC`	ADC	dest, src	Add with Carry: dest = dest + src + carry_flag. Essential for multi-word arithmetic.
`SBB`	SBB	dest, src	Subtract with Borrow: dest = dest - src - borrow_flag. Used with ADC for multi-word subtraction.
`NEG`	NEG	reg	Negate: reg = -reg (two's complement negation). Faster than subtracting from zero.

Example: Multi-Word Addition

; Add two 128-bit numbers (R0:R1 + R2:R3, result in R0:R1)
; Low word addition (may set carry)
ADD R1, R3      ; R1 = low word sum (sets carry if overflow)
; High word addition (with carry)
ADC R0, R2      ; R0 = high word sum + carry

; Negate a value
LOAD R0, 42
NEG R0          ; R0 = -42

Conditional Move Instructions (CMOVcc)

Conditional moves eliminate branches for simple conditionals, improving performance by avoiding pipeline flushes. Move value only if condition is true.

Instruction	Opcode	Operands	Description
`CMOVZ`	CMOVZ	dest, src	Move if Zero: dest = src if zero flag set
`CMOVNZ`	CMOVNZ	dest, src	Move if Not Zero: dest = src if zero flag clear
`CMOVL`	CMOVL	dest, src	Move if Less: dest = src if less (signed)
`CMOVG`	CMOVG	dest, src	Move if Greater: dest = src if greater (signed)
`CMOVLE`	CMOVLE	dest, src	Move if Less or Equal: dest = src if less or equal (signed)
`CMOVGE`	CMOVGE	dest, src	Move if Greater or Equal: dest = src if greater or equal (signed)
`CMOVC`	CMOVC	dest, src	Move if Carry: dest = src if carry flag set
`CMOVNC`	CMOVNC	dest, src	Move if No Carry: dest = src if carry flag clear

Example: Branchless Conditional Assignment

; Instead of branching:
;   if (R0 == 0) R1 = 100; else R1 = 200;

; Branchless with CMOV:
LOAD R0, 0
LOAD R2, 100
LOAD R3, 200
CMP R0, 0       ; Set flags
CMOVZ R1, R2    ; R1 = R2 if zero (100)
CMOVNZ R1, R3   ; R1 = R3 if not zero (200)

; No branches = better for pipelined CPUs!

Atomic Operations

Atomic operations ensure operations complete without interruption, essential for multi-core synchronization and thread-safe code.

Instruction	Opcode	Operands	Description
`XCHG`	XCHG	dest, src	Exchange: Atomically swaps two values. Useful for lock-free algorithms and register swapping.
`CMPXCHG`	CMPXCHG	dest, src	Compare and Exchange: Atomic operation that compares RAX/EAX/AX with dest, if equal sets dest = src, else sets RAX = dest. Essential for lock-free data structures.

Example: Atomic Swap

; Swap two registers atomically
LOAD R0, 10
LOAD R1, 20
XCHG R0, R1    ; R0 = 20, R1 = 10 (atomic operation)

; Lock-free compare-and-swap
; CMPXCHG requires accumulator (RAX) to be set up properly
LOAD RAX, expected_value
CMPXCHG R0, new_value  ; If R0 == expected: R0 = new_value, else: RAX = R0

Bit Manipulation Instructions

Direct bit-level operations for efficient flag management, bitmaps, and low-level data structures.

Instruction	Opcode	Operands	Description
`BT`	BT	dest, bit_index	Bit Test: Tests a bit and sets carry flag. Doesn't modify the destination.
`BTS`	BTS	dest, bit_index	Bit Test and Set: Tests bit, sets carry flag, then sets the bit to 1.
`BTR`	BTR	dest, bit_index	Bit Test and Reset: Tests bit, sets carry flag, then clears the bit to 0.
`BTC`	BTC	dest, bit_index	Bit Test and Complement: Tests bit, sets carry flag, then toggles the bit.

Example: Bitmap Operations

; Check if bit 5 is set
LOAD R0, bitmap_value
BT R0, 5        ; Test bit 5 (sets carry if set)
JC bit_is_set   ; Jump if carry (bit was set)

; Set a flag bit
LOAD R0, flags
BTS R0, 3       ; Set bit 3, carry = old bit value

; Clear a flag bit
BTR R0, 3       ; Clear bit 3

; Toggle a bit
BTC R0, 3       ; Toggle bit 3

Bit Scan Instructions

Find the index of set bits, useful for finding the first/last set bit in a value (e.g., priority queues, bit allocation).

Instruction	Opcode	Operands	Description
`BSF`	BSF	dest, src	Bit Scan Forward: Finds the index of the first (lowest) set bit in src, stores in dest. Sets zero flag if no bits set.
`BSR`	BSR	dest, src	Bit Scan Reverse: Finds the index of the last (highest) set bit in src, stores in dest. Sets zero flag if no bits set.

Example: Find First Set Bit

; Find the index of the first set bit
LOAD R0, 20     ; Binary: 10100 (bits 2 and 4 set)
BSF R1, R0      ; R1 = 2 (index of first set bit)

; Find the index of the last set bit
BSR R1, R0      ; R1 = 4 (index of last set bit)

; Common use: Find next available resource
LOAD R0, resource_bitmap
BSF R1, R0      ; R1 = index of first free resource
JZ no_resources ; Jump if zero flag (no resources available)

Rotate Instructions

Rotate bits left or right, optionally through the carry flag. Useful for encryption, hash functions, and circular shifts.

Instruction	Opcode	Operands	Description
`ROL`	ROL	reg, count	Rotate Left: Rotates bits left, bit that falls off left end goes to right end.
`ROR`	ROR	reg, count	Rotate Right: Rotates bits right, bit that falls off right end goes to left end.
`RCL`	RCL	reg, count	Rotate Left through Carry: Rotates left including carry flag in rotation.
`RCR`	RCR	reg, count	Rotate Right through Carry: Rotates right including carry flag in rotation.

Example: Circular Bit Rotation

; Rotate 8-bit value left by 2 positions
LOAD R0, 0b11000001  ; Binary: 11000001
ROL R0, 2            ; Result: 00000111 (bits rotated left)

; Rotate with carry (for multi-word rotations)
CLC                  ; Clear carry
LOAD R0, 0b10000000
RCL R0, 1            ; Rotate left through carry: R0 = 0b00000000, CF = 1

; Multi-word rotation (64-bit rotate using 32-bit registers)
; Rotate high word through carry
RCL R0, 1            ; High word: R0 << 1, CF = bit that fell off
; Rotate low word through carry  
RCL R1, 1            ; Low word: R1 << 1, bit 0 = old CF

Arithmetic Instructions

Bitwise & Shift Instructions

Memory Instructions

Control Flow Instructions

Function Call Instructions

I/O Instructions

Canvas Drawing Instructions

System Instructions (RomanOS)

String Instructions (Efficient Memory Operations)

Flag Control Instructions

SETcc Instructions (Set Byte on Condition)

Extended Arithmetic Instructions

Conditional Move Instructions (CMOVcc)

Atomic Operations

Bit Manipulation Instructions

Bit Scan Instructions

Rotate Instructions

Related Documentation