141 lines
4.5 KiB
Markdown
141 lines
4.5 KiB
Markdown
# 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
|
|
```
|