MICROSAR Adaptive

User Manual

Version 9.0.0
English
Imprint

Vector Informatik GmbH

Ingersheimer Straße 24
70499 Stuttgart, Germany

Vector reserves the right to modify any information and/or data in this user documentation without notice. This documentation nor any of
its parts may be reproduced in any form or by any means without the prior written consent of Vector. To the maximum extent permitted
under law, all technical data, texts, graphics, images and their design are protected by copyright law, various international treaties and
other applicable law. Any unauthorized use may violate copyright and other applicable laws or regulations.
© Copyright 2024, Vector Informatik GmbH. Printed in Germany.
All rights reserved.
 Table of Content

Table of Content

1 What Do You Learn From This Manual? 6

2 About This Manual 7

3 Concepts 10
3.1 Introduction 10
3.2 Classic And Adaptive 10
3.3 The Adaptive Concept 11
3.3.1 A Deeper Look In The Adaptive Applications 13
3.3.2 MICROSAR Adaptive Delivery - BSW 15
3.3.3 From Delivery to ECU 16
3.3.4 MICROSAR Adaptive Delivery - DaVinci Developer Adaptive 17
3.3.5 Complete Overview as Summary 18
3.4 MICROSAR Adaptive Clusters 19
3.4.1 Clusters and Modules 20
3.5 General Requirements for MICROSAR Adaptive 22
3.5.1 Customer Code Declarations 22
3.5.2 Only Use Public API in Customer Code 22
3.5.3 C/C++ Compiler Settings 23
3.5.4 Validity of Enums, Pointers and Values 23
3.5.5 Multi-Threaded Execution and Reentrancy 23
3.5.6 Building Libraries and Executables 23
3.5.7 Uniqueness of Model Element Short Names 24
3.5.8 Multiple Processes per Executable Not Supported 24
3.5.9 Support of Suspend-to-RAM 24
3.5.10 Environment Variables of Global Scope 24
3.5.11 Dynamic Memory Allocation 25
3.5.12 Model Extensions 25
3.5.13 Persistent Data Migration During Update 26
3.6 TACO 26
3.6.1 Preface 26
3.6.2 TACO 27
3.6.2.1 CMake Requirements 27

4 StepbyStep 28
4.1 Step By Step Through an Adaptive Application 28
4.1.1 The Template Explains 28
4.2 Steps Using TACO 28
4.2.1 Use the Given Template for TACO 28
4.2.1.1 Models 29
4.2.2 CMake 32
4.2.2.1 HWSRC_APP_OUTPUT_NAME 32
4.2.2.2 add_subdirectory 32
4.2.2.3 taco_target_properties 32
4.2.2.4 app/hello_world/taco.cmake 32
4.2.3 Source Code 33
4.2.3.1 main.cpp 33
4.2.3.2 application.h / application.cpp 33

© Vector Informatik GmbH Version 9.0.0 3

 Table of Content

4.2.3.3 hello_world_error_domain.h / hello_world_error_domain.cpp 34

4.2.4 Run the Application with TACO 35

5 AdvancedTopics 36
5.1 Signal Handling 36
5.2 C++ Exceptions 39
5.2.1 Compilation Without Exception Support 40
5.2.2 Exeption Propagation 40
5.3 C++ Error Handling 40
5.3.1 Result Type 41
5.3.2 Error Propagation 41
5.4 Using Symbolic Links to Start Non-Adaptive Application Outside the Base Directory 42
5.5 Configurable Executable Path for Applications 43
5.6 Integration Non-AUTOSAR Applications 43
5.6.1 Starting Non-AUTOSAR Applications 43
5.6.2 Companion Process 44
5.6.3 Using Diagnostic Tools or Debuggers 46
5.7 Initialization and Shutdown 47
5.8 Orderly Shutdown and Restart of an MICROSAR Adaptive ECU 49
5.8.1 Manual Orderly Shutdown and Restart 49
5.8.2 Automated Orderly Shutdown and Restart Triggered by State Manager 50
5.8.3 Automated Orderly Shutdown and Restart Triggered by SIGTERM 51
5.8.4 Rapid Shutdown and Restart Triggered by State Manager 51
5.9 Disable Execution State Reporting 52
5.10 Additional Restrictions and Exceptions 52
5.10.1 Iterators 53
5.10.2 C-Style Strings 53
5.10.3 Ranges 53
5.11 Abnormal Terminations 53
5.11.1 Detection and Notification 53
5.11.1.1 Execution Manager 54
5.11.1.2 Other Parent Processes 55
5.11.1.2.1 Examples 55
5.11.2 Recovery 55
5.11.3 Application Components and Daemons 55
5.11.4 Library Components 56
5.11.5 Customer Provided Modules 56
5.12 Support of Multiple Adaptive AUTOSAR API Releases 56
5.12.1 C++ Namespace Separation Pattern 57
5.12.2 Build Time Selection of Standard Namespace Mappings 57

© Vector Informatik GmbH Version 9.0.0 4

 Table of Content

5.13 Support of Multi-Target 58

5.14 Source Code of Lower Quality Grade 60

6 Additional Information 61
6.1 Cheat Sheets 61
6.2 Service Oriented - a Flexible Communication Concept 62
6.3 Glossary and Abbreviations 63
6.4 Reference Documents 64

© Vector Informatik GmbH Version 9.0.0 5

 What Do You Learn From This Manual?

1 What Do You Learn From This Manual?

It is up to you how to work with this user manual and depends on your knowledge level
about AUTOSAR Adaptive and MICROSAR Adaptive, the idea behind it and its concepts.
The document contains the following main parts:

Introduction
The chapter you are in right now provides general Information about this document,
meaning of icons and styles, etc.

Concept Step by Step

For beginners: Basic introduction and Start directly: What to do to get
explanation of MICROSAR Adaptive basically running

Concepts StepbyStep

Advanced Topics
Collection of different topics.

AdvancedTopics

Additional Information
Supplementary topics.

Additional Information

© Vector Informatik GmbH Version 9.0.0 6

 About This Manual

2 About This Manual

This document gives an overview on product-wide behavior or use-cases. To ensure

correct operation of the product always follow the instructions provided in the technical
references and (additionally for safety projects) the safety manual. The content of these
documents always replaces/overrides the content from this user manual.

History Information

For detailed information about what's new, what's changed in current version, refer to
section What's New, What's Changed?

Conventions
Conventions The tables below show the notation and icon conventions used throughout the manual.

Style Use
bold Elements of the user interface, for example, dialog names and menu
items
[OK] Notation for buttons in square brackets
File | Save Notation for menus and menu items
file.xml File names, directory names and source code elements
Source code Source code block
Hyperlink References and hyperlinks
<Ctrl>+<S> Key combinations

Icon Use
Notes and tips

Caution

References

Examples

Multimedia references

Introduction

Basic knowledge

Expert knowledge

© Vector Informatik GmbH Version 9.0.0 7

 About This Manual

Icon Use
Step-by-step instructions

Changes

Instructions on editing files

Editing is prohibited

Certification
Cerfification Vector Informatik GmbH has ISO 9001:2008 certification. The ISO standard is a globally
recognized standard.

Warranty
Warranty We reserve the right to modify the contents of the documentation or the software without
notice. Vector disclaims all liabilities for the completeness or correctness of the contents
and for damages which may result from the use of this documentation.

Support
Support Need support? You can submit your support request in the Vector Customer Portal, via e-
mail or telephone.
> Contact via Vector Customer Portal:
https://portal.vector.com/
> Contact via e-mail or telephone:
https://www.vector.com/int/en/company/contacts/support-contact/

Trademarks
Trademarks All brand names in this documentation are either registered or non-registered trademarks
of their respective owners.

Errata Sheet of Hardware Manufacturers

Caution! Vector only delivers software!

Your hardware manufacturer will provide you with the necessary errata sheets
concerning your used hardware. In case of errata, please provide us with the relevant
erratas and we will examine whether this hardware problem is already known to us or
whether to get a possible workaround.

Because of many NDAs with different hardware manufacturers or because we are not
informed about them, we are not able to provide you with information concerning
hardware errata of the hardware manufacturers.

© Vector Informatik GmbH Version 9.0.0 8

 About This Manual

Example Code

All application code in any of the Vector User Manuals is for training purposes only.
They are slightly tested and designed only to understand the basic idea of using a
certain component or set of components. Vector gives consent that you use it as a
basis for developing your own code and modify it (Vector waives its copyright to forbid
you the use), however, with regard to the fact that the code is designed for training
purposes only and not for the use by you, usability of the code is not warranted and
Vector’s liability shall be expressly excluded in cases of normal negligence, to the
extent admissible by law or statute. Of course, you have to test the software developed
on the basis of the code with diligent care before using the software.

This UserManual_MICROSARAdaptive manual is based on a constantly evolving

product, so not all details described here are necessarily valid for the latest
version.

This document gives an overview on product-wide behavior or use-cases. To ensure

correct operation of the product always follow the instructions provided in the technical
references and (additionally for safety projects) the safety manual. The content of these
documents always replaces/overrides the content from this user manual.

Tools provided in the BSW Package as well as DaVinci Developer Adaptive operate
with the folder structure that was used to ship the BSW Package. Changes of the BSW
Package folder structure may result in tool malfunction as the required files cannot be
found as expected. It is therefore not recommended to modify the BSW Package folder
structure

© Vector Informatik GmbH Version 9.0.0 9

 Concepts

3 Concepts

Further information > Introduction

> Classic And Adaptive
> The Adaptive Concept
> MICROSAR Adaptive Clusters
> General Requirements for MICROSAR Adaptive
> TACO

3.1 Introduction

A chapter for beginners This chapter is meant for those who are new to the topic AUTOSAR Adaptive. Especially
and interested. those, who switch from AUTOSAR Classic projects to AUTOSAR Adaptive projects could
have some struggle to understand the different approach between Classic and Adaptive.
But there are also parallels.

3.2 Classic And Adaptive

A brief comparison The development of the AUTOSAR Classic Platform focuses on the requirements for the
development of statically configured automotive Electronic Control Units (ECU) with hard
real-time requirements.
The AUTOSAR Adaptive Platform is a software architecture for the creation of ECUs that
have to cope with upcoming requirements of more demanding use cases such as
automated driving or central applications servers and require more computation power
and flexibility in installation and updating software.
Performance The Adaptive Platform supports high-performance microprocessors with different
operating systems (POSIX-based), more complex application functionality and enables
software development cycles that are much shorter than the typical life cycle of vehicle
models.
Dynamic The Adaptive Platform provides more flexibility in how Automotive Applications can be
implemented and in which Automotive Application can be deployed in vehicles. There is
no longer one binary to download to the hardware. The user experience is similar to a
mobile phone or a PC, you can add and update applications dynamically.
A vision: Software One vision is, to build up a software store like an Appstore to be able to install and
Store continuously update or purchase additional software for your vehicle.

A Software Cluster is a deployable set of adaptive applications.

Adaptive Platform will The AUTOSAR specification is separated into three parts. There is the Foundation, the
complement Classic Classic Platform and the Adaptive Platform.
Platform The Foundation includes the specification of e.g. the bus protocols to ensure
communication compatibility.

© Vector Informatik GmbH Version 9.0.0 10

 Concepts

The Adaptive Platform is designed to complement and interact with the classic world.

Figure 1: Foundation Overview

Communication Traditionally, automotive communication is based on broadcasting signals, which fit very
well for control data of limited size, which has to be communicated cyclically. In
AUTOSAR Classic there is also implemented a static service-based communication
concept.
Due to the possibility to install new applications on the ECU, a static configuration of
communication paths is not suitable. A communication paradigm that enables the
developer to find and establish connections during runtime is needed. The Adaptive
Platform will provide service-oriented communication along with the existing signal-based
paradigm.

3.3 The Adaptive Concept

Adaptive AUTOSAR and MICROSAR Adaptive

MICROAR Adaptive is a product of Vector according to the specifications of Adaptive
AUTOSAR.

The illustration below is a schematic drawing of an Adaptive ECU on the left side and a
Classic ECU on the right that are connected via Ethernet.
They are designed in a very different way to see the differences at a glance. The folder
symbols in the Adaptive Application are chosen to emphasize that its structure is more
like you know it from a personal computer.

© Vector Informatik GmbH Version 9.0.0 11

 Concepts

Please keep in mind that this is just a conceptual illustration to get an understanding
without claim to completeness or technical correctness.

Figure 2: Conceptual Illustration

AUTOSAR Classic In AUTOSAR Classic an ECU is organized via different software components (SWC),
connected to the Basic Software via the runtime environment (Rte). So, there can be
many software components that use one AUTOSAR stack organized by an AUTOSAR
Operating System with predefined tasks, events, alarms, etc.
AUTOSAR Adaptive The organization within adaptive software is different. As there is used a POSIX-OS, the
organization within an ECU is more like a file system you know from PCs or MACs. So,
an Adaptive Application can be physically seen as a folder at a predefined place in a file
system of a POSIX-OS. This folder essentially contains an executable.
Two kinds of Adaptive In Adaptive, you can basically distinguish between two kinds of Applications, that are
Applications marked with blue and red in the illustration above - User Applications and BSW
Application. All Adaptive Applications communicate with each other what is essential for
the function of an ECU.
User Applications (blue)
From the functional point of view, you can compare the User Applications with the
Software Components (SWC) in AUTOSAR Classic. These applications are responsible
for the actual function of the ECU like e.g., Seat Adjustment or Lane Assist. They consist
of the functional customer software and the functional necessary parts of the BSW.
These parts of the BSW either implement a complete functionality or just enable
communication to other User Applications or to other parts of the BSW that are
implemented as BSW Applications.
BSW Applications (red)
In AUTOSAR Classic these are the Basic Software Modules.
In Adaptive, several basic software modules are implemented as Software Components
in their own Applications. These BSW Applications can in turn make use of other BSW
functionality in the same way as already mentioned for the User Applications above.

A good saying!
With MICROSAR Classic you embed the User Application (Software Components) into
the Basic Software.
With MICROSAR Adaptive you embed parts of the Basic Software once into each
individual Adaptive Application, where you need the provided functionality.

Further information > A Deeper Look In The Adaptive Applications

© Vector Informatik GmbH Version 9.0.0 12

 Concepts

> MICROSAR Adaptive Delivery - BSW

> From Delivery to ECU
> MICROSAR Adaptive Delivery - DaVinci Developer Adaptive
> Complete Overview as Summary

3.3.1 A Deeper Look In The Adaptive Applications

In the illustration above, the Adaptive Applications are drawn very simple to get a
conceptual understanding. But the little grey and the light blue boxes already show, that
for real there is more inside than just the executable.

Figure 3: Applications and Executables

A look into Lane Assist Executable of a User Application

A look into a User Application is shown below. It contains the actual application logic of
the User Application; in this example this is the Lane Assist Application Logic.
Additionally there in are the further necessary parts of the BSW like: Com, PhM, Log, Os
and vac.
There are parts of the BSW that offer a direct interface to the User Application Logic
(ara:: connected with line) and those that map internal implementation details.

Figure 4: Lane Assist

main{} has to be Any User Application need to have the function main{} that is also its entry point. This
provided by the function has to be provided by the customer.
customer One of the tasks of the main{} function is to initialize the BSW to be able to use its
services afterwards. During the initialization phase, the BSW reads in its configuration
data that is stored within JSON files (see light blue boxes).

Find more about BSW initialization in the UserManual_AdaptiveMICROSAR in the

TechnicalReferences folder of your delivery.

The folders of an Folders of an User Application

Adaptive Application

© Vector Informatik GmbH Version 9.0.0 13

 Concepts

The following illustration gives insight in a real folder structure of an Adaptive Application.
Basically, there are three folders: bin, etc and var.

Figure 5: DriverAssistance File View

bin The system expects the executables within the bin folder.
etc All configuration files like above mentioned JSON files are stored in the etc folder.
var In the standard, volatile data of the Adaptive Applications should be stored to the folder
var.

The folder var is just the standard folder. Per configuration you can change this as
necessary for your Adaptive Application.

someipd-posix-application.json of folder etc

This configuration file describes which ara::com services the application offers and
which services it needs from outside (for more information about services oriented
communication see Service Oriented - a Flexible Communication Concept.
Which files must be in this folder depend on BSW services that are used by the
Adaptive Application. As an example, Per (Persistency) is only there in if the function
persistency is needed.

A look into a BSW Executable of a BSW Application

Application

© Vector Informatik GmbH Version 9.0.0 14

 Concepts

Basically, a BSW Application follows the same rules as already described for User
Applications. One difference is that the BSW Applications are Adaptive Application that
provided by Vector as part of the MICROSAR Adaptive delivery. This delivery also
contains the actual application logic of the BSW Applications and also necessary parts. In
the case of PhM this is PhM Application Logic and vac.

Figure 6: Phm Application Logic

3.3.2 MICROSAR Adaptive Delivery - BSW

The delivery of BSW modules form Vector is called BSW Package. A BSW Package is a
bundle of ordered software components as a ZIP-file.
This chapter focuses on content of a BSW Package and it will show very clearly the
connection between delivered BSW modules and their usage within the Adaptive
Application Lane Assist example from the last chapter.

Figure 7: BSW Package Content

PhM and vac as The PhM delivery contains a PhM Application file that represents the PhM Application
example Logic and another file that is the PhM lib.
Within the PhM lib the ara::phm is implemented that has to be used by all User
Applications and other BSW Applications that need the functionality of the PhM. The
ara::phm is not only an interface to the Phm, it also contains a part of the functionality of
the PhM. The rest is implemented in the PhM Application Logic.
Another example is the vac. It is an internal supporting component used by all other
components of MICROSAR Adaptive. Therefore, it is used in all applications that make
use of at least one other part of MICROSAR Adaptive.

© Vector Informatik GmbH Version 9.0.0 15

 Concepts

3.3.3 From Delivery to ECU

Many different use AUTOSAR Adaptive is designed not only for flexible software update but also for flexible
cases software design. There are many different possible use cases how to create an ECU.
In this startup description, a very simple use case is shown, that comprises 6 steps.

In many cases, the ARXML is already given, e.g., by the OEM. In this case just leave
out the first step Authoring and continue with step 2 or 3.

According to AUTOSAR, the ARXML contains only necessary parts. There is no chance
to know before, which parts your software will need, so it is up to you to change and
extend the ARXML file.

Authoring 1. Authoring / (Modelling)

In this first step you develop the ARXML Model consisting of multiple different ARXML
files. These ARXML files are interface definition files that can also be used as exchange
format between different tools, different departments or even companies.
In the ARXML you define software design, executables, machines, port interfaces, etc. It
is an overall definition of your system as well as your applications and their need of
Adaptive AUTOSAR features.
What is Authoring / Adaptive software should be easily portable and reusable. Via modeling the software and
Modelling and why is its requirements to the environment to work properly is described in a very abstract way.
it? In case of changes of the environment, just the modeling must be adapted and not all the
details.
As modeling language, ARXML is used. AUTOSAR has defined a set of modeling
properties. And there are additional properties defined by Vector to extend the AUTOSAR
definitions.
DaVinci Developer Adaptive knows the AUTOSAR definitions and the Vector extensions
and supports you with this work.

Validation 2. Model Validation

This step checks the content and parameters of the ARXML for plausibility.
DaVinci Developer Adaptive knows the AUTOSAR definitions and the Vector extensions
and supports you with this work.

Generation 3. Generation
This produces the code C++ and configuration files JSON.
Source code and JSON What are Generators?
files Generators take the user configration as an ARXML model. They extract the
configuration information and produce appropriate generated C++ code and runtime
configuration files. This code and runtime configuration instructs the BSW to exhibit the
configured behavior.
This can also be done via DaVinci Developer Adaptive or via command line tool.
IDE 4. User Application Development (IDE)
This step comprises the actual development and programming of your application logic
according to its required functions and is usually the major work for you to do.
As an example, this can be the code for the Lane Assist Application Logic, that reads ins
camera data and transforms this data into steering information.
Compile 5. Compile (and Link)
Your code (step 4), the previously generated files C++ (step 3) and the necessary parts
of the BSW Package are now compiled to an executable.

© Vector Informatik GmbH Version 9.0.0 16

 Concepts

ECU 6. Deploy to ECU

Put executable and JSON file (step 3) into the ECU and its done.
The software is ready to be run.
What is DaVinci In the steps above, DaVinci Developer Adaptive is mentioned several times.
Developer Adaptive? But what is it?

3.3.4 MICROSAR Adaptive Delivery - DaVinci Developer Adaptive

Another part of the MICROSAR Adaptive delivery is DaVinci Developer Adaptive.
DaVinci Developer Adaptive is an eclipse plugin and is designed for supporting you as
mentioned above in the steps 1 to 3 (see section From Delivery to ECU).
In detail:
Authoring / Modelling > Creation and editing of any ARXM model.
(Step 1) > DSL for more support via AUTOSAR Meta Model knowledge and auto completion.
> ARXML models can be structured in projects.
> Content of models of a project can be spread to different files.
> Models can be combined using project references.
Model Validation > Start validation and solving actions
(Step 2) > Support with error tracking and bugfixing
Generation > Model-dependent generation of source code and configuration data for application
(Step 3) and ECU.

Command Line Interface – CLI

There also exists a CLI. The CLI supports features of the step 2 – Model Validation and
step 3 – Generation.

DaVinci Developer The following screenshot gives an overview of DaVinci Developer Adaptive and its views
Adaptive and functions.

Figure 8: DaVinciDeveloper Adaptive Views and Functions

1. AUTOSAR Adaptive projects in Project Explorer

© Vector Informatik GmbH Version 9.0.0 17

 Concepts

2. Generic Model Editor with object tree

3. Compact DML syntax for textual definition of AUTOSAR models
4. Auto-completion for references and model elements
5. Specialized validation view with direct feedback on model validation
6. Comfort Editors for simplifying model authoring for various tasks such as service
deployment.
7. Wizards for various tasks such as creation of service instances
8. Project frames keep the editors or each project together
9. Cheat Sheets for easy information access

3.3.5 Complete Overview as Summary

Result Now to finalize the conceptual overview of MICROSAR Adaptive, see all parts put
together into one big picture.

Figure 9: Complete Overview

© Vector Informatik GmbH Version 9.0.0 18

 Concepts

3.4 MICROSAR Adaptive Clusters

Cluster Overview The illustration below shows an overview of the MICROSAR Adaptive functional clusters.

Figure 10: MICROSAR Adaptive

Cluster Description
COM Communication
SEC Security
DIAG Diagnostics
EXEC Execution Management
LOG Log and Trace
NM Network Management
OS Operating System
PER Persistancy
PHM Platform Health Management
SM Station Management
TSYN Time Synchronization
UCM Update and Configuration Management

© Vector Informatik GmbH Version 9.0.0 19

 Concepts

Further information > Clusters and Modules

3.4.1 Clusters and Modules

The following list shows the clusters and the containing modules and helps you
understanding the content of a BSW Package delivery.

Clusters and Modules Cluster Modules within the Subfolders in BSW

Cluster
Communication
AraCom amsr-vector-fs-communicationmiddleware
ComCommon amsr-vector-fs-comcommon
ComTrace amsr-vector-fs-comtrace
IpcBinding amsr-vector-fs-ipcbinding
IpcMulticast amsr-vector-fs-ipcmulticast
IpcServiceDiscovery amsr-vector-fs-ipcservicediscovery
PassThroughManager amsr-vector-fs-passthroughmanager
SecureCommunication amsr-vector-fs-sec-libseccom
Socal amsr-vector-fs-socal
SomeIpBinding amsr-vector-fs-someipbinding
SomeIpDaemon amsr-vector-fs-someipdaemon
SomeIpDaemonClient amsr-vector-fs-someipdaemonclient
SomeIpProtocol amsr-vector-fs-someipprotocol
ZeroCopyBinding amsr-vector-fs-zerocopybinding
ZeroCopyCommon amsr-vector-fs-zerocopycommon
Diagnostics
AraDiag amsr-vector-fs-aradiag
DiagnosticManager amsr-vector-fs-diagnosticmanager
DiagnosticRpc amsr-vector-fs-diagnosticrpc
DiagnosticRpcComBinding amsr-vector-fs-diagnosticrpccombinding
DiagnosticUtility amsr-vector-fs-diagnosticutility
DOIPBinding amsr-vector-fs-doipbinding
PduHdrTpBinding amsr-vector-fs-pduhdrtpbinding
UdsTransport amsr-vector-fs-udstransport
Execution Manager
ExecutionManager amsr-vector-fs-em-executionmanager
Network Management

© Vector Informatik GmbH Version 9.0.0 20

 Concepts

Cluster Modules within the Subfolders in BSW

Cluster
Network Management amsr-vector-fs-nm-networkmanager
Log and Trace
LogDaemon amsr-vector-fs-log-daemon
LogAndTrace amsr-vector-fs-log-api
LogConfig amsr-vector-fs-logconfig
LogUtility amsr-vector-fs-logutility
ResourceMonitor amsr-vector-fs-resourcemonitor
Persistency
AsrApPersistency amsr-vector-fs-per-libpersistency
Platform Health Management
PlatformHealthManagement amsr-vector-fs-phm-healthmanager
Update & Configuration Management
UpdateManager amsr-vector-fs-updatemanager
Operating System
OsAbstraction amsr-vector-fs-libosabstraction
Thread amsr-vector-fs-thread
Time Synchronization
AsrApTimeSync amsr-vector-fs-timesync
Base Libraries
ApplicationBase amsr-vector-fs-applicationbase
CharacterConversion amsr-vector-fs-characterconversion
ConfigurationAccess amsr-vector-fs-configurationaccess
Crc amsr-vector-fs-crc
E2E amsr-vector-fs-e2e
IoIntegrityStream amsr-vector-fs-iointegritystream
IoStream amsr-vector-fs-libiostream
Msr4Base amsr-vector-fs-msr4base
VaCommonLib amsr-vector-fs-libvac
VaJson amsr-vector-fs-vajson
SEC
AraCrypto amsr-vector-fs-aracrypto
Crypto amsr-vector-fs-sec-cryptostack
VaAsn1 amsr-vector-fs-vaasn1

© Vector Informatik GmbH Version 9.0.0 21

 Concepts

Cluster Modules within the Subfolders in BSW

Cluster
libES amsr-vector-fs-sec-cryptostack-driver-lib_es
SoftwareCryptoProvider amsr-vector-fs-softwarecryptoprovider
IdentityAccessManager amsr-vector-fs-sec-iam
AraIdsm amsr-vector-fs-araidsm

3.5 General Requirements for MICROSAR Adaptive

There are a few rules you should take care when working with MICROSAR Adaptive.

Further information > Customer Code Declarations

> Only Use Public API in Customer Code
> C/C++ Compiler Settings
> Validity of Enums, Pointers and Values
> Multi-Threaded Execution and Reentrancy
> Building Libraries and Executables
> Uniqueness of Model Element Short Names
> Multiple Processes per Executable Not Supported
> Support of Suspend-to-RAM
> Environment Variables of Global Scope
> Dynamic Memory Allocation
> Model Extensions
> Persistent Data Migration During Update

3.5.1 Customer Code Declarations

There is an additional requirement to take care of.

Do not make any source code declarations: in the ::amsr or ::ara namespace or any
child namespace, unless a customization point is defined explicitly in our documentation
This usage restriction also applies to C++ namespaces configured in ARXML.
Rationale: Additional declaration in the mentioned namespaces may induce unintended
C++ name lookup results, hence leading to malfunction or compilation issues.

3.5.2 Only Use Public API in Customer Code

Only Use Public API: The API of the MICROSAR Adaptive product is built by public
classes, their methods, free functions, and types. Classes, their accessible methods,
free functions, and other types that are intended to be used by customer are annotated
with the documentation tag \vpublic. These items build the product public API.
Customer software shall just use the public API of MICROSAR Adaptive.
The private part shall not be used!

© Vector Informatik GmbH Version 9.0.0 22

 Concepts

3.5.3 C/C++ Compiler Settings

By default, all source files (.cpp, .cc) need to be compiled with a C++ compiler. C-Code
files (.c) have to be compiled using a C compiler / compiler flags.

More Information about C/C++ compiler standard see document

ProductInformation_2_MICROSARAdaptive.pdf in your delivery.

Make sure that the compiler settings match to the hardware (platform) where the
compiled code is executed.

To ensure binary compatibility, all parts of the MICROSAR Adaptive product, e.g.
platform (daemons) and applications (libraries) must be compiled with
> the same compiler version and
> the same compiler options.

3.5.4 Validity of Enums, Pointers and Values

Please make sure to consider the documentation of the MICROSAR Adaptive functions
and only pass valid pointers and enum values at all interfaces to MICROSAR Adaptive
components (see AUTOSAR C++ A7-2-1 for enum values).

Enums, pointers or arguments with invalid values that violate the contract of an API could
lead to immediate termination of the process or undefined behavior.

3.5.5 Multi-Threaded Execution and Reentrancy

Whether a function is thread-safe is documented by the documentation tag
\threadsafe using TRUE or FALSE. If thread-safety depends on other factors, an
explaining comment after TRUE is provided.

Except where explicitly specified by the documentation tag \threadsafe TRUE, thread
safety of functions cannot be assumed.

Whether a function may be recursively reentered is documented by the documentation

tag \reentrant using TRUE or FALSE. If reentrancy depends on other factors, e.g. handles,
an explaining comment after TRUE is provided.

Except where explicitly specified by the documentation tag \reentrant TRUE, a function
shall not be interrupted during its execution and then called again before its previous
invocation has returned.

3.5.6 Building Libraries and Executables

Libraries and executables must be built based on the same AMSR release with the same
compiler and identical compiler settings. Lazy binding must not be used.

Due to component-specific properties, some components cannot be built as static

libraries and must be directly linked into the executable. To identify such components,
please refer to the Technical Reference documents.

© Vector Informatik GmbH Version 9.0.0 23

 Concepts

Vector makes no statement to the question, whether other code like STL, libc, OS
libraries or other third party libraries can be linked dynamically or must be linked
statically. This is up to the customer, possibly in consultation with the provider of the
other code.

3.5.7 Uniqueness of Model Element Short Names

> Executable short names shall be unique within the set of all Executable model
elements.
> Machine short names shall be unique within the set of all Machine model
elements.
> SoftwareCluster short names shall be unique within the set of all
SoftwareCluster model elements.
> Process short names shall be unique for all Process elements mapped to a
single Machine and for all Process elements mapped to a single
SoftwareCluster.

Violating the uniqueness constraints cannot be detected on Vector side.

3.5.8 Multiple Processes per Executable Not Supported

Currently, multiple processes per executable are not supported. The generators cannot
generate artifacts for multiple processes. Execution of an executable as multiple
processes may cause undefined behavior. Currently, only one process per executable is
supported.

3.5.9 Support of Suspend-to-RAM

The support of Suspend-to-RAM with MICROSAR Adaptive requires, that both the
operating system and the C++ library support a steady clock behavior.
This means that the POSIX clock type CLOCK_MONOTONIC and the C++ clock type
std::chrono::steady_clock stop counting ticks during ECU suspend.
When the kernel resumes scheduling the user threads on the ECU, the clocks should
continue counting at the point in time of ECU suspend.

If this requirement is not met, such that user processes are missing time intervals of the
clocks mentioned before, premature expiration of platform health manager deadlines can
occur. If the operating system exposes such behavior, it can be worked around by
suppressing supervision during suspend. Refer to using dedicated function group states
[8] for mode dependent supervision.

3.5.10 Environment Variables of Global Scope

Local environment variables, that are used by one single component, are documented
in the corresponding Technical Reference.

Global environment variables have AMSR_ as name prefix and are used by multiple
components. They can either be feature switches or configuration options.

© Vector Informatik GmbH Version 9.0.0 24

 Concepts

All environment variables with prefix AMSR_ are exclusively used by MICROSAR
Adaptive.
Do not define any environment variable with prefix AMSR_.
Modify only those environment variables with prefix AMSR_ that are listed either in the
according technical reference or here in this user manual. Make sure to follow the given
limitations for each environment variable.
You are responsible for the correct setting of environment variables with prefix AMSR_.

Environment Variable Description

AMSR_DISABLE_INTEGRITY_CHECK Disables the integrity check of
configuration files for QM and
development purposes when set to 1.
AMSR_PROCESS_SHORT_NAME_PATH Contains the process short name path of
the specific process as specified in the
ARXML model. This environment variable
is used by the process to identify itself,
e.g. for the integrity check of configuration
files.

3.5.11 Dynamic Memory Allocation

MICROSAR Adaptive uses dynamic memory allocation. The overall system design must
ensure that memory allocation is successful at all times. Otherwise, the product may
exhibit arbitrary and undefined behavior, including but not limited to ignoring the error.

3.5.12 Model Extensions

DvMEX ARXML files are used for modelling, as defined by the AUTOSAR standard. However,
Vector has introduced some additional vendor-specific parameters, beyond the
AUTOSAR definition.
These additions are called DaVinci Model Extensions (DvMEX) and are using the
AdminData to extend specific model elements. Formal definitions of these DvMEX are
included in the BSW package and provide a description of each parameter and its
purpose.

© Vector Informatik GmbH Version 9.0.0 25

 Concepts

Use DaVinci Developer Adaptive to edit MEX parameters the same way as any other
AUTOSAR defined parameter.

3.5.13 Persistent Data Migration During Update

The structure of persistent data stored by softare components might be potentially
changed due to introduction of new functionalities inside the existing software
components. In such a case, an automated migration of the existing persistent data
would be needed during the software update process to enable the correct usage of the
persistent data after the SW update.
The MICROSAR Adaptive product offers currently only a restricted support of the
automated persistent data migration for the following component:
> UpdateManager (UCM) – upward migration between two subsequent persistent data
versions.
All other related components might need a user interaction to reset/delete/reinitialize the
impacted persistent data storages.

Please consult Vector to find out about the current status of persistent data migration
during update.

3.6 TACO

Further information > Preface

> TACO

3.6.1 Preface

Vector provides the build tools as example. They are neither intended nor qualified for
use in series production.

© Vector Informatik GmbH Version 9.0.0 26

 Concepts

The example build tools as well as any of its modifications and/or implementations must
be tested with diligent care and must comply with all quality requirements which are
necessary according to the state of the art before their use.
MICROSAR Adaptive is shipped with the build tool TACO.

3.6.2 TACO
TACO TACO is a collection of tools written for and in CMake, and not a tool of its own. It is
written in CMake and also called from within CMake.

Currently, we are in a transition phase to TACO, therefore, instead of only

CMakeLists.txt you will see:
> CMakeLists.txt: Switch to taco.cmake, if CMake is called by TACO build
> taco.cmake: CMake files for TACO build
The aim of TACO is to provide a concise build process which is driven only by CMake
and without an additional layer on top of it. This reduces complexity, simplifies CMake
files by following the Modern CMake approach and makes it easier to use the
MICROSAR Adaptive stack in other projects.

For more information see the TechnicalReference_TACO.pdf in folder Doc|

TechnicalReferences of your delivery.

Further information > CMake Requirements

3.6.2.1 CMake Requirements

Version Requirement Please make sure to use CMake version 3.25 or higher!

© Vector Informatik GmbH Version 9.0.0 27

 StepbyStep

4 StepbyStep

Further information > Step By Step Through an Adaptive Application

> Steps Using TACO

4.1 Step By Step Through an Adaptive Application

The following uses the example application amsr-vector-app-example-hello-world as a

template. The files of the example are briefly described.
To get the copy of the example running, there are some minor changes necessary, that
are also described.
In the end your first little adaptive application is running “printing out” your message.

Find more information about TACO.

Further information > The Template Explains

4.1.1 The Template Explains

> What was already done for you?
> What was modeled?
TACO Start with TACO:
Follow section Steps Steps Using TACO.

4.2 Steps Using TACO

The following description is meant for using TACO.

Further information > Use the Given Template for TACO

> CMake
> Source Code
> Run the Application with TACO

4.2.1 Use the Given Template for TACO

1. Copy the directory <SIPDIR>/Examples/amsr-vector-app-example-hello-
world to your workspace.
2. Rename the copied directory according to your application. In this example we name
it amsr-vector-app-my-example.

Your workspace and the location may be located outside of <SIPDIR>. In this example
it is located in ~/src/amsr-vector-app-my-example.

Open a terminal session. To build with TACO set the environment variable
AMSR_SRC_DIR to the path of the BSW Package delivery.

© Vector Informatik GmbH Version 9.0.0 28

 StepbyStep

$ export AMSR_SRC_DIR=~/src/adaptive-microsar
In the terminal change to the directory of amsr-vector-app-my-example and initialize
the build-cache with CMake:
$ cd ~/src/amsr-vector-app-my-example
$ cmake -S . --preset=gcc7_linux_x86_64 -C ${AMSR_SRC_DIR}/
CMakeConfig/linux_gcc7.cmake
The CMake command will initialize a build-cache in ./build/gcc7_linux_x86_64.
Run the code generators for both amsr and hwsrc prefixed targets and reload the build
cache:
$ cd build/gcc7_linux_x86_64
$ ctest -R '(amsr|hwsrc)_.*\.DvACfg.Generate' --progress --
parallel $(nproc)
$ cmake .
The main CMake target is the executable hwsrc_app. To build it together with its
MICROSAR Adaptive dependencies call the following (in the build-directory):
$ cmake --build . --target hwsrc_app --parallel $(nproc)

Further information > Models

4.2.1.1 Models
./model/ All AUTOSAR xml files are located at ./model/

Figure 11: Model

AUTOSAR_MOD_Stan The file AUTOSAR_MOD_StandardTypes.arxml contains the AUTOSAR standard

dardTypes.arxml datatypes.
MyAdaptiveMachine.ar The file MyAdaptiveMachine.arxml contains the MachineDesign and the machine
xml description.
The ModeDeclarationGroups defined here are the set of machinestates and
applicationstates that are available on this machine.
The ethernet cluster is defining which IP addresses should be used. In the machine
design there are references to not used communication connectors, which can be used.
The UserDefinedConnector is an example for IPC.
The EthernetCommunicationConnector is an example connector which can be used
for SOME/IP communication in later steps.
Additionally, some service discovery configs are defined in the machine
design.
The machine is referring the machine design.
Additionally, the processor cores are defined.
The ResourceGroups are defined in the machine as well.

© Vector Informatik GmbH Version 9.0.0 29

 StepbyStep

MyAdaptiveApplication. The file MyAdaptiveApplication.arxml contains the Executable, the

arxml StartupConfigSet and the Process.
The executable is the description of your executable running on the system.
You should take care that the short name of the executable matches with the name
of your executable on the target,
i.e. that you have to rename any amsr_vector_app_hello_world_example in the file to
amsr_vector_app_my_example.

You can also use the DaVinci Adaptive Tool Suite for this.
1. Open your project in

2. Click [Directory] and browse to the folder amsr-vector-app-my-example

3. Click [Finish]
4. Open the context menu on your project
5. Select Configure|Convert to DaVinci Adaptive Project…

© Vector Informatik GmbH Version 9.0.0 30

 StepbyStep

6. Set model as Model and select User Application

7. Click [Next] and [Finish]

8. Rename amsr_vector_app_hello_word_example with amsr_vector_app_my_example
in the name field

startup config Inside the startup config set the startupconfig is defined. We defined an
option “-c“. This option is not used by the application. If you would like to use this, you
need to implement an argument parser.

© Vector Informatik GmbH Version 9.0.0 31

 StepbyStep

Additionally, the scheduling priority and policy are defined.

The Process is the instantiation of the executable. The process is referring the
executable, the startup config and the machine state in which the process should be
running.
MyDeployment.arxml The file MyDeployment.arxml contains the Process to Machine mapping.
The definition on which machine which process is running is called
ProcessToMachineMapping.
Additionally, it defines which CPU cores should be used/not used by the process. In this
case it is CPU core 0.

4.2.2 CMake
Further information > HWSRC_APP_OUTPUT_NAME
> add_subdirectory
> taco_target_properties
> app/hello_world/taco.cmake

4.2.2.1 HWSRC_APP_OUTPUT_NAME
The variable HWSRC_APP_OUTPUT_NAME defines the name of the executable. TACO
evaluates variables named <target-upper>_OUTPUT_NAME to deduce the executable
name from the target name.

4.2.2.2 add_subdirectory
add_subdirectory("${AMSR_SRC}" "AMSR")
The AMSR stack is included as source sub-project. This means that:
> the AMSR stack and the hello world application share one build-directory
> both projects can be initialized and build with one CMake command
> the hello world application CMake files can directly reference targets from the AMSR
stack, `find_package` is not needed.

4.2.2.3 taco_target_properties
The content in these files includes the hello_world subdirectory and makes sure that the
MICROSAR Adaptive daemons are build and installed together with the hello world
application.

This is for demonstration purposes only. In a real world application you would build your
own daemons and provide your own configuration files.

4.2.2.4 app/hello_world/taco.cmake
The function dvacfg_file_gen() makes sure that the generators for the models are
run.
In this example the keyword argument OUTPUT lists generated CMake files instead of
source and config files. This has the advantage that you do not need to list each
generated file individually. dvacfg_file_gen() also adds the generated files as
dependency to the target sources of hwsrc_app.

© Vector Informatik GmbH Version 9.0.0 32

 StepbyStep

See the TechnicalReference_TACO.pdf in the path Doc|TechnicalReferenes of your

delivery for details on this function
(API Description - Module - Find Modules - FindDvACfg).

4.2.3 Source Code

The source code files are all located inside the directory ./app/hello_world/src of
the project.

Figure 12: Hello World Src

Further information > main.cpp

> application.h / application.cpp
> hello_world_error_domain.h / hello_world_error_domain.cpp

4.2.3.1 main.cpp
This is the entry point of the process. This method will return zero if the execution was
successful.
1. The first step of the main method is to block all signals for this thread and all child
threads. It is necessary that only the signalhandler thread can react on signals.
2. The next step is the initialization of logging. This step is basically reading the
configuration files and is configuring the logging settings at runtime.
3. Afterwards the initialization of the logging is supposed to be successfully done. This
is checked by the if statement.
4. The following step is to create the application object and call the run method of it.

4.2.3.2 application.h / application.cpp

application.h The file application.h gives the definition of the application class. The
application.cpp is providing the implementation of the class defined in the
application.h file.
Constructor The constructor of the application class is basically performing the initialization of the
process. In this case the signalhandler thread is started. You could for example add
the parsing of arguments, some configuration files or read some persistent data at this
point.
Destructor The destructor is setting the member variable exit_requested_ to true. This
member variable can be used to identify that the destruction of this object was triggered.
So, you could terminate the tasks you are currently performing.

© Vector Informatik GmbH Version 9.0.0 33

 StepbyStep

SIGTERM or SIGINT Afterwards the destructor is checking if exit was requested by sending SIGTERM or
SIGINT. If not the termination of the signal handler thread is triggered to shut down the
application. Finally, the destructor will wait till all threads have joined (Here just the signal
handler thread). Here you can add the logic to persist some data before shutting down.

Do not use this to store safety critical (ASIL related) information.

StartSignalHandlerThre The method StartSignalHandlerThread is basically just starting the signal handler
ad thread, setting its name, and returning an ara::core::Result object containing either
the process id or the corresponding error.
Run The method Run is the logic of the application. If the application is reaching this point and
the initialization went well it is reporting the application state kRunning to the
Executionmanager. Afterwards the example is printing a log message
“Hello AUTOSAR Adaptive World”.
At the comment seen below you can add your application logic.
/* TODO(xxx) Your application code can be added here.
* TODO(xxx) You should terminate if exit_requested_ is true
*/
Change the output 1. Open the file application.cpp
2. Change the text of the LogInfo

Please ensure like mentioned in the comment that you are going to terminate if the
exit_requested_ member is set to true.

Afterwards the application state kTerminating is reported to the Executionmanager.

SignalHandlerThread The SignalHandlerThread method is describing the behavior of the signal handler
thread.
This thread is basically just waiting for any signal. If the signal is either SIGINT or
SIGTERM the application is supposed to shut down. This is triggered by setting the
member variable exit_requested_ to true.
If another signal was received it will be ignored and the thread will wait for another
arriving signal.
ReportApplicationState The method ReportApplicationState is performing the report to the
Executionmanager using the applicationstate API.

4.2.3.3 hello_world_error_domain.h / hello_world_error_domain.cpp

hello_world_error_dom The hello_world_error_domain.h file is giving the definition of the
ain.h HelloWorldErrorDomain class.
The hello_world_error_domain.cpp is providing the implementation of the class
defined in hello_world_error_domain.h file.
This class is describing an ErrorDomain and is used to identify if an error occurred during
the startup of the SignalHandlerThread.

This is an example on how you can use the ErrorDomains in your project. If you are
not interested in just remove it.

© Vector Informatik GmbH Version 9.0.0 34

 StepbyStep

4.2.4 Run the Application with TACO

As you changed the log message you need to rebuild the application using the command
from before (from inside the build-directory):
$ cmake --build . --target hwsrc_app --parallel $(nproc)
This time the build is much faster as only the changed parts are rebuilt (incremental
build).
Install the runtime components to a dedicated folder (from inside the build-directory):
$ cmake --install . --component HWSRC_Runtime --prefix install/
gcc7_linux_x86_64
The command creates a folder install/gcc7_linux_x86_64 and places all runtime
dependencies in it, including those from the AMSR stack. The folder has the same layout
as on the target device.
Change to the install directory and run the application:
$ cd install/gcc7_linux_x86_64
$ sudo ./sbin/amsr_em_daemon -a ./opt -m ./etc/
machine_exec_config.json -l ./etc/logging_config.json

© Vector Informatik GmbH Version 9.0.0 35

 AdvancedTopics

5 AdvancedTopics

Further information > Signal Handling

> C++ Exceptions
> C++ Error Handling
> Using Symbolic Links to Start Non-Adaptive Application Outside the Base Directory
> Configurable Executable Path for Applications
> Integration Non-AUTOSAR Applications
> Initialization and Shutdown
> Orderly Shutdown and Restart of an MICROSAR Adaptive ECU
> Disable Execution State Reporting
> Additional Restrictions and Exceptions
> Abnormal Terminations
> Support of Multiple Adaptive AUTOSAR API Releases
> Support of Multi-Target
> Source Code of Lower Quality Grade

5.1 Signal Handling

Signals are one of several IPC mechanisms available on POSIX systems. In contrast to
other IPC mechanisms, the only information that a POSIX Signal can carry is its
occurrence, there is no payload information associated with it. Despite their limited
information content, Signals are an integral part of the operation of a POSIX system (e.g.,
for signaling the request to terminate a process or to signal certain error conditions) and
must therefore be dealt with properly. Due to technical details of the underlying system,
correctly handling POSIX Signals is not trivial, and several approaches exist in the
literature. In the following, one possible approach is detailed that best suits the properties
of Adaptive MICROASR.
A defined signal handling is important as all code of MICROSAR Adaptive must be
protected against concurrently occurring POSIX Signals.
To ensure that POSIX Signals do not interfere with other operations, there shall be one
dedicated thread for signal handling that receives and processes Signals. To route all
Signals to this dedicated thread, all Signals (with few exceptions detailed later) shall be
blocked at the very beginning of a new process by setting an appropriate signal mask.
This shall be done before ara::core::Initalize().

Refer to chapter 4.5 for details about ara::core::Initialize().

The signal mask, that defines which Signals are blocked, will be inherited by any further
created thread. It has to be ensured that no additional threads are created before the
signal mask is correctly set. Note that there are classes in the ara::* namespace that
spawn threads immediately upon instantiation. Such classes shall not be instantiated as
static objects to prevent creating new threads before main (i.e., before the signal mask
can be set). For more information which ara::* objects create threads please refer to the
respective technical reference documents of the MICROSAR Adaptive components.
The only exception to this rule is the five Signals SIGABRT, SIGBUS, SIGFPE, SIGILL
and SIGSEGV. They shall not be blocked as these Signals are raised when an error
occurs where there is no reasonable way to continue program execution. According to
the POSIX specification, blocking these Signals would lead to undefined behavior. If one

© Vector Informatik GmbH Version 9.0.0 36

 AdvancedTopics

of these Signals occurs, the default signal handling action, as defined by the underlying
POSIX environment, is performed. It is expected by MICROSAR Adaptive code that the
process is terminated immediately. Note that, depending on the configuration of the
POSIX system, a core dump file may be written to persistent storage. Note also that the
two Signals SIGSTOP and SIGKILL cannot be blocked. For any further information
please see the documentation of the underlying operating system.
To implement the dedicated Signal Handling Thread, it is recommended to use a call to
sigwait within a while-loop. This prevents synchronization problems due to the
asynchronous execution of dedicated signal handler functions. Sigwait has a signal set as
parameter that defines the Signals that it waits for. This signal set must contain at least
SIGTERM, as SIGTERM is sent by the Execution Management Cluster of the Adaptive
Platform (see [1] for information about the MICROSAR Adaptive Execution Management)
to initiate process termination. After receiving a Signal, the signal number shall be
queried, and an appropriate action must be executed. For example, after receiving
SIGTERM, an orderly shutdown of the application must be initiated. Note that all signals
specified in the signal set to wait for with sigwait must be blocked in the calling thread and
all other threads. Otherwise there is a race condition between the default processing and
sigwait. If the signal mask is set correctly at the beginning of the process, as described
above, the signals should be blocked.
The code example below shows how to enable an Adaptive Application to handle Signals
received from platform components or other applications, e.g. from the Execution
Management Cluster of the Adaptive Platform. The example Adaptive Application has two
threads, the main thread and one separate thread for signal handling. The sigwait
function is used to wait for the SIGTERM Signal. After receiving SIGTERM the Adaptive
Application shall be stopped in a proper way. Therefore, the other threads must be
notified. In the example this is realized by setting a global “exit requested” flag
(g_exit_requested).
The main function first calls the Init function. Within Init the function SetSigMask is called
where all Signals except SIGABRT, SIGBUS, SIGFPE, SIGILL and SIGSEGV are
blocked by setting a new signal mask. The signal mask, which is set during the call to
SetSigMask, is inherited by any further created thread. (Therefore, the signal mask
should always be set first in the main function.) After setting the signal mask, a new
thread for signal handling is spawned. The main thread then enters its run phase.
The Signal Handler Thread prepares the signal set that specifies the Signals that are
waited for. In the example only SIGTERM is specified. Subsequently, sigwait is called
with the prepared signal set within a while-loop. The function sigwait suspends execution
of the calling thread until at least one Signal specified in the passed signal set becomes
pending. When such a Signal occurs, the sigwait function returns. Thus, the Signal
Handling Thread wakes up and queries the signal number of the received Signal. If
SIGTERM was received, the Adaptive Application global “exit requested” flag is set to
true, and the Signal Handler Thread terminates. The main thread cyclically checks this
global flag. And as soon as the flag is set to true, it stops its run phase and enters the
shutdown phase. The main thread waits until all other threads are terminated and then
also terminates.
The code example below shows the recommended way to handle Signals. But some
parts can be varied:
> The global “exit requested” flag can be replaced by another synchronization primitive.
For example, this could be a pipe that is opened within Init and closed after receiving
SIGTERM.
> The sigwait call to wait for Signals can also be made within the main thread after
everything necessary has been set up, such as starting worker threads. In this case,
the Main thread becomes the dedicated Signal Handler Thread.
> In addition to SIGTERM the SIGINT Signal can be used to initiate process
termination. It is recommended not to use other Signals.
The sigwait function is not the only way to suspend the execution of a thread until a
Signal occurs but using sigwait is highly recommended for its ease of use.

© Vector Informatik GmbH Version 9.0.0 37

 AdvancedTopics

#include <atomic>
#include <csignal>
#include <iostream>
#include <thread>
#include <vector>

#include <unistd.h>

/* flag to identify whether the application has received a SIGTERM

signal */
volatile std::atomic_bool g_exit_requested{false};
constexpr uint_least8_t kNumOfThreads = 2;
std::vector<std::thread> gThreads; /* stores all thread objects */

void SignalHandlerThread() {
sigset_t signal_set;
int sig = -1;
if (0 != sigemptyset(&signal_set)) { /*empty the set of
signals*/
/* abort application because emptying signal set failed */
ara::core::Abort("Emptying signal set failed.");
}
if (0 != sigaddset(&signal_set, SIGTERM)) { /* add SIGTERM to
signal set */
/* abort application because adding SIGTERM to signal set
failed */
ara::core::Abort("Adding SIGTERM to signal set failed.");
}

/* wait until signal SIGTERM occurs */

while (sig != SIGTERM) {
if (0 != sigwait(&signal_set, &sig) {
/* abort application because of an invalid signal set */
ara::core::Abort("Sigwait() was called with an invalid
signal set.");
}
}
g_exit_requested = true;
}

void SetSigMask() {
bool success{true};
/* Block all signals except SIGABRT, SIGBUS, SIGFPE, SIGILL and
SIGSEGV
* because blocking them will lead to undefined behavior. Their
default
* handling shall not be changed (dependent on underlying POSIX
environment,
* usually process is killed and a dump file is written).
* Signal mask will be inherited by subsequent threads. */
sigset_t signals;
success = success && (0 == sigfillset(&signals));
success = success && (0 == sigdelset(&signals, SIGABRT));
success = success && (0 == sigdelset(&signals, SIGBUS));
success = success && (0 == sigdelset(&signals, SIGFPE));
success = success && (0 == sigdelset(&signals, SIGILL));
success = success && (0 == sigdelset(&signals, SIGSEGV));
success = success && (0 == pthread_sigmask(SIG_SETMASK,

© Vector Informatik GmbH Version 9.0.0 38

 AdvancedTopics

&signals, nullptr));
if (!success) {
/* abort application because preparing or setting new signal
mask failed */
ara::core::Abort("SetSigMask failed.");
}
}

void Init() {
/* initialize signal handling by setting the signal mask */
SetSigMask();

/* reserve space in std::vector */

gThreads.reserve(kNumOfThreads);
/* spawn a new signal handler thread */
gThreads.push_back(std::thread(SignalHandlerThread));
/* may spawn some more threads here */
}

void Shutdown() {
/* do application clean-up in here */
/* wait until other threads have joined */
std::cout << "Waiting for my threads." << std::endl;
for (std::vector<std::thread>::iterator it = gThreads.begin();
it != gThreads.end(); it++) {
it->join();
}
std::cout << "Terminating." << std::endl;
}
int main() {
Init();
while (!g_exit_requested) {
/* do some work here */
}
Shutdown();
return 0;
}

5.2 C++ Exceptions

The MICROSAR Adaptive base software, as far as mandated by the AUTOSAR AP

standard, will not create or handle C++ exceptions, unless stated otherwise, e.g. for:
> ara::core::Result::ValueOrThrow
> ara::core::Future::get,
or
> ara::core::ErrorDomain::ThrowAsException,
and its overrides in child classes.
While applications based on MICROSAR Adaptive may use C++ exceptions for their own
purposes, their use in context of the MICROSAR API is not supported.
When exception support is disabled (e.g. with -fno-exceptions), apart from the above
mentioned functions, all functions that raise an exception will immediately terminate the
process unsuccessfully instead of raising an exception.

Vector strongly recommends disabling the support of C++ exceptions (-fno-exceptions).

© Vector Informatik GmbH Version 9.0.0 39

 AdvancedTopics

Further information > Compilation Without Exception Support

> Exeption Propagation

5.2.1 Compilation Without Exception Support

Due to lack of tool support, the basic exception safety guarantee cannot be given for all
possible execution paths. Therefore, Vector strongly recommends to deactivate C++
exceptions (e.g. with -fno-exceptions) and to use libraries (i.e. the standard C++
library) that replace exceptions with std::terminate or adequate result types like
ara::core::Result.

If exceptions are disabled (-fno-exceptions), it is assumed that the process is

terminated immediately in case of an exception thrown by the C++ standard library. It is
also assumed that the macro __EXCEPTIONS is not defined.

5.2.2 Exeption Propagation

If exceptions are enabled, a user shall consider the propagation of exceptions by
MICROSAR Adaptive base software as unspecified.
> Exceptions thrown by third party libraries, for example the C++ standard library, will
cause an abnormal process termination, if an API function is annotated with
noexcept.
> API functions not annotated with noexcept may propagate exceptions thrown by
third party libraries. However, depending on arguments and internal call propagation,
they may also terminate the process abnormally.
> Exceptions thrown by application callbacks or fed into MICROSAR Adaptive base
software via dependency injection including virtual inheritance and template
parameters will cause undefined behavior.
> Data types in the ara::core namespace, as far as not extended by the AUTOSAR
AP standard to provide additional functionality compared to their C++ standard library
equivalents, are currently represented by type aliases of the C++ standard types.
This implies their C++ standard exception throwing behavior. Therefore these types
shall be used only in a way that ensures that no exceptions are thrown.

The user of MICROSAR Adaptive shall take additional measures to mitigate the
resulting risk of resource leaks and undefined behavior, such as long-term integration
tests while monitoring resource consumption and/or using tools for resource leak
detection.

5.3 C++ Error Handling

The basic error handling principles are that no failure condition leads to undefined
behavior and any failure shall be detected as early as possible. In addition, side effects
caused by failed operations must be avoided.
In consequence, the following failure categories and reactions are distinguished see [9].

© Vector Informatik GmbH Version 9.0.0 40

 AdvancedTopics

Category Severity Situation and Reaction

Violation Not recoverable Failed pre- or post-condition which leads to an
abnormal termination of the process. Supports
debugging with generated core dump. Refer to
chapter 4.9 for details.
Corruption Not recoverable Runtime failure in the system environment, e.g.,
missing configuration file or inadequate privileges,
which causes an unsuccessful normal process
termination. Exit code yields information about what
action needs to be taken to fix environment; see
reference box below this table.
Error Recoverable Request not fulfilled, but execution can proceed.
Return error within Result type, see following
subsections for details.

For possible exit codes, please refer to the subsection Exit Codes of the section Error
Handling in the corresponding Technical Reference document.

Further information > Result Type

> Error Propagation

5.3.1 Result Type

As written in chapter C++ Exceptions, the use of exceptions in context of the MICROSAR
Adaptive API is not supported. Instead, the ara::core::Result type is used to
indicate success or non-success of a function.
Therefore, the returned Result has to be checked for success or error. In the latter case
the Result contains an object of type ara::core::ErrorCode, which provides error
context information (i.e. the error domain), the error code, and optional support data.
However, an error is only returned if the given failure situation can neither be treated
locally by applying an appropriate recovery strategy nor finally classified as non-
recoverable.

5.3.2 Error Propagation

Error propagation means that an error is reported to the caller until the first caller is
reached with an appropriate error handling strategy in place or with enough context
information to eventually decide that the error is to be considered a corruption or post-
condition violation.

© Vector Informatik GmbH Version 9.0.0 41

 AdvancedTopics

Different API may define specific error domains which come with their own set of error
codes. Beyond that the ara::core::ErrorDomain::SupportDataType might
transport additional information like an error subcode and/or a string literal holding
location information where the problem was detected first.

5.4 Using Symbolic Links to Start Non-Adaptive Application

Outside the Base Directory

The Execution Manager requires that all application binaries are located within the
application base directory. This constraint can be circumvented by using symbolic links
that point from the application directory to the actual application binary, e. g. to /usr/
bin/strace. The path to the application base directory can be provided via command
line argument at the startup of Execution Manager.
> > ln --symbolic /usr/bin/strace <APPLICATION_BASE_DIRECTORY>/
app_A/bin/app_A

With introduction of chapter Configurable Executable Path for Applications, the usage of
symbolic links is no longer needed.

Figure 13: Example Showing Use Of Symbolic Links

© Vector Informatik GmbH Version 9.0.0 42

 AdvancedTopics

5.5 Configurable Executable Path for Applications

By default, Execution Manager starts executables from the location <Application

Base Directory>/<Application Directory>/bin. Being said that it is possible
to explicitly specify the executable’s location using ExecutableLocation model
extension.

<PROCESS>
<SHORT-NAME>exampleProc</SHORT-NAME>
<ADMIN-DATA>
<SDGS>
<SDG GID="DvMex:ExecutableLocation">
<SD GID="executableLocation">/usr/bin/top</SD>
</SDG>
</SDGS>
</ADMIN-DATA>
<!-- Other elements omitted from this example. -->
</PROCESS>

5.6 Integration Non-AUTOSAR Applications

Adaptive AUTOSAR has some guidelines/constraints for application development which

have to be considered by applications running on the Adaptive Platform (see Reference
Documents). Applications which are not developed for AUTOSAR Adaptive do not follow
these guidelines.
This chapter describes how to integrate such applications with MICROSAR Adaptive

Further information > Starting Non-AUTOSAR Applications

> Companion Process
> Using Diagnostic Tools or Debuggers

5.6.1 Starting Non-AUTOSAR Applications

AUTOSAR Adaptive guidelines say Adaptive Applications shall report their Execution
State (called Application State in previous AUTOSAR releases) during startup (see [6],
[7]). The Execution Manager tracks the Execution States of all Processes and enables to
define dependencies among Processes. The Processes are started in an order that
meets the defined dependencies. Regular Unix tools which are common in POSIX
environments (e.g. ssh server) do not report their Execution State.
AUTOSAR 19-11 introduced Non-Reporting Processes to support the usage of such
executables. Non-Reporting Process behavior can be configured in Execution Manager
using the Executable.reportingBehaviorExecutable attribute.

© Vector Informatik GmbH Version 9.0.0 43

 AdvancedTopics

<EXECUTABLE>
<SHORT-NAME>app_A_exe</SHORT-NAME>
<CATEGORY>APPLICATION_LEVEL</CATEGORY>
<REPORTING-BEHAVIOR>DOES-NOT-REPORT-EXECUTION-STATE</
REPORTING-BEHAVIOR>
</EXECUTABLE>

After a Non-Adaptive Application is started by the Execution Manager its state is Running
without knowing when it will be in a ready state and e. g. able to accept connection.
Dependencies on Non-Reporting Processes can lead to timing issues and are not
recommended.
Reporting Processes should always be preferred and are the default in Adaptive
AUTOSAR.

5.6.2 Companion Process

Execution Manager changes the Execution State of Non-Reporting Processes
automatically to Running after creation, i.e. Execution Manager considers the Process to
be Running, even if the OS did not schedule it yet. This might lead to following
unexpected behavior:
> During Function Group state transition, transition is considered to be completed but
Non-Reporting Process never has been scheduled yet.

© Vector Informatik GmbH Version 9.0.0 44

 AdvancedTopics

> Together with Execution Dependencies: If a Process B is configured to have a

Running Execution Dependency to Non-Reporting Process A, Process B is started
immediately after Process A has been started, even if Process A never has been
scheduled and does not provide its service yet (e.g. handling ssh connections). The
very next illustration shows the described issue.

Figure 14: Non-Reporting Processes

This scenario can be resolved by introducing an additional process called Companion

Process. The Companion Process is a regular Reporting Process which is started by
Execution Manager together with the Non-Reporting Process representing the state of
the Non-Reporting Process (see Figure 6 2). The Companion Process monitors the

© Vector Informatik GmbH Version 9.0.0 45

 AdvancedTopics

availability of a service that is provided by the Non-Reporting Process and reports the
Execution State Running when the service is actually available. The implementation of
the monitoring is user defined and differs for the individual services.

Figure 15: Report Execution State Via Companion Process

5.6.3 Using Diagnostic Tools or Debuggers

Some diagnostic or debugging tools which are used to analyze an executable, are
executables themselves (e.g. strace or gdbserver). Integrating e.g. /usr/bin/strace
into an MSRA StartupConfig requires following steps:
1. Configure the path to diagnostic/debugging tool using ExecutableLocation model
extension as described in chapter Configurable Executable Path for Applications.
Now Execution Manager will start /usr/bin/strace instead of the application
app_A.
2. Modify the ARXML file and add the necessary command line arguments for the
diagnostic or debugging tool (e.g. for strace add the path to the executable to be
started and its parameters).
<PROCESS-ARGUMENTS>
<PROCESS-ARGUMENT>
<ARGUMENT><absolute_path>/app_A</ARGUMENT>
</PROCESS-ARGUMENT>
</PROCESS-ARGUMENTS>
1. ApplicationClient process is expected to report its PID to Execution Manager and a
check is being made to ensure that this ApplicationClient is reporting from the correct
process. In case of using debugging tool parent process, ApplicationClient will report
PID of child process, which Execution Manager is not aware of. This requires
ApplicationClient Identity Verification to be disabled.
To disable this verification, set Tool Process’s model extension
peerIdentificationDisabled to TRUE.
<SHORT-NAME>wrapper_test_process</SHORT-NAME>
<ADMIN-DATA>
<SDGS>

© Vector Informatik GmbH Version 9.0.0 46

 AdvancedTopics

<SDG GID="DvMex:PeerIdentificationDisabled">
<SD GID="peerIdentificationDisabled">TRUE </SD>
</SDG>
</SDGS>
</ADMIN-DATA>
1. Optional: Debugging tools will likely increase the startup time of the process,
therefore you might have to increase the timeout values within the configuration of
the process you want to debug, otherwise Execution Manager's timeout violation
handling will be triggered. The example below defines 20 seconds for the enter and
exit timeout.
<TIMEOUT>
<ENTER-TIMEOUT-VALUE>20</ENTER-TIMEOUT-VALUE>
<EXIT-TIMEOUT-VALUE>20</EXIT-TIMEOUT-VALUE>
</TIMEOUT>
With these steps the Adaptive Application is started by the diagnostic/debugging tool and
in case of strace system calls are printed to the terminal.

5.7 Initialization and Shutdown

This section describes the central (pre-)initialization and shutdown of the MICROSAR
Adaptive (Adaptive Runtime for Applications) framework.
In a nutshell
> The MICROSAR Adaptive API must not be used before
ara::core::Initialize() returned.
> The MICROSAR Adaptive API must not be used after
ara::core::Deinitialize() returned.
> The functions are available via ara/core/initialization.h.
> All calls to ara::core::Initialize() and ara::core::Deinitialize()
have to be done from the main thread when static memory initialization has
completed and before the statically initialized data is destructed.
> ara::core::Initialize() and ara::core::Deinitialize() are generated
for Adaptive Applications dependent to the model (ARXML) and the used
functionality.
> The MICROSAR Adaptive API must not be used while
ara::core::Deinitialize() has been called and is processing.

All threads should be joined before ara::core::Deinitialize() is called.

This example shows a possible use of ara::core::Initialize() and ara::core::Deinitialize():

ara::core::Deinitialize():
// ...
int main() {
// static variables/objects initialized
int result_code {-1};

// setup signal handling, ...

ara::core::Result<void> init_result
{ara::core::Initialize()};

© Vector Informatik GmbH Version 9.0.0 47

 AdvancedTopics

// init_result.HasValue() != true -> ARA cannot be used

// init_result.HasValue() == true -> ARA can be used
if(init_result.HasValue()) {
result_code = 0;
// … business logic …

// shutdown (all threads accessing ARA APIs joined!)

ara::core::Result<void> deinit_result
{ara::core::Deinitialize()};
deinit_result.InspectError([](ara::core::ErrorCode const&
error) {
std::cerr << "ara::core::Deinitialize() failed!";
std::cerr << "Result contains: " << error.Message() << ", "
<<
error.UserMessage();
});
}
// else (ara::core::Initialize() failed): report error / adjust
result_code

return result_code;
} // static variables/objects will be deinitialized
The function ara::core::Initialize() coordinates the start-up of the MICROSAR
Adaptive framework. This includes e.g. the initialization of MICROSAR Adaptive
framework-specific data structures and spanning of background threads. Prior to this call,
no interaction with the ARA is allowed. Exceptions are documented. Prerequisite for this
call is that static memory initialization is completed (e.g. inside of function main()).
The function ara::core::Deinitialize() coordinates the shutdown of the
MICROSAR Adaptive framework. For a proper shutdown, it is expected that
ara::core::Deinitialize() is called before the statically initialized data is
destructed.
An error returned by ara::core::Deinitialize() is the only way for MICROSAR
Adaptive to report an error that is guaranteed to be available, e.g., in case ara::log has
already been deinitialized. The user is not expected to be able to recover from such an
error.
A call to an MICROSAR Adaptive API that depends on initialization is treated as a
violation, if the runtime is currently not initialized (i.e. before ara::core::Initialize() has
returned with success, or after ara::core::Deinitialize() was called).
For more details see [4].

The function ara::core::Initialize() does not setup signal handling. Signals

shall be blocked at the very beginning of a new process, before
ara::core::Initialize() is called.

Repeated initialization and deinitialization, i.e., calling ara::core::Initialize(),

ara::core::Deinitialize(), ara::core::Initialize() is not supported and
may lead to undefined behavior. After ara::core::Deinitialize() is called, the
process must be terminated and restarted before ara::core::Initialize() can
be called again.

© Vector Informatik GmbH Version 9.0.0 48

 AdvancedTopics

5.8 Orderly Shutdown and Restart of an MICROSAR Adaptive

ECU

This chapter presents the customer with existing possibilities to orderly shutdown AMSR
stack and then optionally to restart the stack or the whole MICROSAR Adaptive ECU.
Orderly Shutdown in contrast to an abrupt termination allows to switch off the MICROSAR
Adaptive stack while maintaining a defined state throughout the whole procedure. Being
in a well-defined Shutdown state is a necessary condition for the next smooth and
successful start of the MICROSAR Adaptive stack.

Further information > Manual Orderly Shutdown and Restart

> Automated Orderly Shutdown and Restart Triggered by State Manager
> Automated Orderly Shutdown and Restart Triggered by SIGTERM
> Rapid Shutdown and Restart Triggered by State Manager

5.8.1 Manual Orderly Shutdown and Restart

This section describes the necessary configuration and steps to shut down or restart an
Adaptive ECU. Optionally, it is also possible to shut down the Adaptive part of an ECU
only.
For further details on the shutdown and restart process, please refer to see [6] and the
TPS Manifest specification.
For this scenario we expect the following configuration:
> A State Manager process is assigned to all machine states (i.e. it is assigned to all
valid states of the function group MachineFG). This State Manager is controlling all
the function groups including the machine state via the Execution Manager’s
StateClient API.
> A dedicated shutdown application process is assigned to the machine states
Shutdown and Restart. Once this process is started, it initiates the shutdown or
restart procedure by accessing OS-specific interfaces (e.g. calling reboot() on
Linux).
With this preparation a shutdown procedure essentially looks like this:
> Set all existing Function Group states to Off except for the MachineFG Function
Group. Since no process may reference state Off, this terminates all running
processes except for the Execution Management and the processes which are
assigned to MachineFG Function Group.
> Setting the machine state to Shutdown or Restart activates the Shutdown
Application process.

© Vector Informatik GmbH Version 9.0.0 49

 AdvancedTopics

> The remaining processes of Execution Management and State Management are
terminated by the OS during shutdown or restart. If the intended behavior is to shut
down the Adaptive instance without shutting down the ECU, the shutdown application
must instead send SIGKILL to these processes and terminate afterwards.

Figure 16: Restart/Shutdown Procedure

5.8.2 Automated Orderly Shutdown and Restart Triggered by State

Manager
This section describes the necessary steps to shut down or restart AMSR stack using
dedicated service of Execution Management. In general, this service takes over the task
to terminate all running AMSR processes including Execution Manager itself, relieving the
customer from the duty to manually accomplish this procedure.
Once called, this service automatically brings all Function Groups to state Off. Then
Execution Manager process terminates.
The configuration becomes somewhat simpler than in the manual scenario:
> A State Manager process still should be assigned to all the states of MachineFG to
be always able to issue the Shutdown request.
> There is no more need of the dedicated shutdown application since Execution
Manager shuts down State Manager process and itself.
AMSR shutdown with the assistance from Execution Manager looks like following:
> If there are no dependencies between different Function Groups, State Management
can directly issue the Shutdown request using the StateClient API. Otherwise, State
Management should bring first all dependent Function Groups to state Off in the
correct order, since Execution Management is not aware about inter-Function Group
dependencies.
> Once Execution Manager receives the Shutdown request it autonomously brings all
Function Groups to state Off and then exits. Any requests from the outside that might
anyhow affect Function Group are ignored during the entire period.

© Vector Informatik GmbH Version 9.0.0 50

 AdvancedTopics

> Upon Execution Manager termination OS informs its parent process, so it can take
actions, be it starting AMSR stack anew or switching off the rest of the ECU.

Automated Restart/
Shutdown procedure of
an Adaptive ECU

Figure 17: Automated Orderly Shutdown and Restart Triggered by State Manager

Automated Shutdown becomes particularly useful if there is a need to switch off or restart
AMSR stack without shutting down the Operating System or the entire ECU. Examples of
such scenarios include:
> Restart after AMSR stack update.
> Restart due to some problem occurred in AMSR stack. It is anticipated in this case
that some Function Groups won’t switch to state Off smoothly. Use of Automated
Shutdown that independently handles such irregularities, is likely to reduce State
Management error handling complexity.

5.8.3 Automated Orderly Shutdown and Restart Triggered by SIGTERM

Automated Shutdown can be triggered by sending SIGTERM to the Execution Manager
process.
From the moment Execution Manager receives the SIGTERM it takes the same course of
actions as in the case of the shutdown triggered by State Manager.

5.8.4 Rapid Shutdown and Restart Triggered by State Manager

Rapid Shutdown can be seen as a time optimization of Automated Orderly Shutdown.
This means that they share the same configuration, and the only difference is the
triggering command and the execution details that are outlined below.
> Rapid Shutdown can be triggered by issuing RapidShutdown request to the
Execution Manager process using StateClient API.
> Once Execution Manager receives the RapidShutdown request it initiates transition of
all Function Groups to state Off at the same time sending SIGKILL to all its child
processes – the measure that accelerates the state transition.

© Vector Informatik GmbH Version 9.0.0 51

 AdvancedTopics

From this moment Rapid Shutdown progresses in the same manner as in the case of
Automated Orderly Shutdown.

Figure 18: Rapid Shutdown And Restart Triggered by State Manager

It’s important to note that the applications are killed in the most plain and unconditional
manner: there is not any particular order in which SIGKILL is sent; Execution
Dependencies and Exit Timeouts are not respected as well.
Rapid Shutdown is most appropriate for the situations when MICROSAR Adaptive stack
should be brought down as quickly as possible and the inter-dependencies between the
Function Groups or processes are not a concern.

5.9 Disable Execution State Reporting

Application state reporting is an intrinsic feature of the Execution Management that

requires applications to report their state back to the Execution Manager. This feature can
be disabled for the base software daemons (SomeIpDaemon, LogDaemon, etc.) by
setting the respective compile time switch to OFF. Depending on the component, this is
either ENABLE_EXEC_MANAGER or ENABLE_EXEC_MANAGER_SUPPORT.

For details, please refer to the Integration chapter of the corresponding Technical
Reference document.

5.10 Additional Restrictions and Exceptions

This chapter describes additional restrictions and expectations regarding the use of
iterators, C-style strings and ranges when using MICROSAR Adaptive.

Further information > Iterators

© Vector Informatik GmbH Version 9.0.0 52

 AdvancedTopics

> C-Style Strings

> Ranges

5.10.1 Iterators
> The ISO C++ definition of a valid range ([§24.2.1.7] see [3]) is insufficient to prevent
out-of-bounds access.
> Therefore, make sure that a pair of iterators, which are supposed to define a valid
range, are created from the same object.
> In addition, make sure that no type defines its iterators in a way, which would cause
out-of-bounds access.

5.10.2 C-Style Strings

> Make sure that C-style strings (§17.5.2.1.4.1 see [3]) are valid pointers, i.e. they are
null-terminated.
> Especially after using range limited operations like strncpy, it should be ensured the
null character is present.

5.10.3 Ranges
In APIs which accept multiple ranges in form of iterator or pointer pairs, make sure that
the ranges do not overlap.

5.11 Abnormal Terminations

This chapter describes the behavior of MICROSAR Adaptive in case of unexpected

errors and abnormal terminations of processes, and different options to handle these. It
outlines hooks for a user provided failure handler application. This handler is supposed to
trigger recovery actions when unexpected errors of any kind have put the stack into a
potentially inoperable state. Requirements for user applications need to meet to integrate
with this mechanism are specified.
To avoid undefined stack behavior, it is essential to propagate unexpected errors events.
Guidelines in this chapter cover components included the MICROSAR Adaptive delivery,
as well as user provided modules called by these.

Further information > Detection and Notification

> Recovery
> Application Components and Daemons
> Library Components
> Customer Provided Modules

5.11.1 Detection and Notification

Process terminations in the MICROSAR Adaptive stack, are detected by parent
processes, using the standard POSIX mechanism (see [2]). Parent processes can wait
for one or more child processes and retrieve their exit status. A normal termination
means, that the child process reached the main function return statement or invoked the

© Vector Informatik GmbH Version 9.0.0 53

 AdvancedTopics

exit system call. Abnormal terminations in a POSIX system (see [2]), for example process
aborts triggered by unhandled exceptions, illegal arithmetic operations or machine
statements, null pointer dereferences, are raised using signals.
The operating system kernel promotes both information to the calling parent process in
the exit status word.

Process Termination
Data Flow in a POSIX
System

In the figure above the green arrows represent normal termination while red arrows are
examples for abnormal terminations.

Further information > Execution Manager

> Other Parent Processes

5.11.1.1 Execution Manager

The execution manager provides an interface [1] to retrieve
> application short name path,
> status code as returned by the POSIX [2] system call wait,

© Vector Informatik GmbH Version 9.0.0 54

 AdvancedTopics

of all child process terminations. This includes both normal and abnormal terminations. It
allows a user provided error handler application to extract the termination conditions
using POSIX defined macros, e.g. WIFEXITED, WEXITSTATUS, WIFSIGNALED,
WTERMSIG.

Termination Notification
Performed by the
Execution Manager

In the figure above processes with blue boundaries are examples of user provided
applications. Processes with red boundaries are examples of MICROSAR Adaptive base
software components.

5.11.1.2 Other Parent Processes

When other facilities than the execution manager are used to invoke MICROSAR
Adaptive processes, the POSIX [2] mechanism to detect abnormal child process
termination applies.

Further information > Examples

5.11.1.2.1 Examples
In case of systemd using on-failure or on-abnormal as arguments of restart or
watchdog options include abnormal terminations.
When starting applications from shell or shell scripts using bash, ksh, or zsh, command
lists with elements linked with && and || operators will detect both non-zero return values
and abnormal terminations.

5.11.2 Recovery
Recovery from unexpected errors must be handled by a user provided failure handling
application.
Vector recommends resetting the ECU or the ECU partition, respectively, in response to
abnormal terminations. Unexpected errors usually indicate that an application could not
return to an operable state for unknown reasons. It cannot be guaranteed, that restarting
only specific processes would return the entire stack into an operational state.

5.11.3 Application Components and Daemons

Encountering unexpected errors detected by the C++ [3] runtime environment, an
application shall terminate with the POSIX [2] defined signal SIGARBT.

© Vector Informatik GmbH Version 9.0.0 55

 AdvancedTopics

Unrecoverable error conditions raised directly by the operating system kernel, not
involving the C++ runtime environment, will be reported using their corresponding signals,
e.g. SIGSEGV, SIGFPE, SIGILL.

5.11.4 Library Components

API function calls may respond to unexpected errors in one of two ways:
> Functions not labelled as noexcept will propagate unexpected exceptions to the
caller. Unless documented otherwise in the component’s Technical Reference, it is
not safe to assume the application can be resumed after encountering unexpected
errors. In such cases the caller shall propagate the exception in a way that ultimately
aborts the process, to allow detection of the unrecoverable failure by detecting the
abort signal.
> Functions with a noexcept specification will invoke the current process termination
handler, which by default will terminate the process with the POSIX defined signal
SIGARBT. Optionally, a user application may alter this behavior by registering a
custom termination handler using std::set_terminate. That handler, however, is
required to abort execution and allow detection of the unrecoverable failure. It is not
possible to resume execution from a termination handler.

5.11.5 Customer Provided Modules

Code provided by the user and called by MICROSAR Adaptive components shall
propagate unexpected errors and allow abnormal termination and notification of the
execution management system in one of two ways:
> Throw an exception not handled by the calling component. Please check the
corresponding component’s Technical Reference, whether any exceptions are
expected and whether the specified handling would be appropriate.
> Abort the process implicitly or explicitly with the POSIX defined signal SIGARBT, e.g.
by invoking std::terminate or abort.
Errors putting the application in an unrecoverable state shall not be suppressed. They
shall also not result in a normal termination using exit.

5.12 Support of Multiple Adaptive AUTOSAR API Releases

AUTOSAR is publishing new API definitions for functional clusters with every AUTOSAR
AP release. These are neither separated into release-specific namespaces, nor required
to retain backward compatibility.
In the MICROSAR Adaptive implementation, public APIs are based on a specific release,
and are extended on demand according to AUTOSAR updates, if compatibility can be
retained. Once the standard definition changes in an incompatible way, MICROSAR
Adaptive must separate implementations and provide a user choice, which AUTOSAR AP
to use in functional cluster standard namespaces.

Please refer to the section Supported AUTOSAP API Releases in the individual
technical references of MICROSAR Adaptive API components, if available.

Further information > C++ Namespace Separation Pattern

> Build Time Selection of Standard Namespace Mappings

© Vector Informatik GmbH Version 9.0.0 56

 AdvancedTopics

5.12.1 C++ Namespace Separation Pattern

Provisioning and selection are done in two steps for each affected functional cluster. The
distinct API definitions are provided in product-specific namespaces denoting the target
AUTOSAR AP release. Then, include files in release-specific include file paths are used
to map a selected release to the unique standard namespace.

Let YY-MM be an AUTOSAR AP release, such as 19-03 of 20-11. Let fc be a functional

cluster, such as com, core, log. Let Sample be an API, such as InstanceIdentifier or
Result.
Standard Namespace Mapping
include_rYY_MM/ara/fc/sample.h
#include "amsr/fc/rYY_MM/sample.h"
namespace ara {
namespace fc {
using Sample =
amsr::fc::rYY_MM::Sample;
} // namespace fc
} // namespace ara
Versioned Implementation
include/amsr/fc/rYY_MM/sample.h
namespace amsr {
namespace fc {
namespace rYY_MM {
class Sample {
// …
};
} // namespace rYY_MM
} // namespace fc
} // namespace amsr

5.12.2 Build Time Selection of Standard Namespace Mappings

The scope of standard ara::* namespace mapping is the executable at build time.
Different executables can use different releases, but within a single executable, all API
invocations must agree on one version per functional cluster.
The configuration is primarily done in ADMIN_DATA elements in the ARXML model.

© Vector Informatik GmbH Version 9.0.0 57

 AdvancedTopics

ARXML snippet selecting the ara::com API from AUTOSAR AP release 20-11:
<EXECUTABLE>
<ADMIN-DATA>
<SDGS>
<SDG GID="DvMex:BswVersionedApi">
<SD GID="amsrAraComApi">r20_11</SD>
</SDG>
</SDGS>
</ADMIN-DATA>

The corresponding model extension schema read by the DaVinci Developer Adaptive for
presenting and validating selections is provided in the ApplicationBase component in
amsr-vector-fs-applicationbase/mex/MexDefBswVersionedApi.arxml.

For the integration of versioned API components into an application CMake build
configuration refer to the appropriate technical references in your TechnicalReference
folder of your delivery
Please refer to chapter Module|Find Modules and the description of Function
dvacfg_file_gen in the TechnicalReference_TACO.pdf.

Each MICROSAR Adaptive API component providing selectable versions will also
define a default version used in absence of an explicit user selection. Despite this,
CMake code in the application build configuration still needs to be prepared to make
use of that.

5.13 Support of Multi-Target

The AUTOSAR configuration model distinguishes between design and deployment

information. When deploying a modelled executable to multiple machines, design
information usually stays the same while deployment information may vary between
them. In the following these machines are also referred to as targets.

Figure 19: Support of Multi-Target

© Vector Informatik GmbH Version 9.0.0 58

 AdvancedTopics

In MICROSAR Adaptive, design information is embedded in the generated code and

compiled as part of the executables. Deployment information is considered runtime-
configurable and provided through JSON configuration files. However, there are some
exceptions to this rule where generated code also contains deployment information.
A source or header file is considered target-dependent if its generation is based on
deployment information or if a target-dependent file is part of its include hierarchy. All
remaining generated source and header files are considered target-independent.
Configuration files are always considered target-dependent due to the contained
deployment information.
Classification of target MICROSAR Adaptive supports classification of target-dependent and target-independent
dependency files through the boolean generator argument enableMultiTarget. When set to true,
source and header files are generated into separate directories according to their
classification. If DaVinci Configurator Adaptive Command Line Tool is used to run the
generators, then the argument can either be set individually for each generator or for all
of them at once.

--genArgUniversal "enableMultiTarget=true"

A separation into target-dependent and target-independent directories is only needed for

build systems that perform caching on folder level. It allows these build systems to be
configured in such a way that the target-independent files are only compiled once for all
machines. The target-dependent files need to be compiled separately for each of them.
When the deployment for a machine changes, only these files need to be recompiled,
which allows the overall rebuild time to improve.

Initial built time is not improved. Target-independent object files need to be cached for
subsequent linking of executables.

The achievable improvement in the overall rebuild time depends on the configured
caching mechanism in the build system.

When the file classification is enabled, following compile dependencies should be applied
to prevent a recompilation of application code upon deployment changes:

Multiple Processes per Executable in a single ARXML model are still not supported
(see Multiple Processes per Executable Not Supported). To handle the deployment
configuration of multiple machines, these specific model parts must be split to different
model files and used as input for different generator runs.

Multi-Target is only supported on user applications. Generated code for daemon

applications is not separated into different directories, even when enableMultiTarget is
set to true for these generators.

© Vector Informatik GmbH Version 9.0.0 59

 AdvancedTopics

Generation of non- MICROSAR Adaptive supports generation of non-deployed services through the boolean
deployed services generator argument generateNonDeployedServices. A service is considered non-
deployed if the configuration model only contains design information for that service. If
DaVinci Configurator Adaptive Command Line Tool is used to run the generators, then
the argument can either be set individually for each generator or for all of them at once.

--genArgUniversal "generateNonDeployedServices=true"

When set to true, design information of non-deployed services additionally is generated

as part of the target-independent code. This allows not only changing configuration of
existing deployed service instances, but also adding and deleting instances without
having to recompile the target-independent code again.

For more information, please refer to the technical references for the respective models.

Generation of non-deployed services has a negative impact on the initial build time due
to the compilation of additional files.

5.14 Source Code of Lower Quality Grade

A software component may contain parts of source code of lower quality than originally
specified in the component scope.
These parts are disabled by default but can be enabled if necessary.
The reason that a component may contain low lower graded source code is, for example,
that new developed code should be made available for beta testing or to provide an ASIL
component with additional functionality when used in a QM context.
However, it is essential that beta code does not enter production and that QM code is
never used in an ASIL context.
Therefore, these pieces of code must be explicitly activated via configuration.
The configuration is not done per feature, but at the application/executable level, usually
via the ARXML model, i.e. H. when Beta is enabled for a component, all included beta
code can be used.

For details on how to enable the downgraded source code of a specific component, see
the component's corresponding BETA ESCAN and Technical Reference.

When enabled, the status information is passed to the compiler via the build system as a
flag: AMSR_LG_BETA_ENABLED and/or AMSR_LG_QM_ENABLED.

Attempting to access the lower quality code, even if it is not enabled, will result in
deprecation warnings and/or unresolved symbols in the linking phase.

© Vector Informatik GmbH Version 9.0.0 60

 Additional Information

6 Additional Information

Further information > Cheat Sheets

> Service Oriented - a Flexible Communication Concept
> Glossary and Abbreviations
> Reference Documents
> Reference Documents

6.1 Cheat Sheets

Cheat Sheets Cheat Sheets

A cheat sheet guides you through an application development process. Depending on the
cheat sheets, the necessary tool can be started automatically for you.
There are many cheat sheets in the DaVinci Developer Adaptive with step-by-step
guidelines to help you to create your adaptive application.

Find the Cheat Sheets in the DaVinci Adaptive Tool Suite via: Help|Cheat Sheets…

© Vector Informatik GmbH Version 9.0.0 61

 Additional Information

6.2 Service Oriented - a Flexible Communication Concept

To understand the concept behind Adaptive Platform, there is a few information

prerequisites to know, that strongly differs from the classical concept used in the
automotive environment until now. This is the service oriented data transmission.
Some/IP – Scalable Some/IP is short for Scalable Service-Oriented Middleware over IP and brings a new
Service-Oriented service-oriented philosophy for data transmission into the vehicle as classic bus systems
Middleware over IP like CAN, LIN and FlexRay use signal-oriented data transmission.

Classic signal-oriented Recap Signal-Oriented Data Transmission

data transmission
With signal-oriented data transmission, information is sent when the transmitter sees a
need, for example, when there are updates or changes in values. This is regardless of
whether this data is currently required by a receiver in the network and so these data
transmissions can burden a network and all connected nodes.
Furthermore, most information is broadcasted in the network, i.e., everyone will receive
the information and has to figure out, whether the information is relevant or not.

Service-oriented data Service-Oriented Data Transmission

transmission
The situation is different with service-oriented data transmission. Here a sender only
transmits data when at least one receiver in the network needs it. The advantage of this
procedure is that the network and all connected nodes are not burdened by unnecessary
data. And a sender transmits data only to a recipient which has explicitly registered for
this data.
Service-oriented data transmission therefore requires that a server is somehow informed
about which receivers needs which data.
A client has the possibility to subscribe to the content of a service on the server. If an
event occurs, it then receives the updated data from the server. A content of a service
can be subscribed to by several clients simultaneously. Subscribing to a content is done
using the SOME/IP Service Discovery (Some/IP-SD)
Calling methods - Another possibility for data exchange is that information can be provided by calling a
Remote procedure call method (so-called remote procedure call). With this a function on the server side is
started by the client.
Some/IP Daemon The Some/IP Daemon is a central communication unit over which all communication
within a machine takes place (if not direct inter process communication - IPC is used).
Using the Service Discovery, the Daemon manages all services that are provided by the
system.

Every machine has one Some/IP Daemon or better said, every instance of AUTOSAR
Adaptive software has one Some/IP Daemon. An instance can e.g. also be a partition
on a hypervisor.

What is a Daemon? Linux-familiar developers can skip this explanation.

A Daemon is a Linux or unix program that runs in the background. Usually, their names
end with a d, e.g. Some/IPd. Daemons are often started at boot time.

Service Discovery To make sure that a client knows which services are currently available, Some/IP-SD
(Service Discovery) provides two mechanisms that allow the dynamic discovery of
services.
> An Offer Service enables the server to offer all services it offers in the Network.

© Vector Informatik GmbH Version 9.0.0 62

 Additional Information

> The Find Services allows the Clients to ask for available service instead.

If you are familiar with AUTOSAR Classic, knowing and understanding of the signal-
based data transmission approach is key for understanding a main part of the
AUTOSAR Adaptive concept and key for understanding the following content.

6.3 Glossary and Abbreviations

Abbreviation Description
AA Adaptive Application
API Application Programming Interface
ARA AUTOSAR Runtime for Adaptive
Applications
ARXML AUTOSAR XML
AUTOSAR Automotive Open System Architecture
BSW Basis Software
CPU Central Processing Unit
DCM Diagnostic Communication Manager
DEM Diagnostic Event Manager
DET Development Error Tracer
DID Data Identifier
DLT Diagnostic Log and Trace
DM Diagnostic Manager
DTC Diagnostic Trouble Code
ECU Electronic Control Unit
GB Giga Byte
GHz Giga Hertz
ICAS In Car Application Server
IP Internet Protocol
IPC Inter Process Communication
MB Mega Byte
MHz Mega Hertz
NRC Negative Response Code
OEM Original Equipment Manufacturer
OS Operating System
POSIX Portable Operating System Interface
PSE POSIX System Environment Profile

© Vector Informatik GmbH Version 9.0.0 63

 Additional Information

Abbreviation Description
REST Representational State Transfer
RTE Run Time Environment (Classic
AUTOSAR context)
SOME/IP Scalable service-Oriented MiddlewarE
over IP
SRS Software Requirement Specification
SWC Software Component
SWS Software Specification
TLV Tag-Length-Value
UDS Unified Diagnostic Services

6.4 Reference Documents

The following table lists the documents that are referenced within this User Manual.

No. Source Titel Version

[1] Vector Technical Reference Execution Manager See delivery
[2] IEEE and The POSIX. 1-2017 2018
Open Group
[3] ISO ISO/IEC 14882: Information technology – 2014
Programming languages – C++
[4] Vector Technical Reference Application Base See delivery
[5] AUTOSAR AUTOSAR CPP 14 guidelines R17.10
[6] AUTOSAR Specification of Execution Management - -
Document ID 721:
AUTOSAR_SWS_ExecutionManagement
[7] AUTOSAR Guidelines for using Adaptive Platform -
interfaces
[8] Vector Technical Reference Platform Health See delivery
Manager
[9] AUTOSAR Specification of Adaptive Platform Core -

© Vector Informatik GmbH Version 9.0.0 64

Get more Information

Visit our Website for:

> News
> Products
> Demo Software
> Support
> Training Classes
> Addresses

www.vector.com