Introduction

Scope

This application note describes the functional background of the E2E module and COM Callout method used for communication protection. As well as providing a workflow guide to implement E2E within an existing project. In the context of this application note, the existing project to be used will be the 9.2.1 Standard Starter Kit. Though it will not include the already present E2E Wrapper method (therefore, this requires removing before continuing with this AN)

Definitions & Abbreviations

AR: AUTOSAR

BSW: AUTOSAR Basic Software / Hardware independent service layer

RTE: AUTOSAR Real Time Environment

OS: AUTOSAR Operating System

AN: Application Note

SK: Starter Kit

E2E: End2End Communication Protection

CRC: Cyclic Redundancy Check

PDU: Protocol Data Unit

SWC: Software Component

Tool-chain

It is assumed to complete this AN, the RTA-CAR v9.2.1 tool-chain is in use:

RTA-CAR 9.2.1 tool-chain
ISOLAR-AB	9.2.1
RTA-BSW	6.1.3
RTA-RTE	7.5.3
RTE-OS	6.2.0

Prerequisites

In order to complete this guide, it is assumed the user has a good knowledge of AR methodology and terminology. As well as having the specified tool-chain installed, and access to the VRTA Standard 9.2.1 SK as mentioned.

Functional Overview

By using E2E communication protection mechanisms, the faults in the communication link can be detected and handled at runtime.

E2E Library

The E2E library itself does not handle detected communication errors. It only detects such errors for single received data elements and returns this information to the callers (e.g. SWCs), which have to react appropriately. The E2E Library can be used in different ways, for the purpose of this document the second method will be explored:

E2E Protection Wrapper - Non-standard integrator software to protect data above the RTE layer
COM Call-outs - Non-standard integrator code to protect I-PDUs
Hybrid / Unused
Out-of-box protection at RTE level

E2E COM Call-outs

In this approach, the E2E communication protection protects the data exchange between COM modules. The protection is done at the level of COM's signal groups, which are protected and checked by E2E Library.

For each I-PDU, there is a separate call-out function. Each I-PDU call-out function "knows" if and how each signal group of the I-PDU needs to be protected/checked. This means that the call-out invokes the E2E Library functions with appropriate settings and state parameters. The E2E Library does now "know" signal groups and their settings - entire information is passed as function parameters to E2E library functions.

The call-out invokes the E2E library, once for each E2E-protected signal group in a given I-PDU.

On both receiver and sender sides, if a call-out returns True then COM continues. However, if a COM E2E call-out returns FALSE, then COM stops to process the given I-PDU (in the current cycle).

In case the COM call-out is used, the serialisation is done by the communication stack (RTE, COM), so the call-out operates directly on the serialised signal groups in the I-PDU. The diagram below summarises the COM E2E call-out solution on the sender side:

The diagram below summarises the COM E2E call-out solution on the receiver side. The very important step is that the E2E Library overwrites the CRC byte in the signal group by check status bits (E2E_PXXCheckStateType). Then, this overwritten CRC byte is converted by COM to signals and then by RTE to data elements. As a result, the SWC receives in the CRC data element, the E2E check bits, and not the CRC value.

Methodology of usage of E2E library

The steps needed to use the E2E Library are:

The user selects the architectural approach of how the E2E Library is to be used in a given system (through COM call-outs / through E2E protection wrapper etc.).
The user selects which data elements or signal groups need to be protected and with which E2E profile.
The user determines the settings for each selected data element or signal group to be protected.
The user generates (or develops) the necessary 'glue' code, responsible for invocation of E2E Library functions.

E2E variants 1A and 1B

Communication protection mechanism has set of E2E profiles. Moreover, some E2E Profiles have standard E2E variants. An E2E variant is simply a set of configuration options to be used with a given E2E Profile.

Within this AN the E2E Profile 1 to protect and check the two signal groups mapped to one I-PDU. The first signal group is protected and checked using variant 1A and the second signal group is protected and checked using variant 1B.

The E2E Profile variant 1A is defined as follows:

CRC is the 0th byte in the signal group (i.e. starts with bit offset 0)
Alive counter is located in the lowest 4 bits of the first byte (i.e. starts with bit offset 8)
E2E_P01DataIDMode = E2E_P01_DATAID_BOTH
SignalIPdu.unusedBitPattern = 0xFF

In the double Data ID configuration (both bytes of Data ID are included in CRC every time) all 16 bits are always included in the CRC calculation.

The E2E Profile variant 1B is defined as follows:

CRC is the 0th byte in the signal group (i.e. starts with bit offset 0)
Alive counter is located in the lowest 4 bits of the first byte (i.e. starts with bit offset 8)
E2E_P01DataIDMode = E2E_P01_DATAID_ALTERNATING
SignalIPdu.unusedBitPattern = 0xFF

In the alternating Data ID configuration, either high byte or low byte of Data ID is put in CRC alternatively, depending of parity or Counter.

Note: In the case of CAN or LIN, the length of the complete data element (including application data, CRC and counter) protected by E2E Profile 1 should not exceed 8 bytes.

For the purpose of this workflow, only the Variant 1B will be used.

Workflow

Workflow Summary

Create new Implementation Data Types
Create new Port Interfaces
Configuration of SWCs
Composition Configuration
Modification & Import DBC file
System Data Mapping
ECUExtract
Configuration Generator
Configuration of CRC CAN Hardware Objects
Configuration of E2E
Configuration of CRC
Configuration of COM Ipdu Callout
Generation of BSW
OsTask Configuration
Generation of RTE
Generation of OS
ASW Code Implementation
Com Code Implementation
Build MCAL and Generate VRTA Project
Testing with Busmaster

ASW Configuration

Implementation Data Types

To begin, open the Implementation Data Types folder from the AR Explorer using the Data Dictionary Editor:

Create an implementation data types with the category Structure, as shown below, which represent the exchanged data elements with the additional two data elements: CRC (checksum calculation) and Counter.

Port Interfaces

According to the specification, in case the E2E Library is used to protect data elements, the the use of E2E Library shall use the Sender-Receiver communication model for safety-related communication. Therefore, open the Interface folder within the AR Explorer using the Data Dictionary Editor:

Navigate to the Sender Receiver Interface tab (if not already selected), and ensure the default Package and File are set accordingly:

Create two new port SR Interfaces, setting their SR ShortNames and VDP type references as follows:

SWC Configuration

Following the creation of these new port interface, the next step is to configure it to a SWC so that it maybe used in the transmission of E2E data. Navigate to the MasterSWC located under Software → Components and open it with the Component Editor as shown:

Create a PPort using the Interface: E2E_Interface naming it accordingly:

Following this, create a RPort for the same Interface, naming accordingly:

Navigate to the Functions tab to create the Runnable linking to the ports created.

Following the creation of the Runnable, navigate to the Events tab. Following the instructions below, create a DataReceivedEvent with the Data Element E2E_DataElement:

Navigating back to the Functions tab, here the created Runnable require the Data Access Points (DAP) which will provide the parameters to be passed through these functions. This project will utilise the RE_RunTest for testing the Transmission of a protected message through passing a test-code to trigger the output. Therefore, within RE_RunTest add the DAPs from DataSendPoints from PPort_E2E. Then for RE_E2E_Rx set the DAPs from DataReceivePointsByArguments from RPort_E2E as shown below.

Once the MasterSWC has been configured, the same is required to be done for the TesterSWC as this will act as our bridge to communicate and test this project for E2E. The steps to follow for TesterSWC:

Create PPort & RPort
Create Runnables (RE_E2E_Tx & RE_E2E_Rx)
Create TimingEvents for each runnable with timing period 0.1
Assign DAPs to each runnable

Composition Configuration

Now both SWCs have been configured, their ports require connecting within the TopLevelComposition. To do so, open the composition (found under Software → Compositions) using the Composition Editor:

Navigating to the Manual Connection Editor Tab, select the CPT_MasterSWC and CPT_TesterSWC as the source and target components. Here manually connect the following ports as shown below:

CPT_MasterSWC ↔ CPT_TesterSWC
PPort_E2E	RPort_E2E
RPort_E2E	PPort_E2E

System Configuration

DBC File Import

Once all ASW elements have been configured, the pre-imported DBC file needs to be modified to accommodate these changes. The information below addresses the CAN frames and their signals. This information can be simply appended to the current DBC import file found under System_config within the project, above predefined CAN frames.

Modification of DBC

BO_ 4 Protected_Msg_Tx: 8 ApplicationECU
 SG_ CRC_E2E_Tx : 0|8@1+ (1,0) [0|0] ""  TestECU
 SG_ Counter_E2E_Tx : 8|4@1+ (1,0) [0|15] ""  TestECU
 SG_ Data_E2E_Tx : 16|16@1+ (1,0) [0|0] ""  TestECU

BO_ 5 Protected_Msg_Rx: 8 TestECU  
 SG_ CRC_E2E_Rx : 0|8@1+ (1,0) [0|0] ""  ApplicationECU
 SG_ Counter_E2E_Rx : 8|4@1+ (1,0) [0|15] ""  ApplicationECU
 SG_ Data_E2E_Rx : 16|16@1+ (1,0) [0|0] ""  ApplicationECU

SIG_GROUP_ 4 Signal_Group_E2E_Tx 1 :  Data_E2E_Tx CRC_E2E_Tx Counter_E2E_Tx;
SIG_GROUP_ 5 Signal_Group_E2E_Rx 1 :  Counter_E2E_Rx CRC_E2E_Rx Data_E2E_Rx;

Once the modifications are complete, ensure that all tabs within the ISOLAR-AB workspace are closed before selecting the project and DBC Importer tool:

Select only the ApplicationECU and its CAN frames before clicking Finish. As this will generate all the necessary signals within the System information for when it comes to generating the ECU framework. Upon completing this step, ISOLAR-AB will prompt the user to compare the changes, due to re-importing information alongside new information. Simply close this tab and decline the generation of a report.

System Data Mapping

Once imported, navigate to System → System Info and open System using the System Data Mapping Editor, where these new signals will be mapped to the correct interface.

Scroll down to the MasterSWC where the Ports created can be located, and then map the signal group and signals to the Data Element accordingly:

ECU Configuration

ECUExtract

Once System Data Mapping has been completed, the project requires an ECU extract to form the structure of the ECU Configurator. Done by right-clicking the 'System' container within System Info and select Create ECU Extract:

Uncheck Ignore compspec conflicts and also Update existing ECUExtract. Then click Finish:

Configuration Generator

Once the ECU Extract has been generated, execute the Configuration Generator for the ECU, selecting the RTA-BSW v6.1.3:

Configuration of CAN Hardware Objects

Open the CAN module using the BSW Editor by double-clicking on the module itself from within the ECU Navigator → Bsw Modules → COM Stack → CAN Modules:

Within this editor, set the CanHwFilter's of the CanHardwareObjects: Can_Network_CANNODE_0_Rx_Std_MailBox_7 (Referenced within CanIf to the Protected_Msg_Rx) to 5, 2047 and Can_Network_CANNODE_0_Tx_Std_MailBox_6 (Referenced within CanIf to the Protected_Msg_Tx) to 4, 2001. As shown below:

Configuration of E2E

As the E2E module was removed for the purpose of implementing a alternative method, create the module by right-clicking on Bsw Modules and selecting E2E under Create Other Modules:

BSW Editor should open automatically, configure the General attributes as follow:

Set the E2ERbCrcManualDefinitions attributes E2ERbCrc8FirstCall to true, and E2ERbCrc8ManualValues to x00:

Configuration of CRC

Once the E2E module has been configured, navigate the ECU Configurator to the CRC module under BSW Modules → Services. Open this module using the BSW Editor:

Set the values of the CrcGeneral attributes as follows:

Configuration of COM IPDU Callouts

Navigate the ECU Configurator, to open the COM module in BSW Editor under: Bsw Modules → COM Stack → COM. And open by double-clicking the module:

Under ComIPdus configure the IP_Protected_Msg_Rx_Can_Network_Channel_CAN_Rx and IP_Protected_Msg_Rx_Can_Network_Channel_CAN_Tx as follows below. As well as assigning the ComCallout

Ensure that the COM Signal Groups have been mapped correctly, with their corresponding signals and system signal references. This should be handled by the configuration generator, though is best to check as these are vital to this projects success.

RTA-BSW Generation

Following the configurations necessary for E2E within this project, it is time to generate the code for the BSW layer. Open the RTA Code Generator Dialog as shown below:

The following should appear, select RTA-BSW v6.1.3 under tools and then select E2E within the Modules fields (found under RTA-SAFE). Then click Apply and then Run:

OsTask Configuration

After RTA-BSW has generated correctly, OsTasks configuration is required before generating RTA-RTE and RTA-OS. Navigate the ECU Configurator and open EcucValueCollection with RTE Mapping Editor, located under Bsw Modules → Ecuc Value Collections:

Map the MasterSWC runnables created earlier to OsTask_ASW as shown below:

RTA-RTE Generation

Open the RTA Code Generator Dialog using the same method for RTA-BSW and then using the code block below, apply it to the RTE Command:

--strict-unconnected-rport-check=off --os-define-osenv=RTAOS40 --notimestamps --samples=memmap --os-output-param=changed

RTA-OS Generation

Finally, generate RTA-OS using the RTA Code Generator Dialog:

Code Implementation

ASW Code Implementation

Within "MasterSWC.c" in the ASW Src project folder, AppDataElVal_Tx_E2E and AppDataElVal_Rx_E2E are to be defined using the configured structure E2E_Structure. As well as, the test codes for checking the transmission and reception works:

/*Define test codes for testing */
#define TEST_E2E_Tx			0x21u
#define TEST_E2E_Rx			0x22u 

---------------------------------------------------

/*Assign the data structure E2E_Structure to a variable, and construct them to be used in testing */
static E2E_Structure AppDataElVal_Tx_E2E;
static E2E_Structure *AppDataEl_Tx_E2E = &AppDataElVal_Tx_E2E;
static E2E_Structure AppDataElVal_Rx_E2E;
static E2E_Structure *AppDataEl_Rx_E2E = &AppDataElVal_Rx_E2E;

Then within the RE_RunTest runnable function, implement the test code for transmission of E2E protected messages:

/*
    E2E Transmission Test - check that the E2E module can send a protected message. 
*/
{
	if(testCode == TEST_E2E_Tx)
    {
		/* Define variables to be used, including 'i' as counter */
        uint32 retRteWrite_E2E;
        static uint8 i = 0;

		/* Increment 'i' and assign the data structure variables based off it */
        i++;
        AppDataEl_Tx_E2E->CRC = 0;
        AppDataEl_Tx_E2E->Data = 4*i;

		/*Write to the protected message to tester ECU, triggering the COM Callout associated */
        retRteWrite_E2E = Rte_Write_PPort_E2E_E2E_DataElement(AppDataEl_Tx_E2E);

		/* If retRteWrite_E2E is written back as true, meaning the message is protected and handled correctly. */
        if(retRteWrite_E2E == RTE_E_OK)
		{
			/* Write the test code back to Tester ECU and similarly to other tests, clear the second byte. */
			Rte_Write_PPort_TestResult_TestResult(TEST_E2E_Tx);
            Rte_Write_PPort_TestResult_Data_TestResult_Data(0x00)
		}
	}
}

Then implement the new runnable function RE_E2E_Rx_func for testing that the reception of E2E protected messages are handled correctly:

/*
E2E Recieve Communication Test - check that the E2E module handles incoming protected messages correctly
This function is only triggered when data has been sent to the respected port.
*/
FUNC(void, MasterSWC_CODE) RE_E2E_Rx_func(void)
{
	/* Define standard return type as true (i.e. RTE_E_OK) */
	Std_ReturnType retRteRead_E2E = RTE_E_OK;
	/* Read the data being passed in, which will trigger the COM callout for receiving protected messages from E2E */
    retRteRead_E2E = Rte_Read_RPort_E2E_E2E_DataElement(AppDataEl_Rx_E2E);

	/* If the check result is still true, the following will happen */
    if(retRteRead_E2E == RTE_E_OK)
    {
		/* Write the test code back to Tester ECU and similarly to other tests, clear the second byte. */ 
        Rte_Write_PPort_TestResult_TestResult(TEST_E2E_Rx);
        Rte_Write_PPort_TestResult_Data_TestResult_Data(0x00);
    }
}

COM Code Implementation

Once the implementation of the runnables & tests within MasterSWC.c, navigate to the Com_Integration.c file located under bsw → Com → Integration. Then within the header of the file include these header files, as well as the data structure and values for the E2E config that will be used within our COM callouts:

#include "Com_Cbk.h"
#include "E2E_P01.h"

---------------------------------------------------

static const E2E_P01ConfigType Config_E2E =
{ 8, /* CounterOffset */
  0, /* CRCOffset */
  64000, /* DataID, 2 bytes */
  12, /* DataIDNibbleOffset */
  E2E_P01_DATAID_ALT, /* DataIDMode */
  32, /* DataLength */
  1, /* MaxDeltaCounterInit */
  2, /* MaxNoNewOrRepeatedData */
  2, /* SyncCounterInit */
};

Following this, implement the below code which will check a protected message before transmitting it from the ApplicationECU:

FUNC(boolean,COM_CODE) IPDU_Protect_2001(VAR(PduIdType, AUTOMATIC) id, P2VAR(PduInfoType, AUTOMATIC, COM_APPL_DATA) ptr)
{
  static E2E_P01ProtectStateType Protectstate_E2E = {0}; /*Counter to be used for protecting the next Data.*/
  Std_ReturnType retE2EProtect_E2E = RTE_E_OK;
  boolean retval;  
  
  /* The callout invokes the E2E Library, once for each E2E-protected signal group in a given I-PDU.*/
  retE2EProtect_E2E = E2E_P01Protect(&Config_E2E, &Protectstate_E2E, ptr->SduDataPtr+4);

  /* return TRUE if no error in protect functions */
  return (retE2EProtect_E2E == RTE_E_OK ) ? TRUE : FALSE;
}

Second to this, implement the following function which will check incoming protected messages and passing back a true / false value to confirm its integrity:

/*The callout function is generated to protect the signal groups of one I-PDU and
  simply invokes the E2E Library (once per each E2E-protected signal group)*/
  
FUNC(boolean,COM_CODE) IPDU_Protect_2002(VAR(PduIdType, AUTOMATIC) id, P2CONST(PduInfoType, AUTOMATIC, COM_APPL_CONST) ptr)
{
  static E2E_P01CheckStateType Checkstate_E2E = {0,0,TRUE,FALSE,0,E2E_P01STATUS_NONEWDATA,0,0};
  Std_ReturnType retE2ECheck_E2E = RTE_E_OK;
  boolean retval = FALSE;

  /* If callout is invoked, this means that new data is available at COM.*/
  Checkstate_E2E.NewDataAvailable = TRUE ;
  
  /* The callout invokes the E2E Library, once for each E2E-protected signal group in a given I-PDU.*/
  retE2ECheck_E2E = E2E_P01Check(&Config_E2E, &Checkstate_E2E, ptr->SduDataPtr+4);
  
  /* The callout copies the status into the CRC byte, so that it can be analyzed, if needed, by receiver SW-C.*/
  *(ptr->SduDataPtr+4) = Checkstate_E2E.Status;

  /* return TRUE if no error, possibly only some messages lost Within counter tolerance */
  if( retE2ECheck_E2E == RTE_E_OK && ((Checkstate_E2E.Status == E2E_P01STATUS_OK) || (Checkstate_E2E.Status == E2E_P01STATUS_OKSOMELOST)) )
  {  
    retval = TRUE;
  }
  
	return retval;
}

MCAL & VRTA Build

MCAL Build

Now that the project is completed, the final step before testing this build with BusMaster is to re-generate the MCAL. To do this, run the 01_mcal.bat which can be found under the Build folder in the SK. This may differ from another project structure the user is using.

VRTA Build

Once the MCAL has been built successfully, execute the 02_build.bat located in the same folder as the MCAL build file. Reminder: Process may differ from those used by users organisation.

Testing

Once having built the project, an executable is created into the sub-directory Build → output named RTA-SK-VRTA.exe. Double click on this file to execute it; the VRTA will open and begin the virtualisation of the project within the application. Ensure, that the runLoopback.bat is running also, as this will allow us to communicate with the virtualised ECU.

Now that both programs are running open BusMaster. Setting the Driver Selection to ETAS BOA:

A Hardware Selection prompt window should appear, here select any CAN hardware (except ETAS://ETH/ES523:VLoopBack/CAN:1) and move to Configured CAN Hardware and click Ok:

Then click connect, and the following should appear in the Message Window:

Now that we are connected, within the Simulation Windows tab, select the Transmit Window. A dialog window should appear, within this window enter a message with the ID 0x14 which be used for testing the Transmission of Protected Messages. Then assign to the 1st byte (00) the test code value 0x21.

This should output a protected message from the ECU as well as writing back the test code.

Following onto testing the reception of a protected message, follow the same guide but this time create a message with the ID 0x05 and input a protected message to send. Should it be successful, it should output the test code 0x22. Before sending the protected message shown below, send the message E6:F1:00:10 as this will initialise the COM callout, so that the next message is the message we want.

RTA Knowledge Base

Contents

Introduction

Scope

Definitions & Abbreviations

Tool-chain

Prerequisites

Functional Overview

E2E Library

E2E COM Call-outs

Methodology of usage of E2E library

E2E variants 1A and 1B

Workflow

Workflow Summary

ASW Configuration

Implementation Data Types

Port Interfaces

SWC Configuration

Composition Configuration

System Configuration

DBC File Import

System Data Mapping

ECU Configuration

ECUExtract

Configuration Generator

Configuration of CAN Hardware Objects

Configuration of E2E

Configuration of CRC

Configuration of COM IPDU Callouts

RTA-BSW Generation

OsTask Configuration

RTA-RTE Generation

RTA-OS Generation

Code Implementation

ASW Code Implementation

COM Code Implementation

MCAL & VRTA Build

MCAL Build

VRTA Build

Testing

RTA Knowledge Base

Configuring E2E COM Callouts

Contents

Introduction

Scope

Definitions & Abbreviations

Tool-chain

Prerequisites

Functional Overview

E2E Library

E2E COM Call-outs

Methodology of usage of E2E library

E2E variants 1A and 1B

Workflow

Workflow Summary

ASW Configuration

Implementation Data Types

Port Interfaces

SWC Configuration

Composition Configuration

System Configuration

DBC File Import

System Data Mapping

ECU Configuration

ECUExtract

Configuration Generator

Configuration of CAN Hardware Objects

Configuration of E2E

Configuration of CRC

Configuration of COM IPDU Callouts

RTA-BSW Generation

OsTask Configuration

RTA-RTE Generation

RTA-OS Generation

Code Implementation

ASW Code Implementation

COM Code Implementation

MCAL & VRTA Build

MCAL Build

VRTA Build

Testing