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