-
Notifications
You must be signed in to change notification settings - Fork 25
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
The following change is a reboot of the SOME/IP specifications in an attempt to drastically simplify to show how we map up-l1 messages to SOME/IP messages and uSubscription messages to SOME/IP-SD messages. the older specifications had a lot of uProtocol version 1.3.6 concepts (cloudevents) that were rather complicating the situation. #93
- Loading branch information
czfdcn
committed
Apr 18, 2024
1 parent
8fcb37d
commit e9e7c9a
Showing
20 changed files
with
221 additions
and
2,849 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,221 @@ | ||
| = SOME/IP | ||
| :toc: | ||
| :sectnums: | ||
| :plantuml-server-url: http://www.plantuml.com/plantuml | ||
| :github-plantuml-url: https://github.com/plantuml/plantuml-server/raw/master/dist | ||
|
|
||
| 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 https://www.rfc-editor.org/info/bcp14[IETF BCP14 (RFC2119 & RFC8174)] | ||
|
|
||
| ---- | ||
| Licensed to the Apache Software Foundation (ASF) under one | ||
| or more contributor license agreements. See the NOTICE file | ||
| distributed with this work for additional information | ||
| regarding copyright ownership. The ASF licenses this file | ||
| to you under the Apache License, Version 2.0 (the | ||
| "License"); you may not use this file except in compliance | ||
| with the License. You may obtain a copy of the License at | ||
| http://www.apache.org/licenses/LICENSE-2.0 | ||
| Unless required by applicable law or agreed to in writing, | ||
| software distributed under the License is distributed on an | ||
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| KIND, either express or implied. See the License for the | ||
| specific language governing permissions and limitations | ||
| under the License. | ||
| ---- | ||
|
|
||
| == 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 (User Datagram Protocol) 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. | ||
|
|
||
| === Open Source Libraries | ||
|
|
||
| As of the time of writing, there are two open source projects that are available for SOME/IP: | ||
|
|
||
| 1. *https://github.com/COVESA/vsomeip[COVESA-vsomeip]:* C++ solution based on the original specifications developed by BMW prior to contribution to AUTOSAR | ||
| 2. *https://projects.eclipse.org/projects/automotive.sommr[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. | ||
|
|
||
|
|
||
| == Transport Layer Translation | ||
|
|
||
| === UAttributes | ||
|
|
||
| The following table highlights the mapping of uAttributes to SOME/IP fields that apply to all event types. For more information about uAttributes please refer to link:../basics/uri.adoc[URI]. | ||
|
|
||
|
|
||
| ==== Uris | ||
|
|
||
| link:../basics/uattributes.adoc[UAttributes Specification] explains that `source` attributes defines the address of whom sent the message, while `sink` defines the destination for the message in link:../basics/uri.adoc[`UUri`] format. `UUri` is translated to SOME/IP attributes per <<sink-source-uri-mapping>> below. | ||
|
|
||
| .Sink & Source URI Mapping | ||
| [sink-source-uri-mapping] | ||
| |=== | ||
| |*UUri Portion* |*SOME/IP Field* |*Description* | ||
| |*`UAuthority::ip`* |IP address & port |IP address & port (destination | ||
| endpoint) of the mDevice | ||
|
|
||
| |*`UEntity::id`* |Service ID |Software entity ID that is placed in the upper 16 | ||
| bits of the SOME/IP Message ID header field | ||
|
|
||
| |*`UResource::id`* |Method/Event ID |Identifier of the method/resource placed in the | ||
| lower 15 bits of the SOME/IP Message ID header field | ||
|
|
||
| |=== | ||
|
|
||
|
|
||
| ==== UUIDs | ||
|
|
||
| link:../basics/uuid.adoc[uProtocol UUID specifications] create a unique identifier for each message along with timestamp information. the ID is used for correlate between request and response as well. SOME/IP instead defines the ID as 16bit client ID + 16 bit session ID (that is incremented). When messages are converted SOME/IP to/from uProtocol, care must be taken to ensure that the SOME/IP ID and uProtocol UUID are properly mapped, especially when corelating a request to a response. | ||
|
|
||
| * Generated SOME/IP events *SHOULD* set the 16 bit client ID to 0 per SOME/IP specifications 4.1.2.4 | ||
| * *MUST* auto-populate the request ID cached from the request event, into the response event and then flush the entry in the cache | ||
|
|
||
| Further details of the usage of IDs for the various message types can be found in the next section. | ||
|
|
||
| ==== Message Type | ||
|
|
||
| .UMessageType Mapping | ||
| [umessagetype-mapping] | ||
| |=== | ||
| | UMessageType | SOME/IP Type | Details | ||
|
|
||
| |`UMESSAGE_TYPE_PUBLISH` or `UMESSAGE_TYPE_NOTIFICATION` |`NOTIFICATION` |Both publication and notifications events are the same for SOME/IP | ||
|
|
||
| | `UMESSAGE_TYPE_REQUEST` |`REQUEST` |Requests type message | ||
|
|
||
| | `UMESSAGE_TYPE_RESPONSE` |`RESPONSE` or `ERROR` |Responses or error has occurred while attempting to deliver the message or a service | ||
| has thrown an exception | ||
|
|
||
| |=== | ||
|
|
||
|
|
||
| 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 | ||
| ``` | ||
|
|
||
| * Auto-generated SOME/IP REQUEST message, *MAY* set the 16 bit client ID to the 0 per SOME/IP specifications | ||
|
|
||
| When receiving a SOME/IP initiated requests: | ||
|
|
||
| * *MUST* cache the SOME/IP request ID as well as the generated `UAttributes` for the request messages so that the response can be translated back to a SOME/IP response message | ||
|
|
||
|
|
||
| ==== Communication Status | ||
|
|
||
| <<commstatus-mapping>> below provides the mapping of uAttributes `commstatus` `UCode` codes to SOME/IP error codes. | ||
|
|
||
| .Error Code Mapping | ||
| [commstatus-mapping, width=70%] | ||
| |=== | ||
| | UCode | SOME/IP Error Codes | ||
|
|
||
| |`OK` |`E_OK` | ||
| |`INVALID_ARGUMENT` |`E_WRONG_MESSAGE_TYPE` or `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` | ||
| |=== | ||
|
|
||
|
|
||
| === UPayload | ||
|
|
||
| `UPayload` hosts the application layer data that is being sent between devices. `UPayload` structure, defined in link:../basics/upayload.adoc[UPayload] contains either a copy or reference to the actual payload that is to be sent. `UPayload` also contains `UPayloadFormat` used to give a hint of the payload format (protobuf serialized, SOME/IP format, TEXT, RAW, etc...). The SOME/IP specifications however does not have an equivalent field for `UPayloadFormat` as 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 `UPayloadFormat` field *SHOULD* be ignored (left at the default of `UMESSAGE_TYPE_UNSPECIFIED`). | ||
|
|
||
|
|
||
| === uTransport | ||
|
|
||
| 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. | ||
|
|
||
|
|
||
| == 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. | ||
|
|
||
| === 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 (5.1.3.1) are mapped to uSubscription messages for the subscribe | ||
| and unsubscribe flows. | ||
|
|
||
| ==== 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 usined in uProtocol `UMessage` for performing subscription operations. | ||
|
|
||
| .Common Field Mappings | ||
| [#common-field-mappings, width=70%] | ||
| |=== | ||
| |Eventgroup Entry Field |UUri | ||
|
|
||
| |Service ID |`UEntity.id` | ||
|
|
||
| |Major Version | `UEntity.major_version` | ||
|
|
||
| |Eventgroup ID | `UResource.id` | ||
|
|
||
| |=== | ||
|
|
||
| NOTE: `UUri.authority.ip` is translated to/from IPv4 (and/or IPv6) Endpoint Option of the SOME/IP-SD message | ||
|
|
||
| ==== EventGroup Entry Type Mapping | ||
|
|
||
| .EventGroup Entry Type Mapping | ||
| [#eventgroup-entry-mapping, cols="1,1,2"] | ||
| |=== | ||
| |Eventgroup Entry Type |uSubscription Message | Additional Details | ||
|
|
||
| |`SubscribeEventGroup` | ||
| |`SubscriptionRequest` | ||
| a|The message is used to subscribe to a topic. | ||
|
|
||
| * Instance ID *SHALL* assume to be 0 | ||
| * *SHALL* assume version 0 to match uProtocol backwards compatibility requirements | ||
| * TTL (`SubscribeAttributes.ttl`) *SHALL* set to 0xFFFFFF to indicate that the subscription should remain for the duration of the ignition cycle | ||
|
|
||
| NOTE: If temporal subscriptions shall be supported by the various uProtocol implementation, `ttl` *SHOULD* be set to the desired duration of the subscription. | ||
|
|
||
| |`SubscribeEventGroupAck` | ||
| |`SubscriptionResponse` | ||
| a|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` | ||
| a|The message is used to acknowledge a failed subscription request. | ||
|
|
||
| * SubscriptionStatus.code *SHALL* be set to the corresponding error code per the <<commstatus-mapping>> table | ||
| * SubscriptionStatus.state *SHALL* be set to `UNSUBSCRIBED` | ||
|
|
||
| |`StopSubscribeEventGroup` | ||
| |`UnsubscribeRequest` | ||
| a|The message is used to unsubscribe from a topic. | ||
|
|
||
| * Instance ID *SHALL* assume to be 0 | ||
| * *SHALL* assume version 0 to match uProtocol backwards compatibility requirements | ||
| * TTL *SHALL* set to 0 to indicate that the subscription has terminated | ||
|
|
||
| |=== | ||
|
|
||
|
|
||
|
|
||
| === uDiscovery Translation | ||
|
|
||
| _TODO: Pending uDiscovery v3 redesign_ |
Oops, something went wrong.