Merge pull request eclipse-score#2515 from eclipse-score/aschemmel-tech-add-os-integration

aschemmel-tech · web-flow · commit b670fe68a53e · 2026-02-19T13:26:56.000+01:00
OS module requirements and AoU
diff --git a/docs/modules/baselibs/memory_shared/docs/architecture/index.rst b/docs/modules/baselibs/memory_shared/docs/architecture/index.rst
@@ -21,7 +21,7 @@ Memory Shared Component Architecture
    :safety: ASIL_B
    :status: valid
    :implements: logic_arc_int__baselibs__memory_shared
-   :uses: logic_arc_int__os__fcntl, logic_arc_int__os__stat, logic_arc_int__os__mmap
+   :uses: logic_arc_int__os__fcntl, logic_arc_int__os__stat, logic_arc_int__os__mman
 
    .. needarch::
       :scale: 50
diff --git a/docs/modules/communication/docs/requirements/aou_req.rst b/docs/modules/communication/docs/requirements/aou_req.rst
@@ -1,3 +1,17 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2025 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
 Assumptions of Use
 ##################
 
diff --git a/docs/modules/lifecycle/index.rst b/docs/modules/lifecycle/index.rst
@@ -43,7 +43,7 @@ Lifecycle
    :status: valid
    :safety: ASIL_B
    :implements: logic_arc_int__lifecycle__controlif, logic_arc_int__lifecycle__alive_if
-   :uses: logic_arc_int__logging__logging, logic_arc_int__baselibs__json, logic_arc_int__os__fork, logic_arc_int__lifecycle__lifecycle_if
+   :uses: logic_arc_int__logging__logging, logic_arc_int__baselibs__json, logic_arc_int__os__unistd, logic_arc_int__lifecycle__lifecycle_if
    :security: NO
 
 
diff --git a/docs/modules/os/docs/index.rst b/docs/modules/os/docs/index.rst
@@ -18,12 +18,22 @@
    :safety: ASIL_B
    :security: YES
    :includes: comp__os_libc, comp__os_message_passing
+   :tags: external
 
-.. mod_view_sta:: OS
+.. mod_view_sta:: OS (external)
    :id: mod_view_sta__os__os
-   :includes: comp__os_libc, comp__os_message_passing
+   :includes: comp__os_libc, comp__os_message_passing, comp__os_libcpp
    :belongs_to: mod__os
 
+   The module "OS" is not a part of the S-CORE SW-Platform, but it is a crucial external SW element.
+   Its components are modelled in S-CORE to be able to describe dependencies of S-CORE features to this external component.
+   As it is external to S-CORE, the (folder/file) structure of the documentation may be different from the other modules.
+   Its main content is the operating system environment (sometimes also already called a "SW platform").
+   But also other SW components are modelled as a part of it as these are often provided by the "OS" supplier.
+   One example of these "other" SW components are the C/C++ libs which may come from a processor manufacturer instead.
+   S-CORE expects to support integration of more than one operating system, so these may be seen already in this module view,
+   as different components. Requirements on this OS integration are documented in :need:`doc__os_requirements`.
+
    .. needarch::
       :scale: 50
       :align: center
@@ -36,3 +46,6 @@ Module Documents
 .. toctree::
    :maxdepth: 2
    :titlesonly:
+
+   requirements/index.rst
+   requirements/aou_req.rst
diff --git a/docs/modules/os/docs/requirements/aou_req.rst b/docs/modules/os/docs/requirements/aou_req.rst
@@ -0,0 +1,83 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2026 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+Assumptions of Use
+##################
+
+.. document:: Operating System Assumptions of Use
+   :id: doc__os_aou
+   :status: draft
+   :safety: ASIL_B
+   :security: YES
+   :realizes: wp__requirements_comp
+
+.. aou_req:: No Root Privileges
+   :id: aou_req__os__nonroot
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   No process running on the SW-platform shall request root privileges.
+
+   Note: The root privilege is dangerous for security and safety as it destroys process isolation.
+
+.. aou_req:: Safe OS Function Use
+   :id: aou_req__os__safe_fctn_use
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   If an application or SW-platform component is safety relevant and uses OS functions, it shall only use the safe functions.
+
+   Note: For checking the "to be expected" safe functions the developer can consider the safe function list
+   published by the OS supplier. For QNX this can be found for example in `appendices here <https://fs-products.tuvasi.com/certificates?keywords=Blackberry&productcategory_id=1#prodid_9842>`_ (for one version).
+
+.. aou_req:: OS Public API Use
+   :id: aou_req__os__public_api
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   All components shall only use the public API of the OS components.
+
+.. aou_req:: C++ Library Preference
+   :id: aou_req__os__cxx_preference
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   All components should prefer the use of C++ standard lib over the C lib to call a functionality.
+   If C lib must be used, it shall not be mixed with C++ lib for the same functionality.
+
+.. aou_req:: Minimal Process Privileges
+   :id: aou_req__os__minimal_privileges
+   :reqtype: Functional
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   All components shall only use the privileges that are indispensable for their function.
+
+   Note1: OS safety manuals provide lists of allowed and not allowed privileges.
+
+   Note2: One example is the "channel connect" - only IPC connections are allowed which are specified in the architecture.
+
+   Note3: Another example is mmap_peer which would allow accessing other processes memory if wrongly used.
+
+.. needextend:: "__os_" in id
+   :+tags: operating_system
diff --git a/docs/modules/os/docs/requirements/index.rst b/docs/modules/os/docs/requirements/index.rst
@@ -0,0 +1,65 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2026 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+
+
+Requirements
+############
+
+.. document:: Operating System Requirements
+   :id: doc__os_requirements
+   :status: draft
+   :safety: ASIL_B
+   :security: YES
+   :realizes: wp__requirements_comp
+
+Generally the OS (as an external SW element) is expected by the S-CORE project to fulfill the following requirements,
+defined in the SW-platform assumptions (and partly even in the Stakeholder requirements).
+
+The system integrator integrating S-CORE with the OS to provide a safe product has to make sure
+
+- the functional requirements below are matching the OS used - see also :need:`aou_req__platform__safety_matching`
+- the non-functional (integration) requirements below are fulfilled by the OS supplier - see also :ref:`integration_assumptions`
+
+Integration Requirements
+========================
+
+Community Level
+---------------
+
+- :need:`aou_req__platform__integration_assistance`
+- :need:`aou_req__platform__os_integration_manual`
+- :need:`aou_req__platform__bug_interface`
+
+Functional Level
+----------------
+
+- :need:`aou_req__platform__bazel_tooling`
+- :need:`aou_req__platform__bug_fixing`
+
+Certifiable Level
+-----------------
+
+- :need:`aou_req__platform__levels`
+- :need:`aou_req__platform__safety_aou`
+- :need:`aou_req__platform__safety_functions`
+- :need:`aou_req__platform__safety_anomaly`
+
+
+OS Specific Functional Requirements
+===================================
+
+- :need:`aou_req__platform__process_isolation`
+- :need:`aou_req__platform__os_safety_functions`
+- :need:`aou_req__platform__posix_operating_system`
diff --git a/docs/modules/os/libc/docs/architecture/index.rst b/docs/modules/os/libc/docs/architecture/index.rst
@@ -15,12 +15,12 @@
 libc Component Architecture
 ***************************
 
-.. comp:: os::libc
+.. comp:: libc
    :id: comp__os_libc
    :security: YES
    :safety: ASIL_B
    :status: valid
-   :implements: logic_arc_int__os__fcntl, logic_arc_int__os__stat, logic_arc_int__os__mmap, logic_arc_int__os__fork
+   :implements: logic_arc_int__os__fcntl, logic_arc_int__os__stat, logic_arc_int__os__mman, logic_arc_int__os__unistd
 
 .. comp_arc_sta:: libc
    :id: comp_arc_sta__os__libc
@@ -72,8 +72,8 @@ libc Component Architecture
    :status: valid
    :included_by: logic_arc_int__os__fcntl
 
-.. logic_arc_int:: mmap
-   :id: logic_arc_int__os__mmap
+.. logic_arc_int:: mman
+   :id: logic_arc_int__os__mman
    :security: YES
    :safety:  ASIL_B
    :status: valid
@@ -91,14 +91,14 @@ libc Component Architecture
    :security: YES
    :safety:  ASIL_B
    :status: valid
-   :included_by: logic_arc_int__os__mmap
+   :included_by: logic_arc_int__os__mman
 
 .. logic_arc_int_op:: SHM Unlink
    :id: logic_arc_int_op__os__shm_unlink
    :security: YES
    :safety:  ASIL_B
    :status: valid
-   :included_by: logic_arc_int__os__mmap
+   :included_by: logic_arc_int__os__mman
 
 .. logic_arc_int:: stat
    :id: logic_arc_int__os__stat
@@ -153,3 +153,22 @@ libc Component Architecture
    :safety:  ASIL_B
    :status: valid
    :included_by: logic_arc_int__os__stat
+
+.. logic_arc_int:: unistd
+   :id: logic_arc_int__os__unistd
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   .. needarch::
+      :scale: 50
+      :align: center
+
+      {{ draw_interface(need(), needs) }}
+
+.. logic_arc_int_op:: fork
+   :id: logic_arc_int_op__os__fork
+   :security: YES
+   :safety:  ASIL_B
+   :status: valid
+   :included_by: logic_arc_int__os__unistd
diff --git a/docs/modules/os/libcpp/docs/architecture/index.rst b/docs/modules/os/libcpp/docs/architecture/index.rst
@@ -0,0 +1,50 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2026 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+libcpp Component Architecture
+*****************************
+
+.. comp:: libcpp
+   :id: comp__os_libcpp
+   :status: valid
+   :safety: ASIL_B
+   :implements: logic_arc_int__os__libcpp
+   :security: YES
+
+.. comp_arc_sta:: C++ Std Library
+   :id: comp_arc_sta__os__libcpp
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+   :satisfies:
+   :belongs_to: comp__os_libcpp
+   :fulfils: comp_req__component_name__some_title
+
+   .. needarch::
+      :scale: 50
+      :align: center
+
+      {{ draw_component(need(), needs) }}
+
+.. logic_arc_int:: Library headers (C++17)
+   :id: logic_arc_int__os__libcpp
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+
+   .. needarch::
+      :scale: 50
+      :align: center
+
+      {{ draw_interface(need(), needs) }}
diff --git a/docs/modules/os/libcpp/docs/index.rst b/docs/modules/os/libcpp/docs/index.rst
@@ -0,0 +1,27 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2026 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+.. _comp_doc_libcpp:
+
+libcpp
+######
+
+Component Documents
+===================
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   architecture/index
diff --git a/docs/modules/os/message_passing/docs/architecture/index.rst b/docs/modules/os/message_passing/docs/architecture/index.rst
@@ -21,6 +21,7 @@ Message Passing Component Architecture
    :safety: ASIL_B
    :status: valid
    :implements: logic_arc_int__os__message_passing
+   :satisfies:
 
 
 .. comp_arc_sta:: QNX::Message Passing Static View
@@ -49,18 +50,6 @@ Message Passing Component Architecture
 
       {{ draw_interface(need(), needs) }}
 
-.. logic_arc_int:: OS::fork
-   :id: logic_arc_int__os__fork
-   :security: YES
-   :safety: ASIL_B
-   :status: valid
-
-   .. needarch::
-      :scale: 50
-      :align: center
-
-      {{ draw_interface(need(), needs) }}
-
 .. logic_arc_int_op:: Reply
    :id: logic_arc_int_op__os__reply
    :security: YES
diff --git a/docs/requirements/platform_assumptions/index.rst b/docs/requirements/platform_assumptions/index.rst
