From 2d90b4a97673d2900d18b76aeec4fec27a37e5e1 Mon Sep 17 00:00:00 2001
From: Ian Moffett <ian@osmora.org>
Date: Sat, 27 Jul 2024 16:08:58 -0400
Subject: Initial commit

Signed-off-by: Ian Moffett <ian@osmora.org>
---
 README.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0985312
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+OSMX64 is a 64-bit multi-core SoC architecture designed to be fast, efficient, and low-cost.
+
+## Registers
+
+Registers store data which can be accessed at any time. These include special registers for
+
+| Name       | Size     | Purpose                             |
+| ---------- | -------- | ----------------------------------- |
+| `x0`       | 64 bits  | Read-only, always `0`               |
+| `x1`-`x15` | 64 bits  | General purpose, read-write         |
+| `f0`-`f7`  | 32 bits  | IEEE 754 single-precision number    |
+| `d0`-`d7`  | 64 bits  | IEEE 754 double-precision number    |
+| `v0`-`v7`  | 512 bits | SIMD vector data                    |
+| `pc`       | 64 bits  | Program counter, `0` on startup     |
+| `sp`       | 64 bits  | Stack pointer                       |
+| `fp`       | 64 bits  | Frame pointer                       |
+| `ptp`      | 64 bits  | Page tree pointer                   |
+
+### Internal Registers
+
+Only accessed by the CPU for certain instructions. Cannot be directly read/written.
+
+| Name  | Size    | Purpose                     |
+| ----- | ------- | --------------------------- |
+| `rp`  | 64 bits | Return pointer for branches |
+| `ins` | 64 bits | Current instruction at `pc` |
+
+## Instructions
+
+### Bitwise Instructions
+
+Bitwise logic operations can write to all registers except `v0`-`v7` and `pc`. Can read from all registers except `v0`-`v7`.
+
+| Mnemonic                     | Effect                 |
+| ---------------------------- | ---------------------- |
+| `mov` dst: r/m, src: r/m/imm | `dst` = `src`          |
+| `and` dst: r/m, val: r/m/imm | `dst` = `dst` & `val`  |
+| `or` dst: r/m, val: r/m/imm  | `dst` = `dst` \| `val` |
+| `xor` dst: r/m, val: r/m/imm | `dst` = `dst` ^ `val`  |
+
+#### Example
+```
+/* Set x1 to 5 */
+mov x1, 5
+/* Ands x1 (which equals 5) with 1 */
+and x1, 1
+/* x1 now equals 1 */
+```
+
+### Arithmetic Instructions
+
+Arithmetic operations can write to all registers except `v0`-`v7` and `pc`. Can read from all registers except `v0`-`v7`.
+
+| Mnemonic                     | Effect                |
+| ---------------------------- | --------------------- |
+| `add` dst: r/m, val: r/m/imm | `dst` = `dst` + `val` |
+| `sub` dst: r/m, val: r/m/imm | `dst` = `dst` - `val` |
+| `mul` dst: r/m, val: r/m/imm | `dst` = `dst` * `val` |
+| `div` dst: r/m, val: r/m/imm | `dst` = `dst` / `val` |
+| `inc` dst: r/m               | `dst` = `dst` + `1`   |
+| `dec` dst: r/m                | `dst` = `dst` - `1`   |
+
+#### Example
+```
+/* Set x1 to 5 */
+cpy x1, 5
+/* Increment x1 */
+inc x1
+/* x1 now equals 6 */
+```
+
+### Control Flow Instructions
+
+Control flow instructions are used to control which instructions the CPU executes, allowing for the concept of procedures and conditional execution.
+
+| Mnemonic                               | Effect                                          |
+| -------------------------------------- | ----------------------------------------------- |
+| `hlt`                                  | Execution halted                                |
+| `br` dst: r/m/imm                      | `pc` = `dst`                                    |
+| `brl` dst: r/m/imm                     | `rp` = `pc` + size of opcode, then `pc` = `dst` |
+| `bret`                                 | `pc` = `rp`                                     |
+| `beq` a: r/m, b: r/m/imm, dst: r/m/imm | Iff `a` = `b`, `pc` = `dst`                     |
+| `bne` a: r/m, b: r/m/imm, dst: r/m/imm | Iff `a` != `b`, `pc` = `dst`                    |
+| `blt` a: r/m, b: r/m/imm, dst: r/m/imm | Iff `a` < `b`, `pc` = `dst`                     |
+| `bgt` a: r/m, b: r/m/imm, dst: r/m/imm | Iff `a` > `b`, `pc` = `dst`                     |
+| `ble` a: r/m, b: r/m/imm, dst: r/m/imm | Iff `a` <= `b`, `pc` = `dst`                    |
+| `bge` a: r/m, b: r/m/imm, dst: r/m/imm | Iff `a` >= `b`, `pc` = `dst`                    |
+
+#### Example
+```
+/* Subtract x2 from x1 */
+sub x1, x2
+beq x1, 0, zero
+cpy x1, 2
+zero:
+cpy x1, 3
+/* Iff x1 - x2 = 0, x1 equals 3 */
+/* Iff x1 - x1 != 0, x1 equals 2 */
-- 
cgit v1.2.3