Generate profiling data: Difference between revisions
(Created page with "== How to enable Simulant's profiler == Every Simulant application allows the user to change various parameters in the AppConfig struct. In order to enable the profiler, the...") |
No edit summary |
||
| Line 1: | Line 1: | ||
== How to enable Simulant's profiler == | == How to enable Simulant's profiler == | ||
Every Simulant application allows the user to change various | Every Simulant application allows the user to change various settings exposed in the AppConfig struct. | ||
In order to enable the profiler, the following lines should be added to | |||
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() | int main() | ||
| Line 16: | Line 17: | ||
a file named '''gmon.out''' will be created in '''./build/dreamcast-sh4-gcc/debug/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! | '''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: | During the profiling process the terminal will display how many arcs haven been processed. The output will look like this: | ||
| Line 32: | Line 33: | ||
-- Writing 6750 arcs | -- Writing 6750 arcs | ||
-- Profiler thread finished! | -- 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. | |||
Revision as of 12:58, 30 May 2020
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.