Runtime ABI
This is the contract used by niblick/compiler.py and
niblick/runtime/runtime.asm.
Values
Type |
Representation |
|---|---|
|
One register or one RAM nibble |
|
Two nibbles, low first |
|
Four nibbles, low first |
|
Eight nibbles, low first |
|
Sixteen nibbles; results use a memory buffer |
|
Three nibbles: low, middle, high |
|
No value |
Signed and unsigned types share the same layout. Signed values are two’s complement; widening sign-extends.
Expression results use fixed registers:
Width |
Registers |
|---|---|
4-bit |
|
8-bit |
|
16-bit |
|
32-bit |
|
|
|
R0 is reserved for instructions that access memory only through it:
MOV [NN],R0, MOV R0,[NN], MOV [XY],R0, MOV R0,[XY], CP R0,N,
ADD R0,N, and the immediate logical forms.
User function calls
Niblick uses static parameter slots, not register argument passing.
The compiler allocates a fixed RAM slot for every parameter and local.
At a call site, each argument expression is evaluated and stored into the callee’s parameter slot.
The caller executes
GOSUB fn_name.The callee returns with
RET R0,0. Anibbleresult is inR1; acharresult is low inR1, high inR2.The caller treats
R0throughR9as clobbered. Temporaries that must survive a call live in the caller’s frame.
Functions are non-reentrant. Parameter and local slots are overlaid across functions that cannot be active at the same time. A function that keeps an expression temporary live across a call gets a private temporary area in its own frame.
Tail calls
A call in tail position compiles to GOTO:
; return f(a, b);
<evaluate args into temporaries>
<copy temporaries into f's parameter slots>
GOTO fn_f
The callee’s RET returns to the original caller. Tail recursion uses constant
hardware stack depth. Self-tail calls evaluate all arguments into temporaries
before overwriting parameter slots. Non-tail recursion is rejected.
Runtime library ABI
The UART and flash helpers are hand-written assembly and use the expression result registers:
Routine |
Input |
Output |
|---|---|---|
|
|
none |
|
none |
|
|
|
none |
|
|
|
|
none |
|
|
|
none |
|
|
none |
|
|
none |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
quotient |
|
|
quotient |
|
|
signed quotient and remainder |
|
|
signed quotient and remainder |
|
|
|
|
|
quotient and remainder buffers |
Runtime routines may clobber R0 through R9 and do not preserve flags. The
flash reader uses R6, R7, and R8 as the 12-bit pointer and R5 as a
scratch nibble.
User assembly modules
Imported .asm routines use the same static-slot convention:
import "my_driver.asm";
extern fn char read_byte(char addr_lo);
fn_read_byte:
MOV R0, [${addr_lo}]
...
RET R0, 0
Parameters are allocated in RAM and read with ${param}. Results use the normal
expression-result registers. The compiler scans GOSUB and GOTO in imported
assembly so runtime linking, the call graph, and stack reports stay accurate.
See Imported assembly modules.
GPIO and SFR helpers
gpio_read()readsINat0x0BorInBat0xFB.gpio_write(n)writesOUTat0x0AorOutBat0xFA.gpio_set,gpio_clear, andgpio_toggleread, modify, and write the output latch.gpio_testreads the input port and returns 1 if any masked bit is set.
The GPIO runtime routines are not linked when every call uses a constant mask.
The compiler emits BSET, BCLR, BTG, or BIT directly.
Other SFR helpers are ordinary library functions:
Helper |
Module |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Memory layout
The compiler uses these regions. The full data-memory map is in Voja4 Memory Map.
Range |
Use |
|---|---|
|
Compile-time expression temporaries |
|
16-bit multiply/divide runtime scratch |
|
Signed division sign scratch during a runtime call |
User RAM |
Optional 24-nibble 32-bit multiply/divide scratch |
|
Globals, parameters, locals, RAM arrays |
Call depth
main runs at depth 0. Each non-tail GOSUB consumes one hardware stack entry.
The compiler rejects a maximum non-tail user depth above 4.
Call |
Stack levels |
|---|---|
|
1 |
|
2 |
|
3 |
GPIO runtime fallback |
2 |
Signed 8-bit and 16-bit |
2 |
|
1 |
uart_init, uart_available, and uart_puts are library functions and add a
normal user frame around the runtime byte primitive.
--stack prints the deepest user path, per-function entry depth, runtime call
sites with cost, and a warning when a call would exceed the five hardware stack
entries.
Flash data
A flash char[] is stored as RET R0,nibble words: low nibble first, then high
nibble. A flash nibble[] is one RET word per element. Strings use 0x00 as
the terminator.
The compiler emits flash bytes as pairs of NIBBLE directives.
main
main is entered by GOTO fn_main, not GOSUB. It never returns to a caller;
return from main compiles to JR -1.