Skip to content

Latest commit

 

History

History
315 lines (206 loc) · 16 KB

someip.adoc

File metadata and controls

315 lines (206 loc) · 16 KB
Raw

SOME/IP

Table of Contents

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)

SPDX-FileCopyrightText: 2023 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-FileType: DOCUMENTATION
SPDX-License-Identifier: Apache-2.0

1. Overview

Scalable service-Oriented MiddlewarE over IP (SOME/IP) is a communication protocol used in the automotive industry for exchanging data between electronic control units (ECUs) in a vehicle.

SOME/IP provides a framework for efficient and reliable communication between ECUs over IP networks. It is designed to support real-time and high-bandwidth communication requirements in automotive systems. The protocol allows ECUs to discover and communicate with each other, exchange messages, and provide services in a distributed system.

SOME/IP is based on the Internet Protocol (IP) and uses UDP or TCP as the transport layer. It supports various communication patterns, including unicast, multicast, and broadcast. The protocol defines a set of message formats and procedures for encoding and decoding data, handling service discovery, and managing communication sessions. By using SOME/IP, automotive ECUs can communicate with each other to exchange information related to vehicle functions, such as sensor data, control commands, diagnostics, and software updates. It enables the integration and interoperability of different ECUs from various automotive suppliers within a vehicle’s network architecture. Overall, SOME/IP plays a crucial role in facilitating efficient and standardized communication between ECUs in modern automotive systems.

The following specification will elaborate on how uProtocol shall be mapped to SOME/IP protocol so that mechatronics applications and services can be connected to non-mechatronics and cloud based applications and services.

1.1. Open Source Libraries

As of the time of writing, there are two open source projects that are available for SOME/IP:

  1. COVESA-vsomeip: C++ solution based on the original specifications developed by BMW prior to contribution to AUTOSAR

  2. Eclipse-SommR: Rust implementation based on the latest AUTOSAR SOME/IP specifications.

Note
 Given the latest version of SOME/IP specifications from AUTOSAR is not open source, we cannot share or implement uProtocol using Eclipse-SommR.

1.2. AUTOSAR References

All references below to:

A search engine usually finds the correct document based on the reference number.

2. Transport Layer Translation

Transport layer (uP-L1) specifies how uMessages are sent and received over a "wire" between uEs or between devices. In this section we will cover the SOME/IP communication protocol binding and event mapping.

Mapping of uTransport APIs to SOME/IP specific library APIs shall not be covered in this document given there are multiple open source libraries available for SOME/IP.

Although some limitations of vsomeip library are mentioned bellow as NOTES.

2.1. UUris

UUri is translated to SOME/IP attributes per UUri Mapping table below.

Table 1. UUri Mapping
UUri Portion SOME/IP Field Description

authority_name

IP:port

  • IP address & port (destination endpoint) of the mDevice.

Note
 vsomeip hides IP endpoint information and uses ServiceID/InstanceID instead.
SHOULD be left blank or mapped via static transport configuration.

ue_id

InstanceID|ServiceID

  • ServiceID MUST be encoded in the lower 16 bits of the 32 bit ue_id.

  • InstanceID MAY be encoded in the upper 16 bits of ue_id.

  • If the upper 16 bits are 0x0000 (a reserved instance value), InstanceID is assumed to be 1.

  • Explicitly setting InstanceID to 0x0001 SHOULD be avoided as it increases uProtocol message size.

ue_version_major

Interface Version

  • Interface Version field of SOME/IP Header. [PRS_SOMEIP_00053].

  • Maps to Major Version for the ServiceID.

  • If set, it SHOULD be passed to underlying SOME/IP library to override it’s default Service Major Version

resource_id

MethodID/EventID

  • Identifier of the method/event placed in the lower 16 bits of the SOME/IP Header MessageID. [PRS_SOMEIP_00034]
NOTES

  • ServiceID and MethodID are defined in SOME/IP Header format, specified by AUTOSAR [PRS_SOMEIP_00030].

  • EventID is an alias for MethodID, but used for events. [PRS_SOMEIP_00245]

  • InstanceID is defined in SOME/IP-SD Service Entry Type, specified by AUTOSAR [PRS_SOMEIPSD_00268].

  • InstanceID is not present in SOME/IP Header, but is needed for Service Discovery and events and MUST be provided for SOME/IP libraries (e.g. vsomeip). [PRS_SOMEIP_00162]

  • Additional mappings MAY be required by the underlying SOME/IP library, e.g. Service Major/Minor version. Such values MAY be pre-configured

2.2. UAttributes

The following sections highlight the mapping of UAttributes to SOME/IP fields.

2.2.1. Common UMessage Attributes

Table 2. Common UMessage Attributes
UMessage SOME/IP Mapping

id

UUid to SOME/IP MessageID as explained in UUIds.

priority

Not available in SOME/IP. Default UPriority values are used per UMessage type as described in UAttributes.

  • SOME/IP NOTIFICATION SHOULD use the CS1 priority.

  • SOME/IP REQUEST SHOULD use CS4 or higher priority.

  • SOME/IP RESPONSE MUST use the priority from its corresponding REQUEST message.

ttl

Should be checked for incoming UMESSAGE_TYPE_REQUEST messages.

  • SOME/IP REQUEST SHOULD not be sent if incoming UMessage ttl has already expired.

  • Remaining time from ttl SHOULD be used to limit the time a REQUEST is kept in the cache for correlation with a RESPONSE.

  • If needed ttl=0 MAY be used to indicate REQUEST_NO_RETURN (currently not allowed)

Check ttl NOTE below.

payload_format

SOME/IP specification however does not have an equivalent field for UPayloadFormat.

It is assumed that the payload is serialized in the format that the other end knows how to deserialize (i.e. it is fixed per topic). As such, when converting between uProtocol and SOME/IP, the payload_format field SHOULD be ignored (left at the default or UPAYLOAD_FORMAT_UNSPECIFIED).
Note
 Unix timestamps in UUID are likely to be different between hosts, so small ttl values may cause undefined behavior: e.g. not sending REQUEST, or ignoring the RESPONSE.

2.2.2. UUIDs

uProtocol UUID specifications create a unique identifier for each message along with timestamp information.

The UUid is used for correlate between request and response as well. SOME/IP instead defines the RequestID as 16 bit ClientID + 16 bit SessionID (that is incremented). [PRS_SOMEIP_00046]

  • When messages are converted SOME/IP to/from uProtocol, care must be taken to ensure that the SOME/IP Response RequestID and uProtocol UUID are properly mapped, especially when corelating a request to a response.

  • Generated SOME/IP Events MUST set the 16 bit ClientID to 0 per [PRS_SOMEIP_00925]

  • Generated SOME/IP Responses MUST auto-populate the RequestID cached from the request message, into the response message and then flush the entry in the cache.

Further details of the usage of IDs for the various message types is described below.

2.2.3. Message Type

UMessageType Mapping table below maps of uProtocol messages to [PRS_SOMEIP_00055] SOME/IP message types.

Table 3. UMessageType Mapping
UMessageType SOME/IP Type Details

UMESSAGE_TYPE_PUBLISH

NOTIFICATION

Publish SOME/IP Events.

UMESSAGE_TYPE_NOTIFICATION

n/a

Same as SOME/IP NOTIFICATION.

UMESSAGE_TYPE_REQUEST

REQUEST

RPC Request

UMESSAGE_TYPE_RESPONSE

RESPONSE or ERROR

RPC Response or Error has occurred while attempting to deliver the message.

  • When receiving uProtocol initiated requests:

    • MUST cache the request UAttributes for a maximum of ttl so that it can be used to build a response UAttributes when receiving a response from SOME/IP.

      response.priority = request.priority
response.reqid = request.id

    • MUST clean up the cache after the ttl has expired and send an Error UMESSAGE_TYPE_RESPONSE

    • MUST ignore incoming SOME/IP Response(s) for an expired Request.

  • When sending auto-generated SOME/IP REQUEST messages:

    • MUST cache the message’s RequestID to correlate with the RESPONSE message.

    • Underlying SOME/IP library MAY handle RequestID updating automatically.

  • When receiving a SOME/IP initiated requests:

    • MUST cache the SOME/IP RequestID as well as the generated UAttributes for the request messages so that the response can be translated back to a SOME/IP RESPONSE message

2.2.4. Sink & Source Mapping

UAttributes Specification explains that source attributes defines the address of whom sent the message, while sink defines the destination for the message as described in UUri Mapping.

Table 4. SOME/IP to UAttributes Sink & Source Mapping

UMessageType

SOME/IP Type

MessageID

RequestID

Interface Version

Return Code (commstatus)

ServiceID (1)

MethodID

ClientID (1),(4)

SessionID

NOTIFICATION (5)

REQUEST_NO_RETURN (0x01)

sink.ue_id

sink.resource_id

source.ue_id

(2),(3)

sink.ue_major_version

PUBLISH

NOTIFICATION (0x02)

source.ue_id

source.resource_id

sink.ue_id=0

(2)

source.ue_major_version

REQUEST

REQUEST (0x00)

sink.ue_id

sink.resource_id

source.ue_id

(2),(3)

sink.ue_major_version

OK

RESPONSE

RESPONSE (0x80)

sink.ue_id

sink.resource_id

source.ue_id

(2),(3)

sink.ue_major_version

OK

ERROR (0x81)

sink.ue_id

sink.resource_id

source.ue_id

(2),(3)

sink.ue_major_version

commstatus
NOTES

  • (1) Maps to lower 16 bits of ue_id

  • (2) Using session handling so value is increased by 1 until max 0xFFFF and mapped to UAttributes.id

  • (3) source.ue_version_major missing!

  • (4) ClientID for vsomeip transport SHOULD be set via configuration to source.ue_id. It MUST be unique for the network.

  • (5) REQUEST_NO_RETURN is a Request in SOME/IP that applies to MethodID, but in uProtocol NOTIFICATION applies to events (resource_id > 0x8000).

2.2.5. Communication Status

UCode to SOME/IP Error Code Mapping below provides the mapping of UAttributes commstatus UCode codes to SOME/IP error codes [PRS_SOMEIP_0019].

Table 5. UCode to SOME/IP Error Code Mapping
UCode SOME/IP Error Codes

OK

E_OK

INVALID_ARGUMENT

E_WRONG_MESSAGE_TYPE / E_UNKNOWN_METHOD

DEADLINE_EXCEEDED

E_TIMEOUT

NOT_FOUND

E_UNKNOWN_SERVICE

UNAVAILABLE

E_NOT_READY

DATA_LOSS

E_MALFORMED_MESSAGE

INTERNAL

E_NOT_REACHABLE

UNKNOWN

E_NOT_OK

FAILED_PRECONDITION

E_WRONG_PROTOCOL_VERSION / E_WRONG_INTERFACE_VERSION

3. Application Layer Translation

Application (or message payload) translation is the process of converting SOME/IP-SD subscription and discovery messages, to/from uDiscovery and uSubscription Messages.

3.1. uSubscription

The following section will elaborate only on the translation of uSubscription messages to/from SOME/IP-SD messages. Subscription state (persistent or not) is handled in the uSubscription services and not at the transport layer or this component.

The following section we will elaborate on how Eventgroup Entry types are mapped to uSubscription messages for the subscribe and unsubscribe flows per [PRS_SOMEIPSD_00385].

3.1.1. Common Fields

Common Field Mappings table below illustrates the common SOME/IP-SD EventGroup Entry fields that are present in for all SOME/IP-SD Eventgroup entry types (SubscribeEventgroup, SubscribeEventGroupAck, SubscribeEventgroupNack, StopSubscribeEventGroup).

These fields are then mapped to uProtocol UUri attributes used in uProtocol UMessage for performing subscription operations.

Table 6. Common Field Mappings
Eventgroup Entry Field UUri

ServiceID

Set in lower 16 bits of ue_id

InstanceID

If instance is not the default (0x1), set it in upper 16 bits of ue_id

Major Version

ue_version_major

EventGroupID / EventID

resource_id

Note
 1:1 mapping between EventGroupID and EventID is assumed.
This may require specific ECU Firmware.
Note
 UUri.authority_name MAY be translated to/from IPv4 (and/or IPv6) Endpoint Option of the SOME/IP-SD message, although in vsomeip this is not available in the API (e.g. each discovered Endpoint maps to ServiceID/InstanceID/Major Version/Minor Version).

EventGroup Entry Type Mapping table below illustrates the mapping of SOME/IP-SD Eventgroup Entry types to uSubscription messages for the subscribe and unsubscribe flows.

Table 7. EventGroup Entry Type Mapping
Eventgroup Entry Type uSubscription Message Additional Details

SubscribeEventGroup

SubscriptionRequest

The message is used to subscribe to a topic.

  • If SubscribeAttributes.expire is not set, TTL MAY be set to 0xFFFFFF to indicate that the subscription should remain for the duration of the ignition cycle

Note
 vsomeip has static TTL configuration (for Service Discovery), that applies for all subscriptions.
It can’t be changed per subscription.

SubscribeEventGroupAck

SubscriptionResponse

The message is used to acknowledge a successful subscription request.

  • SubscriptionStatus.code SHALL be set to OK

  • SubscriptionStatus.state SHALL be set to SUBSCRIBED

SubscribeEventGroupNack

SubscriptionResponse

The message is used to acknowledge a failed subscription request.

StopSubscribeEventGroup

UnsubscribeRequest

The message is used to unsubscribe from a topic.

  • TTL SHALL be set to 0 to indicate that the subscription has terminated. NOTE: handled by underlying SOME/IP library.

3.2. uDiscovery Translation

TODO: Pending uDiscovery v3 redesign