From 8004bc7675d38dc4648d3c1619d1a5736a336229 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Wed, 21 Nov 2018 10:39:04 -0600 Subject: Initial start of converting the Word outline to Rest Thanks to Scott Zemerick for the analysis and ideas that led to this. --- software-engineering-handbook/README | 7 +++ .../RTEMS-Engineering-Standards-v3.docx | Bin 0 -> 32450 bytes .../change-management.rst | 14 +++++ software-engineering-handbook/coding-standards.rst | 11 ++++ software-engineering-handbook/conf.py | 14 +++++ software-engineering-handbook/index.rst | 56 +++++++++++++++++ software-engineering-handbook/issue-tracking.rst | 18 ++++++ software-engineering-handbook/preface.rst | 26 ++++++++ software-engineering-handbook/prequalification.rst | 68 +++++++++++++++++++++ .../software-development-git-users.rst | 11 ++++ .../software-development-management.rst | 22 +++++++ software-engineering-handbook/stakeholders.rst | 15 +++++ software-engineering-handbook/wscript | 11 ++++ wscript | 1 + 14 files changed, 274 insertions(+) create mode 100644 software-engineering-handbook/README create mode 100755 software-engineering-handbook/RTEMS-Engineering-Standards-v3.docx create mode 100644 software-engineering-handbook/change-management.rst create mode 100644 software-engineering-handbook/coding-standards.rst create mode 100644 software-engineering-handbook/conf.py create mode 100644 software-engineering-handbook/index.rst create mode 100644 software-engineering-handbook/issue-tracking.rst create mode 100644 software-engineering-handbook/preface.rst create mode 100644 software-engineering-handbook/prequalification.rst create mode 100644 software-engineering-handbook/software-development-git-users.rst create mode 100644 software-engineering-handbook/software-development-management.rst create mode 100644 software-engineering-handbook/stakeholders.rst create mode 100644 software-engineering-handbook/wscript diff --git a/software-engineering-handbook/README b/software-engineering-handbook/README new file mode 100644 index 0000000..5897350 --- /dev/null +++ b/software-engineering-handbook/README @@ -0,0 +1,7 @@ +This is a work in process. The initial parts of +RTEMS-Engineering-Standards-v3.docx have been converted to Rest. The +remaining sections need to be converted. And as marked, there are +sections where content from the Wiki needs to be converted to Rest +and included directly here. + +--joel diff --git a/software-engineering-handbook/RTEMS-Engineering-Standards-v3.docx b/software-engineering-handbook/RTEMS-Engineering-Standards-v3.docx new file mode 100755 index 0000000..7fbfb9e Binary files /dev/null and b/software-engineering-handbook/RTEMS-Engineering-Standards-v3.docx differ diff --git a/software-engineering-handbook/change-management.rst b/software-engineering-handbook/change-management.rst new file mode 100644 index 0000000..ff04675 --- /dev/null +++ b/software-engineering-handbook/change-management.rst @@ -0,0 +1,14 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Change Manaegment +***************** + +Major decisions about RTEMS are made by the core developers in concert +with the user community, guided by the Mission Statement. We provide +access to our development sources via a Git Repository (see these +Instructions for details). + +TBD - ??? diff --git a/software-engineering-handbook/coding-standards.rst b/software-engineering-handbook/coding-standards.rst new file mode 100644 index 0000000..0af9c78 --- /dev/null +++ b/software-engineering-handbook/coding-standards.rst @@ -0,0 +1,11 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Coding Standards +**************** + +TBD - Convert the following to Rest and insert into this file +TBD - https://devel.rtems.org/wiki/Developer/Coding/Conventions +TBD - https://devel.rtems.org/wiki/Developer/Coding diff --git a/software-engineering-handbook/conf.py b/software-engineering-handbook/conf.py new file mode 100644 index 0000000..a4da3ff --- /dev/null +++ b/software-engineering-handbook/conf.py @@ -0,0 +1,14 @@ +import sys, os +sys.path.append(os.path.abspath('../common/')) + +from conf import * + +project = "RTEMS Software Engineering Handbook" + +latex_documents = [ + ('index', + 'software-engineering-handbook.tex', + u'RTEMS Software Engineering Handbook', + u'RTEMS Documentation Project', + 'manual'), +] diff --git a/software-engineering-handbook/index.rst b/software-engineering-handbook/index.rst new file mode 100644 index 0000000..224e46a --- /dev/null +++ b/software-engineering-handbook/index.rst @@ -0,0 +1,56 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: COPYRIGHT (c) 2016-2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +================================================ +RTEMS Software Engineering Handbook (|version|). +================================================ + + | **COPYRIGHT (c) 1988 - 2015.** + | **On-Line Applications Research Corporation (OAR).** + | **COPYRIGHT (c) 2016-2018.** + | **RTEMS Foundation, The RTEMS Documentation Project** + + | **License:** + | Creative Commons Attribution-ShareAlike 4.0 International Public License + | https://creativecommons.org/licenses/by-sa/4.0/legalcode + +The authors have used their best efforts in preparing this material. These +efforts include the development, research, and testing of the theories and +programs to determine their effectiveness. No warranty of any kind, expressed +or implied, with regard to the software or the material contained in this +document is provided. No liability arising out of the application or use of +any product described in this document is assumed. The authors reserve the +right to revise this material and to make changes from time to time in the +content hereof without obligation to notify anyone of such revision or changes. + +The RTEMS Project is hosted at http://www.rtems.org/. Any inquiries concerning +RTEMS, its related support components, or its documentation should be directed +to the Community Project hosted at http://www.rtems.org/. + +.. topic:: RTEMS Online Resources + + ================ ============================= + Home https://www.rtems.org/ + Developers https://devel.rtems.org/ + Documentation https://docs.rtems.org/ + Bug Reporting https://devel.rtems.org/query + Mailing Lists https://lists.rtems.org/ + Git Repositories https://git.rtems.org/ + ================ ============================= + +.. toctree:: + :maxdepth: 4 + :numbered: + + preface + prequalification + stakeholders + software-development-management + function_and_variable + concept + +* :ref:`genindex` diff --git a/software-engineering-handbook/issue-tracking.rst b/software-engineering-handbook/issue-tracking.rst new file mode 100644 index 0000000..47ec03a --- /dev/null +++ b/software-engineering-handbook/issue-tracking.rst @@ -0,0 +1,18 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Issue Tracking +************** + +This section discussions Trac usage and tickets. + +Related URLs to review for conversion to this document + +https://devel.rtems.org/wiki/NewTicket +https://devel.rtems.org/wiki/Developer/Bug_Reporting + +Querying existing tickets (keep as a link) + +https://devel.rtems.org/query diff --git a/software-engineering-handbook/preface.rst b/software-engineering-handbook/preface.rst new file mode 100644 index 0000000..81b16df --- /dev/null +++ b/software-engineering-handbook/preface.rst @@ -0,0 +1,26 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Preface +******* + +The Real Time Executive for Multiprocessor Systems (RTEMS) operating +systems is a layered system with each of the public APIs implemented in +terms of a common foundation layer called the SuperCore. RTEMS provides +full capabilities for management of tasks, interrupts time, and multiple +processors in addition to those features typical of generic operating +systems. RTEMS has been implemented in both the Ada and C programming +languages. + +.. topic: RTEMS Mission Statement + + RTEMS development aims to provide a free deterministic real-time operating + system targeted towards deeply embedded systems which is competitive + with closed source products. The RTEMS project encourages the support + and use of standard APIs in order to promote application portability + and ease porting other packages to the RTEMS environment. Source: + https://devel.rtems.org/wiki/Mission_Statement + +The RTEMS development effort uses an open development environment in which all users collaborate to improve RTEMS. The RTEMS cross development toolset is based upon the free GNU tools and the open source C Library newlib. RTEMS supports many host platforms and target architectures. diff --git a/software-engineering-handbook/prequalification.rst b/software-engineering-handbook/prequalification.rst new file mode 100644 index 0000000..5234dbf --- /dev/null +++ b/software-engineering-handbook/prequalification.rst @@ -0,0 +1,68 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: COPYRIGHT (c) 2016-2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Introduction to Pre-Qualification +********************************* + +RTEMS has a long history of being used to support critical +applications. In some of these application domains, there are standards +(e.g., DO-178C, NPR 7150.2) which define the expectations for the +processes used to develop software and the associated artifacts. These +standards typically do not specify software functionality but address +topics like requirements definition, traceability, having a documented +change process, coding style, testing requirements, and a user’s +manual. During system test, these standards call for a review – usually +by an independent entity – that the standard has been adhered too. These +reviews cover a broad variety of topics and activities, but the process +is generally referred to as qualification, verification, or auditing +against the specific standard in use. The RTEMS Project will use the +term “qualification” independent of the standard. + +The goal of the RTEMS Qualification Project is to make RTEMS easier +to review regardless of the standard chosen. Quite specifically, +the RTEMS Qualification effort will NOT produce a directly qualified +product or artifacts in the format dictated by a specific organization +or standard. The goal is to make RTEMS itself, documentation, testing +infrastructure, etc. more closely align with the information requirements +of these high integrity qualification standards. In addition to improving +the items that a mature, high quality open source project will have, +there are additional artifacts needed for a qualification effort that +no known open source project possesses. Specifically, requirements and +the associated traceability to source code, tests, and documentation +are needed. + +The RTEMS Qualification Project is technically +“pre-qualification”. True qualification must be performed on the +project’s target hardware in a system context. The FAA has provided +guidance for Reusable Software Components (FAA-AC20-148) and this +effort should follow that guidance. The open RTEMS Project, with the +assistance of domain experts, will possess and maintain the master +technical information needed in a qualification effort. Consultants +will provide the services required to tailor the master information, +perform testing on specific system hardware, and to guide end users in +using the master technical data in the context of a particular standard. + +The RTEMS Qualification Project will broadly address two areas. The first area is suggesting areas of improvement for automated project infrastructure and the master technical data that has traditionally been provided by the RTEMS Project. For example, the RTEMS Qualification could suggest specific improvements to code coverage reports. The teams focused on qualification should be able to provide resources for improving the automated project infrastructure and master technical data for RTEMS. The term “resources” is often used by open source projects to refer to volunteer code contributions or funding. Although code contributions in this area are important and always welcome, funding is also important. At a minimum, ongoing funding is needed for maintenance and upgrades of the RTEMS Project server infrastructure, addition of services to those servers, and core contributors to review submissions + +The second area is the creation and maintenance of master technical +data that has traditionally not been owned or maintained by the RTEMS +Project. The most obvious example of this is a requirements set with +proper infrastructure for tracing requirements through code to test +and documentation. It is expected that these will be maintained by the +RTEMS Qualification Project. They will be evaluated for adoption by +the main RTEMS Project but the additional maintenance burden imposed +will be a strong factor in this consideration. It behooves the RTEMS +Qualification Project to limit dependence on manual checks and ensure +that automation and ongoing support for that automation is contributed +to the RTEMS Project. + +It is expected that the RTEMS Qualification Project will create and +maintain maps from the RTEMS master technical data to the various +qualification standards. It will maintain “scorecards” which +identify how the RTEMS Project is currently doing when reviewed per each +standard. These will be maintained in the open as community resources +which will guide the community in improving its infrastructure. diff --git a/software-engineering-handbook/software-development-git-users.rst b/software-engineering-handbook/software-development-git-users.rst new file mode 100644 index 0000000..ebd79bb --- /dev/null +++ b/software-engineering-handbook/software-development-git-users.rst @@ -0,0 +1,11 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Software Development (Git Users) +******************************** + +TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Users to Rest +TBD - and insert here. diff --git a/software-engineering-handbook/software-development-management.rst b/software-engineering-handbook/software-development-management.rst new file mode 100644 index 0000000..f10349a --- /dev/null +++ b/software-engineering-handbook/software-development-management.rst @@ -0,0 +1,22 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Software Development Management +******************************* + +TBD - Convert https://devel.rtems.org/wiki/TBR/Website/WhyContribute to Rest +TBD - and insert here + + + + +.. COMMENT: Subsections +.. toctree:: + + software-development-git-users + coding-standards + change-management + issue-tracking diff --git a/software-engineering-handbook/stakeholders.rst b/software-engineering-handbook/stakeholders.rst new file mode 100644 index 0000000..5046269 --- /dev/null +++ b/software-engineering-handbook/stakeholders.rst @@ -0,0 +1,15 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Qualification - Stakeholder Involvement +*************************************** + +Qualification of RTEMS is a specialized activity and only specific users +of RTEMS will complete a formal qualification activity. The RTEMS Project +cannot self-fund this entire activity and requires stakeholder to invest +in an ongoing basis to ensure the any investment they make is maintained +and viable in an ongoing basis. The RTEMS core developers view steady +support of the qualification effort as necessary to continue to lower +the overall costs of qualification RTEMS. diff --git a/software-engineering-handbook/wscript b/software-engineering-handbook/wscript new file mode 100644 index 0000000..26ab0ca --- /dev/null +++ b/software-engineering-handbook/wscript @@ -0,0 +1,11 @@ +from sys import path +from os.path import abspath +path.append(abspath('../common/')) + +from waf import cmd_configure as configure +from waf import cmd_build as build +from waf import cmd_options as options +from waf import spell +from waf import cmd_spell +from waf import linkcheck +from waf import cmd_linkcheck diff --git a/wscript b/wscript index 5ce7f0d..41a1e9e 100644 --- a/wscript +++ b/wscript @@ -17,6 +17,7 @@ build_all = ['user', 'bsp-howto', 'posix-users', 'posix-compliance', + 'software-engineering-handbook', 'filesystem', 'networking', 'shell', -- cgit v1.2.3 From 3715efda2331e3aca66be9fb22e6ad5f58d7b1a3 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 27 Nov 2018 17:24:24 -0600 Subject: First cut --- eng/README | 7 ++ eng/appendix-a.rst | 83 +++++++++++++++++++++ eng/change-management.rst | 14 ++++ eng/change-reports.rst | 11 +++ eng/coding.rst | 11 +++ eng/conf.py | 14 ++++ eng/index.rst | 60 +++++++++++++++ eng/issue-tracking.rst | 13 ++++ eng/license-requirements.rst | 16 ++++ eng/management.rst | 23 ++++++ eng/preface.rst | 29 +++++++ eng/prequalification.rst | 80 ++++++++++++++++++++ eng/release-mgmt.rst | 17 +++++ eng/stakeholders.rst | 15 ++++ eng/test-plan.rst | 44 +++++++++++ eng/test-suites.rst | 10 +++ eng/tester.rst | 10 +++ eng/users-manuals.rst | 30 ++++++++ eng/vc-authors.rst | 11 +++ eng/vc-users.rst | 11 +++ eng/vdd-generation.rst | 13 ++++ eng/wscript | 11 +++ software-engineering-handbook/README | 7 -- .../RTEMS-Engineering-Standards-v3.docx | Bin 32450 -> 0 bytes .../change-management.rst | 14 ---- software-engineering-handbook/coding-standards.rst | 11 --- software-engineering-handbook/conf.py | 14 ---- software-engineering-handbook/index.rst | 56 -------------- software-engineering-handbook/issue-tracking.rst | 18 ----- software-engineering-handbook/preface.rst | 26 ------- software-engineering-handbook/prequalification.rst | 68 ----------------- .../software-development-git-users.rst | 11 --- .../software-development-management.rst | 22 ------ software-engineering-handbook/stakeholders.rst | 15 ---- software-engineering-handbook/wscript | 11 --- wscript | 2 +- 36 files changed, 534 insertions(+), 274 deletions(-) create mode 100644 eng/README create mode 100644 eng/appendix-a.rst create mode 100644 eng/change-management.rst create mode 100644 eng/change-reports.rst create mode 100644 eng/coding.rst create mode 100644 eng/conf.py create mode 100644 eng/index.rst create mode 100644 eng/issue-tracking.rst create mode 100644 eng/license-requirements.rst create mode 100644 eng/management.rst create mode 100644 eng/preface.rst create mode 100644 eng/prequalification.rst create mode 100644 eng/release-mgmt.rst create mode 100644 eng/stakeholders.rst create mode 100644 eng/test-plan.rst create mode 100644 eng/test-suites.rst create mode 100644 eng/tester.rst create mode 100644 eng/users-manuals.rst create mode 100644 eng/vc-authors.rst create mode 100644 eng/vc-users.rst create mode 100644 eng/vdd-generation.rst create mode 100644 eng/wscript delete mode 100644 software-engineering-handbook/README delete mode 100755 software-engineering-handbook/RTEMS-Engineering-Standards-v3.docx delete mode 100644 software-engineering-handbook/change-management.rst delete mode 100644 software-engineering-handbook/coding-standards.rst delete mode 100644 software-engineering-handbook/conf.py delete mode 100644 software-engineering-handbook/index.rst delete mode 100644 software-engineering-handbook/issue-tracking.rst delete mode 100644 software-engineering-handbook/preface.rst delete mode 100644 software-engineering-handbook/prequalification.rst delete mode 100644 software-engineering-handbook/software-development-git-users.rst delete mode 100644 software-engineering-handbook/software-development-management.rst delete mode 100644 software-engineering-handbook/stakeholders.rst delete mode 100644 software-engineering-handbook/wscript diff --git a/eng/README b/eng/README new file mode 100644 index 0000000..5897350 --- /dev/null +++ b/eng/README @@ -0,0 +1,7 @@ +This is a work in process. The initial parts of +RTEMS-Engineering-Standards-v3.docx have been converted to Rest. The +remaining sections need to be converted. And as marked, there are +sections where content from the Wiki needs to be converted to Rest +and included directly here. + +--joel diff --git a/eng/appendix-a.rst b/eng/appendix-a.rst new file mode 100644 index 0000000..dfc141f --- /dev/null +++ b/eng/appendix-a.rst @@ -0,0 +1,83 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Appendix: Core Qualification Artifacts/Documents +************************************************ + +An effort at NASA has been performed to suggest a core set of artifacts +(as defined by BOTH NASA NPR 7150.2B and DO-178B) that can be utilized +by a mission as a baselined starting point for “pre-qualification” +for (open-source) software that is intended to be utilized for flight +purposes. This effort analyzed the overlap between NPR 7150.2B +and DO-178B and highlighted a core set of artifacts to serve as a +starting point for any open-source project. These artifacts were also +cross-referenced with similar activities for other NASA flight software +qualification efforts, such as the open-source Core Flight System (cFS). +Along with the specific artifact, the intent of the artifact was also +captured; in some cases open-source projects, such as RTEMS, are already +meeting the intent of the artifacts with information simply needing +organized and formalized. The table below lists the general category, +artifact name, and its intent. Please note that this table does NOT +represent all the required artifacts for qualification per the standards; +instead, this table represents a subset of the most basic/core artifacts +that form a strong foundation for a software engineering qualification +effort. + +TBD convert to a table; see original PDF for guidance on desired look + +============================================= +Table 1. Core Qualification Artifacts + +Category Artifact Intent +Requirements Software Requirements Specification (SRS) + +Requirements Management The project shall document the software requirements. + +The project shall collect and manage changes to the software requirements. + +The project shall identify, initiate corrective actions, and track until closure inconsistencies among requirements, project plans, and software products. + Requirements Test and Traceability Matrix The project shall perform, document, and maintain bidirectional traceability between the software requirement and the higher-level requirement. + Validation The project shall perform requirements validation to ensure that the software will perform as intended in the customer environment. + + +Design and Implementation Software Development or Management Plan A plan for how you will develop the software that you are intent upon developing and delivering. + +The Software Development Plan includes the objectives, standards and life cycle(s) to be used in the software development process. This plan should include: Standards: Identification of the Software Requirements Standards, Software Design Standards, and Software Code Standards for the project. + + Software Configuration Management Plan To identify and control major software changes, ensure that change is being properly implemented, and report changes to any other personnel or clients who may have an interest. + + Implementation The project shall implement the software design into software code. + +Executable Code to applicable tested software. + + Coding Standards Report The project shall ensure that software coding methods, standards, and/or criteria are adhered to and verified. + Version Description Document (VDD) The project shall provide a Software Version Description document for each software release. + +Testing and Software Assurance Activities Software Test Plan Document describing the testing scope and activities. + Software Assurance/Testing Procedures + To define the techniques, procedures, and methodologies that will be used. + + Software Change Report / Problem Report The project shall regularly hold reviews of software activities, status, and results with the project stakeholders and track issues to resolution. + + Software Schedule Milestones have schedule and schedule is updated accordingly. + + Software Test Report / Verification Results The project shall record, address, and track to closure the results of software verification activities. + +Problem report - Describes the process non-compliance with plans, output deficiency, or software anomalous behavior, and the corrective action taken. + +The project shall ensure that the software code is unit tested per the plans for software testing. + + +Usability Software User’s Manual The Software User Manual defines user instructions for the software. +============================================= + +In an effort to remain lightweight and sustainable for open-source +projects, Table 1 above was condensed into a single artifact outline +that encompasses the artifacts’ intents. The idea is that this living +qualification document will reside under RTEMS source control and be +updated with additional detail accordingly. The artifact outline is +as follows: + diff --git a/eng/change-management.rst b/eng/change-management.rst new file mode 100644 index 0000000..add8d00 --- /dev/null +++ b/eng/change-management.rst @@ -0,0 +1,14 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Change Manaegment +***************** + +Major decisions about RTEMS are made by the core developers in concert +with the user community, guided by the Mission Statement. We provide +access to our development sources via a Git Repository (see these +Instructions for details). + +TBD - ??? what in the Wiki diff --git a/eng/change-reports.rst b/eng/change-reports.rst new file mode 100644 index 0000000..bffb9ae --- /dev/null +++ b/eng/change-reports.rst @@ -0,0 +1,11 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Software Change Report Generation +********************************* + +– Review process, workflows, etc +TBD convert from https://devel.rtems.org/wiki/Release diff --git a/eng/coding.rst b/eng/coding.rst new file mode 100644 index 0000000..0af9c78 --- /dev/null +++ b/eng/coding.rst @@ -0,0 +1,11 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Coding Standards +**************** + +TBD - Convert the following to Rest and insert into this file +TBD - https://devel.rtems.org/wiki/Developer/Coding/Conventions +TBD - https://devel.rtems.org/wiki/Developer/Coding diff --git a/eng/conf.py b/eng/conf.py new file mode 100644 index 0000000..a4da3ff --- /dev/null +++ b/eng/conf.py @@ -0,0 +1,14 @@ +import sys, os +sys.path.append(os.path.abspath('../common/')) + +from conf import * + +project = "RTEMS Software Engineering Handbook" + +latex_documents = [ + ('index', + 'software-engineering-handbook.tex', + u'RTEMS Software Engineering Handbook', + u'RTEMS Documentation Project', + 'manual'), +] diff --git a/eng/index.rst b/eng/index.rst new file mode 100644 index 0000000..5fe93d4 --- /dev/null +++ b/eng/index.rst @@ -0,0 +1,60 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: COPYRIGHT (c) 2016-2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +================================================ +RTEMS Software Engineering Handbook (|version|). +================================================ + + | **COPYRIGHT (c) 1988 - 2015.** + | **On-Line Applications Research Corporation (OAR).** + | **COPYRIGHT (c) 2016-2018.** + | **RTEMS Foundation, The RTEMS Documentation Project** + + | **License:** + | Creative Commons Attribution-ShareAlike 4.0 International Public License + | https://creativecommons.org/licenses/by-sa/4.0/legalcode + +The authors have used their best efforts in preparing this material. These +efforts include the development, research, and testing of the theories and +programs to determine their effectiveness. No warranty of any kind, expressed +or implied, with regard to the software or the material contained in this +document is provided. No liability arising out of the application or use of +any product described in this document is assumed. The authors reserve the +right to revise this material and to make changes from time to time in the +content hereof without obligation to notify anyone of such revision or changes. + +The RTEMS Project is hosted at http://www.rtems.org/. Any inquiries concerning +RTEMS, its related support components, or its documentation should be directed +to the Community Project hosted at http://www.rtems.org/. + +.. topic:: RTEMS Online Resources + + ================ ============================= + Home https://www.rtems.org/ + Developers https://devel.rtems.org/ + Documentation https://docs.rtems.org/ + Bug Reporting https://devel.rtems.org/query + Mailing Lists https://lists.rtems.org/ + Git Repositories https://git.rtems.org/ + ================ ============================= + +.. toctree:: + :maxdepth: 4 + :numbered: + + preface + prequalification + stakeholders + management + release-mgmt + users-manuals + license-requirements + appendix-a + function_and_variable + concept + +* :ref:`genindex` diff --git a/eng/issue-tracking.rst b/eng/issue-tracking.rst new file mode 100644 index 0000000..680d7bd --- /dev/null +++ b/eng/issue-tracking.rst @@ -0,0 +1,13 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Issue Tracking +************** + +TBD - This covers Issue Tracking and Trac usage +Need instructions which weave useful URLs including ones like these +https://devel.rtems.org/query +https://devel.rtems.org/wiki/NewTicket + diff --git a/eng/license-requirements.rst b/eng/license-requirements.rst new file mode 100644 index 0000000..06934b1 --- /dev/null +++ b/eng/license-requirements.rst @@ -0,0 +1,16 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Licensing Requirements +********************** + +All artifacts shall adhere to RTEMS Project licensing +requirements. Currently, the preferred licenses are CC-BY-SA-4.0 license +for documentation and “Two Paragraph BSD” for source code. + +• https://devel.rtems.org/wiki/Developer/Coding/Conventions#Licenses + +• https://www.rtems.org/license diff --git a/eng/management.rst b/eng/management.rst new file mode 100644 index 0000000..3ed36d4 --- /dev/null +++ b/eng/management.rst @@ -0,0 +1,23 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Software Development Management +******************************* + +TBD - Convert https://devel.rtems.org/wiki/TBR/Website/WhyContribute to Rest +TBD - and insert here + + + + +.. COMMENT: Subsections +.. toctree:: + + vc-users + vc-writers + coding + change-management + issue-tracking diff --git a/eng/preface.rst b/eng/preface.rst new file mode 100644 index 0000000..562f61f --- /dev/null +++ b/eng/preface.rst @@ -0,0 +1,29 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Preface +******* + +The Real Time Executive for Multiprocessor Systems (RTEMS) operating +systems is a layered system with each of the public APIs implemented in +terms of a common foundation layer called the SuperCore. RTEMS provides +full capabilities for management of tasks, interrupts time, and multiple +processors in addition to those features typical of generic operating +systems. RTEMS has been implemented in both the Ada and C programming +languages. + +.. topic: RTEMS Mission Statement + + RTEMS development aims to provide a free deterministic real-time operating + system targeted towards deeply embedded systems which is competitive + with closed source products. The RTEMS project encourages the support + and use of standard APIs in order to promote application portability + and ease porting other packages to the RTEMS environment. Source: + https://devel.rtems.org/wiki/Mission_Statement + +The RTEMS development effort uses an open development environment in +which all users collaborate to improve RTEMS. The RTEMS cross development +toolset is based upon the free GNU tools and the open source C Library +newlib. RTEMS supports many host platforms and target architectures. diff --git a/eng/prequalification.rst b/eng/prequalification.rst new file mode 100644 index 0000000..4055f70 --- /dev/null +++ b/eng/prequalification.rst @@ -0,0 +1,80 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: COPYRIGHT (c) 2016-2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Introduction to Pre-Qualification +********************************* + +RTEMS has a long history of being used to support critical +applications. In some of these application domains, there are standards +(e.g., DO-178C, NPR 7150.2) which define the expectations for the +processes used to develop software and the associated artifacts. These +standards typically do not specify software functionality but address +topics like requirements definition, traceability, having a documented +change process, coding style, testing requirements, and a user’s +manual. During system test, these standards call for a review – usually +by an independent entity – that the standard has been adhered too. These +reviews cover a broad variety of topics and activities, but the process +is generally referred to as qualification, verification, or auditing +against the specific standard in use. The RTEMS Project will use the +term “qualification” independent of the standard. + +The goal of the RTEMS Qualification Project is to make RTEMS easier +to review regardless of the standard chosen. Quite specifically, +the RTEMS Qualification effort will NOT produce a directly qualified +product or artifacts in the format dictated by a specific organization +or standard. The goal is to make RTEMS itself, documentation, testing +infrastructure, etc. more closely align with the information requirements +of these high integrity qualification standards. In addition to improving +the items that a mature, high quality open source project will have, +there are additional artifacts needed for a qualification effort that +no known open source project possesses. Specifically, requirements and +the associated traceability to source code, tests, and documentation +are needed. + +The RTEMS Qualification Project is technically +“pre-qualification”. True qualification must be performed on the +project’s target hardware in a system context. The FAA has provided +guidance for Reusable Software Components (FAA-AC20-148) and this +effort should follow that guidance. The open RTEMS Project, with the +assistance of domain experts, will possess and maintain the master +technical information needed in a qualification effort. Consultants +will provide the services required to tailor the master information, +perform testing on specific system hardware, and to guide end users in +using the master technical data in the context of a particular standard. + +The RTEMS Qualification Project will broadly address two areas. The +first area is suggesting areas of improvement for automated project +infrastructure and the master technical data that has traditionally been +provided by the RTEMS Project. For example, the RTEMS Qualification could +suggest specific improvements to code coverage reports. The teams focused +on qualification should be able to provide resources for improving the +automated project infrastructure and master technical data for RTEMS. The +term “resources” is often used by open source projects to refer to +volunteer code contributions or funding. Although code contributions in +this area are important and always welcome, funding is also important. At +a minimum, ongoing funding is needed for maintenance and upgrades of +the RTEMS Project server infrastructure, addition of services to those +servers, and core contributors to review submissions + +The second area is the creation and maintenance of master technical +data that has traditionally not been owned or maintained by the RTEMS +Project. The most obvious example of this is a requirements set with +proper infrastructure for tracing requirements through code to test +and documentation. It is expected that these will be maintained by the +RTEMS Qualification Project. They will be evaluated for adoption by +the main RTEMS Project but the additional maintenance burden imposed +will be a strong factor in this consideration. It behooves the RTEMS +Qualification Project to limit dependence on manual checks and ensure +that automation and ongoing support for that automation is contributed +to the RTEMS Project. + +It is expected that the RTEMS Qualification Project will create and +maintain maps from the RTEMS master technical data to the various +qualification standards. It will maintain “scorecards” which +identify how the RTEMS Project is currently doing when reviewed per each +standard. These will be maintained in the open as community resources +which will guide the community in improving its infrastructure. diff --git a/eng/release-mgmt.rst b/eng/release-mgmt.rst new file mode 100644 index 0000000..276440c --- /dev/null +++ b/eng/release-mgmt.rst @@ -0,0 +1,17 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Software Release Management +*************************** + +TBD write content + + +.. COMMENT: Subsections +.. toctree:: + + change-reports + vdd-generation diff --git a/eng/stakeholders.rst b/eng/stakeholders.rst new file mode 100644 index 0000000..5046269 --- /dev/null +++ b/eng/stakeholders.rst @@ -0,0 +1,15 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Qualification - Stakeholder Involvement +*************************************** + +Qualification of RTEMS is a specialized activity and only specific users +of RTEMS will complete a formal qualification activity. The RTEMS Project +cannot self-fund this entire activity and requires stakeholder to invest +in an ongoing basis to ensure the any investment they make is maintained +and viable in an ongoing basis. The RTEMS core developers view steady +support of the qualification effort as necessary to continue to lower +the overall costs of qualification RTEMS. diff --git a/eng/test-plan.rst b/eng/test-plan.rst new file mode 100644 index 0000000..43ec69f --- /dev/null +++ b/eng/test-plan.rst @@ -0,0 +1,44 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Software Test Plan Assurance and Procedures +******************************************** + +Testing and Coverage +==================== + +Testing to verify that requirements are implemented is a critical part of +the high integrity processes. Similarly, measuring and reporting source +and decision path coverage of source code is critical. + +Needed improvements to the RTEMS testing infrastructure should be done +as part of the open project. Similarly, improvements in RTEMS coverage +reporting should be done as part of the open project. Both of these +capabilities are part of the RTEMS Tester toolset. + +Assuming that a requirements focused test suite is added to the open +RTEMS, tools will be needed to assist in verifying that requirements are +“fully tested.” A fully tested requirement is one which is implemented +and tested with associated logical tracing. Tools automating this analysis +and generating reporting and alerts will be a critical part of ensuring +the master technical data does not bit rot. + +Must use tools from: + +TBD - Change URL to git.rtems.org and list support tools +RTEMS Tools Project: https://github.com/RTEMS/rtems-tools + + +Scope, Procedures, Methodologies, Tools +TBD - Write content + + + +.. COMMENT: Subsections +.. toctree:: + + test-suites + tester diff --git a/eng/test-suites.rst b/eng/test-suites.rst new file mode 100644 index 0000000..a076fbe --- /dev/null +++ b/eng/test-suites.rst @@ -0,0 +1,10 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Test Suites +*********** + +TBD from https://devel.rtems.org/wiki/Developer/Testing/TestSuites + diff --git a/eng/tester.rst b/eng/tester.rst new file mode 100644 index 0000000..5f12802 --- /dev/null +++ b/eng/tester.rst @@ -0,0 +1,10 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +RTEMS Tester +************ + +TBD https://devel.rtems.org/wiki/Testing/Tester + diff --git a/eng/users-manuals.rst b/eng/users-manuals.rst new file mode 100644 index 0000000..e6c5dfa --- /dev/null +++ b/eng/users-manuals.rst @@ -0,0 +1,30 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +User's Manuals +********************************* + +TBD - write and link to useful documentation, potential URLs: + +Reference the RTEMS C User’s Manual + +* https://docs.rtems.org/doc-current/share/rtems/pdf/c_user.pdf + +Reference any other existing user documentation + +* https://docs.rtems.org/doxygen/cpukit/html/index.html + +* https://devel.rtems.org/ + +* http://www.rtems.com/ + +* https://www.rtems.org/onlinedocs.html + +* https://devel.rtems.org/wiki/Developer/Contributing + +* https://docs.rtems.org/releases/rtemsdocs-4.10.1/share/rtems/html/ + + diff --git a/eng/vc-authors.rst b/eng/vc-authors.rst new file mode 100644 index 0000000..68f28e3 --- /dev/null +++ b/eng/vc-authors.rst @@ -0,0 +1,11 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Software Development (Git Writers) +********************************** + +TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Committers +TBD - and insert here. diff --git a/eng/vc-users.rst b/eng/vc-users.rst new file mode 100644 index 0000000..ebd79bb --- /dev/null +++ b/eng/vc-users.rst @@ -0,0 +1,11 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Software Development (Git Users) +******************************** + +TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Users to Rest +TBD - and insert here. diff --git a/eng/vdd-generation.rst b/eng/vdd-generation.rst new file mode 100644 index 0000000..28b891c --- /dev/null +++ b/eng/vdd-generation.rst @@ -0,0 +1,13 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Version Description Document (VDD) Generation +********************************************* + +TBD - probably Dannie's project + +This URL may be of use but it probably Trac auto-generated and not +useful for this purpose: https://devel.rtems.org/wiki/TracChangeLog diff --git a/eng/wscript b/eng/wscript new file mode 100644 index 0000000..26ab0ca --- /dev/null +++ b/eng/wscript @@ -0,0 +1,11 @@ +from sys import path +from os.path import abspath +path.append(abspath('../common/')) + +from waf import cmd_configure as configure +from waf import cmd_build as build +from waf import cmd_options as options +from waf import spell +from waf import cmd_spell +from waf import linkcheck +from waf import cmd_linkcheck diff --git a/software-engineering-handbook/README b/software-engineering-handbook/README deleted file mode 100644 index 5897350..0000000 --- a/software-engineering-handbook/README +++ /dev/null @@ -1,7 +0,0 @@ -This is a work in process. The initial parts of -RTEMS-Engineering-Standards-v3.docx have been converted to Rest. The -remaining sections need to be converted. And as marked, there are -sections where content from the Wiki needs to be converted to Rest -and included directly here. - ---joel diff --git a/software-engineering-handbook/RTEMS-Engineering-Standards-v3.docx b/software-engineering-handbook/RTEMS-Engineering-Standards-v3.docx deleted file mode 100755 index 7fbfb9e..0000000 Binary files a/software-engineering-handbook/RTEMS-Engineering-Standards-v3.docx and /dev/null differ diff --git a/software-engineering-handbook/change-management.rst b/software-engineering-handbook/change-management.rst deleted file mode 100644 index ff04675..0000000 --- a/software-engineering-handbook/change-management.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: COPYRIGHT (c) 2018. -.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project - -Change Manaegment -***************** - -Major decisions about RTEMS are made by the core developers in concert -with the user community, guided by the Mission Statement. We provide -access to our development sources via a Git Repository (see these -Instructions for details). - -TBD - ??? diff --git a/software-engineering-handbook/coding-standards.rst b/software-engineering-handbook/coding-standards.rst deleted file mode 100644 index 0af9c78..0000000 --- a/software-engineering-handbook/coding-standards.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: COPYRIGHT (c) 2018. -.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project - -Coding Standards -**************** - -TBD - Convert the following to Rest and insert into this file -TBD - https://devel.rtems.org/wiki/Developer/Coding/Conventions -TBD - https://devel.rtems.org/wiki/Developer/Coding diff --git a/software-engineering-handbook/conf.py b/software-engineering-handbook/conf.py deleted file mode 100644 index a4da3ff..0000000 --- a/software-engineering-handbook/conf.py +++ /dev/null @@ -1,14 +0,0 @@ -import sys, os -sys.path.append(os.path.abspath('../common/')) - -from conf import * - -project = "RTEMS Software Engineering Handbook" - -latex_documents = [ - ('index', - 'software-engineering-handbook.tex', - u'RTEMS Software Engineering Handbook', - u'RTEMS Documentation Project', - 'manual'), -] diff --git a/software-engineering-handbook/index.rst b/software-engineering-handbook/index.rst deleted file mode 100644 index 224e46a..0000000 --- a/software-engineering-handbook/index.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: COPYRIGHT (c) 1988-2008. -.. COMMENT: On-Line Applications Research Corporation (OAR). -.. COMMENT: COPYRIGHT (c) 2016-2018. -.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project - -================================================ -RTEMS Software Engineering Handbook (|version|). -================================================ - - | **COPYRIGHT (c) 1988 - 2015.** - | **On-Line Applications Research Corporation (OAR).** - | **COPYRIGHT (c) 2016-2018.** - | **RTEMS Foundation, The RTEMS Documentation Project** - - | **License:** - | Creative Commons Attribution-ShareAlike 4.0 International Public License - | https://creativecommons.org/licenses/by-sa/4.0/legalcode - -The authors have used their best efforts in preparing this material. These -efforts include the development, research, and testing of the theories and -programs to determine their effectiveness. No warranty of any kind, expressed -or implied, with regard to the software or the material contained in this -document is provided. No liability arising out of the application or use of -any product described in this document is assumed. The authors reserve the -right to revise this material and to make changes from time to time in the -content hereof without obligation to notify anyone of such revision or changes. - -The RTEMS Project is hosted at http://www.rtems.org/. Any inquiries concerning -RTEMS, its related support components, or its documentation should be directed -to the Community Project hosted at http://www.rtems.org/. - -.. topic:: RTEMS Online Resources - - ================ ============================= - Home https://www.rtems.org/ - Developers https://devel.rtems.org/ - Documentation https://docs.rtems.org/ - Bug Reporting https://devel.rtems.org/query - Mailing Lists https://lists.rtems.org/ - Git Repositories https://git.rtems.org/ - ================ ============================= - -.. toctree:: - :maxdepth: 4 - :numbered: - - preface - prequalification - stakeholders - software-development-management - function_and_variable - concept - -* :ref:`genindex` diff --git a/software-engineering-handbook/issue-tracking.rst b/software-engineering-handbook/issue-tracking.rst deleted file mode 100644 index 47ec03a..0000000 --- a/software-engineering-handbook/issue-tracking.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: COPYRIGHT (c) 2018. -.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project - -Issue Tracking -************** - -This section discussions Trac usage and tickets. - -Related URLs to review for conversion to this document - -https://devel.rtems.org/wiki/NewTicket -https://devel.rtems.org/wiki/Developer/Bug_Reporting - -Querying existing tickets (keep as a link) - -https://devel.rtems.org/query diff --git a/software-engineering-handbook/preface.rst b/software-engineering-handbook/preface.rst deleted file mode 100644 index 81b16df..0000000 --- a/software-engineering-handbook/preface.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: COPYRIGHT (c) 2018. -.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project - -Preface -******* - -The Real Time Executive for Multiprocessor Systems (RTEMS) operating -systems is a layered system with each of the public APIs implemented in -terms of a common foundation layer called the SuperCore. RTEMS provides -full capabilities for management of tasks, interrupts time, and multiple -processors in addition to those features typical of generic operating -systems. RTEMS has been implemented in both the Ada and C programming -languages. - -.. topic: RTEMS Mission Statement - - RTEMS development aims to provide a free deterministic real-time operating - system targeted towards deeply embedded systems which is competitive - with closed source products. The RTEMS project encourages the support - and use of standard APIs in order to promote application portability - and ease porting other packages to the RTEMS environment. Source: - https://devel.rtems.org/wiki/Mission_Statement - -The RTEMS development effort uses an open development environment in which all users collaborate to improve RTEMS. The RTEMS cross development toolset is based upon the free GNU tools and the open source C Library newlib. RTEMS supports many host platforms and target architectures. diff --git a/software-engineering-handbook/prequalification.rst b/software-engineering-handbook/prequalification.rst deleted file mode 100644 index 5234dbf..0000000 --- a/software-engineering-handbook/prequalification.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: COPYRIGHT (c) 1988-2008. -.. COMMENT: On-Line Applications Research Corporation (OAR). -.. COMMENT: COPYRIGHT (c) 2016-2018. -.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project - -Introduction to Pre-Qualification -********************************* - -RTEMS has a long history of being used to support critical -applications. In some of these application domains, there are standards -(e.g., DO-178C, NPR 7150.2) which define the expectations for the -processes used to develop software and the associated artifacts. These -standards typically do not specify software functionality but address -topics like requirements definition, traceability, having a documented -change process, coding style, testing requirements, and a user’s -manual. During system test, these standards call for a review – usually -by an independent entity – that the standard has been adhered too. These -reviews cover a broad variety of topics and activities, but the process -is generally referred to as qualification, verification, or auditing -against the specific standard in use. The RTEMS Project will use the -term “qualification” independent of the standard. - -The goal of the RTEMS Qualification Project is to make RTEMS easier -to review regardless of the standard chosen. Quite specifically, -the RTEMS Qualification effort will NOT produce a directly qualified -product or artifacts in the format dictated by a specific organization -or standard. The goal is to make RTEMS itself, documentation, testing -infrastructure, etc. more closely align with the information requirements -of these high integrity qualification standards. In addition to improving -the items that a mature, high quality open source project will have, -there are additional artifacts needed for a qualification effort that -no known open source project possesses. Specifically, requirements and -the associated traceability to source code, tests, and documentation -are needed. - -The RTEMS Qualification Project is technically -“pre-qualification”. True qualification must be performed on the -project’s target hardware in a system context. The FAA has provided -guidance for Reusable Software Components (FAA-AC20-148) and this -effort should follow that guidance. The open RTEMS Project, with the -assistance of domain experts, will possess and maintain the master -technical information needed in a qualification effort. Consultants -will provide the services required to tailor the master information, -perform testing on specific system hardware, and to guide end users in -using the master technical data in the context of a particular standard. - -The RTEMS Qualification Project will broadly address two areas. The first area is suggesting areas of improvement for automated project infrastructure and the master technical data that has traditionally been provided by the RTEMS Project. For example, the RTEMS Qualification could suggest specific improvements to code coverage reports. The teams focused on qualification should be able to provide resources for improving the automated project infrastructure and master technical data for RTEMS. The term “resources” is often used by open source projects to refer to volunteer code contributions or funding. Although code contributions in this area are important and always welcome, funding is also important. At a minimum, ongoing funding is needed for maintenance and upgrades of the RTEMS Project server infrastructure, addition of services to those servers, and core contributors to review submissions - -The second area is the creation and maintenance of master technical -data that has traditionally not been owned or maintained by the RTEMS -Project. The most obvious example of this is a requirements set with -proper infrastructure for tracing requirements through code to test -and documentation. It is expected that these will be maintained by the -RTEMS Qualification Project. They will be evaluated for adoption by -the main RTEMS Project but the additional maintenance burden imposed -will be a strong factor in this consideration. It behooves the RTEMS -Qualification Project to limit dependence on manual checks and ensure -that automation and ongoing support for that automation is contributed -to the RTEMS Project. - -It is expected that the RTEMS Qualification Project will create and -maintain maps from the RTEMS master technical data to the various -qualification standards. It will maintain “scorecards” which -identify how the RTEMS Project is currently doing when reviewed per each -standard. These will be maintained in the open as community resources -which will guide the community in improving its infrastructure. diff --git a/software-engineering-handbook/software-development-git-users.rst b/software-engineering-handbook/software-development-git-users.rst deleted file mode 100644 index ebd79bb..0000000 --- a/software-engineering-handbook/software-development-git-users.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: COPYRIGHT (c) 2018. -.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project - - -Software Development (Git Users) -******************************** - -TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Users to Rest -TBD - and insert here. diff --git a/software-engineering-handbook/software-development-management.rst b/software-engineering-handbook/software-development-management.rst deleted file mode 100644 index f10349a..0000000 --- a/software-engineering-handbook/software-development-management.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: COPYRIGHT (c) 2018. -.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project - - -Software Development Management -******************************* - -TBD - Convert https://devel.rtems.org/wiki/TBR/Website/WhyContribute to Rest -TBD - and insert here - - - - -.. COMMENT: Subsections -.. toctree:: - - software-development-git-users - coding-standards - change-management - issue-tracking diff --git a/software-engineering-handbook/stakeholders.rst b/software-engineering-handbook/stakeholders.rst deleted file mode 100644 index 5046269..0000000 --- a/software-engineering-handbook/stakeholders.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: COPYRIGHT (c) 2018. -.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project - -Qualification - Stakeholder Involvement -*************************************** - -Qualification of RTEMS is a specialized activity and only specific users -of RTEMS will complete a formal qualification activity. The RTEMS Project -cannot self-fund this entire activity and requires stakeholder to invest -in an ongoing basis to ensure the any investment they make is maintained -and viable in an ongoing basis. The RTEMS core developers view steady -support of the qualification effort as necessary to continue to lower -the overall costs of qualification RTEMS. diff --git a/software-engineering-handbook/wscript b/software-engineering-handbook/wscript deleted file mode 100644 index 26ab0ca..0000000 --- a/software-engineering-handbook/wscript +++ /dev/null @@ -1,11 +0,0 @@ -from sys import path -from os.path import abspath -path.append(abspath('../common/')) - -from waf import cmd_configure as configure -from waf import cmd_build as build -from waf import cmd_options as options -from waf import spell -from waf import cmd_spell -from waf import linkcheck -from waf import cmd_linkcheck diff --git a/wscript b/wscript index 41a1e9e..82d5eaa 100644 --- a/wscript +++ b/wscript @@ -17,7 +17,7 @@ build_all = ['user', 'bsp-howto', 'posix-users', 'posix-compliance', - 'software-engineering-handbook', + 'eng', 'filesystem', 'networking', 'shell', -- cgit v1.2.3 From 82e721e894ddce39ec83c226994344d406aa107a Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Wed, 28 Nov 2018 18:18:38 -0600 Subject: eng: Clean up. --- eng/appendix-a.rst | 5 +++-- eng/index.rst | 1 + eng/management.rst | 2 +- eng/users-manuals.rst | 6 +++++- 4 files changed, 10 insertions(+), 4 deletions(-) diff --git a/eng/appendix-a.rst b/eng/appendix-a.rst index dfc141f..633996b 100644 --- a/eng/appendix-a.rst +++ b/eng/appendix-a.rst @@ -27,8 +27,9 @@ that form a strong foundation for a software engineering qualification effort. TBD convert to a table; see original PDF for guidance on desired look +TBD The PDF is in https://ftp.rtems.org/pub/rtems/people/joel/sw_eng_hb/ -============================================= +.. COMMENT: ====================================== BEGIN Table 1. Core Qualification Artifacts Category Artifact Intent @@ -72,7 +73,7 @@ The project shall ensure that the software code is unit tested per the plans for Usability Software User’s Manual The Software User Manual defines user instructions for the software. -============================================= +.. COMMENT: ====================================== END In an effort to remain lightweight and sustainable for open-source projects, Table 1 above was condensed into a single artifact outline diff --git a/eng/index.rst b/eng/index.rst index 5fe93d4..9d48ac4 100644 --- a/eng/index.rst +++ b/eng/index.rst @@ -50,6 +50,7 @@ to the Community Project hosted at http://www.rtems.org/. prequalification stakeholders management + test-plan release-mgmt users-manuals license-requirements diff --git a/eng/management.rst b/eng/management.rst index 3ed36d4..6494819 100644 --- a/eng/management.rst +++ b/eng/management.rst @@ -17,7 +17,7 @@ TBD - and insert here .. toctree:: vc-users - vc-writers + vc-authors coding change-management issue-tracking diff --git a/eng/users-manuals.rst b/eng/users-manuals.rst index e6c5dfa..e3b102d 100644 --- a/eng/users-manuals.rst +++ b/eng/users-manuals.rst @@ -5,7 +5,7 @@ User's Manuals -********************************* +************** TBD - write and link to useful documentation, potential URLs: @@ -28,3 +28,7 @@ Reference any other existing user documentation * https://docs.rtems.org/releases/rtemsdocs-4.10.1/share/rtems/html/ +Documentation Style Guidelines +============================== + +TBD - write me -- cgit v1.2.3 From 8444a20f29b4fcd6604efdb7a36ffdba0c13d775 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Thu, 29 Nov 2018 15:49:13 -0600 Subject: More updates to reflect GCI tasks --- eng/change-management.rst | 4 ++-- eng/change-reports.rst | 3 +-- eng/coding-80cols.rst | 10 ++++++++++ eng/coding-conventions.rst | 11 +++++++++++ eng/coding-deprecating.rst | 11 +++++++++++ eng/coding-doxygen-bsp.rst | 10 ++++++++++ eng/coding-doxygen.rst | 10 ++++++++++ eng/coding-file-hdr.rst | 10 ++++++++++ eng/coding-gen-patch.rst | 10 ++++++++++ eng/coding-naming.rst | 10 ++++++++++ eng/coding.rst | 16 +++++++++++++--- eng/issue-tracking.rst | 9 +++++++++ eng/license-requirements.rst | 11 +++++++++-- eng/management.rst | 3 --- eng/stakeholders.rst | 10 +++++++++- eng/test-plan.rst | 2 -- eng/test-suites.rst | 3 +++ eng/tester.rst | 2 ++ eng/vdd-generation.rst | 6 +++--- 19 files changed, 133 insertions(+), 18 deletions(-) create mode 100644 eng/coding-80cols.rst create mode 100644 eng/coding-conventions.rst create mode 100644 eng/coding-deprecating.rst create mode 100644 eng/coding-doxygen-bsp.rst create mode 100644 eng/coding-doxygen.rst create mode 100644 eng/coding-file-hdr.rst create mode 100644 eng/coding-gen-patch.rst create mode 100644 eng/coding-naming.rst diff --git a/eng/change-management.rst b/eng/change-management.rst index add8d00..3e6d30a 100644 --- a/eng/change-management.rst +++ b/eng/change-management.rst @@ -3,7 +3,7 @@ .. COMMENT: COPYRIGHT (c) 2018. .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project -Change Manaegment +Change Management ***************** Major decisions about RTEMS are made by the core developers in concert @@ -11,4 +11,4 @@ with the user community, guided by the Mission Statement. We provide access to our development sources via a Git Repository (see these Instructions for details). -TBD - ??? what in the Wiki +TBD - ??? what in the Wiki could go here diff --git a/eng/change-reports.rst b/eng/change-reports.rst index bffb9ae..841bd04 100644 --- a/eng/change-reports.rst +++ b/eng/change-reports.rst @@ -7,5 +7,4 @@ Software Change Report Generation ********************************* -– Review process, workflows, etc -TBD convert from https://devel.rtems.org/wiki/Release +TBD - What goes here? diff --git a/eng/coding-80cols.rst b/eng/coding-80cols.rst new file mode 100644 index 0000000..442a9e0 --- /dev/null +++ b/eng/coding-80cols.rst @@ -0,0 +1,10 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Eighty Character Line Limit +*************************** + +TBD - Convert the following to Rest and insert into this file +TBD - https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line diff --git a/eng/coding-conventions.rst b/eng/coding-conventions.rst new file mode 100644 index 0000000..654b5bb --- /dev/null +++ b/eng/coding-conventions.rst @@ -0,0 +1,11 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Coding Conventions +****************** + +TBD - Convert the following to Rest and insert into this file +TBD - https://devel.rtems.org/wiki/Developer/Coding/Conventions + diff --git a/eng/coding-deprecating.rst b/eng/coding-deprecating.rst new file mode 100644 index 0000000..4ca4c7c --- /dev/null +++ b/eng/coding-deprecating.rst @@ -0,0 +1,11 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Deprectating Interfaces +*********************** + +TBD - Convert the following to Rest and insert into this file +TBD - https://devel.rtems.org/wiki/Developer/Coding/Deprecating + diff --git a/eng/coding-doxygen-bsp.rst b/eng/coding-doxygen-bsp.rst new file mode 100644 index 0000000..e6f73d0 --- /dev/null +++ b/eng/coding-doxygen-bsp.rst @@ -0,0 +1,10 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +BSP Doxygen Recommentations +=========================== + +TBD - Convert the following to Rest and insert into this file +TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen_for_BSPs diff --git a/eng/coding-doxygen.rst b/eng/coding-doxygen.rst new file mode 100644 index 0000000..5aafde0 --- /dev/null +++ b/eng/coding-doxygen.rst @@ -0,0 +1,10 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +General Doxygen Recommentations +=============================== + +TBD - Convert the following to Rest and insert into this file +TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst new file mode 100644 index 0000000..67c177f --- /dev/null +++ b/eng/coding-file-hdr.rst @@ -0,0 +1,10 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Boilerplate File Header +*********************** + +TBD - Convert the following to Rest and insert into this file +TBD - https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header diff --git a/eng/coding-gen-patch.rst b/eng/coding-gen-patch.rst new file mode 100644 index 0000000..d4e05da --- /dev/null +++ b/eng/coding-gen-patch.rst @@ -0,0 +1,10 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Generating a Tools Patch +************************ + +TBD - Convert the following to Rest and insert into this file +TBD - https://devel.rtems.org/wiki/Developer/Coding/GenerateAPatch diff --git a/eng/coding-naming.rst b/eng/coding-naming.rst new file mode 100644 index 0000000..054dd5d --- /dev/null +++ b/eng/coding-naming.rst @@ -0,0 +1,10 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Naming Rules +************ + +TBD - Convert the following to Rest and insert into this file +TBD - https://devel.rtems.org/wiki/Developer/Coding/NamingRules diff --git a/eng/coding.rst b/eng/coding.rst index 0af9c78..14223ba 100644 --- a/eng/coding.rst +++ b/eng/coding.rst @@ -6,6 +6,16 @@ Coding Standards **************** -TBD - Convert the following to Rest and insert into this file -TBD - https://devel.rtems.org/wiki/Developer/Coding/Conventions -TBD - https://devel.rtems.org/wiki/Developer/Coding +TBD - Write introduction, re-order, identify missing content + +.. COMMENT: Subsections +.. toctree:: + + coding-conventions + coding-80cols + coding-deprecating + coding-doxygen-bsp + coding-doxygen + coding-file-hdr + coding-gen-patch + coding-naming diff --git a/eng/issue-tracking.rst b/eng/issue-tracking.rst index 680d7bd..83c76c8 100644 --- a/eng/issue-tracking.rst +++ b/eng/issue-tracking.rst @@ -6,8 +6,17 @@ Issue Tracking ************** +TBD Review process, workflows, etc + TBD - This covers Issue Tracking and Trac usage Need instructions which weave useful URLs including ones like these https://devel.rtems.org/query https://devel.rtems.org/wiki/NewTicket +Filing a Change Request or Problem Report +========================================= + +The RTEMS Project uses Trac to manage all change requests and problem reports +and refers to either as a ticket. Ticket may be filed or viewed at +https://devel.rtems.org/wiki/Release + diff --git a/eng/license-requirements.rst b/eng/license-requirements.rst index 06934b1..90a5409 100644 --- a/eng/license-requirements.rst +++ b/eng/license-requirements.rst @@ -11,6 +11,13 @@ All artifacts shall adhere to RTEMS Project licensing requirements. Currently, the preferred licenses are CC-BY-SA-4.0 license for documentation and “Two Paragraph BSD” for source code. -• https://devel.rtems.org/wiki/Developer/Coding/Conventions#Licenses +Historically, RTEMS has been licensed under the GPL v2 with linking +exception (https://www.rtems.org/license). It is preferred that new +submissions be under one of the two preferred licenses. If you have +previously submitted code to RTEMS under a historical license, please +grant the project permission to relicense. See +https://devel.rtems.org/ticket/3053 for details. + +TBD - Convert the following to Rest and insert into this file +TBD - https://devel.rtems.org/wiki/Developer/Coding/Conventions#Licenses -• https://www.rtems.org/license diff --git a/eng/management.rst b/eng/management.rst index 6494819..2b03dee 100644 --- a/eng/management.rst +++ b/eng/management.rst @@ -10,9 +10,6 @@ Software Development Management TBD - Convert https://devel.rtems.org/wiki/TBR/Website/WhyContribute to Rest TBD - and insert here - - - .. COMMENT: Subsections .. toctree:: diff --git a/eng/stakeholders.rst b/eng/stakeholders.rst index 5046269..51bd125 100644 --- a/eng/stakeholders.rst +++ b/eng/stakeholders.rst @@ -3,8 +3,16 @@ .. COMMENT: COPYRIGHT (c) 2018. .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project +RTEMS Stakeholders +****************** + +RTEMS is a community based open source project. All users are treated +as stakeholders. It is hoped that as stakeholders, users will contribute +to the project, sponsor core developers, and help fund the infrastructure +required to host and manage the project. + Qualification - Stakeholder Involvement -*************************************** +======================================= Qualification of RTEMS is a specialized activity and only specific users of RTEMS will complete a formal qualification activity. The RTEMS Project diff --git a/eng/test-plan.rst b/eng/test-plan.rst index 43ec69f..d1320a6 100644 --- a/eng/test-plan.rst +++ b/eng/test-plan.rst @@ -35,8 +35,6 @@ RTEMS Tools Project: https://github.com/RTEMS/rtems-tools Scope, Procedures, Methodologies, Tools TBD - Write content - - .. COMMENT: Subsections .. toctree:: diff --git a/eng/test-suites.rst b/eng/test-suites.rst index a076fbe..1380ee8 100644 --- a/eng/test-suites.rst +++ b/eng/test-suites.rst @@ -6,5 +6,8 @@ Test Suites *********** +TBD - Convert the following to Rest and insert into this file TBD from https://devel.rtems.org/wiki/Developer/Testing/TestSuites +TBD also update list of tests based on rtems/testsuites + diff --git a/eng/tester.rst b/eng/tester.rst index 5f12802..97893aa 100644 --- a/eng/tester.rst +++ b/eng/tester.rst @@ -6,5 +6,7 @@ RTEMS Tester ************ +TBD - Convert the following to Rest and insert into this file TBD https://devel.rtems.org/wiki/Testing/Tester +TBD - Above file is horribly out of date. Find new docs and refer to them diff --git a/eng/vdd-generation.rst b/eng/vdd-generation.rst index 28b891c..905554b 100644 --- a/eng/vdd-generation.rst +++ b/eng/vdd-generation.rst @@ -7,7 +7,7 @@ Version Description Document (VDD) Generation ********************************************* -TBD - probably Dannie's project +TBD - discuss how generated. Preferably Dannie's project -This URL may be of use but it probably Trac auto-generated and not -useful for this purpose: https://devel.rtems.org/wiki/TracChangeLog +This URL may be of use but it probably Trac auto-generated and can +only be referenced: https://devel.rtems.org/wiki/TracChangeLog -- cgit v1.2.3 From 562d48ca5a5026286732838d2fd929e1473136b3 Mon Sep 17 00:00:00 2001 From: Pritish Jain Date: Sat, 1 Dec 2018 03:29:01 +0530 Subject: test-suites:Convert TBD to rest Format(GCI 2018) --- eng/test-suites.rst | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/eng/test-suites.rst b/eng/test-suites.rst index 1380ee8..4cbe792 100644 --- a/eng/test-suites.rst +++ b/eng/test-suites.rst @@ -6,8 +6,36 @@ Test Suites *********** -TBD - Convert the following to Rest and insert into this file -TBD from https://devel.rtems.org/wiki/Developer/Testing/TestSuites +.. COMMENT:TBD - Convert the following to Rest and insert into this file +.. COMMENT:TBD from https://devel.rtems.org/wiki/Developer/Testing/TestSuites -TBD also update list of tests based on rtems/testsuites +.. COMMENT:TBD also update list of tests based on rtems/testsuites +All RTEMS source distributions include the complete RTEMS test suites. These +tests must be compiled and linked for a specific BSP. Some BSPs are for freely +available simulators and thus anyone may test RTEMS on a simulator. Most of +the BSPs which can execute on a simulator include scripts to help automate +running them. + +The RTEMS Project welcomes additions to the various test suites and sample +application collections. + +The following functional test suites are included with RTEMS. + +* Classic API Single Processor Test Suite +* POSIX API Test Suite +* ITRON API Test Suite +* Support Library Test Suite (libtests) +* Multiprocessing Test Suite +* Classic API Ada95 Binding Test Suite + +The following timing test suites are included with RTEMS. + +* Classic API Timing Test Suite +* ITRON API Timing Test Suite +* The RTEMS source distribution includes three collections of sample applications. + +Sample Applications (built as RTEMS tests) + +* Example Applications (built as RTEMS user applications) +* Network Demonstration Applications -- cgit v1.2.3 From b37605299d9392d471b4d31449b8477e57c352f8 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Sat, 1 Dec 2018 10:08:49 -0600 Subject: eng/test-suites.rst: Update to reflect current reality --- eng/test-suites.rst | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/eng/test-suites.rst b/eng/test-suites.rst index 4cbe792..94cd42e 100644 --- a/eng/test-suites.rst +++ b/eng/test-suites.rst @@ -18,24 +18,42 @@ the BSPs which can execute on a simulator include scripts to help automate running them. The RTEMS Project welcomes additions to the various test suites and sample -application collections. +application collections. This helps improve coverage of functionality as +well as ensure user use cases are regularly tested. The following functional test suites are included with RTEMS. * Classic API Single Processor Test Suite * POSIX API Test Suite -* ITRON API Test Suite +* File System Test Suite * Support Library Test Suite (libtests) -* Multiprocessing Test Suite +* Symmetric Multiprocessing Test Suite +* Distributed Multiprocessing Test Suite * Classic API Ada95 Binding Test Suite The following timing test suites are included with RTEMS. * Classic API Timing Test Suite -* ITRON API Timing Test Suite -* The RTEMS source distribution includes three collections of sample applications. +* POSIX API Timing Test Suite +* Rhealstone Collection +* Benchmarks Collecction -Sample Applications (built as RTEMS tests) +The RTEMS source distribution includes two collections of sample applications. +* Sample Applications (built as RTEMS tests) * Example Applications (built as RTEMS user applications) + +The RTEMS libbsd package includes its own test suite. + +Legacy Test Suites +================== + +The following are available for the legacy IPV4 Network Stack: + * Network Demonstration Applications + +Post RTEMS 4.10, ITRON API support was removed. The following test suites +are only available if the ITRON API support is present in RTEMS. + +* ITRON API Test Suite +* ITRON API Timing Test Suite -- cgit v1.2.3 From 22c60450f564a7aff323038d80f2624ac5a2f25b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=A7al=20Comajoan=20Cara?= Date: Sat, 1 Dec 2018 15:17:11 +0100 Subject: eng/appendix-a: convert to a table Convert text to a table, TBDs into comments and add missing formatting. This work was part of GCI 2018. --- eng/appendix-a.rst | 152 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 104 insertions(+), 48 deletions(-) diff --git a/eng/appendix-a.rst b/eng/appendix-a.rst index 633996b..cfad927 100644 --- a/eng/appendix-a.rst +++ b/eng/appendix-a.rst @@ -8,7 +8,7 @@ Appendix: Core Qualification Artifacts/Documents ************************************************ An effort at NASA has been performed to suggest a core set of artifacts -(as defined by BOTH NASA NPR 7150.2B and DO-178B) that can be utilized +(as defined by **BOTH** NASA NPR 7150.2B and DO-178B) that can be utilized by a mission as a baselined starting point for “pre-qualification” for (open-source) software that is intended to be utilized for flight purposes. This effort analyzed the overlap between NPR 7150.2B @@ -20,60 +20,116 @@ Along with the specific artifact, the intent of the artifact was also captured; in some cases open-source projects, such as RTEMS, are already meeting the intent of the artifacts with information simply needing organized and formalized. The table below lists the general category, -artifact name, and its intent. Please note that this table does NOT +artifact name, and its intent. Please note that this table does **NOT** represent all the required artifacts for qualification per the standards; instead, this table represents a subset of the most basic/core artifacts that form a strong foundation for a software engineering qualification effort. -TBD convert to a table; see original PDF for guidance on desired look -TBD The PDF is in https://ftp.rtems.org/pub/rtems/people/joel/sw_eng_hb/ +.. COMMENT: TBD convert to a table; see original PDF for guidance on desired look +.. COMMENT: TBD The PDF is in https://ftp.rtems.org/pub/rtems/people/joel/sw_eng_hb/ -.. COMMENT: ====================================== BEGIN -Table 1. Core Qualification Artifacts +.. table:: Table 1. Core Qualification Artifacts + :class: rtems-table -Category Artifact Intent -Requirements Software Requirements Specification (SRS) - -Requirements Management The project shall document the software requirements. - -The project shall collect and manage changes to the software requirements. - -The project shall identify, initiate corrective actions, and track until closure inconsistencies among requirements, project plans, and software products. - Requirements Test and Traceability Matrix The project shall perform, document, and maintain bidirectional traceability between the software requirement and the higher-level requirement. - Validation The project shall perform requirements validation to ensure that the software will perform as intended in the customer environment. - - -Design and Implementation Software Development or Management Plan A plan for how you will develop the software that you are intent upon developing and delivering. - -The Software Development Plan includes the objectives, standards and life cycle(s) to be used in the software development process. This plan should include: Standards: Identification of the Software Requirements Standards, Software Design Standards, and Software Code Standards for the project. - - Software Configuration Management Plan To identify and control major software changes, ensure that change is being properly implemented, and report changes to any other personnel or clients who may have an interest. - - Implementation The project shall implement the software design into software code. - -Executable Code to applicable tested software. - - Coding Standards Report The project shall ensure that software coding methods, standards, and/or criteria are adhered to and verified. - Version Description Document (VDD) The project shall provide a Software Version Description document for each software release. - -Testing and Software Assurance Activities Software Test Plan Document describing the testing scope and activities. - Software Assurance/Testing Procedures - To define the techniques, procedures, and methodologies that will be used. - - Software Change Report / Problem Report The project shall regularly hold reviews of software activities, status, and results with the project stakeholders and track issues to resolution. - - Software Schedule Milestones have schedule and schedule is updated accordingly. - - Software Test Report / Verification Results The project shall record, address, and track to closure the results of software verification activities. - -Problem report - Describes the process non-compliance with plans, output deficiency, or software anomalous behavior, and the corrective action taken. - -The project shall ensure that the software code is unit tested per the plans for software testing. - - -Usability Software User’s Manual The Software User Manual defines user instructions for the software. -.. COMMENT: ====================================== END + +----------------+-----------------------+---------------------------------+ + | Category | Artifact | Intent | + +================+=======================+=================================+ + | Requirements | Software Requirements | The project shall document the | + | | Specification (SRS) | software requirements. | + | | | | + | | | The project shall collect and | + | | | manage changes to the software | + | | | requirements. | + | | Requirements | | + | | Management | The project shall identify, | + | | | initiate corrective actions, | + | | | and track until closure | + | | | inconsistencies among | + | | | requirements, project plans, | + | | | and software products. | + | +-----------------------+---------------------------------+ + | | Requirements Test and | The project shall perform, | + | | Traceability Matrix | document, and maintain | + | | | bidirectional traceability | + | | | between the software | + | | | requirement and the | + | | | higher-level requirement. | + | +-----------------------+---------------------------------+ + | | Validation | The project shall perform | + | | | validation to ensure that the | + | | | software will perform as | + | | | intended in the customer | + | | | environment. | + +----------------+-----------------------+---------------------------------+ + | Design and | Software Development | A plan for how you will develop | + | Implementation | or Management Plan | the software that you are | + | | | intent upon developing and | + | | | delivering. | + | | | | + | | | The Software Development Plan | + | | | includes the objectives, | + | | | standards and life cycle(s) to | + | | | be used in the software | + | | | development process. This plan | + | | | should include: Standards: | + | | | Identification of the Software | + | | | Requirements Standards, | + | | | Software Design Standards, | + | | | and Software Code Standards for | + | | | the project. | + | +-----------------------+---------------------------------+ + | | Software | To identify and control major | + | | Configuration | software changes, ensure that | + | | Management Plan | change is being properly | + | | | implemented, and report changes | + | | | to any other personnel or | + | | | clients who may have an | + | | | interest. | + | +-----------------------+---------------------------------+ + | | Implementation | The project shall implement the | + | | | software design into software | + | | | code. | + | | | | + | | | Executable Code to applicable | + | | | tested software. | + | +-----------------------+---------------------------------+ + | | Coding Standards | The project shall ensure that | + | | Report | software coding methods, | + | | | standards, and/or criteria are | + | | | adhered to and verified. | + | +-----------------------+---------------------------------+ + | | Version Description | The project shall provide a | + | | Document (VDD) | Software Version Description | + | | | document for each software | + | | | release. | + +----------------+-----------------------+---------------------------------+ + | Testing and | Software Test Plan | Document describing the testing | + | Software | | scope and activities. | + | Assurance +-----------------------+---------------------------------+ + | Activities | Software | To define the techniques, | + | | Assurance/Testing | procedures, and methodologies | + | | Procedures | that will be used. | + | +-----------------------+---------------------------------+ + | | Software Change | The project shall regularly | + | | Report / Problem | hold reviews of software | + | | Report | activities, status, and results | + | | | with the project stakeholders | + | | | and track issues to resolution. | + | +-----------------------+---------------------------------+ + | | Software Schedule | Milestones have schedule and | + | | | schedule is updated | + | | | accordingly. | + | +-----------------------+---------------------------------+ + | | Software Test | The project shall record, | + | | Report / Verification | address, and track to closure | + | | Results | the results of software | + | | | verification activities. | + +----------------+-----------------------+---------------------------------+ + | Usability | Software User’s | The Software User Manual | + | | Manual | defines user instructions for | + | | | the software. | + +----------------+-----------------------+---------------------------------+ In an effort to remain lightweight and sustainable for open-source projects, Table 1 above was condensed into a single artifact outline -- cgit v1.2.3 From 08ad7e768dc2f3444f68bb86278467c89620dcd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=A7al=20Comajoan=20Cara?= Date: Sat, 1 Dec 2018 18:11:15 +0100 Subject: eng/coding-80cols: Convert wiki page to Rest Converted https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line to Rest, and TBDs into comments. This work was part of GCI 2018. --- eng/coding-80cols.rst | 148 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 146 insertions(+), 2 deletions(-) diff --git a/eng/coding-80cols.rst b/eng/coding-80cols.rst index 442a9e0..8fbe10d 100644 --- a/eng/coding-80cols.rst +++ b/eng/coding-80cols.rst @@ -6,5 +6,149 @@ Eighty Character Line Limit *************************** -TBD - Convert the following to Rest and insert into this file -TBD - https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line +.. COMMENT: TBD - Convert the following to Rest and insert into this file +.. COMMENT: TBD - https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line + + Code should look good for everyone under some standard width assumptions. + Where a line wraps should be the same for anyone reading the code. For + historical reasons, RTEMS uses 80 characters as the maximum width for each + line of code. + +If you find yourself with code longer than 80 characters, first ask yourself +whether the nesting level is too deep, names too long, compound expressions too +complicated, or if some other guideline for improving readability can help to +shrink the line length. Refactoring nested blocks into functions can help to +alleviate code width problems while improving code readability. Making names +descriptive yet terse can also improve readability. If absolutely necessary +to have a long line, follow the rules on this page to break the line up to adhere +to the 80 characters per line rule. + +Breaking long lines +------------------- + +``if``, ``while``, and ``for`` loops have their condition expressions aligned +and broken on separate lines. When the conditions have to be broken, none go on +the first line with the ``if``, ``while``, or ``for`` statement, and none go on +the last line with the closing parenthesis and (optional) curly brace. Long +statements are broken up and indented at operators, with an operator always +being the last token on a line. No blank spaces should be left at the end of +any line. Here is an example with a ``for`` loop. + +.. code-block:: c + + for ( initialization = statement; a + really + long + statement + that + evaluates + to < a + boolean; another + statement++ ) { + z = a + really + long + statement + that + needs + two + lines + gets + indented + four + more + spaces + on + the + second + and + subsequent + lines + and + broken + up + at + operators; + } + +Should be replaced with + +.. code-block:: c + + for ( + initialization = statement; + a + really + long + statement + that + evaluates + to < + a + boolean; + another + statement++ + ) { + z = a + really + long + statement + that + needs + + two + lines + gets + indented + four + more + + spaces + on + the + second + and + subsequent + + lines + and + broken + up + at + operators; + } + +Note that indentations should add 2 nesting levels (4 space characters, not tabs). + +Similarly, + +.. code-block:: c + + if ( this + that < those && this + these < that && this + those < these && this < those && those < that ) { + +should be broken up like + +.. code-block:: c + + if ( + this + that < those && + this + these < that && + this + those < these && + this < those && + those < that + ) { + +Note that each expression that resolves to a boolean goes on its own line. +Where you place the boolean operator is a matter of choice. + +When a line is long because of a comment at the end, move the comment to +just before the line, for example + +.. code-block:: c + + #define A_LONG_MACRO_NAME (AND + EXPANSION) /* Plus + a + really + long + comment */ + +can be replaced with + +.. code-block:: c + + /* Plus + a + really + long + comment */ + #define A_LONG_MACRO_NAME (AND + EXPANSION) + +C Preprocessor macros need to be broken up with some care, because the +preprocessor does not understand that it should eat newline characters. So + +.. code-block:: c + + #define A_LONG_MACRO_NAME (AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + DEFINED) + +would become + +.. code-block:: c + + #define A_LONG_MACRO_NAME ( \ + AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + \ + DEFINED \ + ) + +Notice that each line is terminated by a backslash then the carriage return. +The backslash tells the preprocessor to eat the newline. Of course, if you have +such a long macro, you should consider not using a macro. + +Function declarations can be broken up at each argument, for example + +.. code-block:: c + + int this_is_a_function( int arg1, int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8, int arg9 ); + +would be broken up as + +.. code-block:: c + + int this_is_a_function( + int arg1, + int arg2, + int arg3, + int arg4, + int arg5, + int arg6, + int arg7, + int arg8, + int arg9 + ); + +Excessively long comments should be broken up at a word boundary or somewhere +that makes sense, for example + +.. code-block:: c + + /* Excessively long comments should be broken up at a word boundary or somewhere that makes sense, for example */ + +would be + +.. code-block:: c + + /* Excessively long comments should be broken up at a word boundary or + * somewhere that makes sense, for example */ + +Note that multiline comments have a single asterisk aligned with the asterisk +in the opening ``/*``. The closing ``*/`` should go at the end of the last +line. -- cgit v1.2.3 From 2ba3735555d4516d302785a2780f467be33b28ea Mon Sep 17 00:00:00 2001 From: Pritish Jain Date: Sat, 1 Dec 2018 14:57:48 +0530 Subject: coding-gen-patch:Convert TBD to rest Format(GCI 2018) --- eng/coding-gen-patch.rst | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/eng/coding-gen-patch.rst b/eng/coding-gen-patch.rst index d4e05da..8e19abe 100644 --- a/eng/coding-gen-patch.rst +++ b/eng/coding-gen-patch.rst @@ -6,5 +6,22 @@ Generating a Tools Patch ************************ -TBD - Convert the following to Rest and insert into this file -TBD - https://devel.rtems.org/wiki/Developer/Coding/GenerateAPatch +.. COMMENT:TBD - Convert the following to Rest and insert into this file +.. COMMENT:TBD - https://devel.rtems.org/wiki/Developer/Coding/GenerateAPatch + +The RTEMS patches to the development tools are generated using a command like this + +.. code block:: shell + diff -N -P -r -c TOOL-original-image TOOL-with-changes >PATCHFILE + +where the options are: + +* -N and -P take care of adding and removing files (be careful not to +include junk files like file.mybackup) + +* -r tells diff to recurse through subdirectories +* -c is a context diff (easy to read for humans) +* -u is a unified diff (easy for patch to apply) +Please look at the generated PATCHFILE and make sure it does not contain anything you did not intend to send to the maintainers. It is easy to accidentally leave a backup file in the modified source tree or have a spurious change that should not be in the PATCHFILE. + +If you end up with the entire contents of a file in the patch and can't figure out why, you may have different CR/LF scheme in the two source files. The GNU open-source packages usually have UNIX style CR/LF. If you edit on a Windows platform, the line terminators may have been transformed by the editor into Windows style. -- cgit v1.2.3 From cb9bdb01c7188b273def3f6a64d9344b95fccb16 Mon Sep 17 00:00:00 2001 From: Pritish Jain Date: Sun, 2 Dec 2018 14:14:29 +0530 Subject: coding-doxygen-bsp: Convert TBD to rest Format(GCI 2018) --- eng/coding-doxygen-bsp.rst | 388 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 384 insertions(+), 4 deletions(-) diff --git a/eng/coding-doxygen-bsp.rst b/eng/coding-doxygen-bsp.rst index e6f73d0..752dad9 100644 --- a/eng/coding-doxygen-bsp.rst +++ b/eng/coding-doxygen-bsp.rst @@ -3,8 +3,388 @@ .. COMMENT: COPYRIGHT (c) 2018. .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project -BSP Doxygen Recommentations -=========================== -TBD - Convert the following to Rest and insert into this file -TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen_for_BSPs +.. COMMENT:TBD - Convert the following to Rest and insert into this file +.. COMMENT:TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen_for_BSPs + + +Doxygen Recommendations for BSPs +================================================== + +RTEMS contains well over a hundred `Board Support Packages (BSPs) `_. , across over 20 different `CPU Architectures `_. . What this means is that there is a lot of hardware dependent code that gets written, and that adding Doxygen to properly document it all can be a very complicated task. + +The goal of this document is to attempt to simplify this process a bit, and to get you started on adding Doxygen to the bsps/ directory in a way that is logical and has structure. Before we move on to detailing the process of actually adding Doxygen to BSPs, you will be greatly served by having at least a basic understanding of the purpose of a Board Support Package (it always helps to know a bit about what you're documenting), as well as of the existing structure of the bsps/ directory. + +Feel free to skip around and skim parts of this. + +BSP Basics +================================================= + +Embedded development is hard. Different CPUs have different instructions for doing the same thing, and different boards will have all sorts of different hardware that require unique drivers and interfaces. RTEMS handles this by having discrete packages, BSPs, to encapsulate code to accommodate for unique hardware. BSPs seek to implement the Hardware-Software interface. This, in a nutshell, is one of the `core purposes `_. of RTEMS: To abstract (as much as is possible) away from the physical hardware and provide a standards compliant real-time environment for the embedded developer. If you think about it, the operating system on your normal computer serves a very similar purpose. + +Common Features Found In BSPs +============================================= +Although the actual implementation code will differ between BSPs, all BSPs will share some degree of common functionality. This is because that no matter what exact hardware you have, you need some basic features implemented in order to have a real time system you can develop on. Some of the most common shared features across most boards include: + + * **console**: is technically the serial driver for the BSP rather than just a console driver, it deals with the board UART (i.e. serial devices) + * **clock**: support for the clock tick - a regular time basis for the kernel + * **timer**: support of timer devices, used for timing tests + * **rtc** or **tod**: support for the hardware real time clock + * **network**: the Ethernet driver + * **shmsupp**: support of shared memory driver MPCI layer in a multiprocessor system + * **gnatsupp**: BSP specific support for the GNU Ada run-time + * **irq**: support for how the processor handles interrupts (probably the most common module shared by all boards) + * **tm27**: specific routines for the tm27 timing test + * **start** and **startup**: c and assembly used to initialize the board during startups/resets/reboots + +These are just some of the things you should be looking for when adding Doxygen to a BSP. + +Note that there is no guarantee a particular BSP will implement all of these features, or even some of them. These are just the most common ones to look for. RTEMS follows a standardized naming convention for the BSP sub directories, so you should be able to tell in most cases what has been implemented on the BSP level and what has not. + +Shared Features +==================================================== + +Some of the RTEMS executive is hardware independent and can be abstracted so that the same piece of code can be shared across multiple CPU architectures, or across multiple boards on the same architecture. This is done so that chunks of software can be reused, as well as aiding in reducing the development and debugging time for implementing new BSPs. This greatly aids the developer, but as someone seeking to document this code, this can make your life a little bit harder. It is hard to tell by looking at the directory of a BSP which features have simply been left out and which features are being implemented by using shared code from either from the architecture (../shared) or the base bsps/ shared directory (../../shared). You may be looking at the BSP headers and notice that you have an irq.h, but no irq.c implementing it, or you might even be missing both. You know that the processor has interrupt support somehow, but where is it? The easiest way to figure this out is by looking at the Makefile.am for a BSP. We'll detail this process more in a bit. + +Rationale +======================================================= + +As someone adding documentation and not doing actual development work, you might think it is not necessary to know some of the in and outs of BSPs. In actuality, this information will prove to be very useful. Doxygen documentation works by grouping things and their components (i.e. functions and other definitions), and by having brief descriptions of what each group does. You can't know what to look for or know how to group it or know how to describe it without some basic knowledge of what a BSP is. For more information on any of the above or BSPs in general, check out the `BSP Development Guide `_. . + +The Structure of the bsps/ directory +=================================================== + +All BSPs are found within the bsps/ directory, which is itself very well ordered. At the first level, we find a directory for each CPU architecture RTEMS supports, as well as a directory for code shared by all implementations. + +.. code block:: shell +$ cd bsps +$ ls +arm bsp.am lm32 m68k mips no_cpu README sparc +avr h8300 m32c Makefile.am moxie powerpc sh sparc64 +bfin i386 m32r MERGE.PROCEDURE nios2 preinstall.am shared v850 + + +If we cd into a specific architecture, we see that a similar structure is employed. bsps/arm/ contains directories for each Board Support Package for boards with an ARM cpu, along with a folder for files and .h's shared by all BSPs of that architecture. + +.. code block:: shell +$ cd arm +$ ls +acinclude.m4 edb7312 gumstix Makefile.am realview-pbx-a9 stm32f4 +configure.ac gba lm3s69xx nds rtl22xx xilinx-zynq +csb336 gdbarmsim lpc24xx preinstall.am shared +csb337 gp32 lpc32xx raspberrypi smdk2410 + + +Finally, if we cd into a specific BSP, we see the files and .h's that compose the package for that particular board. You may recognize the directory names as some of the [common features] we outlined above, like '''irq''', '''clock''', '''console''', and '''startup'''. These directories contain implementations of these features. + +.. code block:: shell +$ cd raspberrypi +$ ls +bsp_specs configure.ac include make misc README +clock console irq Makefile.am preinstall.am startup + + +Another way to get an idea of the structure of bsps/ is to navigate to a directory and execute the "tree -f" command. This outputs a nice graphic that conveys some of the hierarchical properties of a particular directory. + +.. code block:: shell +$ pwd +~/rtems/bsps/arm/raspberrypi +$ tree -f +. +|-- ./bsp_specs +|-- ./clock +| `-- ./clock/clockdrv.c +|-- ./configure.ac +|-- ./console +| |-- ./console/console-config.c +| `-- ./console/usart.c +|-- ./include +| |-- ./include/bsp.h +| |-- ./include/irq.h +| |-- ./include/mmu.h +| |-- ./include/raspberrypi.h +| `-- ./include/usart.h +|-- ./irq +| `-- ./irq/irq.c +|-- ./make +| `-- ./make/custom +| `-- ./make/custom/raspberrypi.cfg +|-- ./Makefile.am +|-- ./misc +| `-- ./misc/timer.c +|-- ./preinstall.am +|-- ./README +`-- ./startup + |-- ./startup/bspreset.c + |-- ./startup/bspstart.c + |-- ./startup/bspstarthooks.c + |-- ./startup/linkcmds + `-- ./startup/mm_config_table.c + + + +In short, BSPs will use the following directories: + * bsps/**shared** <- code used that is shared by all BSPs + * bsps/**CPU**/**shared** <- code used shared by all BSPs of a particular CPU architecture + * bsps/**CPU**/**BSP** <- code unique to this BSP + +As you can see, the bsps/ directory has a very logical and easy to understand structure to it. The documentation generated by Doxygen should attempt to match this structure as closely as possible. We want an overarching parent group to serve the same purpose as the bsps/ directory. In it, we want groups for each CPU architecture and a group for the shared files. We then want groups for each BSP. Breaking our documentation up into discrete groups like this will greatly simplify the process and make the documentation much easier to go through. By learning about the existing structure of the bsps/ directory, we get an idea of how we should structure the Doxygen groups we create. More on this in the next section. + +Doxygen +============================ +Now that we have covered some of the preliminaries, we can move on to what you are actually reading this wiki page for: adding Doxygen to the bsps/ directory. Let's start with some Doxygen basics. Skip this if you are already comfortable with Doxygen. + +In addition to this, check out the page on `Doxygen Recommendations `_. , which also contains a fair amount of information that will not be covered here. + +Doxygen Basics +===================================================== + +Doxygen is a documentation generator. It allows for documentation to be written right by the source code, greatly easing the pains of keeping documentation relevant and up to date. Doxygen has many commands, used for things like annotating functions with descriptions, parameter information, or return value information. You can reference other files or even other documentation. + +The core component of Doxygen (that we care about right now at least) is what's called a **group**, or **module**. These are used to add structure and associate groups of files that serve a similar purpose or implement the same thing. + +Doxygen Headers +===================================== +Doxygen is always found in a special Doxygen comment block, known as a **Doxygen header**. In RTEMS, this block comes in the form of a multiline comment with some included Doxygen commands, which are preceded by the '@' tag. Take a look at this Doxygen header that declares the arm_raspberrypi module, which houses the documentation in the BSP for the Raspberry Pi. + +.. code block:: shell +bsps/arm/raspberrypi/include/bsp.h: + +/** + * @defgroup arm_raspberrypi Raspberry Pi Support + * + * @ingroup bsp_arm + * + * @brief Raspberry Pi support package + * + */ + + + +You see a few commands here that we'll cover in the following sections. Briefly, the @defgroup command declares a new group, the @ingroup command nests this group as a submodule of some other group (in this case bsp_arm), and the @brief command provides a brief description of what this group is. + + The @defgroup Command +========================================== + +The @defgroup command is used to declare new groups or modules. Think "define group". The syntax of this command is as follows: + +.. code block:: shell +@defgroup + + +The group name is the name used by Doxygen elsewhere to reference this group. The group description is what is displayed when the end user navigates to this module in the resulting documentation. The group description is a couple words formatted as how it would be in a table of contents. This part is what actually shows up in the documentation, when the user navigates to this group's module, this description will be the modules name. + +Groups should only be declared (@defgroup) in .h files. This is because Doxygen is used primarily to document interfaces, which are only found in .h files. Placing @defgroups in .h files is the only real restriction. Which .h file you place the group declaration in surprisingly doesn't matter. There is no information in the resulting documentation that indicates where the group was declared. You will see that we do have some rules for where you should place these declarations, but we also use this fact that it doesn't matter to our advantage, in order to standardize things. + +The @defgroup command is used only to define ''structure''. No actual documentation is generated as a result of its use. We must @ingroup things to the group we declare in order to create documentation. Even though it does not generate visible documentation, the @defgroup command is still very important. We use it in a way that seeks to emulate the structure of the bsps/ directory itself. We do this by creating a hierarchy of groups for each CPU architecture and each BSP. + +The @ingroup Command +============================================= + +The @ingroup command is used to add 'things' to already declared groups or modules. These 'things' can either be other groups, or files themselves. The syntax of the @ingroup command is as follows: + +.. code block:: shell +@ingroup + + +The group name is the actual name, not description, of the group you want to add yourself to. Remember that group name was the second argument passed to the @defgroup command. + +Using the @ingroup command is how we add ''meaning'' to the ''structure'' created by using @defgroup. @ingroup associates the file it is found in and all other Doxygen found within (function annotations, prototypes, etc) with the group we declared with the @defgroup command. We add related files and headers to the same groups to create a logical and cohesive body of documentation. If the end user wanted to read documentation about how the raspberry pi handles interrupts, all they would have to do would be to navigate to the raspberry pi's interrupt support module (which we created with a @defgroup command), and read the documentation contained within (which we added with @ingroup commands). + +@ingroup is found within all Doxygen headers, along with an @brief statement. There are two types of Doxygen headers, which we will go over after we see a description of the @brief command. + + The @brief Command +===================================================== + +The @brief command is used to give either a) a brief description in the form of an entry as you would see it in a table of contents (i.e. Capitalized, only a couple of words) or b) a brief topic sentence giving a basic idea of what the group does. The reason you have two uses for the brief command is that it is used differently in the two types of Doxygen headers, as we will see shortly. The syntax of the brief command is self evident, but included for the sake of completion: + +.. code block:: shell +@brief + + +The Two Types of Doxygen Headers +================================================= + +There are two types of Doxygen Headers. The first type is found at the beginning of a file, and contains an @file command. This type of header is used when @ingroup-ing the file into another doxygen group. The form of the @brief command in this case is a topic sentence, often very close to the file name or one of it's major functions. An example of this type of header, found in bsps/arm/raspberrypi/include/bsp.h is as follows: + +.. code block:: shell +Header type 1: used to add files to groups, always found at the beginning of a file +/** + * @file + * + * @ingroup raspberrypi + * + * @brief Global BSP definitions. + */ + +/* + * Copyright (c) 2013 Alan Cudmore + * +... + + +Notice the form and placement of this type of header. It is always found at the beginning of a file, and is in its own multiline comment block, separated by one line white space from the copyright. If you look at the header itself, you see a @file, @ingroup, and @brief command. Consider the @file and the @ingroup together, what this says is that we are adding this file to the raspberrypi group. There is actually a single argument to the @file command, but Doxygen can infer it, so we leave it out. Any other Doxygen, function annotations, function prototypes, #defines, and other code included in the file will now be visible and documented when the end user navigates to the group you added it to in the resulting documentation. + +Now let's consider the second type of header. This type is syntactically very similar, but is used not to add files to groups, but to add groups to other groups. We use this type of header to define new groups and nest them within old groups. This is how we create hierarchy and structure within Doxygen. The following is found, again, in bsps/arm/raspberrypi/include/bsp.h: + +.. code block:: shell +Header type 2: Used to nest groups, found anywhere within a file +/** + * @defgroup arm_raspberrypi Raspberry Pi Support + * + * @ingroup bsp_arm + * + * @brief Raspberry Pi Support Package + */ + + +It looks very similar to the first type of header, but notice that the @file command is replaced with the @defgroup command. You can think about it in the same way though. Here we are creating a new group, the arm_raspberry pi group, and nesting it within the bsp_arm group. The @brief in this case should be in the form of how you would see it in a table of contents. Words should be capitalized and there should be no period. This type of header can be found anywhere in a file, but it is typically found either in the middle before the file's main function, or at the tail end of a file. Recall that as we are using the @defgroup command and creating a new group in this header, the actual .h we place this in does not matter. + +The second type of header is the **structure** header, it's how we create new groups and implement hierarchy. The first type of header was the **meaning** header, it's how we added information to the groups we created. + +For more examples of Doxygen structure and syntax, refer to BSPs found within the arm architecture, the lpc32xx and raspberrypi BSPs are particularly well documented. A good way to quickly learn more is by tweaking some Doxygen in a file, then regenerating the html, and seeing what has changed. + +Generating Documentation +==================================================== + +Doxygen is a documentation generator, and as such, we must generate the actual html documentation to see the results of our work. This is a very good way to check your work, and see if the resulting structure and organization was what you had intended. The best way to do this is to simply run the `do_doxygen script `_. . To use the script: + +Make sure Doxygen is installed. Also, the environment needs to have the root directory of RTEMS set in the variable `r` so that `$r` prints the path to RTEMS, and the script takes as argument a relative directory from there to generate the doxygen, for example to generate the doxygen for all of bsps/ you would do: + +.. code block:: shell +export r=~/rtems +./do_doxygen bsps + + +Doxygen in bsps/ +================================================== + +Now that we've covered the basics of Doxygen, the basics of BSPs and the structure of the bsps/ directory, actually adding new Doxygen to bsps/ will be much easier than it was before. We will cover a set of rules and conventions that you should follow when adding Doxygen to this directory, and include some tips and tricks. + + Group Naming Conventions +=================================================== + +This is an easy one. These are in place in order for you to quickly identify some of the structure of the Doxygen groups and nested groups, without actually generating and looking at the documentation. The basic idea is this: when defining a new group (@defgroup), the form of the name should be the super group, or the name of the group you are nesting this group within, followed by an underscore, followed by the intended name of this new group. In command form: + +.. code block:: shell + <----- This is your group name -------> <--usual description --> +@defgroup _ + + +Some examples of this: + * **bsp_arm**: This is the group for the arm architecture. It is a member of the all inclusive bsp-kit group (more on this in structure conventions), so we prefix it with the "**bsp**" super group name. This is the group for the arm architecture, so the rest is just "'''arm'''" + * **arm_raspberrypi**: This is the group for the Raspberry Pi BSP. It is is an arm board, and as such, is nested within the bsp_arm group. We prefix the group name with an "**arm**" (notice we drop the bsp prefix of the arm group - we only care about the immediate super group), and the rest is a simple "'''raspberrypi'''", indicating this is the raspberrypi group, which is nested within the bsp_arm group. + * **raspberrypi_interrupt** This is the group for code handling interrupts on the Raspberry Pi platform. Because this code and the group that envelops it is Raspberry Pi dependent, we prefix our name with a "**raspberrypi**", indicating this group is nested within the raspberrypi group.= Structure Conventions = + +This covers where, when, and why you should place the second type of Doxygen header. Remember that our goal is to have the structure of the documentation to match the organization of the bsps/ directory as closely as possible. We accomplish this by creating groups for each cpu architecture, each BSP, and each shared directory. These groups are nested as appropriate in order to achieve a hierarchy similar to that of bsps/. The arm_raspberrypi group would be nested within the bsp_arm group, for example. + + Where to place @defgroup +===================================================== + +Remember how I said it really doesn't matter where you place the @defgroup? Well, it does and it doesn't. It would be chaotic to place these anywhere, and almost impossible to tell when you have a @defgroup and when you don't, so we do have some rules in place to guide where you should place these. + + @defgroups for CPU Architectures and Shared Directories +============================================================================== + +The standardized place for these is within a special doxygen.h file placed within the particular architectures shared directory. This doxygen.h file exists solely for this purpose, to provide a standard place to house the group definitions for CPU architectures and the shared directory for that architecture. This is done because there is no single file that all architectures share, so it would be impossible to declare a standardized location for architecture declarations without the creation of a new file. This also allows others to quickly determine if the group for a particular architecture has already been defined or not. Lets look at the doxygen.h for the arm architecture as an example, found at arm/shared/doxygen.h: + +.. code block:: shell + /** + * @defgroup bsp_arm ARM + * + * @ingroup bsp_kit + * + * @brief ARM Board Support Packages + */ + + /** + * @defgroup arm_shared ARM Shared Modules + * + * @ingroup bsp_arm + * + * @brief ARM Shared Modules + */ + + + +The doxygen.h contains only 2 Doxygen headers, both of which are of the second type. One header is used to create the groups for the arm architecture **bsp_arm**, nesting it as part of the bsp_kit group, and the other creates an **arm_shared** group to house the code that is shared across all BSPs of this architecture. Because these are the second type of Doxygen header, where we place them does not matter. This allows us to place them in a standard doxygen.h file, and the end user is non the wiser. Note that this .h file should never be included by a .c file, and that the only group declarations that should be placed here are the declarations for the CPU Architecture group and the shared group. + +There is also a doxygen.h file that exists at the root bsps/shared directory, to @defgroup the the parent **bsp_kit** group (the only group to not be nested within any other groups) and to @defgroup the **bsp_shared** group, to serve as the holder for the bsps/shared directory. + +If the architecture in which the BSP you are tasked with does not have one of these files already, you will need to copy the format of the file here, replacing the **arm** with whatever the CPU Architecture you are working with is. Name this file doxygen.h, and place it in the shared directory for that architecture. + +The only groups you should ever add to this CPU group would be groups for specific BSPs and a group for the shared directory. + +@defgroups for BSPs +======================================= + +These are much easier than placing @defgroups for CPU Architectures. The overwhelming majority of the time, the @defgroup for a BSP is found within the bsp.h file found at '''''bsp'''''/include/bsp.h. It is usually placed midway through or towards the end of the file. In the event that your board lacks a bsp.h file, include this group declaration within the most standard or commonly included header for that BSP. + +The group for a BSP should **always** be nested within the group for the CPU architecture it uses. This means that the Doxygen header for defining a BSP group should always look something like this: + +.. code block:: shell + /** + * @defgroup *architecture*_*BSP* *name* + * + * @ingroup bsp_*architecture* + * + * @brief *BSP* Support Package + */ + + + @defgroups for Everything Else +====================================================== + +Never be afraid to add more structure! Once the basic CPU and BSP group hierarchy is established, what we're left with is all the sub directories and implementation code. Whether working within a shared directory for a CPU architecture, or within a BSP directory, you should always be looking for associations you can make to group files together by. Your goal should be to avoid @ingroup-ing files directly to the cpu_shared group and the cpu_bsp group as much as possible, you want to find more groups you can nest within these groups, and then @ingroup files to those groups. Here are some things to look for: + +==== Look Common Features Implemented +=================================================== + +Remember that list of common features outlined in the BSP Basics section? Find the .h's that are responsible for providing the interface for these features, and @defgroup a group to @ingroup the files responsible for implementing this feature. + +RTEMS has a naming convention for its BSP sub directories, so it should be a really quick and easy process to determine what features are there and what is missing. + +Examples of this are found within the **arm_raspberrypi** group, which contains nested subgroups like **raspberry_interrupt** to group files responsible for handling interrupts, **raspberrypi_usart** to group files responsible for implementing USART support, and many other subgroups. + +==== Check out the Makefile +=============================================== + +When working within a BSP, take a look at the Makefile.am. Often times, you will find that the original developer of the code has outlined the groups nicely for you already, with comments and titles before including source files to be built. Also, this is often the only way to tell which features a BSP simply does not implement, and which features a BSP borrows from either the architecture's shared group, or the bsps/ shared group. + +==== Start with a .h, and look for files that include it +============================================================= + +You should end up with a @defgroup for ''most'' .h files. Some .h files are related and will not have independent groups, but most provide interfaces for different features and should have their own group defined. Declare a group for the header, then use cscope to find the files that include this header, and try to determine where the implementation code for prototypes are found. These are the files you should @ingroup. + +==== Files with similar names +=============================================== + +If you see that a few files have similar names, like they are all prefixed with the same characters, then these files should most likely be part of the same group. + +Remember, your goal is to @defgroup as much as you can. The only files you should be @ingroup-ing directly to the BSP group or the shared group are files that don't cleanly fit into any other group. + +Where to place @ingroup +============================================= + +The @ingroups you add should make sense. + + * If you are working within an architecture's shared directory, @ingroup should be adding things either to the *architecture*_shared group, or some sub group of it. + * If you are working within a BSP directory, @ingroup should be adding things to either the *architecture_*bsp* group, or some sub group of it. + + @ingroup in the first type of Doxygen Header +======================================================== + +Remember that in the first type of Doxygen header, we are adding files to groups. This type of header should always be at the top of the file. You should be adding files that are associated in some way to the same groups. That is to say, if three different .h files provide an interface allowing interrupt support, they should be a part of the same group. Some good ways to associate files were outlined above. + + @ingroup in the second type of Doxygen Header === +================================================================== +Here we are using the @ingroup command to add groups to other groups, creating a hierarchy. The goal for bsps/ is to have one single group that holds all other groups. This root group is the **bsp_kit** group. All groups should be added either directly to this group (if you are creating an architecture group) or added to one of its sub groups. + +When nesting groups, try to match the structure of bsps/ as closely as possible. For example, if a group is defined to associate all files that provide for a real time clock for the raspberrypi, nest it within the arm_raspberrypi group. + +@ingroup for shared code +================================================ + +This is tricky. You may end up in a situation where your BSP uses code found in either the architecture shared directory, or the bsps/shared directory. Even though this code is logically associated with the BSP, as stated above: all files in the shared directory should be added to either the *architecture*_shared group, or some subgroup of it ''not'' the BSP group. You could make a note under the @brief line in the header (which shows up in the resulting documentation) that a particular BSP uses this code. + +When working with shared code, you should be careful and add notes to @brief to indicate that it is a shared code or interface. Prefixing things with "Generic" is a good idea here. You will still be able to form groups and associate things when working on the shared level, but sometimes you will find that you have the interface (.h) to @defgroup, but not many files to add to the group as it may be hardware dependent. This is okay. -- cgit v1.2.3 From 15194924f0f948af5e5d503ec9662410cc97a753 Mon Sep 17 00:00:00 2001 From: Pritish Jain Date: Sun, 2 Dec 2018 01:46:35 +0530 Subject: coding-file-hdr: Convert TBD to Rest Format (GCI 2018) --- eng/coding-file-hdr.rst | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst index 67c177f..23e5db0 100644 --- a/eng/coding-file-hdr.rst +++ b/eng/coding-file-hdr.rst @@ -3,8 +3,38 @@ .. COMMENT: COPYRIGHT (c) 2018. .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +.. COMMENT:TBD - Convert the following to Rest and insert into this file +.. COMMENT:TBD - https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header + + Boilerplate File Header -*********************** +========================================== + + +Every file should include two comment header blocks, one for the Doxygen output and a copyright notice. This is a typical example: + +.. code block:: shell +/** + * @file + * + * @ingroup TheGroupForThisFile + * + * @brief Short "Table of Contents" Description of File Contents + * + * A short description of the purpose of this file. + */ + +/* + * Copyright (c) 20XX Your Name Or Your Company. + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * https://www.rtems.org/license/LICENSE. + */ + + -TBD - Convert the following to Rest and insert into this file -TBD - https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header + * Use exactly one blank line between the Doxygen header and copyright notice. Leave the first line of the copyright notice blank. + * Separate the Doxygen header and copyright notice so the copyright notice is not included in the Doxygen output. + * The copyright owner and specific license terms may vary. -- cgit v1.2.3 From aed8d278a14664af623079652acb1d5dd632b0be Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Sun, 2 Dec 2018 11:29:33 -0600 Subject: coding-doxygen-bsp.rst, coding-file-hdr.rst: Fix formatting --- eng/coding-doxygen-bsp.rst | 917 ++++++++++++++++++++++++++++++--------------- eng/coding-file-hdr.rst | 55 +-- 2 files changed, 651 insertions(+), 321 deletions(-) diff --git a/eng/coding-doxygen-bsp.rst b/eng/coding-doxygen-bsp.rst index 752dad9..2ea82fd 100644 --- a/eng/coding-doxygen-bsp.rst +++ b/eng/coding-doxygen-bsp.rst @@ -9,382 +9,709 @@ Doxygen Recommendations for BSPs -================================================== - -RTEMS contains well over a hundred `Board Support Packages (BSPs) `_. , across over 20 different `CPU Architectures `_. . What this means is that there is a lot of hardware dependent code that gets written, and that adding Doxygen to properly document it all can be a very complicated task. - -The goal of this document is to attempt to simplify this process a bit, and to get you started on adding Doxygen to the bsps/ directory in a way that is logical and has structure. Before we move on to detailing the process of actually adding Doxygen to BSPs, you will be greatly served by having at least a basic understanding of the purpose of a Board Support Package (it always helps to know a bit about what you're documenting), as well as of the existing structure of the bsps/ directory. +================================ + +RTEMS contains well over a hundred `Board Support Packages (BSPs) +`_. , across over 20 different +`CPU Architectures `_. . What this +means is that there is a lot of hardware dependent code that gets +written, and that adding Doxygen to properly document it all can be a +very complicated task. + +The goal of this document is to attempt to simplify this process a bit, +and to get you started on adding Doxygen to the bsps/ directory in a way +that is logical and has structure. Before we move on to detailing the +process of actually adding Doxygen to BSPs, you will be greatly served by +having at least a basic understanding of the purpose of a Board Support +Package (it always helps to know a bit about what you're documenting), +as well as of the existing structure of the bsps/ directory. Feel free to skip around and skim parts of this. BSP Basics -================================================= - -Embedded development is hard. Different CPUs have different instructions for doing the same thing, and different boards will have all sorts of different hardware that require unique drivers and interfaces. RTEMS handles this by having discrete packages, BSPs, to encapsulate code to accommodate for unique hardware. BSPs seek to implement the Hardware-Software interface. This, in a nutshell, is one of the `core purposes `_. of RTEMS: To abstract (as much as is possible) away from the physical hardware and provide a standards compliant real-time environment for the embedded developer. If you think about it, the operating system on your normal computer serves a very similar purpose. +---------- + +Embedded development is hard. Different CPUs have different instructions +for doing the same thing, and different boards will have all sorts of +different hardware that require unique drivers and interfaces. RTEMS +handles this by having discrete packages, BSPs, to encapsulate +code to accommodate for unique hardware. BSPs seek to implement the +Hardware-Software interface. This, in a nutshell, is one of the `core +purposes `_. of RTEMS: To abstract (as much as +is possible) away from the physical hardware and provide a standards +compliant real-time environment for the embedded developer. If you think +about it, the operating system on your normal computer serves a very +similar purpose. Common Features Found In BSPs -============================================= -Although the actual implementation code will differ between BSPs, all BSPs will share some degree of common functionality. This is because that no matter what exact hardware you have, you need some basic features implemented in order to have a real time system you can develop on. Some of the most common shared features across most boards include: +----------------------------- - * **console**: is technically the serial driver for the BSP rather than just a console driver, it deals with the board UART (i.e. serial devices) +Although the actual implementation code will differ between BSPs, all +BSPs will share some degree of common functionality. This is because +that no matter what exact hardware you have, you need some basic features +implemented in order to have a real time system you can develop on. Some +of the most common shared features across most boards include: + + * **console**: is technically the serial driver for the BSP rather than + just a console driver, it deals with the board UART (i.e. serial devices) * **clock**: support for the clock tick - a regular time basis for the kernel * **timer**: support of timer devices, used for timing tests * **rtc** or **tod**: support for the hardware real time clock * **network**: the Ethernet driver - * **shmsupp**: support of shared memory driver MPCI layer in a multiprocessor system + * **shmsupp**: support of shared memory driver MPCI layer in a + multiprocessor system * **gnatsupp**: BSP specific support for the GNU Ada run-time - * **irq**: support for how the processor handles interrupts (probably the most common module shared by all boards) + * **irq**: support for how the processor handles interrupts (probably + the most common module shared by all boards) * **tm27**: specific routines for the tm27 timing test - * **start** and **startup**: c and assembly used to initialize the board during startups/resets/reboots + * **start** and **startup**: C and assembly used to initialize the + board during startups/resets/reboots -These are just some of the things you should be looking for when adding Doxygen to a BSP. +These are just some of the things you should be looking for when adding +Doxygen to a BSP. -Note that there is no guarantee a particular BSP will implement all of these features, or even some of them. These are just the most common ones to look for. RTEMS follows a standardized naming convention for the BSP sub directories, so you should be able to tell in most cases what has been implemented on the BSP level and what has not. +Note that there is no guarantee a particular BSP will implement all of +these features, or even some of them. These are just the most common +ones to look for. RTEMS follows a standardized naming convention for +the BSP sub directories, so you should be able to tell in most cases +what has been implemented on the BSP level and what has not. Shared Features -==================================================== - -Some of the RTEMS executive is hardware independent and can be abstracted so that the same piece of code can be shared across multiple CPU architectures, or across multiple boards on the same architecture. This is done so that chunks of software can be reused, as well as aiding in reducing the development and debugging time for implementing new BSPs. This greatly aids the developer, but as someone seeking to document this code, this can make your life a little bit harder. It is hard to tell by looking at the directory of a BSP which features have simply been left out and which features are being implemented by using shared code from either from the architecture (../shared) or the base bsps/ shared directory (../../shared). You may be looking at the BSP headers and notice that you have an irq.h, but no irq.c implementing it, or you might even be missing both. You know that the processor has interrupt support somehow, but where is it? The easiest way to figure this out is by looking at the Makefile.am for a BSP. We'll detail this process more in a bit. +--------------- + +Some of the RTEMS executive is hardware independent and can be abstracted +so that the same piece of code can be shared across multiple CPU +architectures, or across multiple boards on the same architecture. This +is done so that chunks of software can be reused, as well as aiding +in reducing the development and debugging time for implementing new +BSPs. This greatly aids the developer, but as someone seeking to document +this code, this can make your life a little bit harder. It is hard to +tell by looking at the directory of a BSP which features have simply been +left out and which features are being implemented by using shared code +from either from the architecture (../shared) or the base bsps/ shared +directory (../../shared). You may be looking at the BSP headers and notice +that you have an irq.h, but no irq.c implementing it, or you might even be +missing both. You know that the processor has interrupt support somehow, +but where is it? The easiest way to figure this out is by looking at +the Makefile.am for a BSP. We'll detail this process more in a bit. Rationale -======================================================= - -As someone adding documentation and not doing actual development work, you might think it is not necessary to know some of the in and outs of BSPs. In actuality, this information will prove to be very useful. Doxygen documentation works by grouping things and their components (i.e. functions and other definitions), and by having brief descriptions of what each group does. You can't know what to look for or know how to group it or know how to describe it without some basic knowledge of what a BSP is. For more information on any of the above or BSPs in general, check out the `BSP Development Guide `_. . - -The Structure of the bsps/ directory -=================================================== - -All BSPs are found within the bsps/ directory, which is itself very well ordered. At the first level, we find a directory for each CPU architecture RTEMS supports, as well as a directory for code shared by all implementations. - -.. code block:: shell -$ cd bsps -$ ls -arm bsp.am lm32 m68k mips no_cpu README sparc -avr h8300 m32c Makefile.am moxie powerpc sh sparc64 -bfin i386 m32r MERGE.PROCEDURE nios2 preinstall.am shared v850 - - -If we cd into a specific architecture, we see that a similar structure is employed. bsps/arm/ contains directories for each Board Support Package for boards with an ARM cpu, along with a folder for files and .h's shared by all BSPs of that architecture. - -.. code block:: shell -$ cd arm -$ ls -acinclude.m4 edb7312 gumstix Makefile.am realview-pbx-a9 stm32f4 -configure.ac gba lm3s69xx nds rtl22xx xilinx-zynq -csb336 gdbarmsim lpc24xx preinstall.am shared -csb337 gp32 lpc32xx raspberrypi smdk2410 - - -Finally, if we cd into a specific BSP, we see the files and .h's that compose the package for that particular board. You may recognize the directory names as some of the [common features] we outlined above, like '''irq''', '''clock''', '''console''', and '''startup'''. These directories contain implementations of these features. - -.. code block:: shell -$ cd raspberrypi -$ ls -bsp_specs configure.ac include make misc README -clock console irq Makefile.am preinstall.am startup - - -Another way to get an idea of the structure of bsps/ is to navigate to a directory and execute the "tree -f" command. This outputs a nice graphic that conveys some of the hierarchical properties of a particular directory. - -.. code block:: shell -$ pwd -~/rtems/bsps/arm/raspberrypi -$ tree -f +--------- + +As someone adding documentation and not doing actual development +work, you might think it is not necessary to know some of the in and +outs of BSPs. In actuality, this information will prove to be very +useful. Doxygen documentation works by grouping things and their +components (i.e. functions and other definitions), and by having +brief descriptions of what each group does. You can't know what to +look for or know how to group it or know how to describe it without +some basic knowledge of what a BSP is. For more information on any +of the above or BSPs in general, check out the `BSP Development Guide +`_. . -|-- ./bsp_specs -|-- ./clock -| `-- ./clock/clockdrv.c -|-- ./configure.ac -|-- ./console -| |-- ./console/console-config.c -| `-- ./console/usart.c -|-- ./include -| |-- ./include/bsp.h -| |-- ./include/irq.h -| |-- ./include/mmu.h -| |-- ./include/raspberrypi.h -| `-- ./include/usart.h -|-- ./irq -| `-- ./irq/irq.c -|-- ./make -| `-- ./make/custom -| `-- ./make/custom/raspberrypi.cfg -|-- ./Makefile.am -|-- ./misc -| `-- ./misc/timer.c -|-- ./preinstall.am -|-- ./README -`-- ./startup - |-- ./startup/bspreset.c - |-- ./startup/bspstart.c - |-- ./startup/bspstarthooks.c - |-- ./startup/linkcmds - `-- ./startup/mm_config_table.c +The Structure of the bsps/ directory +------------------------------------ + +All BSPs are found within the bsps/ directory, which is itself very +well ordered. At the first level, we find a directory for each CPU +architecture RTEMS supports, as well as a directory for code shared by +all implementations. + + .. code-block:: shell + + $ cd bsps + $ ls + arm bsp.am lm32 m68k mips no_cpu README sparc + avr h8300 m32c Makefile.am moxie powerpc sh sparc64 + bfin i386 m32r MERGE.PROCEDURE nios2 preinstall.am shared v850 + + +If we cd into a specific architecture, we see that a similar structure is +employed. bsps/arm/ contains directories for each Board Support Package +for boards with an ARM cpu, along with a folder for files and .h's shared +by all BSPs of that architecture. + + .. code-block:: shell + + $ cd arm + $ ls + acinclude.m4 edb7312 gumstix Makefile.am realview-pbx-a9 stm32f4 + configure.ac gba lm3s69xx nds rtl22xx xilinx-zynq + csb336 gdbarmsim lpc24xx preinstall.am shared + csb337 gp32 lpc32xx raspberrypi smdk2410 + +Finally, if we cd into a specific BSP, we see the files and .h's that +compose the package for that particular board. You may recognize the +directory names as some of the [common features] we outlined above, +like '''irq''', '''clock''', '''console''', and '''startup'''. These +directories contain implementations of these features. + + .. code-block:: shell + + $ cd raspberrypi + $ ls + bsp_specs configure.ac include make misc README + clock console irq Makefile.am preinstall.am startup + +Another way to get an idea of the structure of bsps/ is to navigate +to a directory and execute the "tree -f" command. This outputs a nice +graphic that conveys some of the hierarchical properties of a particular +directory. + + .. code-block:: shell + + $ pwd + ~/rtems/bsps/arm/raspberrypi + $ tree -f + . + |-- ./bsp_specs + |-- ./clock + | `-- ./clock/clockdrv.c + |-- ./configure.ac + |-- ./console + | |-- ./console/console-config.c + | `-- ./console/usart.c + |-- ./include + | |-- ./include/bsp.h + | |-- ./include/irq.h + | |-- ./include/mmu.h + | |-- ./include/raspberrypi.h + | `-- ./include/usart.h + |-- ./irq + | `-- ./irq/irq.c + |-- ./make + | `-- ./make/custom + | `-- ./make/custom/raspberrypi.cfg + |-- ./Makefile.am + |-- ./misc + | `-- ./misc/timer.c + |-- ./preinstall.am + |-- ./README + `-- ./startup + |-- ./startup/bspreset.c + |-- ./startup/bspstart.c + |-- ./startup/bspstarthooks.c + |-- ./startup/linkcmds + `-- ./startup/mm_config_table.c In short, BSPs will use the following directories: + * bsps/**shared** <- code used that is shared by all BSPs * bsps/**CPU**/**shared** <- code used shared by all BSPs of a particular CPU architecture * bsps/**CPU**/**BSP** <- code unique to this BSP -As you can see, the bsps/ directory has a very logical and easy to understand structure to it. The documentation generated by Doxygen should attempt to match this structure as closely as possible. We want an overarching parent group to serve the same purpose as the bsps/ directory. In it, we want groups for each CPU architecture and a group for the shared files. We then want groups for each BSP. Breaking our documentation up into discrete groups like this will greatly simplify the process and make the documentation much easier to go through. By learning about the existing structure of the bsps/ directory, we get an idea of how we should structure the Doxygen groups we create. More on this in the next section. +As you can see, the bsps/ directory has a very logical and easy to +understand structure to it. The documentation generated by Doxygen +should attempt to match this structure as closely as possible. We want +an overarching parent group to serve the same purpose as the bsps/ +directory. In it, we want groups for each CPU architecture and a group +for the shared files. We then want groups for each BSP. Breaking our +documentation up into discrete groups like this will greatly simplify +the process and make the documentation much easier to go through. By +learning about the existing structure of the bsps/ directory, we get an +idea of how we should structure the Doxygen groups we create. More on +this in the next section. Doxygen -============================ -Now that we have covered some of the preliminaries, we can move on to what you are actually reading this wiki page for: adding Doxygen to the bsps/ directory. Let's start with some Doxygen basics. Skip this if you are already comfortable with Doxygen. +------- + +Now that we have covered some of the preliminaries, we can move on to +what you are actually reading this wiki page for: adding Doxygen to the +bsps/ directory. Let's start with some Doxygen basics. Skip this if you +are already comfortable with Doxygen. -In addition to this, check out the page on `Doxygen Recommendations `_. , which also contains a fair amount of information that will not be covered here. +In addition to this, check out the page on `Doxygen Recommendations +`_. , which also contains a fair amount +of information that will not be covered here. Doxygen Basics -===================================================== +-------------- -Doxygen is a documentation generator. It allows for documentation to be written right by the source code, greatly easing the pains of keeping documentation relevant and up to date. Doxygen has many commands, used for things like annotating functions with descriptions, parameter information, or return value information. You can reference other files or even other documentation. +Doxygen is a documentation generator. It allows for documentation to be +written right by the source code, greatly easing the pains of keeping +documentation relevant and up to date. Doxygen has many commands, +used for things like annotating functions with descriptions, parameter +information, or return value information. You can reference other files +or even other documentation. -The core component of Doxygen (that we care about right now at least) is what's called a **group**, or **module**. These are used to add structure and associate groups of files that serve a similar purpose or implement the same thing. +The core component of Doxygen (that we care about right now at least) is +what's called a **group**, or **module**. These are used to add structure +and associate groups of files that serve a similar purpose or implement +the same thing. Doxygen Headers -===================================== -Doxygen is always found in a special Doxygen comment block, known as a **Doxygen header**. In RTEMS, this block comes in the form of a multiline comment with some included Doxygen commands, which are preceded by the '@' tag. Take a look at this Doxygen header that declares the arm_raspberrypi module, which houses the documentation in the BSP for the Raspberry Pi. - -.. code block:: shell -bsps/arm/raspberrypi/include/bsp.h: - -/** - * @defgroup arm_raspberrypi Raspberry Pi Support - * - * @ingroup bsp_arm - * - * @brief Raspberry Pi support package - * - */ - - - -You see a few commands here that we'll cover in the following sections. Briefly, the @defgroup command declares a new group, the @ingroup command nests this group as a submodule of some other group (in this case bsp_arm), and the @brief command provides a brief description of what this group is. - - The @defgroup Command -========================================== - -The @defgroup command is used to declare new groups or modules. Think "define group". The syntax of this command is as follows: - -.. code block:: shell -@defgroup - - -The group name is the name used by Doxygen elsewhere to reference this group. The group description is what is displayed when the end user navigates to this module in the resulting documentation. The group description is a couple words formatted as how it would be in a table of contents. This part is what actually shows up in the documentation, when the user navigates to this group's module, this description will be the modules name. - -Groups should only be declared (@defgroup) in .h files. This is because Doxygen is used primarily to document interfaces, which are only found in .h files. Placing @defgroups in .h files is the only real restriction. Which .h file you place the group declaration in surprisingly doesn't matter. There is no information in the resulting documentation that indicates where the group was declared. You will see that we do have some rules for where you should place these declarations, but we also use this fact that it doesn't matter to our advantage, in order to standardize things. - -The @defgroup command is used only to define ''structure''. No actual documentation is generated as a result of its use. We must @ingroup things to the group we declare in order to create documentation. Even though it does not generate visible documentation, the @defgroup command is still very important. We use it in a way that seeks to emulate the structure of the bsps/ directory itself. We do this by creating a hierarchy of groups for each CPU architecture and each BSP. +--------------- +Doxygen is always found in a special Doxygen comment block, known as a +**Doxygen header**. In RTEMS, this block comes in the form of a multiline +comment with some included Doxygen commands, which are preceded by the '@' +tag. Take a look at this Doxygen header that declares the arm_raspberrypi +module, which houses the documentation in the BSP for the Raspberry Pi. + + .. code-block:: c + + bsps/arm/raspberrypi/include/bsp.h: + + /** + * @defgroup arm_raspberrypi Raspberry Pi Support + * + * @ingroup bsp_arm + * + * @brief Raspberry Pi support package + * + */ + +You see a few commands here that we'll cover in the following +sections. Briefly, the @defgroup command declares a new group, the +@ingroup command nests this group as a submodule of some other group (in +this case bsp_arm), and the @brief command provides a brief description +of what this group is. + +The @defgroup Command +--------------------- + +The @defgroup command is used to declare new groups or modules. Think +"define group". The syntax of this command is as follows: + + .. code-block:: c + + @defgroup + + +The group name is the name used by Doxygen elsewhere to reference this +group. The group description is what is displayed when the end user +navigates to this module in the resulting documentation. The group +description is a couple words formatted as how it would be in a table +of contents. This part is what actually shows up in the documentation, +when the user navigates to this group's module, this description will +be the modules name. + +Groups should only be declared (@defgroup) in .h files. This is +because Doxygen is used primarily to document interfaces, which are +only found in .h files. Placing @defgroups in .h files is the only real +restriction. Which .h file you place the group declaration in surprisingly +doesn't matter. There is no information in the resulting documentation +that indicates where the group was declared. You will see that we do +have some rules for where you should place these declarations, but we +also use this fact that it doesn't matter to our advantage, in order to +standardize things. + +The @defgroup command is used only to define ''structure''. No actual +documentation is generated as a result of its use. We must @ingroup things +to the group we declare in order to create documentation. Even though it +does not generate visible documentation, the @defgroup command is still +very important. We use it in a way that seeks to emulate the structure +of the bsps/ directory itself. We do this by creating a hierarchy of +groups for each CPU architecture and each BSP. The @ingroup Command -============================================= - -The @ingroup command is used to add 'things' to already declared groups or modules. These 'things' can either be other groups, or files themselves. The syntax of the @ingroup command is as follows: - -.. code block:: shell -@ingroup - - -The group name is the actual name, not description, of the group you want to add yourself to. Remember that group name was the second argument passed to the @defgroup command. +-------------------- -Using the @ingroup command is how we add ''meaning'' to the ''structure'' created by using @defgroup. @ingroup associates the file it is found in and all other Doxygen found within (function annotations, prototypes, etc) with the group we declared with the @defgroup command. We add related files and headers to the same groups to create a logical and cohesive body of documentation. If the end user wanted to read documentation about how the raspberry pi handles interrupts, all they would have to do would be to navigate to the raspberry pi's interrupt support module (which we created with a @defgroup command), and read the documentation contained within (which we added with @ingroup commands). +The @ingroup command is used to add 'things' to already declared +groups or modules. These 'things' can either be other groups, or files +themselves. The syntax of the @ingroup command is as follows: -@ingroup is found within all Doxygen headers, along with an @brief statement. There are two types of Doxygen headers, which we will go over after we see a description of the @brief command. + .. code-block:: shell - The @brief Command -===================================================== + @ingroup -The @brief command is used to give either a) a brief description in the form of an entry as you would see it in a table of contents (i.e. Capitalized, only a couple of words) or b) a brief topic sentence giving a basic idea of what the group does. The reason you have two uses for the brief command is that it is used differently in the two types of Doxygen headers, as we will see shortly. The syntax of the brief command is self evident, but included for the sake of completion: -.. code block:: shell -@brief
+The group name is the actual name, not description, of the group you +want to add yourself to. Remember that group name was the second argument +passed to the @defgroup command. +Using the @ingroup command is how we add ''meaning'' to the ''structure'' +created by using @defgroup. @ingroup associates the file it is found in +and all other Doxygen found within (function annotations, prototypes, etc) +with the group we declared with the @defgroup command. We add related +files and headers to the same groups to create a logical and cohesive +body of documentation. If the end user wanted to read documentation +about how the raspberry pi handles interrupts, all they would have to +do would be to navigate to the raspberry pi's interrupt support module +(which we created with a @defgroup command), and read the documentation +contained within (which we added with @ingroup commands). -The Two Types of Doxygen Headers -================================================= - -There are two types of Doxygen Headers. The first type is found at the beginning of a file, and contains an @file command. This type of header is used when @ingroup-ing the file into another doxygen group. The form of the @brief command in this case is a topic sentence, often very close to the file name or one of it's major functions. An example of this type of header, found in bsps/arm/raspberrypi/include/bsp.h is as follows: - -.. code block:: shell -Header type 1: used to add files to groups, always found at the beginning of a file -/** - * @file - * - * @ingroup raspberrypi - * - * @brief Global BSP definitions. - */ - -/* - * Copyright (c) 2013 Alan Cudmore - * -... - +@ingroup is found within all Doxygen headers, along with an @brief +statement. There are two types of Doxygen headers, which we will go over +after we see a description of the @brief command. -Notice the form and placement of this type of header. It is always found at the beginning of a file, and is in its own multiline comment block, separated by one line white space from the copyright. If you look at the header itself, you see a @file, @ingroup, and @brief command. Consider the @file and the @ingroup together, what this says is that we are adding this file to the raspberrypi group. There is actually a single argument to the @file command, but Doxygen can infer it, so we leave it out. Any other Doxygen, function annotations, function prototypes, #defines, and other code included in the file will now be visible and documented when the end user navigates to the group you added it to in the resulting documentation. +The @brief Command +------------------ -Now let's consider the second type of header. This type is syntactically very similar, but is used not to add files to groups, but to add groups to other groups. We use this type of header to define new groups and nest them within old groups. This is how we create hierarchy and structure within Doxygen. The following is found, again, in bsps/arm/raspberrypi/include/bsp.h: +The @brief command is used to give either a) a brief description +in the form of an entry as you would see it in a table of contents +(i.e. Capitalized, only a couple of words) or b) a brief topic sentence +giving a basic idea of what the group does. The reason you have two uses +for the brief command is that it is used differently in the two types of +Doxygen headers, as we will see shortly. The syntax of the brief command +is self evident, but included for the sake of completion: -.. code block:: shell -Header type 2: Used to nest groups, found anywhere within a file -/** - * @defgroup arm_raspberrypi Raspberry Pi Support - * - * @ingroup bsp_arm - * - * @brief Raspberry Pi Support Package - */ + .. code-block:: shell + @brief
-It looks very similar to the first type of header, but notice that the @file command is replaced with the @defgroup command. You can think about it in the same way though. Here we are creating a new group, the arm_raspberry pi group, and nesting it within the bsp_arm group. The @brief in this case should be in the form of how you would see it in a table of contents. Words should be capitalized and there should be no period. This type of header can be found anywhere in a file, but it is typically found either in the middle before the file's main function, or at the tail end of a file. Recall that as we are using the @defgroup command and creating a new group in this header, the actual .h we place this in does not matter. -The second type of header is the **structure** header, it's how we create new groups and implement hierarchy. The first type of header was the **meaning** header, it's how we added information to the groups we created. +The Two Types of Doxygen Headers +-------------------------------- + +There are two types of Doxygen Headers. The first type is found at the +beginning of a file, and contains an @file command. This type of header +is used when @ingroup-ing the file into another doxygen group. The form +of the @brief command in this case is a topic sentence, often very close +to the file name or one of it's major functions. An example of this type +of header, found in bsps/arm/raspberrypi/include/bsp.h is as follows: + + .. code-block:: c + + Header type 1: used to add files to groups, always found at the beginning of a file + /** + * @file + * + * @ingroup raspberrypi + * + * @brief Global BSP definitions. + */ + + /* + * Copyright (c) YYYY NAME + * + * + */ + + +Notice the form and placement of this type of header. It is always found +at the beginning of a file, and is in its own multiline comment block, +separated by one line white space from the copyright. If you look at the +header itself, you see a @file, @ingroup, and @brief command. Consider +the @file and the @ingroup together, what this says is that we are +adding this file to the raspberrypi group. There is actually a single +argument to the @file command, but Doxygen can infer it, so we leave +it out. Any other Doxygen, function annotations, function prototypes, +#defines, and other code included in the file will now be visible and +documented when the end user navigates to the group you added it to in +the resulting documentation. + +Now let's consider the second type of header. This type is syntactically +very similar, but is used not to add files to groups, but to add groups +to other groups. We use this type of header to define new groups +and nest them within old groups. This is how we create hierarchy +and structure within Doxygen. The following is found, again, in +bsps/arm/raspberrypi/include/bsp.h: -For more examples of Doxygen structure and syntax, refer to BSPs found within the arm architecture, the lpc32xx and raspberrypi BSPs are particularly well documented. A good way to quickly learn more is by tweaking some Doxygen in a file, then regenerating the html, and seeing what has changed. + .. code-block:: c + + Header type 2: Used to nest groups, found anywhere within a file + /** + * @defgroup arm_raspberrypi Raspberry Pi Support + * + * @ingroup bsp_arm + * + * @brief Raspberry Pi Support Package + */ + +It looks very similar to the first type of header, but notice that the +@file command is replaced with the @defgroup command. You can think +about it in the same way though. Here we are creating a new group, the +arm_raspberry pi group, and nesting it within the bsp_arm group. The +@brief in this case should be in the form of how you would see it in a +table of contents. Words should be capitalized and there should be no +period. This type of header can be found anywhere in a file, but it is +typically found either in the middle before the file's main function, +or at the tail end of a file. Recall that as we are using the @defgroup +command and creating a new group in this header, the actual .h we place +this in does not matter. + +The second type of header is the **structure** header, it's how we +create new groups and implement hierarchy. The first type of header +was the **meaning** header, it's how we added information to the groups +we created. + +For more examples of Doxygen structure and syntax, refer to BSPs found +within the arm architecture, the lpc32xx and raspberrypi BSPs are +particularly well documented. A good way to quickly learn more is by +tweaking some Doxygen in a file, then regenerating the html, and seeing +what has changed. Generating Documentation -==================================================== +------------------------ -Doxygen is a documentation generator, and as such, we must generate the actual html documentation to see the results of our work. This is a very good way to check your work, and see if the resulting structure and organization was what you had intended. The best way to do this is to simply run the `do_doxygen script `_. . To use the script: +Doxygen is a documentation generator, and as such, we must +generate the actual html documentation to see the results +of our work. This is a very good way to check your work, and +see if the resulting structure and organization was what you had +intended. The best way to do this is to simply run the `do_doxygen script +`_. To use the script: -Make sure Doxygen is installed. Also, the environment needs to have the root directory of RTEMS set in the variable `r` so that `$r` prints the path to RTEMS, and the script takes as argument a relative directory from there to generate the doxygen, for example to generate the doxygen for all of bsps/ you would do: +Make sure Doxygen is installed. Also, the environment needs to have the +root directory of RTEMS set in the variable `r` so that `$r` prints the +path to RTEMS, and the script takes as argument a relative directory +from there to generate the doxygen, for example to generate the doxygen +for all of bsps/ you would do: -.. code block:: shell -export r=~/rtems -./do_doxygen bsps + .. code-block:: shell + export r=~/rtems + ./do_doxygen bsps Doxygen in bsps/ -================================================== +---------------- + +Now that we've covered the basics of Doxygen, the basics of BSPs and the +structure of the bsps/ directory, actually adding new Doxygen to bsps/ +will be much easier than it was before. We will cover a set of rules and +conventions that you should follow when adding Doxygen to this directory, +and include some tips and tricks. -Now that we've covered the basics of Doxygen, the basics of BSPs and the structure of the bsps/ directory, actually adding new Doxygen to bsps/ will be much easier than it was before. We will cover a set of rules and conventions that you should follow when adding Doxygen to this directory, and include some tips and tricks. +Group Naming Conventions +------------------------ - Group Naming Conventions -=================================================== +This is an easy one. These are in place in order for you to quickly +identify some of the structure of the Doxygen groups and nested groups, +without actually generating and looking at the documentation. The basic +idea is this: when defining a new group (@defgroup), the form of the name +should be the super group, or the name of the group you are nesting this +group within, followed by an underscore, followed by the intended name +of this new group. In command form: -This is an easy one. These are in place in order for you to quickly identify some of the structure of the Doxygen groups and nested groups, without actually generating and looking at the documentation. The basic idea is this: when defining a new group (@defgroup), the form of the name should be the super group, or the name of the group you are nesting this group within, followed by an underscore, followed by the intended name of this new group. In command form: + .. code-block:: c -.. code block:: shell <----- This is your group name -------> <--usual description --> -@defgroup _ + @defgroup _ Some examples of this: - * **bsp_arm**: This is the group for the arm architecture. It is a member of the all inclusive bsp-kit group (more on this in structure conventions), so we prefix it with the "**bsp**" super group name. This is the group for the arm architecture, so the rest is just "'''arm'''" - * **arm_raspberrypi**: This is the group for the Raspberry Pi BSP. It is is an arm board, and as such, is nested within the bsp_arm group. We prefix the group name with an "**arm**" (notice we drop the bsp prefix of the arm group - we only care about the immediate super group), and the rest is a simple "'''raspberrypi'''", indicating this is the raspberrypi group, which is nested within the bsp_arm group. - * **raspberrypi_interrupt** This is the group for code handling interrupts on the Raspberry Pi platform. Because this code and the group that envelops it is Raspberry Pi dependent, we prefix our name with a "**raspberrypi**", indicating this group is nested within the raspberrypi group.= Structure Conventions = - -This covers where, when, and why you should place the second type of Doxygen header. Remember that our goal is to have the structure of the documentation to match the organization of the bsps/ directory as closely as possible. We accomplish this by creating groups for each cpu architecture, each BSP, and each shared directory. These groups are nested as appropriate in order to achieve a hierarchy similar to that of bsps/. The arm_raspberrypi group would be nested within the bsp_arm group, for example. - - Where to place @defgroup -===================================================== - -Remember how I said it really doesn't matter where you place the @defgroup? Well, it does and it doesn't. It would be chaotic to place these anywhere, and almost impossible to tell when you have a @defgroup and when you don't, so we do have some rules in place to guide where you should place these. - - @defgroups for CPU Architectures and Shared Directories -============================================================================== - -The standardized place for these is within a special doxygen.h file placed within the particular architectures shared directory. This doxygen.h file exists solely for this purpose, to provide a standard place to house the group definitions for CPU architectures and the shared directory for that architecture. This is done because there is no single file that all architectures share, so it would be impossible to declare a standardized location for architecture declarations without the creation of a new file. This also allows others to quickly determine if the group for a particular architecture has already been defined or not. Lets look at the doxygen.h for the arm architecture as an example, found at arm/shared/doxygen.h: - -.. code block:: shell - /** - * @defgroup bsp_arm ARM - * - * @ingroup bsp_kit - * - * @brief ARM Board Support Packages - */ - - /** - * @defgroup arm_shared ARM Shared Modules - * - * @ingroup bsp_arm - * - * @brief ARM Shared Modules - */ - - - -The doxygen.h contains only 2 Doxygen headers, both of which are of the second type. One header is used to create the groups for the arm architecture **bsp_arm**, nesting it as part of the bsp_kit group, and the other creates an **arm_shared** group to house the code that is shared across all BSPs of this architecture. Because these are the second type of Doxygen header, where we place them does not matter. This allows us to place them in a standard doxygen.h file, and the end user is non the wiser. Note that this .h file should never be included by a .c file, and that the only group declarations that should be placed here are the declarations for the CPU Architecture group and the shared group. - -There is also a doxygen.h file that exists at the root bsps/shared directory, to @defgroup the the parent **bsp_kit** group (the only group to not be nested within any other groups) and to @defgroup the **bsp_shared** group, to serve as the holder for the bsps/shared directory. - -If the architecture in which the BSP you are tasked with does not have one of these files already, you will need to copy the format of the file here, replacing the **arm** with whatever the CPU Architecture you are working with is. Name this file doxygen.h, and place it in the shared directory for that architecture. -The only groups you should ever add to this CPU group would be groups for specific BSPs and a group for the shared directory. +* **bsp_arm**: This is the group for the arm architecture. It is a +member of the all inclusive bsp-kit group (more on this in structure +conventions), so we prefix it with the "**bsp**" super group name. This +is the group for the arm architecture, so the rest is just "'''arm'''" + +* **arm_raspberrypi**: This is the group for the Raspberry Pi BSP. It +is is an arm board, and as such, is nested within the bsp_arm group. We +prefix the group name with an "**arm**" (notice we drop the bsp prefix +of the arm group - we only care about the immediate super group), +and the rest is a simple "'''raspberrypi'''", indicating this is the +raspberrypi group, which is nested within the bsp_arm group. + +* **raspberrypi_interrupt** This is the group for code handling +interrupts on the Raspberry Pi platform. Because this code and the group +that envelops it is Raspberry Pi dependent, we prefix our name with a +"**raspberrypi**", indicating this group is nested within the raspberrypi +group.= Structure Conventions = + +This covers where, when, and why you should place the second type of +Doxygen header. Remember that our goal is to have the structure of +the documentation to match the organization of the bsps/ directory as +closely as possible. We accomplish this by creating groups for each +cpu architecture, each BSP, and each shared directory. These groups are +nested as appropriate in order to achieve a hierarchy similar to that +of bsps/. The arm_raspberrypi group would be nested within the bsp_arm +group, for example. + +Where to place @defgroup +------------------------ + +Remember how I said it really doesn't matter where you place the +@defgroup? Well, it does and it doesn't. It would be chaotic to place +these anywhere, and almost impossible to tell when you have a @defgroup +and when you don't, so we do have some rules in place to guide where +you should place these. + +@defgroups for CPU Architectures and Shared Directories +------------------------------------------------------- + +The standardized place for these is within a special doxygen.h file +placed within the particular architectures shared directory. This +doxygen.h file exists solely for this purpose, to provide a standard +place to house the group definitions for CPU architectures and the +shared directory for that architecture. This is done because there is +no single file that all architectures share, so it would be impossible +to declare a standardized location for architecture declarations without +the creation of a new file. This also allows others to quickly determine +if the group for a particular architecture has already been defined or +not. Lets look at the doxygen.h for the arm architecture as an example, +found at arm/shared/doxygen.h: + + .. code-block:: c + + /** + * @defgroup bsp_arm ARM + * + * @ingroup bsp_kit + * + * @brief ARM Board Support Packages + */ + + /** + * @defgroup arm_shared ARM Shared Modules + * + * @ingroup bsp_arm + * + * @brief ARM Shared Modules + */ + + +The doxygen.h contains only 2 Doxygen headers, both of which are of +the second type. One header is used to create the groups for the arm +architecture **bsp_arm**, nesting it as part of the bsp_kit group, +and the other creates an **arm_shared** group to house the code that is +shared across all BSPs of this architecture. Because these are the second +type of Doxygen header, where we place them does not matter. This allows +us to place them in a standard doxygen.h file, and the end user is non +the wiser. Note that this .h file should never be included by a .c file, +and that the only group declarations that should be placed here are the +declarations for the CPU Architecture group and the shared group. + +There is also a doxygen.h file that exists at the root bsps/shared +directory, to @defgroup the the parent **bsp_kit** group (the only +group to not be nested within any other groups) and to @defgroup +the **bsp_shared** group, to serve as the holder for the bsps/shared +directory. + +If the architecture in which the BSP you are tasked with does not have +one of these files already, you will need to copy the format of the file +here, replacing the **arm** with whatever the CPU Architecture you are +working with is. Name this file doxygen.h, and place it in the shared +directory for that architecture. + +The only groups you should ever add to this CPU group would be groups +for specific BSPs and a group for the shared directory. @defgroups for BSPs -======================================= - -These are much easier than placing @defgroups for CPU Architectures. The overwhelming majority of the time, the @defgroup for a BSP is found within the bsp.h file found at '''''bsp'''''/include/bsp.h. It is usually placed midway through or towards the end of the file. In the event that your board lacks a bsp.h file, include this group declaration within the most standard or commonly included header for that BSP. - -The group for a BSP should **always** be nested within the group for the CPU architecture it uses. This means that the Doxygen header for defining a BSP group should always look something like this: - -.. code block:: shell - /** - * @defgroup *architecture*_*BSP* *name* - * - * @ingroup bsp_*architecture* - * - * @brief *BSP* Support Package - */ - - - @defgroups for Everything Else -====================================================== - -Never be afraid to add more structure! Once the basic CPU and BSP group hierarchy is established, what we're left with is all the sub directories and implementation code. Whether working within a shared directory for a CPU architecture, or within a BSP directory, you should always be looking for associations you can make to group files together by. Your goal should be to avoid @ingroup-ing files directly to the cpu_shared group and the cpu_bsp group as much as possible, you want to find more groups you can nest within these groups, and then @ingroup files to those groups. Here are some things to look for: - -==== Look Common Features Implemented -=================================================== - -Remember that list of common features outlined in the BSP Basics section? Find the .h's that are responsible for providing the interface for these features, and @defgroup a group to @ingroup the files responsible for implementing this feature. - -RTEMS has a naming convention for its BSP sub directories, so it should be a really quick and easy process to determine what features are there and what is missing. - -Examples of this are found within the **arm_raspberrypi** group, which contains nested subgroups like **raspberry_interrupt** to group files responsible for handling interrupts, **raspberrypi_usart** to group files responsible for implementing USART support, and many other subgroups. - -==== Check out the Makefile -=============================================== - -When working within a BSP, take a look at the Makefile.am. Often times, you will find that the original developer of the code has outlined the groups nicely for you already, with comments and titles before including source files to be built. Also, this is often the only way to tell which features a BSP simply does not implement, and which features a BSP borrows from either the architecture's shared group, or the bsps/ shared group. - -==== Start with a .h, and look for files that include it -============================================================= - -You should end up with a @defgroup for ''most'' .h files. Some .h files are related and will not have independent groups, but most provide interfaces for different features and should have their own group defined. Declare a group for the header, then use cscope to find the files that include this header, and try to determine where the implementation code for prototypes are found. These are the files you should @ingroup. - -==== Files with similar names -=============================================== - -If you see that a few files have similar names, like they are all prefixed with the same characters, then these files should most likely be part of the same group. - -Remember, your goal is to @defgroup as much as you can. The only files you should be @ingroup-ing directly to the BSP group or the shared group are files that don't cleanly fit into any other group. +------------------- + +These are much easier than placing @defgroups for CPU Architectures. The +overwhelming majority of the time, the @defgroup for a BSP is found within +the bsp.h file found at '''''bsp'''''/include/bsp.h. It is usually placed +midway through or towards the end of the file. In the event that your +board lacks a bsp.h file, include this group declaration within the most +standard or commonly included header for that BSP. + +The group for a BSP should **always** be nested within the group for +the CPU architecture it uses. This means that the Doxygen header for +defining a BSP group should always look something like this: + + .. code-block:: c + + /** + * @defgroup *architecture*_*BSP* *name* + * + * @ingroup bsp_*architecture* + * + * @brief *BSP* Support Package + */ + + +@defgroups for Everything Else +------------------------------ + +Never be afraid to add more structure! Once the basic CPU and BSP group +hierarchy is established, what we're left with is all the sub directories +and implementation code. Whether working within a shared directory for +a CPU architecture, or within a BSP directory, you should always be +looking for associations you can make to group files together by. Your +goal should be to avoid @ingroup-ing files directly to the cpu_shared +group and the cpu_bsp group as much as possible, you want to find more +groups you can nest within these groups, and then @ingroup files to +those groups. Here are some things to look for: + +Look Common Features Implemented +-------------------------------- + +Remember that list of common features outlined in the BSP Basics +section? Find the .h's that are responsible for providing the interface +for these features, and @defgroup a group to @ingroup the files +responsible for implementing this feature. + +RTEMS has a naming convention for its BSP sub directories, so it should +be a really quick and easy process to determine what features are there +and what is missing. + +Examples of this are found within the **arm_raspberrypi** group, which +contains nested subgroups like **raspberry_interrupt** to group files +responsible for handling interrupts, **raspberrypi_usart** to group files +responsible for implementing USART support, and many other subgroups. + +Check out the Makefile +---------------------- + +When working within a BSP, take a look at the Makefile.am. Often times, +you will find that the original developer of the code has outlined the +groups nicely for you already, with comments and titles before including +source files to be built. Also, this is often the only way to tell which +features a BSP simply does not implement, and which features a BSP borrows +from either the architecture's shared group, or the bsps/ shared group. + +Start with a .h, and look for files that include it +--------------------------------------------------- + +You should end up with a @defgroup for ''most'' .h files. Some .h files +are related and will not have independent groups, but most provide +interfaces for different features and should have their own group +defined. Declare a group for the header, then use cscope to find the files +that include this header, and try to determine where the implementation +code for prototypes are found. These are the files you should @ingroup. + +Files with similar names +------------------------ + +If you see that a few files have similar names, like they are all prefixed +with the same characters, then these files should most likely be part +of the same group. + +Remember, your goal is to @defgroup as much as you can. The only files +you should be @ingroup-ing directly to the BSP group or the shared group +are files that don't cleanly fit into any other group. Where to place @ingroup -============================================= +----------------------- The @ingroups you add should make sense. - * If you are working within an architecture's shared directory, @ingroup should be adding things either to the *architecture*_shared group, or some sub group of it. - * If you are working within a BSP directory, @ingroup should be adding things to either the *architecture_*bsp* group, or some sub group of it. +* If you are working within an architecture's shared directory, @ingroup should be adding things either to the *architecture*_shared group, or some sub group of it. - @ingroup in the first type of Doxygen Header -======================================================== +* If you are working within a BSP directory, @ingroup should be adding things to either the *architecture_*bsp* group, or some sub group of it. -Remember that in the first type of Doxygen header, we are adding files to groups. This type of header should always be at the top of the file. You should be adding files that are associated in some way to the same groups. That is to say, if three different .h files provide an interface allowing interrupt support, they should be a part of the same group. Some good ways to associate files were outlined above. +@ingroup in the first type of Doxygen Header +-------------------------------------------- - @ingroup in the second type of Doxygen Header === -================================================================== -Here we are using the @ingroup command to add groups to other groups, creating a hierarchy. The goal for bsps/ is to have one single group that holds all other groups. This root group is the **bsp_kit** group. All groups should be added either directly to this group (if you are creating an architecture group) or added to one of its sub groups. +Remember that in the first type of Doxygen header, we are adding files +to groups. This type of header should always be at the top of the +file. You should be adding files that are associated in some way to +the same groups. That is to say, if three different .h files provide an +interface allowing interrupt support, they should be a part of the same +group. Some good ways to associate files were outlined above. -When nesting groups, try to match the structure of bsps/ as closely as possible. For example, if a group is defined to associate all files that provide for a real time clock for the raspberrypi, nest it within the arm_raspberrypi group. +@ingroup in the second type of Doxygen Header +--------------------------------------------- -@ingroup for shared code -================================================ +Here we are using the @ingroup command to add groups to other groups, +creating a hierarchy. The goal for bsps/ is to have one single group that +holds all other groups. This root group is the **bsp_kit** group. All +groups should be added either directly to this group (if you are creating +an architecture group) or added to one of its sub groups. -This is tricky. You may end up in a situation where your BSP uses code found in either the architecture shared directory, or the bsps/shared directory. Even though this code is logically associated with the BSP, as stated above: all files in the shared directory should be added to either the *architecture*_shared group, or some subgroup of it ''not'' the BSP group. You could make a note under the @brief line in the header (which shows up in the resulting documentation) that a particular BSP uses this code. +When nesting groups, try to match the structure of bsps/ as closely as +possible. For example, if a group is defined to associate all files that +provide for a real time clock for the raspberrypi, nest it within the +arm_raspberrypi group. -When working with shared code, you should be careful and add notes to @brief to indicate that it is a shared code or interface. Prefixing things with "Generic" is a good idea here. You will still be able to form groups and associate things when working on the shared level, but sometimes you will find that you have the interface (.h) to @defgroup, but not many files to add to the group as it may be hardware dependent. This is okay. +@ingroup for shared code +------------------------ + +This is tricky. You may end up in a situation where your BSP uses code +found in either the architecture shared directory, or the bsps/shared +directory. Even though this code is logically associated with the BSP, +as stated above: all files in the shared directory should be added to +either the *architecture*_shared group, or some subgroup of it ''not'' +the BSP group. You could make a note under the @brief line in the header +(which shows up in the resulting documentation) that a particular BSP +uses this code. + +When working with shared code, you should be careful and add notes to +@brief to indicate that it is a shared code or interface. Prefixing things +with "Generic" is a good idea here. You will still be able to form groups +and associate things when working on the shared level, but sometimes you +will find that you have the interface (.h) to @defgroup, but not many +files to add to the group as it may be hardware dependent. This is okay. diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst index 23e5db0..1ff16b8 100644 --- a/eng/coding-file-hdr.rst +++ b/eng/coding-file-hdr.rst @@ -9,32 +9,35 @@ Boilerplate File Header -========================================== - +======================= Every file should include two comment header blocks, one for the Doxygen output and a copyright notice. This is a typical example: -.. code block:: shell -/** - * @file - * - * @ingroup TheGroupForThisFile - * - * @brief Short "Table of Contents" Description of File Contents - * - * A short description of the purpose of this file. - */ - -/* - * Copyright (c) 20XX Your Name Or Your Company. - * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * https://www.rtems.org/license/LICENSE. - */ - - - - * Use exactly one blank line between the Doxygen header and copyright notice. Leave the first line of the copyright notice blank. - * Separate the Doxygen header and copyright notice so the copyright notice is not included in the Doxygen output. - * The copyright owner and specific license terms may vary. + .. code-block:: c + + /** + * @file + * + * @ingroup TheGroupForThisFile + * + * @brief Short "Table of Contents" Description of File Contents + * + * A short description of the purpose of this file. + */ + + /* + * Copyright (c) 20XX Your Name Or Your Company. + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * https://www.rtems.org/license/LICENSE. + */ + + +* Use exactly one blank line between the Doxygen header and copyright notice. Leave the first line of the copyright notice blank. + +* Separate the Doxygen header and copyright notice so the copyright notice is not included in the Doxygen output. + +* The copyright owner and specific license terms may vary. + +TBD Add link to license requirements section and show variant licenses. -- cgit v1.2.3 From 9d3cb23123f378f8171d4ed966f7a426156b384e Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Sun, 2 Dec 2018 11:35:41 -0600 Subject: eng/license-requirements.rst: Add a TBD for BSD info --- eng/license-requirements.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/eng/license-requirements.rst b/eng/license-requirements.rst index 90a5409..c57bdd4 100644 --- a/eng/license-requirements.rst +++ b/eng/license-requirements.rst @@ -21,3 +21,4 @@ https://devel.rtems.org/ticket/3053 for details. TBD - Convert the following to Rest and insert into this file TBD - https://devel.rtems.org/wiki/Developer/Coding/Conventions#Licenses +TBD - Review and make sure this includes info on BSD variants -- cgit v1.2.3 From 1e106e21788f0df0854f3fac2536162710dd4cc4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=A7al=20Comajoan=20Cara?= Date: Sun, 2 Dec 2018 17:02:40 -0600 Subject: eng/conf.py: Use new short name of SW Eng Handbook --- eng/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eng/conf.py b/eng/conf.py index a4da3ff..d44e8b7 100644 --- a/eng/conf.py +++ b/eng/conf.py @@ -7,7 +7,7 @@ project = "RTEMS Software Engineering Handbook" latex_documents = [ ('index', - 'software-engineering-handbook.tex', + 'eng.tex', u'RTEMS Software Engineering Handbook', u'RTEMS Documentation Project', 'manual'), -- cgit v1.2.3 From 186e1dcd504276b3df05f2d044c847be716a5b23 Mon Sep 17 00:00:00 2001 From: Pritiah Jain Date: Mon, 3 Dec 2018 02:43:01 +0530 Subject: management: Convert TBD to rest Format (GCI 2018) --- eng/management.rst | 5 +- eng/why-contribute.rst | 151 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 154 insertions(+), 2 deletions(-) create mode 100644 eng/why-contribute.rst diff --git a/eng/management.rst b/eng/management.rst index 2b03dee..a71167a 100644 --- a/eng/management.rst +++ b/eng/management.rst @@ -7,8 +7,8 @@ Software Development Management ******************************* -TBD - Convert https://devel.rtems.org/wiki/TBR/Website/WhyContribute to Rest -TBD - and insert here +.. COMMENT:TBD - Convert https://devel.rtems.org/wiki/TBR/Website/WhyContribute to Rest +.. COMMENT:TBD - and insert here .. COMMENT: Subsections .. toctree:: @@ -18,3 +18,4 @@ TBD - and insert here coding change-management issue-tracking + why-contribute diff --git a/eng/why-contribute.rst b/eng/why-contribute.rst new file mode 100644 index 0000000..619a255 --- /dev/null +++ b/eng/why-contribute.rst @@ -0,0 +1,151 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Why Contribute? +*************** + +If you are writing a major extension to RTEMS, such as a port +to a new CPU family or model, a new target board, a major rewrite +of some existing component, or adding some missing functionality, +please keep in mind the importance of keeping other developers informed. +Part of being a good cooperating member of the RTEMS development team is the +responsibility to consider what the other developers need in order +to work effectively. + +Nobody likes to do a lot of work and find it was duplicated effort. +So when you work on a major new feature, you should tell +rtems-users@www.rtems.com what you are working on, and give +occasional reports of how far you have come and how confident +you are that you will finish the job. This way, other developers +(if they are paying attention) will be aware which projects would +duplicate your effort, and can either join up with you, or at +least avoid spending time on something that will be unnecessary +because of your work. If, for whatever reason, you are not in a +position to publicly discuss your work, please at least privately +let a Steering Committee member know about it so they can look +out for duplicated effort or possible collaborators. + +You should also monitor the +`RTEMS Mailing Lists `_. +to see if someone else mentions working on a similar +project to yours. If that happens, speak up! + +If you are thinking of taking a contract to develop changes +under a temporary delayed-release agreement, please negotiate +the agreement so that you can give progress reports before the +release date, even though you cannot release the code itself. +Also please arrange so that, when the agreed-on date comes, +you can release whatever part of the job you succeeded in doing, +even if you have not succeeded in finishing it. +Someone else may be able to finish the job. + +Many people have done RTEMS ports or BSPs on their own, to a wide +variety of processors, without much communication with the RTEMS +development team. However, much of this work has been lost over +time, or have proven very hard to integrate. So, what we're asking +is that, to the maximum extent possible, you communicate with us +as early on and as much as possible. + + +Common Questions and Answers +---------------------------- + +Here are some questions RTEMS porters may have with our answers to +them. While the focus here is on new ports and BSPs, we believe that +the issues are similar for other RTEMS development efforts including +student efforts to implement new algorithmic optimizations. + +''Our engineers understand our target environment better than anyone +else, and we have a tight schedule. Why should we work with the RTEMS +developers, when we can get the code out faster by whacking it out on our own?'' + +You understand your target environment better than anyone else. +However, the RTEMS developers understand RTEMS better than anyone +else; furthermore, the RTEMS developers tend to have a wide breadth +of experience across a large number of processors, boards, peripherals, +and application domains. It has been our experience that few problems +encountered in embedded systems development are unique to a particular +processor or application. The vast majority of the time an issue that +arises in one project has also shown up in other projects. + +The intimate knowledge of RTEMS internals as well as a wide breadth of +embedded systems knowledge means that there is a good chance that at +least one RTEMS developer has already addressed issues you are likely +to face when doing your port, BSP, or application. The developers can +help guide you towards a workable long term solution, possibly saving +you significant time in your development cycle. + +If getting the sources into the official RTEMS distributions is one of +your goals, then engaging other RTEMS developers early will also likely +shorten your development time. By interacting as early as possible you +are more likely to write code which can be easily accepted into the official +sources when you are finished. If you wait until you think you are done +to begin interacting with the RTEMS team, you might find that you did +some things wrong and you may have to rewrite parts of your RTEMS port, +which is a waste of your valuable time. + +''Why should we care if our port is integrated into the official +RTEMS sources? We can distribute it ourselves to whoever is interested.'' + +Yes, the GNU GPL allows you to do that. But by doing so, you end up +having to maintain that code yourself; this can be a significant +effort over time as the RTEMS sources change rapidly. + +You also lose the advantage of wider exposure by including your port +in the official RTEMS sources maintained by the RTEMS Project. +The wider exposure in the RTEMS developer and tester community will +help keep your work up to date with the current sources. You may even +find that volunteers will run the ever-growing test suite on your port +and fix problems during the development cycle -- sometimes without your +intervention. + +It has been our experience that integrated ports tend to ultimately +be of better quality and stay up to date from release to release. + +''Why should we communicate up front? We're happy to let the +RTEMS developers integrate our stuff later.'' + +See above. It will save work for you over both the short and the +long term, and it is the right thing to do. + +''Aspects of my target environment that my application exploits +are still under NDA.'' + +Nevertheless, if the target hardware is built of any commercial parts +that are generally available including, but not limited to, the CPU +or peripherals, then that portion of your work is still of general use. +Similarly, if you have written software that adheres to existing API or +interface standards, then that portion is also of general use. +Our experience is that most embedded applications do utilize a custom +mix of hardware and application, but they are built upon layers of hardware +and software components that are in no way unique to the project. + +If you are porting to an unreleased CPU family or model, then just +announcing it is important because other RTEMS users may be planning +to use it and some of them may already be trying to port RTEMS on +their own. Your customers might be happier to know that your port +will eventually be available. Also, there is no requirement that RTEMS +include all features or ports at any particular time, so you are encouraged +to submit discrete pieces of functionality in stages. + +Assume that your processor has some new functionality or peripherals. +However that functionality is still covered by NDA, but the basic core +architecture is not. It is still to your advantage to go ahead and work +with the developers early to provide a "base port" for the CPU family. +That base port would only use the publicly available specifications +until such time as the NDA is lifted. Once the NDA is lifted you can +work with the developers to provide the code necessary to take +advantage of the new functionality. + +Ultimately, cooperating with the free software community as early as +possible helps you by decreasing your development cycle, decreasing +your long term maintenance costs and may help raise interest in your +processor by having a free compiler implementation available to +anyone who wants to take a look. + +Finally, please note that GPL-covered code may not be distributed +under an NDA, as explained by Richard Stallman in +http://gcc.gnu.org/ml/gcc/2001-07/msg01342.html. -- cgit v1.2.3 From 9b5be547bb9ea524ccb36cc69e717d0aa0d917fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=A7al=20Comajoan=20Cara?= Date: Mon, 3 Dec 2018 06:33:31 +0100 Subject: eng/vc-authors: Convert wiki page to Rest (GCI 2018) Converted https://devel.rtems.org/wiki/Developer/Git/Committers to Rest, and TBDs and wiki TODOs into comments. Also changed http links to https (the ones that are possible), corrected some typos, created a folder for eng images and added some formatting. This work was part of GCI 2018. --- eng/vc-authors.rst | 355 +++++++++++++++++++++++++++++++++++++++- images/eng/Git-personalrepo.png | Bin 0 -> 24895 bytes 2 files changed, 353 insertions(+), 2 deletions(-) create mode 100644 images/eng/Git-personalrepo.png diff --git a/eng/vc-authors.rst b/eng/vc-authors.rst index 68f28e3..7e6e763 100644 --- a/eng/vc-authors.rst +++ b/eng/vc-authors.rst @@ -7,5 +7,356 @@ Software Development (Git Writers) ********************************** -TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Committers -TBD - and insert here. +.. COMMENT: TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Committers +.. COMMENT: TBD - and insert here. + +.. COMMENT: TBD - Some guidelines for anyone who wishes to contribute to +.. COMMENT: TBD - rtems... Patches? Pull Requests?... + + The preferred workflow for making changes to RTEMS is to push patches to a + committer's personal repository in public view and then merge changes from + there. For working on enhancements or bug fixes committers are encouraged to + push to branches on their personal repositories and to merge into the main + RTEMS repository from their personal repository. Personal branches should + not be pushed to the RTEMS repository. + +SSH Access +---------- + +Currently all committer's should have an ssh account on the main git server, +dispatch.rtems.org. If you have been granted commit access and do have an +account on dispatch.rtems.org one should be requested on the devel@… list. +SSH access for git uses key logins instead of passwords. The key should be at +least 1024bits in length. + +The public repositories can by cloned with + +.. code-block:: shell + + git clone ssh://user@dispatch.rtems.org/data/git/rtems.git + +Or replace `rtems.git` with another repo to clone another one. + +Personal Repository +------------------- +Personal repositories keep the clutter away from the master repository. A +user with a personal repository can make commits, create and delete branches, +plus more without interfering with the master repository. Commits to the +master repository generate email to the vc@… list and development type commits +by a developer would only add noise and lessen the effectiveness of the commit +list + +A committer should maintain a personal clone of the RTEMS repository through +which all changes merged into the RTEMS head are sent. The personal repository +is also a good place for committers to push branches that contain works in +progress. The following instructions show how to setup a personal repositor +that by default causes commits to go to your private local repository and +pushes to go to your publicly visible personal repository. The RTEMS head is +configured as a remote repository named 'upstream' to which you can push +changes that have been approved for merging into RTEMS. + +Branches aren't automatically pushed until you tell git to do the initial push +after which the branch is pushed automatically. In order to keep code private +just put it on a branch in your local clone and do not push the branch. + +Create a personal repository +---------------------------- + +Set up the server side repository. In the following substitute user with your +username. + +.. code-block:: shell + + # ssh git.rtems.org + [user@git ~]$ ln -s /data/git/user git + [user@git ~]$ ls -l + lrwxrwxrwx 1 user rtems 16 Feb 1 11:52 git -> /data/git/user + [user@git ~]$ cd git + [user@git git]$ git clone --mirror /data/git/rtems.git + +Provide a description for the repository, for example "Clone of master +repository." + +.. code-block:: shell + + [user@git git]$ echo "Clone of master repository." > rtems.git/description + [user@git git]$ logout + +Clone the repository on your local machine + +.. code-block:: shell + + # git clone ssh://user@dispatch.rtems.org/home/user/git/rtems.git + # cd rtems + +Add the RTEMS repository as a remote repository and get the remote tags +and branches + +.. code-block:: shell + + # git remote add upstream ssh://user@dispatch.rtems.org/data/git/rtems.git + # git fetch upstream + +After a little while you should be able to see your personal repo +at https://git.rtems.org/@USER@/rtems.git/ and you can create other +repositories in your git directory that will propagate +to https://git.rtems.org/@USER@/ if you need. For example, `joel`'s personal +repos appear at https://git.rtems.org/joel/. + + +.. figure:: ../images/eng/Git-personalrepo.png + :width: 50% + :align: center + :alt: Git Personal Repositories + +Check your setup +~~~~~~~~~~~~~~~~ + +.. code-block:: shell + + git remote show origin + +Should print something similar to + +.. code-block:: shell + + * remote origin + Fetch URL: ssh://user@dispatch.rtems.org/home/user/git/rtems.git + Push URL: ssh://user@dispatch.rtems.org/home/user/git/rtems.git + HEAD branch: master + Remote branches: + 4.10 tracked + 4.8 tracked + 4.9 tracked + master tracked + Local branch configured for 'git pull': + master merges with remote master + Local ref configured for 'git push': + master pushes to master (up to date) + +Push commits to personal repo master from local master +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: shell + + # git push + +Push a branch onto personal repo +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: shell + + # git push origin branchname + +Update from upstream master (RTEMS head) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + When you have committed changes on a branch that is private (hasn't been + pushed to your personal repo) then you can use rebase to obtain a linear + history and avoid merge commit messages. + +.. code-block:: shell + + # git checkout new_features + # git pull --rebase upstream master + +If you cannot do a fast-forward merge then you could use the ``--no-commit`` +flag to prevent merge from issuing an automatic merge commit message. + +When you have committed changes on a branch that is public/shared with another +developer you should not rebase that branch. + +GIT Push Configuration +---------------------- + +People with write access to the main repository should make sure that they +push the right branch with the git push command. The above setup ensures +that git push will not touch the main repository, which is identified as +upstream, unless you specify the upstream (by ``git push upstream master``). + +Lets suppose we have a test branch intended for integration into the master +branch of the main repository. + +.. code-block:: shell + + # git branch + master + * test + +There are two options for pushing with the branch. First, + +.. code-block:: shell + + # git push origin test + +Will push the test branch to the personal repository. To delete the remote +branch + +.. code-block:: shell + + # git push origin :test + +You'll still need to delete your local branch if you are done with it. + +If you are going to work exclusively with one branch for a while, you might +want to configure git to automatically push that branch when you use git push. +By default git push will use the local master branch, but you can use the +`test` branch as the source of your changes: + +.. code-block:: shell + + # git config remote.origin.push test:master + +Now git push will merge into your master branch on your personal repository. +You can also setup a remote branch: + +.. code-block:: shell + + # git config remote.origin.push test:test + +You can see what branch is configured for pushing with + +.. code-block:: shell + + # git remote show origin + +And reset to the default + +.. code-block:: shell + + # git config remote.origin.push master + +Pull a Developer's Repo +----------------------- + +The procedures for creating personal repositories ensure that every developer +can post branches that anyone else can review. To pull a developer's personal +repository into your local RTEMS git clone, just add a new remote repo: + +.. code-block:: shell + + # git remote add devname git://dispatch.rtems.org/devname/rtems.git + # git fetch devname + # git remote show devname + # git branch -a + +Replace devname with the developer's user name on git, which you can see by +accessing https://git.rtems.org. Now you can switch to the branches +for this developer. + +Use a tracking branch if the developer's branch is changing: + +.. code-block:: shell + + # git branch --track new_feature devname/new_feature + +Committing +---------- + +Ticket Updates +~~~~~~~~~~~~~~ + +Our trac instance supports updating a related ticket with the commit message. + +Any references to a ticket for example #1234 will insert the message into +he ticket as an 'update'. No command is required. + +Closing a ticket can be done by prefixing the ticket number with any of the +following commands: + +``close``, ``closed``, ``closes``, ``fix``, ``fixed``, or ``fixes`` + +For example: + +``closes #1234`` + +``This is a random update it closes #1234 and updates #5678`` + +Commands +~~~~~~~~ + +When merging someone's work, whether your own or otherwise, we have some +suggested procedures to follow. + +* Never work in the master branch. Checkout a new branch and apply + patches/commits to it. +* Before pushing upstream: + - Update master by fetching from the server + - Rebase the working branch against the updated master + - Push the working branch to the server master + +The basic workflow looks like + +.. code-block:: shell + + # git checkout -b somebranch upstream/master + # patch .. git add/rm/etc + # git commit ... + # git pull --rebase upstream master + # git push upstream somebranch:master + +If someone pushed since you updated the server rejects your push until you +are up to date. + +For example a workflow where you will commit a series of patches from +``../patches/am/`` directory: + +.. code-block:: shell + + # git checkout -b am + # git am ../patches/am* + # git pull --rebase upstream master + # git push upstream am:master + # git checkout master + # git pull upstream master + # git log + # git branch -d am + # git push + +The git log stage will show your newly pushed patches if everything worked +properly, and you can delete the am branch created. The git push at the end +will push the changes up to your personal repository. + +Another way to do this which pushes directly to the upstream is shown here +in an example which simply (and quickly) applies a patch to the branch: + +.. code-block:: shell + + git checkout -b rtems4.10 --track remotes/upstream/4.10 + cat /tmp/sp.diff | patch + vi sparc.t + git add sparc.t + git commit -m "sparc.t: Correct for V8/V9" + git push upstream rtems4.10:4.10 + git checkout master + git log + git branch -d rtems4.10 + +Pushing Multiple Commits +------------------------ + +A push with more than one commit results in Trac missing them. Please use the +following script to push a single commit at a time: + +.. code-block:: shell + + #! /bin/sh + commits=$(git log --format='%h' origin/master..HEAD | tail -r) + for c in $commits + do + cmd=$(echo $c | sed 's%\(.*\)%git push origin \1:master%') + echo $cmd + $cmd + done + +Ooops! +------ + +So you pushed something upstream and broke the repository. First things first: +stop what you're doing and notify devel@... so that (1) you can get help and +(2) no one pulls from the broken repo. For an extended outage also notify +users@.... Now, breathe easy and let's figure out what happened. One thing +that might work is to just `undo the push +`_. To get an +idea of what you did, run ``git reflog``, which might be useful for getting +assistance in undoing whatever badness was done. diff --git a/images/eng/Git-personalrepo.png b/images/eng/Git-personalrepo.png new file mode 100644 index 0000000..751499a Binary files /dev/null and b/images/eng/Git-personalrepo.png differ -- cgit v1.2.3 From e1eac627d7dddebaea432bb43f6d22f9cc4e3b10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=A7al=20Comajoan=20Cara?= Date: Mon, 3 Dec 2018 18:01:40 +0100 Subject: eng/vc-users: Convert wiki page to Rest (GCI 2018) Converted https://devel.rtems.org/wiki/Developer/Git/Users to Rest, and TBDs and wiki TODOs into comments. Also changed http links to https (the ones that are possible), corrected typos, updated learning resources links and added formattings. This work was part of GCI 2018. --- eng/vc-users.rst | 643 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 641 insertions(+), 2 deletions(-) diff --git a/eng/vc-users.rst b/eng/vc-users.rst index ebd79bb..efa29e0 100644 --- a/eng/vc-users.rst +++ b/eng/vc-users.rst @@ -7,5 +7,644 @@ Software Development (Git Users) ******************************** -TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Users to Rest -TBD - and insert here. +.. COMMENT: TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Users to +.. COMMENT: TBD - Rest and insert here. + +.. COMMENT: TBD - Managing a (private/public) Git mirror, using GitHub, +.. COMMENT: TBD - submitting pull requests... + +Browse the Git Repository Online +-------------------------------- + +You can browse all available repositories online by +accessing https://git.rtems.org/. + +Using the Git Repository +------------------------ + +The following examples demonstrate how to use the RTEMS' Git repos. These +examples are provided for the main rtems module, but they are also valid +for the other modules. + +First, we need to obtain our own local copy of the RTEMS Git repository: + +.. code-block:: shell + + git clone git://git.rtems.org/rtems.git rtems + +This command will create a folder named rtems in the current directory. This +folder will contain a full-featured RTEMS' Git repository and the current HEAD +revision checked out. Since all the history is available we can check out any +release of RTEMS. Major RTEMS releases are available as separate branches in +the repo. + +To see all available remote branches issue the following command: + +.. code-block:: shell + + git branch -r + +We can check out one of those remote branches (e.g. rtems-4.10 branch) using +the command: + +.. code-block:: shell + + git checkout -b rtems410 origin/4.10 + +This will create a local branch named "rtems410", containing the rtems-4.10 +release, that will track the remote branch "rtems-4-10-branch" in origin +(​git://git.rtems.org/rtems.git). The ``git branch`` command prints a list of +the current local branches, indicating the one currently checked out. + +If you want to switch between local branches: + +.. code-block:: shell + + git checkout + +With time your local repository will diverge from the main RTEMS repository. To +keep your local copy up to date you need to issue: + +.. code-block:: shell + + git pull origin + +This command will update all your local branches with any new code revisions +available on the central repository. + +Making Changes +-------------- + +Git allows you to make changes in the RTEMS source tree and track those changes +locally. We recommend you make all your changes in local branches. If you are +working on a few different changes or a progression of changes it is best to +use a local branch for each change. + +A branch for each change lets your repo's master branch track the upstream +RTEMS' master branch without interacting with any of the changes you are +working on. A completed change is emailed to the developer's list for review +and this can take time. While this is happening the upstream's master branch +may be updated and you may need to rebase your work and test again if you are +required to change or update your patch. A local branch isolates a specific +change from others and helps you manage the process. + +First, you need to clone the repository: + +.. code-block:: shell + + git clone git://git.rtems.org/rtems.git rtems + +Or if you already cloned it before, then you might want to update to the latest +version before making your changes: + +.. code-block:: shell + + cd rtems + git pull + +Create a local branch to make your changes in, in this example, the change is +``faster-context-switch``: + +.. code-block:: shell + + git checkout -b faster-context-switch + +Next, make your changes to files. If you add, delete ormove/rename files you +need to inform Git + +.. code-block:: shell + + git add /some/new/file + git rm /some/old/file + git mv /some/old/file /some/new/file + +When you're satisfied with the changes you made, commit them (locally) + +.. code-block:: shell + + git commit -a + +The ``-a`` flag commits all the changes that were made, but you can also +control which changes to commit by individually adding files as you modify +them by using. You can also specify other options to commit, such as a message +with the ``-m`` flag. + +.. code-block:: shell + + git add /some/changed/files + git commit + +Create a patch from your branch, in this case, we have two commits we want to +send for review: + +.. code-block:: shell + + git format-patch -2 + + There are new changes pushed to the RTEMS' master branch and our local branch + needs to be updated: + +.. code-block:: shell + + git checkout master + git pull + git checkout faster-context-switch + git rebase master + +Working with Branches +--------------------- + +Branches facilitate trying out new code and creating patches. + +The previous releases of RTEMS are available through remote branches. To check +out a remote branch, first query the Git repository for the list of branches: + +.. code-block:: shell + + git branch -r + +Then check out the desired remote branch, for example: + +.. code-block:: shell + + git checkout -b rtems410 origin/4.10 + +Or if you have previously checked out the remote branch then you should see it +in your local branches: + +.. code-block:: shell + + git branch + +You can change to an existing local branch easily: + +.. code-block:: shell + + git checkout rtems410 + +You can also create a new branch and switch to it: + +.. code-block:: shell + + git branch temporary + git checkout temporary + +Or more concisely: + +.. code-block:: shell + + git checkout -b temporary + +If you forget which branch you are on + +.. code-block:: shell + + git branch + +shows you by placing a * next to the current one. + +When a branch is no longer useful you can delete it. + +.. code-block:: shell + + git checkout master + git branch -d temporary + +If you have unmerged changes in the old branch Git complains and you need to +use ``-D`` instead of ``-d``. + +Viewing Changes +--------------- + +To view all changes since the last commit: + +.. code-block:: shell + + git diff HEAD + +To view all changes between the current branch and another branch, say master: + +.. code-block:: shell + + git diff master..HEAD + +To view descriptions of committed changes: + +.. code-block:: shell + + git log + +Or view the changeset for some file (or directory): + +.. code-block:: shell + + git log /some/file + +To view the changesets made between two branches: + +.. code-block:: shell + + git log master..HEAD + +Or for a more brief description use shortlog: + +.. code-block:: shell + + git shortlog master..HEAD + +Reverting Changes +----------------- + +To remove all (uncommitted) changes on a branch + +.. code-block:: shell + + git checkout -f + +Or to selectively revert (uncommited) files, for example if you +accidentally deleted ./some/file + +.. code-block:: shell + + git checkout -- ./some/file + +or + +.. code-block:: shell + + git checkout HEAD ./some/file + +To remove commits there are two useful options, reset and revert. ``git reset`` +should only be used on local branches that no one else is accessing remotely. +``git revert`` is cleaner and is the right way to revert changes that have +already been pushed/pulled remotely. + +git reset +--------- + +``git reset`` is a powerful and tricky command that should only be used on +local (un-pushed) branches): A good description of what it enables to do can be +found ​here. The following are a few useful examples. Note that adding a ~ +after HEAD refers to the most recent commit, and you can add a number after +the ~ to refer to commits even further back; HEAD by itself refers to the +current working directory (changes since the last commit). + +.. code-block:: shell + + git reset HEAD~ + +Will undo the last commit and unstage those changes. Your working directory +will remain the same, therefore a ``git status`` will yield any changes you +made plus the changes made in your last commit. This can be used to fix the +last commit. You will need to add the files again. + +.. code-block:: shell + + git reset --soft HEAD~ + +Will just undo the last commit. The changes from the last commit will still be +staged (just as if you finished git adding them). This can be used to amend the +last commit (e.g. You forgot to add a file to the last commit). + +.. code-block:: shell + + git reset --hard HEAD~ + +Will revert everything, including the working directory, to the previous +commit. This is dangerous and can lead to you losing all your changes; the +``--hard`` flag ignores errors. + +.. code-block:: shell + + git reset HEAD + +Will unstage any change. This is used to revert a wrong ``git add``. (e.g. You +added a file that shouldn't be there, but you haven't 'committed') + +Will revert your working directory to a HEAD state. You will lose any change +you made to files after the last commit. This is used when you just want to +destroy all changes you made since the last commit. + +git revert +---------- + +``git revert`` does the same as reset but creates a new commit with the +reverted changes instead of modifying the local repository directly. + +.. code-block:: shell + + git revert HEAD + +This will create a new commit which undoes the change in HEAD. You will be +given a chance to edit the commit message for the new commit. + +Merging Changes +--------------- + +Suppose you commit changes in two different branches, branch1 and branch2, +and want to create a new branch containing both sets of changes: + +.. code-block:: shell + + git checkout -b merged + git merge branch1 + git merge branch2 + +Or you might want to bring the changes in one branch into the other: + +.. code-block:: shell + + git checkout branch1 + git merge branch2 + +And now that branch2 is merged you might get rid of it: + +.. code-block:: shell + + git branch -d branch2 + +If you have done work on a branch, say branch1, and have gone out-of-sync +with the remote repository, you can pull the changes from the remote repo and +then merge them into your branch: + +.. code-block:: shell + + git checkout master + git pull + git checkout branch1 + git merge master + +If all goes well the new commits you pulled into your master branch will be +merged into your branch1, which will now be up-to-date. However, if branch1 +has not been pushed remotely then rebasing might be a good alternative to +merging because the merge generates a commit. + +Rebasing +-------- + +An alternative to the merge command is rebase, which replays the changes +(commits) on one branch onto another. ``git rebase`` finds the common ancestor +of the two branches, stores each commit of the branch you’re on to temporary +files and applies each commit in order. + +For example + +.. code-block:: shell + + git checkout branch1 + git rebase master + +or more concisely + +.. code-block:: shell + + git rebase master branch1 + +will bring the changes of master into branch1, and then you can fast-forward +master to include branch1 quite easily + +.. code-block:: shell + + git checkout master + git merge branch1 + +Rebasing makes a cleaner history than merging; the log of a rebased branch +looks like a linear history as if the work was done serially rather than in +parallel. A primary reason to rebase is to ensure commits apply cleanly on a +remote branch, e.g. when submitting patches to RTEMS that you create by working +on a branch in a personal repository. Using rebase to merge your work with the +remote branch eliminates most integration work for the committer/maintainer. + +There is one caveat to using rebase: Do not rebase commits that you have pushed +to a public repository. Rebase abandons existing commits and creates new ones +that are similar but different. If you push commits that others pull down, and +then you rewrite those commits with ``git rebase`` and push them up again, the +others will have to re-merge their work and trying to integrate their work +into yours can become messy. + +Accessing a developer's repository +---------------------------------- + +RTEMS developers with Git commit access have personal repositories +on https://git.rtems.org/ that can be cloned to view cutting-edge +development work shared there. + +Creating a Patch +---------------- + +Before submitting a patch read about `Contributing +`_ to RTEMS and the +`Commit Message `_ +formatting we require. + +The recommended way to create a patch is to branch the Git repository master +and use one commit for each logical change. Then you can use +``git format-patch`` to turn your commits into patches and easily submit them. + +.. code-block:: shell + + git format-patch master + +Creates a separate patch for each commit that has been made between the master +branch and the current branch and writes them in the current directory. Use the +``-o`` flag to redirect the files to a different directory. + +If you are re-submitting a patch that has previously been reviewed, you should +specify a version number for your patch, for example, use + +.. code-block:: shell + + git format-patch -v2 ... + +to indicate the second version of a patch, ``-v3`` for a third, and so forth. + +Patches created using ``git format-patch`` are formatted so they can be emailed +and rely on having Git configured with your name and email address, for example + +.. code-block:: shell + + git config --global user.name "Your Name" + git config --global user.email name@domain.com + +Please use a real name, we do not allow pseudonyms or anonymous contributions. + +Submitting a Patch +------------------ + +Using ``git send-email`` you can easily contribute your patches. You will need +to install ``git send-email`` first: + +.. code-block:: shell + + sudo yum install git-email + +or + +.. code-block:: shell + + sudo dnf install git-email + +or + +.. code-block:: shell + + sudo apt install git-email + +Then you will need to configure an SMTP server. You could install one on your +localhost, or you can connect to a mail server such as Gmail. + +Configuring git send-email to use Gmail +--------------------------------------- + +Configure Git to use Gmail: + +.. code-block:: shell + + git config --global sendemail.smtpserver smtp.gmail.com + git config --global sendemail.smtpserverport 587 + git config --global sendemail.smtpencryption tls + git config --global sendemail.smtpuser your_email@gmail.com + +It will ask for your password each time you use ``git send-email``. Optionally +you can also put it in your ``git config``: + +.. code-block:: shell + + git config --global sendemail.smtppass your_password + +Sending Email +------------- + +To send your patches just + +.. code-block:: shell + + git send-email /path/to/patch --to devel@rtems.org + +To send multiple related patches (if you have more than one commit in your +branch) specify a path to a directory containing all of the patches created by +``git format-patch``. ``git send-email`` has some useful options such as: + +* ``--annotate`` to show/edit your patch +* ``--cover-letter`` to prepend a summary +* ``--cc=
`` to cc someone + +You can configure the to address: + +.. code-block:: shell + + git config --global sendemail.to devel@rtems.org + +So all you need is: + +.. code-block:: shell + + git send-email /path/to/patch + +Troubleshooting +--------------- + +Some restrictive corporate firewalls block access through the Git protocol +(​git://). If you are unable to reach the server ​git://git.rtems.org/ you can +try accessing through http. To clone the rtems repository using the http +protocol use the following command: + +.. code-block:: shell + + git clone http://git.rtems.org/rtems/ rtems + +This access through http is slower (way slower!) than through the git protocol, +therefore, the Git protocol is preferred. + +Manage Your Code +---------------- + +You may prefer to keep your application and development work in a Git +repository for all the good reasons that come with version control. +For public repositories, you may like to try `GitHub `_ +or `BitBucket `_. RTEMS maintains +`mirrors on GitHub `_ which can make synchronizing +with upstream changes relatively simple. If you need to keep your work private, +you can use one of those services with private repositories or manage your own +server. The details of setting up a server are outside the scope of this +document, but if you have a server with SSH access you should be able to `find +instructions +`_ on +how to set up Git access. Once you have git configured on the server, adding +repositories is a snap. + +Private Servers +--------------- + +In the following, replace @USER@ with your username on your server, @REPO@ with +the name of your repository, and @SERVER@ with your server's name or address. + +To push a mirror to your private server, first create a bare repository on your +server. + +.. code-block:: shell + + cd /home/@USER@ + mkdir git + mkdir git/@REPO@.git + cd git/@REPO@.git + git --bare init + +Now from your client machine (e.g. your work laptop/desktop), push a git, +perhaps one you cloned from elsewhere, or one that you made locally with +``git init``, by adding a remote and pushing: + +.. code-block:: shell + + git remote add @SERVER@ ssh://@SERVER@/home/@USER@/git/@REPO@.git + git push @SERVER@ master + +You can replace the @SERVER@ with another name for your remote if you like. +And now you can push other branches that you might have created. Now you can +push and pull between your client and your server. Use SSH keys to authenticate +with your server if you want to save on password typing; remember to put a +passphrase on your SSH key if there is a risk the private key file might get +compromised. + +The following is an example scenario that might be useful for RTEMS users that +uses a slightly different approach than the one just outlined: + +.. code-block:: shell + + ssh @SERVER@ + mkdir git + git clone --mirror git://git.rtems.org/rtems.git + ## Add your ssh key to ~/.ssh/authorized_keys + exit + git clone ssh://@SERVER@/home/@USER@/git/rtems.git + cd rtems + git remote add upstream git://git.rtems.org/rtems.git + git fetch upstream + git pull upstream master + git push + ## If you want to track RTEMS on your personal master branch, + ## you should only push changes to origin/master that you pull + ## from upstream. The basic workflow should look something like: + git checkout master + git pull upstream master + git push + git checkout -b anewbranch + ## Repeat: do work, git commit -a + git push origin anewbranch + + ## delete a remote branch + git push origin :anewbranch + ## delete a local branch + git branch -d anewbranch + +Learn more about Git +-------------------- + +Links to the sites with good Git information: + +* http://gitready.com/ - An excellent resource from beginner to very advanced. +* http://progit.org/book/ - Covers Git basics and some advanced features. + Includes some useful workflow examples. +* https://lab.github.com/ - Learn to use Git and GitHub while doing a series of + projects. +* https://git-scm.com/docs - The official Git reference. -- cgit v1.2.3 From 2bcf84f72dc8efa8d25717bae9379233825f4bf1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=A7al=20Comajoan=20Cara?= Date: Mon, 3 Dec 2018 19:38:13 +0100 Subject: images/eng/Git-personalrepo: Redrawn image (GCI 2018) Redraw images/eng/Git-personalrepo as SVG and PNG with a better color palette. --- images/eng/Git-personalrepo.png | Bin 24895 -> 52677 bytes images/eng/Git-personalrepo.svg | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+) create mode 100644 images/eng/Git-personalrepo.svg diff --git a/images/eng/Git-personalrepo.png b/images/eng/Git-personalrepo.png index 751499a..f4622da 100644 Binary files a/images/eng/Git-personalrepo.png and b/images/eng/Git-personalrepo.png differ diff --git a/images/eng/Git-personalrepo.svg b/images/eng/Git-personalrepo.svg new file mode 100644 index 0000000..b0a5d24 --- /dev/null +++ b/images/eng/Git-personalrepo.svg @@ -0,0 +1,33 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- cgit v1.2.3 From 9cdcc1377a8e2f4a1be48ee874e729957890f458 Mon Sep 17 00:00:00 2001 From: Pritish Jain Date: Tue, 4 Dec 2018 05:10:47 +0530 Subject: coding-naming: Convert TBD to Rest format (GCI 2018) --- eng/coding-naming.rst | 87 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 85 insertions(+), 2 deletions(-) diff --git a/eng/coding-naming.rst b/eng/coding-naming.rst index 054dd5d..4fb4e7c 100644 --- a/eng/coding-naming.rst +++ b/eng/coding-naming.rst @@ -6,5 +6,88 @@ Naming Rules ************ -TBD - Convert the following to Rest and insert into this file -TBD - https://devel.rtems.org/wiki/Developer/Coding/NamingRules +.. COMMENT:TBD - Convert the following to Rest and insert into this file +.. COMMENT:TBD - https://devel.rtems.org/wiki/Developer/Coding/NamingRules + +General Rules +------------- + + * Avoid abbreviations. + + * Exception: when the abbreviation is more common than the full word. + * Exception: For well-known acronyms. + + * Use descriptive language. + * File names should be lower-case alphabet letters only, plus the extension. + Avoid symbols in file names. + * Prefer to use underscores to separate words, rather than + `CamelCase `_.or !TitleCase. + * Local-scope variable names are all lower case with underscores between words. + * CPP macros are all capital letters with underscores between words. + * Enumerated (enum) values are all capital letters with underscores between + words, but the type name follows the regular rules of other type names. + * Constant (const) variables follow the same rules as other variables. + An exception is that a const that replaces a CPP macro might be all + capital letters for backward compatibility. + * Type names, function names, and global scope names have different rules + depending on whether they are part of the public API or are internal + to RTEMS, see below. + +**User-Facing APIs** + +The public API routines follow a standard API like POSIX or BSD or start +with *rtems_*. If a name starts with *rtems_*, then it should be assumed to be +available for use by the application and be documented in the User's Guide. + +If the method is intended to be private, then make it static to a file or +start the name with a leading _. + +**Classic API** + +* Public facing APIs start with *rtems_* followed by a word or phrase to + indicate the Manager or functional category the method or data type + belongs to. + +* Non-public APIs should be static or begin with a leading _. The required + form is the use of a leading underscore, functional area with leading + capital letter, an underscore, and the method with a leading capital letter. + +**POSIX API** + + * Follow the rules of POSIX. + +**RTEMS Internal Interfaces** + +**Super Core** + +The `Super Core `_. is organized in an +Object-Oriented fashion. Each score Handler is a Package, or Module, +and each Module contains type definitions, functions, etc. +The following summarizes our conventions for using names within +`SuperCore `_. Modules. + + * Use "Module_name_Particular_type_name" for type names. + * Use "_Module_name_Particular_function_name" for functions names. + * Use "_Module_name_Global_or_file_scope_variable_name" for global or + file scope variable names. + +Within a structure: + + * Use "Name" for struct aggregate members. + * Use "name" for reference members. + * Use "name" for primitive type members. + +As shown in the following example: + + .. code-block:: c + + typedef struct { + Other_module_Struct_type Aggregate_member_name; + Other_module_Struct_type *reference_member_name; + Other_module_Primitive_type primitive_member_name; + } The_module_Type_name; + + +**BSP** + + * TODO. -- cgit v1.2.3 From 64426a77e056bad495408744774e76027022b439 Mon Sep 17 00:00:00 2001 From: zehata Date: Mon, 3 Dec 2018 17:40:15 +0800 Subject: Converted Doxygen Best Practices Documentation to Rest format (GCI 2018) --- eng/coding-doxygen.rst | 418 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 417 insertions(+), 1 deletion(-) diff --git a/eng/coding-doxygen.rst b/eng/coding-doxygen.rst index 5aafde0..a75579e 100644 --- a/eng/coding-doxygen.rst +++ b/eng/coding-doxygen.rst @@ -4,7 +4,423 @@ .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project General Doxygen Recommentations -=============================== +------------------------------- TBD - Convert the following to Rest and insert into this file TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen + +Doxygen Best Practices +---------------------- + +* Do not use @a. Instead use @param to document function parameters. +* Do not use @return. Instead use @retval to document return status codes. +* Do not write documentation for trivial functions. +* Do not repeat documentation, use @see for example. +* Do not use @note. +* Use groups and arrange them in a hierarchy. Put every file into at least one group. +* Use dot comments for state diagrams. +* Use one whitespace character after an asterisk. + +Special Notes for Google Code In Students +----------------------------------------- + +* Follow the directions given by the `Google Code In `_ task and this should take care of itself if in doubt ask a mentor and/or tell a mentor the decision you made. + +Header File Example +------------------- + +​`thread.h `_ and `​threadimpl.h `_ should be a good example of how a header file should be written. The following gives details in bits and pieces. + +Header blocks +------------- + +Header files should contain the similar comment blocks as other source files, described at `Boilerplate File Header `_. + + .. code-block:: c + + /** + * @file + * + * @ingroup FlipFlop + * + * @brief Flip-Flop API + */ + + /* + * Copyright (c) YYYY Author. + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * http://www.rtems.com/license/LICENSE. + */ + +Header guard +------------ + +After the comment blocks, use a header guard that assembles at least the include path of the file. For example, if flipflop.h is in then + + .. code-block:: c + + #ifndef RTEMS_LIB_FLIP_FLOP_H + #define RTEMS_LIB_FLIP_FLOP_H + +Includes +-------- + +Then add your include files before protecting C declarations from C++. + + + .. code-block:: c + + #include + + #ifdef __cplusplus + extern "C" { + #endif /* __cplusplus */ + +Using @defgroup for group definitions +------------------------------------- + +Add any group definitions surrounding the function declarations that belong in that group. Rarely, a header may define more than one group. Here we use a dot diagram. + + + .. code-block:: c + + /** + * @defgroup FlipFlop Flip-Flop + * + * @brief Simple Flip-Flop state machine. + * + * @dot + * digraph { + * start [label="START"]; + * flip [label="FLIP"]; + * flop [label="FLOP"]; + * flip -> flop [label="flop()", URL="\ref flop"]; + * flop -> flip [label="flip()", URL="\ref flip"]; + * start -> flip + * [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"]; + * start -> flop + * [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"]; + * flip -> start + * [label="flip_flop_restart()", URL="\ref flip_flop_restart"]; + * } + * @enddot + * + * @{ + */ + +enum and struct +--------------- + +Provide documentation for declarations of enumerated types and structs. Use typedefs for structs, and do not use _t as a typename suffix. + + + .. code-block:: c + + /** + * @brief The set of possible flip-flop states. + * + * Enumerated type to define the set of states for a flip-flop. + */ + typedef enum { + START = 0, + FLIP, + FLOP + } flip_flop_state; + + /** + * @brief Object containing multiple flip-flops. + * + * Encapsulates multiple flip-flops. + */ + typedef struct { + /** + * @brief Primary flip-flop. + */ + flip_flop_state primary; + /** + * @brief Secondary flip-flop. + */ + flip_flop_state secondary; + } flip_flop_multiple; + + +Using @name for organization +---------------------------- + +Complicated groups can be given additional organization by using @name, or by declaring additional groups within the hierarchy of the header file's top-level group. + + .. code-block:: c + + /** + * @name Flip-Flop Maintenance + * + * @{ + */ + +Declaring functions +------------------- + +Function declarations should have an @brief that states what the function does in a single topic sentence starting with a descriptive verb in the present tense. + + + .. code-block:: c + /** + * @brief Initializes the flip-flop state. + * + * @param[in] state The initial state to set the flip-flop. + * + * @retval RTEMS_SUCCESSFUL Successfully initialized. + * @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid. + */ + rtems_status_code flip_flop_initialize(flip_flop_state state); + + /** + * @brief Restarts the flip-flop. + * + * @retval RTEMS_SUCCESSFUL Successfully restarted. + * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state. + */ + rtems_status_code flip_flop_restart(void); + +Do not document trivial functions, such as getter/setter methods. + + .. code-block:: c + flip_flop_state flip_flop_current_state(void); + +Close the documentation name definition and open a new name definition. + + .. code-block:: c + /** @} */ + + /** + * @name Flip-Flop Usage + * + * @{ + */ + + /** + * @brief Flip operation. + * + * @retval RTEMS_SUCCESSFUL Flipped successfully. + * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation. + */ + rtems_status_code flip( void ); + + /** + * @brief Flop operation. + * + * @retval RTEMS_SUCCESSFUL Flopped successfully. + * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation. + */ + rtems_status_code flop( void ); + + /** @} */ + +Ending the file +--------------- + +Close the documentation group definition, then the extern C declarations, then the header guard. + + .. code-block:: c + /** @} */ + + #ifdef __cplusplus + } + #endif /* __cplusplus */ + + #endif /* RTEMS_LIB_FLIP_FLOP_H */ + +No newline at the end of the file. + +Source File Example +------------------- + + .. code-block:: c + + /** + * @file + * + * @ingroup FlipFlop + * + * @brief Flip-Flop implementation. + */ + + /* + * Copyright (c) YYYY Author. + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * http://www.rtems.com/license/LICENSE. + */ + + #include + + static flip_flop_state current_state; + + rtems_status_code flip_flop_initialize(flip_flop_state state) + { + if (current_state == START) { + current_state = state; + + return RTEMS_SUCCESSFUL; + } else { + return RTEMS_INCORRECT_STATE; + } + } + + rtems_status_code flip_flop_restart(void) + { + if (current_state == FLIP) { + current_state = START; + + return RTEMS_SUCCESSFUL; + } else { + return RTEMS_INCORRECT_STATE; + } + } + + flip_flop_state flip_flop_current_state(void) + { + return current_state; + } + + rtems_status_code flip(void) + { + if (current_state == FLOP) { + current_state = FLIP; + + return RTEMS_SUCCESSFUL; + } else { + return RTEMS_INCORRECT_STATE; + } + } + + rtems_status_code flop(void) + { + if (current_state == FLIP) { + current_state = FLOP; + + return RTEMS_SUCCESSFUL; + } else { + return RTEMS_INCORRECT_STATE; + } + } + +Files +----- + +Document files with the @file directive omitting the optional filename argument. Doxygen will infer the filename from the actual name of the file. Within one Doxygen run all files are unique and specified by the current Doxyfile. We can define how the generated output of path and filenames looks like in the Doxyfile via the FULL_PATH_NAMES, STRIP_FROM_PATH and STRIP_FROM_INC_PATH options. + +Functions +--------- + +For documentation of function arguments there are basically to ways: The first one uses @param: + + .. code-block:: + /** + * @brief Copies from a source to a destination memory area. + * + * The source and destination areas may not overlap. + * + * @param[out] dest The destination memory area to copy to. + * @param[in] src The source memory area to copy from. + * @param[in] n The number of bytes to copy. + */ + The second is to use @a param in descriptive text, for example: + + /** + * Copies @a n bytes from a source memory area @a src to a destination memory + * area @a dest, where both areas may not overlap. + */ + +The @a indicates that the next word is a function argument and deserves some kind of highlighting. However, we feel that @a buries the usage of function arguments within description text. In RTEMS sources, we prefer to use @param instead of @a. + +Doxyfile Hints +-------------- + +Header Files +------------ + +It is an RTEMS build feature that header files need to be installed in order to be useful. One workaround to generate documentation which allows automatic link generation is to use the installed header files as documentation input. Assume that we have the RTEMS sources in the rtems directory and the build of our BSP in build/powerpc-rtems5/mybsp relative to a common top-level directory. Then you can configure Doxygen like: + + + .. code-block:: + INPUT = rtems/bsps/powerpc/mybsp \ + rtems/c/src/lib/libcpu/powerpc/mycpu \ + rtems/make/custom/mybsp.cfg \ + build/powerpc-rtems5/mybsp/lib/include/myincludes + + RECURSIVE = YES + + EXCLUDE = rtems/bsps/powerpc/mybsp/include \ + rtems/c/src/lib/libcpu/powerpc/mycpu/include + + FULL_PATH_NAMES = YES + + STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \ + rtems + +Script and Assembly Files +------------------------- + +Doxygen cannot cope with script (= files with #-like comments) or assembly files. But you can add filter programs for them (TODO: Add source code for filter programs somewhere): + + .. code-block:: + FILTER_PATTERNS = *.S=c-comments-only \ + *.s=c-comments-only \ + *.cfg=script-comments-only \ + *.am=script-comments-only \ + *.ac=script-comments-only + +Assembly Example +---------------- + + .. code-block:: + /** + * @fn void mpc55xx_fmpll_reset_config() + * + * @brief Configure FMPLL after reset. + * + * Sets the system clock from 12 MHz in two steps up to 128 MHz. + */ + GLOBAL_FUNCTION mpc55xx_fmpll_reset_config + /* Save link register */ + mflr r3 + + LA r4, FMPLL_SYNCR + +You have to put a declaration of this function somewhere in a header file. + +Script Example +-------------- + + .. code-block:: + ## + # + # @file + # + # @ingroup mpc55xx_config + # + # @brief Configure script of LibBSP for the MPC55xx evaluation boards. + # + + AC_PREREQ(2.60) + AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla]) + +GCC Attributes +-------------- + +The Doxygen C/C++ parser cannot cope with the GCC attribute((something)) stuff. But you can discard such features with pre-defined preprocessor macros: + + .. code-block:: + ENABLE_PREPROCESSING = YES + MACRO_EXPANSION = YES + EXPAND_ONLY_PREDEF = YES + PREDEFINED = __attribute__(x)= + +History +------- + +RTEMS is much older than ​`Doxygen `_ and the documentation in the .h and .inl files was obviously not written with ​`Doxygen markup `_. In 2007, `JoelSherrill `_ undertook to convert the documentation in the .h and .inl files in the RTEMS SuperCore? to Doxygen format. As a result of this effort, the Doxygen for the development version of the RTEMSSuperCore is now built automatically multiple times per day and made available on the RTEMS Website. In April 2008, `JoelSherrill `_ began to update the Classic API (e.g. cpukit/rtems) .h and .inl files to include `​Doxygen markup `_. -- cgit v1.2.3 From bd60bbc56ee347d5588cfea68d1da75238a23d41 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 4 Dec 2018 13:21:54 -0600 Subject: eng/coding-doxygen.rst: Clean up and make subsubsections --- eng/coding-doxygen.rst | 681 ++++++++++++++++++++++++++----------------------- 1 file changed, 364 insertions(+), 317 deletions(-) diff --git a/eng/coding-doxygen.rst b/eng/coding-doxygen.rst index a75579e..49c53bb 100644 --- a/eng/coding-doxygen.rst +++ b/eng/coding-doxygen.rst @@ -9,8 +9,21 @@ General Doxygen Recommentations TBD - Convert the following to Rest and insert into this file TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen +.. sidebar:: *History* + + RTEMS is much older than Doxygen (http://www.doxygen.org/) and + the documentation in the .h files was obviously not written with + Doxygen markup in mind. In 2007, Joel Sherrill undertook to convert the + documentation in the .h and .inl files in the RTEMS SuperCore? to Doxygen + format. As a result of this effort, the Doxygen for the development + version of the RTEMS is now built automatically periodically and made + available on the RTEMS Website. In April 2008, Joel Sherrill began to + update the Classic API (e.g. cpukit/rtems) .h files to include Doxygen + markup. Now, RTEMS has nice Doxygen markup including state and sequence + diagrams. + Doxygen Best Practices ----------------------- +^^^^^^^^^^^^^^^^^^^^^^ * Do not use @a. Instead use @param to document function parameters. * Do not use @return. Instead use @retval to document return status codes. @@ -22,405 +35,439 @@ Doxygen Best Practices * Use one whitespace character after an asterisk. Special Notes for Google Code In Students ------------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* Follow the directions given by the `Google Code In `_ task and this should take care of itself if in doubt ask a mentor and/or tell a mentor the decision you made. +* Follow the directions given by the `Google Code In +`_ task and this should take care +of itself if in doubt ask a mentor and/or tell a mentor the decision +you made. Header File Example -------------------- +^^^^^^^^^^^^^^^^^^^ -​`thread.h `_ and `​threadimpl.h `_ should be a good example of how a header file should be written. The following gives details in bits and pieces. +The files *thread.h* +(https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/thread.h) +and *threadimpl.h* +(https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/threadimpl.h) +should be a good example of how a header file should be written. The +following gives details in bits and pieces. Header blocks -------------- +^^^^^^^^^^^^^ Header files should contain the similar comment blocks as other source files, described at `Boilerplate File Header `_. - .. code-block:: c - - /** - * @file - * - * @ingroup FlipFlop - * - * @brief Flip-Flop API - */ - - /* - * Copyright (c) YYYY Author. - * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.com/license/LICENSE. - */ - -Header guard ------------- + .. code-block:: c + + /** + * @file + * + * @ingroup FlipFlop + * + * @brief Flip-Flop API + */ + + /* + * Copyright (c) YYYY Author. + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * http://www.rtems.com/license/LICENSE. + */ -After the comment blocks, use a header guard that assembles at least the include path of the file. For example, if flipflop.h is in then +Header Guard +^^^^^^^^^^^^ - .. code-block:: c +After the comment blocks, use a header guard that assembles at +least the include path of the file. For example, if flipflop.h is in + then - #ifndef RTEMS_LIB_FLIP_FLOP_H - #define RTEMS_LIB_FLIP_FLOP_H + .. code-block:: c + + #ifndef RTEMS_LIB_FLIP_FLOP_H + #define RTEMS_LIB_FLIP_FLOP_H Includes --------- +^^^^^^^^ Then add your include files before protecting C declarations from C++. - .. code-block:: c + .. code-block:: c - #include + #include - #ifdef __cplusplus - extern "C" { - #endif /* __cplusplus */ + #ifdef __cplusplus + extern "C" { + #endif /* __cplusplus */ Using @defgroup for group definitions -------------------------------------- - -Add any group definitions surrounding the function declarations that belong in that group. Rarely, a header may define more than one group. Here we use a dot diagram. - - - .. code-block:: c - - /** - * @defgroup FlipFlop Flip-Flop - * - * @brief Simple Flip-Flop state machine. - * - * @dot - * digraph { - * start [label="START"]; - * flip [label="FLIP"]; - * flop [label="FLOP"]; - * flip -> flop [label="flop()", URL="\ref flop"]; - * flop -> flip [label="flip()", URL="\ref flip"]; - * start -> flip - * [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"]; - * start -> flop - * [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"]; - * flip -> start - * [label="flip_flop_restart()", URL="\ref flip_flop_restart"]; - * } - * @enddot - * - * @{ - */ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Add any group definitions surrounding the function declarations +that belong in that group. Rarely, a header may define more than one +group. Here we use a dot diagram. + + + .. code-block:: c + + /** + * @defgroup FlipFlop Flip-Flop + * + * @brief Simple Flip-Flop state machine. + * + * @dot + * digraph { + * start [label="START"]; + * flip [label="FLIP"]; + * flop [label="FLOP"]; + * flip -> flop [label="flop()", URL="\ref flop"]; + * flop -> flip [label="flip()", URL="\ref flip"]; + * start -> flip + * [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"]; + * start -> flop + * [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"]; + * flip -> start + * [label="flip_flop_restart()", URL="\ref flip_flop_restart"]; + * } + * @enddot + * + * @{ + */ enum and struct ---------------- - -Provide documentation for declarations of enumerated types and structs. Use typedefs for structs, and do not use _t as a typename suffix. - - - .. code-block:: c - - /** - * @brief The set of possible flip-flop states. - * - * Enumerated type to define the set of states for a flip-flop. - */ - typedef enum { - START = 0, - FLIP, - FLOP - } flip_flop_state; - - /** - * @brief Object containing multiple flip-flops. - * - * Encapsulates multiple flip-flops. - */ - typedef struct { - /** - * @brief Primary flip-flop. - */ - flip_flop_state primary; - /** - * @brief Secondary flip-flop. - */ - flip_flop_state secondary; - } flip_flop_multiple; +^^^^^^^^^^^^^^^ + +Provide documentation for declarations of enumerated types and +structs. Use typedefs for structs, and do not use _t as a typename suffix. + + + .. code-block:: c + + /** + * @brief The set of possible flip-flop states. + * + * Enumerated type to define the set of states for a flip-flop. + */ + typedef enum { + START = 0, + FLIP, + FLOP + } flip_flop_state; + + /** + * @brief Object containing multiple flip-flops. + * + * Encapsulates multiple flip-flops. + */ + typedef struct { + /** + * @brief Primary flip-flop. + */ + flip_flop_state primary; + /** + * @brief Secondary flip-flop. + */ + flip_flop_state secondary; + } flip_flop_multiple; Using @name for organization ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Complicated groups can be given additional organization by using @name, or by declaring additional groups within the hierarchy of the header file's top-level group. +Complicated groups can be given additional organization by using @name, +or by declaring additional groups within the hierarchy of the header +file's top-level group. - .. code-block:: c + .. code-block:: c - /** - * @name Flip-Flop Maintenance - * - * @{ - */ + /** + * @name Flip-Flop Maintenance + * + * @{ + */ Declaring functions -------------------- - -Function declarations should have an @brief that states what the function does in a single topic sentence starting with a descriptive verb in the present tense. - - - .. code-block:: c - /** - * @brief Initializes the flip-flop state. - * - * @param[in] state The initial state to set the flip-flop. - * - * @retval RTEMS_SUCCESSFUL Successfully initialized. - * @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid. - */ - rtems_status_code flip_flop_initialize(flip_flop_state state); - - /** - * @brief Restarts the flip-flop. - * - * @retval RTEMS_SUCCESSFUL Successfully restarted. - * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state. - */ - rtems_status_code flip_flop_restart(void); +^^^^^^^^^^^^^^^^^^^ + +Function declarations should have an @brief that states what the function +does in a single topic sentence starting with a descriptive verb in the +present tense. + + + .. code-block:: c + + /** + * @brief Initializes the flip-flop state. + * + * @param[in] state The initial state to set the flip-flop. + * + * @retval RTEMS_SUCCESSFUL Successfully initialized. + * @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid. + */ + rtems_status_code flip_flop_initialize(flip_flop_state state); + + /** + * @brief Restarts the flip-flop. + * + * @retval RTEMS_SUCCESSFUL Successfully restarted. + * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state. + */ + rtems_status_code flip_flop_restart(void); Do not document trivial functions, such as getter/setter methods. - .. code-block:: c - flip_flop_state flip_flop_current_state(void); + .. code-block:: c + + flip_flop_state flip_flop_current_state(void); Close the documentation name definition and open a new name definition. - .. code-block:: c - /** @} */ - - /** - * @name Flip-Flop Usage - * - * @{ - */ - - /** - * @brief Flip operation. - * - * @retval RTEMS_SUCCESSFUL Flipped successfully. - * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation. - */ - rtems_status_code flip( void ); - - /** - * @brief Flop operation. - * - * @retval RTEMS_SUCCESSFUL Flopped successfully. - * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation. - */ - rtems_status_code flop( void ); - - /** @} */ + .. code-block:: c + + /** @} */ + + /** + * @name Flip-Flop Usage + * + * @{ + */ + + /** + * @brief Flip operation. + * + * @retval RTEMS_SUCCESSFUL Flipped successfully. + * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation. + */ + rtems_status_code flip( void ); + + /** + * @brief Flop operation. + * + * @retval RTEMS_SUCCESSFUL Flopped successfully. + * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation. + */ + rtems_status_code flop( void ); + + /** @} */ Ending the file ---------------- +^^^^^^^^^^^^^^^ -Close the documentation group definition, then the extern C declarations, then the header guard. +Close the documentation group definition, then the extern C declarations, +then the header guard. - .. code-block:: c - /** @} */ + .. code-block:: c - #ifdef __cplusplus - } - #endif /* __cplusplus */ + /** @} */ - #endif /* RTEMS_LIB_FLIP_FLOP_H */ + #ifdef __cplusplus + } + #endif /* __cplusplus */ + + #endif /* RTEMS_LIB_FLIP_FLOP_H */ No newline at the end of the file. Source File Example -------------------- - - .. code-block:: c - - /** - * @file - * - * @ingroup FlipFlop - * - * @brief Flip-Flop implementation. - */ - - /* - * Copyright (c) YYYY Author. - * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.com/license/LICENSE. - */ - - #include - - static flip_flop_state current_state; - - rtems_status_code flip_flop_initialize(flip_flop_state state) - { - if (current_state == START) { - current_state = state; - - return RTEMS_SUCCESSFUL; - } else { - return RTEMS_INCORRECT_STATE; - } - } - - rtems_status_code flip_flop_restart(void) - { - if (current_state == FLIP) { - current_state = START; - - return RTEMS_SUCCESSFUL; - } else { - return RTEMS_INCORRECT_STATE; - } - } - - flip_flop_state flip_flop_current_state(void) - { - return current_state; - } - - rtems_status_code flip(void) - { - if (current_state == FLOP) { - current_state = FLIP; - - return RTEMS_SUCCESSFUL; - } else { - return RTEMS_INCORRECT_STATE; - } - } - - rtems_status_code flop(void) - { - if (current_state == FLIP) { - current_state = FLOP; - - return RTEMS_SUCCESSFUL; - } else { - return RTEMS_INCORRECT_STATE; - } - } +^^^^^^^^^^^^^^^^^^^ + + .. code-block:: c + + /** + * @file + * + * @ingroup FlipFlop + * + * @brief Flip-Flop implementation. + */ + + /* + * Copyright (c) YYYY Author. + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * http://www.rtems.com/license/LICENSE. + */ + + #include + + static flip_flop_state current_state; + + rtems_status_code flip_flop_initialize(flip_flop_state state) + { + if (current_state == START) { + current_state = state; + + return RTEMS_SUCCESSFUL; + } else { + return RTEMS_INCORRECT_STATE; + } + } + + rtems_status_code flip_flop_restart(void) + { + if (current_state == FLIP) { + current_state = START; + + return RTEMS_SUCCESSFUL; + } else { + return RTEMS_INCORRECT_STATE; + } + } + + flip_flop_state flip_flop_current_state(void) + { + return current_state; + } + + rtems_status_code flip(void) + { + if (current_state == FLOP) { + current_state = FLIP; + + return RTEMS_SUCCESSFUL; + } else { + return RTEMS_INCORRECT_STATE; + } + } + + rtems_status_code flop(void) + { + if (current_state == FLIP) { + current_state = FLOP; + + return RTEMS_SUCCESSFUL; + } else { + return RTEMS_INCORRECT_STATE; + } + } Files ------ +^^^^^ Document files with the @file directive omitting the optional filename argument. Doxygen will infer the filename from the actual name of the file. Within one Doxygen run all files are unique and specified by the current Doxyfile. We can define how the generated output of path and filenames looks like in the Doxyfile via the FULL_PATH_NAMES, STRIP_FROM_PATH and STRIP_FROM_INC_PATH options. Functions ---------- +^^^^^^^^^ For documentation of function arguments there are basically to ways: The first one uses @param: - .. code-block:: - /** - * @brief Copies from a source to a destination memory area. - * - * The source and destination areas may not overlap. - * - * @param[out] dest The destination memory area to copy to. - * @param[in] src The source memory area to copy from. - * @param[in] n The number of bytes to copy. - */ - The second is to use @a param in descriptive text, for example: - - /** - * Copies @a n bytes from a source memory area @a src to a destination memory - * area @a dest, where both areas may not overlap. - */ + .. code-block:: + + /** + * @brief Copies from a source to a destination memory area. + * + * The source and destination areas may not overlap. + * + * @param[out] dest The destination memory area to copy to. + * @param[in] src The source memory area to copy from. + * @param[in] n The number of bytes to copy. + */ + The second is to use @a param in descriptive text, for example: + + /** + * Copies @a n bytes from a source memory area @a src to a destination memory + * area @a dest, where both areas may not overlap. + */ The @a indicates that the next word is a function argument and deserves some kind of highlighting. However, we feel that @a buries the usage of function arguments within description text. In RTEMS sources, we prefer to use @param instead of @a. Doxyfile Hints --------------- +^^^^^^^^^^^^^^ Header Files ------------ -It is an RTEMS build feature that header files need to be installed in order to be useful. One workaround to generate documentation which allows automatic link generation is to use the installed header files as documentation input. Assume that we have the RTEMS sources in the rtems directory and the build of our BSP in build/powerpc-rtems5/mybsp relative to a common top-level directory. Then you can configure Doxygen like: +TBD - This is out of date since the include file reorganizaiton + +It is an RTEMS build feature that header files need to be installed +in order to be useful. One workaround to generate documentation which +allows automatic link generation is to use the installed header files as +documentation input. Assume that we have the RTEMS sources in the rtems +directory and the build of our BSP in build/powerpc-rtems5/mybsp relative +to a common top-level directory. Then you can configure Doxygen like: + + .. code-block:: - .. code-block:: - INPUT = rtems/bsps/powerpc/mybsp \ - rtems/c/src/lib/libcpu/powerpc/mycpu \ - rtems/make/custom/mybsp.cfg \ - build/powerpc-rtems5/mybsp/lib/include/myincludes + INPUT = rtems/bsps/powerpc/mybsp \ + rtems/c/src/lib/libcpu/powerpc/mycpu \ + rtems/make/custom/mybsp.cfg \ + build/powerpc-rtems5/mybsp/lib/include/myincludes - RECURSIVE = YES + RECURSIVE = YES - EXCLUDE = rtems/bsps/powerpc/mybsp/include \ - rtems/c/src/lib/libcpu/powerpc/mycpu/include + EXCLUDE = rtems/bsps/powerpc/mybsp/include \ + rtems/c/src/lib/libcpu/powerpc/mycpu/include - FULL_PATH_NAMES = YES + FULL_PATH_NAMES = YES - STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \ - rtems + STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \ + rtems Script and Assembly Files -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ -Doxygen cannot cope with script (= files with #-like comments) or assembly files. But you can add filter programs for them (TODO: Add source code for filter programs somewhere): +Doxygen cannot cope with script (= files with #-like comments) or assembly +files. But you can add filter programs for them (TODO: Add source code +for filter programs somewhere): - .. code-block:: - FILTER_PATTERNS = *.S=c-comments-only \ - *.s=c-comments-only \ - *.cfg=script-comments-only \ - *.am=script-comments-only \ - *.ac=script-comments-only + .. code-block:: + + FILTER_PATTERNS = *.S=c-comments-only \ + *.s=c-comments-only \ + *.cfg=script-comments-only \ + *.am=script-comments-only \ + *.ac=script-comments-only Assembly Example ----------------- - - .. code-block:: - /** - * @fn void mpc55xx_fmpll_reset_config() - * - * @brief Configure FMPLL after reset. - * - * Sets the system clock from 12 MHz in two steps up to 128 MHz. - */ - GLOBAL_FUNCTION mpc55xx_fmpll_reset_config - /* Save link register */ - mflr r3 - - LA r4, FMPLL_SYNCR +^^^^^^^^^^^^^^^^ -You have to put a declaration of this function somewhere in a header file. + .. code-block:: -Script Example --------------- + /** + * @fn void mpc55xx_fmpll_reset_config() + * + * @brief Configure FMPLL after reset. + * + * Sets the system clock from 12 MHz in two steps up to 128 MHz. + */ + GLOBAL_FUNCTION mpc55xx_fmpll_reset_config + /* Save link register */ + mflr r3 - .. code-block:: - ## - # - # @file - # - # @ingroup mpc55xx_config - # - # @brief Configure script of LibBSP for the MPC55xx evaluation boards. - # + LA r4, FMPLL_SYNCR - AC_PREREQ(2.60) - AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla]) +You have to put a declaration of this function somewhere in a header file. -GCC Attributes --------------- +Script Example +^^^^^^^^^^^^^^ + + .. code-block:: shell + + ## + # + # @file + # + # @ingroup mpc55xx_config + # + # @brief Configure script of LibBSP for the MPC55xx evaluation boards. + # + + AC_PREREQ(2.60) + AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla]) -The Doxygen C/C++ parser cannot cope with the GCC attribute((something)) stuff. But you can discard such features with pre-defined preprocessor macros: +GCC Attributes +^^^^^^^^^^^^^^ - .. code-block:: - ENABLE_PREPROCESSING = YES - MACRO_EXPANSION = YES - EXPAND_ONLY_PREDEF = YES - PREDEFINED = __attribute__(x)= +The Doxygen C/C++ parser cannot cope with the GCC attribute((something)) +stuff. But you can discard such features with pre-defined preprocessor +macros: -History -------- + .. code-block:: shell -RTEMS is much older than ​`Doxygen `_ and the documentation in the .h and .inl files was obviously not written with ​`Doxygen markup `_. In 2007, `JoelSherrill `_ undertook to convert the documentation in the .h and .inl files in the RTEMS SuperCore? to Doxygen format. As a result of this effort, the Doxygen for the development version of the RTEMSSuperCore is now built automatically multiple times per day and made available on the RTEMS Website. In April 2008, `JoelSherrill `_ began to update the Classic API (e.g. cpukit/rtems) .h and .inl files to include `​Doxygen markup `_. + ENABLE_PREPROCESSING = YES + MACRO_EXPANSION = YES + EXPAND_ONLY_PREDEF = YES + PREDEFINED = __attribute__(x)= -- cgit v1.2.3 From 890276d8409dee8b3f08bc1481862395d8c12b6b Mon Sep 17 00:00:00 2001 From: Sal Date: Tue, 4 Dec 2018 13:29:43 -0600 Subject: eng/coding-file-hdr.rst: Fix file formatting (GCI 2018) --- eng/coding-file-hdr.rst | 48 +++++++++++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst index 1ff16b8..7104d06 100644 --- a/eng/coding-file-hdr.rst +++ b/eng/coding-file-hdr.rst @@ -3,41 +3,43 @@ .. COMMENT: COPYRIGHT (c) 2018. .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project - -.. COMMENT:TBD - Convert the following to Rest and insert into this file +.. COMMENT:TBD - Convert the following to Rest and insert into this file .. COMMENT:TBD - https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header Boilerplate File Header ======================= -Every file should include two comment header blocks, one for the Doxygen output and a copyright notice. This is a typical example: +Every file should include two comment header blocks, one for the Doxygen +output and a copyright notice. This is a typical example: - .. code-block:: c +.. code-block:: c - /** - * @file - * - * @ingroup TheGroupForThisFile - * - * @brief Short "Table of Contents" Description of File Contents - * - * A short description of the purpose of this file. - */ + /** + * @file + * + * @ingroup TheGroupForThisFile + * + * @brief Short "Table of Contents" Description of File Contents + * + * A short description of the purpose of this file. + */ - /* - * Copyright (c) 20XX Your Name Or Your Company. - * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * https://www.rtems.org/license/LICENSE. - */ + /* + * Copyright (c) 20XX Your Name Or Your Company. + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * https://www.rtems.org/license/LICENSE. + */ -* Use exactly one blank line between the Doxygen header and copyright notice. Leave the first line of the copyright notice blank. +* Use exactly one blank line between the Doxygen header and copyright notice. + Leave the first line of the copyright notice blank. -* Separate the Doxygen header and copyright notice so the copyright notice is not included in the Doxygen output. +* Separate the Doxygen header and copyright notice so the copyright notice is + not included in the Doxygen output. * The copyright owner and specific license terms may vary. -TBD Add link to license requirements section and show variant licenses. +.. COMMENT: TBD - TBD Add link to license requirements section and show variant licenses. -- cgit v1.2.3 From 63abc263dd5d73291caa9f665c2b9d7d0ec06d2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=A7al=20Comajoan=20Cara?= Date: Wed, 5 Dec 2018 15:43:00 +0100 Subject: eng/coding-doxygen: Fix errors This work was part of GCI 2018. --- eng/coding-doxygen.rst | 718 +++++++++++++++++++++++++------------------------ 1 file changed, 363 insertions(+), 355 deletions(-) diff --git a/eng/coding-doxygen.rst b/eng/coding-doxygen.rst index 49c53bb..9068074 100644 --- a/eng/coding-doxygen.rst +++ b/eng/coding-doxygen.rst @@ -4,10 +4,10 @@ .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project General Doxygen Recommentations -------------------------------- +=============================== -TBD - Convert the following to Rest and insert into this file -TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen +.. COMMENT: TBD - Convert the following to Rest and insert into this file +.. COMMENT: TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen .. sidebar:: *History* @@ -23,451 +23,459 @@ TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen diagrams. Doxygen Best Practices -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- -* Do not use @a. Instead use @param to document function parameters. -* Do not use @return. Instead use @retval to document return status codes. +* Do not use ``@a``. Instead use ``@param`` to document function parameters. +* Do not use ``@return``. Instead use ``@retval`` to document return status + codes. * Do not write documentation for trivial functions. -* Do not repeat documentation, use @see for example. -* Do not use @note. -* Use groups and arrange them in a hierarchy. Put every file into at least one group. +* Do not repeat documentation, use ``@see`` for example. +* Do not use ``@note``. +* Use groups and arrange them in a hierarchy. Put every file into at least + one group. * Use dot comments for state diagrams. * Use one whitespace character after an asterisk. -Special Notes for Google Code In Students -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Special Notes for Google Code-in Students +----------------------------------------- -* Follow the directions given by the `Google Code In -`_ task and this should take care -of itself if in doubt ask a mentor and/or tell a mentor the decision -you made. +Follow the directions given by the `Google Code-in +`_ task and this should take +care of itself if in doubt ask a mentor and/or tell a mentor the decision you +made. Header File Example -^^^^^^^^^^^^^^^^^^^ +------------------- -The files *thread.h* -(https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/thread.h) -and *threadimpl.h* -(https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/threadimpl.h) -should be a good example of how a header file should be written. The -following gives details in bits and pieces. +`thread.h +`_ and +`threadimpl.h +`_ +should be a good example of how a header file shouldbe written. The following +gives details in bits and pieces. Header blocks -^^^^^^^^^^^^^ - -Header files should contain the similar comment blocks as other source files, described at `Boilerplate File Header `_. - - .. code-block:: c - - /** - * @file - * - * @ingroup FlipFlop - * - * @brief Flip-Flop API - */ - - /* - * Copyright (c) YYYY Author. - * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.com/license/LICENSE. - */ - -Header Guard -^^^^^^^^^^^^ +------------- + +Header files should contain the similar comment blocks as other source files, +described at :ref:`coding-file-hdr`. + +.. code-block:: c + + /** + * @file + * + * @ingroup FlipFlop + * + * @brief Flip-Flop API + */ + + /* + * Copyright (c) YYYY Author. + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * http://www.rtems.com/license/LICENSE. + */ + +Header guard +------------ -After the comment blocks, use a header guard that assembles at -least the include path of the file. For example, if flipflop.h is in - then +After the comment blocks, use a header guard that assembles at least the +include path of the file. For example, if ``flipflop.h`` is in +```` then - .. code-block:: c +.. code-block:: c - #ifndef RTEMS_LIB_FLIP_FLOP_H - #define RTEMS_LIB_FLIP_FLOP_H + #ifndef RTEMS_LIB_FLIP_FLOP_H + #define RTEMS_LIB_FLIP_FLOP_H Includes -^^^^^^^^ +-------- Then add your include files before protecting C declarations from C++. +.. code-block:: c - .. code-block:: c - - #include + #include - #ifdef __cplusplus - extern "C" { - #endif /* __cplusplus */ + #ifdef __cplusplus + extern "C" { + #endif /* __cplusplus */ Using @defgroup for group definitions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Add any group definitions surrounding the function declarations -that belong in that group. Rarely, a header may define more than one -group. Here we use a dot diagram. - - - .. code-block:: c - - /** - * @defgroup FlipFlop Flip-Flop - * - * @brief Simple Flip-Flop state machine. - * - * @dot - * digraph { - * start [label="START"]; - * flip [label="FLIP"]; - * flop [label="FLOP"]; - * flip -> flop [label="flop()", URL="\ref flop"]; - * flop -> flip [label="flip()", URL="\ref flip"]; - * start -> flip - * [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"]; - * start -> flop - * [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"]; - * flip -> start - * [label="flip_flop_restart()", URL="\ref flip_flop_restart"]; - * } - * @enddot - * - * @{ - */ +------------------------------------- + +Add any group definitions surrounding the function declarations that belong +in that group. Rarely, a header may define more than one group. Here we use +a dot diagram. + +.. code-block:: c + + /** + * @defgroup FlipFlop Flip-Flop + * + * @brief Simple Flip-Flop state machine. + * + * @dot + * digraph { + * start [label="START"]; + * flip [label="FLIP"]; + * flop [label="FLOP"]; + * flip -> flop [label="flop()", URL="\ref flop"]; + * flop -> flip [label="flip()", URL="\ref flip"]; + * start -> flip + * [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"]; + * start -> flop + * [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"]; + * flip -> start + * [label="flip_flop_restart()", URL="\ref flip_flop_restart"]; + * } + * @enddot + * + * @{ + */ enum and struct -^^^^^^^^^^^^^^^ - -Provide documentation for declarations of enumerated types and -structs. Use typedefs for structs, and do not use _t as a typename suffix. - - - .. code-block:: c - - /** - * @brief The set of possible flip-flop states. - * - * Enumerated type to define the set of states for a flip-flop. - */ - typedef enum { - START = 0, - FLIP, - FLOP - } flip_flop_state; - - /** - * @brief Object containing multiple flip-flops. - * - * Encapsulates multiple flip-flops. - */ - typedef struct { - /** - * @brief Primary flip-flop. - */ - flip_flop_state primary; - /** - * @brief Secondary flip-flop. - */ - flip_flop_state secondary; - } flip_flop_multiple; - +--------------- + +Provide documentation for declarations of enumerated types and structs. +Use typedefs for structs, and do not use ``_t`` as a typename suffix. + +.. code-block:: c + + /** + * @brief The set of possible flip-flop states. + * + * Enumerated type to define the set of states for a flip-flop. + */ + typedef enum { + START = 0, + FLIP, + FLOP + } flip_flop_state; + + /** + * @brief Object containing multiple flip-flops. + * + * Encapsulates multiple flip-flops. + */ + typedef struct { + /** + * @brief Primary flip-flop. + */ + flip_flop_state primary; + /** + * @brief Secondary flip-flop. + */ + flip_flop_state secondary; + } flip_flop_multiple; Using @name for organization -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------- -Complicated groups can be given additional organization by using @name, -or by declaring additional groups within the hierarchy of the header -file's top-level group. +Complicated groups can be given additional organization by using ``@name``, or +by declaring additional groups within the hierarchy of the header file's +top-level group. - .. code-block:: c +.. code-block:: c - /** - * @name Flip-Flop Maintenance - * - * @{ - */ + /** + * @name Flip-Flop Maintenance + * + * @{ + */ Declaring functions -^^^^^^^^^^^^^^^^^^^ - -Function declarations should have an @brief that states what the function -does in a single topic sentence starting with a descriptive verb in the -present tense. - - - .. code-block:: c - - /** - * @brief Initializes the flip-flop state. - * - * @param[in] state The initial state to set the flip-flop. - * - * @retval RTEMS_SUCCESSFUL Successfully initialized. - * @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid. - */ - rtems_status_code flip_flop_initialize(flip_flop_state state); - - /** - * @brief Restarts the flip-flop. - * - * @retval RTEMS_SUCCESSFUL Successfully restarted. - * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state. - */ - rtems_status_code flip_flop_restart(void); +------------------- + +Function declarations should have an @brief that states what the function does +in a single topic sentence starting with a descriptive verb in the present +tense. + +.. code-block:: c + + /** + * @brief Initializes the flip-flop state. + * + * @param[in] state The initial state to set the flip-flop. + * + * @retval RTEMS_SUCCESSFUL Successfully initialized. + * @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid. + */ + rtems_status_code flip_flop_initialize(flip_flop_state state); + + /** + * @brief Restarts the flip-flop. + * + * @retval RTEMS_SUCCESSFUL Successfully restarted. + * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state. + */ + rtems_status_code flip_flop_restart(void); Do not document trivial functions, such as getter/setter methods. - .. code-block:: c +.. code-block:: c - flip_flop_state flip_flop_current_state(void); + flip_flop_state flip_flop_current_state(void); Close the documentation name definition and open a new name definition. - .. code-block:: c +.. code-block:: c - /** @} */ + /** @} */ - /** - * @name Flip-Flop Usage - * - * @{ - */ + /** + * @name Flip-Flop Usage + * + * @{ + */ - /** - * @brief Flip operation. - * - * @retval RTEMS_SUCCESSFUL Flipped successfully. - * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation. - */ - rtems_status_code flip( void ); + /** + * @brief Flip operation. + * + * @retval RTEMS_SUCCESSFUL Flipped successfully. + * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation. + */ + rtems_status_code flip( void ); - /** - * @brief Flop operation. - * - * @retval RTEMS_SUCCESSFUL Flopped successfully. - * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation. - */ - rtems_status_code flop( void ); + /** + * @brief Flop operation. + * + * @retval RTEMS_SUCCESSFUL Flopped successfully. + * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation. + */ + rtems_status_code flop( void ); - /** @} */ + /** @} */ Ending the file -^^^^^^^^^^^^^^^ +--------------- Close the documentation group definition, then the extern C declarations, then the header guard. - .. code-block:: c +.. code-block:: c - /** @} */ + /** @} */ - #ifdef __cplusplus - } - #endif /* __cplusplus */ + #ifdef __cplusplus + } + #endif /* __cplusplus */ - #endif /* RTEMS_LIB_FLIP_FLOP_H */ + #endif /* RTEMS_LIB_FLIP_FLOP_H */ -No newline at the end of the file. + No newline at the end of the file. Source File Example -^^^^^^^^^^^^^^^^^^^ - - .. code-block:: c - - /** - * @file - * - * @ingroup FlipFlop - * - * @brief Flip-Flop implementation. - */ - - /* - * Copyright (c) YYYY Author. - * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.com/license/LICENSE. - */ - - #include - - static flip_flop_state current_state; - - rtems_status_code flip_flop_initialize(flip_flop_state state) - { - if (current_state == START) { - current_state = state; - - return RTEMS_SUCCESSFUL; - } else { - return RTEMS_INCORRECT_STATE; - } - } - - rtems_status_code flip_flop_restart(void) - { - if (current_state == FLIP) { - current_state = START; - - return RTEMS_SUCCESSFUL; - } else { - return RTEMS_INCORRECT_STATE; - } - } - - flip_flop_state flip_flop_current_state(void) - { - return current_state; - } - - rtems_status_code flip(void) - { - if (current_state == FLOP) { - current_state = FLIP; - - return RTEMS_SUCCESSFUL; - } else { - return RTEMS_INCORRECT_STATE; - } - } - - rtems_status_code flop(void) - { - if (current_state == FLIP) { - current_state = FLOP; - - return RTEMS_SUCCESSFUL; - } else { - return RTEMS_INCORRECT_STATE; - } - } +------------------- + +.. code-block:: c + + /** + * @file + * + * @ingroup FlipFlop + * + * @brief Flip-Flop implementation. + */ + + /* + * Copyright (c) YYYY Author. + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * http://www.rtems.com/license/LICENSE. + */ + + #include + + static flip_flop_state current_state; + + rtems_status_code flip_flop_initialize(flip_flop_state state) + { + if (current_state == START) { + current_state = state; + + return RTEMS_SUCCESSFUL; + } else { + return RTEMS_INCORRECT_STATE; + } + } + + rtems_status_code flip_flop_restart(void) + { + if (current_state == FLIP) { + current_state = START; + + return RTEMS_SUCCESSFUL; + } else { + return RTEMS_INCORRECT_STATE; + } + } + + flip_flop_state flip_flop_current_state(void) + { + return current_state; + } + + rtems_status_code flip(void) + { + if (current_state == FLOP) { + current_state = FLIP; + + return RTEMS_SUCCESSFUL; + } else { + return RTEMS_INCORRECT_STATE; + } + } + + rtems_status_code flop(void) + { + if (current_state == FLIP) { + current_state = FLOP; + + return RTEMS_SUCCESSFUL; + } else { + return RTEMS_INCORRECT_STATE; + } + } Files -^^^^^ - -Document files with the @file directive omitting the optional filename argument. Doxygen will infer the filename from the actual name of the file. Within one Doxygen run all files are unique and specified by the current Doxyfile. We can define how the generated output of path and filenames looks like in the Doxyfile via the FULL_PATH_NAMES, STRIP_FROM_PATH and STRIP_FROM_INC_PATH options. +----- +Document files with the ``@file`` directive omitting the optional filename +argument. Doxygen will infer the filename from the actual name of the file. +Within one Doxygen run all files are unique and specified by the current +Doxyfile. We can define how the generated output of path and filenames looks +like in the Doxyfile via the ``FULL_PATH_NAMES``, ``STRIP_FROM_PATH`` and +``STRIP_FROM_INC_PATH`` options. Functions -^^^^^^^^^ +--------- -For documentation of function arguments there are basically to ways: The first one uses @param: +For documentation of function arguments there are basically to ways: - .. code-block:: +The first one uses ``@param``: - /** - * @brief Copies from a source to a destination memory area. - * - * The source and destination areas may not overlap. - * - * @param[out] dest The destination memory area to copy to. - * @param[in] src The source memory area to copy from. - * @param[in] n The number of bytes to copy. - */ - The second is to use @a param in descriptive text, for example: +.. code-block:: c - /** - * Copies @a n bytes from a source memory area @a src to a destination memory - * area @a dest, where both areas may not overlap. - */ + /** + * @brief Copies from a source to a destination memory area. + * + * The source and destination areas may not overlap. + * + * @param[out] dest The destination memory area to copy to. + * @param[in] src The source memory area to copy from. + * @param[in] n The number of bytes to copy. + */ -The @a indicates that the next word is a function argument and deserves some kind of highlighting. However, we feel that @a buries the usage of function arguments within description text. In RTEMS sources, we prefer to use @param instead of @a. +The second is to use ``@a`` param in descriptive text, for example: -Doxyfile Hints -^^^^^^^^^^^^^^ +.. code-block:: c -Header Files ------------- + /** + * Copies @a n bytes from a source memory area @a src to a destination memory + * area @a dest, where both areas may not overlap. + */ + +The ``@a`` indicates that the next word is a function argument and deserves +some kind of highlighting. However, we feel that ``@a`` buries the usage of +function arguments within description text. In RTEMS sources, we prefer to +use ``@param`` instead of ``@a``. -TBD - This is out of date since the include file reorganizaiton +Doxyfile Hints +-------------- -It is an RTEMS build feature that header files need to be installed -in order to be useful. One workaround to generate documentation which -allows automatic link generation is to use the installed header files as -documentation input. Assume that we have the RTEMS sources in the rtems -directory and the build of our BSP in build/powerpc-rtems5/mybsp relative -to a common top-level directory. Then you can configure Doxygen like: +Header Files +~~~~~~~~~~~ +It is an RTEMS build feature that header files need to be installed in order to +be useful. One workaround to generate documentation which allows automatic +link generation is to use the installed header files as documentation input. +Assume that we have the RTEMS sources in the rtems directory and the build of +our BSP in build/powerpc-rtems5/mybsp relative to a common top-level directory. +Then you can configure Doxygen like: - .. code-block:: +.. code-block:: - INPUT = rtems/bsps/powerpc/mybsp \ - rtems/c/src/lib/libcpu/powerpc/mycpu \ - rtems/make/custom/mybsp.cfg \ - build/powerpc-rtems5/mybsp/lib/include/myincludes + INPUT = rtems/bsps/powerpc/mybsp \ + rtems/c/src/lib/libcpu/powerpc/mycpu \ + rtems/make/custom/mybsp.cfg \ + build/powerpc-rtems5/mybsp/lib/include/myincludes - RECURSIVE = YES + RECURSIVE = YES - EXCLUDE = rtems/bsps/powerpc/mybsp/include \ - rtems/c/src/lib/libcpu/powerpc/mycpu/include + EXCLUDE = rtems/bsps/powerpc/mybsp/include \ + rtems/c/src/lib/libcpu/powerpc/mycpu/include - FULL_PATH_NAMES = YES + FULL_PATH_NAMES = YES - STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \ - rtems + STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \ + rtems Script and Assembly Files -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ Doxygen cannot cope with script (= files with #-like comments) or assembly -files. But you can add filter programs for them (TODO: Add source code -for filter programs somewhere): +files. But you can add filter programs for them + +.. COMMENT: TBD - Add source code for filter programs somewhere - .. code-block:: +.. code-block:: - FILTER_PATTERNS = *.S=c-comments-only \ - *.s=c-comments-only \ - *.cfg=script-comments-only \ - *.am=script-comments-only \ - *.ac=script-comments-only + FILTER_PATTERNS = *.S=c-comments-only \ + *.s=c-comments-only \ + *.cfg=script-comments-only \ + *.am=script-comments-only \ + *.ac=script-comments-only Assembly Example -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ - .. code-block:: +.. code-block:: c - /** - * @fn void mpc55xx_fmpll_reset_config() - * - * @brief Configure FMPLL after reset. - * - * Sets the system clock from 12 MHz in two steps up to 128 MHz. - */ - GLOBAL_FUNCTION mpc55xx_fmpll_reset_config - /* Save link register */ - mflr r3 + /** + * @fn void mpc55xx_fmpll_reset_config() + * + * @brief Configure FMPLL after reset. + * + * Sets the system clock from 12 MHz in two steps up to 128 MHz. + */ + GLOBAL_FUNCTION mpc55xx_fmpll_reset_config + /* Save link register */ + mflr r3 - LA r4, FMPLL_SYNCR + LA r4, FMPLL_SYNCR You have to put a declaration of this function somewhere in a header file. Script Example -^^^^^^^^^^^^^^ - - .. code-block:: shell - - ## - # - # @file - # - # @ingroup mpc55xx_config - # - # @brief Configure script of LibBSP for the MPC55xx evaluation boards. - # - - AC_PREREQ(2.60) - AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla]) +~~~~~~~~~~~~~~ + +.. code-block:: shell + + ## + # + # @file + # + # @ingroup mpc55xx_config + # + # @brief Configure script of LibBSP for the MPC55xx evaluation boards. + # + + AC_PREREQ([2.69]) + AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[https://devel.rtems.org/newticket]) + GCC Attributes -^^^^^^^^^^^^^^ +-------------- -The Doxygen C/C++ parser cannot cope with the GCC attribute((something)) -stuff. But you can discard such features with pre-defined preprocessor -macros: +The Doxygen C/C++ parser cannot cope with the GCC ``attribute((something))`` +stuff. But you can discard such features with pre-defined preprocessor macros - .. code-block:: shell +.. code-block:: shell - ENABLE_PREPROCESSING = YES - MACRO_EXPANSION = YES - EXPAND_ONLY_PREDEF = YES - PREDEFINED = __attribute__(x)= + ENABLE_PREPROCESSING = YES + MACRO_EXPANSION = YES + EXPAND_ONLY_PREDEF = YES + PREDEFINED = __attribute__(x)= -- cgit v1.2.3 From eac8ca8e3c77bb0a958429c94d97e2187e763184 Mon Sep 17 00:00:00 2001 From: Pritish Jain Date: Sun, 9 Dec 2018 21:20:04 +0530 Subject: eng/coding-conventions.rst: Convert TBD to Rest Format (GCI 2018) --- eng/coding-conventions.rst | 245 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 243 insertions(+), 2 deletions(-) diff --git a/eng/coding-conventions.rst b/eng/coding-conventions.rst index 654b5bb..b9ba7d2 100644 --- a/eng/coding-conventions.rst +++ b/eng/coding-conventions.rst @@ -3,9 +3,250 @@ .. COMMENT: COPYRIGHT (c) 2018. .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project +.. COMMENT:TBD - Convert the following to Rest and insert into this file +.. COMMENT:TBD - https://devel.rtems.org/wiki/Developer/Coding/Conventions + Coding Conventions ****************** -TBD - Convert the following to Rest and insert into this file -TBD - https://devel.rtems.org/wiki/Developer/Coding/Conventions +The style of RTEMS is generally consistent in the core areas. +This page attempts to capture generally accepted practices. +When in doubt, consult the code around you or look in cpukit/rtems. +See the sister page `Doxygen Recommendations `_. +for examples that illustrate style rules and Doxygen usage. + +Source Documentation +-------------------- + +* Use Doxygen according to our `Doxygen Recommendations `_.. +* Start each file with a brief description followed by a license. + See `Boilerplate File Header `_.. +* Use /* */ comments. +* Use comments wisely within function bodies, to explain + or draw attention without being verbose. +* Use English prose and strive for good grammar, + spelling, and punctuation. +* Use TODO: with a comment to indicate code that needs improvement. + Make it clear what there is to do. +* Use XXX or FIXME to indicate an error/bug/broken code. + +Licenses +-------- + +* The RTEMS `License `_. is the typical + and preferred license. + * 2- and 3-clause BSD, MIT, and other OSI-approved non-copyleft licenses + that permit statically linking with the code of different licenses + are acceptable. + * GPL licensed code is NOT acceptable, neither is LGPL. + See `this blog post explanation `_. + for more information. + * Advertising obligations are NOT acceptable, but restrictions are permissible. + +Language and Compiler +--------------------- + +* Use C99. +* Treat warnings as errors: eliminate them. +* Favor C, but when assembly language is required use inline + assembly if possible. +* Do not use compiler extensions. +* Use the RTEMS_macros defined in score/basedefs.h for abstracting + compiler-specific features. +* Use NULL for the null pointer, and prefer to use explicit + checks against NULL, e.g., + + .. code-block:: c + + if ( ptr != NULL ) + instead of + + .. code-block:: c + + if ( !ptr ) +* Use explicit checks for bits in variables. + * Example 1: Use + .. code-block:: c + + if ( XBITS == (var & XBITS) ) + to check for a set of defined bits. + * Example 2: Use + .. code-block:: c + + if ( (var & X_FLAGS) != 0) ) + instead of + .. code-block:: c + + if ( !!(var & X_FLAGS) ) + to check for at least 1 defined bit in a set. +* Use '(void) unused;' to mark unused parameters and set-but-unused + variables immediately after being set. +* Do not put function prototypes in C source files, any global functions + should have a prototype in a header file and any private function + should be declared static. +* Declare global variables in exactly one header file. + Define global variables in at most one source file. + Include the header file declaring the global variable as + the first include file if possible to make sure that the + compiler checks the declaration and definition and that + the header file is self-contained. +* Do not cast arguments to any printf() or printk() variant. + Use PRI constants for the types supported there. + Use for the other POSIX and RTEMS types that + have PRI constants defined there. This increases the portability + of the printf() format. +* Do not use the register keyword. It is deprecated since C++14. + +Formatting +----------- + +* Use spaces instead of tabs. +* Use two spaces for indentation, four spaces for + hanging indentation. +* Adhere to a limit of `80 characters per line `_.. +* Put function return types and names on one line if they fit. +* Put function calls on one line if they fit. +* No space between a function name or function-like macro and + the opening parens. +* Put braces on the same line as and one space after the + conditional expression ends. +* Put the opening brace of a function definition one line after + the closing parenthesis of its prototype. +* Put a single space inside and outside of each parenthesis + of a conditional expression. + * Exception: never put a space before a closing semi-colon. +* Put a single space before and after ternary operators. +* Put a single space before and after binary operators. +* Put no space between unary operators (e.g. *, &, !, ~, ++, --) + and their operands. +* No spaces around dereferencing operators (-> and .). +* Do not use more than one blank line in a row. +* Do not use trailing whitespace at the end of a line. + +Readability +------------ + +* Understand and follow the `naming rules `_.. +* Use typedef to remove 'struct', but do not use typedef + to hide pointers or arrays. + * Exception: typedef can be used to simplify function pointer types. + +* Do not mix variable declarations and code. +* Declare variables at the start of a block. +* Only use primitive initialization of variables at their declarations. + Avoid complex initializations or function calls in variable declarations. +* Do not put unrelated functions or data in a single file. +* Do not declare functions inside functions. +* Avoid deep nesting by using early exits e.g. return, break, continue. + * Parameter checking should be done first with early error returns. + * Avoid allocation and critical sections until error checking is done. + * For error checks that require locking, do the checks early after acquiring locks. + * Use of 'goto' requires good reason and justification. + +* Test and action should stay close together. +* Avoid complex logic in conditional and loop statements. +* Put conditional and loop statements on the line after the expression. +* Favor inline functions to hide + `compile-time feature-conditioned compilation `_.. +* Define non-inline functions in a .c source file. +* Declare all global (non-static) functions in a .h header file. +* Declare and define inline functions in one place. Usually, this + is a *impl.h header file. +* Declare and define static functions in one place. Usually, this is + toward the start of a .c file. Minimize forward declarations of + static functions. +* Function declarations should include variable names. +* Avoid excess parentheses. Learn the + `operator precedence `_. rules. +* Always use parentheses with sizeof. This is an exception to the rule + about excess parentheses. + +Robustness +----------- + +* Check all return statuses. +* Validate input parameters. +* Use debug assertions (assert). +* Use const when appropriate for read-only function parameters + and compile-time constant values. +* Do not hard code limits such as maximum instances into your code. +* Prefer to use sizeof(variable) instead of sizeof(type). +* Favor C automatic variables over global or static variables. +* Use global variables only when necessary and ensure + atomicity of operations. +* Do not shadow variables. +* Avoid declaring large buffers or structures on the stack. +* Avoid using zero (0) as a valid value. Memory often + defaults to being zero. +* Favor mutual exclusion primitives over disabling preemption. +* Avoid unnecessary dependencies, such as by not calling + ''printf()'' on error paths. +* Avoid inline functions and macros with complicated logic + and decision points. +* Prefer inline functions, enum, and const variables instead of CPP macros. +* CPP macros should use a leading underscore for parameter + names and `avoid macro pitfalls `_.. + +Portability +----------- + +* Think portable! RTEMS supports a lot of target hardware. +* For integer primitives, prefer to use precise-width integer + types from C99 stdint.h. +* Write code that is 16-bit, 32-bit, and 64-bit friendly. + +Maintainability +--------------- + +* Minimize modifications to `third-party code `_.. +* Keep it simple! Simple code is easier to debug and easier to read than clever code. +* Share code with other architectures, CPUs, and BSPs where possible. +* Do not duplicate standard OS or C Library routines. + +Performance +----------- + +* Prefer algorithms with the `lowest order of time and space `_. + for fast, deterministic execution times with small memory footprints. +* Understand the constraints of `real-time programming `_.. + Limit execution times in interrupt contexts and critical sections, + such as Interrupt and Timer Service Routines (TSRs). +* Functions used only through function pointers should be declared + 'static inline' (RTEMS_INLINE_ROUTINE) +* Prefer to ++preincrement instead of postincrement++. +* Avoid using floating point except where absolutely necessary. + +Miscellaneous +------------- + +* If you need to temporarily change the execution mode of a + task/thread, restore it. +* If adding code to ''cpukit'' be sure the filename is unique since + all files under that directory get merged into a single library. + +Layering +-------- + +* TBD: add something about the dependencies and header file layering. +* Understand the `RTEMS Software Architecture '_. + +Exceptions to the Rules +----------------------- + +* Minimize reformatting existing code in RTEMS unless the file undergoes + substantial non-style changes. +* `Third-party code `_. + should not be reformatted to fit RTEMS style. + Exception: unmaintained third-party code adopted and + maintained by RTEMS may be reformatted, subject to the + above rules. + +Tools +----- + +Some of the above can be assisted by tool support. Feel free to add +more tools, configurations, etc here. +* `Uncrustify `_. + Configuration for RTEMS: + `rtems.uncrustify `_. -- cgit v1.2.3