Tews Technologies TIP675-SW-42 User manual

The Embedded I/O Company
TIP675-SW-42
VxWorks Device Driver
48 TTL I/O Lines with Interrupts
Version 1.2.x
User Manual
Issue 1.2.1
June 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

TIP675-SW-42 – VxWorks Device Driver Page 2 of 31
TIP675-SW-42
VxWorks Device Driver
48 TTL I/O Lines with Interrupts
Supported Modules:
TIP675
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.
2002-2008 by TEWS TECHNOLOGIES GmbH
Issue Description Date
1.0 First Issue September 12, 2002
1.1.0 IPAC Carrier Driver Support January 11, 2006
1.2.0 New Address TEWS TECHNOLOGIES LLC
ChangeLog.txt added to file list, new error code for tip675DevCreate() December 5, 2006
1.2.1 Carrier Driver description added June 24, 2008

TIP675-SW-42 – VxWorks Device Driver Page 3 of 31
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 Tornado IDE project ..............................................................................6
2.2 System resource requirement .......................................................................................................7
3 I/O SYSTEM FUNCTIONS..........................................................................................8
3.1 tip675Drv() .......................................................................................................................................8
3.2 tip675DevCreate()..........................................................................................................................10
4 I/O FUNCTIONS .......................................................................................................13
4.1 open() .............................................................................................................................................13
4.2 close().............................................................................................................................................15
4.3 ioctl() ..............................................................................................................................................17
4.3.1 FIO_T675_SET_DIR..........................................................................................................19
4.3.2 FIO_T675_INSTALL_ISF...................................................................................................21
4.3.3 FIO_T675_REMOVE_ISF..................................................................................................24
4.3.4 FIO_T675_ENA_EXCLK....................................................................................................26
4.3.5 FIO_T675_DIS_EXCLK.....................................................................................................27
4.3.6 FIO_T675_READ...............................................................................................................28
4.3.7 FIO_T675_WRITE .............................................................................................................30

TIP675-SW-42 – VxWorks Device Driver Page 4 of 31
1Introduction
1.1 Device Driver
The TIP675-SW-42 VxWorks device driver software allows the operation of the TIP675 IP conforming
to the VxWorks I/O system specification. This includes a device-independent basic I/O interface with
open(), close() and ioctl() functions.
The TIP675 driver includes the following functions:
reading the input register
writing the output register
programming direction of every I/O line
configure simultaneous update feature
connect interrupt callback functions to every I/O line
The TIP675-SW-42 supports the modules listed below:
TIP675-10 48 TTL I/O Lines with Interrupts (IPAC)
To get more information about the features and use of the supported devices it is recommended to
read the manuals listed below.
TIP675 User manual
TIP675 Engineering Manual
CARRIER-SW-42 IPAC Carrier User Manual

TIP675-SW-42 – VxWorks Device Driver Page 5 of 31
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 TIP675-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-65 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
tip675exa.c.
If the IPAC carrier driver isn’t used for the IPAC driver setup, the application software has to setup
carrier board hardware, mapping of device memory and interrupt level setup by itself.

TIP675-SW-42 – VxWorks Device Driver Page 6 of 31
2Installation
The following files and directories are located on the distribution media:
Directory path ‘./TIP675-SW-42/’:
tip675drv.c TIP675 device driver source
tip675def.h TIP675 driver include file
tip675.h TIP675 include file for driver and application
tip675exa.c Example application
include/ipac_carrier.h Carrier driver interface definitions
TIP675-SW-42-1.2.1.pdf PDF copy of this manual
Release.txt Release information
ChangeLog.txt Release history
2.1 Include device driver in Tornado IDE project
For Including the TIP675-SW-42 device driver into a Tornado IDE project follow the steps below:
(1) Copy the files from the distribution media into a subdirectory in your project path.
(For example: ./TIP675)
(2) Add the device drivers C-files to your project.
Make a right click to your project in the ‘Workspace’ window and use the ‘Add Files ...’ topic.
A file select box appears, and the driver files can be selected.
(3) 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 Tornado User’s
Guide.

TIP675-SW-42 – VxWorks Device Driver Page 7 of 31
2.2 System resource requirement
The table gives an overview over the system resources that will be needed by the driver.
Resource Driver requirement Devices requirement
Memory < 1 KB < 1 KB
Stack < 1 KB ---
Semaphores --- ---
Memory and Stack usage may differ from system to system, depending on the used compiler
and its setup.
The following formula shows the way to calculate the common requirements of the driver and devices.
<total requirement> = <driver requirement> + (<number of devices> * <device requirement>)
The maximum usage of some resources is limited by adjustable parameters. If the application
and driver exceed these limits, increase the according values in your project.

TIP675-SW-42 – VxWorks Device Driver Page 8 of 31
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 tip675Drv()
NAME
tip675Drv() - installs the TIP675 driver in the I/O system
SYNOPSIS
#include “tip675.h”
STATUS tip675Drv(void)
DESCRIPTION
This function initializes the TIP675 driver and installs it 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.
EXAMPLE
#include "tip675.h”
/*------ Initialize Driver -----*/
status = tip675Drv();
if (status == ERROR)
{
/* Error handling */
}
RETURNS
OK, or ERROR if the function fails.

TIP675-SW-42 – VxWorks Device Driver Page 9 of 31
ERROR CODES
The error codes are stored in errno and 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
VxWorks Programmer’s Guide: I/O System

TIP675-SW-42 – VxWorks Device Driver Page 10 of 31
3.2 tip675DevCreate()
NAME
tip675DevCreate() – Add a TIP675 serial channel device to the VxWorks system
SYNOPSIS
#include “tip675.h”
STATUS tip675DevCreate
(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 TIP675 minor device number to add to the system.
If modules of the same type are installed the device numbers will be advised in the order the
IPAC CARRIER ipFindDevice() function will find the devices.
For TIP675 devices there is only one devIdx per hardware module starting with devIdx = 0.
funcType
This parameter is unused and should be set to 0.

TIP675-SW-42 – VxWorks Device Driver Page 11 of 31
pParam
This parameter points to a structure (TIP675_DEVCONFIG) containing the default configuration
of the channel.
The structure (TIP675_DEVCONFIG) has the following layout and is defined in tip675.h:
typedef struct
{struct ipac_resource *ipac;
} TIP675_DEVCONFIG;
ipac Pointer to TIP675 module resource descriptor, retrieved by CARRIER Driver
ipFindDevice() function
EXAMPLE
#include "tip675.h”
STATUS result;
TIP675_DEVCONFIG tip675Conf;
struct ipac_resource ipac;
/* IPAC CARRIER Driver initialization */
…
/*
** Find an IP module from TEWS TECHNOLOGIES (manufacturer = 0xB3)
** with model number MODEL_TIP675 (see tip675.h). This module does not
** use interrupts and we need only the IO space base address for the
** related driver.
*/
result = ipFindDevice(0xB3, MODEL_TIP675, 0,
IPAC_INT0_EN | IPAC_LEVEL_SENS | IPAC_CLK_8MHZ,
&ipac);
if (result == OK) {
devConfig.ipac = &ipac;
/*-------------------------------------------------------
Create the device "/tip675/0"
-------------------------------------------------------*/
tip675Conf.ipac = &ipac;
…

TIP675-SW-42 – VxWorks Device Driver Page 12 of 31
…
result = tip675DevCreate( "/tip675/0",
0,
0,
(void*)&tip675Conf);
if (result == OK)
{
/* Device successfully created */
}
else
{
/* Error occurred when creating the device */
}
}
else {
printf("ERROR: No IP found on supported IP carrier boards\n");
}
…
RETURNS
OK, or ERROR if the function fails an error code will be stored in errno.
ERROR CODES
The error codes are stored in errno and can be read with the function errnoGet().
Error code Description
S_ioLib_NO_DRIVER Driver not installed, run tip675Drv()
S_tip675Drv_IARG Invalid argument in device configuration buffer. Please
check all arguments given to tip675DevCreate().
S_ioLib_DEVICE_ERROR Device error. The certain TIP675 device seems to be
faulty or isn’t a TIP675 device at all.
S_tdrv002Drv_EXISTS Device has already been created
SEE ALSO
VxWorks Programmer’s Guide: I/O System

TIP675-SW-42 – VxWorks Device Driver Page 13 of 31
4I/O Functions
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 TIP675 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 tip675DevCreate() must be
used
flags Not used
mode Not used

TIP675-SW-42 – VxWorks Device Driver Page 14 of 31
EXAMPLE
int fd;
…
/*------------------------------------------
Open the device named "/tip675/0" for I/O
------------------------------------------*/
fd = open("/tip675/0", 0, 0);
if (fd == ERROR)
{
/* Handle error */
}
…
RETURNS
A device descriptor number, or ERROR if the function fails an error code will be stored in errno.
ERROR CODES
The error codes are stored in errno and 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()

TIP675-SW-42 – VxWorks Device Driver Page 15 of 31
4.2 close()
NAME
close() – close a device or file
SYNOPSIS
int close
(int fd
)
DESCRIPTION
This function closes opened devices.
PARAMETER
fd This file descriptor specifies the device to be closed. The file descriptor has been returned by
the open() function.
EXAMPLE
int fd;
int retval;
…
/*----------------
close the device
----------------*/
retval = close(fd);
if (retval == ERROR)
{
/* Handle error */
}
…

TIP675-SW-42 – VxWorks Device Driver Page 16 of 31
RETURNS
A device descriptor number or ERROR if the function fails an error code will be stored in errno.
ERROR CODES
The error codes are stored in errno and 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 - close()

TIP675-SW-42 – VxWorks Device Driver Page 17 of 31
4.3 ioctl()
NAME
ioctl() - performs an I/O control function.
SYNOPSIS
#include “tip675.h”
int ioctl
(int fd,
int request,
int arg
)
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.
For details of supported ioctl functions see VxWorks Reference Manual: VxWorks Programmer’s
Guide: I/O system.
PARAMETER
fd This file descriptor specifies the device to be used. The file descriptor has been returned by the
open() function.
request
This argument specifies the function that shall be executed.
Following functions are defined:
Function Description
FIO_T675_SET_DIR Set direction of I/O lines
FIO_T675_INSTALL_ISF Install user supplied I/O service function at
specified I/O line
FIO_T675_REMOVE_ISF Remove user supplied I/O service function from
specified I/O line
FIO_T675_ENA_EXCLK Enable simultaneous update feature
FIO_T675_DIS_EXCLK Disable simultaneous update feature
FIO_T675_READ Read from input buffer
FIO_T675_WRITE Write to output buffer

TIP675-SW-42 – VxWorks Device Driver Page 18 of 31
arg This parameter depends on the selected function (request). How to use this parameter is
described below with the function.
RETURNS
Function dependent value (described with the function) or ERROR if the function fails an error code
will be stored in errno.
ERROR CODES
The error codes are stored in errno and 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 - ioctl()

TIP675-SW-42 – VxWorks Device Driver Page 19 of 31
4.3.1 FIO_T675_SET_DIR
NAME
FIO_T675_SET_DIR – Set direction of I/O lines
DESCRIPTION
With this ioctl function each of the 48 I/O line may be individually set as input or output. After driver
startup all I/O lines are set to be inputs. To set a line to be input, set the corresponding bit in the mask
to 1.
The direction mask (T675_DIRECTION_STR) will be passed in the ioctl argument arg to the driver.
typedef struct
{unsigned short dir_1_16;
unsigned short dir_17_32;
unsigned short dir_33_48;
} T675_DIRECTION_STR;
dir_1_16
Specifies the line direction for I/O-line 1 up to 16. (Line 1 is assigned to bit 0, line 2 to bit 1 and
so on.)
dir_17_32
Specifies the line direction for I/O-line 17 up to 32. (Line 17 is assigned to bit 0, line 18 to bit 1
and so on.)
dir_33_48
Specifies the line direction for I/O-line 33 up to 48. (Line 33 is assigned to bit 0, line 34 to bit 1
and so on.)

TIP675-SW-42 – VxWorks Device Driver Page 20 of 31
EXAMPLE
#include "tip675.h"
…
int fd;
int retval;
T675_DIRECTION_STR dBuf;
…
/*----------------------------------
Set direction: Line 1-24 – output
Line 25-32 – input
----------------------------------*/
dBuf.out_1_16 = 0xFFFF;
dBuf.out_17_32 = 0x00FF;
dBuf.out_33_48 = 0x0000;
retval = ioctl(fd, FIO_T675_SET_DIR, (int)&dBuf);
if (retval == ERROR)
{
/* handle function specific error conditions */
}
…
ERRORS
No function specific error codes.
SEE ALSO
ioLib, basic I/O routine - ioctl(), VxWorks Programmer's Guide: I/O System.