From 57bb4a55720a2f7150035c55a2d5216d984f28b4 Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Thu, 18 Jun 2026 12:41:50 +0200 Subject: [PATCH 01/17] Feature Request for DDS Gateway --- .../communication/dds_gateway/index.rst | 178 ++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 docs/features/communication/dds_gateway/index.rst diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst new file mode 100644 index 00000000000..a47b4f77743 --- /dev/null +++ b/docs/features/communication/dds_gateway/index.rst @@ -0,0 +1,178 @@ +.. + # ******************************************************************************* + # Copyright (c) 2024 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 + # ******************************************************************************* + +DDS Gateway +=========== + +.. document:: DDS-Gateway + :id: doc__dds_gateway + :status: valid + :safety: ASIL_B + :tags: contribution_request, feature_request + :security: YES + :realizes: wp__feat_request + + +Overview +-------- + +The DDS Gateway introduces a communication bridge within the S-CORE communication stack. +It enables controlled and configurable data exchange between ``mw::com (LoLa)`` (intra-ECU +communication via IPC binding) and DDS-based systems (inter-ECU +communication), allowing integration with distributed DDS environments +while preserving existing application implementations. + +Architecture Concept +-------------------- +The DDS Gateway acts as a centralized communication bridge between local +``mw::com (LoLa)`` communication and DDS domains, enabling inter-ECU +communication between ``mw::com`` participants via DDS transport. + +:: + + ============================== ============================== + ECU 1 ECU 2 + ============================== ============================== + + +-------------------------+ +-------------------------+ + | Application A | | Application B | + | (mw::com LoLa) | | (mw::com LoLa) | + +-----------+-------------+ +-----------+-------------+ + | ^ + | mw::com (LoLa - IPC) | mw::com (LoLa - IPC) + v | + +---------------------+ +---------------------+ + | DDS Gateway | | DDS Gateway | + | (ECU 1) | | (ECU 2) | + +----------+----------+ +----------+----------+ + | ^ + | | + v | + =================== DDS NETWORK =================== + | ^ + ============================== | + ECU 3 | + ============================== | + | | + v | + +---------------------+ | + | DDS Application |--------------------------+ + | (optional) | + +---------------------+ + +Each DDS Gateway instance connects to: +- Local ``mw::com (LoLa)`` participants (IPC binding) +- A DDS domain for inter-ECU communication + +The gateway is responsible for: + +- Translating data in both directions between ``mw::com`` and DDS representations +- Routing data across DDS domains +- configure QOS on DDS for each route +- Applying E2E protection + + +Scope +----- +The DDS Gateway provides: + +- Bridging between ``mw::com (LoLa)`` and DDS via the gateway: + - ``mw::com (LoLa)`` → DDS GW → ``mw::com (LoLa)`` (inter-ECU communication via DDS) + - ``mw::com (LoLa)`` → DDS GW → DDS applications + - DDS applications → DDS GW → ``mw::com (LoLa)`` + +- Configurable routing: + + - Mapping between ``mw::com`` events(TBD for fields and methods) and DDS topics + - Support for DDS domain-based routing + +- Dynamic Type handling: + + - Runtime type definition via configuration or via dynamic library + - No dependency on DDS IDL generation + - Enables data translation and consistent serialization across middleware boundaries + - Supports DDS standard encodings (e.g., XCDR1 and XCDR2) for interoperability + +- End-to-End (E2E) protection: + + - Centralized handling of Counter, CRC, and DataID + - Validation and protection configurable per route + +- DDS stack abstraction: + + - Pluggable DDS implementations via defined interfaces + +- Execution and performance model: + + - Asynchronous processing using internal worker queues + - Support for configurable priority-based routing + - High-priority routes can be processed with dedicated queues and worker pools to achieve low-latency data delivery + - Normal-priority routes are handled via standard processing queues + - Priority configuration is defined per route + +- DDS QoS configurability: + + - Ability to configure DDS Quality of Service (QoS) policies per route + - Enables tuning of reliability, durability, and latency behavior based on use case + +Motivation +---------- + +S-CORE currently focuses on local communication via ``mw::com (LoLa)`` but does +not provide a standardized mechanism for inter-ECU communication using DDS-based +systems. + +In mixed middleware environments: + +- Integration with DDS requires custom adapters +- Applications may need to embed DDS logic, reducing abstraction +- Communication with native DDS applications is not standardized +- Inter-ECU communication between ``mw::com`` participants via DDS is not standardized +- Multi-domain DDS setups are difficult to manage consistently + + +The DDS Gateway addresses these challenges by introducing a centralized, +configurable component responsible for bridging and routing communication +across middleware boundaries. + +Key Value +--------- + +- Standardized integration with DDS systems +- Direct interoperability with native DDS applications via the gateway +- Standardized inter-ECU communication between ``mw::com`` participants via DDS +- Clean separation between ``mw::com (LoLa)`` and DDS +- Reduced integration effort +- Support for distributed and multi-domain systems + +- Performance and determinism: + + - Low-latency processing for high-priority data flows + - Controlled execution via configurable worker queues + - Predictable behavior for mixed criticality communication + +- Interoperability across heterogeneous systems: + + - Enables communication between systems with different architectures + (e.g., 32-bit / 64-bit, different endianness) + - Ensures consistent data representation via Dynamic Type handling + +- Centralized handling of safety (E2E) and type management + +Reference +--------- + +The detailed Feature Request is available here: + +- DDS Gateway Feature Request:https://github.com/eclipse-score/score/issues/2726 From b23b40596db9989bf708d30aae0609177c04cb3a Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Thu, 25 Jun 2026 17:58:38 +0200 Subject: [PATCH 02/17] Revise DDS Gateway documentation for clarity and detail Update PR gainst https://github.com/eclipse-score/score/pull/2997#discussion_r3451771277 Signed-off-by: Abhishek GOYAL --- .../communication/dds_gateway/index.rst | 179 +++++++++++++----- 1 file changed, 128 insertions(+), 51 deletions(-) diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index a47b4f77743..4a1ff3d9506 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -12,8 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -DDS Gateway -=========== +DDS Binding and Gateway +======================= .. document:: DDS-Gateway :id: doc__dds_gateway @@ -26,18 +26,75 @@ DDS Gateway Overview -------- +This feature introduces DDS communication support for ``mw::com`` and a +reference DDS Gateway implementation. -The DDS Gateway introduces a communication bridge within the S-CORE communication stack. -It enables controlled and configurable data exchange between ``mw::com (LoLa)`` (intra-ECU -communication via IPC binding) and DDS-based systems (inter-ECU -communication), allowing integration with distributed DDS environments -while preserving existing application implementations. +DDS communication is provided as a binding beneath ``mw::com``. This allows +applications to use the ``mw::com`` abstraction while the communication is +transported over a DDS network, based on the service and deployment +configuration selected by the integrator. + +In addition, the DDS Gateway provides a reference translation concept between +local ``mw::com (LoLa)`` communication and DDS-based inter-ECU communication. +It enables controlled and configurable data exchange between intra-ECU +``mw::com (LoLa)`` participants and DDS-based systems while preserving +existing application implementations. Architecture Concept -------------------- -The DDS Gateway acts as a centralized communication bridge between local -``mw::com (LoLa)`` communication and DDS domains, enabling inter-ECU -communication between ``mw::com`` participants via DDS transport. + +The DDS feature supports two integration concepts: + +- Direct DDS binding usage beneath ``mw::com`` +- Reference DDS Gateway based translation + +Direct DDS Binding Concept +~~~~~~~~~~~~~~~~~~~~~~~~~~ +In this concept, an application uses the regular ``mw::com`` API and service +definition. The integrator selects DDS as the communication binding through +the service/deployment configuration. The application does not directly use +DDS APIs, but its communication is transported over the DDS network. + +:: + + ============================== ============================== + ECU 1 ECU 2 + ============================== ============================== + + +-------------------------+ +-------------------------+ + | Application A | | Application B | + | (mw::com) | | (mw::com) | + +-----------+-------------+ +-----------+-------------+ + | ^ + | mw::com API | mw::com API + v | + +---------------------+ +---------------------+ + | DDS Binding | | DDS Binding | + | beneath mw::com | | beneath mw::com | + +----------+----------+ +----------+----------+ + | ^ + | DDS | DDS + v | + =================== DDS NETWORK =================== + +The DDS binding provides the DDS communication layer beneath ``mw::com``. +It is responsible for runtime type handling, creation of DDS communication +entities, conversion between ``mw::com`` samples and DDS data representation, +DDS routing, QoS configuration, and interaction with the underlying DDS stack. + +Applications continue to use the standard ``mw::com`` programming model, +while the selected binding transports the data over DDS. +The application programming model remains unchanged. Publishers and subscribers +continue to allocate and populate typed ``mw::com`` samples, while the DDS +binding performs the conversion to the DDS data representation and interacts +with the underlying DDS stack. + +Reference DDS Gateway Concept +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The DDS Gateway is a reference implementation that demonstrates one possible +translation concept between local ``mw::com (LoLa)`` communication and DDS +domains. In this concept, the applications continue to use ``mw::com (LoLa)`` +locally, while the gateway performs the translation and routing to DDS. :: @@ -71,60 +128,74 @@ communication between ``mw::com`` participants via DDS transport. | (optional) | +---------------------+ +The reference DDS Gateway is implemented using the DDS communication binding +beneath ``mw::com``. The gateway focuses on translation between local +``mw::com (LoLa)`` communication and DDS communication while reusing the +common DDS communication layer. + +The reference DDS Gateway is one such implementation built on top of the +DDS communication binding. The binding architecture also supports deployment +solutions without an explicit gateway process. + Each DDS Gateway instance connects to: + - Local ``mw::com (LoLa)`` participants (IPC binding) - A DDS domain for inter-ECU communication The gateway is responsible for: -- Translating data in both directions between ``mw::com`` and DDS representations -- Routing data across DDS domains -- configure QOS on DDS for each route -- Applying E2E protection - +- Translating between ``mw::com (LoLa)`` and DDS communication +- Managing configurable translation routes +- Applying End-to-End (E2E) protection +- Scheduling translation through configurable worker queues (e.g., Mailbox and Queue policies) Scope ----- -The DDS Gateway provides: -- Bridging between ``mw::com (LoLa)`` and DDS via the gateway: - - ``mw::com (LoLa)`` → DDS GW → ``mw::com (LoLa)`` (inter-ECU communication via DDS) - - ``mw::com (LoLa)`` → DDS GW → DDS applications - - DDS applications → DDS GW → ``mw::com (LoLa)`` +This feature provides: + +DDS Communication Binding +~~~~~~~~~~~~~~~~~~~~~~~~~ -- Configurable routing: +The DDS communication binding provides DDS communication beneath ``mw::com``. - - Mapping between ``mw::com`` events(TBD for fields and methods) and DDS topics - - Support for DDS domain-based routing +It provides: -- Dynamic Type handling: +- Communication between ``mw::com`` applications over DDS using the standard + ``mw::com`` programming model +- Mapping between ``mw::com`` events (TBD for fields and methods) and DDS topics +- Support for DDS domain-based routing +- Runtime type definition via configuration (e.g. JSON) or dynamic library +- Runtime creation of DDS entities (Topics, DataReaders, and DataWriters) +- True Zero-generation workflow with no dependency on DDS IDL generation +- Conversion between ``mw::com`` raw memory samples and the DDS runtime data representation +- Serialization and deserialization using the underlying DDS stack +- Support for DDS standard encodings (e.g., XCDR1 and XCDR2) +- Per-route DDS Quality of Service (QoS) configuration +- Pluggable DDS stack implementations via defined abstract interfaces - - Runtime type definition via configuration or via dynamic library - - No dependency on DDS IDL generation - - Enables data translation and consistent serialization across middleware boundaries - - Supports DDS standard encodings (e.g., XCDR1 and XCDR2) for interoperability +Reference DDS Gateway +~~~~~~~~~~~~~~~~~~~~~ -- End-to-End (E2E) protection: +The DDS Gateway is the reference implementation for translating between +``mw::com (LoLa)`` and DDS. - - Centralized handling of Counter, CRC, and DataID - - Validation and protection configurable per route +It provides: -- DDS stack abstraction: +- Bridging between ``mw::com (LoLa)`` and DDS: + - ``mw::com (LoLa)`` → DDS GW → ``mw::com (LoLa)`` + - ``mw::com (LoLa)`` → DDS GW → DDS applications + - DDS applications → DDS GW → ``mw::com (LoLa)`` - - Pluggable DDS implementations via defined interfaces +- Centralized End-to-End (E2E) protection - Execution and performance model: - Asynchronous processing using internal worker queues - Support for configurable priority-based routing - - High-priority routes can be processed with dedicated queues and worker pools to achieve low-latency data delivery + - High-priority routes can be processed with dedicated queues and worker pools - Normal-priority routes are handled via standard processing queues - - Priority configuration is defined per route -- DDS QoS configurability: - - - Ability to configure DDS Quality of Service (QoS) policies per route - - Enables tuning of reliability, durability, and latency behavior based on use case Motivation ---------- @@ -135,26 +206,32 @@ systems. In mixed middleware environments: -- Integration with DDS requires custom adapters -- Applications may need to embed DDS logic, reducing abstraction +- ``mw::com`` does not provide a standardized DDS communication binding +- Different projects implement DDS integration using project-specific solutions +- Integration with DDS requires project-specific bindings or adapters +- Applications may need to embed DDS-specific logic, reducing abstraction - Communication with native DDS applications is not standardized - Inter-ECU communication between ``mw::com`` participants via DDS is not standardized -- Multi-domain DDS setups are difficult to manage consistently +- Multi-domain DDS deployments are difficult to configure consistently + +This feature addresses these challenges by introducing a reusable DDS +communication binding beneath ``mw::com`` together with a reference DDS +Gateway implementation. -The DDS Gateway addresses these challenges by introducing a centralized, -configurable component responsible for bridging and routing communication -across middleware boundaries. +The DDS binding provides standardized DDS communication for ``mw::com`` +applications, while the reference gateway demonstrates one possible approach +for translating between local ``mw::com (LoLa)`` communication and DDS-based +communication. Key Value --------- -- Standardized integration with DDS systems -- Direct interoperability with native DDS applications via the gateway +- Standardized DDS communication support through an ``mw::com`` binding +- Reference DDS Gateway implementation for ``mw::com (LoLa)`` to DDS translation +- Supports multiple integration concepts through a common DDS communication layer +- Direct interoperability with native DDS applications - Standardized inter-ECU communication between ``mw::com`` participants via DDS -- Clean separation between ``mw::com (LoLa)`` and DDS -- Reduced integration effort -- Support for distributed and multi-domain systems - Performance and determinism: @@ -175,4 +252,4 @@ Reference The detailed Feature Request is available here: -- DDS Gateway Feature Request:https://github.com/eclipse-score/score/issues/2726 +- DDS Gateway Feature Request: https://github.com/eclipse-score/score/issues/2726 From 5c9e3f4d62d907194c4f56bd6cc6e57dcc4d05b5 Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Thu, 25 Jun 2026 18:33:55 +0200 Subject: [PATCH 03/17] Clarify End-to-End (E2E) protection details Signed-off-by: Abhishek GOYAL --- docs/features/communication/dds_gateway/index.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index 4a1ff3d9506..81b228ca74a 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -187,7 +187,10 @@ It provides: - ``mw::com (LoLa)`` → DDS GW → DDS applications - DDS applications → DDS GW → ``mw::com (LoLa)`` -- Centralized End-to-End (E2E) protection +- End-to-End (E2E) protection: + - The translation layer performs generation and validation of Counter, CRC, and DataID + - Independent of the underlying DDS stack implementation + - Validation and protection configurable per route - Execution and performance model: @@ -245,7 +248,10 @@ Key Value (e.g., 32-bit / 64-bit, different endianness) - Ensures consistent data representation via Dynamic Type handling -- Centralized handling of safety (E2E) and type management +- End-to-End (E2E) protection: + - The translation layer performs generation and validation of Counter, CRC, and DataID + - Independent of the underlying DDS stack implementation + - Validation and protection configurable per route Reference --------- From 988cef5e0f1a23c61169b20c8a78bc65d9df9004 Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Fri, 26 Jun 2026 10:11:43 +0200 Subject: [PATCH 04/17] Improve DDS binding and reference gateway documentation Enhanced the description of the DDS binding and its features, including runtime serialization, mapping, and QoS configuration. Updated the reference DDS Gateway implementation details and clarified the support for DDS domain-based routing and type handling. Signed-off-by: Abhishek GOYAL --- .../communication/dds_gateway/index.rst | 39 ++++++++++++------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index 81b228ca74a..9e06be7abad 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -78,9 +78,10 @@ DDS APIs, but its communication is transported over the DDS network. =================== DDS NETWORK =================== The DDS binding provides the DDS communication layer beneath ``mw::com``. -It is responsible for runtime type handling, creation of DDS communication -entities, conversion between ``mw::com`` samples and DDS data representation, -DDS routing, QoS configuration, and interaction with the underlying DDS stack. +It is responsible for runtime type handling, runtime serialization and +deserialization, creation of DDS communication entities, conversion between +``mw::com`` samples and DDS runtime data representation, DDS communication +routing, QoS configuration, and interaction with the underlying DDS stack. Applications continue to use the standard ``mw::com`` programming model, while the selected binding transports the data over DDS. @@ -128,11 +129,6 @@ locally, while the gateway performs the translation and routing to DDS. | (optional) | +---------------------+ -The reference DDS Gateway is implemented using the DDS communication binding -beneath ``mw::com``. The gateway focuses on translation between local -``mw::com (LoLa)`` communication and DDS communication while reusing the -common DDS communication layer. - The reference DDS Gateway is one such implementation built on top of the DDS communication binding. The binding architecture also supports deployment solutions without an explicit gateway process. @@ -163,14 +159,26 @@ It provides: - Communication between ``mw::com`` applications over DDS using the standard ``mw::com`` programming model -- Mapping between ``mw::com`` events (TBD for fields and methods) and DDS topics -- Support for DDS domain-based routing + +- Configuration-driven mapping between ``mw::com`` and DDS: + + - Each ``mw::com`` event is mapped to one DDS Topic + - DDS Topic data is mapped back to the corresponding ``mw::com`` event + - DDS deployment configuration extends the ``mw::com`` deployment + configuration with DDS-specific attributes such as runtime type references, + QoS policies and DDS Domain IDs + - Standard DDS endpoint discovery is used to determine the availability of + configured DDS endpoints and map this to the ``mw::com`` availability model + +- Support for configurable DDS domain-based routing - Runtime type definition via configuration (e.g. JSON) or dynamic library -- Runtime creation of DDS entities (Topics, DataReaders, and DataWriters) -- True Zero-generation workflow with no dependency on DDS IDL generation -- Conversion between ``mw::com`` raw memory samples and the DDS runtime data representation -- Serialization and deserialization using the underlying DDS stack -- Support for DDS standard encodings (e.g., XCDR1 and XCDR2) +- Runtime creation of DDS entities (Topics, DataReaders and DataWriters) +- Runtime conversion between ``mw::com`` raw memory samples and the DDS runtime +data representation using runtime type definitions +- Runtime serialization and deserialization performed by the DDS binding using +configured runtime type definitions +- Support for standard DDS serialization encodings (e.g. XCDR1 and XCDR2) +- True zero-generation workflow with no dependency on DDS IDL generation - Per-route DDS Quality of Service (QoS) configuration - Pluggable DDS stack implementations via defined abstract interfaces @@ -233,6 +241,7 @@ Key Value - Standardized DDS communication support through an ``mw::com`` binding - Reference DDS Gateway implementation for ``mw::com (LoLa)`` to DDS translation - Supports multiple integration concepts through a common DDS communication layer +- DDS-stack-independent runtime type handling through a common abstraction layer - Direct interoperability with native DDS applications - Standardized inter-ECU communication between ``mw::com`` participants via DDS From eac818d3fa14355e4ee18b21deebcdd33774381b Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Fri, 26 Jun 2026 10:19:08 +0200 Subject: [PATCH 05/17] Enhance DDS Gateway documentation with Topic details Add explanation of DDS Topics and their role in communication. Signed-off-by: Abhishek GOYAL --- docs/features/communication/dds_gateway/index.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index 9e06be7abad..3a6098867e5 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -83,6 +83,12 @@ deserialization, creation of DDS communication entities, conversion between ``mw::com`` samples and DDS runtime data representation, DDS communication routing, QoS configuration, and interaction with the underlying DDS stack. +In DDS, a Topic represents a named communication channel associated with a +specific data type.The DDS binding maps ``mw::com`` events to DDS Topics and creates the +required DDS Topics, DataReaders and DataWriters from the deployment +configuration. DDS Domains provide communication isolation and may be used to separate +communication routes (for example, QM and ASIL communication). + Applications continue to use the standard ``mw::com`` programming model, while the selected binding transports the data over DDS. The application programming model remains unchanged. Publishers and subscribers From c2e63f6339070fbd0bc03332095e3a0bf4d94b80 Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Fri, 26 Jun 2026 10:23:54 +0200 Subject: [PATCH 06/17] Update DDS stack implementation description Clarified the description of pluggable DDS stack implementations. Signed-off-by: Abhishek GOYAL --- docs/features/communication/dds_gateway/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index 3a6098867e5..b0f56b66824 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -186,7 +186,8 @@ configured runtime type definitions - Support for standard DDS serialization encodings (e.g. XCDR1 and XCDR2) - True zero-generation workflow with no dependency on DDS IDL generation - Per-route DDS Quality of Service (QoS) configuration -- Pluggable DDS stack implementations via defined abstract interfaces +- Pluggable DDS stack implementations via defined abstract interfaces, + isolating DDS-stack-specific APIs from the DDS communication binding Reference DDS Gateway ~~~~~~~~~~~~~~~~~~~~~ From 8d27006ba01fa45d11c28e742c03789959462e67 Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Fri, 26 Jun 2026 11:06:18 +0200 Subject: [PATCH 07/17] Refactor DDS Binding section in documentation Removed redundant text in DDS Binding section. Signed-off-by: Abhishek GOYAL --- docs/features/communication/dds_gateway/index.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index b0f56b66824..61e8ae81591 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -70,8 +70,7 @@ DDS APIs, but its communication is transported over the DDS network. v | +---------------------+ +---------------------+ | DDS Binding | | DDS Binding | - | beneath mw::com | | beneath mw::com | - +----------+----------+ +----------+----------+ + +----------+----------+ +----------+----------+ | ^ | DDS | DDS v | From a66e598a0375c9255683762d7140cf0af4d39183 Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Fri, 26 Jun 2026 11:12:50 +0200 Subject: [PATCH 08/17] Improve clarity in DDS Gateway documentation Refactor text for clarity and formatting consistency in DDS Gateway documentation. Signed-off-by: Abhishek GOYAL --- .../features/communication/dds_gateway/index.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index 61e8ae81591..c7379df5c25 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -50,10 +50,9 @@ The DDS feature supports two integration concepts: Direct DDS Binding Concept ~~~~~~~~~~~~~~~~~~~~~~~~~~ -In this concept, an application uses the regular ``mw::com`` API and service -definition. The integrator selects DDS as the communication binding through -the service/deployment configuration. The application does not directly use -DDS APIs, but its communication is transported over the DDS network. +In this concept, an application uses the regular ``mw::com`` API.The integrator selects DDS as +the communication binding through the service/deployment configuration. +The application does not directly use DDS APIs, but its communication is transported over the DDS network. :: @@ -82,11 +81,12 @@ deserialization, creation of DDS communication entities, conversion between ``mw::com`` samples and DDS runtime data representation, DDS communication routing, QoS configuration, and interaction with the underlying DDS stack. +Communication is established by mapping mw::com events to DDS Topics. In DDS, a Topic represents a named communication channel associated with a -specific data type.The DDS binding maps ``mw::com`` events to DDS Topics and creates the -required DDS Topics, DataReaders and DataWriters from the deployment -configuration. DDS Domains provide communication isolation and may be used to separate -communication routes (for example, QM and ASIL communication). +specific data type.Based on the deployment configuration, the DDS binding +creates the required DDS Topics, DataReaders and DataWriters. DDS Domains +provide communication isolation and may be used to separate communication +routes (for example, QM and ASIL communication). Applications continue to use the standard ``mw::com`` programming model, while the selected binding transports the data over DDS. From dfe286cd68df50f5a287fdb5da65ee4b40688ef9 Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Fri, 26 Jun 2026 11:32:54 +0200 Subject: [PATCH 09/17] Fix formatting in DDS Gateway index.rst Removed extra line break in DDS Gateway documentation. Signed-off-by: Abhishek GOYAL --- docs/features/communication/dds_gateway/index.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index c7379df5c25..2e5a780de39 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -185,8 +185,7 @@ configured runtime type definitions - Support for standard DDS serialization encodings (e.g. XCDR1 and XCDR2) - True zero-generation workflow with no dependency on DDS IDL generation - Per-route DDS Quality of Service (QoS) configuration -- Pluggable DDS stack implementations via defined abstract interfaces, - isolating DDS-stack-specific APIs from the DDS communication binding +- Pluggable DDS stack implementations via defined abstract interfaces,isolating DDS-stack-specific APIs from the DDS communication binding Reference DDS Gateway ~~~~~~~~~~~~~~~~~~~~~ From 13fe00a9b6e13411c3ce8b9996ca1bc10b11c972 Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Fri, 26 Jun 2026 11:34:59 +0200 Subject: [PATCH 10/17] Fix formatting issue Signed-off-by: Abhishek GOYAL --- docs/features/communication/dds_gateway/index.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index 2e5a780de39..5a1ea559d64 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -178,10 +178,8 @@ It provides: - Support for configurable DDS domain-based routing - Runtime type definition via configuration (e.g. JSON) or dynamic library - Runtime creation of DDS entities (Topics, DataReaders and DataWriters) -- Runtime conversion between ``mw::com`` raw memory samples and the DDS runtime -data representation using runtime type definitions -- Runtime serialization and deserialization performed by the DDS binding using -configured runtime type definitions +- Runtime conversion between ``mw::com`` raw memory samples and the DDS runtime data representation using runtime type definitions +- Runtime serialization and deserialization performed by the DDS binding usingconfigured runtime type definitions - Support for standard DDS serialization encodings (e.g. XCDR1 and XCDR2) - True zero-generation workflow with no dependency on DDS IDL generation - Per-route DDS Quality of Service (QoS) configuration From 128b24aad85bec4ed84bc8c05f8e5a3548379d1e Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Wed, 15 Jul 2026 17:40:41 +0200 Subject: [PATCH 11/17] Enhance DDS Gateway documentation with detailed explanations Expanded the explanation of the DDS Gateway's functionality, including its role in translating between local mw::com communication and DDS-based communication, and detailed the service availability propagation process. Signed-off-by: Abhishek GOYAL --- .../communication/dds_gateway/index.rst | 285 ++++++++++++++++-- 1 file changed, 262 insertions(+), 23 deletions(-) diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index 5a1ea559d64..3c639e9bdf2 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -134,21 +134,55 @@ locally, while the gateway performs the translation and routing to DDS. | (optional) | +---------------------+ -The reference DDS Gateway is one such implementation built on top of the -DDS communication binding. The binding architecture also supports deployment -solutions without an explicit gateway process. +The DDS Gateway is a reference deployment concept for translating between +local ``mw::com (LoLa)`` communication and DDS-based communication. -Each DDS Gateway instance connects to: +A gateway deployment may separate the functionality responsible for local +``mw::com`` interaction from the functionality responsible for DDS stack +interaction. -- Local ``mw::com (LoLa)`` participants (IPC binding) -- A DDS domain for inter-ECU communication - -The gateway is responsible for: +:: -- Translating between ``mw::com (LoLa)`` and DDS communication -- Managing configurable translation routes -- Applying End-to-End (E2E) protection -- Scheduling translation through configurable worker queues (e.g., Mailbox and Queue policies) + +-------------------------+ + | Local mw::com | + | Applications | + +------------+------------+ + | + | mw::com (LoLa) + v + +--------------------------------------------+ + | Gateway Component | + | | + | - Local service model | + | - Runtime type handling | + | - Runtime Serialization / Deserialization | + | - E2E processing | + +------------+-------------------------------+ + | + | IPC + v + +--------------------------------+ + | DDS Communication | + | Component | + | | + | - DDS discovery | + | - DDS Topics | + | - DDS QoS | + | - DDS Stack interaction | + | - DDS publication and | + | subscription of serialized | + | payloads | + +------------+-------------------+ + | + | DDS + v + ================== + DDS NETWORK + ================== + +This separation allows deployments where DDS stack interaction is isolated +from local application interaction while preserving the standard +``mw::com (LoLa)`` programming model for local applications. Scope ----- @@ -172,16 +206,24 @@ It provides: - DDS deployment configuration extends the ``mw::com`` deployment configuration with DDS-specific attributes such as runtime type references, QoS policies and DDS Domain IDs - - Standard DDS endpoint discovery is used to determine the availability of - configured DDS endpoints and map this to the ``mw::com`` availability model - +- DDS endpoint and service discovery: + - Standard DDS discovery mechanisms are used to discover matching + DDS endpoints. + - Service availability is derived from the DDS endpoints associated + with a configured service instance. + - DDS endpoint availability is mapped to the corresponding + ``mw::com`` availability model. + - Availability changes resulting from DDS participant join, leave, + restart, or recovery are propagated through the ``mw::com`` availability model. - Support for configurable DDS domain-based routing - Runtime type definition via configuration (e.g. JSON) or dynamic library - Runtime creation of DDS entities (Topics, DataReaders and DataWriters) - Runtime conversion between ``mw::com`` raw memory samples and the DDS runtime data representation using runtime type definitions - Runtime serialization and deserialization performed by the DDS binding usingconfigured runtime type definitions - Support for standard DDS serialization encodings (e.g. XCDR1 and XCDR2) -- True zero-generation workflow with no dependency on DDS IDL generation +- No dependency on DDS-stack-specific IDL-generated application interfaces +- Runtime type definitions and E2E-related configuration may be generated + or manually maintained as part of the deployment configuration - Per-route DDS Quality of Service (QoS) configuration - Pluggable DDS stack implementations via defined abstract interfaces,isolating DDS-stack-specific APIs from the DDS communication binding @@ -198,10 +240,211 @@ It provides: - ``mw::com (LoLa)`` → DDS GW → DDS applications - DDS applications → DDS GW → ``mw::com (LoLa)`` +- Service availability propagation: + + - DDS endpoint discovery is performed by ``DDS Communication Component`` for the DDS Topics + associated with a configured service route. + + - The gateway configuration maps the discovered DDS Topics and endpoints to + the events of the corresponding ``mw::com`` service instance. + + - Service availability is derived from the configured DDS Topics associated + with the service instance. + + - Once the endpoints required for all configured DDS Topics are available, + ``DDS Communication Component`` exposes the corresponding inter-daemon route to ``Gateway Component``. + + - ``Gateway Component`` offers the corresponding local ``mw::com`` service only after + the inter-daemon route and the required DDS communication path are + available. + + - Loss of a required DDS endpoint causes ``DDS Communication Component`` to withdraw the + inter-daemon route. ``Gateway Component`` then withdraws the corresponding local + ``mw::com`` service availability. + + - Availability is restored automatically when the required DDS endpoints + and the inter-daemon communication route become available again. + +:: + + +------------------------------------------------------------+ + | DDS NETWORK | + +------------------------------------------------------------+ + | | | + | Topic A | Topic B | Topic C + | discovered | discovered | discovered + v v v + + +------------------------------------------------------------+ + | DDS Communication Component | + | | + | DDS endpoint discovery | + | Topic-to-service mapping | + | | + | All configured service events available? | + +--------------------------+---------------------------------+ + | + | Yes + | + | Offer inter-daemon route + v + + ==================== mw::com (LoLa IPC) ===================== + + +------------------------------------------------------------+ + | Gateway Component | + | | + | Discover inter-daemon route | + | Establish event subscriptions | + | | + | Offer local mw::com service | + +--------------------------+---------------------------------+ + | + | + v + + +------------------------------------------------------------+ + | Local mw::com Application | + +------------------------------------------------------------+ + + Availability loss propagates in the reverse direction: + + DDS endpoint lost + -> DDS Communication Component withdraws route + -> Gateway Component StopOfferService() + -> local service unavailable - End-to-End (E2E) protection: - - The translation layer performs generation and validation of Counter, CRC, and DataID - - Independent of the underlying DDS stack implementation - - Validation and protection configurable per route + + - E2E protection is implemented by the gateway translation layer and is + independent of the selected DDS stack implementation. + + - E2E generation and validation are performed by ``Gateway Component``. + ``DDS Communication Component`` and the DDS stack transport the resulting payload without + interpreting the E2E protection information. + + - E2E protection is configurable per communication route. + + - Routes may be configured with or without E2E protection according to + deployment requirements. + + - E2E protection information, including Counter, CRC, and DataID related + information, is associated with the application payload representation used for translation and is independent of DDS or RTPS transport headers. + + - The E2E representation is defined through configuration associated with + the runtime type description of the mapped ``mw::com`` event and DDS Topic. + + - Runtime type information may be provided through configuration or a + dynamically loaded type description. + + - No DDS-stack-specific IDL generated application interfaces are required + for E2E processing. + +- For outgoing communication: + + - ``Gateway Component`` reads the sample using the configured runtime type. + + - ``Gateway Component`` updates Counter, CRC, DataID and other configured + E2E elements. + + - ``Gateway Component`` serializes the payload using the configured runtime + type representation. + + - The serialized payload is forwarded to the + ``DDS Communication Component``. + + - The ``DDS Communication Component`` publishes the serialized payload + through the DDS stack. + +- For incoming communication: + + - The ``DDS Communication Component`` receives the serialized DDS payload. + + - The serialized payload is forwarded to the + ``Gateway Component``. + + - ``Gateway Component`` performs deserialization using the configured + runtime type representation. + + - ``Gateway Component`` validates the configured E2E information before + delivering the sample to the local application. + + - Samples failing E2E validation are handled according to the configured + route policy. + +:: + + Outgoing direction + + +----------------------------+ + | Local mw::com Sample | + +-------------+--------------+ + | + v + +----------------------------+ + | Gateway Component | + | | + | Runtime type handling | + | Update Counter | + | Update CRC | + | Update DataID | + | Serialize payload | + +-------------+--------------+ + | + | Serialized payload + v + + ================= LoLa IPC ================= + + | + v + + +-------------------------------+ + | DDS Communication Component | + | | + | DDS discovery | + | DDS Topics | + | DDS write_cdr() | + +-------------+-----------------+ + | + v + + DDS NETWORK + + + Incoming direction + + DDS NETWORK + | + v + + +-------------------------------+ + | DDS Communication Component | + | | + | DDS read_cdr() | + +-------------+-----------------+ + | + | Serialized payload + v + + ================= LoLa IPC ================= + + | + v + + +----------------------------+ + | Gateway Component | + | | + | Deserialize payload | + | Validate Counter | + | Validate CRC | + | Validate DataID | + +-------------+--------------+ + | + v + + +----------------------------+ + | Local mw::com Sample | + +----------------------------+ - Execution and performance model: @@ -260,10 +503,6 @@ Key Value (e.g., 32-bit / 64-bit, different endianness) - Ensures consistent data representation via Dynamic Type handling -- End-to-End (E2E) protection: - - The translation layer performs generation and validation of Counter, CRC, and DataID - - Independent of the underlying DDS stack implementation - - Validation and protection configurable per route Reference --------- From 67f446355e67507b4b73e8c6e32378be0b2785bb Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Wed, 15 Jul 2026 19:37:11 +0200 Subject: [PATCH 12/17] Update DDS communication component terminology Signed-off-by: Abhishek GOYAL --- docs/features/communication/dds_gateway/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index 3c639e9bdf2..5231c519522 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -403,7 +403,7 @@ It provides: | | | DDS discovery | | DDS Topics | - | DDS write_cdr() | + | DDS serialized data sending | +-------------+-----------------+ | v @@ -420,7 +420,7 @@ It provides: +-------------------------------+ | DDS Communication Component | | | - | DDS read_cdr() | + | DDS serialized Data receiving | +-------------+-----------------+ | | Serialized payload From b83d0fc452bc754db3b1ff30033c2cd69650fab6 Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Wed, 22 Jul 2026 17:17:31 +0200 Subject: [PATCH 13/17] Address review comments for DDS service discovery and E2E design --- .../dds_gateway/architecture/index.rst | 588 +++++++++++++++++ .../communication/dds_gateway/e2e/index.rst | 229 +++++++ .../communication/dds_gateway/index.rst | 607 +++++------------ .../dds_gateway/requirements/index.rst | 460 +++++++++++++ .../dds_gateway/service_discovery/index.rst | 612 ++++++++++++++++++ .../dds_gateway/use_cases/index.rst | 298 +++++++++ 6 files changed, 2352 insertions(+), 442 deletions(-) create mode 100644 docs/features/communication/dds_gateway/architecture/index.rst create mode 100644 docs/features/communication/dds_gateway/e2e/index.rst create mode 100644 docs/features/communication/dds_gateway/requirements/index.rst create mode 100644 docs/features/communication/dds_gateway/service_discovery/index.rst create mode 100644 docs/features/communication/dds_gateway/use_cases/index.rst diff --git a/docs/features/communication/dds_gateway/architecture/index.rst b/docs/features/communication/dds_gateway/architecture/index.rst new file mode 100644 index 00000000000..c840949cd9b --- /dev/null +++ b/docs/features/communication/dds_gateway/architecture/index.rst @@ -0,0 +1,588 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +.. _dds_binding_gateway_architecture: + +DDS Binding and Gateway Architecture +#################################### + +Overview +======== + +This feature introduces two DDS integration concepts: + +* a DDS Binding beneath ``mw::com``; and +* a DDS Gateway between LoLa and DDS. + +The DDS Binding is used when DDS is selected as the communication binding of an +``mw::com`` application. + +The DDS Gateway is used when an existing application remains on LoLa and +configured LoLa services shall be forwarded to or received from DDS. + +Both deployment concepts reuse the same DDS Communication Daemon. + +The DDS Communication Daemon contains the DDS network-facing functionality, +including the selected DDS stack, DDS discovery, DDS Domains, Topics, +DataReaders, DataWriters, and QoS handling. + +The DDS Binding and DDS Gateway communicate with the DDS Communication Daemon +through runtime inter-process communication. + +This process boundary allows the DDS stack to remain outside the +application-facing process. This is especially relevant when the DDS Binding or +DDS Gateway executes in an ASIL context while the selected DDS stack is +available as a QM component. + +Context View +============ + +The feature supports: + +#. Direct DDS Binding deployment. +#. LoLa application with DDS Gateway deployment. + +The DDS Gateway is not an additional ``mw::com`` binding. + +It is a separately deployed process that communicates with local applications +through LoLa and with the DDS Communication Daemon through runtime IPC. + +Direct DDS Binding Deployment +============================= + +In this deployment, DDS is selected as the ``mw::com`` communication binding. + +The application continues to use the standard ``mw::com`` API. + +The DDS Binding performs the application-side adaptation between ``mw::com`` +and DDS. The DDS stack remains in the separately deployed DDS Communication +Daemon. + +:: + + ============================== + ECU + ============================== + + +------------------------------------------------+ + | Application Process | + | | + | +------------------------------------------+ | + | | mw::com Application | | + | +--------------------+---------------------+ | + | | | + | mw::com API | + | | | + | +--------------------v---------------------+ | + | | DDS Binding | | + | | | | + | | - mw::com service adaptation | | + | | - Runtime type handling | | + | | - Serialization / deserialization | | + | | - Route mapping | | + | | - Availability-policy evaluation | | + | | - Configured E2E processing | | + | +--------------------+---------------------+ | + +-----------------------|------------------------+ + | + | Runtime IPC + v + +------------------------------------------------+ + | DDS Communication Daemon Process | + | | + | - DDS discovery and endpoint matching | + | - Route-state tracking | + | - DDS Domains and Topics | + | - DataReaders / DataWriters | + | - DDS QoS | + | - DDS stack processing and RTPS message handling | + | - DDS stack abstraction | + | - DDS stack | + +-----------------------+------------------------+ + | + DDS / RTPS + | + DDS Network + +Direct DDS Binding Responsibilities +----------------------------------- + +The DDS Binding is responsible for: + +* exposing the standard ``mw::com`` programming model; +* mapping configured ``mw::com`` events to DDS communication routes; +* runtime type handling; +* conversion and serialization between ``mw::com`` samples and the configured + DDS serialized representation; +* configured E2E Protect and E2E Check processing; +* runtime communication-route handling; +* evaluation of the configured service-availability policy; and +* propagation of the resulting state into the ``mw::com`` availability model. + +Gateway Deployment +================== + +In this deployment, the application remains configured with the LoLa Binding. + +The DDS Gateway is deployed as a separate process. + +The Gateway communicates with local applications through LoLa IPC and with the +DDS Communication Daemon through runtime IPC. + +:: + + ============================== + ECU + ============================== + + +------------------------------------------------+ + | Application Process | + | | + | +------------------------------------------+ | + | | mw::com Application | | + | +--------------------+---------------------+ | + | | | + | mw::com API | + | | | + | +--------------------v---------------------+ | + | | LoLa Binding | | + | +--------------------+---------------------+ | + +-----------------------|------------------------+ + | + | LoLa IPC + v + +------------------------------------------------+ + | DDS Gateway Process | + | | + | - Generic Proxy / Generic Skeleton | + | - LoLa service interaction | + | - Route translation | + | - Runtime type handling | + | - Serialization / deserialization | + | - Availability-policy evaluation | + | - Configured E2E processing | + +-----------------------+------------------------+ + | + | Runtime IPC + v + +------------------------------------------------+ + | DDS Communication Daemon Process | + | | + | - DDS discovery and endpoint matching | + | - Route-state tracking | + | - DDS Domains and Topics | + | - DataReaders / DataWriters | + | - DDS QoS | + | - DDS stack abstraction and DDS stack | + +-----------------------+------------------------+ + | + DDS / RTPS + | + DDS Network + +Gateway Responsibilities +------------------------ + +The DDS Gateway is responsible for: + +* discovering configured local LoLa services; +* creating Generic Proxies for locally provided services; +* creating Generic Skeletons for remotely provided DDS services; +* mapping configured LoLa events to DDS route identifiers; +* mapping received DDS route identifiers to LoLa events; +* runtime type handling; +* conversion and serialization between LoLa samples and the configured DDS + serialized representation; +* configured E2E Protect and E2E Check processing; +* evaluation of the configured service-availability policy; +* offering or withdrawing mapped local services; and +* forwarding runtime data between LoLa and the DDS Communication Daemon. + +Relationship Between DDS Binding and DDS Gateway +================================================ + +The DDS Binding and DDS Gateway serve different deployment scenarios. + +The DDS Binding is part of an application process when DDS is selected as the +application's ``mw::com`` binding. + +The DDS Gateway is a separate process used when the application remains on +LoLa. + +Both communicate with the same DDS Communication Daemon through runtime IPC. + +:: + + +-----------------------------+ + | DDS Communication Daemon | + | | + | DDS stack and DDS runtime | + +-------------+---------------+ + ^ + | + IPC | IPC + | + +--------------------+--------------------+ + | | + +-------+--------+ +--------+-------+ + | DDS Binding | | DDS Gateway | + | | | | + | Application | | Separate | + | process | | process | + +----------------+ +----------------+ + +The DDS Binding and DDS Gateway may reuse common application-facing +infrastructure, including: + +* the daemon communication protocol; +* the route-identification model; +* the serialized data-transfer mechanism; +* runtime type and serialization utilities; and +* the discovery and availability-notification model. + +DDS DomainParticipants, Topics, DataReaders, DataWriters, QoS, and the selected +DDS stack are owned and managed only by the DDS Communication Daemon. + +DDS Communication Daemon +======================== + +The DDS Communication Daemon is responsible for: + +* integration of the selected DDS stack; +* creation and management of DDS DomainParticipants; +* creation and management of DDS Topics; +* creation and management of DDS DataReaders and DataWriters; +* DDS participant and endpoint discovery; +* DDS endpoint matching; +* tracking configured communication-route state; +* transmission and reception of explicit service state where configured; +* DDS QoS handling; +* submission and reception of serialized DDS samples; +* runtime IPC notifications; +* resource management; and +* reporting DDS-related runtime errors. +The DDS Communication Daemon may serve: + +* multiple applications using the DDS Binding; +* the DDS Gateway process; or +* a combination of DDS Binding applications and the DDS Gateway. + +:: + + Application A / DDS Binding --\ + \ + Application B / DDS Binding ----+--> DDS Communication Daemon + / + DDS Gateway -------------------/ + +Configuration Model +=================== + +The DDS integration extends the existing ``mw::com`` deployment configuration +model. + +Existing ``mw::com`` service-type and service-instance information remains the +basis of the application-facing model. + +DDS-specific deployment information supplements it with: + +* DDS Domain; +* DDS Topic; +* DDS data type; +* communication direction; +* DDS QoS; +* service-availability policy; and +* optional E2E information. + +The DDS Binding, DDS Gateway, and DDS Communication Daemon may consume separate +but mutually consistent configuration artifacts. + +Configuration is not exchanged through runtime IPC. + +DDS Communication Route +----------------------- + +A configured DDS communication route associates an existing ``mw::com`` event +with the corresponding DDS communication information. + +The configuration shall provide sufficient information to identify: + +* the ``mw::com`` service type; +* the service version; +* the service instance; +* the event; +* the DDS Domain; +* the DDS Topic; +* the DDS data type; +* the communication direction; and +* the applicable DDS QoS. + +The configuration may additionally provide information for service-availability +evaluation, explicit service-state communication, E2E handling, and +communication prioritization. + +Event-to-Topic Mapping +---------------------- + +Each ``mw::com`` event configured for DDS communication is mapped to a DDS +Topic. + +The mapping shall be deterministic and unambiguous. + +The Topic name may be explicitly configured or derived according to an +implementation-defined deterministic convention. + +This feature request does not prescribe one mandatory Topic naming convention. + +DDS Type Configuration +---------------------- + +Each DDS-enabled ``mw::com`` event shall reference sufficient runtime type +information for: + +* DDS entity creation; +* serialization; +* deserialization; +* compatibility validation; and +* native DDS interoperability. + +The ``mw::com`` application itself is not required to use a DDS-generated API. + +DDS Domain Configuration +------------------------ + +Each DDS communication route shall be associated with a DDS Domain identifier. + +Different configured routes may use different DDS Domains. + +DDS QoS Configuration +--------------------- + +The DDS deployment information shall provide the QoS required by each +configured communication route. + +The supported QoS policies depend on the selected DDS stack and implementation. + +Component-Specific Configuration +-------------------------------- + +The DDS Binding may require: + +* application-facing event-to-route mapping; +* runtime type information; +* serialization and deserialization information; +* route identification; +* service-availability policy; +* E2E configuration; and +* application-facing availability mapping. + +The DDS Gateway may require: + +* LoLa-to-DDS and DDS-to-LoLa routes; +* Generic Proxy and Generic Skeleton deployment information; +* runtime type information; +* route identification; +* service-availability policy and mapping; and +* E2E configuration. + +The DDS Communication Daemon may require: + +* DDS Domain configuration; +* DDS Topic identities; +* DDS type information; +* endpoint direction; +* QoS configuration; +* explicit service-state route information where configured; and +* identifiers associating IPC traffic with configured DDS entities. + +Configuration Validation +------------------------ + +Invalid or inconsistent deployment information shall be detected before the +affected route or availability policy becomes operational. + +Validation shall include, where applicable: + +* unresolved service types, instances, or events; +* missing or incompatible DDS type information; +* invalid DDS Domain or QoS configuration; +* duplicate or ambiguous Topic mappings; +* conflicting route definitions; +* missing communication direction; +* invalid service-availability policies; +* references to unknown availability routes; and +* inconsistent component-specific configuration. + +Runtime IPC +=========== + +Runtime IPC carries: + +* serialized DDS payloads; +* communication-route identifiers; +* communication-route state notifications; +* local and remote service-instance state; +* lifecycle notifications; and +* runtime errors. + +Runtime IPC does not carry deployment configuration. + +The IPC protocol, message format, buffer mechanism, and IPC technology are +implementation-specific. + +Why IPC Is Used +=============== + +The DDS Binding or DDS Gateway may execute in an ASIL context while the selected +DDS stack is available as a QM component. + +The DDS Communication Daemon creates a process boundary between the +application-facing communication component and the DDS stack. + +The complete freedom-from-interference argument remains deployment-specific. + +Data Flow Overview +================== + +DDS Binding Publish +------------------- + +:: + + mw::com Application + | + v + DDS Binding + | + | conversion and serialization + | configured E2E Protect + v + Runtime IPC + | + v + DDS Communication Daemon + | + v + DDS Network + +DDS Binding Receive +------------------- + +:: + + DDS Network + | + v + DDS Communication Daemon + | + v + Runtime IPC + | + v + DDS Binding + | + | configured E2E Check + | deserialization + v + mw::com Application + +Gateway Publish +--------------- + +:: + + Local mw::com Producer + | + v + DDS Gateway Generic Proxy + | + | conversion and serialization + | configured E2E Protect + v + Runtime IPC + | + v + DDS Communication Daemon + | + v + DDS Network + +Gateway Receive +--------------- + +:: + + DDS Network + | + v + DDS Communication Daemon + | + v + Runtime IPC + | + v + DDS Gateway + | + | configured E2E Check + | deserialization + v + Generic Skeleton / LoLa IPC + | + v + Local mw::com Consumer + +Discovery and Availability +========================== + +DDS discovery is performed only by the DDS Communication Daemon through the DDS +stack. + +The daemon tracks configured DDS communication-route state and communicates +relevant changes through runtime IPC. + +The DDS Binding or DDS Gateway evaluates the configured service-availability +policy. + +The policy may use route state, explicit service-instance state, or both. + +Detailed behavior is defined in +:ref:`dds_binding_gateway_service_discovery`. + +E2E Considerations +================== + +The DDS Binding or DDS Gateway performs configured application-level E2E +processing on the serialized application-data representation. + +The DDS Communication Daemon transports the serialized payload and does not +perform E2E Protect, E2E Check, or application-specific acceptance decisions. + +Detailed E2E behavior is defined in +:ref:`dds_binding_gateway_e2e`. + +Implementation Considerations +============================= + +This architecture does not prescribe: + +* the internal IPC protocol; +* the number of IPC channels; +* the queue or worker model; +* the shared-memory layout; +* the buffer-allocation strategy; +* the configuration-file format; +* the configuration-generation mechanism; +* the Topic naming convention; +* one mandatory representation for explicit service state; +* DDS entity-creation time; or +* the selected DDS stack. diff --git a/docs/features/communication/dds_gateway/e2e/index.rst b/docs/features/communication/dds_gateway/e2e/index.rst new file mode 100644 index 00000000000..227b89b55ac --- /dev/null +++ b/docs/features/communication/dds_gateway/e2e/index.rst @@ -0,0 +1,229 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +.. _dds_binding_gateway_e2e: + +DDS E2E Considerations +###################### + +Overview +======== + +End-to-End (E2E) protection is optional and is enabled through deployment +configuration for the communication routes that require it. + +When E2E protection is not configured for a route, the route operates without +E2E Protect or E2E Check processing. + +When E2E protection is configured, the DDS Binding or DDS Gateway performs the +per-sample E2E processing. The DDS Communication Daemon and the DDS stack do +not perform application-level E2E processing. + +E2E Processing Boundary +======================= + +E2E Protect and E2E Check operate on the configured serialized representation +of the application data. + +The protected data does not include DDS or RTPS protocol headers, transport +headers, discovery data, or other metadata generated by the DDS stack. + +The serialized representation, the E2E profile, and the placement of any +transmitted E2E fields shall be consistently defined for all publishers and +subscribers of the communication route. + +Direct DDS Binding Deployment +============================= + +For direct DDS Binding deployment, the DDS Binding performs the configured +per-sample E2E processing. + +Outgoing Communication +---------------------- + +For an outgoing sample, the DDS Binding: + +#. converts and serializes the ``mw::com`` sample into the configured DDS + application-data representation; +#. performs the configured E2E Protect operation on that serialized + representation; and +#. forwards the protected serialized payload and route identifier to the DDS + Communication Daemon. + +Incoming Communication +---------------------- + +For an incoming sample, the DDS Binding: + +#. receives the protected serialized payload and route identifier from the DDS + Communication Daemon; +#. performs the configured E2E Check operation on the serialized + representation; +#. deserializes the application data into an ``mw::com`` sample; and +#. provides the sample together with the per-sample E2E result to the + application. + +DDS Gateway Deployment +====================== + +For DDS Gateway deployment, the DDS Gateway performs the configured per-sample +E2E processing. + +Outgoing Communication +---------------------- + +For an outgoing LoLa sample, the DDS Gateway: + +#. converts and serializes the sample into the configured DDS application-data + representation; +#. performs the configured E2E Protect operation on that serialized + representation; and +#. forwards the protected serialized payload and route identifier to the DDS + Communication Daemon. + +Incoming Communication +---------------------- + +For an incoming DDS sample, the DDS Gateway: + +#. receives the protected serialized payload and route identifier from the DDS + Communication Daemon; +#. performs the configured E2E Check operation on the serialized + representation; +#. deserializes the application data into the corresponding LoLa sample; and +#. provides the sample together with the per-sample E2E result to the local + ``mw::com`` consumer. + +DDS Communication Daemon +======================== + +The DDS Communication Daemon transports serialized application payloads +between the DDS Binding or DDS Gateway and the selected DDS stack. + +When E2E protection is enabled, the daemon transports the protected serialized +payload without interpreting or modifying its application-level E2E content. + +The DDS Communication Daemon does not perform: + +* E2E Protect; +* E2E Check; +* application-level E2E state-machine processing; or +* application-specific acceptance decisions. + +E2E Result Interface +==================== + +The DDS Binding or DDS Gateway performs an E2E Check for every received sample. + +The result of the E2E Check is associated with that individual sample. + +The DDS Binding or DDS Gateway forwards the received sample together with the +corresponding E2E result to the receiving ``mw::com`` application. + +The E2E result provides sufficient information for the receiving application, +or its application-facing communication support, to update the configured E2E +state machine and evaluate communication health according to its own safety +requirements. + +The exact representation of the E2E result is implementation-specific. + +E2E State Machine +================= + +The E2E state machine is outside the scope of the DDS Binding and DDS Gateway. + +The E2E Check evaluates the integrity of a single received sample. The E2E +state machine evaluates the health of the communication channel over multiple +received samples. + +The DDS Binding or DDS Gateway therefore performs only the per-sample E2E +Check and forwards the received sample together with its corresponding E2E +result. + +The receiving application, or its application-facing communication support, +uses this information to update its configured E2E state machine and determine +whether the received data may be accepted. + +The E2E state machine is associated with the receiving consumer because +different consumers of the same published sample may require different +state-machine configurations or different acceptance policies. + +Consequently, the E2E state machine is maintained independently by each +receiving application and is not maintained centrally by the DDS Binding or +DDS Gateway. +:: + + DDS Sample + | + | E2E Check + v + +---------------------------+ + | DDS Binding / DDS Gateway | + +---------------------------+ + | + | Sample + + | E2E Result + v + +---------------------------+ + | Receiving mw::com | + | Application | + +---------------------------+ + | + | Update local + | E2E State Machine + v + +---------------------------+ + | Communication State | + | | + | • Healthy | + | • Degraded | + | • Invalid | + +---------------------------+ + | + | Application + | acceptance policy + v + Use / Reject Data + +E2E Configuration +================= + +E2E processing is enabled or disabled per configured communication route. + +For an E2E-enabled route, the deployment configuration shall identify the +information required to apply the selected E2E profile consistently, including +where applicable: + +* the E2E profile; +* the Data ID; +* the counter behavior; +* the CRC parameters; +* the location and size of transmitted E2E fields; and +* the information required to interpret the per-sample E2E result. + +The exact configuration schema is implementation-specific. + +Implementation Considerations +============================= + +This feature request does not prescribe: + +* a mandatory E2E profile; +* the binary layout of E2E fields; +* the representation of the per-sample E2E result; +* the implementation of the consumer E2E state machine; +* application-specific acceptance criteria; or +* the detailed E2E configuration format. + +The E2E design described in this chapter currently applies to event-based +communication. diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index 5231c519522..b49a6ac5258 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -1,6 +1,6 @@ .. # ******************************************************************************* - # Copyright (c) 2024 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,11 +12,13 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _dds_binding_gateway_feature: + DDS Binding and Gateway -======================= +####################### -.. document:: DDS-Gateway - :id: doc__dds_gateway +.. document:: DDS Binding and Gateway + :id: doc__dds_binding_gateway :status: valid :safety: ASIL_B :tags: contribution_request, feature_request @@ -24,489 +26,210 @@ DDS Binding and Gateway :realizes: wp__feat_request -Overview --------- -This feature introduces DDS communication support for ``mw::com`` and a -reference DDS Gateway implementation. - -DDS communication is provided as a binding beneath ``mw::com``. This allows -applications to use the ``mw::com`` abstraction while the communication is -transported over a DDS network, based on the service and deployment -configuration selected by the integrator. - -In addition, the DDS Gateway provides a reference translation concept between -local ``mw::com (LoLa)`` communication and DDS-based inter-ECU communication. -It enables controlled and configurable data exchange between intra-ECU -``mw::com (LoLa)`` participants and DDS-based systems while preserving -existing application implementations. - -Architecture Concept --------------------- - -The DDS feature supports two integration concepts: - -- Direct DDS binding usage beneath ``mw::com`` -- Reference DDS Gateway based translation - -Direct DDS Binding Concept -~~~~~~~~~~~~~~~~~~~~~~~~~~ -In this concept, an application uses the regular ``mw::com`` API.The integrator selects DDS as -the communication binding through the service/deployment configuration. -The application does not directly use DDS APIs, but its communication is transported over the DDS network. - -:: - - ============================== ============================== - ECU 1 ECU 2 - ============================== ============================== - - +-------------------------+ +-------------------------+ - | Application A | | Application B | - | (mw::com) | | (mw::com) | - +-----------+-------------+ +-----------+-------------+ - | ^ - | mw::com API | mw::com API - v | - +---------------------+ +---------------------+ - | DDS Binding | | DDS Binding | - +----------+----------+ +----------+----------+ - | ^ - | DDS | DDS - v | - =================== DDS NETWORK =================== - -The DDS binding provides the DDS communication layer beneath ``mw::com``. -It is responsible for runtime type handling, runtime serialization and -deserialization, creation of DDS communication entities, conversion between -``mw::com`` samples and DDS runtime data representation, DDS communication -routing, QoS configuration, and interaction with the underlying DDS stack. - -Communication is established by mapping mw::com events to DDS Topics. -In DDS, a Topic represents a named communication channel associated with a -specific data type.Based on the deployment configuration, the DDS binding -creates the required DDS Topics, DataReaders and DataWriters. DDS Domains -provide communication isolation and may be used to separate communication -routes (for example, QM and ASIL communication). - -Applications continue to use the standard ``mw::com`` programming model, -while the selected binding transports the data over DDS. -The application programming model remains unchanged. Publishers and subscribers -continue to allocate and populate typed ``mw::com`` samples, while the DDS -binding performs the conversion to the DDS data representation and interacts -with the underlying DDS stack. - -Reference DDS Gateway Concept -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The DDS Gateway is a reference implementation that demonstrates one possible -translation concept between local ``mw::com (LoLa)`` communication and DDS -domains. In this concept, the applications continue to use ``mw::com (LoLa)`` -locally, while the gateway performs the translation and routing to DDS. - -:: - - ============================== ============================== - ECU 1 ECU 2 - ============================== ============================== - - +-------------------------+ +-------------------------+ - | Application A | | Application B | - | (mw::com LoLa) | | (mw::com LoLa) | - +-----------+-------------+ +-----------+-------------+ - | ^ - | mw::com (LoLa - IPC) | mw::com (LoLa - IPC) - v | - +---------------------+ +---------------------+ - | DDS Gateway | | DDS Gateway | - | (ECU 1) | | (ECU 2) | - +----------+----------+ +----------+----------+ - | ^ - | | - v | - =================== DDS NETWORK =================== - | ^ - ============================== | - ECU 3 | - ============================== | - | | - v | - +---------------------+ | - | DDS Application |--------------------------+ - | (optional) | - +---------------------+ - -The DDS Gateway is a reference deployment concept for translating between -local ``mw::com (LoLa)`` communication and DDS-based communication. - -A gateway deployment may separate the functionality responsible for local -``mw::com`` interaction from the functionality responsible for DDS stack -interaction. - -:: - - +-------------------------+ - | Local mw::com | - | Applications | - +------------+------------+ - | - | mw::com (LoLa) - v - +--------------------------------------------+ - | Gateway Component | - | | - | - Local service model | - | - Runtime type handling | - | - Runtime Serialization / Deserialization | - | - E2E processing | - +------------+-------------------------------+ - | - | IPC - v - +--------------------------------+ - | DDS Communication | - | Component | - | | - | - DDS discovery | - | - DDS Topics | - | - DDS QoS | - | - DDS Stack interaction | - | - DDS publication and | - | subscription of serialized | - | payloads | - +------------+-------------------+ - | - | DDS - v - ================== - DDS NETWORK - ================== - -This separation allows deployments where DDS stack interaction is isolated -from local application interaction while preserving the standard -``mw::com (LoLa)`` programming model for local applications. - -Scope ------ - -This feature provides: - -DDS Communication Binding -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The DDS communication binding provides DDS communication beneath ``mw::com``. - -It provides: - -- Communication between ``mw::com`` applications over DDS using the standard - ``mw::com`` programming model - -- Configuration-driven mapping between ``mw::com`` and DDS: - - - Each ``mw::com`` event is mapped to one DDS Topic - - DDS Topic data is mapped back to the corresponding ``mw::com`` event - - DDS deployment configuration extends the ``mw::com`` deployment - configuration with DDS-specific attributes such as runtime type references, - QoS policies and DDS Domain IDs -- DDS endpoint and service discovery: - - Standard DDS discovery mechanisms are used to discover matching - DDS endpoints. - - Service availability is derived from the DDS endpoints associated - with a configured service instance. - - DDS endpoint availability is mapped to the corresponding - ``mw::com`` availability model. - - Availability changes resulting from DDS participant join, leave, - restart, or recovery are propagated through the ``mw::com`` availability model. -- Support for configurable DDS domain-based routing -- Runtime type definition via configuration (e.g. JSON) or dynamic library -- Runtime creation of DDS entities (Topics, DataReaders and DataWriters) -- Runtime conversion between ``mw::com`` raw memory samples and the DDS runtime data representation using runtime type definitions -- Runtime serialization and deserialization performed by the DDS binding usingconfigured runtime type definitions -- Support for standard DDS serialization encodings (e.g. XCDR1 and XCDR2) -- No dependency on DDS-stack-specific IDL-generated application interfaces -- Runtime type definitions and E2E-related configuration may be generated - or manually maintained as part of the deployment configuration -- Per-route DDS Quality of Service (QoS) configuration -- Pluggable DDS stack implementations via defined abstract interfaces,isolating DDS-stack-specific APIs from the DDS communication binding - -Reference DDS Gateway -~~~~~~~~~~~~~~~~~~~~~ - -The DDS Gateway is the reference implementation for translating between -``mw::com (LoLa)`` and DDS. - -It provides: - -- Bridging between ``mw::com (LoLa)`` and DDS: - - ``mw::com (LoLa)`` → DDS GW → ``mw::com (LoLa)`` - - ``mw::com (LoLa)`` → DDS GW → DDS applications - - DDS applications → DDS GW → ``mw::com (LoLa)`` - -- Service availability propagation: - - - DDS endpoint discovery is performed by ``DDS Communication Component`` for the DDS Topics - associated with a configured service route. - - - The gateway configuration maps the discovered DDS Topics and endpoints to - the events of the corresponding ``mw::com`` service instance. - - - Service availability is derived from the configured DDS Topics associated - with the service instance. - - - Once the endpoints required for all configured DDS Topics are available, - ``DDS Communication Component`` exposes the corresponding inter-daemon route to ``Gateway Component``. - - - ``Gateway Component`` offers the corresponding local ``mw::com`` service only after - the inter-daemon route and the required DDS communication path are - available. - - - Loss of a required DDS endpoint causes ``DDS Communication Component`` to withdraw the - inter-daemon route. ``Gateway Component`` then withdraws the corresponding local - ``mw::com`` service availability. - - - Availability is restored automatically when the required DDS endpoints - and the inter-daemon communication route become available again. - -:: - - +------------------------------------------------------------+ - | DDS NETWORK | - +------------------------------------------------------------+ - | | | - | Topic A | Topic B | Topic C - | discovered | discovered | discovered - v v v +.. toctree:: + :hidden: - +------------------------------------------------------------+ - | DDS Communication Component | - | | - | DDS endpoint discovery | - | Topic-to-service mapping | - | | - | All configured service events available? | - +--------------------------+---------------------------------+ - | - | Yes - | - | Offer inter-daemon route - v - - ==================== mw::com (LoLa IPC) ===================== - - +------------------------------------------------------------+ - | Gateway Component | - | | - | Discover inter-daemon route | - | Establish event subscriptions | - | | - | Offer local mw::com service | - +--------------------------+---------------------------------+ - | - | - v - - +------------------------------------------------------------+ - | Local mw::com Application | - +------------------------------------------------------------+ - - Availability loss propagates in the reverse direction: - - DDS endpoint lost - -> DDS Communication Component withdraws route - -> Gateway Component StopOfferService() - -> local service unavailable -- End-to-End (E2E) protection: + architecture/index.rst + requirements/index.rst + service_discovery/index.rst + e2e/index.rst + use_cases/index.rst - - E2E protection is implemented by the gateway translation layer and is - independent of the selected DDS stack implementation. - - E2E generation and validation are performed by ``Gateway Component``. - ``DDS Communication Component`` and the DDS stack transport the resulting payload without - interpreting the E2E protection information. +Feature Flag +============ - - E2E protection is configurable per communication route. +To activate this feature, use the implementation-specific DDS Binding or DDS +Gateway feature configuration. - - Routes may be configured with or without E2E protection according to - deployment requirements. - - E2E protection information, including Counter, CRC, and DataID related - information, is associated with the application payload representation used for translation and is independent of DDS or RTPS transport headers. +Abstract +======== - - The E2E representation is defined through configuration associated with - the runtime type description of the mapped ``mw::com`` event and DDS Topic. +This feature introduces DDS communication into the ``mw::com`` ecosystem +through two complementary deployment concepts: - - Runtime type information may be provided through configuration or a - dynamically loaded type description. +* DDS Binding beneath ``mw::com``; and +* DDS Gateway between LoLa and DDS. - - No DDS-stack-specific IDL generated application interfaces are required - for E2E processing. +The DDS Binding allows applications to use DDS while preserving the standard +``mw::com`` concepts. -- For outgoing communication: - - - ``Gateway Component`` reads the sample using the configured runtime type. - - - ``Gateway Component`` updates Counter, CRC, DataID and other configured - E2E elements. - - - ``Gateway Component`` serializes the payload using the configured runtime - type representation. - - - The serialized payload is forwarded to the - ``DDS Communication Component``. - - - The ``DDS Communication Component`` publishes the serialized payload - through the DDS stack. - -- For incoming communication: +The DDS Gateway enables existing LoLa-based applications to communicate with +DDS without changing their application-facing API. - - The ``DDS Communication Component`` receives the serialized DDS payload. - - - The serialized payload is forwarded to the - ``Gateway Component``. +Both deployment concepts reuse a common DDS Communication Daemon containing the +selected DDS stack and DDS network-facing functionality. - - ``Gateway Component`` performs deserialization using the configured - runtime type representation. +The DDS Binding or DDS Gateway communicates with the DDS Communication Daemon +through runtime IPC, allowing deployments where the application-facing +communication component executes in an ASIL context while the DDS stack remains +a QM component. - - ``Gateway Component`` validates the configured E2E information before - delivering the sample to the local application. - - - Samples failing E2E validation are handled according to the configured - route policy. - -:: - Outgoing direction +Motivation +========== - +----------------------------+ - | Local mw::com Sample | - +-------------+--------------+ - | - v - +----------------------------+ - | Gateway Component | - | | - | Runtime type handling | - | Update Counter | - | Update CRC | - | Update DataID | - | Serialize payload | - +-------------+--------------+ - | - | Serialized payload - v +DDS is widely used in automotive systems requiring scalable publish-subscribe +communication, configurable Quality of Service (QoS), runtime discovery, and +interoperability with native DDS participants. - ================= LoLa IPC ================= +Applications using ``mw::com`` shall remain independent of the selected +communication technology. - | - v +This feature therefore introduces DDS support while preserving the existing +``mw::com`` programming model. - +-------------------------------+ - | DDS Communication Component | - | | - | DDS discovery | - | DDS Topics | - | DDS serialized data sending | - +-------------+-----------------+ - | - v +The feature provides: - DDS NETWORK +* DDS Binding beneath ``mw::com``; +* DDS Gateway for existing LoLa applications; +* runtime DDS type handling; +* configuration-driven mapping between ``mw::com`` events and DDS Topics; +* configurable DDS Domains and QoS; +* configurable service availability mapping; +* configurable End-to-End (E2E) processing; and +* architectural separation between the application-facing communication + component and the DDS stack where required by the deployment safety concept. - Incoming direction +Rationale +========= - DDS NETWORK - | - v +DDS Binding and DDS Gateway address different deployment scenarios. - +-------------------------------+ - | DDS Communication Component | - | | - | DDS serialized Data receiving | - +-------------+-----------------+ - | - | Serialized payload - v +The DDS Binding provides native DDS communication beneath ``mw::com`` while +preserving the existing application programming model. - ================= LoLa IPC ================= +The DDS Gateway enables existing LoLa deployments to communicate with DDS +and vice-versa where DDS application communicate with LoLa applications +without changing their configured communication binding. - | - v +Both deployment concepts reuse the same DDS Communication Daemon and DDS stack +integration. - +----------------------------+ - | Gateway Component | - | | - | Deserialize payload | - | Validate Counter | - | Validate CRC | - | Validate DataID | - +-------------+--------------+ - | - v +DDS-specific deployment information extends the existing ``mw::com`` deployment +model with DDS Topics, runtime type information, Domains, QoS, communication +routes, availability policies, and E2E configuration. - +----------------------------+ - | Local mw::com Sample | - +----------------------------+ -- Execution and performance model: +Specification +============= - - Asynchronous processing using internal worker queues - - Support for configurable priority-based routing - - High-priority routes can be processed with dedicated queues and worker pools - - Normal-priority routes are handled via standard processing queues +The DDS Binding and DDS Gateway specification consists of the following +chapters. +Architecture +------------ -Motivation ----------- +The Architecture chapter describes: + +* DDS Binding deployment; +* DDS Gateway deployment; +* DDS Communication Daemon; +* configuration model; +* communication routes; +* Topic mapping; +* runtime type handling; +* QoS configuration; and +* runtime data flow. + +Requirements +------------ + +The Requirements chapter defines the requirements for the DDS +Binding, DDS Gateway, DDS Communication Daemon, deployment configuration, +runtime behavior, interoperability, and safety aspects. -S-CORE currently focuses on local communication via ``mw::com (LoLa)`` but does -not provide a standardized mechanism for inter-ECU communication using DDS-based -systems. +Service Discovery and Availability +---------------------------------- -In mixed middleware environments: +The Service Discovery chapter describes: -- ``mw::com`` does not provide a standardized DDS communication binding -- Different projects implement DDS integration using project-specific solutions -- Integration with DDS requires project-specific bindings or adapters -- Applications may need to embed DDS-specific logic, reducing abstraction -- Communication with native DDS applications is not standardized -- Inter-ECU communication between ``mw::com`` participants via DDS is not standardized -- Multi-domain DDS deployments are difficult to configure consistently +* DDS endpoint discovery; +* communication-route state; +* configurable service-availability policies; +* route-based availability; +* explicit service-state propagation; +* startup behavior; and +* recovery behavior. +End-to-End Protection +--------------------- -This feature addresses these challenges by introducing a reusable DDS -communication binding beneath ``mw::com`` together with a reference DDS -Gateway implementation. +The E2E chapter describes: -The DDS binding provides standardized DDS communication for ``mw::com`` -applications, while the reference gateway demonstrates one possible approach -for translating between local ``mw::com (LoLa)`` communication and DDS-based -communication. +* ownership of E2E processing; +* E2E Protect and E2E Check; +* Binding deployment; +* Gateway deployment; +* interaction with the DDS Communication Daemon; and +* application-facing E2E semantics. -Key Value +Use Cases --------- -- Standardized DDS communication support through an ``mw::com`` binding -- Reference DDS Gateway implementation for ``mw::com (LoLa)`` to DDS translation -- Supports multiple integration concepts through a common DDS communication layer -- DDS-stack-independent runtime type handling through a common abstraction layer -- Direct interoperability with native DDS applications -- Standardized inter-ECU communication between ``mw::com`` participants via DDS +The Use Cases chapter illustrates supported deployment scenarios and expected +runtime behavior. -- Performance and determinism: - - Low-latency processing for high-priority data flows - - Controlled execution via configurable worker queues - - Predictable behavior for mixed criticality communication +Backwards Compatibility +======================= -- Interoperability across heterogeneous systems: +Existing ``mw::com`` applications continue to use the standard ``mw::com`` API. - - Enables communication between systems with different architectures - (e.g., 32-bit / 64-bit, different endianness) - - Ensures consistent data representation via Dynamic Type handling +Existing LoLa application's deployment remain unchanged unless DDS Gateway communication is +explicitly configured for this application requiring communication over DDS network. -Reference ---------- +Security Impact +=============== + +DDS communication may interact with other systems for which security is needed. + +Validation of received data, deployment of DDS Security, credential management, +network protection, and platform hardening remain deployment-specific unless +covered by another SCORE feature. + + +Safety Impact +============= + +DDS stacks are typically available as QM software components. + +Deployments requiring ASIL/QM separation may execute the DDS Binding or DDS +Gateway in an ASIL context while placing the DDS stack inside a separate DDS +Communication Daemon. + +The runtime IPC boundary provides architectural separation between the +application-facing communication component and the DDS stack. + +The complete freedom-from-interference argument remains deployment-specific. + +Refer to the Architecture and E2E chapters for further details. + + +License Impact +============== + +DDS is an open communication standard supported by multiple implementations. + +The implementation shall comply with the license terms of the selected DDS +implementation while preserving the stable application-facing abstraction +defined by this feature. + + +How to Teach This +================= + +Application developers continue to use the standard ``mw::com`` API and are not +required to understand deeply DDS programming/concept. -The detailed Feature Request is available here: +System integrators configure DDS deployment information, including Topics, +runtime types, Domains, QoS, communication routes, availability policies, and +E2E settings. -- DDS Gateway Feature Request: https://github.com/eclipse-score/score/issues/2726 +Developers implementing the communication infrastructure should additionally +understand the DDS Binding architecture, DDS Gateway architecture, DDS +Communication Daemon, service discovery, communication routes, and E2E +processing. diff --git a/docs/features/communication/dds_gateway/requirements/index.rst b/docs/features/communication/dds_gateway/requirements/index.rst new file mode 100644 index 00000000000..777cc1eeb99 --- /dev/null +++ b/docs/features/communication/dds_gateway/requirements/index.rst @@ -0,0 +1,460 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +.. _dds_binding_gateway_requirements: + +DDS Binding and Gateway Requirements +#################################### + +Architecture Requirements +========================= + +.. req:: Direct DDS Binding deployment + :id: feat_req__dds__direct_binding + :status: valid + + The feature shall support deployment of a DDS Binding beneath ``mw::com``. + +.. req:: DDS Gateway deployment + :id: feat_req__dds__gateway + :status: valid + + The feature shall support deployment of a DDS Gateway between LoLa and DDS. + +.. req:: Common DDS Communication Daemon + :id: feat_req__dds__common_daemon + :status: valid + + The DDS Binding and DDS Gateway shall be able to reuse the same DDS + Communication Daemon capability. + +.. req:: DDS stack outside ASIL-facing process + :id: feat_req__dds__stack_process_separation + :status: valid + + A deployment requiring ASIL/QM separation shall support placing the DDS + stack in a DDS Communication Daemon process outside the DDS Binding or DDS + Gateway process. + +.. req:: Runtime IPC + :id: feat_req__dds__runtime_ipc + :status: valid + + The DDS Binding and DDS Gateway shall communicate with the DDS Communication + Daemon through runtime IPC. + +Configuration Requirements +========================== + +.. req:: Extend mw::com deployment for DDS + :id: feat_req__dds__extend_mwcom_deployment + :status: valid + + The DDS integration shall extend the existing ``mw::com`` deployment model + with the DDS-specific information required to establish configured DDS + communication routes. + +.. req:: Reuse mw::com service model + :id: feat_req__dds__reuse_mwcom_service_model + :status: valid + + DDS configuration shall reuse the existing ``mw::com`` service type, + version, service instance, and event identities. + +.. req:: DDS communication route information + :id: feat_req__dds__route_information + :status: valid + + A configured DDS communication route shall identify the corresponding + ``mw::com`` event, DDS Domain, DDS Topic, DDS type, communication direction, + and applicable DDS QoS configuration. + +.. req:: Component-specific configuration + :id: feat_req__dds__component_specific_configuration + :status: valid + + The DDS Binding, DDS Gateway, and DDS Communication Daemon may consume + separate configuration artifacts according to their respective + responsibilities. + +.. req:: Configuration consistency + :id: feat_req__dds__configuration_consistency + :status: valid + + Configuration artifacts used by the DDS Binding, DDS Gateway, and DDS + Communication Daemon shall be mutually consistent for every configured + route and availability policy. + +.. req:: Configuration outside runtime IPC + :id: feat_req__dds__configuration_outside_runtime_ipc + :status: valid + + DDS deployment configuration shall not be exchanged through the runtime IPC + between the DDS Binding or DDS Gateway and the DDS Communication Daemon. + +.. req:: Configuration validation + :id: feat_req__dds__configuration_validation + :status: valid + + The implementation shall not activate a DDS route or service-availability + policy whose required configuration is missing, inconsistent, ambiguous, + invalid, or unsupported. + +Topic Mapping Requirements +========================== + +.. req:: Event-to-Topic mapping + :id: feat_req__dds__event_topic_mapping + :status: valid + + Each ``mw::com`` event configured for DDS communication shall be mapped + unambiguously to a DDS Topic. + +.. req:: Deterministic Topic identity + :id: feat_req__dds__deterministic_topic_identity + :status: valid + + A configured or derived DDS Topic identity shall be deterministic. + +.. req:: Prevent unintended Topic collision + :id: feat_req__dds__topic_collision_prevention + :status: valid + + The event-to-Topic mapping shall prevent different DDS communication routes + from unintentionally resolving to the same DDS Topic identity. + +.. req:: Explicit or derived Topic name + :id: feat_req__dds__topic_name_selection + :status: valid + + The deployment shall support a Topic identity that is either explicitly + configured or derived according to an implementation-defined deterministic + convention. + +.. req:: Compatible Topic definition + :id: feat_req__dds__compatible_topic_definition + :status: valid + + Communicating publishers and subscribers shall use compatible DDS Domain, + Topic, type, and QoS information. + +DDS Type Requirements +===================== + +.. req:: DDS type configuration + :id: feat_req__dds__type_configuration + :status: valid + + Each DDS-enabled ``mw::com`` event shall be associated with sufficient DDS + type information to create the DDS Topic and corresponding endpoint. + +.. req:: Runtime serialization information + :id: feat_req__dds__runtime_serialization_information + :status: valid + + The configured type information shall be sufficient to serialize and + deserialize the event payload at runtime. + +.. req:: No generated DDS application interface + :id: feat_req__dds__no_generated_application_interface + :status: valid + + The DDS integration shall not require the ``mw::com`` application to use or + link a DDS-generated application interface. + +.. req:: Type compatibility validation + :id: feat_req__dds__type_compatibility_validation + :status: valid + + The implementation shall validate compatibility between the configured + ``mw::com`` event type and DDS type before activating the route. + +DDS Domain Requirements +======================= + +.. req:: DDS Domain configuration + :id: feat_req__dds__domain_configuration + :status: valid + + Each DDS communication route shall be associated with a DDS Domain. + +.. req:: Multiple DDS Domains + :id: feat_req__dds__multiple_domains + :status: valid + + The deployment model shall allow different configured routes to use + different DDS Domains. + +DDS QoS Requirements +==================== + +.. req:: DDS QoS configuration + :id: feat_req__dds__qos_configuration + :status: valid + + The DDS deployment information shall provide the DDS QoS required for each + configured communication route. + +.. req:: Reusable QoS profiles + :id: feat_req__dds__reusable_qos_profiles + :status: valid + + An implementation may allow multiple routes to refer to a reusable DDS QoS + profile. + +.. req:: Explicit QoS configuration + :id: feat_req__dds__explicit_qos_configuration + :status: valid + + The implementation shall not assume an automatic one-to-one mapping between + LoLa communication properties and DDS QoS policies. + +Binding Requirements +==================== + +.. req:: Binding-independent application API + :id: feat_req__dds__binding_independent_api + :status: valid + + An application using the DDS Binding shall continue to use the standard + ``mw::com`` API. + +.. req:: Binding runtime type handling + :id: feat_req__dds__binding_runtime_types + :status: valid + + The DDS Binding shall use the configured runtime type information required + for its routes. + +.. req:: Binding serialization + :id: feat_req__dds__binding_serialization + :status: valid + + The DDS Binding shall convert between ``mw::com`` samples and the configured + serialized DDS representation. + +Gateway Requirements +==================== + +.. req:: Generic Proxy + :id: feat_req__dds__generic_proxy + :status: valid + + The DDS Gateway shall be able to consume configured locally provided LoLa + events through a Generic Proxy. + +.. req:: Generic Skeleton + :id: feat_req__dds__generic_skeleton + :status: valid + + The DDS Gateway shall be able to provide configured remotely received DDS + events through a Generic Skeleton. + +.. req:: Bidirectional Gateway routes + :id: feat_req__dds__bidirectional_gateway + :status: valid + + The DDS Gateway shall support configured LoLa-to-DDS and DDS-to-LoLa event + routes. + +Daemon Requirements +=================== + +.. req:: DDS entity creation + :id: feat_req__dds__daemon_entity_creation + :status: valid + + The DDS Communication Daemon shall create the configured DDS Domains, Topics, + DataReaders, and DataWriters according to the deployment lifecycle policy. + +.. req:: Serialized DDS write + :id: feat_req__dds__serialized_write + :status: valid + + The DDS Communication Daemon shall publish serialized DDS samples received + for configured writer routes. + +.. req:: Serialized DDS read + :id: feat_req__dds__serialized_read + :status: valid + + The DDS Communication Daemon shall deliver serialized DDS samples received + on configured reader routes through runtime IPC. + +.. req:: Multiplex configured routes + :id: feat_req__dds__multiplex_routes + :status: valid + + The runtime IPC shall support multiple configured communication routes + without requiring one IPC connection per Topic, service, or event. + +Discovery and Availability Requirements +======================================= + +.. req:: DDS endpoint discovery + :id: feat_req__dds__endpoint_discovery + :status: valid + + The DDS Communication Daemon shall use DDS participant and endpoint + discovery for configured DDS communication routes. + +.. req:: Communication-route state + :id: feat_req__dds__route_operational_state + :status: valid + + The DDS Communication Daemon shall evaluate the operational state of each + configured DDS communication route. + +.. req:: Route-state notification + :id: feat_req__dds__endpoint_status_notification + :status: valid + + The DDS Communication Daemon shall communicate relevant communication-route + state changes to the DDS Binding or DDS Gateway through runtime IPC. + +.. req:: Configurable service-availability policy + :id: feat_req__dds__availability_policy + :status: valid + + The deployment configuration shall define how availability of each mapped + ``mw::com`` service instance is determined. + +.. req:: Availability-policy inputs + :id: feat_req__dds__availability_sources + :status: valid + + The service-availability policy shall support using: + + * DDS communication-route state; + * explicit service-instance state; + +.. req:: Required communication routes + :id: feat_req__dds__required_availability_routes + :status: valid + + For route-based availability, the deployment configuration shall identify + the DDS communication routes that participate in the service-availability + decision. + +.. req:: Explicit service-state propagation + :id: feat_req__dds__explicit_service_availability + :status: valid + + The architecture shall support propagation of explicit service-instance + state through a configured DDS communication route. + + +.. req:: Binding availability propagation + :id: feat_req__dds__binding_availability + :status: valid + + The DDS Binding shall apply the configured service-availability policy and + update the corresponding ``mw::com`` availability state. + +.. req:: Gateway availability propagation + :id: feat_req__dds__gateway_availability + :status: valid + + The DDS Gateway shall apply the configured service-availability policy and + offer or withdraw the corresponding local LoLa service. + +.. req:: Native DDS route-based availability + :id: feat_req__dds__native_endpoint_availability + :status: valid + + A compatible native DDS participant that does not provide explicit + service-instance state shall be supportable through a route-based + availability policy. + +.. req:: Availability recovery + :id: feat_req__dds__availability_recovery + :status: valid + + Following DDS communication or DDS Communication Daemon recovery, service + availability shall be restored only after the configured availability + conditions are fulfilled again. + +.. req:: Bounded startup data handling + :id: feat_req__dds__bounded_startup_handling + :status: valid + + The implementation shall define bounded behavior for DDS samples received + before the corresponding local application-facing communication path is + ready. + +E2E Requirements +================ + +.. req:: Binding-independent E2E API + :id: feat_req__dds__e2e_binding_independent_api + :status: valid + + An application shall use the same ``mw::com`` E2E-facing API when deployed + with the DDS Binding or LoLa Binding. + +.. req:: Single E2E owner + :id: feat_req__dds__single_e2e_owner + :status: valid + + A protected communication route shall have one configured owner for E2E + protection and one configured owner for E2E checking. + +.. req:: Disable duplicate LoLa E2E + :id: feat_req__dds__disable_duplicate_lola_e2e + :status: valid + + LoLa-side E2E processing shall be disabled for an internal DDS Gateway leg + when the DDS Gateway owns the same configured E2E profile. + +.. req:: Gateway E2E result forwarding + :id: feat_req__dds__gateway_e2e_forwarding + :status: valid + + For incoming DDS Gateway routes, the Gateway shall forward the payload and + produced E2E result to the local ``mw::com`` consumer without repeating the + same E2E check in LoLa. + +Safety Requirements +=================== + +.. req:: ASIL/QM process boundary + :id: feat_req__dds__asil_qm_boundary + :status: valid + + A deployment requiring separation between an ASIL-facing communication + component and a QM DDS stack shall use the DDS Communication Daemon process + boundary. + +.. req:: Deployment-specific IPC suitability + :id: feat_req__dds__ipc_suitability + :status: valid + + The selected runtime IPC mechanism shall be suitable for the requirements of + the deployment safety concept. + +Interoperability Requirements +============================= + +.. req:: Native DDS interoperability + :id: feat_req__dds__native_interoperability + :status: valid + + A configured route shall be able to interoperate with a compatible native + DDS participant using matching Domain, Topic, type, and QoS information. + +.. req:: DDS stack abstraction + :id: feat_req__dds__stack_abstraction + :status: valid + + Application-facing components shall not depend directly on one + vendor-specific DDS API. diff --git a/docs/features/communication/dds_gateway/service_discovery/index.rst b/docs/features/communication/dds_gateway/service_discovery/index.rst new file mode 100644 index 00000000000..fa1c389d53c --- /dev/null +++ b/docs/features/communication/dds_gateway/service_discovery/index.rst @@ -0,0 +1,612 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +.. _dds_binding_gateway_service_discovery: + +DDS Service Discovery and Availability +###################################### + +Overview +======== + +DDS and ``mw::com`` provide different communication abstractions. + +DDS discovers communication participants and compatible communication +endpoints (DataReaders and DataWriters). Applications using ``mw::com``, +however, interact with service instances rather than individual DDS endpoints. + +A mapped ``mw::com`` service instance may contain multiple events, where each +event is mapped to an independent DDS communication route. Consequently, the +availability of a service instance cannot always be inferred directly from the +discovery state of a single DDS endpoint. + +To bridge this semantic difference, this feature defines how DDS runtime +information is mapped to the ``mw::com`` service-availability model. + +The feature introduces configurable service-availability policies that derive +the availability of a mapped ``mw::com`` service instance from DDS runtime +information while preserving standard DDS discovery. + +The resulting service availability is then exposed to applications through the +standard ``mw::com`` programming model. + +Service-Availability Policy +=========================== + +DDS endpoint discovery and ``mw::com`` service availability are distinct +concepts. + +DDS discovery provides runtime information about DDS communication endpoints. + +The DDS Binding or DDS Gateway derives the availability of each mapped +``mw::com`` service instance according to a configured availability policy. + +This specification defines the following availability policies: + +* Endpoint-Based Availability +* Explicit Service Availability + +Future specifications may define additional availability policies without +changing the DDS discovery mechanism described by this feature. + +Availability policies derive application-level service availability. They do +not introduce an additional DDS discovery mechanism. + +Endpoint-Based Availability +--------------------------- + +Endpoint-Based Availability derives the availability of a mapped +``mw::com`` service instance from the operational state of its configured DDS +communication routes. + +A DDS communication route represents one configured communication path between +an ``mw::com`` event and a DDS Topic. A mapped ``mw::com`` service instance may +therefore depend on multiple DDS communication routes. + +The DDS Communication Daemon performs standard DDS participant and endpoint +discovery through the selected DDS stack. For every configured communication +route, the daemon determines whether the required compatible remote DDS +endpoint is discovered and matched. + +A communication route becomes operational when the required compatible remote +DDS endpoint is discovered and matched. It becomes non-operational when, for +example: + +* the corresponding remote DataWriter or DataReader is removed; +* the remote DDS participant disappears; +* a previously matched endpoint becomes unmatched; or +* another configured DDS runtime condition invalidates the route. + +The DDS Communication Daemon reports every communication-route state change to +the DDS Binding or DDS Gateway through runtime IPC. + +The DDS Binding or DDS Gateway maintains the current operational state of all +routes associated with each mapped ``mw::com`` service instance. Whenever a +route state changes, the Endpoint-Based Availability policy is evaluated using +the current state of all required routes. + +During initial discovery, routes may become operational one by one. The mapped +service remains unavailable until all routes required by the configured policy +are operational. No withdrawal action is performed while the service is already +unavailable. + +When all required routes become operational, the service state changes from +unavailable to available. The DDS Binding or DDS Gateway exposes the mapped +service through the standard ``mw::com`` service-discovery mechanism. + +After the service has become available, if any required route becomes +non-operational, the service state changes from available to unavailable. The +DDS Binding or DDS Gateway withdraws the mapped service through the standard +``mw::com`` service-discovery mechanism. + +Endpoint-Based Availability with DDS Binding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following diagram shows the transition from unavailable to available after +all required DDS communication routes have been discovered and matched. + +:: + + Remote DDS Application + ---------------------- + Topic A Topic B Topic C + | | | + | DDS endpoint discovery and matching + v v v + +-----------------------------------+ + | DDS Communication Daemon | + |-----------------------------------| + | Route A: operational | + | Route B: operational | + | Route C: operational | + +-----------------+-----------------+ + | + | route-state changes + | through runtime IPC + v + +-----------------------------------+ + | DDS Binding | + |-----------------------------------| + | Current state for Service X | + | | + | Route A: operational | + | Route B: operational | + | Route C: operational | + +-----------------+-----------------+ + | + | evaluate Endpoint-Based + | Availability policy + v + +-----------------------------------+ + | All required routes operational | + | | + | Service state transition: | + | UNAVAILABLE -> AVAILABLE | + +-----------------+-----------------+ + | + | expose mapped service through + | mw::com service discovery + v + +-----------------------------------+ + | mw::com Application | + |-----------------------------------| + | Service available | + | | + +-----------------------------------+ + +The following diagram shows the transition from available to unavailable when +a previously operational required route disappears or becomes unmatched. + +:: + + Remote DDS Application + ---------------------- + Topic A Topic B Topic C + | X | + | Topic B removed | + | or endpoint lost | + v v + +-----------------------------------+ + | DDS Communication Daemon | + |-----------------------------------| + | Route A: operational | + | Route B: non-operational | + | Route C: operational | + +-----------------+-----------------+ + | + | Route B state changed: + | operational -> non-operational + | through runtime IPC + v + +-----------------------------------+ + | DDS Binding | + |-----------------------------------| + | Current state for Service X | + | | + | Route A: operational | + | Route B: non-operational | + | Route C: operational | + +-----------------+-----------------+ + | + | re-evaluate Endpoint-Based + | Availability policy + v + +-----------------------------------+ + | A required route is unavailable | + | | + | Service state transition: | + | AVAILABLE -> UNAVAILABLE | + +-----------------+-----------------+ + | + | withdraw mapped service from + | mw::com service discovery + v + +-----------------------------------+ + | mw::com Application | + |-----------------------------------| + | service unavailable | + | | + +-----------------------------------+ + +Endpoint-Based Availability with DDS Gateway +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following diagram shows the transition from unavailable to available after +all required DDS communication routes have been discovered and matched. + +:: + + Remote DDS Application + ---------------------- + Topic A Topic B Topic C + | | | + | DDS endpoint discovery and matching + v v v + +-----------------------------------+ + | DDS Communication Daemon | + |-----------------------------------| + | Route A: operational | + | Route B: operational | + | Route C: operational | + +-----------------+-----------------+ + | + | route-state changes + | through runtime IPC + v + +-----------------------------------+ + | DDS Gateway | + |-----------------------------------| + | Current state for Service X | + | | + | Route A: operational | + | Route B: operational | + | Route C: operational | + +-----------------+-----------------+ + | + | evaluate Endpoint-Based + | Availability policy + v + +-----------------------------------+ + | All required routes operational | + | | + | Service state transition: | + | UNAVAILABLE -> AVAILABLE | + +-----------------+-----------------+ + | + | Generic Skeleton + | OfferService() + v + +-----------------------------------+ + | mw::com Application | + |-----------------------------------| + | Service available | + | | + +-----------------------------------+ + +The following diagram shows the transition from available to unavailable when +a previously operational required route disappears or becomes unmatched. + +:: + + Remote DDS Application + ---------------------- + Topic A Topic B Topic C + | X | + | Topic B removed | + | or endpoint lost | + v v + +-----------------------------------+ + | DDS Communication Daemon | + |-----------------------------------| + | Route A: operational | + | Route B: non-operational | + | Route C: operational | + +-----------------+-----------------+ + | + | Route B state changed: + | operational -> non-operational + | through runtime IPC + v + +-----------------------------------+ + | DDS Gateway | + |-----------------------------------| + | Current state for Service X | + | | + | Route A: operational | + | Route B: non-operational | + | Route C: operational | + +-----------------+-----------------+ + | + | re-evaluate Endpoint-Based + | Availability policy + v + +-----------------------------------+ + | A required route is unavailable | + | | + | Service state transition: | + | AVAILABLE -> UNAVAILABLE | + +-----------------+-----------------+ + | + | Generic Skeleton + | StopOfferService() + v + +-----------------------------------+ + | mw::com Application | + |-----------------------------------| + | | + | service unavailable | + +-----------------------------------+ + + +Explicit Service Availability +----------------------------- + +Explicit Service Availability derives the availability of a mapped +``mw::com`` service instance from an explicit availability indication +provided by a remote DDS Binding or DDS Gateway. + +Unlike Endpoint-Based Availability, this policy does not derive +application-level availability only from the discovery state of DDS +communication endpoints. + +Instead, the explicit availability indication represents the lifecycle state +of the remotely provided ``mw::com`` service instance. + +For example, the indication may represent that the remotely provided service +has become available or unavailable. + +The mechanism used to exchange the explicit availability indication is +implementation-specific. + +The following details are therefore not prescribed by this feature: + +* the DDS Topic used to carry the indication; +* the data representation; +* the DDS QoS; +* the mapping between service instances and availability indications; +* the runtime IPC representation; and +* the internal availability state machine. + +The DDS Communication Daemon receives the explicit availability indication and +reports the resulting availability change to the DDS Binding or DDS Gateway +through runtime IPC. + +The DDS Binding or DDS Gateway then exposes or withdraws the corresponding +mapped service through the standard ``mw::com`` service-discovery mechanism. + +This policy allows ``mw::com`` service availability to follow the lifecycle of +the remote provider independently of the discovery state of the DDS data +endpoints. + +Explicit Service Availability with DDS Binding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When a service is provided through a DDS Binding, the provider-side Binding +observes the lifecycle of the locally provided ``mw::com`` service instance. + +When the local service becomes available or unavailable, the provider-side +Binding propagates the corresponding explicit availability indication through +the DDS Communication Daemon. + +The receiving DDS Communication Daemon reports the indication to the +consumer-side DDS Binding. + +The consumer-side DDS Binding then exposes or withdraws the corresponding +mapped ``mw::com`` service instance. + +The consuming application observes the resulting availability change through +the standard ``mw::com`` service-discovery mechanism. + +:: + + Provider ECU Consumer ECU + ============ ============ + + +--------------------------+ +--------------------------+ + | Provider mw::com | | Consumer mw::com | + | Application | | Application | + | | | | + | Local service lifecycle | | Observes mapped service | + | state | | availability | + +------------+-------------+ +-------------^------------+ + | | + | local mw::com service | + | lifecycle | + v | + +--------------------------+ +--------------------------+ + | Provider DDS Binding | | Consumer DDS Binding | + +------------+-------------+ +-------------^------------+ + | | + | explicit availability | + | state through runtime IPC | + v | + +--------------------------+ +--------------------------+ + | DDS Communication Daemon | | DDS Communication Daemon | + +------------+-------------+ +-------------^------------+ + | | + | implementation-specific explicit | + | service-availability mechanism | + +---------------- DDS ------------------------+ + | + | + expose or withdraw mapped + mw::com service instance + +The explicit availability indication and the DDS event data may use +independent communication mechanisms and independent DDS Topics. + +Explicit Service Availability with DDS Gateway +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When a locally provided ``mw::com`` service is forwarded through a DDS Gateway, +the provider-side Gateway observes the lifecycle of the local service through +its Generic Proxy. + +When the local service becomes available or unavailable, the provider-side +Gateway forwards the corresponding explicit availability indication to the DDS +Communication Daemon. + +On the receiving ECU, the DDS Communication Daemon reports the explicit +availability indication to the consumer-side DDS Gateway. + +The consumer-side DDS Gateway then exposes or withdraws the corresponding +mapped service through its Generic Skeleton. + +The consuming application observes the resulting availability change through +the standard ``mw::com`` service-discovery mechanism. + +:: + + Provider ECU Consumer ECU + ============ ============ + + +--------------------------+ +--------------------------+ + | Provider mw::com | | Consumer mw::com | + | Application | | Application | + | | | | + | Local service lifecycle | | Observes mapped service | + | state | | availability | + +------------+-------------+ +-------------^------------+ + | | + | local mw::com communication | + v | + +--------------------------+ +--------------------------+ + | DDS Gateway | | DDS Gateway | + | | | | + | Generic Proxy observes | | Generic Skeleton exposes | + | local service lifecycle | | or withdraws mapped | + | | | service instance | + +------------+-------------+ +-------------^------------+ + | | + | explicit availability | + | state through runtime IPC | + v | + +--------------------------+ +--------------------------+ + | DDS Communication Daemon | | DDS Communication Daemon | + +------------+-------------+ +-------------^------------+ + | | + | implementation-specific explicit | + | service-availability mechanism | + +---------------- DDS ------------------------+ + +The consuming application therefore observes the lifecycle of the remote +provider through the standard ``mw::com`` service-discovery mechanism. + +Native DDS Interoperability +=========================== + +Native DDS applications typically participate only in standard DDS endpoint +discovery and do not provide application-level service-availability +information. + +Endpoint-Based Availability enables interoperability with native DDS +applications by deriving ``mw::com`` service availability from standard DDS +endpoint discovery without requiring an additional DDS protocol or +application-level availability information. + +Responsibility Split +==================== + +DDS Communication Daemon +------------------------ + +The DDS Communication Daemon is responsible for: + +* performing DDS participant and endpoint discovery; +* creating and managing the required DDS communication entities; +* maintaining the runtime state of configured DDS communication routes; +* mapping DDS endpoint state to configured communication-route identifiers; +* receiving and transmitting explicit service-availability indications, where + configured; +* reporting communication-route and explicit availability changes through + runtime IPC; and +* restoring DDS runtime state following restart or communication recovery. + +The DDS Communication Daemon does not expose ``mw::com`` services directly to +applications. + +DDS Binding +----------- + +The DDS Binding is responsible for: + +* associating daemon notifications with configured ``mw::com`` service + instances; +* evaluating the configured availability policy; +* offering or withdrawing the mapped ``mw::com`` service instance; +* exposing the resulting availability through the standard ``mw::com`` + service-discovery API; +* observing the lifecycle of locally provided ``mw::com`` services; and +* forwarding local service-availability changes where Explicit Service + Availability is configured. + +Applications using the DDS Binding continue to use the standard ``mw::com`` +API. + +DDS Gateway +----------- + +The DDS Gateway is responsible for: + +* associating daemon notifications with configured Generic Skeleton service + instances; +* evaluating the configured availability policy; +* calling ``OfferService()`` or ``StopOfferService()`` on the corresponding + Generic Skeleton; +* observing locally provided services through the corresponding Generic Proxy; + and +* forwarding local service-availability changes where Explicit Service + Availability is configured. + +The DDS Gateway exposes remotely provided DDS services to local applications +through the standard LoLa and ``mw::com`` service-discovery mechanisms. + +Configuration +============= + +The deployment configuration shall provide sufficient information to determine +the availability behavior of every mapped ``mw::com`` service instance. + +This may include: + +* the mapped service type and service instance; +* the DDS communication routes associated with the service instance; +* the availability policy associated with the mapped service instance; +* the communication routes participating in the availability decision; +* the communication routes used to exchange Explicit Service Availability, + where configured; and +* deployment-specific policy parameters. + +The DDS Communication Daemon, DDS Binding and DDS Gateway may consume separate +configuration artifacts. + +These artifacts shall define mutually consistent communication-route +identifiers and availability policies. + +The exact configuration schema is implementation-specific. + +Startup and Data Handling +========================= + +DDS communication may become operational before the corresponding local +application-facing communication path is ready. + +The implementation shall define bounded handling for samples received during +this interval. + +Possible strategies include: + +* delaying DDS reception; +* bounded buffering; +* retaining only the latest sample; +* using configured DDS durability and history; +* dropping samples until the local communication path becomes available; or +* another bounded deployment-specific strategy. + +Unlimited buffering is not required. + +Implementation Considerations +============================= + +This feature request does not prescribe: + +* one mandatory availability policy; +* one mandatory DDS Topic for Explicit Service Availability; +* the binary representation of Explicit Service Availability; +* the QoS associated with Explicit Service Availability; +* DDS entity creation time; +* the runtime IPC protocol; +* the internal state-machine representation; +* polling versus callback-based implementations; +* one startup buffering strategy; or +* fixed discovery or availability timeout values. diff --git a/docs/features/communication/dds_gateway/use_cases/index.rst b/docs/features/communication/dds_gateway/use_cases/index.rst new file mode 100644 index 00000000000..00c61ce0841 --- /dev/null +++ b/docs/features/communication/dds_gateway/use_cases/index.rst @@ -0,0 +1,298 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _dds_binding_gateway_use_cases: + +DDS Binding and Gateway Use Cases +################################# + +Supported Use Cases +=================== + +Direct DDS Binding +------------------ + +An ``mw::com`` application is deployed with the DDS Binding. + +The application uses the standard ``mw::com`` API while the DDS Binding maps +configured events to DDS communication routes. + +The DDS stack executes in the DDS Communication Daemon. + +Native DDS Interoperability +--------------------------- + +An ``mw::com`` publisher or subscriber communicates with a compatible native +DDS participant. + +Both sides use compatible DDS Domain, Topic, type, and QoS information. + +Endpoint-based availability may be used when the native DDS participant does +not provide explicit service-instance state. + +LoLa-to-DDS Gateway +------------------- + +An existing LoLa producer is connected to DDS through the DDS Gateway. + +The Gateway consumes the configured LoLa event using a Generic Proxy, +serializes the sample, and forwards it through runtime IPC to the DDS +Communication Daemon. + +DDS-to-LoLa Gateway +------------------- + +A DDS sample is received by the DDS Communication Daemon and forwarded through +runtime IPC to the DDS Gateway. + +The Gateway deserializes the sample and provides it locally using a Generic +Skeleton. + +LoLa-to-LoLa Communication over DDS +----------------------------------- + +A LoLa application on one ECU communicates with a LoLa application on another +ECU through DDS Gateways and DDS Communication Daemons. + +The applications remain unaware of DDS. + +Configure an Existing mw::com Event for DDS +------------------------------------------- + +An integrator extends the existing ``mw::com`` deployment information for an +event with the DDS information required to establish communication. + +The existing service type, service version, service instance, event, provider, +and consumer information is reused. + +DDS-specific deployment information supplements it with: + +* DDS Domain selection; +* DDS Topic mapping; +* DDS type information; +* communication direction; +* DDS QoS; and +* service-availability policy where required. + +The configured route may be consumed by a DDS Binding deployment or a DDS +Gateway deployment. + +Deterministic DDS Topic Mapping +------------------------------- + +A configured ``mw::com`` event is mapped unambiguously to a DDS Topic. + +The Topic name may be explicitly configured or deterministically derived from +deployment information. + +The mapping distinguishes routes where required by service type, version, +instance, event, Domain, or type. + +The mapping avoids unintended Topic collisions and ensures that communicating +endpoints use compatible Topic identities. + +Externally Defined DDS Topic +---------------------------- + +A deployment maps an ``mw::com`` event to a DDS Topic whose identity is already +defined by an external DDS system. + +The Topic name is explicitly configured rather than derived. + +The ``mw::com`` application remains unchanged. + +Runtime DDS Type +---------------- + +A DDS route is created using runtime type information rather than a +DDS-generated interface linked into the application. + +The configured type information is sufficient for DDS entity creation, +serialization, deserialization, validation, and interoperability. + +Per-Route DDS QoS +----------------- + +An integrator assigns DDS QoS to a configured communication route. + +Different events or service instances may use different QoS profiles according +to their communication requirements. + +The application continues to use the standard ``mw::com`` API and remains +unaware of the DDS QoS configuration. + +Reusable DDS QoS Profile +------------------------ + +Multiple DDS routes refer to the same configured QoS profile. + +This allows consistent QoS deployment without repeating policy values for every +route. + +Multiple DDS Domains +-------------------- + +Different configured DDS routes use different DDS Domains. + +This enables communication isolation according to deployment needs while +preserving the same ``mw::com`` programming model. + +Multiple Applications per Daemon +-------------------------------- + +A DDS Communication Daemon serves multiple applications using DDS Bindings, +or DDS Gateways. + +Each runtime IPC message is associated with a preconfigured communication +route. + +Component-Specific Configuration +-------------------------------- + +A deployment process produces separate, mutually consistent configuration +artifacts for the DDS Binding, DDS Gateway, and DDS Communication Daemon. + +Each component receives the information required for its own responsibilities. + +Configuration is not distributed through runtime IPC. + +DDS Route-State Propagation to Binding +-------------------------------------- + +The DDS Communication Daemon detects a change in the operational state of a +configured DDS communication route. + +The resulting route state is communicated to the DDS Binding. + +The DDS Binding evaluates the configured service-availability policy and updates +the corresponding ``mw::com`` availability state. + +DDS Route-State Propagation through Gateway +------------------------------------------- + +The DDS Communication Daemon detects changes in the operational state of the +DDS communication routes associated with a configured remote service. + +The resulting route state is communicated to the DDS Gateway. + +The DDS Gateway evaluates the configured service-availability policy and offers +or withdraws the corresponding local LoLa service. + +Explicit Service-State Propagation +---------------------------------- + +A locally provided ``mw::com`` service is offered or withdrawn. + +Where explicit service-state propagation is configured, the DDS Binding or DDS +Gateway forwards the local service state to the DDS Communication Daemon. + +The daemon propagates this state through a configured DDS communication route. + +The receiving side uses the state as an input to its configured +service-availability policy. + +Configurable Service-Availability Policy +---------------------------------------- + +A deployment defines how the availability of a mapped ``mw::com`` service +instance is determined. + +The configured policy may use: + +* DDS communication-route state; +* explicit service-instance state; or +* both. + +For endpoint-based evaluation, the policy identifies the communication routes +that are required before the service instance is considered available. + +Configured E2E with Direct Binding +---------------------------------- + +The DDS Binding applies the configured E2E processing to a DDS route while +exposing binding-independent E2E result semantics to the application. + +Configured E2E with Gateway +--------------------------- + +The DDS Gateway applies the configured E2E processing to the network route. + +LoLa E2E processing is disabled for the internal Gateway leg when the Gateway +owns the same E2E profile. + +Daemon Restart and Recovery +--------------------------- + +The DDS Communication Daemon is restarted independently from the application or +Gateway process. + +Configured DDS entities and runtime availability are restored according to the +deployment lifecycle and availability policies. + +Implementation-Dependent Use Cases +================================== + +Dynamic DDS Instances +--------------------- + +Runtime selection or creation of previously unconfined DDS instances may be +supported by an implementation but is not required by this feature. + +Payload Transformation +---------------------- + +Semantic transformation between different application data models is not +required. + +The required use case is representation conversion for compatible configured +types. + +Out of Scope +============ + +The following are outside the scope of this feature request: + +* one mandatory DDS Topic naming formula; +* one mandatory representation for explicit service state; +* one mandatory JSON schema; +* runtime modification of DDS deployment configuration through IPC; +* semantic payload transformation; +* automatic universal QoS mapping; +* one IPC connection per Topic; +* one worker or queue per route; +* DDS Security configuration; +* network-layer security; +* TSN configuration; +* application-specific safety decisions; and +* certification of a particular DDS stack. + +Rejected or Invalid Configurations +================================== + +A DDS route shall not become operational when required configuration is missing, +ambiguous, inconsistent, or unsupported. + +Examples include: + +* an unknown service type, instance, or event; +* missing DDS type information; +* an event type incompatible with the DDS type; +* an invalid DDS Domain; +* an unsupported QoS policy; +* duplicate or ambiguous Topic mappings; +* conflicting communication directions; +* inconsistent Binding, Gateway, and Daemon route identities; +* a missing external Topic mapping where derivation is disabled; +* an availability policy referencing an unknown communication route; or +* inconsistent availability policies between configured components. From 12811b5d857c637ab127c2ecf93a86915b61023e Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Wed, 22 Jul 2026 17:32:37 +0200 Subject: [PATCH 14/17] Correct Formatting --- .../dds_gateway/architecture/index.rst | 25 ++++++++++--------- .../communication/dds_gateway/e2e/index.rst | 25 ++++++++++--------- .../communication/dds_gateway/index.rst | 24 +++++++++--------- .../dds_gateway/requirements/index.rst | 25 ++++++++++--------- .../dds_gateway/service_discovery/index.rst | 25 ++++++++++--------- .../dds_gateway/use_cases/index.rst | 24 +++++++++--------- 6 files changed, 76 insertions(+), 72 deletions(-) diff --git a/docs/features/communication/dds_gateway/architecture/index.rst b/docs/features/communication/dds_gateway/architecture/index.rst index c840949cd9b..0458d260231 100644 --- a/docs/features/communication/dds_gateway/architecture/index.rst +++ b/docs/features/communication/dds_gateway/architecture/index.rst @@ -1,15 +1,16 @@ -# ******************************************************************************* -# 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 -# ******************************************************************************* +.. + ******************************************************************************* + 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 + ******************************************************************************* .. _dds_binding_gateway_architecture: diff --git a/docs/features/communication/dds_gateway/e2e/index.rst b/docs/features/communication/dds_gateway/e2e/index.rst index 227b89b55ac..94679e6e4a7 100644 --- a/docs/features/communication/dds_gateway/e2e/index.rst +++ b/docs/features/communication/dds_gateway/e2e/index.rst @@ -1,15 +1,16 @@ -# ******************************************************************************* -# 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 -# ******************************************************************************* +.. + ******************************************************************************* + 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 + ******************************************************************************* .. _dds_binding_gateway_e2e: diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index b49a6ac5258..efa92d8c29c 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -1,16 +1,16 @@ .. - # ******************************************************************************* - # 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 - # ******************************************************************************* + ******************************************************************************* + 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 + ******************************************************************************* .. _dds_binding_gateway_feature: diff --git a/docs/features/communication/dds_gateway/requirements/index.rst b/docs/features/communication/dds_gateway/requirements/index.rst index 777cc1eeb99..0721a8dd074 100644 --- a/docs/features/communication/dds_gateway/requirements/index.rst +++ b/docs/features/communication/dds_gateway/requirements/index.rst @@ -1,15 +1,16 @@ -# ******************************************************************************* -# 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 -# ******************************************************************************* +.. + ******************************************************************************* + 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 + ******************************************************************************* .. _dds_binding_gateway_requirements: diff --git a/docs/features/communication/dds_gateway/service_discovery/index.rst b/docs/features/communication/dds_gateway/service_discovery/index.rst index fa1c389d53c..6f91b3e475e 100644 --- a/docs/features/communication/dds_gateway/service_discovery/index.rst +++ b/docs/features/communication/dds_gateway/service_discovery/index.rst @@ -1,15 +1,16 @@ -# ******************************************************************************* -# 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 -# ******************************************************************************* +.. + ******************************************************************************* + 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 + ******************************************************************************* .. _dds_binding_gateway_service_discovery: diff --git a/docs/features/communication/dds_gateway/use_cases/index.rst b/docs/features/communication/dds_gateway/use_cases/index.rst index 00c61ce0841..eee7cd9c0e9 100644 --- a/docs/features/communication/dds_gateway/use_cases/index.rst +++ b/docs/features/communication/dds_gateway/use_cases/index.rst @@ -1,16 +1,16 @@ .. - # ******************************************************************************* - # 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 - # ******************************************************************************* + ******************************************************************************* + 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 + ******************************************************************************* .. _dds_binding_gateway_use_cases: From 8f747485b920e6856df61440be6544521078e88a Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Wed, 22 Jul 2026 17:48:38 +0200 Subject: [PATCH 15/17] remove security impact section --- docs/features/communication/dds_gateway/index.rst | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/features/communication/dds_gateway/index.rst b/docs/features/communication/dds_gateway/index.rst index efa92d8c29c..cc2340c18dd 100644 --- a/docs/features/communication/dds_gateway/index.rst +++ b/docs/features/communication/dds_gateway/index.rst @@ -182,16 +182,6 @@ Existing LoLa application's deployment remain unchanged unless DDS Gateway commu explicitly configured for this application requiring communication over DDS network. -Security Impact -=============== - -DDS communication may interact with other systems for which security is needed. - -Validation of received data, deployment of DDS Security, credential management, -network protection, and platform hardening remain deployment-specific unless -covered by another SCORE feature. - - Safety Impact ============= From ea35fd9d9ad49e539e6d7086f4e5d84b1561dba9 Mon Sep 17 00:00:00 2001 From: Abhishek GOYAL Date: Mon, 27 Jul 2026 17:35:47 +0200 Subject: [PATCH 16/17] Clear serialization terminology to DDS CDR format Signed-off-by: Abhishek GOYAL --- .../features/communication/dds_gateway/architecture/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/communication/dds_gateway/architecture/index.rst b/docs/features/communication/dds_gateway/architecture/index.rst index 0458d260231..6c523dc6fbc 100644 --- a/docs/features/communication/dds_gateway/architecture/index.rst +++ b/docs/features/communication/dds_gateway/architecture/index.rst @@ -89,7 +89,7 @@ Daemon. | | | | | | - mw::com service adaptation | | | | - Runtime type handling | | - | | - Serialization / deserialization | | + | | - DDS CDR Serialization / deserialization| | | | - Route mapping | | | | - Availability-policy evaluation | | | | - Configured E2E processing | | @@ -169,7 +169,7 @@ DDS Communication Daemon through runtime IPC. | - LoLa service interaction | | - Route translation | | - Runtime type handling | - | - Serialization / deserialization | + | - DDS CDR Serialization / deserialization | | - Availability-policy evaluation | | - Configured E2E processing | +-----------------------+------------------------+ From efacb69bead2eb65e9dbe7dd1f60ef49db85d9d5 Mon Sep 17 00:00:00 2001 From: Manju Kiran H C Date: Mon, 3 Aug 2026 16:06:45 +0530 Subject: [PATCH 17/17] Fixed documentation build issue --- .../dds_gateway/requirements/index.rst | 112 +++++++++--------- 1 file changed, 56 insertions(+), 56 deletions(-) diff --git a/docs/features/communication/dds_gateway/requirements/index.rst b/docs/features/communication/dds_gateway/requirements/index.rst index 0721a8dd074..fb17f187184 100644 --- a/docs/features/communication/dds_gateway/requirements/index.rst +++ b/docs/features/communication/dds_gateway/requirements/index.rst @@ -20,26 +20,26 @@ DDS Binding and Gateway Requirements Architecture Requirements ========================= -.. req:: Direct DDS Binding deployment +.. feat_req:: Direct DDS Binding deployment :id: feat_req__dds__direct_binding :status: valid The feature shall support deployment of a DDS Binding beneath ``mw::com``. -.. req:: DDS Gateway deployment +.. feat_req:: DDS Gateway deployment :id: feat_req__dds__gateway :status: valid The feature shall support deployment of a DDS Gateway between LoLa and DDS. -.. req:: Common DDS Communication Daemon +.. feat_req:: Common DDS Communication Daemon :id: feat_req__dds__common_daemon :status: valid The DDS Binding and DDS Gateway shall be able to reuse the same DDS Communication Daemon capability. -.. req:: DDS stack outside ASIL-facing process +.. feat_req:: DDS stack outside ASIL-facing process :id: feat_req__dds__stack_process_separation :status: valid @@ -47,7 +47,7 @@ Architecture Requirements stack in a DDS Communication Daemon process outside the DDS Binding or DDS Gateway process. -.. req:: Runtime IPC +.. feat_req:: Runtime IPC :id: feat_req__dds__runtime_ipc :status: valid @@ -57,7 +57,7 @@ Architecture Requirements Configuration Requirements ========================== -.. req:: Extend mw::com deployment for DDS +.. feat_req:: Extend mw::com deployment for DDS :id: feat_req__dds__extend_mwcom_deployment :status: valid @@ -65,14 +65,14 @@ Configuration Requirements with the DDS-specific information required to establish configured DDS communication routes. -.. req:: Reuse mw::com service model +.. feat_req:: Reuse mw::com service model :id: feat_req__dds__reuse_mwcom_service_model :status: valid DDS configuration shall reuse the existing ``mw::com`` service type, version, service instance, and event identities. -.. req:: DDS communication route information +.. feat_req:: DDS communication route information :id: feat_req__dds__route_information :status: valid @@ -80,7 +80,7 @@ Configuration Requirements ``mw::com`` event, DDS Domain, DDS Topic, DDS type, communication direction, and applicable DDS QoS configuration. -.. req:: Component-specific configuration +.. feat_req:: Component-specific configuration :id: feat_req__dds__component_specific_configuration :status: valid @@ -88,7 +88,7 @@ Configuration Requirements separate configuration artifacts according to their respective responsibilities. -.. req:: Configuration consistency +.. feat_req:: Configuration consistency :id: feat_req__dds__configuration_consistency :status: valid @@ -96,14 +96,14 @@ Configuration Requirements Communication Daemon shall be mutually consistent for every configured route and availability policy. -.. req:: Configuration outside runtime IPC +.. feat_req:: Configuration outside runtime IPC :id: feat_req__dds__configuration_outside_runtime_ipc :status: valid DDS deployment configuration shall not be exchanged through the runtime IPC between the DDS Binding or DDS Gateway and the DDS Communication Daemon. -.. req:: Configuration validation +.. feat_req:: Configuration validation :id: feat_req__dds__configuration_validation :status: valid @@ -114,27 +114,27 @@ Configuration Requirements Topic Mapping Requirements ========================== -.. req:: Event-to-Topic mapping +.. feat_req:: Event-to-Topic mapping :id: feat_req__dds__event_topic_mapping :status: valid Each ``mw::com`` event configured for DDS communication shall be mapped unambiguously to a DDS Topic. -.. req:: Deterministic Topic identity +.. feat_req:: Deterministic Topic identity :id: feat_req__dds__deterministic_topic_identity :status: valid A configured or derived DDS Topic identity shall be deterministic. -.. req:: Prevent unintended Topic collision +.. feat_req:: Prevent unintended Topic collision :id: feat_req__dds__topic_collision_prevention :status: valid The event-to-Topic mapping shall prevent different DDS communication routes from unintentionally resolving to the same DDS Topic identity. -.. req:: Explicit or derived Topic name +.. feat_req:: Explicit or derived Topic name :id: feat_req__dds__topic_name_selection :status: valid @@ -142,7 +142,7 @@ Topic Mapping Requirements configured or derived according to an implementation-defined deterministic convention. -.. req:: Compatible Topic definition +.. feat_req:: Compatible Topic definition :id: feat_req__dds__compatible_topic_definition :status: valid @@ -152,28 +152,28 @@ Topic Mapping Requirements DDS Type Requirements ===================== -.. req:: DDS type configuration +.. feat_req:: DDS type configuration :id: feat_req__dds__type_configuration :status: valid Each DDS-enabled ``mw::com`` event shall be associated with sufficient DDS type information to create the DDS Topic and corresponding endpoint. -.. req:: Runtime serialization information +.. feat_req:: Runtime serialization information :id: feat_req__dds__runtime_serialization_information :status: valid The configured type information shall be sufficient to serialize and deserialize the event payload at runtime. -.. req:: No generated DDS application interface +.. feat_req:: No generated DDS application interface :id: feat_req__dds__no_generated_application_interface :status: valid The DDS integration shall not require the ``mw::com`` application to use or link a DDS-generated application interface. -.. req:: Type compatibility validation +.. feat_req:: Type compatibility validation :id: feat_req__dds__type_compatibility_validation :status: valid @@ -183,13 +183,13 @@ DDS Type Requirements DDS Domain Requirements ======================= -.. req:: DDS Domain configuration +.. feat_req:: DDS Domain configuration :id: feat_req__dds__domain_configuration :status: valid Each DDS communication route shall be associated with a DDS Domain. -.. req:: Multiple DDS Domains +.. feat_req:: Multiple DDS Domains :id: feat_req__dds__multiple_domains :status: valid @@ -199,21 +199,21 @@ DDS Domain Requirements DDS QoS Requirements ==================== -.. req:: DDS QoS configuration +.. feat_req:: DDS QoS configuration :id: feat_req__dds__qos_configuration :status: valid The DDS deployment information shall provide the DDS QoS required for each configured communication route. -.. req:: Reusable QoS profiles +.. feat_req:: Reusable QoS profiles :id: feat_req__dds__reusable_qos_profiles :status: valid An implementation may allow multiple routes to refer to a reusable DDS QoS profile. -.. req:: Explicit QoS configuration +.. feat_req:: Explicit QoS configuration :id: feat_req__dds__explicit_qos_configuration :status: valid @@ -223,21 +223,21 @@ DDS QoS Requirements Binding Requirements ==================== -.. req:: Binding-independent application API +.. feat_req:: Binding-independent application API :id: feat_req__dds__binding_independent_api :status: valid An application using the DDS Binding shall continue to use the standard ``mw::com`` API. -.. req:: Binding runtime type handling +.. feat_req:: Binding runtime type handling :id: feat_req__dds__binding_runtime_types :status: valid The DDS Binding shall use the configured runtime type information required for its routes. -.. req:: Binding serialization +.. feat_req:: Binding serialization :id: feat_req__dds__binding_serialization :status: valid @@ -247,21 +247,21 @@ Binding Requirements Gateway Requirements ==================== -.. req:: Generic Proxy +.. feat_req:: Generic Proxy :id: feat_req__dds__generic_proxy :status: valid The DDS Gateway shall be able to consume configured locally provided LoLa events through a Generic Proxy. -.. req:: Generic Skeleton +.. feat_req:: Generic Skeleton :id: feat_req__dds__generic_skeleton :status: valid The DDS Gateway shall be able to provide configured remotely received DDS events through a Generic Skeleton. -.. req:: Bidirectional Gateway routes +.. feat_req:: Bidirectional Gateway routes :id: feat_req__dds__bidirectional_gateway :status: valid @@ -271,28 +271,28 @@ Gateway Requirements Daemon Requirements =================== -.. req:: DDS entity creation +.. feat_req:: DDS entity creation :id: feat_req__dds__daemon_entity_creation :status: valid The DDS Communication Daemon shall create the configured DDS Domains, Topics, DataReaders, and DataWriters according to the deployment lifecycle policy. -.. req:: Serialized DDS write +.. feat_req:: Serialized DDS write :id: feat_req__dds__serialized_write :status: valid The DDS Communication Daemon shall publish serialized DDS samples received for configured writer routes. -.. req:: Serialized DDS read +.. feat_req:: Serialized DDS read :id: feat_req__dds__serialized_read :status: valid The DDS Communication Daemon shall deliver serialized DDS samples received on configured reader routes through runtime IPC. -.. req:: Multiplex configured routes +.. feat_req:: Multiplex configured routes :id: feat_req__dds__multiplex_routes :status: valid @@ -302,35 +302,35 @@ Daemon Requirements Discovery and Availability Requirements ======================================= -.. req:: DDS endpoint discovery +.. feat_req:: DDS endpoint discovery :id: feat_req__dds__endpoint_discovery :status: valid The DDS Communication Daemon shall use DDS participant and endpoint discovery for configured DDS communication routes. -.. req:: Communication-route state +.. feat_req:: Communication-route state :id: feat_req__dds__route_operational_state :status: valid The DDS Communication Daemon shall evaluate the operational state of each configured DDS communication route. -.. req:: Route-state notification +.. feat_req:: Route-state notification :id: feat_req__dds__endpoint_status_notification :status: valid The DDS Communication Daemon shall communicate relevant communication-route state changes to the DDS Binding or DDS Gateway through runtime IPC. -.. req:: Configurable service-availability policy +.. feat_req:: Configurable service-availability policy :id: feat_req__dds__availability_policy :status: valid The deployment configuration shall define how availability of each mapped ``mw::com`` service instance is determined. -.. req:: Availability-policy inputs +.. feat_req:: Availability-policy inputs :id: feat_req__dds__availability_sources :status: valid @@ -339,7 +339,7 @@ Discovery and Availability Requirements * DDS communication-route state; * explicit service-instance state; -.. req:: Required communication routes +.. feat_req:: Required communication routes :id: feat_req__dds__required_availability_routes :status: valid @@ -347,7 +347,7 @@ Discovery and Availability Requirements the DDS communication routes that participate in the service-availability decision. -.. req:: Explicit service-state propagation +.. feat_req:: Explicit service-state propagation :id: feat_req__dds__explicit_service_availability :status: valid @@ -355,21 +355,21 @@ Discovery and Availability Requirements state through a configured DDS communication route. -.. req:: Binding availability propagation +.. feat_req:: Binding availability propagation :id: feat_req__dds__binding_availability :status: valid The DDS Binding shall apply the configured service-availability policy and update the corresponding ``mw::com`` availability state. -.. req:: Gateway availability propagation +.. feat_req:: Gateway availability propagation :id: feat_req__dds__gateway_availability :status: valid The DDS Gateway shall apply the configured service-availability policy and offer or withdraw the corresponding local LoLa service. -.. req:: Native DDS route-based availability +.. feat_req:: Native DDS route-based availability :id: feat_req__dds__native_endpoint_availability :status: valid @@ -377,7 +377,7 @@ Discovery and Availability Requirements service-instance state shall be supportable through a route-based availability policy. -.. req:: Availability recovery +.. feat_req:: Availability recovery :id: feat_req__dds__availability_recovery :status: valid @@ -385,7 +385,7 @@ Discovery and Availability Requirements availability shall be restored only after the configured availability conditions are fulfilled again. -.. req:: Bounded startup data handling +.. feat_req:: Bounded startup data handling :id: feat_req__dds__bounded_startup_handling :status: valid @@ -396,28 +396,28 @@ Discovery and Availability Requirements E2E Requirements ================ -.. req:: Binding-independent E2E API +.. feat_req:: Binding-independent E2E API :id: feat_req__dds__e2e_binding_independent_api :status: valid An application shall use the same ``mw::com`` E2E-facing API when deployed with the DDS Binding or LoLa Binding. -.. req:: Single E2E owner +.. feat_req:: Single E2E owner :id: feat_req__dds__single_e2e_owner :status: valid A protected communication route shall have one configured owner for E2E protection and one configured owner for E2E checking. -.. req:: Disable duplicate LoLa E2E +.. feat_req:: Disable duplicate LoLa E2E :id: feat_req__dds__disable_duplicate_lola_e2e :status: valid LoLa-side E2E processing shall be disabled for an internal DDS Gateway leg when the DDS Gateway owns the same configured E2E profile. -.. req:: Gateway E2E result forwarding +.. feat_req:: Gateway E2E result forwarding :id: feat_req__dds__gateway_e2e_forwarding :status: valid @@ -428,7 +428,7 @@ E2E Requirements Safety Requirements =================== -.. req:: ASIL/QM process boundary +.. feat_req:: ASIL/QM process boundary :id: feat_req__dds__asil_qm_boundary :status: valid @@ -436,7 +436,7 @@ Safety Requirements component and a QM DDS stack shall use the DDS Communication Daemon process boundary. -.. req:: Deployment-specific IPC suitability +.. feat_req:: Deployment-specific IPC suitability :id: feat_req__dds__ipc_suitability :status: valid @@ -446,14 +446,14 @@ Safety Requirements Interoperability Requirements ============================= -.. req:: Native DDS interoperability +.. feat_req:: Native DDS interoperability :id: feat_req__dds__native_interoperability :status: valid A configured route shall be able to interoperate with a compatible native DDS participant using matching Domain, Topic, type, and QoS information. -.. req:: DDS stack abstraction +.. feat_req:: DDS stack abstraction :id: feat_req__dds__stack_abstraction :status: valid