Bweh/readme.md

# 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
```