This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Component Implementation

1: 1907.0_LUA_Nexteer_CBD_GMLAN_31_Mch_Renesas RH850-CBD1400346B
2: 1907.0_LUA_Nexteer_CBD_GMLAN_31_Mch_Renesas RH850-CBD1400346B_ind
3: 1907.0_LUA_Nexteer_CBD_GMLAN_31_Mch_Renesas RH850-CBD1400346Bs
4: AN-IND-8-003_GM_Support_in_CANoe_7.2
5: AN-IND-8-003_GM_Support_in_CANoe_7.2_ind
6: AN-IND-8-003_GM_Support_in_CANoe_7.2s
7: AN-ISC-2-1052_CANbedded_and_Operating_Systems
8: AN-ISC-2-1052_CANbedded_and_Operating_Systems_ind
9: AN-ISC-2-1052_CANbedded_and_Operating_Systemss
10: AN-ISC-2-1081_Interrupt_Control_VStdLib
11: AN-ISC-2-1081_Interrupt_Control_VStdLib_ind
12: AN-ISC-2-1081_Interrupt_Control_VStdLibs
13: AN-ISC-8-1056_CANbedded_Program_Stack_Usage
14: AN-ISC-8-1056_CANbedded_Program_Stack_Usage_ind
15: AN-ISC-8-1056_CANbedded_Program_Stack_Usages
16: AN-ISC-8-1074_Possible_Loss_Of_Wakeup_Message
17: AN-ISC-8-1074_Possible_Loss_Of_Wakeup_Message_ind
18: AN-ISC-8-1074_Possible_Loss_Of_Wakeup_Messages
19: CANdelaStudio_Gm_contact
20: CANdelaStudio_Gm_contact_ind
21: CANdelaStudio_Gm_contacts
22: DeliveryDescription_CBD1400346
23: IssueReport_CBD1400346
24: IssueReport_CBD1400346_ind
25: IssueReport_CBD1400346s
26: TechnicalReference_CANdesc
27: TechnicalReference_CANdesc_ind
28: TechnicalReference_CANdesc_KWP_GM
29: TechnicalReference_CANdesc_KWP_GM_ind
30: TechnicalReference_CANdesc_KWP_GMs
31: TechnicalReference_CANdescs
32: TechnicalReference_Database_Attributes_GM
33: TechnicalReference_Database_Attributes_GM_ind
34: TechnicalReference_Database_Attributes_GMs
35: TechnicalReference_GMLANCalibration
36: TechnicalReference_GMLANCalibration_ind
37: TechnicalReference_GMLANCalibrations
38: UserManual_Startup_with_GMLAN_GENy
39: UserManual_Startup_with_GMLAN_GENy_ind
40: UserManual_Startup_with_GMLAN_GENys

Component Implementation

Component Documentation

1 - 1907.0_LUA_Nexteer_CBD_GMLAN_31_Mch_Renesas RH850-CBD1400346B

LIMITED USE SOFTWARE LICENSE AGREEMENT

2 - 1907.0_LUA_Nexteer_CBD_GMLAN_31_Mch_Renesas RH850-CBD1400346B_ind

Page 1
Page 2

3 - 1907.0_LUA_Nexteer_CBD_GMLAN_31_Mch_Renesas RH850-CBD1400346Bs

LIMITED USE SOFTWARE LICENSE AGREEMENT

0.1
This Limited Use Software License Agreement (“Agreement”), effective July 3, 2014 (“Effective Date”), by and
between  VECTOR  CANTECH,  INC.,  a    Michigan  corporation,  having  principal  offices  at  39500  Orchard  Hill  Place,
Suite 550, Novi, Michigan 48375 (“CANtech”); VECTOR INFORMATIK GmbH, a  German limited liability company,
having  principal  offices  at  Ingersheimer  Strasse  24,  D-70499  Stuttgart,  Federal  Republic  of  Germany  (“Informatik”)
(CANtech  and  Informatik  hereafter  collectively  referred  to  as  “Supplier”);  and  NEXTEER  AUTOMOTIVE
CORPORATION LLC, a Delaware limited liability company, having principal offices at  3900 E. Holland Rd, Saginaw,
Michigan 48601 (“Customer”).

Vector  and  Licensee  hereby  agree  the  following  as  stated  in  the  SECOND  AMENDMENT  TO  THE  SOFTWARE
LICENSE  AGREEMENT  AND  THE  GENERAL  TERMS  AND  CONDITIONS  FOR  INFORMATION  SYSTEMS  AND
SERVICES:

1.
"Licensed  Software"  –  means  both  the  embedded  software  and  PC  software  specified  in  Schedule  A,
together,  including,  where  applicable  but  not  limited  to,  source  code,  object  code  (including  microcode),  and  any
revisions, derivatives, enhancements, modifications, upgrades, updates or releases relating thereto, provided or to be
provided by Vector and all manuals, training materials, product, or other printed or electronic information relating to the
embedded software or the PC software.

2.
Grant of Limited Use License.  Supplier is delivering the software specified in Schedule A as requested by
Customer, under a limited use license, which is untested, non-validated, and non-warranted.  With respect to Software
delivered  by  Supplier  to  Customer  under  limited  use  license,  during  the  term  specified  in  the  Software  Specification
Document,  Supplier  hereby  grants  to  Customer  and  Customer  hereby  accepts  from  Supplier  a  worldwide,  non-
exclusive  and,  except  as  provided  herein,  an  irrevocable,  non-transferable  license  to  copy,  distribute,  use,  execute
and display the delivered Generation Tool PC Software object code, the Embedded Software Source Code, as well as
any  Source  Code  selected  therefrom  by  the  Generation  Tool  PC  Software,  which  license  shall  be  limited  to:  (i)  use
under  the  network  protocol  specified  in  the  corresponding  Purchase  Order,  Transaction  Agreement,  or  Software
Specification  Document  for  the  OEM  specified  in  the  corresponding  Purchase  Order,  Transaction  Agreement,  or
Software  Specification  Document,  (ii)  use  in  Customer’s  automotive  electronic  module  research  and  development
environment, excluding (A) any use in a mass production engine or vehicle, and (B) any use in any other applications
including,  but  not  limited  to  network  development  or  analysis  tools  for  sale,  aerospace,  medical  applications,
locomotive,  earth  moving  industries,  and  (iii)  use  on  the  specific  microcontroller  specified  in  the  corresponding
Purchase  Order,  Transaction  Agreement,  or  Software  Specification  Document  with  the  compiler  version  specified  in
the  corresponding  Purchase  Order,  Transaction  Agreement,  or  Software  Specification  Document.    Any  other  use,
distribution, copying, execution or display of the Embedded Software or Generation Tool PC Software licensed under
this Article 6 is expressly prohibited.

4.
CUSTOMER
ACKNOWLEDGEMENTS
AND
ASSUMPTION  OF  RESPONSIBILITY.    Customer
acknowledges and agrees that: (i) Customer is fully aware and has actual knowledge that prototype Software licensed
under this Article 6 is untested, non-validated, non-warranted, and potentially dangerous to life, limb, and property and
(ii)  Customer  shall  be  responsible  at  all  times  for  the  supervision,  control,  management,  condition,  development,
configuration, testing, integration, operation and any other use of the Software in any Software environment (“Use”),
including  without  limitation  any  Use  in  an  Electronic  Module  or  Electronic  Control  Unit  (ECU),  a  test  or  prototype
vehicle, or an engine (whether or not the engine is used in a vehicle or a dynamometer) and any Use of the Software
released to third parties by Customer.

5.
WARRANTY  DISCLAIMER.    AS  AN  EXPRESS  CONDITION  OF  CUSTOMER’S  USE  OF
SOFTWARE LICENSED UNDER THIS  ARTICLE 6, CUSTOMER  ASSUMES THE ENTIRE RISK  AS TO
THE USE AND PERFORMANCE.  SUCH SOFTWARE IS PROVIDED ‘AS IS’ WITHOUT WARRANTIES
OF  ANY  KIND,  EITHER  EXPRESS  OR  IMPLIED,  WHETHER  WRITTEN  OR  ORAL,  INCLUDING,  BUT
NOT  LIMITED  TO,  THE  IMPLIED  WARRANTIES  OF  MERCHANTABILITY  AND  FITNESS  FOR  A
PARTICULAR PURPOSE, WHICH ARE HEREBY SPECIFICALLY DISCLAIMED.

6.
LIMITATION  OF  LIABILITY  AND  INDEMNIFICATION.  EXCEPT  FOR  A  BREACH  OF  THE
REPRESENTATION AND WARRANTY OF NO INFRINGEMENT OR MISAPPROPRIATION SET FORTH
IN  SECTION  3.2(c)  AND  FOR  SUPPLIER'S  INDEMNITY  OBLIGATION  IN  SECTION  7.1(a)  OF  THE
TERMS AND CONDITIONS, SUPPLIER SHALL NOT BE LIABLE TO CUSTOMER FOR ANY DAMAGES
WHATSOEVER  THAT  ARISE OR RESULT FROM OR RELATE  TO  ANY SOFTWARE DELIVERED BY

Page 1 of 2

LIMITED USE SOFTWARE LICENSE AGREEMENT

SUPPLIER  TO  CUSTOMER  UNDER  THIS  ARTICLE  6,  INCLUDING  ANY  AMOUNTS  REPRESENTING
DIRECT  DAMAGES,  INDIRECT  DAMAGES,  CONSEQUENTIAL  DAMAGES,  INCIDENTAL  DAMAGES,
LOSS  OF  PROFIT,  LOSS  OF  BUSINESS,  EXEMPLARY  DAMAGES,  OR  PUNITIVE  DAMAGES  OF
CUSTOMER  OR  ITS  AFFILIATES,  INCLUDING  COSTS  OR  DAMAGES  RELATED  TO  PRODUCT
RECALLS, PROGRAM DEVELOPMENT/PRODUCTION DELAYS, WORK STOPPAGES, OR PRODUCT
LIABILITY.  CUSTOMER SHALL INDEMNIFY SUPPLIER AND ITS AFFILIATES FROM AND AGAINST
ANY AND ALL CLAIMS, LAWSUITS, AND OTHER DAMAGES, INCLUDING ATTORNEYS’ FEES, THAT
ARISE  OR  RESULT  FROM  OR  RELATE  TO  THE  AUTHORIZED  OR  UNAUTHORIZED  USE  OR
OPERATION  OF  THE  SOFTWARE,  INCLUDING  ANY  USE  BY  CUSTOMER’S  AFFILIATES,
SUPPLIERS,  OR  ITS  CUSTOMERS  OR  ANY  OTHER  THIRD  PARTY  TO  WHOM  CUSTOMER  HAS
PROVIDED THE SOFTWARE.

7.
Warning to Users.  Software provided to Customer pursuant to a Limited Use License shall contain a warning
message,  which  is  shown  at  start  up.  The  warning  message  shall  contain  the  phrases  “Limited  Use  License-No
Warranty” and “Not for Production Use”.”

8.
Termination.  This Agreement shall commence on the Effective Date stated above and shall continue for six
(6) months, unless terminated automatically upon: (a) the execution by Licensee and Vector of a mutually acceptable
Master Software License Agreement, governing Licensee’s use of the Licensed  Software, or (b) Licensee’s rejection
and return/destruction of the Licensed Software within six (6) months of the Effective Date, whereupon Licensee shall
provide Vector with satisfactory evidence of its removal from Licensee’s storage media and its return/destruction in the
form of a signed statement. Upon termination of this Agreement pursuant to Section 8(b), the license to any Licensed
Software  hereunder  shall  automatically  and  simultaneously  terminate  and  Section  5  (Warranty  Disclaimer)  and
Section 6 (Indemnification) shall survive the termination of this Agreement.  No refunds of License Fees shall be given
for termination of this Agreement.

9.
Entire  Agreement,  Applicable  Law.    Except  upon  termination  of  this  Agreement  pursuant  to  Section  8(a),
this Agreement and Schedules A hereto constitute the entire agreement between Vector and Licensee and supersede
any  prior or contemporaneous communications, representations  or agreements between  the parties,  whether oral or
written,  regarding  the  subject  matter  of  this  Agreement  or  Schedules  A.    Licensee's  terms  and  conditions  (including
those appearing on the front or reverse side of, or as an attachment to, a Licensee purchase order) shall not apply and
shall be null and void.  This Agreement and Schedules A may not be changed except through a written amendment to
this Agreement, signed by an authorized representative of each party.  This Agreement shall be governed by the laws
of the United States of America and the State of Michigan.

10.
This Limited Use License, having an effective date set forth above in Part 0.1 hereof, shall be subject to the
terms,  conditions,  and  limitations  of  the  Master  Software  License  Agreement  hereof,  which  are  hereby  incorporated
into and made a part of this Limited Use License by reference as though fully set forth herein.

SCHEDULE A  –  LICENSED SOFTWARE

Description & Form of Software (source code, etc.)
License Fee
Project:  CBD_GMLAN_31_Mch (BETA) Pre-Release
$ 7,000.00

Micro: Renesas RH850 Derivative: R7F701308
Compiler: GreenHills Compiler Version:  2013.5.5

Note: This package is offered at a reduced price based on the purchase of a
full package.  (Non-Production).

CBD1400346
PO#UI129133

Page 2 of 2

4 - AN-IND-8-003_GM_Support_in_CANoe_7.2

GM Support in CANoe 7.2

5 - AN-IND-8-003_GM_Support_in_CANoe_7.2_ind

Outline
Page 1
Page 2
Page 3
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13
Page 14
Page 15
Page 16
Page 17
Page 18
Page 19

6 - AN-IND-8-003_GM_Support_in_CANoe_7.2s

GM Support in CANoe 7.2

1.0  Overview
1.1  Introduction
As a simulation, analysis and testing tool for electronic control units, CANoe supports the GMLAN 3.0 protocol in a
special way. This document briefly describes the support provided by CANoe specifically for GMLAN and explains
the possible use cases of the “Test Feature Set” for GMLAN in detail. This document is based on CANoe version
7.2. Because CANoe support for GMLAN is extended continuously, we recommend that the reader checks whether
a newer version of this document is available.
The general Test Feature Set concept is explained in a separate document; see chapter 6.0. Familiarity with the
Test Feature Set is assumed in this document.
1.2  Terms and Abbreviations
Term
Meaning
CANoe Vector
product
SUT
System under Test
TFS Test
Feature
Set
ÆCANoe component
TSL Test
Service
Library
ÆTFS component
CAPL
CANoe Access Programming Language
ÆLanguage used for programming simulation
nodes, test modules etc. in CANoe.
hsCAN
High speed CAN Bus (GM-specific terminology)
swCAN
Single wire CAN Bus (GM-specific terminology)
GM extended
Message with a 29-bit identifier
message
Standard message  Message with an 11-bit identifier
Panel Designer
Vector product for editing panels
Panel Editor
Vector product for editing panels
Test Automation
Vector product for editing XML test modules
Editor
Table 1: Terms and Abbreviations

2
Application Note AN-IND-8-003

GM Support in CANoe 7.2

2.0  Basic Support in CANoe
Basic support for GMLAN is activated automatically as soon as a GMLAN network file is identified. The existence
and contents of the “UseGMParameterIds” network attribute are used as identification criteria.
Details about basic support, which are available in the Online Help for CANoe, are referenced briefly in the
following chapters.
2.1  Trace Window
Separate columns display GM-specific “SourceID”, “Prio” and “ParameterID” information. The “GMLAN” base
configuration can be selected. This contains basic information along with additional GM-relevant default columns
such as “Prio”, “PID”, “SourceID” and “CAN-ID”.
2.2  Logging
GM-extended messages are logged along with standard messages. The CAN-ID is decoded in the comment field
and documented separately as “ParameterID”, “SourceID” and “Prio”.
2.3  Export
Signal histories for standard messages can be exported from the log block, but this is not possible for signals on
GM-extended messages.
2.4  Interactive Generator Block
The Interactive Generator Block (IG) allows GM-extended messages to be sent. A special “GMLAN” tab is
provided for this purpose, as well as the ability to modify the message priority and SourceID.

Figure 1: Defining a message in the Interactive Generator Block
2.5  Generator Block
The Generator Block makes it possible to send GM-extended messages in symbolic entry mode.
2.6  Symbol Selection Dialog
The symbolic selection dialog makes it possible to select symbols from the network database (*.dbc).

3
Application Note AN-IND-8-003

GM Support in CANoe 7.2

2.6.1 Selecting a Message
Messages can be selected, for example, in filters, in the Interactive Generator Block and in the CAPL browser.

Figure 2: Message selection in the symbolic selection dialog

Only the message name is included in the CAPL browser, regardless of the path followed in the selection dialog.

4
Application Note AN-IND-8-003

GM Support in CANoe 7.2

2.6.2 Selecting a signal
Signals can be selected, for instance, in the CAPL browser, the Data Window and the Graphics Window.

Figure 3: Signal selection in the symbolic selection dialog

Only the signal name is included in the CAPL browser, regardless of how the selection dialog is navigated. If
additional qualifiers are required, these can be inserted in the CAPL browser by choosing “Insert message from
CANdb++…”.
2.7 Data Window
Application signals are fully supported in the Data Window.
.

Figure 4: Data Window

5
Application Note AN-IND-8-003

GM Support in CANoe 7.2

The send node of the signals can be checked in the special dialog “configuration overview” that is accessible from
the context menu of the Data Window:

Figure 5: Configuration overview
2.7.1  Special signals in the Data window
Message-specific statistical signals can be selected in the Data and Graphics windows. These are available for
standard messages but not for GM-extended messages.
2.8  Graphics Window
The Graphics Window allows the display of signals on a timeline. The notes that apply to the Data Window apply
equally to the selection of signals and special signals in the Graphics Window (see 2.7).
2.9  Panels
A panel may contain elements used to visualize and control signal values. The notes that apply to the Data
Window apply similar to the selection of signals here (see 2.7).
The Panel Editor selects a signal via a symbol path that contains the database name, the tx node, the tx message
and the signal. For older configurations (created with older versions than CANoe 7.0), it must be ensured that the
tx node is part of the symbol path (see area highlighted in red).

6
Application Note AN-IND-8-003

GM Support in CANoe 7.2

Figure 6: Configuration dialog for an “Input/Output Box” panel control
The Panel Designer fully supports GM by automatically inserting the tx node.
2.10 CAPL
A special message type – “gmlanMessage” – is available for GM-extended messages in CAPL, the CANoe
programming language. With this message type, the Prio and SourceID parameters present in addition to the
ParameterID can be queried using operators and set using special functions.
Relevant CAPL code fragments are available e.g. in chapter 4.3.

7
Application Note AN-IND-8-003

GM Support in CANoe 7.2

3.0  “GM Package” Modeling Package
The “GM Package” modeling package contains the following special GM-specific components:
• Interaction
layer
• Network
management
• Model
generation
•  Message panels for visualizing and controlling signal values.

Since the supplied manual of the GM Package provides details on the modeling package and the components
included in it, the following chapter discusses the functionality of the package only briefly.
The modeling package is not included in the default CANoe installation, but can be requested from Vector support
mailto:support@de.vector.com as a separate package free of charge.
3.1  Model Generation
The model generation wizard included in CANoe has been extended to include a GM option. swCAN and hsCAN
networks can be generated.

Figure 7: Model Generation Wizard

It is also possible to generate a multi-bus configuration.
Generation produces a complete CANoe configuration; the only action required is to select a node from the
alternative nodes in the GM network file and to deactivate or delete unused nodes in the simulation setup.
3.2  Node Panels, Message Panels
The configuration generated by the model generation wizard uses message controls developed especially for GM.
These message controls make it possible, for example, to modify the signal values that are transmitted by the
simulated nodes. The panels can be used to visualize signal values for concretely existing nodes.
These controls can be created/changed in the “Panel Editor”.

8
Application Note AN-IND-8-003

GM Support in CANoe 7.2

Figure 8: Panel for changing and visualizing all send signals of a node in their messages

In addition, a network management panel is generated for each node with which the virtual network status for
existing simulated nodes can be visualized and modified.

Figure 9: Panel for controlling and visualizing the network status for the current node

9
Application Note AN-IND-8-003

GM Support in CANoe 7.2

3.3  Interaction Layer
The interaction layer can be integrated into individual simulation nodes as a modeling DLL. It is used automatically
when a model is generated using the model generation wizard. The interaction layer configures itself on the basis
of the network database. Changes to the network database are therefore integrated automatically. The tasks of the
individual components are:
•  To provide a signal-oriented interface, i.e. individual signal values can be set as signal stimulants from
within in CAPL, panels and the Test Feature Set. When using the COM server, then ensure to use the
signal objects that are “outputs” or “inputs” of nodes.
•  To utilize the network database’s transmission model. Cyclical transmissions, spontaneous transmissions
in reaction to changes, etc. are sent to the bus in accordance with the transmission model.
•  For some test cases, it is also necessary to be able to send messages on request. This is supported as
well.
•  Linkage to the network management: The “virtual networks” observed by the network management are
known to the interaction layer. This affects whether a transmission should actually be sent or not.
•  To provide a standard fault injection interface which is suitable to control the sending of messages from
within CAPL. For more information about these functions refer to the CANoe Online Help. These
functionalities can also be used comfortable in CANoe Test Modules.
3.4  Network Management
Network management is also available as a special modeling DLL. This component also configures itself based on
information contained in the network database.
The individual tasks of the components are:
•  To control bus communications when waking up virtual networks and keeping them awake, insofar as the
node‘s role is that of an activator.
•  To observe bus communications in order to detect changes in the status of the virtual networks that control
the node.
•  Depending on the status of the virtual networks, the interaction layer is informed and its transmissions are
suppressed completely. The virtual networks can be activated or deactivated manually in CAPL or on the
panel.
•  To provide a CAPL interface that makes it possible to control virtual networks or remain informed of virtual
network status changes from within the application.

10
Application Note AN-IND-8-003

GM Support in CANoe 7.2

4.0  Modeling Control Units (ECUs) in CAPL
In principle, the following message types are available with GMLAN:
•  Standard messages (with 11-bit message IDs)
•  GM-extended messages (with 29-bit message IDs)
Messages of both types can be sent as well as received:
4.1  Signal Access
To access to signal values (set and get signal value) there is a tight way available by using the $-operator:
dword sigValue;
$ECC::A2RAlrmTime = 10; // set signal value
sigValue = $ECC::A2RAlrmTime; // get signal value
4.2  Receiving Standard Messages
Standard messages can be received and evaluated in the usual way by defining “on message” handlers:
on message Dynamic_Normal_Force
{
long val;
val = this.DynNrmlFrcFrLfWhl; // signal access
// Application code …
}
4.3  Receiving GM-Extended Messages
GM-extended messages can be received and evaluated by defining “on gmlanmessage” handlers: The message
handler can then be programmed specifically for one or more SourceIDs:
on gmlanmessage Chime_Status
{
long val;
if(gmLanGetSourceId(this) == AMP.SourceId)
{
val = this.ChmAct;
// Application code …
}
}
4.4  Receiving Signals Directly
Signals can be received directly in CANoe by defining an “on signal” handler in CAPL. This is supported for signals
on standard messages but not currently for signals on GM-extended messages.

11
Application Note AN-IND-8-003

GM Support in CANoe 7.2

4.5 Sending Standard Messages
Standard messages are sent according to the following general principle:
message Dynamic_Normal_Force msg;
msg.DynNrmlFrcFrLfWhl = 1; // example signal value
output(msg);

4.6 Sending GM-Extended Messages
Before a GM-extended message is sent, the SourceID must be specified; whereas the Prio is added automatically:
gmlanmessage ChimeStatus msg;
gmLanSetSourceId(msg, AMP.SourceId);
output(msg)
Hint: When working signal oriented (4.1), the message is sent by the Interaction layer; no need to care about
SourceIDs.

12
Application Note AN-IND-8-003

GM Support in CANoe 7.2

5.0  Test Feature Set
5.1  Test Feature Set in CAPL
A typical test sequence consists of
•  Stimulation of signals or messages (SUT input vector)
•  Allowance for a SUT settling time until the expected reaction is to occur, and
•  Evaluation of signal states or message events (SUT output vector) in response to the stimulation.

The allowed settling time can be shortened by specifying a concrete event in the test sequence, e.g. receipt of a
message with a specific message ID.
Test sequences can be structured into test cases, test groups and test modules.
The CANoe test sequence and test structure apply equally to GMLAN, regardless of whether the test modules are
formulated in CAPL, XML or .NET. There are, however, a number of particularities, which are explained in the
following chapters.
5.1.1  Configuring the Restbus Simulation
The restbus simulation is used directly by the Test Feature Set. Based on the interaction layer configured there, it
takes charge of sending messages and thus of signal stimulation. Consequently, the prerequisite for the
stimulation of signal values is that the restbus simulation node is present in the simulation setup and is assigned to
the database node, and that the “CANoe GM Interaction Layer” modeling DLL is assigned to the simulation node.
Note:
The restbus simulation will be correctly and fully configured if it is created using the “model
generation wizard” that comes with the modeling package. Use of this generation method is
therefore recommended.

5.1.2  Signal Abstraction – Evaluation
Note:
For signals that are mapped onto GM extended messages the signal symbol has to be prefixed by
the send node, e.g. checkSignalInRange(ECC::A2RAlrmTime, 10, 20).
A signal value can be compared directly to a specified interval using the following functions:
long checkSignalInRange(dbSignal aSignal,
float aLowLimit,
float aHighLimit);

Combined signal value queries, immediate comparison with a specified interval and automatic recording of the
actual and target values for the comparison results are also possible by means of special functions:

13
Application Note AN-IND-8-003

GM Support in CANoe 7.2

long testValidateSignalInRange (char aTestStep[],
dbSignal aSignal,
float aLowLimit,
float aHighLimit)
long testValidateSignalOutsideRange (char aTestStep[],
dbSignal aSignal,
float aLowLimit,
float aHighLimit)
Please refer to the CANoe Online Help for further details about these functions.
5.1.3 Signal Abstraction – Stimulation
Signal values can be stimulated with the $-operator (4.1). This requires (at least for the specified Tx node) a
configured restbus simulation (5.1.1).
$ECC::A2RAlrmTime = 10;
If a signal that is already being sent by a real ECU is to be stimulated as part of a test sequence, then the real ECU
should be stimulated, thereby indirectly causing the changed signal value to be sent.
Using the signal stimulation within the Test Feature Set the stimulation is reported in the test report.
5.1.4 Message Abstraction – Evaluation
There are also wait functions available for testing message events, with which the test sequence pauses until the
event condition is fulfilled. Simulation node techniques (see 4.1 and 4.3) are available likewise. These wait
functions can be used either symbolically by specifying a message symbol from the network file or numerically by
specifying a message ID.
For standard messages these are:
long TestWaitForMessage(dbMessage aMsg, dword aTimeout)
long TestWaitForMessage(long aMsgId, dword aTimeout)

For GM-extended messages, only the numeric function for passing the message ID is available; alternative ways
of using the wait function are described below:
a) Symbolic setup via instantiation of a message buffer
The “aMsgId” expected in the function is created by means of a series of calls. The example below is
constructed for the send node “AMP” that transmits the message “Chime_Status”, with a maximum wait
time of 2000ms:

14
Application Note AN-IND-8-003

GM Support in CANoe 7.2

// Example signal evaluation on message level
testcase a ()
{
gmlanmessage Chime_Status msg;

if(testWaitForMessage(gmLanId(Chime_Status, AMP), 2000) == 1)
{
testGetWaitEventMsgData(msg);

if(msg.ChmAct == 1)
TestStepPass("A", "Message received, signal matches");
else
TestStepFail("A", "Message received, signal does not match");
}
else
TestStepFail("A", "Message missing");
}

Commonly, application level tests are done by using signal access and signal test functions. Message
level checks are done mostly by utilizing the TSL checks (refer 5.3 for details).
b) Numerical setup via modification of a message buffer
If the name of the message or send node is not known in CAPL and the message ID is to be set up in a
strictly numerical manner, the following steps are necessary:
// initialise local variables
gmlanmessage * msg1;

// do something, e.g. stimulate the SUT

// Set up and wait for response
msg1.id = (0x10);
gmLanSetSourceId(msg1, 0x81);
gmLanSetPrio(msg1, 4);
TestWaitForMessage(msg1.id, 2000);

5.1.5  Message Abstraction – Stimulation
GM messages are sent in the same way as in simulation nodes. Standard GM messages are handled as described
in the CANoe Online Help. Only the GM-extended messages require special treatment: The “Prio” and “SourceID”
parameters can be added to a CAN-ID in the following ways:
Numerically, within the variable definition:
testcase numericOutput()
{
gmlanmessage 0x10x msg1 = {SA =0x81, PRIO= 0x4};
output(msg1);
}
Specifying PRIO (for the message priority) is optional, as this is taken from the message definition. If it is not
specified, the SA selector (for the SourceID) is taken to be 0. For this reason, it is absolutely necessary to add the
SourceID by using, for example, the following process (see also 4.6):

15
Application Note AN-IND-8-003

GM Support in CANoe 7.2

testcase symbolicOutputProgrammatic()
{
gmlanmessage Chime_Status msg2;
gmLanSetSourceId(msg2, AMP.SourceId);
output(msg2);
}
5.1.6 Interaction Layer Fault Injection Functions
There are also Fault Injection functions available which are suitable to control the sending of messages, e.g. to
change the cycle time, to suppress messages completely or to change the DLC of messages. For more information
about these functions refer to the CANoe Online Help.
These fault injection functions can also be used for messages with extended IDs. Therefore the ID-based functions
have to be used:
id_DDM = gmLanId(Driver_Door_Status, DDM);
TestDisableMsg(id_DDM);
This example disables the sending of the message “Driver_Door_Status” of node “DDM”.
5.2 Test Feature Set in XML
GMLAN requires no new constructs with the Test Feature Set in XML test modules. The existing qualification of
signals using send nodes can be used directly here and must be used for GM-extended messages and their
signals.
The table below shows the existing test functions and their GM support:
Test function name
Usage in test modules for messages with standard or GM-
extended IDs
Await Value Match
3
CANstress Configuration
3 Trigger/disturbance definition for standard IDs
: Trigger/disturbance definition for GM-extended IDs
CANstress State
3
Diagnostics Service
3
Diagnostics Service Check
3
(replaced by Diagnostics Service)
Initialize
3 for signal abstraction
3 for message abstraction
Replay
3
Request Response
3
Set
3 for signal abstraction
3 for message abstraction
State Change
3
State Check
3
Stimulate Ramp
3
System Call
3
Tester Confirmation
3
Until End
3
VT System Configuration
3
Wait
3
Window Capture
3
Table 2: XML Test Functions

16
Application Note AN-IND-8-003

GM Support in CANoe 7.2

Syntax example for GM-extended:
<testcase title="my GM test case">
<statechange wait="200ms">
<in>
<cansignal id="stim_sig" node="sender">
10
</cansignal>
</in>
<expected>
<cansignal id="expected_sig" node="sender">
<eq>10</eq>
</cansignal>
</expected>
</statechange>
</testcase>

17
Application Note AN-IND-8-003

GM Support in CANoe 7.2

5.3  Test Service Library in CAPL and XML Test Modules
The table below shows the existing check objects (“TSL checks”) and their usage for different message types:
Check base name
Usage in test modules
Usage in test modules for messages with
for messages with
GM-extended IDs
standard IDs

CAPL
XML
CAPL
XML
Cycle Time (Abs)
For message
3
3
3 (ID-based)
3
Cycle Time (Rel)
For message
3
3
3 (ID-based)
3
For node
3
3
3
3
DLC Monitoring
For single message
3
3
3 (ID-based)
3
For all tx messages of node
3
3
3
3
For all rx messages of node
3
3
3
3
Error Frame Check
3
3
3
3
Fallback Observation
--
3
--
3
Message Distance
3
3
3 (ID-based)
3
Unknown Message Received
3
3
3
3
Signal Value Constancy
3
3
3
3
Node Active
For message list
--
3
--
3
For single node
3
3
3
3
For all nodes
3
--
3
--
Node Inactive

For message list
--
3
--
3
For single node
3
3
3
3
For all nodes
3
--
3
--
Absence of Defined Message
3
3
3 (ID-based)
3
Occurrence of a Message
For single message
3
3
3 (ID-based)
3
For node
3
--
3
--
Request Response Check
--
3
--
3
Value Invariant
--
3
--
3
Signal Value
3
3
3
3
Timeout Check
3
3
3
3
Table 3: Test Service Library Checks

Symbols
Meaning
3
Fully supported
--
Generally not available (specific feature of
XML test modules or CAPL test modules)
:
Not supported for GM-extended messages

18
Application Note AN-IND-8-003

GM Support in CANoe 7.2

5.4 Test Automation Editor
The Test Automation Editor 1.1 supports fully the GMLAN networks and the editing of XML test modules.
It provides a setting to fill in always the send node of an added symbol.

For further information about the separate Vector product Test Automation

Document Outline

7 - AN-ISC-2-1052_CANbedded_and_Operating_Systems

CANbedded and Operating Systems

8 - AN-ISC-2-1052_CANbedded_and_Operating_Systems_ind

Page 1
Page 2
Page 3
Page 4
Page 5

9 - AN-ISC-2-1052_CANbedded_and_Operating_Systemss

CANbedded and Operating Systems
Version 1.0
2007-01-18
Application Note AN-ISC-2-1052

Author(s) Hartmut
Hörner, Patrick Markl
Restrictions Restricted
Membership
Abstract
The Vector CANbedded software components have some requirements for the run-time
environment. These requirements are described in this application note.

Table of Contents

1.0
Overview ..........................................................................................................................................................1
2.0
General Requirements.....................................................................................................................................1
3.0
Interrupt Handling ............................................................................................................................................2
3.1
Interrupt Service Routines (ISRs) .................................................................................................................2
3.2
Access to interrupt control registers..............................................................................................................2
4.0
Data consistency..............................................................................................................................................3
5.0
Memory protection and virtual memory management .....................................................................................3
6.0
Privilege modes ...............................................................................................................................................4
7.0
Operating systems with stringent driver models..............................................................................................4
8.0
Startup Time ....................................................................................................................................................5
9.0
Contacts...........................................................................................................................................................5

1.0 Overview
The Vector CANbedded components have some requirements for the run-time environment. Some of these might
impact the usage of the operating system elements as well as the real-time design.
Two run-time environments are explicitly supported by CANbedded:
•  A system without operating system
•  An OSEK Operating System (version 2.1r1 onwards) such as Vector osCAN

In the following chapters the requirements are listed and for some cases where no explicitly support exists
workarounds are described.
2.0 General Requirements
Higher layer CANbedded components require an initialization function and one or more cyclic functions.
CANbedded hardware drivers have an initialization function, ISRs in interrupt driven mode and cyclic functions in
polling mode. The initialization function must be called before the cyclic function is called for the first time and
before the first ISR occurs.
The CANbedded stack requires a shared address space with the application since some functionalities such as
signal and flag access are implemented by macros.
There are no requirements for dynamic memory management. All not constant global variables are explicitly
initialized in the initialization functions. There are no requirements for memory initialization in the start-up code
unless constant data is located in RAM.
1
Copyright © 2007 - Vector Informatik GmbH
Contact Information: www.vector-informatik.com or ++49-711-80 670-0

CANbedded and Operating Systems

Since the CANbedded components have to interface directly with the communication hardware adequate access
privileges are required.
3.0 Interrupt Handling
3.1  Interrupt Service Routines (ISRs)
If the CAN Driver is used in an interrupt driven mode one or more ISRs must be installed.
Two categories of ISRs are supported:
•  ISR implemented with the related compiler pragma or qualifier. This is used in a system without operating
system and for OSEK-OS ISRs of category 1.
•  OSEK-OS ISR category 2.

If an operating system other than OSEK is used the following workaround is possible:
If OSEK-OS and OSEK-OS category 2 ISR support are selected in the generation tool the ISR has the following C
syntax:

ISR(CanInterrupt)
{
…
}

Supply a header file osek.h with the following macro, to make the ISR available in other modules as a void-void
function.

#define ISR(x) void x(void)

Example for an operating system which provides a service OSRegisterISR to register an ISR:

OSRegisterISR(CanInterrupt, 10);     /* second parameter is interrupt vector number */

If the prototype of the ISR required by the OS is not of the kind void x(void) an intermediate function must be used
to circumvent type conflicts.
3.2  Access to interrupt control registers
To achieve its own data consistency and to export such services to the application the CANbedded components
require access to the interrupt control registers of the communication controller and to interrupt control registers of
the interrupt controller or the CPU which allow to disable interrupts globally or up to a certain level.
If it is not desirable or possible that the CANbedded components access the global interrupt directly this
functionality can be replaced by other mechanisms (“interrupt control by application”, supported in CAN driver RI
version 1.4 onwards).
If a resource locking mechanism of the operating system is used it must support nested critical sections.

2
Application Note AN-ISC-2-1052

CANbedded and Operating Systems

4.0 Data consistency
For efficiency reasons some services of the CANbedded components are implemented as macros with
unprotected critical sections. If these macros are used in multiple full-preemptive tasks or in multiple ISRs data
consistency problems can be caused. One of the following solutions is possible:
•  Use these services only in non-preemptable tasks
•  Use these services only in one cooperative task group (OSEK: internal resource concept)
•  Supply critical section in the application code

Some CANbedded components have specific requirements concerning processing priorities and reentrancy. These
requirements are described in the technical reference of the individual component.

5.0  Memory protection and virtual memory management
This chapter is only applicable if the processor and the run-time environment support such mechanisms.
Since some CANbedded services are implemented as macros which access to global variables the application part
which uses the CANbedded services and the complete CANbedded stack must reside in one address space.
In addition all CANbedded tasks and ISRs must be able to access the peripheral address space of the
communication hardware.
The following figure shows a possible configuration with three different applications with an own address space.
Two applications perform application tasks (drawn in green), one application is responsible for the communication
(drawn in red).
Application 1
Application 2
Communication application
CANbedded stack
Communication hardware

Figure 1 Different applications with own address space

To move data between the applications operating system services are required which have the capability to tunnel
the address barrier (drawn with blue arrows)..

3
Application Note AN-ISC-2-1052

CANbedded and Operating Systems

6.0 Privilege modes
This chapter is only applicable if the processor and the run-time environment support such mechanisms.
In some architectures different privilege modes such as user and supervisor mode are defined. If a task or ISR is
running in user mode the access to peripheral hardware and global resources such as interrupt control registers
may be restricted.
It must be possible to assign all tasks and ISRs which provide or use CANbedded services a sufficient privilege
level to allow for:
•  Access to communication hardware
•  Access to communication related interrupt control
•  Access to global interrupt control registers including the capability to execute instructions related to global
interrupt control registers unless interrupt control by application is used (s. chapter 3.2).

If such a privilege level is not possible for tasks but only for ISRs a cyclic timer ISR can be used to perform all
required CANbedded cyclic processing. Note that such an ISR must have a lower interrupt level than the ISRs of
the CANbedded drivers.
7.0  Operating systems with stringent driver models
This chapter is only applicable if the run-time environment supports such mechanisms.
In some operating systems hardware access is only allowed for specific hardware drivers which have to follow a
predefined implementation model. When a hardware driver is called in such a system the required privileges are
assigned. To allow the usage of CANbedded a wrapper layer between application and CANbedded is required to
implement the required driver interface.
Such a design is illustrated in the figure below, the driver interface is drawn with blue arrows:
Application 1
Application 2
Wrapper layer
CANbedded stack

Figure 2 With Wrapper Layer

4
Application Note AN-ISC-2-1052

CANbedded and Operating Systems

8.0 Startup Time
Some Operating systems (especially more sophisticated and larger ones) are running out of RAM, while the
binaries are stored in non-volatile memories like Flash. This requires that the startup code transfers the OS image
into RAM after power on reset. Depending on the size of the OS image this can take up to several hundreds of
milliseconds. As a consequence the initialization of the CANbedded stack occurs after the kernel is loaded
completely. Often this long startup times do not match the OEMs’ startup requirements. There are two possibilities
to solve this issue. Either the OEM accepts the longer startup time or the operating system supports a mechanism
that allows initialization of the CANbedded stack before the kernel is loaded completely.
If the operating system supports some kind of a runtime environment before the kernel is loaded it could be also
relevant to have a possibility to hand over the information received during the startup phase via CAN to the fully
loaded kernel environment.
9.0 Contacts

Vector Informatik GmbH
Vector CANtech, Inc.
VecScan AB
Ingersheimer Straße 24
39500 Orchard Hill Pl., Ste 550
Lindholmspiren 5
70499 Stuttgart
Novi, MI 48375
402 78 Göteborg
Germany
USA
Sweden
Tel.: +49 711-80670-0
Tel: +1-248-449-9290
Tel: +46 (0)31 764 76 00
Fax: +49 711-80670-111
Fax: +1-248-449-9704
Fax: +46 (0)31 764 76 19
Email: info@vector-informatik.de
Email: info@vector-cantech.com
Email: info@vecscan.com

Vector France SAS
Vector Japan Co. Ltd.

168 Boulevard Camélinat
Seafort Square Center Bld. 18F
92240 Malakoff
2-3-12, Higashi-shinagawa,
France
Shinagawa-ku
Tel: +33 (0)1 42 31 40 00
J-140-0002 Tokyo
Fax: +33 (0)1 42 31 40 09
Tel.: +81 3 5769 6970
Email: information@vector-france.fr
Fax: +81 3 5769 6975

Email: info@vector-japan.co.jp

5
Application Note AN-ISC-2-1052

10 - AN-ISC-2-1081_Interrupt_Control_VStdLib

Application Interrupt Control with VStdLib

11 - AN-ISC-2-1081_Interrupt_Control_VStdLib_ind

Page 1
Page 2
Page 3
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13

12 - AN-ISC-2-1081_Interrupt_Control_VStdLibs

Application Interrupt Control with VStdLib
Version 1.0
2008-08-06
Application Note AN-ISC-2-1081

Author(s) Patrick
Markl
Restrictions Restricted
Membership
Abstract
This application note explains how the application can control interrupt handling via the
VStdLib and which constraints apply.

Table of Contents

1.0
Overview ..........................................................................................................................................................1
1.1
Introduction....................................................................................................................................................1
2.0
Interrupt Control by Application .......................................................................................................................3
2.1
Constraints ....................................................................................................................................................3
2.1.1
Constraint 1: Nested Calls ..........................................................................................................................3
2.1.2
Constraint 2: Recursive Calls when Disabling CAN Interrupts...................................................................3
2.1.3
Constraint 3: No Locking when Disabling CAN Interrupts..........................................................................3
3.0
Solution ............................................................................................................................................................6
3.1.1
Nested Calls................................................................................................................................................6
3.1.2
No Locking of Interrupts..............................................................................................................................7
4.0
Referenced Documents .................................................................................................................................12
5.0
Contacts.........................................................................................................................................................13

1.0 Overview
This application note describes how the user can configure the interrupt control options of the VStdLib. Some
applications provide their own lock/unlock functions, which better fulfill the application’s needs. Because of this the
VStdLib provides a means which allows the application to use it’s own lock/unlock functions, instead of the
implementation provided by the VStdLib.
This application note describes the handling of this use case in more detail.
1.1 Introduction
The VStdLib provides functions to lock/unlock interrupts. There are three options to be set in the configuration tool,
as shown in figure1. The first option (Default) lets the VStdLib lock global interrupts. Depending on the hardware
plattform it is also possible to lock interrupts to a certain level. The lock is implemented by the VStdLib itself.

Figure 1: Possible configuration options for VStdLib interrupt control
1
Copyright © 2008 - Vector Informatik GmbH
Contact Information: www.vector-informatik.com or ++49-711-80 670-0

Application Interrupt Control with VStdLib

The second option (OSEK) is to configure the VStdLib in a way that locking of interrupts is done by means of
OSEK OS functions. The third and last option (User defined) requires the application to perform the
locking/unlocking functionality within callback functions.
This application note focusses mainly on the third option. It describes the way the application has to implement the
callback functions required by the VStdLib.

Figure 2: Configuration of interrupt control by application

Figure 2 shows the VStdLib configuration dialog, if interrupt control by application is configured. The user has to
enter the names of two functions in the dialog, which will be called by the VStdLib in order to lock/unlock interrupts.
If the user has specified the callback function names as shown in figure 2, the application must provide the
implementations of these two two functions. The prototypes are:

void ApplNestedDisable(void);
void ApplNestedRestore(void);

From now on these two function names will be used within this application note.
These two functions are called by the VStdLib, in case any Vector component requests a lock for a critical section.
The user has to make sure that the locking mechanism within these two functions is sufficient to protect data. This
depends heavily on the architecture of the application. The more priority levels exists, which call Vector functions,
the more restrictive the lock must be.

Please check the technical references of the other Vector components for restrictions regarding the call
context of the API functions.

2
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

2.0  Interrupt Control by Application
This configuration option is usually used, if a global lock is not desired by the user or special lock mechanisms are
used. Once this option is configured, there are two functions to be provided by the application. The user can
specify the names of these functions in the configuration dialog of the VStdLib. The VStdLib calls these functions
instead of directly locking/unlocking interrupts. This means, if any Vector component requests an interrupt lock, it is
finally performed by the application provided functions.
The first function is called, in order to perform a lock operation. It is expected, that the application function stores
the current interrupt state(or any other), in order to restore it later. The second function is to restore the previously
saved lock state.
The implementation of these two functions is up to the user. The user may lock just certain interrupt sources or set
a mutex, semaphore or whatever ensures consistent data and fulfills the call context requirements, described in the
Vector component specific technical references.
2.1 Constraints
The usage of Interrupt Control by Application has some constraints, which have to be taken into account. The
following chapters describe them.
2.1.1  Constraint 1: Nested Calls
It is expected that the two callback functions (ApplNestedDisable()/-Restore()) are implemented in a way that
nested calls are possible. This means if the function ApplNestedDisable() was called by some software component
it may happen that this function is called again from somewhere else. This has to be taken into account when
saving and restoring the interrupt state! The implementer of these two function can assume that the number of lock
and unlock calls is identical and nesting is balanced.
2.1.2  Constraint 2: Recursive Calls when Disabling CAN Interrupts
Instead of implementing an own lock mechanism, the user could configure interrupt control by application and call
the CAN driver’s CanCanInterruptDisable()/-Restore() functions. These two function simply disable CAN interrupts
for the given CAN channel. These two CAN driver functions protect the access to their state variables by means of
the VStdLib’s lock mechanism, which would again be implemented by the callbacks provided by the application.
This would cause an indirect recursion.

Please note that CanCanInterruptDisable()/Restore() shall not be called from
ApplNestedDisable()/Restore(). This application note does not provide a solution for this use case!

2.1.3  Constraint 3: No Locking when Disabling CAN Interrupts
One could think of letting the application directly modify the interrupt flags of the CAN controller, to overcome the
recursion, described in the previous chapter. But this would cause the CAN interrupts to be never locked, when
CanCanInterruptDisable() is called, by any component. The reason is that the application’s interrupt lock code
would interfere with the code in the CAN driver’s function CanCanInterruptDisable(). The following pseudo code
shows the way CanCanInterruptDisable() is implemented. It is assumed that ApplNestedDisable()/-Restore() are
implemented to allow nested calls.

3
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

/* CAN Interrupt will be never locked in this example!!! */
void CanCanInterruptDisable(CAN_CHANNEL_CANTYPE_ONLY)
{
ApplNestedDisable();
Lock CAN interrupts
ApplNestedRestore();
}

void ApplNestedDisable(void)
{
Save current CAN interrupt state();
Lock CAN Interrupts();
}

void ApplNestedRestore(void)
{
Restore CAN interrupts to previous state();
}

Figure 3 shows what happens in this case. The function CanCanInterruptDisable() calls ApplNestedDisable() in
order to protect an internal counter. This lock function disables the CAN interrupts, afterwards the CAN driver’s
function locks the CAN interrupts too. The next thing is to call ApplNestedRestore() which again is implemented by
the application and restores the previous CAN interrupt state – in this case enables the CAN interrupts. Now an
inconsistency exists. The code which called CanCanInterruptDisable() assumes locked CAN interrupts, but they
aren’t

4
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

sd FailedLock
Component
CAN Driver
Application
CAN Controller
CanCanInterruptDisable
VStdGlobalInterruptDisable
Lock CAN Interrupt
Lock CAN Interrupt
VStdGlobalInterruptRestore
Unlock CAN Interrupt

Figure 3: Sequence diagram of CanCanInterruptDisable()

5
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

3.0 Solution
This chapter proposes a solution and a code examples, to overcome the constraints 1 and 3 described in the
previous chapters.
3.1.1 Nested
Calls
Solving the first issue – nested calls – is simply done by introducation of a nesting counter. The callbacks
implemented by the application need to manage this counter. The counter is to be incremented, if the function to
lock interrupts is called and decremented if the unlock function is called. The application has to take care to
initialize this counter, before any Vector function is called, in order to ensure a consistent interrupt locking.
The interrupt state is to be modified only if the counter has the value zero. If the value is greater than zero, the
counter is just maintained. The following code example shows, how this nested counter could be implemented.

/* Global variable as nesting counter */
vuint8 gApplNestingCounter;

/* Must be called before the Vector components are initialized! */
void SomeApplicationInitFunction(void)
{
gApplNestingCounter = (vuint8)0;
}

void ApplNestedDisable(void)
{
/* check counter – lock if counter is 0 */
if((vuint8)0 == gApplNestingCounter)
{
/* Save current state and perform lock */
ApplicationSpecificSaveStateAndLock();
}
/* increment counter – do not disable if nested, because already done */
gApplNestingCounter++;
}

void ApplNestedRestore(void)
{
gApplNestingCounter--;
if((vuint8)0 == gApplNestingCounter)
{

6
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

ApplicationSpecificRestoreToPreviousState();
}
}

3.1.2 No Locking of Interrupts
Constraint 3 described a situation, in which the CAN interrupts are not locked at all. This is because the application
implements a lock function, which modifes the CAN interrupt registers with own code. To overcome this issue, a
global flag needs to be implemented. This global flag tells the application, when to lock or unlock CAN interrupts.
The flag is set within two additional callback functions to be implemented by the application. The prototypes of the
additional callbacks are:

void ApplCanAddCanInterruptDisable(CanChannelHandle channel);
void ApplCanAddCanInterruptRestore(CanChannelHandle channel);

The callback functions are called by the CAN driver from within the functions CanCanInterruptDisable() and
CanCanInterruptRestore() and have to be enabled by means of the preprocessor define
C_ENABLE_INTCTRL_ADD_CAN_FCT. This is done, by creating a user config file, which contains this definition.
More information about these two functions can be found in [1].
The sequence diagrams in figure 4 and figure 5 show the lock and unlocking procedure respectively.

7
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

sd InterruptControlByApplication_Lock
Component
CAN Driver
VStdLib
Application
CanCanInterruptDisable
CanNestedGlobalInterruptDisable
ApplDisableFunc
Lock if
Flag
cleared
Lock CAN Interrupts
ApplCanAddCanInterruptDisable
Set
Global
Flag
CanNestedGlobalInterruptRestore
ApplRestoreFunc
Unlock
if Flag
cleared

Figure 4: Sequence diagram for locking just CAN interrupts.

8
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

sd InterruptControlByApplication_UnLock
Component
CAN Driver
VStdLib
Application
CanCanInterruptRestore
VStdGlobalInterruptDisable
ApplDisableFunc
Lock if
Flag
cleared
Restore CAN Interrupts
ApplCanAddCanInterruptRestore
Clear Global Flag
VStdGlobalInterruptRestore
ApplRestoreFunc
Unlock
if Flag
cleared

Figure 5: Sequence diagram for unlocking just CAN interrupts

The following code example shows how to implement the handling of the global flag. If the function
CanCanInterruptDisable() is called, it calls the ApplNestedDisable(), in order to protect a counter. This function
locks CAN interrupts using own code. When ApplNestedDisable() returns, the CAN driver locks CAN interrupts too.
Afterwards ApplCanAddCanInterruptDisable() is called. This function is implemented by the application and sets
the global flag. Before the function CanCanInterruptDisable() returns, it calls ApplNestedRestore(). The application,
which implements the restore callback function has to check, if the global flag is set. If yes, the CAN interrupts
must not be unlocked!
If the function CanCanInterruptRestore() is called, first ApplNestedDisable() is called again. Then the CAN driver
unlocks the CAN interrupts (if its nesting counter reached the value zero) and calls the function
ApplCanAddCanInterruptRestore(). Within this function the flag is cleared. If ApplNestedRestore() is called now,
the flag is not set anymore and the restore of the CAN interrupts is performed.

9
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

Note that the application needs to implement also a nesting counter, if it uses own code to lock CAN interrupts, in
order to avoid the issue described by constraint 1. The following code example shows, how to implement the
nesting counter and the flag.

vuint8 gCanLockFlag;
vuint8 gApplNestingCounter;

void ApplicationInitFunction(void)
{
/* initialize the flags */
gCanLockFlag = (vuint8)0;
gApplNestingCounter = (vuint8)0;
}

void ApplNestedDisable(void)
{
if((vuint8)0 == gApplNestingCounter)
{
if((vuint8)0 == gCanLockFlag)
{
Save current CAN interrupt state();
Lock CAN Interrupts();
}
}
gApplNestingCounter++;
}

void ApplNestedRestore (void)
{
gApplNestingCounter--;
if((vuint8)0 == gApplNestingCounter)
{
if((vuint8)0 == gCanLockFlag)
{
Restore CAN interrupts to previous state();
}

10
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

}
}

void ApplCanAddCanInterruptDisable(CanChannelHandle channel)
{
gCanLockFlag = (vuint8)1;
}

void ApplCanAddCanInterruptRestore(CanChannelHandle channel)
{
gCanLockFlag = (vuint8)0;
}

11
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

4.0 Referenced Documents
The following table contains the referenced documents.

Referenced Documents
[1] TechnicalReference_CANDriver.pdf

12
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

5.0 Contacts

Vector Informatik GmbH
Vector CANtech, Inc.
VecScan AB
Ingersheimer Straße 24
39500 Orchard Hill Pl., Ste 550
Lindholmspiren 5
70499 Stuttgart
Novi, MI 48375
402 78 Göteborg
Germany
USA
Sweden
Tel.: +49 711-80670-0
Tel: +1-248-449-9290
Tel: +46 (0)31 764 76 00
Fax: +49 711-80670-111
Fax: +1-248-449-9704
Fax: +46 (0)31 764 76 19
Email: info@vector-informatik.de
Email: info@vector-cantech.com
Email: info@vecscan.com

Vector France SAS
Vector Japan Co. Ltd.
Vector Korea IT Inc.
168 Boulevard Camélinat
Seafort Square Center Bld. 18F
Daerung Post Tower III, 508
92240 Malakoff
2-3-12, Higashi-shinagawa,
Guro-gu, Guro-dong, 182-4
France
Shinagawa-ku
Seoul, 152-790
Tel: +33 (0)1 42 31 40 00
J-140-0002 Tokyo
Republic of Korea
Fax: +33 (0)1 42 31 40 09
Tel.: +81 3 5769 6970
Tel.: +82-2-2028-0600
Email: information@vector-france.fr
Fax: +81 3 5769 6975
Fax: +82-2-2028-0604

Email: info@vector-japan.co.jp
Email: info@vector-korea.com

13
Application Note AN-ISC-2-1081

13 - AN-ISC-8-1056_CANbedded_Program_Stack_Usage

CANbedded Program-Stack usage

14 - AN-ISC-8-1056_CANbedded_Program_Stack_Usage_ind

Page 1
Page 2
Page 3
Page 4
Page 5
Page 6

15 - AN-ISC-8-1056_CANbedded_Program_Stack_Usages

CANbedded Program-Stack usage
Version 1.0
2007/01/08
Application Note AN-ISC-8-1056

Author(s) Andreas
Raisch
Restrictions Customer
confidential
- subject to prior approval by PSC
Abstract
This application note provides basic information on the (program-) stack consumption of
Vector's CANbedded communication components.

Table of Contents

1.0
Overview ..........................................................................................................................................................1
1.1
Definition “The Stack”....................................................................................................................................1
1.2
Embedded System Stack Handling...............................................................................................................2
1.3
Stack-Usage Approach in CANbedded.........................................................................................................3
1.3.1
Example ......................................................................................................................................................3
1.3.2
Configuration Aspects.................................................................................................................................5
1.4
Calculating and Measuring Stack Need........................................................................................................5
2.0
Summary..........................................................................................................................................................5
3.0
Contacts...........................................................................................................................................................6

1.0 Overview
This application note provides basic information on the (program-) stack consumption of Vector’s CANbedded
communication components.
1.1  Definition “The Stack”
In computer science, a call stack is a special stack, which stores information about the active subroutines of a
computer program. (The active subroutines are those, which have been called but have not yet completed
execution by returning.) This kind of stack is also known as a program stack, execution stack, control stack,
function stack or run-time stack and is often abbreviated to just "the stack".

The actual details of the stack in a programming language depend upon the compiler, operating system, and the
available instruction set.

As noted above, the primary purpose of the stack is:
•  Storing the return address – When a subroutine is called, the location of the instruction to return to
needs to be saved somewhere.

A stack may serve additional functions, depending on the language, operating system and machine environment.
Among them can be:
•  Local data storage – A subroutine frequently needs memory space for storing the values of local
variables, the variables that are known only within the active subroutine and do not retain values after it
returns.
1
Copyright © 2007 - Vector Informatik GmbH
Contact Information: www.vector-informatik.com or ++49-711-80 670-0

CANbedded Program-Stack usage

•  Parameter passing – Subroutines often require that values for parameters must be supplied to them by
the code which calls them and it is not uncommon that space for these parameters may be laid out in the
stack. Generally if there are only a few small parameters, processor registers will be used to pass the
values. The stack works well as a place for these parameters, especially since each call to a subroutine,
which will have differing values for parameters, will be given separate space on the stack for those values.
•  Other return state – Besides the return address, in some environments there may be other machine or
software states that need to be restored when a subroutine returns. This might include things like
processor registers, privilege level, exception handling information, arithmetic modes and so on. If needed,
this may be stored on the stack just as the return address is.

The typical stack is used for the return address, locals, and parameters (known as a call frame). In some
environments there may be more or fewer functions assigned to the stack.
A stack is composed of stack frames (sometimes called activation records). Each stack frame corresponds to a call
to a subroutine, which has not yet terminated with a return. For example, if a subroutine named DrawLine is
currently running, having just been called by a subroutine DrawSquare, the top part of the stack might be laid out
like this:

The stack frame at the top of the stack is for the currently executing routine. In the most common approach the
stack frame includes space for the local variables of the routine, the return address back to the routine's caller, and
the parameter values passed into the routine. The memory locations within a frame are often accessed via a
register called the stack pointer, which also serves to indicate the current top of the stack. Alternatively, memory
within the frame may be accessed via a separate register, often termed the frame pointer, which typically points to
some fixed point in the frame structure, such as the location for the return address.
Stack frames are not all of the same size. Different subroutines have differing numbers of parameters, so that part
of the stack frame will be different for different subroutines, although usually fixed across all activations of a
particular subroutine. Similarly, the amount of space needed for local variables will be different for different
subroutines.
[Source: Wikipedia]

1.2  Embedded System Stack Handling
The bandwidth of embedded system architectures and also the used µC (and compilers) results in a huge variety
of stack handling approaches.
The simplest approach is often valid, when no operating system (OS) is used. In such a case the stack is simply a

2
Application Note AN-ISC-8-1056

CANbedded Program-Stack usage

reserved RAM area used by the whole system.
If an OSEK/OS or AUTOSAR OS is used, the stack handling depends on the available features in the OS and the
underlying µC. Each OS task has usually its own stack but can share this stack if some preconditions are kept with
other tasks. Providing one or more own stacks for interrupts can reduce the stack need of the OS tasks, too.
The stack need of an embedded system depends also on the specific handling for interrupts:
•  Storing of CPU registers on the stack or simply switching to a different stack bank
•  Supporting/using nested interrupts; i.e. interrupts can cause multiple store actions to the stack
•  Configuring own stack(s) for interrupts or using the stack of the currently running OS task (or other
interrupt)
Please note that for most implementations the stack pointer starts at a high address and grows to lower addresses.
1.3  Stack-Usage Approach in CANbedded
The CANbedded architecture is optimized for so-called deeply embedded systems with limited RAM and runtime in
real-time systems. As a result of this, the architecture is gained to be a good compromise between
•  ROM usage (multiple implementation of same behavior vs. in-lining or calling functions)
•  RAM usage (static parameters vs. local parameters on the stack; calling a function vs. implementing
something short twice, …)
•  Runtime consumption (calling a function needs more time than local handling)

A CANbedded function shall therefore
•  have only few arguments (none, 1 or 2, very very rarely more than 2 parameters)
•  be implemented in a way that local data stored on the stack is minimized
•  call no other functions unless it is necessary due to layered architecture

Most CANbedded API functions are implemented in a way that only flags are set which are evaluated on a cyclic
function to prevent too deep function call trees (and with this an increased stack need).
An additional task of the CANbedded communication components is the separation of the interrupt driven
hardware handling and the task-level view of the application. To be able to react on communication events
correctly, parts of the handler implementation are executed on interrupt level and parts are executed on task level.
Which stack and how much stacks are used for the task and the interrupt context depends on the underlying
system (see chapter 1.2 for details).
1.3.1 Example
A typical example for such a CANbedded implementation is a transport protocol, where the reaction on incoming
events has to be fast whereas the timeout and state handling can be slower. The implementation will therefore be
split in a function called within the CAN RX interrupt for fast actions and a cyclic called function for the slower ones.
The same is true for the next upper layer, the diagnostic layer. See Figure 2 for details how the diagnostic layer
handles the separation of RX event notification in CAN ISR context and further handling on task context.
As a result, the call tree of the RX event handling in ISR context stops latest on diagnostic layer level. All further
handling (including application calls) is processed a few milliseconds later from task level with only very few
function calls on the stack.

3
Application Note AN-ISC-8-1056

CANbedded Program-Stack usage

osCAN
Application
Diagnostics
Layer
Universal
Measure-
Interaction
Network
ment
Layer
Management
And
Communication
Calibration
Control
Transport Protocol
Protocol
Layer
CAN Driver
CAN Controller
Transce
Transc iver
CAN Bus

Figure 1 Example CANbedded Stack with CAN Driver, TP and Diagnostic Layer as the largest call-tree

Data
Da
Eve
Ev nt
ready
Cyclic
han
ha dler
flag
hand
ha
l
nd er
CAN
CAN
Transp
Trans ort
Diagnostics
osti

Application
Driver
Protocol
Protoc
Laye
Lay r
Further handling
RX o
RX f TP frame
am
Optional call to application
unknown to std. SW
Copy RX data
dat
Check RX
data ready
Further handling
RX o
RX f last TP frame
am
Optional call to application
unknown to std. SW
Copy RX data
dat
Indicate RX data ready
Check RX
data ready
PreHandler
Further handling
unknown to std. SW
MainHandler
Further handling
unknown to std. SW
ISR/Event context
Task context

Figure 2 Example call-tree for diagnostic data reception

4
Application Note AN-ISC-8-1056

CANbedded Program-Stack usage

1.3.2 Configuration
Aspects
The configurations of the CANbedded components have a large impact on the stack needs. There is a customer
specific, static setup of CANbedded components which interact together to fulfill the OEM requirements. I.e. the
CAN driver always informs e.g. the transport layer if a specific CAN frame is received and the transport layer
informs the diagnostic layer if the full message is received. This call sequence is preconfigured by Vector,
nevertheless, the software supports multiple points (callbacks) where customer specific hooks can be included.
This customer hooks have additional influence to the stack needs.
Another very important configuration parameter is the decision if the RX/TX handling shall be processed in
interrupt or on task context. If it is processed on task context, the stack need can be calculated easier than when
the handling is performed with interrupts.
In an ECU with one CAN bus, an interaction layer (IL), a network management (NM), a transport layer (TP) and a
diagnostic component, the RX path of incoming diagnostic CAN messages has usually the largest call tree form
communication point of view and therefore the highest stack need.
1.4 Calculating and Measuring Stack Need
Exactly calculating the stack needs is a difficult and error-prone task. Therefore the stack size is often estimated
based on the environmental conditions described in chapter 1.2 and a safety value of 10% to 20%, sometimes
100%, is added to the result.
If an operating system is used, this system usually provides means to measure stack usage and test stack
consistency. OSEK/OS and AUTOSAR OS for instance provides such means to check the stack with each OS
action and also to initialize the stack with patterns so the worst case usage for a given scenario can be found.
When using such a method, it is important to analyze upfront the worst case call trees and make sure they have
happened during test execution, too. This implies also “special” scenarios like “ECU in diagnostics”, “ECU with high
I/O interrupt load”, occurrence of OSEK category 1 and 2 interrupts at the same time, …
2.0 Summary
As a result of all this effects, no detailed figure for the concrete stack usage of the CANbedded communication
components can be given upfront of the real usage in an ECU project.
Vector offers different levels of support to customers, starting from telephone hotline for the more simple questions,
integrating the CANbedded communication components and other software up to analyzing your ECU setup as a
separate project work.

Note:
Please be aware that due to all the points mentioned in this application note Vector can not finally
list the stack needs of the CANbedded communication components in your project. The concrete
layout and dimension of the stack(s) in an ECU project is the task of the system integrator.

5
Application Note AN-ISC-8-1056

CANbedded Program-Stack usage

3.0 Contacts

Vector Informatik GmbH
Vector CANtech, Inc.
VecScan AB
Ingersheimer Straße 24
39500 Orchard Hill Pl., Ste 550
Lindholmspiren 5
70499 Stuttgart
Novi, MI 48375
402 78 Göteborg
Germany
USA
Sweden
Tel.: +49 711-80670-0
Tel: +1-248-449-9290
Tel: +46 (0)31 764 76 00
Fax: +49 711-80670-111
Fax: +1-248-449-9704
Fax: +46 (0)31 764 76 19
Email: info@vector-informatik.de
Email: info@vector-cantech.com
Email: info@vecscan.com

Vector France SAS
Vector Japan Co. Ltd.

168 Boulevard Camélinat
Seafort Square Center Bld. 18F
92240 Malakoff
2-3-12, Higashi-shinagawa,
France
Shinagawa-ku
Tel: +33 (0)1 42 31 40 00
J-140-0002 Tokyo
Fax: +33 (0)1 42 31 40 09
Tel.: +81 3 5769 6970
Email: information@vector-france.fr
Fax: +81 3 5769 6975

Email: info@vector-japan.co.jp

6
Application Note AN-ISC-8-1056

16 - AN-ISC-8-1074_Possible_Loss_Of_Wakeup_Message

Possible Loss Of Wakeup Message

17 - AN-ISC-8-1074_Possible_Loss_Of_Wakeup_Message_ind

Page 1
Page 2
Page 3
Page 4
Page 5

18 - AN-ISC-8-1074_Possible_Loss_Of_Wakeup_Messages

Possible Loss Of Wakeup Message
Version 1.0
2008-02-26
Application Note AN-ISC-8-1074

Author(s) Ralf
Fritz
Restrictions
Customer confidential - GM only
Abstract
This application note describes the possibility of loosing a wake-up request in a GMLAN
Single Wire environment and the possibility to minimize the possibility of occurrence. For
GM customer only.

Table of Contents

1.0
Overview ..........................................................................................................................................................1
2.0
Initialization Of CAN controller.........................................................................................................................2
2.1
During Startup ...............................................................................................................................................2
2.2
Switching Baud Rate .....................................................................................................................................2
2.3
Bus-Off Event ................................................................................................................................................2
2.4
Before Sleep Mode........................................................................................................................................2
3.0
Switching Transceiver to Sleep mode .............................................................................................................3
3.1
Check For Messages ....................................................................................................................................3
3.2
Use Transceiver Wake Pin............................................................................................................................4
4.0
Switching CAN cell into sleep mode ................................................................................................................4
5.0
Polling versus Interrupt ....................................................................................................................................5
6.0
Additional Resources .......................................................................................................................................5
7.0
Contacts...........................................................................................................................................................5

1.0 Overview
GMLAN uses special messages, so called High Voltage Wake-Up Messages (HVWU), to wake-up sleeping
modules on the Single Wire CAN bus. Under certain conditions it is possible that these messages are discarded
and do not cause a wake-up of the ECU like expected. This document describes these possible situations and
methods of reducing the time period where a HVWU message can be lost.

Note:
This document applies to the Single-Wire CAN bus only, because of its special physical
implementation. The wake-up behavior on a non Single-Wire CAN bus will differ since every
receive message will cause a CAN cell wake-up if the CAN cell supports sleep wake-up.

Note:
The occurrence of this behavior depends on the hardware platform, the compiler, hardware layout
and many more parameters. Because of this, this application note cannot specify specific time
durations.

Note:
Any code samples are only examples of implementation proposals. Because these
functions are meant for demonstration purposes only, Vector’s liability shall be expressly
excluded in cases of ordinary negligence to the extent admissible by law or statute.
1
Copyright © 2008 - Vector CANtech, Inc.
Contact Information: www.vector-informatik.com or ++49-711-80 670-0

Possible Loss Of Wakeup Message

2.0  Initialization Of CAN controller
The GMLAN handler will initialize the CAN controller at different times during runtime. The CAN controller is
initialized in the following situations:
•  During startup of the handler
•  Switching baud-rate during flash programming
•  After a Bus-Off event
•  Before the handler tries to enter the sleep mode
•  In case the High Voltage Wake-Up message cannot be sent onto CAN bus

If the CAN cell is initialized, all currently received and not handled receive-messages will be discarded. This means
that also pending HVWU messages will be discarded and can cause the module not to switch back to
Communication Enable or Communication Active state as expected.
The chapters below include a more detailed description of these situations.
2.1 During
Startup
Vectors GMLAN handler can be configured to initialize the CAN controller during the call of IlInitPowerOn().
During this time it is not likely to lose any HVWU message, because this function is only called if the system
performs a cold start. Please see [1] and [2] for further information when this function needs to be called by the
application.
After the call of IlInitPowerOn(), the handler will enter at least the Communication Enable state for 8 seconds,
this means bus activity can be detected and a lost HVWU frame will not cause the module not to participate in the
CAN communication.
2.2 Switching
Baud
Rate
To be able to switch the current baud rate to a higher or lower one, the CAN controller needs to be re-initialized
with the different baud rate settings. During this period, the handler is in the Normal Communication Halted state.
This means that the module is already awake during this time and will stay awake for at least 4 more seconds. This
means that if a HVWU frame is lost at this point in time, the handler will still be able to participate in an ongoing
CAN communication.
2.3 Bus-Off
Event
To start the CAN cell bus-off recovery sequence and to remove any pending transmit request from the CAN
controller, the GMLAN handler is calling two CAN Driver interface functions. These functions are
CanResetBusOffStart() and CanResetBusOffEnd(). One of these functions is usually mapped to a function
which will re-initialize the CAN cell. In such situations, the handler shall ignore any receive messages, which also
includes HVWU messages.
Note:
The implementation of the functions CanResetBusOffStart() and CanResetBusOffEnd()
are depending on the hardware. Please check the related hardware manual [3] for more
information.
2.4  Before Sleep Mode
Vectors GMLAN handler will call CanResetBusSleep() before the CAN controller is put into sleep mode to
remove any pending transmit request from the CAN hardware.

2
Application Note AN-ISC-8-1074

Possible Loss Of Wakeup Message

Note:
The implementation of the function CanResetBusSleep() is depending on the hardware. Please
check the related hardware manual [3] for more information.
This function is usually mapped to a function which will initialize the CAN controller. The call of this function
happens when the remainder of the Communication Enable timer reaches a value of 100 ms + 2 times the task
cycle of the network management task (IlNwmTask()) and the application accepts the sleep request
(ApplNwmSleepConfirmation returns NmSleepOk).
Note:
100 ms is the default provided by the generation tool. This value can be calibrated later to a
different value. Please check your usage.
If now the delay between the related I-VNMF to the discarded HVWU message is longer then the time set-up, the
transceivers will be switched into sleep mode before the I-VNMF is sent to the CAN bus. This will prevent the CAN
controller from receiving the message and the system will stay in sleep mode. This behavior cannot be changed by
a software or hardware change.
3.0 Switching Transceiver to Sleep mode
On a Single Wire bus it is quite normal, that a single ECU will enter the CAN sleep mode and other modules
continue to communicate on the same physical CAN bus. To be able to do this, the transceivers of these modules
are switched into sleep mode before the CAN cell is put into sleep mode. This will prevent any normal message
communication from being passed to the controller and allows it to enter the CAN sleep mode. Vectors GMLAN
handler does not check, if there is an ongoing CAN message reception while it requests the application to switch
the transceiver into sleep mode by calling the function ApplTrcvrSleepMode(). If a normal receive message is
interrupted, this causes no functional issue, since the module already decided that normal message reception must
be ignored.
If during this time a HVWU message is received, the message is most likely lost. This is because only parts of the
physical CAN message are received by the CAN controller. The transceiver will act like a filter after it is put into
sleep mode and will not pass all bits of the message to the CAN controller (Please check your transceiver manual
for the exact behavior of your transceiver). Because the message is not received by the CAN cell, the system will
not switch back into the Communication Enable or Active state as expected.
Depending on the used hardware there are maybe some possibilities to minimize the window in which this issue
can happen. Below two current know methods.
3.1 Check For Messages
The goal of this implementation is to minimize the possibility that the HVWU message is cut off by switching the
transceiver into sleep mode. This requires the CAN hardware to be able to provide the information that there is
currently ongoing message reception. Vectors GMLAN handler does not provide this information!
Note:
Not all hardware platforms provide the needed hardware feature for this implementation. Please
check your device manual for further information.
The idea is to check for CAN bus-idle before the transceiver is switched into sleep mode. This would reduce the
window of losing a HVWU message from the message length of this message to the time it takes to switch the
transceiver and CAN into sleep mode after an idle CAN bus was detected.
The flow chart below shows a possible implementation strategy.

3
Application Note AN-ISC-8-1074

Possible Loss Of Wakeup Message

Start
No
Bus Idle?
Yes
Put TRV
To sleep
End

Note:
Waiting for bus idle can take a longer period of time. Please make sure that the loop has a timeout
criteria which will allow the software to continue in case there will be no bus-idle detected after a
certain time!
The code which implements this flow chart needs to be placed into the application callback function
ApplTrcvrSleepMode() of the Single Wire CAN. This function is called by Vectors GMLAN handler to switch
the transceiver into sleep mode. After this call, the handler will try and put the CAN cell into sleep mode.
3.2  Use Transceiver Wake Pin
If the hardware allows, it is preferable to use the wake-up notification pin of the transceiver. For most of the
transceivers they provide a dedicated hardware output, which is set high, if the transceiver detects a wakeup frame
on the CAN bus. If the controller detects that this pin was set, the software should call the GMLAN handler API
function NmCanWakeUp() to notify the GMLAN handler about this event.
Note:
Not all hardware provides the needed feature for this implementation. Please check your device /
transceiver manual for further information.

4.0  Switching CAN cell into sleep mode
After the transceiver is put into sleep mode the CAN cell will be put into sleep mode as well by the GMLAN
handler. Depending on the hardware and the related software implementation of the GMLAN handler there is a
chance that a pending HVWU message will be lost.
This can happen if the reception of a HVWU message is finished during or delayed until the time when the GMLAN
handler switches the transceiver and the CAN cell into sleep mode (The GMLAN handler will disable interrupts
while it is putting the CAN bus into sleep mode). In such a situation the handler will call the CAN Driver API
function CanSleep() while a not handled receive message is pending in the CAN cell. Depending on the used
CAN cell and the implementation of the handler function CanSleep(), this message reception is discarded or

4
Application Note AN-ISC-8-1074

Possible Loss Of Wakeup Message

suppressed and will not lead to a wake-up. Please check the related CAN Driver manual [3] for more information
about the behavior of CanSleep().
5.0 Polling versus Interrupt
The GMLAN handler allows receiving message either on interrupt or polling basis. It is more likely, that a HVWU
message will be lost, if the handler is configured to receive this message in polling mode. This is because usually a
receive notification interrupt can happen right after the reception of the physical message and is not delayed until
the next call of the receive polling task. Interrupt handling of the HVWU frame does not guarantee that the
message will be received and processed all the time, since the GMLAN handler and the application potentially
disable the CAN interrupts during certain periods of times for example to guarantee data consistency which will
also cause a delay of the receive message handling.

6.0 Additional Resources
[1] GMLAN Technical Reference documentation.
[2] IL Technical Reference documentation.
[3] CAN Driver Technical Reference documentation of the used hardware platform.

7.0 Contacts

Vector Informatik GmbH
Vector CANtech, Inc.
VecScan AB
Ingersheimer Straße 24
39500 Orchard Hill Pl., Ste 550
Lindholmspiren 5
70499 Stuttgart
Novi, MI 48375
402 78 Göteborg
Germany
USA
Sweden
Tel.: +49 711-80670-0
Tel: +1-248-449-9290
Tel: +46 (0)31 764 76 00
Fax: +49 711-80670-111
Fax: +1-248-449-9704
Fax: +46 (0)31 764 76 19
Email: info@vector-informatik.de
Email: info@vector-cantech.com
Email: info@vecscan.com

Vector France SAS
Vector Japan Co. Ltd.
Vector Korea IT Inc.
168 Boulevard Camélinat
Seafort Square Center Bld. 18F
Daerung Post Tower III, 508
92240 Malakoff
2-3-12, Higashi-shinagawa,
Guro-gu, Guro-dong, 182-4
France
Shinagawa-ku
Seoul, 152-790
Tel: +33 (0)1 42 31 40 00
J-140-0002 Tokyo
Republic of Korea
Fax: +33 (0)1 42 31 40 09
Tel.: +81 3 5769 6970
Tel.: +82-2-2028-0600
Email: information@vector-france.fr
Fax: +81 3 5769 6975
Fax: +82-2-2028-0604

Email: info@vector-japan.co.jp
Email: info@vector-korea.com

5
Application Note AN-ISC-8-1074

19 - CANdelaStudio_Gm_contact

Microsoft Word - CANdelaStudio_GM_contact.doc

20 - CANdelaStudio_Gm_contact_ind

Page 1

21 - CANdelaStudio_Gm_contacts

Vector Informatik GmbH
Ingersheimer Str. 24
D-70499 Stuttgart
www.vector.com

Vector Informatik GmbH - Ingersheimer Str. 24 – D-70499 Stuttgart



CANdelaStudio Option General Motors (GM)

Um neue Dokumente mit CANdelaStudio erzeugen zu können, wird eine Dokumentvorlage
benötigt. Eine Dokumentvorlage enthält die formale Beschreibung des verwendeten
Diagnoseprotokolls und ist daher herstellerspezifisch. Die Weiterentwicklung und
Pflege der Dokumentvorlagen liegt in der Verantwortung des Fahrzeugherstellers. Aus
diesem Grund werden Dokumentvorlagen nicht von Vector Informatik bereitgestellt,
sondern vom jeweiligen Fahrzeughersteller.
To create new documents with CANdelaStudio, a document template is needed. A document
template contains the formal specification of the used diagnostic protocol, thus it is
manufacturer specific. The development and maintenance of the document templates is in
charge of the car manufacturer. On this account the document templates are not
provided by Vector Informatik, but by the respective car manufacturer.

Die Vorlagen für die Option General Motors (GM) sind erhältlich bei:

The templates for the option General Motors (GM) are available from:

General Motors Corporation
Mr. Michael Sowa
Warren Technical Center Campus
30003 Van Dyke P.O. Box 9060
Warren, MI  48090-9060
Phone:  +1 586 492 5501
Email:  michael.a.sowa@gm.com

Bei Rückfragen wenden Sie sich bitte an:

For any questions please contact:

support@vector.com
Phone: +49 (0)711/80670-200
Phone: +49 (0)711/80670-0
Landesbank BW 2 224 585 (BLZ 600 501 01)
Managing Directors:
Fax: +49 (0)711/80670-111
Deutsche Bank Stuttgart 1 614 080 (BLZ 600 700 70)
Dr. Thomas Beck, Eberhard Hinderer,
www.vector.com
Handelsregister Stuttgart HRB 17317
Martin Litschel, Dr. Helmut Schelling

22 - DeliveryDescription_CBD1400346

Delivery Description CBD1400346

Delivery Information

Customer Information

Package Information:	Nexteer Automotive Corporation Package: GMLAN 3.1 Micro: R7F701308 Compiler: GHS 2013.5.5
License Number:	CBD1400346
License Expiry Date:	License does not expire
OEM:	Gm
SLP:	GMLAN 3.1
Controller:	Rh850
CAN Cell:	Rscan
Compiler:	GreenHills
Ordered Derivative:	R7F701308
Customer Contacts:	Lucas Wendling Lucas.Wendling@nexteer.com Lonnie Newton lonnie.newton@nexteer.com Contact address for Vector for all topics concerning this license. This includes questions and issue reports. Please inform Vector if this contact changes.
Vector Contact:	GMSupport GMSupport@us.vector.com Contact address at Vector for all questions concerning this delivery.
Non-Disclosure:	A non-disclosure agreement related to this license exists.

Delivery Information

Delivery ID:	01.01.24.01.40.03.46.00.00.00 This is the unique identification number of this delivery. Please always have this number and above license information ready when contacting Vector customer support.
SIP Version:	01.01.24
Delivery Number:	00
Release Type:	Pre release (complete functionality, partly tested, reduced process)
Delivery Type:	Initial delivery (based on explicit purchase order)
Delivery Reason:	5015512
Vector Order Confirmation Number:	5015512
Tested Derivative:	R7F701352

Version Information

Component Version Information

Project	Component	Version
CBD_Gm_SLP9	Preconfig	1.00.00
Common_Vdef	Implementation	3.43.00
Cp_Xcp	GenTool_Geny	2.20.03
Cp_Xcp	Implementation	1.28.02
Cp_XcpOnCan	GenTool_Geny	1.08.02
Cp_XcpOnCan	Implementation	1.07.03
Diag_CanDesc__coreBase	GenTool_Geny_CANdesc	6.15.00
Diag_CanDesc__coreBase	Implementation	6.15.03
Diag_CanDescGgdaExt_Gm	GenTool_Geny	1.06.01
Diag_CanDescGgdaExt_Gm	Implementation	2.06.05
Diag_CddPersistors	Implementation	1.06.00
Diag_DataCddt_Gm	DiagDescription	1.00.01
Diag_DescDataModel	Implementation	1.26.01
Diag_Geny_coreBase	GenTool_Geny	6.21.00
DrvCan__base	GenTool_Geny	3.22.00
DrvCan__baseExt_Gm	GenTool_Geny	1.00.02
DrvCan__baseHll	GenTool_Geny	3.06.01
DrvCan__baseRi14	GenTool_Geny	2.09.01
DrvCan__baseRi14Hll	GenTool_Geny	2.05.03
DrvCan__baseRi15	GenTool_Geny	1.05.00
DrvCan__baseRi15Hll	GenTool_Geny	1.01.03
DrvCan_Rh850RscanHll	Implementation	3.11.00
DrvCan_Sh2RscanHll	GenTool_Geny	1.07.00
GenTool_GenyDriverBase	GenTool_Geny	2.08.04
GenTool_GenyFrameworkCsyntax	GenTool_Geny	2.10.02
GenTool_GenyFrameworkGenXml	GenTool_Geny	1.13.00
GenTool_GenyGraphicsLibCan	GenTool_Geny	1.03.00
GenTool_GenyGuiChannelCfg	GenTool_Geny	1.05.01
GenTool_GenyHtmlConfigDocumentor	Implementation	1.00.01
GenTool_GenyObjectHierarchyCan	GenTool_Geny	1.21.01
GenTool_GenyObjectModel	GenTool_Geny	2.12.00
GenTool_GenyPluginConfigDocumentor	GenTool_Geny	2.02.03
GenTool_GenyVcfgNameDecorator	Description	1.01.01
GenTool_GenyVcfgNameDecorator	GenTool_Geny	2.25.00
GenTool_TemplateUpdate	Implementation	1.00.01
GenTool_XA2lParser	Implementation	1.60.04
GenTool_XChecksumcrc	GenTool_Geny	1.00.00
Hw__baseCpuCan	GenTool_Geny	2.26.01
Hw_Rh850Cpu	GenTool_Geny	1.06.00
Hw_Sh2RscanCpuCan	GenTool_Geny	2.08.00
Il_Vector	GenTool_Geny	1.16.02
Il_Vector_Gm	GenTool_Geny	1.01.01
Il_Vector_Gm	Implementation	1.01.01
Nm_Gmlan_Gm	GenTool_Geny	1.02.02
Nm_Gmlan_Gm	Implementation	4.03.02
Tp_Iso15765	GenTool_Geny	2.34.00
Tp_Iso15765	Implementation	3.08.01
VStdLib__base	GenTool_Geny	1.02.00
VStdLib_Rh850	Implementation	1.03.00

Build Information

Build Environment - Options & Versions

Compiler
Version:	This Green Hills compiler uses the Edison Design Group C/C++ Front End, version 3.10.1 (Oct 4 2013 13:57:11) Copyright 1988-2007 Edison Design Group, Inc. C-RH850 2013.5.5 DEVELOPMENT VERSION: Copyright (C) 1983-2013 Green Hills Software. All Rights Reversed.
AdditionalOptions:	-DBRS_TIMEBASE_CLOCK=160 -DEVA_BOARD_VEBN00937 -DMAIN_OSC_CLK=16 -DBRS_CPU_FAMILY=P1X -DDEMO_DISABLE_BOOTLOADER -list=lst/.lst -object_dir=obj -stderr=err\.err -cpu=rh850g3m -c -needprototype -Wundef --no_commons -G -dual_debug -noobj -pragma_asm_inline -inline_prologue --long_long -fsoft -registermode=32
Linker
Version:	This Green Hills compiler uses the Edison Design Group C/C++ Front End, version 3.10.1 (Oct 4 2013 13:57:11) Copyright 1988-2007 Edison Design Group, Inc. C-RH850 2013.5.5 DEVELOPMENT VERSION: Copyright (C) 1983-2013 Green Hills Software. All Rights Reversed.
AdditionalOptions:	-o .elf -map=.map -cpu=rh850g3m --preprocess_linker_directive -e __usr_init Demo.ld -Manx -G -dual_debug
Librarian
Version:	This Green Hills compiler uses the Edison Design Group C/C++ Front End, version 3.10.1 (Oct 4 2013 13:57:11) Copyright 1988-2007 Edison Design Group, Inc. C-RH850 2013.5.5 DEVELOPMENT VERSION: Copyright (C) 1983-2013 Green Hills Software. All Rights Reversed.
Flags:	:archiver.args=-c -archive -o makesupport.xml

23 - IssueReport_CBD1400346

ElectricPowerSteering_RH850_GM_T1XX_website/content/en/docs/GM_000A_GMLAN3.1MchRH850_Impl/doc/IssueReport_CBD1400346

24 - IssueReport_CBD1400346_ind

Outline
Page 1
Page 2
Page 3
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13
Page 14
Page 15
Page 16
Page 17
Page 18
Page 19
Page 20
Page 21
Page 22
Page 23
Page 24
Page 25
Page 26
Page 27
Page 28
Page 29
Page 30
Page 31
Page 32
Page 33
Page 34
Page 35
Page 36
Page 37
Page 38
Page 39
Page 40
Page 41
Page 42

25 - IssueReport_CBD1400346s

Issue Report
License Number
Customer
CBD1400346
Nexteer Automotive Corporation
Package: GMLAN 3.1
Micro: R7F701308
Compiler: GHS 2013.5.5
Maintenance Expiry Date
2014-08-01
SIP Delivery Date
SIP Version
2014-07-03
01.01.24
SLP
Delivery Number
GMLAN 3.1
D00
Report Creation Date
2014-07-11
Contact
In case of questions or the need for an update of the basic software delivery, please contact
GMSupport@us.vector.com or your Vector contact person.
Table of Contents
1.
Introduction
1.1 Resolving Issues
1.2 Issue Classification
2.
New Issues
2.1 Runtime Issues without Workaround: 2
2.2 Runtime Issues with Workaround: 6
2.3 Apparent Issues: 15
2.4 Compiler Warnings: 10
3.
New Issues for Information: 0
4.
Report Legend
5.
Quality Management Contact
1

Issue Report
1. Introduction
1.1 Resolving Issues
Reported issues are not necessarily fixed automatically by the next update delivery. If some of the
reported issues shall be fixed, please contact Vector to establish an agreement about issues that
shall be fixed in upcoming deliveries. Please note that Vector may fix additional issues without
explicit request.
1.2 Issue Classification
This Issue Report provides issues that have been detected since the last report. The issues have
been classified to facilitate the assessment of their impact:
The chapter 'New Issues' lists issues that have been detected since the last report and which could
not be excluded based on the use-case defined in the questionnaire. The issues are classified as
follows:
•
Runtime Issues without Workaround: Runtime issues without a workaround require an
update of the basic software delivery in case the issue affects the ECU overall functionality.
The effect of an issue to the ECU functionality has to be analyzed by the customer as the basic
software usage and its configuration is not known by Vector. The risk of change has also to be
taken into account.
•
Runtime Issues with Workaround: It is not recommended to update a delivery due to a
runtime issue with a documented workaround. The effect of an issue to the ECU functionality
has to be analyzed by the customer as the basic software usage and its configuration is not
known by Vector. The risk of change has also to be taken into account.
•
Compiler Warnings: As a service we report the known compiler warnings. The occurrence of
a compiler warning may depend on the used configuration and compiler settings.
•
Apparent Issues: Apparent issues are detected immediately when using the basic software.
If an issue does not show up while working with the basic software the ECU project is not
affected by the issue. Apparent issues may or may not have workarounds.
The chapter 'New Issues for Information' lists issues that are not relevant for the use case that
has been documented in the questionnaire provided to Vector. The issues may, however, be
relevant for other use cases. Additionally, issues that have been accepted or are tolerated by the
OEM (as defined in the questionnaire) are reported here.
2

Issue Report
2. New Issues
3

Issue Report
2.1 Runtime Issues without Workaround
The lists contain issues that have been detected since the last report and which could not be
excluded based on the use-cases defined in the questionnaire (see chapter ‘New Issues for
Information’).
4

Issue Report
ESCAN00074189
Service 0x2C: A PID declined by the application via
pre-handler is skipped for the DPID definition
Component@Subcomponent:
Diag_CanDesc__coreBase@Implementation
First affected version:
6.06.00
Fixed in versions:

Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
During the definition of a DPID with service 0x2C, when the application declines a PID in its pre-
handler (by setting a NRC) a positive response is sent instead of a negative response with NRC
0x31.
When does this happen:
-------------------------------------------------------------------
During runtime.
In which configuration does this happen:
-------------------------------------------------------------------
Protocol == KWP
AND
Service 0x2C is used
AND
Pre-Handler for PIDs are used

Resolution Description:
Workaround:
-------------------------------------------------------------------
No workaround available.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
5

Issue Report
ESCAN00076278
StateOn flag return value may be incorrect
Component@Subcomponent:
Il_Vector_Gm@Implementation
First affected version:
1.00.00
Fixed in versions:

Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The value reported by the StateOn flag (IlGet<signal>RxStateOn) may be incorrect.
- It may return true (non-zero) even though no relevant VN is active
When does this happen:
-------------------------------------------------------------------
The issue is observed at runtime, but it is caused by an incorrectly generated macro. If the macro
is generated incorrectly, the runtime behavior is consistent and reproducible (it occurs each and
every time).
In which configuration does this happen:
-------------------------------------------------------------------
In MultiChannel Configurations with State On Flags.

Resolution Description:
Workaround:
-------------------------------------------------------------------
No workaround available.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
2.2 Runtime Issues with Workaround
It is not recommended to update a delivery due to a runtime issue with a documented
workaround. The effect of an issue to the ECU functionality has to be analyzed by the customer as
the basic software usage and its configuration is not known by Vector. Thereby the risk of change
has also to be taken into account.
Index
ESCAN00027894
Memory is overwritten when initializing the CANBedded Stack
Nm_Gmlan_Gm@Implementation
ESCAN00045854
An incorrect timeout is issued for Flow Control and Consecutive Frame timing
supervision.
Tp_Iso15765@GenTool_Geny
ESCAN00067827
Rh850Rscan only: CAN communication shows undefined behavior
DrvCan__baseRi14Hll@GenTool_Geny
ESCAN00068912
Positive response to service $A5 03 not suppressed
Diag_CanDesc__coreBase@Implementation
ESCAN00073999
Signal handler names have wrong names after deletion of some signals of a
DID
Diag_CanDesc__coreBase@GenTool_Geny_CANdesc
ESCAN00076096
Periodic response of a DPID requested with service $AA return wrong data
Diag_CanDesc__coreBase@Implementation
6

Issue Report
ESCAN00027894
Memory is overwritten when initializing the
CANBedded Stack
Component@Subcomponent:
Nm_Gmlan_Gm@Implementation
First affected version:
3.30.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Memory is overwritten when initializing the CANBedded Stack.
When does this happen:
-------------------------------------------------------------------
The issue occurs always and immediately if CclInitPowerOn or IlInitPowerOn is called with the
configuration mentioned below.
In which configuration does this happen:
-------------------------------------------------------------------
Any configuration, where the number of Nm Channels differs from the number of Can Channels.
Hint: The generated define in kCanNumberOfChannels in can_cfg.h differs from
kNmNumberOfChannels generated to nm_cfg.h

Resolution Description:
Workaround:
-------------------------------------------------------------------
Do not call IlInitPowerOn in the application. Instead, call IlInit for each channel which uses the
Interaction Layer.
Note for GM ECUs: If the Interaction Layer is not used on the first channel in GENy (channel index
0), the application must additionally call CanInitPowerOn before IlInit.
Example:
The ECU has three CAN channels, where the Interaction Layer is only used on the first two.
IlInit(0); /* Initialize the IL on CAN channel 0 */
IlInit(1); /* Initialize the IL on CAN channel 1 */
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
7

Issue Report
ESCAN00045854
An incorrect timeout is issued for Flow Control and
Consecutive Frame timing supervision.
Component@Subcomponent:
Tp_Iso15765@GenTool_Geny
First affected version:
2.00.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
An incorrect timeout is issued for Flow Control (TX) and Consecutive Frame (RX) timing
supervision in case of large timeouts.
When does this happen:
-------------------------------------------------------------------
During runtime at transmission and/or reception of multi frames.
In which configuration does this happen:
-------------------------------------------------------------------
This can only appear if channel specific timing is activated (#if defined
TP_CHANNEL_SPECIFIC_TIMING)
AND
the configured timeout values are greater than 255 "ticks".
Please note that the number of "ticks" is calculated by dividing the configured timeout value by
the configured periodic cycle time of the TP.

Resolution Description:
Workaround:
-------------------------------------------------------------------
Use smaller timeouts or increase the call-cycle of the TP task functions.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
8

Issue Report
ESCAN00067827
Rh850Rscan only: CAN communication shows
undefined behavior
Component@Subcomponent:
DrvCan__baseRi14Hll@GenTool_Geny
First affected version:
1.00.00
Fixed in versions:
2.06.00
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
CAN communication shows undefined behavior
When does this happen:
-------------------------------------------------------------------
Anytime during runtime (init, rx, tx, ..)
In which configuration does this happen:
-------------------------------------------------------------------
Only for platform Rh850 with Rscan cell
All configurations that use any of the physical channels CAN5, CAN6 or CAN7

Resolution Description:
Workaround:
-------------------------------------------------------------------
Do not use physical channels CAN5, CAN6 or CAN7.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
9

Issue Report
ESCAN00068912
Positive response to service $A5 03 not suppressed
Component@Subcomponent:
Diag_CanDesc__coreBase@Implementation
First affected version:
6.12.01
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The positive response to service $A5 03 is not suppressed.
AND possibly
The following compiler warning occurs:
static void DescOemEnableProgrammingMode(DescMsgContext *pMsgContext)
^
"desc.c", Warning[Pe177]:
function "DescOemEnableProgrammingMode" was declared but never referenced
When does this happen:
-------------------------------------------------------------------
At runtime/compile time.
In which configuration does this happen:
-------------------------------------------------------------------
Configurations created in an older delivery affected by ESCAN00061312:
"Not possible to support negative responses while suppressing positive response for service $A5
03"
AND
The 'Reload all description files' button on the 'Diag_CanDesc_Kwp' page in GENy has NOT been
pressed at least once since moving from the older delivery.
Hint:
-------------------------------------------------------------------
This issue has been analyzed thoroughly and will not be fixed due to the following reasons:
a) In GENy there is no reasonable possibility to detect that an old configuration has been loaded
which would require a reload of the CDD.
b) The issue only occurs in a migration scenario with an old GENy configuration from a previous
delivery and a new delivery using that configuration.

Resolution Description:
Workaround:
-------------------------------------------------------------------
Press the 'Reload all description files' button on the 'Diag_CanDesc_Kwp' page in GENy and then
save the configuration. This process only needs to be done once.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
10

Issue Report
ESCAN00073999
Signal handler names have wrong names after
deletion of some signals of a DID
Component@Subcomponent:
Diag_CanDesc__coreBase@GenTool_Geny_CANdesc
First affected version:
6.00.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
After reloading a modified CDD-file, where signals of a DID were deleted, the signal handler the
DID have the names of the deleted signals.
When does this happen:
-------------------------------------------------------------------
After deleting some signals within a signal list of a DID in CANdela-Studio and reloading the
modified CDD-File
within GENy.
In which configuration does this happen:
-------------------------------------------------------------------
Signal handlers are used

Resolution Description:
Workaround:
-------------------------------------------------------------------
Empty the field "CANdela document name" and click "Reload all description files". The
configuration is now empty and no old names are stored. Afterwards import the CDD file again.
OR
For the affected signals change the Signal Handler Type to "Direct Access" and back to "Signal
Handler" again
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
11

Issue Report
ESCAN00076096
Periodic response of a DPID requested with service
$AA return wrong data
Component@Subcomponent:
Diag_CanDesc__coreBase@Implementation
First affected version:
4.02.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The periodic response for a DPID requested with service $AA contains wrong data
When does this happen:
-------------------------------------------------------------------
During runtime when the following situation occurs:
- One or more DPIDs are requested with service $AA in a specific rate
- For one DPID the data of it's source PIDs is currently read from the application
- During the read out process the reporting of all DPIDs is stopped
- Before the reading is finished the reporting of a DPID is requested again
In which configuration does this happen:
-------------------------------------------------------------------
Service $AA is used
AND
((Service $2C is used) OR (The source PIDs of a DPID are asynchronous))

Resolution Description:
Workaround:
-------------------------------------------------------------------
Use the High-Performance Mode in CANdesc. The utilization is described in the TechnicalReference
in the API description of "DescMayCallStateTaskAgain".
In case at least one source PID used for DPIDs is asynchronous (that means the application can't
always provide the data for the PID in the first function call to the application), change the
application so the data is always available on the first call of the application function (make the
PID synchronous).
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
12

Issue Report
2.3 Apparent Issues
Apparent issues are detected immediately when using the basic software. If an issue does not
show up while working with the basic software the ECU project is not affected by the issue.
Apparent issues may or may not have workarounds.
Index
ESCAN00049589
Compile error: direct signal access feature in CANdesc does not consider far
memory pointers
Diag_CanDesc__coreBase@Implementation
ESCAN00055957
appdesc.c missing line feed (LF) after carraige return (CR) on some lines
Diag_CanDesc__coreBase@Implementation
ESCAN00069542
Missing description that initially active VNs are no more activated upon power
on
Nm_Gmlan_Gm@Doc_TechRef
ESCAN00069732
Objects are not handled by interrupt or polling as configured in the Individual
Polling view
DrvCan__baseRi15@GenTool_Geny
ESCAN00069876
Incorrect Description for Calibration Attribute nmMaxApplShutDownDenyCnt
CBD_TechRef_GmlanCalibration@Doc_TechRef
ESCAN00070445
The P2 timings can be changed in the tool GUI but the new values have no
effect on CANdesc code generation
Diag_CanDesc__coreBase@GenTool_Geny_CANdesc
ESCAN00070517
Compiler error: missing constant kDescStateSessionDefault
Diag_CanDesc__coreBase@Implementation
ESCAN00071069
The description of service 0x12 is out-dated
Diag_CanDesc_Oem@Doc_TechRef_Kwp_Gm
ESCAN00071131
Wrong API name "DescApplSendSpontaneousResponse" in Technical Reference
Diag_CanDesc__coreBase@Doc_TechRef
ESCAN00073848
Tester present timeout occurs too early after a 0x28 request
Diag_CanDesc__coreBase@Implementation
ESCAN00074878
a2l error: The parameter SAMPLE_RATE is always 0
Cp_XcpOnCan@GenTool_Geny
ESCAN00075459
TpRxGetAssignedDestination returns wrong destination
Tp_Iso15765@Implementation
ESCAN00076138
GENy does not respond when importing CDD files
Diag_Geny_coreBase@GenTool_Geny
ESCAN00076840
Missing pre-conditions in the API description of
DescApplSendSpontaneousResponse
Diag_CanDesc__coreBase@Doc_TechRef
ESCAN00076879
Comment for Messages wrong - Generated code is not affected
DrvCan__base@GenTool_Geny
13

Issue Report
ESCAN00049589
Compile error: direct signal access feature in
CANdesc does not consider far memory pointers
Component@Subcomponent:
Diag_CanDesc__coreBase@Implementation
First affected version:
1.00.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Compile error for mismatching pointer type assignment.
When does this happen:
-------------------------------------------------------------------
At compile time.
In which configuration does this happen:
-------------------------------------------------------------------
- CANdesc
AND
- Direct signal access to RAM/ROM objects is used.
AND
- FAR memory
Some services such as the UDS ones 0x22/0x2A and 0x2E, can be processed on signal level. If
they are processed on signal level it is possible to choose "Direct Access" as Signal
Handler Type. In this case, CANdesc reads or writes the value of signal direct of/to a variable.
(The name of the variable is configured in the cdd file or GENy.) If this variable
is located in FAR memory a Compiler/Linker warning or error will occur.

Resolution Description:
Workaround:
-------------------------------------------------------------------
Avoid direct signal access to such objects and implement the main-handler within the application
code. (Choose "Signal Handler" for the Signal Handler Type and copy the
data that is located in the FAR memory in the application callback for this signal.)
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
14

Issue Report
ESCAN00055957
appdesc.c missing line feed (LF) after carraige
return (CR) on some lines
Component@Subcomponent:
Diag_CanDesc__coreBase@Implementation
First affected version:
5.07.26
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The appdesc.c file is missing the line feed (LF) character at the end of certain lines. It should
follow the carraige return (CR) character. This will cause compilers and debuggers to display the
incorrect line of source code. Additionally, some IDEs will complain that the line feed character is
missing.
When does this happen:
-------------------------------------------------------------------
At generation time.
In which configuration does this happen:
-------------------------------------------------------------------
All configurations.

Resolution Description:
Workaround:
-------------------------------------------------------------------
No workaround available.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
15

Issue Report
ESCAN00069542
Missing description that initially active VNs are no
more activated upon power on
Component@Subcomponent:
Nm_Gmlan_Gm@Doc_TechRef
First affected version:
2.01.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Chapters 3.3 "VN Concept" and 4.2 "Normal Operation" states that initially active VNs are
activated upon power on.
This is not correct. Since implementation version 4.02.00 initially active VNs are only activated
upon reception or transmission of a HLVW message.
When does this happen:
-------------------------------------------------------------------
When reading the technical reference.
In which configuration does this happen:
-------------------------------------------------------------------
In configurations with initially active VNs.

Resolution Description:
Workaround:
-------------------------------------------------------------------
No workaround available.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
16

Issue Report
ESCAN00069732
Objects are not handled by interrupt or polling as
configured in the Individual Polling view
Component@Subcomponent:
DrvCan__baseRi15@GenTool_Geny
First affected version:
1.00.00
Fixed in versions:
1.05.01
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Not all configured BasicCAN objects are visible in the Individual Polling view of GENy.
AND
Any objects are not handled by interrupt or polling as configured in the Individual Polling view.
When does this happen:
-------------------------------------------------------------------
Always after adding a further CAN channel while configuring and then anytime during runtime.
In which configuration does this happen:
-------------------------------------------------------------------
Individual Polling is enabled
AND
Multiple BasicCAN is enabled
AND
more than one BasicCAN object is configured
AND
more than one CAN channel is configured

Resolution Description:
API Extensions:
-------------------------------------------------------------------
No extension of the API.
API Changes:
-------------------------------------------------------------------
No modification of the API.
Module handling changes:
-------------------------------------------------------------------
No modification of the module handling.
For a detailed description of the API and the handling of the module refer to the Technical
Reference.
17

Issue Report
ESCAN00069876
Incorrect Description for Calibration Attribute
nmMaxApplShutDownDenyCnt
Component@Subcomponent:
CBD_TechRef_GmlanCalibration@Doc_TechRef
First affected version:
2.01.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The description in chapter 6.7 for calibration attribute nmMaxApplShutDownDenyCnt suggests
that this attribute can be modified in the GENy GUI, but the selection doesn't exist. The
documentation will be updated to remove this suggestion.
nmMaxApplShutDownDenyCnt can be modified in the generated handler calibrations file gmlcal.c.
When does this happen:
-------------------------------------------------------------------
Always
In which configuration does this happen:
-------------------------------------------------------------------
All

Resolution Description:
Workaround:
-------------------------------------------------------------------
No workaround available.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
18

Issue Report
ESCAN00070445
The P2 timings can be changed in the tool GUI but
the new values have no effect on CANdesc code
generation
Component@Subcomponent:
Diag_CanDesc__coreBase@GenTool_Geny_CANdesc
First affected version:
6.00.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The user is able to modify the default P2 timings in the GENtool GUI, but the new values are not
used during the CANdesc code generation. As a result the default P2 timings are only applicable.
When does this happen:
-------------------------------------------------------------------
At CANdesc configuration resp. code generation time.
In which configuration does this happen:
-------------------------------------------------------------------
Any KWP2000 configuration that shall use P2 timings other than the default ones.

Resolution Description:
Workaround:
-------------------------------------------------------------------
The P2/P2* timings are set automatically according to the GM specification to the values of 75 ms/
5000 ms. Usually, there should be no need to change the P2/P2* timings in GENy to a different
value.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
19

Issue Report
ESCAN00070517
Compiler error: missing constant
kDescStateSessionDefault
Component@Subcomponent:
Diag_CanDesc__coreBase@Implementation
First affected version:
1.00.05
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Compile error for missing constant kDescStateSessionDefault
When does this happen:
-------------------------------------------------------------------
At compile time.
In which configuration does this happen:
-------------------------------------------------------------------
CANdesc Full is used
AND
In the used CDD the name of the default session state is different from "Default".

Resolution Description:
Workaround:
-------------------------------------------------------------------
Rename the default session state in the CDD to "Default"
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
20

Issue Report
ESCAN00071069
The description of service 0x12 is out-dated
Component@Subcomponent:
Diag_CanDesc_Oem@Doc_TechRef_Kwp_Gm
First affected version:
3.00.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The description of service 0x12 doesn't consider the changes made with CANdesc 6.
Only one application callback on SID level is generated instead of two, for each sub-function.
When does this happen:
-------------------------------------------------------------------
Always.
In which configuration does this happen:
-------------------------------------------------------------------
Any.

Resolution Description:
Workaround:
-------------------------------------------------------------------
6.2 Service ReadFailureRecordData ($12)
CANdesc generates only one function callback (main-handler) for all service $12 requests and
does not offer any special support for this service. Therefore all dispatching and validation steps
(e.g. dispatching on sub-function level, check the request length or validate the PID parameter if
applicable), as well as the assembly of the response message (including the sub-function byte)
have to be performed by the application.
6.2.1 Service ReadFailureRecordIdentifiers ($12 $01)
Depending on the report type requested (PID or DPID) the application must place one of the
following values into the first data byte of the response message:
0x00 - for report by PID
0x01 - for report by DPID

Note
The ECU can support either reports by PID or DPID, but not both.

6.2.2 Service ReadFailureRecordParameters ($12 $02)
CANdesc does not automatically include the PID parameter in the response message for service
$12 $02. The application must perform this task.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
21

Issue Report
ESCAN00071131
Wrong API name
"DescApplSendSpontaneousResponse" in Technical
Reference
Component@Subcomponent:
Diag_CanDesc__coreBase@Doc_TechRef
First affected version:
3.05.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Wrong API name in Technical Reference:
DescApplSendSpontaneousResponse is stated in the Technical Reference but the correct name is
DescSendApplSpontaneousResponse

Resolution Description:
Workaround:
-------------------------------------------------------------------
No workaround available.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
22

Issue Report
ESCAN00073848
Tester present timeout occurs too early after a
0x28 request
Component@Subcomponent:
Diag_CanDesc__coreBase@Implementation
First affected version:
5.05.04
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The positive response $60 after a tester present timeout is sent too early (<5000 ms).
When does this happen:
-------------------------------------------------------------------
- Send service 0x28 (DisableNormalCommunication) request
- Do not send a valid TesterPresent request
- Wait for the tester present timeout to occur (>5000 ms)
In which configuration does this happen:
-------------------------------------------------------------------
DiagProtocol == KWP
AND
Service 0x28 DisableNormalCommunication is active

Resolution Description:
Workaround:
-------------------------------------------------------------------
1.) Increase the tester present timeout slightly by creating a UserConfig.cfg-file with the following
content:
----------------
#ifdef kDescS1TimerTicks
# undef kDescS1TimerTicks
# define kDescS1TimerTicks 503
#endif
----------------
2.) Load the UserConfig.cfg-file into GENy
3.) Generate the source files
After these steps, the tester present timeout should be between the required timespan 5000 ms
to 5100 ms.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
23

Issue Report
ESCAN00074878
a2l error: The parameter SAMPLE_RATE is always 0
Component@Subcomponent:
Cp_XcpOnCan@GenTool_Geny
First affected version:
1.07.00
Fixed in versions:
1.08.03
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The parameter SAMPLE_RATE in the generated CanXcp.a2l file is generated with a fixed value of 0
and does not reflect the parameter as configured in the bus timing configuration.
When does this happen:
-------------------------------------------------------------------
Always and immediately
In which configuration does this happen:
-------------------------------------------------------------------
all configurations

Resolution Description:
Workaround:
-------------------------------------------------------------------
No workaround available.
The file CanXcp.a2l is only used ECU externally for the XCP Master and can be patched manually.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
24

Issue Report
ESCAN00075459
TpRxGetAssignedDestination returns wrong
destination
Component@Subcomponent:
Tp_Iso15765@Implementation
First affected version:
2.73.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
TpRxGetAssignedDestination returns kTpRequestDiagPhysical, although the current connection is
functional.
When does this happen:
-------------------------------------------------------------------
During reception of a functional request with normal fixed, extended or mixed29 addressing
In which configuration does this happen:
-------------------------------------------------------------------
- multiple addressing AND
- application precopy callback must be enabled (TP_USE_APPL_PRECOPY == kTpOn)
- fast Precopy is disabled
- new ApplTpCheckTA API is used (introduced in TP version 2.73.00)

Resolution Description:
Workaround:
-------------------------------------------------------------------
The upper layer which implements the CheckTA / ApplPrecopy callback have to store the
information if the reception is functional or physical.
This information have to be used by the code which want to use TpRxGetAssignedDestination().

Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
25

Issue Report
ESCAN00076138
GENy does not respond when importing CDD files
Component@Subcomponent:
Diag_Geny_coreBase@GenTool_Geny
First affected version:
6.12.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
GENy shows 'busy icon' and will not respond for a long time
When does this happen:
-------------------------------------------------------------------
Always when importing a CDD file
In which configuration does this happen:
-------------------------------------------------------------------
All with periodic DIDs, delay increases with number of periodic DIDs

Resolution Description:
Workaround:
-------------------------------------------------------------------
The tool is not crashing, so an unreasonable amount of patience can help.
Larger CDD files can take more than a day to load, so this workaround is not possible for all use-
cases.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
26

Issue Report
ESCAN00076840
Missing pre-conditions in the API description of
DescApplSendSpontaneousResponse
Component@Subcomponent:
Diag_CanDesc__coreBase@Doc_TechRef
First affected version:
3.05.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Only service 0x86 is listed as pre-condition in the description of the API
DescApplSendSpontaneousResponse.
However there are additional conditions for that API.
When does this happen:
-------------------------------------------------------------------
Always
In which configuration does this happen:
-------------------------------------------------------------------
When Service 0x86 is not supported or the feature to send a spontaneous response is disabled in
GENy
AND
FBL behavior according to HIS is supported by CANdesc

Resolution Description:
Workaround:
-------------------------------------------------------------------
Additional pre-conditions:
The API is also available for specific OEMs in case FBL behavior according to HIS is required
(please refer to chapter 11.8).
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
27

Issue Report
ESCAN00076879
Comment for Messages wrong - Generated code is
not affected
Component@Subcomponent:
DrvCan__base@GenTool_Geny
First affected version:
2.00.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The comment if a message is a BasicCan or a FullCan message is wrong in certain cases
When does this happen:
-------------------------------------------------------------------
During configuration time
In which configuration does this happen:
-------------------------------------------------------------------
- A message is sent and received ( RX and TX message ) AND
- FullCan Flag configured for Rx OR Tx message

Resolution Description:
Workaround:
-------------------------------------------------------------------
No workaround available.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
28

Issue Report
2.4 Compiler Warnings
As a service we also provide the known compiler warnings. The occurrence of a compiler warning
may depend on the used basic software configuration and compiler settings.
Index
ESCAN00027751
Compiler warning for cast to smaller type for "failedByteMask"
Diag_CanDesc__coreBase@Implementation
ESCAN00029697
Compiler warning for useless assignment on API DescPmClientCheckPid
Diag_CanDesc__coreBase@Implementation
ESCAN00031035
Compiler Warning: variable "timer" in "DescRdpiDeletePid" is possibly
uninitialized
Diag_CanDesc__coreBase@Implementation
ESCAN00032552
Compiler warning statement not reached in Internal Assertion
DrvCan__coreHll@Implementation
ESCAN00044044
Compiler Warning: condition is always false
Cp_Xcp@Implementation
ESCAN00047283
IL flags are declared without the "volatile" keyword.
Il_Vector@Implementation
ESCAN00058378
Compiler warning: narrowing or signed-to-unsigned type conversion found
Diag_CanDescGgdaExt_Gm@Implementation
ESCAN00059701
Compiler warning: condition is always true" in the IlTxTimerTask,
IlTxStateTask and IlTxRepetitionsAreActive
Il_Vector@Implementation
ESCAN00066833
Compiler warning: Redefined macro name when compiling a main GENy
project with a sub-project
GenTool_GenyDriverBase@GenTool_Geny
ESCAN00067350
Compiler warning: Redefined macro name when compiling a main GENy
project with a sub-project
GenTool_GenyVcfgNameDecorator@GenTool_Geny
29

Issue Report
ESCAN00027751
Compiler warning for cast to smaller type for
"failedByteMask"
Component@Subcomponent:
Diag_CanDesc__coreBase@Implementation
First affected version:
3.01.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Compiler warning message for the assignment:
*failedByteMask = (vuint8)(0x02 << *failedByteMask);
But there is no real danger of losing information by casting down to a smaller type since the code
generator does not allow more than 7 (seven) sub-service bytes in the request message. So
skipping the SID (bit 0) does not lead to losing the MSB and the value of the failedByteMask
cannot be greater than six.
When does this happen:
-------------------------------------------------------------------
At compile time.
In which configuration does this happen:
-------------------------------------------------------------------
-CANdesc/CANdescBasic

Resolution Description:
Workaround:
-------------------------------------------------------------------
Ignore the warning
Resolution:
-------------------------------------------------------------------
This ESCAN will not be resolved, since the fix might require more resources on the ECU. The code
generator assures that there will be no overflow on the shift operation.
30

Issue Report
ESCAN00029697
Compiler warning for useless assignment on API
DescPmClientCheckPid
Component@Subcomponent:
Diag_CanDesc__coreBase@Implementation
First affected version:
4.02.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The compiler generates a warning message for useless assignment (a = a;) .
When does this happen:
-------------------------------------------------------------------
At compile time.
In which configuration does this happen:
-------------------------------------------------------------------
- CANdesc
_AND_
- Service 0x22 is supported with multiple DIDs in single request.
_AND_
- Service 0x2C is not supported.

Resolution Description:
Workaround:
-------------------------------------------------------------------
Ignore this warning since it is only because of an useless assignment.
Resolution:
-------------------------------------------------------------------
The described issue will not be corrected, since the solution will require more ROM resources.
31

Issue Report
ESCAN00031035
Compiler Warning: variable "timer" in
"DescRdpiDeletePid" is possibly uninitialized
Component@Subcomponent:
Diag_CanDesc__coreBase@Implementation
First affected version:
5.00.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The compiler produces the warning "variable 'timer' is possibly uninitialized" when compiling
desc.c.
When does this happen:
-------------------------------------------------------------------
At compile time
In which configuration does this happen:
-------------------------------------------------------------------
If service 0xAA supported and at least one periodic transmission mode is supported (i.e. not only
"send one response" is supported).

Resolution Description:
Workaround:
-------------------------------------------------------------------
No workaround available.
Resolution:
-------------------------------------------------------------------
This warning is incorrect and can be safely ignored.
32

Issue Report
ESCAN00032552
Compiler warning statement not reached in
Internal Assertion
Component@Subcomponent:
DrvCan__coreHll@Implementation
First affected version:
2.06.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Compiler warning "statement not reached" may occur in the following line:
assertInternal( ((kCanNumberOfTxObjects + CanTxQueuePadBits[kCanNumberOfChannels-1])
<= 65536u), kCanAllChannels, kErrorTxQueueTooManyHandle)
or
assertInternal( ((kCanNumberOfTxObjects + CanTxQueuePadBits[kCanNumberOfChannels-1])
<= 256u), kCanAllChannels, kErrorTxQueueTooManyHandle)
When does this happen:
-------------------------------------------------------------------
At compile time
In which configuration does this happen:
-------------------------------------------------------------------
In the following circumstances:
- transmit queue (C_ENABLE_TRANSMIT_QUEUE is defined)
AND
- assertion check (C_ENABLE_INTERNAL_CHECK is defined)
AND
- multi channel (C_MULTIPLE_RECEIVE_CHANNEL is defined)
AND
- the CAN driver supports the Bit Queue algorithm. (DRVCAN__HLLTXQUEUEBIT_VERSION is
defined in can_def.h and NOT in can_drv.c)

Resolution Description:
Workaround:
-------------------------------------------------------------------
This warning can be ignored since there is no danger for the software normal functioning.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
33

Issue Report
ESCAN00044044
Compiler Warning: condition is always false
Component@Subcomponent:
Cp_Xcp@Implementation
First affected version:
1.26.02
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Compiling file: ../../BSW/Xcp/xcpProf.c
0 errors, 5 warnings
ctc W549: ["../../BSW/Xcp/xcpProf.c" 2518/22] condition is always false
ctc W549: ["../../BSW/Xcp/xcpProf.c" 2522/22] condition is always false
ctc W549: ["../../BSW/Xcp/xcpProf.c" 2526/22] condition is always false
ctc W549: ["../../BSW/Xcp/xcpProf.c" 2659/22] condition is always false
ctc W549: ["../../BSW/Xcp/xcpProf.c" 2663/22] condition is always false
0 errors, 5 warnings
When does this happen:
-------------------------------------------------------------------
This happens when XCP_DISABLE_WRITE_PROTECTION and XCP_DISABLE_WRITE_EEPROM are
defined.
In which configuration does this happen:
-------------------------------------------------------------------
see above

Resolution Description:
Workaround:
-------------------------------------------------------------------
Enable
XCP_DISABLE_WRITE_PROTECTION or XCP_DISABLE_WRITE_EEPROM
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
34

Issue Report
ESCAN00047283
IL flags are declared without the "volatile" keyword.
Component@Subcomponent:
Il_Vector@Implementation
First affected version:
3.10.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
IL flags (Indication, FirstValue, Confirmation, Timeout) are declared without the "volatile"
keyword. Read and Write access to IL flags has no effect due to a Read-Modify-Write problematic.
e.g.
FlagA and FlagB are in the same byte and set on interrupt level
this sequence is executed on task level:
disable int;
clear FlagA; /*1*/
enable int;
... /*3*/
disable int;
clear FlagB; /*2*/
enable int;
The compiler might optimize this sequence and the flag read and write ALWAYS fails:
read the byte at 1), modify the local copy and write the byte at 2)
if the byte is written on interrupt level at 3), the data is lost.
When does this happen:
-------------------------------------------------------------------
At runtime (This Problem has been found by a review and has never been detected in a ECU)
In which configuration does this happen:
-------------------------------------------------------------------
- This issue highly depends on the used compiler and compiler options.
- Preemptive IL flag access is used (e.g. interrupt system)

Resolution Description:
Workaround:
-------------------------------------------------------------------
Review the optimization configuration of your compiler.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
35

Issue Report
ESCAN00058378
Compiler warning: narrowing or signed-to-unsigned
type conversion found
Component@Subcomponent:
Diag_CanDescGgdaExt_Gm@Implementation
First affected version:
2.00.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
The following compiler warning occurs:
warning (dcc:1643): narrowing or signed-to-unsigned type conversion found: unsigned int to
unsigned short
This warning occurs for the following code in GgdaRdiRxTask:
/* send the DTC number and the FTB */
vuint16 DTCNr = ((vuint16) ggdaContexts[context].uudtPrimBuffer[1] << 8)
| (vuint16) ggdaContexts[context].uudtPrimBuffer[2];
When does this happen:
-------------------------------------------------------------------
The warning is issued by the compiler during compilation of the code in case the configuration is
as described below.
In which configuration does this happen:
-------------------------------------------------------------------
Configurations which use service $A9.

Resolution Description:
Workaround:
-------------------------------------------------------------------
The warning can be safely ignored.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
36

Issue Report
ESCAN00059701
Compiler warning: condition is always true" in the
IlTxTimerTask, IlTxStateTask and
IlTxRepetitionsAreActive
Component@Subcomponent:
Il_Vector@Implementation
First affected version:
2.42.00
Fixed in versions:
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Compiler warns for "condition is always true" in the IlTxTimerTask, IlTxStateTask and
IlTxRepetitionsAreActive API. This may happen depending on the configuration.
When does this happen:
-------------------------------------------------------------------
The warning is issued by the compiler during compilation of the code in case the configuration is
as described below.
In which configuration does this happen:
-------------------------------------------------------------------
IlTxTimerTask, IlTxStateTask: Any configuration with exactly one tx message.
IlTxRepetitionsAreActive: Any configuration with exactly one tx message and the API is
configured. (IL_ENABLE_SYS_TX_REPETITIONS_ARE_ACTIVE_FCT must be defined)
Hint:
-------------------------------------------------------------------
The compiler warning is known and has been analyzed thoroughly for its impact on the code.
Nevertheless it will not be fixed due to the rare configuration. The code uses a while loop with a
counter and can probably replaced by a for loop, but other compilers or codeanalysers may warn
about a useless loop. The code exists for about 15 Years and will not be changed.

Resolution Description:
Workaround:
-------------------------------------------------------------------
No workaround available.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
37

Issue Report
ESCAN00066833
Compiler warning: Redefined macro name when
compiling a main GENy project with a sub-project
Component@Subcomponent:
GenTool_GenyDriverBase@GenTool_Geny
First affected version:
2.00.00
Fixed in versions:
2.10.00
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Compiler generates warning on the following macro redefinitions:
v_cfg_1.h(180) : CC78K0R warning W0816: Redefined macro name
'V_ATOMIC_BIT_ACCESS_IN_BITFIELD'
v_cfg_1.h(181) : CC78K0R warning W0816: Redefined macro name
'V_ATOMIC_VARIABLE_ACCESS'
v_cfg_1.h(196) : CC78K0R warning W0816: Redefined macro name 'kComNumberOfNodes'
v_cfg_1.h(197) : CC78K0R warning W0816: Redefined macro name 'ComSetCurrentECU'
v_cfg_1.h(198) : CC78K0R warning W0816: Redefined macro name 'comMultipleECUCurrent'
When does this happen:
-------------------------------------------------------------------
The warning is issued by the compiler during compilation of the code in case the configuration is
as described below.
In which configuration does this happen:
-------------------------------------------------------------------
When two GENy projects are compiled together (e.g. CAN, LIN), one is setup as "main project"
and the other is setup as "sub-project"

Resolution Description:
Workaround:
-------------------------------------------------------------------
No workaround available.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.
38

Issue Report
ESCAN00067350
Compiler warning: Redefined macro name when
compiling a main GENy project with a sub-project
Component@Subcomponent:
GenTool_GenyVcfgNameDecorator@GenTool_Geny
First affected version:
2.19.00
Fixed in versions:
2.26.01, 2.27.00
Problem Description:
What happens (symptoms):
-------------------------------------------------------------------
Compiler generates warning on the following macro redefinitions:
v_cfg_1.h(180) : CC78K0R warning W0816: Redefined macro name
'V_ATOMIC_BIT_ACCESS_IN_BITFIELD'
v_cfg_1.h(181) : CC78K0R warning W0816: Redefined macro name
'V_ATOMIC_VARIABLE_ACCESS'
v_cfg_1.h(196) : CC78K0R warning W0816: Redefined macro name 'kComNumberOfNodes'
v_cfg_1.h(197) : CC78K0R warning W0816: Redefined macro name 'ComSetCurrentECU'
v_cfg_1.h(198) : CC78K0R warning W0816: Redefined macro name 'comMultipleECUCurrent'
When does this happen:
-------------------------------------------------------------------
The warning is issued by the compiler during compilation of the code in case the configuration is
as described below.
In which configuration does this happen:
-------------------------------------------------------------------
When two GENy projects are compiled together (e.g. CAN, LIN), one is setup as "main project"
and the other is setup as "sub-project"

Resolution Description:
Workaround:
-------------------------------------------------------------------
No workaround available.
Resolution:
-------------------------------------------------------------------
The described issue is corrected by modification of all affected work-products.

39

Issue Report
3. New Issues for Information
Issues which should not have an effect on the usage of the license as the issues are relevant for
use cases other than those defined in the questionnaire. The list contains issues that have been
detected since the last report.
Issues listed in this section are not relevant for the use case that has been documented in the
questionnaire provided to Vector. However, the issues may be relevant for other use cases. Also
issues that have been accepted or are tolerated by the OEM (as defined in the questionnaire) are
reported here.
No issue to be reported.
40

Issue Report
4. Report Legend
41

Issue Report
5. Quality Management Contact
Diemo Krüger
PES Quality Management Engineer
Productline Embedded Software (PES)

Vector Informatik GmbH
Ingersheimer Str. 24
D-70499 Stuttgart

Phone: +49 711 80670-3477
Fax: +49 711 80670-399
eMail: diemo.krueger@vector.com
42

Document Outline

26 - TechnicalReference_CANdesc

YourTopic

27 - TechnicalReference_CANdesc_ind

Outline
Page 1
Page 2
Page 3
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13
Page 14
Page 15
Page 16
Page 17
Page 18
Page 19
Page 20
Page 21
Page 22
Page 23
Page 24
Page 25
Page 26
Page 27
Page 28
Page 29
Page 30
Page 31
Page 32
Page 33
Page 34
Page 35
Page 36
Page 37
Page 38
Page 39
Page 40
Page 41
Page 42
Page 43
Page 44
Page 45
Page 46
Page 47
Page 48
Page 49
Page 50
Page 51
Page 52
Page 53
Page 54
Page 55
Page 56
Page 57
Page 58
Page 59
Page 60
Page 61
Page 62
Page 63
Page 64
Page 65
Page 66
Page 67
Page 68
Page 69
Page 70
Page 71
Page 72
Page 73
Page 74
Page 75
Page 76
Page 77
Page 78
Page 79
Page 80
Page 81
Page 82
Page 83
Page 84
Page 85
Page 86
Page 87
Page 88
Page 89
Page 90
Page 91
Page 92
Page 93
Page 94
Page 95
Page 96
Page 97
Page 98
Page 99
Page 100
Page 101
Page 102
Page 103
Page 104
Page 105
Page 106
Page 107
Page 108
Page 109
Page 110
Page 111
Page 112
Page 113
Page 114
Page 115
Page 116
Page 117
Page 118
Page 119
Page 120
Page 121
Page 122
Page 123
Page 124
Page 125
Page 126
Page 127
Page 128
Page 129
Page 130
Page 131
Page 132
Page 133
Page 134
Page 135
Page 136
Page 137
Page 138
Page 139
Page 140
Page 141
Page 142
Page 143
Page 144
Page 145
Page 146
Page 147
Page 148
Page 149
Page 150
Page 151
Page 152
Page 153
Page 154
Page 155
Page 156
Page 157
Page 158
Page 159
Page 160
Page 161
Page 162
Page 163
Page 164

28 - TechnicalReference_CANdesc_KWP_GM

Technical Reference

29 - TechnicalReference_CANdesc_KWP_GM_ind

Outline
Page 1
Page 2
Page 3
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13
Page 14
Page 15
Page 16
Page 17
Page 18
Page 19
Page 20
Page 21
Page 22
Page 23
Page 24
Page 25
Page 26
Page 27
Page 28
Page 29
Page 30
Page 31
Page 32
Page 33
Page 34
Page 35
Page 36
Page 37
Page 38
Page 39
Page 40
Page 41
Page 42
Page 43
Page 44
Page 45
Page 46
Page 47
Page 48
Page 49
Page 50
Page 51
Page 52
Page 53
Page 54
Page 55
Page 56
Page 57
Page 58
Page 59
Page 60
Page 61
Page 62
Page 63
Page 64
Page 65
Page 66
Page 67
Page 68
Page 69
Page 70
Page 71
Page 72
Page 73
Page 74
Page 75
Page 76
Page 77
Page 78
Page 79
Page 80

30 - TechnicalReference_CANdesc_KWP_GMs

CANdesc
Technical Reference
GM / Opel specifics

Version 3.1.0

Authors
Mishel Shishmanyan; Christoph Rätz; Oliver Garnatz;
Matthias Heil; Katrin Thurow
Status
Released

Technical Reference CANdesc KWP GM

1  History
Author
Date
Version
Remarks
Mishel Shishmanyan
2002-05-07
0.9.0 Creation
Christoph Rätz
2002-07-31
0.9.4
Reworked and released
Mishel Shishmanyan
2002-12-12
1.0.0
Added requirements for
ProgrammingMode (Sid $A5) and
DeviceControl(Sid $AE)
Released
Mishel Shishmanyan
2003-04-09
1.1.0
Added default CANdelaStudio
attribute settings for GM/OPEL
ECUs
Oliver Garnatz
2003-12-19
2.0.0
Adapted to CANdesc 2.xx.xx
New Word template used.
Oliver Garnatz
2004-05-14
2.1.0
Replaced AppDesc with ApplDesc
Changed support level of ‘Security
access’
Oliver Garnatz, Mishel
2004-07-15
2.2.0
Added description of CANdesc
Shishmanyan
OBD support
Mishel Shishmanyan
2006-05-02
2.3.0 Added:
-  Service
DynamicallyDefineMessag
e ($2C)
- Service
DefinePIDByAddress ($2D)
-  The PacketHandler
(another type of service
processor)
Modified:
- Cosmetics
-  All APIs described in
detailed table form
Removed:
- None
Jason Wolbers
2006-08-03
2.4.0 Improved
wording
Mishel Shishmanyan
2006-10-22
2.5.0 Added:
- 6.1 “ECU Address configuration”
Mishel Shishmanyan
2006-11-03
2.6.0 Modified:
- 6.1.2 “Multi address ECU
(dynamic addressing)”
Mishel Shishmanyan
2007-12-14
2.7.0 Modified:
- 8.3 “Service attributes”
©2011, Vector Informatik GmbH

2 /  80

Technical Reference CANdesc KWP GM

- 7.6 ”Service
DisableNormalCommunication
($28)”

Removed:
- 6.1.2 “Multi address ECU
(dynamic addressing)” – only
target addresses 0xFE and 0xFD
(for gateways only) are accepted
by CANdesc.
Mishel Shishmanyan
2010-12-21
2.8.0 Modified:
- 6.1 ECU Address configuration
Added:
- 7.5 Service SecurityAccess ($27)
Matthias Heil
2011-04-20
3.0.0 Modified:
- Update to new formatting
- 7.11 Service ProgrammingMode
($A5)
Added:
- 5.3 Update from earlier versions
- 8.4 State group for the
Programming Sequence
Katrin Thurow
2011-12-16
3.1.0 Modified:
6.6.3 High speed programming
mode state

©2011, Vector Informatik GmbH

3 / 80

Technical Reference CANdesc KWP GM

2  Related documents
X  Technical Reference CANdesc
X  User Manual CANdesc

User Manual
Technical
Technical
Reference
Reference
General
OEM
You are here

Figure 2-1 Manuals and References for CANdesc
All GM/Opel specific CANdesc topics are described within this technical reference. Topics
which are common to all OEMs (e.g. features, concepts) are located in the general
technical reference document “TechnicalReference_CANdesc”.
For faster integration, please refer to the user manual document “UserManual_CANdesc”.
©2011, Vector Informatik GmbH

7 /  80

Technical Reference CANdesc KWP GM

3 Overview
The GM/Opel version of CANdesc uses an internal implementation to handle many
diagnostic tasks. Many of these tasks are realized through generated code (constants,
state count, etc.) which gives more flexibility to the application in case of specification or
variant changes. On the other hand, there are “built-in” diagnostic service implementations
which can free the application from some very complex tasks (e.g.
ReadDiagnosticInformation (SID $A9), ReadDataByPacketIdentifier (SID $AA), etc.) and
hide all of the underlying functionality under a simple signal interface for the application. In
addition, CANdesc also handles certain GM/Opel specific management functionality (e.g.
virtual networks) in order to fully comply with GM/Opel diagnostic specifications.
©2011, Vector Informatik GmbH

8 / 80

Technical Reference CANdesc KWP GM

4 CANdesc support by diagnostic service
CANdesc provides three possible levels of support independently for each diagnostic
service – complete, assisted, or basic. The level of support varies according to CANdesc
capability and user selection in CANdelaStudio. All three levels of support provide
complete communication handling (including all transport protocol processing and error
handling), diagnostic session and timer management, and basic error checking.
Communication handling not only includes testing support of service, but also consistency
of service, sub-function and/or identifier combination. A validity check of the addressing
method and data length is performed. Parallel requests are managed (SID $3E, $AA, and
$A9) when allowed. As error handling is a significant part of any ECU software, all low
level errors are handled internally by CANdesc. Finally, CANdesc assists with the
connection to GMLAN (e.g. supervision and management of the VN timer, message
transmission mode, bus speed switching, etc.).
Complete
Complete support means that CANdesc is capable of handling the diagnostic transaction
without requesting support from the ECU application. The ECU developer need not
provide any code to help implement the diagnostic feature; CANdesc handles all
processing. In the case where diagnostic messages contain real-time data, or “signals”,
CANdesc can map that data to global variables in the ECU application and read/write the
values directly to/from RAM without calling any ECU application callbacks; the ECU
developer does not have to concern himself with the protocol level implementation. If a
service modifies a diagnostic state group, CANdesc notifies the application using a
callback function.
Assisted
Assisted support means that CANdesc is capable of fully parsing request messages and
building response messages, but it does not contain the logic necessary to execute the
request or determine data values. The ECU developer must provide callbacks for
CANdesc to fill these logic gaps, which typically come in the form of calculating a signal
value, controlling an I/O port, or perhaps executing an ECU-specific feature such as a self-
test or EEPROM access routine.
Basic
Basic support means that CANdesc is only capable of identifying that the ECU application
must process the request. The ECU application may have to provide logic to validate the
request message and build the response byte-by-byte. This level of support is only used
where code generation is not practical or supported.
©2011, Vector Informatik GmbH

9 / 80

Technical Reference CANdesc KWP GM

RequestCurrentDiagnosticData ($01) – Assisted
The application must implement only the handling of this service (no request length
validation).
RequestFreezeFrameData ($02) – Assisted
The application must implement only the handling of this service (no request length
validation).
RequestEmissionRelatedDTC ($03) – Assisted
The application must implement only the handling of this service (no request length
validation).
ClearDiagnosticInformation ($04) – Assisted
The application must provide a function that clears fault memory.
RequestTestResultsForNonContinouslyMonitoredSystems ($06) – Assisted
The application must implement only the handling of this service (no request length
validation).
RequestTestResultsForContinouslyMonitoredSystems ($07) – Assisted
The application must implement only the handling of this service (no request length
validation).
RequestControlOfOnBoardSystemTestOrComponent ($08) – Assisted
The application must implement only the handling of this service (no request length
validation when the request data length is a constant value).
RequestVehicleInformation ($09) – Assisted
The application must implement only the handling of this service (no request length
validation).
InitiateDiagnosticOperation ($10) – Assisted
The application must provide a function that implements the logic to enable/disable the
settings of DTCs.
ReadFailureRecordData ($12) – Basic
The application must provide a function that implements the request parsing (validation)
and the logic to report the failure record data.
©2011, Vector Informatik GmbH

10 / 80

Technical Reference CANdesc KWP GM

ReadDataByIdentifier ($1A) – Complete
CANdesc completely implements this service for DIDs whose data maps to global
variables. Assisted support is provided for DIDs whose data does not map to global
variables.
ReturnToNormalMode ($20) – Complete
The application must provide an implementation for the event-based callbacks triggered by
this service.
ReadDataByParameterIdentifier ($22) – Complete
CANdesc completely implements this service for PIDs whose data maps to global
variables. Assisted support is provided for PIDs whose data does not map to global
variables. In any case, multiple PID handling (in a single request) is handled internally by
CANdesc.
ReadMemoryByAddress ($23) – Basic
The application must provide a function to determine if the requested address is valid and
a function to return the data stored at the requested address.
SecurityAccess ($27) – Basic
The application must provide functions, which implement the security access mechanism.
By utilizing a diagnostic state group, CANdesc can track the current security level and
assist the application in determining if a request is allowed at the given time.
DisableNormalCommunication ($28) – Complete
CANdesc completely implements this service.
DynamicallyDefineMessage ($2C) – Complete
CANdesc completely implements this service.
DefinePIDByAddress ($2D) – Complete
CANdesc completely implements this service.
RequestDownload ($34) – Basic
The application must implement this service.
TransferData ($36) – Basic
The application must implement this service.
©2011, Vector Informatik GmbH

11 / 80

Technical Reference CANdesc KWP GM

WriteDataByIdentifier ($3B) – Complete
CANdesc completely implements this service for DIDs whose data maps to global
variables. Assisted support is provided for DIDs whose data does not map to global
variables.
TesterPresent ($3E) – Complete
CANdesc completely implements this service.
ReportProgrammedState ($A2) – Complete
CANdesc completely implements this service if the programmed state maps to a global
variable. Assisted support is provided if the programmed state does not map to a global
variable.
ProgrammingMode ($A5) – Assisted
The application must only provide functions that implement programming mode requests.
CANdesc performs state checking internally.
ReadDiagnosticInformation ($A9) – Assisted
The application must provide functions that read fault memory and construct the response
messages byte-by-byte. The application must provide functions to retrieve the number of
fault codes and to step through the list of fault codes matching the requested mask.
Moreover, it has to detect a change in the number of DTCs. CANdesc handles the
scheduler internally.
ReadDataByPacketIdentifier ($AA) – Complete
CANdesc completely implements this service for DPIDs whose data maps to global
variables. Assisted support is provided for DPIDs whose data does not map to global
variables. The scheduler is handled internally by CANdesc.
DeviceControl ($AE) – Assisted
The application must provide device-specific functions that implement the control
algorithms.

Caution
Diagnostic services other than those listed above are not supported by CANdesc in any
way and must be implemented entirely by the ECU developer as a workaround.

©2011, Vector Informatik GmbH

12 / 80

Technical Reference CANdesc KWP GM

5  Important application requirements
5.1
Initialization
In order to initialize the GM/Opel CANdesc component, the application must call the
following function:
Prototype
void DescInitPowerOn (DescInitParam initParameter)
Parameter
initParameter
Initialization parameter
(recommended: ‘kDescPowerOnInitParam’)
Return code
-
-
Functional Description
Power-on initialization of the CANdesc component.
The application must call this function once after power-on, before all other CANdesc functions.

The GM/Opel version of CANdesc has no special behavior for initialization; therefore, the initialization
function can be called with any parameter value. Even so, it is recommended that the ECU developer use
‘kDescPowerOnInitParam’ for the parameter value.
Particularities and Limitations
X  DescInitPowerOn (initParameter) must be called after TpInitPowerOn() (please refer to the transport
protocol documentation) or any reserved diagnostic connection will be lost.
X  DescInitPowerOn (initParameter) calls DescInit() internally for further initializations
Call context
X  Background-loop level with global interrupts disabled
Table 5-1   DescInitPowerOn

©2011, Vector Informatik GmbH

13 / 80

Technical Reference CANdesc KWP GM

Prototype
void DescInit (DescInitParam initParameter)
Parameter
initParameter
Initialization parameter
(recommended: ‘kDescPowerOnInitParam’)
Return code
-
-
Functional Description
Re-initializes the CANdesc component.
The application can call this function to re-initialize CANdesc (e.g. after wakeup). All internal states will be
set to their default values.

The GM/Opel version of CANdesc has no special behavior for initialization; therefore, the initialization
function can be called with any parameter value. Even so, it is recommended that the ECU developer use
‘kDescPowerOnInitParam’ for the parameter value.
Particularities and Limitations
X  The application has already initialized CANdesc once by calling DescInitPowerOn()
Call context
X  Background-loop level with global interrupts disabled
Table 5-2   DescInit
5.2
DeviceControl ($AE) service requirement
The GM/Opel diagnostic specification requires that device control activity shall be limited
by tester present timeout.
Please refer to the section Service DeviceControl ($AE) for more details.
5.3
Update from earlier versions
The behavior of the CANdesc embedded module has not changed fundamentally in
CANdesc version 6.x, but the configuration is much more independent from the CDD
settings. Many options that were previously only configurable as attributes in the CDD file
are now available for configuration in the GENy configuration tool.
As part of this change, the naming scheme for service callbacks is now more independent
from the CDD contents and more adherent to the GMW3110 specification. This will require
modification of existing application code to fit the new naming scheme.
In addition, the implementation of mode $A5 was changed to use the standard CANdesc
state management feature. You can now easily have service execution depend on the
reprogramming sequence, e.g. prevent a service from executing while programming mode
is active. Please also refer to chapter 7.11 - Service ProgrammingMode ($A5) for more
information.
©2011, Vector Informatik GmbH

14 / 80

Technical Reference CANdesc KWP GM

6  GM/Opel specific functionality
6.1
ECU Address configuration
GM/Opel use extended addressing for the functional request message. By default,
CANdesc will accept any request with target address 0xFE. There are some other use
cases that are considered to be supported with the help of user configuration files (refer
the “TechnicalReference_CANdesc.pdf” for configuration details).
6.1.1  Gateway ECUs
According to the GMW3110 v1.6, gateways shall be accessible also via the special target
address 0xFD. To enable the reception on this address, please insert into your user
configuration file for CANdesc the following definition:
#define DESC_ENABLE_GW_ECU_ADDR
6.1.2  Virtual network management
A GMLAN/IVLAN specific implementation is built into CANdesc, which completely
integrates CANdesc into a GM/Opel project. CANdesc manages all aspects of the
diagnostics VN, including activation of the VN in the GMLAN handler and then deactivation
of the VN after diagnostic inactivity (e.g. missing tester) as described in GMW-3110.
When the first diagnostic request is received, CANdesc will activate the diagnostics VN to
provide communication capability with the tester. The VN is then automatically deactivated
under the following conditions:
X  8 seconds after the diagnostic request “ReturnToNormalMode” ($20) is received
X  8 seconds after the tester present timeout
X  8 seconds after the last response is sent, or in the case of requests that do not send a
response, 8 seconds after the request is completely processed
6.1.3  Diagnostic activity notification
CANdesc notifies the application via a callback function when a diagnostic session begins
(the first diagnostic request) and when it ends (the deactivation conditions listed above).
These callbacks are listed below.
©2011, Vector Informatik GmbH

15 / 80

Technical Reference CANdesc KWP GM

Prototype
void ApplDescOnDiagActive (void)
Parameter
-
-
Return code
-
-
Functional Description
When the first diagnostic request (after ECU power-on or wakeup) is received, regardless of the addressing
method, CANdesc calls this function to notify the application that ECU diagnostics are now active (so that
the application can begin diagnostic specific tasks, for instance).
Particularities and Limitations
X  None
Call context
X  Interrupt context, if the CAN-driver is configured to handle receive messages in interrupt mode
X  Background-loop level task context, if the CAN-driver is configured to handle receive messages in
polling mode
Table 6-1   ApplDescOnDiagActive
Prototype
void ApplDescOnDiagInactive (void)
Parameter
-
-
Return code
-
-
Functional Description
Once the conditions for deactivating the diagnostics VN are met (i.e. the diagnostics VN timer reaches
zero), CANdesc calls this function to notify the application that ECU diagnostics are no longer active (so
that the application can end diagnostic specific tasks to lower CPU utilization, for instance).
Particularities and Limitations
X  None
Call context
X  Background-loop level task context of DescTimerTask().
Table 6-2   ApplDescOnDiagInactive

©2011, Vector Informatik GmbH

16 / 80

Technical Reference CANdesc KWP GM

6.2
Request validation
The GM/Opel version of CANdesc is capable of performing the following request
validations:
X  Is the designed diagnostic buffer big enough to hold the whole request? If the request is
physically addressed, the GM/Opel CANdesc implementation will accept it even if the
length is greater than the defined buffer and let the “request length validation” routine
handle the situation. If the request is functionally addressed and the length is greater
than the defined buffer, it will be ignored (regardless of whether it would normally send a
response).
X  Is the requested SID supported? If the SID is not relevant for the ECU, CANdesc will
automatically send a negative response with error code “ServiceNotSupported” ($11).
Further processing will be aborted.
X  Is the request addressing method for the SID correct? Two cases are possible:
X  The requested SID normally provides a response (as defined in CANdelaStudio). In
this case, CANdesc will send a negative response with error code
“ConditionsNotCorrect” ($22). Further processing will be aborted.
X  The requested SID normally does not provide a response (as defined in
CANdelaStudio). In this case, the request will be ignored.
X  Does the request meet the minimum required length (to be distinguishable from other
instances)? Each request is formatted as shown in the figure below:

  1Byt N Bytes (N = 0..n)
L Bytes (L = 0..l)
SID
SID_EXT
Application data
Service instance qualification
“Service head”

Figure 6-1 Request message logical format
X  In order to process the request further, the service instance must be found (which
provides more detailed information about the request than the SID alone); therefore,
the request must be at least n + 1 bytes in length, where n is service dependent.
X  If the length is less than the minimum allowed (as defined in CANdelaStudio),
CANdesc will send a negative response with error code
“SubfunctionNotSupportedInvalidFormat” ($12). Further processing will be aborted.
X  Is the requested service instance supported by the ECU? If not, CANdesc will send a
negative response with error code “SubfunctionNotSupportedInvalidFormat” ($12).
Further processing will be aborted.
X  Is the total request length correct? Two cases are possible:
X  The request length is dynamic. In this case, no automated check can be performed,
and the task will be left to the application.
©2011, Vector Informatik GmbH

17 / 80

Technical Reference CANdesc KWP GM

X  The request length is fixed. In this case, CANdesc will check if the current request
length matches the expected length (as defined in CANdelaStudio). If not, a
negative response with error code “SubfunctionNotSupportedInvalidFormat” ($12)
will be sent. Further processing will be aborted.
X  Does the requested service instance have a defined pre-handler function (please refer
to the user manual CANdesc document “UserManual_CANdesc” for more details about
pre-handlers)? If so, it will be called. This allows the application to extend the built-in
validation with additional custom checks.

Note
If the request passes all of the above validation checks, the main-handler is called
  (please refer to the user manual CANdesc for more details about main-handlers) for
further processing.

6.3
Timeout events
6.3.1  Tester present timeout
Once the tester present timer has been activated, the tester must send the diagnostic
service “Tester Present” ($3E) periodically in order to keep the timer running.
In case of a timeout, the diagnostic state will be initialized exactly the same as Service
ReturnToNormalMode ($20).

Note
CANdesc will automatically send an unsolicited positive response for the
  “ReturnToNormalMode” ($20) diagnostic service (see section 6.5 Sending an
unsolicited single frame response).

6.4
Using the extended negative response
The GM/Opel version of CANdesc supports the extended negative response format to
specify service faults more precisely. This response has the following format:
$7F $AE $E3 $xx $yy (DeviceControlLimitsExceeded)
where $xx and $yy are the extended failure codes (as defined in an ECU specific
diagnostic specification).
There are two possible ways to send an extended negative response:
©2011, Vector Informatik GmbH

18 / 80

Technical Reference CANdesc KWP GM

6.4.1  Sending an extended negative response during service processing
If the application is currently processing a request which requires an extended negative
response, the standard function DescSetNegResponse(errorCode) (please refer to the
general technical reference document “TechnicalReference_CANdesc” for more details)
cannot be used. Instead, the following function is defined:
Prototype
Single Context
void DescSetExtNegResponse (DescNegResCode errorCode,
DescExtNegResCode extErrorCode)
Multi Context
void DescSetExtNegResponse (vuint8 iContext,
DescNegResCode errorCode,
DescExtNegResCode extErrorCode)
Parameter
iContext
Reference to the corresponding request context
errorCode
One of the error code constants defined by CANdesc (located in the
generated desc.h file) with the following naming convention:
kDescNrc<error name>.
Normally, only error code 0xE3 is used.
extErrorCode
A two byte value which is ECU/use-case dependent
Return code
-
-
Functional Description
In the pre-handler or main-handler callback, the application can call this function to send an extended
negative response.
Normally, this extended negative response is only useful for service $AE, but the function may be used for
any currently active service (prior to calling DescProcessingDone()).
Particularities and Limitations
X  The application must already have initialized CANdesc by calling DescInitPowerOn()
X  The define DESC_ENABLE_EXT_NEG_RES_CODE_HANDLING must exist in the generated code
X  Once an error code has been set it cannot be overwritten or reset.
X  This function does not finish the processing of the request. The application must confirm that the
request processing is completely finished by calling DescProcessingDone().
Call context
X  Within a service pre-handler callback and within or after a service main-handler callback
Table 6-3   DescSetExtNegResponse
©2011, Vector Informatik GmbH

19 / 80

Technical Reference CANdesc KWP GM

6.4.2  Sending an unsolicited extended negative response
If the application is not currently processing a request but an extended negative response
must be sent, the function above cannot be used. Instead, a generic API for transmitting
an unsolicited response can be used. In this case, the application must compose the
response message on its own. The following is an example using the format description
from the beginning of section 6.4:

Figure 6-2  Example code for transmitting an unsolicited response
6.5
Sending an unsolicited single frame response
If service “DeviceControl” ($AE) has been activated and the application detects that
conditions have changed detrimentally (e.g. they are “out of limits”) since service
activation, GM/Opel requires that an unsolicited extended negative response shall be sent
by the ECU. To accomplish this, the following API is provided which allows the ECU
developer to send any single frame message using the physically addressed diagnostic
response CAN ID. This API is not just a simple “re-transmitter”, calling the TP with the
application data, but it also synchronizes the request with the current CANdesc
reception/transmission state machine:
X  If CANdesc is currently receiving a request, the unsolicited response will be delayed
until the reception finishes (either with success or failure).
©2011, Vector Informatik GmbH

20 / 80

Technical Reference CANdesc KWP GM

X  If CANdesc is currently transmitting a response, the unsolicited response will be delay
until the transmission finishes (either with success or failure).
See Table 6-4 DescTransmitSingleFrame for the API description.
Prototype
void DescTransmitSingleFrame(DescMsg resData, vuint8 resLen)
Parameter
resData
Pointer to the application data
resLen
The length of the data (in bytes) to be sent
Return code
-
-
Functional Description
This function is called by CANdesc to send the unsolicited positive response on a tester present timeout or
by the application to send an unsolicited extended negative response.
Particularities and Limitations
X  The application must already have initialized CANdesc by calling DescInitPowerOn().
X  The data pointed to by resData is not cached (copied to another buffer) by CANdesc, so the ECU
developer should be careful not to use automatic variable references (non-static function local
variables).
X  The length of the data may not exceed the transport layer single frame length (seven bytes in the case
of normal addressing and six bytes in the case of extended addressing).
Call context
X  Background-loop level task context
Table 6-4   DescTransmitSingleFrame
6.6
GM/Opel CANdesc state machine access
The states relevant to the programming sequence are modeled as a normal CANdesc
state group. This also enables all the usual state group related callbacks and functions for
transition notification, access to the current state, and a function to modify the current
state. For naming convention and an API description, please refer to the general CANdesc
technical reference.
The state group and its states’ names have been fixed to provide a consistent API
independent from the configuration. Normally the names would depend on the settings in
the CDD file. Please refer to Table 8-4 Programming  Sequence state group for the exact
names.
For compatibility reasons CANdesc still provides the API described in this chapter although
they be replaced by the state machine API.
©2011, Vector Informatik GmbH

21 / 80

Technical Reference CANdesc KWP GM

6.6.1  Normal communication state

Prototype
vuint8 DescGetCommState (void)
Parameter
-
-
Return code
kDescCommDisabled
Normal message transmission is deactivated
kDescCommEnabled
Normal message transmission is activated
Functional Description
The application can call this function at any time to obtain the current transmission state.
Particularities and Limitations
X  The application must already have initialized CANdesc by calling DescInitPowerOn().
X  The same information can be retrieved using DescGetStateProgrammingMode ().
X  State information updates after any post handler of mode $28.
Call context
X  Any
Table 6-5   DescGetCommState
©2011, Vector Informatik GmbH

22 / 80

Technical Reference CANdesc KWP GM

6.6.2  Programming mode state

Prototype
vuint8 DescGetProgMode (void)
Parameter
-
-
Return code
kDescProgModeIdle
No enter programming mode request up to now
kDescProgModeAccepted  Enter programming mode accepted (but not active yet)
kDescProgModeActive
Enter programming mode sequence complete
Functional Description
The application can call this function at any time to read the “enter programming mode” sequence state.
Particularities and Limitations
X  The application must already have initialized CANdesc by calling DescInitPowerOn().
X  The same information can be retrieved using DescGetStateProgrammingMode ().
X  State information updates after any post handler of mode $A5.
Call context
X  Any
Table 6-6   DescGetProgMode
©2011, Vector Informatik GmbH

23 / 80

Technical Reference CANdesc KWP GM

6.6.3  High speed programming mode state

Prototype
Single channel
vuint8 DescGetHiSpeedMode (void)
Multiple channel
vuint8 DescGetHiSpeedMode (vuint8 commChannel)
Parameter
commChannel
Communication channel on which CANdesc is running
Return code
kDescHiSpeedModeIdle
No enter programming mode request up to now.
kDescHiSpeedModeAccepted  Enter high speed programming mode accepted (but not active yet)
kDescHiSpeedModeActive
Enter high speed programming mode sequence complete
Functional Description
This function can be called by the application at any time to see if the programming mode requires a switch
to high speed mode.
If the define DESC_ENABLE_FLASHABLE_ECU exists in the generated code, then the application should
call this function within the callback ApplDescOnEnterProgMode to decide whether to switch into high
speed mode.
Particularities and Limitations
X  The result is only valid for the channel on which CANdesc is running.
X  The application has already initialized CANdesc once by calling DescInitPowerOn().
X  The define DESC_ENABLE_REQ_HISPEED_PROG must exist in the generated code (if the ECU must
support service $A5 $02).
X  Idle and Accepted can be retrieved using DescGetStateProgrammingMode ()
X  Active can be queried using IlNwmGetState()
X  State information updates after any post handler of mode $A5.

Call context
X  Any
Table 6-7   DescGetHiSpeedMode

6.7
The PacketHandler (another type of service processor)
A main-handler is the typical callback function for request processing (please refer to the
general technical reference document “TechnicalReference_CANdesc” for more details).
For the GM/Opel version of CANdesc, a different type of service processor for Service
ReadDataByPacketIdentifier ($AA) is necessary – the PacketHandler.
©2011, Vector Informatik GmbH

24 / 80

Technical Reference CANdesc KWP GM

A PacketHandler is a very simple callback that has only one task – to query the application
data and place it into the correct position of the response data buffer. The application may
not use the negative response API with a PackedHandler. The API works asynchrounously,
to allow moving time-consuming operations to different task contexts.
.
6.7.1  PacketHandler API

Prototype
void ApplDescReadPack<Instance-Qualifier> (DescMsg pMsg)
Parameter
pMsg
A pointer to a buffer where the application must copy its data
Return code
-
-
Functional Description
CANdesc calls this function to query the application for the response data related to <Instance-Qualifier>.
The application can provide the data within this function, or it can exit the function and provide it later on
the task level. When the data is ready, the application must call DescDataPacketProcessingDone().
Once the application calls DescDataPacketProcessingDone(), the PacketHandler assembles the data to
be sent with the response (the response length is predefined in CANdelaStudio by the DPID data structure
definition).
Particularities and Limitations
X  The application may not call DescProcessingDone().
Call context
X  Background-loop level context of DescStateTask().
Table 6-8   PacketHandler

©2011, Vector Informatik GmbH

25 / 80

Technical Reference CANdesc KWP GM

Prototype
void DescDataPacketProcessingDone (DescDataPacketProcessStatus status)
Parameter
status
Valid values:
X  kDescDataPacketOk – if the application copied the data successfully
X  kDescDataPacketFailedSendDummy – if the application encountered
an error while obtaining the requested data. CANdesc will transmit the
UUDT response, but it will contain only the message padding pattern and
no actual data.
X  kDescDataPacketFailedDoNotSend - if the application encountered
an error while obtaining the requested data. No UUDT response will be
sent.
Return code
-
-
Functional Description
The application must call this function when it has finished the ApplDescReadPack<Instance-Qualifier>
(DescMsg pMsg) request.
This function allows the ECU developer to have a very slow PacketHandler (e.g. read data from another
CPU).
The CANdesc scheduler can process only one DPID at a time, so once the data has been copied to the
pMsg buffer the application should call this function immediately to avoid long scheduler delays (time jitter
from the configured scheduler rates).
Particularities and Limitations
X  CANdesc must have previously called a PacketHandler callback ApplDescReadPack<Instance-
Qualifier> (DescMsg pMsg).
Call context
X  Background-loop level context of DescStateTask().
Table 6-9   DescDataPacketProcessingDone

©2011, Vector Informatik GmbH

26 / 80

Technical Reference CANdesc KWP GM

sd PacketHandler for CANdesc 4.xx
Tester
CANdesc
Application
[USDT] $AA $01 [DPID]
ApplDescReadPack<Instance-Qualifier> (pMessage)
[UUDT] [DPID] [pMsg]
[status == kDescDataPacketOk ]: DescDataPacketProcessingDone (status )

Figure 6-3 Asynchronous PacketHandler for current CANdesc versions

sd PacketHandler for CANdesc 4.xx ($78)
Tester
CANdesc
Application
[USDT] $AA $01 [DPID]
ApplDescReadPack<Instance-Qualifier> (pMessage)
[ResponsePending time = P2]: [USDT] $7F $AA $78
[status == kDescDataPacketOk ]: DescDataPacketProcessingDone (status )
[UUDT] [DPID] [pMsg]

Figure 6-4 Asynchronous PacketHandler with delayed processing of the first data packet
©2011, Vector Informatik GmbH

27 / 80

Technical Reference CANdesc KWP GM

sd PacketHandler for CANdesc 4.xx (Dummy)
Tester
CANdesc
Application
[USDT] $AA $01 [DPID]
ApplDescReadPack<Instance-Qualifier> (pMessage)
[status==kDescDataPacketFailedSendDummy]: DescDataPacketProcessingDone (status )
[UUDT] [DPID] 00 00 00 00 00 00 00

Figure 6-5 Asynchronous PacketHandler with dummy response, due to an application error while obtaining response data
©2011, Vector Informatik GmbH

28 / 80

Technical Reference CANdesc KWP GM

7  GM/Opel service implementations
7.1
Service InitiateDiagnosticOperation ($10)
CANdesc implements a special handling of the following sub-functions of this service:
X  “DisableAllDtcs” (sub-function $02)
X  “EnableDtcsDuringDeviceControl” (sub-function $03)
WakeUpLinks (sub-function $04) can be implemented using standard main- and post-
handlers.

Note
The actual implementation of these services is still left to the application, controlled by
  the callbacks mentioned below. CANdesc only manages the internal states and
performs service validation.

7.1.1  Service DisableAllDTCs ($10 $02)

Prototype
void ApplDescOnDisableAllDtc (void)
Parameter
-
-
Return code
-
-
Functional Description
Once the service $10 $02 execution has completed with success, CANdesc calls this function to notify the
application about the new state of the diagnostics module.
Particularities and Limitations
X  In this callback the application must implement the actual disabling of DTCs.
X  Also refer to ApplDescOnReturnToNormalMode in order to re-enable DTCs.
Call context
X  Background-loop level task context of DescStateTask()
Table 7-1   ApplDescOnDisableAllDtc
©2011, Vector Informatik GmbH

29 / 80

Technical Reference CANdesc KWP GM

7.1.2  Service EnableDTCsDuringDeviceControl ($10 $03)

Prototype
void ApplDescOnEnableDtcsChangeDuringDevCntrl (void)
Parameter
-
-
Return code
-
-
Functional Description
Once the service $10 $03 execution has completed with success, CANdesc calls this function to notify the
application about the new state of the diagnostics module.
Particularities and Limitations
X  In this callback, the application must enable DTCs during device control.
X  Also refer to ApplDescOnReturnToNormalMode.
Call context
>  Background-loop level task context of DescStateTask().
Table 7-2   ApplDescOnEnableDtcChangeDuringDevCntrl

Note
CANdesc activates the tester present timer for both service instances above.

7.2
Service ReadFailureRecordData ($12)
CANdesc does not offer any special support for this service, but since the definition of the
service is not compatible with the dispatching ability of CANdesc, there are limitations on
the application design:
©2011, Vector Informatik GmbH

30 / 80

Technical Reference CANdesc KWP GM

7.2.1  Service ReadFailureRecordIdentifiers ($12 $01)
Request
CANdesc fully dispatches the diagnostic request; the application does not have to perform
validation.
Response
Depending on the report type requested (PID or DPID), the application must place one of
the following values into the first data byte of the response message:
X  0x00 - for report by PID
X  0x01 - for report by DPID

Note
The ECU can support either reports by PID or DPID, but not both.

7.2.2  Service ReadFailureRecordParameters ($12 $02)
Request
The diagnostic request $12 $02 uses a PID parameter, which is not automatically
dispatched by CANdesc. As a result, CANdesc generates only one function callback
(main-handler) for all service $12 $02 requests. The application must validate the PID
parameter, check the request length, and then process the PID accordingly.
Response
CANdesc does not automatically include the PID parameter in the response message for
service $12 $02. The application must perform this task.
7.3
Service ReturnToNormalMode ($20)
CANdesc completely handles this service and performs the following actions after a
positive response has been sent (or after finishing service execution when the request
does not require a response):
X  The tester present timer will be deactivated.
X  If communication was disabled, it will be re-enabled. CANdesc will notify the application
via the callback function ApplDescOnEnableNormalComm.
X  The network management timer will be started by a new request (timeout: 8 seconds).
X  If the service SendOnChangeDTCCount ($A9 $82) was active, CANdesc will notify the
application to deactivate it by calling the function ApplDescDisableOnChangeDtcCount.
X  The scheduling mechanism for the Service ReadDataByPacketIdentifier ($AA) will be
deactivated, and the scheduler lists will be cleared.
©2011, Vector Informatik GmbH

31 / 80

Technical Reference CANdesc KWP GM

CANdesc also notifies the application of the return to normal mode event via the function
call ApplDescOnReturnToNormalMode:
Prototype
void ApplDescOnReturnToNormalMode (void)
Parameter
-
-
Return code
-
-
Functional Description
CANdesc calls this function on completion of service $20 processing (after the response has been sent, if
applicable) or a tester present timeout.
Particularities and Limitations
X  None
Call context
X  Background-loop level task context of DescStateTask().
Table 7-3   ApplDescOnReturnToNormalMode
7.4
Service ReadDataByParameterIdentifier ($22)
The description for this service is located in the general technical reference document
“TechnicalReference_CANdesc”. Detailed below are only the deviations and behavior not
defined in the general technical reference.
7.4.1  Reading a dynamically defined PID (Parameter Identifier)
Some PIDs are statically defined in CANdelaStudio (i.e. their data structure is predefined
at compile time); however, others can only be defined at runtime using a special service
request (see
Service DefinePIDByAddress ($2D). These dynamically definable PIDs have no data
definitions at power-on, so if the tester tries to read them the result is undefined (according
to GMW-3110 version 1.6). In this situation, CANdesc sends a positive response with no
actual data (only the response service ID ($62) and the PID number from the request).
Please refer to the sequence in Figure 7-9 The dynamically definable PID is not defined.
7.5
Service SecurityAccess ($27)
In general, the application shall implement this service by itself, but CANdesc already
handles some of the tasks regarding this implementation. In the following, you will learn
about what already has been done for you by CANdesc and about the remained parts to
be implemented by your application.
©2011, Vector Informatik GmbH

32 / 80

Technical Reference CANdesc KWP GM

CANdesc tasks:
X  Service format verification.
This step includes: request length and supported sub-service checks.
X  Sub-service execution preconditions specified in the CDD file.
X  SecurityAccess state change
according to the CDD file on positive response for “send-key” service(s).
Application tasks:
X  Additional preconditions checks (pre-handling).
X  Seed-key sequence verification.
X  Timeout monitoring for next seed retry.
X  MEC and vulnerability flag implementation (if applicable).
X  Seed generation.
X  Key computation and verification upon requested key.
X  In case of valid keys, starting of the TesterPresent timer in CANdesc (see API
DescActivateS1Timer). The best place to do that would be the post-handler of a “send-
key” service. Just verify if the service has been responded positively, and the response
was sent successfully. For details about service post-handling, please refer the OEM
independent CANdesc TechnicalReference file located in the delivered software
package.
7.6
Service DisableNormalCommunication ($28)
The GM/Opel version of CANdesc takes the following actions prior sending the positive
response:
X  Requests GMLAN/IVLAN to disable normal communication
X  If the disable normal communication request succeeds:
X  Sets the new communication status (kDescCommDisabled)
X  Activates the tester present timer
X  Notifies the application via the function call ApplDescOnDisableNormalComm.
X  Positive response will be sent
X  If the disable normal communication request fails:
X  A negative response with NRC $22 (ConditionsNotCorrect) will be sent
©2011, Vector Informatik GmbH

33 / 80

Technical Reference CANdesc KWP GM

Prototype
void ApplDescOnDisableNormalComm (void)
Parameter
-
-
Return code
-
-
Functional Description
CANdesc calls this function once normal message transmission has been disabled by a service $28
request and the resulting positive response has been sent.
Particularities and Limitations
X  None
Call context
X  Background-loop level task context of DescStateTask().
Table 7-4   ApplDescOnDisableNormalComm

Prototype
void ApplDescOnEnableNormalComm (void)
Parameter
-
-
Return code
-
-
Functional Description
Once normal message transmission has been restored, CANdesc calls this function to notify the
application.
Particularities and Limitations
X  None
Call context
X  Background-loop level task context of DescStateTask().
Table 7-5   ApplDescOnEnableNormalComm
©2011, Vector Informatik GmbH

34 / 80

Technical Reference CANdesc KWP GM

7.7
Service DynamicallyDefineMessage ($2C)
The GM diagnostic specification (GMW-3110 version 1.6) allows some DPIDs to be
defined at runtime by the tester, rather than at compile time. Using this technique, the
tester can map one or more PIDs (statically or dynamically defined) to a DPID and then
read them back via Service ReadDataByPacketIdentifier ($AA).
CANdesc completely implements this service; no application implementation is required.
The diagram below depicts the relationship between statically and dynamically defined
DPIDs and PIDs and the services that can access them.

Service ID $22
Read
PID pool
(static and
Find
dynamic)

Service ID $2C

Refer
Define
Dynamically
Read
definable

DPID pool
Service ID $AA
Read
Static defined
DPID pool

Figure 7-1 Dynamically defined DPID service relations
©2011, Vector Informatik GmbH

35 / 80

Technical Reference CANdesc KWP GM

7.8
Operations on dynamically definable DPIDs
Dynamically definable DPIDs can be defined and read. The following sections illustrate
these operations with sequence charts involving the tester, CANdesc, and application.
7.8.1  Defining a dynamically definable DPID
If the requested parameters are valid (both PIDs referenced and DPID to be defined are
valid, request has the correct length, etc.), CANdesc overwrites the current DPID definition
with the new list of PIDs.

Caution
If the tester request contains multiple instances of the same PID, the resulting DPID
  definition will contain multiple instances as well. CANdesc does not verify that all of the
requested PIDs are unique.

7.8.2  Reading a dynamically definable DPID
When a read operation is performed on a dynamically definable DPID, four scenarios are
possible:
-  The DPID is not defined
-  The DPID is defined, but the data is not accessible at the moment
-  The DPID is defined, and the data is accessible
-  The DPID is defined, but one of the contained PIDs is dynamically definable and it has
not been defined

If the DPID is not defined, the CANdesc scheduler will send UUDT messages with no
actual data content (only zeros):
©2011, Vector Informatik GmbH

36 / 80

Technical Reference CANdesc KWP GM

sd Read DynDPID (not defined)
Tester
CANdesc
Application
[USDT ] $AA [rate = fast] [DPID]
[UUDT ] $DPID $00 $00 $00 $00 $00 $00 $00
[UUDT ] $DPID $00 $00 $00 $00 $00 $00 $00

Figure 7-2 Dynamically definable DPID is not defined
The next example assumes that the dynamically definable DPID has already been defined
and references a single PID. In addition, the reading of this PID is not possible at the time
of data access (e.g. the data is corrupted), and therefore the application would like to reject
the PID processing. In this situation, the UUDT response message would once again
contain no actual data (only zeros):

Caution
In the case where multiple PIDs are contained in the DPID, and some of them cannot
be processed with success, these PIDs will be skipped in the UUDT response.

©2011, Vector Informatik GmbH

37 / 80

Technical Reference CANdesc KWP GM

sd Read DynDPID (PID failed)
Tester
CANdesc[M AIN]
CANdesc[DYN_DPID]
Application
[USDT ] $AA [rate = fast] [DPID]
DescProcessDynDPID(DPID)
Send virtual request($22 [PID])
ApplDescReadDataByIdentifier_PID
DescSetNegResponse(kDescNrcConditionsNotCorrect)
DescProcessingDone
Send Response($7F $22 $22)
[UUDT ] $DPID $00 $00 $00 $00 $00 $00 $00

Figure 7-3 Single referenced PID cannot provide any data
©2011, Vector Informatik GmbH

38 / 80

Technical Reference CANdesc KWP GM

If the PID is accessible at the time of the request, the UUDT message will contain its data:
sd Read DynDPID (PID ok)
Tester
CANdesc[M AIN]
CANdesc[DYN_DPID]
Application
[USDT ] $AA [rate = fast] [DPID]
DescProcessDynDPID(DPID)
Send virtual request($22 [PID])
ApplDescReadDataByIdentifier_PID
Copy data
DescProcessingDone
Send Response($62 [PID] [Data])
[UUDT ] $DPID [Data]

Figure 7-4 Reading the dynamically defined DPID succeeds
©2011, Vector Informatik GmbH

39 / 80

Technical Reference CANdesc KWP GM

Since dynamically defined DPIDs can also contain dynamically definable PIDs, any
dynamically definable PIDs within the requested DPID must be defined, or the resulting
UUDT response will not contain any actual data (only zeros):
sd Read DynDPID (DynPID not defined)
Tester
CANdesc[M AIN]
CANdesc[DYN_DPID]
Application
[USDT ] $AA [rate = fast] [DPID]
DescProcessDynDPID(DPID)
Send virtual request($22 [PID])
Send Response($62 [PID])
[UUDT ] $DPID $00 $00 $00 $00 $00 $00 $00

Figure 7-5 Dynamically definable PID, referenced by the DPID, is not defined

Caution
When a read operation is performed on a DPID which contains a dynamically definable
PID that is not defined but also other defined PIDs, the resulting UUDT response will
not contain the data for this PID.

©2011, Vector Informatik GmbH

40 / 80

Technical Reference CANdesc KWP GM

7.9
Service DefinePIDByAddress ($2D)
The GM diagnostic specification (GMW-3110 version 1.6) allows some PIDs to be defined
at runtime by the tester, rather than at compile time. Using this technique, the tester can
map a certain memory area to a PID and then read it back via Service
ReadDataByParameterIdentifier ($22) or pack the PID into a DPID (Service
DynamicallyDefineMessage ($2C)) for future read operations via Service
ReadDataByPacketIdentifier ($AA).
CANdesc completely implements this service. The application must only implement the
memory area validation and access functionality.
The diagram below depicts the relationship between statically and dynamically defined
PIDs and the services that can access them.

Read
Service ID $22
PID pool
Read
Dynamically
definable PID
Service ID $2D
Define
pool

Figure 7-6 Dynamically defined PID service relations
©2011, Vector Informatik GmbH

41 / 80

Technical Reference CANdesc KWP GM

7.10  Operations on dynamically definable PIDs
Dynamically definable PIDs can be defined and read. The following sections illustrate
these operations with sequence charts involving the tester, CANdesc, and application.
7.10.1  Defining a dynamically definable PID
If the requested memory area parameters are valid and do not refer to a secured location,
the following diagram applies:
sd Definition of memory block (ok)
Tester
CANdesc
Application
$2D [PID] [m em Address] [m em Size]
ApplDescCheckDynPidM em oryArea(m em Address, m em Size)
m em BlockOk
Update definition of PID
$6D [PID]

Figure 7-7  Definition of dynamically definable PID with valid parameter

©2011, Vector Informatik GmbH

42 / 80

Technical Reference CANdesc KWP GM

If the application detects a problem with the requested memory area (e.g. bad location
reference, security protection, etc.), the sequence below will take place:
sd Definition of memory block (failed)
Tester
CANdesc
Application
$2D [PID] [m em Address] [m em Size]
ApplDescCheckDynPidM em oryArea(m em Address, m em Size)
m em BlockInvSecurity
Convert UseCase->NRC
$7F $2D [NRC = $31]

Figure 7-8 Defining of a dynamically definable PID failed due to security violation

©2011, Vector Informatik GmbH

43 / 80

Technical Reference CANdesc KWP GM

7.10.2  Reading a dynamically definable PID
When a read operation is performed on a dynamically definable PID, three scenarios are
possible:
-  The PID is not defined
-  The PID is defined, but the data is not accessible at the moment
-  The PID is defined, and the data is accessible

If the PID is not defined, CANdesc returns a positive response with no actual data bytes:
sd Read DynPID (not defined)
Tester
CANdesc
Application
$22 [PID]
$62 [PID]

Figure 7-9  The dynamically definable PID is not defined
©2011, Vector Informatik GmbH

44 / 80

Technical Reference CANdesc KWP GM

If the application has already accepted the PID read request (in
ApplDescCheckDynPidMemoryArea) but it cannot complete the read operation, a negative
response can still be sent back to the tester:
sd Read DynPID (failed)
Tester
CANdesc
Application
$22 [PID]
ApplDescReadDynPidM em Content(m em Address, m em Size)
[ResponsePending tim e = P2]: $7F $22 $78
DescReadDynPidM em ContentDone(m em BlockInvCondition)
$7F $22 $22

Figure 7-10 Application error when reading the memory block

©2011, Vector Informatik GmbH

45 / 80

Technical Reference CANdesc KWP GM

In the ideal case, the application writes the data into the supplied data buffer (see
ApplDescCheckDynPidMemoryArea) and acknowledges the end of writing with success:
sd Read DynPID (ok)
Tester
CANdesc
Application
$22 [PID]
ApplDescReadDynPidM em Content(m em Address, m em Size)
[ResponsePending tim e = P2]: $7F $22 $78
DescReadDynPidM em ContentDone(m em BlockOk)
$62 [PID] [Data]

Figure 7-11 Reading of dynamically defined PID succeeds

©2011, Vector Informatik GmbH

46 / 80

Technical Reference CANdesc KWP GM

Prototype
Single Context
DescDynPidMemAccessResult ApplDescCheckDynPidMemoryArea (
const DescDynPidMemBlockInfo* const memArea)
Multi Context
DescDynPidMemAccessResult ApplDescCheckDynPidMemoryArea (
vuint8 iContext,
const DescDynPidMemBlockInfo* const memArea)
Parameter
iContext
Current request handle (reserved for future use)
memArea
A pointer to the memory area definition which must be validated by the

application
>
Address[]
The requested start address (can be a 2, 3 or 4 byte array)
>
size
The requested memory block size
Return code
memBlockOk
The requested area is valid (no memory protection violation, range ok, etc.)
memBlockInvAddress
The requested memory address is invalid (wrong memory access)
memBlockInvSize
The requested memory size is invalid (e.g. out of range)
memBlockInvSecurity  The requested memory address and size are valid, but the area is protected
by security
memBlockInvCondition The access conditions are not correct
Functional Description
CANdesc calls this function when the tester requests a valid $2D service (according to the specification).
The application must validate the memory area parameters.
When the application exits the function, CANdesc generates the appropriate NRC based on the application
return value.
Particularities and Limitations
X  Only available if the ECU supports service $2D.
X  This function runs synchronously, so the application should exit the function as quickly as possible.
Call context
X  Background-loop level task context of DescStateTask().
Table 7-6   ApplDescCheckDynPidMemoryArea

©2011, Vector Informatik GmbH

47 / 80

Technical Reference CANdesc KWP GM

Prototype
Single Context
void ApplDescReadDynPidMemContent (DescMsg pMsg,
const DescDynPidMemBlockInfo* const memArea)
Multi Context
void ApplDescReadDynPidMemContent (vuint8 iContext,
DescMsg pMsg,
const DescDynPidMemBlockInfo* const memArea)
Parameter
iContext
Current request handle (reserved for future use)
pMsg
A pointer to a buffer where the application must write the requested memory
contents
memArea
A pointer to the memory area definition which the application can use for data

acquisition:
>
Address[]
The requested start address (can be a 2, 3 or 4 byte array)
>
size
The requested memory block size
Return code
-
-
Functional Description
Once defined, a dynamically definable PID can be read by the tester using service $22. Dynamically
defined PIDs have special main-handlers which are implemented internally by CANdesc. These main-
handlers call this function to retrieve the data at the requested memory address.
CANdesc does not use a direct memory access implementation for this service since certain ranges may
be located in slow (external) memory chips that require extended periods of time to access. As a result, this
data acquisition function is designed to be asynchronous.
Once the requested data bytes have been written into the buffer pointed to by pMsg, the application must
call DescReadDynPidMemContentDone to acknowledge that the operation is complete.
Particularities and Limitations
>  Only available if the ECU supports service $2D.
>  This function runs asynchronously, so once the application exits this function it can take as much time
as necessary to complete the requested operation
Call context
>  Background-loop level task context of DescStateTask().
Table 7-7   ApplDescReadDynPidMemContent

©2011, Vector Informatik GmbH

48 / 80

Technical Reference CANdesc KWP GM

Prototype
Single Context
void DescReadDynPidMemContentDone (DescDynPidMemAccessResult result)
Multi Context
void DescReadDynPidMemContentDone (vuint8 iContext,
DescDynPidMemAccessResult result)
Parameter
iContext
The request handle previously passed as a parameter to the application in the
callback ApplDescReadDynPidMemContent.
result
The result of the operation:
X  memBlockOk: The requested area is valid (no memory protection
violation, range ok, etc.)
X  memBlockInvAddress: The requested memory address is not valid
(bad memory access)
X  memBlockInvSize: The requested memory size is invalid (e.g. out of
range)
X  memBlockInvSecurity: The requested memory address and size are
valid, but the area is protected by security
X  memBlockInvCondition: The access conditions are not correct
Return code
-
-
Functional Description
Once the data requested by ApplDescReadDynPidMemContent has been written into the buffer pointed to
by pMsg, the application must call this function to acknowledge that the operation is complete.
Particularities and Limitations
X  Only available if the ECU supports service $2D.
Call context
X  Background-loop level task context of DescStateTask().
Table 7-8   DescReadDynPidMemContentDone

©2011, Vector Informatik GmbH

49 / 80

Technical Reference CANdesc KWP GM

7.11  Service ProgrammingMode ($A5)
This service is implemented completely using the CANdesc state management.
The programming sequence follows the state graph shown below:
stm PreProgramming Sequence
Normal
DescInitPowerOn()
+ kDescStateProgrammingModeNormal
ECUPowerOn
Successfully processed SID $28
CommHalted
+ kDescStateProgrammingModeCommHalted
Request $A5 $02
Request $A5 $01
[ApplDescPreRequestProgrammingMode_HiSpeed]
[ApplDescPreRequestProgrammingMode]
Requested
Request $A5 $02 [ApplDescPreRequestProgrammingMode]
Requested_HiSpeed
+ kDescStateProgrammingModeRequested
+ kDescStateProgrammingModeRequested_HiSpeed
Request $A5 $01 [ApplDescPreRequestProgrammingMode_HiSpeed]
Request $A5 $03
Request $A5 $03
Activ e
+ kDescStateProgrammingModeActive

Figure 7-12  Programming mode flowchart
To further restrict service execution based on the current state in the programming
sequence, please refer to 8 - CANdelaStudio default attribute settings regarding the setup
of the corresponding state group in CANdela studio.
7.11.1  Allowing programming mode ($A5 $01/$02)
Prior to activating programming mode, the tester must ask the ECU for permission. The
application may accept or deny this request using a standard prehandler for the respective
level. CANdesc will activate these prehanders per default.
Prehandler names can be changed in the CDD file or the configuration tool, for your
reference the default names are:
X  $A5 $01: ApplDescPreRequestProgrammingMode
X  Compatibility note: This completely replaces the dedicated callback
ApplDescMayEnterProgMode
©2011, Vector Informatik GmbH

50 / 80

Technical Reference CANdesc KWP GM

X  $A5 $02: ApplDescPreRequestProgrammingMode_HiSpeed
X  Compatibility note: This completely replaces the dedicated callback
ApplDescMayEnterHiSpeedProgMode
Please also refer to the general CANdesc technical reference for further information about
prehandler implementation.
7.11.2  Entering programming mode ($A5 $03)
Once the entire programming mode sequence is complete, the application usually makes
the jump to the bootloader (FBL) in one of two ways. Both strategies are discussed in the
following sections.
7.11.2.1  FBL start on EnterProgrammingMode ($A5 $03)
If the application jumps to the FBL on this service, the ECU developer must enable the
“Flashable ECU” option in the generation tool. CANdesc will notify the application to
perform the FBL jump by calling the function ApplDescOnEnterProgMode. The application
can use the function  DescGetHiSpeedMode  to determine if a high speed mode switch
must be performed manually.

Note
If the application jumps to the FBL on this service, it must manage the bus speed
  switching manually.

Prototype
void ApplDescOnEnterProgMode (void)
Parameter
-
-
Return code
-
-
Functional Description
CANdesc will call this function so the application can perform the FBL jump.
Particularities and Limitations
X  To enable this notification, the ECU developer must enable the “Flashable ECU” option in the
generation tool (the define DESC_ENABLE_FLASHABLE_ECU exists in the generated code).
Call context
X  Background-loop level task context of DescStateTask().
Table 7-9   ApplDescOnEnterProgMode

©2011, Vector Informatik GmbH

51 / 80

Technical Reference CANdesc KWP GM

7.11.2.2  FBL start on RequestDownload ($34)
If the application jumps to the FBL on this service, the ECU developer must disable the
option “Flashable ECU” in the generation tool. CANdesc will automatically handle the high
speed switching (if necessary) to comply with the tester expectations. The application must
only implement the service main-handler and perform the jump to the FBL. In order to
verify that the programming mode sequence was completed successfully, the ECU
developer can call the function DescGetProgMode() in the main-handler.

Note
The ECU developer must disable the option “Flashable ECU” in the generation tool
  when no FBL is present in the ECU.

7.11.2.3  Concluding programming mode
Once the flashing activity has concluded (through a service $20 tester request or tester
present timeout), the GM/Opel diagnostic specification states that the ECU shall perform a
software reset. Two scenarios are possible:
>  If the ECU was actually re-flashed, the FBL should perform the reset.
>  If the ECU was not actually re-flashed (the tester was re-flashing another ECU or the
ECU is not flashable), CANdesc notifies the application to perform an ECU reset via the
function call ApplDescForceEcuReset.

Prototype
void ApplDescForceEcuReset (void)
Parameter
-
-
Return code
-
-
Functional Description
CANdesc calls this function to notify the application that it shall perform an ECU reset.
It is not required that the application perform the reset within this function call since it may need to prepare
first (by saving RAM variables into EEPROM, for instance).
Particularities and Limitations
X  None
Call context
X  Background-loop level task context of DescStateTask().
Table 7-10   ApplDescForceEcuReset
©2011, Vector Informatik GmbH

52 / 80

Technical Reference CANdesc KWP GM

7.11.3  Considerations when upgrading
The callback functions used by CANdesc have changed in version 6.x. The following APIs
are no longer used and need to be replaced by service prehandlers:
X  ApplDescMayEnterProgMode
X  ApplDescMayEnterHiSpeedProgMode
7.12  Service ReadDiagnosticInformation ($A9)
This service supplies the tester with information about various DTC statuses (e.g. on
change count of the DTCs, a list of all DTCs matching a given status mask, etc.).
Since the DTC storage and management is application specific, the implementation of the
diagnostic service “ReadDiagnosticInformation” (RDI) ($A9) generalizes this functionality,
reducing the application task to a few callback implementations.

The ECU developer should keep the following important properties in mind when
designing the application:
1.  When an $A9 sub-function has been requested, CANdesc cannot process another
request until after the first UUDT response message has been sent.
2.  While processing and sending the list of matching DTCs for an $A9 $81 request,
CANdesc can process another request except $A9 $80.
3.  CANdesc can process the requests $A9 $80 and $A9 $81 in parallel with $A9 $82.
4.  Application callbacks are handled asynchronously.

Here is a parallel service execution matrix:
Active
$A9 $80
$A9 $81
$A9 $82
Other requests

(except scheduled
$AA )
Requested
$A9 $80
Not possible
Not possible
Possible after
Not possible
the first UUDT is
sent
$A9 $81
Not possible
Not possible
Possible after
Not possible
the first UUDT is
sent
$A9 $82
Not possible
Possible after
Possible after
Not possible
the first UUDT is  the first UUDT is
sent
sent
Other requests  Not possible
Possible after
Possible after
Not possible
the first UUDT is  the first UUDT is
sent
sent
Table 7-11   Service $A9 parallel execution matrix
©2011, Vector Informatik GmbH

53 / 80

Technical Reference CANdesc KWP GM

Note
The RCR-RP responses in the sequence diagrams below are shown for better timing
  request-response relation understanding; however, if the application is fast enough
there will be no RCR-RP response sent.

7.12.1  ReadStatusOfDTCByNumber ($A9 $80)
CANdesc processes this service as shown below.

If the application finds the requested DTC number with the given failure type byte, the
following sequence will be executed:
sd ReadStatusOfDTCByNumber (good)
Tester
CANdesc
Application
[USDT ] $A9 $80 [DT C] [FailureT ypeByte]
ApplDescGetDtcStatusByNum ber(DT C, FailureT ypeByte)
[ResponsePending tim e = P2]: [USDT ] $7F $A9 $78
[ResponsePending tim e = P3M ax]: [USDT ] $7F $A9 $78
DescRdiDtcStatusByNum berFound(StatusByte)
[UUDT ] $80 [DT C][FailureT ypeByte][StatusByte]

Figure 7-13  Request $A9 $80 where the requested fault type combination was found
©2011, Vector Informatik GmbH

54 / 80

Technical Reference CANdesc KWP GM

If the requested fault type combination is not supported by the ECU, the following
sequence will be executed:
sd ReadStatusOfDTCByNumber (failed)
Tester
CANdesc
Application
[USDT ] $A9 $80 [DT C] [FailureT ypeByte]
ApplDescGetDtcStatusByNum ber(DT C, FailureT ypeByte)
[ResponsePending tim e = P2]: [USDT ] $7F $A9 $78
[ResponsePending tim e = P3M ax]: [USDT ] $7F $A9 $78
DescRdiDtcStatusByNum berNotFound
[USDT ] $7F $A9 $31

Figure 7-14 Request $A9 $80 where the requested fault type combination was not found

©2011, Vector Informatik GmbH

55 / 80

Technical Reference CANdesc KWP GM

Here are the detailed descriptions of the APIs used in the above diagrams:

Prototype
void ApplDescGetDtcStatusByNumber (vuint16 dtcNum, vuint8 failureTypeByte)
Parameter
dtcNum
The requested DTC number
failureTypeByte
The requested failure-type byte
Return code
-
-
Functional Description
CANdesc calls this function to query the application for the request combination of DTC number and
failure-type byte. When the application finds this combination, it must acknowledge this by calling the
function DescRdiDtcStatusByNumberFound. If the application cannot find a matching entry, it must
acknowledge this by calling the function DescRdiDtcStatusByNumberNotFound.
Particularities and Limitations
X  Only available if the ECU supports $A9 sub-function $80
X  The application can call DescRdiDtcStatusByNumberFound or DescRdiDtcStatusByNumberNotFound
within this function, or it can exit this function and call one of them later on the application task level.
Call context
X  Background-loop level task context (same as DescStateTask()).
Table 7-12   ApplDescGetDtcStatusByNumber

©2011, Vector Informatik GmbH

56 / 80

Technical Reference CANdesc KWP GM

Prototype
void DescRdiDtcStatusByNumberFound (vuint8 statusByte)
Parameter
statusByte
The current status of the DTC which was passed as a parameter in the
callback ApplDescGetDtcStatusByNumber
Return code
-
-
Functional Description
The application can call this function to acknowledge the successful search result of the DTC number and
failure-type byte combination which were passed as parameters in the callback
ApplDescGetDtcStatusByNumber.
Particularities and Limitations
X  Only available if the ECU supports $A9 sub-function $80
X  CANdesc must have previously called ApplDescGetDtcStatusByNumber
Call context
X  Background-loop level task context
Table 7-13   DescRdiDtcStatusByNumberFound
Prototype
void DescRdiDtcStatusByNumberNotFound (void)
Parameter
-
-
Return code
-
-
Functional Description
The application can call this function to acknowledge the unsuccessful search result of the DTC number
and failure-type byte combination which were passed as parameters in the callback
ApplDescGetDtcStatusByNumber
Particularities and Limitations
X  Only available if the ECU supports $A9 sub-function $80
X  CANdesc must have previously called ApplDescGetDtcStatusByNumber
Call context
X  Background-loop level task context
Table 7-14   DescRdiDtcStatusByNumberNotFound
7.12.2  ReadStatusOfDTCByStatusMask ($A9 $81)
This service transmits a list of DTCs and their properties back to the tester. CANdesc uses
an iteration-based process to request each element of the list from the application.

©2011, Vector Informatik GmbH

57 / 80

Technical Reference CANdesc KWP GM

Note
The iterator parameter discussed below is only provided to help the application keep
track of where it should begin/continue searching the list. The value of this parameter
has no meaning to CANdesc.

CANdesc processes this service as shown below.
If the application finds DTCs that match the given status mask byte, the following
sequence will be executed:
sd ReadStatusOfDTCByStatusM ask (At Least one DTC found)
Tester
CANdesc
Application
[USDT ] $A9 $81 [DT C] [StatusM ask]
ApplDescGetDtcStatusByM ask(iter = 0, StatusM ask)
[ResponsePending tim e = P2]:
[USDT ] $7F $A9 $78
[ResponsePending tim e = P3M ax]:
[USDT ] $7F $A9 $78
DescRdiDtcStatusByM askFound(iter = X, DT C0, FailureT ypeByte0, StatusByte0)
[UUDT ] $81 [DT C0][FailureT ypeByte0][StatusByte0]
ApplDescGetDtcStatusByM ask(iter = X, StatusM ask)
DescRdiDtcStatusByM askFound(iter = Y, DT C1, FailureT ypeByte1, StatusByte1)
[UUDT ] $81 [DT C1][FailureT ypeByte1][StatusByte1]
ApplDescGetDtcStatusByM ask(iter =Y, StatusM ask)
DescRdiDtcStatusByM askNotFound(StatusAvailabilityM ask)
[UUDT ] $81 $00 $00 $00 [StatusAvailabilityM ask]

Figure 7-15 Request $A9 $81 where the application found two DTCs with the requested status mask

©2011, Vector Informatik GmbH

58 / 80

Technical Reference CANdesc KWP GM

Notes
1.  If the application cannot send the second and the following DTCs matching the requested

mask within P2ecu time, CANdesc will not send further RCR-RP messages back to the
tester.
2.  Although CANdesc can process another request after the first UUDT response has been
sent, if that next request is either $A9 $80 or $A9 $81 the request will be rejected with
negative response “ConditionsNotCorrect” ($22).
3.  CANdesc can process $A9 $80 or $A9 $81 requests again once the “End of DTC report”
message has been sent..

If the application cannot find any DTCs matching the requested status mask, CANdesc will
only send the final UUDT response as shown below:
sd ReadStatusOfDTCByStatusM ask (No DTC found)
Tester
CANdesc
Application
[USDT ] $A9 $81 [DT C] [StatusM ask]
ApplDescGetDtcStatusByM ask(iter = 0, StatusM ask)
[ResponsePending tim e = P2]: [USDT ] $7F $A9 $78
[ResponsePending tim e = P3M ax]: [USDT ] $7F $A9 $78
DescRdiDtcStatusByM askNotFound(StatusAvailabilityM ask)
[UUDT ] $81 $00 $00 $00 [StatusAvailabilityM ask]

Figure 7-16  Request $A9 $81 where the application cannot find any DTCs with the requested status mask

©2011, Vector Informatik GmbH

59 / 80

Technical Reference CANdesc KWP GM

Here are the detailed descriptions of the APIs used in the above diagrams:

Prototype
void ApplDescGetDtcStatusByMask (vuint16 iterPos, vuint8 statusMask)
Parameter
iterPos
An iterator for the search start position (abstract)
statusMask
The status mask that the DTC shall match (OR-ed)
Return code
-
-
Functional Description
CANdesc calls this function to query the application for the first/next DTC number that has at least one bit
in its status byte matching the parameter statusMask. When the application finds this combination, it must
acknowledge this by calling the function DescRdiDtcStatusByMaskFound. If the application cannot find any
(more) matching DTCs, it must acknowledge this by calling the function
DescRdiDtcStatusByMaskNotFound.
The application can use the iterator parameter as a marker to continue the search from a certain position
instead of implementing a counter or state machine.
Particularities and Limitations
X  Only available if the ECU supports $A9 sub-function $81
X  The application can call DescRdiDtcStatusByMaskFound or DescRdiDtcStatusByMaskNotFound within
this function, or it can exit this function and call one of them later on the application task level.
Call context
X  Background-loop level task context (same as DescStateTask()).
Table 7-15   ApplDescGetDtcStatusByMask

©2011, Vector Informatik GmbH

60 / 80

Technical Reference CANdesc KWP GM

Prototype
void DescRdiDtcStatusByMaskFound (DescRdiDtcRecord *pDtcReport)
Parameter
vuint16 nextIterPos
The position of the current matching DTC
vuint16 dtcNum
The DTC number which matches the given mask
vuint8 failureTypeByte  The failure type byte of the DTC
vuint8 statusByte
The actual status byte value of the DTC
Return code
-
-
Functional Description
The application can call this function to acknowledge the successful search result of the statusMask which
was passed as a parameter in the callback ApplDescGetDtcStatusByMask.
The parameter pDtcReport is a pointer to a DTC property structure. Since CANdesc will immediately copy
the contents of this structure, the ECU developer can use an automatic variable to save RAM.
Particularities and Limitations
X  Only available if the ECU supports $A9 sub-function $81.
X  CANdesc must have previously called ApplDescGetDtcStatusByMask
Call context
X  Background-loop level task contex
Table 7-16   DescRdiDtcStatusByMaskFound

Prototype
void DescRdiDtcStatusByMaskNotFound (vuint8 dtcSam)
Parameter
dtcSam
Represents the status availability mask of the fault memory manager (i.e.
which bits of the status mask are relevant for the ECU).
Return code
-
-
Functional Description
The application can call this function to acknowledge that there were no (more) DTCs found that match the
statusMask which was passed as a parameter in the callback ApplDescGetDtcStatusByMask
Particularities and Limitations
X  Only available if the ECU supports $A9 sub-function $81.
X  CANdesc has previously called ApplDescGetDtcStatusByMask.
Call context
X  Background-loop level task context
Table 7-17   DescRdiDtcStatusByMaskNotFound
©2011, Vector Informatik GmbH

61 / 80

Technical Reference CANdesc KWP GM

7.12.3  SendOnChangeDTCCount ($A9 $82)
This service manages the background application monitor which detects DTC count
changes. In an effort to more efficiently manage this functionality, CANdesc notifies the
application via function callbacks to activate/deactivate the monitor.
CANdesc processes this service as shown below.
If the tester sends a request for this service with a non-zero status mask, the DTC count
monitor shall be activated:
sd Send on change DTC count request (Enable)
Tester
CANdesc
Application
[StatusM ask != 0]: [USDT ] $A9 $82 [StatusM ask]
ApplDescEnableOnChangeDtcCount
[ResponsePending tim e = P2]: [USDT ] $7F $A9 $78
[ResponsePending tim e = P3M ax]: [USDT ] $7F $A9 $78
DescRdiOnDtcCountChanged(NewCount0)
[UUDT ] $82 [NewCount0]
DescRdiOnDtcCountChanged(NewCount1)
[UUDT ] $82 [NewCount1]

Figure 7-17  Request $A9 $82 with activation of the background DTC count monitor

©2011, Vector Informatik GmbH

62 / 80

Technical Reference CANdesc KWP GM

If the tester sends a request for this service with a status mask of zero, the background
monitoring shall be deactivated:
sd Send on change DTC count request (Disable)
Tester
CANdesc
Application
[StatusM ask == 0]: [USDT ] $A9 $82 [StatusM ask]
ApplDescDisableOnChangeDtcCount
[UUDT ] $82 $00 $00

Figure 7-18 Request $A9 $82 with explicit deactivation of the background DTC count monitor.
©2011, Vector Informatik GmbH

63 / 80

Technical Reference CANdesc KWP GM

Since this service is monitored for tester present timeouts, when no more $3E requests are
received the DTC count monitor shall be deactivated:
sd Send on change DTC count request  (Timeout)
Tester
CANdesc
Application
[StatusM ask != 0]: [USDT ] $A9 $82 [StatusM ask]
ApplDescEnableOnChangeDtcCount
[ResponsePending tim e = P2]: [USDT ] $7F $A9 $78
[ResponsePending tim e = P3M ax]: [USDT ] $7F $A9 $78
DescRdiOnDtcCountChanged(NewCount0)
[UUDT ] $82 [NewCount0]
DescRdiOnDtcCountChanged(NewCount1)
[UUDT ] $82 [NewCount1]
T esterPresent T im eout
ApplDescDisableOnChangeDtcCount

Figure 7-19  Request $A9 $82 with deactivation of the background DTC count monitor by timeout.

Note
In addition to tester present timeout, CANdesc will react in the same way on the
  following events:
X  The tester sends a Service ReturnToNormalMode ($20) request
X  The application calls the function DescRdiDeactivateOnChangeDtcCount.

CANdesc can process this request in parallel to an $A9 $81 request after the first UUDT
response has been sent.
©2011, Vector Informatik GmbH

64 / 80

Technical Reference CANdesc KWP GM

Here are the detailed descriptions of the APIs used in the above diagrams:
Prototype
void ApplDescEnableOnChangeDtcCount (vuint8 statusMask)
Parameter
statusMask
The status mask which the application shall apply as a filter for the DTC count
monitor (i.e. which DTCs shall be monitored)
Return code
-
-
Functional Description
CANdesc calls this function to tell the application that it shall activate DTC count monitoring. From this point
on, the application shall send the DTC count on change by calling the function
DescRdiOnDtcCountChanged.
CANdesc does not store the requested statusMask; it must be stored by the application
Particularities and Limitations
X  Only available if the ECU supports $A9 sub-function $82.
Call context
X  Background-loop level task context (same as DescStateTask()).
Table 7-18   ApplDescEnableOnChangeDtcCount

Prototype
void ApplDescDisableOnChangeDtcCount (void)
Parameter
-
-
Return code
-
-
Functional Description
CANdesc calls this function to notify the application that it shall deactivate DTC count monitoring. From this
point on, the application shall not send the DTC count on change
Particularities and Limitations
X  Only available if the ECU supports $A9 sub-function $82.
Call context
X  Background-loop level task context (same as DescStateTask()).
Table 7-19   ApplDescDisableOnChangeDtcCount

©2011, Vector Informatik GmbH

65 / 80

Technical Reference CANdesc KWP GM

Prototype
void DescRdiOnDtcCountChanged (vuint16 newCount)
Parameter
newCount
The new count of DTCs that match the mask that was passed as a parameter
by the function ApplDescEnableOnChangeDtcCount.
Return code
-
-
Functional Description
The application can call this function to notify CANdesc that the DTC count has changed. CANdesc will
send a UUDT response back to the tester.
Particularities and Limitations
X  Only available if the ECU supports $A9 sub-function $82.
X  CANdesc must have previously called the function ApplDescEnableOnChangeDtcCount.
Call context
X  Background-loop level task context
Table 7-20   DescRdiOnDtcCountChanged

Prototype
void DescRdiDeactivateOnChangeDtcCount (void)
Parameter
-
-
Return code
-
-
Functional Description
The application can call this function to notify CANdesc that it has stopped DTC count monitoring.
CANdesc will call the function ApplDescDisableOnChangeDtcCount to acknowledge this event.
Particularities and Limitations
X  Only available if the ECU supports $A9 sub-function $82.
X  CANdesc must have previously called the function ApplDescEnableOnChangeDtcCount.
Call context
X  Background-loop level task context.
Table 7-21   DescRdiDeactivateOnChangeDtcCount
7.13  Service ReadDataByPacketIdentifier ($AA)
This service allows the tester to read a DPID (data packet identifier) either once or
periodically with three possible speeds (slow, medium, or fast). CANdesc completely
©2011, Vector Informatik GmbH

66 / 80

Technical Reference CANdesc KWP GM

handles this service. Only the PacketHandlers may be implemented by the application as
described in section 6.7 The PacketHandler (another type of service processor).
7.13.1  Handling undefined use cases
There are some use cases which are not covered or completely described in the GM/Opel
diagnostic specification. The following sections describe these cases along with the
resulting CANdesc behaviour.
7.13.1.1  Service $AA handling for undefined dynamically definable DPIDs
According to GMW-3110 version 1.6, if the tester requests an undefined dynamically
definable DPID with service $AA the result is undefined. In this situation, CANdesc sends
a UUDT response with no actual data (byte zero is the DPID number and the remaining
bytes are padded).
7.13.1.2  Service $AA handling for undefined referenced dynamically defined PIDs
As mentioned in section 7.4.1 Reading a dynamically defined PID (Parameter Identifier),
the undefined PID contained by the DPID will contain no data. In this situation, CANdesc
sends a UUDT response with no actual data (byte zero is the DPID number and the
remaining bytes are padded).
7.13.1.3  Service $AA handling for unaccessible referenced PIDs
A dynamically defined DPID references one or more PIDs. If any of those PIDs are not
accessible to the application for any reason (e.g. security access, current ECU state,
memory access error, etc.) at the time the scheduler needs the data, CANdesc sends a
UUDT response with no actual data (byte zero is the DPID number and the remaining
bytes are padded).
7.14  Service DeviceControl ($AE)
The application must completely implement this service. In addition, the GM/Opel
diagnostic specification requires that the tester present timeout monitoring shall be
activated once a DeviceControl service has been executed. Since CANdesc manages the
tester present timer, the application must call the function DescActivateS1Timer to fulfill
this requirement. The proper location for this is the PostHandler for every CPID (Control
Packet Identifier) except 0x00 (reserved for “terminate device control”). To facilitate this,
the ECU developer should select ‘User’ as the PostHandler attribute for these CPIDs in
CANdela Studio. These PostHandlers must then evaluate the status parameter (see
TechnicalReference_CANdesc) and if the result is ok (i.e. CANdesc has successfully sent
the positive response) the application must call the function DescActivateS1Timer.

©2011, Vector Informatik GmbH

67 / 80

Technical Reference CANdesc KWP GM

Note
To reduce ROM usage and improve run-time, the ECU developer can use the
  “PostHanlderOverrideName” attribute in CANdelaStudio to define a single PostHandler
used by all CPIDs.
Please refer to section 8.3 Service attributes for more details.

Here is an example how the ECU developer could implement the PostHandler:

Figure 7-20 PostHandler for “DeviceControl” ($AE)

Prototype
void DescActivateS1Timer (void)
Parameter
-
-
Return code
-
-
Functional Description
The application can call this function to enable tester present timeout monitoring. This function is
normally only used in the “DeviceControl” ($AE) service PostHandler.

This function will not restart the tester present timer!  Only the tester can reset the timer, by sending the
“TesterPresent” ($3E) service.
Particularities and Limitations
X  None
Call context
X  Background-loop level task context (same as DescStateTask()).
Table 7-22   DescActivateS1Timer

©2011, Vector Informatik GmbH

68 / 80

Technical Reference CANdesc KWP GM

7.15 Service TesterPresent ($3E)
CANdesc implements this service by reloading the tester present timer with the original
timeout value.

Caution
This service does not activate tester present timeout monitoring!

©2011, Vector Informatik GmbH

69 / 80

Technical Reference CANdesc KWP GM

8  CANdelaStudio default attribute settings
In order to use the features of CANdesc described in this document, the ECU developer
must set the CANdelaStudio attributes appropriately for the corresponding services and/or
their instances as described below.
The ECU developer configures CANdelaStudio attributes on three levels:
X  Diagnostic Class (like “Ecu identification”, “Security access”, etc.)
X  Diagnostic Instance (like “(DID $90) Vehicle Identification Number”,
“RequestProgrammingModeHighSpeed”, etc.)
X  Service (like “Read” or “Write” on Diagnostic Instance “(DID $90) Vehicle Identification
Number”).
The picture below illustrates these three levels in CANdelaStudio:

Figure 8-1  CANdelaStudio views
Legend:
X  RED:
Diagnostic Class
X  BLUE:
Diagnostic Instance
X  YELLOW:    Service
©2011, Vector Informatik GmbH

70 / 80

Technical Reference CANdesc KWP GM

8.1
Diagnostic class attributes
CANdesc is designed to handle certain events on a diagnostic class basis; therefore, the
ECU developer must configure the attributes on the diagnostic class level. The relevant
services and their attribute configurations are listed below.

Figure 8-2  Diagnostic Class level attributes
Diagnostic Class name
MainHandler  PreHandler
PacketHandler  PostHandler
Support (for  Support (for  Support
Support (for
all Protocol
all Protocol
all Protocol
Service)
Services)
Services)
Failure Record Data –
USER
None None  None
Parameters
Dynamic Data Packets
None
None
All
None
Data Packet
OEM
None
All OEM
Programming mode
OEM
None None  OEM
Table 8-1   Default ‘Diagnostic Class’ attribute settings

©2011, Vector Informatik GmbH

71 / 80

Technical Reference CANdesc KWP GM

8.2
Diagnostic instance attributes
CANdesc is designed to handle certain events on a diagnostic instance basis; therefore,
the ECU developer must configure the attributes on the diagnostic instance level. The
relevant services and their attribute configurations are listed below.

Figure 8-3 Diagnostic Instance level attributes

Diagnostic Class name where Diagnostic
PacketHandler Option
Instances shall be configured

Default
Optional
Data Packet
USER Generated
Table 8-2 Default ‘Diagnostic instance’ attribute settings
©2011, Vector Informatik GmbH

72 / 80

Technical Reference CANdesc KWP GM

8.3
Service attributes
CANdesc is designed to handle certain events on a diagnostic service basis; therefore, the
ECU developer must configure the attributes on the diagnostic service level. The relevant
services and their attribute configurations are listed below.

Figure 8-4 Service related attributes
©2011, Vector Informatik GmbH

73 / 80

Technical Reference CANdesc KWP GM

Notes:
Service (and
MainHandler  PreHandler  PreHandler
PostHandler  PostHandler
sub-service) ID  Support (for  Support
OverrideName
Support
OverrideName
that shall be
Service)
configured
$10 $02
Generated
None
OEM

(User)
$10 $03
Generated
None
OEM

(User)
$20
OEM
None
OEM

$28
OEM 1)
None
None
$3E
Generated

OEM

(User)
$A9 $80
OEM OEM
None

$A9 $81
OEM OEM
None

$A9 $82
OEM
None
OEM

$AE $00
User
None

None

$AE $01-$FF
User
None

User
One function for all
sub-services (see
Service
DeviceControl
($AE))
Table 8-3   Default ‘Service’ attribute settings
>  All cells defined as “None” can optionally be replaced only by “User” attributes when
desired.
>  Some data access services (e.g. $22, $1A, $3B and $AA) use “Generated”
MainHandler (for $AA PacketHandler) support. This eliminates the need for the
application to correctly order the data in the response message (it must only return the
data; CANdesc will assemble the response in the correct order)

Caution
1) It is not possible to implement the MainHandler for service $28 in your application
  since CANdesc (since version 5.05.04) uses this service callback. To evaluate the
service execution conditions, you can use the PreHandler to perform those checks and
to reject the service if needed.

©2011, Vector Informatik GmbH

74 / 80

Technical Reference CANdesc KWP GM

8.4
State group for the Programming Sequence
The CANdesc implementation for the programming mode sequence relies on a state
machine that can be defined as CANdela Studio state group.
State Group
State Qualifier
Blocked  Transitions
Qualifier
Services
ProgrammingMode  Normal
$A5 $xx  $28 -> CommHalted
CommHalted
$A5 $03  $A5 $01 -> Requested
$A5 $02 -> Requested_HiSpeed
$20 -> Normal
Requested
None
$A5 $02 -> Requested_HiSpeed
$A5 $03 -> Active
$20 -> Normal
Requested_HiSpeed None
$A5 $01 -> Requested
$A5 $03 -> Active
$20 -> Normal
Active
$A5 $xx  $20 -> Normal
Table 8-4   Programming Sequence state group
CANdesc will generate these states and transitions even if they do not exist in the CDD
file. Otherwise, CANdesc will reuse what is already present, and add/remove all missing
states and/or transitions.
This means you cannot change the programming sequence by means of changing the
state configuration, but you can put the correct sequence in the CDD file (using the exact
qualifiers from the table above). This opens up the possibility to block further services from
executing in any of these states.
E.g. if you want to block all $AE services from executing while programming mode is
‘Active’, you can model this in CANdela Studio, and CANdesc will do the rest for you.

Note
Since the StateGroup ‘ProgrammingMode’ follows the usual state group
  implementation, all functionality regarding state groups is available for use. Especially
the callback ApplDescOnTransitionProgrammingMode will notify your application of any
state change.

©2011, Vector Informatik GmbH

75 / 80

Technical Reference CANdesc KWP GM

9 OBD support
What is special about OBD support? GM/Opel uses extended addressing for functionally
addressed enhanced diagnostic services; however, functionally addressed OBD requests
must use normal addressing. Due to this, CANdesc uses two separate reception paths.
Additionally, the message definition of some OBD services does not match the generic
service instance generator used by CANdesc so they can only be supported on the
protocol service level.
9.1
CAN identifiers
Enhanced diagnostic services
GM specifies enhanced diagnostic service requirements in GMW-3110.
CAN ID 0x101 - 11-bit extended addressing USDT
This ID is only used for functionally addressed enhanced diagnostic requests. Functionally
addressed OBD requests must use CAN ID 0x7DF.
OBD services
GM uses the OBD service requirements described in ISO15031-5.
CAN ID 0x7DF - 11-bit normal addressing USDT
This ID is only used for functionally addressed OBD requests. Functionally addressed
enhanced diagnostic requests must use CAN ID 0x101.
CAN ID 0x7E0-0x7EF - 11-bit normal addressing USDT
These IDs are used for physically addressed OBD requests to individual ECUs that
support OBD services. ECUs using these IDs for OBD services may also elect to use the
same IDs for physically addressed enhanced diagnostic services; however, ECUs that do
not support OBD services may not use these IDs for enhanced diagnostic services.
9.2
Restrictions
SID $01, $02, $06, $08 and $09 must be handled at the diagnostic class level when the
‘may be combined’ property is enabled in CANdelaStudio.
©2011, Vector Informatik GmbH

76 / 80

Technical Reference CANdesc KWP GM

9.3
CANdelaStudio default attribute settings for OBD services
9.3.1  Diagnostic classes
Powertrain diagnostic and freeze frame data (EOBD) – SID $01 / $02
Emission related trouble codes – SID $03 / $07 / $04
Test results for non-continuously monitored systems (EOBD) – SID $06
Control of on-board system, test, or component (EOBD) – SID $08
Vehicle information (EOBD) – SID $09

Service
PreHandler  MainHandler PostHandler PacketHandler
ID
Support
Support
Support
Support
(On Protocol
level)
$01 None
User
None None
$02 None
User
None None
$06 None
User
None None
$08 None
User
None None
$09
None
User
None None
Table 9-1   Diagnostic class specific attributes
9.4
CANgen configuration
9.4.1  DBC attribute settings for the OBD request message
A message cannot be supported by both the Interaction Layer and CANdesc. For this
reason, diagnostic messages must have the attribute “GenMsgNoIalSupport” set to “yes”
(or, depending on the DBC version, the attribute “GenMsgILSupport” set to “no”). The DBC
author is responsible for setting this attribute.
9.4.2  CANgen version < 4.15.00
In older CANgen versions, no automatic configuration of OBD support is performed so the
ECU developer must configure it manually:
For the functional OBD request message (CAN ID 0x7DF), a precopy function with the
name DescOBDReqInd must be configured (in CANgen on the “Receive Messages” tab).
9.4.3  CANgen version ≥ 4.15.00
Since CANgen version 4.15.00, the DBC author can set the attribute ‘DiagState’ for the
functional OBD request message (CAN ID 0x7DF) to ‘Yes’. In this case, CANgen will
automatically configure the precopy function.
©2011, Vector Informatik GmbH

77 / 80

Technical Reference CANdesc KWP GM

9.4.4 GENy configuration
The DBC author can set the attribute ‘DiagState’ for the functional OBD request message
(CAN ID 0x7DF) to ‘Yes’. Then, CANdesc configures the precopy function automatically.
9.5
CANdesc configuration (without a Powertrain CANdela template)
If the ECU developer is not using a Powertrain template (no OBD services are available in
CANdelaStudio) but the ECU must still support OBD services, a workaround is necessary
to activate the OBD reception path in CANdesc. This workaround requires the ECU
developer to make changes to the file “CANdelaGenAPI.ini”, which is located in the
CANgen executable folder.
To override the look up result, modify:
[GeneratorController]
OverrideAnyObdServiceDetection = [0 - don't (default), 1 - activate OBD support]
The OBD services themselves will be handled by the application using the ‘user-service’
feature, which shall be enabled by the same INI file:
[Misc]
UseGenericUserServiceHandler = [0 - don't (default), 1 - activated]
Optionally, the following entry can be used for post-handler support:
UseGenericUserServicePostHandler = [0 - don't (default), 1 - activated]
©2011, Vector Informatik GmbH

78 / 80

Technical Reference CANdesc KWP GM

10 Debug assertion codes
The GM/Opel specific implementation has optional debug code for certain situations where
the ECU could “hang” or incorrect behavior could occur. Depending on the debug level
chosen in the generation tool, the following cases may be checked:
Assertion name
ID(HEX)  Description
kDescAssertInvalidA9Mode
91
The module has set the $A9 sub-
service iterator incorrectly, which
will cause wrong buffer assignment
when there is parallel processing
of sub-service $82 with one of the
$80 and $81 sub-functions.
kDescAssertUudtBufferAlreadyUnlocked A0  CANdesc received confirmation
that a UUDT response was
successfully transmitted on the
bus, but the internal state machine
indicates that no transmission was
in progress.
kDescAssertWrongUudtTransmitterHandle
A1
CANdesc received confirmation
that a UUDT response was
successfully transmitted on the
bus, but the transmit handle does
not match the one that CANdesc
actually tried to send.
kDescAssertUudtBufferStillLocked
A2
CANdesc attempted a second
UUDT transmission before the
previous one was actually
transmitted on the bus.
kDescAssertIllegalPostProgModeId
A3
CANdesc began the internal post
processing for a programming
mode request, but the requested
programming mode sub-function
was invalid.
Table 10-1   Debug assertion codes
©2011, Vector Informatik GmbH

79 / 80

Technical Reference CANdesc KWP GM

11  Contact
Please visit our website for more information:
>  News
>  Products
>  Demo software
>  Support
>  Training data
>  Addresses

Document Outline

31 - TechnicalReference_CANdescs

Technical Reference CANdesc

CANdesc
Technical Reference

Version 3.07.00

Authors
Oliver Garnatz, Mishel Shishmanyan, Stefan Hübner,
Matthias Heil, Katrin Thurow, Patrick Rieder
Status
Released

2013, Vector Informatik GmbH
Version: 3.07.00
1 / 164
based on template version 5.1.0

Technical Reference CANdesc
1  History
Author
Date
Version  Remarks
Oliver Garnatz
2003-11-12
2.00.00  Splitting into separate documents
and general revision
Oliver Garnatz
2004-01-13
2.00.01  Added chapter ‘Application interface
flow’
Updated format template
Mishel Shishmanyan
2004-03-09
2.01.00  New application callback convention
(from CANdesc 2.09.00)
Mishel Shishmanyan
2004-03-29
2.02.00  New APIs:
-
DescGetActivityState (from
CANdesc 2.10.00)
-
DescSchedulerTask() (from
CANdesc 2.09.00)
Mishel Shishmanyan
2004-04-26
2.03.00  Added more information and
limitations about the ring-buffer
mechanism (12.6.9 “Ring Buffer
Mechanism”)
New feature:
-
Support for generic user
service (from CANdesc
2.11.00)
-
Force CANdesc to send
RCR-RP response (from
CANdesc 2.11.00)
Stefan Hübner
2004-07-16
2.03.01  Editorial revision
Oliver Garnatz
2004-08-12
2.04.00  Added chapter 4.2
ReadDataByIdentifier (SID $22)
within the Single- and the Multiple
PID mode is described
Oliver Garnatz
2004-10-08
2.05.00  ESCAN0000982: Description of
MainHandler structure is not
readable
ROE transmission unit is described
in detail
Stefan Hübner
2004-10-15
2.06.00  Some additional information are
Oliver Garnatz
provided
Peter Herrmann
2005-06-22
2.07.00  Added: Service $2C description.
Klaus Emmert
Added: Warning Text added
Mishel Shishmanyan
2005-08.03
2.08.00  API added:
Oliver Garnatz
-
DescStateTask,
-
DescTimerTask,
-
DescMayCallStateTaskAgain
.
2013, Vector Informatik GmbH
Version: 3.07.00
2 / 164
based on template version 5.1.0

Technical Reference CANdesc
-
ApplDescFatalError
API modified:
-
DescTask,
-
ApplDescCheckSessionTran
sition,
-
DescGetActivityState,
-
DescGetStateSession.
API removed:
-
DescSchedulerTask
Modified description for
ReadDataByIdentifier with long data
and negative response in main-
handler.
Oliver Garnatz
2006-03-02
2.09.00  Added: ...prevent the ECU going to
sleep while diagnostic is active
Mishel Shishmanyan
2006-03-24
2.10.00  Added: document overview
Mishel Shishmanyan
2006-04-27
2.11.00  Modified:
-12.6.13
DynamicallyDefineDataIdentifier
($2C) (UDS) functions
-12.6.13.1
DescMayCallStateTaskAgain()

Mishel Shishmanyan
2007-02-22
2.12.00  Added:
-
12.6.9.3
“DescRingBufferCancel()”

Matthias Heil
2008-01-03
2.13.00  Added:
Caution    concerning    user    main
handler on protocol level l
Matthias Heil
2008-02-29
2.14.00  Added:
Handling of read/write memory by
address:
- 9.3 “Read/Write Memory by
Address”
- 12.6.8.2
“DescStartMemByAddrRepeatedCal
l()”
- 12.6.14 ”Memory Access
Callbacks”
Mishel Shishmanyan
2008-06-06
2.15.00  Removed:
Chapter “ResponseOnEvent
Transmission Unit”
Added:
- 12.6.13.3 “Non-volatile memory
support”
Mishel Shishmanyan
2008-11-09
2.16.00  Modified:
2013, Vector Informatik GmbH
Version: 3.07.00
3 / 164
based on template version 5.1.0

Technical Reference CANdesc
- 12.6.9 and 12.6.9.1: Added
limitation for UDS and SPRMIB with
the ring buffer usage.
- 13.6 …work with the ring-buffer
mechanism
Added:
- 12.6.15 Flash Boot Loader
Support
- 13.8 …send a positive response
without request after FBL flash job
Mishel Shishmanyan
2009-05-18
2.17.00  Modified:
12.6.6.1ApplDescCheckSessionTra
nsition()
Added:
12.6.6.3DescIsSuppressPosResBit
Set ()
Mishel Shishmanyan
2009-08-11
2.18.00  Modified:
Minor editorial changes
5.2 Configure Handlers using
CANdela attributes – added new
data object attributes
Added:
13.9 …enforce CANdesc to use
ANSI C instead of hardware
optimized bit type
5.1 Configure DBC attributes for
diagnostics

Mishel Shishmanyan
2009-09-17
3.00.00  Added:
6 CANdesc Configuration in GENy
8 Multi Identity
12.6.2 Multi Variant Configuration
Functions
Mishel Shishmanyan
2010-01-26
3.01.00  Added:
7 CANdescBasic Configuration in
GENy
Mishel Shishmanyan
2010-12-21
3.02.00  Modified:
12.6.14.1
ApplDescReadMemoryByAddress()
12.6.14.2
ApplDescWriteMemoryByAddress()
12.6.9.2 DescRingBufferWrite()
Katrin Thurow
2011-08-25
3.03.00  Added:
8.1 Single Identity Mode
8.3 Multi Identity Mode
13.10 …configure Extended
Addressing
2013, Vector Informatik GmbH
Version: 3.07.00
4 / 164
based on template version 5.1.0

Technical Reference CANdesc
13.11 …use Multiple Addressing
12.6.6.7
DescGetSessionIdOfSessionState
Modified:
8  Multi Identity Support
13.8 …send a positive response
without request after FBL flash job
Katrin Thurow
2011-09-19
3.04.00  Added:
13.12…use “Dynamic Normal
Addressing Multi TP” with multiple
tester
Modified:
13.11 …use Multiple Addressing
Katrin Thurow
2011-11-27
3.05.00  Added:
12.6.17 “Spontaneous Response”
transmission
Modified:
6.2.1 Global CANdesc Settings
Patrick Rieder
2013-01-23
3.06.00  Added:
10 Generic Processing Notifications
12.6.18 Generic Processing
Notifications

Modified:
6.2.1 Global CANdesc Settings
12.6.4 Service callback functions
12.6.9 Ring Buffer Mechanism
Small fixes
Patrick Rieder
2013-05-27
3.07.00  Added:
11 Busy Repeat Responder Support
Modified:
13.12 …use “Dynamic Normal
Addressing Multi TP” with multiple
tester

2013, Vector Informatik GmbH
Version: 3.07.00
5 / 164
based on template version 5.1.0

Technical Reference CANdesc
2 Introduction
This document has not the job to describe the diagnostic itself. The focus of this document
is the technical aspects of the CANdesc component.

Please note
We have configured the programs in accordance with your specifications in the

questionnaire. Whereas the programs do support other configurations than the one
specified in your questionnaire, Vector’s release of the programs delivered to your
company is expressly restricted to the configuration you have specified in the
questionnaire.

2013, Vector Informatik GmbH
Version: 3.07.00
12 / 164
based on template version 5.1.0

Technical Reference CANdesc
3  Documents this one refers to…
  User Manuals CANdesc and CANdescBasic (one for both)
  Docu OEM

User Manual
Technical
Technical
Reference
Reference
General
OEM
You are here

Figure 3-1: Manuals and References for CANdesc
All  common  topics  with  CANdesc  and  CANdescBasic  are  described  within  this  technical
reference very detailed.
Read all about OEM-specific differences in the TechnicalReference_OEM.
For  faster  integration,  refer  to  the  product’s  corresponding  user  manual  CANdesc  or
CANdescBasic.

2013, Vector Informatik GmbH
Version: 3.07.00
13 / 164
based on template version 5.1.0

Technical Reference CANdesc
4  Architecture Overview
This  chapter  should  describe  the  internal  structure  and  behavior  of  the  CANdesc
component.

4.1
CANdesc – Internal processing
4.1.1
Diagnostic protocol
The  communication  described  in  the  diagnostic  protocol  consists  of  a  ping-pong
communication  between  a  tester  (client)  and  an  ECU  (server).  The  tester  requests  a
service  in  the  ECU  by  transmitting  a  request  to  him.  The  ECU  should  response  with  a
positive response, if the result of this service is valid or the action is prepared to be done.
Is  the  result  negative  or  the  action  could  not  be  executed,  the  ECU  should  respond
negative.
The  validity  checks  have  typically  the  same  pattern  for  all  services  (as  shown  in  Figure
4-1: General request flow). These components which are included in this flow, build up the
main base of the CANdesc component.

Application
Prehandler optional
Mainhandler
Posthandler optional
{
{
{
....
}
}
DescProcessingDone( );
}
Diagnostics - CANdesc
Check Svc
Check SvcInst
Check Session
Check Format
ACK
t
positive Response
Request
negative Response
Tester

Figure 4-1: General request flow

2013, Vector Informatik GmbH
Version: 3.07.00
14 / 164
based on template version 5.1.0

Technical Reference CANdesc
4.1.2
How does this flow actually work?
The picture below shows a simply structured description of the module functionality.
Request reception
Dispatching the request
Idle mode/Awaiting request
Processing the request
Finishing processing of the
request

Figure 4-2: DESC run diagram
Lets assume that the component is currently in the “Awaiting request” state. In this state
it  waits  for  the  next  diagnostic  request  and  if  it  is  needed  –  it  provides  also  timing
monitoring.
Once  a  diagnostic  request  transmission  was  initiated  from  the  transport  layer,  the
component  enters  in  the  state  “Request  reception”.  If  the  reception  is  finished,  further
physical requests will be blocked until the response is sent. Depending on the used OEM a
functional request in the ISO 14230 standard will be handled parallel1 to physical request.
The  ISO  14229-1  standard  is  more  restricted  to  the  parallel  handling.  Except  the
TesterPresent Service no other service could be handled parallel.

1 Not all services could be handled parallel.
2013, Vector Informatik GmbH
Version: 3.07.00
15 / 164
based on template version 5.1.0

Technical Reference CANdesc
After  the  reception  of  the  request  is  completed  the  request  processing  will  be  prepared.
The component is in the  “Dispatching  request”  state. The processing of  the request  is
done at a task level within the next call of the DescTask() function.
First  the  SID  is  checked  whether  supported  or  not.  If  not  a  negative  response
‘ServiceNotSupported’ (NRC $11) will be sent.
Next step is to check if the supported SID is permitted in the current Session (Diagnostic
Mode).  If  not,  the  negative  response  ‘ServiceNotSupportedInTheCurrentSession’  (NRC
$7F) is sent automatically by the CANdesc component.




1Byte    n Bytes (n=0..N)

m

  Bytes (m = 0..M)



SID


SID _EXT
Application data



Service instance qualificatio n

“Request head
“


Figure 4-3: Request message mapping

After  that  the  CANdesc  component  validates,  if  the  sub-service  (service  instance)  is
supported  or  not.  This  is  implemented  with  a  powerful  binary  search.  If  the  service
instance is not  supported, the request will be rejected with the corresponding error code
‘SubFunctionNotSupported’  (NRC  $11,  for  service  which  have  SubFunctions)  or
‘InvalidFormat’ (NRC $13, for service with data identifiers).
For each service  instance which  is supported by the current  configuration,  the CANdesc
component  knows  the  exact  length  of  most  requests.  (Some  requests  use  variable  data
length elements  thus a fixed length doesn’t exist.)  If the length is known and it does not
match, the dispatcher will reject this request (dependent to the manufacturer specification).
If the complete request length is not known, the application has to do this job.
If the service instance is found, the state checks (e.g. ‘Security Level’) will be performed. If
all of them are passed then the component enters the state “Processing the request” in
the  diagram  above.  This  state  consists  of  several  parts  that  are  represented  in  more
detailed  structure  shown  below.  The  dotted  lines  reveal  the  optional  parts  for  the
implementation. For example – the Pre-, Post- and SignalHandlers are optional and might
not be implemented.

2013, Vector Informatik GmbH
Version: 3.07.00
16 / 164
based on template version 5.1.0

Technical Reference CANdesc
Request analyzed
PreHandler
MainHandler
Signal-Handler #0
Signal-Handler #1
Signal-Handler #k
PostHandler

Figure 4-4: Request processing stages
After  the  response  is  composed  CANdesc  must  be  informed  about,  to  start  the
transmission  of  the  final  response.  CANdesc  is  doing  the  handshake  with  the  Tester
(automatic transmission of RCR-RP) while the state “Processing the request” is active.
Within  the  end  of  the  transmission  the  state  “Finishing  processing  of  the  request”  is
entered and the PostHandler (if configured) is called.  In this PostHandler the application
has to do the closing (e.g. updating a state machine, prepare the ECU for a reset …). The
session  state  for  example  (which  is  managed  by  CANdesc)  is  also  updated  in  a
PostHandler.
2013, Vector Informatik GmbH
Version: 3.07.00
17 / 164
based on template version 5.1.0

Technical Reference CANdesc
4.2
Application interface flow
4.2.1
Session- and CommunicationControl
The  services  SessionControl  and  CommunicationControl  are  typically  handled  by
CANdesc. But the application still has the possibility to reject these service requests. You
can find a detailed description in  chapter  12.6.6  Session Handling  and in  chapter  12.6.7
CommunicationControl Handling also.
IDLE
Receive a Request
Search
SID
SID $28
Supported Unsupported
SID $10
(SID $29)
SID $xx
SID $xx
ApplDesc<PreHandler>
ApplDesc<PreHandler>
ApplDesc<PreHandler>
callback
callback
callback
ApplDescCheckSessionTransition
ApplDescCheckCommCtrl
ApplDesc<MainHandler>
{
{
{
...
...
...
DescSessionTransitionChecked();
DescCommCtrlChecked();
DescProcessingDone();
}
}
}
Transmit
Transmit positive
Transmit positive
Transmit positive
negative
response $50
response $68
response $xx
response
NRC $11
WAIT
WAIT
WAIT
TX acknowledge
TX acknowledge
TX acknowledge
$50
$68
$xx
ApplDescOnCommunicationEnabled
ApplDescOnSessionTransition
ApplDescOnCommunicationDisabled
ApplDesc<PostHandler>
>optional - not all OEMs<
IDLE

2013, Vector Informatik GmbH
Version: 3.07.00
18 / 164
based on template version 5.1.0

Technical Reference CANdesc
5  Advanced Configuration
5.1
Configure DBC attributes for diagnostics
If the diagnostic messages shall be defined in the communication data-base file (DBC),
and not received via CANdriver ranges (e.g. in case of normal fixed or extended
addressing), the following attributes in the DBC file must exist and shall be set as shown
below.

Attribute Name
Object  Value  Values
Description
Type
Type  the default value is
written in bold
DiagRequest
Message  Enum  No
Specifies (Yes) that the message is a diagnostic
Yes
physical USDT request message.

DiagResponse
Message  Enum  No
Specifies (Yes) that the message is a diagnostic
Yes
USDT response message.
DiagState
Message  Enum  No
Specifies (Yes) that the message is a diagnostic
Yes
functional USDT request message.
DiagUudtResponse  Message  Enum  false
Specifies (true) that the message is a diagnostic
true
UUDT response message.
Table 5-1: DBC file diagnostic message attributes
2013, Vector Informatik GmbH
Version: 3.07.00
19 / 164
based on template version 5.1.0

Technical Reference CANdesc
6  CANdesc Configuration in GENy
Since version 6.00.00, the CANdesc configuration concept has been improved by splitting
the  concrete  ECU  parameterization  and  software  integration  from  the  diagnostic
specification.
The configuration of CANdesc in GENy consists of two important steps:
-  Importing  a  diagnostic  description  file.  Currently  only  CANdela  (CDD)  files  are
supported therefore in further only the term CDD file will be used.
-  Setup all service options required by the application like:
o  Configure the service handlers (pre-, main- and post-handlers)
o  Setup  the  service  specific  settings,  like  maximum  number  of  dynamically
defined items per DynDID, size of scheduler for periodic data reading, etc.
o  Setup timing parameters (e.g. periodic rates).
The second step is optional, since after importing a CDD file all important settings will be
already prepared for usage. If there are missing or invalid settings, GENy will notify you at
generation time.

6.1
Step One – Importing an ECU Diagnostic Description
After activating the CANdesc component in GENy, you will have the following view:

Figure 6-1 CANdesc GENy startup screen
At this time GENy does not have any CDD file and can not generate CANdesc. You have
to specify a CDD file, using the button on the option “CANdela document name”.

After selecting the CDD file, the CANdesc component tree view will look like:
2013, Vector Informatik GmbH
Version: 3.07.00
20 / 164
based on template version 5.1.0

Technical Reference CANdesc

Info
Please note, the diagnostic buffer size is now set to a non-zero value. At CDD import
time, GENy calculates a statistic over all services with simple, linear data structure and
sets the buffer size to fit the longest request resp. response message. The message
window will show you which service requires the suggested buffer size:

Complex services like reading the faultmemory information or
upload/download/transferdata are excluded from this statistic, since the worst case
response calculation is not possible.
You can still set another value for the buffer size, even lower as the size suggested by
GENy. At generation time, the code generator will check again the set buffer size and
consider more options you have changed (like RingBuffer support) and notify you if the
buffer size is too small.

Now you can try to generate your diagnostic layer, using the default settings.

6.2
Step Two – ECU Diagnostic Configuration in GENy
Once the CDD content is imported, there are several options that can and shall be set up
for best match on your ECU integration needs.

2013, Vector Informatik GmbH
Version: 3.07.00
21 / 164
based on template version 5.1.0

Technical Reference CANdesc
What You Can Configure in GENy
The  goal  of  splitting  the  ECU  integration  configuration  from  the  ECU  diagnostic
specification  is  to  provide  a  simplified  view  on  what  the  ECU  diagnostic  application
developer  is  able  to  configure  without  danger  of  changing  the  diagnostic  specification
provided by the OEM.
If  a  CANdesc  parameter  is  not  available  in  the  source  diagnostic  description  (CDD  file),
you will be able to edit it in GENy, even if it is relevant for the diagnostic specification.
The chapters below will show you all configuration parameters of CANdesc that can be set
up in GENy.
What You Can Not Configure in GENy
All  diagnostic  parameters  that  could  affect  the  ECU  behaviour  regarding  its  diagnostic
specification, provided by the concrete OEM or would lead to inconsistency between the
tester expectations on the ECU behaviour are not editable in GENy. If a change is required
on such a parameter, the diagnostic description source shall be modified, to guarantee that
the OEM or/and the tester will take this change into account.

6.2.1
Global CANdesc Settings
Under  the  generic  settings  you  will  find  the  options  that  affect  the  overall  module
performance,  independently  of  the  diagnostic  services  that  shall  be  supported.  In  the
picture and the table below follows the description of the settings for CANdesc.

Figure 6-2 Example of GENy global CANdesc settings
2013, Vector Informatik GmbH
Version: 3.07.00
22 / 164
based on template version 5.1.0

Technical Reference CANdesc
Attribute Name
Availability
Value Type  Values
Description
The default
value is written
in bold
Cycle Time [ms]
Always available.
Integer
10
The DescTask (resp.
1..255
DescTimerTask) function must be
called EXACTLY in the time period
specified here.
This is important since the time
constant will be converted into a
number of function calls and if this
setting doesn't match the real call
cycle, the component internal
timeout monitors will not function
properly.
Generate CANdesc  Always available.
Button

This feature is only available after
you have generated the whole
CANbedded package.
NOTE: If you run into problems,
generate the whole package again!
Number of ‘Busy-
OEM dependent
Integer
0
The value is the maximum count of
RepeatRequest’
availability.
0..255
parallel handled diagnostic
responded
requests. Only the first diagnostic
Requests
request will be processed, all other
(additonal) request, which will be
received while the first one is in
process, will be also received, but
only responded with NRC $21
('BUSY - repeat request'). If there
are more requests onto the bus
than this number, only the first N
will be responded - all other will be
just ignored.
Flashable ECU
OEM dependent
Boolean
False
Depending on the car
availability.
True
manufacturer this option has
different effects. Please, see the
OEM specific technical reference
document for more information.
Ring Buffer Support  Always available.
Boolean
False
In case your ECU shall send a
True
very long positive response for
some services (usually when
reading fault memory) you can
reserve enough RAM for the
diagnostic buffer to handle the
longest possible response length,
or you can use the built-in ring-
buffer mechanism which allows
usage of smaller buffer. The linear
buffer usage saves ROM and run-
time but needs more RAM, the
ring-buffer saves RAM (you may
send 4095 Byte response with a
20Byte buffer) but requires more
ROM and causes run-time
overhead when used. NOTE: This
2013, Vector Informatik GmbH
Version: 3.07.00
23 / 164
based on template version 5.1.0

Technical Reference CANdesc
Attribute Name
Availability
Value Type  Values
Description
The default
value is written
in bold
option just unlocks the built-in
support, but the selection usage of
the feature is done at run-time by
your application (for each service
independently).
Forced RCR
In some cases (e.g. prior jump into
-RP
OEM dependent
Boolean
False
Response
the FBL (FlashBootLoader), ECU

availability.
True
busy so no task function can be
called for long period of time) it is
necessary to prevent the tester
from ECU response timeout.
Enabling this feature you will be
able to send a RCR-RP
(ResponseCorrectlyReceived-
ResponsePending) response any
time during an active serivce
processing (main-handler called
but no DescProcessingDone has
been called yet).
Repeated Service
Always available.
Enum
Deactivated  In some cases (usually for slow
Call Type
Always
services like reading from
Individual
EEPROM) it is useful to let the
component to poll your application
(service main-handler) until the
service execution is completed.
Otherwise you have to leave the
service's main-handler function
and trigger an own additional
polling task and finalize the service
from there. Using the built-in
polling mechanism you will save
ROM and run-time. Also it prevents
from confusing code structures.
Always: Each main-handler will be
called as long as the application
didn’t call DescProcessingDone().
Individual: Each main-handler will
decide by itself if it will be called
once or as long as the application
didn’t call DescProcessingDone().
Production Mode
OEM dependent
Boolean
False
Enabling the production mode will
availability.
True
set all options in the possible
safest (uncritical) value.
Some car manufacturers don't
allow all of the features in
production, so they will be turned
off.
Spontaneous
Available if Service  Boolean
This setting enables the possibility

False
Response
to send diagnostic responses

0x86 is part of the
True
diagnostic
without a preceding request.
configuration.
This feature is needed for Service

0x86 with Transmission Type I.
2013, Vector Informatik GmbH
Version: 3.07.00
24 / 164
based on template version 5.1.0

Technical Reference CANdesc
Attribute Name
Availability
Value Type  Values
Description
The default
value is written
in bold
The spontaneous response can be
triggered via the API
DescSendApplSpontaneousRespo
nse.
Supplier Notification  Available if
Boolean
False
If this option is enabled, CANdesc
Support
CANdesc
True
notifies the application on incoming
according to ISO
service requests and outgoing
14229-1 2012 is
responses. CANdesc only notifies
used.
the application if the requested
service is supported in the active
session and security state. For
more details see 10 Generic
Processing Notifications
Manufacturer
Available if
Boolean
False
If this option is enabled, CANdesc
Notification Support  CANdesc
True
notifies the application on incoming
according to ISO
service requests and outgoing
14229-1 2012 is
responses. CANdesc notifies the
used.
application right before the
processing of the request starts
and after a response has been
sent. For more details see 10
Generic Processing Notifications
Unknown Services
OEM dependent
Boolean
False
In some cases if the diagnostic
Acceptance
availability.
True
database doesn't contain all
necessary service Ids, or you need
a (some) test identifier(s), you can
enable this option which will
redirect all received requests with
unknown service Ids to your
application for additional
acknowledgment and processing.
Unknown Services
OEM dependent
Boolean
False
If the option 'Unknown Services
Post Handler Calls
availability.
True
Acceptance' is enabled, you may
use this feature to be notified each
time an unknown service
processing has been
accomplished. This post handler
usage is the same as the one of
the normal services post handlers.
Application Interface  Always available.
Boolean
False
The SW component provides built-
Assertions
True
in debug support (assertion) to
ease up the integration and test
into the project.
In general, the usage of assertions
is recommended during the
integration and pre-test phases. It
is not recommended to enable the
assertions in production code due
to increased runtime and ROM
needs. The assertion checks the
correctness of the assigned
2013, Vector Informatik GmbH
Version: 3.07.00
25 / 164
based on template version 5.1.0

Technical Reference CANdesc
Attribute Name
Availability
Value Type Values
Description
The default
value is written
in bold
condition and calls an error-
handler in case this fails. The error
handler is called with an error and
line number. You can find
information about the defined error
numbers in the Desc.h file.
Internal Assertions
Always available.
Boolean
False
The SW component provides built-
True
in debug support (assertion) to
ease up the integration and test
into the project.
In general, the usage of assertions
is recommended during the
integration and pre-test phases. It
is not recommended to enable the
assertions in production code due
to increased runtime and ROM
needs. The assertion checks the
correctness of the assigned
condition and calls an error-
handler in case this fails. The error
handler is called with an error and
line number. You can find
information about the defined error
numbers in the Desc.h file.
List of DANIS
Always available.
String List

Add an arbitrary list of DANIS
drivers
drivers for custom bus access.

Each entry here will result in a user
driver, which can be used to
connect CANdesc to arbitrary
transport layers.

Example:
Adding a driver name “MostTp” will
force CANdesc to generate
templates for a driver with this
name. You will have only to
implement the functions of the
driver skeleton.
UUDT Message
Available only if
Integer
100
This is the maximum time after
Confirmation
UUDT message
1..65535
which a UUDT (Unacknowledged
Timeout [ms]
transmission is
Unsegmented Data Transfer)
supported.
message will be deleted from the
CAN drive request queue and (if
possible) will be replaced by the
next queued message.
Faultmemory
Available only if
Integer
0
Limit the iteration depth for
Iteration Limiter
CANdesc provides
0..255
faultmemory read services.
fault-memory

service
2013, Vector Informatik GmbH
Version: 3.07.00
26 / 164
based on template version 5.1.0

Technical Reference CANdesc
Attribute Name
Availability
Value Type Values
Description
The default
value is written
in bold
implementation.
Some faultmemory ($19) services
can consume much runtime when
performed en bloc. To reduce the
run time of the CANdesc task, use
this option to limit the iteration
depth of the faultmemory access
function so your controller can
handle the workload.
ATTENTION: Depending on your
Tp timeout settings, to low a
number of iterations can result in
an aborted transmission due to
buffer underrun.

A value of 0 (zero) will disable any
limitation.
Variant Mode
OEM dependent
Enum
None
Note: This setting is independent
Selection
availability.
Multi Identity from communication identities!
Mode
None: The diagnostics support one
VSG Mode
configuration only.
Multi Identity Mode: The
diagnostics support different
diagnostic variants. One variant is
active a time.
VSG Mode: Diagnostic Entities
(SubServices, DTCs...) are
grouped into VSGs. Several VSGs
can be active at a time.

6.2.1.1
Generic Processing Notifications (UDS2012)
On activation of the feature “Generic Processing Notifications”, GENy shows the names of
the additional callbacks that will be generated. The names of the callbacks are fixed and
can not be modified (see Figure 6-3). For a detailed description of the feature see chapter
10 Generic Processing Notifications.

Figure 6-3 Activated feature “Generic Processing Notifications”
6.2.2
Service Specific Settings
Once the CDD file is imported you can have an overview of the supported services of your
ECU:
2013, Vector Informatik GmbH
Version: 3.07.00
27 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 6-4 GENy diagnostic service overview

On this level you can also configure all services that will be supported on service Id level
only.

6.2.2.1
Generic Service Settings
Using the CANdesc component tree view you can explore the detailed settings for each
service and its sub-services (if available).
A generic sub-service setup looks like the picture below:
2013, Vector Informatik GmbH
Version: 3.07.00
28 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 6-5 GENy generic sub-service setup
Almost all services have a very simple configuration view. You can see the main-handler is
always available and a preview of the call-back name is shown.
You can only add a pre- and / or a post-handler to such a service, if required.

6.2.2.2
Predefined (implemented) Services in CANdesc
There are configurations (OEM dependent) where several services are fully implemented
by CANdesc. Such service can be, StartDiagnsoticSession, SecurityAccess,
DynamicallyDefinedDataIdentifier, ReadDataByPeriodicIdentifier, etc.
Those services that will not be handled by the application are marked in GENy as shown
on the picture:
2013, Vector Informatik GmbH
Version: 3.07.00
29 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 6-6 GENy predefined sub-service setup
As you can see, the main-handler is grayed and marked as “implemented by CANdesc”.
The same can apply (depends on the service) also to the pre- and post-handlers of the
service.
In the example on the Figure 6-6 GENy predefined sub-service setup you see that the pre-
handler is still free for usage. This means you can still implement a pre-handler to check
additional conditions prior CANdesc will be able to process the service. For other service it
could be also the post-handler free for implementation.

There are several services that make some exceptions to the predefined implementation
rule:

2013, Vector Informatik GmbH
Version: 3.07.00
30 / 164
based on template version 5.1.0

Technical Reference CANdesc
Service 0x2A:
-  PreHandler  configuration  is possible:  If  a pre-handler  is required,  it  must  be
enabled on all sub-functions of the concrete DID. The pre-handler name will
be “ApplDescPreReadPeriodicDid<DID instance name>”.
-  PreHandler on “stop all” is not used by CANdesc and will not be considered
during the code generation even if it is enabled.
-  Main-Handler  are  set  to  “implemented  by  CANdesc”  since  the  data  reading
call-back will be the corresponding 0x22 DID service call. This means that if
the corresponding service 0x22 DID has been set to use the “Signal API”, the
periodic reading service will use it too.
-  Post-Handlers are not supported at all.

Service 0x2C:
-  PreHandler  configuration  is possible:  If  a pre-handler  is required,  it  must  be
enabled on all sub-functions of the concrete DID. The pre-handler name will
be “ApplDescPreDynDefineDid<DID instance name>”.
-  PreHandler on “clear all” is not used by CANdesc and will not be considered
during the code generation even if it is enabled.
-  Main-Handler are set to “implemented by CANdesc” since the DID definition
is always done by CANdesc.
-  Post-Handler are not supported at all.
6.2.2.3
Signal Access Enabled Services
Some services such as the UDS ones 0x22/0x2A and 0x2E, can be processed on  signal
level. This means CANdesc will analyze the request/response data structure and generate
the  service  main-handler,  leaving  to  the  application  only  the  task  to  provide  the  signal
values for the response, resp. to write the requested signal values to the ECU memory.
The setting view of such a service is shown below:
2013, Vector Informatik GmbH
Version: 3.07.00
31 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 6-7 GENy signal API enabled sub-service setup
Note: For the read dynamically defined DID service, there is no signal access since they
are always implemented by CANdesc internally.

If  the  “Signal API” option  is  not  enabled  this  service  is  to  be  implemented  like  any  other
diagnostic service. The data object specific settings, described below,  will have no effect
on the code generation.
If the “Signal API” option is enabled, CANdesc will generate per default a call-back function
for  any  data  object  (signal)  the  service  contains. You  can  specify  more  options  on  each
signal,  to  achieve  the  maximum  advantage  of  CANdesc  –  fully  implemented  diagnostic
service.
2013, Vector Informatik GmbH
Version: 3.07.00
32 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 6-8 GENy signal view of a sub-service
You can have three types of signal handling:

Figure 6-9 GENy signal handler types

FAQ
Constant is only possible if the CDD file has contained constant value for the selected data
object. You can not specify in GENy a constant value for a signal handler.

In case of selected “Direct Access” signal handling, the following options will be enabled:
2013, Vector Informatik GmbH
Version: 3.07.00
33 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 6-10 GENy direct access signal handler settings

Attribute Name
Availability
Value
Values
Description
Type
The default value is
written in bold
Signal Handler Type  Only for signal API  Enum
SignalHandler  Select the type of signal handler
enabled services.
Constant

DirectAccess
Constant: The data value is
constant. The data value can be
used directly. This is used only
when the corresponding
subservice uses a signal API main
handler.

Signal Handler: Use a callback
function to get/set the data value.
This function is used only when the
corresponding subservice uses a
signal API main handler.

Direct Access: Directly use a
variable to access the data object.
Also, a signal API main handler
has to be used for this setting to
have any effect.
SignalHandler
Only for signal API  String
<DataObjectQ
This value is used as base for the
Function Base
enabled services
ualifier>+<Dia
signal access function - depending
Name
and a signal
gInstanceQual on how the value is used, the
access through a
ifier>
name entered here is prefixed with
SignalHandler is
different prefixes, e.g
selected
ApplDescRead / ApplDescWrite.

You can override the default name,
by specifying an own signal base.
The Prefix (e.g. ApplDesc can not
be overridden).
Signal Variable
Only for signal API  String
<DataObjectQ
The name of the signal variable.
Name
enabled services
ualifier>
2013, Vector Informatik GmbH
Version: 3.07.00
34 / 164
based on template version 5.1.0

Technical Reference CANdesc
Attribute Name
Availability
Value
Values
Description
Type
The default value is
written in bold
and if
Example:
DirectAccess
signal handling is
c_dataTemp
selected
g_applData.bit0
Signal Variable
Only for signal API  Enum
Ram
To create the proper extern
Prototype
enabled services
None
declaration to access the signal
and if
Const
variable, the proper access
DirectAccess
User
modifiers have to be specified.
signal handling is

selected
None: No prototype is generated at
all. "DescType.h" where the user
has to define the real typedefs (for
structure access for example).

Ram: The variable is located in
RAM.

Const: The variable is located in
ROM.

User: Set a user defined prototype.
Signal Variable User  Only for signal API  String
Empty
Set the prototype of the signal
Prototype
enabled services
variable.
and if
Example:
DirectAccess
signal handling is
boolean
selected
EcuTempType
and if the Signal
Variable Prototype
is set to User

6.2.3
Timing Settings
GENy imports all possible timings that the diagnostic  description source provides. Those
parameters  that  are  available  in  the  CDD  file  are  considered  as  a  part  of  the  ECU
specification  and  are  not  modifiable  in  GENy.  If  a  modification  of  those  parameters  is
required,  please  change  their  values  in  the  diagnostic  description  file  and  re-import  it  in
GENy.
All  other  parameters  can  be  set  up  manually,  but  the  default  value  already  matches  the
OEM specification.
2013, Vector Informatik GmbH
Version: 3.07.00
35 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 6-11 GENy CANdesc timing parameters
6.2.4
Security Access Settings (UDS2006)
If the security access service is implemented by CANdesc (see the service handler on the
service 0x27 instances), you can set here the level specific attributes, like attempts to start
the delay time, delay time on power on, etc.

Caution
It  is OEM  specific  property  whether  the security access  parameters  will  be  evaluated
  security  level  specific  or  not.  In  case  the  security  access  service  specification  of  the
concrete OEM requires only global configuration of these options, the code generator
will calculate the maximum value over all levels for each parameter and this value will
be used by the service implementation in CANdesc.
Example: Level 1 has “Attempt Counter” = 1, and Level 2 has for the same parameter =
3. CANdesc will use then for “Attempt Counter” = 3 for all security levels.

2013, Vector Informatik GmbH
Version: 3.07.00
36 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 6-12 GENy CANdesc security access parameters

Attribute Name
Availability
Value
Values
Description
Type
The default value is
written in bold
Attempt Counter
Only if the
Integer
0
Specifies the maximum number of
SecurityAccess
1..255
failed attempts to unlock the ECU.
state group is
If this number is reached, a delay
available
for the next security access try will
be inserted.
If a non-zero value is entered, the
delay time must be set to a non-
zero value too.

Note: This parameter has only
effect only if the SecurityAccess
service is handled by CANdesc.
Initial Delay [ms]
Only if the
Integer
0
Specifies the delay time after the
SecurityAccess
1..65535
maximum retry attempt count has
state group is
been reached.
available

If a non-zero value is entered, the
2013, Vector Informatik GmbH
Version: 3.07.00
37 / 164
based on template version 5.1.0

Technical Reference CANdesc
Attribute Name
Availability
Value
Values
Description
Type
The default value is
written in bold
attempt count must be set to a
non-zero value too.

Note: This parameter has only
effect only if the SecurityAccess
service is handled by CANdesc.
PowerOn Delay [ms]  Only if the
Integer
0
Specifies the delay time at power
SecurityAccess
1..65535
on.
state group is

available
If a non-zero value is entered, the
delay time must be set to a non-
zero value too.

Note: This parameter has only
effect only if the SecurityAccess
service is handled by CANdesc.

6.2.5
Security Access Settings (UDS2012)
Due to the new features in CANdesc UDS2012, the configuration of the security levels in
GENy has changed.

Figure 6-13 Security settings in GENy
Attribute Name
Availability
Value
Values
Description
Type
The default value is
written in bold
Level Specific Failed  Only if the
Boolean  False
Switch to select whether a global
Access Attempt
SecurityAccess
True
false attempt counter and delay
Supervision
state group is
timer for all security levels shall be
available
used (false) or if each level has its
own false attempt counter and
delay timer (true).
Use Static Seed
Only if the
Boolean  False
For each level can be selected if a
SecurityAccess
True
static seed is used (true) or not
state group is
(false). Static seed means that
2013, Vector Informatik GmbH
Version: 3.07.00
38 / 164
based on template version 5.1.0

Technical Reference CANdesc
Attribute Name
Availability
Value
Values
Description
Type
The default value is
written in bold
available
CANdesc stores the seed and re-
uses the seed in a positive
response to a seed request for that
level, until the level is unlocked.
Failed Attempt
Only if the
Integer
Value
The number of failed security
Counter to Delay
SecurityAccess
imported from  unlock attempts allowed before a
state group is
the Cdd file.
delay is imposed between
available
0..65535
attempts.
Failed Attempt
Only if the
Integer
Value
The delay time in ms which is
Delay [ms]
SecurityAccess
imported from  imposed if the Failed Attempt
state group is
the Cdd file.
Counter limit has been reached.
available
0..65535
Further security access attempts
are discarded, until the delay has
expired.
PowerOn Delay [ms]  Only if the
Integer
Value
The delay time in ms which is
SecurityAccess
imported from  imposed when the ECU is
state group is
the Cdd file.
powered on. Requests to unlock
available
0..65535
the security level are declined until
the delay has expired.

6.2.6
Scheduler Settings
If  the  ECU  shall  support  the  periodic  data  reading  service,  the  following  settings  are
relevant and shall be setup to match the ECU performance and RAM resource availability.

2013, Vector Informatik GmbH
Version: 3.07.00
39 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 6-14 GENy CANdesc scheduler parameters

Attribute Name
Availability
Value
Values
Description
Type
The default value is
written in bold
Maximum Count of
Only if the periodic Integer
5
The maximum number of items
Scheduled Items
data reading
1..255
that are sent periodically.
service is available
You can only request at most this
in the ECU
number of periodic DIDs,
configuration.
independently per scheduling rate.

Example:
2013, Vector Informatik GmbH
Version: 3.07.00
40 / 164
based on template version 5.1.0

Technical Reference CANdesc
Attribute Name
Availability
Value
Values
Description
Type
The default value is
written in bold
If set up 5 items for scheduling,
CANdesc will be able to schedule
at most 5 items at fast, 5 items at
slow and 5 items at medium rate.

Note: If the scheduler size exceeds
the total number of available
periodic DIDs, CANdesc will
automatically reduce the size to
the lowest value.
Fast/Medium/Slow
Only if the periodic Integer
OEM
Specifies the timings of each
Scheduling Rate
data reading
dependent
scheduling rate that the ECU
[ms]
service is available
1..65535
supports.
in the ECU
configuration.

2013, Vector Informatik GmbH
Version: 3.07.00
41 / 164
based on template version 5.1.0

Technical Reference CANdesc
7  CANdescBasic Configuration in GENy
As  already  stated  in  6  CANdesc  Configuration  in  GENy  since  version  6.00.00,  the
CANdesc  configuration  in  GENy  has  been  changed.  Both  CANdesc  and  CANdescBasic
variants  share  the  same  GUI  and  settings  representation  in  GENy.  Due  to  the  reduced
feature  set  in  CANdescBasic,  its  GENy  GUI  provides  you  correspondingly  a  reduced
configuration option set, covering all of the CANdescBasic requirements.
7.1
Global CANdescBasic Settings
CANdescBasic shares the same global settings as the CANdesc variant (refer to chapter
6.2.1 Global CANdesc Settings).

Info
CANdescBasic does not support any of the multi identity modes!

7.2
Service Specific Settings
In CANdescBasic, you don’t have any more an external diagnostic specification document
that  shall  be  imported  (like  a  CDD  file).  In  your  software  delivery,  there  is  already  a
prepared diagnostic configuration template that fulfills the concrete OEM and its diagnostic
protocol requirements.

Info
In CANdescBasic versions, prior 6.00.00, it was possible to import information, out of a
  CDD file, whether a service Id is supported or not-supported and any new sessions. In
CANdesc 6.00.00 and newer this feature is temporarily disabled, but you still can
manually configure these changes.

Since CANdescBasic provides only a Sid view over the diagnostic services, its service specific configuration is performed
primarily within the service overview grid in GENy (refer to chapter 0
Service Specific Settings

CANdescBasic  also  provides  a  built  in  support  for  some  of  the  diagnostic  services  like
CANdesc,  but  its scope is reduced (due to lack  of  enough service definition information)
only  to  the  most  important  for  diagnostic  communication  services  (e.g.
DiagnosticSessionControl, TesterPresent, etc.). You will recognize these services in GENy
as described in chapter 6.2.2.2 Predefined (implemented) Services in CANdesc.

2013, Vector Informatik GmbH
Version: 3.07.00
42 / 164
based on template version 5.1.0

Technical Reference CANdesc
7.3
Timing Settings
The configuration aspect of the CANdescBasic timings settings is the same as described
in 6.2.3 Timing Settings, with the difference, that here there is no CDD file but a predefined
template.

7.4
Diagnostic State Configuration
CANdescBasic has a built in support only for the diagnostic session states. All other states
like SecurityAccess and ECU specific service execution conditions shall be implemented
by the application.
The supplied CANdescBasic template already includes all mandatory session, specified by
the concrete OEM. If some additional sessions needed, you can add them in GENy as
shown below:

Figure 7-1 CANdescBasic add a user session
2013, Vector Informatik GmbH
Version: 3.07.00
43 / 164
based on template version 5.1.0

Technical Reference CANdesc

Info
For any session added by you (user sessions), GENy automatically creates all session
  transitions, required by the concrete diagnostic protocol (e.g. UDS, KWP2000).
Examples:
        Service 0x10:
                 <AllExistingSessions>-><NewSsession>,
                 <NewSession>-><NewSession>
        Service 0x20:
                  <NewSession>-><DefaultSession>

Caution
The allowed session Ids are protocol dependent. For example: on UDS you can not
  specify user sessions with Ids greater than 0x7F. On KWP2000 any value is acceptable
for session Id.

The session Id must be a unique value among all sessions, supported by your ECU.

For the user defined session, you can any time change their name, session or completely
remove them:

Figure 7-2 CANdescBasic change user session name, id or completely delete user session
2013, Vector Informatik GmbH
Version: 3.07.00
44 / 164
based on template version 5.1.0

Technical Reference CANdesc
Once a user session has been added, you can configure for each service whether it shall
be supported or not in the new session. You can do this configuration either on the service
overview grid, or if there are some service that have sub-services, for each sub-service.
The pictures below show each of the service level configuration views.

Figure 7-3 CANdescBasic session configuration at service overview

Figure 7-4 CANdescBasic session configuration at service Id level
2013, Vector Informatik GmbH
Version: 3.07.00
45 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 7-5 CANdescBasic session configuration at sub-service level

2013, Vector Informatik GmbH
Version: 3.07.00
46 / 164
based on template version 5.1.0

Technical Reference CANdesc
8  Multi Identity Support
CANdesc allows you to use multiple diagnostic configuration sets – a use case where the
ECU  always  communicates  over  the  same  connection,  but  shall  implement  different
functionality depending on some hardware (jumper) setting.
All supported configuration sets are described in the following chapters.

Info
Please note:
  The multi identity feature of CANdesc is:
-
firstly supported in CANdesc 6.00.00;
-
not supported at all in the CANdescBasic variant.

8.1
Single Identity Mode
CANdesc  has  a  static  configuration  set  –  once  all  services  and  communication
connections are  configured,  and  the  program  code  is flashed  into  the  ECU  there  are  no
more configuration changes possible.
8.1.1.1
Configuration in CANdela
You  need  just  to  prepare  the  corresponding  CDD  variant  for  your  ECU  configuration  in
CANdelaStudio.
8.1.1.2
Configuration in GENy
Import the CDD file and the corresponding variant in GENy (refer to chapter 6.2 Step Two
– ECU Diagnostic Configuration in GENy for details).

8.2
VSG Mode
The VSG mode is a special multi identity mode, which has the following characteristics:
  Allows  to  support  multiple  diagnostic  configuration  variants  –  each  variant  reflects  a
VSG from the imported CDD file, and additionally there is a base variant that contains
all services that does not belong to any VSG.
  One  or  several  configuration  variants  can  be  simultaneously  activated  during  the  ECU
initialization. The base variant is always active.

2013, Vector Informatik GmbH
Version: 3.07.00
47 / 164
based on template version 5.1.0

Technical Reference CANdesc
CANdesc
APPL


CANdesc
CANdesc
DIAG CFG

TP

Figure 8-1 CANdesc multi identity mode
CANdesc  will  be  initialized  with  the  base  variant  at  ECU  start  up  sequence.  If  required,
additional  variant(s)  can  be  activated  by  the  application  (please  refer  to  chapter  12.6.2
Multi Variant Configuration Functions for more information about the variant initialization).

8.2.1
Implementation Limitations
In  order  to  generate  the  correct  NRC  for  a  requested  service  Id  (e.g.  0x7F
(ServiceNotSupprtedInActiveSession),  CANdesc  considers  all  of  its  sub-services
diagnostic  session  specific  execution  precondition  and  calculates  a  diagnostic  session
filter for the SID. In case of a multi-identity such a calculation shall be made for all of the
diagnostic configuration variants, which will cost a lot of ROM resources.

In  order  to  keep  CANdesc  ROM  resources  as  low  as  possible  the  service  Id  specific
session  filtering  is  created  considering  the  superset  of  all  sub-services  it  contains,
independently of their configuration affiliation. Depending on the active configuration set in
the ECU, this limitation can lead to the following effect:
A requested service will be  responded with the NRC 0x12 (SubfunctionNotSupported) or
0x31(requestOutOfRange),  depending  on  if  it  has  a  sub-function  or  not,  instead  of  the
NRC 0x7F. Such a configuration could be for example:
Service 0x22 (ReadDataByIdentifier) supports only two DIDs:
0xF100 - supported only in the default diagnostic sessions and available only in variant 1;
0xF101 – supported only in a non-default session and available only in variant 2.
CANdesc  will  summarize  in  this  case,  that  service  0x22  is  allowed  in  any  diagnostic
session since there is at least one DID supported in at least one of each session.
Now  let’s  assume  the  ECU  is  powered  up  with  active  variant  2.  If  the  client  sends  a
request  0x22 0xF100 while in  the default diagnostic session,  CANdesc will respond with
2013, Vector Informatik GmbH
Version: 3.07.00
48 / 164
based on template version 5.1.0

Technical Reference CANdesc
the  NRC  0x31  (DID  not  supported),  instead  of  the  0x7F  (none  of  the  DIDs  in  the  active
configuration is executable in the default session -> the service Id itself is not executable in
the session -> NRC 0x7F would be expected).

8.2.2
Configuration in CANdela
  If multiple diagnostic configuration sets shall be selectable in CANdesc, you will need a
CDD with several VSGs where each describes a diagnostic configuration set.

Caution
CANdesc supports the multiple diagnostic configurations only on service/sub-service
  availability level. Therefore the following limitations must be considered while creating
the separate CDD files resp. CANdela variants for CANdesc:
  A service can be completely deactivated within a VSG;
  A sub-service (e.g. DID, sub-function, etc.) can be completely deactivated within a
VSG;
  If a service exist in multiple VSGs, then it must have exactly the same properties
-
Execution pre-conditions (e.g. diagnostic session, security access, etc.)
-
Support of SPRMIB
-
Addressing mode (physical/function)
-
Response behavior (response on physical/function request)
  If a sub-service exist in multiple VSGs, then it must have exactly the same
properties
-
Execution pre-conditions (e.g. diagnostic session, security access, etc.),
resp. trigger of state transitions.
-
Addressing mode (physical/function)
-
Response behavior (response on physical/function request)
-
Protocol information semantic (sub-function, identifier, etc.)
-
Request resp. response content must be identical – same data
structure, data types, and constant value (if any available)
  Service 0x31 (RoutineControlByIdentifier) specifics
-
The multi-identity varying is allowed only on RID level. If a RID is
supported in multiple variants, then the sub-functions supported by this
RID must be the same (i.e. it is not allowed to have one variant with only
“start” sub-function and one with “start and stop” for the one and same
RID).
  Service 0x2F (IoControlByIdentifier) specifics
-
The multi-identity varying is allowed only on DID level. If a DID is
supported in multiple variants, then the control options supported by this
DID must be the same (i.e. it is not allowed to have one variant with only
“ShortTermAdjustment” and one with “ShortTerm-Adjustment and
ReturnControlToEcu” for the one and same DID).

If at least one of the above requirements is not fulfilled, the variant that violates the rule
will not be imported.

2013, Vector Informatik GmbH
Version: 3.07.00
49 / 164
based on template version 5.1.0

Technical Reference CANdesc
8.2.3
Configuration in CANdela
Please follow the steps below on how to configure VSG in CANdelaStudio.

1.  Defining all available VSGs for the concrete ECU.
In CANdelaStudio, select the Vehichle System Groups view and add all necessary VSGs
into the VSG pool.

Figure 8-2 Defining VSGs in CANdelaStudio
The  name  of  the  created  VSG  will  be  used  later  by  CANdesc  for  the  diagnostic
configuration  constants  that  the  CANdesc  application  shall  use  during  the  configuration
activation phase (refer to chapter 12.6.2 Multi Variant Configuration Functions).

Once  all  of  the  required  VSGs  are  created,  you  can  start  with  the  service  to  VSG
assignment.

2.  Service to VSG assignment
Using CANdelaStudio you can assign any diagnostic instance to none, one or multiple
VSGs. Those services that do belong to a diagnostic instance without a VSG assignment
will be considered as services of the base variant (services that are always available).
2013, Vector Informatik GmbH
Version: 3.07.00
50 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 8-3 Setting a VSG for service in CANdelaStudio
8.2.4
Configuration in GENy
In order to put GENy into VSG mode, you have to select  it on the CANdesc component
root.  Please  refer  to  the  chapter  6.2.1  Global  CANdesc  Settings  for  details  about  the
variant selection option.
Now import the CDD file, containing the VSGs in GENy as described in chapter 6.1 Step
One – Importing an ECU Diagnostic Description. That is all.

8.3
Multi Identity Mode

Multi Identy Mode is not supported by CANdesc.
2013, Vector Informatik GmbH
Version: 3.07.00
51 / 164
based on template version 5.1.0

Technical Reference CANdesc
9  Diagnostic Service Implementation Specifics
9.1
ReadDataByIdentifier (SID $22)
This service has the purpose to read some predefined data records (PID). Each PID has a
concrete data structure which is designed by CANdelaStudio.
As the standard case the request contains a single PID. This results in a single response
containing the data structure of the record.
Single PID
Sing
mode
le PID
(
mode  well kno
kn w case
ca
)
se exampl
ex
e for P
e f
ID
or P
$1
ID
2
$1 34
Tester‘s reque
Te
st:
ster‘s reque
$22 $12 $34
ECU‘s response:
ECU‘s respon
$62 $12 $34 Data bl
Da
ock

The UDS allows to request multiple PIDs in a single request. This results is also a single
response including the data structure of each requested PID.

Multip
Mul
le
tip  PID mod
PI
e exa
D mod
mple for
e exa

mple for PIDs
PID : $1234,
$1
$ABCD
$A
Tester‘s reque
Te
st:
ster‘s reque
$22 $12 $34 $AB
$A $CD
ECU‘s response:
ECU‘s respon
$62 $12 $34 Data bl
Da
ock $AB
$A $CD
Data bl
Da
ock

CANdesc will hide this multiple PID processing from the application. To do that some minor
limitations in the interface has to be made (see chapter 9.1.2 Single PID mode). To show
the  differences,  we  discuss  first  the  standard  case.  In  the  standard  case  there  is  no
multiple  PID  processing  possible.  The  second  chapter  (9.1.3  Multiple  PID  mode)  is
showing the multiple PID processing.
Which mode is used depends on the configuration (typically the OEM).

2013, Vector Informatik GmbH
Version: 3.07.00
52 / 164
based on template version 5.1.0

Technical Reference CANdesc
9.1.1
Limitations of the service
Session management
This service contains no sub-function identifier which means the global state group
“session” may not be selected as a “relevant group” for any instance of this service. If
there is a need for a PID to be rejected under a certain session, all PIDs must follow this
rule and be specified to be rejected for this session. As a result the whole SID $22 will be
rejected for this session. This behavior is harmonized with the UDS protocol specification,
which allows service identifiers to be rejected in a session but no parameter identifiers.

2013, Vector Informatik GmbH
Version: 3.07.00
53 / 164
based on template version 5.1.0

Technical Reference CANdesc
9.1.2
Single PID mode
The Single PID mode is configured automatically, if the number of PIDs that can be
requested at the same time, is limited to one PID. If more than one PID is requested, the
request will be rejected with ‘RequestOutOfRange’ (NRC $31).
If the multiple PID mode of CANdesc is deactivated, the service $22 will be executed and
processed like any other diagnostic service without any additional specifics or limitations.
9.1.2.1
Sending a positive response using linear buffer access
Tester
CANdesc
Application
Check all states if the
SId[$22],Pid[$xxxx]
"read PID" service can
StateGroupsCheck for Pid
be executed.
If available execute the pre-handler and
ApplDescPreReadDataById_xxxx
check if the application rejected the service.
ApplDescReadDataById_xxxx
Execute the main-handler
Write data (pMsgContext->resData)
to fill the response data.
Set total response data length
(pMsgContext->resDataLen = N)
DescProcessingDone()
RSid[$62], PID[$xxxx], Data[N]
The positive response transmission will be
initiated after the DescProcessingDone
gets called.

Figure 9-1: Linearly written positive response on single PID request

2013, Vector Informatik GmbH
Version: 3.07.00
54 / 164
based on template version 5.1.0

Technical Reference CANdesc
9.1.2.2
Sending a positive response using ring buffer access
Tester
CANdesc
Application
Check all states if the
SId[$22],Pid[$xxxx]
"read PID" service may
StateGroupsCheck for Pid
be executed.
If available execute the pre-handler and check if
ApplDescPreReadDataById_xxxx
the application rejected the service.
Execute the main-handler
ApplDescReadDataById_xxxx
to fill the response data.
Set total response data length
(pMsgContext->resDataLen = N)
DescRingBufferStart()
Write data (DescRingBufferWrite())
FF (RSid[$62], PID[$xxxx], Data[3])
The positive response transmission will be initiated after
the DescRingBufferStart gets called and there are at
least 7 bytes ready to be transmitted (i.e. 3 data bytes).
Write data (DescRingBufferWrite())
CF(Data[N-3])

Figure 9-2: “On the fly” response data writing.

2013, Vector Informatik GmbH
Version: 3.07.00
55 / 164
based on template version 5.1.0

Technical Reference CANdesc
9.1.2.3
Sending a negative response
Due to the fact that the negative response handling has changed in the multiple PID mode,
we  recommend  to  do  the  same  handling  in  the  Single  PID  mode,  too.  Please  refer  the
chapter 9.1.3.2 “Ring buffer active configuration” for the recommended negative response
handling.
Tester
CANdesc
Application
Check all states if the
SId[$22],Pid[$xxxx]
"read PID" service can
StateGroupsCheck for Pid
be executed.
If available execute the pre-handler and
check if the application rejected the service.
ApplDescPreReadDataById_xxxx
Execute the main-handler
ApplDescReadDataById_xxxx
to fill the response data.
DescSetNegresponse(errorCode)
The main-handler still can
register any errors.
DescProcessingDone()
RSid[$7F], Sid[$22], ErrorCode[errorCode]
The negative response transmission will be
initiated after the DescProcessingDone
gets called.

Figure 9-3: Negative response on single PID
9.1.3
Multiple PID mode
The  Multiple  PID  mode  is  configured  automatically  if  the  number  of  PIDs,  that  can  be
requested at the same time, is greater than one. If more than this predetermined number
of PIDs is requested, the request will be rejected with ‘RequestOutOfRange’ (NRC $31).
In  this  configuration  some  minor  limitations  must  be  taken  into  account  while  using  the
CANdesc interfaces.
For the service “ReadDataByIdentifier” the ring-buffer feature can be used. Depending on
the usage of this feature, there are two main use cases for the multiple PID mode.:

2013, Vector Informatik GmbH
Version: 3.07.00
56 / 164
based on template version 5.1.0

Technical Reference CANdesc
9.1.3.1
Pure linear buffer configuration
The ring-buffer feature is deactivated in general.
If the system doesn’t use any ring buffer access for filling the response, the PID pipeline is
still quite simple and therefore with less limitations to the CANdesc API usage and
application performance.
9.1.3.1.1
Sending a positive response
Tester
CANdesc
Application
SId[$22],Pid0[$xxxx],Pid1[$yyyy]
Before the requested PIDs will be processed, check
StateGroupsCheck for PID0[$xxxx]
all PIDs':
1. States (may be executed)
2. Pre-handlers.
ApplDescPreReadDataById_xxxx
StateGroupsCheck for PID1[$yyyy]
ApplDescPreReadDataById_yyyy
ApplDescReadDataById_xxxx
Execute the first PID's
main-handler to fill the response
data.
Write data (pMsgContext->resData)
Set total response data length
(pMsgContext->resDataLen = N)
Once the service execution of
the current PID has been
accomplished...
DescProcessingDone()
...execute the next
queued one.
ApplDescReadDataById_yyyy
Write data (pMsgContext->resData)
Set total response data length
(pMsgContext->resDataLen = M)
DescProcessingDone()
FF (RSid[$62], PID0[$xxxx], Data[3])
CF[i](Data[N-3],PID1[$yyyy]Data[M)
The positive response transmission will be
initiated after all PIDs have called
DescProcessingDone and all the data ...

Figure 9-4: Linearly written positive response on multiple PIDs (global ring buffer option is off)

2013, Vector Informatik GmbH
Version: 3.07.00
57 / 164
based on template version 5.1.0

Technical Reference CANdesc
9.1.3.1.2
Sending a negative response
This example  depicts the case where  from two requested PIDs the first  one may not  be
accessible and rejects the service execution.
Tester
CANdesc
Application
Before requested PIDs will be processed check all
SId[$22],Pid0[$xxxx],Pid1[$yyyy]
PIDs':
StateGroupsCheck for PID0[$xxxx]
1. States (may be executed)
2. Pre-handlers.
ApplDescPreReadDataById_xxxx
StateGroupsCheck for PID1[$yyyy]
ApplDescPreReadDataById_yyyy
ApplDescReadDataById_xxxx
Execute the first PID's
main-handler to fill the response
data.
DescSetNegResponse(errorCode)
Once the service execution of
the current PID has been
accomplished...
DescProcessingDone()
Skip further processing
of the list
RSid[$7F], Sid[$22], ErrorCode[errorCode]
The second PID's
Main-handler will not be
executed.
...stops the further
processing a...

Figure 9-5: Negative response on multiple PIDs (global ring buffer option is off)
9.1.3.2
Ring buffer active configuration
Attention: The Ring-Buffer in ‘Multiple PID‘ services can be first-time used since CANdesc
version 2.13.00
Different concepts for the buffer handling were discussed while development. Two
solutions with different pros and cons are discussed here:

  Multiple buffer
Normally  each  service  handler  (MainHandler  routine)  has  the  whole  diagnostic  buffer
available (apart from the protocol header bytes hidden by CANdesc). Based on this logic
the service $22 using PID pipelining has the same tasks as the normal service processor:
executing  a  PID  handler  and  provide  him  the  whole  diagnostic  buffer  for  response  data.
This will hide the whole process and makes the application’s life easier (no exceptions for
the implementation). To realize this concept means to provide a separate diagnostic buffer
for each PID which size is the same as the main one (configured by GENtool). This is a
fast and quite simple solution but requires too much RAM to be reserved for only the case
that  sometimes  the  testers  would  like  to  use  the  maximum  capacity  of  the  ECU    (i.e.
requests as many PIDs as possible for this ECU in a single request).
Pros: less ROM usage
2013, Vector Informatik GmbH
Version: 3.07.00
58 / 164
based on template version 5.1.0

Technical Reference CANdesc
Cons: very high RAM usage

  virtual multiple buffer
This concept  is more generically designed and will not  have additional ROM overhead if
the pipeline size  will be increased. An intelligent  buffer concept  gives the application the
whole size of the buffer for each MainHandler call.
Once the whole data for the current PID has been written, the data supplement will stop
(because the next PID handler will not be called). The transmission in the transport layer is
started  and  some  time  later  it  runs  into  buffer  under-run. This  ‘signal’  is  used  to  call  the
next PID MainHandler. This MainHandler has to provide his data very quick. Otherwise the
response transmission will stop (due to a continuously buffer under-run).
Pros:  less RAM usage (practically independent of the maximum list size).
Cons:  moderate  ROM  overhead  /  the  response  data  must  be  composed  very
quickly.
The virtual multiple buffer concept is the implemented solution. The application can choose
for each PID separately to write the data linearly or by using the ring buffer.
performance requirements
The application has performance requirements:
-  If  linear  access  has  been  chosen,  the  whole  response  data  of  each  MainHandler
must  be  filled  within  the  lower  duration  of  the  P2  time  and  the  TP  confirmation
timeout.  Normally  the  P2  time  is  shorter  than  the  transport  layers  confirmation
timeout  so  just  take  into  account  that  each  Main-Handler  must  be  able  to  fill  its
response data within a time far shorter than the P2 time.
-  If  ring  buffer  access  has  been  chosen,  the  application  has  to  call    the
“DescRingBufferWrite” fast enough to keep TP from confirmation timeout.
Negative response on PID
The  negative  response  handling  is  changed  in  the  multiple  PID  mode!  This  affects  all
protocol-services  with  a  activated  ‘May  be  combined’  property.  The  UDS  specification
encloses  only  the  SIDs:  $22  and  $2A.  For  all  other  services  the  negative  response
handling is not changed!
If  the  application has  to  reject  a  request  (e.g.  ignition  key  check)  it  has  to do  that  in  the
PreHandler.  The  application  is  not  allowed  to  call  “DescSetNegResponse()”  to  send  a
negative response in any MainHandler.
This limitation is based on the concept to check all reject conditions in PreHandlers before
starting the transmission. This is necessary because after CANdesc has executed the first
MainHandler (which starts the positive response transmission) there will  be no chance to
send a negative response.
The  usage  of  the  concept:  CANdesc  starts  to  call  all  PreHandlers  of  this  multiple  PID
request.  If  no  negative  response  is  set,  CANdesc  will  start  to  call  the  corresponding
MainHandlers. Within the first call of DescProcessingDone() the transmission is initiated.
Note (for version 3.02.00 of CANdesc and above):
2013, Vector Informatik GmbH
Version: 3.07.00
59 / 164
based on template version 5.1.0

Technical Reference CANdesc
In case the application sets an error code during the main-handler execution in non-debug
(released) version of the component, depending on the situation will lead to:
For service $22:
-  First DID of the list main-handler: sending a negative response to service $22;
-  Second or any of the succeeding DIDs in the list: transmission interruption.
For service $2A:
-  Ignoring the scheduled response.

9.1.3.2.1
Sending a positive response
Tester
CANdesc
Application
SId[$22],Pid0[$xxxx],Pid1[$yyyy]
Before requested PIDs will be processed check all
StateGroupsCheck for PID0[$xxxx]
PIDs':
1. States (may be executed)
ApplDescPreReadDataById_xxxx
2. Pre-handlers.
StateGroupsCheck for PID1[$yyyy]
ApplDescPreReadDataById_yyyy
ApplDescReadDataById_xxxx
Execute the first PID's
main-handler to fill the response
data.
Write data (pMsgContext->resData)
Set total response data length
(pMsgContext->resDataLen = N)
DescProcessingDone()
FF (RSid[$62], PID0[$xxxx], Data[3])
With the first called
DescProcessingDone() starts
the response transmission.
CF[i](Data[N-3])
Once the whole data of  the current PID has
been sent the next PID main-handler will be
ApplDescReadDataById_yyyy
called to supply the response data.
Write data (pMsgContext->resData)
CF[j](Data[N-k],PID1[$yyyy]Data[m])
Set total response data length
(pMsgContext->resDataLen = M)
DescProcessingDone()
CF[l](Data[M-m])

2013, Vector Informatik GmbH
Version: 3.07.00
60 / 164
based on template version 5.1.0

Technical Reference CANdesc
Figure 9-6: Linearly written response data on multiple PIDs (global ring buffer option is on)

9.1.3.2.2
Sending a negative response
Tester
CANdesc
Application
SId[$22],Pid0[$xxxx],Pid1[$yyyy]
Before requested PIDs will be processed check all
StateGroupsCheck for PID0[$xxxx]
PIDs':
1. States (may be executed)
2. Pre-handlers.
ApplDescPreReadDataById_xxxx
StateGroupsCheck for PID1[$yyyy]
ApplDescPreReadDataById_yyyy
DescSetNegResponse(errorCode)
If error has been set - no
main-hadnler processing will
follow.
RSid[$7F], Sid[$22], ErrorCode[errorCode]
Send immediately
negative response.

Figure 9-7: Negative response on multiple PIDs (global ring buffer option is on)

2013, Vector Informatik GmbH
Version: 3.07.00
61 / 164
based on template version 5.1.0

Technical Reference CANdesc
9.1.3.2.3
PostHandler execution rule
All  PostHandlers  are  executed  after  the  finished  response  transmission  (like  a  normal
PostHandler).
Independent  of  the  ring-buffer  option  setting  (enabled  or  disabled),  the  execution  of  the
service  $22  PostHandler(s)  has  the  following  rule  which  has  to  be  taken  into  account:
calling the Post-Handler of a specific PID means: either the PreHandler of this PID
has been previously called or its MainHandler.
The following sequence chart depicts this:
Tester
CANdesc
Application
SId[$22],Pid0[$xxxx],Pid1[$yyyy],
Before requested PIDs will be processted check all
Pid2[$zzzz]
StateGroupsCheck for PID0[$xxxx]
PIDs':
1. States (may be executed)
2. Pre-handlers.
ApplDescPreReadDataById_xxxx
PID0, PID1and PID2 have all
post-handlers configured.
StateGroupsCheck for PID1[$yyyy]
PID1 has no pre-handler
cofigured.
StateGroupsCheck for PID2[$zzzz]
ApplDescPreReadDataById_zzzz
DescSetNegResponse(errorCode)
If error has been set - no
main-hadnler processing will
follow.
RSid[$7F], Sid[$22], ErrorCode[errorCode]
Send immediately
negative response.
ApplDescPostReadDataById_xxxx
PID1 has a post-handler but since
the application doesn't know about
its reception - no post-handler will
ApplDescPostReadDataById_zzzz
be called.

Figure 9-8: Post-Handler execution sequence.

9.2
DynamicallyDefineDataIdentifier (SID $2C) (UDS)
The DynamicallyDefineDataIdentifier service allows the client (tester) to dynamically define
in a server (ECU) a data identifier that can be read via the ReadDataByIdentifier service at
a later time.
The intention of  this service  is to provide the client  with the ability to group one or more
data  elements  into  a  data  superset  that  can  be  requested  en  masse  via  the
2013, Vector Informatik GmbH
Version: 3.07.00
62 / 164
based on template version 5.1.0

Technical Reference CANdesc
ReadDataByIdentifier  or  ReadDataByPeriodicIdentifier  service.  The  data  elements  to  be
grouped together can either be referenced by:
  a source data identifier, a position and size or,
  a memory address and a memory length, or,
  a combination of the two methods listed above using multiple requests to define the
single  data  element.  The  dynamically  defined  dataIdentifier  will  then  contain  a
concatenation of the data parameter definitions.

The  definition  of  the  dynamically  defined  data  identifier  can  either  be  done  via  a  single
request  message  or  via  multiple  request  messages.  This  allows  for  the  definition  of  a
single  data  element  referencing  source  identifier(s)  and  memory  addresses.  The  server
has  to  concatenate  the  definitions  for  the  single  data  element.  A  redefinition  of  a
dynamically defined data identifier can be achieved by clearing the current definition and
start over with the new definition.
At last the dynamically defined data identifier consists of a list of (non-dynamically) defined
data identifiers and memory area ranges that can be used in any combination.
For more information, see /ISO 14229-1/

9.2.1
Feature set
These are the supported subfunctions for service $2C (DynamicallyDefineDataIdentifier):
Subfunction Name
Hex Value
defineByIdentifier
01
defineByMemoryAddress
02
clearDynamicallyDefinedDataIdentifier
03

9.2.2
API Functions
The reception of a Service $2C request will either delete a DynamicDataIdentifier (DDID)
or  PeriodicDataIdentifier  (PDID)  by  subfunction  $03  or  build  a  DDID/PDID  by  (several
times) using subfunction $01 and/or $02.
For  subfunction  $02  (defineByMemoryAddress)  there  is  a  new  application  callback
function (see chapter 12.6.13 “DynamicallyDefineDataIdentifier  ($2C) (UDS) functions”). It
allows the application to permit or deny the extension of the DDID/PDID by accessing the
defined memory range. The callback function must check, if the requested memory area is
readable  for  the  external Tester  and  if  the  current  security  state  of  the  ECU  permits  the
extension  of  the  DDID/PDID.  See  chapter  12.6.13.2  for  the  full  set  of  checks  to  be
executed.
Please  note  that  later,  when  reading  the  DDID  by  using  service  $22
(ReadDataByIdentifier),  further  (security)  checks  for  each  element  of  the  DDID’s  list  are
executed  to  verify  that  e.g.  the  (then  active)  security  state  permits  the  reading  of  the
memory area or DID. These checks (of  Service  $22 and $23) are done in  the traditional
sequence of Pre-, Main- and PostHandler.
2013, Vector Informatik GmbH
Version: 3.07.00
63 / 164
based on template version 5.1.0

Technical Reference CANdesc
The  reception  of  a  Service  $22  request  starts  a  new  context  in  CANdesc.  Typically  the
requested data can not be asked from the application by using one single callback function
but  must  be  constructed  sequentially  by  collecting  data  for  each  part  of  the  DDID’s
definition list:
  A  requested  basic  source  data  identifier  (DID)  is  asked  of  the  application  by  the
respective callback (as for Service $22 request), the result data is stripped down to
the defined position and size
  A memory address is read by its defined function (typically the same as used for a
Service $23 request) and the defined ‘size’ bytes are collected.
As  recommended  from  /ISO  14229-1/  to  prevent  data  consistency  problems  a  recursive
definition of DDIDs is NOT supported.
The Service $22 response data is collected by splitting the service request into these basic
tasks,  then  running  the  well  known  internal  functions  that  were  defined  for  them,  collect
their  results  and build  up  the  Service  $22  response. Therefore,  each of  the above  tasks
starts  a  new  context,  executes  the  defined  Pre-,  Main-  and  Post-Handler  where
Application-Callbacks get data, delivers its result and finally ends its context.
The recursive evaluation of DDIDs enforces the usage of MultiContext mode.
We would like to point out that the described operating sequence above is completely run
within  CANdesc  and  totally  transparent  for  the  application  except  for  the  additional API
callback function. Using Service $2C or $2A switches CANdesc to MultiContext mode – if
your application isn’t prepared to support MultiContext mode (by using the defined macros)
you’ll get compiler errors about inconsistent argument lists.

9.2.3
Sequence Charts
Service $2C – Define a DDID
The  following  picture  exemplifies  the  sequence  of  defining  a  DDID  by  several  call  of
Service DynamicallyDefineDataIdentifier ($2C).
In  our  example  the  first  Service  $2C  request  defines  the  DDID  $F300  to  return  two
independent
memory
areas.
For
both
areas
the
callback
function
ApplDescCheckDynDidMemoryArea()  is  triggered  and  in  this  example  the  application
permits both accesses.
The consecutive Service $2C request extends the DDID $F300 by (some fragments of) the
existing DID $F010. As the here executed PreHandler does not set a Negative Response
Code,  CANdesc  considers  the  extension  of  the  DDID  valid  and  enlarges  the  DDID
definition.
A third Service $2C request tries to extend the DDID $F300 once more by another memory
area. In our example the call fails, as the specified memory area ($0000) is not valid for
this  ECU. The  service  is  negative  responded  and  the  previous  DDID  specification  is  left
untouched.
2013, Vector Informatik GmbH
Version: 3.07.00
64 / 164
based on template version 5.1.0

Technical Reference CANdesc
sd Define a new DDID v ia Serv ice $2C request
Tester
CANdesc
Application
Define DDID $F300 as
$2C 02 F300 12 ABCD04 FEDC05
4-byte memory block at
address $ABCD and
5-byte block at $FEDC
check for
ApplDescCheckDynDidMemoryArea
Addr. $ABCD,
memBlockOk
Size $04
check for
ApplDescCheckDynDidMemoryArea
Addr. $FEDC,
Size $05
memBlockOk
PosResponse ($6C 02)
$2C 01 F300 F010 ...
Extend the DDID $F300
PreHandler for DID F010
by using
existing DID $F010
No Neg. RCode
set --> success
PosResponse ($6C 01)
$2C 02 F300 12 000004
Further extention fails
due invalid address
value ($0000) in
ApplDescCheckDynDidMemoryArea
request
check for Addr.
memBlockInvAddress
$0000 fails!
NegResponse ($7F 2C 31)

Figure 9-9: Defining a DDID.

2013, Vector Informatik GmbH
Version: 3.07.00
65 / 164
based on template version 5.1.0

Technical Reference CANdesc
Service $22 – Read a DDID
The  above  defined  DDID  is  now  read  by  Service  ReadDataByIdentifier  ($22).  Within
CANdesc  the  DDID  is  disassembled  into  its  elements:  One  (virtual)  request  for  the  first
memory range, another request for the second memory range and finally a request for the
predefined DID $F010.
sd Read defined DDID v ia Serv ice $22 request
Tester
CANdesc
Application
Read DDID $F300 that
$22 F300
was defined as:
    Addr ABCD, Size 04
$23 12 ABCD04
+ Addr FEDC, Size 05
+ DID F010, Pos .., Size ..
execute virtual
$23 request
PreHandler
MainHandler
PostHandler
$23 12 FEDC05
execute virtual
$23 request
PreHandler
MainHandler
PostHandler
$22 F010
execute virtual
$22 request ...
PreHandler
MainHandler
PostHandler
... and cut out the
required bytes
from the result
concatenate
the results
PosResponse ($62)

Figure 9-10: Reading a DDID.
Between  CANdesc  and  the  application  the  sequence  looks  same  as  if  the  tester  would
have  sent  3  requests:  (1)  ReadMemoryByAddress  ($23)  on  first  address  range,  (2)
ReadMemoryByAddress  ($23)  on  second  address  range,  and  finally  (3)
ReadDataByIdentifier ($22) on the DID $F010. Keep in mind: this is just a picture for the
succession of events/API-calls - these requests are not real, the messages are never seen
on the bus, the internal sequence is actually slightly different but for the application it looks
the same!
2013, Vector Informatik GmbH
Version: 3.07.00
66 / 164
based on template version 5.1.0

Technical Reference CANdesc
9.3
Read/Write Memory by Address (SID $23/$3D) (UDS)

Caution
This chapter does not apply to all ECU configurations. Only in special cases the
  memory access support will be available!

The  services  $23  (ReadMemoryByAddress)  and  $3D  (WriteMemoryByAddress)  are
handled uniformly in CANdesc.
Basically the memory by address requests look like this:
$23
FID
address
length
$3D
FID
address
length
data

The  application  need  not  concern  itself  with  the  details  how  the  address  and  length  are
formatted.  If  a  valid  FID  is  recognized,  CANdesc  will  extract  the  address  and  length
information from the request and call an appropriate application callback.
See also:
ApplDescReadMemoryByAddress (12.6.14.1)
ApplDescWriteMemoryByAddress (12.6.14.2)
9.3.1
Tasks performed by CANdesc
To a certain degree CANdesc validates the request.
The basic format checks and service level state validation – this means e.g. security and
session validation – are performed before calling the application callback.
Service  level  state  validation  means  that  the  request  will  be  denied  if  all  diagnostic
instances of service $23 or $3D are not allowed in the current state.
In  case  of  WriteMemoryByAddress  the  application  has  linear  access  to  the  whole  data
block to write.
9.3.2
Task to be performed by the Application
CANdesc currently does not provide state validation on format identifier level or memory
address / memory block level.
This  means,  that for example  different  memory  addresses  shall  require  different  security
levels, the application will have to verify that the ECU currently is in an appropriate state to
access the requested memory area.
9.3.3
Repeated service calls
The repeated service call feature is available for the memory access callbacks.
Because  they  have  a  different  prototype  than  a  normal  main  handler,  the  usual  API
‘DescStartRepeatedServiceCall (see  12.6.8.1)’ can not  be used with the memory access
callbacks.
2013, Vector Informatik GmbH
Version: 3.07.00
67 / 164
based on template version 5.1.0

Technical Reference CANdesc
Instead, a new API call ‘DescStartMemByAddrRepeatedCall (see 12.6.8.2)’ has been
added.
To abort the repeated service call, use the usual API.
2013, Vector Informatik GmbH
Version: 3.07.00
68 / 164
based on template version 5.1.0

Technical Reference CANdesc
10 Generic Processing Notifications
If CANdesc UDS2012 is used, the feature “Generic Processing Notifications” is provided.
Upon activating this feature, CANdesc will notify the application when the processing of a
request starts and ends. Thereby, the notification mechanism is two-staged. On each
stage there are two application callbacks, one indication and one confirmation callback.
On the first stage “Manufacturer Notification Support”, CANdesc will notify the application
right before the processing of a fully received request starts, by calling the function
ApplDescManufacturerIndication(). When the processing of the request has been finished,
the response has been sent and all PostHandlers were called, CANdesc notifies the
application again by calling the function ApplDescManufacturerConfirmation().
The application callbacks of the second stage “Supplier Notification Support” are named
accordingly ApplDescSupplierIndication() and ApplDescSupplierConfirmation(). The
indication callback is called by CANdesc after it has verified that the requested service is
supported in the active session, security state and user states. The confirmation callback
is also called after the response has been sent, and all PostHandlers were called, but right
before the call to ApplDescManufacturerConfirmation(). Thus, the manufacturer and
supplier callbacks are called in a nested way. Figure 3-1 illustrates the order of the
notification callbacks related to the processing of a service request.
Application
Prehandler
Manufacturer
Mainhandler
Supplier
Indication
Confirmation
Posthandler
Supplier
Manufacturer
Indication
Confirmation
CANdesc
Check SID
… Check Format
Check Session/Security
t
Request
positive Response

negative Response
Tester

Figure 10-1 Call order of Manufacturer- and Supplier-Notficiation

2013, Vector Informatik GmbH
Version: 3.07.00
69 / 164
based on template version 5.1.0

Technical Reference CANdesc
10.1  Using dynamically defined data Identifier
The  Service  DynamicallyDefineDataIdentifier  allows  the  definition  of  data  identifiers  with
other  data  identifiers  or  memory  areas.  These  DDIDs  can  be  read  via  service
ReadDataByIdentifier. When reading a DDID, for each source element a virtual request is
processed  by  CANdesc  to  get  the  information  for  this  source  element  from  the
application(see  chapter  9.2).  Because  CANdesc  processes  the  virtual  requests  equal  to
normal  requests,  the  notification  functions  will  not  only  be  called  for  the  $22  request
containing  the  DDID,  but  also  for  each  virtual  request.  The  application  has  to  consider
these additional calls, in case a DDID is requested.
Figure 10-2 shows an example of reading a DDID with service $22.
sd Read defined DDID v ia Serv ice $22 request w ith Generic Processing Notifications
Tester
CANdesc
Application
Read DDID $F300 that
$22 F300()
was defined as:
    Addr ABCD, Size 04
Manufacturer Indication()
+ Addr FEDC, Size 05
Confirmation calls
+ DID F010, Pos .., Size ..
Supplier Indication()
execute virtual
for the request to
$23 request
read the DDID
$23 12 ABCD04()
Manufacturer Indication()
Nested confirmation
Supplier Indication()
calls for the virtual
request
PreHandler()
MainHandler()
PostHandler()
Supplier Confirmation()
Manufacturer Confirmation()
...
Process further
virtual requests
...
PosResponse ($62)
PostHandler()
Supplier Confirmation()
Manufacturer Confirmation()

Figure 10-2 Read out a DDID with generic processing notifications
2013, Vector Informatik GmbH
Version: 3.07.00
70 / 164
based on template version 5.1.0

Technical Reference CANdesc
11  Busy Repeat Responder Support (UDS2006 and UDS2012)
Busy  Repeat  Responder  is  a  feature,  that  allowes  CANdesc  to  respond  to  incoming
requests  during  the  processing  of  another  request.  Such  parallel  requests  are  properly
received  and  in  the  next  task  cycle  of  CANdesc  responded  negatively  with  NRC
BusyRepeatRequest (0x21).
Figure 11-1 illustrates the functionality of the Busy Repeat Responder mechanism. During
the  processing  of  Request  1,  Requests  2 and  3 from Tester 2  are  responded negatively
with  NRC  BusyRepeatRequest.  After  the  processing  of  request  1  has  finished  and  a
positive response has been sent, Request 4 from Tester 2 can be processed properly.
sd BusyRepeatResponder
Tester 1
Tester 2
CANdesc
Request 1()
CANdesc has received a
request from Tester 1 and
starts the processing
Request 2()
Neg Response Busy()
Parallel requests from
another tester are responded
Request 3()
negatively with NRC
BusyRepeatRequest
Neg Response Busy()
Pos Response for Request 1()
After CANdesc has finished
Request 4()
the processing of the request
from Tester 1, Requests from
Tester 2 can be processed
Pos Response for Request 4()
again.

Figure 11-1  Illustration of the feature BusyRepeatResponder
Preconditions that must be fulfilled when using the feature Busy Repeat Responder:
>  The TP must be a ISO TP from Vector with TP Class “Dynamic Normal Addressing
Multi TP” or “Dynamic Normal Fixed Addressing Multi TP”
>  In the TP configuration the feature “Extended API – Overrun Reception” must be active
>  In the TP configuration the number of Rx channels and Tx Channels must be > 1
>  In case of Dynamic Normal Addressing Multi TP, a dispatcher needs to be
implemented in the application (for a detailed description see chapter 13.12)
2013, Vector Informatik GmbH
Version: 3.07.00
71 / 164
based on template version 5.1.0

Technical Reference CANdesc
Restrictions when using the feature Busy Repeat Responder:
>  Only physical parallel requests are responded negatively. Functional parallel requests
will NOT get a negative response.
11.1  Configuration in GENy
To  activate  the  feature  Busy  Repeat  Responder  use  the  setting  in  the  CANdesc
component root (refer to chapter 6.2.1 Global CANdesc Settings).
Furthermore,  the  feature  requires  additional  configuration  in  the  TP  component.  The
feature “Extended API – Overrun Reception” must be enabled. This setting is available in
the  group  “Advanced  Configuration”. To  be  able  to  receive  another  request  while  one  is
under processing, the “Number of Rx Channels” and “Number of Tx Channels” must be at
least two. The number of channels can be configured in the TP Connection Groups:

Figure 11-2 Example of the “Number of Rx(Tx) Channels” settings
In case of “Dynamic Normal Addressing Multi TP” a dispatcher needs to be implemented in
the  application.  The  description  of  the  GENy  configuration  to  integrate  the  dispatcher  is
described  in  chapter  13.12  …use  “Dynamic  Normal  Addressing  Multi  TP”  with  multiple
tester.

2013, Vector Informatik GmbH
Version: 3.07.00
72 / 164
based on template version 5.1.0

Technical Reference CANdesc
12  CANdesc API
12.1  API Categories
12.1.1  Single Context
This API category is used if no parallel processing is necessary. This is typical for the ISO
14229 specification.
12.1.2  Multiple Context (only CANdesc)
This  API  category  is  used  if  parallel  processing  is  necessary.  This  means  not  that
CANdesc  can  work  with  multiple  instances,  but  only  one  functional  request  can  be
processed parallel to a working physical request.
12.2  Data Types
The following standard data types are used in this document:
vuint8
Represents 8 bit unsigned integer value.
vsint8
Represents 8 bit signed integer value.
vuint16
Represents 16 bit unsigned integer value.
vsint16
Represents 16 bit signed integer value.
vuint32
Represents 32 bit unsigned integer value.
vsint32
Represents 32 bit signed integer value.
Table 12-1: standard data types

Additional data  types used  in  this  document  are  described  in  the corresponding function
description.
12.3  Global Variables
-
12.4  Constants
12.4.1  Component Version
The  version  of  the  CANdesc  component  consist  of  3  parts  in  the  following  format:
MM.SS.BB,
Where:
  MM is the main version of the component,
  SS is the subversion of the component,
  BB is the bug-fix version of the component.
To get the current CANdesc version, the application could use the following shared data:

2013, Vector Informatik GmbH
Version: 3.07.00
73 / 164
based on template version 5.1.0

Technical Reference CANdesc
Name
Type
Description
g_descMainVersion
BCD
Contains the main version part.
g_descSubVersion
BCD
Contains the subversion part.
g_descBugFixVersion
BCD
Contains the bug-fix version part.
Table 12-2: Version API data
Note: The version of the module is the same as the version of the generator’s DLL file.
12.5  Macros
12.5.1  Data exchange
The CANdesc provides a generic API for splitting a multi-byte (up to 4 bytes) variable to a
byte sequence with platform transparent access to each byte, and assembling a multi-byte
(up to 4 bytes) variable from a sequence of bytes.
12.5.1.1  Splitting 16 bit data
The  following  function  could  be  used  to  get  platform  independent  access  to  the
corresponding bytes of 16 bit data variable:
vuint8 DescGetHiByte(16BitData)

vuint8 DescGetLoByte(16BitData)

12.5.1.2  Splitting 32 bit data
The  following  function  could  be  used  to  get  platform  independent  access  to  the
corresponding  bytes of 32 bit data variable:
vuint8 DescGetHiHiByte(32BitData)

vuint8 DescGetHiLoByte(32BitData)

vuint8 DescGetLoHiByte(32BitData)

vuint8 DescGetLoLoByte(32BitData)

12.5.1.3  Assembling 16 bit data
The application can create the 16 bit signal from a byte stream using the following API:
uint16  DescMake16Bit(hiByte, loByte)
where the hiByte, loByte are the corresponding bytes for the returned 16 bit data.

2013, Vector Informatik GmbH
Version: 3.07.00
74 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.5.1.4  Assembling 32 bit data
The application can create the 32 bit signal from a byte stream using the following API:
uint32 DescMake32Bit(HiHiByte, HiLoByte, LoHiByte, LoLoByte)
where the HiHiByte, HiLoByte, LoHiByte, LoLoByte are the corresponding bytes for the
returned 32 bit dat
12.6  Functions
12.6.1  Administrative Functions
12.6.1.1  DescInitPowerOn()
DescInitPowerOn
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescInitPowerOn (DescInitParam initParameter)
Multi Context
void DescInitPowerOn (DescInitParam initParameter)
Parameter
initParameter
Manufacturer specific type, please refer ‘CANdesc: OEM
specifics’ document
Return code
-
-
Functional Description
PowerOn Initialization of the CANdesc.
This function has to be called once before all other functions of CANdesc after PowerOn.
Pre-conditions
Correctly initialized CAN-driver via CanInitPowerOn() and TransportLayer via
TpInitPowerOn().
Call context
Background-loop level with global disabled interrupts
Particularities and Limitations
  DescInitPowerOn (initParameter) must be called after TpInitPowerOn() was called
(please, refer the /TPMC/ documentation), otherwise the reserved diagnostic
connection will be los

2013, Vector Informatik GmbH
Version: 3.07.00
75 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.1.2  DescInit()
DescInit
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescInit (DescInitParam initParameter)
Multi Context
void DescInit (DescInitParam initParameter)
Parameter
initParameter
Manufacturer specific type, please refer ‘CANdesc Part IV:
OEM specifics’ document
Return code
-
-
Functional Description
Re-initialization of CANdesc.
This function can be called to re-initialize CANdesc (e.g. after WakeUp). All internal states
will be set to default, except the states in this initParameter (e.g. Session or
CommunicationControl).
Pre-conditions
CANdesc was once initialized via DescInitPowerOn ()
Call context
Background-loop level with global disabled

2013, Vector Informatik GmbH
Version: 3.07.00
76 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.1.3  DescTask()
DescTask
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescTask (void)
Multi Context
void DescTask (void)
Parameter
-
-
Return code
-
-
Functional Description
The function DescTask() has to be called periodically (cycle time TDescCallCycle) by the
application.
Within the context of this function the interaction with the application is performed. In
addition the monitoring of the timings is done, therefore the accuracy of the timings
depends on the call cycle and on the accuracy of the calls.
Pre-conditions
-
Call context
Background-loop level or OSEK-OS Task. The task should have a lower or equal priority
than all other interaction to the CANdesc component.
Particularities and Limitations
  May not be called if the DescStateTask() and DescTimerTask() are called.


2013, Vector Informatik GmbH
Version: 3.07.00
77 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.1.4  DescStateTask()
DescStateTask
Available since 4.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescStateTask (void)
Multi Context
void DescStateTask (void)
Parameter
-
-
Return code
-
-
Functional Description
Motivation: Using a single task function for timers and processing leads either to slow
processing or to faster timers which costs runtime for the ECU. The timers need very
stable cyclical call but the processing tasks may be done “as soon as possible” (i.e. using
OSEK to be assigned to lower priority task).
The function DescStateTask() has to be called periodically by the application. It is not a
timer task – it has no specific time period. As smaller this tasks call period is, so faster will
be the service processing.
This task function will process received request and to control the transmission of the
responses. Depending on the ECU requirements it is recommended to call this task as
soon as possible to avoid delays of the response (e.g. dynamically defined DID,
scheduled data, etc.), but take into account that within this task the corresponding
MainHandler will be executed too.
Pre-conditions
-
Call context
Background-loop level or OSEK-OS Task. The Task should have a lower or equal priority
than all other interaction to the CANdesc component.
Particularities and Limitations
  May not be called if the DescTask() is used (reentrancy is forbidden).


2013, Vector Informatik GmbH
Version: 3.07.00
78 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.1.5  DescTimerTask()
DescTimerTask
Available since 4.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescTimerTask (void)
Multi Context
void DescTimerTask (void)
Parameter
-
-
Return code
-
-
Functional Description
Motivation: Using a single task function for timers and processing leads either to slow
processing or to faster timers which costs runtime for the ECU. The timers need very
stable cyclical call but the processing tasks may be done “as soon as possible” (i.e. using
OSEK to be assigned to lower priority task).
The function DescTimerTask() has to be called periodically by the application in the
configured task period. It can be called as slow as possible to free run time resources.

Pre-conditions
-
Call context
Background-loop level or OSEK-OS Task. The Task should have a lower or equal priority
than all other interaction to the CANdesc component.
Particularities and Limitations
  May not be called if the DescTask() is used. This will lead to either reentrancy
(consistency) problems or/and to timing issues.


2013, Vector Informatik GmbH
Version: 3.07.00
79 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.1.6  DescGetActivityState()
DescGetActivityState
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
DescContextActivity DescGetActivityState (void)
Multi Context
DescContextActivity DescGetActivityState (vuint8 iContext)
Parameter
iContext
reference to the corresponding request context
Return code
1. kDescContextIdle
1.  There is currently no request processing (even
when scheduler is active).
2. kDescContextActiveRxBegin
2.  Currently request reception is active.
3. kDescContextActiveRxEnd
3.  Reception finished, request will be processed.
4. kDescContextActiveProcess
4.  The request was received, is under processing
5. kDescContextActiveProcessEnd
now
6. kDescContextActiveTxReady
5.  DescProcessingDone called waiting for data
before starting the transmission.
7. kDescContextActiveTx
6.  Ready for response transmission.
8. kDescContextActivePostProcess
7.  Transmission of the response is currently active.

8.  Transmission/processing ended. Post-processing
will be performed.
Functional Description
Motivation: Sometimes the knowledge about the presence of a tester is necessary. A typical
use-case is to avoid the ECU from going into sleep mode.
A non-default session indicates that a tester is present. But how can this be done, if the ECU is
in the default session?
Due to that fact  the ECU application can call the function DescGetActivityState() any time to
check if CANdesc has something to do or is in idle mode. This can be used e.g. to change the
state of the ECU sleep mode.
Note: The return value is bit coded and  any senseful combination of the above mentioned
values is possible (e.g. kDescContextActiveRxBegin | kDescContextActivePostProcess).
Please check always with bit test (and operation) and not using the value comparison.
Pre-conditions
-
Call context
-
Particularities and Limitations

2013, Vector Informatik GmbH
Version: 3.07.00
80 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.2  Multi Variant Configuration Functions
12.6.2.1  DescInitConfigVariant()
DescInitConfigVariant
Available since 6.00.00
Is Reentrant

Is callback

Prototype
Single Context and Multi Context
void DescInitConfigVariant (DescVariantMask varMask)
Parameter
varMask
Contains the VSG(s) that shall be active additionally to the base
variant
Return code
-
-
Functional Description
After CANdesc has been initialized via one of the APIs
DescInitPowerOn
or
DescInit;
the base variant will be only active (refer to the chapter 8 Multi Identity  for more details). If
additionally other variants shall be activated, this API shall be called with a parameter
value that represents the variants (multiple variants can be OR-ed) that shall be activated.

The variant values that shall be used for building the API parameter value are located in
the desc.h file. The naming convention is as follows:
kDescVariant<variant/VSG qualifier>

Pre-conditions
-Multi- variant (VSG) mode is activated for CANdesc.
Call context
-
Particularities and Limitations
  Shall not interrupt the DescTask function.
  Best place to call this API is immediately after the CANdesc initialization API-call while
the interrupts are still locked.

2013, Vector Informatik GmbH
Version: 3.07.00
81 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.2.2  DescGetConfigVariant()
DescGetConfigVariant
Available since 6.00.00
Is Reentrant

Is callback

Prototype
Single Context and Multi Context
DescVariantMask DescGetConfigVariant (void)
Parameter
-

Return code
Variant mask
Represents the bit-mapped value of the currently active variants
in the ECU.
Functional Description
This API returns the bit-mapped value of the currently active variants set in CANdesc.

The variant values that shall be used for checking the API return value are located in the
desc.h file. The naming convention is as follows:
kDescVariant<variant/VSG qualifier>

Pre-conditions
-Multi- variant (VSG) mode is activated for CANdesc.
Call context
- This API can be called from any call-context.
Particularities and Limitations
  -

2013, Vector Informatik GmbH
Version: 3.07.00
82 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.3  Service Functions
12.6.3.1  DescSetNegResponse()
DescSetNegResponse
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescSetNegResponse (DescNegResCode errorCode)
Multi Context
void DescSetNegResponse (vuint8 iContext, DescNegResCode errorCode)
Parameter
iContext
reference to the corresponding request context
errorCode
the errorCode is the one of the provided error code constants
of CANdesc in the desc.h file with the following naming
convention:
kDescNrc<error name>.
Return code
-
-
Functional Description
In the PreHandler or in the MainHandler function the application has the possibility of
forcing negative response with a certain negative response code for the current request
when it is necessary.
Pre-conditions
-
Call context
Within a ‘Service PreHandler’ function and within or after a ‘Service MainHandler’ function
Particularities and Limitations
  Once an error was set it can not be overwritten or reset.
  This function does not finish the processing of the request. It just sets a certain error
and after that the application must confirm that the request processing was completely
finished by calling DescProcessingDone().

2013, Vector Informatik GmbH
Version: 3.07.00
83 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.3.2  DescProcessingDone()
DescProcessingDone
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescProcessingDone (void)
Multi Context
void DescProcessingDone (vuint8 iContext)
Parameter
iContext
reference to the corresponding request context
Return  code
-
-
Functional Description
After completing the request execution the application must call the API function.
By calling this function, depending on the previous actions of the application the CANdesc
module will either send a response (positive/negative depending on the error state
machine) or no response will be send if the application/CANdesc decides that there must
be no response (please refer the Part III User Manual)
Pre-conditions
-
Call context
Within or after a ‘Service MainHandler’ function
Particularities and Limitations

12.6.4  Service callback functions
In CANdesc 6 the naming convention of the service callback function has changed due to
standardization reasons. In Table 12-3, the new naming convention can be found. Earlier
versions of CANdesc (< 6.0) used always Service-Qualifiers and Instance-Qualifiers from
the  CDD  file.  Since  CANdesc  6,  for  Service-Qualifiers  always  standardized  names  are
used,  whereas  for  Instance-Qualifiers  either  a  standardized  name  or  the  name  from  the
CDD file is used. The names of the service callback functions are based on the following
pattern:
ApplDesc[Pre|Post]<ServiceQualifier><DiagInstanceQualifier>
When migrating to CANdesc 6 the service callbacks have to be renamed according to the
new naming convention.
Service
SubService
Instance-Qualifier
Service-Qualifier
0x01
Default
0x10
StartSession
0x02
Programming
2013, Vector Informatik GmbH
Version: 3.07.00
84 / 164
based on template version 5.1.0

Technical Reference CANdesc
Service
SubService
Instance-Qualifier
Service-Qualifier
0x03
Extended
0x01
Hard
0x02
KeyOffOn
0x11
0x03
Soft
EcuReset
0x04
EnableRapidShutDown
0x05
DisableRapidShutDown
0x14
None
DiagInfo
Clear
0x01
RNODTCBSM
ReadDtc
0x02
RDTCBSM
0x03
RDTCSSI
0x04
RDTCSSBDTC
0x05
RDTCSSBRN
0x06
RDTCEDRBDN
0x07
RNODTCBSMR
0x08
RDTCBSMR
0x09
RSIODTC
0x0A
RSUPDTC
0x0B
RFTFDTC
0x0C
RFCDTC
0x19
0x0D
RMRTFDTC
0x0E
RMRCDTC
0x0F
RMMDTCBSM
0x10
RMDEDRBDN
0x11
RNOMMDTCBSM
0x12
RNOOBDDTCBSM
0x13
ROBDDTCBSM
0x14
RDTCFDC
0x15
RDTCWPS
0x16
RDTCRDIDBDN
0x41
RWWHOBDNDTCBMR
0x42
RWWHOBDDTCBMR
0x55
RWWHOBDDTCWPS
0x22
Any
Instance-Qualifier from CDD
ReadDid
0x23
None
MemoryByAddress
Read
0x24
Any
Instance-Qualifier from CDD
ReadScalingDid
Odd Id
GetSeed
0x27
Instance-Qualifier from CDD
Even Id
SendKey
0x00
EnableRxEnableTx
0x28
CommCtrl
0x01
EnableRxDisableTx
2013, Vector Informatik GmbH
Version: 3.07.00
85 / 164
based on template version 5.1.0

Technical Reference CANdesc
Service
SubService
Instance-Qualifier
Service-Qualifier
0x02
DisableRxEnableTx
0x03
DisableRxDisableTx
0x01
ReadDidSlow
0x02
ReadDidMed
0x2A
Instance-Qualifier from CDD
0x03
ReadDidFast
0x04
ReadDidStop
0x01
DynDefineByDid
0x2C
0x02
Instance-Qualifier from CDD
DynDefineByAddr
0x03
DynDefineClear
0x2E
Any
Instance-Qualifier from CDD
WriteDid
0x00
IoCtrlRetCtrlToEcu
0x01
IoCtrlRstToDefault
0x2F
Instance-Qualifier from CDD
0x02
IoCtrlFrzCurrState
0x03
IoCtrlShortTermAdj
0x01
RtnCtrlStart
0x31
0x02
Instance-Qualifier from CDD
RtnCtrlStop
0x03
RtnCtrlReqRes
0x34
None

RequestDownload
0x35
None

RequestUpload
0x36
None

TransferData
0x37
None

RequestTransferExit
0x3D
None
MemoryByAddress
Write
0x3E
0x00
TesterPresent
Send
0x84
None

SecuredDataTransmission
0x01
Enable
0x85
ControlDtcSetting
0x02
Disable
0x00
Stop
0x01
OnDtcStatChg
0x02
OnTmrInt
0x03
OnChgOfDid
0x04
ReportActEv
0x05
Start
0x06
Clear
0x86
Roe
0x07
OnCompOfVal
0x40
StStop
0x41
StOnDtcStatChg
0x42
StOnTmrInt
0x43
StOnChgOfDid
0x44
StReportActEv
0x45
StStart
2013, Vector Informatik GmbH
Version: 3.07.00
86 / 164
based on template version 5.1.0

Technical Reference CANdesc
Service
SubService
Instance-Qualifier
Service-Qualifier
0x46
StClear
0x47
StOnCompOfVal
0x01
VerifyFixedBaudrate
0x87
0x02
VerifySpecificBaudrate
LinkControl
0x03
TransitionBaudrate
Table 12-3 Naming convention of service callback functions in CANdesc 6
12.6.4.1  Service PreHandler
ApplDescPre<Service-Qualifier + Instance-Qualifier>>
Available since 2.00.00
Is callback

Prototype
Single Context
void ApplDescPre<Service-Qualifier + Instance-Qualifier> (void)
Multi Context
void ApplDescPre<Service-Qualifier + Instance-Qualifier> (vuint8 iContext)
Parameter
iContext
the current request context location
Return  code
-
-
Functional Description
The PreHandler is executed before the Service MainHandler is called. In the PreHandler,
the application can hook any (especially application-specific) state validations. One
PreHandler implementation may be shared with different service instances (only
CANdesc).
To allow quite complex operations to take place, the application has access to the request
data using the context data structure (if given).
Pre-conditions
Must be configured to ‘User’ in attribute ‘PreHandlerSupport’’
Call context
From DescTask()
Particularities and Limitations

2013, Vector Informatik GmbH
Version: 3.07.00
87 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.4.2  Service MainHandler
ApplDesc<Service-Qualifier + Instance-Qualifier>
Available since 2.00.00
Is callback

Prototype
Single Context
void ApplDesc<Service-Qualifier + Instance-Qualifier> (DescMsgContext* pMsgContext)
Multi Context
void ApplDesc<Service-Qualifier + Instance-Qualifier> (DescMsgContext* pMsgContext)
Parameter
typedef struct
pMsgContext
{
  DescMsg reqData;
  DescMsgLen reqDataLen;
  DescMsg resData;
  DescMsgLen resDataLen;
  DescMsgAddInfo msgAddInfo;
  vuint8 iContext;
  t_descUsdtNetBus busInfo;
} DescMsgContext;
  DescBitType reqType :2; /* 0x01: Phys 0x02: Func */
DescMsgAddInfo    DescBitType resOnReq :2; /* 0x01: Phys 0x02: Func */
  DescBitType suppPosRes:1; /* 0x00: No 0x01: Yes */
Read access
pMsgContext->reqData
pointer to the first byte of the already extracted request data.
pMsgContext->reqDataLen
length of the extracted request data.
pMsgContext->iContext
the current request context location
(used only as a handle - DO NOT MODIFY).
pMsgContext->msgAddInfo.reqType
the current request addressing method. Could be either
‚kDescFuncReq’ or ‚kDescPhysReq’ (bitmapped).
pMsgContext->msgAddInfo.suppPosRes
if set, no positive response will be sent. (UDS only).
pMsgContext->busInfo
the current request communication information (i.e. driver type (CAN,
MOST, FlexRay, etc.), addressing information, communication channel
number, tester address (if applicable) etc.
Write access
pMsgContext->resData
pointer to the first position where the response data can be written.
pMsgContext->resDataLen
length of the written data.
pMsgContext->msgAddInfo.resOnReq
can be used to disable the response transmission on the current
request. If set to ‘0’ no response will be transmitted. Physical and
function can be set separately (bitmapped).
Return  code
2013, Vector Informatik GmbH
Version: 3.07.00
88 / 164
based on template version 5.1.0

Technical Reference CANdesc
-
-
Functional Description
The MainHandler processes the service request.

Perform length validation for varying length information of request.

Disassemble any data received with the request telegram and process it,.

Assemble any data to be send with the response and update current response
length.

Confirm that the processing is finished.
Pre-conditions
Must be configured to ‘User’ in attribute ‘MainHandlerSupport’
Call context
From DescTask()
Particularities and Limitations
 If used as MainHandler for Protocol Services, the Protocol-Service-Qualifier is used
instead

2013, Vector Informatik GmbH
Version: 3.07.00
89 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.4.3  Service PostHandler
ApplDescPost<Service-Qualifier + Instance-Qualifier>
Available since 2.00.00
Is callback

Prototype
Single Context
void ApplDescPost<Service-Qualifier + Instance-Qualifier> (vuint8 status)
Multi Context
void ApplDescPost<Service-Qualifier + Instance-Qualifier> (vuint8 iContext,
vuint8 status)
Parameter
iContext
the current request context location
status (bit-coded)
kDescPostHandlerStateOk
The positive response was transmitted successfully
kDescPostHandlerStateNegResSent
It was a negative response
kDescPostHandlerStateTxFailed
A transmission error occurred
Return  code
-
-
Functional Description
Any state transition may not be performed before the current service is finished
completely (the last frame of the response is sent successfully).
The PostHandler is executed after a confirmation of the message transmission is received
and is designated for state adaptation – all other things are already done when the
PostHandler is called.
Pre-conditions
Must be configured to ‘User’ in attribute ‘PostHandlerSupport’
Call context
From DescTask()
Particularities and Limitations
  If used as PostHandler for Protocol Services, the Protocol-Service-Qualifier is used
instead
  You can override the given name extension (Service-Qualifier + Instance-Qualifier) by
using the ‘PostHandlerOverrideName’.
2013, Vector Informatik GmbH
Version: 3.07.00
90 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.5  User (Unknown) Service Handling
In some cases the ECU shall support a service which is not described in the common way
for CANdesc (by means of CANdelaStudio/GENtool). With a little bit more effort inside the
application  than  for  the  “known”  services  the  ECU  is  still  be  able  to  support  those  user
defined services. The effort comes form the fact that CANdesc knows nothing about this
service (e.g. session, security or other states described in the CDD configuring CANdesc,
addressing methods allowed for those services, etc.) and therefore the application must do
this  work  for  each  user  defined  service  by  itself.  In  fact  for  CANdesc  there  is  only  one
“unknown” service and it is up to the application to differentiate between multiple unknown
service(s).
Attention: This feature is available since version 2.11.00 of CANdesc(Basic).
12.6.5.1  How it works
If  the  feature  “Support  Generic  User  Service”  is  enabled  in  the  GENtool  CANdesc  uses
following handling:
-  if  a  service  was  not  recognized  by  its  SID,  before  the  automatic  negative
response  transmission  will  be  sent,  the  application  will  be  called  (see
12.6.5.2  ApplDescCheckUserService)  to  check  this  SID  too.  If  it  can  not
recognize it as a valid one the usual negative response will be sent.
-  If  the  application  has  accepted  the  SID,  then  a  special  “user  service”
MainHandler will be called (see 12.6.5.4 Generic User Service MainHandler).
-  If  in  GENtool  “Support  Generic  User  Service  PostHandler”  is  set,  after  the
request  processing  has  been  accomplished,  a  special  “user  service”
PostHandler will be called (see 12.6.5.5 Generic User Service PostHandler).
Note:
-  Since CANdesc doesn’t distinguish user defined services, a special API was
designed to get the application the opportunity to dispatch among the SIDs
(in MainHandler and in the PostHandler).
-  The user defined services are processed on service id level which means the
application shall dispatch and do the whole format check of these requests.
The state management shall be performed bye application, too.

2013, Vector Informatik GmbH
Version: 3.07.00
91 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.5.2  ApplDescCheckUserService()
ApplDescCheckUserService
Available since 2.11.00
Is callback

Prototype
Single Context
vuint8 ApplDescCheckUserService (DescMsgItem sid)
Multi Context
vuint8 ApplDescCheckUserService (DescMsgItem sid)
Parameter
sid
The service identifier which is currently under processing.
Return  code
1.  kDescOk
1.  Return this value if the service id is a “user defined” one.
2.
2.  Return this value if the service id is unknown for the
  kDescFailed
application too.
Functional Description
The currently received request contains an unknown for CANdesc service Id. Within this
function the ECU application has to decide immediately if the SID is one of the user
defined or not. Depending on the return value, CANdesc will process further this request
or will reject it by sending negative response ‘ServiceNotSupported’.
Pre-conditions
The “Support Generic User Service” option was enabled in the GENtool configuration.
Call context
From DescTask() (in KWP diagnostics also from RxInterrupt).
Particularities and Limitations

2013, Vector Informatik GmbH
Version: 3.07.00
92 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.5.3  DescGetServiceId()
DescGetServiceId
Available since 2.11.00
Is Reentrant

Is callback

Prototype
Single Context
DescMsgItem DescGetServiceId (void)
Multi Context
DescMsgItem DescGetServiceId (vuint8 iContext)
Parameter
iContext
The current request context location
Return  code
DescMsgItem
The service id which is currently under processing.
Functional Description
Reports the service id of the currently processed user-service request.
Pre-conditions
The “Support Generic User Service” option was enabled in the GENtool configuration.
Call context
From DescTask()
Particularities and Limitations
  This function may be called at any time within a diagnostic request life cycle starting at
the call of the MainHandler and ending by the PostHandler (if configured) or (if none
configured) by calling  DescProcessingDon

2013, Vector Informatik GmbH
Version: 3.07.00
93 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.5.4  Generic User Service MainHandler
ApplDescUserServiceHandler
Available since 2.11.00
Is callback

Prototype
Single Context
void ApplDescUserServiceHandler (DescMsgContext* pMsgContext)
Multi Context
void ApplDescUserServiceHandler (DescMsgContext* pMsgContext)
Parameter
pMsgContext
Refer the section 12.6.4.2 Service MainHandler for details about this
parameter.
Read Access
pMsgContext->reqData
pointer to the first byte after the service Id.
The other members of the parameter are described in 12.6.4.2 Service
MainHandler
Write access
pMsgContext->resData
pointer to the first byte after the response SID, where the data (incl. sub-
parameters) will be written.
The other members of the parameter are described in 12.6.4.2 Service
MainHandler
Return  code
-
-
Functional Description
This MainHandler is called for all unknown service requests at service id level, so the
application has to do following:

Perform service id dispatching (if more than one user defined service shall be
used).

Perform length validation for varying length information of request.

Perform parameter (if any) validation.

Disassemble any data received with the request telegram and process it.

Assemble any data to be send with the response and update current response
length

Confirm that the processing is finished.
Pre-conditions
The “Support Generic User Service” option was enabled in the GENtool configuration.
Call context
From DescTask()
Particularities and Limitations
  Refer the section 12.6.4.2 Service MainHandler.
  DescGetServiceId() may be called here to dispatch the SID of the currently processed
user service (refer 12.6.5.3 DescGetServiceId

2013, Vector Informatik GmbH
Version: 3.07.00
94 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.5.5  Generic User Service PostHandler
ApplDescPostUserServiceHandler
Available since 2.11.00
Is callback

Prototype
Single Context
void ApplDescPostUserServiceHandler (vuint8 status)
Multi Context
void ApplDescPostUserServiceHandler (vuint8 iContext, vuint8 status)
Parameter
iContext, status
Refer 12.6.4.3 Service PostHandler for information.
Return  code
-
-
Functional Description
The functionality of the user service PostHandler is the same as the one of the normal
service PostHandler. Refer 12.6.4.3 Service PostHandler for more details.
Pre-conditions
The “Support Generic User Service PostHandler” option was enabled in the GENtool
configuration.
CANdesc version >= 2.11.00
Call context
From DescTask()
Particularities and Limitations
  Refer the section 12.6.4.3 Service PostHandler for information.
  DescGetServiceId() may be called here to dispatch the SID of the currently post-
processed user service (refer 12.6.5.3 DescGetServiceId
2013, Vector Informatik GmbH
Version: 3.07.00
95 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.6  Session Handling
12.6.6.1  ApplDescCheckSessionTransition()
ApplDescCheckSessionTransition
Available since 2.00.00
Is callback

Prototype
Single Context
void ApplDescCheckSessionTransition (DescStateGroup newState, DescStateGroup
formerState)
Multi Context
void ApplDescCheckSessionTransition (vuint8 iContext, DescStateGroup newState,
DescStateGroup formerState)
Parameter
iContext
the current request context location
newState
the CANdesc component has change to this session state
formerState
the CANdesc component has change from this session state
Return  code
-
-
Functional Description
This hook function will be called, while session request is received (SID $10). If the
application wants to discard this request, an error must be set (via
DescSetNegResponse() ).
The application always has to confirm this hook function via
DescSessionTransitionChecked().
Both above functions can be called also outside of the context of this function (e.g.
application task waiting for results form an I/O port). CANdesc will send RCR-RP
response as long as the application delays the confirmation for the session transition.

In some cases the application has to know whether the SPRMIB in the request was set or
not. Since this API call does not contain this information, a dedicated API in CANdesc
provides it: DescIsSuppressPosResBitSet ().
Pre-conditions
At least one DiagnosticSessionControl service must be configured to ‘OEM’ in attribute
‘MainHandlerSupport’
Call context
From DescTask()
Particularities and Limitations
  Call the API function DescSessionTransitionChecked() to end the service processing


2013, Vector Informatik GmbH
Version: 3.07.00
96 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.6.2  DescSessionTransitionChecked()
DescSessionTransitionChecked
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescSessionTransitionChecked (void)
Multi Context
void DescSessionTransitionChecked (vuint8 iContext)
Parameter
iContext
the current request context location
Return  code
-
-
Functional Description
After the application has finished the processing in the hook function
ApplDescCheckSessionTransition() this function must be called.
Pre-conditions
At least one DiagnosticSessionControl service must be configured to ‘OEM’ in attribute
‘MainHandlerSupport’
Call context
Within or after a ‘ApplDescCheckSessionTransition()’ function
Particularities and Limitations
  If this function will be called late, the CANdesc component sends automatically the
RCR-RP responses

2013, Vector Informatik GmbH
Version: 3.07.00
97 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.6.3  DescIsSuppressPosResBitSet ()
DescIsSuppressPosResBitSet
Available since 5.07.14
Is Reentrant

Is callback

Prototype
Single Context
DescBool DescIsSuppressPosResBitSet (void)
Multi Context
DescBool DescIsSuppressPosResBitSet (vuint8 iContext)
Parameter
iContext
the current request context location
Return  code
kDescTrue
The SPRMIB is set.
The SPRMIB is NOT set.
kDescFalse

Functional Description
This API can be always called while a diagnostic service processing is ongoing to get the
information about the SPRMIB state. All main-handlers do contain this information already
in the pMsgContext parameter so use it instead of this API.
In some other cases the application does not have access to the pMsgContext, and there
the API can be used.
Pre-conditions
Only for UDS configurations.
May be called only while a diagnostic service processing is ongoing. Otherwise invalid
data can be reported.
Call context
Any.
Particularities and Limitations


2013, Vector Informatik GmbH
Version: 3.07.00
98 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.6.4  ApplDescOnTransitionSession()
ApplDescOnTransitionSession
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void ApplDescOnTransitionSession (DescStateGroup newState,
  DescStateGroup formerState)
Multi Context
void ApplDescOnTransitionSession (DescStateGroup newState,
  DescStateGroup formerState)
Parameter
newState
the CANdesc component has change to this session state
formerState
the CANdesc component has change from this session state
Return  code
-
-
Functional Description
After the positive response of a SessionControl request the session will transit to the
requested session. This function informs the application that such a transition occurs.
Pre-conditions
-
Call context
From DescTask()
interrupts might be disabled
Particularities and Limitations
  Only informational function

2013, Vector Informatik GmbH
Version: 3.07.00
99 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.6.5  DescSetStateSession()
DescSetStateSession
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescSetStateSession (DescStateGroup newSession)
Multi Context
void DescSetStateSession (DescStateGroup newSession)
Parameter
newSession
the CANdesc component will change to this session state
Return  code
-
-
Functional Description
By this function the state of the SessionState-group can be changed by the ECU
application. The transition notification function ‘ApplDescOnTransitionSession’ will be
called to notify the application about the new session.

Pre-conditions
-
Call context
-
Particularities and Limitations
  Refer the section 12.6.11.2 "DescSetState<StateGroup>()” for more details.

2013, Vector Informatik GmbH
Version: 3.07.00
100 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.6.6  DescGetStateSession()
DescGetStateSession
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
currentSession DescGetStateSession (void)
Multi Context
currentSession DescGetStateSession (void)
Parameter
-

Return  code
currentSession

Functional Description
This function returns the current session state. Since the states are bit-coded the
evaluation expressions may be optimized for multiple use cases.
Example: Code execution only when either default or extended session is active.
lState = DescGetStateSession();
if ( (lState & (kDescStateSession<Default>) | kDescStateSession<Extended>)) != 0 )
{
/*execute code*/
}
Pre-conditions

-
Call context
-
Particularities and Limitations
  Refer the section 12.6.11.1 “DescGetState<StateGroup>()” for more details.

2013, Vector Informatik GmbH
Version: 3.07.00
101 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.6.7  DescGetSessionIdOfSessionState
DescGetSessionIdOfSessionState
Available since 3.00.00
Is Reentrant

Is callback

Prototype
Any Context
DescMsgItem DescGetSessionIdOfSessionState (DescStateGroup sessionState)
Parameter
sessionState
- Must be one of the valid session states (i.e. the value of the
API DescGetStateSession() ).
Return code
DescMsgItem
- Is the corresponding session identifier value.
Functional Description
This function provides a conversion from a session state to its corresponding session
identifier (e.g. calling this function with parameter kDescStateSessionDefault will return
0x01).
Pre-conditions
-
Call context
-
Particularities and Limitations


2013, Vector Informatik GmbH
Version: 3.07.00
102 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.7  CommunicationControl Handling
This  API  is  provided,  if  the  ECU  supports  the  serviceCommunicationControl  (UDS)  or
service 0x28/0x29 Dis-/EnableNormalMessageTransmission (KWP).
12.6.7.1  ApplDescCheckCommCtrl()
ApplDescCheckCommCtrl
Available since 2.00.00
Is callback

Prototype
Single Context
void ApplDescCheckCommCtrl (DescOemCommControlInfo* commControlInfo)
Multi Context
void ApplDescCheckCommCtrl (vuint8 iContext,
  DescOemCommControlInfo* commControlInfo)
Parameter
iContext
The current request context location
commControlInfo
OEM dependent
Return  code
-
-
Functional Description
The execution of this service is completely done within the CANdesc component. This
hook function can be used to permit the application to reject the execution under some
circumstance. If the application wants to discard this request, an error must be set (via
DescSetNegResponse()).
The application always has to confirm this hook function (via DescCommCtrlChecked()).
Pre-conditions
The CommunicationControl service must be activated and the attribute
‘MainHandlerSupport’ has to be set to ‘OEM’
Call context
From DescTask()
Particularities and Limitations
  If the API function DescCommCtrlChecked() will be not called, the service processing
will not end

2013, Vector Informatik GmbH
Version: 3.07.00
103 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.7.2  DescCommCtrlChecked()
DescCommCtrlChecked
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescCommCtrlChecked (void)
Multi Context
void DescCommCtrlChecked (vuint8 iContext)
Parameter
iContext
the current request context location
Return  code
-
-
Functional Description
The CANdesc component calls a hook function to check for the execution permission of
the CommunicationControl service. Within or after this hook function
(ApplDescCheckCommCtrl()) the application can set an error
(DescSetNegResponse()) to reject the request. This function is used to terminate the
hook function ApplDescCheckCommCtrl().
Pre-conditions
The CommunicationControl service must be activated and the attribute
‘MainHandlerSupport’ has to be set to ‘OEM’
Call context
Within or after ApplDescCheckCommCtrl()
Particularities and Limitations


2013, Vector Informatik GmbH
Version: 3.07.00
104 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.8  Periodic call of ‘Service MainHandler’
12.6.8.1  DescStartRepeatedServiceCall()
DescStartRepeatedServiceCall
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescStartRepeatedServiceCall (DescMainHandler descMainHandler)
Multi Context
void DescStartRepeatedServiceCall (vuint8 iContext, DescMainHandler descMainHandler)
Parameter
descMainHandler
Reference to a function. The function prototype must be based
on a ‘Service MainHandler’.
iContext
The current request context location
Return  code
-
-
Functional Description
The application can use this function to get a periodic call to the specified function (in the
parameter) from the CANdesc component.
It is possible to use the same ‘Service MainHandler’ function as it is called in.
Pre-conditions

Call context
Within or after a ‘Service MainHandler’ function
Particularities and Limitations
  CANdesc can do no validation, if this pointer is valid.
  Is the parameter NULL, the periodic calls will get stopped.
  The function is called in the same cycle time (context) as the DescTask()

2013, Vector Informatik GmbH
Version: 3.07.00
105 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.8.2  DescStartMemByAddrRepeatedCall()
DescStartMemByAddrRepeatedCall
Available since 5.06.04
Is Reentrant

Is callback

Prototype
Single Context
void DescStartMemByAddrRepeatedCall ()
Multi Context
void DescStartMemByAddrRepeatedCall (vuint8 iContext)
Parameter
iContext
The current request context location
Return  code
-
-
Functional Description
The application can use this function to get a periodic call to the current Read/Write
memory by address handler.
Pre-conditions

Call context
Within ApplDescReadMemoryByAddress or ApplDescWriteMemoryByAddress.
Particularities and Limitations
  The memory access handler is called in the same cycle time (context) as the
DescTask()

12.6.9  Ring Buffer Mechanism
The ring-buffer option can be used to save RAM when some responses are quite long and
reserving such space of RAM is impossible. In contrast to the linear responses, where the
response data will be first written and then the transmission to the tester will be initiated,
the ring-buffer concept starts a transmission as soon as it has either the whole data (for
short [single frame] responses) or at least enough data to fill a first-frame of a multi-frame
transmission.  Once  the  ring  buffer  has  been  activated  and  the  response  transmission
initiated, the application must supply enough data to keep the transmission away from lack
of data. In multiple PID mode, the application can decide in each PID main handler to use
the  ring  buffer  or  not.  However,  if  one  of  the  PIDs  has  dynamic  length,  the  ring  buffer
mechanism can not be used for any PID in the list.

2013, Vector Informatik GmbH
Version: 3.07.00
106 / 164
based on template version 5.1.0

Technical Reference CANdesc

Note
The ring buffer should only be used for long responses, because using the ring buffer
instead of the linear buffer causes a runtime overhead.

2013, Vector Informatik GmbH
Version: 3.07.00
107 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.9.1  DescRingBufferStart()
DescRingBufferStart
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescRingBufferStart (void)
Multi Context
void DescRingBufferStart (vuint8 iContext)
Parameter
iContext
reference to the corresponding request context
Return  code
-
-
Functional Description
After completing the request validation the application can decide (in runtime), if the ring-
buffer mechanism should be used or not.
By calling this function, the decision is made to use the ring-buffer. Otherwise
DescProcessingDone() should be called, after filling the response data (in a linear way).
Either DescProcessingDone() or DescRingBufferStart() will finish the response handling.
Depending on the previous actions of the application the CANdesc module will either send
a response (positive/negative depending on the error state machine) or no response will
be send if the application/CANdesc decides that there must be no response (please refer
the Part III User Manual).
The transmission of the positive response will not start immediately. The application has to
fill the ring-buffer first. If the ring-buffer has enough data, the transmission will be started
(internally).
Pre-conditions
- ring-buffer has been enabled in the configuration
Call context
Within or after a ‘Service MainHandler’ function
Particularities and Limitations
  This API must not be called from any of the other handler type (Pre- or PostHandlers)
  Either DescProcessingDone() or DescRingBufferStart() must be used to finish the
response handling.
  Total response length must be written before!
  No response data must be written before!
  This function must not be called in interrupt context
  Limitation: Until CANdesc version 2.13.00 it was not possible to use the Ring-Buffer in
‘Multiple PID’ services (as described in section 9.1.3 Multiple PID mode)
  UDS limitation: Always check the SPRMIB prior starting the ring-buffer. If this bit is
set, the ring-buffer shall not be started. Instead DescProcessingDone() must be called
(see 13.6).
2013, Vector Informatik GmbH
Version: 3.07.00
108 / 164
based on template version 5.1.0

Technical Reference CANdesc

12.6.9.2  DescRingBufferWrite()
DescRingBufferWrite
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
vuint8 DescRingBufferWrite (DescMsg data, DescMsgLen dataLength)
Multi Context
vuint8 DescRingBufferWrite (vuint8 iContext, DescMsg data, DescMsgLen dataLength)
Parameter
iContext
Reference to the corresponding request context
DescMsg
Pointer to application data, which should be copied into ring-
buffer.
DescMsgLen
Amount of data, which should be copied (from pointer data) into
ring-buffer.
Return  code
vuint8
kDescOk
If the copy process was successful
kDescFailed
if the data are not copied into the ring-buffer
Functional Description
The application writes data into the ring-buffer by this function. It is not necessary that the
application must write the data in the context of a special API function.
The write order is always linear! The first written byte is the first byte in the response
message.
Pre-conditions
-
ring-buffer has been enabled in the configuration;
-
DescRingBufferStart() must be called first, to activate the ring-buffer mechanism.
Call context
- This API shall not interrupt the DescTask. Required for the case the currently ongoing
transmission is interrupted due to a communication error, and the application still writes
into the buffer.
Particularities and Limitations
  dataLength must be lower or equal to the ring-buffer size, else the function will
always fail
  CANdesc has already filled the first bytes (SID, etc.) into the ring-buffer. So in the first
call of DescRingBufferWrite() the dataLength must lower as the buffer size + these
byte

2013, Vector Informatik GmbH
Version: 3.07.00
109 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.9.3  DescRingBufferCancel()
DescRingBufferCancel
Available since 5.01.00
Is Reentrant

Is callback

Prototype
Single Context
void DescRingBufferCancel (void)
Multi Context
void DescRingBufferCancel (vuint8 iContext)
Parameter
iContext
Reference to the corresponding request context
Return  code
-
-
Functional Description
The application may call this API once the a data acquisition error has been occurred after
the ring-buffer has been activated via DescRingBufferStart().

CANdesc will automatically determine the appropriate action depending on its current
internal state:
-
if the response data transmission has not been started yet, a negative
response will be sent back.
-
If the response transmission has been started – a transmission interrupt
will occur – the tester will not get a complete response.
Pre-conditions
-
ring-buffer has been enabled in the configuration
-
DescRingBufferStart() must be called before to activate the ring-buffer mechanism
Call context
-
Particularities and Limitations


2013, Vector Informatik GmbH
Version: 3.07.00
110 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.9.4  DescRingBufferGetFreeSpace()
DescRingBufferGetFreeSpace
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
DescMsgLen DescRingBufferGetFreeSpace (void)
Multi Context
DescMsgLen DescRingBufferGetFreeSpace (vuint8 iContext)
Parameter
iContext
reference to the corresponding request context
Return  code
DescMsgLen
The amount of free space/bytes in the ring-buffer.
Functional Description
This function returns the amount of free space/bytes in the ring-buffer.
Pre-conditions
-
ring-buffer has been enabled in the configuration
-
DescRingBufferStart() must be called before to activate the ring-buffer mechanism
Call context
-

2013, Vector Informatik GmbH
Version: 3.07.00
111 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.9.5  DescRingBufferGetProgress()
DescRingBufferGetProgress
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
DescMsgLen DescRingBufferGetProgress (void)
Multi Context
DescMsgLen DescRingBufferGetProgress (vuint8 iContext)
Parameter
iContext
reference to the corresponding request context
Return  code
DescRingBufferProgress  Current byte position in the whole response.
Functional Description
This function returns the progress of the copy process.
Pre-conditions
-
ring-buffer has been enabled in the configuration
-
DescRingBufferStart() must be called before to activate the ring-buffer mechanism
Call context
-
Particularities and Limitations


2013, Vector Informatik GmbH
Version: 3.07.00
112 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.10 Signal Interface of CANdesc
CANdesc  will  provide  a  signal  interface  to  the  ECU  application.  This  can  help  the  ECU
application  to  assemble  the  response  automatically.  No  further  code  changes  are
necessary, if a signal will move or change its size.
The  current  implementation  has  only  support  for  a  synchronous  signal  interface.  This
means  the  ECU  application has  to  provide the  signal  value  within  the  call/context  of  the
Signal Handler function (while reading) or to write thewithin the call/context of the  Signal
Handler function (while writing).
12.6.10.1 ApplDesc<Signal-Handler>()
ApplDesc<Signal-Handler>
Available since 2.00.00
Is callback

Prototype
Single Context
- ApplDesc<Service-Qualifier + Data-Object-Qualifier + Instance-Qualifier> (-)
Multi Context
- ApplDesc<Service-Qualifier + Data-Object-Qualifier + Instance-Qualifier> (-)
Parameter
vuint8, vsint8,
Available for write services.
vuint16, vsint16,
Type depend on signal type
vuint32, vsint32,
DescMsg (vuint8*)
DescMsg (vuint8*)
Available for read services and signals > 32 bit (N bit)
Return  code
vuint8, vsint8,
Available for read services.
vuint16, vsint16,
Type depend on signal type.
vuint32, vsint32
Functional Description
A Signal Handler is generated if the Service MainHandler is configured to be generated. In
this case, writing Signal Handlers are generated for all dataObjects transported with the
request and reading Signal Handlers are generated for all dataObjects transported with
the response (read/write from application point of view).
The data type of the Signal Handler argument depends on the dataObject which is to be
processed.
Pre-conditions
Must be configured to ‘generated’ in attribute ‘MainHandlerSupport’
Call context
From DescTask()
Particularities and Limitations
   You can override the given name extension (Service-Qualifier + Data-Object-Qualifier
+ Instance-Qualifier) by using the SignalHandlerOverrideName.

2013, Vector Informatik GmbH
Version: 3.07.00
113 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.10.2 Configuration of direct signal access
  Application variable for direct access (default = not set)
If this variable is specified, an access to the given external (= application) variable is
generated. Nothing has to be done by the application. The external variable must
be defined inside the application.
  SignalHandlerOverrideName (default = not set).
You can adapt the name of the Signal Handler setting this value. By using this
“Override Name” it is also possible to reuse an already existing Signal Handler
12.6.11 State Handling (CANdesc only)
12.6.11.1 DescGetState<StateGroup>()
DescGetState<StateGroup>
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
DescStateGroup DescGetState<StateGroup-Qualifier> (void)
Multi Context
DescStateGroup DescGetState<StateGroup-Qualifier> (void)
Parameter
-
-
Return  code
DescStateGroup
The current state of the state group
Functional Description
This function returns the current session state. Since the states are bit-coded the
evaluation expressions may be optimized for multiple use cases.
Example: Code execution only when either the current state of this group is either state X
or state Y.
lState = DescGetState< StateGroupQualifier >();
if ( (lState & (kDescState< StateGroupQualifier ><StateQualifier_X>) |
  kDescState< StateGroupQualifier ><StateQualifier_Y>)) != 0 )
{
/*execute code*/
}
Pre-conditions
-
Call context
-
Particularities and Limitations
  For each state of a state-group a constant is defined in desc.h:
kDescState<StateGroup-Qualifier><StateQualifier>

2013, Vector Informatik GmbH
Version: 3.07.00
114 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.11.2 DescSetState<StateGroup>()
DescSetState<StateGroup>
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void DescSetState<StateGroup-Qualifier> (DescStateGroup newState)
Multi Context
void DescSetState<StateGroup-Qualifier> (DescStateGroup newState)
Parameter
DescStateGroup
the state in which the state group should be changed
Return  code
-
-
Functional Description
By this function the state of the state-group can be changed by the ECU application. The transition
notification function ‘ApplDescOnTransition< StateGroupQualifier >’ will be called to notify the
application about the new state.
Example:
DescSetState<StateGroupQualifier>(kDescState<StateGroupQualifier><StateQualifier>);

This line will force CANdesc to change the state of the given state group to the new one.
Pre-conditions
-
Call context
-From a task with priority lower or equal to the DescTask.
Particularities and Limitations
  For each state of a state-group a constant will be defined in desc.h:
kDescState<StateGroup-Qualifier><State-Qualifier>
  The ApplDescOnTransition<StateGroup-Qualifier>() notification function is called in any
case. Also if the newState is the same as the current stat

2013, Vector Informatik GmbH
Version: 3.07.00
115 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.11.3 ApplDescOnTransition«StateGroup»()
ApplDescOnTransition«StateGroup»
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void ApplDescOnTransition<StateGroup-Qualifier>(DescStateGroup newState,
  DescStateGroup formerState)
Multi Context
void ApplDescOnTransition<StateGroup-Qualifier> (DescStateGroup newState,
DescStateGroup formerState)
Parameter
newState
the CANdesc component has changed to this session state
formerState
the CANdesc component has changed from this session state
Return  code
-
-
Functional Description
This notification function will be called each time a transition has happened.
Pre-conditions
-
Call context
From DescTask()
interrupts might be disabled
Particularities and Limitations
  For each state of a state-group a constant will be defined in desc.h:
kDescState<StateGroup-Qualifier><StateName-Qualifier>
  For some exceptions (e.g. Session) the newState can be the same as the formerState.

2013, Vector Informatik GmbH
Version: 3.07.00
116 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.12 Force “Response Correctly Received - Response Pending” transmission
In  some  cases  it  is  useful  for  the  application  to  be  sure  that  it  has  enough  time  to
accomplish a  process  without  causing  the  tester  to  get  response timeout.  In  such  cases
the  application  can  use  the  “force  RCR-RP”  mechanism  of  CANdesc,  which  prevents
timeout between the tester and the ECU application.
How it works:
This feature is mostly applicable when a FlashBootLoader (FBL) is available for the ECU.
Before  starting  it,  the  application  wants  to  assure  that  there  is  enough  time  to  perform
reset  and  activate  the  FBL  before  the  tester  gets  response  timeout.  The  RCR-RP
mechanism notifies the tester that some action is ongoing and so resets the timeout timer
in the tester.
To transmit a ‘Response Correctly Received - Response Pending’ response the application
has  to  call  the  DescForceRcrRpResponse()  function.  To  be  sure  this  response  is
transmitted,  the  application  has  to  wait  for  the  transmission  confirmation  of  this  forced
RCR-RP  response  (the  function  ApplDescRcrRpConfirmation).  Depending  on  its
transmission  status  parameter  the  application  can  decide  how  the  processing  shall
continue (a jump to FBL or to close the request processingth negative response).

2013, Vector Informatik GmbH
Version: 3.07.00
117 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.12.1 DescForceRcrRpResponse()
DescForceRcrRpResponse
Available since 2.11.00
Is Reentrant

Is callback

Prototype
Single Context
void DescForceRcrRpResponse(void)
Multi Context
void DescForceRcrRpResponse(vuint8 iContext)
Parameter
iContext
reference to the corresponding request context
Return code
-
-
Functional Description
Calling this function the application can force CANdesc to send immediately (not later than
the next call of DescTask() function) a RCR-RP response.
Pre-conditions
CANdesc was configured to use this option (enabled in the GENtool).
Call context
Task or interrupt.
Particularities and Limitations
 This function can be called:
after a call of a MainHandler function (e.g. ApplDescCheckSessionTransition())
and until the call of ApplDescResponsePendingOverrun() or
ApplDescResponsePendingOvertimed() orpConfirmation().

2013, Vector Informatik GmbH
Version: 3.07.00
118 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.12.2 ApplDescRcrRpConfirmation()
ApplDescRcrRpConfirmation
Available since 2.11.00
Is callback

Prototype
Single Context
void ApplDescRcrRpConfirmation(vuint8 status)
Multi Context
void ApplDescRcrRpConfirmation(vuint8 iContext, vuint8 status)
Parameter
iContext
Reference to the corresponding request context
status
If the transmission was successful, the parameter value will be
kDescOk. Otherwise – kDescFailed.
Return code
-
-
Functional Description
Once the RCR-RP response has been forced, this function will be called in any case. The
transmission status is reported by the status parameter.
Pre-conditions
CANdesc was configured to use this option (enabled in the GENtool).
Call context
CAN Driver TX-ISR  TP Confirmation  this function
Particularities and Limitations
 Be aware of time consuming implementation for this function (interrupt call context).

12.6.13 DynamicallyDefineDataIdentifier ($2C) (UDS) functions
Since this feature is only for some OEM available, please refer to the OEM specific documentation
to find out if is applicable for your configuration.

2013, Vector Informatik GmbH
Version: 3.07.00
119 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.13.1 DescMayCallStateTaskAgain()
DescMayCallStateTaskAgain
Available since 4.00.00
Is Reentrant

Is callback

Prototype
Single Context
DescBool DescMayCallStateTaskAgain (void)
Multi Context
DescBool DescMayCallStateTaskAgain (void)
Parameter
-
-
Return code
kDescTrue
TRUE if you may call again the state task within this application
task cycle.
kDescFalse
FALSE if the DescStateTask() must not be called again.
Functional Description
Motivation: The DescStateTask() can be called as fast as possible but it still can not be
enough fast for complex service processing (e.g. DDIDs containing long descriptions) to
match fast timing-performance requirements. This function provides the info if the
application may call again the state-task in the same task context without causing endless
loop (important for non-preemptive OS environments).
Example of the API usage:
void ApplDiagTask(void) /* application function called as fast as possible */
{
do /* pump the state task as long as needed */
{
DescStateTask();
}
while(DescMayCallStateTaskAgain() == kDescTrue);
}
Pre-conditions
- Preprocessor define “DESC_ENABLE_HIPERFORMANCE_DYNDID_MODE” is
available (using user-config file in GENtool).
- The application uses the split-task concept (i.e. calls DescState-/TimerTask() instead of
DescTask()).
Call context
Background-loop level or OSEK-OS Task. The Task should have a lower or equal priority
than all other interaction to the CANdesc component.
Particularities and Limitations


2013, Vector Informatik GmbH
Version: 3.07.00
120 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.13.2 ApplDescCheckDynDidMemoryArea()
ApplDescCheckDynDidMemoryArea
Available since 3.02.00
Must be Reentrant

Is callback

Prototype
Any Context
DescDynDidMemCheckResult ApplDescCheckDynDidMemoryArea (
DescDynDidMemBlockAddress srcAddr,
DescDynDidMemBlockSize len );
Parameter
srcAddr
Start address (Service $2C 02 request parameter ‘memoryAddress’).
len
Length of block to read (Service $2C 02 request parameter
‘memorySize’).
Return code
memBlockOk
Permit the access to requested memory block and extend the DDID.
memBlockInvAddress
Forbid the access due invalid requested memory address
(requestOutOfRange).
memBlockInvSize
Forbid the access due invalid requested block length
(requestOutOfRange).
memBlockInvSecurity
Forbid the access due current security mode settings prohibit the DDID
definition (securityAccessDenied).
memBlockInvCondition  Forbid the access due other restrictions (conditionsNotCorrect).
If the memory access if forbidden, the Service $2C Request is negative responded with NRC 22
(conditionsNotCorrect), 31 (requestOutOfRange) or 33 (securityAccessDenied).
Functional Description
This callback function is triggered when defining a DDID that shall read bytes from the ECU’s
memory (Service Request $2C 02). The application can permit the (re-)definition of the DDID or
forbid it.
The service request is responded according to this.
The application must check
  if the given srcAddr and following len bytes are valid ECU addresses and if they are
readable,
  if the current security state allows to define the DDID right now,
  if there are other conditions that may forbid the definition of the DDID.
If all checks allow the DDID definition, the callback function must return memBlockOk.
FYI: When later reading the defined DDIDs by service $22, the standard checks [of Service $23
ReadMemoryByAddress] are executed, that perform security checks before accessing the
memory.
So, above security check with service $2C shall prove that the current security state permits the
definition of the DDID, the security check in service $22 (resp. $23) proves [in the context of the
then existing security state] the actual reading of the memory range.
Pre-conditions
-
2013, Vector Informatik GmbH
Version: 3.07.00
121 / 164
based on template version 5.1.0

Technical Reference CANdesc
Call context
From DescTask()
Particularities and Limitations


12.6.13.3 Non-volatile memory support
For  some  car-manufactures  CANdesc  provides  NVRAM  support  for  the  dynamically
defined DID definitions. There are some APIs that must be operated and some call-backs
to be implemented by the application in order to get the NVRAM support fully operational.

The following diagrams show the two oeprations on NVRAM – restore (at power on) and st
ore (usuall prior power off) data.

Restore data at ECU power on

Caution
At each CANdesc initialization (e.g. ECU reset/ power on) the “restore” procedure must
  be performed!
2013, Vector Informatik GmbH
Version: 3.07.00
122 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 12-1 DynDID definition restore and tester interaction

2013, Vector Informatik GmbH
Version: 3.07.00
123 / 164
based on template version 5.1.0

Technical Reference CANdesc
Store data at ECU power down

Info
The store operation can be performed at any time not only at power down.

Figure 12-2 Store DynDID definitions

2013, Vector Informatik GmbH
Version: 3.07.00
124 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.13.3.1 DescDynDefineDidPowerUp()
DescDynDefineDidPowerUp
Available since 5.06.09
Is Reentrant

Is callback

Prototype
Single Context
void DescDynDefineDidPowerUp (void)
Multi Context
void DescDynDefineDidPowerUp (void)
Parameter
-
-
Return  code
-
-
Functional Description
Once the ECU has been powered one/reset or just need to be reinitialized, this API must
be called to restore the dynamically defined DID content.

Usually called after the NVRAM manager is initialized.
Pre-conditions
- Service 0x2C needs to store the DynDID definitions to the NVRAM (OEM specific
requirement)
Call context
- any
Particularities and Limitations
  Must be called after DescInitPowerOn().

2013, Vector Informatik GmbH
Version: 3.07.00
125 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.13.3.2 DescDynIdMemContentRestored ()
DescDynIdMemContentRestored
Available since 5.06.09
Is Reentrant

Is callback

Prototype
Single Context
void DescDynIdMemContentRestored (DescDynDidStorageInfo storageInfo)
Multi Context
void DescDynIdMemContentRestored (DescDynDidStorageInfo storageInfo)
Parameter
storageInfo.nvData
Not used
The size (in bytes) of the restored table.
storageInfo.nvDataSize

The stored checksum, calculated by CANdesc at store time.
storageInfo.checkSum
Return  code
-
-
Functional Description
After CANdesc has requested the application to restore the DynDID data
(“ApplDescRestoreDynIdMemContent ()”), this API must be called to notify CANdesc that
the DynDID content has been restored and can be used.

Pre-conditions
- Service 0x2C needs to store the DynDID definitions to the NVRAM (OEM specific
requirement)
Call context
- any
Particularities and Limitations
  none

2013, Vector Informatik GmbH
Version: 3.07.00
126 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.13.3.3 DescDynDefineDidPowerDown ()
DescDynDefineDidPowerDown
Available since 5.06.09
Is Reentrant

Is callback

Prototype
Single Context
void DescDynDefineDidPowerDown (void)
Multi Context
void DescDynDefineDidPowerDown (void)
Parameter
-
-
Return  code
-
-
Functional Description
If the ECU has to be reset or just power off /shutdown, this API must be called to store the
current DID definitions.

In order to save E2PROM write cycles, the application may perform compare to the
current E2PROM content and decide whether to store the table content or not.
Pre-conditions
- Service 0x2C needs to store the DynDID definitions to the NVRAM (OEM specific
requirement)
Call context
- any
Particularities and Limitations
  Shall be called prior power-down/shutdown execution
  May be called any time to store the current content of the DynDID tables.

2013, Vector Informatik GmbH
Version: 3.07.00
127 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.13.3.4 ApplDescStoreDynIdMemContent ()
ApplDescStoreDynIdMemContent
Available since 5.06.09
Is Reentrant

Is callback

Prototype
Single Context
void ApplDescStoreDynIdMemContent (DescDynDidStorageInfo storageInfo)
Multi Context
void ApplDescStoreDynIdMemContent (DescDynDidStorageInfo storageInfo)
Parameter
storageInfo.nvData
The pointer to the data to be stored;
The size (in bytes) of the table;
storageInfo.nvDataSize

The checksum value, calculated by CANdesc, to be stored.
storageInfo.checkSum
Return  code
-
-
Functional Description
Once this API is called by CANdesc, the application must trigger a write E2PROM
procedure to store the data given by CANdesc and the checksum value.

In order to save E2PROM write cycles, the application may perform compare to the
current E2PROM content and decide whether to store the table content or not.

Pre-conditions
- Service 0x2C needs to store the DynDID definitions to the NVRAM (OEM specific
requirement)
Call context
- any
Particularities and Limitations
  CANdesc does not keep the data pointed by the parameter pointer during the write
operation! The application must mirror the data if needed!

2013, Vector Informatik GmbH
Version: 3.07.00
128 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.13.3.5 ApplDescRestoreDynIdMemContent ()
ApplDescRestoreDynIdMemContent
Available since 5.06.09
Is Reentrant

Is callback

Prototype
Single Context
void ApplDescRestoreDynIdMemContent (DescDynDidStorageInfo storageInfo)
Multi Context
void ApplDescRestoreDynIdMemContent (DescDynDidStorageInfo storageInfo)
Parameter
storageInfo.nvData
The pointer to the data to where the stored data shall be written
The size (in bytes) of the table expected.
storageInfo.nvDataSize

Not used
storageInfo.checkSum
Return  code
-
-
Functional Description
Once this API is called by CANdesc, the application must trigger a read E2PROM
procedure to restore the data for CANdesc and the checksum value.

Once the read process has completed, the API “DescDynIdMemContentRestored ()” must
be called to acknowledge the operation status to CANdesc.
Pre-conditions
- Service 0x2C needs to store the DynDID definitions to the NVRAM (OEM specific
requirement)
Call context
- any
Particularities and Limitations


2013, Vector Informatik GmbH
Version: 3.07.00
129 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.14 Memory Access Callbacks
12.6.14.1 ApplDescReadMemoryByAddress()
ApplDescReadMemoryByAddress
Available since 5.06.04
Is Reentrant

Is callback

Prototype
Any Context
void ApplDescReadMemoryByAddress (DescMsgContext* pMsgContext,
t_descMemByAddrInfo* pMemInfo)
Parameter
pMsgContext
Refer the section 12.6.4.2 Service MainHandler for details
about this parameter.
pMsgContext->resData
The response buffer pointer
pMsgContext->resDataLen  The actual response length
pMemInfo->address
The address to read from
pMemInfo->length
The number of bytes to read
Return  code
-
-
Functional Description
This callback is called for read memory by address requests. The application has to do
following:

Perform memory block validation (negative response can be set by calling
DescSetNegResponse()).

Optional: Perform additional state validations (negative response can be set by
calling DescSetNegResponse()).

Copy the requested memory contents into the response buffer.

Set the response data length to the number of bytes copied.

Confirm that the processing is finished (by calling DescProcessingDone()).
Pre-conditions
  The read memory by address service is supported.
  Refer to chapter 9.3 Read/Write Memory by Address (SID $23/$3D) (UDS) for more
details of the availability of this API. If you don’t see this API provided in desc.h, then
this feature is not supported for your project.
Call context
From DescTask()
Particularities and Limitations
  To call this handler periodically, ‘DescStartMemByAddrRepeatedCall’ needs to be used

2013, Vector Informatik GmbH
Version: 3.07.00
130 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.14.2 ApplDescWriteMemoryByAddress()
ApplDescWriteMemoryByAddress
Available since 5.06.04
Is Reentrant

Is callback

Prototype
Any Context
void ApplDescWriteMemoryByAddress (DescMsgContext* pMsgContext,
t_descMemByAddrInfo* pMemInfo)
Parameter
pMsgContext
Refer the section 12.6.4.2 Service MainHandler for details
about this parameter.
pMsgContext->reqData
The pointer to the data to store
pMemInfo->address
The address to write to
pMemInfo->length
The number of bytes to write
Return  code
-
-
Functional Description
This callback is called for write memory by address requests. The application has to do
following:

Perform memory block validation (negative response can be set by calling
DescSetNegResponse()).

Optional: Perform additional state validations (negative response can be set by
calling DescSetNegResponse()).

Copy the provided data into the memory area.

Confirm that the processing is finished (by calling DescProcessingDone()).
Pre-conditions
  The write memory by address service is supported.
  Refer to chapter 9.3 Read/Write Memory by Address (SID $23/$3D) (UDS) for more
details of the availability of this API. If you don’t see this API provided in desc.h, then
this feature is not supported for your project.
Call context
From DescTask()
Particularities and Limitations
  To call this handler periodically, ‘DescStartMemByAddrRepeatedCall’ needs to be used

12.6.15 Flash Boot Loader Support
CANdesc provides some features to comply with the HIS flash boot loader procedures.
These features are not released for all OEMs so if the below listed APIs are not available
in your CANdesc version, then for the OEM, you currently use CANdesc, does not require,
resp. has another FBL procedures.
2013, Vector Informatik GmbH
Version: 3.07.00
131 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.15.1 DescSendPosRespFBL()
DescSendPosRespFBL
Available since 4.05.00
Is Reentrant

Is callback

Prototype
Any Context
void DescSendPosRespFBL (t_descFblPosRespType posRespSId)
Parameter
posRespSId
One of the following values are allowed:
  kDescSendFblPosRespEcuHardReset
  kDescSendFblPosRespDscDefault.
Return code
-
-
Functional Description
The application shall call this function as soon as possible after the initialization of the
CANdesc component is done and the ECU is able to communicate.

Once this function called, CANdesc will try to send the corresponding positive response
as follows:
  kDescSendFblPosRespEcuHardReset – a positive response to EcuHardReset ($51
$01) will be sent.
  kDescSendFblPosRespDscDefault – a positive response to DiagnosticSessionControl
Default session ($50 $01 $P2time $P2Star/10) will be sent.

If CANdesc is currently busy with a new tester request, there will be no response sent by
this API.
Pre-conditions
The FBL positive response feature is supported.
Call context
Any.
Particularities and Limitations
  See 13.8

2013, Vector Informatik GmbH
Version: 3.07.00
132 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.15.2 ApplDescInitPosResFblBusInfo()
ApplDescInitPosResFblBusInfo
Available since 5.07.04
Is Reentrant

Is callback

Prototype
Any Context
vuint8 ApplDescInitPosResFblBusInfo (t_descUsdtNetBus* pBusInfo)
Parameter
pBusInfo
Reference to the bus information structure that will be
initialized here.
pBusInfo->busType
The bus driver that will send the response
pBusInfo->comChannel
The communication channel on which the response will be
sent. (relevant only on multi channel systems)
pBusInfo->testerId
The tester address which will be respond to. (relevant only on
bus systems with source/target addresses)
Return  code
kDescOk
Operation was successful, the FBL positive response will be
sent.
kDescFailed
Operation failed – no FBL positive response will be sent.
Functional Description
This callback is called once the application decided to call the API DescSendPosRespFBL
to get the concrete addressing information.

The application shall initialize only the parameter described above. The optional ones can
be skipped if not relevant on your system.

Pre-conditions
The FBL positive response feature is supported.
Call context
From DescSendPosRespFBL context.
Particularities and Limitations
  -

2013, Vector Informatik GmbH
Version: 3.07.00
133 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.16 Debug Interface / Assertion
12.6.16.1 ApplDescFatalError()
ApplDescFatalError
Available since 2.00.00
Is Reentrant

Is callback

Prototype
Single Context
void ApplDescFatalError (vuint8 errorCode, vuint16 lineNumber)
Multi Context
void ApplDescFatalError (vuint8 errorCode, vuint16 lineNumber)
Parameter
errorCode
The errorCode is a classification of the assertion. The
errorCodes can be also found in file ‘desc.h’. The errorCodes
are listed below:
lineNumber
A line number of file ‘desc.c’ from which this function is called.
Return  code
-
-
Functional Description
The CANdesc debug interface is similar to assertion constructof common programming
languages. Assertions are code checks which are written so that they should always
evaluate to true. If an assertion is false, it indicates a possible bug in the program, corrupt
system state or a misoperation of the user-interface.
CANdesc is calling the function ApplDescFatalError() function to indicate a evaluation of
an assertion to false. If this will happen it is recommended to halt the program's execution
immediately. This could be reach by an endless loop in that call-back.
The assertions can be disabled in the GenTool settings. The resource (ROM and runtime)
consumption can be reduced by disabling the assertions.
Error codes
kDescAssertWrongTpTxChannel (0x00):
The wrong TP channel is used – verify the TP interface to the CANdesc component

kDescAssertIndexTableInvalidReference (0x02):
Internal generation failure.

kDescAssertSvcTableUnreachableItem (0x03):
Internal generation failure.

kDescAssertSvcTableInvalidReference (0x04):
Internal generation failure.

2013, Vector Informatik GmbH
Version: 3.07.00
134 / 164
based on template version 5.1.0

Technical Reference CANdesc
kDescAssertSvcTableInconsistentNumber (0x05):
Internal generation failure.

kDescAssertMissingMainHandler (0x06):
Internal generation failure.

kDescAssertInvalidContextId (0x08):
Wrong iContext should be used - Check the consistency of the iContext parameter in the
application.

kDescAssertSvcTableIndexOutOfRange (0x09):
Internal generation failure.

kDescAssertSvcInstTableIndexOutOfRange (0x0A):
Internal generation failure.

kDescAssertContextIdWasModified (0x0B):
The iContext member of the pMsgContext parameter in the MainHandler functions are
illegal modified – verify the MainHandler functions in the application

kDescAssertProcessingDoneCallAfterResFlushing (0x0E):
DescProcessingDone() is called at least twice for one request – check the call of
DescProcessingDone() in the application.

kDescAssertTooLongSingleFrameResponse (0x0F):
Response lengthof a periodic DID is exceeding the SingleFrame length – check the
response length for periodic DIDs.

kDescAssertApplLackOfConfirmation (0x11):
The time for response processing is too long – verify if the call of DescProcessingDone()
is done in any case.

kDescAssertZeroStateValue (0x13):
The state parameter is zero – check state handling

kDescAssertInvalidContextMode (0x16):
Internal runtime error

kDescAssertUnexpectedWriteIntoRingBuffer (0x17):
DescRingBufferWrite() is called without activated ring-buffer

kDescAssertRingBufferWriteExceedsTheResLen (0x18):
DescRingBufferWrite() is called to often

2013, Vector Informatik GmbH
Version: 3.07.00
135 / 164
based on template version 5.1.0

Technical Reference CANdesc
kDescAssertIllegalUsageOfNegativeResponse (0x1A):
After call of DescProcessingDone() a negative response is set

kDescAssertDiagnosticBufferOverflow (0x1B):
currently not available

kDescAssertFuncReqWoResMayNotUseRingBuffer (0x1C):
It is not possible to use the ring-buffer feature for functional request (KWP only)

kDescAssertSchedulerTimerEventWithoutAnyPID (0x1E):
Internal runtime error

kDescAssertSchedulerRingBufferIsActivated (0x1F):
For periodic DIDs it is not possible to use the ring-buffer.

kDescAssertUnknownTpTransmissionType (0x21):
Internal runtime error

kDescAssertIllegalAddRequestCount (0x22):
Internal runtime error

kDescAssertNoSidCanBeReportedInIdleMode (0x23):
Call of DescGetSeriveId() while not a user-service is processed

kDescAssertInvalidUsageOfForceRcrRpApi (0x24):
The DescForceRcrRpResponse() function is used illegal.

kDescAssertPidResLenToCddDefNotMatched (0x26):
The response length set by the application do not fit to the response length defined in
CANdela (cdd).

kDescAssertPidResLenToCurrLinearFreeSpace (0x27):
Internal runtime error

kDescAssertMissingDataForTransmission (0x28):
Internal runtime error

kDescAssertSchedulerFreeCellNotFound (0x29):
Internal runtime error

kDescAssertInvalidStateParameterValue (0x2A):
The state parameter value is wrong – check state handling in your application

2013, Vector Informatik GmbH
Version: 3.07.00
136 / 164
based on template version 5.1.0

Technical Reference CANdesc
kDescAssertNoFreeICNChannel (0x2B):
Internal runtime error

kDescAssertInvalidDescICNClient (0x2C):
Internal runtime error

kDescAssertNoFreeMsgContext (0x2D):
Internal runtime error

kDescAssertUnExpectedContextWithResponse (0x2E):
A response will be sent out of a wrong context.

kDescAssertIllegalCallOfRingBufferCancel (0x2F):
The API DescRingBufferCancel() has been called for a response that is not using the ring-
buffer concept (e.g. DescRingBufferStart() was not called).

kDescNetAssertWrongIsoTpRxChannel (0x40):
The wrong TP channel is used – verify the TP interface to the CANdesc component

kDescNetAssertWrongIsoTpTxChannel (0x41):
The wrong TP channel is used – verify the TP interface to the CANdesc component

kDescNetAssertWrongBusType (0x42):
The wrong bus type is used – verify the TP interface to the CANdesc component

kDescAssertDescIcnIllegalTargetPointer (0x50):
Internal runtime assertion

Pre-conditions
At least on type of assertions are activated
Call context
Form ISR or task level. The interrupts might be disabled
Particularities and Limitations
  After a call of this function the system is not stable anymore. It can not be guaranteed
that this component or the whole system is still working in correct manner.
12.6.17 “Spontaneous Response” transmission

To implement the service $86 (Respone On Event) it is necessary to transmit a message
without a previous request. If the same CAN ID have to be used for this reponse as for the
diagnostics response, CANdesc provides an API to trigger the transmission.
2013, Vector Informatik GmbH
Version: 3.07.00
137 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.17.1 DescApplSendSpontaneousResponse()
DescApplSendSpontaneousResponse
Available since 6.09.00
Is Reentrant

Is callback

Prototype
Any Context
DescBool DescApplSendSpontaneousResponse(DescMsg resData,
DescMsgLen resLen,
t_descUsdtNetBus* pBusInfo)
Parameter
resData
Pointer to an application buffer with response data (including
posive response header).
resLen
Number of bytes to be sent (up to 4095 bytes).
pBusInfo
Reference to the bus information structure that will be initialized
here.
pBusInfo->busType
The bus driver that will send the response.
pBusInfo->comChannel
The communication channel on which the response will be sent.
(relevant only on multi channel systems).
pBusInfo->testerId
The tester address which will be respond to (relevant only on
bus systems with source/target addresses).
Return  code
kDescTrue
Operation was successful, the response will be sent.
kDescFalse
Operation failed – no response will be sent.
Functional Description
Calling this function the application can force CANdesc to send immediately a
spontaneous response.
If CANdesc is currently busy with a tester request, there will be no response sent by this
API and kDescFalse will be returned.
If this API returns kDescTrue, the application shall wait for the
ApplDescSpontaneousResponseConfirmation() prior initiating a new spontaneous
transmission.
Pre-conditions
CANdesc was configured to use this option (enabled in the GENtool). Only possible to
configure if Service 0x86 is contained in the cdd.
Call context
Task or interrupt.
Particularities and Limitations
  -

2013, Vector Informatik GmbH
Version: 3.07.00
138 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.17.2 ApplDescSpontaneousResponseConfirmation()
ApplDescSpontaneousResponseConfirmation
Available since 6.09.00
Is callback

Prototype
Single Context
void ApplDescSpontaneousResponseConfirmation(vuint8 status)
Multi Context
void ApplDescSpontaneousResponseConfirmation (vuint8 iContext, vuint8 status)
Parameter
iContext
Will be always “kDescPrimContext”.
status
If the transmission was successful, the parameter value will be
kDescOk. Otherwise – kDescFailed.
Return code
-
-
Functional Description
Once the spontaneous response has been successfully triggered (ref.
DescApplSendSpontaneousResponse()), this function will be called in any case. The
transmission status is reported by the status parameter.

Pre-conditions
Only available if the API DescApplSendSpontaneousResponse() is available.
Call context
CAN Driver TX-ISR  TP Confirmation  this function
Particularities and Limitations
 Be aware of time consuming implementation for this function (interrupt call context).
2013, Vector Informatik GmbH
Version: 3.07.00
139 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.18 Generic Processing Notifications
12.6.18.1 ApplDescManufacturerIndication
ApplDescManufacturerIndication
Available since 6.13.00
Is callback

Prototype
Single Context
void ApplDescManufacturerIndication(vuint8 sid,
vuint8* data,
vuint16 length,
vuint8 reqType,
t_descUsdtNetBus* pBusInfo)
Multi Context
void ApplDescManufacturerIndication(vuint8 iContext,
vuint8 sid,
vuint8* data,
vuint16 length,
vuint8 reqType,
t_descUsdtNetBus* pBusInfo)
Parameter
iContext
The current request context location
(used only as a handle - DO NOT MODIFY).
sid
The service identifier of the received service request.
data
Pointer to the first byte of the request data (without service
identifier byte).
length
Length of the request data (without service identifier byte)
reqType
The current request addressing method. Could be either
‚kDescFuncReq’ or ‚kDescPhysReq’ (bitmapped).
pBusInfo
The current request communication information (i.e. driver type
(CAN, MOST, FlexRay, etc.), addressing information,
communication channel number, tester address (if applicable)
etc.
Return code
-
-
Functional Description
This function is called right before CANdesc starts the processing of a received request.

2013, Vector Informatik GmbH
Version: 3.07.00
140 / 164
based on template version 5.1.0

Technical Reference CANdesc
Pre-conditions
Only available if the feature “Manufacturer Notification Support” is activated and CANdesc
UDS2012 is used.
Call context
From DescTask()
Particularities and Limitations

12.6.18.2 ApplDescManufacturerConfirmation
ApplDescManufacturerConfirmation
Available since 6.13.00
Is callback

Prototype
Single Context
void ApplDescManufacturerConfirmation(vuint8 status)
Multi Context
void ApplDescManufacturerConfirmation(vuint8 iContext,
vuint8 status)
Parameter
iContext
The current request context location
(used only as a handle - DO NOT MODIFY).
status
kDescPostHandlerStateOk
The positive response was transmitted successfully
kDescPostHandlerStateNegResSent
It was a negative response
kDescPostHandlerStateTxFailed
A transmission error occurred
Return  code
-
-
Functional Description
This function is called after the processing of a request has been finished, a response has
been sent (or sending has failed) and all service PostHandlers were called.

Pre-conditions
Only available if the feature “Manufacturer Notification Support” is activated and CANdesc
UDS2012 is used.
Call context
From DescTask ()
Particularities and Limitations

2013, Vector Informatik GmbH
Version: 3.07.00
141 / 164
based on template version 5.1.0

Technical Reference CANdesc
12.6.18.3 ApplDescSupplierIndication
ApplDescSupplierIndication
Available since 6.13.00
Is callback

Prototype
Single Context
void ApplDescSupplierIndication(vuint8 sid,
vuint8* data,
vuint16 length,
vuint8 reqType,
t_descUsdtNetBus* pBusInfo)
Multi Context
void ApplDescSupplierIndication(vuint8 iContext,
vuint8 sid,
vuint8* data,
vuint16 length,
vuint8 reqType,
t_descUsdtNetBus* pBusInfo)
Parameter
iContext
The current request context location
(used only as a handle - DO NOT MODIFY).
sid
The service identifier of the received service request.
data
Pointer to the first byte of the request data (without service
identifier byte).
length
Length of the request data (without service identifier byte)
reqType
The current request addressing method. Could be either
‚kDescFuncReq’ or ‚kDescPhysReq’ (bitmapped).
pBusInfo
The current request communication information (i.e. driver type
(CAN, MOST, FlexRay, etc.), addressing information,
communication channel number, tester address (if applicable)
etc.
Return code
-
-
Functional Description
This function is called during the processing of a request, after CANdesc has verified that
the requested service is allowed in the active session and security state.

2013, Vector Informatik GmbH
Version: 3.07.00
142 / 164
based on template version 5.1.0

Technical Reference CANdesc
Pre-conditions
Only available if the feature “Supplier Notification Support” is activated and CANdesc
UDS2012 is used.
Call context
From DescTask()
Particularities and Limitations

12.6.18.4 ApplDescSupplierConfirmation
ApplDescSupplierConfirmation
Available since 6.13.00
Is callback

Prototype
Single Context
void ApplDescSupplierConfirmation(vuint8 status)
Multi Context
void ApplDescSupplierConfirmation(vuint8 iContext,
vuint8 status)
Parameter
iContext
The current request context location
(used only as a handle - DO NOT MODIFY).
status
kDescPostHandlerStateOk
The positive response was transmitted successfully
kDescPostHandlerStateNegResSent
It was a negative response
kDescPostHandlerStateTxFailed
A transmission error occurred
Return  code
-
-
Functional Description
This function is called after the processing of a request has been finished, a response has
been sent (or sending has failed) and all service PostHandlers were called. It is called
before ApplDescManufacturerConfirmation().

Pre-conditions
Only available if the feature “Supplier Notification Support” is activated and CANdesc
UDS2012 is used.
Call context
From DescTask ()
Particularities and Limitations

2013, Vector Informatik GmbH
Version: 3.07.00
143 / 164
based on template version 5.1.0

Technical Reference CANdesc
13  How To…

13.1  …implement a protocol service MainHandler

//1. Read ProtocolService
// - dynamic length
// - PIDs

void DESC_API_CALLBACK_TYPE ApplDescManiOnTimerEvent_storeEvent(DescMsgContext*
pMsgContext)
{
  /* Check the length */
  if(pMsgContext->reqDataLen > 2)
  {
  /* Check the sub-parameters */
  vuint16 param;
  /* Compose one parameter combining the HiByte and the LoByte in this order*/
  param = DescMake16Bit(pMsgContext->reqData[0], pMsgContext->reqData[1]);

  /* Dispatch the parameter */
  switch(param)
  {
  case 0xFFFF:
  if(pMsgContext->reqDataLen != 0xFFFF)
  {
  /* Write some data (skip the parameter offsets 0 und 1) */
  pMsgContext->resData[2] = DescGetLoByte(0x1234);
  pMsgContext->resData[3] = DescGetHiByte(0x1234);
  /* Set the response length */
  pMsgContext->resDataLen = 4;
  }
  else
  {
  DescSetNegResponse(pMsgContext->iContext, kDescNrcInvalidFormat);
  }
  break;
  default:
  /* unknown parameter */
  DescSetNegResponse(pMsgContext->iContext, kDescNrcInvalidFormat);
  }
  }
  else
  {
  DescSetNegResponse(pMsgContext-iContext, kDescNrcInvalidFormat);
  }
  /* In this case we did everything in the main-handler */
  DescProcessingDone(pMsgContext->iContext);
}

//2. Read ProtocolService
// - dynamic length
// - sub-function
2013, Vector Informatik GmbH
Version: 3.07.00
144 / 164
based on template version 5.1.0

Technical Reference CANdesc

void DESC_API_CALLBACK_TYPE ApplDescManiOnTimerEvent_storeEvent(DescMsgContext*
pMsgContext)
{
  /* Check the length */
  if(pMsgContext->reqDataLen > 1)
  {
  /* Dispatch the sub-function */
  switch(pMsgContext->reqData[0])
  {
  case 0xFF:
  if(pMsgContext->reqDataLen != 0xFFFF)
  {
  /* Format check ok: write some data (skip the parameter) */
  pMsgContext->resData[1] = DescGetLoByte(0x1234);
  pMsgContext->resData[2] = DescGetHiByte(0x1234);
  /* Set the response length */
  /* Hint: if the response length wasn't set, zero value is assumed! */
  pMsgContext->resDataLen = 3;
  }
  else
  {
  /* Wrong sub-parameter format */
  DescSetNegResponse(pMsgContext->iContext, kDescNrcInvalidFormat);
  }
  break;
  default:
  /* Unknown sub-function */
  DescSetNegResponse(pMsgContext->iContext,
kDescNrcSubfunctionNotSupported);
  }
  }
  else
  {
  DescSetNegResponse(pMsgContext-iContext, kDescNrcInvalidFormat);
  }
  /* In this case we did everything in the main-handler */
  DescProcessingDone(pMsgContext->iContext);
}

//3. Write ProtocolService
// - dynamic length
// - PIDs

void DESC_API_CALLBACK_TYPE ApplDescManiOnTimerEvent_storeEvent(DescMsgContext*
pMsgContext)
{
  /* Check the sub-parameters */
  vuint16 param;

  /* Check the length */
  if(pMsgContext->reqDataLen > 2)
  {
  /* Compose one parameter combining the HiByte and the LoByte in this order
*/
  param = DescMake16Bit(pMsgContext->reqData[0], pMsgContext->reqData[1]);

  /* Dispatch the parameter */
  switch(param)
  {
2013, Vector Informatik GmbH
Version: 3.07.00
145 / 164
based on template version 5.1.0

Technical Reference CANdesc
  case 0xFFFF:
  if(pMsgContext->reqDataLen != 0xFFFF)
  {
  /* Copy from the request data to your application */
  /* Use the data pointed by: pMsgContext->reqData[2],
pMsgContext->reqData[3], etc.*/
  }
  else
  {
  DescSetNegResponse(pMsgContext->iContext, kDescNrcInvalidFormat);
  }
  break;
  default:
  /* unknown parameter */
  DescSetNegResponse(pMsgContext->iContext, kDescNrcRequestOutOfRange);
  }
  }
  else
  {
  DescSetNegResponse(pMsgContext-iContext, kDescNrcInvalidFormat);
  }
  /* In this case we did everything in the main-handler */
  /* Hint: if the response length wasn't set, zero value is assumed! */
  DescProcessingDone(pMsgContext->iContext);
}

//4. Write ProtocolService
// - dynamic length
// - Sub-function

void DESC_API_CALLBACK_TYPE ApplDescManiOnTimerEvent_storeEvent(DescMsgContext*
pMsgContext)
{
  /* Check the sub-parameters */
  vuint16 param;

  /* Check the length */
  if(pMsgContext->reqDataLen > 2)
  {
  /* Compose one parameter combining the HiByte and the LoByte in this order*/
  param = DescMake16Bit(pMsgContext->reqData[0], pMsgContext->reqData[1]);

  /* Dispatch the parameter */
  switch(param)
  {
  case 0xFFFF:
  if(pMsgContext->reqDataLen != 0xFFFF)
  {
  /* Copy from the request data to your application */
  /* Use the data pointed by: pMsgContext->reqData[2],
pMsgContext->reqData[3], etc.*/
  }
  else
  {
  DescSetNegResponse(pMsgContext->iContext, kDescNrcInvalidFormat);
  }
  break;
  default:
  /* unknown sub-function /
  DescSetNegResponse(pMsgContext->iContext,
2013, Vector Informatik GmbH
Version: 3.07.00
146 / 164
based on template version 5.1.0

Technical Reference CANdesc
kDescNrcSubfunctionNotSupported);
  }
  }
  else
  {
  DescSetNegResponse(pMsgContext-iContext, kDescNrcInvalidFormat);
  }
  /* In this case we did everything in the main-handler */
  /* Hint: if the response length wasn't set, zero value is assumed! */
  DescProcessingDone(pMsgContext->iContext);
}

13.2  …implement a service MainHandler

//5. Read Service
// - dynamic length
// - sub-function/PID

void DESC_API_CALLBACK_TYPE ApplDescManiOnTimerEvent_storeEvent(DescMsgContext*
pMsgContext)
{
  /* Check the length */
  if(pMsgContext->reqDataLen != 0xFFFF)
  {
  /* Format check ok: write some data */
  pMsgContext->resData[0] = DescGetLoByte(0x1234);
  pMsgContext->resData[1] = DescGetHiByte(0x1234);
  /* Set the response length */
  /* Hint: if the response length wasn't set, zero value is assumed! */
  pMsgContext->resDataLen = 2;
  }
  else
  {
  /* Wrong sub-function format */
  DescSetNegResponse(pMsgContext->iContext, kDescNrcInvalidFormat);
  }

  /* In this case we did everything in the main-handler */
  DescProcessingDone(pMsgContext->iContext);
}

//6. Read Service
// - static length
// - sub-function/PID

void DESC_API_CALLBACK_TYPE ApplDescManiOnTimerEvent_storeEvent(DescMsgContext*
pMsgContext)
{
  /* Format check ok: write some data */
  pMsgContext->resData[0] = DescGetLoByte(0x1234);
  pMsgContext->resData[1] = DescGetHiByte(0x1234);
  /* Set the response length */
  /* Hint: if the response length wasn't set, zero value is assumed! */
  pMsgContext->resDataLen = 2;

  /* In this case we did everything in the main-handler */
2013, Vector Informatik GmbH
Version: 3.07.00
147 / 164
based on template version 5.1.0

Technical Reference CANdesc
  DescProcessingDone(pMsgContext->iContext);
}

//7. Write Service
// - dynamic length
// - sub-function/PID

void DESC_API_CALLBACK_TYPE ApplDescManiOnTimerEvent_storeEvent(DescMsgContext*
pMsgContext)
{
  /* Check the length */
  if(pMsgContext->reqDataLen != 0xFFFF)
  {
  /* Format check ok: write some data */
  /* Copy from the request data to your application */
  /* Use the data pointed by: pMsgContext->reqData[0],
pMsgContext->reqData[1], etc.*/
  }
  else
  {
  /* Wrong sub-function format */
  DescSetNegResponse(pMsgContext->iContext, kDescNrcInvalidFormat);
  }

  /* In this case we did everything in the main-handler */
  /* Hint: if the response length wasn't set, zero value is assumed! */
  DescProcessingDone(pMsgContext->iContext);
}

//8. Write Service
// - static length
// - sub-function/PID

void DESC_API_CALLBACK_TYPE ApplDescManiOnTimerEvent_storeEvent(DescMsgContext*
pMsgContext)
{
  /* Copy from the request data to your application */
  /* Use the data pointed by: pMsgContext->reqData[0], pMsgContext->reqData[1],
etc.*/

  /* In this case we did everything in the main-handler */
  /* Hint: if the response length wasn't set, zero value is assumed! */
  DescProcessingDone(pMsgContext->iContext);
}

13.3  …implement a Signal Handler

//1. ReadSignalHandler
// - length <= 4Byte
// Limitations: No DescProcessingDone() or DescSetNegResponse() allowed.

vuintx DESC_API_CALLBACK_TYPE ApplDescGetTemp(void)
{
  /* Return directly the signal value */
  return (vuintx)0xFFFF;
2013, Vector Informatik GmbH
Version: 3.07.00
148 / 164
based on template version 5.1.0

Technical Reference CANdesc
}

//2. ReadSignalHandler
// - length > 4Byte
// Limitations: No DescProcessingDone() or DescSetNegResponse() allowed.

DescMsgLen DESC_API_CALLBACK_TYPE ApplDescGetTemp(DescMsg tgt)
{
  /* Copy the signal data into the buffer pointed by "tgt".*/
  /* Return the amount of written bytes */
  return 0;
}

//3. WriteSignalHandler
// - length <= 4Byte
// Limitations: No DescProcessingDone() or DescSetNegResponse() allowed.

void DESC_API_CALLBACK_TYPE ApplDescGetTemp(vuintx data)
{
  /* "data" contains the signal value as-is from the request.
Copy it into your application. */
}

//4. ReadSignalHandler
// - length > 4Byte
// Limitations: No DescProcessingDone() or DescSetNegResponse() allowed.

DescMsgLen DESC_API_CALLBACK_TYPE ApplDescGetTemp(DescMsg src)
{
  /* Copy the signal data from the buffer pointed by "src".*/
  /* Return the amount of copied bytes */
  return 0;
}

13.4  …implement a Packet Handler
//1. ReadPacketHandler
// Limitations: No DescProcessingDone() or DescSetNegResponse() allowed.

void DESC_API_CALLBACK_TYPE ApplDescGetTemp(DescMsg pMsg)
{
  /* Copy the signal value into the "pMsg" buffer. */
  pMsg[0] = DescGetLoByte(0x1234);
  pMsg[1] = DescGetLoByte(0x1234);
}

13.5  …implement a state transition function

//1. StateTransitionNotification
// Limitations: No DescProcessingDone() or DescSetNegResponse() allowed.
2013, Vector Informatik GmbH
Version: 3.07.00
149 / 164
based on template version 5.1.0

Technical Reference CANdesc

void DESC_API_CALLBACK_TYPE ApplDescOnTransitionSession(DescStateGroup
formerState, DescStateGroup newState)
{
/* You are just notified that this state group has performed a transition from
* "formerState" to the "newState". */
}

2013, Vector Informatik GmbH
Version: 3.07.00
150 / 164
based on template version 5.1.0

Technical Reference CANdesc
13.6 …work with the ring-buffer mechanism
13.6.1 with asynchronous write
TPMC
Desc
Appl_MainHandler
Appl_MainHandler_2
EEPROM
Appl_PostHandler
Driver
call
Analyze and validate request
It is not possible to write data as in
Write response length the standard way if a ring-buffer will
be used (standard way is, to write to
DescMsgContext->ResData)
DescRingBufferStart()
DescRingBufferWrite(* dataPtr, dataLength)
Now - it is possibel to
Enough data are
write data to the ring-buffer
stored in the
ring-buffer to start
the transmission
DescRingBufferWrite(* dataPtr, dataLength)
DescRingBufferWrite(* dataPtr, dataLength)
StartTransmission
Not enough free
bytes to write
new data
TP reads
asynchronous the
DescRingBufferGetFreeSpace
data out of the
ring-buffer
return countOfFreeBytesInRingBuffer
TpCopyToCan
DescRingBufferGetFreeSpace
return countOfFreeBytesInRingBuffer
DescRingBufferWrite(* dataPtr, dataLength)
TpCopyToCan
DescRingBufferGetProgress
return currentBytePosition
FinishTransmission
Call of Service Post Handler

//1. Read Service (with asynchronous Ring-Buffer)
// - static length
// - sub-function/PID

vuint8 g_iContext;

2013, Vector Informatik GmbH
Version: 3.07.00
151 / 164
based on template version 5.1.0

Technical Reference CANdesc
void DESC_API_CALLBACK_TYPE ApplDescReadDTC(DescMsgContext* pMsgContext)
{
  vuint8 lData;
  /* Format check already done by CANdesc */

  /* Analysis of request has to done by ECU application */

  /* Set the response length */
  pMsgContext->resDataLen = 16;

  /* Fill the first data */
  lData = 5;

  /* Store iContext for further interaction with CANdesc */
  g_iContext = pMsgContext->iContext;
  /* check only on services with sub-function (e.g. 0x19) */
  if(pMsgContext->msgAddInfo.suppPosRes != 0)
  {
  /* since no response required – skip further processing */
  DescProcessingDone(pMsgContext->iContext);
  }
else
  {
/* Now we have to set CANdesc into the Ring-Buffer mode */
DescRingBufferStart(pMsgContext->iContext);
/* Now it is possible to write into the Ring-Buffer */
DescRingBufferWrite(pMsgContext->iContext, &lData, 1);

/* Now trigger e.g. an EEPROM read event */
...
  }
}

EEPROM_TASK(xyz)
{
  vuint8 lDTC[3];

  ...
  /* Wait for EEPROM event */
  /* EEPROM event is finished with reading */
  {
  DescRingBufferWrite(g_iContext, &lDTC, 3);
  /* Now trigger next EEPROM reading */
  }
}

2013, Vector Informatik GmbH
Version: 3.07.00
152 / 164
based on template version 5.1.0

Technical Reference CANdesc
13.6.2  with synchronous write
Desc
Appl_MainHandler
Appl_MainHandler_2
EEPROM
Appl_PostHandler
Driver
call
Analyze and validate request
write response length
DescRingBufferStart
DescRingBufferWrite(* dataPtr, dataLength)
DescStartRepeatedServiceCall(&ApplMainHandler_2)
Within this function
Activate the
call the data can be
multiple service
written synchronous.
call to get a
periodic call from
CANdesc
call
GetEEPROMData
DescRingBufferWrite(* dataPtr, dataLength)
call
DescRingBufferGetFreeSpace
return countOfFreeBytesInRingBuffer
call
DescRingBufferGetFreeSpace
return countOfFreeBytesInRingBuffer
GetEEPROMData
DescRingBufferWrite(* dataPtr, dataLength)
PostHandler

//2. Read Service (with synchronous Ring-Buffer)
// - static length
// - sub-function/PID

extern void ApplDescReadDTC_AddOn(DescMsgContext* pMsgContext);

void DESC_API_CALLBACK_TYPE ApplDescReadDTC(DescMsgContext* pMsgContext)
{
  vuint8 lData;
  /* Format check already done by CANdesc */

2013, Vector Informatik GmbH
Version: 3.07.00
153 / 164
based on template version 5.1.0

Technical Reference CANdesc
  /* Analysis of request has to done by ECU application */

  /* Set the response length */
  pMsgContext->resDataLen = 16;

  /* Fill the first data */
  lData = 5;

  /* check only on services with sub-function (e.g. 0x19) */
  if(pMsgContext->msgAddInfo.suppPosRes != 0)
  {
  /* since no response required – skip further processing */
  DescProcessingDone(pMsgContext->iContext);
  }
else
{
    /* Now we have to set CANdesc into the Ring-Buffer mode */
    DescRingBufferStart(pMsgContext->iContext);
    /* Now it is possible to write into the Ring-Buffer */
    DescRingBufferWrite(pMsgContext->iContext, &lData, 1);

    /* Use RepeatedSeriveCall feature to poll e.g. EEPROM driver */
    DescStartRepeatedServiceCall(pMsgContext->iContext, &ApplDescReadDTC_AddOn);
}
}

void ApplDescReadDTC_AddOn(DescMsgContext* pMsgContext)
{
  vuint8 lDTC[3];
  DescMsgLen freeSpace;
  /* Check if enough space is free in ring-buffer */
  freeSpace = DescRingBufferGetFreeSpace();
  if (freeSpace >= 3)
  /* try to read from EEPROM */
  {
  /* Success - result is in lDTC */
  DescRingBufferWrite(pMsgContext->iContext, &lDTC, 3);
  }
  else
  {
  /* nothing to do, wait for next MainHandler call, ring-buffer is full */
  }
}

13.7  …prevent the ECU going to sleep while diagnostic is active
Most car manufactures have the requirement to keep the ECU alive while the diagnostic
layer is active; including a pending request or a non-default session is currently active.
This  requirement  is handled  by  CANdesc for  some  car  manufactures  (see  OEM  specific
TechnicalReference_CANdesc document for details)
The  following  code  example  shows  all  necessary  steps  to  keep  the  ECU  alive  while
diagnostic jobs are running (e.g. non-default session):
{
  DescContextActivity lActivity;
2013, Vector Informatik GmbH
Version: 3.07.00
154 / 164
based on template version 5.1.0

Technical Reference CANdesc
  DescStateGroup lState;

  lAcitvity = DescGetActivityState();
  lState = DescGetStateSession();

  /* check for a pending request or a non-default session */
  if ( ((lState & kDescStateSessionDefault) == 0) ||
(lActivity != kDescContextIdle) )
  {
  /* Force to stay alive */
  }
  else
  {
  /* Ready for sleeping */
  }
}
13.8  …send a positive response without request after FBL flash job
According to some specifications the application has to send a positive response either to
“diagnostic  session  control  –  default  session”  or  “ECU  reset  –  hard  reset”  after  a
successful  flash  job  without  a  request.  The  Flash  Boot  Loader  has  to  set  a  flag  (reset
response  flag)  in  RAM  or  EEPROM  which  has  to  be  evaluated  by  the  application  at
startup.  Depending  on  its  value  the  application  has  to  call  the  CANdesc  function
DescSendPosRespFBL() with the appropriate response ID.
CANdesc provides the API DescSendPosRespFBL() for this purpose.
Due  to  bus  communication  is  necessary  to  send  the  positive  response;  some  limitations
have to be handled by the application:
1) Bus communication is to be requested by the application
2) If bus communication is possible, the application has to call DescSendPosRespFBL().
CANdescBasic will send the positive response.
3) The application will be called (ApplDescInitPosResFblBusInfo()) to provide the concrete
addressing information of the response.
4) Bus communication can be released by the application.
13.9  …enforce CANdesc to use ANSI C instead of hardware optimized bit type
CANdesc  uses  per  default  the  bit-type  definition  provided  by  the  CANdriver,  since  it  is
selected  as  optimal  for  the  concrete  CPU.  On  this  way  the  CANdesc  ROM  and  RAM
resource consumption is kept as low as possible.
Due to the complexity of some CANdesc data structures there can be problems on certain
compilers with special bit-structure compiler options.
If you encounter such problems either at compile or at run-time, you can turn the ANSIC C
bit-type support in CANdesc on. To do that, just add a user configuration file in GENy with
the following content:
#define DESC_USE_ANSI_C_BIT_TYPE

2013, Vector Informatik GmbH
Version: 3.07.00
155 / 164
based on template version 5.1.0

Technical Reference CANdesc
13.10  …configure Extended Addressing
If Extended Addressing is used as TP Addressing mode some additional settings have to
be done.  “DescCheckTA” has to be set for the “Target Address Message Filter” in GENy.

Figure 13-1 GENy TP configuration
Additional  a  user  configuration  file  has  to  be  used  to  configure  the  functional  target
address. An example for the content of the user configuration file is given below.

#define kDescOemExtAddrFuncTargetAddr 0xFE
13.11  …use Multiple Addressing
This  chapter  is  a  short  summary  of  additional  information  that  the  application  has  to
provide for CANdesc if the Tp addressing mode is Multiple Addressing.
In the case that a positive response has to be send after FBL flash job of the application,
please  assure  that  the  correct  addressing  information  are  provided  in  the  callback
ApplDescInitPosResFblBusInfo().
Furthermore, the “Rx Get Buffer” and “Rx Indication” functions have to be redirected to the
application if one of the Tp Addressing modes is Normal Addressing. This can be done in
the  GENy  configuration  of  the  TP,  a  callback  name  different  from  the  one  that  is
implemented in CANdesc has to be entered.

2013, Vector Informatik GmbH
Version: 3.07.00
156 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 13-2 GENy TP callbacks
The  callbacks  have  to  be  implemented  in  the  application.  In  the  Get  Buffer  function  the
CAN Id has to be set for the FC in the case of Normal Addressing,

/* Example: A configuration with only CANdesc Tp connections and only one Tp
Tx/Rx channel. */
TP_MEMORY_MODEL_DATA canuint8* DispatcherDescGetBuffer(canuint8 tpChannel,
canuint16 datLen)
{
  TP_MEMORY_MODEL_DATA canuint8* retPtr = V_NULL;

  retPtr = DescGetBuffer(tpChannel, datLen);

if(retPtr != V_NULL)
{
  if((TpRxGetAddressingFormat(tpChannel) == kTpNormalAddressing))
  {
         /* kApplNormalAddressingTxId, have to defined by the application*/
  TpRxSetTransmitID(tpChannel, kApplNormalAddressingTxId);
  }
}

return retPtr;
}

2013, Vector Informatik GmbH
Version: 3.07.00
157 / 164
based on template version 5.1.0

Technical Reference CANdesc
The  response  ID  for  Normal  Addressing  has  to  be  set  in  the  Indication  function.  The
response Id has to be set after the call of DescPhysReqInd().

/* Example: A configuration with only CANdesc Tp connections and only one Tp
Tx/Rx channel. */
void DispatcherDescPhysReqInd(canuint8 tpChannel, canuint16 datLen)
{
  vuint8 addressingType = (TpRxGetAddressingFormat(tpChannel));

  DescPhysReqInd(tpChannel, datLen);

  /*Set CAN IDs for the Response*/
  if(addressingType == kTpNormalAddressing)
  {
/* kApplNormalAddressingTxId and kApplNormalAddressingPhysRxId, have to
defined by     the   application*/
TpTxSetChannelID(0 /*tpTxChannel*/, kApplNormalAddressingTxId,
kApplNormalAddressingPhysRxId);
/* tpTxChannel = 0 is only possible because only one Tx Channel is
configured.*/
  }
}

13.12  …use “Dynamic Normal Addressing Multi TP” with multiple tester
This  chapter  is  a  short  summary  of  additional  information  that  the  application  has  to
provide for CANdesc if the Tp addressing mode is “Dynamic Normal Addressing Multi TP”
with more than one tester.
In the case that a positive response has to be send after FBL flash job of the application,
please  assure  that  the  correct  addressing  information  are  provided  in  the  callback
ApplDescInitPosResFblBusInfo().
Furthermore, the “Rx Get Buffer” function has to be redirected to the application. This can
be done in the GENy configuration of the TP, a callback name different from the one that is
implemented in CANdesc has to be entered.
2013, Vector Informatik GmbH
Version: 3.07.00
158 / 164
based on template version 5.1.0

Technical Reference CANdesc

Figure 13-3 GENy TP callbacks (physical addressing)

The  “Get  Buffer”  function  of  the  functional  connection  has  to  be  redirected  to  the
application too.

Figure 13-4 GENy TP callbacks (functional addressing)

The callbacks have to be implemented in the application.  The received CAN ID has to be
mapped to the  corresponding transmit CAN ID and the TP connection number has to be
set in the xxxGetBuffer callback:
2013, Vector Informatik GmbH
Version: 3.07.00
159 / 164
based on template version 5.1.0

Technical Reference CANdesc
TP_MEMORY_MODEL_DATA canuint8* DispatcherDescGetBuffer(canuint8 tpChannel,
canuint16 datLen)
{
  TP_MEMORY_MODEL_DATA canuint8* retPtr = V_NULL;

  switch(TpRxGetChannelID(tpChannel))
  {
  case kDispatcherRxDiagPhysCanId:
  TpRxSetTransmitID(tpChannel, kDispatcherTxDiagPhysCanId);
  TpRxSetConnectionNumber(tpChannel, kDescDiagConnection);
  retPtr = DescGetBuffer(tpChannel, datLen);
  break;

  case kDispatcherRxDiagAddPhysCanId:
  TpRxSetTransmitID(tpChannel, kDispatcherTxDiagAddPhysCanId);
  TpRxSetConnectionNumber(tpChannel, kDescDiagAddConnection);
  retPtr = DescGetBuffer(tpChannel, datLen);
  break;

  default:
  ;
  }
  return retPtr;
}

The  receiced  CAN  ID  has  to  be  mapped  to  the  corresponding  transmit  CAN  ID  in  the
xxxGetFuncBuffer callback.  Furthermore it is important, that  the physical Rx ID is set for
the response and not the functional one. This CAN ID is used to recognize the FC of the
tester in case of a multiframe response:
TP_MEMORY_MODEL_DATA canuint8* DispatcherDescGetFuncBuffer(vuint16 dataLength)
{
  TP_MEMORY_MODEL_DATA canuint8* retPtr = V_NULL;

  switch(TpFuncGetReceiveCanID())
  {
  case kDispatcherRxDiagFunc:
  TpFuncSetTransmitCanID(kDispatcherTxDiagPhysCanId);
  TpFuncSetReceiveCanID(kDispatcherRxDiagPhysCanId);
  retPtr = DescGetFuncBuffer(dataLength);
  break;

  case kDispatcherRxDiagAddFunc:
  TpFuncSetTransmitCanID(kDispatcherTxDiagAddPhysCanId);
  TpFuncSetReceiveCanID(kDispatcherRxDiagAddPhysCanId);
  retPtr = DescGetFuncBuffer(dataLength);
  break;

  default:
  ;
  }

  return retPtr;
}

2013, Vector Informatik GmbH
Version: 3.07.00
160 / 164
based on template version 5.1.0

Technical Reference CANdesc
The code examples above are for 2 testers, in the example are some defines used that
have to be provided by the application corresponding to the configuration.

Define
Description
kDispatcherRxDiagPhysCanId
Physical request CAN ID of the first tester
kDispatcherRxDiagFuncCanId
Functional request CAN ID of the first tester
kDispatcherTxDiagPhysCanId
Response CAN ID of the first tester
kDispatcherRxDiagAddPhysCanId
Physical request CAN ID of the second tester
kDispatcherRxDiagAddFuncCanId
Functional request CAN ID of the second tester
kDispatcherTxDiagAddPhysCanId
Response CAN ID of the second tester
kDispatcherTxDiagTpChannel
Transmit Tp Channel of CANdesc. If only one
Tp Channel is used, it is has to be set to zero.

2013, Vector Informatik GmbH
Version: 3.07.00
161 / 164
based on template version 5.1.0

Technical Reference CANdesc
14  Related documents

Abbreviation  File Name
Description
/KWP2000/

Keyword 2000 protocol
/TPMC/

User  manual  of  the  multi-connection  transport  layer
module.  The  transport  layer  is  implemented
according to /ISO 15765/
/ISO 15765/
This  ISO  standard  describes  diagnostics  and
diagnostics on CAN.
Note: If no file name is given, the document is not provided by Vector.

2013, Vector Informatik GmbH
Version: 3.07.00
162 / 164
based on template version 5.1.0

Technical Reference CANdesc
15  Glossary

Abbreviation  Description
CANdb
CAN database by Vector which is used by Vector tools.
CANdesc
CAN diagnostics embedded software component
CDD
CANdela Diagnostic Database
CF
Consecutive Frame (transport protocol frame)
CCL
Communication Control Layer
DBC
CAN database format of the Vector company, which is used by the
GENtool to gather information about the ECUs in the network, their
communication relations, message definitions, signals of
messages, network related information (e.g. manufacturer type,
network management type, etc.).
ECU
Electronic Control Unit
FBL
Flash Boot Loader
KWP 2000
Keyword Protocol 2000
OSEK
German  abbreviation,  “Offene  Systeme  und  deren  Schnittstellen
für die Elektronik im Kraftfahrzeug”, means “open systems and the
corresponding interfaces for automotive electronics”
RCR-RP
Request Correctly Received – Response Pending
SF
Single Frame
SID
Service Identifier
SPRMIB
Suppress Positive Response Message Indication Bit
TP
Transport Protocol
UDS
Unified Diagnostic Services
VSG
Vehicle System Group

2013, Vector Informatik GmbH
Version: 3.07.00
163 / 164
based on template version 5.1.0

Technical Reference CANdesc
16  Contact
Visit our website for more information on

>  News
>  Products
>  Demo software
>  Support
>  Training data
>  Addresses

www.vector.com
2013, Vector Informatik GmbH
Version: 3.07.00
164 / 164
based on template version 5.1.0

Document Outline

32 - TechnicalReference_Database_Attributes_GM

Database Attributes GMLAN V3.0

33 - TechnicalReference_Database_Attributes_GM_ind

Outline
Page 1
Page 2
Page 3
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13
Page 14
Page 15
Page 16
Page 17
Page 18
Page 19
Page 20
Page 21

34 - TechnicalReference_Database_Attributes_GMs

Database Attributes
Technical Reference

GMLAN 3.1
Version 2.02.01

Authors
Frank Triem
Versions:
2.02.01
Status:
Released

Technical Reference Database Attributes

1  Document Information
1.1
History
Author
Date
Version
Remarks
Frank Triem
2007-06-06
1.0
Creation of document based on “Database
Attributes GMLAN V3.0”.
Frank Triem
2007-06-25
1.1
Database Attribute
GenMsgMandatoryToSupervise corrected
Frank Triem
2008-01-23
2.0
Update for configuration tool GENy
Frank Triem
2008-02-06
2.1
Database attributes added
- Baudrate
- SamplePointMin
- SamplePointMax
- SyncJumpWidthMin
- SyncJumpWidthMax
Frank Triem
2012-10-23
2.2
Database Attribute NodeSuprvStabilityTime
added in chapter 3.2
Frank Triem
2013-01-28
2.02.01
ESCAN00064577: Update GMLAN version
from GMLAN 3.0 to GMLAN 3.1
Table 1-1   History of the Document

Please note
We have configured the programs in accordance with your specifications in the

questionnaire. Whereas the programs do support other configurations than the one
specified in your questionnaire, Vector’s release of the programs delivered to your
company is expressly restricted to the configuration you have specified in the
questionnaire.
2013, Vector Informatik GmbH
Version: 2.02.01
2 / 21
Based on template version 2.8

Technical Reference Database Attributes

2 Introduction
This document describes the database attributes that are used by the configuration and
generation tool GENy for the configuration of the GMLAN Handler. In chapter 3 all possible
attributes are listed along with a description of how the attributes should be set for use with
GMLAN.
A list of database base attributes that can be found in the GM databases, which are not
used by GENy, can be found in chapter 6. Please note that this is not a complete list of all
available database attributes.

Caution
This document is valid for GMLAN 3.1 and Nm_Gmlan_Gm version 4.02.00 and higher.

2013, Vector Informatik GmbH
Version: 2.02.01
5 / 21
Based on template version 2.8

Technical Reference Database Attributes

3  Attribute Definitions for GMLAN 3.1 Databases
3.1
Network Attributes
On the network level the following attributes are evaluated by GENy:
Name
Type
Description
Manufacturer
String
This is a fixed value and must be set to “GM”
Default: “GM”
NmType
String
Must be set to “GMLAN” to define the GMLAN
network management.
Default:
“GMLAN”
NmBaseAddress
Hexadecimal  Defines the base address for the VNMF. This
value is usually set to 0x620 to declare a range of
0x620-0x63F in the CAN-identifier range for the
VNMF.
NmMessageCount
Integer
This attribute defines the maximum number of
nodes on the network. This attribute is used in
combination with NmBaseAddress and spans a
range of CAN-identifier within the 11-bit range for
the VNMF. The value must be given as 2N (e.g.
16 or 32).
NetworkType
String
Defines the type of the CAN-network. The
following Network Types are known:
Possible values:
“Powertrain”, “Bodybus”, “Infotainment”
GENy uses this attribute in order to configure the
baud rate.
VersionNumber
BCD-coded
This attribute can be used for versioning
Integer
purposes. The value shall be a BCD-coded
format. Thus, the number 100 is treated as
Version 1.00, or the value 245 is handled as
V2.45. This attribute definition is stored in ROM in
two 8-bit constant values that can be accessed
globally. Mainly used to retrieve the DB-version
number by diagnostics.
The names of the global variables are:
  kDataDictMainVersion,
  kDataDictSubVersion.
BusOffRecoveryTime
Integer
Defines the node recovery time after a BusOff
event.
BusWakeUpDelay
Integer
Defines the time between a High-Level Voltage
Wakeup (HLVW) and the activation of Initially-
Active VNs.
2013, Vector Informatik GmbH
Version: 2.02.01
6 / 21
Based on template version 2.8

Technical Reference Database Attributes

This parameter is also used as a delay time
between the Activation of shared-local input VNs
and the actual activation inside the ECU.
Table 3-1   Network Attributes
3.1.1
Network Attributes for Node Communication Active Message
On the network level the following attributes are defined for the Node Communication
Active (NCA) Message:
Name
Type
Description
NodeStatusMsgID
Hexadecimal  Declares the CAN-identifier for the Node-
Communication-Active (NCA) message. This is a
message transmitted by a node when using
Parameter-IDs on the network. The node
transmits the message with a pre-defined cycle
time, whenever at least one Virtual Network gets
active.
Note that the last 8 bits of this parameter must be
0.
See also: NodeStatusMsgCycleTime  and
NodeStatusMsgTimeoutTime,
(Default: 0x13FFFE00)
NodeStatusMessageCycleTime  Integer
Defines the periodic rate for the NCA message.
Default: 1200
Unit: ms
NodeStatusMsgTimeoutTime
Integer
Defines the minimum time a node must receive at
least one message from a node for a specific
source address. If at least one virtual network is
active, but the node receives no messages
(including NCAs) within this time; all NCA-
supervised messages and signals are handled by
supervision failure.
Default: 3000
Unit: ms
Table 3-2   Network Attributes for Node Communication Active Message
3.1.2
Network Attributes for Virtual Networks
On the network level the following attributes are defined for the Virtual Networks:
Name
Type
Description
VN_<<vn-name>>
Integer
Declares the Virtual Network with the name <<vn-
Range:
name>> (placeholder-name). The integer value
0..55
must be a contiguous and zero based number.
VNInitAct<<vn-name>>
Enum:
Defines whether a Virtual Network is declared as
No
‘Initially Active’.
Yes
Default: No
Table 3-3   Network Attributes for Virtual Networks
2013, Vector Informatik GmbH
Version: 2.02.01
7 / 21
Based on template version 2.8

Technical Reference Database Attributes

3.1.3
Network Attributes for Bit Timing Register setup
On the network level the following attributes are defined for Bit Timing Register (BTR)
setup. All five database attributes have to be defined in conjunction for GENy.
Name
Type
Description
Baudrate
Integer
Defines the baud rate for the respective network.
SamplePointMin
Integer
Defines the minimum sample point in [%] for the respective
network.
SamplePointMax
Integer
Defines the maximum sample point in [%] for the respective
network.
SyncJumpWidthMin
Integer
Defines the minimum synchronous jump width for the respective
network.
SyncJumpWidthMax
Integer
Defines the maximum synchronous jump width for the
respective network.
Table 3-4   Network Attributes for Bit Timing Register setup
3.2
Node Attributes
On node level the following attributes are evaluated by GENy:
Name
Type
Description
ILUsed
Enum:
Defines whether the Interaction Layer of the
No
GMLAN-Handler shall be used or not.
Yes
If the attribute is not set, the IL-Option page will
not appear in GENy.
Default: “Yes”
NmNode
Enum:
Defines whether the Network Management of the
No
GMLAN-Handler shall be used or not.
Yes
If the attribute is not set, the GMLAN-Option page
will not appear in GENy.
Default: “Yes”
VNECU<<vn-name>>
Enum:
Defines the VN-Type for a specific Node for the
None
specific VN
Activator
Remoted
Activator_Remoted
Shared Local
NodeSuprvStabilityTime  Integer:
This attribute defines a delay time in ms between
activation of a VN and start of supervision of the
0..65535
corresponding signals.
The supervision stability time is used to avoid
'Loss of Communication' DTCs due to transient
conditions after VN activation.
Default: “5000”
Table 3-5   Node Attributes

2013, Vector Informatik GmbH
Version: 2.02.01
8 / 21
Based on template version 2.8

Technical Reference Database Attributes

3.3
Message Attributes
On message level the following message attributes are evaluated by GENy:
Name
Type
Description
GenMsgSendType
Enum:
Defines the send type of a message. It could either
spontanX  be defined as periodic or non-periodic.
cyclicX
Periodic includes both strict periodic and periodic
with event. Non-periodic is strictly event-based.
cyclicX = periodic
spontanX = non-periodic
GenMsgCycleTime
Integer
If the message is defined as periodic, this attribute
defines the periodic time.
Unit: ms
GenMsgDelayTime
Integer
Defines the minimum update time of a message.
The value is given in units of ms. The minimum
update time is mostly used for mixed send types,
namely periodic and event send types.
Unit: ms
GenMsgStartDelayTime
Integer
Defines the start time after VN Activation when
processing of message events is started (i.e. the
cyclic transmission of the messages is started).
Unit: ms
GenMsgMandatoryToSupervision  Enum:
Defines the default setting after Power-up before
No
the Source Learning procedure the functional
Yes
messages with extended IDs has been started. The
source address of a message is either initialized to
FF (Yes) or FE (No). Different indications to the
application are given if a timeout occur for non-
learned messages.
GenMsgILSupport
Enum:
Defines whether a message shall be handled by the
No
Interaction Layer.
Yes
Default: “Yes”
Prio
Integer
Defines the priority of the functional messages in an
Range:
GM database. These are the first three bits of the
0..7
Extended CAN ID.
The priority is added to the CAN Identifier, which
can be found in the database, within GENy in order
to build the Transmit CAN-identifier as defined for
GMLAN with Extended CAN-Ids.
NmMessage
Enum:
Declares a message as a Network Management
No
message. The attribute must be set to ‘Yes’ for all
Yes
Virtual Network Management Frames (VNMF
messages).
TpTxIndex
Integer
Defines application TP messages.
Table 3-6   Message Attributes

2013, Vector Informatik GmbH
Version: 2.02.01
9 / 21
Based on template version 2.8

Technical Reference Database Attributes

3.3.1
Attribute Definitions for Diagnostics
The following message attributes need to be defined to assign CAN-messages for the
Diagnostic communication:
Name
Type
Description
DiagState
Enum:
Defines the AllNodeMessage request message
No
wit the CAN-ID 0x101 as the functional
Yes
diagnostic request message.
This attribute causes the GENy to reduce the
DLC check to a 1-byte value in order to let
messages shorter than 8 bytes also pass the
DLC-check.
It also forces the Generation Tool to generate a
specific function call inside the GMLAN-handler.
DiagRequest
Enum:
Defines the physical request message from the
No
tester to the node for the diagnostic
Yes
communication. Together with the definition of
DiagResponse, GENy assigns a connection
within the Transport Layer.
Note that GENy can only manage one pair of
diagnostic connection. Thus, only one message
can be defined for DiagRequest for one node.
DiagResponse
Enum:
Defines the physical response message from the
No
node to the tester for the diagnostic
Yes
communication. Together with the definition of
DiagRequest, GENy assigns a connection within
the Transport Layer.
Note that GENy can only manage one pair of
connection. Thus, only one message can be
defined for DiagRequest for one node.
TpApplType
String
Defines the UUDT message of a node. It has to
be set to “DiagUUDTResponse” for all diagnostic
UUDT response messages.
This attribute causes GENy to generate separate
naming independent macros used by CANdesc.
It will also generate tables that can potentially
used by Multiple Identity Modules (MIMs).
Table 3-7   Attribute Definitions for Diagnostics

2013, Vector Informatik GmbH
Version: 2.02.01
10 / 21
Based on template version 2.8

Technical Reference Database Attributes

3.4
Signal Attributes
On Signal level there are four concepts that need to be defined:
>  Assignments of signals to VNs
>  Definition of signal transmit models
>  Definition of signal supervision methods
>  Define default values for signal attributes (valid-failed, supervision failed, VDA/Mask
signal failed, start-up default value)
3.4.1
VN-Assignment of Signals
VN assignments of  signals are signal-dependent and therefore  defined at signal level.
Every signal can be assigned to any or all VNs. Signal VN assignments are defined
through the use of VN-specific attributes one per VN per signal.
Name
Type
Description
VNSig<VnName>
Enum:
Declares if a signal is assigned to a VN or not
No
Yes
Table 3-8   VN-Assignment of Signals
3.4.2
Signal Transmit Model Attributes
Event-based signal transmit criteria are defined at the signal level. Periodic transmit
criteria are defined at the message level and do not appear here. Refer to chapter 4.1.1
“Message Attributes”.
Name
Type
Description
GenSigSendOnInit
Enum:
Defines whether a signal (and the message)
NotInitialized
should be transmitted upon:
Application
>  Reception or transmission of an I-VNMF that
Handler
initializes at least one VN that is associated to
the VN
>  Start of a Shared Local VN, which the
message is associated to
>  All Initial Messages that are associated to any
Initially Active VN are transmitted upon
reception of a HLVW.
.

2013, Vector Informatik GmbH
Version: 2.02.01
11 / 21
Based on template version 2.8

Technical Reference Database Attributes

3.4.3
Signal Supervision Attributes
Signal supervision attributes are node-dependent and therefore  defined at the Node-Rx-
Signal relation instead on the signal itself. A signal can have different supervision criteria in
different messages and different nodes.
Name
Attribute  Attribute Type  Description
Class
GenSigTimeoutTime
Signal
Integer
The attribute defines the timeout time for
self-supervision or supervised-by-presence.
If the corresponding message doesn’t come
in within this time, supervision failure
indication is done on this message.
GenSigTimeoutMsg
Signal
Hex
This value defines the CAN-identifier that is
used for supervision. For self-supervised
messages, this is the CAN-identifier of the
same message. This attribute directs to the
message used for supervision-by-presence.
GenSigSuprvResp
Node-
Enum:
Defines the strategy concerning substitution
Mapped
None
and notification in case the signal
Rx Signal  Notify
supervision has failed.
Substitute
>  Notify:
NotifySubstitute
A timeout flag is automatically configured
for the signal.
>  Substitute:
The timeout default value defined by
‘GenSigSuprvRespSubValue’ is
automatically configured for the signal.
>  NotifySubstitute:
Both a timeout flag and timeout default
value are configured automatically for the
signal.

GenSigSuprvRespSubValue  Node-
Integer
Timeout substitution value for failsoft
Mapped
mechanism. It is automatically set in case
Rx Signal
‘GenSigSuprvResp’ is defined as
‘Substitute’ or ‘NotifySubstitute’.
Table 3-9   Signal Supervision Attributes

Info
Note: Validity signals are identified by the Capital-V at the end of its signal short name.

The Validity signal must have the same base name as the signal it is assigned to.

Example
Signal name:   SysPwrMode

Validity signal:  SysPwrModeV

2013, Vector Informatik GmbH
Version: 2.02.01
12 / 21
Based on template version 2.8

Technical Reference Database Attributes

3.4.4
Signal Attributes
The following signal attribute  is  used in order to define the default/initial behavior of
signals. These values are defined on signal level and are the same  for all nodes that
transmit the signal.
Name
Type
Description
GenSigStartValue
Integer
Default value for a signal used by the GMLAN-
Handler to initialize the transmit value during
Power-Up initialization.
Table 3-10   Signal Attributes

2013, Vector Informatik GmbH
Version: 2.02.01
13 / 21
Based on template version 2.8

Technical Reference Database Attributes

4  Attribute Settings in Terms of GM Concepts
Understanding the attributes and how they affect GENy  and the configuration of GMLAN
can lead to a simple mapping of attribute values to GM-specific concepts on transmit
models and signal supervision.
Below is an outline of how GM transmit model and signal supervision concepts can drive
the settings for the attributes involved.
4.1
Signal Transmit Model
4.1.1
Message Attributes
As signals can only be transmitted as part of a message, all signals in a message will
share the same transmission behavior. The message transmit model must therefore be set
correctly to ensure all signals contained in the message can be transmitted according to
their signal-specific requirements. Signal attributes define  event-based transmit criteria,
but not periodic transmit criteria. Periodic transmit criteria must be defined at the message
level. Any message containing a signal that must be transmitted periodically, regardless of
value, must be marked as periodic. Signal attributes do not contain this information. Signal
transmission requirements must be considered by the serial data engineer and used to
determine if a message must be transmitted periodically. Periodic messages allow for
event-based transmission in addition to the regularly scheduled cyclic transmissions.
For periodic messages, a cycle time must be defined. The cycle time must be equal to the
shortest transmit cycle time of all signals contained in the message. For signals with both
slow and fast cycle times, only the slow cycle time should be considered.
For periodic messages, a minimum update (or delay) time must be defined. The minimum
update time is the least amount of time that must elapse between  transmissions of the
message. The minimum update time must be equal to the longest minimum update time of
all signals contained in the message.
Name
Value for Transmit Model
Strictly Event Driven  Periodic
Periodic w/Event
GenMsgSendType
spontanX
cyclicX
cyclicX
GenMsgCycleTime
N/A
cycle time in ms
cycle time in ms
GenMsgDelayTime
minimum delay time in  N/A
minimum delay time in ms
ms
Table 4-1   Message Attributes of Transmit Model

2013, Vector Informatik GmbH
Version: 2.02.01
14 / 21
Based on template version 2.8

Technical Reference Database Attributes

4.1.2
Signal Attributes
Event-based transmit criteria are defined at the signal  level. Every signal has its own
event-based transmit criteria. The signal type determines the valid and possible event-
based transmit criteria. Signal type is defined by the SignalType attribute.
Attributes displayed in italic font aren’t used any more. They are listed for documentation
purpose only.
Name
Value for Transmit Model (by Signal Type)
SignalType = ENM

Any
None
GenSigSendType
OnAnyChange
NoSigSendType
SignalType = BLN

Send on 0-1
Send on 1-0
Send on Any Change
None
GenSigSendType
OnChangeIfActive
OnChangeIfActive
OnAnyChange
NoSigSendType
GenSigInactiveValue
0
1
N/A
N/A
SignalType = UNM

Send on
On Delta &
On Delta &
On Delta, Top &
None
Delta
Top
Bottom
Bottom
GenSigSendType
OnDelta
OnDelta
OnDelta
OnDelta
NoSigSend
Type
GenSigDeltaValue
delta
delta value
delta value
delta value
N/A
value
GenSigSendTopBottom
None
SendOnTop
SendOnBottom
SendOnTopBotto
N/A
m
Table 4-2   Signal Attributes of Transmit Model

2013, Vector Informatik GmbH
Version: 2.02.01
15 / 21
Based on template version 2.8

Technical Reference Database Attributes

4.2
Signal Supervision
4.2.1
Signal Attributes
Signal supervision is defined at the signal level. Every signal has its own supervision
criteria. There are two concepts that define signal supervision criteria. One concept is the
signal supervision method and the other is the response triggered by a supervision failure.
Name
Value for Supervision Method
Unsuper
Source
Self
Supervised By
Supervised
vised
Learning
Supervised
Presence
By Value
(direct)
(indirect)
NodeStatusMsgTime
0
> 0
N/A
N/A
N/A
outTime
GenSigTimeoutTime
0
0
time in ms
time in ms
N/A
GenSigTimeoutMsg
0
0
hex CAN-ID of
hex CAN-ID of
N/A
message
message that
containing this  shall be used for
signal
supervision
Table 4-3   Signal Attributes for Supervision
Name
Value for Supervision Failure Response Type
None
Notify
Substitute
Notify & Substitute
Application
Value
GenSigSuprvResp
None
Notify
Substitute
NotifySubstitute
GenSigSuprvRespSubValue
N/A
N/A
raw bus value
raw bus value
Table 4-4   Signal Attributes for Failsoft Mechanism
2013, Vector Informatik GmbH
Version: 2.02.01
16 / 21
Based on template version 2.8

Technical Reference Database Attributes

5  Database Attributes for CANoe Models
The following database attributes are used for the configuration of CANoe models. They
are not used by the configuration tools for the GMLAN Handler:

Attribute Name
Attribute
Attribute  Description
Class
Type
NodeLayerModules1  Node
String
This attribute is used by CANoe to load
NodeLayer DLLs. These DLLs are used to
provide an advanced interface to CAPL and
extended functionality of a specific node.
Typically, the value “GMLAN02.DLL” is
provided. This DLL extends CANoe to provide
GMLAN-specific functionalities. Another
attribute value is “osek_tp.dll”. This DLL
provides
Table 5-1   Database Attributes for CANoe Models


1 This attribute is not used for the configuration of the GMLAN-Handler.
2013, Vector Informatik GmbH
Version: 2.02.01
17 / 21
Based on template version 2.8

Technical Reference Database Attributes

6  Database Attributes not evaluated by GENy
This chapter contains database attributes, which are defined in GM’s network databases
but are not evaluated by the configuration and generation tool GENy for configuration of
the GMLAN-Handler.

Attribute Name
Attribute
Attribute Type
Description
Class
UseGMParameterIDs
Network
Integer
Defines if the network uses the
GMLAN parameter ID’s in the
29-bit architecture.
1: Network uses Parameter-Ids
(29-Bit)
0: Network uses no parameter-
ID’s (11-Bit)
SourceID
Node
Hexadecimal
The Source address of a node is
given as an attribute inside the
database. There are two
possibilities to use this attribute:
>  Instead of initialization of the
Source Address by the
application, the handler could
do this in the function IlInit().
This would imply, that the
value is always fixed (MIM-
modules will be handled
correctly depending on the
pre-selection of the
application, which instant
should run).
>  The transmit messages
inside the handler will already
be pre-set with the Source
Address given in this
attribute.
This would avoid the runtime
effort of the driver to add the
source address every time a
message must be
transmitted. The dynamic
setting will only be required
for MIM’s.
GenSigVBitResp
Node-
Enum:
Identifies that a validity signal is
Mapped
No
used for signal integrity.
Rx Signal
Yes
GenSigVDAFailResp
Node-
Enum:
Identifies that a VDA signal is
2013, Vector Informatik GmbH
Version: 2.02.01
18 / 21
Based on template version 2.8

Technical Reference Database Attributes

Mapped
No
used for signal integrity.
Rx Signal
Yes
Table 6-1   Network attributes not evaluated by GENy

6.1
Signal Transmit Model Attributes
Name
Type
Description
SignalType
String
Defines the type of the signal:
“ENM” : Enumeration
“BLN” : Boolean
“UNM” : Unsigned Numeric
GenSigSendType
Enum:
Defines the transmit criteria for a signal
0 not used
ENM:
1 not used
NoSigSendType or OnAnyChange
2 not used
UNM:
3 not used
NoSigSendType or OnDelta
4 not used
5 not used
BLN:
6 not used
NoSigSendType or OnChangeIfActive or
7 NoSigSendType
OnANyChange
8 not used
9 not used
10 OnAnyChange
11 OnChangeIfActive
12 OnDelta
GenSigInactiveValue
Integer
Defines if a signal shall be transmitted if
changed (SigSendType = OnChangeIfActive). It
is not send if it reaches the inactive value.
Used to define the send type 0-to-1 OR 1-to-0.
GenSigInactiveValue is defined as a raw value
(for signals of type Boolean only raw values are
used at all).
GenSigSendTopBottom  Enum:
Defines whether a signal of type UNM needs to
None
be sent if the physical value reaches one or all
SendOnTop
of its limits.
SendOnBottom
The limits for Top and Bottom are defined in the
SendOnTopBottom
Min and Max values of the database.
GenSigDeltaValue
Integer
This is used with SigSendType “OnDelta”. If the
most recent value exceeds the value of Delta
compared to the last value sent via CAN, the
signal is transmitted again.
Table 6-2   Signal Transmit Model attributes not evaluated by GENy

2013, Vector Informatik GmbH
Version: 2.02.01
19 / 21
Based on template version 2.8

Technical Reference Database Attributes

6.1.1
Node Mapped Rx-Signal Default Value Attributes
Name
Type
Description
GenSigRxStartValue
String
Value receivers set signal to at power up.
Used for documentation and UEF-Export.
Table 6-3 Rx-Signal Default attributes not evaluated by GENy

2013, Vector Informatik GmbH
Version: 2.02.01
20 / 21
Based on template version 2.8

Technical Reference Database Attributes

7 Contact
Visit our website for more information on

> News
> Products
> Demo software
> Support
> Training data
> Addresses

www.vector-informatik.com
2013, Vector Informatik GmbH
Version: 2.02.01
21 / 21
Based on template version 2.8

Document Outline

35 - TechnicalReference_GMLANCalibration

YourTopic

36 - TechnicalReference_GMLANCalibration_ind

Outline
Page 1
Page 2
Page 3
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13
Page 14
Page 15
Page 16
Page 17
Page 18
Page 19
Page 20
Page 21
Page 22
Page 23
Page 24

37 - TechnicalReference_GMLANCalibrations

GMLAN 3.1
Technical Reference

Calibration with GENy
Version 2.01.01

Authors
Gunnar Meiss, Markus Schwarz, Jason Wolbers, Heiko
Hübler, Frank Triem, Marco Pfalzgraf
Versions:
2.01.01
Status:
Released

Technical Reference GMLAN 3.1

1  Document Information
1.1  History
Author
Date
Version  Remarks
Gunnar Meiss
2007-04-13
1.0
Creation
Gunnar Meiss
2008-01-16
2.0
Added GENy Support
Markus Schwarz
2009-03-26
2.00.01  Corrected generation rules for
nmVNMFStartSendCalCnt
Jason Wolbers
2012-03-27
2.00.02  Added descriptions for
IlVnRxMessageEnabled,
IlVnTxMessageEnabled
Fixed Init Message description
Heiko Hübler,
2012-10-27
2.01.00  Added description for Rx Timeout Time
Marco Pfalzgraf,
Chapter 3 added
Frank Triem
Added descriptions for ‘Sleep Transition Time’,
‘Supervision Stability Time’, ‘Max No Sleep
Confirmation’
Frank Triem
2013-01-28
2.01.01  ESCAN00064578: Update GMLAN version
from GMLAN 3.0 to GMLAN 3.1
Table 1-1
History of the Document
1.2  Reference Documents
Index
Document
[1]
Vector’s Interaction Layer User Manual
[2]
Vector’s Interaction Layer Technical Reference for GENy
[3]
Vector’s Interaction Layer Technical Reference for GM
[4]
Vector’s Network Management Technical Reference
Table 1-2
References Documents

Please note
We have configured the programs in accordance with your specifications in the

questionnaire. Whereas the programs do support other configurations than the one
specified in your questionnaire, Vector’s release of the programs delivered to your
company is expressly restricted to the configuration you have specified in the
questionnaire.
2013, Vector Informatik GmbH
Version: 2.01.01
2 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

2  Introduction
This document describes the calibration (post build configuration) parameters of the
GMLAN  Handler  that is configured with GENy.  It does not describe the process how the
calibration of the GMLAN Handler is carried out.

Please note
This document is valid for GMLAN 3.1

  Il_Vector_Gm version 1.01.00 and higher
  Nm_Gmlan_Gm version 4.03.00 and higher
Changes to previous module version can be found in chapter 3.

2013, Vector Informatik GmbH
Version: 2.01.01
5 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

3  Module History
This chapter describes the calibration  implementation of the Vector Interaction Layer and
Network Management for General Motors in GENy.
3.1
Il_Vector_Gm Version 1.01.00
3.1.1
What is new?
  The Rx Timeout Time for each message is calibrated (chapter 5.2.1).
3.1.2
What has changed?
  There are no changes in this version.
3.2
Nm_Gmlan_Gm Version 4.03.00
3.2.1
What is new?
  New calibrateable values for ‘Sleep Transition Time’, ‘Supervision Stability Time’ and
‘Max No Sleep Confirmation’ (chapters 6.5, 6.6 and 6.7).
3.2.2
What has changed?
  There are no changes in this version.

2013, Vector Informatik GmbH
Version: 2.01.01
6 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

4 GMLAN Handler Calibration
The calibration of the GMLAN Handler is done by modification of the post build time
configuration parameters (constant variables and tables) that can be found in gmlcal.c.

The following chapter describes in detail the configuration parameters (constant variables
and tables) of the generated file gmlcal.c.

Info
If the calculated Table Values have a remainder, the value has to be rounded depending

on your needs.

2013, Vector Informatik GmbH
Version: 2.01.01
7 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

5  Il_Vector_Gm : Interaction Layer
This chapter describes the calibration capabilities of the Interaction Layer.
5.1  Transmit Messages
The GMLAN Handler provides the ability to enable and disable the transmit process for
each transmitted functional message with the function IlSetTxMessageEnable(..).
The default for this calibration is ‘enabled’.
This can also be calibrated directly using the table IlVnTxMessageEnabled[]. Note
that  using  the function IlSetTxMessageEnable  has the same effect as modifying
IlVnTxMessageEnabled[], so it is not necessary to both calibrate the table and call the
function. The table is a bit-packed field where each bit represents one IL transmit
message. If the bit is a 1, the message is calibrated on and can be sent whenever a
relevant VN is active; if the bit is a 0, the message is calibrated off and will never be sent
by the IL at runtime regardless of VN activity.  The IL messages are ordered least
significant bit to most significant bit in each byte. The first byte contains IL messages 7-0,
the second byte 15-8, and so on. For example, consider a single CAN channel
configuration with 10 IL messages:
{0xFF, 0x03} – All 10 IL messages are calibrated on
{0xFE, 0x03} – IL message 0 is calibrated off
{0x7F, 0x03} – IL message 7 is calibrated off
{0xFF, 0x01} – IL message 9 is calibrated off

When a configuration contains more than one CAN channel, a new byte in
IlVnTxMessageEnabled  is started to represent the IL messages for the next channel.
The remaining bits in the byte for the previous channel are skipped and have no meaning.
For example, consider a configuration with 10 IL messages on channel 0 and 12 IL
messages on channel 1:
{0xFF, 0x03, 0xFF, 0x0F} – All 22 IL messages are calibrated on
{0xFF, 0x03, 0xFE, 0x0F}  –  IL message 10 (the first  IL  message on channel 1) is
calibrated off
{0xFF, 0x03, 0x7F, 0x0F} – IL message 17 (the eighth IL message on channel 1) is
calibrated off

The numbering of the IL messages can be found at the top of the generated file il_par.h
in the format #define IlTxMsgHnd<message name>  <number>.  Non-IL messages
(VNMF, HLVW, diagnostics, etc.) cannot be calibrated using this method.
2013, Vector Informatik GmbH
Version: 2.01.01
8 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

5.1.1
Message Delay Time
The start delay time for each transmit message (Interaction Layer Tx Handle) is configured
in the table IlTxStartCycles[].
Symbol
Description
GenMsgStartDelayTime
The start delay time of a message in ms.
This is also the corresponding database attribute.
kIlTxCycleTime
The call cycle time of the IlTxTask of the dependent
channel in ms.
TableValue
The value in the table for the corresponding IL Tx handle.

The Formula for the Value Calculation is:
GenMsgSt t
ar DelayTime  +1 = TableValue




kIlTxCycl Tim
e
e

If the following condition matches, the value 0 has to be used for the IL Tx handle.
GenMsgSt t
ar DelayTime  = 0




kIlTxCycl Tim
e
e

5.1.2
Minimum Update Time
The minimum update time for each transmit message (Interaction Layer Tx Handle) is
configured in the table IlTxUpdateCycles[].
Symbol
Description
GenMsgDelayTime
The delay time of a message in ms.
This is also the corresponding database attribute.
kIlTxCycleTime
The call cycle time of the IlTxTask of the dependent
channel in ms.
TableValue
The value in the table for the dependent IL Tx handle.

The Formula for the Value Calculation is:
GenMsgDel yT
a
ime  +1 = TableValue



 kIlTxCycl Tim
e
e 
If the following condition matches, the value 0 has to be used for the IL Tx handle.
GenMsgDel yT
a
ime  = 0



 kIlTxCycl Tim
e
e 

2013, Vector Informatik GmbH
Version: 2.01.01
9 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

5.1.3
Periodic Rate
The periodic rate for each transmit message (Interaction Layer Tx Handle) is configured in
the table IlTxCyclicCycles[].
Symbol
Description
GenMsgCycleTime
The cycle time of a cyclic message in ms.
This is also the corresponding database attribute.
kIlTxCycleTime
The call cycle time of the IlTxTask of the dependent
channel in ms.
TableValue
The value in the table for the dependent IL Tx handle.

The Formula for the Value Calculation is:
GenMsgC eT
ycl
ime  = TableValue



 kIlTxCycl Tim
e
e 

5.1.4
Fast Periodic Rate
The fast periodic rate for each transmit message (Interaction Layer Tx Handle) is
configured in the table IlTxEventCycles[].
Symbol
Description
GenMsgCycleTimeFast
The fast cycle time of a message in ms.
This is also the corresponding database attribute.
kIlTxCycleTime
The call cycle time of the IlTxTask of the dependent
channel in ms.
TableValue
The value in the table for the dependent IL Tx handle.

The Formula for the Value Calculation is:
GenMsgC eT
ycl
imeFast  = TableValue




kIlTxCycl Tim
e
e


5.1.5
Init Message
The Init Messages are enabled/disabled in the table IlVnTxSendOnInit[]. The table
contains one bit for each transmit message (Interaction Layer Tx Handle):
  0: The transmit message is not an Init Message
  1: The transmit message is an Init Message
  The layout of the table follows the same pattern as IlVnTxMessageEnabled[] for
transmit messages.  Please see section 4.1 for a description and examples.
Please note
The implementation of the table has changed between CANGen and GENy.

2013, Vector Informatik GmbH
Version: 2.01.01
10 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

Any message that is transmitted via the Interaction Layer (usually all messages with
extended IDs) can be configured as Init Messages. These messages are transmitted
according to the configured transmission type ‘cyclic’, ‘on event’ or ‘cyclic and on event’.
The Init Messages are additional transmitted upon:
  Reception or transmission of an I-VNMF that initializes at least one VN that is
associated to the VN
  Start of a Shared Local VN, which the message is associated to
  All Initial Messages that are associated to any Initially Active VN are transmitted upon
reception of a HLVW.
The transmission of the Init Message is delayed according to the calibrated message delay
time. Refer to 5.1.1.
5.2  Receive Messages
The GMLAN Handler provides the ability to enable and disable the receive process for
each received functional message with the function IlSetRxMessageEnable(..).
The default for this calibration is ‘enabled’.
This can also be calibrated directly using the table IlVnRxMessageEnabled[].  Note
that  using  the function IlSetRxMessageEnable  has the same effect as modifying
IlVnRxMessageEnabled[], so it is not necessary to both calibrate the table and call the
function.  The layout of the table follows the same pattern as IlVnTxMessageEnabled[]
for transmit messages. Please see section 4.1 for a description and examples.
5.2.1
Rx Timeout Time
The Rx Timeout Time for each message is configured in the table IlRxTimeoutTbl[].
Symbol
Description
GenSigTimeoutTime_<ECU>  Timeout time of a message in ms.
This is also the corresponding database attribute.
kIlRxCycleTime
The call cycle time of the IlRxTask of the dependent
channel in ms.
TableValue
The value in the table for the dependent IL Rx handle.

The Formula for the Value Calculation is:
GenSigTi o
me utTime  = TableValue



 kIlRxCycl Tim
e
e

2013, Vector Informatik GmbH
Version: 2.01.01
11 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

5.3 Transmit Signals
5.3.1
Initial Transmit Value
This chapter describes the configuration of Tx signal default values that are set are set in
the Interaction Layer state transitions IlInit / IlTxStart / IlTxStop.
The following message layout is used as example in the following chapters.

Figure 5-1
Signal layout of the example message
2013, Vector Informatik GmbH
Version: 2.01.01
12 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

5.3.1.1  GENy Configuration
In order  to have the calibration (post build) capability of default values for all transmit
signals the ‘Init default’, ‘Start default’ and ‘Stop default’ have to be activated in GENy as
shown in the following figures.

Figure 5-2
GENy configuration of the ‚Tx Signals’ view  with the example message’s signals
5.3.1.2  Initial Default Values of Transmit Signals
The generated file gmlcal.c  contains for each transmit  message a table named
<MessageName>IlTxDefaultInitValue with the data type vuint8 [].
The size of the table depends on the length of the data of the corresponding message that
is relevant for your node. The table contains the default values of the message.

Example
The SignalA is located in the first byte of the array. The signal starts in bit 4 and ends in

bit 7 as shown in Figure 5-1.
If for example the default value for the SignalA in the Intel format is 1 and for the SignalB
and SignalC is 0, the table would contain the following values:

GMLCAL_MEMROM0 GMLCAL_MEMROM1 vuint8 GMLCAL_MEMROM2
MessageIlTxDefaultInitValue[] = {
   0x10
  ,0x00
};

Caution
The byte order (Little Endian / Big Endian) has to be taken in account when setting up

the default values for the signals.

2013, Vector Informatik GmbH
Version: 2.01.01
13 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

5.3.1.3  Start and Stop Default Values of Transmit Signals
The generated file gmlcal.c  contains for each transmit  message a table named
<MessageName>IlTxDefaultStartMask
for the IlTxStart
transition and
<MessageName>IlTxDefaultStopMask for the IlTxStop transition with the data type
vuint8 [].
The size of these tables depends on the length of the data of the corresponding message
that is relevant for your node. These  tables  contain  masks that are applied on the
corresponding default value of the table <MessageName>IlTxDefaultInitValue.
The mask table contains a ‘set bit’ at each bit position, where the default value is applied.

Example
If for example the default value for the SignalA shall be set at IlTxStart and not for

SignalB and SignalC, the table would contain the following values:

GMLCAL_MEMROM0 GMLCAL_MEMROM1 vuint8 GMLCAL_MEMROM2
MessageIlTxDefaultStartMask[] = {
   0xF0
  ,0x00
};

5.4  Receive Signals
Receive signal calibration is not supported by the GMLAN Handler.
2013, Vector Informatik GmbH
Version: 2.01.01
14 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

6  Nm_Gmlan_Gm : Network Management
This chapter describes the calibration capabilities of the Network Management.
6.1  nmVNMFStartSendCalCnt (Bus Wakeup Delay Time)
This is the time between transmission of a HLVW message and a VNMF-Init message
when activating a Virtual Network. Also known as the Bus Wakeup Delay Time. Time is
measured in multiples of the Nm Cycle Time. Default value is 100ms.
Symbol
Description
BusWakeupDelayTime
Delay time in ms.
NM_CYCLETIME
The call cycle time of the IlNwmTask of the dependent
channel in ms.
TableValue
The value in the table for the dependent NM channel.

 NmInitDel yT
a
ime + NM _ CYCLETIME − 1 = TableValue




NM _ CYCLETIME


Info
For a single channel configuration, there is only a constant generated.

For a multi channel configuration there will be an array generated which will have
as much entries as CAN channels are configured. The first entry is used for the
first CAN channel, the second for the second CAN channel and so on.

6.2  nmVNMFSendTimeCalCnt (VMNMF Periodic rate)
Time between sending continue VNMFs. Time is measured as multiples of the Nm Cycle
Time. Default value is 3000ms if the attribute GenMsgCycleTime for this VNMF message
is not set to a different value in the database.
Symbol
Description
VNMFPeriodicRate
Cycle of the VNMF message time in ms.
NM_CYCLETIME
The call cycle time of the IlNwmTask of the dependent
channel in ms.
TableValue
The value in the table for the dependent NM channel.

VNMFPerio ic
d Rate + NM _ CYCLETIME − 1 = TableValue




NM _ CYCLETIME


2013, Vector Informatik GmbH
Version: 2.01.01
15 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

Info
For a single channel configuration, there is only a constant generated.

For a multi channel configuration there will be an array generated which will have
as much entries as CAN channels are configured. The first entry is used for the
first CAN channel, the second for the second CAN channel and so on.

6.3  nmBusoffRecoveryTimeCalCnt (BusOff Recovery Delay Time)
The ‘BusOff recovery Delay Time’ is the time to wait after a BUS-OFF event to reset the
CAN controller and attempt recovery. The time is measured as multiples of the Nm Cycle
Time. The value corresponds to the “BusOff Recovery Time” field in the channel properties
of GENy.

Figure 6-1
“BusOff Recovery Time” configuration in GENy
Symbol
Description
BusOffRecoveryDelayTime  Delay time in ms for Bus-Off recovery.
NM_CYCLETIME
The call cycle time of the IlNwmTask of the dependent
channel in ms.
TableValue
The value in the table for the dependent NM channel.

 BusOff Re cov eryDelayT me
i
+ NM _ CYCLETIME −1 = TableValue




NM _ CYCLETIME


Info
For a single channel configuration, there is only a constant generated.

For a multi channel configuration there will be an array generated which will have
as much entries as CAN channels are configured. The first entry is used for the
first CAN channel, the second for the second CAN channel and so on.

2013, Vector Informatik GmbH
Version: 2.01.01
16 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

6.4  nmInitDelayTimeCalCnt (Init Delay Time)
For initially-active Virtual Networks, the ‘Init DelayTime’ defines the time between reception
of a HLVW message and transmission of Node Communication Active (NCA), periodic,
and send on-init messages. The time is measured as multiples of the Nm Cycle Time. The
value corresponds to the “Init Delay Time” field in the channel properties of GENy.

Figure 6-2
“Init Delay Time” configuration in GENy

Symbol
Description
NmInitDelayTime
Delay time in ms.
NM_CYCLETIME
The call cycle time of the IlNwmTask of the dependent
channel in ms.
TableValue
The value in the table for the dependent NM channel.

 NmInitDel yT
a
ime + NM _ CYCLETIME − 1 = TableValue




NM _ CYCLETIME


Info
For a single channel configuration, there is only a constant generated.

For a multi channel configuration there will be an array generated which will have
as much entries as CAN channels are configured. The first entry is used for the
first CAN channel, the second for the second CAN channel and so on.

6.5  nmSleepTransitionDelayTimeCalCnt (Sleep Transition Time)
The ‘Sleep Transition Time’ defines an extra delay time between CAN driver initialization
and setting the transceiver into sleep mode during shut down. This extra time gap between
CanInit() and ApplTrcvrSleepMode()provides additional protection against missing
of wake-up messages (HLVW).
The total time is calculated by adding the 'Bus Wakeup Delay Time' (chapter 6.1) and
'Sleep Transition Time' (this value). Note: The total time must not exceed 4 seconds!
2013, Vector Informatik GmbH
Version: 2.01.01
17 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

The value corresponds to the “Init Delay Time” field in the channel properties of GENy. The
default value is 50ms.

Figure 6-3
"Sleep Transition Time" configuration in GENy

Time is measured as multiples of the Nm Cycle Time.
Symbol
Description
NmSleepTransitionTime
Delay time in ms.
NM_CYCLETIME
The call cycle time of the IlNwmTask of the dependent
channel in ms.
TableValue
The value in the table for the dependent NM channel.

 NmSleepT n
ra sitionTime + NM _ CYCLETIME − 1 = TableValue




NM _ CYCLETIME


Info
For a single channel configuration, there is only a constant generated.

For a multi channel configuration there will be an array generated which will have
as much entries as CAN channels are configured. The first entry is used for the
first CAN channel, the second for the second CAN channel and so on.

2013, Vector Informatik GmbH
Version: 2.01.01
18 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

6.6  nmSupervisionStabilityTimeCalCnt (Supervision Stability Time)
The ‘Supervision Stability Time’ defines a delay time between activation of a VN and start
of Rx supervision of the corresponding signals. It is used to avoid 'Loss of Communication'
DTCs due to transient conditions after VN activation.
The value corresponds to the “Init Delay Time” field in the channel properties of GENy. It is
derived by the dbc attribute 'NodeSuprvStabilityTime'. If attribute does not exist, a default
value of 5000ms is used.

Figure 6-4
"Supervision Stability Time" configuration in GENy

Time is measured as multiples of the Nm Cycle Time.
Symbol
Description
NmSuprvStabilityTime
Delay time in ms.
NM_CYCLETIME
The call cycle time of the IlNwmTask of the dependent
channel in ms.
TableValue
The value in the table for the dependent NM channel.

 NmSuprvSt b
a ilityTime + NM _ CYCLETIME − 1 = TableValue




NM _ CYCLETIME


Info
For a single channel configuration, there is only a constant generated.

For a multi channel configuration there will be an array generated which will have
as much entries as CAN channels are configured. The first entry is used for the
first CAN channel, the second for the second CAN channel and so on.

2013, Vector Informatik GmbH
Version: 2.01.01
19 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

6.7  nmMaxApplShutDownDenyCnt (Max No Sleep Confirmation)
This value is only used if ‘Fault Detection and Mitigation’ and ‘Sleep Confirmation’ are both
enabled in GENy.
The value defines a threshold for number of times the application may deny the transition
to sleep mode within ApplNwmSleepConfirmation(). For detailed description of Fault
Detection and Mitigation Algorithm see chapter 3.11 in [4].
The value corresponds to the “Max No Sleep Confirmation” field in the channel properties
of GENy. The default value is 5.

Figure 6-5
"Max No Sleep Confirmation" configuration in GENy

The value is generated directly as defined in GENy.

Info
For a single channel configuration, there is only a constant generated.

For a multi channel configuration there will be an array generated which will have
as much entries as CAN channels are configured. The first entry is used for the
first CAN channel, the second for the second CAN channel and so on.

2013, Vector Informatik GmbH
Version: 2.01.01
20 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

6.8  GMLANNodeStatusTimeoutTimeCalCnt  (Node Communication Active Frame
Timeout)
The timeout for incoming Node Communication Active (NCA) messages is configured with
kGMLANNodeStatusTimeoutTimeCalCnt. Failure to receive a NCA message in this
period indicates that a node has failed. Time is measured as multiples of the Nm Cycle
Time. The value corresponds to the value of the NodeStatusMsgTimeoutTime attribute in
the database.
Symbol
Description
NodeStatusMsgTimeoutTime  Timeout time in ms.
NM_CYCLETIME
The call cycle time of the IlNwmTask of the dependent
channel in ms.
TableValue
The value in the table for the dependent NM channel.

 NoteStatusMsgTimeoutTime + NM _ CYCLETIME −1 = TableValue




NM _ CYCLETIME


Info
For a single channel configuration, there is only a constant generated.

For a multi channel configuration there will be an array generated which will have
as much entries as CAN channels are configured. The first entry is used for the
first CAN channel, the second for the second CAN channel and so on.

2013, Vector Informatik GmbH
Version: 2.01.01
21 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

7  Memory Definition file: MemDef.h
In order to allow calibration of the GMLAN Handler without modification of the generated
configuration files all calibration parameters are located in the same file (gmlcal.c).
Since the calibration parameters are stored in non-volatile memory (flash or EEPROM) the
possibility of linking/locating these parameters in a separate memory section is provided.
There are mechanisms in order to support various compilers:
  Memory Mapping via pre-processor directives (#pragma)
  Linking of tables with memory qualifiers
If necessary both mechanism may be combined.
7.1  Memory Mapping
The memory mapping with pre-processor directives is done with the definition of sections
that are embraced with a start definition that is followed by MemDef.h and a stop definition
that is followed by MemDef.h. By adding #pragma definitions at the beginning and end of
a section the parameters (tables)  in-between  may  be linked in to a defined memory
section.

Example
The following code shows a partial extract of gmlcal.c and a the mapping of the

calibration parameters to the section CALIBRATION:
gmlcal.c:
#define GMLCAL_START_SEC_CONST
#include "MemDef.h"

GMLCAL_MEMROM0 GMLCAL_MEMROM1 canuint16 GMLCAL_MEMROM2
nmBusoffRecoverTimeCalCnt = (NM_BUSOFF_RECOVER_TIME + NM_CYCLETIME-
1)/NM_CYCLETIME;

#define GMLCAL_STOP_SEC_CONST
#include "MemDef.h"

MemDef.h:
/* Definition of section for calibration parameters. */
#if defined ( GMLCAL_START_SEC_CONST )
#undef GMLCAL_START_SEC_CONST
#pragma section .CALIBRATION
#endif

/* Definition of section for default parameters. */
#if defined ( GMLCAL_STOP_SEC_CONST )
#undef GMLCAL_STOP_SEC_CONST
#pragma section .DEFAULT
#endif

2013, Vector Informatik GmbH
Version: 2.01.01
22 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

7.2  Memory Qualifiers
Separate memory qualifiers are used for all calibration parameters instead of the GMLAN
Handler’s Standard memory qualifiers in order to support linking these parameters to a
separate memory section. These memory qualifiers have to be adapted to the user’s
needs.
The following table provides a list of these memory qualifiers that are defined in
MemDef.h.
Memory Qualifier
Default definition
GMLCAL_MEMROM0
V_MEMROM0
GMLCAL_MEMROM1
V_MEMROM1
GMLCAL_MEMROM2
V_MEMROM2 (usually defined to const)
GMLCAL_MEMROM3
V_MEMROM3
The memory qualifiers defined in MemDef.h are exclusive used in gmlcal.c and gmlcal.h
The following example shows how the memory qualifiers are used in gmlcal.c.

Example
The following example shows how the memory qualifiers are used in gmlcal.c / gmlcal.h:

GMLCAL_MEMROM0 extern GMLCAL_MEMROM1 canuint16 GMLCAL_MEMROM2
nmBusoffRecoverTimeCalCnt;

2013, Vector Informatik GmbH
Version: 2.01.01
23 / 24
based on template version 2.7

Technical Reference GMLAN 3.1

8 Contact
Visit our website for more information on

> News
> Products
> Demo software
> Support
> Training data
> Addresses

www.vector.com

2013, Vector Informatik GmbH
Version: 2.01.01
24 / 24
based on template version 2.7

Document Outline

38 - UserManual_Startup_with_GMLAN_GENy

User Manual

39 - UserManual_Startup_with_GMLAN_GENy_ind

Outline
Page 1
Page 2
Page 3
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13
Page 14
Page 15
Page 16
Page 17
Page 18
Page 19
Page 20
Page 21
Page 22
Page 23
Page 24
Page 25
Page 26
Page 27
Page 28
Page 29
Page 30
Page 31
Page 32

40 - UserManual_Startup_with_GMLAN_GENys

  Startup with GMLAN and
  GENy
   User Manual
    (Your First Steps)

    Version 1.0.1

    Vector Informatik GmbH, Ingerheimer Str. 24, 70499 Stuttgart
    Tel. 0711/80670-0, Fax 0711/80670-399, Email can@vector-informatik.de
    Internet http:\\www.vector-informatik.de

User Manual  Startup with GMLAN

1 / 32

Authors:  Klaus Emmert
Version:  1.0.1
Status:
in preparation (in preparation/completed/inspected/released)

2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual Startup with GMLAN

2 / 32
History
Author
Date
Version
Remarks
Klaus Emmert
2008-03-10
1.0
Created
Klaus Emmert
2011-11-11
1.0.1
Improved Understandability

2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual Startup with GMLAN

3 / 32
Motivation For This Work
You want to read a document and follow its installation hints and as a result the
software is basically running? Then continue reading this user manual.
It is a guide through the installation of the GMLAN components, helps you to
configure you application for the needs of GMLAN and gives you precious hints for
the different requirements an ECU using GMLAN has to fulfill (PowerTrain,
SingleWire CAN…).

WARNING
All application code in any of the Vector User Manuals are for training
purposes only. They are slightly tested and designed to understand the basic
idea of using a certain component or a set of components.

2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

7 / 32
1  About this Document
This document gives you an understanding of GMLAN. You will receive general
information, a step-by-step tutorial to get the Startup with GMLAN running.
1.1  Legend and Explanation of Symbols
You find these symbols at the right side of the document. Use this helpful feature to
find fast the topics, you need information about.
These areas
to the right of
Symbol
Meaning
the text
contain brief
items of
The building bricks mark examples.
information
that will

facilitate your
search for
Comm
ents
You will find key words and information in short sentences in the margin. This will
and
specific
explanation

greatly simplify your search for topics.
topics.
The footprints will lead you through the steps until you can use the Startup with
GMLAN.

There is something you should take care about.

Useful and additional information is displayed in areas with this symbol.

This file you are allowed to edit on demand.

This file you must not edit at all.

This indicates an area dealing with frequently asked questions (FAQ).

2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

8 / 32
2  What is GMLAN
GMLAN is CANbedded for GM
GMLAN is General Motors' network operating software, which is supplied
exclusively by Vector. Vector has great experience with GMLAN from its beginning
on since 1999. Used by GM and its subsidiaries worldwide, GMLAN provides a
multi-layered network software solution for CAN bus management and access.
GMLAN consists of mandatory components and optional components.
Vector provides all current GMLAN software implementations and each software
implementation is:
  Microcontroller-specific
  CAN controller-specific
  Compiler-specific

Figure  2-1 GMLAN Layers with standard and optional components

Mandatory components of GMLAN
CAN Driver
The CAN Driver interconnects to the CAN controller, manages CAN transmission
and  reception, handles CAN initialization, bit  rate, sample  point,  SJW value  and
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

9 / 32
filtering. The CAN Driver interfaces with the GM-specific network software  and
provides a common low-level interface across a variety of CAN controllers.
Interaction Layer
It handles message reception,  transmission,  event  and  periodic messages,
manages Virtual Network initialization and fault detection (signal faults, VN faults).
Transport Protocol
The Transport Protocol implements the requirements of GMLAN network layer and
is primarily used for diagnostics. It manages large data transfers using USDT with
data size up to 4095 bytes. The Transport Protocol is based on ISO 15765.
GMLAN Network Management
It handles both node  and network management, manages communication states
(active, enabled, sleep). It manages node states (power up, sleep, wake up) and
the virtual networks. It also handles the use of the VNMF message.
Configuration Tool
It is PC-based and operates with Windows 2000/XP. The configuration tool is
delivered with the GMLAN Software Components and is used to scale the software
down to your specific needs, to optimize the use of ROM / RAM resources and to
select the GMLAN features that require integration into your ECU.

Info
The CAN Driver and the Transport Protocol are standard components and are not GM-specific.
The main difference of the GMLAN software stack in comparison with other OEM-specific stacks
is the Interaction Layer / GMLAN Network Management and the concepts of the virtual networks.

Additional components, optional available:
Diagnostics - CANdesc
  HIGHLY RECOMMENDED by GM!
This is a functional  interface for diagnostic  services based upon the CDD
diagnostic data  base created by CANdelaStudio. It fulfills the requirements of
GMW3110, V1.5  and  handles direct processing of CAN-specific  diagnostic
requests (enable/disable normal message transmission), negative responses (e.g.
service not available), exceptions  (e.g.  busy,  request  pending) and address
handling (detection of response  service  identification). It also supports UUDT-
message transmission. Testing of diagnostic is easy using CANdito, CANoe or
CANape
Communication Control Layer CCL
It supports integration of the software components CAN Driver, Interaction Layer,
Network Management, Transport Protocol and Diagnostics.
Also it provides an abstraction for different vehicle manufacturers, microcontrollers,
compiler/linker,  CAN controllers / transceivers. It supports a global  debug
mechanism and is configured via the configuration tool.
Measurement and Calibration (CCP/XCP)
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

10 / 32
The CCP/XCP is a high performance CAN-based monitor program. It supports
memory read / write and calibration activities and provides data acquisition. It can
also be used for flash programming  and data security. It works with Vector’s
CANape tool.

2.1  Virtual Networks
In general the ECUs form a network where every ECU is a network node.
The concept of GMLAN Network Management groups distributed functions into so-
called Virtual Networks (VNs).

Figure  2-2 Virtual Networks

What comes along with this concept?
  Each VN is a functional entity of GMLAN.
  The location of a VN or parts of it is independent of the physical partitioning
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

11 / 32
  The VNs are spread over the different ECUs. An ECU can only go to sleep
mode, if all VNs inside are asleep.
  Each VN handles its related signals, the use of the network and may include
sleep/wakeup.
  Related signals are grouped according to their function
  A message can contain signals of different VNs. There must be a decision
whether a signal of a VN is valid (VN awake) or not (VN sleeps).
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

12 / 32
3  Your ECU
Before you start with implementing GMLAN Software Components take a look at
the ECU you have to develop regarding the following questions:

  Is it a Body Bus ECU? With Single Wire CAN and mixed IDs (11bit and 29bit)
or 11 bit IDs only? Is it a multiple Identity ECU?
  Is it an Infotainment ECU?
  Is it a Powertrain ECU?
The above mentioned kinds of ECUs and bus systems have many settings in
common and differ in special settings.
The following installation description shows typical configurations including the
differences for the three mentioned cases.
3.1  Body Bus ECU
Single Wire CAN Mixed Identifiers (11bit and 29bit)
  Typically 33.333 kBaud
  1 wire ( bus communication possible while other ECUs are in sleep mode)
  2 initialization objects predefined: 33.333 kBaud and 83.333 kBaud for flashing
  29 bit application messages
  Source Learning
  Flexible monitoring of receive messages
Single Wire CAN 11 Bit Identifier
  Typically 33.333 kBaud
  1 wire ( bus communication possible while other ECUs are in sleep mode)
  2 initialization objects predefined: 33.333 kBaud and 83.333 kBaud for flashing
Multiple ECU on Single Wire CAN
  Used for nodes that exist more than once in a car with only a few differences
  At power up the application decides by means of a function call (see below),
which node should be realized, e.g. left passenger door, or right driver door.
  To reduce the memory consumption messages that are sent exclusively from
one node can be overlapped with the exclusively sent messages from the other
nodes. The result of this overlapping is that all these messages share a
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

13 / 32
common memory location for the transmit data. This can be configured
manually in the Send message tab in the Configuration Tool.
3.2  Infotainment ECU
  CAN Class C
  125 kBaud
  2 wires
  Able to be woken up
  Mixed IDs
3.3  PowerTrain ECU (or Chassis expansion or Powertrain expansion)
  CAN Class C
  500 kBaud
  2 wires
  Clamp 15 with and without follow-up time
  Shared local-input activated VN
  Special bus off recovery time
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

14 / 32
4  GMLAN In 6 Steps
STEP 1 :  PREPARE YOUR SOFTWARE PROJECT
Create folders in your application to store the delivered source code components and
the generated files in.

STEP 2:   CONFIGURATION TOOL AND DATA BASE FILE
Read-in the data base files that should be provided from your OEM (DBC file / CDD file
for diagnostics) in the Configuration Tool and make the configuration settings for the
CANbedded Software Components.

STEP 3:  ADD FILES TO YOUR APPLICATION
Add the CANbedded C and H files to your project or makefile.

STEP 4:   ADAPTATIONS FOR YOUR APPLICATION
Now your application files must be modified to use the CANbedded Software
Components (includes, cyclic calls, initialization) and do the call back functions.

STEP 5:   COMPILE AND LINK
Compile and link the complete project and download it to your test hardware or
development environment.

STEP 6:   TEST THE SOFTWARE COMPONENT
Test the software via a suitable test environment.

2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

15 / 32
4.1  STEP 1    Prepare Your Software Project
Following the GM_Readme  document you have already installed the delivered
GMLAN Software Implementation package. To use the GMLAN components for
your application copy the needed component source code into your project folder.
Normally these are the following component folders:

This includes the code for the CAN Driver, the Interaction Layer, the Network
Management (GMLAN) and the Transport Protocol.

Info
For the diagnostic there is an additional software component of Vector Informatik available -
CANdesc. This component is completely generated; you won’t find any source code in your
delivery.

A folder gendata is optional but recommended to be the target for all the data that
is generated by the Configuration Tool.

2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

16 / 32
4.2  STEP 2    Configuration Tool GENy and DBC File

Info
Use the online help of the configuration tool GENy for more information about using GENy and its
concepts. You additionally find a comparison between GENy and CANgen.

Start the Configuration Tool  GENy.exe. Select pre-configuration file,
microcontroller, derivative and compiler in the first Setup Dialog window.

Figure  4-1 Setup Dialog
The Preconfiguration selection determines which settings are preset in GENy and
which settings are not shown at all. This makes configuration for you very easy.
There is available:
  Bodybus
  Infotainment
  Powertrain

Then go on with adding a data base file using the green plus

Figure  4-2 Add data base file for a certain bus system, here CAN.

Info
The DBC file is designed by the vehicle manufacturer and distributed to all suppliers that develop an
ECU. Thus every supplier uses the SAME DBC file for one vehicle platform and one bus system
(powertrain, body CAN etc.) to guarantee a common basis for development.
The DBC file contains e.g. information about every node in the network, the messages/signals each
node has to send or to receive. The distribution of the signals among the messages is stored in the
DBC file, too.
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

17 / 32

Use the browse button […] to select your data base file (DBC).
As you will use a
different data
base file you will
get more and
other data base
nodes displayed.

Figure  4-3 Channel Setup Window

The Nodes list shows all available ECUs within the CAN network. Select yours.

Caution for Multiple ECUs
Use the <Strg> key to mark more than one ECU in the Nodes
list box then the Multiple Nodes section will be accessible.
Confirm with [OK].

2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

18 / 32
4.2.1  Setting of Generation Paths
Open the menu Configuration|Generation Paths…  to set the paths where the
Configuration Tool has to generate the files in. Here we use the folder gendata to
collect all generated files.

Figure  4-4 Paths To Generate Files to destined folders
Enter your Root Path for relative directories. Additionally you can add extra path
extensions below the Path  column. Always make sure that the Resolved  Path
points to the correct path!
4.2.2  Component Selection
Use the Component Selection to choose all components you need for your project.
The screenshot below shows a possible selection.

Figure  4-5 Component Selection
4.2.3  Tree view – A List of all selected components
All components selected before are now displayed in the Tree View  below
MyECU|Components.
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

19 / 32

Figure  4-6 Tree View of all selected components
Now select the different components to perform their individual configuration in
their Configuration View right besides the Tree View.
4.2.4  HW_<microcontroller>
This contains the hardware specific CAN driver settings for your controller. Refer to
the manual TechnicalReference_CANDriver_<hardware>.pdf and to your controller
manual for more information.
4.2.5  Nm_Gmlan_Gm
These settings are derived from the data base file. For this first start-up you can
work with the default settings.
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

20 / 32

Figure  4-7 Settings for GMLAN
All necessary settings for the VNs are already done derived from the data base file.

Info
Attributes are defined in the data base to specify the characteristics of a network, an ECU, a
network node, a message or a signal. These settings are common for all ECUs that are based upon
this data base file.
E.g. the attribute NetworkType can only be modified in the data base file (dbc). It can be set to
PowerTrain or BodyBus and determines whether it is a CAN Class C or a CAN single wire CAN.

4.2.6  Tp_Iso15765
You need the Transport Protocol normally for diagnostic purposes only. Use the
default.
Info
For more information about the settings of the transport protocol for your individual
  needs, refer to the TechnicalReference_TPMC.pdf or the UserManual_TP_GM.pdf.

4.2.7  Diagnostics – Diag_CanDesc_KWP
If you use diagnostic component select it in the Component Selection view.
Read-in an appropriate CDD file and use the default settings.
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

21 / 32

Figure  4-8 Path to the CDD file on the Configuration View of Diag_CanDesc_KWP
The CDD file has to be created and edited with the Vector Tool CANdelaStudio.

4.2.8  DrvCan_<microcontroller>
There is the access point for two very important setting, the bus timing registers
and the acceptance registers.

Figure  4-9 Acceptance Filters and Bus timing are channel-dependent settings
As bus timing register and acceptance register settings are channel-dependant, the
buttons to open the appropriate windows […]  can be found in the configuration
view of the channels.
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

22 / 32

Bus timing registers
The values for the bus timing registers are preset via data base attributes and
should be 33.333 kBaud for Single Wire CAN and 500 kBaud for PowerTrain.
Check those values again.
Enter the correct value for the Clock [kHz] of your hardware.

Figure  4-10  CAN Bus Timing Register Setup
Acceptance registers
Per default the acceptance registers are set to be open. Optimize filters… to get a
minimum of non-relevant messages into your system.
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

23 / 32
4.2.9  Settings are Finished
After the settings are done start the generation process of the tool via the yellow
flash button.
Use the views Generated Files and Messages to get information during and after
the generation process.

Figure  4-11  Success Window containing Information about Generated Files.
Messages
In the messages view the generation process puts out necessary information like
what has been done correctly or which errors occurred.
GENy e.g. checks whether all receive messages of your ECU will pass the
acceptance filters. If not, a warning will be displayed, containing the message(s)
that won’t pass the filter.
Generated Files
This view displays all generated files and the path, where the files have been
written to. A good chance to check the correctness of your path settings again.

2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

24 / 32
4.3  STEP 3    Add Files to Your Application
Now you have to add the files of GMLAN Software Components to your application
files in your project or makefile.
This includes
  delivered source code files and (see the list of files in GM_Readme.pdf)
  generated files in the gendata folder

4.4  STEP 4   Adaptations For Your Application
To use the GMLAN Software Components you have to do a few adaptations to
your application code.
4.4.1  Includes
The only file you have to include is il_inc.h.
#include “il_inc.h”

4.4.2  Initialization
/* make sure all interrupts are disabled*/
CanInitPowerOn();  /*If this initialization is
demanded to be done from the NM, you do not have to
call it.
The selection above can be done in the Generation
Tool*/
IlInitPowerOn();
TpInitPowerOn();
DescInitPowerOn();  /*optional, if CANdesc is used*/

/*Enable or Disable RX Messages based on Calibrations*/
IlSetRxMessageEnable(<Rx_Message_Name>, 0 or 1 for on or off);
This is optional
and only used to
cut down the

message set.
/*Enable or Disable TX Messages based on Calibrations*/
IlSetTxMessageEnable(<Rx_Message_Name>, 0 or 1 for on or off);

For 29-bit IDs
IlSetOwnNodeAddress(SWCAN, <srcAddress>);
only

/*Get learnt source IDs from EEPROM (single channel system)*/
for( index=0; index<kIlNumberOfExtIdRxObjects; index++)
{
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

25 / 32
  IlSetRxMessageSourceAddress(index, GetBLearnedSourceId(index));
}

4.4.3  Cyclic calls to keep the components running
The CAN Driver is the only component that is event triggered and that does not
need a cyclic call to work properly (except for the CAN Driver used in polling
mode).
All other components provide a task function that you have to call in the correct call
cycle that is entered in the Configuration Tool for each component.

/*Network Management task*/
IlNwmTask();

/*Interaction Layer tasks, separated in Tx and Rx*/
IlRxTask();
IlTxTask();

/*Transport Protocol tasks, separated in Tx and Rx*/
TpRxTask();
TpTxTask();

/*Diagnostics task - CANdesc*/
DescTask();

4.4.4  Provide Callback functions
The GMLAN Software Components call the application on internal events. For this
case there are callback functions to enable the application to know about the
program flow and to intervene if necessary. These callback functions must be
provided by the application. For the first attempt in most of the cases it is enough to
provide an empty callback function.

Callback functions for the Interaction Layer
void ApplIlNodeCommActiveFailed( vuint8 srcAddress ){} /*for mixed IDs
only*/

void ApplIlRxMsgSrcAddressLearned( IlReceiveHandle ilRxHnd, vuint8
srcAddress ){}   /*for mixed IDs only*/

2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

26 / 32
void ApplIlNodeCommActiveRecovery( vuint8 srcAddress ){}  /*for mixed IDs
  only*/

void ApplIlSourceAddressLearned( vuint8 srcAddress ){}     /*for mixed IDs
only*/
Callback functions for the Diagnostics
This depends on the selected diagnostic functions.

Callback functions for the Network Management
canuint8 ApplNwmSleepConfirmation( NM_CHANNEL_APPLTYPE_ONLY )
{
  return NmSleepOk;
}

void ApplNwmReinitRequest( NM_CHANNEL_APPLTYPE_FIRST unsigned char VnNr,
unsigned char ReinitRequest ){}

void ApplTrcvrNormalMode( NM_CHANNEL_APPLTYPE_ONLY ){}

void ApplTrcvrSleepMode( NM_CHANNEL_APPLTYPE_ONLY ){}

void ApplTrcvrHighVoltage( NM_CHANNEL_APPLTYPE_ONLY ){}

void ApplNwmVnDeactivated( NM_CHANNEL_APPLTYPE_FIRST unsigned char VnNr
){}

void ApplNwmVnActivated( NM_CHANNEL_APPLTYPE_FIRST unsigned char VnNr
){}

2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

27 / 32
4.5  STEP 5   Compile And Link
Now we compile and link the project. There should not be any errors or linker
problems.

4.6  STEP 6   Test the Software Component
To test the result download the executable to an appropriate target and test it e.g.
with CANoe.

2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

28 / 32
5  Further Information
5.1  Full CAN Message Transmission with Extended Ids
A 29bit message in GMLAN is build-up as shown. The lower 8 bits (Source
Address) are set by the CAN Driver.
Priority:
Parameter ID:
Reserved:
Source Address:
3 bits
13 bits
5 bits
8 bits

Figure  5-1 Extended CAN Identifier 29bit
If the message is a full CAN message the source address will not be written by the
CAN Driver as the full CAN messages are initialized at startup. There are two
strategies dealing with full CAN messages:
  Avoid putting extended ID messages to a full CAN object
  Use a pretransmit function to set the source address for every full CAN
transmission by hand. The disadvantage is the delay time for calling the
function and setting the source address.
Info
It would be sufficient to set the source address only once after initialization of the full CAN transmit
objects.

5.2  Take care when working with VNs
Caution
An IlSetEvent for transmitting a corresponding message will be deleted if the ECU is still sleeping.

The transmission of messages caused by an event has to be handled by the
application. For this case the application has to perform an IlPut to put in the new
value of the signal and an IlSetEvent  to trigger the actual sending of the
corresponding message.
A state transition of the Interaction Layer from suspended to running mode will
reset the settings of the Interaction Layer including all pending IlSetEvents.
A state transition will be performed every time a node wakes up.
Solution
An  IlSetEvent  should only be performed if the Interaction Layer is in running
mode. Use the function IlNwmGetStatus  to check the state of the Interaction
Layer.

If( IlNwmStateNMActive( IlNwmGetStatus() ) ) == 1
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

29 / 32
{
  IlSetEvent…
}

Another solution would be to use the StateOn flags  for signals. They can be
activated in the Configuration Tool on the tab Send signals and look like e.g.
ILGetTxDgnInfStateOn();
It returns a true value (0x01) if the corresponding VN is active. Then you could set
your event, too.

5.3  Validity of Signals
There are three mechanisms to define a signal to be valid or to be invalid.

  Timeout – message timeout, signal timeout --> flag or function, Configuration
Tool
  Validity bit in the same message as the signal
  VDA – Virtual device availability

To find out which signal is using which of the three mechanisms refer to your
specification.
Before you use the content of a signal do the testing if the signal is valid right now.

5.4  Signals assigned to different VNs and located in one message
Lets suppose that a message contains signals that are assigned to different VNs.
One VN is active the other VN is inactive.

VN1 is active
VN2 is inactive
Signal1( VN1 )
Signal2( VN2 )
CAN Message
data
data
data
data
data
data
data
data

Figure  5-2 Signals of Different VNs in One Message
As a result the confirmation and indication flags of the Signal2 (inactive VN) could
be set regardless that the corresponding VN is inactive. Transmission of this signal
is possible too and an IlSetEvent will provoke the transmission of the message
triggered by an inactive VN.
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual  Startup with GMLAN

30 / 32
The other ECUs know that the message had been sent by an inactive VN and that
the corresponding signals are invalid.
Suggestion
You could check before the IlSetEvent if the corresponding VN is active or not.

5.5  Source Learning for Single Wire CAN with Mixed Identifiers (11 bit and
29 bit)
The reason for the source learning mechanism is a flexible monitoring of the
receive messages.
Received messages are learned and this information is stored in an array by the
Interaction Layer. The application is informed about new learned entries via
callback functions
( ApplIlRxMsgSrcAddressLearned, ApplIlSourceAddressLearned ).

The application only has to store this array in a non-volatile memory and update
that array at startup time with the values from the non-volatile memory.
Refer to TechnicalReference_InteractionLayer_GM.pdf in the chapter “Dealing with
extended IDs” for more information.
5.6  Activation and deactivation of VNs
The Virtual Networks are activated or deactivated either by the network
management (initially active) or by the application. This also depends on the VN
configuration.
VN configuration:
  Activator
  Remotely Activated
  Local
  Initially Active
5.6.1  IlNwmActivateVN( channel, VN)
Via this function you activate a virtual network. Only VNs that are configured as
activator or local can be manually activated with this function. With it the Interaction
Layer is activated to send and receive messages/signals.
5.7  llNwmDeactivateVN
Deactivates the corresponding virtual network and stops Interaction Layer from
transmitting.
2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0

User Manual Startup with GMLAN

1 / 32
6 Index
Acceptance registers .................................. 22
Interaction Layer ..................................... 9, 25
Bus timing registers .................................... 22
makefile ....................................................... 24
callback functions ....................................... 25
Measurement and Calibration (CCP/XCP) ... 9
CAN Driver .................................................... 8
Motivation ...................................................... 3
CAN driver (Advanced) ............................... 18
Multiple ECU ......................................... 12, 17
CANdesc ..................................................... 15
Network Management ................................. 26
Communication Control Layer CCL .............. 9
project ......................................................... 24
Compile ....................................................... 27
Shared input activated VN .......................... 13
Configuration Tool .... 9, 14, 15, 16, 18, 25, 29
Signals ........................................................ 29
Cyclic calls .................................................. 25
source code ................................................. 24
DBC ............................................................ 16
Source Learning .......................................... 30
dbc file......................................................... 16
STEP 1 .................................................. 14, 15
Diagnostics - CANdesc ................................. 9
STEP 2 .................................................. 14, 16
gendata ........................................... 15, 18, 24
STEP 3 .................................................. 14, 24
generated files ...................................... 18, 24
STEP 4 .................................................. 14, 24
Generation Paths ........................................ 18
STEP 5 .................................................. 14, 27
GENy .......................................................... 16
STEP 6 .................................................. 14, 27
GM_Readme .............................................. 15
Symbols ........................................................ 7
GMLAN Network Management ..................... 9
Test ............................................................. 27
GMLAN options .......................................... 19
TP options ................................................... 20
IlSetEvent ....................................... 28, 29, 30
Transport Protocol......................................... 9
Includes....................................................... 24
Validity of Signals ........................................ 29
Init registers ................................................ 21
VNs.............................................................. 28
Initialization ................................................. 24

2011, Vector Informatik GmbH

Version: 1.0.1

based of template version 2.0