Tews Technologies TIP810-SW-42 User manual

The Embedded I/O Company
TIP810-SW-42
VxWorks Device Driver
CAN Bus IP
Version 2.0.x
User Manual
Issue 2.0.0
November 2008
TEWS TECHNOLOGIES GmbH TEWS TECHNOLOGIES LLC
Am Bahnhof 7
25469 Halstenbek, Germany
www.tews.com
Phone: [phone]
Fax: [phone]
e-mail: [e-mail]
9190 Double Diamond Parkway,
Suite 127, Reno, NV 89521, USA
www.tews.com
Phone: [phone]
Fax: [phone]
e-mail: usa[email protected]m

TIP810-SW-42 - VxWorks Device Driver Page 2 of 36
TIP810-SW-42
VxWorks Device Driver
CAN Bus IP
This document contains information, which is
proprietary to TEWS TECHNOLOGIES GmbH. Any
reproduction without written permission is forbidden.
TEWS TECHNOLOGIES GmbH has made any
effort to ensure that this manual is accurate and
complete. However TEWS TECHNOLOGIES GmbH
reserves the right to change the product described
in this document at any time without notice.
TEWS TECHNOLOGIES GmbH is not liable for any
damage arising out of the application or use of the
device described herein.
2004-2008 by TEWS TECHNOLOGIES GmbH
Issue Description Date
1.0 First Issue January 1995
1.1 General Revision September 2003
1.2 Added support for PeliCAN mode July 2004
2.0.0 TEWS Carrier Support added, new address TEWS LLC November 20, 2008

TIP810-SW-42 - VxWorks Device Driver Page 3 of 36
Table of Contents
1 INTRODUCTION.........................................................................................................4
1.1 Device Driver ...................................................................................................................................4
1.2 IPAC Carrier Driver .........................................................................................................................5
2 INSTALLATION..........................................................................................................6
2.1 Include device driver in VxWorks project ....................................................................................6
2.2 Special installation for Intel x86 based targets............................................................................6
3 I/O SYSTEM FUNCTIONS..........................................................................................7
3.1 t810Drv()...........................................................................................................................................7
3.2 t810DevCreate()...............................................................................................................................9
4 I/O INTERFACE FUNCTIONS..................................................................................13
4.1 open() .............................................................................................................................................13
4.2 read() ..............................................................................................................................................15
4.3 write() .............................................................................................................................................18
4.4 ioctl() ..............................................................................................................................................21
4.4.1 FIO_T810_SET_BUSTIMING ............................................................................................23
4.4.2 FIO_T810_SET_FILTER....................................................................................................25
4.4.3 FIO_T810_SET_BUSON....................................................................................................27
4.4.4 FIO_T810_SET_BUSOFF..................................................................................................28
4.4.5 FIO_T810_GET_CANSTATUS..........................................................................................29
4.4.6 FIO_T810_ENABLE_SELFTEST.......................................................................................31
4.4.7 FIO_T810_DISABLE_SELFTEST......................................................................................32
4.4.8 FIO_T810_ENABLE_LISTENONLY...................................................................................33
4.4.9 FIO_T810_DISABLE_ LISTENONLY.................................................................................34
4.4.10 FIO_T810_SET_LIMIT .....................................................................................................35
5 APPENDIX................................................................................................................36
5.1 Predefined Symbols......................................................................................................................36
5.2 Status and Error Codes................................................................................................................36

TIP810-SW-42 - VxWorks Device Driver Page 4 of 36
1 Introduction
1.1 Device Driver
The TIP810-SW-42 VxWorks device driver allows the operation of the TIP810 CAN Bus IP conforming
to the VxWorks I/O system specification. This includes a device-independent interface with open,
read,write and ioctl functions.
After installation of the device driver in the I/O system messages can be transmitted to and received
from the CAN bus by calling the write() or read() functions.
Special I/O operation that does not fit to the standard I/O calls will be performed by calling the ioctl()
function with a specific function code and an optional function-dependent argument.
This driver invokes a mutual exclusion and queuing mechanism to prevent simultaneous requests by
multiple users from interfering with each other.
The TIP810-SW-42 device driver supports the following features:
Transmission and receive of Standard and Extended CAN Frames
Standard bit rates from 20 kbit up to 1.0 Mbit and user defined bit rates
Message acceptance filtering
Single-Shot transmission
Listen only mode
Message self reception
Programmable error warning limit
The TIP816-SW-42 supports the modules listed below:
TIP810-10 CAN Bus Industry Pack®
This device driver has only been tested with TIP810 V2.0+ hardware, and does not guarantees
support for V1.0 modules.
To get more information about the features and use of TIP810 devices it is recommended to read the
manuals listed below.
TIP810 User manual
TIP810 Engineering Manual
CARRIER-SW-42 IPAC Carrier User Manual
SJA1000 PeliCAN controller User Manual

TIP810-SW-42 - VxWorks Device Driver Page 5 of 36
1.2 IPAC Carrier Driver
IndustryPack (IPAC) carrier boards have different implementations of the system to IndustryPack bus
bridge logic, different implementations of interrupt and error handling and so on. Also the different byte
ordering (big-endian versus little-endian) of CPU boards will cause problems on accessing the
IndustryPack I/O and memory spaces.
To simplify the implementation of IPAC device drivers which work with any supported carrier board,
TEWS TECHNOLOGIES has designed a so called Carrier Driver that hides all differences of different
carrier boards under a well defined interface.
The TEWS TECHNOLOGIES IPAC Carrier Driver CARRIER-SW-42 is part of this TIP810-SW-42
distribution. It is located in directory CARRIER-SW-42 on the corresponding distribution media.
This IPAC Device Driver requires a properly installed IPAC Carrier Driver. Due to the design of the
Carrier Driver, it is sufficient to install the IPAC Carrier Driver once, even if multiple IPAC Device
Drivers are used.
Please refer to the CARRIER-SW-42 User Manual for a detailed description how to install and setup
the CARRIER-SW-42 device driver, and for a description of the TEWS TECHNOLOGIES IPAC Carrier
Driver concept.
How to use the carrier driver in the application program is shown in the programming example
tip810exa.c.
If the IPAC carrier driver isn’t used for the IPAC carrier setup, the application software has to setup
carrier board hardware, mapping of device memory and interrupt level setup by itself.

TIP810-SW-42 - VxWorks Device Driver Page 6 of 36
2Installation
Following files are located on the distribution media:
Directory path ‘TIP810-SW-42’:
tip810drv.c TIP810 Driver source
tip810.h TIP810 Driver include file for driver and application
tip810def.h TIP810 Driver private include file
tip810exa.c TIP810 Driver usage example program
sja1000.h Header file for the SJA1000 CAN Controller (TIP810 V2.0+)
pca82c200.h Header file for the PCA82C200 CAN Controller (TIP810 V1.0)
include/ipac_carrier.h Carrier driver interface definitions
TIP810-SW-42-2.0.0.pdf PDF copy of this manual
Release.txt Release information
ChangeLog.txt Release history
2.1 Include device driver in VxWorks project
For including the TIP810-SW-42 device driver into a VxWorks project (e.g. Tornado IDE or
Workbench) follow the steps below:
Copy the files from the distribution media into a subdirectory in your project path.
(For example: ./TIP810)
Add the device drivers C-files to your project.
Now the driver is included in the project and will be built with the project.
For a more detailed description of the project facility please refer to your VxWorks User’s
Guide (e.g. Tornado, Workbench, etc.)
2.2 Special installation for Intel x86 based targets
The TIP810 device driver is fully adapted for Intel x86 based targets. This is done by conditional
compilation directives inside the source code and controlled by the VxWorks global defined macro
CPU_FAMILY. If the content of this macro is equal to I80X86 special Intel x86 conforming code and
function calls will be included.

TIP810-SW-42 - VxWorks Device Driver Page 7 of 36
3I/O system functions
This chapter describes the driver-level interface to the I/O system. The purpose of these functions is to
install the driver in the I/O system, add and initialize devices.
3.1 t810Drv()
NAME
t810Drv() - installs the TIP810 driver in the I/O system
SYNOPSIS
#include “tip810.h”
STATUS tip810Drv(void)
DESCRIPTION
This function installs the TIP810 driver in the I/O system.
A call to this function is the first thing the user has to do before adding any device to the
system or performing any I/O request.
EXAMPLE
#include "tip810.h”
STATUS result;
/*-------------------
Initialize Driver
-------------------*/
result = tip810Drv();
if (result == ERROR)
{
/* Error handling */
}

TIP810-SW-42 - VxWorks Device Driver Page 8 of 36
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
ERROR CODES
Error codes are only set by system functions. The error codes are stored in errno and can be read with
the function errnoGet().
SEE ALSO
VxWorks Programmer’s Guide: I/O System

TIP810-SW-42 - VxWorks Device Driver Page 9 of 36
3.2 t810DevCreate()
NAME
t810DevCreate() - add a TIP810 device to the system and initialize device hardware
SYNOPSIS
#include “tip810.h”
STATUS t810DevCreate
(char *name,
int devIdx,
int funcType,
void *pParam
)
DESCRIPTION
This routine adds the selected device to the VxWorks system. The device hardware will be setup and
prepared for use.
This function must be called before performing any I/O request to this device.
PARAMETER
name This string specifies the name of the device that will be used to identify the device, for example
for open() calls.
devIdxThis index number specifies the device to add to the system.
The device number of one TIP810-10 will be assigned as n.
Example: A system with 2 TIP810-10 will assign the following device indices:
Module Device Index
1st TIP810-10 0
2nd TIP810-10 1
funcType
This parameter is unused and should be set to 0.

TIP810-SW-42 - VxWorks Device Driver Page 10 of 36
pParam
This parameter points to a structure (TIP810_DEVCONFIG) containing the default configuration
of the channel.
The structure (TIP810_DEVCONFIG) has the following layout and is defined in tip810.h:
typedef struct
{struct ipac_resource *ipac;
int nMsg;
T810_FILTER filter;
T810_TIMING timing;
} TIP810_DEVCONFIG;
ipac Pointer to TIP810 module resource descriptor, retrieved by CARRIER Driver
ipFindDevice() function
nMsg This argument defines the size of the device read FIFO for buffering incoming messages
which passes the acceptance filter.
filter The argument filter sets the acceptance filter code and mask register(s). For more details
see FIO_T810_SET_FILTER ioctl function.
timing The argument timing selects the transfer rate of the CAN bus. For more details see
FIO_T810_SET_BUSTIMING ioctl function.

TIP810-SW-42 - VxWorks Device Driver Page 11 of 36
EXAMPLE
#include “ipac_carrier.h”
#include “tip810.h”
STATUS result;
TIP810_DEVCONFIG tip816Conf;
struct ipac_resource ipac;
/* IPAC CARRIER Driver initialization */
/*
** Find an IP module with manufacturer id MANUFACTOR_TEWS (0xB3)
** and model number MODEL_TIP810 (see tip810.h). This module uses
** interrupts on INT0 and we need need the 16bit memory space. The
** module need an IACK cycle for interrupt handling.
*/
result = ipFindDevice(MANUFACTOR_TEWS, MODEL_TIP810, 0,
IPAC_INT0_EN | IPAC_LEVEL_SENS | IPAC_CLK_8MHZ |
IPAC_MEM_16BIT | IPAC_IACK_CYC,
&ipac);
if (result == OK)
{
/*-------------------------------------------------------
Create the device "/t810A" for the first CAN device
..* Device specific parameters must be set up:
o reserve a read buffer for 1000 messages
o transfer rate = 100kbit/s, one sample per bit
o only messages with identifiers 128…135 passes the acceptance filter
-------------------------------------------------------*/
tip810Conf.ipac = &ipac;
tip810Conf.filter.acceptance_code = 128 << 3;
tip810Conf.filter.acceptance_mask = (8 << 3) – 1;
tip810Conf.filter.single_filter = 1;
tip810Conf.timing.timing_value = T810_100KBIT;
tip810Conf.timing.three_samples = 0;
result = tip816DevCreate( "/t810A",
0,
0,
(void*)&tip810Conf);
if (result == OK)
{
/* Device successfully created */
}

TIP810-SW-42 - VxWorks Device Driver Page 12 of 36
else
{
/* Error occurred when creating the device */
}
}
RETURNS
OK, or ERROR if no device was found or an error occurred during device initialization.
ERROR CODES
The error codes are stored in errno and can be read with the function errnoGet().
Error code Description
S_ioLib_NO_DRIVER The TIP810 driver has not been started
EINVAL Input parameters are invalid
EISCONN The device has been created already
SEE ALSO
VxWorks Programmer’s Guide: I/O System

TIP810-SW-42 - VxWorks Device Driver Page 13 of 36
4I/O interface functions
This chapter describes the interface to the basic I/O system used for communication over the CAN
bus.
4.1 open()
NAME
open() - open a device or file.
SYNOPSIS
int open
(const char *name,
int flags,
int mode
)
DESCRIPTION
Before I/O can be performed to the TIP810 device, a file descriptor must be opened by invoking the
basic I/O function open().
PARAMETER
name Specifies the device which shall be opened, the name specified in t810DevCreate() must be
used
flags Not used
mode Not used

TIP810-SW-42 - VxWorks Device Driver Page 14 of 36
EXAMPLE
int fd;
/*------------------------------------------
Open the device named "/t810A" for I/O
------------------------------------------*/
fd = open("/t810A", 0, 0);
if (fd == ERROR)
{
/* error handling */
}
RETURNS
A device descriptor number or ERROR. If the function fails an error code will be stored in errno.
ERROR CODES
The error code can be read with the function errnoGet().
The error code is a standard error code set by the I/O system (see VxWorks Reference Manual).
SEE ALSO
ioLib, basic I/O routine - open()

TIP810-SW-42 - VxWorks Device Driver Page 15 of 36
4.2 read()
NAME
read() - read a message from specified TIP810 device
SYNOPSIS
int read (
int fd, /* device descriptor from opened TIP810 device */
char *buffer, /* pointer to a message buffer (typecast T810_MSG_BUF) */
size_t maxbytes /* always sizeof(T810_MSG_BUF) */
)
DESCRIPTION
The read function reads a CAN message from the driver receive queue. A pointer to the callers
message buffer (T810_MSG_BUF) and the size of this structure are passed by the parameters buffer
and maxbytes to the device driver.
The T810_MSG_BUF structure has the following layout:
typedef struct
{unsigned long identifier;
unsigned char io_flags;
unsigned char msg_len;
unsigned char data[8];
unsigned char status;
int timeout;
} T810_MSG_BUF, *PT810_MSG_BUF;
identifier
Receives the message identifier of the read CAN message.
io_flags
Receives CAN message attributes as a set of bit flags. The following attribute flags are
possible:
Value Description
T810_EXTENDED Set if the received message is an extended
message frame. Reset for standard message
frames.
T810_REMOTE_FRAME Set if the received message is a remote
transmission request (RTR) frame.

TIP810-SW-42 - VxWorks Device Driver Page 16 of 36
msg_len
Receives the number of message data bytes (0...8).
data This buffer receives up to 8 data bytes. Data[0] receives message Data 0, Data[1] receives
message Data 1 and so on.
timeout
Specifies the amount of time (in ticks) the caller is willing to wait for execution of read. A timeout
value of WAIT_FOREVER means wait indefinitely; a value of NO_WAIT means do not wait at
all.
statusThis parameter receives status information about overrun conditions either in the CAN controller
or intermediate software FIFO.
Value Description
T810_SUCCESS No messages lost
T810_FIFO_OVERRUN One or more messages was overwritten in the
receive queue FIFO. This problem occurs if the
FIFO is too small for the application read interval.
T810_MSGOBJ_OVERRUN One or more messages were overwritten in the
CAN controller message object because the
interrupt latency is too large. Reduce the CAN bit
rate or upgrade the system speed.
EXAMPLE
#include “tip810.h”
int fd;
int num_bytes;
T810_MSG_BUF msg_buf;
msg_buf.timeout = 200; /* wait max. 200 ticks */
num_bytes = read(fd, &msg_buf, sizeof(msg_buf));
if (num_bytes != ERROR)
{
/* process received CAN message */
}

TIP810-SW-42 - VxWorks Device Driver Page 17 of 36
RETURNS
ERROR or number of data bytes read [0..8]. In the case of ERROR see tip810.h for device specific
error codes.
SEE ALSO
ioLib, basic I/O routine - read()

TIP810-SW-42 - VxWorks Device Driver Page 18 of 36
4.3 write()
NAME
write() - write a message to specified TIP810 device
SYNOPSIS
int write (
int fd, /* device descriptor from opened TIP810 device */
char *buffer, /* pointer to message buffer (typecast T810_MSG_BUF*) */
size_t nbytes /* always sizeof(T810_MSG_BUF) */
)
DESCRIPTION
The write function writes a CAN message to the device with descriptor filedes. A pointer to the callers
message buffer (T810_MSG_BUF) and the size of this structure are passed by the parameters buffer
and size to the device.
The T810_MSG_BUF structure has the following layout:
typedef struct
{unsigned long identifier;
unsigned char io_flags;
unsigned char msg_len;
unsigned char data[8];
unsigned char status;
int timeout;
} T810_MSG_BUF, *PT810_MSG_BUF;
identifier
Contains the message identifier of the CAN message to write.
io_flags
Contains a set of bit flags, which define message attributes and controls the write operation. To
set more that one bit flag the predefined macros must be binary ORed.
Value Description
T810_EXTENDED Transmit an extended message frame. If this macro
isn't set or the "dummy" macro T810_STANDARD
is set a standard frame will be transmitted.
T810_REMOTE_FRAME A remote transmission request (RTR bit is set) will
be transmitted.

TIP810-SW-42 - VxWorks Device Driver Page 19 of 36
T810_SINGLE_SHOT No re-transmission will be performed if an error
occurred or the arbitration will be lost during
transmission (single-shot transmission).
T810_SELF_RECEPTION The message will be transmitted and
simultaneously received if the acceptance filter is
set to the corresponding identifier.
msg_len
Contains the number of message data bytes (0..8).
data This buffer contains up to 8 data bytes. Data[0] contains message Data 0, Data[1] contains
message Data 1 and so on.
timeout
Specifies the amount of time (in ticks) the caller is willing to wait for execution of write. A timeout
value of WAIT_FOREVER means wait indefinitely; a value of NO_WAIT means do not wait at
all.
statusThis parameter is unused for this control function.
EXAMPLE
#include “tip810.h”
int result;
T810_MSG_BUF msg_buf;
/* Write Extended Frame, ID = 1234, Data = {0xaa, 0x55}, Timeout = 200 ticks
** The transmitted frame will be received simultaneously.*/
msg_buf.identifier = 1234;
msg_buf.timeout = 200;
msg_buf.io_flags = T810_EXTENDED | T810_SELF_RECEPTION;
msg_buf.msg_len = 2;
msg_buf.data[0] = 0xaa;
msg_buf.data[1] = 0x55;
result = write(fd, &msg_buf, sizeof(msg_buf));
if (result == ERROR) {
printf( "\nWrite failed --> Error = 0x%08X.\n", errnoGet());
}

TIP810-SW-42 - VxWorks Device Driver Page 20 of 36
RETURNS
ERROR or number of data bytes written [0..8]. In the case of ERROR see tip810.h for device specific
error codes retrieved by errnoGet().
SEE ALSO
ioLib, basic I/O routine - write()