# Isolation Verification Tool 7.43 Lab John D. Corbett December 22, 2014 The Xilinx Isolation Verification Tool software (IVT) checks designs intended for single chip crypto solutions. The partial reconfiguration flow is used to partition the placement and routing of designs into logically isolated regions called isolation groups. An isolation group is a portion of a design that is separated from other portions of the design and can only communicate with other isolation groups through specially isolated routing. The separation is designed to hold up even if an adversary could introduce a limited number of changes (faults) into the design. The IVT software is used during two phases of the design process: first, in the UCF phase, when pin locations, isolation groups, and basic floorplanning are under development; and again, in the NCD phase, when placed and routed design files are being generated. IVT can be run in three ways. IVT can analyze a UCF, it can analyze a set of NCDs, or for debugging, it can be run to analyze a user supplied path. This lab covers the first two.
#### Commmand line arguments for UCF checking In UCF phase, IVT checks area groups and pin locations according to the User Constraint File (UCF) and the Pin Isolation Group (PIG) file. The PIG file specifies isolation groups for pins. Since the UCF file may not necessarily specify the target device or package, they must be specified on the command line. The association between isolation groups and area groups is also specified on the command line. More than one area group may belong to a single isolation group. IVT Inputs and Outputs at the UCF Phase The arguments appear below, with optional arguments in [brackets]:
`-device <device>` | E.g. xc4vlx60
`-package <package>` | E.g. ff1152
`-group <isolation_group> <area_group>` | At least two distinct isolation groups are required.
`[-spacing <clbs>]` | Ranges from 1 to 10, defaults to 1 CLB.
`[-pig <pin_isolation_groups>]` | If omitted, no pin-related analysis performed.
`[-output <output>]` | The output is a text file. It is recommended that the name include "ucf" in it somewhere, e.g. `my_crypto_design_ucf.rpt`.
`[-verbose]` |
`[-f <parameter_file>]` | Arguments can be stored and documented in a file.
`<user_constraint_file>` | E.g. my_crypto_design.ucf
#### Command line arguments for NCD checking In the NCD phase, IVT checks pin locations as before. However, IVT does not check area groups; instead, it checks the actual routing. The inputs to IVT in this phase are simpler. The inputs are a combined NCD file with the complete routing and Partial Reconfiguration Modules (PRMs) for each isolation group. Note that more than one NCD file may belong to a single isolation group. IVT obtains the device, package, and networks of isolated designs directly from the NCD files. IVT Inputs and Outputs at the NCD Phase If information could potentially leak from one isolated region to another by the introduction of fewer than the given number of faults, IVT will report a faulty path. In this context the faulty path refers not to an actual defect present in a design, but rather a defect that might be introduced with a limited number of changes or failures that might occur by accident or by tampering. Only the defects that could conceivably result in information leaking from one isolation group to another are of interest here. IVT reports a signal as shared if it appears in more than one NCD file. This behavior is a consequence of the fact that every PRM NCD file contains all shared signals in addition to information about the partial reconfiguration module. Therefore, user analysis is required to verify that each and every shared signal falls into one of the permitted categories: power, clocks, global resets, and bus macros. The arguments appear below:
`-group <isolation_group> <nets>` | The nets parameter may be specified as the name of a block or as an NCD file. At least two -group parameters are required.
`[-faults <faults>]` | Ranges from 2 to 10, defaults to 2.
`[-output <output>]` | The output is a text file. It is recommended that the name include "ncd" in it somewhere, e.g. `my_crypto_design_ncd.rpt`.
`[-nopin]` | Suppresses pin-related checks.
`[-verbose]` |
`[-f <parameter_file>]` | Arguments can be stored and documented in a file.
`<combined>` | The complete placed and routed NCD file
# Installing IVT The IVT executable requires Xilinx . The directory containing the Xilinx executables and dynamic link libraries must be listed in the `PATH` environment variable for IVT to find them. The quickest way to arrange this is to simply save `ivt.exe` into the directory where the ISE executables are located. Note: To save a link to a local file, right click on the link and select "Save Target As..." or "Save Link As..." from the menu. Note: You must save the file using the exact same name as listed here. If you are using Microsoft Internet Explorer as your web browser, you will need to change the type of the file to "All Files" in the drop down menu at the bottom of the Save As dialog, otherwise, the file will have `.txt` appended to the name. The default installation directory Xilinx ISE is:
    C:\Xilinx\nt\bin\
- If dropping `ivt.exe` in with the ISE executables presents difficulties, then you can put ivt.exe in any directory you like, provided you add that directory to the `PATH` environment variable. Save `ivt.exe` (right click, "Save Target As..." or "Save Link As...") to `bin\nt` directory in the ISE installation directory. IVT is now installed. Open a Command Prompt window (click start, "Run...", type `cmd`, press <Enter>) Verify that IVT runs by typing `ivt` and pressing <Enter>. If several lines of usage information are displayed, the installation was successful. #### Troubleshooting Installation Problems The `ivt` executable requires dynamic link libraries from a specific version the Xilinx ISE software. If the operating system cannot locate the libraries or cannot locate the correct versions of the libraries, the following errors will occur. The message,
      The procedure entry point nnn could not be located in the
      dynamic link library mmm.dll.
- indicates the required version of ISE is missing from your `PATH` environment variable. The command `echo %PATH%` is a quick way to examine the path. The message,
      This application has failed to start because libPds_Exception.dll
      was not found. Re-installing the application may fix this problem.
3. indicates ISE is either not installed or the `PATH` environment variable does not include the `nt\bin` directory in the ISE installation. # Lab 1: Running IVT on a Passing UCF Design In this lab, you will run IVT on a UCF design that has no isolation violations and you will make some trivial modifications to the input parameters. Since the command line arguments for IVT are somewhat long, especially for checking UCFs, it is recommended that you create a file containing the arguments and supply the file to IVT rather than typing them directly on the command line. Arguments can be spread across multiple lines, blank lines and lines beginning with `#` are ignored (comments). #### Input Files Three input files for this lab have been prepared in advance: `smt_ucf.ivt` - an IVT parameter file, `smt.ucf` - a User Constraint File, and `smt.pig` - a Pin Isolation Group file. #### Procedure Create a folder for this lab and save the three files above to it. Open a Command Prompt window and `cd` to the folder you just created. Run `ivt` as follows:
       ivt -f smt_ucf.ivt
   A file called `smt_ivt_ucf.rpt` will be created. Examine the report file. Near the end of report the following should appear:
         UCF file contains 0 constraint violations.

         Isolation analysis completed.

         Elapsed time: 0:00:22
8. Copy `smt_ucf.ivt` to `smt_ucf_v.ivt`. Open `smt_ucf_v.ivt` in a text editor. Uncomment the `-verbose` switch. Change the name of the output file to `smt_ivt_ucf_v.rpt` Run `ivt` with the new command file:
       ivt -f smt_ivt_ucf_v.ivt
3. Examine the new output report `smt_ivt_ucf_v.rpt`. Always look for "Isolation analysis completed." If this sentence is missing, then IVT encountered an internal error. # Lab 2: Running IVT on a Faulty UCF Design In this lab, you will run IVT on a UCF design that has several isolation-related faults due to incorrect area group ranges and incorrect pin assignments. #### Input Files As in Lab 1, the input files have been prepared in advance: smt_ucf_bad.ivt - an IVT parameter file, smt_bad.pig - a pin isolation group file with errors, and smt_bad.ucf - a UCF file with errors. #### Procedure Create a folder for this lab and save the three files above to it. Open a Command Prompt window and `cd` to the folder you just created. Run `ivt` as follows:
       ivt -f smt_ucf_bad.ivt
A file called `smt_ivt_ucf_bad.rpt` will be created. Examine the report file. IVT should report three types of errors and should report, "Isolation analysis completed". #### Notes The package pin grid for the Virtex-4 series is documented in the Virtex-4 Packaging and Pinout Specification. See www.xilinx.com for the latest edition. The pinout of the FF1517 (FX140) is on page 314. Bank information is on page 315. The relationship between package pins and I/O buffers can be ascertained from the Xilinx PARTgen program. The command below was used to generate the report `xc4vfx140ff1517.pkg`.
    partgen -arch virtex4 -p xc4vfx140
9. # Lab 3: Running a Passing NCD Design In this lab, you will run IVT on a simple NCD design that has no isolation violations. Since the input command line for this design is easier than in the previous labs, you will create it from scratch. #### Input Files Three input files for this lab have been prepared in advance. Note: the input files for this lab and the next lab are not human readable, as you will see if you click the links below instead of saving them locally. hsimple.ncd - the combined design file for a simple design, hblack.ncd - the Black module of the design, and hred.ncd - the Red module of the design. #### Procedure Create a folder for this lab and save the three files above to it. Create an IVT argument file for this design called `hsimple_ncd.ivt`. Notice in the command line argument descriptions above that the `-device` and `-package` switches are not included for NCD files. This information is read from the combined NCD file. Notice also that the `-group` switch has a different second parameter than in the UCF phase. The second parameter in this case is an NCD file that specifies 'ingredients' of an isolation group. Add a `-group` switch to your argument file for the Black partial reconfiguration module `hblack.ncd`. Add another `-group` switch for the Red partial reconfiguration module `hred.ncd`. Add the `-output` switch and specify `hsimple_ivt_ncd.rpt` for the name of the report file. Open a Command Prompt window and `cd` to the folder you created above. Run `ivt` as follows:
       ivt -f hsimple_ncd.ivt
6. A file called `hsimple_ivt_ncd.rpt` will be created. Examine the report file. It should list no error and contain the test, "Isolation analysis completed" near the end. #### Troubleshooting the Input Arguments Since IVT takes such a variety of input parameters, it is sometimes difficult to see what is wrong with an IVT command line. If you are experiencing errors attempting to get IVT to run, a working version of parameters for this lab may help you figure out what the problem is. If you copied one of the command files from the previous labs, be sure to remove the `-device`, `-package`, and `-pig` switches. Also note that the `-group` switch requires a label and a file name and that the final argument will be an NCD file, not a UCF file. # Lab 4: Running a Faulty NCD Design In this lab, you will run IVT on a NCD design based on the one from the previous lab. This design, however, has had artificial routing faults injected into it. #### Input Files The input files have been prepared in advance: hsimple_ivt_ncd.ivt - an IVT parameter file, hsimpleh_n2_0-2.ncd - the combined design file for a simple design with a fault injected into it, hblack.ncd - the Black module of the design, and hred.ncd - the Red module of the design. #### Procedure Create a folder and save all the input files. Notice that the command argument file `hsimple_ivt_ncd.ivt` has a new option `-faults 2`. This tells IVT that a fault should be reported if it is possible to create a route between isolated regions in fewer than two faults. Recall that for some routing resources, more than one fault is required to use it; there is not a one-to-one correspondence between segments in a route and faults. Run IVT using the command file. Examine the output report `hsimple_ivt_ncd.rpt`. There will be two FPGA Editor scripts in the output. You will also notice messages about networks that are not fully routed. This is an artifact of the method used for fault injection. The appearance of this warning in a production design would indicate that the design is not finished. Careful examination of prior ISE reports is indicated. Copy the first FPGA Editor script into a file called `fault1.scr`. Open the combined design `hsimpleh_n2_0-2.ncd` in FPGA Editor. FPGA Editor can be run independently from ISE. To run FPGA Editor from the command prompt, type
       fpga_editor
If you prefer, can select FPGA Editor from the Start menu (start > All Programs > Xilinx ISE 14.7 > Accessories > FPGA Editor), Once FPGA Editor has finished loading, open `hsimpleh_n2_0-2.ncd` (File > Open Design > Browse > select `hsimpleh_n2_0-2.ncd` > Open > Open.) Once the design has finished opening, load the FPGA Editor script you saved previously (Tools > scripts > playback > Browse > Open > `fault1.scr` > OK). When FPGA Editor has finished running the script, the display will look like the image below. The potential fault is temporarily selected in red. The source net is highlighted in yellow and the load net is highlighted in blue. Recall that the highlighted error does not actually appear in the user's design, however it might be possible to construct it in fewer than 2 faults. FPGA Editor showing a potential fault selected in red #### Notes If you have time, here are a few ideas for further exploration. Changing the `-faults` parameter and observe the effect on the IVT output. Rather than loading the FPGA Editor script all at once, paste one line at a time into the command area at the bottom of the FPGA Editor main window. This will give you a chance to explore the individual wires and arcs (programmable connection between wires) comprising the route. Swap or omit input files and observe the errors IVT generates. Introduce mistakes into the designs from previous labs and observe the results. # Summary In these four labs, you learned how to install IVT, how to run it, what passing output looks like, and what failing output looks like. Thank you. © Copyright 2006--2014 ilinx, Inc. All Rights Reserved.