diff --git a/docs/features/nonipc/index.rst b/docs/features/nonipc/index.rst new file mode 100644 index 00000000000..db4f3ab5af5 --- /dev/null +++ b/docs/features/nonipc/index.rst @@ -0,0 +1,122 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _nonipc_feature: + +NonIPC Communication +#################### + +.. document:: NonIPC Communication + :id: doc__nonipc + :status: valid + :safety: ASIL_B + :tags: feature_request + :security: YES + :realizes: wp__feat_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/nonipc/requirements/index.rst b/docs/features/nonipc/requirements/index.rst new file mode 100644 index 00000000000..67ac7dbe037 --- /dev/null +++ b/docs/features/nonipc/requirements/index.rst @@ -0,0 +1,146 @@ +.. + # ******************************************************************************* + # 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 +############ + +.. feat_req:: One-way data sharing into a VM + :id: feat_req__nonipc__one_way_sharing + :reqtype: Functional + :security: YES + :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