Note : Referencing the external components should be avoided in most cases. Only in unavoidable circumstance external components should be referred. Developer should track the references.

Global Functions(Non RTE) to be provided to Integration Project

Configuration REQUIREMeNTS

The Can component is provided with a template file for configuration of the module. This template file should be copied into the project for inclusion in the build after adapting the template for the needs of the project. Additionally, the leading underscore should be removed from this file. This file can be found in the “tools/template/” folder of this component. For details on how to adapt, third party documentation found in this component can be referenced as needed.

Build Time Config

Modules	Notes

Configuration Files to be provided by Integration Project

N/A

Da Vinci Parameter Configuration Changes

Parameter	Notes	SWC

DaVinci Interrupt Configuration Changes

ISR Name	Notes

Manual Configuration Changes

Constant	Notes	SWC

Integration DATAFLOW REQUIREMENTS

Required Global Data Inputs

Required Global Data Outputs

Specific Include Path present

Yes

Runnable Scheduling

Third party documentation can be referenced as needed.

Init	Scheduling Requirements	Trigger

Runnable	Scheduling Requirements	Trigger

Memory Map REQUIREMENTS

Mapping

Memory Section	Contents	Notes

* Each …START_SEC… constant is terminated by a …STOP_SEC… constant as specified in the AUTOSAR Memory Mapping requirements.

Usage

Feature	RAM	ROM

NvM Blocks

Compiler Settings

Preprocessor MACRO

Optimization Settings

Appendix

2 - Can Peer Review Checklists

Overview

Summary Sheet
Synergy Project

Sheet 1: Summary Sheet

Rev 1.2

8-Jun-15

Peer Review Summary Sheet

Synergy Project Name:

kzshz2: Intended Use: Identify which component is being reviewed. This should be the Module Short Name from Synergy Rationale: Required for traceability. It will help to ensure this form is not attaced to the the wrong change request. Can

Revision / Baseline:

kzshz2: Intended Use: Identify which Synergy revision of this component is being reviewed Rationale: Required for traceability. It will help to ensure this form is not attaced to the the wrong change request. Can_Vector_CANbedded_03.15.00_02.18.00_0

Change Owner:

kzshz2: Intended Use: Identify the developer who made the change(s) Rationale: A change request may have more than one resolver, this will help identify who made what change. Change owner identification may be required by indusrty standards. Lucas Wendling

Work CR ID:

EA4#9536

kzshz2: Intended Use: Intended to identify at a high level to the reviewers which areas of the component have been changed. Rationale: This will be good information to know when ensuring appropriate reviews have been completed. Modified File Types:

kzshz2: Intended Use: Identify who where the reviewers, what they reviewed, and if the reviewed changes have been approved to release the code for testing. Comments here should be at a highlevel, the specific comments should be present on the specific review form sheet. Rationale: Since this Form will be attached to the Change Request it will confirm the approval and provides feedback in case of audits. ADD DR Level Move reviewer and approval to individual checklist form Review Checklist Summary:

Reviewed:

N/A

MDD

N/A

Source Code

N/A

PolySpace

N/A

Integration Manual

N/A

Davinci Files

Comments:

3rd Party BSW component. Only reviewed 3rd party files for correctness to delivery and any Nexteer created

source files and documentation

General Guidelines:
- The reviews shall be performed over the portions of the component that were modified as a result of the Change Request.
- New components should include FDD Owner and Integrator as apart of the Group Review Board (Source Code, Integration Manual, and Davinci Files)
- Enter any rework required into the comment field and select No. When the rework is complete, review again using this same review sheet and select Yes. Add date and additional comment stating that the rework is completed.
- To review a component with multiple source code files use the "Add Source" button to create a Source code tab for each source file.
- .h file should be reviewed with the source file as part of the source file.

Sheet 2: Synergy Project

Peer Review Meeting Log (Component Synergy Project Review)

Quality Check Items:

Rationale is required for all answers of No

New baseline version name from Summary Sheet follows

Yes

Comments:

Follows convention created for

naming convention

BSW components

Project contains necessary subprojects

N/A

Comments:

Project contains the correct version of subprojects

N/A

Comments:

Design subproject is correct version

N/A

Comments:

General Notes / Comments:

LN: Intended Use: Identify who were the reviewers and if the reviewed changes have been approved. Rationale: Since this Form will be attached to the Change Request it will confirm the approval and provides feedback in case of audits. KMC: Group Review Level removed in Rev 4.0 since the design review is not checked in until approved, so it would always be DR4. Review Board:

Change Owner:

Lucas Wendling

Review Date :

02/03/17

Lead Peer Reviewer:

Rijvi

Approved by Reviewer(s):

Yes

Other Reviewer(s):

3 - TechnicalReference_CANDriver

TechnicalReference

4 - TechnicalReference_CANDriver_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

5 - TechnicalReference_CANDrivers

Vector CAN Driver
Technical Reference

Reference Implementation 1.5

Version 3.01.01

Authors: H. Honert, K. Emmert
Version:
3.01.01
Status:
released (in preparation/completed/inspected/released)

©2010, Vector Informatik GmbH
Version: 3.01.01
1 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

1  Document Information
1.1  History
Author
Date
Version
Remarks
Hoffmann
July, 30th 1997  1.00
Initial draft
Baudermann, Ebner
Aug, 9th 1999
2.00
Reorganization of the document
Hardware related
documentation removed
Ebner
Nov, 2nd 1999  2.01
Spelling corrections
Baudermann
Nov, 6th 1999
2.02
Restrictions with reentrance
capability for the following CAN
Driver functions: CanInit,
CanReset..., CanSleep,
CanWakeUp and CAN
interrupts
Honert
Dec, 14th 1999  2.03
DLC check added
Ebner
Feb, 8th 2000
2.04
Configuration by tool support
(CANgen) added
Baudermann, Rein, Honert,  May, 23th 2000  2.10
Generally reworked
Brändle
According to reference
implementation, version 1.1
Honert
Oct, 31th 2000  2.11
Description of indexed CAN
Driver added
Honert
Feb, 28th 2001  2.12
Extensions according to
reference implementation
version 1.2
Hardware related
documentation of HC12 and
C16x moved to a separate
document
Honert
Aug, 10th 2001  2.13
Description of API extended
  Single Receive Channel CAN
Driver
  CanCancelTransmit and
CanCancelMsgTransmit added
  Access to ErrorCounters added
Honert,
Aug, 20th 2001  2.14
Prototype of UserPrecopy

corrected
Spelling corrections
Emmert
Modifications for pdf conversion
Emmert
Okt, 9th 2001
2.15
Modifications of Figure 4 and 5.
Honert
Mai, 17th 2002  2.16
Function name corrected for
indexed driver
Extensions according to
©2010, Vector Informatik GmbH
Version: 3.01.01
2 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

reference implementation
version 1.3
Ebner, Honert, Emmert
Jun, 18th, 2003 2.20
Macro names corrected in
figure 7.
Extensions according to
reference implementation
version 1.4.
Additional explanation for offline
/ partial offline mode (ch. 5.2.6)
Emmert, Honert
Juli, 29th, 2003  2.21
New tables for API descriptions.
Corrections of some
Parameters and API
descriptions.
Stephan Hoffmann, Klaus
May 17nd,
2.22 Description
of
API
extended
Emmert, Heike Honert,
2004
  Direct Transmit Objects
Patrick Markl
Cancel in Hardware
Language corrections, New
Layout, Technical revisions
Klaus Emmert
2005-12-30
2.23
GENy added as Generation
Matthias Fleischmann
Tool
Added description for:
  Multiple ECU
  Common CAN
  Signal Access Macros
  Rx Queue
  Conditional Message Received
  Variable Datalen
Heike Honert
2006-08-01
2.30
Extensions according to
reference implementation 1.5.
Heike Honert
2007-01-09
3.00
prepare links to hw specific
Added description for:
  CAN RAM check
  Standard/HighEnd CAN Driver
Heike Honert
2007-01-29
3.01
some corrections
  improve Common CAN
  service functions for conditional
message reception added
  Description for Partial Offline
Mode for GENy modified
  ESCAN00032527: Update
description of
ApplCanAddCanInterruptDisabl
e/Restore call-back function
Heike Honert
2010-06-11
3.01.01
Reference to documentation of
VstdLib changed
Table 1-1   History of the Document
©2010, Vector Informatik GmbH
Version: 3.01.01
3 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

1.2
Reference Documents
Index and Document Name
[1] TechnicalReference_<hardware>.pdf
Table 1-2 Reference 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.
©2010, Vector Informatik GmbH
Version: 3.01.01
4 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

2 About this Document
This document describes the concept, features, API and the configuration of the Vector
CAN Driver.
The CAN Driver interface to the CAN Controller is designed to use the hardware specific
capabilities in an efficient way. The interface to the higher communication layers is mostly
identical for different CAN Controllers, so that the Interaction Layer, Network Management,
Transport Protocol and especially the user software are independent of the particular CAN
Controller used. Please note that in this document the term Application is not used strictly
for the user software but also for all the higher communication layers as listed above.
Therefore, Application refers to any of the software modules using the CAN Driver.
Two different types of CAN Driver are supported. These are the Standard CAN Driver and
the High End CAN Driver. The High End CAN Driver is an extended Standard CAN Driver.
The description of the Standard CAN Driver is also valid for the High End CAN Driver. The
additional features of the High End CAN Driver are described in own chapters.
The API of the functions is described in a separate chapter at the end of this document.
Referred functions are always shown in the Single receive channel mode.
Hardware related special features and implementation specifics are described in a
separate document which is named TechnicalReference_CAN_<hardware>.pdf.

©2010, Vector Informatik GmbH
Version: 3.01.01
13 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

2.1  Documents this one refers to…
  User Manual CAN Driver
  Hardware-specific documentation for the CAN Driver

User Manual
Technical
Technical
Reference
Reference
General
Hardware
You are here
#hw_<xxx>

Figure 2-1  Manuals and References for the CAN Driver

2.2  Naming Conventions
Some of the function names are mandatory, because they are used in the CAN Driver.
Other names are placeholders, and the Application can redefine or has to select them
according to its requirements:
Can...
It is mandatory to use all names beginning with Can... as they appear. Can...
stands for CAN Driver.
ApplCan...
The functions, starting with Appl... are so called callback functions. They are
provided by the Application and called by the CAN Driver. They are used to
notify the application about events such as state transitions.
User...
All names starting with User... are placeholders and will be selected by using
the Generation Tool according to the requirements of the Application. User...
stands for user-specific functions.
©2010, Vector Informatik GmbH
Version: 3.01.01
14 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

3  Reference Implementations
The reference implementation is a general specification for all Vector CAN Drivers. The
software versions for specific CAN Drivers differs, because there are different source
codes for different CAN Controllers. Therefore another overall version number exists,
representing the reference implementation. The CAN Drivers are implemented according
to this reference implementation with an identical feature set and Application interface as
well as a harmonized implementation.

3.1  Version 1.0
3.1.1  What's new?
  Identifier ranges defined by acceptance code and mask to receive a complete set of
several CAN identifiers. This is much more efficient for special requirements with fixed
identifier ranges and can be configured by the Application. Useful settings for
Application are selected automatically by the Generation Tool.
  Some parameters are provided by preprocessor defines in the CAN Driver configuration
file instead of global variables. This results in more efficient code.
  Notification of a CAN receive message overrun condition is done by the callback
function ApplCanOverrun(). This is configurable.
  The internal copy mechanism of the CAN Driver is configurable separately for receive
and transmit direction. It will be enabled automatically if an Application data buffer is
selected by the Generation Tool.
3.1.2  What's changed?
  General interrupt disable during critical service functions is replaced by a reentrant
solution.
  General assertion categories for the following severe errors in the CAN Driver:
  - User interface (e.g. invalid handles)
  - Generated data (caused by the Generation Tool)
  - Hardware problems (unexpected conditions of the CAN Controller)
  - Internal errors (e.g. inconsistent transmit queue entries)
  The different categories can be configured separately and the name of the callback
function has changed from ApplFatalError(..) to ApplCanFatalError(..).
  Callback function CanMsgReceive() has changed in ApplCanMsgReceived().
  Plausibility check for configuration switches of the CAN Driver is optional and will be
done in a separate header file called CAN_CHK.H.
  CanRxActualDLC will be provided as a preprocessor macro.
©2010, Vector Informatik GmbH
Version: 3.01.01
15 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

  If the transmit queue is used for CAN Controllers with several hardware transmit
objects, only one of these register sets will be used for normal transmission (in
combination with the transmit queue). The others are reserved for Full CAN Transmit
Objects with fixed CAN identifier and DLC.
  The names of the following global variables have been changed:
  CanEcuNumber to canEcuNumber
  CanRxHandle to canRxHandle

3.2  Version 1.1
3.2.1  What's new?
3.2.1.1
Mandatory (for all CAN Drivers)
  Configurable callback function if software acceptance filtering doesn't match.
  Configurable callback functions to monitor the correct transmit behavior.
  Dynamic transmit objects for variable CAN identifier and DLC
  Security level for the data consistency during the internal copy routines for receive and
transmit data.
  Configurable callback functions to control hardware dependent loop break conditions
(e.g. during the transition to reset, standby or sleep mode).
  For micros with nested interrupt levels the global disabling of interrupts by
CanGlobalInterruptDisable/Restore() is replaced by a configurable interrupt lock level.
3.2.1.2
Optional (for some specific CAN Drivers)
  Support of extended CAN identifiers in different modes (extended only or mixed with
standard identifiers)
  Non-interrupt (polling) mode for asynchronous transmission, reception, error and wake-
up notification.
  Dynamic transmit objects (for flexible transmit buffer, pretransmit as well as confirmation
function).
  Full CAN Transmit Objects with fixed CAN identifier and DLC.
  Dynamic hardware acceptance filtering for the reception of different messages.
3.2.2  What's changed?
  Service functions for flexible CAN identifier and DLC CanTransmitVarDLC/ID(..) must
not be used for new developments. It will be replaced by dynamic transmit objects.
  Special macros for the direct access to CAN message information (identifier, DLC, ...) in
the receive function (Dir...) will be removed. The standard macros can be used instead.
©2010, Vector Informatik GmbH
Version: 3.01.01
16 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

  Configurable DLC check for the length of the according receive buffer to avoid the
overwriting of the next receive buffer: The complete data will not be copied and the
Application will not be notified if an inconsistency is detected.
  The return code data type of the CanGetStatus() service function has changed because
of additional information in the software state of the CAN Driver and the hardware state
of the CAN Controller.
3.3  Version 1.2
3.3.1  What’s new?
  Hash search algorithm
  Low level transmit functionality to support e.g. gateways
  Service functions to stop and restart the CAN Controller.
  partial offline to switch dedicated transmit messages off.
  New return code of CanTransmit() in case of partial offline.
  Macros which return 8 bit of a received extended ID for use in precopy functions.
  Access to error counter of the CAN controller
  Service function to cancel transmit requests and confirmations
3.3.2  What’s changed?
  Generic Precopy function is now mandatory
  CanSleep() and CanWakeUp() has now a return value.
  CanGetStatus() is always available. Activation of extended status enables the additional
information in the hardware state of the CAN Controller.
  Passive mode can only be activated for all transmit requests and not for dedicated
messages.
  The name of some macros to access the ID in a precopy function has changed
  In the indexed CAN Driver, CanGetDynTxObj() has the channel as additional parameter.
  Macro CanRxActualIdHi renamed to CanRxActualIdRawHi
  Macro CanRxActualIdLo renamed to CanRxActualIdRawLo
3.4  Version 1.3
3.4.1  What’s new?
  New service functions to disable and restore CAN interrupts
3.4.2  What’s changed?
  Function CanInterruptDisable renamed to CanGlobalInterruptDisable
©2010, Vector Informatik GmbH
Version: 3.01.01
17 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

  Function CanInterruptRestore renamed to CanGlobalInterruptRestore
  Support of systems with mixed Identifier expanded
  Macro CanRxActualId returns the Identifier always in the logical presentation
3.5  Version 1.4
3.5.1  What’s new?
3.5.1.1
Mandatory (for all CAN Drivers)
3.5.1.1.1 Common features
  New functions CanCopyFromCan and CanCopyToCan. Hardware/Compiler dependent
functions to optimize copying of data (provide for higher layers such as TP, Diag).
more… API…
  The CAN driver can be configured to run without any disabling of interrupts.
The application has to take care of reentrancy! To set the Can Driver to this mode, the
security level has to be set to the lowest value. more…
  The CAN Driver is more fault tolerant against unexpected CAN interrupts like Rx
interrupt of a transmit object. Interrupt in polling mode or interrupts of unused objects
are handled by the driver.
  Callback function ApplCanPreWakeUp which is called immediately after the activation of
the wakeup interrupt. more... API…
  The CAN Driver doesn’t use library function of the compiler library (except for intrinsic
functions)
  The Can Driver code is MISRA compliant.
3.5.1.1.2 Transmission features
A confirmation function common to all transmit messages is supported. This function is
called after any successful transmission (except Direct Transmit Objects but includes
canceled transmit objects that had been sent although). more… API…
3.5.1.2
Optional (for some specific CAN Drivers)
3.5.1.2.1 Transmission features
  CanDirectTransmit( txHandle ) to support direct transmit objects.
This transmission is completely independent of other transmit messages and can
be sent e.g. out of a NMI (non-maskable interrupt service routine. (see also what’s
changed).
3.5.1.2.2 Reception features
  For Full CAN controllers polling of Basic CAN is supported (all functionality of the CAN
driver can be used in polling mode). more…
  A callback function is called, if the DLC check fails (this means if the DLC of the
received message is shorter than configured for this message). more… API…
©2010, Vector Informatik GmbH
Version: 3.01.01
18 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

  Support variable data length (for specific OEMs).

3.5.2  What’s changed?
  The names of the different kinds of transmission objects changed. To make the
differences clear in the following table all kinds of transmission objects are listed even if
nothing changed. more…
Old names (before RI 1.4)
New names (RI 1.4 and later)
Transmit Objects
Normal Transmit Object
Direct Transmit Objects
Full CAN Transmit Object
Dynamic Transmit Objects
Dynamic Transmit Objects
--- Direct
Transmit
Objects
Low Level Message Transmit
Low Level Message Transmit

3.5.2.1
Transmission features
  The interface of the TxObserve Callback functions has changed (parameter of the
functions  ApplCanTxObjStart() and ApplCanTxObjConfirmed() and ApplCanInit(). An
additional parameter is used. This additional parameter is the handle of the hardware
object (a unique number over all hardware transmit objects which starts with 0).
more… API…
  The functions CanCancelTransmit() and CanCancelMsgTransmit can now delete a
message in the hardware transmit buffer as well as in the queue. more… API…
  To get the tx handle of a pending transmit message, a new Service function is defined:
CanTxGetActHandle(CanObjectHandle logTxHwObject) more… API…
  If a CAN controller doesn’t support arbitration by ID, Direct Transmit Objects and Full
CAN Transmit Objects have a higher priority than the Normal Transmit Object. The Low
Level Message transmission has the lowest priority. more…
  It is not possible/necessary any longer to specify the number of the CAN transmit buffer
for Full CAN Transmit Objects. This will be done by the Generation Tool automatically.
  The functions CanPartOffline and CanPartOnline are designed to be reentrant. API…
3.6  Version 1.5
3.6.1  What’s new?
  data size optimized Tx Queue.
  In systems with mixed IDs (standard and extended), each range can be configured to
standard or extended ID individually.
  Each hardware objects can be configured individually to polling or interrupt mode.
more... API...
  Multiple Basic CAN objects can be defined to optimize the hardware filters. more...
©2010, Vector Informatik GmbH
Version: 3.01.01
19 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

  Rx Queue supports now queuing of messages out of a range.
  Notification about mode change of the CAN driver between offline and online mode.
  New macros to fill structure of Low Level Message Transmit
  distinguish between Standard CAN Driver and High End CAN Driver instead of optional
features
3.6.2  What’s changed?
  Source Address of Range Specific Precopy Messages removed – deviation to HIS CAN
Driver Specification. (EcuNumber isn’t any longer a member of tCanRxInfoStruct)
  Return code of Range Precopy Functions has effect on further reception handling.
  Direct Transmit Objects are not supported any more
  API Categories Single Receive Buffer (SRD) and Multiple Receive Buffer (MRB) are not
supported any more.
  Global Interrupt Control has been moved to VStdLib (CanGlobalInterruptDisable(),.
CanGlobalInterruptRestore(),  Interrupt Control by Application, Interrupt Lock Level).
...more information see Application Note AN-ISC-2-1050_VstdLibIntegration.pdf.
  Channel parameter for Hardware Loop Check Callbacks – deviation to HIS CAN Driver
Specification API...
  The following macros are not available any more: MK_EXTID_LO, MK_EXTID_HI,
MK_STDID_LO, MK_STDID_HI, CanRxActualIdRaw, CanRxActualIdRawHi,
CanRxActualIdRawLo
  The polling Tasks are allowed to be called in Sleep mode, too.
  Improvement of usage of assertions
  Same OSEK OS interrupt category for all CAN interrupts.
  Variable data length replaced by copying data with received DLC and DLC check
against minimum length.
  Description of dynamic pretransmit function, dynamic confirmation function and dynamic
acceptance filtering removed.

©2010, Vector Informatik GmbH
Version: 3.01.01
20 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

4  Overview
For error prevention, maintainability and expandability of Application programs, it is
essential to have a uniform interface between Application and CAN Driver, mostly
independent of the CAN Controller used. The CAN Driver itself must be adapted to the
CAN Controller for reasons of efficiency. This yields the following requirements for a
universally applicable CAN Driver:
  Independent of Application
  Driver code optimized for the CAN Controller used
  Uniform interface to the Application for different CAN Controllers
  Efficient usage of hardware resources, especially RAM and run time
  Support of special services like Interaction Layer, Network Management, Transport
Protocol

Figure 4-1  Relationship of the individual Software Components. They are customized by the Generation Tool
The generic CAN Driver code is independent of the Application. Only the callback
functions have to be given by the Application. The Application specific description data are
stored in dedicated data structures. The structure of the description data is fixed; however,
the contents of the structures are defined according to the ECU specific behavior by the
Generation Tool. This is done partly automatically based on information in the CAN
database and partly manually by user specific settings in the Generation Tool. The data
structures are specific for the CAN Controller, they are linked to the CAN Driver code
(ROM-capable).
The data to be transmitted or received are exchanged by default via global data buffers.
These data buffers are CAN message based. They are also created by the Generation
©2010, Vector Informatik GmbH
Version: 3.01.01
21 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Tool. Additionally, the Generation Tool creates signal-based access macros and/or
functions. This means the Application does not have to know the location and the structure
of the global data buffers. The names of the access macros/functions are formed from the
signal names in the CAN database. The detailed structure and features of the access
macros/functions are described in the documentation of the Generation Tool.
The Generation Tool will not be discussed in this CAN Driver documentation, since it is
irrelevant for the CAN Driver functionality. But the generated data structures are highly
optimized for an efficient usage of each CAN Controller. Therefore the usage of the
Generation Tool is a must to customize the CAN Driver code to the special needs of the
Application.
4.1  Short Summary of the Functional Scope
In this section the main tasks of the CAN Driver are summarized very briefly:
1.  Initialize the CAN Controller
2.  Transmit a single CAN message
3.  Receive a single CAN messages
4.  Handle Bus-Off
5.  Support sleep mode
6.  Support special services

4.1.1  Initialization
There are several CAN Driver service functions for initialization purposes available.
CanInitPowerOn(..) for the complete initialization of software and hardware after power-on,
CanResetBusOffStart(..) and CanResetBusOffEnd(..) for the re-initialization of the CAN
Controller after BusOff. For any other re-initialization the application can call CanInit(..).
Various initialization data structures can be predefined by the Generation Tool and
referenced in the Application by means of a specific initialization handle.
4.1.2  Transmission
One of the main services provided by the CAN Driver is to set up a transmit request in the
CAN Controller by the service function CanTransmit(..). The reference to the CAN
message specific description data is done by a transmit handle used in the Application.
This information like CAN identifier and DLC is set up by the Generation Tool based on the
CAN Database and additional user specific settings. If the CAN Controller is busy because
all hardware transmit objects are currently reserved, the transmit request can be stored
temporarily in a transmit queue. The number of hardware transmit objects depends on the
CAN Controller or CAN Driver configuration. For details please refer to the CAN Controller
specific documentation TechnicalReference_CAN_<hardware>.pdf  [#hw_comObj]. If the
CAN Controller is ready, data can be copied by different mechanism to the hardware
transmit registers. The return code of the transmit function informs whether the transmit
request was accepted by the CAN Driver or not. If it was rejected by an error and no
transmit queue is used, the Application is responsible for the repetition of the transmit
©2010, Vector Informatik GmbH
Version: 3.01.01
22 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

request until the message is in the CAN Controller. A successful transmission is signaled
by a confirmation. Special features like offline or passive mode are available to control the
transmit path of the CAN Driver by the Network Management or Diagnostics.
4.1.3  Reception
If a message on the CAN bus was accepted by the hardware and software acceptance
filtering, data can be read by different mechanism and this asynchronous event is notified
to the application by an indication. Additionally a special callback function
ApplCanMsgReceived() allows the user to access receive data directly in the scope of a
receive interrupt before the software acceptance filtering. The algorithm for the software
acceptance filtering is configurable because in some Applications a lot of irrelevant CAN
identifiers are passing the hardware acceptance filter and an efficient software filtering is
very important.
4.1.4  Bus-Off
The CAN Driver notifies a detected BusOff state to the Application by calling a special
callback function ApplCanBusOff(). Further processing like re-initialization of the CAN
Controller and additional customer-specific requirements like disabling transmissions for a
certain time have to be done by the Application.
4.1.5  Sleep Mode
Some CAN Controller are supporting a so called sleep mode with reduced power
consumption. The CAN Driver provides the service functions CanSleep() and
CanWakeUp() to enter and leave this special mode on request of the Application.
If the CAN Controller is also wakeable by the CAN bus, the callback function
ApplCanWakeUp() is called if this condition is detected. In some cases this leads to the
situation that the CAN controller is initialized (CanWakeUp) before the application will be
notified.
In case of changing the PLL (SLEEP = slow speed / ACTIVE = normal speed) the
application must be informed immediately. Otherwise the “long” interrupt execution causes
a watchdog reset. Therefore the callback function ApplCanPreWakeUp is called just after
the activation of the wakeup interrupt. The configuration is done via the Generation Tool or
user configuration file.

4.1.6  Special Features
There is additional support for special features like
  Status of CAN Driver and CAN Controller
  Interrupt control
  Assertions
  Hardware loop check
  Support of OSEK compliant operating systems
  Multiple-channel CAN Driver
  Polling mode
©2010, Vector Informatik GmbH
Version: 3.01.01
23 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

  Handling of Extended Identifiers
  Stop mode
4.2  Data Structures for CAN Driver Customization
The description data created by the Generation Tool are split into initialization structures
for the CAN Controller as well as transmission and reception structures for CAN
messages. They are located in the ROM memory of the microprocessor. The receive and
transmit buffers are mapped in RAM data and will be referenced by the description data.
The description data also contains references (pointers) to user-specific functions of the
Application. The CAN Driver accesses all the structures in the description data. The CAN
Driver is independent of the Application but the generated description data depends on the
particular Application.

©2010, Vector Informatik GmbH
Version: 3.01.01
24 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Figure 4-2  Description data, CAN Driver and Application with their interfaces.
4.2.1  ROM Data
4.2.1.1
Initialization Structures
The CAN Controller is initialized with the description data stored in the initialization
structures. They consist of the register values for the CAN Controller. They are highly
dependent on the particular used CAN Controller.
©2010, Vector Informatik GmbH
Version: 3.01.01
25 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

4.2.1.2
Transmit Structures
The structures listed below are used by the CAN Driver internally.
ID
Identifier of the messages to be transmitted. The format is CAN
Controller dependent for efficiency reasons.
DLC
Number of data bytes to be transmitted (Data Length Code).
The format is CAN Controller dependent for efficiency reasons.
DataPtr
Pointer to the CAN message based global transmit buffer.
UserPreTransmitPtr
Pointer to the user specific pretransmit function (must be a
NULL pointer if not used).
UserConfirmationPtr
Pointer to the user specific confirmation function (must be a
NULL pointer if not used).
ConfirmationOffset/Mask  Byte offset and bit mask for the CAN Driver access to the
corresponding confirmation flag.

4.2.1.3
Receive Structures
The structures listed below are used by the CAN Driver internally.
ID
Identifier of the messages to be received. The format is CAN
Controller dependent for efficiency reasons.
DataLen
Number of data bytes to be copied. The value may be different
from the DLC of the message received. The driver then only
copies the number of bytes stored in this structure. The other
bytes are ignored.
DataPtr
Pointer to the CAN message based global receive buffer.
UserPrecopyPtr
Pointer to the user specific precopy function (must be a NULL
pointer if not used).
UserIndicationPtr
Pointer to the user specific indication function (must be a NULL
pointer if not used).
IndicationOffset/Mask
Byte offset and bit mask for the CAN Driver access to the
corresponding indication flag.

4.2.2  RAM Data
The RAM data consist of transmit and receive buffers for the CAN messages.
In the data buffers, the first byte transmitted or received is located at the least significant
address of the data array (Note: Bit 7 is transmitted first).
For some microprocessors there are memory areas which can be accessed more
efficiently (e.g. internal RAM or bit addressable segments). The data buffers can be
mapped by the Generation Tool.

©2010, Vector Informatik GmbH
Version: 3.01.01
26 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5  Detailed Description of the Functional Scope (Standard)
5.1
Initialization
5.1.1  Power-On Initialization of the CAN Driver
The following service function must be called once after power-on to initialize the CAN
Driver:
void CanInitPowerOn( void );

This call initializes the CAN Controller for each channel and all CAN Driver variables (local
and global), i.e. the CAN Driver is set to online and active state.
This service function has to be called for a proper initialization before any other CAN
Driver function and before the global interrupts are enabled.
5.1.2  Re-Initialization of the CAN Controller
The CAN Controller is completely re-initialized by the service function call:
void CanInit( CanInitHandle initObject );

The parameter initObject means a handle for a specific initialization structure.
It is a must to bring the CAN Driver into offline state before this service function is called.
By this service function only the CAN Controller and the corresponding internal variables
will be initialized. Software states like online/offline or active/passive remain unchanged.
Changes of individual registers of the CAN Controller are only possible by means of a
complete re-initialization, i.e. an entire initialization structure must be provided for each
register change (e.g. bit timing, acceptance filtering, .. ).
5.2
Transmission
5.2.1  Detailed Functional Description
This section shows the transmission of a CAN message using different methods. For the
general processing first a flow chart is used. The gray decision symbols branch to features
that can be removed from the CAN Driver using the configuration options (see Figure 5-1).
In a second step sequence charts are used to show how the different objects of the CAN
Driver, description data and Application program work together.

©2010, Vector Informatik GmbH
Version: 3.01.01
27 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

STARTING POINT
Application
Leave Transmit Interrupt
CanTransmit
Yes
CanTransmitQueuedObj
No
Queue Empty
Yes
CAN offline
Use not
No
Use
Transmit Queue
Configured
Part offline
check
Not configured
Yes
CAN offline
Confirmation Function
Not configured
Yes
Part offline
No
Configured
Confirmation Function
Defined
No
Confirmation Flag
Use Queue
Use
Not configured
Configured
Confirmation Flag
Use not
Defined
Transmit Buffer Full
Yes
No
Confirm Transmission
Use not
Configured
Pretransmit Function
defined
Use
Confirmation of
Transmission
Pretransmit Function
Not configured
Yes
Confirm TxObserve
kCanCopyData
Use not
Use
No
Use TxObserve
Copy Data
Switches in the Generation Tool for
optional features of the CAN Driver
Enter Transmit Interrupt
Decisions in the code, if the feature is selected.
Initiate Transmit
Optional or mandatory functions of the CAN Driver
No
end
Interrupt Enabled
Mandatory path through the CAN Driver
Queue
Use
Use TxObserve
Yes
Optional path through the CAN Driver
TxObserve Started
Use not
Direction of work flow
ACKNOWLEDGE
(sent message received)
CAN Message
Transmit

Figure 5-1 Transmission of a CAN message
©2010, Vector Informatik GmbH
Version: 3.01.01
28 / 149
based on template version 2.1

The main service function to initiate a transmit request is
vuint8 CanTransmit( CanTransmitHandle txObject );

The function parameter is a transmit message handle. It represents an index in the
generated transmit description data. The return code contains the following information:
kCanTxOk
Successful transmit request. The message is sent out by the
CAN Controller without any further action required. For CAN
Drivers with transmit queue, this return code is also used if the
transmit request has been accepted in the queue, even if it was
already in queue.
kCanTxFailed
CAN transmit request failed. In this case the calling application
has to repeat the transmit request later.

kCanTxPartOffline
Error code because CAN Driver’s transmit path is in partial
offline mode for this transmit object.

The left path (see Figure 5-1) time flows from top to bottom. This path shows the program
flow calling the service function CanTransmit(..). First the CAN Driver checks whether the
transmit path is switched to offline state. If so the function returns with an error code. Then
the Driver checks (if configured) the partial offline mode. If the specified message is offline,
the function will return an error code.
In the next step the CAN Driver checks the availability of a hardware transmit object. If no
object is available the transmit request is stored in the transmit queue (if configured to be
used) and the CAN Driver returns to the Application with the return code kCanTxOk. If no
transmit queue is used the CAN Driver returns with an error code kCanTxFailed.
If a transmit object is available the CAN identifier and the data length code will be set in
accordance to the description data. Now, if a pretransmit function is configured, this
pretransmit function will be called. Within this user specific function the Application may
copy the data to be transmitted directly to the CAN Controller hardware registers. If the
data is completely copied, the pretransmit function returns kCanNoCopyData to the CAN
Driver.

The data has to be copied by the CAN Driver itself, if there is no pretransmit function
defined or this function returns kCanCopyData. In this case the CAN Driver copies the data
from the global data buffer associated with the message to the CAN Controller hardware
registers.
Then the transmission of the CAN message is started in the CAN Controller and the
function returns the code kCanTxOk to the Application.
Dependent on the configuration, the TxObserve function is now started.
In the right path of the figure below, the time flows from bottom to top. This path shows the
program flow in the interrupt service routine after a successfully transmission of the
message to the CAN bus. In the transmit interrupt routine, the confirmation actions are
performed. If configured, first the TxObservation is confirmed, then (if configured) a
©2010, Vector Informatik GmbH
Version: 3.01.01
29 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

confirmation function for all messages is called. Afterwards the confirmation flag is set and
then the message-specific confirmation function is called.
If the CAN Driver is configured to use a transmit queue, after processing the confirmation
actions the CAN Driver checks if the transmit queue is empty. If so the transmit interrupt
routine is finished. If there are entries in the queue the highest priority CAN message is
removed from the queue and the transmission of this message is requested. This is also
done on interrupt level.
In the middle of the picture we see the transmit queue which is used if all hardware
transmit objects are busy, when CanTransmit(..) is called.
The next sections describe the transmission of a CAN message using sequence charts.
The vertical lines within these diagrams represent program objects like interrupt routines,
functions (thick lines) or data objects (thin lines). The horizontal lines represent program
flow or data access within the program. Flow control and program instances are described
using thick lines, data access is described using thin lines. Time flows from the top of a
chart downwards so that sequence „1“ is performed before sequence „2“. The description
of the sequence charts is given in the tables following the charts.

The first sequence chart in Figure 5-2 shows the behavior if a hardware transmit object is
available, a global data buffer is associated to the message and the copy mechanism of
the CAN Driver is used.

CAN Data
TX Interrupt
Can-
Driver
Global Data
Conf.
CAN
Conf. Flag
Pretransmit
Application
Buffer
Routine
Transmit
Parameters Buffer
Function
1
2
3
4
5
6
7
8
9
10

Figure 5-2 Transmission with an available transmit object; Using global data buffer
No
Description
1
The Application writes the data to the global data buffer
2
The Application calls CanTransmit(..) service function
3
Function uses description data (CAN identifier, DLC, etc...)
4
Global data buffer is read and copied; the transmit process is started
5
CanTransmit(..) service function is finished, the return code is kCanTxOk
6
The message is successfully sent to the CAN bus. Transmit interrupt routine is
started
7
Transmit confirmation flag is set (cleared by the Application)
©2010, Vector Informatik GmbH
Version: 3.01.01
30 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8
Confirmation function is called
9
Confirmation functions returns to transmit interrupt routine
10
Transmit interrupt routine is left

The next sequence chart in shows the behavior if a hardware transmit object is available
and a pretransmit function is used to copy the data to be sent.

CAN Data
TX Interrupt Can-
Driver
Global Data
Conf.
CAN
Conf. Flag
Pretransmit
Application
Buffer
Routine
Transmit
Parameters Buffer
Function
1
2
3
4
5
6
7
8
9
10
11

Figure 5-3 Transmission with an available hardware transmit object; Using a pretransmit function to copy data

No
Description
1
CanTransmit(..) service function is called by the Application
2
Function reads the description data (CAN identifier, DLC, etc.)
3
Call of the pretransmit function
4
Pretransmit function writes data to the CAN Controller
5
Pretransmit function returns to CanTransmit(..)
6
Start transmission; CanTransmit(..) service function is finished and the return code
is kCanTxOk
7
The message is successfully sent to the CAN bus. Transmit interrupt routine is
started
8
Transmit confirmation flag is set (cleared by the Application)
9
Confirmation function is called
10
Confirmation function returns to transmit interrupt routine
11
Transmit interrupt routine is left
©2010, Vector Informatik GmbH
Version: 3.01.01
31 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

The next sequence chart in shows the behavior, if no hardware transmit object is available.
This sequence chart is valid only if the CAN Driver is configured to use a transmit queue.
The data is copied by the CAN Driver itself.

TX Interrupt
Can-
Driver
Global Data
Conf.
CAN
CAN Data
Conf. Flag
Application
Buffer
Routine
Transmit
Parameters
Buffer
Pretransmit Function
1
2
3
4
5
6
7
8
9
10

Figure 5-4  Transmit procedure if no hardware transmit object available
No  Description
1
The Application writes the data to the global data buffer
2
The Application calls CanTransmit() service function. No hardware transmit objects
available. Request is stored in the transmit queue.
3
Function returns kCanTxOk
4
Transmit interrupt: A (previous) CAN message was successfully sent, transmit object
is available again
5
Confirmation flag of the previous CAN message is set (cleared by the Application)
6
Confirmation function of the previous CAN message is called
7
Confirmation function return
8
The transmit queue is checked for requests. The pending transmit request is found.
The description data are evaluated (CAN identifier, DLC, etc...)
9
Global data buffer is read and copied; the transmit process is started
10  Transmit interrupt routine is left

5.2.2  Transmit Queue
The normal Tx object can be configured to use a transmit queue or not. The Transmit
Queue is not available for Full CAN Objects and the Low Level Transmit Object. If no
transmit queue is used, the Application is responsible to restart a transmit request if it
wasn’t accepted by the CAN Driver. In case of using a transmit queue, a transmit request
is always accepted (if the driver is online). But the transmit queue holds only the transmit
©2010, Vector Informatik GmbH
Version: 3.01.01
32 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

request of a CAN message. It doesn’t store the data to be sent. Please note the same
message can be queued only once. The CAN Driver sets a transmit request in the transmit
queue, if no hardware transmit object is available after CanTransmit(..) is called. On a
transmit interrupt, i. e. when a message has been sent successfully, the CAN Driver
checks whether transmit requests are stored in the queue. If so, one requests is removed
from the queue and the transmit request is executed. The search algorithm in the queue is
priority based, there is no FIFO strategy. This means the CAN identifier with the lowest
number is removed first from the queue.
If the CAN Driver is configured to use a transmit queue, the internal data copy mechanism
will be initiated and/or the pretransmit function will be called in the scope of a transmit
interrupt after the completion of a previous transmit request. Therefore the user has to
guarantee the data consistency, because an Application write access to the global data
buffer may be interrupted by such a transmit interrupt. If within this interrupt the associated
message is requested to be transmitted on the CAN bus, inconsistent data may be sent.
The Application must ensure data consistency by one of the following mechanisms:
  Disable Interrupts while writing data to the global data buffer
  Use the message based confirmation flag to manage the data access handling. On
startup the access right is on Application side. Calling CanTransmit(..) this access right
is given to the CAN Driver. As soon as the confirmation flag is set by the CAN Driver,
the access right is given back to the Application.
  In polling mode the service function CanTxTask() must be used to transmit queued
messages. The transmission of a CAN message is only started if the CanTxTask() is
called. In polling mode every message is queued in the transmit queue. To ensure that
every message was send the CanTxTask() may be called cyclic.
5.2.3  Data Copy Mechanisms
There are two different methods for the Application to pass the data to be transmitted to
the CAN Driver. The CAN Driver selects the method for each message depending on the
CAN Driver description data. If no pretransmit function is defined, the usage of a global
data buffer is a prerequisite and the CAN Drivers internal data copy mechanism is always
used. If a pretransmit function is defined, the data to be transmitted may be stored
anywhere in the Applications memory and the user defined copy mechanism in the
pretransmit function is used.
5.2.3.1
Internal
With the internal data copy mechanism, the Application writes the data to be transmitted to
a global data buffer associated with the transmit message. The global data buffer is
defined by the Generation Tool. The access to the global data buffer is done by means of
access macros and/or functions which are also defined by the Generation Tool. After
passing the data to the global data buffer, the Application initiates the transmit request by
calling CanTransmit(..) and the data is copied internally to the CAN Controller hardware
registers.
Important
Data consistency of CAN messages has to be guaranteed by the Application if
  CanTransmit(..) is called on a higher interrupt or task level, or the transmit queue is
used.
©2010, Vector Informatik GmbH
Version: 3.01.01
33 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.2.3.2
User defined (“Pretransmit Function”)
Using the pretransmit function to pass the data to be transmitted to the CAN bus, the
Application first initiates the transmit request by calling CanTransmit(..). Just before the
message is put in the CAN chip, the CAN Driver calls a user defined pretransmit function.
For each transmit message a separate pretransmit function may be defined. Within this
user specific function the user can write the data directly to the hardware registers of the
CAN Controller, but other tasks can also be performed. The return code of the pretransmit
function indicates to the CAN Driver whether the data are to be copied by the CAN Driver
internally from the global data buffer to the CAN Controller hardware registers or not (if it is
already done within the pretransmit function).

Important
Be careful if a pretransmit function is used. Interrupts are not disabled during the call of
  this user specific function by the CAN Driver, therefore the restrictions for security level 0
are valid. If the interrupts are not disabled before and restored after the copy process by
the Application, data consistency of a CAN messages cannot be guaranteed if the
transmit queue is used.
5.2.4  Notification
After the successful transmission of a message on the CAN bus (i.e. at least one other
CAN bus node received the CAN message correctly with an acknowledge), the Application
can be notified by different confirmation mechanisms:
5.2.4.1
Data Interface (Confirmation Flag)
If a confirmation flag is used, this message related flag is set by the CAN Driver, if the
associated CAN message was sent on the CAN bus. This is done in the scope of the
transmit interrupt. The flag must be cleared by the Application.

Important
Interrupts have to be disabled while the confirmation flags are being cleared, because of
  the read-modify-write conflict if this operation is interrupted by a CAN transmit interrupt
routine. This can result in the loss of events.
5.2.4.2
Functional Interface (Confirmation Function for each message)
In parallel or instead of the data interface a functional interface can be configured, i.e. user
specific function is called if the associated CAN message was sent on the CAN bus. This
is also done in the scope of the transmit interrupt and therefore special care of the run time
of this function has to be taken.
5.2.4.3
Functional Interface (Common Confirmation Function for all messages)
A common confirmation function informs the application via ApplCanTxConfirmation about
a successful transmission of a message. Any message is confirmed via this callback
function.

Info
A canceled transmission will provoke a notification if the message was send on the bus.
  If the message had been deleted out of the hardware, the application will not be notified.
More…

©2010, Vector Informatik GmbH
Version: 3.01.01
34 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.2.5  Offline Mode
The CAN Driver's transmit path can be switched to the offline state, i.e. disabled. In this
state no CAN messages are sent to the CAN bus. On each transmit request the CAN
Driver checks the internal flag which indicates whether the transmission is currently
disabled and the transmit service function returns an error code. This flag is set and reset
by the following CAN Driver service functions
void CanOnline( void );
void CanOffline( void );

These CAN Driver service functions are called by the Network Management or by the
Application (only if there is no Network Management available on a specific CAN channel).

The Application can be notified about the mode change (e.g. if the Network Management
calls CanOnline() or CanOffline()). This is done with the following callback functions:

void ApplCanOnline( void );
void ApplCanOffline( void );

5.2.6  Partial Offline Mode
The partial Offline Mode enables the application to prevent the transmission of groups of
CAN messages. CanTransmit() returns a special code, if the requested message cannot
be sent because of the active partial offline mode. The partial offline mode is implemented
by the following functions:
void CanPartOnline ( vuint8 sendGroup );
void CanPartOffline( vuint8 sendGroup );
vuint8 CanGetPartMode( void );

The partial offline mode can handle up to eight different groups of messages. The function
parameter sendGroup decides about this group. CanPartOffline() switches all messages of
one ore more send groups to the offline state. Earlier calls of CanPartOffline() are not
affected. CanPartOnline() switches one or more send groups back to online state.
Each message might be assigned to one or more send groups. The names of the send
groups are configurable. Each send group can be switched to offline or online by using the
generated define:
C_SEND_GRP_<name>
C_SEND_GRP_ALL        can be used to switch all groups together to offline or online.

Example
The following table shows, which message is assigned to which send group (CANgen
  concept. For GENy concept, go to the next chapter.).

send group name
7 6 5 4 3 User2 User1 User0
©2010, Vector Informatik GmbH
Version: 3.01.01
35 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

MESSAGE1
  x  x
x

MESSAGE2
    x

x
MESSAGE3
  x  x

Example
for a possible program flow:
  CanPartOffline(C_SEND_GRP_User0); MESSAGE2 is stopped to be send
CanPartOffline(C_SEND_GRP_User1); MESSAGE1 is stopped to be send
              MESSAGE2 is still stopped to be send
status = CanGetPartMode();   status is equal to ( C_SEND_GRP_User0
|                          C_SEND_GRP_User1)
CanPartOnline(C_SEND_GRP_User0); MESSAGE1 is still stopped to be sent
              MESSAGE2 can be sent again
CanPartOffline(C_SEND_GRP_User0 | C_SEND_GRP_3);
MESSAGE1 is stopped to be sent
MESSAGE2 is stopped to be sent
MESSAGE3 is stopped to be sent
CanPartOnline(C_SEND_GRP_ALL);
All send groups are online again. All
messages can be sent now.
Info
If the offline mode and partial offline mode are used in parallel the offline
  mode has ‘higher priority’. This means if the offline mode is set the function
CanTransmit always returns ‘kCanTxFailed’ independent of the current
partial offline state.

5.2.6.1   Partial Offline Mode with GENy
In GENy there are
  8 Offline Modes (SendGroups)
  Default name is UserX, but can be changed as shown in the illustration below. There
Offline mode 4 is changed to MyGroup4.
  5 Message Classes for
  Default (0)
  Appl
  Nm
  Tp
  Diag
  Il

©2010, Vector Informatik GmbH
Version: 3.01.01
36 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

All messages are assigned automatically to a message class using their attribute
information from the DBC file.

Figure 5-5 Partial Offline Mode settings in GENy

Info
You find this information in the configuration view of the CAN Driver.

With the checked checkbox for OfflineMode4 (Message Class 1 (APPL) all application
messages are assigned to the Offline Mode 4.
If you select an application message, you will find the following:
©2010, Vector Informatik GmbH
Version: 3.01.01
37 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Figure 5-6 One Single Application Message Selected
At the Message Class entry you see this is an application message and below you see
your MyGroup4 and a checked checkbox. I.e. this message is assigned to MyGroup4.

Figure 5-7 User Defined assignment to Offline Modes
For any message you can decide whether to assign the message to another Offline Mode
or to additionally assign the message to another Offline Mode. In the example above, the
messate DummyTransmit (application message) is not assigned to MyGroup4 anymore.
Now this message is assigned to USER2.

©2010, Vector Informatik GmbH
Version: 3.01.01
38 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Figure 5-8  Overview Messages and Offline Modes

Info
If you cannot find any information concerning Offline Modes you should use the
  Customize Grid functionality. Activate the view below via: View|Customize Grid and
then select Offline Modes.

To get an overall view of which message is assigned to which group, or to do the
necessary assignments having a good overview, select all TxMessages in the tree view
and activate the Offline Modes via Customize Grid (described at the top of this chapter).
5.2.7  Passive State
The CAN Driver's transmit path can be switched to the passive state. In passive state no
transmit request is passed to the CAN bus, i.e. no CAN message is sent. However, there
is only the CAN bus activity affected but not the Application interface because there is no
error code returned and the notification is done in the normal way, i.e. the Application
software runs in normal operating mode. This is the main difference to the offline mode.
The passive state may be used to localize errors in a CAN bus and is realized by the
following CAN Driver service functions
void CanSetActive ( void );
void CanSetPassive( void );
©2010, Vector Informatik GmbH
Version: 3.01.01
39 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

The passive state of the CAN Driver is usually used during the development phase of the
CAN bus. If an Application might disturb the other nodes, it can be switched to passive
state temporarily and simulated by an appropriated tool. This is usually done by a
Diagnostics.

Info
To use the Passive State efficiently there must be a special support by the network
  designer. An external tool must be able to take over the tasks of the ECU simultaneously
when the ECU is switched to passive state.

The passive state of the CAN Driver must not be mixed up with the passive state of
OSEK Network Management. If the OSEK Network Management is put into passive
state (service functions SilentNM / TalkNM) only Network Management messages are
affected. The passive state of the CAN Driver prevents any CAN messages (including
Network Management messages) from being sent on the CAN bus.

Also note the following hints for the usage of the passive state:
  If the passive function is enabled the corresponding code in CanSetPassive() and
CanSetActive() is activated, otherwise only dummy macros will be provided. This results
in less CAN Driver code and an easy way to switch off this service function without
changing the Application software.
  The Application calls the service function CanSetPassive() to prevent transmission. In
case of a transmit queue it is cleared, i.e. confirmation activities may be lost during the
transition from active to passive state. Beginning with the next CanTransmit() the
messages are not sent on the CAN bus until CanSetActive() is called.
In case of a transmit queue, the service function CanSetPassive() has to be called in
the confirmation function of the last message to be sent on the CAN bus. If there is no
such request, CanSetPassive() can be called at any time.
In passive mode, the result seems to be successful, i.e. the code kCanTxOk is returned
from CanTransmit(), and all configured flags (cleared by the Application) are set and the
functions are called (Common Confirmation Function, Confirmation Flag and/or
Confirmation Function). Tx Observation is not used in passive state.
  To restart transmission, the service function CanSetActive() has to be called. Starting
with the next call of CanTransmit(), the messages are transmitted again on the CAN
bus.
Important
If the CAN Driver is switched from active to passive state, the transmit queue will be
  cleared and therefore some confirmations may be lost.

5.2.8  Tx Observe
This functionality is used to check the transmit path of the CAN Driver by the following
way: After a successful transmit request in the CAN Controller a specific function is called:
void ApplCanTxObjStart( logTxHwObject );
©2010, Vector Informatik GmbH
Version: 3.01.01
40 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

If the message was sent on the CAN network successfully another callback function is
called in the scope of the transmit interrupt:
void ApplCanTxObjConfirmed( logTxHwObject );

This functionality can be used to observe any transmission. As the CAN Driver is not time
triggered, the call back functions offer the application a way to start a timer with
ApplCanTxObjStart and stop this timer with ApplCanTxObjConfirmed. In case of exceeding
a predefined time for transmission, the message can be deleted or any other reaction can
be done.
In case of a well working system, these callback functions are normally called in a
symmetric way within the maximum specified delay time which is allowed in the existing
run time environment after a transmit request until the CAN message is sent to the CAN
bus successfully. In case of a transmit error a time-out supervision can be implemented by
these callback functions and error recovery can be done. If more than one hardware
transmit object is used, these callback functions can be called in a nested way and so an
additional counter is necessary. That counter has to be reset after each re-initialization of
the CAN Controller. This can be done in the following callback function:
void ApplCanInit( logTxHwObjectFirstUsed,
logTxHwObjectFirstUnused);
5.2.9 Cancellation of a Transmission
There are several ways to cancel a requested transmission.
5.2.9.1
Cancel a Transmission via CanInit
CanInit initializes the CAN controller hardware and can therefore be used to cancel any
current transmission. (see Re-Initialization of the CAN Controller). Some controllers do not
stop their transmission immediately, so it is possible that the Cancellation via CanInit()
could lead to an errorframe on the bus.
5.2.9.2
Cancel a Transmission via CanCancelTransmit or CanCancelMsgTransmit
Both functions work the same way, except that CanCancelTransmit cancels a transmission
initiated via CanTransmit and CanCancelMsgTransmit cancels a transmission initiated via
CanMsgTransmit.
The call of the confirmation function or the setting of the confirmation flag are suppressed,
if this message is already in the transmit buffer of the CAN Controller. If the transmit queue
is enabled, a pending transmit request in the queue is canceled.
These functions also delete messages in the hardware transmit buffer if configured. But
this feature is strongly dependent of the hardware. Some CAN Driver / CAN Controller
require the call of CanRxTask() / CanTxTask() to be able to continue.
Using the cancel functions out of the Tx observe functionality (see above) the handle for
the functions must be obtained via the function CanTxGetActHandle(CanObjectHandle
logTxHwObject). The return code decides whether it was a CanTransmit or a
CanMsgTransmit which causes a CanCancelTransmit or a CanCancelMsgTransmit.

©2010, Vector Informatik GmbH
Version: 3.01.01
41 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

CanTransmitHandle Hdl;
Hdl = CanTxGetActHandle(logTxHwObject);

if(Hdl == kCanBufferMsgTransmit)
{
CanCancelMsgTransmit(Hdl);
}
else if(Hdl < kCanBufferMsgTransmit)
{
CanCancelTransmit(Hdl);
}
else if(Hdl > kCanBufferMsgTransmit)
{
/* The Tx request was confirmed or cancelled, or no Tx request is pending. */
}

5.2.9.3
Notification about Cancellation of a message
The application can be notified each time the transmit request or the pending confirmation
is cancel. That means either the message based confirmation (flag or function) or the
cancel notification will be executed after successful call of CanTransmit() or
CanMsgTransmit().
To enable the notification the flag “CAN Cancel Notification” in the Generation Tool must
be selected. If this flag is set a Callback function informs the Application about that a
message was cancelled. ApplCanCancelNotification() will be called if the transmit request
was initiated via CanTransmit(), ApplCanMsgCancelNotification() will be called if the
request was set up via CanMsgTransmit().
©2010, Vector Informatik GmbH
Version: 3.01.01
42 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.2.10  Overview of Transmit Objects
The table shows the naming for different RI versions. Some of the features of the column
are hardware dependent.
Names before RI 1.4
Names RI 1.4
Names RI 1.5 and later
Transmit Object
Normal Transmit Object
Normal Transmit Object
Direct Transmit Objects
Full CAN Transmit Object
Full CAN Transmit Object
--- Direct
Transmit
Objects
---
Dynamic Transmit Objects
Dynamic Transmit Objects
Dynamic Transmit Objects
Low Level Message Transmit  Low Level Message Transmit
Low Level Message Transmit

5.2.11  Normal Transmit Object
A Normal Transmit Object is the hardware transmit object supported by all CAN Drivers. All
transmit messages that are not assigned to a Full CAN Transmit Object will be transmitted
via this Normal Transmit Object. The transmit queue works only on this object and the
Dynamic Transmit Objects can only be transmitted via this object, too.
5.2.12  Full CAN Transmit Objects
Each Full CAN Transmit Object has its own Hardware Transmit Object. This means a Full
CAN Transmit Object holds exactly one CAN message with a specific CAN identifier and
DLC. These CAN messages are statically assigned by the Generation Tool. Changes of
this reference during run time are not possible. There are two reasons for Full CAN
Transmit Object:
1.  The associated CAN message object is never occupied by another transmit request
2.  There is no need to copy the CAN identifier and the DLC. The message data can also
be stored directly in the CAN Controller and the transmit request can be initiated
directly.
Info
Full CAN objects are sent via CanTransmit() function.

5.2.13  Dynamic Transmit Objects
The CAN Driver supports the transmission of CAN messages with dynamic parameters.
These messages must not be specified in the CAN database. This feature can be used in
gateways, for example.
These dynamic objects can consist of mixed dynamic and static parts. CAN identifier, DLC
and data pointer can be selected separately as dynamic or static. The selection is common
for all dynamic objects. Pretransmit functions and confirmation functions are always static.
The CAN identifier priority for dynamic objects is lost if a transmit queue is used. Dynamic
objects have a higher internal priority than static objects, independent of their current CAN
identifier.
©2010, Vector Informatik GmbH
Version: 3.01.01
43 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Before the Application can use a dynamic object, the Application needs to reserve one.
This can be done by the following service function:
CanTransmitHandle CanGetDynTxObj( CanTransmitHandle txHandle);

The next step is to set all dynamic parameters of this object. This will be done by calling
the service functions:
void CanDynTxObjSetId ( ... );
void CanDynTxObjSetExtId ( ... );
void CanDynTxObjSetDlc ( ... );
void CanDynTxObjSetDataPtr ( ... );

After this, the dynamic object can be transmitted by calling CanTransmit(..) with the handle
of the dynamic object. The Application is allowed to use a dynamic object several times. If
the Application doesn’t need the dynamic objects any more, it can be released by the
service function
vuint8 CanReleaseDynTxObj( CanTransmitHandle txHandle );
There are two macros to allow a call of CanReleaseDynTxObj() in a confirmation function.
Both macros are only allowed to be called in the context of the user confirmation function
of this Dynamic Object.
CanConfirmStart(txHand This macro enables release of dynamic objects in a confirmation
le)
function.
txHandle has to be equal to the parameter of the confirmation
function.
CanConfirmEnd()
This macro restores security mechanism for release of dynamic
Objects.

Example:
void Confirm_ResDynTxObj ( CanTransmitHandle txHandle )
{
…
CanConfirmStart(txHandle);
if (CanReleaseDynTxObj( txHandle )== kCanDynNotReleased)
{ //error handling }
CanConfirmEnd();
…
}

If a dynamic object is used several times, the Application has to take care to use the
confirmation flag / function.
The maximum number of Dynamic Transmit Objects must be defined statically in the
Generation Tool.
Messages of dynamic transmit objects can not be sent via Full CAN Transmit Objects.

©2010, Vector Informatik GmbH
Version: 3.01.01
44 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.2.14  Priority of Transmit Objects

Message ID
Priority
Low 0
Full CAN Transmit Objects
High n
Normal Transmit Object
Low Level Transmit Object
(High End)

Figure 5-9  Priority of Transmit Objects


Full CAN Objects have the highest priority and they are sorted according to their ID. This is
automatically done by the Generation Tool.
There is only one Normal Transmit Object with a lower priority than the Full CAN Objects.
Dynamic Transmit Objects are transmitted via the Normal Transmit Object.
The Low Level Message Transmit Object has the lowest priority.
This priority is only valid, if the hardware is not able to arbitrate according the IDs.

©2010, Vector Informatik GmbH
Version: 3.01.01
45 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.3
Reception
5.3.1 Detailed Functional Description
CAN Message
Receive
No Action
Message not accepted
Hardware
Acceptance Filter
Message accepted
Interrupt Request
No
Interrupt Enabled
is stored
Yes
Enter
Receive Interrupt
Use
Use Receive Function
Receive Function
Use not
No
kCanCopyData
Yes
Use
Range
Filter
No
Match?
Yes
Range/Component
PreCopy Function
kCanNoCopyData
Use
UseMessage
Message not matched
Software
Message Not Matched
NotMatched
Acceptance Filter
Message accepted
Use not
Use
Check DLC
Use not
Use
Failed
DLC Failed
UseDlcFailed
DLC Check
Ok
Use not
Use
Use Generic Precopy
Generic
Use not
PreCopy Function
No
kCanCopyData
Yes
Defined
Precopy defined
Not defined
Precopy Function
No
kCanCopyData
Switches in the Generation Tool for
optional features of the CAN Driver
Yes
Decisions in the code, if the feature is selected.
Optional or mandatory functions of the CAN Driver
Copy Data
Mandatory path through the CAN Driver
Defined
Indication Flag
Optional path through the CAN Driver
defined
Direction of work flow
Indication Flag
Not defined
Defined
Indication Function
defined
Indication Function
Not defined
Leave
Receive Interrupt

end

Figure 5-10 Reception of a CAN messages
©2010, Vector Informatik GmbH
Version: 3.01.01
46 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

CAN messages are received asynchronously and without any explicit service function call.
Normally, the CAN Driver is informed by the CAN Controller via interrupt of the reception of
a CAN message. That means the received CAN identifier has passed the hardware
acceptance filtering of the CAN Controller and the entire message is stored in a receive
register. In case of a Basic CAN object, the message has to be retrieved and processed as
fast as possible. If a feature is only in Basic CAN or Full CAN available if is mentioned in
the text.
The gray decision symbols branch to features that can be removed from the CAN Driver
using the configuration options of the Generation Tool. Disabled features cannot be used
for any messages. The code for these features is completely removed. If a feature is
enabled, it can be determined for each message whether it is used or not.
The receive callback function ApplCanMsgReceived(..) is called on every reception of a
CAN message after the hardware acceptance filter is passed. Within this function the
Application may preprocess the received message in any way (ECU specific dynamic
filtering mechanisms, gateway functionality, etc...). If the function returns kCanCopyData,
the CAN Driver continues the processing. If the function returns kCanNoCopyData, the
CAN Driver terminates the message reception.
During the software acceptance filtering (only available for Basic CAN) the CAN Driver first
checks for range specific identifiers. For the range specific identifiers special precopy
functions may be defined. Afterwards the single CAN identifier based filtering is performed.
The CAN Drivers support different mechanisms like linear search, hash search or an index
search. In any case the filtering capabilities of the CAN Controller are used. The
corresponding receive object has to be determined by comparing the generated CAN
identifier in the data description tables with the received CAN identifier in the Basic CAN
object.
If the result of the software acceptance filtering is negative (only done for a Basic CAN
object), the callback function ApplCanMsgNotMatched() is called. Then the receive
interrupt is terminated immediately after the CAN Controller hardware is serviced.
After a CAN identifier match, the DLC will be checked. In case of a failed DLC check there
can be a configured callback function to notify the application.
In case of a successful DLC check the generic precopy function is called (if configured).
Generic precopy means that a common function named ApplCanGenericPrecopy() is
called for all identifiers. If this function returns kCanNoCopyData the CAN Driver
terminates further processing. If this function returns kCanCopyData, the CAN Driver
continues to work on the message received.
After the generic precopy if configured a precopy function separate for each message
according to the entry in the description data is called. Within this user specific function
any processing of the message received may occur (complete processing of a message or
special storage methods like ring buffers, FIFOs, ...). If the precopy function returns
kCanNoCopyData the CAN Driver terminates further processing. If the precopy function
returns kCanCopyData, the CAN Driver continues to work on the message received.
In the next step the data is copied to the global data buffer. The CAN Driver copies only
the number of bytes from the CAN receive buffer that is stored in the array CanRxDataLen.
©2010, Vector Informatik GmbH
Version: 3.01.01
47 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Then the indication actions defined for this message are performed. This means the
indication flag is set and/or the indication function is called. The Application has to reset
the indication flag before or after data processing.
In the following sections the processing steps are described using sequence charts. The
vertical directed lines within these diagrams represent program objects like interrupt
routines, functions or data objects. The horizontal lines represent program flow or data
access within the program. Within the sequence charts below flow control and program
instances are described using thick lines, data access is described using thin lines. Time
flows from the top of a chart downwards so that sequence „1“ is performed before
sequence „2“. The description of the sequence charts is given in the tables following the
charts.

CAN Data
RX Interrupt Driver
Global Data Indication
ApplCan-
CAN
Precopy
Indication
Application
Buffer
Routine
Parameters
Buffer
Flag
MsgReceived
1
2
3
4
5
6
7
8

Figure 5-11 Reception of a CAN message: The data is completely processed in the precopy function
No Description
1
A CAN message has passed the hardware acceptance filtering, the receive interrupt
routine is triggered
2
If configured, the ApplCanMsgReceived() callback function is called
3
The ApplCanMsgReceived() callback function returns kCanCopyData
4
Software acceptance filtering and identification of the received CAN message
5
If configured, the precopy function is called. The Application is able to take control over
the receive process immediately after the software acceptance filtering and direct access
to the CAN Controller receive register is possible.
6
Within the precopy function the data in the CAN Controller hardware registers are read
and completely processed.
7
The precopy function returns kCanNoCopyData. No further processing (copying of data,
indication actions) occurs in the CAN Driver
8
After servicing the CAN Controller hardware (the receive registers of the CAN Controller
are released), the receive interrupt routine is left.

Info
1. If the ApplCanMsgReceived() callback function returns kCanNoCopyData, the
received message is ignored. This means no further software filtering, no precopy, no
©2010, Vector Informatik GmbH
Version: 3.01.01
48 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

copying of data and no indication actions are performed.

2. If the precopy function returns kCanNoCopyData, no copying of data and no
indication actions are performed.

RX
CAN Data
Driver
Indication
ApplCanMsg
Interrupt
Global Data
CAN
Buffer
Parameters
Flag
Precopy
Indication
Receive
Application
Routine
Buffer
1
2
3
4
5
6
7
8
9
10
11

Figure 5-12 Reception of a CAN message: The CAN Driver internal copying mechanism is used

No  Description
1
A CAN message has passed the hardware acceptance filtering, the receive interrupt
routine is triggered
2
If configured, the ApplCanMsgReceived(..) callback function is called
3
The ApplCanMsgReceived(..) callback function returns kCanCopyData
4
Software acceptance filtering and identification of the received CAN message
5
If configured, the precopy function is called. The Application is able to take control
over the receive process immediately after the software acceptance filtering and the
direct access to the CAN Controller receive register is possible.
6
The precopy function returns kCanCopyData. The CAN Driver continues its normal
processing.
7
The received data are copied from the CAN Controller receive register to the global
data buffer associated to the CAN message
8
If configured, the indication flag is set (must be reset by the Application)
9
If configured, the indication function is called; any user actions can be performed
within this user specific function
10  Indication function returns to the receive interrupt routine
11  Receive interrupt routine is left

©2010, Vector Informatik GmbH
Version: 3.01.01
49 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.3.2  Receive Function
Before the software filtering is done, the Application optionally may use the
ApplCanMsgReceived() callback function called by the CAN Driver. Within this function the
Application can define whether to process the message received or not.
5.3.3  Range-Specific Precopy Functions
The CAN Driver's receive path can be configured to filter special identifier ranges and
associated precopy functions will be called directly. Up to four ranges are supported by the
CAN Driver. The ranges must be defined by a start address (e.g. 0x400) and a mask (e.g.
0x1F, i.e. if a bit is set it means don’t care) and leads to a specific range (in our example it
is from 0x400 to 0x 41F). The ranges are typically predefined by the Generation Tool for
special functions. If these are not used they are available for the application:

Range 0  Network
If the usage of a Network Management is configured
Management
Application
Application specific. May be used by the Application
Range 1  Diagnostics
If extended addressing mode of the Transport Protocol is configured
Application
Application specific. May be used by the Application
Range 2  Special usage
Car manufacturer specific
Application
Application specific. May be used by the Application
Range 3  Application
Application specific. May be used by the Application

Special capabilities of some CAN Controllers with several hardware acceptance filters may
also be used for the range specific filtering.
5.3.4  Identifier Search Algorithms
The following software filtering mechanisms are supported: All mechanisms but linear are
optional in the different hardware implementations.
Linear Search:
The identifier of the incoming message is compared to all CAN
identifiers in a table (if found, the search stops). The average search
time is proportional to the number of receive messages.
Hash Search:
An optimized search algorithm with a small known number of search
steps. The Generation tool calculates an optimized search table and
some parameters used at run time. The number of search steps can
be defined by the user. The less search steps the bigger the resulting
hash tables.
Table Search:
This is a kind of hash mechanism. The last three bits of a CAN
identifier are used as a selector for the search table. There are 8
different tables for each of the hardware acceptance filters in the
CAN Controller. Within the table a linear search is implemented.
Index Search:
A table with 2048 entries (one entry for each identifier) is used for
software filtering. Index Search is used for Standard ID only.

©2010, Vector Informatik GmbH
Version: 3.01.01
50 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.3.5  DLC check
The Data Length Code of a received message will be compared to the length of the
Application receive buffer of this message. If the DLC is smaller than the Application
receive buffer, data will not be copied. The length of the received message buffer is the
maximum length which is necessary to treat all signals for this ECU. To inform the
application the callback function ApplCanMsgDlcFailed will be called. The reception
process will be terminated afterwards.
Depending on the OEM the length of the received data bytes can be different at run time. It
is also possible to compare the length of the received message with a minimum length
which can be smaller than the Application receive buffer.
The behavior can be configured via generation tool and the database attribute
GenMsgMinAcceptLength.
5.3.6  Data Copy Mechanism
There are two different methods for the Application to access the data received from the
CAN bus.
5.3.6.1
Internal
Using the internal data copy mechanism, the CAN Driver copies the contents of the CAN
controller receive registers to a global data buffer associated to the receive message. The
Application can access the signal values in the message specific data buffer using access
macros or functions. The access macros are generated by the Generation Tool using
information in the CAN database. The signal access macros always return unsigned
values.
The Application itself is responsible for the data consistency of signals in a CAN message
which cannot be handled in atomic operations because the receive buffer may be
overwritten asynchronously by a CAN receive interrupt. Different mechanisms can be used
to guarantee data consistency:

1.  Disabling of the CAN receive interrupt.
2.  Read the receive signal. Compare the signal value with the signal in the hardware
buffer. Repeat the read operation if the values differ.
3.  Usage of the message based indication flag:
3.1  Clear the message indication flag
3.2  Read the data (one or more signals of a message)
3.3  Check the message indication flag: If set then return to 3.1

Depending on the OEM the length of the received data bytes can be different at run time.
Instead of copying all needed bytes (equal to the length of the global data buffer
associated to the receive message) the CAN Driver can be configured to copy the number
of received bytes. In case the number of received bytes exceed the length of the data
buffer, the CAN Driver takes care to copy at maximum the length of the data buffer.
©2010, Vector Informatik GmbH
Version: 3.01.01
51 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Info
The signal access macros are not affected. The application has to make sure, that it
does not access data via access macros that is not copied now because of a change of
the data length.

5.3.6.2
User-defined Precopy Functions
The user can define specific precopy functions for each receive object in the Generation
Tool. If defined, the CAN Driver calls this user-specific function immediately after the
software filtering. Within this precopy function the Application can access the data directly
in the CAN Controller receive registers. The precopy function indicates this to the CAN
Driver by the appropriate return code kCanNoCopyData and the further processing will be
terminated immediately. On the other side the CAN Driver can be forced to continue with
normal processing of the message after the precopy function by using the return code
kCanCopyData.
The parameter of the precopy function is a pointer to a structure. This structure includes
the handle of the received message and a pointer to the received data.
A separate user-specific function may be defined for each receive message. But it is also
possible to use the same function for different messages.
If no such function is defined, a NULL pointer is written to the corresponding description
data by the Generation Tool.
The user has to note that these user-specific functions are called in the receive interrupt.
Only short receive actions should be done to avoid negative influence on the Application
task by a long interrupt disable time.
The precopy mechanism can be used to handle only a small number of receive signals in
an efficient way, if there is a CAN receive message with 8 bytes but the receiving ECU for
example only needs the 6th bit of the 7th byte. The standard copy routine starts always at
the beginning of the receive data buffer and copies all data up to the last byte with
significant signals for the dedicated node (the 7th byte in the example above). This results
in some overhead in RAM and run time, particularly if these signals are mapped in the rear
part of the message. The precopy function can therefore be used to implement a user
specific copy routine and has to return the return code kCanNoCopyData.
Another example for a precopy function is a compare mechanism between the CAN
Controller receive register and the global Application buffer. If both are matching, data
have not to be copied and the indication is not necessary, i.e. kCanNoCopyData is
returned. Otherwise the return code kCanCopyData leads to the standard copy
mechanism of the CAN Driver and notification to the Application using indications.
The precopy function can also be used to implement receive queues (FIFO, FILO or ring
buffer).
5.3.7 Notification
After the reception of a message from the CAN bus and the successful hardware and
software acceptance filtering, the Application can be notified by different indication
mechanisms:
©2010, Vector Informatik GmbH
Version: 3.01.01
52 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.3.7.1
Data Interface (Indication Flag)
If an indication flag is used, this message related flag is set by the CAN Driver, if the
associated CAN message was received. This is done in the scope of the receive interrupt.
The flag must be cleared by the Application.

Caution
Interrupts have to be disabled during reset of the indication flags because of the read-
  modify-write conflict if this operation is interrupted by a CAN receive interrupt routine.
This can result in the loss of events.

5.3.7.2
Functional Interface (Indication Function)
In parallel or instead of the data interface a functional interface can be configured, i.e. a
user-specific function is called if the associated CAN message was received. This is also
done in the scope of the receive interrupt and therefore special care on the run time of this
user-specific function has to be taken. A special notification mechanism for the Application
can be implemented in such an indication function.
5.3.8  Not-Matched Function
If a CAN message has passed the hardware acceptance filtering but is rejected by the
software acceptance filtering (in case of a Basic CAN receive object) a special callback
function will be called (if configured):
void ApplCanMsgNotMatched( ... );

5.3.9  Overrun Handling
An Overrun appears if a CAN message is lost in the Basic CAN receive object, because
the other was not treated yet entirely. There are two possibilities how a message could be
lost. In some cases the old message was overwritten with a new message. In other cases
a new message couldn’t be received.
If enabled, the Application has to provide an overrun callback function:
void ApplCanOverrun( void );

The overrun handling itself is done by the CAN Driver.
5.3.10  Full CAN Overrun Handling
A Full CAN Overrun appears if a CAN message is lost in the Full CAN receive object,
because the other was not treated yet entirely. There are two possibilities how a message
could be lost. In some cases the old message was overwritten with a new message. In
other cases a new message couldn’t be received.
If enabled, the Application has to provide an overrun callback function for Full CAN
objects:
void ApplCanFullCanOverrun( void );

The overrun handling itself is done by the CAN Driver
©2010, Vector Informatik GmbH
Version: 3.01.01
53 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.3.11  Conditional Message Received
The Conditional Message Received function ApplCanMsgCondReceived() will be
conditional called for each reception of a CAN message. The condition can be set / reset
and read by application via CanResetMsgReceivedCondition(),
CanSetMsgReceivedCondition(), and CanGetMsgReceivedCondition(). The condition is
automatically set by CanInitPowerOn() and CanSleep().

5.4
Bus-Off Handling
There are several functions provided by the CAN Driver to handle a BusOff state of the
CAN Controller after severe transmit errors. For some CAN Controllers a re-initialization
must be done to satisfy the hardware requirements others are changing automatically to
the 'Error Active' state after 128 x 11 recessive bits on the CAN bus as it is specified in the
CAN protocol. Nevertheless it is recommended by most of the customer specific CAN bus
specifications to re-initialize the CAN Controller in every case, because the transmit error
might be caused by a faulty bit in the CAN Controller registers, e.g. bus timing registers, in
case of EMC influences. The following service functions have to be used by the
Application to handle a BusOff error:
void CanResetBusOffStart( CanInitHandle initObject );
void CanResetBusOffEnd( CanInitHandle initObject );

Typically an extension (compared to the CAN protocol specific requirements) of the error
recovery time for the CAN bus is implemented. This is done by switching the CAN Driver's
transmit path to off using the service function CanOffline(). Because of recursive calls of
some CAN Driver service functions, CanResetBusOffStart(..) and CanResetBusOffEnd(..)
are only allowed to be called in the offline mode of the CAN Driver, i.e. CanOffline() has to
be called before.
Typically the Network Management handles BusOff errors. In such case there are no
additional activities necessary by the Application. If no Network Management is used, the
Application has to provide a callback function
void ApplCanBusOff( void );

This callback function is called by the CAN Driver in case of BusOff. The error handling as
described above has to be done in this function. CanOnline has to be called outside of this
function on task level.

Important
For CAN controller which has autorecovery after BusOff detection we don’t recommend
  to use the status polling. If using status polling with autorecovery it could happen, that
the application doesn’t detect a BusOff because a transmit request was detected first
and the application wasn’t informed about the BusOff.
©2010, Vector Informatik GmbH
Version: 3.01.01
54 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.5
Sleep Mode
Some CAN Controllers support a special power-down mode with reduced power
consumption which is typically called sleep mode. This mode will be entered by the
following service:
vuint8 CanSleep( void );
Important
Before entering the sleep mode, some hardware specific preconditions have to be
  ensured, e.g. the CAN Controller transmit registers have to be empty. It has to be
guaranteed, that the following service functions are called before CanSleep():
void CanOffline( void );
void CanResetBusSleep( CanInitHandle initObject );.

The return to normal mode will be initiated by an explicit request of the Application:
vuint8 CanWakeUp( void );

Sleep mode is not supported by all CAN Controllers. If not, both related service functions
are provided to guarantee a unified service function interface for all CAN Drivers and to
make the Application mostly hardware independent. However, the functions itself have no
effect on the CAN Controller.
A subset of CAN Controllers, which are supporting a sleep mode in principle, are able to
be awakened by any CAN bus activity, i.e. a dominant level on the CAN bus. This wake-up
by CAN is an asynchronous event, normally detected by a special wake-up interrupt. The
Application will be notified by the following callback function:
void ApplCanWakeUp( void );

This callback function has to be provided by the Application. CanWakeUp() doesn't have to
be called in this case, because the CAN Controller returns to normal mode automatically
or initiated by the CAN Driver before this function call. Other communication related issues
like the activation of the bus transceiver hardware used or the return to the online mode
(see CanOnline()) have to be done in this callback function or as a consequence of this
event.
If a CAN Controller doesn't support a wake-up by the CAN bus, other hardware
substitutions like an external interrupt based on the CAN Controller's Rx line have to be
implemented.
The application should check the return value of CanSleep() and CanWakeUp()  in
every case to get the status of the CAN Controller. If CanSleep() returns kCanFailed
the CAN controller hasn’t entered into sleep mode. If CanWakeUp() returns kCanFailed
the CAN controller has not woken up. The application has to decide how to react on this
behavior.
If sleep mode is not entered, no CAN wake-up interrupt will be generated on detection of
any message on the CAN bus. The callback function ApplCanWakeUp() will not be called
and as a consequence the bus transceiver will not be initialized. This may lead to a
deadlock. Therefore it is necessary to call CanSleep() successfully to build a wake-up
capable system.
©2010, Vector Informatik GmbH
Version: 3.01.01
55 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

There is a limitation in the access to the API in Sleep mode.

The implementation of this functionality is very hardware dependent. See also CAN
controller specific documentation TechnicalReference_CAN_<hardware>.pdf [#hw_sleep].
5.6
Special Features
5.6.1  Status
Some internal software states of the CAN Driver and hardware states of the CAN
Controller can be read by the return code of the following service function:
vuint8 CanGetStatus( void );

In detail this is the following information:
  CAN Controller is in sleep mode (CanSleep() was called)
  CAN Controller is in stop mode ( CanStop() was called )
  CAN Driver transmit path is in offline mode(CanOffline() was called)
  current error states of the CAN Controller (Error-Active, Warning, Error-Passive or Bus-
Off)
Not all of the CAN protocol specific bus states are supported by each CAN Driver. Please
refer to the CAN Controller related section of the CAN Driver documentation for details
TechnicalReference_CAN_<hardware>.pdf [#hw_status].
There are special macros to provide an easier access on the single information in the
return code. These macros are true (not equal to 0) if the specific condition is valid and
false (equal to 0) if not. The parameter of this macros is the status, i.e. the return code of
CanGetStatus():
vuint8 CanHwIsOk ( vuint8 status );
vuint8 CanHwIsWarning( vuint8 status );
vuint8 CanHwIsPassive( vuint8 status );
vuint8 CanHwIsBusOff ( vuint8 status );
vuint8 CanHwIsSleep ( vuint8 status );
vuint8 CanHwIsWakeUp ( vuint8 status );
vuint8 CanHwIsStop ( vuint8 status );
vuint8 CanHwIsStart ( vuint8 status );
vuint8 CanHwIsOffline( vuint8 status );
vuint8 CanHwIsOnline ( vuint8 status );

If the hardware status information isn’t used by the Application this part of the functionality
can be disabled.
©2010, Vector Informatik GmbH
Version: 3.01.01
56 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.6.2  Stop Mode
The function CanStop() switches the CAN controller hardware to a state in which the CAN
controller doesn’t influence the communication of other nodes on the bus. For example no
hardware acknowledge is given, messages can’t be transmitted or received. In this state
the Can controller can’t be activated by activities on the CAN bus.
The function CanStart() reactivates the CAN controller hardware again.
The implementation of this functionality is very hardware dependent. See also CAN
controller specific documentation TechnicalReference_CAN_<hardware>.pdf [#hw_stop].
5.6.3  Remote Frames
The CAN Driver ignores remote frames and doesn’t answer on a remote request.
5.6.4  Interrupt Control
The interrupt control of the CAN Driver is done by the service functions
void CanGlobalInterruptDisable( void );
void CanGlobalInterruptRestore( void );

These functions have been moved to VstdLib. Only macros for compatibility reasons are
still provided in the CAN Driver:
#define CanGlobalInterruptDisable VStdSuspendAllInterrupts
#define CanGlobalInterruptRestore VStdResumeAllInterrupts

...more information see in the technical reference of the VStdLib.
(TechnicalReference_VstdLib.pdf).
5.6.4.1
Security Level
The security levels can be used to guarantee the data consistency of a complete CAN
message during the copy process (this is a must, because the CAN Driver does not know
anything about the signal structure of the message) and the access to the notification flags
(indication and confirmation). During these operations the interrupt lock time is as short as
possible. Depending on the program scope with access to CAN message signals,
indication or confirmation flags in the Application the following actions in the CAN Driver
have to be realized without any interruption:
  Copy process for receive messages (in the scope of the receive interrupt)
  Copy process for transmit messages (in the scope of CanTransmit(..) or in a pretransmit
function)
  Set of indication and confirmation flags (in the scope of the receive and transmit
interrupt)
  Some internal mechanisms for data consistency.
Therefore different security levels are supported:

©2010, Vector Informatik GmbH
Version: 3.01.01
57 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Level
CAN Driver
Restrictions for the Application
prevention
  None
No consistency mechanisms at all. The CAN
00
driver has to be configured to polling mode.
CAN interrupts are not allowed. All CAN driver
tasks, all calls to service functions, all data and
flag access must be performed from the same
level.
10
No Flag and Copy  No usage of CAN transmit and receive signals
Security
in the interrupt context. Usage of the TxQueue
is allowed in Tx polling mode only.
No reset of notification flags in the interrupt
context
If a fully-preemptive operating system is used,
the access to the transmit data and
transmission of the data has to be done on the
same priority level. (data consistency).
20 Interrupts
are
a) Interrupt-Mode:
disabled during the
No usage of CAN receive signals and no
copy process of
reset of notification flags in the interrupt
transmit messages
context
b) Polling-Mode
Access to CAN receive signals, indication
and confirmation flags is only allowed at the
same level or at lower level than CanTask().
30
Interrupts are
No restrictions for the Application, neither on
(default)  disabled during the  the usage of CAN receive or transmit signals
copy process of
nor on the reset of notifications flags, can i.e.
transmit and
both be done at any time.
receive messages
and during the
access to the
notification flags
Figure 1: Security levels
Important
Be careful if a pretransmit function is used. Interrupts are not disabled during the call of
  this user specific function by the CAN Driver, therefore the restrictions for security level
10 are valid. If the interrupts are not disabled before and restored after the copy process
by the Application, data consistency of a CAN messages cannot be guaranteed if the
transmit queue is used..

5.6.4.2
Control of CAN interrupts
The interrupt control of the CAN Interrupts is done by the service functions
void CanCanInterruptDisable( void );
©2010, Vector Informatik GmbH
Version: 3.01.01
58 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

void CanCanInterruptRestore( void );

These service functions control the CAN Interrupts. CanCanInterruptDisable disables the
CAN interrupts and CanCanInterruptRestore restores the state of the CAN interrupts
before the call of CanCanInterruptDisable. This mechanism is accompanied with a counter
to recognize the number of calls. A “disable” increments the counter and a “restore”
decrements the counter to allow nested calls of these functions.
These functions could only be called as pair. That means that on a
CanCanInterruptDisable must follow a CanCanInterruptRestore. Otherwise the selected
interrupt(s) are always disabled.
Additionally refer to the hardware description for the specific platform
TechnicalReference_CAN_<hardware>.pdf [#hw_int] especially concerning the handling of
the wake-up interrupt. It depends on the hardware whether the wake-up interrupt is
included or not.
There are two call back functions for the application. After the CanCanInterruptDisable the
function ApplCanAddCanInterruptDisable is called and after the CanCanInterruptRestore
the function ApplCanAddCanInterruptRestore is called.
Use these two functions to handle the wake-up interrupt if the hardware treats this interrupt
separately or if the Driver runs in Polling Mode disable the polling tasks.
To activate the call back functions refer to the API description of the functions.
5.6.5  Assertions
To detect some incorrect internal conditions of the CAN Driver during development,
integration and software test, there are different categories of so called assertions
configurable:

  User interface (for example input parameters, reentrance if not allowed)
  Fatal hardware errors
  Generated data
  Internal software errors (for example inconsistent internal states)
Each type of assertion can be configured independently.
These assertions will help in different development phases to deal with unexpected
problems which cannot be handled by the CAN Driver internally. In such case the following
callback function will be called by the CAN Driver:
void ApplCanFatalError( vuint8 errorNumber );

This callback function has to be provided by the Application. The function parameter
errorNumber gives more detailed information about the kind of error which is occurred.
Generally, the error number has to be checked to solve the underlying problem.
Important
This callback function must not return to the CAN Driver afterwards.

©2010, Vector Informatik GmbH
Version: 3.01.01
59 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

The recommended usage of the different assertion categories is explained in the following
table:

User Interface
Development of Application software
Fatal hardware errors
Development of Application software
New CAN Controller used
Generated Data
New version of the Generation Tool used
Test of software changes in the Generation Tool or CAN Driver
(Vector internal)
Internal software errors
Test of software changes in the CAN Driver (Vector internal)

These checks could be very run-time intensive and should only be activated for the
development phase of the CAN Driver
The call back function ApplCanFatalError() is called with the following error codes:
In case of a user assertion:
kErrorTxDlcTooLarge
CanTransmitVarDlc() or CanDynTxObjSetDlc() called
with DLC > 8.
kErrorTxHdlTooLarge service
function called with transmit handle too large
kErrorIntRestoreTooOften
CanCanInterruptRestore() called too often
kErrorIntDisableTooOften
CanCanInterruptDisable() called too often
kErrorChannelHdlTooLarge service
function called with channel handle too large
kErrorInitObjectHdlTooLarge
CanInit() called with parameter “initObject” too large
kErrorTxHwHdlTooLarge
CanTxGetActHandle() called with logical hardware
handle too large
kErrorHwObjNotInPolling
CanTxObjTask(), CanRxFullCANObjTask() or
CanRxBasicCANObjTask() called for hardware object
which is configured to interrupt mode.
kErrorHwHdlTooSmall
CanTxObjTask(), CanRxFullCANObjTask() or
CanRxBasicCANObjTask() called for hardware object
handle too small
kErrorHwHdlTooLarge
CanTxObjTask(), CanRxFullCANObjTask() or
CanRxBasicCANObjTask() called for hardware object
handle too large
kErrorAccessedInvalidDynObj
CanGetDynTxObj(),CanReleaseDynTxObj()  or
CanDynTxObjSet...() is called with wrong transmit
handle (transmit handle too large)
kErrorAccessedStatObjAsDyn
CanGetDynTxObj(),CanReleaseDynTxObj()  or
CanDynTxObjSet...() is called with wrong transmit
handle (transmit handle belongs to a static object)
kErrorDynObjReleased
UserConfirmation() or UserPreTransmit() is called for a
dynamic object which is already released.
kErrorPollingTaskRecursion
CAN Driver Polling tasks (Can...Task()) are called
©2010, Vector Informatik GmbH
Version: 3.01.01
60 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

recursive or interrupt each other.
kErrorDisabledChannel
Service function called for disabled channel on systems
with multiple configurations.
kErrorDisabledTxMessage
CanCancelTransmit() or CanTransmit() called with
txHandle that is not active in the current configuration.
(Physical multiple ECU)
kErrorDisabledCanInt
CanSleep() or CanWakeUp() is called with disabled
CAN Interrupts (via CanCanInterruptDisable()).
kErrorCanSleep
CanStop(), CanCanInterruptDisable() or
CanCanInterruptRestore() called during Sleep mode, or
offline mode is not active during sleep mode.
kErrorCanOnline
CanSleep() or CanStop() is called without offline mode.
kErrorCanStop
CanSleep() is called during Stop mode or offline mode
is not active during Stop mode.
kErrorWrongMask
CanSetTxIdExtHi() is called with illegal mask (mask
higher than 0x1F).
kErrorWrongId
CanDynTxObjSetId() or CanDynTxObjSetExtid() is
called with illegal ID (standard ID higher than 0x7ff or
extended ID higher than 0x1FFFFFFF).
In case of a generation assertion:
kErrorTxROMDLCTooLarge
Error in generated table of transmit DLCs
In case of a hardware assertion:
kErrorTxBufferBusy
HW transmit object is busy, but this is not expected
In case of a internal assertion:
kErrorTxHandleWrong
saved transmit handle has an unexpected value
kErrorInternalTxHdlTooLarge
internal function called with parameter tx handle too
large
kErrorRxHandleWrong
The variable rx handle has an illegal value.
kErrorTxObjHandleWrong
The handle of the hardware transmit object has an
illegal value.
kErrorReleasedUnusedDynObj
CanReleaseDynTxObj() is called for an object which is
already released.
kErrorTxQueueToManyHandle
The data type of the Tx Queue cannot handle all tx
messages.
kErrorInternalChannelHdlTooLarge Static function called with channel handle too large or
calculated channel handle too large.
kErrorInternalDisabledChannel
Static function called for disabled channel on systems
with multiple configurations.
kErrorInternalDisabledTxMessage Confirmation called with txHandle that is not active in
the current configuration. (Physical multiple ECU)

See the CAN Controller specific part of the CAN Driver documentation
TechnicalReference_CAN_<hardware>.pdf [#hw_assert] to get the list of additional
hardware specific error numbers for each CAN Driver.
©2010, Vector Informatik GmbH
Version: 3.01.01
61 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.6.6  Hardware Loop Check
There are two kinds of handling loops in the CAN Driver internally. The first one uses a
counter or other mathematics algorithms to abort the loop. The second one uses hardware
information from the CAN Controller to abort the loop.
Some of these state transitions have to be done by two steps:
1. Request
2. Acknowledge
In the first step the request for a specific action (e.g. re-initialization of the CAN Controller)
is set but generally it cannot be entered immediately because of the prerequisite that the
CAN bus has to be in idle state, i.e. waiting for a recessive CAN bus level. In normal
operation the described behavior is non-critical. However, an exception is a malfunction of
the hardware. If the hardware is damaged or disturbed for a longer time, this loop may be
too long or even endless and is finally stopped by a watchdog reset. Because of this
restrictive error recovery the complete software functionality is affected, nothing can be
done to prevent the repetition and additionally it is not possible to store any error specific
diagnostic information, i.e. the problem cannot be checked later.
To avoid those kinds of endless loops, the user can configure a special loop control. This
has to be handled by the Application. It cannot be done by the CAN Driver itself because it
is hardware dependent.
Therefore the Application is informed once by the following callback function if such a
critical loop is entered:
void ApplCanTimerStart( vuint8 timerIdentification );

This callback function starts a timer realized by the Application. The recommended timer
handling is counting downwards to zero because of faster code on most microprocessors.
The parameter identifies the timer, i.e. the kind of loop. It is necessary to identify the loop
type because the corresponding start value has to be set. Beside of this, different (not the
same) loops can be started re-entrant and so the Application has to provide one timer for
each kind of loop. The list of necessary timers is pre-defined by the CAN Driver and
depends on the CAN Controller. Please refer to CAN Controller specific documentation for
a detailed list TechnicalReference_CAN_<hardware>.pdf [#hw_loop].
During the loop wait state a second callback function is called repeatedly to control the
break condition for the loop by the Application:
vuint8 ApplCanTimerLoop( vuint8 timerIdentification );

This callback function returns the status of the corresponding timer to the CAN Driver. The
return code must be TRUE (not equal to 0) if the timer is still running and FALSE (equal to
0) if the timer has expired. In this case the CAN Driver loop will be left immediately. The
Application must be aware of a serious problem in the hardware and the following actions
have to be done:
  Store diagnostics information
  Switch off transmit (CanOffline()) and receive path of the CAN Driver
©2010, Vector Informatik GmbH
Version: 3.01.01
62 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

  Re-initialization of the CAN Driver (CanInit()). This may lead to the next loop control
failure, therefore it has to be limited and in case of a permanent severe hardware
problem a special limp home state has to be foreseen.
If the loop is terminated, a third callback function is provided to stop the previously started
loop control timer:
void ApplCanTimerEnd( vuint8 timerIdentification );

Important
Be aware of the priorities of the timer interrupt routine and the CAN interrupt routine. If
  the priority of the timer interrupt is below the CAN Interrupt priority the timer value for the
loop check may not be changed anymore while a CAN interrupt routine is running.

5.6.7  Support of OSEK-Compliant Operating Systems
If an OSEK operating system is used (ISR category 2), the hard-coded interrupt routines
for receiving, transmitting, error and wake-up are replaced by the ISR macro. In this case
an OSEK-specific header has to be included in can_inc.h to provide this macro.
5.6.8  Multiple-Channel CAN Driver
There are two different kinds of multiple-channel CAN Drivers: Sometimes two CAN
Controllers are used by one ECU on the same CAN bus, to increase the number of receive
and transmit objects. Logically, they can be conceived as a single CAN Controller. This
behavior is described in the chapter Common CAN.   more...
Usually, two (or more) CAN Controllers are used to serve different CAN networks, for
example in gateways.

5.6.8.1
Indexed CAN Driver
Indexed CAN Drivers work on more than one CAN bus without doubling of code. Function
names are equal to single channel (standard) CAN Driver. Function parameter are different
in many cases.
Switches in can_cfg.h are without a suffix but with effect to all CAN channels.

5.6.9  Standard Polling Mode
In polling mode no interrupts are used. Instead of interrupts the Application has to call
cyclic service functions in the CAN Driver, to work on transmit and receive messages as
well as other asynchronous events. This cyclic service function is
void CanTask ( void );

and calls all needed service functions for transmission, reception, error and wake-up which
can also be polled separately by the following service functions:
void CanRxBasicCANTask ( void );
void CanRxFullCANTask   ( void );
void CanTxTask ( void );
©2010, Vector Informatik GmbH
Version: 3.01.01
63 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

void CanErrorTask   ( void );
void CanWakeUpTask ( void );

The transmission and the reception of CAN messages can be served by interrupt or by
polling separately. Several configurations for polling are available:
  Full CAN Receive objects (for Full CAN Controllers only)
  Basic CAN Receive Objects
  Transmit objects
  Errors
  Wake-Up

5.6.9.1
Application Hints
Concerning the transmit polling the handling depends on the configuration of transmit
queue and the confirmation notification:
  No transmit queue but confirmation flags and/or confirmation functions are configured:
The CanTxTask() has to be called cyclically as fast as the confirmation notification is
needed or before CanTransmit() is called to release the CAN Controller hardware
transmit register.
  Transmit queue is configured: CanTransmit() puts only a transmit request into the
transmit queue. CanTxTask() transmits the messages on the CAN bus and does the
confirmation as well. Therefore CanTxTask() has to be called as fast as confirmation is
needed and the messages should be transmitted.
5.6.10  Handling of different identifier types
Every Vector CAN Driver supports per default only the standard mode using 11 bits for a
CAN identifier. In addition to this standard mode, some Vector CAN Drivers also support
the feature of extended mode using 29 bits for a CAN identifier.
Depending on the selected mode (standard or extended CAN identifiers) the Generation
Tool switches to the correct initialization structures used for the corresponding mode. The
type and number of supported search algorithms depends on the mode. Four different
CAN Driver configurations are possible:

  Standard mode (only 11 bit CAN identifier)
  Extended mode for the normal receive path of single CAN messages (only 29 bit CAN
identifier)
  Mixed mode (11 bit and 29 bit CAN identifier mixed on one CAN bus)
  For indexed drivers a bus dependent mode (11 bit CAN identifier on one and 29 bit CAN
identifier on the other CAN bus).
©2010, Vector Informatik GmbH
Version: 3.01.01
64 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

5.6.11  Copying Mechanisms
CanCopyToCan or CanCopyFromCan are hardware/compiler dependent functions that are
provided to optimize copying of data from/to the CAN hardware buffer.
Info
CanCopyFromCan should only be used within a precopy function. CanCopyToCan
  should only be used within a pretransmit function.

5.6.12  Common CAN
Common CAN is a special feature which is available only on request and on systems with
2 or more CAN controllers. The idea of this feature is to map different HW channels into
one application channel.
When Common CAN is activated additional receive FullCAN messages can be configured
on a channel. This is realized by using a second CAN controller for the same channel. The
first CAN controller (CAN A) supports Tx, Rx Full CAN and Rx Basic CAN. The second
CAN controller (CAN B) supports Rx Full CAN. Both CAN controllers have to be connected
to the same CAN bus. The API is always ‘Multiple Receive Channel’.

To enable the Common CAN feature activate the corresponding checkbox in the channel
settings.

First select the messages handled in Full CAN objects. Then select the “Hardware
Channel” to be used to receive the full CAN message.

Please note that the messages received on CAN B of the Common CAN must be filtered
out with the Basic CAN mask.

5.6.13  Multiple ECU
The feature Multiple ECU is usually used for nodes that exist more than once in a car with
only a few differences. At power up the application decides 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 common memory location for the
transmit data.

5.6.14  Signal Access Macros
Signal access macros are function like macros, to access signals within a message. They
can be used by the application for an easy access to signals. The generation of signal
value access macros can be enabled or disabled. If enabled, the Generation Tool
generates access macros using the signal names from the communication data base with
respect to prefixes or post-fixes defined in the Names tab.

©2010, Vector Informatik GmbH
Version: 3.01.01
65 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Figure 5-13 Name of signal access macros
For each signal an access macro is formed from the signal name in the CAN database, a
signal variable prefix (access via signal structures or byte/word commands), a signal
prefix, a signal postfix, and a signal variable postfix. Prefixes and postfixes can be
configured by the user in the generator program. To assure better readability, it is
advisable not to use all four prefixes and postfixes simultaneously.
The access macros for the CAN receive buffer get an extended prefix CAN_. Within
Precopy and Pretransmit routines these macros serve to access the CAN controller's CAN
receive and transmit buffer on a signal basis.

5.6.15 CAN RAM Check
The CAN driver supports a check of the CAN controller’s mailboxes. The CAN controller
RAM check is called internally every time the function CanInit() is called. The CAN driver
verifies that no used mailboxes is corrupt. A mailbox is considered corrupt if a predefined
pattern is written to the appropriate mailbox registers and the read operation does not
return the expected pattern. If a corrupt mailbox is found the function
ApplCanCorruptMailbox() is called. This function tells the application which mailbox is
corrupt.
After the check of all mailboxes the CAN driver calls the callback function
ApplCanMemCheckFailed() if at least one corrupt mailbox was found. The application
must decide if the CAN driver disables communication or not by means of the callback
function’s return value. If the application has decided to disable the communication there is
no possibility to enable the communication again until the next call to CanInitPowerOn().
The CAN RAM check functionality itself can be activated via Generation Tool. This include
the callback ApplCanMemCheckFailed(). The callback ApplCanCorruptMailbox() can only
be activated via a user configuration file.
©2010, Vector Informatik GmbH
Version: 3.01.01
66 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

6  Detailed Description of the Functional Scope (High End extension)
6.1  Transmission
6.1.1  Low-Level Message Transmit
Using a multiple channel CAN Driver the routing of complete CAN messages from one
CAN Bus to another one is supported by the function
vuint8 CanMsgTransmit(...);
This function has a parameter with a pointer to a CAN Message Buffer. So it is possible to
route the whole buffer from one CAN chip to the other one. To prevent a conflict with the
functional messages, this function uses an own send buffer (If an additional buffer is
available in the CAN Controller).
A special confirmation function and an initialization callback function are called.
void ApplCanMsgTransmitConf(...); within confirmation interrupt
void ApplCanMsgTransmitInit(...); within CanInit
These functions can be used by the application to implement a data queue mechanism.
There is no internal transmit queue for this transmit object available.

CanMsgTransmit() can also be used for dynamic transmission. Therefore the CAN driver
supports macros to write standard ID or extended ID, DLC and data to the structure:

CanMsgTransmitSetStdId (...)
CanMsgTransmitSetExtId (...)
CanMsgTransmitSetDlc (...)
CanMsgTransmitSetData (...)

6.2  Reception
6.2.1  Multiple Basic CAN
To improve efficiency of the hardware filtering and reduce the interrupt load produced by
reception of unwanted messages, the number of Hardware Basic CAN objects can be
changed in the Generation Tool. Each Hardware Basic CAN object has it’s own filter.
Increasing the number of Basic CAN objects will reduce the number of available Full CAN
objects (Rx and Tx).
This feature is only available for Full CAN controllers.
6.2.2  Rx Queue
The Rx Queue is a data queue which stores receive messages if the application does not
want to process them within the interrupt context. In some applications it may happen that
the run time in the receive interrupt becomes too long. This leads to long interrupt
latencies and possible loss of messages. The Rx Queue may help in these cases. If the
Rx Queue is configured the received messages are copied into this queue in the interrupt
©2010, Vector Informatik GmbH
Version: 3.01.01
67 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

context. The handling of the queued messages is done on task level. Messages which are
received by means of a RangePrecopy can also be copied into the queue or handled in
the interrupt context.
In order to handle the queued messages the application has to call cyclically a CAN Driver
function which checks for queued messages and processes them.
If Precopy and Indication functions are used for application messages, be aware that they
are not called in interrupt context any more.
By using the Rx Queue the runtime in the Rx interrupt is decreased. The average runtime
of the application is increased because of the overhead for handling the queue.
Please note
In case a range is configured to be handled via the Rx Queue, the return code of the
RangePrecopy for this range is ignored.
6.2.2.1 Handling in Receive Interrupt
During the receive interrupt the CAN Driver calls the callback function
ApplCanPreRxQueue() after the range or search algorithm match in order to let the
application decide whether the received message is processed within the interrupt or has
to be entered into the Rx queue. The function ApplCanPreRxQueue() is only called if
configured. Otherwise all received messages are handled by the Rx queue. If the Rx
Queue is full the CAN Driver notifies the application by calling the callback function
ApplCanRxQueueOverrun() (if configured) and discards the received message. After the
message was copied into the Rx queue the Rx interrupt is terminated.
©2010, Vector Informatik GmbH
Version: 3.01.01
68 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Receive message
(hardware filtering)
Hardware Level
Enter
Rx Interrupt Level Start
Receive Interrupt
ApplCanMsgReceived
(CanRxInfoStructPtr)
SW Range
entered
yes
no
Queue
yes
configured
no
Normal receive-interrupt
Range Precopy
ApplCanPreRxQueue
with SW message search
Indexed,
Function
(CanRxInfoStructPtr)
Hash,
Linear
ApplCanPreRxQueue
(CanRxInfoStructPtr)
Return
kCanCopyData
Return
yes
yes
kCanCopyData
no
Write FIFO
Write FIFO
Handle
Handle
normal receive-interrupt
no
Id
Id
with Message Precopy,
DLC
DLC
data copy mechanism,
Data
Data
Indication Function / Flags
yes
Exit
Rx Interrupt Level End

Figure 6-1 Handling of the Rx queue within the receive routine.
6.2.2.2 Handling on Task Level
In order to process the messages pending in the Rx queue the application has to call the
function CanHandleRxMsg(). This function processes all messages in the queue. The
processing of the messages is done in the same way like in the Rx interrupt. That means
©2010, Vector Informatik GmbH
Version: 3.01.01
69 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

for each message the Generic Precopy and the UserPrecopy are called. After that the
message data are copied into the RAM buffer and than the Indication Flag is set and the
UserIndication function is called. The last step is to delete the processed message from
the Rx queue.
CanHandleRxMsg()
Task Level Start
Read FIFO
Handle
Id
DLC
Data
SW Range
no
entered
yes
normal receive-interrupt
Range Precopy
with Message Precopy,
Function
data copy mechanism
Clear FIFO
Clear FIFO
Handle
Handle
Id
Id
DLC
DLC
Data
Data
Indication Function / Flags
Exit
Task Level End

Figure 6-2 Handling of the Rx queue on task level.
6.2.2.3 Resetting the Rx Queue
The CAN Driver provides the function CanDeleteRxQueue() to delete all messages
pending in the Rx Queue
©2010, Vector Informatik GmbH
Version: 3.01.01
70 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

6.3  Special Features
6.3.1  Individual Polling
Each mailbox (BasicCAN Rx, FullCAN Rx, FullCAN Tx, low level Tx and normal Tx) can be
selected to be polled or treat in interrupt context. This also provides the possibility to use
interrupt mode on one channel and polling mode on the other.
The polling tasks of the standard polling mode are still available. The CAN Driver provides
additional service functions to poll each mailbox individual.
void CanRxBasicCANObjTask ( ... );
void CanRxFullCANObjTask   ( ... );
void CanTxObjTask   ( ... );
These functions have the number of the mailbox and the hardware channel as parameter.
For both parameters, symbolic names are generated.
CanTask(),  CanErrorTask() and CanWakeUpTask() are available in this polling
mode, too.
©2010, Vector Informatik GmbH
Version: 3.01.01
71 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

7  Feature List (Standard and High End)
This general feature list describes the overall feature set of Vector CAN Drivers. Not all of
these features are mandatory for all CAN Drivers. Please refer to the CAN Controller
dependent CAN Driver manual for details TechnicalReference_CAN_<hardware>.pdf
[#hw_feature].

CAN Driver Functionality

Standard
HighEnd
Functions
Initialization

Power-On Initialization


CanInitPowerOn
Re-Initialization


CanInit

Transmission

Transmit Request


CanTransmit
Transmit Request Queue



Internal data copy mechanism



Pretransmit functions


UserPreTransmit
Common confirmation function


ApplCanTxConfirmation
Confirmation flag



Confirmation function


UserConfirmation
Offline Mode


CanOnline, CanOffline
Partial Offline Mode
CanOnline, CanPartOffline,


CanGetPartMode
Passive-Mode
CanSetActive,


CanSetPassive
Tx Observe mode
ApplCanInit,


ApplCanTxObjStart,
ApplCanTxObjConfirmed
Dynamic TxObjects
ID


CanDynTxSet(Ext)Id

DLC


CanDynTxSetDlc

Data-Ptr


CanDynTxSetDataPtr
Full CAN Tx Objects

Cancellation in Hardware
CanCancelTransmit,

CanCancelMsgTransmit
Low Level Message Transmit


CanMsgTransmit

Reception

Receive function


ApplCanMsgReceived
Search algorithms
Linear



Table

Index



Hash



©2010, Vector Informatik GmbH
Version: 3.01.01
72 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Range specific precopy functions
ApplCanRangeXxxPrecopy
4
4
Xxx .. 0,1,2,3
DLC check


ApplCanMsgDlcFailed
Internal data copy mechanism



Generic precopy function


ApplCanGenericPrecopy
Precopy function


UserPrecopy
Indication flag



Indication function


UserIndication
Message not matched function


ApplCanMsgNotMatched
Overrun Notification


ApplCanOverrun
Full-CAN overrun notification

ApplCanFullCanOverrun
Multiple Basic CAN



Rx Queue
CanHandleRxMsg,


CanDeleteRxQueue

Bus off

Notification function


ApplCanBusOff
Nested Recovery functions
CanResetBusOffStart,


CanResetBusOffEnd

Sleep Mode

Mode Change

CanSleep, CanWakeUp
Preparation


CanResetBusSleep
Notification function

ApplCanWakeUp

Special Feature

Status


CanGetStatus
Security Level



Assertions


ApplCanFatalError
Hardware loop check
ApplCanTimerStart


ApplCanTimerLoop
ApplCanTimerEnd
Stop Mode

CanStart, CanStop
Support of OSEK operating system



Standard Polling Mode
Tx


CanTxTask

Rx(Full CAN objects)

CanRxFullCANTask

Rx(Basic CAN objects)


CanRxBasicCANTask

Error


CanErrorTask

Wakeup

CanWakeUpTask
Individual Polling
CanTxObjTask,


CanRxFullCANObjTask,
CanRxBasicCANObjTask
Multi-channel



Support extended ID addressing mode



Support mixed ID addressing mode



Support access to error counters
CanRxActualErrorCounter


CanTxActualErrorCounter
©2010, Vector Informatik GmbH
Version: 3.01.01
73 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Copy functions
CanCopyFromCan,


CanCopyToCan
CAN RAM check


ApplCanMemCheckFailed
Figure 2: Feature List
   feature is supported in general (exceptions might be possible if a CAN controller is not able to support a
feature.

feature is not implemented for each hardware because different CAN controller doesn’t support this
feature.

©2010, Vector Informatik GmbH
Version: 3.01.01
74 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8  Description of the API (Standard)
The complete Standard CAN Driver API is described in this section.
8.1
API Categories
Depending on the number of supported channels, i.e. the number of connected CAN
networks to one ECU, the API of the CAN Driver is realized as "Single Channel" or
"Multiple Channel" with additional channel specific information.
8.1.1  Single Receive Channel (SRC)
A “Single Receive Channel” CAN Driver supports one CAN channel.
8.1.2  Multiple Receive Channel (MRC)
A "Single Receive Channel" CAN Driver is typically extended for multiple channels by
adding an index to the function parameter list (e.g. CanOnline() becomes to
CanOnline(channel)) or by using the handle as a channel indicator (e.g.
CanTransmit(txHandle)).
©2010, Vector Informatik GmbH
Version: 3.01.01
75 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.2
Data Types
The following general data types are defined by the CAN Driver:

vbittype
canbittype
Single bit information
vuint8
canuint8
unsigned 8 bit (byte) value
vuint16
canuint16
unsigned 16 bit (word) value
vuint32
canuint32
unsigned 32 bit (dword) value
vsint8
cansint8
signed 8 bit (byte) value
vsint16
cansint16
signed 16 bit (word) value
vsint32
cansint32
signed 32 bit (dword) value

There are special data types to reference specific generated data structures:
CanInitHandle Initialization
parameters
CanReceiveHandle Receive
parameters
CanTransmitHandle Transmit
parameters
CanChannelHandle
Channel parameters ( only available in indexed CAN Drivers )

Some data types are referencing the CAN Controller registers
CanChipDataPtr
Receive and transmit data register of the CAN Controller
CanChipMsgPtr
Complete receive and transmit message objects including CAN
identifier and DLC
Some data types are only available in Single Receive Channel and Multiple Receive
Channel CAN Drivers
typedef volatile struct
Structure with transmit information.
{

CanChipDataPtr     pChipData;
pChipData is the pointer to the transmit data bytes
CanTransmitHandle Handle;
in the CAN controller.
} CanTxInfoStruct;
Handle of the transmit message.

typedef volatile struct
Structure with receive information:
{
Channel from which the precopy is called.
CanChannelHandle   Channel;
pChipMsgObj is the pointer to the CAN Controller
CanChipMsgPtr     pChipMsgObj;
Receive Register. If there are several receive
objects with different memory addresses available,
CanChipDataPtr     pChipData;
pChipMsgObj contains the pointer to the dedicated
CanReceiveHandle   Handle;
receive object to get some information like CAN
} tCanRxInfoStruct;
identifier or DLC of the received message directly
out of the CAN Controller registers.

pChipData is the pointer to the received data bytes.
©2010, Vector Informatik GmbH
Version: 3.01.01
76 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Handle of the received message.
CanRxInfoStructPtr
Pointer to structure with receive information.

8.3
Constants
This information is stored in ROM.
8.3.1  Version Number
kCanMainVersion and kCanSubVersion contains the BCD coded version of the CAN
Driver:

kCanMainVersion
Main version of the CAN Driver (BCD coded in a vuint8 constant
variable)
kCanSubVersion
Sub version of the CAN Driver (BCD coded in a vuint8 constant
variable)
kCanBugFixVersion Release version of the CAN Driver (BCD coded in a vuint8
constant variable)

Example
A version number 2.31.00 is coded as 0x02 in kCanMainVersion, 0x31 in
  kCanSubVersion and 0x00 in kCanBugFixVersion.

8.4
Macros
8.4.1  Conversion between Logical and Hardware Representation of CAN
Parameter DLC
These macros are used to convert the CAN protocol specific parameter DLC between the
logical presentation (DLC: 0..8) and the CAN Controller dependent, internal register layout
of different CAN Controllers.
They are normally used by the Generation Tool for the initialization of the node specific
control structures but they are available also for the Application, if necessary.
The MK_... macros are converting from the logical to the CAN Controller dependent
representation:
MK_TX_DLC(dlc)
Conversion of transmit DLC, if associated CAN message has
standard identifier

The following macro is only allowed to be used if extended CAN identifiers are used:
MK_TX_DLC_EXT(dlc)  Conversion of transmit DLC if associated CAN message has an
extended identifier

The XT_... macro is converting from the CAN Controller dependent to the logical
presentation:
©2010, Vector Informatik GmbH
Version: 3.01.01
77 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

XT_TX_DLC(dlc)
Conversion of transmit DLC independent of identifier type

8.4.2  Direct Access to the CAN Controller Registers
These macros are defined by the CAN Driver to provide the access on CAN protocol
specific parameters like CAN identifier and DLC currently available in the CAN Controller.
To assign these information to a previously received message they are only valid in the
callback function ApplCanMsgReceived() or in user specific precopy functions. Only in this
scope there is a clear reference on receive messages possible and data in the CAN
Controller receive registers are still locked. They are referencing either on the CAN
Controller register or on the software shadow buffer of the CAN Driver, if used. The
parameter rxStruct is only available for Single Receive Channel and Multiple Receive
Channel Drivers and is the pointer to the receive information structure.
CanRxActualId(rxStruct)
Read identifier in logical presentation (0h..7FFh for
standard identifier or 0h..1FFFFFFFh for extended
identifier).
In case of mixed identifier, the macro
CanRxActualIdType can be used to decide whether
the CAN identifier is in standard or extended
format.
CanRxActualIdType(rxStruct) Read the format type of the CAN identifier
kCanIdTypeStd  standard
format
kCanIdTypeExt  extended
format
CanRxActualDLC(rxStruct)
Read DLC in logical presentation (0..8)
CanRxActualData(rxStruct,i) Read Data in logical presentation. i is the position
of the byte (0..7).
CanRxActualErrorCounter(
Read current status of the receive error counter. In
channel)
use of microcontrollers without an readable error
counter, this macro returns always 0.
CanTxActualErrorCounter(
Read current status of the transmit error counter. In
channel)
use of microcontrollers without an readable error
counter, this macro returns always 0.

The following macros are only available if extended CAN identifiers are used:
CanRxActualIdExtHi(
Read the bit 24 to 29 of the extended identifier in
rxStruct)
logical presentation
CanRxActualIdExtMidHi(
Read the bit 16 to 23 of the extended identifier in
rxStruct)
logical presentation
CanRxActualIdExtMidLo(
Read the bit 8 to 15 of the extended identifier in
rxStruct)
logical presentation
CanRxActualIdExtLo(
Read the bit 0 to 7 of the extended identifier in
rxStruct)
logical presentation

To write CAN protocol specific parameters like CAN identifier and DLC the to the CAN
controller there are some macros available. The parameter txStruct is only available for
©2010, Vector Informatik GmbH
Version: 3.01.01
78 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Single Receive Channel and Multiple Receive Channel Drivers and is the pointer to the
transmit information structure.
CanTxWriteActId(txStruct,
Write the parameter id in standard format and in
id)
logical presentation to the hardware.
CanTxWriteActDLC(rxStruct,  Write the DLC in logical presentation (0..8)
dlc)

The following macro is only available if extended CAN identifiers are used:
CanTxWriteActExtId(
Write the parameter id in extended format and in
txStruct,id)
logical presentation to the hardware.

8.4.3  Interpretation of the CAN Status
The following macros are used to decode the return code of CanGetStatus() (TRUE
means not equal to zero):
CanHwIsOk(state)
This macro returns TRUE, if the status of the CAN
Controller is Error-Active.
CanHwIsWarning(state) This macro returns TRUE, if the status of the CAN
Controller is Warning (at least one error counter is equal or
higher than 96).
CanHwIsPassive(state) This macro returns TRUE, if the status of the CAN
Controller is Error-Passive.
CanHwIsBusOff(state)  This macro returns TRUE, if the status of the CAN
Controller is Bus-Off. This information is only temporary. The
time when this status changes from TRUE to FALSE
depends on the CAN controller. This could be after the CAN
controller has resynchronized on the bus regardless of the
Busoff recovery by the Application. This could also be after
CanResetBusoffStart() is called or after
CanResetBusoffEnd() is called.
Hint: Busoff detection has to be performed with
ApplCanBusoff().
CanHwIsWakeup(state)  This macro returns TRUE, if the CAN Controller is not in
sleep mode.
CanHwIsSleep(state)
This macro returns TRUE, if the CAN Controller is in sleep
mode.
CanHwIsStart(state)
This macro returns TRUE, if the CAN Controller is not in
stop mode.
CanHwIsStop(state)
This macro returns TRUE, if the CAN Controller is in stop
mode.
CanIsOnline(state)
This macro returns TRUE, if the CAN Driver is online.
CanIsOffline(state)
This macro returns TRUE, if the CAN Driver is offline.

©2010, Vector Informatik GmbH
Version: 3.01.01
79 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Not all CAN Controllers support all of the hardware dependent states. Please refer to the
CAN Controller specific documentation TechnicalReference_CAN_<hardware>.pdf
[#hw_status] for details.
8.4.4  Access to low level transmit structure
These macros are defined by the CAN driver to fill the set the data to be transmitted with
CanMsgTransmit():
CanMsgTransmitSetStdId(  Write the parameter id in standard format and in logical
tCanMsgTransmitStruct
presentation to the structure txData.
*txData, vuint16 id)
CanMsgTransmitSetExtId(  Write the parameter id in extended format and in logical
tCanMsgTransmitStruct
presentation to the structure txData.
*txData, vuint32 id)
CanMsgTransmitSetDlc(
Write the DLC in logical presentation (0..8)
tCanMsgTransmitStruct
*txData, vuint8 dlc)
CanMsgTransmitSetData(
Write the data bytes to be transmitted to the structure
tCanMsgTransmitStruct
txData. nrDataBytes specifies the number of bytes to be
*txData, vuint8
copied (e.g. same as the DLC, max. 8). txDataBytes
nrDataByte, vuint8
points to the current location where the data has to be
*txDataBytes)
copied from.

8.5
Functions
This chapter contains a description of the CAN Driver functions (services, callbacks and
user specifics) and the appropriate parameters and return codes. The function declarations
are given in C syntax as explained below:
vuint8 CanTransmit( CanTransmitHandle txObject );
  vuint8 is the type of the return code
  CanTransmit is the name of the function
  CanTransmitHandle is the type of the function parameter
  txObject is the function parameter.
©2010, Vector Informatik GmbH
Version: 3.01.01
80 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.1  Service Functions
8.5.1.1  CanInitPowerOn
CanInitPowerOn
Prototype
Single Receive Channel
void CanInitPowerOn ( void )
Multiple Receive Channel
Parameter
-
-
Return code
-
-
Functional Description
The service function CanInitPowerOn() initializes the CAN Controller and the CAN Drivers internal
variables. The CAN Driver is always set to online mode and active operating state.
Particularities and Limitations
  This service function has to be called before any other CAN Driver function. The interrupts have to
be disabled during this service function is called.
  For indexed CAN Drivers every channel is initialized with kCanInitObj0.

8.5.1.2
CanInit
CanInit
Prototype
Single Receive Channel
void CanInit ( CanInitHandle initObject )
Multiple Receive Channel
void CanInit ( CanChannelHandle channel, CanInitHandle
initObject )
Parameter
initObject
Handle of an initialization structure. The generated macros should be
used:
kCanInitObjX  (with X = 1 ... Number of generated initialization structures)
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
Initialization of the CAN Controller hardware. It is used to cancel pending transmit requests in the CAN
Controller transmit register and to change the baud rate or the hardware acceptance filters.
Online/Offline mode and Active/Passive state will not be changed.
Particularities and Limitations
©2010, Vector Informatik GmbH
Version: 3.01.01
81 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

  During the call of CanInit(..), the CAN Driver has to be in offline mode.
  CanInit(..) is not reentrant and therefore must not be called recursively.
  CanInit(..) must not be interrupted by CanReset...(..), CanSleep(..), CanWakeUp(..)
or by any CAN interrupt service routine and vice versa.
  CanInit(..) must not interrupt the confirmation interrupt and must not be called in the
confirmation or indication function.

8.5.1.3  CanTransmit
CanTransmit
Prototype
Single Receive Channel
vuint8 CanTransmit ( CanTransmitHandle txObject )
Multiple Receive Channel
Parameter
txObject
Handle of the transmit object
Return code
kCanTxOk
The transmit request was accepted by the CAN Driver
kCanTxFailed
Error code because one of the following conditions:
  Transmit request could not be passed to the CAN Controller because
the transmit registers are busy (only if there is no transmit queue
used)
  CAN Driver's transmit path is in offline mode
  Special hardware conditions of the CAN Controller (e.g. the sleep
mode was entered; failed synchronization on the CAN bus)
kCanTxPartOffline
Error code because the transmit path of the CAN driver is in partial
offline mode for this transmit object.
Functional Description
The service function CanTransmit(..) checks if a transmit register in the CAN Controller is
available. If so, the transmit process is initiated in the CAN Controller and kCanTxOk is returned. If not
and if there is no transmit queue configured, the function call returns with the error code
kCanTxFailed or kCanTxPartOffline. For a CAN Driver with a configured transmit queue; the
transmit request is marked in the queue and kCanTxOk is returned. Only the transmit request is saved
but not the associated data. As soon as one of the CAN Controller transmit registers becomes
available (successful transmission of the previous transmit request), the next transmit request with the
highest priority (lowest CAN identifier) in the transmit queue will be serviced.
By the parameter txObject all information for transmission (CAN identifier, DLC, location and length
of data, etc...) can be taken from the CAN Driver description data. They will be copied to the CAN
Controller and the transmit process is started. The message will be actually transmitted on the CAN
bus after a successful arbitration of the CAN protocol.
After a successful transmission a CAN message (at least one other CAN bus node gives an
acknowledge) the confirmation notification (a flag will be set or a user specific function will be called)
are executed in the scope of the CAN transmit interrupt routine.
Particularities and Limitations
©2010, Vector Informatik GmbH
Version: 3.01.01
82 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

  CanTransmit(..) supports the Network Management which can enable or disable the CAN
Driver's transmit path by means of the CAN Driver service functions CanOnline() and
CanOffline(). No distinction is made between Network Management and Application messages.
In the offline mode, the transmit request is rejected with an error code.
  For CAN Controllers with priority controlled transmit queue (hardware or software) the sequence of
transmission may deviate from the call sequence of CanTransmit(..) because the transmit
queues are handled according to priorities (lowest CAN identifier first) and not according to the
chronological order of the entries in the queue (FIFO).
  The generated handles should be used to reference the transmit objects. The names consist of the
message symbol, a prefix and a postfix. Fixed rules are used to build these names. For more
details please refer to the user manual of the Generation Tool

8.5.1.4
CanTask
CanTask
Prototype
Single Receive Channel
void CanTask ( void )
Multiple Receive Channel
Parameter
-
-
Return code
-
-
Functional Description
The service function CanTask() does polling of error events, receive objects, transmit objects and
wake-up events in the CAN Controller according to the configured polling mode. In multiple channel
drivers the CanTask() handles all channels.
Particularities and Limitations
  CanTask() must not run on higher priority than other CAN functions.
  CanTask() is available, if any polling mode is configured for the CAN Driver
  CanTask() is also available for some CAN Controllers if cancellation in hardware is configured.
See more about that in the CAN Controller specific documentation
TechnicalReference_CAN_<hardware>.pdf [#hw_cancel] .

8.5.1.5  CanTxTask
CanTxTask
Prototype
Single Receive Channel
void CanTxTask ( void )
Multiple Receive Channel
void CanTxTask ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
©2010, Vector Informatik GmbH
Version: 3.01.01
83 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Functional Description
The service function CanTxTask() does polling of transmit objects in the CAN Controller.
Confirmation functions will be called and confirmation flags will be set. If the transmit queue is
configured, this service function additionally transmits the queued messages.
Particularities and Limitations
  CanTxTask() is available, if the general polling mode or the transmit polling mode is configured.
  CanTxTask() is also available for some CAN Controllers if cancellation in hardware is configured.
See more about that in the CAN Controller specific documentation
TechnicalReference_CAN_<hardware>.pdf [#hw_cancel] .

8.5.1.6
CanRxFullCANTask
CanRxFullCanTask
Prototype
Single Receive Channel
void CanRxFullCANTask ( void )
Multiple Receive Channel
void CanRxFullCANTask ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanRxFullCanTask() does polling of Full CAN receive objects (if available)
according to the configured polling mode.
Particularities and Limitations
  CanRxFullCanTask() must not run on higher priority than other CAN functions.
  CanRxFullCanTask() is available if the Full CAN receive polling mode is configured.

8.5.1.7
CanRxBasicCANTask
CanRxBasicCANTask
Prototype
Single Receive Channel
void CanRxBasicCANTask ( void )
Multiple Receive Channel
void CanRxBasicCANTask ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanRxBasicCANTask() does polling of Basic CAN receive objects according to
the configured polling mode.
©2010, Vector Informatik GmbH
Version: 3.01.01
84 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Particularities and Limitations
  CanRxBasicCANTask() must not run on higher priority than other CAN functions.
  CanRxBasicCANTask() is available if the Basic CAN receive polling mode is configured.

8.5.1.8
CanErrorTask
CanErrorTask
Prototype
Single Receive Channel
void CanErrorTask ( void )

Multiple Receive Channel
void CanErrorTask ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanErrorTask() does polling of error events in the CAN Controller. In case of a
BusOff, the callback function ApplCanBusOff() is called by this service function.
Particularities and Limitations
  CanErrorTask() is available if the error polling is enabled.

8.5.1.9
CanWakeUpTask
CanWakeUpTask
Prototype
Single Receive Channel
void CanWakeUpTask ( void )
Multiple Receive Channel
void CanWakeUpTask ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanWakeUpTask() does polling of the wake-up events in the CAN Controller
according to the enabled polling mode. In case of a wake-up event on the CAN bus, the callback
function ApplCanWakeUp() will be called by this service function.
Particularities and Limitations
  CanWakeUpTask() is available if the wakeup polling is enabled.
  A wake-up by the CAN bus is not supported by all CAN Controllers. Please refer to the CAN
controller specific documentation TechnicalReference_CAN_<hardware>.pdf [#hw_sleep].
©2010, Vector Informatik GmbH
Version: 3.01.01
85 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.1.10 CanOnline
CanOnline
Prototype
Single Receive Channel
void CanOnline ( void )
Multiple Receive Channel
void CanOnline ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanOnline() enables the CAN Driver's transmit path for all subsequent transmit
requests of CanTransmit(..). This is prerequisite to transmit any CAN message.
The current status of the transmit path can be queried by CanGetStatus().
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations
If a Network Management is used, the service function CanOnline() may only be used by the
Network Management.
It is only allowed to call CanOnline() on Task level. No other CAN Driver service function is allowed
to be interrupted by CanOnline().

8.5.1.11 CanOffline
CanOffline
Prototype
Single Receive Channel
void CanOffline ( void )
Multiple Receive Channel
void CanOffline ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanOffline() disables the CAN Driver's transmit path for all subsequent
transmit requests of CanTransmit(..).
While the transmit path is blocked, transmit requests by CanTransmit(..) are rejected with an
error. This can be determined by evaluating the return code.
The current status of the transmit path can be queried by CanGetStatus().
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations
©2010, Vector Informatik GmbH
Version: 3.01.01
86 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

If the CAN Driver is configured to use a transmit queue, all queue entries will be cleared, i.e. transmit
requests will be lost.
If a Network Management is used, the service functions CanOffline() may only be used by the
Network Management.

8.5.1.12  CanPartOnline
CanPartOnline
Prototype
Single Receive Channel
void CanPartOnline ( vuint8 sendGroup )
Multiple Receive Channel
void CanPartOnline ( CanChannelHandle channel, vuint8
sendGroup )
Parameter
sendGroup
Send group or groups to be switched to online.
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanPartOnline() enables the CAN Driver's transmit path for the selected send
groups.
The current status of the partial offline mode can be queried by CanGetPartMode().
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations

8.5.1.13  CanPartOffline
CanPartOffline
Prototype
Single Receive Channel
void CanPartOffline ( vuint8 sendGroup )
Multiple Receive Channel
void CanPartOffline ( CanChannelHandle channel, vuint8
sendGroup )
Parameter
sendGroup
Send group or groups to be switched to offline.
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
©2010, Vector Informatik GmbH
Version: 3.01.01
87 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

The service function CanPartOffline() disables the CAN Driver's transmit path for the selected
send groups.
While the transmit path is blocked for a selected group, transmit requests of a message assigned to
this group by CanTransmit(..) are rejected with kCanPartOffline. This can be determined by
evaluating the return code.
The current status of the partial offline mode can be queried by CanGetPartMode().
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations
  A queued message will be still send after the function CanPartOffline() was called.

8.5.1.14  CanGetPartMode
CanGetPartMode
Prototype
Single Receive Channel
vuint8 CanGetPartMode ( void )
Multiple Receive Channel
vuint8 CanGetPartMode ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
vuint8
Send groups which are in partial offline mode.
  C_SEND_GRP_NONE (if the partial mode is inactive)
  C_SEND_GRP_ALL (if the partial mode is active for all groups.)
NOTE: predefined macros can be used to check for all or none
send groups.
For indexed CAN Driver, this functionality is related to the specified CAN
channel.
See also 5.2.6 Partial Offline Mode page 35
Functional Description
Reads the current partial offline status of the CAN Driver.
Particularities and Limitations

8.5.1.15  CanGetStatus
CanGetStatus
Prototype
Single Receive Channel
vuint8 CanGetStatus ( void )
Multiple Receive Channel
vuint8 CanGetStatus ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
©2010, Vector Informatik GmbH
Version: 3.01.01
88 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Return code
vuint8
Software status of the CAN Driver. The following information is coded in
the return code:
  CAN Driver is offline (CanOffline() was called)
If extended status is enabled, this function also returns the hardware
status of the CAN Controller. The following additional information are
coded in the return code:
  Warning level, Error-Active/-Passive state and Bus-Off of the CAN
Controller
  CAN Controller is in sleep mode (CanSleep() was called)
  CAN Controller is in stop mode (CanStop() was called)
There are special macros to get this information in the return code.
These macros are TRUE (not equal to 0) if the specific condition is valid
and FALSE (equal to 0) if not. The parameter of these macros is the
status, i.e. the return code of CanGetStatus():
  CanHwIsWarning(..), CanHwIsPassive(..),
CanHwIsBusOff(..),
  CanHwIsOk(..)
  CanHwIs Sleep(..), CanHwIsWakeup(..)
  CanHwIsStop(..), CanHwIsStart(..)
  CanIsOffline(..), CanIsOnline(..)
For indexed CAN Driver, this functionality is related to the specified CAN
channel.
Functional Description
Reads the current status of the CAN Driver and the CAN Controller.
Particularities and Limitations

8.5.1.16  CanSleep
CanSleep
Prototype
Single Receive Channel
vuint8 CanSleep (void )
Multiple Receive Channel
vuint8 CanSleep ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
Result of the sleep request:
kCanFailed
Sleep mode not entered
kCanOk
Sleep mode entered
kCanNotSupported
The function CanSleep is not supported by this driver
Functional Description
The service function CanSleep() puts the CAN Controller into sleep mode. This reduces the power
©2010, Vector Informatik GmbH
Version: 3.01.01
89 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

consumption of the CAN Controller and enables the wake up behavior if the CAN Controller supports
this functionality. For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations
  This functionality is not supported for all CAN Controllers. In such case the function is provided by
the CAN Driver but without any effect on the CAN Controller. This is done to enable the Application
to realize an orthogonal software structure.
  If it is supported by the CAN Controller, on a wake-up by the CAN bus, the callback function
ApplCanWakeUp() is called.
  If a message is currently transmitted or received during the call of this service function, a direct
wake-up interrupt occurs or the CAN Driver remains in this function until the sleep mode is entered.
This behavior of the CAN Controller has to be considered in implementing the Application or the
Network Management. (This behavior is hardware dependent and described more detailed in the
CAN controller specific documentation TechnicalReference_CAN_<hardware>.pdf [#hw_sleep])
  If the sleep mode is not entered, no CAN wake-up interrupt occurs on the detection of any
message on the CAN bus. The callback function ApplCanWakeUp() will not be called and in
consequence the bus transceiver will not be initialized. This leads to CAN bus errors. Therefore it is
necessary to call a set of functions to realize a wake-up capable system. The order of the function
calls is very important. more…
  During the call of CanSleep() the CAN Driver has to be offline.
  CanSleep() must not be interrupted by CanInit(), CanReset...(), CanWakeUp() or any
CAN interrupt routine and vice versa.
  CanSleep(..) is not reentrant and therefore must not be called recursively.
  It isn’t allowed to call CanSleep() out of any callback function.
  CAN Interrupts should be disabled during the call of CanSleep(). To disable the Can Interrupts
the function CanCanInterruptDisable() should not be used. If this function is used no CAN
wake-up interrupt occurs on the detection of any message on the CAN bus. The callback function
ApplCanWakeUp() will not be called.
  In Sleep mode the service functions CanGetStatus(), CanWakeUp(), CanTransmit(),
CanTask() and all Can...Task() are allowed to be called.

8.5.1.17  CanWakeUp
CanWakeUp
Prototype
Single Receive Channel
vuint8 CanWakeUp ( void )
Multiple Receive Channel
vuint8 CanWakeUp ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
Result of the wakeup request
kCanFailed
wakeup was not successful
kCanOk
Sleep mode left
kCanNotSupported
The function CanWakeUp is not supported by this driver.
Functional Description
©2010, Vector Informatik GmbH
Version: 3.01.01
90 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

The service function CanWakeUp() enters the normal operating mode of the CAN Controller.
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations
  This functionality is not supported for all CAN Controllers. In such case the function is provided by
the CAN Driver but without any effect on the CAN Controller. This is done to enable the Application
to realize an orthogonal software structure.
  During the call of CanWakeUp() the CAN Driver has to be offline.
  No wake-up interrupt is generated by the call of CanWakeUp().
  CanWakeUp() must not be interrupted by CanInit(), CanReset...(), CanSleep() or any
CAN interrupt routine and vice versa.
  CanWakeUp(..) is not reentrant and therefore must not be called recursively.

8.5.1.18  CanStart
CanStart
Prototype
Single Receive Channel
vuint8 CanStart ( void )
Multiple Receive Channel
vuint8 CanStart ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
Result of the stop request
kCanFailed
Restart of the CAN controller was not successful.
kCanOk
Stop mode left
kCanNotSupported
The function CanStart() is not supported by this driver.
Functional Description
The service function CanStart() enters the normal operating mode of the CAN Controller.
CanStart() may not be called in sleep mode.
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations
  This functionality is not supported for all CAN Controllers. In such case the function is provided by
the CAN Driver but without any effect on the CAN Controller. This is done to enable the Application
to realize an orthogonal software structure.
  During the call of CanStart() the CAN Driver has to be offline.
  CanStart() must not be interrupted by CanInit(), CanReset...(), CanWakeUp() or any
CAN interrupt routine and vice versa.
  CanStart(..) is not reentrant and therefore must not be called recursively.

©2010, Vector Informatik GmbH
Version: 3.01.01
91 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.1.19  CanStop
CanStop
Prototype
Single Receive Channel
vuint8 CanStop ( void )
Multiple Receive Channel
vuint8 CanStop ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
Result of the stop request:
kCanFailed
Stop mode not entered
kCanOk
Stop mode entered
kCanNotSupported
The function CanStop is not supported by this driver.
Functional Description
The service function CanStop() puts the CAN Controller into stop or hold mode. This does not
reduces the power consumption of the CAN Controller. The stop mode can only be left by calling
CanStart(). CanStop() must not be called in sleep mode.
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations
  This functionality is not supported for all CAN Controllers. In such case the function is provided by
the CAN Driver but without any effect on the CAN Controller. This is done to enable the Application
to realize an orthogonal software structure.
  During the call of CanStop() the CAN Driver has to be offline.
  CanStop() must not be interrupted by CanInit(), CanReset...(), CanWakeUp() or any
CAN interrupt routine and vice versa.
  CanStop(..) is not reentrant and therefore must not be called recursively.

8.5.1.20  CanGlobalInterruptDisable
CanGlobalInterruptDisable
Prototype
Single Receive Channel
void CanGlobalInterruptDisable ( void )
Multiple Receive Channel
Parameter
-
-
Return code
-
-
Functional Description
The service function CanGlobalInterruptDisable() disables interrupts, either by changing the
global interrupt control flag of the microprocessor or the interrupt level of the interrupt controller. In the
later case, the interrupt level is configurable. All levels where the CAN API (CAN interrupt, Flags,
service functions) is used have to be disabled.
©2010, Vector Informatik GmbH
Version: 3.01.01
92 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Particularities and Limitations
  This function has been moved to VstdLib. For more information refer to Application note-ISC-2-
1050_VstdLibIntegration.pdf

8.5.1.21  CanGlobalInterruptRestore
CanGlobalInterruptRestore
Prototype
Single Receive Channel
void CanGlobalInterruptRestore ( void )
Multiple Receive Channel
Parameter
-
-
Return code
-
-
Functional Description
The service function CanGlobalInterruptRestore() restores the initial interrupt state which was
saved temporarily by CanGlobalInterruptDisable(). If CanGlobalInterruptDisable() is
called in a nested way, the initial interrupt state is not restored until
CanGlobalInterruptRestore() has been called as many times.
Particularities and Limitations
  This function has been moved to VstdLib. For more information refer to Application note AN-ISC-2-
1050_VstdLibIntegration.pdf

8.5.1.22  CanCanInterruptDisable
CanCanInterruptDisable
Prototype
Single Receive Channel
void CanCanInterruptDisable ( void )
Multiple Receive Channel
void CanCanInterruptDisable ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanCanInterruptDisable() disables all CAN interrupts of one CAN channel,
either by changing the CAN interrupt control flags of the interrupt controller or of the CAN controller. In
case of separately implemented wake-up interrupt routines they have to be disabled by the
application. Therefore the callback function ApplCanAddCanInterruptDisable() can be
activated.
Particularities and Limitations
©2010, Vector Informatik GmbH
Version: 3.01.01
93 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

  The CAN Drivers differ in the implementation of this service function. Please refer to the CAN
Controller specification documentation TechnicalReference_CAN_<hardware>.pdf [#hw_int] for
details.
  This service function is not allowed to be called during Sleep-Mode.

8.5.1.23  CanCanInterruptRestore
CanCanInterruptRestore
Prototype
Single Receive Channel
void CanCanInterruptRestore ( void )
Multiple Receive Channel
void CanCanInterruptRestore ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanCanInterruptRestore() restores the initial interrupt state which was
saved temporarily by CanCanInterruptDisable(). If CanCanInterruptDisable() is called in
a nested way, the initial interrupt state is not restored until CanCanInterruptRestore() has been
called as many times. In case of separately implemented wake-up interrupt routines they have to be
restored by the application. Therefore the callback function ApplCanAddCanInterruptRestore()
can be activated.
Particularities and Limitations
  The CAN Drivers differ in the implementation of this service function. Please refer to the CAN
Controller specification documentation TechnicalReference_CAN_<hardware>.pdf [#hw_int] for
details.
  This service function is not allowed to be called during Sleep-Mode.

8.5.1.24  CanSetPassive
CanSetPassive
Prototype
Single Receive Channel
void CanSetPassive ( void )
Multiple Receive Channel
void CanSetPassive ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanSetPassive(..) switches the CAN Driver to the passive state.
For indexed CAN Driver, this functionality is related to the specified CAN channel.
©2010, Vector Informatik GmbH
Version: 3.01.01
94 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Particularities and Limitations
  If the CAN Driver is configured to use a transmit queue, all queue entries will be cleared, i.e.
transmit requests and subsequent confirmations will be lost.
  The passive state of the CAN Driver will have an effect only if it is enabled by the CAN Driver
configuration. Nevertheless this service function is available at any time

8.5.1.25  CanSetActive
CanSetActive
Prototype
Single Receive Channel
void CanSetActive ( void )
Multiple Receive Channel
void CanSetActive ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanSetActive() switches the CAN Driver back to the active state.
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations
  The passive state of the CAN Driver will have an effect only if it is enabled by the CAN Driver
configuration. Nevertheless this service function is available at any time.

8.5.1.26  CanResetBusOffStart
CanResetBusOffStart
Prototype
Single Receive Channel
void CanResetBusOffStart ( CanInitHandle initObject )
Multiple Receive Channel
void CanResetBusOffStart ( CanChannelHandle channel,
CanInitHandle initObject )
Parameter
initObject
Handle of an initialization structure. The generated macros should be
used:
kCanInitObjX (with X = 1 ... Number of generated initialization structures)
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
©2010, Vector Informatik GmbH
Version: 3.01.01
95 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

This service function starts error recovery of the CAN Controller directly after BusOff. Usually a re-
initialization of the CAN Controller is done. The correct handling of a BusOff depends on the used
CAN Controller. Please refer to the CAN Controller specification documentation
TechnicalReference_CAN_<hardware>.pdf [#hw_busoff] for details.
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations
  During the call of CanResetBusOffStart(..), the CAN Driver has to be in offline mode.
  CanResetBusOffStart(..) is not reentrant and therefore must not be called recursively.
  CanResetBusOffStart() must not be interrupted by CanInit(), CanResetBusOffEnd(),
CanResetBusSleep(), CanSleep(), CanWakeUp() or by any CAN interrupt service routine
and vice versa.
  This service function can be realized as a preprocessor macro.

8.5.1.27  CanResetBusOffEnd
CanResetBusOffEnd
Prototype
Single Receive Channel
void CanResetBusOffEnd ( CanInitHandle initObject )
Multiple Receive Channel
void CanResetBusOffEnd ( CanChannelHandle channel,
  CanInitHandle initObject )
Parameter
initObject
Handle of an initialization structure. The generated macros should be
used:
kCanInitObjX (with X = 1 ... Number of generated initialization structures)
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
Completes the error recovery after BusOff. For most of the CAN Drivers this service function has no
effect.
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations
  During the call of CanResetBusOffEnd(..), the CAN Driver has to be in offline mode.
  CanResetBusOffEnd(..) is not reentrant and therefore must not be called recursively.
  CanResetBusOffEnd() must not be interrupted by CanInit(), CanResetBusOffStart(),
CanResetBusSleep(), CanSleep(), CanWakeUp() or by any CAN interrupt service routine
and vice versa.
  This service function can be realized as a preprocessor macro.

8.5.1.28  CanResetBusSleep
CanResetBusSleep
Prototype
©2010, Vector Informatik GmbH
Version: 3.01.01
96 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Single Receive Channel
void CanResetBusSleep ( CanInitHandle initObject )
Multiple Receive Channel
void CanResetBusSleep ( CanChannelHandle channel,
  CanInitHandle initObject )
Parameter
initObject
Handle of an initialization structure. The generated macros should be
used:
kCanInitObjX  (with X = 1 ... Number of generated initialization structures)
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX  (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
This service function aborts pending transmit requests in the CAN Controller before the sleep mode of
the CAN Controller is entered. This can be done by different ways, depending on CAN Controller
specific features:
  Complete re-initialization of the CAN Controller (using the service function CanInit() )
  Cancel of the transmit requests
Please refer to the CAN Controller specific documentation for details.
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations
  During the call of CanResetBusSleep(..), the CAN Driver has to be in offline mode.
  CanResetBusSleep(..) is not reentrant and therefore must not be called recursively.
  CanResetBusSleep() must not be interrupted by CanInit(), CanResetBusOffStart(),
CanResetBusOffEnd(), CanSleep(), CanWakeUp() or by any CAN interrupt service routine
and vice versa.
  This service function can be realized as a preprocessor macro.

8.5.1.29  CanGetDynTxObj
CanGetDynTxObj
Prototype
Single Receive Channel
CanTransmitHandle CanGetDynTxObj ( CanTransmitHandle
Multiple Receive Channel
txObject )
Parameter
txObject
Handle of the dynamic transmit object.
Return code
CanTransmitHandle
Handle of the dynamic transmit object or kCanNoTxDynObjAvailable
if no dynamic transmit object is available or the specific dynamic object
is already used.
Functional Description
©2010, Vector Informatik GmbH
Version: 3.01.01
97 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Reserves a dynamic transmit object.
To use dynamic transmit objects an Application must reserve a dynamic transmit object from the CAN
Driver.
Before transmission, the Application must set all configured dynamic parameters of the dynamic
transmit object.
The Application can use a dynamic transmit object for one or many transmissions, but finally it must
release the dynamic transmit object by calling CanReleaseDynTxObj(..).
Particularities and Limitations
This service function is only available, if dynamic transmit objects are configured.
The generated handles should be used to reference the transmit objects. The names consist of the
message symbol, a prefix and a postfix. Fixed rules are used to build these names. For more
details please refer to the online help of the Generation Tool.

©2010, Vector Informatik GmbH
Version: 3.01.01
98 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.1.30  CanReleaseDynTxObj
CanReleaseDynTxObj
Prototype
Single Receive Channel
vuint8 CanReleaseDynTxObj ( CanTransmitHandle txObject )
Multiple Receive Channel
Parameter
txObject
Handle of the dynamic transmit object which was returned by
CanGetDynTxObj(..)
Return code
kCanDynReleased
Dynamic object is released
kCanDynNotReleased
Dynamic transmit object couldn’t be released because the object is still
in the transmit queue or in the transmit register of the CAN Controller.
CanReleaseDynTxObj(..) has to be called later again.
Functional Description
Release a dynamic transmit object, which was reserved before by calling CanGetDynTxObj(..).
The dynamic transmit object is referenced by txObject.
After a transmission of one or more messages is finished, the Application has to release the reserved
resource, because the number of dynamic transmit objects is limited and the Application should not
keep reserved dynamic transmit objects for a longer time.
Particularities and Limitations
  This service function is only available, if dynamic transmit objects are configured.
  The parameter txObject was reserved before by a call to CanGetDynTxObj(..).

8.5.1.31  CanDynTxObjSetId
CanDynTxObjSetId
Prototype
Single Receive Channel
void CanDynTxObjSetId ( CanTransmitHandle txObject, vuint16
Multiple Receive Channel
id )
Parameter
txObject
Handle of the dynamic transmit object which was returned by
CanGetDynTxObj(..).
id
CAN identifier in standard format
Return code
-
-
Functional Description
Sets the CAN identifier in standard format of a dynamic transmit object. The dynamic transmit object is
referenced by txObject.
Particularities and Limitations
  This service function is only available, if dynamic transmit objects are configured.
  The parameter txObject was reserved before by a call to CanGetDynTxObj(..).

©2010, Vector Informatik GmbH
Version: 3.01.01
99 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.1.32  CanDynTxObjSetExtId
CanDynObjSetExtId
Prototype
Single Receive Channel
void CanDynTxObjSetExtId ( CanTransmitHandle txObject,
Multiple Receive Channel
vuint16 idExtHi,
vuint16 idExtLo)
Parameter
txObject
Handle of the dynamic transmit object which was returned by
CanGetDynTxObj(..)
idExtHi
Upper 16 bit of the CAN identifier in extended format
idExtLo
Lower 16 bit of the CAN identifier in extended format
Return code
-
-
Functional Description
Sets the CAN identifier in extended format of a dynamic transmit object. The dynamic transmit object
is referenced by txObject
Particularities and Limitations
  This service function is only available, if dynamic transmit objects are configured.
  The parameter txObject was reserved before by a call to CanGetDynTxObj(..).

8.5.1.33  CanDynTxObjSetDlc
CanDynTxObjSetDlc
Prototype
Single Receive Channel
void CanDynTxObjSetDlc ( CanTransmitHandle txObject,
Multiple Receive Channel
  vuint8 dlc )
Parameter
txObject
Handle of the dynamic transmit object which was returned by
CanGetDynTxObj(..)
dlc
Data Length Code of the dynamic transmit object
Return code
-
-
Functional Description
Sets the Data Length Code of a dynamic transmit object. The dynamic transmit object is referenced by
txObject.
Particularities and Limitations
  This service function is only available, if dynamic transmit objects are configured.
  The parameter txObject was reserved before by a call to CanGetDynTxObj(..).

©2010, Vector Informatik GmbH
Version: 3.01.01
100 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.1.34  CanDynTxObjSetDataPtr
CanDynTxObjSetDataPtr
Prototype
Single Receive Channel
void CanDynTxObjSetDataPtr ( CanTransmitHandle txObject,
Multiple Receive Channel
  vuint8 *pData )
Parameter
txObject
Handle of the dynamic transmit object which was returned by
CanGetDynTxObj(..)
*pData
Data reference of the application specific data buffer referenced by the
dynamic transmit object
Return code
-
-
Functional Description
Sets the data pointer of a dynamic transmit object. The dynamic transmit object is referenced by
txObject.
Particularities and Limitations
  This service function is only available, if dynamic transmit objects are configured.
  The parameter txObject was reserved before by a call to CanGetDynTxObj(..).

8.5.1.35  CanCancelTransmit
CanCancelTransmit
Prototype
Single Receive Channel
void CanCancelTransmit ( CanTransmitHandle txObject )
Multiple Receive Channel
Parameter
txObject
Handle of the transmit object
Return code
-
-
Functional Description
The call of the confirmation function resp. setting of the confirmation flag associated with txObject are
suppressed, if this message is already in the transmit buffer of the CAN controller.
If the transmit queue is enabled, a pending transmit request in the queue is canceled.
Particularities and Limitations
The function call of CanCancelTransmit() must not interrupt the transmit ISR, CanTransmit() or
the CanTxTask().
Though a transmission is canceled it will be sent if the request has been already in the hardware
object. Only if activated and highly dependent on hardware and vehicle manufacturer the transmit
request can be deleted in the hardware transmit object, too.

8.5.1.36  CanCopyFromCan
CanCopyFromCan
©2010, Vector Informatik GmbH
Version: 3.01.01
101 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Prototype
Single Receive Channel
void CanCopyFromCan (void *dst, CanChipDataPtr src, vuint8
Multiple Receive Channel
len)
Parameter
dst
Pointer to the destination in default memory. This pointer is available in
the Precopy Function.
src
Pointer to the source CAN buffer or temporary buffer
len
number of bytes which have to be copied
Return code
-
-
Functional Description
This function copies data from the CAN data buffer to the RAM.
Particularities and Limitations
This function can only be used within precopy functions.

8.5.1.37  CanCopyToCan
CanCopyToCan
Prototype
Single Receive Channel
void CanCopyToCan ( CanChipDataPtr dst, void *src, vuint8
Multiple Receive Channel
len)
Parameter
dst
Pointer to the destination CAN buffer or temporary buffer. This pointer is
available in the Pretransmit Function.
src
Pointer to the source in default memory.
len
number of bytes which have to be copied
Return code
-
-
Functional Description
This function copies data from the RAM into the CAN data buffer.
Particularities and Limitations
This function can only be used within pretransmit functions.

8.5.1.38  CanTxGetActHandle
CanTxGetActHandle
Prototype
Single Receive Channel
CanTransmitHandle CanTxGetActHandle (CanObjectHandle
Multiple Receive Channel
logTxHwObject)
Parameter
©2010, Vector Informatik GmbH
Version: 3.01.01
102 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

logTxHwObject
Handle of the CAN hardware transmit object. For indexed drivers this is
a unique number over all CAN channels.
Return code
txObject
Handle of the transmit object which is currently in the hardware transmit
object. In case of enabled LowLevelMessageTransmit, this could also be
a handle of such a message
kCanBufferMsgTransmit: CanCancelMsgTransmit
kCanTxHandleNotUsed: Handle is not valid
Functional Description
This service functions returns the handle of the transmit message, which has been transmitted in a
certain CAN hardware transmit object. The return value can be used as a parameter for
CanCancelTransmit(). If the return value is kCanBufferMsgTransmit,
CanCancelMsgTransmit() has to be called in stead of CanCancelTransmit().
CanCancelTransmit() ignores invalid handle and kCanBufferMsgTransmit.
Particularities and Limitations
This function is only allowed to be called in or after ApplCanTxObjStart() and before
ApplCanTxObjConfirmed() of a certain CAN buffer.

8.5.1.39  CanResetMsgReceivedCondition
CanResetMsgReceivedCondition
Prototype
Single Receive Channel
void CanResetMsgReceivedCondition ( void )
Multiple Receive Channel
void CanResetMsgReceivedCondition ( CanChannelHandle
channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX   (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanResetMsgReceivedConditional() disables the calling of
ApplCanMsgCondReceived().
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations

8.5.1.40  CanSetMsgReceivedCondition
CanSetMsgReceivedCondition
Prototype
Single Receive Channel
void CanSetMsgReceivedCondition ( void )
Multiple Receive Channel
void CanSetMsgReceivedCondition ( CanChannelHandle channel
)
Parameter
©2010, Vector Informatik GmbH
Version: 3.01.01
103 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX   (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanSetMsgReceivedConditional() enables the calling of
ApplCanMsgCondReceived().
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations

8.5.1.41  CanGetMsgReceivedCondition
CanGetMsgReceivedCondition
Prototype
Single Receive Channel
void CanGetMsgReceivedCondition ( void )
Multiple Receive Channel
void CanGetMsgReceivedCondition ( CanChannelHandle channel
)
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX   (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The service function CanGetMsgReceivedConditional()returns the status of the condition for
calling ApplCanMsgCondReceived().
For indexed CAN Driver, this functionality is related to the specified CAN channel.
Particularities and Limitations

©2010, Vector Informatik GmbH
Version: 3.01.01
104 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.2  User Specific Functions
The user specific functions listed in this section are called by the CAN Driver and provided
by the Application when certain events occur. The user can define user specific functions
specifically for each message. The names in this section are only placeholders. The name
could be set in the generation tool. The type of the particular user specific message must
agree with the function types listed here.
8.5.2.1
UserPrecopy
UserPrecopy
Prototype
Single Receive Channel
vuint8 UserPrecopy ( CanRxInfoStructPtr rxStruct )
Multiple Receive Channel
Parameter
rxStruct
Pointer to the receive structure
Return code
kCanCopyData
Received data will be copied using the CAN Driver 's internal copy
mechanism
kCanNoCopyData
CAN Driver doesn’t copy data and doesn’t perform indication
Functional Description
User specific function of the CAN Driver, which is called in the receive interrupt of a CAN message
before copying the data from the CAN Controller receive register to the application specific global data
buffer.
Depending on the function's return code, the CAN Driver will either terminate the processing of the
received message (kCanNoCopyData) or resume normal processing (kCanCopyData).
Particularities and Limitations
  For each CAN message a separate precopy function may be defined.

8.5.2.2
UserIndication
UserIndication
Prototype
Single Receive Channel
void UserIndication( CanReceiveHandle rxObject)
Multiple Receive Channel
Parameter
rxObject
Handle of the received message
Return code
-
-
Functional Description
User specific function which is called in the receive interrupt of a CAN message after data has been
copied and the CAN Controller receive register have been released.
Particularities and Limitations
  For each CAN message a separate indication function may be defined.
©2010, Vector Informatik GmbH
Version: 3.01.01
105 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.2.3
UserPreTransmit
UserPreTransmit
Prototype
Single Receive Channel
vuint8 UserPreTransmit( CanTxInfoStruct txStruct )
Multiple Receive Channel
Parameter
txStruct
Transmit structure
Return code
kCanCopyData
After the return of this user specific function, the CAN Driver copies the
data to be transmitted from the application specific global data buffer
associated to the corresponding message to the CAN Controller transmit
register
kCanNoCopyData
The CAN Driver does not copy data but starts the transmit request in the
CAN Controller immediately
Functional Description
User specific function which is called before the message is copied from the application specific data
buffer to the transmit register of the CAN Controller. This is done in the scope of the Tx interrupt or the
CanTxTask() via CanTransmit(..). The usage of the internal copy mechanism of the CAN Driver
is controlled by the return code.
A possible usage is the acquiring and copying of existing data which are spread in the Application.
Particularities and Limitations
For each CAN message a separate pretransmit function may be defined.

8.5.2.4
UserConfirmation
UserConfirmation
Prototype
Single Receive Channel
void UserConfirmation( CanTransmitHandle txObject )
Multiple Receive Channel
Parameter
txObject
Handle of the transmit object
Return code
-
-
Functional Description
User specific function which is called in the scope of the CAN transmit interrupt routine or the
CanTxTask() after the message has been sent on the CAN bus successfully
Particularities and Limitations
For each CAN message a separate confirmation function may be defined.

©2010, Vector Informatik GmbH
Version: 3.01.01
106 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.3  Callback Functions
Callback functions are called by the CAN Driver on certain events and have to be provided
by the Application. In contrast to the user specific functions in the section before the
callback functions are not message related but only event related. Their name can also be
reconfigured.
8.5.3.1  ApplCanBusOff
ApplCanBusOff
Prototype
Single Receive Channel
void ApplCanBusOff ( void )
Multiple Receive Channel
void ApplCanBusOff ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
This callback function is called if the CAN Controller enters BusOff state. The function is called in the
error interrupt, CanTask() or CanErrorTask().
Particularities and Limitations
If no Network Management is used which provides a BusOff error handling, the Application has to do
the subsequent error handling (usually the re-initialization of the CAN Controller) by the CAN Driver
service function CanResetBusOffStart() and CanResetBusOffEnd() itself.

8.5.3.2
ApplCanWakeUp
ApplCanWakeUp
Prototype
Single Receive Channel
void ApplCanWakeUp ( void )
Multiple Receive Channel
void ApplCanWakeUp ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX  (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
This callback function is called if a wake-up condition on the CAN bus is detected during sleep mode
of the CAN Controller. The function is called in the wakeup interrupt, in the CanTask() or in the
CanWakeupTask().
Particularities and Limitations
©2010, Vector Informatik GmbH
Version: 3.01.01
107 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

  If the CAN Controller was put into sleep mode by calling the service function CanSleep(), and
afterwards there is a dominant level at the receive input of the CAN Controller, CAN Controller
generates a wake-up interrupt. The CAN Driver calls the callback function ApplCanWakeUp() to
handle further wake-up call activities, e.g. starting the Network Management.
  The Application must assure that the CAN transmit path is restored to its normal operating state,
typically by the activation of the bus transceiver.
  This wake-up functionality is not supported by all CAN Controllers. If there is no power-down mode
of the CAN Controller or if the microprocessor cannot detect an external wake-up condition by the
CAN bus, this callback function will never be called.

8.5.3.3
ApplCanOverrun
ApplCanOverrun
Prototype
Single Receive Channel
void ApplCanOverrun ( void )
Multiple Receive Channel
void ApplCanOverrun ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX  (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
This callback function is called if an overrun in a Basic CAN receive object was detected. It indicates a
possible loss of receive data. The function is called in the error interrupt, in the receive interrupt, in the
CanTask(), in the CanRxTask(), or in the CanErrorTask().
Particularities and Limitations
The overrun is completely handled by the CAN Driver. This callback function only notifies the
Application about such a condition.

8.5.3.4
ApplCanFullCanOverrun
ApplCanFullCanOverrun
Prototype
Single Receive Channel
void ApplCanFullCanOverrun ( void )
Multiple Receive Channel
void ApplCanFullCanOverrun ( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX  (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
This callback function is called if an overrun of a Full CAN receive object was detected. It indicates a
possible loss of receive data. The function is called in the error interrupt, in the receive interrupt, in the
CanTask(), in the CanRxTask() or in the CanErrorTask().
©2010, Vector Informatik GmbH
Version: 3.01.01
108 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Particularities and Limitations
  The overrun is completely handled by the CAN Driver. This callback function only notifies the
Application about an overrun.

8.5.3.5
ApplCanMsgReceived
ApplCanMsgReceived
Prototype
Single Receive Channel
vuint8 ApplCanMsgReceived( CanRxInfoStructPtr rxStruct )
Multiple Receive Channel
Parameter
rxStruct
Pointer to receive information structure
Return code
kCanCopyData
Receive processing will be continued
kCanNoCopyData
Receive processing will be terminated
Functional Description
This callback function is called on every reception of a CAN message when the hardware acceptance
filter is passed. The function is called in the receive interrupt, in the CanTask() or in the
CanRxTask().
Particularities and Limitations
  The callback function may be used for gateway functionality or any other purpose.
  There are preprocessor macros available to read the CAN identifier, the Data Length Code and the
data in the CAN Controller receive register.

8.5.3.6
ApplCanRangePrecopy
ApplCanRangePrecopy
Prototype
Single Receive Channel
vuint8 ApplCanRangePrecopy( CanRxInfoStructPtr rxStruct)
Multiple Receive Channel
Parameter
rxStruct
Pointer to the receive structure
Return code
kCanCopyData
The CAN receive interrupt routine is continued with verifying a match to
the next range and ID search.
kCanNoCopyData
The CAN receive interrupt routine is terminated immediately after the
CAN Controller is serviced
Functional Description
©2010, Vector Informatik GmbH
Version: 3.01.01
109 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

This precopy function is not called on a specific message CAN identifier but on a complete CAN
identifier range. The function is called in the receive interrupt, in the CanTask(), in the
CanRxTask() or in CanHandleRxMsg(). The return code is not taken into account, if the range is
handled via the RX Queue. In this case, the handling of the received message will be terminated after
calling the range specific precopy function.
The name of this function is only a placeholder. The name could be set in the generation tool.
Up to four ranges with individual precopy functions can be specified per CAN channel.
Particularities and Limitations
  Ranges are normally used for Network Management or Transport Protocol services only
  In case a range configured to be handled via the Rx Queue, the return code of this function is
ignored.

8.5.3.7
ApplCanAddCanInterruptDisable
ApplCanAddCanInterruptDisable
Prototype
Single Receive Channel
void ApplCanAddCanInterruptDisable ( CanChannelHandle
Multiple Receive Channel
channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
In case of Single Receive Channel channel is always 0.
Return code
-
-
Functional Description
Disabling of additional CAN interrupts (like separately implemented Wake-Up interrupts and Polling
Tasks) can be added to the standard mechanism of the CAN by this callback function. The function is
called on interrupt and task level.
Particularities and Limitations
  ApplCanAddCanInterruptDisable() is only called if configured

8.5.3.8
ApplCanAddCanInterruptRestore
ApplCanAddCanInterruptRestore
Prototype
Single Receive Channel
void ApplCanAddCanInterruptRestore ( CanChannelHandle
Multiple Receive Channel
channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
In case of Single Receive Channel channel is always 0.
Return code
-
-
Functional Description
©2010, Vector Informatik GmbH
Version: 3.01.01
110 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Complementary callback function for ApplCanAddCanInterruptDisable().The function is called
on interrupt and task level.
Particularities and Limitations
  ApplCanAddCanInterruptRestore() is only called if configured.

8.5.3.9
ApplCanFatalError
ApplCanFatalError
Prototype
Single Receive Channel
void ApplCanFatalError ( vuint8 errorNumber )
Multiple Receive Channel
void ApplCanFatalError ( CanChannelHandle channel, vuint8
errorNumber )
Parameter
errorNumber
Error identification: There is a predefined list with supported assertion
checks for each CAN Driver. All the function parameters starting with
kError.... Please refer to chapter Assertions and the CAN Controller
Specific documentation TechnicalReference_CAN_<hardware>.pdf
[#hw_assert] for details.
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
If assertions are configured, the callback function ApplCanFatalError(..) is called in case of
invalid user conditions (Application interface, reentrance), inconsistent generated data, hardware
errors or internal errors (queue). An error number is passed by the parameter. The function is called on
interrupt and task level.
Particularities and Limitations
  This callback function does not have to return to the CAN Driver.

8.5.3.10  ApplCanMsgNotMatched
ApplCanMsgNotMatched
Prototype
Single Receive Channel
void ApplCanMsgNotMatched ( CanRxInfoStructPtr rxStruct )
Multiple Receive Channel
Parameter
rxStruct
Pointer to the receive structure
Return code
-
-
Functional Description
This callback function is called if a CAN message passes the hardware acceptance filter, but not the
software filter (inclusive the identifier specific predefined ranges). The function is called in the receive
interrupt, in the CanTask() or in the CanRxTask().
©2010, Vector Informatik GmbH
Version: 3.01.01
111 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Particularities and Limitations

8.5.3.11  ApplCanInit
ApplCanInit
Prototype
Single Receive Channel
void ApplCanInit( CanObjectHandle logTxHwObjectFirstUsed,
       CanObjectHandle logTxHwObjectFirstUnused)
Multiple Receive Channel
void ApplCanInit( CanChannelObject channel,
       CanObjectHandle logTxHwObjectFirstUsed,
       CanObjectHandle logTxHwObjectFirstUnused)
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX  (with X = 0 ... Number of generated channel index)
logTxHwObjectFirstUsed
Handle of the first CAN hardware transmit object of the current channel.
logTxHwObjectFirstUnused Handle of the first unused CAN hardware transmit object of the current
channel.
example:
for ( i = logTxHwObjectFirstUsed; i <
logTxHwObjectFirstUnused; i++)
{
/* loop over all used hardware transmit buffer of
the current
channel */
}
Return code
-
-
Functional Description
This callback function is called in CanInit() for general purposes. In CanInit() transmit requests in
the CAN Controller are canceled. This means the corresponding confirmation notification will never
occur. User defined actions started in ApplCanTxObjStart() have to be stopped in
ApplCanInit().The function is called on interrupt and task level.
Particularities and Limitations
This callback is active only if ‘Tx observe’ functionality is activated.

©2010, Vector Informatik GmbH
Version: 3.01.01
112 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.3.12 ApplCanTxObjStart
ApplCanTxObjStart
Prototype
Single Receive Channel
void ApplCanTxObjStart( CanObjectHandle logTxHwObject)
Multiple Receive Channel
void ApplCanTxObjStart( CanChannelHandle channel,
CanObjectHandle logTxHwObject)
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
logTxHwObject
Handle of the CAN buffer transmit object. For indexed drivers this is a
unique number over all CAN channels.
Return code
-
-
Functional Description
This callback function is called every time, a transmit request is initiated in the CAN Controller. This is
done in the service CanTransmit(..).The function is called in the transmit interrupt, in the
CanTask() or in the CanTxTask(), if the transmit queue is enabled.
Particularities and Limitations
This callback is active only if ‘Tx observe’ functionality is activated.

8.5.3.13 ApplCanTxObjConfirmed
ApplCanTxObjConfirmed
Prototype
Single Receive Channel
void ApplCanTxObjConfirmed( CanObjectHandle logTxHwObject)
Multiple Receive Channel
void ApplCanTxObjConfirmed (CanChannelHandle channel,
CanObjectHandle logTxHwObject)
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
logTxHwObject
Handle of the CAN buffer transmit object. For indexed drivers this is a
unique number over all CAN channels.
Return code
-
-
Functional Description
This callback function is called every time, a successful transmission is confirmed by the CAN
Controller in the scope of a transmit interrupt, in the CanTask() or in the CanTxTask().
Particularities and Limitations
This callback is active only if ‘Tx observe’ functionality is activated.

©2010, Vector Informatik GmbH
Version: 3.01.01
113 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.3.14  ApplCanTimerStart
ApplCanTimerStart
Prototype
Single Receive Channel
void ApplCanTimerStart(vuint8 timerIdentification)
Multiple Receive Channel
void ApplCanTimerStart(CanChannelObject channel, vuint8
timerIdentification)
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
timerIdentification
Identifier for the hardware dependent loop timer
Return code
-
-
Functional Description
This callback function is called before a CAN Controller dependent loop is started.
Particularities and Limitations

8.5.3.15  ApplCanTimerLoop
ApplCanTimerLoop
Prototype
Single Receive Channel
vuint8 ApplCanTimerLoop(vuint8 timerIdentification)
Multiple Receive Channel
vuint8 ApplCanTimerLoop(CanChannelObject channel, vuint8
timerIdentification)
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
timerIdentification
Identifier for the hardware dependent loop timer
Return code
FALSE (equal to 0)
Exit loop, even if hardware is not correct
TRUE (not equal to 0)
Continue with waiting for hardware condition
Functional Description
This callback function is called once in every loop cycle, i.e. multiple times for a specific condition.
Particularities and Limitations

©2010, Vector Informatik GmbH
Version: 3.01.01
114 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.3.16  ApplCanTimerEnd
ApplCanTimerEnd
Prototype
Single Receive Channel
void ApplCanTimerEnd(vuint8 timerIdentification)
Multiple Receive Channel
void ApplCanTimerEnd(CanChannelObject channel, vuint8
timerIdentification)
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
timerIdentification
Identifier for the hardware dependent loop timer
Return code
-
-
Functional Description
This callback function is called after a hardware dependent loop is finished, due to return value also of
ApplCanTimerLoop or hardware condition met.
Particularities and Limitations

8.5.3.17  ApplCanGenericPrecopy
ApplCanGenericPrecopy
Prototype
Single Receive Channel
vuint8 ApplCanGenericPrecopy(CanRxInfoStructPtr rxStruct)
Multiple Receive Channel
Parameter
rxStruct
Pointer to the receive structure
Return code
kCanCopyData
The UserPrecopy function will be called and the Received data will be
copied using the CAN Driver’s internal copy mechanism.
kCanNoCopyData
CAN Driver doesn’t copy data and doesn’t perform indication
Functional Description
This precopy function is common to all receive messages. It will be called immediately after the DLC-
check. The call of the UserPrecopy functions or copy of data are influenced by
ApplCanGenericPrecopy(). The function is called in the receive interrupt, in the CanTask() or in
the CanRxTask().
Particularities and Limitations

8.5.3.18  ApplCanPreWakeup
ApplCanPreWakeup
Prototype
©2010, Vector Informatik GmbH
Version: 3.01.01
115 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Single Receive Channel
void ApplCanPreWakeUp( void )
Multiple Receive Channel
void ApplCanPreWakeUp(CanChannelHandle channel)
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
Is called just after the activation of the wakeup interrupt.
Particularities and Limitations

8.5.3.19 ApplCanTxConfirmation
ApplCanTxConfirmation
Prototype
Single Receive Channel
void ApplCanTxConfirmation( CanTxInfoStructPtr txStruct)
Multiple Receive Channel
Parameter
txStruct
Pointer to transmit structure

typedef struct
{
CanChannelHandle Channel;
CanTransmitHandle Handle;
} tCanTxConfInfoStruct;

typedef tCanTxConfInfoStruct
*CanTxInfoStructPtr;
Handle:
- 0 ... (kCanNumberOfTxMessages-1): the handle of the Tx message.
- kCanBufferMsgTransmit, in case the message was sent via
CanCancelMsgTransmit().
- ((CanTransmitHandle)0xFFFFFFFEU)
in case the message was cancel by CanCanTransmit() or
CanCancelMsgTransmit() but sent on the bus
Return code
-
-
Functional Description
This confirmation function is common to all transmit messages. It will be called after the successful
transmission. The function is called in the transmit interrupt, in the CanTask() or in the
CanTxTask().
Particularities and Limitations

©2010, Vector Informatik GmbH
Version: 3.01.01
116 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.3.20 ApplCanMsgDlcFailed
ApplCanMsgDlcFailed
Prototype
Single Receive Channel
void ApplCanMsgDlcFailed( CanRxInfoStructPtr rxStruct )
Multiple Receive Channel
Parameter
rxStruct
Pointer to the receive structure
Return code
-
-
Functional Description
This callback function is called, if the DLC check fails. To activate this callback function the switch
C_ENABLE_DLC_FAILED_FCT has to be set in a user configuration file. The function is called in the
receive interrupt, in the CanTask() or in the CanRxTask().
Particularities and Limitations
It depends on the OEM if ApplCanMsgDlcFailed() is available.

8.5.3.21 ApplCanCancelNotification
ApplCanCancelNotification
Prototype
Single Receive Channel
void ApplCanCancelNotification(CanTransmitHandle txHandle)
Multiple Receive Channel
Parameter
txHandle
Handle of cancelled transmit object
Return code
-
-
Functional Description
This function will be called if a transmit message is deleted (CanCancelTransmit, CanOffline or
CanInit). This function could be called in Interrupt or Task context.
Particularities and Limitations
ApplCanCancelNotification() is only called if configured.

©2010, Vector Informatik GmbH
Version: 3.01.01
117 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

8.5.3.22  ApplCanOnline
ApplCanOnline
Prototype
Single Receive Channel
void ApplCanOnline(CanChannelHandle channel)
Multiple Receive Channel
Parameter
channel
CAN Channel on which the CAN driver was switched to online mode.
Return code
-
-
Functional Description
This callback function indicates that the CAN driver is switched to online mode. This function is called
by the CAN Driver if the mode change is initiated via CanOnline().
Particularities and Limitations
Call context: This function is called within CanOnline(). This service function is only allowed to be
called on task level.

8.5.3.23  ApplCanOffline
ApplCanOffline
Prototype
Single Receive Channel
void ApplCanOffline(CanChannelHandle channel)
Multiple Receive Channel
Parameter
channel
CAN Channel on which the CAN driver was switched to offline mode.
Return code
-
-
Functional Description
This callback function indicates that the CAN driver is switched to offline mode. This function is called
by the CAN Driver if the mode change is initiated via CanOffline().
Particularities and Limitations
Call context: This function is called within CanOffline(). This service function is allowed to be
called on task level or on interrupt level.

8.5.3.24  ApplCanMsgCondReceived
ApplCanMsgCondReceived
Prototype
Single Receive Channel
void ApplCanMsgCondReceived (CanRxInfoStructPtr rxStruct)
Multiple Receive Channel
Parameter
rxStruct
Pointer to the receive information structure
©2010, Vector Informatik GmbH
Version: 3.01.01
118 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Return code
-
-
Functional Description
This callback function is conditionally called on every reception of a CAN message when the hardware
acceptance filter is passed.
There are preprocessor macros available to read the CAN identifier, the Data Length Code and the
data in the CAN Controller receive register.
Particularities and Limitations
Call context: The function is called in the receive interrupt, in the CanTask() or in the
CanRxTask().

8.5.3.25  ApplCanMemCheckFailed
ApplCanMemCheckFailed
Prototype
Single Receive Channel
vuint8 ApplCanMemCheckFailed ( void )
Multiple Receive Channel
vuint8 ApplCanMemCheckFailed ( CanChannelHandle channel )
Parameter
Channel
Handle of the CAN channel on which the check failed. The generated
macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
kCanEnableCommunication  Allow communication.
kCanDisableCommunication Disable communication, no reception and no transmission is performed.
Functional Description
This callback function is called if the CAN driver has found at least one corrupt memory bit within the
CAN mailboxes. The application can decide if the CAN driver allows further communication by means
of the return value.
Particularities and Limitations
Call context: This function is called on task level or within the busoff interrupt.

8.5.3.26  ApplCanCorruptMailbox
ApplCanCorruptMailbox
Prototype
Single Receive Channel
void ApplCanCorruptMailbox ( CanObjectHandle hwObjHandle )
Multiple Receive Channel
void ApplCanCorruptMailbox ( CanChannelHandle channel,
CanObjectHandle hwObjHandle )
Parameter
hwObjHandle
The index of the corrupt mailbox.
channel
Handle of the CAN channel on which the corrupt mailbox is located. The
generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
©2010, Vector Informatik GmbH
Version: 3.01.01
119 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Return code
-
-
Functional Description
This callback function is called if the CAN driver has found a corrupt mailbox.
Particularities and Limitations
Call context: This function is called on task level or within the busoff interrupt.

©2010, Vector Informatik GmbH
Version: 3.01.01
120 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

9  Description of the API (High End extension)
9.1  Functions
9.1.1  Service Functions
9.1.1.1  CanTxObjTask
CanTxObjTask
Prototype
Single Receive Channel
void CanTxObjTask ( CanObjectHandle txObjHandle )
Multiple Receive Channel
void CanTxObjTask ( CanChannelHandle canHwChannel,
CanObjectHandle txObjHandle )
Parameter
canHwChannel
Handle of a CAN Hardware channel. The generated macros should be
used:
Normal Tx Object:
C_TX_NORMAL_<channel>_HW_CHANNEL (with <channel> = 0 ... Number
of logical channel)
Full CAN Tx Object:
<message name>_HW_CHANNEL (with <message name> = Name of the
Message with pre and postfixes generated in “can_par.h”t)
Low Level Tx Object:
C_TX_LL_<channel>_HW_CHANNEL (with <channel> = 0 ... Number of logical
channel)
txObjHandle
Handle of a Tx mailbox. The generated macros should be used:
Normal Tx Object:
C_TX_NORMAL_<channel>_HW_OBJ (with <channel> = 0 ... Number of
logical channel)
Full CAN Tx Object:
<message name>_HW_OBJ (with <message name> = Name of the Message with
pre and postfixes generated in “can_par.h”)
Low Level Tx Object:
C_TX_LL_<channel>_HW_OBJ (with <channel> = 0 ... Number of logical
channel)
Return code
-
-
Functional Description
The service function CanTxObjTask() does polling of specified transmit hardware objects in the
CAN controller. Confirmation functions will be called and confirmation flags will be set. If the transmit
queue is configured, this service function additionally transmits the queued messages.
Particularities and Limitations
  CanTxObjTask() is available, if the individual polling mode and at least one mailbox is configured
for polling.

©2010, Vector Informatik GmbH
Version: 3.01.01
121 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

9.1.1.2  CanRxFullCANObjTask
CanRxFullCANObjTask
Prototype
Single Receive Channel
void CanRxFullCANObjTask (CanObjectHandle rxObjHandle )
Multiple Receive Channel
void CanRxFullCANObjTask ( CanChannelHandle canHwChannel,
CanObjectHandle rxObjHandle )
Parameter
canHwChannel
Handle of a CAN Hardware channel. The generated macros should be
used:
<message name>_HW_ CHANNEL (with <message name> = Name of the
Message with pre and postfixes generated in “can_par.h”)
rxObjHandle
Handle of an Rx mailbox. The generated macros should be used:
<message name>_HW_OBJ (with <message name> = Name of the Message
with pre and postfixes generated in “can_par.h”t)
Return code
-
-
Functional Description
The service function CanRxFullCANObjTask() does polling of specified Full CAN receive objects
according to the configured objects in polling mode.
Particularities and Limitations
  CanRxFullCANObjTask() must not run on higher priority than other CAN functions.
  CanRxFullCANObjTask() is available, if the individual polling mode and at least one mailbox is
configured for polling.

9.1.1.3
CanRxBasicCANObjTask
CanRxBasicCANObjTask
Prototype
Single Receive Channel
void CanRxBasicCANObjTask ( void )
Multiple Receive Channel
void CanRxBasicCANObjTask (CanChannelHandle canHwChannel,
CanObjectHandle rxObjHandle )
Parameter
canHwChannel
Handle of a CAN Hardware channel. The generated macros should be
used:
C_BASIC<number_of_the_BasicCAN>_<channel>HW_CHANNEL
(with <number_of_the_BasicCAN>= the logical number of the Basic CAN on this
channel
<channel> = 0 ... Number of logical channel)
txObjHandle
Handle of a Rx mailbox. The generated macros should be used:
C_BASIC<number_of_the_BasicCAN>_<channel>_HW_OBJ
(with
<number_of_the_BasicCAN>= the logical number of the Basic CAN on this channel
<channel> = 0 ... Number of logical channel)
Return code
-
-
Functional Description
©2010, Vector Informatik GmbH
Version: 3.01.01
122 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

The service function CanRxBasicCANObjTask() does polling of specified Basic CAN receive
objects according to the configured objects in polling mode.
Particularities and Limitations
  CanRxBasicCANObjTask() must not run on higher priority than other CAN functions.
  CanRxBasicCANObjTask() is available, if the individual polling mode and at least one mailbox is
configured for polling.

9.1.1.4
CanMsgTransmit
CanMsgTransmit
Prototype
Single Receive Channel
vuint8 CanMsgTransmit ( tCanMsgTransmitStruct *txData )
Multiple Receive Channel
vuint8 CanMsgTransmit ( CanChannelHandle channel,
tCanMsgObject *txData )
Parameter
*txData
Pointer to the structure with ID, DLC and data to send
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
kCanTxOk
if the message-buffer is free and the data could be copied to the CAN-
data-buffer or if passive mode (CanSetPassive()) is active.
kCanTxFailed
if offline mode is active, the CAN buffer is not free.
Functional Description
This function is called by the application. The function sends the message which is defined in the
txData (Id, DLC, Data) to the CAN-Bus which is defined in the channel.
Particularities and Limitations
  the contents of txData may not be changed while CanMsgTransmit() is running

9.1.1.5
CanCancelMsgTransmit
CanCancelMsgTransmit
Prototype
Single Receive Channel
void CanCancelMsgTransmit( void )
Multiple Receive Channel
void CanCancelMsgTransmit( CanChannelHandle channel )
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX  (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
The call of ApplCanMsgTransmitConf() is suppressed, if a message is already in the transmit
buffer of the CAN controller associated with CanMsgTransmit(). Dependent on the configuration
this function cancels a message in the CAN hardware.
©2010, Vector Informatik GmbH
Version: 3.01.01
123 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Particularities and Limitations
The function call of CanCancelTransmit() must not interrupt the transmit ISR,
CanMsgTransmit() or the CanTxTask().
Though a transmission is canceled it will be sent if the request has been already in the hardware
object. Only if activated and highly dependent on hardware and vehicle manufacturer the transmit
request which is initiated with CanMsgTransmit() can be deleted in the hardware transmit object,
too. The function CanCancelMsgTranmit() is only available if the confirmation
ApplCanMsgTransmitConf() is configured.

9.1.1.6
CanHandleRxMsg
CanHandleRxMsg
Prototype
Single Receive Channel
void CanHandleRxMsg ( void )
Multiple Receive Channel
Parameter
-
-
Return code
-
-
Functional Description
The service function CanHandleRxMsg() handles the received messages which are stored in the Rx
Queue. The standard mechanism (GenericPrecopy, UserPrecopy, copy of data, Indication Flag and
UserIndication) is started for each stored message.
Particularities and Limitations
This function is only allowed to be called on task level.

9.1.1.7
CanDeleteRxQueue
CanDeleteRxQueue
Prototype
Single Receive Channel
void CanDeleteRxQueue ( void )
Multiple Receive Channel
Parameter
-
-
Return code
-
-
Functional Description
The service function CanDeleteRxQueue() clears all pending messages in the Rx Queue.
Particularities and Limitations
This function is only allowed to be called on task level.

©2010, Vector Informatik GmbH
Version: 3.01.01
124 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

9.1.2 Callback Functions
9.1.2.1
ApplCanMsgTransmitConf
ApplCanMsgTransmitConf
Prototype
Single Receive Channel
void ApplCanMsgTransmitConf( void )
Multiple Receive Channel
void ApplCanMsgTransmitConf(CanChannelHandle channel)
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
This function will be called from the CAN Driver after sending the message. It is called directly in the
transmit Interrupt (Confirmation) from the CAN-Controller. On task level it is called in the CanTask()
or in the CanTxTask(). With this callback function it is possible to implement a queue-functionality.
Particularities and Limitations
ApplCanMsgTransmitConf() is only called if configured.

9.1.2.2
ApplCanMsgTransmitInit
ApplCanMsgTransmitInit
Prototype
Single Receive Channel
void ApplCanMsgTransmitInit( void )
Multiple Receive Channel
void ApplCanMsgTransmitInit(CanChannelHandle channel)
Parameter
channel
Handle of a CAN channel. The generated macros should be used:
kCanIndexX (with X = 0 ... Number of generated channel index)
Return code
-
-
Functional Description
This function will be called from the CAN Driver after a possible cancel of a transmit request in
CanInit().
Particularities and Limitations
ApplCanMsgTransmitInit() is only called if ApplCanMsgTransmitConf() is configured.

9.1.2.3
ApplCanMsgCancelNotification
ApplCanMsgCancelNotification
Prototype
Single Receive Channel
void ApplCanMsgCancelNotification( void )
©2010, Vector Informatik GmbH
Version: 3.01.01
125 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Multiple Receive Channel
void ApplCanMsgCancelNotification( CanChannelHandle channel
)
Parameter
Channel
CAN Channel on which the Tx Object was cancelled.
Return code
-
-
Functional Description
This function will be called if a transmit message is deleted (CanCancelMsgTransmit). It applies only
to Tx messages that have been transmitted via CanMsgTransmit. This function could be called in
Interrupt or Task context.
Particularities and Limitations
ApplCanMsgCancelNotification() is only called if configured.

9.1.2.4
ApplCanPreRxQueue
ApplCanPreRxQueue
Prototype
Single Receive Channel
vuint8 ApplCanPreRxQueue( CanRxInfoStructPtr rxStruct )
Multiple Receive Channel
Parameter
rxStruct
Pointer to receive information structure
Return code
kCanCopyData
The data of the received message will be stored in the Rx Queue.
kCanNoCopyData
The data of the received message are not stored in the Rx Queue. The
reception is handled within the receive interrupt.
Functional Description
This precopy function is called if a message is received which is a valid message in the receive
structures or has to be handled via a range (in case the use of the Rx Queue is configured for this
range ). The application can decide whether to handle the message via the Rx Queue or the standard
CAN Driver mechanism within the receive interrupt.
Particularities and Limitations
Call context: This function is called within the receive interrupt.

9.1.2.5
ApplCanRxQueueOverrun
ApplCanRxQueueOverrun
Prototype
Single Receive Channel
void ApplCanRxQueueOverrun( void )
Multiple Receive Channel
Parameter
-
-
Return code
-
-
©2010, Vector Informatik GmbH
Version: 3.01.01
126 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Functional Description
This callback function indicates an overrun of the Rx Queue. This function is called by the CAN Driver,
in case a new message has to be stored in the Rx Queue, but the Queue if full. This new message will
be lost.
Particularities and Limitations
Call context: This function is called within the receive interrupt.

©2010, Vector Informatik GmbH
Version: 3.01.01
127 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

10  Configuration (Standard and High End)
This chapter describes the common options for configuring (customizing) the CAN Driver.
CAN Controller dependent configuration is described in the CAN Controller specific
documentation TechnicalReference_CAN_<hardware>.pdf [#hw_conf]. The configuration
can be done by the Generation Tool automatically.
10.1  Network Database – Attribute Definition
Caution
Attribute names in CANgen are case sensitive and not evaluated, if the name case is
  incorrect.

Name
GenMsgMinAcceptLength
Description
The DLC check can be configured to verify the received DLC against the value
given by this attribute (Against minimum acceptance length). The value can be
smaller than the Application receive buffer of this message.
Value “-1” means the DLC of the received message will be compared to the
length of the Application receive buffer of this message.
Type Of Object
Message
Value Type
Integer
Default
-1
Minimum
-1
Maximum
8

10.2  Automatic Configuration by GENy
Using the Generation Tool GENy the configuration can be done by the tool. The
configuration options common to all CAN Drivers is described here. The CAN Controller
dependent options are described in the CAN Controller specific user manual. The following
dialog describes the CAN Driver common options. The configuration data is stored by the
tool in the file can_cfg.h for GENy.

©2010, Vector Informatik GmbH
Version: 3.01.01
128 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Figure 10-1 Configuration of the common CAN Driver options with GENy

Feature
Explanation
Common Driver Parameters
Online/Offline Callback
If CanOnline() or CanOffline() is called the Application is notified that
Functions
a certain CAN driver state was entered.
DLC check
The DLC check can be configured to “disabled”, comparison of received
DLC “against data length” or “against minimum acceptance length”.
“against data length” means the number of bytes necessary for the ECU
and is equal to the length of the application data buffer.
The minimum acceptance length can be configured message specific via
database or on the Rx message view.
If DLC check is used, received Data messages with smaller DLC than
expected for this ID are ignored.
Data Copy Mechanism
The Data Copy Mechanism can be configured to “copy number of
needed bytes” or “copy all received bytes”.
“copy number of needed bytes” means the CAN driver copies always the
number of bytes which is equal to the length of the application data
buffer.
“copy all received bytes” means if the number of received bytes is less
than the size of the application data buffer only the received bytes are
copied. Otherwise the number of bytes which is equal to the length of the
application data buffer will be copied.
RAM check
The CAN driver supports a RAM check of the CAN controller mailboxes.
Sleep / Wakeup
If this field is checked, the CAN controller can be switched to sleep
mode.
©2010, Vector Informatik GmbH
Version: 3.01.01
129 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Feature
Explanation
Cancel in Hardware
CanCancelTransmit() and CanCancelMsgTransmit() will delete a
pending request in the CAN controller hardware.
FullCAN Overrun
If checked an overrun in the receive FullCAN objects will be signaled to
Notification
the Application.
Receive Function
The receive function ApplCanMsgReceived() is called by the CAN
Driver on every reception of a CAN message after the hardware
acceptance filter is passed. Within this callback function the Application
may preprocess the received message in any way (ECU specific
dynamic filtering mechanisms, preprocessing of the messages, gateway
functionality...).
If the callback function ApplCanMsgReceived() returns kCanCopyData,
the CAN Driver continues to work on the message received.
If the callback function returns kCanNoCopyData, the CAN finishes
working on the message received.
The callback function has to be defined by the application.
Active / Passive State
If this field is checked, the CAN Driver's transmit path can be switched to
the "Passive" state. In this state no CAN messages are sent to the CAN
bus. The transmit request always returns with ”OK”.
This ”passive” state functionality may be used to localize errors in a CAN
bus: If there are errors in a CAN bus, and the errors disappear when a
particular node is switched to passive state, the scapegoat is found. The
Application must be switched to the passive state and back to active
state by an external tester.
If active/passive state is enabled, the CAN Driver is in active state after
initialization.
If this field is not selected, the corresponding service functions are
available but without any effect on the CAN Driver status.
Extended Status
This is the global checkbox for using hardware status information in the
CAN Driver service CanGetStatus() or not.
Transmit Queue
If this field is checked the CAN Driver is configured to use a transmit
queue.
If no transmit queue is used, the Application is responsible to restart a
transmit request if it wasn’t accepted by the CAN Driver. In the case of
using a transmit queue, a transmit request is almost accepted. But the
queue does only store the transmit request of a message. It doesn’t
store the data to be sent in any case. The CAN Driver inserts a transmit
request to the queue, if no hardware object is available when
CanTransmit() is called. On a transmit interrupt, this means a former
requested message is transmitted, the CAN Driver checks whether
transmit requests are stored in the queue. If so, these requests are
removed from the queue and the transmit request is executed. The
search algorithm in the queue is priority based, there is no FIFO
strategy. This means the identifier with the lowest number is removed
first from the queue.
Tx observation
This is the global switch for using the Tx observe functionality of the
CAN Driver or not.
©2010, Vector Informatik GmbH
Version: 3.01.01
130 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Feature
Explanation
Message-Not-Matched
This is the global switch for using the MsgNotMatched function of the
Function
CAN Driver or not.
Overrun Notification
If this field is checked the CAN Driver is configured to notify the
Application in case of an overrun.
The Application has to provide an Overrun callback function:
void ApplCanOverrun(void)  /* Overrun in the CAN Controller */
The overrun handling itself is done by the CAN Driver.
Hardware Loop Check
This is the global switch for using the hardware loop check of the CAN
Driver or not.
Partial Offline Mode
If the checkbox “Use PartOffline Functionality” is checked, the partial
offline mode is available.
Generic Pre-copy
This checkbox enables the use of the generic precopy function –
ApplCanGenericPrecopy(). This precopy function is common to all
receive messages. it will be called as soon as the receive handle is
determined.
CAN Copy from & to CAN  This checkbox enables the use of copy functions CopyFromCan() and
CopyToCan().
CAN cancel Notification
The application will be notified via ApplCanCancelNotification() if a
message is canceled and therefore confirmation will occur. This is valid
for messages which have been requested via CanTransmit().
CAN Interrupt Control
There are two call back functions for the application. Within
Callbacks
CanCanInterruptDisable() the function
ApplCanAddCanInterruptDisable() is called and within
CanCanInterruptRestore() the function
ApplCanAddCanInterruptRestore() is called.
These two functions have to be used to handle the wake-up interrupt if
the hardware treats this interrupt separately or if the Driver runs in
Polling Mode the polling tasks have to be disabled.
Common Confirmation
If this field is checked the common confirmation function of the CAN
Function
Driver is enabled.
Offline Modes
Name of Mode X
with X = 0..7.
If the partial Offline Mode is enabled the name of each send group can
be configured here. more...
Default Mapping
Message Class 0
All messages with don’t belong to an other class are assigned to this
class.
OfflineModeX
with X = 0..7.
The message class 0 can be assigned to certain Offline Modes (send
goups) by selecting the check box.
Message Class 1 (Appl)
All application messages are assigned to this message class.
OfflineModeX
with X = 0..7.
The message class 1 can be assigned to certain Offline Modes (send
goups) by selecting the check box.
©2010, Vector Informatik GmbH
Version: 3.01.01
131 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Feature
Explanation
Message Class 2 (NM)
All network mangement messages are assigned to this message class.
OfflineModeX
with X = 0..7.
The message class 2 can be assigned to certain Offline Modes (send
goups) by selecting the check box.
Message Class 3 (TP)
All transport layer messages are assigned to this message class.
OfflineModeX
with X = 0..7.
The message class 3 can be assigned to certain Offline Modes (send
goups) by selecting the check box.
Message Class 4 (Diag)
All diagnostic messages are assigned to this message class.
OfflineModeX
with X = 0..7.
The message class 4 can be assigned to certain Offline Modes (send
goups) by selecting the check box.
Message Class 5 (IL)
All interaction layer messages are assigned to this message class.
OfflineModeX
with X = 0..7.
The message class 5 can be assigned to certain Offline Modes (send
goups) by selecting the check box.
OSEK OS
Use OsekOS Interrupt Cat In case of using OSEK-OS the interrupt category of the CAN Driver
2
interrupts have to be defined. Normally category 1 is used. Instead of
this category 2 can be selected.
OSEK OS
If this field is checked the CAN Driver is configured to support OSEK-
OS. The kind of OSEK-OS depends on the specific microprocessor.
Polling
Polling type
The polling type can be switched between “None”, “Type specific” and
“individual”.
Individual: If enabled, each BasicCAN, Normal Tx, Low level Tx and
FullCAN can be selected to be polled individual
Rx Basic CAN Polling
Normally the CAN driver works interrupt driven. To use the reception via
Basic CAN objects in polling mode, check this field. This field is available
in “Type specific polling mode”.
Rx Full CAN Polling
Normally the CAN driver works interrupt driven. To use the reception via
Full CAN objects in polling mode, check this field. This field is available
in “Type specific polling mode”.
Tx Polling
Normally the CAN driver works interrupt driven. To use the transmission
in polling mode, check this field. This field is available in “Type specific
polling mode”.
Wakeup Polling
Normally the CAN driver works interrupt driven. To use the wake up
detection in polling mode, check this field.
CAN Status Polling
Normally the CAN driver works interrupt driven. To use the Status and
Error detection in polling mode, check this field.
Low Level Transmission
©2010, Vector Informatik GmbH
Version: 3.01.01
132 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Feature
Explanation
Cancel Notification
The application will be notified if a message is canceled and therefore
Function
confirmation will occur. This is valid if the transmission has been
requested via CanMsgTransmit().
Enable Low Level
If the checkbox “Use Low Level Message Transmit” is checked, the
Transmission
function CanMsgTransmit() can be used.
Confirmation Function
This checkbox is only available, if “use Low Level Message Transmit” is
active. The confirmation and init callback functions of low level transmit
functionality can be activated by this checkbox.
API
Symbolic Names for
If the database allows the assignment of value tables to individual
Signal Values
signals, this feature is selectable. If this functionality is enabled, symbolic
names for values are generated for all signals that have an associated
value table
Indexed Component
This switch determines whether the component should configure the
indexed or non-indexed version of the driver component.
General Settings
Security level
This is the define value to configure the security level. Valid values are 0,
10, 20 or 30. more...
User Config File
The CAN Driver configuration file (can_cfg.h) is generated. If the user
wants to overwrite this automatically generated configuration file, the
user is able to define the name of a user defined configuration file which
is included at the end of the generated file can_cfg.h. This means entries
in the user defined configuration file overwrite the entries in can_cfg.h.
Debug Suport
Assertions
There are different groups of assertions supported by the CAN Driver.
They can be selected depending of the development phase:
None: No debug functionality active.
User: User API is debugged. The CAN Driver service function
parameters are checked.
Hardware: The CAN Controller interface is checked. Depends on CAN
Controller.
Gen: The configuration data are checked.
Internal: CAN Driver internal checking.
Dynamic Tx Objects
ID
If the checkbox “ID” is checked, the IDs of the dynamic transmit objects
can be changed by the service function CanDynTxObjSetId() and/or by
the service function CanDynTxObjSetExtId(). The last mentioned
service function is only available if extended ID addressing is checked in
the Generation Tool.
DLC
If the checkbox “DLC” is checked, the DLC of the dynamic transmit
objects can be changed by the service function CanDynTxObjSetDlc.
Data Pointer
If the checkbox “Data Pointer” is checked, the data pointers of the
dynamic transmit objects can be changed by the service function
CanDynTxObjSetDataPtr().
©2010, Vector Informatik GmbH
Version: 3.01.01
133 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Feature
Explanation
Confirmation
If the checkbox “Confirmation” is checked, the confirmation function of
the dynamic transmit objects can be changed by the service function
CanDynTxObjSetConfirmationFct(). The occurrence of this switch is
CAN Controller dependent.
Pre-transmit
If the checkbox “Pre-transmit” is checked, the pretransmit function of the
dynamic transmit objects can be changed by the service function
CanDynTxObjSetPreTransmitFct().The occurrence of this switch is
CAN Controller dependent.
ID Search Algorithm
Search Algorithm
For a Basic CAN Controller or the Basic CAN object of a Full CAN
Controller the hardware acceptance filtering provided by the CAN
Controller is not sufficient. Therefore a software acceptance filtering has
to be supported by comparing the incoming message identifier with the
complete list of all relevant message identifier. Here could the way how
to search in the table of the receive messages be defined. The optimum
algorithm depends on the number of the received messages to search in
and their identifier structure. The supported search algorithms are
dependent of the CAN Driver and the hardware. Refer to the CAN
controller specific documenation
TechnicalReference_CAN_<hardware>.pdf [#hw_feature] for more
information.
  linear
  hash search
  index search
  table search
Additional Memory [Byes]  This shows the byte consumption when hash search is selected. It is
just for information.
Maximum Search Steps
This is only activated when hash search is selected. Enter here the
amount of maximum search steps that are necessary to find the received
message ID in the list of to be received messages. The little this value
the greater the additional memory bytes and the faster the receive ISR.
Rx Queue
Overrun Notification
The Application is informed, if the Rx Queue is full and a new message
should be copied into the Queue. The new message will be lost.
Enable Rx Queue
If the checkbox “Enable Rx Queue” is checked, the RX Queue is
enabled. Else the Rx Queue is disabled.
Pre Rx Queue Function
If the checkbox “Pre Rx Queue Function” is checked, a Callback function
is enabled where the application could decide what should happen with
the CAN Message which was received. The two possibilities are to store
the message in the queue, or to process the message in the interrupt.
Number of queued Rx
Specifies the depth of the queue ("Number of queued Rx messages").
Messages

©2010, Vector Informatik GmbH
Version: 3.01.01
134 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Figure 10-2 Channel Specific Configuration for GENy

Features
Explanation
Configuration Options
General Settings
Bus System Type
Each channel is configured for a specific type of bus
system. The bus system is always CAN for CAN Driver.
Manufacturer
Manufacturer with is specified in the database file for this
channel.
Common Driver Parameters
Multiple Basic CAN
Enable Multiple Basic
If checked, the number of Basic CAN objects can be
CAN
selected. The deselecting of this checkbox resets the
number of Basic CAN objects to the default.
Number Of BasicCAN
Enter number of needed Basic CAN objects. Each Basic
Objects
CAN object may consist of 2 hardware mailboxes. This
depends on the CAN controller.
Ranges / Range Precopy Functions
Range
Ranges are normally used for Network Management,
Transport Protocol and so on. There are in maximum 4
ranges configurable.
Mask
Acceptance mask of this identifier range.
Code
Acceptance code of this identifier range.
Precopy function
Specific precopy function for this range.
Extended IDs
The range can be specified to receive extended IDs. If not
selected, this range will receive standard IDs.
©2010, Vector Informatik GmbH
Version: 3.01.01
135 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Use Own Filter
If there are enough Basic CAN filters available, one Basic
CAN filter can be used exclusive for this range.
Use Rx Queue
All messages which are received by this range can be
configured to be handled via the Rx Queue. This is only
possible, if the feature Rx Queue is activated.
Dynamic Tx objects
Number of dynamic Tx
Maximum number of dynamic send objects which are
objects
available at run time.

Figure 10-3 Configuration of individual polling with GENy

Features
Explanation
Configuration Options
Enable Polling
If checked, the associated mailbox will be handled in
polling mode. This is only selectable, if the polling mode is
configured to individual polling.

©2010, Vector Informatik GmbH
Version: 3.01.01
136 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Figure 10-4 Configuration of a Tx message with GENy
Features
Explanation
Configuration Options
Message / Frame Properties
Generate
If unchecked, the generation of this message will be
suppressed.
Common Driver Parameters
Signal Access Macros
Signal access macros can be used by the application for
an easy access to signals specified within a message.
Offline Modes
<Part offline group>/<Mode X name>
Usage
Standard: configuration via default mapping
User Defined: the user can set or reset the “Real Value”
Real Value
It set, the message belongs to this group and the
transmission of this message will be disabled if this group
is switched offline.
Flags
Confirmation Flag
After successful transmission of a message the driver sets
the confirmation flag of the message.
Functions
Confirmation Function
After successful transmission of a message the driver call
the user defined confirmation function of the message. The
name of this function has to be specified in this field.
Pretransmit Function
The used defined pretransmit function can be called before
the transmission of a message is started. The name of this
function has to be specified in this field.
©2010, Vector Informatik GmbH
Version: 3.01.01
137 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Full CAN Tx
Tx FullCAN
A Tx message can be assigned to a Full CAN objects.

Figure 10-5 Configuration of an Rx message with GENy
Features
Explanation
Configuration Options
Message / Frame Properties
Generate
If unchecked, the generation of this message will be
suppressed.
Common Driver Parameters
Minimum Data Length

Signal Access Macros
Signal access macros can be used by the application for
an easy access to signals specified within a message.
Flags
Indication Flag
After successful reception of a message the driver sets the
indication flag of the message
Functions
Indication Function
The name of the used defined indication function can be
specified in this field.
Precopy Function
The name of the used defined precopy function can be
specified in this field.
Full CAN
Full CAN
An Rx message can be assigned to a Full CAN objects.
Lock Full CAN
If set, the assignment of a Rx message to a Full CAN
©2010, Vector Informatik GmbH
Version: 3.01.01
138 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

object cannot be changes by the filter optimization.
Hardware Channel
In case a receive message is configured to be ‘FullCAN’
and Common CAN is activated then the user can configure
this message to be received on the first (Channel A) or the
second (Channel B) CAN controller on this channel.

10.3 Automatic Configuration by CANgen
Using the Generation Tool CANgen the configuration can be done by the tool. The
configuration options common to all CAN Drivers is described here. The CAN Controller
dependent options are described in the CAN Controller specific user manual. The following
dialog describes the CAN Driver common options. The configuration data is stored by the
tool in the file can_cfg.h for CANgen.

Figure 10-6 CAN Driver configuration tab

©2010, Vector Informatik GmbH
Version: 3.01.01
139 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Feature
Explanation

Path of the CAN config file The CAN Driver configuration file (can_cfg.h) is generated. If the user
wants to overwrite this automatically generated configuration file, the
user is able to define the name of a user defined configuration file which
is included at the end of the generated file can_cfg.h. This means entries
in the user defined configuration file overwrite the entries in can_cfg.h.
Use Receive Function
The receive function ApplCanMsgReceived() is called by the CAN
(ApplCanMsgReceived)
Driver on every reception of a CAN message after the hardware
acceptance filter is passed. Within this callback function the Application
may preprocess the received message in any way (ECU specific
dynamic filtering mechanisms, preprocessing of the messages, gateway
functionality...).
If the callback function ApplCanMsgReceived() returns kCanCopyData,
the CAN Driver continues to work on the message received.
If the callback function returns kCanNoCopyData, the CAN finishes
working on the message received.
Support Active/Passive
If this field is checked, the CAN Driver's transmit path can be switched to
State
the "Passive" state. In this state no CAN messages are sent to the CAN
bus. The transmit request always returns with ”OK”.
This ”passive” state functionality may be used to localize errors in a CAN
bus: If there are errors in a CAN bus, and the errors disappear when a
particular node is switched to passive state, the scapegoat is found. The
Application must be switched to the passive state and back to active
state by an external tester.
If active/passive state is enabled, the CAN Driver is in active state after
initialization.
Use Transmit Queue
If this field is checked the CAN Driver is configured to use a transmit
queue.
If no transmit queue is used, the Application is responsible to restart a
transmit request if it wasn’t accepted by the CAN Driver. In the case of
using a transmit queue, a transmit request is almost accepted. But the
queue does only store the transmit request of a message. It doesn’t
store the data to be sent in any case. The CAN Driver inserts a transmit
request to the queue, if no hardware object is available when
CanTransmit() is called. On a transmit interrupt, this means a former
requested message is transmitted, the CAN Driver checks whether
transmit requests are stored in the queue. If so, these requests are
removed from the queue and the transmit request is executed. The
search algorithm in the queue is priority based, there is no FIFO
strategy. This means the identifier with the lowest number is removed
first from the queue.
Support for OSEK OS
If this field is checked the CAN Driver is configured to support OSEK-
OS. The kind of OSEK-OS depends on the specific microprocessor.
Use OsekOS Interrupt Cat In case of using OSEK-OS the interrupt category of the CAN Driver
2
interrupts have to be defined. Normally category 1 is used. Instead of
this category 2 can be selected.
©2010, Vector Informatik GmbH
Version: 3.01.01
140 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Feature
Explanation
Support Overrun
If this field is checked the CAN Driver is configured to notify the
Notification
Application in case of an overrun.
The Application has to provide an Overrun callback function:
void ApplCanOverrun(void)  /* Overrun in the CAN Controller */
The overrun handling itself is done by the CAN Driver:
Security Level
This is the define value to configure the security level. Valid values are
0,10, 20 or 30.
Extended Status
This is the global checkbox for using hardware status information in the
CAN Driver service CanGetStatus() or not.
Debug level
There are different Debug Levels supported by the CAN Driver:
None: No debug functionality active.
User: User API is debugged. The CAN Driver service function
parameters are checked.
Hardware: The CAN Controller interface is checked. Depends on CAN
Controller.
Gen: The configuration data are checked.
Internal: CAN Driver internal checking (consistency of transmit queue).
Extended IDs
This checkbox is available only if extended CAN identifiers are selected
in the channel configuration dialog. It has to be enabled if extended CAN
identifiers have to be received by the range specific acceptance filtering
and the appropriate precopy function has to be called. In such case no
standard identifiers can be received by any acceptance range.
Use Range X
This is the global switch to select identifier range specific precopy
functions. These ranges are normally used for Network Management,
Transport Protocol and so on. There are in maximum 4 ranges
configurable, where ‘X’ is the number of the specified range. If a range is
enabled, the following additional settings has to be done:
Range X mask
Acceptance code of the identifier range X.
Range X ID
Acceptance mask of the identifier range X.
Range X precopy function  Specific precopy function for range X.
Tx observe
This is the global switch for using the tx observe functionality of the CAN
Driver or not.
Use MsgNotMatched
This is the global switch for using the MsgNotMatched function of the
function
CAN Driver or not.
Hardware Loop Check
This is the global switch for using the hardware loop check of the CAN
Driver or not.
Number of dynamic tx
Maximum number of dynamic send objects which are available at run
objects
time.
Dynamic TxId
If the checkbox “DynamicTxId” is checked, the IDs of the dynamic
transmit objects can be changed by the service function
CanDynTxObjSetId() and/or by the service function
CanDynTxObjSetExtId(). The last mentioned service function is only
available if extended ID addressing is checked in the Generation Tool.
©2010, Vector Informatik GmbH
Version: 3.01.01
141 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Feature
Explanation
Dynamic TxDLC
If the checkbox “DynamicTxDLC” is checked, the DLCs of the dynamic
transmit objects can be changed by the service function
CanDynTxObjSetDlc().
Dynamic TxDataPtr
If the checkbox “DynamicTxDataPtr” is checked, the data pointers of the
dynamic transmit objects can be changed by the service function
CanDynTxObjSetDataPtr(). The occurrence of this switch is CAN
Controller dependent.
Dynamic TxConfirmation
If the checkbox “DynamicTxConfirmation” is checked, the confirmation
function of the dynamic transmit objects can be changed by the service
function CanDynTxObjSetConfirmationFct(). The occurrence of this
switch is CAN Controller dependent.
Dynamic TxPreTransmit
If the checkbox “DynamicTxPretransmit” is checked, the pretransmit
function of the dynamic transmit objects can be changed by the service
function CanDynTxObjSetPreTransmitFct().The occurrence of this
switch is CAN Controller dependent.
Use Low Level Message
If the checkbox “Use Low Level Message Transmit” is checked, the
Transmit
function CanMsgTransmit() can be used.
Use Low Level Message
This checkbox is only available, if “use Low Level Message Transmit” is
Transmit Confirmation
active. The confirmation and init callback functions of low level transmit
functionality can be activated by this checkbox.
Use PartOffline
If the checkbox “Use PartOffline Functionality” is checked, the partial
Functionality
offline mode is available.
Use Generic Precopy
This checkbox enables the use of the generic precopy function –
ApplCanGenericPrecopy(). This precopy function is common to all
receive messages. It will be called as soon as the receive handle is
determined.

The next figure shows the Configuration of the partial offline mode. Every transmit
message can be assigned to up to eight partial offline groups.
©2010, Vector Informatik GmbH
Version: 3.01.01
142 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

Figure 10-7 Configuration of Partial Offline Mode

Feature
Explanation
Edit part offline mode
this button can be used to change the names of the eight partial offline
names
groups

The following features cannot be configured by the Application. They are set automatically
depending on the used OEM:
  DLC check
  Data Copy Mechanism
  Cancel in Hardware

©2010, Vector Informatik GmbH
Version: 3.01.01
143 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

10.4  Manual configuration via user configuration file
This chapter describes additional configuration options for special features which can only
be configured via user configuration file.
In the following table you will find a list of configuration switches, used to control the
functional units of the CAN Driver:

Switch
Value / Range
Use of ...
C_xxx_APPLCANPREWAKEUP_FCT  ENABLE, DISABLE
Activate call of ApplCanPreWakeUp() if
an WakeUp Interrupt occurs.
C_xxx_NOTIFY_CORRUPT_MAILBOX ENABLE,
DISABLE  Activate call of ApplCanCorruptMailbox()
in case the CAN RAM Check fails for a
certain mailbox.

If the Generation Tool CANgen is used, some additional configurations can only be due via
user configuration file:

Switch
Value / Range
Use of ...
C_xxx_ONLINE_OFFLINE_CALLBACK ENABLE, DISABLE
Activate call of ApplCanOnline() and
_FCT
ApplCanOffline() if the associated CAN
driver state was entered.
C_xxx_INTCTRL_ADD_CAN_FCT ENABLE,
DISABLE
Activate call of
ApplCanAddCanInterruptDisable()
and
ApplCanAddCanInterruptRestore().
These two functions have to be used to
handle the wake-up interrupt if the
hardware treats this interrupt separately
or if the Driver runs in Polling Mode the
polling tasks have to be disabled.

©2010, Vector Informatik GmbH
Version: 3.01.01
144 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

11 Glossary
Abbreviations and
Expressions
Explanation
Acceptance filtering
Mechanism which decides whether each received protocol frame is
to be taken into account by the local Node or ignored.
API Application
Program
Interface.
Application Interface
An application interface is the prescribed method of a SW
component for using the available functionality.
Arbitration
Mechanism which guarantees that a simultaneous access made by
multiple stations results in a contention where one frame will
survive uncorrupted.
ASAP Arbeitskreis
zur
Standardisierung von Applikationssystemen.
Standardization of Application and Calibration system task force
BCD
Binary Coded Decimal
Buffer
A buffer in a memory area normally in the RAM. It is an area, the
application reserved for data storage
Bus
Defines what we call internal as channel or connection.
BusOff
A node is in the state bus off when it is switched off from the bus
due to a request of fault confinement entity. In the bus off state, a
node can neither send nor receive any frames. A node can start the
recovery from bus off state only upon a user request.A node is in
the state BusOff when it is switched off from the bus. In the state
BusOff a node can neither send nor receive any protocol frames.
Callback function
This is a function provided by an application. E.g. the CAN Driver
calls a callback function to allow the application to control some
action, to make decisions at runtime and to influence the work of
the Driver.
CAN
Controller Area Network protocol originally defined for use as a
communication network for control applications in vehicles.
CAN Controller
A hardware unit integrated into a micro controller (or as a separate
unit) handling the CAN protocol.
CAN Driver
The CAN driver encapsulates a specific CAN controller handling. It
consists of algorithms for HW initialization, CAN message
transmission and reception. The application interface supports both
event and polling notification and WR/RD access to the message
buffers.
Channel
A channel defines the assignment (1:1) between a physical
communication interface and a physical layer on which different
modules are connected to (either CAN or LIN). 1 channel consists
of 1..X network(s).
Configuration
The communication configuration adapts the communication stack
to the specific component requirements by means of the
Generation Tool.
Confirmation
A service primitive defined in the ISO/OSI Reference model (ISO
©2010, Vector Informatik GmbH
Version: 3.01.01
145 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

7498). With the service primitive 'confirmation' a service provider
informs a service user about the result of a preceding service
request of the service user. Notification by the CAN Driver on
asynchronous successful transmission of a CAN message.
Data consistency
Data consistency means that the content of a given application
message correlates unambiguously to the operation performed
onto the message by the application. This means that no
unforeseen sequence of operations may alter the content of a
message hence rendering a message inconsistent with respect to
its allowed and expected value.
DBC
CAN database format of the Vector company which is used by
Vector tools
DLC
Data Length CodeNumber of data bytes of a CAN message
ECU
Electronic Control Unit
Error
Error is a local problem which could be solved locally. If not, the
error will be given as an exception to the application. An error is not
the specification conform misbehavior of a system (e.g. a not
responded diagnostic request after three requests without
response is no error). Discrepancy between a computed, observed
or measured value or condition and the true, specified or
theoretically correct value or condition (IEC 61508-4).
FIFO
First In First Out
FILO
First In Last Out
Gateway
A gateway is designed to enable communication between different
bus systems, e.g. from CAN to LIN.
Generation Tool
See CANgen, DBKOMGen and GENy. The generation tool
configures the communication stack based on database attributes
(vehicle manufacturer), project settings (module supplier) and
license information (Vector).
HIS Hersteller-Initiative
Software
HW Hardware
ID
Identifier (e.g. Identifier of a CAN message)
Indication
A service primitive defined in the ISO/OSI Reference Model (ISO
7498). With the service primitive 'indication' a service provider
informs a service user about the occurrence of either an internal
event or a service request issued by another service user.
Notification of application in case of events in the Vector software
components, e.g. an asynchronous reception of a CAN message.
Interrupt
Processor-specific event which can interrupt the execution of a
current program section.
Interrupt level
Processing level provided for time-critical activities. To keep the
interrupt latency brief, only absolutely indispensable actions should
be effected in the Interrupt Service Routine, which ensures
reception of the interrupt and trigger its (post) processing within a
task. Other processing levels are: Operating System Level and
Task Level.
ISO
International Standardization Organization
©2010, Vector Informatik GmbH
Version: 3.01.01
146 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

ISR
Interrupt Service Routine
LIN
Local Interconnect Network
Manufacturer Vehicle
manufacturer
Message
A message is responsible for the logical transmission and reception
of information depending on the restrictions of the physical layer.
The definition of the message contents is part of the database
given by the vehicle manufacturer.
MISRA
Motor Industry Software Reliability Association
MRC
Multiple Receive Channel
Network
A network defines the assignment (1:N) between a logical
communication grouping and a physical layer on which different
modules are connected to (either CAN or LIN). 1 network consists
of 1 channel, Y networks consists of 1..Z channel(s). We say
network if we talk about more than 1 bus.
NM Network
Management
Node
A network topological entity. Nodes are connected by data links
forming the network. Each node is separately addressable on the
network.
OEM
Original Equipment Manufacturer
Offline
State of the data link layer. In the Offline state, no application
communication is possible. Only the network management is
allowed to communicate.
Online
(Normal) state of the data link layer. Application and Network
Management communication are possible.
OS Operating
System
OSEK
Name of the overall project: Abbreviation of the German term
"Offene Systeme und deren Schnittstellen fÃ¼r die Elektronik im
Kraftfahrzeug" - Open Systems and the Corresponding Interfaces
for Automotive Electronics.
Overrun
Overwriting data in a memory with limited capacity, e.g. Queued
message object
Platform
The sum of micro controller derivative, communication controller
implementation and compiler is called platform.
RAM Random
Access
Memory
Register
A register is a memory area in the controller, e.g. in the CAN
Controller. Distinguish Register from Buffer
RI Reference
Implementation
ROM Read-Only
Memory
Signal
A signal is responsible for the logical transmission and reception of
information depending on the restrictions of the physical layer. The
definition of the signal contents is part of the database given by the
vehicle manufacturer. Signals describe the significance of the
individual data segments within a message. Typically bits, bytes or
words are used for data segments but individual bit combinations
are also possible. In the CAN data base, each data segment is
assigned a symbolic name, a value range, a conversion formula
©2010, Vector Informatik GmbH
Version: 3.01.01
147 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

and a physical unit, as well as a list of receiving nodes.
SRC
Single Receive Channel
Status
A status describes the properties (parameters) of an entity. A state
is interpreted as an information, e.g. an error, by the entity which
uses a status, and is frequently determined by the history.
Task Level
Processing level where the actual application software, is
executed. Tasks are executed according to the priority assigned to
them, and to the selected scheduling policy. Other processing
levels are: Interrupt level and Operating System Level.
Transceiver
A transceiver adapts the physical layer to the communication
interface.
Vehicle Manufacturer
We use this instead of OEM
Watchdog
A monitoring entity.

©2010, Vector Informatik GmbH
Version: 3.01.01
148 / 149
based on template version 2.1

TechnicalReference Vector CAN Driver

12 Contact
Visit our website for more information on

> News
> Products
> Demo software
> Support
> Training data
> Addresses

www.vector-informatik.com
©2010, Vector Informatik GmbH
Version: 3.01.01
149 / 149
based on template version 2.1

Document Outline

6 - TechnicalReference_Rh850_Rscan

Vector CAN Driver

7 - TechnicalReference_Rh850_Rscan_ind

8 - TechnicalReference_Rh850_Rscans

Vector CAN Driver
Technical Reference

Renesas
RH850
RSCAN

Version 1.08.00

Authors
Torsten Kercher
Status
Released

Vector CAN Driver Technical Reference RH850 RSCAN

Document Information
History

Author
Date
Version  Remarks
Torsten Kercher  2013-05-27  1.00.00  Initial release (support F1L with GreenHills compiler)
Torsten Kercher  2013-07-18  1.01.00  Support R1L derivatives
Correct description of nested interrupt behavior
Torsten Kercher  2013-08-26  1.02.00  Support HighEnd features
Support WindRiver Diab compiler
Torsten Kercher  2013-10-16  1.03.00  Support R1M derivatives
Update referenced version of the R1x manual
Support external wakeup functionality
Update chapters 5, 6, 7.2.2
Torsten Kercher  2014-04-04  1.04.00  Support extended CAN RAM check
Support RSCAN RAM test
Support D1L, D1M, P1M derivatives
Update referenced version of the F1L manual
Torsten Kercher  2014-04-29  1.04.01  Update description of nested interrupt behavior
Torsten Kercher  2014-05-15  1.05.00  Support IAR compiler
Support F1H derivatives
Update expected loop durations in chapter 5
Torsten Kercher  2014-07-23  1.06.00  Support Renesas compiler
Support C1H, C1M, E1L, E1M derivatives
Update chapters 5, 9.4, 10.3
Update ref. versions of the F1L and F1H manuals
Torsten Kercher  2014-11-24  1.07.00  Support configuration of the used ‘CAN Interface’
Support F1M derivatives
Update chapters 5, 6, 7.2.9, 9.4, 10.3
Update ref. versions of the P1x and R1x manuals
Torsten Kercher  2015-08-19  1.08.00  Support F1K derivatives
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.

2015, Vector Informatik GmbH
Version: 1.08.00
2 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

1  Introduction
The concept of the CAN driver and the standardized interface between the CAN driver and
the  application  is  described  in  the  document  TechnicalReference_CANDriver.pdf.  The
CAN driver interface to the hardware is designed in a way that capabilities of the special
CAN chips can be utilized optimally. The interface to the application was made identical for
the  different  CAN  chips,  so  that  the  "higher"  layers  such  as  network  management,
transport protocols and especially the application would essentially be independent of the
particular CAN chip used.

This  document  describes  the  hardware  dependent  special  features  and  implementation
specifics of the Renesas RSCAN on the RH850 platform.
2015, Vector Informatik GmbH
Version: 1.08.00
5 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

2  Important References
The  following  table  summarizes  information  about  the  CAN  Driver.  It  gives  you  detailed
information  about  the  versions,  derivatives  and  compilers. As  very  important  information
the  documentations  of  the  hardware  manufacturers  are  listed. The  CAN  Driver  is  based
upon these documents in the given version.

Driver
Supported
Supported
Hardware Manufacturer Documents
Version
Version

  Compilers
Derivatives
3.15.xx,  GreenHills,
C1H
R01UH0414EJ0041, RH850/C1x,
Rev.0.41
RI 1.5
WindRiver Diab,  C1M
User’s Manual: Hardware
Feb 2014
Renesas,
D1L
R01UH0451EJ0041, RH850/D1L/D1M
Rev.0.41
IAR
D1M
Group, User’s Manual: Hardware
Jan 2014
E1L
R01UH0468JJ0040, RH850/E1L,
Rev.0.40
User’s Manual: Hardware
Dec 2013
E1M
R01UH0466JJ0040, RH850/E1M-S,
Rev.0.40
User’s Manual: Hardware
Dec 2013
F1H 1
R01UH0445EJ0011, RH850/F1H Group,  Rev.0.11
User’s Manual: Hardware
Apr 2014
F1K 1
R01UH0562EJ0050, RH850/F1K Group   Rev.0.50
User’s Manual: Hardware
Mar 2015
F1L
R01UH0390EJ0110, RH850/F1L Group,   Rev.1.10
User’s Manual: Hardware
Jun 2014
F1M
R01UH0518EJ0010, RH850/F1M Group,   Rev.0.10
User’s Manual: Hardware
Nov 2014
P1M
R01UH0436EJ0060, RH850/P1x Group,   Rev.0.60
User’s Manual: Hardware
Jul 2014
R1L
R01UH0411EJ0110, RH850/R1x Group,   Rev.1.10
R1M
User’s Manual: Hardware
Aug 2014

R01US0058EJ0020, RH850 Family,
Rev.0.20
User’s Manual: Software
Feb 2013
Table 2-1   Supported Hardware Overview

Driver Version: This is the current version of the CAN Driver. RI shows the version of the Reference
Implementation and therefore the functional scope of the CAN Driver.
Supported Compilers: List of compilers the CAN Driver is working with.
Supported Derivatives: List of derivatives the CAN Driver can be used on.
Hardware Manufacturer Documents: List of the documentation the CAN Driver is based on.
Version: Version of the documentation the CAN Driver is based on.


1 Only the first RSCAN unit (RSCAN0) is supported (physical channels CAN0-CAN5).
2015, Vector Informatik GmbH
Version: 1.08.00
6 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

3  Usage of Controller Features
3.1
[#hw_comObj] - Communication Objects
The generation tool supports a flexible allocation of message buffers:

Figure 3-1  Hardware Object Layout

Note
Figure  3-1  depicts  the  maximum  capacities  of  one  RSCAN  unit  -  the  actual  layout
  depends  on  the  used  derivative.  Refer  to  the  hardware  manual  to  get  the  number  of
supported physical channels to determine which Tx buffers are available. The amount
of  supported  Rx  buffers  (nRXMBmax)  equals  the  number  of  supported  physical
channels of the used RSCAN unit * 16.

2015, Vector Informatik GmbH
Version: 1.08.00
7 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

Obj
Hw object  Log object  No. of
Comment
number
type
type
objects
These objects are used to receive
specific CAN messages. The user
defines statically (Generation Tool) that
a CAN message should be received in a
FullCAN message object. The

Generation Tool distributes the
0
messages to the FullCAN objects. Up to
0

Receive
Receive
-
nRxMBmax receive FullCAN objects can
-
buffer
FullCAN
nRXMBmax be configured per channel, but the sum
(nRXFC

-1)

over all receive FullCAN objects on all
= nRXFC
channels must not exceed nRxMBmax.
The receive buffers for the FullCAN
objects of all channels (sorted
ascending by the physical channel
index) are allocated continuously
starting from index 0.
These objects are not used. It depends
on the configuration of receive FullCAN
nRXFC
0
Receive

objects and nRxMBmax how many
-
Unused
buffer

-
receive buffers are not used. These
127

128
objects will not be configured, so they
don’t consume shared hardware buffers.
All other CAN messages (Application,
Diagnostics, Network Management) are
received via the BasicCAN objects.
Each object consists of one receive
FIFO buffer with a configurable amount
of acceptance filters and an individually
configurable FIFO depth (number of
allocated shared buffers). In general
0
there is one BasicCAN object per
128

-
channel, but by using the Multiple
-
Receive
Receive
8
BasicCAN feature the amount of used
(128 +

FIFO buffer  BasicCAN
BasicCAN objects can be configured.
nRXBC

-1)
= nRXBC
Up to 8 receive BasicCAN objects can
be configured per channel, but the sum
over all receive BasicCAN objects on all
channels must not exceed 8. The
receive FIFO buffers for the BasicCAN
objects of all channels (sorted
ascending by the physical channel
index) are allocated continuously
starting from index 128.
These objects are not used. It depends
on the configuration of receive
128 + nRXBC
0
Receive

BasicCAN objects how many receive
-
Unused
FIFO buffer

-
FIFO buffers are not used. These
135

8
objects will not be configured, so they
don’t consume shared hardware buffers.
2015, Vector Informatik GmbH
Version: 1.08.00
8 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

Obj
Hw object  Log object  No. of
Comment
number
type
type
objects
The usage of Transmit / Receive FIFO
136
Transmit /
buffers is not supported by this driver.
-
Receive
Unused
24
These objects are always unused and
159
FIFO buffer
will not be configured, so they don’t
consume shared hardware buffers.
This object is used by CanTransmit()
to send several messages on the logical
Transmit
Transmit
1
160 + (n*16)

channel that is mapped to physical

buffer
Normal
per channel  channel n. If the transmit message
object is busy, the transmit request is
stored in a software queue.
This object is used by
0 or 1
Transmit
CanMsgTransmit() to send its
Low Level  per channel
161 + (n*16)

buffer
messages on the logical channel that is

Transmit

= nTXLL
mapped to physical channel n if the Low

Level transmit functionality is used.
These objects are used by
CanTransmit() to send a certain
message on the logical channel that is

161 + (n*16)
0
mapped to physical channel n. The user

+ nTXLL
defines statically (Generation Tool)
-
-
Transmit
Transmit
15
which CAN messages are located in

161 + (n*16) +  buffer
FullCAN
such Tx FullCAN objects. The
nTXLL +
per channel  Generation Tool distributes the
nTXFC(n)

-1
messages to the objects. Up to 15
= nTXFC(n)   transmit FullCAN objects can be
assigned per channel (up to 14 if the
Low Level transmit functionality is used).
161 + (n*16) +
These objects are not used. It depends
nTXLL +
0
on the configuration of transmit objects
nTXFC(n)
Transmit
how many transmit buffer objects are
Unused
-

-
buffer
15
not used. Additionally all transmit buffers
161 + (n*16)
per channel  of not supported or unused physical
+14
channels n are unused.
Table 3-1   Hardware Object Layout

nRxMBmax  Amount of RX buffers that is supported by the used derivative (see note above)
nRxFC
Number of used Rx FullCAN objects over all channels
nRxBC
Number of used Rx BasicCAN objects over all channels
n
Index of the physical channel
nTXLL
Number of Low Level transmit objects per channel (0 or 1)
nTXFC(n)
Number of used Tx FullCAN objects on the channel that is mapped to the physical channel n

2015, Vector Informatik GmbH
Version: 1.08.00
9 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

Caution
The number of available transmit buffer objects per physical channel is constant. The
  receive buffers and FIFOs are shared over all channels and the availability per channel
is  restricted  as  explained  in  table  3-1.  Furthermore  the  internal  buffers  for  all  receive
objects  are  allocated  out  of  a common  buffer  pool  with  size  of  (number  of  supported
physical  channels  of  the  used  RSCAN  unit  *  64).  This  has  to  be  considered  when
configuring the number of the Rx FullCAN objects and the number and individual FIFO
depths of the Rx BasicCAN objects (refer to section 11.1.3 for further information and
details on how to configure the hardware objects).

3.2
Acceptance Filters
The hardware acceptance filters of the receive BasicCAN objects must allow reception of
all  messages  that  are  not  received  in  FullCAN  message  objects  and  additionally  all
messages  that  fit  in  a  configured  range  (e.g.  for  Network  Management,  Transport
Protocol).  The  generation  tool  offers  assistance  for  configuration.  The  number  of  used
filters  is  also  configurable  to  allow  efficient  hardware  filtering  to  minimize  unnecessary
CPU load.

Caution
The hardware supports a pool of acceptance filters with size of (number of supported
  physical channels of the used RSCAN unit * 64) that are used for Rx BasicCAN as well
as Rx FullCAN objects. This has to be considered when configuring the number of Rx
FullCAN objects and the number of filters per Rx BasicCAN object. See section 11.1.3
for further information and details on the configuration.

2015, Vector Informatik GmbH
Version: 1.08.00
10 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

4   [#hw_sleep] - SleepMode and WakeUp
The  driver  supports  sleep  and  wakeup  functionality.  With  the  function  CanSleep()  the
CAN controller enters sleep mode and leaves it with the function CanWakeUp() (internal
wakeup)  or  upon  a  falling  edge  respectively  dominant  level  on  the  Rx  pin  (external
wakeup).
Specify the Sleep/Wakeup option in the generation tool in order to use the Sleep/Wakeup
functionality.  If  this  option  is  not  enabled,  the  service  functions  CanSleep()  and
CanWakeUp() are empty and return kCanNotSupported.
4.1
Sleep
The  function  CanSleep()  changes  the  channel  from  communication  mode  via  reset
mode to stop mode. If the function is called during CAN communication, the reception or
transmission  is  terminated  before  it  is  completed  (the  same  applies  to  a  call  of
CanResetBusSleep()).
The return value kCanOk is always expected as these mode transitions do not depend on
external influences (e.g. the CAN bus level). However, if the function returns kCanFailed
(e.g. caused by a hardware loop cancellation, see chapter 5 for details) call CanSleep()
again or re-initialize the channel.
4.2
Internal Wakeup
The  function  CanWakeUp()  changes  the  channel  from  stop  mode  via  reset  mode  to
communication mode.
The return value kCanOk is always expected as these mode transitions do not depend on
external influences (e.g. the CAN bus level). However, if the function returns kCanFailed
(e.g. caused by a hardware loop cancellation, see chapter 5 for details) call CanWakeup()
again or re-initialize the channel.
4.3
External Wakeup
The external wakeup functionality is realized by external interrupts but fully handled by the
CAN driver in default configurations. The RSCAN itself does not provide any possibility of
detecting bus activity if  it is in  stop mode. Instead  the port configuration of  many  RH850
derivatives allows combining the CANn Rx pin with an external interrupt INTPm to be able
to  detect  a  CAN  event  even  if  the  driver  is  in  sleep  mode.  See  the  hardware
documentation of the actual derivative for details (Port x – Alternative Functions) and refer
to chapter 10 for implementation hints.
When the driver is in  sleep mode and a  CAN event is detected on the Rx pin a wakeup
interrupt is generated. It is also possible to detect this event by polling the interrupt request
flag without enabling the interrupt source. The ISR or the task function calls the application
function  ApplCanPreWakeUp()  (if  configured),  changes  the  channel  mode  via  reset
mode to communication mode and then calls ApplCanWakeUp().
2015, Vector Informatik GmbH
Version: 1.08.00
11 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

Caution
If the Sleep/Wakeup functionality is enabled via the configuration tool both the internal
  and external wakeup are available  by default  and the CAN driver expects that the Rx
pin  of  each  used  CAN  channel  is  linked  with  an  external  interrupt  in  context  of  the
RH850  port  configuration  as  depicted  in  the  corresponding  hardware  manual.
Additionally  the  driver  expects  that  each  external  interrupt  source  is  assigned  to  the
lowest  possible  interrupt  channel  if  the  sources  are  multiplexed  (check  the  “INTC1
interrupt select register” if applicable).
If  this  configuration  is  not  possible  for  the  actual  derivative  (refer  to  the  hardware
documentation) or any respective external interrupt cannot be used exclusively by the
driver (write accesses to the corresponding interrupt control register, e.g. if any external
MCU  wakeup  handling  using  this  source  is  implemented),  the  external  wakeup
functionality must not be used.
In this case the Sleep/Wakeup functionality has to be disabled via the generation tool
or the external wakeup handling has to be deactivated by adding following to the user
configuration file:
#define C_ENABLE_EXTERNAL_WAKEUP_SUPPRESSION
Then  the  driver  does  not  access  the  external  interrupt  sources  and  only  the  internal
wakeup is possible (the driver does not wake up on bus activity).

Caution
The driver performs write accesses within the interrupt controller address space of the
  MCU if the external wakeup functionality is used. If wakeup processing is configured to
interrupt  the  corresponding  source  is  enabled  at  successful  sleep  transitions  and
disabled  during  wakeup  transitions.  Additionally  the  corresponding  interrupt  request
flag is cleared right before the interrupt is enabled; hence a wakeup event can only be
detected  after  the  sleep  transition  has  been  successfully  completed.  Refer  to  section
10.3 if an exclusive write access to the interrupt control registers is not possible. Please
note that the interrupt request flag also has to be cleared for polling configurations.

2015, Vector Informatik GmbH
Version: 1.08.00
12 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

5   [#hw_loop] - Hardware Loop Check
In  context  of  the  feature  Hardware  Loop  Check  (see  TechnicalReference_CANDriver,
chapter Hardware Loop Check) this CAN Driver provides the following timer identifications.
Refer to the hardware manual for a description of the RSCAN clock sources and additional
information  on  other  hardware  specifics  like  the  mode  transitions.  Please  note  that  the
expected loop durations  vary between individual derivatives. The given values depict the
worst case and may be lower for the actually used derivative.

Caution
Always significantly increase the given durations for the loop callout implementation to
  compensate additional software delays.

kCanLoopRamInit
This loop may be called within the function CanInitPowerOn() and is processed until
the  CAN  RAM  initialization  after  a  MCU  reset  has  finished.  This  is  necessary  as  this
initialization has to be completed before the  RSCAN  can be configured. As this loop is
not called in channel context the channel parameter has to be ignored.
The maximum  expected  duration  to  wait for  the  CAN  RAM  initialization  starts  from  the
time  of  the  MCU  reset  and  is  device  specific.  Refer  to  the  corresponding  hardware
manual (e.g.  section RSCAN Setting Procedure  –  Initial Settings) to get  the number of
required cycles of the pclk. If this loop is canceled try to call CanInitPowerOn() again
or reset the MCU.

kCanLoopInit
This  loop may  be  called  within  the function  CanInitPowerOn(). As  it  is  not  called  in
channel  context  the  channel  parameter  has  to  be  ignored.  The  loop  may  be  called
multiple times within this function and the possible occurrences are as follows:
  To protect the transition via global reset mode to global stop mode.
  To protect the transition to global reset mode.
  To protect transitions and settings in context of the global test mode (only active if the
RSCAN RAM test is enabled)
  To protect the transition to channel reset mode for each active channel.
  To protect the transition to global operation mode.

The duration for each mode transition in this context is expected to be two CAN bit times
at  highest  (of  the  lowest  communication  speed  of  the  channels  in  use).  If  any  loop
occurrence is canceled try to call CanInitPowerOn() again or reset the MCU.

2015, Vector Informatik GmbH
Version: 1.08.00
13 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

kCanLoopBusOffRecovery
This channel dependent loop may be called in CanInit() if the RSCAN is currently in
BusOff  state  and  is  processed  until  11  consecutive  recessive  bits  have  been  detected
128 times on the bus to ensure compliance to the BusOff recovery specification (see also
chapter 6).
The  maximum  expected  duration  is  1408  CAN  bit  times  on  a  recessive  bus,  128
message  times  including  inter-frame  space  on  a  communicative  bus  or  any  time  if
disturbances are present. There is no issue and nothing to do if the loop is canceled, but
the specified BusOff recovery time may not be met.

kCanLoopEnterResetMode
This  channel  dependent  loop  may  be  called  multiple  times  in  CanInit()  and  is
processed  as  long  as  the  CAN  cell  does  not  enter  channel  reset  mode,  respectively
channel operation mode.
The  maximum  expected  duration  of  each  loop  is  three  CAN  bit  times.  If  the  loop  is
canceled try to call CanInit() again. If the loop still doesn’t finish within the expected
time call CanInitPowerOn().

kCanLoopEnterOperationMode
This channel dependent loop is called in CanStart() and is processed as long as the
CAN cell does not enter channel operation mode.
The  maximum  expected  duration  of  the  loop  is  three  CAN  bit  times.  If  the  loop  is
canceled  try  to  call  CanStart()  again  or  invoke  CanInit().  If  the  loop  still  doesn’t
finish within the expected time call CanInitPowerOn().

kCanLoopEnterSleepMode
This  channel  dependent  loop  may  be  called  multiple  times  in  CanSleep()  and  is
processed  as  long  as  the  CAN  cell  does  not  enter  channel  reset  mode,  respectively
channel stop mode.
The maximum expected duration of the loop is two CAN bit times. If the loop is canceled
try to call CanSleep() again or invoke CanInit(). If the loop still doesn’t finish within
the expected time call CanInitPowerOn().

kCanLoopEnterWakeupMode
This  channel  dependent  loop  may  be  called  multiple  times  in  CanWakeUp()  and  is
processed  as  long  as  the  CAN  cell  does  not  enter  channel  reset  mode,  respectively
channel operation mode.
The  maximum  expected  duration  of  the  loop  is  three  CAN  bit  times.  If  the  loop  is
canceled try to call CanWakeUp() again or invoke CanInit(). If the loop still doesn’t
finish within the expected time call CanInitPowerOn().

2015, Vector Informatik GmbH
Version: 1.08.00
14 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

kCanLoopRxFcProcess
This  channel  depended  loop  may  be  called  in  CanFullCanMsgReceived()  and  is
processed  as  long  as  new  messages  are  received  by  the  current  receive  buffer  while
copying a previously received message to a temporary software buffer. This ensures that
always consistent and most recent data is indicated to the higher layers.
It is expected that the loop is called only one time. Please note that if the loop iterates at
all,  previously  received  messages  of  the  current  receive  buffer  are  discarded  without
further notification as data consistency cannot be ensured. There is no issue and nothing
to do if the loop is canceled, but the latest message is also discarded and the function
CanFullCanMsgReceived() returns without indicating any message at all.

2015, Vector Informatik GmbH
Version: 1.08.00
15 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

6  [#hw_busoff] - Bus off
In  case  of  a  BusOff  event  the  controller  automatically  changes  to  stop  mode  on  the
respective  channel.  There  is  no  automatic  recovery  as  specified  by  ISO11898-1;  the
application  has  to  restart  communication  following  the  description  in  the  Technical
Reference CAN driver, i.e. by calling CanResetBusOffStart/-End() which leads to a
call of CanInit().

Caution
Please note that if CanResetBusOffEnd() is called before 11 consecutive recessive
  bits have been detected 128 times on the bus, the function CanInit() waits until this
condition  is  met.  Reason  is  that  the  current  recovery  status  is  lost  during  re-
initialization.  It  may  not  be  acceptable  for  the  program  to  wait  until  the  hardware  has
recovered  as  this  delay  is  implemented  synchronously.  In  this  case  use  the  feature
“Hardware  Loop  Check”  to  control  the  behavior.  See  kCanLoopBusOffRecovery  in
chapter 5 for details.

2015, Vector Informatik GmbH
Version: 1.08.00
16 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

7  CAN Driver Features
7.1
[#hw_feature] - Feature List

Standard
HighEnd
Initialization
Power-On Initialization


Re-Initialization


Transmission
Transmit Request


Transmit Request Queue


Internal data copy mechanism


Pretransmit functions


Common confirmation function


Confirmation flag


Confirmation function


Offline Mode


Partial Offline Mode


Passive-Mode


Tx Observe mode


Dynamic TxObjects
ID



DLC



Data-Ptr


Full CAN Tx Objects


Cancellation in Hardware


Low Level Message Transmit
-

Reception
Receive function


Search algorithms
Linear



Table
-
-

Index



Hash


Range specific precopy functions
4
4
(min. 2, typ.4)
DLC check


Internal data copy mechanism


Generic precopy function


Precopy function


Indication flag


Indication function


Message not matched function


2015, Vector Informatik GmbH
Version: 1.08.00
17 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

Overrun Notification


Full CAN overrun notification
-
-
Multiple Basic CAN
-

Rx Queue 2
-

Bus off
Notification function


Nested Recovery functions


Sleep Mode
Mode Change


Preparation


Notification function


Special Features
Status


Security Level


Assertions


Hardware loop check


Stop Mode


Support of OSEK operating


system
Polling Mode
Tx



Rx (FullCAN) 3



Rx (BasicCAN)



Error



Wakeup


Individual Polling 4
-

Multi channel


Support extended ID addressing


mode
Support mixed ID addressing


mode
Support access to error counters


Copy functions


CAN RAM check 5


Extended CAN RAM check 6


Table 7-1   CAN Driver Functionality


2 Consider that the Rx BasicCAN hardware FIFOs in combination with Rx BasicCAN polling might be a more
efficient alternative to the Rx Queue in many configurations.
3 Due to hardware limitations (no interrupt request can be generated for receive buffers) Rx FullCAN polling
is mandatory if Rx FullCAN objects are configured.
4 Due to hardware limitations (see note 3) all Rx FullCAN objects have to be polled.
5 Due to hardware limitations (no write access to Rx objects) only supported for Tx objects.
6 This feature is project specific and only available if explicitly ordered.
2015, Vector Informatik GmbH
Version: 1.08.00
18 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

7.2
Description of Hardware-related Features
7.2.1
[#hw_status] - Status
If a status is not supported, the related macro always returns false.
Status
Support
CanHwIsOk(state)

CanHwIsWarning(state)

CanHwIsPassive(state)

CanHwIsBusOff(state)

CanHwIsWakeup(state)

CanHwIsSleep(state)

CanHwIsStart(state)

CanHwIsStop(state)

CanIsOnline(state)

CanIsOffline(state)

Table 7-2   CAN Status
7.2.2
[#hw_stop] - Stop Mode
The service function CanStop() calls CanInit() and leaves the channel in reset mode,
where it is disconnected from the bus. If the function is called during CAN communication,
the reception or transmission is terminated before it is completed. This mode can be left by
calling CanStart(). Both transitions do not depend on external influences (e.g. the CAN
bus level), so the return value kCanOk is always expected. However, if the functions return
kCanFailed (e.g. caused by a hardware loop cancellation, see chapter 5 for details) call
CanStop() respectively CanStart() again or re-initialize the channel.

7.2.3
[#hw_int] - Control of CAN Interrupts
CAN interrupt locking is performed by modifying the interrupt request mask bits (MK) in the
control registers of the appropriate sources directly within the interrupt controller address
space of the MCU. Therefore the driver needs exclusive write access to all CAN related EI
level  interrupt  control  registers  (ICn).  If  the  Sleep/Wakeup  functionality  is  enabled  this
includes the ICn of external interrupt sources (see chapter 4).
Since  Rx  FIFO  interrupt  and  overrun  (global  error)  cannot  be  enabled  and  disabled  for
every  object  individually  they  are  disabled  globally  when  the  interrupts  of  at  least  one
controller are disabled and enabled globally if  the interrupts of no controller are disabled
anymore.
All CAN related ICn are initialized and then modified by the driver during runtime (interrupt
disable  and  restore).  The  priority  level  for  the  initialization  can  be  selected  via  the
configuration  tool  (all  CAN  interrupts  must  have  the  same  priority),  see  section  11.1.3.
Refer to chapter 10 for further information on CAN interrupts.
2015, Vector Informatik GmbH
Version: 1.08.00
19 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

Caution
In standard configuration the driver needs exclusive write access to all CAN related EI
  level  interrupt  control  registers.  Refer  to  chapter  10  for  further  information  and
especially section 10.3 if an exclusive write access is not possible.

7.2.4
[#hw_cancel] - Cancel in Hardware

Yes  No
Has the CanTxTask() to be called by the application to handle the canceled
transmit request in the hardware?



Cancelling transmission of messages via CanCancelTransmit() or
CanCancelMsgTransmit():

Yes  No
ApplCanTxConfirmation() is only called for transmitted messages, successfully
canceled messages are not notified. That means the CAN driver is able to detect


whether a message is transmitted even if the application has tried to cancel.

7.2.5
Remote Frames
Remote Frames will not have any influence on  the communication because they  are not
received due to hardware filtering.

7.2.6
CAN RAM Check
The  CAN  driver  supports  a  check  of  the  CAN  mailboxes  which  is  performed  internally
every  time  the  function  CanInit()  is  called.  The  CAN  driver  verifies  that  no  used
mailboxes are corrupt. A mailbox is considered corrupt if predefined patterns are written to
the appropriate mailbox registers and read operations do not return the expected patterns.
If  a  corrupt  mailbox  is  found  the  function  ApplCanCorruptMailbox()  is  optionally
called to inform the application which mailbox is affected.
After  the  check  of  all  mailboxes  on  the  given  channel  the  CAN  driver  calls  the  function
ApplCanMemCheckFailed() if at least one corrupt mailbox was found. The application
can control whether the CAN driver disables communication on the current channel or not
by  means  of  the  return  value  of  the  call-back  function.  If  the  application  has  decided  to
disable the communication there is no possibility to enable the communication again until
the next call of CanInitPowerOn().

Caution
Due to hardware limitations (no write access for receive objects) the CAN RAM check
  is only supported for transmit mailboxes. Consider the behavioural differences of CAN
RAM check when it is used in combination with the extended CAN RAM check feature.

2015, Vector Informatik GmbH
Version: 1.08.00
20 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

The additional call-back function ApplCanCorruptMailbox() can only be activated via
the user configuration file - the settings are listed below. In case no user config file is used
(i.e. the mentioned switch is not defined) the feature is disabled.
Switch
Value
Description
C_ENABLE_NOTIFY_CORRUPT_MAILBOX

Activate call of ApplCanCorruptMailbox()
in case the CAN RAM check fails for a certain
mailbox.

7.2.7
Extended CAN RAM Check
The  extended RAM check provides an additional check of the CAN cell control  registers
RAM with extended API and modified standard CAN RAM check and driver behaviour.
The RSCAN control registers are differentiated between registers that have to be written in
global  reset  mode  (afterwards  referred  to  as  “global  registers”)  or  can  also  be  written  in
channel reset mode (afterwards referred to as “channel registers”). Since the transition to
global reset mode affects all channels, the global register RAM is checked only once within
CanInitPowerOn(). If the global register RAM is considered corrupt a call-back function
(see below) is issued to allow the application to control whether the driver initialization is
proceeded or not.
The  channel  register  and  mailbox  RAM  check  is  performed  within  the  function
CanInit(). The registers RAM check disables the complete channel communication if at
least  one  of  the  checked  registers  is  considered  corrupt. The  mailbox  RAM  check  (only
available for Tx objects) disables corrupt mailboxes so that no transmission is possible on
them.  In  both  cases  the  appropriate  call-backs  (see  below)  are  called  to  inform  the
application  about  the  failures.  Channels  and  mailboxes  can  be  re-enabled  by  the
application  using  the  extended API.  If  any  of  the  control  registers  check  or  the  mailbox
registers  check  fails  the  overall  RAM  check  call-back  ApplCanMemCheckFailed()  is
invoked.
More detailed information is given below; section 9.3 describes the API functions:
  If any of the global registers (e.g. global configuration registers, registers relating to the
configuration of receive objects and receive rules) are considered corrupt the function
ApplCanGlobalMemCheckFailed()  is  invoked  within  CanInitPowerOn().  If  this
function  returns  kCanEnableCommunication  the  initialization  is  continued  ignoring
the results of the check. If it returns kCanDisableCommunication the RSCAN is put
back  into  global  stop  mode  and  CanInitPowerOn()  returns  without  initializing  the
RSCAN.  The  check  of  the  channel  registers  RAM  is  also  not  performed  and
CanInitPowerOn() has to be called again to be able to use the CAN functionality in
this case (other CAN API functions must not be called until CanInitPowerOn() was
executed completely). The check is performed with every call of this function.
  If  any  of  the  channel  control  registers  are  considered  corrupt  the  function
ApplCanCorruptRegisters()  is  called  and  the  communication  on  the  given
channel is disabled. The CAN cell stays in stop mode whatever the general call-back
function ApplCanMemCheckFailed()  returns  and the  channel  is disconnected from
the Tx port pin.
2015, Vector Informatik GmbH
Version: 1.08.00
21 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

  If  a  corrupt  mailbox  is  found  it  is  disabled  by  the  driver  and  the  call-back  function
ApplCanCorruptMailbox()  is  invoked  (if  this  is  enabled  by  the  definition  of
C_ENABLE_NOTIFY_CORRUPT_MAILBOX).  In  this  case  (but  only  if  no  corrupt  CAN
control registers were found on the given channel) the application can decide whether
the  communication  on  the  channel  should  be  disabled  using  the  return  value  of  the
function ApplCanMemCheckFailed(), but the mailbox stays disabled anyway.
  If the communication on a channel was disabled previously it can be re-enabled using
the function CanEnableChannelCommunication().
  Mailboxes that were disabled by mailbox RAM check can be re-enabled by the function
CanEnableMailboxCommunication() (but  only if the communication on the given
channel is enabled).
  No  mailbox  or  register  RAM  check  is  performed  and  no  RAM  check  call-backs  are
invoked  if  CanInit()  is  called  by  CanResetBusOffEnd().  However,  all  previously
disabled channels or mailboxes stay disabled.

Caution
The  only  way  to re-enable  channel  or  mailbox  communication  is  to  use  the  functions
  CanEnableChannelCommunication(),  CanEnableMailboxCommunication()
or CanInitPowerOn().

The extended CAN RAM check feature needs the standard CAN RAM check functionality
to  be  activated.  The  following  settings  have  to  be  done  in  the  user  configuration  file.  In
case  no  user  config  file  is  used  (i.e.  the  mentioned  switch  is  not  defined)  the  feature  is
disabled. Please note that this is a project specific feature that might not be available and
C_ENABLE_CAN_RAM_CHECK_EXTENDED has no effect in this case.
Switch
Value  Description
C_ENABLE_CAN_RAM_CHECK_EXTENDED

Activate the extended CAN RAM check feature.

7.2.8
RSCAN ECC Configuration
In context of the RSCAN RAM error detection and correction (ECC) the driver provides the
additional  call-back  function  ApplCanEccConfiguration()  (see  section  9.2)  that  is
invoked by CanInitPowerOn() after the CAN RAM initialization is complete and before
the RSCAN is configured while the cell is in global stop mode. This gives the application
the possibility to configure the ECC behavior for  the RSCAN. The driver offers no further
support for this feature - any ECC configuration and handling has to be performed by the
application.
The following settings have to be done in the user configuration file. In case no user config
file is used (i.e. the mentioned switch is not defined) the feature is disabled.
Switch
Value  Description
C_ENABLE_ECC_CALLOUT

Activate call of ApplCanEccConfiguration().

2015, Vector Informatik GmbH
Version: 1.08.00
22 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

7.2.9
RSCAN RAM Test
The RSCAN provides a global test mode that enables the driver to perform a check of the
internal  RSCAN  RAM  that  is  not  accessible  during  normal  operation.  This  check  is
performed once  within  CanInitPowerOn().  Similar  to the  (extended)  CAN  RAM  check
the internal RAM is considered corrupt if predefined patterns are written to the appropriate
RAM  addresses  and  read  operations  do  not  return  the  expected  patterns.  If  any  corrupt
bits  are  found  the  call-back  function  ApplCanGlobalMemCheckFailed()  is  invoked
(see section 9.3). If this function returns kCanEnableCommunication the initialization is
continued  ignoring  the  results  of  the  check.  If  it  returns  kCanDisableCommunication
the RSCAN is put back into global stop mode and CanInitPowerOn() returns without
initializing the RSCAN. CanInitPowerOn() has to be called again to be able to use the
CAN  functionality  in  this  case  (other  CAN  API  functions  must  not  be  called  until
CanInitPowerOn()  was  executed  completely).  The  RAM  test  is  performed  with  every
call of this function.
If this test is used in combination with the (extended) CAN RAM check the coverage of the
latter one is reduced in order to save runtime.
  The receive rule registers are omitted by  the global register check within the function
CanInitPowerOn().
  The mailbox check is omitted if CanInit() is called out of CanInitPowerOn().

The following settings have to be done in the user configuration file. In case no user config
file is used (i.e. the first switch is not defined) the feature is disabled. The second switch is
only evaluated if C_ENABLE_CAN_HW_RAM_CHECK is defined.
Switch
Value
Description
C_ENABLE_CAN_HW_RAM_CHECK

Activate the RSCAN RAM test feature.
C_ENABLE_CAN_HW_RAM_CHECK_SIZE
32 .. 65504  The given number of bytes is checked by the
(bytes)
RAM test (always starting from the beginning
of the CAN RAM). The value must be a
multiple of 32 bytes and has to be valid for the
used derivative (refer to the corresponding
hardware manual).

Caution
Depending  on  the  size  of  RAM  to  be  checked,  used  compiler  options,  clock  settings
  and others this check might take up to several milliseconds. Suggestion is to verify the
runtime of CanInitPowerOn()in the actual project if this feature is enabled.

2015, Vector Informatik GmbH
Version: 1.08.00
23 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

8   [#hw_assert] – Assertions
The driver implements no specific assertions with additional error codes.
2015, Vector Informatik GmbH
Version: 1.08.00
24 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

9  API
9.1
Category
Single Receive Channels (SRC)

A “Single Receive Channel” CAN Driver supports one CAN
channel.)
Multiple Receive Channel (MRC)

A "Multiple Receive Channel" CAN Driver is typically
extended for multiple channels by adding an index to the
function parameter list (e.g. CanOnline() becomes
CanOnline(channel)) or by using the handle as a
channel indicator (e.g. CanTransmit(txHandle)).
Table 9-1   API Category

9.2
RSCAN ECC Configuration
In  context  of  the  RSCAN  ECC  feature  the  application  has  to  provide  following  call-back
function (see section 7.2.8 further information).

ApplCanEccConfiguration
Prototype
Single Receive Channel
void ApplCanEccConfiguration (void)
Multiple Receive Channel
void ApplCanEccConfiguration (void)
Parameter
-
-
Return code
-
-
Functional Description
This function is called by CanInitPowerOn() to allow the configuration of the RSCAN ECC functionality.
Particularities and Limitations
Only required if C_ENABLE_ECC_CALLOUT is defined.

2015, Vector Informatik GmbH
Version: 1.08.00
25 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

9.3
(Extended) CAN RAM Check

In context of the CAN RAM check feature the application has to provide following call-back
functions (see sections 7.2.6 and 7.2.7 for further information).

ApplCanMemCheckFailed
Prototype
Single Receive Channel
vuint8 ApplCanMemCheckFailed (void)
Multiple Receive Channel
vuint8 ApplCanMemCheckFailed (CanChannelHandle channel)
Parameter
This parameter specifies the CAN channel on which the memory check is
CanChannelHandle channel
performed.
Return code
vuint8
kCanEnableCommunication – Allow communication (see note in
“Particularities and Limitations”).
kCanDisableCommunication – Disable communication, no reception and
no transmission is performed.
Functional Description
This call-back function is invoked within CanInit() if the CAN driver has found at least one corrupt bit
within the CAN mailboxes RAM or (if extended CAN RAM check is enabled) at least one corrupt bit within
the channel control registers RAM. The application can decide whether the CAN driver allows further
communication by means of the return value.
Particularities and Limitations
Call context: If the feature Extended CAN RAM check is deactivated this function is called on task level or
within the BusOff interrupt; else only on task level.
Configuration: Required if the following setting is active:
C_ENABLE_CAN_RAM_CHECK
Important note: If the optional feature “Extended CAN RAM check” is activated
(C_ENABLE_CAN_RAM_CHECK_EXTENDED is defined) and the registers RAM check failed (call-back
function ApplCanCorruptRegisters() was called for the given channel), the communication on the
channel will be disabled, the CAN cell stays in stop mode and the return value of this function is ignored –
the communication will NOT be allowed even if the return value is kCanEnableCommunication.

2015, Vector Informatik GmbH
Version: 1.08.00
26 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

ApplCanCorruptMailbox
Prototype
Single Receive Channel
void ApplCanCorruptMailbox (CanObjectHandle hwObjHandle)
Multiple Receive Channel
void ApplCanCorruptMailbox (CanChannelHandle channel,
CanObjectHandle hwObjHandle)

      CanObjectHandle hwObjHandle )
Parameter
This parameter specifies the CAN channel on which the memory check is
CanChannelHandle channel
performed.
This parameter specifies the index of the corrupt mailbox.
CanObjectHandle

hwObjHandle
Return code
-
-
Functional Description
This function is called within CanInit() if the CAN driver has found a corrupt mailbox.
Particularities and Limitations
Call context: If the feature “Extended CAN RAM check” is deactivated this function is called on task level or
within the BusOff interrupt; else only on task level.
Configuration: Required if the following settings are active:
C_ENABLE_CAN_RAM_CHECK
C_ENABLE_NOTIFY_CORRUPT_MAILBOX

In case the feature extended CAN RAM check is enabled the following additional call-back
functions have to be provided by the application.

ApplCanCorruptRegisters
Prototype
Single Receive Channel
void ApplCanCorruptRegisters (void)
Multiple Receive Channel
void ApplCanCorruptRegisters (CanChannelHandle channel)
Parameter
This parameter specifies the CAN channel on which the memory check is
CanChannelHandle channel
performed.
Return code
-
-
Functional Description
This function is called if the CAN driver has found corrupt channel control registers.
Particularities and Limitations
Call context: This function is called out of task level within CanInit() on the given channel if the RAM
check is not suppressed. The RAM check is suppressed if CanInit() is called in scope of the functions
CanResetBusOffEnd()or (dependent on parameter) CanEnableChannelCommunication().
Configuration: Required if the following settings are active:
C_ENABLE_CAN_RAM_CHECK
C_ENABLE_CAN_RAM_CHECK_EXTENDED

2015, Vector Informatik GmbH
Version: 1.08.00
27 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

ApplCanGlobalMemCheckFailed
Prototype
Single Receive Channel
vuint8 ApplCanGlobalMemCheckFailed (void)
Multiple Receive Channel
vuint8 ApplCanGlobalMemCheckFailed (void)
Parameter
-
-
Return code
vuint8
kCanEnableCommunication – Continue initialization of the RSCAN.
kCanDisableCommunication – Stop initialization of the RSCAN.
Functional Description
This call-back function is invoked if the CAN driver has found at least one corrupt bit within the global control
registers RAM in context of the extended CAN RAM check or if any corrupt bit was found in context of the
RSCAN RAM test (see section 7.2.9). The application can decide whether the CAN driver proceeds with the
RSCAN initialization by means of the return value.
Particularities and Limitations
Call context: This function is called out of task level within CanInitPowerOn().
Configuration: Required if the following settings are active:
C_ENABLE_CAN_RAM_CHECK
C_ENABLE_CAN_RAM_CHECK_EXTENDED
or
C_ENABLE_CAN_HW_RAM_CHECK
Important note: Be aware of undefined runtime behavior if kCanEnableCommunication is returned as
the driver tries to initialize and communicate despite corrupt RAM was found. The application has to verify
the system in this case.

2015, Vector Informatik GmbH
Version: 1.08.00
28 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

The following service functions are provided by the driver in context of the extended CAN
RAM check feature.

CanEnableChannelCommunication
Prototype
Single Receive Channel
void CanEnableChannelCommunication (vuint8 suppressRamCheck)
void CanEnableChannelCommunication (CanChannelHandle channel,
Multiple Receive Channel
vuint8 suppressRamCheck)
Parameter
This parameter specifies the CAN channel that shall be re
CanChannelHandle channel
-enabled.
vuint8 suppressRamCheck
kCanTrue – RAM check will be suppressed while re-enabling the
communication on the channel.
kCanFalse – RAM check will be performed while re-enabling the
communication on the channel
Return code
-
-
Functional Description
The function re-enables the channel communication if it was disabled previously. It calls CanInit()
internally but all eventually disabled mailboxes stay disabled. If the RAM check is not suppressed it can fail
again and the appropriate call-back function is invoked in this case.
Particularities and Limitations
Restriction: Same restrictions as for a call of CanInit() apply.
Call context: This function is called by the application.
Configuration: Available if the following settings are active:
C_ENABLE_CAN_RAM_CHECK
C_ENABLE_CAN_RAM_CHECK_EXTENDED

2015, Vector Informatik GmbH
Version: 1.08.00
29 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

CanEnableMailboxCommunication
Prototype
Single Receive Channel
vuint8 CanEnableMailboxCommunication (CanObjectHandle

hwObjHandle)
Multiple Receive Channel
vuint8 CanEnableMailboxCommunication (CanChannelHandle channel,

CanObjectHandle hwObjHandle)
Parameter
This parameter specifies the CAN channel for which the mailbox shall be
CanChannelHandle channel
re-enabled.
The index of the mailbox to be re
CanObjectHandle
-enabled.
hwObjHandle
Return code
vuint8
kCanOk - Mailbox communication was re-enabled.
kCanFailed - Enabling of mailbox communication failed: hwObjHandle is
not a valid Tx mailbox, the mailbox was not disabled previously or the
communication on the channel is still disabled.
Functional Description
The function re-enables the mailbox communication that was disabled previously by the extended CAN
RAM check. Note that the mailbox RAM check is not performed in scope of this function call - the
application must guarantee that the mailbox is not corrupt.
Particularities and Limitations
Call context: This function is called by the application.
Configuration: Available if the following settings are active:
C_ENABLE_CAN_RAM_CHECK
C_ENABLE_CAN_RAM_CHECK_EXTENDED

2015, Vector Informatik GmbH
Version: 1.08.00
30 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

9.4
External CAN Interrupt Handling
These  call-back  functions  are  invoked  if  the  driver  does  not  perform  the  CAN  interrupt
handling. See section 10.3 for details.

ApplCanWriteIcr8
Prototype
Single Receive Channel
void ApplCanWriteIcr8 (vuint32 address, vuint8 value)
Multiple Receive Channel
void ApplCanWriteIcr8 (vuint32 address, vuint8 value)
Parameter
This parameter specifies the memory address the function has to write to.
vuint32 address
It is always part of the interrupt controller address space.
vuint8 value
This parameter specifies the value the function has to write.
Return code
-
-
Functional Description
This call-back is invoked by several driver functions and has to write one byte with the given value to the
given address.
Particularities and Limitations
Only required if C_ENABLE_INTC_ACCESS_BY_APPL is defined.
Always perform a byte access. The function has to be synchronous.

ApplCanReadIcr8
Prototype
Single Receive Channel
vuint8 ApplCanReadIcr8 (vuint32 address)
Multiple Receive Channel
vuint8 ApplCanReadIcr8 (vuint32 address)
Parameter
This parameter specifies the memory address the function has to read
vuint32 address
from. It is always part of the interrupt controller address space.
Return code
vuint8
The value that was read from the given address.
Functional Description
This call-back is invoked by several driver functions and has to read and return one byte from the given
address.
Particularities and Limitations
Only required if C_ENABLE_INTC_ACCESS_BY_APPL is defined.
Always perform a byte access. The function has to be synchronous.

2015, Vector Informatik GmbH
Version: 1.08.00
31 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

OsCanCanInterruptDisable
Prototype
Single Receive Channel
void OsCanCanInterruptDisable (void)
Multiple Receive Channel
void OsCanCanInterruptDisable (CanChannelHandle channel)
Parameter
This parameter specifies the logical CAN channel for which the interrupts
CanChannelHandle channel
shall be disabled.
Return code
-
-
Functional Description
This function is called by CanCanInterruptDisable() and has to disable the CAN interrupts on the
given channel.
Particularities and Limitations
Only required if C_ENABLE_OSEK_CAN_INTCTRL is defined.

OsCanCanInterruptRestore
Prototype
Single Receive Channel
void OsCanCanInterruptRestore (void)
Multiple Receive Channel
void OsCanCanInterruptRestore (CanChannelHandle channel)
Parameter
This parameter specifies the logical CAN channel for which the interrupts
CanChannelHandle channel
shall be restored.
Return code
-
-
Functional Description
This function is called by CanCanInterruptRestore() and has to restore the CAN interrupts on the
given channel.
Particularities and Limitations
Only required if C_ENABLE_OSEK_CAN_INTCTRL is defined.

2015, Vector Informatik GmbH
Version: 1.08.00
32 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

ApplCanWakeupInterruptDisable
Prototype
Single Receive Channel
void ApplCanWakeupInterruptDisable (vuint8 channel)
Multiple Receive Channel
void ApplCanWakeupInterruptDisable (vuint8 channel)
Parameter
This parameter specifies the logical CAN channel for which the wakeup
vuint8 channel
interrupt shall be disabled.
Return code
-
-
Functional Description
This function is called by CanWakeup() and CanInit() and has to disable the wakeup interrupt on
the given channel.
Particularities and Limitations
Only required if C_ENABLE_OSEK_CAN_INTCTRL and C_ENABLE_SLEEP_WAKEUP are defined and the
external wakeup is used.

ApplCanWakeupInterruptEnable
Prototype
Single Receive Channel
void ApplCanWakeupInterruptEnable (vuint8 channel)
Multiple Receive Channel
void ApplCanWakeupInterruptEnable (vuint8 channel)
Parameter
This parameter specifies the logical CAN channel for which the wakeup
vuint8 channel
interrupt shall be enabled.
Return code
-
-
Functional Description
This function is called by CanSleep() and has to enable the wakeup interrupt on the given channel.
Particularities and Limitations
Only required if C_ENABLE_OSEK_CAN_INTCTRL and C_ENABLE_SLEEP_WAKEUP are defined and the
external wakeup is used.

2015, Vector Informatik GmbH
Version: 1.08.00
33 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

ApplCanWakeupOccurred
Prototype
Single Receive Channel
vuint8 ApplCanWakeupOccurred (vuint8 channel)
Multiple Receive Channel
vuint8 ApplCanWakeupOccurred (vuint8 channel)
Parameter
This parameter specifies the logical CAN channel to check for a wakeup
vuint8 channel
occurrence.
Return code
CAN_NOT_OK: If no wakeup occurred on this channel
vuint8
CAN_OK: If a wakeup occurred on this channel
Functional Description
This function is called by CanWakeupTask() and has to check for a wakeup event on the given
channel.
Particularities and Limitations
Only required if C_ENABLE_OSEK_CAN_INTCTRL, C_ENABLE_SLEEP_WAKEUP and
C_ENABLE_WAKEUP_POLLING are defined and the external wakeup is used.

2015, Vector Informatik GmbH
Version: 1.08.00
34 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

10  Implementations Hints
10.1  Important Notes
1.  The  following  condition  will  lead  to  an  endless  recursion  in  the  CAN  Driver:
Recursive  call  of  'CanTransmit'  within  a  confirmation  routine,  if  the  CAN  Driver  has
been set into the passive state by CanSetPassive. Recommendations are:
>  NO CALL OF CanTransmit WITHIN CONFIRMATION-ROUTINES
>  PLEASE USE CanSetPassive ONLY ACCORDING TO THE DESCRIPTION

2.  Only  the  transmit  line  of  the  CAN  Driver  is  blocked  by  the  functions  CanOffline().
However, messages in the transmit buffer of the CAN-Chip, are still sent. For a reliable
prevention  of  this  fact,  call  function  CanInit()  after  calling  CanOffline().  The
order of the two function calls is urgently required, due to the fact, that CanInit() is
only allowed in offline mode.
3.  If the VStdLib interrupt-lock-level is used, the chosen priority level must be higher than
the  highest  level  of  any  functionality  of  the  CAN  Driver  (signal  access,  etc).  Keep  in
mind that smaller values represent higher priorities.
4.  Resetting  indication  flags  and  confirmation  flags  is  done  by  Read-Modify-Write.  The
application  is  responsible  for  consistency.  CanGlobalInterruptDisable()  and
CanGlobalInterruptRestore()  must  be  called  to  avoid  interruption  by  the  CAN.
Otherwise confirmations or indications can be lost.
5.  Port and general clock settings are not handled by the driver. This has to be performed
by  the  upper  layers  before  the  call  of  CanInitPowerOn().  Please  check  the
appropriate hardware manual of the used derivative for details regarding the hardware
specific  configuration  aspects.  The  CAN  clock  (fCAN)  for  baudrate  generation  can  be
selected via the configuration tool; refer to section 11.1.2.
6.  If  external  wakeup  support  is  used  the  port  configuration  (performed  by  the  upper
layers) has to be extended. Besides setting the correct port functions for CAN it has to
be  ensured  that  this  function  is  combined  with  the  respective  external  interrupt.
Additionally the edge/level detection has to be configured correctly to generate interrupt
requests  upon  detection  of  CAN  events  (e.g.  on  low  level  or  falling  edges)  on  the
corresponding  pins  (see  the  hardware  manual  for  details;  refer  to  the  filter  control
register for instance). If the external wakeup is used the control registers of the external
interrupts are also fully handled by the CAN driver in default configuration.
7.  When using GreenHills, IAR or Renesas compiler the ID bit of the PSW is cleared by
software when any category 1 interrupt service routine of the CAN driver is entered to
allow  nesting  of  interrupts.  For  other  compilers  the  default  platform  behavior  is  not
modified (the ID bit stays set) and the acknowledgement of further interrupt requests is
blocked when any driver ISR is processed. This default driver behavior for category 1
interrupts  can  be  changed  by  definition  of  C_DISABLE_NESTED_INTERRUPTS
respectively C_ENABLE_NESTED_INTERRUPTS via the user configuration file. Keep in
mind that enabling the feature is redundant if the compiler inserts code to allow nesting
of interrupts in general and always verify that the compiler generates correct code if the
feature is enabled.
2015, Vector Informatik GmbH
Version: 1.08.00
35 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

10.2  Interrupt Configuration
With  exception  of  the  CAN  related  EI  level  interrupt  control  registers  (ICn,  see  section
7.2.3) all further interrupt configuration within the interrupt controller address space of the
MCU has to be performed by the application before the call of CanInitPoweron().
The  default  implementation  configures  table  reference  as  the  way  to  determine  the
interrupt  vector  (TB  bit  in  ICn  registers  is  set).  The  application  has  to  take  care  about
referencing the CAN interrupt service routines in the interrupt vector table - the prototypes
are  exported in  the driver header file.  Please check the appropriate hardware  manual of
the used derivative for details regarding the hardware specific configuration aspects. Table
10-1 shows the provided  ISRs and the accordant interrupt  sources (n is the index of the
physical  channel).  Please  note  that  it  is  configuration  dependent  whether  a  particular
interrupt service routine is available (see remarks in table).

CAN interrupt
CAN interrupt
Provided service  Remarks
request name
request cause
routine
CAN RX FIFO
Used for BasicCAN reception if ‘Rx
INTRCANGRECC  interrupt
CanIsrRxFifo
BasicCan Polling’ is not enabled or

‘Individual Polling’ is configured.
CAN global error
INTRCANGERR
Used for Rx BasicCAN overrun if ‘Error

interrupt
CanIsrGlobalStatus

Polling’ is not enabled.
Used for transmission on physical
INTRCANnTRX
CANn TX interrupt
CanIsrTx_n
channel n if ‘Tx Polling’ is not enabled
or ‘Individual Polling’ is configured.
CANn TX/RX  FIFO
INTRCANnREC
RX complete interrupt -
This interrupt is not used.

Used for BusOff detection on physical
INTRCANnERR
CANn error interrupt
CanIsrStatus_n
channel n if ‘Error Polling’ is not
enabled.
Used for wakeup detection on physical
External interrupt
channel n if the Sleep/Wakeup
INTPm

(see chapter 4)
CanIsrWakeup_n
functionality is enabled, the external

wakeup is used and ‘Wakeup Polling’ is
not enabled.
Table 10-1   Interrupt Service Routines
If the INTC shall implement direct jumps to an address determined by the interrupt priority
level  (instead  of  table  reference)  the  switch  C_ENABLE_DIRECT_INTERRUPT_BRANCH
has to be defined via the user configuration file. (This setting affects the TB bit in the ICn
registers.) In this case the application has to implement a common service routine for all
CAN interrupts and jump to it from the corresponding address (refer to  hardware manual
for configuration aspects).
See below an implementation example for GreenHills compiler and a full interrupt system
with disabled Sleep/Wakeup functionality that uses physical channels 1 and 4; also refer to
the information in table 10-1 about the presence of the individual CAN interrupt functions.
Each driver routine must not be called if the CAN interrupts for the corresponding channel
(respectively  any  CAN  channel  for  the  global  handlers)  are  currently  disabled.  This  is
especially relevant if more than one channel is used or other interrupt sources also call the
common service routine. In general it is recommended to check the status of the MK bit in
2015, Vector Informatik GmbH
Version: 1.08.00
36 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

the  ICn  register  of  each  CAN  interrupt  source  before  invoking  the  corresponding  driver
routine as these bits directly indicate the status of the CAN interrupt lock mechanism. Any
driver routine may only be called if the corresponding interrupt source is enabled (MK bit
== 0). These actions may differ if the application handles the CAN interrupt disable/restore
mechanism (see section 10.3 below), but the requirements above must always be met.  If
the feature “Multiple Configurations” is used only functions corresponding to channels that
are used in the active identity should be called.

#pragma ghs interrupt
void CommonIsr_Prio_x ( void )
{
  /* handling for other interrupts that are assigned to
this priority and not handled by table reference */

  /* CAN interrupts */
  if (MK bit of INTRCANGRECC == 0) CanIsrRxFifo();
  if (MK bit of INTRCANGERR == 0) CanIsrGlobalStatus();
  if (MK bit of INTRCAN1ERR == 0) CanIsrStatus_1();
  if (MK bit of INTRCAN1TRX == 0) CanIsrTx_1();
  if (MK bit of INTRCAN4ERR == 0) CanIsrStatus_4();
  if (MK bit of INTRCAN4TRX == 0) CanIsrTx_4();

  /* handling for other interrupts that are assigned to
this priority and not handled by table reference */
}

Since  the  common  service  routine  is  already  qualified  as  an  ISR  to  the  compiler,  the
individual CAN interrupt routines have to be configured as void-void functions if this variant
is used. Therefore the switch C_ENABLE_ISRVOID additionally has to be defined via the
user configuration file (if category 1 CAN interrupts are used).

Caution
The  driver  performs  no  measures  to  ensure  the  correct  functionality  of  the  CAN
  interrupt disable/restore mechanism if it is bypassed by the common interrupt handler
when  C_ENABLE_DIRECT_INTERRUPT_BRANCH  is  defined.  Therefore  the  usage  of
this switch in not recommended in general and should only be defined if table reference
is not possible at all.

10.2.1  Configuration of Interrupt Vectors with IAR compiler
Instead  of a  manual  initialization  of  the  interrupt  vector  table  it  is  possible  to  let  the  IAR
compiler  set  up  the  table  by  using  the  #pragma  vector=xx  directive  (only  for  category  1
interrupts). This feature  can  be  enabled  via  the  user  configuration  file  by  defining  the  EI
level  interrupt  number  for  each  used  CAN  interrupt.  The  names  of  these  defines  are
derived from the corresponding ISR names.
See below an example for a full interrupt system with external wakeup support that uses
physical channels 2 and 5. Refer to the information in table 10-1 about the presence of the
individual CAN interrupt functions.

2015, Vector Informatik GmbH
Version: 1.08.00
37 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

#define C_CANISRRXFIFO_VECTOR         15
#define C_CANISRGLOBALSTATUS_VECTOR  14
#define C_CANISRTX_VECTOR_2           211
#define C_CANISRSTATUS_VECTOR_2       209
#define C_CANISRWAKEUP_VECTOR_2       31
#define C_CANISRTX_VECTOR_5           281
#define C_CANISRSTATUS_VECTOR_5       279
#define C_CANISRWAKEUP_VECTOR_5       36

Caution
This is an example and the necessary defines depend on the actual configuration. The
  interrupt numbers depend on the selected derivative; refer to the hardware manual to
get the respective values.

10.3  External CAN Interrupt Handling
There are several solutions if accesses to the EI level interrupt control registers (ICn) are
not possible or allowed for the driver (reasons may be restricted operating modes, memory
protection, bus guard functionalities or similar).
10.3.1  Hardware Access by Call-Back Functions
If the switch C_ENABLE_INTC_ACCESS_BY_APPL is defined via the user configuration file
the  driver  implementation  is  still  used  to  initialize  and  modify  all  ICn  as  described  in  the
previous sections, but all actual read and write accesses to the interrupt control registers
have to be performed by call-back functions.
The functions ApplCanWriteIcr8() and ApplCanReadIcr8() (see section 9.4 for the
API  definitions)  are  always  invoked  when  accessing  registers  of  the  interrupt  controller
(other  peripherals  are  not  accessed  by  the  driver).  These  functions  have  to  be
implemented by the application and perform the hardware access including any unlocking
mechanisms,  checks  for  the  given  addresses  or  similar.  It  is  expected  by  the  driver  that
every access is synchronous and always successfully performed.

Caution
An exclusive write access to the ICn as stated in the previous sections still has to be
  guaranteed.  If  any  access  is  not  successfully  performed  when  these  functions  are
called,  the  driver  has  to  be  re-initialized  by  calling  CanInitPowerOn()  as  correct
behavior cannot be ensured.

10.3.2  Interrupt Control by Application
If  an  exclusive  write  access  to the  CAN  related  ICn  is  not  possible  or  the  internal driver
mechanisms
that  are
described
above
are
not  applicable,
the
switch
C_ENABLE_OSEK_CAN_INTCTRL  can  be  defined  via  the  user  configuration  file.  In  this
case the application has to ensure proper initialization, disabling and restoring of the CAN
interrupt sources as the driver provides no support for these tasks at all. The registers of
the interrupt controller are never accessed by the driver.
2015, Vector Informatik GmbH
Version: 1.08.00
38 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

If  this  switch  is  defined  the  application  additionally  has  to  perform  the  initialization  of  all
necessary ICn before the call of CanInitPowerOn(). All used sources (see remarks in
table  10-1)  have  to  be  enabled  after  initialization  whereas  unused  sources  have  to  be
disabled.
In  context  of  the  CAN  interrupt  disable/restore  mechanism  the  driver  implements
application  call-back  functions  that  are  used  whenever  CanCanInterruptDisable()
or  CanCanInterruptRestore()  are  invoked  by  the  program  (see  section  9.4  for  the
API definitions). Suggestion is that the function OsCanCanInterruptDisable() saves
the value of the MK bit of the ICn of all used CAN interrupt sources that are linked to the
given  logical  channel  and  then  sets  these  MK  bits  to  1  in  order  to  disable  the  sources.
OsCanCanInterruptRestore()  should  restore  the  value  of  the  previously  saved  MK
bits for the given logical channel. Keep in mind that the right physical channel has to be
chosen based on the given logical channel (to get the right ICn) and that the receive FIFO
and global status interrupt are used by all channels, hence they should be disabled as long
as any channel’s interrupts are disabled.
If the Sleep/Wakeup functionality is enabled and the external wakeup is used please note
that the external wakeup interrupts always have to be disabled after initialization as these
sources are only enabled on demand. Also additional application call-back functions (see
section 9.4 for the API definitions) are invoked by the driver. This is relevant for interrupt
and polling systems as the external interrupt request flag has to be cleared independently
of the interrupt configuration.
ApplCanWakeupInterruptEnable()  is  always  invoked  in  context  of  CanSleep().
This function first has to clear the external interrupt request flag in the  corresponding ICn
and  then  –  only  if  wakeup  detection  is  performed  by  interrupts  –  enable  the  external
interrupt.  Keep  in  mind  that  depending  on  the  current  status  of  the  CAN  interrupt
disable/restore mechanism this has to be performed either by clearing the corresponding
mask bit in the respective hardware register or in the mask status that was saved by the
function  OsCanCanInterruptDisable().  ApplCanWakeupInterruptDisable()  is
only  invoked  if  wakeup  detection  is  performed  by  interrupts  in  context  of  CanWakeup(),
respectively  the  external  wakeup  handling,  and  in  CanInit().  This  function  has  to
disable the interrupt, depending on the current status of the CAN interrupt disable/restore
mechanism either by setting the corresponding mask bit in the hardware register or in the
saved  mask  status.  ApplCanWakeupOccurred()  is  called  in  context  of  the  function
CanWakeupTask() to check for the occurrence of a wakeup event (i.e. the presence of
the interrupt request flag) if the detection is performed by polling.
The implementation may differ but all CAN interrupts for the corresponding channel have
to  be  disabled  after  the  first  call  (keep  in  mind  that  nested  calls  can  occur)  of
OsCanCanInterruptDisable()  and  stay  disabled  until  the  last  nested  call  of
OsCanCanInterruptRestore()  that  has  to  restore  the  previous  interrupt  state.
ApplCanWakeupInterruptEnable()  and  ApplCanInterruptDisable()  have  to
enable and disable the wakeup interrupt for one channel but must not violate the general
CAN interrupt disable/restore mechanism. It is also important to clear the wakeup interrupt
request  flag  within  ApplCanWakeupInterruptEnable().  The  application  additionally
has to handle possible concurrent accesses to the ICn and ensure that those accesses do
not violate the conditions above.

2015, Vector Informatik GmbH
Version: 1.08.00
39 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

Caution
The  definition  of  C_ENABLE_INTC_ACCESS_BY_APPL  is  recommended  if  interrupt
  control registers cannot be accessed by the driver. If C_ENABLE_OSEK_CAN_INTCTRL
is defined the driver performs no measures to ensure consistency of the interrupt lock
mechanism. Additionally the application has to ensure correct concurrent accesses to
the  ICn  and  has  to  handle  nested  calls  of  OsCanCanInterruptDisable()  and
OsCanCanInterruptRestore().  Therefore  the  usage  of  this  switch  is  not
recommended in general and should only be defined if the internal driver mechanisms
or the definition of C_ENABLE_INTC_ACCESS_BY_APPL are not possible at all.

2015, Vector Informatik GmbH
Version: 1.08.00
40 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

11  Configuration
11.1  Configuration by GENy
The  driver  is  configured  with  the  help  of  the  configuration  tool  GENy.  This  section
describes  the  configuration  of  the  driver  specific  aspects.  The  configuration  options
common to all CAN drivers are described in TechnicalReference_CANDriver.pdf.

Note
To get further information please refer to the online help of the generation tool.

11.1.1  Platform Settings

Figure 11-1  GENy Platform Settings
Attribute
Supported
Description
Values
Preconfiguration

Select the pre-configuration file to use.
Micro
Hw_Rh850Cpu
Select the target platform.
Derivative
See Table 2-1
Select the specific derivative group.
Compiler
See Table 2-1
Select the used compiler.
Table 11-1   GENy Platform Settings

2015, Vector Informatik GmbH
Version: 1.08.00
41 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

11.1.2  Component Settings

Figure 11-2  GENy Component Settings
Attribute
Supported
Description
Values
CAN Interface
RSCAN,
Select the CAN interface that is incorporated by the used
RSCAN_FD
derivative - see the HW manual for information. This selection
is independent of the actual CAN-FD usage as the driver has
to handle general hardware differences for both variants.
Maximum number of
1 - 8
Enter the maximum number of physical CAN channels that
CAN channels
are supported by the used RSCAN unit of the actual
derivative. This value is independent from the number of
channels in the configuration but used to determine the
available hardware resources. Only if this value is correct the
tool can ensure valid configurations for the actual derivative.
Depending on the selected derivative not all values may be
available.
CAN external clock
true,
Enable this attribute to use the external clock input
source
false
(clk_xincan) as CAN clock (fCAN). If the attribute is disabled
clkc is used - this is the default selection. (This setting directly
affects the DCS bit in the global configuration register.)
Table 11-2   GENy Component Settings

2015, Vector Informatik GmbH
Version: 1.08.00
42 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

11.1.3  Channel-specific Settings

Figure 11-3  GENy Channel Specific Settings

Caution
The  sum  of  the  shared  buffers  used  to  allocate  the  receive  objects  over  all  channels
  must  not  exceed  (“Maximum  number  of  CAN  channels”    *  64)7.  This  includes  the  Rx
FullCAN  objects  (1  buffer  per  actually  assigned  object;  not  the  value  of  “Rx  FullCAN
object  allocation)  and  the  depth  of  all  Rx  BasicCAN  objects  (individually  configurable
amount of buffers, selected by the attribute “Rx Fifo depth”) on all channels.
The  sum  of  used  acceptance  filters  over  all  channels  must  not  exceed  (“Maximum
number of CAN channels” * 64)7. Each actually assigned Rx FullCAN object uses one
filter  and  each  Rx  BasicCAN  object  uses the  number  of filters  that  is  selected  by the
attribute “Filters per BasicCAN” on the corresponding channel.
The generation tool checks these and other restrictions (e.g. allowed selection for the
attribute “Physical controller”) to ensure valid configurations. Therefore it is mandatory
to enter a valid value for the attribute “Maximum number of CAN channels”7. Refer to
chapter 3 for additional information.


7 Refer to section 11.1.2 for the description of the attribute “Maximum number of CAN channels“.
2015, Vector Informatik GmbH
Version: 1.08.00
43 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

Attribute
Supported
Description
Values
BCFG
register value
The value for the Channel Configuration Register.
Acceptance Filter
-
Opens the acceptance filter dialog, see section 11.1.3.1. If
Configuration
several init structures are created this is only possible for the
first structure.
Bustiming
-
Opens the bustiming dialog to determine the value for BCFG,
Configuration
see section 11.1.3.2.
Physical controller
CAN 0 – CAN 7
Select the physical channel you want to assign to this logical
channel. The value is enumerated the same way as referenced
in the hardware manual. Depending on the selected derivative
and configuration of the attribute “Maximum number of CAN
channels” (see section 11.1.2) not all values may be available.
CAN interrupt priority  0 – 15
Select the interrupt priority level of this CAN channel’s interrupts
that are configured if the driver has interrupt control. Depending
on the selected derivative not all levels may be available. See
section 7.2.3 and chapter 10 for further information.
Rx FullCAN object
0 – nRXMBmax
You can configure as many receive FullCAN messages on this
allocation
channel as specified here. This value is used to limit the
selection for manual or automatic configuration - only the
actually arranged FullCAN objects will be configured in
hardware. The value of nRXMBmax equals “Maximum number
of CAN channels” * 16.
Filters per BasicCAN  1 – 128
Select how many acceptance filters will be assigned to each Rx
BasicCAN object on this channel; see section 11.1.3.1 for
details. Depending on the selected derivative not all values may
be available.
Rx Fifo process count  2 – 255
Select the maximum number of pending receive messages that
are processed for each Rx BasicCAN object within one polling
cycle respectively one interrupt occurrence. By adjusting this
value it can be ensured that high FIFO loads will be evenly
processed by the driver. Remaining messages are processed
within the next polling cycle respectively the interrupt of the next
received message on this channel. Select greater values if
overruns occur.
Rx Fifo depth
4, 8, 16, 32,
Individually configure the depth (amount of assigned shared
48, 64, 128
buffers) of every Rx FIFO, that is used as Rx BasicCAN object
on this channel.
Table 11-3   GENy Channel Specific Settings

Note
As  the  RSCAN  has  restrictions  regarding  the  receive  buffers  (e.g.  no  interrupt
  processing,  no  overrun  detection)  also  consider  configurations  without  Rx  FullCAN
objects. The large FIFO sizes and amount of filters that are possible for the BasicCAN
objects  give  similar  advantages  as  the  usage  of  FullCAN  objects.  For  many
configurations  this  can  be  an  alternative  that  above  all  is  more  effective  regarding
runtime and memory usage.

2015, Vector Informatik GmbH
Version: 1.08.00
44 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

11.1.3.1  Acceptance Filter Configuration

Figure 11-4  GENy Acceptance Filter Configuration
Attribute
Supported
Description
Values
Acceptance Filter
representation of
The configured BasicCAN filters are shown. Each ID-bit is
type, mask and
represented by “0/1/X”, meaning must match “0”, “1” or don’t
code
care “X”. The number of filters can be adjusted by the attribute
“Filters per BasicCAN” on the channel view.
Type
standard,
Select if the filter shall apply to standard or extended ID types.
extended
(Based on the database and configuration only one type may
be available.)
Mask / Code
register values
The register values for this filter that will be configured in
hardware.
Open filters
-
Open the filters completely to receive all messages.
Optimize
-
Configure the filters automatically to just receive IDs in the
database if possible. A large number of filters allow better
optimizations, but don’t configure more filters than the
optimization algorithm uses for message distribution.
“Use FullCAN” tries to put as many messages as possible in
FullCAN objects. Select the maximum number of available
objects by adjusting the attribute “Rx FullCAN object
allocation” on the channel view. This is useful when only a few
number of BasicCAN filters are configured for example.
Table 11-4   GENy Acceptance Filter Configuration
2015, Vector Informatik GmbH
Version: 1.08.00
45 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

11.1.3.1.1  Additional information if the feature “Multiple BasicCAN objects” is used
The dialog shows all BasicCAN acceptance filters for the respective channel. The amount
of filters equals the product of configured BasicCAN objects and the number of filters per
BasicCAN.  An  example  configuration  with  3  BasicCAN  objects  and  2  filters  per  object
results in 6 filters as shown in figure 11-5. The first 2 filters (in accordance with the attribute
“Filters per BasicCAN”) are assigned to the first BasicCAN object, the next 2 to the second
BasicCAN object and so on.

Figure 11-5  GENy Acceptance Filter Assignment
Please note that  a received message is stored in  the first  mailbox with a matching filter.
After  an  identifier  was  compared  against  the  FullCAN  filters,  it  is  compared  against  the
BasicCAN filters in the order that is depicted in the dialog. This has to be considered when
the  feature  “Multiple  BasicCAN  objects”  is  used.  If  filter  number  1  in  the  example  from
figure 11-5 was open (all bits “don’t care”), all non FullCAN standard identifiers would be
received by BasicCAN0 and BasicCAN2 would never receive any message.

Note
In  some  “Multiple  BasicCAN”  configurations  it  may  be  useful  to  assign  certain
  BasicCAN  messages  to  specific  hardware  objects  as  the  FIFO  depths  or  “Individual
Polling” settings can be adapted to the actual communication aspects for example. As
the  optimization  algorithms  don’t  consider  this  use  case  the  filters  have  to  be  edited
manually in this case.
Alternatively it is possible to configure and lock only several significant filters and then
use the optimization functionality. But after doing so always check the result because
manually configured filters may not always receive the pre-assigned identifiers as the
message could match an automatically assigned filter that is compared first. Focus on
filters with smaller numbers or add some “dummy filters” for earlier objects to achieve
better results.

2015, Vector Informatik GmbH
Version: 1.08.00
46 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

11.1.3.2  Bustiming Configuration

Figure 11-6  GENy Bustiming Configuration
Attribute
Supported
Description
Values
Clock
CAN clock
Set the clock frequency that is provided to the CAN cell for
baudrate generation (fCAN). Consider the setting of the
attribute “CAN external clock source” (see section 11.1.2).
Baudrate
baudrate
Set the baudrate to be used for this channel.
CAN BTR register
register value
Enter the value for the Channel Configuration Register (see
attribute BCFG in section 11.1.3).
Calculate
-
Calculate possible Channel Configuration Register settings
out of the entered baudrate or vice versa.
CAN_BTR, Sample,
-
Select specific channel configuration register values to adapt
BTL cycles, SJW
the sample point and sync phase to comply with your bus
physics.
Table 11-5   GENy Bustiming Configuration
2015, Vector Informatik GmbH
Version: 1.08.00
47 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

11.2  Manual Configuration
This section describes additional configuration options for special features that can only be
configured via the user configuration file.
  Define  C_DISABLE_NESTED_INTERRUPTS  or  C_ENABLE_NESTED_INTERRUPTS  to
control the nesting of the CAN interrupts. See section 10.1 for further information.
  Define  C_ENABLE_DIRECT_INTERRUPT_BRANCH  (and  if  needed  additionally
C_ENABLE_ISRVOID)  to  deactivate  table  reference  as  the  method  to  handle  CAN
interrupts. See section 10.2 for further information.
  Define  C_ENABLE_INTC_ACCESS_BY_APPL  or  C_ENABLE_OSEK_CAN_INTCTRL  to
prohibit  read  and  write  accesses  within  the  interrupt  controller  address  space.  See
section 10.3 for further information.
  Define C_ENABLE_EXTERNAL_WAKEUP_SUPPRESSION to disable the external wakeup
functionality. See chapter 4 for further information.
  See sections 7.2.6 to 7.2.9 for options that control different RAM test features.
  See  section  10.2.1  for  information  on  how  to  set  up  the  interrupt  vector  table  when
using IAR compiler.
2015, Vector Informatik GmbH
Version: 1.08.00
48 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

12  Known Issues / Limitations
1.  Due  to  hardware  limitations  the  feature  CAN  RAM  check  is  not  supported  for  receive
mailboxes (no write access is possible for these objects).
2.  Due to hardware limitations receive FullCANs cannot be processed in interrupt context
and no overruns can be detected for these objects.
3.  With  default  configuration  the  driver  needs  exclusive  write  access  to  all  EI  level
interrupt control registers (ICn) that are related to a CAN interrupt source (see section
7.2.3 and chapter 10 for further information.).
4.  Refer  to  chapter  4  for  restrictions  when  using  the  Sleep/Wakeup  functionality.
Additionally the global stop mode of the RSCAN is not supported.
5.  When using multiple initialization structures no multiple acceptance filter configurations
are  supported  by  the  driver.  The  filter  settings  are  always  derived  from  the  first
structure. Use several structures only to arrange multiple baudrate configurations.
6.  When using the feature Multiple ECU Configurations it is not supported to use a logical
channel in more than one identity. The only exception is the first logical channel which
can be present in any identity if it is also mapped to the physical channel CAN0. This
limitation  does  not  apply  to  the  usage  of  physical  channels:  Every  available  physical
channel can be used in any identity and the same physical channel can be used in as
many identities as needed (if it is referenced by different logical channels).
7.  For  derivatives  that  incorporate  multiple  RSCAN  units  only  the  first  one  (RSCAN0)  is
supported by the driver.

For  latest  information  about  issues  or  limitations  of  the  actually  used  derivative  please
contact the hardware manufacturer.

2015, Vector Informatik GmbH
Version: 1.08.00
49 /50
based on template version 3.2

Vector CAN Driver Technical Reference RH850 RSCAN

13  Contact
Visit our website for more information on

>  News
>  Products
>  Demo software
>  Support
>  Training data
>  Addresses

www.vector.com

2015, Vector Informatik GmbH
Version: 1.08.00
50 /50
based on template version 3.2

Document Outline

9 - UserManual_CanDriver

User Manual

10 - UserManual_CanDriver_ind

11 - UserManual_CanDrivers

Vector CAN Driver
User Manual
(Your First Steps)

Version 2.4

Vector Informatik GmbH, Ingersheimer 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 Vector CAN Driver

2 / 56

Higher layer components
CAN Driver
CAN Controller
Transceiver
CAN
Message Transmission - Reception

Authors: Klaus Emmert
Version:
2.4
Status:
released (in preparation/completed/inspected/released)

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

3 / 56
History
Author
Date
Version
Remarks
Klaus Emmert
2001-05-11
0.1
First version of the User Manual
Klaus Emmert
2001-08-11
0.4
Technical and linguistic revision
Klaus Emmert
2001-09.21
0.6
Revision (pretransmit)
Klaus Emmert
2001-10-10
0.6a
Error in description of a mes-
sage, how to enter the manufac-
turer type to the example data
base.
Klaus Emmert
2001-12-14
1.0
Linguistic revision
Klaus Emmert
2002-09-25
1.4
Linguistic corrections and little
adaptations
Klaus Emmert
2003-07-16
1.5
Warning added for example code
usage
Klaus Emmert
2004-10-26
1.6
New Layout, example dbc file
deleted and description modified,
description for CANgen and the
new Generation Tool GENy, new
Symbols
Klaus Emmert
2006-05-30
1.7
Updated dialog for bus timing
register setup
Klaus Emmert
2006-09-08
1.8
Page number of Index, headline
numbering
Klaus Emmert
2007-02-20
1.9
Issues in Word Hyperlinks
Klaus Emmert
2007-07-26
2.0
Issues in steps introduction,
some typos.
Klaus Emmert
2007-09-06
2.1
Typos and reference in TOC
Klaus Emmert
2007-10-29
2.2
Baudrate setting description
Klaus Emmert
2008-09-04
2.3
Include file for CAN Driver and
GENy
Klaus Emmert
2009-08-26
2.4
Fix: v_inc.h must not be changed
manually.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

4 / 56
Motivation For This Work
The CAN Driver is the only component among the CANbedded Software Compo-
nents that is directly connected with the CAN Controller hardware. It is the founda-
tion for all other CANbedded Software Components.
The first target for you is to get the CAN Driver running, to see receive and transmit
messages on the bus.

WARNING
All application code in any of the Vector User Manuals is for training pur-
poses only. They are slightly tested and designed to understand the basic
idea of using a certain component or a set of components.

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

8 /  56
1  Welcome to the CAN Driver User Manual
1.1
Beginners with the CAN Driver start here ?
You need some information about this document?
  Æ see Chapter 2
Getting started                                                   Æ see Chapter 3
9 Steps for the CAN Driver                                      Æ see Chapter 6

1.2
For Advanced Users
Start reading here.                                              Æ see Chapter 5


1.3
Special topics
Strategies for receiving a CAN message                       Æ see Chapter 6.9.1
Strategies for sending a CAN message                        Æ see Chapter 6.9.2
An exercise                                                      Æ see Chapter 7.1

1.4
Documents this one refers to…
TechnicalReference_CANDriver.pdf
TechnicalReference_CAN_xxx.pdf

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

9 / 56
2 About This Document
This document gives you an understanding of the CAN Driver. You will receive
general information, a step-by-step tutorial on how to include and use the function-
alities of the CAN Driver.
For more detailed information about the CAN Driver and its API refer to the Technical
Reference (TechnicalReference_CANDriver.pdf) and the hardware specific refer-
ences TechnicalReference_CAN_xxx.pdf (e.g. TechnicalReference_CAN_HC12.pdf).
2.1
How This Documentation Is Set-Up
Chapter
Content
Chapter 1
The welcome page is to navigate in the document. The main parts of the document
can be accessed from here via hyperlinks.
Chapter 2
It contains some formal information about this document, an explanation of legends
and symbols.
Chapter 3
An introduction to the files, the tools and information necessary to understand the
descriptions in the following chapters.
Chapter 4
Here you find some more insight in the CAN Driver about receiving and transmitting
messages, the CAN controllers and the data structure.
Chapter 5
A step-by-step guide to establish CAN communication on an ECU for the first time.
Follow the 9 steps to get the answer to most of your questions and problems..
Chapter 6
Here you find a problem to solve to check your understanding of the CAN Driver and
its functions.
Chapter 7
In this last chapter there is a list of experiences with the CAN Driver.

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

10 / 56
2.2
Legend and Explanation of Symbols
You find these symbols at the right side of the document. They indicate special ar-
eas in the text. Here is a list of their meaning.
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
explanati-
greatly simplify your search for topics.
topics.
The footprints will lead you through the steps until you can use the described Vector
CAN Driver.

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).

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

11 / 56
3 ECUs and Vector CANbedded Components – An Overall View
3.1
Network Data Base File (DBC)
Normally the different ECUs in a modern vehicle are developed by different suppli-
ers (SUPPLIER X). All ECUs within the same bus system ( n or o) use the same
data base (dbc file) to guarantee that the ECUs will work together later on in the
vehicle.
SUPPLIER 1
SUPPLIER 6
SUPPLIER 2
SUPPLIER 5
Network Database
n All_ECUs_highspeed.dbc
n Powertrain
o All_ECUs_midspeed.dbc
o BodyCAN
SUPPLIER 4
SUPPLIER 3

Figure 3-1 A Modern Vehicle With Body CAN And PowerTrain Bus
The dbc file is designed by the vehicle manufacturer and distributed to all suppliers
There is the same
dbc file per bus
that develop an ECU. Thus every supplier uses the SAME dbc file for one vehicle
system (high
speed, low
platform and one bus system (powertrain, body CAN etc.) to guarantee a common
speed, etc) for all
basis for development.
suppliers to
guarantee a
common basis for
The dbc file contains e.g. information about every node in the network, the mes-
development.
sages/signals each node has to send or to receive. The distribution of the signals
among the messages is stored in the DBC file, too.
For example: every ECU has to know that a 1 in bit 7 in the 4th byte of the message
0x305 means “Ignition Key” on/off.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

12 / 56
4 CANbedded Software Components
The vector CANbedded environment consists of a number of adaptive source code
components that cover the basic communication and diagnostics requirements in
automotive applications.

Figure 4-1 CANbedded Software Components
CAN Driver
The CAN Driver handles the hardware specific CAN chip characters and provides a standardized
application interface.
Interaction Layer
The Interaction Layer (IL for short) is responsible for the transmission of messages according to
specified rules, monitoring receive messages, timeout monitoring, etc. It provides a signal oriented
application interface for the application.
Transport Protocol
The CAN protocol is restricted to 8 data bytes per message. But in some cases (e.g. diagnostics)
you need to exchange much more than 8 data bytes. The segmentation of the data, the monitoring
of the messages and the timeouts is done by the Transport Protocol (TP for short).
Diagnostics
Diagnostics Layer according to ISO14229 / ISO14230 (Keyword Protocol 2000).
Network Management
The Network Management (NM for short) is the component to control the bus, to synchronize the
transition to bus sleep, error recovery after bus-off, etc.
Communication Control Layer (CCL)
The CCL provides an integration environment for the CANbedded Software Components, an ab-
straction for different vehicle manufacturers, microcontrollers, CAN Controllers and compil-
ers/linkers. It also provides a global debug mechanism.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

13 / 56
Universal Measurement and Calibration Protocol (XCP)
This is the Software Component for measurement and calibration on several bus systems. To men-
tion some feature: read and write access to various memory locations or flash programming.
Generation Tool
This is a PC tool for configuring the above listed components. The Generation Tool is driven by a
network database file, DBC file for short.

The CANbedded Software Components are configurable and can be adapted to
your specific needs via the Generation Tool.

4.1
Generation Tool
The Generation Tool displays the complete set of ECUs in the network. In general
you pick out the one you develop the software for. In special cases when you de-
velop ECUs that are almost identical (e.g. door ECUs) you select more than one
(so-called multiple ECUs).
For  your ECU there are special requirements concerning the hardware and the
functionality. I.e. the driver must be suitable for your hardware and the standard
components must be adaptable for your project-specific needs. The means to do
this is the Generation Tool.
The Generation Tool is a PC-Tool. It reads in the Network Data Base file (DBC)
and offers you to select the node you are going to develop and has therefore all
information about your ECU, the receive and transmit messages, the signals etc.
The Generation Tool generates files that contain this information (DBC, hardware
and specific settings) and so complete the components core files and have to be
Include the
generated
included in the compile and link process.
files in your
system as
shown.
You must not
Your Hardware Platform-
change the
and Compiler information
Application
generated
files by hand
Project specific  component settings
Specific Data
– the  next
generation
process will

delete these
changes.
Right now there are two Generation Tools available, CANgen and the new Genera-
tion Tool called GENy. Which tool you have to use depends on you delivery and the
project.

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

14 / 56
4.2
The Vector CAN Driver
A driver is a program to control a piece of hardware. In this case the Vector CAN
Driver controls the CAN Controller and its registers.
4.2.1  Tasks of The Vector CAN Driver
The CAN Driver basically handles the reception and transmission of information via
the CAN Bus and recognizes bus failure (bus off). The CAN Driver provides a
standard application interface for the application.
Your application only has to use a set of predefined functions to control the CAN
Driver and will be notified via interrupt about incoming information (messages). To
control the incoming and outgoing data and to be notified of important events you
have to add some service- and call-back-functions to your application (see  6.5).
For more detailed information about the CAN Driver please refer to the Vector CAN
Driver Technical Reference (TechnicalReference_CANDriver.pdf and TechnicalRe-
ferfence_CAN_<hardwareplatform>.pdf, e.g. TechnicalReference_CAN_HC12.pdf).

4.2.2  Vector CAN Driver Files
The Vector CAN Driver consists of 3 sets of files, component files, generated files
and configurable files
4.2.2.1
Component Files
Independent of the used Generation Tool
can_drv.c - can_def.h - v_def.h
You must not change these files at all.

4.2.2.2
Generated Files
Independent of the used Generation Tool
can_cfg.h - v_cfg.h
Only for CANgen
YourECU.c - YourECU.h
Only for GENy
can_par.c - can_par.h - drv_par.c - drv_par.h - v_par.h - v_par.c - v_inc.h

Do not change these files. You will lose the changes after the next generation proc-
ess.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

15 / 56

4.2.2.3
Configurable files
Independent of the used Generation Tool
can_inc.h
INC stands for include. Here you can add includes you need.. You have to include
can_inc.h in every application C file where you need CAN functionality, followed by
the include of YourECU.h.
The Generation Tool CANgen generates the signal and message access macros
as well as the indication or confirmation flags to the file YourECU.h. GENy gener-
ates this to the file can_par.h.

4.2.3  Include The CAN Driver Into Your Application
Use the illustration in Figure  4-2 to include the files for the CAN Driver into your
application correctly. Please keep to the including order to avoid errors while com-
piling or linking.

Figure  4-2  Order For Including Files

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

16 / 56
5  Vector CAN Driver– A More Detailed View
You access the
signals   relevant
for your ECU with
the macros
5.1
Information Package on the CAN Bus
generated by the
Generation Tool.

As mentioned before, the information is exchanged between ECUs via the CAN
The generated
bus. The maximum amount of data which can be exchanged is 8 data bytes and
file sig_test.c
they are transmitted via a so-called message.
contains a list of
all access macros
to the signals.
A message contains the ID (the “name” or number of the message), the DLC (data
length code, i.e., the number of data bytes) and the data bytes .
A message on the CAN Bus can contain from 0 to 8 data bytes.
Every message is divided up into signals. A signal consists of 1 up to 64 bits. A
signal cannot exceed the message boundary.
We do not consider signals here which are greater than 64 bits, as this involves the
Transport Protocol.

Message
ID DLC
DL
0x01 0x12
Signal
(1 Bit to 8 Bytes) 0x01 0x12
e.g. Temperature,
(hi, low
(hi, lo )
A signal can
l ca  exceed
exce
byte boundaries
rie

Figure  5-1  Message and Signal
Signals are assigned to messages by the vehicle manufacturer database engineer.
This assignment is stored in the database (dbc file).
Normally you must not change the database (dbc file).

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

17 / 56
5.2
Storing Information Packages
The more you understand about data handling in the CAN Driver the better you are
able to design your application. You have to know where the data is stored at a
specific point in time to be able to access this data correctly.
Notification for
Application
RAM buffer
Temp
Ignition
Copy to RAM buffer depending on ID.
Door_S
or_ tate
Keep data consistent!
CAN Driver
Rx register
ID DLC
Transceiver
CAN messages
CAN messages

Figure 5-2 Rx Register, Data Structure and Notification

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

18 / 56
Updated by Application
RAM buffer
Temp
Ignit
Igni ion
Door_
Door State
CanTransmit (TxHandle)
CAN Driver
Copy data to Tx register.
Tx register
Keep data consistent!
ID DLC
Transceiver
CAN messages
CAN messages

Figure  5-3  Tx Register, Data Structure and CanTransmit
There are 3 elements involved in storing information packages:
5.2.1  The Registers of the CAN Controller
Your CAN Controller has a receive register (Rx Register) and a transmit register
(Tx Register).
Later on you will
Data is always received in the Rx Register of the controller. The data is written to
see, that this
special access to
the Tx Register immediately before a transmission.
the hardware is
possible only in
the functions
You can access these two registers via the signal access macros containing the
ApplCanMsgRe-
_CAN_ in the name (see YourECU.h if you use CANgen and can_par.h if you use
ceived and in the
Precopy Func-
GENy).
tions for reception
and in the Pre-
transmit Function
for transmission.
The signal access to the Tx Register is dependent on the hardware, not all drivers
support this feature.
5.2.2  The Data Structure Generated by the Generation Tool for Storing Mes-
sage Data.
The Generation Tool defines variables to allocate memory for the data of the re-
ceive messages and the transmit messages (The data allocation is optional and
can be switched off). In the receive procedure, the data will be copied from the Rx
Register to the message-specific memory area (RAM). In the transmit procedure,
you have to enter the current values in the variables and the driver will copy the
data to the Tx Register as shown in Figure  5-2 and Figure  5-3.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

19 / 56
The decision, whether to copy the data to or from the registers (receive and transmit)
with your own function or whether you let the driver do the copying action is up to
you and is decided by the return value of specific functions (precopy function, pre-
transmit function, see  6.9).
The Generation Tool optimizes the memory consumption. The highest byte con-
taining relevant signals determines the amount of bytes to be reserved for this
message. In the picture below, the red areas and lines in the bytes show where
relevant signal information is stored within the message.

4 bytes
The Generation
Tool minimizes
8 bytes
the amount of

memory reserved
for a message.
Figure  5-4  Memory optimization by the Generation Tool

In the first message the 3rd byte contains the last signal (counting started with 0).
Byte 4, 5, 6 and 7 have no relevant information for your ECU. In this case the Gen-
eration Tool only reserves 4 (0-3) bytes for this message.
The second message has information in the 7th byte, so the number of byte to be
reserved is 8 (0-7).
5.2.3  Memory the Application Reserved for Signals.
Sometimes you only need one byte or even only one bit signal out of a message.
To save RAM memory do not use a generated data structure. Use the precopy
function (see  6.9.1.5) to copy the byte or the bit of the received message to the
byte or the bit field you reserved in your application to hold this specific information.

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

20 / 56
6  CAN Driver in 9 Steps
STEP 1 :   UNPACK THE DELIVERY
Follow the install shield, unpack the delivery and install the generation tool.

STEP 2:   GENERATION TOOL AND DBC FILE
Configure the CAN Driver using the generation tool and an appropriate data base file
(DBC)..

STEP 3:  GENERATE FILES
The generation tool generates all necessary files for the CAN Driver.

STEP 4:   ADD FILES TO YOUR APPLICATION PROJECT
To use the CAN Driver you have to add the CAN Driver files to your application project.

STEP 5:   ADAPTATIONS FOR YOUR APPLICATION
Also adapt your application files to be able to use the functionality of the CAN Driver.

STEP 6:   COMPILE AND LINK
Compile and Link your application project including the CAN Driver.

STEP 7:   RECEPTION OF A CAN MESSAGE
Test the receiving path of the CAN Driver by sending a message to your ECU.

STEP 8:   TRANSMISSION OF A CAN MESSAGE
Transmit your first CAN message using the CAN Driver service functions.

STEP 9:   FURTHER ACTIONS AND SETTINGS
Topics above the very easy beginning.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

21 / 56
6.1
STEP 1 Unpack the Delivery
The delivery of CANbedded Software Components normally comprises a Genera-
tion Tool and the source code of the software components.
The Generation
Tool generates
You only have to start the
files for your
application. It is
…_Setup.exe
the connection
between your
hardware and
and to follow the install shield wizard.
settings, the
requirements of
your vehicle
manufacturer and
We recommend creating a shortcut to the Generation Tool.
the other ECUs,
your ECU has to
communicate

with.

Back to 9 Steps overview

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

22 / 56
6.2
STEP 2 Generation Tool and dbc File
Use new Generation Tool GENy, look there >>
6.2.1  Using CANgen as Generation Tool
When you start the Generation Tool you will see a window like Figure   6-1. This
starting window is the main window of the Generation Tool.

Figure  6-1  Add a dbc file
A click on the green plus (+) will open a new window to add your database (dbc
file).
When you use
the browse-button
you will get an
absolute path to
the dbc file.
It is suggested
that you use
relative paths in
order to be able
to move your
project more
easily from one
directory to
another.
This warning
occurs only if you

open the dbc.file
Figure
for the first time
6-2  Warning – do not bother
because of the
extension file has
Browse for your dbc file and select it. When you do this for the first time, the Warn-
still not been
created. The
ing above will occur. Ignore it, and just confirm with OK..
extension file will
contain your
Select your node; choose your target system and compiler.
settings you do in
the following.
Since we are using a CAN Driver with just one channel, the channel index has to be
left empty. When you have two or more channels, they will be distinguished via this
index.

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

23 / 56
The Name field is
set to the name of
the dbc file. You
can change the
name . It is only
used in the list of
your channels in
figure 2-5.

Figure  6-3 Channel properties
Confirm with OK and you will see your setting as text in the field of the starting win-
dow of the Generation Tool. When we save the configuration for the first time, we
have to use the menu command File/Save as.

Figure  6-4  Save Setting For The First Time
Take a look at the directory where you stored the settings of the Generation Tool.
There is your dbc file and new files (see note) only used by the Tool.
The following files belong to the Generation Tool:

<databasename>.dbc
(exampleDRV.dbc)
<databasename>.ext
(exampleDRV.ext)
<databasename_nodename>.msg
(exampleDRV_YourECU.msg)
<databasename_nodename>.sig (exampleDRV_YourECU.sig)
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

24 / 56
(<databasename_nodename>.fms (exampleDRV_YourECU.fms))
fms only when using a full CAN controller.
yourECU.ccf
this is the project file for the Generation
Tool.

Now you can open your settings in the normal way (not via the dbc file) by opening
the file YourECU.ccf.
When your vehicle manufacturer changes the dbc file, just copy all files important for
the Generation Tool into a new directory, delete the old dbc file and copy the new dbc
file in this new directory. Rename the old ext file with the name of the new dbc file.
This preserves your application-specific settings.
The checkbox
Generate only bit
and byte signal
This does not work when the target system has changed!!!
macros is only
used for very
special applica-
tions. If you have

any doubt, do not
choose this.
Now we shall make additional settings for the component CAN Driver. Use this but-
ton[
] to open the Generation Options and to enter the following dialog.

Figure 6-5 Overview of Signals and Directories
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

25 / 56
In the overview tab page (Figure  6-5) you see all receive and send messages for
your node.
Just choose the path where the header and the C file are to be generated and the
path for the configuration file can_cfg.h.
Select the tab CAN Driver.
In the following dialog you can make settings that are the same for all CAN drivers
regardless of the hardware platform. For the first attempt we do not select anything.
Here you see the
variety of setting
you can make to
configure a CAN
Driver. Take a
look at it but do
not enter anything
for this first
attempt.

Refer to the
document
CANdrv.doc to
get further infor-
mation about
these settings.

Figure  6-6  CAN Driver Dialog (for HC12)
The next tab, CAN driver (advanced) is very special for the specific vehicle manufac-
turer and the hardware platform. Please refer to the description of your CAN Driver
Technical Reference for the advanced settings (TechnicalRefer-
ence_CAN_hardwareplatform.pdf).
Finally we have to set the Init registers. Please select this tab (Figure  6-7).
Some of the following information might be hardware dependent but the fundamental
mechanisms are the same.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

26 / 56
Every two col-
umns belong to
one so-called init
structure consist-
ing of baud rate,
acceptance
filters…

Figure 6-7 Init Registers For The CAN Controller (for HC12)
This is a very important dialog. Please pay special attention to these settings.
Here is where you can make the settings for the hardware acceptance filters and
the bus timing of your CAN Controller.
First we look at the Acceptance filters, second at the Bustiming registers.
In order to minimize the number of messages that should not be received by your
ECU, you can set a hardware filter by means of the acceptance register (1) (see
Figure 6-8).
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

27 / 56
The reception of any message normally causes an interrupt. To minimize the inter-
rupt load you set the filters, so only relevant message will pass and cause an inter-
rupt.

Figure 6-8 Acceptance Filters For The CAN Controller (for HC12)
For the first attempt it is your choice whether to open all filter via the Open filters or
you use the Optimize filters button. Confirm with OK.
The setting of the filters is described in detail in the help document for the Generation
Tool. (just use the HELP button).
Next we will look at the bus timing. To do this, while still on the Init registers tab
page, click on the Bustiming registers button.
Incorrect Bus Timing settings are common mistakes that cause errors while transmis-
sion and reception. Please pay special attention to all settings in this dialog.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

28 / 56

Figure 6-9 Bus Timing Register Settings

Caution
Before SOP it is duty of the OEM / Tier1 supplier to recalculate and validate these
automatically calculated values for the bus timing registers.

First you have to enter the clock signal frequency. This is the base for further calcu-
lating the timing registers. Make sure to select the correct frequency.
The Bus Timing Registers of any CAN controller contain information about the bus
rate, the synchronization jump width (SJW) and the BTL cycles. There are two
ways to make these setting:
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

29 / 56
1.  Do you know the baud rate ?
Enter the baud rate and click on Calculate bustiming registers. You will get a
list of possible register setting. Choose your setting by a click in the list.
Between 60 and 80% is a good value for the Sample Rate and the SJW for your se-
lection. All vehicle manufacturers have strict guidelines for these settings.
2.  You can also simply enter values for the two bus timing registers (CBT0 and
CBT1) and let the software calculate the baud rate.
Return to the Init registers dialog via OK and see the changed values.
With a further OK you return to the main window of the Generation Tool.

Make sure that the checkboxes Use TP, Use diagnosis, Use Can Calibration
Protocol, Use MCNet … are NOT selected (as we are working with the CAN
Driver only for this example).
The variety of these buttons is dependent on the manufacturer. Deactivate any com-
ponent but the CAN Driver.

Figure  6-10 TP Options
The figure is only an example. The screenshot may look very different in your case.
But you see the checkbox which must not be selected.

Read the following chapter if you use GENy.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

30 / 56
6.2.2  Using GENy, the new Generation Tool
The following first steps with the Generation Tool are described in details in the online
help of the Generation Tool GENy, too.
Start the Generation Tool and setup a new configuration. Via File/New you open
the Setup Dialog Window. Select License, Compiler, Micro and Derivative (if avail-
able) and confirm via [OK]. Then open the Channel Setup Window via the green
plus and the selection of the underlying bus system (CAN or LIN).

Figure  6-11 Setup Dialog Window and Channel Setup Window to Create a New Configuration
The channel name is Channel X per default (X is starting with 1). Use the browse
functionality to enter the location of the data base (dbc file).
Select your node out of the field Database Nodes and confirm the settings with
[OK].
Now save the configuration via File/Save or File/Save as.
First at all you should switch on/off the components you need, in this case we only
use the CAN Driver.
Use the component selection at the bottom of the main window of the Generation
Tool and select the suitable Driver (in this example application we use the
CPUHC12 and the Driver HC12).

Figure  6-12 Component Selection

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

31 / 56
Now you should set the path where the Generation Tool generated the files to. To
do this, open the Generation Directories Window via Configuration/Generation
Paths. Enter the root path and select additionally individual paths for the compo-
nents, if the Generation Tool should generated the files to different folders. This is
also described very detailed in the GENy online help.
For the HC12 there are some hardware-specific settings that you have to make,
the register block address and the register block offset. It depends on you hard-
ware whether you have to do such kind of settings or not. Refer to the Technical-
Reference_CAN_YourHardware.pdf for more information.

Figure 6-13 The Register Block Address is a General Setting for the CPU

Figure 6-14 Register Block Offset, Acceptance Filters and Bus Timing are Channel-Specific Settings for the CPU
What is missing now is the settings for the acceptance filters and the bus timing.
Acceptance filter configuration and bus timing configuration are very important set-
tings. Please pay special attention to them.
As you see in the navigation tree above you can open the configuration windows
for these two settings via the channels of the hardware (e.g. CPUHC12).
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

32 / 56
First we take a look at the Acceptance filters, second at the Bustiming registers.
In order to minimize the number of messages that should not be received by your
ECU, you can set a hardware filter by means of the acceptance register.

Figure 6-15 Acceptance Filter Settings Window of GENy
The reception of any message normally causes an interrupt. To minimize the inter-
rupt load you set the filters, so only relevant message will pass and cause an inter-
rupt.
For the first attempt it is your choice whether to open all filter via the Open filters
or you use the Optimize filters button. Confirm with [OK].
The window for the bus timing registers is the same as for the CANgen Generation
Tool. Refer to the lines above for this explanation.
To make the settings for the component CAN Driver itself use the lists below Driv-
erHC12 and DriverHC12/Channels/Channel 1. But for the this first attempt leave
these driver settings on their default values.

Back to 9 Steps overview

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

33 / 56
6.3
STEP 3 Generate Files
6.3.1  Using CANgen Generation Tool
Click on the button
and start the generation process.

Remember to
start the genera-
tion process after
any change in the
dialog windows of
the Generation
Tool.

Figure  6-16 Generation Process

The double arrow is only available if you have a multi-channel CAN Driver distin-
guished via the Channel index.
Now we have generated for the first time. Check the directory and see the new
files. There should be at least the files YourECU.c and YourECU.h, and in the path
for the configuration file there should be can_cfg.h and v_cfg.h.
If you do not find the generated files check your path in the Overview dialog.

6.3.2  Using GENy
Click on the button
and start the generation process.

Figure  6-17 Information About the Generated Files and the Generation Process
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

34 / 56
The Generation Tool provides you with information about the Generated Files and
Generation information. In this example shown above the acceptance filters are
not set correctly, Message_2 will not pass the filter. Open or optimize the filters.
If a message will not pass the acceptance filters, the Generation Tool will not create
signal access macros for the hardware (_CAN_ see in chapter 5.2.1). Make sure that
the generation process runs without error messages.
Now we have generated for the first time. Check the directory and see the new
files: can_par.c, can_par.h, drv_par.c, drv_par.h, can_cfg.h, v_par.c, v_par.h,
v_cfg.h, v_inc.h.
If you do not find the files check the paths in the Generation Paths… dialog.

Back to 9 Steps overview

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

35 / 56
6.4
STEP 4 Add Files to your Application
In this step you have to add all files of the CANbedded Software Components (In
this example these files are only the ones for the CAN Driver) and the generated
ones to your project (or makefile).
Rename the file _can_inc.h to can_inc.h (remove the underscore prefix) and open
it with an appropriate editor. As you do not use any other component but the CAN
Driver you should delete the #include of the Network Management (nm_cfg.h) at
the end of this file.
If you want to use functions of the CAN Driver or you want to access signals or mes-
sages, you only have to include the can_inc.h and then the YourECU.h for CANgen
and v_inc.h for using GENy.
Now add the driver files to your source list for your compiler or your makefile.
If you want to apply changes you have made in the Generation Tool, you must start
the generation process again. Remember compiling afterwards.
!!! We are still not able to compile and link. !!!
The starting point for this example is a very simple application consisting of only
one file (here applmain) and an interrupt vector table (vectors.c). It should give you
an idea of how to handle the service- and callback functions of the CAN Driver.
In the following chapters we complete this example step by step.
This example was created for using CANgen. For the usage of GENy you just have
to include the v_inc.h.

Example for HC12:
|-------------------------------------------------------------------
| A U T H O R I D E N T I T Y
|-------------------------------------------------------------------
| Initials Name Company
| -------- --------------------- ---------------------------
| em Emmert Klaus Vector Informatik GmbH
|-------------------------------------------------------------------

/*Includes ********************************************************/
#include "can_inc.h"
#include "yourecu.h"

void main (void )
{
}

Back to 9 Steps overview

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

36 / 56
6.5
STEP 5 Adaptations for your Application
To be able to compile and link, you have to adapt a few things in your application.

Example for the HC12:

/* Includes*********************************************************/
#include "can_inc.h"  /*using CANgen*/
#include "yourecu.h"  /*using CANgen*/
#include "can_par.h"  /*is also included for GENy via include of v_inc.h*/

/*Function prototypes **********************************************/
void enableInterrupts( void );
void hardwareInit( void );

/*Main Function **********************************************/
void main(void)
{
/* make sure that the interrupts are disabled to initialize the
modules.*/

DO  NOT USE any CAN API function before calling CanInitPowerOn.
It is forbidden to use CanInterruptDisable here

hardwareInit();

It is forbidden to

use any CAN
functionality
  CanInitPowerOn(kCanInitObj1);
before CanInit-

PowerOn !!!
enableInterrupts();

for(;;)
{
;
}
}

void ApplCanBusOff( void )
{
; /*Callback function for notification of BusOff*/
}

void ApplCanWakeUp( void )
{

; /*Callback function at the transition from SleepMode to sleep
indication recommended*/
}

void hardwareInit( void )
{
/*
Do your hardware specific initializations here.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

37 / 56
Remember your TRANSCEIVER
*/
;
}

@interrupt void irq_dummy0(void)
{
  for( ;; ); /*all other interrupts except the CAN Interrupts are routed
to this function.*/
}

Now the description of the above code:
First, we have to include the can_inc.h and then the generated header, here
yourecu.h.
The following define is to enable the interrupts and is hardware dependent.
In the main() function you have to do initializations first.
In the hardwareInit you can turn on timers or PWM or something else.
When you use a
As you see, the transceiver connects directly to the CAN Bus, so:
high speed
transceiver, you
!!!  PLEASE THINK OF SWITCHING YOUR TRANSCEIVER ON !!!
have to take care
THE CAN DRIVER DOES NOT HANDLE THE TRANSCEIVER
of your terminat-
ing resistor of
120Ω
Normally this is only necessary when using a low-speed-transceiver. Refer to your
hardware guide.
CAN Driver
CAN Controller
can_rx
can_tx
(standby
enable)
Transceiver
CAN_H
CAN_L
GND

Figure  6-18 The Transceiver
To start the CAN Controller and the CAN Driver, you have to call the function:
CanInitPowerOn( kCanInitObj1 )
Make sure that
the interrupts are
disabled when
calling the func-
Make sure that you use functions of the CAN Driver API after CanInitPowerOn.
tion CanInitPow-
erOn. Normally
the interrupts are
disabled by
default at startup.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

38 / 56
The parameter passed in determines the init structure you made the settings for via
the Generation Tool. You will find the macro kCanInitObj1 in the generated
yourecu.h (can_par.h for GENy) normally at the end of the file. (On some hard-
ware platforms, this parameter is not necessary (e.g. V850). Refer to your hard-
ware specific documentation for this information.
Now you can enable interrupts.
The main-function is an endless-loop. Perhaps you can turn on some LEDs, to see
the application running.
You also have to provide the CAN Driver with two application functions, applCan-
BusOff and applCanWakeUp. For the first start, you can leave these functions
empty to avoid linker errors.
Think of adding

this or a similar
file to your sys-
Since the CAN Driver uses interrupts for notifying the application when a CAN
tem, i.e. your
makefile or  your
message has been received, you have to map the interrupts on the corresponding
project.
interrupt service routines. Refer to your compiler manual how to do this in your
case.
For the HC12 CAN Drivers this is done in the file vectors.c. Let’s have a look at this
file.
Interrupts and interrupt tables are highly dependent on the hardware. Just use this
example as a guide.

Example for HC12:

const functptr vectab[] = { // @0xFFC4 start address of table
  CanTxInterrupt, // $FFC4 CAN transmit
CanRxInterrupt, // $FFC6 CAN receive
CanErrorInterrupt, // $FFC8 CAN error
irq_dummy0, // reserved
irq_dummy0, //
irq_dummy0, //
  CanWakeUpInterrupt, // $FFD0 CAN wake-up
irq_dummy0, //ATD
irq_dummy0, //SCI 2
irq_dummy0, //SPI
irq_dummy0, //SPI
irq_dummy0, //Pulse acc input
irq_dummy0, //Pulse acc overf
irq_dummy0, //Timer overf
irq_dummy0, //Timer channel 7
irq_dummy0, //Timer channel 6
irq_dummy0, //Timer channel 5
irq_dummy0, //Timer channel 4
irq_dummy0, //Timer channel 3
irq_dummy0, //Timer channel 2
irq_dummy0, //Timer channel 1
irq_dummy0, //Timer channel 0
irq_dummy0, //Real time
irq_dummy0, //IRQ
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

39 / 56
irq_dummy0, //XIRQ
irq_dummy0, //SWI
irq_dummy0, //illegal
irq_dummy0, //cop fail
irq_dummy0, //clock fail
_stext //RESET
};

As you see in the example, we only use CAN-specific interrupts and the reset vec-
tor. All other interrupts result in a dummy interrupt.
You also have to provide the function irq_dummy0( ) in your application. Refer to your
hardware description to figure out the solution for your situation.

Back to 9 Steps overview

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

40 / 56
6.6
STEP 6 Compile, Link and Download
Now start your compiler by calling the makefile or just clicking the start button. What
you do is depends on your development tool chain.

Back to 9 Steps overview

6.7
STEP 7 Receiving A Message

Congratulations !!

You have now arrived at Step 7, i.e. you can compile and link. You are very close
to your first CAN communication.
In every project you normally have to spend a lot of the time starting up the hardware
and the development environment.

Make sure that:
You have the correct clock frequency (important for baud rate).
You have entered this clock in the dialog box of the Generation Tool.
The memory mapping is correct.
The physical CAN connection is there and has no damage.
You have a terminating resistor (120Ω) if you use high-speed CAN (powertrain).
Your transceiver is initialized properly
After the download of your Application, set a breakpoint in your debugger on the
main (void) function and start. Did it stop at main?
If so, Congratulations again.
Remove the breakpoint and restart. Now your application is running in the endless
loop. Please check this!
CANoe is very
convenient for
testing a CAN
communication.
As soon as you
see the message
Id or the Name in
the  Trace win-
dow after sending

a message, you
know that your
Figure  6-19 Simple Test Environment
hardware settings
are correct.
Now send a CAN message on the bus. It is best to use an ID your ECU normally
has to receive.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

41 / 56
A very easy way to send a message is by using the CANoe (or CANalyzer), a PC-tool
from Vector Informatik. Use the generator block and send the message.
Send the message and observe the Trace window.
Do you see the name of the message or the ID?
Great, your ECU has acknowledged the CAN message, i.e. all hardware settings
are correct.
If you see Error frames, check the list above. The main mistakes are hardware set-
tings (transceiver), the baud rate (clock of CAN Controller), wiring problems and
ground offsets.
Now we are ready to modify our application. Please check in the Generation Tool
on the tab Receive messages, if the Indication flag for the message is switched on.

Figure  6-20 Check button for indication flag
There are many
If not, switch it on, start a new generation process, compile and link the system again
more ways to
react  when a
and download it to the target.
CAN message  is
received. Refer to
Step 9 in this
Now we use the so-called Indication flag to poll the reception of the CAN message.
manual.
When an interrupt is triggered by the reception of a CAN message, the indication
flag will be set (if chosen in the Generation Tool).
When you use another dbc file, your message will have a different name. You will find
the correct macro for your indication flag in the file yourecu.h (can_par.h). Just search
for indication.
Example for the HC12:
void main(void)
{
hardwareInit();

CanInitPowerOn(kCanInitObj1);

enableInterrupts();

for(;;)
{
  /* First Test modification*/
if( Message_2_ind_b )
{
Message_2_ind_b = 0; Breakpoint here
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

42 / 56
}
}
}

The names are generated out of the name of the signal and the pre- and postfixes
from the “names” tab. Refer to the file YourECU.h (can_par.h) for the correct writing of
messages, indication flags etc.
Compile, link and download the application and set a breakpoint (as shown). Now
send the CAN message via the Generator Block.

It stopped at the breakpoint?

If so, you received the message, used the correct macro for the flag and got noti-
fied of the reception.

Back to 9 Steps overview

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

43 / 56
6.8
STEP 8 Sending a Message
The next step is the transmission of a CAN message. This is done by calling the
function
CanTransmit( handle );
The  handle specifies the message you want to send. Open the file yourecu.h
(can_par.h for GENy) and search for “handle” in the section on send/transmit
objects. Chose the appropriate macro for the send message and use it as shown.

Example:
void main(void)
{
hardwareInit();

CanInitPowerOn(kCanInitObj1);

enableInterrupts();

for(;;)
handle
{
/* First Test modification*/
if( Message_2_ind_b )
{
  /*Second Test modification*/

if( CanTransmit( CanTxMessage_1 ) == kCanTxOk )
{

    Message_2_ind_b = 0;
  }
}
}
}

Refer to the file YourECU.h (can_par.h for GENy) for the message handles.

Meaning of the return value of CanTransmit
The function CanTransmit has a return value, kCanTxOk or kCanTxFailed.  The
meaning of this value is not as simple as it looks like.
Without Software Transmit Queue
kCanTxOk means that the data has been copied from the RAM to the Tx Register
and the transmit request is set in the CAN Controller hardware. The physical trans-
mission of the message depends on when the message wins the CAN bus arbitra-
tion.
kCanTxFailed means the hardware register is busy or CAN Driver is offline.
With Software Transmit Queue
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

44 / 56
kCanTxOk could mean the same as above. But it also could mean that the transmit
request is set in the software queue of the CAN Driver and will be processed as soon
as possible. Read more about the software queue in the chapter 6.9.2.3.
kCanTxFailed means the CAN Driver is offline.

Full CAN Tx Object
There is no Tx queue functionality for Full CAN Tx Objects.

This modified application sends back a CAN message. You should see the re-
sponse message in your Trace window. Refer to the TechnicalRefer-
ence_CANDriver.pdf to get information about the return value.
Do you see the response message in the Trace window?

CONGRATULATIONS!
The basic CAN communication is running.

Of course this is a very simple application and far away from the complexity of your
application, but as the saying goes:
The longest way starts with the first step(s).

Back to 9 Steps overview

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

45 / 56
6.9
STEP 9 Further Actions
The next step is to build up your application around the communication. To do this
in a simple manner, read the following tips and recommendations. You will then be
given an exercise that poses a problem which you will try to solve. After finding the
correct answer, you will understand the order in which the functions of the CAN
Driver are called.
6.9.1  Strategies for Receiving a CAN Message
The  Figure   6-21 shows the calling order of the functions when receiving a mes-
sage.
Indication Flag/Function
Hardware Copy of data to
locked
software buffer
conditional
Precopy Function
exit
Search Algorithm
exit
if not found
Ranges
exit
if matched
ApplCanMsgReceived
conditional
exit
Hardware Filter
CAN-BUS

Figure  6-21 Calling Order Of Functions When A CAN Message Is Received
6.9.1.1
Hardware Filter (HW Filter)
As you have learned before, you can adjust the hardware filter in the Generation
Tool. Every message that passes the hardware filter triggers an interrupt – if not
using polling mode.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

46 / 56
To reduce your interrupt load, optimize the filters (Generation Tool).
6.9.1.2
ApplCanMsgReceived
In the Generation Tool you can choose to have this function called with any recep-
tion of a CAN message that passes the hardware filter.
Here you can filter the messages that pass the hardware filter but contain no rele-
If you select the
function
vant information. At this point, the data is in the receive register (Rx register). Use
ApplCanMsgRe-
the hardware access macros to figure out ID, DLC and DATA of the received mes-
ceived, the
prototype will be
sage.
generated. You
only have to enter
the function.
6.9.1.3
Ranges
Ranges are a software filter mechanism. Since the message is filtered by its ID
and assigned to the categories Network Management, Diagnostics, Application,
etc., you can route more messages on the same Range precopy function.
6.9.1.4
Search Algorithm
To figure out whether a message is meant for your ECU and which message ID it
is the CAN Driver has to compare the ID with an ID-list. This comparison can be
done in different ways. The criterion is the speed for browsing the list. The Genera-
tion Tool offers different search algorithms to choose. Please refer to the CAN
Driver Technical Manual for the differences.
6.9.1.5
Precopy
In the Generation Tool (receive objects/functions) you can enter a name for a mes-
sage-specific precopy function. This function is called by the CAN Driver before
copying the message data from the receive register to the RAM data structure (if
The _CAN_
selected).
macros will be
generated only
when you have
The Precopy function e.g. can be used to check to see if the data has
chosen a precopy
function or the
changed. Use the _CAN_ access macros to read the data out of the receive regis-
object is a full can
object.
ter and compare it with the RAM buffer (look in yourECU.h for CANgen and in
can_par.h for GENy for these access macros).
This macro will be only generated if the message is a full can object or you have se-
lected a precopy-function for this message (see later).
As you are in interrupt context, data consistency is not in danger (refer to the tech-
nical reference for you hardware). Keep your actions short in any Precopy func-
tion.
The return value of the Precopy function determines what happens next.
kCanCopyData: The driver is to do the copying from receive register to RAM
buffer.
kCanNoCopyData: You did the copy of relevant data and the driver does not need
to call its copying routine.

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

47 / 56
6.9.1.6
Indication Flag / Indication Function
The application is notified by the indication flags and/or the indication functions
The driver indicates the reception of a message to the application.
Indication Function
This function runs in interrupt context and is message-specific. Keep your action
very short in this function.
You can enter a name for a message-specific Indication function in the
Generation Tool (in the same way as you did it for the Precopy function).
Indication Flag
This flag is message-specific. It is set by the CAN Driver and can be polled by the
application. It tells the application a new message has been received.
!!! This flag must be reset by the application. !!!
You can use this flag to ensure you are working on the newest contents of a mes-
sage.
If the flag is set, it means that a new message has been received. Clear the flag and
access the received data. If the flag is cleared after your access, you can be sure that
you have current data. If the flag is set, new data has been received in the meantime,
so repeat this once again.

Remember for Data consistency
All flags are set by the driver in an interrupt context. If your µC does not perform an
atomic (i.e. uninterruptible) write access to bit data it is necessary to protect the
write access via an interrupt lock to prevent unexpected change or loss of flag
states. It is recommended to perform this (CAN-) interrupt lock via the API func-
tions CanInterruptDisable / CanInterruptRestore.
Please refer to your controller and/or compiler manual for information about atomic
write access to bit data in your system. In case of doubts, it is recommended to
lock the interrupt during the access.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

48 / 56
6.9.2 Strategies for Sending a CAN Message
The transmission of a CAN message is divided into two parts: the preparations until
the transmission of a message and the transmit interrupt handling, which informs
you about the successful sending of a message.
First we look at the preparations before sending.
Update RAM buffer
CAN Transmit
yes
Buffer free?
Entry in Queue
exit
Pretransmit
Copy of data to
hardware buffer
Send Message
CAN-BUS

Figure 6-22 States Before Transmitting A CAN Message
6.9.2.1
Update RAM buffer
The methods of transmission highly depend on your application. You may have to
send in a fixed cycle, or you may have to send when a specific event occurs.
Both cases require current data. If you use the RAM buffer, you just have to keep
the data in it up-to-date.
When you use your own buffer you should enter the values directly into the trans-
mit register just before sending the message. Otherwise the data could be overwrit-
ten by another transmit message.
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

49 / 56
6.9.2.2
CanTransmit
The CanTransmit function initiates the transmission of a specific message. The
You can only be
handle (in the file yourECU.h for CANgen and in can_par.h for GENy) specifies
sure that the
message has
which message is sent.
been sent when
you get the
confirmation
CanTransmit has 2 possible return values, but none of them guarantee that the
interrupt (confir-
mation function or
message has been sent yet. They just say that either the message will be sent as
confirmation flag)
soon as possible (with or without a queue) or the transmission request has been
rejected (see  6.8);

6.9.2.3
The Queue
There are two possible causes for a return value of kCanTxOk: either the message
has directly entered the transmit buffer or the message has entered the queue (if
chosen in the Generation Tool).
An entry in the queue means, the REQUEST to send this message is stored, not
the data. So leave the data untouched until you are sure the message has been
sent, i.e. until the Confirmation flag is set or the Confirmation function
is called.
6.9.2.4
Pretransmit Function
When you do not have a RAM buffer for your message, you must copy the data to
the transmit register of the CAN Controller in the Pretransmit function. With
the call of the function you get a pointer directly to the transmit registers. In this
case you have to know the distribution of the signals to the bytes, because you do
not get signal access macros.
The time between the call of CanTransmit and the confirmation interrupt is not pre-
dictable. To update your data short before the transmission, use the Pretransmit func-
tion too. If this function is called, you can be sure that this message is the next mes-
sage to be sent.
When the message is sent and at least one ECU receives this message, the ac-
knowledge will trigger the so-called transmit interrupt. This interrupt calls the
transmit interrupt service routine, which in turn might call the confirmation function
or set the confirmation flag.
6.9.2.5
Confirmation Function and Confirmation Flag
The Confirmation function is called in interrupt context, so keep the run time
See the parallels
as short as possible by not doing much in the code. Now you can be sure, your
between the
indication func-
message has been sent successfully.
tion/flag  and the
confirmation
The Confirmation flag has the same meaning, but you have to poll this flag in
function/flag
your application (similar to the way it is done with the Indication flag). You
get the macro out of the generated file yourECU.h (can_par.h).
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

50 / 56
Leave Interrupt
CanTransmitQueuedObject
Queue Empty?
Confirmation Flag/Function
CAN-BUS
ACKNOWLEDGE
Figure 6-23 Confirmation Interrupt After Transmission Of CAN Message
After the confirmation the queue (if chosen) will be worked on.

Back to 9 Steps overview

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

51 / 56
7  Further Information
7.1
An Exercise For Practice
The program below is a small application (for the HC12) using the basic service- and
call-back functions of the CAN driver. Try to follow the program and answer the
questions connected with.

The application receives a CAN message containing a byte signal b_Signal_2_c.
After processing the incoming message, the application sends another message
containing only one byte signal, called b_Signal_1_c.
Can you calculate the value that will be sent back with b_Signal_1_c depending
on the value of the variable a  and the value of the received signal
b_Signal_2_c?
See the solution at the end of this document

Example for the HC12:
/* Includes
*******************************************************************/
#include "can_inc.h"    /*for CANgen*/
#include "yourecu.h"    /*for CANgen*/

#include "can_par.h"    /*only include for GENy*/

/* Variable definition
*******************************************************************/
unsigned char a;

/* Function prototypes
********************************************************/
void main_function(void);
void enableInterrupts( void );
void hardwareInit( void );

/* The Main Function
**********************************************************/

void main(void)
{
hardwareInit();

CanInitPowerOn(kCanInitObj1);

  a = 5;
  b_Signal_2_c = 0;

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

52 / 56
enableInterrupts();

for(;;)
{

if( Message_2_ind_b )
    {
      b_Signal_1_c = b_Signal_2_c + a;
      if( CanTransmit( CanTxMessage_1 ) == kCanTxOk )
      {
/*Disable Interrupt*/
Message_2_ind_b = 0;
/*Enable Interrupt*/
      }

    }
if( Message_1_conf_b )
    {
a=1;
/*Disable Interrupt*/
Message_1_conf_b = 0;
/*Enable Interrupt*/
    }

  }
}

/* Other Functions
**********************************************************/

void enableInterrupts( void )
{
/*Enable interrupts*/
}
void ApplCanBusOff( void ) /*later uesd for bus off treatment*/
{
;
}
void ApplCanWakeUp( void ) /*later used for wakeup functionality*/
{
;
}
/* new function added in the Generation Tool and application */
canuint8 ApplCanMsgReceived( void )
{
a=a+2;

  return( kCanCopyData );
}
canuint8 M1_PretransmitFunction(CanChipDataPtr dat)
{
  b_Signal_1_c = b_Signal_1_c +1;
  return( kCanCopyData );
}
void M1_ConfirmationFunction(CanTransmitHandle tmtObject)
{
a=a+23;
}
canuint8 M2_Precopy(CanReceiveHandle rcvObject)
{
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

53 / 56
rcvObject = rcvObject;  /*to  avoid  compiler  warning.  You  only

use this handle if you have one

precopy function for two or more

messages*/
a=2;
  if( b_CAN_Signal_2_c == b_Signal_2_c )
{

return(
kCanNoCopyData
);
/*same value as before, no need to

copy data, leave interrupt*/
}
else
{
a = b_CAN_Signal_2_c;
return( kCanCopyData );
}
}

void M2_IndicationFunction(CanReceiveHandle rcvObject)
{
  rcvObject = rcvObject; /*to
avoid
compiler
warning.
You
only
       use this handle if you have
one
precopy
function
for
two
or
more
messages*/
a=a+1;
}
/****************************************************/
void hardwareInit( void )
{
/*
  Do your hardware specific initializations here.
  Don’t forget to initialize your TRANSCEIVER, if necessary*/
;
}
@interrupt void irq_dummy0(void)
{
  for( ;; );
}

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

54 / 56
7.2
The Solution To The Exercise
7.2.1  After the first reception and transmission of a new value:
a = 1
b_Signal_1_c = b_Signal_2_c*2+2

7.2.2  After the reception of the same value as before:
a = 2
no return message

Did you get it?

7.2.3  The solution, step by step
At the beginning,
a=5 and b_Signal_2_c = 0
The Main loop is waiting on an Indication Flag for Message 2 and a Confirmation
Flag for Message 1.
The first function that is called after the reception of Message 2 is ApplCan-
MsgReceived. There the 2 is added to a and returned with kCanCopyData, so
the reception process continues.
At this point a=7 and b_Signal_2_c = b_Signal_2_c
The next function executed is M2_Precopy. The variable a is set to 2 and the re-
ceived signal b_CAN_Signal_2_c (the data in the Rx register, i.e. in the CAN Con-
troller) is compared with the signal b_Signal_2_c.
If there is no change, the return value kCanNoCopyData stops the receive process
the receive interrupt is exited.
Now a=2 and no response message will be sent.
If there is a difference, a is set to b_CAN_Signal_2_c and the return value keeps
the receive interrupt going on.
At this point a= b_CAN_Signal_2_c and b_Signal_2_c= b_Signal_2_c
Now the Indication function M2_IndicatinoFunction is called, where a
is increased by 1.
Now a= b_Signal_2_c+1 and b_Signal_2_c= b_Signal_2_c
©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

55 / 56
Since the Indication flag is set, now the main loop put b_Signal_1_c =
b_Signal_2_c+a, i.e. b_Signal_1_c= 2* b_Signal_2_c+1.
Now the message is requested to be sent (CanTransmit). If the request is an-
swered with a kCanTxOk, the Indication flag is cleared to avoid sending the mes-
sage again and again. Otherwise the flags stay set until the request of sending this
message is successful.
At this point a = b_Signal_2_c+1 and b_Signal_2_c = b_Signal_2_c and
b_Signal_1_c = 2* b_Signal_2_c +1
Before the message is on its way, the function M1_PretransmitFunction is
called. This function increments the send signal by 1 and the return value lets the
driver copy the data from the RAM buffer to the Tx register.
At this point a = b_Signal_2_c+1 and b_Signal_2_c = b_Signal_2_c and
b_Signal_1_c = 2* b_Signal_2_c +2
Now the message is on its way via CAN. The first node to receive this message (in
this test case, CANoe) gives an acknowledge that triggers a transmit interrupt.
In the function M1_ConfirmationFunction 23 is added to a.
Now a = b_Signal_2_c+24 and b_Signal_2_c = b_Signal_2_c and b_Signal_1_c = 2*
b_Signal_2_c +2
Then the Confirmation flag is set and recognized by the main loop. There the
variable a is set to 1 and the Confirmation flag is reset to 0 to prevent setting
a over and over again.
So the result is:
a = 1
b_Signal_1_c = 2* b_Signal_2_c +2

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7

User Manual Vector CAN Driver

56 / 56
8
Index
Acceptance filters ................................. 26, 32
Hardware..................................................... 45
applCanBusOff ........................................... 38
Including Order............................................ 15
ApplCanMsgReceived .................... 46, 52, 54
Indication flag .................................. 41, 49, 55
applCanWakeUp......................................... 38
Indication Flag............................................. 47
baud rate............................................... 29, 41
Indication Function...................................... 47
Bootloader .................................................. 10
Init registers........................................... 25, 29
Bustiming ........................................ 26, 27, 32
Interaction Layer ................................... 12, 13
Bustiming registers ............................... 26, 32
interrupt ....................................................... 47
CAN Driver. 12, 14, 15, 17, 22, 25, 33, 35, 45,
link.......................................35, 36, 40, 41, 42
46
makefile................................................. 35, 40
can_cfg.h .............................................. 25, 33
memory requirement................................... 19
can_inc.h .................................................... 35
message...................................................... 16
CANalyzer................................................... 41
Motivation...................................................... 4
CANdesc IN 8 STEPS ................................ 53
Network Management................................. 12
CANdesc tab............................................... 15
Open filters............................................ 27, 32
CanInitPowerOn ......................................... 37
Optimze filters ....................................... 27, 32
CanInterruptDisable.................................... 47
Precopy ...............................19, 46, 47, 52, 54
CanInterruptRestore ................................... 47
Pretransmit............................................ 19, 49
CANoe .................................................. 41, 55
Queue ......................................................... 49
Channel properties ..................................... 23
Ranges........................................................ 46
clock.......................................... 28, 39, 40, 41
receive register............................................ 18
compile ..................................... 35, 36, 40, 41
Registers ..................................................... 18
Confirmation ............................................... 49
Search Algorithm......................................... 46
Data consistency ........................................ 47
signals ......................................................... 16
dbc file ............................................ 11, 22, 41
Strategies .............................................. 45, 48
dbc-file ............................................ 22, 23, 24
transmit register .......................................... 18
Diagnostics ................................................. 12
Transport Protocol....................................... 12
example .......................................... 35, 38, 39
Universal Measurement and Calibration
Example........................ 35, 36, 38, 41, 43, 51
Protocol (XCP).................................. 12, 13
generation process ................... 14, 33, 35, 41
yourecu.h ................35, 36, 37, 38, 41, 43, 51

©2009, Vector Informatik GmbH

Version: 2.4

based of template version 1.7