Add ISA definitions for symphony

Adds both a 'stock' ISA (copied from the game) and one modified for test
code

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

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 [[src/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

examples/README.md

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

isa/README.md

@@ -0,0 +1,43 @@
+Symphony ISA specs for use in stdlib
+
+# `default.isa`
+The stock game ISA. Production code must comply to this. Taken from `symphony_11_functions` in game version 2.1.330A
+
+# `test.isa`
+ISA with additional instructions. These additional instructions may be used in
+the tests directory only. Some of these instructions require hardware changes.
+
+## Labels in more instructions
+
+`cmp`, `load`, and `store` instructions (but not `pload` and `pstore`) now also accept labels.
+
+## `qcall %a(label)`
+Performs a jump-and-link function call, with label size up to 32 bits.
+
+_HARDWARE:_ Store PC+4 in the result register when in jump mode.
+
+## `li %a(register) %b:U32(immediate | label)
+Loads an immediate up to 32 bits long
+
+_HARDWARE:_ No requirements
+
+## `halt%c(condition)`
+Halts if `flags` matches the condition.
+
+_HARDWARE:_ Halt if instruction bit 31 is set AND the condition block is true.
+
+```
+condition
+""     1000
+".all" 1000
+".e"   0001
+".ne"  1001
+".b"   0010
+".ae"  1010
+".be"  0011
+".a"   1011
+".l"   0100
+".ge"  1100
+".le"  0101
+".g"   1101
+```

isa/default.isa

@@ -0,0 +1,316 @@
+[settings]
+name = "Symphony"
+
+[fields]
+
+register
+zr 0000
+r1 0001
+r2 0010
+r3 0011
+r4 0100
+r5 0101
+r6 0110
+r7 0111
+r8 1000
+r9 1001
+r10 1010
+r11 1011
+r12 1100
+r13 1101
+sp 1110
+flags 1111
+
+[instructions]
+
+nop
+00000000 00000000 00000000 00000000
+# (31337_88272577071256, `Does nothing.`)
+
+in %a(register)
+00000001 aaaa0000 00000000 00000000
+# (31337_44524771082050, `Loads an input and stores it in %a.`)
+
+out %b(register)
+00000010 00000000 0000bbbb 00000000
+# (31337_18254089726214, `Sends %b to output.`)
+
+out %a:U16(immediate)
+00010010 00000000 aaaaaaaa aaaaaaaa
+# (31337_15915531259935, `Sends %a to output.`)
+
+keyboard %a(register)
+00000011 aaaa0000 00000000 00000000
+# (31337_27868418224252, `Loads keyboard input and stores it to %a.`)
+
+screen %a(register), %b(register)
+00000100 0000aaaa 0000bbbb 00000000
+# (31337_39857449355186, `Stores the value of %b in screen setting %a.`)
+
+screen %a(register), %b:U16(immediate)
+00010100 0000aaaa bbbbbbbb bbbbbbbb
+# (31337_12835125621741, `Stores the value of %b in screen setting %a.`)
+
+time_0 %a(register)
+00000101 aaaa0000 00000000 00000000
+# (31337_72551400437977, `Loads the lower four bytes of the time value and stores it to %a.`)
+
+time_1 %a(register)
+00000110 aaaa0000 00000000 00000000
+# (31337_68219187873304, `Loads the upper four bytes of the time value and stores it to %a.`)
+
+counter %a(register)
+00000111 aaaa0000 00000000 00000000
+# (31337_67376584796076, `Loads the counter value and stores it to %a.`)
+
+
+
+nand %a(register), %b(register), %c(register)
+00100000 aaaabbbb 0000cccc 00000000
+# (31337_86705346481666, `NAND %b and %c and stores the result in %a.`)
+
+or %a(register), %b(register), %c(register)
+00100001 aaaabbbb 0000cccc 00000000
+# (31337_40732211165530, `OR %b and %c and stores the result in %a.`)
+
+and %a(register), %b(register), %c(register)
+00100010 aaaabbbb 0000cccc 00000000
+# (31337_85679146831122, `AND %b and %c and stores the result in %a.`)
+
+nor %a(register), %b(register), %c(register)
+00100011 aaaabbbb 0000cccc 00000000
+# (31337_37333076617857, `NOR %b and %c and stores the result in %a.`)
+
+add %a(register), %b(register), %c(register)
+00100100 aaaabbbb 0000cccc 00000000
+# (31337_51030225266712, `ADD %b and %c and stores the result in %a.`)
+
+sub %a(register), %b(register), %c(register)
+00100101 aaaabbbb 0000cccc 00000000
+# (31337_28652904157569, `SUB %b and %c and stores the result in %a.`)
+
+xor %a(register), %b(register), %c(register)
+00100110 aaaabbbb 0000cccc 00000000
+# (31337_46967848572964, `XOR %b and %c and stores the result in %a.`)
+
+lsl %a(register), %b(register), %c(register)
+00100111 aaaabbbb 0000cccc 00000000
+# (31337_13576771671264, `Logical shifts left %b by %c and stores the result in %a.`)
+
+lsr %a(register), %b(register), %c(register)
+00101000 aaaabbbb 0000cccc 00000000
+# (31337_67019902294705, `Logical shifts right %b by %c and stores the result in %a.`)
+
+asr %a(register), %b(register), %c(register)
+00101001 aaaabbbb 0000cccc 00000000
+# (31337_42626144645228, `Arithmetic shift right %b by %c and stores the result in %a.`)
+
+cmp %a(register), %b(register)
+00101010 1111aaaa 0000bbbb 00000000
+# (31337_54565380946620, `Compares %a and %b and stores the result in the 'flags' register.`)
+
+
+nand %a(register), %b(register), %c:U16(immediate | label)
+00110000 aaaabbbb cccccccc cccccccc
+# (31337_75302656449127, `NAND %b and %c and stores the result in %a.`)
+
+or %a(register), %b(register), %c:U16(immediate | label)
+00110001 aaaabbbb cccccccc cccccccc
+# (31337_30574433901064, `OR %b and %c and stores the result in %a.`)
+
+nor %a(register), %b(register), %c:U16(immediate | label)
+00110011 aaaabbbb cccccccc cccccccc
+# (31337_46087142860391, `NOR %b and %c and stores the result in %a.`)
+
+and %a(register), %b(register), %c:U16(immediate | label)
+00110010 aaaabbbb cccccccc cccccccc
+# (31337_86713121915282, `AND %b and %c and stores the result in %a.`)
+
+add %a(register), %b(register), %c:U16(immediate | label)
+00110100 aaaabbbb cccccccc cccccccc
+# (31337_23349431010010, `ADD %b and %c and stores the result in %a.`)
+
+sub %a(register), %b(register), %c:U16(immediate | label)
+00110101 aaaabbbb cccccccc cccccccc
+# (31337_67495552371225, `SUB %b and %c and stores the result in %a.`)
+
+xor %a(register), %b(register), %c:U16(immediate | label)
+00110110 aaaabbbb cccccccc cccccccc
+# (31337_66785854415645, `XOR %b and %c and stores the result in %a.`)
+
+lsl %a(register), %b(register), %c:U16(immediate | label)
+00110111 aaaabbbb cccccccc cccccccc
+# (31337_54577249258785, `Logical shifts left %b by %c and stores the result in %a.`)
+
+lsr %a(register), %b(register), %c:U16(immediate | label)
+00111000 aaaabbbb cccccccc cccccccc
+# (31337_16685334571248, `Logical shifts right %b by %c and stores the result in %a.`)
+
+asr %a(register), %b(register), %c:U16(immediate | label)
+00111001 aaaabbbb cccccccc cccccccc
+# (31337_55551510150818, `Arithmetic shifts right %b and %c and stores the result in %a.`)
+
+cmp %a(register), %b:U16(immediate)
+00111010 1111aaaa bbbbbbbb bbbbbbbb
+# (31337_37102964808364, `Compares %a and %b and stores the result in the 'flags' register.`)
+
+
+jmp %a(register)
+01001000 00001111 0000aaaa 00000000
+# (31337_74148826866592, `Jumps to %a.`)
+
+
+jmp %a:U16(immediate | label)
+01011000 00001111 aaaaaaaa aaaaaaaa
+# (31337_90876214388280, `Jumps to %a.`)
+
+je %a:U16(immediate | label)
+01010001 00001111 aaaaaaaa aaaaaaaa
+# (31337_88180305667389, `Jumps to %a if the values were equal (reading results from 'flags').`)
+
+jne %a:U16(immediate | label)
+01011001 00001111 aaaaaaaa aaaaaaaa
+# (31337_67178948469318, `Jumps to %a if the values were not equal (reading results from 'flags').`)
+
+
+jb %a:U16(immediate | label)
+01010010 00001111 aaaaaaaa aaaaaaaa
+# (31337_31763492459833, `Jumps to %a if the first value was below (unsigned) the second (reading results from 'flags').`)
+
+jae %a:U16(immediate | label)
+01011010 00001111 aaaaaaaa aaaaaaaa
+# (31337_82087388048746, `Jumps to %a if the first value was above (unsigned) or equal to the second (reading results from 'flags').`)
+
+jbe %a:U16(immediate | label)
+01010011 00001111 aaaaaaaa aaaaaaaa
+# (31337_26183125927881, `Jumps to %a if the First value was below (unsigned) or equal to the second (reading results from 'flags').`)
+
+ja %a:U16(immediate | label)
+01011011 00001111 aaaaaaaa aaaaaaaa
+# (31337_11626177279992, `Jumps to %a if the first value was above (unsigned) the second (reading results from 'flags').`)
+
+
+jl %a:U16(immediate | label)
+01010100 00001111 aaaaaaaa aaaaaaaa
+# (31337_71637103729391, `Jumps to %a if the first value was less (signed) than the second (reading results from 'flags').`)
+
+jge %a:U16(immediate | label)
+01011100 00001111 aaaaaaaa aaaaaaaa
+# (31337_53499765587663, `Jumps to %a if the first value was greater (signed) or equal to the second (reading results from 'flags').`)
+
+jle %a:U16(immediate | label)
+01010101 00001111 aaaaaaaa aaaaaaaa
+# (31337_77040234358389, `Jumps to %a if the first value was less (signed) or equal to the second (reading results from 'flags').`)
+
+jg %a:U16(immediate | label)
+01011101 00001111 aaaaaaaa aaaaaaaa
+# (31337_71317192057126, `Jumps to %a if the first value was greater (signed) than the second (reading results from 'flags').`)
+
+
+
+load_8 %dest(register), [%adr(register)]
+01100000 dddd0000 0000aaaa 00000000
+# (31337_57200935026773, `Loads address %adr from main memory and stores it to %dest.`)
+
+load_8 %dest(register), [%adr:U16(immediate)]
+01110000 dddd0000 aaaaaaaa aaaaaaaa
+# (31337_57200935026773, `Loads address %adr from main memory and stores it to %dest.`)
+
+load_16 %dest(register), [%adr(register)]
+01100001 dddd0000 0000aaaa 00000000
+# (31337_57200935026773, `Loads address %adr from main memory and stores it to %dest.`)
+
+load_16 %dest(register), [%adr:U16(immediate)]
+01110001 dddd0000 aaaaaaaa aaaaaaaa
+# (31337_57200935026773, `Loads address %adr from main memory and stores it to %dest.`)
+
+load_32 %dest(register), [%adr(register)]
+01100010 dddd0000 0000aaaa 00000000
+# (31337_57200935026773, `Loads address %adr from main memory and stores it to %dest.`)
+
+load_32 %dest(register), [%adr:U16(immediate)]
+01110010 dddd0000 aaaaaaaa aaaaaaaa
+# (31337_57200935026773, `Loads address %adr from main memory and stores it to %dest.`)
+
+pload %dest(register), [%adr(register)]
+01100011 dddd0000 0000aaaa 00000000
+# (31337_89257021109854, `Loads address %adr from persistent memory and stores it to %dest.`)
+
+pload %dest(register), [%adr:U16(immediate)]
+01110011 dddd0000 aaaaaaaa aaaaaaaa
+# (31337_89257021109854, `Loads address %adr from persistent memory and stores it to %dest.`)
+
+store_8 [%adr(register)], %value(register)
+01100100 0000vvvv 0000aaaa 00000000
+# (31337_61040780958703, `Stores %value to address %adr in main memory.`)
+
+store_8 [%adr:U16(immediate)], %value(register)
+01110100 0000vvvv aaaaaaaa aaaaaaaa
+# (31337_61040780958703, `Stores %value to address %adr in main memory.`)
+
+store_16 [%adr(register)], %value(register)
+01100101 0000vvvv 0000aaaa 00000000
+# (31337_61040780958703, `Stores %value to address %adr in main memory.`)
+
+store_16 [%adr:U16(immediate)], %value(register)
+01110101 0000vvvv aaaaaaaa aaaaaaaa
+# (31337_61040780958703, `Stores %value to address %adr in main memory.`)
+
+store_32 [%adr(register)], %value(register)
+01100110 0000vvvv 0000aaaa 00000000
+# (31337_61040780958703, `Stores %value to address %adr in main memory.`)
+
+store_32 [%adr:U16(immediate)], %value(register)
+01110110 0000vvvv aaaaaaaa aaaaaaaa
+# (31337_61040780958703, `Stores %value to address %adr in main memory.`)
+
+pstore [%adr(register)], %value(register)
+01100111 0000vvvv 0000aaaa 00000000
+# (31337_13110303123442, `Stores %value to address %adr in persistent memory.`)
+
+pstore [%adr:U16(immediate)], %value(register)
+01110111 0000vvvv aaaaaaaa aaaaaaaa
+# (31337_13110303123442, `Stores %value to address %adr in persistent memory.`)
+
+
+mov %a(register), %b(register)
+00100001 aaaa0000 0000bbbb 00000000
+# (31337_53941960758392, `Moves a value to %a from %b.`)
+
+mov %a(register), %b:U16(immediate | label)
+00110001 aaaa0000 bbbbbbbb bbbbbbbb
+# (31337_34859363394334, `Moves a value to %a.`)
+
+neg %a(register), %b(register)
+00100101 aaaa0000 0000bbbb 00000000
+# (31337_72894099288447, `Negates a %b and stores it in %a.`)
+
+neg %a(register), %b:U16(immediate | label)
+00110101 aaaa0000 bbbbbbbb bbbbbbbb
+# (31337_57504570243305, `Negates a value and stores it in %a.`)
+
+not %a(register), %b(register)
+00100011 aaaa0000 0000bbbb 00000000
+# (31337_55357258069734, `Toggles the bits of %b and stores it in %a.`)
+
+not %a(register), %b:U16(immediate | label)
+00110011 aaaa0000 bbbbbbbb bbbbbbbb
+# (31337_40508048121543, `Toggles the bits of a value and stores it in %a.`)
+
+
+push %a(register)
+00110101 11101110 00000000 00000100   01100110 0000aaaa 00001110 00000000
+# (31337_28545157055801, `Pushes %a onto the stack. This instruction is a synonym for:   sub sp, sp, 4   store_32 [sp], %a`)
+
+pop %a(register)
+01100010 aaaa0000 00001110 00000000   00110100 11101110 00000000 00000100
+# (31337_54469754973269, `Pops %a off the stack. This instruction is a synonym for:   load_32 %a, [sp]   add sp, sp, 4`)
+
+call %a(label)
+00000111 11110000 00000000 00000000   00110100 11111111 00000000 00010100   00110101 11101110 00000000 00000100   01100110 00001111 00001110 00000000   01011000 00001111 aaaaaaaa aaaaaaaa
+# (31337_57788320241950, `Calls %a. Overwrites the flag register. This instruction is a synonym for:   counter flags   add flags, flags, 20   sub sp, sp, 4   store_32 [sp], flags   jmp %a`)
+
+ret
+01100010 11110000 00001110 00000000   00110100 11101110 00000000 00000100   01001000 00001111 00001111 00000000
+# (31337_48332460366102, `Returns from the last function call. Overwrites the flag register. This instruction is a synonym for:   load_32 flags, [sp]   add sp, sp, 4   jmp flags`)
+

isa/test.isa

@@ -0,0 +1,358 @@
+[settings]
+name = "Symphony"
+
+[fields]
+
+register
+zr 0000
+r1 0001
+r2 0010
+r3 0011
+r4 0100
+r5 0101
+r6 0110
+r7 0111
+r8 1000
+r9 1001
+r10 1010
+r11 1011
+r12 1100
+r13 1101
+sp 1110
+flags 1111
+
+condition
+""     1000
+".all" 1000
+".e"   0001
+".ne"  1001
+".b"   0010
+".ae"  1010
+".be"  0011
+".a"   1011
+".l"   0100
+".ge"  1100
+".le"  0101
+".g"   1101
+
+[instructions]
+
+nop
+00000000 00000000 00000000 00000000
+# (31337_88272577071256, `Does nothing.`)
+
+in %a(register)
+00000001 aaaa0000 00000000 00000000
+# (31337_44524771082050, `Loads an input and stores it in %a.`)
+
+out %b(register)
+00000010 00000000 0000bbbb 00000000
+# (31337_18254089726214, `Sends %b to output.`)
+
+out %a:U16(immediate)
+00010010 00000000 aaaaaaaa aaaaaaaa
+# (31337_15915531259935, `Sends %a to output.`)
+
+keyboard %a(register)
+00000011 aaaa0000 00000000 00000000
+# (31337_27868418224252, `Loads keyboard input and stores it to %a.`)
+
+screen %a(register), %b(register)
+00000100 0000aaaa 0000bbbb 00000000
+# (31337_39857449355186, `Stores the value of %b in screen setting %a.`)
+
+screen %a(register), %b:U16(immediate)
+00010100 0000aaaa bbbbbbbb bbbbbbbb
+# (31337_12835125621741, `Stores the value of %b in screen setting %a.`)
+
+time_0 %a(register)
+00000101 aaaa0000 00000000 00000000
+# (31337_72551400437977, `Loads the lower four bytes of the time value and stores it to %a.`)
+
+time_1 %a(register)
+00000110 aaaa0000 00000000 00000000
+# (31337_68219187873304, `Loads the upper four bytes of the time value and stores it to %a.`)
+
+counter %a(register)
+00000111 aaaa0000 00000000 00000000
+# (31337_67376584796076, `Loads the counter value and stores it to %a.`)
+
+
+
+nand %a(register), %b(register), %c(register)
+00100000 aaaabbbb 0000cccc 00000000
+# (31337_86705346481666, `NAND %b and %c and stores the result in %a.`)
+
+or %a(register), %b(register), %c(register)
+00100001 aaaabbbb 0000cccc 00000000
+# (31337_40732211165530, `OR %b and %c and stores the result in %a.`)
+
+and %a(register), %b(register), %c(register)
+00100010 aaaabbbb 0000cccc 00000000
+# (31337_85679146831122, `AND %b and %c and stores the result in %a.`)
+
+nor %a(register), %b(register), %c(register)
+00100011 aaaabbbb 0000cccc 00000000
+# (31337_37333076617857, `NOR %b and %c and stores the result in %a.`)
+
+add %a(register), %b(register), %c(register)
+00100100 aaaabbbb 0000cccc 00000000
+# (31337_51030225266712, `ADD %b and %c and stores the result in %a.`)
+
+sub %a(register), %b(register), %c(register)
+00100101 aaaabbbb 0000cccc 00000000
+# (31337_28652904157569, `SUB %b and %c and stores the result in %a.`)
+
+xor %a(register), %b(register), %c(register)
+00100110 aaaabbbb 0000cccc 00000000
+# (31337_46967848572964, `XOR %b and %c and stores the result in %a.`)
+
+lsl %a(register), %b(register), %c(register)
+00100111 aaaabbbb 0000cccc 00000000
+# (31337_13576771671264, `Logical shifts left %b by %c and stores the result in %a.`)
+
+lsr %a(register), %b(register), %c(register)
+00101000 aaaabbbb 0000cccc 00000000
+# (31337_67019902294705, `Logical shifts right %b by %c and stores the result in %a.`)
+
+asr %a(register), %b(register), %c(register)
+00101001 aaaabbbb 0000cccc 00000000
+# (31337_42626144645228, `Arithmetic shift right %b by %c and stores the result in %a.`)
+
+cmp %a(register), %b(register)
+00101010 1111aaaa 0000bbbb 00000000
+# (31337_54565380946620, `Compares %a and %b and stores the result in the 'flags' register.`)
+
+
+nand %a(register), %b(register), %c:U16(immediate | label)
+00110000 aaaabbbb cccccccc cccccccc
+# (31337_75302656449127, `NAND %b and %c and stores the result in %a.`)
+
+or %a(register), %b(register), %c:U16(immediate | label)
+00110001 aaaabbbb cccccccc cccccccc
+# (31337_30574433901064, `OR %b and %c and stores the result in %a.`)
+
+nor %a(register), %b(register), %c:U16(immediate | label)
+00110011 aaaabbbb cccccccc cccccccc
+# (31337_46087142860391, `NOR %b and %c and stores the result in %a.`)
+
+and %a(register), %b(register), %c:U16(immediate | label)
+00110010 aaaabbbb cccccccc cccccccc
+# (31337_86713121915282, `AND %b and %c and stores the result in %a.`)
+
+add %a(register), %b(register), %c:U16(immediate | label)
+00110100 aaaabbbb cccccccc cccccccc
+# (31337_23349431010010, `ADD %b and %c and stores the result in %a.`)
+
+sub %a(register), %b(register), %c:U16(immediate | label)
+00110101 aaaabbbb cccccccc cccccccc
+# (31337_67495552371225, `SUB %b and %c and stores the result in %a.`)
+
+xor %a(register), %b(register), %c:U16(immediate | label)
+00110110 aaaabbbb cccccccc cccccccc
+# (31337_66785854415645, `XOR %b and %c and stores the result in %a.`)
+
+lsl %a(register), %b(register), %c:U16(immediate | label)
+00110111 aaaabbbb cccccccc cccccccc
+# (31337_54577249258785, `Logical shifts left %b by %c and stores the result in %a.`)
+
+lsr %a(register), %b(register), %c:U16(immediate | label)
+00111000 aaaabbbb cccccccc cccccccc
+# (31337_16685334571248, `Logical shifts right %b by %c and stores the result in %a.`)
+
+asr %a(register), %b(register), %c:U16(immediate | label)
+00111001 aaaabbbb cccccccc cccccccc
+# (31337_55551510150818, `Arithmetic shifts right %b and %c and stores the result in %a.`)
+
+cmp %a(register), %b:U16(immediate | label)
+00111010 1111aaaa bbbbbbbb bbbbbbbb
+# (31337_37102964808364, `Compares %a and %b and stores the result in the 'flags' register.`)
+
+
+jmp %a(register)
+01001000 00001111 0000aaaa 00000000
+# (31337_74148826866592, `Jumps to %a.`)
+
+
+jmp %a:U16(immediate | label)
+01011000 00001111 aaaaaaaa aaaaaaaa
+# (31337_90876214388280, `Jumps to %a.`)
+
+je %a:U16(immediate | label)
+01010001 00001111 aaaaaaaa aaaaaaaa
+# (31337_88180305667389, `Jumps to %a if the values were equal (reading results from 'flags').`)
+
+jne %a:U16(immediate | label)
+01011001 00001111 aaaaaaaa aaaaaaaa
+# (31337_67178948469318, `Jumps to %a if the values were not equal (reading results from 'flags').`)
+
+
+jb %a:U16(immediate | label)
+01010010 00001111 aaaaaaaa aaaaaaaa
+# (31337_31763492459833, `Jumps to %a if the first value was below (unsigned) the second (reading results from 'flags').`)
+
+jae %a:U16(immediate | label)
+01011010 00001111 aaaaaaaa aaaaaaaa
+# (31337_82087388048746, `Jumps to %a if the first value was above (unsigned) or equal to the second (reading results from 'flags').`)
+
+jbe %a:U16(immediate | label)
+01010011 00001111 aaaaaaaa aaaaaaaa
+# (31337_26183125927881, `Jumps to %a if the First value was below (unsigned) or equal to the second (reading results from 'flags').`)
+
+ja %a:U16(immediate | label)
+01011011 00001111 aaaaaaaa aaaaaaaa
+# (31337_11626177279992, `Jumps to %a if the first value was above (unsigned) the second (reading results from 'flags').`)
+
+
+jl %a:U16(immediate | label)
+01010100 00001111 aaaaaaaa aaaaaaaa
+# (31337_71637103729391, `Jumps to %a if the first value was less (signed) than the second (reading results from 'flags').`)
+
+jge %a:U16(immediate | label)
+01011100 00001111 aaaaaaaa aaaaaaaa
+# (31337_53499765587663, `Jumps to %a if the first value was greater (signed) or equal to the second (reading results from 'flags').`)
+
+jle %a:U16(immediate | label)
+01010101 00001111 aaaaaaaa aaaaaaaa
+# (31337_77040234358389, `Jumps to %a if the first value was less (signed) or equal to the second (reading results from 'flags').`)
+
+jg %a:U16(immediate | label)
+01011101 00001111 aaaaaaaa aaaaaaaa
+# (31337_71317192057126, `Jumps to %a if the first value was greater (signed) than the second (reading results from 'flags').`)
+
+
+
+load_8 %dest(register), [%adr(register)]
+01100000 dddd0000 0000aaaa 00000000
+# (31337_57200935026773, `Loads address %adr from main memory and stores it to %dest.`)
+
+load_8 %dest(register), [%adr:U16(immediate | label)]
+01110000 dddd0000 aaaaaaaa aaaaaaaa
+# (31337_57200935026773, `Loads address %adr from main memory and stores it to %dest.`)
+
+load_16 %dest(register), [%adr(register)]
+01100001 dddd0000 0000aaaa 00000000
+# (31337_57200935026773, `Loads address %adr from main memory and stores it to %dest.`)
+
+load_16 %dest(register), [%adr:U16(immediate | label)]
+01110001 dddd0000 aaaaaaaa aaaaaaaa
+# (31337_57200935026773, `Loads address %adr from main memory and stores it to %dest.`)
+
+load_32 %dest(register), [%adr(register)]
+01100010 dddd0000 0000aaaa 00000000
+# (31337_57200935026773, `Loads address %adr from main memory and stores it to %dest.`)
+
+load_32 %dest(register), [%adr:U16(immediate | label)]
+01110010 dddd0000 aaaaaaaa aaaaaaaa
+# (31337_57200935026773, `Loads address %adr from main memory and stores it to %dest.`)
+
+pload %dest(register), [%adr(register)]
+01100011 dddd0000 0000aaaa 00000000
+# (31337_89257021109854, `Loads address %adr from persistent memory and stores it to %dest.`)
+
+pload %dest(register), [%adr:U16(immediate)]
+01110011 dddd0000 aaaaaaaa aaaaaaaa
+# (31337_89257021109854, `Loads address %adr from persistent memory and stores it to %dest.`)
+
+store_8 [%adr(register)], %value(register)
+01100100 0000vvvv 0000aaaa 00000000
+# (31337_61040780958703, `Stores %value to address %adr in main memory.`)
+
+store_8 [%adr:U16(immediate | label)], %value(register)
+01110100 0000vvvv aaaaaaaa aaaaaaaa
+# (31337_61040780958703, `Stores %value to address %adr in main memory.`)
+
+store_16 [%adr(register)], %value(register)
+01100101 0000vvvv 0000aaaa 00000000
+# (31337_61040780958703, `Stores %value to address %adr in main memory.`)
+
+store_16 [%adr:U16(immediate | label)], %value(register)
+01110101 0000vvvv aaaaaaaa aaaaaaaa
+# (31337_61040780958703, `Stores %value to address %adr in main memory.`)
+
+store_32 [%adr(register)], %value(register)
+01100110 0000vvvv 0000aaaa 00000000
+# (31337_61040780958703, `Stores %value to address %adr in main memory.`)
+
+store_32 [%adr:U16(immediate | label)], %value(register)
+01110110 0000vvvv aaaaaaaa aaaaaaaa
+# (31337_61040780958703, `Stores %value to address %adr in main memory.`)
+
+pstore [%adr(register)], %value(register)
+01100111 0000vvvv 0000aaaa 00000000
+# (31337_13110303123442, `Stores %value to address %adr in persistent memory.`)
+
+pstore [%adr:U16(immediate)], %value(register)
+01110111 0000vvvv aaaaaaaa aaaaaaaa
+# (31337_13110303123442, `Stores %value to address %adr in persistent memory.`)
+
+
+mov %a(register), %b(register)
+00100001 aaaa0000 0000bbbb 00000000
+# (31337_53941960758392, `Moves a value to %a from %b.`)
+
+mov %a(register), %b:U16(immediate | label)
+00110001 aaaa0000 bbbbbbbb bbbbbbbb
+# (31337_34859363394334, `Moves a value to %a.`)
+
+neg %a(register), %b(register)
+00100101 aaaa0000 0000bbbb 00000000
+# (31337_72894099288447, `Negates a %b and stores it in %a.`)
+
+neg %a(register), %b:U16(immediate | label)
+00110101 aaaa0000 bbbbbbbb bbbbbbbb
+# (31337_57504570243305, `Negates a value and stores it in %a.`)
+
+not %a(register), %b(register)
+00100011 aaaa0000 0000bbbb 00000000
+# (31337_55357258069734, `Toggles the bits of %b and stores it in %a.`)
+
+not %a(register), %b:U16(immediate | label)
+00110011 aaaa0000 bbbbbbbb bbbbbbbb
+# (31337_40508048121543, `Toggles the bits of a value and stores it in %a.`)
+
+
+push %a(register)
+00110101 11101110 00000000 00000100   01100110 0000aaaa 00001110 00000000
+# (31337_28545157055801, `Pushes %a onto the stack. This instruction is a synonym for:   sub sp, sp, 4   store_32 [sp], %a`)
+
+pop %a(register)
+01100010 aaaa0000 00001110 00000000   00110100 11101110 00000000 00000100
+# (31337_54469754973269, `Pops %a off the stack. This instruction is a synonym for:   load_32 %a, [sp]   add sp, sp, 4`)
+
+call %a(label)
+00000111 11110000 00000000 00000000   00110100 11111111 00000000 00010100   00110101 11101110 00000000 00000100   01100110 00001111 00001110 00000000   01011000 00001111 aaaaaaaa aaaaaaaa
+# (31337_57788320241950, `Calls %a. Overwrites the flag register. This instruction is a synonym for:   counter flags   add flags, flags, 20   sub sp, sp, 4   store_32 [sp], flags   jmp %a`)
+
+ret
+01100010 11110000 00001110 00000000   00110100 11101110 00000000 00000100   01001000 00001111 00001111 00000000
+# (31337_48332460366102, `Returns from the last function call. Overwrites the flag register. This instruction is a synonym for:   load_32 flags, [sp]   add sp, sp, 4   jmp flags`)
+
+
+li %r(register), %a:S33(immediate | label)
+; assert(0 - 0x80000000 <= %a, "%a is too low")
+; assert(%a <= 0xffffffff, "%a is too high")
+%nota = ~%a
+when 0x0000 <= %a && %a <= 0xffff: 00110001 rrrr0000 %a[15:0]                                           ; First 64k
+when %nota <= 0xffff             : 00110001 rrrr0000 %nota[15:0]    00100011 rrrr0000 0000rrrr 00000000 ; Last 64k
+when !(%a & 0x0f) && %a < 0xffff0: 00110001 rrrr0000 %a[19:4]       00100111 rrrrrrrr 00000000 00000100 ; 16-byte aligned
+when !(%a & 0x03) && %a < 0x3fffc: 00110001 rrrr0000 %a[17:2]       00100111 rrrrrrrr 00000000 00000010 ; 4-byte aligned
+00110001 rrrr0000 %a[31:16]   00100111 rrrrrrrr 00000000 00010000   00110001 rrrrrrrr %a[15:0]          ; Any 32-bit
+# Load 32-bit immediate %a into %r
+
+qcall %a:U32(label)
+; assert(0 - 0x80000000 <= %a, "%a is too low")
+; assert(%a <= 0xffffffff, "%a is too high")
+%r = 13
+%f = 15
+%nota = ~%a
+when 0x0000 <= %a && %a <= 0xffff: 01011000 rrrrffff %a[15:0]                                                                                  ; First 64k
+when %nota <= 0xffff             : 00110001 rrrr0000 %nota[15:0]    00100011 rrrr0000 0000rrrr 00000000    01001000 rrrrffff 0000rrrr 00000000 ; Last 64k
+when !(%a & 0x0f) && %a < 0xffff0: 00110001 rrrr0000 %a[19:4]       00100111 rrrrrrrr 00000000 00000100    01001000 rrrrffff 0000rrrr 00000000 ; 16-byte aligned
+when !(%a & 0x03) && %a < 0x3fffc: 00110001 rrrr0000 %a[17:2]       00100111 rrrrrrrr 00000000 00000010    01001000 rrrrffff 0000rrrr 00000000 ; 4-byte aligned
+00110001 rrrr0000 %a[31:16]   00100111 rrrrrrrr 00000000 00010000   00110001 rrrrrrrr %a[15:0]             01001000 rrrrffff 0000rrrr 00000000 ; Any 32-bit
+# Jump and link to 32-bit label
+
+halt%c(condition)
+1000cccc 00001111 00000000 00000000
+# Halt on condition %c

src/LUTs.asm

@@ -0,0 +1,100 @@
+@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
+; e.g. 1 -> !
+U8 32 ; Space -> Space
+U8 49 ; ! -> 1
+U8 39 ; " -> '
+U8 51 ; # -> 3
+U8 52 ; $ -> 4
+U8 53 ; % -> 5
+U8 55 ; & -> 7
+U8 34 ; ' -> "
+U8 57 ; ( -> 9
+U8 48 ; ) -> 0
+U8 56 ; * -> 8
+U8 61 ; + -> =
+U8 60 ; , -> <
+U8 95 ; - -> _
+U8 62 ; . -> >
+U8 63 ; / -> ?
+U8 41 ; 0 -> )
+U8 33 ; 1 -> !
+U8 64 ; 2 -> @
+U8 35 ; 3 -> #
+U8 36 ; 4 -> $
+U8 37 ; 5 -> %
+U8 94 ; 6 -> ^
+U8 38 ; 7 -> &
+U8 42 ; 8 -> *
+U8 40 ; 9 -> (
+U8 59 ; : -> ;
+U8 58 ; ; -> :
+U8 44 ; < -> ,
+U8 43 ; = -> +
+U8 46 ; > -> .
+U8 47 ; ? -> /
+U8 50 ; @ -> 2
+U8 97 ; A -> a
+U8 98 ; B -> b
+U8 99 ; C -> c
+U8 100; D -> d
+U8 101; E -> e
+U8 102; F -> f
+U8 103; G -> g
+U8 104; H -> h
+U8 105; I -> i
+U8 106; J -> j
+U8 107; K -> k
+U8 108; L -> l
+U8 109; M -> m
+U8 110; N -> n
+U8 111; O -> o
+U8 112; P -> p
+U8 113; Q -> q
+U8 114; R -> r
+U8 115; S -> s
+U8 116; T -> t
+U8 117; U -> u
+U8 118; V -> v
+U8 119; W -> w
+U8 120; X -> x
+U8 121; Y -> y
+U8 122; Z -> z
+U8 123; [ -> {
+U8 124; \ -> |
+U8 125; ] -> }
+U8 125; ^ -> 6
+U8 45 ; _ -> -
+U8 126; ` -> ~
+U8 65 ; a -> A
+U8 66 ; b -> B
+U8 67 ; c -> C
+U8 68 ; d -> D
+U8 69 ; e -> E
+U8 70 ; f -> F
+U8 71 ; g -> G
+U8 72 ; h -> H
+U8 73 ; i -> I
+U8 74 ; j -> J
+U8 75 ; k -> K
+U8 76 ; l -> L
+U8 77 ; m -> M
+U8 78 ; n -> N
+U8 79 ; o -> O
+U8 80 ; p -> P
+U8 81 ; q -> Q
+U8 82 ; r -> R
+U8 83 ; s -> S
+U8 84 ; t -> T
+U8 85 ; u -> U
+U8 86 ; v -> V
+U8 87 ; w -> W
+U8 88 ; x -> X
+U8 89 ; y -> Y
+U8 90 ; z -> Z
+U8 91 ; { -> [
+U8 92 ; | -> \
+U8 93 ; } -> ]
+U8 96 ; ~ -> `

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/console.asm

@@ -0,0 +1,69 @@
+; Reads a line from the keyboard and fills the specified buffer with it
+; Does not support Shift or any other special keys
+; Arguments:
+; r1 - pointer to the buffer
+; Result:
+; r1 - pointer to the same buffer
+; Clobbers: r2, r3, r4, r5, r6, r7
+pub read_line:
+	mov r6, 1
+	lsl r6, r6, 16
+	sub r6, r6, 32 ; Calculating the address to the shift LUT
+	mov r2, 0 ; Storing the shift status here
+	mov r4, 0 ; Storing the last key here, so we don't repeat the same key
+	mov r3, r1 ; The pointer to after the last character
+
+	read_line_keyloop:
+		keyboard r5
+		
+		cmp r5, r4
+		je read_line_keyloop ; If the current key is same as previous, we loop
+		mov r4, r5 ; Storing current key as previous
+		
+		cmp r5, 0x120 ; Is the key renderable or special?
+		jb read_line_special ; If the key was special, we handle it separately
+		xor r5, r5, 0x100 ; Clearing the "down" bit
+
+		cmp r2, zr ; Checking for shift status
+		je read_line_store ; If shift is up, we skip conversion
+
+		;;; converting from shift-down to shift-up keys
+		add r7, r6, r5 ; Calculating the index of the shift conversion
+		load_8 r5, [r7] ; Loading the shifted value
+		;;;
+
+		read_line_store:
+			store_8 [r3], r5 ; Else, we store the key in the buffer
+			add r3, r3, 1 ; We advance forward
+			; TODO: Writeback
+			jmp read_line_keyloop
+
+		read_line_special:
+			cmp r5, 13 ; Was the key Backspace?
+			je read_line_backspace ; If yes we need to move one character back
+
+			cmp r5, 10 ; Was the key Enter?
+			je read_line_finished ; If so, we're finished
+
+			and r5, r5, 0x1FB ; Mask out the left/right shift direction bit
+			cmp r5, 0x110 ; Was the key Shift Down?
+			and flags, flags, 0x1 ; We care only about equality bit
+			or r2, r2, flags ; If shift was down before, it still is. If it was pressed now, it is down now
+
+			cmp r5, 0x010 ; Was the key Shift Up?
+			and flags, flags, 0x1 ; We care only about equality bit
+			xor flags, flags, 0x1 ; We invert it, i.e. "if it's not up"
+			and r2, r2, flags ; The shift can be kept down if it's not currently up
+
+			jmp read_line_keyloop ; If no special handling, we loop back
+
+		read_line_backspace:
+			cmp r3, r1 ; Compare the current pointer to start of buffer
+			je read_line_keyloop ; If we are at the start, we loop
+			sub r3, r3, 1 ; We move back one character
+			; TODO: Writeback
+			jmp read_line_keyloop
+
+	read_line_finished:
+		store_8 [r3], zr ; We store null at the end so the string is finished
+		jmp r13

src/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

src/stdlib.asm

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

stdlib.asm

@@ -1,25 +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

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.