tdrv009-sw-42 - bentech...
TRANSCRIPT
The Embedded I/O Company
TDRV009-SVxWorks Device
High Speed Synch/Asynch
Version 2.0.x
User ManuIssue 2.0.1
March 2010
TEWS TECHNOLOGIES GAm Bahnhof 7 25469 Ha
Phone: +49 (0) 4101 4058 0 Fax: +49e-mail: [email protected] www.tews
W-42Driver
Serial Interface
al
mbHlstenbek, Germany(0) 4101 4058 19.com
TDRV009-SW-42 – VxWorks Device Driver Page 2 of 139
TDRV009-SW-42
VxWorks Device Driver
High Speed Synch/Asynch Serial Interface
Supported Modules:TPMC363TPMC863TAMC863TCP863
This document contains information, which isproprietary to TEWS TECHNOLOGIES GmbH. Anyreproduction without written permission is forbidden.
TEWS TECHNOLOGIES GmbH has made anyeffort to ensure that this manual is accurate andcomplete. However TEWS TECHNOLOGIES GmbHreserves the right to change the product describedin this document at any time without notice.
TEWS TECHNOLOGIES GmbH is not liable for anydamage arising out of the application or use of thedevice described herein.
2007-2010 by TEWS TECHNOLOGIES GmbH
Issue Description Date
1.0.0 First Issue February 5, 2007
1.1.0 Clock Multiplier changed (X4 instead of X8) April 4, 2007
1.2.0 Interrupt Wait Ioctl function added June 20, 2007
1.2.1 Support for TAMC863 added April 8, 2008
1.2.2 Return value of write() function corrected, functionality of the Validfield in TDRV009_DATA_BUFFER clarified.
February 13, 2009
2.0.0 Support for VxBus and API description added March 2, 2010
2.0.1 Legacy vs. VxBus Driver modified March 26, 2010
TDRV009-SW-42 – VxWorks Device Driver Page 3 of 139
Table of Contents1 INTRODUCTION......................................................................................................... 52 INSTALLATION.......................................................................................................... 6
2.1 Legacy vs. VxBus Driver ................................................................................................................72.2 VxBus Driver Installation ...............................................................................................................7
2.2.1 Direct BSP Builds.................................................................................................................82.3 Legacy Driver Installation ..............................................................................................................9
2.3.1 Include device driver in VxWorks projects ...........................................................................92.3.2 Special installation for Intel x86 based targets ....................................................................92.3.3 BSP dependent adjustments .............................................................................................10
2.4 System resource requirement .....................................................................................................10
3 API DOCUMENTATION ........................................................................................... 113.1 General Functions.........................................................................................................................11
3.1.1 tdrv009Open() ....................................................................................................................113.1.2 tdrv009Close()....................................................................................................................13
3.2 Device Access Functions.............................................................................................................153.2.1 tdrv009Read.......................................................................................................................153.2.2 tdrv009FrameRead ............................................................................................................173.2.3 tdrv009Write.......................................................................................................................203.2.4 tdrv009FrameWrite ............................................................................................................223.2.5 tdrv009WriteBufDone.........................................................................................................253.2.6 tdrv009SetOperationMode.................................................................................................273.2.7 tdrv009GetOperationMode ................................................................................................353.2.8 tdrv009SetBaudrate ...........................................................................................................433.2.9 tdrv009SetReceiverState ...................................................................................................453.2.10 tdrv009ClearRxBuffer ....................................................................................................473.2.11 tdrv009RtsSet ................................................................................................................493.2.12 tdrv009RtsClear .............................................................................................................513.2.13 tdrv009CtsGet................................................................................................................533.2.14 tdrv009DtrSet.................................................................................................................553.2.15 tdrv009DtrClear .............................................................................................................573.2.16 tdrv009DsrGet ...............................................................................................................593.2.17 tdrv009SetExternalXtal ..................................................................................................613.2.18 tdrv009RegisterRead.....................................................................................................633.2.19 tdrv009RegisterWrite .....................................................................................................653.2.20 tdrv009EepromRead......................................................................................................673.2.21 tdrv009EepromWrite......................................................................................................693.2.22 tdrv009RingbufferRegister.............................................................................................713.2.23 tdrv009RingbufferUnregister..........................................................................................773.2.24 tdrv009WaitForInterrupt.................................................................................................79
4 LEGACY I/O SYSTEM FUNCTIONS........................................................................ 814.1 tdrv009Drv() ...................................................................................................................................814.2 tdrv009DevCreate() .......................................................................................................................834.3 tdrv009PciInit() ..............................................................................................................................86
5 I/O FUNCTIONS ....................................................................................................... 875.1 open() .............................................................................................................................................875.2 close().............................................................................................................................................895.3 read() ..............................................................................................................................................915.4 write() .............................................................................................................................................93
TDRV009-SW-42 – VxWorks Device Driver Page 4 of 139
5.5 ioctl() ..............................................................................................................................................955.5.1 TDRV009_SET_OPERATION_MODE ..............................................................................975.5.2 TDRV009_GET_OPERATION_MODE............................................................................1045.5.3 TDRV009_SET_BPS .......................................................................................................1105.5.4 TDRV009_FRAME_READ...............................................................................................1115.5.5 TDRV009_FRAME_WRITE .............................................................................................1135.5.6 TDRV009_WRITEBUF_DONE ........................................................................................1155.5.7 TDRV009_RINGBUFFER_REGISTER ...........................................................................1165.5.8 TDRV009_RINGBUFFER_UNREGISTER ......................................................................1215.5.9 TDRV009_SET_RECEIVER_STATE ..............................................................................1225.5.10 TDRV009_CLEAR_RX_BUFFER ...............................................................................1235.5.11 TDRV009_EEPROM_WRITE......................................................................................1245.5.12 TDRV009_EEPROM_READ .......................................................................................1265.5.13 TDRV009_RTS_SET...................................................................................................1285.5.14 TDRV009_RTS_CLEAR..............................................................................................1295.5.15 TDRV009_CTS_GET ..................................................................................................1305.5.16 TDRV009_DTR_SET...................................................................................................1315.5.17 TDRV009_DTR_CLEAR..............................................................................................1325.5.18 TDRV009_DSR_GET ..................................................................................................1335.5.19 TDRV009_SET_EXT_XTAL........................................................................................1345.5.20 TDRV009_REGREAD .................................................................................................1355.5.21 TDRV009_REGWRITE................................................................................................1365.5.22 TDRV009_WAITFORINTERRUPT..............................................................................138
TDRV009-SW-42 – VxWorks Device Driver Page 5 of 139
1 IntroductionThe TDRV009-SW-42 release contains independent driver sources for the old legacy (pre-VxBus) andthe new VxBus-enabled driver model. The VxBus-enabled driver is recommended for newdevelopments with later VxWorks 6.x releases and mandatory for VxWorks SMP systems.
Both drivers, legacy and VxBus, share the same application programming interface (API) and device-independent basic I/O interface with open(), close() and ioctl() functions. The basic I/O interface is onlyfor backward compatibility with existing applications and should not be used for new developments.
Both drivers invoke a mutual exclusion and binary semaphore mechanism to prevent simultaneousrequests by multiple tasks from interfering with each other.
The TDRV009-SW-42 device driver supports the following features:
setup and configure a serial channel send data buffers receive data buffers (buffer based / character based)
The TDRV009-SW-42 supports the modules listed below:
TPMC863 4 Channel High Speed Synch/AsynchSerial Interface
PMC
TPMC363 4 Channel High Speed Synch/AsynchSerial Interface
PMC, Conduction Cooled
TAMC863 4 Channel High Speed Synch/AsynchSerial Interface
Advanced Mezzanine Card
TCP863 4 Channel High Speed Synch/AsynchSerial Interface
CompactPCI
In this document all supported modules and devices will be called TDRV009. Specials for acertain device will be advised.
To get more information about the features and use of supported devices it is recommended to readthe manuals listed below.
TPMC863 (or compatible) User manual
TPMC863 (or compatible) Engineering Manual
TDRV009-SW-42 – VxWorks Device Driver Page 6 of 139
2 InstallationFollowing files are located on the distribution media:
Directory path ‘TDRV009-SW-42’:
TDRV009-SW-42-2.0.1.pdf PDF copy of this manualTDRV009-SW-42-VXBUS.zip Zip compressed archive with VxBus driver sourcesTDRV009-SW-42-LEGACY.zip Zip compressed archive with legacy driver sourcesChangeLog.txt Release historyRelease.txt Release information
The archive TDRV009-SW-42-VXBUS.zip contains the following files and directories:
Directory path ‘./tews/tdrv009’:
tdrv009drv.c TDRV009 device driver sourcetdrv009def.h TDRV009 driver include filecommCtrl.h Include file for controller chiptdrv009.h TDRV009 include file for driver and applicationtdrv009api.c TDRV009 API filenode.c Linked list support functionsnode.h Linked list support functions header fileMakefile Driver Makefile40tdrv009.cdf Component description file for VxWorks development toolstdrv009.dc Configuration stub file for direct BSP buildstdrv009.dr Configuration stub file for direct BSP buildsinclude/tvxbHal.h Hardware dependent interface functions and definitionsapps/tdrv009exa.c Example application
The archive TDRV009-SW-42-LEGACY.zip contains the following files and directories:
Directory path ‘./tdrv009’:
tdrv009drv.c TDRV009 device driver sourcetdrv009def.h TDRV009 driver include filecommCtrl.h Include file for controller chiptdrv009.h TDRV009 include file for driver and applicationtdrv009pci.c TDRV009 PCI MMU mapping for Intel x86 based targetstdrv009exa.c Example applicationnode.c Linked list support functionsnode.h Linked list support functions header fileinclude/tdhal.h Hardware dependent interface functions and definitions
TDRV009-SW-42 – VxWorks Device Driver Page 7 of 139
2.1 Legacy vs. VxBus DriverIn later VxWorks 6.x releases, the old VxWorks 5.x legacy device driver model was replaced byVxBus-enabled device drivers. Legacy device drivers are tightly coupled with the BSP and the boardhardware. The VxBus infrastructure hides all BSP and hardware differences under a well definedinterface, which improves the portability and reduces the configuration effort. A further advantage isthe improved performance of API calls by using the method interface and bypassing the VxWorksbasic I/O interface.
VxBus-enabled device drivers are the preferred driver interface for new developments.
The checklist below will help you to make a decision which driver model is suitable and possible foryour application:
Legacy Driver VxBus Driver
VxWorks 5.x releases
VxWorks 6.5 and earlierreleases
VxWorks 6.x releases withoutVxBus PCI bus support
VxWorks 6.6 and later releaseswith VxBus PCI bus
SMP systems (only the VxBusdriver is SMP safe!)
TEWS TECHNOLOGIES recommends not using the VxBus Driver before VxWorks release 6.6.In previous releases required header files are missing and the support for 3rd-party drivers maynot be available.
2.2 VxBus Driver InstallationBecause Wind River doesn’t provide a standard installation method for 3rd party VxBus device driversthe installation procedure needs to be done manually.
In order to perform a manual installation extract all files from the archive TDRV009-SW-42-VXBUS.zipto the typical 3rd party directory installDir/vxworks-6.x/target/3rdparty (whereas installDir must besubstituted by the VxWorks installation directory).
After successful installation the TDRV009 device driver is located in the vendor and driver-specificdirectory installDir/vxworks-6.x/target/3rdparty/tews/tdrv009.
At this point the TDRV009 driver is not configurable and cannot be included with the kernelconfiguration tool in a Wind River Workbench project. To make the driver configurable the driver libraryfor the desired processer (CPU) and build tool (TOOL) must be built in the following way:
(1) Open a VxWorks development shell (e.g. C:\WindRiver\wrenv.exe -p vxworks-6.7)
(2) Change into the driver installation directoryinstallDir/vxworks-6.x/target/3rdparty/tews/tdrv009
(3) Invoke the build command for the required processor and build toolmake CPU=cpuName TOOL=tool
For Windows hosts this may look like this:
C:> cd \WindRiver\vxworks-6.7\target\3rdparty\tews\tdrv009
TDRV009-SW-42 – VxWorks Device Driver Page 8 of 139
C:> make CPU=PENTIUM4 TOOL=diab
To compile SMP-enabled libraries, the argument VXBUILD=SMP must be added to the command line.
C:> make CPU=PENTIUM4 TOOL=diab VXBUILD=SMP
To integrate the TDRV009 driver with the VxWorks development tools (Workbench), the componentconfiguration file 40tdrv009.cdf must be copied to the directoryinstallDir/vxworks-6.x/target/config/comps/VxWorks.
C:> cd \WindRiver\vxworks-6.7\target\3rdparty\tews\tdrv009C:> copy 40tdrv009.cdf \Windriver\vxworks-6.7\target\config\comps\vxWorks
In VxWorks 6.7 and newer releases the kernel configuration tool scans the CDF file automatically andupdates the CxrCat.txt cache file to provide component parameter information for the kernelconfiguration tool as long as the timestamp of the copied CDF file is newer than the one of theCxrCat.txt. If your copy command preserves the timestamp, force to update the timestamp by a utility,such as touch.
In earlier VxWorks releases the CxrCat.txt file may not be updated automatically. In this case, removeor rename the original CxrCat.txt file and invoke the make command to force recreation of this file.
C:> cd \Windriver\vxworks-6.7\target\config\comps\vxWorksC:> del CxrCat.txtC:> make
After successful completion of all steps above and restart of the Wind River Workbench, the TDRV009driver can be included in VxWorks projects by selecting the “TEWS TDRV009 Driver“ component inthe “hardware (default) - Device Drivers” folder with the kernel configuration tool.
2.2.1 Direct BSP Builds
In development scenarios with the direct BSP build method without using the Workbench or the vxprjcommand-line utility, the TDRV009 configuration stub files must be copied to the directoryinstallDir/vxworks-6.x/target/config/comps/src/hwif. Afterwards the vxbUsrCmdLine.c file must beupdated by invoking the appropriate make command.
C:> cd \WindRiver\vxworks-6.7\target\3rdparty\tews\tdrv009C:> copy tdrv009.dc \Windriver\vxworks-6.7\target\config\comps\src\hwifC:> copy tdrv009.dr \Windriver\vxworks-6.7\target\config\comps\src\hwif
C:> cd \Windriver\vxworks-6.7\target\config\comps\src\hwifC:> make vxbUsrCmdLine.c
TDRV009-SW-42 – VxWorks Device Driver Page 9 of 139
2.3 Legacy Driver Installation
2.3.1 Include device driver in VxWorks projects
For including the TDRV009-SW-42 device driver into a VxWorks project (e.g. Tornado IDE orWorkbench) follow the steps below:
(1) Extract all files from the archive TDRV009-SW-42-LEGACY.zip to your project directory.
(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 in the tdrv009 directory 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 VxWorks User’sGuide (e.g. Tornado, Workbench, etc.)
2.3.2 Special installation for Intel x86 based targets
The TDRV009 device driver is fully adapted for Intel x86 based targets. This is done by conditionalcompilation directives inside the source code and controlled by the VxWorks global defined macroCPU_FAMILY. If the content of this macro is equal to I80X86 special Intel x86 conforming code andfunction calls will be included.
The second problem for Intel x86 based platforms can’t be solved by conditional compilationdirectives. Due to the fact that some Intel x86 BSP’s doesn’t map PCI memory spaces of deviceswhich are not used by the BSP, the required device memory spaces can’t be accessed.
To solve this problem a MMU mapping entry has to be added for the required TDRV009 PCI memoryspaces prior the MMU initialization (usrMmuInit()) is done.
The C source file tdrv009pci.c contains the function tdrv009PciInit(). This routine finds out allTDRV009 devices and adds MMU mapping entries for all used PCI memory spaces. Please insert acall to this function after the PCI initialization is done and prior to MMU initialization (usrMmuInit()).
The right place to call the function tdrv009PciInit() is at the end of the function sysHwInit() in sysLib.c(it can be opened from the project Files window).
Be sure that the function is called prior to MMU initialization otherwise the TDRV009 PCI spacesremains unmapped and an access fault occurs during driver initialization.
Please insert the following call at a suitable place in sysLib.c:
tdrv009PciInit();
Modifying the sysLib.c file will change the sysLib.c in the BSP path. Remember this for futureprojects and recompilations.
TDRV009-SW-42 – VxWorks Device Driver Page 10 of 139
2.3.3 BSP dependent adjustments
The driver includes a file called include/tdhal.h which contains functions and definitions for BSPadaptation. It may be necessary to modify them for BSP specific settings. Most settings can be madeautomatically by conditional compilation set by the BSP header files, but some settings must beconfigured manually. There are two ways of modification, first you can change the include/tdhal.h anddefine the corresponding definition and its value, or you can do it, using the command line option –D.
There are 3 offset definitions (USERDEFINED_MEM_OFFSET, USERDEFINED_IO_OFFSET, andUSERDEFINED_LEV2VEC) that must be configured if a corresponding warning message appearsduring compilation. These definitions always need values. Definition values can be assigned bycommand line option -D<definition>=<value>.
definition description
USERDEFINED_MEM_OFFSET The value of this definition must be set to the offsetbetween CPU-Bus and PCI-Bus Address for PCImemory space access
USERDEFINED_IO_OFFSET The value of this definition must be set to the offsetbetween CPU-Bus and PCI-Bus Address for PCI I/Ospace access
USERDEFINED_LEV2VEC The value of this definition must be set to thedifference of the interrupt vector (used to connect theISR) and the interrupt level (stored to the PCI header )
Another definition allows a simple adaptation for BSPs that utilize a pciIntConnect() function toconnect shared (PCI) interrupts. If this function is defined in the used BSP, the definition ofUSERDEFINED_SEL_PCIINTCONNECT should be enabled. The definition by command line option ismade by -D<definition>.
Please refer to the BSP documentation and header files to get information about the interruptconnection function and the required offset values.
2.4 System resource requirementThe table gives an overview over the system resources that will be needed by the driver.
Resource Driver requirement Devices requirement
Memory < 1 KB depends on FIFO size
Stack < 1 KB ---
Memory and Stack usage may differ from system to system, depending on the used compilerand 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 applicationand driver exceed these limits, increase the according values in your project.
TDRV009-SW-42 – VxWorks Device Driver Page 11 of 139
3 API Documentation
3.1 General Functions
3.1.1 tdrv009Open()
Name
tdrv009Open() – open a device.
Synopsis
TDRV009_DEV tdrv009Open(
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. The firstTDRV009 channel device is named “/tdrv009/0”, the second channel device is named“/tdrv009/1” and so on.
Example
#include “tdrv009.h”
TDRV009_DEV pDev;
/*** open file descriptor to device*/pDev = tdrv009Open(“/tdrv009/0”);if (pDev == NULL){
/* handle open error */}
TDRV009-SW-42 – VxWorks Device Driver Page 12 of 139
RETURNS
A device descriptor pointer, 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.
TDRV009-SW-42 – VxWorks Device Driver Page 13 of 139
3.1.2 tdrv009Close()
Name
tdrv009Close() – close a device.
Synopsis
int tdrv009Close(
TDRV009_DEV pDev)
Description
This function closes previously opened devices.
Parameters
pDev
This value specifies the file descriptor pointer to the hardware module retrieved by a call to thecorresponding open-function.
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int result;
/*** close file descriptor to device*/result = tdrv009Close(pDev);if (result < 0){
/* handle close error */}
TDRV009-SW-42 – VxWorks Device Driver Page 14 of 139
RETURNS
Zero, or -1 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.
TDRV009-SW-42 – VxWorks Device Driver Page 15 of 139
3.2 Device Access Functions
3.2.1 tdrv009Read
Name
tdrv009Read – Read data from device
Synopsis
int tdrv009Read(
TDRV009_DEV pDev,unsigned char *pData,int nBytes
)
Description
This function reads data from the device. The data is returned on a byte basis, no frame information isreturned. The function returns immediately after copying either the available or the requested amountof data.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pData
This argument points to a user supplied buffer. The data will be copied into this buffer.
nBytes
This parameter specifies the maximum number of bytes to be read (buffer size).
TDRV009-SW-42 – VxWorks Device Driver Page 16 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;unsigned char buffer[100];
/*--------------------------------------------Read up to 100 bytes from TDRV009 channel--------------------------------------------*/
retval = tdrv009Read( pDev, buffer, 100 );if (retval != ERROR){
printf(“%d bytes read\n”, retval);printf(“data = %s\n”, buffer);
}else{
/* Handle Error */}
RETURNS
Number of bytes read or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid data buffer specified.
TDRV009-SW-42 – VxWorks Device Driver Page 17 of 139
3.2.2 tdrv009FrameRead
Name
tdrv009FrameRead – Read data from a specified device
Synopsis
STATUS tdrv009FrameRead(
TDRV009_DEV pDev,TDRV009_DATA_BUFFER *pDataBuffer
)
Description
This function reads one data buffer from the internal receive buffer. The function will returnimmediately, if data is available. If no data is available, the function will wait until data arrives, or thespecified timeout occurs. The returned data buffer will be available until the next call to this I/O controlfunction.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pDataBuffer
This parameter is a pointer to a TDRV009_DATA_BUFFER structure describing the data toread.
typedef struct{
unsigned char *pData;unsigned long Length;unsigned long Valid;int Overflow;int Timeout;
} TDRV009_DATA_BUFFER;
pData
Pointer to the receive data section. This pointer directly references the driver’s internalreceive buffer. It points to the beginning of the corresponding data frame. Do not free theassociated memory section!
TDRV009-SW-42 – VxWorks Device Driver Page 18 of 139
Length
Number of valid data bytes for this data buffer.
Valid
This value specifies if the corresponding data buffer contains valid data, or if the readdata buffer also contains a “Frame End”. The given values can be binary OR’ed. Possiblevalues are:
Value Description
TDRV009_RXBUF_DATAVALID Current data block contains valid (unread)data.
TDRV009_RXBUF_FRAMEEND Current data block is the last one of areceived data frame.
Overflow
This value specifies if a buffer overrun has happened. The automatically stopped receiveris enabled again after the read access.
Timeout
This value specifies the maximum time to wait for incoming data. The timeout is specifiedin system ticks.
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;TDRV009_DATA_BUFFER DataBuf;
/*-------------------------------------------------Read a data buffer. Wait max. 120 ticks.-------------------------------------------------*/
DataBuf.Timeout = 120;
retval = tdrv009FrameRead(pDev, &DataBuf);if (retval == OK){
/* function succeeded */printf( “%d data bytes received.\n”, DataBuf.Length );if (DataBuf.Overflow){
printf( “Data was lost due to a buffer overflow.\n” );}
}else {
/* handle the write error */}
TDRV009-SW-42 – VxWorks Device Driver Page 19 of 139
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid data buffer specified. The supplied buffer pointer isNULL.
EBUSY The channel is currently busy with another write operation.
ENOMEM Not enough memory to queue this transmission.
EIO Failed to initialize the transmitter.
TDRV009-SW-42 – VxWorks Device Driver Page 20 of 139
3.2.3 tdrv009Write
Name
tdrv009Write – Write data from a buffer to a specified device
Synopsis
STATUS tdrv009Write(
TDRV009_DEV pDev,unsigned char *pData,int nBytes
)
Description
This function can be used to write data to the device. The function returns immediately to the callerafter queuing the data into the transmit descriptor list. Make sure that the supplied data buffer persistsuntil the transmission is completed. To check if the data buffer is completely processed, namely thedata has been transferred to the hardware FIFO, use the API function tdrv009WriteBufDone (seebelow).
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pData
This argument points to a user supplied buffer. The data of the buffer will be written to thedevice. The data buffer must be physically contiguous and accessible by the DMA controller.
nBytes
This parameter specifies the maximum number of bytes to write.
TDRV009-SW-42 – VxWorks Device Driver Page 21 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;unsigned char *pData;
/*------------------------------Write data to a TDRV009 device------------------------------*/
pData = (char*)cacheDmaMalloc( 12 );sprintf( (char*)pData, “Hello World” );
retval = tdrv009Write(pDev, buffer, 12);if (retval == OK){
printf(“Data queued for transmission.\n”);}else{
/* handle the write error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid data buffer specified.
TDRV009-SW-42 – VxWorks Device Driver Page 22 of 139
3.2.4 tdrv009FrameWrite
Name
tdrv009FrameWrite – Write data from a buffer to a specified device
Synopsis
STATUS tdrv009FrameWrite(
TDRV009_DEV pDev,TDRV009_TX_DATA_BUFFER *pDataBuffer
)
Description
This function transmits one data buffer. The function will return immediately after handing over thebuffer to the driver. It is possible to wait until the supplied data buffer is transferred to the hardwareFIFO. This can be done either by waiting on the specified semaphore, or by polling the statusparameter.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pDataBuffer
This parameter is a pointer to a TDRV009_TX_DATA_BUFFER structure describing the data tobe sent.
typedef struct{
unsigned char *pData;unsigned long Length;unsigned long Status;SEM_ID WaitSema;
} TDRV009_TX_DATA_BUFFER;
pData
Pointer to the data section containing the data to be transmitted. This buffer must bephysically coherent. Make sure that the data buffer is not modified during transmission.
Length
Number of data bytes for this data buffer.
TDRV009-SW-42 – VxWorks Device Driver Page 23 of 139
Status
This value contains the current status of this transmit data packet. Possible values are:Value Description
TDRV009_TXDATA_BUSY Data buffer is currently in use. Do notmodify it.
TDRV009_TXDATA_COMPLETED Data buffer is completed. The data isat least transferred into the hardwareFIFO.
WaitSema
This value holds a semaphore created by the user. This semaphore will be signaled afterthe data buffer is processed.
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval, result;unsigned char *pData;TDRV009_TX_DATA_BUFFER TxDataBuf;
/*-------------------------------------------------------Send a data buffer. Wait max. 120 ticks for completion-------------------------------------------------------*/
pData = (unsigned char*)cacheDmaMalloc( 20*sizeof(unsigned char) );sprintf((char*)pData, “Hello World!”);
TxDataBuf.Status = 0;TxDataBuf.WaitSema = semBCreate(SEM_Q_FIFO, SEM_EMPTY);TxDataBuf.pData = pData;TxDataBuf.Length = strlen((char*)pData);
retval = tdrv009FrameWrite(pDev, &TxDataBuf);if (retval == OK){
/*** function succeeded, wait for completion of the data packet.*/result = semTake( TxDataBuf.WaitSema, 120 );
TDRV009-SW-42 – VxWorks Device Driver Page 24 of 139
if (result == OK){
printf( “data buffer processed\n” );}else{
printf( “data buffer still busy\n” );}
}else{
/* handle the write error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid data buffer specified. The supplied buffer pointer isNULL.
EBUSY The channel is currently busy with another write operation.
ENOMEM Not enough memory to queue this transmission.
EIO Failed to initialize the transmitter.
TDRV009-SW-42 – VxWorks Device Driver Page 25 of 139
3.2.5 tdrv009WriteBufDone
Name
tdrv009WriteBufDone – Write data from a buffer to a specified device
Synopsis
STATUS tdrv009WriteBufDone(
TDRV009_DEV pDev,unsigned char *pData
)
Description
This function checks the current state of a transmit data buffer, which was previously handed over tothe driver using the tdrv009Write() function. If the buffer has already been processed (i.e. data wastransferred to the hardware FIFO), the function returns OK. If the buffer has not been processed, thefunction will return ERROR with an appropriate error code.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pData
This argument points to a user supplied buffer, which has previously been queued fortransmission using function tdrv009Write().
TDRV009-SW-42 – VxWorks Device Driver Page 26 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;unsigned char *pData;
/*-------------------------------------------------send TX data buffer-------------------------------------------------*/
pData = (char*)cacheDmaMalloc(…);…retval = tdrv009Write(pDev, pData, …);…
/*-------------------------------------------------check state of a TX data buffer-------------------------------------------------*/
retval = tdrv009WriteBufDone(pDev, buffer);if (retval == OK){
printf( “Data buffer completed.\n” );}else{
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid data buffer specified.
TDRV009-SW-42 – VxWorks Device Driver Page 27 of 139
3.2.6 tdrv009SetOperationMode
Name
tdrv009SetOperationMode – Configure channel operation mode
Synopsis
STATUS tdrv009SetOperationMode(
TDRV009_DEV pDev,TDRV009_OPERATION_MODE_STRUCT *pOperationMode
)
Description
This function configures the channel’s operation mode.
A call to this function must be done prior to any communication operation, because after driverstartup, the channel’s transceivers are disabled.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pOperationMode
This argument points to a TDRV009_OPERATION_MODE_STRUCT structure. It is necessaryto completely initialize the structure. This can be done by calling the API functiontdrv009GetOperationMode described below.
TDRV009-SW-42 – VxWorks Device Driver Page 28 of 139
typedef struct{
TDRV009_COMM_TYPE CommType;TDRV009_TRANSCEIVER_MODE TransceiverMode;TDRV009_ENABLE_DISABLE Oversampling;TDRV009_BRGSOURCE BrgSource;TDRV009_TXCSOURCE TxClkSource;unsigned long TxClkOutput;TDRV009_RXCSOURCE RxClkSource;TDRV009_CLKMULTIPLIER ClockMultiplier;unsigned long Baudrate;unsigned char ClockInversion;unsigned char Encoding;TDRV009_PARITY Parity;int Stopbits;int Databits;TDRV009_ENABLE_DISABLE UseTermChar;char TermChar;TDRV009_ENABLE_DISABLE HwHs;TDRV009_CRC Crc;
} TDRV009_OPERATION_MODE_STRUCT;
CommType
This parameter describes the general communication type for the specific channel. Possiblevalues are:
Value Description
TDRV009_COMMTYPE_ASYNC Asynchronous communication
TDRV009_COMMTYPE_HDLC_ADDR0 Standard HDLC communication withoutaddress recognition. Used for synchronouscommunication.
TDRV009_COMMTYPE_HDLC_TRANSP Extended Transparent mode. No protocolprocessing, channel works as simple bitcollector.
TDRV009-SW-42 – VxWorks Device Driver Page 29 of 139
TransceiverMode
This parameter describes the transceiver mode of the programmable multi-protocoltransceivers. Possible values are:
Value Description
TDRV009_TRNSCVR_NOT_USED Default V.11
TDRV009_TRNSCVR_RS530A EIA-530A (V.11 / V.10)
TDRV009_TRNSCVR_RS530 EIA-530 (V.11), also suitable for RS422
TDRV009_TRNSCVR_X21 X.21 (V.11)
TDRV009_TRNSCVR_V35 V.35 (V.35 / V.28)
TDRV009_TRNSCVR_RS449 EIA-449 (V.11)
TDRV009_TRNSCVR_V36 V.36 (V.11)
TDRV009_TRNSCVR_RS232 EIA-232 (V.28)
TDRV009_TRNSCVR_V28 V.28 (V.28)
TDRV009_TRNSCVR_NO_CABLE High impedance
Oversampling
This parameter enables or disables 16times oversampling, used for asynchronouscommunication. For communication with standard UARTs it is recommended to enable thisfeature. Valid values are:
Value Description
TDRV009_DISABLED The 16 times oversampling is not used.
TDRV009_ENABLED The 16 times oversampling is used.
BrgSource
This parameter specifies the frequency source used as input to the BRG (Baud RateGenerator). Valid values are:
Value Description
TDRV009_BRGSRC_XTAL1 XTAL1 oscillator is used for BRG input
TDRV009_BRGSRC_XTAL2 XTAL2 oscillator is used for BRG input
TDRV009_BRGSRC_XTAL3 XTAL3 oscillator is used for BRG input
TDRV009_BRGSRC_RXCEXTERN External clock at RxC input used for BRG input
TDRV009_BRGSRC_TXCEXTERN External clock at TxC input used for BRG input
TxClkSource
This parameter specifies the frequency source used as input to the transmit engine. Validvalues are:
Value Description
TDRV009_TXCSRC_BRG Baud Rate Generator output used for Tx clock
TDRV009_TXCSRC_BRGDIV16 BRG output divided by 16 used for Tx clock
TDRV009_TXCSRC_RXCEXTERN External clock at RxC input used for Tx clock
TDRV009_TXCSRC_TXCEXTERN External clock at TxC input used for Tx clock
TDRV009_TXCSRC_DPLL DPLL output used for Tx clock
TDRV009-SW-42 – VxWorks Device Driver Page 30 of 139
TxClkOutput
This parameter specifies which output lines are used to output the transmit clock, e.g. forsynchronous communication. The given values can be binary OR’ed. Valid values are:
Value Description
TDRV009_TXCOUT_TXC Transmit clock available at TxC output line
TDRV009_TXCOUT_RTS Transmit clock available at RTS output line
RxClkSource
This parameter specifies the frequency source used as input to the receive engine. Valid valuesare:
Value Description
TDRV009_RXCSRC_BRG Baud Rate Generator output used for Rx clock
TDRV009_RXCSRC_RXCEXTERN External clock at RxC input used for Rx clock
TDRV009_RXCSRC_DPLL DPLL output used for Rx clock
ClockMultiplier
This parameter specifies the multiplier used for BRG clock input. Valid values are:Value Description
TDRV009_CLKMULT_X1 Clock multiplier disabled
TDRV009_CLKMULT_X4 Selected input clock is multiplied by 4
Baudrate
This parameter specifies the desired frequency to be generated by the Baud Rate Generator(BRG), which can be used as clock input signal. The value is derived from the selectedclocksource. Please note that only specific values depending on the selected oscillator arevalid. This frequency is internally multiplied by 16, if oversampling shall be used.
ClockInversion
This parameter specifies the inversion of the transmit clock and/or the receive clock. This valuecan be binary OR’ed. Possible values are:
Value Description
TDRV009_CLKINV_NONE no clock inversion
TDRV009_CLKINV_TXC transmit clock is inverted
TDRV009_CLKINV_RXC receive clock is inverted
Encoding
This parameter specifies the data encoding used for communication. Valid values are:Value Description
TDRV009_ENC_NRZ NRZ data encoding
TDRV009_ENC_NRZI NRZI data encoding
TDRV009_ENC_FM0 FM0 data encoding
TDRV009_ENC_FM1 FM1 data encoding
TDRV009_ENC_MANCHESTER Manchester data encoding
TDRV009-SW-42 – VxWorks Device Driver Page 31 of 139
Parity
This parameter specifies the parity bit generation used for asynchronous communication. Validvalues are:
Value Description
TDRV009_PAR_DISABLED No parity generation is used.
TDRV009_PAR_EVEN EVEN parity bit
TDRV009_PAR_ODD ODD parity bit
TDRV009_PAR_SPACE SPACE parity bit (always insert ‘0’)
TDRV009_PAR_MARK MARK parity bit (always insert ‘1’)
Stopbits
This parameter specifies the number of stop bits to use for asynchronous communication.Possible values are 1 or 2.
Databits
This parameter specifies the number of data bits to use for asynchronous communication.Possible values are 5 to 8.
UseTermChar
This parameter enables or disables the usage of a termination character for asynchronouscommunication. Valid values are:
Value Description
TDRV009_DISABLED A termination character is not used.
TDRV009_ENABLED A termination character is used.
TermChar
This parameter specifies the termination character. After receiving this termination character,the communication controller will forward the received data packet immediately to the hostsystem and use a new data packet for further received data. Any 8bit value may be used for thisparameter.
HwHs
This parameter enables or disables the hardware handshaking mechanism using RTS/CTS.Valid values are:
Value Description
TDRV009_DISABLED Hardware handshaking is not used.
TDRV009_ENABLED Hardware handshaking is used.
TDRV009-SW-42 – VxWorks Device Driver Page 32 of 139
Crc
This parameter is a structure describing the CRC checking configuration.
typedef struct{
TDRV009_CRC_TYPE Type;TDRV009_ENABLE_DISABLE RxChecking;TDRV009_ENABLE_DISABLE TxGeneration;TDRV009_CRC_RESET ResetValue;
} TDRV009_CRC;
Type
This parameter describes the CRC type to be used. Possible values are:Value Description
TDRV009_CRC_16 16bit CRC algorithm is used for checksum
TDRV009_CRC_32 32bit CRC algorithm is used for checksum
RxChecking
This parameter enables or disables the receive CRC checking. Possible values are:Value Description
TDRV009_DISABLED CRC checking will not be used
TDRV009_ENABLED CRC checking will be used
TxGeneration
This parameter enables or disables the transmit CRC generation. Possible values are:Value Description
TDRV009_DISABLED A CRC checksum will be generated
TDRV009_ENABLED A CRC checksum will not be generated
ResetValue
This parameter describes the reset value for the CRC algorithm. Possible values are:Value Description
TDRV009_CRC_RST_FFFF CRC reset value will be 0xFFFF
TDRV009_CRC_RST_0000 CRC reset value will be 0x0000
TDRV009-SW-42 – VxWorks Device Driver Page 33 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;TDRV009_OPERATION_MODE_STRUCT OperationMode;
/*-------------------------------------------------Configure channel for Async / RS232 / 115200bps-------------------------------------------------*/
OperationMode.CommType = TDRV009_COMMTYPE_ASYNC;OperationMode.TransceiverMode = TDRV009_TRNSCVR _RS232;OperationMode.Oversampling = TDRV009_ENABLED;OperationMode.BrgSource = TDRV009_BRGSRC_XTAL1;OperationMode.TxClkSource = TDRV009_TXCSRC_BRG;OperationMode.TxClkOutput = 0;OperationMode.RxClkSource = TDRV009_RXCSRC_BRG;OperationMode.ClockMultiplier = TDRV009_CLKMULT_X1;OperationMode.Baudrate = 115200;OperationMode.ClockInversion = TDRV009_CLKINV_NONE;OperationMode.Encoding = TDRV009_ENC_NRZ;OperationMode.Parity = TDRV009_PAR_DISABLED;OperationMode.Stopbits = 1;OperationMode.Databits = 8;OperationMode.UseTermChar = TDRV009_DISABLED;OperationMode.TermChar = 0;OperationMode.HwHs = TDRV009_DISABLED;OperationMode.Crc.Type = TDRV009_CRC_16;OperationMode.Crc.RxChecking = TDRV009_DISABLED;OperationMode.Crc.TxGeneration = TDRV009_DISABLED;OperationMode.Crc.ResetValue = TDRV009_CRC_RST_FFFF;retval = tdrv009SetOperationMode(pDev, &OperationMode);if (retval != OK){
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
TDRV009-SW-42 – VxWorks Device Driver Page 34 of 139
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid parameter specified. Either the supplied bufferpointer is NULL, or a parameter inside the structure isinvalid.
TDRV009-SW-42 – VxWorks Device Driver Page 35 of 139
3.2.7 tdrv009GetOperationMode
Name
tdrv009GetOperationMode – Return channel’s current operation mode configuration
Synopsis
STATUS tdrv009SetOperationMode(
TDRV009_DEV pDev,TDRV009_OPERATION_MODE_STRUCT *pOperationMode
)
Description
This function function returns the channel’s current operation mode.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pOperationMode
This argument points to a TDRV009_OPERATION_MODE_STRUCT structure.
TDRV009-SW-42 – VxWorks Device Driver Page 36 of 139
typedef struct{
TDRV009_COMM_TYPE CommType;TDRV009_TRANSCEIVER_MODE TransceiverMode;TDRV009_ENABLE_DISABLE Oversampling;TDRV009_BRGSOURCE BrgSource;TDRV009_TXCSOURCE TxClkSource;unsigned long TxClkOutput;TDRV009_RXCSOURCE RxClkSource;TDRV009_CLKMULTIPLIER ClockMultiplier;unsigned long Baudrate;unsigned char ClockInversion;unsigned char Encoding;TDRV009_PARITY Parity;int Stopbits;int Databits;TDRV009_ENABLE_DISABLE UseTermChar;char TermChar;TDRV009_ENABLE_DISABLE HwHs;TDRV009_CRC Crc;
} TDRV009_OPERATION_MODE_STRUCT;
CommType
This parameter describes the general communication type for the specific channel. Possiblevalues are:
Value Description
TDRV009_COMMTYPE_ASYNC Asynchronous communication
TDRV009_COMMTYPE_HDLC_ADDR0 Standard HDLC communication withoutaddress recognition. Used for synchronouscommunication.
TDRV009_COMMTYPE_HDLC_TRANSP Extended Transparent mode. No protocolprocessing, channel works as simple bitcollector.
TDRV009-SW-42 – VxWorks Device Driver Page 37 of 139
TransceiverMode
This parameter describes the transceiver mode of the programmable multi-protocoltransceivers. Possible values are:
Value Description
TDRV009_TRNSCVR_NOT_USED Default V.11
TDRV009_TRNSCVR_RS530A EIA-530A (V.11 / V.10)
TDRV009_TRNSCVR_RS530 EIA-530 (V.11), also suitable for RS422
TDRV009_TRNSCVR_X21 X.21 (V.11)
TDRV009_TRNSCVR_V35 V.35 (V.35 / V.28)
TDRV009_TRNSCVR_RS449 EIA-449 (V.11)
TDRV009_TRNSCVR_V36 V.36 (V.11)
TDRV009_TRNSCVR_RS232 EIA-232 (V.28)
TDRV009_TRNSCVR_V28 V.28 (V.28)
TDRV009_TRNSCVR_NO_CABLE High impedance
Oversampling
This parameter enables or disables 16times oversampling, used for asynchronouscommunication. For communication with standard UARTs it is recommended to enable thisfeature. Valid values are:
Value Description
TDRV009_DISABLED The 16 times oversampling is not used.
TDRV009_ENABLED The 16 times oversampling is used.
BrgSource
This parameter specifies the frequency source used as input to the BRG (Baud RateGenerator). Valid values are:
Value Description
TDRV009_BRGSRC_XTAL1 XTAL1 oscillator is used for BRG input
TDRV009_BRGSRC_XTAL2 XTAL2 oscillator is used for BRG input
TDRV009_BRGSRC_XTAL3 XTAL3 oscillator is used for BRG input
TDRV009_BRGSRC_RXCEXTERN External clock at RxC input used for BRG input
TDRV009_BRGSRC_TXCEXTERN External clock at TxC input used for BRG input
TxClkSource
This parameter specifies the frequency source used as input to the transmit engine. Validvalues are:
Value Description
TDRV009_TXCSRC_BRG Baud Rate Generator output used for Tx clock
TDRV009_TXCSRC_BRGDIV16 BRG output divided by 16 used for Tx clock
TDRV009_TXCSRC_RXCEXTERN External clock at RxC input used for Tx clock
TDRV009_TXCSRC_TXCEXTERN External clock at TxC input used for Tx clock
TDRV009_TXCSRC_DPLL DPLL output used for Tx clock
TDRV009-SW-42 – VxWorks Device Driver Page 38 of 139
TxClkOutput
This parameter specifies which output lines are used to output the transmit clock, e.g. forsynchronous communication. The given values can be binary OR’ed. Valid values are:
Value Description
TDRV009_TXCOUT_TXC Transmit clock available at TxC output line
TDRV009_TXCOUT_RTS Transmit clock available at RTS output line
RxClkSource
This parameter specifies the frequency source used as input to the receive engine. Valid valuesare:
Value Description
TDRV009_RXCSRC_BRG Baud Rate Generator output used for Rx clock
TDRV009_RXCSRC_RXCEXTERN External clock at RxC input used for Rx clock
TDRV009_RXCSRC_DPLL DPLL output used for Rx clock
ClockMultiplier
This parameter specifies the multiplier used for BRG clock input. Valid values are:Value Description
TDRV009_CLKMULT_X1 Clock multiplier disabled
TDRV009_CLKMULT_X4 Selected input clock is multiplied by 4
Baudrate
This parameter specifies the desired frequency to be generated by the Baud Rate Generator(BRG), which can be used as clock input signal. The value is derived from the selected clocksource. Please note that only specific values depending on the selected oscillator are valid. Thisfrequency is internally multiplied by 16, if oversampling shall be used.
ClockInversion
This parameter specifies the inversion of the transmit clock and/or the receive clock. This valuecan be binary OR’ed. Possible values are:
Value Description
TDRV009_CLKINV_NONE no clock inversion
TDRV009_CLKINV_TXC transmit clock is inverted
TDRV009_CLKINV_RXC receive clock is inverted
Encoding
This parameter specifies the data encoding used for communication. Valid values are:Value Description
TDRV009_ENC_NRZ NRZ data encoding
TDRV009_ENC_NRZI NRZI data encoding
TDRV009_ENC_FM0 FM0 data encoding
TDRV009_ENC_FM1 FM1 data encoding
TDRV009_ENC_MANCHESTER Manchester data encoding
TDRV009-SW-42 – VxWorks Device Driver Page 39 of 139
Parity
This parameter specifies the parity bit generation used for asynchronous communication. Validvalues are:
Value Description
TDRV009_PAR_DISABLED No parity generation is used.
TDRV009_PAR_EVEN EVEN parity bit
TDRV009_PAR_ODD ODD parity bit
TDRV009_PAR_SPACE SPACE parity bit (always insert ‘0’)
TDRV009_PAR_MARK MARK parity bit (always insert ‘1’)
Stopbits
This parameter specifies the number of stop bits to use for asynchronous communication.Possible values are 1 or 2.
Databits
This parameter specifies the number of data bits to use for asynchronous communication.Possible values are 5 to 8.
UseTermChar
This parameter enables or disables the usage of a termination character for asynchronouscommunication. Valid values are:
Value Description
TDRV009_DISABLED A termination character is not used.
TDRV009_ENABLED A termination character is used.
TermChar
This parameter specifies the termination character. After receiving this termination character,the communication controller will forward the received data packet immediately to the hostsystem and use a new data packet for further received data. Any 8bit value may be used for thisparameter.
HwHs
This parameter enables or disables the hardware handshaking mechanism using RTS/CTS.Valid values are:
Value Description
TDRV009_DISABLED Hardware handshaking is not used.
TDRV009_ENABLED Hardware handshaking is used.
TDRV009-SW-42 – VxWorks Device Driver Page 40 of 139
Crc
This parameter is a structure describing the CRC checking configuration.
typedef struct{
TDRV009_CRC_TYPE Type;TDRV009_ENABLE_DISABLE RxChecking;TDRV009_ENABLE_DISABLE TxGeneration;TDRV009_CRC_RESET ResetValue;
} TDRV009_CRC;
Type
This parameter describes the CRC type to be used. Possible values are:Value Description
TDRV009_CRC_16 16bit CRC algorithm is used for checksum
TDRV009_CRC_32 32bit CRC algorithm is used for checksum
RxChecking
This parameter enables or disables the receive CRC checking. Possible values are:Value Description
TDRV009_DISABLED CRC checking will not be used
TDRV009_ENABLED CRC checking will be used
TxGeneration
This parameter enables or disables the transmit CRC generation. Possible values are:Value Description
TDRV009_DISABLED A CRC checksum will be generated
TDRV009_ENABLED A CRC checksum will not be generated
ResetValue
This parameter describes the reset value for the CRC algorithm. Possible values are:Value Description
TDRV009_CRC_RST_FFFF CRC reset value will be 0xFFFF
TDRV009_CRC_RST_0000 CRC reset value will be 0x0000
TDRV009-SW-42 – VxWorks Device Driver Page 41 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;TDRV009_OPERATION_MODE_STRUCT OperationMode;
/*-------------------------------------------------Configure channel for Async / RS232 / 115200bps-------------------------------------------------*/
OperationMode.CommType = TDRV009_COMMTYPE_ASYNC;OperationMode.TransceiverMode = TDRV009_TRNSCVR _RS232;OperationMode.Oversampling = TDRV009_ENABLED;OperationMode.BrgSource = TDRV009_BRGSRC_XTAL1;OperationMode.TxClkSource = TDRV009_TXCSRC_BRG;OperationMode.TxClkOutput = 0;OperationMode.RxClkSource = TDRV009_RXCSRC_BRG;OperationMode.ClockMultiplier = TDRV009_CLKMULT_X1;OperationMode.Baudrate = 115200;OperationMode.ClockInversion = TDRV009_CLKINV_NONE;OperationMode.Encoding = TDRV009_ENC_NRZ;OperationMode.Parity = TDRV009_PAR_DISABLED;OperationMode.Stopbits = 1;OperationMode.Databits = 8;OperationMode.UseTermChar = TDRV009_DISABLED;OperationMode.TermChar = 0;OperationMode.HwHs = TDRV009_DISABLED;OperationMode.Crc.Type = TDRV009_CRC_16;OperationMode.Crc.RxChecking = TDRV009_DISABLED;OperationMode.Crc.TxGeneration = TDRV009_DISABLED;OperationMode.Crc.ResetValue = TDRV009_CRC_RST_FFFF;
retval = tdrv009SetOperationMode(pDev, &OperationMode);if (retval != OK){
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
TDRV009-SW-42 – VxWorks Device Driver Page 42 of 139
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid parameter specified. Either the supplied bufferpointer is NULL, or a parameter inside the structure isinvalid.
TDRV009-SW-42 – VxWorks Device Driver Page 43 of 139
3.2.8 tdrv009SetBaudrate
Name
tdrv009SetBaudrate – Configure transmission rate
Synopsis
STATUS tdrv009SetBaudrate(
TDRV009_DEV pDev,int Baudrate
)
Description
This function sets up the transmission rate for the specific channel. This is done without changing theconfiguration set by tdrv009SetOperationMode. If async oversampling is enabled, the desiredbaudrate is internally multiplied by 16. It is important that this result can be derived from the selectedclocksource. This function specifies the desired frequency which should be generated by the BaudRate Generator (BRG).
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
Baudrate
This parameter specifies the baudrate which should be generated by the Baud Rate Generator.Be sure that the baudrate can be derived from the previously selected clock source.
TDRV009-SW-42 – VxWorks Device Driver Page 44 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;
/*------------------------------Set baudrate to 14400bps------------------------------*/
retval = tdrv009SetBaudrate(pDev, 14400);if (retval != ERROR){
/* function succeeded */}else{
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid parameter specified. The desired baudrate cannotbe derived from the selected clock source
TDRV009-SW-42 – VxWorks Device Driver Page 45 of 139
3.2.9 tdrv009SetReceiverState
Name
tdrv009SetReceiverState – Enable or disable receiver
Synopsis
STATUS tdrv009SetReceiverState(
TDRV009_DEV pDev,int ReceiverState
)
Description
This function sets the channel’s receiver either to active or inactive. This function must be called inuser-ringbuffer-mode, after a buffer-overflow has happened and free receive buffers are availableagain.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
ReceiverState
This parameter defines the new state of the receiver. Possible values are:Value Description
TDRV009_RCVR_ON The receiver is enabled.TDRV009_RCVR_OFF The receiver is disabled.
TDRV009-SW-42 – VxWorks Device Driver Page 46 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;
/*------------------------------Enable the receiver------------------------------*/
retval = tdrv009SetReceiverState(pDev, TDRV009_RCVR_ON);if (retval != ERROR){
/* function succeeded */}else{
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid parameter specified.
TDRV009-SW-42 – VxWorks Device Driver Page 47 of 139
3.2.10 tdrv009ClearRxBuffer
Name
tdrv009ClearRxBuffer – Discard all received data
Synopsis
STATUS tdrv009ClearRxBuffer(
TDRV009_DEV pDev)
Description
This function removes all received data from the channel’s receive buffer, and flushes the hardwareFIFO as well.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;
/*------------------------------Clear receive buffer------------------------------*/
retval = tdrv009ClearRxBuffer(pDev);if (retval != ERROR){
/* function succeeded */}else{
/* handle the error */}
TDRV009-SW-42 – VxWorks Device Driver Page 48 of 139
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EIO Error during reset or init of the receiver’s hardware DMAengine.
TDRV009-SW-42 – VxWorks Device Driver Page 49 of 139
3.2.11 tdrv009RtsSet
Name
tdrv009RtsSet – Assert RTS signal
Synopsis
STATUS tdrv009RtsSet(
TDRV009_DEV pDev)
Description
This function asserts the RTS handshake signal line of the specific channel. This function is notavailable if the channel is configured for hardware handshaking.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;
/*------------------------------Assert RTS------------------------------*/
retval = tdrv009RtsSet(pDev);if (retval != ERROR){
/* function succeeded */}else{
/* handle the error */}
TDRV009-SW-42 – VxWorks Device Driver Page 50 of 139
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EPERM The channel is in hardware handshake mode, so thisfunction is not allowed.
TDRV009-SW-42 – VxWorks Device Driver Page 51 of 139
3.2.12 tdrv009RtsClear
Name
tdrv009RtsClear – De-assert RTS signal
Synopsis
STATUS tdrv009RtsClear(
TDRV009_DEV pDev)
Description
This function de-asserts the RTS handshake signal line of the specific channel. This function is notavailable if the channel is configured for hardware handshaking.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;
/*------------------------------De-assert RTS------------------------------*/
retval = tdrv009RtsClear(pDev);if (retval != ERROR){
/* function succeeded */}else{
/* handle the error */}
TDRV009-SW-42 – VxWorks Device Driver Page 52 of 139
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EPERM The channel is in hardware handshake mode, so thisfunction is not allowed.
TDRV009-SW-42 – VxWorks Device Driver Page 53 of 139
3.2.13 tdrv009CtsGet
Name
tdrv009CtsGet – Return status of CTS signal
Synopsis
STATUS tdrv009CtsGet(
TDRV009_DEV pDev,unsigned long *pCtsState
)
Description
This function returns the current state of the CTS handshake signal line of the specific channel.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pCtsState
This parameter points to an unsigned long buffer where the status of the CTS signal will bestored. Depending on the state of CTS, either 0 (inactive) or 1 (active) is returned.
TDRV009-SW-42 – VxWorks Device Driver Page 54 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;unsigned long CtsStatus;
/*------------------------------Read CTS state------------------------------*/
retval = tdrv009CtsGet(pDev, &CtsStatus);if (retval != ERROR){
/* function succeeded */printf( “CTS = %ld\n”, CtsStatus );
}else{
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL The supplied buffer pointer is NULL.
TDRV009-SW-42 – VxWorks Device Driver Page 55 of 139
3.2.14 tdrv009DtrSet
Name
tdrv009DtrSet – Assert DTR signal
Synopsis
STATUS tdrv009DtrSet(
TDRV009_DEV pDev)
Description
This function sets the DTR signal line to HIGH. This function is only available for the 4th channel of aTDRV009 module.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;
/*------------------------------Set DTR to HIGH (only valid for channel 3)------------------------------*/
retval = tdrv009DtrSet(pDev);if (retval != ERROR){
/* function succeeded */}else{
/* handle the error */}
TDRV009-SW-42 – VxWorks Device Driver Page 56 of 139
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
ENOTSUP This function is not supported by the specific channel.
TDRV009-SW-42 – VxWorks Device Driver Page 57 of 139
3.2.15 tdrv009DtrClear
Name
tdrv009DtrClear – De-assert DTR signal
Synopsis
STATUS tdrv009DtrClear(
TDRV009_DEV pDev)
Description
This function sets the DTR signal line to LOW. This function is only available for the 4th channel of aTDRV009 module.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;
/*------------------------------Set DTR to LOW (only valid for channel 3)------------------------------*/
retval = tdrv009DtrClear(pDev);if (retval != ERROR){
/* function succeeded */}else{
/* handle the error */}
TDRV009-SW-42 – VxWorks Device Driver Page 58 of 139
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
ENOTSUP This function is not supported by the specific channel.
TDRV009-SW-42 – VxWorks Device Driver Page 59 of 139
3.2.16 tdrv009DsrGet
Name
tdrv009DsrGet – Return status of DSR signal
Synopsis
STATUS tdrv009DsrGet(
TDRV009_DEV pDev,unsigned long *pDsrState
)
Description
This function returns the current state of the DSR signal line of the specific channel. This function isonly available for the 4th channel of a TDRV009 module
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pDsrState
This parameter points to an unsigned long buffer where the status of the DSR signal will bestored. Depending on the state of DSR, either 0 (inactive) or 1 (active) is returned.
TDRV009-SW-42 – VxWorks Device Driver Page 60 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;unsigned long DsrStatus;
/*------------------------------Read DSR state------------------------------*/
retval = tdrv009DsrGet(pDev, &DsrStatus);if (retval != ERROR){
/* function succeeded */printf( “DSR = %ld\n”, DsrStatus );
}else{
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL The supplied buffer pointer is NULL.
TDRV009-SW-42 – VxWorks Device Driver Page 61 of 139
3.2.17 tdrv009SetExternalXtal
Name
tdrv009SetExternalXtal – Configure externally supplied oscillator frequency
Synopsis
STATUS tdrv009SetExternalXtal(
TDRV009_DEV pDev,int XtalFrequency
)
Description
This function specifies the frequency of an externally provided clock. This frequency is used forbaudrate calculation, and describes the input frequency to the Baud Rate Generator (BRG). Theexternal frequency may be supplied either at input line TxC or RxC.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
XtalFrequency
This parameter specifies the clock frequency in Hz.
TDRV009-SW-42 – VxWorks Device Driver Page 62 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;
/*------------------------------Specify 1MHz as external clock frequency------------------------------*/
retval = tdrv009SetExternalXtal(pDev, 1000000);if (retval != ERROR){
/* function succeeded */}else{
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid parameter specified. The specified frequency mustbe larger than 0.
TDRV009-SW-42 – VxWorks Device Driver Page 63 of 139
3.2.18 tdrv009RegisterRead
Name
tdrv009RegisterRead – Read from controller’s register space
Synopsis
STATUS tdrv009RegisterRead(
TDRV009_DEV pDev,TDRV009_ADDR_STRUCT *pRegisterBuffer
)
Description
This function reads one 32bit word from the communication controller’s register space.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pRegisterBuffer
This Parameter is a pointer to a TDRV009_ADDR_STRUCT structure.
typedef struct{
unsigned long Offset;unsigned long Value;
} TDRV009_ADDR_STRUCT;
Offset
This parameter specifies a byte offset into the communication controller’s register space.Please refer to the hardware user manual for further information.
Value
This parameter returns the 32bit word from the communication controller’s register space.
TDRV009-SW-42 – VxWorks Device Driver Page 64 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;TDRV009_ADDR_STRUCT AddrBuf;
/*-------------------------------------------------Read a 32bit value (Version Register)-------------------------------------------------*/
AddrBuf.Offset = 0x00F0;
retval = tdrv009RegisterRead(pDev, &AddrBuf);if (retval == OK){
printf( “Value = 0x%lX\n”, AddrBuf.Value );}else{
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid data buffer specified. The supplied buffer pointer isNULL.
EACCES The specified offset is invalid.
TDRV009-SW-42 – VxWorks Device Driver Page 65 of 139
3.2.19 tdrv009RegisterWrite
Name
tdrv009RegisterWrite – Write to controller’s register space
Synopsis
STATUS tdrv009RegisterWrite(
TDRV009_DEV pDev,TDRV009_ADDR_STRUCT *pRegisterBuffer
)
Description
This function writes one 32bit word to the communication controller’s register space.
Modifying register contents may result in communication problems, system crash or otherunexpected behavior.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pRegisterBuffer
This Parameter is a pointer to a TDRV009_ADDR_STRUCT structure.
typedef struct{
unsigned long Offset;unsigned long Value;
} TDRV009_ADDR_STRUCT;
Offset
This parameter specifies a byte offset into the communication controller’s register space.Please refer to the hardware user manual for further information.
Value
This 32bit word will be written to the communication controller’s register space.
TDRV009-SW-42 – VxWorks Device Driver Page 66 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;TDRV009_ADDR_STRUCT AddrBuf;
/*-------------------------------------------------Write a 32bit value (FIFO Control Register 4)-------------------------------------------------*/
AddrBuf.Offset = 0x0034;AddrBuf.Value = 0xffffffff;
retval = tdrv009RegisterWrite(pDev, &AddrBuf);if (retval != OK){
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid data buffer specified. The supplied buffer pointer isNULL.
EACCES The specified offset is invalid.
TDRV009-SW-42 – VxWorks Device Driver Page 67 of 139
3.2.20 tdrv009EepromRead
Name
tdrv009EepromRead – Read from EEPROM
Synopsis
STATUS tdrv009EepromRead(
TDRV009_DEV pDev,TDRV009_EEPROM_BUFFER *pEepromBuffer
)
Description
This function reads one 16bit word from the onboard EEPROM.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pEepromBuffer
This Parameter is a pointer to a TDRV009_EEPROM_BUFFER structure.
typedef struct{
unsigned long Offset;unsigned long Value;
} TDRV009_EEPROM_BUFFER;
Offset
This parameter specifies a 16bit word offset into the EEPROM.Following offsets are available:
Offset Access
00h – 5Fh R
60h – 7Fh R / W
Value
This parameter returns the 16bit word from the EEPROM at the given offset.
TDRV009-SW-42 – VxWorks Device Driver Page 68 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;TDRV009_EEPROM_BUFFER EepromBuf;
/*-------------------------------------------------Read a 16bit value into the EEPROM, offset 0-------------------------------------------------*/
EepromBuf.Offset = 0;
retval = tdrv009EepromRead(pDev, &EepromBuf);if (retval == OK){
printf( “Value = 0x%lX\n”, EepromBuf.Value );}else{
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid data buffer specified. The supplied buffer pointer isNULL.
EACCES Specified offset is invalid, and may not be accessed.
TDRV009-SW-42 – VxWorks Device Driver Page 69 of 139
3.2.21 tdrv009EepromWrite
Name
tdrv009EepromWrite – Write to controller’s register space
Synopsis
STATUS tdrv009EepromWrite(
TDRV009_DEV pDev,TDRV009_EEPROM_BUFFER *pEepromBuffer
)
Description
This function writes one 16bit word into the onboard EEPROM. The first part of the EEPROM isreserved for factory usage, write accesses to this area will result in an error.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pEepromBuffer
This Parameter is a pointer to a TDRV009_EEPROM_BUFFER structure.
typedef struct{
unsigned long Offset;unsigned long Value;
} TDRV009_EEPROM_BUFFER;
Offset
This parameter specifies a 16bit word offset into the EEPROM.Following offsets are available:
Offset Access
00h – 5Fh R
60h – 7Fh R / W
Value
This parameter specifies the 16bit word to be written into the EEPROM at the givenoffset.
TDRV009-SW-42 – VxWorks Device Driver Page 70 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;TDRV009_EEPROM_BUFFER EepromBuf;
/*-------------------------------------------------Write a 16bit value into the EEPROM, offset 60h-------------------------------------------------*/
EepromBuf.Offset = 0x60;EepromBuf.Value = 0x1234;
retval = tdrv009EepromWrite(pDev, &EepromBuf);if (retval != OK){
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid data buffer specified. The supplied buffer pointer isNULL.
EACCES The specified offset address is invalid, or read-only.
TDRV009-SW-42 – VxWorks Device Driver Page 71 of 139
3.2.22 tdrv009RingbufferRegister
Name
tdrv009RingbufferRegister – Register user-supplied ringbuffer
Synopsis
STATUS tdrv009RingbufferRegister(
TDRV009_DEV pDev,TDRV009_RINGBUFFER *pRingBuffer
)
Description
This advanced function provides a user-supplied ringbuffer to the driver using a pointer to a dynamicTDRV009_RINGBUFFER structure. The buffer consists of a header and a dynamically expandabledata section. The driver formats the allocated buffer automatically according to the specification. Theuser must ensure that the buffer persists as long as it is registered to the driver. The buffer must bephysically coherent, because direct memory access is used. Please refer to the following figure forfurther information.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
TDRV009-SW-42 – VxWorks Device Driver Page 72 of 139
pRingBuffer
This Parameter is a pointer to a TDRV009_RINGBUFFER structure.
typedef struct{
TDRV009RINGBUFFER_HEADER Header;unsigned char DataSection[40]; /* dynamically expandable buffer */
} TDRV009_RINGBUFFER;
Header
Contains administrative information used for buffer management.
DataSection
Inside the data section the real data buffers and their corresponding entry information isstored.
The TDRV009_RINGBUFFER_HEADER structure has the following layout:
typedef struct{
unsigned long BufferSize; /* total size of memory available for data */unsigned long PacketSize; /* size of one data packet, adjusted by driver */unsigned long NumberOfEntries; /* number of entries */unsigned long get; /* index where data can be read */unsigned long put; /* current index where new data is filled in */unsigned long Overflow; /* TRUE if an overflow happened. Receiver is disabled. */
} TDRV009_RINGBUFFER_HEADER;
BufferSize
Memory size available for the complete data buffers.
PacketSize
Memory size available for one data packet. The complete data buffer is divided into severalpackets matching the specified PacketSize.
NumberOfEntries
Number of available single buffers. This value is calculated out of BufferSize and PacketSize.Read Only.
get
Indicates the index where new data can be read out of the ringbuffer.
put
Indicates the index where the driver fills in new arrived data. Read Only.
Overflow
Indicates if a buffer overflow has happened. After a buffer overflow the receiving channel isdisabled and must be enabled again by hand. Read Only.
TDRV009-SW-42 – VxWorks Device Driver Page 73 of 139
The TDRV009_RINGBUFFER_ENTRY structure has the following layout:
typedef struct{
unsigned long NumberOfBytes; /* number of valid bytes for the current buffer index */unsigned long Size; /* total size of the current buffer */unsigned long Offset; /* offset into the data section where the buffer starts */unsigned long DmaAddress; /* physical address for the dma controller */unsigned long Valid; /* TRUE if the current buffer contains valid data */
} TDRV009_RINGBUFFER_ENTRY;
NumberOfBytes
This value indicates the number of valid bytes inside the corresponding buffer. Read Only.
Size
This value indicates the total size of the corresponding data buffer. Read Only.
Offset
This value specifies the offset relative to the beginning of the data section, where thecorresponding data buffer starts. Read Only.
DmaAddress
This value states the physical address of the data buffer used by the DMA controller. ReadOnly.
Valid
This value indicates if the corresponding data buffer contains valid data. This is the only valuethat should be modified by the user.
To ensure the correct functionality of the ringbuffer mode, do not change any of theadministrative read-only information values.
TDRV009-SW-42 – VxWorks Device Driver Page 74 of 139
Assistant Macros and Functions for Buffer handling
To help the user work with this ringbuffer concept some assistant macros and functions were definedin “tdrv009.h”. They are explained in the following.
CALCULATE_RINGBUFFER_SIZE( BufferSize, PacketSize )calculates the total size necessary for allocation of the complete ringbuffer
GET_BUFFER( pRingBuffer, index )returns a pointer to the corresponding data buffer
IS_VALID( pRingBuffer, index )TRUE if the corresponding buffer contains valid data, otherwise FALSE
SET_VALID( pRingBuffer, index, value )sets the Valid-flag for the specified entry to value
CLEAR_BUFFER( pRingBuffer, index )clears the corresponding data buffer
GET_POS( pRingBuffer )returns the current get-position where new data can be read
OVERFLOW( pRingBuffer )TRUE if a buffer overflow has happened, otherwise false
unsigned char*GetNewBuffer( TP862_RINGBUFFER* pRingBuffer, ULONG* length );
returns a pointer to a buffer containing new data. The get-position is set to the next entry, thenumber of valid bytes is returned in length. The previous data buffer is marked as invalid, so thedriver may reuse this buffer for data reception.
For further information on how to deal with the ringbuffer, the special assistant macros, and functions,please refer to the provided example application.
TDRV009-SW-42 – VxWorks Device Driver Page 75 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;TDRV009_RINGBUFFER* pRingBuffer;
#define BUFFER_SIZE 5000#define PACKET_SIZE 100
/*-----------------------------------------------------------allocate memory for ringbuffer (physically coherent, nonchached):
5000 bytes total data space100 bytes per packet
-----------------------------------------------------------*/pRingBuffer = (TDRV009_RINGBUFFER*)cacheDmaMalloc(
CALCULATE_RINGBUFFER_SIZE( BUFFER_SIZE, PACKET_SIZE ));
pRingBuffer->Header.BufferSize = BUFFER_SIZE;pRingBuffer->Header.PacketSize = PACKET_SIZE;
retval = tdrv009RingbufferRegister(pDev, pRingBuffer);if (retval != OK){
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
TDRV009-SW-42 – VxWorks Device Driver Page 76 of 139
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid data buffer specified. The supplied buffer pointer isNULL.
EBUSY A ringbuffer is already registered. Unregister it first.
ENOMEM Not enough memory available to create necessary receivedescriptor list.
EIO Error during reset or init of the receiver’s hardware DMAengine.
TDRV009-SW-42 – VxWorks Device Driver Page 77 of 139
3.2.23 tdrv009RingbufferUnregister
Name
tdrv009RingbufferUnregister – Unregister user-supplied ringbuffer
Synopsis
STATUS tdrv009RingbufferUnregister(
TDRV009_DEV pDev)
Description
This function unregisters a previously registered user-ringbuffer. A channel-reset is performed and thedriver uses its internal ringbuffer to receive data again.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;
/*-----------------------------------unregister user-supplied ringbuffer-----------------------------------*/
retval = tdrv009RingbufferUnregister(pDev);if (retval != ERROR){
/* function succeeded */}else{
/* handle the error */}
TDRV009-SW-42 – VxWorks Device Driver Page 78 of 139
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EACCES No user-supplied ringbuffer is used, so this function is notsupported at the moment.
EIO Error during reset or init of the receiver’s hardware DMAengine.
TDRV009-SW-42 – VxWorks Device Driver Page 79 of 139
3.2.24 tdrv009WaitForInterrupt
Name
tdrv009WaitForInterrupt – Wait for SCC interrupt event
Synopsis
STATUS tdrv009WaitForInterrupt(
TDRV009_DEV pDev,TDRV009_WAIT_STRUCT *pWaitBuffer
)
Description
This function waits until a specified SCC-interrupt or the timeout occurs.
Parameters
pDev
This parameter specifies the device descriptor to the hardware module retrieved by a call to thecorresponding open-function.
pEepromBuffer
This parameter is a pointer to a TDRV009_WAIT_STRUCT structure.
typedef struct{
unsigned long Interrupts;int Timeout;
} TDRV009_WAIT_STRUCT;
Interrupts
This parameter specifies interrupt bits to wait for. If at least one interrupt occurs, the valueis returned in this parameter. Please refer to the hardware user manual for furtherinformation on the possible SCC interrupt bits.
Timeout
This parameter specifies the time (in system ticks) to wait for an interrupt. If -1 isspecified, the function will block indefinitely.
TDRV009-SW-42 – VxWorks Device Driver Page 80 of 139
Example
#include “tdrv009.h”
TDRV009_DEV pDev;int retval;TDRV009_WAIT_STRUCT WaitStruct;
/*-------------------------------------------------Wait at least 60 system ticks for aCTS Status Change (CSC) interrupt-------------------------------------------------*/
WaitStruct.Interrupts = (1 << 14);WaitStruct.Timeout = 60;
retval = tdrv009WaitForInterrupt(pDev, &WaitStruct);if (retval == OK){
printf( “Occurred Interrupt = 0x%lX\n”, WaitStruct.Interrupts );}else{
/* handle the error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set error code described below.
Error code Description
EBADF The device handle is invalid
EINVAL Invalid data buffer specified. The supplied buffer pointer isNULL.
EBUSY Too many simultaneous wait jobs active.
S_objLib_OBJ_TIMEOUT Timeout occurred.
TDRV009-SW-42 – VxWorks Device Driver Page 81 of 139
4 Legacy I/O system functionsThis chapter describes the driver-level interface to the I/O system. The purpose of these functions is toinstall the driver in the I/O system, add and initialize devices.
4.1 tdrv009Drv()
NAME
tdrv009Drv() - installs the TDRV009 driver in the I/O system
SYNOPSIS
#include “tdrv009.h”
STATUS tdrv009Drv(void)
DESCRIPTION
This function searches for devices on the PCI bus, and installs the TDRV009 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 thesystem or performing any I/O request.
EXAMPLE
#include "tdrv009.h”
STATUS result;
/*-------------------Initialize Driver-------------------*/
result = tdrv009Drv();if (result == ERROR){
/* Error handling */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
TDRV009-SW-42 – VxWorks Device Driver Page 82 of 139
ERROR CODES
The error codes are stored in errno and can be read with the function errnoGet().
Error code Description
ENOMEM Not enough memory available.
ENXIO No supported modules found.
EIO Error during hardware configuration.
SEE ALSO
VxWorks Programmer’s Guide: I/O System
TDRV009-SW-42 – VxWorks Device Driver Page 83 of 139
4.2 tdrv009DevCreate()
NAME
tdrv009DevCreate() – Add a TDRV009 device to the VxWorks system
SYNOPSIS
#include “tdrv009.h”
STATUS tdrv009DevCreate(
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 andprepared 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 examplefor open() calls.
devIdx
This index number specifies the device to add to the system.The index number depends on the search priority of the modules. The modules will be searchedin the following order:
- TPMC863-xx- TPMC363-xx- TCP863-xx- TAMC863-xx
If modules of the same type are installed the channel numbers will be assigned in the order theVxWorks pciFindDevice() function will find the devices.
TDRV009-SW-42 – VxWorks Device Driver Page 84 of 139
Example: (A system with 1 TPMC863-xx, 2 TPMC363-xx, and 1 TCP863-xx) will assign thefollowing device indices:
Module Device Index
TPMC863-xx 0
TPMC363-xx (1st) 1
TPMC363-xx (2nd) 2
TCP863-xx 3
funcType
This parameter is unused and should be set to 0.
pParam
This parameter is unused and should be set to NULL.
EXAMPLE
#include "tdrv009.h”
STATUS result;
/*-------------------------------------------------------Create the device "/tdrv009/0" for the first channel device-------------------------------------------------------*/
result = tdrv009DevCreate( "/tdrv009/0",0,0,(void*)NULL);
if (result == OK){
/* Device successfully created */}else{
/* Error occurred when creating the device */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
TDRV009-SW-42 – VxWorks Device Driver Page 85 of 139
ERROR CODES
The error codes are stored in errno and can be read with the function errnoGet().
Error code Description
ENXIO No supported modules found.
EBUSY The desired device has already been created.
SEE ALSO
VxWorks Programmer’s Guide: I/O System
TDRV009-SW-42 – VxWorks Device Driver Page 86 of 139
4.3 tdrv009PciInit()
NAME
tdrv009PciInit() – Generic PCI device initialization
SYNOPSIS
void tdrv009PciInit()
DESCRIPTION
This function is required only for Intel x86 VxWorks platforms. The purpose is to setup the MMUmapping for all required TDRV009 PCI spaces (base address register) and to enable the TDRV009device for access.
The global variable tdrv009Status obtains the result of the device initialization and can be polled laterby the application before the driver will be installed.
Value Meaning
> 0 Initialization successful completed. The value of tdrv009Status is equal to thenumber of mapped PCI spaces
0 No TDRV009 device found
< 0 Initialization failed. The value of (tdrv009Status & 0xFF) is equal to the number ofmapped spaces until the error occurs.Possible cause: Too few entries for dynamic mappings in sysPhysMemDesc[].Remedy: Add dummy entries as necessary (syslib.c).
EXAMPLE
extern void tdrv009PciInit();
…
tdrv009PciInit();
TDRV009-SW-42 – VxWorks Device Driver Page 87 of 139
5 I/O Functions
5.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 TDRV009 device, a file descriptor must be opened by invoking thebasic I/O function open().
PARAMETER
name
Specifies the device which shall be opened, the name specified in tdrv009DevCreate() must beused
flags
Not used
mode
Not used
TDRV009-SW-42 – VxWorks Device Driver Page 88 of 139
EXAMPLE
int fd;
/*------------------------------------------Open the device named "/tdrv009/0" for I/O------------------------------------------*/
fd = open("/tdrv009/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 code is a standard error code set by the I/O system (see VxWorks Reference Manual).
SEE ALSO
ioLib, basic I/O routine - open()
TDRV009-SW-42 – VxWorks Device Driver Page 89 of 139
5.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 bythe open() function.
EXAMPLE
int fd;STATUS retval;
/*----------------close the device----------------*/
retval = close(fd);if (retval == ERROR){
/* Handle error */}
TDRV009-SW-42 – VxWorks Device Driver Page 90 of 139
RETURNS
OK or ERROR. If the function fails, an error code will be stored in errno.
ERROR CODES
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()
TDRV009-SW-42 – VxWorks Device Driver Page 91 of 139
5.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 theopen() 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).
TDRV009-SW-42 – VxWorks Device Driver Page 92 of 139
EXAMPLE
#define BUFSIZE 100
int fd;char buffer[BUFSIZE];int retval;
/*-----------------------------Read data from TDRV009 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.
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) or adriver set error code described below.
Error code Description
EACCES An external ringbuffer is in use, so this function is notsupported at the moment.
SEE ALSO
ioLib, basic I/O routine - read()
TDRV009-SW-42 – VxWorks Device Driver Page 93 of 139
5.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. The function returns immediately to the callerafter queuing the data into the transmit descriptor list. Make sure that the supplied data buffer persistsuntil the transmission is completed. To check if the data buffer is completely processed, namely thedata has been transferred to the hardware FIFO, use the I/O control functionTDRV009_WRITEBUF_DONE (see below).
PARAMETER
fd
This file descriptor specifies the device to be used. The file descriptor has been returned by theopen() function.
buffer
This argument points to a user supplied buffer. The data of the buffer will be written to thedevice. The data buffer must be physically contiguous and accessible by the DMA controller
nbytes
This parameter specifies the number of bytes to be written.
TDRV009-SW-42 – VxWorks Device Driver Page 94 of 139
EXAMPLE
int fd;char *buffer;int retval;
/*------------------------------Write data to a TDRV009 device------------------------------*/
pData = (char*)cacheDmaMalloc( 12 );sprintf( pData, “Hello World” );
retval = write(fd, buffer, strlen(buffer));if (retval == OK){
printf(“Data queued for transmission.\n”);}else{
/* handle the write error */}
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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) or adriver set code described below.
Error code Description
EBUSY A different write operation is currently in progress.
ENOMEM No transmit packets or descriptors available. Too manyparallel transmissions in progress.
EIO Error during channel initialization.
SEE ALSO
ioLib, basic I/O routine - write()
TDRV009-SW-42 – VxWorks Device Driver Page 95 of 139
5.5 ioctl()
NAME
ioctl() - performs an I/O control function.
SYNOPSIS
#include “tdrv009.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 (read, write) will be performed bycalling the ioctl() function.
PARAMETER
fd
This file descriptor specifies the device to be used. The file descriptor has been returned by theopen() function.
request
This argument specifies the function that shall be executed. Following functions are defined:Function Description
TDRV009_SET_OPERATION_MODE Configure channel operation mode
TDRV009_GET_OPERATION_MODE Read current channel configuration
TDRV009_SET_BPS Setup transmission rate
TDRV009_FRAME_READ Read data buffer
TDRV009_FRAME_WRITE Write data buffer
TDRV009_WRITEBUF_DONE Check status of transmit data buffer
TDRV009_RINGBUFFER_REGISTER Register user ringbuffer
TDRV009_RINGBUFFER_UNREGISTER Unregister user ringbuffer
TDRV009_SET_RECEIVER_STATE Configure receiver state
TDRV009_CLEAR_RX_BUFFER Clear receive buffer and FIFO
TDRV009_EEPROM_WRITE Write value to EEPROM
TDRV009_EEPROM_READ Read value from EEPROM
TDRV009_RTS_SET Assert RTS handshake line
TDRV009-SW-42 – VxWorks Device Driver Page 96 of 139
TDRV009_RTS_CLEAR De-Assert RTS handshake line
TDRV009_CTS_GET Read state of CTS
TDRV009_DTR_SET Set DTR signal line
TDRV009_DTR_CLEAR Clear DTR signal line
TDRV009_DSR_GET Read state of DSR
TDRV009_SET_EXT_XTAL Configure externally supplied clock frequency
TDRV009_REGREAD Read value from register space
TDRV009_REGWRITE Write value to register space
TDRV009_WAITFORINTERRUPT Wait for specific SCC interrupt
arg
This parameter depends on the selected function (request). How to use this parameter isdescribed below with the function.
RETURNS
OK or ERROR. If the function fails an error code will be stored in errno.
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).Function specific error codes will be described with the function.
Error code Description
ENOTSUP Command not supported by device driver or module.
SEE ALSO
ioLib, basic I/O routine - ioctl()
TDRV009-SW-42 – VxWorks Device Driver Page 97 of 139
5.5.1 TDRV009_SET_OPERATION_MODE
This I/O control function configures the channel’s operation mode. The function specific controlparameter arg is a pointer to a TDRV009_OPERATION_MODE_STRUCT structure. It is necessary tocompletely initialize the structure. This can be done by calling the I/O control functionTDRV009_GET_OPERATION_MODE described below.
A call to this function must be done prior to any communication operation, because after driverstartup, the channel’s transceivers are disabled.
typedef struct{
TDRV009_COMM_TYPE CommType;TDRV009_TRANSCEIVER_MODE TransceiverMode;TDRV009_ENABLE_DISABLE Oversampling;TDRV009_BRGSOURCE BrgSource;TDRV009_TXCSOURCE TxClkSource;unsigned long TxClkOutput;TDRV009_RXCSOURCE RxClkSource;TDRV009_CLKMULTIPLIER ClockMultiplier;unsigned long Baudrate;unsigned char ClockInversion;unsigned char Encoding;TDRV009_PARITY Parity;int Stopbits;int Databits;TDRV009_ENABLE_DISABLE UseTermChar;char TermChar;TDRV009_ENABLE_DISABLE HwHs;TDRV009_CRC Crc;
} TDRV009_OPERATION_MODE_STRUCT;
CommType
This parameter describes the general communication type for the specific channel. Possiblevalues are:
Value Description
TDRV009_COMMTYPE_ASYNC Asynchronous communication
TDRV009_COMMTYPE_HDLC_ADDR0 Standard HDLC communication withoutaddress recognition. Used for synchronouscommunication.
TDRV009_COMMTYPE_HDLC_TRANSP Extended Transparent mode. No protocolprocessing, channel works as simple bitcollector.
TDRV009-SW-42 – VxWorks Device Driver Page 98 of 139
TransceiverMode
This parameter describes the transceiver mode of the programmable multi-protocoltransceivers. Possible values are:
Value Description
TDRV009_TRNSCVR_NOT_USED Default V.11
TDRV009_TRNSCVR_RS530A EIA-530A (V.11 / V.10)
TDRV009_TRNSCVR_RS530 EIA-530 (V.11), also suitable for RS422
TDRV009_TRNSCVR_X21 X.21 (V.11)
TDRV009_TRNSCVR_V35 V.35 (V.35 / V.28)
TDRV009_TRNSCVR_RS449 EIA-449 (V.11)
TDRV009_TRNSCVR_V36 V.36 (V.11)
TDRV009_TRNSCVR_RS232 EIA-232 (V.28)
TDRV009_TRNSCVR_V28 V.28 (V.28)
TDRV009_TRNSCVR_NO_CABLE High impedance
Oversampling
This parameter enables or disables 16 times oversampling, used for asynchronouscommunication. For communication with standard UARTs it is recommended to enable thisfeature. Valid values are:
Value Description
TDRV009_DISABLED The 16 times oversampling is not used.
TDRV009_ENABLED The 16 times oversampling is used.
BrgSource
This parameter specifies the frequency source used as input to the BRG (Baud RateGenerator). Valid values are:
Value Description
TDRV009_BRGSRC_XTAL1 XTAL1 oscillator is used for BRG input
TDRV009_BRGSRC_XTAL2 XTAL2 oscillator is used for BRG input
TDRV009_BRGSRC_XTAL3 XTAL3 oscillator is used for BRG input
TDRV009_BRGSRC_RXCEXTERN External clock at RxC input used for BRG input
TDRV009_BRGSRC_TXCEXTERN External clock at TxC input used for BRG input
TxClkSource
This parameter specifies the frequency source used as input to the transmit engine. Validvalues are:
Value Description
TDRV009_TXCSRC_BRG Baud Rate Generator output used for Tx clock
TDRV009_TXCSRC_BRGDIV16 BRG output divided by 16 used for Tx clock
TDRV009_TXCSRC_RXCEXTERN External clock at RxC input used for Tx clock
TDRV009_TXCSRC_TXCEXTERN External clock at TxC input used for Tx clock
TDRV009_TXCSRC_DPLL DPLL output used for Tx clock
TDRV009-SW-42 – VxWorks Device Driver Page 99 of 139
TxClkOutput
This parameter specifies which output lines are used to output the transmit clock, e.g. forsynchronous communication. The given values can be binary OR’ed. Valid values are:
Value Description
TDRV009_TXCOUT_TXC Transmit clock available at TxC output line
TDRV009_TXCOUT_RTS Transmit clock available at RTS output line
RxClkSource
This parameter specifies the frequency source used as input to the receive engine. Valid valuesare:
Value Description
TDRV009_RXCSRC_BRG Baud Rate Generator output used for Rx clock
TDRV009_RXCSRC_RXCEXTERN External clock at RxC input used for Rx clock
TDRV009_RXCSRC_DPLL DPLL output used for Rx clock
ClockMultiplier
This parameter specifies the multiplier used for BRG clock input. Valid values are:Value Description
TDRV009_CLKMULT_X1 Clock multiplier disabled
TDRV009_CLKMULT_X4 Selected input clock is multiplied by 4
Baudrate
This parameter specifies the desired frequency to be generated by the Baud Rate Generator(BRG), which can be used as clock input signal. The value is derived from the selected clocksource. Please note that only specific values depending on the selected oscillator are valid. Thisfrequency is internally multiplied by 16, if oversampling shall be used.
ClockInversion
This parameter specifies the inversion of the transmit clock and/or the receive clock. This valuecan be binary OR’ed. Possible values are:
Value Description
TDRV009_CLKINV_NONE no clock inversion
TDRV009_CLKINV_TXC transmit clock is inverted
TDRV009_CLKINV_RXC receive clock is inverted
Encoding
This parameter specifies the data encoding used for communication. Valid values are:Value Description
TDRV009_ENC_NRZ NRZ data encoding
TDRV009_ENC_NRZI NRZI data encoding
TDRV009_ENC_FM0 FM0 data encoding
TDRV009_ENC_FM1 FM1 data encoding
TDRV009_ENC_MANCHESTER Manchester data encoding
TDRV009-SW-42 – VxWorks Device Driver Page 100 of 139
Parity
This parameter specifies the parity bit generation used for asynchronous communication. Validvalues are:
Value Description
TDRV009_PAR_DISABLED No parity generation is used.
TDRV009_PAR_EVEN EVEN parity bit
TDRV009_PAR_ODD ODD parity bit
TDRV009_PAR_SPACE SPACE parity bit (always insert ‘0’)
TDRV009_PAR_MARK MARK parity bit (always insert ‘1’)
Stopbits
This parameter specifies the number of stop bits to use for asynchronous communication.Possible values are 1 or 2.
Databits
This parameter specifies the number of data bits to use for asynchronous communication.Possible values are 5 to 8.
UseTermChar
This parameter enables or disables the usage of a termination character for asynchronouscommunication. Valid values are:
Value Description
TDRV009_DISABLED A termination character is not used.
TDRV009_ENABLED A termination character is used.
TermChar
This parameter specifies the termination character. After receiving this termination character,the communication controller will forward the received data packet immediately to the hostsystem and use a new data packet for further received data. Any 8bit value may be used for thisparameter.
HwHs
This parameter enables or disables the hardware handshaking mechanism using RTS/CTS.Valid values are:
Value Description
TDRV009_DISABLED Hardware handshaking is not used.
TDRV009_ENABLED Hardware handshaking is used.
TDRV009-SW-42 – VxWorks Device Driver Page 101 of 139
Crc
This parameter is a structure describing the CRC checking configuration.
typedef struct{
TDRV009_CRC_TYPE Type;TDRV009_ENABLE_DISABLE RxChecking;TDRV009_ENABLE_DISABLE TxGeneration;TDRV009_CRC_RESET ResetValue;
} TDRV009_CRC;
Type
This parameter describes the CRC type to be used. Possible values are:Value Description
TDRV009_CRC_16 16bit CRC algorithm is used for checksum
TDRV009_CRC_32 32bit CRC algorithm is used for checksum
RxChecking
This parameter enables or disables the receive CRC checking. Possible values are:Value Description
TDRV009_DISABLED CRC checking will not be used
TDRV009_ENABLED CRC checking will be used
TxGeneration
This parameter enables or disables the transmit CRC generation. Possible values are:Value Description
TDRV009_DISABLED A CRC checksum will be generated
TDRV009_ENABLED A CRC checksum will not be generated
ResetValue
This parameter describes the reset value for the CRC algorithm. Possible values are:Value Description
TDRV009_CRC_RST_FFFF CRC reset value will be 0xFFFF
TDRV009_CRC_RST_0000 CRC reset value will be 0x0000
TDRV009-SW-42 – VxWorks Device Driver Page 102 of 139
EXAMPLE
#include “tdrv009.h”
int fd;TDRV009_OPERATION_MODE_STRUCT OperationMode;int retval;
/*-------------------------------------------------Configure channel for Async / RS232 / 115200bps-------------------------------------------------*/
OperationMode.CommType = TDRV009_COMMTYPE_ASYNC;OperationMode.TransceiverMode = TDRV009_TRNSCVR _RS232;OperationMode.Oversampling = TDRV009_ENABLED;OperationMode.BrgSource = TDRV009_BRGSRC_XTAL1;OperationMode.TxClkSource = TDRV009_TXCSRC_BRG;OperationMode.TxClkOutput = 0;OperationMode.RxClkSource = TDRV009_RXCSRC_BRG;OperationMode.ClockMultiplier = TDRV009_CLKMULT_X1;OperationMode.Baudrate = 115200;OperationMode.ClockInversion = TDRV009_CLKINV_NONE;OperationMode.Encoding = TDRV009_ENC_NRZ;OperationMode.Parity = TDRV009_PAR_DISABLED;OperationMode.Stopbits = 1;OperationMode.Databits = 8;OperationMode.UseTermChar = TDRV009_DISABLED;OperationMode.TermChar = 0;OperationMode.HwHs = TDRV009_DISABLED;OperationMode.Crc.Type = TDRV009_CRC_16;OperationMode.Crc.RxChecking = TDRV009_DISABLED;OperationMode.Crc.TxGeneration = TDRV009_DISABLED;OperationMode.Crc.ResetValue = TDRV009_CRC_RST_FFFF;
retval = ioctl(fd, TDRV009_SET_OPERATION_MODE, (int)&OperationMode);if (retval != ERROR){
/* function succeeded */}else{
/* handle the error */}
TDRV009-SW-42 – VxWorks Device Driver Page 103 of 139
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. Either the supplied bufferpointer is NULL, or a parameter inside the structure isinvalid.
TDRV009-SW-42 – VxWorks Device Driver Page 104 of 139
5.5.2 TDRV009_GET_OPERATION_MODE
This I/O control function returns the channel’s current operation mode. The function specific controlparameter arg is a pointer to a TDRV009_OPERATION_MODE_STRUCT structure.
typedef struct{
TDRV009_COMM_TYPE CommType;TDRV009_TRANSCEIVER_MODE TransceiverMode;TDRV009_ENABLE_DISABLE Oversampling;TDRV009_BRGSOURCE BrgSource;TDRV009_TXCSOURCE TxClkSource;unsigned long TxClkOutput;TDRV009_RXCSOURCE RxClkSource;TDRV009_CLKMULTIPLIER ClockMultiplier;unsigned long Baudrate;unsigned char ClockInversion;unsigned char Encoding;TDRV009_PARITY Parity;int Stopbits;int Databits;TDRV009_ENABLE_DISABLE UseTermChar;char TermChar;TDRV009_ENABLE_DISABLE HwHs;TDRV009_CRC Crc;
} TDRV009_OPERATION_MODE_STRUCT;
CommType
This parameter describes the general communication type for the specific channel. Possiblevalues are:
Value Description
TDRV009_COMMTYPE_ASYNC Asynchronous communication
TDRV009_COMMTYPE_HDLC_ADDR0 Standard HDLC communication withoutaddress recognition. Used for synchronouscommunication.
TDRV009_COMMTYPE_HDLC_TRANSP Extended Transparent mode. No protocolprocessing, channel works as simple bitcollector.
TDRV009-SW-42 – VxWorks Device Driver Page 105 of 139
TransceiverMode
This parameter describes the transceiver mode of the programmable multi-protocoltransceivers. Possible values are:
Value Description
TDRV009_TRNSCVR_NOT_USED Default V.11
TDRV009_TRNSCVR_RS530A EIA-530A (V.11 / V.10)
TDRV009_TRNSCVR_RS530 EIA-530 (V.11), also suitable for RS422
TDRV009_TRNSCVR_X21 X.21 (V.11)
TDRV009_TRNSCVR_V35 V.35 (V.35 / V.28)
TDRV009_TRNSCVR_RS449 EIA-449 (V.11)
TDRV009_TRNSCVR_V36 V.36 (V.11)
TDRV009_TRNSCVR_RS232 EIA-232 (V.28)
TDRV009_TRNSCVR_V28 V.28 (V.28)
TDRV009_TRNSCVR_NO_CABLE High impedance
Oversampling
This parameter enables or disables 16 times oversampling, used for asynchronouscommunication. For communication with standard UARTs it is recommended to enable thisfeature. Valid values are:
Value Description
TDRV009_DISABLED The 16 times oversampling is not used.
TDRV009_ENABLED The 16 times oversampling is used.
BrgSource
This parameter specifies the frequency source used as input to the BRG (Baud RateGenerator). Valid values are:
Value Description
TDRV009_BRGSRC_XTAL1 XTAL1 oscillator is used for BRG input
TDRV009_BRGSRC_XTAL2 XTAL2 oscillator is used for BRG input
TDRV009_BRGSRC_XTAL3 XTAL3 oscillator is used for BRG input
TDRV009_BRGSRC_RXCEXTERN External clock at RxC input used for BRG input
TDRV009_BRGSRC_TXCEXTERN External clock at TxC input used for BRG input
TxClkSource
This parameter specifies the frequency source used as input to the transmit engine. Validvalues are:
Value Description
TDRV009_TXCSRC_BRG Baud Rate Generator output used for Tx clock
TDRV009_TXCSRC_BRGDIV16 BRG output divided by 16 used for Tx clock
TDRV009_TXCSRC_RXCEXTERN External clock at RxC input used for Tx clock
TDRV009_TXCSRC_TXCEXTERN External clock at TxC input used for Tx clock
TDRV009_TXCSRC_DPLL DPLL output used for Tx clock
TDRV009-SW-42 – VxWorks Device Driver Page 106 of 139
TxClkOutput
This parameter specifies which output lines are used to output the transmit clock, e.g. forsynchronous communication. The given values can be binary OR’ed. Valid values are:
Value Description
TDRV009_TXCOUT_TXC Transmit clock available at TxC output line
TDRV009_TXCOUT_RTS Transmit clock available at RTS output line
RxClkSource
This parameter specifies the frequency source used as input to the receive engine. Valid valuesare:
Value Description
TDRV009_RXCSRC_BRG Baud Rate Generator output used for Rx clock
TDRV009_RXCSRC_RXCEXTERN External clock at RxC input used for Rx clock
TDRV009_RXCSRC_DPLL DPLL output used for Rx clock
ClockMultiplier
This parameter specifies the multiplier used for BRG clock input. Valid values are:Value Description
TDRV009_CLKMULT_X1 Clock multiplier disabled
TDRV009_CLKMULT_X4 Selected input clock is multiplied by 4
Baudrate
This parameter specifies the desired frequency to be generated by the BRG (Baud RateGenerator), which can be used as clock input signal. The value is derived from the selectedclock source. Please note that only specific values depending on the selected oscillator arevalid. This frequency is internally multiplied by 16, if oversampling shall be used.
ClockInversion
This parameter specifies the inversion of the transmit clock and/or the receive clock. This valuecan be binary OR’ed. Possible values are:
Value Description
TDRV009_CLKINV_NONE no clock inversion
TDRV009_CLKINV_TXC transmit clock is inverted
TDRV009_CLKINV_RXC receive clock is inverted
Encoding
This parameter specifies the data encoding used for communication. Valid values are:Value Description
TDRV009_ENC_NRZ NRZ data encoding
TDRV009_ENC_NRZI NRZI data encoding
TDRV009_ENC_FM0 FM0 data encoding
TDRV009_ENC_FM1 FM1 data encoding
TDRV009_ENC_MANCHESTER Manchester data encoding
TDRV009-SW-42 – VxWorks Device Driver Page 107 of 139
Parity
This parameter specifies the parity bit generation used for asynchronous communication. Validvalues are:
Value Description
TDRV009_PAR_DISABLED No parity generation is used.
TDRV009_PAR_EVEN EVEN parity bit
TDRV009_PAR_ODD ODD parity bit
TDRV009_PAR_SPACE SPACE parity bit (always insert ‘0’)
TDRV009_PAR_MARK MARK parity bit (always insert ‘1’)
Stopbits
This parameter specifies the number of stop bits to use for asynchronous communication.Possible values are 1 or 2.
Databits
This parameter specifies the number of data bits to use for asynchronous communication.Possible values are 5 to 8.
UseTermChar
This parameter enables or disables the usage of a termination character for asynchronouscommunication. Valid values are:
Value Description
TDRV009_DISABLED A termination character is not used.
TDRV009_ENABLED A termination character is used.
TermChar
This parameter specifies the termination character. After receiving this termination character,the communication controller will forward the received data packet immediately to the hostsystem and use a new data packet for further received data. Any 8bit value may be used for thisparameter.
HwHs
This parameter enables or disables the hardware handshaking mechanism using RTS/CTS.Valid values are:
Value Description
TDRV009_DISABLED Hardware handshaking is not used.
TDRV009_ENABLED Hardware handshaking is used.
TDRV009-SW-42 – VxWorks Device Driver Page 108 of 139
Crc
This parameter is a structure describing the CRC checking configuration.
typedef struct{
TDRV009_CRC_TYPE Type;TDRV009_ENABLE_DISABLE RxChecking;TDRV009_ENABLE_DISABLE TxGeneration;TDRV009_CRC_RESET ResetValue;
} TDRV009_CRC;
Type
This parameter describes the CRC type to be used. Possible values are:Value Description
TDRV009_CRC_16 16bit CRC algorithm is used for checksum
TDRV009_CRC_32 32bit CRC algorithm is used for checksum
RxChecking
This parameter enables or disables the receive CRC checking. Possible values are:Value Description
TDRV009_DISABLED CRC checking will not be used
TDRV009_ENABLED CRC checking will be used
TxGeneration
This parameter enables or disables the transmit CRC generation. Possible values are:Value Description
TDRV009_DISABLED A CRC checksum will be generated
TDRV009_ENABLED A CRC checksum will not be generated
ResetValue
This parameter describes the reset value for the CRC algorithm. Possible values are:Value Description
TDRV009_CRC_RST_FFFF CRC reset value will be 0xFFFF
TDRV009_CRC_RST_0000 CRC reset value will be 0x0000
TDRV009-SW-42 – VxWorks Device Driver Page 109 of 139
EXAMPLE
#include “tdrv009.h”
int fd;TDRV009_OPERATION_MODE_STRUCT OperationMode;int retval;
/*-------------------------------------------------Retrieve current configuration-------------------------------------------------*/
retval = ioctl(fd, TDRV009_GET_OPERATION_MODE, (int)&OperationMode);if (retval != ERROR){
/* function succeeded */printf( “Current speed: %d bps\n”, OperationMode.Baudrate );
}else{
/* handle the error */}
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. The supplied buffer pointer isNULL.
TDRV009-SW-42 – VxWorks Device Driver Page 110 of 139
5.5.3 TDRV009_SET_BPS
This I/O control function sets up the transmission rate for the specific channel. This is done without allthe other configuration stuff contained in TDRV009_SET_OPERATION_MODE. If async oversamplingis enabled, the desired baudrate is internally multiplied by 16. It is important that this result can bederived from the selected clocksource. This function specifies the desired frequency which should begenerated by the Baud Rate Generator (BRG). The function dependent parameter arg passes anunsigned long value containing the desired baudrate to the device driver.
EXAMPLE
#include “tdrv009.h”
…
int fd;unsigned long Baudrate;int retval;
…
/*-------------------------------------------------Set baudrate to 14400bps-------------------------------------------------*/
Baudrate = 14400;retval = ioctl(fd, TDRV009_SET_BPS, (int)Baudrate);if (retval != ERROR){
/* function succeeded */}else{
/* handle the error */}
…
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. The desired baudrate cannotbe derived from the selected clock source.
TDRV009-SW-42 – VxWorks Device Driver Page 111 of 139
5.5.4 TDRV009_FRAME_READ
This I/O control function reads one data buffer from the internal receive buffer. The function will returnimmediately, if data is available. If no data is available, the function will wait until data arrives, or thespecified timeout happens. The returned data buffer will be available until the next call to this I/Ocontrol function. The function specific control parameter arg is a pointer to aTDRV009_DATA_BUFFER structure.
typedef struct{
unsigned char *pData;unsigned long Length;unsigned long Valid;int Overflow;int Timeout;
} TDRV009_DATA_BUFFER;
pData
Pointer to the receive data section. This pointer directly references the driver’s internal receivebuffer. It points to the beginning of the corresponding data frame. Do not free the associatedmemory section!
Length
Number of valid data bytes for this data buffer.
Valid
This value specifies if the corresponding data buffer contains valid data, or if the read databuffer also contains a “Frame End”. The given values can be binary OR’ed. Possible values are:
Value Description
TDRV009_RXBUF_DATAVALID Current data block contains valid (unread) data.
TDRV009_RXBUF_FRAMEEND Current data block is the last one of a receiveddata frame.
Overflow
This value specifies if a buffer overrun has happened. The automatically stopped receiver isenabled again after the read access.
Timeout
This value specifies the maximum time to wait for incoming data. The timeout is specified insystem ticks.
TDRV009-SW-42 – VxWorks Device Driver Page 112 of 139
EXAMPLE
#include “tdrv009.h”
…
int fd;TDRV009_DATA_BUFFER DataBuf;int retval;
…
/*-------------------------------------------------Read a data buffer. Wait max. 120 ticks.-------------------------------------------------*/
DataBuf.Timeout = 120;retval = ioctl(fd, TDRV009_FRAME_READ, (int)&DataBuf);if (retval != ERROR){
/* function succeeded */printf( “%d data bytes received.\n”, DataBuf.Length );if (DataBuf.Overflow){
printf( “Data was lost due to a buffer overflow.\n” );}
}else{
/* handle the error */}
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. The supplied buffer pointer isNULL.
EBUSY The channel is busy with a pending read operation.
EACCES An external ringbuffer is used, so this function is notsupported at the moment.
ETIME The specified timeout occurred.
TDRV009-SW-42 – VxWorks Device Driver Page 113 of 139
5.5.5 TDRV009_FRAME_WRITE
This I/O control function transmits one data buffer. The function will return immediately after handingover the buffer to the driver. It is possible to wait until the supplied data buffer is transferred to thehardware FIFO. This can be done either by waiting on the specified semaphore, or by polling thestatus parameter. The function specific control parameter arg is a pointer to aTDRV009_TX_DATA_BUFFER structure.
typedef struct{
unsigned char *pData;unsigned long Length;unsigned long Status;SEM_ID WaitSema;
} TDRV009_TX_DATA_BUFFER;
pData
Pointer to the data section containing the data to be transmitted. This buffer must be physicallycoherent. Make sure that the data buffer is not modified during transmission.
Length
Number of data bytes for this data buffer.
Status
This value contains the current status of this transmit data packet. Possible values are:Value Description
TDRV009_TXDATA_BUSY Data buffer is currently in use. Do not modify it.
TDRV009_TXDATA_COMPLETED Data buffer is completed. The data is at leasttransferred into the hardware FIFO.
WaitSema
This value holds a semaphore created by the user. This semaphore will be signaled after thedata buffer is processed.
TDRV009-SW-42 – VxWorks Device Driver Page 114 of 139
EXAMPLE
#include “tdrv009.h”
int fd;TDRV009_TX_DATA_BUFFER TxDataBuf;unsigned char* pData;int retval, result;
/*-------------------------------------------------Send a data buffer. Wait max. 120 ticks for completion-------------------------------------------------*/
pData = cacheDmaMalloc( 20*sizeof(unsigned char) );sprintf(pData, “Hello World!”);TxDataBuf.Status = 0;TxDataBuf.WaitSema = semBCreate(SEM_Q_FIFO, SEM_EMPTY);TxDataBuf.pData = pData;TxDataBuf.Length = strlen(pData);retval = ioctl(fd, TDRV009_FRAME_WRITE, (int)&TxDataBuf);if (retval != ERROR){
/*** function succeeded, wait for completion of the data packet.*/result = semTake( TxDataBuf.WaitSema, 120 );if (result == OK){
printf( “data buffer processed\n” );} else {
printf( “data buffer still busy\n” );}
}else{
/* handle the error */}
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. The supplied buffer pointer isNULL.
EBUSY The channel is busy with a pending read operation.
TDRV009-SW-42 – VxWorks Device Driver Page 115 of 139
5.5.6 TDRV009_WRITEBUF_DONE
This I/O control function checks the current state of a transmit data buffer, which was previouslyhanded over to the driver using the write() function. If the buffer has already been processed (i.e. datawas transferred to the hardware FIFO), the function returns OK. If the buffer has not been processed,the function will return ERROR with an appropriate error code. The function dependent parameter argpasses an unsigned char pointer to the device driver.
EXAMPLE
#include “tdrv009.h”
int fd;unsigned char* pData;int retval;
/*-------------------------------------------------send TX data buffer-------------------------------------------------*/
retval = write( fd, pData, ...);...
/*-------------------------------------------------check state of a TX data buffer-------------------------------------------------*/
retval = ioctl(fd, TDRV009_WRITEBUF_DONE, (int)pData);if (retval == OK){
/* function succeeded */printf( “Data buffer completed.\n” );
}else{
/* handle the error */}
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. The supplied pointer is NULL.
EBUSY The data buffer is still in use. Do not modify or free thebuffer.
TDRV009-SW-42 – VxWorks Device Driver Page 116 of 139
5.5.7 TDRV009_RINGBUFFER_REGISTER
This command provides a user-supplied ringbuffer to the driver using a pointer to a dynamicTDRV009_RINGBUFFER structure. The buffer consists of a header and a dynamically expandabledata section. The driver formats the allocated buffer automatically according to the specification. Theuser must ensure that the buffer persists as long as it is registered to the driver. The buffer must bephysically coherent, because direct memory access is used. Please refer to the following figure forfurther information.
The TDRV009_RINGBUFFER structure has the following layout:
typedef struct{
TDRV009RINGBUFFER_HEADER Header;unsigned char DataSection[40]; /* dynamically expandable buffer */
} TDRV009_RINGBUFFER;
Header
Contains administrative information used for buffer management.
DataSection
Inside the data section the real data buffers and their corresponding entry information is stored.
The TDRV009_RINGBUFFER_HEADER structure has the following layout:
typedef struct{
unsigned long BufferSize; /* total size of memory available for data */unsigned long PacketSize; /* size of one data packet, adjusted by driver */unsigned long NumberOfEntries; /* number of entries */unsigned long get; /* index where data can be read */unsigned long put; /* current index where new data is filled in */unsigned long Overflow; /* TRUE if an overflow happened. Receiver is disabled. */
} TDRV009_RINGBUFFER_HEADER;
TDRV009-SW-42 – VxWorks Device Driver Page 117 of 139
Members (TDRV009_RINGBUFFER_HEADER)
BufferSize
Memory size available for the complete data buffers.
PacketSize
Memory size available for one data packet. The complete data buffer is divided into severalpackets matching the specified PacketSize.
NumberOfEntries
Number of available single buffers. This value is calculated out of BufferSize and PacketSize.Read Only.
get
Indicates the index where new data can be read out of the ringbuffer.
put
Indicates the index where the driver fills in new arrived data. Read Only.
Overflow
Indicates if a buffer overflow has happened. After a buffer overflow the receiving channel isdisabled and must be enabled again by hand. Read Only.
The TDRV009_RINGBUFFER_ENTRY structure has the following layout:
typedef struct{
unsigned long NumberOfBytes; /* number of valid bytes for the current buffer index */unsigned long Size; /* total size of the current buffer */unsigned long Offset; /* offset into the data section where the buffer starts */unsigned long DmaAddress; /* physical address for the dma controller */unsigned long Valid; /* TRUE if the current buffer contains valid data */
} TDRV009_RINGBUFFER_ENTRY;
Members (TDRV009_RINGBUFFER_HEADER)
NumberOfBytes
This value indicates the number of valid bytes inside the corresponding buffer. Read Only.
Size
This value indicates the total size of the corresponding data buffer. Read Only.
TDRV009-SW-42 – VxWorks Device Driver Page 118 of 139
Offset
This value specifies the offset relative to the beginning of the data section, where thecorresponding data buffer starts. Read Only.
DmaAddress
This value states the physical address of the data buffer used by the DMA controller. ReadOnly.
Valid
This value indicates if the corresponding data buffer contains valid data. This is the only valuethat should be modified by the user.
To ensure the correct functionality of the ringbuffer mode, do not change any of theadministrative read-only information values.
TDRV009-SW-42 – VxWorks Device Driver Page 119 of 139
Assistant Macros and Functions for Buffer handling
To help the user work with this ringbuffer concept some assistant macros and functions were definedin “tdrv009.h”. They are explained in the following.
CALCULATE_RINGBUFFER_SIZE( BufferSize, PacketSize )calculates the total size necessary for allocation of the complete ringbuffer
GET_BUFFER( pRingBuffer, index )returns a pointer to the corresponding data buffer
IS_VALID( pRingBuffer, index )TRUE if the corresponding buffer contains valid data, otherwise FALSE
SET_VALID( pRingBuffer, index, value )sets the Valid-flag for the specified entry to value
CLEAR_BUFFER( pRingBuffer, index )clears the corresponding data buffer
GET_POS( pRingBuffer )returns the current get-position where new data can be read
OVERFLOW( pRingBuffer )TRUE if a buffer overflow has happened, otherwise false
unsigned char*GetNewBuffer( TP862_RINGBUFFER* pRingBuffer, ULONG* length );
returns a pointer to a buffer containing new data. The get-position is set to the next entry, thenumber of valid bytes is returned in length. The previous data buffer is marked as invalid, so thedriver may reuse this buffer for data reception.
For further information on how to deal with the ringbuffer, the special assistant macros and functions,please refer to the provided example application.
TDRV009-SW-42 – VxWorks Device Driver Page 120 of 139
Example
#include “tdrv009.h”
int fd;int retval;TDRV009_RINGBUFFER* pRingBuffer;
#define BUFFER_SIZE 5000#define PACKET_SIZE 100
/*-----------------------------------------------------------allocate memory for ringbuffer (physically coherent, nonchached):
5000 bytes total data space100 bytes per packet
-----------------------------------------------------------*/pRingBuffer = (TDRV009_RINGBUFFER*)cacheDmaMalloc(
CALCULATE_RINGBUFFER_SIZE( BUFFER_SIZE, PACKET_SIZE ));
pRingBuffer->Header.BufferSize = BUFFER_SIZE;pRingBuffer->Header.PacketSize = PACKET_SIZE;
retval = ioctl( fd, TDRV009_RINGBUFFER_REGISTER, (int)pRingBuffer);if (retval != OK){
/* process Ioctl error */}
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. The supplied buffer pointer isNULL.
EBUSY A ringbuffer is already registered. Unregister it first.
ENOMEM Not enough memory available to create necessary receivedescriptor list.
EIO Error during reset or init of the receiver’s hardware DMAengine.
TDRV009-SW-42 – VxWorks Device Driver Page 121 of 139
5.5.8 TDRV009_RINGBUFFER_UNREGISTER
This command unregisters a previously registered user-ringbuffer. A channel-reset is performed andthe driver uses its internal ringbuffer to receive data again. No additional parameter is necessary.
Example
#include “tdrv009.h”
int fd;int retval;
/*** unregister the ringbuffer*/retval = ioctl( fd, TDRV009_RINGBUFFER_UNREGISTER, 0);if (retval != OK){
/* process Ioctl error */}
ERROR CODES
Error code Description
EACCES No external ringbuffer is used, so this function is notsupported at the moment.
EIO Error during reset or init of the receiver’s hardware DMAengine.
TDRV009-SW-42 – VxWorks Device Driver Page 122 of 139
5.5.9 TDRV009_SET_RECEIVER_STATE
This command sets the channel’s receiver either to active or inactive. This function must be called inuser-ringbuffer-mode, after a buffer-overflow has happened and free receive buffers are availableagain.
The parameter arg passed to this Ioctl function defines the new state of the receiver. Possible valuesare:
Value DescriptionTDRV009_RCVR_ON The receiver is enabled.TDRV009_RCVR_OFF The receiver is disabled.
Example
#include “tdrv009.h”int fd;int retval;
/*** enable the receiver*/retval = ioctl( fd, TDRV009_SET_RECEIVER_STATE, TDRV009_RCVR_ON);if (status != OK){
/* process Ioctl error */}
ERROR CODES
Error code Description
EINVAL Invalid parameter specified.
TDRV009-SW-42 – VxWorks Device Driver Page 123 of 139
5.5.10 TDRV009_CLEAR_RX_BUFFER
This I/O control function removes all received data from the channels receive buffer, and flushes thehardware FIFO as well. The function dependent argument arg is not used for this function.
Example
#include “tdrv009.h”
int fd;int retval;
/*-----------------------------------------------------------Clear receive buffer-----------------------------------------------------------*/
retval = ioctl( fd, TDRV009_CLEAR_RX_BUFFER, 0);if (retval != OK){
/* process Ioctl error */}
ERROR CODES
Error code Description
EIO Error during reset or init of the receiver’s hardware DMAengine.
TDRV009-SW-42 – VxWorks Device Driver Page 124 of 139
5.5.11 TDRV009_EEPROM_WRITE
This I/O control function writes one 16bit word into the onboard EEPROM. The first part of theEEPROM is reserved for factory usage, write accesses to this area will result in an error. The functionspecific control parameter arg is a pointer to a TDRV009_EEPROM_BUFFER structure.
typedef struct{
unsigned long Offset;unsigned long Value;
} TDRV009_EEPROM_BUFFER;
Offset
This parameter specifies a 16bit word offset into the EEPROM.Following offsets are available:
Offset Access
00h – 5Fh R
60h – 7Fh R / W
Value
This parameter specifies the 16bit word to be written into the EEPROM at the given offset.
EXAMPLE
#include “tdrv009.h”
int fd;TDRV009_EEPROM_BUFFER EepromBuf;int retval;
/*-------------------------------------------------Write a 16bit value into the EEPROM, offset 60h-------------------------------------------------*/
EepromBuf.Offset = 0x60;EepromBuf.Value = 0x1234;retval = ioctl(fd, TDRV009_EEPROM_WRITE, (int)&EepromBuf);if (retval != OK){
/* handle the error */}
TDRV009-SW-42 – VxWorks Device Driver Page 125 of 139
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. The supplied buffer pointer isNULL.
EACCES The specified offset address is invalid, or read-only.
TDRV009-SW-42 – VxWorks Device Driver Page 126 of 139
5.5.12 TDRV009_EEPROM_READ
This I/O control function reads one 16bit word from the onboard EEPROM. The function specificcontrol parameter arg is a pointer to a TDRV009_EEPROM_BUFFER structure.
typedef struct{
unsigned long Offset;unsigned long Value;
} TDRV009_EEPROM_BUFFER;
Offset
This parameter specifies a 16bit word offset into the EEPROM.Following offsets are available:
Offset Access
00h – 5Fh R
60h – 7Fh R / W
Value
This parameter returns the 16bit word from the EEPROM at the given offset.
EXAMPLE
#include “tdrv009.h”
int fd;TDRV009_EEPROM_BUFFER EepromBuf;int retval;
/*-------------------------------------------------Read a 16bit value into the EEPROM, offset 0-------------------------------------------------*/
EepromBuf.Offset = 0;retval = ioctl(fd, TDRV009_EEPROM_READ, (int)&EepromBuf);if (retval == OK){
printf( “Value = 0x%X\n”, EepromBuf.Value );}else{
/* handle the error */}
TDRV009-SW-42 – VxWorks Device Driver Page 127 of 139
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. The supplied buffer pointer isNULL.
EACCES Specified offset is invalid, and may not be accessed.
TDRV009-SW-42 – VxWorks Device Driver Page 128 of 139
5.5.13 TDRV009_RTS_SET
This I/O control function asserts the RTS handshake signal line of the specific channel. This function isnot available if the channel is configured for hardware handshaking. The function dependent argumentarg is not used for this function.
Example
#include “tdrv009.h”
int fd;int retval;
/*-----------------------------------------------------------Assert RTS-----------------------------------------------------------*/
retval = ioctl( fd, TDRV009_RTS_SET, 0);if (retval != OK){
/* process Ioctl error */}
ERROR CODES
Error code Description
EPERM The channel is in handshake mode, so this function is notallowed.
TDRV009-SW-42 – VxWorks Device Driver Page 129 of 139
5.5.14 TDRV009_RTS_CLEAR
This I/O control function de-asserts the RTS handshake signal line of the specific channel. Thisfunction is not available if the channel is configured for hardware handshaking. The functiondependent argument arg is not used for this function.
Example
#include “tdrv009.h”
int fd;int retval;
/*-----------------------------------------------------------De-assert RTS-----------------------------------------------------------*/
retval = ioctl( fd, TDRV009_RTS_CLEAR, 0);if (retval != OK){
/* process Ioctl error */}
ERROR CODES
Error code Description
EPERM The channel is in handshake mode, so this function is notallowed.
TDRV009-SW-42 – VxWorks Device Driver Page 130 of 139
5.5.15 TDRV009_CTS_GET
This I/O control function returns the current state of the CTS handshake signal line of the specificchannel. The function dependent argument arg passes a pointer to an unsigned long value to thedriver. Depending on the state of CTS, either 0 (inactive) or 1 (active) is returned.
Example
#include “tdrv009.h”
int fd;int retval;unsigned long CtsState;
/*-----------------------------------------------------------Read CTS state-----------------------------------------------------------*/
retval = ioctl( fd, TDRV009_CTS_GET, (int)&CtsState);if (retval == OK){
printf( “CTS = %ld\n”, CtsState );}else{
/* process Ioctl error */}
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. The supplied buffer pointer isNULL.
TDRV009-SW-42 – VxWorks Device Driver Page 131 of 139
5.5.16 TDRV009_DTR_SET
This I/O control function sets the DTR signal line to HIGH. This function is only available for channel 3.The function dependent argument arg is not used for this function.
Example
#include “tdrv009.h”
int fd;int retval;
/*-----------------------------------------------------------Set DTR to HIGH (only valid for channel 3)-----------------------------------------------------------*/
retval = ioctl( fd, TDRV009_DTR_SET, 0);if (retval != OK){
/* process Ioctl error */}
ERROR CODES
Error code Description
ENOTSUP This function is not supported by the specific channel.
TDRV009-SW-42 – VxWorks Device Driver Page 132 of 139
5.5.17 TDRV009_DTR_CLEAR
This I/O control function sets the DTR signal line to LOW. This function is only available for channel 3.The function dependent argument arg is not used for this function.
Example
#include “tdrv009.h”
int fd;int retval;
/*-----------------------------------------------------------Set DTR to LOW (only valid for channel 3)-----------------------------------------------------------*/
retval = ioctl( fd, TDRV009_DTR_CLEAR, 0);if (retval != OK){
/* process Ioctl error */}
ERROR CODES
Error code Description
ENOTSUP This function is not supported by the specific channel.
TDRV009-SW-42 – VxWorks Device Driver Page 133 of 139
5.5.18 TDRV009_DSR_GET
This I/O control function returns the current state of the DSR signal line. This function is only availablefor channel 3. The function dependent argument arg passes a pointer to an unsigned long value to thedriver. Depending on the state of DSR, either 0 (inactive) or 1 (active) is returned.
Example
#include “tdrv009.h”
int fd;int retval;unsigned long DsrState;
/*-----------------------------------------------------------Read DSR state-----------------------------------------------------------*/
retval = ioctl( fd, TDRV009_DSR_GET, (int)&DsrState);if (retval == OK){
printf( “DSR = %ld\n”, DsrState );}else{
/* process Ioctl error */}
ERROR CODES
Error code Description
ENOTSUP This function is not supported by the specific channel.
EINVAL Invalid parameter specified. The supplied buffer pointer isNULL.
TDRV009-SW-42 – VxWorks Device Driver Page 134 of 139
5.5.19 TDRV009_SET_EXT_XTAL
This I/O control function specifies the frequency of an externally provided clock. This frequency isused for baudrate calculation, and describes the input frequency to the Baud Rate Generator (BRG).The external frequency may be supplied either at input line TxC or RxC. The function dependentargument arg passes the clock frequency in Hz.
Example
#include “tdrv009.h”
int fd;int retval;
/*-----------------------------------------------------------Specify 1000000Hz as external clock frequency-----------------------------------------------------------*/
retval = ioctl( fd, TDRV009_SET_EXT_XTAL, 1000000);if (retval != OK){
/* process Ioctl error */}
ERROR CODES
Error code Description
EINVAL Invalid parameter. The specified frequency must be largerthan 0.
TDRV009-SW-42 – VxWorks Device Driver Page 135 of 139
5.5.20 TDRV009_REGREAD
This I/O control function reads one 32bit word from the communication controller’s register space. Thefunction specific control parameter arg is a pointer to a TDRV009_ADDR_STRUCT structure.
typedef struct{
unsigned long Offset;unsigned long Value;
} TDRV009_ADDR_STRUCT;
Offset
This parameter specifies a byte offset into the communication controller’s register space. Pleaserefer to the hardware user manual for further information.
Value
This parameter returns the 32bit word from the communication controller’s register space.
EXAMPLE
#include “tdrv009.h”
int fd;TDRV009_ADDR_STRUCT AddrBuf;int retval;
/*-------------------------------------------------Read a 32bit value (Version Register)-------------------------------------------------*/
AddrBuf.Offset = 0x00F0;retval = ioctl(fd, TDRV009_REGREAD, (int)&AddrBuf);if (retval == OK){
printf( “Value = 0x%lX\n”, AddrBuf.Value );} else {
/* handle the error */}
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. The supplied buffer pointer isNULL.
EACCES The specified offset is invalid.
TDRV009-SW-42 – VxWorks Device Driver Page 136 of 139
5.5.21 TDRV009_REGWRITE
This I/O control function writes one 32bit word to the communication controller’s register space. Thefunction specific control parameter arg is a pointer to a TDRV009_ADDR_STRUCT structure.
typedef struct{
unsigned long Offset;unsigned long Value;
} TDRV009_ADDR_STRUCT;
Offset
This parameter specifies a byte offset into the communication controller’s register space. Pleaserefer to the hardware user manual for further information.
Value
This 32bit word will be written to the communication controller’s register space.
Modifying register contents may result in communication problems, system crash or otherunexpected behavior.
EXAMPLE
#include “tdrv009.h”
int fd;TDRV009_ADDR_STRUCT AddrBuf;int retval;
/*-------------------------------------------------Write a 32bit value (FIFO Control Register 4)-------------------------------------------------*/
AddrBuf.Offset = 0x0034;AddrBuf.Value = 0xffffffff;retval = ioctl(fd, TDRV009_REGWRITE, (int)&AddrBuf);if (retval != OK){
/* handle the error */}
TDRV009-SW-42 – VxWorks Device Driver Page 137 of 139
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. The supplied buffer pointer isNULL.
EACCES The specified offset is invalid.
TDRV009-SW-42 – VxWorks Device Driver Page 138 of 139
5.5.22 TDRV009_WAITFORINTERRUPT
This I/O control function waits until a specified SCC-interrupt or the timeout occurs. The functionspecific control parameter arg is a pointer to a TDRV009_WAIT_STRUCT structure.
typedef struct{
unsigned long Interrupts;int Timeout;
} TDRV009_WAIT_STRUCT;
Interrupts
This parameter specifies interrupt bits to wait for. If one interrupt occurs, the value is returned inthis parameter. Please refer to the hardware user manual for further information on the possibleSCC interrupt bits.
Timeout
This parameter specifies the time (in system ticks) to wait for an interrupt. If -1 is specified, thefunction will block indefinitely.
EXAMPLE
#include “tdrv009.h”
int fd;TDRV009_WAIT_STRUCT WaitStruct;int retval;
/*-------------------------------------------------Wait at least 60 system ticks for aCTS Status Change (CSC) interrupt-------------------------------------------------*/
WaitStruct.Interrupts = (1 << 14);WaitStruct.Timeout = 60;retval = ioctl(fd, TDRV009_WAITFORINTERRUPT, (int)&WaitStruct);if (retval == OK){
printf( “Occurred Interrupt = 0x%lX\n”, WaitStruct.Interrupts );}else{
/* handle the error */}
TDRV009-SW-42 – VxWorks Device Driver Page 139 of 139
ERROR CODES
Error code Description
EINVAL Invalid parameter specified. The supplied buffer pointer isNULL.
EBUSY Too many simultaneous wait jobs active.
S_objLib_OBJ_TIMEOUT Timeout happened.