FrontPanel Tutorial – Part 4 (archived)

Note: This tutorial is outdated and no longer maintained to be consistent with the latest FrontPanel SDK or Xilinx tools. Please review the FrontPanel User’s Manual for the latest information and use the current Samples (and their README) from your installation as guidance.

Part IV – ModelSim Behavioral Simulation of FrontPanel API

Approximate time to complete this part: 45 minutes

In this part of the tutorial, the PC/FPGA connectivity shown in Part III will be performed in simulation by the free ModelSim XE III (available from Xilinx). We are also assuming that the user is working with the Verilog sample of the DES Tester for XEM3001v2.

For simulation, the okLibrary.v or okLibrary.vhd files are not required. Instead, all FrontPanel HDL components are replaced by modules in the FrontPanel simulation libraries. These libraries make it possible to call functions from an HDL test fixture that mimic the operation of FrontPanel API calls.

The FrontPanel simulation libraries are currently distributed in Verilog and VHDL libraries. They were compiled under the free ModelSim XE III Starter 6.0a and typically be refreshed for usage under newer versions of ModelSim SE and PE.

Note: The DES core that is integral to this part of the tutorial was written by Rudolf Usselmann and provided to OpenCores.org. Please visit their website for an updated distribution if you’re interested in using that core.

Modelsim Project Setup

Once you have a version of ModelSim 6 installed on your machine, we need to make sure your main DES project directory is setup properly. The following files from DESTutorial.zip (Part4) are required:

• des.v
• destop.v
• key_sel.v
• crp.v
• sbox1.v
• sbox2.v
• sbox3.v
• sbox4.v
• sbox5.v
• sbox6.v
• sbox7.v
• sbox8.v
• \Simulation\des.do
• \Simulation\des_tf.v
• \Simulation\okHostCalls_v2.v

ModelSim INI

Next, ModelSim must find the FrontPanel simulation libraries. This can be done several ways, but only one will be described here.

Find the modelsim.ini file in your ModelSim installation directory. Edit the section near the top of the file that defines the library locations to add the FrontPanel Library links. It should now look a lot like the text below:

; VHDL Section
unisim = $MODEL_TECH/../xilinx/vhdl/unisim
simprim = $MODEL_TECH/../xilinx/vhdl/simprim
xilinxcorelib = $MODEL_TECH/../xilinx/vhdl/xilinxcorelib
aim = $MODEL_TECH/../xilinx/vhdl/aim
pls = $MODEL_TECH/../xilinx/vhdl/pls
cpld = $MODEL_TECH/../xilinx/vhdl/cpld
okFPsim_v2 = C:/Program Files/Opal Kelly/FrontPanel/FrontPanelHDL/ModelSimXE6_v2/okFPsim_v2

; Verilog Section
unisims_ver = $MODEL_TECH/../xilinx/verilog/unisims_ver
uni9000_ver = $MODEL_TECH/../xilinx/verilog/uni9000_ver
simprims_ver = $MODEL_TECH/../xilinx/verilog/simprims_ver
xilinxcorelib_ver = $MODEL_TECH/../xilinx/verilog/xilinxcorelib_ver
aim_ver = $MODEL_TECH/../xilinx/verilog/aim_ver
cpld_ver = $MODEL_TECH/../xilinx/verilog/cpld_ver
okFPsim_v2_ver = C:/Program Files/Opal Kelly/FrontPanel/FrontPanelHDL/ModelSimXE6_v2/okFPsim_v2_ver

For many projects, you will need to have the Unisim and Xilinx Corelib libraries linked as well. These and a few others should already be setup for ModelSim XE III.

You are now ready to launch ModelSim. Upon doing so, you should see the available libraries listed in the Workspace. Hopefully, okFPsim_v2 and okFPsim_v2_ver are present with a valid Path

Simulation Test Fixture: Setup and Variables

Now that ModelSim is up and running, let’s spend a moment to look at the files provided for this tutorial.

The files in the root project directory are exactly the same files used in the previous tutorials (Verilog version). However, we are no longer going to use okLibrary.v. Instead, we will use a Verilog test fixture, des_tf.v, and the FrontPanel simulation library.

The test fixture links to the top level of the root project, destop.v. Through Verilog function and task calls within des_tf.v, pseduo FrontPanel API calls can be simulated through the okHostInterface connection.

Within the test fixture, there are the configuration integers, arrays, and function calls necessary to support the simulation. Let’s look at the configuration variables below.

integer k, e;
 
parameter pipeInWaitStates = 0;   // (REQ) # of clocks between pipeIns; Integer 0-255
parameter pipeOutWaitStates = 0;  // (REQ) # of clocks between pipeOuts; Integer 0-255
 
parameter pipeInSize = 16;        // In bytes (must be even); Integer 0-2^32
parameter pipeOutSize = 16;       // In bytes (must be even); Integer 0-2^32
 
// We will be piping in 8 random words for DES encrypting
reg   [7:0]   pipeIn [0:(pipeInSize-1)];
initial for (k=0; k<pipeInSize; k=k+1) pipeIn[k] = $random;
 
reg   [7:0]   pipeOut [0:(pipeOutSize-1)];
initial for (k=0; k<pipeOutSize; k=k+1) pipeOut[k] = 8'h00;
 
// DES keys; set to whatever the user wishes
reg   [15:0]  key [0:3];
initial begin
   key[0] = 16'hABCD;
   key[1] = 16'h3234;
   key[2] = 16'h3456;
   key[3] = 16'h4567;
end
 
// Storage array for initial pipeIn data
reg   [7:0]   pipetmp [0:(pipeInSize-1)];

1. The integers at the top are used for loop counting.
2. The second group contains variables necessary for pipe operations. The pipe wait states, if set to a non-zero value, will place delays between transfers during pipe streaming. This allows the programmer to test the robustness of their HDL because there may be lags of data in the actual FrontPanel pipe operation.
3. The last two parameters sets the length for the pipeIn and pipeOut arrays. Pipe arrays will be discussed in greater detail in the last section of this tutorial.
4. The rest of the code creates arrays of data and storage for more data.

Simulation Test Fixture: Task and Function Calls

Next, let’s look at some of the Verilog function and task calls that will simulate FrontPanel API calls.

// User configurable block of called FrontPanel operations.
initial begin
Reset;    // Start routine with Reset;
 
// Assert then deassert RESET
SetWireIns(8'h30, 16'hffff, 16'h0001);
UpdateWireIns;
SetWireIns(8'h30, 16'h0000, 16'h0001);
UpdateWireIns;
 
// Set the DES key value (WireIns)
for (k=0; k<4; k=k+1)
   SetWireIns((8'h0b - k), key[k], 16'hffff);
 
// Set the encrypt bit
SetWireIns(8'h30, 16'h0000, 16'h0010);
UpdateWireIns;

1. The first command must be Reset for correct operation. The Reset Verilog task clears essential internal variables and sends a reset signal to the FrontPanel HDL modules.
2. The rest of the code should look amazingly similar to the C++ API calls in the previous tutorial.

After the remaining bulk of the simulation test fixture code, there is one more essential line of code:

`include "okHostCalls_v2.v"  // Do not remove!  The tasks, functions, and data stored
                             // in okHostCalls.v must be included here.

All of the Verilog task and function routines are actually stored inokHostCalls_v2.v. ModelSim, when compiling des_tf.v, appends the code stored in okHostCalls_v2.v to this point. We seperated these functions to another file to simplify the look and function of des_tf.v.

• VHDL does not support this type of file insertion so all Host Calls in VHDL simulation are located within the test fixture.

Compilation and Simulation with ”des.do”

After starting ModelSim and making sure the okFPsim_v2_ver library is properly installed, it’s time to redirect the working directory.

Click File > Change Directory… and navigate to the simulation directory that was setup in the first section of this tutorial. You should now be in the directory that contains des.do, des_tf.v, and okHostCalls_v2.v.

Before running des.do, lets look at the some of the code it contains.

# Source files and testfixture
vlib work
vlog des_tf.v
vlog ../destop.v
vlog ../crp.v
vlog ../des.v
vlog ../key_sel.v
vlog ../sbox1.v
vlog ../sbox2.v
vlog ../sbox3.v
vlog ../sbox4.v
vlog ../sbox5.v
vlog ../sbox6.v
vlog ../sbox7.v
vlog ../sbox8.v
vsim -L okFPsim_v2_ver -L unisims_ver -t ps DES_TEST okFPsim_v2_ver.glbl

1. The first line creates the work library for the project fourteen lines and the next 13 lines compile all of the files into it.
2. The last line links necessary libraries and initiates the simulation.
3. -L okFPsim_v2_ver links the FrontPanel Verilog library.
4. -L unisims_ver links the Xilinx Unisims Verilog library.
5. -t ps sets the simulation resolution.
6. DES_TEST sets DES_TEST as one of the top level modules.
7. okFPsim_v2_ver.glbl sets okFPsim_v2_ver.glbl as a second top level module. This is required to simulate certain Xilinx primitives. glbl.v is provided by Xilinx and was compiled and included into FrontPanel’s Verilog Simulation Libraries for convenience. For many projects, this file may be excluded. Likewise, a different version of glbl.v may be compiled and linked in your local project.

Now it’s time to actually run the simulation. Click anywhere in the Transcript window and type do des.doand hit Enter.

The files should compile, the full simulation will run, the transcript window will be updated with output calls from des_tf.v indicating success or failure, and a waveform window should appear that looks something like this:

Miscellaneous Pointers

• Verilog tasks (and VHDL procedures) cannot pass or receive arrays. Therefore, the tasks defined in okHostCalls_v2.v for pipe operations are already associated with a pipe array. If you need to use multiple arrays of data and you don’t want to transfer data around to the default pipeIn (or pipeOutarrays), you can edit okHostCalls_v2.v to add more unique tasks.

For example, if we had wanted the pipetmp.v array to have it’s own specific task, we could have added the following code to okHostCalls_v2.v:

//---------------------------------------------------------
// WriteToPipeTmp
//---------------------------------------------------------
task WriteToPipeTmp (
    input [7:0]        ep,
   input integer      length
);
   integer            len, i, j;
begin
   len = length/2;
   if (length%2)
      $display("Error. Pipes may only send and receive an even # of bytes.");
   @(posedge hi_clk) hi_rdwr = 1;
   hi_addr = `DWriteToPipeIn;
   hi_dataout = {pipeInWaitStates, ep};
   @(posedge hi_clk) hi_addr = `DNOP;
   hi_dataout = len;
   @(posedge hi_clk) hi_dataout = (len >> 16);
   for (i=0; i %lt length; i=i+2) begin
      @(posedge hi_clk);
      hi_dataout[7:0] = pipetmp[i];
      hi_dataout[15:8] = pipetmp[i+1];
      for (j=0; j %lt pipeInWaitStates; j=j+1)
         @(posedge hi_clk);
   end
   wait (hi_busy == 0);
end
endtask

• You do not have to edit your main modelsim.ini. Instead, you can place copies of modelsim.ini in your project Simulation directory and only edit this local modelsim.ini file. When you change directories within ModelSim, it automatically load any local modelsim.ini if present. This will allow for project specific modelsim.ini configuration.
  • This may not work in newer versions of ModelSim

• If you are making changes in your waveform windows between simulations, select the Save icon within the waveform window and save the waveform configuration file as wave.do. Then, alter your main dofile to include the line do wave.do after the simulation instatiation. Now, you can independantly save updated waveform configurations, but still quickly re-compile and re-simulate the whole project by re-running the main <strong>do</strong> file in the Transcript window.

• A modified des.do that operates like this:

vlib work
...
vlog ../sbox8.v
vsim -L okFPsim_v2_ver -L unisims_ver -t ps DES_TEST okFPsim_v2_ver.glbl

do wave.do

run 200us

Now, if any Verilog files are updated or the waveform window is modified (and saved again as wave.do), a quick call of do des.do recompiles and resimulates the whole project.

• If you have any tips or tricks to facilitate simulation under ModelSim with Opal Kelly Simulation Libraries, please share them in the forum!