Transport Requirements

This section defines requirements for the transport layer implementation in OpenSOMEIP, including UDP and TCP transports.

Overview

The transport layer provides:

1. UDP transport with multicast support

2. TCP transport with connection management

3. Abstract transport interface for extensibility

Requirements

UDP Transport

Requirement: UDP Bind and Unicast Send/Receive REQ_TRANSPORT_001a

status: implemented priority: high satisfies: feat_req_someip_32, feat_req_someip_318, feat_req_someip_319, feat_req_someip_33

The implementation shall provide UDP transport that supports binding to local address and port, sending messages to unicast destinations, and receiving messages from any source. Rationale: UDP unicast is the foundation for SOME/IP point-to-point communication. Code Location: src/transport/udp_transport.cpp

Requirement: UDP Multicast Support REQ_TRANSPORT_001b

status: implemented priority: high satisfies: feat_req_someip_584, feat_req_someip_811, feat_req_someip_315, feat_req_someip_316

The implementation shall support sending to multicast destinations and multicast group join/leave for receiving multicast traffic. Rationale: Multicast is required for Service Discovery and eventgroup subscriptions. Code Location: src/transport/udp_transport.cpp

Requirement: Non-Blocking I/O and Thread Safety REQ_TRANSPORT_001c

status: implemented priority: high satisfies: feat_req_someip_659, feat_req_someip_664, feat_req_someip_317

The implementation shall provide non-blocking I/O with configurable timeouts and thread-safe operation for concurrent send/receive. Rationale: Non-blocking I/O and thread safety enable integration with event loops and multi-threaded applications. Code Location: src/transport/udp_transport.cpp

TCP Transport

Requirement: TCP Client/Server Modes REQ_TRANSPORT_002a

status: implemented priority: high satisfies: feat_req_someip_32, feat_req_someip_325, feat_req_someip_323, feat_req_someip_324

The implementation shall provide a TCP transport (TcpTransport) that supports client mode (connect to remote server) and server mode (accept incoming connections). Rationale: Client and server modes cover both initiator and responder roles in TCP communication. Code Location: src/transport/tcp_transport.cpp

Requirement: TCP Framing and State Management REQ_TRANSPORT_002b

status: implemented priority: high satisfies: feat_req_someip_585, feat_req_someip_644, feat_req_someip_645, feat_req_someip_661

The implementation shall provide message framing over TCP streams, connection state management, automatic reconnection (configurable), and thread-safe operation. Rationale: TCP streams require framing to delimit messages; state management enables robust reconnection. Code Location: src/transport/tcp_transport.cpp

Connection Management

Requirement: Connection State Tracking and Notification REQ_TRANSPORT_003a

status: implemented priority: medium satisfies: feat_req_someip_326, feat_req_someip_644, feat_req_someip_646

The TCP transport shall track connection state (disconnected, connecting, connected) and notify listeners of connection state changes. Rationale: State tracking and notifications enable applications to react to connection lifecycle events. Code Location: src/transport/tcp_transport.cpp

Requirement: Graceful Shutdown and Error Handling REQ_TRANSPORT_003b

status: implemented priority: medium satisfies: feat_req_someip_647, feat_req_someip_678, feat_req_someip_679, feat_req_someip_680

The TCP transport shall support graceful connection shutdown, handle connection errors and timeouts, and support multiple simultaneous connections (server mode). Rationale: Graceful shutdown and error handling ensure clean resource release and predictable behavior on failures. Code Location: src/transport/tcp_transport.cpp

Error Recovery

Requirement: Retry Send on Transient Errors REQ_TRANSPORT_004a

status: implemented priority: medium satisfies: feat_req_someip_429, feat_req_someip_430, feat_req_someip_434, feat_req_someip_435

The transport layer shall retry send operations on transient errors (e.g., EAGAIN, EWOULDBLOCK) according to configurable retry policy. Rationale: Transient errors are common in non-blocking I/O and often resolve on retry. Code Location: src/transport/udp_transport.cpp, src/transport/tcp_transport.cpp

Requirement: Socket Close/Reopen on Persistent Errors REQ_TRANSPORT_004b

status: implemented priority: medium satisfies: feat_req_someip_436, feat_req_someip_437, feat_req_someip_438

The transport layer shall close and reopen sockets when persistent errors occur (e.g., connection reset, broken pipe). Rationale: Persistent errors indicate the socket is unusable; reopening restores communication. Code Location: src/transport/udp_transport.cpp, src/transport/tcp_transport.cpp

Requirement: Error Logging with Detail REQ_TRANSPORT_004c

status: implemented priority: medium satisfies: feat_req_someip_439, feat_req_someip_440, feat_req_someip_441

The transport layer shall log errors with sufficient detail for diagnosis (errno, endpoint, operation context). Rationale: Detailed error logs enable rapid troubleshooting in production environments. Code Location: src/transport/udp_transport.cpp, src/transport/tcp_transport.cpp

Requirement: Return Error Codes and Configurable Retry REQ_TRANSPORT_004d

status: implemented priority: medium satisfies: feat_req_someip_326, feat_req_someip_371, feat_req_someip_442, feat_req_someip_443

The transport layer shall return appropriate error codes to callers and support configurable retry policies (count, delay). Rationale: Error codes allow application-layer handling; configurable retry adapts to different deployment requirements. Code Location: src/transport/udp_transport.cpp, src/transport/tcp_transport.cpp

Transport Interface

Requirement: Abstract Transport Interface REQ_TRANSPORT_005

status: implemented priority: high satisfies: feat_req_someip_32, feat_req_someip_56, feat_req_someip_31

The implementation shall provide an abstract transport interface (ITransport) that defines: start(): Initialize and start the transport stop(): Stop the transport and release resources send(Message&, Endpoint&): Send a message set_listener(ITransportListener*): Set message listener is_running(): Check transport state Rationale: Abstract interface enables transport-agnostic application code and testing. Code Location: include/transport/transport.h

Endpoint Configuration

Requirement: Endpoint Configuration REQ_TRANSPORT_006

status: implemented priority: medium satisfies: feat_req_someip_32, feat_req_someip_659, feat_req_someip_660, feat_req_someip_661, feat_req_someip_733

The implementation shall provide endpoint configuration: IP address (IPv4 and IPv6) Port number Protocol type (UDP/TCP) Validation of endpoint parameters String representation for logging Rationale: Proper endpoint handling is fundamental to network communication. Code Location: include/transport/endpoint.h

Transport Protocol Binding

Requirement: nPDU Feature Support REQ_TRANSPORT_010

status: implemented priority: high satisfies: feat_req_someip_702, feat_req_someip_741, feat_req_someip_663

The software shall support transporting more than one SOME/IP message in a single transport layer PDU (nPDU feature). For cyclic senders, nPDU shall be supported without explicit configuration. Rationale: nPDU reduces per-message overhead for high-frequency communication. Code Location: src/transport/udp_transport.cpp (send_data, receive_loop)

Requirement: UDP Multicast Support REQ_TRANSPORT_011

status: implemented priority: high satisfies: feat_req_someip_811, feat_req_someip_812, feat_req_someip_814

The software shall support UDP unicast and multicast transmission. Multicast eventgroups shall use unicast for initial field events. Clients shall support receiving via unicast and/or multicast. Rationale: Multicast reduces bandwidth for events delivered to many subscribers. Code Location: src/transport/udp_transport.cpp (join_multicast_group, configure_multicast)

Requirement: Multicast Threshold Switching REQ_TRANSPORT_012

status: draft priority: medium satisfies: feat_req_someip_813

The software shall support dynamic switching of eventgroups between unicast and multicast based on the Multicast-Threshold configuration. Rationale: Dynamic switching optimizes bandwidth based on actual subscriber count. Code Location: src/transport/udp_transport.cpp, include/sd/sd_types.h

Requirement: Internal Message Multiplexing REQ_TRANSPORT_013

status: draft priority: high satisfies: feat_req_someip_732

The software shall support internal de/multiplexing of SOME/IP messages independent of the number of controllers, cores, and IP addresses. Rationale: Internal multiplexing decouples service routing from physical network topology. Code Location: src/rpc/rpc_server.cpp (service_id_ filtering), src/sd/sd_server.cpp

Requirement: Port Configuration REQ_TRANSPORT_014

status: implemented priority: high satisfies: feat_req_someip_658, feat_req_someip_676, feat_req_someip_733

The software shall read port numbers from configuration files. Port 30490 shall only be used for SOME/IP-SD, not application communication. Rationale: Configuration-driven ports ensure deterministic network resource allocation. Code Location: include/transport/udp_transport.h (UdpTransportConfig), include/sd/sd_types.h (SdConfig)

Requirement: Ephemeral Port Range REQ_TRANSPORT_015

status: implemented priority: medium satisfies: feat_req_someip_661

The software shall use IETF/IANA ephemeral port range (49152-65535) for dynamic ports. Rationale: Ephemeral port range compliance avoids conflicts with well-known services. Code Location: include/transport/endpoint.h, src/transport/udp_transport.cpp

TCP Connection Management

Requirement: Client-Initiated TCP Connection REQ_TRANSPORT_016

status: implemented priority: high satisfies: feat_req_someip_646, feat_req_someip_647

The software shall open TCP connections from the client side when the first method call or notification subscription is needed. The client is responsible for re-establishing failed connections. Rationale: Client-initiated connections simplify server-side connection management. Code Location: src/transport/tcp_transport.cpp (connect_internal)

Requirement: TCP Connection Sharing REQ_TRANSPORT_017

status: implemented priority: high satisfies: feat_req_someip_644, feat_req_someip_645

The software shall use a single TCP connection for all methods, events, and notifications of a service instance. TCP connections shall be shared across services to minimize connection count. Rationale: Connection sharing minimizes TCP connection overhead and OS resource usage. Code Location: src/transport/tcp_transport.cpp (connection sharing logic)

Requirement: TCP Connection Closure REQ_TRANSPORT_018

status: implemented priority: high satisfies: feat_req_someip_678, feat_req_someip_679, feat_req_someip_680

TCP connections shall be closed by the client when no longer required or when all services are unavailable. The server shall not close connections preemptively. Rationale: Client-controlled closure prevents servers from disrupting active communication. Code Location: src/transport/tcp_transport.cpp (disconnect, disconnect_internal)

Requirement: TCP Timeout on Connection Loss REQ_TRANSPORT_019

status: implemented priority: high satisfies: feat_req_someip_326, feat_req_someip_681

The software shall treat outstanding requests as timeouts when the TCP connection is lost. Rationale: Timeout handling prevents clients from waiting indefinitely for responses on broken connections. Code Location: src/transport/tcp_transport.cpp (connection_monitor_loop)

Magic Cookie Support

Requirement: TCP Magic Cookie Messages REQ_TRANSPORT_020

status: implemented priority: medium satisfies: feat_req_someip_586, feat_req_someip_591, feat_req_someip_592, feat_req_someip_609, feat_req_someip_619

The software shall support SOME/IP Magic Cookie Messages for TCP stream resynchronization. Each TCP segment shall start with a Magic Cookie (Service ID 0xFFFF, Method ID 0x0000/0x8000, Length 8, Client ID 0xDEAD, Session ID 0xBEEF). Rationale: Magic Cookies enable TCP stream resynchronization after framing errors. Code Location: src/transport/tcp_transport.cpp (parse_message_from_buffer)

Requirement: Magic Cookie Fallback Heuristic REQ_TRANSPORT_021

status: implemented priority: medium satisfies: feat_req_someip_593, feat_req_someip_594

If the software cannot access TCP segmentation, it shall insert Magic Cookie Messages every 10 seconds on active connections. Rationale: Periodic Magic Cookies provide a fallback when TCP segmentation info is unavailable. Code Location: src/transport/tcp_transport.cpp

Service Instance Binding

Requirement: Multiple Service Instance Port Binding REQ_TRANSPORT_022

status: implemented priority: high satisfies: feat_req_someip_445, feat_req_someip_636, feat_req_someip_967, feat_req_someip_1079, feat_req_someip_444

The software shall support multiple service instances on different ECUs and on the same ECU. Multiple instances of the same service on one ECU shall listen on different ports. Rationale: Multi-port binding enables horizontal scaling of service instances. Code Location: src/sd/sd_server.cpp (offer_service per instance), include/sd/sd_types.h

Requirement: Client Server Address Resolution REQ_TRANSPORT_023

status: implemented priority: high satisfies: feat_req_someip_660, feat_req_someip_665

The client shall use the IP address and port number announced by the server via SOME/IP-SD for communication. Rationale: SD-announced address resolution ensures clients connect to the correct server endpoint. Code Location: src/sd/sd_client.cpp (process_offer_entry, ip_address from option)

Requirement: Unaligned Message Reception REQ_TRANSPORT_024

status: implemented priority: medium satisfies: feat_req_someip_664, feat_req_someip_668

The software shall be capable of receiving unaligned SOME/IP messages when multiple messages are transported in a single UDP or TCP PDU. Rationale: Unaligned message handling supports nPDU and multi-message PDUs. Code Location: src/transport/tcp_transport.cpp (parse_message_from_buffer), src/transport/udp_transport.cpp

Magic Cookie Details

Requirement: Magic Cookie Message Format REQ_TRANSPORT_025

status: implemented priority: medium satisfies: feat_req_someip_589, feat_req_someip_607

The software shall use the specified Magic Cookie message layout: Service ID 0xFFFF, Method ID 0x0000/0x8000, Length 8, Client ID 0xDEAD, Session ID 0xBEEF. Rationale: A well-defined Magic Cookie format ensures both peers can detect the resync marker. Code Location: src/transport/tcp_transport.cpp

Requirement: Error - UDP Send Failure REQ_TRANSPORT_001_E01

status: implemented priority: high

The software shall return an error and log details when UDP send fails. Rationale: Network unreachable and other send errors must be reported for diagnostics. Error Handling: Return SEND_FAILED error code with errno details. Code Location: src/transport/udp_transport.cpp

Requirement: Error - UDP Bind Failure REQ_TRANSPORT_001_E02

status: implemented priority: high

The software shall return an error when UDP socket binding fails. Rationale: Port conflicts must be reported clearly for deployment troubleshooting. Error Handling: Return BIND_FAILED error code. Code Location: src/transport/udp_transport.cpp

Requirement: Error - TCP Connection Refused REQ_TRANSPORT_002_E01

status: implemented priority: high

The software shall handle TCP connection refused by reporting the error and scheduling reconnection. Rationale: Connection refused indicates the server is not yet available. Error Handling: Log error, schedule reconnection with configurable backoff. Code Location: src/transport/tcp_transport.cpp

Requirement: Error - TCP Connection Reset REQ_TRANSPORT_002_E02

status: implemented priority: high

The software shall handle TCP connection resets by transitioning to DISCONNECTED and timing out pending requests. Rationale: Abrupt connection resets must trigger proper cleanup. Error Handling: Transition to DISCONNECTED, timeout pending requests, log reset. Code Location: src/transport/tcp_transport.cpp

Requirement: Error - Multicast Join Failure REQ_TRANSPORT_011_E01

status: implemented priority: medium

The software shall return an error when multicast group join fails. Rationale: Failed multicast joins prevent SD and event reception. Error Handling: Return MULTICAST_ERROR and log group address and interface. Code Location: src/transport/udp_transport.cpp

Requirement: Error - Port Already In Use REQ_TRANSPORT_014_E01

status: implemented priority: high

The software shall detect and report port conflicts during service startup. Rationale: Port conflicts prevent service startup and must be caught early. Error Handling: Return BIND_FAILED with port number in error message. Code Location: src/transport/udp_transport.cpp, src/transport/tcp_transport.cpp

Requirement: Error - TCP Reconnection Exhaustion REQ_TRANSPORT_016_E01

status: implemented priority: medium

The software shall stop reconnection attempts after the configured maximum and report failure. Rationale: Unbounded reconnection wastes resources when the server is permanently unavailable. Error Handling: Report RECONNECT_EXHAUSTED, transition to DISCONNECTED. Code Location: src/transport/tcp_transport.cpp

Requirement: Error - TCP Message Framing Error REQ_TRANSPORT_002_E03

status: implemented priority: high

The software shall handle TCP framing errors by attempting resynchronization or resetting the connection. Rationale: Framing errors corrupt the TCP stream and prevent further message parsing. Error Handling: Attempt Magic Cookie resync if available, otherwise reset connection. Code Location: src/transport/tcp_transport.cpp

Requirement: Error - UDP Receive Buffer Too Small REQ_TRANSPORT_001_E03

status: implemented priority: medium

The software shall handle UDP receive buffer truncation by logging a warning. Rationale: Truncated UDP messages cannot be processed correctly. Error Handling: Log warning with received vs expected size, discard message. Code Location: src/transport/udp_transport.cpp

Requirement: Error - Endpoint Address Format Invalid REQ_TRANSPORT_006_E01

status: implemented priority: medium

The software shall validate endpoint address format during configuration and report errors. Rationale: Invalid addresses prevent communication and must be caught at configuration time. Error Handling: Return INVALID_ENDPOINT error with address string. Code Location: include/transport/endpoint.h

Requirement: Error - TCP Server Socket Exhaustion REQ_TRANSPORT_003_E01

status: implemented priority: medium

The software shall reject new TCP connections when the maximum connection limit is reached. Rationale: Connection limits prevent resource exhaustion from excessive clients. Error Handling: Reject connection, log client address and current connection count. Code Location: src/transport/tcp_transport.cpp

Requirement: Error - TCP Send on Disconnected Socket REQ_TRANSPORT_002_E04

status: implemented priority: high

The software shall return an error when attempting to send on a disconnected TCP connection. Rationale: Send on disconnected socket causes undefined behavior. Error Handling: Return SEND_FAILED, queue message for retry after reconnect. Code Location: src/transport/tcp_transport.cpp

Requirement: Error - UDP Multicast TTL Configuration REQ_TRANSPORT_011_E02

status: implemented priority: low

The software shall configure the multicast TTL to limit message propagation scope. Rationale: Incorrect TTL causes multicast messages to leak across network boundaries. Error Handling: Apply configured TTL, default to 1 if not specified. Code Location: src/transport/udp_transport.cpp

Traceability

Implementation Files

• include/transport/transport.h - Transport interface

• include/transport/udp_transport.h - UDP transport interface

• include/transport/tcp_transport.h - TCP transport interface

• include/transport/endpoint.h - Endpoint structure

• src/transport/udp_transport.cpp - UDP implementation

• src/transport/tcp_transport.cpp - TCP implementation

Test Files

• tests/test_udp_transport.cpp - UDP transport tests

• tests/test_tcp_transport.cpp - TCP transport tests

Examples

• examples/basic/hello_world_client.cpp - Basic UDP client

• examples/basic/hello_world_server.cpp - Basic UDP server

• examples/advanced/tcp_client.cpp - TCP client example

• examples/advanced/tcp_server.cpp - TCP server example