Guides:MAME - Troubleshooting
Troubleshooting MAME
MAME is a beast these days and when something doesn't work it can be difficult to know where to start, I am going to document some methods here, trying to help out on github issues. This is a teach a man to fish scenario.
Searching for Infomation
This will cover the simplest forms of finding information
Read the documentation
MAME provides documentation in the forms listed below (nb: see the Documentation menu on mamedev.org)
Check social media
Check your general social media platforms for solutions to issues, you may find both community knowledge and devs floating around these platforms (nb: see the Community menu on mamedev.org)
Official
Unofficial
MAMETesters
MAMETesters is used as a community bug reporting tool more-so aligned to testing and reporting on specific title performance. You may search freely but will need an account to submit
github issues
Start your search with the github issues list, it may have been solved in a later code change or simply be documented there
Basic Troubleshooting
Simple troubleshooting with any type of build, some of these may be obvious but we will document them anyway
One step at a time
Make small change(s) to help identify the change that influenced the fix, you can report on this and help MAME progress. If you jump forward and change a lot document what was changed then backtrack until you break it again to try and isolate the problem.
Run in verbose mode
Run mame in -verbose mode and review the output
-verbose
Test an older version
Download (or build) and older version of MAME and test your configuration, find a build that works and report that to the MAME team, this can help identify a subset of changes that may be to blame.
Clean installation
Run with a clean installation, move your $HOME/.mame folder and run mame without the influences of any pre-existing configuration to see if the problem persists
BGFX
If troubleshooting BGFX issues, try a different chain and backend, up to version 0.236 the vulkan backend has been particularly troublesome whereas the more mature opengl backend is OK
You can see the available chains under ./bgfx/chains/ they are json files and will be called on the cli without the .json extension
The cli options you will want are
-video bgfx -bgfx_backend (vulkan|opengl) -bgfx_chain <chain name>
Alternatively see the sliders menu on the ingame menu (default: tab) to change between chains
Further Troubleshooting
Compiling
Compile your own build, this will give you the control you need to start narrowing down when the issue first presented.
This is a large topic please see the official documentation
I currently compile with
-j12 STRIP_SYMBOLS=1 NOWERROR=1 CFLAGS='-U_FORTIFY_SOURCE' TOOLS=1 REGENIE=1
Option | Usage | Reference |
---|---|---|
j12 | Threaded compile, can use up to (n)+1 cores | - |
STRIP_SYMBOLS=1 | Do not include debugging symbols | - |
NOWERROR=1 | Disable Warnings as Errors | bannister.org |
CFLAGS='-U_FORTIFY_SOURCE' | This is a compiler flag that is required to work around particulars with gcc | bannister.org Jira |
TOOLS=1 | Build external tools (i.e. chdmam, floptool) | - |
REGENIE=1 | Regenerate settings for build | - |
Shaders
Compile the shaders, not all shaders are compiled at any time so if you are testing CRT simulation issues compile the latest shaders
make shaders
Debug Builds
Once you have learnt to compile your own builds, you can now have the opportunity of building a debug version, to build a debug version pass DEBUG=1 to your build flags
DEBUG=1 STRIP_SYMBOLS=0
When run you can enabled the debugger with -debug on the command line and if using an external debugging tool like gdb you should have useful output in your backtrace
External Tools =
- gdb
Timelines
Look at the release date of the version you have identified as problematic and/or the settings which cause the issue, take that release date and have a look at the changes to the source code around at this time, was there updates to the feature you are having issues with?
Review the source code
Pull down a copy of the source code and start to take a look over it, perhaps by now you have identified a particular file that was changed for a feature where you have identified a crash, perhaps you just have an error message.
grep the source code for the error, what does the code seem to do? Trace this back through files until you are either completely lost or find what you are looking for.
Final thoughts
Don't stress
The MAMEdev team know this source, you may not and it is a huge project to jump into. Raise an issue with your findings, a dev may make suggestions on where to look next or you may have managed to do 70% of the investigation for them, they do appreciate it.
Own your ignorance and ask for help, it is a learning opportunity that may have long term impact.