.align

.align INT

Aligns the current location to at least INT bytes

.align 8

.autosection

.autosection SECTIONTYPE

Automatically creates a section of the given type. The content of the section is taken from other directives and defaults.

.autosection header

.autosectionstart

.autosectionstart SECTIONTYPE

Starts a section with automatically generated content. This is the same as .autosection but the section is not yet ended with .endsection. This is useful if additional content is to be added to the section.

.autosectionstart header
; more content
.endsection

.bug

.bug

Marks a point in code as only reachable by means of a bug. Generates code that will throw an exception.

.bug

.byte

.align INT [, INT [, INT [, ...]]]

Outputs the given bytes.

.bytes 0x56, 0x4D

.cat

.cat STRING [, STRING [, STRING [, ...]]]

Includes files as-is into the output. No translation is performed when including file files. This is mostly useful to include large binary objects (blobs).

.cat "help.txt"

.cold

.cold PREG [, PREG [, PREG [, ...]]]

Mark a given physical register as cold. Cold registers are unlikely to be used/referenced. This allows the assembler to optimise better.

.cold arg

.endfunction

.endfunction

Ends a function started with .function. This will also emit a corresponding end$function$FUNCTION and size$function$FUNCTION alias. If the function did not end with a returning opcode a void return is inserted before closing the function.

.endfunction

.endlabel

.endlabel

Generate a end mark for a label. This can later be referend using end$label$LABEL.

.endlabel

.endsection

.endsection

Ends a section started with .section

.endsection

.force_mapped

.force_mapped REG [, REG [, REG [, ...]]]

Force the automatic mapping of registers (see .regmap_auto) to map a given set of registers. This is normally not needed, but can be used to move mappings outside small loops to improve performance.

.force_mapped io, user7

.function

.function NAME

Marks the start of a function. This emits a function$NAME alias. It also informs the assembler that the code is only reachable via a function call. This changes the assembler's understanding of the state of the registers. Functions are normally to be terminated using .endfunction.

.function main

.hot

.hot PREG [, PREG [, PREG [, ...]]]

Marks a given physical register as hot. Hot registers are likely to be used frequently. This allows the assembler to optimise better.

.hot user3, out

.include

.include STRING [, STRING [, STRING [, ...]]]

Includes source files and translates them. The .include directive does not create a new context of any kind. The files are included as if their content were in the main file.

.include "lib.vmv0-asm"

.label

.label NAME

Adds an alias for the given label, it can later be referenced using label$NAME.

.label blubber

.lukewarm

.lukewarm PREG [, PREG [, PREG [, ...]]]

Marks physical registers as lukewarm. This tells the assmeber that they are not specically hot nor cold. This is the default temperature for registers.

.lukewarm user2, error

.map

.map LREG, PREG

Marks a logical register to be mapped to a physical register in the assembler's internal state without actually emitting an opcode. This is useful to set a correct state e.g. after a jump when the assembler can no longer know the actual mapping. To actually emit an opcode use map.

.map r0 user0

.mine

.mine REG [, REG [, REG [, ...]]]

This marks registers as owned by the author. If a register is owned by the authour the assembler will not try to use it for automatic code generation (such as auto mapping). This is the default for registers.

.mine r0, r1, r2, out

.noops

.noops INT

Inserts the given number of noops.

.noops 4

.not_implemented

.not_implemented

Marks a section of code as not (yet) implemented. Generates code that throws a corresponding exception.

.not_implemented

.org

.org INT

Seeks the output to the given position. If the value is relative moves relative to the current position

.org 0x100

.popname

.popname VAR [, VAR [, VAR [, ...]]]

Pops a name of the name stack. See .pushname for details.

.popname $x, $y

.pushname

.pushname VAR = VALUE [, VAR = VALUE [, VAR = VALUE [, ...]]]

Pushes name-value-pairs onto the name stack. Each name must start with a single $. The value can be any value (register, constant, ...) but another name. This mechanism can be used to assign more memorable names to registers or other constants. Those names can be used at any point. Names are pushed onto the stack, meaning if a name becomes pushed again it shadows the old content. The old content will be come visible again after .popname.

.pushname $x = 5, $y = user7

quit

.quit

Quits the assembler, the rest of the file is ignored.

.quit

.regattr

.regattr REG ATTR [, ATTR [, ...]]

Sets register attributes. The following attributes are defined:

• mine, yours, theirs: Sets register ownership
• cold, lukewarm, hot: Sets register temperature

.regattr r0 mine, hot

.regattr user3 theirs, cold

.regmap_auto

.regmap_auto BOOL

Enables or disables automatic register mapping by the assembler. In order to work as expected some logical registers must be declared .yours. The number of registers that should be declared .yours depend on the code. A general starting point would be three or four.

.regmap_auto true

.section

.section SECTIONTYPE [, STRING ]

Starts a section of the given type. If another section is already open it first needs to be ended with .endsection. Optionally a magic can be given as a second argument. Consider starting sections with .autosectionstart. This will include automatically generated and default content into the section.

.section header

.synthetic_auto_unref

.synthetic_auto_unref BOOL

Enables (default) or disables automatich unref-ing of temporary registers in synthetic opcodes. If enabled the assembler will try to unref all temporary registers immediately. This is normally the safter option, but might not be the most performant one. This option can be used to skip this step.

.synthetic_auto_unref true

.theirs

.theirs REG [, REG [, REG [, ...]]]

Marks a register as owned not by the author nor the assambler. This can be useful if it is for example owned by a library or other module.

.theirs deep, user4

.utf8

.utf8 STRING [, STRING, [, ...]]]

Writes the given strings as-is to the output. No final null-byte is inserted. However it can be manually added using \0. Any escaped characters within must be valid UTF-8.

Note that the source file must be in UTF-8 (it always must). If it is not, strange things might happen.

.utf8 "Hello World\n", "Good afternoon!\0", U+1F981

.yours

.yours REG [, REG [, REG [, ...]]]

Marks a register as owned by the assembler. The assembler is free to use it however it sees fit. The author should avoid using those registers after being declared yours.

.yours r4, r5, r6, r7

.yours r*, arg, user7

add

add out, REG, REG †
add out, REG, INT †

Adds the given two values, storing the result in out.

add out, user0, user1

add out, user0, 12

autodie

autodie

Dies with the error in error if error is not undef and not RoarAudio error code 0 (none).

autodie

byte_transfer

byte_transfer! REG, REG, INT
byte_transfer REG, REG, INT

Transfers the given number of bytes from the source to the destination register. Optionally dies if the number of bytes actually transferred is less than the number of bytes requested. The transferred length is stored in out.

byte_transfer! r0, r2, 15

call

call? REG, REG
call! REG, REG
call REG †
call INT †
call ID †
call REG, INT †
call REG, ID †

Calls the function (second argument) using the given context (first argument Before the call the filter-output port is reset, the filter input port is set to in. After successful return out is set to the filter output port.

If the only one argument is passed, the sole argument is the function to call. It will be run in a fresh context. This might have performance implications (both ways).

call! r0, r1

compare

compare out, REG, REG [, with FLAG [, FLAG [, FLAG [, ...]]]]

Compares two registers storing the result in out. Optionally a number of flags can be passed. The result is a number that is smaller than zero if the first input is smaller than the second, zero if they are equal, and bigger than zero if the first input is bigger than the second. The following flags are supported:

• icase: Compare case insensitive
• asciz: Compare up to a 0-byte
• prefix: The first input is in the second but may have a prefix in front
• suffix: The first input is in the second but may have a suffix after it
• nulls_distinct: Null values are distinct
• nulls_equal: Null values are equal
• nulls_first: Null values are considered smaller than any other value
• nulls_last: Null values are considered bigger than any other value
• seekback_start: Preforms a seekback on the second input to match the start of the submatch of the first input
• seekback_end: Preforms a seekback on the second input to match the end of the submatch of the first input
• subject: True if the subjects match, even if the handles are distinct handles

compare out, user0, user4

compare out, user0, user4 with icase

compare out, user0, user4 with nulls_first, prefix

contents

contents REG, REG
contents REG, INT †
contents REG, ID †

Performs a call to the function (second argument) for every content element of the given handle (first argument). The context for the calls can be given via arg. If arg is undefined, then a new context is created (and destroyed) automatically.

contents user0, user3

contents user0, function$perentry

control

control REG, REG
control REG, REG, REG
control REG, sni:NNN
control REG, sni:NNN, REG
control REG, sni:NNN, sni:MMM
control REG, sni:NNN, INT

Performs a control call on the target register. The second argument is the command, the third is in if any. arg is taken from the arg register. And out is always the out register.

See also SIRTX numerical identifiers (sni) for details on sni values.

control! user0, sni:31, user1

die

die REG

Dies with the error in the given register. The value is stored in the error register.

die r0

div

div out, REG, REG †
div out, REG, INT †

Divides the second parameter by the third, storing the result in out.

div out, user0, user1

div out, user0, 7

exit

exit REG

Exits the program (not just returns the function). Stores the value from the given register in out

exit r0

filesize

filesize INT

Emits a filesize directive. This is generally only useful in the header section. The value provided is in bytes. But it may be encoded in other units. The only useful value is size$out$.

filesize size$out$

jump

jump REG
jump INT
jump INT {if|unless} out OP VAL [or [out OP VAL [or [out OP VAL [...]]]]]

Jumps to the given position. If the integer form is used the target must be within range of a relative jump (which it is for all files smaller than 64KiB). A condition can be provided in some forms beginning with if or unless followed by triplets that are or-ed. The following conditions are supported:

• out is valid: True if the handle is defined and valid
• out is true: True if the value has a true truth value (default: false)
• out is notfine: True if the value indicates a not so fine state
• out < 0, out <= -1: True if the value is negative number
• out == 0: True if the value is zero
• out > 0, out >= 1: True if the value is a positive number

jump r0

jump label$repeat

jump label$good if out is true

magic

magic

Writes a format specific magic. Normally this is used as the very first opcode for format detection. If it is encountered anywhere in the code it is equivalent to a noop.

magic

map

map LREG, PREG

Maps a logical register to a physical register.

map r0 user0

metadata

metadata REG, REG, REG

Calls the output function (first argument) for every metadata of tag (second argument), and relation (third argument). The context for the calls can be given via arg. If arg is undefined, then a new context is created (and destroyed) automatically.

metadata user0, user1, user2

mod

mod out, REG, REG †
mod out, REG, INT †

Calculates the modulus (integer reminder) of the second value divided by the third, storing the result in out.

mod out, user0, user1

mod out, user0, 8

move

move REG, REG

Moves a value from one register to another. The source register becomes undef by the move. To copy a value (like many assembler langauges do with mov) use replace.

move r0, r1

mul

mul out, REG, arg †
mul out, REG, REG †
mul out, REG, INT †

Multiplies two values, storing the result in out. Using arg as the second factor results in smaller and faster code.

sub out, user0, arg

sub out, user0, 4

noop

noop

Does nothing (no operation).

noop

open

open REG, INT
open REG, ID
open REG, ns, INT
open REG, ns, INT, INT
open REG, undef †

Opens a handle and stores the value in the given register. The forms using ns will resolve the given id using the type given in ns. If two INTs are given the first one will be used to resolve to a type and the second to do the final resolver step.

open r0, 7

open user3, sni:80

open user3, ns, 13

open_context

open_context REG

Creates a new context and stores it in the target register. The context will be child context of the current context (in context).

open_context r0

open_function

open_function REG, INT

Creates a handle for the given function.

open_function r0, function$print

relations

relations REG, REG, REG, undef
relations REG, undef, REG, REG

Calls the output function (first argument) for every relation of tag (second register), relation (third register), and related (forth register). One of tag or relation must be undef. The context for the calls can be given via arg. If arg is undefined, then a new context is created (and destroyed) automatically.

relations r0, r1, r2, undef

replace

replace REG, REG

Replaces a value in a register with the value of another register. The source register is unchanged.

replace r0, r2

return

return
return REG
return undef †

Returns from the current function. If a register is given the value is copied into out before return. If no value (or undef) is given, out is unref-ed.

return

return user4

rewind

rewind REG

Rewinds (seeks to the beginning) the handle in the given register.

rewind r0

seek

seek REG, REG

Seeks the value in the left register to the positon in the right register.

seek r0, r1

sub

sub out, REG, REG †
sub out, REG, INT †

Subtracts the third value from the second, storing the result in out.

sub out, user0, user1

sub out, user0, 4

substr

substr REG, REG, INT, INT

Opens a substring of the input register in the output register. The offset and end is given. If the end is given as a relative integer it is understood as the length.

substr rodata, program_text, 0x100, +13

tell

tell REG, REG

Stores the current position of the input register in the output register.

tell r0, r3

transfer

transfer REG, REG

Transfers the subject/object from the source register to the target register.

transfer r0, r2

unref

unref REG

Un-references (undefines) the given register.

unref r3