Safety Stakeholder req and AoU addition

docs/requirements/platform_assumptions/index.rst

@@ -14,10 +14,10 @@
 
 .. _platform_assumptions:
 
-SW Platform Assumptions
+SW-platform Assumptions
 =======================
 
-.. document:: SW Platform Assumptions
+.. document:: SW-platform Assumptions
    :id: doc__platform_assumptions
    :status: draft
    :security: YES
@@ -27,13 +27,13 @@ SW Platform Assumptions
 Assumptions on Environment
 --------------------------
 
-In this section assumptions are described which need to be fulfilled by the architecture level below the SW platform,
+In this section assumptions are described which need to be fulfilled by the architecture level below the SW-platform,
 i.e. by the elements or organizations outside of S-CORE, but used by S-CORE platform components. These include elements like
 the operating system, programming language libraries, hypervisor or processing hardware.
 For "organizations" two roles are used in the AoU text:
 
-- Supplier: is the provider of an element the S-CORE SW platform is using but which is developed and maintained externally.
-- System Integrator: uses the S-CORE SW platform as a part of a system he provides to a customer. The system integrator can be for example a Tier1 providing an electronic control unit to a OEM or an OEM providing a car to his end-customer. S-CORE does not know which.
+- Supplier: is the provider of an element the S-CORE SW-platform is using but which is developed and maintained externally.
+- System Integrator: uses the S-CORE SW-platform as a part of a system he provides to a customer. The system integrator can be for example a Tier1 providing an electronic control unit to a OEM or an OEM providing a car to his end-customer. S-CORE does not know which.
 
 To fulfill these assumptions is the responsibility of the mentioned roles.
 
@@ -83,7 +83,7 @@ Assumptions on the external SW element integration - Functional Level
 ---------------------------------------------------------------------
 
 This is the middle level of integraton, the higher level will build on this.
-It is the level where the S-CORE SW platform will functionally "work" with the external SW element.
+It is the level where the S-CORE SW-platform will functionally "work" with the external SW element.
 
 .. aou_req:: bazel tooling
    :id: aou_req__platform__bazel_tooling
@@ -92,8 +92,8 @@ It is the level where the S-CORE SW platform will functionally "work" with the e
    :safety: QM
    :status: valid
 
-   The supplier shall provide tools for Bazel to be able to build the S-CORE SW platform with the external SW element
-   and support the run and test of the S-CORE SW platform.
+   The supplier shall provide tools for Bazel to be able to build the S-CORE SW-platform with the external SW element
+   and support the run and test of the S-CORE SW-platform.
 
 .. aou_req:: bug fixing
    :id: aou_req__platform__bug_fixing
@@ -106,7 +106,7 @@ It is the level where the S-CORE SW platform will functionally "work" with the e
 
    Note: For OSS community providing an external SW element this requirement could be covered by analyzing how bugs were treated in the past. For companies by the definition of a service level process.
 
-.. aou_req:: SW platform testing
+.. aou_req:: SW-platform testing
    :id: aou_req__platform__testing
    :reqtype: Non-Functional
    :security: YES
@@ -116,23 +116,23 @@ It is the level where the S-CORE SW platform will functionally "work" with the e
    The system integrator shall run the tests provided by S-CORE (platform, feature, component and Unit level for his selected S-CORE modules) on his selected OS/Hypervisor/HW combination,
    or provide equivalent argumentation.
 
-   Note1: S-CORE will run these tests for one or more reference OS/Hypervisor/HW combination, if not all passing, remaining issues are documented in release notes. In case the selected combination is equal to a S-CORE reference and the complete S-CORE SW platform is used, this AoU may be skipped.
+   Note1: S-CORE will run these tests for one or more reference OS/Hypervisor/HW combination, if not all passing, remaining issues are documented in release notes. In case the selected combination is equal to a S-CORE reference and the complete S-CORE SW-platform is used, this AoU may be skipped.
 
    Note2: Equivalent argumentation could be for example that the test environments for unit tests would be sufficiently equal in S-CORE project and at the integrator.
 
-.. aou_req:: SW platform integration bug reporting
+.. aou_req:: SW-platform integration bug reporting
    :id: aou_req__platform__bug_report
    :reqtype: Non-Functional
    :security: YES
    :safety: QM
    :status: valid
 
-   The system integrator shall report the bugs found during integration of the S-CORE SW Platform on his selected OS/Hypervisor/HW combination to the external SW element supplier and S-CORE for analysis.
+   The system integrator shall report the bugs found during integration of the S-CORE SW-platform on his selected OS/Hypervisor/HW combination to the external SW element supplier and S-CORE for analysis.
 
 Assumptions on the external SW element integration - Certifiable Level
 ----------------------------------------------------------------------
 
-This is the highest level of integraton. This is the level where the S-CORE SW platform will be certifiable with an external SW element.
+This is the highest level of integraton. This is the level where the S-CORE SW-platform will be certifiable with an external SW element.
 
 .. aou_req:: integration levels
    :id: aou_req__platform__levels
@@ -165,8 +165,8 @@ This is the highest level of integraton. This is the level where the S-CORE SW p
 
    The supplier shall provide a list of safe external SW element functions.
 
-.. aou_req:: OS safety anomaly reporting
-   :id: aou_req__platform__os_safety_anomaly
+.. aou_req:: safety anomaly reporting
+   :id: aou_req__platform__safety_anomaly
    :reqtype: Non-Functional
    :security: YES
    :safety: ASIL_B
@@ -183,29 +183,29 @@ This is the highest level of integraton. This is the level where the S-CORE SW p
    :safety: ASIL_B
    :status: valid
 
-   If the system using the SW platform has safety goals, the system integrator shall integrate the SW platform with external SW elements providing safety functions.
-   This includes to make sure that the safety functions S-CORE SW platform requires match with the ones provided by these external SW elements (as in :need:`aou_req__platform__safety_functions`).
+   If the system using the SW-platform has safety goals, the system integrator shall integrate the SW-platform with external SW elements providing safety functions.
+   This includes to make sure that the safety functions S-CORE SW-platform requires match with the ones provided by these external SW elements (as in :need:`aou_req__platform__safety_functions`).
 
    Note1: A list of safety functions needed from external SW elements is compiled by the S-CORE project here (TBD).
 
-   Note2: The integrator can expect that for the safe S-CORE reference integration (incl. OS and other external SW elements) this AoU is fulfilled by S-CORE SW Platform already, but without guarantee.
+   Note2: The integrator can expect that for the safe S-CORE reference integration (incl. OS and other external SW elements) this AoU is fulfilled by S-CORE SW-platform already, but without guarantee.
 
-   Note3: This applies also if the system integrator would replace a S-CORE SW platform element with another SW element which is external to S-CORE.
+   Note3: This applies also if the system integrator would replace a S-CORE SW-platform element with another SW element which is external to S-CORE.
 
 .. aou_req:: safety integration
-   :id: aou_req__platform__os_safety_integration
+   :id: aou_req__platform__safety_integration
    :reqtype: Non-Functional
    :security: YES
    :safety: ASIL_B
    :status: valid
 
-   If the system using the SW platform has safety goals, the system integrator shall make sure that the AoUs relevant for external SW element safety functions (as in :need:`aou_req__platform__safety_aou`) are fulfilled by the S-CORE SW platform.
+   If the system using the SW-platform has safety goals, the system integrator shall make sure that the AoUs relevant for external SW element safety functions (as in :need:`aou_req__platform__safety_aou`) are fulfilled by the S-CORE SW-platform.
 
    Note1: This could be done by contributing the required updates to the S-CORE project if S-CORE elements are affected.
 
-   Note2: The system integrator can expect that for the safe S-CORE reference integration (incl. OS and other external SW elements) this AoU is fulfilled by S-CORE SW Platform already, but without guarantee.
+   Note2: The system integrator can expect that for the safe S-CORE reference integration (incl. OS and other external SW elements) this AoU is fulfilled by S-CORE SW-platform already, but without guarantee.
 
-   Note3: This applies also if the system integrator would replace a S-CORE SW platform element with another SW element which is external to S-CORE.
+   Note3: This applies also if the system integrator would replace a S-CORE SW-platform element with another SW element which is external to S-CORE.
 
 .. aou_req:: Integrator safety anomaly reporting
    :id: aou_req__platform__integration_safety_anomaly
@@ -214,12 +214,96 @@ This is the highest level of integraton. This is the level where the S-CORE SW p
    :safety: ASIL_B
    :status: valid
 
-   If the system using the SW platform has safety goals, the system integrator shall perform safety anomaly reporting taking into account also the reporting of all the components he integrates.
+   If the system using the SW-platform has safety goals, the system integrator shall perform safety anomaly reporting taking into account also the reporting of all the components he integrates.
 
-Assumptions of Use
-------------------
 
-In this section assumptions are described which need to be fulfilled by the applications running on top of the SW platform.
+Assumptions on Applications
+---------------------------
 
+In this section assumptions are described which need to be fulfilled by the applications running on top of the SW-platform.
 
-TBD: more detailed functional AoUs
+.. aou_req:: Avoidance of Exceptions
+   :id: aou_req__platform__no_exceptions
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   All applications using the SW-platform shall not handle exceptions.
+
+   Note: Exceptions create additional overhead which may be a safety risk. Therefore, all exceptions are expected to lead directly to a termination of the application causing the exception.
+   This is supported by the library safecpp/aborts_upon_exception supplied by S-CORE "base libraries" feature.
+
+.. aou_req:: Error Reaction
+   :id: aou_req__platform__error_reaction
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   Safety applications using the SW-platform shall read error information from the requested S-CORE functions and perform an appropriate reaction.
+
+   Note: For many errors detected by SW-platform elements there could be mitigation actions to be applied by the user application.
+   So the SW-platform reports the errors to the user application and does not stop execution as a standard reaction. See :need:`stkh_req__dependability__safe_state`.
+
+.. aou_req:: No mixed ASIL
+   :id: aou_req__platform__no_mixed_asil
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   Safety application components running in one POSIX process shall implement the highest ASIL of their assigned requirements.
+
+.. aou_req:: Program Flow Monitoring
+   :id: aou_req__platform__flow_monitoring
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   Safety applications using the SW-platform shall use program flow monitoring to detect run time errors or explain in their safety concept why they do not need this.
+
+   Note1: Reasons for not needing program flow monitoring could be an OS scheduler with timing and execution guarantees.
+   Or that in case of non/late execution of the application the safety integrity of the system is not affected.
+
+   Note2: The SW-Platform supports this - see :need:`stkh_req__dependability__safety_features` "live, deadline, logical supervision"
+
+Assumptions on Safety System
+----------------------------
+
+In this section assumptions are described which need to be fulfilled by the system or system integrator.
+
+.. aou_req:: Safe HW platform
+   :id: aou_req__platform__hardware_safety
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   If the system using the SW-platform has safety goals, the system shall provide state-of-the art hardware safety mechanisms.
+
+   Note1: A selection of hardware safety mechanisms is collected in :need:`stkh_req__dependability__safety_features`
+
+   Note2: These safety mechanisms are mostly OS/Hypervisor/HW specific, so the system integrator can only expect S-CORE support for the reference OS/Hypervisor/HW combination.
+
+.. aou_req:: External Health Management
+   :id: aou_req__platform__external_health_management
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   If the system using the SW-platform has safety goals, the system shall provide an external health management element which is able to initiate a safe system state.
+
+   Note: This can be an "External Hardware Watchdog"
+
+.. aou_req:: Process Isolation
+   :id: aou_req__platform__process_isolation
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   If the system using the SW-platform has safety goals, the used operating system shall offer POSIX processes isolation.
+   This shall cover memory isolation. Timing isolation may be covered.

docs/requirements/stakeholder/index.rst

@@ -248,9 +248,10 @@ Dependability
    :reqtype: Functional
    :security: NO
    :safety: ASIL_B
-   :rationale: tbd
+   :rationale: There are state-of-the-art safety mechanisms to check HW and SW errors. These are expected to be supported either by the SW-platform alone or by using HW or OS provided safety features.
    :status: valid
    :tags: safety_mechanism
+   :valid_from: v1.0.0
 
    The SW-platform shall support the following safety feature:
 
@@ -264,9 +265,91 @@ Dependability
    * ECC Memory
    * Software Lockstep
    * Power management integrated circuit (PMIC), external watchdog and voltage monitoring
-   * Safe switch from engineering for field mode and back
+   * Safe switch from engineering to field mode and back
 
-   Note: This is part of 0.5 release and therefore can only support ASIL_B. Goal is ASIL_D.
+
+.. stkh_req:: SW-platform error reaction
+   :id: stkh_req__dependability__error_reaction
+   :reqtype: Functional
+   :security: NO
+   :safety: ASIL_B
+   :rationale: Safety relies on error reporting, e.g. to preserve a safe system state.
+   :status: valid
+   :tags: safety_mechanism
+
+   The SW-platform shall react in the following way on errors:
+
+   - report the error (incl. details if available) to the calling user function
+
+   Note: See also :need:`stkh_req__dependability__safe_state`
+
+
+.. stkh_req:: Safe SW-platform state
+   :id: stkh_req__dependability__safe_state
+   :reqtype: Functional
+   :security: NO
+   :safety: ASIL_B
+   :rationale: A safe state definition is a common expectation of safety integrity standards.
+   :status: valid
+   :tags: safety_mechanism
+   :valid_from: v1.0.0
+
+   The SW-platform shall react in the following way on errors:
+
+   - in case of an unrecoverable error (e.g. access violations), report the error to the external health monitor
+
+   Note1: Together with :need:`stkh_req__dependability__error_reaction` the "safe state" of the SW-platform can be described as "error reported".
+
+   Note2: The implementation of the reporting of an unrecoverable error must take into account that after such an error
+   the functions of the SW-platform may be corrupted (solution for this may be a cyclic triggering of an external watchdog in the healthy case
+   and stopping the triggering in the error case).
+
+
+.. stkh_req:: Error report timing
+   :id: stkh_req__dependability__error_report_timing
+   :reqtype: Functional
+   :security: NO
+   :safety: ASIL_B
+   :rationale: It is assumed that there is a need to know how much time is allowed between the ocurrence of an error and the reporting, so we define a feasible time span.
+   :status: valid
+   :tags: safety_mechanism
+   :valid_from: v1.0.0
+
+   The SW-platform shall react on errors (as described in :need:`stkh_req__dependability__safe_state` and :need:`stkh_req__dependability__error_reaction`) within 1 millisecond. If this is not feasible a special component AoU needs to be defined.
+
+   Note1: The time span mentioned is the SW reaction time and not the time between the error happening and the reporting.
+   For example if there is a alive supervision configured with 10ms cycle time and 5ms allowed delay,
+   the error could happen in the first millisecond but will be reported earliest after 10+5ms plus the SW reaction time.
+
+   Note2: If a user application calls a SW-platform function the (error) return is required latest after the reaction time, so there could be a timeout used by the application considering this.
+
+
+.. stkh_req:: No mixed ASIL
+   :id: stkh_req__dependability__no_mixed_asil
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :rationale: It is assumed that POSIX processes as implemented by the OS provide isolation from memory and timing errors of other processes but not within.
+   :status: valid
+
+   The SW-platform safety components running in one POSIX process shall implement the highest ASIL of their assigned functional requirements.
+
+
+.. stkh_req:: Program Flow Monitoring
+   :id: stkh_req__dependability__flow_monitoring
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :rationale: Not all POSIX operating systems provide protection of POSIX processes from timing errors (e.g. delayed execution, deadlocks)
+   :status: valid
+   :valid_from: v1.0.0
+
+   The SW-platform safety components shall use program flow monitoring to detect run time errors or explain in their safety concept why they do not need this.
+
+   Note1: Reasons for not needing program flow monitoring could be an OS scheduler with timing and execution guarantees.
+   Or that the non/late execution of the application keeps the system in a safe state.
+
+   Note2: The SW-Platform supports this - see :need:`stkh_req__dependability__safety_features` "live, deadline, logical supervision"
 
 
 .. stkh_req:: Availability