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..0458d260231 --- /dev/null +++ b/docs/features/communication/dds_gateway/architecture/index.rst @@ -0,0 +1,589 @@ +.. + ******************************************************************************* + 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..94679e6e4a7 --- /dev/null +++ b/docs/features/communication/dds_gateway/e2e/index.rst @@ -0,0 +1,230 @@ +.. + ******************************************************************************* + 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 new file mode 100644 index 00000000000..cc2340c18dd --- /dev/null +++ b/docs/features/communication/dds_gateway/index.rst @@ -0,0 +1,225 @@ +.. + ******************************************************************************* + 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: + +DDS Binding and Gateway +####################### + +.. document:: DDS Binding and Gateway + :id: doc__dds_binding_gateway + :status: valid + :safety: ASIL_B + :tags: contribution_request, feature_request + :security: YES + :realizes: wp__feat_request + + +.. toctree:: + :hidden: + + architecture/index.rst + requirements/index.rst + service_discovery/index.rst + e2e/index.rst + use_cases/index.rst + + +Feature Flag +============ + +To activate this feature, use the implementation-specific DDS Binding or DDS +Gateway feature configuration. + + +Abstract +======== + +This feature introduces DDS communication into the ``mw::com`` ecosystem +through two complementary deployment concepts: + +* DDS Binding beneath ``mw::com``; and +* DDS Gateway between LoLa and DDS. + +The DDS Binding allows applications to use DDS while preserving the standard +``mw::com`` concepts. + +The DDS Gateway enables existing LoLa-based applications to communicate with +DDS without changing their application-facing API. + +Both deployment concepts reuse a common DDS Communication Daemon containing the +selected DDS stack and DDS network-facing functionality. + +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. + + +Motivation +========== + +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. + +Applications using ``mw::com`` shall remain independent of the selected +communication technology. + +This feature therefore introduces DDS support while preserving the existing +``mw::com`` programming model. + +The feature provides: + +* 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. + + +Rationale +========= + +DDS Binding and DDS Gateway address different deployment scenarios. + +The DDS Binding provides native DDS communication beneath ``mw::com`` while +preserving the existing application programming model. + +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. + +Both deployment concepts reuse the same DDS Communication Daemon and DDS stack +integration. + +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. + + +Specification +============= + +The DDS Binding and DDS Gateway specification consists of the following +chapters. + +Architecture +------------ + +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. + +Service Discovery and Availability +---------------------------------- + +The Service Discovery chapter describes: + +* 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 +--------------------- + +The E2E chapter describes: + +* ownership of E2E processing; +* E2E Protect and E2E Check; +* Binding deployment; +* Gateway deployment; +* interaction with the DDS Communication Daemon; and +* application-facing E2E semantics. + +Use Cases +--------- + +The Use Cases chapter illustrates supported deployment scenarios and expected +runtime behavior. + + +Backwards Compatibility +======================= + +Existing ``mw::com`` applications continue to use the standard ``mw::com`` API. + +Existing LoLa application's deployment remain unchanged unless DDS Gateway communication is +explicitly configured for this application requiring communication over DDS network. + + +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. + +System integrators configure DDS deployment information, including Topics, +runtime types, Domains, QoS, communication routes, availability policies, and +E2E settings. + +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..0721a8dd074 --- /dev/null +++ b/docs/features/communication/dds_gateway/requirements/index.rst @@ -0,0 +1,461 @@ +.. + ******************************************************************************* + 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..6f91b3e475e --- /dev/null +++ b/docs/features/communication/dds_gateway/service_discovery/index.rst @@ -0,0 +1,613 @@ +.. + ******************************************************************************* + 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..eee7cd9c0e9 --- /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.