From 8e0fdf0d28df347c18500aca9302a718de928900 Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Mon, 31 Aug 2026 10:08:44 +0200 Subject: [PATCH 01/14] start readme --- README.md | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 44ed975..f492266 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,36 @@ -# symphony_stdlib +# 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 [stdlib.asm] is your main header, include it after your code. +You'll also need to include globals.asm in the first line of your main assembly file. + +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 +n.a. zr +preserved: sp, r8 - r12 +scratch: flags, r1 - r7 +arguments: r1 - r7 (r1 = 1st argument, r6 = 6th arg/stack args, r7 = 7th arg/stack res) +result: r1, r2 (r1 = low word, r2 = high word) +return address: r13 + +### Stack +grows downwards from top of memory +arguments are passed in reverse order with the stack so: +lowest address = 1st stack arg +highest address = last stack arg + +### Types + +#### String +Strings are stored in memory as null terminated sequences of bytes encoding ascii characters. +They should be passed by reference. -standard library for symphony \ No newline at end of file From af5a750031401d07623eabaf2205753c3f8233d7 Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Mon, 31 Aug 2026 10:10:10 +0200 Subject: [PATCH 02/14] link test --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f492266..63cdb77 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ You'll also need to include globals.asm in the first line of your main assembly 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] +If you are intersted in contributing have a look at [[CONTRIBUTING.md]] --- From 4bce47209a75a6d59c3fc2191485822eb0c5fd49 Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Mon, 31 Aug 2026 10:12:57 +0200 Subject: [PATCH 03/14] fix remaining links --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 63cdb77..1222934 100644 --- a/README.md +++ b/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 [stdlib.asm] is your main header, include it after your code. +If you just want to use the standard library [[stdlib.asm]] is your main header, include it after your code. You'll also need to include globals.asm in the first line of your main assembly file. If you are using it as a learning resource have a look at the [teaching folder](teaching). From daf4168129855f697199514299a27555489b018a Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Mon, 31 Aug 2026 10:17:25 +0200 Subject: [PATCH 04/14] format calling convention --- README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 1222934..0a39d03 100644 --- a/README.md +++ b/README.md @@ -15,12 +15,14 @@ If you are intersted in contributing have a look at [[CONTRIBUTING.md]] ## ABI ### Calling Convention -n.a. zr -preserved: sp, r8 - r12 -scratch: flags, r1 - r7 -arguments: r1 - r7 (r1 = 1st argument, r6 = 6th arg/stack args, r7 = 7th arg/stack res) -result: r1, r2 (r1 = low word, r2 = high word) -return address: r13 +| class | registers | +| ----- | --------- | +| n.a. | zr | +| preserved | sp, r8 - r12 | +| scratch | flags, r1 - r7 | +| arguments | r1 - r5, r6 = stack args, r7 = stack res | +| result | r1 = low word, r2 = high word | +| return address | r13 | ### Stack grows downwards from top of memory From 33b7886e7004718c4601a0089a73976afbf8fe8b Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Tue, 1 Sep 2026 13:07:13 +0200 Subject: [PATCH 05/14] add arrays to readme --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 0a39d03..fe2ddb7 100644 --- a/README.md +++ b/README.md @@ -36,3 +36,6 @@ highest address = last stack arg 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 From 60e7b6209f5e30ea4c650cd81601106cef0e8a67 Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Tue, 1 Sep 2026 13:18:46 +0200 Subject: [PATCH 06/14] basic contribution guidelines --- CONTRIBUTING.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..610468a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,25 @@ +# Contributing + +## Code of Conduct +Be nice, we are all just doing this to have fun + +## General rules +- All text (names, comments, etc.) has to be in English +- You are responsible for ensuring that you have the rights for us to use the code you contribute to the project +- follow the guidelines, for code, documentation, etc. +- all code has to work with the standard symphony ISA + +## Documenting Functions +All functions in the standard library should follow the following outline: +```asm +; +; Arguments: +; Result: +; Clobbers: +fn_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 + From f2e5c830b345173c577c6e4a983f2c4833dfe70e Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Tue, 1 Sep 2026 13:48:12 +0200 Subject: [PATCH 07/14] explain inline comment --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 610468a..82a0201 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,7 +11,7 @@ Be nice, we are all just doing this to have fun ## Documenting Functions All functions in the standard library should follow the following outline: -```asm +``` ; ; Arguments: ; Result: @@ -22,4 +22,4 @@ fn_label: <;SHOULD BE INLINED> ``` 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 From 9816111f387014142dedc9ef71473f968f8ce2f3 Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Tue, 1 Sep 2026 14:08:20 +0200 Subject: [PATCH 08/14] clarify stack arguments --- README.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index fe2ddb7..d16f476 100644 --- a/README.md +++ b/README.md @@ -20,16 +20,22 @@ If you are intersted in contributing have a look at [[CONTRIBUTING.md]] | n.a. | zr | | preserved | sp, r8 - r12 | | scratch | flags, r1 - r7 | -| arguments | r1 - r5, r6 = stack args, r7 = stack res | -| result | r1 = low word, r2 = high word | +| arguments | r1 - r7 | +| result | r1-r7 | | return address | r13 | -### Stack -grows downwards from top of memory -arguments are passed in reverse order with the stack so: +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 r7. +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 r7. +r7 points at the highest available address for results, with the 8th result being stored there, the 9th below it and so on. + +### Stack +Grows downwards from top of memory. + ### Types #### String From a3d6cb64b5b2ac8c81e58ce874ae64c13f3a73fe Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Wed, 2 Sep 2026 11:17:18 +0200 Subject: [PATCH 09/14] remove duplicate documentation from stdlib.asm --- stdlib.asm | 25 +------------------------ 1 file changed, 1 insertion(+), 24 deletions(-) diff --git a/stdlib.asm b/stdlib.asm index 5852f04..1b352f1 100644 --- a/stdlib.asm +++ b/stdlib.asm @@ -1,25 +1,2 @@ -; ===== INTRODUCTION ===== -; This is supposed to provide some standard library functionality for stock symphony. -; In particular its supposed to work with an unmodified ISA, that means some choices are not -; optimal (RA being stored in flags for example) - -; ===== ABI ===== - -; ----- CALLING CONVENTION ----- -; n.a. zr -; preserved: sp, r8 - r12 -; scratch: flags, r1 - r7 -; arguments: r1 - r7 (r1 = 1st argument, r6 = 6th arg/stack args, r7 = 7th arg/stack res) -; result: r1, r2 (r1 = low word, r2 = high word) -; return address: r13 - -; ----- STACK ----- -; grows downwards from top of memory -; arguments are passed in reverse order with the stack so: -; lowest address = 1st stack arg -; highest address = last stack arg - -; ===== TYPES ===== - pub include bit -pub include imath \ No newline at end of file +pub include imath From ddca02d8a80a2344699f8ff833e878a103643ca6 Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Wed, 2 Sep 2026 11:21:03 +0200 Subject: [PATCH 10/14] relax r7 requirement for result stack --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d16f476..12c7afd 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,9 @@ 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 r7. -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 r7. -r7 points at the highest available address for results, with the 8th result being stored there, the 9th below it and so on. +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. ### Stack Grows downwards from top of memory. From 8f1b970a2f5e4cc535ce308e87564c094f69341c Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Wed, 2 Sep 2026 11:31:33 +0200 Subject: [PATCH 11/14] remove mention of non existent file --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 12c7afd..aec7650 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,6 @@ 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 [[stdlib.asm]] is your main header, include it after your code. -You'll also need to include globals.asm in the first line of your main assembly file. If you are using it as a learning resource have a look at the [teaching folder](teaching). From dbd4865f1485ba747307377ec07550e34b7fa847 Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Wed, 2 Sep 2026 11:31:52 +0200 Subject: [PATCH 12/14] change stack start --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index aec7650..1a3d693 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ This reduces the amount of argument registers to 6 and all arguments above that This register points at the highest available address for results, with the 8th result being stored there, the 9th below it and so on. ### Stack -Grows downwards from top of memory. +Grows downwards from 0xXXFE_0000 (so top of memory -0x1_0000). ### Types From 8301d5988a4b8ee0f31a43a1221d6253165e7db0 Mon Sep 17 00:00:00 2001 From: ShatteredMINT Date: Wed, 2 Sep 2026 11:32:46 +0200 Subject: [PATCH 13/14] create teaching directory --- teaching/README.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 teaching/README.md diff --git a/teaching/README.md b/teaching/README.md new file mode 100644 index 0000000..67ae43d --- /dev/null +++ b/teaching/README.md @@ -0,0 +1,5 @@ +# Teaching + +This is a collection of teaching advice regarding the stdlib. + +**WIP** From 84636799b6d1f65a819628419911da04a747dabe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Isalski?= Date: Tue, 1 Sep 2026 22:42:32 +0200 Subject: [PATCH 14/14] Changed docs of math functions to conform to new guidelines --- imath.asm | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/imath.asm b/imath.asm index 90056f0..0c08923 100644 --- a/imath.asm +++ b/imath.asm @@ -1,8 +1,15 @@ +; Multiplies r1 and r2, returning the lower part of the result +; Arguments: +; r1 - The first value +; r2 - The second value +; Result: +; r1 - The lower 32 bits of the result +; Clobbers: r2, r3, r4, r5 pub mul_low: mov r3, 0 ; result mov r4, 31 ; loop counter - mull_loop: + mul_low_loop: asr r5, r2, 31 and r5, r5, r1 lsl r5, r5, r4 @@ -10,14 +17,18 @@ pub mul_low: lsl r2, r2, 1 sub r4, r4, 1 cmp r4, 0 - jge mull_loop + jge mul_low_loop mov r1, r3 jmp r13 ; Calculates the absolute value of the value provided in the r1 register -; Based on Stanford's BitHacks -; Clobbers r2 +; Arguments: +; r1 - The value for which we want the absolute value +; Result: +; r1 - The calculated absolute value +; Clobbers: r2 +; Info: Based on Stanford's BitHacks pub abs: ; SHOULD BE INLINED ; mask = v >> 31 asr r2, r1, 31 @@ -28,8 +39,13 @@ pub abs: ; SHOULD BE INLINED jmp r13 ; Calculates the minimum value of the two values provided in the r1 and r2 registers -; Based on Stanford's BitHacks -; Clobbers flags +; Arguments: +; r1 - The first value +; r2 - The second value +; Result: +; r1 - The smaller value +; Clobbers: Nothing +; Info: Based on Stanford's BitHacks pub min: ; SHOULD BE INLINED ; x < y cmp r1, r2 @@ -45,8 +61,13 @@ pub min: ; SHOULD BE INLINED jmp r13 ; Calculates the maximum value of the two values provided in the r1 and r2 registers -; Based on Stanford's BitHacks -; Clobbers r2 and flags +; Arguments: +; r1 - The first value +; r2 - The second value +; Result: +; r1 - The smaller value +; Clobbers: r2 +; Info: Based on Stanford's BitHacks pub max: ; SHOULD BE INLINED ; x < y cmp r1, r2