Profiling with Lemur

Lemur comes with a profiler. Profiling can show you what code your game is running when, and help you find which parts of the game are slowest. It's a useful tool if you're making games that push the Virtual Boy to its limits.

Setup

To give you the most insight into your code, Lemur reads all information it can from the game file. The more information in the game file, the better your debugging experience will be.

Worst: ROM file (.vb extension): the profile will only include raw addresses. This is very difficult to debug with, and you are better off using...
Better: ELF file (.elf extension, possibly no extension): the profile will include function names. This is much easier to read, but won't tell you as much as...
Best: ELF file with debug info: the profile will include inlined functions as well. This gives you the most information possible.

Note: the current version of VUEngine Studio deletes ELF files after builds unless you modify the makefile. The next VUEngine Studio version will (probably) not do this.

Compiling with debug info

To get the most useful profiles, your game's .elf file should include debug info. To do this, simply add -g to your CFLAGS.

The -g flag is supported in

v810-gcc v4.9.4
v810-llvm

Note that VUEngine Studio uses an older version of v810-gcc, so inlined functions won't appear in profiles for VUEngine games. This will be fixed Eventually™️.

This debug info will be added to your game's .elf file, but stripped from the final .vb file. This means compiling with -g won't make your ROM bigger or slower.

Enable the profiler

To start the profiler, go to "Tools > Profiler". Make sure the "Enable profiling" box is checked. You can also pass --profile on the command line, to enable the profiler when the emulator starts. Note that when you first enable profiling, your game will restart.

Note that just because the profiler is enabled doesn't mean it's recording. You can begin recording any time, but the profiler must be enabled first.

Profiling

You can begin recording a performance profile by clicking the "Record" button. While recording, you can press "Finish recording" to save that profile to a file, or "Cancel recording" to discard it.

Profiles are best viewed in https://profiler.firefox.com/. You can read how to use this profiler at https://profiler.firefox.com/docs/#/./guide-ui-tour-timeline.

An example profile can be found at https://share.firefox.dev/4mILw5X.

Custom markers

You can define your own markers to include in the profile. This can be useful for e.g. defining "Drawing finished" or "Character data loaded" events.

To emit a marker, write the address of a (null-terminated) string to the address 0x02000038.

volatile char* const MARKER = (char*) 0x02000038;

void emitPerformanceMarker(const char *name) {
    *MARKER = name
}

/* Later, after your drawing code... */
emitPerformanceMarker("Drawing finished");