dev/vm-improvements (#3)
Co-authored-by: Nilton Constantino <nilton.constantino@visma.com> Reviewed-on: #3
This commit was merged in pull request #3.
This commit is contained in:
@@ -31,7 +31,8 @@ The VM has:
|
||||
|
||||
* **PC (Program Counter)** — next instruction
|
||||
* **Operand Stack** — value stack
|
||||
* **Call Stack** — frame stack
|
||||
* **Call Stack** — stores execution frames for function calls
|
||||
* **Scope Stack** — stores frames for blocks within a function
|
||||
* **Heap** — dynamic memory
|
||||
* **Globals** — global variables
|
||||
* **Constant Pool** — literals and references
|
||||
@@ -60,13 +61,21 @@ Properties:
|
||||
|
||||
| Type | Description |
|
||||
| --------- | ------------------------- |
|
||||
| `integer` | 64-bit signed integer |
|
||||
| `int32` | 32-bit signed integer |
|
||||
| `int64` | 64-bit signed integer |
|
||||
| `float` | 64-bit floating point |
|
||||
| `boolean` | true/false |
|
||||
| `string` | immutable UTF-8 |
|
||||
| `null` | absence of value |
|
||||
| `ref` | heap reference |
|
||||
|
||||
### 3.1 Numeric Promotion
|
||||
The VM promotes types automatically during operations:
|
||||
* `int32` + `int32` → `int32`
|
||||
* `int32` + `int64` → `int64`
|
||||
* `int` + `float` → `float`
|
||||
* Bitwise operations promote `int32` to `int64` if any operand is `int64`.
|
||||
|
||||
Do not exist:
|
||||
|
||||
* magic coercions
|
||||
@@ -75,11 +84,30 @@ Do not exist:
|
||||
|
||||
---
|
||||
|
||||
## 4. Stack Conventions
|
||||
## 4. Stack Conventions & Calling ABI
|
||||
|
||||
* Operations use the top of the stack
|
||||
* Results always return to the stack
|
||||
* Last pushed = first consumed
|
||||
* Operations use the top of the stack.
|
||||
* Results always return to the stack.
|
||||
* **LIFO Order:** Last pushed = first consumed.
|
||||
* **Mandatory Return:** Every function (`Call`) and `Syscall` MUST leave exactly **one** value on the stack upon completion. If there is no meaningful value to return, `Null` must be pushed.
|
||||
|
||||
### 4.1 Calling Convention (Call / Ret)
|
||||
|
||||
1. **Arguments:** The caller pushes arguments in order (arg0, arg1, ..., argN-1).
|
||||
2. **Execution:** The `Call` instruction specifies `args_count`. These `N` values become the **locals** of the new frame (local 0 = arg0, local 1 = arg1, etc.).
|
||||
3. **Return Value:** Before executing `Ret`, the callee MUST push its return value.
|
||||
4. **Cleanup:** The `Ret` instruction is responsible for:
|
||||
- Popping the return value.
|
||||
- Removing all locals (the arguments) from the operand stack.
|
||||
- Re-pushing the return value.
|
||||
- Restoring the previous frame and PC.
|
||||
|
||||
### 4.2 Syscall Convention
|
||||
|
||||
1. **Arguments:** The caller pushes arguments in order.
|
||||
2. **Execution:** The native implementation pops arguments as needed. Since it's a stack, it will pop them in reverse order (argN-1 first, then argN-2, ..., arg0).
|
||||
3. **Return Value:** The native implementation MUST push exactly one value onto the stack before returning to the VM.
|
||||
4. **Cleanup:** The native implementation is responsible for popping all arguments it expects.
|
||||
|
||||
Example:
|
||||
|
||||
@@ -122,6 +150,7 @@ State:
|
||||
| `HALT` | 1 | Terminates execution |
|
||||
| `JMP addr` | 2 | Unconditional jump |
|
||||
| `JMP_IF_FALSE addr` | 3 | Jumps if top is false |
|
||||
| `JMP_IF_TRUE addr` | 3 | Jumps if top is true |
|
||||
|
||||
---
|
||||
|
||||
@@ -133,6 +162,10 @@ State:
|
||||
| `POP` | 1 | Removes top |
|
||||
| `DUP` | 1 | Duplicates top |
|
||||
| `SWAP` | 1 | Swaps two tops |
|
||||
| `PUSH_I32 v` | 2 | Pushes 32-bit int |
|
||||
| `PUSH_I64 v` | 2 | Pushes 64-bit int |
|
||||
| `PUSH_F64 v` | 2 | Pushes 64-bit float |
|
||||
| `PUSH_BOOL v` | 2 | Pushes boolean |
|
||||
|
||||
---
|
||||
|
||||
@@ -155,9 +188,17 @@ State:
|
||||
| `NEQ` | 2 |
|
||||
| `LT` | 2 |
|
||||
| `GT` | 2 |
|
||||
| `LTE` | 2 |
|
||||
| `GTE` | 2 |
|
||||
| `AND` | 2 |
|
||||
| `OR` | 2 |
|
||||
| `NOT` | 1 |
|
||||
| `BIT_AND` | 2 |
|
||||
| `BIT_OR` | 2 |
|
||||
| `BIT_XOR` | 2 |
|
||||
| `SHL` | 2 |
|
||||
| `SHR` | 2 |
|
||||
| `NEG` | 1 |
|
||||
|
||||
---
|
||||
|
||||
@@ -174,12 +215,16 @@ State:
|
||||
|
||||
### 6.6 Functions
|
||||
|
||||
| Instruction | Cycles | Description |
|
||||
|----------------| ------ |---------------------------------|
|
||||
| `CALL addr` | 5 | Call |
|
||||
| `RET` | 4 | Return |
|
||||
| `PUSH_SCOPE n` | 3 | Creates scope (execution frame) |
|
||||
| `POP_SCOPE` | 3 | Removes scope |
|
||||
| Instruction | Cycles | Description |
|
||||
|----------------| ------ |--------------------------------------------|
|
||||
| `CALL addr` | 5 | Saves PC and creates a new call frame |
|
||||
| `RET` | 4 | Returns from function, restoring PC |
|
||||
| `PUSH_SCOPE` | 3 | Creates a scope within the current function |
|
||||
| `POP_SCOPE` | 3 | Removes current scope and its local variables |
|
||||
|
||||
**ABI Rules for Functions:**
|
||||
* **Mandatory Return Value:** Every function MUST leave exactly one value on the stack before `RET`. If the function logic doesn't return a value, it must push `null`.
|
||||
* **Stack Cleanup:** `RET` automatically clears all local variables (based on `stack_base`) and re-pushes the return value.
|
||||
|
||||
---
|
||||
|
||||
@@ -205,6 +250,18 @@ Heap is:
|
||||
|--------------| -------- | --------------------- |
|
||||
| `SYSCALL id` | variable | Call to hardware |
|
||||
|
||||
**ABI Rules for Syscalls:**
|
||||
* **Argument Order:** Arguments must be pushed in the order they appear in the call (LIFO stack behavior).
|
||||
* Example: `gfx.draw_rect(x, y, w, h, color)` means:
|
||||
1. `PUSH x`
|
||||
2. `PUSH y`
|
||||
3. `PUSH w`
|
||||
4. `PUSH h`
|
||||
5. `PUSH color`
|
||||
6. `SYSCALL 0x1002`
|
||||
* **Consumption:** The native function MUST pop all its arguments from the stack.
|
||||
* **Return Value:** If the syscall returns a value, it will be pushed onto the stack by the native implementation. If not, the stack state for the caller remains as it was before pushing arguments.
|
||||
|
||||
#### Implemented Syscalls (v0.1)
|
||||
|
||||
| ID | Name | Arguments (Stack) | Return |
|
||||
|
||||
Reference in New Issue
Block a user