R3X CPU documentation and Instruction Manual

CPU Summary

The R3X CPU is a 32-bit little-endian, stack-based, RISC-like CPU, which is one of the central components of the R3X runtime. The R3X CPU can also be classfied as a hybrid between stack and register based design. In general, however, most of the operations are done over stack.

Stack

The R3X CPU contains two stacks: One is known as the 'data stack', where most operations are done, the second stack is known as the 'address or call' stack which contains return addresses of calls.

Registers

The R3X CPU contains 21 registers [R0-R20] which can be used to temporarily store data, these can be operated on using instructions which accept an 8-bit immediate known as 'register index'. The following is a table of register indexes:
Register 8-bit Register Index Value
R0 0
R1 1
R2 2
R3 3
R4 4
R5 5
R6 6
R7 7
R8 8
R9 9
R10 10
R11 11
R12 12
R13 13
R14 14
R15 1
R16 16
R17 17
R18 18
R19 19
R20 20
There is another register called the 'FLAGS' register, which contains the CPU Flags, the following is a table which shows the structure of the 32-bit FLAGS register. The FLAGS register can be retrieved by the 'pushf' instruction and set by the 'popf' instruction.
Bit no. Description
1 E (EQUAL)
2 G (GREATER THAN)
3 L (LESSER THAN)
4 Z (ZERO)
5 EXF (EXCEPTION)
All bits not mentioned are presumed to be reserved.

Syscalls

The 'syscall' instruction is used to call a VM specific function, these include things like output, input, file I/O, multithreading, etc. The following is table of values to be passed as an 8-bit immediate to the 'syscall' instruction.
Syscall Name Syscall Value (to be passed to 'syscall' as immediate) Description
SYSCALL_PUTS 0x0 Print a string to stdout, whose address is pushed last to data stack.
SYSCALL_PUTI 0x1 Print the integer to stdout, which is pushed last to data stack.
SYSCALL_PUTF 0x2 Print the float to stdout, which is pushed last to data stack.
SYSCALL_GLUPDATE 0x3 Call the VM's video refresh function.
SYSCALL_GETC 0x4 Read from keyboard buffer, and push character to data stack. Does not wait, instead pushes 0 if no character was read.
SYSCALL_PUTCH 0x5 Print ASCII character to stdout, whose value was pushed last to data stack.
SYSCALL_ATOI 0x6 Convert string, whose address is pushed last to data stack, and push the result to data stack.
SYSCALL_ALLOC 0x7 Allocate memory, with size, whose value is pushed last to data stack, and push the allocated address to data stack.
SYSCALL_DISPATCH 0x8 Create a new thread, and start execution from address which was pushed last to data stack.
SYSCALL_LOADDYNAMIC 0x9 Load a dynamic library, whose location is in a string, whose address is pushed last to data stack, and push the library handle to data stack, which is to be used when calling a dynamic library function using the 'calldynamic' instruction.
SYSCALL_GETCLOCK 0x10 Push the number of CPU clock ticks to data stack.
SYSCALL_GETCLOCKSPERSEC 0x11 Push the number of CPU ticks in one second to data stack.

Exceptions

Exceptions in R3X can be thrown using the 'throw' instruction. You can set exception handlers using 'catch'. How these instructions work is given in the instruction manual below. These instructions require something called an 'exception ID' to identify what exception to throw, and what exception has occured, the following is a list of exception IDs.
Exception Name Exception ID Exception Description
INVALID_ACCESS 0 Thrown when a program attempts to access a region of memory which is inaccessible or protected or non-existent.
INVALID_OPCODE 1 Thrown when the CPU encounters an invalid opcode.
R_EXCEP 2 User defined exception.
INVALID_ARITH 3 Thrown when the CPU attempts to do an invalid arithmetic operation. (division by 0 for example)

Instructions

(Note: The top of stack is always empty, the last pushed value is always one place below the top of stack!)

push

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
push 0x01, byte Push an immediate to data stack. 32-bit constant 0x01 (BYTE) [DWORD]

pop

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
pop 0x02, byte Pop a 32-bit integer from stack. Value trashed. Nothing 0x02 (BYTE)

add

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
add 0x03, byte Add two numbers on top of data stack, and push result to data stack. Nothing 0x03 (BYTE)

sub

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
sub 0x04, byte Subtract the number on top of data stack from the number pushed second last. And push result to data stack. Nothing 0x04 (BYTE)

mul

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
mul 0x05, byte Multiply two numbers on top of data stack, and push result to data stack. Nothing 0x05 (BYTE)

div

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
div 0x06, byte Divide the number on top of data stack by the number pushed second last. And push result to data stack. Nothing 0x06 (BYTE)

fadd

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
fadd 0x07, byte Add the IEEE754 float on top of data stack to the IEEE754 float pushed second last. And push the IEEE754 float result to data stack. Nothing 0x07 (BYTE)

fsub

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
fsub 0x08, byte Subtract the IEEE754 float on top of data stack from the IEEE754 float pushed second last. And push the IEEE754 float result to data stack. Nothing 0x08 (BYTE)

fmul

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
fmul 0x09, byte Multiply the IEEE754 float on top of data stack with the IEEE754 float pushed second last. And push the IEEE754 float result to data stack. Nothing 0x09 (BYTE)

fdiv

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
fdiv 0x0A, byte Divide the IEEE754 float on top of data stack by the IEEE754 float pushed second last. And push the IEEE754 float result to data stack. Nothing 0x0A (BYTE)

cmp

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
cmp 0x0A, byte Compare the two values on top of data stack. Let A be the value pushed second last, a B be the value pushed last. If A > B, Set 'G' (Greater Than) flag to true. If A = B, Set 'E' (Equal) flag to true. If A < B, Set L (Lesser Than) flag to true. The comparsion is unsigned. Nothing 0x0B (BYTE)

je

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
je 0x0C, byte Jump to a 32-bit address, if Equal flag is set, given by the immediate. This jump is absolute. 32-bit Constant 0x0C (BYTE) [DWORD]

jl

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
jl 0x0D, byte Jump to a 32-bit address, if Lesser than flag is set, given by the immediate. This jump is absolute. 32-bit Constant 0x0C (BYTE) [DWORD]

jg

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
jg 0x0E, byte Jump to a 32-bit address, if Greater than flag is set, given by the immediate. This jump is absolute. 32-bit Constant 0x0E (BYTE) [DWORD]

jz

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
jz 0x11, byte Jump to a 32-bit address, if Zero flag is set, given by the immediate. This jump is absolute. 32-bit Constant 0x11 (BYTE) [DWORD]

jmp

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
jmp 0x20, byte Jump to a 32-bit address given by the immediate. This jump is absolute. 32-bit Constant 0x20 (BYTE) [DWORD]

and

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
and 0x12, byte Do a bitwise AND on second last number pushed to data stack, by the value of number on top of stack bits. Nothing 0x12 (BYTE)

or

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
or 0x13, byte Do a bitwise OR on second last number pushed to data stack, by the value of number on top of stack bits. Nothing 0x13 (BYTE)

xor

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
xor 0x14, byte Do a bitwise XOR on second last number pushed to data stack, by the value of number on top of stack bits. Nothing 0x14 (BYTE)

dup

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
dup 0x15, byte Duplicate the value on top of data stack, and push the result to data stack. Nothing 0x15 (BYTE)

loads

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
loads 0x17, byte Load value from number of positions below top of data stack, given by immediate and push it to the data stack. Push to Data Stack (Data Stack[Top of Data Stack - immediate]) 32-bit constant 0x17 (BYTE) [DWORD]

load

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
load 0x18, byte Load DWORD from address on top of data stack. Nothing 0x18 (BYTE)

store

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
store 0x19, byte Store DWORD which is on top of data stack, to address whose value is pushed second last. Nothing 0x19 (BYTE)

exit

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
exit 0x1F, byte Exit VM and all subsystems (if called from main thread, Else exit current thread. Nothing 0x1F (BYTE)

syscall

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
syscall 0x21, byte Call VM internal function whose 8-bit index is given by the immediate. 8-bit Constant 0x21 (BYTE) [BYTE]

loadlib

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
loadlib 0x22, byte Load native library, whose location is stored in a string whose address must be on top of stack. Nothing 0x22 (BYTE)

libexec

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
libexec 0x23, byte Call a function from the native library, whose name is in a string whose address must be pushed last on data stack, and whose library location is stored in the address which is pushed second last on the data stack. loadlib with the same library locations must be called beforehand. Nothing 0x23 (BYTE)

call

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
call 0x24, byte Jump to address given by immediate, and push return address to call stack (next instruction in memory). 32-bit Constant 0x24 (BYTE) [DWORD]

ret

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
ret 0x25, byte Pop address from call stack, and jump to that address. Nothing 0x25 (BYTE)

pusha

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
pusha 0x26, byte Push the 32-bit immediate to call stack. 32-bit immediate 0x26 (BYTE) [DWORD]

popa

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
popa 0x27, byte Pop last pushed item from call stack. 32-bit immediate 0x27 (BYTE)

memcpy

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
memcpy 0x28, byte Copy memory from address pushed second last to data stack, to destination pushed third last with size pushed last (i.e. on top of) to data stack. Nothing 0x28 (BYTE)

lods'x'

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
lodsb, lodsw, lodsd 0x29 (lodsb) or 0x62 (lodsw) or 0x31 (lodsd), byte Load data from address pointed by register R0 to register R1 with size either byte, word, or dword determined by the suffix of the mnemonic, b, w, and d respectively. Nothing 0x29 (lodsb) or 0x62 (lodsw) or 0x31 (lodsd) (BYTE)

stos'x'

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
stosb, stosw, stosd 0x2A (stosb) or 0x61 (stosw) or 0x2E (stosd), byte Store value of register R1 to address pointed by register R0 with size either byte, word, or dword determined by the suffix of the mnemonic, b, w, and d respectively. Nothing 0x2A (stosb) or 0x61 (stosw) or 0x2E (stosd) (BYTE)

cmps'x'

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
cmpsb, cmpsw, cmpsd 0x2F (cmpsb) or 0x63 (cmpsw) or 0x30 (cmpsd), byte Compare value of register R1 with value at address pointed by R3, with size either byte, word, or dword determined by the suffix of the mnemonic, b, w, and d respectively. Nothing 0x2F (cmpsb) or 0x63 (cmpsw) or 0x30 (cmpsd) (BYTE)

loadr

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
loadr 0x2B, byte Load register pointed by 8-bit register index (immediate), with value pointed by the 32-bit immediate. 8-bit Register Index, 32-bit Constant 0x2B (BYTE) [BYTE] [DWORD]

pushr

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
pushr 0x2C, byte Push value of register index, to data stack, pointed by 8-bit register index (immediate) 8-bit Register Index 0x2C (BYTE) [BYTE]

popr

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
popr 0x2D, byte Pop value from data stack, and store it in register pointed by the 8-bit register index (immediate). 8-bit Register Index 0x2D (BYTE) [BYTE]

incr

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
incr 0x32, byte Increment value of register by 1, pointed by 8-bit register index (immediate). 8-bit Register Index 0x32 (BYTE) [BYTE]

decr

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
decr 0x33, byte Decrement value of register by 1, pointed by 8-bit register index (immediate). 8-bit Register Index 0x33 (BYTE) [BYTE]

int *

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
int 0x34, byte Cause a CPU interrupt, whose index is given by the 8-bit ISR index (immediate). 8-bit ISR Index 0x34 (BYTE) [BYTE]

loadi *

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
loadi 0x35, byte Set interrupt vector, given by 8-bit ISR Index (immediate), to address given by the 32-bit address (immediate). 8-bit ISR Index, 32-bit address 0x35 (BYTE) [BYTE] [DWORD]

not

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
not 0x36, byte Do a bitwise NOT to value pushed last on data stack, and push result. Nothing 0x36 (BYTE)

neg

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
neg 0x37, byte Do a bitwise NEG (negation) on value pushed last to data stack and push result. Nothing 0x37 (BYTE)

pushar

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
pushar 0x38, byte Push value of register index, to call stack, pointed by 8-bit register index (immediate) 8-bit Register Index 0x38 (BYTE) [BYTE]

popar

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
popar 0x39, byte Pop value from call stack, and store it in register pointed by the 8-bit register index (immediate). 8-bit Register Index 0x39 (BYTE) [BYTE]

shr

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
shr 0x4A, byte Do a SHR (Right Bit shift) operation on value pushed second last on data stack, by number of bits pushed last, and push result on data stack. Nothing 0x4A (BYTE)

shl

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
shl 0x4B, byte Do a SHL (Left Bit shift) operation on value pushed second last on data stack, by number of bits pushed last, and push result on data stack. Nothing 0x4B (BYTE)

calldynamic

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
calldynamic 0x53, byte Call a dynamic library function, whose library handle is pushed second last to data stack, and name is pushed last to data stack. Nothing 0x53 (BYTE)
(Note: The library handle can be retrived by calling 'syscall SYSCALL_LOADDYNAMIC'.);

fxxx (trignometric function)

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
fsin, fcos, ftan 0x56 (fsin), 0x57 (fcos) or 0x58 (ftan), byte Evaluates the sine, cosine or tangent, depending upon the suffix sin, cos, and tan respectively, of the IEEE754 float pushed last to stack and push result to data stack, IEEE754 float. (in radians) Nothing 0x56 (fsin), 0x57 (fcos) or 0x58 (ftan) (BYTE)

axxx (inverse trignometric function)

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
asin, acos, atan 0x59 (asin), 0x5A (acos) or 0x5B (atan), byte Evaluates the inverse sine, cosine or tangent, depending upon the suffix sin, cos, and tan respectively, of the IEEE754 float pushed last to stack, and push result to data stack, IEEE754 float. (in radians) Nothing 0x59 (asin), 0x5A (acos) or 0x5B (atan) (BYTE)

fpow

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
fpow 0x5C, byte Raise the IEEE754 float pushed second last to stack to the power of IEEE754 float pushed last, and push the result to data stack, which is a IEEE754 float. Nothing 0x5C (BYTE)

mod

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
mod 0x5D, byte Do a modulus operation on value pushed second last to data stack by value pushed last to data stack, and push result to data stack. Explaination: Push to Data Stack (Remainder of (Data Stack [Top - 1], [Top])) Nothing 0x5D (BYTE)

fmod

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
fmod 0x5E, byte Do a modulus operation on IEEE754 float pushed second last to data stack by IEEE754 float pushed last to data stack, and push result to data stack, IEEE754 float. Same as mod, but for IEEE754 floating point numbers. Nothing 0x5E (BYTE)

rconv

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
rconv 0x5F, byte Convert angles to radians. The angle value must be pushed to stack and should be a IEEE754 floating point number. The result is pushed to stack. Nothing 0x5F (BYTE)

aconv

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
aconv 0x60, byte Convert radians to angles. The radian value must be pushed to stack and should be a IEEE754 floating point number. The result is pushed to stack. Nothing 0x60 (BYTE)

cmps

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
cmps 0x67, byte Same as cmp, but comparsion is signed. Nothing 0x67 (BYTE)

popn

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
popn 0x68, byte Pop and trash, 'n' number of items from stack, where 'n' is equal to value of 32-bit immediate. 32-bit constant 0x68 (BYTE) [DWORD]

pushf

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
pushf 0x69, byte Push FLAGS register to data stack. Nothing 0x69 (BYTE)

popf

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
popf 0x6A, byte Pop value from data stack and set it to FLAGS register. Nothing 0x6A (BYTE)

tern

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
tern 0x6B, byte Do a ternary operation on stack. The third last pushed value on data stack must be a boolean, if boolean is true then the second last value will be popped out from data stack, if boolean is false then the value last pushed to data stack will be popped out. Nothing 0x6B (BYTE)

ror

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
ror 0x4C, byte Do a ROR (Rotate bits right) operation on value pushed second last on data stack, by number of bits, whose value is pushed last. Nothing 0x4C (BYTE)

rol

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
ror 0x4D, byte Do a ROR (Rotate bits left) operation on value pushed second last on data stack, by number of bits, whose value is pushed last. Nothing 0x4D (BYTE)

catch

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
catch 0x6C, byte Set exception handler, the ID of the exception which is to be handled (given in the CPU description above) must be pushed second last to data stack, and the address of the handler to be set must be pushed last. When an exception occurs the CPU will jump to this address, and set EXF (EXception Flag) to true. Nothing 0x6C (BYTE)

handle

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
handle 0x6E, byte Handle exception, that is, set EXF to false. This is must be put at the end of a handler, just before return. Nothing 0x6E (BYTE)

throw

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
throw 0x6D, byte Throw exception. The type of exception (exception ID) to be throw must be on top of stack. (Set exception ID's in the CPU description section) Nothing 0x6D (BYTE)

stores

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
stores 0x6F, byte Replace the value to number of positions below top of data stack, given by the value of the immediate, by value pushed last to stack. In other words: Data Stack [ Top of Data Stack - Value of immediate ] = Data Stack [ Top of Stack ] 32-bit constant 0x6F (BYTE) [DWORD]

loadsr

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
loadsr 0x70, byte Load value from number of positions below top of data stack, given by the value of the register whose index is given by the immediate and push it to the data stack. In other words: Push to Data Stack ( Data Stack [ Top of Data Stack - Value of Register specified by immediate] ) 8-bit register index 0x70 (BYTE) [BYTE]

storesr

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
loadsr 0x71, byte Replce the value to number of positions below top of data stack, given by the value of the register whose index is given by the immediate, by value pushed last to stack. In other words: Data Stack [ Top of Data Stack - Value of Register specified by immediate ] = Data Stack [ Top of Stack ] 8-bit register index 0x71 (BYTE) [BYTE]

set'xx'

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
sete or setne or setg or setl 0x72 (sete) or 0x73 (setne) 0x74 (setg) or 0x75 (setl), byte Set the register whose index is given by the 8-bit register index immediate to 0x0 if equal is set, or equal is unset, or lesser than flag is set or greater than flag is set, depending upon the suffix, which can be e, ne, g or l, respectively. 8-bit register index 0x72 (sete), 0x73 (setne), 0x74 (setg), 0x75 (setl) (BYTE) [BYTE]

f'xxx'h (trignometric function)

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
fsinh or fcosh or ftanh 0x76 (fsinh) or 0x77 (fcosh) or 0x78 (ftanh), byte Evaluates the hyperbolic sine, cosine or tangent, depending upon the suffix sinh, cosh, and tanh respectively, of the IEEE754 float pushed last to stack and push result to data stack, IEEE754 float. (in radians) Nothing 0x76 (fsinh), 0x77 (fcosh), 0x78 (ftanh) (BYTE)

fabs

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
fabs 0x79, byte Take absolute value of the IEEE754 float last pushed to data stack, and push the result to data stack. Nothing 0x79 (BYTE)

floor

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
floor 0x7A, byte Do a 'floor' operation on the IEEE754 float pushed to data stack, and push the result to data stack. Nothing 0x7A (BYTE)

ceil

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
fabs 0x7B, byte Do a 'ceil' operation on the IEEE754 float pushed to data stack, and push the result to data stack. Nothing 0x7B (BYTE)

a'xxx'h (trignometric function)

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
asinh or acosh or atanh 0x7C (asinh) or 0x7D (acosh) or 0x7E (atanh), byte Evaluates the inverse hyperbolic sine, cosine or tangent, depending upon the suffix sinh, cosh, and tanh respectively, of the IEEE754 float pushed last to stack and push result to data stack, IEEE754 float. (in radians) Nothing 0x7C (asinh), 0x7D (acosh), 0x7E (atanh) (BYTE)

fconv

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
fconv 0x7F, byte Convert integer pushed to data stack to IEEE754 float, and push result to data stack. Nothing 0x7F (BYTE)

iconv

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
fconv 0x7F, byte Convert IEEE754 pushed to data stack to 32-bit integer, and push result to data stack. Values after decimal point will be lost due to lack of precision. Nothing 0x7F (BYTE)

jmpl

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
jmpl 0x82, byte Jump to a 32-bit address given by the immediate. This jump is relative. 32-bit Constant 0x82 (BYTE) [DWORD]

jel

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
jel 0x83, byte Jump to a 32-bit address, if equal flag is set, given by the immediate. This jump is relative. 32-bit Constant 0x83 (BYTE) [DWORD]

jgl

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
jgl 0x84, byte Jump to a 32-bit address, if greater than flag is set, given by the immediate. This jump is relative. 32-bit Constant 0x84 (BYTE) [DWORD]

jll

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
jll 0x85, byte Jump to a 32-bit address, if lesser than flag is set, given by the immediate. This jump is relative. 32-bit Constant 0x85 (BYTE) [DWORD]

jzl

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
jzl 0x87, byte Jump to a 32-bit address, if zero flag is set, given by the immediate. This jump is relative. 32-bit Constant 0x87 (BYTE) [DWORD]

puship

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
puship 0x86, byte Push current IP address to data stack. Nothing 0x86 (BYTE)

ars

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
ars 0x89, byte Do an 'arithmetic right shift' operation on value pushed last to data stack, by number of bits pushed second last to stack. Nothing 0x89 (BYTE)

break

Instruction mnemonic Opcode and Opcode Size Description Arguments Encoding
break 0x8A, byte VM Specific 'break' instruction. Current implementation will switch to the debugger. Nothing 0x8A (BYTE)

R3X Macro Instructions

Macro instructions are higher level instructions which aid the programmer and compiler to produce shorter code which can then be expanded by the assembler. The following are the list of available R3X macro instructions:

.text

Macro Instruction mnemonic Description Arguments Expansion
.text { ... } Place code within brackets under text section of the binary None None

.data

Macro Instruction mnemonic Description Arguments Expansion
.data { ... } Place data within brackets under data section of the binary None None

.bss

Macro Instruction mnemonic Description Arguments Expansion
.bss { ... } Place reserved bytes within brackets under bss section of the binary None None

declare_bss_entry

Macro Instruction mnemonic Description Arguments Expansion
declare_bss_entry entry_name Declare a 4-byte entry in the BSS section of the binary Name of Label used to reference entry None

extern

Macro Instruction mnemonic Description Arguments Expansion
extern function_name, "lib_name" Declare external function in import section of binary Name of externally referenced function, Path of library containing the said function. None

externcall

Macro Instruction mnemonic Description Arguments Expansion
externcall function_name Call an external function from a dyanmic library Name of externally referenced function pushr R1
loadrm dword, R20, import_section.lib_name ; Load address of referenced library in R20
; The import section is filled by VM on load, containing the address of the library.
; This is essential as it helps the library know where it is in RAM.
loadrm dword, R1, import_section.func_addr ; Load address of function
push return_addr
pushr R1
ret
return_addr:
popr R1

loadrr

Macro Instruction mnemonic Description Arguments Expansion
loadrr dest_register,source_register Set destination register to source register. Destination Register Index (8-bit), Source Register Index (8-bit) pushr dest_reg
popr source_reg

pushstring

Macro Instruction mnemonic Description Arguments Expansion
pushstring "string" Pushes address of string on stack. A string push string_addr
.data {
string_addr: db "string"
}

loadrm

Macro Instruction mnemonic Description Arguments Expansion
loadrm word_size,dest_register,memory_addr Copy from memory address of give word size to register. word size: can be one of the following: dword (32-bit), word (16-bit), byte (8-bit)
Destination Register Index (8-bit), 32-bit memory address		 pushr R0
loadr R0, memaddr
if word size == byte
lodsb
else if word size == word
lodsw
else if word size == dword
lodsd
end if
loadrr dest_register, R1
popr R0

R3X Calling Convention

The R3X Calling convention is the standard convention by which REX programs are supposed to communicate to external / internal methods. It is totally stack based. The arguments are pushed in an ascending order (based on when they occur) on the stack, as opposed to the reverse way of pushing arguments which is seen in most other calling conventions. This effectively means that the first argument will be pushed first, followed by the second, then the third. Hence, for this to work properly the callee must have an idea of how many arguments are in total in order to retrieve them. The caller must also increment the data stack by 4 items, this space is mostly used by the caller to save certain registers if they are modified by the callee. The return value of the callee is stored in R7. An example is given below (in assembly): 
	...
	push 1
	push 2
	push 3
	; Push 4 items to stack.
	; They can be regs as well, if you want to save their values
	push 0
	push 0
	push 0
	push 0
	
	call add3numbers
	
	popn 4
	; Pop out the number of args on stack
	popn 3
	...
function add3numbers
	; load first argument from stack
	loadr R8, 4+3
	loadsr R8
	loadr R7, R8
	; Load second argument from stack
	loadr R8, 4+2
	loadsr R8
	addrr R7, R8
	; Load third argument from stack
	loadr R8, 4+1
	loadsr R8
	addr R7, R8
	; Return
	ret
endfunction
	...