Reporting Problems


Many of the people in the gem5 community are happy to help when someone has a problem or something doesn’t work. However, please keep in mind those working on gem5 have other commitments, so we’d appreciate, prior to reporting, if users could put in some effort to solving their own problems, or, at least, gather enough information to help others resolve the issue.

Below we outline some general advise on issue reporting.

Prior to reporting a problem

The most important thing to do prior to reporting a problem is to investigate the issue as much as possible. This may lead you to a solution, or enable you to provide more information to the gem5 community regarding the problem. Below are a series of steps/checks we’d advise you carry out before reporting an issue:

  1. Please check if a similar question has already been asked on any of our channels (check the archives as well).

  2. Ensure you’re compiling and running the latest version of gem5. The issue may have already been resolved.

  3. Check changes currently under review on our GitHub system. It’s possible a fix to your issue is already on its way to being merged into the project.

  4. Make sure you’re running with gem5.opt or gem5.debug, not gem5.fast. The gem5.fast binary compiles out assertion checking for speed, so a problem that causes a crash or an error on gem5.fast may result in a more informative assertion failure with gem5.opt or gem5.debug.

  5. If it seems appropriate, enable some debug flags (e.g.,--debug-flags=Foo via the CLI). For more information on debug flags, please consult our debugging tutorial.

  6. Don’t be afraid to debug using GDB if your problem is occurring on the C++ side.

Reporting a problem

Once you believe you have gathered enough information about your problem. Then feel free to report it.

Solving the problem

If you have solved a problem that you reported, please let the community know about your solution as a follow-up on your GitHub issue or discussion. If you have fixed a bug, we’d appreciate if you could submit the fix to the gem5 source. Please see our beginners guide to contributing on how to do this.

If your issue is with the content of a gem5 document/tutorial being incorrect, then please consider submitting a change. Please consult our README for more information on how to make contributions to the gem5 website.