Moves to supervm.md to documentation and adds a documentation of the SuperVM Assembly Language.
This commit is contained in:
Felix Queißner
parent
7b5d44aa07
commit
c32d30506b
3 changed files with 232 additions and 46 deletions
187
documentation/supervm-asm.md
Normal file
187
documentation/supervm-asm.md
Normal file
|
|
@ -0,0 +1,187 @@
|
||||||
|
# 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.
|
||||||
45
documentation/supervm-mnemonics.md
Normal file
45
documentation/supervm-mnemonics.md
Normal file
|
|
@ -0,0 +1,45 @@
|
||||||
|
# Common Assembler Mnemonics
|
||||||
|
|
||||||
|
The following table lists a set of practial mnemonics for the use in an assembly language.
|
||||||
|
Each mnemonic declares a specific configuration of an instruction.
|
||||||
|
|
||||||
|
| Mnemonic | Arg? | i0 | i1 | Cmd | CmdInfo | Output | Flags? | Description 1 |
|
||||||
|
|----------|------|------|------|---------|----------|---------|--------|-------------------------------------------------------------------------------------------------|
|
||||||
|
| nop | no | zero | zero | copy | 0 | discard | no | Does noting |
|
||||||
|
| push | yes | arg | zero | copy | 0 | push | no | Pushes its argument on the stack |
|
||||||
|
| drop | no | pop | zero | copy | 0 | discard | no | Removes the top value from the stack |
|
||||||
|
| dup | no | peek | zero | copy | 0 | push | no | Duplicates the top value on the stack. |
|
||||||
|
| jmp | yes | arg | zero | copy | 0 | jump | no | Jumps to its argument. |
|
||||||
|
| jmpi | no | pop | zero | copy | 0 | jump | no | Pops a value from the stack and jumps to it. |
|
||||||
|
| ret | no | pop | zero | copy | 0 | jump | no | Pops a value from the stack and jumps to it. |
|
||||||
|
| load | yes | arg | zero | load | 0 | push | no | Loads the value located at the argument from memory. |
|
||||||
|
| loadi | no | pop | zero | load | 0 | push | no | Pops an address from the stack and loads the value from memory. |
|
||||||
|
| store | yes | arg | pop | store | 0 | discard | no | Pops a value and stores it in memory at the argument address. |
|
||||||
|
| storei | no | pop | pop | store | 0 | discard | no | First, pops an address from the stack, then a value. Stores the value at the address. |
|
||||||
|
| get | yes | arg | zero | get | 0 | push | no | Pushes the value at the given base pointer offset at the stack. |
|
||||||
|
| geti | no | pop | zero | get | 0 | push | no | Pops an offset from the stack, then pushes the value at the popped base pointer offset. |
|
||||||
|
| set | yes | arg | pop | set | 0 | discard | no | Pops a value from the stack and copies it to the given stack offset. |
|
||||||
|
| seti | no | pop | pop | set | 0 | discard | no | Pops an offset from the stack, then a value. Stores the value at the given offset on the stack. |
|
||||||
|
| bpget | no | zero | zero | bpget | 0 | push | no | Pushes the current base pointer. |
|
||||||
|
| bpset | no | pop | zero | bpset | 0 | discard | no | Pops a value and sets the base pointer. |
|
||||||
|
| spget | no | zero | zero | spget | 0 | push | no | Pushes the current stack pointer. |
|
||||||
|
| spset | no | pop | zero | spset | 0 | discard | no | Pops a value and sets the stack pointer. |
|
||||||
|
| cpget | no | zero | zero | cpget | 1 | push | no | Pushes the address of the second-next instruction. |
|
||||||
|
| add | no | pop | pop | math | 0 | push | no | Pops two values and pushes the sum. |
|
||||||
|
| sub | no | pop | pop | math | 1 | push | no | Pops two values and pushes the difference. |
|
||||||
|
| cmp | no | pop | pop | math | 1 | discard | yes | Pops two values and subtracts them. Discards the result, but modifies the flags. |
|
||||||
|
| mul | no | pop | pop | math | 2 | push | no | Pops two values and pushes the product. |
|
||||||
|
| div | no | pop | pop | math | 3 | push | no | Pops two values and pushes the quotient. |
|
||||||
|
| mod | no | pop | pop | math | 4 | push | no | Pops two values and pushes the euclidean quotient. |
|
||||||
|
| and | no | pop | pop | math | 5 | push | no | Pops two values and pushes the bitwise and. |
|
||||||
|
| or | no | pop | pop | math | 6 | push | no | Pops two values and pushes the bitwise or. |
|
||||||
|
| xor | no | pop | pop | math | 7 | push | no | Pops two values and pushes the exclusive or. |
|
||||||
|
| not | no | pop | zero | math | 8 | push | no | Pops a single value and pushes the bitwise not |
|
||||||
|
| rol | no | pop | pop | math | 9 | push | no | TO BE SPECIFIED |
|
||||||
|
| ror | no | pop | pop | math | 10 | push | no | TO BE SPECIFIED |
|
||||||
|
| asl | no | pop | pop | math | 11 | push | no | TO BE SPECIFIED |
|
||||||
|
| asr | no | pop | pop | math | 12 | push | no | TO BE SPECIFIED |
|
||||||
|
| shl | no | pop | pop | math | 13 | push | no | TO BE SPECIFIED |
|
||||||
|
| shr | no | pop | pop | math | 14 | push | no | TO BE SPECIFIED |
|
||||||
|
| syscall | yes | zero | zero | syscall | 0 | discard | no | Mnemonic for a generic syscall. |
|
||||||
|
| hwio | yes | zero | zero | hwio | 0 | discard | no | Mnemonic for a generic hwio. |
|
||||||
|
|
@ -268,52 +268,6 @@ Each instruction can emit an output value. The output can be used in the followi
|
||||||
The instruction argument can provide static input which can be used
|
The instruction argument can provide static input which can be used
|
||||||
as a value source for the first input value.
|
as a value source for the first input value.
|
||||||
|
|
||||||
## Common Assembler Mnemonics
|
|
||||||
|
|
||||||
The following table lists a set of practial mnemonics for the use in an assembly language.
|
|
||||||
Each mnemonic declares a specific configuration of an instruction.
|
|
||||||
|
|
||||||
| Mnemonic | Arg? | i0 | i1 | Cmd | CmdInfo | Output | Flags? | Description 1 |
|
|
||||||
|----------|------|------|------|---------|----------|---------|--------|-------------------------------------------------------------------------------------------------|
|
|
||||||
| nop | no | zero | zero | copy | 0 | discard | no | Does noting |
|
|
||||||
| push | yes | arg | zero | copy | 0 | push | no | Pushes its argument on the stack |
|
|
||||||
| drop | no | pop | zero | copy | 0 | discard | no | Removes the top value from the stack |
|
|
||||||
| dup | no | peek | zero | copy | 0 | push | no | Duplicates the top value on the stack. |
|
|
||||||
| jmp | yes | arg | zero | copy | 0 | jump | no | Jumps to its argument. |
|
|
||||||
| jmpi | no | pop | zero | copy | 0 | jump | no | Pops a value from the stack and jumps to it. |
|
|
||||||
| ret | no | pop | zero | copy | 0 | jump | no | Pops a value from the stack and jumps to it. |
|
|
||||||
| load | yes | arg | zero | load | 0 | push | no | Loads the value located at the argument from memory. |
|
|
||||||
| loadi | no | pop | zero | load | 0 | push | no | Pops an address from the stack and loads the value from memory. |
|
|
||||||
| store | yes | arg | pop | store | 0 | discard | no | Pops a value and stores it in memory at the argument address. |
|
|
||||||
| storei | no | pop | pop | store | 0 | discard | no | First, pops an address from the stack, then a value. Stores the value at the address. |
|
|
||||||
| get | yes | arg | zero | get | 0 | push | no | Pushes the value at the given base pointer offset at the stack. |
|
|
||||||
| geti | no | pop | zero | get | 0 | push | no | Pops an offset from the stack, then pushes the value at the popped base pointer offset. |
|
|
||||||
| set | yes | arg | pop | set | 0 | discard | no | Pops a value from the stack and copies it to the given stack offset. |
|
|
||||||
| seti | no | pop | pop | set | 0 | discard | no | Pops an offset from the stack, then a value. Stores the value at the given offset on the stack. |
|
|
||||||
| bpget | no | zero | zero | bpget | 0 | push | no | Pushes the current base pointer. |
|
|
||||||
| bpset | no | pop | zero | bpset | 0 | discard | no | Pops a value and sets the base pointer. |
|
|
||||||
| spget | no | zero | zero | spget | 0 | push | no | Pushes the current stack pointer. |
|
|
||||||
| spset | no | pop | zero | spset | 0 | discard | no | Pops a value and sets the stack pointer. |
|
|
||||||
| cpget | no | zero | zero | cpget | 1 | push | no | Pushes the address of the second-next instruction. |
|
|
||||||
| add | no | pop | pop | math | 0 | push | no | Pops two values and pushes the sum. |
|
|
||||||
| sub | no | pop | pop | math | 1 | push | no | Pops two values and pushes the difference. |
|
|
||||||
| cmp | no | pop | pop | math | 1 | discard | yes | Pops two values and subtracts them. Discards the result, but modifies the flags. |
|
|
||||||
| mul | no | pop | pop | math | 2 | push | no | Pops two values and pushes the product. |
|
|
||||||
| div | no | pop | pop | math | 3 | push | no | Pops two values and pushes the quotient. |
|
|
||||||
| mod | no | pop | pop | math | 4 | push | no | Pops two values and pushes the euclidean quotient. |
|
|
||||||
| and | no | pop | pop | math | 5 | push | no | Pops two values and pushes the bitwise and. |
|
|
||||||
| or | no | pop | pop | math | 6 | push | no | Pops two values and pushes the bitwise or. |
|
|
||||||
| xor | no | pop | pop | math | 7 | push | no | Pops two values and pushes the exclusive or. |
|
|
||||||
| not | no | pop | zero | math | 8 | push | no | Pops a single value and pushes the bitwise not |
|
|
||||||
| rol | no | pop | pop | math | 9 | push | no | TO BE SPECIFIED |
|
|
||||||
| ror | no | pop | pop | math | 10 | push | no | TO BE SPECIFIED |
|
|
||||||
| asl | no | pop | pop | math | 11 | push | no | TO BE SPECIFIED |
|
|
||||||
| asr | no | pop | pop | math | 12 | push | no | TO BE SPECIFIED |
|
|
||||||
| shl | no | pop | pop | math | 13 | push | no | TO BE SPECIFIED |
|
|
||||||
| shr | no | pop | pop | math | 14 | push | no | TO BE SPECIFIED |
|
|
||||||
| syscall | yes | zero | zero | syscall | 0 | discard | no | Mnemonic for a generic syscall. |
|
|
||||||
| hwio | yes | zero | zero | hwio | 0 | discard | no | Mnemonic for a generic hwio. |
|
|
||||||
|
|
||||||
## Function Calls
|
## Function Calls
|
||||||
|
|
||||||
The following chapter defines the SuperVM calling convention. It is required that all
|
The following chapter defines the SuperVM calling convention. It is required that all
|
||||||
Loading…
Reference in a new issue