A CPU emulator for running unit tests on Game Boy code.

Evie M.

Last update: Jan 1, 2023

Related tags

Emulators evunit

Overview

evunit

This is a unit testing application for Game Boy roms. It includes a CPU emulator, and loads test configurations from TOML files.

Configuring a test

Within the test config you can create a heading for each test you want to run, and assign default and expected values for registers

[add-one]
b = 1
[add-one.result]
a = 2

[add-two]
b = 2
[add-two.result]
a = 3

The values you can initialize are:

a, b, c, d, e, h, l (8-bit registers)
bc, de, hl, pc, sp (16-bit registers)
z.f, z.n, z.h, z.c (Boolean flags)

You can assign an integer (or true/false for flags) to any of these (0x for hex), or a label if you have a symfile loaded. To determine which functions should run, you can assign a label to pc.

Sometimes you have configurations which should apply to all tests, like a global variable or the stack pointer. Any configurations at the top of the file (before a heading) are global and apply to all tests.

sp = "wStack.end"

[my-test]
pc = "MyTest"
a = 42
[my-test.result]
b = 42

If the test result is absent, the test will always pass unless it crashes.

Creating an exhaustive set of tests by hand might be tedious, so remember that you an always generate tests in a bash script or any other language of your choice.

for i in {0..7}
do
	echo "
[my-test$i]
pc = \"GetBitA\"
a = $i
[my-test$i.result]
a = $((1 << $i))
"
done
"

Then pipe this into evunit. Note that evunit does not currently support opening - as stdin, so /dev/stdin must be used instead. This is guaranteed to work without issues.

bash config.bash | evunit -c /dev/stdin bin/rom.gb

And you can always use cat to add a handwritten file into the mix.

bash config.bash | cat config.toml - | evunit -c /dev/stdin bin/rom.gb

Additional configuration options

In addition to registers, there are a few other options you can configure. All of these can be configured globally as well as per-test.

crash

Marks an address as a "crash", causing the test to fail if pc reaches it. This is useful for crash handler functions such as rst $38

crash = 0x38
crash = "crash"

enable-breakpoints

Enables or disables printing register info after executing ld b, b and ld d, d. Enabled by default. This configuration can only be used globally.

enable-breakpoints = true
enable-breakpoints = false

timeout

Sets the maximum number of cycles before a test fails. This is useful if you have code that tends to get stuck in infinite loops, or code which can take an extremely long time to complete. The default value is 65536.

timeout = 65536

Diagnosing failures

When a test fails, it outputs some cpu registers depending on the failure reason to help you diagnose the issue. However, sometimes you need to check the state of memory as well; this can be accomplished with the --dump-dir (-d) flag. Pass a directory to this flag and when any test fails a text dump of memory will be placed in the provided directory.

evunit -c fail.toml -d dump/ rom.gb

The dump is simply a giant list of bytes, with headers for each memory type:

[WRAM 0]
0xc000: 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0
0xc010: 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0
0xc020: 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0
0xc030: 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0
0xc040: 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0
0xc050: 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0
0xc060: 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0
...

Comments

Share ROM between tests

Currently, every test uses its own copy of the ROM (Vec<u8> in the AddressSpace); since ROM is immutable, it should be possible to instead take a &[u8] instead; this might conflict with #3, though, unless using something like scoped_thread.

opened by ISSOtm 6
Performance improvement

this branch will track whatever performance improvements I can come up with and depends on #14 . I will only add here changes that provably improve the performance in the tests available to me. I will also later add the tests in a separate branch, including the setup to check performance.

opened by DaKnig 4
Allow specifying (more) arbitrary termination conditions

Currently, the test requires PC = 0xFFFF to return (and this is enforced on ret by pushing that to the stack just prior). It would be useful to specify other stop location(s), to unit test inlined code as well.
enhancement

opened by ISSOtm 3
Explain how tests know when to end

If I initialize a test with pc = SomeRoutine, I would expect it to end when the routine returns. But there are more complex cases. What about testing a routine that calls other routines, where they may return? What about if SomeRoutine pops its return address off the stack and messes with it? Or if you start with call SomeRoutine / dw SomeData, and SomeRoutine pops its "return address" to use SomeData as an argument? Or if you're testing a whole ROM (so pc isn't initialized) and there may be interrupts?

opened by Rangi42 2
Documentation mistake with Boolean flags

The README claims you can use the values "z.f, z.n, z.h, z.c (Boolean flags)". I expect that should say "f.z, f.n, f.h, f.c (Boolean flags)".

opened by Rangi42 0
Add performance analysis tools

without them, we can speculate about performance all we want. adding flame graphs is the easy first step but it is not the whole solution. IMO we should also look at how the program behaves over time under heavy load.

opened by DaKnig 3
Allow setting and testing memory in config files

What is says on the tin. Suggested syntax: [8:addr], [16l:addr], [16b:addr] (specifying endianness). Larger sizes can be checked by composing, 16-bit is a convenience that cuts in half other "decompositions". (Endianness is too annoying to specify past 16-bit, too.)
enhancement

opened by ISSOtm 1
Big input files consume a lot of memory

Exhaustive testing will lead to big input files (obviously, due to combinatorial explosion), which currently makes evunit take a lot of memory (everything is read into memory before processing even begins.

It might be possible to use serde to generate a "streaming" deserializer, for example.
enhancement

opened by ISSOtm 0