Bug Reporting

Derek Bruening edited this page Nov 29, 2014 · 6 revisions

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.

Issue title

Please use one of these keywords as the first word in the title of an Issue involving a bug:

  • CRASH

    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_mask runtime option controls when livedumps are created. Run with -dumpcore_mask 0x8bff to ask for livedumps on common failures such as DynamoRIO crashes and client crashes. Compress the resulting <logdir>/<appname>.<pid>.00000000.ldmp file (it should shrink quite a bit) and attach to the Issue report.

  • APP CRASH

    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.

  • HANG

    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.

  • ASSERT

    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

Cross-references

The text #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
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.