Specification of SOME/IP Transformer AUTOSAR CP R19-11
Total Page:16
File Type:pdf, Size:1020Kb
Specification of SOME/IP Transformer AUTOSAR CP R19-11 Specification of SOME/IP Document Title Transformer Document Owner AUTOSAR Document Responsibility AUTOSAR Document Identification No 660 Document Status published Part of AUTOSAR Standard Classic Platform Part of Standard Release R19-11 Document Change History Date Release Changed by Description • Extended Serialization for Data Structures in SOME/IP with tag/length/value encoding set to valid • Removed *_ACK message types • replaced implementsSOMEIPStringHandling AUTOSAR (in class 2019-11-28 R19-11 Release SOMEIPTransformationSignalProps) Management with implementsLegacyStringSerialization • Minor corrections / clarifications / editorial changes; For details please refer to the ChangeDocumentation • Changed Document Status from Final to published • Checking for length of received dynamic length strings AUTOSAR • Extended Serialization for Data 2018-10-31 4.4.0 Release Structures in SOME/IP with Management tag/length/value encoding • Minor corrections / clarifications / editorial changes; For details please refer to the ChangeDocumentation 1 of 101 Document ID 660: AUTOSAR_SOMEIPTransformer — AUTOSAR CONFIDENTIAL — Specification of SOME/IP Transformer AUTOSAR CP R19-11 • Bugfixes in serialization of strings AUTOSAR and data with variable size 2017-12-08 4.3.1 Release • Signatures improved Management • Minor corrections / clarifications / editorial changes; For details please refer to the ChangeDocumentation • Sizes of length fields can be configured independently from each AUTOSAR other 2016-11-30 4.3.0 Release • Support of union data types Management • Minor corrections / clarifications / editorial changes; For details please refer to the ChangeDocumentation • Size of length fields is configurable • External trigger events are communciated as fire-and-forget AUTOSAR methods 2015-07-31 4.2.2 Release • Autonomous error reactions of Management SOME/IP transformer • Minor corrections / clarifications / editorial changes; For details please refer to the ChangeDocumentation AUTOSAR 2014-10-31 4.2.1 Release Initial Release Management 2 of 101 Document ID 660: AUTOSAR_SOMEIPTransformer — AUTOSAR CONFIDENTIAL — Specification of SOME/IP Transformer AUTOSAR CP R19-11 Disclaimer Disclaimer This work (specification and/or software implementation) and the material contained in it, as released by AUTOSAR, is for the purpose of information only. AUTOSAR and the companies that have contributed to it shall not be liable for any use of the work. The material contained in this work is protected by copyright and other types of intel- lectual property rights. The commercial exploitation of the material contained in this work requires a license to such intellectual property rights. This work may be utilized or reproduced without any modification, in any form or by any means, for informational purposes only. For any other purpose, no part of the work may be utilized or reproduced, in any form or by any means, without permission in writing from the publisher. The work has been developed for automotive applications only. It has neither been developed, nor tested for non-automotive applications. The word AUTOSAR and the AUTOSAR logo are registered trademarks. 3 of 101 Document ID 660: AUTOSAR_SOMEIPTransformer — AUTOSAR CONFIDENTIAL — Specification of SOME/IP Transformer AUTOSAR CP R19-11 Table of Contents 1 Introduction and functional overview6 2 Acronyms and Abbreviations7 3 Related documentation8 3.1 Input documents..............................8 3.2 Related standards and norms.......................9 3.3 Related specification............................9 4 Constraints and assumptions 10 4.1 Limitations.................................. 10 4.2 Applicability to car domains........................ 10 5 Dependencies to other modules 11 5.1 File structure................................ 11 5.1.1 Code file structure........................ 11 5.1.2 Header file structure....................... 11 6 Requirements Tracing 12 7 Functional specification 17 7.1 Definition of Identifiers........................... 21 7.2 Specification of the SOME/IP on-wire format............... 21 7.2.1 Message Length Limitations.................. 22 7.2.2 Endianess............................ 22 7.2.3 Header.............................. 22 7.2.3.1 Message ID [32 bit]................... 23 7.2.3.2 Length [32 bit]...................... 24 7.2.3.3 Request ID [32 bit]................... 24 7.2.3.4 Protocol Version [8 bit]................. 25 7.2.3.5 Interface Version [8 bit]................. 25 7.2.3.6 Message Type [8 bit].................. 25 7.2.3.7 Return Code [8 bit]................... 26 7.2.3.8 Payload [variable size]................. 27 7.2.4 Serialization of Parameters and Data Structures....... 27 7.2.4.1 Basic Datatypes.................... 28 7.2.4.2 Structured Datatypes (structs)............. 29 7.2.4.3 Structured Datatypes and Arguments with Identifier and optional Members................. 31 7.2.4.4 Strings.......................... 36 7.2.4.5 Arrays (fixed length).................. 41 7.2.4.6 Optional Parameters / Optional Elements...... 44 7.2.4.7 Dynamic Length Arrays / Variable Size Arrays.... 44 7.2.4.8 Bitfield.......................... 47 7.2.4.9 Union / Variant..................... 47 4 of 101 Document ID 660: AUTOSAR_SOMEIPTransformer — AUTOSAR CONFIDENTIAL — Specification of SOME/IP Transformer AUTOSAR CP R19-11 7.3 Protocol specification............................ 50 7.3.1 Client/Server Communication.................. 50 7.3.2 Sender/Receiver Communication................ 52 7.3.3 Unqueued External Trigger Events............... 54 7.3.4 Error Handling.......................... 54 7.3.4.1 Return Code...................... 55 7.3.4.2 Communication Errors and Handling of Communica- tion Errors........................ 56 7.4 Reserved and special identifiers for SOME/IP and SOME/IP-SD.... 58 7.5 Development Errors............................ 59 7.6 Production Errors.............................. 60 7.7 Extended Production Errors........................ 60 7.8 Error Notification.............................. 60 8 API specification 61 8.1 Imported types............................... 61 8.2 Type definitions............................... 61 8.3 Function definitions............................. 61 8.3.1 SomeIpXf_<transformerId>................... 61 8.3.2 SomeIpXf_Inv_<transformerId>................ 66 8.3.3 SomeIpXf_Init.......................... 71 8.3.4 SomeIpXf_DeInit......................... 71 8.3.5 SomeIpXf_GetVersionInfo................... 71 8.4 Callback notifications............................ 72 8.5 Scheduled functions............................ 72 8.6 Expected interfaces............................. 72 9 Sequence diagrams 73 10 Configuration specification 74 A Referenced Meta Classes 75 B Features of SOME/IP not supported by AUTOSAR SOME/IP transformer 97 C Examples 97 C.1 Serialization of a Client/Server Operation................. 97 C.1.1 Client............................... 99 C.1.2 Server............................... 100 5 of 101 Document ID 660: AUTOSAR_SOMEIPTransformer — AUTOSAR CONFIDENTIAL — Specification of SOME/IP Transformer AUTOSAR CP R19-11 1 Introduction and functional overview This document specifies the Scalable service-Oriented MiddlewarE over IP (SOME/IP) Transformer. This is a transformer which linearizes data with the SOME/IP on-the-wire format and specifies an automotive/embedded mechanism for Clien- t/Server communication. The only valid abbreviation is SOME/IP. Other abbreviations (e.g. Some/IP) are wrong and shall not be used. The basic motivation to specify "yet another Client/Server and Sender/Receiver mech- anism" instead of using an existing infrastructure/technology is the goal to have a tech- nology that: • Fulfills the hard requirements regarding resource consumption in an embedded world • Is compatible through as many use-cases and communication partners as possi- ble • Provides the features required by automotive use-cases • Is scalable from tiny to large platforms • Can be implemented on different operating system (i.e. AUTOSAR, GENIVI, and OSEK) and even embedded devices without operating system 6 of 101 Document ID 660: AUTOSAR_SOMEIPTransformer — AUTOSAR CONFIDENTIAL — Specification of SOME/IP Transformer AUTOSAR CP R19-11 2 Acronyms and Abbreviations The glossary below includes acronyms and abbreviations relevant to the SOME/IP Transformer that are not included in the [1, AUTOSAR glossary]. Abbreviation / Acronym: Description: The configuration and required data of a service instance another Client-Service-Instance-Entry ECU offers shall be called Client-Service-Instance-Entry at the ECU using this service (Client). a field represents a status and thus has a valid value at all times Field on which getter, setter and notfier act upon. to send a SOME/IP-SD message in order to find a needed ser- Finding a service instance vice instance. Getter a Request/Response call that allows read access to a field. a method, procedure, function, or subroutine that is called/in- Method voked sends out event message with a new value on change of the Notifier value of the field. Request a message of the client to the server invoking a method a message of the server to the client transporting results of a Response method invocation SD Service Discovery (see[2]) a logical combination of zero or more methods, zero or more Service events, and zero or more fields (empty service is allowed, e.g. for announcing non-SOME/IP services in SOME/IP-SD) software implementation