RTEMSBugReporting
From RTEMSWiki
Our preferred way of receiving bugs is via the RTEMS Bugzilla bug reporting system.
Before you report a bug, please check the list of well-known bugs and, if possible in any way, try a current development snapshot. If you want to report a bug with older versions of RTEMS, we strongly recommend upgrading to the current release first.
Contents |
Summarized bug reporting instructions
After this summary, you'll find detailed bug reporting instructions, that explain how to obtain some of the information requested in this summary.
What we need
Please include in your bug report all of the following items:
- the exact version of RTEMS;
- the system type (CPU family, model, and BSP);
- the options given when RTEMS was configured/built;
- the undesired run-time behavior; and
- a complete description of the build problem or undesired run-time behavior.
What we do not want
- A source file that #includes header files that are left out of the bug report (see above)
- That source file and a collection of header files.
- An attached archive (tar, zip, shar, whatever) containing all (or some :-) of the above.
- A code snippet that won't cause RTEMS to produce the exact output mentioned in the bug report (e.g., a snippet with just a few lines around the one that apparently triggers the bug, with some pieces replaced with ellipses or comments for extra obfuscation :-)
- The location (URL) of the package that failed to build (we won't download it, anyway, since you've already given us what we need to duplicate the bug, haven't you? :-)
- E-mail messages that complement previous, incomplete bug reports. Post a new, self-contained, full bug report instead, if possible as a follow-up to the original bug report
- Assembly files (*.s) produced by the compiler, or any binary files, such as object files, executables, core files, or precompiled header files
- Duplicate bug reports, or reports of bugs already fixed in the development tree, especially those that have already been reported as fixed last week :-)
- Bugs in the assembler, the linker or the C library. These are separate projects, with separate mailing lists and different bug reporting procedures. The RTEMS Project is happy to work with you and those projects to resolve the problem but we must work with those projects.
- Bugs in releases or snapshots of RTEMS not issued by the RTEMS Project. Report them to whoever provided you with the release
- Questions about the correctness or the expected behavior of programming language constructs or calls to library routines that are not part of RTEMS. Ask them in forums dedicated to the discussion of the programming language or library
Developing and debugging real-time embedded systems can be difficult. Exercise caution in reporting an error that occurs only some of the times a certain program is executed, such that retrying a sufficient number of times results in a successful compilation; this is often a symptom of a hardware problem or application issue, not of a RTEMS bug (sorry). We do recognize that sometimes a timing bug will exist in RTEMS but want you to exercise due diligence before pointing fingers.
Where to post it
Please submit your bug report directly to the RTEMS Buzilla bug database.
The RTEMS lists have message size limits (100 kbytes) and bug reports over those limits will currently be bounced. If your bug is larger than that, please post it using the RTEMS Bugzilla bug database.
Detailed bug reporting instructions
In general, all the information we need can be obtained by collecting the command line below, as well as its output and the preprocessed file it generates.
Whether to use MIME attachments or uuencode is up to you. In any case, make sure the compiler command line, version and error output are in plain text, so that we don't have to decode the bug report in order to tell who should take care of it. A meaningful subject indicating language and platform also helps.
Please avoid posting an archive (.tar, .shar or .zip); we generally need just a single file to reproduce the bug (the .i/.ii preprocessed file), and, by storing it in an archive, you're just making our volunteers' jobs harder. Only when your bug report requires multiple source files to be reproduced should you use an archive. In any case, make sure the compiler version, error message, etc, are included in the body of your bug report as plain text, even if needlessly duplicated as part of an archive.
If you fail to supply enough information for a bug report to be reproduced, someone will probably ask you to post additional information (or just ignore your bug report, if they're in a bad day, so try to get it right on the first posting :-). In this case, please post the additional information to the bug reporting mailing list, not just to the person who requested it, unless explicitly told so. If possible, please include in this follow-up all the information you had supplied in the incomplete bug report (including the preprocessor output), so that the new bug report is self-contained.
Bug reports have to contain at least the following information in order to be useful:
- the exact version of RTEMS;
- the system type;
- the options when RTEMS was configured/built;
- the exact configure command used to configure RTEMS;
- a collection of source files for reproducing the bug, preferably a minimal set;
- a description of the expected behavior;
- a description of actual behavior.
When you have checked that your report meets these criteria, please submit it according to our generic instructions.
Frequently Reported Bugs in RTEMS
This section contains a description of things that RTEMS users encounter that may be consdered bugs in RTEMS but are not.
- The POSIX standard does NOT specify the default set of thread attributes. Thus when passing a NULL for attributes to pthread_create, the application is not guaranteed any particular thread behavior.
- The defaults for all RTEMS Configuration Table parameters are intentionally small. Thus it is common for RTEMS tasking and file related calls to return errors indicating out of resources until the configuration parameters are properly tuned for the application. For example, there are only 3 file descriptors available by default: stdin, stdout, and stderr. Any attempt to open a socket or file will fail unless more file descriptors are configured.
- When first developing a BSP, many users encounter an unexpected interrupt or exception immediately upon completion of RTEMS initialization. This occurs because interrupts are disabled during RTEMS initialization and are automatically initialized as part of switching to the first task. The interrupted user code will be in either _CPU_Context_switch or _Thread_Handler. This indicates that an interrupt source has not been properly initialized or masked.
- Some users encounter a random reset during BSP initialization. This usually indicates that the board has a watchdog timer that is not being properly serviced during the BSP initialization.
Managing Bugs (Bugzilla and the test-suite)
This section contains information mostly intended for RTEMS contributors. But if you submit a bug report, it is very important for you to submit a reproducible test case. These submitted test cases end up being added to the test suite to prevent future regressions.
If you find a bug, but you are not fixing it (yet):
- Create a (minimal) test-case.
- Add the test-case to our test-suite, documenting it as a current failure unless the bug is a regression.
- Add a bug report referencing the test-case to Bugzila.
If you want to provide additional information in the bug tracking system about a reported bug:
- If the bug has been tracked down to a specific area or routine in RTEMS, please provide information about its location.
- Minimize the test case.
- Try the test case with earlier and later versions of RTEMS to determine which versions it affects and whether it is a regression. If it is a regression, identify the patch that introduced it.
If you fix a bug for which there is already a Bugzila entry:
- Remove the failure notation on the test-case.
- Attach your fix and test case to the Bugzilla bug report.
- Close the bug report in Bugzila.
If you find a bug, and you are fixing it right then:
- Create a (minimal) test-case.
- Add the test-case to our test-suite, documenting it as known to work.
- Check in your fixes.
Maintainer's View of Fields
As a RTEMS-specific convention, we will attach a special meaning to some fields. The State field should be used in the following way:
- open - The PR has been filed and the responsible person(s) notified.
- analyzed - A maintainer has verified that this is indeed a bug in RTEMS. Every once in a while, old reports will need to be rechecked, to find out whether the bug still exists. At that time, an indication should be left in the report who tested the bug and when.
- feedback - The submitter was asked for further information, or asked to try out a patch. The PR remains in that state until the submitter responds.
- working - Someone is actively working on fixing the problem and has determined that it may take a while to fix. The intention of this state is to make sure that if someone is working on the problem, that everyone knows it so they can better coordinate efforts.
- suspended - Work on the problem has been postponed. This happens if a timely solution is not possible or is not cost-effective at the present time. The PR continues to exist, though a solution is not being actively sought. If the problem cannot be solved at all, it should be closed rather than suspended.
In addition, the high priority is reserved to maintainers in RTEMS, indicating that a certain problem must be solved before the next version of RTEMS is released.
Procedures and Policies
Bugs that are in state "feedback" because they lack information that is necessary for reproducing the problem can be closed if no response was received for three months.
Regressions should be explicitly marked as such. The synopsis line should read
[<branches-to-fix> regression] <rest-of-synopsis>
where <branches-to-fix> is the list of maintained branches (separated by slashes) that need fixing. A regression should start with priority "high" to bring it to attention. It may be downgraded later if a defect is not important enough to justify "high priority".
Bugs that refer to older releases or snapshots/CVS versions should be put into state "feedback", asking the reporter whether they can still reproduce the problem and to report their findings in any case (whether positive or negative).
- If the response is "works now", close the report,
- if the reponse is "still broken", change the state to "open", and
- if no response arrives, close the PR after three months.
