Welcome to VTRAN®! VTRAN® is a powerful vector translation tool that translates vectors to and from a variety of IC development environments with virtually any data manipulation desired. Over 30 popular logic simulator and tester formats as well as user defined formats are supported. The frustration of dealing with dissimilar simulator data formats is eliminated with VTRAN®. Common uses of VTRAN® include

• Re-formatting existing simulation data files which were generated by one simulator into files compatible with another simulator.
• Translating state data files from logic analyzers, test programs or other data sources into stimulus files compatible with logic simulators. This includes the incorporation of pin timing.
• Modifying simulation data files including changing pin lists, pin order, bus radixes, time offsets, pin timing and time scaling.
• Translating simulation/ATPG output vector data or test programs into testbench data files for Verilog/VHDL re-simulation and verification.
• Vector translation from simulation or ATPG-generated vectors into functional test vectors for physical device testers.
• Act as a front-end to graphical waveform tools enabling them to read and display nearly any vector data file.

This application note provides all the information necessary to get started using VTRAN®.

VTRAN® is available for Solaris 32-bit, Solaris 64-bit, Linux 32-bit, and Linux 64-bit operating systems. To install VTRAN® on your system:

• Go to www.sourceiii.com/support.php#downloads
• Create a working directory on your local machine:

  mkdir source3 *

• Select the desired software bundle on the web page.
• Download by pressing the RMB and "Save Link Target As..." into your local directory *
• Select and download the INTERFACES bundle which includes example files and documentation on popular translations.
• Create and populate your working directory with the executables and examples using the UNIX "gunzip" and "tar" utilities - for example:

  
  
  
  gunzip linux64_vtran_tar.gz * 
  
  
  
  tar xvfp linux64_vtran_tar * 
  
  
  
  gunzip INTERFACES_tar.gz * 
  
  
  
  tar xvfp INTERFACES_tar * 

• Set the environment variable "S3_ROOT" to the name of the directory created by the tar operation on the downloaded software bundle in your shell startup script (i.e. .cshrc, .login)

  setenv S3_ROOT /usr/source3/linux64 *

• Include S3_ROOT in your search path in your shell startup script - for example

  set path=(. /bin /usr/bin /etc /usr/source3/linux64 .....) *

• Initialize your environment by logging out and logging back in or In C shell use

  
  
  
  source .cshsrc
  
  
  
  or
  
  
  
  source .login

Usage of commands may vary depending on operating system, shell, and the name of the software bundle selected.

The license file that contains the enabling keys for the software is provided in "sdmt.enable". Place this file in the S3_ROOT directory created above.

To use only the PREVIEW key that allows VTRAN® to run in a full feature mode but limits the number of vectors which can be translated to a few hundred, use the sdmt.preview file contained in the software bundle. Copy this file to sdmt.enable in the S3_ROOT directory.

cd $S3_ROOT *



cp sdmt.preview sdmt.enable *

Evaluation license keys can be requested by filling in the form at www.sourceiii.com/support.php#evaluation-keys. If you have received an evaluation license key after requesting it from Source III, place the full license key line at the top of the sdmt.enable file in your VTRAN® directory.

* Usage of commands may vary depending on operating system, shell, and the name of the software bundle selected.

The VTRAN® vector translator is invoked from the command line with the name of a VTRAN® command file. The Original Vector File (file to be translated) and the name of the Target Vector File (file to contain the translated results) can be specified either on the command line or in the command file.

vtran cmd_file [ovf file] [tvf_file]

To run a VTRAN® translation example, go the the INTERFACES directory created above.

cd /usr/source3/INTERFACES/AGILENT93K/EVCDHP93K *



vtran exp1.vtran

VTRAN® has other modes of execution. These include:

• HOSTID mode - retrieves the hostid on Solaris and Linux for the purpose of generating node-locked licences. HOSTID is immediately available after installing the VTRAN® software bundle by typing:

  vtran -hostid

• PINS mode - extracts the signal names and directions from an Original Vector File supported by a canned reader for the purpose of verifying signal names or generating pin lists for use in the VTRAN® command file.

  vtran -pins 

  For example:

  vtran -pins verilog_vcd sim.log > pins.log

  Places the names of all the pins in the simulation vector vcd file "sim.log" into a file names "pins.log" using the redirection feature of UNIX.

• CHECK mode - verifies the integrity of the VTRAN® command file syntax without doing any significant vector processing

  vtran -check

• VERSIONS mode - produces VTRAN® header with S3_ROOT setting and the versions of all canned readers currently being used.

  vtran -versions 

On-line support for VTRAN® is available on the Source III web site at www.sourceiii.com. Common problems related to the system environment are covered on the Source III FAQs page at www.sourceiii.com/support.php#faqs. A VTRAN® manual, Data Sheet, Training Foils, and a series of Application Notes can be found at www.sourceiii.com/product-vtran.php and www.sourceiii.com/support.php#application-notes. Additionally the software and INTERFACES downloads are rich with README files.

VTRAN® is invoked from the command line with the name of the VTRAN® command file. This command file is divided into three blocks that reflect the three fundamental tasks that comprise the VTRAN® translation process. These blocks are:

• OVF_BLOCK - The Original Vector File Block
• PROC_BLOCK - The Process Block
• TVF BLOCK - The Target Vector Block

The OVF_BLOCK is used to tell VTRAN® how to read the Original Vector File (OVF). The PROC_BLOCK contains commands that tell VTRAN® what data processing functions to perform on the original vector data during translation. Finally, the TVF_BLOCK contains commands that specify the desired output format and optional reporting parameters.

Note: VTRAN® command statement text is not case sensitive. Comments can be placed inside {}.

VTRAN®'s reader technology enables it to read almost any simulation data file. VTRAN® includes canned readers for many print-on-change and cycle-based formats such as Verilog VCD/EVCD, WGL, and STIL as well as support for user defined formats. In many cases, the selection of the original vector file format is the only command needed in the OVF block. Other commands are needed when the selected input format does not inherently provide all the information that VTRAN® needs. This is most often limited to directional data.

Selecting the Original Vector File Format

Either (not both) the SCRIPT_FORMAT or TABULAR_FORMAT command is used to specify the reader interface. Some examples are:

SCRIPT_FORMAT verilog_vcd [params];



SCRIPT_FORMAT verilog_vcdf [params];



TABULAR_FORMAT wgl [params];



TABULAR_FORMAT stil [params];

For each format, there are a number of optional parameters [params]. These parameters vary with the selected reader. For example, parameters for the STIL reader include:

TABULAR_FORMAT STIL



  -cycle



  -scan



  -include_cells



  -expand_loops



  -expand_reps



  -one_loop_level



  patternexec="xyz"



  -allow_undef_wfc



  ;

A complete list of supported canned reader interfaces and their parameter lists can be found in Appendix E VTRAN® User's Guide.

Original Vector File Formats with Signal Direction Information

In the case of a well known format, VTRAN® most likely has a canned reader. If this format also allows VTRAN® to automatically determine signal direction (as is the case with Verilog EVCD, WGL, STIL,) there is often very little information actually needed in this block. Here is an example of a complete OVF block when the format of the Original Vector File is STIL:

OVF_BLOCK



  BEGIN



  SCRIPT_FORMAT STIL -cycle, -scan;



  ORIG_FILE = "filename.stil";



  END

Original Vector File Formats WITHOUT Signal Direction Information

Once again, in the case of a well known format, VTRAN® most likely has a canned reader. If this format does not, however, allow VTRAN® to automatically determine signal direction (as is the case with Verilog VCD), pin declarations are required. INPUTS, OUTPUTS, and BIDIRECTS commands are used for this purpose. They can be used in any order and as many times as desired to specify the signals you wish to have read from the original vector file. Note that the order of declarations also determines the order of the signals in the output vector file. Here is an example of a complete OVF block when the format of the Original Vector File is Verilog VCD:

OVF_BLOCK



  BEGIN



  SCRIPT_FORMAT Verilog_vcd;



  INPUTS pin1, pin2, pin3, clka, clkb, dbus[31:0];



  OUTPUTS opbus[7:0], ackn, red;



  BIDIRECTS iobus[15:0];



  INPUTS ioctrl;



  ORIG_FILE = "filename.vcd";



  END

User-Programmed Reader

When no canned reader exists to read the format of the vectors in the original vector file, more information must be specified in the OVF block for the User-Programmed Reader. The INPUTS, OUTPUTS, and BIDIRECTS commands shown above, as well as the detailed user format descriptions in SCRIPT_FORMAT, TABULAR_FORMAT, and WAVEFORM_FORMAT commands are critical components in the successful input of User Formats. Additional commands that may be used to specify reader options for user formats include BEGIN_LINE, BEGIN_STRING, BUSFORMAT, WHITESPACE, CASE_SENSITIVE, GROUP, and MAX_UNMATCHED. See the VTRAN® User's Guide Section 3.0 for details on how to use these commands.

MERGE_FILE

Multiple vector files can be merged horizontally or vertically using VTRAN®. The original files may contain all the same signals (in which case the merge is actually a concatenation), all different signals, or there may be an overlap of some of the signals in some of the original files. See the Application Note titled "Merging Multiple Input Files" (www.sourceiii.com/notes-merge1.html) for more details.

Other Commands

VTRAN® also provides other commands for use in the OVF block that allow the user to specify generic reader options. They can be used in any of the situations listed above. See the VTRAN® User's Guide Section 3.0 for details on how to use these commands.

THE PROC_BLOCK contains commands that tell VTRAN® what data processing functions to perform on the OVF data during translation. At a minimum these functions will usually include state mapping. Other functions such as cyclization, bidirectional data control considerations, adding pins, masking pins, inserting statements, and modifying the timing of state transitions are dependent on the needs of the particular translation.

The processing functions occur in a predefined order and are not affected by the order in which they appear in the PROC block. Some information about the processing sequence is provided in the following discussion of each translation type. See the VTRAN® User's Guide Section 6.2 for more details.

State Mapping

State Mapping considerations apply to nearly every translation type. When using VTRAN® to reformat simulation stimulus and results files for use with another logic simulator or to translate a simulation or ATPG-generated file for use on a tester or for a simulation testbench, this may be the only PROC_BLOCK command needed.

The state characters used in the Original Vector File will most likely be different than those used in the Target Vector File. For example, in a standard Verilog VCD file, the state characters are 1, 0, X, Z, x, and z. The state character set used by a target vector format tester will vary. A typical set (say for a Credence tester) would be 1, 0, H, L, X, Z. It may also be desirable to map the Z state on outputs to an X so the checking is masked, and perhaps any X states on pure inputs to a valid 1 or 0 state. State mapping is accomplished using the STATE_TRANS command. The above example can be accomplished with:

STATE_TRANS inputs 'x'->'1', 'X'->'1', 'z'->'Z';



STATE_TRANS outputs '1'->H', '0'->'L', 'z'->'X',



            'Z'->'X',' 'x'->X';

Note the use of predefined signal group inputs and outputs. Other predefined signal groups are pure_inputs, pure_outputs, bidir_inputs, and bidir_outputs.

Important: STATE_TRANS is one of the last processes applied to the Original Vector File. This means that most all other processes invoked by the PROC block use the states directly from the OVF input file for logic expressions (i.e. before STATE_TRANS is applied).

Cyclization

Translations from print-on-change (POC) formats to cycle based formats require a process called cyclization. POC formats such as Verilog VCD, Mentor's LSIM, TSSI's TDS or Novas FSDB typically have state data and time entries in the vector file every time there is a state change on any pin. One can consider these as flat or time-expanded vectors. Cycle-based formats used by testers such as Credence, Teradyne and Verigy, however, use a single vector to combine all the state transitions that occur in a given time period or cycle. The cyclization commands tell VTRAN® how many print-on-change vectors should be collapsed into a cycle vector, how to gather meaningful state data, and target timing.

VTRAN® supports multiple cyclization flows and and can be used with POC files that have both single and multiple timesets. Here, timeset refers to a set of signal behaviors and an associated period. Multiple timeset POC file flows, use the TEMPLATE_CYCLIZATION feature of VTRAN®. This flow is described in detail in a separate Application Note titled "VTRAN® Template Cyclization Feature" (www.sourceiii.com/notes-temp_cyc.html). Single timeset POC file flows use the ALIGN commands and are described in the Application Note titled "Print-on-change to Cycle-based Translations" (www.sourceiii.com/notes-cyclize.html).

Bi-directional Data Control

VTRAN® creates two internal pins versions for each bi-directional signal. The input uses the defined name and is used to store the input data from the OVF. Output data is stored on the output version of the signal "signal.O". The input is assigned a Z state when the pin direction is determined to be output. Similarly, the output is assigned an X state when the pin direction is determined to be input. For some vector formats like Verilog VCD files, there is no distinction in the data itself for determining whether the state data on a bi-directional signal is input data or output data. It is therefore necessary to use a VTRAN® process like BIDIRECT_CONTROL to specify when states represent input data or output data, usually as a logical function of a control signal. An example of this would be:

BIDIRECT_CONTROL bi1, bi2, bi3, bi4 = INPUT when ctl = 0;

Here we specify that the state data on the bi-directional signals bi1, bi2, bi3, bi4 in the VCD file should be interpreted as input data when the control signal ctl is a logic 0. By default, this implies it is output state data if ctl is not 0. All bi-directional signals in the VCD file need to have their data directions specified in a manner similar to this. Multiple BIDIRECT_CONTROL statements can be used (up to one for each bi-directional pin if needed). BIDIRECT_STATES commands are also used to specify signal direction and are used when the OVF is a user format and the format uses different characters for input data than for output data.

If the OVF format contains information such that the VTRAN® reader can make a determination when data on a bidirectional pin represents an input state or an output state, BIDIRECT_CONTROL statements are not needed. WGL, STIL, and Verilog EVCD are examples of this type of format.

ADD_PIN

ADD_PIN provides a way to add pins to the TVF that did not exist in the OVF. This feature allows for a set of state value assignments where each assignment is based upon the evaluation of a compound logic expression. Once created, this pin can be manipulated like any other signal in the original vector file. See the Application Note titled "Using the ADD PIN Command" (www.sourceiii.com/notes-add_pins.html).

MASK_PINS

The MASK_PINS command can be used to modify the state defined for a signal in the Original Vector File (OVF). This command can be applied both to input and output signals, and to both the input and output data of a bidirectional signal. Any state can be used as a mask character. Pin states can be masked within each cycle, or in multiple vectors within a time range, or when specified masking conditions are met. MASK_PINS can be used to mask output signals for times in the cycle they are not in a stable state or for debugging a functional test program. MASK_PINS is applied before STATE_TRANS. For details on how to use command see the Application Note titled "Using the MASK_PINS Command" (www.sourceiii.com/notes-maskpins.html).

Inserting Statements into the Target Vector File

The intention of this feature is to allow arbitrary tester or simulation statements to be inserted into the target vector file. This can be used to insert macros or subroutine calls in a test pattern or a testbench. It can also be used to insert comments for documentation. See the Application Note titled "Adding Statements to Target Vector File" (www.sourceiii.com/notes-insertstmt.html).

Modifying Timing State Transitions

Extensive modifications to the timing of state transitions in POC vector files for the purpose of re-simulation using the same or another simulator can be made using the SCALE and EDGE_SHIFT commands.

proc_block



  begin



  state_trans inputs '0'->'D', '1'->'U', 'X'->'N';



  state_trans outputs '0'->'L', '1'->'H', 'Z'->'T';



  SCALE 0.90;



  EDGE_SHIFT CLOCK @ 2, -3;



  end

In this example, the entire time of the Original Vector File is contracted by 10%. Also the rising edge of the CLOCK signal is delayed by 2 ns and the falling edge of the CLOCK signal is moved forward by 3ns.

Other Commands

See the VTRAN® User's Guide Section 4.0 for information on all commands available for use in the PROC block.

The commands in the TVF block tell VTRAN® how to format the vectors in the Target Vector File and what if any reporting parameters are desired.

Selecting the Target Interface

Either (not both) the SIMULATOR or TESTER_FORMAT command is used to specify the simulator or tester interface. This is the only required command in the TVF block. Some examples are:

SIMULATOR WGL [params];



SIMULATOR STIL [params];



SIMULATOR VERILOG_TB [params];



TESTER_FORMAT AGILENT93K [params];



TESTER_FORMAT Teradyne [params];

For each format, there are a number of optional parameters [params] that allow the user to customize the output. These parameters vary with the selected target interface. For example, parameters for a VERILOG Test Bench include:

SIMULATOR verilog_tb,



  -VERBOSE,



  -INHIBIT_CHECKING,



  TESTBENCH_MODULE = "Top_of_generic",



  COMPONENT_MODULE = "Component_of_generic",



  INSTANCE_NAME = "Instance_of_generic",



  TIMESCALE = "1ns/100ps",



  OUTPUT_GROUP = "pin3, pin4, .. "



  PSEUDO_SIGNAL = "pinname",



  TERMINATE_RUN = "$finish",



  MAX_MISMATCHES = "nn"



  ;

A complete list of supported target interfaces and their parameter lists can be found in Appendix C & D of the VTRAN® User's Guide.

Reporting

The CREATE_STATISTICS command causes VTRAN® to accumulate and report statistics on the states and state transitions of any or all signals for some or all the vector space. This is especially useful, when generating test programs or test bench files, where it is important to know to what extent output signals are being checked. See the Application Note titled "Generating Device Test Program Statistics" (www.sourceiii.com/notes-create_statistics.html).

Other Commands

Commands in the TVF block can also be used to specify signal renaming, bus formatting, signal identity and order of appearance in the target vector file. See the VTRAN® User's Guide Section 5.0 for more details.

Putting it All Together

The construction of a VTRAN® command file using the OVF_BLOCK, PROC_BLOCK, and TVF_BLOCK described above, allows each VTRAN® translation process to be performed under tight user control. For example, the following VTRAN® command file causes a set of HP93000 test program files to be merged and translated into a Verilog Testbench file:

OVF_BLOCK



  begin



  tabular_format HP93000 ;



  merge_file



    orig_file "small1.agk";



    aux_file "small1.dvc";



  end_merge;



  merge_file



    orig_file "small2.agk";



    aux_file "small2.dvc";



  end_merge;



  merge_file



    orig_file "small3.agk";



    aux_file "small3.dvc";



  end_merge;



  end



  PROC_BLOCK



  begin



  state_trans outputs 'L'->'0', 'H'->'1', 'M'->'Z';



  end



  TVF_BLOCK



  begin



  SIMULATOR VERILOG_TB,



    TIMESCALE = "1ns/100ps";



  target_file "small2" ;



  end

Specific Translation Examples

Specific translation examples are available in the INTERFACES bundle (see the Getting VTRAN® Software sections of this document) and in the following list of application notes:

• Cycle-based to Testbench Translations
• Print-on-change to Testbench Translations
• Verifying VTRAN®-generated Test Programs
• Translating EDA Vector Files to SPICE
• Translating WGL/STIL Vector Files to Teradyne Tester Formats
• Translating WGL/STIL Vector Files to HP83000/93000 Tester Formats
• Translating WGL/STIL Vector Files to the Credence Tester Format
• Control Signal and Vector Insertion for Q-Star Test Modules

While these examples generally focus on specific formats, the strategies and processing illustrated can be applied to other translations.