Incomplete

This section is embarassingly incomplete. You can try looking at samples directory (containing roughly 4KLOC of sample Viua VM code [with comments]) if you feel that something is missing.

Instruction set

Below you can find a complete Viua VM's instruction set reference. Every instruction is described and some examples of usage are given.

Instructions are presented below in groups. Inside each group, they are listed in alphabetical order. Descriptions presented here are only high-level overviews. To read full documentation for an instrction go to its page.

How to read an instruction's documentation?

Documentation consists of several parts: syntax (describes syntax and operands structure of the instruction), semantics (describes what the instruction does), exceptions (lists possible exceptions thrown by the instruction), examples (shows example usage), notes (additional notes for the instruction).

Opcode group: arithmetic

add

Performs arithmetic addition. Both operand numbers can be of different types, type of result is determined by result type specifier.

Canonical form: add Output:r-op Lhs:r-op Rhs:r-op

div

Performs arithmetic division.

Canonical form: div output:r-op lhs:r-op rhs:r-op

fstore

Puts a floating-point number inside a register.

Canonical form: fstore output:r-op :floating-point-literal

idec

Decrements an integer by one.

Canonical form: idec target:r-op

iinc

Increments an integer by one.

Canonical form: iinc target:r-op

istore

Puts a 64 bit signed integer into a register.

Canonical form: istore :r-op :integer

izero

Puts a 64 bit signed integer with the value of 0 into a register.

Canonical form: izero :r-op

mul

Multiplies left-hand operand by right-hand operand.

Canonical form: mul output:r-op lhs:r-op rhs:r-op

sub

Performs subtraction.

Canonical form: sub output:r-op lhs:r-op rhs:r-op

Opcode group: bits

ashl

Perform a arithmetic shift left.

Canonical form: ashl out:r-op source:r-op offset:r-op

ashr

Perform a arithmetic shift right.

Canonical form: ashr out:r-op source:r-op offset:r-op

bitand

Perform bitwise and of two bit strings.

Canonical form: bitand destination:r-op lhs:r-op rhs:r-op

bitat

Get value of a specific bit inside a bit string.

Canonical form: bitat destination:r-op source-bits:r-op index:r-op

bitnot

Negate a bit string.

Canonical form: bitnot destination:r-op source:r-op

bitor

Perform bitwise or of two bit strings.

Canonical form: bitor destination:r-op lhs:r-op rhs:r-op

bits

Create a bit string value.

Canonical form: bits destination:r-op value:bits-literal

bitset

Set a bit inside a bit string.

Canonical form: bitset target:r-op index:r-op value:boolean-literal

bitxor

Perform a bitwise xor.

Canonical form: bitxor destination:r-op lhs:r-op rhs:r-op

rol

Rotate bits to the left.

Canonical form: rol source:r-op offset:r-op

ror

Rotate bits to the right.

Canonical form: ror source:r-op offset:r-op

shl

Perform a logical shift left.

Canonical form: shl out:r-op source:r-op offset:r-op

shr

Perform a logical shift right.

Canonical form: shr out:r-op source:r-op offset:r-op

Opcode group: calls

arg

Fetches value from arguments register set.

Canonical form: arg destination:r-op parameter-slot:index

argc

Returns number of arguments passed to this function. DEPRECATED

Canonical form: argc output:r-op

call

Calls a function.

Canonical form: call output:r-op|void function-name:atom|r-op

defer

Calls a function when current frame is being discarded.

Canonical form: defer function-name:atom|r-op

frame

Prepares an empty frame for a function call.

Canonical form: frame number-of-parameters:index number-of-local-registers:index

msg

Calls a function of a type using dynamic dispatch (method call).

Canonical form: msg return-value:r-op|void function-name:atom|r-op

pamv

Move a value to parameter slot.

Canonical form: pamv parameter-slot:index source:r-op

param

Copy value to parameter slot.

Canonical form: param parameter-slot:index source:r-op

return

Returns from a call.

Canonical form: return

tailcall

Performs a tail call.

Canonical form: tailcall function:atom|r-op

Opcode group: casts

ftoi

Casts a floating-point number to an integer.

Canonical form: ftoi destination:r-op source:r-op

itof

Casts an integer value to a floating-point value.

Canonical form: itof destination:r-op source:r-op

stof

Casts string to a floating point number.

Canonical form: stof destination:r-op source:r-op

stoi

Casts string to an integer.

Canonical form: stoi destination:r-op source:r-op

Opcode group: closures

capture

Captures a reference to a value for use inside a closure. References are transparent to user-code, and are automatically resolved by the runtime. Using references implies a switch from scope-based resource management into reference-counting scheme; the switch is done on a per-value basis.

Canonical form: capture affected-closure:r-op target-register-inside-closure:index source:r-op

capturecopy

Captures copy of a value for use inside a closure.

Canonical form: capturecopy affected-closure:r-op target-register-inside-closure:index source:r-op

capturemove

Moves a value from surrounding scope into a closure.

Canonical form: capturemove affected-closure:r-op target-register-inside-closure:index source:r-op

closure

Creates a closure from a function.

Canonical form: closure :r-op function-name:atom

Opcode group: concurrency

join

Joins another process.

Canonical form: join result:r-op|void pid-to-join:r-op :timeout

process

Spawns a new process.

Canonical form: process returned-pid-of-new-process:r-op|void function-name:atom|r-op

receive

Receives a message.

Canonical form: receive result:r-op|void :timeout

self

Returns PID of current process.

Canonical form: self pid-of-self:r-op

send

Sends a message to another process.

Canonical form: send pid-to-send-to:r-op message:r-op

Opcode group: control-flow

if

Checks if the source value is true or false, and takes a branch based on the state of said value.

Canonical form: if condition:r-op jump-if-true:instruction-index jump-if-false:instruction-index

jump

Jumps to a different instruction.

Canonical form: jump :instruction-index

Opcode group: error-handling

catch

Registers a type-catcher in a try-frame.

Canonical form: catch "type-name" handler-block-name:atom

draw

Fetch exception value from exception register and put it in a general-purpose register.

Canonical form: draw destination:r-op

enter

Enters a block of instructions.

Canonical form: enter block-name:atom

leave

Leave a block of instructions.

Canonical form: leave

throw

Throws a value up the stack to signal an exception.

Canonical form: throw :r-op

try

Perpare exception frame.

Canonical form: try

watchdog

Sets up watchdog function for a process.

Canonical form: watchdog function-name:atom

Opcode group: functional

function

Create a function object and put it in a register.

Canonical form: function output:r-op function-name:atom

Opcode group: logic

and

Calculates Boolean "and" of two values.

Canonical form: and Result:r-op Lhs:r-op Rhs:r-op

bool

Converts any value into a Boolean value. NOT IMPLEMENTED

Canonical form: bool output:r-op input:r-op

eq

Checks if two numeric values are equal to each other.

Canonical form: eq result:r-op lhs:r-op rhs:r-op

gt

Determines if a numeric value is greater-than in relation to some other numeric value.

Canonical form: gt output:r-op lhs:r-op rhs:r-op

gte

Determines if a numeric value is greater-than-or-equal-to in relation to some other numeric value.

Canonical form: gte output:r-op lhs:r-op rhs:r-op

lt

Determines if a numeric value is less-than in relation to some other numeric value.

Canonical form: lt output:r-op lhs:r-op rhs:r-op

lte

Determines if a numeric value is less-than-or-equal-to in relation to some other numeric value.

Canonical form: lte output:r-op lhs:r-op rhs:r-op

not

Calculates Boolean negation of a value.

Canonical form: not destination:r-op source:r-op

or

Calculates Boolean alternative of a value.

Canonical form: or result:r-op lhs:r-op rhs:r-op

Opcode group: miscellaneous

echo

Print value to standard output without adding newline character.

Canonical form: echo :r-op

halt

Halths the VM.

Canonical form: halt

import

Import a foreign library into the machine.

Canonical form: import "library-name"

nop

Does nothing. It can be used as a filler instruction, or as a placeholder. Executing a nop instruction does not change the state of the program, except for modifying the instruction pointer.

Canonical form: nop

print

Prints value to standard output and adds a newline.

Canonical form: print :r-op

ptr

Creates a pointer to a value.

Canonical form: ptr destincation:r-op source:r-op

Opcode group: register-manipulation

copy

Copies values between registers.

Canonical form: copy destination:r-oparand source:r-op

isnull

Checks if a register is null.

Canonical form: isnull output:r-op checked-register:r-op

move

Move a value from one register to another.

Canonical form: move destination:r-oparand source:r-op

ress

Switches primary register set.

Canonical form: ress :register-set-specifier

swap

Swaps values in two registers.

Canonical form: swap :r-op :r-op

Opcode group: resource-management

delete

Deletes a value.

Canonical form: delete source:r-op

Opcode group: strings

streq

Compares two strings for equality. NOT IMPLEMENTED

Canonical form: streq result:r-op lhs:r-op rhs:r-op

strstore

Puts a string into a register.

Canonical form: strstore destination:r-op "content"

Opcode group: structs

insert

Moves a value into a struct under specified key.

Canonical form: insert target-struct:r-op source:r-op key:r-op

new

Create new struct with a given type.

Canonical form: new :r-op type-name:atom

remove

Removes a key from a struct.

Canonical form: remove result:r-op source-struct:r-op key:r-op

Opcode group: text

text

Puts a text into a register.

Canonical form: text Destination:r-op "utf8-content"

textat

Return copy of the character at a given index in text.

Canonical form: textat result-register string-register index-register

textcommonprefix

Return length of common prefix of two text values.

Canonical form: textcommonprefix result-register lhs-string-register rhs-string-register

textcommonsuffix

Puts a string into a register.

Canonical form: textcommonsuffix result-register lhs-string-register rhs-string-register

textconcat

Concatenate two text values. Creates a copy of each text value.

Canonical form: textconcat result-register lhs-string-register rhs-string-register

texteq

Compare two text values for equality.

Canonical form: texteq result-register lhs-register rhs-register

textlength

Return length of a given text value (in characters).

Canonical form: textlength result-register string-register

textsub

Return a copy of a part of the given text between given indexes.

Canonical form: textsub result-register string-register begin-index-register end-index:register|void

Opcode group: typesystem

attach

Attaches function to a type to act as a method implementation.

Canonical form: attach target:r-op implementation-function:atom method-name:atom

class

Creates a new type.

Canonical form: class :r-op class-name:atom

derive

Marks one type as derived from another.

Canonical form: derive target-class:r-op base-class:atom

register

Registers a new type in the typesystem. DEPRECATED

Canonical form: register new-type:r-op

Opcode group: vectors

vat

Creates a pointer to an element of a vector at given index.

Canonical form: vat destination:r-op source-vector:r-op index:integer

vec

Creates a vector.

Canonical form: vec :r-op

vinsert

Moves a value into the vector at a given index. Elements after given index are shifted to the left, starting with the element previously present at given index.

Canonical form: vinsert target-vector:r-op source:r-op index:r-op

vlen

Returns length of a vector.

Canonical form: vlen result:r-op source-vector:r-op

vpop

Pops a value from a vector.

Canonical form: vpop popped-value:r-op source-vector:r-op index

vpush

Pushes a value into the vector as a last element. The value is moved from the source register.

Canonical form: vpush affected-vector:r-op source:r-op