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)

• official documentation
• wiki
• FAQ
• Emulated Systems Guide

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

• Official Forum
• bannister.org
• Twitter
• IRC

Unofficial

• MAMEworld
• Reddit

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

Compile options

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.