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