CONTRIBUTING.md

@@ -16,10 +16,22 @@ All functions in the standard library should follow the following outline:
 ; Arguments: <which register contains what argument>
 ; Result: <what is the result, and where is it stored>
 ; Clobbers: <list of registers that are clobbered>
+; Globals: <list of globals are accessed. OPTIONAL>
+; Errors: <list of any status codes returned in flags. OPTIONAL>
 <label>: <;SHOULD BE INLINED>
     <CODE>
 
 ```
 
 Functions should be in the appropriate asm file, if you are unsure where functionality fits make a seperate file and ask in the pull request
-Functions that are provided for convenience/reference but should be inlined in production code should be marked with `;SHOULD BE INLINED` after their label
+Functions that are provided for convenience/reference but should be inlined in production code should be marked with `;SHOULD BE INLINED` after their label.
+
+If the function returns a status code in flags, the preamble should list all it might return.
+
+## Globals
+
+Any function that uses global variables should document this in the preamble comment, see above.
+
+A file/module should check on intialisation that the address `globals.MAGIC_ADDRESS` contains the 16 bit value `globals.MAGIC_VALUE`, to ensure that the user has properly included [[src/start.asm]] and reservered the global variable area.
+
+No opinion is offered on whether modules can assume globals variables are initialised to zero.

README.md

@@ -3,7 +3,7 @@
 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.
+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).
 
@@ -20,7 +20,7 @@ If you are intersted in contributing have a look at [[CONTRIBUTING.md]]
 | preserved | sp, r8 - r12 |
 | scratch | flags, r1 - r7 |
 | arguments | r1 - r7 |
-| result | 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.
@@ -32,9 +32,14 @@ Should a function return more values than fit into the 7 registers, the caller h
 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

src/errno.asm

@@ -0,0 +1,27 @@
+; Error numbers should be 16 bit ODD numbers, so they can be loaded as immediates
+; and can be checked with:
+;
+;   qcall falible_function
+;   jne falible_ok ; Jump no error
+;       ; handle error
+;   falible_ok:
+;   ; Happy path
+;   ; ...
+; OR
+;   qcall falible_function
+;   je handle_error ; Jump if error
+;   ; Happy path
+;   ; ...
+;   handle_error:
+;       ; handle error
+
+pub const OK                   = 0x0000
+pub const SCREEN_INVALID_MODE  = 0x0001
+pub const SCREEN_INVALID_WIDTH = 0x0003
+pub const SCREEN_FB_TOO_SMALL  = 0x0005
+pub const SCREEN_OUTSIDE_FB    = 0x0007
+
+pub const MAGIC_BAD            = 0x8001
+
+; Extended error codes, these would require loading a 32 bit value.
+pub const EXT_OK              = 0x00000000

src/globals.asm

@@ -0,0 +1,30 @@
+; Addresses of global variables
+
+pub const MAGIC_ADDRESS_LONG = 0x0c       ; U32 Location of the magic value
+pub const MAGIC_VALUE_LONG   = 0xb301534c ; U32 Full 32 bits of the magic value
+pub const MAGIC_ADDRESS      = 0x0e       ; U16 Location of the low 16 bits of magic value
+pub const MAGIC_VALUE        = 0x534c     ; U16 Low 16 bits of the magic value
+
+; If not double buffering these point to the same buffer
+; If double buffering they must the same size
+pub const FB_DISPLAY_PTR     = 0x10       ; U32 Currently displayed buffer
+pub const FB_DISPLAY_STRIDE  = 0x14       ; U16 Bytes in each row of the displayed buffer
+pub const FB_DISPLAY_DEPTH   = 0x16       ; U16 Bits per pixel of the display buffer
+pub const FB_DRAW_PTR        = 0x18       ; U32 Draw to this buffer
+pub const FB_DRAW_STRIDE     = 0x1c       ; U16 Bytes in each row of the draw buffer == FB_DISPLAY_STRIDE
+pub const FB_DRAW_DEPTH      = 0x1e       ; U16 Bits per pixel of the draw buffer == FB_DISPLAY_DEPTH
+pub const FB_SIZE_BYTE       = 0x20       ; U32 In bytes
+pub const FB_WIDTH_PX        = 0x24       ; U16 Width of screen in pixels
+pub const FB_HEIGHT_PX       = 0x26       ; U16 Height of screen in pixels
+
+; Log2 of width in pixels, e.g.
+; * 10 => 1024 * 768
+; *  8 =>  256 * 192
+pub const FB_LOG_WIDTH       = 0x28       ; U8
+pub const FB_LOG_STRIDE      = 0x29       ; U8 Log2 of FB_xxx_STRIDE in bytes
+
+pub const FB_BYTES_PER_PIXEL = 0x2a       ; U8 Specialisations should hardcode this
+; Log2 of bytes per pixel
+; * 0 => 8 bits per pixel
+; * 2 => 32 bits per pixel
+pub const FB_LOG_BPP         = 0x2b       ; U8 Specialisations should hardcode this

src/start.asm

@@ -0,0 +1,19 @@
+;@0 ; Reserve space for globals
+
+; First initialise the stack pointer
+nor sp, zr, 0xffff
+; Jump over the globals to user code
+jmp 0x100
+
+U32 0 ; 4 bytes
+
+; MAGIC_VALUE
+;@0x0c
+U32 0xb301534c
+
+; Pad with zeroes since the @addr feature is currently broken.
+; * https://discord.com/channels/828292123936948244/1545010596246847568
+;
+U1920 0  ; 240 bytes
+
+;@0x100 ; start of user code