From fab28ced0bb13cde2eb0d5727ee682dffccdfa5d Mon Sep 17 00:00:00 2001
From: John <j@soft.fish>
Date: Sat, 22 Jun 2024 09:05:52 -0500
Subject: [PATCH] Add readme.md

---
 readme.md | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)
 create mode 100644 readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..0c0a2f1
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,140 @@
+# Bweh-mulator
+
+A work-in-progress emulator for the venerable Game Boy.
+
+
+# Using the Debugger:
+
+The debugger accepts a variety of commands, which take a number of expression arguments:
+
+- `set dst, src`: Sets memory at `dst` to value(s) of `src` 
+- `get addr`: Hex-dumps memory (the default behavior.)
+- `run n`: Executes `n` instructions. Prints live disassembly for small values of `n`.
+- `break addr` | `br`: Sets a breakpoint at `addr`.
+- `unbreak addr` | `ub`: Unsets the breakpoint at `addr`.
+- `dis addr` | `di`: Disassembles bytes at `addr`.
+- `eval expr` | `=`: evaluates and prints an expression.
+- `regs`: Dumps CPU registers, including internal registers.
+- `cart`: Parses and prints cartridge header info.
+- `trace`: Toggles memory-write tracing mode.
+- `reset`: Resets the CPU, without clearing memory.
+
+## Operand Expressions:
+
+The debugger supports a variety of datatypes:
+- Integers: `100`, `0x100`, `0d256`, `0o400`, `0b100000000`
+  - All integers are base-16 by default
+- Booleans: `true`, `false`
+  - Not useful as operands, but can be negated/logically-operated
+- Registers: `a`, `f`, `b`, `c`, `d`, `e`, `h`, `l`, `af`, `bc`, `de`, `hl`, `pc`, `sp`
+- Exclusive Ranges: `a..b`, `a.b` (shorthand)
+- Arrays: `[10, 20]`
+  - Used for multiple-assignment
+
+The debugger supports a variety of arithmetic and logic operations:
+
+### Binary
+| Op  | Description            | Precedence |
+|-----|------------------------|------------|
+| `*` | Multiplication         | Term       |
+| `/` | Int Division           | Term       |
+| `%` | Remainder              | Term       |
+| `+` | Addition               | Factor     |
+| `-` | Subtraction            | Factor     |
+| `>>`| Shift Right            | Shift      |
+| `<<`| Shift Left             | Shift      |
+| `&` | Bitwise And            | Bit        |
+| `|` | Bitwise Or             | Bit        |
+| `^` | Bitwise Exclusive Or   | Bit        |
+| `.` | Exclusive Range        | Range      |
+
+
+### Unary Prefix
+
+| Op  | Description            | Precedence |
+|-----|------------------------|------------|
+| `*` | "Pointer" Dereference  | Sign       |
+| `-` | Signed Negation        | Sign       |
+| `!` | Bitwise Not            | Sign       |
+| `+` | accepted, but useless  | Sign       |
+
+### Other operations
+
+- `( )`: Parentheses (grouping)
+- `a[0]`: Array indexing
+  - Works on arrays, registers, and absolute addresses
+
+## Multiple Evaluation With Arrays and Ranges
+
+Arrays and ranges have a handful of special/unique behaviors when used as arguments to commands:
+
+### Writing Memory With Set:
+
+The `set` command takes any nested tree of arrays of ranges of locations and attempts to pair them up in one of eight multiple-assignment forms.
+
+#### Multiple Assignment
+- Assign arrays to arrays
+```
+gb> set [0, 2, 4, 6], [30, 32, 34, 36]
+gb> 0
+0000  30 00 32 00 34 00 36 00  00 00 00 00 00 00 00 00  |0.2.4.6.........|
+```
+- Assign arrays to ranges
+```
+gb> set 0..A, [39, 38, 37, 36, 35, 34, 33, 32, 31, 30]
+gb> 0
+0000  39 38 37 36 35 34 33 32  31 30 00 00 00 00 00 00  |9876543210......|
+```
+- Assign ranges to arrays
+```
+gb> set [6, 2, 5, 1, 7, 8, 3, 9, 4, 0], 30..3A
+gb> 0
+0000  39 33 31 36 38 32 30 34  35 37 00 00 00 00 00 00  |9316820457......|
+```
+- Assign ranges to ranges
+```
+gb> set 0..A, 41..51
+gb> 0
+0000  41 42 43 44 45 46 47 48  49 4a 00 00 00 00 00 00  |ABCDEFGHIJ......|
+```
+- Assign arrays to integers (and vice versa)
+```
+gb> set 0, [41, 41, 42, 42]
+gb> 0
+0000  41 41 42 42 00 00 00 00  00 00 00 00 00 00 00 00  |AABB............|
+gb> set [2, 4, 6, 8], 55
+gb> 0
+0000  41 41 55 42 55 00 55 00  55 00 00 00 00 00 00 00  |AAUBU.U.U.......|
+```
+- Assign ranges to integers (and vice versa)
+```
+gb> set 4, 30..38
+gb> 0
+0000  00 00 00 00 30 31 32 33  34 35 36 37 00 00 00 00  |....01234567....|
+gb> set[A..F], 41
+gb> 0
+0000  00 00 00 00 30 31 32 33  34 35 41 41 41 41 41 00  |....012345AAAAA.|
+```
+### Get and Dis:
+
+Get and Dis have specialized range forms, which restrict their output to the provided ranges:
+
+### Hex-dumping With Get:
+
+```
+gb> get 3..3a
+0003  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
+0013  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
+0023  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
+0033  00 00 00 00 00 00 00                              |.......|
+```
+
+### Disassembling with Dis:
+The disassembler will keep disassembling until it reaches an instruction outside the provided range
+```
+gb> pc
+0100  00 c3 13 02 ce ed 66 66  cc 0d 00 0b 03 73 00 83  |.Ã..ÎíffÌ....s..|
+gb> dis pc..pc+1
+0100: nop
+0101: jp        0213
+```