From 9d1c8e32d7c89d3b31fbc7f0854e2f79a13c5fe3 Mon Sep 17 00:00:00 2001 From: Fabien Chouteau Date: Thu, 30 Oct 2025 17:41:48 +0100 Subject: [PATCH 1/7] First version of the Railway Software Booklet --- .../chapters/annex.rst | 244 ++++ .../chapters/bibliography.rst | 8 + .../chapters/cenelec.rst | 455 ++++++ .../chapters/contribution.rst | 253 ++++ .../chapters/introduction.rst | 241 ++++ .../chapters/table4-1.csv | 40 + .../chapters/table4-10.csv | 27 + .../chapters/table4-11.csv | 13 + .../chapters/table4-12.csv | 11 + .../chapters/table4-13.csv | 11 + .../chapters/table4-14.csv | 16 + .../chapters/table4-15.csv | 7 + .../chapters/table4-16.csv | 27 + .../chapters/table4-17.csv | 10 + .../chapters/table4-18.csv | 11 + .../chapters/table4-19.csv | 8 + .../chapters/table4-2.csv | 49 + .../chapters/table4-20.csv | 14 + .../chapters/table4-3.csv | 21 + .../chapters/table4-4.csv | 5 + .../chapters/table4-5.csv | 6 + .../chapters/table4-6.csv | 10 + .../chapters/table4-7.csv | 10 + .../chapters/table4-8.csv | 6 + .../chapters/table4-9.csv | 16 + .../chapters/technology.rst | 1241 +++++++++++++++++ .../chapters/tools.rst | 1111 +++++++++++++++ .../conf.ini | 5 + .../images/fig-1.png | Bin 0 -> 41637 bytes .../images/fig-2.png | Bin 0 -> 24558 bytes .../images/fig-3.png | Bin 0 -> 23406 bytes .../index.rst | 152 ++ .../references.bib | 243 ++++ content/global.txt | 24 +- content/index.rst | 1 + 35 files changed, 4294 insertions(+), 2 deletions(-) create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/annex.rst create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/bibliography.rst create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/contribution.rst create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-1.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-10.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-11.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-12.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-13.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-14.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-15.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-16.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-17.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-18.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-19.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-2.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-20.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-3.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-4.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-5.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-6.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-7.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-8.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/table4-9.csv create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/technology.rst create mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/tools.rst create mode 100644 content/booklets/adacore-technologies-for-railway-software/conf.ini create mode 100644 content/booklets/adacore-technologies-for-railway-software/images/fig-1.png create mode 100644 content/booklets/adacore-technologies-for-railway-software/images/fig-2.png create mode 100644 content/booklets/adacore-technologies-for-railway-software/images/fig-3.png create mode 100644 content/booklets/adacore-technologies-for-railway-software/index.rst create mode 100644 content/booklets/adacore-technologies-for-railway-software/references.bib diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/annex.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/annex.rst new file mode 100644 index 000000000..8c7d2d0b3 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/annex.rst @@ -0,0 +1,244 @@ +.. include:: ../../../global.txt + +Technology Annex +================ + +This annex summarizes how AdaCore's tools and technologies support the various +techniques and measures defined in Annex\ |nbsp|\ D of |en-50128|. +The qualification status for tools, and certifiability for run-time libraries, +are also noted. + +.. index:: single: Ada language; Support for Annex D techniques (summary) + +Ada Programming Language +------------------------ + +See :ref:`Railway_SW_Ada`. + +Qualification +~~~~~~~~~~~~~ + +Although there is no qualification of a language *per se*, the Ada language +is standardized through an official process managed by an ISO committee, +IEC/ISO 8652. +AdaCore's Ada compilers and tools have reference and user documentation +that precisely describes the expected behavior, including the effects +of implementation-defined features. + +Annex D References +~~~~~~~~~~~~~~~~~~ + +* D.2 Analyzable Programs +* D.4 Boundary Value Analysis +* D.14 Defensive Programming +* D.18 Equivalence Classes and Input Partition Testing +* D.24 Failure Assertion Programming +* D.33 Information Hiding / Encapsulation +* D.34 Interface Testing +* D.35 Language Subset +* D.38 Modular Approach +* D.49 Strongly Typed Programming Languages +* D.53 Structured Programming +* D.54 Suitable Programming Languages +* D.57 Object Oriented Programming +* D.60 Procedural Programming + + +GNAT Pro Assurance Toolsuite +---------------------------- + +.. index:: single: GNAT Pro Assurance; Qualification +.. index:: single: Tool qualification; GNAT Pro Assurance + +Qualification +~~~~~~~~~~~~~ + +.. rubric:: GNAT Pro compiler family + +The GNAT Pro compilers for Ada and for C are qualified at class T3. +AdaCore can provide documentation attesting to various aspects such as +service history, development standard, and testing results. +This documentation has been submitted and accepted in past certification +activities. +T3 qualification material can also be developed for the GNAT Pro for C++ and +GNAT Pro for Rust compilers. + +Since compilers are large and complex pieces of software, bugs can be +detected (and subsequently corrected) after a particular version has been +chosen. Following the requirements stated in 6.7.4.11, however, a corrected +version of the compiler cannot be deployed without specific justification. +AdaCore offers a dedicated service |ndash| GNAT Pro Assurance |ndash| on a +specified version of the technology, which provides critical problem fixes +(or workaround suggestions) as well as detailed descriptions of the changes. +Using GNAT Pro Assurance, a customer can integrate a corrected version of +a specific compiler release into their development infrastructure +without the risk of regressions from unwanted updates. + +See :ref:`Railway_SW_GNAT_Pro_Assurance`. + +.. index:: single: GNATstack; Tool qualification +.. index:: single: Tool qualification; GNATstack + +.. rubric:: GNATstack + +GNATstack can be qualified as a class T2 tool. + +.. index:: single: Light Profile; Certification material +.. index:: single: Light-Tasking Profile; Certification material + +Run-Time Certification +~~~~~~~~~~~~~~~~~~~~~~ + +Certification material up to SIL 4 can be developed for the Light and +Light-Tasking run-time libraries. + +See :ref:`Railway_SW_Configurable_Run-Time_Libraries`. + +.. index:: single: GNAT Pro Assurance; Support for Annex D techniques (summary) + +Annex D References +~~~~~~~~~~~~~~~~~~ + +* D.10 Data Flow Analysis +* D.15 Coding Standards and Style Guide +* D.18 Equivalence Classes and Input Partition Testing +* D.35 Language Subset + + +SPARK Language and Toolsuite +---------------------------- + +See :ref:`Railway_SW_SPARK`. + +.. index:: single: SPARK Pro toolsuite; Qualification +.. index:: single: Tool qualification; SPARK Pro toolsuite + +Qualification +~~~~~~~~~~~~~ + +The SPARK Pro toolsuite can be qualified at class T2. + +.. index:: single: SPARK technology; Support for Annex D techniques (summary) + +Annex D References +~~~~~~~~~~~~~~~~~~ + +The SPARK language and toolset can contribute to the deployment or +implementation of the following techniques: + +* D.2 Analyzable Programs +* D.4 Boundary Value Analysis +* D.10 Data Flow Analysis +* D.14 Defensive Programming +* D.18 Equivalence Classes and Input Partition Testing +* D.24 Failure Assertion Programming +* D.28 Formal Methods +* D.29 Formal Proof +* D.34 Interface Testing +* D.35 Language Subset +* D.38 Modular Approach +* D.57 Object Oriented Programming + +GNAT Static Analysis Suite +-------------------------- + +**This section will be completed after review of the content for the +various GNAT SAS tools. CodePeer is no longer a branded tool, and +in any event there is an issue with its qualification status +since it is not sound.** + +See :ref:`Railway_SW_GNAT_Static_Analysis_Suite`. + +Defects and Vulnerability Analysis +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**This section will be deleted (and re-titled), or else adapted as needed** + +.. index:: single: Defects and Vulnerability Analysis; Qualification +.. index:: single: Tool qualification; Defects and Vulnerability Analysis + + +Qualification +^^^^^^^^^^^^^ + +GNAT SAS's defects and vulnerability analysis tool can be qualified at +class T2. +It has a long cross-industry track record and has been qualified under other +standards in the past, such as DO-178B/C as a verification tool/TQL5. + +.. index:: single: Defects and Vulnerability Analysis; Support for Annex D techniques (summary) + +Annex D References +^^^^^^^^^^^^^^^^^^ + +GNAT SAS's defects and vulnerability analysis tool can contribute to the +deployment or implementation of the following techniques: + +* D.2 Analyzable Programs +* D.4 Boundary Value Analysis +* D.8 Control Flow Analysis +* D.10 Data Flow Analysis +* D.14 Defensive Programming +* D.18 Equivalence Classes and Input Partition Testing +* D.24 Failure Assertion Programming +* D.32 Impact Analysis + +Basic Static Analysis tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The basic tools are GNATcheck and GNATmetric. + +.. index:: single: GNATcheck; Qualification +.. index:: single: Tool qualification; GNATcheck +.. index:: single: GNATmetric; Qualification +.. index:: single: Tool qualification; GNATmetric + +Qualification +^^^^^^^^^^^^^ + +These tools can be qualified at class T2. +GNATcheck has been qualified under other standards as well, +such as DO-178B/C as a verification tool/TQL5. + +.. index:: single: GNATcheck; Support for Annex D techniques (summary) +.. index:: single: GNATmetric; Support for Annex D techniques (summary) + +Annex D References +^^^^^^^^^^^^^^^^^^ + +* D.2 Analyzable Programs +* D.14 Defensive Programming +* D.15 Coding Standard and Style Guide +* D.35 Language Subset +* D.37 Metrics + + +GNAT Dynamic Analysis Suite +--------------------------- + +This suite comprises GNATtest, GNATemulator, GNATcoverage, GNATfuzz, and TGEN. + +See :ref:`Railway_SW_GNAT_Dynamic_Analysis_Suite`. + +.. index:: single: GNATtest; Qualification +.. index:: single: Tool qualification; GNATtest +.. index:: single: GNATemulator; Qualification +.. index:: single: Tool qualification; GNATemulator +.. index:: single: GNATcoverage; Qualification +.. index:: single: Tool qualification; GNATcoverage + +Qualification +~~~~~~~~~~~~~ + +GNATtest, GNATemulator and GNATcoverage can be qualified at class T2. +GNATcoverage has been qualified under other standards as well, +such as DO-178B/C as a verification tool/TQL5. + +.. index:: single: GNATtest; Support for Annex D techniques (summary) +.. index:: single: GNATemulator; Support for Annex D techniques (summary) +.. index:: single: GNATcoverage; Support for Annex D techniques (summary) + +Annex D References +~~~~~~~~~~~~~~~~~~ + +* D.50 Structure Based Testing diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/bibliography.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/bibliography.rst new file mode 100644 index 000000000..2c8bd2969 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/bibliography.rst @@ -0,0 +1,8 @@ +.. include:: ../../../global.txt + +.. only:: builder_html or builder_epub + + Bibliography + ============ + +.. bibliography:: diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst new file mode 100644 index 000000000..2c50417f8 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst @@ -0,0 +1,455 @@ +.. include:: ../../../global.txt + +CENELEC EN 50128 +================ + +Overview +-------- + +EN 50128 governs software used in railway control and protection applications, +i.e., systems that ensure the safe and efficient movement of trains. +Examples include: + +* *Automatic Train Protection (ATP)*, which ensure automatic braking to avoid + collisions or overspeed; + +* *Interlocking Systems*, which prevent conflicting train movements through + tracks, signals, and switches; + +* *Train Control Management Systems (TCMS)*, which coordinate control of + subsystems (doors, brakes, traction); + +* *Level Crossing Protection*, which manages gates and warnings at road-rail + intersections; and + +* *Centralized Traffic Control (CTC)*, which oversee train routing and + dispatch across large regions. + +The goal of the standard is to provide confidence that that the software +functions reliably and safely relative to its SIL. To this end it +specifies requirements in areas including the following: + +* Software development lifecycle processes; +* Verification and validation; +* Tools, techniques, and documentation; +* Risk mitigation measures; and +* Assessment of compliance with the standard. + +More specifically, |en-50128| identifies the procedures and prerequisites +(organization, independence and competencies management, quality management, +V&V team, etc.) applicable to the development of programmable electronic +systems used in railway control and protection applications. The standard +therefore may apply to some software applications in the rail sector but not +necessarily to all. + +|en-50128| is used in both safety-related and non-safety-related applications +and applies exclusively to software and its interaction with the whole system. +(In light of its role in the certification of non-safety-related software, +the standard introduces the Safety Integrity Level "Basic Integrity", which +pertains to software that is not safety related.) + +Although |en-50128| is targeted to the rail industry, it is not intrinsically +domain specific. The standard is basically a specification of sound +software engineering practices for long-lived large-scale high-assurance +systems in general and could in principle be applied in other domains. + +One of the distinctive points of |en-50128| is its requirement to justify the +implementation of the resources. For this reason, it is said to be a +"resources standard". + +.. index:: single: EN 50128; Structure of the standard + +Structure of the standard +------------------------- + +:numref:`Railway_SW_fig3` illustrates the structure of |en-50128| (note that chapters in +CENELEC standards are referred to as clauses, and individual sections and +sub-sections within a chapter are sub-clauses). + +.. _Railway_SW_fig3: +.. figure:: ../images/fig-3.png + :align: center + +Clauses 1, 2, and 3 |mdash| *Scope*, *Normative references*, and +*Terms, definitions and abbreviations*, respectively |mdash| +provide context and basic information. + +.. index:: single: EN 50128; Clause 4 (Objectives, conformance and software safety integrity levels) + +Clause 4, *Objectives, conformance and software safety integrity levels*, +identifies the five Safety Integrity Levels and states the criterion for +conformance to the standard: + + *To conform to this European standard it shall be shown that each of the + requirements has been satisfied to the software safety integrity + level defined and therefore the objective of the sub-clause in question + has been met.* + +This clause also specifies the role of normative Annex A in the selection of +techniques and measures for satisfying the requirements, +and the means for verifying compliance (inspection of the required documents, +augmented when appropriate by other evidence such as auditing and the +witnessing of tests). + +Clauses 5 through 9 form the core of the standard, with sub-clauses providing +the following content: + +* *Objective*: the purpose of meeting the requirements specified in the + sub-clause + +* *Input documents* (if applicable) + +* *Output documents* (if applicable) + +* *Requirements*: Details on what the software supplier needs to do or + provide. In some cases the requirements reference the tables in + Annex\ |nbsp|\ A for specific techniques or measures to be used. + +.. index:: single: EN 50128; Clause 5 (Software management and organization) + +Clause 5, *Software management and organization*, covers three topics: + +* Organization, roles and responsibilities (sub-clause 5.1); +* Personnel competence (sub-clause 5.2); and +* Lifecycle-related issues (sub-clause 5.3). + +The standard does not dictate a specific lifecycle, but it cites the "V" +approach as a recommendation, from the software specification to the overall +software testing and integration, and also imposes some requirements. +For example, the chosen lifecycle model needs to account for potential +iterations between phases, and detailed documentation in the Software +Quality Assurance Plan as specified in sub-clause 6.5 has to be supplied. + +.. index:: single: EN 50128; Clause 6 (Software assurance) + +Clause 6, *Software assurance*, has the goal of achieving a software package +with a minimum level of error and involves a variety of activities +and technologies: + +.. Kludges needed to stay within 80 character per line limit +.. in an indented construct: + +.. |sphinx-hack-verification| replace:: "confirmation, through the provision \ + of objective evidence, that specified requirements have been fulfilled" + +.. |sphinx-hack-validation| replace:: "confirmation, through the provision \ + of objective evidence, that the requirements for a specific intended use \ + or application have been fulfilled" + +* Software testing (sub-clause 6.1); +* Software verification (sub-clause 6.2) |mdash| defined in sub-clause 3.1.48 + as |sphinx-hack-verification|; +* Software validation (sub-clause 6.3) |mdash| defined in sub-clause 3.1.46 + as |sphinx-hack-validation|; +* Software assessment (sub-clause 6.4); +* Software quality assurance (sub-clause 6.5); +* Modification and change control (sub-clause 6.6); and +* Support tools and languages (sub-clause 6.7) |mdash| see + :ref:`Railway_SW_tool-qualification` below. + +As shown in :cite:`Boulanger_Schön_2007`, for software applications the +assessment process involves demonstrating that the software application +achieves its associated safety objectives. + +|en-50128| makes a clear separation between the application software, +referred to as the *generic software* (Clause 7), +and the data or algorithms that are used to configure the generic software +(Clause 8). + +.. index:: single: EN 50128; Clause 7 (Generic software development) + +Clause 7, *Generic software development*, has the following sub-clauses: + +* Lifecycle and documentation for generic software (sub-clause 7.1); +* Software requirements (sub-clause 7.2); +* Architecture and Design (sub-clause 7.3); +* Component design (sub-clause 7.4); +* Component implementation and testing (sub-clause 7.5); +* Integration (sub-clause 7.6); and +* Overall Software Testing / Final Validation (sub-class 7.7). + +.. index:: single: EN 50128; Clause 8 (Development of application data or algorithms) + +Clause 8, *Development of application data or algorithms: systems configured +by application data or algorithms*, ensures that the configuration parameters +are verified and validated with the same degree of assurance, based on the +relevant SIL, as is needed for the generic software that they configure. + +.. index:: single: EN 50128; Clause 9 (Software deployment and maintenance) + +An important part of the standard is Clause 9, *Software deployment and +maintenance*. +As stated in sub-clauses 9.1.1 and 9.2.1, the objectives of this clause +are, respectively: + + *To ensure that the software performs as required, preserving the + required software integrity level when it is deployed in the final + environment of the application.* + +and + + *To ensure that the software performs as required, preserving the + required software integrity level and dependability when making + corrections, enhancements or adaptations to the software itself.* + +.. index:: single: EN 50128; Annex A (Criteria for the Selection of Techniques and Measures) + +Annex A (normative), *Criteria for the Selection of Techniques and Measures*, +contains a set of tables that correlate the artifacts and practices +(documentation, techniques, and measures) specified elsewhere in the +standard, with an indication of whether, and how strongly, they are +recommended based on the software's SIL: + +* **M**: Mandatory. Must be used +* **HR**: Highly Recommended. If not used, need to explain rationale + for using alternative technique +* **R**: Recommended +* **--**: No recommendation either for or against usage +* **NR**: Not recommended. If used, need to explain rationale for decision + +Annex A consists of two sub-clauses: + +* *Clauses tables (A.1)*; the table headings identify the + sub-clause(s) containing the relevant requirements: + + - Table A.1 |ndash| Lifecycle Issues and Documentation (5.3) + - Table A.2 |ndash| Software Requirements Specification (7.2) + - Table A.3 |ndash| Software Architecture (7.3) + - Table A.4 |ndash| Software Design and Implementation (7.4) + - Table A.5 |ndash| Verification and Testing (6.2 and 7.3) + - Table A.6 |ndash| Integration (7.6) + - Table A.7 |ndash| Overall Software Testing (6.2 and 7.7) + - Table A.8 |ndash| Software Analysis Techniques (6.3) + - Table A.9 |ndash| Software Quality Assurance (6.5) + - Table A.10 |ndash| Software Maintenance (9.2) + - Table A.11 |ndash| Data Preparation Techniques (8.4) + +* *Detailed tables (A.2)*; these are lower-level tables + that expand on certain entries in the Clauses tables: + + - Table A.12 |ndash| Coding Standards + - Table A.13 |ndash| Dynamic Analysis and Testing + - Table A.14 |ndash| Functional/Black Box Test + - Table A.15 |ndash| Textual Programming Languages + - Table A.16 |ndash| Diagrammatic Languages for Application Algorithms + - Table A.17 |ndash| Modeling + - Table A.18 |ndash| Performance Testing + - Table A.19 |ndash| Static Analysis + - Table A.20 |ndash| Components + - Table A.21 |ndash| Test Coverage for Code + - Table A.22 |ndash| Object Oriented Software Architecture + - Table A.23 |ndash| Object Oriented Detailed Design + +As an example, Table A.4 contains a row for the programming language(s) +selection: + +.. csv-table:: + :widths: 30 15 15 10 10 10 10 + + **Technique/Measure**, **Ref**, **Basic Integrity**, **SIL 1**, **SIL 2**, **SIL 3**, **SIL 4** + "...", "...", "...", "...", "...", "...", "..." + "10 Programming Language", "Table A.15", "R", "HR", "HR","HR","HR" + "...", "...", "...", "...", "...", "...", "..." + +Table A.15 contains a row for Ada: + +.. csv-table:: + :widths: 30 15 15 10 10 10 10 + + **Technique/Measure**, **Ref**, **Basic Integrity**, **SIL 1**, **SIL 2**, **SIL 3**, **SIL 4** + "ADA", "D.54", "R", "HR", "HR","HR","HR" + "...", "...", "...", "...", "...", "...", "..." + + +Sub-clause D.54 (*Suitable Programming languages*) notes the features that a +suitable language should have (e.g., run-time array bound checking), and +features that it should encourage (e.g., definition of variable sub-ranges). +On the other side, D.54 also lists features that should be avoided because +they complicate verification (e.g., implicit variable initialization). + +The entries in Tables A.4 and A.15 show that Ada is a Highly Recommended +language at |sil1| through |sil4| and a Recommended language at the +Basic Integrity level. +Features that should be avoided can be detected and prevented by using +AdaCore's GNATcheck tool in the GNAT Static Analysis Suite; +see :ref:`Railway_SW_GNAT_Static_Analysis_Suite`. + +.. index:: single: EN 50128; Annex B (Key software roles and responsibilities) + +Annex B (normative), *Key software roles and responsibilities*, consists of +ten tables detailing the responsibilities and key competencies for the various +roles specified in the standard: Requirements Manager, Designer, Implementor, +Tester, Verifier, Integrator, Validator, Assessor, Project Manager, and +Configuration Manager. + +.. index:: single: EN 50128; Annex C (Documents Control Summary) + +Annex C (informative), *Documents Control Summary*, provides a table that +lists, for each project phase, its output documents and, for each +document, the responsible author and reviewer(s). The lifecycle phases +and their associated document count are: + +* *Planning:* 5 documents +* *Software requirements:* 3 documents +* *Architecture and design:* 6 documents +* *Component design:* 3 documents +* *Component implementation and testing:* 3 documents +* *Integration:* 3 documents +* *Overall software testing / Final validation:* 4 documents +* *Systems configured by application data/algorithms:* 8 documents +* *Software deployment:* 5 documents +* *Software maintenance:* 4 documents +* *Software assessment:* 2 documents + +.. index:: single: EN 50128; Annex D (Bibliography of techniques) + +Annex D (informative), *Bibliography of techniques*, details the aim and +description for seventy-one specific software engineering practices. +These are applicable at various lifecycle phases; for example: + +* Coding Standards and Style Guide (sub-clause D.15) and Language Subset + (sub-clause D.35) at the design and implementation phase, + +* Formal Methods and Formal Proof (sub-clauses D.28 and D.29) at the + implementation and verification phases, and + +* Equivalence Classes and Input Partition Testing (sub-clause D.18) at the + testing phase. + +.. index:: single: EN 50128; Annex ZZ + +Annex ZZ (Informative), *Relationship between this European standard and the +essential requirements of EU Directive 2016/797/EU [2016 OJ L138] aimed to +be covered* was introduced in |en-50128|/A1. It contains a table +showing the relationship noted in the Annex title. + +.. _Railway_SW_tool-qualification: + +.. index:: Tool qualification + +Tool qualification +------------------ + +An earlier edition of the standard, |en-50128|:2001, introduced a requirement +that the compilers employed for a project be purpose-certified, but did not +give a clear indication of what precisely was expected. +Clause 6.7 in the 2011 revision formalizes this concept, which will be +referred to here as "tool qualification", and provides details on what +needs to be performed and/or supplied. +(The standard does not use a specific term for this process, but the +"tool qualification" terminology from the airborne software standards +|do-178c| :cite:`RTCA_EUROCAE_2011a` and |do-330| :cite:`RTCA_EUROCAE_2011b` +is appropriate.) + +.. index:: Tool classes + +Tool classes +~~~~~~~~~~~~ + +Tool qualification is based on the recognition that different tools need +different levels of confidence in their reliability, based on how a +tool error affects the application software. This is formalized in the +concept of a "tool class". As stated in sub-clause 6.7.1: + + *The objective is to provide evidence that potential failures of tools + do not adversely affect the integrated toolset output in a safety related + manner that is undetected by technical and/or organisational measures + outside the tool. To this end, software tools are categorised into three + classes namely, T1, T2 & T3 respectively.* + +.. index:: T1 tool class + +* **T1** is reserved for tools that affect neither the verification of the + software nor the final executable file. + +.. index:: T2 tool class + +* **T2** applies to tools where a fault could lead to an error in the results + of the verification or validation. Examples include tools used for verifying + compliance with a coding standard, generating quantified metrics, performing + static analysis of the source code, managing and executing tests, etc. + +.. index:: T3 tool class + +* **T3** applies to tools where a fault could have an impact on (and, for + example, introduce errors into) the final executable software. + This class includes compilers, code generators, etc. + +Sub-clause 6.7 of |en-50128| defines a set of recommendations for each tool +class; these affect the content of the tool qualification report. +The standard identifies twelve requirements (numbered from 6.7.4.1 to +6.7.4.12) concerning tool qualification. +Requirement 6.7.4.12 is a mapping from each tool class to the applicable +sub-clauses in the standard. +It is shown here in the table below, which augments the version in the +standard by also specifying the lifecycle phase that is relevant for each +sub-clause. +The steps shown indicate the requirements to be met and reflect the additional +effort needed as the tool level increases; for further information, please see +:cite:`Boulanger_2015`, Chapter 9. + + +.. .. figure:: ../images/table1.png + + + ++----------------+-------------------------------------+------------------------------+ +| Tool class | Applicable sub-clause(s) | Lifecycle phase | ++================+=====================================+==============================+ +| T1 | 6.7.4.1 | Tool identification | ++----------------+-------------------------------------+------------------------------+ +| T2 | 6.7.4.1 | Tool identification | +| +-------------------------------------+------------------------------+ +| | 6.7.4.2 | Tool justification | +| +-------------------------------------+------------------------------+ +| | 6.7.4.3 | Tool specification/manual | +| +-------------------------------------+------------------------------+ +| | 6.7.4.10, 6.7.4.11 | Tool version management | ++----------------+-------------------------------------+------------------------------+ +| T3 | 6.7.4.1 | Tool identification | +| +-------------------------------------+------------------------------+ +| | 6.7.4.2 | Tool justification | +| +-------------------------------------+------------------------------+ +| | 6.7.4.3 | Tool specification/manual | +| +-------------------------------------+------------------------------+ +| | (6.7.4.4 and 6.7.4.5) or 6.7.4.6 | Tool conformity evidence | +| +-------------------------------------+------------------------------+ +| | (6.7.4.7 or 6.7.4.8) and 6.7.4.9 | Tool requirement fulfillment | +| +-------------------------------------+------------------------------+ +| | 6.7.4.10, 6.7.4.11 | Tool version management | ++----------------+-------------------------------------+------------------------------+ + +.. index:: single: Tool qualification; AdaCore support + +AdaCore tool qualification support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As will be explained below, AdaCore supports |en-50128| compliance through +tools qualified for several purposes: + +* Static and dynamic analysis; +* Code verification including formal proof; and +* Compilation with traceability and reproducibility guarantees. + +These capabilities reduce certification risk while improving code quality and +lifecycle confidence. + +AdaCore's qualification packages contain the information required by +|en-50128|, such as documentation, history, infrastructure, user references, +recommended usage, validation strategy, configuration management and change +tracking. + +Furthermore, tools can be provided through a subscription service +known as "sustained branches" (see :ref:`Railway_SW_Sustained_Branches`). +In this mode, a specific version of the tools can be put into special +maintenance, where AdaCore can investigate known problems +and provide repairs or work-arounds for potential issues on these branches +without unrelated updates that may risk regressions. + +AdaCore's decades-long experience in software certification for embedded and +safety-critical domains, including rail and avionics, ensures that customers +have access to: + +* Qualification material for |en-50128| and/or |do-330| tool assessment; +* A formally verifiable language (SPARK) for high-integrity use cases; and +* Lifecycle support aligned with the needs of long-term platform deployments diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/contribution.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/contribution.rst new file mode 100644 index 000000000..213ed2381 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/contribution.rst @@ -0,0 +1,253 @@ +.. include:: ../../../global.txt + +.. index:: Software Quality Assurance Plan + +AdaCore Contributions to the Software Quality Assurance Plan +============================================================ + +This chapter identifies AdaCore's tools and technologies that support the +techniques and measures defined in the |en-50128| Annex A tables +and that can be cited accordingly in the Software Quality Assurance Plan. +The information is presented in the form of annotations on the +relevant tables in Annex A. These annotations indicate whether a technique +or measure is covered by an AdaCore tool or technology and, if so, a +comment on how the tool or technology contributes is provided. + +Summary of abbreviations: + +* **M** |rt-arrow| Mandatory +* **HR** |rt-arrow| Highly Recommended +* **R** |rt-arrow| Recommended +* **---** |rt-arrow| Optional (neither Recommended nor Not Recommended) +* **NR** |rt-arrow| Not Recommended + +Table A.3 |ndash| Software Architecture (7.3) +--------------------------------------------- + +The Ada language and AdaCore technology do not provide support for software +architecture *per se*, but rather are more targeted towards software component +design. However, the presence of some capabilities at the lower level may +enable certain design decisions at a higher level. This table offers some +guidance on how that can be done. + +.. only:: latex + + .. raw:: latex + + \begin{landscape} + +.. csv-table:: + :file: table4-1.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.4 |ndash| Software Design and Implementation (7.4) +---------------------------------------------------------- + +.. csv-table:: + :file: table4-2.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.5 |ndash| Verification and Testing (6.2 and 7.3) +-------------------------------------------------------- + +.. csv-table:: + :file: table4-3.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.6 |ndash| Integration (7.6) +----------------------------------- + +.. csv-table:: + :file: table4-4.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.7 |ndash| Overall Software Testing (6.2 and 7.7) +-------------------------------------------------------- + +.. csv-table:: + :file: table4-5.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.8 |ndash| Software Analysis Techniques (6.3) +---------------------------------------------------- + +.. csv-table:: + :file: table4-6.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.9 |ndash| Software Quality Assurance (6.5) +-------------------------------------------------- + +Although AdaCore doesn't directly provide services for ISO 9001 +or configuration management, it follows standards to enable +tool qualification and/or certification. The following table +only lists items that can be useful to third parties. + +.. csv-table:: + :file: table4-7.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.10 |ndash| Software Maintenance (9.2) +--------------------------------------------- + +.. csv-table:: + :file: table4-8.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.11 |ndash| Data Preparation Techniques (8.4) +---------------------------------------------------- + +.. csv-table:: + :file: table4-9.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.12 |ndash| Coding Standards +----------------------------------- + +There are available references for coding standards. Their verification +can be automated through different ways: the GNAT compiler can define +base coding standard rules to be checked at compile time, and +GNATcheck implements a wider range of rules and is tailorable to support +project-specific coding standards. + +.. csv-table:: + :file: table4-10.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.13 |ndash| Dynamic Analysis and Testing +----------------------------------------------- + +.. csv-table:: + :file: table4-11.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.14 |ndash| Functional/Black Box Test +-------------------------------------------- + +GNATtest can generate and execute a testing framework, +with the actual tests being written by developers from requirements. + +.. csv-table:: + :file: table4-12.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.15 |ndash| Textual Programming Language +----------------------------------------------- + +.. csv-table:: + :file: table4-13.csv + :widths: 30 20 20 20 70 + :header-rows: 1 + :class: longtable + + +Table A.17 |ndash| Modeling +---------------------------- + +.. csv-table:: + :file: table4-14.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.18 |ndash| Performance Testing +-------------------------------------- + +.. csv-table:: + :file: table4-15.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.19 |ndash| Static Analysis +---------------------------------- + +.. csv-table:: + :file: table4-16.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.20 |ndash| Components +----------------------------- + +.. csv-table:: + :file: table4-17.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.21 |ndash| Test Coverage for Code +----------------------------------------- + +.. csv-table:: + :file: table4-18.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.22 |ndash| Object Oriented Software Architecture +-------------------------------------------------------- + +.. csv-table:: + :file: table4-19.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + + +Table A.23 |ndash| Object Oriented Detailed Design +-------------------------------------------------- + +.. csv-table:: + :file: table4-20.csv + :widths: 28 13 17 22 10 70 + :header-rows: 1 + :class: longtable + +.. only:: latex + + .. raw:: latex + + \end{landscape} diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst new file mode 100644 index 000000000..99bee30e1 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst @@ -0,0 +1,241 @@ +.. include:: ../../../global.txt + +Introduction +============ + +CENELEC safety-related railway standards +---------------------------------------- + +.. index:: CENELEC + +Railway projects are subject to a legal framework (laws, decrees, etc.) +and also a normative process based on certification standards. +In Europe, these standards are issued and maintained by CENELEC +(European Committee for Electrotechnical Standardization). +This document explains the usage of AdaCore's technologies in conjunction +with |en-50128|:2011 :cite:`CENELEC_2011` |mdash| +*Railway applications - Communication, signalling and processing systems +- Software for railway control and protection systems* |mdash| +as modified by amendments +|en-50128|/A1 :cite:`CENELEC_2020a` and |en-50128|/A2 :cite:`CENELEC_2020b`. +(For ease of exposition, the 2011 edition of the standard, as modified +by the A1 and A2 amendments, will simply be referred to as |en-50128|.) + +|EN-50128| is concerned with the safety-related aspects of a railway +system, down to the hardware and/or software elements used. +This document will cover where AdaCore's technologies fit best and how they +can best be applied to meet various requirements in this standard. + +|en-50128| is based on fundamentals described in other CENELEC railway +standards: + +.. index:: EN 50126 + +* |en-50126|-1 :cite:`CENELEC_2017b` |mdash| + *Railway applications - The specification and demonstration of reliability, + availability, maintainability and safety (RAMS) - Part 1: Generic RAMS + process* (subsequently modified by |en-50126|-1/A1 :cite:`CENELEC_2024`) + +* |en-50126|-2 :cite:`CENELEC_2017c` |mdash| + *Railway applications - The specification and demonstration of reliability, + availability, maintainability and safety (RAMS): Part 2: systems approach + to safety* + +.. index:: EN 50129 + +* |en-50129| :cite:`CENELEC_2018` |mdash| + *Railway applications - Communication, signalling and processing systems - + Safety related electronic systems for signalling* + +As noted in |en-50128|, page 7: + + *EN 50126-1 addresses system issues on the widest scale, while EN 50129 + addresses the approval process for individual systems which can exist + within the overall railway control and protection system. + ... [EN 50128] concentrates on the methods which need to be used + in order to provide software which meets the demands of safety integrity + which are placed upon it by these wider considerations.* + +In addition to EN 50126 and |en-50129|, several other CENELEC standards +relate to software's role in the safety of a railway system: + +.. index:: EN 50657 + +* |en-50657|:2017 :cite:`CENELEC_2017a` as modified by amendment + |en-50657|/A1 :cite:`CENELEC_2023a` |mdash| + *Railways applications - Rolling stock applications - Software on Board + Rolling Stock* + + This standard extends the principles of |en-50128| into the rolling stock + domain, focusing on onboard systems such as braking, door control, and + driver interfaces. + + It retains RAMS goals but tailors them for embedded systems in motion, + where environmental and operational variables are more dynamic. + +.. index:: EN 50716 + +* |en-50716|:2023 :cite:`CENELEC_2023b` |mdash| + *Railway Applications - Requirements for software development* + + This standard is a successor to |en-50128| and |en-50657|, + providing better alignment with |en-50126-1| and |en-50126-2|. + As of 2025 it is at the early adoption stage but is intended to + supersede both |en-50128| and |en-50657|. + +:numref:`Railway_SW_fig1` depicts the relationships among the various standards. + +.. _Railway_SW_fig1: +.. figure:: ../images/fig-1.png + :align: center + +.. index:: Safety Integrity Level (SIL) + +Safety Integrity Levels +----------------------- + +.. index:: Safety Integrity Level (SIL) + +A key concept in |en-50128| is the *Safety Integrity Level* +(SIL) of a software component, which reflects the risk of a hazard occurring +if the software fails. If there is no impact on safety, the level is referred +to as "Basic Integrity" (earlier known as |sil0|). +Otherwise the level has a value between 1 and 4, where 4 is the +most critical; i.e., with the highest risk of a hazard in case of software +failure. + +|en-50128| defines the techniques/measures that need to be used +at various software life cycle stages, based on the applicable SIL. + +AdaCore technologies for railway software +----------------------------------------- + +.. index:: V software life cycle + +AdaCore's technologies revolve around programming activities, as well as the +closely related design and verification activities. This is the bottom of the +"V" cycle as defined in |en-50128|, sub-clause 5.3, Figure 4 +(see :numref:`Railway_SW_fig2` below). +The company's tools exploit the features of the Ada language (highly +recommended by table A.15) and its formally verifiable SPARK subset. +In particular, the 2012 version of the Ada standard includes some significant +capabilities in terms of specification and verification. + +AdaCore's technologies bring two main benefits to the software life cycle +processes defined by the CENELEC railway standards. + +* *Expressing software interface specifications and software component + specifications directly in the source code.* + + Interfaces can be precisely expressed through standard syntax for features + such as strong typing, parameter constraints, and subprogram contracts. + These help to clarify interface documentation, to enforce program + constraints and invariants, and to provide an extensive foundation for + software component and integration verification. + +* *Reducing the verification costs.* + + Bringing additional specification at the language level allows verification + activities to run earlier in the software life cycle, during the software + component implementation itself. Tools provided by AdaCore support this + effort and are designed to be equally usable by both the development team + and the verification team. Allowing developers to use verification tools + greatly reduces the number of defects found at the verification stage and + thus reduces costs related to change requests identified in the ascending + stages of the cycle. + +AdaCore's technologies can be used at all Safety Integrity Levels, from +Basic Integrity to |sil4|. At lower levels, the full Ada language is suitable, +independent of platform. At higher levels, specific subsets will be needed, +for example the :index:`Ravenscar Profile` (:cite:`Burns_et_al_2004`, +:cite:`McCormick_Chapin_2015`) for concurrency support with analyzable +semantics and a reduced footprint, or the :index:`Light Profile` +:cite:`AdaCore_Web_UG_Cross` for a subset with no run-time library +requirements. At the highest level (|sil4|) the SPARK language +(:cite:`McCormick_Chapin_2015`, :cite:`AdaCore_Altran_2020`) and its +verification toolsuite enable mathematical proof of properties including +correct information flow, absence of run-time exceptions, and, for the most +critical code, correctness of the implementation against a formally +defined specification. + +The following technologies will be presented: + +.. index:: Ada language + +* *Ada*, a compilable programming language supporting imperative, + object-oriented, and functional programming styles and offering strong + specification and verification features. Unless otherwise indicated, + "Ada" denotes the 2012 version of the Ada language standard. + +.. index:: SPARK technology + +* *SPARK*, an Ada language subset and toolset supporting formal verification + of program properties such as Absence of Run-Time Errors + +.. index:: GNAT Pro Assurance + +* *GNAT Pro Assurance*, a specialized edition of AdaCore's GNAT Pro + language development environments that is oriented towards projects with + long maintenance cycles or certification requirements + +.. index:: GNAT Static Analysis Suite (GNAT SAS) +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); Defects and vulnerability analysis +.. index:: GNATmetric +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); GNATmetric +.. index:: GNATcheck +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); GNATcheck + +* The *GNAT Static Analysis Suite* ("GNAT SAS"), comprising several tools: + + - A "bug finder" engine that identifies potential defects and + vulnerabilities in Ada code + - GNATmetric |mdash| a metric computation tool + - GNATcheck |mdash| a coding standard checker + +.. index:: GNAT Dynamic Analysis Suite (GNAT DAS) +.. index:: GNATtest +.. index:: single: GNAT Dynamic Analysis Suite (GNAT DAS); GNATtest +.. index:: GNATcoverage +.. index:: single: GNAT Dynamic Analysis Suite (GNAT DAS); GNATemulator +.. index:: GNATemulator +.. index:: single: GNAT Dynamic Analysis Suite (GNAT DAS); GNATcoverage +.. index:: GNATfuzz +.. index:: single: GNAT Dynamic Analysis Suite (GNAT DAS); GNATfuzz +.. index:: TGen +.. index:: single: GNAT Dynamic Analysis Suite (GNAT DAS); TGen + +* The *GNAT Dynamic Analysis Suite* ("GNAT DAS"), comprising several tools: + + - GNATtest |mdash| a unit testing framework generator + - GNATemulator |mdash| a processor emulator + - GNATcoverage |mdash| a structural code coverage analyzer + - GNATfuzz |mdash| a fuzzing tool that helps uncover potential faults + - TGen |mdash| an experimental run-time library for automating test case + generation + +.. index:: GNAT Pro for Rust + +* *GNAT Pro for Rust*, a professionally supported complete development + environment for the Rust programming language + +.. index:: Integrated Development Environments (IDEs) +.. index:: GNAT Studio IDE +.. index:: single: Integrated Development Environments (IDEs); GNAT Studio +.. index:: VS Code support +.. index:: single: Integrated Development Environments (IDEs); VS Code support +.. index:: GNATbench IDE +.. index:: Eclipse IDE +.. index:: single: Integrated Development Environments (IDEs); GNATbench +.. index:: GNATdashboard IDE +.. index:: single: Integrated Development Environments (IDEs); GNATdashboard + +* Several *Integrated Development Environments* (IDEs): + + - GNAT Studio |mdash| a robust, flexible, and extensible IDE + - VS Code support |mdash| extensions for Ada and SPARK + - GNATbench |mdash| an Ada-knowlegeable Eclipse plug-in + - GNATdashboard |mdash| a metric integration and management platform + +.. _Railway_SW_fig2: +.. figure:: ../images/fig-2.png + :align: center diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-1.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-1.csv new file mode 100644 index 000000000..f291e7f16 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-1.csv @@ -0,0 +1,40 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Defensive Programming,D.14,HR,HR,Yes,"Defensive programming is more a \ +component or a programming activity than an architecture activity per se, \ +but as it is recorded in this table, it's worth mentioning that the Ada \ +language provides several features addressing various objectives of \ +defensive programming techniques (e.g., exception handling). In addition, \ +the GNAT Static Analysis Suite and SPARK tools help identify pieces of code \ +that should be protected by defensive code." + Fault Detection & Diagnosis,D.26,R,R,No, + Error Correcting Codes,D.19,|mdash|,|mdash|,No, + Error Detecting Codes,D.19,R,HR,No, + Failure Assertion Programming,D.24,R,HR,Yes,"The Ada language allows formalizing \ +assertions and contracts in various places in the code." + Safety Bag Techniques,D.47,R,R,No, + Diverse Programming,D.16,R,HR,Yes,"Using Ada along with another language \ +and a different code generation technology can be used to contribute to the \ +diverse programming argument." + Recovery Block,D.44,R,R,No, + Backward Recovery,D.5,NR,NR,No, + Forward Recovery,D.30,NR,NR,No, + Retry Fault Recovery Mechanisms,D.46,R,R,No, + Memorising Executed Cases,D.36,R,HR,No, + Artificial Intelligence – Fault Correction,D.1,NR,NR,No, + Dynamic Reconfiguration of software,D.17,NR,NR,No, + Software Error Effect Analysis,D.25,R,HR,No, + Graceful Degradation,D.31,R,HR,No, + Information Hiding / Encapsulation,D.33,HR,HR,Yes,"The Ada language \ +provides the necessary features to separate the interface of a module \ +from its implementation and enforce this separation." + Fully Defined Interface,D.38,HR,M,Yes,"The Ada language provides the \ +necessary features to separate the interface of a module from its \ +implementation and enforce this separation." + Formal Methods,D.28,R,HR,Yes,"SPARK can be used to formally define \ +architectural properties, such as data flow, directly in the code and \ +provides the means to verify them." + Modeling,Table A.17,R,HR,Yes,"Ada and SPARK allow defining certain \ +modeling properties in the code and provide means to verify them." + Structured Methodology,D.52,HR,HR,Yes,"Structured Methodology designs \ +can be implemented with Ada." + Modeling supported by computer aided design and specification tools,Table A.17,R,HR,No, diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-10.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-10.csv new file mode 100644 index 000000000..57ffea354 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-10.csv @@ -0,0 +1,27 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Coding Standard,D.15,HR,M,Yes,"GNATcheck allows implementing and verifying \ +a coding standard." + Coding Style Guide,D.15,HR,HR,Yes,"GNATcheck allows implementing and verifying \ +a coding style guide." + No Dynamic Objects,D.15,R,HR,Yes,"GNATcheck can forbid the use of dynamic \ +objects." + No Dynamic Variables,D.15,R,HR,Yes,"GNATcheck can forbid the use of dynamic \ +variables." + Limited Use of Pointers,D.15,R,R,Yes,"GNATcheck can forbid the use of \ +pointers or force justification of their usage." + Limited Use of Recursion,D.15,R,HR,Yes,"GNATcheck can forbid the use of \ +recursion or force justification of their usage." + No Unconditional Jumps,D.15,HR,HR,Yes,"GNATcheck can forbid the use of \ +unconditional jumps." + "Limited size and complexity of Functions, Subroutines and \ +Methods",D.38,HR,HR,Yes,"GNATmetric can compute complexity measures, and \ +GNATcheck can report excessive complexity." + "Entry/Exit Point strategy for Functions, Subroutines and \ +Methods",D.38,HR,HR,Yes,"GNATcheck can verify rules related to exit points." + Limited number of subroutine parameters,D.38,R,R,Yes,"GNATcheck can limit \ +the number of parameters for subroutines and report when that number is \ +exceeded." + Limited use of Global Variables,D.38,HR,M,Yes,"GNATcheck can flag global \ +variable usage and enforce their justification. SPARK forbids function \ +side effects and enforces documentation and verification of uses of global \ +variables. GNAT Studio allows analyzing usage of global variables." diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-11.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-11.csv new file mode 100644 index 000000000..8a7b027a3 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-11.csv @@ -0,0 +1,13 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Test Case Execution from Boundary Value Analysis,D.4,HR,HR,Yes,"GNATtest can \ +generate and execute a testing framework for tests written by \ +developers from requirements." + Test Case Execution from Error Guessing,D.20,R,HR,Yes,"GNAT fuzz can automate \ +the generation of large numbers of test cases at a high frequency." + Test Case Execution from Error Seeding,D.21,R,HR,No, + Performance Modeling,D.39,R,HR,No, + Equivalence Classes and Input Partition Testing,D.18,R,HR,Yes,"Ada and SPARK \ +provide specific features for partitioning function input and verifying that \ +this partitioning is well formed (i.e., no overlap and no gaps)." + Structure-Base Testing,D.50,R,HR,Yes,See Table A.21 + \ No newline at end of file diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-12.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-12.csv new file mode 100644 index 000000000..a9ff46323 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-12.csv @@ -0,0 +1,11 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Test Case Execution from Cause Consequence Diagrams,D6,|mdash|,R,No, + Prototyping/ Animation,D.43,|mdash|,R,No, + Boundary Value Analysis,D.4,R,HR,Yes,"GNATtest can be used to implement \ +tests coming from boundary value analysis." + Equivalence Classes and Input Partitioning Testing,D.18,R,HR,Yes,"Ada and \ +SPARK provide specific features for partitioning function input and \ +verifying that this partitioning is well formed (i.e., no overlap and \ +no gaps)." + Process Simulation,D.42 R,R,No, + \ No newline at end of file diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-13.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-13.csv new file mode 100644 index 000000000..1168a8c22 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-13.csv @@ -0,0 +1,11 @@ +Technique/Measure,SIL 2,SIL 3/4,Covered,Comment +Ada,HR,HR,Yes,GNAT Pro tools support all versions of the Ada language. +MODULA-2,HR,HR,No, +PASCAL,HR,HR,No, +C or C++,R,R,Yes,GNAT Pro for C and GNAT Pro for C++ support these languages +PL/M,R,NR,No, +BASIC,NR,NR,No, +Assembler,R,R,No, +C#,R,R,No, +Java,R,R,No, +Statement List,R,R,No, diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-14.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-14.csv new file mode 100644 index 000000000..9c51cc934 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-14.csv @@ -0,0 +1,16 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Data Modeling,D.65,R,HR,Yes,"Ada allows modeling data constraints, \ +in the form of type predicates." + Data Flow Diagram,D.11,R,HR,Yes,"SPARK allows defining data flow \ +dependencies at subprogram specification." + Control Flow Diagram,D.66,R,HR,No, + Finite State Machine or State Transition Programs,D.27,HR,HR,No, + Time Petri Nets,D.55,R,HR,No, + Decision/Truth Tables,D.13,R,HR,No, + Formal Methods,D.28,R,HR,Yes,"SPARK allows defining formal \ +properties on the code that can be verified by the SPARK toolset." + Performance Modeling,D.39,R,HR,No, + Prototyping/Animation,D.43,R,R,No, + Structure Diagrams,D.51,R,HR,No, + Sequence Diagrams,D.67,R,HR,No, + \ No newline at end of file diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-15.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-15.csv new file mode 100644 index 000000000..d6c0901bf --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-15.csv @@ -0,0 +1,7 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Avalanche/Stress Testing,D.3,R,HR,No,"Ada allows modeling data constraints, \ +in the form of type predicates." + Response Timing and Memory Constraints,D.45,HR,HR,Yes,"GNATstack can \ +statically analyze stack usage." + Performance Requirements,D.40,HR,HR,No, + \ No newline at end of file diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-16.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-16.csv new file mode 100644 index 000000000..247135c4e --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-16.csv @@ -0,0 +1,27 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Boundary Value Analysis,D.4,R,HR,Yes,"GNAT SAS can compute boundary values \ +for variables and parameters from the source code. GNAT SAS and SPARK can \ +verify various properties by analyzing potential values and boundary values \ +of variables. This includes detecting errors such as dereferencing a pointer \ +that could be null, generating a value outside the bounds of an Ada type or \ +subtype, violating a memory safety constraint (`buffer overrun`), \ +generating a numeric overflow or wraparound, and dividing by zero. \ +GNAT SAS and SPARK also help to confirm expected boundary values of \ +variables and parameters coming from the design." + Checklists,D.7,R,R,No, + Control Flow Analysis,D.8,HR,HR,Yes,"GNAT SAS and SPARK can detect \ +suspicious and potentially incorrect control flows, such as unreachable \ +code, redundant conditionals, loops that either run forever or fail to \ +terminate normally, and subprograms that never return. GNATstack can analyze \ +control flow and compute the maximum amount of stack memory for each task. \ +More generally, GNAT Studio provides visualization for call graphs and \ +call trees." + Data Flow Analysis,D.10,HR,HR,Yes,"GNAT SAS and SPARK can detect suspicious \ +and potentially incorrect data flow, such as variables being read before \ +they are written (uninitialized variables), and values that are written to \ +variables without being read (redundant assignments)." + Error Guessing,D.20,R,R,Yes,"Although realized through dynamic rather than \ +static analysis, GNAT fuzz can automatically generate test cases to \ +support Error Guessing." + Walkthroughs/Design Reviews,D.56,HR,HR,Yes, "GNAT Studio can display \ +and navigate the code, supporting walkthrough activities." diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-17.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-17.csv new file mode 100644 index 000000000..572e07cea --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-17.csv @@ -0,0 +1,10 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Information Hiding,D.33,|mdash|,|mdash|,Yes,"See Information Encapsulation below." + Information Encapsulation,D.33,HR,HR,Yes,"Ada provides the necessary features \ +to separate the interface of a module from its implementation, and enforce \ +this separation." + Parameter Number Limit,D.38,R,R,Yes,"GNATcheck can limit the number of \ +parameters for subroutines, and report violations." + Fully Defined Interface,D.38,HR,M,Yes,"Ada offers many features to support \ +interface definition, including behavior specification through pre- and \ +post-conditions." diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-18.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-18.csv new file mode 100644 index 000000000..fbc46e4fc --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-18.csv @@ -0,0 +1,11 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Statement,D.50,HR,HR,Yes,"GNATcoverage provides statement-level \ +coverage capabilities." + Branch,D.50,R,HR,Yes,"GNATcoverage provides branch-level \ +coverage capabilities." +Compound Condition,D.50,R,HR,Yes,"GNATcoverage provides MC/DC \ +(Modified Condition/Decision Coverage) capabilities, which can be \ +used as an efficient alternative to Compound Condition coverage." + Data Flow,D.50,R,HR,No, + Path,D.50,R,NR,No, + \ No newline at end of file diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-19.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-19.csv new file mode 100644 index 000000000..45afe2bad --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-19.csv @@ -0,0 +1,8 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + "Traceability of the concept of the application domain to the classes \ +of the architecture",|mdash|,R,HR,No, + "Use of suitable frames, commonly used combinations of classes and \ +design patterns",|mdash|,R,HR,Yes,"The conventional OO design patterns can be \ +implemented in Ada." + Object Oriented Detailed Design,Table A.23,R,HR,Yes,See Table A.23 + \ No newline at end of file diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-2.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-2.csv new file mode 100644 index 000000000..c1b247108 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-2.csv @@ -0,0 +1,49 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Formal Methods,D.28,R,HR,Yes,"Component requirements and interfaces \ +can be written in the form of formal boolean properties, using the \ +Ada or SPARK languages. These properties are verifiable." + Modeling,Table A.17,HR,HR,Yes,"Ada and SPARK allow defining certain \ +modeling properties in the code and provide means to verify them." + Structured methodology,D.52,HR,HR,Yes,"Structured Methodology designs \ +can be implemented with Ada." + Modular Approach,D.38,M,M,Yes,"A module can be represented as an Ada \ +package, with a cohesive and well-defined functionality, a clear \ +external interface in the visible part of the package spec, a private \ +part whose visibility is limited to to its child units, and a body \ +containing the implementation (which is only visible to its subunits)." + Components,Table A.20,HR,HR,Yes,"A component can be defined as a set \ +of Ada packages, which can clearly define the interface to access the \ +internal data, and the interfaces can be fully and unambiguously defined. \ +This set of packages is typically identified within a project file \ +(GPR file) and can be put into a version control system." + Design and Coding Standards,Table A.12,HR,M,Yes,"There are available \ +references for the coding standard. Verification can be automated in \ +different ways: the GNAT compiler can define base coding standard rules \ +to be checked at compile-time, with GNATcheck implementing a wider range of \ +rules." + Analyzable Programs,D.2,HR,HR,Yes,"The Ada language provide native \ +features to improve program analysis, such as type ranges, parameter modes, \ +and encapsulation. Tools such as GNATmetric and GNATcheck can help monitor \ +the complexity of the code and prevent the use of overly complex code. \ +GNAT SAS allows making an assessment of program analyzability during its \ +development. For higher SILs, the use of SPARK ensures that the subset \ +of the language used is suitable for most the rigorous analysis." + Strongly Typed Programming Language,D.49,HR,HR,Yes,"Ada is a strongly typed \ +language." + Structured Programming,D.53,HR,HR,Yes,"Ada supports all the usual paradigms \ +of structured programming. In addition, GNATcheck can control additional \ +design properties, such as explicit control flows, where subprograms have \ +single entry and single exit points, and structural complexity is reduced." + Programming Language,Table A.15,HR,HR,Yes,"Ada can be used for most of the \ +development, while facilitating interfacing to other languages such as \ +C or assembly." + Language Subset,D.35,|mdash|,HR,Yes,"Ada is designed to support \ +subsetting, possibly under the control of specific runtimes, GNATcheck, or \ +with SPARK. Another possibility is to follow the recommendations in \ +:cite:`ISO_IEC_1998`." + Object-Oriented Programming,"Table A.22, D.57",R,R,Yes,"If needed, Ada \ +supports all the usual paradigms of object-oriented programming, in addition \ +to safety-related features such as the :index:`Liskov Substitution Principle`." + Procedural Programming,D.60,HR,HR,Yes,"Ada supports all the usual paradigms \ +of procedural programming." +Metaprogramming,D.59,R,R,No, diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-20.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-20.csv new file mode 100644 index 000000000..8d8d7247e --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-20.csv @@ -0,0 +1,14 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + "Class should have only one objective",|mdash|,R,HR,Yes,"It's possible in \ +Ada to write classes with a unique objective." + "Inheritance used only if the derived class is a refinement of its basic \ +class",|mdash|,HR,HR,Yes,"Ada and SPARK can enforce respecting the \ +:index:`Liskov Substitution Principle`, ensuring inheritance consistency." + "Depth of inheritance limited by coding standards",|mdash|,R,HR,Yes,"GNATcheck \ +can limit inheritance depth." + "Overriding of operations (methods) under strict control",|mdash|,R,HR,Yes,"Ada \ +can enforce explicit syntax for overriding methods." + "Multiple inheritance used only for interface classes",|mdash|,HR,HR,Yes,"Ada \ +only allows multiple inheritance from interfaces." + "Inheritance from unknown classes",|mdash|,|mdash|,NR,Yes,"Ada only allows \ +inheritance from known classes." diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-3.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-3.csv new file mode 100644 index 000000000..dfcb202b0 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-3.csv @@ -0,0 +1,21 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Formal Proof,D.29,R,HR,Yes,"When Ada pre- and post-conditions are used, \ +together with the SPARK subset of the language, formal methods can formally \ +verify compliance of the implementation with these contracts." + Static Analysis,Table A.19,HR,HR,Yes,See Table A.19 + Dynamic Analysis and Testing,Table A.13,HR,HR,Yes,See Table A.13 + Metrics,D.37,R,R,Yes,"GNATmetric can compute and report metrics, such as \ +code size, comment percentage, cyclomatic complexity, unit nesting, and \ +loop nesting. These can then be compared with standards." + Traceability,D.58,HR,M,No, + Software Error Effect Analysis,D.25,R,HR,Yes,"GNAT Studio supports code \ +display and navigation. GNAT SAS can identify likely error locations in the \ +code. This supports potential software error detection and analysis \ +throughout the code." + Test Coverage for code,Table A.21,HR,HR,Yes,See Table A.21 + Functional / Black-Box Testing,Table A.14,HR,HR,Yes,See Table A.14 + Performance Testing,Table A.18,HR,HR,No, + Interface Testing,D.34,HR,HR,Yes,"Ada's strong typing, together with \ +its contract-based programming support, provides increased assurance to \ +demonstrate that the software interfaces are correct. This can help \ +improve software-to-software integration testing." diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-4.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-4.csv new file mode 100644 index 000000000..803cdae42 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-4.csv @@ -0,0 +1,5 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Functional and Black-box testing,Table A.14,HR,HR,Yes,"GNATtest can generate \ +a framework for testing." + Performance Testing,Table A.18,R,HR,Yes,"Stack consumption can be statically \ +computed using the GNATstack tool." diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-5.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-5.csv new file mode 100644 index 000000000..0ca119361 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-5.csv @@ -0,0 +1,6 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Performance Testing,Table A.18,HR,M,Yes,"Stack consumption can be statically \ +computed using the GNATstack tool." + Functional and Black-box Testing,Table A.14,HR,M,Yes,"GNATtest can generate a \ +testing framework for testing." +Modeling,Table A.17,R,R,No, diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-6.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-6.csv new file mode 100644 index 000000000..f86092f5a --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-6.csv @@ -0,0 +1,10 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Static Software Analysis,"D.13, D.37, Table A.19",HR,HR,Yes,"See Table A.19." + Dynamic Software Analysis,"Tables A.13, A.14",R,HR,Yes,"See Tables A.13 and \ +A.14." + Cause Consequence Diagrams,D.6,R,R,No, + Event Tree Analysis,D.22,R,R,No, + Software Error Effect Analysis,D.25,R,HR,Yes,"GNAT Studio supports code \ +display and navigation. GNAT SAS can identify likely error locations in the \ +code. These tools support both detection of potential software errors and \ +analysis throughout the code." \ No newline at end of file diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-7.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-7.csv new file mode 100644 index 000000000..a7f5bc93f --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-7.csv @@ -0,0 +1,10 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Accredited to EN ISO 9001,7.1,HR,HR,No, + Compliant with EN ISO 9001,7.1,M,M,No, + Compliant with ISO/IEC 90003,7.1,R,R,No, + Company Quality System,7.1,M,M,No, + Software Configuration Management,D.48,M,M,No, + Checklists,D.7,HR,M,No, + Traceability,D.58,HR,M,No, + Data Recording and Analysis,D.12,HR,M,Yes,"The data produced by tools \ +can be written to files and placed under configuration management." diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-8.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-8.csv new file mode 100644 index 000000000..db53f173a --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-8.csv @@ -0,0 +1,6 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Impact Analysis,D.32,HR,M,Yes,"GNAT SAS contributes to identifying the \ +impact of a code change between two baselines." + Data Recording and Analysis,D.12,HR,M,Yes,"AdaCore tools can be invoked \ +from the command line. They produce result files including the date and \ +version of the tool used." diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-9.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-9.csv new file mode 100644 index 000000000..95f99cbc6 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-9.csv @@ -0,0 +1,16 @@ + Technique/Measure,Ref,SIL 2,SIL 3/4,Covered,Comment + Tabular Specification Methods,D.68,R,R,Yes,"Tables of data \ +can be expressed using the Ada language, together with type-wide \ +contracts (predicates or invariants)." + Application specific language,D.69,R,R,No, + Simulation,D.42,HR,HR,No, + Functional testing,D.42,M,M,No, + Checklists,D.7,HR,M,No, + Fagan inspection,D.23,HR,HR,No, + Formal design reviews,D.56,HR,HR,Yes,"GNAT Studio can display code and \ +navigate through the code as a support for walkthrough activities." + Formal proof of correctness,D.29,|mdash|,HR,Yes,"When contracts are \ +expressed within the SPARK subset, their correctness can \ +be formally verified." + Walkthrough,D.56,R,HR,Yes,"GNAT Studio can display code and navigate through \ +the code as a support for walkthrough activities." diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/technology.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/technology.rst new file mode 100644 index 000000000..66b02d6ca --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/technology.rst @@ -0,0 +1,1241 @@ +.. include:: ../../../global.txt + +Technology Usage Guide +====================== + +This chapter explains how AdaCore's tools and technologies support a variety +of techniques from Annex D. + +.. _Railway_SW_Analyzable_Programs: + +.. index:: single: Annex D; Analyzable Programs (D.2) +.. index:: single: Ada language; Support for Analyzable Programs (D.2) + +Analyzable Programs (D.2) +------------------------- + +The Ada language has been designed to increase program specification +expressiveness and verification. Explicit constraints at the code level +can be used as the basis of both manual analysis (inspection), such as +code reviews, and automatic analysis, ranging from the compiler's +semantic consistency checks to the SPARK tools' formal proof of +program properties. + +Examples of Ada language features supporting analysis include: + +* type and subtype ranges and predicates +* parameter modes and subprogram contracts +* packages and private types (encapsulation) +* the Ravenscar concurrency profile +* minimal set of implicit or undefined behaviors + +.. index:: single: GNATmetric; Support for Analyzable Programs (D.2) +.. index:: single: GNATcheck; Support for Analyzable Programs (D.2) + +Tools such as GNATmetric and GNATcheck allow monitoring the complexity +and quality of the code and identifying potentially problematic constructs. +This is accomplished through techniques such as basic code size metrics, +cyclomatic complexity computation, and coupling analysis. + +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Analyzable Programs (D.2) + +GNAT SAS identifies potential run-time errors in the code. The number of +false positive results depends on the code complexity. A high number of +false positives is often a symptom of overly-complicated code. Using GNAT SAS +during development allows finding locations in the code that are +overly complex and provides information on what needs to be improved. + +.. index:: single: SPARK technology; Support for Analyzable Programs (D.2) + +The SPARK language is much more ambitious in analyzing programs, at the +extreme supporting full correctness proofs against formally specified +requirements. +It structurally forbids features such as exceptions, which complicate or +prevent formal analysis. +Code that is hard to analyze is often hard to understand and maintain, +and conversely. +Using SPARK as part of the development phase thus results in code that is +not only maximally analyzable but also clear and readable. + +.. index:: single: GNAT Studio IDE; Support for Analyzable Programs (D.2) + +During code review phases, GNAT Studio offers a variety of features that can +be used for program analysis, in particular call graphs, reference searches, +and other code organization viewers. + +.. index:: single: Annex D; Boundary Value Analysis (D.4) + +Boundary Value Analysis (D.4) +----------------------------- + +The objective of this technique is to verify and test the behavior of a +subprogram at the limits and boundaries values of its parameters. +AdaCore's technologies can provide complementary assurance on the quality +of this analysis and potentially decrease the number of tests that need +to be performed. + +.. index:: single: Ada language; Support for Boundary Value Analysis (D.4) + +Ada's strong typing allows refining types and variables boundaries. +For example: + +.. code-block:: ada + + type Temperature is new Float range -273.15 .. 1_000; + V : Temperature; + +Additionally, it's possible to define the specific behavior of values at +various locations in the code. For example, it's possible to define +relationships between the input and output of a subprogram, in the form +of a partitioning of the input domain: + +.. code-block:: ada + + function Compute (J : Integer) return Integer + with Contract_Cases => (J = Integer'First => Compute'Result = -1, + J = Integer'Last => Compute'Result = 1, + others => J - 1); + +The above shows an input partition of one parameter (but it can also be a +combination of several parameters). The behavior on the boundaries of :ada:`J` +is specified and can then either be tested (for example, with enabled +assertions) or formally proven with SPARK. Further discussion of input +partitioning can be found in the context of +:ref:`Railway_SW_Equivalence_Classes_and_Input_Partition_Testing`. + +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Boundary Value Analysis (D.4) + +Another possibility is to use GNAT SAS to identify possible values for +variables, and propagate those values from call to call, constructing +lists and/or ranges of potential values for each variable at each point +of the program. These are used as the input to run-time error analysis. +When used in full-soundness mode, GNAT SAS provides guarantees that the +locations it reports on the code are the only ones that may have run-time +errors, thus allowing a reduction of the scope of testing and review to +only these places. + +However, it's important to stress that GNAT SAS is only performing this +boundary value analysis with respect to potential exceptions and robustness. +No information is provided regarding the correctness of the values +produced by subprograms. + +GNAT SAS also has the capacity to display the possible values of variables +and parameters. This can be used as a mechanism to increase confidence +that testing has taken into account all possible boundaries for values. + +.. index:: single: SPARK technology; Support for Boundary Value Analysis (D.4) +.. index:: Absence of Run-Time Errors (AORTE) +.. index:: single: SPARK technology; Absence of Run-Time Errors (AORTE) + +SPARK has the ability to perform similar absence of run-time errors (AORTE) +analysis, thus reaching the same objectives. In addition to the above, +when requirements can be described in the form of boolean contracts, +SPARK can demonstrate correctness of the relation between input and output +on the entire range of values. + +.. index:: single: Annex D; Control Flow Analysis (D.8) +.. index:: single: GNAT Studio IDE; Support for Control Flow Analysis (D.8) + +Control Flow Analysis (D.8) +--------------------------- + +Control flow analysis requires identifying poor and incorrect data structures, +including unreachable code and useless tests in the code (such as conditions +that are always true). + +GNAT Studio can display call graphs between subprograms, allowing +visualization and analysis of control flow in the application. + +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Control Flow Analysis (D.8) + +GNAT SAS contributes to control flow analysis by identifying unreachable code, +as well as conditions being always true or always false. This analysis is +partial and needs to be completed with other techniques such as code review or +code coverage analysis, which together will allow reaching higher levels of +confidence. + +.. index:: single: GNATmetric; Support for Control Flow Analysis (D.8) + +GNATmetric can compute coupling metrics between units, helping to identify +loosely or tightly coupled units. + +.. index:: single: GNATstack; Support for Control Flow Analysis (D.8) + +GNATstack computes worst-case stack consumption based on the application's +call graph. This can help identify poorly structured code which consumes +too much memory on some sequences of calls. + +.. index:: single: Annex D; Data Flow Analysis (D.10) + +Data Flow Analysis (D.10) +------------------------- + +.. index:: single: GNAT Pro Assurance; Support for Data Flow Analysis (D.10) + +The GNAT Pro toolchain can be configured to detect uninitialized variables +at run-time through the use of the pragma :ada:`Initialize_Scalars`. +With this pragma, all scalars are automatically initialized to either an +out-of-range value (if there is one) or to an "unusual" value (either +the largest or smallest). +This significantly improves detection at test time. + +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Data Flow Analysis (D.10) + +GNAT SAS can detect suspicious and potentially incorrect data +flows, such as variables that are read before they are written +(uninitialized variables), variables written more than once without being +read (redundant assignments), and variables that are written but never read. +This analysis is partial and needs to be completed with other techniques +such as formal proof, code review or code coverage analysis, which together +allow reaching higher levels of confidence. + +.. index:: single: SPARK technology; Support for Data Flow Analysis (D.10) + +SPARK performs this analysis and much more, allowing the specification +and verification of data flow. This is used in the following activities: + +* verification that all inputs and outputs have been specified, + including possible side effects +* verification that all dependencies between inputs and outputs are specified +* verification that the implemented dataflow corresponds to the one specified + +Here's an example: + +.. code-block:: ada + + procedure Compute (A, B, C : Integer; R1, R2 : out Integer) + with Depends => (R1 => (A, B), + R2 => (B, C)); + + procedure Compute (A, B, C : Integer; R1, R2 : out Integer) is + begin + R1 := A + B; + R2 := A + B - C; + end Compute; + +:ada:`R1` is required to be computed from :ada:`A` and :ada:`B`, and :ada:`R2` +from :ada:`B` and :ada:`C`. However, in the procedure body, :ada:`R2` also +depends on :ada:`A`. SPARK's formal proof detects this error. + +The error is likewise detected in the presence of branches: + +.. code-block:: ada + + procedure Compute (A, B, C : Integer; R1, R2 : out Integer) is + begin + R1 := A + B; + if A = 0 then + R2 := B + C; + else + R2 := B - C; + end if; + end Compute; + +Here :ada:`R2` depends on the result of the expression :ada:`A = 0`, +so its value is actually computed from +:ada:`A`, :ada:`B` and :ada:`C`, and not just :ada:`B` and :ada:`C`. +As in the previous case, SPARK's formal analysis detects the error. + +A similar result occurs when the dependence is indirect, through a subprogram +call. +Here's an example based on a logging procedure that has a global state, +:ada:`Screen`, which is written to by the procedure: + +.. code-block:: ada + + procedure Log (V : String) + with Global => (Output => Screen), + Depends => (Screen => V) + + procedure Compute (A, B, C : Integer; R1, R2 : out Integer) + with Depends => (R1 => (A, B), + R2 => (B, C)); + + procedure Compute (A, B, C : Integer; R1, R2 : out Integer) is + begin + R1 := A + B; + R2 := B + C; + + if A = 0 then + Log ("A is 0"); + end if; + end Compute; + +The data flow does not correspond to the specification: :ada:`Compute` should +specify that it modifies :ada:`Screen`. So the incorrect code is detected. +The error is detected whether or not a branch is present, serving as a useful +complement to structural code coverage in many cases. + +.. index:: single: Annex D; Defensive Programming (D.14) + +Defensive Programming (D.14) +---------------------------- + +As stated in sub-clause D.14, the goal of defensive programming is to +"detect anomalous control flow, data flow, or data values ... \ +and react to them in a predetermined and acceptable manner". + +.. index:: single: Ada language; Support for Defensive Programming (D.14) + +Ada's strong typing will avoid the need for many situations where constraints +would be expressed in the form of defensive code. However, in some situations +strong typing is not enough. This can be the case, for example, when accessing +an element of an array. In this case, Ada allows expressing constraints in the +specification, through preconditions, postconditions or predicates. + +Beyond this, Ada provides specific support for a subset of what's specified +in the D.14 annex. GNAT SAS and SPARK will allow the development of defensive +programming in places where it makes the most sense. + +.. index:: single: GNATcheck; Support for Defensive Programming (D.14) + +Specific defensive code rules can also be defined in the coding standard and +their verification can then be automated through code analysis using, +for example, GNATcheck. + +.. index:: Range checking + +Data should be range checked +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ada offers types and subtypes that are naturally associated with ranges, e.g.: + +.. code-block:: ada + + subtype Percent is Integer range 0 .. 100; + -- Percent is the same type as Integer but with a run-time constraint on its range + + X, Y : Integer; + V : Percent; + ... + V := X + Y; -- Raises exception Constraint_Error if X + Y is not in 0 .. 100 + ... + +It's then the task of the developer to react to potential exceptions. +Alternatively, it's possible to write explicit verification in the code to +ensure that the expression is within its boundary: + +.. code-block:: ada + + V_Int : Integer; + V_Pct : Percent; + ... + V_Int := X+Y; + if V_Int in Percent then + V_Pct := V_Int; + else + ... -- Respond to out-of-range result + end if; + +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Defensive Programming (D.14) +.. index:: single: SPARK technology; Support for Defensive Programming (D.14) + +Another way to proactively ensure the absence of range check failure is +to use tools such as GNAT SAS or SPARK, which statically identify the +only possible locations in the code where such failures can happen. + +Note that run-time checks can be deactivated if needed for performance +reasons, for example once thorough testing or formal proof has been +performed. + +Data should be dimension-checked +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: single: GNAT Pro Assurance; Support for Defensive Programming (D.14) +.. index:: Dimension consistency analysis + +The GNAT Pro compiler provides a language extension for dimensional +consistency analysis, which ensures that variables are properly typed +according to their dimension. The system is implemented based on the +seven base dimensions (meter, kilogram, second, ampere, kelvin, mole, +candela), and will check that operations between these types are +consistent. +For example, a type :ada:`Speed` can be defined to represent time per +distance. Consistency between these types is checked at compile time +so that dimension errors will be reported as errors. For example: + +.. code-block:: ada + + D : Distance := 10; + T : Time := 1; + S : Speed := D / T; -- OK + My_Time : Time := 100; + ... + Distance_Traveled := S / My_Time; + -- Error, resulting dimension is Distance / Time**2 + -- The expression should be S * My_Time + +.. index:: single: Ada language; Support for Defensive Programming (D.14) +.. index:: single: Ada language; Parameter checking + +Read-only and read-write parameters should be separated and their access checked +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Ada, the parameter mode is specified in parameter specifications and +is checked by the compiler. For example, a read-only parameter is passed as +mode :ada:`in` and may not be modified. A read-write parameter is passed +either as mode :ada:`in out` or as mode :ada:`out` and is modifiable. +(The :ada:`out` mode is appropriate if the parameter is written before being +read). The compiler will produce an error for +an attempted modification of :ada:`in` parameters and detect when an +:ada:`in out` or :ada:`out` parameter is not modified and so could have been +passed as :ada:`in`. For example: + +.. code-block:: ada + + procedure P (V : in Integer) is + begin + V := 5; -- ERROR, V is mode "in" + end P; + +Functions should treat all parameters as read-only +-------------------------------------------------- + +The original version of Ada required that functions could only have :ada:`in` +parameters. +This restriction was relaxed in a later version of the standard, +but the original behavior can be reverted through a GNATcheck rule. +The SPARK Ada subset forbids functions with writable (i.e., :ada:`out` or +:ada:`in out` parameters). + +Literals and constants should not be write-accessible +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ada provides many kinds of literals (e.g. numeric, character, enumeration, +string) and allows declaring constants of any type +but ensures that their values can not be updated. + +.. code-block:: ada + + type Color is (Red, Blue, Green); + Answer : constant Integer := 42; + One_Third : constant := 1.0 / 3.0; + Greeting : String := "Hello"; + +The literals and constants are read-only as per language definition. +For example, trying to pass :ada:`Red` or :ada:`Answer` to a subprogram +as an :ada:`out` or :ada:`in out` parameter would be illegal. +Note that :ada:`Greeting` is a variable and can be assigned to, but +the literal :ada:`"Hello"` is immutable. + +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Defensive Programming (D.14) +.. index:: single: SPARK technology; Support for Defensive Programming (D.14) + +Using GNAT SAS and SPARK to drive defensive programming +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GNAT SAS and SPARK identify locations where there are potential run-time +errors |mdash| in other words, places where code is either wrong or where +defensive programming should be deployed. This helps guide the writing +of defensive code. For example: + +.. code-block:: ada + + procedure P (S : String; V : Integer) is + C : Character; + begin + ... + C := S (V); + ... + end P; + +In the above code, there's a use of :ada:`V` as an index into the +String :ada:`S`. +GNAT SAS and SPARK will detect the potential for a run-time error. Protection +of the code to prevent the error can take several forms: + +.. rubric:: Explicit test + +The application code checks that :ada:`V` is in range before using its +value as an index into the String. If the check fails, the appropriate +recovery action can be taken (here the procedure simply returns). + +.. code-block:: ada + + procedure P (S : String; V : Integer) is + C : Character; + begin + ... + if V not in S'Range then + return; + end if; + C := S (V) + ... + end P; + +.. rubric:: Precondition + +Here the error is detected at call time. If assertion checking is +enabled and the check fails, the :ada:`Assertion_Check` exception +is raised. + +.. code-block:: ada + + procedure P (S : String; V : Integer) + with Pre => V in S'Range + is + C : Character; + begin + ... + C := S (V); + ... + end P; + +The main difference between GNAT SAS and SPARK is that GNAT SAS may miss some +potential run-time errors (except when run only on small pieces of code if +configured in "sound" mode), while SPARK requires the use of the appropriate +Ada subset but is a sound technology (i.e., it will detect all potential +run-time errors). + +In general, the recommended Ada style is to use contracts instead of defensive +code. + +.. index:: single: Annex D; Coding Standards and Style Guide (D.15) +.. index:: single: GNATcheck; Support for Coding Standards and Style Guide (D.15) +.. index:: single: pragma Restrictions; Support for Coding Standards and Style Guide (D.15) + +Coding Standards and Style Guide (D.15) +--------------------------------------- + +A coding standard can be defined using a combination of predefined rules +(using GNAT options and GNATcheck rules) and appropriate arguments to +pragma :ada:`Restrictions`. + +.. _Railway_SW_Equivalence_Classes_and_Input_Partition_Testing: + +.. index:: single: GNAT Pro Assurance; Support for Coding Standards and Style Guide (D.15) +.. index:: single: SPARK technology; Support for Coding Standards and Style Guide (D.15) + +Equivalence Classes and Input Partition Testing (D.18) +------------------------------------------------------ + +This technique involves partitioning the various potential inputs to +subprograms and creating a testing and verification strategy based on +this partitioning. + +Ada extensions included in GNAT Pro for Ada can support partitioning at the +source code level. The partition is a list of conditions for inputs together +with their associated expected output, verifying the following criteria: + +* The full set of all potential values is covered +* There is no overlap between partitions + +These criteria can be verified either dynamically, by verifying at +test time that all inputs exercised fall into one and only one partition, +or formally by SPARK, proving that the partition are indeed complete +and disjoint. + +.. index:: Contract_Cases aspect + +Here's a simple example of such partitioning with two input variables: + +.. code-block:: ada + + function ArcTan (X, Y : Float) return Float with + Contract_Cases => + (X >= 0 and Y >= 0 => ArcTan'Result >= 0 and ArcTan'Result <= PI/2, + X < 0 and Y >= 0 => ArcTan'Result >= PI/2 and ArcTan'Result <= PI, + X < 0 and Y < 0 => ArcTan'Result >= PI and ArcTan'Result <= 3 * PI/2, + X >= 0 and Y < 0 => ArcTan'Result >= 3 * PI/2 and ArcTan'Result <= 2 * PI); + +The presence of these contracts enable further verification. At run time, +they act as assertions and allow verification that the form of the output +indeed corresponds to the expected input. If SPARK is used, it's possible +to formally verify the correctness of the relation between the input and +properties. + +.. index:: single: Annex D; Error Guessing (D.20) +.. index:: single: GNATfuzz; Support for Error Guessing (D.20) + +Error Guessing (D.20) +--------------------- + +The GNATfuzz tool for fuzz testing (part of the GNAT Dynamic Analysis Suite) +supports the Error Guessing technique and can provide evidence for a system's +robustness. +GNATfuzz exercises a program with a large number of automatically generated +test values, often random or malformed, and checks for crashes, hangs, +and other anomalous behavior. + +.. index:: single: Annex D; Failure Assertion Programming (D.24) +.. index:: single: pragma Assert; Support for Failure Assertion Programming (D.24) +.. index:: single: Contract-based programming; Support for Failure Assertion Programming (D.24) + +Failure Assertion Programming (D.24) +------------------------------------ + +Ada offers a large variety of assertions (contracts) that can be defined +in the code, either through pragmas or aspects. + +* Pragma :ada:`Assert` + + This pragma allows verification within a sequence of statements: + + .. code-block:: ada + + A := B + C; + pragma Assert (A /= 0); + D := X / A; + +* Pre- and postcondition contracts + + Pre- and postconditions can be defined as subprogram aspects: + + .. code-block:: ada + + procedure Double (X : in out Integer) + with Pre => X < 100, + Post => X = X'Old * 2; + +* Predicates and invariants + + Predicate and invariant contracts can be defined on types: + + .. code-block:: ada + + type Even is new Integer + with Dynamic_Predicate => Even mod 2 = 0; + +These contracts can be checked dynamically, for example, during testing. +The developer has fine control over which contracts can be removed +(e.g. for improved performance) and which should remain in the deployed +software. + +.. index:: single: SPARK technology; Support for Failure Assertion Programming (D.24) + +The contracts can be used by the static analysis and formal proof tools. +GNAT SAS uses contracts to refine its analysis and exploits them as +assertions, even if it may not be able to demonstrate that they are correct. +In this manner, contracts provide the tool with additional information +on the code behavior. SPARK can go further and either prove their +correctness, or else report its inability to do so. (In the latter case, +the issue is either that the contract or the code is incorrect, or that +the proof engine is not powerful enough to construct a proof.) + +.. index:: single: Annex D; Formal Methods (D.28) +.. index:: single: SPARK technology; Support for Formal Methods (D.28) + +Formal Methods (D.28) +--------------------- + +With SPARK, formal methods are used to define and check certain architectural +properties, in particular for data coupling specification and verification. +For example: + +.. code-block:: ada + + G : Integer; + + procedure P (X, Y : Integer) + with Global => (Output => G), + Depends => (G => (X, Y)); + +In the above example, the side effect of the subprogram is fully defined: +:ada:`P` is modifying :ada:`G`. SPARK will check that this side effect, +and no other, is present. :ada:`G` is specified as depending on the values +of :ada:`X` and :ada:`Y`. Again, SPARK will analyze the code to check that +the variable relationships specified are correct. + +In this example, an actual variable is used to define data flow. +It's also possible to create an "abstract" state, implemented by a set of +variables. Generally speaking, although these notations and verifications +are quite useful on the lower levels of the architecture, they may not be +that pertinent at higher levels. SPARK is flexible with regard to where +this should be checked or and where it should not. + +At the lower level of the design phases, some properties and requirements +can be refined or specified in the form of boolean expressions. +SPARK will allow expressing these properties, including the formalism of +first-order logic (quantifiers). These properties can be expressed in the +form of subprogram preconditions, postconditions, type invariants and type +predicates. For example: + +.. code-block:: ada + + -- P must have an input greater or equal to 10, and then has to modify V. + procedure P (V : in out Integer) + with Pre => V >= 10, + Post => V'Old /= V; + + -- Variables of type Even must be even + type Even is new Integer + with Dynamic_Predicate => Even mod 2 = 0; + + -- Arrays of this type are always sorted in ascending order + type Sorted_Array is array (Integer range <>) of Integer + with Dynamic_Predicate => + Sorted_Array'Size <= 1 or else + (for all I in Sorted_Array'First .. Sorted_Array'Last - 1 => + Sorted_Array (I) <= Sorted_Array (I + 1)); + +These properties can be formally verified through the SPARK toolset, using +state of the art theorem proving methodologies. Testing aimed at verifying +the correctness of these properties can then be simplified, if not entirely +removed. + +.. index:: single: Annex D; Impact Analysis (D.32) +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Impact Analysis (D.32) + + +Impact Analysis (D.32) +---------------------- + +Identifying the effect of a change on entire software component requires +the combination of various techniques, including reviews, testing and static +analysis. GNAT SAS has specific features to identify the impact of a change +from the perspective of potential run-time errors. It can establish a baseline +with regard to potential failure analysis and filter only the potential +defects that have been introduced or repaired following a change in the code. + +.. index:: single: GNAT Studio IDE; Support for Impact Analysis (D.32) + +GNAT Studio can provide call graphs and call trees, allowing the developer +to see how a function is called in the software. This can be directly used +in impact analysis. + +.. index:: single: Annex D; Information Encapsulation (D.33) + +.. index:: single: Ada language; Support for Information Encapsulation (D.33) + +Information Encapsulation (D.33) +-------------------------------- + +Information encapsulation is good software engineering practice, +enforcing access to data on a "need to know" basis and preventing +hard-to-detect bugs from erroneous updates to global variables. +Encapsulation has been intrinsic to the Ada design since the earliest +version of the language and is embodied in the syntax and semantics +of a variety of language features. + +.. index:: single: Ada language; Object-Oriented Programming (OOP) + +Ada's approach to encapsulation achieves similar methodological benefits to +Object-Oriented Programming, but with a different syntax. +In most OO languages, a class is both a type (which can be +instantiated to produce objects) and a module (which can +be separately compiled). Ada separates these concepts, +modeling a class by a type (typically a private type, as will +be shown below) defined with a package (the main unit of +modularization in Ada). + +.. rubric:: Separation of specification and body + +The various program units in Ada |mdash| packages, tasks, subprograms, +generic templates |mdash| have a structure that supports the separation of +the unit's specification (its interface to other units) and its +implementation (inaccessible externally). +This physical separation not only supports encapsulation but also +facilitates independent development of the two parts. For example, +a package specification can be produced during the detailed design +phase, with the body fleshed out later, perhaps by a different +developer, during the implementation phase. + +.. rubric:: Package structure + +.. index:: single: Ada language; Package feature + +A package comprises at least a specification and, if necessary, +a body that implements the subprograms and other entities whose +specifications are in the package specification. +The package specification in general consists of a visible part +and a private part. In a typical scenario, the visible part declares +a type as :ada:`private`, along with subprogram specifications +for the operations that are relevant to that type. +The type and operations form the interface for that type. +The private part of the package specification then provides +the full declaration of the type, and the package body supplies +the bodies for the subprograms defined for the type. + +External to the package, the type name and the operations +defined for the type are accessible, but the representational details +for the full type declaration are hidden. +This allows the designer of the package to modify the representation +of the type during development or maintenance, without requiring +source code changes to client code. +This principle is sometimes referred to as *data abstraction*. +Here is an example: + +.. code-block:: ada + + package Counters is + type Counter is private; + -- We don't want to give access to the representation of the counter here + + procedure Increment (C : in out Counter); + procedure Print (C : in out Counter); + + private + + type Counter is new Integer; + -- Here, Counter is an Integer, but it could change to something + -- else if needed without disturbing the interface. + end Counters; + + with Ada.Text_IO; + package body Counters is + procedure Increment (C : in out Counter) is + begin + C := C + 1; + end Increment; + + procedure Print (C : in out Counter) is + begin + Ada.Text_IO.Put_Line (C'Img); + end Print; + end Counters; + +As a variation on this example, Ada supports encapsulation through +"getter" and "setter" subprograms. +Rather than directly manipulating a global variable declared in a +package specification, the program can be structured to enforce +accesses through a procedural interface: + +.. code-block:: ada + + package Data is + function Value return Integer; -- "Getter" function + procedure Set (New_Value : Integer); -- "Setter" procedure + end Data; + + package body Data is + Global : Integer := 0; + + function Value return Integer is + begin + return Global; + end Value; + + procedure Set (New_Value : Integer) is + begin + Value := New_Value; + end Set; + end Data; + +.. index:: single: Ada language; Concurrent programming +.. index:: single: Ada language; Task object / task type +.. index:: single: Ada language; Protected object / Protected type + +.. rubric:: Concurrency + +Both of Ada's tasking constructs |mdash| the task and the protected object +|mdash| enforce encapsulation. + +* A task object or task type specification defines its interface + (its entries, which are used for synchronization and communication), and its + body defines the implementation. + +* A protected object or protected type specification defines its interface + (entries and procedures, which are executed with mutual exclusion), + and its body defines the implementation. + The private part of a protected object/type specification + encapsulates the data that is being protected: it can only be accessed + externally through the entries and procedures that it defines. + +.. index:: single: Ada language; Representation clause + +.. rubric:: Representation clauses + +As another form of encapsulation, +Ada's representation clause facility +separates an entity's logical properties |mdash| +its interface to client code |mdash| and its representation. +For example: + +.. code-block:: ada + + type Alert is (Low, Medium, High); + + type Packet is record + Flag : Boolean; + Danger : Alert; + Data : Interfaces.Unsigned_8; + end record; + + Byte : constant := 8; + + for Alert use (Low => 0, Medium => 5, High => 10); + for Alert'Size use 4; + + for Packet use record + Flag at 0*Byte range 3 .. 3; -- Bits 1..2 are unused + Danger at 0*Byre range 4 .. 7; + Data at 1*Byte range 0 .. 7; + end Packet; + for Packet'Size use 2*Byte; + + +.. index:: single: Annex D; Interface Testing (D.34) +.. index:: single: Ada language; Support for Interface Testing (D.34) + +Interface Testing (D.34) +------------------------ + +Ada allows extending the expressiveness of an interface specification +at the code level, allowing constraints such as: + +* parameter passing modes +* pre- and postconditions +* input partitioning +* typing + +These are each described in other sections of this document. +These specifications can help the development of tests around the interface, +formalize constraints on how the interface is supposed to be used, +and activate additional dynamic checking or formal proofs (through SPARK), +all ensuring that users are indeed respecting the expectations of the +interface designer. + +.. index:: single: GNATtest; Support for Interface Testing (D.34) + +In addition, GNATtest can generate a testing framework to implement +interface testing, and GNATfuzz can help by probing the robustness +of the system when interface requirements are violated. + +.. _Railway_SW_Language_Subset: + +.. index:: single: Annex D; Language Subset (D.35) +.. index:: single: pragma Restrictions; Support for Language Subset (D.35) + +Language Subset (D.35) +---------------------- + +The Ada language has been designed to facilitate subsetting, since its +targeted domain |mdash| long-lived safety-critical embedded systems |mdash| +often involves small-footprint applications that need to be certified +under demanding software standards. The full language would be inappropriate +with such constraints, and Ada provides a general feature |mdash| pragma +:ada:`Restrictions` |mdash| to allow subsetting on a user-selectable basis. +For example, with :ada:`pragma Restrictions (No_Abort_Statements)` +the program will be rejected by the compiler if it contains an :ada:`abort` +statement. + +.. index:: single: Ravenscar Profile; Support for Language Subset (D.35) + +Going one step further, the language standard has bundled a set of +restrictions into a so-called profile |mdash| the Ravenscar Profile |mdash| +that supports common concurrency idioms (e.g. periodic and sporadic tasks) +and can make a tasking program deterministic and statically analyzable. + +.. index:: SPARK language; Support for Language Subset (D.35) + +SPARK is a natural Ada language subset, constraining the language so that +programs can be subject to formal analysis (e.g., safe pointers, +no aliasing, and no exceptions). + +.. index:: single: Certifiable profile; Support for Language Subset (D.35) +.. index:: single: GNATcheck; Support for Language Subset (D.35) + +Other language subsets can be supplied by the implementation, such as +the features implemented by the GNAT Pro Certifiable Profiles. +And with GNATcheck the user can in effect define a subset in an *à la carte* +fashion, to specify prohibited constructs and verify that they are +not present in the code. + +.. index:: single: Annex D; Metrics (D.37) +.. index:: single: GNATmetric; Support for Metrics (D.37) + +Metrics (D.37) +-------------- + +The GNATmetric tool reports various metrics on the code, from simple +structural metrics such as lines of code or number of entities to more +complex computations such as cyclomatic complexity or coupling. + +Custom metrics can be computed based on these first-level metrics. +In particular, the GNATdashboard environment allows gathering all metrics +into a database that can then accessed through Python or SQL. + +These metrics can be viewed through various interfaces. + +.. index:: single: Annex D; Modular Approach (D.38) + +Modular Approach (D.38) +----------------------- + +Connections between modules shall be limited and defined, coherence shall be strong +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: Ada language; Support for Modular Approach (D.38) +.. index:: Project (GNAT Pro); Support for Modular Approach (D.38) +.. index:: Child package; Support for Modular Approach (D.38) +.. index:: Private package; Support for Modular Approach (D.38) + +Ada allows the developer to define group of packages that have different +levels of coupling, through the notions of *child packages* and +*private packages* as described below. +In addition, the GNAT Pro technology provides the notion of a *project*, +which defines a group of packages, possibly with a defined interface. +These constructs can be used to define a tool-supported notion of "component" +or "module" at the software level. + +.. index:: Ada language; Coupling between modules + +There are three main types of dependence between compilation units: + +* Loose coupling through :ada:`with` clauses. If unit :ada:`Q` + :ada:`with`\ s unit :ada:`P`, then :ada:`Q` can only access + the entities in the visible part of :ada:`P`. + +* Medium coupling through public child units. + If :ada:`P` is a package, + then child :ada:`P.Q` has visibility privileges that would + not be available to a unit that only :ada:`with`\ s :ada:`P`. + More specifically, :ada:`P.Q`, which is said to be a *public + child*, can access the entities in the visible part of :ada:`P`. + However, only the private part and body of :ada:`P.Q` can + access the entities in the private part of :ada:`P`. + And the entities declared in the body of :ada:`P` are + only accessible in the package body itself. + +* Tight coupling through private child units. + As a generalization of public child units, + if :ada:`P.Q` is declared as a *private* child, then + the visible part of :ada:`P.Q` can also access the entities + in the private part of :ada:`P`. + This does not compromise encapsulation; the only units that + can :ada:`with` a private child are units that otherwise would + have access to the entities that the private child can see. + +Ada's expressiveness makes it easier to develop large software systems, with +precise control over the coupling between modules, and guaranteeing +that data are only accessed by the intended units. + +A typical example is the implementation of a complex system that needs to be +spread across several packages. +For example, suppose that packages :ada:`Communication` and :ada:`Interfaces`, +contribute to the implementation of a signaling protocol. +In Ada, this design can be implemented in three (or more) distinct files: + +.. code-block:: ada + + package Signaling is ... + private package Signaling.Communication is . + private package Signaling.Interfaces is ... + +The two private packages are defined in separate files. They are private +children of :ada:`Signaling`, which means they can only be used by the +implementation of :ada:`Signaling`, and not by any module outside of the +hierarchy. + +.. index:: GNATmetric; Metrics on inter-package coupling + +In addition, tools can provide metrics on coupling between packages. +GNATmetric has built-in support for retrieving these numbers. + +.. index:: Project (GNAT Pro); GPR files + +At a coarser granularity, packages can be grouped together into a +GNAT Project file ("GPR"), with a clear interface. +An application architecture can be defined as a combination of project files. + +Collections of subprograms shall be built providing several level of modules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Following the above example, it's possible to create public sub-modules +as well, creating a hierarchy of services. +Public child units are accessible to client code. + +Subprograms shall have a single entry and single exit only +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: GNATcheck; Support for Modular Approach (D.38) + +The GNATcheck tool has specific rules to verify this property +on any Ada code. + +Modules shall communicate with other modules via their interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: Ada language; Support for Modular Approach (D.38) + +This is built-in to the Ada language. It's not possible to circumvent +a package's interface. +If a module is implemented using a coarser granularity, e.g. as a group of +packages or at project level, then the project file description allows +identifying those packages that are part of the interface and those packages +that are not. + +Module interfaces shall be fully documented +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Although this is mostly the responsibility of the developer, +Ada contracts can be used to formalize part of the documentation +associated with a package interface, using a formal notation that can be +checked for consistency by the compiler. +This addresses the part of the documentation that can be +expressed through boolean properties based on the software-visible entities. + +Interfaces shall contain the minimum number of parameters necessary +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The GNAT Pro compiler will warn about parameters not used by a subprogram +implementation. + +.. index:: GNATcheck; Support for Modular Approach (D.38) + +A suitable restriction of parameter number shall be specified, typically 5 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GNATcheck allows specifying a maximum number of parameters per subprogram. + +Unit Proof and Unit Test +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: GNATtest; Support for Modular Approach (D.38) + +GNATtest can be used to generate a unit testing framework for Ada +applications. + +.. index:: SPARK technology; Support for Modular Approach (D.38) + +SPARK performs a modular formal verification: it proves the postcondition +of a subprogram according to its own precondition and the precondition +and postconditions of its callees, whether or not these callees are +themselves proven. + +For a complete proof, all the subprograms of an application need +to be formally proven. +Where this is not possible, one subset can be proven +and the other can be assumed to be true. +These assumptions can then be verified using traditional testing methodology, +allowing for a hybrid test / proof verification system. + +.. index:: Ada language; Support for Strongly Typed Programming Languages (D.49) + +Strongly Typed Programming Languages (D.49) +------------------------------------------- + +Ada is, from its inception, a strongly typed language, which supports +both static and dynamic verification. + +From a static verification point of view, each type is associated with a +representation and a semantic interpretation. Two types with similar +representations but different semantics will still be considered different +by the compiler. For example: + +.. code-block:: ada + + type Kilometers is new Float; + type Miles is new Float: + +These are distinct types. +the compiler will not allow mixed operations, for example assigning a +:ada:`Kilometers` value to a :ada:`Miles` variable, or adding +a :ada:`Kilometers` value and a :ada:`Miles` value, unless explicit +conversions are used. +Mixing floating point and integer values is similar: the developer is +responsible for deciding where and how conversion should be made. + +From a dynamic verification point of view, types can be associated with +constraints, such as value ranges or arbitrary boolean predicates. +These type ranges and predicates will be verified at specific points in +the application, allowing the early detection of inconsistencies. + +.. index:: single: Annex D; Structure Based Testing (D.50) + +.. index:: GNATtest; Support for Structure Based Testing (D.50) +.. index:: GNATemulator; Support for Structure Based Testing (D.50) +.. index:: GNATcoverage; Support for Structure Based Testing (D.50) + +Structure Based Testing (D.50) +------------------------------ + +AdaCore provides three tools to support structure based testing: + +* GNATtest is a unit testing framework generator. It will run on Ada + specifications, and generate a skeleton for each subprogram. + The actual test can then be manually written into that skeleton. + +* GNATemulator allows emulating code for a given target (e.g. PowerPC + and Leon) on a host platform such as Windows or Linux. + It's particularly well suited for running unit tests. + +* GNATcoverage performs structural coverage analysis from an instrumented + platform (GNATemulator or Valgrind on Linux or directly on a board through + a Nexus probe). + It supports statement coverage and decision coverage as well as MC/DC. + Note that although |en-50128| requires compound condition coverage, + Modified Condition/Decision Coverage (MC/DC) is usually accepted as + a means of compliance. + +.. index:: single: Annex D; Structured Programming (D.53) + +.. index:: Ada language; Support for Structured Programming (D.53) + +Structured Programming (D.53) +----------------------------- + +The Ada language supports all the usual paradigms of structured programming. +Complexity can be controlled with various tools, see +:ref:`Railway_SW_Analyzable_Programs` for more details. + +.. index:: single: Annex D; Suitable Programming Languages (D.54) +.. index:: Ada language; Support for Suitable Programming Languages (D.54) + +Suitable Programming Languages (D.54) +------------------------------------- + +Ada is noted as "Highly Recommended" in the list of programming +languages. +Some features may, however, not be suitable for the highest SIL. +To enforce the detection and rejection of specific features, the +developer can specify a language subset; see :ref:`Railway_SW_Language_Subset`. + +One of the advantage of the Ada language is that it is precisely defined +in a international document, ISO/IEC 8652. +This document specifies the required effect as well as any +implementation-defined behavior for the core language, the standard Ada +libraries (known as the "predefined environment"), and the specialized needs +annexes. + +.. index:: single: Annex D; Object Oriented Programming (D.57) + +.. index:: Ada language; Support for Object Oriented Programming Languages (D.57) + +Object Oriented Programming (D.57) +---------------------------------- + +Ada supports the usual constructs for object-oriented programming, but, for +reasons of simplicity and reliability, with multiple inheritance limited to +:ada:`interface` types. +In addition, the :index:`Liskov Substitution Principle` can be verified +through class-wide contracts and SPARK formal verification, allowing the +verification of class hierarchy consistency and the safety of dispatching +operations. + +Ada's OOP model is particularly well suited to safety-critical applications, +as it allows instantiating objects on the stack. For example: + +.. code-block:: ada + + type Base_Class is tagged ...; -- Base_Class is the root of a class hierarchy + procedure P (X : Base_Class); + ... + type Subclass is new Base_Class with ...; + overriding procedure P (X : Subclass); + + B : Base_Class := ... -- on the stack + S : Subclass := ... -- on the stack + + X : Some_Type'Class := (if .. then B else S): + P (X); -- Dispatches to appropriate version of P + +In the above code, :ada:`X` is a polymorphic object that can be initialized +with a value from any class in the hierarchy rooted at :ada:`Base_Class`; +here it will be a value from either :ada:`Base_Class` or :ada:`Subclass`. +Storage for :ada:`X` is reserved on the stack, and the invocation :ada:`P (X)` +will dispatch to the appropriate version of :ada:`P`. + +The booklet :cite:`AdaCore_2016` provides additional information on how to use +object-oriented features in a certified context. + +.. index:: single: Annex D; Procedural Programming (D.60) + +.. index:: Ada language; Support for Procedural Programming (D.60) + +Procedural Programming (D.60) +----------------------------- + +Ada implements all the usual features of procedural programming languages, +with a general-purpose data type facility and a comprehensive set of control +constructs. diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/tools.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/tools.rst new file mode 100644 index 000000000..56b9b7e67 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/tools.rst @@ -0,0 +1,1111 @@ +.. include:: ../../../global.txt + +AdaCore Tools and Technologies Overview +======================================= + +.. index:: single: Ada language; History + +.. _Railway_SW_Ada: + +Ada +--- + +.. _Railway_SW_Background: + +Background +~~~~~~~~~~ + +.. index:: Ichbiah (Jean), Taft (Tucker) + +Ada is a modern programming language designed for large, long-lived +applications |mdash| and embedded systems in particular |mdash| where +reliability, maintainability, and efficiency are essential. +It was originally developed in the early 1980s (this version is +generally known as Ada 83) by a team led by Jean Ichbiah at +CII-Honeywell-Bull in France. The language was revised and +enhanced in an upward compatible fashion in the early 1990s, +under the leadership of Tucker Taft from Intermetrics in the U.S. + +The resulting language, Ada 95, was the first internationally +standardized (ISO) object-oriented language. Under the auspices +of ISO, a further (minor) revision was completed as an amendment +to the standard; this version of the language is known as Ada 2005. +Additional features (including support for contract-based programming +in the form of subprogram pre- and postconditions and type invariants) +were added in the Ada 2012 version of the language standard, and a +number of features to increase the language's expressiveness were +introduced in Ada 2022 (see :cite:`ISO_IEC_2016`, :cite:`Barnes_Brosgol_2015`, +:cite:`Barnes_2014`, :cite:`ISO_IEC_2022` for information about Ada). + +.. index:: Lovelace (Augusta Ada), Babbage (Charles), Byron (Lord George) + +The name "Ada" is not an acronym; it was chosen in honor of +Augusta Ada Lovelace (1815-1852), a mathematician who is +regarded as the world's first programmer because of her work with +Charles Babbage. She was also the daughter of the poet Lord Byron. + +The Ada language is seeing significant usage worldwide in high-integrity / +safety-critical / high-security domains including railway systems, +commercial and military aircraft avionics, air traffic control, and +medical devices. + +With its embodiment of modern software engineering principles, Ada +is an excellent teaching language for both introductory and advanced +computer science courses, and it has been the subject of significant +university research especially in the area of real-time technologies. +The so-called :index:`Ravenscar Profile` |mdash| a subset of the language's +concurrency features with deterministic semantics |mdash| broke new ground +in supporting the use of concurrent programming in high assurance software. + +AdaCore has a long history and close connection with the Ada programming +language. Company members worked on the original Ada 83 design and review +and played key roles in the Ada 95 project as well as the subsequent +revisions. AdaCore's initial GNAT compiler was essential to the growth of +Ada 95; it was delivered at the time of the language's standardization, +thus guaranteeing that users would have a quality implementation for +transitioning to Ada 95 from Ada 83 or other languages. + +.. _Railway_SW_Language_Overview: + +Language Overview +~~~~~~~~~~~~~~~~~ + +Ada is multi-faceted. From one perspective it is a classical stack-based +general-purpose language, not tied to any specific development methodology. +It has a simple syntax, structured control statements, flexible data +composition facilities, strong type checking, traditional features for code +modularization ("subprograms"), and a mechanism for detecting and responding +to exceptional run-time conditions ("exception handling"). +But it also includes much more: + +.. index:: single: Ada language; Scalar ranges + +Scalar Ranges +^^^^^^^^^^^^^ + +Unlike languages based on C syntax (such as C++, Java, and C#), Ada allows the +programmer to simply and explicitly specify the range of values that are +permitted for variables of scalar types (integer, floating-point, fixed-point, +and enumeration types). The attempted assignment of an out-of-range value +causes a run-time error. The ability to specify range constraints makes +programmer intent explicit and makes it easier to detect a major source of +coding and user input errors. It also provides useful information to +static analysis tools and facilitates automated proofs of program properties. + +Here's an example of an integer scalar range: + +.. code-block:: ada + + declare + Score : Integer range 1..100; + N : Integer; + begin + ... -- Code that assigns a value to N + Score := N; + -- A run-time check verifies that N is within the range 1..100 + -- If this check fails, the Constraint_Error exception is raised + end; + +.. index:: single: Ada language; Contract-based programming +.. index:: single: Ada language; Preconditions +.. index:: single: Ada language; Postconditions + +Contract-Based Programming +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A feature introduced in Ada 2012 allows extending a subprogram specification +or a type/subtype declaration with a contract (a Boolean assertion). +Subprogram contracts take the form of preconditions and postconditions, +type contracts are used for invariants, and subtype contracts provide +generalized constraints (predicates). Through contracts the developer can +formalize the intended behavior of the application, and can +verify this behavior by testing, static analysis or formal proof. + +Here's a skeletal example that illustrates contact-based programming; a +:ada:`Table` object is a fixed-length container for distinct :ada:`Float` +values. + +.. code-block:: ada + + package Table_Pkg is + type Table is private; -- Encapsulated type + + procedure Insert (T : in out Table; Item: in Float) + with Pre => not Is_Full(T) and not Contains(T, Item), + Post => Contains(T, Item); + + procedure Remove (T : in out Table; Item: out Float); + with Pre => Contains(T, Item), + Post => not Contains(T, Item); + + function Is_Full (T : in Table) return Boolean; + function Contains (T : in Table; Item: in Float) return Boolean; + ... + private + ... -- Full declaration of type Table + end Table_Pkg; + + package body Table_Pkg is + ... -- Implementation of Insert, Remove, Is_Full, and Contains + end Table_Pkg; + +A compiler option controls whether the pre- and postconditions +are checked at run time. If checks are enabled, +any pre- or postcondition failure |mdash| i.e., the contract's +Boolean expression evaluating to :ada:`False` |mdash| raises the +:ada:`Assertion_Error` exception. + +.. index:: single: Ada language; Programming in the large + +Programming in the large +^^^^^^^^^^^^^^^^^^^^^^^^ + +The original Ada 83 design introduced the package construct, +a feature that supports encapsulation ("information hiding") and +modularization, and which allows the developer to control the +namespace that is accessible within a given compilation unit. Ada 95 +introduced the concept of "child units," adding considerable flexibility +and easing the design of very large systems. +Ada 2005 extended the language's modularization facilities by allowing +certain kinds of mutual references between package specifications, +thus making it easier to interface with languages such as Java. + +.. index:: single: Ada language; Generic templates + +Generic Templates +^^^^^^^^^^^^^^^^^ + +A key to reusable components is a mechanism for parameterizing modules +with respect to data types and other program entities, for example a +stack package for an arbitrary element type. Ada meets this requirement +through a facility known as "generics"; since the parameterization is done +at compile time, run-time performance is not penalized. + +.. index:: single: Ada language; Object-Oriented Programming (OOP) + +Object-Oriented Programming (OOP) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ada 83 was object-based, allowing the partitioning of a system into modules +corresponding to abstract data types or abstract objects. +Full OOP support was not provided since, first, it seemed not to be required +in the real-time domain that was Ada's primary target, +and, second, the apparent need for automatic garbage collection in an +Object-Oriented language would have interfered with predictable and efficient +performance. + +However, large real-time systems often have components such as GUIs that do +not have real-time constraints and that could be most effectively developed +using OOP features. In part for this reason, Ada 95 supplies comprehensive +support for OOP, through its "tagged type" facility: classes, polymorphism, +inheritance, and dynamic binding. Ada 95 does not require automatic garbage +collection but rather supplies definitional features allowing the developer +to supply type-specific storage reclamation operations ("finalization"). +Ada 2005 brought additional OOP features including Java-like interfaces and +traditional :ada:`obj.op(...)` operation invocation notation. + +Ada is methodologically neutral and does not impose a distributed overhead for +OOP. If an application does not need OOP, then the OOP features do not have +to be used, and there is no run-time penalty. +See :cite:`Barnes_2014` or :cite:`AdaCore_2016` for more details.. + +.. index:: single: Ada language; Concurrent programming + +Concurrent Programming +^^^^^^^^^^^^^^^^^^^^^^ + +Ada supplies a structured, high-level facility for concurrency. The unit of +concurrency is a program entity known as a "task". Tasks can communicate +implicitly via shared data or explicitly via a synchronous control mechanism +known as the rendezvous. A shared data item can be defined abstractly as a +"protected object" (a feature introduced in Ada 95), with operations executed +under mutual exclusion when invoked from multiple tasks. +Protected objects provide the functionality of semaphores and condition +variables but more clearly and reliably (e.g., avoiding subtle race +conditions). + +Ada supports asynchronous task interactions for timeouts, software event +notifications, and task termination. Such asynchronous behavior is deferred +during certain operations, to prevent the possibility of leaving shared data +in an inconsistent state. Mechanisms designed to help take advantage of +multi-core architectures were introduced in Ada 2012. + +.. index:: single: Ada language; Systems programming + +Systems Programming +^^^^^^^^^^^^^^^^^^^ + +Both in the "core" language and the Systems Programming Annex, Ada supplies +the necessary features for hardware-specific processing. +For example, the programmer can specify the bit layout for fields in a record, +define alignment and size properties, place data at specific machine +addresses, and express specialized code sequences in assembly language. +Interrupt handlers can be written in Ada, using the protected type facility. + +.. index:: single: Ada language; Real-time programming + +Real-Time Programming +^^^^^^^^^^^^^^^^^^^^^ + +Ada's tasking facility and the Real-Time Systems Annex support common idioms +such as periodic or event-driven tasks, with features that can help avoid +unbounded priority inversions. A protected object locking policy is defined +that uses priority ceilings; this has an especially efficient implementation +in Ada (mutexes are not required) since protected operations are not allowed +to block. Ada 95 defined a task dispatching policy that basically requires +tasks to run until blocked or preempted. Subsequent versions of the language +standard introduced several other policies, such as Earliest Deadline First. + +.. index:: single: Ada language; High-integrity systems +.. index:: single: Ada language; Prevention of vulnerabilities +.. index:: single: Ada language; Prevention of buffer overflow +.. index:: single: Ada language; Memory safety +.. index:: single: Ada language; Strong typing +.. index:: single: Ada language; Prevention of null pointer dereferencing +.. index:: single: Ada language; Prevention of dangling references +.. index:: Buffer overflow +.. index:: Memory safety + +High-Integrity Systems +^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: Common Criteria security standard + +With its emphasis on sound software engineering principles, Ada supports the +development of high-integrity applications, including those that need to be +certified against safety standards such |en-50128| for rail systems, +|do-178c| :cite:`RTCA_EUROCAE_2011a` for avionics, and security standards +such as the Common Criteria :cite:`CCDB_2022`. +Key to Ada's support for high-assurance software is the language's +memory safety; this is illustrated by a number of features, including: + +* *Strong typing* + + Data intended for one purpose will not be accessed via inappropriate + operations; errors such as treating pointers as integers (or vice versa) + are prevented. + +* *Array bounds checking* + + A run-time check guarantees that an array index is within the bounds of + the array. + This prevents buffer overflow vulnerabilities that are common in C and C++. + In many cases a a compiler optimization can detect statically that the + index is within bounds and thus eliminate any run-time code for the check. + +* *Prevention of null pointer dereferences* + + As with array bounds, pointer dereferences are checked to make sure that + the pointer is not null. + Again, such checks can often be optimized out. + +* *Prevention of dangling references* + + A scope accessibility checks ensures that a pointer cannot reference an + object on the stack after exit/return from the scope (block or subprogram) + in which the object is declared. Such checks are generally static, + with no run-time overhead. + +.. index:: single: Ada language; pragma Restrictions + +However, the full language may be inappropriate in a safety-critical +application, since the generality and flexibility could interfere +with traceability / certification requirements. Ada addresses this issue by +supplying a compiler directive, :ada:`pragma Restrictions`, that +allows constraining the language features to a well-defined subset +(for example, excluding dynamic OOP facilities). + +The evolution of Ada has seen the continued increase in support for +safety-critical and high-security applications. Ada 2005 +standardized the :index:`Ravenscar Profile`, a collection of concurrency +features that are powerful enough for real-time programming but +simple enough to make certification and formal analysis practical. + +.. index:: Contract-based programming +.. index:: single: Ada language; Contract-based programming + +Ada 2012 introduced contract-based programming facilities, allowing the +programmer to specify preconditions and/or postconditions for subprograms, +and invariants for encapsulated (private) types. These can serve both +for run-time checking and as input to static analysis tools. + +The most recent version of the standard, Ada 2022, has added several +contract-based programming constructs inspired by SPARK +(:ada:`Contract_Cases`, :ada:`Global`, and :ada:`Depends` aspects) and, +more generally, has enhanced the language's expressiveness. For example, +Ada 2022 has introduced some new syntax in its concurrency support and has +defined the :index:`Jorvik tasking profile `, which is more +inclusive than :index:`Ravenscar `. + +Summary +^^^^^^^ + +In brief, Ada is an internationally standardized language combining +object-oriented programming features, well-engineered concurrency +facilities, real-time support, and built-in reliability through both +compile-time and run-time checks. As such it is an appropriate +language for addressing the real issues facing software developers +today. Ada has a long and successful history and is used throughout +a number of major industries to design software that protects +life and property. + +.. index:: SPARK language +.. index:: SPARK Pro toolsuite +.. index:: GNATprove +.. index:: single: SPARK language; Usage +.. index:: single: SPARK Pro toolsuite; GNATprove + + +.. _Railway_SW_SPARK: + +SPARK +----- + +SPARK is a software development technology (programming language and +verification toolset) specifically designed for engineering +ultra-low defect level applications, for example where safety +and/or security are key requirements. SPARK Pro is AdaCore's +commercial-grade offering of the SPARK technology. The main component +in the toolset is GNATprove, which performs formal verification on +SPARK code. + +SPARK has an extensive industrial track record. Since its inception +in the late 1980s it has been used worldwide in a range of +industrial applications such as railway signaling, civil and military +avionics, air traffic management / control, cryptographic +software, and cross-domain solutions. + +The SPARK language has been stable over the years, with periodic +enhancements. The 2014 version of SPARK represented a major revision +:cite:`McCormick_Chapin_2015`, :cite:`AdaCore_Altran_2020`), +incorporating contract-based programming +syntax from Ada 2012, and subsequent upgrades included support for pointers +(access types) based on the Rust ownership model. + +Flexibility +~~~~~~~~~~~ + +SPARK offers the flexibility of configuring the language on a per-project +basis. Restrictions can be fine-tuned based on the relevant coding +standards or run-time environments. +SPARK code can easily be combined with full Ada code or with C, so that +new systems can be built on and reuse legacy codebases. + +.. index:: single: SPARK language; Static verification +.. index:: single: SPARK language; Formal verification +.. index:: single: SPARK technology; Absence of Run-Time Errors (AORTE) + +Powerful Static Verification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The SPARK language supports a wide range of static verification techniques. +At one end of the spectrum is basic data and control flow analysis, i.e., +exhaustive detection of errors such as attempted reads of uninitialized +variables, and ineffective assignments (where a variable is assigned a +value that is never read). For more critical applications, dependency +contracts can constrain the information flow allowed in an application. +Violations of these contracts |mdash| potentially representing violations of +safety or security policies |mdash| can then be detected even before the code +is compiled. + +In addition, the language supports mathematical proof and can thus provide +high confidence that the software meets a range of assurance requirements: +from the absence of run-time errors ("AORTE"), to the enforcement of safety +or security properties, to compliance with a formal specification of the +program's required behavior. + +Ease of Adoption +~~~~~~~~~~~~~~~~ + +User experience has shown that the language and the SPARK Pro toolset do not +require a steep learning curve. Training material such as AdaCore's online +AdaLearn course for SPARK :cite:`AdaCore_AdaLearn` can quickly bring +developers up to speed; users are assumed to be experts in their own +application domain such as railway software and do not need to be familiar +with formal methods or the proof technology implemented by the toolset. +In effect, SPARK Pro is an advanced static analysis tool that will detect +many logic errors very early in the software life cycle. It can be smoothly +integrated into an organization's existing development and verification +methodology and infrastructure. + +SPARK uses the standard Ada 2012 contract syntax, which both simplifies the +learning process and also allows new paradigms of software verification. +Programmers familiar with writing executable contracts for run-time assertion +checking can use the same approach but with additional flexibility: the +contracts can be verified either dynamically through classical run-time +testing methods or statically (i.e., pre-compilation and pre-test) using +automated tools. + +.. index:: single: SPARK language; Hybrid verification +.. index:: Hybrid verification + +.. _Railway_SW_Hybrid_Verification: + +Hybrid Verification +~~~~~~~~~~~~~~~~~~~ + +SPARK supports "hybrid verification", which combines testing and +formal proofs. +As an example, an existing project in Ada and C can adopt SPARK to implement +new functionality for critical components. The SPARK units can be analyzed +statically to achieve the desired level of verification, with testing +performed at the interfaces between the SPARK units and the modules in the +other languages. + +.. index:: single: SPARK language; Reduced cost of verification + +Reduced Cost and Improved Efficiency of Executable Object Code Verification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Software verification typically involves extensive testing, including unit +tests and integration tests. Traditional testing methodologies are a major +contributor to the high delivery costs for safety-critical software. +Furthermore, they may fail to detect errors. SPARK addresses this issue by +allowing automated proof to be used to demonstrate functional correctness +at the subprogram level, either in combination with or as a replacement +for unit testing. +In the high proportion of cases where proofs can be discharged automatically, +the cost of writing unit tests is completely avoided. Moreover, verification +by proofs covers all execution conditions and not just a sample. + +.. index:: GNAT Pro Assurance + +.. _Railway_SW_GNAT_Pro_Assurance: + +GNAT Pro Assurance +------------------ + +.. index:: single: GNAT Pro Assurance; Sustained branch +.. index:: Sustained branch +.. index:: single: GNAT Pro Assurance; GNAT Pro for Ada +.. index:: single: GNAT Pro Assurance; GNAT Pro for C +.. index:: single: GNAT Pro Assurance; GNAT Pro for C++ +.. index:: single: GNAT Pro Assurance; GNAT Pro for Rust +.. index:: C language support +.. index:: C++ language support +.. index:: Rust language support + +.. _Railway_SW_Sustained_Branches: + +Sustained Branches +~~~~~~~~~~~~~~~~~~ + +GNAT Pro Assurance is a specialized version of the GNAT Pro development +environment, available for any of the products in the GNAT Pro family: +GNAT Pro for Ada, GNAT Pro for C, GNAT Pro for C++, and GNAT Pro for Rust. +It is targeted to projects +requiring customized support, including bug fixes and "known problems" +analyses, on a specific version of the toolchain. This service is +especially suitable for applications with long maintenance cycles or +certification requirements, since critical updates to the compiler or +other product components may become necessary years after the initial +release. Such customized maintenance of a specific version of the product +is known as a *sustained branch*. + +A project on a sustained branch can monitor relevant known +problems, analyze their impact and, if needed, update to a newer version +of the product on the same development branch (i.e., not incorporating +changes introduced in later versions of the product). + +Sustained branches are a practical solution to the problem of ensuring +toolchain stability while allowing flexibility in case an upgrade is +needed to correct a critical problem. + +Language and Tool Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +GNAT Pro Assurance for Ada supports all versions of the Ada +language standard as well as multiple versions of C (C89, C99, and C11). +It provides an Integrated Development Environment +(see :ref:`Railway_SW_Integrated_Development_Environments`), a comprehensive toolsuite +including a visual debugger, and an extensive set of libraries and bindings. +Details on the GNAT Pro for Ada toolchain may be found in +:cite:`AdaCore_Web_UG_Native`. +AdaCore's GNAT project facility, based on a multi-language builder for +systems organized into subsystems and libraries, is documented in +:cite:`AdaCore_Web_GPR`. + +.. index:: single: GNAT Pro Assurance; Configurable Run-Time Libraries + +.. _Railway_SW_Configurable_Run-Time_Libraries: + +Configurable Run-Time Libraries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: Light Profile +.. index:: Light-Tasking Profile +.. index:: Certifiable profile + +Two specific GNAT-defined run-time libraries have been designed with +certification in mind and are known as the Certifiable Profiles +(see :cite:`AdaCore_Web_UG_Cross`): + +* *Light Profile* + +* *Light-Tasking Profile* + +The Light Profile provides a flexible Ada subset that is supported by a +certifiable Ada run-time library. Depending on application requirements, +this profile can be further restricted through the :ada:`Restrictions` pragma, +with the application only including run-time code that is used by the +application. + +These run-time libraries can also be customized directly to suit +certification requirements: unneeded packages can be removed to allow for +self-certification of the runtime, while the "|nbhyphen| nostdlib" linker +switch can be used to prevent the use of the runtime. Even when the run-time +library is suppressed, some run-time sources are still required to provide +compile-time definitions. While this code produces no object code, the +certification protocol may still require tests to ensure correct access +to these definitions. + +.. index:: Ravenscar Profile + +The Light-Tasking Profile expands the Light Profile to include Ravenscar +tasking support, allowing developers to use concurrency in their certification +applications. + +Although limited in terms of dynamic Ada semantics, all Certifiable Profiles +fully support static Ada constructs such as private types, generic templates, +and child units. Some dynamic semantics are also supported. For example, +these profiles allow the use of tagged types (at library level) and other +Object-Oriented Programming features, including dynamic dispatching. +The general use of dynamic dispatching at the application level can be +prevented through pragma :ada:`Restrictions`. + +A traditional problem with predefined profiles is their inflexibility: +if a feature outside a given profile is needed, then it is the developer's +responsibility to address the certification issues deriving from its use. +GNAT Pro Assurance accommodates this need by allowing the developer to define +a profile for the specific set of features that are used. Typically this will +be for features with run-time libraries that require associated certification +materials. Thus the program will have a tailored run-time library supporting +only those features that have been specified. + +More generally, the configurable run-time capability allows specifying support +for Ada's dynamic features in an |a-grave| la carte fashion ranging from none +at all to full Ada. +The units included in the executable may be either a subset of +the standard libraries provided with GNAT Pro, or specially tailored to the +application. This latter capability is useful, for example, if one of the +predefined profiles implements almost all the dynamic functionality needed +in an existing system that has to meet new safety-critical requirements, +and where the costs of adapting the application without the additional +run-time support are considered prohibitive. + + +Full Implementation of Ada Standards +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GNAT Pro provides a complete implementation of the Ada language from Ada 83 +to Ada 2012, and support for selected features from Ada 2022. +Developers of safety-critical and high-security systems can thus take +advantage of features such as contract-based programming, which effectively +embed requirements in the source program text and simplify verification. + +.. index:: single: GNAT Pro Assurance; Source-to-object traceability + +Source to Object Traceability +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A compiler option can limit the use of language constructs that generate +object code that is not directly traceable to the source code. +As an add-on service, AdaCore can perform an analysis that demonstrates +this traceability and justifies any remaining cases of non-traceable code. + +.. index:: single: AdaCore; Support services +.. index:: single: AdaCore; Training and consulting services + +Safety-Critical Support and Expertise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +At the heart of every AdaCore subscription are the support services that +AdaCore provides to its customers. AdaCore staff are recognized experts on +the Ada language, software certification standards in several domains, +compilation technologies, and static and dynamic verification. +They have extensive experience in supporting customers in railway, avionics, +space, energy, air traffic management/control, automotive, and military +projects. Every AdaCore product comes with front-line support provided +directly by these experts, who are also the developers of the technology. +This ensures that customers' questions (requests for guidance on feature +usage, suggestions for technology enhancements, or defect reports) are +handled efficiently and effectively. + +Beyond this bundled support, AdaCore also provides Ada language and tool +training as well as on-site consulting on topics such as how to best deploy +the technology, and assistance on start-up issues. On-demand tool development +and ports to new platforms are also available. + +.. index:: Libadalang +.. index:: single: GNAT Pro Assurance; Libadalang + +Libadalang +~~~~~~~~~~ + +Libadalang is a library included with GNAT Pro that gives applications access +to the complete syntactic and semantic structure of an Ada compilation unit. +This library is typically used by tools that need to perform some sort of +static analysis on an Ada program. + +AdaCore can assist customers in developing libadalang-based tools to meet +their specific needs, as well as develop such tools upon request. + +Typical libadalang applications include: + +* Static analysis (property verification) +* Code instrumentation +* Design and document generation tools +* Metric testing or timing tools +* Dependency tree analysis tools +* Type dictionary generators +* Coding standard enforcement tools +* Language translators (e.g., to CORBA IDL) +* Quality assessment tools +* Source browsers and formatters +* Syntax directed editors + +.. index:: GNATstack +.. index:: single: GNAT Pro Assurance; GNATstack + +.. _Railway_SW_GNATstack: + +GNATstack +~~~~~~~~~ + +Included with GNAT Pro is GNATstack, a static analysis tool that enables an +Ada/C software developer to accurately predict the maximum size of the memory +stack required for program execution. + +GNATstack statically predicts the maximum stack space required by each task +in an application. The computed bounds can be used to ensure that sufficient +space is reserved, thus guaranteeing safe execution with respect to stack +usage. The tool uses a conservative analysis to deal with complexities such +as subprogram recursion, while avoiding unnecessarily pessimistic estimates. + +This static stack analysis tool exploits data generated by the compiler to +compute worst-case stack requirements. It performs per-subprogram stack usage +computation combined with control flow analysis. + +GNATstack can analyze object-oriented applications, automatically determining +maximum stack usage on code that uses dynamic dispatching in Ada. +A dispatching call challenges static analysis because the identity of the +subprogram being invoked is not known until run time. GNATstack solves this +problem by statically determining the subset of potential targets (primitive +operations) for every dispatching call. This significantly reduces the +analysis effort and yields precise stack usage bounds on complex Ada code. + +GNATstack's analysis is based on information known at compile time. When the +tool indicates that the result is accurate, the computed bound can never be +exceeded. + +On the other hand, there may be cases in which the results will not be +accurate (the tool will report such situations) because of some missing +information (such as the maximum depth of subprogram recursion, indirect +calls, etc.). The user can assist the tool by specifying missing call graph +and stack usage information. + +GNATstack's main output is the worst-case stack usage for every entry point, +together with the paths that result in these stack sizes. +The list of entry points can be automatically computed (all the tasks, +including the environment task) or can be specified by the user (a list of +entry points or all the subprograms matching a given regular expression). + +GNATstack can also detect and display a list of potential problems when +computing stack requirements: + +* Indirect (including dispatching) calls. The tool will indicate the number + of indirect calls made from any subprogram. +* External calls. The tool displays all the subprograms that are reachable + from any entry point for which there is no stack or call graph information. +* Unbounded frames. The tool displays all the subprograms that are reachable + from any entry point with an unbounded stack requirement. + The required stack size depends on the arguments passed to the subprogram. + For example: + + .. code-block:: ada + + procedure P(N : Integer) is + S : String (1..N); + begin + ... + end P; + +* Cycles. The tool can detect all the cycles (i.e., potential recursion) in + the call graph. + +GNATstack allows the user to supply a text file with the missing information, +such as the potential targets for indirect calls, the stack requirements for +external calls, and the maximal size for unbounded frames. + + +.. index:: GNAT Static Analysis Suite (GNAT SAS) + +.. _Railway_SW_GNAT_Static_Analysis_Suite: + +GNAT Static Analysis Suite (GNAT SAS) +------------------------------------- + +.. index:: Defects and vulnerability analysis (in GNAT SAS) +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); Defects and vulnerability analysis + +Defects and Vulnerability Analyzer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GNAT SAS features an Ada source code analyzer that detects run-time and logic +errors. It assesses potential bugs and vulnerabilities before program +execution, serving as an automated peer reviewer, helping to find errors +easily at any stage of the development life-cycle. It helps improve code +quality and makes it easier to perform safety and/or security +analysis. + +The defects and vulnerability analyzer can detect several of the +"Top 25 Most Dangerous Software Errors" in the Common Weakness Enumeration. +It is a stand-alone tool that runs on Windows and Linux platforms and +may be used with any standard Ada compiler or fully integrated into the +GNAT Pro development environment. + + +.. index:: GNATmetric +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); GNATmetric + +GNATmetric +~~~~~~~~~~ + +The GNATmetric tool analyzes source code to calculate a set of commonly used +industry metrics, thus allowing developers to estimate the size and better +understand the structure of the source code. This information also +facilitates satisfying the requirements of certain software development +frameworks. + +.. index:: GNATcheck +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); GNATcheck + +.. _Railway_SW_GNATcheck: + +GNATcheck +~~~~~~~~~ + +GNATcheck is a coding standard verification tool that is extensible and +rule-based. It allows developers to completely define a project-specific +coding standard as a set of rules, for example a subset of permitted +language features and/or code formatting and style conventions. +It verifies a program's conformance with the resulting rules and thereby +facilitates demonstration of a system's compliance with a certification +standard's requirements on language subsetting. + +GNATcheck provides: + +* An integrated "Ada Restrictions" mechanism for banning specific features + from an application. This can be used to restrict features + such as tasking, exceptions, dynamic allocation, fixed- or floating point, + input/output, and unchecked conversions. + +* Restrictions specific to GNAT Pro, such as banning features that result + in the generation of implicit loops or conditionals + in the object code, or in the generation of elaboration code. + +* Additional Ada semantic rules resulting from customer input, such as + ordering of parameters, normalized naming of entities, and + subprograms with multiple returns. + +* An easy-to-use interface for creating and using a complete coding standard. + +* Generation of project-wide reports, including evidence of the level of + compliance with a given coding standard. + +* Over 30 compile-time warnings from GNAT Pro that detect typical error + situations, such as local variables being used before being + initialized, incorrect assumptions about array lower bounds, infinite + recursion, incorrect data alignment, and accidental hiding of names. + +* Style checks that allow developers to control indentation, casing, + comment style, and nesting level. + +AdaCore's :index:`GNATformat` tool :cite:`AdaCore_Web_GNATformat`, which +formats Ada source code according to the GNAT coding style +:cite:`AdaCore_Coding_Style`, can help avoid having code that violates +GNATcheck rules. GNATformat is included in the GNAT Pro for Ada toolchain. + +GNATcheck comes with a query language (LKQL, for Language Kit Query Language) +that lets developers define their own checks for any in-house rules that need +to be followed. +GNATcheck can thus be customized to meet an organization's specific +requirements, processes and procedures. + + +.. index:: GNAT Dynamic Analysis Suite (GNAT DAS) + +.. _Railway_SW_GNAT_Dynamic_Analysis_Suite: + +GNAT Dynamic Analysis Suite (GNAT DAS) +-------------------------------------- + +.. index:: GNATtest +.. index:: single: GNAT Dynamic Analysis Suite (GNAT DAS); GNATtest + +.. _Railway_SW_GNATtest: + +GNATtest +~~~~~~~~ + +The GNATtest tool helps create and maintain a complete unit testing +infrastructure for complex projects. It captures +the simple idea that each public subprogram (these are known as +"visible" subprograms in Ada) should have at least one corresponding +unit test. GNATtest takes a project file as input, and produces two outputs: + +* The complete harnessing code for executing all the unit tests under + consideration. This code is generated completely automatically. + +* A set of separate test stubs for each subprogram to be tested. + These test stubs are to be completed by the user. + +GNATtest handles Ada's Object-Oriented Programming features and can be used +to help verify tagged type substitutability (the Liskov Substitution +Principle) that can be used to demonstrate consistency of class hierarchies. + +Testing a private subprogram is outside the scope of GNATtest but can be +implemented by defining the relevant testing code in a private child of the +package that declares the private subprogram. +Additionally, hybrid verification can help (see :ref:`Railway_SW_Hybrid_Verification`): +augmenting testing with the use of SPARK to formally prove relevant properties +of the private subprogram. + +.. index:: GNATemulator +.. index:: single: GNAT Dynamic Analysis Suite (GNAT DAS); GNATemulator + +GNATemulator +~~~~~~~~~~~~ + +GNATemulator is an efficient and flexible tool that provides integrated, +lightweight target emulation. + +Based on the QEMU technology, a generic and open-source machine emulator +and virtualizer, GNATemulator allows software developers to +compile code directly for their target architecture and run it on their +host platform, through an approach that translates from the +target object code to native instructions on the host. This avoids the +inconvenience and cost of managing an actual board, while offering an +efficient testing environment compatible with the final hardware. + +There are two basic types of emulators. The first can serve as a surrogate +for the final hardware during development for a wide range of verification +activities, particularly those that require time accuracy. However, they +tend to be extremely costly, and are often very slow. The second, which +includes GNATemulator, does not attempt to be a complete time-accurate +target board simulator, and thus it cannot be used for all aspects of +testing. But it does provide a very efficient and cost-effective way to +execute the target code very early in the development and verification +processes. GNATemulator thus offers a practical compromise between a native +environment that lacks target emulation capability, and a cross configuration +where the final target hardware might not be available soon enough or in +sufficient quantity. + +.. index:: GNATcoverage +.. index:: single: GNAT Dynamic Analysis Suite (GNAT DAS); GNATcoverage + +GNATcoverage +~~~~~~~~~~~~ + +GNATcoverage is a code coverage analysis tool. Its results are computed from +trace files that show which program constructs have been exercised by a given +test campaign. With source code instrumentation, the tool produces these files +by executing an alternative version of the program, built from source code +instrumented to populate coverage-related data structures. +Through an option to GNATcoverage, the user can specify the granularity of +the analysis: statement coverage, decision coverage, or Modified Condition / +Decision Coverage (MC/DC). + +Source-based instrumentation brings several major benefits: efficiency of tool +execution (much faster than alternative coverage strategies using binary +traces and target emulation, especially on native platforms), compact-size +source trace files independent of execution duration, and support for coverage +of shared libraries. + +.. index:: single: GNAT Dynamic Analysis Suite (GNAT DAS); GNATfuzz +.. index:: GNATfuzz + +.. _Railway_SW_GNATfuzz: + +GNATfuzz +~~~~~~~~ + +GNATfuzz is a fuzzing tool; i.e., a tool that automatically +and repeatedly executes tests and generates new test cases at a very high +frequency to detect faulty behavior of the system under test. Such anomalous +behavior is captured by monitoring the system for triggered exceptions, +failing built-in assertions, and signals such as SIGSEGV. + +Fuzz testing has proven to be an effective mechanism for finding corner-case +vulnerabilities that traditional human-driven verification mechanisms, +such as unit and integration testing, can miss. +Since such vulnerabilities can often lead to malicious exploitations, +fuzzing technology can help meet security verification +requirements. + +However, fuzz-testing campaigns are complex and time-consuming to construct, +execute and monitor. GNATfuzz simplifies the process by analyzing a code base +and identifying subprograms that can act as fuzz-test entry points. GNATfuzz +then automates the creation of test harnesses suitable for fuzzing. +In addition, GNATfuzz will automate the building, executing and analyzing +of fuzz-testing campaigns. + +GNATfuzz can serve a useful role as part of the software development +and verification life cycle processes. For example, by detecting +anomalous behavior such as data corruption due to +task or interrupt conflicts, GNATfuzz can help prevent defects from being +introduced into the source code. + +.. index:: TGen +.. index:: single: GNAT Dynamic Analysis Suite (GNAT DAS); TGen + +TGen +~~~~ + +TGen is an experimental run-time library / marshalling technology that can be +used by :index:`GNATtest` and/or :index:`GNATfuzz` to automate the production +of test cases for Ada code. It performs type-specific low-level processing to +generate test vectors for subprogram parameters, such as uniform value +distribution for scalar types and analogous strategies for unconstrained +arrays and record discriminants. A command-line argument specifies the number +of test values to be generated, and these can then be used as input to test +cases created by GNATtest. + +TGen can also be used with GNATfuzz, to help start a fuzz-testing campaign +when the user supplies an initial set of test cases where some may contain +invalid data. GNATfuzz will utilize coverage-driven fuzzer mutations coupled +with TGen to convert invalid test cases into valid ones. TGen represents test +data values compactly, removing a large amount of memory padding that would +otherwise be present for alignment of data components. With its +space-efficient representation, TGen significantly increases the probability +of a successful mutation that results in a new valid test case. + +.. index:: GNAT Pro for Rust +.. index:: Rust language support + +GNAT Pro for Rust +----------------- + +The Rust language was designed for software that needs to meet stringent +requirements for both assurance and performance: Rust is a memory-safe +systems-programming language with software integrity guarantees (in both +concurrent and sequential code) enforced by compile-time checks. The language +is seeing growing use in domains such as automotive systems and is a viable +choice for railway software. + +AdaCore's GNAT Pro for Rust is a complete development environment for the +Rust programming language, supporting both native builds and cross compilation +to embedded targets. The product is not a fork of the Rust programming +language or the Rust tools. Instead, GNAT Pro for Rust is a professionally +supported build of a selected version of rustc and other core Rust development +tools that offers stability for professional and high-integrity Rust projects. +Critical fixes to GNAT Pro for Rust are upstreamed to the Rust community, +and critical fixes made by the community to upstream Rust tools are backported +as needed to the GNAT Pro for Rust code base. +Additionally, the Assurance edition of GNAT Pro for Rust includes the +"sustained branch" service (see :ref:`Railway_SW_Sustained_Branches`) that strikes the +balance between tool stability and project flexibility. + +.. index:: Integrated Development Environments (IDEs) + +.. _Railway_SW_Integrated_Development_Environments: + +Integrated Development Environments (IDEs) +------------------------------------------ + +.. index:: single: Integrated Development Environments (IDEs); GNAT Studio +.. index:: GNAT Studio IDE + +GNAT Studio +~~~~~~~~~~~ + +GNAT Studio is a powerful and simple-to-use IDE that streamlines software +development from the initial coding stage through testing, debugging, system +integration, and maintenance. It is designed to allow programmers to get the +most out of GNAT Pro technology. + +**Tools** + +GNAT Studio's extensive navigation and analysis tools can generate a variety +of useful information including call graphs, source dependencies, +project organization, and complexity metrics, giving a thorough understanding +of a program at multiple levels. It allows interfacing with third-party +version control systems, easing both development and maintenance. + +**Robust, Flexible and Extensible** + +Especially suited for large, complex systems, GNAT Studio can import existing +projects from other Ada implementations while adhering to their +file naming conventions and retaining the existing directory organization. +Through the multi-language capabilities of GNAT Studio, components +written in C and C++ can also be handled. The IDE is highly extensible; +additional tools can be plugged in through a simple scripting +approach. It is also tailorable, allowing various aspects of the program's +appearance to be customized in the editor. + +**Easy to learn, easy to use** + +GNAT Studio is intuitive to new users thanks to its menu-driven interface +with extensive online help (including documentation on all the +menu selections) and "tool tips". The Project Wizard makes it simple to get +started, supplying default values for almost all of the project properties. +For experienced users, it offers the necessary level of control for +advanced purposes; e.g., the ability to run command scripts. Anything that +can be done on the command line is achievable through the menu interface. + +**Remote Programming** + +Integrated into GNAT Studio, Remote Programming provides a secure and +efficient way for programmers to access any number of remote servers +on a wide variety of platforms while taking advantage of the power and +familiarity of their local PC workstations. + +.. index:: single: Integrated Development Environments (IDEs); VS Code support +.. index:: VS Code support + +VS Code Extensions for Ada and SPARK +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +AdaCore's extensions to Visual Studio Code (VS Code) enable Ada and SPARK +development with a lightweight editor, as an alternative to the full +GNAT Studio IDE. Functionality includes: + +* Syntax highlighting for Ada and SPARK files +* Code navigation +* Error diagnostics (errors reported in the Problems pane) +* Build integration (execution of GNAT-based toolchains from within VS Code) +* Display of SPARK proof results (green/red annotations from GNATprove) +* Basic IntelliSense (completion and hover information for known symbols) + +.. index:: single: Integrated Development Environments (IDEs); GNATbench +.. index:: single: Integrated Development Environments (IDEs); Workbench +.. index:: single: Integrated Development Environments (IDEs); Eclipse +.. index:: Workbench IDE (Wind River) +.. index:: Eclipse IDE +.. index:: GNATbench IDE + +Eclipse Support |ndash| GNATbench +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GNATbench is an Ada development plug-in for Eclipse and Wind River's Workbench +environment. The Workbench integration supports Ada development on a variety +of VxWorks real-time operating systems. The Eclipse version is primarily +for native applications, with some support for cross development. In both +cases the Ada tools are tightly integrated. + +.. index:: single: Integrated Development Environments (IDEs); GNATdashboard +.. index:: GNATdashboard IDE + +GNATdashboard +~~~~~~~~~~~~~ + +GNATdashboard serves as a one-stop control panel for monitoring and improving +the quality of Ada software. It integrates and aggregates the results of +AdaCore's various static and dynamic analysis tools (GNATmetric, GNATcheck, +GNATcoverage, SPARK Pro, among others) within a common interface, helping +quality assurance managers and project leaders understand or reduce +their software's technical debt, and eliminating the need for manual input. + +GNATdashboard fits naturally into a continuous integration environment, +providing users with metrics on code complexity, code coverage, +conformance to coding standards, and more. diff --git a/content/booklets/adacore-technologies-for-railway-software/conf.ini b/content/booklets/adacore-technologies-for-railway-software/conf.ini new file mode 100644 index 000000000..d43866fb3 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/conf.ini @@ -0,0 +1,5 @@ +[DEFAULT] +title=AdaCore Technologies for Railway Software +author=Jean-Louis Boulanger \\and Quentin Ochem +version=2.1 +bibtex_file=references.bib diff --git a/content/booklets/adacore-technologies-for-railway-software/images/fig-1.png b/content/booklets/adacore-technologies-for-railway-software/images/fig-1.png new file mode 100644 index 0000000000000000000000000000000000000000..f60b9e7258b05edb8ae1c0967210415f55d003a5 GIT binary patch literal 41637 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 q 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 ahD;Tx28pekgoTc zLDBE`_xs)V{?@(sk9Vz?wOqn^&a=-xyU*VHJic-=61dnT*dP!H_sQc&&p;py;8(P- z|3HBM4pQ$M0RMsQo=H3a<#m%S1Am|!i%N@vK!rg#C%V8?v@JO)MX~eqbM(9HKeo0r ziz_`tVqW@(JybX1SJW|m^)@B9XlZ3_dVV1$Jx5Z{f?Zn8H#%u}V#@YS;C&fgC8uC* z&)8SVbtx@N>78o^J}KO)7FcvV3NP&T4-Rjzi3n)fS_bFF*H7C;7Kt0X<1-6~mi0?o zc$4vpxA%PeIygeiD;ZeOL-SYz#=u)pRUcV37Lt@!(b&SKVDc`z^SN8Z4UR{m`Y!6$ zF1H^lHMAr2o#1yxq(ch6;NV^Xwj-x&i;e;HN~$t)3&F&~j;f)cKg`O;dJNlkNn63-sUYf;fMhZXnUAR<#Rbd=Sx7LieZ z`rMR?mWli>y{-QTJ?8+DTlbiF9z>Q6sF}N`d|uG9^$z&dW*?a57@X-6mJ^iQW#yB| zDj=?H?<1*h`T`y)uB6ZXP==0;&nKZ{#A?c;`y8}>!#^bUuJ%)#gENx92S1va4ndNY*?-t z+H4x#e)vo~q_ErjLv2FKibmpiVD+MD+LTk?Y--2aT_ramw^Dpg>1({tq(b_iyzi!z zu?eaD4v#NOsGlN!q$lR{8H+&(hxx$`L6w&Ua~?%=Vf9NYv12K%t9Z=9HonP|lap7k zUUhYKg+ien9UTb?2{<@7D=RCrv$GNs62ij5{r&y5wY8d>nqR+uZEkL6V`JOh-L0so zU}tBSlatHH$gs7w-QVA*prANDK9-i277-D#u(06c!67)KzgvOAFJ7cKzPl_f8aK&Oh8>U-adIG zs_3k>Uh5K1(e`T5XBK=-0QCCv^gWx+E25idPvp^=5$bNNJVukmuxY9d@U1Ik3aKF` z!^t{oMR&u{e3Ji}QMep5VJCrHla%Hj<y(mXXz+Bld za0eF!Cv7o4tqGH<#zakfYFj+v`)c*U2T5g?R^`N1({EU)_pTM2c9@pUe(Pd#nn+<{ zte=Ibu$9>lCbFQOZrg6?wKA#ARXwP!IH7MH)LN&XgCj9bF3~8C)ErwPd2m{>@v>~g zUWJqtwWQ&~TZgqHQcdp6J6+6%YcLgZ9Mt%|g%yXjZ!c^2lhs;>rSpWSQPk+{s5Bc% z%fs)F@+Uq{&JMoV%d;X=)@q9N`Zw9bE5zdHw~@48Yf5WI- zUbTfESvaPVa2v&g@ZjR%o0bP&oaVdqDzvy4`?tYU_oQM;81LS&j`)UR3N5Ao@E6NX zFY&qCW&KJ|QG82wi|>f6Y{VxC6tbng_3KTVY6PzPR}&2hyf-M8%Lx&%<-Cq)S}@Pe z4!=O_aJa#=4x7Fan?Cj`QVhcJTQ{%q;1cOr0vo0bs7%2}H{b}vD#h%CZ-XIHJ^@B- zDSINsazZ-r<=|c^>V67ZNGB$Yg`6$6qG`t$Pte!N>p2%G!Vqq1G)K+$~I@rv;Yv0RBCw2jUN+q&;t;rNdYSNyn>8b8H( zC_lnoYqnA+KV$zbeebFMXm*cq&Cb`)6q9`Y!?l`Z0nB|+TJzQEwny3WRVgl*tCLR% zhj|(is^dFz`s>GOoTG-FVB#+Z57s@|lHCvkpwjhs8P2`U0)~#W@euvlWXr%TE-gv> z2fJSUyLa57nJ{Y+-lXonx`*~wTh|_O9QR9JnL}sLH>_Qs8ga=-aMCGIT(V3*4@!IT zNIm-W;fcA$8cV~l$Ebn=gbqsN@odjdYxp95Fyakk=OqQ3%*+xn5af4ByI# zscHxZj}l8d;`@thpXFJhUy|m4z2Up}!{dGN_Z`OYj`r)X>YP;=)@av>b(SQ9$)F~N z;}jIUWxU(^*-|dIQe&ht1(C{x52Yosz!Xk@+i31GU8l=S!o1>E_MW_`n=|dZzLTTIPeWPl7U7y>qyo6?AuKVr`_{Il) z_EPRQ9Nmfc{K^aa+Rfvx$>`c*6k{uLseVGRg2IR8WAi2KyOGL2MTA*-dFjTqLcm<_ ze_ZSPb`*D{>0QP6G(v?&VP=~sIiWBX+i4B#@)Q9bB&!KVU8Z`hw+6#gB+j_p(R)B$=zn z2kL)2=o^AFT9vn1RltY?5 zg9#g^5Nz;oBs=mExU0jv+*O@JAq!D#j&HN^XwiPNm!_OeC0{>kaJ3fm3tOwD?JgJt z^xF;1D=m(fu02!PJF;cfr?kI`Hi3BwGYj#lW$k6j`L#T~Y}VTa&cEGNVti+OV_wUS za9G^PVV-#M>Lo!A!+DL#kAoRr)>hhJR5vPN*~fi=ZMN4@FXi4>Ck<=`EscFnIZHnp zAzA{QKy8BA9v6v%!p81Zdp~WI#gi2>j4YDW__Er4-@GvU+IKDt;%Oa)7MY9dQiHRsL_dxAVR$i*SJ(@z8dh636?A;n#Aa>q z6)ft=AfAqM*RF`>YB)18o4YktQrQQ>jH}_it?oY;KPA|CC{Lu*FfYGIR)+Rahp#eW zVul{0N>U!m({I8d#0&f!!dV)Ghr78g2BAC+_yN*uz4i2V3gi=ejy4gGV~6iNe|Idt z@qmy=XPdV8-NYI_9!a48@G})U00Rz@fg;jtP+El5W8&oRU|H!vNuLs2Ydw77GP|X2 zO}ED-Aa!-T8DgEU00L5F2qiKOl2=67svKg()1HOmuFeK32Jl(Y>5PwHycMVV5BTP! zI`!^$2p^L5nM@TJ1QsdKIo`o!cM~(P)q&_A1rBc_9es^sWeA1QsRG$!MU8!QkCB@*Ih!AFBu}Y;iIxi(Go(;Cikg>rs%^b>VrO zX`5bgDVUtod$DR8e#+PiV}sO}s+rHQ;i%AQUfu|jeMp~)&R}cukDFWom=BV&z@Xi` zKS8knVxgxUV<>|bly-}?-ZxN^~9IE-bZD28wks`X}wIN zWc~+-6zoe^QE?tssKmo*uMcK=YPWu^JeM{qW_M3rox(ay1KO|A74u~KdTQxs5hYg9 zTDfh2AO!>uw-wZ62OcTP`w4UcPP+S0^o1J7X)5t^xVXDs)m2ylUVMwt>e*Fzrf;@p z8b{`b8!q8nMsOdA&)B4DqfSsD0E}Rijk&d5t_E zjKa{3I63}i|0GQmtP`;zxa>~6Koeli3@e~uG$gF{K)*#`r2d^gP4s43duo6RL~3uu zbdAE&)?F@#jLt}VgDq*vmo91@-~S;pD%6`J7P_0E>L*CJcG8-*TS>EaE91RbRwx2)BiphFpnTn5e%mAaDF_1cOT^dbnBLhorjPY2ISOzHYwvinA_c^0mF~ zA+}>I!!Kx>EFzVOA30Lo3+?k9tM`7a)i_C!>Zq?hx^C6WNkpn%^7*4X*6ru7j_$p) zdF_5X(>>ZnojZZqg#%qnwUf#A9DAB=`>IYJOFp4X__80^&+yK!c=pTV<-y2@o#Eeb zfzwAn;R{GV8D}CXHBCuII`ku$#AWOkgbJ_Rw$X5=^5Qt)G$bcRw@urJ0U`S~#`yR- z>749#t~VR|fU0Cw!y7Okv&>H{Tbrk%HT6-5vAPTDH0zmvU9iPam$Z}%q<+x>3UvuXu>kR0USjPD`;k~Kh>i+ zd~8X7g)nZ4UiJo)Xl*=5cn_#@JWVd>RC1fkl204hN=@OLT<5Q+3jGnQd4>#{ucT0{ zm>U2EE)>k?aGVmTNUQKu_kAGHS-l<>7WSzyvJXVs=Hz>5c`7|J!nIRo$tMedIkBN> z&ejo|iZEy8gg$?bLV_6@9VIHLrvF+MMg>Artth+@Uxz2z`MgoN`@2VFQ;pWVe7Xv> z;)yxit9sK>@5caNWC?QhSIz2~5MJfQ#7XB^7m{%uBK3C7g{)#W3Lsnlcwuy*4^#E{ zsek`F1||dZb=*8ACX``V_63VKM@f8Mn`S|(5aI)FKw(_e?m!{K`2Hb~hA2CtetDve zjxq`_4d9JofWeAWT1x1-yE+h5wHbU==-h#jJ->kh<_S&*o`1!V;Xf_&{y?S5KFFlu zGRd1qu$=7oY+fD;jRvf$r~}W|X32a=nB`OJzlRN-f8unWr)N;|FQj`zQ40bg3806H z-U>ltXWXY1aRg+4EhBf6!uRyYRc<-~)Q%w#DVm_S$+rb4j6w;Og-d zA%#O98am1-0B3H1y7Y}TfjzM#5b01#6Fx~eq2Y&;8{F1CCg{5OIaJi8ie z9zE4BbpM`wbJ~0OT+2QT4dXA+ojsC;=e1;KWLGf$+DLe!ir)FL9ko-NDHHexSo@CwEbYV6xDAd{25v70b+98cY_V-+7 z=GL?Q*Ks%a{^rK>#Gun3m29=3$iMMbb79}BH%@fydyV-Qd7eHk!CV9gPcvS!iSi*Z z7)ycx$!putHBa8t$T(%Rzv&YmZia_pQ5w$W1v&AR1psKYaU; z(=YFSka<#DTG(r11tfL+KkhjS-B?oK0E92?L%6F>I?5=;2tauXebghPjNo4Jh+W2Vt&|SB0{gw1Y zU-u)xF8IW0GW-bQucs?ZI~|=0SGu`zGU6 z@ezQWZOaV`vM7ikqZcVW2w8Bgx-M0SzpqEy{yz^DXx1qf+!Ve^ClcL^92h-!G;sKY z6K{}~1TOn28LU|tCJv3B7w$fk*DZL6JJ3cT{kRV_$3ABeL2t!TC_%JT7g9a@;foZo zpBJ?2m;0#(`&q8`hdUCFyc*~M1xdNj_sRE}7Ia8FV&-%aaGokKp|>10uR~`o@_X<1 zejQ}>YSg)hOb`;Vt>QwBPpkKdsp5&(hev&&cXzQ9RsDF z2HYaO>jTiie7?$WA<#Gtj`47C=iUft$*F@{?{kQ*u30M!(H({XR*K*u|Eabxtxp?h zZHF|_$M&9q>`J!vZZ|Tu9+dkmtOq*rumh2)+_k4Qm`2zrE$^^|_uk>DQ`x6+&=0`x zm@Fu{Kfn>LOe2i{KHy!_D53s7fO-2Cz-Pp83sEC?B=T6?6HWZKvfhG!X(FBIPUllw3ov-SOWl4?R+ zgb*J^IdmXQ%=a<(Hg|PHVNl?Xv^r^9OZMD6f``|AL7+dn!uU}chc0|K4RNVJ2q;hH zspMI}Q9%(#yTl_eNzT$)n=jo<6~(JYX+fR69xMBzoX_O6Pkirs^nnc1??{A^wi6@^ zu|FY@ZoE3Obu-GLaT&fRtW zu{-5qN%&Lz>3kIlYRjo?LlvBv>}Ega+|)xo^x*5SYB~jk2zB9JZ*pcR=Xk+9l6ZJwa>J@iE;OMuLIWMUh@3q=AMyE-y&>Q7Y{3^ z=PJHyd^_mvEw|3P-wdNm1Alt&P*Na813aVpw`Un($0UFc({!i5CG?kX{vPh}+mc=Q z&Rf>>1;0UFxc4huO2fY;F2~Spd>AuOT>ljwuIN`qJ>cE#H!ij9sR*^TV#_s1FPg?W zJ;u|g_x2j3sAQvu`~^C53{)x#fh0WVnqA(rKkqzqEF?Wi?)|QhqnRc`m(>p7 zHjlOQGDITg-kLJ^foQ4?EB}}hc6i9AHP4s_iKr+Vs2MnUQF4$F7Ks7i-Y6RV2A76_ z)?h5pZ{J+wP@$C*`cw?;0tld#=bstTRk!1MSQAr#m0zzQAp!CD&C2jfuUzeoR*!Yy zpgzBX-YMaY#91YJ$j_~l(Wq65}0@ zh>e*v+D*Tx;q(aU_wwek&9G#!e2eyv!Pl=3WW_QTD9`TfTbH{$ zK2@zjmpvz7RJHDYM%C&~cz<OmM}J!&w`5E^wZYJx2n90R~K()eC&+( zTVkqJ=uOF_06>f1y8LP2w0dQ+&TI~`i99jBDFh*iSwSa4aL))i{6cuL;cy6JQ;o(toEZh)( zXG8v_VdB$BySPO618HvJ17ob}fk3C}qJW9TmBEKkDHkk?_pz`bio<{NdsBeF}Q)bW|kV_F}`eJ{C&@nqWDE|+zMOp!d>04(80)Dz?=o|Q0)i2 zu3-A;$)bd1cdjTNqmoPId2@0qeTmVaPPwrY2$g0+LM)m_#fwWocOdieR;yWHt?t39 z&fWK&Zz`QWr6RJHq%qw#>t>p^S*V0DAM=Z*#!L0WaGqFadZnS0~ zlQD7%X)ODaY2hwM4$a^~Rre?z1n#cORnqB=8R{iW{H#=oz4dQBTdhhSdkw?M2NJuc zW5==aKcb}T_Iz4=k(n7A966HY3d?rE%8QEKE>)#i+eGb^XC~f?kp-F2Y|Jru2W&>I z4qi;eK>5wKT-z;rI8~^GE1h^+Fm*e)!dx$WN4d}W&9E-KwPRN6noXGv&i;n`KXfGz z=p|JZrDLuSA}Wk03|Ks>^x+@6UJmuYO8qcLkME95!#u9~U7(wh9|iH&AD4S?S%hf=}JEJj^koC16swXfORuKy$x46fBxx68FzcPzHDweH9eobBU$-WE3KdM#jW9Vfr4l&2a=`&rHXJRK!K2YJf5!mS2ai4EP$m#)h zZgA%{0wtwIc{8K&9inUBgYt-U`u#1=C)*1H_59vN6Mt}fK@Bmta>C3*=%8{ep-v^1 zx>FO^sl1gR8)Esd(C<_%!+UfeCvyW_n;n^m#M~fN_WIenP+Up=<$H5uP)xJVns|aa z8ioH`mL32GkYKUFIVIq!^!`I5`WyrUQq%Mb-L&o7K%`#1tLl}TqCZ8Q)Vzbzh;;xq zx#O^Tfj0%>W5o&NWNw}jV-(qM8wb&zGc z7>)@ewuaU%O}#304~5CzDqwNu-wet{NCJxk20N@#W78bIqbJ8bO+DLkrRlc}*%-5^u*&#mNCSB5q_mJ-mTHPVVSTOH&K|1SceVXbIuZZch9gxuOtmwam$Z(Gv1cw#CSTugI#X)YdpEMmJ z+~AjE$mK;0=|@g=|&!albMhOvftThJCHy4 zx_1t<&r!4mH`M$!HH9rBk(+$8QewiMh5awUSqKIIxAJiVmOFn&SF#X&`J{mB!K-R? zfrE|i{8D%o!<-l!RYqa_KT}P!5m0kxyubtJh1wHp)5Dud9EJnK| z0$OMM%W-=V#zxXY|fFy1ah z=cp!&Zk6_z9YyQ>Xxl_`?I1Kx!^{LiW=?NsW)U_xIBG&P{h6X0KOl|t){FME5aNDPx0;jelDF15DQeDs%; z0uSp1ji4)t3fEd=|0Sl_u}oR=UMqBXvU~r1w$T)PhVp2C&vEjoCxREtiFoPZX{rWi zC(xWA*qeLX>6LXGt<@{>Ng1NG4c8Ac<+m!OO(~i{rC5H)C1OFRo4vI8^QmkNh2nGV z^YddzuWhz|@Ca{a6kTQTyKg1Ut@-f6TgbhgA83PN#=Da}MB@wxoA!K#ZA#ZOn?E4c z@hC2}3AP%Iw}dybmuJm`-F3_bmZ|Y=-K~ukK0d;fn6Dozd9kcjju@^2mj2e2b385> zJ0IZ|uH2!X6k7KbDDZ}riyM8n_PKDK$*?cK1Ebn>fCf#p|6U5EJu%V?IxFo1>b!10 zK2z*Q8suAlNaf>y!QV94-#FpwEP0lVcr2hGP@(2F$Sf2(_HmJ_ma#7AB(2bDo+%<~ zOWrL`e%bDL$`RLE%E@y;_cY<#FN-J=6XOhoRr`@~8nQ-QBD=BrkBO35>ZuIjO;+jY zAAN$Mv=eFdbfm5y)Y8r@$YM^~GsKFecAurKW_n!j^JBFPiIcXN|1a; zTWO_Q!o+Ps4ZAG8vaw#OcT7lzHaD5|5xKpWF_(z0eDj^^+mIXhXu|h!t>v5^D=iiG zfy4+^xxPWkcCKlT4>ElN&53eh&v9kBWa7*nm-skXDH~IG1n{sS4z-#<$GZ$xL^@fX zY{g#z53oQpF;DVj_5A>I#UR`Wd1}f9r;(ox!y(5JQI?~lJd+$Sx&4(nw6tH|6wX#`yL}a~W0YB^ z2%c}C1kbPAUvj>OTl!0McO;d8P3KLn=|+7jG%T4sc-J1m(vW%Q)2P*=#j~B@{V?~O z;u)Y2{4$@b?|Z5|+dxRvqx~CE+52O&5hWvrWtY5%37FlF)ZUM=DFKfv%=CY~!OFvu z_#&OZEe~AwUNBi`MaEuFD{vw;-sR<9PIlKCcJQl`z3};Hod)yw%^vF{7`Hm~f);L+TPpOw`sKvrs2NZWM|+CO zbAqkm(=UGxXN%!AydQb4YC+iLbLk1ehPIp71jqsE3m*zL+}=b5Rl8)@{`t#Y&ClKI z18e6k1dIITRH$ia5?RSMXZV;R@&BH?FpmQSHTA0XmMnj{im)W^+!!0#$_^!W65$ml2UjjLTLm@7>LqmxuuMuEB~zyl1ME zawb$j?<(SiM;8|>rv*__JZwCnib+>6030hJ$i~#gj*ij$k@caPGp&5z4RDX+vo(H* z0R6!+E<5P}Fq{ExMi08`VO+hbh7$86HI4-{tXEw6z)9H$!3{XWFHz@MAc6I3!J17!!1vzgu6%CZpdLI@>4w4oaS zGSPhk2uhvkCvdfZigGh~g$BX5J0fp*vBI~+fRi~gblw&J5jNo2mz(D6^eSZ+56^fG-yxAzbTS&}G;ayC{0s?O(B%YOUA!yT zO49?xIV!-Dr;fg)+YR#sWmF%bKm#p$r}M%SGb4>=={#)09DR@ZR)NRP!G-u$vAZ{r z?ZjJMbUjE4Jxsv5`^l* z{UKlq$h4c75Bg-sCOuC=9mB{hyj4UJ^`>wJ5H(R|e@9fL1-t?^gZV4H3nNkvDUm4I zd#U75d0JI<4CwUol~JrV@d!BcOzQQ~d|lpv_ZP69-*HwOZT9 z(5#fG)=|n(uP^%5@zax`;Bx`+x#{`XyJiZE2BE%70_t_RlKRi=y4YRSPP_LeQUN{Z4zg

V(l@_v=z5gx_eG%13 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 + + .. image:: ../../images/ccheart_black.png + :width: 108pt + +.. only:: builder_html + + .. container:: ebook-download + + .. raw:: html + + + Download PDF + + + + Download EPUB + + +.. only:: builder_latex or builder_epub + + .. raw:: latex + + \clearpage + +.. rubric:: **About the Authors** + +Jean-Louis Boulanger + +Since the late 1990s Jean-Louis Boulanger has been an independent +safety assessor for the CERTIFER certification authority in France, +for safety-critical software in railway systems. He is an experienced +safety expert in both the railway industries with the CENELEC standard +and the automotive domain with ISO 26262. He has published a number of +books on the industrial use of formal methods, as well as a book on +safety for hardware architectures and a recent book on the application +of the CENELEC |en-50128| and IEC 62279 standards. He has also served +as a professor and researcher at the University of Technology of +Compiègne. + +Quentin Ochem + +Quentin Ochem is the Chief Product and Revenue Officer at AdaCore, +where he oversees marketing, sales, and product management while +steering the company's strategic initiatives. He joined AdaCore in +2005 to work on the company's Integrated Development Environments and +cross-language bindings. With an extensive background in software +engineering in high-integrity domains such as avionics and defense, he +has served leading roles in technical sales, customer training, and +product development. Notably, he has conducted training on the Ada +language, AdaCore tools, and the |do-178b| and |do-178c| software +certification standards. In 2021 he stepped into his current role, +directing the company's strategic initiatives. + +.. rubric:: **Foreword** + +The guidance in the CENELEC standard |en-50128|:2011 helps achieve +confidence that railway control and protection software meets its +safety requirements. Certifying compliance with this standard is a +challenging task, especially for the testing and verification +activities, but appropriate usage of qualified tools and specialized +run-time libraries can significantly simplify the effort. This +document explains how a number of technologies offered by AdaCore +|mdash| tools, libraries, and supplemental services |mdash| can help. +The content is based on the authors' many years of practical +experience with the certification of railway software and with the Ada +and SPARK programming languages. + +| Jean-Louis Boulanger +| October 2015 + +| Quentin Ochem, AdaCore +| October 2015 + +.. rubric:: Foreword to V2.1 + +In the years since the initial version of this document was published, +the |en-50128|:2011 standard has been amended twice, and AdaCore's products +have evolved to meet the growing demands for, and challenges to, high +assurance in mission-critical real-time software. This revised edition +reflects the current (2025) versions of |en-50128| and AdaCore's offerings. +Among other updates and enhancements to the company's products, the static +analysis tools supplementing the |gnatpro| development environment have been +integrated into a cohesive toolset (the *GNAT Static Analysis Suite*). +The dynamic analysis tools have likewise been consolidated, and the resulting +*GNAT Dynamic Analysis Suite* has introduced a fuzzing tool |mdash| *GNATfuzz* +|mdash| which exercises the software with invalid input and checks for +failsafe behavior. + +As editor of this revised edition, I would like to thank Vasiliy Fofanov +(AdaCore) for his detailed and helpful review and suggestions. + +For up-to-date information on AdaCore support for developers of rail +software, please visit :cite:`AdaCore_Web_Rail`. + +| Ben Brosgol, AdaCore +| September 2025 + +.. toctree:: + :maxdepth: 4 + :numbered: + + Introduction + CENELEC EN 50128 + Tools and Technologies Overview + AdaCore Contributions to The Software Quality Assurance Plan + Technology Usage Guide + Technology Annex + Bibliography diff --git a/content/booklets/adacore-technologies-for-railway-software/references.bib b/content/booklets/adacore-technologies-for-railway-software/references.bib new file mode 100644 index 000000000..1fbb9faa9 --- /dev/null +++ b/content/booklets/adacore-technologies-for-railway-software/references.bib @@ -0,0 +1,243 @@ +.. Bibliography + +@manual{AdaCore_2016, + organization = {AdaCore}, + title = {{High-Integrity Object-Oriented Programming in Ada, Version 1.4}}, + year = {2016}, + month = oct, + url = {https://www.adacore.com/knowledge/technical-papers/high-integrity-oop-in-ada/} +} + +@online{AdaCore_AdaLearn, + author = {AdaCore}, + title = {{Online training for Ada and SPARK}}, + url = {https://learn.adacore.com/} +} + +@manual{AdaCore_Altran_2020, + organization = {AdaCore and Altran}, + title = {{SPARK Reference Manual, Release 2020}}, + year = {2020}, + url = {https://www.adacore.com/uploads/techPapers/spark_rm_community_2020.pdf} +} + +@manual{AdaCore_Coding_Style, + organization = {AdaCore}, + title = {{GNAT Coding Style: A Guide for GNAT Developers}}, + year = {2025}, + url = {https://gcc.gnu.org/onlinedocs/gnat-style.pdf} +} + +@online{AdaCore_Web_GNATformat, + author = {AdaCore}, + title = {{GNATformat Documentation}}, + url = {https://docs.adacore.com/live/wave/gnatformat/html/user-guide/} +} + +@online{AdaCore_Web_GPR, + author = {AdaCore}, + title = {{GPRbuild and GPR Companion Tools User's Guide}}, + url = {https://docs.adacore.com/gprbuild-docs/html/gprbuild_ug.html} +} + +@online{AdaCore_Web_Rail, + author = {AdaCore}, + title = {{AdaCore + Rail}}, + url = {https://www.adacore.com/industries/rail} +} + +@online{AdaCore_Web_UG_Cross, + author = {AdaCore}, + title = {{GNAT User's Guide Supplement for Cross Platforms}}, + url = {https://docs.adacore.com/live/wave/gnat_ugx/html/gnat_ugx/gnat_ugx.html} +} + +@online{AdaCore_Web_UG_Native, + author = {AdaCore}, + title = {{GNAT User's Guide for Native Platforms}}, + url = {https://docs.adacore.com/live/wave/gnat_ugn/html/gnat_ugn/gnat_ugn.html} +} + +@book{Barnes_2014, + author = {John Barnes}, + title = {{Programming in Ada 2012}}, + publisher = {Cambridge University Press}, + year = 2014 +} + +@manual{Barnes_Brosgol_2015, + author = {John Barnes and Ben Brosgol}, + title = {{Safe and Secure Software, an invitation to Ada 2012}}, + year = {2015}, + url = {https://www.adacore.com/books/safe-and-secure-software} +} + +@book{Boulanger_2015, + author = {Jean-Louis Boulanger}, + title = {{CENELEC 50128 and IEC 62279 standards}}, + publisher = {ISTE-Wiley}, + address = {London}, + year = {2015}, + url = {https://onlinelibrary.wiley.com/doi/book/10.1002/9781119005056} +} + +@inproceedings{Boulanger_Schön_2007, + author = {Jean-Louis Boulanger and Walter Schön}, + title = {{Assessment of Safety Railway Application}}, + booktitle = {{ESREL 2007 ‐ the 18th European Safety and + Reliability Conference}}, + year = {2007} +} + +@article{Burns_et_al_2004, + author = {{Alan Burns, Brian Dobbing and Tullio Vardanega}}, + title = {{Guide for the use of the Ada Ravenscar Profile in + high integrity systems}}, + journal = {Ada Letters}, + month = jun, + year = {2004} +} + +@manual{CCDB_2022, + organization = {Common Criteria Development Board}, + title = {{Common Criteria for Information Technology + Security Evaluation (ISO/IEC 15408)}}, + year = {2022}, + url = {https://www.commoncriteriaportal.org/} +} + +@manual{CENELEC_2011, + title = {{EN 50128: Railway applications – Communications, signalling and + processing systems – Software for railway control and + protection systems}}, + organization = {CENELEC}, + year = {2011}, +} + +@manual{CENELEC_2017a, + title = {{EN 50657: Railways applications – Rolling stock applications - + Software on Board Rolling Stock}}, + organization = {CENELEC}, + month = aug, + year = {2017}, +} + +@manual{CENELEC_2017b, + title = {{EN 50126-1: Railway applications - The specification and demonstration + of reliability, availability, maintainability and safety + (RAMS)- Part 1: Generic RAMS process}}, + organization = {CENELEC}, + month = oct, + year = {2017}, +} + +@manual{CENELEC_2017c, + title = {{EN 50126-2: Railway applications - The specification and demonstration + of reliability, availability, maintainability and safety + (RAMS)- Part 2: systems approach to safety}}, + organization = {CENELEC}, + month = oct, + year = {2017}, +} + +@manual{CENELEC_2018, + title = {{EN 50129: Railway applications - Communication, signalling and + processing systems - Safety related electronic systems + for signalling}}, + organization = {CENELEC}, + month = nov, + year = {2018}, +} + +@manual{CENELEC_2020a, + title = {{EN 50128/A1: Railway applications – Communications, signalling and + processing systems – Software for railway control and + protection systems}}, + organization = {CENELEC}, + month = feb, + year = {2020}, +} + +@manual{CENELEC_2020b, + title = {{EN 50128/A2: Railway applications – Communications, signalling and + processing systems – Software for railway control and + protection systems}}, + organization = {CENELEC}, + month = jul, + year = {2020}, +} + +@manual{CENELEC_2023a, + title = {{EN 50657/A1: Railways applications – Rolling stock applications - + Software on Board Rolling Stock}}, + organization = {CENELEC}, + month = nov, + year = {2023}, +} + +@manual{CENELEC_2023b, + title = {{EN 50716: Railway applications – Requirements for software + development}}, + organization = {CENELEC}, + month = nov, + year = {2023}, +} + +@manual{CENELEC_2024, + title = {{EN 50126-1/A1: Railway applications - The specification and demonstration + of reliability, availability, maintainability and safety + (RAMS) - Part 1: Generic RAMS process}}, + organization = {CENELEC}, + year = {2024}, +} + +@techreport{ISO_IEC_1998, + title = {{Working Draft 3.6 - Programming Languages - + Guide for the Use of the Ada Programming Language + in High Integrity Systems}}, + institution = {International Organization for Standardization}, + author = {{ISO/IEC JTC1/SC22}}, + month = aug, + year = {1998}, + type = {{ISO/IEC PDTR}}, + number = 15942, + url = {https://www.open-std.org/JTC1/SC22/WG9/n350.pdf} +} + +@manual{ISO_IEC_2016, + title = {{Ada Reference Manual, Language and Standard Libraries}}, + organization = {International Organization for Standardization}, + author = {{ISO/IEC JTC1/SC22}}, + year = {2016}, + note = {{ISO/IEC 8652:2012(E) with Technical Corrigendum 1}}, + url = {https://www.adacore.com/documentation/ada-2012-reference-manual} +} + +@manual{ISO_IEC_2022, + title = {{Ada Reference Manual, 2022 Edition, Language and Standard Libraries}}, + organization = {International Organization for Standardization}, + author = {{ISO/IEC JTC1/SC22}}, + year = {2022}, + url = {https://www.adacore.com/documentation/ada-2022-reference-manual} +} + +@book{McCormick_Chapin_2015, + author = {John W. McCormick and Peter C. Chapin}, + title = {{Building High Integrity Applications with SPARK}}, + publisher = {Cambridge University Press}, + year = 2015 +} + +@manual{RTCA_EUROCAE_2011a, + title = {{DO-178C/ED-12C: Software Considerations in Airborne Systems and Equipment Certification}}, + organization = {RTCA and EUROCAE}, + month = dec, + year = {2011} +} + +@manual{RTCA_EUROCAE_2011b, + title = {{DO-330/ED-215: Software Tool Qualification Considerations}}, + organization = {RTCA and EUROCAE}, + month = dec, + year = {2011} +} \ No newline at end of file diff --git a/content/global.txt b/content/global.txt index 673de01ef..d3a7e830a 100644 --- a/content/global.txt +++ b/content/global.txt @@ -28,8 +28,10 @@ .. include:: +.. |a-grave| unicode:: U+00E0 .. lower case 'a' with grave accent .. |blankcell| unicode:: U+0020 .. |nbhyphen| unicode:: U+2011 .. non-breaking hyphen +.. |rt-arrow| unicode:: U+2192 .. right-pointing arrow .. |gnata| replace:: ``-gnata`` .. |do-160| replace:: DO |nbhyphen| 160/ED |nbhyphen| 14 .. |do-178| replace:: DO |nbhyphen| 178/ED |nbhyphen| 12 @@ -45,5 +47,23 @@ .. |do-331| replace:: DO |nbhyphen| 331/ED |nbhyphen| 218 .. |do-332| replace:: DO |nbhyphen| 332/ED |nbhyphen| 217 .. |do-333| replace:: DO |nbhyphen| 333/ED |nbhyphen| 216 -.. |gnatsas| replace:: GNAT SAS -.. |gnatdas| replace:: GNAT DAS +.. |gnatsas| replace:: GNAT SAS +.. |gnatdas| replace:: GNAT DAS +.. |gnatpro| replace:: GNAT\ |nbsp|\ Pro + +.. |en-50126| replace:: EN\ |nbsp|\ 50126 +.. |en-50126-1| replace:: EN\ |nbsp|\ 50126\ |nbhyphen|\ 1 +.. |en-50126-2| replace:: EN\ |nbsp|\ 50126\ |nbhyphen|\ 2 +.. |en-50128| replace:: EN\ |nbsp|\ 50128 +.. |en-50128a1| replace:: EN\ |nbsp|\ 50128/A1 +.. |en-50128a2| replace:: EN\ |nbsp|\ 50128/A2 +.. |en-50129| replace:: EN\ |nbsp|\ 50129 +.. |en-50657| replace:: EN\ |nbsp|\ 50657 +.. |en-50716| replace:: EN\ |nbsp|\ 50716 + +.. |sil0| replace:: SIL\ |nbsp|\ 0 +.. |sil1| replace:: SIL\ |nbsp|\ 1 +.. |sil4| replace:: SIL\ |nbsp|\ 4 +.. |ssil0| replace:: SSIL\ |nbsp|\ 0 +.. |ssil4| replace:: SSIL\ |nbsp|\ 4 + diff --git a/content/index.rst b/content/index.rst index 8d2bac841..9b3702fdc 100644 --- a/content/index.rst +++ b/content/index.rst @@ -133,6 +133,7 @@ :caption: AdaCore Technologies Booklets AdaCore Technologies For Airborne Software + AdaCore Technologies For Railway Software .. only:: builder_html From 672e77f4ecdcc3d82d1706afb1e600fdb53f379d Mon Sep 17 00:00:00 2001 From: gusthoff Date: Sat, 8 Nov 2025 03:03:17 +0100 Subject: [PATCH 2/7] Editorial change: remove trailing whitespaces --- .../chapters/cenelec.rst | 36 ++++++++-------- .../chapters/introduction.rst | 42 +++++++++---------- 2 files changed, 39 insertions(+), 39 deletions(-) diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst index 2c50417f8..91bdc67a5 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst @@ -7,7 +7,7 @@ Overview -------- EN 50128 governs software used in railway control and protection applications, -i.e., systems that ensure the safe and efficient movement of trains. +i.e., systems that ensure the safe and efficient movement of trains. Examples include: * *Automatic Train Protection (ATP)*, which ensure automatic braking to avoid @@ -84,7 +84,7 @@ conformance to the standard: requirements has been satisfied to the software safety integrity level defined and therefore the objective of the sub-clause in question has been met.* - + This clause also specifies the role of normative Annex A in the selection of techniques and measures for satisfying the requirements, and the means for verifying compliance (inspection of the required documents, @@ -140,16 +140,16 @@ and technologies: * Software verification (sub-clause 6.2) |mdash| defined in sub-clause 3.1.48 as |sphinx-hack-verification|; * Software validation (sub-clause 6.3) |mdash| defined in sub-clause 3.1.46 - as |sphinx-hack-validation|; -* Software assessment (sub-clause 6.4); -* Software quality assurance (sub-clause 6.5); + as |sphinx-hack-validation|; +* Software assessment (sub-clause 6.4); +* Software quality assurance (sub-clause 6.5); * Modification and change control (sub-clause 6.6); and * Support tools and languages (sub-clause 6.7) |mdash| see - :ref:`Railway_SW_tool-qualification` below. + :ref:`Railway_SW_tool-qualification` below. As shown in :cite:`Boulanger_Schön_2007`, for software applications the assessment process involves demonstrating that the software application -achieves its associated safety objectives. +achieves its associated safety objectives. |en-50128| makes a clear separation between the application software, referred to as the *generic software* (Clause 7), @@ -173,7 +173,7 @@ Clause 7, *Generic software development*, has the following sub-clauses: Clause 8, *Development of application data or algorithms: systems configured by application data or algorithms*, ensures that the configuration parameters are verified and validated with the same degree of assurance, based on the -relevant SIL, as is needed for the generic software that they configure. +relevant SIL, as is needed for the generic software that they configure. .. index:: single: EN 50128; Clause 9 (Software deployment and maintenance) @@ -199,12 +199,12 @@ contains a set of tables that correlate the artifacts and practices (documentation, techniques, and measures) specified elsewhere in the standard, with an indication of whether, and how strongly, they are recommended based on the software's SIL: - + * **M**: Mandatory. Must be used * **HR**: Highly Recommended. If not used, need to explain rationale for using alternative technique * **R**: Recommended -* **--**: No recommendation either for or against usage +* **--**: No recommendation either for or against usage * **NR**: Not recommended. If used, need to explain rationale for decision Annex A consists of two sub-clauses: @@ -223,7 +223,7 @@ Annex A consists of two sub-clauses: - Table A.9 |ndash| Software Quality Assurance (6.5) - Table A.10 |ndash| Software Maintenance (9.2) - Table A.11 |ndash| Data Preparation Techniques (8.4) - + * *Detailed tables (A.2)*; these are lower-level tables that expand on certain entries in the Clauses tables: @@ -245,10 +245,10 @@ selection: .. csv-table:: :widths: 30 15 15 10 10 10 10 - + **Technique/Measure**, **Ref**, **Basic Integrity**, **SIL 1**, **SIL 2**, **SIL 3**, **SIL 4** "...", "...", "...", "...", "...", "...", "..." - "10 Programming Language", "Table A.15", "R", "HR", "HR","HR","HR" + "10 Programming Language", "Table A.15", "R", "HR", "HR","HR","HR" "...", "...", "...", "...", "...", "...", "..." Table A.15 contains a row for Ada: @@ -257,7 +257,7 @@ Table A.15 contains a row for Ada: :widths: 30 15 15 10 10 10 10 **Technique/Measure**, **Ref**, **Basic Integrity**, **SIL 1**, **SIL 2**, **SIL 3**, **SIL 4** - "ADA", "D.54", "R", "HR", "HR","HR","HR" + "ADA", "D.54", "R", "HR", "HR","HR","HR" "...", "...", "...", "...", "...", "...", "..." @@ -311,8 +311,8 @@ These are applicable at various lifecycle phases; for example: (sub-clause D.35) at the design and implementation phase, * Formal Methods and Formal Proof (sub-clauses D.28 and D.29) at the - implementation and verification phases, and - + implementation and verification phases, and + * Equivalence Classes and Input Partition Testing (sub-clause D.18) at the testing phase. @@ -348,7 +348,7 @@ Tool classes Tool qualification is based on the recognition that different tools need different levels of confidence in their reliability, based on how a -tool error affects the application software. This is formalized in the +tool error affects the application software. This is formalized in the concept of a "tool class". As stated in sub-clause 6.7.1: *The objective is to provide evidence that potential failures of tools @@ -386,7 +386,7 @@ standard by also specifying the lifecycle phase that is relevant for each sub-clause. The steps shown indicate the requirements to be met and reflect the additional effort needed as the tool level increases; for further information, please see -:cite:`Boulanger_2015`, Chapter 9. +:cite:`Boulanger_2015`, Chapter 9. .. .. figure:: ../images/table1.png diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst index 99bee30e1..0d4e9c544 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst @@ -13,7 +13,7 @@ and also a normative process based on certification standards. In Europe, these standards are issued and maintained by CENELEC (European Committee for Electrotechnical Standardization). This document explains the usage of AdaCore's technologies in conjunction -with |en-50128|:2011 :cite:`CENELEC_2011` |mdash| +with |en-50128|:2011 :cite:`CENELEC_2011` |mdash| *Railway applications - Communication, signalling and processing systems - Software for railway control and protection systems* |mdash| as modified by amendments @@ -22,29 +22,29 @@ as modified by amendments by the A1 and A2 amendments, will simply be referred to as |en-50128|.) |EN-50128| is concerned with the safety-related aspects of a railway -system, down to the hardware and/or software elements used. +system, down to the hardware and/or software elements used. This document will cover where AdaCore's technologies fit best and how they can best be applied to meet various requirements in this standard. |en-50128| is based on fundamentals described in other CENELEC railway -standards: +standards: .. index:: EN 50126 -* |en-50126|-1 :cite:`CENELEC_2017b` |mdash| +* |en-50126|-1 :cite:`CENELEC_2017b` |mdash| *Railway applications - The specification and demonstration of reliability, availability, maintainability and safety (RAMS) - Part 1: Generic RAMS process* (subsequently modified by |en-50126|-1/A1 :cite:`CENELEC_2024`) -* |en-50126|-2 :cite:`CENELEC_2017c` |mdash| +* |en-50126|-2 :cite:`CENELEC_2017c` |mdash| *Railway applications - The specification and demonstration of reliability, availability, maintainability and safety (RAMS): Part 2: systems approach to safety* .. index:: EN 50129 -* |en-50129| :cite:`CENELEC_2018` |mdash| - *Railway applications - Communication, signalling and processing systems - +* |en-50129| :cite:`CENELEC_2018` |mdash| + *Railway applications - Communication, signalling and processing systems - Safety related electronic systems for signalling* As noted in |en-50128|, page 7: @@ -75,7 +75,7 @@ relate to software's role in the safety of a railway system: .. index:: EN 50716 -* |en-50716|:2023 :cite:`CENELEC_2023b` |mdash| +* |en-50716|:2023 :cite:`CENELEC_2023b` |mdash| *Railway Applications - Requirements for software development* This standard is a successor to |en-50128| and |en-50657|, @@ -105,7 +105,7 @@ most critical; i.e., with the highest risk of a hazard in case of software failure. |en-50128| defines the techniques/measures that need to be used -at various software life cycle stages, based on the applicable SIL. +at various software life cycle stages, based on the applicable SIL. AdaCore technologies for railway software ----------------------------------------- @@ -115,26 +115,26 @@ AdaCore technologies for railway software AdaCore's technologies revolve around programming activities, as well as the closely related design and verification activities. This is the bottom of the "V" cycle as defined in |en-50128|, sub-clause 5.3, Figure 4 -(see :numref:`Railway_SW_fig2` below). +(see :numref:`Railway_SW_fig2` below). The company's tools exploit the features of the Ada language (highly recommended by table A.15) and its formally verifiable SPARK subset. In particular, the 2012 version of the Ada standard includes some significant -capabilities in terms of specification and verification. +capabilities in terms of specification and verification. AdaCore's technologies bring two main benefits to the software life cycle processes defined by the CENELEC railway standards. * *Expressing software interface specifications and software component specifications directly in the source code.* - + Interfaces can be precisely expressed through standard syntax for features - such as strong typing, parameter constraints, and subprogram contracts. + such as strong typing, parameter constraints, and subprogram contracts. These help to clarify interface documentation, to enforce program constraints and invariants, and to provide an extensive foundation for - software component and integration verification. + software component and integration verification. * *Reducing the verification costs.* - + Bringing additional specification at the language level allows verification activities to run earlier in the software life cycle, during the software component implementation itself. Tools provided by AdaCore support this @@ -156,16 +156,16 @@ requirements. At the highest level (|sil4|) the SPARK language verification toolsuite enable mathematical proof of properties including correct information flow, absence of run-time exceptions, and, for the most critical code, correctness of the implementation against a formally -defined specification. +defined specification. -The following technologies will be presented: +The following technologies will be presented: .. index:: Ada language * *Ada*, a compilable programming language supporting imperative, object-oriented, and functional programming styles and offering strong specification and verification features. Unless otherwise indicated, - "Ada" denotes the 2012 version of the Ada language standard. + "Ada" denotes the 2012 version of the Ada language standard. .. index:: SPARK technology @@ -176,14 +176,14 @@ The following technologies will be presented: * *GNAT Pro Assurance*, a specialized edition of AdaCore's GNAT Pro language development environments that is oriented towards projects with - long maintenance cycles or certification requirements + long maintenance cycles or certification requirements .. index:: GNAT Static Analysis Suite (GNAT SAS) .. index:: single: GNAT Static Analysis Suite (GNAT SAS); Defects and vulnerability analysis .. index:: GNATmetric .. index:: single: GNAT Static Analysis Suite (GNAT SAS); GNATmetric .. index:: GNATcheck -.. index:: single: GNAT Static Analysis Suite (GNAT SAS); GNATcheck +.. index:: single: GNAT Static Analysis Suite (GNAT SAS); GNATcheck * The *GNAT Static Analysis Suite* ("GNAT SAS"), comprising several tools: @@ -228,7 +228,7 @@ The following technologies will be presented: .. index:: single: Integrated Development Environments (IDEs); GNATbench .. index:: GNATdashboard IDE .. index:: single: Integrated Development Environments (IDEs); GNATdashboard - + * Several *Integrated Development Environments* (IDEs): - GNAT Studio |mdash| a robust, flexible, and extensible IDE From 90de919ee88e3081d7f04da089a639311cf470ea Mon Sep 17 00:00:00 2001 From: gusthoff Date: Sat, 8 Nov 2025 03:04:00 +0100 Subject: [PATCH 3/7] Editorial change: fix image references (`refnum`) --- .../chapters/cenelec.rst | 2 ++ .../chapters/introduction.rst | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst index 91bdc67a5..0ba323862 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst @@ -70,6 +70,8 @@ sub-sections within a chapter are sub-clauses). .. figure:: ../images/fig-3.png :align: center + Structure of CENELEC EN 50128 + Clauses 1, 2, and 3 |mdash| *Scope*, *Normative references*, and *Terms, definitions and abbreviations*, respectively |mdash| provide context and basic information. diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst index 0d4e9c544..1c743f8d7 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst @@ -89,6 +89,8 @@ relate to software's role in the safety of a railway system: .. figure:: ../images/fig-1.png :align: center + Relationships among the various standards + .. index:: Safety Integrity Level (SIL) Safety Integrity Levels @@ -239,3 +241,5 @@ The following technologies will be presented: .. _Railway_SW_fig2: .. figure:: ../images/fig-2.png :align: center + + Contributions of AdaCore technology to the "V" Cycle From a8fccd260dc61577cf326944f34a414bb1028195 Mon Sep 17 00:00:00 2001 From: gusthoff Date: Sat, 8 Nov 2025 04:25:15 +0100 Subject: [PATCH 4/7] Editorial change: remove trailing whitespaces --- .../chapters/contribution.rst | 48 +-- .../chapters/technology.rst | 362 +++++++++--------- .../chapters/tools.rst | 120 +++--- 3 files changed, 265 insertions(+), 265 deletions(-) diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/contribution.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/contribution.rst index 213ed2381..1efe6d99d 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/contribution.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/contribution.rst @@ -36,7 +36,7 @@ guidance on how that can be done. \begin{landscape} -.. csv-table:: +.. csv-table:: :file: table4-1.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -46,7 +46,7 @@ guidance on how that can be done. Table A.4 |ndash| Software Design and Implementation (7.4) ---------------------------------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-2.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -56,7 +56,7 @@ Table A.4 |ndash| Software Design and Implementation (7.4) Table A.5 |ndash| Verification and Testing (6.2 and 7.3) -------------------------------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-3.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -66,7 +66,7 @@ Table A.5 |ndash| Verification and Testing (6.2 and 7.3) Table A.6 |ndash| Integration (7.6) ----------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-4.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -76,7 +76,7 @@ Table A.6 |ndash| Integration (7.6) Table A.7 |ndash| Overall Software Testing (6.2 and 7.7) -------------------------------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-5.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -86,7 +86,7 @@ Table A.7 |ndash| Overall Software Testing (6.2 and 7.7) Table A.8 |ndash| Software Analysis Techniques (6.3) ---------------------------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-6.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -97,11 +97,11 @@ Table A.9 |ndash| Software Quality Assurance (6.5) -------------------------------------------------- Although AdaCore doesn't directly provide services for ISO 9001 -or configuration management, it follows standards to enable -tool qualification and/or certification. The following table -only lists items that can be useful to third parties. +or configuration management, it follows standards to enable +tool qualification and/or certification. The following table +only lists items that can be useful to third parties. -.. csv-table:: +.. csv-table:: :file: table4-7.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -111,7 +111,7 @@ only lists items that can be useful to third parties. Table A.10 |ndash| Software Maintenance (9.2) --------------------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-8.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -121,7 +121,7 @@ Table A.10 |ndash| Software Maintenance (9.2) Table A.11 |ndash| Data Preparation Techniques (8.4) ---------------------------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-9.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -135,9 +135,9 @@ There are available references for coding standards. Their verification can be automated through different ways: the GNAT compiler can define base coding standard rules to be checked at compile time, and GNATcheck implements a wider range of rules and is tailorable to support -project-specific coding standards. +project-specific coding standards. -.. csv-table:: +.. csv-table:: :file: table4-10.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -147,7 +147,7 @@ project-specific coding standards. Table A.13 |ndash| Dynamic Analysis and Testing ----------------------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-11.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -160,7 +160,7 @@ Table A.14 |ndash| Functional/Black Box Test GNATtest can generate and execute a testing framework, with the actual tests being written by developers from requirements. -.. csv-table:: +.. csv-table:: :file: table4-12.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -170,7 +170,7 @@ with the actual tests being written by developers from requirements. Table A.15 |ndash| Textual Programming Language ----------------------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-13.csv :widths: 30 20 20 20 70 :header-rows: 1 @@ -180,7 +180,7 @@ Table A.15 |ndash| Textual Programming Language Table A.17 |ndash| Modeling ---------------------------- -.. csv-table:: +.. csv-table:: :file: table4-14.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -190,7 +190,7 @@ Table A.17 |ndash| Modeling Table A.18 |ndash| Performance Testing -------------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-15.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -200,7 +200,7 @@ Table A.18 |ndash| Performance Testing Table A.19 |ndash| Static Analysis ---------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-16.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -210,7 +210,7 @@ Table A.19 |ndash| Static Analysis Table A.20 |ndash| Components ----------------------------- -.. csv-table:: +.. csv-table:: :file: table4-17.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -220,7 +220,7 @@ Table A.20 |ndash| Components Table A.21 |ndash| Test Coverage for Code ----------------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-18.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -230,7 +230,7 @@ Table A.21 |ndash| Test Coverage for Code Table A.22 |ndash| Object Oriented Software Architecture -------------------------------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-19.csv :widths: 28 13 17 22 10 70 :header-rows: 1 @@ -240,7 +240,7 @@ Table A.22 |ndash| Object Oriented Software Architecture Table A.23 |ndash| Object Oriented Detailed Design -------------------------------------------------- -.. csv-table:: +.. csv-table:: :file: table4-20.csv :widths: 28 13 17 22 10 70 :header-rows: 1 diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/technology.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/technology.rst index 66b02d6ca..efa5ba18f 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/technology.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/technology.rst @@ -4,7 +4,7 @@ Technology Usage Guide ====================== This chapter explains how AdaCore's tools and technologies support a variety -of techniques from Annex D. +of techniques from Annex D. .. _Railway_SW_Analyzable_Programs: @@ -15,19 +15,19 @@ Analyzable Programs (D.2) ------------------------- The Ada language has been designed to increase program specification -expressiveness and verification. Explicit constraints at the code level +expressiveness and verification. Explicit constraints at the code level can be used as the basis of both manual analysis (inspection), such as code reviews, and automatic analysis, ranging from the compiler's semantic consistency checks to the SPARK tools' formal proof of -program properties. +program properties. Examples of Ada language features supporting analysis include: - + * type and subtype ranges and predicates * parameter modes and subprogram contracts * packages and private types (encapsulation) * the Ravenscar concurrency profile -* minimal set of implicit or undefined behaviors +* minimal set of implicit or undefined behaviors .. index:: single: GNATmetric; Support for Analyzable Programs (D.2) .. index:: single: GNATcheck; Support for Analyzable Programs (D.2) @@ -39,11 +39,11 @@ cyclomatic complexity computation, and coupling analysis. .. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Analyzable Programs (D.2) -GNAT SAS identifies potential run-time errors in the code. The number of -false positive results depends on the code complexity. A high number of +GNAT SAS identifies potential run-time errors in the code. The number of +false positive results depends on the code complexity. A high number of false positives is often a symptom of overly-complicated code. Using GNAT SAS during development allows finding locations in the code that are -overly complex and provides information on what needs to be improved. +overly complex and provides information on what needs to be improved. .. index:: single: SPARK technology; Support for Analyzable Programs (D.2) @@ -54,47 +54,47 @@ It structurally forbids features such as exceptions, which complicate or prevent formal analysis. Code that is hard to analyze is often hard to understand and maintain, and conversely. -Using SPARK as part of the development phase thus results in code that is +Using SPARK as part of the development phase thus results in code that is not only maximally analyzable but also clear and readable. .. index:: single: GNAT Studio IDE; Support for Analyzable Programs (D.2) During code review phases, GNAT Studio offers a variety of features that can be used for program analysis, in particular call graphs, reference searches, -and other code organization viewers. +and other code organization viewers. .. index:: single: Annex D; Boundary Value Analysis (D.4) Boundary Value Analysis (D.4) ----------------------------- -The objective of this technique is to verify and test the behavior of a +The objective of this technique is to verify and test the behavior of a subprogram at the limits and boundaries values of its parameters. AdaCore's technologies can provide complementary assurance on the quality of this analysis and potentially decrease the number of tests that need -to be performed. +to be performed. .. index:: single: Ada language; Support for Boundary Value Analysis (D.4) Ada's strong typing allows refining types and variables boundaries. -For example: +For example: .. code-block:: ada type Temperature is new Float range -273.15 .. 1_000; - V : Temperature; + V : Temperature; Additionally, it's possible to define the specific behavior of values at various locations in the code. For example, it's possible to define relationships between the input and output of a subprogram, in the form -of a partitioning of the input domain: +of a partitioning of the input domain: .. code-block:: ada function Compute (J : Integer) return Integer - with Contract_Cases => (J = Integer'First => Compute'Result = -1, + with Contract_Cases => (J = Integer'First => Compute'Result = -1, J = Integer'Last => Compute'Result = 1, - others => J - 1); + others => J - 1); The above shows an input partition of one parameter (but it can also be a combination of several parameters). The behavior on the boundaries of :ada:`J` @@ -105,19 +105,19 @@ partitioning can be found in the context of .. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Boundary Value Analysis (D.4) -Another possibility is to use GNAT SAS to identify possible values for -variables, and propagate those values from call to call, constructing +Another possibility is to use GNAT SAS to identify possible values for +variables, and propagate those values from call to call, constructing lists and/or ranges of potential values for each variable at each point of the program. These are used as the input to run-time error analysis. When used in full-soundness mode, GNAT SAS provides guarantees that the locations it reports on the code are the only ones that may have run-time errors, thus allowing a reduction of the scope of testing and review to -only these places. +only these places. However, it's important to stress that GNAT SAS is only performing this boundary value analysis with respect to potential exceptions and robustness. No information is provided regarding the correctness of the values -produced by subprograms. +produced by subprograms. GNAT SAS also has the capacity to display the possible values of variables and parameters. This can be used as a mechanism to increase confidence @@ -131,7 +131,7 @@ SPARK has the ability to perform similar absence of run-time errors (AORTE) analysis, thus reaching the same objectives. In addition to the above, when requirements can be described in the form of boolean contracts, SPARK can demonstrate correctness of the relation between input and output -on the entire range of values. +on the entire range of values. .. index:: single: Annex D; Control Flow Analysis (D.8) .. index:: single: GNAT Studio IDE; Support for Control Flow Analysis (D.8) @@ -141,10 +141,10 @@ Control Flow Analysis (D.8) Control flow analysis requires identifying poor and incorrect data structures, including unreachable code and useless tests in the code (such as conditions -that are always true). +that are always true). GNAT Studio can display call graphs between subprograms, allowing -visualization and analysis of control flow in the application. +visualization and analysis of control flow in the application. .. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Control Flow Analysis (D.8) @@ -152,7 +152,7 @@ GNAT SAS contributes to control flow analysis by identifying unreachable code, as well as conditions being always true or always false. This analysis is partial and needs to be completed with other techniques such as code review or code coverage analysis, which together will allow reaching higher levels of -confidence. +confidence. .. index:: single: GNATmetric; Support for Control Flow Analysis (D.8) @@ -163,7 +163,7 @@ loosely or tightly coupled units. GNATstack computes worst-case stack consumption based on the application's call graph. This can help identify poorly structured code which consumes -too much memory on some sequences of calls. +too much memory on some sequences of calls. .. index:: single: Annex D; Data Flow Analysis (D.10) @@ -177,7 +177,7 @@ at run-time through the use of the pragma :ada:`Initialize_Scalars`. With this pragma, all scalars are automatically initialized to either an out-of-range value (if there is one) or to an "unusual" value (either the largest or smallest). -This significantly improves detection at test time. +This significantly improves detection at test time. .. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Data Flow Analysis (D.10) @@ -187,49 +187,49 @@ flows, such as variables that are read before they are written read (redundant assignments), and variables that are written but never read. This analysis is partial and needs to be completed with other techniques such as formal proof, code review or code coverage analysis, which together -allow reaching higher levels of confidence. +allow reaching higher levels of confidence. .. index:: single: SPARK technology; Support for Data Flow Analysis (D.10) SPARK performs this analysis and much more, allowing the specification -and verification of data flow. This is used in the following activities: +and verification of data flow. This is used in the following activities: * verification that all inputs and outputs have been specified, including possible side effects * verification that all dependencies between inputs and outputs are specified -* verification that the implemented dataflow corresponds to the one specified +* verification that the implemented dataflow corresponds to the one specified -Here's an example: +Here's an example: .. code-block:: ada procedure Compute (A, B, C : Integer; R1, R2 : out Integer) - with Depends => (R1 => (A, B), - R2 => (B, C)); + with Depends => (R1 => (A, B), + R2 => (B, C)); procedure Compute (A, B, C : Integer; R1, R2 : out Integer) is - begin - R1 := A + B; + begin + R1 := A + B; R2 := A + B - C; - end Compute; + end Compute; :ada:`R1` is required to be computed from :ada:`A` and :ada:`B`, and :ada:`R2` from :ada:`B` and :ada:`C`. However, in the procedure body, :ada:`R2` also -depends on :ada:`A`. SPARK's formal proof detects this error. +depends on :ada:`A`. SPARK's formal proof detects this error. -The error is likewise detected in the presence of branches: +The error is likewise detected in the presence of branches: .. code-block:: ada procedure Compute (A, B, C : Integer; R1, R2 : out Integer) is - begin + begin R1 := A + B; if A = 0 then - R2 := B + C; - else + R2 := B + C; + else R2 := B - C; - end if; - end Compute; + end if; + end Compute; Here :ada:`R2` depends on the result of the expression :ada:`A = 0`, so its value is actually computed from @@ -244,34 +244,34 @@ Here's an example based on a logging procedure that has a global state, .. code-block:: ada procedure Log (V : String) - with Global => (Output => Screen), + with Global => (Output => Screen), Depends => (Screen => V) procedure Compute (A, B, C : Integer; R1, R2 : out Integer) - with Depends => (R1 => (A, B), - R2 => (B, C)); + with Depends => (R1 => (A, B), + R2 => (B, C)); procedure Compute (A, B, C : Integer; R1, R2 : out Integer) is - begin + begin R1 := A + B; R2 := B + C; if A = 0 then - Log ("A is 0"); + Log ("A is 0"); end if; - end Compute; + end Compute; The data flow does not correspond to the specification: :ada:`Compute` should specify that it modifies :ada:`Screen`. So the incorrect code is detected. The error is detected whether or not a branch is present, serving as a useful -complement to structural code coverage in many cases. +complement to structural code coverage in many cases. .. index:: single: Annex D; Defensive Programming (D.14) Defensive Programming (D.14) ---------------------------- -As stated in sub-clause D.14, the goal of defensive programming is to +As stated in sub-clause D.14, the goal of defensive programming is to "detect anomalous control flow, data flow, or data values ... \ and react to them in a predetermined and acceptable manner". @@ -285,17 +285,17 @@ specification, through preconditions, postconditions or predicates. Beyond this, Ada provides specific support for a subset of what's specified in the D.14 annex. GNAT SAS and SPARK will allow the development of defensive -programming in places where it makes the most sense. +programming in places where it makes the most sense. .. index:: single: GNATcheck; Support for Defensive Programming (D.14) Specific defensive code rules can also be defined in the coding standard and their verification can then be automated through code analysis using, -for example, GNATcheck. +for example, GNATcheck. .. index:: Range checking -Data should be range checked +Data should be range checked ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Ada offers types and subtypes that are naturally associated with ranges, e.g.: @@ -304,41 +304,41 @@ Ada offers types and subtypes that are naturally associated with ranges, e.g.: subtype Percent is Integer range 0 .. 100; -- Percent is the same type as Integer but with a run-time constraint on its range - + X, Y : Integer; V : Percent; ... - V := X + Y; -- Raises exception Constraint_Error if X + Y is not in 0 .. 100 + V := X + Y; -- Raises exception Constraint_Error if X + Y is not in 0 .. 100 ... -It's then the task of the developer to react to potential exceptions. +It's then the task of the developer to react to potential exceptions. Alternatively, it's possible to write explicit verification in the code to -ensure that the expression is within its boundary: +ensure that the expression is within its boundary: .. code-block:: ada V_Int : Integer; V_Pct : Percent; - ... + ... V_Int := X+Y; if V_Int in Percent then V_Pct := V_Int; else ... -- Respond to out-of-range result - end if; + end if; .. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Defensive Programming (D.14) .. index:: single: SPARK technology; Support for Defensive Programming (D.14) Another way to proactively ensure the absence of range check failure is to use tools such as GNAT SAS or SPARK, which statically identify the -only possible locations in the code where such failures can happen. +only possible locations in the code where such failures can happen. Note that run-time checks can be deactivated if needed for performance reasons, for example once thorough testing or formal proof has been -performed. +performed. -Data should be dimension-checked +Data should be dimension-checked ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: single: GNAT Pro Assurance; Support for Defensive Programming (D.14) @@ -352,23 +352,23 @@ candela), and will check that operations between these types are consistent. For example, a type :ada:`Speed` can be defined to represent time per distance. Consistency between these types is checked at compile time -so that dimension errors will be reported as errors. For example: +so that dimension errors will be reported as errors. For example: .. code-block:: ada D : Distance := 10; T : Time := 1; - S : Speed := D / T; -- OK + S : Speed := D / T; -- OK My_Time : Time := 100; ... Distance_Traveled := S / My_Time; -- Error, resulting dimension is Distance / Time**2 - -- The expression should be S * My_Time + -- The expression should be S * My_Time .. index:: single: Ada language; Support for Defensive Programming (D.14) .. index:: single: Ada language; Parameter checking -Read-only and read-write parameters should be separated and their access checked +Read-only and read-write parameters should be separated and their access checked ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In Ada, the parameter mode is specified in parameter specifications and @@ -377,18 +377,18 @@ mode :ada:`in` and may not be modified. A read-write parameter is passed either as mode :ada:`in out` or as mode :ada:`out` and is modifiable. (The :ada:`out` mode is appropriate if the parameter is written before being read). The compiler will produce an error for -an attempted modification of :ada:`in` parameters and detect when an +an attempted modification of :ada:`in` parameters and detect when an :ada:`in out` or :ada:`out` parameter is not modified and so could have been -passed as :ada:`in`. For example: +passed as :ada:`in`. For example: .. code-block:: ada procedure P (V : in Integer) is begin V := 5; -- ERROR, V is mode "in" - end P; + end P; -Functions should treat all parameters as read-only +Functions should treat all parameters as read-only -------------------------------------------------- The original version of Ada required that functions could only have :ada:`in` @@ -396,7 +396,7 @@ parameters. This restriction was relaxed in a later version of the standard, but the original behavior can be reverted through a GNATcheck rule. The SPARK Ada subset forbids functions with writable (i.e., :ada:`out` or -:ada:`in out` parameters). +:ada:`in out` parameters). Literals and constants should not be write-accessible ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -408,7 +408,7 @@ but ensures that their values can not be updated. .. code-block:: ada type Color is (Red, Blue, Green); - Answer : constant Integer := 42; + Answer : constant Integer := 42; One_Third : constant := 1.0 / 3.0; Greeting : String := "Hello"; @@ -421,28 +421,28 @@ the literal :ada:`"Hello"` is immutable. .. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Defensive Programming (D.14) .. index:: single: SPARK technology; Support for Defensive Programming (D.14) -Using GNAT SAS and SPARK to drive defensive programming +Using GNAT SAS and SPARK to drive defensive programming ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GNAT SAS and SPARK identify locations where there are potential run-time errors |mdash| in other words, places where code is either wrong or where defensive programming should be deployed. This helps guide the writing -of defensive code. For example: +of defensive code. For example: .. code-block:: ada procedure P (S : String; V : Integer) is C : Character; - begin - ... + begin + ... C := S (V); - ... - end P; + ... + end P; In the above code, there's a use of :ada:`V` as an index into the String :ada:`S`. GNAT SAS and SPARK will detect the potential for a run-time error. Protection -of the code to prevent the error can take several forms: +of the code to prevent the error can take several forms: .. rubric:: Explicit test @@ -454,14 +454,14 @@ recovery action can be taken (here the procedure simply returns). procedure P (S : String; V : Integer) is C : Character; - begin + begin ... if V not in S'Range then - return; - end if; + return; + end if; C := S (V) - ... - end P; + ... + end P; .. rubric:: Precondition @@ -471,21 +471,21 @@ is raised. .. code-block:: ada - procedure P (S : String; V : Integer) + procedure P (S : String; V : Integer) with Pre => V in S'Range - is + is C : Character; - begin - ... + begin + ... C := S (V); - ... - end P; + ... + end P; The main difference between GNAT SAS and SPARK is that GNAT SAS may miss some potential run-time errors (except when run only on small pieces of code if configured in "sound" mode), while SPARK requires the use of the appropriate Ada subset but is a sound technology (i.e., it will detect all potential -run-time errors). +run-time errors). In general, the recommended Ada style is to use contracts instead of defensive code. @@ -511,13 +511,13 @@ Equivalence Classes and Input Partition Testing (D.18) This technique involves partitioning the various potential inputs to subprograms and creating a testing and verification strategy based on -this partitioning. +this partitioning. Ada extensions included in GNAT Pro for Ada can support partitioning at the source code level. The partition is a list of conditions for inputs together with their associated expected output, verifying the following criteria: -* The full set of all potential values is covered +* The full set of all potential values is covered * There is no overlap between partitions These criteria can be verified either dynamically, by verifying at @@ -532,11 +532,11 @@ Here's a simple example of such partitioning with two input variables: .. code-block:: ada function ArcTan (X, Y : Float) return Float with - Contract_Cases => + Contract_Cases => (X >= 0 and Y >= 0 => ArcTan'Result >= 0 and ArcTan'Result <= PI/2, X < 0 and Y >= 0 => ArcTan'Result >= PI/2 and ArcTan'Result <= PI, X < 0 and Y < 0 => ArcTan'Result >= PI and ArcTan'Result <= 3 * PI/2, - X >= 0 and Y < 0 => ArcTan'Result >= 3 * PI/2 and ArcTan'Result <= 2 * PI); + X >= 0 and Y < 0 => ArcTan'Result >= 3 * PI/2 and ArcTan'Result <= 2 * PI); The presence of these contracts enable further verification. At run time, they act as assertions and allow verification that the form of the output @@ -552,7 +552,7 @@ Error Guessing (D.20) The GNATfuzz tool for fuzz testing (part of the GNAT Dynamic Analysis Suite) supports the Error Guessing technique and can provide evidence for a system's -robustness. +robustness. GNATfuzz exercises a program with a large number of automatically generated test values, often random or malformed, and checks for crashes, hangs, and other anomalous behavior. @@ -569,48 +569,48 @@ in the code, either through pragmas or aspects. * Pragma :ada:`Assert` - This pragma allows verification within a sequence of statements: + This pragma allows verification within a sequence of statements: .. code-block:: ada A := B + C; pragma Assert (A /= 0); - D := X / A; + D := X / A; * Pre- and postcondition contracts - Pre- and postconditions can be defined as subprogram aspects: + Pre- and postconditions can be defined as subprogram aspects: .. code-block:: ada procedure Double (X : in out Integer) - with Pre => X < 100, + with Pre => X < 100, Post => X = X'Old * 2; * Predicates and invariants - Predicate and invariant contracts can be defined on types: + Predicate and invariant contracts can be defined on types: .. code-block:: ada type Even is new Integer - with Dynamic_Predicate => Even mod 2 = 0; + with Dynamic_Predicate => Even mod 2 = 0; These contracts can be checked dynamically, for example, during testing. -The developer has fine control over which contracts can be removed +The developer has fine control over which contracts can be removed (e.g. for improved performance) and which should remain in the deployed software. .. index:: single: SPARK technology; Support for Failure Assertion Programming (D.24) -The contracts can be used by the static analysis and formal proof tools. +The contracts can be used by the static analysis and formal proof tools. GNAT SAS uses contracts to refine its analysis and exploits them as assertions, even if it may not be able to demonstrate that they are correct. In this manner, contracts provide the tool with additional information on the code behavior. SPARK can go further and either prove their correctness, or else report its inability to do so. (In the latter case, the issue is either that the contract or the code is incorrect, or that -the proof engine is not powerful enough to construct a proof.) +the proof engine is not powerful enough to construct a proof.) .. index:: single: Annex D; Formal Methods (D.28) .. index:: single: SPARK technology; Support for Formal Methods (D.28) @@ -620,58 +620,58 @@ Formal Methods (D.28) With SPARK, formal methods are used to define and check certain architectural properties, in particular for data coupling specification and verification. -For example: +For example: .. code-block:: ada - G : Integer; + G : Integer; procedure P (X, Y : Integer) with Global => (Output => G), - Depends => (G => (X, Y)); + Depends => (G => (X, Y)); In the above example, the side effect of the subprogram is fully defined: :ada:`P` is modifying :ada:`G`. SPARK will check that this side effect, and no other, is present. :ada:`G` is specified as depending on the values of :ada:`X` and :ada:`Y`. Again, SPARK will analyze the code to check that -the variable relationships specified are correct. +the variable relationships specified are correct. In this example, an actual variable is used to define data flow. It's also possible to create an "abstract" state, implemented by a set of variables. Generally speaking, although these notations and verifications are quite useful on the lower levels of the architecture, they may not be that pertinent at higher levels. SPARK is flexible with regard to where -this should be checked or and where it should not. +this should be checked or and where it should not. At the lower level of the design phases, some properties and requirements can be refined or specified in the form of boolean expressions. SPARK will allow expressing these properties, including the formalism of first-order logic (quantifiers). These properties can be expressed in the form of subprogram preconditions, postconditions, type invariants and type -predicates. For example: +predicates. For example: .. code-block:: ada -- P must have an input greater or equal to 10, and then has to modify V. procedure P (V : in out Integer) - with Pre => V >= 10, + with Pre => V >= 10, Post => V'Old /= V; -- Variables of type Even must be even type Even is new Integer with Dynamic_Predicate => Even mod 2 = 0; - + -- Arrays of this type are always sorted in ascending order type Sorted_Array is array (Integer range <>) of Integer - with Dynamic_Predicate => + with Dynamic_Predicate => Sorted_Array'Size <= 1 or else - (for all I in Sorted_Array'First .. Sorted_Array'Last - 1 => + (for all I in Sorted_Array'First .. Sorted_Array'Last - 1 => Sorted_Array (I) <= Sorted_Array (I + 1)); These properties can be formally verified through the SPARK toolset, using state of the art theorem proving methodologies. Testing aimed at verifying the correctness of these properties can then be simplified, if not entirely -removed. +removed. .. index:: single: Annex D; Impact Analysis (D.32) .. index:: single: GNAT Static Analysis Suite (GNAT SAS); Support for Impact Analysis (D.32) @@ -685,7 +685,7 @@ the combination of various techniques, including reviews, testing and static analysis. GNAT SAS has specific features to identify the impact of a change from the perspective of potential run-time errors. It can establish a baseline with regard to potential failure analysis and filter only the potential -defects that have been introduced or repaired following a change in the code. +defects that have been introduced or repaired following a change in the code. .. index:: single: GNAT Studio IDE; Support for Impact Analysis (D.32) @@ -758,31 +758,31 @@ Here is an example: .. code-block:: ada package Counters is - type Counter is private; + type Counter is private; -- We don't want to give access to the representation of the counter here - procedure Increment (C : in out Counter); + procedure Increment (C : in out Counter); procedure Print (C : in out Counter); - private + private type Counter is new Integer; -- Here, Counter is an Integer, but it could change to something - -- else if needed without disturbing the interface. + -- else if needed without disturbing the interface. end Counters; with Ada.Text_IO; - package body Counters is + package body Counters is procedure Increment (C : in out Counter) is - begin + begin C := C + 1; - end Increment; - + end Increment; + procedure Print (C : in out Counter) is - begin + begin Ada.Text_IO.Put_Line (C'Img); - end Print; - end Counters; + end Print; + end Counters; As a variation on this example, Ada supports encapsulation through "getter" and "setter" subprograms. @@ -796,7 +796,7 @@ accesses through a procedural interface: function Value return Integer; -- "Getter" function procedure Set (New_Value : Integer); -- "Setter" procedure end Data; - + package body Data is Global : Integer := 0; @@ -804,7 +804,7 @@ accesses through a procedural interface: begin return Global; end Value; - + procedure Set (New_Value : Integer) is begin Value := New_Value; @@ -823,7 +823,7 @@ Both of Ada's tasking constructs |mdash| the task and the protected object * A task object or task type specification defines its interface (its entries, which are used for synchronization and communication), and its body defines the implementation. - + * A protected object or protected type specification defines its interface (entries and procedures, which are executed with mutual exclusion), and its body defines the implementation. @@ -844,18 +844,18 @@ For example: .. code-block:: ada type Alert is (Low, Medium, High); - + type Packet is record Flag : Boolean; - Danger : Alert; + Danger : Alert; Data : Interfaces.Unsigned_8; end record; - + Byte : constant := 8; for Alert use (Low => 0, Medium => 5, High => 10); for Alert'Size use 4; - + for Packet use record Flag at 0*Byte range 3 .. 3; -- Bits 1..2 are unused Danger at 0*Byre range 4 .. 7; @@ -871,19 +871,19 @@ Interface Testing (D.34) ------------------------ Ada allows extending the expressiveness of an interface specification -at the code level, allowing constraints such as: +at the code level, allowing constraints such as: * parameter passing modes * pre- and postconditions * input partitioning -* typing +* typing -These are each described in other sections of this document. +These are each described in other sections of this document. These specifications can help the development of tests around the interface, formalize constraints on how the interface is supposed to be used, and activate additional dynamic checking or formal proofs (through SPARK), all ensuring that users are indeed respecting the expectations of the -interface designer. +interface designer. .. index:: single: GNATtest; Support for Interface Testing (D.34) @@ -912,7 +912,7 @@ statement. .. index:: single: Ravenscar Profile; Support for Language Subset (D.35) Going one step further, the language standard has bundled a set of -restrictions into a so-called profile |mdash| the Ravenscar Profile |mdash| +restrictions into a so-called profile |mdash| the Ravenscar Profile |mdash| that supports common concurrency idioms (e.g. periodic and sporadic tasks) and can make a tasking program deterministic and statically analyzable. @@ -920,7 +920,7 @@ and can make a tasking program deterministic and statically analyzable. SPARK is a natural Ada language subset, constraining the language so that programs can be subject to formal analysis (e.g., safe pointers, -no aliasing, and no exceptions). +no aliasing, and no exceptions). .. index:: single: Certifiable profile; Support for Language Subset (D.35) .. index:: single: GNATcheck; Support for Language Subset (D.35) @@ -929,7 +929,7 @@ Other language subsets can be supplied by the implementation, such as the features implemented by the GNAT Pro Certifiable Profiles. And with GNATcheck the user can in effect define a subset in an *à la carte* fashion, to specify prohibited constructs and verify that they are -not present in the code. +not present in the code. .. index:: single: Annex D; Metrics (D.37) .. index:: single: GNATmetric; Support for Metrics (D.37) @@ -939,20 +939,20 @@ Metrics (D.37) The GNATmetric tool reports various metrics on the code, from simple structural metrics such as lines of code or number of entities to more -complex computations such as cyclomatic complexity or coupling. +complex computations such as cyclomatic complexity or coupling. Custom metrics can be computed based on these first-level metrics. In particular, the GNATdashboard environment allows gathering all metrics -into a database that can then accessed through Python or SQL. +into a database that can then accessed through Python or SQL. -These metrics can be viewed through various interfaces. +These metrics can be viewed through various interfaces. .. index:: single: Annex D; Modular Approach (D.38) - + Modular Approach (D.38) ----------------------- -Connections between modules shall be limited and defined, coherence shall be strong +Connections between modules shall be limited and defined, coherence shall be strong ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: Ada language; Support for Modular Approach (D.38) @@ -966,7 +966,7 @@ levels of coupling, through the notions of *child packages* and In addition, the GNAT Pro technology provides the notion of a *project*, which defines a group of packages, possibly with a defined interface. These constructs can be used to define a tool-supported notion of "component" -or "module" at the software level. +or "module" at the software level. .. index:: Ada language; Coupling between modules @@ -986,16 +986,16 @@ There are three main types of dependence between compilation units: access the entities in the private part of :ada:`P`. And the entities declared in the body of :ada:`P` are only accessible in the package body itself. - + * Tight coupling through private child units. - As a generalization of public child units, + As a generalization of public child units, if :ada:`P.Q` is declared as a *private* child, then the visible part of :ada:`P.Q` can also access the entities in the private part of :ada:`P`. This does not compromise encapsulation; the only units that can :ada:`with` a private child are units that otherwise would have access to the entities that the private child can see. - + Ada's expressiveness makes it easier to develop large software systems, with precise control over the coupling between modules, and guaranteeing that data are only accessed by the intended units. @@ -1004,11 +1004,11 @@ A typical example is the implementation of a complex system that needs to be spread across several packages. For example, suppose that packages :ada:`Communication` and :ada:`Interfaces`, contribute to the implementation of a signaling protocol. -In Ada, this design can be implemented in three (or more) distinct files: +In Ada, this design can be implemented in three (or more) distinct files: .. code-block:: ada - package Signaling is ... + package Signaling is ... private package Signaling.Communication is . private package Signaling.Interfaces is ... @@ -1020,22 +1020,22 @@ hierarchy. .. index:: GNATmetric; Metrics on inter-package coupling In addition, tools can provide metrics on coupling between packages. -GNATmetric has built-in support for retrieving these numbers. +GNATmetric has built-in support for retrieving these numbers. .. index:: Project (GNAT Pro); GPR files At a coarser granularity, packages can be grouped together into a GNAT Project file ("GPR"), with a clear interface. -An application architecture can be defined as a combination of project files. +An application architecture can be defined as a combination of project files. -Collections of subprograms shall be built providing several level of modules +Collections of subprograms shall be built providing several level of modules ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Following the above example, it's possible to create public sub-modules as well, creating a hierarchy of services. -Public child units are accessible to client code. +Public child units are accessible to client code. -Subprograms shall have a single entry and single exit only +Subprograms shall have a single entry and single exit only ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: GNATcheck; Support for Modular Approach (D.38) @@ -1043,7 +1043,7 @@ Subprograms shall have a single entry and single exit only The GNATcheck tool has specific rules to verify this property on any Ada code. -Modules shall communicate with other modules via their interface +Modules shall communicate with other modules via their interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: Ada language; Support for Modular Approach (D.38) @@ -1053,9 +1053,9 @@ a package's interface. If a module is implemented using a coarser granularity, e.g. as a group of packages or at project level, then the project file description allows identifying those packages that are part of the interface and those packages -that are not. +that are not. -Module interfaces shall be fully documented +Module interfaces shall be fully documented ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Although this is mostly the responsibility of the developer, @@ -1065,7 +1065,7 @@ checked for consistency by the compiler. This addresses the part of the documentation that can be expressed through boolean properties based on the software-visible entities. -Interfaces shall contain the minimum number of parameters necessary +Interfaces shall contain the minimum number of parameters necessary ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The GNAT Pro compiler will warn about parameters not used by a subprogram @@ -1073,12 +1073,12 @@ implementation. .. index:: GNATcheck; Support for Modular Approach (D.38) -A suitable restriction of parameter number shall be specified, typically 5 +A suitable restriction of parameter number shall be specified, typically 5 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GNATcheck allows specifying a maximum number of parameters per subprogram. -Unit Proof and Unit Test +Unit Proof and Unit Test ~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: GNATtest; Support for Modular Approach (D.38) @@ -1091,14 +1091,14 @@ applications. SPARK performs a modular formal verification: it proves the postcondition of a subprogram according to its own precondition and the precondition and postconditions of its callees, whether or not these callees are -themselves proven. +themselves proven. For a complete proof, all the subprograms of an application need to be formally proven. Where this is not possible, one subset can be proven -and the other can be assumed to be true. +and the other can be assumed to be true. These assumptions can then be verified using traditional testing methodology, -allowing for a hybrid test / proof verification system. +allowing for a hybrid test / proof verification system. .. index:: Ada language; Support for Strongly Typed Programming Languages (D.49) @@ -1106,7 +1106,7 @@ Strongly Typed Programming Languages (D.49) ------------------------------------------- Ada is, from its inception, a strongly typed language, which supports -both static and dynamic verification. +both static and dynamic verification. From a static verification point of view, each type is associated with a representation and a semantic interpretation. Two types with similar @@ -1124,7 +1124,7 @@ the compiler will not allow mixed operations, for example assigning a a :ada:`Kilometers` value and a :ada:`Miles` value, unless explicit conversions are used. Mixing floating point and integer values is similar: the developer is -responsible for deciding where and how conversion should be made. +responsible for deciding where and how conversion should be made. From a dynamic verification point of view, types can be associated with constraints, such as value ranges or arbitrary boolean predicates. @@ -1140,15 +1140,15 @@ the application, allowing the early detection of inconsistencies. Structure Based Testing (D.50) ------------------------------ -AdaCore provides three tools to support structure based testing: +AdaCore provides three tools to support structure based testing: * GNATtest is a unit testing framework generator. It will run on Ada specifications, and generate a skeleton for each subprogram. - The actual test can then be manually written into that skeleton. + The actual test can then be manually written into that skeleton. * GNATemulator allows emulating code for a given target (e.g. PowerPC and Leon) on a host platform such as Windows or Linux. - It's particularly well suited for running unit tests. + It's particularly well suited for running unit tests. * GNATcoverage performs structural coverage analysis from an instrumented platform (GNATemulator or Valgrind on Linux or directly on a board through @@ -1156,7 +1156,7 @@ AdaCore provides three tools to support structure based testing: It supports statement coverage and decision coverage as well as MC/DC. Note that although |en-50128| requires compound condition coverage, Modified Condition/Decision Coverage (MC/DC) is usually accepted as - a means of compliance. + a means of compliance. .. index:: single: Annex D; Structured Programming (D.53) @@ -1178,7 +1178,7 @@ Suitable Programming Languages (D.54) Ada is noted as "Highly Recommended" in the list of programming languages. Some features may, however, not be suitable for the highest SIL. -To enforce the detection and rejection of specific features, the +To enforce the detection and rejection of specific features, the developer can specify a language subset; see :ref:`Railway_SW_Language_Subset`. One of the advantage of the Ada language is that it is precisely defined @@ -1186,7 +1186,7 @@ in a international document, ISO/IEC 8652. This document specifies the required effect as well as any implementation-defined behavior for the core language, the standard Ada libraries (known as the "predefined environment"), and the specialized needs -annexes. +annexes. .. index:: single: Annex D; Object Oriented Programming (D.57) @@ -1201,10 +1201,10 @@ reasons of simplicity and reliability, with multiple inheritance limited to In addition, the :index:`Liskov Substitution Principle` can be verified through class-wide contracts and SPARK formal verification, allowing the verification of class hierarchy consistency and the safety of dispatching -operations. +operations. Ada's OOP model is particularly well suited to safety-critical applications, -as it allows instantiating objects on the stack. For example: +as it allows instantiating objects on the stack. For example: .. code-block:: ada @@ -1213,10 +1213,10 @@ as it allows instantiating objects on the stack. For example: ... type Subclass is new Base_Class with ...; overriding procedure P (X : Subclass); - + B : Base_Class := ... -- on the stack S : Subclass := ... -- on the stack - + X : Some_Type'Class := (if .. then B else S): P (X); -- Dispatches to appropriate version of P @@ -1238,4 +1238,4 @@ Procedural Programming (D.60) Ada implements all the usual features of procedural programming languages, with a general-purpose data type facility and a comprehensive set of control -constructs. +constructs. diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/tools.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/tools.rst index 56b9b7e67..6bf486476 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/tools.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/tools.rst @@ -7,7 +7,7 @@ AdaCore Tools and Technologies Overview .. _Railway_SW_Ada: -Ada +Ada --- .. _Railway_SW_Background: @@ -18,7 +18,7 @@ Background .. index:: Ichbiah (Jean), Taft (Tucker) Ada is a modern programming language designed for large, long-lived -applications |mdash| and embedded systems in particular |mdash| where +applications |mdash| and embedded systems in particular |mdash| where reliability, maintainability, and efficiency are essential. It was originally developed in the early 1980s (this version is generally known as Ada 83) by a team led by Jean Ichbiah at @@ -40,14 +40,14 @@ introduced in Ada 2022 (see :cite:`ISO_IEC_2016`, :cite:`Barnes_Brosgol_2015`, .. index:: Lovelace (Augusta Ada), Babbage (Charles), Byron (Lord George) The name "Ada" is not an acronym; it was chosen in honor of -Augusta Ada Lovelace (1815-1852), a mathematician who is +Augusta Ada Lovelace (1815-1852), a mathematician who is regarded as the world's first programmer because of her work with Charles Babbage. She was also the daughter of the poet Lord Byron. The Ada language is seeing significant usage worldwide in high-integrity / safety-critical / high-security domains including railway systems, commercial and military aircraft avionics, air traffic control, and -medical devices. +medical devices. With its embodiment of modern software engineering principles, Ada is an excellent teaching language for both introductory and advanced @@ -67,7 +67,7 @@ transitioning to Ada 95 from Ada 83 or other languages. .. _Railway_SW_Language_Overview: -Language Overview +Language Overview ~~~~~~~~~~~~~~~~~ Ada is multi-faceted. From one perspective it is a classical stack-based @@ -80,7 +80,7 @@ But it also includes much more: .. index:: single: Ada language; Scalar ranges -Scalar Ranges +Scalar Ranges ^^^^^^^^^^^^^ Unlike languages based on C syntax (such as C++, Java, and C#), Ada allows the @@ -116,13 +116,13 @@ Contract-Based Programming A feature introduced in Ada 2012 allows extending a subprogram specification or a type/subtype declaration with a contract (a Boolean assertion). Subprogram contracts take the form of preconditions and postconditions, -type contracts are used for invariants, and subtype contracts provide +type contracts are used for invariants, and subtype contracts provide generalized constraints (predicates). Through contracts the developer can -formalize the intended behavior of the application, and can +formalize the intended behavior of the application, and can verify this behavior by testing, static analysis or formal proof. Here's a skeletal example that illustrates contact-based programming; a -:ada:`Table` object is a fixed-length container for distinct :ada:`Float` +:ada:`Table` object is a fixed-length container for distinct :ada:`Float` values. .. code-block:: ada @@ -144,7 +144,7 @@ values. private ... -- Full declaration of type Table end Table_Pkg; - + package body Table_Pkg is ... -- Implementation of Insert, Remove, Is_Full, and Contains end Table_Pkg; @@ -152,7 +152,7 @@ values. A compiler option controls whether the pre- and postconditions are checked at run time. If checks are enabled, any pre- or postcondition failure |mdash| i.e., the contract's -Boolean expression evaluating to :ada:`False` |mdash| raises the +Boolean expression evaluating to :ada:`False` |mdash| raises the :ada:`Assertion_Error` exception. .. index:: single: Ada language; Programming in the large @@ -161,9 +161,9 @@ Programming in the large ^^^^^^^^^^^^^^^^^^^^^^^^ The original Ada 83 design introduced the package construct, -a feature that supports encapsulation ("information hiding") and +a feature that supports encapsulation ("information hiding") and modularization, and which allows the developer to control the -namespace that is accessible within a given compilation unit. Ada 95 +namespace that is accessible within a given compilation unit. Ada 95 introduced the concept of "child units," adding considerable flexibility and easing the design of very large systems. Ada 2005 extended the language's modularization facilities by allowing @@ -179,7 +179,7 @@ A key to reusable components is a mechanism for parameterizing modules with respect to data types and other program entities, for example a stack package for an arbitrary element type. Ada meets this requirement through a facility known as "generics"; since the parameterization is done -at compile time, run-time performance is not penalized. +at compile time, run-time performance is not penalized. .. index:: single: Ada language; Object-Oriented Programming (OOP) @@ -232,11 +232,11 @@ multi-core architectures were introduced in Ada 2012. .. index:: single: Ada language; Systems programming -Systems Programming +Systems Programming ^^^^^^^^^^^^^^^^^^^ Both in the "core" language and the Systems Programming Annex, Ada supplies -the necessary features for hardware-specific processing. +the necessary features for hardware-specific processing. For example, the programmer can specify the bit layout for fields in a record, define alignment and size properties, place data at specific machine addresses, and express specialized code sequences in assembly language. @@ -254,7 +254,7 @@ that uses priority ceilings; this has an especially efficient implementation in Ada (mutexes are not required) since protected operations are not allowed to block. Ada 95 defined a task dispatching policy that basically requires tasks to run until blocked or preempted. Subsequent versions of the language -standard introduced several other policies, such as Earliest Deadline First. +standard introduced several other policies, such as Earliest Deadline First. .. index:: single: Ada language; High-integrity systems .. index:: single: Ada language; Prevention of vulnerabilities @@ -284,7 +284,7 @@ memory safety; this is illustrated by a number of features, including: Data intended for one purpose will not be accessed via inappropriate operations; errors such as treating pointers as integers (or vice versa) are prevented. - + * *Array bounds checking* A run-time check guarantees that an array index is within the bounds of @@ -292,13 +292,13 @@ memory safety; this is illustrated by a number of features, including: This prevents buffer overflow vulnerabilities that are common in C and C++. In many cases a a compiler optimization can detect statically that the index is within bounds and thus eliminate any run-time code for the check. - + * *Prevention of null pointer dereferences* As with array bounds, pointer dereferences are checked to make sure that the pointer is not null. Again, such checks can often be optimized out. - + * *Prevention of dangling references* A scope accessibility checks ensures that a pointer cannot reference an @@ -309,16 +309,16 @@ memory safety; this is illustrated by a number of features, including: .. index:: single: Ada language; pragma Restrictions However, the full language may be inappropriate in a safety-critical -application, since the generality and flexibility could interfere +application, since the generality and flexibility could interfere with traceability / certification requirements. Ada addresses this issue by -supplying a compiler directive, :ada:`pragma Restrictions`, that +supplying a compiler directive, :ada:`pragma Restrictions`, that allows constraining the language features to a well-defined subset (for example, excluding dynamic OOP facilities). The evolution of Ada has seen the continued increase in support for -safety-critical and high-security applications. Ada 2005 +safety-critical and high-security applications. Ada 2005 standardized the :index:`Ravenscar Profile`, a collection of concurrency -features that are powerful enough for real-time programming but +features that are powerful enough for real-time programming but simple enough to make certification and formal analysis practical. .. index:: Contract-based programming @@ -326,7 +326,7 @@ simple enough to make certification and formal analysis practical. Ada 2012 introduced contract-based programming facilities, allowing the programmer to specify preconditions and/or postconditions for subprograms, -and invariants for encapsulated (private) types. These can serve both +and invariants for encapsulated (private) types. These can serve both for run-time checking and as input to static analysis tools. The most recent version of the standard, Ada 2022, has added several @@ -341,9 +341,9 @@ Summary ^^^^^^^ In brief, Ada is an internationally standardized language combining -object-oriented programming features, well-engineered concurrency +object-oriented programming features, well-engineered concurrency facilities, real-time support, and built-in reliability through both -compile-time and run-time checks. As such it is an appropriate +compile-time and run-time checks. As such it is an appropriate language for addressing the real issues facing software developers today. Ada has a long and successful history and is used throughout a number of major industries to design software that protects @@ -358,22 +358,22 @@ life and property. .. _Railway_SW_SPARK: -SPARK +SPARK ----- SPARK is a software development technology (programming language and -verification toolset) specifically designed for engineering +verification toolset) specifically designed for engineering ultra-low defect level applications, for example where safety -and/or security are key requirements. SPARK Pro is AdaCore's +and/or security are key requirements. SPARK Pro is AdaCore's commercial-grade offering of the SPARK technology. The main component in the toolset is GNATprove, which performs formal verification on SPARK code. SPARK has an extensive industrial track record. Since its inception -in the late 1980s it has been used worldwide in a range of +in the late 1980s it has been used worldwide in a range of industrial applications such as railway signaling, civil and military -avionics, air traffic management / control, cryptographic -software, and cross-domain solutions. +avionics, air traffic management / control, cryptographic +software, and cross-domain solutions. The SPARK language has been stable over the years, with periodic enhancements. The 2014 version of SPARK represented a major revision @@ -395,7 +395,7 @@ new systems can be built on and reuse legacy codebases. .. index:: single: SPARK language; Formal verification .. index:: single: SPARK technology; Absence of Run-Time Errors (AORTE) -Powerful Static Verification +Powerful Static Verification ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The SPARK language supports a wide range of static verification techniques. @@ -414,7 +414,7 @@ from the absence of run-time errors ("AORTE"), to the enforcement of safety or security properties, to compliance with a formal specification of the program's required behavior. -Ease of Adoption +Ease of Adoption ~~~~~~~~~~~~~~~~ User experience has shown that the language and the SPARK Pro toolset do not @@ -454,7 +454,7 @@ other languages. .. index:: single: SPARK language; Reduced cost of verification -Reduced Cost and Improved Efficiency of Executable Object Code Verification +Reduced Cost and Improved Efficiency of Executable Object Code Verification ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Software verification typically involves extensive testing, including unit @@ -594,14 +594,14 @@ and where the costs of adapting the application without the additional run-time support are considered prohibitive. -Full Implementation of Ada Standards +Full Implementation of Ada Standards ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GNAT Pro provides a complete implementation of the Ada language from Ada 83 to Ada 2012, and support for selected features from Ada 2022. Developers of safety-critical and high-security systems can thus take advantage of features such as contract-based programming, which effectively -embed requirements in the source program text and simplify verification. +embed requirements in the source program text and simplify verification. .. index:: single: GNAT Pro Assurance; Source-to-object traceability @@ -609,14 +609,14 @@ Source to Object Traceability ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A compiler option can limit the use of language constructs that generate -object code that is not directly traceable to the source code. +object code that is not directly traceable to the source code. As an add-on service, AdaCore can perform an analysis that demonstrates this traceability and justifies any remaining cases of non-traceable code. .. index:: single: AdaCore; Support services .. index:: single: AdaCore; Training and consulting services -Safety-Critical Support and Expertise +Safety-Critical Support and Expertise ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ At the heart of every AdaCore subscription are the support services that @@ -669,7 +669,7 @@ Typical libadalang applications include: .. _Railway_SW_GNATstack: -GNATstack +GNATstack ~~~~~~~~~ Included with GNAT Pro is GNATstack, a static analysis tool that enables an @@ -705,7 +705,7 @@ calls, etc.). The user can assist the tool by specifying missing call graph and stack usage information. GNATstack's main output is the worst-case stack usage for every entry point, -together with the paths that result in these stack sizes. +together with the paths that result in these stack sizes. The list of entry points can be automatically computed (all the tasks, including the environment task) or can be specified by the user (a list of entry points or all the subprograms matching a given regular expression). @@ -845,11 +845,11 @@ GNAT Dynamic Analysis Suite (GNAT DAS) .. _Railway_SW_GNATtest: -GNATtest +GNATtest ~~~~~~~~ The GNATtest tool helps create and maintain a complete unit testing -infrastructure for complex projects. It captures +infrastructure for complex projects. It captures the simple idea that each public subprogram (these are known as "visible" subprograms in Ada) should have at least one corresponding unit test. GNATtest takes a project file as input, and produces two outputs: @@ -881,9 +881,9 @@ GNATemulator is an efficient and flexible tool that provides integrated, lightweight target emulation. Based on the QEMU technology, a generic and open-source machine emulator -and virtualizer, GNATemulator allows software developers to +and virtualizer, GNATemulator allows software developers to compile code directly for their target architecture and run it on their -host platform, through an approach that translates from the +host platform, through an approach that translates from the target object code to native instructions on the host. This avoids the inconvenience and cost of managing an actual board, while offering an efficient testing environment compatible with the final hardware. @@ -1027,38 +1027,38 @@ most out of GNAT Pro technology. **Tools** GNAT Studio's extensive navigation and analysis tools can generate a variety -of useful information including call graphs, source dependencies, +of useful information including call graphs, source dependencies, project organization, and complexity metrics, giving a thorough understanding of a program at multiple levels. It allows interfacing with third-party version control systems, easing both development and maintenance. -**Robust, Flexible and Extensible** +**Robust, Flexible and Extensible** Especially suited for large, complex systems, GNAT Studio can import existing -projects from other Ada implementations while adhering to their +projects from other Ada implementations while adhering to their file naming conventions and retaining the existing directory organization. -Through the multi-language capabilities of GNAT Studio, components +Through the multi-language capabilities of GNAT Studio, components written in C and C++ can also be handled. The IDE is highly extensible; -additional tools can be plugged in through a simple scripting +additional tools can be plugged in through a simple scripting approach. It is also tailorable, allowing various aspects of the program's appearance to be customized in the editor. -**Easy to learn, easy to use** +**Easy to learn, easy to use** GNAT Studio is intuitive to new users thanks to its menu-driven interface -with extensive online help (including documentation on all the +with extensive online help (including documentation on all the menu selections) and "tool tips". The Project Wizard makes it simple to get started, supplying default values for almost all of the project properties. For experienced users, it offers the necessary level of control for advanced purposes; e.g., the ability to run command scripts. Anything that -can be done on the command line is achievable through the menu interface. +can be done on the command line is achievable through the menu interface. -**Remote Programming** +**Remote Programming** Integrated into GNAT Studio, Remote Programming provides a secure and -efficient way for programmers to access any number of remote servers +efficient way for programmers to access any number of remote servers on a wide variety of platforms while taking advantage of the power and -familiarity of their local PC workstations. +familiarity of their local PC workstations. .. index:: single: Integrated Development Environments (IDEs); VS Code support .. index:: VS Code support @@ -1084,7 +1084,7 @@ GNAT Studio IDE. Functionality includes: .. index:: Eclipse IDE .. index:: GNATbench IDE -Eclipse Support |ndash| GNATbench +Eclipse Support |ndash| GNATbench ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GNATbench is an Ada development plug-in for Eclipse and Wind River's Workbench @@ -1096,14 +1096,14 @@ cases the Ada tools are tightly integrated. .. index:: single: Integrated Development Environments (IDEs); GNATdashboard .. index:: GNATdashboard IDE -GNATdashboard +GNATdashboard ~~~~~~~~~~~~~ GNATdashboard serves as a one-stop control panel for monitoring and improving the quality of Ada software. It integrates and aggregates the results of AdaCore's various static and dynamic analysis tools (GNATmetric, GNATcheck, GNATcoverage, SPARK Pro, among others) within a common interface, helping -quality assurance managers and project leaders understand or reduce +quality assurance managers and project leaders understand or reduce their software's technical debt, and eliminating the need for manual input. GNATdashboard fits naturally into a continuous integration environment, From 694243a582fb2475c63c65cd56a5245bd461ad8b Mon Sep 17 00:00:00 2001 From: gusthoff Date: Sat, 8 Nov 2025 04:27:13 +0100 Subject: [PATCH 5/7] Editorial fix: remove line in .bib file --- .../adacore-technologies-for-railway-software/references.bib | 2 -- 1 file changed, 2 deletions(-) diff --git a/content/booklets/adacore-technologies-for-railway-software/references.bib b/content/booklets/adacore-technologies-for-railway-software/references.bib index 1fbb9faa9..1e6f35d7f 100644 --- a/content/booklets/adacore-technologies-for-railway-software/references.bib +++ b/content/booklets/adacore-technologies-for-railway-software/references.bib @@ -1,5 +1,3 @@ -.. Bibliography - @manual{AdaCore_2016, organization = {AdaCore}, title = {{High-Integrity Object-Oriented Programming in Ada, Version 1.4}}, From bdf8600611d9fa8a7665179c4fdbb36e1ccbd554 Mon Sep 17 00:00:00 2001 From: gusthoff Date: Sat, 8 Nov 2025 04:29:31 +0100 Subject: [PATCH 6/7] Editorial change: prefix all entries in bibliography Getting rid of bibliography data error in references.bib file: "repeated bibliography entry." --- .../chapters/cenelec.rst | 6 +- .../chapters/introduction.rst | 26 +++---- .../chapters/table4-2.csv | 2 +- .../chapters/technology.rst | 2 +- .../chapters/tools.rst | 26 ++++--- .../index.rst | 2 +- .../references.bib | 74 +++++++++---------- 7 files changed, 70 insertions(+), 68 deletions(-) diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst index 0ba323862..91427cc6d 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst @@ -149,7 +149,7 @@ and technologies: * Support tools and languages (sub-clause 6.7) |mdash| see :ref:`Railway_SW_tool-qualification` below. -As shown in :cite:`Boulanger_Schön_2007`, for software applications the +As shown in :cite:`Railway_SW_Boulanger_Schön_2007`, for software applications the assessment process involves demonstrating that the software application achieves its associated safety objectives. @@ -340,7 +340,7 @@ referred to here as "tool qualification", and provides details on what needs to be performed and/or supplied. (The standard does not use a specific term for this process, but the "tool qualification" terminology from the airborne software standards -|do-178c| :cite:`RTCA_EUROCAE_2011a` and |do-330| :cite:`RTCA_EUROCAE_2011b` +|do-178c| :cite:`Railway_SW_RTCA_EUROCAE_2011a` and |do-330| :cite:`Railway_SW_RTCA_EUROCAE_2011b` is appropriate.) .. index:: Tool classes @@ -388,7 +388,7 @@ standard by also specifying the lifecycle phase that is relevant for each sub-clause. The steps shown indicate the requirements to be met and reflect the additional effort needed as the tool level increases; for further information, please see -:cite:`Boulanger_2015`, Chapter 9. +:cite:`Railway_SW_Boulanger_2015`, Chapter 9. .. .. figure:: ../images/table1.png diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst index 1c743f8d7..f1884529a 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst @@ -13,11 +13,11 @@ and also a normative process based on certification standards. In Europe, these standards are issued and maintained by CENELEC (European Committee for Electrotechnical Standardization). This document explains the usage of AdaCore's technologies in conjunction -with |en-50128|:2011 :cite:`CENELEC_2011` |mdash| +with |en-50128|:2011 :cite:`Railway_SW_CENELEC_2011` |mdash| *Railway applications - Communication, signalling and processing systems - Software for railway control and protection systems* |mdash| as modified by amendments -|en-50128|/A1 :cite:`CENELEC_2020a` and |en-50128|/A2 :cite:`CENELEC_2020b`. +|en-50128|/A1 :cite:`Railway_SW_CENELEC_2020a` and |en-50128|/A2 :cite:`Railway_SW_CENELEC_2020b`. (For ease of exposition, the 2011 edition of the standard, as modified by the A1 and A2 amendments, will simply be referred to as |en-50128|.) @@ -31,19 +31,19 @@ standards: .. index:: EN 50126 -* |en-50126|-1 :cite:`CENELEC_2017b` |mdash| +* |en-50126|-1 :cite:`Railway_SW_CENELEC_2017b` |mdash| *Railway applications - The specification and demonstration of reliability, availability, maintainability and safety (RAMS) - Part 1: Generic RAMS - process* (subsequently modified by |en-50126|-1/A1 :cite:`CENELEC_2024`) + process* (subsequently modified by |en-50126|-1/A1 :cite:`Railway_SW_CENELEC_2024`) -* |en-50126|-2 :cite:`CENELEC_2017c` |mdash| +* |en-50126|-2 :cite:`Railway_SW_CENELEC_2017c` |mdash| *Railway applications - The specification and demonstration of reliability, availability, maintainability and safety (RAMS): Part 2: systems approach to safety* .. index:: EN 50129 -* |en-50129| :cite:`CENELEC_2018` |mdash| +* |en-50129| :cite:`Railway_SW_CENELEC_2018` |mdash| *Railway applications - Communication, signalling and processing systems - Safety related electronic systems for signalling* @@ -61,8 +61,8 @@ relate to software's role in the safety of a railway system: .. index:: EN 50657 -* |en-50657|:2017 :cite:`CENELEC_2017a` as modified by amendment - |en-50657|/A1 :cite:`CENELEC_2023a` |mdash| +* |en-50657|:2017 :cite:`Railway_SW_CENELEC_2017a` as modified by amendment + |en-50657|/A1 :cite:`Railway_SW_CENELEC_2023a` |mdash| *Railways applications - Rolling stock applications - Software on Board Rolling Stock* @@ -75,7 +75,7 @@ relate to software's role in the safety of a railway system: .. index:: EN 50716 -* |en-50716|:2023 :cite:`CENELEC_2023b` |mdash| +* |en-50716|:2023 :cite:`Railway_SW_CENELEC_2023b` |mdash| *Railway Applications - Requirements for software development* This standard is a successor to |en-50128| and |en-50657|, @@ -149,12 +149,12 @@ processes defined by the CENELEC railway standards. AdaCore's technologies can be used at all Safety Integrity Levels, from Basic Integrity to |sil4|. At lower levels, the full Ada language is suitable, independent of platform. At higher levels, specific subsets will be needed, -for example the :index:`Ravenscar Profile` (:cite:`Burns_et_al_2004`, -:cite:`McCormick_Chapin_2015`) for concurrency support with analyzable +for example the :index:`Ravenscar Profile` (:cite:`Railway_SW_Burns_et_al_2004`, +:cite:`Railway_SW_McCormick_Chapin_2015`) for concurrency support with analyzable semantics and a reduced footprint, or the :index:`Light Profile` -:cite:`AdaCore_Web_UG_Cross` for a subset with no run-time library +:cite:`Railway_SW_AdaCore_Web_UG_Cross` for a subset with no run-time library requirements. At the highest level (|sil4|) the SPARK language -(:cite:`McCormick_Chapin_2015`, :cite:`AdaCore_Altran_2020`) and its +(:cite:`Railway_SW_McCormick_Chapin_2015`, :cite:`Railway_SW_AdaCore_Altran_2020`) and its verification toolsuite enable mathematical proof of properties including correct information flow, absence of run-time exceptions, and, for the most critical code, correctness of the implementation against a formally diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-2.csv b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-2.csv index c1b247108..85ddb6f15 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/table4-2.csv +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/table4-2.csv @@ -40,7 +40,7 @@ C or assembly." Language Subset,D.35,|mdash|,HR,Yes,"Ada is designed to support \ subsetting, possibly under the control of specific runtimes, GNATcheck, or \ with SPARK. Another possibility is to follow the recommendations in \ -:cite:`ISO_IEC_1998`." +:cite:`Railway_SW_ISO_IEC_1998`." Object-Oriented Programming,"Table A.22, D.57",R,R,Yes,"If needed, Ada \ supports all the usual paradigms of object-oriented programming, in addition \ to safety-related features such as the :index:`Liskov Substitution Principle`." diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/technology.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/technology.rst index efa5ba18f..68c4ff376 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/technology.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/technology.rst @@ -1226,7 +1226,7 @@ here it will be a value from either :ada:`Base_Class` or :ada:`Subclass`. Storage for :ada:`X` is reserved on the stack, and the invocation :ada:`P (X)` will dispatch to the appropriate version of :ada:`P`. -The booklet :cite:`AdaCore_2016` provides additional information on how to use +The booklet :cite:`Railway_SW_AdaCore_2016` provides additional information on how to use object-oriented features in a certified context. .. index:: single: Annex D; Procedural Programming (D.60) diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/tools.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/tools.rst index 6bf486476..14f4b2446 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/tools.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/tools.rst @@ -34,8 +34,10 @@ Additional features (including support for contract-based programming in the form of subprogram pre- and postconditions and type invariants) were added in the Ada 2012 version of the language standard, and a number of features to increase the language's expressiveness were -introduced in Ada 2022 (see :cite:`ISO_IEC_2016`, :cite:`Barnes_Brosgol_2015`, -:cite:`Barnes_2014`, :cite:`ISO_IEC_2022` for information about Ada). +introduced in Ada 2022 (see :cite:`Railway_SW_ISO_IEC_2016`, +:cite:`Railway_SW_Barnes_Brosgol_2015`, +:cite:`Railway_SW_Barnes_2014`, +:cite:`Railway_SW_ISO_IEC_2022` for information about Ada). .. index:: Lovelace (Augusta Ada), Babbage (Charles), Byron (Lord George) @@ -207,7 +209,7 @@ traditional :ada:`obj.op(...)` operation invocation notation. Ada is methodologically neutral and does not impose a distributed overhead for OOP. If an application does not need OOP, then the OOP features do not have to be used, and there is no run-time penalty. -See :cite:`Barnes_2014` or :cite:`AdaCore_2016` for more details.. +See :cite:`Railway_SW_Barnes_2014` or :cite:`Railway_SW_AdaCore_2016` for more details.. .. index:: single: Ada language; Concurrent programming @@ -274,8 +276,8 @@ High-Integrity Systems With its emphasis on sound software engineering principles, Ada supports the development of high-integrity applications, including those that need to be certified against safety standards such |en-50128| for rail systems, -|do-178c| :cite:`RTCA_EUROCAE_2011a` for avionics, and security standards -such as the Common Criteria :cite:`CCDB_2022`. +|do-178c| :cite:`Railway_SW_RTCA_EUROCAE_2011a` for avionics, and security standards +such as the Common Criteria :cite:`Railway_SW_CCDB_2022`. Key to Ada's support for high-assurance software is the language's memory safety; this is illustrated by a number of features, including: @@ -377,7 +379,7 @@ software, and cross-domain solutions. The SPARK language has been stable over the years, with periodic enhancements. The 2014 version of SPARK represented a major revision -:cite:`McCormick_Chapin_2015`, :cite:`AdaCore_Altran_2020`), +:cite:`Railway_SW_McCormick_Chapin_2015`, :cite:`Railway_SW_AdaCore_Altran_2020`), incorporating contract-based programming syntax from Ada 2012, and subsequent upgrades included support for pointers (access types) based on the Rust ownership model. @@ -419,7 +421,7 @@ Ease of Adoption User experience has shown that the language and the SPARK Pro toolset do not require a steep learning curve. Training material such as AdaCore's online -AdaLearn course for SPARK :cite:`AdaCore_AdaLearn` can quickly bring +AdaLearn course for SPARK :cite:`Railway_SW_AdaCore_AdaLearn` can quickly bring developers up to speed; users are assumed to be experts in their own application domain such as railway software and do not need to be familiar with formal methods or the proof technology implemented by the toolset. @@ -520,10 +522,10 @@ It provides an Integrated Development Environment (see :ref:`Railway_SW_Integrated_Development_Environments`), a comprehensive toolsuite including a visual debugger, and an extensive set of libraries and bindings. Details on the GNAT Pro for Ada toolchain may be found in -:cite:`AdaCore_Web_UG_Native`. +:cite:`Railway_SW_AdaCore_Web_UG_Native`. AdaCore's GNAT project facility, based on a multi-language builder for systems organized into subsystems and libraries, is documented in -:cite:`AdaCore_Web_GPR`. +:cite:`Railway_SW_AdaCore_Web_GPR`. .. index:: single: GNAT Pro Assurance; Configurable Run-Time Libraries @@ -538,7 +540,7 @@ Configurable Run-Time Libraries Two specific GNAT-defined run-time libraries have been designed with certification in mind and are known as the Certifiable Profiles -(see :cite:`AdaCore_Web_UG_Cross`): +(see :cite:`Railway_SW_AdaCore_Web_UG_Cross`): * *Light Profile* @@ -821,9 +823,9 @@ GNATcheck provides: * Style checks that allow developers to control indentation, casing, comment style, and nesting level. -AdaCore's :index:`GNATformat` tool :cite:`AdaCore_Web_GNATformat`, which +AdaCore's :index:`GNATformat` tool :cite:`Railway_SW_AdaCore_Web_GNATformat`, which formats Ada source code according to the GNAT coding style -:cite:`AdaCore_Coding_Style`, can help avoid having code that violates +:cite:`Railway_SW_AdaCore_Coding_Style`, can help avoid having code that violates GNATcheck rules. GNATformat is included in the GNAT Pro for Ada toolchain. GNATcheck comes with a query language (LKQL, for Language Kit Query Language) diff --git a/content/booklets/adacore-technologies-for-railway-software/index.rst b/content/booklets/adacore-technologies-for-railway-software/index.rst index 2f428bb88..ddd1ce229 100644 --- a/content/booklets/adacore-technologies-for-railway-software/index.rst +++ b/content/booklets/adacore-technologies-for-railway-software/index.rst @@ -134,7 +134,7 @@ As editor of this revised edition, I would like to thank Vasiliy Fofanov (AdaCore) for his detailed and helpful review and suggestions. For up-to-date information on AdaCore support for developers of rail -software, please visit :cite:`AdaCore_Web_Rail`. +software, please visit :cite:`Railway_SW_AdaCore_Web_Rail`. | Ben Brosgol, AdaCore | September 2025 diff --git a/content/booklets/adacore-technologies-for-railway-software/references.bib b/content/booklets/adacore-technologies-for-railway-software/references.bib index 1e6f35d7f..129e8cb76 100644 --- a/content/booklets/adacore-technologies-for-railway-software/references.bib +++ b/content/booklets/adacore-technologies-for-railway-software/references.bib @@ -1,4 +1,4 @@ -@manual{AdaCore_2016, +@manual{Railway_SW_AdaCore_2016, organization = {AdaCore}, title = {{High-Integrity Object-Oriented Programming in Ada, Version 1.4}}, year = {2016}, @@ -6,71 +6,71 @@ @manual{AdaCore_2016 url = {https://www.adacore.com/knowledge/technical-papers/high-integrity-oop-in-ada/} } -@online{AdaCore_AdaLearn, +@online{Railway_SW_AdaCore_AdaLearn, author = {AdaCore}, title = {{Online training for Ada and SPARK}}, - url = {https://learn.adacore.com/} + url = {https://learn.adacore.com/} } -@manual{AdaCore_Altran_2020, +@manual{Railway_SW_AdaCore_Altran_2020, organization = {AdaCore and Altran}, title = {{SPARK Reference Manual, Release 2020}}, year = {2020}, url = {https://www.adacore.com/uploads/techPapers/spark_rm_community_2020.pdf} } -@manual{AdaCore_Coding_Style, +@manual{Railway_SW_AdaCore_Coding_Style, organization = {AdaCore}, title = {{GNAT Coding Style: A Guide for GNAT Developers}}, year = {2025}, url = {https://gcc.gnu.org/onlinedocs/gnat-style.pdf} } -@online{AdaCore_Web_GNATformat, +@online{Railway_SW_AdaCore_Web_GNATformat, author = {AdaCore}, title = {{GNATformat Documentation}}, url = {https://docs.adacore.com/live/wave/gnatformat/html/user-guide/} } -@online{AdaCore_Web_GPR, +@online{Railway_SW_AdaCore_Web_GPR, author = {AdaCore}, title = {{GPRbuild and GPR Companion Tools User's Guide}}, url = {https://docs.adacore.com/gprbuild-docs/html/gprbuild_ug.html} } -@online{AdaCore_Web_Rail, +@online{Railway_SW_AdaCore_Web_Rail, author = {AdaCore}, title = {{AdaCore + Rail}}, url = {https://www.adacore.com/industries/rail} } -@online{AdaCore_Web_UG_Cross, +@online{Railway_SW_AdaCore_Web_UG_Cross, author = {AdaCore}, title = {{GNAT User's Guide Supplement for Cross Platforms}}, url = {https://docs.adacore.com/live/wave/gnat_ugx/html/gnat_ugx/gnat_ugx.html} } -@online{AdaCore_Web_UG_Native, +@online{Railway_SW_AdaCore_Web_UG_Native, author = {AdaCore}, title = {{GNAT User's Guide for Native Platforms}}, url = {https://docs.adacore.com/live/wave/gnat_ugn/html/gnat_ugn/gnat_ugn.html} } -@book{Barnes_2014, +@book{Railway_SW_Barnes_2014, author = {John Barnes}, title = {{Programming in Ada 2012}}, publisher = {Cambridge University Press}, year = 2014 } -@manual{Barnes_Brosgol_2015, +@manual{Railway_SW_Barnes_Brosgol_2015, author = {John Barnes and Ben Brosgol}, title = {{Safe and Secure Software, an invitation to Ada 2012}}, year = {2015}, - url = {https://www.adacore.com/books/safe-and-secure-software} + url = {https://www.adacore.com/books/safe-and-secure-software} } -@book{Boulanger_2015, +@book{Railway_SW_Boulanger_2015, author = {Jean-Louis Boulanger}, title = {{CENELEC 50128 and IEC 62279 standards}}, publisher = {ISTE-Wiley}, @@ -79,7 +79,7 @@ @book{Boulanger_2015 url = {https://onlinelibrary.wiley.com/doi/book/10.1002/9781119005056} } -@inproceedings{Boulanger_Schön_2007, +@inproceedings{Railway_SW_Boulanger_Schön_2007, author = {Jean-Louis Boulanger and Walter Schön}, title = {{Assessment of Safety Railway Application}}, booktitle = {{ESREL 2007 ‐ the 18th European Safety and @@ -87,16 +87,16 @@ @inproceedings{Boulanger_Schön_2007 year = {2007} } -@article{Burns_et_al_2004, +@article{Railway_SW_Burns_et_al_2004, author = {{Alan Burns, Brian Dobbing and Tullio Vardanega}}, - title = {{Guide for the use of the Ada Ravenscar Profile in + title = {{Guide for the use of the Ada Ravenscar Profile in high integrity systems}}, journal = {Ada Letters}, month = jun, year = {2004} } -@manual{CCDB_2022, +@manual{Railway_SW_CCDB_2022, organization = {Common Criteria Development Board}, title = {{Common Criteria for Information Technology Security Evaluation (ISO/IEC 15408)}}, @@ -104,7 +104,7 @@ @manual{CCDB_2022 url = {https://www.commoncriteriaportal.org/} } -@manual{CENELEC_2011, +@manual{Railway_SW_CENELEC_2011, title = {{EN 50128: Railway applications – Communications, signalling and processing systems – Software for railway control and protection systems}}, @@ -112,15 +112,15 @@ @manual{CENELEC_2011 year = {2011}, } -@manual{CENELEC_2017a, - title = {{EN 50657: Railways applications – Rolling stock applications - +@manual{Railway_SW_CENELEC_2017a, + title = {{EN 50657: Railways applications – Rolling stock applications - Software on Board Rolling Stock}}, organization = {CENELEC}, month = aug, year = {2017}, } -@manual{CENELEC_2017b, +@manual{Railway_SW_CENELEC_2017b, title = {{EN 50126-1: Railway applications - The specification and demonstration of reliability, availability, maintainability and safety (RAMS)- Part 1: Generic RAMS process}}, @@ -129,7 +129,7 @@ @manual{CENELEC_2017b year = {2017}, } -@manual{CENELEC_2017c, +@manual{Railway_SW_CENELEC_2017c, title = {{EN 50126-2: Railway applications - The specification and demonstration of reliability, availability, maintainability and safety (RAMS)- Part 2: systems approach to safety}}, @@ -138,7 +138,7 @@ @manual{CENELEC_2017c year = {2017}, } -@manual{CENELEC_2018, +@manual{Railway_SW_CENELEC_2018, title = {{EN 50129: Railway applications - Communication, signalling and processing systems - Safety related electronic systems for signalling}}, @@ -147,7 +147,7 @@ @manual{CENELEC_2018 year = {2018}, } -@manual{CENELEC_2020a, +@manual{Railway_SW_CENELEC_2020a, title = {{EN 50128/A1: Railway applications – Communications, signalling and processing systems – Software for railway control and protection systems}}, @@ -156,7 +156,7 @@ @manual{CENELEC_2020a year = {2020}, } -@manual{CENELEC_2020b, +@manual{Railway_SW_CENELEC_2020b, title = {{EN 50128/A2: Railway applications – Communications, signalling and processing systems – Software for railway control and protection systems}}, @@ -165,15 +165,15 @@ @manual{CENELEC_2020b year = {2020}, } -@manual{CENELEC_2023a, - title = {{EN 50657/A1: Railways applications – Rolling stock applications - +@manual{Railway_SW_CENELEC_2023a, + title = {{EN 50657/A1: Railways applications – Rolling stock applications - Software on Board Rolling Stock}}, organization = {CENELEC}, month = nov, year = {2023}, } -@manual{CENELEC_2023b, +@manual{Railway_SW_CENELEC_2023b, title = {{EN 50716: Railway applications – Requirements for software development}}, organization = {CENELEC}, @@ -181,7 +181,7 @@ @manual{CENELEC_2023b year = {2023}, } -@manual{CENELEC_2024, +@manual{Railway_SW_CENELEC_2024, title = {{EN 50126-1/A1: Railway applications - The specification and demonstration of reliability, availability, maintainability and safety (RAMS) - Part 1: Generic RAMS process}}, @@ -189,7 +189,7 @@ @manual{CENELEC_2024 year = {2024}, } -@techreport{ISO_IEC_1998, +@techreport{Railway_SW_ISO_IEC_1998, title = {{Working Draft 3.6 - Programming Languages - Guide for the Use of the Ada Programming Language in High Integrity Systems}}, @@ -202,7 +202,7 @@ @techreport{ISO_IEC_1998 url = {https://www.open-std.org/JTC1/SC22/WG9/n350.pdf} } -@manual{ISO_IEC_2016, +@manual{Railway_SW_ISO_IEC_2016, title = {{Ada Reference Manual, Language and Standard Libraries}}, organization = {International Organization for Standardization}, author = {{ISO/IEC JTC1/SC22}}, @@ -211,7 +211,7 @@ @manual{ISO_IEC_2016 url = {https://www.adacore.com/documentation/ada-2012-reference-manual} } -@manual{ISO_IEC_2022, +@manual{Railway_SW_ISO_IEC_2022, title = {{Ada Reference Manual, 2022 Edition, Language and Standard Libraries}}, organization = {International Organization for Standardization}, author = {{ISO/IEC JTC1/SC22}}, @@ -219,23 +219,23 @@ @manual{ISO_IEC_2022 url = {https://www.adacore.com/documentation/ada-2022-reference-manual} } -@book{McCormick_Chapin_2015, +@book{Railway_SW_McCormick_Chapin_2015, author = {John W. McCormick and Peter C. Chapin}, title = {{Building High Integrity Applications with SPARK}}, publisher = {Cambridge University Press}, year = 2015 } -@manual{RTCA_EUROCAE_2011a, +@manual{Railway_SW_RTCA_EUROCAE_2011a, title = {{DO-178C/ED-12C: Software Considerations in Airborne Systems and Equipment Certification}}, organization = {RTCA and EUROCAE}, month = dec, year = {2011} } -@manual{RTCA_EUROCAE_2011b, +@manual{Railway_SW_RTCA_EUROCAE_2011b, title = {{DO-330/ED-215: Software Tool Qualification Considerations}}, organization = {RTCA and EUROCAE}, month = dec, year = {2011} -} \ No newline at end of file +} From 3879d32d3f6712b2f71f693a5d005ddae5ea455f Mon Sep 17 00:00:00 2001 From: gusthoff Date: Sat, 8 Nov 2025 04:33:27 +0100 Subject: [PATCH 7/7] Editorial change: replace central `bibliography` by `footbibliography` Getting rid of "duplicate citation for key" warning (`bibtex.duplicate_citation`). --- .../chapters/annex.rst | 7 +++++++ .../chapters/bibliography.rst | 8 -------- .../chapters/cenelec.rst | 7 +++++++ .../chapters/contribution.rst | 7 +++++++ .../chapters/introduction.rst | 7 +++++++ .../adacore-technologies-for-railway-software/index.rst | 1 - 6 files changed, 28 insertions(+), 9 deletions(-) delete mode 100644 content/booklets/adacore-technologies-for-railway-software/chapters/bibliography.rst diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/annex.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/annex.rst index 8c7d2d0b3..72743067f 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/annex.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/annex.rst @@ -242,3 +242,10 @@ Annex D References ~~~~~~~~~~~~~~~~~~ * D.50 Structure Based Testing + + +.. only:: builder_html + + .. rubric:: Bibliography + +.. footbibliography:: diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/bibliography.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/bibliography.rst deleted file mode 100644 index 2c8bd2969..000000000 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/bibliography.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. include:: ../../../global.txt - -.. only:: builder_html or builder_epub - - Bibliography - ============ - -.. bibliography:: diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst index 91427cc6d..afaa0dcb3 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/cenelec.rst @@ -455,3 +455,10 @@ have access to: * Qualification material for |en-50128| and/or |do-330| tool assessment; * A formally verifiable language (SPARK) for high-integrity use cases; and * Lifecycle support aligned with the needs of long-term platform deployments + + +.. only:: builder_html + + .. rubric:: Bibliography + +.. footbibliography:: diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/contribution.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/contribution.rst index 1efe6d99d..1b1a537d4 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/contribution.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/contribution.rst @@ -251,3 +251,10 @@ Table A.23 |ndash| Object Oriented Detailed Design .. raw:: latex \end{landscape} + + +.. only:: builder_html + + .. rubric:: Bibliography + +.. footbibliography:: diff --git a/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst b/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst index f1884529a..90019865d 100644 --- a/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst +++ b/content/booklets/adacore-technologies-for-railway-software/chapters/introduction.rst @@ -243,3 +243,10 @@ The following technologies will be presented: :align: center Contributions of AdaCore technology to the "V" Cycle + + +.. only:: builder_html + + .. rubric:: Bibliography + +.. footbibliography:: diff --git a/content/booklets/adacore-technologies-for-railway-software/index.rst b/content/booklets/adacore-technologies-for-railway-software/index.rst index ddd1ce229..045b0237f 100644 --- a/content/booklets/adacore-technologies-for-railway-software/index.rst +++ b/content/booklets/adacore-technologies-for-railway-software/index.rst @@ -149,4 +149,3 @@ software, please visit :cite:`Railway_SW_AdaCore_Web_Rail`. AdaCore Contributions to The Software Quality Assurance Plan Technology Usage Guide Technology Annex - Bibliography