If you just want to use the standard library src/stdlib.asm is your main header, include it after your code. Some modules also require src/start.asm at the very start of the program.

If you are using it as a learning resource have a look at the teaching folder.

If you are intersted in contributing have a look at CONTRIBUTING.md

ABI

Calling Convention

class	registers
n.a.	zr
preserved	sp, r8 - r12
scratch	flags, r1 - r7
arguments	r1 - r7
result	flags, r1 - r7
return address	r13

Arguments not fitting into the 7 registers should be passed on the top of the stack, meaning they should be the last values pushed before the function call. Arguments are passed in reverse order with the stack so: lowest address = 1st stack arg highest address = last stack arg

Should a function return more values than fit into the 7 registers, the caller has to allocate space on the stack for them, and pass the pointer to that space in the next free argument register. This reduces the amount of argument registers to 6 and all arguments above that shall go on the stack, the pointer to the result stack shall always be passed in an argument register. This register points at the highest available address for results, with the 8th result being stored there, the 9th below it and so on.

Some functions return a success/failure status code in flags. A set low bit will indicate some error condition, the function may return more than one possible value to report different errors. A flags value of 0 is set on success. No other even values are used. This can be checked with je or jne immediatly on return to the caller. All other functions clobber flags.

Stack

Grows downwards from 0xXXFE_0000 (so top of memory -0x1_0000).

Globals

Global variables are stored near the bottom of RAM in the address range 0x0010..0x0100. Programs should include src/start as the first line before their own code and before other includes, or otherwise reserve this space, the first instruction should be a jump to user code.

Types

String

Strings are stored in memory as null terminated sequences of bytes encoding ascii characters. They should be passed by reference.

Array

Arrays are stored in memory with a reference to them being the tuple (pointer, length) stored in a register pair. Array elements may only have a size of 8/16/32 bits