Initial version of atoi

Functions to convert strings to integers in various bases

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>
+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
+Functions that are provided for convenience/reference but should be inlined in production code should be marked with `;SHOULD BE INLINED` after their label

README.md

@@ -1,3 +1,46 @@
-# 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.
+
+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

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
+; Arguments:
-; Clobbers r2
+; 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
+; Arguments:
-; Clobbers flags
+; 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
+; Arguments:
-; Clobbers r2 and flags
+; 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

stdlib.asm

@@ -1,25 +1,3 @@
-; ===== 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 imath
+pub include strint

strint.asm

@@ -0,0 +1,145 @@
+; Convert string to integer
+; Arguments:
+; r1 - Pointer to string
+; Result:
+; r1 - Parsed integer
+; r2 - Pointer to first rejected input byte
+; Clobbers:
+; flags
+; r3 - last character read
+pub fn_atoi:
+load_8 r3, [r1]
+cmp r3, 0x30 ; '0'
+jne fn_atoi_dec ; No prefix, parse decimal
+add r1, r1, 1
+load_8 r3, [r1] ; From "boxBOX", or an octal digit
+cmp r3, 0x30 ; '0'
+jl atoi_badprefix
+cmp r3, 0x37 ; '7'
+jle fn_atoi_oct
+add r1, r1, 1 ; Not octal; 2-byte prefix 
+and r3, r3, 0x5f ; to uppercase
+cmp r3, 0x42 ; 'B'
+je fn_atoi_bin
+cmp r3, 0x4F ; 'O'
+je fn_atoi_oct
+cmp r3, 0x58 ; 'X'
+je fn_atoi_hex
+
+; not a valid prefix, but we did see a zero
+atoi_badprefix:
+mov r2, r1
+mov r1, 0
+; Only exists because conditional register jumps are not allowed
+atoi_done:
+jmp r13
+
+; Convert decimal string to integer
+; Arguments:
+; r1 - Pointer to string
+; Result:
+; r1 - Parsed integer
+; r2 - Pointer to first rejected input byte
+; Clobbers:
+; flags
+; r3 - last character read
+pub fn_atoi_dec:
+mov r2, r1
+mov r1, 0
+atoi_dec_loop:
+load_8 r3, [r2]
+cmp r3, 0x30 ; '0'
+jl atoi_done
+cmp r3, 0x39 ; '9'
+jg atoi_done
+add r2, r2, 1
+sub r3, r3, 0x30 ; '0'
+lsl flags, r1, 2
+add r1, r1, flags
+lsl r1, r1, 1
+add r1, r1, r3
+jmp atoi_dec_loop
+
+; Convert binary string to integer
+; Arguments:
+; r1 - Pointer to string
+; Result:
+; r1 - Parsed integer
+; r2 - Pointer to first rejected input byte
+; Clobbers:
+; flags
+; r3 - last character read
+pub fn_atoi_bin:
+mov r2, r1
+mov r1, 0
+atoi_bin_loop:
+load_8 r3, [r2]
+cmp r3, 0x30 ; '0'
+jl atoi_done
+cmp r3, 0x39 ; '1'
+jg atoi_done
+add r2, r2, 1
+sub r3, r3, 0x30 ; '0'
+lsl r1, r1, 1
+add r1, r1, r3
+jmp atoi_bin_loop
+
+; Convert octal string to integer
+; Arguments:
+; r1 - Pointer to string
+; Result:
+; r1 - Parsed integer
+; r2 - Pointer to first rejected input byte
+; Clobbers:
+; flags
+; r3 - last character read
+pub fn_atoi_oct:
+mov r2, r1
+mov r1, 0
+atoi_oct_loop:
+load_8 r3, [r2]
+cmp r3, 0x30 ; '0'
+jl atoi_done
+cmp r3, 0x39 ; '7'
+jg atoi_done
+add r2, r2, 1
+sub r3, r3, 0x30 ; '0'
+lsl r1, r1, 3
+add r1, r1, r3
+jmp atoi_oct_loop
+
+; Convert hexadecimal string to integer
+; Arguments:
+; r1 - Pointer to string
+; Result:
+; r1 - Parsed integer
+; r2 - Pointer to first rejected input byte
+; Clobbers:
+; flags
+; r3 - last character read
+pub fn_atoi_hex:
+mov r2, r1
+mov r1, 0
+atoi_hex_loop:
+load_8 r3, [r2]
+cmp r3, 0x30 ; '0'
+jl atoi_done
+cmp r3, 0x39 ; '9'
+jg atoi_hex_letter
+add r2, r2, 1
+sub r3, r3, 0x30 ; '0'
+lsl r1, r1, 4
+add r1, r1, r3
+jmp atoi_hex_loop
+
+atoi_hex_letter:
+and r3, r3, 0x5f ; to uppercase
+cmp r3, 0x41 ; 'A'
+jl atoi_done
+cmp r3, 0x46 ; 'F'
+jg atoi_done
+add r2, r2, 1
+sub r3, r3, 0x37 ; 'A' - 10
+lsl r1, r1, 4
+add r1, r1, r3
+jmp atoi_hex_loop

strint_test.asm

@@ -0,0 +1,86 @@
+mov r1, 1
+mov r2, test1
+mov r3, test1_end
+mov r13, test1_pass
+jmp atoi_test
+test1_pass:
+
+mov r1, 2
+mov r2, test2
+mov r3, test2_end
+mov r13, test2_pass
+jmp atoi_test
+test2_pass:
+
+mov r1, 3
+mov r2, test3
+mov r3, test3_end
+mov r13, test3_pass
+jmp atoi_test
+test3_pass:
+
+mov r1, 4
+mov r2, test4
+mov r3, test4_end
+mov r13, test4_pass
+jmp atoi_test
+test4_pass:
+
+mov r1, 5
+mov r2, test5
+mov r3, test5_end
+mov r13, test5_pass
+jmp atoi_test
+test5_pass:
+
+success:
+jmp success
+
+; test strint.fn_atoi
+; Arguments:
+; r1 - test number
+; r2 - test data label
+; r3 - test end-of-string label
+; Result:
+; void. Hangs in failure: on failure.
+; Clobbers:
+; r8 - test number
+; r9 - Expected result in r1
+; r10 - Expected result in r2
+; Notes:
+; Depends on fn_atoi not clobbering r8-r10.
+atoi_test:
+mov r8, r1
+load_32 r9, [r2]
+add r1, r2, 4
+mov r10, r3
+push r13
+mov r13, atoi_test_ret
+jmp stdlib.strint.fn_atoi
+atoi_test_ret:
+pop r13
+cmp r1, r9
+jne failure
+cmp r2, r10
+jne failure
+jmp r13
+
+failure:
+jmp failure
+
+test1: U32 0 "0"
+test1_end: "\0"
+
+test2: U32 1 "1"
+test2_end: "\0"
+
+test3: U32 2 "2"
+test3_end: "\0"
+
+test4: U32 42 "42"
+test4_end: "\0"
+
+test5: U32 67 "67"
+test5_end: "lol"
+
+include stdlib

teaching/README.md

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