3. Usage

3.1. Overview

As shown in Figure 2 below, the Integration Toolkit for AUTOSAR Classic is comprised of a single application, rtiarcgen. rtiarcgen ingests an AUTOSAR model export in ARXML format, containing one or more Software Components (SW-Cs) of ComplexDeviceDriver (CDD) type, and produces all the following artifacts needed to exercise the CDD SW-C interfaces over DDS:

  • DDS-IDL and DDS-XML type definitions.

  • DDS-IDL RPC definitions (compliant with the DDS-RPC and Adaptive AUTOSAR standards).

  • C-language bidirectional conversion routines between RTE and DDS types.

  • C-language bidirectional marshaling routines between RTE and DDS endpoint entities.

  • C-language DDS middleware/entity configuration, and RTE/DDS mapping routines.

Figure 2: Integration Toolkit for AUTOSAR Classic workflow

Figure 2: Integration Toolkit for AUTOSAR Classic workflow

DDS-IDL and DDS-XML outputs are meant to be processed by an DDS-IDL/DDS-XML type support code generator, like rtiddsgen, in order to produce C-language (.c and .h extensions) support files that integrate with Connext Micro and the rest of generated C-language artifacts.

rtiarcgen is provided as a command-line executable that, once properly installed, can be run with the following command:

$ rtiarcgen [options] <path-to-arxml-input-file> <path-to-arxml-input-file> ...

rtiarcgen is located in the installation directory of Connext Drive, with a platform-dependent launch script located in the “bin” subdirectory. You can launch the application by using its absolute path or, if more convenient, put the absolute path to the “bin” subdirectory in your PATH environment variable.

See the Features section for a detailed description of which AUTOSAR model elements can be parsed and transformed by the Integration Toolkit. The Command-line Parameters section below describes the [options] you can use to control the Integration Toolkit’s output.

3.2. Command Line Parameters for rtiarcgen

3.2.1. Global options

The following options provide product information, configure the output path of generated files, and configure some aspects of rtiarcgen's execution:

Global Options

Option

Description

Default value

-help

Displays product version information and a quick reference of all command-line parameters.

N/A

-version

Displays product version information.

N/A

-target <target>

Determines target AUTOSAR environment. 5

"generic_generic"

-selfTest

Runs an internal template loader self-test.

N/A

-idlPath <path>

Configures the output path for DDS-IDL files (.idl) generated from the AUTOSAR model.

"."

-xmlPath <path>

Configures the output path for DDS-XML files (.xml) generated from the AUTOSAR model.

"."

-cHeaderPath <path>

Configures the output path for C language header files (.h extension) generated from the AUTOSAR model.

"."

-cSourcePath <path>

Configures the output path for C language source files (.c extension) generated from the AUTOSAR model.

"."

-schemaPath <path>

Configures the DDS-XML schema path to include in DDS-XML files (.xml extension) generated from the AUTOSAR model, if any.

""

(no schema-related attributes in the top-level “types” element)

-singleFile

Configures whether the different code generators should produce single files “amalgamating” elements of each AUTOSAR element kind (i.e., one file per data type, one file for data type conversion, etc), instead of one separate file per model element. 1

"disabled"

-verbose

Configures whether the different processors and code generators produce extra messages reflecting its inner workings, like what exact model elements are being found and processed at each stage.

"disabled"

-optimize

Configures whether the different C code generators will consider C-language memory layouts of both DDS and RTE types. The goal is to eliminate both the conversion function calls and these conversion functions themselves.

If used, the conversion function calls suitable for optimization are replaced by simple C pointer casts, which of course improves performance and reduces the final binary footprint.

"disabled"

-dryRun

When enabled, no code is generated, only target file names are show.

"disabled"

3.2.2. AUTOSAR Classic options

The following options configure how ARXML input files are processed and what artifacts will be generated from the input files:

ARXML Input Options

Option

Description

Default Value

Related Options

-componentFilter <regex>

Configures an ECMA-Script regular expression that the ARXML parser will use to identify Complex Device Driver Software Components (CDD SW-C) relevant for code generation. 2

".*"

(all components included)

-runnablesSuffix <suffix>

Configures a suffix string that will be appended to file names and functions during generation/patching of C runnable source code. 3

""

-cHeaderPath
-cSourcePath

-idlTypes

Configures the Integration Toolkit to produce DDS-IDL data type files (.idl extension).

"disabled"

-componentFilter
-idlPath

-idlComponentInterfaces

Configures the Integration Toolkit to produce DDS-IDL component interface files (.idl extension).

"disabled"

-componentFilter
-idlPath

-xmlTypes

Configures the Integration Toolkit to produce DDS-XML data type files (.xml extension).

"disabled"

-componentFilter
-xmlPath

-xmlComponentInterfaces

Configures the Integration Toolkit to produce DDS-XML component interface files (.xml extension).

"disabled"

-componentFilter
-xmlPath
-schemaPath

-ddsTypeSupport

Configures the Integration Toolkit to produce DDS type support files (.c, .h extensions) using RTI's rtiddsgen, from implicitly or explicitly generated DDS-IDL or DDS-XML type files. 4

"disabled"

RTIDDSGEN_PARAMS
-idlPath
-xmlPath

-conversions

Configures the Integration Toolkit to produce DDS to/from RTE data type conversion files (.c and .h extensions).

"disabled"

-componenFilter
-cSourcePath
-cHeaderPath
-optimize

-runnables

Configures the Integration Toolkit to produce runnable implementation files for selected CDD SW-C model elements.

"disabled"

-componentFilter
-cSourcePath
-cHeaderPath
-optimize

-entities

Configures the Integration Toolkit to produce DDS entity support files (dds_entities.h, dds_entities.c).

"disabled"

-componentFilter
-cSourcePath
-cHeaderPath

-entitiesTemplate

Configures the Integration Toolkit to produce a template configuration file (dds_entities_config.c) for the DDS middleware and the DDS entities it will instantiate. The file is only a template, which the AUTOSAR ECU integrator should adapt to suit the project needs.

"disabled"

-componentFilter
-cSourcePath

3.3. Environment variables

The following environment variables control additional aspects of rtiarcgen's execution:

Environment Variables

Option

Description

Default Value

Related Options

RTIDDSGEN_PARAMS

Parameters passed to RTI's rtiddsgen tool. Please note these will always be automatically extended with -d option(s) to control the external tool's output path(s).

"-language microC -replace"

-ddsTypeSupport

-idlPath

-xmlPath

3.4. ARXML extensions

Since DDS is not supported by the AUTOSAR's Classic Platform meta-model, certain deployment and operational aspects of DDS are impossible to define with, or infer from, AUTOSAR ARXML exports.

To overcome this limitation, rtiarcgen leverages the general-purpose "Admin Data" structures (nesting Special Data Group Sections, Special Data Groups and Special Data elements) that any AUTOSAR model entity can define.

The following is an exemple ARXML representation of an entity's Admin Data:

<ADMIN-DATA>
   <SDGS>
      <SDG GID="GroupName">
         <SD GID="GroupName::ValueName">VALUE</SD>
      </SDG>
   </SDGS>
</ADMIN-DATA>

rtiarcgen supports Special Data elements as defined below.

3.4.1. DataReader access mode

When AUTOSAR SW-C Runnables are linked to S/R Port Prototype Elements for writing or reading, the link is called an "Access Point". Such access points can be annotated with Admin Data elements that specify (for Provided S/R Port Prototypes) how data samples from the underlying DDS DataReader will be read. Available choices are:

  • Listener, where the SW-C Runnable is directly called from a Listener callback, which is only triggered by the DDS Middleware when the DataReader in question has received samples.

  • Polling, where the SW-C Runnable is configured to run periodically, checking the underlying DataReader for available samples and transferring those to the Provided port.

Thus, rtiarcgen will look for Special Data elements whose identifier is Rti::DataReaderAccessMode, accepting the following values:

  • LISTENER, assumed by default if nothing is specified, resulting in the listener-driven access policy described above.

<ADMIN-DATA>
   <SDGS>
      <SDG GID="Rti">
         <SD GID="Rti::DataReaderAccessMode">LISTENER</SD>
      </SDG>
   </SDGS>
</ADMIN-DATA>
  • POLLING, resulting in the polling access policy described above.

<ADMIN-DATA>
   <SDGS>
      <SDG GID="Rti">
         <SD GID="Rti::DataReaderAccessMode">POLLING</SD>
      </SDG>
   </SDGS>
</ADMIN-DATA>

Footnotes

1

The -singleFile option also references how runnable code files (.c extensions) reference type and conversion routine files (i.e., a single “#include” statement for all referenced elements, instead of one “#include” statement for each).

For example, if your AUTOSAR “model.arxml” ARXML file contains two supported Implementation data types, “Foo” and “Bar”:

  • With -singleFile, the DDS-IDL code generator will produce a single “model_types.idl” file;

  • Without -singleFile, the DDS-IDL code generator will produce separate “Foo.idl” and “Bar.idl” files.

2

Please make sure to include your regular expression within double quotes in order to avoid interference by the operating system’s shell interpreter when processing special characters such as parentheses, asterisks, etc.

The complete AUTOSAR model path (including enclosing package names) of each CDD SW-C is used when matching against this regular expression.

For example, suppose your AUTOSAR “model.arxml” ARXML file contains two CDD SW-Cs, “/Foo/Bar/Alpha” and “/Foo/Bar/Beta”:

  • With -componentFilter ”.*Alpha.*”, only “/Foo/Bar/Alpha” is processed;

  • With -componentFilter ”\/Foo\/Bar\/.+”, both “/Foo/Bar/Alpha” and “/Foo/Bar/Beta” are processed, but not SW-Cs in other packages;

  • Without -componentFilter ”...”, all SW-Cs in all packages are processed (see default value).

3

For example, suppose your AUTOSAR “model.arxml” ARXML file contains a CDD SW-Cs “/Foo/Bar/Alpha” with runnables “F1” and “F2”:

  • With -componentFilter ”_dds”, the Integration Toolkit will generate “Alpha_dds.c”, which implements “F1_dds” and “F2_dds”;

  • Without -runnablesSuffix ”...”, the Integration Toolkit will generate “Alpha.c”, which implements “F1” and “F2” (see default value).

4

rtiddsgen must be available in the PATH environment.

5

Targets are expressed as a string combining vendor, product, version and extra information:

<vendor>_<product>[_<major>.<minor>.<patch>[_extra]]

Supported AUTOSAR environments are:

  • Vendors: elektrobit, vector, generic

  • Products: tresos, microsar, generic