Tews Technologies TPMC821-SW-42 User manual

The Embedded I/O Company
TPMC821-SW-42
VxWorks Device Driver
INTERBUS Master G4 PMC
Version 1.4
User Manual
Issue 1.2
January 2004
TEWS TECHNOLOGIES GmbH
Am Bahnhof 7 25469 Halstenbek / Germany
Phone: [phone] Fax: [phone]
e-mail: [email protected] www.tews.com
TEWS TECHNOLOGIES LLC
1 E. Liberty Street, Sixth Floor Reno, Nevada 89504 / USA
Phone: [phone] Fax: [phone]
e-mail: [email protected] www.tews.com

TPMC821-SW-42 - VxWorks Device Driver Page 2 of 37
TPMC821-SW-42
INTERBUS Master G4 PMC
VxWorks Device Driver
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.
2000-2004 by TEWS TECHNOLOGIES GmbH
Issue Description Date
1.0 First Issue January 2000
1.1 Support for Intel x86 based targets June 2000
1.2 General Revision January 2004

TPMC821-SW-42 - VxWorks Device Driver Page 3 of 37
Table of Content
1INTRODUCTION.........................................................................................................4
2INSTALLATION..........................................................................................................5
2.1 Install the driver to VxWorks system............................................................................................5
2.2 Including the driver in VxWorks....................................................................................................5
2.3 Hardware and system dependencies............................................................................................5
2.4 Special installation for Intel x86 based targets............................................................................7
3I/O SYSTEM FUNCTIONS..........................................................................................8
3.1 tp821Drv() ........................................................................................................................................8
3.2 tp821DevCreate().............................................................................................................................9
4I/O INTERFACE FUNCTIONS..................................................................................11
4.1 open() .............................................................................................................................................11
4.2 read() ..............................................................................................................................................13
4.3 write() .............................................................................................................................................18
4.4 ioctl() ..............................................................................................................................................22
4.4.1 FIO_TP821_BIT_CMD ..................................................................................................23
4.4.2 FIO_TP821_MBX_WAIT ...............................................................................................25
4.4.3 FIO_TP821_MBX_NOWAIT..........................................................................................27
4.4.4 FIO_TP821_GET_DIAG................................................................................................29
4.4.5 FIO_TP821_CONFIGURE.............................................................................................31
4.4.6 FIO_TP821_SET_HOST_FAIL......................................................................................33
4.4.7 FIO_TP821_REMOVE_HOST_FAIL.............................................................................34
4.4.8 FIO_TP821_CLEAR_HWERROR.................................................................................35
5APPENDIX................................................................................................................36
5.1 Predefined Symbols......................................................................................................................36
5.2 Additional Error Codes.................................................................................................................37

TPMC821-SW-42 - VxWorks Device Driver Page 4 of 37
1 Introduction
The TPMC821-SW-42 VxWorks device driver allows the operation of the TPMC821 PMC conforming
to the VxWorks system specification. This includes a device-independent basic I/O interface with
open(), read(), write() and ioctl() functions.
Special I/O operation that do 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 binary semaphore mechanism to prevent simultaneous
requests by multiple tasks from interfering with each other.
To prevent the application program for losing data, incoming messages will be stored in a message
FIFO with a depth of 100 messages.
This device driver supports the following features:
•use all possible bus operation modes
oasynchronous mode without consistency locking
oasynchronous mode with consistency locking
obus synchronous mode
oprogram synchronous mode
•use bit commands
•use mailbox commands
•read data
•write data
•control the host interrupt request
•reset hardware error

TPMC821-SW-42 - VxWorks Device Driver Page 5 of 37
2Installation
The software is delivered on a 3½" HD diskette.
Following files are located on the diskette:
tp821drv.c TPMC821 Device Driver Source
tpmc821.h TPMC821 Include File for driver and application
tp821def.h TPMC821 Driver Include File
tp821exa.c TPMC821 Example Application
tpmctime.h Include file with delay macro
tpmc_pci.c PCI dependent functions
tpmc_pci.h PCI dependent include
tp821_pci.c TPMC821 PCI MMU mapping for Intel x86 based targets
tpxxxhwdep.c Collection of hardware dependent functions
tpxxxhwdep.h Include for hardware dependent functions
For installation the files have to be copied to the desired target directory.
2.1 Install the driver to VxWorks system
To install the TPMC821 device driver to the VxWorks system following steps have to be done:
•Build the object code of the TPMC821 device driver
•Link or load the driver object file to the VxWorks system
•Call the tp821Drv() function to install the driver.
2.2 Including the driver in VxWorks
How to include the device drive in the VxWorks system is described in the VxWorks and Tornado
manuals.
2.3 Hardware and system dependencies
The TPMC821 can be mounted to different hardware. This will sometimes need some hardware
dependant adaptation.
PCI Initialization
The hardware must be configured before starting the driver. The following points must be guaranteed:
•The PCI spaces of the TPMC821 (PLX9050) must be set up to unused PCI areas. Memory and I/O
accesses must be enabled in the PCI configuration space (see example below).
•The PCI interrupts must be set up (Interrupt routing and handler).

TPMC821-SW-42 - VxWorks Device Driver Page 6 of 37
BSP dependencies
The tpmc_pci.c file has to be adapted, because there are some hardware and system dependent
values (only PowerPC targets). Please check the following values:
•PCI_MEM_BRIDGE_OFFSET This must be set to the offset, which is added by the PCI bridge
(refer to BSP) when accessing PCI memory.
•PCI_IO_BRIDGE_OFFSET This must be set to the offset, which is added by the PCI bridge
(refer to BSP) when accessing PCI I/O spaces.
•int_dev_no (array) This array defines the interrupt vectors/levels for #INTA of the
different device position (first index = bus number, second index
= device number). These values or the size of the table have to
be adapted (if using busses with higher bus numbers). The
interrupt vectors/levels depend on BSP.
Time factor
A counter constant is the last thing, which has to be configured. This constant is used for a delay,
which is needed by the INTERBUS G4 controller in synchronous mode. The constant and a wait
macro (waiting 5µs) are placed in the file tpmctime.h. There is a little function tp821_TestTime() in the
example code, which will help to find the right constant. This value should always be calibrated when
using a synchronous operation mode. It is not necessary for asynchronous operation modes.
The device driver uses this delay during the interrupt function. This may delay other tasks and
interrupts (the times will be < 100µs).

TPMC821-SW-42 - VxWorks Device Driver Page 7 of 37
2.4 Special installation for Intel x86 based targets
The TPMC821 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. If the contents of this macro are equal to I80386, I80386 or PENTIUM special Intel x86
conforming code and function calls will be included.
The second problem for Intel x86 based platforms can’t be solved by conditional compilation
directives. Due to the fact that some Intel x86 BSP’s doesn’t map PCI memory spaces of devices
which are not used by the BSP, the required CAN controller device registers can’t be accessed.
To solve this problem a MMU mapping entry has to be added for the required TPMC821 PCI memory
spaces prior the MMU initialization (usrMmuInit()) is done.
Please examine the BSP documentation or contact the BSP Vendor whether the BSP perform
automatic PCI and MMU configuration or not. If the PCI and MMU initialization is done by the BSP the
function tp821PciInit() won’t be included and the user can skip to the following steps.
The C source file tp821pci.c contains the function tp821PciInit(). This routine finds out all TPMC821
devices and adds MMU mapping entries for all used PCI memory spaces. Please insert a call to this
function after the PCI initialization is done and prior to MMU initialization (usrMmuInit()).
If the Tornado 2.0 project facility is used, the right place to call the function tp821PciInit() is at the end
of the function sysHwInit() in sysLib.c (can be opened from the project Files window).
If Tornado 1.0.1 compatibility tools are used insert the call to tp821PciInit() at the beginning of the root
task (usrRoot()) in usrConfig.c.
Be sure that the function is called prior to MMU initialization otherwise the TPCM821 PCI spaces
remains unmapped and an access fault occurs during driver initialization.
Please insert the following call at a suitable place in either sysLib.c or usrConfig.c:
tp821PciInit();
To link the driver object modules to VxWorks, simply add all necessary driver files to the project. If
Tornado 1.0.1 Standard BSP Builds... is used add the object modules to the macro MACH_EXTRA
inside the BSP Makefile (MACH_EXTRA = tp821drv.o tp821pci.o ...).
The function tp821PciInit() was designed for and tested on generic Pentium targets. If another
BSP is used, please refer to BSP documentation or contact the technical support for required
adaptation.
If strange errors appeared after system startup with the new build system please carrying out a
VxWorks build clean and build all.

TPMC821-SW-42 - VxWorks Device Driver Page 8 of 37
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 tp821Drv()
NAME
tp821Drv() - installs the TPMC821 driver in the I/O system.
SYNOPSIS
void tp821Drv(void)
DESCRIPTION
This function installs the TPMC821 driver in the I/O system.
The call of this function is the first thing the user has to do before adding any device to the system or
performing any I/O request.
RETURNS
OK or ERROR (if the driver cannot be installed)
INCLUDE FILES
tpmc821.h

TPMC821-SW-42 - VxWorks Device Driver Page 9 of 37
3.2 tp821DevCreate()
NAME
tp821DevCreate() - adds TPMC821 device to the system and initializes device hardware.
SYNOPSIS
STATUS tp821DevCreate
(
char *name, /* name of the device to create */
int busNo, /* bus number where the module is moutned */
int deviceNo, /* device number where the module is mounted */
int functionNo /* function number, must be always ‘0’ */
)
DESCRIPTION
This routine is called to add a device to the system that will be serviced by the TPMC821 driver. This
function must be called before performing any I/O request to this driver.
There are several device dependent arguments required for the device initialization and allocation of
the system resources.
PARAMETER
The argument name specifies the name, which will select the device in future calls.
The arguments busNo and deviceNo specify the position of the TPMC821. These values are system
dependent (refer to the carrier manual).
The argument functionNo must be left ‘0’. This value selects the module function. The TPMC821
supports only one function.
EXAMPLE
#include "tpmc821.h"
...
int status;
/*-----------------------------------------------------------
Create a device "/tp821A"
to select TPMC821 is mounted to bus 0 and device 16
-----------------------------------------------------------*/
status = tp821DevCreate("/tp821A", 0, 16, 0);
...

TPMC821-SW-42 - VxWorks Device Driver Page 10 of 37
RETURNS
OK or ERROR
INCLUDE FILES
tpmc821.h

TPMC821-SW-42 - VxWorks Device Driver Page 11 of 37
4I/O interface functions
This chapter describes the interface to the basic I/O system used for communication over the
INTERBUS.
4.1 open()
NAME
open() - opens a device or file.
SYNOPSIS
int open
(
const char *name, /* name of the device to open */
int flags, /* not used for TPMC821 driver, must be ‘0’ */
int mode /* not used for TPMC821 driver, must be ‘0’ */
)
DESCRIPTION
Before I/O can be performed to the TPMC821 device, a file descriptor must be opened by invoking the
basic I/O function open().
PARAMETER
The parameter name selects the device which shall be opened.
The parameters flags and mode are not used and must be 0.
EXAMPLE
...
/*-----------------------------------------------------------
Open the device named "/tpmc821A" for I/O
-----------------------------------------------------------*/
fd = open("/tpmc821A", 0, 0);
...
RETURNS
A device descriptor number or ERROR (if the device does not exist or no device descriptors are
available)

TPMC821-SW-42 - VxWorks Device Driver Page 12 of 37
INCLUDE FILES
vxworks.h
tpmc821.h
SEE ALSO
ioLib, basic I/O routine - open()

TPMC821-SW-42 - VxWorks Device Driver Page 13 of 37
4.2 read()
NAME
read() – reads data from the specified TPMC821 device.
SYNOPSIS
int read
(
int fd, /* device descriptor from opened TPMC821 device */
char *buffer, /* pointer to the data buffer */
size_t maxbytes /* not used */
)
PARAMETER
The parameter fd is a file descriptor specifying the device which shall be used.
The argument buffer points to a driver-specific I/O parameter block. This buffer is segmented into
parts with the data structure of the type TP821_RW_SEGMENT (see below).
The parameter maxbytes is not used by the TPMC821 Device Driver.
data structure TP821_RW_SEGMENT
typedef struct
{
unsigned short itemNumber; /* number of items (bytes, w..) */
unsigned short itemType; /* TP821_BYTE|TP821_WORD|.. */
unsigned short dataOffset; /* Byte Off. in DATA IN/OUT reg */
union
{
unsigned char byte[1];
unsigned short word[1];
unsigned long lword[1];
} u;
} TP821_RW_SEGMENT;
The argument itemNumber specifies how many elements of the specified type will follow.
The itemType specifies the length of the data element. Allowed values are:
TP821_END Specifies the last segment of a segment list for data
commands, no data follows.
TP821_BYTE Specifies a segment with byte data. The union part byte will
be used (Datalength = itemNumber * 1 byte).
TP821_WORD Specifies a segment with word data. The union part word will
be used (Datalength = itemNumber * 2 byte).
TP821_LWORD Specifies a segment with longword data. The union part
lword will be used (Datalength = itemNumber * 4 byte).

TPMC821-SW-42 - VxWorks Device Driver Page 14 of 37
The argument dataOffset specifies the offset in the data area of the TPMC821. The specified data will
be read from the data in base address + dataOffset (in byte).
The union umarks the first element of the data area of the segment. The area size is not specified by
this array. It is specified with the itemNumber argument.
The data structure TP821_RW_SEGMENT will be put over the data buffer.
There are two MACROS defined in tpmc821.h, which will help setting up the data buffer.
The 1st function SEGMENT_SIZE(pSeg) calculates the length of the data segment. The data segment
must be specified with the segment pointer in pSeg.
The 2nd function NEXT_SEGMENT(pSeg) calculates the start of the next segment. The actual data
segment must be specified with the segment pointer in pSeg. The new data pointer will be the return
value (see example below).
Example
The transmitted data shall be split into two segments and an end segment. The 1st segment shall have
a size of 8 bytes, the 2nd segment shall have a size of 2 longwords. The contents of the 1st segment
shall be read from data offset 8 and the 2nd segment shall be read from position 0. The data buffer
segmentation will have the following layout.
Segment values (before calling the read function):
1st segment:
itemNumber: 8
itemType: TP821_BYTE
itemOffset: 0x008
data: (8 byte)
2nd segment:
itemNumber: 2
itemType: TP821_LWORD
itemOffset: 0x000
data: (2 longwords)
End segment:
itemNumber: 0
itemType: TP821_END
itemOffset: 0x000
data: (none)

TPMC821-SW-42 - VxWorks Device Driver Page 15 of 37
The data buffer has the following layout (before calling the read function):
Offset +0 +1 +2 +3 +4 +5 +6 +7
+0x00 0x00 0x08 0x00 0x01 0x00 0x08 xx xx
+0x08 xx xx xx xx xx xx 0x00 0x02
+0x10 0x00 0x04 0x00 0x00 xx xx xx xx
+0x18 xx xx xx xx 0x00 0x00 0x00 0x00
+0x20 0x00 0x00 xx xx xx xx xx xx
The data input area of the TPMC821:
Offset +0 +1 +2 +3 +4 +5 +6 +7
+0x00 0x12 0x34 0x56 0x78 0x9A 0xBC 0xDE 0xF0
+0x08 0x00 0x11 0x22 0x33 0x44 0x55 0x66 0x77
The data buffer has the following layout (after calling the read function):
Offset +0 +1 +2 +3 +4 +5 +6 +7
+0x00 0x00 0x08 0x00 0x01 0x00 0x08 0x00 0x11
+0x08 0x22 0x33 0x44 0x55 0x66 0x77 0x00 0x02
+0x10 0x00 0x04 0x00 0x00 0x12 0x34 0x56 0x78
+0x18 0x9A 0xBC 0xDE 0xF0 0x00 0x00 0x00 0x00
+0x20 0x00 0x00 xx xx xx xx xx xx
Segment values (after calling the read function):
1st segment:
itemNumber: 8
itemType: TP821_BYTE
itemOffset: 0x008
data: 0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77
2nd segment:
itemNumber: 2
itemType: TP821_LWORD
itemOffset: 0x000
data: 0x12345678, 0x9ABCDEF0
End segment:
itemNumber: 0
itemType: TP821_END
itemOffset: 0x000
data: (none)

TPMC821-SW-42 - VxWorks Device Driver Page 16 of 37
EXAMPLE
#include "tpmc821.h"
...
unsigned char segmentBuffer[100];
TP821_RW_SEGMENT *pSeg;
unsigned long result;
int size;
/*-----------------------------------------------------------
Read data from an open TPMC821 device,
read data from offset 0,
read the same data with byte, word and longword length,
the length shall always be 4 byte
-----------------------------------------------------------*/
size = 0; /* Checking buffer overrun (size always < 100) */
/* pointer to the first segment */
pSeg = (TP821_RW_SEGMENT*)&segmentBuffer;
pSeg->itemType = TP821_BYTE;
pSeg->itemNumber = 4;
pSeg->dataOffset = 0;
size += SEGMENT_SIZE(pSeg);
/* same data read as word */
pSeg = NEXT_SEGMENT(pSeg);
pSeg->itemType = TP821_WORD;
pSeg->itemNumber = 2;
pSeg->dataOffset = 0;
size += SEGMENT_SIZE(pSeg);
/* same data read as longword */
pSeg = NEXT_SEGMENT(pSeg);
pSeg->itemType = TP821_LWORD;
pSeg->itemNumber = 1;
pSeg->dataOffset = 0;
size += SEGMENT_SIZE(pSeg);
/* End segment */
pSeg = NEXT_SEGMENT(pSeg);
pSeg->itemType = TP821_END;
pSeg->itemNumber = 0;
pSeg->dataOffset = 0;
size += SEGMENT_SIZE(pSeg);
result = read(tp821_dev, &segmentBuffer, size);
if (result != ERROR)
{
/* read successfully completed */
}

TPMC821-SW-42 - VxWorks Device Driver Page 17 of 37
else
{
/* read failed */;
}
...
RETURNS
ERROR or length of data buffer
INCLUDES
vxworks.h
tpmc821.h
SEE ALSO
ioLib, basic I/O routine - read()

TPMC821-SW-42 - VxWorks Device Driver Page 18 of 37
4.3 write()
NAME
write() – writes data to the specified TPMC821 device.
SYNOPSIS
int write
(
int fd, /* device descriptor from opened TPMC821 device */
char *buffer, /* pointer to the data buffer */
size_t bytes /* not used */
)
PARAMETER
The parameter fd is a file descriptor specifying the device which shall be used.
The argument buffer points to a driver-specific I/O parameter block. This data structure is named
TP821_RW_SEGMENT (see below).
The parameter bytes is not used by the TPMC821 Device Driver.
data structure TP821_RW_SEGMENT
typedef struct
{
unsigned short itemNumber; /* number of items (bytes, w..) */
unsigned short itemType; /* TP821_BYTE|TP821_WORD|.. */
unsigned short dataOffset; /* Byte Off. in DATA IN/OUT reg */
union
{
unsigned char byte[1];
unsigned short word[1];
unsigned long lword[1];
} u;
} TP821_RW_SEGMENT;
The argument itemNumber specifies how many elements of the specified type will follow.
The itemType specifies the length of the data element. Allowed values are:
TP821_END Specifies the last segment of a segment list for data
commands, no data follows.
TP821_BYTE Specifies a segment with byte data. The union part byte will
be used (Datalength = itemNumber * 1 byte).
TP821_WORD Specifies a segment with word data. The union part word will
be used (Datalength = itemNumber * 2 byte).
TP821_LWORD Specifies a segment with longword data. The union part
lword will be used (Datalength = itemNumber * 4 byte).

TPMC821-SW-42 - VxWorks Device Driver Page 19 of 37
The argument dataOffset specifies the offset in the data area of the TPMC821. The specified data will
be written to the data in base address + dataOffset (in byte).
The union umarks the first element of the data area of the segment. The area size is not specified by
this array. It is specified with the itemNumber argument.
The data structure TP821_RW_SEGMENT will be put over the data buffer.
There are two MACROS defined in tpmc821.h, which will help setting up the data buffer.
The 1st function SEGMENT_SIZE(pSeg) calculates the length of the data segment. The data segment
must be specified with the segment pointer in pSeg.
The 2nd function NEXT_SEGMENT(pSeg) calculates the start of the next segment. The actual data
segment must be specified with the segment pointer in pSeg. The new data pointer will be the return
value (see example below).
Example
There are two data segments that shall be transmitted. The 1st segment has a size of 8 bytes, the 2nd
segment shall have a size of 2 longwords. The contents of the 1st segment shall be written to data
offset 8 and the 2nd segment shall be written to position 0. The data buffer segmentation will have the
following layout.
Segment values:
1st segment:
itemNumber: 8
itemType: TP821_BYTE
itemOffset: 0x008
data: 0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77
2nd segment:
itemNumber: 2
itemType: TP821_LWORD
itemOffset: 0x000
data: 0x12345678, 0x9ABCDEF0
End segment:
itemNumber: 0
itemType: TP821_END
itemOffset: 0x000
data: (none)

TPMC821-SW-42 - VxWorks Device Driver Page 20 of 37
The data buffer has the following layout:
Offset +0 +1 +2 +3 +4 +5 +6 +7
+0x00 0x00 0x08 0x00 0x01 0x00 0x08 0x00 0x11
+0x08 0x22 0x33 0x44 0x55 0x66 0x77 0x00 0x02
+0x10 0x00 0x04 0x00 0x00 0x12 0x34 0x56 0x78
+0x18 0x9A 0xBC 0xDE 0xF0 0x00 0x00 0x00 0x00
+0x20 0x00 0x00 xx xx xx xx xx xx
The data output area of the TPMC821 (after writing):
Offset +0 +1 +2 +3 +4 +5 +6 +7
+0x00 0x12 0x34 0x56 0x78 0x9A 0xBC 0xDE 0xF0
+0x08 0x00 0x11 0x22 0x33 0x44 0x55 0x66 0x77
EXAMPLE
#include "tpmc821.h"
...
unsigned char segmentBuffer[100];
TP821_RW_SEGMENT *pSeg;
unsigned long result;
int size;
/*-----------------------------------------------------------
Write data to an open TPMC821 device,
write data to offset 0,
write one word with data (0x1234)
-----------------------------------------------------------*/
size = 0; /* Checking buffer overrun (size always < 100) */
/* pointer to the first segment */
pSeg = (TP821_RW_SEGMENT*)&segmentBuffer;
pSeg->itemType = TP821_WORD;
pSeg->itemNumber = 1;
pSeg->dataOffset = 0;
pSeg->u.word[0] = 0x1234;
size += SEGMENT_SIZE(pSeg);
/* End segment */
pSeg = NEXT_SEGMENT(pSeg);
pSeg->itemType = TP821_END;
pSeg->itemNumber = 0;
pSeg->dataOffset = 0;
size += SEGMENT_SIZE(pSeg);