= RTEMS Bug Reporting =

[[TOC(Developer/Bug_Reporting, depth=2)]]

Our preferred way of receiving bug reports is via the [http://devel.rtems.org RTEMS Trac] ticket system. If you have patches not specifically related to bugs or existing tickets, we prefer to use the [wiki:TBR/Website/RTEMSMailingLists Developer's Mailing List].

When you have checked that your report meets the following criteria, please submit it according to the generic instructions in [#ReportingaBug Reporting a Bug].

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 compiler toolchain version used
 *  The options given when RTEMS was configured/built
 *  A description of the expected behaviour
 *  A description of actual undesired behaviour

Only when your bug report requires multiple source files to be reproduced should you use an archive otherwise the uploaded individual source file or diff should contain the minimal source code needed to reproduce the bug. In any case, make sure the above are included in the body of your bug report as plain text, even if needlessly duplicated as part of an archive. Please try and repeat on the current git master.

If you fail to supply enough information for a bug report to be reproduced, someone will probably ask you to post additional information. In this case, please post the additional information and not just to the person who requested it, unless explicitly told so.

== 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 any of the above.
 *  A code snippet that won't cause RTEMS to produce the exact output mentioned in the bug report.
 *  The location (URL) of the package that failed to build.
 *  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.
 *  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 behaviour of programming language constructs or calls to library routines that are not part of RTEMS.

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 recognise that sometimes a timing bug will exist in RTEMS but want you to exercise due diligence before pointing fingers.

== Not RTEMS Bugs ==

RTEMS users sometimes encounter that may be considered 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.

== Reporting a Bug ==

To submit a bug report please follow the instructions:
 
1. Sign in to the RTEMS Trac website using the [https://devel.rtems.org/login Trac Login].
1. Click in [https://devel.rtems.org/query View Tickets] (upper right corner of the screen).
1. Search for a similar ticket about the bug (to avoid duplicates).
1. If you haven't found a similar ticket, create a [https://devel.rtems.org/newticket New Ticket] and:
  a. Add a useful single line summary.
  a. Set the `Type` field to `defect` for a bug. Note `infra` is used to report issues with the RTEMS servers at OSUOSL.
  a. Set the `Version` field. If it is with the current git master branch use the next version
  a. Set the `Component` field and leave as `General` if you are not sure.
  a. Describe the bug or issue in the `Description` field with any details useful to the RTEMS maintainers such as host machine, build of tools, output traces, plus if you have any local modification and detailed instructions in order to reproduce the bug. The `WikiFormatting` is useful in formatting the information you provide and it does help the readability of the information you provide.
  a. Click `Create Ticket` when you are happy you have all the details you can provide.

The [wiki:TracWorkflow Trac Ticket Workflow] details the workflow for RTEMS Tickets.

Before you report a bug, please check the list of [#NotRTEMSBugs non-bugs] and 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.

== Managing Bugs ==

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 Trac.

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 Trac ticket:

* Remove the failure notation on the test-case.
* Attach your fix and test case to the Trac ticket.
* Close the ticket by adding `fixes #<ticket numer>` to the commit message.

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.

The state of a ticket is:

  '''open''':: The ticket has been filed and the responsible person(s) notified.
  '''accepted''':: The assigned 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.

The `resolve` action has the following:

  '''fixed''':: The bug has been fixed. 
  '''invalid''':: The bug report is not valid and nothing further will be done.
  '''wontfix''':: The bug will not be fixed.
  '''duplicate''':: The ticket is a duplicate of any other ticket and that ticket should be referenced in future.
  '''worksforme''':: The bug could not be repeated and there is not more the maintainer can do.

If a bug has been closed and you think there has been a mistake please reopen the ticket and add suitable comments to explain the reason for reopening the ticket.

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.

== Ticket Updates with Git Commits ==

Tickets can be automatically updated using a git commit message. If the commit contains `fixes #12345` the ticket ''12345'' will be closed and the commit message used a comment in the ticket. The valid keywords are:

  '''Close a ticket''':: `close` `closed` `closes` `fix` `fixed` `fixes` `Close` `Closes` `Closed` `Fix` `Fixed` `Fixes`

  '''Update a ticket''':: `addresses` `references` `refs` `see` `address` `update` `updates` `Refs` `See` `Address` `Update` `Updates`