Generate profiling data

How to enable Simulant's profiler

Every Simulant application allows the user to change various settings exposed in the AppConfig struct.

In order to enable the profiler, the build needs to be run in DEBUG mode and the following lines should be added to int main():

#ifndef NDEBUG
       config.log_level = smlt::LOG_LEVEL_DEBUG;
       config.development.force_profiling = true;
#endif

How to generate the actual profiling data

Once the user decides to run the application via dcload-ip, e.g.:

sudo dc-tool -t 192.168.0.123 -x myCoolGame.elf -c ./assets

a file named gmon.out will be created in ./build/dreamcast-sh4-gcc/debug/assets

The file must not be opened while the application is running!

During the profiling process the terminal will display how many arcs haven been processed. The output will look like this:

-- 1000 arcs recorded...
-- 2000 arcs recorded...
-- 3000 arcs recorded...

Best profiling results can be achieved, if the amount of arcs reaches about 6000 - 7000 entries.

IMPORTANT: To flush the profiling data into gmon.out, the application needs to be properly terminated (e.g. ESC key). Shutting down the console or terminal prematurely will NOT WORK.

The profiling was successful, if the terminal displays something like this:

Stopping profiling...
-- Writing 6750 arcs
-- Profiler thread finished!

How to process the profiling data

The file gmon.out is encoded in a binary file format and needs to be converted into a text file.

Copy or move gmon.out into ./build/dreamcast-sh4-gcc/debug (debug directory)

If your game is named myCoolGame, you should also find these 2 files in the debug directory: myCoolGame.elf and myCoolGame.elf.debug

Open the terminal, navigate into the debug directory and execute the following line:

docker run -v `pwd`:`pwd`:Z kazade/dreamcast-sdk /bin/bash -c "source /etc/bash.bashrc; cd `pwd`; sh-elf-gprof myCoolGame.elf.debug gmon.out" > ~/Desktop/gprof.out

This will essentially convert the profiling data into a human readable file on your Desktop, which can be viewed with any text editing program.

Before moving/reading gprof.out though, the following line should be executed as a final step:

cat ~/Desktop/gprof.out | gprof2dot -n 0.001 | dot -Tsvg -o output.svg

A new file named output.svg will appear in the debug directory.

It will visualize the data contained in gprof.out as a graph, making it easier for the developer to understand relations between different areas of Simulant's engine code. It can be opened with e.g. GIMP or any modern Internet Browser.