wind net can - pudn.comread.pudn.com/downloads153/doc/comm/671972/windnet_can_progra… · 2.11.2...

1.4

WIND NET CAN

Programmer’s Guide

®

D R A F T

Copyright 2004 Wind River Systems, Inc.

All rights reserved. No part of this publication may be reproduced or transmitted in any form or by any means without the prior written permission of Wind River Systems, Inc.

Wind River, the Wind River logo, Tornado, and VxWorks are registered trademarks of Wind River Systems, Inc. Any third-party trademarks referenced are the property of their respective owners. For further information regarding Wind River trademarks, please see:

http://www.windriver.com/company/terms/trademark.html

This product may include software licensed to Wind River by third parties. Relevant notices (if any) are provided in your product installation under the following directory: installDir/docs/pdf/3rd_party_licensor_notice.

Corporate HeadquartersWind River Systems, Inc.500 Wind River WayAlameda, CA 94501-1153U.S.A.

toll free (U.S.): (800) 545-WINDtelephone: (510) 748-4100facsimile: (510) 749-2010

For additional contact information, please visit the Wind River URL:

http://www.windriver.com

For information on how to contact Customer Support, please visit the following URL:

http://www.windriver.com/support

WIND NET CAN Programmer’s Guide, 1.4 26 Apr 04 Part #: DOC-15262-ZD-00

http://www.windriver.com/company/terms/trademark.html

http://www.windriver.com

http://www.windriver.com/support

Draft: 26 Apr 04 iii

Contents

1 Overview ............................................................................................... 1

1.1 Introduction ............................................................................................................. 1

1.2 Using This Manual ................................................................................................. 2

1.3 CAN ........................................................................................................................... 3

1.4 WIND NET CAN API ............................................................................................ 3

1.5 CAN Device Topology ........................................................................................... 4

2 Getting Started Tutorial ....................................................................... 7

2.1 Introduction ............................................................................................................. 8

2.2 Before You Begin .................................................................................................... 9

2.3 Building the WIND NET CAN Standard and Debug Libraries ................... 10

2.4 Obtaining a Configurable VxWorks Image ...................................................... 13

2.5 Configuring a VxWorks Image with WIND NET CAN .................................. 15

2.5.1 Adding WIND NET CAN Components ............................................... 15

2.5.2 Setting Properties for a CAN Board Component ................................ 17

WIND NET CANProgrammer’s Guide, 1.4

iv Draft: 26 Apr 04

2.6 Verifying Your CAN Hardware Switches .......................................................... 21

2.7 Building, Booting, and Verifying Your VxWorks Image ................................ 21

2.8 WIND NET CAN Sample Application .............................................................. 23

2.8.1 Routines ..................................................................................................... 23

2.8.2 Editing #defines ........................................................................................ 24

2.9 Building the Sample Application ....................................................................... 24

2.10 Downloading the Sample Application .............................................................. 27

2.11 Using the Sample Application ............................................................................. 28

2.11.1 Multiple VxWorks Targets ...................................................................... 28

2.11.2 CANalyzer or Similar CAN Bus Monitoring Device .......................... 28

2.11.3 Running the Sample Application ........................................................... 29

2.12 Configuration Details ............................................................................................ 32

3 WIND NET CAN Programming ............................................................ 33

3.1 Introduction ............................................................................................................. 34

3.2 WIND NET CAN API ............................................................................................ 34

3.3 Opening and Initializing a CAN Device ........................................................... 36

3.4 Setting the Bit Timings and the Baud Rate ....................................................... 38

3.5 Starting and Stopping a CAN Device ................................................................. 39

3.6 Controller Level Interrupts ................................................................................... 39

3.7 Transmitting ............................................................................................................ 40

3.8 Receiving .................................................................................................................. 41

3.9 Interrupts .................................................................................................................. 42

3.9.1 Installing an ISR Callback Routine ........................................................ 42

Contents

Draft: : 26 Apr 04 v

3.9.2 Enabling Interrupts .................................................................................. 43

3.9.3 Transmission Interrupt Processing ........................................................ 43

3.9.4 Receive Interrupt Processing .................................................................. 47

3.9.5 Other Interrupt Processing ..................................................................... 50

3.10 Closing a CAN Device Session ............................................................................ 51

3.11 Advanced Functionality ........................................................................................ 51

3.11.1 Filters .......................................................................................................... 51

3.11.2 Remote Messages ..................................................................................... 53

3.11.3 Wake and Sleep ......................................................................................... 56

3.11.4 Polling ........................................................................................................ 56

3.11.5 Pre-initialization ....................................................................................... 56

4 Device I/O Interface .............................................................................. 59

4.1 Introduction ............................................................................................................. 59

4.2 Device Names .......................................................................................................... 60

4.3 I/O Interfaces ........................................................................................................... 60

4.4 Using a Controller .................................................................................................. 61

4.4.1 Opening a Controller Device .................................................................. 61

4.4.2 Configuring a Controller ......................................................................... 62

4.4.3 Configuration Data Structures ............................................................... 64

WNCAN_BUSINFO ................................................................................ 64WNCAN_CONFIG .................................................................................. 64WNCAN_CTRLCONFIG ........................................................................ 66

4.4.4 Reading and Writing a Controller .......................................................... 66

4.4.5 Using the Select Facility with a Controller ........................................... 67

4.4.6 Closing a Controller ................................................................................. 67

4.5 Using a Channel ..................................................................................................... 67


vi Draft: 26 Apr 04

4.5.1 Opening a Channel Device ..................................................................... 67

4.5.2 Configuring a Channel ............................................................................ 68

4.5.3 Configuration Data Structures ............................................................... 70

WNCAN_CHNCONFIG ......................................................................... 70

4.5.4 Writing to a Channel ................................................................................ 71

WNCAN_CHNMSG ................................................................................ 71

4.5.5 Reading from a Channel .......................................................................... 71

4.5.6 Using the Select Facility with a Channel .............................................. 72

4.5.7 Closing a Channel .................................................................................... 72

4.6 Examples .................................................................................................................. 72

5 Driver Developer Kit ............................................................................. 77

5.1 Introduction ............................................................................................................. 77

5.2 Organization ............................................................................................................ 78

5.3 Templates ................................................................................................................. 79

5.3.1 Terminology .............................................................................................. 79

5.3.2 Conventions .............................................................................................. 79

5.3.3 Preparation ................................................................................................ 80

5.3.4 Porting to a New Board ........................................................................... 81

5.3.5 Porting to a Controller ............................................................................. 82

5.3.6 Porting Issues ............................................................................................ 83

5.4 Conformance Tests ................................................................................................. 83

5.4.1 Preparation ................................................................................................ 84

5.4.2 Offline Tests ............................................................................................... 84

5.4.3 Online Tests ............................................................................................... 85

5.4.4 Manual Tests ............................................................................................. 86

Filter Test ................................................................................................... 86Remote Response ..................................................................................... 87

Contents

Draft: : 26 Apr 04 vii

Remote Request – Standard ID .............................................................. 89Remote Request – Extended ID .............................................................. 90

A Libraries ................................................................................................ 93

B Routines ................................................................................................ 97

C CAN Board Support ............................................................................. 135

C.1 Introduction ............................................................................................................. 136

C.2 CAN Board Identifiers .......................................................................................... 136

C.3 Supported CAN Board/Processor Configurations ........................................... 137

C.4 ADLINK 7841 .......................................................................................................... 137

C.4.1 ADLINK 7841 Controller Support ......................................................... 138

C.5 Biscayne HCAN2 .................................................................................................... 138

C.5.1 Biscayne HCAN2 Suggested IRQ Setting ............................................. 138

C.5.2 Biscayne HCAN2 Controller Support ................................................... 139

C.6 ESD PC104-200 ........................................................................................................ 139

C.6.1 ESD PC104-200 Suggested I/O Addresses and IRQ Settings ............ 140

C.6.2 ESD PC104-200 Controller Support ....................................................... 140

C.7 ESD PCI/200 ............................................................................................................. 140

C.7.1 ESD PCI/200 Controller Support .......................................................... 141

C.8 MSMCAN PC104 .................................................................................................... 141

C.8.1 MSMCAN PC104 Suggested I/O Addresses and IRQ Settings ........ 141

C.8.2 MSMCAN PC104 Controller Support ................................................... 142

C.8.3 MSMCAN PC104 Limitations ................................................................ 142

C.9 PPC5xx TouCAN ..................................................................................................... 142

C.9.1 PPC5xx TouCAN Suggested IRQ Setting ............................................. 142


viii Draft: 26 Apr 04

C.9.2 PPC5xx TouCAN Controller Support ................................................... 143

C.10 Tahoe-Amanda HCAN2 ......................................................................................... 143

C.10.1 Tahoe-Amanda HCAN2 Suggested IRQ Setting ................................. 143

C.10.2 Tahoe-Amanda HCAN2 Controller Support ....................................... 144

C.10.3 Tahoe-Amanda HCAN2 Transceivers and Connectors ...................... 144

C.11 MCF5282 FlexCAN ................................................................................................. 144

C.11.1 MCF5282 FlexCAN Controller Support ................................................ 145

D CAN Controller Support ...................................................................... 147

D.1 Introduction ............................................................................................................. 147

D.2 Intel 82527 ................................................................................................................ 148

D.3 Phillips SJA 1000 .................................................................................................... 148

D.4 TouCAN .................................................................................................................... 149

D.5 HCAN2 ..................................................................................................................... 149

D.5.1 HCAN2 Limitations ................................................................................. 149

D.5.2 Channel Interrupts ................................................................................... 150

D.5.3 Remote Frames ......................................................................................... 150

D.5.4 Register Access ......................................................................................... 150

D.6 FlexCAN ................................................................................................................... 151

D.6.1 Bit Timing Considerations ...................................................................... 151

D.6.2 B.5.2 FlexCAN Interrupts ........................................................................ 151

E API Equivalents .................................................................................... 155

E.1 Introduction ............................................................................................................. 155

E.2 Common Interfaces ................................................................................................ 156

E.3 CAN Device and Controller Interfaces .............................................................. 156

Contents

Draft: : 26 Apr 04 ix

E.4 CAN Channel Interfaces ....................................................................................... 157

E.5 Controller Specific Interfaces .............................................................................. 158

Index .............................................................................................................. 159


x Draft: 26 Apr 04

Draft: 26 Apr 04

1
Overview
1.2 Using This Manual 2

1.3 CAN 3

1.4 WIND NET CAN API 3

1.5 CAN Device Topology 4

1.1 Introduction

WIND NET CAN is a collection of platform independent CAN (Controller Area Network) device drivers that share a common API. With WIND NET CAN, you develop applications that will use the CAN bus, or create higher level protocols based on CAN, independent of the CAN hardware to be used. This independence allows for greater flexibility and code portability among different platforms and CAN hardware.

1


1.2 Using This Manual

The WIND NET CAN Programmer’s Guide contains the following chapters and appendices:

1. Overview discusses the CAN technology and outlines the major benefits of using the WIND NET CAN API.

2. Getting Started Tutorial gives detailed instructions for building the WIND NET CAN libraries, and for configuring a VxWorks image with WIND NET CAN. It also shows you how to build and run a WIND NET CAN sample application.

3. WIND NET CAN Programming describes the WIND NET CAN API, and provides several examples useful in developing applications with the API.

4. Device I/O Interface describes using the standard VxWorks IOS device interface (open, read, write, etc.) to access CAN devices. This interface is an alternative to the WIND NET CAN API, and is required if using WIND NET CAN within a VxWorks AE Application domain.

5. Driver Developer Kit describes the test wuite included in WIND NET CAN which allows CAN driver developers to verify that teir driver satisfies the WIND NET CAN interface.

A. Libraries documents the libraries that comprise the WIND NET CAN API.

B. Routines documents the routines that comprise the WIND NET CAN API.

C. CAN Board Support contains board-specific information for supported CAN boards.

D. CAN Controller Support contains controller-specific information for supported CAN controllers.

E. API Equivalents provides a mapping between the WIND NET CAN API and the standard VxWorks device driver interface described in Chapter 4. Device I/O Interface.

NOTE: Some CAN-controller documentation uses the term “message buffer” where other CAN-controller documentation uses the term “channel.” This document consistently uses “channel.”

2 Draft: 26 Apr 04

1 Overview1.3 CAN

1
1.3 CAN
CAN is a communications protocol first developed by Robert Bosch GmbH targeting automotive, industrial automation, medical devices, robotics, and other real-time control applications. It is an asynchronous, short distance, priority-based protocol that can run over a variety of mediums (such as fiber optic cable or unshielded twisted pair cable). Additional CAN features include:

■ Management of multiplexed communications between multiple CPUs.

■ Non-destructive bit-wise arbitration to decide which node “owns” the bus.

■ A message priority scheme based on the value of the message identifier transmitted with each message.

■ Operation at baud rates of up to 1 megabit per second.

■ Error detection and confinement capabilities.

1.4 WIND NET CAN API

The WIND NET CAN API is designed to be both generic and flexible so that applications can efficiently utilize the interface without adding excessive overhead (code size or performance degradation). The main purpose of the interface is to decouple hardware dependencies from the protocol layers.

Benefits of Using a Common CAN Interface

■ Protocol and application code can be developed independent of the platform and CAN hardware to be used.

■ Driver level code can be ported to different operating systems and CAN devices without affecting the protocol layers.

■ A modular and layered programming approach to the design of the protocol stacks and device drivers is adopted thereby achieving a high level of portability and testability.

■ Parallel development with internal and external engineering teams is facilitated by clearly establishing areas of responsibility and by simplifying integration efforts.

Draft: : 26 Apr 04 3


■ Development times are reduced by promoting code reuse through sharable CAN libraries.

1.5 CAN Device Topology

Figure 1-1 shows the overall topology of CAN protocols and interfaces. Both applications and protocols use the WIND NET CAN API library of generic CAN I/O functions at the hardware interface. The WIND NET CAN API is described in 3. WIND NET CAN Programming, A. Libraries and B. Routines.

4 Draft: 26 Apr 04

1 Overview1.5 CAN Device Topology

1
Figure 1-1 CAN Device Topology
Application Layer Interface

VxWorks Device I/O

Device Net CANOpen IDB-C

Amanda82527SJA1000

WIND NET CAN API

TouCAN

Protocol Stacks

CAN Controllers



6 Draft: 26 Apr 04

Draft: 26 Apr 04

2
Getting Started Tutorial
2.2 Before You Begin 9

2.3 Building the WIND NET CAN Standard and Debug Libraries 10

2.4 Obtaining a Configurable VxWorks Image 13

2.5 Configuring a VxWorks Image with WIND NET CAN 15

2.6 Verifying Your CAN Hardware Switches 21

2.7 Building, Booting, and Verifying Your VxWorks Image 21

2.8 WIND NET CAN Sample Application 23

2.9 Building the Sample Application 24

2.10 Downloading the Sample Application 27

2.11 Using the Sample Application 28

2.12 Configuration Details 32

7


2.1 Introduction

In this tutorial, you build the WIND NET CAN libraries, configure a VxWorks image with WIND NET CAN, and run a WIND NET CAN sample application.

Tutorial Requirements

The WIND NET CAN Getting Started Tutorial supports the following CAN boards:

■ ESD PC104 200■ ESD PCI 200■ MicroSpace PC104 CAN■ PPC5xx TouCAN

For WIND NET CAN system requirements, see your Wind River Platform getting started guide.

NOTE: Not all WIND NET CAN boards are documented for this tutorial, however, all boards will work with the tutorial.

8 Draft: 26 Apr 04

2 Getting Started Tutorial2.2 Before You Begin

2

2.2 Before You Begin

Tutorial instructions assume some familiarity with Wind River’s Tornado IDE.

Many Tornado development tasks can be accomplished in more than one way. To optimize continuity, this tutorial gives instructions for one way to do each task and omits discussion of alternative methods. Some tasks described can be done more efficiently by additional use of context-sensitive menus and other shortcuts.

A starting point for further information about the Tornado IDE is the Tornado User’s Guide. The Documentation Guide in your product family getting started guide lists additional sources of TORNADO and VxWorks information.

Text Variables

This tutorial uses italicized text to indicate placeholders for text strings that are user specific. Some of these are described below.

■ your_VxWorks_project_name denotes the name of your VxWorks image project.

■ your_VxWorks_project_folder denotes (the full path of) your VxWorks image project

■ your_workspace_name denotes the name of your VxWorks image workspace.

■ your_CAN_board_type denotes one of the following VxWorks CAN component identifiers:

– ADLINK 7841– ESD PC104 200– ESD PCI 200– MicroSpace PC104 CAN– PPC5xx TouCAN– MCF5282 FlexCAN

■ installDir denotes (the full path of) the root folder of your Tornado 2.2 distribution, that is, the location where Tornado libraries, tools, docs, utilities, and other files are stored. In this tutorial, when installDir appears in a line to be input, you should type the full path of your Tornado 2.2 distribution root folder.

■ tornado_dev denotes (the full path of) your Tornado project folder. In this tutorial, when tornado_dev appears in a line to be input, you should type the full path of your Tornado project folder.

We recommend that tornado_dev be a folder outside of installDir.



■ Tornado22 denotes the name of the folder used to install the Tornado launch item for your Tornado 2.2 installation. (To start Tornado, select Start > Programs>Tornado22 >Tornado.)

■ CPU_family is the name of the CPU family. For example, pentium.

■ processor is the name of the processor. For example, PENTIUM.

■ toolchain is the name of the toolchain. For example, gnu.

2.3 Building the WIND NET CAN Standard and Debug Libraries

After installation, a WIND NET CAN library must be built before it can be used with Tornado. Both standard and debug libraries can be built.

Location of the Standard Library

The standard library is put into the following location if you have a default Tornado installation:

installDir/target/lib/CPU_family/processor/toolchain/libwnCAN.a

The object files for the standard library are put into the following location:

installDir/target/lib/CPU_family/processor/toolchain/objwnCAN

Building a Standard Library

To build the WIND NET CAN standard library:

1. Start Tornado. If you have a default installation, from Windows select:

Start > Programs>Tornado22 > Tornado.

NOTE: The standard and debug standard libraries are kept in separate locations. See Building a Debug Library, p.12 for information about how to use the debug library with your application.

10 Draft: 26 Apr 04

2 Getting Started Tutorial2.3 Building the WIND NET CAN Standard and Debug Libraries

2

2. Build the library.

a. With Tornado, select Tools > wnCAN > Build wnCAN Library...(see Figure 2-1)

The Build wnCAN Library dialog is displayed (see Figure 2-2).

b. Select a toolchain.

c. Verify that the Include Debug Info item is cleared (not enabled).

Figure 2-1 Tornado Tools Menu

Figure 2-2 Build wnCAN Library Dialog

Draft: : 26 Apr 04 11


d. Select an Optimization Level.

e. Enable the Rebuild All item (clean and rebuild entire library).

f. Click Build to build the library.

Building a Debug Library

To build the WIND NET CAN debug library for your toolchain, follow the same procedure as the standard library, but this time enable the Include Debug Info item, and set Optimization Level to none.

Using a Debug Library

When a debug library is built using the Build wnCAN Library dialog, an additional wnCAN Debug Library Location dialog appears with the location to your debug library (see Figure 2-4).

NOTE: The makefile used to build the CAN library is invoked from the folder:

installDir/target/src/drv/can

NOTE: If a debug library is to be built, and Optimization Level is NOT none, a warning dialog appears (see Figure 2-3).

Figure 2-3 Debug Optimization Warning

12 Draft: 26 Apr 04

2 Getting Started Tutorial2.4 Obtaining a Configurable VxWorks Image

2

To use the debug library with your project:

1. Right-click on the library location field and select Copy.

2. With your project window, obtain the Properties dialog for your project build item.

3. Click the Libs tab and prepend the copied debug library location to the existing search string.

To subsequently revert to the standard library, remove the debug library location string from the search path.

2.4 Obtaining a Configurable VxWorks Image

To obtain a configurable VxWorks image, use Tornado to either open an existing image or create a new one.

Existing VxWorks Image

To open an existing configurable VxWorks image:

1. From the Tornado menu bar, select File > Open Workspace...The Open Workspace dialog is displayed.

2. Click the Existing tab, and then use the Browse... button to select your image.

Figure 2-4 Debug Library Location Dialog

Draft: : 26 Apr 04 13


New VxWorks Image

To create a new VxWorks image:

1. In the Tornado window, select File > New Project.The Create Project in New/Existing Workspace dialog is displayed.

2. Click the New tab and select Create a bootable VxWorks image (custom configured).

3. Click OK.The project wizard dialog is displayed.

4. In step 1 of the project wizard:

a. In the Name field, enter your_VxWorks_project_name.

b. In the Location field, enter your_VxWorks_project_folder.

c. In the Workspace field, enter: your_VxWorks_project_folder/your_workspace_name.wsp

d. Click Next.

5. In step 2 of the project wizard, base the image on a BSP:

a. Click A BSP.

b. Click the ... (location) button and navigate to your target BSP.

c. From the Tool drop-down list, select the toolchain on which to base your image.

d. Click Next>.

6. In step 3 of the project wizard, click Finish. Project dependencies are generated and a new Workspace is created in the Tornado window.

NOTE: You may need to modify your bootrom to locate the new image.

NOTE: The toolchain selected must be the same as the one used in building the CAN libraries.

14 Draft: 26 Apr 04

2 Getting Started Tutorial2.5 Configuring a VxWorks Image with WIND NET CAN

2

2.5 Configuring a VxWorks Image with WIND NET CAN

In this section, you configure the VxWorks image obtained in 2.4 Obtaining a Configurable VxWorks Image, p.13.

2.5.1 Adding WIND NET CAN Components

1. Click the VxWorks tab at the bottom your Tornado WorkSpace window, and expand the CAN network device nodes as shown in Figure 2-5.

2. Add CAN show routines to the VxWorks image:

a. Right-click on the expanded your_workspace_name>your_VxWorks_project_name VxWorks > network components > CAN network devices > CAN show routines node, and select Include CAN show routines...The Include Componentsdialog is displayed.

b. Click OK in the Include Components dialog.

Draft: : 26 Apr 04 15


3. Add a CAN board component to the VxWorks image:

a. In the Tornado WorkSpace window, find your_CAN_board_type in the list of boards in the CAN network devices folder and right-click on the expanded your_workspace_name > your_VxWorks_project_nameVxWorks >network components > CAN network devices>your_CAN_board_type node, and select Include your_CAN_board_type...

The Include Components dialog is displayed.

b. Click OK in the Include Components dialog.

Figure 2-5 Tornado WorkSpace Window

16 Draft: 26 Apr 04


2

2.5.2 Setting Properties for a CAN Board Component

After adding a CAN board component, you must set properties for that component. Some parameter values set must agree with CAN hardware settings (see 2.6 Verifying Your CAN Hardware Switches, p.21).

To set properties for a CAN board component:

1. Right-click again on the expanded your_workspace_name > your_VxWorks_project_nameVxWorks >network components > CAN network devices>your_CAN_board_type node, and this time select Properties...

The Properties dialog for the your_CAN_board_type component is displayed. Figure 2-6 shows the ESD PC104 200 component Properties dialog as it would appear while setting the number of ESD PC104 200 boards to 1.

NOTE: If your target contains more than one CAN board type, you must configure your VxWorks image for each of the additional CAN board types by adding (see step 3 above) and configuring (see 2.5.2 Setting Properties for a CAN Board Component, p.17 below) the corresponding VxWorks CAN board components.

Figure 2-6 Component Properties Dialog

Draft: : 26 Apr 04 17


2. In the Properties dialog, click the Params tab and set properties as instructed in the section for your_CAN_board_type below.

After setting properties for your_CAN_board_type, click OK to exit the Properties dialog.

ESD PC104 200

If your_CAN_board_type is ESD PC104 200, set the following board parameters:

■ Set the MAX_ESD_CAN_PC104_200_BOARDS parameter to the number of ESD PC104 200 boards installed on your target.

■ Set the ESD_CAN_PC104_200_IOADDRESS parameter to a valid I/O address for your ESD PC104 200 board. If you have more than one ESD PC104 200 board, list an I/O address for each board, separated by spaces. For suggested values, see C.6.1 ESD PC104-200 Suggested I/O Addresses and IRQ Settings, p.140, and your ESD PC104 200 documentation.

■ Set the ESD_CAN_PC104_200_IRQ parameter to a valid IRQ for your ESD PC104 200 board. If you have more than one ESD PC104 200 board, list an IRQ for each board, separated by spaces. For suggested values, see C.6.1 ESD PC104-200 Suggested I/O Addresses and IRQ Settings, p.140, and your ESD PC104 200 documentation.

ESD PCI 200

If your_CAN_board_type is ESD PCI 200, set the following board parameters:

■ Set the MAX_ESD_CAN_PCI_200_BOARDS parameter to the number of ESD PCI 200 boards installed on your target.

MSMCAN PC104

If your_CAN_board_type is MSMCANPC104, set the following board parameters:

■ Set the MAX_MSMCAN_PC104_BOARDS parameter to the number of MSMCAN PC104 boards installed on your target.

■ Set the MSMCAN_PC104_IOADDRESS parameter to a valid I/O address for your MSMCAN PC104 board. If you have more than one MSMCAN PC104 board, list an I/O address for each board, separated by spaces. For suggested values, see C.8.1 MSMCAN PC104 Suggested I/O Addresses and IRQ Settings, p.141, and your MSMCAN PC104 documentation.

■ Set the MSMCAN_PC104_IRQ parameter to a valid IRQ for your MicroSpace PC104 CAN board. If you have more than one MSMCAN PC104 board, list an

18 Draft: 26 Apr 04


2

IRQ for each board, separated by spaces. For suggested values, see C.8.1 MSMCAN PC104 Suggested I/O Addresses and IRQ Settings, p.141, and your MSMCAN PC104 documentation.

PPC5xx TouCAN

If your_CAN_board_type is PPC5xx TouCAN, set the following board parameters:

■ Set the MAX_PPC5xx_CAN_DEVICES parameter to the number of PPC5xx TouCAN controllers installed on your target.

■ Set the PPC5xx_TOUCAN_INTLEVEL parameter to a valid interrupt level for your PPC5xx TouCAN controller. If you have more than one PPC5xx TouCAN controller, list an interupt level for each board, separated by spaces. For suggested values, see your PPC5xx CAN 2.0B controller documentation.

■ Set the PPC5xx_TOUCAN_RXMODE parameter to the receive mode for your PPC5xx TouCAN controller. If you have more than one PPC5xx TouCAN controller, list a receive mode for each controller, separated by spaces. The valid receive modes are 0 (default) and 4. Use 4 only if your controller requires an inverted signal. For more information, see your PPC5xx TouCAN controller documentation.

■ Set the PPC5xx_TOUCAN_TXMODE parameter to the transmit mode for your PPC5xx TouCAN controller. If you have more than one PPC5xx TouCAN controller, list a transmit mode for each controller, separated by spaces. The valid transmit modes are 0 (default) and 1. Use 1 only if your controller transmits an inverted signal. For more information, see your PPC5xx CAN 2.0B controller documentation.

MCF5282 FlexCAN

If your_CAN_board_type is MCF5282 FlexCAN, set the following board parameters:

■ Set the MCF5282_FlexCAN_INTLEVEL parameter to a valid interrupt level for use as the default interrupt level of all interrupt sources of your MCF5282 FlexCAN controller. You can assign a different interrupt level to an individual interrupt source using the routine FlexCAN_SetIntLevel( ) (see [* Xref]).

■ Set the MCF5282_FlexCAN_INTPRIORITY parameter to a valid priority for use as the default priority of all interrupt sources of your MCF5282 FlexCAN controller. You can assign a different priority within a level to an individual interrupt source using the routine FlexCAN_SetIntLevel( ), which sets both an interrupt level and the priority within an interrupt level (see [* Xref]).

Draft: : 26 Apr 04 19


■ Set the MCF5282_FlexCAN_RXMODE parameter to the receive mode for your MCF5282 FlexCAN controller. The valid receive modes are 0 (default) and 1. Use 1 only if your controller requires an inverted signal. For more information, see your MCF5282 FlexCAN controller documentation.

■ Set the MCF5282_FlexCAN_TXMODE parameter to the transmit mode for your MCF5282 FlexCAN controller. The valid transmit modes are 0 (default) and 1. Use 1 only if your controller transmits an inverted signal. For more information, see your MCF5282 FlexCAN controller documentation.

20 Draft: 26 Apr 04

2 Getting Started Tutorial2.6 Verifying Your CAN Hardware Switches

2

2.6 Verifying Your CAN Hardware Switches

Some CAN hardware switches must be set to agree with the parameter setting made above. Consult your CAN board documentation for further instructions on how to verify your hardware settings.

ESD PC104 200

Verify that the I/O address jumper switches are set to agree with the values you entered in 2.5.2 Setting Properties for a CAN Board Component, p.17 above.

ESD PCI 200

There are no switches that must agree with parameter settings on this CAN device.

MicroSpace PC104 CAN

Verify that the I/O address dip switches are set to agree with the values you entered in 2.5.2 Setting Properties for a CAN Board Component, p.17 above.

Verify that the IRQ dip switches are set to agree with the values you entered in 2.5.2 Setting Properties for a CAN Board Component, p.17 above.

PPC5xx TouCAN


MCF5282 FlexCAN


2.7 Building, Booting, and Verifying Your VxWorks Image

1. Build the new image.

a. In your workspace window, click the Files tab.

b. Right-click on the expanded your_workspace_name > your_VxWorks_project_nameFiles node and select Rebuild All (vxWorks).

2. Boot your target (see your Tornado and target documentation for details.)

Draft: : 26 Apr 04 21


3. Create, configure, and launch a target server.

a. From Tornado, select Tools > Target Server > Configure.

The Configure Target Server dialog appears.

b. With the Configure Target Server dialog:

i. Click New.

ii. In the Description field, enter SampleCAN.

iii. Enable the Add description to menu checkbox.

iv. In the Target Server Name field, enter SampleCAN.

v. From the Target Server Properties drop-down list, select Core Symbols and Files.

vi. Select File, and click the ... (location) button and navigate to your_VxWorks_project_folder > default > vxWorks.

vii. From the Target Server Properties drop-down list, select Back End.

viii. From the Available Back Ends scroll list, select wdbrpc.

ix. In the Target Name/IP Address field, enter the IP address of your target.

x. Click Launch to launch the target server and exit the dialog.

A red target icon in the Windows status bar indicates a successful launch of the target server.

4. Launch a WindSh window, and enterWNCAN_Show to verify that the CAN-configured VxWorks image is running on your target.

The call returns information for each of the CAN controllers attached to the target.

22 Draft: 26 Apr 04

2 Getting Started Tutorial2.8 WIND NET CAN Sample Application

2

2.8 WIND NET CAN Sample Application

WIND NET CAN includes a sample application that demonstrates the use of the WIND NET CAN basic API (see Basic API, p.35). The source for the sample application is located at installDir/target/src/demo/CAN/sample.c.

The sample application can be used with most development configurations. As delivered, it can exercise up to two controllers on the first CAN board of each target. (If desired, the sample application can easily be extended to support multiple CAN boards per target).

Instructions are provided for using the sample application in the following configurations:

■ Using one VxWorks target with a dual controller CAN board.

■ Using one or more VxWorks targets (each with a CAN board) AND a Vector Informatik GmbH CANalyzer (or similar CAN bus monitoring device).

■ Using two or more VxWorks targets (each with a CAN board).

2.8.1 Routines

This section describes the sample application routines that can be called from a WindSh. See the sample.c source file for additional documentation.

The following routines all take one argument, the node number. The sample application currently supports nodes 0 and 1 on the first CAN board of a given target. If this argument is omitted, the default, 0, is used.

setupNode( ) opens a CAN device, initializes its controller, sets bit timings to achieve a baud rate of 125K and a sample point at 87.5%, enables all interrupts, sets the global filter to receive all standard CAN IDs, assigns a channel to receive standard messages, and enables channel 14 to receive messages with extended IDs.

startNode( ) brings the CAN device online.

stopNode( ) takes the CAN device offline.

releaseNode( ) aborts CAN communications, takes the CAN device offline, disables and frees all channels, disables all interrupts, and closes the device.

statusNode( ) reports bus status to stdout.

printRxMsg( ) reports received message identifiers and message ID format to stdout.

Draft: : 26 Apr 04 23


2.8.2 Editing #defines

The sample application contains #defines that you may need to edit depending on your CAN board type and development configuration.

NODE_DEVICE denotes the WNCAN_BoardType used by the sample application when opening a WNCAN_Device. NODE_DEVICE should be defined as one of the following: WNCAN_ESD_PC104_200, WNCAN_ESD_PCI_200, WNCAN_MSMCAN, or WNCAN_PPC5XX.

ID0 and ID1 denote the CAN IDs used by controllers 0 and 1 on the first CAN board of your target when transmitting messages. When recompiling the sample application for additional targets, modify these values so that your transmitted CAN IDs are unique.

2.9 Building the Sample Application

In this section, you create a sample application project and build the application.

1. Create a new downloadable project in the existing workspace and call it sampleCAN. Locate it in the folder tornado_dev/sampleCAN, and base it on your toolchain.

2. Add the sample.c source file to your sampleCAN project:

a. In your workspace window, click the Files tab.

b. Right-click on the expanded your_workspace_name>sampleCAN Files node and select Add Files... (see Figure 2-7).

The Add Source File to sampleCAN dialog appears (see Figure 2-8).

c. In the Add Source File to sampleCAN dialog, navigate to:

installDir/target/src/demo/CAN/sample.c

and click Add.

NOTE: If you are using a board not documented in this tutorial, refer to installDir/target/h/CAN/canBoard.h for a listing of all the NODE_DEVICE definitions.

24 Draft: 26 Apr 04

2 Getting Started Tutorial2.9 Building the Sample Application

2

Figure 2-7 Adding a Source File

Figure 2-8 Add Source File Dialog

Draft: : 26 Apr 04 25


3. Edit the sample.c project file.

See 2.8.2 Editing #defines, p.24.

4. Build the sampleCAN project.

In the Files view of your workspace window, right-click on the sampleCAN Files node and select Rebuild All (sampleCAN.out).

An expanded Files view will now look like Figure 2-9.

Figure 2-9 Workspace Window: sampleCAN project after build

26 Draft: 26 Apr 04

2 Getting Started Tutorial2.10 Downloading the Sample Application

2

2.10 Downloading the Sample Application

In this section, you download the sample application to your target.

To download the sample application to your target:

1. If needed, launch the sampleCAN target server, and verify that sampleCAN@your_computer_name is selected in the Tornado Launch toolbar drop-down list.

2. From Tornado, select Project > Download.

The Download Objects dialog is displayed (see Figure 2-10).

3. With the Download Objects dialog, navigate to the following file, and click Download:

tornado_dev/sampleCAN/PENTIUMgnu/sampleCAN.out

Figure 2-10 Download Objects Dialog

Draft: : 26 Apr 04 27


2.11 Using the Sample Application

In this section, you perform additional tasks required for your CAN network configuration, and then use a WindSh to call sample application routines.

2.11.1 Multiple VxWorks Targets

If you are using multiple VxWorks targets, then for each additional target, you will need to configure, build, boot, and verify a VxWorks image, and then edit, build, and download the sample application.

See sections 2.4 Obtaining a Configurable VxWorks Image, p.13 through 2.10 Downloading the Sample Application, p.27 for details. (Use unique target server names for additional targets.)

2.11.2 CANalyzer or Similar CAN Bus Monitoring Device

If you are using a CANalyzer (or similar CAN bus monitoring device) in combination with one or more VxWorks targets, prepare it to transmit and receive messages as outlined below.

Baud Rate and Sample Point

Set your CANalyzer (or similar CAN bus monitoring device) to communicate at a baud rate of 125K, with a sample point at 87.5% of the bit time.

For more information on CiA bit timing recommendations see:

http://www.port.de/engl/canprod/sv_req_form.html

Receiving Messages

If you are using a CANalyzer, open the Trace and the Bus Statistics windows to monitor message traffic on the CAN network. (For details, see your CANalyzer documentation.)

For other CAN bus monitoring devices, set up a method to monitor message traffic on the CAN network.

28 Draft: 26 Apr 04

http://www.port.de/engl/canprod/sv_req_form.html

2 Getting Started Tutorial2.11 Using the Sample Application

2

Transmitting Messages

If you are using a CANalyzer, configure a Generator Block to transmit several messages when triggered, and insert it before the Send block. (For more detail, see your CANalyzer documentation.)

For other CAN bus monitoring devices, set up a method to transmit messages.

CAN Network

Verify that all controllers are connected to form a properly terminated CAN network. (See your CAN board documentation.)

If you are using one VxWorks target with a dual controller CAN board only, you may need to provide a loop back connector between the controllers to create a CAN network. (See your CAN board documentation.)

2.11.3 Running the Sample Application

In this section, you run the sample application by following an outlined procedure.

1. If not already running, launch a target server and open a WindSh for each VxWorks target.

2. Set up the available VxWorks target CAN nodes (controllers).

For each node, enter setupNode(node#) in the corresponding WindSh.

3. Start each node.

For each node, enter startNode(node#) in the corresponding WindSh.

4. Transmit messages from each node.

For each node, enter transmitMsg(node#) several times in the corresponding WindSh.

5. If you are using a CANalyzer (or similar CAN bus monitoring device):

a. Verify (receive) the CAN message traffic.

b. Transmit messages from the CANalyzer (or similar CAN bus monitoring device).

6. Receive messages at each node.

For each node, enter printRxMsg(node#) in the corresponding WindSh. The return from this call shows all messages transmitted from other controllers.

Draft: : 26 Apr 04 29


7. Stop each node.

For each node, enter stopNode(node#) in the corresponding WindSh.

8. Release each node.

For each node, enter releaseNode(node#) in the corresponding WindSh.

In Figure 2-11, we show an example WindSh result of running the sample application with one VxWorks target (all the sample application calls use the default node) and a CANalyzer.

30 Draft: 26 Apr 04

2 Getting Started Tutorial2.11 Using the Sample Application

2

Figure 2-11 Running the Sample Application

Draft: : 26 Apr 04 31


2.12 Configuration Details

The configuration interface for WIND NET CAN may be a bit more complicated than what is normally used for other VxWorks components. The complexity arises from the fact the WIND NET CAN is a source-code component. The component is compiled separately from your project but configured within a project to select specific CAN hardware and WIND NET CAN features for the project. It is incumbent upon you to choose the configuration correctly. Configuration of a CAN board that your target hardware does not have may result in compilation or link errors of your project. Also, even if the code compiles and links, without the proper hardware installed on your target board, it is likely that your application will fail to run on your target board.

Referring back to Figure 2-5, the following describes the configuration components of WIND NET CAN.

■ CAN core initialization: Provides initialization of the core WIND NET CAN code. This component is automatically included when you configure any board component.

■ CAN device I/O interface: Enables the device I/O standard interface to WIND NET CAN devices.

■ CAN show routines: Enables the device show routines.

■ CAN boards: The set of components representing supported boards for WIND NET CAN. You can choose one or more boards for a given application.

■ CAN support components: This component folder contains private components. Certain boards need special initialization needed to operating within a VxWorks application. These components are automatically included when the associated board component is added to the application.

The typical configuration method for WIND NET CAN consists of 1) selecting one or more CAN boards; 2) optionally selecting the show or device I/O interface components; 3) examining any board component parameters and changing as needed.

It is recommended that WIND NET CAN be configured in a VxWorks bootable image. Downloaded modules can use the API and do not require any WIND NET CAN configuration.

32 Draft: 26 Apr 04

Draft: 26 Apr 04

3
WIND NET CAN Programming
3.1 Introduction 34

3.2 WIND NET CAN API 34

3.3 Opening and Initializing a CAN Device 36

3.4 Setting the Bit Timings and the Baud Rate 38

3.5 Starting and Stopping a CAN Device 39

3.6 Controller Level Interrupts 39

3.7 Transmitting 40

3.8 Receiving 41

3.9 Interrupts 42

3.10 Closing a CAN Device Session 51

3.11 Advanced Functionality 51

33


3.1 Introduction

This chapter describes the WIND NET CAN API, and provides several examples useful in developing applications with the API.

For a synopsis and description of each API routine, see B. Routines.

Getting Started Tutorial

For detailed instructions on getting started with WIND NET CAN, including building the WIND NET CAN libraries, configuring a VxWorks image for CAN, and running a sample application, see 2. Getting Started Tutorial.

Hardware Support

For CAN hardware support and hardware-specific information see C. CAN Board Support and D. CAN Controller Support.

3.2 WIND NET CAN API

The WIND NET CAN API is a hardware abstraction layer, which allows a CAN application to be developed independent of:

■ the CAN controller used (Phillips SJA1000, Motorola TOUCAN, ...)

■ the VxWorks target processor (Pentium, PowerPC, ...)

■ the communication mechanism (PCMCIA, PCI,...) between the CAN controller and the processor

The API is logically partitioned into four distinct classes of API routines and interfaces: basic, advanced, utility, and device I/O.

NOTE: In addition to the common basic, advanced, and utility routines listed below, the WIND NET CAN API contains one controller-specific routine, TouCAN_SetPropseg( ), for setting the propseg bit timing argument of the TouCAN controller.

34 Draft: 26 Apr 04

3 WIND NET CAN Programming3.2 WIND NET CAN API

3

Basic API

The basic API routines implement the basic functionality provided by the CAN drivers. These routines are listed below:

Advanced Routines

The advanced API routines provide expanded functionality that will not be required for most applications. The extended functionality is of two forms:

■ advanced CAN messaging concepts (example: RTR messaging)

■ manual inspection and modification of CAN driver status information (example: CAN mode). This second type of advanced routine is included in case they are needed within a specific application.

The advanced API routines are listed below:

CAN_Open( ) CAN_Tx( )CAN_Init( ) CAN_TxMsg( )CAN_Start( ) CAN_TxAbort( )CAN_Stop( ) CAN_SetIntMask( )CAN_Close( ) CAN_EnableInt( )CAN_SetBitTiming( ) CAN_DisableInt( )CAN_GetRxChannel( ) CAN_ReadID( )CAN_GetTxChannel( ) CAN_WriteID( )CAN_EnableChannel( ) CAN_ReadData( )CAN_DisableChannel( ) CAN_WriteData( )CAN_FreeChannel( ) CAN_InstallISRCallback( )CAN_GetIntStatus( )

NOTE: A sample application is provided with WIND NET CAN that contains examples of use for each of the WIND NET CAN API basic routines. See 2.8 WIND NET CAN Sample Application, p.23.

CAN_SetMode( ) CAN_SetRTR( )CAN_GetMode( ) CAN_Sleep( )CAN_GetRTRRequesterChannel( ) CAN_WakeUp( )CAN_GetRTRResponderChannel( ) CAN_IsRTR( )CAN_SetLocalMsgFilter( ) CAN_SetGlobalRxFilter( )

Draft: : 26 Apr 04 35


Utility Routines

The utility API routines provide functionality used by the basic routines, and can also be invoked directly from your CAN application. These routines are listed below:

Device I/O Interface

This interface follows the standard VxWorks I/O system interface for hardware devices. For more details, refer to 4. Device I/O Interface.

3.3 Opening and Initializing a CAN Device

This section discusses the WIND NET CAN API functionality related to opening and initializing a CAN device.

Use CAN_Open( ) to create, initialize, and obtain a pointer to a WNCAN_Device structure. The WNCAN_Device pointer uniquely identifies a CAN controller and is used as an argument for all subsequent CAN API routines.

The CAN_Open( ) prototype is:

struct WNCAN_Device *CAN_Open(

UINT brdType,UINT brdNdx,UINT ctrlNdx

);

brdType identifies the type of device opened (i.e. WNCAN_ESD_PC104_200, WNCAN_ESD_PCI_200, ...). The value of this argument should match one of the supported device types given in the header file CAN/canBoard.h.

CAN_GetBusStatus( ) CAN_GetBaudRate( )CAN_GetBusError( ) CAN_GetXtalFreq( )CAN_GetMessageLength( ) CAN_GetControllerType( )CAN_WriteReg( ) CAN_IsMessageLost( )CAN_ReadReg( ) CAN_GetNumChannels( )CAN_GetLocalMsgFilter( ) CAN_ClearMessageLost( )CAN_GetGlobalRxFilter( ) CAN_GetVersion( )

36 Draft: 26 Apr 04

3 WIND NET CAN Programming3.3 Opening and Initializing a CAN Device

3

brdNdx is a zero based number that identifies an instance of a particular device type. For example, brdNdx = 0 is the first CAN board of the specified device type, brdNdx = 1 is the second CAN board of the same device type, and so on.

ctrlNdx is a zero based number that identifies an instance of a controller on the board being opened.

The following example uses CAN_Open( ) to open the second controller of the third ESD PCI 200 board:

UINT brdNdx = 2;UINT ctrlNdx = 1;struct WNCAN_Device *devPtr = NULL;devPtr = CAN_Open(WNCAN_ESD_PCI_200, brdNdx, ctrlNdx);

If the return of CAN_Open( ) is NULL, an error occurred. A likely cause is that the board is not installed. Use errnoGet( ) and the status error codes defined in CAN/wnCAN.h to diagnose the problem.

The following code sample illustrates use of errnoGet( ) when CAN_Open( ) fails:

if (devPtr == NULL){

if ((errnoGet() == S_can_unknown_board)printf("Unknown board.\n");

else if ( another test )...

}

Displaying Installed CAN Hardware

If you have included the “show routines” component in your configuration, you can display a list of installed CAN hardware. After rebuilding and restarting VxWorks, invoke WNCAN_Show( ) from a WindSh to display CAN boards and controllers currently connected to the VxWorks target. WNCAN_Show( ) returns the information needed to call CAN_Open( ).

Initializing a CAN Controller

Initialize the CAN controller with the CAN_Init( ) call. This step must be performed before most other CAN API calls are possible.

Draft: : 26 Apr 04 37


3.4 Setting the Bit Timings and the Baud Rate

Set the controller bit timings and baud rate using CAN_SetBitTiming( ).

The bit timing settings of a CAN controller determine its baud rate and sample point. Both the baud rate and the sample point must be consistent across the CAN network to ensure proper communications.

You should set the arguments to this routine based on established recommendations.

There is also a controller-specific routine, TouCAN_SetPropseg( ), for setting the propseg bit timing argument of the TouCAN controller.

The following example code shows how to set the bit timing arguments of CAN_SetBitTiming( ) for several baud rates based on CiA (CAN in Automation) recommendations.

/****************************************************************************SetBaudRate - set the baud rate according to CiA recommendations.** This routine sets the baud rate of the specifed CAN device to one of 4 * predetermined settings according to the rate parameter value:** rate = 0 -> 125 kbits/s* 1 -> 250 kbits/s* 2 -> 500 kbits/s* 3 -> 1000 kbits/s** RETURNS: OK or ERROR** ERRNO: N/A*/static STATUS BaudRateSet(struct WNCAN_Device *pDev, /* Pointer to CAN device */int rate /* baud rate index */){STATUS retVal = OK;

switch (rate){case 0: /* 125 Kbits/s */

CAN_SetBitTiming(pDev,0x0c,0x01,0x03,0);break;

case 1: /* 250 Kbits/s */CAN_SetBitTiming(pDev,0x0c,0x01,0x01,0); break;

NOTE: The PPC5xx TouCAN controller contains a half speed bit that affects the setting of baud rates. For details, see D.4 TouCAN, p.149.

38 Draft: 26 Apr 04

3 WIND NET CAN Programming3.5 Starting and Stopping a CAN Device

3

case 2: /* 500 Kbits/s */CAN_SetBitTiming(pDev,0x0c,0x01,0,0);break;

case 3: /* 1000 Kbits/s */CAN_SetBitTiming(pDev,0x04,0x01,0,0);break;

default:logMsg("Unknown bit rate.\n",0,0,0,0,0,0);retVal = ERROR;break;

}return (retVal);

}

3.5 Starting and Stopping a CAN Device

Use CAN_Start( ) to bring a device online, and CAN_Stop( ) to take it offline. A device must be online before it can transmit or receive.

Stopping a CAN device is often done in conjunction with a standard sequence of calls from the CAN API. For an example of a such a call sequence, see 3.10 Closing a CAN Device Session, p.51.

3.6 Controller Level Interrupts

Controller level interrupts are set with CAN_SetIntMask( ).

Enable interrupts (at the controller level) with CAN_EnableInt( ).

Disable interrupts (at the controller level) with CAN_DisableInt( ).

Disabling interrupts is often done in conjunction with a standard sequence of calls from the CAN API. For an example of a such a call sequence, see 3.10 Closing a CAN Device Session, p.51.

Draft: : 26 Apr 04 39


3.7 Transmitting

Perform the following steps to transmit a message. Transmission only occurs after starting the controller.

1. Obtain an available channel for transmission. Use the CAN_GetTxChannel( ) API call to return a channel number used in subsequent API calls.

if (CAN_GetTxChannel(pDev, &chnTx) != OK) printf("No available Tx channels\n");

2. Enable the channel. Use the CAN_EnableChannel( ) API call to enable the channel and configure the use of interrupts for the channel.

CAN_EnableChannel(pDev, chnTx, WNCAN_INT_TX);

3. Transmit the message. Use CAN_TxMsg( ) to transmit the message (the controller must already be started).

CAN_TxMsg(pDev, chnTx, id, FALSE, data, 6);

4. Determine when the transmission completes. You must not use the channel until the transmission completes. It is recommended that you configure the channel for Tx interrupt and install an ISR callback. See 3.9 Interrupts, p.42.

An alternative to step 3 above can be used. The CAN_WriteID( ), CAN_WriteData( ), and CAN_Tx( ) calls are equivalent to the single CAN_TxMsg( ) call. For example:

CAN_WriteID(pDev, chnTx, id, FALSE);CAN_WriteData(pDev, chnTx, data, 6);CAN_Tx(pDev, chnTx);

is equivalent to:

CAN_TxMsg(pDev, chnTx, id, FALSE, data, 6);

By de-coupling the configuration of the channel (CAN_WriteID( ) and CAN_WriteData( )) from initiating transmission (CAN_Tx( )), you gain more flexibility by reusing invariant channel configurations. This technique can be used to configure transmission before starting the controller or to reuse an existing transmit channel with a slightly different configuration. The following example repeatedly transmits the same CAN message ID with different data.

40 Draft: 26 Apr 04

3 WIND NET CAN Programming3.8 Receiving

3

CAN_Start(pDev)CAN_WriteID(pDev, chnTx, id, FALSE);for(data = 0; data < 100; data += 10){ CAN_WriteData(pDev, chnTx, (UCHAR*)&data, sizeof(data)); CAN_Tx(pDev, chnTx);

...wait until transmission is completed...}

Like CAN_TxMsg( ), CAN_Tx( ) can only be used after the controller is started. However, CAN_WriteID( ) and CAN_WriteData( ) can be used before the controller is started.

3.8 Receiving

Perform the following steps to receive a message. Reception only occurs after starting the controller.

1. Obtain an available channel for reception. Use CAN_GetRxChannel( ) to return a channel number used in subsequent API calls.

if (CAN_GetRxChannel(pDev, &chnRx) != OK) printf("No available Rx channels\n");

2. Configure the channel with the CAN ID to receive. Use CAN_WriteID( ) to set the channel with the desired CAN ID.

CAN_WriteID(pDev, chnRx, id, FALSE);

Optionally, program the local filter for the channel. The filter is used to allow the channel to receive multiple CAN IDs. Typically, you do not need to do this. By default, the channel will receive only messages having the exact CAN ID.

3. Enable the channel for reception with CAN_EnableChannel( ). The channel now begins to receive messages.

CAN_EnableChannel(pDev, chnRx, WNCAN_INT_RX);

There are some important details regarding reception of messages.

■ Once an Rx channel is enabled and the controller is started, messages will be received.

■ On most controllers, once the Rx channel is enabled, you cannot change the CAN ID. It is recommended that if you need to change the CAN ID, first

Draft: : 26 Apr 04 41


disable the channel with CAN_DisableChannel( ), write a new CAN ID, then enable the channel.

■ You should process the reception of a message as quickly as possible. Until the received message has been processed, subsequent messages with that same CAN ID will not be received. Thus, you can lose messages if you are tardy with reception processing.

■ It is expected that you install an ISR callback function to process the received messages.

■ If you enable the channel without using interrupts, you must properly detect and acknowledge the received message. This may require accessing the controller registers directly using CAN_ReadReg( ) and CAN_WriteReg( ).

3.9 Interrupts

Interrupts are a fundamental component of the WIND NET CAN API. They automatically handle all of the controller-specific processing required to acknowledge a transmission or reception. All you need to do is provide code to process the channel causing the interrupt.

The following sections describe the use of interrupts with a WIND NET CAN application.

3.9.1 Installing an ISR Callback Routine

To install an ISR callback routine, use CAN_InstallISRCallback( ).

The ISR callback routine is invoked whenever the CAN controller generates a CPU interrupt. The ISR callback routine is useful for implementing user defined message processing schemes within the CAN ISR.

42 Draft: 26 Apr 04

3 WIND NET CAN Programming3.9 Interrupts

3

Write the callback routine with the following interface:

void myIsrCallBackFunc(

struct WNCAN_Device *pDev, /* pointer to a WNCAN_Device */WNCAN_IntStatus intStatus, /* the interrupt status */UCHAR chnNum /* channel number of interrupt */

){

user’s ISR message processing code};

3.9.2 Enabling Interrupts

You must configure and enable interrupts before an interrupt can occur. By default, interrupts are disabled. Most controllers support selecting which interrupts you want to process. Use CAN_SetIntMask( ) to select your interrupts, followed by CAN_EnableInt( ) to enable the interrupts.

pDev = CAN_Open( ... );CAN_Init(pDev);CAN_InstallISRCallback(pDev, myIsrCallBackFunc);CAN_SetIntMask(pDev, WNCAN_INT_ALL);CAN_EnableInt(pDev);CAN_Start(pDev);

3.9.3 Transmission Interrupt Processing

Before you can reuse a transmit channel, you must know when it is safe to do so. The easiest method for detecting when a channel has completed transmission is with interrupts and your callback routine. Exactly what you do within your callback depends on how you intend to subsequently use the channel. Regardless, each controller will automatically handle the low-level details of acknowledging the interrupt. Therefore, within your callback, you do not need to access controller-specific registers or change the interrupt status. Described below are two possible cases of handling transmission interrupts. Please, note that only the relevant pieces of code are illustrated. For example, error handling is not shown.

NOTE: An additional interrupt code, WNCAN_INT_TXCLR, is generated when the transmit channel has been unlocked and is available for immediate retransmission. This is currently only used in support of the Device I/O interface.

Draft: : 26 Apr 04 43


Multiple Transmit Channels

The first case involves a sequence of message transmission. This technique uses a separate channel for each transmission.

void myIsrCallBackFunc(struct WNCAN_Device *pDev, /* pointer to a WNCAN_Device */WNCAN_IntStatus intStatus, /* the interrupt status */UCHAR chnNum /* the channel causing the interrupt */){ if (intStatus == WNCAN_INT_TX) { CAN_DisableChannel(pDev, chnNum); CAN_FreeChannel(pDev, chnNum); }}

int cantask(){ struct WNCAN_Device *pDev; UCHAR chnTx, i;

...init, install callback, enable interrupts, start device...

for(i=0; i<5; i++) { while(CAN_GetTxChannel(pDev, &chnTx) != OK) taskDelay(1); CAN_EnableChannel(pDev, chnTx, WNCAN_INT_TX); CAN_TxMsg(pDev, chnTx, 0x44+i, FALSE, &i, sizeof(i)); }

...stop and close the device...}

By using a different channel for each transmission, the callback routine need only disable and free the channel. When the channel is freed, the channel can be reused again. Also, notice that there is a loop when attempting to get a channel. If there is no channel available, the task delays until there is an available channel. Thus, if the particular controller had only 2 channels for transmission, the above code would configure those two channels for transmission then wait until one of those channels completes before transmitting the next message.

It is interesting to note a possible side effect of this technique. By using multiple channels simultaneously for transmission, if you have a sufficiently fast processor, multiple channels will be ready for transmission before the controller actually begins transmission. Consequently, the controller must choose which channel to transmit first. Channel transmission order is controller dependent. Some controllers use the CAN ID to decide which to transmit first, others may use the

44 Draft: 26 Apr 04


3

channel number. Thus, if specific sequencing of multiple messages is required, the above technique is not appropriate.

Single Transmit Channel

The second technique reuses the same channel to transmit multiple messages. Unlike the previous technique, this technique ensures exact sequencing of the message transmissions.

SEM_ID G_TxSem;void myIsrCallBackFunc(struct WNCAN_Device *pDev, /* pointer to a WNCAN_Device */WNCAN_IntStatus intStatus, /* the interrupt status */UCHAR chnNum /* the channel causing the interrupt */){ if (intStatus == WNCAN_INT_TX) { semGive(G_TxSem); }}

int cantask(){ struct WNCAN_Device *pDev; UCHAR chnTx, i;


G_TxSem = semBCreate(SEM_Q_FIFO, SEM_EMPTY); CAN_GetTxChannel(pDev, &chnTx); CAN_EnableChannel(pDev, chnTx, WNCAN_INT_TX);

for(i=0; i<5; i++) { CAN_TxMsg(pDev, chnTx, 0x44+i, FALSE, &i, sizeof(i)); semTake(G_TxSem); }

CAN_DisableChannel(pDev, chnTx); CAN_FreeChannel(pDev, chnTx);


By using the same channel for each transmission, there must be synchronization between the transmission of the next message and the completion of the previous message transmission. This is illustrated using a binary semaphore. Alternative synchronization techniques are also possible instead of a semaphore.

Draft: : 26 Apr 04 45


It is also interesting to note that by only utilizing only one channel, the synchronization code is minimized. If multiple channels for simultaneous transmission were being used, separate semaphores would be needed for each channel.

Regardless of your approach to handling transmit interrupts, the fundamental idea is that channels are a limited resource and must be managed appropriately. Each use of CAN_GetTxChannel( ) and CAN_EnableChannel( ) must be balanced with CAN_DisableChannel( ) and CAN_FreeChannel( ) calls. Failure to use these routines correctly will result in an exhaustion of available channels for subsequent transmissions. Also, since most controller channels can be used for both transmission and reception, exhausting all transmit channels may also exhaust channels available for reception.

NOTE: When using a RTR remote requestor message, when the request is transmitted the WNCAN_INT_TX interrupt will occur. You must not disable or free the channel at this time. The reason is that the same channel used to send the request will be receiving the reply.

46 Draft: 26 Apr 04


3

3.9.4 Receive Interrupt Processing

Unlike transmission interrupt processing, handling reception interrupts is much more straightforward regarding the use the channel. The issue with reception interrupts is what to do after a message has been received.

The choice when processing receive interrupts is between handling the message within the callback, or allowing the task to process the message. The choice is up to you; you must consider interrupt latency, complexity, message rate, and response time in selecting which method to implement.

The following examples illustrate a couple of different techniques for processing the receive interrupt. Note that only the relevant pieces of code are illustrated. For example, error handling is not shown.

Reception Processing Within a Callback

The first example processes the message within the callback.

LOCAL volatile short count;

void myIsrCallBackFunc(struct WNCAN_Device *pDev, /* pointer to a WNCAN_Device */WNCAN_IntStatus intStatus, /* the interrupt status */UCHAR chnNum /* the channel causing the interrupt */){ ULONG canid; BOOL extID; UCHAR len;

if (intStatus == WNCAN_INT_RX) { canID = CAN_ReadID(pDev, chnNum, &extID); if (canID == 0x50) { len = sizeof(count); CAN_ReadData(pDec, chnNum, (UCHAR*)&count, &len, &extID); CAN_DisableChannel(chnNum); } }}

int cantask(){ struct WNCAN_Device *pDev; UCHAR chnRx;


Draft: : 26 Apr 04 47


count = 0; CAN_GetRxChannel(pDev, &chnRx); CAN_WriteID(pDev, chnRx, 0x50, FALSE); CAN_EnableChannel(pDev, chnRx, WNCAN_INT_RX);

while(1) { while( count==0 ) taskDelay(1);

printf("Received: %d\n", count); if (count == 0xff) break;

count = 0; CAN_EnableChannel(pDev, chnRx, WNCAN_INT_RX); }

CAN_DisableChannel(pDev, chnRx); CAN_FreeChannel(pDev, chnRx);


In this example, the global variable count is used for both synchronization and for data reception. The task waits until count is non-zero. After that, the value of the received message is printed, then the task either terminates or resets the data, and enables the channel for the next message.

The callback detects the receive interrupt, validates that the CAN ID matches the expected value, then reads the message data directly into the global variable. The callback also disables the channel. This ensures data coherency, because the channel cannot receive another message until it is enabled.

Reception Processing Within a Task

In the second example, another task is used to process the message. A semaphore is used to synchronize when the message has been received.

SEM_ID G_RxSem;

void myIsrCallBackFunc(struct WNCAN_Device *pDev, /* pointer to a WNCAN_Device */WNCAN_IntStatus intStatus, /* the interrupt status */UCHAR chnNum /* the channel causing the interrupt */){ ULONG canid; BOOL extID;

48 Draft: 26 Apr 04


3

if (intStatus == WNCAN_INT_RX) { canID = CAN_ReadID(pDev, chnNum, &extID); if (canID == 0x50) { CAN_DisableChannel(pDev, chnNum); semGive(G_RxSem); } }

int rxtask(int cantaskId /* task ID of main task */struct WNCAN_Device *pDev, /* pointer to a WNCAN_Device */UCHAR chnNum, /* rx channel */){ UCHAR len; short count; BOOL extID;

len = sizeof(count); while(1) { semTake(G_RxSem);

len = sizeof(count); CAN_ReadData(pDev, chnNum, (UCHAR*)&count, &len, &extID); printf("Received: %d\n", count);

if (count == 0xff) break;

CAN_EnableChannel(pDev, chnNum, WNCAN_INT_RX); }

taskResume(cantaskId);}



CAN_GetRxChannel(pDev, &chnRx);

G_RxSem = semBCreate(SEM_Q_FIFO, SEM_EMPTY);

taskSpawn("tRxTask", 100, 0, 512, rxtask, taskIdSelf(),(int)pDev, chnRx, 0,0,0,0,0,0,0,0);

Draft: : 26 Apr 04 49


CAN_WriteID(pDev, chnRx, 0x50, FALSE); CAN_EnableChannel(pDev, chnRx, WNCAN_INT_RX);

taskSuspend(); /* suspend until all done */

CAN_DisableChannel(pDev, chnRx); CAN_FreeChannel(pDev, chnRx);


This example is simplified because only one message is received. It is not recommended that you have a separate task for each message. It would be a better use of resources if you implement a more sophisticated mechanism for processing the messages, such as a priority queue in conjunction with the reception task.

3.9.5 Other Interrupt Processing

Additional interrupts may be processed within your callback routine. These are the bus off, wake up, and error interrupts. When the conditions exist on your controller to warrant one of those interrupts, the cause is detected and the condition cleared before the callback is invoked. However, the conditions may persist and subsequent calls to the callback routine will be made as long as the interrupt is enabled. It might be beneficial to disable the offending interrupt once it is detected. Some of these other interrupts are designed to reflect the current state of the controller and the network. Thus, for robust systems, you should not ignore these interrupts.

Although these other interrupt should not occur as frequently as a transmission or reception interrupt, the technique described above to process the interrupt can be adopted to these interrupts. Consult your specific board and controller documentation on the processing of the conditions, which generate these interrupts.

50 Draft: 26 Apr 04

3 WIND NET CAN Programming3.10 Closing a CAN Device Session

3

3.10 Closing a CAN Device Session

Close a CAN device with the CAN_Close( ) routine.

The following example is excerpted from code that releases the pointer to a WNCAN_Device structure. It stops CAN message processing, disables interrupts, frees all CAN channels, and closes the CAN device.

CAN_TxAbort(pDev); CAN_Stop(pDev);

for(i=0;i<CAN_GetNumChannels(pDev);i++){CAN_DisableChannel(pDev, i);CAN_FreeChannel(pDev, i);

}CAN_DisableInt(pDev);CAN_Close(pDev);

3.11 Advanced Functionality

The WIND NET CAN API supports some advanced features found on CAN controllers. For sophisticated applications, you may need the additional functionality to optimize use of the controllers. The following sections describe API support of several advanced features.

3.11.1 Filters

Filters allow the reception of different CAN IDs into the same channel. You can consider filters to be like wildcards. For example, you can program a channel to receive all messages with CAN IDs that match 0x1xx; where xx is in the range 0..0xff. For more information about filters and filtering, consult your particular CAN controller documentation.

NOTE: A controller may have additional features not supported by API. To access these features, use the CAN_ReadReg( ) and CAN_WriteReg( ) register access routines.

Draft: : 26 Apr 04 51


Global Receive Filter

Some controllers support a global filter that applies to all receive channels on the controller. Use CAN_SetGlobalRxFilter( ) and CAN_GetGlobalRxFilter( ) to manipulate the filter. When the global receive filter is used, you must ensure that all of the message CAN IDs you intend to receive pass the filter, else those messages will not be received. For more information about global filtering, consult your controller documentation. If you use the API calls and the controller does not support the global filter, an error is reported.

Local Message Filter

Some controllers support a filter for a channel. Use CAN_SetLocalMsgFilter( ) and CAN_GetLocalMsgFilter( ) to manipulate the filter. The local filter applies only to the channel programmed for it. If the controller supports a global receive filter, you must consider both the global filtering and local filtering to properly process the intended messages. Filters should only be used with channels receiving messages. Undefined behavior may result if you use a local filter on a channel for transmission. By default, CAN_TxMsg( ) specifically resets the local message filter for the channel.

The following example programs a channel to receive only CAN IDs within the range 0x100..0x1ff.



count = 0; CAN_GetRxChannel(pDev, &chnRx); CAN_WriteID(pDev, chnRx, 0x100, FALSE); CAN_SetLocalMessageFilter(pDev, chnRx, 0x0300, FALSE); CAN_EnableChannel(pDev, chnRx, WNCAN_INT_RX);

...other processing...


52 Draft: 26 Apr 04

3 WIND NET CAN Programming3.11 Advanced Functionality

3

3.11.2 Remote Messages

Briefly, the concept of a remote message is a message sent as a request, to another controller on the CAN bus, for the contents of that message ID to be transmitted on the bus. For example, controller #1 senses the temperature of the room and controller #2 adjusts the airflow. When controller #2 needs to know the room temperature, it transmits a remote request for the room temperature. Controller #1 receives the request and replies with the room temperature value. It is important to note that this request and reply is done with the same CAN ID. For more information about remote messages (also described as remote frames), consult your controller documentation.

WIND NET CAN uses the following terminology regarding remote messages. A requester initiates the request for the message. A responder contains the data and replies to a request. Most controllers support channels that can be configured for either for transmission or reception. If your controller supports this, you can use one channel. If your controller's channels can not be configured either way, you need to use multiple channels.

Programming the Requester

The requester first must transmit a request onto the CAN bus. The requester then expects to receive the same CAN ID with the data.

LOCAL volatile short roomTemp;SEM_ID G_TempSem;

void myIsrCallBackFunc(struct WNCAN_Device *pDev, /* pointer to a WNCAN_Device */WNCAN_IntStatus intStatus, /* the interrupt status */UCHAR chnNum /* the channel causing the interrupt */){ ULONG canid; BOOL extID; UCHAR len;

if (intStatus == WNCAN_INT_RX) { canID = CAN_ReadID(pDev, chnNum, &extID); if (canID == 0x50) { len = sizeof(roomTemp); CAN_ReadData(pDec, chnNum, (UCHAR*)& roomTemp, &len, &extID); CAN_DisableChannel(chnNum); semGive(G_TempSem); } }

Draft: : 26 Apr 04 53


}

int cantask(){ struct WNCAN_Device *pDev; UCHAR chnRem; short unused;


G_TempSem = semBCreate(SEM_Q_FIFO, SEM_EMPTY);

CAN_GetRTRRequesterChannel(pDev, &chnRem); CAN_EnableChannel(pDev, chnRem, WNCAN_INT_TX); CAN_TxMsg(pDev,chnRem, 0x50, FALSE, (UCHAR*)&unused, sizeof(unused));

/* wait for message to be received */ semTake(G_TempSem); printf("room temperature=%d\n", roomTemp);


It is critical that you program the length of the requestor's message. There is no API call to just program the length field of the CAN message. You must transmit the remote request message as if it is a regular message, and that programs the length field. However, the data portion of the requestor's remote frame is ignored and not transmitted. In the example, it is expected that the room temperature data is the size of a short (2 bytes) and coded accordingly.

On controllers that do not have channels which can either transmit or receive, CAN_GetRTRRequesterChannel( ) can not be used. Two channels must be used instead: one for transmission, one for reception.

int cantask(){ struct WNCAN_Device *pDev; UCHAR chnTx, chnRx; short unused;


G_TempSem = semBCreate(SEM_Q_FIFO, SEM_EMPTY);

CAN_GetRxChannel(pDev, &chnRx); CAN_SetMode(pDev, chnRx, WNCAN_CHN_RECEIVE); CAN_WriteID(pDev, chnRx, 0x50); CAN_EnableChannel(pDev, chnRx, WNCAN_INT_RX);

CAN_GetTxChannel(pDev, &chnTx); CAN_SetRTR(pDev, chnTx); CAN_EnableChannel(pDev, chnTx, WNCAN_INT_NONE); CAN_TxMsg(pDev,chnTx, 0x50, FALSE, (UCHAR*)&unused, sizeof(unused));

54 Draft: 26 Apr 04


3

/* wait for message to be received */ semTake(G_TempSem); printf("room temperature=%d\n", roomTemp);


Programming the Responder

The responder waits until a request is received before it transmits its data. On most controllers, the transmission, once the request is received, happens automatically. Therefore, there is no need for additional processing in your callback routine. If your specific controller does not automatically respond, you will need code to handle this case.

int cantask(){ struct WNCAN_Device *pDev; UCHAR chnRx; short roomtemp;


CAN_GetRTRResponderChannel(pDev, &chnRx); CAN_WriteID(pDev, chnRx, 0x50, FALSE);

while(1) { /* update room temperature periodically */ roomtemp = read room temperature CAN_WriteData(pDev, chnRx, (UCHAR*)&roomtemp, sizeof(roomtemp)); CAN_EnableChannel(pDev, chnRx, WNCAN_INT_RX);

taskDelay(1000); CAN_DisableChannel(pDev, chnRx); }

...disable, free, stop and close the device...}

For the responder channel, you must write the data into the channel. Data can only be written into the channel when the channel is disabled.

NOTE: There is an inconsistency with regard to the automatic response to the remote request. On some controllers, the length, as set within the responder, will be transmitted. On other controllers, the length from the requester's message determines the amount of data transmitted by the responder. Consult your controller documentation regarding this issue.

Draft: : 26 Apr 04 55


3.11.3 Wake and Sleep

CAN controllers have the ability to go to sleep and no longer be part of the bus transactions. Use CAN_Sleep( ) and CAN_WakeUp( ) to control this feature. A controller in the sleep state may also be a form of power reduction, for those controllers where power usage is important.

Some controllers can be programmed to automatically waken when a specific condition is detected. For example, if a message is programmed for reception on the controller, the controller may automatically wake so that the message is received. Consult your controller documentation on the features regarding this feature.

3.11.4 Polling

Another technique for detecting when a channel completes transmission or receives a message without using interrupts is called polling. Polling is not supported within the WIND NET CAN API. Therefore, if you decide to poll, you must directly program the controller using the register access API calls. Note that if polling, you may not be able to use the expected API functions that manipulate the contents of a channel because those routines may change settings needed for polling. You may have to examine the controller-specific implementation to determine if you can still use the relevant API functions.

3.11.5 Pre-initialization

Some applications may require a pre-initialization of the CAN device data structure. Although not a formal part of the WIND NET CAN API, a set of additional function-like macros can be used to modify data structure elements before calling CAN_Init( ).

The following table summarizes these additional macros:

Macro Description

CAN_SetSjw(pDev, sjw) Change the default bit-timing SJW parameter.

CAN_SetBrp(pDev, brp) Change the default bit-timing baud rate pre-scalar parameter.

CAN_SetTseg1(pDev, ts1) Change the default bit-timing TSEG1 parameter.

56 Draft: 26 Apr 04


3

CAN_SetTseg2(pDev, ts2) Change the default bit-timing TSEG2 parameter.

CAN_SetNumOfSamples (pDev, samples)

Change the default bit-timing samples parameter.

Macro Description

Draft: : 26 Apr 04 57


58 Draft: 26 Apr 04

Draft: 26 Apr 04

4
Device I/O Interface
4.1 Introduction 59

4.2 Device Names 60

4.3 I/O Interfaces 60

4.4 Using a Controller 61

4.5 Using a Channel 67

4.6 Examples 72

4.1 Introduction

The Device I/O interface is an optional API for WIND NET CAN. The interface uses the VxWorks I/O system APIs, such as open( ), read( ), write( ), and so forth. For general information about the interface, see the VxWorks Programmer’s Guide: I/O system. This section describes the interface as it pertains to WIND NET CAN devices. The functionality of this interface mirrors the CAN API functions.

The CAN device I/O component configures the interface into your project.

59


4.2 Device Names

The device interface is divided into two functional forms. One form manipulates the CAN device controller and the other form manipulates a specific CAN channel. Table 4-1 describes the naming conventions of the two forms.

Examples: \esdpci200_1\0, \esdpci200_1\0\4.

Each CAN board may contain one or more CAN controllers. Each board has a default name and can be changed using a component parameter from the Tornado GUI. You cannot modify the controller or channel names. Those are always represented numerically.

4.3 I/O Interfaces

Table 4-2 shows the available I/O system interfaces for WIND NET CAN.

Table 4-1 Device Name Conventions

Device Types Naming Convention

CAN Controller \boardname\controller #

CAN Channel \boardname\controller #\channel #

Table 4-2 I/O Interfaces

Interface Controller Channel

creat( ) - -

remove( ) - -

open( ) ✓ ✓

close( ) ✓ ✓

read( ) - ✓

write( ) - ✓

60 Draft: 26 Apr 04

4 Device I/O Interface4.4 Using a Controller

4

4.4 Using a Controller

From the set of boards you have included into your project, each board automatically creates device entries for each board and controller, using the component parameter to name the board. The devices will appear in the VxWorks device list and are displayed using the devs command.

Example 4-1 Device List Display From A Shell

devsdrv name 0 /null 1 /tyCo/0 1 /tyCo/1 5 svl-target1: 6 /pty/rlogin.S 7 /pty/rlogin.M 8 /vio 9 /tgtsvr 10 /esdpci_200_0/0 11 /esdpci_200_0/1 12 /esdpci_200_1/0 13 /esdpci_200_1/1

4.4.1 Opening a Controller Device

A controller device must be opened to configure it for synchronization to the CAN bus. The controller device must remain open during all subsequent channel operations. Premature closing of the device will render all channels inoperative, even though the channel descriptors may still be valid.

The open( ) command expects passing the name of the board and controller. In addition, only the O_RDWR flag is supported and there are no modes.

ioctl( ) ✓ ✓

select( ) ✓ ✓

Table 4-2 I/O Interfaces (cont’d)

Interface Controller Channel

Draft: : 26 Apr 04 61


The controller is not immediately brought online to the CAN bus. After controller baud rate is configured, use the WNCAN_HALT ioctl( ) function to bring the controller online.

4.4.2 Configuring a Controller

After the controller is open, issue ioctl( ) commands to configure it. By default, the controller is configured to a board-specific configuration. It is recommended that you specifically configure the device rather than rely on defaults. Table 4-3 lists the supported ioctl( ) function codes.

Table 4-3 CAN Controller ioctl( ) Function Codes

Function Code DescriptionArgument Type or Value

FIOSELECT Add wake-up process in select I/O SEL_WAKEUP_NODE *

FIOUNSELECT Remove wake-up process in select I/O SEL_WAKEUP_NODE *

WNCAN_HALT Halt (1) or start (0) the controller int

WNCAN_SLEEP Set controller into sleep state 0

WNCAN_WAKE Force controller out of sleep 0

WNCAN_TX_ABORT Abort all CAN transmissions 0

WNCAN_RXCHAN_GET Get an available receive channel UCHAR *

WNCAN_TXCHAN_GET Get an available transmit channel UCHAR *

WNCAN_RTRREQCHAN_GET Get an available channel for a remote request

UCHAR *

WNCAN_RTRRESPCHAN_GET Get an available channel for a remote response

UCHAR *

WNCAN_BUSINFO_GET Get current status WNCAN_BUSINFO *

WNCAN_CONFIG_SET Set one or more configuration parameters WNCAN_CONFIG *

WNCAN_CONFIG_GET Get one or more configuration parameters WNCAN_CONFIG *

WNCAN_CTRLCONFIG_SET Set controller-specific parameters WNCAN_CTRLCONFIG *

62 Draft: 26 Apr 04


4
WNCAN_CTRLCONFIG_GET Get controller-specific parameters WNCAN_CTRLCONFIG *
Table 4-3 CAN Controller ioctl( ) Function Codes (cont’d)

Function Code DescriptionArgument Type or Value

Draft: : 26 Apr 04 63


4.4.3 Configuration Data Structures

The following are the data structures used for various ioctl( ) functions.

WNCAN_BUSINFO

typedef struct _wncan_businfo{ WNCAN_BusStatus busStatus; /* bus status */ WNCAN_BusError busError; /* bus error */} WNCAN_BUSINFO;

WNCAN_CONFIG

typedef struct _wncan_config{ UINT flags; /* access options */

/* read-only items */ struct { WNCAN_VersionInfo version; /* WNC version */ WNCAN_ControllerType ctrlType; /* CAN controller type */ XtalFreq xtalfreq; /* crystal frequency */ UCHAR numChannels; /* total # of channels */ UINT baudRate; /* computed baud (bits/s) */ UINT samplePoint; /* % of bit time at which the bit is sampled.*/ } info;

/* read/write items */ struct { ULONG mask; /* filter mask */ BOOL extended; /* extended flag */ } filter;

struct { UCHAR tseg1; /* time quanta for segment 1 */ UCHAR tseg2; /* time quanta for segment 2 */ UCHAR brp; /* baud rate prescaler */ UCHAR sjw; /* syncro jump width */ BOOL oversample; /* normal or over-sampling option */ } bittiming;

} WNCAN_CONFIG;

64 Draft: 26 Apr 04


4

Table 4-4 shows available values for the flags field, which indicates which element sub-structures are valid or requested.

The names values can be ‘OR’ed together to select multiple sub-structures, with the exception of WNCAN_CFG_NONE, which must be singularly specified.

The info sub-structure is only used with the WNCAN_CFG_GET function. The extended member of the filter sub-structure must always be set with a value for both WNCAN_CFG_GET and WNCAN_CFG_SET functions.

Table 4-4 Configuration Flags

Named Values Description

WNCAN_CFG_ALL All sub-structures valid for function

WNCAN_CFG_INFO The info sub-structure is validWNCAN_CFG_GLBFILTER The filter sub-structure is valid

WNCAN_CFG_BITTIMING The bittiming sub-structure is valid

WNCAN_CFG_NONE No sub-structure is valid

Draft: : 26 Apr 04 65


WNCAN_CTRLCONFIG

typedef struct _wncan_ctlrconfig{

WNCAN_ControllerType ctlrType;

union{

struct{

UCHAR propseg; /* propagation segment */} toucanData;

struct{

struct intLevelInfo_t{

UCHAR intSrcNum; /* FlexCAN interrupt source number, always an input for */ /* WNCAN_CTLRCONFIG_SET and WNCAN_CTLRCONFIG_GET */

UCHAR intLevel; /*FlexCAN interrupt level, for WNCAN_CTLRCONFIG_SET: *//* input, for WNCAN_CTLRCONFIG_GET: output */

UCHAR intPrioLevel; /* priority within interrupt level, *//* WNCAN_CTLRCONFIG_SET: input and *//* WNCAN_CTLRCONFIG_GET: output */

} intLevelInfo; } flexcanData;

/* Other controller-specific structs can be defined here */ULONG dummy; /* placeholder for future defs */} ctlrData;

} WNCAN_CTLRCONFIG;

Controller-specific configuration is handled through this structure. For more information about the configuration parameters, consult the controller’s documentation.

4.4.4 Reading and Writing a Controller

Since the controller refers to the entire CAN device, and not a particular channel, read( ) and write( ) I/O system calls are not supported for the entire controller. For information on reading and writing data to channels, see sections 4.5.4 Writing to a Channel, p.71 and 4.5.5 Reading from a Channel, p.71.

66 Draft: 26 Apr 04

4 Device I/O Interface4.5 Using a Channel

4

4.4.5 Using the Select Facility with a Controller

The Select facility is supported for a controller. The controller’s WNCAN_INT_ERROR, WNCAN_INT_BUS_OFF, and WNCAN_INT_WAKE_UP conditions will wake up all tasks blocked on the controller’s device descriptor. When using the select( ) function, specify the controller device descriptor in the read set descriptors.

4.4.6 Closing a Controller

Closing a controller makes the controller inactive and off the CAN bus. Make sure that your program closes any open controller channel device descriptors before closing the controller’s descriptor.

4.5 Using a Channel

After the controller device is opened, its channels are available to be opened. The controller device must remain open during all subsequent channel transactions. Premature closure of the device will take the controller offline and render any channel device descriptors inoperable.

4.5.1 Opening a Channel Device

A channel device must be opened for CAN messages transmission and reception. We recommend you use the WNCAN_TXCHAN_GET, WNCAN_RXCHAN_GET, and similar ioctl( ) functions of the controller device to choose an available channel number. Otherwise, you must keep track of which channels are available.

The open( ) command expects passing the name of the board, controller number, and channel number. All flags are supported with the following meanings: O_RDWR, transmit and receive privilege; O_RDONLY, receive privilege only; O_WRONLY, transmit privilege only. There are no modes.

Draft: : 26 Apr 04 67


4.5.2 Configuring a Channel

After the channel is open, issue ioctl( ) commands to configure it. Table 4-5 lists the supported ioctl( ) function codes.

Table 4-5 CAN Controller ioctl( ) Function Codes

Function Code Description Argument Type or Value

FIOSELECT Add wake-up process in select I/O

SEL_WAKEUP_NODE *

FIOUNSELECT Remove wake-up process in select I/O

SEL_WAKEUP_NODE *

FIONFREEa Number of bytes available in the transmit queue.

int *

FIONREADa Number of bytes ready to be read from the reception queue

int *

FIONWRITEa Number of bytes queued for transmission

int *

FIOFLUSH Discard all bytes in transmit and reception queues

0

FIORFLUSH Discard al bytes in reception queue

0

FIOWFLUSH Discard all bytes in transmit queue

0

FIORBUFSETb Set number of messages available in reception queue

int

FIOWBUFSETb Set number of messages available in transmit queue

int

WNCAN_CHNCONFIG_SET Set one or more channel configuration parameters

WNCAN_CHNCONFIG *

WNCAN_CHNCONFIG_GET Get one or more channel configuration parameters

WNCAN_CHNCONFIG *

68 Draft: 26 Apr 04


4

WNCAN_CHN_ENABLE Enable (1) or disable (0) the channel

int

WNCAN_CHN_TX Transmit configured message immediately

0

WNCAN_CHNMSGLOST_GET Determine if a message has been lost

int *

WNCAN_CHNMSGLOST_CLEAR Clear message lost indication 0

a. Divide number of bytes by sizeof(WNCAN_CHNMSG) to determine number of messages.b. Value specified should be in terms of numbers of messages in the queue, not total number of bytes.

Table 4-5 CAN Controller ioctl( ) Function Codes (cont’d)

Draft: : 26 Apr 04 69


4.5.3 Configuration Data Structures

The following are the data structures used for various ioctl( ) functions.

WNCAN_CHNCONFIG

typedef struct _wncan_chnconfig{ UINT flags; /* access options */

/* local filter mask */ struct { ULONG mask; /* filter mask */ BOOL extended; /* extended flag */ } filter;

struct { ULONG id; /* CAN ID */ BOOL extId; /* is ID extended or not? */ UCHAR len; /* length */ UCHAR data[WNCAN_MAX_DATA_LEN]; /* message data */ } channel;

BOOL rtr; /* RTR bit setting */ WNCAN_ChannelMode mode; /* channel mode */

} WNCAN_CHNCONFIG;

Table 4-6 lists the available values for the flags field, which indicates which element sub-structures are valid or requested.

Table 4-6 WNCAN_CHNCONFIG Flags

Named Values Description

WNCAN_CHNCFG_ALL All sub-structures valid for function

WNCAN_CHNCFG_MODE The mode element is valid

WNCAN_CHNCFG_RTR The rtr element is valid

WNCAN_CHNCFG_LCLFILTER The filter sub-structure is valid

WNCAN_CHNCFG_CHANNEL The channel sub-structure is valid

WNCAN_CHNCFG_NONE No sub-structure or member is valid

70 Draft: 26 Apr 04


4

The names values can be ‘OR’ed together to select multiple sub-structures, with the exception of WNCAN_CFG_NONE, which must be singularly specified.

The extended member of the filter sub-structure must always be set with a value for both WNCAN_CHNCONFIG_SET and WNCAN_CHNCONFIG_SET functions.

4.5.4 Writing to a Channel

The write( ) function causes a message to be placed into the transmit queue for subsequent transmission on the CAN bus. The buffer argument must always be a pointer to an instance of a WNCAN_CHNMSG structure and likewise, the maxbytes argument must reflect the size of that structure. The function will return an error if the transmit queue is full.

Transmission will only happen if the channel is enabled. Use the WNCAN_CHN_ENABLE ioctl( ) command to enable or disable the channel.

WNCAN_CHNMSG

typedef struct _wncan_chnmsg{ ULONG id; /* CAN ID */ BOOL extId; /* is ID extended or not? */ BOOL rtr; /* remote frame transmit request */ UCHAR len; /* message length */ UCHAR data[WNCAN_MAX_DATA_LEN]; /* message data */} WNCAN_CHNMSG;

4.5.5 Reading from a Channel

The read( ) function removes a message from the reception queue. The buffer argument must always be a pointer to an instance of a WNCAN_CHNMSG structure and likewise, the maxbytes argument must reflect the size of that structure. The function returns the number of bytes read, which will either be the size of the WNCAN_CHNMSG structure or 0.

Reception will only happen if the channel is configured using ioctl( ) with a CAN ID or filter using the WNCAN_CHNCONFIG_SET function and the channel is enabled using the WNCAN_CHN_ENABLE function.

Draft: : 26 Apr 04 71


4.5.6 Using the Select Facility with a Channel

The Select facility is supported for a channel. The controller’s WNCAN_INT_TX, WNCAN_INT_RX, and WNCAN_INT_RTR_RESPONSE conditions wake up all tasks blocked on the channel’s device descriptor. When using the select( ) function, specify the controller device descriptor in read or write set descriptors.

4.5.7 Closing a Channel

Closing a channel makes the channel inactive; however, any ongoing transmission or reception will complete. You should make sure that your program closes all open channel device descriptors before closing the controller’s descriptor.

4.6 Examples

Example 4-2 Sample Transmission

#define CANDEVICENAME "/esdpci_200_0/0"int tx_sample(){ WNCAN_CHNMSG txdata; int fdCtrlr, fdChan1, st; struct fd_set writeFds; char chnname[32]; UCHAR txChan1; fdCtrlr = open(CANDEVICENAME, O_RDWR, 0); if (fdCtrlr == ERROR) {printf("can't open\n"); return -1;}

/* START the controller!! */ ioctl(fdCtrlr, WNCAN_HALT, 0);

if (ioctl(fdCtrlr, WNCAN_TXCHAN_GET, (int)&txChan1) != OK) goto errexit;

sprintf(chnname, CANDEVICENAME "/%d", txChan1); fdChan1 = open(chnname, O_WRONLY, 0); if (fdChan1 == ERROR) { printf("can't open channel\n"); goto errexit; }

/* enable the channel */ ioctl(fdChan1, WNCAN_CHN_ENABLE, 1);

72 Draft: 26 Apr 04

4 Device I/O Interface4.6 Examples

4

txdata1.id = 0x19a; txdata1.extId = FALSE; txdata1.rtr = FALSE;

FD_ZERO(&writeFds); FD_SET(fdChan1, &writeFds);

for(st = 140000; st < 140256; st++) { FD_SET(fdChan1, &writeFds);

select(fdChan1+1, NULL, &writeFds, NULL, NULL);

if (FD_ISSET(fdChan1, &writeFds)) { unsigned long data = st;

txdata1.data[0] = ((char*)&data)[0]; txdata1.data[1] = ((char*)&data)[1]; txdata1.data[2] = ((char*)&data)[2]; txdata1.data[3] = ((char*)&data)[3]; txdata1.len = (st%4)+1; /* 1-4 bytes */ write(fdChan1, (char*)&txdata1, sizeof(txdata1)); FD_CLR(fdChan1, &writeFds); } }

/* wait until the transmit queue is empty */ for(ioctl(fdChan1, FIONWRITE, (int)&st); st; ioctl(fdChan1, FIONWRITE, (int)&st)) taskDelay(5);

close(fdChan1); close(fdCtrlr); return 0;

errexit: close(fdCtrlr); return -1;}

Draft: : 26 Apr 04 73


Example 4-3 Sample Reception

#define CANDEVICENAME "/esdpci_200_0/0"int read_test(){ WNCAN_CHNMSG rxdata; WNCAN_CHNCONFIG chncfg; int st, i, fdCtrlr, fdChan; struct fd_set readFds; char chnname[32]; UCHAR rxChan; FD_ZERO(&readFds);

fdCtrlr = open(CANDEVICENAME, O_RDWR, 0); if (fdCtrlr == ERROR) {printf("can't open\n"); return -1;}

/* START the controller!! */ ioctl(fdCtrlr, WNCAN_HALT, 0);

if (ioctl(fdCtrlr, WNCAN_RXCHAN_GET, (int)&rxChan) != OK) goto errexit;

sprintf(chnname, CANDEVICENAME "/%d", rxChan);

fdChan = open(chnname, O_RDONLY, 0); if (fdChan == ERROR) { printf("can't open channel\n"); goto errexit; }

/* configure the channel */ chncfg.flags = WNCAN_CHNCFG_CHANNEL; chncfg.channel.id = 0x35; chncfg.channel.extId = FALSE; chncfg.channel.len = 0; /* ignored for read configuration */ ioctl(fdChan, WNCAN_CHNCONFIG_SET, (int)&chncfg);

/* enable the channel */ ioctl(fdChan, WNCAN_CHN_ENABLE, 1);

st=0; do { FD_ZERO(&readFds); FD_SET(fdChan, &readFds);

select(fdChan+1, &readFds, NULL, NULL, NULL);

read(fdChan, (char*)&rxdata, sizeof(rxdata));

printf("read ID: %x len %d\nData: ", rxdata.id, rxdata.len); for(i=0; i<rxdata.len; i++) printf("%x ", rxdata.data[i]); printf("\n");

74 Draft: 26 Apr 04

4 Device I/O Interface4.6 Examples

4

st++;

} while(st<5);

close(fdChan);

close(fdCtrlr);

return 0;

errexit: return -1;}

Draft: : 26 Apr 04 75


76 Draft: 26 Apr 04

Draft: 26 Apr 04

5
Driver Developer Kit
5.1 Introduction 77

5.2 Organization 78

5.3 Templates 79

5.4 Conformance Tests 83

5.1 Introduction

The WIND NET CAN Driver Developer Kit (DDK) provides guidance for developers wanting to do the following:

■ Develop a CAN driver within the WIND NET CAN framework.

■ Test a CAN driver for conformance and completeness.

■ Example usage of CAN API functions.

It is assumed that the developer is familiar with the WIND NET CAN functionality and the CAN device hardware.

77


5.2 Organization

The DDK is provided as part of a WIND NET CAN distribution and is installed into installDir/share/WindNetCAN/ddk. The DDK is divided into two major parts, the conformance tests and the source code templates.

ddk/conformance_tests/analyzerThis directory contains configuration files related to specific third-party CAN bus analyzer tools. The configuration aids device testing by providing a programmable CAN device used for testing CAN message transmission and reception.

ddk/conformance_tests/manualThis directory contains individual tests requiring manual invocation of the tests and CAN bus analyzer message transmission and reception.

ddk/conformance_tests/offlineThis directory contains several tests which exercise a CAN driver without requiring the device to be connected to a network.

ddk/conformance_tests/onlineThis directory contains several tests which test message transmission and other features requiring the device to be connected to a CAN network. A CAN bus analyzer is required to examine the results of the transmissions.

ddk/templatesThis directory contains template source files needed for implementing a new driver for WIND NET CAN.

Figure 5-1 Distribution Structure

78 Draft: 26 Apr 04

5 Driver Developer Kit5.3 Templates

5

5.3 Templates

Source code templates are provided to aid the development of a new CAN driver. This kit is not a CAN developer’s guide, in that there is no attempt to describe how to program for a particular CAN device, rather just a guide in developing the driver within WIND NET CAN. It is expected that other reference material will be used to guide the development of a particular CAN device, such as the device’s programmer’s manual and using examples of existing drivers. CAN drivers are, generally speaking, pretty much the same and it is highly likely that code for other drivers can be reused in the new driver with minor modification.

5.3.1 Terminology

With regard to developing a WIND NET CAN driver, there are some additional terms used to describe various parts of the driver. The term board is used to describe the target board hardware a CAN device is connected to. The term controller is used to describe the CAN device. The term CAN driver or just driver, consists of code needed to configure both the board and the controller.

5.3.2 Conventions

The template source files were created by taking an existing driver and removing all of the content, leaving mostly empty function bodies. Comments are provided to guide what is needed at any particular point. Also, the notations <NEW_BOARD_NAME>, <NEW_CONTROLLER_NAME>, and <CAN_CONTROLLER_ON_BOARD> are used frequently within the template code. These notations act as placeholders for the actual name you choose for your controller and board. There may also be a placeholder representing the nth element or name of a variable.

Template source is presented in Example 5-1. Notice the placeholders in various portions of the code.

Draft: : 26 Apr 04 79


Example 5-1 Template Source Code

#include <CAN/<CAN_CONTROLLER_ON_BOARD>.h>#include <CAN/private/<NEW_BOARD_NAME>.h>

static const char deviceName[] ="<NEW_BOARD_NAME>";

/** Specify unique indexes for CAN controllers present on board*/ const UINT <NEW_BOARD_NAME>_CONTROLLER_1_ndx = 0;const UINT <NEW_BOARD_NAME>_CONTROLLER_n_ndx = 1;

Once you have decided on a name for the new CAN driver, with the board and controller having different names, Example 5-2 shows the code with the names substituted.

Example 5-2 Driver Source Code

#include <CAN/sja1000.h>#include <CAN/private/esd_pci_200.h>

static const char deviceName[] ="ESD PCI 200";

/** Specify unique indexes for CAN controllers present on board*/ const UINT esd_pci_200_CONTROLLER_1_ndx = 0;const UINT esd_pci_200_CONTROLLER_2_ndx = 1;

5.3.3 Preparation

Before you begin developing a new driver, you must prepare the template files. The ddk/templates folder is just a convenient location for the template files. For integration within WIND NET CAN, you must place copies of each of the files within the proper directory within the WIND NET CAN source structure.

Table 5-1 lists the template source files and their associated directories, which the files must be copied into.

Table 5-1 Source File Locations

Template Source Name Destination Directory

03wnCAN_newBoard.cdf installDir/target/config/comps/VxWorks

new_board_cfg.c installDir/target/config/comps/src/CAN

newBoardName.c installDir/target/src/drv/CAN

80 Draft: 26 Apr 04

5 Driver Developer Kit5.3 Templates

5

Notice that placeholders exist in the names of the template source files. When you copy the files, rename the files to closely match the names used within the source files. In the forthcoming porting instructions, file names will be referred to by their template source names even though it is expected that you have renamed the files appropriately for your new board and/or controller.

5.3.4 Porting to a New Board

While evaluating the new board, it may be the case that the controller for the board has already been implemented. Such is the case with the SJA1000 and HCAN2 controllers. These controllers are used on multiple boards. If your new board uses an existing controller, you need only port the board portion of the driver. If controller support does not already exist, you will have to implement the controller code as well. In either case, the new board must be ported.

Following are the set of steps for the process. During the process, it is recommended that you reference existing board files and code to aid your porting effort.

1. Start by modifying the component definition file (03wnCAN_newBoard.cdf). Update the placeholders with your board name and make other modifications to the definition file. For more information about the Component Language, refer to the Tornado BSP Developer’s Guide. You will need to determine if there are any parameters that must be specified for the board, such as IRQ level, base address or number of boards. (It is possible to support multiple instances of the same board within the WIND NET CAN framework. This is common for PCI-based CAN cards.) These parameters will allow you to change the data from the Tornado-GUI just like other VxWorks components. If you do not know if your board needs parameters, you can always add them as needed.

newBoardName.h installDir/target/h/CAN/private

newControllerName.c installDir/target/src/drv/CAN

newControllerName.h installDir/target/h/CAN

newControllerOffsets.h installDir/target/h/CAN

Table 5-1 Source File Locations (cont’d)

Template Source Name Destination Directory

Draft: : 26 Apr 04 81


2. Modify the configlette source file (new_board_cfg.c) for the new board. Update the placeholders with your board name and make other modifications as needed. The configlette normally initializes the board using any parameters specified in the CDF file. In addition, the configlette initializes the board for use with the device I/O interface, if that interface has been configured.

3. Modify the file installDir/target/h/CAN/canBoard.h for the new board. This file is a core WIND NET CAN file. You need to add a macro, which identifies your board with a unique identification number. Look for name CAN_BoardType within a comment to find the proper location for the new macro. In addition, you may need to add to the XtalFreq enumeration if your board does not use an existing frequency identifier.

4. Memory for global variables used by WIND NET CAN drivers is statically allocated. A structure must be defined to include the different data required to support the board. This structure is defined within the private board header file (newBoardName.h).

5. Modify the board source file (newBoardName.c). Update the placeholders with your board name and make other modifications as needed.

At this point, you have completed the necessary steps to port a board for WIND NET CAN. But, you are still tasked to implement all of the specific code needed to implement the proper functionality. It cannot be encouraged enough to utilize as much as possible existing board code to aid the development of your new board.

5.3.5 Porting to a Controller

If the new board, added in the previous section, uses a controller that has not been implemented, you will need to implement the new controller. Unfortunately, implementing a new controller is significantly harder than adding a new board. You must read and thoroughly understand the function of the particular controller. Take advantage of the existing controller code; however, your controller will be different.

1. Modify the file installDir/target/h/CAN/canController.h for the new controller. This file is a core WIND NET CAN file. You need to add a macro, which identifies the new controller with a unique identification number. Look for name CAN_ControllerType within a comment to find the proper location for the new macro.

2. Modify the controller header file (newControllerOffsets.h). Update the placeholders with your controller name and make other modifications as needed.

82 Draft: 26 Apr 04

5 Driver Developer Kit5.4 Conformance Tests

5

3. Modify the controller header file (newControllerName.h). Update the placeholders with controller register definitions.

4. Modify the controller source file (newControllerName.c). Update the placeholders with your controller name and make other modifications as needed.

At this point, you have completed the necessary steps to port a controller for WIND NET CAN. The majority of the remaining work is now to implement all of the functions defined within the controller source file to work with your controller. It is recommended that you implement and test small subsets of the functions during your development process.

5.3.6 Porting Issues

The following are some issues that you should consider during the porting process.

■ Separate the board and controller code so that you can reuse the controller on more than one board.

■ Identify the functionality of each controller channel (also called mailboxes or buffers). Issues include which buffers are receive-only, transmit-only or receive and transmit.

■ Support for global and local masks.

■ Support for remote messages and auto-reply capability.

■ Support for sleep, wake, and error functionality.

5.4 Conformance Tests

The conformances tests provide a mechanism to validate a CAN driver’s conformance to the WIND NET CAN API and functionality. You can also use portions of the tests as example code during development to provide sample tests.

The tests are divided into three groups: offline, online, and manual. Each group focuses on different pieces of functionality but there is substantial overlap between

Draft: : 26 Apr 04 83


the tests. Therefore, a single programming error may result in many test failures. The following sections describe how to use the tests.

5.4.1 Preparation

Each test group should be placed into a separate downloaded image. Do not attempt to combine the groups into a single image. Thus, you will need to create a bootable image without the tests. The bootable image must include the WIND NET CAN configuration for the board and controller under test. Alternatively, you can place a single test group within a bootable image rather than having a separate downloaded image.

5.4.2 Offline Tests

The offline tests provide conformance testing for API functionality that does not require the CAN device to be active on a CAN network. In other words, it tests initialization, baud rate, and other non-transmit, non-receive functionality. Use the following steps to execute the tests.

1. Create a downloadable project and add all C source files from all of the sub-directories from ddk/conformance_tests/offline. Since you will be modifying some of the files, you may want to make a copy of the tests before using them.

2. Edit the file containing the test parameters, offline/main/usrip.c. The test parameters are specific to the board and controller under test. The file is documented and describes the changeable parameters. In addition, this file contains specifications of which tests are used and which ones are skipped.

3. Edit the file, offline/offlineTestsConf.h, by specifying which of the board and controller header files are needed for proper compilation. This file also contains the definition of the ErrorLog macro. By default, the error log messages are sent to a text file on a remote host as specified within the test parameters. You can change the logging to suit your needs.

4. Each test is documented within its source file, but all are summarized within the single file, offline/offlineREADME.txt.

5. Compile the project and download it to the target.

84 Draft: 26 Apr 04


5

6. Invoke the tests by calling the start function from the shell and pass the configuration structure that is defined within the main/usrip.c file:

runOfflineTests (&test1)

7. Examine the test results, generated by default in a log file in the remote host. If any test fails, examine the test code to understand the mechanics of the test before making a change to the driver.

5.4.3 Online Tests

The online tests provide conformance testing for API functionality that requires the CAN device to be active on a CAN network. In other words, it tests transmit functionality. Use the following steps to execute the tests. The steps are similar to those used for the offline tests.

1. Create a downloadable project and add all C source files from all of the sub-directories from ddk/conformance_tests/online. Since you will be modifying some of the files, you may want to make a copy of the tests before using them.

2. Edit the file containing the test parameters, online/main/usrip.c. The test parameters are specific to the board and controller under test. The file is documented and describes the changeable parameters. Most importantly, configure the proper bit timing parameters. In addition, this file contains specifications of which tests are used and which ones are skipped.

3. Edit the file, online/onlineCTest.h, by specifying which of the board and controller header files are needed for proper compilation. This file also contains the definition of the ErrorLog macro. By default, the error log messages are sent to a text file on a remote host as specified within the test parameters. You can change the logging to suit your needs.

4. Each test is documented within its source file, but all are summarized within the single file, online/onlineREADME.txt.


6. Connect the target board’s CAN device that is under test to a CAN network. You must have an additional CAN device, which can receive messages for the tests to work properly. It is recommended that a CAN bus analyzer be used so that you can log the message transmission and verify that the messages are transmitted correctly. In addition, if you use the test named sleep61_1, the bus analyzer (or other node) must be able to transmit a message (any message will

Draft: : 26 Apr 04 85


do) for the test to work. Make sure that the bus analyzer’s baud rate matches that used for the tests.

7. Invoke the tests by calling the start function from the shell and pass the configuration structure that is defined within the main/usrip.c file:

runOnlineTests (&test1)

8. Examine the test results, generated by default in a log file in the remote host. If any test fails, examine the test code to understand the mechanics of the test before making a change to the driver. In addition, log the message transmission and verify that the messages sent are correct, that is, the CAN ID and data bytes are correct.

5.4.4 Manual Tests

There are four test which require a bus analyzer tool to generate messages and respond to remote frame messages. The ddk/conformance_tests/analyzer directory contains configuration files for some popular bus analyzers. If you do not have such an analyzer, you must create the equivalent messages within your analyzer. The required messages are listed below along with the testing instructions. The instructions assume the use of the CANAlyzer bus analyzer.

Filter Test

This test programs the global and local message filters of the CAN device. If your device does not have such filters, the test cannot be performed.

The test configures from the device under test:

■ A receive channel to receive extended ID, 0x4cc01.

■ A receive channel to receive all extended IDs.

The bus analyzer should transmit multiple extended ID messages (the data is irrelevant) including 0x4cc01 as well as other extended IDs. Also, transmission of standard IDs can be done to check that the device under test does not receive those messages.

To perform the test, follow the steps below.

1. Create a downloadable project and include the file, manual/test1/filter.c.

2. Modify the file to set the bit timing parameters and change the NODE_DEVICE macro to indicate the CAN board you are testing.

86 Draft: 26 Apr 04


5


4. Connect the target board’s CAN device that is under test to a CAN network. Connect your bus analyzer to the same network and make sure that the bus analyzer’s baud rate matches that used for the test.

5. Begin the test by issuing the following commands from the shell:

setupNode(0) startNode(0)

6. Transmit the extended ID messages from the bus analyzer tool. Using the CANAlyzer configuration, press the W or Q key to transmit a message. Transmit as many messages as desired.

7. Display the results of the tests by issuing the following command from the shell:

printRxMsg(0)

You should see an accounting of the extended ID messages received by the node. If there were extended ID messages transmitted but not received, then there is a problem with the filtering.

8. When you have completed evaluating the test, issue the following command to terminate the test:

releaseNode(0)

9. If your target device contains more than one CAN device on the controller, perform this test again, but pass the value of 1 to the test functions.

10. You may want to test other filtering combinations. Use this sample to create additional test configurations, such as receiving only message IDs fitting a pattern of 0x3xx (0x300-0x3ff) or 0x2x (0x20-0x2f).

Remote Response

This test transmits a remote reply after receiving a remote request from the bus analyzer tool.


■ Uses the CAN_GetRTRResponderChannel( ) API and uses ID 0x260. If your device does not support this API function, you must modify the test. The code contains support for the SJA1000 controller, which does not support the API. Use the SJA1000 code to help code the test for your controller.

Draft: : 26 Apr 04 87


The bus analyzer must be able to transmit a remote request with ID 0x260. Up to 8 data bytes can be requested.


1. Create a downloadable project and include the file, manual/test2/remoteRespStd.c.






6. Transmit the remote request from the bus analyzer tool. Using the CANAlyzer configuration, press R to transmit the request message.

Examine the bus analyzer’s message log to verify that a remote reply message was received from the target device. For example, using the CANAlyzer, expect to see a log similar to the following:


printRxMsg(0)

You should see an accounting remote request message received by the node.

8. When you have completed the evaluating the test, issue the following command to terminate the test:

releaseNode(0)


time ident attr dlc data0x260 Tx r 20x260 Rx d 2 0xDD 0xEE

88 Draft: 26 Apr 04


5
Remote Request – Standard ID
This test transmits a remote request and expects a remote reply from the bus analyzer tool.


■ Uses the CAN_GetRTRRequesterChannel( ) API and uses ID 0x365. If your device does not support this API function, you must modify the test. The code contains support for the SJA1000 controller, which does not support the API. Use the SJA1000 to help code the test for your controller.

The bus analyzer must be able to transmit a remote reply with ID 0x365, 8 data bytes are requested.


1. Create a downloadable project and include the file, manual/test2/remoteReqStd.c.






6. Transmit the remote request:

transmitMsg(0)

NOTE: On controllers that do not support the requestor API function, such as the SJC1000, the controller may not set the RTR bit when receiving the request. Consult the controller documentation on how the RTR bit is handled when a remote request is received.

Draft: : 26 Apr 04 89


7. Examine the bus analyzer’s message log to verify that a remote request message was received and the reply transmitted. For example, using the CANAlyzer, expect to see a log similar to the following:


printRxMsg(0)

You should see the remote reply message is received by the node.


releaseNode(0)


Remote Request – Extended ID

This test transmits a remote request and expects a remote reply from the bus analyzer tool. This test is nearly identical to the previous test, except an extended ID is used.


■ Uses the CAN_GetRTRRequesterChannel( ) API and uses extended ID 0x35515. If your device does not support this API function, you must modify the test. The code contains support for the SJA1000 controller, which does not support the API. Use the SJA1000 to help code the test for your controller.

The bus analyzer must be able to transmit a remote reply with ID 0x35515, 8 data bytes are requested.


1. Create a downloadable project and include the file, manual/test2/remoteReqExt.c.



time ident attr dlc data0x365 Rx r 80x365 Tx d 2 0x34 0x12

90 Draft: 26 Apr 04


5




6. Transmit the remote request:

transmitMsg(0)

7. Examine the bus analyzer’s message log to verify that a remote request message was received and the reply transmitted. For example, using the CANAlyzer, expect to see a log similar to the following:


printRxMsg(0)

You should see the remote reply message is received by the node.


releaseNode(0)


time ident attr dlc data0x35515 Rx r 80x35515 Tx d 2 0x34 0x12

Draft: : 26 Apr 04 91


92 Draft: 26 Apr 04

Draft: 26 Apr 04 93

ALibraries

can_api – WIND NET CAN API documentation ................................................................... 94toucan – implementation of CAN Common Interface for Motorola TouCAN ................ 95


94 Draft: 26 Apr 04

can_api

NAME can_api – WIND NET CAN API documentation

ROUTINES CAN_Open( ) – get a handle to the requested WNCAN_DEVICECAN_Close( ) – close the handle to the requested WNCAN_DEVICECAN_GetMode( ) – get the current mode of the channelCAN_SetMode( ) – set the mode of the channelCAN_GetBusStatus( ) – get the status of the CAN busCAN_GetBusError( ) – get the bus errorsCAN_Init( ) – initialize the CAN device controllerCAN_Start( ) – bring the CAN controller onlineCAN_Stop( ) – put the CAN controller offlineCAN_SetBitTiming( ) – set the bit timing parameters of the controllerCAN_GetBaudRate( ) – get the programmed baud rate valueCAN_SetIntMask( ) – enable controller level interrupts on the CAN deviceCAN_EnableInt( ) – enable interrupts from the CAN device to the CPUCAN_DisableInt( ) – disable interrupts from the CAN device to the CPUCAN_GetNumChannels( ) – get the number of channels on the CAN controllerCAN_GetTxChannel( ) – get a free transmit channelCAN_GetRxChannel( ) – get a free receive channelCAN_GetRTRRequesterChannel( ) – get a free channel for remote transmit receiveCAN_GetRTRResponderChannel( ) – get a free channel for an automatic remote responseCAN_FreeChannel( ) – free the specified channelCAN_GetVersion( ) – get the version number of the CAN driversCAN_ReadID( ) – read the CAN ID from the specified controller and channelCAN_WriteID( ) – write the CAN ID to the specified channelCAN_ReadData( ) – read data from the specified channelCAN_GetMessageLength( ) – get the message lengthCAN_WriteData( ) – write the data to the specified channel CAN_Tx( ) – transmit the CAN message on the specified channelCAN_TxMsg( ) – transmit a CAN message with all parameters specifiedCAN_SetGlobalRxFilter( ) – set the global filter in the controllerCAN_GetGlobalRxFilter( ) – get the global filter valueCAN_SetLocalMsgFilter( ) – set a local message object filter CAN_GetLocalMsgFilter( ) – get the specified local filter valueCAN_GetIntStatus( ) – get the interrupt status of a CAN interruptCAN_IsMessageLost( ) – test if a received CAN message has been lostCAN_ClearMessageLost( ) – clear message lost indication CAN_IsRTR( ) – test if the message has the RTR bit setCAN_SetRTR( ) – test if the message has the RTR bit setCAN_TxAbort( ) – abort the current CAN transmissionCAN_Sleep( ) – put the CAN controller of the device into sleep modeCAN_WakeUp( ) – force the CAN controller out of sleep mode

A Libraries toucan

Draft: 26 Apr 04 95

A

CAN_EnableChannel( ) – enable channel and set interruptsCAN_DisableChannel( ) – reset channel interrupts and disable channelCAN_WriteReg( ) – write data to offset in CAN controller’s memory areaCAN_ReadReg( ) – access memory and read dataCAN_GetXtalFreq( ) – get the crystal frequency of the CAN controllerCAN_GetControllerType( ) – get the controller typeCAN_InstallISRCallback( ) – install the ISR callback function

DESCRIPTION This library defines the WIND NET CAN API, an interface for implementations of CAN communications.

MACRO USE For normal use, these routines are replaced by equivalent macro definitions in CAN/wnCAN.h. To avoid namespace collisions in your application code, or to implement a custom naming convention, you can redefine the macro names. To dispense with the macro definitions and use the function calls defined in this file, manually set the #define USE_CAN_FUNCTION_DEFS in the header file CAN/wncan_api.h, then recompile the CAN library with the make utility.

INCLUDE FILES CAN/wnCAN.hCAN/canBoard.h

SEE ALSO can_api

toucan

NAME toucan – implementation of CAN Common Interface for Motorola TouCAN

ROUTINES TouCAN_SetPropseg( ) – set propagation segment value

DESCRIPTION This file contains the functions, specific to the Motorola TouCAN CAN controller, that implement the interface defined in the wnCAN.h header file.

SEE ALSO toucan


96 Draft: 26 Apr 04

Draft: 26 Apr 04 97

BRoutines

CAN_ClearMessageLost( ) – clear message lost indication............................................................................. 99CAN_Close( ) – close the handle to the requested WNCAN_DEVICE ............................................ 99CAN_DisableChannel( ) – reset channel interrupts and disable channel..................................................... 100CAN_DisableInt( ) – disable interrupts from the CAN device to the CPU ........................................... 100CAN_EnableChannel( ) – enable channel and set interrupts.......................................................................... 101CAN_EnableInt( ) – enable interrupts from the CAN device to the CPU ............................................ 101CAN_FreeChannel( ) – free the specified channel ......................................................................................... 102CAN_GetBusError( ) – get the bus errors ....................................................................................................... 103CAN_GetBusStatus( ) – get the status of the CAN bus.................................................................................. 104CAN_GetControllerType( ) – get the controller type ....................................................................................... 105CAN_GetGlobalRxFilter( ) – get the global filter value................................................................................... 105CAN_GetIntStatus( ) – get the interrupt status of a CAN interrupt........................................................... 106CAN_GetLocalMsgFilter( ) – get the specified local filter value .................................................................... 107CAN_GetMessageLength( ) – get the message length ..................................................................................... 108CAN_GetMode( ) – get the current mode of the channel ....................................................................... 109CAN_GetNumChannels( ) – get the number of channels on the CAN controller....................................... 110CAN_GetRTRRequesterChannel( ) – get a free channel for remote transmit receive................................ 111CAN_GetRTRResponderChannel( ) – get a free channel for an automatic remote response ................... 112CAN_GetRxChannel( ) – get a free receive channel ......................................................................................... 113CAN_GetTxChannel( ) – get a free transmit channel....................................................................................... 114CAN_GetVersion( ) – get the version number of the CAN drivers .......................................................... 114CAN_GetXtalFreq( ) – get the crystal frequency of the CAN controller ................................................... 115CAN_Init( ) – initialize the CAN device controller ....................................................................... 116CAN_InstallISRCallback( ) – install the ISR callback function ...................................................................... 117CAN_IsMessageLost( ) – test if a received CAN message has been lost ....................................................... 118CAN_IsRTR( ) – test if the message has the RTR bit set.................................................................... 118CAN_Open( ) – get a handle to the requested WNCAN_DEVICE ................................................... 119CAN_ReadData( ) – read data from the specified channel ..................................................................... 120CAN_ReadID( ) – read the CAN ID from the specified controller and channel .............................. 121CAN_ReadReg( ) – access memory and read data.................................................................................. 122


98 Draft: 26 Apr 04

CAN_SetBitTiming( ) – set the bit timing parameters of the controller....................................................... 123CAN_SetGlobalRxFilter( ) – set the global filter in the controller .................................................................. 124CAN_SetIntMask( ) – enable controller level interrupts on the CAN device .......................................... 125CAN_SetLocalMsgFilter( ) – set a local message object filter .......................................................................... 126CAN_SetMode( ) – set the mode of the channel ...................................................................................... 127CAN_SetRTR( ) – test if the message has the RTR bit set .................................................................... 128CAN_Sleep( ) – put the CAN controller of the device into sleep mode......................................... 128CAN_Start( ) – bring the CAN controller online .............................................................................. 129CAN_Stop( ) – put the CAN controller offline ................................................................................. 129CAN_Tx( ) – transmit the CAN message on the specified channel ........................................... 130CAN_TxAbort( ) – abort the current CAN transmission....................................................................... 130CAN_TxMsg( ) – transmit a CAN message with all parameters specified ...................................... 131CAN_WakeUp( ) – force the CAN controller out of sleep mode .......................................................... 132CAN_WriteData( ) – write the data to the specified channel ................................................................... 132CAN_WriteID( ) – write the CAN ID to the specified channel ............................................................ 133CAN_WriteReg( ) – write data to offset in CAN controller’s memory area ......................................... 134TouCAN_SetPropseg( ) – set propagation segment value................................................................................ 134

B Routines CAN_ClearMessageLost( )

Draft: 26 Apr 04 99

B

CAN_ClearMessageLost( )

NAME CAN_ClearMessageLost( ) – clear message lost indication

SYNOPSIS STATUS CAN_ClearMessageLost(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum /* channel number */)

DESCRIPTION This routine clears the data overrun flag for a particular channel. Valid only for channels with mode = WNCAN_CHN_RECEIVE in the case of simple controllers or channels with mode = WNCAN_CHN_RECEIVE and WNCAN_CHN_RTR_REQUESTER in the case of advanced CAN controllers.

RETURNS OK, or ERROR.

ERRNO S_can_illegal_channel_no, S_can_illegal_config

SEE ALSO can_api

CAN_Close( )

NAME CAN_Close( ) – close the handle to the requested WNCAN_DEVICE

SYNOPSIS void CAN_Close(struct WNCAN_Device * pDev /* CAN device pointer */)

DESCRIPTION This routine deallocates the device struct that is passed in. The links to the CAN controller’s API implementations do not exist after CAN_Close( ) is called.

RETURNS N/A

ERRNO N/A

SEE ALSO can_api


100 Draft: 26 Apr 04

CAN_DisableChannel( )

NAME CAN_DisableChannel( ) – reset channel interrupts and disable channel

SYNOPSIS STATUS CAN_DisableChannel(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum /* channel number */)

DESCRIPTION This routine resets channel interrupts and marks it invalid in hardware. After this routine is called the channel will not transmit or receive any messages.

RETURNS OK if successful, ERROR otherwise.

ERRNO S_can_illegal_channel_no

SEE ALSO can_api

CAN_DisableInt( )

NAME CAN_DisableInt( ) – disable interrupts from the CAN device to the CPU

SYNOPSIS void CAN_DisableInt(struct WNCAN_Device * pDev /* CAN Device pointer */)

DESCRIPTION This routine disables interrupts from the CAN controller from reaching the CPU. Typically, it disables a global interrupt mask bit at the CPU level.

RETURNS N/A

ERRNO N/A

SEE ALSO can_api

B Routines CAN_EnableChannel( )

Draft: 26 Apr 04 101

B

CAN_EnableChannel( )

NAME CAN_EnableChannel( ) – enable channel and set interrupts

SYNOPSIS STATUS CAN_EnableChannel(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum, /* channel number */WNCAN_IntType intSetting /* interrupt type */)

DESCRIPTION This routine marks the channel valid. It also sets the type of channel interrupt requested. If the channel type does not match the type of interrupt requested it returns an error.

The interrupt settings that are available are: (choose only one)

– WNCAN_INT_RX: Message reception interrupt.

– WNCAN_INT_TX: Message transmission interrupt.

RETURNS OK if successful, ERROR otherwise.

ERRNO S_can_illegal_channel_no, S_can_illegal_config, S_can_invalid_parameter, S_can_type_mismatch

SEE ALSO can_api

CAN_EnableInt( )

NAME CAN_EnableInt( ) – enable interrupts from the CAN device to the CPU

SYNOPSIS void CAN_EnableInt(struct WNCAN_Device * pDev /* CAN Device pointer */)

DESCRIPTION This routine enables interrupts from the CAN controller to reach the CPU. Typically, it enables a global interrupt mask bit at the CPU level.

RETURNS N/A

ERRNO N/A

SEE ALSO can_api



CAN_FreeChannel( )

NAME CAN_FreeChannel( ) – free the specified channel

SYNOPSIS STATUS CAN_FreeChannel(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum /* channelNum */)

DESCRIPTION This routine frees a channel by setting its mode to WNCAN_CHN_INVALID.

RETURNS OK, or ERROR if requested channel is out of range.


SEE ALSO can_api

CAN_GetBaudRate( )

NAME CAN_GetBaudRate( ) – get the programmed baud rate value

SYNOPSIS UINT CAN_GetBaudRate(struct WNCAN_Device * pDev, /* CAN device pointer */UINT * samplePoint)

DESCRIPTION This routing returns the programed baud rate value in bits per second. The sample point value is returned by reference in the input parameter samplePoint. The sample point value is returned as a percentage. It is the percentage of the bit time at which the bit is sampled.

RETURNS The baud rate.

ERRNO N/A

SEE ALSO can_api

B Routines CAN_GetBusError( )


B

CAN_GetBusError( )

NAME CAN_GetBusError( ) – get the bus errors

SYNOPSIS WNCAN_BusError CAN_GetBusError(struct WNCAN_Device * pDev /* CAN Device pointer */)

DESCRIPTION This routine returns an ’OR’ed bit mask of all the bus errors that have occurred during the last bus activity.

Bus errors returned by this routine can have the following values:

– WNCAN_ERR_NONE: No errors detected.

– WNCAN_ERR_BIT: Bit error.

– WNCAN_ERR_ACK: Acknowledgement error.

– WNCAN_ERR_CRC: CRC error.

– WNCAN_ERR_FORM: Form error.

– WNCAN_ERR_STUFF: Stuff error.

– WNCAN_ERR_UNKNOWN: Unable to determine cause of error.

The five errors are not mutually exclusive. The occurrence of an error will be indicated by an interrupt. Typically, this routine will be called from the error interrupt handling case in the user’s ISR callback function, to find out the kind of error that occurred on the bus.

RETURNS An ’OR’ed bit mask of all the bus errors.

ERRNO S_can_Unknown_error

SEE ALSO can_api



CAN_GetBusStatus( )

NAME CAN_GetBusStatus( ) – get the status of the CAN bus

SYNOPSIS WNCAN_BusStatus CAN_GetBusStatus(struct WNCAN_Device * pDev /* CAN Device pointer */)

DESCRIPTION This routine returns the status of the CAN bus. The bus is either in a WNCAN_BUS_OFF, WNCAN_BUS_WARN, or WNCAN_BUS_OK state.

WNCAN_BUS_OFF: CAN controller is in BUS OFF state. A CAN node is bus off when the transmit error count is greater than or equal to 256.

WNCAN_BUS_WARN: CAN controller is in ERROR PASSIVE state. A CAN node is in error warning state when the number of transmit errors equals or exceeds 128, or the number of receive errors equals or exceeds 128.

WNCAN_BUS_OK: CAN controller is in ERROR ACTIVE state. A CAN node in error active state can normally take part in bus communication and sends an ACTIVE ERROR FLAG when an error has been detected.

RETURNS The status of the CAN bus.

ERRNO N/A

SEE ALSO can_api

B Routines CAN_GetControllerType( )


B

CAN_GetControllerType( )

NAME CAN_GetControllerType( ) – get the controller type

SYNOPSIS WNCAN_ControllerType CAN_GetControllerType(struct WNCAN_Device * pDev /* CAN device pointer */)

DESCRIPTION This routine returns the controller type of the CAN controller.

RETURNS The controller type.

ERRNO N/A

SEE ALSO can_api

CAN_GetGlobalRxFilter( )

NAME CAN_GetGlobalRxFilter( ) – get the global filter value

SYNOPSIS long CAN_GetGlobalRxFilter(struct WNCAN_Device * pDev, /* CAN device pointer */BOOL ext /* extended flag */)

DESCRIPTION This routine returns the programmed value in the Global filter register. Based on the value of ext passed to the routine, this routine reads the appropriate format of the global mask and returns the value in the specified extended or standard identifier format. If the controller does not have a global mask, a value of -1 is returned. This is not a valid CAN ID.

RETURNS Mask, or -1 on error.

ERRNO S_can_hwfeature_not_available

SEE ALSO can_api



CAN_GetIntStatus( )

NAME CAN_GetIntStatus( ) – get the interrupt status of a CAN interrupt

SYNOPSIS WNCAN_IntType CAN_GetIntStatus(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR * channelNum /* channel pointer */)

DESCRIPTION This routine returns the interrupt status on the controller:

WNCAN_INT_NONE = no interrupt occurredWNCAN_INT_ERROR = bus errorWNCAN_INT_TX = interrupt resulting from a CAN transmissionWNCAN_INT_RX = interrupt resulting form message receptionWNCAN_INT_BUS_OFF = interrupt resulting from bus off conditionWNCAN_INT_WAKE_UP = interrupt resulting from controller waking up after being put in sleep modeWNCAN_INT_SPURIOUS = unknown interrupt

NOTE If the interrupt was caused by the transmission or reception of a message, the channel number that generated the interrupt is set; otherwise, this value is undefined.

RETURNS The interrupt status.

ERRNO N/A

SEE ALSO can_api

B Routines CAN_GetLocalMsgFilter( )


B

CAN_GetLocalMsgFilter( )

NAME CAN_GetLocalMsgFilter( ) – get the specified local filter value

SYNOPSIS long CAN_GetLocalMsgFilter(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channel, /* channel number */BOOL ext /* extended flag */)

DESCRIPTION This routine returns the programmed value in the local filter register. Based on the value of ext passed to the routine, this routine reads the appropriate format of the local mask and returns the value in the specified extended or standard identifier format. The channel argument identifies the local filter associated with the particular channel number.

If the controller does not have a global mask, a value of -1 is returned. This is not a valid CAN ID.

RETURNS Mask, or -1 on error.


SEE ALSO can_api



CAN_GetMessageLength( )

NAME CAN_GetMessageLength( ) – get the message length

SYNOPSIS int CAN_GetMessageLength(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum /* channelNum */)

DESCRIPTION This routine returns the length of the message data in the channel on the controller. The minimum value returned is 0, and the maximum value is 8. This number is equal to the len argument in CAN_ReadData( ). If the data has zero length, this routine returns zero. The mode of the channel must not be WNCAN_CHN_INACTIVE or WNCAN_CHN_INVALID

RETURNS Length of data, or -1 if an input parameter is invalid.


SEE ALSO can_api

B Routines CAN_GetMode( )


B

CAN_GetMode( )

NAME CAN_GetMode( ) – get the current mode of the channel

SYNOPSIS WNCAN_ChannelMode CAN_GetMode(struct WNCAN_Device * pDev, /* CAN Device pointer */UCHAR chn /* device channel */)

DESCRIPTION This routine returns the mode of the channel: WNCAN_CHN_TRANSMIT, WNCAN_CHN_RECEIVE, WNCAN_CHN_INACTIVE, or WNCAN_CHN_INVALID. For advanced controllers, two additional modes exist: WNCAN_CHN_RTR_REQUESTER, or WNCAN_CHN_RTR_RESPONDER.

The mode of the channel is relevant in software only, and is indirectly related to the hardware capability (transmit, receive or both) of a channel.

Note, if the channel has not been allocated by a previous call to CAN_SetMode( ), CAN_GetTxChannel( ), CAN_GetRxChannel( ), CAN_GetRTRResponderChannel( ) or CAN_GetRTRRequesterChannel( ), the return value will be WNCAN_CHN_INVALID even though the channel number is within the range of channels available on the controller.

RETURNS The channel mode.

ERRNO N/A

SEE ALSO can_api

Mode Function

TRANSMIT Transmits data frames. In case of simple controllers, this mode can transmit a remote frame by calling CAN_SetRTR( ).

RECEIVE Receives data frames. In case of simple controllers can receive remote frames as well.

INVALID Channel is available to the CAN driver, but is free and has not been assigned a mode.

INACTIVE Channel is unavailable to the CAN driver.

RTR_REQUESTER Valid only for advanced controllers. Channel is set up to send out a remote request and receives the response to the remote frame in the same hardware channel.

RTR_RESPONDER Valid only for advanced controllers. Channel is set up to respond to an incoming remote request with the same identifier. On receiving such a frame, the response will be sent out automatically.



CAN_GetNumChannels( )

NAME CAN_GetNumChannels( ) – get the number of channels on the CAN controller

SYNOPSIS UCHAR CAN_GetNumChannels(struct WNCAN_Device * pDev /* CAN Device pointer */)

DESCRIPTION This routine returns the number of channels on the controller. This number is fixed by the hardware and does not change during operation.

RETURNS The number of channels on the controller.

ERRNO N/A

SEE ALSO can_api

B Routines CAN_GetRTRRequesterChannel( )


B

CAN_GetRTRRequesterChannel( )

NAME CAN_GetRTRRequesterChannel( ) – get a free channel for remote transmit receive

SYNOPSIS STATUS CAN_GetRTRRequesterChannel(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR * channelNum /* channel number */)

DESCRIPTION This routine is relevant to advanced controllers only. Advanced controllers are controllers, such as TouCAN, whose channels have the capability in hardware to both transmit and receive a message in the same channel. When a remote request is sent out from a particular channel, the reply will be received in the same channel. This routine will return an error and set an error number for simple controllers, such as the SJA1000. In the case of simple controllers, the channels do not have the capability to both transmit and receive messages in the same channel. The channel has a fixed property of either transmitting or receiving a message.

This function returns a free channel uniquely identified by the output argument channelNum. The mode of the channel is assigned WNCAN_CHN_RTR_REQUESTER. A subsequent call to CAN_GetRTRRequesterChannel( ) assigns the next available channel with a different channel number. The channel number remains unavailable to subsequent CAN_GetXXChannel( ) calls until a CAN_FreeChannel( ) call is invoked on the channel. CAN_FreeChannel( ) makes the channel available and resets the mode to WNCAN_CHN_INVALID. After the CAN_GetRTRRequesterChannel( ) call, the mode of the channel can be changed by the CAN_SetMode( ) function call.

RETURNS For advanced controllers, such as the TouCAN and I82527: OK, or ERROR if no channels are available.

For simple controllers, such as the SJA1000: ERROR since this mode cannot be assigned.

ERRNO For advanced controllers, such as the TouCAN and I82527: S_can_no_available_channels

For simple controllers, such as the SJA1000: S_can_rtr_mode_not_supported

SEE ALSO can_api



CAN_GetRTRResponderChannel( )

NAME CAN_GetRTRResponderChannel( ) – get a free channel for an automatic remote response

SYNOPSIS STATUS CAN_GetRTRResponderChannel(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR * channelNum /* channel number */)

DESCRIPTION This routine is relevant to advanced controllers only. Advanced controllers are controllers, such as TouCAN, whose channels have the capability in hardware to both transmit and receive a message in the same channel. An WNCAN_CHN_RTR_RESPONDER channel, can be programmed with data and ID. If a matching remote request is received in the channel, the hardware will automatically respond with the programmed data.

This routine will return an error and set an error number for simple controllers, such as the SJA1000. In the case of simple controllers, the channels do not have the capability to both transmit and receive messages in the same channel. The channel has a fixed property of either transmitting or receiving a message.

This routine returns a free transmit-receive channel uniquely identified by the output argument channelNum. The mode assigned to the channel is WNCAN_CHN_RTR_RESPONDER. A subsequent call to CAN_GetRTRResponderChannel( ) assigns the next available channel with a different channel number. The channel number remains unavailable to subsequent CAN_GetXXChannel( ) and calls until a CAN_FreeChannel( ) call is invoked on the channel. CAN_FreeChannel( ) makes the channel available and resets the mode to WNCAN_CHN_INVALID. After the CAN_GetRTRResponderChannel( ) call, the mode of the channel can be changed by the CAN_SetMode( ) function call.

RETURNS For advanced controllers, such as the TouCAN and I82527: OK, or ERROR if no channels are available.

For simple controllers, such as the SJA1000: ERROR since this mode cannot be assigned.

ERRNO For advanced controllers, such as the TouCAN and I82527: S_can_no_available_channels

For simple controllers, such as the SJA1000: S_can_rtr_mode_not_supported

SEE ALSO can_api

B Routines CAN_GetRxChannel( )


B

CAN_GetRxChannel( )

NAME CAN_GetRxChannel( ) – get a free receive channel

SYNOPSIS STATUS CAN_GetRxChannel(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR * channelNum /* channel number */)

DESCRIPTION This routine gets a free receive channel uniquely identified by the output argument channelNum. The mode of the assigned channel is WNCAN_CHN_RECEIVE. A subsequent call to CAN_GetRxChannel( ) assigns the next available receive channel with a different number. The channel number remains unavailable to subsequent CAN_GetXXChannel( ) calls until a CAN_FreeChannel( ) call is invoked on the channel. CAN_FreeChannel( ) makes the channel available and resets the mode to WNCAN_CHN_INVALID. After the CAN_GetRxChannel( ) call, the mode of the channel can be changed by the CAN_SetMode( ) function call.

RETURNS OK, or ERROR if no channel is available.

ERRNO S_can_no_available_channels

SEE ALSO can_api



CAN_GetTxChannel( )

NAME CAN_GetTxChannel( ) – get a free transmit channel

SYNOPSIS STATUS CAN_GetTxChannel(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR * channelNum /* channel number */)

DESCRIPTION This routine returns a free channel uniquely identified by the output argument channelNum. The mode of the assigned channel is WNCAN_CHN_TRANSMIT. A subsequent call to CAN_GetTxChannel( ) assigns the next available channel with a different channel number. The channel number remains unavailable to subsequent CAN_GetXXChannel( ) calls until a CAN_FreeChannel( ) call is invoked on the channel. CAN_FreeChannel( ) makes the channel available and resets the mode to WNCAN_CHN_INVALID. After the CAN_GetTxChannel( ) call, the mode of the channel can be changed by the CAN_SetMode( ) function call.

RETURNS OK, or ERROR if no channels are available.

ERRNO S_can_no_available_channels

SEE ALSO can_api

CAN_GetVersion( )

NAME CAN_GetVersion( ) – get the version number of the CAN drivers

SYNOPSIS const WNCAN_VersionInfo * CAN_GetVersion ()

DESCRIPTION This routine returns a pointer to the struct WNCAN_VersionInfo, which holds the WIND NET CAN API’s version number.

RETURNS The structure containing version information.

ERRNO N/A

SEE ALSO can_api

B Routines CAN_GetXtalFreq( )


B

CAN_GetXtalFreq( )

NAME CAN_GetXtalFreq( ) – get the crystal frequency of the CAN controller

SYNOPSIS XtalFreq CAN_GetXtalFreq(struct WNCAN_Device * pDev /* CAN device pointer */)

DESCRIPTION This routine returns the crystal frequency of the CAN controller.

RETURNS The crystal frequency.

ERRNO N/A

SEE ALSO can_api



CAN_Init( )

NAME CAN_Init( ) – initialize the CAN device controller

SYNOPSIS STATUS CAN_Init(struct WNCAN_Device * pDev /* CAN Device pointer */)

DESCRIPTION This routine initializes the CAN controller and makes default selections.

1. Puts the CAN controller into debug mode.

2. Disables interrupts at the CAN controller level as well as channel.

3. Sets bit timing values according to values stored in the CAN controller struct. Unless the user has changed these values before CAN_Init( ) is called, the default bit timing values are set to a baud rate of 250K.

4. Clears error counters.

5. Sets local and global receive masks to don’t care (accept all).

6. Makes all channels inactive in hardware.

7. Other controller specific initializations.

8. On exiting the CAN_Init( ) routine, the CAN controller has been initialized, but is offline and unable to participate in CAN bus communication.

CAN_Open( ) is called to obtain a valid device pointer. Subsequently, CAN_Init( ) and CAN_Open( ) are called to initialize the controller, bring it online, and enable active participation in CAN bus activity.

RETURNS OK.

ERRNO N/A

SEE ALSO can_api

B Routines CAN_InstallISRCallback( )


B

CAN_InstallISRCallback( )

NAME CAN_InstallISRCallback( ) – install the ISR callback function

SYNOPSIS STATUS CAN_InstallISRCallback(struct WNCAN_Device * pDev, /* CAN device pointer */void (* pFun)(struct WNCAN_Device * pDev2, /* Isr callback func ptr */WNCAN_IntType intStatus,UCHAR chnNum))

DESCRIPTION The ISR callback is written by the user, has three arguments, and returns void. The callback function executes user written message processing code inside the CAN ISR. The ISR is hardware specific and is implemented at the hardware layer of the device driver. The callback function is entered with board level CAN interrupts disabled. The first argument to the callback is the CAN device pointer. The second argument indicates the interrupt status. The third argument indicates the channel on which the interrupt was generated. The channel number is undefined if the interrupt is not due to a transmission or reception.


ERRNO S_can_invalid_parameter

SEE ALSO can_api



CAN_IsMessageLost( )

NAME CAN_IsMessageLost( ) – test if a received CAN message has been lost

SYNOPSIS int CAN_IsMessageLost(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum /* channel number */)

DESCRIPTION This routine tests if the current message data in the channel overwrote the old message data before CAN_ReadData( ) was called. Valid only for channels with mode = WNCAN_CHN_RECEIVE or WNCAN_CHN_RTR_REQUESTER.

RETURNS 0 if FALSE, 1 if TRUE, or -1 if ERROR.


SEE ALSO can_api

CAN_IsRTR( )

NAME CAN_IsRTR( ) – test if the message has the RTR bit set

SYNOPSIS int CAN_IsRTR(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum /* channel number */)

DESCRIPTION This routine tests if the message has the RTR bit set. The mode of the channel must be WNCAN_CHN_TRANSMIT or WNCAN_CHN_RECEIVE. This routine can only be used on simple controllers, such as the SJA1000. The routine will return an error if called on an advanced controller, such as the TouCAN and I82527. To receive an RTR message for advanced controllers, set the mode of the channel to WNCAN_CHN_RTR_RESPONDER.

RETURNS 0 if FALSE, 1 if TRUE, or -1 if ERROR.

ERRNO S_can_illegal_channel_mode, S_can_illegal_config

SEE ALSO can_api

B Routines CAN_Open( )


B

CAN_Open( )

NAME CAN_Open( ) – get a handle to the requested WNCAN_DEVICE

SYNOPSIS struct WNCAN_Device *CAN_Open(unsigned int brdType, /* board type */unsigned int brdNdx, /* board index */unsigned int ctrlNdx /* controller index */)

DESCRIPTION This is the first routine called. This routine establishes links to the CAN controller specific API implementation. The CAN API cannot be accessed before the device pointer has been correctly initialized by this routine.

RETURNS Pointer to valid WNCAN_DEVICE, or 0 if an error occurred.

ERRNO S_can_unknown_board, S_can_illegal_board_no, S_can_illegal_ctrl_no, S_can_busy

SEE ALSO can_api



CAN_ReadData( )

NAME CAN_ReadData( ) – read data from the specified channel

SYNOPSIS STATUS CAN_ReadData(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR chnNum, /* channel number */UCHAR * data, /* pointer to buffer for data */UCHAR * len, /* length pointer */BOOL * newData /* new data pointer */)

DESCRIPTION This routine reads len bytes of data from the channel and sets the value of len to the number of bytes read. The range of len is zero (for zero length data) to a maximum of eight. The mode of the channel must not be WNCAN_CHN_INVALID or WNCAN_CHN_INACTIVE; however, the newData flag is valid only for channels with mode equal to WNCAN_CHN_RECEIVE or WNCAN_CHN_RTR_REQUESTER. For receive channels, if no new data has been received since the last CAN_ReadData( ) function call, the newData flag is set to FALSE; otherwise, the flag is TRUE. In both cases, the data and length of the data currently in the channel are read. The input parameter len, contains length of data buffer on entering the routine. On return len contains number of bytes copied into data buffer.

RETURNS OK, or ERROR if an input parameter is invalid.

ERRNO S_can_illegal_channel_no, S_can_illegal_config, S_can_buffer_overflow, S_can_illegal_data_length

SEE ALSO can_api

B Routines CAN_ReadID( )


B

CAN_ReadID( )

NAME CAN_ReadID( ) – read the CAN ID from the specified controller and channel

SYNOPSIS long CAN_ReadID(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum, /* channel number */BOOL* ext /* extended flag */)

DESCRIPTION This routine reads the CAN ID corresponding to the channel number on the controller. The standard or extended flag is set by the routine. The mode of the channel can not be WNCAN_CHN_INACTIVE or WNCAN_CHN_INVALID. The extended flag is set to TRUE if the ID has extended format, otherwise it is set to FALSE.

RETURNS The CAN ID, or -1 if an input parameter is invalid.


SEE ALSO can_api



CAN_ReadReg( )

NAME CAN_ReadReg( ) – access memory and read data

SYNOPSIS STATUS CAN_ReadReg(struct WNCAN_Device * pDev, /* CAN device pointer */UINT offset, /* from base of CAN controller */UCHAR * data, /* return data place holder */UINT length /* number of bytes to be copied */)

DESCRIPTION This routine accesses the CAN controller memory at the offset specified. A list of valid offsets are defined as macros in a CAN controller specific header file, named as controllerOffsets.h (for example, toucanOffsets.h or sja1000Offsets.h). A pointer to the data buffer to hold the data to be read, is passed through UINT *data. The length of the data to be copied is specified through the length parameter.

RETURNS OK.

ERRNO S_can_illegal_offset

SEE ALSO can_api

B Routines CAN_SetBitTiming( )


B

CAN_SetBitTiming( )

NAME CAN_SetBitTiming( ) – set the bit timing parameters of the controller

SYNOPSIS STATUS CAN_SetBitTiming(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR tseg1, /* number of time quanta for segment 1 */UCHAR tseg2, /* number of time quanta for segment 2 */UCHAR brp, /* baud rate prescaler */UCHAR sjw, /* syncro jump width */BOOL numSamples/* number of samples */)

DESCRIPTION This routine sets the baud rate and sample point of the controller. The values of the input parameters should be based on an established set of recommendations.

The routine sets the bit timing values in the hardware as well as the controller structure, so that the bit timing values are not lost if CAN_Init( ) is called again.

The routine will preserve the state of the CAN controller. For example, if the CAN controller is online when the routine is called, then the CAN controller will be online after the routine exits.

tseg1 and tseg2 are interpreted according to controller specific definitions and, therefore, can be written to directly using this routine. In all supported controllers, tseg2 refers to the segment of bit time after the sample point. However, tseg1 interpretations vary.

In some controllers, tseg1 refers to the segment of bit time from the end of the sync segment, up to the sample point. Bit time = 1 + (tseg1 + 1) + (tseg2 + 1) time quanta.

For other controllers, tseg1 refers to the segment of bit time from the end of propseg, up to the sample point. Bit time = 1 + (propseg + 1) + (tseg1 + 1) + (tseg2 + 1) time quanta.

tseg1 tseg2sync

sample point

sync tseg2

sample point

propseg tseg1



There is a controller specific function provided to set the propseg of these controllers (see TouCAN_SetPropseg( ), for example). Also, there will be a place holder for the propseg (with the other bit timing parameters) in the CAN controller struct.

For TouCAN the default value of propseg is 7.

The number of samples taken at the sample point is decided by the input argument numSamples to the function. numSamples = 0 (FALSE) indicates one sample will be taken. numSamples = 1 (TRUE) indicates three samples will be taken.

RETURNS OK, or ERROR if any of the input parameters have invalid values.


SEE ALSO can_api

CAN_SetGlobalRxFilter( )

NAME CAN_SetGlobalRxFilter( ) – set the global filter in the controller

SYNOPSIS STATUS CAN_SetGlobalRxFilter(struct WNCAN_Device * pDev, /* CAN device pointer */long mask, /* filter mask value */BOOL ext /* extended flag */)

DESCRIPTION This routine sets the global HW filter mask for incoming messages on the device controller. If the controller does not have a global filter this routine is a no-op. If the ext parameter is TRUE, the mask value applies to extended messages; otherwise, the mask values applies to standard messages. A value of 0 for a particular bit position of the mask means don’t care (for example, the incoming message ID could have a value of zero or one for this bit position); otherwise, a value of 1 means the corresponding bit of the message ID must match identically.

If the controller does not have a global mask, an error is returned.



SEE ALSO can_api

B Routines CAN_SetIntMask( )


B

CAN_SetIntMask( )

NAME CAN_SetIntMask( ) – enable controller level interrupts on the CAN device

SYNOPSIS STATUS CAN_SetIntMask(struct WNCAN_Device * pDev, /* CAN Device pointer */WNCAN_IntType intMask /* ‘OR’ed interrupt masks */)

DESCRIPTION This routine enables the specified list of controller level interrupts on the CAN controller. Interrupts are not enabled at the CAN board level or at the CPU level.

The interrupt masks available are:

– WNCAN_INT_ERROR: Enables interrupts due to errors on the CAN bus. This may be implemented as a single or multiple interrupt source on the CAN controller.

– WNCAN_INT_BUS_OFF: Enables interrupt indicating bus off condition.

– WNCAN_INT_WAKE_UP: Enables interrupt on wake up.

In order to be set, all interrupt masks that need to be enabled must be specified in the list passed to the routine every time the routine is called.

RETURNS OK, or ERROR if interrupt setting not possible.

ERRNO S_can_hwfeature_not_available, S_can_invalid_parameter

SEE ALSO can_api



CAN_SetLocalMsgFilter( )

NAME CAN_SetLocalMsgFilter( ) – set a local message object filter

SYNOPSIS STATUS CAN_SetLocalMsgFilter(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channel, /* channel number */long mask, /* filter mask value */BOOL ext /* extended flag */)

DESCRIPTION This routine sets a local message object filter for incoming messages on a particular channel.

If the ext parameter is TRUE, the mask value applies to extended messages; otherwise, the mask value applies to standard messages. A value of 0 for a particular bit position of the mask means don’t care (for example, the incoming message ID could have a value of zero or one for this bit position); otherwise, a value of 1 means the corresponding bit of the message ID must match identically. Channel number is provided for controllers that have more than one local message object filter.

If the controller does not have a local mask for the channel specified, an error is returned.

RETURNS OK, ERROR.

ERRNO S_can_illegal_channel_no, S_can_hwfeature_not_available

SEE ALSO can_api

B Routines CAN_SetMode( )


B

CAN_SetMode( )

NAME CAN_SetMode( ) – set the mode of the channel

SYNOPSIS STATUS CAN_SetMode(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum, /* channel number */WNCAN_ChannelMode mode /* channel mode */)

DESCRIPTION This routine sets the mode of the channel to one of five values: WNCAN_CHN_TRANSMIT, WNCAN_CHN_RECEIVE, WNCAN_CHN_INACTIVE, WNCAN_CHN_RTR_REQUESTER, or WNCAN_CHN_RTR_RESPONDER. WNCAN_CHN_RTR_REQUESTER and WNCAN_CHN_RTR_RESPONDER are used for advanced controllers. All available channels can be configured to be WNCAN_CHN_INACTIVE. The channels available for transmitting or receiving messages are determined by the device hardware, and therefore, may or may not be configurable with this function call. If an attempt is made to set the mode of a channel to WNCAN_CHN_RTR_RESPONDER or WNCAN_CHN_RTR_REQUESTER for a simple CAN controller such as SJA1000, WNCAN_CHN_INVALID is returned and an errno is set to reflect the error. The preferred approach is to allow the device driver to manage the channels internally using the CAN_GetTxChannel( ), CAN_GetRxChannel( ), CAN_GetRTRRequesterChannel( ), CAN_GetRTRResponderChannel( ) and CAN_FreeChannel( ) function calls.

RETURNS OK, or ERROR if the requested channel number is out of range.


SEE ALSO can_api



CAN_SetRTR( )

NAME CAN_SetRTR( ) – test if the message has the RTR bit set

SYNOPSIS STATUS CAN_SetRTR(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum, /* channel number */BOOL rtr /* rtr flag (TRUE = set bit) */)

DESCRIPTION This routine tests if the message has the RTR bit set. The mode of the channel must be WNCAN_CHN_TRANSMIT. This routine can only be used on simple controllers, such as the SJA1000. The routine will return an error if called on an advanced controller, such as the TouCAN and I82527. To send an RTR message for advanced controllers, set the mode of the channel to WNCAN_CHN_RTR_REQUESTER and call CAN_Tx( ).


ERRNO S_can_illegal_channel_mode, S_can_illegal_config

SEE ALSO can_api

CAN_Sleep( )

NAME CAN_Sleep( ) – put the CAN controller of the device into sleep mode

SYNOPSIS STATUS CAN_Sleep(struct WNCAN_Device * pDev /* CAN device pointer */)

DESCRIPTION This routine puts the CAN controller into sleep mode if the hardware supports this functionality; otherwise, this routine is a no-op.


ERRNO S_can_cannot_sleep_in_reset_mode

SEE ALSO can_api

B Routines CAN_Start( )


B

CAN_Start( )

NAME CAN_Start( ) – bring the CAN controller online

SYNOPSIS void CAN_Start(struct WNCAN_Device * pDev /* CAN Device pointer */)

DESCRIPTION This routine is called to bring the CAN controller online. The CAN controller can now participate in transmissions and receptions on the CAN bus. This routine must be called after CAN_Init( ) has been called to initialize and bring the CAN controller up in a known state. This routine negates the INIT/HALT (offline) bit.

RETURNS OK.

SEE ALSO can_api

CAN_Stop( )

NAME CAN_Stop( ) – put the CAN controller offline

SYNOPSIS void CAN_Stop(struct WNCAN_Device * pDev /* CAN Device pointer */)

DESCRIPTION This routine disables communication between the CAN controller and the CAN bus.

RETURNS OK.

ERRNO N/A

SEE ALSO can_api



CAN_Tx( )

NAME CAN_Tx( ) – transmit the CAN message on the specified channel

SYNOPSIS STATUS CAN_Tx(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum /* channel number */)

DESCRIPTION This routine transmits the CAN ID and data currently in the channel of the specified controller on the device. The mode of the channel must be WNCAN_CHN_TRANSMIT or WNCAN_CHN_RTR_REQUESTER.



SEE ALSO can_api

CAN_TxAbort( )

NAME CAN_TxAbort( ) – abort the current CAN transmission

SYNOPSIS void CAN_TxAbort(struct WNCAN_Device * pDev /* CAN device pointer */)

DESCRIPTION This routine aborts any current CAN transmissions on the controller.

RETURNS N/A

ERRNO N/A

SEE ALSO can_api

B Routines CAN_TxMsg( )


B

CAN_TxMsg( )

NAME CAN_TxMsg( ) – transmit a CAN message with all parameters specified

SYNOPSIS STATUS CAN_TxMsg(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum, /* channel number */ULONG canId, /* CAN ID */BOOL ext, /* extended message flag */UCHAR * data, /* pointer to buffer for data */UCHAR len /* message length */)

DESCRIPTION This routine performs the same function as the following series of function calls:

CAN_WriteID(context,channelNum,canID,ext);CAN_WriteData(context,channelNum,data,len);CAN_Tx(context,channel);

The mode of the channel must be WNCAN_CHN_TRANSMIT or WNCAN_CHN_RTR_REQUESTER. If the length specified exceeds 8 bytes an error will be returned. The extended flag must be set to TRUE if the ID has extended format, or FALSE if the ID has standard format.


ERRNO S_can_illegal_channel_no, S_can_illegal_config, S_can_illegal_data_length

SEE ALSO can_api



CAN_WakeUp( )

NAME CAN_WakeUp( ) – force the CAN controller out of sleep mode

SYNOPSIS STATUS CAN_WakeUp(struct WNCAN_Device * pDev)

DESCRIPTION This routine negates the Sleep bit to force the CAN controller out of sleep mode.

RETURNS OK, always.

ERRNO N/A

SEE ALSO can_api

CAN_WriteData( )

NAME CAN_WriteData( ) – write the data to the specified channel

SYNOPSIS STATUS CAN_WriteData(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR channelNum, /* channel number */UCHAR * data, /* pointer to data buffer */UCHAR len /* length of data buffer */)

DESCRIPTION This routine writes len bytes of data to the channel. An error is returned if the number of bytes to be written exceed 8. The mode of the channel must WNCAN_CHN_TRANSMIT or WNCAN_CHN_RTR_RESPONDER.


ERRNO S_can_illegal_channel_no, S_can_illegal_config, S_can_illegal_data_length

SEE ALSO can_api

B Routines CAN_WriteID( )


B

CAN_WriteID( )

NAME CAN_WriteID( ) – write the CAN ID to the specified channel

SYNOPSIS STATUS CAN_WriteID(struct WNCAN_Device * pDev, /* CAN device pointer */UCHAR chnNum, /* channel number */ULONG canID, /* CAN ID */BOOL ext /* TRUE = extended CAN msg */)

DESCRIPTION This routine writes the CAN ID to the channel. The type of ID (standard or extended) is specified. The behavior of the routine for every channel mode is specified as follows:

– WNCAN_CHN_INVALID: Not allowed. ERROR is returned.

– WNCAN_CHN_INACTIVE: Not allowed. ERROR is returned.

– WNCAN_CHN_RECEIVE: CAN messages with this ID will be received.

– WNCAN_CHN_RTR_RESPONDER: The data bytes to respond with must be set up with a call to CAN_WriteData( ) previously. CAN messages with this ID will be received and a remote response message sent back.

– WNCAN_CHN_RTR_REQUESTER: A CAN message with RTR bit set and the specified ID will be transmitted when CAN_Tx( ) is called.

– WNCAN_CHN_TRANSMIT: A CAN message with the specified ID will be transmitted when CAN_Tx( ) is called.



SEE ALSO can_api



CAN_WriteReg( )

NAME CAN_WriteReg( ) – write data to offset in CAN controller’s memory area

SYNOPSIS STATUS CAN_WriteReg(struct WNCAN_Device * pDev, /* CAN device pointer */UINT offset, /* from base of CAN controller memory */UCHAR * data, /* byte pointer to data to be written */UINT length /* number of bytes to be written */)

DESCRIPTION This routine accesses the CAN controller memory at the offset specified. A list of valid offsets are defined as macros in a CAN controller specific header file, named as controllerOffsets.h (for example, toucanOffsets.h or sja1000Offsets.h). A pointer to the data buffer holding the data to be written is passed to the routine in UCHAR *data. The number of data bytes to be copied from the data buffer to the CAN controller’s memory area is specified by the length parameter.

RETURNS OK.

ERRNO S_can_illegal_offset

SEE ALSO can_api

TouCAN_SetPropseg( )

NAME TouCAN_SetPropseg( ) – set propagation segment value

SYNOPSIS STATUS TouCAN_SetPropseg(struct WNCAN_Device * pDev,UCHAR propseg)

DESCRIPTION This routine sets propagation segment value, if called before CAN_SetBitTiming( ).



SEE ALSO toucan

Draft: 26 Apr 04

C
CAN Board Support
C.1 Introduction 136

C.2 CAN Board Identifiers 136

C.3 Supported CAN Board/Processor Configurations 137

C.4 ADLINK 7841 137

C.5 Biscayne HCAN2 138

C.6 ESD PC104-200 139

C.7 ESD PCI/200 140

C.8 MSMCAN PC104 141

C.9 PPC5xx TouCAN 142

C.10 Tahoe-Amanda HCAN2 143

C.11 MCF5282 FlexCAN 144

135


C.1 Introduction

This appendix starts with tables providing brdType parameter values and supported processor configurations. It continues with board-specific information for each of the supported CAN boards.

For controller-specific information for each of the supported CAN controllers, see D. CAN Controller Support.

C.2 CAN Board Identifiers

The identifiers in the table below can be used in CAN_Open( ) for the brdType parameter value.

CAN Board Identifier

ADLINK 7841 WNCAN_ADLINK_7841

Biscayne HCAN2 WNCAN_SHBISCAYNE

ESD PC104-200 WNCAN_ESD_PC104_200

ESD PCI/200 WNCAN_ESD_PCI_200

MSMCAN PC104 WNCAN_MSMCAN

PPC5xx TouCAN WNCAN_PPC5XX

Tahoe-Amanda HCAN2 WNCAN_SHTAHOEAMANDA

Coldfire M5282EVB WNCAN_MCF5282


C CAN Board SupportC.3 Supported CAN Board/Processor Configurations

C

C.3 Supported CAN Board/Processor Configurations

The following combinations of CAN devices and target boards have been verified by Wind River. While it is likely that the driver for the PCI based CAN cards will work without modification, this should be verified by the user. If it is necessary to port support for an existing device type to a new target, or to create support for a different CAN device, see Chapter 5. Driver Developer Kit.

C.4 ADLINK 7841

The ADLINK 7841 CAN board is a product manufactured by ADLINK TECHNOLOGY, INC. It supports both CAN 2.0A and CAN 2.0B message formats and can operate at bit rates up to 1Mbit/second. This board uses a PCI bus to connect with a target.

For more information about this board, see:

ProcessorFamily

CPUs CAN Boards

I80X86 486, 386, Pentium ESD PC104-200,ESD PCI/200,MSMCAN PC104

PPC mbx860 ESD PC104-200,MSMCAN PC104

PPC mpx5xx PPC5xx TouCAN

SH BigSur 7750, 7751, 7751/R,Solution Engine

ESD PCI/200

SH BigSur 7751/R Tahoe-Amanda HCAN2

SH SH7760 Biscayne HCAN2

Coldfire MCF5282 MCF5282 FlexCAN (m5282evb)

Draft: : 26 Apr 04 137


http://www.adlinktech.com

C.4.1 ADLINK 7841 Controller Support

The ADLINK 7841 board supports the following CAN controllers. Controller Index is used in CAN_Open( ) for the ctrlNdx parameter value.

C.5 Biscayne HCAN2

The Biscayne is a reference board using the Hitachi SH7760 (Camelot) processor core. This core contains an on-chip HCAN2 device. The HCAN2 device contains 2 CAN controllers capable of 1Mbit/s baud rate.

C.5.1 Biscayne HCAN2 Suggested IRQ Setting

Each CAN controller is mapped to separate interrupt request. The controllers are considered on-chip devices and each have assigned an appropriate IRQ line for such devices. The default controller priorities are both set to the same level and can be changed from the component parameters GUI. For more information about HCAN2 device priority, consult the Hitachi SH7760 hardware manual.

NOTE: When using this board with SH-based BSPs, you may need to add a C define symbol identifying which specific target board is used. Without an appropriate defined symbol, you will get compile errors within your project. Examine the source code reporting the compile error to determine the proper symbol.

CAN Controller Controller Index

Phillips SJA 1000 0

Phillips SJA 1000 1


http://www.adlinktech.com

C CAN Board SupportC.6 ESD PC104-200

C

C.5.2 Biscayne HCAN2 Controller Support

The SH7760 processor code supports the following CAN controllers. Controller Index is used in CAN_Open( ) for the ctrlNdx parameter value.

C.6 ESD PC104-200

The ESD PC104-200 board is a product of esd electronic system design gmbh (ESD). It supports both CAN 2.0A and CAN2.0B message formats and can operate at bit rates up to 1Mbit/second. ESD PC104-200 uses the PC/104 interface to connect to a target board.

More information about the ESD PC104-200 board is available at:

http://www.esd-electronics.com


HCAN2 0

HCAN2 1

NOTE: When using this board with SH-based BSPs, you may need to add a C define symbol identifying which specific target board is used. Without an appropriate defined symbol, you will get compile errors within your project. Examine the source code reporting the compile error to determine the proper symbol.

Draft: : 26 Apr 04 139



C.6.1 ESD PC104-200 Suggested I/O Addresses and IRQ Settings

The table below contains the suggested IRQ and I/O Address settings for the ESD PC104-200 board. See 2.5.2 Setting Properties for a CAN Board Component, p.17. For I/O address jumper switch settings, consult the board manufacturer’s data sheet.

C.6.2 ESD PC104-200 Controller Support

The ESD PC104-200 board contains the following CAN controllers. Controller Index is used in CAN_Open( ) for the ctrlNdx parameter value.

C.7 ESD PCI/200

The ESD PCI/200 board is a product of ESD. It supports both CAN 2.0A and CAN2.0B message formats and can operate at bit rates up to 1Mbit/second. ESD PCI/200 uses the PCI interface to connect to a target board.

More information about the ESD PCI/200 board is available at:


Processor Family I/O Address IRQ

Intel PC 0x1E8 0x05

PPC 0x800001e8 0x05


Intel 82527 0

Phillips SJA 1000 1

Siemens 81C91 Not supported



C CAN Board SupportC.8 MSMCAN PC104

C

C.7.1 ESD PCI/200 Controller Support

The ESD PC104-200 board contains the following CAN controllers. Controller Index is used in CAN_Open( ) for the ctrlNdx parameter value.

C.8 MSMCAN PC104

The MSMCAN PC104 board (also known as the Microspace PC/104 CAN card) is a product of Advanced Digital Logic, Inc. (ADL). It supports both CAN 2.0A and CAN2.0B message formats and can operate at bit rates up to 500Kbit/second. MSMCAN PC104 uses the PC/104 interface to connect to a target board.

More information about the MSMCAN PC104 board is available at:

http://www.adlogic-pc104.com

C.8.1 MSMCAN PC104 Suggested I/O Addresses and IRQ Settings

The table below contains the suggested IRQ and I/O Address settings for the MSMCAN PC104 board. See 2.5.2 Setting Properties for a CAN Board Component, p.17. For I/O address jumper switch settings, consult the board manufacturer’s data sheet.


Phillips SJA 1000 0

Phillips SJA 1000 1

Processor Family I/O Address IRQ

Intel PC 0x320 0x09

PPC 0x80000320 0x09

Draft: : 26 Apr 04 141

http://www.adlogic-pc104.com


C.8.2 MSMCAN PC104 Controller Support

The MSMCAN PC104 board contains the following CAN controllers. Controller Index is used in CAN_Open( ) for the ctrlNdx parameter value.

C.8.3 MSMCAN PC104 Limitations

CAN_Sleep( ) and CAN_Wakeup( ) cannot be used with the MSMCAN PC104 board. The I82527 controller's CLKOUT pin is connected to the microprocessor monitor IC MAX1232. Sleep mode disables the CLKOUT pin. If the pin remains disabled for 1200 ms, the microprocessor monitor IC MAX1232 resets the I82527 controller.

C.9 PPC5xx TouCAN

The PPC5xx TouCAN board is actually the MPC5xx microprocessor core. The MPC5xx core is available on target boards from several vendors. It supports both CAN 2.0A and CAN2.0B message formats, and can operate at bit rates up to 1Mbit/second.

More information about the MPC5xx core is available at:

http://www.motorola.com

C.9.1 PPC5xx TouCAN Suggested IRQ Setting

The PPC5xx TouCAN IRQ should be set to an unused level between 1 and 7.


Intel 82527 0

NOTE: Although the IRQ setting for the PPC5xx TouCAN refers to a controller event, this setting is entered as a parameter for the PPC5xx TouCAN board component. See 2.5.2 Setting Properties for a CAN Board Component, p.17.


http://www.motorola.com

C CAN Board SupportC.10 Tahoe-Amanda HCAN2

C

C.9.2 PPC5xx TouCAN Controller Support

The MPC5xx core contains the following CAN controllers. Controller Index is used in CAN_Open( ) for the ctrlNdx parameter value.

C.10 Tahoe-Amanda HCAN2

The Tahoe-Amanda HCAN2 board is a Tahoe-style daughter board for the BigSur7751/R baseboard. It contains the Amanda multi-media chip set and various external I/O components. CAN is one of many multi-media device controllers on the Amanda chip set. Both the Tahoe-Amanda and the BigSur boards are made by Hitachi.

Consult your Hitachi representative to obtain the latest draft of the Tahoe-Amanda board documentation.

C.10.1 Tahoe-Amanda HCAN2 Suggested IRQ Setting

The default setting for the controller IRQ priority is the IRQ priority given to the HCAN2 controllers within the Amanda Interrupt Control module. For more information about the Interrupt Control module and device priorities, consult the Amanda companion chip documentation (HD64404). The IRQ for the board itself is fixed.


TouCAN 0

TouCAN 1

NOTE: Although the IRQ priority setting for the Tahoe-Amanda HCAN2 board refers to a controller event, this setting is entered as a parameter for the PPC5xx TouCAN board component. See 2.5.2 Setting Properties for a CAN Board Component, p.17.

Draft: : 26 Apr 04 143


C.10.2 Tahoe-Amanda HCAN2 Controller Support

The Amanda companion chip contains the following CAN controllers. Controller Index is used in CAN_Open( ) for the ctrlNdx parameter value.

C.10.3 Tahoe-Amanda HCAN2 Transceivers and Connectors

On Revision C of the Tahoe-Amanda board, the two CAN controllers are wired to standard DB9 connectors on the top board:

■ J1: connector for controller #0 using a high-speed transceiver with a bit rate up to 1Mbit/second. The CANHI and CANLO signals are connected to pins #2 and #7. This connector is labeled CAN2 on the top board front faceplate.

■ J2: connector for controller #1 using a low-speed transceiver with a bit rate up to 125Kbit/second. The CANHI and CANLO signals are connected to pins #4 and #8. In addition, the transceiver requires a supply voltage. Consult the board schematics and transceiver chip documentation for proper connection to this transceiver. This connector is labeled CAN1 on the top board front faceplate.

C.11 MCF5282 FlexCAN

The MCF5282 FlexCAN board is identical to the MCF5282 microprocessor core. The MCF5282 core is available on target board m5282evb from Motorola. It supports both CAN 2.0A and CAN2.0B message formats and can operate at bit rates up to 1Mbit/second. Information about the MCF5282 core is available at:

http://e-ww.motorola.com/webapp/sps/site/prod_summary.jsp?code=MCF5282


HCAN2 0

HCAN2 1


C CAN Board SupportC.11 MCF5282 FlexCAN

C

C.11.1 MCF5282 FlexCAN Controller Support

The MCF5282 core contains the FlexCAN CAN controller. Controller Index is used in CAN_Open( ) for the ctrlNdx parameter value.


FlexCAN 0

Draft: : 26 Apr 04 145

Draft: 26 Apr 04

D
CAN Controller Support
D.1 Introduction 147

D.2 Intel 82527 148

D.3 Phillips SJA 1000 148

D.4 TouCAN 149

D.5 HCAN2 149

D.6 FlexCAN 151

D.1 Introduction

This appendix describes CAN controller chip sets supported in WIND NET CAN. Each supported CAN board contains one or more of these controllers.

For board-specific information for each of the supported CAN boards, see C. CAN Board Support.

147


D.2 Intel 82527

The Intel 82527 controller provides 15 channels. Channel numbers 0 to 13 can be configured to be either transmit or receive channels. Channel 14 is receive only, and has a dedicated receive filter (distinct from the global receive filter) that can be set using CAN_SetLocalMsgFilter( ). This filter allows an additional range of CAN messages to be received on channel 14 after testing for a match on all other receive channels. To use channel 14 to receive a range of CAN IDs, call CAN_SetMode( ) followed by CAN_SetLocalMsgFilter( ) as follows:

CAN_SetMode(devPtr, 14, WNCAN_CHN_RECEIVE);CAN_SetLocalMsgFilter(devPtr, mask value);

Because the Intel 82527 can be configured to receive on multiple channels, CAN_WriteId( ) is used in conjunction with the global receive filter. The global filter specifies the ID bit positions that must match. Starting with the lowest numbered receive channel, the Intel 82527 tests for a match on each channel configured to receive. If a match occurs, a CPU interrupt is generated for that channel.

You should exercise caution in assigning multiple transmit channels in conjunction with setting the global receive filter. If two transmit channels have CAN IDs that are non-distinct after being filtered, the Intel 82527 will not recognize a transmit of the higher numbered channel. This will result in the higher number channel retransmitting without end because the transmit request bit will not be reset by the controller.

D.3 Phillips SJA 1000

Only one transmit and one receive channel are available for use on this controller. The transmit channel operates in only one of two modes: either WNCAN_CHN_INACTIVE or WNCAN_CHN_TRANSMIT. Similarly, the receive channel operates in only one of two modes: WNCAN_CHN_INACTIVE, or WNCAN_CHN_RECEIVE.

Because the transmit and receive channel numbers are preassigned, the channel numbers should be obtained through CAN_GetTxChannel( ) and CAN_GetRxChannel( ). Otherwise, you should first check the channel type with CAN_GetChannelType( ), then call CAN_SetMode( ) accordingly.


D CAN Controller SupportD.4 TouCAN

D

Because only one receive channel is available, both CAN_WriteId( ) and CAN_SetGlobalRxFilter( ) set the value of the global receive filter. CAN_WriteId( ) sets the global receive filter to receive only those messages that exactly match the specified ID. Use a call to CAN_SetGlobalRxFilter( ) to override the CAN_WriteId( ) global receive filter setting.

D.4 TouCAN

The PPC5xx TouCAN controller contains a half speed bit that affects the setting of baud rates. The half speed bit is enabled by setting the #define UMCR_HSPEED = 1 in your target’s config.h file.

When the half speed bit is enabled, you can obtain a desired baud rate by halving the value of the brp (baud rate prescaler) argument to CAN_SetBitTiming( ).

For example, if a baud rate of 250K is obtained with the half speed bit disabled by setting brp = 20, then to obtain that same rate with the half speed bit enabled, set brp = 10.

D.5 HCAN2

The Hitachi CAN version 2 (HCAN2) controller supports both CAN 2.0A and CAN2.0B message formats and operates at bit rates up to 1Mbit/second. It has 32 channels: channel 0 is receive-only, and channels 1-31 are receive-transmit.

Documentation for this controller is available from your Hitachi representative, and is included within the HD64404 Amanda companion chip documentation.

D.5.1 HCAN2 Limitations

The following WIND NET CAN API routines are NOT supported:

■ CAN_GetGlobalFilter( ) and CAN_SetGlobalFilter( )

■ CAN_SetRTR( ) and CAN_IsRTR( )

Draft: : 26 Apr 04 149


D.5.2 Channel Interrupts

One type of channel interrupt is used for both transmitting and receiving. However, to optimize code portability, use the appropriate WNCAN_IntType interrupt specification (WNCAN_INT_RX or WNCAN_INT_TX) with CAN_EnableChannel( ).

D.5.3 Remote Frames

The HCAN2 controller supports the use the WIND NET CAN Requester/Responder routines: CAN_GetRTRRequesterChannel( ) and CAN_GetRTRResponderChannel( ). The responder channel is configured for automatic transmission upon reception of the remote frame. No action is required by the application.

The responder channel uses the length (DLC field) of the received remote message as the length of the transmitted message.

D.5.4 Register Access

The WIND NET CAN API interface assumes that controller registers are 8 bit. However, PPC5xx TouCAN controller registers are 16 bit, and for proper operation, they must be accessed as 16 bit data. Therefore, when using CAN_ReadReg( ) and CAN_WriteReg( ), you must provide a data pointer aligned for 16 bit data.

The length parameter for these calls is specified in bytes (so to read n registers, you should specify a length of 2n).

The following example reads two 16 bit registers, BCR1 and BCR0, from an HCAN controller.

( short bcr[2];

...open and init the device...

CAN_ReadReg(pDev, HCAN2_BCR1_OFFSET, (UCHAR*)bcr, 4);}


D CAN Controller SupportD.6 FlexCAN

D

D.6 FlexCAN

The FlexCAN controller supports both CAN 2.0A and CAN2.0B message formats and operates at bit rates up to 1Mbit/second. It has 16 channels and 3 programmable mask (filter) registers: a global mask (for channels 0-13) and two local masks, one for channel 14 and one for channel 15.

The FlexCAN controller is based on and includes all features of the TouCAN controller. For more information refer to the chapter on FlexCAN in the MCF5282 ColdFire Microcontroller User’s Manual.

D.6.1 Bit Timing Considerations

The FlexCAN bitTiming calculation assumes a factor of 2 while calculating the S-clock:

S-clock = fsys / 2(PRESDIV + 1)

This factor should be accounted for when specifying the PRESDIV and other bit timing values to get the desired baud rate.

D.6.2 B.5.2 FlexCAN Interrupts

The FlexCAN can generate upto 19 interrupts—16 message interrupts and interrupts for error, wakeup and standby. Each channel can be an interrupt source. There is no distinction between a transmit and receive interrupt for a particular buffer.

Two interrupt controllers on the MCF5282 handle the complete set of interrupt sources from all modules on the device. Each of the interrupt controllers sends a 3-bit encoded priority level to the CPU core, providing seven levels of interrupt request. Level 7 is the highest priority interrupt level, while level 1 is the lowest. Level-7 interrupts are non-maskable and edge-sensitive within the processor.

Each level supports a 3-bit priority. The priority field decides the priority of interrupt sources within the same level. Level and priority are fully programmable for all sources except interrupt sources 1 through 7. The interrupt source numbers for the Flexcan module on the MCF5282 are, (8) (INT_NUM_CAN_BUF0) through (26) (INT_NUM_CAN_WAKE) on interrupt controller INTC1.

Draft: : 26 Apr 04 151


The interrupt source number provides an offset into the interrupt controller’s memory map, identifying the Interrupt Control Register (ICRnx) for that source. The 3-bit level and the 3-bit priority within the level are defined in the 8-bit ICRnx.

Default selections for interrupt level and priority for all sources on the FlexCAN module are:

Interrupt Level = 4

Interrupt Priority = 1

Specifying the interrupt level and priority from the FlexCAN-related VxWorks configuration macros sets the same interrupt level and priority for all sources. To specify different interrupt levels or priorities for individual FlexCAN interrupt sources, you can use the routine FlexCAN_SetIntLevel( ) (see [* Xref]).

To specify different interrupt levels or priorities for individual FlexCAN interrupt sources, you can use the routine FlexCAN_SetIntLevel( ) (see [* Xref]).

The FlexCAN interrupt sources and their corresponding numbers are listed in the following table:

Table D-1 FlexCAN interrupt source numbers

Source number Source Description

8 Channel 0 interrupt













D CAN Controller SupportD.6 FlexCAN

D

For more information on interrupt processing on the MCF5282, refer to the MCF5282 ColdFire Microcontroller User’s Manual.





24 Error interrupt

25 Bus-off interrupt

26 Wake-up interrupt

Table D-1 FlexCAN interrupt source numbers

Source number Source Description

Draft: : 26 Apr 04 153

Draft: 26 Apr 04

E
API Equivalents
E.1 Introduction 155

E.2 Common Interfaces 156

E.3 CAN Device and Controller Interfaces 156

E.4 CAN Channel Interfaces 157

E.5 Controller Specific Interfaces 158

E.1 Introduction

This appendix provides equivalent forms of the API functions and device I/O interface.

155


E.2 Common Interfaces

E.3 CAN Device and Controller Interfaces

API Function DevIO Function Equivalent

CAN_Open( ) Part of open( ) for CAN devices. open(deviceName, O_RDWR,0)

Part of open( ) for CAN channels. open(channelName, [O_RDONLY | O_WRONLY | O_RDWR], 0)

CAN_Close( ) Part of close( ) for CAN devices and channels.

close([deviceFd | channelFd])

CAN_Init( ) Part of open( ) for CAN devices.

API Function Device I/O Equivalent

CAN_Start( ) ioctl(deviceFd, WNCAN_HALT, 0)

CAN_Stop( ) ioctl(deviceFd, WNCAN_HALT, 1)

CAN_ Sleep( ) ioctl(deviceFd, WNCAN_SLEEP, 0)

CAN_WakeUp( ) ioctl(deviceFd, WNCAN_WAKEUP, 0)

CAN_TxAbort( ) ioctl(deviceFd, WNCAN_TX_ABORT, 0)

also implicit with close( )

CAN_GetRxChannel( ) ioctl(deviceFd, WNCAN_RXCHAN_GET, &channelNum)

CAN_GetTxChannel( ) ioctl(deviceFd, WNCAN_TXCHAN_GET, &channelNum)

CAN_GetRTRRequesterChannel( ) ioctl(deviceFd, WNCAN_RTRREQCHAN_GET, &channelNum)

CAN_GetRTR_ResponderChannel( ) ioctl(deviceFd, WNCAN_RTRRESPCHAN_GET, &channelNum)

CAN_GetBusStatus( )

CAN_GetBusError( )

ioctl(deviceFd, WNCAN_BUSINFO_GET, &businfo)


E API EquivalentsE.4 CAN Channel Interfaces

E

E.4 CAN Channel Interfaces

CAN_SetBitTiming( )

CAN_SetGlobalRxFilter( )

ioctl(deviceFd, WNCAN_CONFIG_SET, &cfg)

CAN_GetGlobalRxFilter( )CAN_GetControllerType( )

CAN_GetVersion( )

CAN_GetNumChannels( )

CAN_GetXtalFreq( )

CAN_GetBaudRate( )

ioctl(deviceFd, WNCAN_CONFIG_GET, &cfg)



CAN_WriteID( )

CAN_WriteData( )

CAN_SetMode( )

CAN_SetRTR( )

CAN_SetLocalMsgFilter( )

ioctl(channelFd, WNCAN_CHNCONFIG_SET, &cfg)

CAN_ReadID( )

CAN_ReadData( )

CAN_GetMessagesLength( )

CAN_GetMode( )

CAN_IsRTR( )

CAN_GetLocalMsgFilter( )

ioctl(channelFd, WNCAN_CHNCONFIG_GET, &cfg)

or

read(channelFd, &chnmsg, sizeof(chnmsg))

CAN_ EnableChannel( ) ioctl(channelFd, WNCAN_CHN_ENABLE, 1)

Draft: : 26 Apr 04 157


E.5 Controller Specific Interfaces

CAN_DisableChannel( ) ioctl(channelFd, WNCAN_CHN_ENABLE, 0)

CAN_Tx( ) ioctl(channelFd, WNCAN_CHN_TX, 0)

CAN_TxMsg( ) write(channelFd, &chnmsg, sizeof(chnmsg))

CAN_IsMessageLost( ) ioctl(channelFd, WNCAN_CHNMSGLOST_GET, &msgLost)

CAN_ClearMessageLost( ) ioctl(channelFd, WNCAN_CHNMSGLOST_CLEAR, 0)

CAN_FreeChannel( ) close(channelFd)



TouCAN_SetPropseg( ) ioctl(deviceFd, WNCAN_CTRLCONFIG_SET, &cfg)

FlexCAN_SetIntLevel ( ) ioctl(deviceFd, WNCAN_CTRLCONFIG_SET, &cfg)

FlexCAN_GetIntLevel ( ) ioctl(deviceFd, WNCAN_CTRLCONFIG_SET, &cfg)


Index

Symbols#defines, editing 24

Numerics386 137486 137

Aadding

WIND NET CAN components 15ADLINK 7841 9, 137arbitration 3

Bbaud rate 3, 23, 28, 38

setting 38before you begin 9benefits, common CAN interface 3Biscayne HCAN2 138bit timing

settings 38

buildingdebug library 12standard library 10WIND NET CAN libraries 10

building, booting, and testing your VxWorks image 21

CCAN 3CAN board component

setting properties for 17CAN board types, supported 139, 140, 141, 142, 143CAN board/processor configurations

supported 136, 137CAN controller

initializing 37CAN device

closing a session 51displaying installed 37opening and initializing 36starting and stopping 39topology 4

CAN hardwaresupport 135, 147switches, verifying 21

CAN librarymakefile 12

159

WIND NET CAN Programmer’s Guide, 1.4

can_api 94CAN_ClearMessageLost( ) 36, 99CAN_Close( ) 35, 51, 99CAN_DisableChannel( ) 35, 51, 100CAN_DisableInt( ) 35, 39, 51, 100CAN_EnableChannel( ) 35, 101CAN_EnableInt( ) 35, 39, 101CAN_FreeChannel( ) 35, 51, 102CAN_GetBaudRate( ) 36, 102CAN_GetBusError( ) 36, 103CAN_GetBusStatus( ) 36, 104CAN_GetControllerType( ) 36, 105CAN_GetGlobalRxFilter( ) 36, 105CAN_GetIntStatus( ) 35, 106CAN_GetLocalMsgFilter( ) 36, 107CAN_GetMessageLength( ) 36, 108CAN_GetMode( ) 35, 109CAN_GetNumChannels( ) 36, 110CAN_GetRTRRequesterChannel( ) 35, 111CAN_GetRTRResponderChannel( ) 35, 112CAN_GetRxChannel( ) 35, 113CAN_GetTxChannel( ) 35, 114CAN_GetVersion( ) 36, 114CAN_GetXtalFreq( ) 36, 115CAN_Init( ) 35, 37, 116CAN_InstallISRCallback( ) 35, 42, 117CAN_IsMessageLost( ) 36, 118CAN_IsRTR( ) 35, 118CAN_Open( ) 35, 36, 37, 119CAN_ReadData( ) 35, 120CAN_ReadID( ) 35, 121CAN_ReadReg( ) 36, 122CAN_SetBitTiming( ) 35, 38, 123CAN_SetGlobalRxFilter( ) 35, 124CAN_SetIntMask( ) 35, 39, 125CAN_SetLocalMsgFilter( ) 35, 126CAN_SetMode( ) 35, 127CAN_SetRTR( ) 35, 128CAN_Sleep( ) 35, 128CAN_Start( ) 35, 39, 129CAN_Stop( ) 35, 39, 51, 129CAN_Tx( ) 35, 130CAN_TxAbort( ) 35, 51, 130CAN_TxMsg( ) 35, 131CAN_WakeUp( ) 132

CAN_Wakeup( ) 35CAN_WriteData( ) 35, 132CAN_WriteID( ) 35, 133CAN_WriteReg( ) 36, 51, 134CANalyzer 23, 28

Generator Block 29Trace and the Bus Statistics windows 28

channelclosing 72configuring 68reading from 71using 67

with the select facility 72writing to 71

channel deviceopening 67

CiA bit timing recommendations 28closing

CAN device session 51channel 72controller 67

Coldfire 137common CAN interface, benefits 3configuration

CAN board/processor, supported 136, 137configuration data structures 64, 70configuring

channel 68controller 62VxWorks image with WIND NET CAN 15

conformance tests 83preparation 84

controllerclosing 67configuring 62reading and writing 66using 61

with the select facility 67controller area network

See CANcontroller device

opening 61conventions

template, DDK 79creating


Index

Index

VxWorks image, new 14

DDDK 77

conformance testsmanual tests

filter test 86remote request – extended ID 90remote request – standard ID 89remote response test 87

offline test 84online test 85

organization 78porting issues 83porting to a controller 82porting to a new board 81templates 79

conventions 79file preparation 80

terminology 79debug library

building 12using 12

device I/O interface 59device names 60displaying installed CAN devices 37documentation guide 9driver developer kit

See DDK

Eediting #defines 24enabling interrupts 39errnoGet( ) 37error detection 3ESD PC104 200 8, 9, 21

setting board parameters 18ESD PC104-200 139ESD PCI 200 8, 9, 21

setting board parameters 18

ESD PCI/200 140examples

sample reception 74sample transmission 72

extended IDs 23

Ffiber optic cable 3filter test, DDK 86FlexCAN 151

Gglobal filter 23

HHCAN2 149

II/O system interfaces 60I80X86 137initializing

CAN controller 37CAN device 36

installDir 9Intel 82527 148interrupts, enabling 39

Lloop back connector 29

Draft: : 26 Apr 04 161

WIND NET CAN Programmer’s Guide, 1.4

Mmakefile 12mbx860 137MCF5282 FlexCAN 9, 21, 144

setting board parameters 19message priority 3MicroSpace PC104 CAN 8, 9, 21MSMCAN PC104 141

setting board parameters 18

Oobtaining

configurable VxWorks image 13offline conformance test, DDK 84online conformance test, DDK 85opening

CAN device 36channel device 67controller device 61VxWorks image, existing 13

overview 1

PPC5xx TouCAN 142Pentium 137Phillips SJA 1000 148porting

to a controller, DDK 82to a new board, DDK 81

porting issues, DDK 83PPC 137PPC5xx TouCAN 8, 9, 21

setting board parameters 19preparation

conformance tests 84template files, DDK 80

propertiesCAN board component 17

Rreading and writing a controller 66reading from a channel 71remote response test, DDK 87Robert Bosch Gmbh 3routines, sample application 23

Ssample application 23

#defines 24project 24routines 23

sample point 23, 28, 38sample reception example 74sample transmission example 72select facility

using with a channel 72using with a controller 67

settingbit timings and baud rate 38board parameters

ESD PC104 200 18ESD PCI 200 18MCF5282 FlexCAN 19MSMCAN PC104 18PPC5xx TouCAN 19

properties, for a CAN board component 17SH 137SH7750 137standard library

building 10location 10

starting and stopping a CAN device 39support, CAN hardware 135, 147supported

CAN board types 139, 140, 141, 142, 143CAN board/processor configurations 136, 137


Index

Index

TTahoe-Amanda HCAN2 143target server 22templates, DDK 79terminology, DDK 79text variables 9topology, CAN device 4Tornado IDE 9Tornado User’s Guide 9tornado_dev 9Tornado22 10TouCAN 149toucan 95TouCAN_SetPropseg( ) 34, 38, 134tutorial 7

Uunshielded twisted pair cable 3using a channel 67using a controller 61using, debug library 12

Vverifying your CAN hardware switches 21VxWorks image

building, booting and testing 21configuring with WIND NET CAN 15creating, new 14obtaining, configurable 13opening, existing 13

WWIND NET CAN

API 3, 34components, adding 15libraries, building 10

programming 33WIND NET CAN library 10WindSh 22WNCAN_BUSINFO 64WNCAN_CHNCONFIG 70WNCAN_CHNMSG 71WNCAN_CONFIG 64WNCAN_CTRLCONFIG 66WNCAN_Device 36WNCAN_ESD PCI 200 136WNCAN_ESD_PC104_200 136WNCAN_ESD_PCI_200 24WNCAN_MSMCAN 24WNCAN_PPC5XX 24, 136WNCAN_Show( ) 37writing to a channel 71

Yyour_CAN_board_type 9your_VxWorks_project_folder 9your_VxWorks_project_name 9your_workspace_name 9

Draft: : 26 Apr 04 163

wind net can - pudn.comread.pudn.com/downloads153/doc/comm/671972/windnet_can_progra… · 2.11.2...

Documents