Table of Contents
Introduction
Scope
This application note describes the background knowledge on creating a calibratable parameter from a SWC for the RTA-RTE. With information on how to emit specific data from the RTA-RTE to the McSupportData. Leading into a detailed step by step guide to generating an A2L file using the RTA-A2L tool.
Definitions & Abbreviations -
BSW: AUTOSAR Basic Software / Hardware indepentent service layer
RTE: AUTOSAR Real Time Environment
OS: AUTOSAR Operating System
AR: AUTOSAR
AN: Application Note
SWC: Software Component
A2L: ASAM MCD-2 MC Language / File type
FID: Flat Instance Descriptor / Description
ECU: Electronic / Engine Control Unit
MCSD: McSupportData generated by RTE
SK: Starter Kit
Toolchain
It is assumed you are using the RTA-CAR 9.2.1 toolchain:
| RTA-CAR 9.2.1 toolchain | |
|---|---|
| ISOLAR-AB | 9.2.1 |
| RTA-RTE | 7.5.3 |
| RTA-BSW | 6.1.3 |
| RTA-OS | 6.2.0 |
Pre-Requisites
In order to complete this guide, it is assumed the Reader has a good knowledge of AR methodology and terminology. As well as having followed the subsequent guide on SWC calibration to create calibratable parameters within ISOLAR-AB 9.2.1 rather than 9.2.0:
https://rtahotline.etas.com/confluence/display/RH/SWC+Calibration
The following guide uses the RTA-CAR 9.2.1 Standard VRTA SK.
Workflow Summary
Here is a summary of the steps that you will be following in this example guide:
- Step 1: RteMeasurementSupport configuration
- Step 2: SwCalibrationAccess configuration
- Step 3: FlatInstanceDescriptor configuration
- Step 4: Emit MCSD Information
- Step 5: RTA-A2L file retrieval
- Step 6: RTA-A2L limitations & pre-processing
- Step 7: RTA-A2L basic use-case #1
- Step 8: RTA-A2L basic use-case #2
- Step 9: RTA-A2L basic use-case #3
Workflow
Calibratable parameter visible to RTA-RTE
After creating parameters Param1 and Param2 in accordance with the pre-requisite guide, the next steps are to ensure that these parameters are visibly labelled to the RTA-RTE as calibration/measurement data. Whether these parameters or future parameters from a separate project are SWC instance specific, shared among the same SWC type or shared globally, they must meet the following three conditions to appear in the McSupportData generated by the RTE:
RteMeasurementSupport
One condition is that RteMeasurementSupport must be set to True. To set this navigate to the EcucValueCollection within the ECU Navigator under Bsw_Modules\Ecuc_Value_Collections and open this using the RTE Editor:
After opening the RTE Editor view, navigate to the RTE Configuration tab in the bottom left of the window:
Here it is possible to configure the RTE generation as the project requires, however for this guide ensure that RteMeasuremenentSupport is set to true:
SwCalibrationAccess
Within each created parameter, there is an attribute named SwCalibrationAccess. This attribute informs the RTE and the rest of the software that this parameter can be accessed for calibration, and therefore is required in the generation of the MCSDs. To find where to edit this attribute for Param1, navigate to the affected SWC, in the case of this guide this is MasterSWC and open its Internal Behavior in generic editor:
Within the generic editor, navigating to the assigned PerInstanceParameters open their respected SwDataDefProps-Conditional files to locate the attribute fields to assign the SwCalibrationAccess:
FlatInstanceDescriptor
For each calibration/measurement parameter there must exist an accompanying FlatInstanceDescriptor as without one the RTE will present a warning while continuing to calibrate other parameters, stating it will not be appended to the MCSD file. To check that a calibration parameter has one open the ApplicationECU_FlatMap.armxl in XML editor view:
Within this file navigate to /AR-PACKAGES/AR-PACKAGE/ELEMENTS/FLAT-MAP/INSTANCES, where these generated FIDs for calibration parameters can be found:
Here there are a number of FIDs for data-values within this project, the interest of this guide is to navigate to Param1 and Param2 created previously present in this Flat Map. By de-collapsing each instance, there are <SHORT-NAME> attributes which will indicate the FID in question. Below are the corresponding FIDs for Param1 and Param2:
Emit Information in MCSD
RTE Generation Commands
During RTE generation, it is possible to set command parameters for how the project should generate the RTE and corresponding files. The first command allows for the specification of options pertaining to the output of MCSD, this command being “--mcsd-policy”. Within this command there are four parameters that can affect the generation of the MCSD file. Here they are in a list:
- Copy-source-path: For each Unit and UnitGroup RTA-RTE emits a SpecialDataGroup, GID="ETAS-RTARTE", containing a SpecialData element, GID="AR-PACKAGE-SRC", which has the value of the full package and shortName for that Unit or UnitGroup as provided in the input configuration.
- Emit-memorys: emits McDataInstance containers for any BSW or ASW Static or Constant Memory.
- Phys-constrs-always: RTA-RTE shall always write PhysConstrs related to every McDataInstance. If necessary, the PhysConstr will be taken from The ApplicationDataType, ImplementationDataType, CompuMethod (for enumerated types) or SwBaseType (for Category NONE, 2C or BOOLEAN). If no PhysConstr can be found or calculated, an error is raised.
- Struct-element-symbols: For McDataInstances that are structure elements, the C names for the elements are emitted as their symbols. These are not global linker symbols, but they do allow the full C expressions to access the elements to be constructed.
- mcfunction-from-shortname: For all McDataInstances where RTA-RTE sees a relevant DataPrototype, that DataPrototype’s shortName is copied to the Mc-DataInstance’s McFunction. This policy is deprecated; it was implementedas a workaround for use before RTA-RTE exported McFunction correctly.
The second command available for affecting the generation of MCSD within the RTE is “--local-mcsd”. This option takes a single parameter that must be an absolute reference to a ApplicationSoftwareComponentType whose internal data is wanted to be reported to in the MCSD. A note to make about this command is that it is a non-AUTOSAR generation phase generating a MCSD for a specific software module, and cannot be mixed with any other phase in the same run of the RTE. The RTE will generate a MCSD report containing the staticMemorys, constantMemorys and perInstanceParameters of the given module, and to include multiple modules in the MCSD it is possible to specify the command multiple times on the command line.
Using RTE Generation Commands
In order to use these commands mentioned above, open the RTA Code Generator Dialog window by selecting the project and clicking the drop down menu for RTA Generation:
Within this window, select the tool RTA-RTE with the tool selection area. This should present the following layout, where the user can input via text an RTE command. Within this guide it is not required to enter one of the aforementioned commands, though are useful to know for future projects. Therefore, paste the following command sequence into the input field: --strict-unconnected-rport-check=off --os-define-osenv=RTAOS40 --notimestamps --samples=memmap
Then click Apply and then Run, to generate the RTE and required Rte_McSupportData.arxml file for usage in the RTA-A2L tool.
Generating A2L file using RTA-A2L
RTA-A2L file setup
Locating files
The RTA-A2L tool supports three basic use-cases for A2L file generation; this guide will follow the first use-case, using the generated MCSD from the RTE and output.map file produced when building the 9.2.1 SK. To find the MCSD, it is located under the SK project folder in /src/rte labelled Rte_McSupportData.armxl:
Then open the folder rte:
Here located towards the middle of the folder contents is the Rte_McSupportData.arxml file, this needs to be copied to a separate folder for the usage of RTA-A2L or copy the path of this file for later reference within the tool:
To find the output.map file which will be used to instantiate the memory addresses of corresponding characteristics and measurements, it is required to build the complete project: meaning generation of AR components should be completed (BSW, OS & RTE). Building the project may be different depending on the practice used, though it should output this file containing all the memory addresses for the ECU. Following the completion of the build generation, the output.map file should be moved to the same folder as the Rte_McSupportData.arxml to aid RTA-A2L by using shorter file paths.
The last requirement for the first use-case of RTA-A2L is a template file which outlines the basic structure and syntax of our generated .a2l file. Below is an example, which can be used for this guide. Simply copy this into a notepad file with the file extension .a2la, which helps the tool identify it as a a2l template. . Template files are ASAM A2L files with the exception that they contain a processing instruction <?emitA2L?> that directs RTA-A2L to insert the translated A2L objects in this section of the document.
ASAP2_VERSION 1 60 /begin PROJECT Example_Template "Prototype Template layout" /begin HEADER "" VERSION "000" PROJECT_NO RTA_A2L_TEST /end HEADER /begin MODULE_A_MODULE "Input to the RTA-A2L Tool" <?emitA2L?> /end MODULE /end PROJECT
RTA-A2L Limitations & Pre-Processing
Now that all the required files have been generated and found, its time to look at the RTA-A2L tool, however there are a few issues to note. Firstly, RTA-A2L will accept any well-formed XML as MCSD input and does not perform any further validation. So, the user should ensure the correct file with McDataInstances is being used. Secondly, when working with the .map file it is important to note that a .txt with the same information on each line will also work as an input. However, there can be no indentation/spacing at the beginning of each line but any amount of whitespace between the symbol and address is acceptable. Each address must be in a hexadecimal format and preceded by 0x and are matched by the regular expression: 0x[0…9A…Fa…f]+, while valid symbols match the regular expression: [A…Za…Z_][A…Za…z_\.\[\]]*. The current version of the RTA-A2L tool does not support mapping files from a compiler because of this format. Therefore, it is required to do some pre-processing to create a new .map/.txt file for the symbols we required for generation of the .a2l file. Which in turn reduces the size of the mapping/symbols file.
Create a new .map/.txt file called formattedOutput and open in a text editor. Then using the Ctrl+F shortcut on the generated output.map file, we can locate our symbol parameters for Param1 and Param2 as shown below:
As shown here, the output.map file displays the characteristics with a different symbol to that created by RTE in the McSupportData. To solve this, copy the memory address of each characteristic/measurement and input the correct symbol name in our new .map/.txt file:
0x0047b3d1 Param1 0x0047b3e7 Param2
RTA-A2L basic use-case #1
Now we have processed these files correctly here is the command that will take them and generate an .a2l file output:
rtaa2l --template [templateFileName].a2la --mcsd [mcsdFileName].arxml --symbols [symbolMapFileName].map --out [a2lFileName].a2l
When using the tool, it is possible to include multiple mcsd files for generating the .a2l file. However, it is imperative that neither file use the same symbol for a characteristic/measurement as this will cause errors further along the project timeline when the addresses are instantiated. Should a characteristic/measurement not include a corresponding symbol to the .map file it will be instantiated with the address zero 0x000000 and continue processing the rest of the contents. It should be noted that RTA-A2L does not issue a warning when this occurs. Upon running the command above, the results should resemble the following:
PS C:\> rtaa2l --template .\template.a2la --mcsd .\Rte_McSupportData.arxml --symbols .\test.map --out .\final.a2l I000001: This is rtaa2l.exe, version 7.5.3. Copyright (C) ETAS Group 2013-2022 I000009: Reading '.\template.a2la' I000009: Reading '.\Rte_McSupportData.arxml' I000018: Found Characteristic 'Param1' I000018: Found Characteristic 'Param2' I000020: Seen processing instruction '<?emitA2L?>' I000009: Reading '.\test.map' I000019: Writing to '.\final.a2l'
RTA-A2L basic use-case #2
As mentioned, there are two other basic use-cases for RTA-A2L, the first being the translation of a MCSD file to an .a2l file without address instantiation. This is to be used when a .map file is not present resulting in the addresses for all characteristics/measurements to be zero 0x000000. In the example below of running the same command minus the symbols parameter it is shown in the output of the .a2l file.
rtaa2l --template [templateFileName].a2la --mcsd [mcsdFileName].arxml --out [a2lFileName].a2l
PS C:\> rtaa2l --template .\template.a2la --mcsd .\Rte_McSupportData.arxml --out .\final.a2l I000001: This is rtaa2l.exe, version 7.5.3. Copyright (C) ETAS Group 2013-2022 I000009: Reading '.\template.a2la' I000009: Reading '.\Rte_McSupportData.arxml' I000018: Found Characteristic 'Param1' I000018: Found Characteristic 'Param2' I000020: Seen processing instruction '<?emitA2L?>' I000019: Writing to '.\final.a2l'
RTA-A2L basic use-case #3
The third basic use-case is for the modification of a pre-existing .a2l file, which is passed to the RTA-A2L tool alongside a .map file. This allows for the re-instantiation of memory addresses, and for note only one .a2l file can be rewritten in a single execution and therefore the “--a2l” option parameter can be supplied only once. The RTA-A2L tool overwrites all characteristics and measurements named in the .map file regardless of whether they had been instantiated previously, and any unnamed characteristic or measurements are passed through untouched. Again, for note, RTA-A2L does not issue any warnings for unmatched or unused symbols. Below is the command and output results:
rtaa2l --a2l[OLDa2lFileName].a2l --symbols [symbolMapFileName].map --out [NEWa2lFileName].a2l
PS C:\> rtaa2l --a2l .\final.a2l --symbols .\test.map --out .\final2.a2l I000001: This is rtaa2l.exe, version 7.5.3. Copyright (C) ETAS Group 2013-2022 I000009: Reading '.\final.a2l' I000009: Reading '.\test.map' I000019: Writing to '.\final2.a2l'