xcp protocol ecu software (xcp starter kit part 2) v1.0 · 02/06/2010 · the xcp ecu software is...

XCP Protocol ECU Software (XCP Starter Kit Part 2) v1.0.5 User Guide

2

Copyright

The data in this document may not be altered or amended without special notification from ETAS

GmbH. ETAS GmbH undertakes no further obligation in relation to this document. The software described in it can only be used if the customer is in possession of a general license agreement or

single license. Using and copying is only allowed in concurrence with the specifications stipulated in

the contract.

Under no circumstances may any part of this document be copied, reproduced, transmitted, stored in a retrieval system or translated into another language without the express written permission of

ETAS GmbH.

© Copyright 2009 ETAS GmbH, Stuttgart

The names and designations used in this document are trademarks or brands belonging to the

respective owners.

Document 10429UG R1.6.0 EN

Contents 3

Contents

1 Introduction ........................................................................................................................................ 7

1.1 Conventions ................................................................................................................................. 7

1.2 Standards compliance ................................................................................................................... 7

1.3 Bibliography ................................................................................................................................. 7

2 Getting started ..................................................................................................................................... 8

2.1 Installed components .................................................................................................................... 8

2.2 Prerequisites ................................................................................................................................ 8

2.3 Supported targets ......................................................................................................................... 8

2.4 Supported transport layers ............................................................................................................ 8

2.5 XCP ECU software usage ............................................................................................................... 9

2.6 Integrating the XCP ECU software into an ECU application ............................................................... 9

3 Tutorial: adding XCP to an ECU application ........................................................................................... 10

3.1 Basic XCP communication ............................................................................................................ 10

3.1.1 XCP API calls ................................................................................................................... 10 3.1.2 XCP callbacks ................................................................................................................... 10 3.1.3 CAN configuration ............................................................................................................ 10 3.1.4 CAN APIs and callbacks .................................................................................................... 11 3.1.5 ECU build process ............................................................................................................ 11 3.1.6 ECU ASAP2 file ................................................................................................................. 11 3.1.7 Try it out ......................................................................................................................... 12

3.2 Adding measurement .................................................................................................................. 12

3.2.1 Review the DAQ list configuration ...................................................................................... 12 3.2.2 XCP API calls ................................................................................................................... 13 3.2.3 Create an XCP timestamp counter...................................................................................... 13 3.2.4 CAN configuration ............................................................................................................ 13 3.2.5 ECU ASAP2 file ................................................................................................................. 13 3.2.6 Try it out ......................................................................................................................... 13

3.3 Adding calibration ....................................................................................................................... 13

3.3.1 XCP callbacks ................................................................................................................... 14 3.3.2 ECU ASAP2 file ................................................................................................................. 14 3.3.3 Try it out ......................................................................................................................... 15

3.4 Adding seed and key .................................................................................................................. 15

4 Contents

3.4.1 Seed and key DLL ............................................................................................................ 15 3.4.2 XCP callbacks ................................................................................................................... 15 3.4.3 Try it out ......................................................................................................................... 16

3.5 Adding RESUME mode ................................................................................................................ 16

3.5.1 Review the DAQ list configuration ...................................................................................... 16 3.5.2 Allocate a region of non-volatile RAM ................................................................................. 16 3.5.3 XCP callbacks ................................................................................................................... 16 3.5.4 Review the use of Xcp_Initialize() ...................................................................................... 16 3.5.5 Try it out ......................................................................................................................... 16

3.6 Adding bypass ............................................................................................................................ 16

3.6.1 Review the DAQ list configuration ...................................................................................... 17 3.6.2 XCP API calls ................................................................................................................... 17 3.6.3 CAN configuration ............................................................................................................ 17 3.6.4 ECU ASAP2 file ................................................................................................................. 17 3.6.5 Try it out ......................................................................................................................... 17

3.7 Adapting the tutorial to support XCP-on-IP ................................................................................... 18

3.7.1 Review the IP configuration .............................................................................................. 18 3.7.2 IP APIs and callbacks ....................................................................................................... 18 3.7.3 Finding the XCP-on-IP slave from INCA .............................................................................. 18

4 Using the XCP ECU software ............................................................................................................... 19

4.1 The XCP configuration tool .......................................................................................................... 19

4.1.1 Installing Perl................................................................................................................... 19 4.1.2 Using the XCP configuration tool ........................................................................................ 19 4.1.3 The generated A2L fragment ............................................................................................. 19

4.2 Session management .................................................................................................................. 20

4.2.1 Session state and configuration ......................................................................................... 20 4.2.2 Seed and key ................................................................................................................... 20 4.2.3 Initialization ..................................................................................................................... 21 4.2.4 Connection and disconnection ........................................................................................... 21 4.2.5 Command processing ....................................................................................................... 21 4.2.6 Command timeouts .......................................................................................................... 21 4.2.7 CTO packet format ........................................................................................................... 22 4.2.8 User-defined commands ................................................................................................... 22 4.2.9 Memory addressing .......................................................................................................... 22

4.3 Measurement and stimulation ...................................................................................................... 23

4.3.1 DAQ clock ....................................................................................................................... 23 4.3.2 DTO packet format ........................................................................................................... 23 4.3.3 DAQ list features .............................................................................................................. 23 4.3.4 DAQ list configuration ....................................................................................................... 24 4.3.5 Event channels ................................................................................................................ 25 4.3.6 DTO over-filling ................................................................................................................ 26 4.3.7 DAQ list overloading ......................................................................................................... 26 4.3.8 DAQ data consistency ....................................................................................................... 26 4.3.9 Protecting regions of memory from measurement and stimulation ........................................ 27 4.3.10 RESUME mode ................................................................................................................. 27

4.4 Bypassing .................................................................................................................................. 27

4.4.1 Implementing bypass using XCP ........................................................................................ 27 4.4.2 Positioning Xcp_DoStimForEvent() and Xcp_DoDaqForEvent() .............................................. 28 4.4.3 STIM data consistency ...................................................................................................... 29 4.4.4 Handling missing STIM DTOs ............................................................................................ 29 4.4.5 Reasons for missing STIM DTOs ........................................................................................ 30

4.5 Calibration ................................................................................................................................. 31

4.5.1 Configuration ................................................................................................................... 31 4.5.2 Upload and download ....................................................................................................... 31 4.5.3 Calibration page management ........................................................................................... 32 4.5.4 Calibration page freezing .................................................................................................. 32 4.5.5 Checksums ...................................................................................................................... 33 4.5.6 Asynchronous calibration callbacks .................................................................................... 33

4.6 Flash programming ..................................................................................................................... 33

4.7 CAN transport layer .................................................................................................................... 34

Contents 5

4.7.1 Interaction with the CAN driver ......................................................................................... 34 4.7.2 Configuration ................................................................................................................... 35 4.7.3 XCP commands ................................................................................................................ 36

4.8 IP transport layer ....................................................................................................................... 36

4.8.1 Interaction with the IP driver ............................................................................................ 36 4.8.2 Configuration ................................................................................................................... 38 4.8.3 XCP commands ................................................................................................................ 38

5 Reference .......................................................................................................................................... 39

5.1 XML configuration file ................................................................................................................. 39

5.2 Types defined by the XCP ECU software ....................................................................................... 39

5.3 APIs provided by the XCP ECU software ....................................................................................... 40

5.4 APIs provided by the CAN transport layer ..................................................................................... 42

5.5 APIs provided by the IP transport layer ........................................................................................ 44

5.6 APIs required by the XCP ECU software ........................................................................................ 45

5.6.1 General functions ............................................................................................................. 45 5.6.2 Calibration page switching functions .................................................................................. 46 5.6.3 Memory access functions .................................................................................................. 49 5.6.4 Measurement functions ..................................................................................................... 52 5.6.5 Non-volatile memory functions .......................................................................................... 53 5.6.6 Seed and key functions ..................................................................................................... 55 5.6.7 Flashing functions ............................................................................................................ 56 5.6.8 CAN functions .................................................................................................................. 59 5.6.9 IP functions ..................................................................................................................... 60

5.7 Integrating the XCP ECU software into an ECU application ............................................................. 60

5.7.1 Overview ......................................................................................................................... 60 5.7.2 Software environment ...................................................................................................... 60 5.7.3 XCP ECU software header files .......................................................................................... 61 5.7.4 Building the XCP ECU software .......................................................................................... 61

5.8 Optimising the resource usage of the XCP ECU software ................................................................ 62

5.8.1 Optimising DTO layout ...................................................................................................... 62 5.8.2 Optimising storage of ODT entry properties ........................................................................ 62 5.8.3 Removing unnecessary configuration ................................................................................. 64 5.8.4 Removing unnecessary functionality................................................................................... 64 5.8.5 Optimisation parameters ................................................................................................... 64

6 Porting the XCP ECU software ............................................................................................................. 66

6.1 Porting process .......................................................................................................................... 66

6.2 PORTNOTE items in xcp_target.h ................................................................................................. 66

6.2.1 XCP_PACK() ..................................................................................................................... 66 6.2.2 XCP_CONFIG_TYPE .......................................................................................................... 66 6.2.3 XCP_STATE_TYPE ............................................................................................................ 66 6.2.4 XCP_FN_TYPE .................................................................................................................. 66 6.2.5 XCP_ENABLE_ALL_INTERRUPTS and XCP_DISABLE_ALL_INTERRUPTS ................................. 67 6.2.6 sizeof_XXX macros ........................................................................................................... 67 6.2.7 Storing ODT entry properties ............................................................................................. 67 6.2.8 uintn and sintn................................................................................................................. 67 6.2.9 Xcp_CfgPtrn and Xcp_StatePtrn ......................................................................................... 68 6.2.10 Other type definitions ....................................................................................................... 68

6.3 PORTNOTE items in xcp_target.c ................................................................................................. 68

6.3.1 Xcp_MemCopy()............................................................................................................... 68 6.3.2 Xcp_MemZero() ............................................................................................................... 68 6.3.3 Xcp_CheckCanId()............................................................................................................ 68

7 Integration with Visu-IT ASAP2 editor .................................................................................................. 69

7.1 Creating a new ECU project ......................................................................................................... 69

7.2 Configuring XCP memory layout in an existing ECU project ............................................................. 69

7.2.1 Memory layout entity for program code .............................................................................. 69 7.2.2 Memory layout entity for calibration data (2-page calibration concept) .................................. 70 7.2.3 Memory layout entity for calibration data (single-page calibration concept) ........................... 70

6 Contents

7.3 Configuring the XCP global settings .............................................................................................. 71

7.4 Configuring measurement values ................................................................................................. 71

8 Integration with ETAS INCA ................................................................................................................ 73

8.1 Seed and key DLL ....................................................................................................................... 73

8.2 Integration into an INCA A2L file ................................................................................................. 73

8.3 Correspondence between XCP configuration and INCA concepts ..................................................... 75

8.3.1 Seed and key ................................................................................................................... 75 8.3.2 INCA’s variable selection dialog ......................................................................................... 75 8.3.3 Fast start mode ................................................................................................................ 76

8.4 Limitations of INCA ..................................................................................................................... 76

8.4.1 CAN message IDs for dynamic DAQ list DTO packets ........................................................... 76 8.4.2 The association between a static DAQ list and an event channel ........................................... 76

9 Integration with ETAS INTECRIO ......................................................................................................... 77

9.1 Integration into an INTECRIO A2L file .......................................................................................... 77

9.2 Using XCP RESUME mode ............................................................................................................ 77

9.3 Known issues and hints on usage ................................................................................................. 77

10 Appendix: Unsupported XCP features ................................................................................................... 78

11 Appendix: Notes on supported targets ................................................................................................. 79

11.1 PC / Visual Studio 2005 ............................................................................................................... 79

11.2 Tasking / Tricore ........................................................................................................................ 79

11.3 Metrowerks / HCS12X ................................................................................................................. 79

11.4 Tasking / XC164 ......................................................................................................................... 79

11.5 Diab / MPC55xx .......................................................................................................................... 79

12 Appendix: Installing Perl ..................................................................................................................... 80

12.1 Perl requirements ....................................................................................................................... 80

12.2 Using the supplied Perl installation ............................................................................................... 80

12.3 Modifying an existing Perl installation ........................................................................................... 80

13 Appendix: ETAS Contact Addresses ...................................................................................................... 81

Introduction 7

1 Introduction

The ETAS XCP starter kit consists of the following components:

1. The ASAP2 editor provided by ETAS’s partner Visu-IT (see http://www.visu-

it.de/ASAP2_Editor/ASAP2_Editor.php).

2. The software which implements the XCP protocol on an ECU.

3. Engineering services provided by ETAS.

This document is a user guide for part 2, i.e. the XCP protocol ECU software. As well as material

traditionally found in a user guide it also contains:

reference information about the XCP ECU software;

porting guidelines for the XCP ECU software.

This document assumes that the reader has a basic understanding of measurement and calibration

concepts and is familiar with the contents of v1.0 of the ASAM XCP standard.

1.1 Conventions

The following typographical conventions are used in this document:

Choose File Open. Menu commands are shown in

boldface.

Click OK. Buttons are shown in boldface.

Press <ENTER>. Keyboard commands are shown in

angled brackets.

The "Open File" dialog box is dis-

played.

Names of program windows, dialog

boxes, fields, etc. are shown in

quotation marks.

Select the file setup.exe Text in drop-down lists on the

screen, program code, as well as

path- and file names are shown in

the Courier font.

A distribution is always a one-

dimensional table of sample points.

General emphasis and new terms

are set in italics.

1.2 Standards compliance

The XCP ECU software is compliant with v1.0 of the ASAM XCP standard, with a few exceptions which

are listed in section 10.

1.3 Bibliography

The following documents provide useful extra information and background.

ASAM XCP standard v1.0, available from www.asam.net, and also installed with the XCP ECU

software.

ASAM ASAP2 standard v1.51 (or later), available from www.asam.net.

Licence and Disclaimer

The XCP ECU software is covered by a licence and disclaimer document which is installed with the software package.

http://www.visu-it.de/ASAP2_Editor/ASAP2_Editor.php

http://www.visu-it.de/ASAP2_Editor/ASAP2_Editor.php

http://www.asam.net/

http://www.asam.net/

8 Getting started

2 Getting started

2.1 Installed components

The following components are installed with the XCP ECU software:

a configuration tool, implemented as a set of Perl scripts;

the source code for the XCP ECU software itself, to be used in an ECU application;

the source code for a CAN transport layer to be used with the XCP ECU software.

the source code for an IP transport layer to be used with the XCP ECU software.

The XCP ECU software code which is installed does not, by itself, form a complete XCP slave driver

implementation. Instead it also requires additional code which is generated by the configuration tool

and additional callbacks which are implemented by the user.

2.2 Prerequisites

The XCP configuration tool is implemented as a set of Perl scripts, and therefore Perl will need to be

installed on the user’s PC before the tool can be used. In addition, the user will need to install the

following Perl packages which are not commonly distributed with Perl:

XML::LibXML::Common

XML::LibXML (at least v1.66)

XML::Simple

Section 12 discusses how the required packages, and Perl itself, can be obtained if they are not

already available on the user’s PC.

2.3 Supported targets

This release of the XCP ECU software supports the following target platforms and toolchains:

Platform Toolchain Notes

PC Visual Studio 2005

(any edition)

This target was used for initial development and testing of the

XCP ECU software. In addition it could be used with ETAS “RTA-

OSEK for PC”.

Tricore Tasking This target was developed and tested using version 2.2.r3 (build

134.1.4) of the Tasking toolchain and a Tricore 1796 ECU

(revision AB). In practice it is likely also to work with other versions of the Tasking software or other Tricore ECUs.

HCS12X Metrowerks /

Freescale

This target was developed using version 5.0.38 of the

Metrowerks compiler and version 5.0.36 of the Metrowerks

linker. It was tested on a S12XDP512-A HCS12X board. In practice it is likely also to work with other versions of the

Metrowerks software or other HCS12 / HCS12X CPUs.

XC164 Tasking This target was developed and tested using version 2.3.r2 (build 112) of the Tasking C166-VX toolchain and an Infineon

XC164CM-8F40F ECU (as contained in the Infineon U CAN

Starter Kit). In practice it is likely also to work with other

versions of the Tasking software or other XC16x ECUs.

MPC55xx Diab / Wind River This target was developed and tested using version 5.6.1 of the

Diab toolchain and a MPC5554 ECU. In practice it is likely also to

work with other versions of the Diab software or other MPC55xx ECUs.

The user selects a target by building the appropriate set of source files for the XCP ECU software.

Further details on each supported target are contained in section 11.

2.4 Supported transport layers

The XCP ECU software supports both CAN and IP (i.e. TCP/IP and UDP/IP) as transport layers, though

only one can be used within a single ECU application. Although the XCP ECU software implements

rbahekar

Hervorheben

rbahekar

Hervorheben

Getting started 9

these transport layers, it does not implement a CAN driver or an IP driver. The user is expected to

provide a CAN driver or IP driver which will integrate with the XCP ECU software as described in

section 4.7.1 or section 4.8.1.

2.5 XCP ECU software usage

In order to use the XCP ECU software, the user must create an XML file which describes the properties

of the particular XCP implementation. Example XML files are provides in the directory Examples\, and sections 4 and 5.1 of this document describe in detail the various parameters which can be configured

in the file.

The XML file is processed by the XCP configuration tool, which generates the following artefacts:

C source code containing configuration for the XCP ECU software;

an ASAM A2L fragment describing the XCP implementation of each XCP session.

The generated C code, together with the static XCP ECU software code, is compiled into the user’s ECU

application to form a complete XCP slave driver.

If the user is working with an MC or RP tool which understands ASAM A2L, the user can import the generated A2L fragment into their tool or ASAP2 editor. Possible scenarios are discussed in sections 7,

8 and 9.

2.6 Integrating the XCP ECU software into an ECU application

Naturally, the user’s ECU application must make calls into the XCP ECU software at various points. The

following APIs will need to be used:

Xcp_Initialize(), to initialise the XCP ECU software.

Xcp_CmdProcessor(), to allow the XCP ECU software to process XCP commands.

Xcp_DoDaqForEvent(), to allow the XCP ECU software to send DAQ packets to the XCP

master.

Xcp_DoStimForEvent(), to allow the XCP ECU software to apply STIM packets received

from the XCP master to the ECU’s memory.

When using XCP-on-CAN:

XcpCan_RxCallback(), to inform the XCP ECU software that a CAN message has been

received.

XcpCan_TxCallback(), to inform the XCP ECU software that a CAN message has been

transmitted.

When using XCP-on-IP:

XcpIp_RxCallback(), to inform the XCP ECU software that TCP or UDP data has been

received.

XcpIp_TxCallback(), to inform the XCP ECU software that TCP or UDP data has been

transmitted.

XcpIp_OnTcpCxnClosed(), to inform the XCP ECU software that a TCP connection has

been closed.

These API calls are described further in section 5.3, 5.4 and 5.5.

The XCP ECU software is largely target-independent, yet it must interface with target-specific ECU devices, such as a CAN or ethernet controller, and even application-specific structures such as the

calibration memory layout. Therefore the user must implement various callback APIs which are

required by the XCP ECU software in order to allow it to access various areas of functionality within the ECU. These APIs are described in section 5.6. An empty implementation of the various callback APIs is

contained in the file Examples\xcp_callbacks.c.

Note, however, that if a certain area of functionality is not required then the associated callback APIs

do not need to be defined.

rbahekar

Hervorheben

rbahekar

Hervorheben

rbahekar

Hervorheben

10 Tutorial: adding XCP to an ECU application


This tutorial describes how to add a basic XCP implementation to an ECU application. It focuses on

describing the steps which must be taken at each stage, rather than explaining the details of every

XML parameter or API which is used. If the user requires more detailed information about an XML

parameter or an API he is encouraged to refer to the other sections of this document.

The main body of the tutorial uses CAN as a transport layer. If it is necessary to use IP instead, the

user should follow the additional steps in section 3.7.

The tutorial assumes that the microcontroller and compiler used for the ECU application are supported

by the XCP ECU software. If this is not the case it will be necessary to begin by porting the XCP ECU

software to the target platform as described in section 6.

The tutorial also assumes that the microcontroller uses a little-endian architecture. If this is not the

case it will be necessary to edit each XML file which accompanies the tutorial and set the XML

parameter XCP_TARGET_BYTE_ORDER to MSB_FIRST.

Sections 3.1 (“Basic XCP communication”), 3.2 (“Adding measurement”) and 3.5 (“Adding RESUME

mode”) are applicable to both INCA and INTECRIO.

Sections 3.3 (“Adding calibration”), 3.4 (“Adding seed and key”) and 3.7 (“Adapting the tutorial to

support XCP-on-IP”) apply only to INCA.

Section 3.6 (“Adding bypass”) applies only to INTECRIO.

The tutorial does not describe how to access an ECU using both INCA and INTECRIO simultaneously; if

the user wishes to do this, he should read the advice in section 4.2.1.

3.1 Basic XCP communication

The first step of the tutorial describes how to integrate the XCP ECU software into the ECU application

and how to establish basic communication with INCA, if INCA is being used. This step of the tutorial also applies if INTECRIO is being used, but further steps are required before communication can be

established with INTECRIO.

The configuration required for this step is contained in the XML file

Examples/Tutorial/1_basic_comms.xml.

3.1.1 XCP API calls

First it is necessary to decide how frequently the XCP ECU software will be polled in order to allow it to

process XCP commands. The parameter XCP_POLL_INTERVAL in the file 1_basic_comms.xml

specifies a polling period of 10ms, though a different value can be used if necessary.

Once the polling period has been defined a new OS task must be created in the ECU application. This

task must call the API Xcp_CmdProcessor() to allow the XCP ECU software to process XCP

commands. The task must be activated with the chosen polling period, e.g. 10ms for the default configuration. The priority of the task is not critical, but a lower priority is probably best to ensure that

XCP commands do not interrupt the other functions of the ECU application.

The ECU application must also call the API Xcp_Initialize(). This must be done exactly once,

before any XCP communication can take place. A good place to do this is in the startup code which

runs before the OS is started.

All API declarations can all be obtained by including the header xcp.h.

3.1.2 XCP callbacks

The XCP ECU software requires the user to implement a number of callbacks to provide target-specific functionality. The file Examples\xcp_callbacks.c provides sample implementations for some of

these callbacks and empty implementations of the others. “TODO” comments mark where further

implementation or review is required.

Note that xcp_callbacks.c is only intended for use in this tutorial. It contains many limitations and

is not suitable for general use in an XCP slave.

At this stage in the tutorial it is not necessary to add anything to xcp_callbacks.c.

3.1.3 CAN configuration

The XML configuration file which accompanies this step of the tutorial configures the following CAN

message IDs:

rbahekar

Hervorheben

Tutorial: adding XCP to an ECU application 11

ID for messages broadcast by the XCP master = 0x100 (XML parameter

XCPCAN_BROADCAST_MSGID);

ID for messages sent from the XCP master to the ECU = 0x200 (XML parameter

XCPCAN_RX_MSGID);

ID for messages sent from the ECU to the XCP master = 0x300 (XML parameter

XCPCAN_TX_MSGID).

The user must configure the ECU application’s CAN driver to transmit and receive these IDs. The IDs

are available as preprocessor definitions in the header file xcpcan_auto_confpriv.h which is

generated by the XCP ECU software configuration tool. If these message IDs are not suitable the XML

configuration file must be modified to specify alternative IDs.

The XCP ECU software expects that the CAN driver within the ECU application will manage a collection

of hardware buffers, which the XCP ECU software refers to as “CAN message objects”. For this tutorial

the XCP ECU software requires the exclusive use of one of these message objects.

The ID of the CAN message object which is used by the XCP ECU software is specified by the parameter XCPCAN_TX_MSGOBJID in the XML configuration file. The user must modify this parameter

to a value which is appropriate to the CAN driver. If the CAN driver does not have a concept of

“hardware buffers” (or if the CAN driver only manages a single hardware buffer), the user can leave

the value of XCPCAN_TX_MSGOBJID unchanged.

The CAN bus timing configuration is specified by the parameters within the XCP_GLOBALS_CAN

element in the XML configuration file. These parameters must be modified to reflect the configuration

of the CAN controller.

3.1.4 CAN APIs and callbacks

The XCP ECU software expects the CAN driver to implement an API XcpApp_CanTransmit(). This

API is discussed fully in sections 4.7.1 and 5.6.8. The user must read these sections and ensure that

the API XcpApp_CanTransmit() is implemented as expected.

The XCP ECU software also expects the CAN driver to call the XCP API functions

XcpCan_RxCallback() and XcpCan_TxCallback(). These APIs are discussed in sections 4.7.1

and 5.4. The user must read these sections and ensure that the APIs are called as expected.

3.1.5 ECU build process

The XML file which accompanies this step of the tutorial assumes that ETAS ASCET is used to build the

ECU application. If this is not the case the user must modify the value of the XML parameter

XCP_ENVIRONMENT. The possible values of this parameter are discussed in section 5.7.2.

The build process of the ECU application must be adapted to include the following steps:

1. Process the file 1_basic_comms.xml using the configuration tool, as described in section

4.1.

2. Compile the C files generated by the configuration tool: xcp_auto_conf.c and

xcpcan_auto_conf.c.

3. Compile the file Examples\xcp_callbacks.c.

4. Compile the C files which are distributed in the following directories in the XCP ECU software

installation:

XcpDriver\

CanTransport\

TargetSpecific\<target name>, where <target name> corresponds to the target in

use.

3.1.6 ECU ASAP2 file

The user must edit the ECU application’s main A2L file and add the following block within the MODULE

block:


/begin A2ML

/include XCP_v1_0_definitions.aml

block "IF_DATA" taggedunion if_data {

/include XCP_v1_0.aml

};

/end A2ML

/include "if_data_xcp_session0.a2l" /* The generated A2L fragment */

The .aml files required by this block are part of the XCP ECU software installation. They should be

copied to a location from which they can be included into the main A2L file.

3.1.7 Try it out

If INCA is being used, it should now be possible to do the following:

1. Connect the ECU to a PC using ETAS hardware which is suitable for XCP-on-CAN, e.g. an

ES580 PCMCIA card or an ES690 ethernet-to-CAN box.

2. Start INCA.

3. Open a new project, and create a new workspace.

4. Search for hardware and find the XCP-on-CAN hardware device.

5. When prompted, select the project (i.e. A2L file) and working data for the ECU application.

6. Initialize the hardware.

An XCP-on-CAN connection has now been established with the ECU.

Although this step of the tutorial also applies when using the XCP ECU software with INTECRIO,

further steps are needed before communication with INTECRIO can be established.

3.2 Adding measurement

This step of the tutorial describes how to add three static DAQ lists to the XCP-on-CAN

implementation. The DAQ lists will correspond to the 2ms, 10ms and 100ms rasters. This step of the

tutorial applies to both INCA and INTECRIO.

The configuration required for this step of the tutorial is contained in the XML file

Examples/Tutorial/2_measurement.xml. This is based on the file 1_basic_comms.xml, so if

any changes were made to 1_basic_comms.xml as part of the first step of the tutorial the same

changes should also be applied to 2_measurement.xml.

3.2.1 Review the DAQ list configuration

The XML file 2_measurement.xml configures three static DAQ lists, one associated with the 2ms

raster, one associated with the 10ms raster and one associated with the 100ms raster.

The period of a raster can be changed simply by editing its parameters within the corresponding

XCP_EVENT XML element. The period of the raster is controlled by the XCP_EVENT_TIMEUNIT and

XCP_EVENT_TIMECYCLE parameters; the possible values of these parameters are described in section

4.3.5.

Each DAQ list is configured (via the XML parameter XCP_MAX_ODT) to have 5 ODTs. When using CAN,

each ODT (i.e. each CAN message) can hold up to 7 bytes of measurement data. Therefore this

configuration is sufficient to hold 35 bytes of measurement data in each DAQ list (5 ODTs x 7 bytes per ODT), though, if INCA is being used, 4 of those bytes will be reserved for the XCP timestamp. If

more capacity is required the number of ODTs in each DAQ list should be increased. If, on the other

hand, too much RAM is consumed by the XCP ECU software it may be necessary to reduce the number

of ODTs per DAQ list.

Each ODT is configured (via the XML parameter XCP_MAX_ODT_ENTRIES) to have up to 7 ODT

entries. This means that each ODT (i.e. each CAN message) can hold up to 7 distinct measurement

variables, i.e. up to 7 1-byte variables. If most variables contain more than a single byte it is possible

to save RAM by re-configuring each ODT to hold only 3 or 4 ODT entries.

rbahekar

Hervorheben

rbahekar

Hervorheben

rbahekar

Hervorheben

rbahekar

Hervorheben


3.2.2 XCP API calls

The user must decide at which points in the ECU application XCP data acquisition should take place.

Usually the data acquisition for a raster should take place at the end of the corresponding OS task. So, for example, the 2ms raster should be sampled at the end of the 2ms OS task, the 10ms raster at the

end of the 10ms OS task and so on.

The user should place the API call Xcp_DoDaqForEvent() at the appropriate points in the ECU

application. The API call takes the ID of an XCP event (i.e. a raster) as an argument.

3.2.3 Create an XCP timestamp counter

The XML file 2_measurement.xml configures the XCP timestamp with the following parameters:

XCP_TIMESTAMP_SIZE specifies that the timestamp will have 4 bytes.

XCP_TIMESTAMP_UNIT and XCP_TIMESTAMP_TICKS_PER_UNIT specify that the

timestamp will have a period of 1ms.

If the user does not require measurement data to be timestamped he should set XCP_TIMESTAMP_SIZE to 0 and ignore the rest of this section. INTECRIO does not use the XCP

timestamp so users of INTECRIO should do the same.

If the user wants a timestamp with a different period he should modify XCP_TIMESTAMP_UNIT and

XCP_TIMESTAMP_TICKS_PER_UNIT according to the instructions in section 4.3.1.

Next the user must implement the callback XcpApp_GetTimestamp() in the file Examples\xcp_callbacks.c. To do this, he must create a 32-bit counter which increments at the

period chosen for the timestamp. The value of the counter must be returned by

XcpApp_GetTimestamp(). If it is inconvenient to create a 32-bit counter, a 16-bit counter can be used if the XML parameter XCP_TIMESTAMP_SIZE is set to 2. However, the user must take care to

ensure that the counter can run for at least several seconds without wrapping, otherwise INCA may

not be able to report the timestamps correctly.


The XML configuration file which accompanies this step of the tutorial configures a CAN message ID

for each DAQ list using the XML parameter XCPCAN_DAQ_MSGID. The user must configure the ECU

application’s CAN driver to transmit these IDs.

If these message IDs are not suitable the XML configuration file must be modified to specify alternative

IDs.


The user must ensure that the ECU application’s A2L file contains some MEASUREMENT blocks which

describe the measurement variables within the ECU application.

3.2.6 Try it out

Once the steps above have been accomplished successfully it should be possible to do the following to

perform measurement in INCA:

1. Rebuild the ECU application.

2. Start an XCP session with the ECU as described in section 3.1.7.

3. Create a new experiment in INCA. There will be a message box warning that calibration

cannot take place yet.

4. Add some variables to the experiment.

5. Start the experiment and observe the values of the variables.

Alternatively, it should be possible to create a simulation in INTECRIO which uses measurement data acquired from the ECU. INTECRIO’s manuals and online help describe how to create a model which

performs bypass via XCP; a model which uses only measurement data can be constructed in exactly

the same way.

3.3 Adding calibration

This step of the tutorial describes how to add support for calibration to the XCP-on-CAN

implementation. For simplicity, the tutorial describes how to implement single-page calibration since


this does not require the user to write code to manipulate the ECU’s calibration memory. This step of

the tutorial applies only to INCA, not to INTECRIO.


Examples/Tutorial/3_calibration.xml. This is based on the file 2_measurement.xml, so if any changes were made to 2_measurement.xml as part of the second step of the tutorial the same

changes should also be applied to 3_calibration.xml.

3.3.1 XCP callbacks

At this point the user must implement some of the XCP callbacks in the file

Examples\xcp_callbacks.c. Sample implementations are provided for the following callbacks,

which the user should review to confirm their suitability:

XcpApp_ConvertAddress()

XcpApp_CalMemWrite()

XcpApp_CalMemRead()

The callback XcpApp_CalMemGetChecksum() must be implemented completely by the user. It must calculate a checksum over a specified region of memory. It is fully documented in sections 5.6.3 and

4.5.5.


The user must ensure that the ECU’s A2L file contains a MEMORY_SEGMENT block which describes the

program code area, and a MEMORY_SEGMENT block which describes the calibration data area. The

calibration data should be located in RAM, since this tutorial uses single-page calibration.

The user must edit the MEMORY_SEGMENT block which contains the program code and insert the

following block:

/begin IF_DATA XCP

/begin SEGMENT

0x00 /* segment logical number */

0x01 /* number of pages */

0x00 /* address extension */

0x00 /* compression method */

0x00 /* encryption method */

/begin CHECKSUM

<checksum type>

/end CHECKSUM

/begin PAGE

0x00 /* page number */

ECU_ACCESS_WITH_XCP_ONLY

XCP_READ_ACCESS_WITH_ECU_ONLY

XCP_WRITE_ACCESS_NOT_ALLOWED

/end PAGE

/end SEGMENT

/end IF_DATA

The value <checksum type> should correspond to the checksum type implemented by the function

XcpApp_CalMemGetChecksum() (see section 3.3.1) and should be encoded as an integer value as

described in section 4.5.5.


The user must edit the MEMORY_SEGMENT block which contains the calibration data and insert the

following block:

/begin IF_DATA XCP

/begin SEGMENT






/begin CHECKSUM

<checksum type>

/end CHECKSUM

/begin PAGE




XCP_WRITE_ACCESS_WITH_ECU_ONLY

/end PAGE

/end SEGMENT

/end IF_DATA

Once again, the value <checksum type> should correspond to the checksum type implemented by the

function XcpApp_CalMemGetChecksum()(see section 3.3.1) and should be encoded as an integer

value as described in section 4.5.5.

3.3.3 Try it out

Once the steps above have been accomplished successfully it should be possible to rebuild the ECU application, start an XCP session with the ECU as described in section 3.1.7 and perform single-page

calibration operations with INCA.

3.4 Adding seed and key

This step of the tutorial describes how to add support for “seed and key” protection to the XCP-on-CAN

implementation. This step of the tutorial applies only to INCA, not to INTECRIO.


Examples/Tutorial/4_seedkey.xml. This is based on the file 3_calibration.xml, so if any changes were made to 3_calibration.xml as part of the third step of the tutorial the same

changes should also be applied to 4_seedkey.xml.

3.4.1 Seed and key DLL

INCA requires a DLL to allow it to unlock XCP resources which are protected by “seed and key”. When

INCA obtains a “seed” for an XCP resource from the ECU the DLL must be able to provide the

corresponding “key” to allow INCA to unlock the XCP resource.

A sample “seed and key” DLL is installed with the XCP ECU software; it is described in section 8.1. The

user must build the DLL and install it as described in section 8.1.

3.4.2 XCP callbacks

During “seed and key” operations some more of the XCP callbacks in the file Examples\xcp_callbacks.c are used. Sample implementations are provided for the following

callbacks, which the user should review to confirm their suitability:

XcpApp_GetSeed()

XcpApp_GetKeyBuffer()

XcpApp_UnlockResource()


3.4.3 Try it out

Once the steps above have been accomplished successfully it should be possible to run INCA as

described in any of the previous steps of the tutorial. INCA should behave just as previously, but it will

transparently unlock various XCP resources when required.

3.5 Adding RESUME mode

This step of the tutorial describes how to add support for RESUME mode to the DAQ lists defined in

previous tutorial steps. It applies both to INCA and INTECRIO.

If INCA is being used, the configuration required for this step of the tutorial is contained in the XML file

Examples/Tutorial/5_resume_INCA.xml. This is based on the file 4_seedkey.xml, so if any

changes were made to 4_seedkey.xml as part of the fourth step of the tutorial the same changes

should also be applied to 5_resume_INCA.xml.

If INTECRIO is being used, the configuration required for this step of the tutorial is contained in the

XML file Examples/Tutorial/5_resume_INTECRIO.xml. This is based on the file

2_measurement.xml, so if any changes were made to 2_measurement.xml as part of the second

step of the tutorial the same changes should also be applied to 5_resume_INTECRIO.xml.


The XML file which accompanies this step of the tutorial enables RESUME mode for each of the three

DAQ lists introduced in section 3.2.

The user should decide whether RESUME mode is required for all three DAQ lists and set the XML

parameter XCP_DAQ_CANRESUME to no for any DAQ list which will not be RESUMEd.

3.5.2 Allocate a region of non-volatile RAM

The generated file xcp_auto_confdefs.h defines a pre-processor symbol XCP_NV_REGION_SIZE

which gives the size in bytes of the region of non-volatile RAM which is required in order to support

RESUME mode.

The user must adapt the ECU application so that it allocates such a region of non-volatile RAM.

3.5.3 XCP callbacks

The user must implement the following XCP callbacks in the file Examples\xcp_callbacks.c:

XcpApp_NvMemWrite()

XcpApp_NvMemRead()

XcpApp_NvMemClear()

These functions access the region of non-volatile RAM on behalf of the XCP ECU software. They are

described fully in section 5.6.5.

3.5.4 Review the use of Xcp_Initialize()

The API Xcp_Initialize() gains extra functionality when RESUME mode is enabled:

It reads DAQ configuration from the region of non-volatile memory RAM.

It sends a single XCP event message to INCA.

Therefore the user must check that the call to Xcp_Initialize() is made after the non-volatile

RAM is initialised and after the CAN or IP driver is initialised.

3.5.5 Try it out

Once the steps above have been accomplished successfully it should be possible to use RESUME mode

from within INCA or INTECRIO. INCA refers to RESUME mode as “fast start”; its use is described in

section 8.3.3. The use of RESUME mode in INTECRIO is described in section 9.2.

3.6 Adding bypass

This step of the tutorial describes how to add support for bypass to the XCP-on-CAN implementation.

This step of the tutorial applies only to INTECRIO.


Examples/Tutorial/6_bypass.xml. This is based on the file 2_measurement.xml, so if any


changes were made to 2_measurement.xml as part of the second step of the tutorial the same

changes should also be applied to 6_bypass.xml.

Bypass is potentially a complex and error-prone operation. The user is encouraged to read section 4.4

to discover more detail about how it is performed.


The XML file 6_bypass.xml configures three static DAQ lists, one associated with the 2ms raster,

one associated with the 10ms raster and one associated with the 100ms raster. Each DAQ list is paired with a static STIM list which is associated with the same raster. Each pair enables bypass to be

performed on an ECU function which is executed within the OS task corresponding to the associated

raster. So, for example, the pair associated with the 10ms raster can be used to bypass an ECU

function which is executed in the 10ms OS task.

Step 2 of the tutorial (specifically section 3.2.1) has already discussed how the period of a raster can

be modified, and how the capacity of each DAQ list is configured. The user should re-read these

remarks and make any necessary changes to the configuration of the DAQ and STIM lists.

3.6.2 XCP API calls

For each ECU function which is to be bypassed, the user must decide at which point the bypass inputs

should be measured, and at which point the bypass outputs should be written to the ECU’s memory.

The bypass inputs are measured when the ECU application calls the API Xcp_DoDaqForEvent(), and the bypass outputs are written to the ECU’s memory when the ECU application calls the API

Xcp_DoStimForEvent(). These API calls takes the ID of an XCP event (i.e. a raster) as an

argument.

Section 4.4.2 discusses the placement of these two API calls in detail, but for the purposes of this

tutorial they should simply be placed around the ECU function which is to be bypassed:

/* The 10ms raster */

{

...

/* Transmit bypass inputs to the RP hardware */

Xcp_DoDaqForEvent( 1 );

DoEcuFunction();

/* Receive bypass outputs from the RP hardware and write them to memory,

* over-writing the outputs of DoEcuFunction() */

Xcp_DoStimForEvent( 1 );

...

}


The XML configuration file which accompanies this step of the tutorial configures a CAN message ID for each DAQ list and each STIM list using the XML parameter XCPCAN_DAQ_MSGID. The user must

configure the ECU application’s CAN driver to transmit the IDs which are used for DAQ lists and receive

the IDs which are used for STIM lists.

If these message IDs are not suitable the XML configuration file must be modified to specify alternative

IDs.


The user must ensure that the ECU application’s A2L file contains MEASUREMENT blocks which describe

the inputs and outputs of the ECU functions which are to be bypassed.

3.6.5 Try it out

Once the steps above have been accomplished successfully it should be possible to create a simulation in INTECRIO which uses XCP-on-CAN to bypass the chosen ECU functions. INTECRIO’s manuals and

online help give comprehensive guidance on how to create such a model.


3.7 Adapting the tutorial to support XCP-on-IP

This supplementary section describes how to modify the tutorial to use IP instead of CAN as a

transport layer. This step of the tutorial applies only to INCA, not to INTECRIO.

The configuration required for this step of the tutorial is contained in the XML file Examples/Tutorial/7_xcp_on_udp.xml. This is based on the file 2_measurement.xml, so if

any changes were made to 2_measurement.xml as part of the second step of the tutorial the same

changes should also be applied to 7_xcp_on_udp.xml.

Any other step of the tutorial can be converted to use XCP-on-IP by applying changes similar to those

which exist between the files 2_measurement.xml and 7_xcp_on_udp.xml.

3.7.1 Review the IP configuration

The file 7_xcp_on_udp.xml uses XCP-on-UDP, as can be seen by the value of the element XCPIP_PROTOCOL. The user can easily change this element to specify XCP-on-TCP instead, and can

also change the elements XCPIP_ADDRESS and XCPIP_PORT which specify the IP address and port

number used by the XCP-on-IP slave.

In order to make the transition from CAN to IP as easy as possible, the user is advised to keep

XCPIP_MAXDTO and XCPIP_MAX_CTO set to 8 during the tutorial, since this value corresponds to the

DTO and CTO sizes used by XCP-on-CAN.

3.7.2 IP APIs and callbacks

The XCP ECU software expects the IP driver to implement an API XcpApp_IpTransmit(). This API

is discussed fully in sections 4.8.1 and 5.6.9. The user must read these sections and ensure that the

API XcpApp_IpTransmit() is implemented as expected.

The XCP ECU software also expects the IP driver to call the XCP API functions XcpIp_RxCallback(), XcpIp_TxCallback() and, if TCP is being used,

XcpIp_OnTcpCxnClosed(). These APIs are discussed in sections 4.8.1 and 5.5. The user must read

these sections and ensure that the APIs are called as expected.

3.7.3 Finding the XCP-on-IP slave from INCA

When using XCP-on-IP, INCA will not be able to find the XCP-on-IP slave automatically. Instead of

using INCA’s “search for hardware” functionality, the user must tell INCA about the slave as follows:

1. Within INCA’s hardware configuration window select the menu item “Device / Insert…”.

2. Select “Ethernet-System / XCP” from the list of hardware which can be inserted.

Using the XCP ECU software 19

4 Using the XCP ECU software

4.1 The XCP configuration tool

4.1.1 Installing Perl

The XCP configuration tool is implemented as a set of Perl scripts, and therefore the user will need to

install Perl on their PC as described in section 12.

4.1.2 Using the XCP configuration tool

The XCP configuration tool is invoked as follows:

perl xcp_conf.pl [options] <XML configuration file>

The configuration tool supports these options:

--cOutputDir <dir> The directory in which .c output files should be placed. The default is the current working directory.

--hOutputDir <dir> The directory in which .h output files should be placed. The default is

the current working directory.

--a2lOutputDir <dir> The directory in which .a2l output files should be placed. The

default is the current working directory.

--h

--help

Display help.

The XML configuration file must be created by the user. Its structure is described in section 5.1.

The configuration tool generates the following artefacts:

C source code containing configuration for the XCP ECU software. The generated C files must

be built into the user’s ECU application as described in section 5.7.

One or more ASAP2 A2L fragments describing the XCP implementation of each XCP session.

This is described in the following section.

4.1.3 The generated A2L fragment

XCP configuration is stored in three locations in an ASAM A2L file:

1. The IF_DATA XCP block within the MODULE block. This block defines most of the XCP

configuration.

2. The optional IF_DATA XCP block within each MEASUREMENT block. This block provides extra

information about the association between the MEASUREMENT and XCP EVENTs.

3. The IF_DATA XCP block within each MEMORY_SEGMENT block. This block defines the

calibration structure of the SEGMENT.

The configuration data required by the XCP ECU software and the XCP configuration in an ASAM A2L

file overlap, but not completely. In other words:

The XCP ECU software requires some configuration which cannot be defined in an A2L file.

An A2L file may contain XCP configuration which is not required by the XCP ECU software.

(This may seem odd, but such configuration is usually associated with the behaviour of

callback functions which the user is required to implement, i.e. it is not associated with the

XCP ECU software as installed).

A consequence of the second bullet-point is that the XCP configuration tool cannot generate all the A2L

which is required to describe the XCP implementation in the ASAM A2L file. In fact, the configuration

tool generates the A2L block for location 1, as listed above. The XCP A2L in locations 2 and 3 must be

created by the user, either by hand or via an A2L editor.

The user can import the generated A2L fragment into their MC tool, RP tool or ASAP2 editor. Possible

scenarios are discussed in sections 7, 8 and 9.


4.2 Session management

4.2.1 Session state and configuration

The XCP ECU software is able to maintain multiple sets of configuration and state data. This allows it

to communicate with multiple XCP masters simultaneously. Addressing within the underlying transport

layer is used to route communication from an XCP master to the appropriate session of the XCP ECU

software. The existence of multiple XCP sessions is almost entirely transparent to the ECU application.

For example, this feature allows an ECU which uses the XCP ECU software to support simultaneous

access from an MC tool and an RP tool.

The configuration data for each session is contained in a separate XCP_SESSION element in the XML

configuration file. However, it is necessary for certain configuration parameters to be global across all sessions; these are contained in the single XCP_GLOBALS XML element. This document will always

indicate whether a given parameter is “global” or “per-session”.

Each XCP session can be enabled or disabled in the XML configuration file by setting the per-session

XML configuration parameter XCP_ENABLE to yes or no.

Inevitably certain ECU resources will be shared between XCP sessions. For example, memory locations

in the ECU application, CAN IDs and CAN hardware buffers (message objects). It is the responsibility of

the user to configure each XCP session so that it does not access resources which are also used by

another session.

4.2.2 Seed and key

The XCP ECU software supports “seed and key” protection of the CAL/PAG, DAQ, STIM and PGM

resources. The initial state of the protection of each resource (i.e. “protected” or “unprotected”) is set

by these per-session XML configuration parameters:

XCP_PROTECT_CALPAG

XCP_PROTECT_DAQ

XCP_PROTECT_STIM

XCP_PROTECT_PGM

Each of these parameters can have the value “yes” (the resource is protected) or “no” (the resource is

not protected).

The “seed and key” DLL which the XCP master must use to unlock the protected resources is named

by the XCP_SEEDNKEY_FUNCTION per-session XML configuration parameter.

The XCP ECU software itself does not compute a seed when one is needed, nor does it store pre-defined seeds. Instead, the user is required to implement the following callback, which the XCP ECU

software calls when a seed is needed:

void XcpApp_GetSeed( uint sessionId, uint8 resource, Xcp_Seed_t** pSeed,

Xcp_StatePtr8 pSeedLen )

This function calculates a seed for the specified ECU resource. It is documented in section 5.6.6.

Similarly, the user is required to implement the following callback, which the XCP ECU software calls to

obtain a buffer in which a key is to be stored:

void XcpApp_GetKeyBuffer( uint sessionId, uint8 resource, Xcp_Key_t** pKey,

uint8 keyLen )

This function allocates a buffer to be used by the XCP ECU software to store a key. The key

corresponds to the seed provided by the previous call to XcpApp_GetSeed(). This function is also

documented in section 5.6.6.

Finally, the user is required to implement the following callback, which the XCP ECU software calls after

it has placed a key in the buffer obtained from XcpApp_GetKeyBuffer():

sint XcpApp_UnlockResource( uint sessionId, uint8 resource )

This function returns zero if the specified resource cannot be unlocked and a non-zero value otherwise.

This function is also documented in section 5.6.6.

If no XCP resources are configured to require protection in any session, or if the global XML parameter

XCP_ENABLE_SEEDNKEY is set to no, the XCP ECU software will be built without support for “seed

and key” functionality. The XCP commands associated with “seed and key” will cause the error ERR_CMD_UNKNOWN. The user will not need to implement any of the “seed and key” callbacks

described above.


4.2.3 Initialization

The user’s ECU application must call the following API exactly once to initialize the XCP ECU software:

void Xcp_Initialize( void )

4.2.4 Connection and disconnection

The XCP ECU software uses the following callbacks to inform the user’s ECU application about

connection and disconnection events. Since the XCP ECU software can support multiple XCP sessions it

is possible for any of these callbacks to be called more than once in succession.

void XcpApp_OnUserDefinedCxn( uint sessionId )

void XcpApp_OnNormalCxn( uint sessionId )

void XcpApp_OnDisconnect( uint sessionId )

The XCP ECU software does not expect these functions to take any particular action.

Each session of the XCP ECU software will identify itself to its XCP master using the name given by the

per-session XML configuration parameter XCP_ECUID.

4.2.5 Command processing

The user application is required to call the following API regularly in order to allow the XCP ECU

software to send and receive XCP packets:

void Xcp_CmdProcessor( void )

The user must declare the period with which this API is called in the XML configuration using the global

parameter XCP_POLL_INTERVAL (with units of 1ms), so that the XCP ECU software is aware how

often this API is called.

The rate at which the user application calls Xcp_CmdProcessor() determines the rate at which the

XCP ECU software is able to receive and process XCP commands from the XCP master.

The XCP ECU software does not support interleaved communication mode; therefore, usually, there is

no risk that the XCP master will transmit command packets faster than the XCP slave can process

them. However during master block mode it is possible for the XCP master to overload the XCP slave in this manner unless the user takes care to set appropriate values for the two XML configuration

parameters:

the per-session XML configuration parameter XCP_BLOCK_SEPARATION_TIME;

the global XML configuration parameter XCP_NUM_RX_CMDBUF.

The per-session configuration parameter XCP_BLOCK_SEPARATION_TIME (with units of 1ms)

specifies the minimum time which the XCP master must allow between transmitting blocks during master block mode. The user must set this parameter so as to prevent the XCP ECU software’s

command queue from overflowing in master block mode. Usually it would be sufficient to set

XCP_BLOCK_SEPARATION_TIME to the same value as XCP_POLL_INTERVAL; however this does not take account of the fact that a command which involves an asynchronous request to the ECU

application (e.g. writing to calibration memory) may require more than one invocation of

Xcp_CmdProcessor() to complete. Therefore the user should be conservative when choosing a

value for XCP_BLOCK_SEPARATION_TIME.

The global configuration parameter XCP_NUM_RX_CMDBUF specifies the number of buffers which are

allocated to each session’s XCP command queue. Choosing a large value for this parameter allows the

XCP ECU software to buffer commands received during master block mode. Choosing a small value saves RAM, with the risk that the command queue will overflow if the XCP master sends commands

too quickly. If XCP_NUM_RX_CMDBUF is not specified in the XML configuration file a default value of 4

is used.

XCP_BLOCK_SEPARATION_TIME and XCP_NUM_RX_CMDBUF should be chosen together to eliminate

the possibility that the XCP ECU software’s command queue will overflow in master block mode.

4.2.6 Command timeouts

When the XCP master sends an XCP command it starts a timeout counter, counting up from zero.

When the XCP ECU software receives an XCP command packet it also starts a counter. The counter is incremented at the end of every execution of Xcp_CmdProcessor(). If the XCP ECU software cannot

transmit all the response packets required by the command before the counter reaches timeout value

t, then the XCP ECU software sends the event EV_CMD_PENDING and restarts the counter.


The value of this timeout t is specified by the per-session XML configuration parameter

XCP_EVENTPENDING_TIMEOUT, in units of 1ms.

If the XCP master receives the event EV_CMD_PENDING it resets its timeout counter.

If the XCP master’s timeout counter is not reset and reaches a value tn then the XCP master treats the

command as having timed-out and executes the appropriate “pre-action” and “action” as described in the ASAM XCP specification. The master requires 7 different values of tn which are used on various

different occasions. These are configured, in units of 1ms, in the per-session XML configuration

parameters XCP_TIMEOUT_T1 to XCP_TIMEOUT_T7.

4.2.7 CTO packet format

The maximum length of a CTO packet depends on the transport layer which is being used:

For XCP-on-CAN, a CTO packet can contain at most 8 bytes, including a PID.

For XCP-on-IP, the maximum length of a CTO packet is set by the per-session XML

configuration parameter XCPIP_MAXCTO; this can be up to 255, including a PID. Note, however, that choosing a large value causes the XCP ECU software to use a lot of RAM. The

precise details of the RAM usage are contained in the description of XCPIP_MAXCTO in

section 4.8.2.

4.2.8 User-defined commands

The XCP specification describes a command, called USER_CMD, which can be customised for each XCP

implementation, in order to provide user-defined functionality.

By default, the XCP ECU software does not support USER_CMD. To enable support for USER_CMD, the

user must:

Set the global XML configuration parameter XCP_ENABLE_USER_CMD to yes.

Define the callback XcpApp_UserCmd() to process USER_CMD packets which are received.

This callback is described in section 5.6.1.

4.2.9 Memory addressing

The XCP ECU software uses the following values for various XCP parameters:

Parameter Value

ADDRESS_GRANULARITY BYTE

GRANULARITY_ODT_ENTRY_SIZE_DAQ BYTE

MAX_ODT_ENTRY_SIZE_DAQ 32 for XCP-on-CAN or 127 for XCP-on-IP

GRANULARITY_ODT_ENTRY_SIZE_STIM BYTE

MAX_ODT_ENTRY_SIZE_STIM 32 for XCP-on-CAN or 127 for XCP-on-IP

These parameters are documented fully in the ASAM XCP specification.

The XCP ECU software uses the type Xcp_Addr_t to refer to all MTA addresses in the ECU. This type is a pointer referring to a single byte in memory. The user is expected to implement the following

callback function to convert an address of the form (address, extension), as supplied by an XCP

command, into an Xcp_Addr_t:

Xcp_Addr_t XcpApp_ConvertAddress( uint32 address, uint8 extension )

This function is described further in section 5.6.4.

The user must assign one of the following values to the global XML configuration parameter

XCP_ADDR_EXTENSION_TYPE:

ADDRESS_EXTENSION_FREE. The address extension can be different within one and the

same ODT during data acquisition.

ADDRESS_EXTENSION_ODT. The address extension must be the same for all entries of an

ODT during data acquisition.

ADDRESS_EXTENSION_DAQ. The address extension must be the same for all entries of a

DAQ list during data acquisition.

The XCP ECU software does not enforce any of the restrictions which might be specified by

XCP_ADDR_EXTENSION_TYPE; such enforcement is the responsibility of the XCP master.


The user must declare the byte ordering used by the target on which the XCP ECU software will be

run. This is done by setting the global XML configuration parameter XCP_TARGET_BYTE_ORDER to

either MSB_LAST or MSB_FIRST to indicate a little-endian or a big-endian target respectively.

4.3 Measurement and stimulation

4.3.1 DAQ clock

The period of the DAQ clock is specified by the following global XML configuration parameters:

XCP_TIMESTAMP_UNIT. One of 1ns, 10ns, 100ns, 1us, 10us, 100us, 1ms, 10ms, 100ms or

1s.

XCP_TIMESTAMP_TICKS_PER_UNIT. The period of the DAQ clock, measured in units given

by XCP_TIMESTAMP_UNIT.

For example, if the DAQ clock has a period of 20us, XCP_TIMESTAMP_UNIT is “10us” and

XCP_TIMESTAMP_TICKS_PER_UNIT is 2.

The XCP ECU software expects the user application to implement the following callback to provide

access to a counter with the period of the DAQ clock:

uint32 XcpApp_GetTimestamp( void )

This function is described fully in section 5.6.4.

XcpApp_GetTimestamp() always returns a 32-bit counter value which the XCP ECU software

truncates if necessary. The per-session XML configuration parameter XCP_TIMESTAMP_SIZE specifies the number of bytes which will be used for a given session’s timestamp (0, 1, 2, or 4). Setting

XCP_TIMESTAMP_SIZE to 0 for an XCP session will mean that DTO packets associated with the

session will not contain a timestamp, and the XCP command GET_DAQ_CLOCK will return the error

XCP_ERR_GENERIC.

4.3.2 DTO packet format

The XCP ECU software supports the identification field type “absolute ODT number” for DTO packets.

When a DAQ list is transmitted by the XCP ECU software, the first DTO packet will contain the current

value of the DAQ clock if:

the XCP master has configured the DAQ list to use TIMESTAMP mode;

and the clock value has been configured to occupy a non-zero number of bytes (see section

4.3.1).

These two conditions also apply to STIM lists: when a STIM list is received by the XCP ECU software, if

both these conditions are met, the XCP ECU software expects the first DTO packet of the list to contain a timestamp. However, even if a timestamp is present in a STIM DTO, it will always be ignored by the

XCP ECU software.

The maximum length of a DTO packet depends on the transport layer which is being used:

For XCP-on-CAN, a DTO packet can contain at most 8 bytes, including a PID.

For XCP-on-IP, the maximum length of a DTO packet is set by the per-session XML

configuration parameter XCPIP_MAXDTO; this can be up to 65531 for TCP and 1472 for UDP, including a PID. Note, however, that choosing a large value causes the XCP ECU software to

use a lot of RAM. The precise details of the RAM usage are contained in the description of

XCPIP_MAXDTO in section 4.8.2.

4.3.3 DAQ list features

The XCP ECU software supports DAQ lists with the following features:

Static DAQ lists are supported and are defined in the XML configuration file. A static DAQ list

can be defined to support measurement only, stimulation only or both measurement and

stimulation1.

Dynamic DAQ lists are supported, with limits defined in the XML configuration file. A dynamic

DAQ list is always assumed to support both measurement and stimulation.

1 Though, as described in the XCP specification, a DAQ list cannot support both measurement and stimulation

simultaneously.


Static and dynamic DAQ lists cannot both be configured simultaneously for the same XCP

session, though two separate sessions can be defined, one which uses static DAQ lists and

one which uses dynamic DAQ lists.

If dynamic DAQ lists are not used by any session in the XML configuration file then the XCP ECU software will be built without support for dynamic DAQ lists. The following XCP

commands associated with dynamic DAQ lists will cause the error ERR_CMD_UNKNOWN:

FREE_DAQ

ALLOC_DAQ

ALLOC_ODT

ALLOC_ODT_ENTRY

ODT entries can be configured at runtime to hold measurement values from 1 bit up to 4

bytes (when using CAN) or 127 bytes (when using IP), as described in the ASAM XCP

specification.

If the XML configuration specifies no DAQ lists which support data stimulation, or if the global XML

configuration parameter XCP_ENABLE_STIM is set to no, the XCP ECU software will be built without

support for data stimulation.

4.3.4 DAQ list configuration

Each static DAQ has the following parameters specified in XML configuration:

XCP_DAQNAME The name of the DAQ list.

XCP_DAQDIR The direction of the DAQ list: DAQ, STIM or DAQ_STIM.

XCP_MAX_ODT The number of ODTs which can be configured in the DAQ

list.

XCP_MAX_ODT_ENTRIES The number of ODTs entries which can be configured in each ODT.

XCP_DAQ_DEFAULT_EVENT The event channel which is initially associated with the

DAQ list. Each DAQ list is always associated with exactly

one event channel.

XCP_DAQ_EVENT_FIXED (optional) This indicates whether the event channel specified by XCP_DAQ_DEFAULT_EVENT is fixed, or whether the DAQ

can be associated with a different event channel at

runtime. The default value for this parameter is no.

XCP_DAQ_CANRESUME This indicates whether the DAQ list can be RESUMEd (see

section 4.3.10). Setting this parameter to “no” does not

prevent the DAQ list from being RESUMEd, but selecting the DAQ list for RESUME is likely to cause memory errors in

the ECU application.

XCP_DAQ_NUM_BUFFERED_CYCLES

(optional)

This specifies the number of complete cycles of this DAQ

list which can be buffered by the XCP ECU software. It defaults to 1. Section 4.4.5 discusses occasions when this

value may need to be modified.

XCP_DAQ_CAN

(optional)

This element contains configuration specific to the CAN

transport layer. It is described in more detail in section 4.7.2.

Obviously dynamic DAQ lists cannot be defined in the XML configuration. Instead, the following

parameters define limits for dynamic DAQ lists:

XCP_MAX_DYN_DAQ The maximum number of dynamic DAQ lists which can be

defined.

XCP_MAX_DYN_ODT The maximum number of ODTs which can be assigned to each dynamic DAQ list.

XCP_MAX_DYN_ODT_ENTRIES The maximum number of ODT entries which can be

assigned to each dynamic ODT.


XCP_MAX_RESUME_DYNDAQLISTS The maximum number of dynamic DAQ lists which can be simultaneously RESUMEd (see section 4.3.10). This limit is

not enforced, but exceeding it may cause memory errors in

the ECU application.

XCP_DAQ_NUM_BUFFERED_CYCLES

(optional) This specifies the number of complete cycles of any dynamic DAQ list which can be buffered by the XCP ECU

software. It defaults to 1. Section 4.4.5 discusses occasions

when this value may need to be modified.

All the DAQ XML configuration parameters are per-session and are described also in section 5.1.

By default, the XCP ECU software is able to buffer one complete cycle of each DAQ or STIM list at

runtime. This means that buffer space will be allocated for each ODT of each DAQ list which is

configured in XML. If dynamic DAQ lists are used, buffer space will be allocated for each potential ODT of each potential DAQ list. Therefore it is important to configure exactly the required number of DAQ

lists and ODTs: configure too many and RAM will be wasted; configure too few and DAQ or STIM DTOs

will be lost at runtime.

In some circumstances (described in section 4.4.5), the XCP ECU software must be able to buffer more than one complete cycle of a particular DAQ or STIM list. This can be achieved by assigning a value

greater than 1 to the XML configuration parameter XCP_DAQ_NUM_BUFFERED_CYCLES. If static DAQ

lists are being used, this parameter can be set per-DAQ-list; if dynamic DAQ lists are being used, this

parameter applies to all dynamic DAQ lists which are defined.

4.3.5 Event channels

Each event channel is defined globally in the XML configuration file. The following parameters must be

specified:

XCP_EVENTCHANNEL_NAME The name of the event channel. This value is passed directly to the generated A2L fragment and is not used otherwise.

XCP_EVENTCHANNEL_SHORTNAME The short name of the event channel.

XCP_EVENTCHANNEL_NUM The ID of the event channel.

XCP_EVENT_TIMEUNIT One of 1ns, 10ns, 100ns, 1us, 10us, 100us, 1ms, 10ms,

100ms or 1s. This value is passed directly to the generated

A2L fragment and is not used otherwise.

XCP_EVENT_TIMECYCLE The period of the event cycle, in units given by

XCP_EVENT_TIMEUNIT. If the event is acyclic (i.e. it does

not have a strict period) the value should be 0.

This value is passed directly to the generated A2L fragment

and is not used otherwise.

The following properties are fixed for each event channel:

The maximum number of DAQ (or STIM) lists which can be associated with this event. This is

always set to 255 (i.e. no limit).

The priority of the event. This is always set to 255.

An event can always be associated with either STIM lists or DAQ lists.

The user application is required to notify the XCP ECU software about the occurrence of the events

which are specified in the XML configuration and which are associated with DAQ and STIM lists.

The user application can do this in one of two ways:

Either it can call the following APIs, specifying the channel number of the event:

void Xcp_DoDaqForEvent( uint eventId )

void Xcp_DoStimForEvent( uint eventId )

Or it can call the static APIs of the following form:

Xcp_DoDaqForEvent_<Event short name>()

Xcp_DoStimForEvent_<Event short name>()

API macros of this form are generated by the configuration tool.

Having separate APIs for DAQ and STIM allows the user application to control when DAQ and STIM

occur during an event cycle.


4.3.6 DTO over-filling

A DTO is over-filled if, when the XCP ECU software tries to use the DTO for measurement or

stimulation, it discovers that the DTO has been configured to hold more data than the underlying

packet size permits. DTO over-filling is prevented in some circumstances:

The configuration tool displays an error message if an ODT is assigned so many ODT entries

that, even if the ODT entries are configured with the minimum length of 1 byte, the

associated DTO will be over-filled.

The XCP command WRITE_DAQ returns an error if an attempt is made to configure an ODT

entry with a length greater than MAX_ODT_ENTRY_SIZE.

Nevertheless, it is still possible that a DTO will become over-filled. It is not desirable to prevent the

ODT which is associated with the DTO from ever entering a state which would cause the DTO to be

over-filled, since this would prevent legitimate sequences such as this:

1. User is using the CAN transport.

2. User configures a DAQ list with mode TIMESTAMP.

3. User configures a 32-bit value for the first ODT entry within the DAQ list (the associated DTO

is now over-filled).

4. User configures the DAQ list with mode !TIMESTAMP (the associated DTO is no longer over-

filled).

Therefore, except for the two bullet-points above, the XCP ECU software does not prevent a DTO from

becoming over-filled. It is the XCP master's responsibility to avoid this situation.

If an over-filled DTO is processed by one of the API functions Xcp_DoDaqForEvent() or Xcp_DoStimForEvent(), the function will report the error XCPEVENT_DTO_OVERFILL. When this

occurs, the function ignores any ODT entries which would lie partly or completely beyond the end of

an over-filled DTO. All other ODT entries are processed as usual.

4.3.7 DAQ list overloading

If measurement begins for a new cycle of a DAQ list before transmission of the data from the previous

cycle is complete, the DAQ list is said to be overloaded. Similarly, a STIM list is said to be overloaded if stimulation data for a new cycle of the list is received by the XCP ECU software before the data from

the previous cycle is completely processed.

If a DAQ list is overloaded during measurement, the error XCPEVENT_DAQ_OVERLOAD will be reported

by the function Xcp_DoDaqForEvent(). If this occurs, Xcp_DoDaqForEvent() aborts transmission of the current cycle of the affected DAQ list and discards any untransmitted measurement data from

that cycle.

If a STIM list is overloaded during stimulation, the XCP ECU software will silently discard some STIM

DTOs. This may cause problems with the consistency of the STIM data which is successfully received.

STIM data consistency is discussed in section 4.4.3.

A DAQ or STIM list usually becomes overloaded when the CPU or the CAN controller has insufficient

clock cycles available, or when the CAN bus has too low a baudrate. There are some possible

remedies:

Increase the baudrate of the CAN bus.

Increase the clock rate of the CPU, or of the CAN controller.

Decrease the application load on the ECU, allowing more clock cycles to be used to process

measurement or stimulation data.

4.3.8 DAQ data consistency

Data for each ODT of a running DAQ list is sampled whenever the XCP ECU software is notified of the event associated with the DAQ list. This occurs when the ECU application calls the API function

Xcp_DoDaqForEvent(), and is described further in section 4.3.5. Unless steps are taken, there is a

risk that this data sampling will be interrupted, perhaps causing the sampled data to be inconsistent.

The XML configuration contains a global value XCP_ATOMIC_DATA_SAMPLING which can take one of

the following values:

NOT_ENFORCED. The XCP ECU software does not take any steps to ensure that sampled data

is consistent. It is the user’s responsibility to ensure that the task used by the ECU application

to call the API Xcp_DoDaqForEvent() cannot be pre-empted in such a way that the DAQ

data will be modified while it is being sampled.


PER_ODT. The XCP ECU software guarantees that data within each ODT will be consistent. It

does this by disabling interrupts while data is sampled for each ODT.

PER_DAQ_LIST. The XCP ECU software guarantees that data within each DAQ list will be

consistent. It does this by disabling interrupts while data is sampled for each DAQ list.

It is generally good practice to avoid disabling interrupts for long periods of time, since doing this disrupts the scheduling of the ECU application. The user is discouraged from using the values

PER_ODT and PER_DAQ_LIST without understanding the impact this will have on the timing of the

ECU application.

The best approach to ensuring DAQ data consistency is to use the value NOT_ENFORCED, and to

arrange for the DAQ data to be sampled in the same task which modifies the data.

4.3.9 Protecting regions of memory from measurement and stimulation

The XCP ECU software expects the user application to implement the following callback:

sint XcpApp_IsRegionMeasurable( uint32 address, uint8 extension, uint32 numBytes )

This returns a boolean indicating whether the specified memory region can be measured and/or

stimulated. This function is described fully in section 5.6.4.

The user can use this callback to prohibit an XCP master from measuring or stimulating private areas

of ECU memory.

4.3.10 RESUME mode

RESUME mode is supported as described in the ASAM XCP specification.

In order to implement RESUME mode, the user application is required to assign a known region of

non-volatile memory (e.g. EEPROM) for use by the XCP ECU software. The XCP ECU software uses this

region to store DAQ states during RESUME mode.

As described in section 4.3.4, the XML configuration specifies the number of DAQ lists which can be RESUMEd simultaneously. The configuration tool uses this information to generate a pre-processor

macro XCP_NV_REGION_SIZE which gives the required size in bytes of the non-volatile memory

region.

The XCP ECU software does not know the absolute location of the non-volatile memory region; it works with offsets within the region. The user application is required to implement the following

callbacks to store and retrieve data in the non-volatile memory region:

void XcpApp_NvMemWrite( uint offset, Xcp_StatePtr8 pData, uint numBytes )

void XcpApp_NvMemRead( uint offset, Xcp_StatePtr8 pData, uint numBytes )

void XcpApp_NvMemClear( uint offset, uint numBytes )

These functions are described fully in section 5.6.5.

If the XML configuration specifies no DAQ lists which can be RESUMEd, or if the global XML

configuration parameter XCP_ENABLE_RESUME is set to no, the XCP ECU software will be built without support for RESUME mode. In this case the user will not need to provide a non-volatile

memory region or implement the above callbacks.

4.4 Bypassing

4.4.1 Implementing bypass using XCP

During bypass, the outputs of a certain function within the ECU application, called the bypassed function, are replaced with the outputs of a function calculated by a rapid prototyping system, called

the bypass function. The rapid prototyping system uses an XCP master driver to communicate with the

ECU.

The XCP ECU software supports bypass, but, as described in the ASAM XCP specification, it is simply

treated as the combination of DAQ and STIM.

In order to perform bypass, the XCP master must configure a DAQ list to measure the inputs of the

bypass function, and a STIM list to write the outputs of the bypass function to the ECU’s memory. Both

the DAQ list and the STIM list must be associated with an XCP event channel which has the same period as the OS task which executes the bypassed function, for example a “10ms event” or an

“engine synchronous event”.


When the OS task runs which contains the bypassed function, the ECU application must call the API

function Xcp_DoDaqForEvent() to run the DAQ list which measures the bypass inputs and the API

function Xcp_DoStimForEvent() to run the STIM list which writes the bypass outputs.

It is likely that the round-trip time associated with XCP bypass will be such that the bypass outputs written to the ECU’s memory during cycle n will have been calculated from inputs measured during

cycle n-1 or even cycle n-2.

The calls to Xcp_DoDaqForEvent() and Xcp_DoStimForEvent(), and the flow of data during

bypass are shown in Figure 1.

ECU timeline

Xcp_DoDaqForEvent()

bypassed

ECU function

Rapid prototyping

system timeline

Bypass

function

Xcp_DoStimForEvent()

Bypass

function

Bypass

function

input

output

event

Xcp_DoDaqForEvent()

bypassed

ECU function

Xcp_DoStimForEvent()

DAQ

STIM

DAQ

STIM

event

ECU memory

(For clarity, ECU

memory access is

omitted from the

second cycle)

Figure 1: XCP bypass, showing an n-1 delay

4.4.2 Positioning Xcp_DoStimForEvent() and Xcp_DoDaqForEvent()

The user should carefully consider the positioning of the call to the API function

Xcp_DoStimForEvent(). When this call is executed, the received bypass outputs are written to the

ECU’s memory, overwriting any data which was present previously. Therefore the ECU application should always call the API function Xcp_DoStimForEvent() after the bypassed function has

executed on the ECU, but before the outputs of the bypassed function are used by any other ECU

function.

If the user cannot guarantee that another ECU function will not use the outputs of the bypassed function before they are overwritten by Xcp_DoStimForEvent(), then the user should disable the

bypassed function while the bypass is active (this can be achieved via a calibration parameter).


Different considerations affect the positioning of the call to the API function Xcp_DoDaqForEvent().

Due to the n-1 (or n-2) delay, the call to Xcp_DoDaqForEvent() does not need to occur before the

execution of the bypassed ECU function:

Xcp_DoDaqForEvent() should be called after the bypassed function if the bypassed function modifies its own inputs, since doing so ensures that the bypass function uses the latest

possible input values.

Otherwise Xcp_DoDaqForEvent() should be called before the bypassed function, since best

performance will be achieved if Xcp_DoDaqForEvent() is called as soon as possible.

4.4.3 STIM data consistency

Stimulation data is received asynchronously from the XCP master and buffered by the XCP ECU

software. When the XCP ECU software is notified of the event associated with a STIM list, the buffered data for each ODT of the STIM list is written directly to the ECU’s memory. This occurs when the ECU

application calls the API function Xcp_DoStimForEvent(), and is described further in section 4.3.5.

There are two ways in which inconsistencies can arise in the data which is written to the ECU’s

memory:

The stimulation task can be interrupted before the stimulation values have been completely

written to the ECU’s memory, allowing inconsistent values to be read from the ECU’s memory.

It is possible that some STIM DTOs which were transmitted by the XCP master were lost or

delayed and so will not have been received by the XCP ECU software in time to be written to

the ECU’s memory.

The first of these problems can be dealt with exactly as described in section 4.3.8:

Either the user must arrange for the STIM data to be written to the ECU’s memory in the

same task which reads the stimulated data values.

Or the global XML configuration parameter XCP_ATOMIC_DATA_SAMPLING must be used to

ensure that interrupts are disabled, either for each STIM ODT, or for each complete STIM list.

The second of the problems above is handled by Xcp_DoStimForEvent(): before the function writes the data from a STIM list to the ECU’s memory, it checks that all the DTO packets of the STIM

list have been received. If this is not the case, the function writes no data from the STIM list to the

ECU’s memory and returns XCPEVENT_MISSING_DTO.

Even if Xcp_DoStimForEvent() returns XCPEVENT_MISSING_DTO, it is likely that some DTO

packets have been received for the STIM list. If the missing STIM DTO packets have simply been

delayed, Xcp_DoStimForEvent() retains those DTO packets which have already been received for

the STIM list. When Xcp_DoStimForEvent() is next called, it is likely that the missing STIM DTO packets will have arrived and the STIM list can be processed successfully. However, if

Xcp_DoStimForEvent() detects that the missing STIM DTO packets have been lost entirely, then

the function discards all the DTO packets which have been received for the current cycle of the STIM

list.

Sections 4.4.4 and 4.4.5 discuss ways to handle or prevent the error XCPEVENT_MISSING_DTO in the

context of a bypass operation.

A consequence of this checking is that the XCP master must not send the XCP ECU software

unexpected STIM DTO packets. Specifically, if a STIM ODT is configured such that the first ODT entry in the ODT has a zero length, the XCP ECU software will not expect to receive any STIM DTOs

corresponding to that ODT. If the XCP master nevertheless sends such a DTO, the behaviour of the

XCP ECU software is undefined.

4.4.4 Handling missing STIM DTOs

The user must consider what will happen if Xcp_DoStimForEvent() reports that missing STIM

DTOs were detected (by returning the error code XCPEVENT_MISSING_DTO). In this case, the bypass outputs contained in the affected STIM list will not be written to the ECU’s memory. Various policies

are available for handling this situation:

Use the outputs of the bypassed function. To implement this policy, the user must

ensure that the bypassed function is still executed, even when bypass is in progress. In the event of a missing STIM DTO, the outputs of the bypassed function will not be overwritten

and will remain in memory to be used by the ECU application. This is the policy shown in

Figure 1, and by the following code block.

{



TheEcuFunction();

Xcp_DoStimForEvent( 1 ); /* This may, or may not, write the bypass ouputs */

}

Use the previous outputs of the bypass function. To implement this policy, the user

must ensure that the bypassed function is not executed when bypass is in progress. If

calibration access to the ECU is available, this can be achieved by using a calibration parameter to “switch off” the bypass function while bypass is in progress. In the event of a

missing STIM DTO, the previous outputs of the bypass function will not be overwritten and

will remain in memory to be used by the ECU application:

extern int bypassEnabled; /* This value can be calibrated */

{


if( !bypassEnabled )

{

TheEcuFunction();

}

Xcp_DoStimForEvent( 1 ); /* This may, or may not, write the bypass ouputs */

}

Use fixed output values. To implement this policy, the ECU application must detect the XCPEVENT_MISSING_DTO error code from Xcp_DoStimForEvent() and copy fixed output

values into the correct locations in the ECU’s memory:

{

uint result;


TheEcuFunction();

result = Xcp_DoStimForEvent( 1 );

if( result & XCPEVENT_MISSING_DTO )

{

/* Xcp_DoStimForEvent() did not write the bypass outputs. */

CopyFixedOutputValues();

}

}

4.4.5 Reasons for missing STIM DTOs

Missing STIM DTOs can occur for a number of reasons, but some of the most common ones are:

Insufficient buffering capacity in the transport layer hardware. The rapid prototyping

system will send STIM DTOs in quick succession, and if the transport layer hardware

controller cannot immediately accept all the incoming DTOs some will be dropped. The transport layer hardware should be configured so that it can successfully buffer the worst-

case arrival pattern of STIM DTOs. For example, in the case of CAN, the CAN driver must

allocated sufficient CAN hardware message objects so that a message object is always

available when a STIM DTO arrives.

Insufficient buffering capacity in the XCP ECU software. Section 4.3.4 explained that

the XCP ECU software allocates enough buffer space to store a complete cycle of each STIM

list. However, depending on the timings of the bypass system, sometimes this is not sufficient

to buffer all incoming STIM DTOs. Consider this example sequence:

Cycle 0:

1. Xcp_DoDaqForEvent() transmits bypass inputs to the rapid prototyping system.

2. Xcp_DoStimForEvent() cannot do anything: no bypass outputs have been

received yet.

3. The rapid prototyping system calculates the bypass outputs and sends them to the

ECU. They are buffered by the XCP ECU software.


Cycle 1, in which the bypass outputs arrive slightly more quickly than in cycle 0:

1. Xcp_DoDaqForEvent() transmits bypass inputs to the rapid prototyping system.

2. The rapid prototyping system calculates the bypass outputs and begins to send them

to the ECU. However, the XCP ECU software is still buffering the bypass outputs

from cycle 0, because Xcp_DoStimForEvent() has not been called since the bypass outputs for cycle 0 were received. To avoid an error, the XCP ECU software

must now buffer two complete cycles of bypass outputs. If this cannot be done,

some or all of the bypass outputs from cycle 1 will be dropped.

3. Xcp_DoStimForEvent() processes the bypass outputs from cycle 0.

If the user suspects that this sequence of events is occurring, he should assign the value 2 to the XML configuration parameter XCP_DAQ_NUM_BUFFERED_CYCLES for the STIM list in

question. This will allow the XCP ECU software to buffer two complete cycles of the STIM list

and ensure that no DTOs are dropped.

A race condition between the ECU and the rapid prototyping system. If the rapid prototyping system sends the bypass outputs at almost exactly the same time as

Xcp_DoStimForEvent() is called, then Xcp_DoStimForEvent() may be called when

some, but not all, of the STIM DTOs have been received, causing XCPEVENT_MISSING_DTO

to be returned.

In this scenario, the bypass results have not been lost, just delayed. Therefore the full results

will be processed successfully by Xcp_DoStimForEvent() in the next cycle.

4.5 Calibration

4.5.1 Configuration

The user must specify the structure of calibration memory for each session which uses calibration

functionality. This is done with the following per-session parameters in the XML configuration file:

The XCP_SEGMENT_LIST element must contain a collection of XCP_SEGMENT elements, one

for each memory segment.

Each XCP_SEGMENT element must contain a XCP_SEGMENT_NUM element, specifying the

segment’s number, and a XCP_PAGE_LIST element, containing a collection of XCP_PAGE

elements.

Each XCP_PAGE element must contain XCP_PAGE_NUM, specifying the page’s number, and

XCP_INIT_SEGMENT, specifying the page’s INIT segment.

A session which does not use calibration functionality does not need to define these parameters in the

XML configuration file.

If the user does not specify these parameters for any session in the XML configuration file, or if the global XML configuration parameter XCP_ENABLE_CALPAG is set to no, the XCP ECU software will be

built without support for calibration functionality. The following XCP commands associated with

calibration will cause the error ERR_CMD_UNKNOWN:

SET_CAL_PAGE

GET_CAL_PAGE

GET_PAG_PROCESSOR_INFO

COPY_CAL_PAGE

SET_SEGMENT_MODE

GET_SEGMENT_MODE

MODIFY_BITS

DOWNLOAD

DOWNLOAD_NEXT

DOWNLOAD_MAX

In this case the user will not need to implement any of the callbacks described in sections 4.5.3 and

4.5.4 below.

4.5.2 Upload and download

The XCP ECU software supports upload, including slave block mode, and download, including master

block mode.


However, the XCP ECU software is not able to access calibration memory by itself. Therefore upload

and download make use of the following callbacks which the user is required to implement:

Xcp_CalMemState XcpApp_CalMemWrite ( Xcp_Addr_t mta, uint32 numBytes,

Xcp_StatePtr8 pBytes )

Xcp_CalMemState XcpApp_CalMemRead( Xcp_Addr_t mta, uint32 numBytes,


Xcp_CalMemState XcpApp_CalMemModifyBits( Xcp_Addr_t mta, uint8 numShiftBits,

uint16 andMask, uint16 xorMask )

These functions are expected to make use of the current tool calibration page, as set by

XcpApp_SetToolCalPage() (see section 4.5.3). These functions are described fully in section

5.6.3.

4.5.3 Calibration page management

The XCP ECU software supports all the specified XCP commands for managing calibration pages. However, the XCP ECU software does not know how to manipulate the ECU’s calibration memory itself;

therefore the XCP ECU software requires the user to implement these callbacks:

Xcp_CalPageErr XcpApp_SetEcuCalPage( uint8 dataSegment, uint8 calPage )

Xcp_CalPageErr XcpApp_SetEcuCalPageAllSegs ( uint8 calPage )

Xcp_CalPageErr XcpApp_SetToolCalPage( uint8 dataSegment, uint8 calPage )

Xcp_CalPageErr XcpApp_SetToolCalPageAllSegs( uint8 calPage )

uint8 XcpApp_GetEcuCalPage( uint8 dataSegment )

Xcp_CalMemState XcpApp_CalPageCopy( uint8 destSegmentId, uint8 destPageId,

uint8 sourceSegmentId, uint8 sourcePageId )

These functions are described in detail in section 5.6.3.

Obviously it is necessary for the ECU application to remember the current “ECU” calibration page for

each memory segment. However, it is also necessary for the ECU application to remember the current “tool” (or “XCP”) calibration page for each memory segment so that the ECU application can implement

those callbacks which access calibration memory on behalf of the XCP ECU software, such as

XcpApp_CalMemRead() and XcpApp_CalMemWrite().

Note that if a DAQ list is configured so that it acquires measurement data from a calibration memory segment the XCP ECU software will always use the “ECU” page of the memory segment to obtain

values for the DAQ list.

Note also that in some ECU applications the “tool” page and the “ECU” page will always be the same.

This is indicated by the keywords XCP_READ_ACCESS_WITH_ECU_ONLY and XCP_WRITE_ACCESS_WITH_ECU_ONLY in the definition of the pages in the ECU application’s A2L file.

In this situation those callbacks which access calibration memory on behalf of the XCP ECU software

(and which therefore ought to use the “tool” page) can use the “ECU” page instead of the “tool” page

if it is easier to do so.

4.5.4 Calibration page freezing

The XCP ECU software supports calibration page freezing as described in the ASAM XCP specification.

The user is required to implement this callback:

Xcp_CalMemState XcpApp_CalSegFreeze( uint8 segmentId, uint8 initSegmentId )

This function should copy the current “XCP” (or “tool”) page of the specified segment into page 0 of

the specified init segment. The function is described fully in section 5.6.3. The user may implement

this as a special case of XcpApp_CalPageCopy().

The XML configuration file contains a global parameter XCP_ENABLE_PAGE_FREEZING. If this is set to no the XCP ECU software will be built without support for page freezing. The following XCP

commands associated with page freezing will cause the error ERR_CMD_UNKNOWN:

SET_SEGMENT_MODE

GET_SEGMENT_MODE

In this case the user will not need to implement the callback described above.


4.5.5 Checksums

The XCP command BUILD_CHECKSUM is supported. However, the user is required to implement the

following callback to calculate a checksum over a range of memory on behalf of the XCP ECU software:

Xcp_CalMemState XcpApp_CalMemGetChecksum( Xcp_Addr_t address, uint32 numBytes,

Xcp_StatePtr8 pChecksumType,

Xcp_StatePtr32 pChecksum )

This callback can use any of the following checksum types:

Type Name Description

1 XCP_ADD_11 Add each byte into a byte checksum, ignore overflows.

2 XCP_ADD_12 Add each byte into a word checksum, ignore overflows.

3 XCP_ADD_14 Add each byte into a dword checksum, ignore overflows.

4 XCP_ADD_22 Add each word into a word checksum, ignore overflows. Checksum

region size must be modulo 2.

5 XCP_ADD_24 Add each word into a dword checksum, ignore overflows. Checksum


6 XCP_ADD_44 Add each dword into a dword checksum, ignore overflows. Checksum


7 XCP_CRC_16 See ASAM XCP specification of BUILD_CHECKSUM command.

8 XCP_CRC_16_CITT See ASAM XCP specification of BUILD_CHECKSUM command.

9 XCP_CRC_32 See ASAM XCP specification of BUILD_CHECKSUM command.

The callback is documented fully in section 5.6.3.

4.5.6 Asynchronous calibration callbacks

The callbacks which access calibration memory (XcpApp_CalMem...() etc.) may not be synchronous,

i.e. the memory access operation may not be complete when the callback returns.

The user is required to implement the following callback to allow the XCP ECU software to obtain the

state of a pending asynchronous request:

Xcp_CalMemState XcpApp_CalMemGetRequestState( void )

This function is described fully in section 5.6.3. If, in fact, all calibration callbacks are completed

synchronously then this function should just return CALMEM_FINISHED.

If a request to access calibration memory completes asynchronously the XCP ECU software will not

submit any other requests to access calibration memory while the asynchronous request is still

pending.

4.6 Flash programming

The XCP ECU software supports flash memory programming as specified in the ASAM XCP standard.

At most one XCP session can perform flash programming at a time, and a session cannot disconnect

during a flash programming sequence. A flash programming session begins with the successful

completion of the XCP command PROGRAM_START and ends either with the completion of the XCP

command PROGRAM_RESET or an error from one of the commands PROGRAM_CLEAR, PROGRAM,

PROGRAM_NEXT or PROGRAM_MAX.

Due to the application-specific nature of flash programming, the XCP ECU software expects that the

user application will implement all required flashing functionality via these callbacks:

Xcp_ProgramState XcpApp_ProgramPrepare( Xcp_Addr_t mta, uint16 codeSize )

Xcp_ProgramState XcpApp_ProgramStart( Xcp_Addr_t mta )

Xcp_ProgramState XcpApp_ProgramClear( Xcp_Addr_t mta, uint32 length )

Xcp_ProgramState XcpApp_Program( Xcp_Addr_t mta, uint8 numBytes,



Xcp_ProgramState XcpApp_ProgramReset( void )

These callbacks may not be synchronous, i.e. the programming operation may not be complete when

the callback returns. Therefore the user is required to implement the following callback to allow the

XCP ECU software to obtain the state of a pending asynchronous request:

Xcp_ProgramState XcpApp_ProgramGetRequestState( void )

If a programming request completes asynchronously the XCP ECU software will not submit any other

programming requests while the asynchronous request is still pending.

All the above callback functions are described fully in section 5.6.7.

If any XCP session is to use flash programming functionality the user must specify the structure of

flash memory via the following global XML configuration parameters:

The XCP_SECTOR_LIST element must contain a collection of XCP_SECTOR elements.

Each XCP_SECTOR element must contain the following configuration parameters:

XCP_SECTOR_NAME The name of the sector.

XCP_SECTOR_NUM The number of the sector.

XCP_SECTOR_ADDR The address of the sector.

XCP_SECTOR_LENGTH The length of the sector.

XCP_CLEAR_SEQ_NUM The sector’s clear sequence number.

XCP_PROGRAM_SEQ_NUM The sector’s programming sequence number.

The XCP ECU software does not make any use of this flash configuration. It just outputs it in the

generated A2L fragment.

If the user does not specify an XCP_SECTOR_LIST element in the XML configuration file, or if the

global XML configuration parameter XCP_ENABLE_PGM is set to no, the XCP ECU software will be built without support for flash programming functionality. The XCP commands associated with flash

programming will cause the error ERR_CMD_UNKNOWN. The user will not need to implement any of

the flash programming callbacks described above.

4.7 CAN transport layer

4.7.1 Interaction with the CAN driver

General

The XCP ECU software is designed to present a target-independent interface to the CAN driver.

The XCP ECU software expects the CAN driver to manage a collection of hardware buffers, which are referred to as CAN message objects. The XCP ECU software permits the CAN driver to multiplex many

CAN messages with different IDs onto a single CAN message object, both for TX messages and RX

messages.

Although the XCP ECU software requires only a single CAN message object for transmission and another for reception, best performance will be achieved if the following CAN message objects can be

allocated:

a message object for transmitting each DAQ list;

a message object for receiving each STIM list;

a message object for receiving XCP commands;

a message object for transmitting XCP responses and events.

Each CAN message object which is used by the XCP ECU software must be reserved exclusively for the

XCP ECU software.

The XCP ECU software is not aware of the existence of more than one CAN controller. Therefore, either a single CAN controller must be used for all XCP CAN messages, or the CAN driver must hide the

existence of multiple CAN controllers from the XCP ECU software.

The XCP ECU software makes very few assumptions about the format of CAN message IDs. Therefore,

CAN message IDs can be specified in any format which is expected by the CAN driver. The only

assumptions made by the XCP ECU software are that:

A CAN message ID can be stored as a 32-bit unsigned integer.


The value 0xffffffff is not a valid CAN message ID. If this is not the case (i.e. if this value

is a valid message ID) then the definition of the pre-processor symbol

XCPCAN_INVALID_MSGID in the file xcpcan_priv.h must be changed.

Transmission

The XCP ECU software expects the CAN driver to implement the following API:

void XcpApp_CanTransmit( XcpCan_MsgObjId_t msgObjId, uint32 msgId, uint numBytes,


This transmits the specified CAN message on the specified CAN message object. The CAN driver is

permitted to queue the message in hardware or software if it needs to do so, but the XCP ECU

software does not assume that any queuing will occur.

However, the XCP ECU software does assume that:

the contents of the buffer pBytes can be discarded after XcpApp_CanTransmit() has

returned;

XcpApp_CanTransmit() cannot fail, i.e. the CAN driver cannot refuse to accept the

message altogether.

The CAN driver can discard the argument msgId if there is a 1-to-1 mapping from message object to

message ID.

The XCP ECU software expects the CAN driver to call the following API when a CAN message has been

transmitted successfully on a CAN message object which is assigned to the CAN transport layer:

void XcpCan_TxCallback( XcpCan_MsgObjId_t msgObjId )

The XCP ECU software assumes that this function will be called from within the CAN driver’s “TX

confirmation” interrupt handler. If this function is not called from within an interrupt handler changes

may be necessary in the XCP ECU software.

Note that XcpCan_TxCallback() may call XcpApp_CanTransmit() again.

Reception

The XCP ECU software expects the CAN driver to call the following API when a CAN message has been

received on a CAN message object which is assigned to the XCP ECU software:

void XcpCan_RxCallback( uint32 msgId, uint8 msgLen, uint8* pMsgData )

As can be seen from the function’s signature, the XCP ECU software does not care which CAN message

object was used to receive the CAN message.

If the XCP ECU software does not recognize the received CAN message it will discard the message

silently. However, for optimum performance, the CAN driver should not rely on this behaviour and should use hardware filtering to ensure that only CAN messages which are associated with the XCP

ECU software are supplied to XcpCan_RxCallback().

The argument msgLen can indicate the true length of the received CAN message, or it can simply be

set to 8. However, the latter choice will cause inefficiency in the XCP ECU software.

The XCP ECU software assumes that XcpCan_RxCallback() will be called from within the CAN driver’s “RX indication” interrupt handler. If this function is not called from within an interrupt handler

changes may be necessary in the XCP ECU software.

4.7.2 Configuration

The CAN transport layer is configured in the XML configuration file, like any other aspect of the XCP

ECU software. CAN configuration exists globally, per-session and per static DAQ list in the configuration

file.

Global CAN configuration

Within the XCP_GLOBALS_CAN XML element the following global configuration parameters must be

defined:

XCPCAN_ALLOW_EXTENDED_MSG_IDS This indicates whether extended CAN IDs are

supported.

XCPCAN_BAUDRATE The bus baudrate in Hz.

XCPCAN_SAMPLE_POINT The sample point as a percentage.


XCPCAN_SAMPLE_RATE This can be SINGLE or TRIPLE.

XCPCAN_BTL_CYCLES The number of BTL cycles in TSeg1 and TSeg2.

XCPCAN_SJW The synchronization jump width.

XCPCAN_SYNC_EDGE This can be SINGLE or DUAL.

Except for XCPCAN_ALLOW_EXTENDED_MSG_IDS, these parameter values are only used when

generating A2L fragments.

Per-session CAN configuration

Within the XCP_SESSION_CAN XML element the following per-session configuration parameters must

be defined:

XCPCAN_BROADCAST_MSGID The CAN message ID used by the XCP master for broadcasts.

XCPCAN_RX_MSGID The CAN message ID used by the XCP master to transmit CMD and DTO packets to the associated XCP session. This can be

over-ridden by the configuration of an individual static STIM list.

XCPCAN_TX_MSGID The CAN message ID used by the XCP slave to transmit RES, ERR, EV and DTO packets to the XCP master. This can be over-

ridden by the configuration of an individual static DAQ list.

XCPCAN_TX_MSGOBJID The ID of the CAN message object (i.e. hardware buffer) used

by the XCP slave to transmit RES, ERR, EV and DTO packets. This can be over-ridden by the configuration of an individual

static DAQ list.

XCPCAN_DYNDAQ_MSGID

(only required if dynamic DAQ lists are used)

The CAN message ID used to transmit/receive DTO packets for

dynamic DAQ/STIM lists to/from the XCP master. This can be over-ridden for an individual DAQ list at runtime by the XCP

command SET_DAQ_ID.

XCPCAN_DYNDAQ_MSGOBJID

(only required if dynamic DAQ lists are used)

The ID of the CAN message object (i.e. hardware buffer) used

by the XCP slave to transmit DTO packets for dynamic DAQ lists.

Per static DAQ list configuration

Within the optional XCP_DAQ_CAN XML element the following configuration parameters may be

specified for a static DAQ list:

XCPCAN_DAQ_MSGID The CAN message ID used by the XCP slave to transmit DTO packets (if this is a DAQ List) or receive DTO packets (if this is a STIM list).

This over-rides the per-session parameter XCPCAN_TX_MSGID (for

DAQ lists) or XCPCAN_TX_MSGID (for STIM lists).

XCPCAN_DAQ_MSGOBJID The ID of the CAN message object (i.e. hardware buffer) used by the XCP slave to transmit DTO packets for this DAQ list. This over-

rides the per-session parameter XCPCAN_TX_MSGOBJID.

4.7.3 XCP commands

The CAN transport layer supports the CAN-specific XCP commands GET_SLAVE_ID, GET_DAQ_ID and

SET_DAQ_ID as specified in the ASAM XCP standard. Note, however, that SET_DAQ_ID can only be

used for a dynamic DAQ list.

4.8 IP transport layer

4.8.1 Interaction with the IP driver

General

The XCP ECU software is designed to present a target-independent interface to the IP driver, though

this interface has been designed with the “sockets” API in mind.

Each XCP session can be configured to use either TCP/IP or UDP/IP, via the per-session XML

configuration parameter XCPIP_PROTOCOL.


The IP transport layer assumes that:

for TCP, each XCP master connects to a different port on the XCP slave;

for UDP, each XCP master sends data to a different UDP port on the XCP slave.

This means that the IP driver may need to listen on several ports: one per XCP session. For each XCP

session using TCP, the IP driver must listen on the port described by the per-session XML configuration

parameter XCPIP_PORT, and must accept only one connection on that port. For each XCP session using UDP, the IP driver must accept datagrams only on the port described by the per-session XML

configuration parameter XCPIP_PORT.

The port which was used to accept a connection (for TCP) or receive data (for UDP) is used thereafter

to identify the connection to the XCP-on-IP transport layer. The transport layer uses this information to associate the connection with an XCP session. Note that, when using TCP, the port which is used to

accept a connection is not the same as the port which is subsequently used to transmit and receive

data.

Therefore the APIs which are used to communicate between the IP driver and the IP transport layer

accept a port number as an argument.

Transmission

The XCP ECU software expects the IP driver to implement the following API:

void XcpApp_IpTransmit( uint16 port, Xcp_StatePtr8 pBytes, uint16 numBytes );

This API transmits the specified data buffer on the specified IP port. If both TCP and UDP protocols are

in use, the API must use the port number to deduce which protocol should be used.

XcpApp_IpTransmit() is permitted to queue the data buffer in hardware or software if it needs to

do so, but the XCP ECU software does not assume that any queuing will occur. However, the XCP ECU

software does assume that XcpApp_IpTransmit() cannot fail, i.e. the IP driver cannot refuse to

accept the data buffer altogether.

The XCP ECU software expects the IP driver to call the following API when the data buffer has been

transmitted successfully, or queued for future transmission:

void XcpIp_TxCallback( uint16 port, uint16 numTxBytes )

The XCP ECU software assumes that this API will be called either from within

XcpApp_IpTransmit() or from within the IP driver’s “TX confirmation” interrupt handler. If this is

not the case, changes may be necessary in the XCP ECU software.

Note that:

XcpIp_TxCallback() may call XcpApp_IpTransmit() again immediately.

Unlike the CAN driver, the IP driver is assumed to have only a single transmit buffer per port.

Therefore, the XCP-on-IP transport layer will not call XcpApp_IpTransmit() again for the

same port until XcpIp_TxCallback() has been called for the port.

When using TCP it is possible that the IP driver will be able to transmit some (but not all) of the data buffer. In this case the IP driver should call XcpIp_TxCallback() anyway,

specifying the number of bytes which were successfully transmitted. The XCP-on-IP transport

layer will automatically perform the necessary re-transmission.

Reception

The XCP ECU software expects the IP driver to call the following API when it receives an IP frame on a

port which is assigned to the XCP ECU software:

void XcpIp_RxCallback( uint16 chunkLen, uint8* pChunkData, uint16 port )

When using TCP, it is possible that the data received by the IP driver will not begin and/or end on an XCP message boundary. The XCP ECU software will handle this automatically: the IP driver just needs

to call XcpIp_RxCallback() whenever a chunk of data is received.

XcpIp_RxCallback() will process as much of the received data chunk as possible. This may result

in the reception of none, one or many XCP messages. If, while doing this, the XCP ECU software

encounters data which it does not recognise, it will silently discard the remainder of the data chunk.

The XCP ECU software assumes that XcpIp_RxCallback() will be called from within the IP driver’s

“RX indication” interrupt handler. If this function is not called from within an interrupt handler changes

may be necessary in the XCP ECU software.


Disconnection (TCP only)

The XCP specification requires that, when using TCP, the XCP ECU software must perform an “XCP

disconnect” if the TCP connection is closed. To allow this to happen, the IP driver must call the

following API if a TCP connection which is used by XCP is closed:

void XcpIp_OnTcpCxnClosed( uint16 port )

4.8.2 Configuration

The IP transport layer is configured in the XML configuration file, like any other aspect of the XCP ECU

software. IP configuration exists globally and per-session in the configuration file.

Global IP configuration

Within the XCP_GLOBALS_IP XML element exactly one of the following global configuration

parameters must be defined:

XCPIP_ADDRESS The dotted IP address ("xxx.xxx.xxx.xxx") of the XCP slave

XCPIP_HOSTNAME The IP hostname of the XCP slave

These parameters are only used when generating A2L fragments.

Per-session IP configuration

Within the XCP_SESSION_IP XML element the following per-session configuration parameters must

be defined:

XCPIP_PORT For TCP, this is the IP port used by the XCP master to connect to the XCP

slave session. For UDP, this is the IP port used by the XCP master to send

data to the XCP slave session.

XCPIP_MAXDTO This is the maximum length of a DTO, and hence the maximum amount of

data (including PID, timestamp, etc.) which can be transmitted or received in an ODT. The XCP ECU software allocates a buffer of

(XCPIP_MAXDTO+4) bytes for each ODT of each DAQ or STIM list, so

XCPIP_MAXDTO must be chosen carefully to provide sufficient measurement capacity without consuming too much RAM.

XCPIP_MAXDTO can be up to 65531 for TCP and 1472 for UDP.

XCPIP_MAXCTO This is the maximum length of a CTO. The XCP ECU software allocates:

one CTO buffer for XCP EVENT messages;

one CTO buffer for XCP RESP/ERR messages;

a number of buffers, configured by the global XML configuration

parameter XCP_NUM_RX_CMDBUF, for XCP CMD messages.

Each one of these buffers will contain (XCPIP_MAXCTO+4) bytes, so

XCPIP_MAXCTO must be chosen carefully to avoid consuming too much

RAM.

XCPIP_MAXCTO must have a value less than or equal to 255.

XCPIP_PROTOCOL This can have the value TCP or UDP, indicating the protocol which is used

for the XCP slave session.

4.8.3 XCP commands

The IP transport layer supports the no IP-specific XCP commands.

Reference 39

5 Reference

5.1 XML configuration file

The XCP ECU software requires the user to create an XML configuration file which is processed by a

configuration tool. Section 4 discusses the various parameters which can be used in the XML

configuration file.

The configuration tool validates the user’s XML configuration file against the XML schema xcp_conf.xsd which is distributed with the XCP ECU software. The schema is heavily commented

and is intended to be used as the authoritative reference for the expected format of the XML

configuration file

Several example XML configuration files are also distributed with the XCP ECU software. They describe

several different XCP sessions, each illustrating aspects of the configuration of the XCP ECU software.

5.2 Types defined by the XCP ECU software

The XCP ECU software defines the following publicly available types. They can be included via the

header files xcp_common.h and xcp_inf.h.

Type Description

uint8 uint16 uint32 Unsigned integers of various widths.

sint8 sint16 sint32 Signed integers of various widths.

uint Unsigned integer of the target’s natural width.

sint Signed integer of the target’s natural width.

Xcp_Addr_t This type is used to refer to all MTA addresses in the ECU. It points to a

single byte in memory.

Xcp_OdtEntryAddr_t This is the type of an “ODT entry address”. See the discussion in section 5.8.2 for more information about this type.

XcpCan_MsgObjId_t This type is used to refer to the ID of a CAN message object (i.e. a CAN

hardware buffer).

Xcp_CfgPtrn An instance of this type points to n bytes of memory in an address space of type XCP_CONFIG_TYPE (see section 6.2.2).

Xcp_StatePtrn An instance of this type points to n bytes of memory in an address

space of type XCP_STATE_TYPE (see section 6.2.3).

Xcp_Seed_t An array of instances of this type contains a seed, as outputted by the callback XcpApp_GetSeed().

Xcp_Key_t An array of instances of this type defines a key buffer, as outputted by

the callback XcpApp_GetKeyBuffer().

enum{...} Xcp_CalPageErr

This is used as the return type for callback functions which switch calibration pages:

CALPAGE_OK. The page switching request was completed

successfully.

CALPAGE_PAGEINVALID. The specified calibration page is

invalid.

CALPAGE_SEGINVALID. The specified calibration segment is invalid.

CALPAGE_REQUESTINVALID. The page switching request was

invalid for some other reason.

40 Reference

Type Description

enum{...}

Xcp_CalMemState

This is used as the return type for callback functions which access

calibration memory:

CALMEM_FINISHED. The request was completed successfully.

CALMEM_BUSY. The request is being processed

asynchronously; call XcpApp_CalMemGetRequestState() at a later time to get progress information.

CALMEM_OUTOFRAM. The request failed because not enough

RAM was available.

CALMEM_REJECTED. The request was rejected as being

temporarily impossible. The request can be re-tried later.

CALMEM_PAGENOTVALID. The request failed because it referred to an invalid calibration page.

CALMEM_SEGNOTVALID. The request failed because it referred

to an invalid calibration segment.

CALMEM_REQUESTNOTVALID. The request is invalid for some

other reason.

enum{...}

Xcp_ProgramState

This is used as the return type for callback functions which program

flash memory:

PROGRAM_FINISHED. The request was completed

successfully.

PROGRAM_BUSY. The request is being processed asynchronously; call XcpApp_ProgramGetRequestState()

at a later time to get progress information.

PROGRAM_REJECTED. The request was rejected as being temporarily impossible. The request can be re-tried later.

PROGRAM_BADADDRESS. The request was rejected because

the specified address is not programmable.

PROGRAM_INVALIDSTATE. The request was rejected because

the device is not in a state which permits flash programming.

5.3 APIs provided by the XCP ECU software

These APIs can be included via the header file xcp_pub.h.

XCP_Initialize

Syntax void Xcp_Initialize( void )

Description This function initializes the XCP ECU software. It must be called exactly once by

the user application before any XCP functionality can be used.

This function also starts any DAQ lists which are in RESUME mode.

XCP_CmdProcessor

Syntax void Xcp_CmdProcessor( void )

Description The user application is required to call this function regularly in order to allow

the XCP ECU software to send and receive XCP packets for all XCP sessions.

The user must declare the period with which this API is called in the XML

configuration using the global parameter XCP_POLL_INTERVAL (with units of

1ms), so that the XCP ECU software is aware how often this API is called.

Reference 41

Xcp_DoDaqForEvent

Syntax uint Xcp_DoDaqForEvent( uint eventId )

Parameters

(in)

eventId The ID (or “number”) of an XCP event.

Return value If this function finds no errors but nevertheless does not acquire any measurement data it returns XCPEVENT_DAQSTIM_NOT_EXECUTED. This

occurs if none of the DAQ lists associated with the specified event is running, or

if none of the DAQ lists is configured with at least one measurement value.

Otherwise, this function returns any bitwise combination of the following:

XCPEVENT_DAQSTIM_EXECUTED. At least one measurement value

was acquired successfully.

XCPEVENT_DAQ_OVERLOAD. At least one of the DAQ lists associated

with the specified event is in an overload situation, as described in

section 4.3.7.

XCPEVENT_DTO_OVERFILL. At least one of the DAQ lists associated

with the specified event has been over-filled, as described in section

4.3.6.

Note that these values are not mutually exclusive; it may even be the case that

all three apply to one and the same DAQ list.

Description This function causes the XCP ECU software to run any DAQ lists which are associated with the specified event in any XCP session. Acquired data will be

transmitted, or queued for transmission, to the XCP master. The user application

must call this function whenever the specified event occurs.

If an over-filled DTO is processed by this function, the return value will contain

the flag XCPEVENT_DTO_OVERFILL. The function ignores any ODT entries

which would lie partly or completely beyond the end of an over-filled DTO. The other ODT entries in the over-filled DTO are processed as usual.

If an overloaded DAQ list is identified by this function, the return value will

contain the flag XCPEVENT_DAQ_OVERLOAD. In such a situation the function

aborts transmission of the current cycle of the affected DAQ list and discards

any untransmitted measurement data from that cycle.

This function is also available via a macro-based equivalent:

Xcp_DoDaqForEvent_<Event short name>()

See the section 4.3.8 for a discussion on the consistency of the data sampled by

this function.

42 Reference

Xcp_DoStimForEvent

Syntax uint Xcp_DoStimForEvent( uint eventId )

Parameters

(in)

eventId The ID (or “number”) of an XCP event.

Return value If this function finds no errors but nevertheless does not write any data to the ECU’s memory it returns XCPEVENT_DAQSTIM_NOT_EXECUTED. This occurs if

none of the STIM lists associated with the specified event is running, or if none

of the STIM lists is configured with at least one measurement value.

Otherwise, this function returns any bitwise combination of the following:

XCPEVENT_DAQSTIM_EXECUTED. At least one of the STIM lists

associated with the specified event was successfully written to the ECU's memory.

XCPEVENT_MISSING_DTO. At least one of the STIM lists associated

with the specified event was missing a DTO. The consequences of this are described in section 4.4.3.

XCPEVENT_DTO_OVERFILL. At least one of the STIM lists associated

with the specified event has been over-filled, as described in section 4.3.6.

Note that these values are not mutually exclusive, since the specified event may

be associated with several STIM lists. Furthermore, XCPEVENT_DAQSTIM_EXECUTED and XCPEVENT_DTO_OVERFILL may apply

to one and the same STIM list.

Description This function causes the XCP ECU software to run any STIM lists which are associated with the specified event in any XCP session. The user application

must call this function whenever the specified event occurs.

STIM data is received asynchronously and buffered by the XCP ECU software. When Xcp_DoStimForEvent() is called, the buffered STIM data is written

directly to the ECU’s memory.

Before Xcp_DoStimForEvent() writes the data from a STIM list to ECU

memory, it checks that all the DTO packets of the STIM list have been received.

If this is not the case, the function’s return value will contain the flag

XCPEVENT_MISSING_DTO. No data from the affected STIM list is written to the ECU memory. All other STIM lists associated with the specified event are

processed as usual.

If the missing STIM DTO packets have just been delayed, Xcp_DoStimForEvent() retains those packets which were successfully

received, allowing the full STIM list to be processed on the next invocation.

However, if the missing STIM DTO packets have been lost entirely, Xcp_DoStimForEvent() discards those STIM DTO packets which were

received for the current cycle of the STIM list.

If an over-filled DTO is processed by Xcp_DoStimForEvent(), the function’s return value will contain the flag XCPEVENT_DTO_OVERFILL. The function

ignores any ODT entries which would lie partly or completely beyond the end of

an over-filled DTO. The other ODT entries in the over-filled DTO are processed

as usual.

This function is also available via a macro-based equivalent:

Xcp_DoStimForEvent_<Event short name>()

See the section 4.4.3 for a discussion on the consistency of the data written to ECU memory by this function.

5.4 APIs provided by the CAN transport layer

These APIs can be included via the header xcpcan_callbacks.h.

Reference 43

XcpCan_RxCallback

Syntax void XcpCan_RxCallback(

uint32 msgId,

uint8 msgLen,

uint8* pMsgData

)

Parameters (in)

msgId The CAN message ID of the received message.

msgLen The length of the received message payload. This can be set to 8 invariably, but doing so will cause inefficient

processing.

pMsgData The received message payload. When the function returns this buffer can be discarded.

Description The CAN driver must call this function when it receives a CAN message on a

CAN message object which is reserved for the XCP ECU software.

See section 4.7.1 for a discussion of this function.

XcpCan_TxCallback

Syntax void XcpCan_TxCallback( XcpCan_MsgObjId_t msgObjId )

Parameters (in)

msgObjId The ID of the CAN message object which has successfully transmitted a CAN message. If only one CAN message

object is available this ID must match the message object

ID specified in the XML configuration file.

Description The CAN driver must call this function when a CAN message object which is reserved for the XCP ECU software successfully transmits a CAN message and

therefore becomes free to be used again.

This function identifies and transmits the highest priority CAN message (i.e. the message with the lowest CAN ID) which is waiting to be sent on the newly-freed

message object.


44 Reference

5.5 APIs provided by the IP transport layer

These APIs can be included via the header xcpip_callbacks.h.

XcpIp_RxCallback

Syntax void XcpIp_RxCallback(

uint16 chunkLen,

uint8* pChunkData,

uint16 port

)

Parameters (in)

chunkLen The number of bytes at pChunkData.

pChunkData The payload of the received IP frame. The caller does not need to interpret the payload: the entire payload should be

passed to XcpIp_RxCallback().

The caller can discard this data after the function returns.

port For TCP: the port which listened for the connection which

received the data. Note that this may not be the same as

the port which actually received the data.

For UDP: the port which received the data.

Description The IP driver must call this function when it receives a frame on an IP port

which is reserved for the XCP ECU software.


XcpIp_TxCallback

Syntax void XcpIp_TxCallback(

uint16 port,

uint16 numTxBytes

)

Parameters (in)

port For TCP: the port which listened for the connection which was used to transmit the data. Note that this may not be

the same as the port which actually transmitted the data.

For UDP: the port which transmitted the data.

numTxBytes The number of bytes which were transmitted during the latest call to XcpApp_IpTransmit(). For TCP, this may

be less than the total number of bytes which were supplied

to XcpApp_IpTransmit().

Description This function must be called by the IP driver during (or after) a call to

XcpApp_IpTransmit() to indicate that a number of bytes have been

successfully transmitted (or queued for transmission) on the identified IP connection.

This function identifies and transmits the next data buffer which is waiting to be

sent on the identified IP connection.

See section 4.8.1 for a further discussion of this function. Note particularly that

XcpIp_TxCallback() may call XcpApp_IpTransmit() again immediately.

Reference 45

XcpIp_OnTcpCxnClosed

Syntax void XcpIp_OnTcpCxnClosed( uint16 port )

Parameters

(in)

port The port which listened for the connection which is now

closed.

Description This function must be called by the IP driver whenever a TCP connection which is used for XCP is closed. The function ensures that the corresponding XCP

session is disconnected.


5.6 APIs required by the XCP ECU software

These APIs must be implemented by the user application so that the XCP ECU software can access various area of ECU-specific functionality. The file Examples\xcp_callbacks.c contains an empty

implementation of each API.

Note, however, that if a certain area of functionality (e.g. flash programming) is not required then the

associated callback APIs can be given trivial implementations or, in some cases, omitted altogether.

The documentation below explains which APIs can be implemented trivially or omitted.

The APIs are declared in the files xcp_inf.h, xcpcan_inf.h, and xcpip_inf.h.

5.6.1 General functions

XcpApp_OnUserDefinedCxn

Syntax void XcpApp_OnUserDefinedCxn( uint sessionId )

Parameters

(in)

sessionId The ID of the XCP session which is connecting.

Description The XCP ECU software calls this function when the CONNECT command is received with a user-defined connection mode. It does not expect this function

to take any particular actions.

Since the XCP ECU software can support multiple XCP sessions it is possible for

this function to be called more than once in succession.

XcpApp_OnNormalCxn

Syntax void XcpApp_OnNormalCxn( uint sessionId )

Parameters

(in)

sessionId The ID of the XCP session which is connecting.

Description The XCP ECU software calls this function when the CONNECT command is

received with a normal connection mode. It does not expect this function to take any particular actions.



XcpApp_OnDisconnect

Syntax void XcpApp_OnDisconnect( uint sessionId )

Parameters (in)

sessionId The ID of the XCP session which is disconnecting.

Description The XCP ECU software calls this function when the DISCONNECT command is

received, or when disconnection occurs for any other reason. It does not expect

this function to take any particular actions.



46 Reference

XcpApp_UserCmd

Syntax void XcpApp_UserCmd(

uint sessionId,

Xcp_StatePtr8 pRxPacket,

Xcp_StatePtr8 pTxPacket,

uint* pTxPacketSize

)

Parameters

(in)

sessionId The index of the session which received the USER_CMD.

pRxPacket The command packet, exactly as received by the XCP ECU

software. The first byte is 0xf1; the second byte is the sub-

command code; subsequent bytes are the sub-command parameters (if any).

Parameters

(out)

pTxPacket The response packet. When using CAN, this buffer contains

space for 8 bytes; when using IP, the buffer's size is determined by the per-session XML configuration parameter

XCPIP_MAXCTO. This buffer must be filled with a valid XCP

RES or ERR packet, as described in sections 1.1.3.2 and 1.1.3.3 of part 2 of the XCP specification.

pTxPacketSize The number of bytes actually used at pTxPacket.

Description The XCP ECU software calls this function when the USER_CMD command is

received. The XCP ECU software expects this function to process the USER_CMD and set the function’s output parameters appropriately. The XCP ECU software

performs no validation on either the input parameters or the output parameters.

The user must take care to output a valid XCP RES or ERR packet from this function, otherwise errors may occur in the XCP master.

If the global XML configuration parameter XCP_ENABLE_USER_CMD is not

defined, or is set to no, this function does not need to be defined.

5.6.2 Calibration page switching functions

If a project’s XML configuration file does not contain any XCP_SEGMENT_LIST elements, or if the

global XML configuration parameter XCP_ENABLE_CALPAG is set to no, these functions do not need

to be defined.

Reference 47

XcpApp_SetEcuCalPage

Syntax Xcp_CalPageErr XcpApp_SetEcuCalPage(

uint8 dataSegment,

uint8 calPage

)

Parameters

(in)

dataSegment The segment whose calibration page is to be changed.

calPage The new “ECU” calibration page for the segment.

Return value See the description of Xcp_CalPageErr in section 5.2.

Description The XCP ECU software expects this function to set the current "ECU" calibration page for a specified segment of calibration memory.

The XCP ECU software relies on this function to determine whether the given

segment number and page number are valid. Therefore this function should always validate its arguments.

The XCP ECU software does not check page access permissions before calling

this function. Therefore this function should check these permissions and return CALPAGE_REQUESTINVALID if there is a problem.

XcpApp_SetEcuCalPageAllSegs

Syntax Xcp_CalPageErr XcpApp_SetEcuCalPageAllSegs(

uint8 calPage

)

Parameters (in)

calPage The new “ECU” page for all calibration segments.


Description The XCP ECU software expects this function to set the current "ECU" calibration

page for all segments of calibration memory.


page number is valid. Therefore this function should always validate its

argument.


this function. Therefore this function should check these permissions and return

CALPAGE_REQUESTINVALID if there is a problem.

48 Reference

XcpApp_SetToolCalPage

Syntax Xcp_CalPageErr XcpApp_SetToolCalPage(

uint8 dataSegment,

uint8 calPage

)

Parameters

(in)

dataSegment The segment whose calibration page is to be changed.

calPage The new “tool” (or “XCP”) calibration page for the segment.


Description The XCP ECU software expects this function to set the current "tool" (or “XCP”) calibration page for a specified segment of calibration memory.


segment number and page number are valid. Therefore this function should always validate its arguments.



The calibration page set by this function should be used during the

implementation of all XCP callback functions which read or write to the specified segment of calibration memory, such as XcpApp_CalMemWrite() or

XcpApp_CalMemGetChecksum().

XcpApp_SetToolCalPageAllSegs

Syntax Xcp_CalPageErr XcpApp_SetToolCalPageAllSegs(

uint8 calPage

)

Parameters

(in)

calPage The new “tool” (or “XCP”) page for all calibration segments.


Description The XCP ECU software expects this function to set the current "tool" (or “XCP”) calibration page for all segments of calibration memory.


page number is valid. Therefore this function should always validate its argument.



The calibration page set by this function should be used during the

implementation of all XCP callback functions which read or write to calibration

memory, such as XcpApp_CalMemWrite() or

XcpApp_CalMemGetChecksum().

Reference 49

XcpApp_GetEcuCalPage

Syntax uint8 XcpApp_GetEcuCalPage( uint8 dataSegment )

Parameters

(in)

dataSegment The calibration segment whose “ECU” page is required.

Return value The current “ECU” page for the given segment.

Description The XCP ECU software expects this function to return the current "ECU"

calibration page for a given calibration segment.

The XCP ECU software tracks the current "tool" calibration page for each segment to allow it to implement page freezing. Therefore there is no analogous

XcpApp_GetToolCalPage() function.

5.6.3 Memory access functions

XcpApp_CalMemWrite

Syntax Xcp_CalMemState XcpApp_CalMemWrite(

Xcp_Addr_t mta,

uint32 numBytes,

Xcp_StatePtr8 pBytes

)

Parameters

(in)

mta The address to which data should be written.

numBytes The number of bytes at pBytes.

pBytes The data to be written to mta.

Return value See the description of Xcp_CalMemState in section 5.2.

Description The XCP ECU software expects this function to write data to calibration memory.

The function is expected to decide for itself within which calibration segment the

address mta lies, and then write to the current “tool” page for that segment, as

set by either XcpApp_SetToolCalPage() or XcpApp_SetToolCalPageAllSegs().

Be aware that this function may not refer to an address within calibration

memory at all. For example, it may be used to download code in preparation for flash programming (see the ASAM XCP specification for PROGRAM_PREPARE).

If a project’s XML configuration file does not contain any XCP_SEGMENT_LIST

elements, or if the global XML configuration parameter XCP_ENABLE_CALPAG is set to no, this function does not need to be defined.

50 Reference

XcpApp_CalMemRead

Syntax Xcp_CalMemState XcpApp_CalMemRead(

Xcp_Addr_t mta,

uint32 numBytes,


)

Parameters (in)

mta The address from which data should be read.

numBytes The number of bytes to be read.

pBytes A buffer to hold the bytes which are read.


Description The XCP ECU software expects this function to read data from calibration

memory.


address mta lies, and then read from the current “tool” page for that segment,

as set by either XcpApp_SetToolCalPage() or XcpApp_SetToolCalPageAllSegs().

Be aware that this function may not refer to an address within calibration

memory at all. For example, it may be used to upload the XCP slave’s identifier (see the ASAM XCP specification for GET_ID).

XcpApp_CalMemModifyBits

Syntax Xcp_CalMemState XcpApp_CalMemModifyBits(

Xcp_Addr_t mta,

uint8 numShiftBits,

uint16 andMask,

uint16 xorMask

)

Parameters

(in)

mta The address at which the bits should be manipulated.

numShiftBits See the specification of the MODIFY_BITS XCP command.

andMask See the specification of the MODIFY_BITS XCP command.

xorMask See the specification of the MODIFY_BITS XCP command.


Description The XCP ECU software expects this function to manipulate the bits at a given

address according to the algorithm given in the ASAM XCP specification for the MODIFY_BITS command.


address mta lies, and then access the current “tool” page for that segment, as set by either XcpApp_SetToolCalPage() or

XcpApp_SetToolCalPageAllSegs().

If a project’s XML configuration file does not contain any XCP_SEGMENT_LIST elements, or if the global XML configuration parameter XCP_ENABLE_CALPAG is

set to no, this function does not need to be defined.

Reference 51

XcpApp_CalPageCopy

Syntax Xcp_CalMemState XcpApp_CalPageCopy(

uint8 destSegmentId,

uint8 destPageId,

uint8 sourceSegmentId,

uint8 sourcePageId

)

Parameters

(in)

destSegmentId The destination segment for the copy operation.

destPageId The destination page for the copy operation.

sourceSegmentId The source segment for the copy operation.

sourcePageId The source page for the copy operation.


Description The XCP ECU software expects this function to copy the contents of the specified source page to the specified destination page.


elements, or if the global XML configuration parameter XCP_ENABLE_CALPAG is set to no, this function does not need to be defined.

XcpApp_CalMemGetChecksum

Syntax Xcp_CalMemState XcpApp_CalMemGetChecksum(

Xcp_Addr_t address,

uint32 numBytes,

Xcp_StatePtr8 pChecksumType,

Xcp_StatePtr32 pChecksum

)

Parameters (in)

address The address of the memory region for the checksum.

numBytes The size of the memory region for the checksum. The XCP ECU software will have validated this parameter already.

Parameters

(out)

pChecksumType The type of checksum which was calculated. This should be

one of the types described in section 4.5.5.

pChecksum The checksum result.


Description The XCP ECU software expects this function to calculate a checksum over a

region of memory.

The function can use any of the checksum types defined for the XCP

BUILD_CHECKSUM command, except the USER_DEFINED type.


checksum region lies, and then access the current “tool” page for that segment, as set by either XcpApp_SetToolCalPage() or

XcpApp_SetToolCalPageAllSegs().

52 Reference

XcpApp_CalMemGetRequestState

Syntax Xcp_CalMemState XcpApp_CalMemGetRequestState( void )


Description If a previous call to XcpApp_CalMemXxx() has returned CALMEM_BUSY, at a

later point in time the XCP ECU software may call this function to get information on the progress of the previous request.

If, in fact, all calibration callbacks are completed synchronously then this

function should just return CALMEM_FINISHED.

This function is also discussed in section 4.5.6.

XcpApp_CalSegFreeze

Syntax Xcp_CalMemState XcpApp_CalSegFreeze(

uint8 segmentId,

uint8 initSegmentId

)

Parameters

(in)

segmentId The segment which is to be frozen.

initSegmentId The INIT_SEGMENT for the freeze request.


Description The XCP ECU software expects this function to copy the contents of the current

"tool" page of the specified segment into page 0 of the specified INIT_SEGMENT.

This function may be implemented as a special case of

XcpApp_CalPageCopy().


elements, or if the global XML configuration parameter XCP_ENABLE_CALPAG is

set to no, or if the global XML configuration parameter XCP_ENABLE_PAGE_FREEZING is set to no, then this function does not need to

be defined.

5.6.4 Measurement functions

XcpApp_GetTimestamp

Syntax uint32 XcpApp_GetTimestamp( void )

Return value The current value of a counter which has the period of the DAQ clock. The value

must use at least the number of bytes indicated by the largest value of

XCP_TIMESTAMP_SIZE in the XCP ECU software's configuration. The counter must be able to run for at least several seconds without wrapping.

Description The XCP ECU software expects this function to return the current value of a

counter which has the period of the DAQ clock. The preprocessor symbols

XCP_TIMESTAMP_UNIT and XCP_TIMESTAMP_TICKS indicate the required period of the counter and are described in section 4.3.1.

If no XCP session requires a DAQ clock this function can simply return 0.

Reference 53

XcpApp_ConvertAddress

Syntax Xcp_Addr_t XcpApp_ConvertAddress(

uint32 address,

uint8 extension

)

Parameters

(in)

address The address to be converted.

extension The address extension to be converted.

Return value Either:

A pointer to the specified location in memory. The pointer must refer to

a single byte in memory.

0 if the XCP tool is not permitted to access the specified address, or if the specified address is invalid.

Description The XCP ECU software expects this function to convert an address of the form

(address, extension) as supplied by an XCP command into a pointer to the

specified memory location.

The (address, extension) pair can be supplied by any of the following XCP

commands:

SET_MTA

SHORT_UPLOAD

Therefore the address may refer to a memory location in any type of memory.

A trivial conversion returns address (cast to Xcp_Addr_t) and ignores extension.

XcpApp_IsRegionMeasurable

Syntax sint XcpApp_IsRegionMeasurable(

uint32 address,

uint8 extension,

uint32 numBytes

)

Parameters

(in)

address The address of the memory region to be measured or

stimulated.

extension The address extension of the memory region to be measured or stimulated.

numBytes The length of the memory region to be measured or stimulated.

Return value A Boolean indicating whether the specified memory region can be measured

and/or stimulated.

Description The XCP ECU software expects this function to indicate whether the specified

memory region can be measured and/or stimulated as part of a DAQ list.

5.6.5 Non-volatile memory functions

If a project’s XML configuration file does not configure any DAQ lists which can be RESUMEd, or if the

global XML configuration parameter XCP_ENABLE_RESUME is set to no, these functions do not need

to be defined.

54 Reference

XcpApp_NvMemWrite

Syntax void XcpApp_NvMemWrite(

uint offset,

Xcp_StatePtr8 pData,

uint numBytes

)

Parameters (in)

offset The offset, measured in bytes, within the NV memory region at which the data is to be written.

pData The data to be written to the NV memory region.

numBytes The number of bytes at pData.

Description The XCP ECU software expects this function to write data to a pre-allocated

region of non-volatile (NV) memory.

The total size of the region, which must be allocated by the user application, is

given by the preprocessor symbol XCP_NV_REGION_SIZE.

XcpApp_NvMemRead

Syntax void XcpApp_NvMemRead(

uint offset,

Xcp_StatePtr8 pData,

uint numBytes

)

Parameters (in)

offset The offset, measured in bytes, within the NV memory region from which the data is to be read.

pData A buffer to receive the data which is read.

numBytes The number of bytes to be read.

Description The XCP ECU software expects this function to read data from a pre-allocated

region of non-volatile (NV) memory.

The total size of the region, which must be allocated by the user application, is

given by the preprocessor symbol XCP_NV_REGION_SIZE.

XcpApp_NvMemClear

Syntax void XcpApp_NvMemClear(

uint offset,

uint numBytes

)

Parameters

(in)

offset The offset, measured in bytes, within the NV memory region at

which the data is to be cleared.

numBytes The number of bytes to be cleared.

Description The XCP ECU software expects this function to clear data from the pre-allocated

region of non-volatile (NV) memory. Cleared data should be set to 0.

Reference 55

5.6.6 Seed and key functions

If a project’s XML configuration file does not configure any XCP resources to be protected with “seed

and key”, or if the global XML parameter XCP_ENABLE_SEEDNKEY is set to no, then these functions

do not need to be defined.

Each of these functions has an argument which refers to an XCP resource. This argument is encoded in

the same manner as described in the ASAM XCP specification of the GET_STATUS command:

Resource Value

PGM 0x10

STIM 0x08

DAQ 0x04

CAL/PAG 0x01

XcpApp_GetSeed

Syntax void XcpApp_GetSeed(

uint sessionId,

uint8 resource,

Xcp_Seed_t** ppSeed,

Xcp_StatePtr8 pSeedLen

)

Parameters (in)

sessionId The XCP session which is requesting a seed.

resource The XCP resource with which the seed is associated. See the start of this section for a description of the possible resource

values.

Parameters

(out)

ppSeed A buffer containing the seed.

pSeedLen The length of the seed.

Description The XCP ECU software expects this function to calculate a seed for the specified

ECU resource.

The buffer which contains the seed is owned by this function and must be retained at least until:

either this function is called again with the same sessionId;

or the function XcpApp_GetKeyBuffer() is called with the same sessionId.

This function must be able to support different seed buffers simultaneously for

each session, but not for each resource within a session.

56 Reference

XcpApp_GetKeyBuffer

Syntax void XcpApp_GetKeyBuffer(

uint sessionId,

uint8 resource,

Xcp_Key_t** ppKey,

uint8 keyLen

)

Parameters

(in)

sessionId The XCP session which is requesting a key buffer.

resource The XCP resource with which the key buffer is associated. See

the start of this section for a description of the possible resource

values.

keyLen The length of the key buffer.

Parameters

(out)

ppKey The buffer in which the key is to be stored.

Description The XCP ECU software expects this function to allocate a buffer to be used by the XCP ECU software to store a key. The key corresponds to the seed provided

by the previous call to XcpApp_GetSeed().

The buffer which contains the key is owned by this function and must be retained at least until:

either this function is called again with the same sessionId;

or the function XcpApp_UnlockResource() is called with the same sessionId;

or the function XcpApp_GetSeed() is called with the same

sessionId.

The function must be able to support different key buffers simultaneously for

each session, but not for each resource within a session.

XcpApp_UnlockResource

Syntax sint XcpApp_UnlockResource(

uint sessionId,

uint8 resource

)

Parameters

(in)

sessionId The XCP session which is requesting the unlock.

resource The XCP resource which is to be unlocked. See the start of this

section for a description of the possible resource values.

Return value A boolean indicating whether the specified resource should be unlocked for the

specified session.

Description The XCP ECU software expects this function to check whether the previous seed

issued by XcpApp_GetSeed() (for the same session) corresponds to the key now present in the previous buffer issued by XcpApp_GetKeyBuffer() (for

the same session).

5.6.7 Flashing functions

If a project’s XML configuration file does not contain a XCP_SECTOR_LIST element, or if the global

XML configuration parameter XCP_ENABLE_PGM is set to no, these functions do not need to be

defined.

Reference 57

XcpApp_ProgramStart

Syntax Xcp_ProgramState XcpApp_ProgramStart( Xcp_Addr_t mta )

Parameters

(in)

mta The current MTA.

Return value See the description of Xcp_ProgramState in section 5.2.

Description The XCP ECU software expects this function to perform the operations described

in the ASAM XCP specification for the PROGRAM_START command.

XcpApp_ProgramPrepare

Syntax Xcp_ProgramState XcpApp_ProgramPrepare(

Xcp_Addr_t mta,

uint16 codeSize

)

Parameters

(in)


codeSize The size of the code block which will be downloaded to the MTA

after the PROGRAM_PREPARE command completes.



in the ASAM XCP specification for the PROGRAM_PREPARE command.

XcpApp_ProgramClear

Syntax Xcp_ProgramState XcpApp_ProgramClear(

Xcp_Addr_t mta,

uint32 length

)

Parameters

(in)


length The length of the range to be cleared.


Description The XCP ECU software expects this function to perform the operations described in the ASAM XCP specification for the PROGRAM_CLEAR command.

58 Reference

XcpApp_Program

Syntax Xcp_ProgramState XcpApp_Program(

Xcp_Addr_t mta,

uint8 numBytes,


)

Parameters (in)

mta The address at which data should be programmed.

numBytes The number of bytes at pBytes. This may be 0 to indicate the end of a memory segment.

pBytes The data to be programmed.


Description The XCP ECU software expects this function to program data into flash memory.

The function may program the data immediately, or it may buffer the data and

program an entire block on a subsequent invocation.

XcpApp_ProgramReset

Syntax Xcp_ProgramState XcpApp_ProgramReset( void )


in the ASAM XCP specification for the PROGRAM_RESET command.

This function may reset the ECU.

XcpApp_ProgramGetRequestState

Syntax Xcp_ProgramState XcpApp_ProgramGetRequestState( void )


Description If a previous call to XcpApp_ProgramXxx() has returned PROGRAM_BUSY, at a later point in time the XCP ECU software may call this function to get

information on the progress of the previous request.

If, in fact, all flash programming callbacks are completed synchronously then this function should just return PROGRAM_FINISHED.

Reference 59

5.6.8 CAN functions

XcpApp_CanTransmit

Syntax void XcpApp_CanTransmit(

XcpCan_MsgObjId_t msgObjId,

uint32 msgId,

uint numBytes,


)

Parameters (in)

msgObjId The ID of the CAN message object (i.e. CAN hardware buffer) to be used to send the message. The CAN driver can discard this if

there is only one message object available.

msgId The CAN message ID to be used for the message. The CAN

driver can discard this if there is a 1-to-1 mapping from

msgObjId to msgId.


pBytes The payload of the CAN message. The XCP ECU software will

discard this after this function returns.

Description This function must transmit the specified CAN message on the specified CAN

message object. The CAN driver is permitted to queue the message in hardware

or software if it needs to do so, but the XCP ECU software does not assume that any queuing will occur.

The XCP ECU software assumes that it has exclusive use of the specified CAN

message object.

60 Reference

5.6.9 IP functions

XcpApp_IpTransmit

Syntax void XcpApp_IpTransmit(

uint16 port,

Xcp_StatePtr8 pBytes,

uint16 numBytes

)

Parameters

(in)

port For TCP: the port which listened for the connection which is to

be used to transmit the data. Note that this may not be the same as the port which actually transmits the data.

For UDP: the port which is to be used to transmit the data.

pBytes The data to be transmitted.


Description This function must transmit the specified bytes on the IP connection identified by port.

The IP driver is permitted to queue the data bytes in hardware or software if it

needs to do so, but the XCP ECU software does not assume that any queuing will occur.

If the IP driver can immediately determine how many data bytes were

successfully transmitted (or queued), it should call XcpIp_TxCallback() as described in section 0.

The XCP ECU software assumes that it has exclusive use of the specified IP port.

5.7 Integrating the XCP ECU software into an ECU application

5.7.1 Overview

In order to use the XCP ECU software within an ECU application the user must call the various API

functions described in sections 5.3, 5.4 and 5.5.

The XCP ECU software needs to access various other ECU drivers, e.g. the CAN driver, the calibration

memory driver, etc. To achieve this, the XCP ECU software expects the user to implement the callbacks

described in section 5.6 which will access the other drivers on behalf of the XCP ECU software.

The information which the XCP ECU software supplies to each callback, and the way in which it expects

each callback to behave are intended to be target-independent, to enable the callbacks to be

implemented no matter the characteristics of the other ECU drivers on a particular target.

If, however, on a particular target it is impossible to write a callback which behaves as the XCP ECU software expects it may be necessary to modify the XCP ECU software code itself, to change the way

in which the callback is used.

5.7.2 Software environment

If the XCP ECU software is being used in an ECU application which was built with ETAS ASCET, or

which contains ETAS RTA-OSEK or RTA-OS, the XCP ECU software can take advantage of types and

APIs defined by ASCET and/or RTA-OSEK and/or RTA-OS.

In order to achieve this the global XML configuration parameter XCP_ENVIRONMENT must be set to

one of the following values:

The value XCP_ENV_ASCET indicates that ETAS ASCET (and implicitly RTA-OSEK) is used to

build the ECU application.

The value XCP_ENV_RTAOSEK4 indicates that ETAS RTA-OSEK v4 is used standalone (i.e.

without ASCET) in the ECU application.

The value XCP_ENV_RTAOSEK5 indicates that ETAS RTA-OSEK v5 is used standalone (i.e.

without ASCET) in the ECU application.

Reference 61

The value XCP_ENV_RTAOS indicates that ETAS RTA-OS is used standalone (i.e. without

ASCET) in the ECU application.

The value XCP_ENV_NOT_ETAS indicates that neither RTA-OSEK nor RTA-OS nor ASCET is in

use.

Choosing a value other than XCP_ENV_NOT_ETAS allows the file xcp_target.h to obtain various target-specific definitions automatically from ASCET and/or RTA header files. Choosing

XCP_ENV_NOT_ETAS means that the user needs to create those target-specific definitions manually in

xcp_target.h; this process is discussed further in sections 6.2.5 and 6.2.8.

5.7.3 XCP ECU software header files

The following header files are provided for use by the ECU application:

File Usage

xcp.h Use this to declare API functions provided by the XCP ECU software.

xcp_common.h Use this to declare basic types used by the XCP ECU software.

xcp_inf.h,

xcpcan_inf.h and

xcpip_inf.h

Use these to declare callback functions which the user application is

expected to implement.

xcp_auto_confdefs.h

(generated by configuration

tool)

Use this to define preprocessor symbols generated from the XML configuration file. Many of these are not required by the ECU

application, but some, such as XCP_NV_REGION_SIZE, are

relevant.

xcpcan_auto_confpriv.h

(generated by configuration

tool)

Use this to define CAN-specific preprocessor symbols generated

from the XML configuration file, e.g. symbols for the various CAN

message IDs which are configured.

5.7.4 Building the XCP ECU software

The XCP ECU software is distributed as source code and therefore must be compiled before it can be

used in an ECU application. The following steps must be taken in the build process of the ECU

application:

1. Process the project’s XCP configuration file using the configuration tool, as described in

section 4.1.

2. Compile the C files generated by the configuration tool: xcp_auto_conf.c and

xcpcan_auto_conf.c or xcpip_auto_conf.c.

3. Compile the C files which are distributed in the following directories in the XCP ECU software

installation:

XcpDriver\

CanTransport\ or IpTransport\

TargetSpecific\<target name>, where <target name> corresponds to the target in

use.

4. Compile any other files in the ECU application which include header files generated by the

configuration tool.

5. Link the compiled object files into the ECU application.

The following makefile fragments exist to help incorporate these steps into the build process of the

ECU application. They are written for GNU make v3.81:

CanTransport\CanTransport.mak. This declares the C files which implement the CAN

transport layer.

IpTransport\IpTransport.mak. This declares the C files which implement the IP

transport layer.

XcpSlaveDriver\XcpDriver.mak. This declares the C files which implement the XCP

slave driver.

Any target-specific considerations (such as required compiler options, etc.) are described in section 11.

62 Reference

The file xcp_auto_confdefs.h, which is generated by the configuration tool, defines the pre-

processor symbol XCP_ENABLE if at least one XCP session is enabled in the XML configuration file. All

the .c files which are part of the XCP ECU software (including the generated .c files) compile their

content conditionally on this symbol. Therefore if no XCP sessions are enabled no XCP code will be

compiled.

If it is possible for no XCP sessions to be enabled the user application should also use the pre-

processor symbol XCP_ENABLE to avoid calling XCP API functions which are not defined. For example:

#ifdef XCP_ENABLE

/* Initialise the XCP ECU software. */

Xcp_Initialize();

#endif

5.8 Optimising the resource usage of the XCP ECU software

5.8.1 Optimising DTO layout

When the XCP ECU software accesses a DTO in memory it always begins on a natural boundary, as

chosen by the compiler. Data within a DTO is laid out in the following order:

The DTO begins with a 1-byte PID.

The first DTO in a DAQ list contains the timestamp, either 0, 1, 2 or 4 bytes as configured.

Thereafter the DTO contains ODT entries in order of their IDs. Usually, this corresponds to

the order in which the associated variables are assigned to a raster in the XCP master.

Some microcontrollers perform more poorly when copying data into locations which are not aligned in a preferred manner. For optimum performance, care should be taken to assign ODT entries to an ODT

in an order which will ensure that the associated DTO is laid out in a manner which will avoid any

limitations of the target microcontroller.

5.8.2 Optimising storage of ODT entry properties

The following properties of an ODT entry can be set at runtime via the XCP WRITE_DAQ command:

the address of the data to be measured (or stimulated);

one of:

o the number of bytes of data to be measured (or stimulated) at the specified address

(this can be from 1 to 4 (for CAN) or 127 (for IP));

o a bit offset specifying the location of the bit to be measured (or stimulated) at the specified address. (According to the XCP specification, the bit offset can be from 0 to

31).

If a bit offset is specified, the implementation of WRITE_DAQ adjusts the specified address and offset

so that the offset is between 0 and 7 (inclusive) instead of 0 and 31. It is possible to do this because

the XCP slave driver supports “byte” address granularity. The adjustment is made for two reasons:

less space is required to store the bit offset;

it allows the measurement or stimulation to be performed with a byte access instead of a

dword access, thus avoiding the error which would occur on some targets if the dword access

was not dword-aligned.

For each ODT entry the XCP slave driver provides two locations which are used together to store the

ODT entry address and length (or bit offset):

a uint8, referred to as the "ODT entry config";

an instance of Xcp_OdtEntryAddr_t, referred to as the "ODT entry address".

Various macros are provided in the target-specific file xcp_target.h to pack and unpack the ODT

entry properties to/from the "ODT entry config" and the "ODT entry address":

XCP_PACK_ODTENTRYCFG_BYTE()

XCP_PACK_ODTENTRYADDR_BYTE()

XCP_PACK_ODTENTRYCFG_BIT()

XCP_UNPACK_ODTENTRY_NUMBYTES()

XCP_UNPACK_ODTENTRY_BYTEADDR()

Reference 63

XCP_UNPACK_ODTENTRY_BITOFFSET()

Each of these macros is documented in detail in the file xcp_target.h.

The default definition of these macros provides the following straightforward way of storing the

properties of an ODT entry:

Xcp_OdtEntryAddr_t is defined as a pointer type.

The address associated with the ODT entry is cast to a Xcp_OdtEntryAddr_t and stored in

the "ODT entry address".

If a whole number of bytes are to be measured, that number is stored in the "ODT entry

config", occupying bits 0-3 (for CAN) or 0-6 (for IP).

If a single bit is to be measured, the offset is stored in the "ODT entry config" (occupying bits

0-2), and the uppermost bit of the "ODT entry config" is set.

This straightforward implementation is easy to understand, but it is wasteful of RAM. On some targets

it may be possible to make certain assumptions which limit the properties of an ODT entry:

Perhaps all measurement variables are located in a small region of RAM, limiting the possible

addresses which can be associated with an ODT entry.

Perhaps bitwise measurements are not required, so there is no need to store a bit offset for

an ODT entry.

Perhaps 4-byte measurement variables are not required.

If assumptions such as these can be made, then it may be possible to redefine the macros

XCP_PACK_XXX() and XCP_UNPACK_XXX() so as to provide a more efficient way of packing the

ODT entry properties into the “ODT entry address” and the “ODT entry config”.

Note, however, that for any packing mechanism the following statement must always be true: "An

'ODT entry config' has the value 0 iff no measurement (or stimulation) is configured for the

corresponding ODT entry."

The following examples illustrate some alternative packing mechanisms.

Example 1

Consider a 16-bit target which uses a 2K block of RAM to store all measurement variables. The

following approach can be used to store the ODT entry properties:

The address associated with the ODT entry is adjusted so that it specifies an offset with

respect to the start of the 2K RAM region. Thus the value of this offset occupies 11 bits.

Xcp_OdtEntryAddr_t is defined as a uint8.

The lower 8 bits of the 11-bit address offset are stored in the "ODT entry address" (which is

now a uint8).

The "ODT entry config" is used as follows:

o Bit 7 is set if the ODT entry is associated with a bit offset and is cleared otherwise.

o Bits 4-6 contain the upper 3 bits of the 11-bit address offset.

o Bits 0-2 contain either a number of bytes (from 0 to 4) or a bit offset (from 0 to 7).

This allows the properties of an ODT entry to be stored using a total of 2 bytes.

Example 2

Consider a 32-bit target which uses a 32K block of RAM to store all measurement variables. The

following approach can be used to store the ODT entry properties:

The address associated with the ODT entry is adjusted so that it specifies an offset with

respect to the start of the 32K RAM region. Thus the value of this offset occupies 15 bits.

The 15-bit address offset is stored in the "ODT entry address" (which is now a uint16).

The "ODT entry config" is used as follows:

o Bit 7 is set if the ODT entry is associated with a bit offset and is cleared otherwise.

o Bits 0-2 are used to store the bit offset (if any) which is associated with the ODT

entry.

o Bits 0-3 are used to store the number of bytes (if any) which is associated with the

ODT entry.

This allows the properties of an ODT entry to be stored using a total of 3 bytes.

64 Reference

5.8.3 Removing unnecessary configuration

The amount of RAM and ROM required to store data can be reduced by removing the following items

from the XML configuration file:

unused sessions;

unused DAQ lists;

unused ODTs and ODT entries within a DAQ list.

Removing the following items will also save CPU cycles during performance-critical operations:

unused XCP sessions;

unused static and dynamic DAQ lists;

unused ODTs within static and dynamic DAQ lists

In summary, the configuration within the XML file should be the minimum required to support the

user’s requirements.

5.8.4 Removing unnecessary functionality

Doing the following will save code space by removing unnecessary functionality:

set the global XML configuration parameter XCP_ENABLE_PAGE_FREEZING to no.

set the global XML configuration parameter XCP_ENABLE_SEEDNKEY to no.

set the global XML configuration parameter XCP_ENABLE_PGM to no.

set the global XML configuration parameter XCP_ENABLE_CALPAG to no.

set the global XML configuration parameter XCP_ENABLE_RESUME to no.

set the global XML configuration parameter XCP_ENABLE_STIM to no.

Furthermore, the XML configuration file contains a global parameter XCP_ENABLE_OPTIONAL_CMDS. Setting this to no will cause the XCP ECU software to be built without support for the following

optional XCP commands:

DOWNLOAD_MAX

GET_COMM_MODE_INFO

GET_DAQ_LIST_INFO

GET_DAQ_PROCESSOR_INFO

GET_DAQ_RESOLUTION_INFO

GET_ID

SHORT_UPLOAD

GET_DAQ_LIST_MODE

PROGRAM_PREPARE

PROGRAM_FORMAT

PROGRAM_MAX

GET_PAG_PROCESSOR_INFO

These commands provide optional services, or allow the XCP master to discover information which can

also be obtained from the ASAM A2L fragment which is generated by the XCP configuration tool. Removing support for these commands is unlikely to limit the XCP slave’s interaction with the XCP

master, but will save a considerable amount of code space.

5.8.5 Optimisation parameters

There are some XML configuration parameters which can be used to enable optimisation without

sacrificing functionality.

DAQ list reordering

If the global XML configuration parameter XCP_ENABLE_DAQLIST_REORDERING is set to yes, and if

a session in the XML configuration file defines a collection of static DAQ lists, then the configuration

tool will re-order the collection of static DAQ lists so as to improve the performance of CAN

transmission. Obviously this is only applicable if CAN is being used as a transport layer.

Reference 65

A consequence of this re-ordering is that the configuration tool may assign numbers to the static DAQ

lists in an order which differs from that implied by the layout of the XML configuration file. If the user

does not care about the order of DAQ list numbers then XCP_ENABLE_DAQLIST_REORDERING should

be set to yes; otherwise it should be set to no, or not specified at all.

Command queue length

The global XML configuration parameter XCP_NUM_RX_CMDBUF is discussed in section 4.2.5. Choosing

a small value for this parameter will save RAM; the minimum possible value is 1.

(If a small value is chosen for XCP_NUM_RX_CMDBUF it is recommended also to choose a large value

for XCP_BLOCK_SEPARATION_TIME to avoid overflow of the command queue).

66 Porting the XCP ECU software


6.1 Porting process

The XCP ECU software can be ported to a different toolchain and/or microcontroller as follows:

1. Choose a short name for the new target. This should identify both the toolchain and the

microcontroller, e.g. TaskTri for the Tasking toolchain with the Infineon Tricore

microcontroller.

2. Target-specific source files are contained in the directory TargetSpecific\<target shortname>. Copy the directory TargetSpecific\SampleTarget\ and rename it using

the short name chosen in step 1.

3. Edit the files xcp_target.c and xcp_target.h in the new target-specific directory and

replace every occurrence of the text PORTNOTE with an appropriate definition. Further

guidance on this is given in sections 6.2 and 6.3.

4. Integrate the XCP ECU software into the ECU application’s build process as described in

section 5.7.

5. Modify sections 2.3 and 11 of this user guide to include information about the new target.

6.2 PORTNOTE items in xcp_target.h

6.2.1 XCP_PACK()

XCP_PACK() ensures that a given structure is packed with no gaps.

Some compilers do not allow the user to specify that a structure should be packed with no gaps. Such

a compiler always uses the same default rules to decide how to pack structures.

In such a case, the user must manually inspect each usage of XCP_PACK() within the XCP ECU

software and satisfy himself that the compiler's default rules will, in fact, produce a closely-packed

structure. If this is the case, then the user may give XCP_PACK() a trivial definition.

6.2.2 XCP_CONFIG_TYPE

This macro expands to a set of type modifiers which are applied to all configuration types defined by

the XCP ECU software. (A “configuration type” contains global data which is read-only).

On a target with a uniform address space only the modifier const will be required.

On a target with a non-uniform address space the user must decide whether the XCP ECU software’s configuration data is to be stored in the default address space. If this is not the case the user must

add target-specific modifiers (such as _near or _far) to the macro definition so as to place the

configuration data in the appropriate address space.

6.2.3 XCP_STATE_TYPE

This macro expands to a set of type modifiers which are applied to all state types defined by the XCP

ECU software. (A “state type” contains global data which is both readable and writeable).

On a target with a uniform address space no modifiers are required and the macro definition should be

empty.

On a target with a non-uniform address space the user must decide whether the XCP ECU software’s

state data is to be stored in the default address space. If this is not the case the user must add target-

specific modifiers (such as _near or _far) to the macro definition so as to place the state data in the

appropriate address space.

6.2.4 XCP_FN_TYPE

This macro expands to a set of type modifiers which are applied to all functions defined by the XCP

ECU software.

On a target with a uniform address space no modifiers are required and the macro definition should be

empty.

On a target with a non-uniform address space the user may use the macro to apply a type modifier

such as _near to the XCP function definitions.

rbahekar

Hervorheben

address space of zedboard is uniform - 32bit wide

rbahekar

Hervorheben

rbahekar

Hervorheben

Porting the XCP ECU software 67

6.2.5 XCP_ENABLE_ALL_INTERRUPTS and XCP_DISABLE_ALL_INTERRUPTS

These macros must be implemented so as to enable or disable all interrupts. They must be defined in

such a way that calls to them can be nested.

If the global XML parameter XCP_ENVIRONMENT is set to any value apart from XCP_ENV_NOT_ETAS the definition of XCP_ENABLE_ALL_INTERRUPTS() and XCP_DISABLE_ALL_INTERRUPTS() is

created automatically and no action is needed from the user. Otherwise the user must create the

definitions by hand in the file xcp_target.h.

The global XML parameter XCP_ENVIRONMENT is discussed further in section 5.7.2.

6.2.6 sizeof_XXX macros

The macros with names of the form sizeof_<type name> must be defined as follows:

Macro Definition

sizeof_Xcp_OdtEntryCfg_t The size of the type Xcp_OdtEntryCfg_t in bytes. This is usually 1 byte.

sizeof_Xcp_NvDaqState_t The size of the type Xcp_NvDaqState_t in bytes. This is

usually 6 bytes.

sizeof_Xcp_NvSession_t The size of the type Xcp_NvSession_t in bytes. This is usually 10 bytes on a 16-bit target or 12 bytes on a 32-bit target.

sizeof_Xcp_DaqDynConfig_t The size of the type Xcp_DaqDynConfig_t in bytes. This is

usually equal to the pre-processor definition

XCP_MAX_ODT_ENTRIES_DYNDAQ, plus either 1 or 2 bytes, depending on the padding added by the compiler.

Although it appears at first sight that these macros can be defined simply via the sizeof operator,

doing so creates difficult circular dependencies between the header files xcp_priv.h and

xcp_auto_confdefs.h.

6.2.7 Storing ODT entry properties

The type definition Xcp_OdtEntryAddr_t and the following macros define the way in which the

properties of an ODT entry are stored at runtime:

XCP_PACK_ODTENTRYCFG_BYTE()

XCP_PACK_ODTENTRYADDR_BYTE()

XCP_PACK_ODTENTRYCFG_BIT()

XCP_UNPACK_ODTENTRY_NUMBYTES()

XCP_UNPACK_ODTENTRY_BYTEADDR()

XCP_UNPACK_ODTENTRY_BITOFFSET()

The definitions which are provided for these macros (and for Xcp_OdtEntryAddr_t) in

SampleTarget/xcp_target.h will work on any target which has a uniform address space.

It may be necessary to provide different definitions if:

either it is necessary for ODT entries to refer to measurement variables which are in a non-

default address space;

or the default definitions are considered to be too wasteful of RAM. Section 5.8.2 discusses

ways in which more efficient definitions can be created.

6.2.8 uintn and sintn

uint8, uint16, uint32, sint8, sint16 and sint32 must be defined to be signed or unsigned

integer types of the appropriate widths.

If the global XML parameter XCP_ENVIRONMENT is set to XCP_ENV_ASCET, XCP_ENV_RTAOS or

XCP_ENV_RTAOSEK5 the definitions of uintn and sintn are created automatically and no action is

needed from the user. Otherwise the user must create the definitions by hand in the file

xcp_target.h.

The global XML parameter XCP_ENVIRONMENT is discussed further in section 5.7.2.


6.2.9 Xcp_CfgPtrn and Xcp_StatePtrn

Xcp_CfgPtrn must refer to n bytes of memory in an address space of type XCP_CONFIG_TYPE (see

section 6.2.2). The default definition of Xcp_CfgPtrn may be adequate, but should be reviewed to

confirm this.

Xcp_StatePtrn must refer to n bytes of memory in an address space of type XCP_STATE_TYPE

(see section 6.2.3). The default definition of Xcp_CfgPtrn may be adequate, but should be reviewed

to confirm this.

6.2.10 Other type definitions

Xcp_Addr_t must be defined as a pointer to a single byte in memory. This type is used to refer to all

MTA addresses. Conversion to this type is performed by the callback function

XcpApp_ConvertAddress() described in section 5.6.4.

On a target with a uniform address space it may be possible to define Xcp_Addr_t simply as

uint8*. A target with a non-uniform address space may require a more complex definition.

An instance of Xcp_OdtEntryAddr_t is used to hold the “ODT entry address” for an ODT entry.

Often it will be defined as a pointer type, though, as section 5.8.2 explains, this is not always the case.

The default definition of Xcp_OdtEntryAddr_t is compatible with the default definition of the macros XCP_PACK_XXX() and XCP_UNPACK_XXX() as discussed in section 6.2.7. If these macros

are modified then the definition of Xcp_OdtEntryAddr_t may need to be modified also. This may

need to be done if:

either it is necessary for ODT entries to refer to measurement variables which are in a non-

default address space;

or the default definitions are considered to be too wasteful of RAM. Section 5.8.2 discusses

ways in which more efficient definitions can be created.

XcpCan_MsgObjId_t must be defined to be an integer type which can hold a value identifying a CAN

message object (or “hardware buffer”). See section 4.7.1 for more information.

An array of instances of Xcp_Seed_t is used to contain a seed, as outputted by the callback XcpApp_GetSeed(). For example, Xcp_Seed_t could be defined as uint8 if the seed is calculated

at runtime, or as const uint8 if the seed is stored in a fixed buffer.

An array of instances of Xcp_Key_t defines the key buffer outputted by the callback

XcpApp_GetKeyBuffer(). The key buffer must be writeable, so uint8 is a possible value for this

type definition.

6.3 PORTNOTE items in xcp_target.c

6.3.1 Xcp_MemCopy()

This function has similar semantics to the library function memcpy(). In fact, it is possible to

implement Xcp_MemCopy() simply by delegating to memcpy(). However it may be advisable to examine the performance of memcpy() first, since it may be possible to improve on memcpy() in

certain situations.

6.3.2 Xcp_MemZero()

This function zeroes a range of memory addresses. Its performance is not critical and therefore it can

usually be implemented simply by delegating to the library function memset(). Indeed, it may be

possible simply to replace Xcp_MemZero() with memset() via a pre-processor macro.

6.3.3 Xcp_CheckCanId()

This function checks whether a CAN message ID has the format required by the CAN driver. It may

need to make use of the pre-processor symbol XCPCAN_ALLOW_EXTENDED_MSG_IDS which indicates

whether extended CAN message IDs should be allowed in the current project.

If the target does not use XCP-on-CAN, this function definition can be removed.

Integration with Visu-IT ASAP2 editor 69

7 Integration with Visu-IT ASAP2 editor

This section describes how to add support for the XCP ECU software to an ECU project configured

within the Visu-IT ASAP2 editor.

This section presents one possible route to accomplish the integration, as advice to users who are uncertain of how to proceed. It is possible for the user to define an alternative XCP configuration in the

ASAP2 editor if they wish.

7.1 Creating a new ECU project

If the ASAP2 editor is being used to create a new ECU project which performs calibration via XCP then

two template projects are available which will provide most of the memory layout settings which are

required. If the new ECU project does not require calibration, then no template is needed: the user can

simply create a new, empty project in the ASAP2 editor.

Both template projects are stored in the directory ASAP2_editor_integration/ XCP within the

installation directory:

The template project Template_XCP_2Page is suitable for ECU projects which will use a 2-

page calibration concept, with separate working and reference pages.

The template project Template_XCP_1Page is suitable for ECU projects which will use a

single-page calibration concept, with no page switching.

The user should select the appropriate template project, copy it, and use it as the basis for his new

ECU project.

In both templates, the memory layout entity ECU_CODE1 is expected to be used for program code and

the memory layout entity ROM is expected to be used for calibration data. In both memory layout

entities only the following XCP parameter remains to be configured:

“Checksum Type”. This value should correspond to the checksum type implemented by the

function XcpApp_CalMemGetChecksum() (see section 5.6.3).

This parameter is on the “XCP – SEGMENT (Part 1)” tab of each memory layout entity.

Although no other XCP parameters require values to be specified, various other parameters of each

memory layout entity must be assigned values, for example “StartAddress” and “ByteSize” on the

“Memory Region” tab.

7.2 Configuring XCP memory layout in an existing ECU project

This section describes the changes which must be made to the memory layout of an existing ECU project in the ASAP2 editor to include support for calibration via the XCP ECU software. If the ECU

project was created from one of the templates described in section 7.1, or if the ECU project does not

require calibration at all, this section can be ignored.

7.2.1 Memory layout entity for program code

The memory layout entity which contains program code must be edited and the following values

entered for the parameters on the “XCP – SEGMENT (part 1)” tab:

Parameter Value

SEGMENT_NUMBER 0

Number of pages 1

ADDRESS_EXTENSION 0

COMPRESSION_METHOD 0

ENCRYPTION_METHOD 0

Checksum type This value should correspond to the checksum type implemented by the


On the “XCP – SEGMENT (part 2)” tab, a single PAGE must be created with the following parameter

values:

Parameter Value

PAGE_NUMBER 0


Parameter Value

ECU_ACCESS_TYPE ECU_ACCESS_WITH_XCP_ONLY

XCP_READ_ACCESS_TYPE XCP_READ_ACCESS_WITH_ECU_ONLY

XCP_WRITE_ACCESS_TYPE XCP_WRITE_ACCESS_NOT_ALLOWED

7.2.2 Memory layout entity for calibration data (2-page calibration concept)

If the ECU application uses a 2-page calibration concept, then the memory layout entity which contains

calibration data must be edited and the following values entered for the parameters on the “XCP –

SEGMENT (part 1)” tab:

Parameter Value

SEGMENT_NUMBER 1

Number of pages 2

ADDRESS_EXTENSION 0


ENCRYPTION_METHOD 0



On the “XCP – SEGMENT (part 2)” tab, two PAGEs must be created with the following parameter

values:

Parameter Value

Page 0:

PAGE_NUMBER 0



XCP_WRITE_ACCESS_TYPE XCP_WRITE_ACCESS_NOT_ALLOWED

INIT_SEGMENT 1

Page 1:

PAGE_NUMBER 1



XCP_WRITE_ACCESS_TYPE XCP_WRITE_ACCESS_WITH_ECU_ONLY

INIT_SEGMENT 1

7.2.3 Memory layout entity for calibration data (single-page calibration concept)

If the ECU application uses a single-page calibration concept, then the memory layout entity which

contains calibration data must be edited and the following values entered for the parameters on the

“XCP – SEGMENT (part 1)” tab:

Parameter Value

SEGMENT_NUMBER 1

Number of pages 1

ADDRESS_EXTENSION 0


Integration with Visu-IT ASAP2 editor 71

Parameter Value

ENCRYPTION_METHOD 0



On the “XCP – SEGMENT (part 2)” tab, one PAGE must be created with the following parameter

values:

Parameter Value

PAGE_NUMBER 0



XCP_WRITE_ACCESS_TYPE XCP_WRITE_ACCESS_WITH_ECU_ONLY

7.3 Configuring the XCP global settings

The contents of the “global_XCP_V10” entity in the XCP IfData template can be imported directly from

the A2L fragment generated by the XCP configuration tool. The only obstacle is the fact that the ASAP2

editor cannot import a genuine A2L fragment, and therefore the generated A2L must be modified

slightly to give it the appearance of a complete A2L file.

These steps should be followed:

1. Run the XCP configuration tool to generate an A2L fragment containing XCP configuration.

2. Edit the generated file containing the A2L fragment and un-comment these lines at the start

and end of the file:

ASAP2_VERSION 1 51

/begin PROJECT

/begin MODULE

...

<XCP A2L>

...

/end MODULE

/end PROJECT

(If it is often necessary to perform this action the user may wish to edit the template

ConfigTool\if_data_xcp.a2lt from which the A2L file is generated. Note, however, that this will cause all generated A2L files to be incompatible with the procedure described in

section 8.2.)

3. Start the ASAP2 editor and open the ECU project into which the XCP A2L is to be imported.

4. Import the generated XCP A2L file into the ECU project, accepting all the default options in

the “Import ASAP2” dialog.

The ASAP2 editor will import the generated XCP A2L file into the XCP IfData template, replacing all existing data in the “global_XCP_V10” entity. There will be non-fatal errors,

which can be ignored, relating to the fact that the PROJECT and MODULE blocks in the

generated XCP A2L file do not have Name or LongIdentifier attributes. There should be

no other errors.

7.4 Configuring measurement values

The ASAM XCP specification allows a MEASUREMENT to be associated with one or more XCP EVENTs by means of an IF_DATA XCP block within the MEASUREMENT block. An MC or RP tool may use this

association to guide the user when he is assigning measurement variables to rasters.

The ASAP2 editor allows this association to be specified in several different ways. The most useful

approach is described below:

1. Go to the “measurement_XCP_V10” entity within the XCP IfData template.


2. Select either:

“FIXED_EVENT_LIST” to assign each MEASUREMENT a list of EVENTs which cannot be

changed later within the MC or RP tool;

“VARIABLE” to assign each MEASUREMENT a default list of EVENTs which can be

changed later within the MC or RP tool.

3. In either the “FIXED_EVENT_LIST” or the “DEFAULT_EVENT_LIST”, set “Count” to 1, and

select “xcpOnlineUpdate” from the “smart” mode dropdown list.

4. Go to the “Calib” tab of a MEASUREMENT entity.

5. Select a raster, or set of rasters, from the “Online update index” dropdown list. The rasters in

this list are associated with XCP EVENTs.

6. When an A2L file is generated by the ASAP2 editor the MEASUREMENT will contain either a

FIXED_EVENT_LIST or a DEFAULT_EVENT_LIST specifying the rasters chosen in step 5.

In order for the above procedure to be successful an association must be defined between each raster and an XCP event. This is not entirely straightforward and is beyond the scope of this document; users

are referred to the ASAP2 editor’s documentation.

Integration with ETAS INCA 73

8 Integration with ETAS INCA

This section is not intended as a complete description of how to perform measurement and calibration

over XCP with INCA. Instead it assumes that the user is familiar with using INCA for measurement and

calibration, and gives guidance on specific details of using XCP with INCA.

The user may also find it helpful to refer to the tutorial in section 3.

8.1 Seed and key DLL

The XCP ECU software installation includes source code for an example “seed and key” DLL. The DLL is implemented using a Microsoft Visual Studio 2005 project, which is in the directory XcpSeedNKey\.

Any edition of Visual Studio 2005 (including the free Express Edition) can be used to build the DLL.

The role of a “seed and key” DLL is to calculate the key to unlock a protected ECU resource, given the

seed for the same resource. The example DLL is able to unlock any ECU resource and assumes that

the seed and the key for the resource are equal.

The source code of the example DLL is extensively commented. Locations which are intended to be

modified by the user are indicated with the text TODO. The following modifications may be necessary:

The DLL can be modified to support fewer ECU resources. This may be desirable if the user

wishes to distribute a version of the DLL which is unable to grant access to certain ECU resources. To do this, the user should modify the initialisation of the global variable

AvailPrivileges.

The algorithm by which the DLL computes a key from a seed can be modified. To do this the

user must modify the function XCP_ComputeKeyFromSeed().

When the “seed and key” DLL has been built, it should be placed in this directory to allow it to be used

by INCA:

<ETAS directory>\<latest ETASShared directory>\Security

8.2 Integration into an INCA A2L file

This section assumes that the user has an A2L file which describes their ECU application and which they wish to use with INCA. The following steps must be taken to add support for the XCP ECU

software to the A2L file:

1. The user must run the XCP configuration tool and generate an A2L fragment. As described in

section 4.1.3, this fragment contains the IF_DATA XCP block which occurs within the

MODULE block of the main A2L file.

2. The user must edit the main A2L file and add the following block within the MODULE block:

/begin A2ML




};

/end A2ML


The .aml files required by this block are part of the XCP ECU software installation. They

should be copied to a location from which they can be included into the main A2L file.

3. The user must edit the MEMORY_SEGMENT block which contains the program code and insert

the following block:

/begin IF_DATA XCP

/begin SEGMENT






/begin CHECKSUM


<checksum type>

/end CHECKSUM

/begin PAGE





/end PAGE

/end SEGMENT

/end IF_DATA

The value <checksum type> should correspond to the checksum type implemented by the

function XcpApp_CalMemGetChecksum() (see section 5.6.3) and should be encoded as

described in the ASAM XCP specification of the BUILD_CHECKSUM command.

4. The user must edit the MEMORY_SEGMENT block which contains the calibration data and insert one of the following two blocks, depending on whether the ECU’s calibration memory

supports page switching.

The block for two-page calibration, to be used if the ECU supports page-switching:

/begin IF_DATA XCP

/begin SEGMENT






/begin CHECKSUM

<checksum type>

/end CHECKSUM

/begin PAGE

0x00 /* page number - reference page */




INIT_SEGMENT 1

/end PAGE

/begin PAGE

0x01 /* page number - working page */




INIT_SEGMENT 1

/end PAGE

/end SEGMENT

/end IF_DATA

The block for single-page calibration, to be used if the ECU does not support page-switching:

/begin IF_DATA XCP

/begin SEGMENT



Integration with ETAS INCA 75




/begin CHECKSUM

<checksum type>

/end CHECKSUM

/begin PAGE





/end PAGE

/end SEGMENT

/end IF_DATA

Once again, the value <checksum type> should correspond to the checksum type

implemented by the function XcpApp_CalMemGetChecksum() (see section 5.6.3) and

should be encoded as described in the ASAM XCP specification of the BUILD_CHECKSUM

command.

The above steps are the minimum which must be carried out to integrate XCP into an INCA A2L file. In

addition, the user can add an IF_DATA XCP block within each MEASUREMENT block, as described in

the ASAM XCP A2L specification.

8.3 Correspondence between XCP configuration and INCA concepts

8.3.1 Seed and key

If:

a “seed and key” DLL has been built as described in section 8.1;

and the name of the DLL is specified in the XML configuration using the per-session

parameter XCP_SEEDNKEY_FUNCTION;

and the generated XCP A2L fragment has been included into INCA’s main A2L file as

described in section 8.2

then INCA will automatically use the “seed and key” DLL to unlock those XCP resources which were

declared as protected in the XML configuration file.

8.3.2 INCA’s variable selection dialog

The rasters in INCA’s variable selection dialog correspond to the XCP EVENTs defined in A2L.

When static DAQ lists are being used, it is advisable to assign a single fixed EVENT to each DAQ list in the XCP ECU software configuration. The most straightforward approach is to have a 1-to-1

correspondence between DAQ lists and EVENTs. Such a configuration can be seen in the file

xcp_example_stat_daqs.xml.

INCA examines the A2L file and aggregates all the ODTs of the DAQ list which is associated with an EVENT; the combined capacity of these ODTs allows INCA to indicate the capacity of the raster

associated with the EVENT.

When dynamic DAQ lists are used INCA will create one dynamic DAQ list for each EVENT. Within this

DAQ list, INCA will create enough dynamic ODTs to hold the variables which the user assigns to the

raster corresponding to the EVENT.

There are a few points to note regarding INCA’s use of dynamic DAQ lists:

INCA always uses a single dynamic DAQ list for each raster. Therefore the capacity of a raster

is limited to the capacity of a single dynamic DAQ list. Even if a second “spare” dynamic DAQ

list is available, INCA will not use it to enlarge the capacity of the raster.

INCA does not monitor the filling-level of a raster which is based on a dynamic DAQ list. Therefore it is possible for the user to add more variables to the raster than can be contained


in the underlying DAQ list. If the user does this, INCA will display the following message in

the monitor window when the user tries to start the experiment:

ERROR: XcpCmd Failure, The XcpError ERR_MEMORY_OVERFLOW(30h) occured in XcpCmd

ALLOC_ODT(D4h)

By default, INCA will allow the user to assign any measurement variable to any raster, subject to the capacity of the raster. The A2L file can restrict the possible rasters for a measurement by specifying an

IF_DATA XCP block within the MEASUREMENT block. Within the IF_DATA XCP block the A2L blocks

AVAILABLE_EVENT_LIST and DEFAULT_EVENT_LIST can be used to specify the “available” and

“default” rasters for the measurement. More details are contained in the ASAM XCP specification.

If the XCP ECU software configuration indicates that DAQ lists will contain timestamps INCA will

automatically make use of the timestamps it receives.

8.3.3 Fast start mode

INCA refers to RESUME mode as “fast start”. Assuming that RESUME mode has been configured for

the XCP ECU software (see section 4.3.10), “fast start” can be used within an INCA experiment by

following these steps:

Create an experiment in INCA, selecting the desired variables and rasters.

Open INCA’s hardware configuration window and enable “fast start” in the parameters for the

XCP hardware device.

Return to INCA’s experiment window and select the menu item Measurement / Fast start /

Store measurement configuration in ECU.

When prompted, switch off the ECU.

Start the experiment.

Switch the ECU on again.

Observe the measurement values in the experiment.

To stop using “fast start”, follow these steps:

Stop the experiment.

Select “Measurement / Fast start / Delete measurement configuration in ECU”.

When prompted, switch off the ECU.

Open INCA’s hardware configuration window and disable “fast start” in the parameters for the

XCP hardware device.

8.4 Limitations of INCA

8.4.1 CAN message IDs for dynamic DAQ list DTO packets

The XML configuration file allows a CAN message ID to be specified for the dynamic DAQ lists used by

a session, as described in section 4.7.2. Furthermore, the XCP ECU software allows the XCP master to

set the CAN message ID for a dynamic DAQ list at runtime using the XCP command SET_DAQ_ID.

However, INCA is unable to assign a CAN message ID to a dynamic DAQ list at runtime, and it ignores any CAN message ID which is assigned to a dynamic DAQ list in the XML configuration file. Instead,

INCA expects dynamic DAQ list DTO packets to use the same CAN message ID as is used by the XCP

slave for command response packets and error packets. (This is the CAN message ID specified by the

per-session XML parameter XCPCAN_TX_MSGID).

Therefore, when using dynamic DAQ lists, although the user must continue to specify the per-session

XML configuration parameter XCPCAN_DYNDAQ_MSGID in order to configure the XCP ECU software,

the value chosen must always be the same as for the parameter XCPCAN_TX_MSGID.

8.4.2 The association between a static DAQ list and an event channel

Recall that section 4.3.4 explains how a DAQ list is always associated with exactly one XCP event

channel. For a static DAQ list, the initial association is given by the DAQ list’s XML configuration parameter XCP_DAQ_DEFAULT_EVENT, though the XCP ECU software allows this association to be

changed at runtime by the XCP master.

However, INCA is not able to change the association between a static DAQ list and an event channel at

runtime. Therefore, the user must ensure that the DAQ list is associated with the correct event channel

in the XML configuration file.

Integration with ETAS INTECRIO 77

9 Integration with ETAS INTECRIO

This section is not intended as a complete description of how to perform bypass over XCP with

INTECRIO; this is covered by the manuals and online help which accompany INTECRIO. Instead, this

section gives guidance on specific details of using XCP with INTECRIO.

The user may also find it helpful to refer to the tutorial in section 3.

9.1 Integration into an INTECRIO A2L file

This section assumes that the user has an A2L file which describes their ECU application and which they wish to use with INTECRIO. The following steps must be taken to add support for the XCP ECU

software to the A2L file:

1. The user must run the XCP configuration tool and generate an A2L fragment. As described in

section 4.1.3, this fragment contains the IF_DATA XCP block which occurs within the

MODULE block of the main A2L file.

2. The user must edit the main A2L file and add the following block within the MODULE block:

/begin A2ML




};

/end A2ML


The .aml files required by this block are part of the XCP ECU software installation. They

should be copied to a location from which they can be included into the main A2L file.

The above steps are the minimum which must be carried out to integrate XCP into an INTECRIO A2L

file. In addition, the user can add an IF_DATA XCP block within each MEASUREMENT block, as

described in the ASAM XCP A2L specification.

9.2 Using XCP RESUME mode

Assuming that RESUME mode has been configured for the XCP ECU software (see section 4.3.10),

INTECRIO can be used to perform a bypass with RESUME mode by following these steps:

1. When importing the ECU’s A2L file into INTECRIO, tick the “Resume Mode” box on the

“Parameters” tab of the XCP hardware node.

2. Build the INTECRIO project and open an experiment as usual.

3. Start the ECU, then start the experiment. At this point, the rapid prototyping hardware will

configure the XCP bypass on the ECU and start the bypass as usual. In addition, the rapid prototyping hardware will ask the ECU to store the bypass configuration in non-volatile

memory.

4. Stop the experiment, then stop the ECU.

5. Re-start the experiment.

6. Re-start the ECU. The bypass will begin running as soon as the ECU starts.

9.3 Known issues and hints on usage

INTECRIO’s online help includes a comprehensive description of the support for XCP. However, there

are a few hints which should be mentioned, particularly since they contrast with INCA’s behaviour:

INTECRIO does not support XCP “seed and key” functionality. Therefore the per-session XML

configuration parameters XCP_PROTECT_XXX should always be set to no.

INTECRIO expects to be able to use certain optional XCP commands. Therefore the global

XML configuration parameter XCP_ENABLE_OPTIONAL_CMDS must always be set to yes.

There is also a single known issue with INTECRIO’s XCP-on-CAN functionality:

When performing bitwise stimulation of a byte-sized or word-sized variable on a big-endian

ECU, INTECRIO will stimulate the wrong memory location.

78 Appendix: Unsupported XCP features

10 Appendix: Unsupported XCP features

The XCP ECU software implements version 1 of the ASAM XCP standard with the following exceptions:

Only the identification field type “absolute ODT number” is supported.

Predefined DAQ lists are not supported.

DAQ list prioritisation is not supported.

DAQ transmission prescalers are not supported.

ODT copy optimisation is not supported, i.e. the optimisation method is always OM_DEFAULT.

Only non-compressed, non-encrypted, sequential flash programming using absolute access

mode is supported.

The XCP ECU software does not report DAQ overload situations to the XCP master.

Interleaved communication mode is not supported.

PID_OFF mode is not supported.

The following optional XCP commands are not supported:

GET_DAQ_EVENT_INFO

GET_PAGE_INFO

GET_PGM_PROCESSOR_INFO

GET_SECTOR_INFO

GET_SEGMENT_INFO

PROGRAM_VERIFY

READ_DAQ

SHORT_DOWNLOAD

The following are specific limitations of certain XCP commands.

The GET_ID command only supports identification type “ASCII text” and response mode 0

(transfer identification via UPLOAD).

The events EV_STORE_CAL, EV_STORE_DAQ and EV_CLEAR_DAQ are never transmitted by

the slave.

In a SET_REQUEST command, the STORE_CAL_REQ bit cannot be set at the same time as

either the STORE_DAQ_REQ bit or the CLEAR_DAQ_REQ bit.

The CAN transport command SET_DAQ_ID can only be used for dynamic DAQ lists.

Appendix: Notes on supported targets 79

11 Appendix: Notes on supported targets

11.1 PC / Visual Studio 2005

This target was used to develop and test the XCP ECU software. It could also be used with ETAS’s

“RTA-OSEK for PC” product.

Obviously a PC does not have some of the ECU functionality which the XCP ECU software requires and

which is accessed by the callback APIs described in section 5.6. Nevertheless, it is possible to simulate

this functionality as follows.

Mostly, the PC’s own memory can be used directly as “ECU memory”. However, calibration memory

must be simulated by defining a two-dimensional array, with each element of the array corresponding

to a location in calibration memory. One dimension of the array corresponds the address of each memory location, and the other dimension of the array gives the calibration page of the memory

location.

This allows calibration page management to take place as usual. However, care must be taken when

implementing callback APIs such as XcpApp_CalMemRead() which sometimes need to access calibration memory and sometimes need to access “ordinary” ECU memory. In the former case the

function must access the array which simulates calibration memory, and in the latter case the function

must access the PC’s memory directly. Section 5.6 indicates which callback APIs must be able to

access either type of memory.

Flash and non-volatile memory can be simulated with an array, or, if true persistence is required, a file.

11.2 Tasking / Tricore

This target was developed and tested using version 2.2.r3 (build 134.1.4) of the Tasking toolchain and a Tricore 1796 ECU (revision AB). In practice, due to the non-target-dependent nature of the XCP ECU

software, it is likely also to work with other versions of the Tasking software or other Tricore ECUs.

No particular toolchain options are required in order to build the Tasking / Tricore port.

The Tasking / Tricore port illustrates how the target-specific function Xcp_MemCopy() (see section

6.3.1) can be optimised to improve on the performance of the standard library function memcpy(). In

this case, the performance of memcpy() can be improved upon for small block sizes.

11.3 Metrowerks / HCS12X

This target was developed using version 5.0.38 of the Metrowerks compiler and version 5.0.36 of the

Metrowerks linker. These correspond to version 5.9.0 of the CodeWarrior IDE.

The target was tested on a S12XDP512-A HCS12X board. In practice, due to the non-target-dependent

nature of the XCP ECU software, it is likely also to work with other versions of the Metrowerks software

or other HCS12 / HCS12X CPUs.

11.4 Tasking / XC164

This target was developed using the Tasking C166-VX toolchain, version 2.3.r2 (build 112 of

cc166.exe).

The target was tested on an Infineon XC164CM-8F40F ECU, as contained in the Infineon U CAN Starter Kit. In practice, due to the non-target-dependent nature of the XCP ECU software, it is likely also to

work with other versions of the Tasking software or other XC16x ECUs.

The XC164 has very little RAM. If RAM is scarce in the user’s application, the user can perform

optimisations to decrease the amount of RAM required to store ODT entry properties. This is described

further in section 5.8.2.

11.5 Diab / MPC55xx

This target was developed and tested using version 5.6.1 of the Diab / Wind River toolchain and a MPC5554 ECU. In practice, due to the non-target-dependent nature of the XCP ECU software, it is

likely also to work with other versions of the Diab software or other MPC55xx ECUs.

No particular toolchain options are required in order to build the Diab / MPC55xx port.

80 Appendix: Installing Perl

12 Appendix: Installing Perl

12.1 Perl requirements

The XCP configuration tool is implemented as a set of Perl scripts, and therefore Perl will need to be

installed on the user’s PC before the tool can be used. The user is recommended to install v5.8.8 of

Perl.

In addition, the user will need to install the following Perl packages which are not commonly

distributed with Perl:

XML::LibXML::Common

XML::LibXML (at least v1.66)

XML::Simple

These packages must be installed in the order given above.

There are two ways in which the user can obtain Perl and the required packages:

either the user can use the Perl installation which is distributed with the XCP ECU software

package;

or the user can modify an existing Perl installation to add the required packages.

These approaches are discussed in the following sections.

12.2 Using the supplied Perl installation

The zip file strawberry_perl.zip which accompanies the XCP ECU software contains a complete

installation of Perl, including all the required packages. This installation contains the Strawberry Perl

distribution (see http://strawberryperl.com); the directory licences\ within the zip file describes the

terms under which the various components of the distribution can be used.

Disclaimer

The package strawberry_perl.zip contains only software which is already available in the public domain. The software was not created by ETAS and is not an ETAS product. ETAS accepts no responsibility for any aspect of this software; ETAS has not tested this software and does not warrant that this software is suitable for any particular purpose; ETAS cannot offer support for this software.

To install the Perl distribution follow these steps:

1. Unzip the file strawberry_perl.zip. It is best to avoid choosing an installation directory

which has spaces in its pathname. A good choice would be c:\strawberry_perl.

2. Modify the PATH environment variable to include these directories:

o <installation directory>\c\bin

o <installation directory>\Perl\bin

12.3 Modifying an existing Perl installation

If the user already has an installation of Perl he may wish to modify it to add the packages required by

the XCP configuration tool. This is only recommended if the user is comfortable with downloading and

installing Perl packages.

The required packages are available via the Perl Package Manager from one of the following

repositories:

Bribes: http://www.bribes.org/perl/ppm

Trouchelle: http://trouchelle.com/ppm

UWinnipeg: http://theoryx5.uwinnipeg.ca/ppms

ActiveState: http://ppm.activestate.com/PPMPackages/5.8-windows

http://strawberryperl.com/

Appendix: ETAS Contact Addresses 81

13 Appendix: ETAS Contact Addresses

ETAS HQ

ETAS GmbH

Borsigstraße 14 Phone: +49 711 89661-0

70469 Stuttgart Fax: +49 711 89661-106

Germany WWW: www.etas.com

ETAS Subsidiaries and Technical Support

For details of your local sales office as well as your local technical support team and product hotlines,

take a look at the ETAS website:

ETAS subsidiaries WWW: www.etas.com/en/contact.php

ETAS technical support WWW: www.etas.com/en/hotlines.php

http://www.etas.com/en/contact.php

http://www.etas.com/en/hotlines.php

xcp protocol ecu software (xcp starter kit part 2) v1.0 · 02/06/2010 · the xcp ecu software is...

Documents