Tews Technologies TPMC500-SW-42 User manual

The Embedded I/O Company
TPMC500-SW-42
VxWorks Device Driver
32 Channel 12 Bit ADC
Version 2.0.x
User Manual
Issue 2.0.0
October 2004
TEWS TECHNOLOGIES GmbH
Am Bahnhof 7 25469 Halstenbek / Germany
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

TPMC500-SW-42 - VxWorks Device Driver Page 2 of 19
TPMC500-SW-42
32 Channel 12 Bit ADC
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.
1999-2004 by TEWS TECHNOLOGIES GmbH
IndustryPack is a registered trademark of SBS Technologies, Inc
Issue Description Date
1.0 First Issue November 1999
1.1 General Revision November 2003
2.0.0 New Device Initialization Parameters, File list modified,
Support for Intel x86 added October 29, 2004

TPMC500-SW-42 - VxWorks Device Driver Page 3 of 19
Table of Contents
1INTRODUCTION.........................................................................................................4
2INSTALLATION..........................................................................................................5
2.1 Hardware dependent Configuration..............................................................................................5
2.2 Including the driver in VxWorks....................................................................................................5
2.3 Special installation for Intel x86 based targets............................................................................6
3I/O SYSTEM FUNCTIONS..........................................................................................7
3.1 tp500Drv() ........................................................................................................................................7
3.2 tp500DevCreate().............................................................................................................................8
4I/O INTERFACE FUNCTIONS..................................................................................10
4.1 open() .............................................................................................................................................10
4.2 close().............................................................................................................................................12
4.3 read() ..............................................................................................................................................13
4.4 ioctl() ..............................................................................................................................................15
4.4.1 FIOSTARTSEQ Setup and start the sequencer ................................................................16
4.4.2 FIOSTOPSEQ Stop the sequencer ...................................................................................16
4.4.3 ioctl() example.....................................................................................................................17
5APPENDIX................................................................................................................19
5.1 Predefined Symbols......................................................................................................................19
5.2 Error Codes ...................................................................................................................................19

TPMC500-SW-42 - VxWorks Device Driver Page 4 of 19
1 Introduction
The TPMC500-SW-42 VxWorks device driver software allows the operation of the TPMC500
32 Channel 12-bit ADC PMC conforming to the VxWorks I/O system specification. This includes a
device-independent basic I/O interface with open(), read() and ioctl() functions.
The TPMC500 driver includes following functions:
!read the actual input value
!start and setup the input sequencer
!stop the input sequencer

TPMC500-SW-42 - VxWorks Device Driver Page 5 of 19
2Installation
Following files are located on the distribution media:
tp500drv.c TPMC500 Device Driver Source
tp500def.h TPMC500 Local Include File
tpmc500.h TPMC500 Application Include File
tp500pci.c TPMC500 PCI MMU mapping for Intel x86 based targets
tpxxxhwdep.c Collection of hardware dependent functions
tpxxxhwdep.h Include for hardware dependent functions
tp500exa.c Example Application
For installation the files have to be copied to the desired target directory.
2.1 Hardware dependent Configuration
The driver is written to be used on TEWS carrier boards and others, but sometimes it is necessary to
adapt the software. The following points have to be guaranteed:
!full access to the PMC I/O area of the card
!full access to PMC memory area of the card (correction data address space)
!interrupt must be connected
Most systems should work without any changes, but it may be necessary to setup address offsets or
an offset between interrupt level and vector. Information for these values should be available in you
BSP manual and/or CPU board manual. If such an adaptation is necessary you will get a warning
while compilation.
The values that have to be modified can be found in tpxxxhwdep.h. There are three values that will be
explicitly undefined after installation. To use these values, you have to define them with an appropriate
value.
USERDEFINED_MEM_OFFSET This value defines the offset between CPU-bus and
PCI-bus address for memory accesses.
USERDEFINED_IO_OFFSET This value defines the offset between CPU-bus and
PCI-bus address for 16-bit I/0 accesses.
USERDEFINED_LEV2VEC This value defines the value that should be added
to the interrupt level number to get the interrupt
vector number.
If everything works fine while the values are undefined, and warnings are generated, you can define
these values with a value of 0;
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.

TPMC500-SW-42 - VxWorks Device Driver Page 6 of 19
2.3 Special installation for Intel x86 based targets
The TPMC500 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 is 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 PCI memory spaces can’t be accessed.
To solve this problem a MMU mapping entry has to be added for the required TPMC500 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 tp500PciInit() won’t be included and the user can skip to the following steps.
The C source file tp461pci.c contains the function tp461PciInit(). This routine finds out all TPMC461
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/2.2 project facility is used, the right place to call the function tp500PciInit() is at the
end of the function sysHwInit() in sysLib.c (can be opened from the project Files window).
Be sure that the function is called prior to MMU initialization otherwise the TPCM500 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:
tp500PciInit();
The function tp500PciInit() is 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.

TPMC500-SW-42 - VxWorks Device Driver Page 7 of 19
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 tp500Drv()
NAME
tp500Drv() - installs the TPMC500 driver in the I/O system and initializes the driver.
SYNOPSIS
STATUS tp500Drv(void)
DESCRIPTION
This function installs the TPMC500 driver in the I/O system, allocates driver resources and initializes
them.
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)
SEE ALSO
VxWorks Programmer’s Guide: I/O System

TPMC500-SW-42 - VxWorks Device Driver Page 8 of 19
3.2 tp500DevCreate()
NAME
tp500DevCreate() - adds a TPMC500 device to the system and initializes device hardware.
SYNOPSIS
STATUS tp500DevCreate
(
char *name, /* name of the device to create */
int glbModNo, /* TPMC500 module number */
unsigned long type /* device type [TPMC500_nn] */
)
DESCRIPTION
This routine is called to add a device to the system that will be serviced by the TPMC500 driver. This
function must be called before performing any I/O request to this driver.
PARAMETER
The name of the device is selected by the string, which is deployed by this routine in the parameter
name.
The argument glbModNo specifies the index of the TPMC500 that should be set up. For the first
found TPMC500 glbModNo must be set to 0, for the second to 1, and so on.
The argument type specifies the module type mounted to the address. There are predefined symbols
for this argument in tpmc500.h. Allowed values are TPMC500_10, TPMC500_11, TPMC500_12,
TPMC500_13, TPMC500_20, TPMC500_21, TPMC500_22 and TPMC500_23.

TPMC500-SW-42 - VxWorks Device Driver Page 9 of 19
EXAMPLE
#include "tpmc500.h"
...
/*-------------------------------------------------------
Create the device "/tpmc500" for the first found TPMC500
The mounted module is a TPMC500-10
-----------------------------------------------------------*/
status = tp500DevCreate ("/tpmc500",
1,
TPMC500_10);
...
RETURNS
OK or ERROR (if the driver is not installed or the device already exists or any other error occurred
during the creation)

TPMC500-SW-42 - VxWorks Device Driver Page 10 of 19
4I/O interface functions
This chapter describes the interface to the basic I/O system.
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 TPMC500 driver, must be 0 */
int mode /* not used for TPMC500 driver, must be 0 */
)
DESCRIPTION
Before I/O can be performed to the TPMC500 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 "/tpmc500" for I/O
-----------------------------------------------------------*/
fd = open("/tpmc500", 0, 0);
...

TPMC500-SW-42 - VxWorks Device Driver Page 11 of 19
RETURNS
A device descriptor number or ERROR (if the device does not exist or no device descriptors are
available)
INCLUDES
ioLib.h, semLib.h
SEE ALSO
ioLib, basic I/O routine - open()

TPMC500-SW-42 - VxWorks Device Driver Page 12 of 19
4.2 close()
NAME
close() - closes a device or file.
SYNOPSIS
int close
(
int fd, /* descriptor to close */
)
DESCRIPTION
This function closes opened devices.
EXAMPLE
int retval;
...
/*------------------
Close the device
------------------*/
retval = close(fd);
...
RETURNS
A device descriptor number or ERROR (if the device does not exist or no device descriptors are
available)
INCLUDES
ioLib.h, semLib.h
SEE ALSO
ioLib, basic I/O routine - close()

TPMC500-SW-42 - VxWorks Device Driver Page 13 of 19
4.3 read()
NAME
read() – reads a value from the specified TPMC500 device.
SYNOPSIS
int read
(
int fd, /* device descriptor from opened TPMC500 device */
char *buffer, /* pointer to an I/O buffer */
size_t maxbytes /* not used */
)
DESCRIPTION
This function starts the conversion for one input channel and returns the value.
PARAMETER
The parameter fd is a file descriptor specifying the device which shall be used.
The parameter buffer points to the special I/O structure TP500_IO_BUFFER (refer to tpmc500.h).
The argument maxbytes is not used for the device driver.
data structure TP500_IO_BUFFER:
typedef struct
{
int Channel; /* Channel number */
int Gain; /* Gain for channel */
unsigned long flags; /* Special flags */
long value; /* Return value */
} TP500_IO_BUFFER;
The argument Channel specifies the channel to use.
The argument Gain specifies the gain, which shall be used.
The flags specify the mode to use. Allowed values are:
TP500_DIFFMODE Enable Differential Mode
TP500_SNGLMODE Enable Single Ended Mode
TP500_CORRENA Enable Data Correction
TP500_CORRDIS Disable Data Correction
The read value will be returned in value.

TPMC500-SW-42 - VxWorks Device Driver Page 14 of 19
EXAMPLE
int fd;
int result;
TP500_IO_BUFFER buf;
...
/*-----------------------------------------------------------
Read the actual value of the input differential channel 1,
the gain shall be 2 and the value shall be corrected
-----------------------------------------------------------*/
buf.Channel = 1;
buf.Gain = 2;
buf.flags = TP500_CORRENA | TP500_DIFFMODE;
result = read (fd, &buf, 0);
...
RETURNS
ERROR if an error occurred
INCLUDE FILES
ioLib.h, semLib.h, tpmc500.h
SEE ALSO
ioLib, basic I/O routine - read()

TPMC500-SW-42 - VxWorks Device Driver Page 15 of 19
4.4 ioctl()
NAME
ioctl() - performs an I/O control function.
SYNOPSIS
int ioctl
(
int fd, /* device descriptor from opened TPMC500 device */
int function, /* function code */
int arg /* optional function dependent argument */
)
DESCRIPTION
Special I/O operation that do not fit to the standard basic I/O calls will be performed by calling the
ioctl() function with a specific function code and an optional function dependent argument.
PARAMETER
The parameter fd specifies the device descriptor of the opened TPMC500 device.
The parameter function selects the action, which will be executed by the driver.
The structure arg depends on the function (see description below).
RETURNS
OK or ERROR (if the device descriptor does not exist or the function code is unknown or an error
occurred)
INCULDES
ioLib.h, semLib.h, tpmc500.h
SEE ALSO
ioLib, basic I/O routine - ioctl(), VxWorks Programmer’s Guide: I/O System

TPMC500-SW-42 - VxWorks Device Driver Page 16 of 19
4.4.1 FIOSTARTSEQ Setup and start the sequencer
This function reads the values of the specified input lines and stores the input values into a user
supplied FIFO. For this operation the argument arg points to a structure named TP500_IOC_BUF.
This structure is defined in tpmc500.h.
Data structure TP500_IOC_BUF:
typedef struct
{
unsigned short cycletime; /* sequencer cycletime */
unsigned long act_channels; /* number of active channels */
TP500_IO_BUFFER *chan_setup; /* channel configurations */
unsigned long buf_size; /* size of buffer */
unsigned long buf_stat; /* buffer state / error */
unsigned long putIdx; /* Index to put data */
unsigned long getIdx; /* Index to read data */
long *buffer; /* pointer to buffer */
} TP500_IOC_BUF
The cycletime argument specifies the length of a cycle. This value is specified in 100µs steps.
The argument act_channels specifies the number of active channels.
The pointer chan_setup points to an array of data structures specifying the channel setups. The used
data structure is the same used by the read command (for more information refer to the read
command).
The argument buf_size specifies the size of the input FIFO.
The actual state and errors will be shown in the buf_stat argument. The following bits are defined.
TP500_SEQ_BUF_OVERRUN The user supplied FIFO is full and new data
can not be stored
TP500_SEQ_DATA_OVERFLOW Old data not read by the software when new
values are ready
TP500_SEQ_TIMER_ERR The specified cycle time is not long enough to
convert the specified channels
TP500_SEQ_INST_RAM_ERR The sequencer is started, but no channel has
been selected.
The arguments putIdx and getIdx are used to specify the actual read and write pointer into the FIFO.
putIdx shall be changed by the driver and just be read from the application. getIdx must be moved by
the application after reading a set of input values and is only read by the driver.
The pointer buffer points to the user supplied memory area where the sequencer input data will be
stored.
4.4.2 FIOSTOPSEQ Stop the sequencer
This command stops a running sequence cycles. This command needs no argument.

TPMC500-SW-42 - VxWorks Device Driver Page 17 of 19
4.4.3 ioctl() example
#define SBUF_SIZE 0x200
int fd;
STATUS result;
TP500_IOC_BUF seq_buf;
TP500_IO_BUFFER seq_rw_par[2];
long seq_data_buf[SBUF_SIZE];
...
/*---------------------------------------------------------
Start sequence using channel 1 and 3
Channel 1:
differential
data correction on
gain = 1
Channel 3:
single-ended
data correction off
gain = 5
---------------------------------------------------------*/
seq_buf.cycletime = 10000; /* Cycletime 1s */
seq_buf.buffer = seq_data_buf;
seq_buf.act_channels = 2;
seq_buf.buf_size = SBUF_SIZE / seq_buf.act_channels;
seq_buf.chan_setup = seq_rw_par;
seq_rw_par[0].Channel = 1;
seq_rw_par[0].Gain = 1;
seq_rw_par[0].flags = TP500_CORRENA | TP500_DIFFMODE;
seq_rw_par[1].Channel = 3;
seq_rw_par[1].Gain = 5;
seq_rw_par[1].Mode = TP500_CORRDIS | TP500_SNGLMODE;
result = ioctl(fd, FIOSTARTSEQ , (int)&cntrl_par);
if (result == OK)
{
/* Sequencer started */
}
else
{
/* Error when starting the sequencer */
}
...

TPMC500-SW-42 - VxWorks Device Driver Page 18 of 19
...
/*---------------------------------------------------------
Stop Sequencer
---------------------------------------------------------*/
result = ioctl(fd, FIOSTOPSEQ , 0);
if (result == OK)
{
/* Sequencer started */
}
else
{
/* Error when starting the sequencer */
}

TPMC500-SW-42 - VxWorks Device Driver Page 19 of 19
5Appendix
This chapter describes the symbols which are defined in the file tpmc500h.
5.1 Predefined Symbols
Ioctl Function Codes
FIOSTARTSEQ 0x00000100 Start and setup the sequencer
FIOSTOPSEQ 0x00000101 Stop the sequencer
Module Types
TPMC500_10 10 TPMC500-10
TPMC500_11 11 TPMC500-11
TPMC500_12 12 TPMC500-12
TPMC500_13 13 TPMC500-13
TPMC500_20 20 TPMC500-20
TPMC500_21 21 TPMC500-21
TPMC500_22 22 TPMC500-22
TPMC500_23 23 TPMC500-23
5.2 Error Codes
If the device driver creates an error the error codes are stored in the errno. They can be read with the
VxWorks function errnoGet() or printErrno().
S_tp500Drv_ICHAN 0x05000001 Illegal channel number specified
S_tp500Drv_IGAIN 0x05000002 Illegal gain specified
S_tp500Drv_MODBUSY 0x05000003 Module is busy (the sequencer is running)
S_tp500Drv_TIMEOUT 0x05000004 Hardware timed out
S_tp500Drv_ICMD 0x05000005 Illegal I/O command
S_tp500Drv_DBLCHAN 0x05000006 Channel is already in use
S_tp500Drv_NOMEM 0x05000007 Can’t allocate memory
S_tp500Drv_NXIO 0x05000008 No module or specified module number not
found
S_tp500Drv_NODRV 0x05000009 Driver has not been started
S_tp500Drv_ILLTYPE 0x0500000A Illegal model type specified