Tews Technologies TDRV004-SW-82 User manual

The Embedded I/O Company
TDRV004-SW-82
Linux Device Driver
Reconfigurable FPGA
Version 2.0.x
User Manual
Issue 2.0.0
November 2011
TEWS TECHNOLOGIES GmbH
Am Bahnhof 7 25469 Halstenbek, Germany
Phone: [phone] Fax: [phone]
e-mail: [e-mail] www.tews.com

TDRV004-SW-82 - Linux Device Driver Page 2 of 62
TDRV004-SW-82
Linux Device Driver
Reconfigurable FPGA
Supported Modules:
TPMC630
TCP630
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.
2005-2011 by TEWS TECHNOLOGIES GmbH
Issue Description Date
1.0.0 First Issue September 30, 2005
1.1.0 Interrupt Support functions added, New Address TEWS LLC June 08, 2007
1.1.1 Address TEWS LLC removed April 22, 2010
2.0.0 API documentation added, Ioctl description removed, General revision November 28, 2011

TDRV004-SW-82 - Linux Device Driver Page 3 of 62
Table of Contents
1 INTRODUCTION.........................................................................................................4
2 INSTALLATION..........................................................................................................5
2.1 Build and install the Device Driver................................................................................................5
2.2 Uninstall the Device Driver ............................................................................................................6
2.3 Install Device Driver into the running Kernel...............................................................................6
2.4 Remove Device Driver from the running Kernel..........................................................................6
2.5 Change Major Device Number.......................................................................................................7
3 API DOCUMENTATION .............................................................................................8
3.1 General Functions...........................................................................................................................8
3.1.1 tdrv004Open ......................................................................................................................8
3.1.2 tdrv004Close....................................................................................................................10
3.2 Device Access Functions.............................................................................................................12
3.2.1 tdrv004XsvfPlay...............................................................................................................12
3.2.2 tdrv004XsvfPos................................................................................................................14
3.2.3 tdrv004XsvfLastCommand...............................................................................................16
3.2.4 tdrv004Reconfigure..........................................................................................................18
3.2.5 tdrv004SetWaitstates.......................................................................................................20
3.2.6 tdrv004SetClock...............................................................................................................22
3.2.7 tdrv004SpiWrite ...............................................................................................................26
3.2.8 tdrv004SpiRead ...............................................................................................................29
3.2.9 tdrv004PlxWrite................................................................................................................32
3.2.10 tdrv004PlxRead ...............................................................................................................35
3.2.11 tdrv004ReadU8................................................................................................................38
3.2.12 tdrv004ReadU16..............................................................................................................41
3.2.13 tdrv004ReadU32..............................................................................................................44
3.2.14 tdrv004WriteU8................................................................................................................47
3.2.15 tdrv004WriteU16..............................................................................................................50
3.2.16 tdrv004WriteU32..............................................................................................................53
3.2.17 tdrv004ConfigureInterrupts..............................................................................................56
3.2.18 tdrv004WaitForINT1.........................................................................................................58
3.2.19 tdrv004WaitForINT2.........................................................................................................60
4 DIAGNOSTIC............................................................................................................62

TDRV004-SW-82 - Linux Device Driver Page 4 of 62
1 Introduction
The TDRV004-SW-82 Linux device driver allows the operation of the TDRV004 compatible devices
conforming to the Linux I/O system specification. This includes a device-independent basic I/O
interface with open(),close(),and ioctl() functions.
The TDRV004-SW-82 device driver supports the following features:
Program and reconfigure onboard FPGA
Program onboard clock generator using the Serial Programming Interface (SPI)
Read/write FPGA registers (32bit / 16bit / 8bit)
Read/write EEPROM blocks located in clock device using the Serial Programming Interface (SPI)
Read/write specific PLX9030 registers
Wait for local interrupt sources
The TDRV004-SW-82 supports the modules listed below:
TPMC630 Reconfigurable FPGA with
64 TTL I/O / 32 Differential I/O Lines PMC
TCP630 Reconfigurable FPGA with
64 TTL I/O / 32 Differential I/O Lines CompactPCI
In this document all supported modules and devices will be called TDRV004. Specials for a
certain device will be advised.
To get more information about the features and use of supported devices it is recommended to read
the manuals listed below.
TPMC630 (or compatible) User manual
TPMC630 (or compatible) Engineering Manual
PLX PCI9030 User Manual

TDRV004-SW-82 - Linux Device Driver Page 5 of 62
2Installation
The directory TDRV004-SW-82 on the distribution media contains the following files:
TDRV004-SW-82-2.0.0.pdf This manual in PDF format
TDRV004-SW-82-SRC.tar.gz GZIP compressed archive with driver source code
fpgaexa.tar.gz FPGA example XSVF
ChangeLog.txt Release history
Release.txt Information about the Device Driver Release
The GZIP compressed archive TDRV004-SW-82-SRC.tar.gz contains the following files and
directories:
Directory path ‘tdrv004’:
tdrv004.c Driver source code
tdrv004def.h Driver include file
tdrv004.h Driver include file for application program
pf_micro.c XSVF player functions (Platform Flash)
pf_micro.h header file for XSVF player functions
pf_lenval.c special functions for XSVF player
pf_lenval.h header file for XSVF functions
pf_ports.c hardware layer for XSVF player
pf_ports.h header file for XSVF hardware layer
Makefile Device driver make file
makenode Script for device node creation
api/tdrv004api.h API include file
api/tdrv004api.c API source file
include/config.h Driver independent library header file
include/tpmodule.c Driver independent library
include/tpmodule.h Driver independent library header file
example/tdrv004exa.c Example application
example/Makefile Example application makefile
In order to perform an installation, extract all files of the archive TDRV004-SW-82-SRC.tar.gz to the
desired target directory. The command ‘tar -xzvf TDRV004-SW-82-SRC.tar.gz’ will extract the files into
the local directory.
Login as root and change to the target directory
Copy tdrv004.h to /usr/include
2.1 Build and install the Device Driver
Login as root
Change to the target directory
To create and install the driver in the module directory /lib/modules/<version>/misc enter:
# make install
To update the device driver’s module dependencies, enter:
#depmod -aq

TDRV004-SW-82 - Linux Device Driver Page 6 of 62
2.2 Uninstall the Device Driver
Login as root
Change to the target directory
To remove the driver from the module directory /lib/modules/<version>/misc enter:
# make uninstall
2.3 Install Device Driver into the running Kernel
To load the device driver into the running kernel, login as root and execute the following
commands:
# modprobe tdrv004drv
After the first build or if you are using dynamic major device allocation it is necessary to create
new device nodes on the file system. Please execute the script file makenode to do this. If your
kernel has enabled a device file system (devfs or sysfs with udev) then you have to skip
running the makenode script. Instead of creating device nodes from the script the driver itself
takes creating and destroying of device nodes in its responsibility.
# sh makenode
On success the device driver will create a minor device for each TDRV004 device found. The first
TDRV004 device can be accessed with device node /dev/tdrv004_0, the second module with device
node /dev/tdrv004_1 and so on.
The assignment of device nodes to physical TDRV004 modules depends on the search order of the
PCI bus driver.
2.4 Remove Device Driver from the running Kernel
To remove the device driver from the running kernel login as root and execute the following
command:
# modprobe –r tdrv004drv
If your kernel has enabled devfs or sysfs (udev), all /dev/tdrv004_x nodes will be automatically
removed from your file system after this.
Be sure that the driver isn’t opened by any application program. If opened you will get the
response “tdrv004drv: Device or resource busy” and the driver will still remain in the system
until you close all opened files and execute modprobe –r again.

TDRV004-SW-82 - Linux Device Driver Page 7 of 62
2.5 Change Major Device Number
This paragraph is only for Linux kernels without dynamic device file system installed. The TDRV004
driver uses dynamic allocation of major device numbers per default. If this isn’t suitable for the
application it is possible to define a major number for the driver.
To change the major number, edit the file tdrv004def.h, change the following symbol to appropriate
value and enter make install to create a new driver.
TDRV004_MAJOR Valid numbers are in range between 0 and 255. A value of 0 means
dynamic number allocation.
Example:
#define TDRV004_MAJOR 122
Be sure that the desired major number isn’t used by other drivers. Please check /proc/devices
to see which numbers are free.

TDRV004-SW-82 - Linux Device Driver Page 8 of 62
3API Documentation
3.1 General Functions
3.1.1 tdrv004Open
NAME
tdrv004Open – Opens a Device
SYNOPSIS
TDRV004_HANDLE tdrv004Open
(
char *DeviceName
);
DESCRIPTION
Before I/O can be performed to a device, a file descriptor must be opened by a call to this function.
PARAMETERS
DeviceName
This parameter points to a null-terminated string that specifies the name of the device.
EXAMPLE
#include “tdrv004api.h”
TDRV004_HANDLE hdl;
/*
** open file descriptor to device
*/
hdl = tdrv004open( “/dev/tdrv004_0” );
if (hdl == NULL)
{
/* handle open error */
}

TDRV004-SW-82 - Linux Device Driver Page 9 of 62
RETURNS
A device handle, or NULL if the function fails. An error code will be stored in errno.
ERROR CODES
The error codes are stored in errno.
The error code is a standard error code set by the I/O system.

TDRV004-SW-82 - Linux Device Driver Page 10 of 62
3.1.2 tdrv004Close
NAME
tdrv004Close – Closes a Device
SYNOPSIS
TDRV004_STATUS tdrv004Close
(
TDRV004_HANDLE hdl
);
DESCRIPTION
This function closes previously opened devices.
PARAMETERS
hdl This value specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
EXAMPLE
#include “tdrv004api.h”
TDRV004_HANDLE hdl;
TDRV004_STATUS result;
/*
** close file descriptor to device
*/
result = tdrv004Close( hdl );
if (result != TDRV004_OK)
{
/* handle close error */
}

TDRV004-SW-82 - Linux Device Driver Page 11 of 62
RETURNS
On success TDRV004_OK, or an appropriate error code.
ERROR CODES
TDRV004_ERR_INVALID_HANDLE The specified TDRV004_HANDLE is invalid.
Other returned error codes are system error conditions.

TDRV004-SW-82 - Linux Device Driver Page 12 of 62
3.2 Device Access Functions
3.2.1 tdrv004XsvfPlay
NAME
tdrv004XsvfPlay – Play an XSVF file for FPGA programming
SYNOPSIS
TDRV004_STATUS tdrv004XsvfPlay
(TDRV004_HANDLE hdl,
unsigned char *pXsvfContent,
unsigned int XsvfSize
);
DESCRIPTION
This function programs the FPGA with a supplied XSVF file. For information on building an XSVF file,
please refer to the Engineering Documentation of the TDRV004 product family.
The device driver is not able to verify the supplied XSVF file content, so please make sure that
the supplied XSVF is of a valid file format.
PROGRAMMING HINTS
Depending on the XSVF file, there might be a waiting period of approx. 15 seconds at the beginning of
programming. The programming of the delivered FPGA example design XSVF file should not take
much longer than 1 minute.
If the programming fails, try to increase the used waitstates with control function
tdrv004SetWaitStates() (refer to the corresponding section in this manual). Additionally, the CLK1
should not be lower than 10MHz for programming.
PARAMETERS
hdl This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
pXsvfContent
This argument points to an unsigned char array containing the XSVF data.

TDRV004-SW-82 - Linux Device Driver Page 13 of 62
XsvfSize
This argument holds the size of the supplied XSVF data area.
EXAMPLE
#include “tdrv004api.h”
TDRV004_HANDLE hdl;
TDRV004_STATUS result;
unsigned char *pXsvfContent;
unsigned long XsvfFileSize;
/*
** Play an XSVF file to program the FPGA.
** The filecontent must be available in a local buffer,
** the size of the file must be stored in XsvfFileSize.
*/
result = tdrv004XsvfPlay ( hdl,
pXsvfContent,
XsvfFileSize );
if (result != TDRV004_OK)
{
/* handle error */
}
RETURNS
On success, TDRV004_OK is returned. In the case of an error, the appropriate error code is returned
by the function.
ERROR CODES
Error Code Description
TDRV004_ERR_INVALID_HANDLE The specified TDRV004_HANDLE is invalid.
TDRV004_ERR_BUSY The device is already busy with XSVF
TDRV004_ERR_INVAL An error occurred during XSVF operation

TDRV004-SW-82 - Linux Device Driver Page 14 of 62
3.2.2 tdrv004XsvfPos
NAME
tdrv004XsvfPos – Retrieve current play-position in XSVF file
SYNOPSIS
TDRV004_STATUS tdrv004XsvfPos
(TDRV004_HANDLE hdl,
int *pXsvfPos
);
DESCRIPTION
This function returns the number of the current processed byte in the XSVF file during programming.
This control function can be used to monitor the programming progress.
PARAMETERS
hdl This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
pXsvfPos
This parameter specifies a pointer to an unsigned int value which receives the current
processed XSVF byte.

TDRV004-SW-82 - Linux Device Driver Page 15 of 62
EXAMPLE
#include “tdrv004api.h”
TDRV004_HANDLE hdl;
TDRV004_STATUS result;
int XsvfPos;
/*
** Check XSVF position
*/
result = tdrv004XsvfPos( hdl,
&XsvfPos );
if (result == TDRV004_OK)
{
printf(“Current XSVF position: %d\n”, XsvfPos);
} else {
/* handle error */
}
RETURNS
On success, TDRV004_OK is returned. In the case of an error, the appropriate error code is returned
by the function.
ERROR CODES
Error Code Description
TDRV004_ERR_INVALID_HANDLE The specified TDRV004_HANDLE is invalid.

TDRV004-SW-82 - Linux Device Driver Page 16 of 62
3.2.3 tdrv004XsvfLastCommand
NAME
tdrv004XsvfLastCommand – Get the last executed XSVF command
SYNOPSIS
TDRV004_STATUS tdrv004XsvfLastCommand
(TDRV004_HANDLE hdl,
int *pXsvfLastCmd
);
DESCRIPTION
This function returns the number of the last executed XSVF command. This value can be used to find
errors inside the supplied XSVF file. This value refers to the line inside the ASCII SVF file.
PARAMETERS
hdl This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
pXsvfLastCmd
This parameter specifies a pointer to an unsigned int value which receives the last executed
XSVF command (line number of ASCII SVF file).

TDRV004-SW-82 - Linux Device Driver Page 17 of 62
EXAMPLE
#include “tdrv004api.h”
TDRV004_HANDLE hdl;
TDRV004_STATUS result;
int XsvfLastCmd;
/*
** Check Last XSVF command
*/
result = tdrv004XsvfLastCommand( hdl,
&XsvfLastCmd );
if (result == TDRV004_OK)
{
printf(“Last XSVF command: %d\n”, XsvfLastCmd);
} else {
/* handle error */
}
RETURNS
On success, TDRV004_OK is returned. In the case of an error, the appropriate error code is returned
by the function.
ERROR CODES
Error Code Description
TDRV004_ERR_INVALID_HANDLE The specified TDRV004_HANDLE is invalid.

TDRV004-SW-82 - Linux Device Driver Page 18 of 62
3.2.4 tdrv004Reconfigure
NAME
tdrv004Reconfigure – Trigger FPGA reconfiguration process
SYNOPSIS
TDRV004_STATUS tdrv004Reconfigure
(TDRV004_HANDLE hdl
);
DESCRIPTION
This function starts the reconfiguration process of the FPGA. This control function must be called after
the FPGA is programmed using tdrv004XsvfPlay(). The function returns after the reconfiguration is
done, or an error occurred.
PARAMETERS
hdl This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
EXAMPLE
#include “tdrv004api.h”
TDRV004_HANDLE hdl;
TDRV004_STATUS result;
/*
** Reconfigure FPGA
*/
result = tdrv004Reconfigure( hdl );
if (result != TDRV004_OK)
{
/* handle error */
}

TDRV004-SW-82 - Linux Device Driver Page 19 of 62
RETURNS
On success, TDRV004_OK is returned. In the case of an error, the appropriate error code is returned
by the function.
ERROR CODES
Error Code Description
TDRV004_ERR_INVALID_HANDLE The specified TDRV004_HANDLE is invalid.
TDRV004_ERR_BUSY The device is already busy with XSVF, Reconfig or
SPI action.
TDRV004_ERR_NOT_READY The DONE signal of the FPGA refused to change
state, the reconfiguration might be invalid. An error
occurred during reconfiguration. This may be
caused by an invalid FPGA content located inside
the XSVF file.

TDRV004-SW-82 - Linux Device Driver Page 20 of 62
3.2.5 tdrv004SetWaitstates
NAME
tdrv004SetWaitstates – Specify number of waitstates for programming
SYNOPSIS
TDRV004_STATUS tdrv004SetWaitstates
(TDRV004_HANDLE hdl,
int WaitStates
);
DESCRIPTION
This function configures the driver to use a number of waitstates during XSVF and SPI programming.
This might be necessary, if the local clock (CLK1) of the onboard clock generator is configured to
rather slow. The local programming interface is clocked with this frequency, which might result in
errors during programming for low CLK1 frequencies and a small amount of waitstates. The system
architecture (existing PCI-to-PCI bridges) might also have an impact.
PARAMETERS
hdl This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
WaitStates
This parameter specifies the number of waitstates to be used for XSVF programming. Valid
values are 1 to 1000.