Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
How to file an Issue
The Issue Tracker is not only how we record bugs but also how we drive our work and track our progress on features. The Issue Tracker is only as useful as the data that we enter into it, which means we need to have some conventions and rules on entering new Issues.
Please use one of these keywords as the first word in the title of an Issue involving a bug:
An internal crash in DynamoRIO. This is a bad thing. Record the exception address. If you were able to acquire the DynamoRIO file and line number (via tools/address_query.pl), include that as well.
If the bug may prove hard to reproduce for a developer, whether because it is non-deterministic or it involves an unusual application or libraries or platform, provide a "livedump". The
-dumpcore_maskruntime option controls when livedumps are created. Run with
-dumpcore_mask 0x8bffto ask for livedumps on common failures such as DynamoRIO crashes and client crashes. Compress the resulting
<logdir>/<appname>.<pid>.00000000.ldmpfile (it should shrink quite a bit) and attach to the Issue report.
An application crash. The application's behavior under DynamoRIO is different from its native behavior, but DynamoRIO itself did not crash. This may or may not be our fault, but all such cases should be reported and analyzed. This category includes the application crashing due to an unhandled exception as well as any strange behavior that does not occur natively. In your bug report, post any messages that the application gives you.
A deadlock or in some cases just a lot of lock contention that results in the process making little forward progress. For a hang we want two call stack dumps so we can tell if it is a deadlock or if in fact some progress is being made.
An internal debug check in DynamoRIO. This will only happen in a debug build. It is similar to a crash but occurs sooner and so is usually easier to debug. Include in the title the line number and at least part of the text of the assert.
After the keyword, include in parentheses the build or version number, the application name, and any non-default runtime options. After the parentheses include additional information. Here are some example titles:
CRASH (1.3.1 calc.exe) vm_area_add_fragment:vmareas.c(4466)
ASSERT (1.3.0 suite/tests/common/segfault) study_hashtable:fragment.c:1745 ASSERT_NOT_REACHED
#N will be auto-linked to Issue N.
Including code in issues
The text in an issue is interpreted as Markdown. To include any kind of raw output or code that contains Markdown symbols, place it between lines that consist solely of three backtics:
``` put code here ```
Attaching images or files to issues
Place the attachment on Google Drive or some other location and include a link to it in the issue text.
Describing a bug
The most basic information is the most critical:
What did you run? Which application, on which platform? When did the bug occur? On startup, or after a particular command given to the app?
What version of DynamoRIO are you using? If a custom version, please provide the symbols.
If any data files are needed to reproduce it, attach them, but first try to minimize the setup in which the bug happens (i.e., don't send a 1MB file if a 1KB one shows the same bug).
Is the error deterministic? If it happened in release build, what's the behavior in debug build?
Acquiring a crash dump on Windows
If your runtime options are not set up for an .ldmp, try to attach WinDbg and acquire a crash dump.
Run WinDbg and press
F6 to attach to the process (or start as "windbg -p pid").
Then create a dump file:
.dump /ma full-dumpfile.dmp