Website Summary Files Commits Branches @commit @diff @stats
path: root / assembler
diff options
context:
space:
mode:
Commitbb8c3f02d7c3c318e67575167886de1da123b95a (patch)
Author
 Syndamia <kamen@syndamia.com>
2025-02-16 13:33:56 +0200
Committer
 Syndamia <kamen@syndamia.com>
2025-02-16 13:33:56 +0200
Files1a8a914cedb85c9ee007cdd4e5d6a9dbf1b368ed /assembler
tonkobali-bb8c3f02d7c3c318e67575167886de1da123b95a.tar
tonkobali-bb8c3f02d7c3c318e67575167886de1da123b95a.tar.gz
tonkobali-bb8c3f02d7c3c318e67575167886de1da123b95a.zip
Parentba21ce6a6337d42f2359db6b0911d6eb1e74c094 (diff)
feat: Add rough documentation
1 files changed, 88 insertions, 0 deletions
-rw-r--r--assembler/README.md88
diff --git a/assembler/README.md b/assembler/README.md
new file mode 100644
index 0000000..0b148e5
--- /dev/null
+++ b/assembler/README.md
@@ -0,0 +1,88 @@
+# tonkobali assembler
+
+This is a very limited assembler.
+Since we support only a single instruction (SUBLEQ), the assembler can also take in "higher-level" instructions which are then simplified (an operation which I call in the codebase as "collapse") to SUBLEQ.
+
+The main goal is to use these higher-order instructions, not subleq itself.
+Look at the `examples` directory for examples.
+
+## Text format
+
+There are two types of lines in your source file: instruction calls and variable definitions.
+Blank lines are allowed.
+
+### Instruction calls
+
+```asm
+label: instruction arg1, arg2, ... ; Comment until the end of the line
+```
+
+Labels and comments are optional.
+A label is a name, refer to [names](#names) for allowed characters.
+
+You may separate a label and it's instruction by a newline and blank lines.
+You may issue multiple labels one after another, but **only** when separated by at least one newline (meaning you may not define two labels on the same line).
+
+Instruction must be separated from their first argument with a blank (space or tab).
+Capitalisation is **not** ignored.
+
+Arguments are [values](#values), with minor type limitations in certain higher-order instructions.
+They are seprated by commas with arbitrary amount of blank (space or tab) characters around the commas.
+All arguments must be on the same line as their instruction.
+
+### Variable definitions
+
+```asm
+name = value ; Comment until the end of the line
+```
+
+Comments are optional.
+
+### Names
+
+A name is a sequence of ASCII letters (capital and lowercase), numbers, underscore, dot, $ and ?.
+Capitalization is **not** ignored.
+
+There is no scoping of names, or in other words, every name is global.
+Labels are also names.
+
+Repeat names overwrite previous ones **globally**, meaning no matter where two definitions are, the second will override the first everywhere in your program.
+
+### Values
+
+All values are reduced to addresses in the memory (after all, all SUBLEQ arguments are addresses).
+We distinguish between three "types" of values:
+
+- Absolute addresses, these are addresses in the memory and are passed down as-is
+
+ They are defined as unsigned numbers, prepended with the `%` symbol.
+ For example: `%384`.
+
+- Number constants, they're placed somewhere in memory and their address is passed
+
+ They are signed 64-bit numbers (as is the Word type for our VM).
+ For example: `56`, `-912`.
+
+- Strings, they're converted into a sequence of numbers, each being the decimal ASCII representation of the character, ending with a zero. The address of the first "ltter" is passed
+
+ They are a sequence of characters, surrounded by double quotes.
+ Double quotes and backwards slash can be escaped by prepending a backwards slash.
+ For example: `"Hello World"`, `"He said \"Wow\""`, `"C:\\System"`.
+
+## Higher-order instructions
+
+| Instruction | Description | Argument 1 | Argument 2 |
+| ----------- | ------------------------------------------------------------------------- | ------------------- | ------------------- |
+| jmp | Jump to address | Location to jump to | |
+| inc | Increment value | Location of value | |
+| dec | Decrement value | Location of value | |
+| add | Add the first value to the second and store the result in the second | First value | Second value |
+| sub | Subtract the first value to the second and store the result in the second | First value | Second value |
+| mov | Move (copy) the value from the first address to the second address | First location | Second location |
+| beq | Branch if first value is equal to zero | Value to check | Location to jump to |
+| jsr | Jump to subroutine | Location to jump to | |
+| rts | Return from subroutine | | |
+
+The idea of subroutines is that jumping to one is the same as normal jump, however the address after the jump is stored.
+So, returning from a subroutine allows you to jump back after the location you entered the subroutine from.
+Addresses are stored in the memory via a "stack", in the first 1024 addresses.