From 3016331a1ebd81ea3181c5b56d67da5fb9b9469a Mon Sep 17 00:00:00 2001 From: FScholPer Date: Fri, 4 Jul 2025 07:16:11 +0200 Subject: [PATCH 1/4] docs: added nonipc feature(#916) --- docs/features/non-ipc/index.rst | 120 +++++++++++++++ docs/features/non-ipc/requirements/index.rst | 146 +++++++++++++++++++ docs/requirements/stakeholder/index.rst | 10 ++ 3 files changed, 276 insertions(+) create mode 100644 docs/features/non-ipc/index.rst create mode 100644 docs/features/non-ipc/requirements/index.rst diff --git a/docs/features/non-ipc/index.rst b/docs/features/non-ipc/index.rst new file mode 100644 index 00000000000..b698b3ffd2c --- /dev/null +++ b/docs/features/non-ipc/index.rst @@ -0,0 +1,120 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _non-ipc_feature: + +NonIPC Communication +#################### + +.. document:: NonIPC Communication + :id: doc__nonipc + :status: valid + :safety: ASIL_B + :tags: feature_request + + +.. toctree:: + :maxdepth: 2 + + ./requirements/index + + +Feature flag +============ + +To activate this feature, use the following feature flag: + +``experimental_nonipc_com`` + +Abstract +======== + +This feature provides mechanisms for communication and data exchange between processes without using IPC. +It includes two classes of communication/data-exchange: + +1. One-way data sharing into a VM for (vehicle) state read-only for the VM (snapshot state) + - Read-only for consumer (VM) + - Support for consistent data-sets (consumer must be able to get a consistent version of related data items) + - Consistent access must be lock-free + - Producer time stamps shall be available for related data-sets + +2. Streamed data based on shared queues (stream of events or data) + - Queues shall be configurable by client (VM) (number of elements etc..) + - Size of a queue + - Allocation of buffers for the data elements + - Queues shall support lock-free access to data elements + - Support for bi-directional communication via writable data elements by the client + - Asynchronous bi-directional support via multiple queues + +Motivation +========== + +NonIPC communication mechanisms are essential to ensure efficient and reliable data exchange between processes, especially in scenarios where IPC may not be suitable or desired. + +Rationale +========= + +These communication mechanisms are developed to address specific needs for data sharing and streaming in a VM environment, ensuring consistent and lock-free access to data. + +Specification +============= + +The NonIPC communication feature consists of the following mechanisms: + +- **One-way data sharing**: Allows read-only access to vehicle state data in a VM, ensuring consistency and lock-free access. +- **Streamed data**: Utilizes shared queues for streaming events or data, configurable by the client, supporting bi-directional communication. + +General requirements: +--------------------- + +- Multiple chunks of shared memory shall be supported to allow required access control. +- Notifications for data updates shall be available (virtual IRQs in a VM). +- Notifications shall be configurable by consumers of data (using flags or watermarks in shared memory from client to producer). + +Backwards Compatibility +======================= + +As this is a new feature, there are no backwards compatibility concerns. + +Security Impact +=============== + +NonIPC communication mechanisms present varying security risks as vulnerabilities could affect multiple components simultaneously. +Each mechanism requires individual security impact analysis based on its functionality and usage patterns. + +Safety Impact +============= + +- Due to wide usage of these communication mechanisms throughout the platform, extra care is needed in design, implementation, and testing to minimize safety impact. +- Mechanisms are developed at various integrity levels from QM (non-safety) up to ASIL-B, depending on their intended use cases. + +License Impact +============== + +The NonIPC communication mechanisms are licensed under Apache License 2.0. + +How to Teach This +================= + +Each mechanism is expected to have a user manual that includes an API reference and usage examples where necessary. + +Rejected Ideas +============== + +There are no rejected ideas related to the NonIPC communication feature at this time. + +Open Issues +=========== + +There are currently no open issues related to the NonIPC communication feature. diff --git a/docs/features/non-ipc/requirements/index.rst b/docs/features/non-ipc/requirements/index.rst new file mode 100644 index 00000000000..6af5831dfef --- /dev/null +++ b/docs/features/non-ipc/requirements/index.rst @@ -0,0 +1,146 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. feat_req:: One-way data sharing into a VM + :id: feat_req__nonipc__one_way_sharing + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + The system shall support one-way data sharing into a VM for vehicle state read-only for the VM (snapshot state). + +.. feat_req:: Read-only access for VM + :id: feat_req__nonipc__readonly_vm + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + The consumer (VM) shall have read-only access to the shared data. + +.. feat_req:: Consistent data-sets + :id: feat_req__nonipc__consistent_data + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + The system shall support consistent data-sets, allowing the consumer to obtain a consistent version of related data items. + +.. feat_req:: Lock-free access + :id: feat_req__nonipc__lock_free_access + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + Consistent access to data must be lock-free. + +.. feat_req:: Producer time stamps + :id: feat_req__nonipc__producer_timestamps + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + Producer time stamps shall be available for related data-sets. + +.. feat_req:: Streamed data based on shared queues + :id: feat_req__nonipc__streamed_data + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + The system shall support streamed data based on shared queues (stream of events or data). + +.. feat_req:: Configurable queues + :id: feat_req__nonipc__configurable_queues + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + Queues shall be configurable by the client (VM), including the number of elements and buffer allocation. + +.. feat_req:: Lock-free queue access + :id: feat_req__nonipc__lock_free_queue + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + Queues shall support lock-free access to data elements. + +.. feat_req:: Bi-directional communication + :id: feat_req__nonipc__bi_directional_comm + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + The system shall support bi-directional communication via writable data elements by the client. + +.. feat_req:: Asynchronous support + :id: feat_req__nonipc__async_support + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + The system shall provide asynchronous bi-directional support via multiple queues. + +.. feat_req:: Shared memory chunks + :id: feat_req__nonipc__shared_memory + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + The system shall support multiple chunks of shared memory to allow required access control. + +.. feat_req:: Data update notifications + :id: feat_req__nonipc__data_notifications + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + Notifications for data updates shall be available (virtual IRQs in a VM). + +.. feat_req:: Configurable notifications + :id: feat_req__nonipc__config_notifications + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__communication__vm + :status: valid + + Notifications shall be configurable by consumers of data (using flags or watermarks in shared memory from client to producer). diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index e916fabf3d2..52eebb53bec 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -564,6 +564,16 @@ Communication The SW-platform shall support intra-process communication. +.. stkh_req:: Non-Intra-process Communication + :id: stkh_req__communication__vm + :reqtype: Functional + :security: NO + :safety: QM + :rationale: Application software typically maps software building blocks into the same process. + :status: valid + + The platform shall support not only IPC but also intra VM communication. + .. stkh_req:: Stable application interfaces :id: stkh_req__communication__stable_app_inter :reqtype: Functional From 17f6306d3c16c161b09adae60995f1e7712bc609 Mon Sep 17 00:00:00 2001 From: Frank Scholter Peres Date: Tue, 10 Feb 2026 18:21:02 +0000 Subject: [PATCH 2/4] updated to new folder --- docs/features/{non-ipc => nonipc}/index.rst | 6 ++++-- docs/features/{non-ipc => nonipc}/requirements/index.rst | 4 ++-- 2 files changed, 6 insertions(+), 4 deletions(-) rename docs/features/{non-ipc => nonipc}/index.rst (96%) rename docs/features/{non-ipc => nonipc}/requirements/index.rst (98%) diff --git a/docs/features/non-ipc/index.rst b/docs/features/nonipc/index.rst similarity index 96% rename from docs/features/non-ipc/index.rst rename to docs/features/nonipc/index.rst index b698b3ffd2c..62458b48e0c 100644 --- a/docs/features/non-ipc/index.rst +++ b/docs/features/nonipc/index.rst @@ -1,6 +1,6 @@ .. # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation + # Copyright (c) 2026 Contributors to the Eclipse Foundation # # See the NOTICE file(s) distributed with this work for additional # information regarding copyright ownership. @@ -12,7 +12,7 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. _non-ipc_feature: +.. _nonipc_feature: NonIPC Communication #################### @@ -22,6 +22,8 @@ NonIPC Communication :status: valid :safety: ASIL_B :tags: feature_request + :security: YES + :realizes: wp__feat_request .. toctree:: diff --git a/docs/features/non-ipc/requirements/index.rst b/docs/features/nonipc/requirements/index.rst similarity index 98% rename from docs/features/non-ipc/requirements/index.rst rename to docs/features/nonipc/requirements/index.rst index 6af5831dfef..67ac7dbe037 100644 --- a/docs/features/non-ipc/requirements/index.rst +++ b/docs/features/nonipc/requirements/index.rst @@ -1,6 +1,6 @@ .. # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation + # Copyright (c) 2026 Contributors to the Eclipse Foundation # # See the NOTICE file(s) distributed with this work for additional # information regarding copyright ownership. @@ -18,7 +18,7 @@ Requirements .. feat_req:: One-way data sharing into a VM :id: feat_req__nonipc__one_way_sharing :reqtype: Functional - :security: NO + :security: YES :safety: QM :satisfies: stkh_req__communication__vm :status: valid From bec2c17ac840c0df81dc9126fb304e3eb1df1003 Mon Sep 17 00:00:00 2001 From: Frank Scholter Peres Date: Tue, 10 Feb 2026 19:35:23 +0000 Subject: [PATCH 3/4] fix warnings --- docs/features/nonipc/index.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/features/nonipc/index.rst b/docs/features/nonipc/index.rst index 62458b48e0c..0da9cb1cf98 100644 --- a/docs/features/nonipc/index.rst +++ b/docs/features/nonipc/index.rst @@ -46,18 +46,18 @@ This feature provides mechanisms for communication and data exchange between pro It includes two classes of communication/data-exchange: 1. One-way data sharing into a VM for (vehicle) state read-only for the VM (snapshot state) - - Read-only for consumer (VM) - - Support for consistent data-sets (consumer must be able to get a consistent version of related data items) - - Consistent access must be lock-free - - Producer time stamps shall be available for related data-sets + * Read-only for consumer (VM) + * Support for consistent data-sets (consumer must be able to get a consistent version of related data items) + * Consistent access must be lock-free + * Producer time stamps shall be available for related data-sets 2. Streamed data based on shared queues (stream of events or data) - - Queues shall be configurable by client (VM) (number of elements etc..) - - Size of a queue - - Allocation of buffers for the data elements - - Queues shall support lock-free access to data elements - - Support for bi-directional communication via writable data elements by the client - - Asynchronous bi-directional support via multiple queues + * Queues shall be configurable by client (VM) (number of elements etc..) + * Size of a queue + * Allocation of buffers for the data elements + * Queues shall support lock-free access to data elements + * Support for bi-directional communication via writable data elements by the client + * Asynchronous bi-directional support via multiple queues Motivation ========== @@ -74,15 +74,15 @@ Specification The NonIPC communication feature consists of the following mechanisms: -- **One-way data sharing**: Allows read-only access to vehicle state data in a VM, ensuring consistency and lock-free access. -- **Streamed data**: Utilizes shared queues for streaming events or data, configurable by the client, supporting bi-directional communication. +* **One-way data sharing**: Allows read-only access to vehicle state data in a VM, ensuring consistency and lock-free access. +* **Streamed data**: Utilizes shared queues for streaming events or data, configurable by the client, supporting bi-directional communication. General requirements: --------------------- -- Multiple chunks of shared memory shall be supported to allow required access control. -- Notifications for data updates shall be available (virtual IRQs in a VM). -- Notifications shall be configurable by consumers of data (using flags or watermarks in shared memory from client to producer). +* Multiple chunks of shared memory shall be supported to allow required access control. +* Notifications for data updates shall be available (virtual IRQs in a VM). +* Notifications shall be configurable by consumers of data (using flags or watermarks in shared memory from client to producer). Backwards Compatibility ======================= @@ -98,8 +98,8 @@ Each mechanism requires individual security impact analysis based on its functio Safety Impact ============= -- Due to wide usage of these communication mechanisms throughout the platform, extra care is needed in design, implementation, and testing to minimize safety impact. -- Mechanisms are developed at various integrity levels from QM (non-safety) up to ASIL-B, depending on their intended use cases. +* Due to wide usage of these communication mechanisms throughout the platform, extra care is needed in design, implementation, and testing to minimize safety impact. +* Mechanisms are developed at various integrity levels from QM (non-safety) up to ASIL-B, depending on their intended use cases. License Impact ============== From 82d2add62eabca57571b0c82ed632412dd5d5faa Mon Sep 17 00:00:00 2001 From: Frank Scholter Peres Date: Tue, 10 Feb 2026 19:49:11 +0000 Subject: [PATCH 4/4] fix ident --- docs/features/nonipc/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/nonipc/index.rst b/docs/features/nonipc/index.rst index 0da9cb1cf98..db4f3ab5af5 100644 --- a/docs/features/nonipc/index.rst +++ b/docs/features/nonipc/index.rst @@ -53,8 +53,8 @@ It includes two classes of communication/data-exchange: 2. Streamed data based on shared queues (stream of events or data) * Queues shall be configurable by client (VM) (number of elements etc..) - * Size of a queue - * Allocation of buffers for the data elements + * Size of a queue + * Allocation of buffers for the data elements * Queues shall support lock-free access to data elements * Support for bi-directional communication via writable data elements by the client * Asynchronous bi-directional support via multiple queues