Upload
others
View
57
Download
2
Embed Size (px)
Citation preview
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.
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
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.
10 Tutorial: adding XCP to an ECU application
3 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:
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:
12 Tutorial: adding XCP to an ECU application
/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.
Tutorial: adding XCP to an ECU application 13
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.
3.2.4 CAN configuration
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.
3.2.5 ECU ASAP2 file
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
14 Tutorial: adding XCP to an ECU application
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.
The configuration required for this step of the tutorial is contained in the XML file
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.
3.3.2 ECU ASAP2 file
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.
Tutorial: adding XCP to an ECU application 15
The user must edit the MEMORY_SEGMENT block which contains the calibration data and insert the
following block:
/begin IF_DATA XCP
/begin SEGMENT
0x01 /* 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_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.
The configuration required for this step of the tutorial is contained in the XML file
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()
16 Tutorial: adding XCP to an ECU application
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.
3.5.1 Review the DAQ list configuration
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.
The configuration required for this step of the tutorial is contained in the XML file
Examples/Tutorial/6_bypass.xml. This is based on the file 2_measurement.xml, so if any
Tutorial: adding XCP to an ECU application 17
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.
3.6.1 Review the DAQ list configuration
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 );
...
}
3.6.3 CAN configuration
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.
3.6.4 ECU ASAP2 file
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.
18 Tutorial: adding XCP to an ECU application
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.
20 Using the XCP ECU software
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.
Using the XCP ECU software 21
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.
22 Using the XCP ECU software
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.
Using the XCP ECU software 23
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.
24 Using the XCP ECU software
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.
Using the XCP ECU software 25
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.
26 Using the XCP ECU software
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.
Using the XCP ECU software 27
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”.
28 Using the XCP ECU software
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).
Using the XCP ECU software 29
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.
{
Xcp_DoDaqForEvent( 1 );
30 Using the XCP ECU software
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 */
{
Xcp_DoDaqForEvent( 1 );
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;
Xcp_DoDaqForEvent( 1 );
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.
Using the XCP ECU software 31
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.
32 Using the XCP ECU software
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_StatePtr8 pBytes )
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.
Using the XCP ECU software 33
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
region size must be modulo 2.
6 XCP_ADD_44 Add each dword into a dword checksum, ignore overflows. Checksum
region size must be modulo 4.
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_StatePtr8 pBytes )
34 Using the XCP ECU software
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.
Using the XCP ECU software 35
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,
Xcp_StatePtr8 pBytes )
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.
36 Using the XCP ECU software
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.
Using the XCP ECU software 37
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.
38 Using 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.
See section 4.7.1 for a discussion of this function.
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.
See section 4.8.1 for a discussion of this function.
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.
See section 4.8.1 for a discussion of this function.
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.
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_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.
Since the XCP ECU software can support multiple XCP sessions it is possible for
this function to be called more than once in succession.
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.
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 all segments of calibration memory.
The XCP ECU software relies on this function to determine whether the given
page number is valid. Therefore this function should always validate its
argument.
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.
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.
Return value See the description of Xcp_CalPageErr in section 5.2.
Description The XCP ECU software expects this function to set the current "tool" (or “XCP”) 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.
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.
Return value See the description of Xcp_CalPageErr in section 5.2.
Description The XCP ECU software expects this function to set the current "tool" (or “XCP”) calibration page for all segments of calibration memory.
The XCP ECU software relies on this function to determine whether the given
page number is valid. Therefore this function should always validate its argument.
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.
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,
Xcp_StatePtr8 pBytes
)
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.
Return value See the description of Xcp_CalMemState in section 5.2.
Description The XCP ECU software expects this function to read data from calibration
memory.
The function is expected to decide for itself within which calibration segment the
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.
Return value See the description of Xcp_CalMemState in section 5.2.
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.
The function is expected to decide for itself within which calibration segment the
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.
Return value See the description of Xcp_CalMemState in section 5.2.
Description The XCP ECU software expects this function to copy the contents of the specified source page to the specified destination page.
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.
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.
Return value See the description of Xcp_CalMemState in section 5.2.
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.
The function is expected to decide for itself within which calibration segment the
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 )
Return value See the description of Xcp_CalMemState in section 5.2.
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.
Return value See the description of Xcp_CalMemState in section 5.2.
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().
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, 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)
mta The current MTA.
codeSize The size of the code block which will be downloaded to the MTA
after the PROGRAM_PREPARE command completes.
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_PREPARE command.
XcpApp_ProgramClear
Syntax Xcp_ProgramState XcpApp_ProgramClear(
Xcp_Addr_t mta,
uint32 length
)
Parameters
(in)
mta The current MTA.
length The length of the range to be cleared.
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_CLEAR command.
58 Reference
XcpApp_Program
Syntax Xcp_ProgramState XcpApp_Program(
Xcp_Addr_t mta,
uint8 numBytes,
Xcp_StatePtr8 pBytes
)
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.
Return value See the description of Xcp_ProgramState in section 5.2.
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 )
Description The XCP ECU software expects this function to perform the operations described
in the ASAM XCP specification for the PROGRAM_RESET command.
This function may reset the ECU.
XcpApp_ProgramGetRequestState
Syntax Xcp_ProgramState XcpApp_ProgramGetRequestState( void )
Return value See the description of Xcp_ProgramState in section 5.2.
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,
Xcp_StatePtr8 pBytes
)
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.
numBytes The number of bytes at pBytes.
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.
numBytes The number of bytes at pBytes.
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 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.
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.
68 Porting the XCP ECU software
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
function XcpApp_CalMemGetChecksum() (see section 5.6.3).
On the “XCP – SEGMENT (part 2)” tab, a single PAGE must be created with the following parameter
values:
Parameter Value
PAGE_NUMBER 0
70 Integration with Visu-IT ASAP2 editor
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
COMPRESSION_METHOD 0
ENCRYPTION_METHOD 0
Checksum type This value should correspond to the checksum type implemented by the
function XcpApp_CalMemGetChecksum() (see section 5.6.3).
On the “XCP – SEGMENT (part 2)” tab, two PAGEs must be created with the following parameter
values:
Parameter Value
Page 0:
PAGE_NUMBER 0
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
INIT_SEGMENT 1
Page 1:
PAGE_NUMBER 1
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_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
COMPRESSION_METHOD 0
Integration with Visu-IT ASAP2 editor 71
Parameter Value
ENCRYPTION_METHOD 0
Checksum type This value should correspond to the checksum type implemented by the
function XcpApp_CalMemGetChecksum() (see section 5.6.3).
On the “XCP – SEGMENT (part 2)” tab, one PAGE must be created with the following parameter
values:
Parameter Value
PAGE_NUMBER 0
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_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.
72 Integration with Visu-IT ASAP2 editor
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
/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. 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
74 Integration with ETAS INCA
<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 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
0x01 /* segment logical number */
0x02 /* number of pages */
0x00 /* address extension */
0x00 /* compression method */
0x00 /* encryption method */
/begin CHECKSUM
<checksum type>
/end CHECKSUM
/begin PAGE
0x00 /* page number - reference page */
ECU_ACCESS_WITH_XCP_ONLY
XCP_READ_ACCESS_WITH_ECU_ONLY
XCP_WRITE_ACCESS_NOT_ALLOWED
INIT_SEGMENT 1
/end PAGE
/begin PAGE
0x01 /* page number - working page */
ECU_ACCESS_WITH_XCP_ONLY
XCP_READ_ACCESS_WITH_ECU_ONLY
XCP_WRITE_ACCESS_WITH_ECU_ONLY
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
0x01 /* segment logical number */
0x01 /* number of pages */
Integration with ETAS INCA 75
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_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 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
76 Integration with ETAS INCA
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
/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.
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
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