3. Usage¶

3.1. Overview¶

The AUTOSAR Runtime Adaptive Code Generator is comprised of a single application, rtiaragen. rtiaragen ingests one or more AUTOSAR ARXML model exports, and produces the following artifacts needed to deploy Service Interfaces and Instances using the DDS Network Binding:

DDS-IDL and DDS-XML type definitions
DDS-IDL Service Interface definitions (compliant with the DDS-RPC and Adaptive AUTOSAR standards)
C++-language bidirectional conversion routines between ara:com and DDS types
C++-language service interface skeletons and proxies
C++-language service interface common declarations
C++-language service interface declarations specific to the DDS Network Binding
C++-language vendor-specific artifacts specific to the DDS Network Binding
Key/Value deployment configuration files

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.

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

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

rtiaragen 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 AUTOSAR Runtime Adaptive Code Generator. The Command-line Parameters section below describes the [options] you can use to control the AUTOSAR Runtime Adaptive Code Generator output.

3.2. Command Line Parameters for rtiaragen¶

3.2.1. Global options¶

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

Table 3.1 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. 4	"`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.	"`.`"
`-cppHeaderPath <path>`	Configures the output path for C++ language header files (.h extension) generated from the AUTOSAR model.	"`.`"
`-cppSourcePath <path>`	Configures the output path for C++ language source files (.cpp extension) generated from the AUTOSAR model.	"`.`"
`-kvPath <path>`	Configures the output path for Key/Value files (.kv extension) generated from the AUTOSAR model.	"`.`"
`-jsonPath <path>`	Configures the output path for JSON files (.json 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 code generators will consider memory layouts of both DDS and ara:com 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 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 Adaptive options¶

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

Table 3.2 ARXML Input Options¶
Option	Description	Default Value	Related Options
`-executableFilter <regex>`	Configures an ECMA-Script regular expression that the ARXML parser will use to identify Executables relevant for code generation. 2	"`.*`" (all components included)
`-idlTypes`	Configures the Code Generator to produce DDS-IDL data type files (.idl extension).	"`disabled`"	`-executableFilter` `-idlPath`
`-idlServiceInterfaces`	Configures the Code Generator to produce DDS-IDL service interface files (.idl extension).	"`disabled`"	`-executableFilter` `-idlPath`
`-xmlTypes`	Configures the Code Generator to produce DDS-XML data type files (.xml extension).	"`disabled`"	`-executableFilter` `-xmlPath` `-schemaPath`
`-xmlServiceInterfaces`	Configures the Code Generator to produce DDS-XML service interface files (.xml extension).	"`disabled`"	`-executableFilter` `-xmlPath` `-schemaPath`
`-ddsTypeSupport`	Configures the Code Generator 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. 3	"`disabled`"	`RTIDDSGEN_PARAMS` `-idlPath` `-xmlPath`
`-implementationTypes`	Configures the Code Generator to produce C++ implementation type files (.h extension).	"`disabled`"	`-executableFilter` `-cSourcePath` `-cHeaderPath`
`-conversions`	Configures the Code Generator to produce DDS to/from ara:com data type conversion files (.cpp and .h extensions).	"`disabled`"	`-componenFilter` `-cSourcePath` `-cHeaderPath` `-optimize`
`-errorDomains`	Configures the Code Generator to produce C++ error and error domain files (.cpp, .h extensions).	"`disabled`"	`-executableFilter` `-cSourcePath` `-cHeaderPath` `-optimize`
`-serviceInterfaces`	Configures the Code Generator to produce C++ service interface files (.h extension).	"`disabled`"	`-executableFilter` `-cSourcePath` `-cHeaderPath`
`-deployments`	Configures the Code Generator to produce Key/Value service interface and instance deployment configuration files (.kv extension).	"`disabled`"	`-executableFilter` `-kvPath`
`-vendorSupport`	Configures the Code Generator to produce vendor-specific support files (vendor-specific extensions).	"`disabled`"	`-target` `-cppHeaderPath` `-cppSourcePath`

3.3. Environment variables¶

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

Table 3.3 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 C -replace`"	`-ddsTypeSupport` `-idlPath` `-xmlPath`

3.4. ARXML extensions¶

Since some DDS aspects are not supported by AUTOSAR's Adaptive 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, rtiaragen 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>

rtiaragen supports Special Data elements as defined below.

3.4.1. Type transfer mode¶

When DDS types are defined, RTI Connext users can optionally specify what format will be used when the type is being transferred over the selected transport.

In most cases, this defaults to the INBAND option, which employs XCDR serialisation to marshall the sample across networks and hosts.
In environments where a shared memory transport is available, the SHMEM_REF option might be preferred, as it avoids sample serialisation and merely exchanges sample references between processes.

Thus, rtiaragen will look for Special Data elements within type definitions whose identifier is Rti::TransferMode, accepting the following values:

INBAND, assumed by default if nothing is specified, resulting in the inband format described above.

<ADMIN-DATA>
   <SDGS>
      <SDG GID="Rti">
         <SD GID="Rti::TransferMode">INBAND</SD>
      </SDG>
   </SDGS>
</ADMIN-DATA>

SHMEM_REF, resulting in the shared memory -friendly format described above.

<ADMIN-DATA>
   <SDGS>
      <SDG GID="Rti">
         <SD GID="Rti::TransferMode">SHMEM_REF</SD>
      </SDG>
   </SDGS>
</ADMIN-DATA>

Footnotes

1

The -singleFile option also references how code files 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 Executable is used when matching against this regular expression.

For example, suppose your AUTOSAR “model.arxml” ARXML file contains two Service Interfaces, “/Foo/Bar/Alpha” and “/Foo/Bar/Beta”:

With -executableFilter ”.*Alpha.*”, only “/Foo/Bar/Alpha” is processed;
With -executableFilter ”\/Foo\/Bar\/.+”, both “/Foo/Bar/Alpha” and “/Foo/Bar/Beta” are processed, but not Executables in other packages;
Without -executableFilter ”...”, all Executables in all packages are processed (see default value).

3

rtiddsgen must be available in the PATH environment.

4

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

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

Supported AUTOSAR environments are:

Vendors: rti, elektrobit, vector, generic
Products: ara-com-reference, microsar, generic