MSCANDriver

For S12 + S12X

User Manual

S12 + S12X
Microcontrollers

MSCANS
MSCANS12 12 DUM
12DUM
Rev. 0.1
01/2013
/2013
2 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

MSCAN Driver User Manual

For S12 + S12X

To provide the most up-to-date information, the revision of our documents on the World Wide Web
will be the most current. Your printed copy may be an earlier revision. To verify that you have the
latest information available, refer to http://www.freescale.com.
The following revision history table summarizes changes contained in this document. For your
convenience, the page number designators have been linked to the appropriate location, and change
bars indicate where changes have been made.

msCANS12/S12X Driver User Manual, Rev. 0.1 3

Freescale Semiconductor
 Revision History

Revision History

Date Revision Description Page

Level Number(s)

1/2013 0.1 Initial release 65

4 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

Contents
Chapter 1
Overview

Chapter 2
Notations
2.1 Manual Structure . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
2.2 Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
2.3 Definitions, Acronyms and Abbreviations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
2.4 References . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Chapter 3
CAN Overview

Chapter 4
msCANS 12 Overview
msCANS12

Chapter 5
msCANS 12 Driver
msCANS12
5.1 Driver Functionality Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
5.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
5.2.1 Driver Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
5.2.2 Message Object Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Chapter 6
msCANS 12 Driver API
msCANS12
6.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
6.2 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
6.3 Constant Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
6.4 Driver Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
6.4.1 Init _CAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
6.4.2 Reset _CAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
6.4.3 Sleep _CAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
6.4.4 Wakeup _CAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
6.4.5 Check_CAN_Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
6.4.6 Clear_CAN_Status. . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
6.4.7 Config_CAN_MB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
6.4.8 Check_CAN_MB_Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
6.4.9 Load_CAN_MB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
6.4.10 Transmit_CAN_MB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
6.4.11 Abort_CAN_MB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
6.4.12 Read_CAN_MB_Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
msCANS12/S12X Driver User Manual, Rev. 0.1 5
Freescale Semiconductor
6.4.13 Read_CAN_MB_Time . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
6.4.14 Read_Rec_Err_Counter . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
6.4.15 Read_Tran_Err_Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
6.4.16 Read_REALTIME_Buffer. . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
6.4.17 Register_Callback… . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
6.4.18 Unregister_Callback . . . . . . . …. . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Chapter 7
Building Application
7.1 MCU Resources Usage . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
7.2 Physical Interface Connection . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
7.3 CAN Network Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
7.4 Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
7.5 Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Appendix A
msCAN Driver Usage
A.1 Driver Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
A.2 Message Buffer Initialization and Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
A.3 Transmitting a Data Frame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
A.4 Receiving a Data Frame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
A.5 Transmitting a Remote Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
A.6 Automatic Reply to a Remote Frame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
A.7 Time Stamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
A.8 Low Power Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
A.9 Reserved Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Appendix B
Sample Application
B.1 Sample Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
B.2 Sample Building and Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
B.3 CodeWarrior Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Appendix C Further Information
C.1 Application Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
C.2 Online Training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Appendix D
Performance Characteristics
D.1 Performance Characteristics and Memory Consumption. … . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63

6 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

Chapter 1

Overview

This User Manual describes CAN protocol driver routines for the Freescale msCAN CAN 2.0B
peripheral modules which are integrated onto a number of devices from the Freescale MC9S12 and
MC9S12X product family.
The driver is optimized for Multi-modules msCAN on-chip. The driver emulates the 'full-CAN'
model, with a message buffer per CAN identifier. The number of message buffers is configurable,
allowing full control over RAM requirements.
The main driver features are:
� Optimized for Multi-modules msCAN on-chip
� Based on S12msCAN V3 version, Supports S12 and S12X family microcontrollers.
� Up to 255 message objects (Standard and Extended Identifiers)
� Up to 32 message buffers
� Advanced priority-based management of queued message objects
� Auto-reply to received Remote Transmission Request Frames
� Auto-receive Data Frames received in response to Remote Transmission Request Frames
� Sleep and Wake-up functions
� Abort transmission function
� Error Callback and notification
� Support reading for msCAN error-counter.
The driver is supplied as source code and header files.
The supported toolchain the CodeWarrior compiler V5.9 or later, with ‘C’ header files for user
defined parameters.

msCANS12/S12X Driver User Manual, Rev. 0.1 7

Freescale Semiconductor
8 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

Chapter 2

Notations

2.1 Manual Structure

This user’s manual comprises the following sections.

Chapter 1 Overview provides the msCANS12/S12X driver for S12 and S12X overview and
describes its main features.
Chapter 2 Notations includes a description of the structure of the document, typographical
conventions used, references to other documents, technical support information, and a list of
acronyms.
Chapter 3 CAN Overview provides a general description of the CAN specification.
Chapter 4 msCAN Overview provides a general description of the msCANS12/S12X module.
Chapter 5 msCANS12/S12X Driver describes the msCANS12/S12X driver configuration and
functionality.
Chapter 6 msCANS12/S12X Driver API provides a detailed description of msCANS12/S12X driver
run-time services.
Chapter 7 Building Application provides Information regarding setting up a CAN network and
describes the steps for compiling and linking the application.
Appendix A msCAN Driver Usage provides information how to use the msCANS12/S12X driver.
Appendix B Sample Application contains the sequence of actions needed for creation, building and
execution of sample application included into the msCANS12/S12X driver package.
Appendix C Further Information refers to further msCAN information (Application Notes and
Online Training).
Appendix D Performance Characteristics contains msCANS12/S12X driver performance
characteristics, such as ROM and RAM usage, timing and CPU load.

2.2 Typographical Conventions

This manual employs the following typographical conventions:

� italic type is used for all names of directives, macros, constants, routines and variables. Also,
this type is used for special terms.

msCANS12/S12X Driver User Manual, Rev. 0.1 9

Freescale Semiconductor
� courier type is used for code examples in the text.

2.3 Definitions, Acronyms and Abbreviations

API application program interface (a set of data types and functions)

CAN controller area network

DLC data length code

IDE identifier extension

ISR interrupt service routine

MCU microcontroller unit (Freescale Semiconductor’s microcontrollers)

Freescale API message oriented API, specified by Freescale

msCAN Freescale CAN 2.0B module for MC9S12

msCANS12/S12X specific implementation of Freescale CAN 2.0B module for S12/S12X family
of MCUs

RAM random access memory

ROM read only memory

RTR remote transmission request

SRR substitute remote request

2.4 Definitions, Acronyms and Abbreviations

[1] CAN Specification A/B, Revision 2.0, September 1991

10 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

Chapter 3

CAN Overview
The Controller Area Network (CAN) protocol is a serial communications protocol designed to
support distributed real-time control applications at bit rates up to 1Mbit/s. Originally developed by
Robert Bosch Gmbh in the early 1980s for the automotive sector, the benefits of the CAN protocol
are applicable to other cost sensitive and environmentally demanding applications e.g. in the
industrial sector. The low cost of CAN networks is realized by high performance microcontrollers
with on-chip CAN modules, such as the Freescale MC9S12 and MC9S12X with the msCAN
module. The driver routines described in this User Manual are designed to facilitate the use of these
on-chip CAN modules by relieving the application programmer from having to understand the
detailed operation of these modules. However a basic understanding of the CAN protocol is
assumed and a very brief overview is provided here.
CAN is a Carrier Sense Multiple Access with Collision Detection (CSMA/CD) protocol.
Information is transmitted on the CAN bus in fixed format messages by nodes. The main message
formats are called: Data Frame, Remote Transmission Request Frame (Remote Frame) and Error
Frame. A Data Frame is used to transmit data and a Remote Frame is a request for data. The Error
Frame is transmitted automatically by the msCAN module when an error is detected. The Data
Frame consists of the following fields: a start bit, an arbitration field, a control field, a data field, a
Cyclic Redundancy (CRC) Field, an acknowledge field and an end of frame field. A Remote Frame
is similar to a Data Frame but has no data field. In order to transmit a Data Frame, the application
must specify the arbitration field, part of the control field (Data Length Code, from 0 to 8) and the
data field (number of bytes specified by Data Length Code), the other fields are generated
automatically by the CAN controller. The arbitration field contains the message Identifier which has
three functions:
1. It defines the priority of the message. CAN is a multi-master protocol, so in the case when
more than one node is attempting to start the transmission of Data or Remote Frames
simultaneously, the bus access conflict is resolved by bit-wise arbitration using the arbitration
field of the message. The message with the highest priority arbitration field wins access to the
CAN bus and may continue to transmit the rest of the message. This requires that each message
in a system is defined with a unique Identifier.
2. It is used to label the message. As each message must have a unique Identifier, the Identifier
may be used to label the message contents. For example, the message with Identifier 0x123
always contains the latest value from sensor A.
3. It is used for message filtering. All nodes test the arbitration field of al l received messages with
a programmable hardware filter to determine whether to accept the message. Messages which
are not relevant to a node can thus be filtered out. An efficient filter implementation will save
processor time by eliminating the processing of unwanted messages. Careful selection of
Identifiers is required to achieve efficient filters on all nodes. Filtering allows any number of
msCANS12/S12X Driver User Manual, Rev. 0.1 11
Freescale Semiconductor
 nodes to receive and simultaneously act upon the same message providing multicast
communication.
CAN specification 2.0A defines an 11-bit Identifier; CAN specification 2.0B defines Identifiers
with 11-bits (Standard) and 29-bits (Extended).

12 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

Chapter 4

msCANS12/S12X Overview
The msCANS12/S12X module is Freescale specific implementations of CAN controllers for the
CAN 2.0B protocol. These are highly efficient CAN controller modules which are optimized for
real-time performance that incorporate important features for predictable CAN network traffic.
In order to have predictable, deterministic behavior, a CAN controller must be able to:
� transmit a stream of CAN messages without that stream being interrupted by a CAN message
of lower priority from an other node
� manage the internal CAN message queue so that messages queued for transmission are
transmitted in order of message priority i.e. the highest priority message in the queue is
transmitted first.
The Freescale msCAN modules are unique in having a triple transmit buffer arrangement with
internal prioritisation which enables the above requirements to be achieved. The local priority
register for each transmit buffer ensures that the transmit buffer which contains the highest priority
message is used to arbitrate for CAN bus access. In the case where more than three CAN messages
are queued for transmission, the driver software must ensure that the two highest priority queued
mess ages are loaded into the msCAN transmit buffers at all times. Thus the highest priority queued
message in one transmit buffer is used to arbitrate for bus access. The second highest priority
message is already in another transmit buffer waiting to begin arbitrating for bus access
immediately after the message in the first buffer has completed its transmission. The final transmit
buffer is available to be loaded with the next highest priority message in the transmit queue. If the
application program schedules a new, higher priority message for transmission, the driver software
must overwrite the transmit buffer which contains the lowest priority message with the new, higher
priority message and place the lower priority message back in the transmit queue.
As a further performance enhancement, the Freescale msCAN modules have a very flexible
programmable acceptance filter, which allows an efficient acceptance filter to be achieved. An
efficient acceptance filter is one which accepts all the CAN messages which are wanted by a node
but which rejects all, or as many as possible, of the CAN messages which are not wanted by that
node. An efficient acceptance filter has a significant impact on the time spent by the CPU
processing received CAN messages. If an unwanted message is accepted by the filter, significant
time may be wasted in checking the Identifier of the received message with a list of wanted
message Identifiers.
The msCANS12/S12X acceptance filter may be configured as:
� 2 independent 32-bit filters, which test the 29 bits of a extended Identifier plus the SRR, IDE
and RTR bits, or the 11 bits of a standard Identifier plus the RTR and IDE bits.
� 4 independent 16-bit filters, which test the 14 most significant bits of an extended Identifier
msCANS12/S12X Driver User Manual, Rev. 0.1 13
Freescale Semiconductor
 plus the SRR and IDE bits, or the 11 bits of a standard Identifier plus the RTR and IDE bits.
� 8 independent 8-bit filters, which test the 8 most significant bits of standard and extended
Identifiers.
The flexibility of the msCAN acceptance filter allows for a highly efficient filter to be implemented.
An offline software utility is available from Freescale that will automatically generate the optimum
msCAN filter values, based on a list of wanted and unwanted message Identifiers.

14 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

Chapter 5

msCANS12/S12X Driver

5.1 Driver Functionality Overview

The msCANS12/S12X driver routines described in this User Manual are designed to provide the
application programmer with a higher level of interface to the msCAN module, thus relieving the
programmer from having to understand the detailed operation of the msCAN module. The
application programmer can design the application to interface to the msCAN driver routines, in the
knowledge that the driver routines will take all the necessary actions to transmit and receive
messages on the CAN bus.
The msCAN driver routines perform the following functions:
� Multi-msCAN Modules supported, each module has individual buffer and interrupts
� Initialization of the msCAN module
� Transmission of CAN messages, with a local priority based queue
� Store received CAN messages in appropriate message buffers
� Functions to configure, load, read and obtain the status of message buffers
� msCAN control functions (Reset_CAN, Sleep_CAN, Wakeup_CAN, Check_CAN_Status,
Clear_CAN_Status)
� Error management and notification, Error callback function supported
� Auto-reply to received Remote Transmission Request Frames
� Real time frame receive function for unexpected frames.
The driver supports Multi-msCAN Modules, the max number of msCAN Module is only limited by
the MUC hardware resources. All the module can work in different bit-rate with highspeed or
lowspeed transceivers.
Initialization of the msCAN module is performed by writing user defined data to the msCAN
control registers. The data defines such things as the CAN bus bit rate , bit timing information and
the programmable identifier acceptance filter.
Data to be transmitted by or received from the ms CAN module is stored in generic message buffers
in RAM. In order to transmit or receive data, the message buffers must be configured appropriately.
Each message buffer is configured by calling the Config_CAN_MB function. This function is also
used to assign a message Identifier, from an array located in ROM, to each message buffer. To
transmit a message, the application must first load the appropriate message buffer with data and
then request the transmission of that buffer. The data contained in the message buffer and the
Identifier assigned to it are then transferred to the msCAN module for transmission. When more
than one message buffer is queued for transmission, the driver ensures that the message with the
greatest lo cal priority in the queue is transmitted first. The local priority is defined by the order in
which the application programmer defines the message Identifiers in the Identifier table. The
msCANS12/S12X Driver User Manual, Rev. 0.1 15
Freescale Semiconductor
application program can check the status of the message buffer to find out if the message has been
successfully transmitted.
When a message is received by the msCAN module which passes the programmable acceptance
filter, that message is processed by the msCAN driver receive ISR. The receive ISR searches all
message buffers configured to receive messages for a message buffer with a matching Identifier. If a
match is found, the driver stores the received data in the matching message buffer. The application
program can check the status of message buffers to find out if any new messages have been receive
d. The application program can then read the data in the message buffer.
Functions are also provided to control and obtain the status of the msCAN module. These include a
function to put the msCAN into its low power SLEEP mode. The msCAN can then be woken up
either explicitly by the application program or automatically by the detection of a message on the
CAN bus.
Real time frame receive function is quite necessary if user don’t quite know the ID and type of
frame to be received, if this function supported, all received frame will be stored to a realtime buffer
for each channel, and then if any message buffers configured to receive messages for a message
buffer with a matching Identifier, the frame will also be stored there. Note that the realtime frame
receive function will add the cpu load and receive latency, so the function is disabled by default,
user should enable it when needed.

5.2 Driver Configuration

5.2.1 Driver Configuration

The driver has a static configuration; it can not be changed during run-time.
To use the msCANS12/S12X driver, the user must place #include “msCANdrv.h” in the application
file and configure the header file “msCANcfg.h”.
File “msCANcfg.h” contains macro definitions (see Table 5-1 Macro Definitions) which may be
modified by the user. The default values of macro definitions will result in:
� 5 msCAN modules enabled
� 16 Message Buffers for each msCAN module
� 16 Number of Message Objects for each msCAN module
� Message time stamps enabled
� bit rate configured for each channel
� the msCANS12/S12X remains active in WAIT mode
� the wake-up filter is active in SLEEP mode
� all CAN Identifiers accepted by the msCAN filter
� Error Callback function enabled
� REAL_TIME receive buffer function disabled

Table 5-1Macro Definitions

16 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

Macro Default Description

REAL_TIME_BUFFER_ENA FALSE Selects weather real time buffer is

BLE_CANx enabled

no_of_mb_CANx 16 Number of message buffers

no_of_ID_CANx 16 Number of Message Objects

Err_Callback_Enable TRUE Selects the Error Callback function is

enabled

TIMESTAMP_CANx TRUE Selects timestamp option

CLKSRC_CANx MCGERCLK Selects clock source

PRESCALER_CANx 8, 8, 1, 2, 2 Prescaler value

TIME_SEG1_CANx 13 Time Segment 1 value

TIME_SEG2_CANx 2 Time Segment 2 value

RJW_CANx 0 Resynchronisation jump width value

LISTEN_CANx FALSE Select listen mode

CANENABLE_CANx TRUE msCAN module enable

SAMPLEX3_CANx TRUE Selects 3 or 1 sample(s) per bit

Selects whether msCAN module is
CSWAI_CANx FALSE
inactive in WAIT mode
Selects whether activity on the CAN
WU_ENABLE_CANx TRUE
bus will wake the msCAN module
WU_FILTER_CANx TRUE Selects whether the wake-up filter is
active

ACC_FILTER_CANx AF32BIT Selects acceptance filter size

ID_CODE0_CANx 0xFF Acceptance code register 0 value

ID_CODE1_CANx 0xFF Acceptance code register 1 value

msCANS12/S12X Driver User Manual, Rev. 0.1 17

Freescale Semiconductor
 ID_CODE2_CANx 0xFF Acceptance code register 2 value

ID_CODE3_CANx 0xFF Acceptance code register 3 value

ID_CODE4_CANx 0xFF Acceptance code register 4 value

ID_CODE5_CANx 0xFF Acceptance code register 5 value

ID_CODE6_CANx 0xFF Acceptance code register 6 value

ID_CODE7_CANx 0xFF Acceptance code register 7 value

ID_MASK0_CANx 0xFF Acceptance mask register 0 value

ID_MASK1_CANx 0xFF Acceptance mask register 0 value

ID_MASK2_CANx 0xFF Acceptance mask register 0 value

ID_MASK3_CANx 0xFF Acceptance mask register 0 value

ID_MASK4_CANx 0xFF Acceptance mask register 0 value

ID_MASK5_CANx 0xFF Acceptance mask register 0 value

ID_MASK6_CANx 0xFF Acceptance mask register 0 value

ID_MASK7_CANx 0xFF Acceptance mask register 0 value

REAL_TIME_BUFFER_ENABLE _CANx
REAL_TIME_BUFFER_ENABLE_CANx
REAL_TIME_BUFFER_ENABLE_CAN0
REAL_TIME_BUFFER_ENABLE_CAN1
REAL_TIME_BUFFER_ENABLE_CAN2
REAL_TIME_BUFFER_ENABLE_CAN3
REAL_TIME_BUFFER_ENABLE_CAN4
This variable specifies whether real-time-buffer is desired for each msCAN module.
Real-time-buffer will be used to store all received message.
E.g.
#define REAL_TIME_BUFFER_ENABLE_CAN0 FALSE

18 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

Disable real-time-buffers for msCAN modules for CAN0 module.

no_of_mb_CANx
no_of_mb_CAN0
no_of_mb_CAN1
no_of_mb_CAN2
no_of_mb_CAN3
no_of_mb_CAN4
These variables specify the number of message buffers desired for each msCAN module. Permitted
values for no_of_mb_CANx are 1 to 255.
E.g.
#define no_of_mb_CAN3 32

Specifies 32 message buffers for CAN3 module.

no_of_ID_CANxx
no_of_ID_CAN
no_of_ID_CAN0
no_of_ID_CAN1
no_of_ID_CAN2
no_of_ID_CAN3
no_of_ID_CAN4
These variables specify the number of message objects desired for each msCAN module. Permitted
values for no_of_ID_CANx are 1 to 255.
E.g.
#define no_of_ID_CAN0 16

Specifies 16 message objects for CAN0 module.

Err_Callback_Enable
This variable specifies whether the Error Callback function is enabled.
E.g.
#define Err_Callback_Enable TRUE

Enable real-time-buffers for msCAN modules.

TIMESTAMP_CANx
TIMESTAMP_CAN0
TIMESTAMP_CAN1
TIMESTAMP_CAN2
TIMESTAMP_CAN3
TIMESTAMP_CAN4

msCANS12/S12X Driver User Manual, Rev. 0.1 19

Freescale Semiconductor
These variables specify whether time stamps are desired for each msCAN module. Permitted values
for TIMESTAMP_CANx are TRUE or FALSE.
E.g.
#define TIMESTAMP_CAN0 TRUE

Enable timestamp for CAN0 module.

CLKSRC_CANx
CLKSRC_CAN0
CLKSRC_CAN1
CLKSRC_CAN2
CLKSRC_CAN3
CLKSRC_CAN4
These variables are used to specify the msCAN source clock for each msCAN module. Permitted
values for CLKSRC_CANx are BUSCLK or MCGERCLK. MCGERCLK specifies a clock derived
directly from the crystal oscillator. BUSCLK specifies a clock which is the MCU internal bus
frequency. This clock may be derived from the crystal oscillator directly or from the output of a
Phase Locked Loop (PLL). For CAN bit rates greater than 125kbps it is recommended NOT to use
a clock source derived from the output of the PLL as the jitter in this clock may exceed the
maximum permitted by the CAN protocol.

Figure 5-1. msCANS 12 Clock Source

msCANS12
E.g.
#define CLKSRC_CAN2 BUSCLK

Specifies the bus clock as the clock source for CAN2 module.

PRESCALER_CANx
PRESCALER_CAN0
PRESCALER_CAN1
PRESCALER_CAN2
PRESCALER_CAN3
PRESCALER_CAN4
These variables specific the prescaler value for each msCAN module. The prescaler value is used to
divide the msCAN source clock to obtain the msCAN time quantum clock. Time Quantum Clock =
20 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

Source Clock / PRESCALER_CANx permitted values of PRESCALER_CANx are 1 to 64.

E.g.
#define PRESCALER_CAN0 8

Specifies a prescaler value of 8 for CAN0 module.

TIME_SEG1_CANx
TIME_SEG1_CAN0
TIME_SEG1_CAN1
TIME_SEG1_CAN2
TIME_SEG1_CAN3
TIME_SEG1_CAN4
These variables specify the duration of the time segment 1 of a CAN bit time for each msCAN
module. The duration is specified in number of time quanta, where 1 time quantum = period of time
quantum clock. The CAN bit time is equal to:
(1 + TIME _SEG1_CAN + TIME _SEG2_CAN) * time quantum.
E.g.
#define TIME_SEG1_CAN3 13

Set time quanta of time segment 1 to 13 for CAN3 module.

TIME_SEG2_CANx
TIME_SEG2_CANx
TIME_SEG2_CAN0
TIME_SEG2_CAN1
TIME_SEG2_CAN2
TIME_SEG2_CAN3
TIME_SEG2_CAN4
These variables specify the duration of the time segment 2 of a CAN bit time for each msCAN
module. The duration is specified in number of time quanta, where 1 time quantum = period of time
quantum clock. The CAN bit time is equal to: (1 + TIME _SEG1_CAN + TIME _SEG2_CAN) *
time quantum.
E.g.
#define TIME_SEG2_CAN4 2

Set time quanta of phase segment 2 to 2 for CAN4 module.

RJW_CANx
RJW_CAN0
RJW_CAN1
RJW_CAN2
RJW_CAN3
RJW_CAN4
These variables specify the CAN bit resynchronisation jump width for each msCAN module. This
msCANS12/S12X Driver User Manual, Rev. 0.1 21
Freescale Semiconductor
value limits the maximum number of time quanta by which a CAN bit time may be shortened or
lengthened on order to resynchronize to the CAN bit stream.
E.g.
#define RJW_CAN0 0

Specifies 1 time quanta for the resynchronisation jump width.

LISTEN_CANx
LISTEN_CAN0
LISTEN_CAN1
LISTEN_CAN2
LISTEN_CAN3
LISTEN_CAN4
These variables are used to select whether the msCAN module is in listen mode for each msCAN
module. Permitted values of LISTEN_CANx are TRUE or FALSE.
E.g.
#define LISTEN_CAN0 TRUE

Specifies CAN0 module in listen mode.

CANENABLE_CANx
CANENABLE_CAN0
CANENABLE_CAN1
CANENABLE_CAN2
CANENABLE_CAN3
CANENABLE_CAN4
These variables are used to enable the msCAN module. Permitted values of CANENABLE _CANx
are TRUE or FALSE.
E.g.
#define CANENABLE_CAN1 TRUE

Specifies CAN1 module enabled.

SAMPLEX3_CANx
SAMPLEX3_CAN0
SAMPLEX3_CAN1
SAMPLEX3_CAN2
SAMPLEX3_CAN3
SAMPLEX3_CAN4
The variable SAMPLEX3_CANx are used to select 1 or 3 samples per CAN bit.
Permitted values of SAMPLEX3_CAN are TRUE or FALSE.
E.g.
#define SAMPLEX3_CAN2 TRUE
22 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

Specifies 3 samples per bit for CAN2 module.

CSWAI_CANx
CSWAI_CAN0
CSWAI_CAN1
CSWAI_CAN2
CSWAI_CAN3
CSWAI_CAN4
The variables CSWAI_CANx specify whether the msCANS12X or msCANS12 modules are
inactive when the MCU is in WAIT mode. Permitted values of CSWAI_CANx are TRUE or
FALSE.
E.g.
#define CSWAI_CAN4 TRUE
Specifies that the msCANS12X module CAN4 remains active in WAIT mode (unless the
msCANS12X was previously put into SLEEP mode).

WU_ENABLE_CANx
WU_ENABLE_CAN0
WU_ENABLE_CAN1
WU_ENABLE_CAN2
WU_ENABLE_CAN3
WU_ENABLE_CAN4
These variables specify whether the wake-up filter are applied to msCAN modules when it is in
SLEEP mode. Permitted values of WU_ENABLE_CANx are TRUE or FALSE.
E.g.
#define WU_ENABLE_CAN0 TRUE
Specifies that activity will wake up the msCAN module CAN0 when it is in SLEEP mode.

WU_FILTER_CANx
WU_FILTER_CAN0
WU_FILTER_CAN1
WU_FILTER_CAN2
WU_FILTER_CAN3
WU_FILTER_CAN4
These variables specify whether the wake-up filters are applied to msCAN modules when
they are in SLEEP mode. When the wake-up filter is applied, short electrical disturbances on the
CAN bus will not wake-up the msCAN module from SLEEP mode. Permitted values of
WU_FILTER_CANx are TRUE or FALSE.
E.g.
#define WU_FILTER_CAN2 TRUE

Specifies that the wake-up filter is applied to msCAN module CAN2 when it is in SLEEP mode.

msCANS12/S12X Driver User Manual, Rev. 0.1 23

Freescale Semiconductor
ACC_FILTER_CANx
ACC_FILTER_CAN0
ACC_FILTER_CAN1
ACC_FILTER_CAN2
ACC_FILTER_CAN3
ACC_FILTER_CAN4
These variables specify the acceptance filters size for receiving CAN messages. The msCANS12X
or msCANS12 may have two 32-bit filters, or four 16-bit filters, or eight 8-bit filters. In the case
where the filter size is less than the size of the CAN message Arbitration field, the filter applies to
the most significant bits of the CAN message arbitration field. Permitted values of
ACC_FILTER_CAN are AF32BIT (32-bit filter), AF16BIT (16-bit filter) and AF8BIT (8-bit filter).
E.g.
#define ACC_FILTER_CAN0 AF32BIT

Specifies a 16-bit acceptance filter size for CAN0 module.

ID_CODEy_CANx
ID_CODEy_CAN0
ID_CODEy_CAN1
ID_CODEy_CAN2
ID_CODEy_CAN3
ID_CODEy_CAN4
The variables ID_CODEy_CANx specify the acceptance code register values. For the msCANS12X
and msCANS12, x is 0 to 7. The values of these variables, together with the acceptance mask values,
specify the CAN message arbitration field values which will pass the msCAN acceptance filter, i.e.
they specify which received CAN messages are accepted by the msCAN module. CAN messages
which do not pass the acceptance filter are checked for errors and acknowledged by the msCAN
module but are not processed in any way, i.e. they are ignored by the driver.
The values assigned to the variables ID_CODEy_CANx determine which CAN message identifiers
will pass the msCAN acceptance filter. A set bit in ID_CODEy_CANx means that the compared bit
in the CAN message arbitration field must be recessive for that bit to pass the acceptance test, and
for the acceptance test to proceed to the next bit. A clear bit in ID_CODEy_CANx means that the
compared bit in the CAN message arbitration field must be dominant for that bit to pass the
acceptance test, and for the acceptance test to proceed to the next bit.
Permitted values for ID_CODEy_CANx are 0 to 0xFF.
E.g.
#define ID_CODE0_CAN0 0x0F
Specifies that the first 4 bits of the CAN message arbitration field must be dominant and the next 4
bits must be recessive for the message to pass the acceptance filter for CAN0 module, if an 8-bit
filter is defined and if ID_CODE0_CAN is equal to 0 (if 16-bit or 32-bit filters are defined the
comparison process continues with the next acceptance code register).
ID_MASKy_CANx
ID_MASKy_CAN0
ID_MASKy_CAN1
24 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

ID_MASKy_CAN2
ID_MASKy_CAN3
ID_MASKy_CAN4
The variables ID_MASKy_CANx specify the acceptance mask register values. For the S12X and
S12G, x is 0 to 7. The values of these variables, together with the acceptance code values, specify
the CAN message arbitration field values which will pass the msCAN acceptance filter, i.e. they
specify which received CAN messages are accepted by the msCAN module. CAN messages which
do not pass the acceptance filter are checked for errors and acknowledged by the msCAN module
but are not processed in any way, i.e. they are ignored by the driver.
The values assigned to the variables ID_MASKy_CANx determine which bits in the corresponding
ID_CODEy_CANx register are used in the comparison with the CAN message identifier field. A
set bit in ID_MASKy_CANx means that the corresponding bit in ID_CODEy_CANx is not
compared with the corresponding bit in the CAN message identifier. A clear bit in
ID_MASKy_CANx means that the corresponding bit in ID_CODEy_CANx is compared with the
corresponding bit in the CAN message identifier.
Permitted values for ID_MASKy_CANx are 0 to 0xFF.
E.g.
#define ID_MASK0_CAN1 0x00
Specifies that all bits of ID_CODE0_CAN0 are compared with the received CAN message
arbitration field bits for a match.
#define ID_MASK1_CAN1 0xFF
specifies that no bits of ID_CODE1_CAN1 are compared with the received CAN message
arbitration field bits.

5.2.2 Message Object Configuration

The Identifier for each message object is defined by the user in the file msCANID.h
For each message object Identifier, the following must be defined:
MOx_ID_TYPE_CAN0 STA NDARD or EXTENDED
MOx_ID_CAN0 Identifier value, 11 bit for Standard or 29 bit for Extended
where x is the message object Identifier number.
Note: Extended Identifiers must have a "L" appended, e.g. 0x12345678L
These values are grouped and stored in an array in ROM. Each message identifier is then referred to
by its Identifier number, i.e. the element of the array which it occupies (x in the above example). Up
to 255 message Identifiers may be defined. For message Identifiers which are transmitted, the
Identifier number specifies the local priority of that message (smallest Identifier number = greatest
local priority). When more than one message buffer is queued for transmission, the driver ensures
that the message with the greatest local priority in the queue is transmitted first.

msCANS12/S12X Driver User Manual, Rev. 0.1 25

Freescale Semiconductor
26 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

Chapter 6

msCANS12/S12X Driver API

6.1 General

This section describes the API functions of the driver in detail. All predefined msCAN driver data
types can be found in 6.2 Data Types.

6.2 Data Types

The following standards are used for variable types.

Table 6-1 Data Types

Mnemonic C type S12 Implementation

uint8 unsigned char unsigned 8 bits

int8 char signed 8 bits

uint16 unsigned int unsigned 16 bits

int16 int signed 16 bits

uint32 unsigned long unsigned32 bits

int32 long signed32 bits

6.3 Constant Definition

There are predefined constant values for some of the data types.
Table 6-2 msCAN Error Return Values (Continued)

Constant Value Value Description

msCANS12/S12X Driver User Manual, Rev. 0.1 27

Freescale Semiconductor
 ERR_OK 0 No error

ERR_MODE 1 Invalid mode argument

ERR_CAN 2 Reserved for future use

ERR_INIT 3 initialization failed

ERR_BOFF 4 msCAN module is in reset state

ERR_NSLP 5 msCAN module is not yet in SLEEP mode

ERR_ID 6 Invalid Identifier argument

ERR_MB 7 Invalid Message Buffer argument

ERR_DLC 8 Invalid number of data bytes specified

ERR_CONFIG 9 Message Buffer is not configured appropriately for

the function concerned

ERR_QED 10 Message Buffer is queued

ERR_NOTQED 11 Message Buffer is not queued

ERR_NODATA 12 Message Buffer has not received any data

ERR_SYNCH 13 msCAN module is not synchronized to the CAN bus

ERR_TS 14 Timestamps are not available

ERR_CHN 15 Wrong msCAN Channel(Module) number

Table 6-3 msCAN Reset Modes

Constant Value Value Description

CMPTX 0 Any active transmission of a Message Object will be

completed before the msCAN enters the reset state

FAST 1 The msCAN will enter the soft reset state

28 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

immediately.

Table 6-4 msCAN Buffer Status

Constant Value Value Description

NODATA 0 NODATAMessage Buffer contains no data.

VALIDDATA 1 A TXDF or AUTOTXDF Message Buffer has been

loaded with data.

QUEUED 2 The Message Buffer has been queued for

transmission, but not yet copied into an msCAN
hardware buffer.

QUEUED2 3 The Message Object has been copied into an msCAN

buffer, ready for transmission.

ABORTREQ 4 The transmission of the Message Buffer has been

requested to be aborted.

ABORTED 5 The transmission of a Message Buffer was

successfully aborted.

TRANSMITTED 6 The Message Buffer has successfully transmitted a

Message Object.

NEWDATA 7 A RXDF Message Buffer contains new data, i.e. has

received one Message Object since it was last read or
configured.

READDATA 8 A RXDF Message Buffer has received a Message

Object which has been read.

OVERRUN 9 A RXDF Message Buffer has received more than one

Message Object since it was last read. The most
recently received Message Object is stored in the
Message Buffer.

Table 6-5 msCAN Buffer Modes

msCANS12/S12X Driver User Manual, Rev. 0.1 29

Freescale Semiconductor
 Constant Value Value Description

CLOSED 0 Close message buffer, i.e. will not transmit or

receive.

RXDF 1 Message buffer will receive Data Frames with

accepted Identifier

TXDF 2 Message buffer will transmit Data Frames

TXRF 3 Message buffer is configured to transmit a Remote

Frame. Once transmitted, this Message buffer will
automatically be reconfigured by the msCAN
Transmit ISR to receive Data Frames.

AUTOTXDF 4 Message buffer will automatically transmit a Data

Frame when a Remote Frame with a matching
Identifier is received.

INVALID 5 Message buffer is not used

Table 6-6 msCAN Error Call Back Register Return Value

Constant Value Value Description

Register_Success 0 Error Call Back function register succeed

Register_Failed 1 Error Call Back function register failed

Unregister_Succes 2 Error Call Back function unregister succeed

s

Unregister_Failed 3 Error Call Back function unregister failed

Table 6-6 ID Type and Frame Type

Constant Value Value Description

ID Type 0 Standard ID (11 Bits)

30 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

ID Type 8 Extended ID (29 Bits)

Frame Types 0 Data Frame

Frame Type 1 Remote Frame

6.4 Driver Services

6.4.1 Init_CAN

Syntax: uint8 Init_CAN(uint8 AChn, uint8 AReMode);

Parameters: AChn — Specify which msCAN module to initialize;

AReMode — Defines the reset mode (see Table 6-3 ):
� CMPTX
� FAST

Return: � ERR_OK — No errors detected.

� ERR_BOFF — msCAN module is bus-off.
� ERR_MODE — Invalid mode specified

Description: This function initializes the msCAN module. This function puts the msCAN module
into the soft reset state in order to access certain registers. Entering the soft reset
state causes the msCAN module to immediately abort any ongoing transmission or
reception of a Message Object. The 'rmode' argument to this function determines
whether the soft reset state is entered immediately or after any ongoing transmission
is completed. While in the reset state, the following msCAN control registers will be
initialized from user defined constants in header file msCANdrv.h: CMCR1,
CBTR0, CBTR1, CIDAC, CIDAR0-7, CIDMR0-7. The msCAN module is then
brought out of the reset state. All Message Buffers will be cleared of data and
configured as CLOSED. This function cannot bring the msCAN module out of the
Bus-off state.

Notes: If the 'mode' argument is assigned a value of CMPTX, this function could take some
time to return. This time could be up to the time required to transmit a complete
CAN message. The COP is NOT refreshed by this function. This function clears the
I-MASK bit in the Condition Code Register.

msCANS12/S12X Driver User Manual, Rev. 0.1 31

Freescale Semiconductor
6.4.2 Reset_CAN

Syntax: uint8 Reset_CAN(uint8 AChn, uint8 AReMode);

Parameters: AChn — Specify which msCAN module to reset;

AReMode — Defines the reset mode (see Table 6-3 ):
� CMPTX
� FAST

Return: � ERR_OK — No errors detected.

� ERR_MODE — Invalid mode specified.

Description: This function puts the msCAN module into the soft reset state. This effectively
disables the msCAN module. Entering the soft reset state causes the msCAN
module to immediately abort any ongoing transmission or reception of a Message
Object. The 'rmode' argument to this function determines whether the soft reset state
is entered immediately or after any ongoing transmission is completed.

Notes: If the 'rmode' argument is assigned a value CMPTX, this function could take some
time to return. This time could be up to the time required to transmit a complete
CAN message. The COP is NOT refreshed by this function.

6.4.3 Sleep_CAN

Syntax: uint8 Sleep_CAN(uint8 AChn, uint8 AReMode);

Parameters: AChn — Specify which msCAN module to go to sleep;

AReMode — Defines the reset mode (see Table 6-3 ):
� CMPTX
� FAST

Return: � ERR_OK — No errors detected.

� ERR_MODE — Invalid mode specified.
� ERR_INIT — initialization failed

Description: This function puts the msCAN module into low-power SLEEP mode when all
queued Message Objects have been transmitted.

32 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

Notes: The argument mode = FAST should not be used.

6.4.4 Wakeup_CAN

Syntax: uint8 Wakeup_CAN(uint8 AChn);

Parameters: AChn — Specify which msCAN module to wake up;

Return: � ERR_OK — No errors detected.

� ERR_NSLP — msCAN is not yet in SLEEP mode.
� ERR_INIT — initialization failed

Description: This function wakes up the msCAN module from SLEEP mode. When woken up,
the msCAN module waits for 11 consecutive recessive bits to synchronize to the
CAN bus.

Notes: If SLEEP mode has been requested (by the CAN_Sleep function) and the msCAN
SLPRQ bit has been set by the driver, the msCAN must enter SLEEP mode before it
can be woken up. If the CAN_Wakeup function detects that the msCAN SLPRQ bit
is set, but the msCAN has not yet entered SL EEP mode (due to ongoing
transmission or reception), it is not possible to prevent the msCAN from entering
SLEEP mode and the error code ERR_NSLP is returned. CAN_ Wakeup should be
called again when the msCAN has entered SLEEP mode.

6.4.5 Check_CAN_Status

Syntax: uint8 Check_CAN_Status(uint8 AChn,uint8 *AStatusPtr);

Parameters: AChn — Specify which msCAN module to clear;

AStatusPtr — Pointer to the user memory buffer where the status data will be
stored, the buffer should be 3 bytes;

Return: ERR_OK — No errors detected.

Description: This function obtains the status of the msCAN module. This function will write the
status of the msCAN module to the address specified in the argument. The status
will be 3 bytes with bits corresponding to the following register names of the
msCAN:

msCANS12/S12X Driver User Manual, Rev. 0.1 33

Freescale Semiconductor
 Byte 0 : CANCTL0

Bit 7 6 5 4 3 2 1 0

RXFRM RXACT CSWAI SYNCH TIME WUPE SLPRQ INITRQ

Byte 1 : CANCTL1

7 6 5 4 3 2 1 Bit 0

CANE CLKSRC LOOPB LISTEN BORM WUPM SLPAK INITAK

Byte 2 : CANRFLG

7 6 5 4 3 2 1 Bit 0

WUPIF CSCIF RSTAT1 RSTAT0 TSTAT1 TSTAT0 OVRIF RXF

Notes: The return value detailed meanings should be found in Data Sheet of msCAN

6.4.6 Clear_CAN_Status

Syntax: uint8 Clear_CAN_Status(uint8 AChn);

Parameters: AChn — Specify which msCAN module to clear;

Return: ERR_OK — No errors detected.

Description: This function clears status flags in CANRFLG register except RXF.

Notes: None

6.4.7 Config_CAN_MB

Syntax: uint8 Config_CAN_MB(uint8 AChn, uint8 ABuffer, uint8 ACmode, uint8

AIdentifierRef)

Parameters: AChn — Specify which msCAN module to configure;

34 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

ABuffer — Specify which message buffer to configure.

ACmode — Defines the Message Buffer mode (see Table 6-5 ):
� CLOSED
� RXDF
� TXDF
� AUTOTXDF
� TXRF
AIdentifierRef — Assigns an Identifier from the Message Identifier Table to the
Message Buffer (lower number = higher local priority).

Return: � ERR_OK — No errors detected.

� ERR_MODE — Invalid mode specified.
� ERR_MB — Invalid message buffer number specified.
� ERR_ID — Invalid message Identifier reference number specified.

Description: This function configures a Message Buffer to receive Data Frames, or transmit Data
Frames or Remote Frames. The Message Buffer is also assigned an Identifier from
the Message Identifier table. The Message Buffer status is set to NODATA. For
Message Buffers which are configured to transmit, the position of the Message
Identifier in the Identifier array specifies the local priority of that Message Buffer:
highest priority (lowest reference number) first. If, when this function is called, the
Message Buffer was configured to transmit Data Frames or Remote Frames, and the
Message Buffer was queued for transmission, the transmission will be aborted.

Notes: None.

6.4.8 Check_CAN_MB_Status

Syntax: uint8 Check_CAN_MB_Status(uint8 AChn, uint8 ABuffer, uint8 *AStatusPtr)

Parameters: AChn — Specify which msCAN module to check;

ABuffer — Specify which message buffer to check.
AStatusPtr — Pointer to the user memory buffer where the status data shall be
stored, the memory buffer should be 2 bytes;

Return: � ERR_OK — No errors detected.

msCANS12/S12X Driver User Manual, Rev. 0.1 35

Freescale Semiconductor
 � ERR_MB — Invalid message buffer number specified..

Description: This function obtains the status and mode of the specified Message Buffer. The
status value is written to the address specified by status and the mode value is
written to the address status + 1.
Status will have one of the values defined in Table 6-4 .
Mode will have one of the values defined in Table 6-5 .

Notes: None.

6.4.9 Load_CAN_MB

Syntax: uint8 Load_CAN_MB ( uint8 AChn, uint8 ABuffer, uint8 *ADataPtr);

Parameters: AChn — Specify which msCAN module to load;

ABuffer — Specify which message buffer to write data to.
ADataPtr — Pointer to data where the first byte is DLC (0 to 8), followed by data
bytes.

Return: � ERR_OK — No errors detected.

� ERR_MODE — Invalid mode specified.
� ERR_CONFIG — Message buffer is not configured to transmit or auto-transmit
Data Frames.
� ERR_QED — Message Buffer is still queued.
� ERR_DLC — Invalid number of data bytes specified.

Description: This function loads a Message Buffer with data. The data is copied from the address
specified to the specified Message Buffer. The specified address must contain the
data length code (DLC), less than or equal to 8, and the immediately following
addresses contain the data bytes. The number of data bytes copied into the Message
Buffer will equal the value of DLC, with a maximum of 8. The Message Buffer
status is set to VALIDDATA. It is not permitted to write to a Message Buffer if the
Message Buffer is queued for transmission, i.e. the previous transmission request
has not completed or has not been aborted. A Message Buffer configured to
AUTOTXDF must be loaded with data before it can automatically be transmitted in
response to a received Remote Frame with a matching Identifier.

Notes: None.

36 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

6.4.10 Transmit_CAN_MB

Syntax: uint8 Transmit_CAN_MB(uint8 AChn, uint8 ABuffer);

Parameters: AChn — Specify which msCAN module to transmit;

ABuffer — Specify which message buffer to transmit.

Return: � ERR_OK — No errors detected.

� ERR_INIT — initialization failed
� ERR_BOFF — msCAN is in bus-off state.
� ERR_MB — Invalid message buffer number specified.
� ERR_CONFIG — Message buffer is not configured to TXDF or TXRF.
� ERR_NODATA — Message buffer has not been loaded with data.
� ERR_QED — Message Buffer is still queued: previous transmission has not
completed or abort request has not been acknowledged.
� ERR_SYNCH — msCAN module is not synchronized to the CAN bus.

Description: This function schedules a Message Buffer for transmission. The Message Buffer
status is checked to see that the previous transmission of this Message Buffer was
completed or aborted. If a msCAN transmit buffer is not available (all are already
filled with messages for transmission), the Message Buffer is queued until a msCAN
buffer becomes available. The Message Buffer status is set to QUEUED during this
time. The local priority of the Message Object in the Message Buffer is compared to
the local priority of the Message Objects already in the msCAN buffers. If the local
priority is greater than any Message Object in the msCAN buffers, the msCAN
buffer with the lowest local priority Message Object is requested to be aborted.
When an msCAN transmit buffer is available, the Message Identifier and data are
copied into the msCAN buffer and the msCAN buffer is scheduled for transmission.
The Message Buffer status is set to QUEUED2 during this time. If the specified
msCAN module is in SLEEP mode, it is woken up. If the Sleep request flag is set
then it is cleared. When the Message Object has been successfully transmitted, the
Message Buffer status is set to TRANSMITTED.

Notes: When a Message Buffer configured to TXRF has successfully transmitted the
Remote Frame, the Message Buffer will automatically be reconfigured to RXDF in
order to receive Data Frames.

msCANS12/S12X Driver User Manual, Rev. 0.1 37

Freescale Semiconductor
6.4.11 Abort_CAN_MB

Syntax: uint8 Abort_CAN_MB(uint8 AChn, uint8 ABuffer);

Parameters: AChn — Specify which msCAN module to abort;

ABuffer — Specify which message buffer to transmit.

Return: � ERR_OK — No errors detected.

� ERR_INIT — initialization failed
� ERR_MB — Invalid message buffer number specified.
� ERR_CONFIG — Message buffer is not configured to TXDF or TXRF.
� ERR_NOTQED — Message Buffer is not queued for transmission.

Description: This function requests that the transmission of a queued Message Buffer is aborted.
If the Message Buffer status is QUEUED, the Message Buffer is removed from the
queue and the status is set to ABORTED. If the Message Buffer status is
QUEUED2, i.e. the Message Object has already been transferred to a msCAN
buffer, an abort request is issued to the msCAN module. The Message Buffer status
is set to ABORTREQ during this time. If the transmission is successfully aborted,
the Message Buffer status is set to ABORTED. Otherwise the Message Object is
transmitted and the Message Buffer status is set to TRANSMITTED.

Notes: None

6.4.12 Read_CAN_MB_Data

Syntax: uint8 Read_CAN_MB_Data(uint8 AChn, uint8 ABuffer, uint8* ADataPtr);

Parameters: AChn — Specify which msCAN module to operate;

ABuffer— Specify which message buffer to transmit.
ADataPtr — Pointer to data where the first byte is DLC (0 to 8), followed by data
bytes

Return: � ERR_OK — No errors detected.

� ERR_MB — Invalid message buffer number specified.
� ERR_CONFIG — Message buffer is not configured to RXDF.
� ERR_NODATA — Message Buffer has not received a Data Frame.

38 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

Description: This function reads the data in a Message Buffer. This function copies the data in the
Message Buffer to the address specified. The data consists of the Data Length Code
followed by the data bytes. This function will only read a Message Buffer
configured to receive Data Frames and which has received a Data Frame since it
was last configured (buffer status = NEWDATA, READDATA or OVERRUN).
After reading the data, the buffer status will be changed to READDATA. The
msCAN receive interrupt will be masked during the data copy operation.

Notes: None

6.4.13 Read_CAN_MB_Time

Syntax: uint8 Read_CAN_MB_Time(uint8 AChn, uint8 ABuffer, uint16 *ADataPtr);

Parameters: AChn — Specify which msCAN module to operate;

ABuffer — Specify which message buffer to transmit.
ADataPtr — Pointer to data where the first byte is DLC (0 to 8), followed by data
bytes

Return: � ERR_OK — No errors detected.

� ERR_MB — Invalid message buffer number specified.
� ERR_CONFIG — Message buffer is configured to closed.
� ERR_NODATA — Message Buffer has not received or transmitted a Message
Object.
� ERR_TS — The Time Stamp option has not been selected.

Description: This function reads the time stamp in a Message Buffer. This function copies the
time stamp in the Message Buffer to the address specified. This function will only
read a Message Buffer which has received a Data Frame since it was last
configured, or transmitted a Data Frame since it was last loaded with data. The
msCAN receive interrupt and transmit interrupts will be masked during the data
copy operation. This function will return an error if TIMESTAMP_CANx = FALSE.
This function does not change the status of the Message Buffer.

Notes: None

msCANS12/S12X Driver User Manual, Rev. 0.1 39

Freescale Semiconductor
6.4.14 Read_Rec_Err_Counter

Syntax: uint8 Read_Rec_Err_Counter (uint8 AChn, uint8* Rec_Err_Counter)

Parameters: AChn — Specify which msCAN module to check

Rec_Err_Counter — Specify where to store the receive error counter number

Return: � ERR_OK — No errors detected.

� ERR_CHN — The msCAN module not exists or not used.
� ERR_MODE — Invalid mode specified.
� ERR_INIT — Initialization of the msCAN module failed.
� ERR_NSLP — msCAN module is not yet in SLEEP mode.

Description: This function reads the Receive Error Counter for the requested msCAN module.
The function copy the value of msCAN Receive Error Counter to Rec_Err_Counter.
To get the accurate value of the register, this function will make the requested
module enter sleep mode and then copy the value, then wake up the module.

Notes: The error number is between 0 to 255;

6.4.15 Read_Tran_Err_Counter

Syntax: uint8 Read_Tran_Err_Counter (uint8 AChn, uint8* Tran_Err_Counter)

Parameters: AChn — Specify which msCAN module to check

Tran_Err_Counter — Specify where to store the transmit error counter number

Return: � ERR_OK — No errors detected.

� ERR_CHN — The msCAN module not exists or not used.
� ERR_MODE — Invalid mode specified.
� ERR_INIT — Initialization of the msCAN module failed.
� ERR_NSLP — msCAN module is not yet in SLEEP mode.

Description: This function reads the Transmit Error Counter for the requested msCAN module.
The function copy the value of msCAN Transmit Error Counter to
Tran_Err_Counter.

40 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

To get the accurate value of the register, this function will make the requested
module enter sleep mode and then copy the value, then wake up the module.

Notes: The error number is between 0 to 255;

6.4.16 Read_REALTIME_Buffers

Syntax: uint8 Read_REALTIME_Buffers(uint8 AChn, uint32* ID, uint8* ID_Type, uint8*

Frame_Type, uint8* DLC, uint8* Data, uint16* TimeStamp)

Parameters: AChn — Specify which msCAN module to read

ID — Specify where to store the ID of received frame
ID_Type — Specify where to store the ID Type of received frame
Frame_Type — Specify where to store the Frame_Type of received frame
DLC — Specify where to store the DLC of received frame
Data — Specify where to store the Data bytes of received frame, it should be as
long as the DLC or 8 bytes. The rest bytes (if DLC<8) makes no sense.
TimeStamp — Specify where to store the TimeStamp of received frame (The
TimeStamp for this msCAN module is enabled in msCANcfg.h, the Parameter
TimeStamp get the real time, and if TimeStamp disabled, The Parameter get a value
of 0xFFFF;

Return: � ERR_OK — No errors detected.

� ERR_CHN — The msCAN module not exists or not used.

Description: If user wants to receive a frame but don’t know the ID and type in advance, he could
use the function to read the received message.
This function will store all received message at once in a buffer and refresh if
another frame received, the function will add cpu load and receive latency, so the
function is disabled by default

Notes: To use the function, REAL_TIME_BUFFER_ENABLE should be defined as TRUE

in msCANcfg.h.

6.4.17 Register_
Register_CCallback

msCANS12/S12X Driver User Manual, Rev. 0.1 41

Freescale Semiconductor
Syntax: uint8 Register_Callback(const uint8 AChn, const pErr_Callbacks_User_Def
FUN_User_Def)

Parameters: AChn — Specify which msCAN module the registered callback function is related
to.
FUN_User_Def — Specify the callback function, the function should be the type of
pErr_Callbacks_User_Def

Return: � ERR_CHN — The msCAN module not exists or not used.

� Register_Success — The register for the module succeeded.
� Register_Failed — The register for the module failed

Description: The function is used to register an error callback function for msCAN module,
When registered, the callback function will be entered if error interrupts occur.

Notes: The Error callback function is defined by user, the parameter of callback function is
ERR_Status which is defined as follows. The return value is void. User can do some
operation according to the error status.

Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0

CSCIF RSTAT1 RSTAT0 TSTAT1 TSTAT1 OVRIF 0 0

6.4.18 Unregister_
Unregister_ Callback
egister_C

Syntax: uint8 Unregister_Callback(const uint8 AChn)

Parameters: AChn — Specify which msCAN module to delete the callback function.

Return: � ERR_CHN — The msCAN module not exists or not used.

� Unregister_Success — The unregister for the module succeeded.
� Unregister_Failed — The unregister for the module failed

Description: The function is used to unregister an predefined error callback function for msCAN
module,
When unregistered, the callback function will no longer be entered if error interrupts
42 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

occur.

Notes: Unregister operation makes no means if corresponding callback function not

registered.

msCANS12/S12X Driver User Manual, Rev. 0.1 43

Freescale Semiconductor
44 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

Chapter 7

Building Application

7.1 MCU Resources Usage

The following MCU resources are used by driver and must not be used by the user application code:
� msCAN module registers and interrupt vectors
� TXCAN pin (must be connected to the CAN Transceiver Tx pin)
� RXCAN pin (must be connected to the CAN Transceiver Rx pin)

7.2 Physical Interface Connection

It is assumed that the MCU is connected to the CAN bus by means of the Physical Interface (CAN
transceiver). The MCU to CAN Physical Interface connection is shown in Figure 7-1

Figure 7-1. Physical Interface Connection

For further required connection to the CAN transceiver refer to the CAN transceiver reference manual.

7.3 CAN Network Setup

There are couple of physical media which can be used for a CAN network implementation. The
most common CAN physical media is a 5V twisted pair media with differential signal transmission.
An example of a CAN high speed network implementation with twisted pair media is shown in
Figure 7-2.

msCANS12/S12X Driver User Manual, Rev. 0.1 45

Freescale Semiconductor
 Figure 7-2. High speed CAN network

For further information a bout CAN physical media refer to ISO11898 or to the CAN transceiver
reference manual.
For a correct transmission of a CAN message two CAN nodes are required in a CAN network
because the transmitted CAN message has to be acknowledge. If a CAN message has not been
acknowledged then the sending node will re-send the message until an acknowledge has been
detected.

7.4 Compilation

There are source files supplied with the library, which must be compiled:
Common files:
� Start12.c (start up code provided by CodeWarrior)
Application files:
� vector.c (vector table)
� main.c (application code)
msCAN Driver files:
� msCANdrv.c
� msCANgv.c
� msCANID.c
The recommended compiler versions are CodeWarrior IDE version 5.9.0 for S12 and S12X . If
other versions ar e used, problems might arise.

7.5 Linking

The driver object files are linked to the rest of the application by including the object files. A file

46 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

containing startup code is also required.

msCANS12/S12X Driver User Manual, Rev. 0.1 47

Freescale Semiconductor
48 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

Appendix A

msCAN Driver Usage

A.1 Driver Initialization

The msCAN module must be initialized after a MCU reset by calling the driver API Init_CAN. This
will initialize the msCAN module with values specified in the file msCANdrv.h. After the function
Init_CAN has returned the msCAN module will synchronize to the CAN bus and will then be ready
to participate in CAN communication with other nodes. The data for initializing the msCAN
module is defined in the file msCANdrv.h.

A.2 Message Buffer Initialization and Configuration

This driver employs generic message buffers. Up to 255 message buffers each module may be
defined. Each message buffer must be configured by the application program before it can be us
ed. Each message buffer consists of the following elements:
� Identifier Reference (1 byte)
� Mode (1 byte)
� Status (1 byte)
� Data Length Code (1 byte)
� Data (8 bytes)
� Time Stamp (2 bytes, only if TIMESTAMP_CANx = TRUE)
Each message buffer thus requires 12 bytes of RAM without a time stamp, or 14 bytes of RAM
with a time stamp.
The driver function CAN_Init initializes the mode of all Message Buffers to CLOSED. Before a
Message Buffer can receive or transmit any messages, it must be configured by calling the function
Config_CAN_MB. This function is used to specify a mode and a message Identifier for a particular
Message Buffer. Refer to Table 6-5 for the Message Buffer modes.
The Identifier is assigned to a Message Buffer by specifying the Identifier number from the list in
the file msCANID.h.
Tip: The speed efficiency of the receive ISR is improved by:
� using lower numbered msCAN modules,
� disable realtime function of receive frames

msCANS12/S12X Driver User Manual, Rev. 0.1 49

Freescale Semiconductor
� using lower numbered Message Buffers to receive Data Frames,
� using the lowest numbered Mess age Buffers to receive the most frequent Data Frames.

Example

This snippet of code will initialize the msCAN module with the values defined in file msCANdrv.h.
If there are no errors, Message Buffers 0 to 7 of Module 0 are configured to receive Data Frames
with Identifiers that match Message Object Identifiers 0 to 7 and Message Buffers 8 to 15 of
Module 0 are configured to transmit Data Frames with Identifiers that match Message Object
Identifiers 8 to 15.
uint8 i;
/* init msCAN0 buffers */
if( Init_CAN (0,FAST) == ERR_OK)
{
for(i = 0; i < 8; i++)
{
/* Configure message buffers */
Config_CAN_MB(0, i, RXDF, i, 0);
Config_CAN_MB(0, i + 8, TXDF, i + 8, 0);
}
}

A.3 Transmitting a Data Frame

To transmit a Data Frame, a Message Buffer mode must first be configured to TXDF by calling the
function Config_CAN_MB. This function also assigns the Identifier to the Message Buffer and sets
the status to NODATA. All Data Frames transmitted by this Message Buffer will have the Identifier
assigned at this stage (the Message Buffer may be reconfigured to transmit a different Identifier).
Next, data must be written into the Message Buffer by calling the function Load_CAN_MB. One of
the arguments of this function is an address where the data is to be copied from. This address must
contain the DLC, and the following addresses must contain the number of data bytes specified by
the DLC. After the Message Buffer has been loaded with data, the Message Buffer status is
VALIDDATA. The Data Frame may now be queued for transmission by calling the function
Transmit_CAN_MB, specifying the Message Buffer number. Whilst it is queued for transmission,
the Message Buffer status is QUEUED whilst waiting to be transferred into a msCAN buffer, and
QUEUED2 when it is in a msCAN buffer. When the Data Frame has been transmitted successfully,
the status of the Message Buffer changes to TRANSMITTED. This Message Buffer may then be
50 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

used to:
� Retransmit the original message, i.e. identical Identifier and data. Do this by calling
Transmit_CAN_MB specifying the Message Buffer number.
� Transmit a new message with the original Identifier and new data. Do this by calling
Load_CAN_MB to load in new data, and then calling Transmit_CAN_MB to transmit the new
message.
� Transmit a new message with a new Identifier and new data. Do this by calling
Config_CAN_MB to specify a new Identifier number, then calling Load_CAN_MB to load in
new data, and then calling Transmit_CAN_MB to transmit the new message.
A Message Buffer cannot be reconfigured or reloaded with data whilst it is queued for transmission,
the Frame must either be transmitted or the transmission aborted with the abort_CAN_mb function.
Note: When more than one Message Buffer is queued for transmission, the driver ensures that the
message with the greatest local priority in the queue is transmitted first. The local priority is
defined by the Identifier number (smallest Identifier number = greatest local priority).

Example

This snippet of code will configure Message Buffer 1 of msCAN 0 to transmit Data Frames. The
Message Buffer is loaded with 6 bytes of data (data[0] = 6) and if there are no errors, the Message
Buffer is queued for transmission.
int err_status; //To store the return value of the driver APIs.
uint8 data[7] = { 6, 0, 0xff, 0, 0xff, 0, 0xff }; //data to be
transmitted
EnableInterrupts;
err_status = Init_CAN(0,FAST); //Initialize msCAN module 0
err_status = Config_CAN_MB (0, 1, TXDF, 0); //Set msCAN module 0 buffer
1 to be TXDF and the corresponding message object is object 0
if(Load_CAN_MB(0, 1, data) == ERR_OK)
{
/* Transmit message buffer */
Transmit_CAN_MB (0, 1); // Send msCAN module 0 buffer 1
}

A.4 Receiving a Data Frame

To receive a Data Frame, a Message Buffer mode must first be configured to RXDF by calling the
function Config_CAN_MB. This function also assigns the Identifier to the Message Buffer. This
msCANS12/S12X Driver User Manual, Rev. 0.1 51
Freescale Semiconductor
means that only data from received messages which pass the acceptance filter and with an Identifier
which matches the Identifier assigned to a Message Buff er, will be stored in that Message Buffer.
Initially, when configured to RXDF, the status of the Message Buffer will be NODATA. When a
message with a matching Identifier is received, the driver will copy the data and DLC into the
corresponding Message Buffer and the status will be updated to NEWDATA. The data may now be
read from the buffer by calling the function Read_CAN_MB_Data or read_mb_data. After the data
has been read, the status of the Message buffer becomes READDATA until another new message is
received. A Message Buffer of status READDATA may be re-read. If a Message Buffer of status
NEWDAT A receives another message before it is read, the new data will overwrite the previous
data and the status of the Message Buffer becomes OVERRUN. Each subsequent new message will
overwrite the previous data, the stat us will remain at OVERRUN until the Message Buffer is read.
Note: The speed efficiency of the receive ISR is improved by:
� using lower numbered Message Buffers to receive Data Frames.
� using the lowest numbered Mess age Buffers to receive the mo st frequent Data Frames.

Example

This snippet of code will configure Message Buffer 0 of msCAN module 0 to receive Data Frames
with an Identifier which matches Message Object 0. The code then continuously attempts to read
the Message Buffer in a loop until the Message Buffer receives a Data Frame. When a Data Frame
is received into the Message Buffer, the Read_CAN_MB_Data successfully reads the data.
uint8 data[9];
/* Configure message buffer 0 */
Config_CAN_MB(0, 0, RXDF, 0);
/* Wait until new data has been received in message buffer 0 */
while (buffer_status[0] != NEWDATA) //Wait for the Receive ISR to
finish and change the buffer status, NEWDATA indicates that the buffer
has receive a new data
{ //check buffer status
err_status = check_CAN_mb_status(0, 0, buffer_status);
}
err_status = Read_CAN_MB_Data(0, 0, data); //Copy the received data
in msCAN channel 0 buffer 0 to data;

A.5 Transmitting a Remote Frame

52 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

To transmit a Remote Frame, a Message Buffer mode must first be configured to TXRF by calling
the function Config_CAN_MB. This function also assigns the Identifier to the Message Buffer. No
data is loaded into the Message Buffer as data is not transmitted by a Remote Frame. The Remote
Frame is then transmitted by calling the function Transmit_CAN_MB, specifying the Message Buff
er number. Whilst it is queued for transmission, the Message Buffer status is QUEUED whilst
waiting to be transferred into an msCAN buffer, and QUEUED2 when it is in a msCAN buffer.
When the Remote Frame has been transmitted, the driver reconfigures the Message Buff er mode to
RXDF and the status to NODATA. The assigned Identifier is unchanged. This is so that the Message
Buffer can be used to receive the Data Frame expected as a reply to the Remote Frame.

Example

This snippet of code will configure Message Buffer 8 to transmit a Remote Frame. The code then
continuously attempt to read the Message Buffer in a loop until th e Message Buffer receives a Data
Frame
in reply to the Remote Frame. When a Data Frame is received into the Message Buffer, the
Read_CAN_MB_Data successfully reads the data.
int err_status; //To store the return value of the driver APIs.
uint8 data_rec[9]; //To store the received frame for remote frame
EnableInterrupts;
err_status = Init_CAN(0,FAST); //Initialize msCAN module 0
//Set msCAN module 0 buffer 1 to be TXRF and the corresponding message
object is object 0
err_status = Config_CAN_MB (0, 1, TXRF, 0);
/* transmit remote message */
Transmit_CAN_MB (0, 1); // Send msCAN module 0 buffer 1
while (buffer_status[0] != NEWDATA) //Wait for the Receive
ISR to finish and change the buffer status, NEWDATA indicates that the
buffer has receive a new data
{ //Use this API to get the status of buffer
err_status = check_CAN_mb_status(0, 1, buffer_status);
}
err_status = Read_CAN_MB_Data(0, 1, data_rec); //copy data

msCANS12/S12X Driver User Manual, Rev. 0.1 53

Freescale Semiconductor
A.6 Automatic Reply to a Remote Frame

To configure a Message Buffer to automatically reply to Remote Frames, the function

Config_CAN_MB is called with the argument AUTOTXDF as the specified mode and also
specifying an Identifier number.
The Message Buffer must then be loaded with data by calling Load_CAN_MB. Now, when a
Remote Frame is received and accepted, and the Identifier matches the assigned Identifier of the
AUTOTXDF Message Buffer, that Message Buffer is automatically queued for transmission.

Example

This snippet of code will configure Message Buffer 8 of msCAN 0 to automatically transmit Data
Frames in response to received Remote Frames with an Identifier which matches Message Object 0.
UINT8 data[] = {8,7,6,5,4,3,2,1,0};
/* Configure message buffer 8 */
Config_CAN_MB(0, 8, AUTOTXDF, 0);
/* Load message buffer 8 with data */
Load_CAN_MB(0, 8, data);

A.7 Time Stamp

This driver is capable of storing a time stamp with each transmitted and received message. The time
stamp consists of a 16-bit time r value from a specific timer module. The exact timer module may
vary between MCU's. The time stamp value is captured at the end of the End Of Frame of a CAN
message, i.e. at the point at which if no errors have been detected, the message is considered valid.
To enable time stamps, the variable TIMESTAMP_CAN in file msCANdrv.h must be defined as
TRUE. To read the time stamp value for a particular Message Buffer, call the function
Read_CAN_MB_Data or Read_CAN_MB_Time.

A.8 Low Power Modes

In applications where low current consumption is important, it may be necessary to shut-down

part or all of the micro-controller during periods when no processing is required. There are different
levels of reduced power consumption: WAIT mode, STOP2 and STOP3 mode. These modes are
entered by executing the WAIT and STOP instructions respectively. Normal processing is resume d
when a reset or an interrupt occurs. For the differences between STOP2 and STOP3 modes check
the MCU reference manual.

54 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

SLEEP mode is a low power mode which applies to the msCAN module only and is independent
of the MCU mode. In SLEEP mode, the msCAN is shut down in a controlled manner. Transmission
and reception of CAN messages is halted. However, the CANRX input pin remains active and if a
transition is detected on the CAN bus the msCAN module will wake-up and function normally after
11 recessive bits have been detected. A CAN message which wakes up the msCAN module is
therefore not received or acknowledged, but the next message is (unless the MC U was in STOP
mode). The msCAN is requested to enter SLEEP mode by calling the function CAN_Sleep. The
function CAN_ CheckStatus should be used to verify that the msCAN has entered SLEE P mode.
The msCAN is woken up from SLEEP mode either by detecting a transition on the CAN bus or
by calling the function CAN_Wakeup or CAN_TransmitMB. In the case when the msCAN is
woken up by a transition on the CAN bus, this will also wake up the MCU from WAIT mode or
STOP3 mode but not from STOP2 mode. The msCAN has a wake-up filter which may be used to
limit the minimum transition period which will wake-up the msCAN. This is activated by the
WU_FILTER_CAN variable in the file msCANdrv.h
In WAIT mode, the CPU and certain other peripheral modules are not clocked, i.e. no longer
function. Some modules may be programmable to function or not in WAIT mode. The
msCANS12 may be programmed to function or not in WAIT mode by means of the CSWAI bit,
which is controlled by the CSWAI_CAN variable in the file msCANdrv.h. In both cases, the
msCANS12 may be put in SLEEP mode prior to entering WAIT mode (in the case of msCAN not
clocked in WAIT mode, it is recommended to put the msCANS12 in SLEEP mode prior to
entering WAIT mode). If the msCAN is put into SLEEP mode prior to entering WAIT mode, then
a transition on the CAN bus will also wake up the MCU from WAIT mode.
In STOP3 mode, the MCU oscillator is shut down and so no modules are clocked. Note that it may
take a significant period of time (100's of microseconds or milliseconds, depending on the crystal)
for the MCU to recover from STOP3 mode due to the start-up time of the oscillator. No CAN
messages can be received during this time. It is recommended to put the msCAN in SLEEP mode
prior to entering STOP3 mode. If the msCAN is put into SLEEP mode prior to entering STOP3
mode, then a transition on the CAN bus will also wake up the MCU from STOP3 mode.
In STOP2 mode, the MCU oscillator is shut down and so no modules ar e clocked. furthermore all
pin are latched to the state prior entering STOP2 mode. The msCAN cannot wake up the MCU from
STOP2 in any cases since the msCAN is in powerdown mode during the MCU is in STOP2 mode.

A.9 Reserved Keywords

REAL_TIME_BUFFER_ENA MC9S12XEP100 CAN_STANDARD

BLE_CANx

no_of_mb_CANx MC9S12G128 CAN_EXTENDED

Err_Callback_Enable MSCANx CAN_IDE

msCANS12/S12X Driver User Manual, Rev. 0.1 55

Freescale Semiconductor
 Err_Callback_Enable MSCAN_CHANNELS_MAX CAN_SRTR

TIMESTAMP_CANx MSCANx_ADDR DATAFRAME

CLKSRC_CANx CANx_USED BUSCLK

PRESCALER_CANx no_of_mb_CANx MCGERCLK

TIME_SEG1_CANx TIMESTAMP_CAN MSCAN_ENABLE

TIME_SEG2_CANx TIMESTAMP_CANx TX_buff0

RJW_CANx CANCTL0_CANx TX_buff1

LISTEN_CANx CANCTL1_CANx TX_buff2

CANENABLE_CANx CANBTR0_CANx AF32BIT

SAMPLEX3_CANx CANBTR1_CANx AF16BIT

CSWAI_CANx no_of_ID_CANx AF8BIT

WU_ENABLE_CANx MOy_ID_TYPE_CANx AFCLOSED

WU_FILTER_CANx MOy_ID_CANx SLEEP

ACC_FILTER_CANx MOy_IDR_CANx IMASK

ID_CODE0_CANx CAN_STANDARD NO_OF_FILTER_REG

ID_CODE1_CANx CAN_EXTENDED no_of_msCAN_TXbuffer

ID_CODE2_CANx CAN_IDE TRUE

ID_CODE3_CANx CAN_CHN_USED FALSE

ID_CODE4_CANx CAN0_CHN_COUNT INITRQ

ID_CODE5_CANx CAN01_CHN_COUNT SLPRQ

ID_CODE6_CANx CAN012_CHN_COUNT WUPE

ID_CODE7_CANx CAN0123_CHN_COUNT TIME

56 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

ID_MASK0_CANx CAN_CHN_COUNT SYNCH

ID_MASK1_CANx CAN0_BUFFER_COUNT CSWAI

ID_MASK2_CANx CAN01_BUFFER_COUNT RXACT

ID_MASK3_CANx CAN012_BUFFER_COUNT RXFRM

ID_MASK4_CANx CAN0123_BUFFER_COUNT INITAK

ID_MASK5_CANx CAN_BUFFER_COUNT SLPAK

ID_MASK6_CANx CAN0_ID_COUNT RXF

ID_MASK7_CANx CAN01_ID_COUNT OVRIF

CAN012_ID_COUNT TSTAT0

CAN0123_ID_COUNT TSTAT1

CAN_ID_COUNT RSTAT0

RSTAT1

CSCIF

WUPIF

BUSOFF

RXFIE

OVRIE

TSTATE0

TSTATE1

RSTATE0

RSTATE1

CSCIE
msCANS12/S12X Driver User Manual, Rev. 0.1 57
Freescale Semiconductor
 WUPIE

IDR0

IDR1

IDR2

IDR3

DSR

DLR

TBPR

(x=0, 1, 2, 3, 4; y=0, 1, … , 254)

58 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

Appendix B

Sample Application

B.1 Sample Description

In the sample projects, find the file sample.c, user can choose which DEMO to run by define
Macro “Demo_To_Run” as different DEMO numbers.
In the DEMO for MC9SXEP100, following DEMO are provided:
Note: The DEMO board of XEP100 has a Oscillator of 16M and is configured to work at 40M and
the Message Objects is configured in advance.

DEMO Macro Details

Demo_Transmit_DataFrame Transmit a dataframe through a msCAN channel

Demo_Receive_DataFrame Receive a expected dataframe through a msCAN

channel

Demo_Receive_DataFrame_Random Receive an unexpected dataframe through a

msCAN channel

Demo_Get_TimeStamp Reads the time stamp in a Message Buffer

Demo_RemoteFrame_Automatic_Function Auto-reply to received Remote Transmission

Request Frames

Demo_Get_msCAN_Status Get the status of a msCAN channel

Demo_Sleep_And_Wakeup Make a msCAN channel go to sleep mode and

wake up.

Demo_Get_ERR_Counter Read Transmit Error Counter Register and

Receive Error Counter Register

Demo_Abort_Transmission Abort a queued transmit buffer

Demo_Callback_Functions Register a Callback_Function and use it

Demo_TransmitReceive_with_MS9S12G Use MC9S12XEP100 to communicate with

msCANS12/S12X Driver User Manual, Rev. 0.1 59

Freescale Semiconductor
 MC9S12G in dataframes

Demo_Remote_Frame_with_MS9S12G Use MC9S12XEP100 to communicate with

MC9S12G in remote frames

In the DEMO for MC9S12G, following DEMO are provided:

Note: The DEMO board of MC9S12G has a Oscillator of 8M and the Message Objects is
configured in advance.

DEMO Macro Details

Demo_Transmit_DataFrame Transmit a dataframe through a msCAN channel

Demo_Get_msCAN_Status Get the status of a msCAN channel

Demo_Sleep_And_Wakeup Make a msCAN channel go to sleep mode and

wake up.

Demo_Get_ERR_Counter Read Transmit Error Counter Register and

Receive Error Counter Register

Demo_Abort_Transmission Abort a queued transmit buffer

Demo_Callback_Functions Register a Callback_Function and use it

Demo_TransmitReceive_with_XEP100 Use MC9S12G to communicate with

MC9S12XEP100 in dataframes

Demo_Remote_Frame_with_MC9S12XEP100 Use MC9S12G to communicate with

MC9S12XEP100 in remote frames

B.2 Sample Building and Running

To build the sample, CodeWarrior software should be installed on the computer. For supported
compiler and debugger versions.
The sample comes with a CodeWarrior project that allows simple access to all files and ready
configured code generation settings. The project is called sample.mcp .

60 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

B.3 CodeWarrior Project

This chapter shows how to build a new project and use the msCAN driver in it step by step.
Take the S12XEP100 for example.
Step 1. Copy“msCAN Driver”file to your project’s file

Step 2. Copy“vector.c”file (in Sample->Sources) to the“Source”file in your project and edit it if

you use other MCU.

Step3. Add these files above to your project in CodeWarrior

Step4. Include“msCANdrv.h”in“main.c”, then make it

msCANS12/S12X Driver User Manual, Rev. 0.1 61

Freescale Semiconductor
Appendix C Further Information

C.1 Application Notes

Following Application notes are useful during developing a CAN application:

• AN2283 — Freescale Scalable Controller Area Networks (msCAN) Interrupts
• AN1798 — CAN Bit Timing Requirements
• AN2255 — MSCAN low Power Applications

C.2 Online Training

Freescale msCANS12 Online Training is available on www.freescale.com

62 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

Appendix D

D.1 Performance Characteristics and Memory Consumption

Table 1 shows the on-chip resources required for operation of this driver
Table 1. Required Resources

Parameter Value

Required peripheral use At least one MSCAN module and up to all MSCAN modules on the
MCU

Table 2 shows the different configurations for performance test for S12XEP100.
Table 2 configurations for performance test

Module Buffer
Configurations Bit-rate Detail
Number Number

C-1 1 16 125kbps 1 Low

Speed CAN

C-2 3 16 125kbps 2 Low

Speed CAN
1 High
Speed CAN
(Not Used)

C-3 1 16 500kbps 1 High

Speed CAN

C-4 3 16 500kbps 3 High

Speed CAN

C-5 5 16 500kbps 3 High

Speed CAN
2 Low
Speed CAN

msCANS12/S12X Driver User Manual, Rev. 0.1 63

Freescale Semiconductor
 (Not Used)

C-6 1 16 1mbps 1 High

Speed CAN

C-7 3 16 1mbps 3 High

Speed CAN

C-8 5 16 1mbps 3 High

Speed CAN
2 Low
Speed CAN
(Not Used)

Table 3 shows the different configurations for performance test for S12G.
Table 3 configurations for performance test

Module Buffer
Configurations Bit-rate Detail
Number Number

C-a 1 16 125kbps 1 High

Speed CAN

C-b 1 16 500kbps 1 High

Speed CAN

C-c 1 16 1Mbps 1 High

Speed CAN

C-d 1 32 1Mbps 1 High

Speed CAN

Figure D-1 and D-2 shows the CAN topology map of the test hardware platform for S12XEP100
and S12G. The other chips in S12 family basically the same.

64 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor
`

D-1 S12XEP100 Test Platform

D-2 S12G Test Platform

Test Tool Description —— AutoCAN Main features

Measurement
� Support of CAN2.0A, CAN2.0B
� Support of standard frame and extended frame according to ISO11898 specification
� Support of high-speed CAN, fault-tolerant CAN and single wire CAN, with configurable timing
parameters
msCANS12/S12X Driver User Manual, Rev. 0.1 65
Freescale Semiconductor
 � Support of monitoring, hardware in the loop simulation and off-line simulation of network nodes
� The creation, modification of CAN bus database file (DBC file type)
� Support of real-time display of message list and signal waveform
� Transmission of sophisticated signal waveform using trigger, timer and scripts
� Bus error detection and error position report

Logging and playback

� Message logging with filter and super large log file analyze
� Playback of message log both on line and off line

Simulation
� C script programming support for each simulated node
� Support of simulation events such as CAN message, timer, simulation variables change
� Up to 8 simulated networks are supported simultaneously
� Creation of simulation panels

Automated Test
� Test engine and report engine integrated
� Standalone test script editor
� Control of CANspider and other test equipment’s by scripts

Miscellaneous
� Multi-language support
� Automation server supports CAN bus operation by other application or scripts

AutoCAN Brief Introduction

Table 4 shows the performance of the driver when compiled using CodeWarrior for S12XEP100.
The CPU speed of the S12XEP100 is 40Mhz in the test.
Table 5 shows the performance of the driver when compiled using CodeWarrior for S12G.
66 msCANS12/S12X Driver User Manual, Rev. 0.1
Freescale Semiconductor
`

The CPU speed of the S12G is 24Mhz in the test.

In all examples of S12XEP 100, the CAN bus is 100% loaded at 125kbits/s to 1Mbits/s and the
S12XEP100 is operating at 40MHz while S12G 24MHz, The Test Board of MC9S12XEP100 is
equipped with 5 msCAN modules, and 2 of them is LOW SPEED CAN and 3 of them is HIGH
SPEED CAN. The Test Board of MC9S12G is equipped with 1 HIGH SPEED CAN .
The data size depends on the total number of msCAN module used and message buffers of each
module. For each message buffer in use the driver will allocate 14 bytes of RAM. Each msCAN
module supports 0~255 buffers.
Maximum latency (Transmit) is the time latency between the point of sending a frame to the
moment of start of the frame.Transmit latency is approximately one message length in the worst
case.
Maximum execution time (Transmit) is the time used to send out a data frame. It includes the time
of the Transmit API of certain channel. Maximum execution time (Receive) is the time used to
Receive a data frame and store to the right buffer. It includes the time of the Receive API of all
channel used and CPU load will increase with the number of MSCAN modules in use. To get the
Maximum execution time (Receive), the received Frame is not matched in msCAN Message
Objects, so the API will search all the buffers and cost the most of time and result in a longest
receive latency.
For the purposes of measuring driver performance, the case loading scenario is used. For a receive
buffer this occurs when a CAN message is received whose ID does match one of the message
buffers. Transmit buffers then send a Frame out. For this example, the driver both receives and
transmits, the loading is the sum of the receive load and the transmit load. In all cases, The CPU
Load is measured when the CAN bus is 100% loaded.

Table 4. msCAN Driver Performance and required Resources

Maximum
Maximum Execution
Confi CPU
Data
gurati Code Size Transmit Time
Size Load
ons
Latency
Transmit Receive

C-1 2873 286

~17 µs 11 µs 23 µs ~2.1%
bytes bytes

C-2 2919 826

~21 µs 11 µs 45 µs ~3.3%
bytes bytes

C-3 2873 286 ~12 µs 11 µs 23 µs ~9.3%

msCANS12/S12X Driver User Manual, Rev. 0.1 67
Freescale Semiconductor
 bytes bytes

C-4 2919 826

~12 µs 11 µs 67 µs ~18.3%
bytes bytes

C-5 2970 1366

~12 µs 11 µs 67 µs ~18.3%
bytes bytes

C-6 2873 286

~11 µs 11 µs 23 µs ~18.6%
bytes bytes

C-7 2919 826

~11 µs 11 µs 67 µs ~39.3%
bytes bytes

C-8 2970 1366

~11 µs 11 µs 67 µs ~39.3%
bytes bytes

Table 5. msCAN Driver Performance and required Resources

Maximum
Maxim
Conf um Execution
Code Data CPU BUS
igura Time
Size Size Transmit Load Load
tions
Latency
Transmit Receive

C-a 2952 279

~25µs 32 µs 62 µs ~9.1% ~81%
bytes bytes

C-b 2952 279

~25 µs 32 µs 62 µs ~11.2% ~22%
bytes bytes

C-c 2952 279

~24µs 32 µs 62 µs ~9% ~10%
bytes bytes

C-d 2952 503

~24µs 32 µs 130µs ~9% ~10%
bytes bytes

Note that: for high speed transmission, the 100% bus load is hard to get, so in this cases, the CPU
Load and the BUS load is all listed for user to have a comprehension of the CAN Driver
performances.

68 msCANS12/S12X Driver User Manual, Rev. 0.1

Freescale Semiconductor