Tews Technologies TPMC866-SW-42 User manual

The Embedded I/O Company
TPMC866-SW-42
VxWorks Device Driver
8 Channel Serial PMC
Version 2.0.x
User Manual
Issue 2.0.1
September 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

TPMC866-SW-42 - VxWorks Device Driver Page 2 of 37
TPMC866-SW-42
VxWorks Device Driver
8 Channel Serial Interface PMC Module
Supported Modules:
TPMC866-10
TPMC866-11
TPMC866-12
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.
1998-2008 by TEWS TECHNOLOGIES GmbH
Issue Description Date
1.0 First Issue April 1998
1.1 Advanced Error Handling January 1999
1.2 New Driver Initialization Function July 1999
1.3 FIFO Function adapted for TPMC866-12 July 1999
1.4 Support for Intel x86 based Targets June 2000
1.5 Parameter for tp866drv() expanded February 2001
1.6 General Revision January 2004
2.0.0 Installation section and driver start changed.
Ioctl() description extended. June 19, 2006
2.0.1 General Revision, New Address TEWS LLC September 17, 2008

TPMC866-SW-42 - VxWorks Device Driver Page 3 of 37
Table of Content
1 INTRODUCTION.........................................................................................................4
2 INSTALLATION..........................................................................................................5
2.1 Include device driver in Tornado IDE project ..............................................................................5
2.2 Special installation for Intel x86 based targets............................................................................5
2.3 System resource requirement.......................................................................................................6
3 I/O SYSTEM FUNCTIONS..........................................................................................7
3.1 tpmc866Drv() ...................................................................................................................................7
3.2 tpmc866DevCreate() .......................................................................................................................9
4 I/O INTERFACE FUNCTIONS..................................................................................13
4.1 open() .............................................................................................................................................13
4.2 close().............................................................................................................................................15
4.3 read() ..............................................................................................................................................17
4.4 write() .............................................................................................................................................19
4.5 ioctl() ..............................................................................................................................................21
4.5.1 FIOBAUDRATE .............................................................................................................23
4.5.2 FIOFIFO.........................................................................................................................24
4.5.3 FIODATABITS ...............................................................................................................26
4.5.4 FIOSTOPBITS...............................................................................................................27
4.5.5 FIOPARITY....................................................................................................................28
4.5.6 FIOENABLEHWHS........................................................................................................29
4.5.7 FIODISABLEHWHS.......................................................................................................30
4.5.8 FIOSETBREAK..............................................................................................................31
4.5.9 FIOCLEARBREAK.........................................................................................................32
4.5.10 FIOCHECKBREAK........................................................................................................33
4.5.11 FIOCHECKERRORS.....................................................................................................34
4.5.12 FIORECONFIGURE......................................................................................................35
5 APPENDIX................................................................................................................36
5.1 Predefined Symbols......................................................................................................................36
5.2 Additional Error Codes.................................................................................................................37

TPMC866-SW-42 - VxWorks Device Driver Page 4 of 37
1 Introduction
The TPMC866-SW-42 VxWorks device driver allows the operation of the TPMC866 serial PMC
conforming to the VxWorks I/O system specification. This includes a device-independent basic I/O
interface with open(),close(),read(),write() and ioctl() functions and a buffered I/O interface (fopen(),
fprintf(),fscanf(), ...).
The TPMC866 device driver includes the following functions supported by the VxWorks tty driver
support library:
ring buffering of input and output
raw mode
optional line mode with backspace and line-delete functions
optional processing of X-on/X-off
optional RETURN/LINEFEED conversion
optional echoing of input characters
optional stripping of the parity bit from 8 bit input
optional special characters for shell abort and system restart
Additionally, the following functions are supported:
select FIFO triggering point
use 5...8 bit data words
use 1, 1.5 or 2 stop bits
optional even or odd parity
enable/disable hardware handshake (only in FIFO mode)
The TPMC866-SW-42 supports the modules listed below:
TPMC866-10 8 channel RS232 serial interface with front
I/O and P14 I/O (PMC)
TPMC866-11 8 channel RS422 serial interface with front
I/O and P14 I/O (PMC)
TPMC866-12 8 channel serial interface RS422, RS485
(FD/HD) with front I/O and P14 I/O (PMC)
To get more information about the features and use of TPMC866 devices it is recommended to read
the manuals listed below.
TPMC866 User manual
TPMC866 Engineering Manual
ST16C654 and XR16C864 UART Controller Manual

TPMC866-SW-42 - VxWorks Device Driver Page 5 of 37
2Installation
Following files are located on the distribution media:
Directory path ‘TPMC866-SW-42’:
tpmc866drv.c TPMC866 device driver source
tpmc866def.h TPMC866 driver include file
tpmc866.h TPMC866 include file for driver and application
tpmc866pci.c TPMC866 PCI MMU mapping for Intel x86 based targets
tpmc866exa.c Example application
include/tdhal.h Hardware dependent interface functions and definitions
TPMC866-SW-42-2.0.1.pdf PDF copy of this manual
ChangeLog.txt Release history
Release.txt Release information
2.1 Include device driver in Tornado IDE project
For Including the TPMC866-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: ./TPMC866)
(2) Add the device driver’s 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.
2.2 Special installation for Intel x86 based targets
The TPMC866 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_FAMILY. If the content of this macro is equal to I80X86 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 device memory spaces can’t be accessed.
To solve this problem an MMU mapping entry has to be added for the required TPMC866 PCI memory
spaces prior the MMU initialization (usrMmuInit()) is done.
The C source file tpmc866pci.c contains the function tp866PciInit(). This routine finds out all
TPMC866 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()).
The right place to call the function tp866PciInit() is at the end of the function sysHwInit() in sysLib.c (it
can be opened from the project Files window).

TPMC866-SW-42 - VxWorks Device Driver Page 6 of 37
Be sure that the function is called prior to MMU initialization otherwise the TPMC866 PCI spaces
remains unmapped and an access fault occurs during driver initialization.
Please insert the following call at a suitable place in sysLib.c:
tp866PciInit();
Modifying the sysLib.c file will change the sysLib.c in the BSP path. Remember this for future
projects and recompilations.
2.3 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 < 1KB
Stack < 2 KB ---
Semaphores 1 ---
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.

TPMC866-SW-42 - VxWorks Device Driver Page 7 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 tpmc866Drv()
NAME
tpmc866Drv() - installs the TPMC866 driver in the I/O system.
SYNOPSIS
#include “tpmc866.h”
STATUS tpmc866Drv(void)
DESCRIPTION
This function searches for devices on the PCI bus, allocates driver and device resources, initializes
them and installs the TPMC866 driver in the I/O system.
A call to 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 "tpmc866.h”
…
STATUS result;
…
/*-------------------
Initialize Driver
-------------------*/
result = tpmc866Drv();
if (result == ERROR)
{
/* Error handling */
}
…

TPMC866-SW-42 - VxWorks Device Driver Page 8 of 37
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
ENXIO No TPMC866 found
SEE ALSO
VxWorks Programmer’s Guide: I/O System

TPMC866-SW-42 - VxWorks Device Driver Page 9 of 37
3.2 tpmc866DevCreate()
NAME
tpmc866DevCreate() - adds TPMC866 device to the system and initializes device hardware with the
selected configuration
SYNOPSIS
STATUS tpmc866DevCreate
(char *name,
int channel,
int rdBufSize,
int wrtBufSize,
TP866_CHANCONF *devconf
)
DESCRIPTION
This routine creates a device on a specified serial channel that will be serviced by the TPMC866
driver. This function must be called before performing any I/O request to this device.
PARAMETER
name This string specifies the name of the device.
channel
This index specifies the channel number to use. The channel numbers will be assigned in the
order the VxWorks pciFindDevice() function will find the devices.
rdBufSize
This value specifies the size of the receive software FIFO.
wrtBufSize
This value specifies the size of the transmit software FIFO.

TPMC866-SW-42 - VxWorks Device Driver Page 10 of 37
devConf
This parameter points to a structure (TP866_CHANCONF) containing the default configuration
of the channel. (This function will be used for reconfigurations).
The structure (TP866_CHANCONF) has the following layout and is defined in tpmc866.h:
typedef struct
{unsigned int Baudrate;
unsigned int Options;
unsigned int FifoTrigRcv;
unsigned int FifoTrigTrm;
unsigned int Databits;
unsigned int Stopbits;
unsigned int Parity;
unsigned int Handshake;
unsigned int ModelType;
} TP866_CHANCONF;
Baudrate
Selects the initial baud rate of the channel - allowed values are (50 .. 460800)
Options
Selects the initial VxWorks driver options
FifoTrigRcv
Selects the receiver FIFO trigger level
(TPMC866-10/-11: use the predefined values in tpmc866.h)
(TPMC866-12: allowed values are 0..127 and TP866F_NO)
If one of the FIFO trigger levels is set to TP866F_NO, the other level is also disabled.
FifoTrigTrm
Selects the transmitter FIFO trigger level
(TPMC866-10/-11: use the predefined values in tpmc866.h)
(TPMC866-12: allowed values are 0..127 and TP866F_NO)
If one of the FIFO trigger levels is set to TP866F_NO, the other level is also disabled.
Databits
Selects the number of data bits in one data word (use predefined values in tpmc866.h)
Stopbits
Selects the number of stop bits in one data word (use predefined values in tpmc866.h)
Parity Selects the parity checking mode (use predefined values in tpmc866.h)
Handshake
If hardware handshake is enabled or disabled (after startup) select YES to use the
handshake lines, otherwise NO. This parameter is ignored for TPMC866-11/-12.

TPMC866-SW-42 - VxWorks Device Driver Page 11 of 37
ModelType
Specifies the type of the TPMC866 (-10/-11/-12), if software detection fails. Software
detection may fail in some systems, if the Local Configuration Space of the TPMC866 is
not placed on 0x100 aligned addresses.
Allowed parameters are:
value description
TPMC866_10 Module is treated as TPMC866-10
TPMC866_11 Module is treated as TPMC866-11
TPMC866_12 Module is treated as TPMC866-12
EXAMPLE
#include "tpmc866.h”
STATUS result;
TP866_CHANCONF tp866setup =
{
115200, /* 115200 Baud */
OPT_TERMINAL, /* Terminal options */
TP866F_NO, TP866F_NO, /* no FIFO */
TP866DB_8, TP866SB_10, TP866NOP, /* 8/1/0 Data/Stop/Pari */
NO, /* no handshake */
TPMC866_10 /* if autodetection fails, */
/* treat it as TPMC866-10 */
};
/*-------------------------------------------------------------
Create the device "/tp866/1" on channel 0 with read and write
buffer sizes of 512 bytes.
Baudrate: 115200Baud
Options: Terminal
FIFOs: disabled
Databits: 8
Stopbits: 1
Parity: off
Handshake: off
ModelType: TPMC866-10
-------------------------------------------------------------*/
result = tp866DevCreate ("/tp866/1", 0, 512, 512, &tp866setup);
if (result == ERROR)
{
/* Error handling */
}

TPMC866-SW-42 - VxWorks Device Driver Page 12 of 37
RETURNS
OK or ERROR (if the driver is not installed, or the channel is invalid or the device already exists)

TPMC866-SW-42 - VxWorks Device Driver Page 13 of 37
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,
int flags,
int mode
)
DESCRIPTION
Before I/O can be performed to the TPMC866 device, a file descriptor must be opened by invoking the
basic I/O function open().
PARAMETER
name Specifies the device which shall be opened
flags Not used
mode Not used

TPMC866-SW-42 - VxWorks Device Driver Page 14 of 37
EXAMPLE
int fd;
…
/*-----------------------------------------------------------
Open the device named "/tp866/1" for I/O
-----------------------------------------------------------*/
fd = open("/tp866/1", 0, 0);
if (fd == ERROR)
{
/* Handle errror */
}
…
RETURNS
A device descriptor number or ERROR (if the device does not exist or no device descriptors are
available)
SEE ALSO
ioLib, basic I/O routine - open()

TPMC866-SW-42 - VxWorks Device Driver Page 15 of 37
4.2 close()
NAME
close() – close a device or file
SYNOPSIS
STATUS 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;
STATUS retval;
…
/*----------------
close the device
----------------*/
retval = close(fd);
RETURNS
OK or ERROR. If the function fails, an error code will be stored in errno.

TPMC866-SW-42 - VxWorks Device Driver Page 16 of 37
ERROR CODES
The error code 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()

TPMC866-SW-42 - VxWorks Device Driver Page 17 of 37
4.3 read()
NAME
read() – read data from a specified device.
SYNOPSIS
int read
(int fd,
char *buffer,
size_t maxbytes
)
DESCRIPTION
This function can be used to read data from the device.
PARAMETER
fd This file descriptor specifies the device to be used. The file descriptor has been returned by the
open() function.
buffer This argument points to a user supplied buffer. The returned data will be filled into this buffer.
maxbytes
This parameter specifies the maximum number of read bytes (buffer size).

TPMC866-SW-42 - VxWorks Device Driver Page 18 of 37
EXAMPLE
#define BUFSIZE 100
…
int fd;
char buffer[BUFSIZE];
int retval;
…
/*------------------------------
Read data from specified device
------------------------------*/
retval = read(fd, buffer, BUFSIZE);
if (retval != ERROR)
{
printf(“%d bytes read\n”, retval);
}
else
{
/* handle the read error */
}
RETURNS
Number of bytes read or ERROR. If the function fails an error code will be stored in errno.
SEE ALSO
ioLib, basic I/O routine - read()

TPMC866-SW-42 - VxWorks Device Driver Page 19 of 37
4.4 write()
NAME
write() – write data from a buffer to a specified device.
SYNOPSIS
int write
(int fd,
char *buffer,
size_t nbytes
)
DESCRIPTION
This function can be used to write data to the device.
PARAMETER
fd This file descriptor specifies the device to be used. The file descriptor has been returned by the
open() function.
buffer This argument points to a user supplied buffer. The data of the buffer will be written to the
device.
nbytesThis parameter specifies the number of bytes to be written.

TPMC866-SW-42 - VxWorks Device Driver Page 20 of 37
EXAMPLE
int fd;
char buffer[] = “Hello World”;
int retval;
…
/*--------------------------------
Write data to a specified device
--------------------------------*/
retval = write(fd, buffer, strlen(buffer));
if (retval != ERROR)
{
printf(“%d bytes written\n”, retval);
}
else
{
/* handle the write error */
}
RETURNS
Number of bytes written or ERROR. If the function fails an error code will be stored in errno.
SEE ALSO
ioLib, basic I/O routine - write()