old-DasOS/documentation/supervm-asm.md

# SuperVM Assembly Language

## Purpose of this Document
The SuperVM Virtual Machine only specifies assembler mnemonics and an instruction format,
but does not define an assembler dialect.

This document describes the reference dialect of the SuperVM assembly language.

## Overview

The SuperVM Assembly Language, short *SVMA*, provides a full interface to the features
of the SuperVM Virtual Machine Instruction Set. It is possible to create any kind of
program, even optimized ones that utilize the full power of the instruction set.

The assembly language provides five basic components:

- Labels
- Mnemonics
- Parameters
- Attributes
- Comments

The following code snippet gives a brief overview over the assembly language:

	_start:
		push 10
		push 33
		add     ; Add 10 and 33
		[i0:arg] sub -1

All components are present in this snippet. `_start:` is a label, `push`, `add` and
`sub` are mnemonics, `10`, `33`, `-1` are the parameters and `[i0:arg]` is an attribute.
`; Add 10 and 33` is a comment.

## Components

The SVMA is a line based language where a line can be blank, a sole comment or a mnemonic definition
following one of the next schemes.

	[comment]
	label [comment]
	[label] [attribute]* mnemonic [attribute]* [argument] [attribute]* [comment]

Each component that is written in `[]` is optional. If a component is followed by an
asterisk (`*`) the component can be written repeatedly. A singular white space in this 
scheme can be replaced by any non-empty combination of whitespace and tab characters.

The verbal description of the language is rather easy: Each line may be terminated by a comment.
A line may start with a label and if it does so, the mnemonic can be omitted. If no label
is given, a mnemonic is necessary. A mnemonic can be followed by an argument.
Attributes may be inserted between any of the components, but can not be in front of the label
or behind the comment.

### Labels
A label defines a kind of marker that stores the current code position.
Labels are commonly used to create jump targets for instructions.

A label is a word string that is follow by a color (`:`) at the beginning of a line.
Anything before the colon is the name of the label and can later be referenced.

### Mnemonics
Mnemonics are short hand names of SuperVM instructions. Each mnemonic will be emitted as
an instruction in the binary code later.

A mnemonics is a short, usually 3 or 4 letter long word that describes the instruction
beeing emitted.

A list of all mnemnonics with descriptions can be found in the Document *Common Assembler Mnemonics*.

### Arguments
Each mnemonic can be followed by an argument which will be emitted as a 32 bit value.
SVMA provides 5 different types of argument descriptions:

| Type    | Example  | Description                            |
|---------|----------|----------------------------------------|
| Binary  | `0b1101` | Provides the literal binary value.     |
| Decimal | `123`    | Provides the literal decimal value     |
| Hexcode | `0xF00F` | Provides the literal hexadeciaml value |
| Char    | `'c'`    | Provides an ascii character code.      |
| Label   | `@label` | Provides the position of the label.    |

### Attributes
An attribute overrides any part of the mnemonic with a custom option. It can be used
to optimize instructions so they require a minimum of input.

#### Primitive Attributes

The following table lists all possible primitive attributes an instruction can have:

| Attribute   | Modification                                       |
|-------------|----------------------------------------------------|
| `f:yes`     | Sets the flag option in the instruction.           |
| `f:no`      | Clears the flag option in the instruction.         |
| `r:discard` | Sets the output mode to *discard*.                 |
| `r:push`    | Sets the output mode to *push*.                    |
| `r:jump`    | Sets the output mode to *jump*.                    |
| `i0:zero`   | Sets input0 to *zero*.                             |
| `i0:pop`    | Sets input0 to *pop value*.                        |
| `i0:peek`   | Sets input0 to *peek value*.                       |
| `i0:arg`    | Sets input0 to *use argument*.                     |
| `i1:zero`   | Sets input1 to *zero*.                             |
| `i1:pop`    | Sets input1 to *pop value*.                        |
| `ex(z)=x`   | Sets the execution for the Z flag to *don't care*. |
| `ex(z)=0`   | Sets the execution for the Z flag to *0*.          |
| `ex(z)=1`   | Sets the execution for the Z flag to *1*.          |
| `ex(n)=x`   | Sets the execution for the N flag to *don't care*. |
| `ex(n)=0`   | Sets the execution for the N flag to *0*.          |
| `ex(n)=1`   | Sets the execution for the N flag to *1*.          |

#### Modifying cmdinfo
The SVMA provides two more complex attributes for modificating the command and the cmdinfo
of an instruction.

To modify the cmdinfo part of the instruction, the attribute `[ci:???]` is used. `???` must
be replaced by any valid decimal unsigned 16 bit wide number.

#### Modifying the command
Another complex attribute allows the modification of the actual command used: `[cmd:???]`.

Here `???` can be replaced with one of the following commands:

| Command |
|---------|
| Copy    |
| Store   |
| Load    |
| Get     |
| Set     |
| BpGet   |
| BpSet   |
| CpGet   |
| Math    |
| SpGet   |
| SpSet   |
| SysCall |
| HwIO    |

## Example Code
This example implements the given C function `print_str`;

	void print_str(char *string)
	{
		char *ptr = string;
		while(*ptr) {
			char c = *ptr;
			putc(c); // Syscall 1
			ptr++;
		}
		return;
	}

which is represented in SVMA:

	; void print_str(char *string);
	print_str:
		bpget ; enter function by
		spget ; saving the parents base pointer
		bpset ; and storing the current stack pointer
			 
		
		; char *ptr = string;
		get -2 ; get argument 0 into our local variable '#1'
		
		; while(*ptr) {
	print_str_loop:
		[i0:peek] loadi [f:yes] ; write flags, also load result, don't discard pointer
		[ex(z)=1] jmp @print_str_end_loop ; when *ptr == 0, then goto print_str_end_loop
		; char c = *ptr; // which is implicitly done by our while(*ptr)
		
		; putc(c);
		[i0:pop] syscall [ci:1] ; removes the loaded character and prints it
		
		; ptr++;
		[i0:arg] add 1 ; adds 1 to the stack top
		
		; }
		jmp @print_str_loop
		
	print_str_end_loop:
		drop ; discard the result from loadi
		drop ; discard our pointer
		
		; return
		bpget ; leave function
		spset ; by restoring parent base pointer
		bpset
		jmpi  ; and jumping back.