diff --git a/user/index.rst b/user/index.rst index 6491c6c..eff85f3 100644 --- a/user/index.rst +++ b/user/index.rst @@ -16,7 +16,8 @@ RTEMS User Manual (|version|). | |copy| 2017 Tanu Hari Dixit | |copy| 2016, 2019 embedded brains GmbH | |copy| 2016, 2019 Sebastian Huber - | |copy| 2012, 2019 Chris Johns + | |copy| 2012, 2019 Chris Johns + | |copy| 2012 Gedare Bloom | |copy| 1988, 2018 On-Line Applications Research Corporation (OAR) .. include:: ../common/license.rst diff --git a/user/support/bugs.rst b/user/support/bugs.rst index 1ad1b5f..290f317 100644 --- a/user/support/bugs.rst +++ b/user/support/bugs.rst @@ -2,21 +2,188 @@ .. Copyright (C) 2019 embedded brains GmbH .. Copyright (C) 2019 Sebastian Huber -.. Copyright (C) 2016 Chris Johns +.. Copyright (C) 2015 Chris Johns +.. Copyright (C) 2012 Gedare Bloom .. index:: bugs .. index:: reporting bugs -Bugs -**** +Report Bugs +*********** -The bug tracker can be found at the :r:url:`bugs`. +The RTEMS Project uses a ticket system to deal with bugs, organize enhancement +requests, and manage small tasks and projects. You can `submit a bug report +`_ to the RTEMS Project ticket system. +Before you do this, please read the following information. Good bug reports +are more likely to get addressed quickly. If you have patches not specifically +related to bugs or existing tickets, please have a look at the +:ref:`Contributing` guidelines. -See the `Submission Guidelines `_ for -details on submitting a ticket. +Search for Existing Bugs +======================== -Be sure to do a cursory search for any tickets that may be relevant to your -problem. +You can `search for existing bugs `_ in the +RTEMS Project ticket system. Please try to avoid duplicate bug reports and +search for an existing bug before you report a new bug. If you are unsure, +please ask on the :r:list:`users` and we will help you sort it out. -If you are unsure about your issue status submit a ticket and we will help you -sort it out. +Not RTEMS Bugs +============== + +Some issues appear to be an RTEMS bug to you, but are actually the intended +behaviour or in the scope of other projects. + +* Bugs in the assembler, the linker, or the C library (Newlib) are not RTEMS + bugs. 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 those products must be addressed in the corresponding project. Report + `assembler, linker, and GDB bugs to sourceware.org `_, + `compiler bugs to GCC `_, and + `Newlib bugs to the Newlib mailing list `_. + If the bug was fixed, then you can update the :ref:`RSB` to pick up the fix. + +* Questions about the correctness or the expected behaviour of programming + language constructs or calls to library routines that are not part of RTEMS + belong somewhere else. + +* 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 behaviour. + +* The defaults for all + `RTEMS Application Configuration `_ + 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 three 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. + +* Bugs in releases or snapshots of RTEMS not issued by the RTEMS Project. + Report them to whoever provided you with the release. + +Good Bug Reports +================ + +Please open the page to `submit a bug `_ to +the RTEMS Project ticket system and follow the guidelines below to write a good +bug report. + +* Provide a useful single line summary. + +* Use `WikiFormatting `_ to + structure the information you provide. It does help the readability of the + information you provide. + +* Add a description of the expected behaviour. The expected behaviour may be + obvious to you, but maybe not to someone else reading the bug report. + +* Add a description of the actual undesired behaviour. + +* Name the :ref:`target hardware ` (processor architecture, chip family + or model, and :ref:`BSP `) in the description. + +* Add the toolchain version used (GCC, Binutils, Newlib) to the description. + Custom toolchain builds are discouraged. To avoid problems caused by custom + builds of the toolchain, please build your toolchain with the :ref:`RSB`. If + you use a custom build of the toolchain, then try to reproduce the bug first + using a toolchain built by the RSB. + +* Provide the configuration options used to build the RTEMS BSP in the + description. This helps to reproduce the issue. + +* Make the bug reproducible by others. Write a self-contained piece of source + code which can be compiled and reproduces the bug. Avoid adding assembly + files (\*.s) produced by the compiler, or any binary files, such as object + files, executables, core files, or precompiled header files. If it is + difficult or time consuming to reproduce the bug, then it may not get the + attention it deserves from others. 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 we want you to exercise due diligence before pointing fingers. + +* Only when your bug report requires multiple source files to be reproduced + should you attach 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 to reproduce the bug on the current Git master. If it is not + reproducible on the Git master, you should figure out if the bug was already + fixed. You can search the existing bugs once again, ask on the + :r:list:`users`, or do a Git bisect to find a commit which fixed the bug. + +* Include only information relevant to the bug. + +* Write separate bug reports for different bugs. + +* Select a *Type* for the ticket. Use ``defect`` for a bug. Note ``infra`` is + used to report issues with the RTEMS servers at OSUOSL. + +* Select a *Version* for the ticket. This should be the first RTEMS version + which is affected by this bug. If this is the current Git master branch use + the version of the next release. Please provide the exact version of RTEMS + in the description. If you use an RTEMS release, then the release number. + If you use a Git clone, then the commit hash. The commit hash should be + present in an RTEMS Project repository. Commit hashes of private branches + are not interesting. + +* Select a *Component* for the ticket. Use ``unspecified`` if you are unsure. + +* Select a *Severity* for the ticket. + +* The fields *Milestone* and *Priority* will be most likely set by an RTEMS + maintainer. + +* You can relate your new bug to existing bugs through the *Blocked by* and + *Blocking* fields. + +When you have checked that your report meets the criteria for a good bug +report, please click on the ``Create ticket`` button to submit it to the RTEMS +Project ticket system. + +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. + +Nobody Fixes my Bug +=================== + +Sometimes, you may notice that after some time your bug report gets no +attention and the bug is not magically fixed. This may have several reasons + +* the bug report is incomplete or confusing, + +* the target hardware is not available to others, + +* the bug is not reproducible on the Git master, + +* the bug is not reproducible at all, + +* the RTEMS version is quite old and no longer used by RTEMS maintainers, + +* fixing the bug has a low priority for others. + +Please note that you do not have a service contract with the RTEMS Project. +The RTEMS Project is run by volunteers and persons who take care about how +RTEMS performs in their application domain. If your bug does not affect the +interest of someone else, then you should try to fix the bug on your own, see +the :ref:`Contributing` guidelines. To change the priorities of others with +respect to your bug, you may refer to the :ref:`SupportCommercial`. diff --git a/user/support/contrib.rst b/user/support/contrib.rst index 11c6350..29c554d 100644 --- a/user/support/contrib.rst +++ b/user/support/contrib.rst @@ -6,6 +6,8 @@ .. index:: community; developers +.. _Contributing: + Contributing ************ diff --git a/user/support/support-commercial.rst b/user/support/support-commercial.rst index d3aebaa..665426b 100644 --- a/user/support/support-commercial.rst +++ b/user/support/support-commercial.rst @@ -4,6 +4,8 @@ .. index:: support; commercial +.. _SupportCommercial: + Commercial Support Services ***************************