Application Base: Technical Reference

Application Base
Technical Reference
Adaptive MICROSAR
Version master-3976
Authors vsarcbosu, vsarcjogu, vsarcjoba

Status Released
Technical Reference Application Base
Document Information
History
The change history of this file is part of the component change history. It is documented in
ChangeHistory.txt of the component folder.
Reference Documents
[1] AUTOSAR. Specification of Core Types for Adaptive Platform. R19-03.
Caution
We have configured the programs in accordance with your specifications in the ques-
tionnaire. Whereas the programs do support other configurations than the one specified
in your questionnaire, Vector´s release of the programs delivered to your company is
expressly restricted to the configuration you have specified in the questionnaire.
© 2021, Vector Informatik GmbH Version: master-3976 1 / 17
based on template version 1.00.00

Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1 Architectural Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.1 Dependencies 5
1.1.2 Component Design 5
2 Functional Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1.1 Initialization and Shutdown 6
2.2 Known Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.1 Build Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2 Files and Include Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.3 Integration of ApplicationBase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.4 CMake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.4.1 Build 8
3.4.2 Exported CMake packages 8
3.5 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4 API Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1 ara/core/initialization.h File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1.1 Detailed Description 10
4.1.2 Function Documentation 10
4.1.2.1 Deinitialize() noexcept 10
4.1.2.2 Initialize() noexcept 11
4.2 amsr/application_base/initialization_error_domain.h File Reference . . . . . . . . . . . . . . . . 12

4.2.1 Detailed Description 13
4.2.2 Enumeration Type Documentation 13
4.2.2.1 InitializationErrc 13
4.2.3 Function Documentation 13
4.2.3.1 GetInitializationErrorDomain() noexcept 13
4.2.3.2 MakeErrorCode(InitializationErrc code, ara::core::ErrorDomain::SupportDataType
data, char const ∗message) noexcept 13
4.2.4 amsr::application_base::InitializationErrorDomain 14
4.2.4.1 Detailed Description 14
4.2.4.2 Constructor & Destructor Documentation 14

4.2.4.3 Member Function Documentation 14
5 Glossary and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5.1 Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
6 Contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Illustrations
Tables
2-1 Supported AUTOSAR Conform Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2-2 Known Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3-1 CMake options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Listings
3-1 Example usage of ApplicationBase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1 Introduction
This document describes the functionality, API and configuration of the Adaptive AUTOSAR BSW
module ApplicationBase.
ApplicationBase provides the global initialization and shutdown functions, that initialize and deinitialize,
respectively, data structures and threads of the AUTOSAR Runtime for Adaptive Applications, as
specified in Adaptive Core Types specification [1].
> Supported AUTOSAR Release R19-03
1.1 Architectural Overview

1.1.1 Dependencies
ApplicationBase has direct dependencies to VaCommonLib.
> VaCommonLib is used to provide STL like containers & abstractions.
1.1.2 Component Design

The ApplicationBase component consists of:
> application_base library
> amsr_applicationbase_init_deinit generator
The application_base library provides the public APIs, ara::core::Initialize() and
ara::core::Deinitialize(). In order for these functions to return suitable errors the error domain
amsr::application_base::InitializationErrorDomain is also provided with the library.
The amsr_applicationbase_init_deinit generator is used to generate the definitions for
ara::core::Initialize() and ara::core::Deinitialize(). This is done by identifying the used
components and then using that information together with a JET-template to create a C++ source file.
ara::core::Initialize() has to be called before any ARA API is called in an Adaptive application.
ara::core::Deinitialize() has to be called when ARA APIs are not used any more in an Adaptive
application.
Only one sequence of ara::core::Initialize(), ara::core::Deinitialize() is supported. If

reinitialization is needed the process shall do a clean exit and recovery shall be done by the execution
manager.

2 Functional Description
The features listed in the sections cover the complete functionality specified for the ApplicationBase.
Referring to the AUTOSAR standard functionality as specified in [1], the implemented features are
described in 2.1.
Known Limitations of the current implementation of the module are listed in 2.2.
2.1 Features
The following features specified in [1] are supported:
Feature Description
Initialization and Shutdown see 2.1.1
Table 2-1 Supported AUTOSAR Conform Features
2.1.1 Initialization and Shutdown

The function definitions for ara::core::Initialize and ara::core::Deinitialize are provided in a static header
file, initialization.h.
The function declarations are generated to a source file, initialization.cpp, by the generator
amsr_applicationbase_init_deinit. The source file will always contain initialization and deinitial-
ization code for the amsr::vac, amsr::osabstraction, amsr::thread and ara::log components.
Initialization and deinitialization code will also be generated to initialization.cpp for all other
components that are used in the Adaptive application (see 2-2 for supported components). To identify
which components are used in an Adaptive application, the generator loops over the port interfaces
defined in the AUTOSAR model for that application:
> A port interface of type PersistencyInterface indicates ara::per usage.

> A port interface of type ServiceInterface indicates ara::com usage.
> A port interface of type DiagnosticPortInterface indicates ara::diag usage.
> A port interface of type TimeSynchronizationInterface indicates amsr::tsync usage.
Also, the attribute DvMex:usePhmApi of the model extension PhmExecutableExtension is used to
check if amsr::phm is used.

2.2 Known Limitations
Limitation Description
Supported Modules Currently generation of initialization and deinitialization code
is only supported for amsr::vac, amsr::osabstraction,
amsr::thread, ara::log, ara::per, ara::com, ara::diag,
amsr::tsync and amsr::phm.
API Generation Currently executable.category is evaluated and only for
APPLICATION_LEVEL is initialization and deinitialization code
generated.
Reinitialization Only one sequence of ara::core::Initialize(),
ara::core::Deinitialize() is supported in one process.
Table 2-2 Known Limitations

3 Integration
3.1 Build Dependencies

To build ApplicationBase the following components are required:
> amsr-vector-fs-libvac
3.2 Files and Include Structure

The header files can be included like this:
#include ”ara/core/initialization.h”
The initialization.h is specified in Adaptive Core Types specification [1].
If the component ara::com is used, the .json-configuration file used for the application must be placed
in the ./etc folder with the name com_application.json.
The generator amsr_applicationbase_init_deinit generator is delivered as a single jar-file:

amsr_application_base_init_deinit.jar.
3.3 Integration of ApplicationBase

Following steps are necessary if ApplicationBase shall be used:
For every application (i.e. an executable that uses ApplicationBase):

> Create an ARXML manifest as defined by AUTOSAR_TPS_ManifestSpecification.
> Add the generated header for this application.
> Build the application.
Every application needs an individual ApplicationBase library that is built with the application specific
generated code.
3.4 CMake
For detailed usage of CMake see documentation available at https://cmake.org/documentation.
3.4.1 Build
The CMake project provided with this component has options as specified in 3-1.
CMake option Description Defaultvalue

-DENABLE_DOXYGEN Vector internal use. Set to OFF OFF
-DBUILD_TESTS Vector internal use. Set to OFF OFF
Table 3-1 CMake options
3.4.2 Exported CMake packages

The amsr-vector-fs-applicationbase CMake project exports packages which can be used to compile
against the exported library.

3.5 Usage
The example shown in 3-1 demonstrates the usage of ApplicationBase.
// ...
#include "ara/core/initialization.h"
int main(int argc, char* argv[]) {

// static variables/objects initialized
// setup signal handling, ...
ara::core::Result<void> init_result {ara::core::Initialize()};
// init_result.HasValue() != true -> ARA can not be used
// init_result.HasValue() == true -> ARA can be used
if(init_result.HasValue()) {
// ... business logic ...
// 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();
});
}
} // static variables/objects will be deinitialized
Listing 3-1 Example usage of ApplicationBase

4 API Description
4.1 ara/core/initialization.h File Reference

Provides ara::core::Initialize() and ara::core::Deinitialize().
#include "amsr/application_base/initialization_error_domain.h"
#include "ara/core/result.h"
Functions
> Result< void > ara::core::Initialize () noexcept
(Pre-)Initialization of the ARA Framework.
> Result< void > ara::core::Deinitialize () noexcept
Shutdown of the ARA Framework.
4.1.1 Detailed Description

Provides ara::core::Initialize() and ara::core::Deinitialize().
Provides the global initialization and shutdown functions that initialize resp. deinitialize data structures
and threads of the AUTOSAR Runtime for Adaptive Applications (ARA).
4.1.2 Function Documentation

4.1.2.1 Result<void> ara::core::Deinitialize ( ) [noexcept]
Shutdown of the ARA Framework.
When Initialize() has returned successfully, Deinitialize() has to be called. After this call, no interaction
with the ARA (Adaptive Runtime for Application) is allowed (with the exception of constant initializations
and types which are trivial destructible). As a prerequisite to calling this API it is expected that the use
of ARA interfaces is completed (with the given exceptions). It is required to make this call in a place
where it is guaranteed that the static initialization has completed and destruction of statically initialized
data has not yet started (e.g. inside of main function).
Precondition
ara::core::Initialize() has returned successfully.
All threads accessing ARA APIs joined.
Note
Calling any ARA functions after calling this function may have unforeseen consequences. When
Deinitialize() returns with an error, it is generally unsafe to call either Deinitialize() or Initialize()
again.
Remarks
The function body is generated.
// ...


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

ara::core::Result<void> deinit_result {
ara::core::Deinitialize()};

});
}
Product public API
Thread-safe: FALSE
Reentrant: FALSE
Return values
InitializationErrc::kWrongSequence Deinitialize() is called in a wrong sequence (e.g.

Deinitialize() is called prior to Initialize()).
Returns
an initialized Result<void> on success.
4.1.2.2 Result<void> ara::core::Initialize ( ) [noexcept]

(Pre-)Initialization of the ARA Framework.
Prior to this call, no interaction with the ARA (Adaptive Runtime for Applications) is allowed with the
exception of constant initializations and types which are trivially destructible. It is required to make
this call in a place where it is guaranteed that static memory initialization has completed (e.g. inside
of main function). When Initialize() has returned successfully, calling it again will return an error.
When Initialize() returns with an error, the application may report the error cause and exit by using an
appropriate return code. Calling Deinitialize() in this case is not necessary.
Note
Calling any ARA functions before calling this function may have unforeseen consequences.

Remarks
The function body is generated.
// ...

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

ara::core::Result<void> deinit_result {
ara::core::Deinitialize()};

});
}
return init_result.HasValue() ? 0 : -1;
Product public API
Thread-safe: FALSE
Reentrant: FALSE
Return values
InitializationErrc::kWrongSequence Initialize() is called in a wrong sequence (e.g. twice

consecutively)
Returns
an initialized Result<void> on success.
4.2 amsr/application_base/initialization_error_domain.h File Reference

Error domain for errors originating from initialization and deinitialization of components.
#include <limits>
#include <utility>
#include "ara/core/error_code.h"
#include "ara/core/error_domain.h"
#include "ara/core/exception.h"
#include "vac/language/throw_or_terminate.h"

Classes
> class amsr::application_base::InitializationException
Exception type thrown by ara::core::Initialize()/aracore::Deinitialize().
> class amsr::application_base::InitializationErrorDomain
Error domain for errors originating from ara::core::Initialize()/aracore::Deinitialize().
Enumerations
> enum amsr::application_base::InitializationErrc : ara::core::ErrorDomain::CodeType {
amsr::application_base::InitializationErrc::kWrongSequence = 101 }
Specifies the internal errors that can occur upon calling ara::core::Initialize()/aracore::Deinitialize().
Functions
> constexpr ara::core::ErrorDomain const & amsr::application_base::GetInitializationErrorDomain ()
noexcept
Obtain the reference to the single global InitializationErrorDomain instance.
> constexpr ara::core::ErrorCode amsr::application_base::MakeErrorCode (InitializationErrc code,
ara::core::ErrorDomain::SupportDataType data, char const ∗message) noexcept
Create a new ErrorCode for InitializationErrorDomain with the given support data type and message.
4.2.1 Detailed Description

Error domain for errors originating from initialization and deinitialization of components.
4.2.2 Enumeration Type Documentation

4.2.2.1 enum amsr::application_base::InitializationErrc : ara::core::ErrorDomain::CodeType
[strong]
Specifies the internal errors that can occur upon calling ara::core::Initialize()/aracore::Deinitialize().
Product public API
4.2.3 Function Documentation

4.2.3.1 constexpr ara::core::ErrorDomain const& amsr::application_base::GetInitializationErrorDomain
( ) [inline], [noexcept]
Obtain the reference to the single global InitializationErrorDomain instance.
Returns
Reference to the InitializationErrorDomain instance.
Product public API
References amsr::application_base::GetInitializationErrorDomain().
Referenced by amsr::application_base::GetInitializationErrorDomain(), and amsr::application_base::MakeErrorCod
4.2.3.2 constexpr ara::core::ErrorCode amsr::application_base::MakeErrorCode (

InitializationErrc code, ara::core::ErrorDomain::SupportDataType data, char const
∗ message ) [inline], [noexcept]
Create a new ErrorCode for InitializationErrorDomain with the given support data type and message.
Parameters
code Enumeration value from InitializationErrc.

data Vendor-defined supplementary value.
message User-defined context message (can be nullptr).
Returns
The new ErrorCode instance.
Product public API
References amsr::application_base::GetInitializationErrorDomain(), and amsr::application_base::MakeErrorCode()

Referenced by amsr::application_base::MakeErrorCode().
4.2.4 amsr::application_base::InitializationErrorDomain
Inheritance diagram for amsr::application_base::InitializationErrorDomain:
ErrorDomain
amsr::application_base::InitializationErrorDomain
Public Types
> using Exception = InitializationException
Alias for the exception base class.
Public Member Functions

> constexpr InitializationErrorDomain () noexcept
Default constructor.
> char const ∗ Name () const noexceptfinal
Return the "shortname" ApApplicationErrorDomain.SN of this error domain.
> char const ∗ Message (ErrorDomain::CodeType error_code) const noexceptfinal
Translates an error code value into a text message.
> void ThrowAsException (ara::core::ErrorCode const &error_code) const noexcept(false) final
Throw the exception type corresponding to the given ErrorCode.
4.2.4.1 Detailed Description

Product public API
4.2.4.2 Constructor & Destructor Documentation

constexpr amsr::application_base::InitializationErrorDomain::InitializationErrorDomain ( )
[inline], [noexcept] Default constructor.
Product public API
4.2.4.3 Member Function Documentation

char const∗ amsr::application_base::InitializationErrorDomain::Message ( ErrorDomain::CodeType
error_code ) const [inline], [final], [noexcept] Translates an error code value into a text
message.
Parameters
error_code The error code value to translate.

Returns
The text message, never nullptr.
Product public API
char const∗ amsr::application_base::InitializationErrorDomain::Name ( ) const [inline],

[final], [noexcept] Return the "shortname" ApApplicationErrorDomain.SN of this error domain.
Returns
"InitializationError".
Product public API
void amsr::application_base::InitializationErrorDomain::ThrowAsException ( ara::core::ErrorCode

const & error_code ) const [inline], [final], [noexcept] Throw the exception type corre-
sponding to the given ErrorCode.
Parameters
error_code The ErrorCode instance.

Product public API
The documentation for this class was generated from the following file:
> lib/application_base/include/amsr/application_base/initialization_error_domain.h

5 Glossary and Abbreviations
5.1 Abbreviations
Abbreviation Description
AMSR Adaptive MICROSAR
amsr-vector-fs- ApplicationBase CMake Project
applicationbase
AUTOSAR Automotive Open System Architecture
BOM Byte order mark
CRC Cyclic redundancy check
MICROSAR Microcontroller Open System Architecture
TLV Tag-Length-Value
UTF-8 Unicode Transformation Format – 8-bit

6 Contact
Visit our website for more information on
> News
> Products
> Demo software
> Support
> Training data
> Addresses
www.vector.com

Application Base: Technical Reference

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Application Base: Technical Reference

Uploaded by

Copyright:

Available Formats

Application Base

Authors vsarcbosu, vsarcjogu, vsarcjoba

© 2021, Vector Informatik GmbH Version: master-3976 1 / 17

based on template version 1.00.00

2.2 Known Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.2 amsr/application_base/initialization_error_domain.h File Reference . . . . . . . . . . . . . . . . 12

© 2021, Vector Informatik GmbH Version: master-3976 2 / 17

based on template version 1.00.00

4.2.4.3 Member Function Documentation 14

5 Glossary and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

© 2021, Vector Informatik GmbH Version: master-3976 3 / 17

based on template version 1.00.00

2-1 Supported AUTOSAR Conform Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3-1 CMake options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3-1 Example usage of ApplicationBase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

© 2021, Vector Informatik GmbH Version: master-3976 4 / 17

based on template version 1.00.00

1.1 Architectural Overview

> VaCommonLib is used to provide STL like containers & abstractions.

1.1.2 Component Design

Only one sequence of ara::core::Initialize(), ara::core::Deinitialize() is supported. If

© 2021, Vector Informatik GmbH Version: master-3976 5 / 17

based on template version 1.00.00

Table 2-1 Supported AUTOSAR Conform Features

2.1.1 Initialization and Shutdown

> A port interface of type PersistencyInterface indicates ara::per usage.

© 2021, Vector Informatik GmbH Version: master-3976 6 / 17

based on template version 1.00.00

2.2 Known Limitations

Table 2-2 Known Limitations

© 2021, Vector Informatik GmbH Version: master-3976 7 / 17

based on template version 1.00.00

3.1 Build Dependencies

3.2 Files and Include Structure

The generator amsr_applicationbase_init_deinit generator is delivered as a single jar-file:

3.3 Integration of ApplicationBase

For every application (i.e. an executable that uses ApplicationBase):

CMake option Description Defaultvalue

Table 3-1 CMake options

3.4.2 Exported CMake packages

© 2021, Vector Informatik GmbH Version: master-3976 8 / 17

based on template version 1.00.00

int main(int argc, char* argv[]) {

// all threads accessing ARA APIs joined

Listing 3-1 Example usage of ApplicationBase

© 2021, Vector Informatik GmbH Version: master-3976 9 / 17

based on template version 1.00.00

4.1 ara/core/initialization.h File Reference

4.1.1 Detailed Description

4.1.2 Function Documentation

int main(int argc, char* argv[]) {

// static variables/objects initialized

© 2021, Vector Informatik GmbH Version: master-3976 10 / 17

based on template version 1.00.00

// ... business logic ...

// all threads accessing ARA APIs joined

std::cerr << "ara::core::Deinitialize() failed!";

Product public API

InitializationErrc::kWrongSequence Deinitialize() is called in a wrong sequence (e.g.

4.1.2.2 Result<void> ara::core::Initialize ( ) [noexcept]

© 2021, Vector Informatik GmbH Version: master-3976 11 / 17

based on template version 1.00.00

int main(int argc, char* argv[]) {