Simulate Translate Test

Using the DFTDirect API

The DFTDirect API gives CAE tool developers direct access to the digital test data contained in simulation and ATPG data files without the bother and overhead of developing a parser. It produces a real-time event stream that replicates the waveforms being applied to the device under test. It also provides access to all Signal Name, Signal Type, Timing, ScanChain, and FreeRunningClock data. This data can be used for simulation, emulation, graphical waveform display, power/current analysis, as well as a variety of timing analysis tasks.

DFTDirect currently supports WGL and STIL source formats and more are planned. The DFTDirect interface is the same regardless.


DFTDirect is provided to the customer as a linkable library and header file that can be integrated into customer applications where access to WGL and STIL data is needed. It also includes the VTRAN WGL and STIL canned readers. These readers are the same standalone executables reliably used for years to support VTRAN translations. For optimal perfomance, a pipe is established between the reader and DFTDirect so that the readers and DFTDirect can run concurrently. The customer application program simply needs to include the header file, declare the user VECFILE_DATA structure, and call API routines to initiate the retrieval of data from the WGL/STIL source files. All data is made available to the user via the user VECFILE_DATA structure and no parsing of STIL or WGL syntax is ever necessary .

Note: The examples in this application note are written in C, but with the appropriate interface most any language (i.e. Python, Tcl, Perl, Java, Ruby, etc...) can be used with the static library and the headers supplied in the DFTDirect software bundle. For more information on using DFTDirect with languages other than C, contact SourceIII.

Using the DFTDirect API®


The DFTDirect API Sofware Bundle is distributed in the form of a gzipped tarball. It contains the following files:

        vread.bin               Canned reader map file 
        vread3.bin              Canned reader, a standalone executable that loads WGL
        vread5.bin              Canned reader, a standalone executables that loads STIL

        lib/libVREAD.a          linkable library
        include/VREAD_lib.h     C header file

        README.txt              API general information
        README10.4              API release notes
        DFTDirect_Guide.pdf     API technical manual

        vlite.c                 Sample C program which demonstrates the API

        Makefile                Sample Makefile which can be used to build
                                vlite, and as a template for your own Makefiles

        include/AppNote_Routines.c	Routines from the Application Note
	examples/MyApp_STIL.c		Example C file referenced in the Application Note
	examples/MyApp_WGL.c		Example C file referenced in the Application Note
	examples/MySourceFile.stil 	Example STIL filereferenced in the Application Note
	examples/MySourceFile.wgl	Example WGL file referenced in the Application Note
	examples/MyApp_STIL.log 	Output of MyApp_STIL
	examples/MyApp_WGL.log		Output of MyApp_WGL 
        examples/Makefile               Sample Makefile which can be used to build the examples

The entire bundle should be unpacked into a single directory.

  • Copy the tarball into /usr/local/MyApp/support
  • Unpack the tarball in /usr/local/MyApp/support
  • 	cd /usr/local/MyApp/support
    	tar zxvf linux64_dftdirect_tar.gz
  • Set environment variable S3_DFTDIRECT_LIB to point to the directory containing the unpacked files. For example, to set the S3_DFTDIRECT_LIB environment variable in the sh shell, type:
  • 	export S3_DFTDIRECT_LIB=/usr/local/MyApp/support/linux64

User Code Example

See how the user can use the DFTDirect API to access to the data in a STIL file in the user application example called MyApp_STIL.c shown below.

#include <stdio.h>
#include <stdlib.h>
#include <malloc.h>
#include <string.h>
#include <ctype.h>
#include "VREAD_lib.h"

#include "AppNote_Routines.c"

int main(int argc, char *argv[])
        VECFILE_DATA my_vec_data;
        int flag;

        flag = Read_Vec("STIL", "MySourceFile.stil", "SILENT\nINCLUDE_CELLS\nENABLE_IPC", &my_vec_data);
        if(flag==0) exit(0);

        flag = Read_Aux(&my_vec_data);
        if(flag==0) exit(0);


        while (1) {
                flag = Read_Event(&my_vec_data);
                if(flag==0) exit(0);
                if (my_vec_data.Event->type == EVENT_END) break;
                Dump_Event_Data(&my_vec_data, 0);


  • #include "VREAD_lib.h". It is the header file supplied in the DFTDirect software bundle and is what allows the user application to share the DFTDirect libary. It defines the VECFILE_DATA data structure and declares the DFTDirect function prototypes. VREAD_lib.h must be included in the user application.
  • the declaration of the local VECFILE_DATA structure called my_vec_data. This is the user accessible data structure and the declaration must be included in the user application.
  • the calls to Read_Vec() and Read_Aux(). These functions launch the reader module (STIL in this case) and load timing and structural data into the user accessible VECFILE_DATA data structure.
  • the repeated calls to Read_Event() to get event stream data.
  • the call to Reset_All(). This function clears and resets all variables and structures that may have been used during the process. Reset_All() allows for the reading of multiple WGL and/or STIL files successively by the application.

The declaration of the local VECFILE_DATA structure and the calls to Read_Vec(), Read_Aux(), Read_Event, and Reset_All() are common to all application programs. Processing the local VECFILE_DATA structure is potentially unique to the user application. The Dump Data functions, used here, are provided in AppNote_Routines.c (included in the DFTDirect software bundle) and are just an example of how the fields in the VECDATA_FILE structure can be processed. These functions simply dump the contents of the local VECFILE_DATA structure to stdout. They can be used with all source file formats.

Compilation of User Code

These are the commands needed to compile and link the MyApp_STIL.c shown above.

	gcc -I$S3_DFTDIRECT_LIB/include -c MyApp_STIL.c
	gcc -o MyApp_STIL MyApp_STIL.o -L$S3_DFTDIRECT_LIB/lib -lVREAD -ldl

There is a sample makefile called Makefile comes in the distribution bundle. It is a DFTDirect build system for Linux and Solaris. See the DFTDirect_Guide.pdf for more information.

Primary Functions and Parameters

The primary DFTDirect API functions are:

  • int Read_Vec(char *Fileformat, char *Filename, char *params, VECFILE_DATA *Vdata);
  • int Read_Aux(VECFILE_DATA *Vdata);
  • int Read_Event(VECFILE_DATA *Vdata);
  • int Reset_all(VECFILE_DATA *Vdata);

Each of these functions pass the pointer to the local VECFILE_DATA structure. The Read_Vec() function also specifies the source file format, the source file name, and a string buffer (params) containing user selectable parameters separated by '\n' character. The params string:


is used in the MyApp_STIL.c example shown earlier. It causes the DFTDirect execution to

  • operate in SILENT mode, i.e. inhibit reader and VREAD_lib-generated terminal output
  • preserve all scan cell data contained in the original vector file
  • run the readers in parallel with the API function calls Read_Vec(), Read_Aux(), and Read_Event().

Other parameters are available. See the DFTDirect_Guide.pdf for information for a complete list.


The user must create a locally accessible data structure of the type VECFILE_DATA and then pass the address (a pointer) of this structure to the DFTDirect function. The DFTDirect Read_Vec(), Read_Aux(), and Read_Event() functions load the local data structure and the user application extracts the data of interest. For the best results, the user should understand the organization of the VECFILE_DATA structure.

The VECFILE_DATA structure stores signal data, timing data, scan data, free running clock data, and event data. See below.

typedef struct
        int pin_cnt;			/* Signal Data */
        char **pin_nam;
        int *pin_type;

        VREAD_TIMESET **Tset;		/* Timing Data */
        int TsetCnt ;

        VREAD_SCANCHAIN **Scan;		/* Scan Data */
        int ScanCnt ;
        int MaxScanData;

        VREAD_FRC *FRCs;		/* Free Running Clock Data */
        int FrcCnt;

        VREAD_EVENT *Event; 		/* Event Data */

        char vec_file_name[FILE_NAME_LEN]; 	/*  Internal */
        char aux_file_name[FILE_NAME_LEN]; 	/*  Internal */
        char trc_file_name[FILE_NAME_LEN]; 	/*  Internal */
        char sts_file_name[FILE_NAME_LEN]; 	/*  Internal */
        FILE *f_vec; 				/*  Internal */
        FILE *f_aux; 				/*  Internal */
        FILE *f_trc; 				/*  Internal */
        FILE *f_sts; 				/*  Internal */

        char *ErrMsg;			/* Error Message String */

Signal Data

The VECFILE_DATA structure identifies name and direction ( pin_type: TYPE_INPUT, TYPE_OUTPUT, TYPE_BIIN, or TYPE_BIOUT ) for each signal in the source file. The pin_cnt specifies the total number of signals. For bidirectional signals both the input track state and the output track state are created. Pin indexes start with 1.

pin_type values are:

#define TYPE_INPUT     0       /* pin_type is input */
#define TYPE_OUTPUT    1       /* pin_type is output */
#define TYPE_BIIN      2       /* pin_type is bidirectional input */
#define TYPE_BIOUT     3       /* pin_type is bidirectional output */

The Dump_Signal_Data() routine used in the code example to access this data looks like:

void Dump_Signal_Data(VECFILE_DATA *my_vec_data)
        int i, j;
        fprintf(stdout, "\n");

        (void) fprintf(stdout, "Pin_Index Direction Name: #pins=%d\n",
        for (i = 1; i<= my_vec_data->pin_cnt; i++) {            // pin index begins at 1
                (void) fprintf(stdout, "%5.d     ", i);
                if((j=my_vec_data->pin_type[i])==5) continue;
                switch (my_vec_data->pin_type[i]) {
                        case TYPE_INPUT:
                                (void)fprintf(stdout, "In       ");
                        case TYPE_OUTPUT:
                                (void)fprintf(stdout, "Out      ");
                        case TYPE_BIIN:
                                (void)fprintf(stdout, "I/O In   ");
                        case TYPE_BIOUT:
                                (void)fprintf(stdout, "I/O Out  ");
                                (void)fprintf(stdout, "?        ");
                (void) fprintf(stdout," %s \n", my_vec_data->pin_nam[i]);

Timing Data

The source file timeset information is stored in an array of VREAD_TIMESET structures (one for each timeset) called Tset. This includes the timeset names, the cycle lengths (in nanoseconds) and the waveform descriptions (states and edges) for each signal. The number of timesets is specified in TsetCnt. Indexes into this array start at 1. There are parallel presentations of the waveform descriptions within VREAD_TIMESET. The VREAD_WFMTBL is described here. This format is the same regardless of source file format.

The VREAD_TIMESET structure looks like:

typedef struct
        char Name[1025];
        double Cycle;
        char **Type;    /* unused in WfmTbl representation */
        char **wfc;     /* unused in WfmTbl representation */
        char **state;   /* unused in WfmTbl representation */
        double **time;  /* unused in WfmTbl representation */
        VREAD_WFMTBL *WfmTbl;

For each timeset there is a VREAD_WFMTBL. Inside the VREAD_WFMTBL is a VREAD_PIN array, one structure for each pin.

typedef struct
{        /* the signal list for this Tset (1 - pin_cnt) */
        int pin_cnt;
        VREAD_PIN **Pin;

All the waveforms on a given pin are stored in an array of VREAD_WAVEFORM structures, one for each waveform behaviour..

typedef struct
{        /* the collection of waveform descriptions for a pin ( 0 - waveform_cnt) */
        int waveform_cnt;
        VREAD_WAVEFORM **Waveform;

Each VREAD_WAVEFORM structure contains a WaveForm Char and state/edgetime arrays that describe the waveform.

typedef struct
{       /* waveform description in terms of states and edges ( 0 - event_cnt ) */
        char wfc;
        int event_cnt;
        char *state;
        double *edgetime;

Product Support