forked from TCShenanigans/symphony_stdlib
Gelthor
46abf8d893
Added support for global variables. This requires including `start.asm` as the first code. This includes a `jmp` to 0x100 for user code, and a magic number that modules can check to verify th the user has correctly reserved the space. The magic number is 0xb301534c: * This has the high bit set so is not a valid instruction * On builds that ignore the high bit this decodes to `nor zr, zr, 0x534c` a no-op. * The immediate is "SL" for standardl ibrary. Due to a bug start pads with U... 0, instead of @addr. `start.asm` also initialises `sp` so it start just below the 64KiB LUT memory alocation. Added some error codes for the upcoming graphics module.
52 lines
2.6 KiB
Markdown
52 lines
2.6 KiB
Markdown
# Symphony Stdlib
|
|
|
|
This is a standard library for symphony.
|
|
It is both intended as a practical toolkit to develop more complex software as well as a teaching resource.
|
|
|
|
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](teaching).
|
|
|
|
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
|