mention globabls.asm

Added handling for backspace character

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:
+```
+; <description>
+; Arguments: <which register contains what argument>
+; Result: <what is the result, and where is it stored>
+; Clobbers: <list of registers that are clobbered>
+<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

MEMORY.md

@@ -0,0 +1,21 @@
+# Memory Map
+
+To not have to allocate a ton of things at run time the Standard Library uses a static memory map for some purposes
+
+## Overview
+
+| Start | Use |
+| ---- | ---- |
+| `0x0` | Reset Vector |
+| `0x16` | Zero Page |
+| `0x100` | User Code |
+| `?` | Library Code |
+| `0x1_0000` | LUTs |
+| `?` | heap |
+| `0xXXF0_0000` | Stack |
+| `0xXXFF_0000` | quick access |
+
+## Zero Page
+Some values are needed not often enough to get their own special register, but often enough that it makes sense to keep them at a quickly accessible location.
+This is what the zero page is for. its position in memory allows us to load them into a register with a single instruction.
+

README.md

@@ -1,3 +1,47 @@
-# symphony_stdlib
+# Symphony Stdlib
 
-standard library for symphony
+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 also need to include [[globals.asm]] as the first line in your 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
+| class | registers |
+| ----- | --------- |
+| n.a. | zr |
+| preserved | sp, r8 - r12 |
+| scratch | flags, r1 - r7 |
+| arguments | r1 - r7 |
+| result | 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.
+
+### Stack
+Grows downwards from 0xXXFE_0000 (so top of memory -0x1_0000).
+
+### 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

examples/README.md

@@ -0,0 +1,3 @@
+# Examples
+
+Examples of how to use the standard library to accomplish a task.

globals.asm

@@ -0,0 +1,10 @@
+jmp 0x100
+
+@0x10
+screen:
+    frambuffer_ptr: U32 0x0
+    size: U32 0x0
+    position_xy: U32 0x0
+    mode: U32 0x0
+
+@0x100

imath.asm

@@ -1,16 +0,0 @@
-pub mul_low:
-	mov r3, 0 ; result
-	mov r4, 31 ; loop counter
-	
-	mull_loop:
-		asr r5, r2, 31
-		and r5, r5, r1
-		lsl r5, r5, r4
-		add r3, r3, r5
-		lsl r2, r2, 1
-		sub r4, r4, 1
-		cmp r4, 0
-		jge mull_loop
-	mov r1, r3
-	
-	jmp r13

src/LUTs.asm

@@ -1,4 +1,4 @@
-@0x10000: ; Example address until we get a proper memory map for this
+@0x10000 ; Example address until we get a proper memory map for this
 
 ; Shift conversion table
 ; It stores the mapping from value 32-127 of the ASCII table to their shifted equivalents (both ways) in the standard US keyboard layout

src/array.asm

@@ -0,0 +1,77 @@
+; Returns the index of the first element matching the provided predicate function (or -1 if not found)
+; Arguments:
+; r1 - The array pointer
+; r2 - The array length (number of items)
+; r3 - The stride (size of one item) - either 1, 2 or 4 (bytes)
+; r4 - The predicate
+; r5 - Predicate context
+; Result:
+; r1 - The index of the first element matching the provided predicate function (or -1 if not found)
+; Clobbers: r2, r3, r4, r5, r6, + what the predicate clobbers
+; Info:
+; The predicate function should follow the stdlib calling convention
+; The predicate receives two arguments (the value and the predicate context) and should return either a zero when the value is not the one we search for
+; , or any other result if it is the searched-for item.
+pub find_index:
+    push r12 ; We will store the predicate pointer here
+    push r11 ; We will store the current pointer here
+    push r10 ; We will store the stride here
+    push r9 ; We will store the final address here
+    push r8 ; We will store the mask here
+
+    mov r12, r4
+    mov r11, r1
+    mov r10, r3
+    mov r9, r2
+    lsr r6, r3, 1 ; We turn the stride into a byte shift
+    lsl r9, r9, r6 ; We calculate bytes left
+    add r9, r9, r1 ; We add the start address to get the final address
+
+    push r13 ; We save up the return address because we will provide our own to the predicate
+    push r1 ; We need the array pointer to calculate the item index
+    counter r13
+    add r13, r13, 52 ; Point to just after the predicate call - we can set this up now so we don't waste loop cycles
+
+    nand r8, zr, zr ; We create a mask of 0xFFFFFFFF
+    mov r6, 4
+    sub r6, r6, r3 ; We create a "negative stride", e.g. 4 -> 0, 2 -> 2, 1 -> 3
+    lsl r6, r6, 3
+    lsr r8, r8, r6 ; We shift the mask by the negative stride to obtain the proper mask for a value
+    ; e.g. stride 4 -> mask is 0xFFFFFFFF
+    ; stride 2 -> mask is 0x0000FFFF
+    ; stride 1 -> mask is 0x000000FF
+
+    push r5 ; We save the predicate context on the stack
+    find_index_loop:
+        load_32 r1, [r11] ; We load the element
+        and r1, r1, r8 ; We mask it to handle stride 2 and 1 cases
+        load_32 r2, [sp] ; We load the predicate context into r2
+        jmp r12 ; We call the predicate
+        cmp r1, zr
+        jne find_index_found_item ; If we found the item, we jump out
+        ; If we didn't, move to next item
+        add r11, r11, r10 ; We add the stride to the pointer
+        cmp r11, r9 ; We compare with the final address
+        jne find_index_loop ; If we did not reach the end we jump back into the loop
+    
+    find_index_not_found:
+        add sp, sp, 8 ; The predicate context and old array pointer are not useful
+        pop r13 ; We get our return address
+        nand r1, zr, zr ; We put -1 in r1
+        jmp find_index_postamble
+    
+    find_index_found_item:
+        add sp, sp, 4 ; The predicate context is not useful
+        pop r1 ; We get the array pointer
+        pop r13 ; We get our return address
+        sub r1, r11, r1 ; We calculate the bytes from the start
+        lsr r10, r10, 1 ; We shift the stride to get the amount to shift the bytes for
+        lsr r1, r1, r10 ; We shift to get the index of the item
+
+    find_index_postamble:
+        pop r8
+        pop r9
+        pop r10
+        pop r11
+        pop r12
+        jmp r13 ; Return

src/bit.asm

@@ -70,3 +70,25 @@ pub popc:
 	add r4, r4, r2
 	and r1, r4, 0xFF ; mask out end result in lowest byte
 	jmp r13
+
+; Calculates the parity of the value provided in the r1 register
+; i.e. 0 means even bits set, 1 means odd bits set
+; Based on Stanford's BitHacks
+; Clobbers r2
+pub parity:
+	; v ^= v >> 16;
+	lsr r2, r1, 16
+	xor r1, r1, r2
+	; v ^= v >> 8;
+	lsr r2, r1, 8
+	xor r1, r1, r2
+	; v ^= v >> 4;
+	lsr r2, r1, 4
+	xor r1, r1, r2
+	; v &= 0xf;
+	and r1, r1, 0x0F
+	; return (0x6996 >> v) & 1;
+	mov r2, 0x6996
+	lsr r1, r2, r1
+	and r1, r1, 0x01
+	jmp r13

src/imath.asm

@@ -0,0 +1,83 @@
+; 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
+	
+	mul_low_loop:
+		asr r5, r2, 31
+		and r5, r5, r1
+		lsl r5, r5, r4
+		add r3, r3, r5
+		lsl r2, r2, 1
+		sub r4, r4, 1
+		cmp r4, 0
+		jge mul_low_loop
+	mov r1, r3
+	
+	jmp r13
+
+; Calculates the absolute value of the value provided in the r1 register
+; 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
+	; v + mask
+	add r1, r1, r2
+	; return (v + mask) ^ mask
+	xor r1, r1, r2
+	jmp r13
+
+; Calculates the minimum value of the two values provided in the r1 and r2 registers
+; 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
+	lsr flags, flags, 2
+	; -(x < y)
+	neg flags, flags
+	; x ^ y
+	xor r1, r1, r2
+	; (x ^ y) & -(x < y)
+	and r1, r1, flags
+	; return y ^ ((x ^ y) & -(x < y))
+	xor r1, r2, r1
+	jmp r13
+
+; Calculates the maximum value of the two values provided in the r1 and r2 registers
+; 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
+	lsr flags, flags, 2
+	; -(x < y)
+	neg flags, flags
+	; x ^ y
+	xor r2, r1, r2
+	; (x ^ y) & -(x < y)
+	and r2, r2, flags
+	; return x ^ ((x ^ y) & -(x < y))
+	xor r1, r1, r2
+	jmp r13

src/stdlib.asm

@@ -0,0 +1,6 @@
+pub include bit
+pub include imath
+pub include console
+
+; Needs to be last!
+pub include LUTs

stdlib.asm

@@ -1,29 +0,0 @@
-; ===== 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
-pub include console
-
-; Needs to be last!
-pub include LUTs

teaching/README.md

@@ -0,0 +1,5 @@
+# Teaching
+
+This is a collection of teaching advice regarding the stdlib.
+
+**WIP**

tests/README.md

@@ -0,0 +1,3 @@
+# Tests
+
+Tests for the standard library go here, tests are allowed to depend on the recommended spec.isa changes.