.. include:: vars.rst .. _section-usage: Usage ===== Overview -------- As shown in :ref:`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-workflow: .. figure:: static/workflow.png :align: center :alt: 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_ME| 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: .. code-block:: console $ rtiarcgen [options] ... *rtiarcgen* is located in the installation directory of |CONNEXT_D|, 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 :ref:`section-features` section for a detailed description of which AUTOSAR model elements can be parsed and transformed by the Integration Toolkit. The :ref:`Command-line Parameters ` section below describes the ``[options]`` you can use to control the Integration Toolkit’s output. .. _section-cli: Command Line Parameters for rtiarcgen ------------------------------------- Global options ~~~~~~~~~~~~~~ The following options provide product information, configure the output path of generated files, and configure some aspects of *rtiarcgen*'s execution: .. list-table:: Global Options :widths: 15 60 25 :header-rows: 1 * - 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 `` - Determines target AUTOSAR environment. [#f5]_ - "``generic_generic``" * - ``-selfTest`` - Runs an internal template loader self-test. - N/A * - ``-idlPath `` - Configures the output path for DDS-IDL files (.idl) generated from the AUTOSAR model. - "``.``" * - ``-xmlPath `` - Configures the output path for DDS-XML files (.xml) generated from the AUTOSAR model. - "``.``" * - ``-cHeaderPath `` - Configures the output path for C language header files (.h extension) generated from the AUTOSAR model. - "``.``" * - ``-cSourcePath `` - Configures the output path for C language source files (.c extension) generated from the AUTOSAR model. - "``.``" * - ``-schemaPath `` - 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. [#f1]_ - "``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``" AUTOSAR Classic options ~~~~~~~~~~~~~~~~~~~~~~~ The following options configure how ARXML input files are processed and what artifacts will be generated from the input files: .. list-table:: ARXML Input Options :widths: 15 55 15 15 :header-rows: 1 * - Option - Description - Default Value - Related Options * - ``-componentFilter `` - 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. [#f2]_ - "``.*``" (all components included) - * - ``-runnablesSuffix `` - Configures a suffix string that will be appended to file names and functions during generation/patching of C runnable source code. [#f3]_ - "" - ``-cHeaderPath`` |br| ``-cSourcePath`` * - ``-idlTypes`` - Configures the Integration Toolkit to produce DDS-IDL data type files (.idl extension). - "``disabled``" - ``-componentFilter`` |br| ``-idlPath`` * - ``-idlComponentInterfaces`` - Configures the Integration Toolkit to produce DDS-IDL component interface files (.idl extension). - "``disabled``" - ``-componentFilter`` |br| ``-idlPath`` * - ``-xmlTypes`` - Configures the Integration Toolkit to produce DDS-XML data type files (.xml extension). - "``disabled``" - ``-componentFilter`` |br| ``-xmlPath`` * - ``-xmlComponentInterfaces`` - Configures the Integration Toolkit to produce DDS-XML component interface files (.xml extension). - "``disabled``" - ``-componentFilter`` |br| ``-xmlPath`` |br| ``-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. [#f4]_ - "``disabled``" - ``RTIDDSGEN_PARAMS`` |br| ``-idlPath`` |br| ``-xmlPath`` |br| * - ``-conversions`` - Configures the Integration Toolkit to produce DDS to/from RTE data type conversion files (.c and .h extensions). - "``disabled``" - ``-componenFilter`` |br| ``-cSourcePath`` |br| ``-cHeaderPath`` |br| ``-optimize`` * - ``-runnables`` - Configures the Integration Toolkit to produce runnable implementation files for selected CDD SW-C model elements. - "``disabled``" - ``-componentFilter`` |br| ``-cSourcePath`` |br| ``-cHeaderPath`` |br| ``-optimize`` * - ``-entities`` - Configures the Integration Toolkit to produce DDS entity support files (dds_entities.h, dds_entities.c). - "``disabled``" - ``-componentFilter`` |br| ``-cSourcePath`` |br| ``-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`` |br| ``-cSourcePath`` Environment variables --------------------- The following environment variables control additional aspects of *rtiarcgen*'s execution: .. list-table:: Environment Variables :widths: 15 55 15 15 :header-rows: 1 * - 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`` 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: .. code-block:: xml VALUE *rtiarcgen* supports Special Data elements as defined below. .. _section-datareader-access-mode: 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. .. code-block:: xml LISTENER * ``POLLING``, resulting in the polling access policy described above. .. code-block:: xml POLLING .. rubric:: Footnotes .. [#f1] 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. .. [#f2] 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). .. [#f3] 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). .. [#f4] *rtiddsgen* must be available in the PATH environment. .. [#f5] Targets are expressed as a string combining vendor, product, version and extra information: ``_[_..[_extra]]`` Supported AUTOSAR environments are: * Vendors: ``elektrobit``, ``vector``, ``generic`` * Products: ``tresos``, ``microsar``, ``generic``