RFC: Transfer google doc safety committee glossary to zephyr /doc/glossary

[romkell]

Introduction

Transfer the safety committee glossary in google doc to the zephyr /doc to have it publicly available.

Problem description

The safety committee glossary shall be publicly available to the safety WG

Proposed change

see introduction

Detailed RFC

Transfer the following safety committee glossary into the Zephyr /doc area.

Terms

• Project timeline:
  The Project timeline for the zephyr safety certification
• Zephyr FSM Plan:
  This Safety Plan / Functional Safety Management Plan contains the planning and mapping of methods and resources of the activities of the Zephyr Safety Lifecycle
• IEC 61508-3 Techniques and Measures:
  The Techniques and Measures document describes what needs to be done to reach a specific SIL from the software point of view. It also contains the decisions of the safety committee which measurements and techniques are implemented or not implemented to achieve the safety certification.
• Zephyr Safety Claims:
  A safety claim is a functionality that is performed in a functional safe way. That means that this function has been analyzed regarding its potential to impair the safety capability of the overall software integrating Zephyr. This safety function is described in the Zephyr Safety Manual regarding its safe usage. Failures caused by this function are handled within Zephyr either by (safety-) monitoring this function or by ensuring the function's systematic capability to reliably work as intended.
• Zephyr Requirements Management Plan:
  Definition of the strategy how to derive and identify (safety) requirements, where and how to document these requirements and how to verify these requirements.
• Zephyr Configuration Management Plan:
  Planning and definition of all items that are in the scope of the Zephyr safety release, how their revisions are managed, file access and editing rights, how baselines and branches are handled and how the valid revision of each work product can be identified. It also defines the valid states of each work product.
• Zephyr Safety Impact Analysis Plan:
  Each change affecting the safety LTS branch of Zephyr needs to be analyzed if and how this change can affect the safety of the product.
• Zephyr Safety Requirements:
  <empty>
• Zephyr LTS Requirements:
  <empty>
• Zephyr Safety Manual:
  The central manual defining and listing all procedures, information and measures the integrator of Zephyr needs to know.
• Zephyr Tool Evaluation:
  In a safety lifecycle the possible malfunctions and their possible impact to the safety of the product need to be analyzed. This Tool Evaluation Sheet documents the analysis of each involved tool.
• Scope document:
  <tbd when finished>
• Software component:
  A software component is a high level description of a software package which encapsulates set of functionality with defined interfaces ( e.g. Kernel, Services, … )
• Software component:
  Software component means a single unit of code ( e.g. source code file, … ) that can work independently, as well as in a team with other components
• Software safety requirement:
  A software safety requirement is a requirement which constrain the software to behave in ways which do not contribute unacceptably to system safety violations within a given context of use ( e.g. stack overflow detection, … ) in other words:
  Safety requirements capture the mechanisms by which you detect and mitigate faults
• Requirement:
  A source type item that contains a single (atomic) requirements statement. Usually configuration managed in the repository along with the source code.
• (SW) Architecture:
  A software architecture describes its components and relations and interactions between them in a software system
• (HW) Architecture:
  <TBD>
• Safety Case:
  Complete set of safety documentation and reports providing all information for the safety certification
• Integrator:
  The person or organization that integrates Zephyr into their product.
• Software Safety Requirements Specification (SRS):
  Defines and describes the software and it requirements from the user perspective. Document that contains a set of (source) requirements that represent the requirements in the safety scope and are subject to safety verification activities.
• Software Test Specification (STS):
  Defines and describes the tests (test sequences) to test the SRS.
  The STS is derived from the SRS
  (linkage: SRS <- tests – STS).
• Software Architecture & Interface Specification (SAIS):
  Defines and describes the software architecture, the interaction of components through their interfaces.
  The SAIS is derived from the SRS
  (linkage: SRS <- refines – SAIS)
• Software Integration Test Specification (SITS):
  Defines and describes the tests (test sequences) to test the SAIS.
  The SITS is derived from the SAIS
  (linkage: SAIS <- tests – SITS).
• Software Component Design Specification (SCDS):
  Defines and describes the software components and its behavior.
  The SCDS is derived from the SAIS
  (linkage: SAIS <- refines – SCDS)
• Software Component Test Specification (SCTS):
  Defines and describes the tests (test sequences) to test the SCDS.
  The SCTS is derived from the SCDS
  (linkage: SCDS <- tests – SCTS).
• Safety Scope:
  A subset of the full Zephyr OS sources (code files)
  being qualified (coded, tested and documented) according to IEC 61508 SIL3
  and marked as such using the “SPDX-FileComment: IEC-61508-SIL3” tag.
  A subset of the full Zephyr OS functionalities
  being qualified (coded, tested and documented) according to IEC-61508-SIL3)
  and being marked in the KConfig “help” definition as “Config in Safety Scope”.

Abbreviations

• FSM: Functional Safety Management
• ZSP: Zephyr Safety (FSM) Plan
• ZVP: Zephyr Verification Plan
• ZDP: Zephyr (safety) Development Plan
• ZSUPP: Zephyr Supporting Process Planning
• ZRP: Zephyr (safety) Release Planning
• SUP: Supporting Processes
• ZTE: Zephyr Tool Evaluation
• CMP: Configuration Management Plan
• LTS: Long Term Support
• FSM: Functional safety manager: Responsible for coordination of the functional safety activities in the development phases of the safety lifecycle
• FSA: Functional safety architect
• SW: Software
• SIL: Safety Integrity Level
• SRS: Software Requirements Specification
• STS: Software Test Specification
• SAIS: Software Architecture & Interface Specification
• SITS: Software Integration Test Specification
• SCDS: Software Component Design Specification
• SCTS: Software Component Test Specification
• FFF: Fake Function Framework (a unit testing framework)

I propose to combine terms, abbreviations and description in on table

Term	Abbreviation	Description
<Term>	<Abbreviation>	<Description>

Proposed change (Detailed)

Transfer the existing google doc safety committee glossary to zephyr /doc/glossary.rst

Dependencies

None.

Concerns and Unresolved Questions

• Is the common glossary the right place?
• If opening a dedicated safety glossary in /doc/safety/glossary.rst, how many other glossaries shall be created and maintained?

Alternatives

• The alternative was present as safety committee private google doc but became unsuitable
• Alternatives as questioned in the "Concerns and Unresolved Questions" can be discussed
• An alternative location, e.g. a public google doc, than the Zephyr /doc area does not make sense, since there is where people go and seek for information.

Links

PRs

The started PRs after questions I consider postponed.

• PR: doc: Add 'Zephyr FSM plan' to glossary #72118
• PR: doc: Add 'project timeline' to glossary #72117

[nashif]

@romkell Such terminology and possible glossary is very specific to the safety section and are not to be confused with general terminology that needs to be part of the overall project glossary. For example the terms interrupt, thread, multi-core etc fall under the general glossary however most of the above should be in a safety specific section.

Also, it makes sense to add only terms that are used in the documentation so we can link back to them and avoid unused terms.

[romkell]

@romkell Such terminology and possible glossary is very specific to the safety section and are not to be confused with general terminology that needs to be part of the overall project glossary. For example the terms interrupt, thread, multi-core etc fall under the general glossary however most of the above should be in a safety specific section.

Also, it makes sense to add only terms that are used in the documentation so we can link back to them and avoid unused terms.

Some are very safety specific, some are requirements management specific.

I guess the task here are:

1. Decide if there shall be different glossaries of just that one
2. define the various topic glossary we want to have

• common
• safety
• (security)
• req-mgmt
• ??

3. define some guideline / criteria where term go in:

• e.g. only the term which are exclusively used by a topic/area and no where else go into the respective glossary,
  All other need to go into common
• I would state that rule in each of the topic glossary at the top

4. For each of the terms above in this issue, decide to still use, where to put, how to describe or drop.
   I guess that works best with a separate PR even though it is more work.
   Handling that in this issue or a common PR will end up in long term mixing comments. Also might different terms go into different glossaries if decide to create several.

[romkell]

"Hi! I am interested in working on this issue. Is anyone already assigned to it, or can I take it up?"

Since I initially create the RFC I answer here as good as I can. The safety chair and architect meanwhile have been newly elected. @simhein resigned and I was not very much involved in the safety anymore due to other prios.

Best join the Safety WG meeting or refer to the new safety architect @tobiaskaestner or the new safety chair Stéphane Parenti.