Service Discovery Requirements¶
This section defines Software Low-Level Requirements (SW-LLR) for the SOME/IP Service Discovery (SOME/IP-SD) module. SD is used to locate service instances, detect their availability, and implement Publish/Subscribe.
Overview¶
The Service Discovery module handles:
SD message parsing and generation
Service offer and find operations
Eventgroup subscription management
TTL-based service availability tracking
Reboot detection
SD Message Format¶
Header Requirements¶
The software shall use Service ID 0xFFFF for all SOME/IP-SD messages. Rationale: Service ID 0xFFFF is reserved for Service Discovery. Code Location: |
The software shall use Method ID 0x8100 for all SOME/IP-SD messages. Rationale: Method ID 0x8100 is defined for SD messages. Code Location: |
The software shall use Client ID 0x0000 for all SOME/IP-SD messages. Rationale: Client ID 0x0000 is reserved for SD. Code Location: |
The software shall use Protocol Version 0x01 for all SOME/IP-SD messages. Rationale: SOME/IP-SD uses Protocol Version 1. Code Location: |
The software shall use Interface Version 0x01 for all SOME/IP-SD messages. Rationale: SOME/IP-SD uses Interface Version 1. Code Location: |
The software shall use Message Type 0x02 (NOTIFICATION) for all SOME/IP-SD messages. Rationale: SD messages are notifications. Code Location: |
The software shall use Return Code 0x00 (E_OK) for all SOME/IP-SD messages. Rationale: SD messages always use E_OK return code. Code Location: |
SD Flags Parsing¶
The software shall parse the SD Flags byte from the first byte (byte 0) of the SOME/IP-SD payload. Rationale: Flags byte contains control flags for SD processing. Code Location: |
The software shall extract the Reboot flag from bit 7 (most significant bit) of the SD Flags byte. Rationale: Reboot flag indicates ECU reboot for session management. Code Location: |
The software shall extract the Unicast flag from bit 6 of the SD Flags byte. Rationale: Unicast flag indicates unicast-capable endpoint. Code Location: |
The software shall set reserved flag bits (bits 5-0) to zero when generating SD messages. Rationale: Reserved bits must be zero per specification. Code Location: |
The software shall ignore reserved flag bits (bits 5-0) when parsing received SD messages. Rationale: Forward compatibility with future flag definitions. Code Location: |
The software shall reject messages that do not match the required SD header values (Service ID 0xFFFF, Method ID 0x8100). Rationale: Invalid SD header indicates malformed message. Error Handling: Discard message and log error. Code Location: |
The software shall return an error when the SD payload is too short to contain the Flags byte. Rationale: Minimum SD payload must contain Flags and Reserved bytes. Error Handling: Return MALFORMED_MESSAGE error. Code Location: |
Entry Parsing¶
Entries Array¶
The software shall parse the Entries Length field as a 4-byte Big Endian value from bytes 4-7 of the SOME/IP-SD payload. Rationale: Entries Length indicates the size of the entries array. Code Location: |
The software shall parse the Entry Type from the first byte of each SD entry. Rationale: Entry Type determines the entry format and semantics. Code Location: |
The software shall use an entry size of 16 bytes for service-type entries (Type 0, Type 1). Rationale: Fixed entry size per specification. Code Location: |
The software shall parse Entry Type 0 as a Find Service entry, extracting Service ID, Instance ID, Major Version, and TTL. Rationale: Find Service is used by clients to discover services. Code Location: |
The software shall parse Entry Type 1 as an Offer Service entry, extracting Service ID, Instance ID, Major Version, Minor Version, and TTL. Rationale: Offer Service announces service availability. Code Location: |
The software shall parse Entry Type 6 as a Subscribe Eventgroup entry, extracting Service ID, Instance ID, Eventgroup ID, Major Version, and TTL. Rationale: Subscribe Eventgroup requests event notifications. Code Location: |
The software shall parse Entry Type 7 as a Subscribe Eventgroup Ack entry, extracting Service ID, Instance ID, Eventgroup ID, and Reserved/Counter. Rationale: Subscribe Eventgroup Ack confirms or denies subscription. Code Location: |
Entry Fields¶
The software shall parse the Service ID from bytes 4-5 of each SD entry in Big Endian byte order. Rationale: Service ID identifies the service. Code Location: |
The software shall parse the Instance ID from bytes 6-7 of each SD entry in Big Endian byte order. Rationale: Instance ID identifies the service instance. Code Location: |
The software shall interpret Instance ID 0xFFFF as a wildcard matching all service instances. Rationale: Wildcard for discovering any instance of a service. Code Location: |
The software shall parse the combined Major Version (1 byte) and TTL (3 bytes) from bytes 8-11 of each SD entry in Big Endian byte order. Rationale: Major Version and TTL share a 4-byte field. Code Location: |
The software shall parse the Minor Version from bytes 12-15 of Offer Service entries in Big Endian byte order. Rationale: Minor Version indicates compatible version range. Code Location: |
The software shall parse the Eventgroup ID from bytes 14-15 of Subscribe Eventgroup entries in Big Endian byte order. Rationale: Eventgroup ID identifies the subscribed event group. Code Location: |
Entry Error Handling¶
The software shall skip entries with unknown Entry Type values and log a warning, continuing to process remaining entries. Rationale: Forward compatibility with new entry types. Error Handling: Log warning and skip entry. Code Location: |
The software shall return an error when an entry would extend beyond the declared Entries Length boundary. Rationale: Prevents buffer overread. Error Handling: Return MALFORMED_MESSAGE error. Code Location: |
The software shall return an error when the Entries Length field exceeds the remaining SD payload size. Rationale: Prevents buffer overread. Error Handling: Return MALFORMED_MESSAGE error. Code Location: |
The software shall log a warning when the Entries Length is not an exact multiple of the entry size. Rationale: May indicate malformed message or version mismatch. Error Handling: Log warning and process complete entries. Code Location: |
TTL Processing¶
The software shall store the TTL value for each service offer received, associated with the Service ID and Instance ID. Rationale: TTL tracks service availability duration. Code Location: |
The software shall decrement the stored TTL value for each active service offer every second. Rationale: TTL countdown for service expiration. Code Location: |
The software shall remove a service from the available services list when its TTL value reaches zero. Rationale: Expired services are no longer considered available. Code Location: |
The software shall interpret TTL value 0xFFFFFF (16777215 seconds) as an infinite lifetime that shall not be decremented. Rationale: Special value for permanent service availability. Code Location: |
The software shall interpret TTL value 0 as an immediate Stop Offer, removing the service from the available list without delay. Rationale: TTL 0 signals service is no longer available. Code Location: |
The software shall reset the TTL to the new value when a new Offer is received for an already-known service instance. Rationale: Refreshes service availability on repeated offers. Code Location: |
The software shall notify the application layer when a service becomes available (offer received) or unavailable (TTL expired or stop offer). Rationale: Application needs to know service availability. Code Location: |
TTL Error Handling¶
The software shall prevent TTL underflow by not decrementing TTL values that are already zero. Rationale: Prevents unsigned integer underflow. Error Handling: Skip decrement for TTL = 0. Code Location: |
The software shall return an error or drop oldest entry when the maximum number of tracked services is reached. Rationale: Resource management for memory-constrained systems. Error Handling: Return RESOURCE_EXHAUSTED or apply eviction policy. Code Location: |
Reboot Detection¶
The software shall store the Session ID from SD messages, associated with the source endpoint (IP address and port). Rationale: Session ID tracking enables reboot detection. Code Location: |
The software shall compare the Session ID in newly received SD messages against the stored Session ID for the source endpoint. Rationale: Session ID regression indicates reboot. Code Location: |
The software shall detect a reboot condition when the new Session ID is less than the stored Session ID (not within wrap-around threshold). Rationale: Lower Session ID indicates ECU restarted. Code Location: |
The software shall detect a reboot condition when the Reboot flag (bit 7 of SD Flags) is set in a received SD message. Rationale: Explicit reboot indication from sender. Code Location: |
The software shall trigger a reboot detection event when a reboot condition is detected for a remote endpoint. Rationale: Application may need to handle reconnection. Code Location: |
The software shall clear all cached service instances associated with a remote endpoint when a reboot is detected. Rationale: Services from rebooted ECU are no longer valid. Code Location: |
The software shall update the stored Session ID to the new value after successfully processing an SD message. Rationale: Enables detection of subsequent reboots. Code Location: |
Reboot Detection Error Handling¶
The software shall correctly handle Session ID wrap-around (0xFFFF to 0x0001) and not falsely detect it as a reboot. Rationale: Normal Session ID progression should not trigger reboot. Error Handling: Use wrap-around detection threshold. Code Location: |
The software shall store the Session ID from a new endpoint without triggering reboot detection. Rationale: First contact cannot be a reboot. Error Handling: Store Session ID and skip reboot check. Code Location: |
Options Parsing¶
Options Array¶
The software shall parse the Options Length field as a 4-byte Big Endian value from the position immediately after the Entries Array. Rationale: Options Length indicates the size of the options array. Code Location: |
The software shall parse the Option Type from byte 2 of each SD option (after length field). Rationale: Option Type determines the option format. Code Location: |
The software shall parse the Option Length from bytes 0-1 of each SD option in Big Endian byte order. Rationale: Option Length indicates the option data size. Code Location: |
IPv4 Endpoint Option¶
The software shall recognize Option Type 0x04 as an IPv4 Endpoint option. Rationale: IPv4 Endpoint provides service endpoint information. Code Location: |
The software shall extract the IPv4 address from bytes 4-7 of the IPv4 Endpoint option. Rationale: IP address is needed for service communication. Code Location: |
The software shall extract the port number from bytes 9-10 of the IPv4 Endpoint option in Big Endian byte order. Rationale: Port number is needed for service communication. Code Location: |
The software shall extract the L4 protocol from byte 8 of the IPv4 Endpoint option (UDP=0x11, TCP=0x06). Rationale: Protocol type determines transport layer. Code Location: |
IPv6 Endpoint Option¶
The software shall recognize Option Type 0x06 as an IPv6 Endpoint option. Rationale: IPv6 Endpoint provides service endpoint information. Code Location: |
The software shall extract the IPv6 address from bytes 4-19 of the IPv6 Endpoint option (16 bytes). Rationale: IPv6 address is needed for service communication. Code Location: |
The software shall extract the port number from bytes 21-22 of the IPv6 Endpoint option in Big Endian byte order. Rationale: Port number is needed for service communication. Code Location: |
The software shall extract the L4 protocol from byte 20 of the IPv6 Endpoint option (UDP=0x11, TCP=0x06). Rationale: Protocol type determines transport layer. Code Location: |
Configuration Option¶
The software shall recognize Option Type 0x01 as a Configuration option. Rationale: Configuration option provides additional service parameters. Code Location: |
The software shall extract the configuration string from the Configuration option payload. Rationale: Configuration data for service parameters. Code Location: |
Multicast Endpoint Options¶
The software shall recognize Option Type 0x14 as an IPv4 Multicast Endpoint option. Rationale: Multicast endpoint for event distribution. Code Location: |
The software shall recognize Option Type 0x16 as an IPv6 Multicast Endpoint option. Rationale: Multicast endpoint for event distribution. Code Location: |
Option Index References¶
The software shall parse the First Option Index (1st options run) from byte 1 of each SD entry. Rationale: Links entry to its endpoint options. Code Location: |
The software shall parse the Second Option Index (2nd options run) from byte 2 of each SD entry. Rationale: Links entry to additional endpoint options. Code Location: |
The software shall parse the option counts (number of options in each run) from byte 3 of each SD entry. Rationale: Determines how many options to read for each run. Code Location: |
Options Error Handling¶
The software shall skip options with unknown Option Type values and log a warning, continuing to process remaining options. Rationale: Forward compatibility with new option types. Error Handling: Log warning and skip option. Code Location: |
The software shall return an error when an option would extend beyond the declared Options Length boundary. Rationale: Prevents buffer overread. Error Handling: Return MALFORMED_MESSAGE error. Code Location: |
The software shall return an error when the Options Length field exceeds the remaining SD payload size. Rationale: Prevents buffer overread. Error Handling: Return MALFORMED_MESSAGE error. Code Location: |
The software shall log a warning when an endpoint option contains an invalid IP address (0.0.0.0 or broadcast address). Rationale: Invalid addresses may indicate configuration errors. Error Handling: Log warning but process option. Code Location: |
The software shall return an error when an entry’s option index refers to a non-existent option. Rationale: Invalid option reference detection. Error Handling: Return MALFORMED_MESSAGE error. Code Location: |
Service State Machine¶
The software shall transition a service to the Find state when an application requests to find a service. Rationale: State machine for service discovery. Code Location: |
The software shall generate and send a Find Service (Type 0) entry when in the Find state. Rationale: Initiates service discovery. Code Location: |
The software shall transition a service to the Available state when a matching Offer Service entry is received. Rationale: Service has been discovered. Code Location: |
The software shall generate and send an Offer Service (Type 1) entry when a local service becomes available. Rationale: Announces service availability. Code Location: |
The software shall generate and send an Offer Service entry with TTL=0 when a local service becomes unavailable. Rationale: Announces service unavailability. Code Location: |
Subscription Management¶
The software shall generate and send a Subscribe Eventgroup (Type 6) entry when an application requests to subscribe to an eventgroup. Rationale: Initiates event subscription. Code Location: |
The software shall generate and send a Subscribe Eventgroup Ack (Type 7) entry when a subscription request is accepted. Rationale: Confirms subscription to client. Code Location: |
The software shall generate and send a Subscribe Eventgroup Ack entry with TTL=0 when a subscription request is rejected. Rationale: Rejects subscription to client. Code Location: |
The software shall automatically renew subscriptions by sending a new Subscribe Eventgroup entry before the subscription TTL expires. Rationale: Maintains continuous event subscription. Code Location: |
The software shall generate and send a Subscribe Eventgroup entry with TTL=0 when an application requests to unsubscribe. Rationale: Terminates event subscription. Code Location: |
Timing and Repetition¶
The software shall wait for a configurable initial delay before sending the first Offer Service message after startup. Rationale: Allows network to stabilize. Code Location: |
The software shall repeat Offer Service messages with exponentially increasing intervals during the repetition phase. Rationale: Ensures discovery while reducing network traffic. Code Location: |
The software shall send Offer Service messages at a configurable cyclic interval during the main phase. Rationale: Periodic refresh of service availability. Code Location: |
The software shall repeat Find Service messages with increasing intervals until the service is found or maximum attempts reached. Rationale: Persistent service discovery. Code Location: |
SD Communication Phases¶
The software shall implement the Initial Wait Phase where SD messages are delayed by a configurable random time between INITIAL_DELAY_MIN and INITIAL_DELAY_MAX before the first message is sent. Rationale: Initial wait phase prevents network storms at startup. Code Location: |
The software shall implement the Repetition Phase where SD messages are sent with exponentially increasing intervals (base delay times 2^repetition) for a configurable number of repetitions. Rationale: Exponential backoff during repetition reduces collision probability. Code Location: |
The software shall implement the Main Phase where SD messages are sent at a configurable cyclic interval (CYCLIC_OFFER_DELAY). Rationale: Stable main phase rate provides predictable service availability announcements. Code Location: |
The software shall send StopOffer entries with TTL=0 for all offered services during shutdown. Rationale: Explicit stop-offer on shutdown enables immediate cleanup of cached service state. Code Location: |
SD Entry Processing¶
The software shall process FindService entries (Type 0) by responding with OfferService entries for matching services. A FindService with Service ID 0xFFFF and Instance ID 0xFFFF shall match all services. Rationale: FindService enables on-demand service discovery. Code Location: |
The software shall process OfferService entries (Type 1) by storing the service endpoint information and notifying subscribed clients of service availability. Rationale: OfferService proactively announces service availability. Code Location: |
The software shall process StopOfferService entries (Type 1 with TTL=0) by removing the service from the known services list and notifying clients of service unavailability. Rationale: Subscription management enables selective event delivery. Code Location: |
The software shall process SubscribeEventgroup entries (Type 6) by validating the subscription and responding with an Ack or Nack. Rationale: ACK/NACK provides explicit feedback to subscribers. Code Location: |
The software shall process StopSubscribeEventgroup entries (Type 6 with TTL=0) by removing the subscription. Rationale: NACK enables the server to reject invalid subscriptions. Code Location: |
The software shall process SubscribeEventgroupAck entries (Type 7 with TTL>0) by activating event reception for the subscribed eventgroup. Rationale: Entry type dispatch enables parallel processing of mixed SD messages. Code Location: |
The software shall process SubscribeEventgroupNack entries (Type 7 with TTL=0) by marking the subscription as rejected. Rationale: Options provide flexible endpoint and configuration metadata. Code Location: |
SD Option Handling¶
The software shall support the Load Balancing Option (Type 0x02) containing priority and weight fields for load distribution. Rationale: Load balancing distributes traffic across equivalent service instances. Code Location: |
The software shall support the IPv4 SD Endpoint Option (Type 0x24) for specifying the SD communication endpoint. Rationale: IPv4 endpoint options carry the transport address for service communication. Code Location: |
The software shall support the IPv6 SD Endpoint Option (Type 0x26) for specifying the SD communication endpoint. Rationale: Multicast options specify the group address for multicast event delivery. Code Location: |
The software shall support referencing options from entries using option index and run length fields. Rationale: Configuration options carry key-value service metadata. Code Location: |
The software shall handle missing mandatory options by rejecting the entry that references them. Rationale: State machines ensure correct SD behavior through defined phase transitions. Code Location: |
The software shall handle redundant (duplicate) options gracefully by using the first valid option. Rationale: Server state machine governs offer/stop-offer lifecycle. Code Location: |
The software shall handle conflicting options by rejecting the entry containing the conflicting options. Rationale: Client state machine governs find/subscribe lifecycle. Code Location: |
SD State Machines¶
The software shall implement the server service state machine with states: Down, InitialWait, Repetition, and Main. Transitions shall follow the specification state machine. Rationale: Client endpoint extraction from subscription determines event delivery target. Code Location: |
The software shall implement the client service state machine with states: Down, InitialWait, Repetition, Main, and Stopped. Transitions shall follow the specification state machine. Rationale: Error reporting via SdResult enables application-level error handling. Code Location: |
The software shall implement the eventgroup subscription state machine for managing subscription lifecycle. Rationale: Serialization/deserialization enables SD message exchange over the network. Code Location: |
SD Endpoint Handling¶
The software shall associate offered services with their transport endpoints (IP address, port, protocol) from the Endpoint Options. Rationale: Per-instance offers allow fine-grained service instance management. Code Location: |
The software shall associate subscribed eventgroups with their multicast endpoints from the Multicast Options. Rationale: Multicast endpoint association enables multicast event delivery per eventgroup. Code Location: |
The software shall send initial events of fields via unicast to newly subscribed clients. Rationale: Unicast initial events ensure new subscribers receive current field values immediately. Code Location: |
SD Error Handling¶
The software shall silently discard malformed SD messages that cannot be parsed. Rationale: Configurable timing adapts SD behavior to network characteristics. Code Location: |
The software shall skip invalid entries within a valid SD message and continue processing remaining entries. Rationale: Skipping invalid entries prevents one malformed entry from disrupting an entire SD message. Code Location: |
The software shall remove services and subscriptions when their TTL expires without renewal. Rationale: TTL-based expiry ensures stale services and subscriptions are cleaned up automatically. Code Location: |
SD Multicast Communication¶
The software shall use multicast for SD OfferService and FindService messages by default. Rationale: Standardized entry format enables interoperability between SOME/IP implementations. Code Location: |
The software shall send unicast SD responses when the Unicast Flag is set in the requesting message. Rationale: Unicast responses reduce multicast traffic when the requester supports unicast. Code Location: |
SD Session Handling¶
The software shall increment the Session ID for each SD message sent and use it for reboot detection. Rationale: End-to-end discovery workflow validates the complete SD protocol implementation. Code Location: |
Upon detecting a remote reboot, the software shall clear all cached service and subscription state for the rebooted endpoint. Rationale: Reboot detection prevents communication with stale cached endpoints. Code Location: |
SD Minor Version Handling¶
The software shall support Minor Version matching in FindService entries. Minor Version 0xFFFFFFFF shall match any minor version. Rationale: Session handling enables SD message deduplication and ordering. Code Location: |
SD General Message Format¶
The software shall parse and construct SD message header with Flags (1 byte) and Reserved (3 bytes) fields according to SOME/IP-SD format. Rationale: Flags and reserved bytes are required by the AUTOSAR SOME/IP-SD specification for message-level metadata. Code Location: |
The software shall parse and construct the SD Entries Array with length field and entry layout according to SOME/IP-SD format. Rationale: The entries array carries service offers, finds, and subscriptions; format compliance ensures interoperability. Code Location: |
The software shall parse and construct the SD Options Array with length field and option layout (IPv4, IPv6, etc.) according to SOME/IP-SD format. Rationale: Options provide endpoint and configuration data; format compliance ensures correct address resolution. Code Location: |
The software shall transport SD messages over UDP using the configured SD port (default 30490) with multicast for general announcements. Rationale: Header fields provide message-level metadata (flags, reserved bytes). Code Location: |
The software shall provide an ECU-internal interface for applications to register services, request services, subscribe to eventgroups, and receive service availability notifications. Rationale: The entries array carries service and subscription announcements. Code Location: |
SD Header Details¶
The software shall parse and validate the complete SD header including Message ID (0xFFFF8100), Length, Request ID, Protocol Version, Interface Version, Message Type, and Return Code. Rationale: FindService entries trigger service discovery responses from servers. Code Location: |
The software shall maintain separate Session IDs for multicast and unicast SD messages. Session IDs shall be incremented for each message sent. Rationale: OfferService entries announce available service instances. Code Location: |
The software shall manage the Reboot Flag in SD messages. The flag shall be set after reboot until the Session ID wraps around. TCP connections shall be reset on reboot detection. Rationale: SubscribeEventgroup entries register client interest in events. Code Location: |
SD Entry Format Details¶
The software shall parse common entry fields: Type (1 byte), Index First/Second Options Run (1 byte each), Number of Options (1 byte), Service ID (2 bytes), Instance ID (2 bytes), Major Version/TTL (4 bytes combined), and type-specific fields (4 bytes). Rationale: Configurable multicast enables deployment-specific network topology. Code Location: |
The software shall parse service entries (Type 0 FindService, Type 1 OfferService) with Minor Version in the type-specific field. Service entries are 16 bytes each. Rationale: Multicast for discovery, unicast for responses optimizes bandwidth. Code Location: |
The software shall parse eventgroup entries (Type 6 Subscribe, Type 7 SubscribeAck) with Reserved, Initial Data Flag, Counter, and Eventgroup ID in the type-specific field. Rationale: TTL-based subscriptions enable automatic cleanup without explicit unsubscribe. Code Location: |
The software shall support multiple entries per SD message, combining entries to reduce the number of SD messages sent. Rationale: TTL-based service availability prevents stale service entries. Code Location: |
SD Option Format Details¶
The software shall parse Configuration Options (Type 0x01) containing key-value configuration strings for service instances. Rationale: Endpoint extraction enables the server to know where to send events. Code Location: |
The software shall parse Load Balancing Options (Type 0x02) containing Priority and Weight fields for server selection. Rationale: Server address resolution enables the client to know where to send requests. Code Location: |
The software shall parse IPv4 Endpoint Options (Type 0x04) containing IPv4 address (4 bytes), reserved byte, protocol (1 byte: 0x06=TCP, 0x11=UDP), and port number (2 bytes). Rationale: Correct IPv4 option format ensures interoperability. Code Location: |
The software shall parse IPv6 Endpoint Options (Type 0x06) containing IPv6 address (16 bytes), reserved byte, protocol, and port number. Rationale: IPv6 support enables SD in IPv6 networks. Code Location: |
The software shall parse IPv4 Multicast Options (Type 0x14) containing multicast IPv4 address, protocol (UDP only), and port number. Rationale: IPv4 multicast option format enables multicast event delivery. Code Location: |
The software shall parse IPv6 Multicast Options (Type 0x16) containing multicast IPv6 address, protocol (UDP only), and port number. Rationale: IPv6 multicast support enables SD in IPv6 networks. Code Location: |
The software shall parse IPv4 SD Endpoint Options (Type 0x24) containing the SD communication endpoint. This option is not referenced by entries. Rationale: SD endpoint option carries the SD communication endpoint independently of entries. Code Location: |
SD Option Referencing Details¶
The software shall reference options from entries using the First and Second Option Index and their respective run lengths. Options are referenced as contiguous runs. Rationale: Service registration makes services discoverable via SD. Code Location: |
The software shall process option runs by iterating from the starting index for the given count. Empty runs (count=0) shall be valid. Unknown option types shall be skipped. Rationale: Service discovery enables clients to find available services dynamically. Code Location: |
The software shall validate options for correct length, type, and content. Invalid options shall cause the referencing entry to be rejected. Rationale: Option validation prevents processing of malformed endpoint data. Code Location: |
The software shall process Endpoint Options to determine the transport endpoint (IP, port, protocol) for a service instance. Rationale: Endpoint processing resolves abstract SD entries to concrete transport addresses. Code Location: |
SD FindService Message Details¶
The software shall construct FindService messages with the appropriate Service ID, Instance ID (0xFFFF for all), Major Version (0xFF for any), and Minor Version (0xFFFFFFFF for any). Rationale: Clean shutdown prevents clients from sending to unavailable services. Code Location: |
The software shall respond to FindService with OfferService entries for matching services. Responses shall use configurable delay (REQUEST_RESPONSE_DELAY). Rationale: Reboot recovery ensures subscriptions are re-established after endpoint restart. Code Location: |
SD OfferService Message Details¶
The software shall construct OfferService messages with Service ID, Instance ID, Major/Minor Version, TTL, and Endpoint Options. Rationale: Non-SOME/IP support enables interoperability with other automotive protocols. Code Location: |
The software shall construct StopOfferService messages with TTL=0 when a service instance is stopped or going down. Rationale: StopOfferService with TTL=0 signals immediate service unavailability. Code Location: |
SD SubscribeEventgroup Message Details¶
The software shall construct SubscribeEventgroup messages with Service ID, Instance ID, Eventgroup ID, TTL, and client Endpoint Options. Subscriptions shall be triggered by OfferService reception. Rationale: Open access simplifies deployment without per-client authorization at SD level. Code Location: |
The software shall manage subscription lifecycle: subscribe on service availability, renew before TTL expiry, unsubscribe on shutdown, and re-subscribe after timeout. Rationale: Subscription lifecycle management ensures correct subscribe/renew/unsubscribe behavior. Code Location: |
The software shall construct SubscribeEventgroupAck messages to confirm accepted subscriptions. Ack shall include Multicast Options if the eventgroup uses multicast. Rationale: Multicast options in ACKs direct the client to the correct multicast group. Code Location: |
The software shall construct SubscribeEventgroupNack messages with TTL=0 to reject subscriptions. Clients shall handle Nack by checking TCP connections. Rationale: NACK with TTL=0 clearly signals subscription rejection. Code Location: |
The software shall construct StopSubscribeEventgroup messages with TTL=0 when unsubscribing from an eventgroup. Rationale: StopSubscribe with TTL=0 signals immediate unsubscription. Code Location: |
SD Communication Behavior Details¶
The software shall support configurable SD timing parameters: INITIAL_DELAY_MIN/MAX, REPETITIONS_BASE_DELAY, REPETITIONS_MAX, and CYCLIC_OFFER_DELAY. Rationale: Configurable timing adapts SD phases to network characteristics. Code Location: |
The software shall implement phase transitions: from Initial Wait to Repetition (after first send), from Repetition to Main (after REPETITIONS_MAX), and from any phase to Down (on stop/error). Rationale: Phase transitions enforce the SD protocol state machine. Code Location: |
The software shall join and leave multicast groups for SD communication based on service registration and subscription state. Rationale: Dynamic multicast group management conserves network resources. Code Location: |
The software shall apply configurable response delays (REQUEST_RESPONSE_DELAY) when responding to FindService messages to avoid network storms. Rationale: Response delays prevent network storms from simultaneous SD responses. Code Location: |
SD Endpoint Handling Details¶
The software shall register server endpoints (IP, port, protocol) for offered services and include them in OfferService options. Rationale: Server endpoint registration enables clients to discover communication endpoints. Code Location: |
The software shall resolve client endpoints from SubscribeEventgroup options to determine where to send events and notifications. Rationale: Client endpoint resolution enables the server to deliver events to subscribers. Code Location: |
The software shall handle multicast endpoints for eventgroups, including joining multicast groups, sending initial events via unicast, and switching between unicast/multicast based on subscriber count. Rationale: Multicast endpoint handling optimizes event delivery for groups with many subscribers. Code Location: |
The software shall validate endpoint options for correct format, valid IP addresses, and supported protocols. Rationale: Endpoint validation prevents communication failures from malformed addresses. Code Location: |
SD Service Registration and Discovery¶
The software shall process OfferService entries by updating the service registry with endpoint information and TTL. Rationale: Initial events ensure newly subscribed clients have up-to-date state. Code Location: |
The software shall track service state (available, unavailable, timing out) and notify applications of state changes. Rationale: Service state tracking enables applications to react to availability changes. Code Location: |
The software shall track subscription state (active, pending, rejected, expired) for each eventgroup. Rationale: Subscription state tracking enables applications to know their subscription status. Code Location: |
The software shall maintain a service registry with service entries, supporting add, remove, update TTL, and lookup operations. Rationale: The service registry provides a central lookup for available services. Code Location: |
SD Shutdown and Recovery¶
The software shall implement graceful shutdown by sending StopOfferService for all offered services and StopSubscribe for all active subscriptions. Rationale: Mandatory features define the minimum required SD implementation. Code Location: |
The software shall recover from remote reboot by clearing cached services and re-subscribing to previously subscribed eventgroups. Rationale: Reserved identifier handling at SD level ensures system integrity. Code Location: |
The software shall handle service stop events by cleaning up subscriptions and notifying affected clients. Rationale: Proper handling of reserved IDs prevents undefined behavior in SD processing. Code Location: |
SD Non-SOME/IP Protocol Support¶
The software shall support announcing non-SOME/IP services using Service ID 0xFFFE with the appropriate configuration. Rationale: Flag processing controls SD response addressing behavior. Code Location: |
SD Initial Event Handling¶
The software shall send initial events of fields via unicast to newly subscribed clients after sending SubscribeEventgroupAck. Rationale: Version-aware subscription ensures clients receive compatible events. Code Location: |
The software shall request initial events after reboot or when no active subscription exists for the eventgroup. Rationale: Version-aware workflows ensure client-server compatibility. Code Location: |
SD Advanced Features¶
The software shall implement SD error handling by checking message headers, entry fields, and option validity. Invalid messages shall be silently discarded. Rationale: Configurable parameters enable deployment-specific SD behavior tuning. Code Location: |
The software shall resolve option conflicts by using the first valid option and ignoring subsequent conflicting options. Rationale: Phase timing configuration controls SD protocol behavior. Code Location: |
The software shall implement SD security measures including message validation, source address verification, and rate limiting. Rationale: SD timing configuration enables adaptation to different network environments. Code Location: |
The software shall process IPv4 SD Endpoint Options when present, using them instead of the source IP/port for SD communication. Rationale: TTL configuration controls service and subscription expiry timing. Code Location: |
The software shall implement the mandatory SD feature set including FindService, OfferService, SubscribeEventgroup, and their acknowledgments. Rationale: Multicast configuration specifies the network parameters for SD communication. Code Location: |
The software shall process the Unicast Flag in SD messages to determine the response transport (unicast vs multicast). Rationale: SD port configuration ensures correct network resource allocation. Code Location: |
The software shall implement detailed service state machine behavior including proper handling of Find/Offer cycles and timer management. Rationale: Port assignment rules prevent conflicts with reserved system ports. Code Location: |
The software shall implement the soft-state model where entries (services, subscriptions) expire unless refreshed. Subscription renewal shall occur before TTL expiry. Rationale: Configurable ports enable deployment flexibility. Code Location: |
The software shall implement the publish/subscribe event flow including link loss handling at both client and server sides. Rationale: Consistent port usage ensures clients can reach services at expected endpoints. Code Location: |
The software shall handle duplicate OfferService messages by updating the existing entry rather than creating duplicates. Rationale: Port validation prevents misconfiguration that could disrupt communication. Code Location: |
The software shall aggregate multiple SD entries into single messages when possible to reduce network traffic. Rationale: Reboot detection triggers re-subscription to restore event delivery. Code Location: |
The software shall implement the SD startup behavior with three phases (Initial Wait, Repetition, Main) as per the specification. Rationale: Delayed startup prevents SD storms when multiple ECUs boot simultaneously. Code Location: |
The software shall implement advanced reboot detection using Session ID regression and Reboot Flag analysis. Rationale: Advanced reboot detection covers complex restart scenarios. Code Location: |
The software shall handle service timeouts by removing expired services and notifying applications of unavailability. Rationale: Service timeout handling cleans up services that stop offering without explicit StopOffer. Code Location: |
The software shall handle multicast in subscriptions including Multicast Option in SubscribeEventgroupAck and SubscribeEventgroupNack for conflicting multicast endpoints. Rationale: Multicast subscription handling enables efficient event delivery to groups. Code Location: |
The software shall maintain server-side subscription state including client lists per eventgroup and proper cleanup on StopSubscribe. Rationale: Per-client subscription state enables correct per-subscriber event delivery decisions. Code Location: |
The software shall support service registration and deregistration with proper cleanup of associated subscriptions and endpoints. Rationale: SD timing parameters control the behavior of all SD protocol phases. Code Location: |
The software shall reject SD messages where the entries array length exceeds the remaining message data. Rationale: Length mismatch prevents correct entry parsing. Error Handling: Discard message, log declared vs available length. Code Location: |
The software shall skip entries that reference option indices beyond the options array. Rationale: Out-of-range option indices indicate malformed SD messages. Error Handling: Skip entry, continue processing remaining entries, log error. Code Location: |
The software shall skip SD entries with unknown entry type codes. Rationale: Unknown entry types may appear in messages from newer SD implementations. Error Handling: Skip entry, log unknown type code, continue processing. Code Location: |
The software shall handle maximum TTL values without timer overflow. Rationale: Maximum TTL values must be handled safely without arithmetic overflow. Error Handling: Clamp TTL to implementation maximum if necessary, log clamping. Code Location: |
The software shall NACK subscriptions for services that are not currently offered. Rationale: Subscriptions to unavailable services cannot be fulfilled. Error Handling: Send NACK (TTL=0), log rejected subscription details. Code Location: |
The software shall ignore OfferService messages with invalid endpoint addresses. Rationale: Invalid endpoints cannot be used for communication. Error Handling: Discard offer, log invalid endpoint address. Code Location: |
The software shall handle duplicate offers by refreshing the TTL without creating duplicate registry entries. Rationale: Duplicate offers are normal during the repetition phase. Error Handling: Refresh TTL of existing entry, no new entry created. Code Location: |
The software shall handle multicast send failures gracefully. Rationale: Multicast may fail due to network configuration issues. Error Handling: Log error, retry or fall back to unicast based on configuration. Code Location: |
The software shall handle SD entries that reference zero options gracefully. Rationale: Entries without options are valid but may limit functionality. Error Handling: Process entry, log warning if endpoint info is missing. Code Location: |
The software shall handle conflicting subscriptions from the same client to the same eventgroup. Rationale: Duplicate subscriptions may indicate configuration errors. Error Handling: Accept latest subscription, log conflict. Code Location: |
The software shall report a timeout when no OfferService response is received within the configured discovery period. Rationale: Discovery timeout enables the application to handle unavailable services. Error Handling: Invoke discovery timeout callback. Code Location: |
The software shall ignore reserved bits in the SD flags byte for forward compatibility. Rationale: Reserved bits may be defined in future SD versions. Error Handling: Ignore reserved bits, process known flags normally. Code Location: |
The software shall treat OfferService entries with TTL=0 as StopOffer messages. Rationale: TTL=0 signals immediate unavailability regardless of entry type. Error Handling: Remove service from registry, notify application. Code Location: |
The software shall correctly extract the 24-bit TTL field from the 3-byte packed format. Rationale: TTL is a 24-bit field packed across bytes, requiring careful extraction. Error Handling: Validate TTL extraction against known test vectors. Code Location: |
The software shall coalesce duplicate subscriptions from the same client into a single subscription with refreshed TTL. Rationale: Duplicate subscriptions waste server resources. Error Handling: Refresh TTL of existing subscription. Code Location: |
The software shall reject new service offers during the shutdown phase. Rationale: Offering services during shutdown creates inconsistent state. Error Handling: Return NOT_READY error. Code Location: |
The software shall handle subscription ACK timeouts by transitioning the subscription state. Rationale: ACK timeout indicates the server may be unreachable. Error Handling: Transition to TIMEOUT state, retry or notify application. Code Location: |
The software shall reject multicast options containing non-multicast addresses. Rationale: Non-multicast addresses in multicast options indicate malformed messages. Error Handling: Reject option, log invalid address. Code Location: |
Traceability¶
Implementation Files¶
include/sd/sd_types.h- SD type definitionsinclude/sd/sd_message.h- SD message interfaceinclude/sd/sd_client.h- SD client interfaceinclude/sd/sd_server.h- SD server interfacesrc/sd/sd_message.cpp- SD message implementationsrc/sd/sd_client.cpp- SD client implementationsrc/sd/sd_server.cpp- SD server implementation
Test Files¶
tests/test_sd.cpp- SD unit tests