Update Profiler

Profiler.md

@@ -1,2 +1,52 @@
-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.
+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.
+
+### 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](https://github.com/jbrandwood/v810-gcc) v4.9.4
+* [v810-llvm](https://github.com/SupernaviX/v810-llvm/releases)
+
+Note that VUEngine Studio uses an older version of v810-gcc, so source-level debugging doesn't work 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](https://profiler.firefox.com/docs/#/./guide-profiler-fundamentals?id=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`.
+
+```c
+volatile char* const MARKER = (char*) 0x02000038;
+
+void emitPerformanceMarker(const char *name) {
+    *MARKER = name
+}
+
+/* Later, after your drawing code... */
+emitPerformanceMarker("Drawing finished");
+```